dsh-pstack 0.1.0 → 0.2.0-beta.3

package/dist/script.mjs

@@ -0,0 +1,485 @@
+import { i as PORT_ROOT } from "./paths-BT77khwm.mjs";
+import { isAbsolute, join, resolve } from "node:path";
+import { spawn } from "node:child_process";
+// src/internal/script-registry.ts
+const SCRIPT_ENTRIES = [
+	{
+		id: "check-plan",
+		assetPath: "skills/poteto-mode/scripts/check-plan.mjs"
+	},
+	{
+		id: "watch-pr",
+		assetPath: "skills/poteto-mode/scripts/watch-pr/watch-pr.mjs"
+	},
+	{
+		id: "worktree-audit",
+		assetPath: "skills/poteto-mode/scripts/worktree-audit.mjs"
+	},
+	{
+		id: "log",
+		assetPath: "skills/show-me-your-work/scripts/log.mjs"
+	},
+	{
+		id: "statechart",
+		assetPath: "skills/statechart/scripts/statechart.mjs"
+	}
+];
+// src/script.ts
+/**
+* `pstack_script`: run a bundled pstack script through the Host's own runtime.
+*
+* The `id` is a closed enum over the shipped artefacts and resolves from this package,
+* so a call cannot reach a script the package does not contain. It is not a shell: no
+* `sh -c`, no glob expansion, no way to name another executable.
+*
+* The child is spawned with `process.execPath` — whichever binary runs this Host, Node or
+* Electron — and `ELECTRON_RUN_AS_NODE=1` only under Electron. That makes the npm CLI and
+* the Desktop build behave the same without `node` on `PATH`.
+*/
+/** Model-facing tool name. */
+const TOOL_NAME = "pstack_script";
+/** The shipped scripts this tool may run, in display order. */
+const SCRIPT_IDS = SCRIPT_ENTRIES.map((entry) => entry.id);
+const DEFAULT_TIMEOUT_MS = 12e4;
+const MAX_TIMEOUT_MS = 6e5;
+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 = SCRIPT_ENTRIES.find((candidate) => candidate.id === id);
+	if (entry === void 0) throw new ScriptInputError(`unknown script id "${String(id)}"`);
+	return join(PORT_ROOT, ...entry.assetPath.split("/"));
+}
+/** The environment a child gets: the Electron selector, and otherwise the caller's. */
+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, relative to the caller-established session directory. */
+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, signal, timeout, and truncation are returned, not thrown. */
+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 ?? 1,
+				signal,
+				timedOut,
+				stdout,
+				stderr,
+				stdoutTruncated,
+				stderrTruncated,
+				durationMs: Date.now() - started
+			});
+		});
+	});
+}
+/** Start a script as a background job. `jobs` absent is a refusal with a reason. */
+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;
+	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"}`
+						});
+					});
+				})
+			};
+		}
+	});
+	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 fence that the content cannot close early. */
+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");
+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"]
+	};
+}
+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,
+		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";
+/** Hard dependencies: the tool registry and the session directory. `jobs` is optional and read per call. */
+const inject = ["tools", "workingDirectory"];
+/** Register `pstack_script` for this row. */
+function apply(ctx) {
+	ctx.tools.register(createPstackScriptTool({
+		tools: ctx.tools,
+		workingDirectory: ctx.workingDirectory,
+		getJobs: () => ctx.get?.("jobs")
+	}));
+}
+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 };

package/dist/skill.d.mts

@@ -0,0 +1,38 @@
+import { _ as ToolsHost, g as ToolDefinition, l as SkillDefinition, p as SkillResourceBase, t as Agent } from "./host-contract-CUPSpeNk.mjs";
+/** Model-facing tool name. */
+export declare const TOOL_NAME = "pstack_skill";
+/** Cordis row name, used by Loader diagnostics. */
+export declare const name = "pstack-skill";
+/** The tool registry and the skill registry. */
+export declare const inject: string[];
+/** The slice of `ctx.skills` this tool reads. */
+export interface SkillsHost {
+  get(name: string, options?: {
+    readonly cwd?: string;
+    readonly signal?: AbortSignal;
+    readonly scope?: Agent;
+  }): Promise<SkillDefinition | undefined>;
+}
+export interface PstackSkillHost {
+  readonly skills: SkillsHost;
+  readonly tools: ToolsHost;
+}
+export interface SkillResourceResult {
+  readonly path: string;
+  readonly content: string;
+}
+export interface LoadSkillResult {
+  readonly name: string;
+  readonly provider: string;
+  readonly resourceBase?: SkillResourceBase;
+  readonly content: string;
+  readonly resource?: SkillResourceResult;
+}
+/** Render one loaded skill in the canonical `<skill_content>` shape. */
+export declare function renderLoadedSkill(result: LoadSkillResult): string;
+/** Read one resource below a directory skill, refusing traversal and absolute paths. */
+export declare function readSkillResource(definition: SkillDefinition, resource: string): Promise<SkillResourceResult>;
+/** Build the tool definition. Exported so tests can drive `execute` directly. */
+export declare function createPstackSkillTool(skills: SkillsHost): ToolDefinition;
+/** Register `pstack_skill` on one row. */
+export declare function apply(ctx: PstackSkillHost): void;