dsh-pstack 0.2.0-beta.1 → 0.2.0-beta.3

package/dist/script.mjs

@@ -1,202 +1,47 @@
-import { t as ASSETS_ROOT } from "./paths-D_JlVmBk.mjs";
+import { i as PORT_ROOT } from "./paths-BT77khwm.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 = [
+// src/internal/script-registry.ts
+const SCRIPT_ENTRIES = [
 	{
 		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"
+		assetPath: "skills/poteto-mode/scripts/check-plan.mjs"
 	},
 	{
 		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"
+		assetPath: "skills/poteto-mode/scripts/watch-pr/watch-pr.mjs"
 	},
 	{
 		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"
+		assetPath: "skills/poteto-mode/scripts/worktree-audit.mjs"
 	},
 	{
 		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"
+		assetPath: "skills/show-me-your-work/scripts/log.mjs"
 	},
 	{
-		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"
+		id: "statechart",
+		assetPath: "skills/statechart/scripts/statechart.mjs"
 	}
 ];
-[...RUNTIME_CLIS, ...RUNTIME_TESTS];
-//#endregion
-//#region src/script.ts
+// 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 `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 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.
+* 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 = RUNTIME_CLIS.map((entry) => entry.id);
-/** Default wall-clock limit for a foreground run. */
+const SCRIPT_IDS = SCRIPT_ENTRIES.map((entry) => entry.id);
 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 {
@@ -214,20 +59,11 @@ var ScriptMissingError = class extends Error {
 };
 /** Absolute path of one shipped artefact. */
 function scriptPath(id) {
-	const entry = RUNTIME_CLIS.find((candidate) => candidate.id === id);
+	const entry = SCRIPT_ENTRIES.find((candidate) => candidate.id === id);
 	if (entry === void 0) throw new ScriptInputError(`unknown script id "${String(id)}"`);
-	return join(ASSETS_ROOT, ...entry.assetPath.split("/"));
+	return join(PORT_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.
-*/
+/** 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 {
@@ -279,33 +115,13 @@ function parseScriptArgs(raw) {
 		...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.
-*/
+/** 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, 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.
-*/
+/** 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();
@@ -361,7 +177,7 @@ async function runForeground(args, options = {}) {
 			resolve({
 				kind: "foreground",
 				id: args.id,
-				exitCode: code ?? (signal === null ? 1 : 1),
+				exitCode: code ?? 1,
 				signal,
 				timedOut,
 				stdout,
@@ -373,13 +189,7 @@ async function runForeground(args, options = {}) {
 		});
 	});
 }
-/**
-* 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.
-*/
+/** 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.");
@@ -387,38 +197,6 @@ async function runBackground(args, options) {
 	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,
@@ -458,21 +236,17 @@ async function runBackground(args, options) {
 			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");
-			});
+			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("error", (error) => settle({
+						status: "failed",
+						detail: error.code ?? "spawn-failed"
+					}));
 					child.once("close", (code, signal) => {
 						if (signal !== null) settle({
 							status: "killed",
@@ -488,12 +262,6 @@ async function runBackground(args, options) {
 			};
 		}
 	});
-	/**
-	* 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.`);
 	};
@@ -518,21 +286,7 @@ async function runBackground(args, options) {
 		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.
-*/
+/** 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));
@@ -580,7 +334,6 @@ const TOOL_DESCRIPTION = [
 	"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",
@@ -616,19 +369,6 @@ function buildScriptParameters() {
 		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,
@@ -713,22 +453,6 @@ function createPstackScriptTool(host) {
 			}]
 		},
 		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);
@@ -748,27 +472,9 @@ function createPstackScriptTool(host) {
 }
 /** 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.
-*/
+/** 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.
-*
-* `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.
-*/
+/** Register `pstack_script` for this row. */
 function apply(ctx) {
 	ctx.tools.register(createPstackScriptTool({
 		tools: ctx.tools,
@@ -776,7 +482,4 @@ function apply(ctx) {
 		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

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;