dsh-pstack 0.1.0 → 0.2.0-beta.1

package/dist/script.mjs

@@ -0,0 +1,782 @@
+import { t as ASSETS_ROOT } from "./paths-D_JlVmBk.mjs";
+import { isAbsolute, join, resolve } from "node:path";
+import { spawn } from "node:child_process";
+//#region scripts/runtime-manifest.ts
+/** The directory holding the authored runtime sources. */
+const AUTHORED_ROOT = "scripts/runtime/";
+/** `TEST_SUPPORT` as entry sources, so a test entry declares what it imports. */
+const TEST_SUPPORT_ROOTS = [{
+	kind: "authored",
+	path: `${AUTHORED_ROOT}tests/expect.ts`
+}, {
+	kind: "authored",
+	path: `${AUTHORED_ROOT}tests/support.ts`
+}];
+const upstreamScript = (path) => ({
+	kind: "upstream",
+	path: `skills/poteto-mode/scripts/${path}`
+});
+/** CLI artifacts, in the order the reviews and the prose name them. */
+const RUNTIME_CLIS = [
+	{
+		id: "check-plan",
+		kind: "cli",
+		entry: upstreamScript("check-plan.mjs"),
+		out: "check-plan.mjs",
+		assetPath: "skills/poteto-mode/scripts/check-plan.mjs",
+		executable: true,
+		sources: [upstreamScript("check-plan.mjs")],
+		summary: "plan-shape checker"
+	},
+	{
+		id: "orch",
+		kind: "cli",
+		entry: upstreamScript("orch/orch.ts"),
+		out: "orch/orch.mjs",
+		assetPath: "skills/poteto-mode/scripts/orch/orch.mjs",
+		executable: true,
+		sources: [upstreamScript("orch/orch.ts"), upstreamScript("orch/store.ts")],
+		summary: "orchestration bookkeeping store"
+	},
+	{
+		id: "watch-pr",
+		kind: "cli",
+		entry: upstreamScript("watch-pr/watch-pr"),
+		out: "watch-pr/watch-pr.mjs",
+		assetPath: "skills/poteto-mode/scripts/watch-pr/watch-pr.mjs",
+		executable: true,
+		sources: [
+			upstreamScript("watch-pr/watch-pr"),
+			upstreamScript("watch-pr/cli.ts"),
+			upstreamScript("watch-pr/github.ts"),
+			upstreamScript("watch-pr/policy.ts"),
+			upstreamScript("watch-pr/render.ts"),
+			upstreamScript("watch-pr/types.ts")
+		],
+		summary: "pull-request watcher"
+	},
+	{
+		id: "worktree-audit",
+		kind: "cli",
+		entry: {
+			kind: "authored",
+			path: `${AUTHORED_ROOT}worktree-audit.ts`
+		},
+		out: "worktree-audit.mjs",
+		assetPath: "skills/poteto-mode/scripts/worktree-audit.mjs",
+		executable: true,
+		sources: [{
+			kind: "authored",
+			path: `${AUTHORED_ROOT}worktree-audit.ts`
+		}],
+		summary: "read-only worktree audit"
+	},
+	{
+		id: "log",
+		kind: "cli",
+		entry: {
+			kind: "authored",
+			path: `${AUTHORED_ROOT}log.ts`
+		},
+		out: "log.mjs",
+		assetPath: "skills/show-me-your-work/scripts/log.mjs",
+		executable: true,
+		sources: [{
+			kind: "authored",
+			path: `${AUTHORED_ROOT}log.ts`
+		}],
+		summary: "decision-log row appender"
+	}
+];
+/** Test bundles, run by `node --test` from a copy with no install step. */
+const RUNTIME_TESTS = [
+	{
+		id: "check-plan-test",
+		kind: "test",
+		entry: upstreamScript("check-plan.test.ts"),
+		out: "check-plan.test.mjs",
+		assetPath: "skills/poteto-mode/scripts/check-plan.test.mjs",
+		executable: false,
+		sources: [upstreamScript("check-plan.test.ts")],
+		summary: "check-plan tests"
+	},
+	{
+		id: "orch-test",
+		kind: "test",
+		entry: upstreamScript("orch/orch.test.ts"),
+		out: "orch/orch.test.mjs",
+		assetPath: "skills/poteto-mode/scripts/orch/orch.test.mjs",
+		executable: false,
+		sources: [
+			upstreamScript("orch/orch.test.ts"),
+			upstreamScript("orch/store.ts"),
+			...TEST_SUPPORT_ROOTS
+		],
+		summary: "orch tests"
+	},
+	{
+		id: "watch-pr-cli-test",
+		kind: "test",
+		entry: upstreamScript("watch-pr/cli.test.ts"),
+		out: "watch-pr/cli.test.mjs",
+		assetPath: "skills/poteto-mode/scripts/watch-pr/cli.test.mjs",
+		executable: false,
+		sources: [
+			upstreamScript("watch-pr/cli.test.ts"),
+			upstreamScript("watch-pr/cli.ts"),
+			upstreamScript("watch-pr/github.ts"),
+			upstreamScript("watch-pr/policy.ts"),
+			upstreamScript("watch-pr/render.ts"),
+			upstreamScript("watch-pr/types.ts"),
+			upstreamScript("watch-pr/fakes.test-helper.ts"),
+			...TEST_SUPPORT_ROOTS
+		],
+		summary: "watch-pr argument and rendering tests"
+	},
+	{
+		id: "watch-pr-github-test",
+		kind: "test",
+		entry: upstreamScript("watch-pr/github.test.ts"),
+		out: "watch-pr/github.test.mjs",
+		assetPath: "skills/poteto-mode/scripts/watch-pr/github.test.mjs",
+		executable: false,
+		sources: [
+			upstreamScript("watch-pr/github.test.ts"),
+			upstreamScript("watch-pr/github.ts"),
+			upstreamScript("watch-pr/types.ts"),
+			upstreamScript("watch-pr/fakes.test-helper.ts"),
+			...TEST_SUPPORT_ROOTS
+		],
+		summary: "watch-pr GitHub reader tests"
+	},
+	{
+		id: "watch-pr-policy-test",
+		kind: "test",
+		entry: upstreamScript("watch-pr/policy.test.ts"),
+		out: "watch-pr/policy.test.mjs",
+		assetPath: "skills/poteto-mode/scripts/watch-pr/policy.test.mjs",
+		executable: false,
+		sources: [
+			upstreamScript("watch-pr/policy.test.ts"),
+			upstreamScript("watch-pr/policy.ts"),
+			upstreamScript("watch-pr/github.ts"),
+			upstreamScript("watch-pr/types.ts"),
+			upstreamScript("watch-pr/fakes.test-helper.ts"),
+			...TEST_SUPPORT_ROOTS
+		],
+		summary: "watch-pr policy and queue tests"
+	}
+];
+[...RUNTIME_CLIS, ...RUNTIME_TESTS];
+//#endregion
+//#region src/script.ts
+/**
+* `pstack_script`: run a bundled pstack script through the Host's own runtime.
+*
+* Every shipped CLI is a Node artefact inside this package. A model could always
+* write `node <path> …` into a shell, and that is exactly what breaks in the
+* Desktop build: Electron runs the same CLI, so `node` is not on `PATH` there.
+*
+* So the entry point is a tool, not a command. The tool spawns the artefact with
+* `process.execPath` — whichever binary is already running this Host, Node or
+* Electron — and passes `ELECTRON_RUN_AS_NODE=1` only when it is Electron. That is
+* what makes the npm CLI and the Desktop build behave the same without depending on
+* anything in `PATH`.
+*
+* The tool never accepts a path or a command string. `id` is a closed enum over the
+* shipped artefacts, resolved from this package, so a call cannot reach a script the
+* package does not contain. It is not a general shell: there is no `sh -c`, no glob
+* expansion by a shell, and no way to name another executable.
+*/
+/** Model-facing tool name. */
+const TOOL_NAME = "pstack_script";
+/** The shipped scripts this tool may run, in display order. */
+const SCRIPT_IDS = RUNTIME_CLIS.map((entry) => entry.id);
+/** Default wall-clock limit for a foreground run. */
+const DEFAULT_TIMEOUT_MS = 12e4;
+/** Bounds a caller may set for one foreground run. */
+const MAX_TIMEOUT_MS = 6e5;
+/** Default cap on captured bytes per stream. */
+const DEFAULT_OUTPUT_LIMIT_BYTES = 65536;
+/** Raised for an argument problem, before anything is spawned. */
+var ScriptInputError = class extends Error {
+	constructor(message) {
+		super(message);
+		this.name = "ScriptInputError";
+	}
+};
+/** Raised when a shipped artefact is missing from this install. */
+var ScriptMissingError = class extends Error {
+	constructor(message) {
+		super(message);
+		this.name = "ScriptMissingError";
+	}
+};
+/** Absolute path of one shipped artefact. */
+function scriptPath(id) {
+	const entry = RUNTIME_CLIS.find((candidate) => candidate.id === id);
+	if (entry === void 0) throw new ScriptInputError(`unknown script id "${String(id)}"`);
+	return join(ASSETS_ROOT, ...entry.assetPath.split("/"));
+}
+/**
+* The environment a child gets.
+*
+* The one rule is the Electron selector. Under Electron, `process.execPath` is the
+* Desktop binary, which starts a browser window unless `ELECTRON_RUN_AS_NODE=1` tells
+* it to behave as Node. Under plain Node the variable is inert — Node ignores it —
+* so setting it unconditionally would also work; it is conditional here so the
+* environment of a normal run stays exactly the caller's, and the one code path that
+* needs it is visible.
+*/
+function scriptEnvironment(base = process.env, versions = process.versions) {
+	if (versions.electron === void 0) return { ...base };
+	return {
+		...base,
+		ELECTRON_RUN_AS_NODE: "1"
+	};
+}
+/** Validate the raw tool arguments. */
+function parseScriptArgs(raw) {
+	if (raw === null || typeof raw !== "object" || Array.isArray(raw)) throw new ScriptInputError("arguments must be an object");
+	const record = raw;
+	for (const key of Object.keys(record)) if (![
+		"id",
+		"args",
+		"cwd",
+		"background",
+		"timeoutMs",
+		"outputLimitBytes"
+	].includes(key)) throw new ScriptInputError(`unknown argument "${key}"`);
+	const id = record["id"];
+	if (typeof id !== "string") throw new ScriptInputError("\"id\" must be a string");
+	if (!SCRIPT_IDS.includes(id)) throw new ScriptInputError(`"id" must be one of ${SCRIPT_IDS.join(", ")}; this tool runs bundled scripts only`);
+	const rawArgs = record["args"];
+	if (rawArgs !== void 0 && !Array.isArray(rawArgs)) throw new ScriptInputError("\"args\" must be an array of strings");
+	const args = [];
+	for (const value of rawArgs ?? []) {
+		if (typeof value !== "string") throw new ScriptInputError("\"args\" must contain only strings");
+		args.push(value);
+	}
+	const cwd = record["cwd"];
+	if (cwd !== void 0 && (typeof cwd !== "string" || cwd.trim() === "")) throw new ScriptInputError("\"cwd\" must be a non-empty string when present");
+	const background = record["background"] ?? false;
+	if (typeof background !== "boolean") throw new ScriptInputError("\"background\" must be a boolean");
+	const timeoutMs = record["timeoutMs"];
+	if (timeoutMs !== void 0) {
+		if (typeof timeoutMs !== "number" || !Number.isInteger(timeoutMs) || timeoutMs <= 0) throw new ScriptInputError("\"timeoutMs\" must be a positive integer");
+		if (timeoutMs > 6e5) throw new ScriptInputError(`"timeoutMs" must be at most ${MAX_TIMEOUT_MS}`);
+	}
+	const outputLimitBytes = record["outputLimitBytes"];
+	if (outputLimitBytes !== void 0) {
+		if (typeof outputLimitBytes !== "number" || !Number.isInteger(outputLimitBytes) || outputLimitBytes <= 0) throw new ScriptInputError("\"outputLimitBytes\" must be a positive integer");
+	}
+	return {
+		id,
+		args,
+		...cwd === void 0 ? {} : { cwd },
+		background,
+		...timeoutMs === void 0 ? {} : { timeoutMs },
+		...outputLimitBytes === void 0 ? {} : { outputLimitBytes }
+	};
+}
+/**
+* Resolve the directory the child runs in.
+*
+* The tool's `cwd` argument is documented as resolving against "this session's
+* directory", so `sessionCwd` — the value `ctx.workingDirectory.ensure()` returns —
+* is the base, not the Host process's working directory.
+*
+* - omitted           -> the session directory
+* - relative          -> joined onto the session directory
+* - absolute          -> used as-is
+*
+* With no Session (a call outside an Agent) there is no session directory to
+* anchor to; the argument is then passed through and `resolve` normalises it
+* against the Host process, which is the only directory that exists.
+*/
+function resolveWorkingDirectory(requested, sessionCwd) {
+	if (requested === void 0) return sessionCwd;
+	if (isAbsolute(requested)) return resolve(requested);
+	return sessionCwd === void 0 ? resolve(requested) : resolve(join(sessionCwd, requested));
+}
+/**
+* Run one script in the foreground.
+*
+* A nonzero exit, a signal, a timeout, and truncated output are all returned rather
+* than raised: the caller needs to see what the script said before it failed, and an
+* exception would discard the captured output.
+*/
+async function runForeground(args, options = {}) {
+	const path = scriptPath(args.id);
+	const started = Date.now();
+	const timeoutMs = args.timeoutMs ?? 12e4;
+	const limit = args.outputLimitBytes ?? 65536;
+	return await new Promise((resolve, reject) => {
+		const child = spawn(options.execPath ?? process.execPath, [path, ...args.args], {
+			cwd: args.cwd ?? options.cwd,
+			env: options.environment ?? scriptEnvironment(),
+			stdio: [
+				"ignore",
+				"pipe",
+				"pipe"
+			],
+			windowsHide: true,
+			signal: options.signal
+		});
+		let stdout = "";
+		let stderr = "";
+		let stdoutTruncated = false;
+		let stderrTruncated = false;
+		let timedOut = false;
+		const collect = (chunk, to) => {
+			const text = chunk.toString("utf8");
+			if (to === "out") {
+				if (stdout.length >= limit) {
+					stdoutTruncated = true;
+					return;
+				}
+				stdout += text.slice(0, limit - stdout.length);
+				if (stdout.length >= limit) stdoutTruncated = true;
+				return;
+			}
+			if (stderr.length >= limit) {
+				stderrTruncated = true;
+				return;
+			}
+			stderr += text.slice(0, limit - stderr.length);
+			if (stderr.length >= limit) stderrTruncated = true;
+		};
+		child.stdout?.on("data", (chunk) => collect(chunk, "out"));
+		child.stderr?.on("data", (chunk) => collect(chunk, "err"));
+		const timer = setTimeout(() => {
+			timedOut = true;
+			child.kill("SIGKILL");
+		}, timeoutMs);
+		child.once("error", (error) => {
+			clearTimeout(timer);
+			reject(error);
+		});
+		child.once("close", (code, signal) => {
+			clearTimeout(timer);
+			resolve({
+				kind: "foreground",
+				id: args.id,
+				exitCode: code ?? (signal === null ? 1 : 1),
+				signal,
+				timedOut,
+				stdout,
+				stderr,
+				stdoutTruncated,
+				stderrTruncated,
+				durationMs: Date.now() - started
+			});
+		});
+	});
+}
+/**
+* Start a script as a background job.
+*
+* `jobs` is required and passing nothing is a refusal with a reason. A job whose
+* output nobody can read would be worse than a failed call: the model would report a
+* task as started and no notice would ever arrive.
+*/
+async function runBackground(args, options) {
+	const jobs = options.jobs;
+	if (jobs === void 0) throw new ScriptInputError("background: true needs the Host jobs service, and this composition has none. Run the call in the foreground (omit background), or ask the operator to mount a job controller.");
+	const path = scriptPath(args.id);
+	const execPath = options.execPath ?? process.execPath;
+	const environment = options.environment ?? scriptEnvironment();
+	const cwd = options.cwd;
+	/**
+	* Settles when the child either started or failed to start, or when the registry
+	* never invoked the producer at all.
+	*
+	* `run` fills this in, so the caller can await the real startup outcome instead of
+	* guessing at one with a timer. `child_process` emits exactly one of `spawn` or
+	* `error`:
+	*
+	* - `spawn` fires once the child has been created, before any stdio or exit event.
+	* - `error` fires instead when creation failed (ENOENT, EACCES, EMFILE), and no
+	*   `spawn` ever follows.
+	*
+	* So these two events are mutually exclusive and jointly exhaustive for "did it
+	* start", which is exactly the question the tool has to answer. Measured on this
+	* Node: a missing binary reports ENOENT through `error`, while a real binary —
+	* including one that exits immediately or runs slowly — reports `spawn` with no
+	* error.
+	*
+	* `state` exists because the promise must never be able to hang. Two cases would
+	* otherwise leave it pending forever:
+	*
+	* - a registry that registers a job without calling `run` (a stub, or a future
+	*   controller with a different contract). `dsh-jobs-local` does call it
+	*   synchronously (`hooks = spec.run(handle)`), but the tool cannot assume which
+	*   implementation it is talking to — and hanging is far worse than reporting
+	*   "started", because the model never gets an answer at all.
+	* - `run` throwing synchronously, which would skip both event handlers.
+	*
+	* Both are treated as "started" only in the sense of "do not claim a failure we did
+	* not observe": a genuinely failed job still settles as `failed` through `done`, and
+	* the Host's job tools report that.
+	*/
+	let reportStarted;
+	const state = {
+		settled: false,
+		ran: false
+	};
+	const started = new Promise((settle) => {
+		reportStarted = (failure) => {
+			if (state.settled) return;
+			state.settled = true;
+			settle(failure);
+		};
+	});
+	const jobId = jobs.start({
+		kind: "bash",
+		label: `pstack_script ${args.id}`,
+		...options.caller === void 0 ? {} : { owner: options.caller },
+		outputLimitBytes: args.outputLimitBytes ?? 65536,
+		run: (job) => {
+			state.ran = true;
+			const settleStarted = reportStarted;
+			let child;
+			try {
+				child = spawn(execPath, [path, ...args.args], {
+					cwd,
+					env: environment,
+					stdio: [
+						"ignore",
+						"pipe",
+						"pipe"
+					],
+					windowsHide: true
+				});
+			} catch (error) {
+				settleStarted(error.code ?? "spawn-threw");
+				throw error;
+			}
+			child.stdout?.on("data", (chunk) => job.append(chunk.toString("utf8"), { channel: "stdout" }));
+			child.stderr?.on("data", (chunk) => job.append(chunk.toString("utf8"), { channel: "stderr" }));
+			child.once("spawn", () => settleStarted(null));
+			child.once("error", (error) => {
+				settleStarted(error.code ?? "spawn-failed");
+			});
+			return {
+				cancel: (reason) => {
+					child.kill("SIGTERM");
+					if (reason !== void 0) job.updateProgress(`cancelling: ${reason}`);
+				},
+				done: new Promise((settle) => {
+					child.once("error", (error) => {
+						settle({
+							status: "failed",
+							detail: error.code ?? "spawn-failed"
+						});
+					});
+					child.once("close", (code, signal) => {
+						if (signal !== null) settle({
+							status: "killed",
+							detail: `signal ${signal}`
+						});
+						else if (code === 0) settle({ status: "completed" });
+						else settle({
+							status: "failed",
+							detail: `exit code ${code ?? "unknown"}`
+						});
+					});
+				})
+			};
+		}
+	});
+	/**
+	* Turn a reported start failure into the tool error.
+	*
+	* The code only. A foreground run is how the caller sees the actual error, and
+	* naming the code keeps host paths out of the model's context.
+	*/
+	const failStart = (reason) => {
+		throw new ScriptMissingError(`background job ${jobId} failed to start (${reason}). Run the same script in the foreground to see its error.`);
+	};
+	if (!state.ran) {
+		const view = jobs.get(jobId, options.caller);
+		if (view.status === "failed") failStart("the job controller reported a failed start");
+		return {
+			kind: "background",
+			id: args.id,
+			jobId,
+			status: view.status
+		};
+	}
+	const startFailure = await started;
+	if (startFailure !== null) failStart(startFailure);
+	const view = jobs.get(jobId, options.caller);
+	if (view.status === "failed") failStart("the job controller reported a failed start");
+	return {
+		kind: "background",
+		id: args.id,
+		jobId,
+		status: view.status
+	};
+}
+/**
+* Render one captured stream as a fenced block, byte for byte.
+*
+* `trimEnd` used to run here, which is wrong for two reasons:
+*
+* - A stream of only whitespace passed the `!== ""` test and then rendered as an
+*   empty-looking `stdout:` line, so a reader concluded the script printed nothing.
+* - `check-plan`'s contract includes exact line counts and blank-line separators, so
+*   a trimmed block is a different document — and the model reads this text as the
+*   script's output.
+*
+* A fence keeps every byte visible, including trailing blank lines. The fence is
+* lengthened past the longest backtick run in the content so it can never be closed
+* early by the content itself. Nothing inside is escaped or reinterpreted.
+*/
+function renderCapturedStream(text) {
+	if (text === "") return [];
+	const longestRun = Math.max(0, ...(text.match(/`+/g) ?? []).map((run) => run.length));
+	const fence = "`".repeat(Math.max(3, longestRun + 1));
+	return [
+		fence,
+		text.endsWith("\n") ? text.slice(0, -1) : text,
+		fence
+	];
+}
+/** Render one outcome for the model. */
+function renderScriptOutcome(outcome) {
+	if (outcome.kind === "background") return [`started ${outcome.id} as background job ${outcome.jobId} (status: ${outcome.status}).`, "Read or stop it through the Host's job tools; this tool does not poll."].join("\n");
+	const lines = [`${outcome.id} exited with code ${outcome.exitCode}${outcome.signal === null ? "" : ` (signal ${outcome.signal})`}${outcome.timedOut ? ` after the timeout` : ""} in ${outcome.durationMs}ms`];
+	if (outcome.stdout !== "") lines.push("", "stdout (exact bytes):", ...renderCapturedStream(outcome.stdout));
+	if (outcome.stderr !== "") lines.push("", "stderr (exact bytes):", ...renderCapturedStream(outcome.stderr));
+	if (outcome.stdoutTruncated) lines.push("", "stdout was truncated at the output limit.");
+	if (outcome.stderrTruncated) lines.push("", "stderr was truncated at the output limit.");
+	if (outcome.exitCode !== 0 || outcome.signal !== null || outcome.timedOut) lines.push("", "This run failed. Read the output above; do not report success.");
+	return lines.join("\n");
+}
+const TOOL_DESCRIPTION = [
+	"Run one of the scripts bundled with pstack, using the Host's own Node runtime.",
+	"",
+	"Use this instead of a shell for the pstack scripts. It works in both deployments: the npm CLI and",
+	"the Desktop app, where `node` is not on PATH because the Desktop process is Electron.",
+	"",
+	"`id` selects a bundled script by name; only those names are accepted, so this is not a general",
+	"shell and takes no path or command string. `args` are passed to the script verbatim.",
+	"",
+	"The run starts in this session's directory, so a relative path in `args` lands inside the",
+	"workspace or worktree the session is using.",
+	"",
+	"**This tool does not go through command approval, and the Host's sandbox policy does not apply**",
+	"to it. It spawns a Node process directly instead of asking `ctx.shell` to run a command, which is",
+	"what keeps it working where no `node` is on PATH. The scripts are this package's own audited",
+	"artefacts and `id` cannot name anything else, but the consequence is real: unlike a bash call, no",
+	"approval prompt is shown and no filesystem policy is enforced on what the script writes. Say so",
+	"when a task depends on that difference.",
+	"",
+	"A nonzero exit, a signal, a timeout, and truncated output all come back in the result with the",
+	"captured output, so a failed run is visible rather than silent.",
+	"",
+	"Set `background: true` for a long run. That needs the Host jobs service; without it the call is",
+	"refused with a reason instead of hanging. Background runs return a job id and a settlement notice",
+	"arrives later — do not poll."
+].join("\n");
+/** The model-facing JSON Schema for `parameters`. */
+function buildScriptParameters() {
+	return {
+		type: "object",
+		additionalProperties: false,
+		properties: {
+			id: {
+				type: "string",
+				enum: [...SCRIPT_IDS],
+				description: "Which bundled pstack script to run. Not a path: only these names are accepted."
+			},
+			args: {
+				type: "array",
+				items: { type: "string" },
+				description: "Arguments passed to the script verbatim, one array entry per argument."
+			},
+			cwd: {
+				type: "string",
+				description: "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."
+			},
+			background: {
+				type: "boolean",
+				description: "Run as a Host background job and return its id. Requires the jobs service; a composition without it refuses the call."
+			},
+			timeoutMs: {
+				type: "integer",
+				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.`
+			},
+			outputLimitBytes: {
+				type: "integer",
+				description: `Per-stream capture limit; 1 or greater, and values below 1 are rejected. Defaults to ${DEFAULT_OUTPUT_LIMIT_BYTES}.`
+			}
+		},
+		required: ["id"]
+	};
+}
+/**
+* The declared shape of one outcome, exported so tests can validate real results.
+*
+* Split by `kind` instead of one flat object. The flat form could only require
+* `kind` and `id`, so a foreground result that omitted `exitCode` was still
+* "valid" and the schema proved nothing about the fields the model reads.
+*
+* `signal` is nullable because `child_process` reports `null` whenever the child
+* exited on its own — that is every successful run. Declaring it `string` made
+* the registry reject the tool's own normal output: `createSuccessResult()`
+* validates before rendering, so **every** clean exit surfaced to the model as
+* `tool "pstack_script" returned invalid output`.
+*/
+const OUTPUT_SCHEMA = { oneOf: [{
+	type: "object",
+	additionalProperties: false,
+	properties: {
+		kind: {
+			type: "string",
+			const: "foreground"
+		},
+		id: {
+			type: "string",
+			description: "Which bundled script ran."
+		},
+		exitCode: {
+			type: "integer",
+			description: "The child's exit code."
+		},
+		signal: {
+			oneOf: [{ type: "string" }, { type: "null" }],
+			description: "Terminating signal, or null when the script exited on its own."
+		},
+		timedOut: {
+			type: "boolean",
+			description: "True when this tool's own timeout killed the run."
+		},
+		stdout: { type: "string" },
+		stderr: { type: "string" },
+		stdoutTruncated: { type: "boolean" },
+		stderrTruncated: { type: "boolean" },
+		durationMs: { type: "integer" }
+	},
+	required: [
+		"kind",
+		"id",
+		"exitCode",
+		"signal",
+		"timedOut",
+		"stdout",
+		"stderr",
+		"stdoutTruncated",
+		"stderrTruncated",
+		"durationMs"
+	]
+}, {
+	type: "object",
+	additionalProperties: false,
+	properties: {
+		kind: {
+			type: "string",
+			const: "background"
+		},
+		id: {
+			type: "string",
+			description: "Which bundled script started."
+		},
+		jobId: {
+			type: "string",
+			description: "The Host job id to read or stop."
+		},
+		status: {
+			type: "string",
+			description: "Job status when the call returned."
+		}
+	},
+	required: [
+		"kind",
+		"id",
+		"jobId",
+		"status"
+	]
+}] };
+/** Build the tool for one row. */
+function createPstackScriptTool(host) {
+	return {
+		name: TOOL_NAME,
+		description: TOOL_DESCRIPTION,
+		parameters: buildScriptParameters(),
+		output: {
+			schema: OUTPUT_SCHEMA,
+			render: (_args, value) => [{
+				type: "text",
+				text: renderScriptOutcome(value)
+			}]
+		},
+		isConcurrencySafe: () => false,
+		/**
+		* The Host's last-resort budget for one call.
+		*
+		* `DEFAULT_TIMEOUT_MS` is the tool's own timer for a foreground run, and it fires
+		* first in every normal case: it kills the child and returns a `timedOut` result the
+		* model can read. This budget is larger on purpose, so it only ever wins when the
+		* tool's own machinery failed to return at all — a hung `await`, a timer that never
+		* ran — and the alternative would be a session blocked with no answer.
+		*
+		* `MAX_TIMEOUT_MS` rather than a new number: it is already the ceiling the tool
+		* accepts for a caller-supplied `timeoutMs`, so the Host budget can never be the
+		* thing that cuts short a run the caller was allowed to request.
+		*
+		* It does not bound a background job. The wrapper disposes its timer when `execute`
+		* settles, which is milliseconds after `jobs.start` returns.
+		*/
+		timeoutMs: MAX_TIMEOUT_MS,
+		async execute(rawArgs, exec) {
+			const args = parseScriptArgs(rawArgs);
+			const sessionCwd = exec.agent === void 0 ? void 0 : await host.workingDirectory.ensure(exec.agent, exec.signal);
+			const cwd = resolveWorkingDirectory(args.cwd, sessionCwd);
+			if (args.background) return await runBackground(args, {
+				jobs: host.getJobs?.(),
+				...cwd === void 0 ? {} : { cwd },
+				...exec.agent === void 0 ? {} : { caller: exec.agent.id }
+			});
+			return await runForeground(args, {
+				signal: exec.signal,
+				...cwd === void 0 ? {} : { cwd }
+			});
+		}
+	};
+}
+/** Cordis row name, used by Loader diagnostics. */
+const name = "pstack-script";
+/**
+* The hard dependencies.
+*
+* `tools` is the registry this row registers into; `workingDirectory` is what
+* turns the tool's `cwd` argument and its omitted case into the Session's
+* directory. Both are always present in a profile that has an Agent at all.
+*
+* `jobs` is deliberately absent: a composition without a job controller still
+* registers the tool, and only `background: true` is refused. Declaring `jobs`
+* here would keep the whole fiber inactive in every profile that has no job
+* controller, which is most of them.
+*/
+const inject = ["tools", "workingDirectory"];
+/**
+* Register `pstack_script` for this row.
+*
+* `inject` is what makes `ctx.tools` readable at all: without it Cordis runs
+* `apply` immediately and the service proxy throws
+* `cannot get property "tools" without inject`, so the row would register nothing
+* in any profile.
+*/
+function apply(ctx) {
+	ctx.tools.register(createPstackScriptTool({
+		tools: ctx.tools,
+		workingDirectory: ctx.workingDirectory,
+		getJobs: () => ctx.get?.("jobs")
+	}));
+}
+//#endregion
+export { DEFAULT_OUTPUT_LIMIT_BYTES, DEFAULT_TIMEOUT_MS, MAX_TIMEOUT_MS, OUTPUT_SCHEMA, SCRIPT_IDS, ScriptInputError, ScriptMissingError, TOOL_NAME, apply, buildScriptParameters, createPstackScriptTool, inject, name, parseScriptArgs, renderCapturedStream, renderScriptOutcome, resolveWorkingDirectory, runBackground, runForeground, scriptEnvironment, scriptPath };
+
+//# sourceMappingURL=script.mjs.map