dsh-pstack 0.3.0-beta.1 → 0.3.1

package/dist/role-remote.mjs

@@ -0,0 +1,106 @@
+import { parseBudgetApplyRequest } from "./budget.mjs";
+import { parseCatalogueResult } from "./catalogue.mjs";
+import { parseBudgetApplyResult, parseRoleFileSnapshot, parseSaveRoleRequest, parseSaveRoleResult } from "./role-wire.mjs";
+// src/role-remote.ts
+/** npm package owning these methods. */
+const REMOTE_PACKAGE = "dsh-pstack";
+/** Cordis service key and wire namespace. */
+const ROLES_SERVICE = "pstackRoles";
+function codec(typeSymbol, parse) {
+	return {
+		mode: "strict",
+		typeSymbol,
+		create: () => ({ parse }),
+		decode: parse
+	};
+}
+function parameter(name, typeSymbol, parse) {
+	return {
+		name,
+		wire: name,
+		source: "json",
+		codec: codec(typeSymbol, parse)
+	};
+}
+function directMethod(options) {
+	return {
+		id: `${REMOTE_PACKAGE}#${ROLES_SERVICE}/${options.method}`,
+		service: ROLES_SERVICE,
+		namespace: ROLES_SERVICE,
+		method: options.method,
+		invocation: { kind: "direct" },
+		parameters: options.parameters,
+		result: options.result,
+		...options.cancellation === true ? { cancellation: { parameter: "signal" } } : {},
+		input() {
+			return { create: () => ({ parse(value) {
+				if (typeof value !== "object" || value === null || Array.isArray(value)) throw new TypeError("the method input must be an object");
+				const record = value;
+				const parsed = {};
+				for (const item of options.parameters) {
+					if (item.codec.mode !== "strict") throw new TypeError("expected a strict codec");
+					parsed[item.wire] = item.codec.create().parse(record[item.wire]);
+				}
+				return parsed;
+			} }) };
+		},
+		invoke(remote, input, signal) {
+			const namespace = Reflect.get(remote, ROLES_SERVICE);
+			const values = options.parameters.map((item) => input[item.wire]);
+			if (options.cancellation === true) values.push(signal);
+			return namespace[options.method](...values);
+		}
+	};
+}
+const statusMethod = directMethod({
+	method: "status",
+	parameters: [],
+	result: codec("PstackRoleFileSnapshot", parseRoleFileSnapshot)
+});
+const catalogueMethod = directMethod({
+	method: "catalogue",
+	parameters: [],
+	result: codec("PstackRoleCatalogue", parseCatalogueResult),
+	cancellation: true
+});
+const saveMethod = directMethod({
+	method: "save",
+	parameters: [parameter("request", "PstackSaveRoleRequest", parseSaveRoleRequest)],
+	result: codec("PstackSaveRoleResult", parseSaveRoleResult),
+	cancellation: true
+});
+const budgetMethod = directMethod({
+	method: "budget",
+	parameters: [parameter("request", "PstackBudgetApplyRequest", parseBudgetApplyRequest)],
+	result: codec("PstackBudgetApplyResult", parseBudgetApplyResult),
+	cancellation: true
+});
+/** Mountable contribution shared by Host registration and Client `$mount`. */
+const pstackRolesRemote = {
+	package: REMOTE_PACKAGE,
+	descriptors: [
+		statusMethod,
+		catalogueMethod,
+		saveMethod,
+		budgetMethod
+	],
+	methods: {
+		[`${ROLES_SERVICE}/status`]: statusMethod,
+		[`${ROLES_SERVICE}/catalogue`]: catalogueMethod,
+		[`${ROLES_SERVICE}/save`]: saveMethod,
+		[`${ROLES_SERVICE}/budget`]: budgetMethod
+	}
+};
+/** Register the Host's strict invocation definitions in `ctx.typert.local`. */
+const pstackRolesHostContribution = {
+	package: REMOTE_PACKAGE,
+	face: "host",
+	schemas: [],
+	model: {
+		services: [],
+		events: [],
+		objects: []
+	},
+	invocations: pstackRolesRemote.descriptors
+};
+export { REMOTE_PACKAGE, ROLES_SERVICE, pstackRolesHostContribution, pstackRolesRemote };

