@nimbus-sh/sdk 0.1.0 → 0.1.2

package/README.md

@@ -1,7 +1,7 @@
 # @nimbus-sh/sdk
 
-SDK for Nimbus — programmatic sandbox handles, token mint/verify, typed
-errors, and session URL helpers.
+SDK for Nimbus — Worker embedder, programmatic sandbox handles,
+token mint/verify, typed errors, and session URL helpers.
 
 ## Install
 
@@ -9,41 +9,85 @@ errors, and session URL helpers.
 npm install @nimbus-sh/sdk @nimbus-sh/worker @nimbus-sh/config
 ```
 
-The sandbox SDK is meant to run inside the Worker or Durable Object that owns
-the `NIMBUS_SESSION` binding. A minimal project setup is:
+Use `@nimbus-sh/sdk/worker` as the public Worker embedder entrypoint.
+`@nimbus-sh/worker` is still installed because it carries the runtime assets
+and Durable Object implementation, but application code imports the
+deploy-time API through the SDK.
+
+Create a deployable Nimbus Worker:
 
 ```bash
-npx @nimbus-sh/cli init my-nimbus-worker
+npx create-nimbus-app my-nimbus-worker
 cd my-nimbus-worker
 npm install
-wrangler secret put JWT_SECRET
-wrangler deploy
+CLOUDFLARE_ACCOUNT_ID=<account-id> npx @nimbus-sh/cli setup cloudflare --name my-nimbus-worker
+npx wrangler secret put JWT_SECRET
+npx wrangler deploy
 ```
 
-From this repository, use the source CLI:
+`src/index.ts`:
 
-```bash
-bun packages/cli/src/bin.ts init my-nimbus-worker
-cd my-nimbus-worker
-bun install
-wrangler secret put JWT_SECRET
-wrangler deploy
+```ts
+import {
+  NimbusSession,
+  SupervisorRPC,
+  NimbusAssetsRPC,
+  NimbusLoaderRPC,
+  NimbusLoadedWorker,
+  NimbusLoadedEntrypoint,
+  NimbusDurableObjectNamespace,
+  NimbusDOStub,
+  CirrusHmrRPC,
+  createNimbusHandler,
+} from '@nimbus-sh/sdk/worker';
+import { defineNimbusConfig } from '@nimbus-sh/config';
+
+export {
+  NimbusSession,
+  SupervisorRPC,
+  NimbusAssetsRPC,
+  NimbusLoaderRPC,
+  NimbusLoadedWorker,
+  NimbusLoadedEntrypoint,
+  NimbusDurableObjectNamespace,
+  NimbusDOStub,
+  CirrusHmrRPC,
+};
+
+const nimbusConfig = defineNimbusConfig({
+  sandboxes: {
+    default: {
+      root: '/home/user',
+      runtimes: { preinstall: ['python'], onDemand: true },
+      tools: { namespace: 'sandbox', kind: 'sandbox' },
+    },
+  },
+});
+
+export default createNimbusHandler({
+  sdk: {
+    remote: true,
+    config: nimbusConfig,
+  },
+});
 ```
 
 ## Programmatic sandbox quickstart
 
-Use `@nimbus-sh/sdk/sandbox` inside the Worker or Durable Object that embeds
-Nimbus. The SDK talks to the `NIMBUS_SESSION` Durable Object binding via DO
-RPC; it does not need a browser WebSocket.
+The same sandbox handle API works in two modes:
+
+- `Nimbus.fromEnv(env, config)` for a Worker or Durable Object with the
+  `NIMBUS_SESSION` binding.
+- `Nimbus.connect({ endpoint, token, config })` for any backend that can reach
+  a deployed Nimbus Worker.
 
 ```ts
-import { Nimbus } from '@nimbus-sh/sdk/sandbox';
+import { Nimbus } from '@nimbus-sh/sdk';
 import { defineNimbusConfig } from '@nimbus-sh/config';
 
 const nimbusConfig = defineNimbusConfig({
-  endpoint: 'https://my-nimbus.workers.dev',
   sandboxes: {
-    proteus: {
+    default: {
       root: '/home/user',
       tools: { namespace: 'sandbox', kind: 'sandbox' },
       runtimes: {
@@ -58,7 +102,6 @@ const nimbusConfig = defineNimbusConfig({
 export default {
   async fetch(_request: Request, env: Env) {
     const box = Nimbus.fromEnv(env, nimbusConfig).sandbox('job-123', {
-      profile: 'proteus',
       tenant: 'acme',
       subject: 'agent',
     });
@@ -72,10 +115,50 @@ export default {
 };
 ```
 
