@wichayutdew/pi-workflows 0.3.0 → 1.0.0

package/src/runtime/main-step-policy.ts

@@ -0,0 +1,84 @@
+import type { ExtensionAPI } from '@earendil-works/pi-coding-agent';
+import { WORKFLOW_COMPLETION_TOOL } from './completion-tool.ts';
+import type {
+  MainStepRuntimeDependencies,
+  MainStepRuntimeState,
+} from './main-step-runtime-types.ts';
+
+type RegisterMainStepPolicyOptions = {
+  readonly pi: ExtensionAPI;
+  readonly state: MainStepRuntimeState;
+  readonly dependencies: MainStepRuntimeDependencies;
+};
+
+/**
+ * Registers policy handlers that isolate and freeze active-step tool calls.
+ *
+ * @param options - Pi API, runtime state, and injected policy operations.
+ */
+export function registerMainStepPolicy({
+  pi,
+  state,
+  dependencies,
+}: RegisterMainStepPolicyOptions): void {
+  pi.on('turn_start', () => {
+    state.invalidCompletionCalls = new Set();
+  });
+
+  pi.on('message_end', (event) => {
+    if (!state.active) {
+      return;
+    }
+
+    const invalidCalls = dependencies.invalidCompletionCallIds(
+      event.message,
+      WORKFLOW_COMPLETION_TOOL,
+    );
+    if (invalidCalls.size > 0 || event.message.role === 'assistant') {
+      state.invalidCompletionCalls = invalidCalls;
+    }
+  });
+
+  pi.on('tool_call', (event) => {
+    if (state.isSuspended) {
+      return {
+        block: true,
+        reason: 'Main-agent workflow step is suspended',
+      };
+    }
+    if (!state.active) {
+      return event.toolName === WORKFLOW_COMPLETION_TOOL
+        ? {
+            block: true,
+            reason: 'No main-agent workflow step is active',
+          }
+        : undefined;
+    }
+    if (state.invalidCompletionCalls.has(event.toolCallId)) {
+      return {
+        block: true,
+        reason: `${WORKFLOW_COMPLETION_TOOL} must be the only tool call in its message`,
+      };
+    }
+    if (event.toolName === WORKFLOW_COMPLETION_TOOL) {
+      dependencies.freezeToolInput(event.input);
+      return;
+    }
+
+    const authorization = dependencies.authorizeToolCall(
+      event.toolName,
+      Object.fromEntries(Object.entries(event.input)),
+      state.active.step,
+      pi.getAllTools(),
+      state.active.approvedBashCommands,
+    );
+    if (!authorization.allowed) {
+      return {
+        block: true,
+        reason: authorization.reason ?? 'Tool blocked by main workflow policy',
+      };
+    }
+
+    dependencies.freezeToolInput(event.input);
+  });
+}

package/src/runtime/main-step-runtime-types.ts

@@ -0,0 +1,64 @@
+import type { ExtensionContext } from '@earendil-works/pi-coding-agent';
+import type { WorkflowStep } from '../config/types.ts';
+import type { invalidCompletionCallIds } from '../policy/completion-batch.ts';
+import type { freezeToolInput } from '../policy/immutable-input.ts';
+import type { authorizeToolCall, resolveActiveTools } from '../policy/tools.ts';
+import type {
+  parseWorkflowStepResult,
+  StepResultPolicy,
+  WorkflowStepResult,
+} from './step-result.ts';
+
+/**
+ * Identity, policy, and settlement callback for one main-agent step.
+ */
+export type MainStepExecution = StepResultPolicy & {
+  readonly workflowId: string;
+  readonly runId: string;
+  readonly stepId: string;
+  readonly stepDigest: string;
+  readonly step: WorkflowStep;
+  readonly approvedBashCommands: ReadonlyArray<string>;
+  /** Handles the captured result after Pi fully settles the agent run. */
+  readonly onSettled: (
+    result: WorkflowStepResult | undefined,
+    context: ExtensionContext,
+  ) => Promise<void> | void;
+};
+
+/**
+ * Functional controller consumed by the workflow harness.
+ */
+export type MainStepRuntimeController = {
+  /** ID of the currently active workflow step. */
+  readonly activeStepId: string | undefined;
+  /** Activates one workflow step. */
+  readonly activate: (execution: MainStepExecution) => void;
+  /** Clears the active step and reports whether one existed. */
+  readonly deactivate: () => boolean;
+  /** Clears the active step and blocks tools until released. */
+  readonly suspend: () => boolean;
+  /** Allows a future step to be activated. */
+  readonly release: () => void;
+};
+
+/**
+ * Injectable policy and parsing operations used by the runtime.
+ */
+export type MainStepRuntimeDependencies = {
+  readonly invalidCompletionCallIds: typeof invalidCompletionCallIds;
+  readonly freezeToolInput: typeof freezeToolInput;
+  readonly authorizeToolCall: typeof authorizeToolCall;
+  readonly resolveActiveTools: typeof resolveActiveTools;
+  readonly parseWorkflowStepResult: typeof parseWorkflowStepResult;
+};
+
+/**
+ * Mutable state isolated within one runtime controller closure.
+ */
+export type MainStepRuntimeState = {
+  active: MainStepExecution | undefined;
+  pendingResult: WorkflowStepResult | undefined;
+  invalidCompletionCalls: ReadonlySet<string>;
+  isSuspended: boolean;
+};