package/dist/{roles.d.mts → role-service.d.mts}

@@ -1,18 +1,22 @@
-import { CatalogueResult } from "./models.mjs";
-import { n as SaveRoleRequest, r as SaveRoleResult, t as RoleFileSnapshot } from "./role-wire-CAJsVA6e.mjs";
+import { n as CatalogueResult } from "./catalogue-wgVaGeUx.mjs";
+import "./models.mjs";
+import { BudgetApplyRequest } from "./budget.mjs";
+import { BudgetApplyResult, RoleFileSnapshot, SaveRoleRequest, SaveRoleResult } from "./role-wire.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. */
+/** Read and write `$DSH_HOME/pstack-models.mdc` for the Web settings 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. */
+  /** The live model directory used by the page's selectors. */
   catalogue(signal: AbortSignal): Promise<CatalogueResult>;
   /** Validate and save one role, then return the reloaded snapshot. */
   save(request: SaveRoleRequest, signal: AbortSignal): Promise<SaveRoleResult>;
+  /** Apply a global budget target and return the reloaded snapshot. */
+  budget(request: BudgetApplyRequest, signal: AbortSignal): Promise<BudgetApplyResult>;
   private get llm();
 }
 export { PstackRolesService as default };

package/dist/role-service.mjs

@@ -0,0 +1,43 @@
+import { collectCatalogue } from "./models.mjs";
+import { modelsFilePath, readRoleConfiguration, resolveDshHome } from "./role-config.mjs";
+import { saveBudgetConfiguration, saveRoleConfiguration, snapshotFromConfiguration } from "./role-editor.mjs";
+import { ROLES_SERVICE, pstackRolesHostContribution } from "./role-remote.mjs";
+import { Service } from "@deepseek-ai/cordis";
+import { TypertRemoteService } from "@deepseek-ai/dsh-typert-protocol";
+// src/role-service.ts
+/** Host role configuration service for the pstack settings page. */
+/** Read and write `$DSH_HOME/pstack-models.mdc` for the Web settings page. */
+var PstackRolesService = class extends TypertRemoteService {
+	static inject = ["llm", "typert"];
+	constructor(ctx) {
+		super(ctx, ROLES_SERVICE);
+	}
+	[Service.init]() {
+		this.ctx.typert.register(pstackRolesHostContribution);
+	}
+	/** Current path, status, values, and per-line issues. */
+	status() {
+		return snapshotFromConfiguration(readRoleConfiguration(roleFilePath()));
+	}
+	/** The live model directory used by the page's selectors. */
+	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();
+		return saveRoleConfiguration(roleFilePath(), request, this.llm, signal);
+	}
+	/** Apply a global budget target and return the reloaded snapshot. */
+	async budget(request, signal) {
+		signal.throwIfAborted();
+		return saveBudgetConfiguration(roleFilePath(), request, this.llm, signal);
+	}
+	get llm() {
+		return this.ctx.llm;
+	}
+};
+function roleFilePath() {
+	return modelsFilePath(resolveDshHome());
+}
+export { PstackRolesService, PstackRolesService as default };

package/dist/role-wire.d.mts

