@phpsandbox/sdk 0.0.68 → 0.1.2

package/examples/README.md

@@ -6,20 +6,20 @@
 PHPSANDBOX_TOKEN=your-token npx tsx examples/basic.ts
 ```
 
-### Running Deployment Examples
+### Running Publication Examples
 
 Cloudflare Containers target:
 
 ```bash
 PHPSANDBOX_TOKEN=your-token PHPSANDBOX_NOTEBOOK_ID=notebook-id \
-  npx tsx examples/deploy-cloudflare-container.ts
+  npx tsx examples/publish-cloudflare-container.ts
 ```
 
 SSH agent target:
 
 ```bash
 PHPSANDBOX_TOKEN=your-token PHPSANDBOX_NOTEBOOK_ID=notebook-id \
-  npx tsx examples/deploy-ssh-agent.ts
+  npx tsx examples/publish-ssh-agent.ts
 ```
 
 Laravel Cloud target:
@@ -29,10 +29,10 @@ PHPSANDBOX_TOKEN=your-token PHPSANDBOX_NOTEBOOK_ID=notebook-id \
   PHPSANDBOX_LARAVEL_CLOUD_REPOSITORY=owner/repo \
   PHPSANDBOX_GITHUB_TOKEN=github-token \
   PHPSANDBOX_LARAVEL_CLOUD_API_KEY=lc-api-key \
-  npx tsx examples/deploy-laravel-cloud.ts
+  npx tsx examples/publish-laravel-cloud.ts
 ```
 
-Deployment examples accept `PHPSANDBOX_API_URL` and `PHPSANDBOX_DEPLOY_SLUG`. On the first run they create the notebook's deployment; later runs publish the existing deployment without changing slug or provider. The SSH example creates a server registration when `PHPSANDBOX_DEPLOY_SERVER_ID` is not set; on local `.test` APIs it also starts local Rook from `PHPSANDBOX_ROOK_DIR` or the sibling `rook` repo. The Laravel Cloud example syncs the notebook to `PHPSANDBOX_LARAVEL_CLOUD_REPOSITORY`, upserts `PHPSANDBOX_GITHUB_TOKEN` into `GITHUB_TOKEN`, and upserts `PHPSANDBOX_LARAVEL_CLOUD_API_KEY` into `LARAVEL_CLOUD_API_KEY` on first publish.
+Publication examples accept `PHPSANDBOX_API_URL` and `PHPSANDBOX_PUBLISH_SLUG`. On the first run they create the notebook's publication; later runs publish it again without changing slug or provider. The SSH example creates a server registration when `PHPSANDBOX_PUBLISH_SERVER_ID` is not set; on local `.test` APIs it also starts local Rook from `PHPSANDBOX_ROOK_DIR` or the sibling `rook` repo. The Laravel Cloud example syncs the notebook to `PHPSANDBOX_LARAVEL_CLOUD_REPOSITORY`, upserts `PHPSANDBOX_GITHUB_TOKEN` into `GITHUB_TOKEN`, and upserts `PHPSANDBOX_LARAVEL_CLOUD_API_KEY` into `LARAVEL_CLOUD_API_KEY` on first publish.
 
 ### Running The Laravel Load Test
 
@@ -105,7 +105,7 @@ Useful flags:
 - `--expect-provisioned=true` asserts the `notebook.ready()` initialization result reports provisioning work.
 - `--expect-provisioning-action=template` asserts the initialization result action.
 - `--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.
+- `--mode=init` limits the scenario to notebook create, ready, and destroy 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.
 - `--local` switches the default API URL to `https://api.phpsandbox.test/v1` and defaults TLS to insecure unless you also pass `--ca-file` or `--no-insecure-tls`.
@@ -116,12 +116,12 @@ Useful flags:
 
 Default baseline coverage:
 
-- notebook lifecycle: create, ready, ping, delete
+- notebook lifecycle: create, ready, ping, destroy
 - secrets
 - container state and telemetry; optional restart with `--include-container-restart`
 - filesystem watch/write/read/search/find/tree/tail
 - optional preview fetch with `--include-preview`
