Repository navigation
Open
Labels
area:buildCI/CD workflows, releases, build targets, packaging, and artifact publication.CI/CD workflows, releases, build targets, packaging, and artifact publication.topic:dxMaking OpenShell easy to contribute to for humans and agents.Making OpenShell easy to contribute to for humans and agents.topic:sdk:typescriptTypeScript SDK implementation, maintenance, interfaces, and distribution.TypeScript SDK implementation, maintenance, interfaces, and distribution.
Description
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 wrapperstasks/scripts/typescript-{install,proto}.ps1;- the
TypeScript SDKjob inbranch-checks.yml, which runssdk:ts:ciand annpm publish --dry-run; sdk-typescript-publish.yml, called byrelease-publish.ymlfor every stable release, which publishes@nvidia/openshell-sdkto GitHub Packages;- the
e2e:sdk:ts:exectask; proto:lint, which runsbuffrom the SDK'snode_modules;ci:check,ci:format,ci:lintandtest, which include thesdk: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-sdkto@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:
- 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. Coremainhas nosdk/typescriptchanges after that tag. - Allow merge commits for the import.
- Decide the package name and registry (decided:
- Import.
- Extract
sdk/typescript/with history usinggit filter-repo --subdirectory-filter, as for the Go SDK, and rewrite#Nreferences toNVIDIA/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.
- Extract
- Cutover in core.
- Remove the TypeScript SDK job from PR gating, and move
proto:lintonto a core-ownedbuf(mise tool). - Add a
TypeScript SDK Freezerequired check that fails on changes tosdk/typescript/. - Open PRs that edit
sdk/typescript/(12 on 2026-11-20 besides feat(sdk): replace the TypeScript SDK in core with an @ai-openshell/sdk stub #5685): feat(sdk): retry TypeScript sandbox create on lock timeout #5725, feat(compute)!: distinguish hard limits from sampled budgets #5119, feat(compute)!: check allowed service ports before creating sandboxes or forwards #5116, fix(forward): reject invalid TCP targets before opening a listener #5115, fix(server): consistent sandbox access after the main process exits #4950, feat(example): demonstrate V8 sandbox suspend and resume #4858, fix(supervisor): report isolation backend Attach refusals to the gateway #4791, feat(policy): freeze a sandbox's effective policy for its lifetime #4735, feat(services): add continuous HTTP readiness checks #4230, feat(sandbox): expose optional username and hostname #4220, feat(ts-sdk): add curated provider client #2964 (draft), feat: add sandbox disruption protection #2692. After feat(sdk): replace the TypeScript SDK in core with an @ai-openshell/sdk stub #5685 merges, comment on each: SDK changes need a separate PR in ai-openshell/sdk-typescript, and when the change also edits protos, that PR waits for the next core prerelease that includes the proto change (the SDK pins release tags). Not posted yet. The Go SDK move's notices are the model (for example feat(example): demonstrate V8 sandbox suspend and resume #4858 (comment)), but with one difference: core no longer keeps the SDK code, so the SDK part has to leave the core PR. - Tooling on the
migration/v0.1.9branch:hack/migration/port-pr.shports an open core PR with its original commits;hack/migration/import-core.shimports a change already on core's main exactly as it is there. feat(services): publish authoritative application origins #4956 was imported this way as feat(services): publish authoritative application origins (NVIDIA/OpenShell#4956) sdk-typescript#19, which waits forv0.1.10-pre.3. - Move the open TypeScript SDK issues (today: the TypeScript half of bug(sdk): TCP forward drops the response after the local client half-closes (Go Listen and TS forward) #4511), and point the issue templates and CONTRIBUTING at sdk-typescript.
- Remove the TypeScript SDK job from PR gating, and move
- Automation in sdk-typescript. As in sdk-python: bump PRs for each core release, E2E against that release's gateway (the
interactive-exectest moves with the SDK), release tagging and a nightly drift check. - Retire in core.
- Replace
sdk/typescript/with a stub@nvidia/openshell-sdkthat contains no SDK code: it depends on@ai-openshell/sdkand re-exports.and./rawfrom 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.10release publishes the stub from core.sdk-typescript-publish.ymlstamps 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.9before thev0.1.10core release; otherwise rerun the publish withworkflow_dispatchafter the SDK release. Users on^0.1.xwho upgrade get the new SDK without code changes. Installs still resolve because.npmrcsetups map only the@nvidiascope to GitHub Packages. Earlier versions stay published so existing lockfiles keep working. - Mark the old versions deprecated with a pointer to
@ai-openshell/sdkif GitHub Packages acceptsnpm deprecate(unconfirmed; test on one version first). - Announce the move in the
v0.1.10release notes, and tell NemoClaw directly. - After
@nvidia/openshell-sdk@0.1.10is published, remove the stub (as chore(sdk/go)!: remove the Go SDK, now at github.com/ai-openshell/sdk-go #5461 did for Go): deletesdk/typescript/andsdk-typescript-publish.yml, removepublish-sdk-typescriptfromrelease-publish.ymland its publisher gate, and remove theTypeScript SDK Freezejob. Later core releases publish no@nvidia/openshell-sdk. The0.1.10stub keeps resolving to the newest@ai-openshell/sdk0.1.x, and0.2.0requires the rename.
- Replace
- Release.
- Make ai-openshell/sdk-typescript public (drop
visibility = "private"in ai-openshell/infragithub/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(repositoryai-openshell/sdk-typescript, workflowrelease.yml, environmentnpm) 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 placeholder0.0.0-placeholder.0. - Publish the first release from sdk-typescript as
@ai-openshell/sdkto npmjs.org.
- Make ai-openshell/sdk-typescript public (drop
Progress:
- History import, frozen at
v0.1.8: chore: import the TypeScript SDK history from NVIDIA/OpenShell sdk-typescript#1. Extraction scripts on themigration/v0.1.8branch. - Standalone build, the rename to
@ai-openshell/sdk, committed bindings and CI on Node 20, 22 and 24: feat!: build, test, and package the TypeScript SDK standalone as @ai-openshell/sdk sdk-typescript#2 (stacked on ci: add GitHub Actions CI workflow with lint, test, and image build #1). - Core freeze and the
@nvidia/openshell-sdkre-export stub: feat(sdk): replace the TypeScript SDK in core with an @ai-openshell/sdk stub #5685. - Core sync (
core-watch,core-drift) and lockstep npm releases with trusted publishing: ci: core sync automation and npm releases with trusted publishing sdk-typescript#4. Needs:- ai-openshell/infra#67: the
sdk-botandnpmenvironments. - ci: GitHub App and sdk-bot secrets for the core-sync automation sdk-typescript#3: the
ai-openshell-sdk-typescriptApp and itssdk-botsecrets (org admin). - The npm trusted publisher and the public repository (phase 6).
- ai-openshell/infra#67: the
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.ymlin thenpmenvironment, so no token is stored. Installing needs no.npmrcor token. This replaces the earlier plan to start on GitHub Packages, now that we have access to theai-openshellnpm 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/orsdk-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-sdkfrom 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.
Metadata
Metadata
Assignees
Labels
area:buildCI/CD workflows, releases, build targets, packaging, and artifact publication.CI/CD workflows, releases, build targets, packaging, and artifact publication.topic:dxMaking OpenShell easy to contribute to for humans and agents.Making OpenShell easy to contribute to for humans and agents.topic:sdk:typescriptTypeScript SDK implementation, maintenance, interfaces, and distribution.TypeScript SDK implementation, maintenance, interfaces, and distribution.
Activity
pimlock commentedon Nov 20, 2026
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 corev0.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 by0.0.0-placeholder.0, and the first release is planned with corev0.1.10(2026-11-24), after the npm trusted publisher is set up on 2026-11-23. The core freeze and the@nvidia/openshell-sdkstub are in draft #5685.Merged
v0.1.9.@ai-openshell/sdk, committed bindings, CI on Node 20, 22 and 24.core-watchbump PRs, nightlycore-driftcheck) andrelease.ymlwith npm trusted publishing.forward()failed every connection against a real gateway.sdk-botandnpmenvironments. ci: GitHub App and sdk-bot secrets for the core-sync automation sdk-typescript#3: theai-openshell-sdk-typescriptApp and itssdk-botsecrets.core-watchopened its first bump PR, chore(core): track v0.1.10-pre.2 sdk-typescript#16 (v0.1.10-pre.2), closed since pre-release bumps are superseded.Open PRs
sdk/typescript/in core, replace it with the@nvidia/openshell-sdkre-export stub, moveproto:lintto core's Buf (closes #5684)/ok to test.Phases
v0.1.9, merge commits allowed for the import. Still to do: tell NemoClaw about the rename.proto:lintmove are in feat(sdk): replace the TypeScript SDK in core with an @ai-openshell/sdk stub #5685. Still to do: port the 12 other open core PRs that editsdk/typescript/, move the TypeScript half of bug(sdk): TCP forward drops the response after the local client half-closes (Go Listen and TS forward) #4511, and point the issue templates and CONTRIBUTING at sdk-typescript.v0.1.10release publishes the stub; it needs a matching@ai-openshell/sdk0.1.x on npmjs.org, or aworkflow_dispatchrerun after the SDK release. After that, remove the stub,sdk-typescript-publish.ymland the freeze job.v0.1.10.Tracked in sdk-typescript
sdk-botsecrets for core syncDecisions
@ai-openshell/sdk, kept for good. GitHub Packages ties the@nvidiascope to the NVIDIA org, so ai-openshell can't publish@nvidia/openshell-sdk.release.ymlin thenpmenvironment. No token is stored, and installing needs no.npmrc. The name is reserved by0.0.0-placeholder.0(dist-tagplaceholder). The trusted publisher must be used within 48 hours of being set up, so it's configured the day before the first release.git filter-repo --subdirectory-filter sdk/typescript, as for sdk-go. The extraction scripts are on the branchmigration/v0.1.8. One commit (fix(sandbox): complete successful main processes #2884) lacksSigned-off-byand needed a DCO override.protoc-gen-esfrom core's protos at the pinned tag (OPENSHELL_CORE_REF) and committed, with a staleness check. Go and Python commit theirs too.@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.main. No dev releases; to try unreleased changes, install from the repository.sdk/typescript/, except the stub's files. Deletions are allowed.Next
v0.1.10release.@ai-openshell/sdkwith corev0.1.10.v0.1.10stub publishes and resolves to@ai-openshell/sdk; rerun it after the SDK release if needed.v0.1.10release notes.sdk/typescript/, move the TypeScript half of bug(sdk): TCP forward drops the response after the local client half-closes (Go Listen and TS forward) #4511, and point the issue templates at sdk-typescript.sdk-typescript-publish.ymlfrom core after0.1.10is out.