@@ -0,0 +1,54 @@
+import { n as InheritAlias, s as RoleShape } from "./role-manifest-D1npMjqZ.mjs";
+import { n as Route } from "./route-7SqXDYrL.mjs";
+import { a as parseCatalogueResult, n as CatalogueResult } from "./catalogue-wgVaGeUx.mjs";
+import { BudgetApplyRequest, parseBudgetApplyRequest } from "./budget.mjs";
+import { t as WireTypeError } from "./wire-error-D_r-UW4w.mjs";
+export type RouteView = Route;
+export interface RoleView {
+  readonly key: string;
+  readonly shape: RoleShape;
+  readonly configured: boolean;
+  readonly line?: number;
+  readonly routes: readonly RouteView[];
+  readonly issues: readonly string[];
+}
+export interface RoleFileIssueView {
+  readonly line?: number;
+  readonly message: string;
+}
+export interface RoleFileSnapshot {
+  readonly path: string;
+  readonly status: "missing" | "loaded" | "unreadable";
+  readonly reason?: string;
+  readonly budget?: string;
+  readonly roles: readonly RoleView[];
+  readonly issues: readonly RoleFileIssueView[];
+  readonly canSave: boolean;
+}
+export interface SaveRoleRequest {
+  readonly key: string;
+  readonly routes: readonly RouteView[];
+}
+export type SaveRoleResult = {
+  readonly ok: true;
+  readonly snapshot: RoleFileSnapshot;
+} | {
+  readonly ok: false;
+  readonly reason: string;
+};
+export type BudgetApplyResult = {
+  readonly ok: true;
+  readonly snapshot: RoleFileSnapshot;
+} | {
+  readonly ok: false;
+  readonly reason: string;
+};
+/** Parse one save request. An empty route list removes the role line. */
+export declare function parseSaveRoleRequest(value: unknown): SaveRoleRequest;
+/** Parse one role-file snapshot returned by the Host. */
+export declare function parseRoleFileSnapshot(value: unknown): RoleFileSnapshot;
+/** Parse one role-save result returned by the Host. */
+export declare function parseSaveRoleResult(value: unknown): SaveRoleResult;
+/** Parse one budget-apply result returned by the Host. */
+export declare function parseBudgetApplyResult(value: unknown): BudgetApplyResult;
+export { type BudgetApplyRequest, type CatalogueResult, type InheritAlias, WireTypeError, parseBudgetApplyRequest, parseCatalogueResult };

package/dist/role-wire.mjs

