Skip to content

feat(sdk): replace the TypeScript SDK in core with an @ai-openshell/sdk stub - #5685

Merged
pimlock merged 6 commits into
mainfrom
5684-freeze-typescript-sdk/pimlock
Nov 20, 2026
Merged

pimlock merged 6 commits into
mainfrom
5684-freeze-typescript-sdk/pimlock

Conversation

@pimlock

@pimlock pimlock commented Nov 18, 2026 •

Copy link
Copy Markdown
Contributor

Summary

The TypeScript SDK moved to ai-openshell/sdk-typescript and is published to npmjs.org as @ai-openshell/sdk. This PR freezes sdk/typescript/ in core and replaces it with a stub @nvidia/openshell-sdk that re-exports @ai-openshell/sdk. The v0.1.10 release publishes that stub, so existing users get the SDK from the new repository without code changes. Core removes the stub after v0.1.10.

Related Issue

Closes #5684. Part of #5480.

#4956 changed sdk/typescript/ after the v0.1.9 import. This PR deletes that change here; ai-openshell/sdk-typescript#19 imports it there, and lands once a core prerelease includes #4956.

Changes

  • Replace sdk/typescript/ with the stub: . and ./raw re-export @ai-openshell/sdk, and the README explains how to switch.
  • sdk-typescript-publish.yml publishes the stub with a ^X.Y.0 dependency and fails if npmjs.org has no matching @ai-openshell/sdk. It is manual dispatch only: sdk-typescript releases @ai-openshell/sdk@X.Y.Z after core tags vX.Y.Z, so the core Release workflow no longer publishes the stub. Run it for v0.1.10 after @ai-openshell/sdk@0.1.10 is on npmjs.org.
  • Replace the TypeScript SDK CI job with a TypeScript SDK Freeze check that rejects SDK changes other than deletions and edits to the stub's own files.
  • Remove the SDK tasks from core, and run proto:lint with core's own Buf.
  • Point docs, contributor guidance and skills at @ai-openshell/sdk.

Release Notes

The TypeScript SDK moved to ai-openshell/sdk-typescript and is now published as @ai-openshell/sdk on npmjs.org. @nvidia/openshell-sdk@0.1.10 is the last release of the old package. It re-exports @ai-openshell/sdk and depends on ^0.1.0, so existing code keeps working and keeps receiving 0.1.x releases. We recommend switching to the new package; see the @nvidia/openshell-sdk package page for migration notes.

Testing

  • mise run pre-commit passes.
  • The packed stub exposes the same exports and types as @ai-openshell/sdk in a consumer project.
  • The freeze check accepts core-only and deletion-only changes and rejects SDK edits.

Checklist

  • Follows Conventional Commits
  • Commits are signed off (DCO)
  • Architecture table and contributor guidance updated

@copy-pr-bot

copy-pr-bot Bot commented Nov 18, 2026

Copy link
Copy Markdown

Auto-sync is disabled for draft pull requests in this repository. Workflows must be run manually.

Contributors can view more details about this message here.

@github-actions github-actions Bot added the state:accepted A maintainer decided OpenShell should pursue this issue label Nov 18, 2026
@github-actions

Copy link
Copy Markdown

