@ian-pascoe/pi-minimal-subagents 0.1.1 → 0.2.0

package/README.md

@@ -130,11 +130,64 @@ children: `subagent`, `agent_message`, `subagent_wait`, `subagent_status`,
 only the three adjacent-coordination tools: `agent_message`, `subagent_wait`,
 and `subagent_status`.
 
-Deleting a child first uses the optional `trash` command when available and
-falls back to unlinking its session file. Each Child Agent has a persistent
-JSONL session. Append-only Root Agent Registry entries retain hierarchy and
-Delivery Evidence across reloads. Forking cancels and drains active work, then
-clones child session leaves so the fork receives an independent hierarchy.
+The `subagent` `tools` argument distinguishes capability presets from exact
+lists: `"read"` grants `read`, `grep`, `find`, and `ls`; `"modify"` adds
+`bash`, `edit`, and `write`; an array such as `["read"]` grants exactly the
+named ordinary tool and does not expand a preset. Coordinator tools are
+injected separately according to delegation and must not appear in `tools`;
+misuse returns an actionable error. Use the string preset when a child needs
+the complete read-only discovery bundle.
+
+`agent_message` reports whether a message was delivered through an active
+parent wait, queued for the recipient, or failed. `subagent_wait` can return an
+intermediate Wait Event containing a Coordination Message before the child turn
+settles; call it again for the terminal turn result. Pass optional `turn_id` to
+address an older retained turn exactly. Without it, waits select the oldest
+observable claimed or pending turn before the active/latest turn. A caller may
+have only one outstanding wait for the same source turn; a concurrent duplicate
+is rejected instead of competing for one Wait Event.
+
+The persisted Delivery Ledger records Coordination Messages, terminal results,
+globally increasing sequence, and wait ownership before delivery. Existing
+items retain their sequence; gaps from skipped malformed records are valid.
+Claims can name only active, latest, or retained turns. Once a wait returns an
+intermediate message, that wait path owns the rest of the source turn across
+reloads, forks, and newer turns. Automatic fallback retains its ordered queue
+reservation, treats idle notifications as advisory, and rechecks actual
+recipient idleness before injecting a message. Destination-session Delivery
+Evidence settles and compacts ledger items, preventing duplicate delivery and
+unbounded checkpoint growth. The pure Delivery Ledger state machine retains at
+most 20 pending wait-only terminal results per source agent; Coordination
+Messages are not removed by that terminal-retention limit. Delivered messages
+include stable delivery, source-agent, and source-turn identities in persisted
+details.
+
+Deleting a child first verifies its session header and persistent identity,
+then uses the optional `trash` command when available and falls back to
+unlinking its session file. Deletion prunes pending delivery state and retained
+recent-message projections sourced from the complete deleted subtree. Restore
+and clone perform the same ownership check and reopen the recorded child-session
+leaf.
+
+Registry replay and Delivery Evidence are scoped to the Root Agent's active
+session-tree branch. Registry writes use V2 records with complete field,
+identity, sequence, hierarchy, adjacency, destination, ordinary-tool ceiling,
+and coordinator-tool exclusion validation. Every available V2 agent has a
+selected leaf; only unavailable recovery placeholders may omit it. Valid V1
+records and checkpoints migrate during replay; invalid owned records are
+skipped with semantic diagnostic codes rather than disabling the extension.
+Persisted message activity carries an explicit `recorded_at` from the
+coordinator clock.
+
+`/tree` abandons old process-local work and restores the selected branch. Fork
+preparation is read-only; only confirmed fork shutdown interrupts work and
+clones the selected branch, so another extension can cancel a fork without
+freezing coordinator tools. Each clone records a new generation-specific
+identity/provenance pair, and the destination appends ownership for that clone's
+current session ID rather than reusing inherited ownership. If a
+process-local fork handoff is lost, recovery reads only the destination's
+selected branch and proceeds only when its canonical `parentSession` proves the
+source file; it never substitutes the source session's newer head.
 
 ## Status and TUI
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ian-pascoe/pi-minimal-subagents",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "private": false,
   "description": "Persistent nested subagents with bounded delegation for Pi",
   "keywords": [

package/src/minimal-subagents-capabilities.ts

@@ -73,6 +73,13 @@ export function resolveOrdinaryToolSelection(
             ? MODIFY_TOOL_BUNDLE
             : selection;
   const uniqueRequested = [...new Set(requested)];
+  const coordinatorTools = new Set<string>(COORDINATOR_TOOL_NAMES);
+  const requestedCoordinatorTools = uniqueRequested.filter((name) => coordinatorTools.has(name));
+  if (requestedCoordinatorTools.length > 0) {
+    throw new Error(
+      `Minimal subagents ordinary tool selection: coordinator tools are injected separately and must not appear in tools: ${requestedCoordinatorTools.join(", ")}`,
+    );
+  }
   const available = new Set(context.availableTools);
   const ceiling = new Set(context.capabilityCeiling);
   const missing = uniqueRequested.filter((name) => !available.has(name));

package/src/minimal-subagents-config.ts

@@ -1,8 +1,34 @@
+import type { JsonValue } from "@earendil-works/pi-ai";
+import type { SettingsManager } from "@earendil-works/pi-coding-agent";
+import { type Static, Type } from "typebox";
+import { Value } from "typebox/value";
 import { DEFAULT_MAX_SUBAGENT_DEPTH, THINKING_LEVELS } from "./minimal-subagents-capabilities.js";
 
 const MODEL_ROLE_NAME_MAX_LENGTH = 64;
 const MODEL_ROLE_HINT_MAX_LENGTH = 500;
 
+const JsonValueSchema = Type.Unsafe<JsonValue>({});
+const SettingsDocumentSchema = Type.Object({
+  minimalSubagents: Type.Optional(JsonValueSchema),
+});
+const MinimalSubagentsSettingsSchema = Type.Object({
+  maxSubagentDepth: Type.Optional(JsonValueSchema),
+  modelRoles: Type.Optional(JsonValueSchema),
+});
+const JsonObjectSchema = Type.Record(Type.String(), JsonValueSchema);
+const PositiveSafeIntegerSchema = Type.Integer({ minimum: 1, maximum: Number.MAX_SAFE_INTEGER });
+const MaxSubagentDepthSettingSchema = Type.Union([PositiveSafeIntegerSchema, Type.Null()]);
+const ShorthandModelRoleSchema = Type.String();
+const ExpandedModelRoleSchema = Type.Object(
+  {
+    model: Type.String(),
+    hint: Type.Optional(Type.String()),
+  },
+  { additionalProperties: false },
+);
+const ModelRoleEntriesSchema = Type.Record(Type.String(), JsonValueSchema);
+const ModelRolesSettingSchema = Type.Union([ModelRoleEntriesSchema, Type.Null()]);
+
 type ModelRoleThinkingLevel = (typeof THINKING_LEVELS)[number];
 
 /** Describes one user-authored advisory model role shown to subagent callers. */
@@ -20,71 +46,153 @@ export interface ResolvedMinimalSubagentsConfig {
   warnings: string[];
 }
 
+interface MinimalSubagentsSettingsDocument {
+  minimalSubagents?: JsonValue;
+}
+
 interface MinimalSubagentsConfigInput {
-  globalSettings: unknown;
-  projectSettings: unknown;
+  globalSettings: MinimalSubagentsSettingsDocument;
+  projectSettings: MinimalSubagentsSettingsDocument;
   eligibleModelIds: readonly string[];
 }
 
+type PiSettingsDocument = ReturnType<SettingsManager["getGlobalSettings"]>;
+type MinimalSubagentsSettingsDocumentInput = PiSettingsDocument | MinimalSubagentsSettingsDocument;
+
 interface MinimalSubagentsSettingsReader {
-  getGlobalSettings(): unknown;
-  getProjectSettings(): unknown;
+  getGlobalSettings(): MinimalSubagentsSettingsDocumentInput;
+  getProjectSettings(): MinimalSubagentsSettingsDocumentInput;
 }
 
 type SettingsScope = "global" | "project";
 
 interface ScopedSettingValue {
   scope: SettingsScope;
-  value: unknown;
+  value: ModelRoleWireValue;
 }
 
-function isRecord(value: unknown): value is Record<string, unknown> {
-  return typeof value === "object" && value !== null && !Array.isArray(value);
+interface ParsedMinimalSubagentsSettings {
+  maxSubagentDepth?: MaxSubagentDepthWireValue;
+  modelRoles?: ModelRolesWireValue;
+}
+
+type MaxSubagentDepthWireValue =
+  | { kind: "depth"; value: number }
+  | { kind: "reset" }
+  | { kind: "invalid" };
+
+type ModelRoleWireValue =
+  | { kind: "delete" }
+  | { kind: "shorthand"; model: string }
+  | { kind: "expanded"; fields: Static<typeof ExpandedModelRoleSchema> }
+  | { kind: "malformed-expanded"; fields: Record<string, JsonValue> }
+  | { kind: "invalid" };
+
+type ModelRolesWireValue =
+  | { kind: "reset" }
+  | { kind: "entries"; entries: ReadonlyMap<string, ModelRoleWireValue> }
+  | { kind: "invalid" };
+
+function parseMaxSubagentDepthWireValue(value: JsonValue): MaxSubagentDepthWireValue {
+  if (!Value.Check(MaxSubagentDepthSettingSchema, value)) return { kind: "invalid" };
+  return value === null ? { kind: "reset" } : { kind: "depth", value };
+}
+
+function parseModelRoleWireValue(value: JsonValue): ModelRoleWireValue {
+  if (value === null) return { kind: "delete" };
+  if (Value.Check(ShorthandModelRoleSchema, value)) return { kind: "shorthand", model: value };
+  if (Value.Check(JsonObjectSchema, value)) {
+    return Value.Check(ExpandedModelRoleSchema, value)
+      ? { kind: "expanded", fields: value }
+      : { kind: "malformed-expanded", fields: value };
+  }
+  return { kind: "invalid" };
+}
+
+function isExpandedModelRoleWireValue(
+  value: ModelRoleWireValue,
+): value is Extract<ModelRoleWireValue, { kind: "expanded" | "malformed-expanded" }> {
+  return value.kind === "expanded" || value.kind === "malformed-expanded";
+}
+
+function parseModelRolesWireValue(value: JsonValue): ModelRolesWireValue {
+  if (!Value.Check(ModelRolesSettingSchema, value)) return { kind: "invalid" };
+  if (value === null) return { kind: "reset" };
+  return {
+    kind: "entries",
+    entries: new Map(
+      Object.entries(value).map(([name, roleValue]) => [name, parseModelRoleWireValue(roleValue)]),
+    ),
+  };
+}
+
+function parsePiSettingsDocument(
+  settings: MinimalSubagentsSettingsDocumentInput,
+): MinimalSubagentsSettingsDocument {
+  if (!Value.Check(SettingsDocumentSchema, settings)) return {};
+  const parsed: MinimalSubagentsSettingsDocument = {};
+  if (settings.minimalSubagents !== undefined) {
+    parsed.minimalSubagents = settings.minimalSubagents;
+  }
+  return parsed;
 }
 
 function readMinimalSubagentsSettings(
-  settings: unknown,
+  settings: MinimalSubagentsSettingsDocument,
   scope: SettingsScope,
   warnings: string[],
-): Record<string, unknown> {
-  if (!isRecord(settings) || settings.minimalSubagents === undefined) return {};
-  if (isRecord(settings.minimalSubagents)) return settings.minimalSubagents;
+): ParsedMinimalSubagentsSettings {
+  if (!Value.Check(SettingsDocumentSchema, settings)) return {};
+  const minimalSubagents = settings.minimalSubagents;
+  if (minimalSubagents === undefined) return {};
+  if (Value.Check(MinimalSubagentsSettingsSchema, minimalSubagents)) {
+    const parsed: ParsedMinimalSubagentsSettings = {};
+    if (minimalSubagents.maxSubagentDepth !== undefined) {
+      parsed.maxSubagentDepth = parseMaxSubagentDepthWireValue(minimalSubagents.maxSubagentDepth);
+    }
+    if (minimalSubagents.modelRoles !== undefined) {
+      parsed.modelRoles = parseModelRolesWireValue(minimalSubagents.modelRoles);
+    }
+    return parsed;
+  }
   warnings.push(`${scope} minimalSubagents: expected an object`);
   return {};
 }
 
 function mergeModelRoleEntries(
-  globalValue: unknown,
-  projectValue: unknown,
+  globalValue: ModelRolesWireValue | undefined,
+  projectValue: ModelRolesWireValue | undefined,
   warnings: string[],
 ): Map<string, ScopedSettingValue> {
   const entries = new Map<string, ScopedSettingValue>();
-  if (globalValue !== undefined) {
-    if (isRecord(globalValue)) {
-      for (const [name, value] of Object.entries(globalValue)) {
-        entries.set(name, { scope: "global", value });
-      }
-    } else if (globalValue !== null) {
-      warnings.push("global minimalSubagents.modelRoles: expected an object or null");
+  if (globalValue?.kind === "entries") {
+    for (const [name, value] of globalValue.entries) {
+      entries.set(name, { scope: "global", value });
     }
+  } else if (globalValue?.kind === "invalid") {
+    warnings.push("global minimalSubagents.modelRoles: expected an object or null");
   }
-  if (projectValue === null) return new Map();
+  if (projectValue?.kind === "reset") return new Map();
   if (projectValue === undefined) return entries;
-  if (!isRecord(projectValue)) {
+  if (projectValue.kind === "invalid") {
     warnings.push("project minimalSubagents.modelRoles: expected an object or null");
     return entries;
   }
+  if (projectValue.kind !== "entries") return entries;
 
-  for (const [name, value] of Object.entries(projectValue)) {
-    if (value === null) {
+  for (const [name, value] of projectValue.entries) {
+    if (value.kind === "delete") {
       entries.delete(name);
       continue;
     }
     const inherited = entries.get(name)?.value;
-    entries.set(name, {
-      scope: "project",
-      value: isRecord(inherited) && isRecord(value) ? { ...inherited, ...value } : value,
-    });
+    const mergedValue =
+      inherited !== undefined &&
+      isExpandedModelRoleWireValue(inherited) &&
+      isExpandedModelRoleWireValue(value)
+        ? parseModelRoleWireValue({ ...inherited.fields, ...value.fields })
+        : value;
+    entries.set(name, { scope: "project", value: mergedValue });
   }
   return entries;
 }
@@ -142,69 +250,78 @@ function parseModelRoles(
     }
 
     const value = entry.value;
-    if (isRecord(value)) {
-      const unknownFields = Object.keys(value).filter((key) => key !== "model" && key !== "hint");
-      if (unknownFields.length > 0) {
-        warnings.push(`${path}: unknown field: ${unknownFields.join(", ")}`);
+    const expandedRoleObject = isExpandedModelRoleWireValue(value) ? value.fields : undefined;
+    if (expandedRoleObject !== undefined) {
+      const invalidFields = Object.keys(expandedRoleObject).filter(
+        (key) => key !== "model" && key !== "hint",
+      );
+      if (invalidFields.length > 0) {
+        warnings.push(`${path}: unknown field: ${invalidFields.join(", ")}`);
         continue;
       }
-    } else if (typeof value !== "string") {
+    } else if (value.kind !== "shorthand") {
       warnings.push(`${path}: expected a model string or expanded role object`);
       continue;
     }
 
-    const model = typeof value === "string" ? value : value.model;
-    if (typeof model !== "string" || model.length === 0 || model !== model.trim()) {
+    const modelValue =
+      expandedRoleObject === undefined && value.kind === "shorthand"
+        ? value.model
+        : expandedRoleObject?.model;
+    if (
+      !Value.Check(ShorthandModelRoleSchema, modelValue) ||
+      modelValue.length === 0 ||
+      modelValue !== modelValue.trim()
+    ) {
       warnings.push(`${path}: model must be a non-empty trimmed string`);
       continue;
     }
-    const resolvedModel = resolveModelRoleReference(model, eligibleModels, path, warnings);
+    const resolvedModel = resolveModelRoleReference(modelValue, eligibleModels, path, warnings);
     if (resolvedModel === undefined) continue;
 
-    const hint = isRecord(value) ? value.hint : undefined;
+    const hintValue = expandedRoleObject?.hint;
     if (
-      hint !== undefined &&
-      (typeof hint !== "string" ||
-        hint.length === 0 ||
-        hint !== hint.trim() ||
-        /[\r\n]/.test(hint) ||
-        hint.length > MODEL_ROLE_HINT_MAX_LENGTH)
+      hintValue !== undefined &&
+      (!Value.Check(ShorthandModelRoleSchema, hintValue) ||
+        hintValue.length === 0 ||
+        hintValue !== hintValue.trim() ||
+        /[\r\n]/.test(hintValue) ||
+        hintValue.length > MODEL_ROLE_HINT_MAX_LENGTH)
     ) {
       warnings.push(`${path}.hint: expected trimmed single-line text up to 500 characters`);
       continue;
     }
-    roles.push({
+    const role: MinimalSubagentsModelRole = {
       name,
       model: resolvedModel.model,
-      ...(resolvedModel.thinkingLevel === undefined
-        ? {}
-        : { thinkingLevel: resolvedModel.thinkingLevel }),
-      ...(hint === undefined ? {} : { hint }),
-    });
+    };
+    if (resolvedModel.thinkingLevel !== undefined) {
+      role.thinkingLevel = resolvedModel.thinkingLevel;
+    }
+    if (hintValue !== undefined && Value.Check(ShorthandModelRoleSchema, hintValue)) {
+      role.hint = hintValue;
+    }
+    roles.push(role);
   }
   return roles;
 }
 
 function resolveMaxSubagentDepth(
-  globalValue: unknown,
-  projectValue: unknown,
+  globalValue: MaxSubagentDepthWireValue | undefined,
+  projectValue: MaxSubagentDepthWireValue | undefined,
   warnings: string[],
 ): number {
   let resolvedDepth = DEFAULT_MAX_SUBAGENT_DEPTH;
-  if (globalValue !== undefined && globalValue !== null) {
-    if (Number.isSafeInteger(globalValue) && Number(globalValue) > 0) {
-      resolvedDepth = Number(globalValue);
-    } else {
-      warnings.push(
-        "global minimalSubagents.maxSubagentDepth: expected a positive safe integer or null",
-      );
-    }
+  if (globalValue?.kind === "depth") {
+    resolvedDepth = globalValue.value;
+  } else if (globalValue?.kind === "invalid") {
+    warnings.push(
+      "global minimalSubagents.maxSubagentDepth: expected a positive safe integer or null",
+    );
   }
   if (projectValue === undefined) return resolvedDepth;
-  if (projectValue === null) return DEFAULT_MAX_SUBAGENT_DEPTH;
-  if (Number.isSafeInteger(projectValue) && Number(projectValue) > 0) {
-    return Number(projectValue);
-  }
+  if (projectValue.kind === "reset") return DEFAULT_MAX_SUBAGENT_DEPTH;
+  if (projectValue.kind === "depth") return projectValue.value;
   warnings.push(
     "project minimalSubagents.maxSubagentDepth: expected a positive safe integer or null",
   );
@@ -242,8 +359,8 @@ export function resolveMinimalSubagentsSettings(
   eligibleModelIds: readonly string[],
 ): ResolvedMinimalSubagentsConfig {
   return resolveMinimalSubagentsConfig({
-    globalSettings: settings.getGlobalSettings(),
-    projectSettings: settings.getProjectSettings(),
+    globalSettings: parsePiSettingsDocument(settings.getGlobalSettings()),
+    projectSettings: parsePiSettingsDocument(settings.getProjectSettings()),
     eligibleModelIds,
   });
 }

package/src/minimal-subagents-context.ts

@@ -11,11 +11,17 @@ export function snapshotCommittedContext(
   return structuredClone(committed);
 }
 
+/** Carries the selected caller messages and whether child preparation should compact them. */
+export interface ImportedSubagentContext {
+  messages: AgentMessage[];
+  compact: boolean;
+}
+
 /** Select the imported message snapshot and defer expensive compact preparation to the child turn. */
 export function assembleImportedContext(
   mode: SessionContextMode,
   committedMessages: AgentMessage[],
-): { messages: AgentMessage[]; compact: boolean } {
+): ImportedSubagentContext {
   if (mode === "omit") return { messages: [], compact: false };
   return { messages: committedMessages, compact: mode === "compact" };
 }