Skip to content

chore(sdk/ts): migrate the TypeScript SDK to ai-openshell/sdk-typescript #5480

Open

Description

@pimlock

User Story

As a maintainer of the TypeScript SDK, I want to move it out of core into ai-openshell/sdk-typescript the way the Go SDK (#5031) and the Python SDK (#5287) moved, so that it gets its own CI, reviews and releases.

Problem Statement

RFC 0019 (#4426) moves the SDKs out of core first. The TypeScript SDK lives in one core directory, sdk/typescript/, but core also owns its tooling:

  • tasks/typescript.toml (sdk:ts:* tasks) and the Windows wrappers tasks/scripts/typescript-{install,proto}.ps1;
  • the TypeScript SDK job in branch-checks.yml, which runs sdk:ts:ci and an npm publish --dry-run;
  • sdk-typescript-publish.yml, called by release-publish.yml for every stable release, which publishes @nvidia/openshell-sdk to GitHub Packages;
  • the e2e:sdk:ts:exec task;
  • proto:lint, which runs buf from the SDK's node_modules;
  • ci:check, ci:format, ci:lint and test, which include the sdk:ts:* tasks;
  • CodeQL paths, license-header exclusions, and docs/sdk/typescript.mdx.

Impact / Why This Matters

  • SDK maintainers own CI, reviews and releases without core review bandwidth, which is the goal of RFC 0019.
  • Users have to change the package name once, from @nvidia/openshell-sdk to @ai-openshell/sdk. GitHub Packages ties an npm scope to the account that owns it, so a workflow in ai-openshell can't publish @nvidia/openshell-sdk. Known consumers include NVIDIA/NemoClaw. The entry points (. and ./raw) and the API stay the same.
  • Core stops building and publishing the package, and core proto PRs no longer have to update the SDK in the same PR.

Proposed Design

Follow the Python SDK's phases (#5287), adapted to TypeScript:

  1. Prerequisites.
    • Decide the package name and registry (decided: @ai-openshell/sdk, see below), and announce the rename to known consumers.
    • Freeze at v0.1.8. Core main has no sdk/typescript changes after that tag.
    • Allow merge commits for the import.
  2. Import.
    • Extract sdk/typescript/ with history using git filter-repo --subdirectory-filter, as for the Go SDK, and rewrite #N references to NVIDIA/OpenShell#N.
    • A second PR makes the package build on its own: protos fetched from core at the pinned tag (OPENSHELL_CORE_REF), the generated bindings committed with a staleness check, the new package name, standalone CI on the supported Node versions, and the repository template applied.
  3. Cutover in core.
  4. Automation in sdk-typescript. As in sdk-python: bump PRs for each core release, E2E against that release's gateway (the interactive-exec test moves with the SDK), release tagging and a nightly drift check.
  5. Retire in core.
    • Replace sdk/typescript/ with a stub @nvidia/openshell-sdk that contains no SDK code: it depends on @ai-openshell/sdk and re-exports . and ./raw from it, and its README says the package moved, with migration steps. The freeze check allows the stub's files. Core's SDK sources, tasks/typescript.toml, the PowerShell wrappers, and the CodeQL and license-header entries go in the same change. docs/sdk/typescript.mdx, AGENTS.md, CONTRIBUTING, TESTING, and the skills point at @ai-openshell/sdk. This lands in feat(sdk): replace the TypeScript SDK in core with an @ai-openshell/sdk stub #5685.
    • The v0.1.10 release publishes the stub from core. sdk-typescript-publish.yml stamps the dependency to the release's minor line (^0.1.0) and fails if npmjs.org has no matching @ai-openshell/sdk, so a stub npm can't install is never published. To avoid that failure, publish @ai-openshell/sdk@0.1.9 before the v0.1.10 core release; otherwise rerun the publish with workflow_dispatch after the SDK release. Users on ^0.1.x who upgrade get the new SDK without code changes. Installs still resolve because .npmrc setups map only the @nvidia scope to GitHub Packages. Earlier versions stay published so existing lockfiles keep working.
    • Mark the old versions deprecated with a pointer to @ai-openshell/sdk if GitHub Packages accepts npm deprecate (unconfirmed; test on one version first).
    • Announce the move in the v0.1.10 release notes, and tell NemoClaw directly.
    • After @nvidia/openshell-sdk@0.1.10 is published, remove the stub (as chore(sdk/go)!: remove the Go SDK, now at github.com/ai-openshell/sdk-go #5461 did for Go): delete sdk/typescript/ and sdk-typescript-publish.yml, remove publish-sdk-typescript from release-publish.yml and its publisher gate, and remove the TypeScript SDK Freeze job. Later core releases publish no @nvidia/openshell-sdk. The 0.1.10 stub keeps resolving to the newest @ai-openshell/sdk 0.1.x, and 0.2.0 requires the rename.
  6. Release.
    • Make ai-openshell/sdk-typescript public (drop visibility = "private" in ai-openshell/infra github/repositories.tf). npm doesn't generate provenance for private repositories, so this has to happen before the first publish.
    • Configure the npm trusted publisher for @ai-openshell/sdk (repository ai-openshell/sdk-typescript, workflow release.yml, environment npm) within 48 hours of the first release, or it lapses: ci: set up the npm trusted publisher on 2026-11-23 for the first release sdk-typescript#5. The name is reserved by the placeholder 0.0.0-placeholder.0.
    • Publish the first release from sdk-typescript as @ai-openshell/sdk to npmjs.org.

Progress:

Decisions:

  • Package name: @ai-openshell/sdk, kept for good. It reads like other JavaScript SDKs (@anthropic-ai/sdk, @modelcontextprotocol/sdk), and npm only hosts JavaScript, so it doesn't clash with the Python or Go SDKs.
  • Registry: npmjs.org from the first release, with trusted publishing (OIDC) from release.yml in the npm environment, so no token is stored. Installing needs no .npmrc or token. This replaces the earlier plan to start on GitHub Packages, now that we have access to the ai-openshell npm org.

Acceptance Criteria

  • ai-openshell/sdk-typescript builds, tests and packages the SDK without a core checkout.
  • The first release from sdk-typescript has the same exports as the last core-built @nvidia/openshell-sdk, as @ai-openshell/sdk.
  • Core CI and releases no longer build, test or publish the SDK, and core proto PRs no longer touch sdk/typescript/.
  • The package is published only from sdk-typescript.
  • The last @nvidia/openshell-sdk (0.1.10) re-exports @ai-openshell/sdk, and its README points at the new package.
  • Core no longer contains sdk/typescript/ or sdk-typescript-publish.yml.
  • No open TypeScript SDK issues remain in core, and core's issue templates send new reports to sdk-typescript.

Alternatives Considered

  • Keep publishing @nvidia/openshell-sdk from core after the move. Core would still build a package it no longer owns, which is what the move removes.
  • Generate the bindings at build time (as core does today). Builds would then need core's protos, so installing from a git ref and rebuilding a release would need network access to core. Go and Python commit their bindings.
  • Keep the SDK in core and delegate through CODEOWNERS. RFC 0019 already weighs this option.

Agent Investigation

An agent mapped the SDK's footprint in core and rehearsed the history extraction locally: 38 commits from 20 authors, with a tip tree (c5a55ea8) identical to sdk/typescript at v0.1.8. One imported commit (#2884) lacks Signed-off-by, so the import PR needs a DCO override.

Activity

  1. self-assigned this
    on Nov 11, 2026
  2. added
    retired:area:sdkRetired; do not apply. See #5151 for item-specific migration to the current taxonomy.
    retired:area:sdk:typescriptRetired; do not apply. See #5151 for item-specific migration to the current taxonomy.
    on Nov 11, 2026
  3. added
    area:buildCI/CD workflows, releases, build targets, packaging, and artifact publication.
    topic:dxMaking OpenShell easy to contribute to for humans and agents.
    topic:sdk:typescriptTypeScript SDK implementation, maintenance, interfaces, and distribution.
    and removed
    retired:area:sdkRetired; do not apply. See #5151 for item-specific migration to the current taxonomy.
    retired:area:sdk:typescriptRetired; do not apply. See #5151 for item-specific migration to the current taxonomy.
    on Nov 15, 2026
  4. pimlock commented on Nov 20, 2026

    @pimlock
    ContributorAuthor

    Status

    This comment is kept up to date. Last updated 2026-11-19.

    ai-openshell/sdk-typescript is public and builds, tests and packages the SDK on its own as @ai-openshell/sdk, pinned to core v0.1.9. Core sync, the E2E lane and the npm release workflow are merged. Nothing is published yet: the name is reserved on npmjs.org by 0.0.0-placeholder.0, and the first release is planned with core v0.1.10 (2026-11-24), after the npm trusted publisher is set up on 2026-11-23. The core freeze and the @nvidia/openshell-sdk stub are in draft #5685.

    Merged

    Open PRs

    PR What State
    #5685 Freeze sdk/typescript/ in core, replace it with the @nvidia/openshell-sdk re-export stub, move proto:lint to core's Buf (closes #5684) Draft. Waiting for /ok to test.
    ai-openshell/sdk-typescript#7 Switch to the shared core-sync scripts and workflows (ai-openshell/workflows#3) Draft, together with ai-openshell/sdk-python#53.

    Phases

    Tracked in sdk-typescript

    Issue What Owner State
    ai-openshell/sdk-typescript#3 GitHub App and sdk-bot secrets for core sync @SDAChess ✅ Closed
    ai-openshell/sdk-typescript#5 Set up the npm trusted publisher on 2026-11-23 for the first release @pimlock Open

    Decisions

    • Package name: @ai-openshell/sdk, kept for good. GitHub Packages ties the @nvidia scope to the NVIDIA org, so ai-openshell can't publish @nvidia/openshell-sdk.
    • Registry: npmjs.org from the first release, with trusted publishing (OIDC) from release.yml in the npm environment. No token is stored, and installing needs no .npmrc. The name is reserved by 0.0.0-placeholder.0 (dist-tag placeholder). The trusted publisher must be used within 48 hours of being set up, so it's configured the day before the first release.
    • History: imported with git filter-repo --subdirectory-filter sdk/typescript, as for sdk-go. The extraction scripts are on the branch migration/v0.1.8. One commit (fix(sandbox): complete successful main processes #2884) lacks Signed-off-by and needed a DCO override.
    • Bindings: generated with protoc-gen-es from core's protos at the pinned tag (OPENSHELL_CORE_REF) and committed, with a staleness check. Go and Python commit theirs too.
    • Old package: core publishes one last @nvidia/openshell-sdk (0.1.10) as a stub that re-exports @ai-openshell/sdk (^0.1.0), then stops. Earlier versions stay published so lockfiles keep working.
    • Release cadence and sync: as in sdk-python. A bump PR for each stable core tag and for the newest pre-release, releases from the stable bump PR, and a nightly drift check of core main. No dev releases; to try unreleased changes, install from the repository.
    • Freeze in core: sdk/typescript/, except the stub's files. Deletions are allowed.

    Next

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Labels

area:buildCI/CD workflows, releases, build targets, packaging, and artifact publication.topic:dxMaking OpenShell easy to contribute to for humans and agents.topic:sdk:typescriptTypeScript SDK implementation, maintenance, interfaces, and distribution.

Type

No type

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions