dsh-pstack 0.1.0 → 0.2.0-beta.3

package/dist/subagent.d.mts

@@ -1,130 +1,199 @@
-import { ContentBlock, ReasoningEffortId } from "@deepseek-ai/dsh-llm";
-import { Context } from "@deepseek-ai/cordis";
-import { Agent } from "@deepseek-ai/dsh-agent";
-//#region src/roles.d.ts
+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";
 /**
- * pstack role resolution.
+ * The one pstack role manifest.
  *
- * `~/.dsh/pstack-models.md` holds one role per line. The tool resolves a role
- * into a child LLM route at call time, so edits apply to the next delegation
- * without restarting the harness.
+ * 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.
  *
- * Parsing never throws. A typo in one line must not break delegation, but it
- * must also not disappear: `parseModelConfigWithIssues` collects `issues` and
- * the parser keeps them so a caller can report the line that is wrong.
+ * This module has no Node imports: the bundle imports it directly.
  */
-interface Route {
+/** 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;
+}
+/** One resolved child route. */
+type Route = {
+  readonly kind: "inherit";
+} | {
+  readonly kind: "route";
   readonly provider: string;
   readonly model: string;
-  readonly reasoningEffort?: string;
+  readonly effort?: string;
+};
+/** How one role's value expands into children. */
+type RouteSelectionMode = "single" | "panel" | "selected";
+interface RouteSelection {
+  readonly role: RoleSpec;
+  readonly mode: RouteSelectionMode;
+  /** Whether the role came from the file or the inherit-parent fallback. */
+  readonly configured: boolean;
+  readonly routes: readonly Route[];
+  /** How many entries the role holds, before selection. */
+  readonly total: number;
+  readonly roleIndex?: number;
 }
-//#endregion
-//#region src/subagent.d.ts
+/** Cordis row name, used by Loader diagnostics. */
 export declare const name = "pstack-subagent";
+/**
+ * Delegation needs the tool registry, the subagent registry, the LLM adapters, and the
+ * session directory. `agents` is not here: it is optional and read per call, so a
+ * profile without it still delegates and the child simply keeps its starting effort.
+ */
 export declare const inject: string[];
-declare const AGENT_KINDS: readonly ["poteto-agent", "comment-sicko", "general"];
+/** Model-facing tool name. */
+export declare const TOOL_NAME = "pstack_subagent";
+/** Backend used when the row does not name one. */
+export declare const DEFAULT_SUBAGENT_PROVIDER = "spawn";
+/** The child kinds this tool knows how to brief. */
+export declare const AGENT_KINDS: readonly ["poteto-agent", "comment-sicko", "general"];
 export type AgentKind = (typeof AGENT_KINDS)[number];
-export interface Config {
-  /** Tool name exposed to the model. */
-  readonly toolName?: string;
-  /** Subagent provider registered on `ctx.subagents`. */
-  readonly provider?: string;
-  /** Default agent kind when the model omits `agent`. */
-  readonly defaultAgent?: AgentKind;
+/** Row configuration. */
+export interface PstackSubagentConfig {
+  readonly provider: string;
+  readonly maxDepth?: number;
 }
-export declare function stripFrontmatter(source: string): string;
-export declare function readAgentInstructions(kind: AgentKind): Promise<string>;
-/**
- * Build the child prompt. A pstack delegate must read `poteto-mode` first, and
- * the parent normally passes its absolute path. When the parent omits it, this
- * fallback keeps the delegate from drifting into general-purpose style.
- */
-export declare function composePrompt(input: {
-  readonly kind: AgentKind;
+/** What a call asked for, after every required argument has been validated. */
+export interface DelegationArgs {
   readonly description: string;
   readonly prompt: string;
-  readonly agentInstructions: string;
-  readonly potetoModePath?: string;
-}): string;
-export interface RoleResolution {
-  readonly route: Route | undefined;
-  /** Human-readable notes to append to the tool reply: issues, near misses. */
-  readonly notes: readonly string[];
+  readonly agent: AgentKind;
+  readonly role: string | null;
+  readonly cwd: string | null;
+  readonly maxDepth: number;
+  readonly roleIndex: number | null;
+  readonly reasoningEffort: string | null;
+}
+/** One child this call started. */
+export interface ChildRecord {
+  readonly childId: string;
+  readonly label: string;
+  readonly agent: string;
+  readonly role: string;
+  readonly route: string;
+  readonly effort?: string;
+  readonly maxDepth?: number;
+}
+export interface DelegationResult {
+  readonly kind: "activation" | "activations";
+  readonly children: readonly ChildRecord[];
+  readonly diagnostics: readonly string[];
+}
+/** Raised for a configuration or argument problem, before any child starts. */
+export declare class DelegationError extends Error {
+  constructor(message: string);
+}
+/** Raised when a child starts but a later entry in the same call fails. */
+export declare class PartialDelegationError extends DelegationError {
+  readonly startedChildren: readonly ChildRecord[];
+  constructor(message: string, startedChildren: readonly ChildRecord[]);
+}
+/** The live services and locations one delegation reads. */
+export interface SubagentRuntime {
+  readonly subagents: SubagentsHost;
+  readonly llm: LlmHost;
+  /** Optional: absent means the child keeps the effort it was started with. */
+  readonly agents?: AgentsHost;
+  readonly workingDirectory: WorkingDirectoryHost;
+  readonly dshHome: string;
 }
 /**
- * Resolve the `role` argument against the shipped role table, explaining a miss
- * instead of swallowing it.
+ * Validate the row configuration without a Schemastery dependency.
  *
- * A missing file is normal. A configured-but-unmatched role is not: it means a
- * skill and `~/.dsh/pstack-models.md` disagree, and the child would silently run
- * on the parent route. The tool reply says so, so the parent can fix the file or
- * report the miss rather than believing the route applied.
+ * A typo must fail at activation rather than at the first delegation, and an omitted
+ * `config` must be valid. Cordis passes the raw mapping because this row exports no
+ * `Config` object; callers that object as `config` are still checked here.
  */
-export declare function resolveRoleArg(role: string | undefined): Promise<RoleResolution>;
-export interface PstackToolDeps {
-  readonly start: (input: {
-    readonly parent: Agent;
+export declare function normalizeConfig(value: unknown): PstackSubagentConfig;
+/** The preset id behind each pstack agent kind. `general` joins the parent preset. */
+export declare const AGENT_PRESETS: Readonly<Record<Exclude<AgentKind, "general">, string>>;
+/** The preset a child of this kind must mount, or undefined to join the parent preset. */
+export declare function agentPresetFor(agent: AgentKind): string | undefined;
+/** Compose the self-contained prompt one child receives. */
+export declare function composeChildPrompt(input: {
+  readonly injectedPaths?: readonly {
     readonly label: string;
-    readonly prompt: ContentBlock[];
-    readonly signal: AbortSignal;
-    readonly route: Route | undefined;
-    readonly cwd: string | undefined;
-  }) => Promise<{
-    readonly childId: string;
-  }>;
-  readonly loadAgent: (kind: AgentKind) => Promise<string>;
-  /**
-   * Resolve the `role` argument. The notes explain a miss so the reply can name
-   * it; an empty list means the route applied as written, or there was no role.
-   */
-  readonly loadRole: (role: string | undefined) => Promise<RoleResolution>;
-  readonly potetoModePath?: string;
-  readonly defaultAgent?: AgentKind;
-  readonly toolName?: string;
+    readonly path: string;
+  }[];
+  readonly task: string;
+}): string;
+/** 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. */
+export interface ChildPlan {
+  readonly index: number;
+  readonly total: number;
+  readonly label: string;
+  readonly agent: AgentKind;
+  readonly role: string;
+  readonly route: Route;
+  readonly routeLabel: string;
+  readonly effort?: string;
+  readonly agentOptions?: AgentOptions;
+  /** Preset id that supplies this child's persona and tool composition. */
+  readonly agentPreset?: string;
+  readonly cwd?: string;
+  readonly maxDepth?: number;
 }
+export interface DelegationPlan {
+  readonly agent: AgentKind;
+  readonly prompt: string;
+  readonly provider: string;
+  readonly role: string;
+  readonly mode: RouteSelection["mode"];
+  readonly roleIndex?: number;
+  readonly roleTotal: number;
+  readonly reasoningEffort?: string;
+  readonly children: readonly ChildPlan[];
+  readonly diagnostics: readonly string[];
+}
+/** 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;
+/** 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. */
+export declare function assertProviderCapabilities(capabilities: SubagentCapabilities, providerName: string, asks: {
+  readonly agentOptions: boolean;
+  readonly agentPreset: boolean;
+  readonly maxDepth: boolean;
+}): void;
 /**
- * Turn a resolved role into the `agentOptions` a child activation carries.
- *
- * This is the only place a `Route` becomes a provider request. Keeping it a
- * pure function lets a test assert the exact options without starting a child,
- * which is where a role-to-route bug would otherwise stay invisible until a
- * live delegation picked the wrong model.
- */
-export declare function routeToAgentOptions(route: Route | undefined): {
-  provider: string;
-  model: string;
-  reasoningEffort?: ReasoningEffortId;
-} | undefined;
-/** Tool definition over injected dependencies; `apply` supplies the runtime. */
-export declare function createPstackTool(deps: PstackToolDeps): import("@deepseek-ai/dsh-tools").ToolDefinition;
-/**
- * Build the provider-facing activation request for one child.
+ * Resolve and validate one child's `cwd`.
  *
- * A role is resolved once, at delegation time, into concrete provider options.
- * The child inherits the parent route when the role is absent or resolves to
- * `inherit-parent`, which is why the field is omitted rather than set to a
- * placeholder.
+ * A child may run inside the session directory or inside an explicitly separate Git
+ * worktree. Anything else is refused: this tool does not create isolation, so it will
+ * not promise one.
  */
-export declare function buildActivationRequest(input: {
-  readonly parent: Agent;
-  readonly prompt: ContentBlock[];
-  readonly route: Route | undefined;
-  readonly cwd: string | undefined;
-}): {
-  parent: Agent;
-  prompt: ContentBlock[];
-  cwd?: string;
-  agentOptions?: {
-    provider: string;
-    model: string;
-    reasoningEffort?: ReasoningEffortId;
-  };
-};
+export declare function resolveChildCwd(requested: string | undefined, sessionRoot: string): string | undefined;
 /**
- * Mount the tool. `ctx.subagents` owns child lifecycle; this row only supplies
- * the pstack-specific shape (agent preambles and role routes) on top.
+ * Start the planned children. Everything rejectable has already been rejected; a
+ * failure at entry N keeps children 1..N-1 running and reports their ids.
  */
-export declare function apply(ctx: Context, config?: Config): void;
-//#endregion
-export {};
-//# sourceMappingURL=subagent.d.mts.map
+export declare function startPlannedChildren(parent: Agent, plan: DelegationPlan, runtime: SubagentRuntime, config: PstackSubagentConfig, signal: AbortSignal): Promise<DelegationResult>;
+/** Full delegation: plan, validate, start. */
+export declare function delegate(parent: Agent, args: DelegationArgs, runtime: SubagentRuntime, config?: PstackSubagentConfig, signal?: AbortSignal): Promise<DelegationResult>;
+/** Render one delegation result for the model. */
+export declare function renderDelegationResult(result: DelegationResult): string;
+/** Build the model-facing tool for one row. */
+export declare function createPstackSubagentTool(runtime: SubagentRuntime, config?: PstackSubagentConfig): ToolDefinition;
+/** The slices of the Cordis context this row uses. */
+export interface PstackSubagentHost {
+  readonly tools: ToolsHost;
+  readonly subagents: SubagentsHost;
+  readonly llm: LlmHost;
+  readonly workingDirectory: WorkingDirectoryHost;
+}
+/** Build the runtime a real Host call reads. */
+export declare function hostRuntime(ctx: PstackSubagentHost, getAgentRegistry?: () => AgentsHost | undefined): SubagentRuntime;
+/** Register `pstack_subagent` for this row. */
+export declare function apply(ctx: PstackSubagentHost & {
+  get?: (name: string) => AgentsHost | undefined;
+}, config?: unknown): void;
+export {};