@north-light/sdk 0.3.557 → 0.3.559

package/dist/oauth/index.d.ts

@@ -1,5 +1,6 @@
 import { type JWK } from 'jose';
 import { type IdTokenClaims } from '@north-light/identity';
+import { type ExecRunDTO } from '@north-light/api';
 import { type AppClient, type CrouterOptions } from '../client.js';
 import { RunWatcher, type RunWatchOptions } from '../resources/run-watcher.js';
 import { GrantWatcher, type GrantWatchOptions } from '../resources/grant-watcher.js';
@@ -118,6 +119,12 @@ export declare class ConnectedCrouter extends AppCrouter {
     /** The person's runtime URL this client calls, as the stored connection named it. */
     readonly runtimeUrl: string;
     constructor(connection: Pick<Connection, 'userId' | 'runtimeUrl'>, options: Pick<CrouterOptions, 'tokenSource' | 'onUnauthorized' | 'fetch'>);
+    /** Run `crtr <argv…>` in this app's sandbox on the person's runtime (`POST /v1/exec`, scopes `crtr:act` and `crtr:schedule`).
+     *  No shell and no stdin; the process starts in the app's files folder. A non-zero exit or a timeout resolves; a refusal
+     *  throws `APIError` (`busy` 429 past 4 live execs for this app, `sandbox_unavailable` 503 on a runtime without a root launcher). */
+    exec(argv: string[], options?: {
+        timeoutS?: number;
+    }): Promise<ExecRunDTO>;
 }
 /** The default deadline of one directory operation (`OAuth2Options.timeoutMs`): a discovery read is forgotten when it passes. */
 export declare const DEFAULT_DIRECTORY_TIMEOUT_MS = 10000;

package/dist/oauth/index.js

@@ -1,6 +1,6 @@
 import { calculateJwkThumbprint, decodeJwt, decodeProtectedHeader, exportJWK, importJWK, importPKCS8, SignJWT } from 'jose';
 import { boundedFetch, FetchDeadlineError, JwksCache, parseScope, verifyIdToken } from '@north-light/identity';
-import { deadlineExceeded, sleepWithin } from '@north-light/api';
+import { deadlineExceeded, routes, sleepWithin } from '@north-light/api';
 import { APIError, CrouterError, NoHostedRuntimeError, NotGrantedError, mapError } from '../errors.js';
 import { Crouter } from '../client.js';
 import { withinDeadline } from '../resources/request.js';
@@ -94,6 +94,13 @@ export class ConnectedCrouter extends AppCrouter {
         Object.defineProperty(this, 'customObjects', { value: { register: customObjects.register.bind(customObjects), publish: customObjects.publish.bind(customObjects), unregister: customObjects.unregister.bind(customObjects) } });
         Object.defineProperty(this, 'canvas', { value: { watch: canvas.watch.bind(canvas), unwatch: canvas.unwatch.bind(canvas) } });
     }
+    /** Run `crtr <argv…>` in this app's sandbox on the person's runtime (`POST /v1/exec`, scopes `crtr:act` and `crtr:schedule`).
+     *  No shell and no stdin; the process starts in the app's files folder. A non-zero exit or a timeout resolves; a refusal
+     *  throws `APIError` (`busy` 429 past 4 live execs for this app, `sandbox_unavailable` 503 on a runtime without a root launcher). */
+    exec(argv, options) {
+        const timeoutS = options?.timeoutS ?? 60;
+        return this.request('POST', routes.exec(), { argv, ...(options?.timeoutS === undefined ? {} : { timeout_s: options.timeoutS }) }, { timeout: timeoutS * 1000 + 15_000 });
+    }
 }
 /** The default deadline of one directory operation (`OAuth2Options.timeoutMs`): a discovery read is forgotten when it passes. */
 export const DEFAULT_DIRECTORY_TIMEOUT_MS = 10_000;

package/dist/skill/northlight/SKILL.md

@@ -2,7 +2,7 @@
 name: northlight
 description: "Use when building, debugging or shipping an app that signs people in with Northlight, starts runs on their Northlight runtime, or calls Northlight providers (sms, search, integrations, context, device) with @north-light/sdk."
 metadata:
-  sdk-version: "0.3.557"
+  sdk-version: "0.3.559"
 ---
 
 # Building a Northlight app
@@ -27,7 +27,7 @@ Never text a person first: Comms refuses a send to anyone who has not texted you
 
 ## First: check this skill matches the SDK
 
