ci: propose bindings updates for new core releases and track drift against core main #5

Part of the automation phase of NVIDIA/OpenShell#5287. It depends on #2 and #3 being on main.

Problem

The generated bindings in src/openshell/_proto are pinned to a core release through OPENSHELL_CORE_REF in mise.toml, which is v0.1.7 today. Nothing tells us when core publishes a new release, and nothing warns us about proto changes on core main that the next release will bring.

Proposal

Port the sdk-go automation (hack/automation/ and its workflows) and keep it as close to sdk-go as possible, so that a fix in one repository applies to the other. Here the scripts go in scripts/core-sync/, next to the E2E gateway scripts in scripts/e2e/ (#12); #11 tracks one layout for all SDK repositories.

What gets synced, and when:

• Core release tags. core-watch.yml runs hourly. It lists the core tags newer than the pin and opens one PR per tag on branch core/<tag>, titled chore(core): track <tag>. The PR moves the pin, regenerates the bindings, refreshes the vendored conformance fixtures, and puts the proto diff in its body. It covers every new stable tag, plus the newest pre-release when that is newer than all of them. A newer pre-release proposal closes the older one.
• Core main. core-drift.yml runs nightly. It doesn't open PRs. It runs buf breaking between the pin and main for the protos we generate, regenerates the bindings from main, and runs the unit tests. It also lists RPCs that no curated API covers, for information only. The results go into a single Core main drift issue, which the workflow creates, updates, or closes.
• A failed run appends a dated line to the drift issue (report-failure.sh).

Each workflow wraps a script behind a mise task (core:tags, core:bump, core:drift), so it can be run locally. Every script that writes to GitHub takes --dry-run.

Python-specific changes from sdk-go:

• The pin lives in OPENSHELL_CORE_REF in mise.toml, not in buf.gen.yaml.
• Regeneration runs mise run proto:gen. CI's proto:check and conformance:check then guard the result.
• The bump PR has the same structure as sdk-go's, with Python commands in the body.

Bot identity

The workflows must use a GitHub App token, not GITHUB_TOKEN. Pushes and PRs made with GITHUB_TOKEN don't trigger workflows, so bump PRs would get no CI.

Admin request, as in ai-openshell/sdk-go#2:

• An App installed on sdk-python: either a dedicated ai-openshell-sdk-python App, or the existing ai-openshell-sdk-go App with sdk-python added. Permissions: contents: write, pull_requests: write, issues: write, metadata: read, and no webhook.
• An sdk-bot environment that only main can deploy to, holding SDK_BOT_CLIENT_ID and SDK_BOT_PRIVATE_KEY.
• Bot commits carry Signed-off-by, so DCO passes.

Out of scope

These are tracked separately:

• E2E against the gateway of the proposed core version. The bump PR will call the reusable e2e.yml once it exists.
• Release tagging and PyPI publishing (sdk-go's release-tag.yml).

Alternative: Dependabot

Dependabot could open PRs when core changes, for example with core added as a git submodule and the gitsubmodule ecosystem enabled. This needs an evaluation before we commit to it:

• A submodule tracks a branch tip, not release tags.
• A Dependabot PR only moves the pointer. It can't regenerate the bindings or refresh the fixtures, and workflows on Dependabot PRs get a read-only token and no secrets. Pushing the generated code would need a second workflow.
• sdk-go would have to switch too.

For now we follow sdk-go. If we switch to Dependabot later, we change both repositories together.

Acceptance criteria

• core-watch.yml and core-drift.yml, the scripts under scripts/core-sync/, and a README with the script and workflow tables are on main.
• A dry run of mise run core:bump -- <tag> works locally.
• The App and the sdk-bot environment are configured.
• With them in place, core-watch opens a bump PR for the current core pre-release (v0.1.8-pre.3 or newer), and CI runs on it.
• core-drift creates the Core main drift issue.