Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions .gitattributes
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
src/gen/** linguist-generated
122 changes: 122 additions & 0 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,122 @@
# SPDX-License-Identifier: Apache-2.0

# Runs the contract tasks from mise.toml. The `ci` job is the one required
# status check; its name is the same in every repository built from the
# template, so one org ruleset can require it everywhere.
name: ci

on:
pull_request:
push:
branches: [main]
workflow_dispatch:

permissions:
contents: read

concurrency:
group: ci-${{ github.ref }}
cancel-in-progress: ${{ github.event_name == 'pull_request' }}

jobs:
checks:
name: checks
runs-on: ubuntu-latest
timeout-minutes: 15
steps:
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
persist-credentials: false

- uses: jdx/mise-action@f5be966e4a917d54244728e6a5fdcd1d93a35e6c # v5.2.6
with:
install: false

- name: Install tools
run: mise install --locked

- name: Format, lint, and drift checks
run: mise run check

# Every Node version in mise.toml's [tools], which are the releases
# package.json's engines field supports.
test:
name: test (node ${{ matrix.node }})
runs-on: ubuntu-latest
timeout-minutes: 15
strategy:
fail-fast: false
matrix:
node: ["20.20.2", "22.23.4", "24.22.2"]
env:
MISE_NODE_VERSION: ${{ matrix.node }}
steps:
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
persist-credentials: false

- uses: jdx/mise-action@f5be966e4a917d54244728e6a5fdcd1d93a35e6c # v5.2.6
with:
install: false

- name: Install tools
run: mise install --locked

- name: Unit tests
run: mise run test

build:
name: build
runs-on: ubuntu-latest
timeout-minutes: 15
steps:
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
persist-credentials: false

- uses: jdx/mise-action@f5be966e4a917d54244728e6a5fdcd1d93a35e6c # v5.2.6
with:
install: false

- name: Install tools
run: mise install --locked

- name: Build and verify
run: mise run build

workflows:
name: workflows
runs-on: ubuntu-latest
timeout-minutes: 10
steps:
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
persist-credentials: false

- uses: jdx/mise-action@f5be966e4a917d54244728e6a5fdcd1d93a35e6c # v5.2.6
with:
install: false

- name: Install tools
run: mise install --locked actionlint shellcheck zizmor

- name: Lint workflows
run: mise run workflows:check

ci:
name: ci
if: always()
needs: [checks, test, build, workflows]
runs-on: ubuntu-latest
timeout-minutes: 5
steps:
- name: Require every job to succeed
env:
RESULTS: ${{ join(needs.*.result, ' ') }}
run: |
for result in $RESULTS; do
if [ "$result" != success ]; then
echo "::error::a required job finished with '$result' ($RESULTS)"
exit 1
fi
done
5 changes: 4 additions & 1 deletion .gitignore
Original file line number Diff line number Diff line change
@@ -1,5 +1,8 @@
node_modules/
src/gen/
dist/
*.tsbuildinfo
.npmrc
coverage/

# Core protos fetched at the pinned ref by `mise run proto:fetch`.
/proto/
53 changes: 30 additions & 23 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,32 +1,34 @@
# @nvidia/openshell-sdk
# @ai-openshell/sdk

TypeScript client for the OpenShell gateway — thin, idiomatic bindings generated from the OpenShell protobufs.

Distributed via GitHub Packages. A public npm release under the same name follows once the npm org is in place; the install specifier and API are unchanged across that move.

This package was published from [NVIDIA/OpenShell](https://github.com/NVIDIA/OpenShell) as `@nvidia/openshell-sdk` before SDK development moved to this repository. To upgrade, replace `@nvidia/openshell-sdk` with `@ai-openshell/sdk` in `package.json` and in imports, and change the `.npmrc` scope below. The entry points (`.` and `./raw`) and the API are unchanged.

Use the SDK and gateway from the same OpenShell release when possible. The raw
types and RPC descriptors are generated from the protobuf definitions in that
release; curated methods remain compatible while those RPC contracts remain
compatible.

## Install

Published to GitHub Packages, so point the `@nvidia` scope at it with a project `.npmrc`:
Published to GitHub Packages, so point the `@ai-openshell` scope at it with a project `.npmrc`:

```shell
@nvidia:registry=https://npm.pkg.github.com
@ai-openshell:registry=https://npm.pkg.github.com
```

Authenticate with a GitHub token that has `read:packages`, then:

```shell
npm install @nvidia/openshell-sdk
npm install @ai-openshell/sdk
```

## Usage

```ts
import { OpenShellClient } from '@nvidia/openshell-sdk'
import { OpenShellClient } from '@ai-openshell/sdk'

const client = await OpenShellClient.connect({
gateway: 'https://gateway.example.com',
Expand Down Expand Up @@ -72,7 +74,7 @@ the client's lifetime. For long-running service automation, use the renewable
client-credentials provider:

```ts
import { clientCredentials, OpenShellClient } from '@nvidia/openshell-sdk'
import { clientCredentials, OpenShellClient } from '@ai-openshell/sdk'

const client = await OpenShellClient.connect({
gateway,
Expand Down Expand Up @@ -111,7 +113,7 @@ await client.sandbox.create({
directly — same API, one less hop:

```ts
import { SandboxClient } from '@nvidia/openshell-sdk'
import { SandboxClient } from '@ai-openshell/sdk'

const sandbox = await SandboxClient.connect({ gateway, oidcToken })
await sandbox.create({ image })
Expand All @@ -125,7 +127,7 @@ Enable operator authentication at the gateway and omit OIDC and edge tokens.
No sandbox or provider attachment is required.

```ts
import { ProviderClient } from '@nvidia/openshell-sdk'
import { ProviderClient } from '@ai-openshell/sdk'

const providers = await ProviderClient.connect({ gateway, caCert, clientCert, clientKey })
const credentials = await providers.getCredentials(
Expand Down Expand Up @@ -224,7 +226,7 @@ own image, environment, resource, and driver-specific settings; sandbox creation
from a template can still attach labels, providers, and create-time policy.

```ts
import { OpenShellClient, type SandboxWorkloadTemplate } from '@nvidia/openshell-sdk'
import { OpenShellClient, type SandboxWorkloadTemplate } from '@ai-openshell/sdk'

const client = await OpenShellClient.connect({ gateway, oidcToken })

Expand Down Expand Up @@ -285,13 +287,13 @@ Curated methods are added deliberately, so some gateway RPCs are not yet wrapped

### Advanced: raw escape hatch

`client.raw` is a generated client for every gateway RPC, including surface the curated sub-clients do not wrap yet (gateway config, provider CRUD, policy status, watch, logs, and the full observed `Sandbox`). `client.transport` is the shared connection, so extra clients reuse one socket. Generated request and response types live at `@nvidia/openshell-sdk/raw`.
`client.raw` is a generated client for every gateway RPC, including surface the curated sub-clients do not wrap yet (gateway config, provider CRUD, policy status, watch, logs, and the full observed `Sandbox`). `client.transport` is the shared connection, so extra clients reuse one socket. Generated request and response types live at `@ai-openshell/sdk/raw`.

```ts
import { create } from '@bufbuild/protobuf'
import { OpenShellClient } from '@nvidia/openshell-sdk'
import { WorkspaceSelectorSchema } from '@nvidia/openshell-sdk/raw'
import type { GetGatewayConfigResponse } from '@nvidia/openshell-sdk/raw'
import { OpenShellClient } from '@ai-openshell/sdk'
import { WorkspaceSelectorSchema } from '@ai-openshell/sdk/raw'
import type { GetGatewayConfigResponse } from '@ai-openshell/sdk/raw'

const client = await OpenShellClient.connect({ gateway, oidcToken })

Expand Down Expand Up @@ -321,7 +323,7 @@ installs no application routes.
Complete object literals typed as either generated message must add
`serviceRoutes: []`. Alternatively, use `create(SandboxConfigSnapshotSchema, init)`
or `create(GetSandboxConfigResponseSchema, init)` from `@bufbuild/protobuf`, with
the corresponding schema imported from `@nvidia/openshell-sdk/raw`. Schema-based
the corresponding schema imported from `@ai-openshell/sdk/raw`. Schema-based
initialization supplies the empty array when omitted. The curated SDK API is
unchanged.

Expand All @@ -335,16 +337,21 @@ The SDK ships primitives, not the CLI's terminal experience. Some things are int

## Development

The version field is a `0.0.0` placeholder; CI stamps the real version from the git release tag at publish time, matching the Rust and Python packages.
The version field is a `0.0.0` placeholder; the release workflow stamps the real version at publish time.

The bindings in `src/gen/` are generated from the protos of the OpenShell core release pinned in `mise.toml` (`OPENSHELL_CORE_REF`) and committed, so building and testing need no core checkout. `mise run proto:check` fails when they are stale.

```shell
mise run sdk:ts:proto # generate stubs from proto/ with buf
mise run sdk:ts:format # Biome: format + safe fixes (writes)
mise run sdk:ts:lint # Biome: lint + format check (read-only)
mise run sdk:ts:typecheck # tsc --noEmit
mise run sdk:ts:test # Vitest unit tests with an 80% line-coverage gate
mise run sdk:ts:build # emit dist/
mise run e2e:sdk:ts:exec # public interactive helper against an isolated Docker gateway
mise run ci # everything CI runs: check, test, build
mise run proto:gen # fetch core's protos at the pin and regenerate src/gen/
mise run format # Biome: format + safe fixes (writes)
mise run check # format check, lint, typecheck, proto:check, vendored:check
mise run test # Vitest unit tests with an 80% line-coverage gate
mise run build # emit dist/ and verify the package contents
```

Formatting and linting are handled by [Biome](https://biomejs.dev) (`biome.json`): 2-space indent, single quotes, semicolons, 120-column width. Generated `src/gen/` is excluded. `sdk:ts:lint` runs in CI as part of `sdk:ts:ci`.
Formatting and linting are handled by [Biome](https://biomejs.dev) (`biome.json`): 2-space indent, single quotes, semicolons, 120-column width. Generated `src/gen/` and the fixtures vendored from core (`test/fixtures/`, listed in `scripts/vendored-core-files.txt`) are excluded.

CI runs the unit tests on every Node version in `mise.toml`. To run them on one locally, set `MISE_NODE_VERSION`, for example `MISE_NODE_VERSION=20.20.2 mise run test`.

`e2e/interactive-exec.mjs` still expects core's Docker gateway harness; running it here against a published gateway comes with the E2E workflow.
2 changes: 1 addition & 1 deletion biome.json
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@
"useIgnoreFile": true
},
"files": {
"includes": ["**", "!src/gen", "!dist", "!coverage"]
"includes": ["**", "!src/gen", "!dist", "!coverage", "!test/fixtures"]
},
"formatter": {
"enabled": true,
Expand Down
20 changes: 10 additions & 10 deletions buf.gen.yaml
Original file line number Diff line number Diff line change
@@ -1,22 +1,22 @@
# SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
# SPDX-License-Identifier: Apache-2.0

# Code generation for the TypeScript SDK. The proto module boundary and
# validation policy live in the repo-level buf.yaml; this template only drives
# generation. buf compiles the module with its own compiler (no protoc) and
# runs the connect-es plugin from this package's devDependencies. Limited to
# the client-surface closure so we don't emit unused compute/test
# Code generation for the TypeScript SDK. `mise run proto:fetch` exports core's
# protos at the pinned ref (OPENSHELL_CORE_REF) into proto/; this template only
# drives generation. buf compiles the module with its own compiler (no protoc)
# and runs the protoc-gen-es plugin from this package's devDependencies.
# Limited to the client-surface closure so we don't emit unused compute/test
# protos; well-known types resolve through @bufbuild/protobuf/wkt and are not
# generated.
version: v2
clean: true
inputs:
- directory: ../../proto
- directory: proto
paths:
- ../../proto/openshell.proto
- ../../proto/sandbox.proto
- ../../proto/datamodel.proto
- ../../proto/options.proto
- proto/openshell.proto
- proto/sandbox.proto
- proto/datamodel.proto
- proto/options.proto
# Standard rich gRPC error messages, pinned to an immutable Google APIs commit.
- module: buf.build/googleapis/googleapis:c17df5b2beca46928cc87d5656bd5343
paths:
Expand Down
2 changes: 1 addition & 1 deletion e2e/interactive-exec.mjs
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
// SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
// SPDX-License-Identifier: Apache-2.0

// Run through mise run e2e:sdk:ts:exec, which supplies an isolated gateway.
// Needs a gateway; the E2E workflow that runs it against a published gateway is not set up yet.
import assert from 'node:assert/strict';
import { readFileSync } from 'node:fs';
import { join } from 'node:path';
Expand Down
Loading
Loading