-This skill is for SDK version `0.3.557`. If the project has `node_modules/@north-light/sdk/package.json`, compare its `version` with that number. If they differ, run `npx @north-light/sdk skill` in the project, then read the rewritten `.agents/skills/northlight/SKILL.md` (or `.claude/skills/northlight/SKILL.md`) instead of this copy. It needs no account. A project that has no SDK yet starts with `npx @north-light/sdk@latest init <dir>`.
+This skill is for SDK version `0.3.559`. If the project has `node_modules/@north-light/sdk/package.json`, compare its `version` with that number. If they differ, run `npx @north-light/sdk skill` in the project, then read the rewritten `.agents/skills/northlight/SKILL.md` (or `.claude/skills/northlight/SKILL.md`) instead of this copy. It needs no account. A project that has no SDK yet starts with `npx @north-light/sdk@latest init <dir>`.
 
 ## Where things run
 

package/dist/testing/cloud.d.ts

@@ -1,4 +1,4 @@
-import type { ProviderDependency } from '@north-light/api';
+import type { ExecRunDTO, ProviderDependency } from '@north-light/api';
 import { Crouter } from '../client.js';
 import { type ConnectionStore } from '../oauth/index.js';
 import { type FakeNotice, type RunNoticeOptions } from './notices.js';
@@ -7,7 +7,7 @@ import { type SpaceOp } from './space.js';
 import { type FakeRefusalCode, type FakeScope, type FakeUser, type Responder } from './users.js';
 import { type FakeError } from './wire.js';
 /** A runtime operation, named as the daemon's `OPERATIONS` table names it. */
-export type FakeOp = 'grant.get' | 'run.start' | 'run.list' | 'run.get' | 'run.message' | 'run.events' | 'run.interrupt' | 'run.cancel' | 'run.delete' | 'run.rename' | 'question.get' | 'question.answer' | 'question.cancel' | 'trace.get' | 'memory.list' | 'memory.get' | 'provider.tools' | 'provider.call' | 'profile.list' | SpaceOp;
+export type FakeOp = 'grant.get' | 'run.start' | 'run.list' | 'run.get' | 'run.message' | 'run.events' | 'run.interrupt' | 'run.cancel' | 'run.delete' | 'run.rename' | 'question.get' | 'question.answer' | 'question.cancel' | 'trace.get' | 'memory.list' | 'memory.get' | 'provider.tools' | 'provider.call' | 'profile.list' | 'exec' | SpaceOp;
 /** A directory operation. */
 export type FakeDirectoryOp = 'directory.discovery' | 'directory.token' | 'directory.jwks';
 /** What `intercept` / `failNext` / `gate` match: a runtime operation, `'*'` (every runtime operation), or a directory operation. */
@@ -53,6 +53,14 @@ export type FakeToolHandler = (input: {
     arguments: Record<string, unknown>;
     signal: AbortSignal | null;
 }) => unknown;
