@emiliosp/pi-maestro 0.6.3 → 0.7.1

package/src/workflow/escalation/resolveEscalations.ts

@@ -0,0 +1,100 @@
+/**
+ * Objective: Save all owner resolutions in the active builder handoff.
+ * Used: When the owner keeps the contract and resolves current questions together.
+ */
+
+import { readBuilderHandoff } from '#artifacts/builder-handoff/readBuilderHandoff.ts';
+import {
+  BUILDER_HANDOFF_STATUSES,
+  type EscalationResolution,
+} from '#artifacts/builder-handoff/schema.ts';
+import { writeBuilderHandoff } from '#artifacts/builder-handoff/writeBuilderHandoff.ts';
+import type { MaestroPaths } from '#MaestroPaths.ts';
+import { readWorkflowState } from '#workflow/state/readWorkflowState.ts';
+import { WORKFLOW_EVENTS, WORKFLOW_PHASES } from '#workflow/state/schema.ts';
+import { writeWorkflowState } from '#workflow/state/writeWorkflowState.ts';
+import { transitionWorkflow } from '#workflow/transitions.ts';
+
+export type EscalationDecision = EscalationResolution & {
+  escalationId: string;
+};
+
+type ResolveEscalationsInput = {
+  paths: MaestroPaths;
+  specId: string;
+  decisions: EscalationDecision[];
+};
+
+export const resolveEscalations = async ({
+  paths,
+  specId,
+  decisions,
+}: ResolveEscalationsInput) => {
+  const workflowPath = paths.getWorkflowPath(specId);
+  const state = await readWorkflowState(workflowPath);
+
+  if (state.specId !== specId) throw new Error('Workflow spec ID mismatch.');
+
+  if (state.phase !== WORKFLOW_PHASES.ESCALATION_DECISION) {
+    throw new Error(
+      `Escalation resolution requires escalation-decision state, found "${state.phase}".`,
+    );
+  }
+
+  const handoffPath = await paths.getActiveBuilderHandoffPath(specId);
+  const handoff = await readBuilderHandoff({ path: handoffPath, specId });
+
+  if (handoff.status !== BUILDER_HANDOFF_STATUSES.ESCALATION) {
+    throw new Error('Escalation resolution requires an escalation handoff.');
+  }
+
+  if (handoff.escalations.some(({ resolution }) => resolution !== null)) {
+    throw new Error('Current questions already contain an owner resolution.');
+  }
+
+  if (decisions.length === 0)
+    throw new Error('At least one escalation decision is required.');
+
+  const expectedIds = new Set(handoff.escalations.map(({ id }) => id));
+  const resolutions = new Map<string, EscalationResolution>();
+
+  for (const { escalationId, ...resolution } of decisions) {
+    if (!expectedIds.has(escalationId))
+      throw new Error(`Unknown escalation ID: "${escalationId}".`);
+
+    if (resolutions.has(escalationId))
+      throw new Error(`Duplicate decision for escalation "${escalationId}".`);
+
+    resolutions.set(escalationId, resolution);
+  }
+
+  const escalations = handoff.escalations.map((escalation) => {
+    const resolution = resolutions.get(escalation.id);
+
+    if (resolution === undefined)
+      throw new Error(`Missing decision for escalation "${escalation.id}".`);
+
+    return { ...escalation, resolution };
+  });
+
+  const nextHandoff = { ...handoff, escalations };
+
+  const nextState = transitionWorkflow({
+    state,
+    event: WORKFLOW_EVENTS.RESOLVE_ESCALATION,
+  });
+
+  // The artifact writer validates every resolution before the first protocol write.
+  await writeBuilderHandoff({
+    path: handoffPath,
+    handoff: nextHandoff,
+    specId,
+  });
+  await writeWorkflowState({ path: workflowPath, state: nextState });
+
+  return {
+    handoff: nextHandoff,
+    state: nextState,
+    projectRoot: paths.getProjectRoot(),
+  };
+};

package/tech-stack.md

