@phpsandbox/sdk 0.0.65 → 0.0.67

package/dist/runtime/rest.js

@@ -0,0 +1,226 @@
+import { ErrorEvent } from '../types.js';
+import { UnsupportedRuntimeTransportError } from '../errors/index.js';
+const restActionRoutes = {
+    'runtime.ready': { method: 'GET', path: '/runtime' },
+    ping: { method: 'GET', path: '/runtime/ping' },
+    'config.get': { method: 'GET', path: '/runtime/config' },
+    'config.update': { method: 'PATCH', path: '/runtime/config' },
+    'config.set-ports': { method: 'PUT', path: '/runtime/config/ports' },
+    'container.state': { method: 'GET', path: '/runtime/container' },
+    'container.start': { method: 'POST', path: '/runtime/container/start' },
+    'container.restart': { method: 'POST', path: '/runtime/container/restart' },
+    'container.stop': { method: 'POST', path: '/runtime/container/stop' },
+    'container.set-php': { method: 'PUT', path: '/runtime/container/php' },
+    'container.opened-ports': { method: 'GET', path: '/runtime/container/ports' },
+    'terminal.list': { method: 'GET', path: '/runtime/terminals' },
+    'shell.exec': { method: 'POST', path: '/runtime/executions' },
+    'fs.info': { method: 'POST', path: '/runtime/files/info' },
+    'fs.readFile': { method: 'GET', path: '/runtime/files/content' },
+    'fs.writeFile': { method: 'PUT', path: '/runtime/files/content' },
+    'fs.write': { method: 'PUT', path: '/runtime/files/text' },
+    'fs.mkdir': { method: 'POST', path: '/runtime/directories' },
+    'fs.createDirectory': { method: 'PUT', path: '/runtime/directories' },
+    'fs.readDirectory': { method: 'POST', path: '/runtime/directories/read' },
+    'fs.stat': { method: 'POST', path: '/runtime/files/stat' },
+    'fs.move': { method: 'POST', path: '/runtime/files/move' },
+    'fs.rename': { method: 'POST', path: '/runtime/files/rename' },
+    'fs.copy': { method: 'POST', path: '/runtime/files/copy' },
+    'fs.remove': { method: 'POST', path: '/runtime/files/remove' },
+    'fs.delete': { method: 'DELETE', path: '/runtime/files' },
+    'fs.tail': { method: 'POST', path: '/runtime/files/tail' },
+    'fs.find': { method: 'POST', path: '/runtime/files/find' },
+    'fs.textSearch': { method: 'POST', path: '/runtime/files/search' },
+    'fs.tree': { method: 'POST', path: '/runtime/files/tree' },
+    'service.list': { method: 'GET', path: '/runtime/services' },
+    'service.run': { method: 'POST', path: '/runtime/services/run' },
+    'service.stop': { method: 'POST', path: '/runtime/services/stop' },
+    'service.logs': { method: 'POST', path: '/runtime/services/logs' },
+    'composer.invoke': { method: 'POST', path: '/runtime/composer/executions' },
+    'composer.packages': { method: 'GET', path: '/runtime/composer/packages' },
+    'composer.dump-autoload': {
+        method: 'POST',
+        path: '/runtime/composer/autoload',
+    },
+    'git.checkpoint': { method: 'POST', path: '/runtime/git/checkpoints' },
+    'git.checkout': { method: 'POST', path: '/runtime/git/checkouts' },
+    'git.log': { method: 'POST', path: '/runtime/git/log' },
+    'git.sync': { method: 'POST', path: '/runtime/git/sync' },
+    'git.diff': { method: 'POST', path: '/runtime/git/diff' },
+    'git.merge': { method: 'POST', path: '/runtime/git/merge' },
+    'git.conflicts': { method: 'GET', path: '/runtime/git/conflicts' },
+    'git.resolve': { method: 'POST', path: '/runtime/git/conflicts/resolve' },
+    'git.restore': { method: 'POST', path: '/runtime/git/restore' },
+    'git.status': { method: 'GET', path: '/runtime/git/status' },
+    'git.review': { method: 'GET', path: '/runtime/git/review' },
+    'git.stage': { method: 'POST', path: '/runtime/git/stage' },
+    'git.unstage': { method: 'POST', path: '/runtime/git/unstage' },
+    'git.revert': { method: 'POST', path: '/runtime/git/revert' },
+};
+export class RestRuntimeInvoker {
+    constructor(data, fetch, refresh) {
+        this.fetch = fetch;
+        this.refresh = refresh;
+        this.refreshPromise = null;
+        this.notebookId = data.id;
+        this.configure(data.runtimeUrl ?? data.okraUrl);
+    }
+    configure(runtimeUrl) {
+        const actionUrl = new URL(runtimeUrl);
+        const ticket = actionUrl.searchParams.get('ticket') ?? '';
+        if (ticket === '') {
+            throw new UnsupportedRuntimeTransportError('The notebook connection does not contain a runtime ticket.');
+        }
+        this.ticket = ticket;
+        actionUrl.protocol = actionUrl.protocol === 'wss:' ? 'https:' : 'http:';
+        actionUrl.pathname = `/api/v1/notebooks/${encodeURIComponent(this.notebookId)}`;
+        actionUrl.searchParams.delete('ticket');
+        actionUrl.hash = '';
+        this.actionUrl = actionUrl;
+    }
+    ready() {
+        return this.invokeRaw('runtime.ready', {}, {});
+    }
+    supports(action) {
+        return action in restActionRoutes;
+    }
+    invoke(action, data = {}, options = {}) {
+        return this.invokeRaw(action, data ?? {}, options);
+    }
+    send() {
+        throw new UnsupportedRuntimeTransportError('Fire-and-forget actions require the realtime transport.');
+    }
+    async invokeRaw(action, data, options) {
+        const abort = runtimeAbort(options);
+        try {
+            for (let attempt = 0; attempt < 2; attempt += 1) {
+                const response = await this.fetch(this.request(action, data, abort.signal));
+                if (response.status === 401 && attempt === 0 && this.refresh !== undefined) {
+                    await this.refreshAuthorization();
+                    continue;
+                }
+                const payload = await runtimeActionResponse(response);
+                if (!response.ok || payload.error !== undefined) {
+                    const error = payload.error ?? payload;
+                    const message = typeof error.message === 'string' ? error.message : `Runtime action ${action} failed.`;
+                    const code = typeof error.code === 'number' ? error.code : response.status;
+                    throw new ErrorEvent(code, message, error);
+                }
+                return payload.data;
+            }
+            throw new ErrorEvent(401, `Runtime action ${action} could not be authorized.`, {});
+        }
+        finally {
+            abort.dispose();
+        }
+    }
+    request(action, data, signal) {
+        const route = restActionRoutes[action];
+        if (route === undefined) {
+            throw new UnsupportedRuntimeTransportError(`Runtime action ${action} requires the realtime transport.`);
+        }
+        const url = new URL(this.actionUrl);
+        url.pathname += route.path;
+        const headers = {
+            Accept: 'application/json, application/octet-stream',
+            Authorization: `Bearer ${this.ticket}`,
+        };
+        const body = runtimeActionRequestBody(action, data, url, headers);
+        return new Request(url, {
+            method: route.method,
+            headers,
+            body: route.method === 'GET' ? undefined : body,
+            signal,
+        });
+    }
+    async refreshAuthorization() {
+        if (this.refreshPromise === null) {
+            this.refreshPromise = this.refresh().then((runtimeUrl) => this.configure(runtimeUrl));
+        }
+        try {
+            await this.refreshPromise;
+        }
+        finally {
+            this.refreshPromise = null;
+        }
+    }
+}
+async function runtimeActionResponse(response) {
+    if (response.ok && response.headers.get('content-type')?.toLowerCase().startsWith('application/octet-stream')) {
+        return { data: new Uint8Array(await response.arrayBuffer()) };
+    }
+    const body = await response.text();
+    if (body === '') {
+        return {};
+    }
+    try {
+        return JSON.parse(body);
+    }
+    catch {
+        return { error: { code: response.status, message: body } };
+    }
+}
+function runtimeActionRequestBody(action, data, url, headers) {
+    const payload = runtimeActionRecord(data);
+    if (action === 'fs.readFile') {
+        setRequiredRuntimeQuery(url, 'path', payload.path);
+        const lineRange = runtimeActionRecord(payload.lineRange);
+        if (lineRange.lineStart !== undefined || lineRange.lineEnd !== undefined) {
+            setRequiredRuntimeQuery(url, 'lineStart', lineRange.lineStart);
+            setRequiredRuntimeQuery(url, 'lineEnd', lineRange.lineEnd);
+        }
+        return undefined;
+    }
+    if (action === 'fs.writeFile') {
+        setRequiredRuntimeQuery(url, 'path', payload.path);
+        const options = runtimeActionRecord(payload.options);
+        setBooleanRuntimeQuery(url, 'overwrite', options.overwrite);
+        setBooleanRuntimeQuery(url, 'create', options.create);
+        setBooleanRuntimeQuery(url, 'unlock', options.unlock);
+        const atomic = runtimeActionRecord(options.atomic);
+        if (typeof atomic.postfix === 'string' && atomic.postfix !== '') {
+            url.searchParams.set('atomicPostfix', atomic.postfix);
+        }
+        if (!ArrayBuffer.isView(payload.contents)) {
+            throw new TypeError('Runtime file contents must be binary data.');
+        }
+        headers['Content-Type'] = 'application/octet-stream';
+        return Uint8Array.from(new Uint8Array(payload.contents.buffer, payload.contents.byteOffset, payload.contents.byteLength)).buffer;
+    }
+    headers['Content-Type'] = 'application/json';
+    return JSON.stringify(data);
+}
+function runtimeActionRecord(value) {
+    return value !== null && typeof value === 'object' ? value : {};
+}
+function setRequiredRuntimeQuery(url, name, value) {
+    if ((typeof value !== 'string' && typeof value !== 'number') || String(value) === '') {
+        throw new TypeError(`Runtime file ${name} is required.`);
+    }
+    url.searchParams.set(name, String(value));
+}
+function setBooleanRuntimeQuery(url, name, value) {
+    url.searchParams.set(name, value === true ? 'true' : 'false');
+}
+function runtimeAbort(options) {
+    if (options.timeout === undefined && options.abortSignal === undefined) {
+        return { signal: new AbortController().signal, dispose: () => undefined };
+    }
+    const controller = new AbortController();
+    const abortFromCaller = () => controller.abort(options.abortSignal?.reason);
+    options.abortSignal?.addEventListener('abort', abortFromCaller, {
+        once: true,
+    });
+    if (options.abortSignal?.aborted) {
+        abortFromCaller();
+    }
+    const timeout = options.timeout === undefined ? undefined : setTimeout(() => controller.abort(), options.timeout);
+    return {
+        signal: controller.signal,
+        dispose: () => {
+            options.abortSignal?.removeEventListener('abort', abortFromCaller);
+            if (timeout !== undefined) {
+                clearTimeout(timeout);
+            }
+        },
+    };
+}