+/** What `exec.respond` installs: the answer to one `POST /v1/exec`. Fields left out default to a clean exit with empty
+ *  output. Throw `FakeCloud.error(...)` for a refusal (e.g. 409 `model_sign_in_required` with `details: { url }`). */
+export type FakeExecHandler = (input: {
+    userId: string;
+    argv: string[];
+    timeoutS: number;
+    signal: AbortSignal | null;
+}) => Partial<ExecRunDTO> | Promise<Partial<ExecRunDTO>>;
 /** `providers.define` input. */
 export interface FakeProvider {
     displayName?: string;
@@ -95,7 +103,8 @@ export interface FakeCloudOptions {
      * Whether the runtime can start an `isolated: true` run. `available` (default) models a Northlight guest, where
      * the Linux root launcher always exists: the run starts, `run.params.isolated` is true, and a `cwd` outside the run's
      * root folder (`/apps/<clientId>/nodes/<run id>`) is 400 `invalid_request` `param: cwd`. `unavailable` models a
-     * runtime without the launcher (a developer's Mac): every isolated start is 503 `isolated_unavailable`, retryable.
+     * runtime without the launcher (a developer's Mac): every isolated start is 503 `isolated_unavailable`, retryable, and
+     * every `exec` is 503 `sandbox_unavailable`, not retryable.
      */
     isolatedRuns?: 'available' | 'unavailable';
     /**
@@ -172,12 +181,24 @@ export declare class FakeCloud {
     readonly providers: {
         define(provider: string, definition: FakeProvider): void;
     };
+    /** `POST /v1/exec`: `respond` sets how every exec answers; `calls` is every accepted exec, oldest first. Unset, an exec exits 0 with empty output. */
+    readonly exec: {
+        respond(handler: FakeExecHandler | null): void;
+        readonly calls: readonly {
+            userId: string;
+            argv: string[];
+            timeoutS: number;
+        }[];
+    };
     private readonly options;
     private readonly clock;
     private readonly users;
     private readonly handles;
     private readonly allRuns;
     private readonly providerDefs;
+    private execHandler;
+    private readonly execCalls;
+    private liveExecs;
     private intercepts;
     private readonly gates;
     private responder;
@@ -306,5 +327,6 @@ export declare class FakeCloud {
     private memoryList;
     private providerEntry;
     private providerTools;
+    private execCall;
     private providerCall;
 }

package/dist/testing/cloud.js

@@ -36,6 +36,7 @@ const ROUTES = [
     ['GET', /^\/v1\/providers\/([^/]+)\/tools$/, 'provider.tools'],
     ['POST', /^\/v1\/provider\/call$/, 'provider.call'],
     ['GET', /^\/v1\/profiles$/, 'profile.list'],
+    ['POST', /^\/v1\/exec$/, 'exec'],
     ['POST', /^\/v1\/schemas$/, 'schema.register'],
     ['POST', /^\/v1\/relations$/, 'relations.write'],
     ['PUT', /^\/v1\/relations$/, 'relations.replace'],
@@ -50,7 +51,9 @@ const ROUTES = [
 ];
 const DIRECTORY_OPS = new Set(['directory.discovery', 'directory.token', 'directory.jwks']);
 const RUN_OPS = new Set(['run.get', 'run.delete', 'run.message', 'run.events', 'run.interrupt', 'run.cancel', 'run.rename', 'trace.get']);
-const ACT_OPS = new Set(['run.start', 'run.message']);
+const ACT_OPS = new Set(['run.start', 'run.message', 'exec']);
+/** The runtime's live exec processes per app (`handlers/exec.ts`); one more is 429 `busy`. */
+const MAX_LIVE_EXECS = 4;
 /** The served memory body cap (`MEMORY_BODY_MAX_BYTES`, src/daemon/api/handlers/memory.ts). */
 const MEMORY_BODY_MAX_BYTES = 1024 * 1024;
 const MEMORY_NAME = /^[A-Za-z0-9_-]+(\/[A-Za-z0-9_-]+)*$/;
@@ -87,12 +90,17 @@ export class FakeCloud {
     /** Testing mode for this cloud's app. */
     testing;
     providers;
+    /** `POST /v1/exec`: `respond` sets how every exec answers; `calls` is every accepted exec, oldest first. Unset, an exec exits 0 with empty output. */
+    exec;
     options;
     clock;
     users = new Map();
     handles = new Map();
     allRuns = [];
     providerDefs = new Map();
+    execHandler = null;
+    execCalls = [];
+    liveExecs = 0;
     intercepts = [];
     gates = new Set();
     responder = null;
@@ -145,6 +153,8 @@ export class FakeCloud {
                     throw new TypeError(`invalid provider id ${provider}`);
                 this.providerDefs.set(provider, definition);
             } };
+        const execCalls = this.execCalls;
+        this.exec = { respond: (handler) => { this.execHandler = handler; }, get calls() { return execCalls; } };
         const cloud = this;
         this.testing = {
             get active() { return cloud.inTesting; },
@@ -820,6 +830,7 @@ export class FakeCloud {
             }
             case 'provider.tools': return this.providerTools(user, id);
             case 'provider.call': return this.providerCall(user, body, signal);
+            case 'exec': return this.execCall(user, body, signal);
             case 'profile.list': return { status: 200, body: { profiles: [{ profile_id: 'default', name: 'default', grantee: this.host.grantee, default_kind: 'general', default: true }] } };
             default:
                 if (SPACE_OPS.has(op))
@@ -1068,6 +1079,36 @@ export class FakeCloud {
         }
         return { status: 200, body: { providers: visible } };
     }
+    async execCall(user, body, signal) {
+        if (!user.scopeStrings().some((scope) => covers(scope, 'crtr:schedule')))
+            throw refuse(403, 'scope_missing', 'missing scope crtr:schedule', { scope: 'crtr:schedule' });
+        const params = objectBody(body);
+        const argv = params['argv'];
+        if (!Array.isArray(argv) || argv.length === 0 || !argv.every((arg) => typeof arg === 'string'))
+            throw invalid('argv must be a non-empty array of strings', 'argv');
+        if (Buffer.byteLength(JSON.stringify(argv)) >= 32 * 1024)
+            throw invalid('argv must be less than 32 KB as JSON', 'argv');
+        const timeoutS = params['timeout_s'] ?? 60;
+        if (typeof timeoutS !== 'number' || !Number.isFinite(timeoutS) || timeoutS <= 0 || timeoutS > 100)
+            throw invalid('timeout_s must be greater than 0 and at most 100', 'timeout_s');
+        if (this.options.isolatedRuns === 'unavailable')
+            throw refuse(503, 'sandbox_unavailable', 'this runtime has no root launcher, so it cannot sandbox an app process', { retryable: false });
+        // One app per cloud, so the runtime's per-app count is the cloud's.
+        if (this.liveExecs >= MAX_LIVE_EXECS)
+            throw refuse(429, 'busy', `${this.host.grantee} already has ${MAX_LIVE_EXECS} exec processes running; retry when one finishes`, { retryable: true });
+        this.liveExecs++;
+        const started = this.clock.now();
+        try {
+            this.execCalls.push({ userId: user.id, argv, timeoutS });
+            // Raced with the request's signal: an abort frees the slot even when the handler never settles, as the runtime's killed process does.
+            const answer = this.execHandler === null ? {} : await withSignal(Promise.resolve(this.execHandler({ userId: user.id, argv, timeoutS, signal })), signal);
+            return { status: 200, body: { exit_code: 0, signal: null, stdout: '', stdout_truncated: false, stderr: '', stderr_truncated: false, timed_out: false,
+                    duration_ms: this.clock.now() - started, ...answer } };
+        }
+        finally {
+            this.liveExecs--;
+        }
+    }
     async providerCall(user, body, signal) {
         const params = objectBody(body);
         const provider = params['provider'];

package/dist/testing/index.d.ts

@@ -1,7 +1,7 @@
 export { FakeCloud, FAKE_TESTER_LIMIT } from './cloud.js';
 export { manualClock } from './clock.js';
 export type { ManualClock } from './clock.js';
-export type { FakeAnswer, FakeCall, FakeCloudOptions, FakeDirectoryCall, FakeDirectoryOp, FakeInterceptOp, FakeOp, FakeProvider, FakeRuns, FakeTester, FakeTesterRef, FakeTesting, FakeToolHandler, Intercept, } from './cloud.js';
+export type { FakeAnswer, FakeCall, FakeCloudOptions, FakeDirectoryCall, FakeDirectoryOp, FakeExecHandler, FakeInterceptOp, FakeOp, FakeProvider, FakeRuns, FakeTester, FakeTesterRef, FakeTesting, FakeToolHandler, Intercept, } from './cloud.js';
 export type { FakeRun, FakeRunEnding, FakeRunMessage, FakeRunParams, FakeQuestion } from './run.js';
 export type { FakeNotice, RunNoticeOptions } from './notices.js';
 export type { FakeAccount, FakeMemoryDoc, FakeRefusalCode, FakeScope, FakeUser, GrantPatch, Responder, ResponderInput } from './users.js';

package/dist/version.d.ts

@@ -1,5 +1,5 @@
 /** This SDK's release version. Informational only: compatibility is the contract level, not this number. */
-export declare const SDK_VERSION = "0.3.557";
+export declare const SDK_VERSION = "0.3.559";
 /** The release sent in `Crouter-Minimum-Runtime-Version` on every request. It is frozen, so a runtime from before the
  *  contract level existed (which only knows this header) refuses this SDK, while every later runtime accepts it. */
 export declare const LEGACY_FLOOR = "0.3.423";

package/dist/version.js

@@ -1,6 +1,6 @@
 // SDK_VERSION is written by scripts/release-version.mjs on every release; do not edit by hand.
 /** This SDK's release version. Informational only: compatibility is the contract level, not this number. */
-export const SDK_VERSION = '0.3.557';
+export const SDK_VERSION = '0.3.559';
 // LEGACY_FLOOR is written once by `scripts/contract.mjs release`, at the first release that carries the contract level
 // (the `0.0.0` placeholder is replaced there and never again); do not edit by hand.
 /** The release sent in `Crouter-Minimum-Runtime-Version` on every request. It is frozen, so a runtime from before the

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@north-light/sdk",
-  "version": "0.3.557",
-  "crouterContract": "1.33",
+  "version": "0.3.559",
+  "crouterContract": "1.34",
   "description": "Typed Node and browser client for running crouter agents through the crtrd /v1 API.",
   "type": "module",
   "main": "./dist/index.js",
@@ -44,9 +44,9 @@
     "prepublishOnly": "node -e \"if (process.env.npm_config_tag !== 'next') { console.error('@north-light/sdk publishes only with --tag next; scripts/promote-sdk.mjs is the only mover of latest.'); process.exit(1); }\""
   },
   "dependencies": {
-    "@north-light/api": "0.3.557",
-    "@north-light/identity": "0.3.557",
-    "@north-light/plugin": "0.3.557",
+    "@north-light/api": "0.3.559",
+    "@north-light/identity": "0.3.559",
+    "@north-light/plugin": "0.3.559",
     "jose": "^6.2.1"
   },
   "peerDependencies": {