workerdeck 2.14.0 → 3.0.1

package/build/cli.mjs

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { a as ConfigError, d as parseArgs, f as resolveInstanceConfig, r as startInstance, u as loadConfigFile } from "./instance-Ca_DJTO5.mjs";
+import { a as ConfigError, d as parseArgs, f as resolveInstanceConfig, r as startInstance, u as loadConfigFile } from "./instance-CTA80T2q.mjs";
 import { dirname, join } from "node:path";
 import { readFile } from "node:fs/promises";
 import { fileURLToPath } from "node:url";
@@ -90,7 +90,14 @@ Options
                             with a tracked record. Off by default and its own switch:
                             unlike an agent's Bash tool, a '$' command goes through
                             no permission prompt at all. Never offered to a scoped
-                            principal.
+                            principal. The agent gets shell_list and shell_read.
+      --shell-agent-write <mode>
+                            what the agent may do to shells of its own with --shell:
+                            read-only (default: it only reads), gated (shell_run,
+                            shell_write and shell_kill behind a permission card,
+                            payload shown; config: shell.agentWrite) or allow (no
+                            card beyond the engine's own mode). Never a shell the
+                            user started, never a session a scoped principal made.
       --approval-timeout <d>
                             how long a permission prompt or a question may wait for
                             an answer before the engine denies it (300000, 30s, 5m;
@@ -164,7 +171,7 @@ function line(text) {
 }
 async function main(argv) {
 	if (argv[0] === "reload") {
-		const { runReload } = await import("./reload-command-Bou3X_hM.mjs");
+		const { runReload } = await import("./reload-command-C1rfoCrl.mjs");
 		return await runReload(argv.slice(1));
 	}
 	if (argv[0] === "guard") {

package/build/cli.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"cli.mjs","names":[],"sources":["../src/lib/shutdown.ts","../src/cli.ts"],"sourcesContent":["import type { Instance } from './instance.ts'\n\nexport type ShutdownOptions = {\n  // A getter, not an instance: under --hot-reload the instance is replaced on every reload, and a captured one\n  // would drain a server that stopped listening several generations ago.\n  current: () => Instance\n  // Runners this process holds outside any instance, which under --hot-reload is what a failed generation leaves\n  // behind: no registry holds them, so `close()` cannot reach them and nothing else ends their engine children.\n  alsoClose?: () => { close: (reason?: 'client' | 'server' | 'error') => void }[]\n  log?: (text: string) => void\n}\n\nexport function installShutdown({\n  current,\n  alsoClose,\n  log = (text) => void process.stdout.write(`${text}\\n`),\n}: ShutdownOptions): (signal: string) => void {\n  // A second signal must always be able to kill a shutdown that is taking too long. That used to work only by\n  // accident - the second call re-entered `instance.close()` and got an immediate callback out of an already-closed\n  // http server - so it evaporated the moment close stopped being idempotent-by-luck. Make it a real path.\n  let shuttingDown = false\n  const shutdown = (signal: string): void => {\n    if (shuttingDown) {\n      process.stdout.write(`\\n[workerdeck] ${signal} again - terminating now\\n`)\n      // Shell children are detached group leaders, so a plain exit orphans every one of them.\n      current().server.shells?.killAllSync()\n      process.exit(130)\n    }\n    shuttingDown = true\n    log(`\\n[workerdeck] ${signal} - shutting down (press again to stop now)`)\n    const instance = current()\n    const running = instance.server.shells?.running() ?? []\n    if (running.length > 0) {\n      const named = running.map((shell) => `#${shell.ordinal} ${shell.label} (session ${shell.sessionId.slice(0, 8)})`).join(', ')\n      log(`[workerdeck] ${running.length} shell(s) still running and will be stopped: ${named}`)\n    }\n    instance\n      .drain({\n        onProgress: (report) => {\n          if (report.working.length > 0) {\n            log(`[workerdeck] waiting for ${report.working.length} session(s) to finish the current turn`)\n          }\n          // Named, not waited for: nothing about shutting down answers a permission prompt.\n          for (const id of report.awaitingHuman) {\n            log(`[workerdeck] session ${id} is waiting on an approval - not waiting for it`)\n          }\n          if (report.timedOut) {\n            log(`[workerdeck] ${report.working.length} session(s) still running - stopping anyway`)\n          } else if (report.working.length === 0) {\n            log('[workerdeck] all turns finished')\n          }\n        },\n      })\n      .catch(() => undefined)\n      .then(() => instance.close())\n      .then(() => {\n        for (const runner of alsoClose?.() ?? []) {\n          runner.close('server')\n        }\n      })\n      .then(() => process.exit(0))\n      .catch(() => process.exit(1))\n  }\n  process.on('SIGINT', () => shutdown('SIGINT'))\n  process.on('SIGTERM', () => shutdown('SIGTERM'))\n  // Returned for the one caller that cannot rely on the signal: a raw-mode TTY delivers ctrl-c as a byte, not SIGINT.\n  return shutdown\n}\n","#!/usr/bin/env node\nimport { spawn } from 'node:child_process'\nimport { readFile } from 'node:fs/promises'\nimport { dirname, join } from 'node:path'\nimport { fileURLToPath } from 'node:url'\nimport { ConfigError, loadConfigFile, parseArgs, resolveInstanceConfig } from './config.ts'\nimport { startInstance } from './lib/instance.ts'\nimport { installShutdown } from './lib/shutdown.ts'\n\nconst HELP = `workerdeck - run a workerdeck instance: session gateway + dashboard, one port.\n\nUsage\n  workerdeck [options]\n  workerdeck guard [options]     check whether it is safe to restart an instance\n  workerdeck reload [options]    hot-reload a gateway started with --hot-reload\n\nOptions\n  -p, --port <n>            port to listen on (default 8787, WORKERDECK_PORT)\n      --host <addr>         interface to bind (default 127.0.0.1, WORKERDECK_HOST)\n      --auth-key <secret>   shared secret, min 12 chars; browsers log in with it,\n                            services send it as x-workerdeck-key\n                            (WORKERDECK_AUTH_KEY). Unset = no auth on loopback;\n                            on any other interface a key is generated instead,\n                            printed once, and stored in <state-dir>/auth-key for\n                            later starts to reuse.\n      --trust-proxy         trust x-forwarded-proto/-host/-for from one reverse\n                            proxy. Required behind TLS termination, or the session\n                            cookie loses its Secure flag and the origin check\n                            computes http:// where the browser says https://.\n      --allowed-origin <o>  extra origin accepted on browser requests, for when a\n                            proxy rewrites Host (repeatable)\n      --allowed-host <name> extra Host header accepted when running without auth\n                            (repeatable; loopback names are always accepted)\n      --insecure-host <name>\n                            bind host that may serve without auth - no key demanded,\n                            none generated - and, while unauthenticated, also\n                            accepted as a Host header (repeatable; config:\n                            insecureHosts). Names the host alone, no port.\n      --profile <name=dir>  Claude config dir a session may run under (repeatable). Declared\n                            this way a profile is fixed: it cannot be changed over the API.\n      --profile-root <path> directory a profile created at runtime may point its config dir at\n                            (repeatable; default: your home directory). Narrow this to pin\n                            exactly which credential stores the dashboard may reach for.\n      --no-profile-store    refuse runtime profile management entirely - /v1/profiles stays\n                            read-only and profiles come from --profile and the config file\n                            alone. Profiles created at runtime are stored in\n                            <state-dir>/profiles.json, so --no-parking-store implies this.\n      --cwd-root <path>     restrict session cwds to this root (repeatable,\n                            WORKERDECK_CWD_ROOTS as a ':'-separated list)\n      --fs-root <path>      narrow which host directories /v1/fs serves\n                            (repeatable, WORKERDECK_FS_ROOTS as a ':'-separated\n                            list). Reading otherwise follows --cwd-root: a caller\n                            who may start a session in a tree can already read it\n                            through the agent. With neither, the routes 404.\n      --fs-write            also accept writes over /v1/fs. Its own switch because\n                            an agent's writes go through the permission flow and a\n                            PUT does not. Every write is still conditional on the\n                            hash the client last read.\n      --shell               let an operator run '$' shell commands on the host from\n                            the composer, in the session's cwd. Every one is a PTY\n                            with a tracked record. Off by default and its own switch:\n                            unlike an agent's Bash tool, a '$' command goes through\n                            no permission prompt at all. Never offered to a scoped\n                            principal.\n      --approval-timeout <d>\n                            how long a permission prompt or a question may wait for\n                            an answer before the engine denies it (300000, 30s, 5m;\n                            config: approvalTimeoutMs). Default 'none' - a prompt\n                            waits as long as the session lives. A session may\n                            override it per request.\n      --state-dir <path>    where parked sessions are persisted\n                            (default: beside the config file, else ~/.workerdeck)\n      --no-parking-store    keep parked sessions in memory only; a restart drops them\n  -c, --config <path>       config file (default: ./workerdeck.config.mjs)\n      --insecure            allow no-auth on a non-loopback address. Only when\n                            something in front is doing the authenticating.\n      --cors-origin <o>     browser origin allowed to call /v1 cross-origin, for a\n                            dashboard served elsewhere (repeatable, exact origin, no\n                            wildcard; config: corsOrigins). Refused without auth. The\n                            key is still required - this only permits the call.\n      --no-keep-awake       don't hold the machine awake while a session is waiting\n                            on it (config: keepAwake: false). By default a turn in\n                            flight, or a session blocked on an approval, blocks idle\n                            sleep - a laptop sleeping mid-turn drops the socket and\n                            burns the turn. The screen is never kept on, and the\n                            lock releases the moment nothing is waiting.\n      --no-web              don't serve the web dashboard (config: web: false).\n                            /v1 and the auth routes are unchanged; everything else\n                            404s. For a gateway reached only from the VS Code\n                            extension, the phone, or another host's dashboard.\n      --open                open the dashboard in a browser once it is up\n      --hot-reload          dev only: re-evaluate the gateway's own source in place on\n                            ctrl-r, SIGUSR2 or \\`workerdeck reload\\`, carrying live\n                            sessions and their engine child processes across the swap.\n                            Needs a source checkout; the published CLI is one bundled\n                            file with nothing to swap.\n  -h, --help                show this\n  -v, --version             print the version\n\nConfig file\n  Options that cannot fit on a command line - \\`authenticate\\`, \\`buildRunnerConfig\\`,\n  \\`createEngineRunner\\` are functions - live in workerdeck.config.mjs, which\n  default-exports the createWorkerServer options (or a function returning them).\n  Flags and env override it. Supplying your own \\`authenticate\\` turns the built-in\n  shared-secret auth off entirely.\n\nCredentials\n  workerdeck implements no Anthropic auth of its own: the official SDK/CLI\n  resolves credentials from the environment, per profile. --auth-key protects this\n  gateway, nothing else.\n`\n\nasync function readVersion(): Promise<string> {\n  // src/cli.ts and build/cli.mjs are both one level under the package root.\n  const pkgPath = join(dirname(fileURLToPath(import.meta.url)), '..', 'package.json')\n  try {\n    const raw = await readFile(pkgPath, 'utf8')\n    return (JSON.parse(raw) as { version?: string }).version ?? 'unknown'\n  } catch {\n    return 'unknown'\n  }\n}\n\nfunction openInBrowser(url: string): void {\n  const command = process.platform === 'darwin' ? 'open' : process.platform === 'win32' ? 'start' : 'xdg-open'\n  try {\n    const child = spawn(command, [url], {\n      stdio: 'ignore',\n      detached: true,\n      shell: process.platform === 'win32',\n    })\n    child.on('error', () => {})\n    child.unref()\n  } catch {}\n}\n\nfunction line(text: string): void {\n  process.stdout.write(`${text}\\n`)\n}\n\nasync function main(argv: string[]): Promise<number> {\n  if (argv[0] === 'reload') {\n    const { runReload } = await import('./dev/reload-command.ts')\n    return await runReload(argv.slice(1))\n  }\n\n  if (argv[0] === 'guard') {\n    const { runGuard } = await import('./lib/guard.ts')\n    return await runGuard(argv.slice(1))\n  }\n\n  const flags = parseArgs(argv)\n  if (flags.help) {\n    process.stdout.write(HELP)\n    return 0\n  }\n  if (flags.version) {\n    process.stdout.write(`${await readVersion()}\\n`)\n    return 0\n  }\n\n  if (flags.hotReload) {\n    const { runHotReload } = await import('./dev/hot-reload.ts')\n    const result = await runHotReload(flags)\n    if (result !== 'unsupported') {\n      return result\n    }\n  }\n\n  const loaded = await loadConfigFile(flags.config)\n  const config = resolveInstanceConfig(flags, loaded)\n  const instance = await startInstance(config)\n\n  if (config.open) {\n    openInBrowser(instance.url)\n  }\n\n  installShutdown({ current: () => instance, log: line })\n\n  // Resolves only on close: until then the process stays up, serving.\n  await instance.closed\n  return 0\n}\n\nmain(process.argv.slice(2))\n  .then((code) => {\n    if (code !== 0) {\n      process.exit(code)\n    }\n  })\n  .catch((error: unknown) => {\n    if (error instanceof ConfigError) {\n      process.stderr.write(`[workerdeck] ${error.message}\\n`)\n      process.exit(2)\n    }\n    process.stderr.write(`[workerdeck] ${error instanceof Error ? (error.stack ?? error.message) : String(error)}\\n`)\n    process.exit(1)\n  })\n"],"mappings":"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"}
+{"version":3,"file":"cli.mjs","names":[],"sources":["../src/lib/shutdown.ts","../src/cli.ts"],"sourcesContent":["import type { Instance } from './instance.ts'\n\nexport type ShutdownOptions = {\n  // A getter, not an instance: under --hot-reload the instance is replaced on every reload, and a captured one\n  // would drain a server that stopped listening several generations ago.\n  current: () => Instance\n  // Runners this process holds outside any instance, which under --hot-reload is what a failed generation leaves\n  // behind: no registry holds them, so `close()` cannot reach them and nothing else ends their engine children.\n  alsoClose?: () => { close: (reason?: 'client' | 'server' | 'error') => void }[]\n  log?: (text: string) => void\n}\n\nexport function installShutdown({\n  current,\n  alsoClose,\n  log = (text) => void process.stdout.write(`${text}\\n`),\n}: ShutdownOptions): (signal: string) => void {\n  // A second signal must always be able to kill a shutdown that is taking too long. That used to work only by\n  // accident - the second call re-entered `instance.close()` and got an immediate callback out of an already-closed\n  // http server - so it evaporated the moment close stopped being idempotent-by-luck. Make it a real path.\n  let shuttingDown = false\n  const shutdown = (signal: string): void => {\n    if (shuttingDown) {\n      process.stdout.write(`\\n[workerdeck] ${signal} again - terminating now\\n`)\n      // Shell children are detached group leaders, so a plain exit orphans every one of them.\n      current().server.shells?.killAllSync()\n      process.exit(130)\n    }\n    shuttingDown = true\n    log(`\\n[workerdeck] ${signal} - shutting down (press again to stop now)`)\n    const instance = current()\n    const running = instance.server.shells?.running() ?? []\n    if (running.length > 0) {\n      const named = running.map((shell) => `#${shell.ordinal} ${shell.label} (session ${shell.sessionId.slice(0, 8)})`).join(', ')\n      log(`[workerdeck] ${running.length} shell(s) still running and will be stopped: ${named}`)\n    }\n    instance\n      .drain({\n        onProgress: (report) => {\n          if (report.working.length > 0) {\n            log(`[workerdeck] waiting for ${report.working.length} session(s) to finish the current turn`)\n          }\n          // Named, not waited for: nothing about shutting down answers a permission prompt.\n          for (const id of report.awaitingHuman) {\n            log(`[workerdeck] session ${id} is waiting on an approval - not waiting for it`)\n          }\n          if (report.timedOut) {\n            log(`[workerdeck] ${report.working.length} session(s) still running - stopping anyway`)\n          } else if (report.working.length === 0) {\n            log('[workerdeck] all turns finished')\n          }\n        },\n      })\n      .catch(() => undefined)\n      .then(() => instance.close())\n      .then(() => {\n        for (const runner of alsoClose?.() ?? []) {\n          runner.close('server')\n        }\n      })\n      .then(() => process.exit(0))\n      .catch(() => process.exit(1))\n  }\n  process.on('SIGINT', () => shutdown('SIGINT'))\n  process.on('SIGTERM', () => shutdown('SIGTERM'))\n  // Returned for the one caller that cannot rely on the signal: a raw-mode TTY delivers ctrl-c as a byte, not SIGINT.\n  return shutdown\n}\n","#!/usr/bin/env node\nimport { spawn } from 'node:child_process'\nimport { readFile } from 'node:fs/promises'\nimport { dirname, join } from 'node:path'\nimport { fileURLToPath } from 'node:url'\nimport { ConfigError, loadConfigFile, parseArgs, resolveInstanceConfig } from './config.ts'\nimport { startInstance } from './lib/instance.ts'\nimport { installShutdown } from './lib/shutdown.ts'\n\nconst HELP = `workerdeck - run a workerdeck instance: session gateway + dashboard, one port.\n\nUsage\n  workerdeck [options]\n  workerdeck guard [options]     check whether it is safe to restart an instance\n  workerdeck reload [options]    hot-reload a gateway started with --hot-reload\n\nOptions\n  -p, --port <n>            port to listen on (default 8787, WORKERDECK_PORT)\n      --host <addr>         interface to bind (default 127.0.0.1, WORKERDECK_HOST)\n      --auth-key <secret>   shared secret, min 12 chars; browsers log in with it,\n                            services send it as x-workerdeck-key\n                            (WORKERDECK_AUTH_KEY). Unset = no auth on loopback;\n                            on any other interface a key is generated instead,\n                            printed once, and stored in <state-dir>/auth-key for\n                            later starts to reuse.\n      --trust-proxy         trust x-forwarded-proto/-host/-for from one reverse\n                            proxy. Required behind TLS termination, or the session\n                            cookie loses its Secure flag and the origin check\n                            computes http:// where the browser says https://.\n      --allowed-origin <o>  extra origin accepted on browser requests, for when a\n                            proxy rewrites Host (repeatable)\n      --allowed-host <name> extra Host header accepted when running without auth\n                            (repeatable; loopback names are always accepted)\n      --insecure-host <name>\n                            bind host that may serve without auth - no key demanded,\n                            none generated - and, while unauthenticated, also\n                            accepted as a Host header (repeatable; config:\n                            insecureHosts). Names the host alone, no port.\n      --profile <name=dir>  Claude config dir a session may run under (repeatable). Declared\n                            this way a profile is fixed: it cannot be changed over the API.\n      --profile-root <path> directory a profile created at runtime may point its config dir at\n                            (repeatable; default: your home directory). Narrow this to pin\n                            exactly which credential stores the dashboard may reach for.\n      --no-profile-store    refuse runtime profile management entirely - /v1/profiles stays\n                            read-only and profiles come from --profile and the config file\n                            alone. Profiles created at runtime are stored in\n                            <state-dir>/profiles.json, so --no-parking-store implies this.\n      --cwd-root <path>     restrict session cwds to this root (repeatable,\n                            WORKERDECK_CWD_ROOTS as a ':'-separated list)\n      --fs-root <path>      narrow which host directories /v1/fs serves\n                            (repeatable, WORKERDECK_FS_ROOTS as a ':'-separated\n                            list). Reading otherwise follows --cwd-root: a caller\n                            who may start a session in a tree can already read it\n                            through the agent. With neither, the routes 404.\n      --fs-write            also accept writes over /v1/fs. Its own switch because\n                            an agent's writes go through the permission flow and a\n                            PUT does not. Every write is still conditional on the\n                            hash the client last read.\n      --shell               let an operator run '$' shell commands on the host from\n                            the composer, in the session's cwd. Every one is a PTY\n                            with a tracked record. Off by default and its own switch:\n                            unlike an agent's Bash tool, a '$' command goes through\n                            no permission prompt at all. Never offered to a scoped\n                            principal. The agent gets shell_list and shell_read.\n      --shell-agent-write <mode>\n                            what the agent may do to shells of its own with --shell:\n                            read-only (default: it only reads), gated (shell_run,\n                            shell_write and shell_kill behind a permission card,\n                            payload shown; config: shell.agentWrite) or allow (no\n                            card beyond the engine's own mode). Never a shell the\n                            user started, never a session a scoped principal made.\n      --approval-timeout <d>\n                            how long a permission prompt or a question may wait for\n                            an answer before the engine denies it (300000, 30s, 5m;\n                            config: approvalTimeoutMs). Default 'none' - a prompt\n                            waits as long as the session lives. A session may\n                            override it per request.\n      --state-dir <path>    where parked sessions are persisted\n                            (default: beside the config file, else ~/.workerdeck)\n      --no-parking-store    keep parked sessions in memory only; a restart drops them\n  -c, --config <path>       config file (default: ./workerdeck.config.mjs)\n      --insecure            allow no-auth on a non-loopback address. Only when\n                            something in front is doing the authenticating.\n      --cors-origin <o>     browser origin allowed to call /v1 cross-origin, for a\n                            dashboard served elsewhere (repeatable, exact origin, no\n                            wildcard; config: corsOrigins). Refused without auth. The\n                            key is still required - this only permits the call.\n      --no-keep-awake       don't hold the machine awake while a session is waiting\n                            on it (config: keepAwake: false). By default a turn in\n                            flight, or a session blocked on an approval, blocks idle\n                            sleep - a laptop sleeping mid-turn drops the socket and\n                            burns the turn. The screen is never kept on, and the\n                            lock releases the moment nothing is waiting.\n      --no-web              don't serve the web dashboard (config: web: false).\n                            /v1 and the auth routes are unchanged; everything else\n                            404s. For a gateway reached only from the VS Code\n                            extension, the phone, or another host's dashboard.\n      --open                open the dashboard in a browser once it is up\n      --hot-reload          dev only: re-evaluate the gateway's own source in place on\n                            ctrl-r, SIGUSR2 or \\`workerdeck reload\\`, carrying live\n                            sessions and their engine child processes across the swap.\n                            Needs a source checkout; the published CLI is one bundled\n                            file with nothing to swap.\n  -h, --help                show this\n  -v, --version             print the version\n\nConfig file\n  Options that cannot fit on a command line - \\`authenticate\\`, \\`buildRunnerConfig\\`,\n  \\`createEngineRunner\\` are functions - live in workerdeck.config.mjs, which\n  default-exports the createWorkerServer options (or a function returning them).\n  Flags and env override it. Supplying your own \\`authenticate\\` turns the built-in\n  shared-secret auth off entirely.\n\nCredentials\n  workerdeck implements no Anthropic auth of its own: the official SDK/CLI\n  resolves credentials from the environment, per profile. --auth-key protects this\n  gateway, nothing else.\n`\n\nasync function readVersion(): Promise<string> {\n  // src/cli.ts and build/cli.mjs are both one level under the package root.\n  const pkgPath = join(dirname(fileURLToPath(import.meta.url)), '..', 'package.json')\n  try {\n    const raw = await readFile(pkgPath, 'utf8')\n    return (JSON.parse(raw) as { version?: string }).version ?? 'unknown'\n  } catch {\n    return 'unknown'\n  }\n}\n\nfunction openInBrowser(url: string): void {\n  const command = process.platform === 'darwin' ? 'open' : process.platform === 'win32' ? 'start' : 'xdg-open'\n  try {\n    const child = spawn(command, [url], {\n      stdio: 'ignore',\n      detached: true,\n      shell: process.platform === 'win32',\n    })\n    child.on('error', () => {})\n    child.unref()\n  } catch {}\n}\n\nfunction line(text: string): void {\n  process.stdout.write(`${text}\\n`)\n}\n\nasync function main(argv: string[]): Promise<number> {\n  if (argv[0] === 'reload') {\n    const { runReload } = await import('./dev/reload-command.ts')\n    return await runReload(argv.slice(1))\n  }\n\n  if (argv[0] === 'guard') {\n    const { runGuard } = await import('./lib/guard.ts')\n    return await runGuard(argv.slice(1))\n  }\n\n  const flags = parseArgs(argv)\n  if (flags.help) {\n    process.stdout.write(HELP)\n    return 0\n  }\n  if (flags.version) {\n    process.stdout.write(`${await readVersion()}\\n`)\n    return 0\n  }\n\n  if (flags.hotReload) {\n    const { runHotReload } = await import('./dev/hot-reload.ts')\n    const result = await runHotReload(flags)\n    if (result !== 'unsupported') {\n      return result\n    }\n  }\n\n  const loaded = await loadConfigFile(flags.config)\n  const config = resolveInstanceConfig(flags, loaded)\n  const instance = await startInstance(config)\n\n  if (config.open) {\n    openInBrowser(instance.url)\n  }\n\n  installShutdown({ current: () => instance, log: line })\n\n  // Resolves only on close: until then the process stays up, serving.\n  await instance.closed\n  return 0\n}\n\nmain(process.argv.slice(2))\n  .then((code) => {\n    if (code !== 0) {\n      process.exit(code)\n    }\n  })\n  .catch((error: unknown) => {\n    if (error instanceof ConfigError) {\n      process.stderr.write(`[workerdeck] ${error.message}\\n`)\n      process.exit(2)\n    }\n    process.stderr.write(`[workerdeck] ${error instanceof Error ? (error.stack ?? error.message) : String(error)}\\n`)\n    process.exit(1)\n  })\n"],"mappings":"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"}

package/build/index.d.mts

@@ -1,4 +1,4 @@
-import { Authenticator, CarriedSession, WorkerServer, WorkerServerOptions } from "@workerdeck/server";
+import { Authenticator, CarriedSession, ShellAgentWriteOption, WorkerServer, WorkerServerOptions } from "@workerdeck/server";
 import { KeyObject } from "node:crypto";
 import { ProfileInfo, SessionNotification, SessionNotificationType, SubagentInfo } from "@workerdeck/protocol";
 import { IncomingMessage, ServerResponse } from "node:http";
@@ -105,6 +105,7 @@ type CliFlags = {
   profileStore?: boolean;
   fsWrite?: boolean;
   shell?: boolean;
+  shellAgentWrite?: ShellAgentWriteOption;
   allowedOrigins: string[];
   allowedHosts: string[];
   insecureHosts: string[];

package/build/index.mjs

@@ -1,3 +1,3 @@
 import { n as runGuard } from "./guard-C4ybpzbt.mjs";
-import { C as createActivityRegistry, S as createDeviceRoute, _ as createApnsForwarder, a as ConfigError, b as createApnsRoute, c as isLoopback, d as parseArgs, f as resolveInstanceConfig, g as buildPush, h as materializeAuthKey, i as renderLoginPage, l as isLoopbackHostname, m as createAuthSessionStore, n as resolveWebRoot, o as defaultStateDir, p as createCliAuth, r as startInstance, s as hostnameOf, t as createHostGuard, u as loadConfigFile, v as createApnsClient, w as createActivityRoute, x as createDeviceRegistry, y as loadApnsKey } from "./instance-Ca_DJTO5.mjs";
+import { C as createActivityRegistry, S as createDeviceRoute, _ as createApnsForwarder, a as ConfigError, b as createApnsRoute, c as isLoopback, d as parseArgs, f as resolveInstanceConfig, g as buildPush, h as materializeAuthKey, i as renderLoginPage, l as isLoopbackHostname, m as createAuthSessionStore, n as resolveWebRoot, o as defaultStateDir, p as createCliAuth, r as startInstance, s as hostnameOf, t as createHostGuard, u as loadConfigFile, v as createApnsClient, w as createActivityRoute, x as createDeviceRegistry, y as loadApnsKey } from "./instance-CTA80T2q.mjs";
 export { ConfigError, buildPush, createActivityRegistry, createActivityRoute, createApnsClient, createApnsForwarder, createApnsRoute, createAuthSessionStore, createCliAuth, createDeviceRegistry, createDeviceRoute, createHostGuard, defaultStateDir, hostnameOf, isLoopback, isLoopbackHostname, loadApnsKey, loadConfigFile, materializeAuthKey, parseArgs, renderLoginPage, resolveInstanceConfig, resolveWebRoot, runGuard, startInstance };

package/build/{instance-Ca_DJTO5.mjs → instance-CTA80T2q.mjs}

@@ -1697,6 +1697,10 @@ function parseDuration(raw, source) {
 	const ms = Number(match[1]) * scale;
 	return ms > 0 ? ms : null;
 }
+function parseShellAgentWrite(value, name) {
+	if (value === "read-only" || value === "gated" || value === "allow") return value;
+	throw new ConfigError(`${name} must be read-only, gated or allow (got '${value}')`);
+}
 function parsePort(raw, source) {
 	const port = Number(raw);
 	if (!Number.isInteger(port) || port < 0 || port > 65535) throw new ConfigError(`${source}: not a valid port: ${raw}`);
@@ -1782,6 +1786,10 @@ function parseArgs(argv) {
 			case "--shell":
 				flags.shell = true;
 				break;
+			case "--shell-agent-write":
+				flags.shellAgentWrite = parseShellAgentWrite(next(i, arg), arg);
+				i++;
+				break;
 			case "--allowed-origin":
 				flags.allowedOrigins.push(next(i, arg));
 				i++;
@@ -1940,9 +1948,10 @@ function resolveInstanceConfig(flags, loaded, env = process.env, cwd = process.c
 		...fsRoots?.length ? { roots: fsRoots } : {},
 		...flags.fsWrite ? { write: true } : {}
 	};
-	if (flags.shell) options.shell = {
+	if (flags.shell || flags.shellAgentWrite !== void 0) options.shell = {
 		...loaded.options.shell,
-		enabled: true
+		...flags.shell ? { enabled: true } : {},
+		...flags.shellAgentWrite !== void 0 ? { agentWrite: flags.shellAgentWrite } : {}
 	};
 	if (flags.profiles.length) options.profiles = flags.profiles;
 	if (flags.approvalTimeoutMs !== void 0) options.approvalTimeoutMs = flags.approvalTimeoutMs;
@@ -2429,4 +2438,4 @@ async function startInstance(config, options = {}) {
 //#endregion
 export { createActivityRegistry as C, createDeviceRoute as S, createApnsForwarder as _, ConfigError as a, createApnsRoute as b, isLoopback as c, parseArgs as d, resolveInstanceConfig as f, buildPush as g, materializeAuthKey as h, renderLoginPage as i, isLoopbackHostname as l, createAuthSessionStore as m, resolveWebRoot as n, defaultStateDir as o, createCliAuth as p, startInstance as r, hostnameOf as s, createHostGuard as t, loadConfigFile as u, createApnsClient as v, createActivityRoute as w, createDeviceRegistry as x, loadApnsKey as y };
 
-//# sourceMappingURL=instance-Ca_DJTO5.mjs.map
+//# sourceMappingURL=instance-CTA80T2q.mjs.map