@@ -0,0 +1,14 @@
+# Tech stack
+
+Maestro is a source-only TypeScript package that uses ECMAScript modules (ESM). Pi loads the TypeScript source directly. The package has no build step or compiled `dist/` directory.
+
+| Technology | Use |
+|---|---|
+| TypeScript | Application code and static type checks with `tsc --noEmit`. |
+| Node.js | Runtime. |
+| Pi | Extension host, agent APIs, and terminal interface. |
+| `pi-subagents` | Builder and verifier execution and activity tracking. |
+| TypeBox | Schemas and runtime validation for configuration, workflow state, tool inputs, and agent reports. |
+| Vitest with V8 coverage | Unit tests, integration tests, and code coverage. |
+| Biome | Formatting and lint checks. |
+| Oxlint with `oxlint-anti-slop` | Additional lint and anti-slop checks. |

package/src/artifacts/escalation/assertEscalation.ts

@@ -1,66 +0,0 @@
-/**
- * Objective: Check the escalation schema and option references.
- * Used: When Maestro handles escalation artifacts.
- */
-
-import { Value } from 'typebox/value';
-import {
-  type Escalation,
-  EscalationSchema,
-} from '#artifacts/escalation/schema.ts';
-import { isValidSpecId } from '#ids/isValidSpecId.ts';
-
-type HasOptionInput = {
-  escalation: Escalation;
-  optionId: string;
-};
-
-const hasOption = ({ escalation, optionId }: HasOptionInput): boolean =>
-  escalation.options.some((option) => option.id === optionId);
-
-function assertEscalationSchema(input: unknown): asserts input is Escalation {
-  if (typeof input !== 'object' || input === null || Array.isArray(input)) {
-    throw new Error('Escalation must be a JSON object.');
-  }
-
-  const [error] = Value.Errors(EscalationSchema, input);
-
-  if (error !== undefined) {
-    throw new Error(`Invalid escalation: ${error.message}.`);
-  }
-}
-
-export function assertEscalation(input: unknown): asserts input is Escalation {
-  assertEscalationSchema(input);
-  const escalation = input;
-
-  if (!isValidSpecId(escalation.specId)) {
-    throw new Error(`Invalid escalation spec ID: "${escalation.specId}".`);
-  }
-
-  if (
-    new Set(escalation.options.map((option) => option.id)).size !==
-    escalation.options.length
-  ) {
-    throw new Error('Escalation option IDs must be unique.');
-  }
-
-  if (
-    escalation.recommendation !== null &&
-    !hasOption({ escalation, optionId: escalation.recommendation.optionId })
-  ) {
-    throw new Error(
-      `Escalation recommendation references unknown option "${escalation.recommendation.optionId}".`,
-    );
-  }
-
-  if (
-    escalation.resolution !== null &&
-    escalation.resolution.selectedOptionId !== null &&
-    !hasOption({ escalation, optionId: escalation.resolution.selectedOptionId })
-  ) {
-    throw new Error(
-      `Escalation resolution references unknown option "${escalation.resolution.selectedOptionId}".`,
-    );
-  }
-}

package/src/artifacts/escalation/createEscalation.ts

@@ -1,52 +0,0 @@
-/**
- * Objective: Create an unresolved escalation.
- * Used: When Maestro handles escalation artifacts.
- */
-
-import { join } from 'node:path';
-import { assertEscalation } from '#artifacts/escalation/assertEscalation.ts';
-import { getNextEscalationId } from '#artifacts/escalation/getNextEscalationId.ts';
-import {
-  ESCALATION_VERSION,
-  type Escalation,
-  type NewEscalation,
-} from '#artifacts/escalation/schema.ts';
-import { writeJson } from '#utils/write-json.ts';
-
-type CreateEscalationInput = {
-  directory: string;
-  specId: string;
-  escalation: NewEscalation;
-};
-
-export const createEscalation = async ({
-  directory,
-  specId,
-  escalation,
-}: CreateEscalationInput): Promise<{
-  path: string;
-  escalation: Escalation;
-}> => {
-  const id = await getNextEscalationId({
-    directory,
-    specId,
-  });
-
-  const newEscalation = {
-    question: escalation.question,
-    context: escalation.context,
-    options: escalation.options,
-    recommendation: escalation.recommendation,
-    notes: escalation.notes,
-    version: ESCALATION_VERSION,
-    specId,
-    id,
-    resolution: null,
-  };
-
-  assertEscalation(newEscalation);
-  const path = join(directory, `${id}.json`);
-  await writeJson({ path, data: newEscalation });
-
-  return { path, escalation: newEscalation };
-};