@@ -0,0 +1,127 @@
+import { INHERIT_ALIASES, ROLE_SHAPES, isRoleKey } from "./role-manifest.mjs";
+import { validateRouteParts } from "./route.mjs";
+import { WireTypeError } from "./wire-error.mjs";
+import { parseBudgetApplyRequest } from "./budget.mjs";
+import { parseCatalogueResult } from "./catalogue.mjs";
+// src/role-wire.ts
+/** Wire shapes shared by the role settings Host service and Client page. */
+function parseRecord(value, path) {
+	if (typeof value !== "object" || value === null || Array.isArray(value)) throw new WireTypeError(path, "an object");
+	return value;
+}
+function optionalString(record, key, path) {
+	const value = record[key];
+	if (value !== void 0 && typeof value !== "string") throw new WireTypeError(`${path}.${key}`, "a string when present");
+	return value;
+}
+function parseRouteView(value, path) {
+	const record = parseRecord(value, path);
+	if (record["kind"] === "inherit") {
+		const alias = record["alias"] ?? "inherit-parent";
+		if (typeof alias !== "string" || !INHERIT_ALIASES.includes(alias)) throw new WireTypeError(`${path}.alias`, "\"inherit-parent\" or \"auto\"");
+		return {
+			kind: "inherit",
+			alias
+		};
+	}
+	if (record["kind"] !== "route") throw new WireTypeError(`${path}.kind`, "\"route\" or \"inherit\"");
+	const provider = record["provider"];
+	const model = record["model"];
+	const effort = record["effort"];
+	if (typeof provider !== "string" || provider.trim() === "") throw new WireTypeError(`${path}.provider`, "a non-empty string");
+	if (typeof model !== "string" || model.trim() === "") throw new WireTypeError(`${path}.model`, "a non-empty string");
+	if (effort !== void 0 && (typeof effort !== "string" || effort.trim() === "")) throw new WireTypeError(`${path}.effort`, "a non-empty string when present");
+	const providerValue = provider.trim();
+	const modelValue = model.trim();
+	const effortValue = typeof effort === "string" ? effort.trim() : void 0;
+	const issue = validateRouteParts(providerValue, modelValue, effortValue);
+	if (issue !== void 0) throw new WireTypeError(path, issue);
+	return {
+		kind: "route",
+		provider: providerValue,
+		model: modelValue,
+		...effortValue === void 0 ? {} : { effort: effortValue }
+	};
+}
+/** Parse one save request. An empty route list removes the role line. */
+function parseSaveRoleRequest(value) {
+	const record = parseRecord(value, "request");
+	if (typeof record["key"] !== "string" || record["key"].trim() === "") throw new WireTypeError("request.key", "a non-empty string");
+	if (!Array.isArray(record["routes"])) throw new WireTypeError("request.routes", "an array");
+	return {
+		key: record["key"],
+		routes: record["routes"].map((route, index) => parseRouteView(route, `request.routes[${index}]`))
+	};
+}
+function parseRoleFileIssue(value, path) {
+	const record = parseRecord(value, path);
+	if (typeof record["message"] !== "string") throw new WireTypeError(`${path}.message`, "a string");
+	const line = record["line"];
+	if (line !== void 0 && typeof line !== "number") throw new WireTypeError(`${path}.line`, "a number when present");
+	return {
+		...typeof line === "number" ? { line } : {},
+		message: record["message"]
+	};
+}
+function parseRoleView(value, index) {
+	const path = `snapshot.roles[${index}]`;
+	const record = parseRecord(value, path);
+	if (typeof record["key"] !== "string" || !isRoleKey(record["key"])) throw new WireTypeError(`${path}.key`, "a role in the manifest");
+	if (typeof record["shape"] !== "string" || !ROLE_SHAPES.includes(record["shape"])) throw new WireTypeError(`${path}.shape`, "\"single\" or \"list\"");
+	if (typeof record["configured"] !== "boolean") throw new WireTypeError(`${path}.configured`, "a boolean");
+	if (!Array.isArray(record["routes"]) || !Array.isArray(record["issues"])) throw new WireTypeError(path, "routes and issues arrays");
+	const line = record["line"];
+	if (line !== void 0 && typeof line !== "number") throw new WireTypeError(`${path}.line`, "a number when present");
+	return {
+		key: record["key"],
+		shape: record["shape"],
+		configured: record["configured"],
+		...typeof line === "number" ? { line } : {},
+		routes: record["routes"].map((route, routeIndex) => parseRouteView(route, `${path}.routes[${routeIndex}]`)),
+		issues: record["issues"].map((issue, issueIndex) => {
+			if (typeof issue !== "string") throw new WireTypeError(`${path}.issues[${issueIndex}]`, "a string");
+			return issue;
+		})
+	};
+}
+/** Parse one role-file snapshot returned by the Host. */
+function parseRoleFileSnapshot(value) {
+	const record = parseRecord(value, "snapshot");
+	const status = record["status"];
+	if (status !== "missing" && status !== "loaded" && status !== "unreadable") throw new WireTypeError("snapshot.status", "\"missing\", \"loaded\", or \"unreadable\"");
+	if (typeof record["path"] !== "string") throw new WireTypeError("snapshot.path", "a string");
+	if (typeof record["canSave"] !== "boolean") throw new WireTypeError("snapshot.canSave", "a boolean");
+	if (!Array.isArray(record["roles"]) || !Array.isArray(record["issues"])) throw new WireTypeError("snapshot", "roles and issues arrays");
+	const reason = optionalString(record, "reason", "snapshot");
+	const budget = optionalString(record, "budget", "snapshot");
+	return {
+		path: record["path"],
+		status,
+		...typeof reason === "string" ? { reason } : {},
+		...typeof budget === "string" ? { budget } : {},
+		roles: record["roles"].map((role, index) => parseRoleView(role, index)),
+		issues: record["issues"].map((issue, index) => parseRoleFileIssue(issue, `snapshot.issues[${index}]`)),
+		canSave: record["canSave"]
+	};
+}
+function parseSnapshotResult(value) {
+	const record = parseRecord(value, "result");
+	if (record["ok"] === true) return {
+		ok: true,
+		snapshot: parseRoleFileSnapshot(record["snapshot"])
+	};
+	if (record["ok"] === false && typeof record["reason"] === "string") return {
+		ok: false,
+		reason: record["reason"]
+	};
+	throw new WireTypeError("result", "a successful snapshot or a refusal reason");
+}
+/** Parse one role-save result returned by the Host. */
+function parseSaveRoleResult(value) {
+	return parseSnapshotResult(value);
+}
+/** Parse one budget-apply result returned by the Host. */
+function parseBudgetApplyResult(value) {
+	return parseSnapshotResult(value);
+}
+export { WireTypeError, parseBudgetApplyRequest, parseBudgetApplyResult, parseCatalogueResult, parseRoleFileSnapshot, parseSaveRoleRequest, parseSaveRoleResult };