package/src/runtime/main-step-runtime.ts

@@ -1,227 +1,156 @@
-import type {
-  ExtensionAPI,
-  ExtensionContext,
-} from '@earendil-works/pi-coding-agent';
-import type { WorkflowStep } from '../config/types.ts';
+import type { ExtensionAPI } from '@earendil-works/pi-coding-agent';
 import { invalidCompletionCallIds } from '../policy/completion-batch.ts';
 import { freezeToolInput } from '../policy/immutable-input.ts';
 import { authorizeToolCall, resolveActiveTools } from '../policy/tools.ts';
+import { registerMainStepCompletion } from './main-step-completion.ts';
+import { registerMainStepLifecycle } from './main-step-lifecycle.ts';
+import { registerMainStepPolicy } from './main-step-policy.ts';
+import type {
+  MainStepExecution,
+  MainStepRuntimeController,
+  MainStepRuntimeDependencies,
+} from './main-step-runtime-types.ts';
 import {
-  WORKFLOW_COMPLETION_PARAMETERS,
-  WORKFLOW_COMPLETION_TOOL,
-} from './completion-tool.ts';
-import {
-  parseWorkflowStepResult,
-  type StepResultPolicy,
-  type WorkflowStepResult,
-} from './step-result.ts';
-
-export interface MainStepExecution extends StepResultPolicy {
-  workflowId: string;
-  runId: string;
-  stepId: string;
-  stepDigest: string;
-  step: WorkflowStep;
-  approvedBashCommands: string[];
-  onSettled(
-    result: WorkflowStepResult | undefined,
-    context: ExtensionContext,
-  ): Promise<void> | void;
-}
+  activateMainStep,
+  createMainStepRuntimeState,
+  deactivateMainStep,
+} from './main-step-state.ts';
+import { parseWorkflowStepResult } from './step-result.ts';
+import { WORKFLOW_COMPLETION_TOOL } from './completion-tool.ts';
 
