dsh-pstack 0.0.0-stage → 0.2.0-beta.1

package/dist/script.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"script.mjs","names":["spawnChild"],"sources":["../scripts/runtime-manifest.ts","../src/script.ts"],"sourcesContent":["/**\n * The shipped script runtime, as one table.\n *\n * pstack ships five CLIs and five test bundles. None of them may require Bun,\n * bash, a `node_modules` tree beside them, or an install step: the npm package\n * installs into a profile whose workspace resolves no peer dependencies, and the\n * Desktop build runs the same package under Electron, where `node` is not on\n * `PATH`.\n *\n * So every shipped script is a single-file Node bundle produced by\n * `scripts/build-runtime.ts` and copied into `assets/` by `scripts/build-assets.ts`.\n * This module is the one place that says what ships and where it lands; the\n * bundler, the asset generator, and the checks read it instead of keeping their\n * own copy.\n *\n * Two source origins:\n *\n * - `upstream` — the pinned upstream TypeScript, rewritten by\n *   `RUNTIME_SOURCE_PATCHES` before it is bundled. `orch`, `watch-pr`,\n *   `check-plan` and their tests stay upstream sources so they keep tracking their\n *   original instead of becoming a fork of it.\n * - `authored` — this repository's own Node implementation under\n *   `scripts/runtime/`. `log` and `worktree-audit` are here because their upstream\n *   form is a shell script; their behaviour is specified by that script and\n *   re-implemented.\n */\n\n/** Where a shipped artifact's source text comes from. */\nexport type RuntimeSourceKind = \"authored\" | \"upstream\";\n\nexport interface RuntimeSource {\n  readonly kind: RuntimeSourceKind;\n  /** Repository-relative POSIX path. */\n  readonly path: string;\n}\n\nexport interface RuntimeEntry {\n  /** Stable id, used in logs and by the Host tool's `id` enum. */\n  readonly id: string;\n  /** A runnable CLI, or a test bundle run by `node --test`. */\n  readonly kind: \"cli\" | \"test\";\n  /** Bundler entry file. */\n  readonly entry: RuntimeSource;\n  /** Output path relative to `runtime/`. */\n  readonly out: string;\n  /** The same path below `assets/`. */\n  readonly assetPath: string;\n  /** Whether the artifact is meant to be executed directly. */\n  readonly executable: boolean;\n  /**\n   * Every source the build touches, entry first.\n   *\n   * The bundler follows imports itself, so this is not a module list: it is the\n   * set staged before the build and the set whose patches must all land. A file\n   * missing here would either fail to resolve or silently skip its rewrite.\n   */\n  readonly sources: readonly RuntimeSource[];\n  /** One line for `build-runtime` output. */\n  readonly summary: string;\n}\n\n/** Upstream script directories whose contents the built artifacts replace. */\nexport const REPLACED_SCRIPT_DIRECTORIES: readonly string[] = [\n  \"skills/poteto-mode/scripts/\",\n  \"skills/show-me-your-work/scripts/\",\n];\n\n/** The directory holding the authored runtime sources. */\nexport const AUTHORED_ROOT = \"scripts/runtime/\";\n\n/** Support modules the ported tests import instead of `bun:test`. */\nexport const TEST_SUPPORT: readonly RuntimeSource[] = [\n  { kind: \"authored\", path: `${AUTHORED_ROOT}tests/expect.ts` },\n  { kind: \"authored\", path: `${AUTHORED_ROOT}tests/support.ts` },\n];\n\n/**\n * Where the support modules land inside the staged source tree.\n *\n * `support.ts` re-exports from `./expect.ts`, so the pair has to stay adjacent.\n * Staging them at the root of `poteto-mode/scripts` lets `orch/` and `watch-pr/`\n * both reach them through `../support.ts` with one copy, instead of one copy per\n * test directory.\n */\nexport const TEST_SUPPORT_STAGED_PREFIX = \"skills/poteto-mode/scripts/\";\n\n/** `TEST_SUPPORT` as entry sources, so a test entry declares what it imports. */\nconst TEST_SUPPORT_ROOTS: readonly RuntimeSource[] = TEST_SUPPORT;\n\nconst upstreamScript = (path: string): RuntimeSource => ({\n  kind: \"upstream\",\n  path: `skills/poteto-mode/scripts/${path}`,\n});\n\n/** CLI artifacts, in the order the reviews and the prose name them. */\nexport const RUNTIME_CLIS: readonly RuntimeEntry[] = [\n  {\n    id: \"check-plan\",\n    kind: \"cli\",\n    entry: upstreamScript(\"check-plan.mjs\"),\n    out: \"check-plan.mjs\",\n    assetPath: \"skills/poteto-mode/scripts/check-plan.mjs\",\n    executable: true,\n    sources: [upstreamScript(\"check-plan.mjs\")],\n    summary: \"plan-shape checker\",\n  },\n  {\n    id: \"orch\",\n    kind: \"cli\",\n    entry: upstreamScript(\"orch/orch.ts\"),\n    out: \"orch/orch.mjs\",\n    assetPath: \"skills/poteto-mode/scripts/orch/orch.mjs\",\n    executable: true,\n    sources: [upstreamScript(\"orch/orch.ts\"), upstreamScript(\"orch/store.ts\")],\n    summary: \"orchestration bookkeeping store\",\n  },\n  {\n    id: \"watch-pr\",\n    kind: \"cli\",\n    entry: upstreamScript(\"watch-pr/watch-pr\"),\n    out: \"watch-pr/watch-pr.mjs\",\n    assetPath: \"skills/poteto-mode/scripts/watch-pr/watch-pr.mjs\",\n    executable: true,\n    sources: [\n      upstreamScript(\"watch-pr/watch-pr\"),\n      upstreamScript(\"watch-pr/cli.ts\"),\n      upstreamScript(\"watch-pr/github.ts\"),\n      upstreamScript(\"watch-pr/policy.ts\"),\n      upstreamScript(\"watch-pr/render.ts\"),\n      upstreamScript(\"watch-pr/types.ts\"),\n    ],\n    summary: \"pull-request watcher\",\n  },\n  {\n    id: \"worktree-audit\",\n    kind: \"cli\",\n    entry: { kind: \"authored\", path: `${AUTHORED_ROOT}worktree-audit.ts` },\n    out: \"worktree-audit.mjs\",\n    assetPath: \"skills/poteto-mode/scripts/worktree-audit.mjs\",\n    executable: true,\n    sources: [{ kind: \"authored\", path: `${AUTHORED_ROOT}worktree-audit.ts` }],\n    summary: \"read-only worktree audit\",\n  },\n  {\n    id: \"log\",\n    kind: \"cli\",\n    entry: { kind: \"authored\", path: `${AUTHORED_ROOT}log.ts` },\n    out: \"log.mjs\",\n    assetPath: \"skills/show-me-your-work/scripts/log.mjs\",\n    executable: true,\n    sources: [{ kind: \"authored\", path: `${AUTHORED_ROOT}log.ts` }],\n    summary: \"decision-log row appender\",\n  },\n];\n\n/** Test bundles, run by `node --test` from a copy with no install step. */\nexport const RUNTIME_TESTS: readonly RuntimeEntry[] = [\n  {\n    id: \"check-plan-test\",\n    kind: \"test\",\n    entry: upstreamScript(\"check-plan.test.ts\"),\n    out: \"check-plan.test.mjs\",\n    assetPath: \"skills/poteto-mode/scripts/check-plan.test.mjs\",\n    executable: false,\n    sources: [upstreamScript(\"check-plan.test.ts\")],\n    summary: \"check-plan tests\",\n  },\n  {\n    id: \"orch-test\",\n    kind: \"test\",\n    entry: upstreamScript(\"orch/orch.test.ts\"),\n    out: \"orch/orch.test.mjs\",\n    assetPath: \"skills/poteto-mode/scripts/orch/orch.test.mjs\",\n    executable: false,\n    sources: [\n      upstreamScript(\"orch/orch.test.ts\"),\n      upstreamScript(\"orch/store.ts\"),\n      ...TEST_SUPPORT_ROOTS,\n    ],\n    summary: \"orch tests\",\n  },\n  {\n    id: \"watch-pr-cli-test\",\n    kind: \"test\",\n    entry: upstreamScript(\"watch-pr/cli.test.ts\"),\n    out: \"watch-pr/cli.test.mjs\",\n    assetPath: \"skills/poteto-mode/scripts/watch-pr/cli.test.mjs\",\n    executable: false,\n    sources: [\n      upstreamScript(\"watch-pr/cli.test.ts\"),\n      upstreamScript(\"watch-pr/cli.ts\"),\n      upstreamScript(\"watch-pr/github.ts\"),\n      upstreamScript(\"watch-pr/policy.ts\"),\n      upstreamScript(\"watch-pr/render.ts\"),\n      upstreamScript(\"watch-pr/types.ts\"),\n      upstreamScript(\"watch-pr/fakes.test-helper.ts\"),\n      ...TEST_SUPPORT_ROOTS,\n    ],\n    summary: \"watch-pr argument and rendering tests\",\n  },\n  {\n    id: \"watch-pr-github-test\",\n    kind: \"test\",\n    entry: upstreamScript(\"watch-pr/github.test.ts\"),\n    out: \"watch-pr/github.test.mjs\",\n    assetPath: \"skills/poteto-mode/scripts/watch-pr/github.test.mjs\",\n    executable: false,\n    sources: [\n      upstreamScript(\"watch-pr/github.test.ts\"),\n      upstreamScript(\"watch-pr/github.ts\"),\n      upstreamScript(\"watch-pr/types.ts\"),\n      upstreamScript(\"watch-pr/fakes.test-helper.ts\"),\n      ...TEST_SUPPORT_ROOTS,\n    ],\n    summary: \"watch-pr GitHub reader tests\",\n  },\n  {\n    id: \"watch-pr-policy-test\",\n    kind: \"test\",\n    entry: upstreamScript(\"watch-pr/policy.test.ts\"),\n    out: \"watch-pr/policy.test.mjs\",\n    assetPath: \"skills/poteto-mode/scripts/watch-pr/policy.test.mjs\",\n    executable: false,\n    sources: [\n      upstreamScript(\"watch-pr/policy.test.ts\"),\n      upstreamScript(\"watch-pr/policy.ts\"),\n      upstreamScript(\"watch-pr/github.ts\"),\n      upstreamScript(\"watch-pr/types.ts\"),\n      upstreamScript(\"watch-pr/fakes.test-helper.ts\"),\n      ...TEST_SUPPORT_ROOTS,\n    ],\n    summary: \"watch-pr policy and queue tests\",\n  },\n];\n\n/** Every artifact, CLIs first. */\nexport const RUNTIME_ENTRIES: readonly RuntimeEntry[] = [...RUNTIME_CLIS, ...RUNTIME_TESTS];\n\n/** The shebang every emitted artifact starts with. */\nexport const SHEBANG = \"#!/usr/bin/env node\\n\";\n\n/** True when a repository-relative upstream path is replaced by a built artifact. */\nexport function isReplacedUpstreamScript(upstreamRelativePath: string): boolean {\n  return REPLACED_SCRIPT_DIRECTORIES.some((prefix) => upstreamRelativePath.startsWith(prefix));\n}\n\n/** Look up one entry by id. */\nexport function runtimeEntry(id: string): RuntimeEntry {\n  const entry = RUNTIME_ENTRIES.find((candidate) => candidate.id === id);\n  if (entry === undefined) throw new Error(`unknown runtime entry \"${id}\"`);\n  return entry;\n}\n","/**\n * `pstack_script`: run a bundled pstack script through the Host's own runtime.\n *\n * Every shipped CLI is a Node artefact inside this package. A model could always\n * write `node <path> …` into a shell, and that is exactly what breaks in the\n * Desktop build: Electron runs the same CLI, so `node` is not on `PATH` there.\n *\n * So the entry point is a tool, not a command. The tool spawns the artefact with\n * `process.execPath` — whichever binary is already running this Host, Node or\n * Electron — and passes `ELECTRON_RUN_AS_NODE=1` only when it is Electron. That is\n * what makes the npm CLI and the Desktop build behave the same without depending on\n * anything in `PATH`.\n *\n * The tool never accepts a path or a command string. `id` is a closed enum over the\n * shipped artefacts, resolved from this package, so a call cannot reach a script the\n * package does not contain. It is not a general shell: there is no `sh -c`, no glob\n * expansion by a shell, and no way to name another executable.\n */\n\nimport { spawn as spawnChild, type ChildProcess } from \"node:child_process\";\n\nimport type {\n  JobId,\n  JobsHost,\n  JsonSchemaNode,\n  SessionId,\n  ToolDefinition,\n  ToolRunContext,\n  ToolsHost,\n  WorkingDirectoryHost,\n} from \"./host-contract.ts\";\nimport { RUNTIME_CLIS } from \"../scripts/runtime-manifest.ts\";\nimport { ASSETS_ROOT } from \"./paths.ts\";\nimport { isAbsolute, join, resolve } from \"node:path\";\n\n/** Model-facing tool name. */\nexport const TOOL_NAME = \"pstack_script\";\n\n/** The shipped scripts this tool may run, in display order. */\nexport const SCRIPT_IDS = RUNTIME_CLIS.map((entry) => entry.id);\n\nexport type ScriptId = (typeof SCRIPT_IDS)[number];\n\n/** Default wall-clock limit for a foreground run. */\nexport const DEFAULT_TIMEOUT_MS = 120_000;\n\n/** Bounds a caller may set for one foreground run. */\nexport const MAX_TIMEOUT_MS = 600_000;\n\n/** Default cap on captured bytes per stream. */\nexport const DEFAULT_OUTPUT_LIMIT_BYTES = 64 * 1024;\n\n/** Raised for an argument problem, before anything is spawned. */\nexport class ScriptInputError extends Error {\n  constructor(message: string) {\n    super(message);\n    this.name = \"ScriptInputError\";\n  }\n}\n\n/** Raised when a shipped artefact is missing from this install. */\nexport class ScriptMissingError extends Error {\n  constructor(message: string) {\n    super(message);\n    this.name = \"ScriptMissingError\";\n  }\n}\n\n/** One parsed call. */\nexport interface ScriptArgs {\n  readonly id: ScriptId;\n  readonly args: readonly string[];\n  readonly cwd?: string;\n  readonly background: boolean;\n  readonly timeoutMs?: number;\n  readonly outputLimitBytes?: number;\n}\n\n/** What a foreground run produced. */\nexport interface ScriptResult {\n  readonly kind: \"foreground\";\n  readonly id: ScriptId;\n  readonly exitCode: number;\n  readonly signal: NodeJS.Signals | null;\n  readonly timedOut: boolean;\n  readonly stdout: string;\n  readonly stderr: string;\n  /** True when a stream was cut off at the limit. */\n  readonly stdoutTruncated: boolean;\n  readonly stderrTruncated: boolean;\n  readonly durationMs: number;\n}\n\n/** What a background run produced. */\nexport interface ScriptJobResult {\n  readonly kind: \"background\";\n  readonly id: ScriptId;\n  readonly jobId: JobId;\n  readonly status: string;\n}\n\n/** Either outcome, as the model sees it. */\nexport type ScriptOutcome = ScriptResult | ScriptJobResult;\n\n/** Absolute path of one shipped artefact. */\nexport function scriptPath(id: ScriptId): string {\n  const entry = RUNTIME_CLIS.find((candidate) => candidate.id === id);\n  if (entry === undefined) throw new ScriptInputError(`unknown script id \"${String(id)}\"`);\n  // `assetPath` is relative to the generated tree, e.g.\n  // `skills/poteto-mode/scripts/orch/orch.mjs`, which is exactly what `ASSETS_ROOT`\n  // is the parent of.\n  return join(ASSETS_ROOT, ...entry.assetPath.split(\"/\"));\n}\n\n/**\n * The environment a child gets.\n *\n * The one rule is the Electron selector. Under Electron, `process.execPath` is the\n * Desktop binary, which starts a browser window unless `ELECTRON_RUN_AS_NODE=1` tells\n * it to behave as Node. Under plain Node the variable is inert — Node ignores it —\n * so setting it unconditionally would also work; it is conditional here so the\n * environment of a normal run stays exactly the caller's, and the one code path that\n * needs it is visible.\n */\nexport function scriptEnvironment(\n  base: NodeJS.ProcessEnv = process.env,\n  // Only the field this decision reads is named, so a test can pass the two shapes\n  // that matter without fabricating a full `process.versions`. The cast is because\n  // `ProcessVersions` types `electron` as an optional literal this file does not own.\n  versions: { readonly electron?: string } = process.versions as { readonly electron?: string },\n): NodeJS.ProcessEnv {\n  if (versions.electron === undefined) return { ...base };\n  return { ...base, ELECTRON_RUN_AS_NODE: \"1\" };\n}\n\n/** Validate the raw tool arguments. */\nexport function parseScriptArgs(raw: unknown): ScriptArgs {\n  if (raw === null || typeof raw !== \"object\" || Array.isArray(raw)) {\n    throw new ScriptInputError(\"arguments must be an object\");\n  }\n  const record = raw as Record<string, unknown>;\n\n  for (const key of Object.keys(record)) {\n    if (![\"id\", \"args\", \"cwd\", \"background\", \"timeoutMs\", \"outputLimitBytes\"].includes(key)) {\n      throw new ScriptInputError(`unknown argument \"${key}\"`);\n    }\n  }\n\n  const id = record[\"id\"];\n  if (typeof id !== \"string\") throw new ScriptInputError('\"id\" must be a string');\n  if (!(SCRIPT_IDS as readonly string[]).includes(id)) {\n    throw new ScriptInputError(\n      `\"id\" must be one of ${SCRIPT_IDS.join(\", \")}; this tool runs bundled scripts only`,\n    );\n  }\n\n  const rawArgs = record[\"args\"];\n  if (rawArgs !== undefined && !Array.isArray(rawArgs)) {\n    throw new ScriptInputError('\"args\" must be an array of strings');\n  }\n  const args: string[] = [];\n  for (const value of (rawArgs ?? []) as readonly unknown[]) {\n    if (typeof value !== \"string\") throw new ScriptInputError('\"args\" must contain only strings');\n    args.push(value);\n  }\n\n  const cwd = record[\"cwd\"];\n  if (cwd !== undefined && (typeof cwd !== \"string\" || cwd.trim() === \"\")) {\n    throw new ScriptInputError('\"cwd\" must be a non-empty string when present');\n  }\n\n  const background = record[\"background\"] ?? false;\n  if (typeof background !== \"boolean\") throw new ScriptInputError('\"background\" must be a boolean');\n\n  const timeoutMs = record[\"timeoutMs\"];\n  if (timeoutMs !== undefined) {\n    if (typeof timeoutMs !== \"number\" || !Number.isInteger(timeoutMs) || timeoutMs <= 0) {\n      throw new ScriptInputError('\"timeoutMs\" must be a positive integer');\n    }\n    if (timeoutMs > MAX_TIMEOUT_MS) {\n      throw new ScriptInputError(`\"timeoutMs\" must be at most ${MAX_TIMEOUT_MS}`);\n    }\n  }\n\n  const outputLimitBytes = record[\"outputLimitBytes\"];\n  if (outputLimitBytes !== undefined) {\n    if (\n      typeof outputLimitBytes !== \"number\" ||\n      !Number.isInteger(outputLimitBytes) ||\n      outputLimitBytes <= 0\n    ) {\n      throw new ScriptInputError('\"outputLimitBytes\" must be a positive integer');\n    }\n  }\n\n  return {\n    id: id as ScriptId,\n    args,\n    ...(cwd === undefined ? {} : { cwd: cwd as string }),\n    background,\n    ...(timeoutMs === undefined ? {} : { timeoutMs: timeoutMs as number }),\n    ...(outputLimitBytes === undefined\n      ? {}\n      : { outputLimitBytes: outputLimitBytes as number }),\n  };\n}\n\n/**\n * Resolve the directory the child runs in.\n *\n * The tool's `cwd` argument is documented as resolving against \"this session's\n * directory\", so `sessionCwd` — the value `ctx.workingDirectory.ensure()` returns —\n * is the base, not the Host process's working directory.\n *\n * - omitted           -> the session directory\n * - relative          -> joined onto the session directory\n * - absolute          -> used as-is\n *\n * With no Session (a call outside an Agent) there is no session directory to\n * anchor to; the argument is then passed through and `resolve` normalises it\n * against the Host process, which is the only directory that exists.\n */\nexport function resolveWorkingDirectory(\n  requested: string | undefined,\n  sessionCwd: string | undefined,\n): string | undefined {\n  if (requested === undefined) return sessionCwd;\n  if (isAbsolute(requested)) return resolve(requested);\n  return sessionCwd === undefined ? resolve(requested) : resolve(join(sessionCwd, requested));\n}\n\n/**\n * Run one script in the foreground.\n *\n * A nonzero exit, a signal, a timeout, and truncated output are all returned rather\n * than raised: the caller needs to see what the script said before it failed, and an\n * exception would discard the captured output.\n */\nexport async function runForeground(\n  args: ScriptArgs,\n  options: {\n    readonly execPath?: string;\n    readonly environment?: NodeJS.ProcessEnv;\n    /** Already resolved by the caller; see `resolveWorkingDirectory`. */\n    readonly cwd?: string;\n    readonly signal?: AbortSignal;\n  } = {},\n): Promise<ScriptResult> {\n  const path = scriptPath(args.id);\n  const started = Date.now();\n  const timeoutMs = args.timeoutMs ?? DEFAULT_TIMEOUT_MS;\n  const limit = args.outputLimitBytes ?? DEFAULT_OUTPUT_LIMIT_BYTES;\n\n  return await new Promise<ScriptResult>((resolve, reject) => {\n    const child = spawnChild(options.execPath ?? process.execPath, [path, ...args.args], {\n      cwd: args.cwd ?? options.cwd,\n      env: options.environment ?? scriptEnvironment(),\n      stdio: [\"ignore\", \"pipe\", \"pipe\"],\n      windowsHide: true,\n      signal: options.signal,\n    });\n\n    let stdout = \"\";\n    let stderr = \"\";\n    let stdoutTruncated = false;\n    let stderrTruncated = false;\n    let timedOut = false;\n\n    const collect = (chunk: Buffer, to: \"out\" | \"err\"): void => {\n      const text = chunk.toString(\"utf8\");\n      if (to === \"out\") {\n        if (stdout.length >= limit) {\n          stdoutTruncated = true;\n          return;\n        }\n        stdout += text.slice(0, limit - stdout.length);\n        if (stdout.length >= limit) stdoutTruncated = true;\n        return;\n      }\n      if (stderr.length >= limit) {\n        stderrTruncated = true;\n        return;\n      }\n      stderr += text.slice(0, limit - stderr.length);\n      if (stderr.length >= limit) stderrTruncated = true;\n    };\n\n    child.stdout?.on(\"data\", (chunk: Buffer) => collect(chunk, \"out\"));\n    child.stderr?.on(\"data\", (chunk: Buffer) => collect(chunk, \"err\"));\n\n    const timer = setTimeout(() => {\n      timedOut = true;\n      child.kill(\"SIGKILL\");\n    }, timeoutMs);\n\n    child.once(\"error\", (error) => {\n      clearTimeout(timer);\n      reject(error);\n    });\n\n    child.once(\"close\", (code, signal) => {\n      clearTimeout(timer);\n      resolve({\n        kind: \"foreground\",\n        id: args.id,\n        exitCode: code ?? (signal === null ? 1 : 1),\n        signal,\n        timedOut,\n        stdout,\n        stderr,\n        stdoutTruncated,\n        stderrTruncated,\n        durationMs: Date.now() - started,\n      });\n    });\n  });\n}\n\n/**\n * Start a script as a background job.\n *\n * `jobs` is required and passing nothing is a refusal with a reason. A job whose\n * output nobody can read would be worse than a failed call: the model would report a\n * task as started and no notice would ever arrive.\n */\nexport async function runBackground(\n  args: ScriptArgs,\n  options: {\n    readonly jobs?: JobsHost | undefined;\n    readonly caller?: SessionId;\n    readonly execPath?: string;\n    readonly environment?: NodeJS.ProcessEnv;\n    readonly cwd?: string;\n  },\n): Promise<ScriptJobResult> {\n  const jobs = options.jobs;\n  if (jobs === undefined) {\n    throw new ScriptInputError(\n      \"background: true needs the Host jobs service, and this composition has none. \" +\n        \"Run the call in the foreground (omit background), or ask the operator to mount a job controller.\",\n    );\n  }\n\n  const path = scriptPath(args.id);\n  const execPath = options.execPath ?? process.execPath;\n  const environment = options.environment ?? scriptEnvironment();\n  // Already resolved by the caller; see `resolveWorkingDirectory`.\n  const cwd = options.cwd;\n\n  /**\n   * Settles when the child either started or failed to start, or when the registry\n   * never invoked the producer at all.\n   *\n   * `run` fills this in, so the caller can await the real startup outcome instead of\n   * guessing at one with a timer. `child_process` emits exactly one of `spawn` or\n   * `error`:\n   *\n   * - `spawn` fires once the child has been created, before any stdio or exit event.\n   * - `error` fires instead when creation failed (ENOENT, EACCES, EMFILE), and no\n   *   `spawn` ever follows.\n   *\n   * So these two events are mutually exclusive and jointly exhaustive for \"did it\n   * start\", which is exactly the question the tool has to answer. Measured on this\n   * Node: a missing binary reports ENOENT through `error`, while a real binary —\n   * including one that exits immediately or runs slowly — reports `spawn` with no\n   * error.\n   *\n   * `state` exists because the promise must never be able to hang. Two cases would\n   * otherwise leave it pending forever:\n   *\n   * - a registry that registers a job without calling `run` (a stub, or a future\n   *   controller with a different contract). `dsh-jobs-local` does call it\n   *   synchronously (`hooks = spec.run(handle)`), but the tool cannot assume which\n   *   implementation it is talking to — and hanging is far worse than reporting\n   *   \"started\", because the model never gets an answer at all.\n   * - `run` throwing synchronously, which would skip both event handlers.\n   *\n   * Both are treated as \"started\" only in the sense of \"do not claim a failure we did\n   * not observe\": a genuinely failed job still settles as `failed` through `done`, and\n   * the Host's job tools report that.\n   */\n  let reportStarted: ((failure: string | null) => void) | undefined;\n  const state: { settled: boolean; ran: boolean } = { settled: false, ran: false };\n  const started = new Promise<string | null>((settle) => {\n    reportStarted = (failure) => {\n      if (state.settled) return;\n      state.settled = true;\n      settle(failure);\n    };\n  });\n\n  const jobId = jobs.start({\n    kind: \"bash\",\n    label: `pstack_script ${args.id}`,\n    ...(options.caller === undefined ? {} : { owner: options.caller }),\n    outputLimitBytes: args.outputLimitBytes ?? DEFAULT_OUTPUT_LIMIT_BYTES,\n    run: (job) => {\n      state.ran = true;\n      const settleStarted = reportStarted as (failure: string | null) => void;\n      let child: ChildProcess;\n      try {\n        child = spawnChild(execPath, [path, ...args.args], {\n          cwd,\n          env: environment,\n          stdio: [\"ignore\", \"pipe\", \"pipe\"],\n          windowsHide: true,\n        });\n      } catch (error) {\n        // A synchronous throw from `spawn` (an invalid argument, or a platform\n        // failure that does not become an event) would otherwise leave the caller\n        // waiting forever, because no listener was ever attached.\n        settleStarted((error as NodeJS.ErrnoException).code ?? \"spawn-threw\");\n        throw error;\n      }\n\n      child.stdout?.on(\"data\", (chunk: Buffer) => job.append(chunk.toString(\"utf8\"), { channel: \"stdout\" }));\n      child.stderr?.on(\"data\", (chunk: Buffer) => job.append(chunk.toString(\"utf8\"), { channel: \"stderr\" }));\n\n      // Report the startup outcome to the caller waiting above. `once` on both, and\n      // the promise settles on whichever arrives first, so a late `error` after a\n      // successful `spawn` cannot overwrite the answer.\n      child.once(\"spawn\", () => settleStarted(null));\n      child.once(\"error\", (error) => {\n        // Only the error code. `child_process`'s `error.message` embeds the host's\n        // absolute path to the artefact, and the model has no business seeing the\n        // host layout.\n        settleStarted((error as NodeJS.ErrnoException).code ?? \"spawn-failed\");\n      });\n\n      const done = new Promise<{ status: \"completed\" | \"killed\" | \"failed\"; detail?: string }>(\n        (settle) => {\n          child.once(\"error\", (error) => {\n            settle({\n              status: \"failed\",\n              detail: (error as NodeJS.ErrnoException).code ?? \"spawn-failed\",\n            });\n          });\n          child.once(\"close\", (code, signal) => {\n            if (signal !== null) settle({ status: \"killed\", detail: `signal ${signal}` });\n            else if (code === 0) settle({ status: \"completed\" });\n            else settle({ status: \"failed\", detail: `exit code ${code ?? \"unknown\"}` });\n          });\n        },\n      );\n\n      return {\n        cancel: (reason?: string) => {\n          child.kill(\"SIGTERM\");\n          if (reason !== undefined) job.updateProgress(`cancelling: ${reason}`);\n        },\n        done,\n      };\n    },\n  });\n\n  // Wait for the real startup outcome, not a guess.\n  //\n  // Three attempts preceded this, and each failed differently:\n  //\n  // 1. A fixed 250 ms wait. Failures before it were caught, failures after it were\n  //    reported to the model as \"started\" and never corrected.\n  // 2. One microtask (`await Promise.resolve()`). `spawn` reports ENOENT\n  //    asynchronously, so this caught nothing at all — measured: after one microtask\n  //    the error had not fired yet, and it appeared ~100 ms later. That made the tool\n  //    report `running` for a job that never started, which is worse than the timer.\n  // 3. This: race `spawn` against `error`, which are mutually exclusive and jointly\n  //    exhaustive for \"did the child start\". No duration is involved, so no\n  //    latency assumption can be wrong.\n  //\n  // If the registry never invoked the producer, the promise would never settle, so\n  // that case is answered up front rather than awaited. `dsh-jobs-local` calls\n  // `spec.run` synchronously, but a stub registry need not, and hanging is the one\n  // outcome the model can do nothing with.\n  /**\n   * Turn a reported start failure into the tool error.\n   *\n   * The code only. A foreground run is how the caller sees the actual error, and\n   * naming the code keeps host paths out of the model's context.\n   */\n  const failStart = (reason: string): never => {\n    throw new ScriptMissingError(\n      `background job ${jobId} failed to start (${reason}). ` +\n        \"Run the same script in the foreground to see its error.\",\n    );\n  };\n\n  if (!state.ran) {\n    // The registry registered a job without invoking the producer, so there is no\n    // child to observe. Report what the registry itself says, and refuse to present a\n    // terminal failure as a started job.\n    const view = jobs.get(jobId, options.caller);\n    if (view.status === \"failed\") failStart(\"the job controller reported a failed start\");\n    return { kind: \"background\", id: args.id, jobId, status: view.status };\n  }\n\n  const startFailure = await started;\n  if (startFailure !== null) failStart(startFailure);\n\n  // A controller may also settle the job as failed after `spawn` but before this\n  // call returns. That is still a start failure from the model's point of view: it\n  // has been told nothing it could act on yet.\n  const view = jobs.get(jobId, options.caller);\n  if (view.status === \"failed\") failStart(\"the job controller reported a failed start\");\n  return { kind: \"background\", id: args.id, jobId, status: view.status };\n}\n\n/**\n * Render one captured stream as a fenced block, byte for byte.\n *\n * `trimEnd` used to run here, which is wrong for two reasons:\n *\n * - A stream of only whitespace passed the `!== \"\"` test and then rendered as an\n *   empty-looking `stdout:` line, so a reader concluded the script printed nothing.\n * - `check-plan`'s contract includes exact line counts and blank-line separators, so\n *   a trimmed block is a different document — and the model reads this text as the\n *   script's output.\n *\n * A fence keeps every byte visible, including trailing blank lines. The fence is\n * lengthened past the longest backtick run in the content so it can never be closed\n * early by the content itself. Nothing inside is escaped or reinterpreted.\n */\nexport function renderCapturedStream(text: string): readonly string[] {\n  if (text === \"\") return [];\n  const longestRun = Math.max(0, ...(text.match(/`+/g) ?? []).map((run) => run.length));\n  const fence = \"`\".repeat(Math.max(3, longestRun + 1));\n  // Strip exactly one final newline: `join(\"\\n\")` puts it back, and keeping it would\n  // add a visible blank line that the script did not print.\n  const body = text.endsWith(\"\\n\") ? text.slice(0, -1) : text;\n  return [fence, body, fence];\n}\n\n/** Render one outcome for the model. */\nexport function renderScriptOutcome(outcome: ScriptOutcome): string {\n  if (outcome.kind === \"background\") {\n    return [\n      `started ${outcome.id} as background job ${outcome.jobId} (status: ${outcome.status}).`,\n      \"Read or stop it through the Host's job tools; this tool does not poll.\",\n    ].join(\"\\n\");\n  }\n\n  const lines = [\n    `${outcome.id} exited with code ${outcome.exitCode}` +\n      `${outcome.signal === null ? \"\" : ` (signal ${outcome.signal})`}` +\n      `${outcome.timedOut ? ` after the timeout` : \"\"} in ${outcome.durationMs}ms`,\n  ];\n  // Omitted only when the stream is genuinely empty; a stream of blank lines is\n  // shown, so \"printed nothing\" and \"printed newlines\" stay distinguishable.\n  if (outcome.stdout !== \"\") lines.push(\"\", \"stdout (exact bytes):\", ...renderCapturedStream(outcome.stdout));\n  if (outcome.stderr !== \"\") lines.push(\"\", \"stderr (exact bytes):\", ...renderCapturedStream(outcome.stderr));\n  if (outcome.stdoutTruncated) lines.push(\"\", \"stdout was truncated at the output limit.\");\n  if (outcome.stderrTruncated) lines.push(\"\", \"stderr was truncated at the output limit.\");\n  if (outcome.exitCode !== 0 || outcome.signal !== null || outcome.timedOut) {\n    lines.push(\"\", \"This run failed. Read the output above; do not report success.\");\n  }\n  return lines.join(\"\\n\");\n}\n\nconst TOOL_DESCRIPTION = [\n  \"Run one of the scripts bundled with pstack, using the Host's own Node runtime.\",\n  \"\",\n  \"Use this instead of a shell for the pstack scripts. It works in both deployments: the npm CLI and\",\n  \"the Desktop app, where `node` is not on PATH because the Desktop process is Electron.\",\n  \"\",\n  \"`id` selects a bundled script by name; only those names are accepted, so this is not a general\",\n  \"shell and takes no path or command string. `args` are passed to the script verbatim.\",\n  \"\",\n  \"The run starts in this session's directory, so a relative path in `args` lands inside the\",\n  \"workspace or worktree the session is using.\",\n  \"\",\n  \"**This tool does not go through command approval, and the Host's sandbox policy does not apply**\",\n  \"to it. It spawns a Node process directly instead of asking `ctx.shell` to run a command, which is\",\n  \"what keeps it working where no `node` is on PATH. The scripts are this package's own audited\",\n  \"artefacts and `id` cannot name anything else, but the consequence is real: unlike a bash call, no\",\n  \"approval prompt is shown and no filesystem policy is enforced on what the script writes. Say so\",\n  \"when a task depends on that difference.\",\n  \"\",\n  \"A nonzero exit, a signal, a timeout, and truncated output all come back in the result with the\",\n  \"captured output, so a failed run is visible rather than silent.\",\n  \"\",\n  \"Set `background: true` for a long run. That needs the Host jobs service; without it the call is\",\n  \"refused with a reason instead of hanging. Background runs return a job id and a settlement notice\",\n  \"arrives later — do not poll.\",\n].join(\"\\n\");\n\n/** The model-facing JSON Schema for `parameters`. */\nexport function buildScriptParameters(): Record<string, unknown> {\n  const properties: Record<string, unknown> = {\n    id: {\n      type: \"string\",\n      enum: [...SCRIPT_IDS],\n      description: \"Which bundled pstack script to run. Not a path: only these names are accepted.\",\n    },\n    args: {\n      type: \"array\",\n      items: { type: \"string\" },\n      description: \"Arguments passed to the script verbatim, one array entry per argument.\",\n    },\n    cwd: {\n      type: \"string\",\n      description:\n        \"Working directory for the script. Relative paths resolve against this session's directory; an absolute path is used as-is. Omitted runs in this session's directory.\",\n    },\n    background: {\n      type: \"boolean\",\n      description:\n        \"Run as a Host background job and return its id. Requires the jobs service; a composition without it refuses the call.\",\n    },\n    timeoutMs: {\n      type: \"integer\",\n      description: `Foreground wall-clock limit; 1 or greater, and values below 1 are rejected. Defaults to ${DEFAULT_TIMEOUT_MS}; values above ${MAX_TIMEOUT_MS} are rejected.`,\n    },\n    outputLimitBytes: {\n      type: \"integer\",\n      description: `Per-stream capture limit; 1 or greater, and values below 1 are rejected. Defaults to ${DEFAULT_OUTPUT_LIMIT_BYTES}.`,\n    },\n  };\n\n  return {\n    type: \"object\",\n    additionalProperties: false,\n    properties,\n    required: [\"id\"],\n  };\n}\n\n/**\n * The declared shape of one outcome, exported so tests can validate real results.\n *\n * Split by `kind` instead of one flat object. The flat form could only require\n * `kind` and `id`, so a foreground result that omitted `exitCode` was still\n * \"valid\" and the schema proved nothing about the fields the model reads.\n *\n * `signal` is nullable because `child_process` reports `null` whenever the child\n * exited on its own — that is every successful run. Declaring it `string` made\n * the registry reject the tool's own normal output: `createSuccessResult()`\n * validates before rendering, so **every** clean exit surfaced to the model as\n * `tool \"pstack_script\" returned invalid output`.\n */\nexport const OUTPUT_SCHEMA: JsonSchemaNode = {\n  oneOf: [\n    {\n      type: \"object\",\n      additionalProperties: false,\n      properties: {\n        kind: { type: \"string\", const: \"foreground\" },\n        id: { type: \"string\", description: \"Which bundled script ran.\" },\n        exitCode: { type: \"integer\", description: \"The child's exit code.\" },\n        signal: {\n          oneOf: [{ type: \"string\" }, { type: \"null\" }],\n          description: \"Terminating signal, or null when the script exited on its own.\",\n        },\n        timedOut: {\n          type: \"boolean\",\n          description: \"True when this tool's own timeout killed the run.\",\n        },\n        stdout: { type: \"string\" },\n        stderr: { type: \"string\" },\n        stdoutTruncated: { type: \"boolean\" },\n        stderrTruncated: { type: \"boolean\" },\n        durationMs: { type: \"integer\" },\n      },\n      required: [\n        \"kind\",\n        \"id\",\n        \"exitCode\",\n        \"signal\",\n        \"timedOut\",\n        \"stdout\",\n        \"stderr\",\n        \"stdoutTruncated\",\n        \"stderrTruncated\",\n        \"durationMs\",\n      ],\n    },\n    {\n      type: \"object\",\n      additionalProperties: false,\n      properties: {\n        kind: { type: \"string\", const: \"background\" },\n        id: { type: \"string\", description: \"Which bundled script started.\" },\n        jobId: { type: \"string\", description: \"The Host job id to read or stop.\" },\n        status: { type: \"string\", description: \"Job status when the call returned.\" },\n      },\n      required: [\"kind\", \"id\", \"jobId\", \"status\"],\n    },\n  ],\n};\n\n/** The slices of the Cordis context this tool needs. */\nexport interface PstackScriptHost {\n  readonly tools: ToolsHost;\n  /** Resolves the Session's current directory; see `WorkingDirectoryHost`. */\n  readonly workingDirectory: WorkingDirectoryHost;\n  /**\n   * Optional, and read per call rather than snapshotted.\n   *\n   * A profile may mount a job controller after this row, so a value read once in\n   * `apply` would stay `undefined` forever. `ctx.get(\"jobs\")` is rc.3's\n   * optional-service read: it returns `undefined` instead of throwing when the\n   * service is absent, which is why `jobs` is not declared in `inject`.\n   */\n  readonly getJobs?: () => JobsHost | undefined;\n}\n\n/** Build the tool for one row. */\nexport function createPstackScriptTool(host: PstackScriptHost): ToolDefinition {\n  return {\n    name: TOOL_NAME,\n    description: TOOL_DESCRIPTION,\n    parameters: buildScriptParameters(),\n    output: {\n      schema: OUTPUT_SCHEMA,\n      render: (_args, value) => [{ type: \"text\", text: renderScriptOutcome(value as ScriptOutcome) }],\n    },\n    // Two runs of the same script may write the same store, so this is not marked\n    // concurrency-safe; the Host then serializes them the way it serializes any tool.\n    isConcurrencySafe: () => false,\n    /**\n     * The Host's last-resort budget for one call.\n     *\n     * `DEFAULT_TIMEOUT_MS` is the tool's own timer for a foreground run, and it fires\n     * first in every normal case: it kills the child and returns a `timedOut` result the\n     * model can read. This budget is larger on purpose, so it only ever wins when the\n     * tool's own machinery failed to return at all — a hung `await`, a timer that never\n     * ran — and the alternative would be a session blocked with no answer.\n     *\n     * `MAX_TIMEOUT_MS` rather than a new number: it is already the ceiling the tool\n     * accepts for a caller-supplied `timeoutMs`, so the Host budget can never be the\n     * thing that cuts short a run the caller was allowed to request.\n     *\n     * It does not bound a background job. The wrapper disposes its timer when `execute`\n     * settles, which is milliseconds after `jobs.start` returns.\n     */\n    timeoutMs: MAX_TIMEOUT_MS,\n    async execute(rawArgs, exec: ToolRunContext) {\n      const args = parseScriptArgs(rawArgs);\n      // Ask the Host where this Session currently is, rather than inheriting the\n      // Host process's directory. `ensure` is the same seam `dsh-tool-bash` uses.\n      const sessionCwd =\n        exec.agent === undefined\n          ? undefined\n          : await host.workingDirectory.ensure(exec.agent, exec.signal);\n      const cwd = resolveWorkingDirectory(args.cwd, sessionCwd);\n      if (args.background) {\n        return await runBackground(args, {\n          jobs: host.getJobs?.(),\n          ...(cwd === undefined ? {} : { cwd }),\n          ...(exec.agent === undefined ? {} : { caller: exec.agent.id }),\n        });\n      }\n      return await runForeground(args, {\n        signal: exec.signal,\n        ...(cwd === undefined ? {} : { cwd }),\n      });\n    },\n  };\n}\n\n/** Cordis row name, used by Loader diagnostics. */\nexport const name = \"pstack-script\";\n\n/**\n * The hard dependencies.\n *\n * `tools` is the registry this row registers into; `workingDirectory` is what\n * turns the tool's `cwd` argument and its omitted case into the Session's\n * directory. Both are always present in a profile that has an Agent at all.\n *\n * `jobs` is deliberately absent: a composition without a job controller still\n * registers the tool, and only `background: true` is refused. Declaring `jobs`\n * here would keep the whole fiber inactive in every profile that has no job\n * controller, which is most of them.\n */\nexport const inject = [\"tools\", \"workingDirectory\"];\n\n/**\n * Register `pstack_script` for this row.\n *\n * `inject` is what makes `ctx.tools` readable at all: without it Cordis runs\n * `apply` immediately and the service proxy throws\n * `cannot get property \"tools\" without inject`, so the row would register nothing\n * in any profile.\n */\nexport function apply(ctx: PstackScriptHost & { get?: (name: string) => JobsHost | undefined }): void {\n  ctx.tools.register(\n    createPstackScriptTool({\n      tools: ctx.tools,\n      workingDirectory: ctx.workingDirectory,\n      // Optional-service read, so a controller mounted later is still seen.\n      getJobs: () => ctx.get?.(\"jobs\"),\n    }),\n  );\n}\n"],"mappings":"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"}