package/dist/route-7SqXDYrL.d.mts

@@ -0,0 +1,36 @@
+import { c as RoleSpec, n as InheritAlias } from "./role-manifest-D1npMjqZ.mjs";
+/** One resolved child route. */
+type Route = {
+  readonly kind: "inherit";
+  readonly alias: InheritAlias;
+} | {
+  readonly kind: "route";
+  readonly provider: string;
+  readonly model: string;
+  readonly effort?: string;
+};
+/** One parsed route token. */
+interface ParsedRoute {
+  readonly route?: Route;
+  readonly issue: string;
+}
+/** Parse one route token. */
+declare function parseRoute(raw: string): ParsedRoute;
+/** Parse one role value: a single route or a comma-separated list. */
+declare function parseRouteValue(raw: string): {
+  routes: readonly Route[];
+  issues: readonly string[];
+};
+/** Validate route parts shared by the text and wire parsers. */
+declare function validateRouteParts(provider: string, model: string, effort: string | undefined): string | undefined;
+/** Render one role value in the file grammar. */
+declare function renderRouteValue(routes: readonly Route[]): string;
+/** Type guard for a concrete route. */
+declare function isRoute(route: Route): route is Extract<Route, {
+  kind: "route";
+}>;
+/** The single-route shape rule shared by the file parser and the save validator. */
+declare function validateRoleRouteShape(spec: RoleSpec, routes: {
+  readonly length: number;
+}): string | undefined;
+export { parseRouteValue as a, validateRouteParts as c, parseRoute as i, Route as n, renderRouteValue as o, isRoute as r, validateRoleRouteShape as s, ParsedRoute as t };

package/dist/route.d.mts

@@ -0,0 +1,2 @@
+import { a as parseRouteValue, c as validateRouteParts, i as parseRoute, n as Route, o as renderRouteValue, r as isRoute, s as validateRoleRouteShape, t as ParsedRoute } from "./route-7SqXDYrL.mjs";
+export { ParsedRoute, Route, isRoute, parseRoute, parseRouteValue, renderRouteValue, validateRoleRouteShape, validateRouteParts };

package/dist/route.mjs

