dsh-pstack 0.2.0 → 0.3.0-beta.1

package/dist/subagent.mjs

@@ -1,5 +1,5 @@
-import { a as POTETO_MODE_SKILL_PATH } from "./paths-BT77khwm.mjs";
-import { a as resolveDshHome, i as requireRole, o as selectRoleRoutes, r as readRoleConfiguration, t as modelsFilePath } from "./role-config-NNn5r1JX.mjs";
+import { a as POTETO_MODE_SKILL_PATH } from "./paths-yji9SNak.mjs";
+import { a as selectRoleRoutes, i as resolveDshHome, n as readRoleConfiguration, r as requireRole, t as modelsFilePath } from "./role-config-a4JpVdc-.mjs";
 import { isAbsolute, join, relative, resolve } from "node:path";
 import { existsSync, statSync } from "node:fs";
 // src/internal/effort.ts
@@ -149,6 +149,13 @@ const AGENT_KINDS = [
 	"general"
 ];
 const DEFAULT_CONFIG = { provider: DEFAULT_SUBAGENT_PROVIDER };
+/**
+* Depth a child runs at when a call omits `maxDepth` or passes an unusable value.
+*
+* A child is always at least depth 1 (it is one level below its parent), so this is the
+* smallest value that can start a child while forbidding it from delegating further.
+*/
+const DEFAULT_CHILD_MAX_DEPTH = 1;
 /** Raised for a configuration or argument problem, before any child starts. */
 var DelegationError = class extends Error {
 	constructor(message) {
@@ -214,22 +221,36 @@ function composeChildPrompt(input) {
 	sections.push(`Task:\n\n${input.task}`);
 	return sections.join("\n\n---\n\n");
 }
+const DELEGATION_ARGUMENT_KEYS = [
+	"description",
+	"prompt",
+	"agent",
+	"role",
+	"roleIndex",
+	"reasoningEffort",
+	"cwd",
+	"maxDepth"
+];
+/**
+* Keys a call must pass. `maxDepth` is accepted but not required: a missing or unusable
+* value resolves to `DEFAULT_CHILD_MAX_DEPTH` instead of forcing the caller to guess an
+* integer, which is where the reflexive `0` came from.
+*/
+const REQUIRED_DELEGATION_ARGUMENT_KEYS = [
+	"description",
+	"prompt",
+	"agent",
+	"role",
+	"roleIndex",
+	"reasoningEffort",
+	"cwd"
+];
 /** Validate every required model-facing argument. Null declines an optional setting. */
 function parseDelegationArgs(raw) {
 	if (typeof raw !== "object" || raw === null || Array.isArray(raw)) throw new DelegationError("arguments must be an object");
 	const record = raw;
-	const known = [
-		"description",
-		"prompt",
-		"agent",
-		"role",
-		"roleIndex",
-		"reasoningEffort",
-		"cwd",
-		"maxDepth"
-	];
-	for (const key of known) if (!Object.hasOwn(record, key)) throw new DelegationError(`missing required argument "${key}"; every argument must be passed explicitly`);
-	for (const key of Object.keys(record)) if (!known.includes(key)) throw new DelegationError(`unknown argument "${key}"; accepted arguments are ${known.join(", ")}`);
+	for (const key of REQUIRED_DELEGATION_ARGUMENT_KEYS) if (!Object.hasOwn(record, key)) throw new DelegationError(`missing required argument "${key}"; every argument except maxDepth must be passed explicitly`);
+	for (const key of Object.keys(record)) if (!DELEGATION_ARGUMENT_KEYS.includes(key)) throw new DelegationError(`unknown argument "${key}"; accepted arguments are ${DELEGATION_ARGUMENT_KEYS.join(", ")}`);
 	const description = record["description"];
 	if (!isNonEmptyString(description)) throw new DelegationError("description must be a non-empty string: it becomes the child label");
 	const prompt = record["prompt"];
@@ -240,8 +261,9 @@ function parseDelegationArgs(raw) {
 	if (role !== null && !isNonEmptyString(role)) throw new DelegationError("role must be a non-empty string or null");
 	const cwd = record["cwd"];
 	if (cwd !== null && !isNonEmptyString(cwd)) throw new DelegationError("cwd must be a non-empty string or null");
-	const maxDepth = record["maxDepth"];
-	if (!isNonNegativeSafeInteger(maxDepth)) throw new DelegationError("maxDepth must be a non-negative safe integer");
+	const rawMaxDepth = record["maxDepth"];
+	const maxDepth = rawMaxDepth === void 0 ? null : rawMaxDepth;
+	if (maxDepth !== null && !isNonNegativeSafeInteger(maxDepth)) throw new DelegationError("maxDepth must be a non-negative safe integer, or null/omitted");
 	const roleIndex = record["roleIndex"];
 	if (roleIndex !== null && !isNonNegativeSafeInteger(roleIndex)) throw new DelegationError("roleIndex must be a non-negative safe integer or null");
 	if (roleIndex !== null && role === null) throw new DelegationError("roleIndex requires a non-null role");
@@ -267,15 +289,30 @@ function routeLabel(route, effortOverride) {
 }
 /** Take the smallest of the requested depth, this row's cap, and the Host setting. */
 function resolveDelegationDepth(configured, requested, hostLimit) {
-	if (requested !== void 0 && !isNonNegativeSafeInteger(requested)) throw new DelegationError("maxDepth must be a non-negative safe integer");
-	if (configured !== void 0 && requested !== void 0 && requested > configured) throw new DelegationError(`maxDepth ${requested} exceeds this row's configured cap of ${configured}. Lower the request or raise \`pstack-subagent\` config.maxDepth.`);
+	if (requested !== void 0 && requested !== null && !isNonNegativeSafeInteger(requested)) throw new DelegationError("maxDepth must be a non-negative safe integer or null");
+	if (configured !== void 0 && requested !== void 0 && requested !== null && requested > configured) throw new DelegationError(`maxDepth ${requested} exceeds this row's configured cap of ${configured}. Lower the request or raise \`pstack-subagent\` config.maxDepth.`);
 	const candidates = [
 		configured,
 		requested,
 		hostLimit
-	].filter((value) => value !== void 0);
+	].filter((value) => value !== void 0 && value !== null);
 	return candidates.length === 0 ? void 0 : Math.min(...candidates);
 }
+/**
+* Turn the per-call `maxDepth` request into an effective depth request.
+*
+* A child is always at least depth 1, so `0` can never start one: it is reported and
+* replaced with `DEFAULT_CHILD_MAX_DEPTH` rather than failing the whole call. Omitting
+* `maxDepth` (null) also uses the default, so a caller never has to guess an integer.
+*/
+function requestedChildDepth(requested, diagnostics) {
+	if (requested === null) return 1;
+	if (requested === 0) {
+		diagnostics.push(`maxDepth 0 cannot start a child (the child itself is depth 1), so this call used 1. Omit maxDepth for that default, or pass 1 or more.`);
+		return 1;
+	}
+	return requested;
+}
 /** Resolve the role file, routes, prompt, and depth into one plan. Pure of service calls. */
 function planDelegation(args, runtime, config = DEFAULT_CONFIG) {
 	const rolePath = modelsFilePath(runtime.dshHome);
@@ -305,7 +342,7 @@ function planDelegation(args, runtime, config = DEFAULT_CONFIG) {
 		task: args.prompt
 	});
 	const agentPreset = agentPresetFor(args.agent);
-	const depth = resolveDelegationDepth(config.maxDepth, args.maxDepth, void 0);
+	const depth = resolveDelegationDepth(config.maxDepth, requestedChildDepth(args.maxDepth, diagnostics), void 0);
 	const total = routes.length;
 	const children = routes.map((route, index) => {
 		const agentOptions = agentOptionsFor(route, args.reasoningEffort ?? void 0);
@@ -495,9 +532,11 @@ async function delegate(parent, args, runtime, config = DEFAULT_CONFIG, signal =
 const TOOL_DESCRIPTION = [
 	"Delegate self-contained work to one or more fresh child agents.",
 	"",
-	"Every argument is required. Pass null for role, roleIndex, reasoningEffort, or cwd when that",
-	"setting is not used. Choose agent explicitly. maxDepth is a non-negative integer. No argument",
-	"has an implicit default.",
+	"Every argument is required except maxDepth. Pass null for role, roleIndex, reasoningEffort,",
+	"or cwd when that setting is not used. Choose agent explicitly. maxDepth is optional: omit it",
+	"(or pass null) for the safe default of 1, where the child exists but cannot start its own",
+	"children; pass 2 or more, within this row's configured cap, to let it delegate further. A 0 is",
+	"treated as 1, because a child is already depth 1 and 0 can never start one.",
 	"",
 	"Returns the id of every child it started plus the route each one resolved. The children run",
 	"in the background: their results arrive later as completion notices in this conversation.",
@@ -546,28 +585,19 @@ function buildParameters() {
 				description: "Required initial working directory, inside this session's directory or a separate Git worktree. Relative paths resolve against this session's directory. Null inherits the session directory."
 			},
 			maxDepth: {
-				type: "integer",
-				description: "Required non-negative delegation-depth limit. It can only lower this row's configured cap."
+				type: ["integer", "null"],
+				description: "Optional delegation-depth cap for the child. Omit or pass null for the safe default of 1 (the child exists but cannot start its own children). Pass 2 or more, within this row's configured cap, to let it delegate further. 0 is treated as 1: a child is already depth 1, so 0 can never start one."
 			},
 			roleIndex: {
 				type: ["integer", "null"],
-				description: "Required entry index for a list-valued role that is not an automatic panel, 0 or greater. Requires a non-null role. Null selects the first entry."
+				description: "Required entry index for a list-valued role that is not an automatic panel, 0 or greater. Requires a non-null role. Null selects the first entry. Call `pstack_roles` to see which roles accept an index."
 			},
 			reasoningEffort: {
 				type: ["string", "null"],
 				description: "Required reasoning-effort override for every child this call starts. Use one token the target model advertises, or null to keep the role line's starting effort. An unknown token fails the whole call before any child starts."
 			}
 		},
-		required: [
-			"description",
-			"prompt",
-			"agent",
-			"role",
-			"roleIndex",
-			"reasoningEffort",
-			"cwd",
-			"maxDepth"
-		]
+		required: [...REQUIRED_DELEGATION_ARGUMENT_KEYS]
 	};
 }
 const OUTPUT_SCHEMA = {
@@ -694,4 +724,4 @@ function describeError(error) {
 	}
 	return String(error);
 }
-export { AGENT_KINDS, AGENT_PRESETS, DEFAULT_SUBAGENT_PROVIDER, DelegationError, PartialDelegationError, TOOL_NAME, agentPresetFor, apply, assertProviderCapabilities, composeChildPrompt, createPstackSubagentTool, delegate, hostRuntime, inject, name, normalizeConfig, parseDelegationArgs, planDelegation, renderDelegationResult, resolveChildCwd, resolveDelegationDepth, routeLabel, startPlannedChildren };
+export { AGENT_KINDS, AGENT_PRESETS, DEFAULT_CHILD_MAX_DEPTH, DEFAULT_SUBAGENT_PROVIDER, DELEGATION_ARGUMENT_KEYS, DelegationError, PartialDelegationError, REQUIRED_DELEGATION_ARGUMENT_KEYS, TOOL_NAME, agentPresetFor, apply, assertProviderCapabilities, composeChildPrompt, createPstackSubagentTool, delegate, hostRuntime, inject, name, normalizeConfig, parseDelegationArgs, planDelegation, renderDelegationResult, requestedChildDepth, resolveChildCwd, resolveDelegationDepth, routeLabel, startPlannedChildren };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-pstack",
-  "version": "0.2.0",
+  "version": "0.3.0-beta.1",
   "description": "pstack for DeepSeek Harness: rigorous agent workflows ported from cursor/plugins.",
   "keywords": [
     "agent-skills",
@@ -38,6 +38,7 @@
     ".": "./dist/index.mjs",
     "./models": "./dist/models.mjs",
     "./remote": "./dist/remote.mjs",
+    "./role-catalog": "./dist/role-catalog.mjs",
     "./roles": "./dist/roles.mjs",
     "./script": "./dist/script.mjs",
     "./skill": "./dist/skill.mjs",
@@ -47,25 +48,26 @@
     "./locale/*.json": "./locale/*.json"
   },
   "dependencies": {
-    "@deepseek-ai/dsh-agent": "0.2.2-alpha.2",
-    "@deepseek-ai/dsh-jobs": "0.2.2-alpha.2",
-    "@deepseek-ai/dsh-llm": "0.2.2-alpha.2",
-    "@deepseek-ai/dsh-session": "0.2.2-alpha.2",
-    "@deepseek-ai/dsh-skill": "0.2.2-alpha.2",
-    "@deepseek-ai/dsh-subagent": "0.2.2-alpha.2",
-    "@deepseek-ai/dsh-system-prompt": "0.2.2-alpha.2",
-    "@deepseek-ai/dsh-tools": "0.2.2-alpha.2",
-    "@deepseek-ai/dsh-typert-protocol": "0.2.2-alpha.2",
-    "@deepseek-ai/dsh-working-directory": "0.2.2-alpha.2",
     "commander": "14.0.0"
   },
   "devDependencies": {
-    "@deepseek-ai/dsh-api-gateway": "0.2.2-alpha.2",
-    "@deepseek-ai/dsh-client-locale": "0.2.2-alpha.2",
-    "@deepseek-ai/dsh-client-ui-plugin-manager": "0.2.2-alpha.2",
-    "@deepseek-ai/dsh-client-ui-renderer": "0.2.2-alpha.2",
-    "@deepseek-ai/dsh-client-ui-slots": "0.2.2-alpha.2",
-    "@deepseek-ai/dsh-typert-registry": "0.2.2-alpha.2",
+    "@deepseek-ai/cordis": "~4.0.6-alpha.2",
+    "@deepseek-ai/dsh-agent": "0.2.2-alpha.3",
+    "@deepseek-ai/dsh-api-gateway": "0.2.2-alpha.3",
+    "@deepseek-ai/dsh-client-locale": "0.2.2-alpha.3",
+    "@deepseek-ai/dsh-client-ui-plugin-manager": "0.2.2-alpha.3",
+    "@deepseek-ai/dsh-client-ui-renderer": "0.2.2-alpha.3",
+    "@deepseek-ai/dsh-client-ui-slots": "0.2.2-alpha.3",
+    "@deepseek-ai/dsh-jobs": "0.2.2-alpha.3",
+    "@deepseek-ai/dsh-llm": "0.2.2-alpha.3",
+    "@deepseek-ai/dsh-session": "0.2.2-alpha.3",
+    "@deepseek-ai/dsh-skill": "0.2.2-alpha.3",
+    "@deepseek-ai/dsh-subagent": "0.2.2-alpha.3",
+    "@deepseek-ai/dsh-system-prompt": "0.2.2-alpha.3",
+    "@deepseek-ai/dsh-tools": "0.2.2-alpha.3",
+    "@deepseek-ai/dsh-typert-protocol": "0.2.2-alpha.3",
+    "@deepseek-ai/dsh-typert-registry": "0.2.2-alpha.3",
+    "@deepseek-ai/dsh-working-directory": "0.2.2-alpha.3",
     "@types/node": "^24.1.0",
     "@types/react": "~18.3.1",
     "@types/react-dom": "~18.3.0",
@@ -79,7 +81,7 @@
     "vite-plus": "1.4.0"
   },
   "peerDependencies": {
-    "@deepseek-ai/cordis": "~4.0.6-alpha.1"
+    "@deepseek-ai/cordis": "~4.0.6-alpha.2"
   },
   "icon": "./assets/logo.png",
   "devEngines": {
@@ -95,7 +97,7 @@
     }
   },
   "engines": {
-    "dsh": ">=0.2.1-rc.5",
+    "dsh": ">=0.2.2-alpha.3",
     "node": ">=24.21.1"
   },
   "dsh": {
@@ -130,7 +132,7 @@
     }
   ],
   "scripts": {
-    "prerelease": "vp run -r check && vp run -r test",
+    "prerelease": "vp run build && vp run -r check && vp run typecheck && vp run -r test",
     "release": "bumpp"
   }
 }

package/dist/role-manifest-C3fUzjLI.d.mts

@@ -1,19 +0,0 @@
-/**
- * The one pstack role manifest.
- *
- * Keys are matched exactly after normalization, and commas belong to some keys
- * (`feature, refactoring`, `reflect judgment, divergent, synthesizer`), so nothing here
- * may split a key on a comma. A second literal role list anywhere is a bug.
- *
- * This module has no Node imports: the bundle imports it directly.
- */
-/** Whether a role holds one route or a comma-separated list of routes. */
-type RoleValueShape = "single" | "list";
-interface RoleSpec {
-  /** Exact key as written in the role file. Commas belong to the key. */
-  readonly key: string;
-  readonly shape: RoleValueShape;
-  /** A list role that starts one child per entry automatically. */
-  readonly autoPanel: boolean;
-}
-export { RoleValueShape as n, RoleSpec as t };