dsh-pstack 0.2.0 → 0.3.0-beta.1

package/dist/{role-config-NNn5r1JX.mjs → role-config-a4JpVdc-.mjs}

@@ -1,108 +1,97 @@
+import { i as findRoleSpec, n as PSTACK_MODELS_FILENAME, o as normalizeRoleName, r as ROLE_MANIFEST, t as INHERIT_PARENT_ALIASES } from "./role-manifest-79cnFfDM.mjs";
 import { join, resolve } from "node:path";
 import { readFileSync } from "node:fs";
 import { homedir } from "node:os";
-// src/internal/role-manifest.ts
-/**
-* File name the role configuration lives under inside `$DSH_HOME`.
-*
-* It keeps the upstream name `pstack-models.mdc`, so a reader moving from the Cursor docs
-* recognizes it, but stores it directly under `$DSH_HOME`; DSH does not load `.mdc` files
-* on its own, and `pstack_subagent` is the only reader.
-*/
-const PSTACK_MODELS_FILENAME = "pstack-models.mdc";
-/** Values that resolve to "send no `agentOptions` and inherit the parent route". */
-const INHERIT_PARENT_ALIASES = ["inherit-parent", "auto"];
-/** The 17 roles, in manifest order. */
-const ROLE_MANIFEST = [
-	{
-		key: "feature, refactoring",
-		shape: "single",
-		autoPanel: false
-	},
-	{
-		key: "bug-fix",
-		shape: "single",
-		autoPanel: false
-	},
-	{
-		key: "perf-issue",
-		shape: "single",
-		autoPanel: false
-	},
-	{
-		key: "hillclimb",
-		shape: "single",
-		autoPanel: false
-	},
-	{
-		key: "judgment and prose",
-		shape: "single",
-		autoPanel: false
-	},
-	{
-		key: "hardest tasks",
-		shape: "single",
-		autoPanel: false
-	},
-	{
-		key: "how explorer",
-		shape: "single",
-		autoPanel: false
-	},
-	{
-		key: "how explainer",
-		shape: "single",
-		autoPanel: false
-	},
-	{
-		key: "why investigators",
-		shape: "single",
-		autoPanel: false
-	},
-	{
-		key: "why synthesizer",
-		shape: "single",
-		autoPanel: false
-	},
-	{
-		key: "reflect tooling",
-		shape: "single",
-		autoPanel: false
-	},
-	{
-		key: "reflect judgment, divergent, synthesizer",
-		shape: "single",
-		autoPanel: false
-	},
-	{
-		key: "arena runners",
-		shape: "list",
-		autoPanel: true
-	},
-	{
-		key: "arena cross-judge pool",
-		shape: "list",
-		autoPanel: false
-	},
-	{
-		key: "swarm workers",
-		shape: "list",
-		autoPanel: false
-	},
-	{
-		key: "architect runners",
-		shape: "list",
-		autoPanel: true
-	},
-	{
-		key: "interrogate reviewers",
-		shape: "list",
-		autoPanel: true
+// src/internal/role-grammar.ts
+function frontmatterBodyStart(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;
+}
+/** One line grammar for role parsing and byte-preserving updates. */
+function scanRoleDocument(text) {
+	const lines = text.split("\n");
+	if (lines.length > 0 && lines[lines.length - 1] === "") lines.pop();
+	const bodyStart = frontmatterBodyStart(lines);
+	const scanned = [];
+	let offset = 0;
+	for (let index = 0; index < lines.length; index += 1) {
+		const rawLine = lines[index];
+		const line = index + 1 - bodyStart;
+		const contentEnd = offset + rawLine.length - (rawLine.endsWith("\r") ? 1 : 0);
+		if (index < bodyStart) {
+			scanned.push({
+				kind: "blank",
+				line
+			});
+			offset += rawLine.length + 1;
+			continue;
+		}
+		const trimmed = rawLine.trim();
+		if (trimmed === "") scanned.push({
+			kind: "blank",
+			line
+		});
+		else if (trimmed.startsWith("#")) {
+			const match = /^#\s*budget:\s*(.+)$/i.exec(trimmed);
+			scanned.push({
+				kind: "comment",
+				line,
+				...match === null ? {} : { budget: match[1].trim() }
+			});
+		} else {
+			const separator = trimmed.indexOf(":");
+			if (separator === -1) scanned.push({
+				kind: "malformed",
+				line,
+				rawLine: trimmed
+			});
+			else {
+				const rawKey = trimmed.slice(0, separator).trim();
+				const key = normalizeRoleName(rawKey);
+				const spec = findRoleSpec(key);
+				if (key === "") scanned.push({
+					kind: "malformed",
+					line,
+					rawLine: ""
+				});
+				else if (spec === void 0) scanned.push({
+					kind: "unknown-role",
+					line,
+					rawKey
+				});
+				else {
+					const valueText = rawLine.slice(0, contentEnd - offset);
+					const sourceSeparator = valueText.indexOf(":");
+					const afterSeparator = valueText.slice(sourceSeparator + 1);
+					const rawValue = afterSeparator.trim();
+					const valueLeading = rawValue === "" ? 0 : afterSeparator.length - afterSeparator.trimStart().length;
+					const valueTrailing = rawValue === "" ? 0 : afterSeparator.length - afterSeparator.trimEnd().length;
+					const valueStart = offset + sourceSeparator + 1 + valueLeading;
+					const valueEnd = contentEnd - valueTrailing;
+					scanned.push({
+						kind: "role",
+						line,
+						rawKey,
+						key,
+						rawValue,
+						spec,
+						valueStart,
+						valueEnd
+					});
+				}
+			}
+		}
+		offset += rawLine.length + 1;
 	}
-];
-/** Exact manifest lookup. Callers normalize the key first. */
-function findRoleSpec(key) {
-	return ROLE_MANIFEST.find((role) => role.key === key);
+	return { lines: scanned };
+}
+/** Replace only the winning role's value, retaining every other source byte. */
+function updateRoleDocument(text, spec, value) {
+	const winning = scanRoleDocument(text).lines.findLast((line) => line.kind === "role" && line.key === spec.key);
+	if (winning?.kind === "role") return `${text.slice(0, winning.valueStart)}${value}${text.slice(winning.valueEnd)}`;
+	const eol = text.includes("\r\n") ? "\r\n" : "\n";
+	return `${text}${text === "" || text.endsWith("\n") ? "" : eol}${spec.key}: ${value}${eol}`;
 }
 // src/internal/role-config.ts
 /**
@@ -149,49 +138,36 @@ function parseRoleConfiguration(text, path) {
 	const issues = [];
 	const roles = /* @__PURE__ */ new Map();
 	let budget;
-	stripFrontmatter(text).split("\n").forEach((rawLine, index) => {
-		const line = index + 1;
-		const trimmed = rawLine.trim();
-		if (trimmed === "") return;
-		if (trimmed.startsWith("#")) {
-			const match = /^#\s*budget:\s*(.+)$/i.exec(trimmed);
-			if (match !== null) budget = match[1].trim();
-			return;
-		}
-		const separator = trimmed.indexOf(":");
-		if (separator === -1) {
-			issues.push({
-				line,
-				message: `expected \`<role>: <value>\`, found ${JSON.stringify(trimmed)}`
-			});
-			return;
+	for (const scanned of scanRoleDocument(text).lines) {
+		const { line } = scanned;
+		if (scanned.kind === "blank") continue;
+		if (scanned.kind === "comment") {
+			if (scanned.budget !== void 0) budget = scanned.budget;
+			continue;
 		}
-		const rawKey = trimmed.slice(0, separator).trim();
-		const rawValue = trimmed.slice(separator + 1).trim();
-		const key = normalizeRoleName(rawKey);
-		if (key === "") {
+		if (scanned.kind === "malformed") {
 			issues.push({
 				line,
-				message: "the role key is empty"
+				message: scanned.rawLine === "" ? "the role key is empty" : `expected \`<role>: <value>\`, found ${JSON.stringify(scanned.rawLine)}`
 			});
-			return;
+			continue;
 		}
-		const spec = findRoleSpec(key);
-		if (spec === void 0) {
+		if (scanned.kind === "unknown-role") {
 			issues.push({
 				line,
-				message: unknownRoleMessage(rawKey, key)
+				message: unknownRoleMessage(scanned.rawKey, normalizeRoleName(scanned.rawKey))
 			});
-			return;
+			continue;
 		}
-		const parsed = parseRouteValue(rawValue);
+		const { rawKey, spec } = scanned;
+		const parsed = parseRouteValue(scanned.rawValue);
 		const entryIssues = [...parsed.issues];
 		if (spec.shape === "single" && parsed.routes.length > 1) entryIssues.push("a single-route role cannot hold a comma-separated list");
 		for (const issue of entryIssues) issues.push({
 			line,
 			message: `${rawKey}: ${issue}`
 		});
-		if (parsed.routes.length === 0) return;
+		if (parsed.routes.length === 0) continue;
 		const previous = roles.get(spec.key);
 		if (previous !== void 0) issues.push({
 			line,
@@ -205,7 +181,7 @@ function parseRoleConfiguration(text, path) {
 			routes: parsed.routes,
 			issues: entryIssues
 		});
-	});
+	}
 	return budget === void 0 ? {
 		status: "loaded",
 		path,
@@ -335,10 +311,6 @@ var RoleNameError = class extends Error {
 		this.name = "RoleNameError";
 	}
 };
-/** Normalize a role name for lookup. Case, spacing, spacing around a comma, and a trailing colon are formatting. */
-function normalizeRoleName(raw) {
-	return raw.normalize("NFC").trim().toLowerCase().replace(/\s+/g, " ").replace(/\s*,\s*/g, ", ").replace(/:+$/, "").trim();
-}
 /** Resolve a role name, or throw a diagnostic that names the near misses. */
 function requireRole(raw) {
 	const spec = findRoleSpec(normalizeRoleName(raw));
@@ -394,14 +366,6 @@ function editDistance(left, right) {
 	}
 	return previous[right.length];
 }
-function stripFrontmatter(text) {
-	const normalized = text.replaceAll("\r\n", "\n");
-	if (!normalized.startsWith("---\n")) return normalized;
-	const end = normalized.indexOf("\n---", 3);
-	if (end === -1) return normalized;
-	const after = normalized.indexOf("\n", end + 1);
-	return after === -1 ? "" : normalized.slice(after + 1);
-}
 function isMissingFile(error) {
 	return typeof error === "object" && error !== null && error.code === "ENOENT";
 }
@@ -412,4 +376,4 @@ function describeError(error) {
 	}
 	return String(error);
 }
-export { resolveDshHome as a, ROLE_MANIFEST as c, requireRole as i, findRoleSpec as l, normalizeRoleName as n, selectRoleRoutes as o, readRoleConfiguration as r, INHERIT_PARENT_ALIASES as s, modelsFilePath as t };
+export { selectRoleRoutes as a, resolveDshHome as i, readRoleConfiguration as n, updateRoleDocument as o, requireRole as r, modelsFilePath as t };

package/dist/role-manifest-79cnFfDM.mjs

@@ -0,0 +1,112 @@
+// src/internal/role-manifest.ts
+/**
+* File name the role configuration lives under inside `$DSH_HOME`.
+*
+* It keeps the upstream name `pstack-models.mdc`, so a reader moving from the Cursor docs
+* recognizes it, but stores it directly under `$DSH_HOME`; DSH does not load `.mdc` files
+* on its own, and `pstack_subagent` is the only reader.
+*/
+const PSTACK_MODELS_FILENAME = "pstack-models.mdc";
+/** Values that resolve to "send no `agentOptions` and inherit the parent route". */
+const INHERIT_PARENT_ALIASES = ["inherit-parent", "auto"];
+/** The 17 roles, in manifest order. */
+const ROLE_MANIFEST = [
+	{
+		key: "feature, refactoring",
+		shape: "single",
+		autoPanel: false
+	},
+	{
+		key: "bug-fix",
+		shape: "single",
+		autoPanel: false
+	},
+	{
+		key: "perf-issue",
+		shape: "single",
+		autoPanel: false
+	},
+	{
+		key: "hillclimb",
+		shape: "single",
+		autoPanel: false
+	},
+	{
+		key: "judgment and prose",
+		shape: "single",
+		autoPanel: false
+	},
+	{
+		key: "hardest tasks",
+		shape: "single",
+		autoPanel: false
+	},
+	{
+		key: "how explorer",
+		shape: "single",
+		autoPanel: false
+	},
+	{
+		key: "how explainer",
+		shape: "single",
+		autoPanel: false
+	},
+	{
+		key: "why investigators",
+		shape: "single",
+		autoPanel: false
+	},
+	{
+		key: "why synthesizer",
+		shape: "single",
+		autoPanel: false
+	},
+	{
+		key: "reflect tooling",
+		shape: "single",
+		autoPanel: false
+	},
+	{
+		key: "reflect judgment, divergent, synthesizer",
+		shape: "single",
+		autoPanel: false
+	},
+	{
+		key: "arena runners",
+		shape: "list",
+		autoPanel: true
+	},
+	{
+		key: "arena cross-judge pool",
+		shape: "list",
+		autoPanel: false
+	},
+	{
+		key: "swarm workers",
+		shape: "list",
+		autoPanel: false
+	},
+	{
+		key: "architect runners",
+		shape: "list",
+		autoPanel: true
+	},
+	{
+		key: "interrogate reviewers",
+		shape: "list",
+		autoPanel: true
+	}
+];
+function isRoleKey(value) {
+	return ROLE_MANIFEST.some((role) => role.key === value);
+}
+/** Normalize formatting while keeping commas that belong to a role name. */
+function normalizeRoleName(raw) {
+	return raw.normalize("NFC").trim().toLowerCase().replace(/\s+/g, " ").replace(/\s*,\s*/g, ", ").replace(/:+$/, "").trim();
+}
+/** Exact manifest lookup. Callers normalize the key first. */
+function findRoleSpec(key) {
+	if (!isRoleKey(key)) return void 0;
+	return ROLE_MANIFEST.find((role) => role.key === key);
+}
+export { isRoleKey as a, findRoleSpec as i, PSTACK_MODELS_FILENAME as n, normalizeRoleName as o, ROLE_MANIFEST as r, INHERIT_PARENT_ALIASES as t };

package/dist/role-manifest-8OERX9-s.d.mts

@@ -0,0 +1,90 @@
+/**
+ * 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;
+}
+/** The 17 roles, in manifest order. */
+declare const ROLE_MANIFEST: readonly [{
+  readonly key: "feature, refactoring";
+  readonly shape: "single";
+  readonly autoPanel: false;
+}, {
+  readonly key: "bug-fix";
+  readonly shape: "single";
+  readonly autoPanel: false;
+}, {
+  readonly key: "perf-issue";
+  readonly shape: "single";
+  readonly autoPanel: false;
+}, {
+  readonly key: "hillclimb";
+  readonly shape: "single";
+  readonly autoPanel: false;
+}, {
+  readonly key: "judgment and prose";
+  readonly shape: "single";
+  readonly autoPanel: false;
+}, {
+  readonly key: "hardest tasks";
+  readonly shape: "single";
+  readonly autoPanel: false;
+}, {
+  readonly key: "how explorer";
+  readonly shape: "single";
+  readonly autoPanel: false;
+}, {
+  readonly key: "how explainer";
+  readonly shape: "single";
+  readonly autoPanel: false;
+}, {
+  readonly key: "why investigators";
+  readonly shape: "single";
+  readonly autoPanel: false;
+}, {
+  readonly key: "why synthesizer";
+  readonly shape: "single";
+  readonly autoPanel: false;
+}, {
+  readonly key: "reflect tooling";
+  readonly shape: "single";
+  readonly autoPanel: false;
+}, {
+  readonly key: "reflect judgment, divergent, synthesizer";
+  readonly shape: "single";
+  readonly autoPanel: false;
+}, {
+  readonly key: "arena runners";
+  readonly shape: "list";
+  readonly autoPanel: true;
+}, {
+  readonly key: "arena cross-judge pool";
+  readonly shape: "list";
+  readonly autoPanel: false;
+}, {
+  readonly key: "swarm workers";
+  readonly shape: "list";
+  readonly autoPanel: false;
+}, {
+  readonly key: "architect runners";
+  readonly shape: "list";
+  readonly autoPanel: true;
+}, {
+  readonly key: "interrogate reviewers";
+  readonly shape: "list";
+  readonly autoPanel: true;
+}];
+type RoleKey = (typeof ROLE_MANIFEST)[number]["key"];
+export { RoleSpec as n, RoleValueShape as r, RoleKey as t };

package/dist/{role-wire-DZwTn2wF.d.mts → role-wire-CAJsVA6e.d.mts}

@@ -1,5 +1,4 @@
-import "./models.mjs";
-import { n as RoleValueShape } from "./role-manifest-C3fUzjLI.mjs";
+import { r as RoleValueShape, t as RoleKey } from "./role-manifest-8OERX9-s.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. */
@@ -14,7 +13,7 @@ type RouteView = {
 };
 /** One of the 17 roles in manifest order. */
 interface RoleView {
-  readonly key: string;
+  readonly key: RoleKey;
   readonly shape: RoleValueShape;
   /** Whether the role file configures this role. */
   readonly configured: boolean;

package/dist/roles.d.mts

@@ -1,5 +1,5 @@
 import { CatalogueResult } from "./models.mjs";
-import { n as SaveRoleRequest, r as SaveRoleResult, t as RoleFileSnapshot } from "./role-wire-DZwTn2wF.mjs";
+import { n as SaveRoleRequest, r as SaveRoleResult, t as RoleFileSnapshot } from "./role-wire-CAJsVA6e.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. */

package/dist/roles.mjs

@@ -1,6 +1,7 @@
 import { collectCatalogue } from "./models.mjs";
+import { i as findRoleSpec, o as normalizeRoleName, r as ROLE_MANIFEST, t as INHERIT_PARENT_ALIASES } from "./role-manifest-79cnFfDM.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 { i as resolveDshHome, n as readRoleConfiguration, o as updateRoleDocument, t as modelsFilePath } from "./role-config-a4JpVdc-.mjs";
 import { dirname } from "node:path";
 import { mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
 import { Service } from "@deepseek-ai/cordis";
@@ -178,40 +179,9 @@ function validateSaveRequest(request, catalogue) {
 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.
-*/
+/** Update the winning role through the same line grammar used by the parser. */
 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`;
+	return updateRoleDocument(text, spec, value);
 }
 function writeAtomically(path, text) {
 	mkdirSync(dirname(path), { recursive: true });

package/dist/script.mjs

@@ -1,4 +1,4 @@
-import { i as PORT_ROOT } from "./paths-BT77khwm.mjs";
+import { i as PORT_ROOT } from "./paths-yji9SNak.mjs";
 import { isAbsolute, join, resolve } from "node:path";
 import { spawn } from "node:child_process";
 // src/internal/script-registry.ts

package/dist/subagent.d.mts

@@ -1,5 +1,5 @@
 import { _ as ToolsHost, g as ToolDefinition, h as SubagentsHost, m as SubagentCapabilities, n as AgentOptions, r as AgentsHost, s as LlmHost, t as Agent, v as WorkingDirectoryHost } from "./host-contract-CUPSpeNk.mjs";
-import { t as RoleSpec } from "./role-manifest-C3fUzjLI.mjs";
+import { n as RoleSpec } from "./role-manifest-8OERX9-s.mjs";
 /** One resolved child route. */
 type Route = {
   readonly kind: "inherit";
@@ -43,6 +43,13 @@ export interface PstackSubagentConfig {
   readonly provider: string;
   readonly maxDepth?: number;
 }
+/**
+ * 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.
+ */
+export declare const DEFAULT_CHILD_MAX_DEPTH = 1;
 /** What a call asked for, after every required argument has been validated. */
 export interface DelegationArgs {
   readonly description: string;
@@ -50,7 +57,7 @@ export interface DelegationArgs {
   readonly agent: AgentKind;
   readonly role: string | null;
   readonly cwd: string | null;
-  readonly maxDepth: number;
+  readonly maxDepth: number | null;
   readonly roleIndex: number | null;
   readonly reasoningEffort: string | null;
 }
@@ -107,6 +114,13 @@ export declare function composeChildPrompt(input: {
   }[];
   readonly task: string;
 }): string;
+export declare const DELEGATION_ARGUMENT_KEYS: readonly ["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.
+ */
+export declare const REQUIRED_DELEGATION_ARGUMENT_KEYS: readonly ["description", "prompt", "agent", "role", "roleIndex", "reasoningEffort", "cwd"];
 /** Validate every required model-facing argument. Null declines an optional setting. */
 export declare function parseDelegationArgs(raw: unknown): DelegationArgs;
 /** One planned child, before any Host call. */
@@ -140,7 +154,15 @@ export interface DelegationPlan {
 /** Route text as reported to the model. */
 export declare function routeLabel(route: Route, effortOverride?: string): string;
 /** Take the smallest of the requested depth, this row's cap, and the Host setting. */
-export declare function resolveDelegationDepth(configured: number | undefined, requested: number | undefined, hostLimit: number | undefined): number | undefined;
+export declare function resolveDelegationDepth(configured: number | undefined, requested: number | null | undefined, hostLimit: number | undefined): number | undefined;
+/**
+ * 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.
+ */
+export declare function requestedChildDepth(requested: number | null, diagnostics: string[]): number;
 /** Resolve the role file, routes, prompt, and depth into one plan. Pure of service calls. */
 export declare function planDelegation(args: DelegationArgs, runtime: SubagentRuntime, config?: PstackSubagentConfig): DelegationPlan;
 /** Check the backend can enforce what this call asks for. */