@@ -0,0 +1,78 @@
+import { INHERIT_ALIASES } from "./role-manifest.mjs";
+// src/route.ts
+/** The shared route grammar for the role file, wire codec, and editor. */
+/** Parse one route token. */
+function parseRoute(raw) {
+	const value = raw.trim();
+	if (value === "") return { issue: "the value is empty" };
+	const alias = value.toLowerCase();
+	if (INHERIT_ALIASES.includes(alias)) return {
+		route: {
+			kind: "inherit",
+			alias
+		},
+		issue: ""
+	};
+	const slash = value.indexOf("/");
+	if (slash <= 0 || slash === value.length - 1) return { issue: `${JSON.stringify(value)} is not a route; use \`inherit-parent\`, \`auto\`, or \`<provider>/<model> [effort]\`` };
+	const provider = value.slice(0, slash).trim();
+	let rest = value.slice(slash + 1).trim();
+	let effort;
+	const bracket = /\s*\[([^[\]]*)\]\s*$/.exec(rest);
+	if (bracket !== null) {
+		effort = bracket[1].trim();
+		rest = rest.slice(0, bracket.index).trim();
+	}
+	const model = rest;
+	const problem = validateRouteParts(provider, model, effort);
+	if (problem !== void 0) return { issue: `${JSON.stringify(value)} ${problem}` };
+	return {
+		route: {
+			kind: "route",
+			provider,
+			model,
+			...effort === void 0 ? {} : { effort }
+		},
+		issue: ""
+	};
+}
+/** Parse one role value: a single route or a comma-separated list. */
+function parseRouteValue(raw) {
+	const routes = [];
+	const issues = [];
+	const segments = raw.split(",");
+	segments.forEach((segment, index) => {
+		const value = segment.trim();
+		if (value === "") {
+			if (index !== segments.length - 1) issues.push(`entry ${index + 1} of the list is empty`);
+			return;
+		}
+		const parsed = parseRoute(value);
+		if (parsed.route === void 0) issues.push(parsed.issue);
+		else routes.push(parsed.route);
+	});
+	if (routes.length === 0 && issues.length === 0) issues.push("the value is empty; use `inherit-parent`, `auto`, or `<provider>/<model> [effort]`");
+	return {
+		routes,
+		issues
+	};
+}
+/** Validate route parts shared by the text and wire parsers. */
+function validateRouteParts(provider, model, effort) {
+	if (provider === "" || model === "" || /\s/.test(provider) || /\s/.test(model)) return "is not a route; provider and model cannot contain spaces";
+	if (effort !== void 0 && effort === "") return "has empty brackets; drop them or name an effort";
+	if (effort !== void 0 && /\s/.test(effort)) return "has a multi-word effort; an effort is one token";
+}
+/** Render one role value in the file grammar. */
+function renderRouteValue(routes) {
+	return routes.map((route) => route.kind === "inherit" ? route.alias : route.effort === void 0 ? `${route.provider}/${route.model}` : `${route.provider}/${route.model} [${route.effort}]`).join(", ");
+}
+/** Type guard for a concrete route. */
+function isRoute(route) {
+	return route.kind === "route";
+}
+/** The single-route shape rule shared by the file parser and the save validator. */
+function validateRoleRouteShape(spec, routes) {
+	if (spec.shape === "single" && routes.length > 1) return "a single-route role cannot hold a comma-separated list";
+}
+export { isRoute, parseRoute, parseRouteValue, renderRouteValue, validateRoleRouteShape, validateRouteParts };

package/dist/skill.d.mts

