@emiliosp/pi-maestro 0.17.0 → 0.18.0

package/src/tools/child/record-simplifier-handoff.ts

@@ -1,9 +1,9 @@
 /**
- * Objective: Register the simplifier's fixed result recording tool.
+ * Objective: Define the simplifier's fixed result recording tool.
  * Used: When a child simplifier completes its refactoring pass.
  */
 
-import type { ExtensionAPI } from '@earendil-works/pi-coding-agent';
+import type { ToolDefinition } from '@earendil-works/pi-coding-agent';
 import { type Static, Type } from 'typebox';
 import { Value } from 'typebox/value';
 
@@ -35,40 +35,38 @@ function assertSimplifierSubmission(
   }
 }
 
-export const registerRecordSimplifierHandoffTool = (pi: ExtensionAPI): void => {
-  pi.registerTool({
-    name: SIMPLIFIER_HANDOFF_TOOL.NAME,
-    label: SIMPLIFIER_HANDOFF_TOOL.LABEL,
-    description: SIMPLIFIER_HANDOFF_TOOL.DESCRIPTION,
-    parameters: SimplifierHandoffToolParameters,
-    async execute(_toolCallId, params, _signal, _onUpdate, context) {
-      assertSimplifierSubmission(params);
+export const recordSimplifierHandoffTool = {
+  name: SIMPLIFIER_HANDOFF_TOOL.NAME,
+  label: SIMPLIFIER_HANDOFF_TOOL.LABEL,
+  description: SIMPLIFIER_HANDOFF_TOOL.DESCRIPTION,
+  parameters: SimplifierHandoffToolParameters,
+  async execute(_toolCallId, params, _signal, _onUpdate, context) {
+    assertSimplifierSubmission(params);
 
-      const { paths, config } = await resolveWorkflowContext({
-        cwd: context.cwd,
-        specId: params.specId,
-      });
+    const { paths, config } = await resolveWorkflowContext({
+      cwd: context.cwd,
+      specId: params.specId,
+    });
 
-      const completed = await completeSimplifierPass({
-        config,
-        paths,
-        specId: params.specId,
-        handoff: { ...params, version: SIMPLIFIER_HANDOFF_VERSION },
-      });
+    const completed = await completeSimplifierPass({
+      config,
+      paths,
+      specId: params.specId,
+      handoff: { ...params, version: SIMPLIFIER_HANDOFF_VERSION },
+    });
 
-      return {
-        content: [
-          {
-            type: 'text',
-            text: 'Simplifier handoff and candidate-ready phase saved. Stop now.',
-          },
-        ],
-        details: {
-          specId: params.specId,
-          handoffPath: completed.handoffPath,
-          phase: completed.state.phase,
+    return {
+      content: [
+        {
+          type: 'text',
+          text: 'Simplifier handoff and candidate-ready phase saved. Stop now.',
         },
-      };
-    },
-  });
-};
+      ],
+      details: {
+        specId: params.specId,
+        handoffPath: completed.handoffPath,
+        phase: completed.state.phase,
+      },
+    };
+  },
+} satisfies ToolDefinition<typeof SimplifierHandoffToolParameters>;

package/src/tools/child/record-verifier-handoff.ts

@@ -1,9 +1,9 @@
 /**
- * Objective: Register the verifier handoff tool for the current project.
+ * Objective: Define the verifier handoff tool for the current project.
  * Used: When the verifier reports its terminal review result.
  */
 
-import type { ExtensionAPI } from '@earendil-works/pi-coding-agent';
+import type { ToolDefinition } from '@earendil-works/pi-coding-agent';
 import { Type } from 'typebox';
 
 import { BuilderAcceptanceCriterionSchema } from '#artifacts/builder-handoff/schema.ts';
@@ -44,46 +44,44 @@ const VerifierHandoffToolParameters = Type.Object(
   { additionalProperties: false },
 );
 
-export const registerRecordVerifierHandoffTool = (pi: ExtensionAPI): void => {
-  pi.registerTool({
-    name: VERIFIER_HANDOFF_TOOL.NAME,
-    label: VERIFIER_HANDOFF_TOOL.LABEL,
-    description: VERIFIER_HANDOFF_TOOL.DESCRIPTION,
-    parameters: VerifierHandoffToolParameters,
-    async execute(_toolCallId, params, _signal, _onUpdate, context) {
-      const { specId, ...submission } = params;
+export const recordVerifierHandoffTool = {
+  name: VERIFIER_HANDOFF_TOOL.NAME,
+  label: VERIFIER_HANDOFF_TOOL.LABEL,
+  description: VERIFIER_HANDOFF_TOOL.DESCRIPTION,
+  parameters: VerifierHandoffToolParameters,
+  async execute(_toolCallId, params, _signal, _onUpdate, context) {
+    const { specId, ...submission } = params;
 
-      const { paths, config } = await resolveWorkflowContext({
-        cwd: context.cwd,
-        specId,
-      });
+    const { paths, config } = await resolveWorkflowContext({
+      cwd: context.cwd,
+      specId,
+    });
 
-      const currentState = await readWorkflowState(paths.getWorkflowPath(specId));
+    const currentState = await readWorkflowState(paths.getWorkflowPath(specId));
 
-      const handoff = {
-        version: VERIFIER_HANDOFF_VERSION,
-        specId: currentState.specId,
-        summary: submission.summary,
-        acceptanceCriteria: submission.acceptanceCriteria,
-        findings: submission.findings,
-        notes: submission.notes,
-      };
+    const handoff = {
+      version: VERIFIER_HANDOFF_VERSION,
+      specId: currentState.specId,
+      summary: submission.summary,
+      acceptanceCriteria: submission.acceptanceCriteria,
+      findings: submission.findings,
+      notes: submission.notes,
+    };
 
-      const completed = await completeVerifierPass({ config, paths, specId, handoff });
+    const completed = await completeVerifierPass({ config, paths, specId, handoff });
 
-      return {
-        content: [
-          {
-            type: 'text',
-            text: `Verifier handoff recorded as ${completed.state.phase}. The handoff and workflow phase are saved. Stop now.`,
-          },
-        ],
-        details: {
-          handoffPath: completed.handoffPath,
-          phase: completed.state.phase,
-          specId: completed.handoff.specId,
+    return {
+      content: [
+        {
+          type: 'text',
+          text: `Verifier handoff recorded as ${completed.state.phase}. The handoff and workflow phase are saved. Stop now.`,
         },
-      };
-    },
-  });
-};
+      ],
+      details: {
+        handoffPath: completed.handoffPath,
+        phase: completed.state.phase,
+        specId: completed.handoff.specId,
+      },
+    };
+  },
+} satisfies ToolDefinition<typeof VerifierHandoffToolParameters>;

package/src/tools/main/run-builder.ts

@@ -3,10 +3,7 @@
  * Used: When the owner invokes the run-builder tool.
  */
 
-import { randomUUID } from 'node:crypto';
-
 import type { ExtensionAPI } from '@earendil-works/pi-coding-agent';
-import type { SubagentDelegationRequest } from 'pi-subagents/delegation';
 import { Type } from 'typebox';
 
 import { readBuilderHandoff } from '#artifacts/builder-handoff/readBuilderHandoff.ts';
@@ -14,15 +11,11 @@ import {
   BUILDER_HANDOFF_STATUSES,
   type BuilderHandoff,
 } from '#artifacts/builder-handoff/schema.ts';
-import { AGENTS, type MaestroConfig } from '#config/schema.ts';
+import type { MaestroConfig } from '#config/schema.ts';
 import { SPEC_ID_PATTERN } from '#ids/isValidSpecId.ts';
 import { refreshMaestroStatus } from '#maestro/status/refreshMaestroStatus.ts';
 import type { MaestroPaths } from '#MaestroPaths.ts';
-import {
-  assertDelegationResponse,
-  SUBAGENT_TIMEOUT_MS,
-  waitForDelegationResponse,
-} from '#tools/utils/pi-subagent-delegation.ts';
+import { executeRoleTask } from '#tools/utils/executeRoleTask.ts';
 import { resolveToolRunContext } from '#tools/utils/resolveToolRunContext.ts';
 import { prepareBuilderRun } from '#workflow/builder/prepareBuilderRun.ts';
 import { WORKFLOW_ROLES } from '#workflow/roles.ts';
@@ -162,7 +155,7 @@ export const registerRunBuilderTool = (pi: ExtensionAPI): void => {
     label: RUN_BUILDER_TOOL.LABEL,
     description: RUN_BUILDER_TOOL.DESCRIPTION,
     parameters: RunBuilderToolParameters,
-    async execute(toolCallId, { specId }, _signal, _onUpdate, context) {
+    async execute(_toolCallId, { specId }, signal, _onUpdate, context) {
       const { paths, config } = await resolveToolRunContext(context.cwd);
 
       const { projectRoot, state: builderRunningState } = await prepareBuilderRun({
@@ -173,28 +166,16 @@ export const registerRunBuilderTool = (pi: ExtensionAPI): void => {
 
       await refreshMaestroStatus(context);
 
-      const request: SubagentDelegationRequest = {
-        requestId: randomUUID(),
-        ownerRunId: toolCallId,
-        nodeId: WORKFLOW_ROLES.BUILDER,
-        // pi-subagents loads this name from agents/builder.md through package.json.
-        // See docs/subagent-integration.md.
-        agent: AGENTS.BUILDER,
-        task: `Implement specId "${specId}" in the project directory "${projectRoot}".`,
-        context: 'fresh',
+      await executeRoleTask({
+        role: WORKFLOW_ROLES.BUILDER,
+        prompt: `Implement specId "${specId}" in the project directory "${projectRoot}".`,
         cwd: projectRoot,
         model: config.builder.model,
-        thinking: config.builder.thinking,
-        timeoutMs: SUBAGENT_TIMEOUT_MS,
-        result: { kind: 'text' },
-      };
-
-      const response = await waitForDelegationResponse({
-        piEventsBus: pi.events,
-        request,
+        thinkingLevel: config.builder.thinking,
+        signal,
+        ui: context.ui,
       });
 
-      assertDelegationResponse(response);
       const result = await readBuilderResult({ paths, specId, config, builderRunningState });
 
       return {

package/src/tools/main/run-simplifier.ts

@@ -3,22 +3,14 @@
  * Used: After verification succeeds or the owner rejects all findings.
  */
 
-import { randomUUID } from 'node:crypto';
-
 import type { ExtensionAPI } from '@earendil-works/pi-coding-agent';
-import type { SubagentDelegationRequest } from 'pi-subagents/delegation';
 import { Type } from 'typebox';
 
 import { readSimplifierHandoff } from '#artifacts/simplifier-handoff/readSimplifierHandoff.ts';
-import { AGENTS } from '#config/schema.ts';
 import { SPEC_ID_PATTERN } from '#ids/isValidSpecId.ts';
 import { refreshMaestroStatus } from '#maestro/status/refreshMaestroStatus.ts';
 import type { MaestroPaths } from '#MaestroPaths.ts';
-import {
-  assertDelegationResponse,
-  SUBAGENT_TIMEOUT_MS,
-  waitForDelegationResponse,
-} from '#tools/utils/pi-subagent-delegation.ts';
+import { executeRoleTask } from '#tools/utils/executeRoleTask.ts';
 import { resolveToolRunContext } from '#tools/utils/resolveToolRunContext.ts';
 import { WORKFLOW_ROLES } from '#workflow/roles.ts';
 import { readWorkflowState } from '#workflow/state/readWorkflowState.ts';
@@ -95,7 +87,7 @@ export const registerRunSimplifierTool = (pi: ExtensionAPI): void => {
     label: RUN_SIMPLIFIER_TOOL.LABEL,
     description: RUN_SIMPLIFIER_TOOL.DESCRIPTION,
     parameters: RunSimplifierToolParameters,
-    async execute(toolCallId, { specId }, _signal, _onUpdate, context) {
+    async execute(_toolCallId, { specId }, signal, _onUpdate, context) {
       const { paths, config, projectRoot } = await resolveToolRunContext(context.cwd);
 
       const workflowPath = paths.getWorkflowPath(specId);
@@ -136,26 +128,16 @@ export const registerRunSimplifierTool = (pi: ExtensionAPI): void => {
         };
       }
 
-      const request: SubagentDelegationRequest = {
-        requestId: randomUUID(),
-        ownerRunId: toolCallId,
-        nodeId: WORKFLOW_ROLES.SIMPLIFIER,
-        agent: AGENTS.SIMPLIFIER,
-        task: `Simplify accepted code for specId "${specId}" in the project directory "${projectRoot}". Discover all current staged, unstaged, and untracked code changes with Git, including pre-existing changes.`,
-        context: 'fresh',
+      await executeRoleTask({
+        role: WORKFLOW_ROLES.SIMPLIFIER,
+        prompt: `Simplify accepted code for specId "${specId}" in the project directory "${projectRoot}". Discover all current staged, unstaged, and untracked code changes with Git, including pre-existing changes.`,
         cwd: projectRoot,
         model: config.simplifier.model,
-        thinking: config.simplifier.thinking,
-        timeoutMs: SUBAGENT_TIMEOUT_MS,
-        result: { kind: 'text' },
-      };
-
-      const response = await waitForDelegationResponse({
-        piEventsBus: pi.events,
-        request,
+        thinkingLevel: config.simplifier.thinking,
+        signal,
+        ui: context.ui,
       });
 
-      assertDelegationResponse(response);
       const result = await readSimplifierResult({ paths, specId });
 
       return {

package/src/tools/main/run-verifier.ts

@@ -3,23 +3,16 @@
  * Used: When the owner invokes the run-verifier tool.
  */
 
-import { randomUUID } from 'node:crypto';
-
 import type { ExtensionAPI } from '@earendil-works/pi-coding-agent';
-import type { SubagentDelegationRequest } from 'pi-subagents/delegation';
 import { Type } from 'typebox';
 
 import { readVerifierHandoff } from '#artifacts/verifier-handoff/readVerifierHandoff.ts';
 import type { VerifierHandoff } from '#artifacts/verifier-handoff/schema.ts';
-import { AGENTS, type MaestroConfig } from '#config/schema.ts';
+import type { MaestroConfig } from '#config/schema.ts';
 import { SPEC_ID_PATTERN } from '#ids/isValidSpecId.ts';
 import { refreshMaestroStatus } from '#maestro/status/refreshMaestroStatus.ts';
 import type { MaestroPaths } from '#MaestroPaths.ts';
-import {
-  assertDelegationResponse,
-  SUBAGENT_TIMEOUT_MS,
-  waitForDelegationResponse,
-} from '#tools/utils/pi-subagent-delegation.ts';
+import { executeRoleTask } from '#tools/utils/executeRoleTask.ts';
 import { resolveToolRunContext } from '#tools/utils/resolveToolRunContext.ts';
 import { WORKFLOW_ROLES } from '#workflow/roles.ts';
 import { readWorkflowState } from '#workflow/state/readWorkflowState.ts';
@@ -131,33 +124,22 @@ export const registerRunVerifierTool = (pi: ExtensionAPI): void => {
     label: RUN_VERIFIER_TOOL.LABEL,
     description: RUN_VERIFIER_TOOL.DESCRIPTION,
     parameters: RunVerifierToolParameters,
-    async execute(toolCallId, { specId }, _signal, _onUpdate, context) {
+    async execute(_toolCallId, { specId }, signal, _onUpdate, context) {
       const { paths, config } = await resolveToolRunContext(context.cwd);
 
       const run = await prepareVerifierRun({ config, paths, specId });
       await refreshMaestroStatus(context);
 
-      const request: SubagentDelegationRequest = {
-        requestId: randomUUID(),
-        ownerRunId: toolCallId,
-        nodeId: WORKFLOW_ROLES.VERIFIER,
-        // pi-subagents loads this name from agents/verifier.md through package.json.
-        agent: AGENTS.VERIFIER,
-        task: `Verify specId "${specId}" in the live project directory "${run.projectRoot}"`,
-        context: 'fresh',
+      await executeRoleTask({
+        role: WORKFLOW_ROLES.VERIFIER,
+        prompt: `Verify specId "${specId}" in the live project directory "${run.projectRoot}".`,
         cwd: run.projectRoot,
         model: config.verifier.model,
-        thinking: config.verifier.thinking,
-        timeoutMs: SUBAGENT_TIMEOUT_MS,
-        result: { kind: 'text' },
-      };
-
-      const response = await waitForDelegationResponse({
-        piEventsBus: pi.events,
-        request,
+        thinkingLevel: config.verifier.thinking,
+        signal,
+        ui: context.ui,
       });
 
-      assertDelegationResponse(response);
       const result = await readVerifierResult({ paths, specId, config, runningState: run.state });
 
       return {

package/src/tools/utils/executeRoleTask.ts

@@ -0,0 +1,57 @@
+/**
+ * Objective: Supply bundled role guidance and its handoff tool to the shared SDK executor.
+ * Used: By the three foreground run tools after preparing their workflow phase.
+ */
+
+import { readFile } from 'node:fs/promises';
+
+import type { ExtensionContext } from '@earendil-works/pi-coding-agent';
+
+import { executeTask, type ExecuteTaskInput } from '#src/delegation/executeTask.ts';
+import { TaskExecutionError } from '#src/delegation/TaskExecutionError.ts';
+import { recordBuilderHandoffTool } from '#tools/child/record-builder-handoff.ts';
+import { recordSimplifierHandoffTool } from '#tools/child/record-simplifier-handoff.ts';
+import { recordVerifierHandoffTool } from '#tools/child/record-verifier-handoff.ts';
+import { WORKFLOW_ROLES, type WorkflowRole } from '#workflow/roles.ts';
+
+const HANDOFF_TOOL_BY_ROLE = {
+  [WORKFLOW_ROLES.BUILDER]: recordBuilderHandoffTool,
+  [WORKFLOW_ROLES.VERIFIER]: recordVerifierHandoffTool,
+  [WORKFLOW_ROLES.SIMPLIFIER]: recordSimplifierHandoffTool,
+} as const;
+
+type ExecuteRoleTaskInput = Pick<
+  ExecuteTaskInput,
+  'prompt' | 'cwd' | 'model' | 'thinkingLevel' | 'signal'
+> & {
+  role: WorkflowRole;
+  ui: ExtensionContext['ui'];
+};
+
+export const executeRoleTask = async ({
+  role,
+  ui,
+  ...input
+}: ExecuteRoleTaskInput): Promise<void> => {
+  const roleGuidance = await readFile(
+    new URL(`../../../agents/${role}.md`, import.meta.url),
+    'utf8',
+  );
+
+  try {
+    const result = await executeTask({
+      ...input,
+      roleGuidance,
+      additionalTools: [HANDOFF_TOOL_BY_ROLE[role]],
+    });
+
+    // Publish before protocol validation so a missing handoff still exposes the transcript.
+    if (result.sessionFile) ui.notify(`Saved child session: ${result.sessionFile}`, 'info');
+  } catch (error) {
+    if (error instanceof TaskExecutionError && error.sessionFile) {
+      ui.notify(`Saved child session: ${error.sessionFile}`, 'info');
+    }
+
+    throw error;
+  }
+};

package/extensions/maestro-subagent.ts

@@ -1,16 +0,0 @@
-/**
- * Objective: Compose the Maestro extension for builder, verifier, and simplifier subagent sessions.
- * Used: When Pi starts a Maestro subagent session.
- */
-
-import type { ExtensionAPI } from '@earendil-works/pi-coding-agent';
-
-import { registerRecordBuilderHandoffTool } from '#tools/child/record-builder-handoff.ts';
-import { registerRecordSimplifierHandoffTool } from '#tools/child/record-simplifier-handoff.ts';
-import { registerRecordVerifierHandoffTool } from '#tools/child/record-verifier-handoff.ts';
-
-export default (pi: ExtensionAPI): void => {
-  registerRecordBuilderHandoffTool(pi);
-  registerRecordVerifierHandoffTool(pi);
-  registerRecordSimplifierHandoffTool(pi);
-};