dsh-pstack 0.2.0-beta.1 → 0.2.0

package/dist/role-wire-DZwTn2wF.d.mts

@@ -0,0 +1,55 @@
+import "./models.mjs";
+import { n as RoleValueShape } from "./role-manifest-C3fUzjLI.mjs";
+/** Which spelling of "inherit the parent route" a role line uses. */
+type InheritAlias = "inherit-parent" | "auto";
+/** One role value as the configuration page sees it. */
+type RouteView = {
+  readonly kind: "inherit";
+  readonly alias: InheritAlias;
+} | {
+  readonly kind: "route";
+  readonly provider: string;
+  readonly model: string;
+  readonly effort?: string;
+};
+/** One of the 17 roles in manifest order. */
+interface RoleView {
+  readonly key: string;
+  readonly shape: RoleValueShape;
+  /** Whether the role file configures this role. */
+  readonly configured: boolean;
+  /** The winning line, when the role file configures this role. */
+  readonly line?: number;
+  readonly routes: readonly RouteView[];
+  readonly issues: readonly string[];
+}
+/** One file-level problem. Unknown and malformed lines are reported, never dropped. */
+interface RoleFileIssue {
+  readonly line?: number;
+  readonly message: string;
+}
+/** Everything the configuration page renders about `$DSH_HOME/pstack-models.mdc`. */
+interface RoleFileSnapshot {
+  readonly path: string;
+  readonly status: "missing" | "loaded" | "unreadable";
+  readonly reason?: string;
+  readonly budget?: string;
+  readonly roles: readonly RoleView[];
+  readonly issues: readonly RoleFileIssue[];
+  /** False only when the file cannot be read at all. */
+  readonly canSave: boolean;
+}
+/** One role save. List roles carry every route, never only the edited one. */
+interface SaveRoleRequest {
+  readonly key: string;
+  readonly routes: readonly RouteView[];
+}
+/** A refused save leaves the file untouched and names the reason. */
+type SaveRoleResult = {
+  readonly ok: true;
+  readonly snapshot: RoleFileSnapshot;
+} | {
+  readonly ok: false;
+  readonly reason: string;
+};
+export { SaveRoleRequest as n, SaveRoleResult as r, RoleFileSnapshot as t };

package/dist/roles.d.mts

@@ -0,0 +1,18 @@
+import { CatalogueResult } from "./models.mjs";
+import { n as SaveRoleRequest, r as SaveRoleResult, t as RoleFileSnapshot } from "./role-wire-DZwTn2wF.mjs";
+import { Context, Service } from "@deepseek-ai/cordis";
+import { TypertRemoteService } from "@deepseek-ai/dsh-typert-protocol";
+/** Read and write the role file for the Plugins configuration page. */
+export declare class PstackRolesService extends TypertRemoteService {
+  static inject: string[];
+  constructor(ctx: Context);
+  protected [Service.init](): void;
+  /** Current path, status, values, and per-line issues. */
+  status(): RoleFileSnapshot;
+  /** The live directory the page offers for its provider/model/effort selects. */
+  catalogue(signal: AbortSignal): Promise<CatalogueResult>;
+  /** Validate and save one role, then return the reloaded snapshot. */
+  save(request: SaveRoleRequest, signal: AbortSignal): Promise<SaveRoleResult>;
+  private get llm();
+}
+export { PstackRolesService as default };

package/dist/roles.mjs