+Remote use:
+
+```ts
+import { Nimbus, issueNimbusToken } from '@nimbus-sh/sdk';
+
+const token = await issueNimbusToken(env, {
+  tn: 'acme',
+  sub: 'agent',
+  scopes: ['sandbox:use'],
+  sid: 'job-123',
+});
+
+const box = Nimbus.connect({
+  endpoint: 'https://my-nimbus.workers.dev',
+  token,
+  config: nimbusConfig,
+}).sandbox('job-123');
+
+const result = await box.exec('python -c "print(2 + 2)"');
+```
+
+Enable the remote API in the Nimbus Worker:
+
+```ts
+export default createNimbusHandler({
+  sdk: {
+    remote: true,
+    config: nimbusConfig,
+  },
+});
+```
+
+`Nimbus.connect()` calls the versioned `/api/nimbus/v1` API internally. The
+Worker verifies the JWT, enforces `sid` pins and `sandbox:use` scope, applies
+the configured runtime policy, and delegates to the same `NimbusSession` RPC
+methods used by `Nimbus.fromEnv()`.
+
 ## Sandbox handle API
 
 ```ts
 const nimbus = Nimbus.fromEnv(env, config, { binding: 'NIMBUS_SESSION' });
+// or:
+const nimbus = Nimbus.connect({ endpoint, token, config });
+
 const box = nimbus.sandbox('session-or-job-id', {
   profile: 'default',
   tenant: 'acme',
@@ -213,6 +296,7 @@ const { token, url } = await mintAndAttach(
 | `@nimbus-sh/sdk/errors` | `NimbusAuthError` class hierarchy. |
 | `@nimbus-sh/sdk/session` | `sessionAttachUrl`, `mintAndAttach`. |
 | `@nimbus-sh/sdk/sandbox` | `Nimbus`, `NimbusSandbox`, programmatic exec/files/runtimes/processes/ports/tools. |
+| `@nimbus-sh/sdk/worker` | Worker embedder entrypoint: `NimbusSession`, RPC classes, `createNimbusHandler`, auth helpers. |
 
 ## Token wire format
 

package/dist/index.d.ts

@@ -1,14 +1,14 @@
 /**
- * @nimbus-sh/sdk — Client SDK for Nimbus.
+ * @nimbus-sh/sdk — Public SDK for Nimbus.
  *
- * The SDK is the **environment-agnostic** half of Nimbus: token mint /
- * verify, typed errors, session-handle types, and the HTTP fallback for
- * non-Worker consumers. Everything in this package is safe to import
- * from a Node SSR layer, a Worker, an Edge function, or a browser
- * build.
+ * The SDK is the public surface for Nimbus applications: token mint /
+ * verify, typed errors, session-handle helpers, programmatic sandboxes,
+ * and the Worker embedder subpath.
  *
- * For the Worker runtime itself (the Durable Object, the router, the
- * facet machinery), see `@nimbus-sh/worker`.
+ * Import the deployed Worker embedder from `@nimbus-sh/sdk/worker`.
+ * The Durable Object, router, assets, VFS, and facet implementation live
+ * in `@nimbus-sh/worker` and are re-exported through that public SDK
+ * subpath.
  *
  * @example mint a token in your Worker's `/api/auth/mint` route
  * ```ts

package/dist/index.js

@@ -1,14 +1,14 @@
 /**
- * @nimbus-sh/sdk — Client SDK for Nimbus.
+ * @nimbus-sh/sdk — Public SDK for Nimbus.
  *
- * The SDK is the **environment-agnostic** half of Nimbus: token mint /
- * verify, typed errors, session-handle types, and the HTTP fallback for
- * non-Worker consumers. Everything in this package is safe to import
- * from a Node SSR layer, a Worker, an Edge function, or a browser
- * build.
+ * The SDK is the public surface for Nimbus applications: token mint /
+ * verify, typed errors, session-handle helpers, programmatic sandboxes,
+ * and the Worker embedder subpath.
  *
- * For the Worker runtime itself (the Durable Object, the router, the
- * facet machinery), see `@nimbus-sh/worker`.
+ * Import the deployed Worker embedder from `@nimbus-sh/sdk/worker`.
+ * The Durable Object, router, assets, VFS, and facet implementation live
+ * in `@nimbus-sh/worker` and are re-exported through that public SDK
+ * subpath.
  *
  * @example mint a token in your Worker's `/api/auth/mint` route
  * ```ts

package/dist/sandbox.d.ts

@@ -28,6 +28,21 @@ export interface NimbusFromEnvOptions {
     binding?: string;
     endpoint?: string;
 }
+export type NimbusHeaders = HeadersInit | (() => HeadersInit | Promise<HeadersInit>);
+export interface NimbusConnectOptions {
+    /** Base URL of a Nimbus deployment, for example `https://nimbus.example.com`. */
+    endpoint: string;
+    /** Nimbus JWT. Sent as `Authorization: Bearer <token>` when provided. */
+    token?: string;
+    /** Additional headers, or a callback for rotating credentials. */
+    headers?: NimbusHeaders;
+    /** Custom fetch implementation. Defaults to global `fetch`. */
+    fetch?: typeof fetch;
+    /** Remote API base path. Defaults to `/api/nimbus/v1`. */
+    basePath?: string;
+    /** Sandbox profiles used by this client. The deployment should use the same config. */
+    config?: NimbusConfig;
+}
 export interface NimbusSandboxOptions {
     profile?: string;
     tenant?: string;
@@ -88,26 +103,50 @@ export interface NimbusAvailableRuntime {
     }>;
 }
 type NimbusSessionNamespace = DurableObjectNamespace<any>;