package/src/artifacts/escalation/getNextEscalationId.ts

@@ -1,23 +0,0 @@
-/**
- * Objective: Allocate the next escalation ID from history.
- * Used: When Maestro handles escalation artifacts.
- */
-
-import { readEscalationHistory } from '#artifacts/escalation/readEscalationHistory.ts';
-
-type GetNextEscalationIdInput = {
-  directory: string;
-  specId: string;
-};
-
-export const getNextEscalationId = async ({
-  directory,
-  specId,
-}: GetNextEscalationIdInput): Promise<string> => {
-  const history = await readEscalationHistory({
-    directory,
-    specId,
-  });
-
-  return `E${history.length + 1}`;
-};

package/src/artifacts/escalation/readEscalation.ts

@@ -1,40 +0,0 @@
-/**
- * Objective: Read an escalation for its workflow.
- * Used: When Maestro handles escalation artifacts.
- */
-
-import { assertEscalation } from '#artifacts/escalation/assertEscalation.ts';
-import type { Escalation } from '#artifacts/escalation/schema.ts';
-import { readJsonFile } from '#utils/read-json.ts';
-
-type AssertWorkflowEscalationInput = {
-  escalation: Escalation;
-  specId: string;
-};
-
-function assertWorkflowEscalation({
-  escalation,
-  specId,
-}: AssertWorkflowEscalationInput): void {
-  if (escalation.specId !== specId) {
-    throw new Error(
-      `Escalation spec ID mismatch: expected "${specId}", found "${escalation.specId}".`,
-    );
-  }
-}
-
-type ReadEscalationInput = {
-  path: string;
-  specId: string;
-};
-
-export const readEscalation = async ({
-  path,
-  specId,
-}: ReadEscalationInput): Promise<Escalation> => {
-  const escalation = await readJsonFile({ path, description: 'Escalation' });
-  assertEscalation(escalation);
-  assertWorkflowEscalation({ escalation, specId });
-
-  return escalation;
-};

package/src/artifacts/escalation/readEscalationHistory.ts

@@ -1,44 +0,0 @@
-/**
- * Objective: Read and order validated escalation history.
- * Used: When Maestro handles escalation artifacts.
- */
-
-import { readdir } from 'node:fs/promises';
-import { join } from 'node:path';
-import { readEscalation } from '#artifacts/escalation/readEscalation.ts';
-import type { Escalation } from '#artifacts/escalation/schema.ts';
-
-const ESCALATION_FILE_PATTERN = /^E([1-9]\d*)\.json$/;
-
-type ReadEscalationHistoryInput = {
-  directory: string;
-  specId: string;
-};
-
-export const readEscalationHistory = async ({
-  directory,
-  specId,
-}: ReadEscalationHistoryInput): Promise<Escalation[]> => {
-  const files = await readdir(directory);
-
-  if (!files.every((file) => ESCALATION_FILE_PATTERN.test(file))) {
-    throw new Error('Escalation history contains an invalid entry.');
-  }
-
-  const orderedFiles = files.sort(
-    (left, right) => Number(left.slice(1, -5)) - Number(right.slice(1, -5)),
-  );
-
-  const escalations: Escalation[] = [];
-
-  for (const file of orderedFiles.values()) {
-    const escalation = await readEscalation({
-      path: join(directory, file),
-      specId,
-    });
-
-    escalations.push(escalation);
-  }
-
-  return escalations;
-};

package/src/artifacts/escalation/resolveEscalation.ts