-export class MainStepRuntime {
-  private active: MainStepExecution | undefined;
-  private pendingResult: WorkflowStepResult | undefined;
-  private invalidCompletionCalls = new Set<string>();
-  private suspended = false;
+export type {
+  MainStepExecution,
+  MainStepRuntimeController,
+  MainStepRuntimeDependencies,
+} from './main-step-runtime-types.ts';
 
-  constructor(private readonly pi: ExtensionAPI) {
-    this.registerLifecycle();
-    this.registerPolicy();
-    this.registerCompletionTool();
-  }
+const DEFAULT_DEPENDENCIES = {
+  invalidCompletionCallIds,
+  freezeToolInput,
+  authorizeToolCall,
+  resolveActiveTools,
+  parseWorkflowStepResult,
+} as const satisfies MainStepRuntimeDependencies;
 
-  get activeStepId(): string | undefined {
-    return this.active?.stepId;
-  }
+/**
+ * Inputs used to create an isolated main-step runtime.
+ */
+export type CreateMainStepRuntimeOptions = {
+  readonly pi: ExtensionAPI;
+  readonly dependencies?: Partial<MainStepRuntimeDependencies>;
+};
 
-  activate(execution: MainStepExecution): void {
-    if (this.active) {
-      throw new Error(
-        `main workflow step "${this.active.stepId}" is still active`,
-      );
-    }
-    this.suspended = false;
-    this.active = execution;
-    this.pendingResult = undefined;
-    this.invalidCompletionCalls.clear();
-    this.pi.setActiveTools(
-      resolveActiveTools(
-        this.pi.getAllTools(),
+/**
+ * Creates a closure-based main-step runtime with explicit policy dependencies.
+ *
+ * @param options - Pi API and optional dependency overrides.
+ * @returns A controller compatible with the workflow harness.
+ */
+export function createMainStepRuntime({
+  pi,
+  dependencies: dependencyOverrides = {},
+}: CreateMainStepRuntimeOptions): MainStepRuntimeController {
+  const dependencies = {
+    ...DEFAULT_DEPENDENCIES,
+    ...dependencyOverrides,
+  };
+  const state = createMainStepRuntimeState();
+
+  const activate = (execution: MainStepExecution): void => {
+    activateMainStep({ state, execution });
+    pi.setActiveTools(
+      dependencies.resolveActiveTools(
+        pi.getAllTools(),
         execution.step,
         WORKFLOW_COMPLETION_TOOL,
       ),
     );
-  }
+  };
 
-  deactivate(): boolean {
-    const wasActive = this.active !== undefined;
-    this.active = undefined;
-    this.pendingResult = undefined;
-    this.invalidCompletionCalls.clear();
-    return wasActive;
-  }
+  const deactivate = (): boolean => deactivateMainStep(state);
 
-  suspend(): boolean {
-    const wasActive = this.deactivate();
+  const suspend = (): boolean => {
+    const wasActive = deactivate();
     if (wasActive) {
-      this.suspended = true;
-      this.pi.setActiveTools([]);
+      state.isSuspended = true;
+      pi.setActiveTools([]);
     }
     return wasActive;
+  };
+
+  const release = (): void => {
+    state.isSuspended = false;
+  };
+
+  registerMainStepLifecycle({ pi, state });
+  registerMainStepPolicy({ pi, state, dependencies });
+  registerMainStepCompletion({ pi, state, dependencies });
+
+  return {
+    get activeStepId() {
+      return state.active?.stepId;
+    },
+    activate,
+    deactivate,
+    suspend,
+    release,
+  };
+}
+
+/**
+ * Compatibility facade for harness code that constructs the runtime with
+ * `new MainStepRuntime(pi)`.
+ */
+export class MainStepRuntime implements MainStepRuntimeController {
+  private readonly controller: MainStepRuntimeController;
+
+  /**
+   * Creates and registers a main-step runtime against the Pi extension API.
+   *
+   * @param pi - Pi extension API used for lifecycle and tool registration.
+   * @param dependencies - Optional policy and parsing overrides.
+   */
+  constructor(
+    pi: ExtensionAPI,
+    dependencies: Partial<MainStepRuntimeDependencies> = {},
+  ) {
+    this.controller = createMainStepRuntime({ pi, dependencies });
   }
 
-  release(): void {
-    this.suspended = false;
+  /** ID of the active main-agent workflow step, when present. */
+  get activeStepId(): string | undefined {
+    return this.controller.activeStepId;
   }
 
-  private registerLifecycle(): void {
-    const reset = (): void => {
-      this.suspended = false;
-      this.deactivate();
-      this.pi.setActiveTools(
-        this.pi
-          .getActiveTools()
-          .filter((tool) => tool !== WORKFLOW_COMPLETION_TOOL),
-      );
-    };
-    this.pi.on('session_start', reset);
-    this.pi.on('session_tree', reset);
-    this.pi.on('session_shutdown', () => {
-      this.suspended = false;
-      this.deactivate();
-    });
-    this.pi.on('agent_settled', (_event, context) => {
-      const active = this.active;
-      if (!active) return;
-      const result = this.pendingResult;
-      this.active = undefined;
-      this.pendingResult = undefined;
-      this.invalidCompletionCalls.clear();
-      return active.onSettled(result, context);
-    });
+  /**
+   * Activates one main-agent workflow step.
+   *
+   * @param execution - Step identity, policy, and settlement callback.
+   */
+  activate(execution: MainStepExecution): void {
+    this.controller.activate(execution);
   }
 
-  private registerPolicy(): void {
-    this.pi.on('turn_start', () => {
-      this.invalidCompletionCalls.clear();
-    });
-    this.pi.on('message_end', (event) => {
-      if (!this.active) return;
-      const invalid = invalidCompletionCallIds(
-        event.message,
-        WORKFLOW_COMPLETION_TOOL,
-      );
-      if (
-        invalid.size > 0 ||
-        (event.message as { role?: unknown }).role === 'assistant'
-      ) {
-        this.invalidCompletionCalls = invalid;
-      }
-    });
-    this.pi.on('tool_call', (event) => {
-      if (this.suspended) {
-        return {
-          block: true,
-          reason: 'Main-agent workflow step is suspended',
-        };
-      }
-      if (!this.active) {
-        if (event.toolName === WORKFLOW_COMPLETION_TOOL) {
-          return {
-            block: true,
-            reason: 'No main-agent workflow step is active',
-          };
-        }
-        return;
-      }
-      if (this.invalidCompletionCalls.has(event.toolCallId)) {
-        return {
-          block: true,
-          reason: `${WORKFLOW_COMPLETION_TOOL} must be the only tool call in its message`,
-        };
-      }
-      if (event.toolName === WORKFLOW_COMPLETION_TOOL) {
-        freezeToolInput(event.input);
-        return;
-      }
-
-      const authorization = authorizeToolCall(
-        event.toolName,
-        event.input as unknown as Record<string, unknown>,
-        this.active.step,
-        this.pi.getAllTools(),
-        this.active.approvedBashCommands,
-      );
-      if (!authorization.allowed) {
-        return {
-          block: true,
-          reason:
-            authorization.reason ?? 'Tool blocked by main workflow policy',
-        };
-      }
-      freezeToolInput(event.input);
-    });
+  /**
+   * Clears the active step.
+   *
+   * @returns Whether a step was active.
+   */
+  deactivate(): boolean {
+    return this.controller.deactivate();
   }
 
-  private registerCompletionTool(): void {
-    this.pi.registerTool({
-      name: WORKFLOW_COMPLETION_TOOL,
-      label: 'Complete Workflow Step',
-      description: 'Return one validated result from an active workflow step',
-      promptSnippet: 'Complete the active workflow step',
-      promptGuidelines: [
-        'Call workflow_complete_step alone after all active workflow-step work is complete.',
-      ],
-      parameters: WORKFLOW_COMPLETION_PARAMETERS,
-      executionMode: 'sequential',
-      execute: async (_toolCallId, params) => {
-        if (!this.active) {
-          throw new Error('No main-agent workflow step is active');
-        }
-        if (this.pendingResult) {
-          throw new Error('Main-agent workflow step already produced a result');
-        }
-        const result = parseWorkflowStepResult(
-          {
-            version: 1,
-            policyDigest: this.active.policyDigest,
-            outcome: params.outcome,
-            summary: params.summary,
-            ...(params.artifact !== undefined
-              ? { artifact: params.artifact }
-              : {}),
-          },
-          this.active,
-        );
-        this.pendingResult = result;
-        this.pi.setActiveTools([]);
-        return {
-          content: [
-            {
-              type: 'text' as const,
-              text: `Captured workflow step outcome "${result.outcome}".`,
-            },
-          ],
-          details: {
-            workflowId: this.active.workflowId,
-            runId: this.active.runId,
-            stepId: this.active.stepId,
-            outcome: result.outcome,
-          },
-          terminate: true,
-        };
-      },
-    });
+  /**
+   * Clears the active step and blocks tools until released.
+   *
+   * @returns Whether a step was active.
+   */
+  suspend(): boolean {
+    return this.controller.suspend();
+  }
+
+  /** Releases a suspended runtime for future activation. */
+  release(): void {
+    this.controller.release();
   }
 }

package/src/runtime/main-step-state.ts

@@ -0,0 +1,85 @@
+import type { ExtensionContext } from '@earendil-works/pi-coding-agent';
+import type {
+  MainStepExecution,
+  MainStepRuntimeState,
+} from './main-step-runtime-types.ts';
+
+/**
+ * Creates the isolated mutable state captured by one main-step runtime.
+ *
+ * @returns A fresh inactive runtime state.
+ */
+export function createMainStepRuntimeState(): MainStepRuntimeState {
+  return {
+    active: undefined,
+    pendingResult: undefined,
+    invalidCompletionCalls: new Set(),
+    isSuspended: false,
+  };
+}
+
+type ActivateMainStepOptions = {
+  readonly state: MainStepRuntimeState;
+  readonly execution: MainStepExecution;
+};
+
+/**
+ * Activates an execution in a runtime state that currently has no active step.
+ *
+ * @param options - State and execution to activate.
+ * @throws When another main-agent step remains active.
+ */
+export function activateMainStep({
+  state,
+  execution,
+}: ActivateMainStepOptions): void {
+  if (state.active) {
+    throw new Error(
+      `main workflow step "${state.active.stepId}" is still active`,
+    );
+  }
+
+  state.isSuspended = false;
+  state.active = execution;
+  state.pendingResult = undefined;
+  state.invalidCompletionCalls = new Set();
+}
+
+/**
+ * Clears active execution data while preserving the suspension flag.
+ *
+ * @param state - Runtime state to clear.
+ * @returns Whether a step was active.
+ */
+export function deactivateMainStep(state: MainStepRuntimeState): boolean {
+  const wasActive = state.active !== undefined;
+  state.active = undefined;
+  state.pendingResult = undefined;
+  state.invalidCompletionCalls = new Set();
+  return wasActive;
+}
+
+type SettleMainStepOptions = {
+  readonly state: MainStepRuntimeState;
+  readonly context: ExtensionContext;
+};
+
+/**
+ * Removes and settles the active execution with its captured result.
+ *
+ * @param options - Runtime state and extension context for the callback.
+ * @returns The execution's settlement callback result.
+ */
+export function settleMainStep({
+  state,
+  context,
+}: SettleMainStepOptions): Promise<void> | void {
+  const activeExecution = state.active;
+  if (!activeExecution) {
+    return;
+  }
+
+  const result = state.pendingResult;
+  deactivateMainStep(state);
+  return activeExecution.onSettled(result, context);
+}

package/src/runtime/serial-task-queue.ts

@@ -1,21 +1,56 @@
 /**
- * Pi may dispatch extension commands while another command is awaiting I/O.
- * Serialize state-changing commands while allowing the queue to recover after
- * an individual command rejects.
+ * Minimal functional surface for serial task execution.
  */
-export class SerialTaskQueue {
-  private tail: Promise<void>;
+export type SerialTaskQueueController = {
+  /** Enqueues a task and returns its eventual result. */
+  readonly run: <TResult>(task: () => Promise<TResult>) => Promise<TResult>;
+};
 
-  constructor() {
-    this.tail = Promise.resolve();
+const settleTask = async (taskResult: Promise<unknown>): Promise<void> => {
+  try {
+    await taskResult;
+  } catch {
+    // The original promise is returned to the caller; only the queue tail recovers.
   }
+};
+
+/**
+ * Creates a closure-based queue that serializes asynchronous state changes.
+ *
+ * A rejected task does not poison the queue; later tasks still execute.
+ *
+ * @returns A serial task queue controller.
+ */
+export function createSerialTaskQueue(): SerialTaskQueueController {
+  let tail = Promise.resolve();
 
-  run<T>(task: () => Promise<T>): Promise<T> {
-    const result = this.tail.then(task, task);
-    this.tail = result.then(
-      () => undefined,
-      () => undefined,
-    );
+  const run = <TResult>(task: () => Promise<TResult>): Promise<TResult> => {
+    const result = tail.then(task, task);
+    tail = settleTask(result);
     return result;
+  };
+
+  return { run };
+}
+
+/**
+ * Compatibility facade for callers that construct a serial queue with `new`.
+ */
+export class SerialTaskQueue implements SerialTaskQueueController {
+  private readonly controller: SerialTaskQueueController;
+
+  /** Creates an isolated serial task queue. */
+  constructor() {
+    this.controller = createSerialTaskQueue();
+  }
+
+  /**
+   * Enqueues one asynchronous task after all previously submitted tasks.
+   *
+   * @param task - State-changing operation to serialize.
+   * @returns The task result or rejection.
+   */
+  run<TResult>(task: () => Promise<TResult>): Promise<TResult> {
+    return this.controller.run(task);
   }
 }