+type NimbusTarget = {
+    kind: 'binding';
+    namespace: NimbusSessionNamespace;
+} | {
+    kind: 'remote';
+    endpoint: string;
+    basePath: string;
+    token?: string;
+    headers?: NimbusHeaders;
+    fetch: typeof fetch;
+};
+export declare class NimbusRemoteError extends Error {
+    readonly status: number;
+    readonly code: string | undefined;
+    readonly body: unknown;
+    constructor(message: string, options: {
+        status: number;
+        code?: string;
+        body?: unknown;
+    });
+}
 export declare class Nimbus {
-    private readonly namespace;
     private readonly config;
     static fromEnv(env: Record<string, unknown>, config?: NimbusConfig, options?: NimbusFromEnvOptions): Nimbus;
-    constructor(namespace: NimbusSessionNamespace, config?: NimbusConfig);
+    static connect(options: NimbusConnectOptions): Nimbus;
+    private readonly target;
+    constructor(target: NimbusSessionNamespace | NimbusTarget, config?: NimbusConfig);
     sandbox(id: string, options?: NimbusSandboxOptions): NimbusSandbox;
 }
 export declare class NimbusSandbox {
-    private readonly namespace;
+    private readonly target;
     private readonly options;
     private readonly config;
     readonly id: string;
     readonly profileName: string;
     private readonly profile;
     private readyPromise;
-    constructor(namespace: NimbusSessionNamespace, id: string, options: NimbusSandboxOptions, config: NimbusConfig);
+    constructor(target: NimbusTarget, id: string, options: NimbusSandboxOptions, config: NimbusConfig);
     private get tenantSegment();
     private get doName();
     private get root();
     private stub;
+    private remoteStub;
+    private remoteRpc;
     ready(): Promise<void>;
     exec(command: string, options?: NimbusExecOptions): Promise<NimbusExecResult>;
     startProcess(command: string, options?: NimbusExecOptions): Promise<NimbusStartResult>;

package/dist/sandbox.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sandbox.d.ts","sourceRoot":"","sources":["../src/sandbox.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,MAAM,MAAM,WAAW,GAAG,MAAM,CAAC;AACjC,MAAM,MAAM,WAAW,GACnB,MAAM,GACN,KAAK,GACL,KAAK,GACL,KAAK,GACL,QAAQ,GACR,MAAM,GACN,OAAO,GACP,OAAO,GACP,CAAC,MAAM,GAAG,EAAE,CAAC,CAAC;AAElB,MAAM,WAAW,mBAAmB;IAClC,UAAU,CAAC,EAAE,WAAW,EAAE,CAAC;IAC3B,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,KAAK,CAAC,EAAE,WAAW,EAAE,CAAC;CACvB;AAED,MAAM,WAAW,oBAAoB;IACnC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,mBAAmB,CAAC;IAC/B,KAAK,CAAC,EAAE;QACN,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,IAAI,CAAC,EAAE,MAAM,CAAC;KACf,CAAC;IACF,OAAO,CAAC,EAAE;QACR,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,SAAS,CAAC,EAAE,OAAO,CAAC;KACrB,CAAC;CACH;AAED,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,oBAAoB,CAAC,CAAC;CAClD;AAED,MAAM,WAAW,oBAAoB;IACnC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,oBAAoB;IACnC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,iBAAiB;IAChC,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC7B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,gBAAgB;IAC/B,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,OAAO,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,iBAAkB,SAAQ,gBAAgB;IACzD,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IACnB,OAAO,EAAE,aAAa,GAAG,IAAI,CAAC;IAC9B,KAAK,EAAE,UAAU,EAAE,CAAC;CACrB;AAED,MAAM,WAAW,aAAa;IAC5B,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,WAAW,EAAE,OAAO,CAAC;CACtB;AAED,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,MAAM,CAAC;IACZ,YAAY,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,oBAAoB;IACnC,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,sBAAsB;IACrC,IAAI,EAAE,MAAM,CAAC;IACb,cAAc,EAAE,MAAM,CAAC;IACvB,QAAQ,EAAE,KAAK,CAAC;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CAC1E;AAyBD,KAAK,sBAAsB,GAAG,sBAAsB,CAAC,GAAG,CAAC,CAAC;AAE1D,qBAAa,MAAM;IAkBf,OAAO,CAAC,QAAQ,CAAC,SAAS;IAC1B,OAAO,CAAC,QAAQ,CAAC,MAAM;IAlBzB,MAAM,CAAC,OAAO,CACZ,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC5B,MAAM,GAAE,YAAiB,EACzB,OAAO,GAAE,oBAAyB,GACjC,MAAM;gBAaU,SAAS,EAAE,sBAAsB,EACjC,MAAM,GAAE,YAAiB;IAG5C,OAAO,CAAC,EAAE,EAAE,MAAM,EAAE,OAAO,GAAE,oBAAyB,GAAG,aAAa;CAGvE;AAED,qBAAa,aAAa;IAOtB,OAAO,CAAC,QAAQ,CAAC,SAAS;IAE1B,OAAO,CAAC,QAAQ,CAAC,OAAO;IACxB,OAAO,CAAC,QAAQ,CAAC,MAAM;IATzB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAuB;IAC/C,OAAO,CAAC,YAAY,CAA8B;gBAG/B,SAAS,EAAE,sBAAsB,EAClD,EAAE,EAAE,MAAM,EACO,OAAO,EAAE,oBAAoB,EAC7B,MAAM,EAAE,YAAY;IAOvC,OAAO,KAAK,aAAa,GAIxB;IAED,OAAO,KAAK,MAAM,GAEjB;IAED,OAAO,KAAK,IAAI,GAEf;IAED,OAAO,CAAC,IAAI;IAMN,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAStB,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,GAAE,iBAAsB,GAAG,OAAO,CAAC,gBAAgB,CAAC;IAKjF,YAAY,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,GAAE,iBAAsB,GAAG,OAAO,CAAC,iBAAiB,CAAC;IAK1F,OAAO,CACX,IAAI,EAAE,MAAM,EACZ,OAAO,GAAE,iBAAiB,GAAG;QAC3B,QAAQ,CAAC,EAAE,YAAY,GAAG,YAAY,GAAG,QAAQ,GAAG,MAAM,GAAG,OAAO,CAAC;QACrE,OAAO,CAAC,EAAE,OAAO,GAAG,WAAW,CAAC;KAC5B,GACL,OAAO,CAAC,gBAAgB,CAAC;IAa5B,KAAK;qBACgB,MAAM,KAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;0BAI1B,MAAM,KAAG,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC;sBAIvC,MAAM,WAAW,MAAM,GAAG,UAAU,KAAG,OAAO,CAAC,IAAI,CAAC;iCAIxC,OAAO,CAAC;YAAE,IAAI,EAAE,MAAM,CAAC;YAAC,IAAI,EAAE,MAAM,CAAA;SAAE,EAAE,CAAC;sBAIrD,MAAM,KAAG,OAAO,CAAC,IAAI,CAAC;uBAIrB,MAAM,KAAG,OAAO,CAAC,OAAO,CAAC;uBAIzB,MAAM,YAAW;YAAE,SAAS,CAAC,EAAE,OAAO,CAAA;SAAE,KAAQ,OAAO,CAAC,IAAI,CAAC;MAIlF;IAEF,QAAQ;yBACe,OAAO,CAAC,sBAAsB,EAAE,CAAC;yBAIjC,OAAO,CAAC,oBAAoB,EAAE,CAAC;;uBArJb,oBAAoB,EAAE;uBAAa,sBAAsB,EAAE;;wBA6J5E,WAAW,YAAW;YAAE,KAAK,CAAC,EAAE,OAAO,CAAA;SAAE;wBAKzC,WAAW,GAAG,WAAW,EAAE,YAAW;YAAE,KAAK,CAAC,EAAE,OAAO,CAAA;SAAE;MAM/E;IAEF,SAAS;oBACS,OAAO,CAAC,aAAa,EAAE,CAAC;oBAItB,MAAM;gBA7KkB,OAAO;iBAAO,MAAM;;oBAiL5C,MAAM,YAAW;YAAE,KAAK,CAAC,EAAE,MAAM,CAAC;YAAC,KAAK,CAAC,EAAE,MAAM,CAAA;SAAE;MAIrE;IAEF,KAAK;oBACa,OAAO,CAAC,UAAU,EAAE,CAAC;uBAIhB,MAAM;;kBAzLiB,MAAM;uBAAa,OAAO;iBAAO,MAAM,GAAG,IAAI;0BAAgB,MAAM,GAAG,IAAI;;yBA8LhG,MAAM;kBA7LiB,MAAM;gBAAM,OAAO;;oBAiMrD,MAAM,KAAG,MAAM,GAAG,SAAS;MACvC;IAEF,KAAK,CAAC,OAAO,GAAE;QAAE,SAAS,CAAC,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAA;KAAO;;;;;;;;;mCAavC,MAAM,SAAS,iBAAiB;;;gCAChC,MAAM,SAAS,UAAU,CAAC,aAAa,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC;;;iCACpD,OAAO;;;iCACN,GAAG;;;kCACH,OAAO;0BA7FO,MAAM;0BAAQ,MAAM;;;;kCA8FpC,OAAO;0BA9FS,MAAM;0BAAQ,MAAM;;;;iCA+FjC,GAAG;;;iCACP,OAAO;;;mCACC,MAAM,SAAS,iBAAiB;;;iCACnC,MAAM,GAAG;oBAAE,GAAG,EAAE,MAAM,CAAA;iBAAE;wBA9NlB,OAAO;yBAAO,MAAM;;;;iCA+NjC,MAAM,GAAG;oBAAE,GAAG,EAAE,MAAM,CAAC;oBAAC,KAAK,CAAC,EAAE,MAAM,CAAC;oBAAC,KAAK,CAAC,EAAE,MAAM,CAAA;iBAAE;;;iCAElD,MAAM,GAAG;oBAAE,IAAI,EAAE,MAAM,CAAA;iBAAE;;0BA9NhB,MAAM;+BAAa,OAAO;yBAAO,MAAM,GAAG,IAAI;kCAAgB,MAAM,GAAG,IAAI;;;;iCA+NlF,MAAM,GAAG;oBAAE,IAAI,EAAE,MAAM,CAAA;iBAAE;0BA9NhB,MAAM;wBAAM,OAAO;;;;;;;gCAgO3B,WAAW;;;;+BAtOV,oBAAoB,EAAE;+BAAa,sBAAsB,EAAE;;;;;IA4OpG,YAAY,IAAI,MAAM,EAAE;IAoBxB,OAAO,CAAC,WAAW;IAOnB,OAAO,CAAC,oBAAoB;IAgB5B,OAAO,CAAC,OAAO;CAUhB"}
+{"version":3,"file":"sandbox.d.ts","sourceRoot":"","sources":["../src/sandbox.ts"],"names":[],"mappings":"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"}

package/dist/sandbox.js

@@ -1,8 +1,19 @@
 /**
  * @nimbus-sh/sdk/sandbox - programmatic Nimbus sandbox handle.
  */
+export class NimbusRemoteError extends Error {
+    status;
+    code;
+    body;
+    constructor(message, options) {
+        super(message);
+        this.name = 'NimbusRemoteError';
+        this.status = options.status;
+        this.code = options.code;
+        this.body = options.body;
+    }
+}
 export class Nimbus {
-    namespace;
     config;
     static fromEnv(env, config = {}, options = {}) {
         const bindingName = options.binding ?? 'NIMBUS_SESSION';
@@ -10,38 +21,62 @@ export class Nimbus {
         if (!binding) {
             throw new Error(`Nimbus.fromEnv: env.${bindingName} Durable Object binding is missing`);
         }
-        return new Nimbus(binding, {
+        return new Nimbus({ kind: 'binding', namespace: binding }, {
             ...config,
             endpoint: options.endpoint ?? config.endpoint,
         });
     }
-    constructor(namespace, config = {}) {
-        this.namespace = namespace;
+    static connect(options) {
+        if (!options.endpoint) {
+            throw new Error('Nimbus.connect: endpoint is required');
+        }
+        const fetchImpl = options.fetch ?? globalThis.fetch?.bind(globalThis);
+        if (typeof fetchImpl !== 'function') {
+            throw new Error('Nimbus.connect: fetch is unavailable; pass a custom fetch implementation');
+        }
+        const config = {
+            ...(options.config ?? {}),
+            endpoint: options.endpoint,
+        };
+        return new Nimbus({
+            kind: 'remote',
+            endpoint: trimTrailingSlashes(options.endpoint),
+            basePath: normalizeBasePath(options.basePath ?? '/api/nimbus/v1'),
+            token: options.token,
+            headers: options.headers,
+            fetch: fetchImpl,
+        }, config);
+    }
+    target;
+    constructor(target, config = {}) {
         this.config = config;
+        this.target = isNimbusTarget(target)
+            ? target
+            : { kind: 'binding', namespace: target };
     }
     sandbox(id, options = {}) {
-        return new NimbusSandbox(this.namespace, String(id), options, this.config);
+        return new NimbusSandbox(this.target, String(id), options, this.config);
     }
 }
 export class NimbusSandbox {
-    namespace;
+    target;
     options;
     config;
     id;
     profileName;
     profile;
     readyPromise = null;
-    constructor(namespace, id, options, config) {
-        this.namespace = namespace;
+    constructor(target, id, options, config) {
+        this.target = target;
         this.options = options;
         this.config = config;
-        this.id = id;
+        this.id = idComponent(id, 'sandbox id');
         this.profileName = options.profile ?? 'default';
         this.profile = config.sandboxes?.[this.profileName] ?? config.sandboxes?.default ?? {};
     }
     get tenantSegment() {
-        const tenant = sanitizeSegment(this.options.tenant ?? 'default');
-        const subject = sanitizeSegment(this.options.subject ?? '_');
+        const tenant = idComponent(this.options.tenant ?? 'default', 'tenant');
+        const subject = idComponent(this.options.subject ?? '_', 'subject');
         return `${tenant}:${subject}`;
     }
     get doName() {
@@ -51,10 +86,81 @@ export class NimbusSandbox {
         return this.options.root ?? this.profile.root ?? '/home/user';
     }
     stub() {
-        const namespace = this.namespace;
+        if (this.target.kind === 'remote')
+            return this.remoteStub();
+        const namespace = this.target.namespace;
         const id = namespace.idFromName(this.doName);
         return namespace.get(id);
     }
+    remoteStub() {
+        return {
+            _rpcReady: (options) => this.remoteRpc('ready', [options]),
+            _rpcExec: (command, options) => this.remoteRpc('exec', [command, options]),
+            _rpcStartProcess: (command, options) => this.remoteRpc('startProcess', [command, options]),
+            _rpcRunCode: (code, options) => this.remoteRpc('runCode', [code, options]),
+            _rpcReadFile: (path) => this.remoteRpc('readFile', [path]),
+            _rpcReadFileBytes: (path) => this.remoteRpc('readFileBytes', [path]),
+            _rpcWriteFile: (path, content) => this.remoteRpc('writeFile', [path, content]),
+            _rpcReaddir: (path) => this.remoteRpc('readdir', [path]),
+            _rpcExists: (path) => this.remoteRpc('exists', [path]),
+            _rpcMkdir: (path) => this.remoteRpc('mkdir', [path]),
+            _rpcDeleteFile: (path, options) => this.remoteRpc('deleteFile', [path, options]),
+            _rpcInstallRuntime: (spec, options) => this.remoteRpc('installRuntime', [spec, options]),
+            _rpcEnsureRuntimes: (specs, options) => this.remoteRpc('ensureRuntimes', [specs, options]),
+            _rpcListRuntimes: () => this.remoteRpc('listRuntimes', []),
+            _rpcListProcesses: () => this.remoteRpc('listProcesses', []),
+            _rpcKillProcess: (pid) => this.remoteRpc('killProcess', [pid]),
+            _rpcProcessLogs: (pid, options) => this.remoteRpc('processLogs', [pid, options]),
+            _rpcListPorts: () => this.remoteRpc('listPorts', []),
+            _rpcExposePort: (port) => this.remoteRpc('exposePort', [port]),
+            _rpcUnexposePort: (port) => this.remoteRpc('unexposePort', [port]),
+        };
+    }
+    async remoteRpc(op, args) {
+        if (this.target.kind !== 'remote') {
+            throw new Error('Nimbus internal error: remoteRpc called on non-remote target');
+        }
+        const headers = new Headers(await resolveHeaders(this.target.headers));
+        headers.set('Accept', 'application/json');
+        headers.set('Content-Type', 'application/json');
+        if (this.target.token && !headers.has('Authorization')) {
+            headers.set('Authorization', `Bearer ${this.target.token}`);
+        }
+        const response = await this.target.fetch(`${this.target.endpoint}${this.target.basePath}/sandboxes/${encodeURIComponent(this.id)}/rpc`, {
+            method: 'POST',
+            headers,
+            body: JSON.stringify(encodeWire({
+                profile: this.profileName,
+                tenant: this.options.tenant,
+                subject: this.options.subject,
+                root: this.root,
+                op,
+                args,
+            })),
+        });
+        const text = await response.text();
+        let payload = null;
+        if (text) {
+            try {
+                payload = JSON.parse(text);
+            }
+            catch {
+                throw new NimbusRemoteError(`Nimbus remote API returned non-JSON response (${response.status})`, {
+                    status: response.status,
+                    body: text,
+                });
+            }
+        }
+        if (!response.ok || payload?.ok !== true) {
+            const message = payload?.error ?? payload?.message ?? `Nimbus remote API request failed (${response.status})`;
+            throw new NimbusRemoteError(message, {
+                status: response.status,
+                code: payload?.code,
+                body: payload,
+            });
+        }
+        return decodeWire(payload.result);
+    }
     async ready() {
         if (!this.readyPromise) {
             const preinstall = this.profile.runtimes?.preinstall ?? [];
@@ -245,15 +351,125 @@ export class NimbusSandbox {
     portUrl(port) {
         const explicit = this.profile.preview?.baseUrl;
         if (explicit) {
-            const base = explicit.replace('{sessionId}', encodeURIComponent(this.id)).replace(/\/+$/, '');
+            const base = trimTrailingSlashes(explicit.replace('{sessionId}', encodeURIComponent(this.id)));
             return `${base}/port/${port}/`;
         }
-        const endpoint = this.config.endpoint?.replace(/\/+$/, '');
+        const endpoint = this.config.endpoint ? trimTrailingSlashes(this.config.endpoint) : '';
         if (!endpoint)
             return undefined;
         return `${endpoint}/s/${encodeURIComponent(this.id)}/port/${port}/`;
     }
 }
-function sanitizeSegment(value) {
-    return String(value).replace(/[^A-Za-z0-9_.:-]/g, '_') || '_';
+function idComponent(value, field) {
+    const text = String(value);
+    if (!isIdComponent(text)) {
+        throw new Error(`Nimbus ${field} must be 1-128 ASCII letters, digits, dot, underscore, or hyphen`);
+    }
+    return text;
+}
+function isIdComponent(value) {
+    if (value.length < 1 || value.length > 128)
+        return false;
+    for (let i = 0; i < value.length; i++) {
+        const code = value.charCodeAt(i);
+        const isDigit = code >= 48 && code <= 57;
+        const isUpper = code >= 65 && code <= 90;
+        const isLower = code >= 97 && code <= 122;
+        const isPunctuation = code === 45 || code === 46 || code === 95;
+        if (!isDigit && !isUpper && !isLower && !isPunctuation)
+            return false;
+    }
+    return true;
+}
+function isNimbusTarget(value) {
+    return !!value && typeof value === 'object' && 'kind' in value;
+}
+function normalizeBasePath(path) {
+    const trimmed = trimSlashes(String(path || '/api/nimbus/v1'));
+    return `/${trimmed}`;
+}
+function trimSlashes(value) {
+    let start = 0;
+    let end = value.length;
+    while (start < end && value[start] === '/')
+        start++;
+    while (end > start && value[end - 1] === '/')
+        end--;
+    return value.slice(start, end);
+}
+function trimTrailingSlashes(value) {
+    let end = value.length;
+    while (end > 0 && value[end - 1] === '/')
+        end--;
+    return value.slice(0, end);
+}
+async function resolveHeaders(input) {
+    if (!input)
+        return undefined;
+    return typeof input === 'function' ? await input() : input;
+}
+function encodeWire(value) {
+    if (value instanceof Uint8Array) {
+        return {
+            __nimbusWireType: 'bytes',
+            base64: bytesToBase64(value),
+        };
+    }
+    if (value instanceof ArrayBuffer) {
+        return {
+            __nimbusWireType: 'bytes',
+            base64: bytesToBase64(new Uint8Array(value)),
+        };
+    }
+    if (ArrayBuffer.isView(value)) {
+        const view = value;
+        return {
+            __nimbusWireType: 'bytes',
+            base64: bytesToBase64(new Uint8Array(view.buffer, view.byteOffset, view.byteLength)),
+        };
+    }
+    if (Array.isArray(value))
+        return value.map(encodeWire);
+    if (value && typeof value === 'object') {
+        const out = {};
+        for (const [key, item] of Object.entries(value)) {
+            if (item !== undefined)
+                out[key] = encodeWire(item);
+        }
+        return out;
+    }
+    return value;
+}
+function decodeWire(value) {
+    if (value
+        && typeof value === 'object'
+        && value.__nimbusWireType === 'bytes'
+        && typeof value.base64 === 'string') {
+        return base64ToBytes(value.base64);
+    }
+    if (Array.isArray(value))
+        return value.map(decodeWire);
+    if (value && typeof value === 'object') {
+        const out = {};
+        for (const [key, item] of Object.entries(value)) {
+            out[key] = decodeWire(item);
+        }
+        return out;
+    }
+    return value;
+}
+function bytesToBase64(bytes) {
+    let binary = '';
+    const chunk = 0x8000;
+    for (let i = 0; i < bytes.length; i += chunk) {
+        binary += String.fromCharCode(...bytes.subarray(i, i + chunk));
+    }
+    return btoa(binary);
+}
+function base64ToBytes(base64) {
+    const binary = atob(base64);
+    const bytes = new Uint8Array(binary.length);
+    for (let i = 0; i < binary.length; i++)
+        bytes[i] = binary.charCodeAt(i);
+    return bytes;
 }

package/dist/session.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"session.d.ts","sourceRoot":"","sources":["../src/session.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAoB,KAAK,aAAa,EAAE,MAAM,wBAAwB,CAAC;AAC9E,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAEhE;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,gBAAgB,CAC9B,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,MAAM,GACZ,MAAM,CAGR;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAsB,aAAa,CACjC,GAAG,EAAE,aAAa,EAClB,KAAK,EAAE;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAAC,GAAG,CAAC,EAAE,MAAM,CAAA;CAAE,EACpE,IAAI,EAAE,iBAAiB,GAAG;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,GAChE,OAAO,CAAC;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,CAAC,CAIzC"}
+{"version":3,"file":"session.d.ts","sourceRoot":"","sources":["../src/session.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAoB,KAAK,aAAa,EAAE,MAAM,wBAAwB,CAAC;AAC9E,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAEhE;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,gBAAgB,CAC9B,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,MAAM,GACZ,MAAM,CAIR;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAsB,aAAa,CACjC,GAAG,EAAE,aAAa,EAClB,KAAK,EAAE;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAAC,GAAG,CAAC,EAAE,MAAM,CAAA;CAAE,EACpE,IAAI,EAAE,iBAAiB,GAAG;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,GAChE,OAAO,CAAC;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,CAAC,CAIzC"}

package/dist/session.js

@@ -26,8 +26,9 @@ import { issueNimbusToken } from '@nimbus-sh/worker/auth';
  * ```
  */
 export function sessionAttachUrl(endpoint, sessionId, token) {
-    const base = endpoint.replace(/\/+$/, '');
-    return `${base}/s/${sessionId}/?nimbus_token=${encodeURIComponent(token)}`;
+    const url = new URL(`/s/${encodeURIComponent(sessionId)}/`, endpoint);
+    url.searchParams.set('nimbus_token', token);
+    return url.toString();
 }
 /**
  * Convenience: mint a token AND build the attach URL in one call.

package/dist/token.d.ts

@@ -5,10 +5,9 @@
  * Why a re-export and not a copy? The auth module is the single source
  * of truth — both Worker (verify) and SDK (mint) call the same code
  * paths so wire-format drift is structurally impossible. The
- * `@nimbus-sh/worker` peer-dependency is OPTIONAL (declared in
- * package.json#peerDependenciesMeta); consumers who only mint tokens
- * outside a Worker can install just `@nimbus-sh/sdk` and the
- * worker peer-dep is tree-shaken to its auth subpath.
+ * `@nimbus-sh/worker` provides the shared auth implementation. The SDK
+ * package depends on that single source of truth so token wire-format
+ * drift is structurally impossible.
  *
  * @example mint
  * ```ts

package/dist/token.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"token.d.ts","sourceRoot":"","sources":["../src/token.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,OAAO,EACL,gBAAgB,EAChB,iBAAiB,EACjB,KAAK,aAAa,GACnB,MAAM,wBAAwB,CAAC;AAEhC,OAAO,EACL,oBAAoB,EACpB,gBAAgB,EAChB,eAAe,EACf,KAAK,iBAAiB,EACtB,KAAK,mBAAmB,EACxB,KAAK,iBAAiB,GACvB,MAAM,wBAAwB,CAAC"}
+{"version":3,"file":"token.d.ts","sourceRoot":"","sources":["../src/token.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,OAAO,EACL,gBAAgB,EAChB,iBAAiB,EACjB,KAAK,aAAa,GACnB,MAAM,wBAAwB,CAAC;AAEhC,OAAO,EACL,oBAAoB,EACpB,gBAAgB,EAChB,eAAe,EACf,KAAK,iBAAiB,EACtB,KAAK,mBAAmB,EACxB,KAAK,iBAAiB,GACvB,MAAM,wBAAwB,CAAC"}

package/dist/token.js

@@ -5,10 +5,9 @@
  * Why a re-export and not a copy? The auth module is the single source
  * of truth — both Worker (verify) and SDK (mint) call the same code
  * paths so wire-format drift is structurally impossible. The
- * `@nimbus-sh/worker` peer-dependency is OPTIONAL (declared in
- * package.json#peerDependenciesMeta); consumers who only mint tokens
- * outside a Worker can install just `@nimbus-sh/sdk` and the
- * worker peer-dep is tree-shaken to its auth subpath.
+ * `@nimbus-sh/worker` provides the shared auth implementation. The SDK
+ * package depends on that single source of truth so token wire-format
+ * drift is structurally impossible.
  *
  * @example mint
  * ```ts

package/dist/worker.d.ts

@@ -0,0 +1,11 @@
+/**
+ * @nimbus-sh/sdk/worker - Cloudflare Worker embedder surface.
+ *
+ * This is the public entrypoint for deploying Nimbus itself inside a
+ * Worker. The implementation is provided by @nimbus-sh/worker, but apps
+ * should import through the SDK so the interactive app and programmatic
+ * sandbox APIs share one public package surface.
+ */
+export { NimbusSession, SupervisorRPC, NimbusAssetsRPC, NimbusLoaderRPC, NimbusLoadedWorker, NimbusLoadedEntrypoint, NimbusDurableObjectNamespace, NimbusDOStub, CirrusHmrRPC, createNimbusHandler, issueNimbusToken, verifyNimbusToken, NimbusAuthError, } from '@nimbus-sh/worker';
+export type { NimbusHandler, NimbusHooks, NimbusHookContext, CustomRoutes, CreateNimbusHandlerOptions, NimbusRemoteApiConfig, NimbusRuntimePolicy, NimbusSandboxProfile, NimbusSdkConfig, NimbusSdkRouterConfig, AuthMode, NimbusAuthConfig, NimbusAuthEnv, NimbusTokenClaims, VerifiedNimbusToken, } from '@nimbus-sh/worker';
+//# sourceMappingURL=worker.d.ts.map

package/dist/worker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"worker.d.ts","sourceRoot":"","sources":["../src/worker.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EACL,aAAa,EACb,aAAa,EACb,eAAe,EACf,eAAe,EACf,kBAAkB,EAClB,sBAAsB,EACtB,4BAA4B,EAC5B,YAAY,EACZ,YAAY,EACZ,mBAAmB,EACnB,gBAAgB,EAChB,iBAAiB,EACjB,eAAe,GAChB,MAAM,mBAAmB,CAAC;AAE3B,YAAY,EACV,aAAa,EACb,WAAW,EACX,iBAAiB,EACjB,YAAY,EACZ,0BAA0B,EAC1B,qBAAqB,EACrB,mBAAmB,EACnB,oBAAoB,EACpB,eAAe,EACf,qBAAqB,EACrB,QAAQ,EACR,gBAAgB,EAChB,aAAa,EACb,iBAAiB,EACjB,mBAAmB,GACpB,MAAM,mBAAmB,CAAC"}

package/dist/worker.js

@@ -0,0 +1,9 @@
+/**
+ * @nimbus-sh/sdk/worker - Cloudflare Worker embedder surface.
+ *
+ * This is the public entrypoint for deploying Nimbus itself inside a
+ * Worker. The implementation is provided by @nimbus-sh/worker, but apps
+ * should import through the SDK so the interactive app and programmatic
+ * sandbox APIs share one public package surface.
+ */
+export { NimbusSession, SupervisorRPC, NimbusAssetsRPC, NimbusLoaderRPC, NimbusLoadedWorker, NimbusLoadedEntrypoint, NimbusDurableObjectNamespace, NimbusDOStub, CirrusHmrRPC, createNimbusHandler, issueNimbusToken, verifyNimbusToken, NimbusAuthError, } from '@nimbus-sh/worker';

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@nimbus-sh/sdk",
-  "version": "0.1.0",
-  "description": "Nimbus SDK — programmatic sandboxes, token mint, types, and Worker client helpers.",
+  "version": "0.1.2",
+  "description": "Nimbus SDK — Worker embedder, programmatic sandboxes, token mint, and client helpers.",
   "homepage": "https://github.com/AshishKumar4/Nimbus",
   "repository": {
     "type": "git",
@@ -35,6 +35,11 @@
       "types": "./dist/sandbox.d.ts",
       "import": "./dist/sandbox.js"
     },
+    "./worker": {
+      "workspace": "./src/worker.ts",
+      "types": "./dist/worker.d.ts",
+      "import": "./dist/worker.js"
+    },
     "./errors": {
       "workspace": "./src/errors.ts",
       "types": "./dist/errors.d.ts",
@@ -52,14 +57,11 @@
     "typecheck": "tsc --noEmit"
   },
   "peerDependencies": {
-    "@nimbus-sh/worker": "^0.1.0"
-  },
-  "peerDependenciesMeta": {
-    "@nimbus-sh/worker": { "optional": true }
+    "@nimbus-sh/worker": "^0.1.2"
   },
   "devDependencies": {
     "@cloudflare/workers-types": "^4.20250327.0",
-    "@nimbus-sh/worker": "^0.1.0",
+    "@nimbus-sh/worker": "^0.1.2",
     "typescript": "^5.7.0"
   },
   "publishConfig": {