@@ -1,43 +0,0 @@
-/**
- * Objective: Record an owner escalation resolution.
- * Used: When Maestro handles escalation artifacts.
- */
-
-import { assertEscalation } from '#artifacts/escalation/assertEscalation.ts';
-import { readEscalation } from '#artifacts/escalation/readEscalation.ts';
-import type {
-  Escalation,
-  EscalationResolution,
-} from '#artifacts/escalation/schema.ts';
-import { writeJson } from '#utils/write-json.ts';
-
-type ResolveEscalationInput = {
-  path: string;
-  specId: string;
-  resolution: EscalationResolution;
-};
-
-export const resolveEscalation = async ({
-  path,
-  specId,
-  resolution,
-}: ResolveEscalationInput): Promise<Escalation> => {
-  const current = await readEscalation({
-    path,
-    specId,
-  });
-
-  if (current.resolution !== null) {
-    throw new Error(`Escalation "${current.id}" is already resolved.`);
-  }
-
-  const resolvedEscalation = {
-    ...current,
-    resolution,
-  };
-
-  assertEscalation(resolvedEscalation);
-  await writeJson({ path, data: resolvedEscalation });
-
-  return resolvedEscalation;
-};

package/src/artifacts/escalation/schema.ts

@@ -1,73 +0,0 @@
-/**
- * Objective: Define escalation options and resolution contracts.
- * Used: When Maestro handles escalation artifacts.
- */
-
-import { type Static, Type } from 'typebox';
-import { SPEC_ID_PATTERN } from '#ids/isValidSpecId.ts';
-
-export const ESCALATION_VERSION = '1.0.0';
-
-export const ESCALATION_ID_PATTERN = /^E([1-9]\d*)$/;
-
-export const EscalationOptionSchema = Type.Object(
-  {
-    id: Type.String({ minLength: 1 }),
-    description: Type.String({ minLength: 1 }),
-    consequences: Type.String({ minLength: 1 }),
-    nextStep: Type.String({ minLength: 1 }),
-  },
-  { additionalProperties: false },
-);
-
-export const EscalationRecommendationSchema = Type.Object(
-  {
-    optionId: Type.String({ minLength: 1 }),
-    reason: Type.String({ minLength: 1 }),
-  },
-  { additionalProperties: false },
-);
-
-export const EscalationResolutionSchema = Type.Object(
-  {
-    selectedOptionId: Type.Union([Type.String({ minLength: 1 }), Type.Null()]),
-    decision: Type.String({ minLength: 1 }),
-    reason: Type.String({ minLength: 1 }),
-  },
-  { additionalProperties: false },
-);
-
-const NewEscalationFields = {
-  question: Type.String({ minLength: 1 }),
-  context: Type.String({ minLength: 1 }),
-  options: Type.Array(EscalationOptionSchema, { minItems: 1 }),
-  notes: Type.Array(Type.String()),
-};
-
-export const NewEscalationSchema = Type.Object(
-  {
-    ...NewEscalationFields,
-    recommendation: Type.Union([EscalationRecommendationSchema, Type.Null()]),
-  },
-  { additionalProperties: false },
-);
-
-export const EscalationSchema = Type.Object(
-  {
-    version: Type.Literal(ESCALATION_VERSION),
-    specId: Type.String({ pattern: SPEC_ID_PATTERN.source }),
-    id: Type.String({ pattern: ESCALATION_ID_PATTERN.source }),
-    ...NewEscalationFields,
-    recommendation: Type.Union([EscalationRecommendationSchema, Type.Null()]),
-    resolution: Type.Union([EscalationResolutionSchema, Type.Null()]),
-  },
-  { additionalProperties: false },
-);
-
-export type EscalationOption = Static<typeof EscalationOptionSchema>;
-
-export type EscalationResolution = Static<typeof EscalationResolutionSchema>;
-
-export type Escalation = Static<typeof EscalationSchema>;
-
-export type NewEscalation = Static<typeof NewEscalationSchema>;

package/src/tools/child/open-escalation.ts

