@ian-pascoe/pi-minimal-subagents 0.4.0 → 0.5.0

package/package.json

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

package/src/minimal-subagents-render-contract.ts

@@ -181,6 +181,138 @@ const DeleteDetailsSchema = Type.Object({
   ),
 });
 
+const CoordinatorTurnStatusOutputSchema = Type.Union([
+  Type.Literal("completed"),
+  Type.Literal("failed"),
+  Type.Literal("cancelled"),
+  Type.Literal("interrupted"),
+]);
+const CoordinatorTurnOutputSchema = Type.Object({
+  agent_id: Type.String(),
+  turn_id: Type.String(),
+  status: CoordinatorTurnStatusOutputSchema,
+  output: Type.String(),
+  error: Type.Optional(Type.String()),
+  usage: Type.Optional(RenderUsageSchema),
+  elapsed_ms: Type.Optional(Type.Number()),
+});
+const CoordinatorAgentSummaryOutputSchema = Type.Object({
+  agent_id: Type.String(),
+  parent_id: Type.String(),
+  state: Type.Union([Type.Literal("running"), Type.Literal("idle")]),
+  availability: Type.Union([Type.Literal("available"), Type.Literal("unavailable")]),
+  active_turn_id: Type.Optional(Type.String()),
+  latest_turn: Type.Optional(
+    Type.Object({
+      turn_id: Type.String(),
+      status: Type.Union([Type.Literal("running"), CoordinatorTurnStatusOutputSchema]),
+    }),
+  ),
+  tools: Type.Array(Type.String()),
+  elapsed_ms: Type.Optional(Type.Number()),
+  latest_activity_at: Type.Optional(Type.String()),
+  task: Type.Optional(Type.String()),
+  child_count: Type.Number(),
+  children: Type.Array(Type.Unknown()),
+  model: Type.String(),
+  thinking_level: Type.String(),
+});
+const CoordinatorAgentDetailOutputSchema = Type.Object({
+  ...CoordinatorAgentSummaryOutputSchema.properties,
+  session_file: Type.Optional(Type.String()),
+  launch_contract: Type.Object({
+    session_context: Type.String(),
+    project_context: Type.String(),
+    model: Type.String(),
+    thinking_level: Type.String(),
+    tools: Type.Optional(
+      Type.Union([
+        Type.Literal("none"),
+        Type.Literal("read"),
+        Type.Literal("modify"),
+        Type.Array(Type.String()),
+      ]),
+    ),
+    ordinary_tools: Type.Array(Type.String()),
+    delegation: Type.Optional(Type.Union([Type.Literal("none"), Type.Literal("fanout")])),
+  }),
+  capability_ceiling: Type.Array(Type.String()),
+  spawn_entry_id: Type.String(),
+  recent_messages: Type.Array(
+    Type.Object({
+      source_agent_id: Type.String(),
+      turn_id: Type.String(),
+      content: Type.String(),
+    }),
+  ),
+  recent_activity: Type.Array(RenderRecentActivitySchema),
+  latest_result: Type.Optional(CoordinatorTurnOutputSchema),
+  missing_dependencies: Type.Array(Type.String()),
+  unavailable_reason: Type.Optional(Type.String()),
+  usage: Type.Optional(RenderUsageSchema),
+});
+const CoordinatorWaitMessageOutputSchema = Type.Object({
+  event: Type.Literal("message"),
+  agent_id: Type.String(),
+  turn_id: Type.String(),
+  message_id: Type.String(),
+  delivery_id: Type.Optional(Type.String()),
+  message: Type.String(),
+});
+const CoordinatorWaitSourceOutputSchema = {
+  source_agent_id: Type.String(),
+  source_turn_id: Type.String(),
+};
+
+/** Final details schemas exposed to CodeMode for the six coordinator tools. */
+export const CoordinatorToolOutputSchemas = {
+  subagent: Type.Object({
+    agent_id: Type.String(),
+    turn_id: Type.String(),
+    status: Type.Literal("running"),
+    agent: Type.Optional(CoordinatorAgentDetailOutputSchema),
+  }),
+  agent_message: Type.Object({
+    agent_id: Type.String(),
+    message_id: Type.String(),
+    disposition: Type.Union([
+      Type.Literal("delivered-via-wait"),
+      Type.Literal("queued"),
+      Type.Literal("failed"),
+    ]),
+    error: Type.Optional(Type.String()),
+  }),
+  subagent_wait: Type.Union([
+    Type.Object({
+      ...CoordinatorWaitMessageOutputSchema.properties,
+      ...CoordinatorWaitSourceOutputSchema,
+    }),
+    Type.Object({
+      ...CoordinatorTurnOutputSchema.properties,
+      event: Type.Literal("turn"),
+      messages: Type.Optional(Type.Array(CoordinatorWaitMessageOutputSchema)),
+      ...CoordinatorWaitSourceOutputSchema,
+    }),
+    Type.Object({
+      event: Type.Literal("timeout"),
+      agent_id: Type.String(),
+      turn_id: Type.String(),
+      timeout_ms: Type.Number(),
+      agent: CoordinatorAgentDetailOutputSchema,
+      ...CoordinatorWaitSourceOutputSchema,
+    }),
+  ]),
+  subagent_status: Type.Union([
+    Type.Object({
+      parent_id: Type.String(),
+      agents: Type.Array(CoordinatorAgentSummaryOutputSchema),
+    }),
+    Type.Object({ agent: CoordinatorAgentDetailOutputSchema }),
+  ]),
+  subagent_cancel: CancelDetailsSchema,
+  subagent_delete: DeleteDetailsSchema,
+} as const;
+
 const MessageRenderDetailsSchema = Type.Union([
   CurrentMessageDetailsSchema,
   LegacyMessageDetailsSchema,

package/src/minimal-subagents-tools.ts

@@ -16,7 +16,10 @@ import {
   renderCoordinatorToolResult,
   type CoordinatorToolName,
 } from "./minimal-subagents-rendering.js";
-import type { CoordinatorToolCallInput } from "./minimal-subagents-render-contract.js";
+import {
+  CoordinatorToolOutputSchemas,
+  type CoordinatorToolCallInput,
+} from "./minimal-subagents-render-contract.js";
 import type { createCoordinatorToolSchemas } from "./minimal-subagents-tool-schemas.js";
 import type {
   AgentMessageResult,
@@ -86,6 +89,10 @@ type CoordinatorToolResultDetails =
   | DeleteResult
   | { agent_id: string; status: "waiting"; elapsed_ms: number };
 
+type CoordinatorToolDefinition = ToolDefinition & {
+  readonly outputSchema: (typeof CoordinatorToolOutputSchemas)[keyof typeof CoordinatorToolOutputSchemas];
+};
+
 function createCoordinatorToolRendering(toolName: CoordinatorToolName) {
   return {
     renderCall: (args: CoordinatorToolCallInput, theme: Theme) =>
@@ -145,7 +152,7 @@ function callerSourceTurnId(
 /** Create caller-bound definitions for the six coordinator tools shared by root and children. */
 export function createCoordinatorToolDefinitions(
   options: CoordinatorToolDefinitionOptions,
-): ToolDefinition[] {
+): CoordinatorToolDefinition[] {
   const modelRolePromptGuidelines = buildModelRolePromptGuidelines(options.modelRoles ?? []);
   const spawnTool = defineTool({
     name: "subagent",
@@ -306,7 +313,14 @@ export function createCoordinatorToolDefinitions(
     ...createCoordinatorToolRendering("subagent_delete"),
   });
 
-  const coordinatorTools = [spawnTool, messageTool, waitTool, statusTool, cancelTool, deleteTool];
+  const coordinatorTools: CoordinatorToolDefinition[] = [
+    Object.assign(spawnTool, { outputSchema: CoordinatorToolOutputSchemas.subagent }),
+    Object.assign(messageTool, { outputSchema: CoordinatorToolOutputSchemas.agent_message }),
+    Object.assign(waitTool, { outputSchema: CoordinatorToolOutputSchemas.subagent_wait }),
+    Object.assign(statusTool, { outputSchema: CoordinatorToolOutputSchemas.subagent_status }),
+    Object.assign(cancelTool, { outputSchema: CoordinatorToolOutputSchemas.subagent_cancel }),
+    Object.assign(deleteTool, { outputSchema: CoordinatorToolOutputSchemas.subagent_delete }),
+  ];
   const allowFanoutTools = options.allowFanoutTools ?? options.callerId === "root";
   return allowFanoutTools
     ? coordinatorTools