@@ -0,0 +1,323 @@
+import { collectCatalogue } from "./models.mjs";
+import { REMOTE_PACKAGE, ROLES_SERVICE, pstackRolesRemote } from "./remote.mjs";
+import { a as resolveDshHome, c as ROLE_MANIFEST, l as findRoleSpec, n as normalizeRoleName, r as readRoleConfiguration, s as INHERIT_PARENT_ALIASES, t as modelsFilePath } from "./role-config-NNn5r1JX.mjs";
+import { dirname } from "node:path";
+import { mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { Service } from "@deepseek-ai/cordis";
+import { TypertRemoteService } from "@deepseek-ai/dsh-typert-protocol";
+import { randomUUID } from "node:crypto";
+// src/internal/role-editor.ts
+/**
+* Role-file editing behind the Plugins configuration page.
+*
+* The writer changes exactly one role line and leaves every other byte of the
+* file alone: unknown lines, malformed lines, comments, and `# budget` survive a
+* save. Saves are validated against the live `pstack_models` catalogue before
+* the first byte is written, so a rejected save leaves the file unchanged.
+*/
+function routeView(route) {
+	if (route.kind === "inherit") return {
+		kind: "inherit",
+		alias: route.alias ?? "inherit-parent"
+	};
+	return {
+		kind: "route",
+		provider: route.provider,
+		model: route.model,
+		...route.effort === void 0 ? {} : { effort: route.effort }
+	};
+}
+function roleView(spec, entry) {
+	return {
+		key: spec.key,
+		shape: spec.shape,
+		configured: entry !== void 0,
+		...entry === void 0 ? {} : { line: entry.line },
+		routes: entry === void 0 ? [] : entry.routes.map(routeView),
+		issues: entry === void 0 ? [] : [...entry.issues]
+	};
+}
+/** Project a parsed file onto the manifest, preserving order and per-line issues. */
+function snapshotFromConfiguration(config) {
+	if (config.status === "unreadable") return {
+		path: config.path,
+		status: "unreadable",
+		reason: config.reason,
+		roles: ROLE_MANIFEST.map((spec) => roleView(spec, void 0)),
+		issues: [],
+		canSave: false
+	};
+	if (config.status === "missing") return {
+		path: config.path,
+		status: "missing",
+		roles: ROLE_MANIFEST.map((spec) => roleView(spec, void 0)),
+		issues: [],
+		canSave: true
+	};
+	return {
+		path: config.path,
+		status: "loaded",
+		...config.budget === void 0 ? {} : { budget: config.budget },
+		roles: ROLE_MANIFEST.map((spec) => roleView(spec, config.roles.get(spec.key))),
+		issues: config.issues.map((issue) => ({
+			...issue.line === void 0 ? {} : { line: issue.line },
+			message: issue.message
+		})),
+		canSave: true
+	};
+}
+/** Validate one save against the manifest and the live catalogue. */
+function validateSaveRequest(request, catalogue) {
+	if (typeof request !== "object" || request === null || Array.isArray(request)) return {
+		ok: false,
+		reason: "the save request must be an object"
+	};
+	if (typeof request.key !== "string") return {
+		ok: false,
+		reason: "the save request must name a role"
+	};
+	const spec = findRoleSpec(normalizeRoleName(request.key));
+	if (spec === void 0) return {
+		ok: false,
+		reason: `unknown role ${JSON.stringify(request.key)}`
+	};
+	if (!Array.isArray(request.routes)) return {
+		ok: false,
+		reason: `role "${spec.key}" must carry a route list`
+	};
+	if (spec.shape === "single" && request.routes.length !== 1) return {
+		ok: false,
+		reason: `role "${spec.key}" holds a single route; save exactly one`
+	};
+	if (request.routes.length === 0) return {
+		ok: false,
+		reason: `role "${spec.key}" must keep at least one route`
+	};
+	const routes = [];
+	for (let index = 0; index < request.routes.length; index += 1) {
+		const route = request.routes[index];
+		const position = request.routes.length === 1 ? "the route" : `route ${index + 1}`;
+		if (typeof route !== "object" || route === null || Array.isArray(route)) return {
+			ok: false,
+			reason: `${position} must be an object`
+		};
+		if (route.kind === "inherit") {
+			const alias = route.alias ?? "inherit-parent";
+			if (!INHERIT_PARENT_ALIASES.includes(alias)) return {
+				ok: false,
+				reason: `${position} has unknown inheritance alias ${JSON.stringify(alias)}; use \`inherit-parent\` or \`auto\``
+			};
+			routes.push({
+				kind: "inherit",
+				alias
+			});
+			continue;
+		}
+		const unknownKind = route.kind;
+		if (unknownKind !== "route") return {
+			ok: false,
+			reason: `${position} has unknown kind ${JSON.stringify(unknownKind)}`
+		};
+		const provider = typeof route.provider === "string" ? route.provider.trim() : "";
+		const model = typeof route.model === "string" ? route.model.trim() : "";
+		if (provider === "" || model === "") return {
+			ok: false,
+			reason: `${position} needs both a provider and a model`
+		};
+		const providerEntry = catalogue.providers.find((candidate) => candidate.provider === provider);
+		if (providerEntry === void 0) return {
+			ok: false,
+			reason: `provider ${JSON.stringify(provider)} is not in the live model directory; run \`pstack_models\` and pick a registered provider`
+		};
+		if (providerEntry.error !== void 0) return {
+			ok: false,
+			reason: `provider ${JSON.stringify(provider)} could not be discovered: ${providerEntry.error}`
+		};
+		const modelEntry = providerEntry.models.find((candidate) => candidate.id === model);
+		if (modelEntry === void 0) return {
+			ok: false,
+			reason: `provider ${JSON.stringify(provider)} does not advertise model ${JSON.stringify(model)}`
+		};
+		if (modelEntry.error !== void 0) return {
+			ok: false,
+			reason: `model ${JSON.stringify(`${provider}/${model}`)} could not be resolved: ${modelEntry.error}`
+		};
+		const effort = typeof route.effort === "string" ? route.effort.trim() : route.effort;
+		if (effort !== void 0 && effort !== "") {
+			if (!modelEntry.efforts.includes(effort)) return {
+				ok: false,
+				reason: `model ${JSON.stringify(`${provider}/${model}`)} does not declare effort ${JSON.stringify(effort)}; declared efforts: ${modelEntry.efforts.length === 0 ? "none" : modelEntry.efforts.join(", ")}`
+			};
+			routes.push({
+				kind: "route",
+				provider,
+				model,
+				effort
+			});
+			continue;
+		}
+		if (effort === "") return {
+			ok: false,
+			reason: `${position} has an empty effort; drop the effort or pick one`
+		};
+		routes.push({
+			kind: "route",
+			provider,
+			model
+		});
+	}
+	return {
+		ok: true,
+		value: {
+			spec,
+			routes
+		}
+	};
+}
+/** Render one role's routes in the role-file grammar. */
+function renderRoleValue(routes) {
+	return routes.map((route) => route.kind === "inherit" ? route.alias ?? "inherit-parent" : route.effort === void 0 ? `${route.provider}/${route.model}` : `${route.provider}/${route.model} [${route.effort}]`).join(", ");
+}
+function bodyStart(lines) {
+	if (lines[0]?.trim() !== "---") return 0;
+	for (let index = 1; index < lines.length; index += 1) if (lines[index]?.trim() === "---") return index + 1;
+	return 0;
+}
+/**
+* Replace the winning line for one role, or append one when absent.
+*
+* Every other line is returned verbatim. A role configured twice keeps its
+* earlier line and replaces the last one, which is the line the parser treats
+* as winning; the duplicate remains visible as a per-line issue.
+*/
+function updateRoleText(text, spec, value) {
+	const lines = text.split("\n");
+	const crlf = text.includes("\r\n");
+	if (lines.length > 0 && lines[lines.length - 1] === "") lines.pop();
+	let match = -1;
+	for (let index = bodyStart(lines); index < lines.length; index += 1) {
+		const line = lines[index];
+		const trimmed = line.endsWith("\r") ? line.slice(0, -1).trim() : line.trim();
+		if (trimmed === "" || trimmed.startsWith("#")) continue;
+		const separator = trimmed.indexOf(":");
+		if (separator === -1) continue;
+		if (normalizeRoleName(trimmed.slice(0, separator)) !== spec.key) continue;
+		match = index;
+	}
+	const rendered = `${spec.key}: ${value}`;
+	if (match >= 0) {
+		const original = lines[match];
+		const indent = /^\s*/.exec(original)?.[0] ?? "";
+		const ending = original.endsWith("\r") ? "\r" : "";
+		lines[match] = `${indent}${rendered}${ending}`;
+	} else lines.push(`${rendered}${crlf ? "\r" : ""}`);
+	return `${lines.join("\n")}\n`;
+}
+function writeAtomically(path, text) {
+	mkdirSync(dirname(path), { recursive: true });
+	const temporary = `${path}.${process.pid}.${randomUUID()}.tmp`;
+	try {
+		writeFileSync(temporary, text, "utf8");
+		renameSync(temporary, path);
+	} catch (error) {
+		rmSync(temporary, { force: true });
+		throw error;
+	}
+}
+/**
+* Save one role and return the reloaded snapshot.
+*
+* A missing file is created with just this role. An unreadable file is never
+* overwritten. Every refusal leaves the existing bytes untouched.
+*/
+function saveRoleConfiguration(path, request, catalogue) {
+	const current = readRoleConfiguration(path);
+	if (current.status === "unreadable") return {
+		ok: false,
+		reason: `the role file is unreadable: ${current.reason}`
+	};
+	const validation = validateSaveRequest(request, catalogue);
+	if (!validation.ok) return validation;
+	let existing = "";
+	if (current.status === "loaded") try {
+		existing = readFileSync(path, "utf8");
+	} catch (error) {
+		return {
+			ok: false,
+			reason: `the role file could not be read: ${describeError(error)}`
+		};
+	}
+	const next = updateRoleText(existing, validation.value.spec, renderRoleValue(validation.value.routes));
+	try {
+		writeAtomically(path, next);
+	} catch (error) {
+		return {
+			ok: false,
+			reason: `the role file could not be written: ${describeError(error)}`
+		};
+	}
+	return {
+		ok: true,
+		snapshot: snapshotFromConfiguration(readRoleConfiguration(path))
+	};
+}
+function describeError(error) {
+	if (error instanceof Error) {
+		const code = error.code;
+		return typeof code === "string" ? `${error.message} (${code})` : error.message;
+	}
+	return String(error);
+}
+// src/roles.ts
+/**
+* `pstack-roles`: the Host half of the role model configuration page.
+*
+* It owns no cached policy: every read and write goes to
+* `$DSH_HOME/pstack-models.mdc`, which `pstack_subagent` also re-reads on every
+* delegation. Saving therefore takes effect on the next delegation without a
+* restart, and an already running child keeps the route it started with.
+*/
+/** Read and write the role file for the Plugins configuration page. */
+var PstackRolesService = class extends TypertRemoteService {
+	static inject = ["llm", "typert"];
+	constructor(ctx) {
+		super(ctx, ROLES_SERVICE);
+	}
+	[Service.init]() {
+		const typert = this.ctx.typert;
+		if (typert === void 0) throw new Error("pstack-roles requires the Typert registry service");
+		typert.register({
+			package: REMOTE_PACKAGE,
+			face: "host",
+			schemas: [],
+			model: {
+				services: [],
+				events: [],
+				objects: []
+			},
+			invocations: pstackRolesRemote.descriptors
+		});
+	}
+	/** Current path, status, values, and per-line issues. */
+	status() {
+		return snapshotFromConfiguration(readRoleConfiguration(roleFilePath()));
+	}
+	/** The live directory the page offers for its provider/model/effort selects. */
+	async catalogue(signal) {
+		return collectCatalogue(this.llm, void 0, signal);
+	}
+	/** Validate and save one role, then return the reloaded snapshot. */
+	async save(request, signal) {
+		signal.throwIfAborted();
+		const catalogue = await collectCatalogue(this.llm, void 0, signal);
+		signal.throwIfAborted();
+		return saveRoleConfiguration(roleFilePath(), request, catalogue);
+	}
+	get llm() {
+		return this.ctx.llm;
+	}
+};
+function roleFilePath() {
+	return modelsFilePath(resolveDshHome());
+}
+export { PstackRolesService, PstackRolesService as default };

package/dist/script.d.mts

@@ -1,15 +1,11 @@
-import { a as JobsHost, g as ToolDefinition, i as JobId, o as JsonSchemaNode, u as SessionId, v as ToolsHost, y as WorkingDirectoryHost } from "./host-contract-o47JH_r8.mjs";
-//#region src/script.d.ts
+import { _ as ToolsHost, a as JobsHost, c as SessionId, g as ToolDefinition, i as JobId, o as JsonSchemaNode, v as WorkingDirectoryHost } from "./host-contract-CUPSpeNk.mjs";
 /** Model-facing tool name. */
 export declare const TOOL_NAME = "pstack_script";
 /** The shipped scripts this tool may run, in display order. */
 export declare const SCRIPT_IDS: string[];
 export type ScriptId = (typeof SCRIPT_IDS)[number];
-/** Default wall-clock limit for a foreground run. */
 export declare const DEFAULT_TIMEOUT_MS = 120000;
-/** Bounds a caller may set for one foreground run. */
 export declare const MAX_TIMEOUT_MS = 600000;
-/** Default cap on captured bytes per stream. */
 export declare const DEFAULT_OUTPUT_LIMIT_BYTES: number;
 /** Raised for an argument problem, before anything is spawned. */
 export declare class ScriptInputError extends Error {
@@ -19,7 +15,6 @@ export declare class ScriptInputError extends Error {
 export declare class ScriptMissingError extends Error {
   constructor(message: string);
 }
-/** One parsed call. */
 export interface ScriptArgs {
   readonly id: ScriptId;
   readonly args: readonly string[];
@@ -28,7 +23,6 @@ export interface ScriptArgs {
   readonly timeoutMs?: number;
   readonly outputLimitBytes?: number;
 }
-/** What a foreground run produced. */
 export interface ScriptResult {
   readonly kind: "foreground";
   readonly id: ScriptId;
@@ -37,74 +31,35 @@ export interface ScriptResult {
   readonly timedOut: boolean;
   readonly stdout: string;
   readonly stderr: string;
-  /** True when a stream was cut off at the limit. */
   readonly stdoutTruncated: boolean;
   readonly stderrTruncated: boolean;
   readonly durationMs: number;
 }
-/** What a background run produced. */
 export interface ScriptJobResult {
   readonly kind: "background";
   readonly id: ScriptId;
   readonly jobId: JobId;
   readonly status: string;
 }
-/** Either outcome, as the model sees it. */
 export type ScriptOutcome = ScriptResult | ScriptJobResult;
 /** Absolute path of one shipped artefact. */
 export declare function scriptPath(id: ScriptId): string;
-/**
- * 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. */
 export declare function scriptEnvironment(base?: NodeJS.ProcessEnv, versions?: {
   readonly electron?: string;
 }): NodeJS.ProcessEnv;
 /** Validate the raw tool arguments. */
 export declare function parseScriptArgs(raw: unknown): ScriptArgs;
-/**
- * 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. */
 export declare function resolveWorkingDirectory(requested: string | undefined, sessionCwd: string | undefined): string | undefined;
-/**
- * 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. */
 export declare function runForeground(args: ScriptArgs, options?: {
   readonly execPath?: string;
   readonly environment?: NodeJS.ProcessEnv;
-  /** Already resolved by the caller; see `resolveWorkingDirectory`. */
   readonly cwd?: string;
   readonly signal?: AbortSignal;
 }): Promise<ScriptResult>;
-/**
- * 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. */
 export declare function runBackground(args: ScriptArgs, options: {
   readonly jobs?: JobsHost | undefined;
   readonly caller?: SessionId;
@@ -112,82 +67,25 @@ export declare function runBackground(args: ScriptArgs, options: {
   readonly environment?: NodeJS.ProcessEnv;
   readonly cwd?: string;
 }): Promise<ScriptJobResult>;
-/**
- * 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. */
 export declare function renderCapturedStream(text: string): readonly string[];
 /** Render one outcome for the model. */
 export declare function renderScriptOutcome(outcome: ScriptOutcome): string;
-/** The model-facing JSON Schema for `parameters`. */
 export declare function buildScriptParameters(): Record<string, unknown>;
-/**
- * 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`.
- */
 export declare const OUTPUT_SCHEMA: JsonSchemaNode;
 /** The slices of the Cordis context this tool needs. */
 export interface PstackScriptHost {
   readonly tools: ToolsHost;
-  /** Resolves the Session's current directory; see `WorkingDirectoryHost`. */
   readonly workingDirectory: WorkingDirectoryHost;
-  /**
-   * Optional, and read per call rather than snapshotted.
-   *
-   * A profile may mount a job controller after this row, so a value read once in
-   * `apply` would stay `undefined` forever. `ctx.get("jobs")` is rc.3's
-   * optional-service read: it returns `undefined` instead of throwing when the
-   * service is absent, which is why `jobs` is not declared in `inject`.
-   */
   readonly getJobs?: () => JobsHost | undefined;
 }
 /** Build the tool for one row. */
 export declare function createPstackScriptTool(host: PstackScriptHost): ToolDefinition;
 /** Cordis row name, used by Loader diagnostics. */
 export declare 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. */
 export declare const inject: string[];
-/**
- * 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. */
 export declare function apply(ctx: PstackScriptHost & {
   get?: (name: string) => JobsHost | undefined;
-}): void;
-//#endregion
-//# sourceMappingURL=script.d.mts.map
+}): void;