package/dist/subagent.d.mts

@@ -0,0 +1,336 @@
+import { f as SubagentCapabilities, g as ToolDefinition, h as SubagentsHost, n as AgentOptions, o as JsonSchemaNode, r as AgentsHost, s as LlmHost, t as Agent, v as ToolsHost } from "./host-contract-o47JH_r8.mjs";
+//#region scripts/role-manifest.d.ts
+/**
+ * The one pstack role manifest.
+ *
+ * Every consumer of the role vocabulary reads this module: `src/roles.ts` for
+ * exact lookup and panel classification, `src/models.ts` for value shapes,
+ * `scripts/build-assets.ts` for the generated example file, and the
+ * `setup-pstack` skill text, which points at that example instead of listing the
+ * roles again. A second literal role list anywhere is a bug.
+ *
+ * Keys are matched exactly after normalization. Commas are part of some keys
+ * (`feature, refactoring`), so nothing here may be split on a comma.
+ *
+ * This module has no Node imports: the Host bundle imports it directly.
+ */
+/** Whether a role holds one route or a comma-separated list of routes. */
+type RoleValueShape = "single" | "list";
+interface RoleSpec {
+  /** Exact key as written in the role file. Commas belong to the key. */
+  readonly key: string;
+  readonly shape: RoleValueShape;
+  /**
+   * A list role that automatically starts one child per entry. Only the three
+   * panel roles set this; every other list role selects one entry.
+   */
+  readonly autoPanel: boolean;
+  /** Skills and playbooks that read this role. */
+  readonly consumers: readonly string[];
+  readonly summary: string;
+}
+//#endregion
+//#region src/models.d.ts
+/** One resolved child route. */
+type ChildRoute = {
+  readonly kind: "inherit";
+} | {
+  readonly kind: "route";
+  readonly provider: string;
+  readonly model: string;
+  readonly effort?: string;
+};
+/** How one role's value expands into children. */
+type RouteSelectionMode = "single" | "panel" | "selected";
+interface RouteSelection {
+  readonly role: RoleSpec;
+  readonly mode: RouteSelectionMode;
+  /** Whether the role came from the file or from the inherit-parent fallback. */
+  readonly configured: boolean;
+  readonly routes: readonly ChildRoute[];
+  /** How many entries the role holds, before selection. */
+  readonly total: number;
+  readonly roleIndex?: number;
+  readonly issues: readonly string[];
+}
+//#endregion
+//#region src/effort.d.ts
+/**
+ * The `agentOptions` one (route, effort override) pair contributes.
+ *
+ * The two independent halves are easy to get wrong in opposite directions:
+ *
+ * - an inherit-parent route with an override must still send `reasoningEffort`,
+ *   which means `{ reasoningEffort }` on its own is a real `agentOptions` value and
+ *   the backend still has to support the capability;
+ * - an override always wins over the role line, because the caller asked for this
+ *   delegation specifically.
+ */
+export declare function agentOptionsFor(route: ChildRoute, effortOverride?: string): AgentOptions | undefined;
+//#endregion
+//#region src/subagent.d.ts
+/** Cordis row name, used by Loader diagnostics. */
+export declare const name = "pstack-subagent";
+/**
+ * Delegation needs the tool registry, the subagent registry, and the LLM adapters.
+ *
+ * `agents` is deliberately **not** here. It is used only to reach a child this tool
+ * has just started, and a composition without it still delegates: the children keep
+ * the effort their request carried and cannot change it afterwards. Declaring it as
+ * a hard dependency would make the whole row inert in such a profile, so the tool
+ * would not exist at all — the failure `pstack-history` already paid for once with
+ * `sessionQuery`. It is read per call through `ctx.get("agents")` instead, which is
+ * why a controller mounted after this row is still seen.
+ */
+export declare const inject: string[];
+/** Model-facing tool name. */
+export declare const TOOL_NAME = "pstack_subagent";
+/** Backend used when the row does not name one. */
+export declare const DEFAULT_SUBAGENT_PROVIDER = "spawn";
+/** Agent type used when the call does not name one. */
+export declare const DEFAULT_AGENT_KIND = "poteto-agent";
+/** The child kinds this tool knows how to brief. */
+export declare const AGENT_KINDS: readonly ["poteto-agent", "comment-sicko", "general"];
+export type AgentKind = (typeof AGENT_KINDS)[number];
+/** One exact route a row may authorize for explicit child selection. */
+export interface AllowedModelRoute {
+  readonly provider: string;
+  readonly model: string;
+}
+/** Row configuration. */
+export interface PstackSubagentConfig {
+  /** `ctx.subagents` provider to start children on. */
+  readonly provider: string;
+  /**
+   * This row's delegation-depth cap. A call may lower it and may never exceed it.
+   * Omitted means the Host setting decides.
+   */
+  readonly maxDepth?: number;
+  /**
+   * Exact routes this row authorizes. Empty means no explicit route limit. This is
+   * pstack's own check and is unrelated to the native session `allowedModels`
+   * policy, which this plugin does not read.
+   */
+  readonly allowedModels: readonly AllowedModelRoute[];
+  /** Non-empty allowlist; also what makes `agentPreset` appear in the schema. */
+  readonly allowedAgentPresets: readonly string[];
+}
+/** What a call asked for, after argument validation. */
+export interface DelegationArgs {
+  readonly description: string;
+  readonly prompt: string;
+  readonly agent: AgentKind;
+  readonly role?: string;
+  readonly cwd?: string;
+  readonly agentPreset?: string;
+  readonly maxDepth?: number;
+  readonly roleIndex?: number;
+  /**
+   * Effort for every child this call starts, overriding each role line's value.
+   *
+   * Validated per entry against the model that entry will actually request, so a
+   * panel with one incompatible entry starts nothing rather than half its children.
+   */
+  readonly reasoningEffort?: string;
+}
+/** One child this call started. */
+export interface ChildRecord {
+  readonly childId: string;
+  readonly label: string;
+  readonly agent: string;
+  readonly role: string;
+  readonly route: string;
+  /** The effort this child runs at, when any applies. */
+  readonly effort?: string;
+  readonly maxDepth?: number;
+}
+export interface DelegationResult {
+  readonly kind: "activation" | "activations";
+  readonly children: readonly ChildRecord[];
+  readonly diagnostics: readonly string[];
+}
+/** Raised for a configuration or argument problem, before any child starts. */
+export declare class DelegationError extends Error {
+  constructor(message: string);
+}
+/** Raised when a child starts but a later entry in the same call fails. */
+export declare class PartialDelegationError extends DelegationError {
+  readonly startedChildren: readonly ChildRecord[];
+  constructor(message: string, startedChildren: readonly ChildRecord[]);
+}
+/** Raised when a required agent preamble is missing or unusable. */
+export declare class PreambleError extends DelegationError {
+  constructor(message: string);
+}
+/** The live services and locations one delegation reads. */
+export interface SubagentRuntime {
+  readonly subagents: SubagentsHost;
+  readonly llm: LlmHost;
+  /**
+   * The Agent registry, used to reach a child this tool just started.
+   *
+   * Optional because a row can be composed without the `agents` service and a
+   * delegation still works there: the children then keep the effort their request
+   * carried and simply cannot change it afterwards. Making it required would turn a
+   * missing service into a row that registers no tool at all.
+   */
+  readonly agents?: AgentsHost;
+  /** `$DSH_HOME`, home of the role file. */
+  readonly dshHome: string;
+  /** Absolute package assets root, home of the agent preambles. */
+  readonly assetsRoot: string;
+}
+interface StandardSchemaIssue {
+  readonly message: string;
+  readonly path?: readonly (string | number)[];
+}
+type StandardSchemaResult = {
+  readonly value: PstackSubagentConfig;
+  readonly issues?: undefined;
+} | {
+  readonly issues: readonly StandardSchemaIssue[];
+};
+/**
+ * Minimal Standard Schema for this row, so an omitted `config` is valid and a
+ * typo fails at load instead of at the first delegation.
+ */
+export declare const Config: {
+  "~standard": {
+    version: number;
+    vendor: string;
+    validate(value: unknown): StandardSchemaResult;
+  };
+};
+/**
+ * Read one agent preamble from the package assets by absolute path.
+ *
+ * A missing or empty preamble blocks that agent type. It never degrades into a
+ * plain child, because a `comment-sicko` or `poteto-agent` child without its
+ * instructions is a different agent wearing the name.
+ */
+export declare function loadAgentPreamble(agent: AgentKind, assetsRoot: string): string | undefined;
+/** One absolute path the Host injects into a child brief. */
+export interface InjectedPath {
+  readonly label: string;
+  readonly path: string;
+}
+/**
+ * Compose the self-contained prompt one child receives.
+ *
+ * The preambles used to locate things themselves; the Host injects the absolute
+ * paths instead, so a child never scans a plugin directory or guesses a version.
+ */
+export declare function composeChildPrompt(input: {
+  readonly preamble?: string;
+  readonly injectedPaths?: readonly InjectedPath[];
+  readonly task: string;
+}): string;
+/** One planned child, before any Host call. */
+export interface ChildPlan {
+  readonly index: number;
+  readonly total: number;
+  readonly label: string;
+  readonly agent: AgentKind;
+  readonly role: string;
+  readonly route: ChildRoute;
+  readonly routeLabel: string;
+  /** The effort this child will actually run at: the override when present, else the role line's. */
+  readonly effort?: string;
+  readonly agentOptions?: AgentOptions;
+  readonly agentPreset?: string;
+  readonly cwd?: string;
+  readonly maxDepth?: number;
+}
+/** The decided plan for one call. */
+export interface DelegationPlan {
+  readonly agent: AgentKind;
+  readonly prompt: string;
+  readonly provider: string;
+  readonly role: string;
+  readonly mode: RouteSelection["mode"];
+  readonly roleIndex?: number;
+  readonly roleTotal: number;
+  /** The call-wide effort override, when it supplied one. */
+  readonly reasoningEffort?: string;
+  readonly children: readonly ChildPlan[];
+  readonly diagnostics: readonly string[];
+}
+/** The text form of one route, as reported back to the model. */
+export declare function routeLabel(route: ChildRoute): string;
+/**
+ * The route text a caller sees when an effort override wins.
+ *
+ * `routeLabel` describes the role file, which stops being the whole truth once the
+ * caller overrode the effort. Reporting the file's value there would tell the model
+ * its override had been ignored.
+ */
+export declare function plannedRouteLabel(route: ChildRoute, effortOverride?: string): string;
+/**
+ * Take the smallest of the requested depth, this row's cap, and the Host setting.
+ *
+ * A request above the row cap is an error rather than a silent clamp, so a caller
+ * cannot believe it asked for two levels when the row allows one.
+ */
+export declare function resolveDelegationDepth(configured: number | undefined, requested: number | undefined, hostLimit: number | undefined): number | undefined;
+/**
+ * Validate the model-facing arguments.
+ *
+ * The tool schema is advisory at the model boundary, so every constraint is
+ * re-checked here and reported with the reason.
+ */
+export declare function parseDelegationArgs(raw: unknown, config?: PstackSubagentConfig): DelegationArgs;
+/**
+ * Resolve the role file, the routes, the prompt, and the depth into one plan.
+ *
+ * Pure with respect to the Host: it reads the role file and the packaged preamble,
+ * and it makes no service call.
+ */
+export declare function planDelegation(args: DelegationArgs, runtime: SubagentRuntime, config?: PstackSubagentConfig): DelegationPlan;
+/** Check the backend can enforce what this call asks for. */
+export declare function assertProviderCapabilities(capabilities: SubagentCapabilities, providerName: string, asks: {
+  readonly agentOptions: boolean;
+  readonly agentPreset: boolean;
+  readonly maxDepth: boolean;
+}): void;
+/**
+ * Start the planned children.
+ *
+ * Everything that can be rejected has already been rejected. A failure at entry N
+ * keeps children 1..N-1 running and reports their ids, because the runtime owns
+ * those activations and this tool cannot roll them back.
+ */
+export declare function startPlannedChildren(parent: Agent, plan: DelegationPlan, runtime: SubagentRuntime, config: PstackSubagentConfig, signal: AbortSignal): Promise<DelegationResult>;
+/** Full delegation: plan, validate, start. */
+export declare function delegate(parent: Agent, args: DelegationArgs, runtime: SubagentRuntime, config?: PstackSubagentConfig, signal?: AbortSignal): Promise<DelegationResult>;
+export declare const OUTPUT_SCHEMA: JsonSchemaNode;
+/** Render one delegation result for the model. */
+export declare function renderDelegationResult(result: DelegationResult): string;
+/** Build the model-facing tool for one row. */
+export declare function createPstackSubagentTool(runtime: SubagentRuntime, config?: PstackSubagentConfig): ToolDefinition;
+/**
+ * The slices of the Cordis context this row uses.
+ *
+ * `agents` is optional in both directions: it is absent from `inject` and read per
+ * call below, so a profile that mounts no agent registry still registers this tool.
+ * See the `inject` comment for why a hard dependency is the wrong shape here.
+ */
+export interface PstackSubagentHost {
+  readonly tools: ToolsHost;
+  readonly subagents: SubagentsHost;
+  readonly llm: LlmHost;
+}
+/** Build the runtime a real Host call reads. */
+export declare function hostRuntime(ctx: PstackSubagentHost, getAgentRegistry?: () => AgentsHost | undefined): SubagentRuntime;
+/**
+ * Register `pstack_subagent` for this row.
+ *
+ * @param ctx - context providing the tool registry, the subagent registry, the LLM
+ *   adapters, and optionally `ctx.get` for the agent registry.
+ * @param config - validated row config.
+ */
+export declare function apply(ctx: PstackSubagentHost & {
+  get?: (name: string) => AgentsHost | undefined;
+}, config?: PstackSubagentConfig): void;
+//#endregion
+export {};
+//# sourceMappingURL=subagent.d.mts.map