-- shell exec and stream
+- shell process execution and streams
 - terminal spawn streaming
 - services with Redis logs
 - composer metadata and autoload dump
@@ -132,7 +132,6 @@ Intentionally excluded by default:
 
 - `beacon`, because it needs a browser iframe runtime
 - `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
 
 ### Running A Read-Only Existing Notebook Smoke Test

package/examples/basic.ts

@@ -16,9 +16,9 @@ console.log('\n');
 
 console.log('====== Read routes/web.php in the notebook ======');
 const decoder = new TextDecoder();
-const content = await notebook.file.readFile('routes/web.php');
+const content = await notebook.files.read('routes/web.php');
 console.log(decoder.decode(content));
 
 // Always close the notebook when done to clean up the connection.
 notebook.dispose();
-await notebook.delete();
+await notebook.destroy();

package/examples/git-merge-smoke.ts

@@ -41,7 +41,7 @@ async function main(): Promise<void> {
   let shouldDeleteFork = false;
 
   try {
-    base = await client.notebook.open(options.notebookId);
+    base = await client.notebook.get(options.notebookId);
     console.log(`Base notebook: ${base.data.id}`);
 
     await base.ready();
@@ -54,10 +54,7 @@ async function main(): Promise<void> {
 
     await fork.ready();
     const editContent = buildEditContent(base.data.id, forkNotebookId, options);
-    const written = await fork.file.write(options.editPath, editContent);
-    if (!written) {
-      throw new Error(`fs.write returned false for ${options.editPath}.`);
-    }
+    await fork.files.write(options.editPath, editContent);
     console.log(`Edited fork file: ${options.editPath}`);
 
     const forkCheckpoint = await fork.git.checkpoint(options.author, `Smoke edit in fork ${forkNotebookId}`, options.ref, false);
@@ -98,7 +95,7 @@ async function main(): Promise<void> {
   } finally {
     if (shouldDeleteFork && fork) {
       try {
-        await fork.delete();
+        await fork.destroy();
         console.log(`Deleted fork notebook: ${fork.data.id}`);
       } catch (error) {
         console.error(`Could not delete fork notebook ${fork.data.id}: ${formatError(error)}`);

package/examples/laravel-load-test.ts

@@ -389,11 +389,10 @@ async function runScenario(
   let notebook: NotebookInstance | null = null;
   let previewUrl: string | undefined;
   let logsCaptured = 0;
-  let logListener: Disposable | null = null;
+  let logReader: ReadableStreamDefaultReader<import('../src/log.js').RuntimeLogEntry> | null = null;
   let initTrace: InitTrace | undefined;
   let readyResult: NotebookInitSuccessResult | undefined;
   let initTraceDisposables: Disposable[] = [];
-  let telemetryEnabled = false;
   let redisRunning = false;
 
   const routeSlug = id.toLowerCase();
@@ -560,12 +559,19 @@ async function runScenario(
     }
 
     if (options.mode !== 'init') {
-      logListener = notebook.log.stream((line) => {
-        if (line.trim().length > 0) {
-          logsCaptured += 1;
-          ui.updateScenarioLogs(id, logsCaptured);
+      logReader = notebook.logs.follow().getReader();
+      void (async () => {
+        while (logReader) {
+          const entry = await logReader.read();
+          if (entry.done) {
+            return;
+          }
+          if (entry.value.message.trim().length > 0) {
+            logsCaptured += 1;
+            ui.updateScenarioLogs(id, logsCaptured);
+          }
         }
-      });
+      })().catch(() => {});
 
       await runCheckedStep('notebook.ping', () => notebook!.ping(), { continueOnError: false });
 
@@ -599,8 +605,8 @@ async function runScenario(
       });
 
       await runCheckedStep('container.state', async () => {
-        const [state, ports] = await Promise.all([notebook!.container.state(), notebook!.container.openedPorts()]);
-        const portInfo = assertPortInfoList(ports, 'container.openedPorts');
+        const [state, ports] = await Promise.all([notebook!.container.state(), notebook!.ports.list()]);
+        const portInfo = assertPortInfoList(ports, 'ports.list');
         return `${state.state} (${describePorts(portInfo)})`;
       });
 
@@ -609,11 +615,11 @@ async function runScenario(
           'container.restart',
           async () => {
             await notebook!.container.start();
-            const [state, ports] = await Promise.all([notebook!.container.state(), notebook!.container.openedPorts()]);
+            const [state, ports] = await Promise.all([notebook!.container.state(), notebook!.ports.list()]);
             if (state.state !== 'running') {
               throw new Error(`Expected running container after restart, got ${state.state}`);
             }
-            return `${state.state} (${describePorts(assertPortInfoList(ports, 'container.openedPorts after restart'))})`;
+            return `${state.state} (${describePorts(assertPortInfoList(ports, 'ports.list after restart'))})`;
           },
           { timeoutMs: options.stepTimeoutMs * 3, continueOnError: false }
         );
@@ -626,29 +632,20 @@ async function runScenario(
         async () =>
           retryWithBackoff(
             async () => {
-              const statsPromise = waitForNextEvent<ContainerStats>(
-                (handler) => notebook!.container.listen('container.stats', handler),
-                options.telemetryTimeoutMs,
-                'container.stats'
-              );
-              void statsPromise.catch(() => undefined);
-              const portsPromise = waitForNextEvent<PortInfo[]>(
-                (handler) => notebook!.container.listen('container.ports', handler),
-                options.telemetryTimeoutMs,
-                'container.ports'
-              );
-              void portsPromise.catch(() => undefined);
-
-              await notebook!.container.enableTelemetry(new Set(['stats', 'ports']));
-              telemetryEnabled = true;
-
-              return await firstFulfilled([
-                statsPromise.then(
-                  (stats) =>
-                    `cpu=${stats.cpu.usage}/${stats.cpu.limit} memory=${stats.memory.usage}/${stats.memory.limit}`
-                ),
-                portsPromise.then((ports) => describePorts(assertPortInfoList(ports, 'container.ports'))),
-              ]);
+              const statsReader = notebook!.metrics.watch().getReader();
+              const portsReader = notebook!.ports.watch().getReader();
+              try {
+                const statsPromise = withTimeout(statsReader.read(), options.telemetryTimeoutMs, 'metrics.watch')
+                  .then(({ value }) => {
+                    if (!value) throw new Error('metrics.watch ended before a sample was received.');
+                    return `cpu=${value.cpu.usage}/${value.cpu.limit} memory=${value.memory.usage}/${value.memory.limit}`;
+                  });
+                const portsPromise = withTimeout(portsReader.read(), options.telemetryTimeoutMs, 'ports.watch')
+                  .then(({ value }) => describePorts(assertPortInfoList(value ?? [], 'ports.watch')));
+                return await firstFulfilled([statsPromise, portsPromise]);
+              } finally {
+                await Promise.all([statsReader.cancel(), portsReader.cancel()]);
+              }
             },
             TELEMETRY_RETRY_DELAYS_MS,
             shouldRetryTelemetryError
@@ -660,7 +657,7 @@ async function runScenario(
         'filesystem.watch-and-write',
         async () => {
           const changeSeen = createDeferred<FileChange>();
-          const watch = await notebook!.file.watch(
+          const watch = await notebook!.files.watch(
             'routes',
             { recursive: true, excludes: ['vendor/**', 'node_modules/**'] },
             (change) => {
@@ -671,12 +668,9 @@ async function runScenario(
           );
 
           try {
-            const current = textDecoder.decode(await notebook!.file.readFile(routePath));
+            const current = textDecoder.decode(await notebook!.files.read(routePath));
             const next = appendRouteDefinition(current, id, routeUrlPath);
-            const written = await notebook!.file.write(routePath, next);
-            if (!written) {
-              throw new Error(`fs.write returned false for ${routePath}.`);
-            }
+            await notebook!.files.write(routePath, next);
 
             const change = await withTimeout(
               changeSeen.promise,
@@ -692,14 +686,13 @@ async function runScenario(
       );
 
       await runCheckedStep('filesystem.inspect', async () => {
-        const [raw, info, stat, directory, tree, found, tail] = await Promise.all([
-          notebook!.file.readFile(routePath),
-          notebook!.file.info(routePath),
-          notebook!.file.stat(routePath),
-          notebook!.file.readDirectory('routes'),
-          notebook!.file.tree('routes'),
-          notebook!.file.find(routeFileName, { includes: ['routes/**'], maxResults: 10 }),
-          notebook!.file.tail(routePath, 20),
+        const [raw, stat, directory, tree, found, tail] = await Promise.all([
+          notebook!.files.read(routePath),
+          notebook!.files.stat(routePath),
+          notebook!.files.list('routes'),
+          notebook!.files.tree('routes'),
+          notebook!.files.find(routeFileName, { includes: ['routes/**'], maxResults: 10 }),
+          notebook!.files.tail(routePath, { lines: 20 }),
         ]);
 
         const text = textDecoder.decode(raw);
@@ -707,7 +700,7 @@ async function runScenario(
           throw new Error(`Expected ${routeUrlPath} in ${routePath}.`);
         }
 
-        const [, matches] = await notebook!.file.search(
+        const [, matches] = await notebook!.files.search(
           { pattern: routeUrlPath },
           { includes: [routePath], excludes: [], maxResults: 10 }
         );
@@ -716,12 +709,12 @@ async function runScenario(
           throw new Error(`file.search() did not find ${routeUrlPath}.`);
         }
 
-        const exists = await notebook!.file.exists(routePath);
+        const exists = await notebook!.files.exists(routePath);
         if (!exists) {
           throw new Error(`${routePath} does not exist after write.`);
         }
 
-        return `size=${stat.size} info=${info.language} dir=${directory.length} tree-lines=${tree.split('\n').length} find=${found.length} tail=${tail.length}`;
+        return `size=${stat.size} dir=${directory.length} tree-lines=${tree.split('\n').length} find=${found.length} tail=${tail.length}`;
       });
 
       if (options.includePreview) {
@@ -732,7 +725,10 @@ async function runScenario(
 
       if (options.includeDownload) {
         await runCheckedStep('filesystem.download', async () => {
-          const archive = await notebook!.file.download(undefined, ['vendor/**', 'node_modules/**'], [routePath, 'composer.json']);
+          const archive = await notebook!.files.download({
+            exclude: ['vendor/**', 'node_modules/**'],
+            include: [routePath, 'composer.json'],
+          });
           if (archive.size === 0) {
             throw new Error('file.download() returned an empty blob.');
           }
@@ -743,8 +739,8 @@ async function runScenario(
         recordSkippedStep(steps, 'filesystem.download', 'Enable with --include-download.');
       }
 
-      await runCheckedStep('shell.exec', async () => {
-        const result = await notebook!.shell.exec(['php', 'artisan', '--version']);
+      await runCheckedStep('shell.run', async () => {
+        const result = await notebook!.run(['php', 'artisan', '--version']).wait();
         result.throw();
         if (!result.output.toLowerCase().includes('laravel')) {
           throw new Error(`Unexpected artisan version output: ${trimDetail(result.output)}`);
@@ -754,21 +750,22 @@ async function runScenario(
       }, { skipIf: explainUnsupportedShell });
 
       await runCheckedStep(
-        'shell.exec-stream',
+        'shell.run-stream',
         async () => {
-          const execution = notebook!.shell.execStream(
-            ['php', 'artisan', 'route:list', `--path=${routeUrlPath}`]
+          const execution = notebook!.run(
+            ['php', 'artisan', 'route:list', `--path=${routeUrlPath}`],
+            { tty: false },
           );
 
           const [streamOutput, result] = await Promise.all([
-            readStreamToString(execution.output, options.streamTimeoutMs, options.maxStreamChars).catch((error) => {
+            readStreamToString(execution.stdout, options.streamTimeoutMs, options.maxStreamChars).catch((error) => {
               if (isStreamInactivityError(error)) {
                 return '';
               }
 
               throw error;
             }),
-            withTimeout(execution.result, options.stepTimeoutMs, 'waiting for shell.execStream() result'),
+            withTimeout(execution.wait(), options.stepTimeoutMs, 'waiting for process exit'),
           ]);
 
           result.throw();
@@ -783,20 +780,20 @@ async function runScenario(
       );
 
       await runCheckedStep(
-        'terminal.spawn',
+        'terminals.create',
         async () => {
-          const process = await notebook!.terminal.spawn(
-            'php',
-            ['artisan', 'route:list', `--path=${routeUrlPath}`]
-          );
+          const process = await notebook!.terminals.create({
+            command: 'php',
+            args: ['artisan', 'route:list', `--path=${routeUrlPath}`],
+          });
 
           try {
             const outputPromise = readStreamToString(process.output, options.streamTimeoutMs, options.maxStreamChars);
-            const exitPromise = withTimeout(process.exit, options.stepTimeoutMs, 'waiting for terminal process to exit');
+            const exitPromise = withTimeout(process.wait(), options.stepTimeoutMs, 'waiting for terminal process to exit');
             const [output, exitCode] = await Promise.all([outputPromise, exitPromise]);
 
             if (exitCode !== 0) {
-              throw new Error(`terminal.spawn() exited with ${exitCode}: ${trimDetail(output)}`);
+              throw new Error(`terminals.create() exited with ${exitCode}: ${trimDetail(output)}`);
             }
 
             if (!output.includes(routeUrlPath)) {
@@ -819,7 +816,7 @@ async function runScenario(
           redisRunning = started.running || started.state === 'running' || started.state === 'starting';
 
           const stream = notebook!.services.logs('redis', { follow: true, tail: 25 });
-          const reader = stream.output.getReader();
+          const reader = stream.getReader();
 
           try {
             const [snapshot, chunk] = await Promise.all([
@@ -836,7 +833,6 @@ async function runScenario(
           } finally {
             await reader.cancel().catch(() => undefined);
             reader.releaseLock();
-            await stream.stop().catch(() => false);
             await notebook!.services.stop('redis').catch(() => started);
             redisRunning = false;
           }
@@ -844,33 +840,22 @@ async function runScenario(
         { timeoutMs: options.stepTimeoutMs * 2 }
       );
 
-      recordSkippedStep(
-        steps,
-        'laravel.maintenance',
-        'Not part of the current okra websocket action set.'
-      );
-
       await runCheckedStep('composer.metadata', async () => {
         let composerLogChunks = 0;
-        const composerLogs = notebook!.composer.stream((line) => {
-          if (line.trim().length > 0) {
+        const dump = notebook!.composer.dumpAutoload();
+        for await (const chunk of dump.output) {
+          if (chunk.data.byteLength > 0) {
             composerLogChunks += 1;
           }
-        });
-
-        try {
-          const [packages, dump] = await Promise.all([notebook!.composer.packages(), notebook!.composer.dumpAutoload()]);
-          if (!dump.success) {
-            throw new Error(dump.message || 'composer.dumpAutoload() failed.');
-          }
-          if (packages.length === 0) {
-            throw new Error('composer.packages() returned no packages.');
-          }
+        }
 
-          return `packages=${packages.length} composer-log-events=${composerLogChunks}`;
-        } finally {
-          composerLogs.dispose();
+        (await dump.wait()).throw();
+        const packages = await notebook!.composer.packages();
+        if (packages.length === 0) {
+          throw new Error('composer.packages() returned no packages.');
         }
+
+        return `packages=${packages.length} composer-log-events=${composerLogChunks}`;
       }, { timeoutMs: Math.max(options.stepTimeoutMs * 2, 120_000) });
 
       await runCheckedStep('git.checkpoint', async () => {
@@ -950,7 +935,7 @@ async function runScenario(
       if (options.reauthorizationUrl) {
         await runCheckedStep('auth.login-logout', async () => {
           await notebook!.auth.login(options.reauthorizationUrl!);
-          await notebook!.auth.logout();
+          notebook!.dispose();
           return 'ok';
         });
       } else {
@@ -965,11 +950,8 @@ async function runScenario(
         await notebook.services.stop('redis').catch(() => undefined);
       }
 
-      if (telemetryEnabled) {
-        await notebook.container.stopTelemetry().catch(() => undefined);
-      }
-
-      logListener?.dispose();
+      await logReader?.cancel().catch(() => undefined);
+      logReader = null;
       for (const disposable of initTraceDisposables) {
         disposable.dispose();
       }
@@ -1020,7 +1002,7 @@ async function cleanupNotebook(notebook: NotebookInstance, steps: StepResult[]):
       const notebookId = notebook.data.id;
       await cleanupDeleteLimiter.run(async () => {
         try {
-          await retryWithBackoff(() => notebook.delete(), DELETE_RETRY_DELAYS_MS, shouldRetryApiRateLimitError);
+          await retryWithBackoff(() => notebook.destroy(), DELETE_RETRY_DELAYS_MS, shouldRetryApiRateLimitError);
         } catch (error) {
           if (formatError(error).includes('Notebook has been deleted')) {
             return;
@@ -1912,7 +1894,7 @@ function firstFulfilled<T>(promises: Array<Promise<T>>): Promise<T> {
 }
 
 async function readStreamToString(
-  stream: ReadableStream<string>,
+  stream: ReadableStream<string | Uint8Array>,
   timeoutMs: number,
   maxChars: number
 ): Promise<string> {
@@ -1926,7 +1908,7 @@ async function readStreamToString(
         break;
       }
 
-      output += chunk.value ?? '';
+      output += chunk.value instanceof Uint8Array ? new TextDecoder().decode(chunk.value) : (chunk.value ?? '');
     }
 
     return output;

package/examples/notebook-readonly-smoke.ts

@@ -155,12 +155,12 @@ async function main(): Promise<void> {
     }, false);
 
     await recordStep(steps, 'container.opened-ports', options.stepTimeoutMs, async () => {
-      const ports = await notebook!.container.openedPorts();
-      return describePorts(assertPortInfoList(ports, 'container.openedPorts'));
+      const ports = await notebook!.ports.list();
+      return describePorts(assertPortInfoList(ports, 'ports.list'));
     }, false);
 
     const rootSnapshot = await recordStep(steps, 'filesystem.root', options.stepTimeoutMs, async () => {
-      const rootEntries = await notebook!.file.readDirectory('/');
+      const rootEntries = await notebook!.files.list('/');
 
       const preferred = ['composer.json', 'index.php', 'artisan'];
       const rootNames = new Set(rootEntries.map(([name]) => name));
@@ -174,7 +174,7 @@ async function main(): Promise<void> {
     const treePath = rootSnapshot.candidate === 'artisan' ? 'routes' : undefined;
     if (treePath) {
       await recordStep(steps, 'filesystem.tree', options.stepTimeoutMs, async () => {
-        const tree = await notebook!.file.tree(treePath);
+        const tree = await notebook!.files.tree(treePath);
         return `path=${treePath} bytes=${tree.length}`;
       }, false);
     } else {
@@ -183,8 +183,8 @@ async function main(): Promise<void> {
 
     const findSnapshot = await recordStep(steps, 'filesystem.find', options.stepTimeoutMs, async () => {
       const [composerFiles, indexFiles] = await Promise.all([
-        notebook!.file.find('composer.json', { maxResults: 10 }),
-        notebook!.file.find('index.php', { maxResults: 10 }),
+        notebook!.files.find('composer.json', { maxResults: 10 }),
+        notebook!.files.find('index.php', { maxResults: 10 }),
       ]);
       const candidate = [...composerFiles, ...indexFiles].find((file) => typeof file.path === 'string')?.path;
       return {
@@ -197,15 +197,13 @@ async function main(): Promise<void> {
 
     if (candidate) {
       await recordStep(steps, 'filesystem.read-candidate', options.stepTimeoutMs, async () => {
-        const [info, stat, content, tail] = await Promise.all([
-          notebook!.file.info(candidate),
-          notebook!.file.stat(candidate),
-          notebook!.file.readFile(candidate),
-          notebook!.file.tail(candidate, 10),
+        const [stat, content, tail] = await Promise.all([
+          notebook!.files.stat(candidate),
+          notebook!.files.read(candidate),
+          notebook!.files.tail(candidate, { lines: 10 }),
         ]);
 
-        const bytes = content instanceof Uint8Array ? content : new TextEncoder().encode(JSON.stringify(content));
-        return `path=${candidate} size=${stat.size} binary=${info.binary} sha256=${sha256(bytes)} tailBytes=${tail.length}`;
+        return `path=${candidate} size=${stat.size} sha256=${sha256(content)} tailBytes=${tail.length}`;
       }, false);
     } else {
       recordSkippedStep(steps, 'filesystem.read-candidate', 'No readable candidate file found.');
@@ -214,7 +212,10 @@ async function main(): Promise<void> {
     if (options.includeDownload) {
       if (candidate) {
         await recordStep(steps, 'filesystem.download', options.stepTimeoutMs, async () => {
-          const archive = await notebook!.file.download(undefined, ['vendor/**', 'node_modules/**'], [candidate]);
+          const archive = await notebook!.files.download({
+            exclude: ['vendor/**', 'node_modules/**'],
+            include: [candidate],
+          });
           if (archive.size === 0) {
             throw new Error('file.download() returned an empty blob.');
           }
@@ -228,7 +229,7 @@ async function main(): Promise<void> {
     }
 
     await recordStep(steps, 'filesystem.search', options.stepTimeoutMs, async () => {
-      const [hasMore, matches] = await notebook!.file.search({
+      const [hasMore, matches] = await notebook!.files.search({
         pattern: 'php',
         isRegExp: false,
         isCaseSensitive: false,
@@ -259,8 +260,8 @@ async function main(): Promise<void> {
     if (options.includeExec) {
       await runExecutionChecks(notebook, steps, options);
     } else {
-      recordSkippedStep(steps, 'shell.exec', 'Enable with --include-exec.');
-      recordSkippedStep(steps, 'terminal.spawn', 'Enable with --include-exec.');
+      recordSkippedStep(steps, 'shell.run', 'Enable with --include-exec.');
+      recordSkippedStep(steps, 'terminals.create', 'Enable with --include-exec.');
       recordSkippedStep(steps, 'terminal.interactive', 'Enable with --include-exec.');
       recordSkippedStep(steps, 'terminal.osc', 'Enable with --include-exec.');
       recordSkippedStep(steps, 'repl.eval', 'Enable with --include-exec.');
@@ -323,8 +324,8 @@ async function main(): Promise<void> {
 }
 
 async function runExecutionChecks(notebook: NotebookInstance, steps: StepArtifact[], options: SmokeOptions): Promise<void> {
-  await recordStep(steps, 'shell.exec', options.stepTimeoutMs, async () => {
-    const result = await notebook.shell.exec(['php', '-r', 'echo "sdk-smoke";']);
+  await recordStep(steps, 'shell.run', options.stepTimeoutMs, async () => {
+    const result = await notebook.run(['php', '-r', 'echo "sdk-smoke";']).wait();
     result.throw();
     if (!result.output.includes('sdk-smoke')) {
       throw new Error(`Unexpected shell output: ${result.output}`);
@@ -332,26 +333,25 @@ async function runExecutionChecks(notebook: NotebookInstance, steps: StepArtifac
     return `exit=${result.exitCode}`;
   }, false);
 
-  await recordStep(steps, 'terminal.spawn', options.stepTimeoutMs, async () => {
-    const process = await notebook.terminal.spawn('php', ['-r', 'echo "sdk-smoke";'], { output: true });
+  await recordStep(steps, 'terminals.create', options.stepTimeoutMs, async () => {
+    const process = await notebook.terminals.create({ command: 'php', args: ['-r', 'echo "sdk-smoke";'] });
     const [exitCode, output] = await Promise.all([
-      withTimeout(process.exit, options.stepTimeoutMs, 'waiting for terminal process exit'),
+      withTimeout(process.wait(), options.stepTimeoutMs, 'waiting for terminal process exit'),
       readStreamToString(process.output, options.streamTimeoutMs, options.maxStreamChars),
     ]);
 
     if (exitCode !== 0 || !output.includes('sdk-smoke')) {
-      throw new Error(`terminal.spawn failed: exit=${exitCode} output=${trimDetail(output)}`);
+      throw new Error(`terminals.create failed: exit=${exitCode} output=${trimDetail(output)}`);
     }
 
     return `exit=${exitCode}`;
   }, false);
 
   await recordStep(steps, 'terminal.interactive', options.stepTimeoutMs, async () => {
-    const process = await notebook.terminal.spawn(
-      'bash',
-      ['-lc', 'IFS= read -r line; printf "sdk-input:%s\\n" "$line"'],
-      { output: true }
-    );
+    const process = await notebook.terminals.create({
+      command: 'bash',
+      args: ['-lc', 'IFS= read -r line; printf "sdk-input:%s\\n" "$line"'],
+    });
 
     try {
       const writer = process.input.getWriter();
@@ -359,7 +359,7 @@ async function runExecutionChecks(notebook: NotebookInstance, steps: StepArtifac
       writer.releaseLock();
 
       const [exitCode, output] = await Promise.all([
-        withTimeout(process.exit, options.stepTimeoutMs, 'waiting for interactive terminal process exit'),
+        withTimeout(process.wait(), options.stepTimeoutMs, 'waiting for interactive terminal process exit'),
         readStreamToString(process.output, options.streamTimeoutMs, options.maxStreamChars),
       ]);
 
@@ -374,19 +374,16 @@ async function runExecutionChecks(notebook: NotebookInstance, steps: StepArtifac
   }, false);
 
   await recordStep(steps, 'terminal.osc', options.stepTimeoutMs, async () => {
-    const process = await notebook.terminal.spawn(
-      'bash',
-      ['-lc', 'printf "sdk-prompt$"'],
-      {
-        output: true,
-        osc: true,
-        terminal: { cols: 80, rows: 15 },
-      }
-    );
+    const process = await notebook.terminals.create({
+      command: 'bash',
+      args: ['-lc', 'printf "sdk-prompt$"'],
+      osc: true,
+      size: [80, 15],
+    });
 
     try {
       const [exitCode, output] = await Promise.all([
-        withTimeout(process.exit, options.stepTimeoutMs, 'waiting for terminal OSC process exit'),
+        withTimeout(process.wait(), options.stepTimeoutMs, 'waiting for terminal OSC process exit'),
         readStreamToString(process.output, options.streamTimeoutMs, options.maxStreamChars),
       ]);
 
@@ -453,7 +450,7 @@ function recordSkippedStep(steps: StepArtifact[], name: string, detail: string):
   console.log(`SKIP ${name} ${detail}`);
 }
 
-async function readStreamToString(stream: ReadableStream<string>, timeoutMs: number, maxChars: number): Promise<string> {
+async function readStreamToString(stream: ReadableStream<string | Uint8Array>, timeoutMs: number, maxChars: number): Promise<string> {
   const reader = stream.getReader();
   let output = '';
 
@@ -463,7 +460,7 @@ async function readStreamToString(stream: ReadableStream<string>, timeoutMs: num
       if (chunk.done) {
         break;
       }
-      output += chunk.value ?? '';
+      output += chunk.value instanceof Uint8Array ? new TextDecoder().decode(chunk.value) : (chunk.value ?? '');
     }
     return output;
   } finally {