@@ -1,22 +1,9 @@
-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. */
+import { Context } from "@deepseek-ai/cordis";
+import { ToolDefinition } from "@deepseek-ai/dsh-tools";
+import { SkillDefinition, SkillRegistry, SkillResourceBase } from "@deepseek-ai/dsh-skill";
 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 declare const TOOL_NAME = "pstack_skill";
 export interface SkillResourceResult {
   readonly path: string;
   readonly content: string;
@@ -28,11 +15,10 @@ export interface LoadSkillResult {
   readonly content: string;
   readonly resource?: SkillResourceResult;
 }
-/** Render one loaded skill in the canonical `<skill_content>` shape. */
+/** Render one loaded skill in the shape DSH skill tools use. */
 export declare function renderLoadedSkill(result: LoadSkillResult): string;
-/** Read one resource below a directory skill, refusing traversal and absolute paths. */
+/** Read one resource relative to a directory-backed skill. */
 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;
+/** Build the tool for one skills registry. */
+export declare function createPstackSkillTool(skills: SkillRegistry): ToolDefinition;
+export declare function apply(ctx: Context): void;

package/dist/skill.mjs

@@ -1,47 +1,30 @@
-import { resolve, sep } from "node:path";
 import { readFile } from "node:fs/promises";
+import { resolve, sep } from "node:path";
 // src/skill.ts
 /**
-* `pstack_skill`: the trusted skill loader for pstack's own instructions.
+* `pstack_skill`: trusted loading of pstack skills by name.
 *
-* pstack hides most of its skills from the model catalog: `how`, `why`, `architect`,
-* `arena`, and the principle skills all declare `disable-model-invocation: true`, so
-* `poteto-mode` cannot route to them through DSH's `skill` tool. The registry's
-* `get()` is deliberately usable by trusted callers without that policy, which is the
-* public seam this tool consumes. It accepts a skill name, not a path, so a call can
-* only load a skill the package itself registered.
-*
-* The optional `resource` argument reads one file below the skill's directory. It is a
-* convenience for the references and playbooks that live beside `SKILL.md`; the path is
-* resolved and checked against the skill directory before reading, so `../` cannot
-* escape it.
+* `dsh-tool-skill` applies the model-invocation policy at the catalog boundary.
+* `ctx.skills.get()` is invocation-neutral, which is the seam this tool uses to
+* load a skill that `disable-model-invocation: true` hides from the model.
 */
-/** Model-facing tool name. */
-const TOOL_NAME = "pstack_skill";
-/** Cordis row name, used by Loader diagnostics. */
 const name = "pstack-skill";
-/** The tool registry and the skill registry. */
 const inject = ["skills", "tools"];
+const TOOL_NAME = "pstack_skill";
 const SKILL_NAME = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
-/** Render one loaded skill in the canonical `<skill_content>` shape. */
+/** Render one loaded skill in the shape DSH skill tools use. */
 function renderLoadedSkill(result) {
-	const lines = [`<skill_content name="${escapeAttr(result.name)}">`, "<skill_resources>"];
+	const lines = [`<skill_content name="${escapeAttribute(result.name)}">`, "<skill_resources>"];
 	if (result.resourceBase === void 0) lines.push(`Resources for this skill are managed by provider "${escapeText(result.provider)}".`, "Load referenced resources only as needed.");
 	else if (result.resourceBase.kind === "directory") lines.push(`Base directory for this skill: ${escapeText(result.resourceBase.path)}`, "Resolve relative paths mentioned by this skill against the base directory before using them. Load referenced resources only as needed.");
 	else if (result.resourceBase.kind === "url") lines.push(`Base URL for this skill: ${escapeText(result.resourceBase.url)}`, "Resolve relative URLs mentioned by this skill against the base URL before using them. Load referenced resources only as needed.");
 	else lines.push(`Resources for this skill: ${escapeText(result.resourceBase.description)}`, "Load referenced resources only as needed.");
 	lines.push("</skill_resources>", "", "<skill_instructions>", result.content, "</skill_instructions>");
-	if (result.resource !== void 0) lines.push("", `<skill_resource path="${escapeAttr(result.resource.path)}">`, result.resource.content, "</skill_resource>");
+	if (result.resource !== void 0) lines.push("", `<skill_resource path="${escapeAttribute(result.resource.path)}">`, result.resource.content, "</skill_resource>");
 	lines.push("</skill_content>");
 	return lines.join("\n");
 }
-function escapeAttr(value) {
-	return value.replaceAll("&", "&amp;").replaceAll("\"", "&quot;").replaceAll("<", "&lt;");
-}
-function escapeText(value) {
-	return value.replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;");
-}
-/** Read one resource below a directory skill, refusing traversal and absolute paths. */
+/** Read one resource relative to a directory-backed skill. */
 async function readSkillResource(definition, resource) {
 	const base = definition.resourceBase;
 	if (base === void 0 || base.kind !== "directory") throw new Error(`skill "${definition.name}" does not expose a directory resource base`);
@@ -125,11 +108,11 @@ const OUTPUT_SCHEMA = {
 const TOOL_DESCRIPTION = [
 	"Load the full instructions of any pstack skill by name, including skills hidden from the model catalog.",
 	"",
-	"Use this when a pstack skill tells you to route through another pstack skill (for example how, why, or architect) and the `skill` tool reports that it is unavailable because the skill disables model invocation.",
+	"Use this when a pstack skill tells you to route through another pstack skill and the `skill` tool cannot see it because the skill disables model invocation.",
 	"",
-	"Pass `resource` with a path relative to the skill directory to read one reference or playbook beside its SKILL.md. The path cannot leave the skill directory."
+	"Pass `resource` with a path relative to the skill directory to read one reference or playbook beside its `SKILL.md`. The path cannot leave the skill directory."
 ].join("\n");
-/** Build the tool definition. Exported so tests can drive `execute` directly. */
+/** Build the tool for one skills registry. */
 function createPstackSkillTool(skills) {
 	return {
 		name: TOOL_NAME,
@@ -144,7 +127,7 @@ function createPstackSkillTool(skills) {
 				},
 				resource: {
 					type: "string",
-					description: "Optional path relative to the skill directory, such as `references/explorer-prompt.md`."
+					description: "Optional path relative to the skill directory."
 				}
 			},
 			required: ["name"]
@@ -158,26 +141,34 @@ function createPstackSkillTool(skills) {
 		},
 		isConcurrencySafe: () => true,
 		async execute(rawArgs, exec) {
+			if (typeof rawArgs !== "object" || rawArgs === null || Array.isArray(rawArgs)) throw new Error("pstack_skill takes an object argument");
 			const args = rawArgs;
-			if (typeof args.name !== "string" || !SKILL_NAME.test(args.name)) throw new Error(`invalid skill name "${String(args.name)}"`);
-			if (args.resource !== void 0 && typeof args.resource !== "string") throw new Error("resource must be a string when present");
-			const definition = await skills.get(args.name, {
+			const skillName = args["name"];
+			const resource = args["resource"];
+			if (typeof skillName !== "string" || !SKILL_NAME.test(skillName)) throw new Error(`invalid skill name "${String(skillName)}"`);
+			if (resource !== void 0 && typeof resource !== "string") throw new Error("resource must be a string when present");
+			const definition = await skills.get(skillName, {
 				signal: exec.signal,
 				...exec.agent === void 0 ? {} : { scope: exec.agent }
 			});
-			if (definition === void 0) throw new Error(`skill "${args.name}" is unknown or no longer available`);
+			if (definition === void 0) throw new Error(`skill "${skillName}" is unknown or no longer available`);
 			return {
 				name: definition.name,
 				provider: definition.provider,
 				...definition.resourceBase === void 0 ? {} : { resourceBase: definition.resourceBase },
 				content: definition.content,
-				...args.resource === void 0 ? {} : { resource: await readSkillResource(definition, args.resource) }
+				...resource === void 0 ? {} : { resource: await readSkillResource(definition, resource) }
 			};
 		}
 	};
 }
-/** Register `pstack_skill` on one row. */
 function apply(ctx) {
 	ctx.tools.register(createPstackSkillTool(ctx.skills));
 }
+function escapeAttribute(value) {
+	return value.replaceAll("&", "&amp;").replaceAll("\"", "&quot;").replaceAll("<", "&lt;");
+}
+function escapeText(value) {
+	return value.replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;");
+}
 export { TOOL_NAME, apply, createPstackSkillTool, inject, name, readSkillResource, renderLoadedSkill };