@pimlock pimlock changed the title ci(sdk): freeze TypeScript SDK changes in core feat(sdk): replace the TypeScript SDK in core with an @ai-openshell/sdk stub Nov 20, 2026
pimlock added a commit to ai-openshell/sdk-typescript that referenced this pull request Nov 20, 2026
Core replaces its TypeScript SDK with @nvidia/openshell-sdk@0.1.10, a stub
that depends on @ai-openshell/sdk@^0.1.0 and re-exports . and ./raw
(ai-openshell/openshell#5685). Record what that means here: keep both entry
points and keep breaking changes out of 0.1.x, since users of the old
name receive every 0.1.x release. Tell README readers that the old name
keeps working through 0.1.x.

Core's agent instructions also explained which protos the SDK compiles.
Here the list lives in two places, proto:fetch and buf.gen.yaml, so say
that a new core proto file goes in both.

Signed-off-by: Piotr Mlocek <pmlocek@nvidia.com>
@pimlock
pimlock force-pushed the 5684-freeze-typescript-sdk/pimlock branch from f6f4ff8 to db3ac9e Compare November 20, 2026 00:25
@pimlock
pimlock marked this pull request as ready for review November 20, 2026 00:49
@github-actions

Copy link
Copy Markdown

Compatibility review (advisory)

New or updated breaking changes; see the full report for all findings.

1. typescript-sdk — No explicit risk acceptance found

@nvidia/openshell-sdk and /raw now re-export @ai-openshell/sdk@^0.1.0 instead of shipping the baseline implementation, leaving preservation of its APIs unverified.

  • Impact: Existing callers may lose baseline SandboxRef.applicationServiceUrls, SandboxRef.gatewayServiceUrls, or matching generated types because the replacement source is absent and the PR describes the corresponding SDK port as pending.
  • Action: Before qualifying v0.1.10, verify a published replacement preserves the baseline root/raw APIs and runtime behavior, and require at least that compatible version.
  • PR: feat(sdk): replace the TypeScript SDK in core with an @ai-openshell/sdk stub #5685
Review details
  • Execution: incomplete
  • Candidate: PR #5685 (aa0793230890e1705793adaae29f48081b780323)
  • Baseline: c24fcd232f84c132d1e9c163b0375e5c6c8e0614 (c24fcd232f84c132d1e9c163b0375e5c6c8e0614)
  • Reviewed: rust-sdk, python-sdk, api-behavior, cli, configuration, policy, helm, state

Advisory review; publication gates are unchanged.

Branch check run

Signed-off-by: Piotr Mlocek <pmlocek@nvidia.com>
The TypeScript SDK now lives in ai-openshell/sdk-typescript and publishes
@ai-openshell/sdk to npmjs.org. Replace sdk/typescript with a stub package
that keeps the @nvidia/openshell-sdk name, depends on @ai-openshell/sdk,
and re-exports its root and /raw entry points. Existing users on a 0.1.x
range move to the new code without changing imports, and the README
gives migration steps.

The release publisher stamps the dependency to the release's minor line
(^X.Y.0) and fails when npmjs.org has no matching @ai-openshell/sdk, so a
stub is never published that npm cannot install. Rerun it with
workflow_dispatch after the SDK release.

The freeze check allows the stub's files. Remove the SDK sources,
tooling, mise tasks, Windows helpers, CodeQL paths, and license
sidecars, and point the docs at @ai-openshell/sdk.

Signed-off-by: Piotr Mlocek <pmlocek@nvidia.com>
ai-openshell/sdk-typescript documents the SDK, and CONTRIBUTING and CI.md cover the core stub and its freeze check.

Signed-off-by: Piotr Mlocek <pmlocek@nvidia.com>
CI.md and CONTRIBUTING state the move in one sentence, and the release canary skill no longer mentions the SDK.

Signed-off-by: Piotr Mlocek <pmlocek@nvidia.com>
@pimlock
pimlock force-pushed the 5684-freeze-typescript-sdk/pimlock branch from db3ac9e to 6d8b101 Compare November 20, 2026 15:46
@pimlock
pimlock requested a review from a team as a code owner November 20, 2026 15:46
The stub depends on @ai-openshell/sdk from the same minor line, and
sdk-typescript only releases that after core tags the matching version.
Publishing the stub from the core Release workflow would always fail on
its only run, so make sdk-typescript-publish.yml manual dispatch only
and drop it from Check Publication.

Signed-off-by: Piotr Mlocek <pmlocek@nvidia.com>
@pimlock

pimlock commented Nov 20, 2026

Copy link
Copy Markdown
Contributor Author

Re: the compatibility review finding on typescript-sdk.

No released API is lost. SandboxRef.applicationServiceUrls, SandboxRef.gatewayServiceUrls, and the matching generated types come from #4956, which is in v0.1.10-pre.3 but not in v0.1.9. The stub publish only runs for stable releases, so no released @nvidia/openshell-sdk ever shipped these fields. The review compared against main, not the last release.

v0.1.10 gets them through the SDK release order:

Before v0.1.10 ships, we'll confirm that @ai-openshell/sdk@0.1.10 exports these fields from both the root and /raw entry points.

The TypeScript SDK implementation moved to ai-openshell/sdk-typescript,
so the review could not inspect it and marked the surface unreviewed on
every run. Remove typescript-sdk from the required surfaces in the
review prompt and the report validator, as done for go-sdk.

Signed-off-by: Piotr Mlocek <pmlocek@nvidia.com>
@pimlock
pimlock added this pull request to the merge queue Nov 20, 2026
Merged via the queue into main with commit b20c144 Nov 20, 2026
89 checks passed
@pimlock
pimlock deleted the 5684-freeze-typescript-sdk/pimlock branch November 20, 2026 19:06
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

state:accepted A maintainer decided OpenShell should pursue this issue

Projects

None yet

Development

Successfully merging this pull request may close these issues.

chore(sdk/ts): freeze core SDK changes at v0.1.9

2 participants