@@ -1,71 +0,0 @@
-/**
- * Objective: Register the builder escalation tool for the current project.
- * Used: When the builder finds a significant discovery that requires an owner decision.
- */
-
-import type { ExtensionAPI } from '@earendil-works/pi-coding-agent';
-import { Type } from 'typebox';
-import {
-  EscalationOptionSchema,
-  EscalationRecommendationSchema,
-} from '#artifacts/escalation/schema.ts';
-import { SPEC_ID_PATTERN } from '#ids/isValidSpecId.ts';
-import { resolveWorkflowContext } from '#tools/child/utils/resolveWorkflowContext.ts';
-import { openBuilderEscalation } from '#workflow/escalation/openBuilderEscalation.ts';
-
-export const BUILDER_ESCALATION_TOOL = {
-  NAME: 'maestro_open_escalation',
-  LABEL: 'Open Builder Escalation',
-  DESCRIPTION:
-    'Ask the owner to choose between options for a significant discovery or unresolved decision. An escalation is not limited to a technical failure or blocker. After success, stop. The tool saves the escalation and workflow phase. Do not wait for the owner.',
-} as const;
-
-const BuilderEscalationToolParameters = Type.Object(
-  {
-    specId: Type.String({ pattern: SPEC_ID_PATTERN.source }),
-    question: Type.String({ minLength: 1 }),
-    context: Type.String({ minLength: 1 }),
-    options: Type.Array(EscalationOptionSchema, { minItems: 1 }),
-    recommendation: Type.Union([EscalationRecommendationSchema, Type.Null()]),
-    notes: Type.Array(Type.String()),
-  },
-  { additionalProperties: false },
-);
-
-export const registerOpenEscalationTool = (pi: ExtensionAPI): void => {
-  pi.registerTool({
-    name: BUILDER_ESCALATION_TOOL.NAME,
-    label: BUILDER_ESCALATION_TOOL.LABEL,
-    description: BUILDER_ESCALATION_TOOL.DESCRIPTION,
-    parameters: BuilderEscalationToolParameters,
-    async execute(_toolCallId, params, _signal, _onUpdate, context) {
-      const { specId, ...escalation } = params;
-
-      const { paths } = await resolveWorkflowContext({
-        cwd: context.cwd,
-        specId,
-      });
-
-      const opened = await openBuilderEscalation({
-        paths,
-        specId,
-        escalation,
-      });
-
-      return {
-        content: [
-          {
-            type: 'text',
-            text: `Escalation ${opened.escalation.id} recorded. The escalation and workflow phase are saved. Stop now. Do not wait for the owner.`,
-          },
-        ],
-        details: {
-          specId: opened.escalation.specId,
-          escalationId: opened.escalation.id,
-          escalationPath: opened.escalationPath,
-          phase: opened.state.phase,
-        },
-      };
-    },
-  });
-};

package/src/tools/main/resolve-escalation.ts

@@ -1,65 +0,0 @@
-/**
- * Objective: Register owner resolution of the current builder escalation.
- * Used: When the owner keeps the approved contract and chooses an escalation resolution.
- */
-
-import type { ExtensionAPI } from '@earendil-works/pi-coding-agent';
-import { Type } from 'typebox';
-import {
-  ESCALATION_ID_PATTERN,
-  EscalationResolutionSchema,
-} from '#artifacts/escalation/schema.ts';
-import { SPEC_ID_PATTERN } from '#ids/isValidSpecId.ts';
-import { resolveToolRunContext } from '#tools/utils/resolveToolRunContext.ts';
-import { resolveBuilderEscalation } from '#workflow/escalation/resolveBuilderEscalation.ts';
-
-export const RESOLVE_ESCALATION_TOOL = {
-  NAME: 'maestro_resolve_escalation',
-  LABEL: 'Resolve Escalation',
-  DESCRIPTION:
-    'Record the explicit owner decision for the current builder escalation when the approved contract remains valid. Save the resolution and workflow transition, then return ready-for-builder without running the builder. If the contract must change, edit spec.md and use maestro_mark_spec_ready instead.',
-} as const;
-
-const ResolveEscalationToolParameters = Type.Object(
-  {
-    specId: Type.String({ pattern: SPEC_ID_PATTERN.source }),
-    escalationId: Type.String({ pattern: ESCALATION_ID_PATTERN.source }),
-    ...EscalationResolutionSchema.properties,
-  },
-  { additionalProperties: false },
-);
-
-export const registerResolveEscalationTool = (pi: ExtensionAPI): void => {
-  pi.registerTool({
-    name: RESOLVE_ESCALATION_TOOL.NAME,
-    label: RESOLVE_ESCALATION_TOOL.LABEL,
-    description: RESOLVE_ESCALATION_TOOL.DESCRIPTION,
-    parameters: ResolveEscalationToolParameters,
-    async execute(_toolCallId, params, _signal, _onUpdate, context) {
-      const { specId, escalationId, ...resolution } = params;
-      const { paths } = await resolveToolRunContext(context.cwd);
-
-      const resolved = await resolveBuilderEscalation({
-        paths,
-        specId,
-        escalationId,
-        resolution,
-      });
-
-      return {
-        content: [
-          {
-            type: 'text',
-            text: `Escalation ${resolved.escalation.id} resolved. Spec ${resolved.state.specId} is ready-for-builder. Run the builder separately.`,
-          },
-        ],
-        details: {
-          specId: resolved.state.specId,
-          escalationId: resolved.escalation.id,
-          phase: resolved.state.phase,
-          projectRoot: resolved.projectRoot,
-        },
-      };
-    },
-  });
-};