package/dist/socket/index.d.ts

@@ -1,6 +1,7 @@
 import type { CloseEvent as ReconnectingWebSocketCloseEvent, ErrorEvent as ReconnectingWebSocketErrorEvent } from 'reconnecting-websocket';
 import { EventDispatcher } from '../events/index.js';
 import { NotebookUnavailableError } from '../errors/index.js';
+type TransportUrlProvider = string | (() => string) | (() => Promise<string>);
 interface WsOptions {
     debug?: boolean;
     startClosed?: boolean;
@@ -73,7 +74,7 @@ export declare class Transport {
     private readonly CONNECT_WAIT_TIMEOUT;
     private pingIntervalStarted;
     private incomingMessageChain;
-    constructor(url: string, eventEmitter: EventDispatcher, options?: WsOptions);
+    constructor(url: TransportUrlProvider, eventEmitter: EventDispatcher, options?: WsOptions);
     /**
      * Validate configuration options
      */

package/dist/socket/index.js

@@ -65,13 +65,16 @@ export class Transport {
         this.incomingMessageChain = Promise.resolve();
         // Validate configuration
         this.validateConfiguration(options);
-        this.url = new URL(url);
+        this.url = typeof url === 'string' ? new URL(url) : null;
+        const urlProvider = typeof url === 'string'
+            ? this.url.toString()
+            : async () => new URL(await url()).toString();
         // Use configurable ping interval
         this.PING_INTERVAL = options.pingInterval ?? 30000;
         this.CONNECT_WAIT_TIMEOUT = options.connectWaitTimeout ?? 30000;
         // Always start closed by default (lazy initialization)
         const startClosed = options.startClosed !== false;
-        this.rws = new ReconnectingWebSocket(this.url.toString(), [], {
+        this.rws = new ReconnectingWebSocket(urlProvider, [], {
             WebSocket: options.webSocket ?? globalThis.WebSocket ?? WebSocket,
             connectionTimeout: options.connectionTimeout,
             maxReconnectionDelay: 2000,
@@ -81,7 +84,7 @@ export class Transport {
             startClosed,
         });
         this.log('debug', 'Transport initialized', {
-            url: this.url.toString(),
+            url: this.url === null ? 'dynamic' : transportLogUrl(this.url),
             options,
         });
         this.registerWatchers();
@@ -699,3 +702,9 @@ _Transport_instances = new WeakSet(), _Transport_connect = function _Transport_c
         };
     });
 };
+function transportLogUrl(url) {
+    const safeUrl = new URL(url);
+    safeUrl.search = '';
+    safeUrl.hash = '';
+    return safeUrl.toString();
+}

package/dist/types.d.ts

@@ -1,4 +1,4 @@
-export type ErrorCode = 500 | 400 | 401 | 403 | 404 | 409 | 422 | 429 | 5000;
+export type ErrorCode = 400 | 401 | 403 | 404 | 405 | 409 | 413 | 422 | 429 | 500 | 503 | 5000;
 export declare class ErrorEvent extends Error {
     readonly code: ErrorCode;
     readonly message: string;

package/docs/api-summary.md

@@ -7,12 +7,18 @@ This is a quick reference for the current SDK surface.
 ```ts
 import { PHPSandbox } from '@phpsandbox/sdk';
 
-const client = new PHPSandbox(token, 'https://api.phpsandbox.io/v1', {
+const client = PHPSandbox.realtime(token, 'https://api.phpsandbox.io/v1', {
   debug: false,
   startClosed: true,
 });
+
+const restClient = PHPSandbox.rest(token, 'https://api.phpsandbox.io/v1', {
+  runtimeUrlProvider: async (notebookId) => getFreshRuntimeUrl(notebookId),
+});
 ```
 
+Connection lifecycle methods, streaming actions, and event subscriptions require the realtime transport. The REST transport rejects unsupported operations without falling back to a websocket.
+
 ### `NotebookApi`
 
 - `create(template, input?, init = true)`
@@ -110,11 +116,11 @@ const client = new PHPSandbox(token, 'https://api.phpsandbox.io/v1', {
 
 ### Laravel (`notebook.laravel`)
 
-- Wrapper exists in the SDK, but the current okra websocket action set does not expose Laravel maintenance actions.
+- Wrapper exists in the SDK, but the current runtime action set does not expose Laravel maintenance actions.
 
 ### Auth (`notebook.auth`)
 
-- `login(newConnectionData)`
+- `login(runtimeUrl)` using a fresh ticket-bearing runtime URL
 - `logout()`
 
 ### Log (`notebook.log`)

package/examples/README.md

@@ -96,7 +96,7 @@ Useful flags:
 
 - `--no-cleanup` keeps every notebook after the run.
 - `--keep-failed` keeps failed notebooks for inspection. By default, failures are deleted too.
-- `--okra-origin=ws://127.0.0.1:9511` preserves the SDK-issued websocket path/auth but routes okra traffic to another host.
+- `--runtime-origin=ws://127.0.0.1:9511` preserves the SDK-issued websocket path/auth but routes runtime traffic to another host.
 - `--include-container-restart` adds a mutable `container.start()` restart check on the fresh notebook.
 - `--include-download` adds `file.download()` to the baseline.
 - `--include-preview` fetches the initialized preview URL in init mode, or the route written by the scenario in full mode.
@@ -104,7 +104,7 @@ Useful flags:
 - `--require-init-messages="Preparing...|Setting up...|Opening..."` asserts frontend-visible init messages were received in order.
 - `--expect-provisioned=true` asserts the `notebook.ready()` initialization result reports provisioning work.
 - `--expect-provisioning-action=template` asserts the initialization result action.
-- `--auth-payload=...` exercises `notebook.auth.login()` / `logout()`.
+- `--reauthorization-url=wss://...?ticket=...` exercises `notebook.auth.login()` / `logout()` with a fresh ticket-bearing runtime URL.
 - `--mode=init` limits the scenario to notebook create, ready, and delete so you can isolate init capacity.
 - `--init-only` is shorthand for `--mode=init`.
 - `--stop-on-failure-level` stops after the first level that has at least one failing scenario.
@@ -131,7 +131,7 @@ Default baseline coverage:
 Intentionally excluded by default:
 
 - `beacon`, because it needs a browser iframe runtime
-- `auth`, because it needs a real connection payload
+- `auth`, because it needs a fresh ticket-bearing runtime URL
 - `laravel.maintenance.*`, because it is not part of the current okra websocket action set
 - `lsp`, because it is useful but more brittle than the rest of the headless baseline
 
@@ -153,12 +153,12 @@ PHPSANDBOX_TOKEN=your-token npx tsx examples/notebook-readonly-smoke.ts \
   --notebook-id=gypjc
 ```
 
-To preserve the SDK-issued notebook auth/path but route the websocket to a different okra host:
+To preserve the SDK-issued notebook auth/path but route the websocket to a different runtime host:
 
 ```bash
 PHPSANDBOX_TOKEN=your-token npx tsx examples/notebook-readonly-smoke.ts \
   --notebook-id=gypjc \
-  --okra-origin=ws://127.0.0.1:9501
+  --runtime-origin=ws://127.0.0.1:9501
 ```
 
 Default smoke coverage:

package/examples/laravel-load-test.ts

@@ -59,8 +59,8 @@ interface LoadTestOptions {
   token: string;
   local: boolean;
   apiUrl: string;
-  okraOrigin?: string;
-  okraUrl?: string;
+  runtimeOrigin?: string;
+  runtimeUrl?: string;
   template: string;
   mode: LoadTestMode;
   stopOnFailureLevel: boolean;
@@ -84,7 +84,7 @@ interface LoadTestOptions {
   requireInitMessages: string[];
   expectProvisioned?: boolean;
   expectProvisioningAction?: NotebookProvisioningAction;
-  authPayload?: string;
+  reauthorizationUrl?: string;
   json: boolean;
   jsonFile?: string;
   insecureTls: boolean;
@@ -478,7 +478,7 @@ async function runScenario(
 
         const data = {
           ...created.data,
-          okraUrl: resolveOkraUrl(created.data.okraUrl, options),
+          runtimeUrl: resolveRuntimeUrl(created.data.runtimeUrl ?? created.data.okraUrl, options),
         };
         created.dispose();
 
@@ -947,14 +947,14 @@ async function runScenario(
         recordSkippedStep(steps, 'lsp.initialize', 'Enable with --include-lsp.');
       }
 
-      if (options.authPayload) {
+      if (options.reauthorizationUrl) {
         await runCheckedStep('auth.login-logout', async () => {
-          await notebook!.auth.login(options.authPayload!);
+          await notebook!.auth.login(options.reauthorizationUrl!);
           await notebook!.auth.logout();
           return 'ok';
         });
       } else {
-        recordSkippedStep(steps, 'auth.login-logout', 'Provide --auth-payload to exercise auth.');
+        recordSkippedStep(steps, 'auth.login-logout', 'Provide --reauthorization-url to exercise auth.');
       }
     }
   } catch (error) {
@@ -1071,8 +1071,8 @@ function renderConfiguration(options: LoadTestOptions): string {
     `  mode: ${options.mode}`,
     `  stop on failing level: ${options.stopOnFailureLevel}`,
     `  api url: ${options.apiUrl}`,
-    options.okraOrigin ? `  okra origin override: ${options.okraOrigin}` : undefined,
-    options.okraUrl ? `  okra url override: ${redactUrl(options.okraUrl)}` : undefined,
+    options.runtimeOrigin ? `  runtime origin override: ${options.runtimeOrigin}` : undefined,
+    options.runtimeUrl ? `  runtime url override: ${redactUrl(options.runtimeUrl)}` : undefined,
     `  levels: ${options.levels.join(', ')}`,
     `  waves per level: ${options.waves}`,
     `  visibility: ${options.visibility}`,
@@ -1085,7 +1085,7 @@ function renderConfiguration(options: LoadTestOptions): string {
     `  required init messages: ${options.requireInitMessages.length > 0 ? options.requireInitMessages.join(' -> ') : 'none'}`,
     `  expect provisioned: ${options.expectProvisioned ?? 'not asserted'}`,
     `  expect provisioning action: ${options.expectProvisioningAction ?? 'not asserted'}`,
-    `  include auth: ${Boolean(options.authPayload)}`,
+    `  include auth: ${Boolean(options.reauthorizationUrl)}`,
     `  insecure tls: ${options.insecureTls}`,
     `  ca file: ${options.caFile ?? 'none'}`,
   ];
@@ -2291,8 +2291,8 @@ function sanitizeArtifact<T>(payload: T): T {
     if ('token' in cloned.options) {
       cloned.options.token = '<redacted>';
     }
-    if ('authPayload' in cloned.options) {
-      cloned.options.authPayload = '<redacted>';
+    if ('reauthorizationUrl' in cloned.options) {
+      cloned.options.reauthorizationUrl = '<redacted>';
     }
   }
 
@@ -2400,8 +2400,8 @@ function parseOptions(argv: string[]): LoadTestOptions {
     token,
     local,
     apiUrl,
-    okraOrigin: stringArg(args, 'okra-origin'),
-    okraUrl: stringArg(args, 'okra-url'),
+    runtimeOrigin: stringArg(args, 'runtime-origin'),
+    runtimeUrl: stringArg(args, 'runtime-url'),
     template: stringArg(args, 'template') ?? 'laravel',
     mode: resolveMode(args),
     stopOnFailureLevel: booleanArg(args, 'stop-on-failure-level') ?? false,
@@ -2425,7 +2425,7 @@ function parseOptions(argv: string[]): LoadTestOptions {
     requireInitMessages: listArg(args, 'require-init-messages'),
     expectProvisioned: booleanArg(args, 'expect-provisioned'),
     expectProvisioningAction: provisioningActionArg(args, 'expect-provisioning-action'),
-    authPayload: stringArg(args, 'auth-payload'),
+    reauthorizationUrl: stringArg(args, 'reauthorization-url'),
     json: booleanArg(args, 'json') ?? false,
     jsonFile: stringArg(args, 'json-file'),
     insecureTls,
@@ -2433,17 +2433,17 @@ function parseOptions(argv: string[]): LoadTestOptions {
   };
 }
 
-function resolveOkraUrl(original: string, options: LoadTestOptions): string {
-  if (options.okraUrl) {
-    return options.okraUrl;
+function resolveRuntimeUrl(original: string, options: LoadTestOptions): string {
+  if (options.runtimeUrl) {
+    return options.runtimeUrl;
   }
 
-  if (!options.okraOrigin) {
+  if (!options.runtimeOrigin) {
     return original;
   }
 
   const source = new URL(original);
-  const target = new URL(options.okraOrigin);
+  const target = new URL(options.runtimeOrigin);
   source.protocol = target.protocol;
   source.host = target.host;
   return source.toString();

package/examples/notebook-readonly-smoke.ts

@@ -24,8 +24,8 @@ interface SmokeOptions {
   local: boolean;
   apiUrl: string;
   notebookId: string;
-  okraUrl?: string;
-  okraOrigin?: string;
+  runtimeUrl?: string;
+  runtimeOrigin?: string;
   includeExec: boolean;
   includeDownload: boolean;
   includePreview: boolean;
@@ -67,8 +67,8 @@ interface SmokeArtifact {
     apiUrl: string;
     local: boolean;
     notebookId: string;
-    okraUrl?: string;
-    okraOrigin?: string;
+    runtimeUrl?: string;
+    runtimeOrigin?: string;
     includeExec: boolean;
     includeDownload: boolean;
     includePreview: boolean;
@@ -77,7 +77,7 @@ interface SmokeArtifact {
     id: string;
     title?: string;
     type?: string;
-    okraUrl: string;
+    runtimeUrl: string;
   };
   initTrace: InitTraceArtifact;
   steps: StepArtifact[];
@@ -103,13 +103,13 @@ async function main(): Promise<void> {
       const result = await client.get<NotebookData>(`/notebook/${options.notebookId}`);
       return {
         data: result.data,
-        detail: `id=${result.data.id} type=${result.data.type ?? ''} title=${result.data.title ?? ''} okraUrl=${redactUrl(result.data.okraUrl)}`,
+        detail: `id=${result.data.id} type=${result.data.type ?? ''} title=${result.data.title ?? ''} runtimeUrl=${redactUrl(result.data.runtimeUrl ?? result.data.okraUrl)}`,
       };
     });
 
     notebookData = {
       ...response.data,
-      okraUrl: resolveOkraUrl(response.data.okraUrl, options),
+      runtimeUrl: resolveRuntimeUrl(response.data.runtimeUrl ?? response.data.okraUrl, options),
     };
 
     notebook = new NotebookInstance(notebookData, client);
@@ -289,8 +289,8 @@ async function main(): Promise<void> {
       apiUrl: options.apiUrl,
       local: options.local,
       notebookId: options.notebookId,
-      okraUrl: options.okraUrl ? redactUrl(options.okraUrl) : undefined,
-      okraOrigin: options.okraOrigin,
+      runtimeUrl: options.runtimeUrl ? redactUrl(options.runtimeUrl) : undefined,
+      runtimeOrigin: options.runtimeOrigin,
       includeExec: options.includeExec,
       includeDownload: options.includeDownload,
       includePreview: options.includePreview,
@@ -300,7 +300,7 @@ async function main(): Promise<void> {
           id: notebookData.id,
           title: notebookData.title,
           type: notebookData.type,
-          okraUrl: redactUrl(notebookData.okraUrl),
+          runtimeUrl: redactUrl(notebookData.runtimeUrl ?? notebookData.okraUrl),
         }
       : undefined,
     initTrace,
@@ -471,17 +471,17 @@ async function readStreamToString(stream: ReadableStream<string>, timeoutMs: num
   }
 }
 
-function resolveOkraUrl(original: string, options: SmokeOptions): string {
-  if (options.okraUrl) {
-    return options.okraUrl;
+function resolveRuntimeUrl(original: string, options: SmokeOptions): string {
+  if (options.runtimeUrl) {
+    return options.runtimeUrl;
   }
 
-  if (!options.okraOrigin) {
+  if (!options.runtimeOrigin) {
     return original;
   }
 
   const source = new URL(original);
-  const target = new URL(options.okraOrigin);
+  const target = new URL(options.runtimeOrigin);
   source.protocol = target.protocol;
   source.host = target.host;
   return source.toString();
@@ -508,8 +508,8 @@ function parseOptions(argv: string[]): SmokeOptions {
       process.env.PHPSANDBOX_API_URL ??
       ((booleanArg(args, 'local') ?? false) ? DEFAULT_LOCAL_API_URL : DEFAULT_API_URL),
     notebookId: stringArg(args, 'notebook-id') ?? 'gypjc',
-    okraUrl: stringArg(args, 'okra-url'),
-    okraOrigin: stringArg(args, 'okra-origin'),
+    runtimeUrl: stringArg(args, 'runtime-url'),
+    runtimeOrigin: stringArg(args, 'runtime-origin'),
     includeExec: booleanArg(args, 'include-exec') ?? false,
     includeDownload: booleanArg(args, 'include-download') ?? false,
     includePreview: booleanArg(args, 'include-preview') ?? false,
@@ -786,7 +786,7 @@ function printSummary(artifact: SmokeArtifact): void {
   console.log('\n=== Notebook readonly smoke summary ===');
   console.log(`Status: ${artifact.status}`);
   console.log(`Notebook: ${artifact.options.notebookId}`);
-  console.log(`Okra URL: ${artifact.notebook?.okraUrl ?? 'unresolved'}`);
+  console.log(`Runtime URL: ${artifact.notebook?.runtimeUrl ?? 'unresolved'}`);
   console.log(`Duration: ${formatDuration(artifact.durationMs)}`);
   console.log(`Steps: passed=${passed} failed=${failed} skipped=${skipped}`);
 
@@ -806,8 +806,8 @@ Options:
   --local                   Use ${DEFAULT_LOCAL_API_URL} and default to insecure TLS.
   --insecure-tls            Disable TLS verification for local HTTPS/WSS.
   --ca-file=<path>          Trust a custom CA for local HTTPS/WSS.
-  --okra-url=<url>          Replace notebook okraUrl with a full WebSocket URL.
-  --okra-origin=<origin>    Replace only the okraUrl origin, preserving path/query auth.
+  --runtime-url=<url>       Replace the notebook runtimeUrl with a full WebSocket URL.
+  --runtime-origin=<origin> Replace only the runtimeUrl origin, preserving path/query auth.
   --include-exec            Also run shell, terminal, and REPL read-safe execution checks.
   --include-download        Also run a read-only file.download() check for a known file.
   --include-preview         Fetch the initialized preview URL.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@phpsandbox/sdk",
-  "version": "0.0.65",
+  "version": "0.0.67",
   "description": "A comprehensive TypeScript SDK for interacting with cloud-based PHP development environments",
   "main": "./dist/index.js",
   "module": "./dist/index.js",