package/src/workflow/escalation/openBuilderEscalation.ts

@@ -1,82 +0,0 @@
-/**
- * Objective: Open a builder escalation and move the workflow to an owner decision.
- * Used: When a builder identifies a significant discovery that requires owner attention.
- */
-
-import { mkdir } from 'node:fs/promises';
-import { createEscalation } from '#artifacts/escalation/createEscalation.ts';
-import type {
-  Escalation,
-  NewEscalation,
-} from '#artifacts/escalation/schema.ts';
-import type { MaestroPaths } from '#MaestroPaths.ts';
-import { readWorkflowState } from '#workflow/state/readWorkflowState.ts';
-import {
-  WORKFLOW_EVENTS,
-  WORKFLOW_PHASES,
-  type WorkflowState,
-} from '#workflow/state/schema.ts';
-import { writeWorkflowState } from '#workflow/state/writeWorkflowState.ts';
-import { transitionWorkflow } from '#workflow/transitions.ts';
-
-export type OpenedBuilderEscalation = {
-  escalation: Escalation;
-  state: WorkflowState;
-  projectRoot: string;
-  workflowPath: string;
-  escalationPath: string;
-};
-
-type OpenBuilderEscalationInput = {
-  paths: MaestroPaths;
-  specId: string;
-  escalation: NewEscalation;
-};
-
-export const openBuilderEscalation = async ({
-  paths,
-  specId,
-  escalation,
-}: OpenBuilderEscalationInput): Promise<OpenedBuilderEscalation> => {
-  const workflowPath = paths.getWorkflowPath(specId);
-  const escalationsPath = paths.getEscalationsPath(specId);
-  const currentState = await readWorkflowState(workflowPath);
-
-  if (currentState.specId !== specId) {
-    throw new Error(
-      `Workflow spec ID mismatch: expected "${specId}", found "${currentState.specId}".`,
-    );
-  }
-
-  if (currentState.phase !== WORKFLOW_PHASES.BUILDER_RUNNING) {
-    throw new Error(
-      `Builder escalation requires builder-running state, found "${currentState.phase}".`,
-    );
-  }
-
-  const nextState = transitionWorkflow({
-    state: currentState,
-    event: WORKFLOW_EVENTS.OPEN_ESCALATION,
-  });
-
-  await mkdir(escalationsPath, { recursive: true });
-
-  const created = await createEscalation({
-    directory: escalationsPath,
-    specId: currentState.specId,
-    escalation,
-  });
-
-  await writeWorkflowState({
-    path: workflowPath,
-    state: nextState,
-  });
-
-  return {
-    escalation: created.escalation,
-    state: nextState,
-    projectRoot: paths.getProjectRoot(),
-    workflowPath,
-    escalationPath: created.path,
-  };
-};