@wichayutdew/pi-workflows 0.3.0 → 1.0.0

package/src/integrations/subagents/client-delegation.ts

@@ -0,0 +1,181 @@
+import {
+  parseDelegationResponse,
+  parseDelegationUpdate,
+  requestIdOf,
+} from './client-messages.ts';
+import type {
+  ActiveDelegation,
+  DelegateOptions,
+  DelegationTimer,
+  SubagentDelegationClientDependencies,
+  SubagentEventBus,
+} from './client-types.ts';
+import {
+  SUBAGENT_DELEGATION_CANCEL_EVENT,
+  SUBAGENT_DELEGATION_PROTOCOL_VERSION,
+  SUBAGENT_DELEGATION_REQUEST_EVENT,
+  SUBAGENT_DELEGATION_RESPONSE_EVENT,
+  SUBAGENT_DELEGATION_STARTED_EVENT,
+  SUBAGENT_DELEGATION_UPDATE_EVENT,
+} from './protocol-events.ts';
+import type {
+  SubagentDelegationRequest,
+  SubagentDelegationResponse,
+} from './protocol-events.ts';
+
+export const DEFAULT_CLIENT_DEPENDENCIES = {
+  scheduleTimeout: (callback: () => void, timeoutMs: number) =>
+    setTimeout(callback, timeoutMs),
+  cancelTimeout: (timer: DelegationTimer) => {
+    clearTimeout(timer);
+  },
+} as const satisfies SubagentDelegationClientDependencies;
+
+type CreatedDelegation = {
+  readonly active: ActiveDelegation;
+  readonly promise: Promise<SubagentDelegationResponse>;
+  readonly start: () => void;
+};
+
+type CreateDelegationOptions = {
+  readonly events: SubagentEventBus;
+  readonly request: SubagentDelegationRequest;
+  readonly options: DelegateOptions;
+  readonly dependencies: SubagentDelegationClientDependencies;
+  readonly releaseActive: (requestId: string) => void;
+};
+
+function isUnsubscribe(value: unknown): value is () => void {
+  return typeof value === 'function';
+}
+
+/**
+ * Creates one delegation lifecycle without retaining client-level state.
+ */
+export const createDelegation = ({
+  events,
+  request,
+  options,
+  dependencies,
+  releaseActive,
+}: CreateDelegationOptions): CreatedDelegation => {
+  let requestCancellation = (): void => undefined;
+  let resolveTerminal = (): void => undefined;
+  const terminal = new Promise<void>((resolve) => {
+    resolveTerminal = resolve;
+  });
+
+  const promise = new Promise<SubagentDelegationResponse>((resolve, reject) => {
+    let isSettled = false;
+    let isCancellationRequested = false;
+    const subscriptions: Array<() => void> = [];
+
+    const subscribe = (
+      event: string,
+      handler: (data: unknown) => void,
+    ): void => {
+      const unsubscribe = events.on(event, handler);
+      if (isUnsubscribe(unsubscribe)) {
+        subscriptions.push(() => {
+          unsubscribe();
+        });
+      }
+    };
+    const stopLocalWatchers = (): void => {
+      dependencies.cancelTimeout(startTimer);
+      dependencies.cancelTimeout(overallTimer);
+      options.signal?.removeEventListener('abort', abort);
+    };
+    const cleanup = (): void => {
+      stopLocalWatchers();
+      for (const unsubscribe of subscriptions) unsubscribe();
+      releaseActive(request.requestId);
+    };
+    const finish = (
+      result:
+        | { readonly response: SubagentDelegationResponse }
+        | { readonly error: Error },
+    ): void => {
+      if (isSettled) return;
+      isSettled = true;
+      cleanup();
+      if ('response' in result) resolve(result.response);
+      else reject(result.error);
+    };
+    const emitCancel = (): void => {
+      if (isCancellationRequested || isSettled) return;
+      isCancellationRequested = true;
+      events.emit(SUBAGENT_DELEGATION_CANCEL_EVENT, {
+        version: SUBAGENT_DELEGATION_PROTOCOL_VERSION,
+        requestId: request.requestId,
+      });
+    };
+    const failAndCancel = (reason: string): void => {
+      if (isSettled) return;
+      emitCancel();
+      // A local timeout is not proof that the child process terminated.
+      // Retain correlation listeners and ownership until the terminal event.
+      // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition -- emitting cancellation can synchronously settle through the event bus
+      if (isSettled) return;
+      isSettled = true;
+      stopLocalWatchers();
+      reject(new Error(reason));
+    };
+    const abort = (): void => {
+      failAndCancel('subagent delegation was cancelled');
+    };
+    requestCancellation = emitCancel;
+
+    subscribe(SUBAGENT_DELEGATION_STARTED_EVENT, (data) => {
+      if (requestIdOf(data) !== request.requestId) return;
+      dependencies.cancelTimeout(startTimer);
+    });
+    subscribe(SUBAGENT_DELEGATION_UPDATE_EVENT, (data) => {
+      const update = parseDelegationUpdate(data);
+      if (!update || update.requestId !== request.requestId) return;
+      options.onUpdate?.(update);
+    });
+    subscribe(SUBAGENT_DELEGATION_RESPONSE_EVENT, (data) => {
+      const response = parseDelegationResponse(data);
+      if (!response || response.requestId !== request.requestId) return;
+      resolveTerminal();
+      if (isSettled) {
+        cleanup();
+        options.onLateTerminal?.(response);
+        return;
+      }
+      finish({ response });
+    });
+
+    const startTimer = dependencies.scheduleTimeout(() => {
+      failAndCancel(
+        'pi-subagents did not accept the delegation request; verify it is installed and loaded',
+      );
+    }, options.startTimeoutMs ?? 3_000);
+    const overallTimer = dependencies.scheduleTimeout(
+      () => {
+        failAndCancel(
+          'pi-subagents did not settle the delegation request before its deadline',
+        );
+      },
+      (request.timeoutMs ?? 900_000) + 5_000,
+    );
+    startTimer.unref();
+    overallTimer.unref();
+    options.signal?.addEventListener('abort', abort, { once: true });
+  });
+
+  return {
+    active: {
+      requestId: request.requestId,
+      requestCancellation: () => {
+        requestCancellation();
+      },
+      terminal,
+    },
+    promise,
+    start: () => {
+      events.emit(SUBAGENT_DELEGATION_REQUEST_EVENT, request);
+    },
+  };
+};

package/src/integrations/subagents/client-messages.ts

@@ -0,0 +1,66 @@
+import { SUBAGENT_DELEGATION_PROTOCOL_VERSION } from './protocol-events.ts';
+import type {
+  SubagentDelegationResponse,
+  SubagentDelegationStatus,
+  SubagentDelegationUpdate,
+} from './protocol-events.ts';
+
+const DELEGATION_STATUSES: ReadonlySet<string> = new Set([
+  'completed',
+  'failed',
+  'timed_out',
+  'cancelled',
+  'interrupted',
+  'turn_budget_exhausted',
+  'tool_budget_exhausted',
+  'structured_output_failed',
+  'acceptance_failed',
+  'invalid_request',
+  'unavailable_context',
+]);
+
+const isRecord = (value: unknown): value is Record<string, unknown> =>
+  value !== null && typeof value === 'object' && !Array.isArray(value);
+
+const isDelegationStatus = (value: string): value is SubagentDelegationStatus =>
+  DELEGATION_STATUSES.has(value);
+
+const isDelegationResponse = (
+  value: unknown,
+): value is SubagentDelegationResponse =>
+  isRecord(value) &&
+  value.version === SUBAGENT_DELEGATION_PROTOCOL_VERSION &&
+  typeof value.requestId === 'string' &&
+  typeof value.status === 'string' &&
+  isDelegationStatus(value.status);
+
+const isDelegationUpdate = (
+  value: unknown,
+): value is SubagentDelegationUpdate =>
+  isRecord(value) &&
+  value.version === SUBAGENT_DELEGATION_PROTOCOL_VERSION &&
+  typeof value.requestId === 'string';
+
+/**
+ * Reads a request identifier from an untrusted event payload.
+ */
+export const requestIdOf = (value: unknown): string | undefined =>
+  isRecord(value) && typeof value.requestId === 'string'
+    ? value.requestId
+    : undefined;
+
+/**
+ * Validates an untrusted terminal delegation response.
+ */
+export const parseDelegationResponse = (
+  value: unknown,
+): SubagentDelegationResponse | undefined =>
+  isDelegationResponse(value) ? value : undefined;
+
+/**
+ * Validates an untrusted delegation progress update.
+ */
+export const parseDelegationUpdate = (
+  value: unknown,
+): SubagentDelegationUpdate | undefined =>
+  isDelegationUpdate(value) ? value : undefined;

package/src/integrations/subagents/client-types.ts

@@ -0,0 +1,36 @@
+import type {
+  SubagentDelegationResponse,
+  SubagentDelegationUpdate,
+} from './protocol-events.ts';
+
+export type SubagentEventBus = {
+  readonly on: (event: string, handler: (data: unknown) => void) => unknown;
+  readonly emit: (event: string, data: unknown) => void;
+};
+
+export type DelegateOptions = {
+  readonly signal?: AbortSignal;
+  readonly startTimeoutMs?: number;
+  readonly onUpdate?: (update: SubagentDelegationUpdate) => void;
+  /**
+   * Called when a terminal response arrives after the delegate promise already
+   * rejected locally. The child was still potentially alive until this event.
+   */
+  readonly onLateTerminal?: (response: SubagentDelegationResponse) => void;
+};
+
+export type DelegationTimer = ReturnType<typeof setTimeout>;
+
+export type SubagentDelegationClientDependencies = {
+  readonly scheduleTimeout: (
+    callback: () => void,
+    timeoutMs: number,
+  ) => DelegationTimer;
+  readonly cancelTimeout: (timer: DelegationTimer) => void;
+};
+
+export type ActiveDelegation = {
+  readonly requestId: string;
+  readonly requestCancellation: () => void;
+  readonly terminal: Promise<void>;
+};

package/src/integrations/subagents/client.ts

@@ -1,240 +1,148 @@
 import {
-  SUBAGENT_DELEGATION_CANCEL_EVENT,
-  SUBAGENT_DELEGATION_PROTOCOL_VERSION,
-  SUBAGENT_DELEGATION_REQUEST_EVENT,
-  SUBAGENT_DELEGATION_RESPONSE_EVENT,
-  SUBAGENT_DELEGATION_STARTED_EVENT,
-  SUBAGENT_DELEGATION_UPDATE_EVENT,
-  type SubagentDelegationRequest,
-  type SubagentDelegationResponse,
-  type SubagentDelegationStatus,
-  type SubagentDelegationUpdate,
-} from './protocol.ts';
+  createDelegation,
+  DEFAULT_CLIENT_DEPENDENCIES,
+} from './client-delegation.ts';
+import type {
+  ActiveDelegation,
+  DelegateOptions,
+  SubagentDelegationClientDependencies,
+  SubagentEventBus,
+} from './client-types.ts';
+import type {
+  SubagentDelegationRequest,
+  SubagentDelegationResponse,
+} from './protocol-events.ts';
+
+export type {
+  DelegateOptions,
+  SubagentDelegationClientDependencies,
+  SubagentEventBus,
+} from './client-types.ts';
+
+/**
+ * Functional surface used by workflow orchestration.
+ */
+export type SubagentDelegationClientController = {
+  /** Request currently owned by this client, if any. */
+  readonly activeRequestId: string | undefined;
+  /** Starts one correlated delegation. */
+  readonly delegate: (
+    request: SubagentDelegationRequest,
+    options?: DelegateOptions,
+  ) => Promise<SubagentDelegationResponse>;
+  /** Cancels the active delegation and waits for terminal confirmation. */
+  readonly cancelActiveAndWait: (waitMs?: number) => Promise<boolean>;
+};
+
+/**
+ * Creates an isolated subagent delegation controller.
+ *
+ * @param events - Event transport shared with the subagent runtime.
+ * @param dependencies - Timer effects used for cancellation and timeouts.
+ * @returns A controller that owns at most one active delegation.
+ */
+export function createSubagentDelegationClient(
+  events: SubagentEventBus,
+  dependencies: SubagentDelegationClientDependencies = DEFAULT_CLIENT_DEPENDENCIES,
+): SubagentDelegationClientController {
+  let active: ActiveDelegation | undefined;
+
+  const delegate = (
+    request: SubagentDelegationRequest,
+    options: DelegateOptions = {},
+  ): Promise<SubagentDelegationResponse> => {
+    if (active) {
+      return Promise.reject(
+        new Error(`subagent request "${active.requestId}" is still active`),
+      );
+    }
+    if (options.signal?.aborted) {
+      return Promise.reject(new Error('subagent delegation was cancelled'));
+    }
 
-export interface SubagentEventBus {
-  on(event: string, handler: (data: unknown) => void): (() => void) | void;
-  emit(event: string, data: unknown): void;
-}
+    const delegation = createDelegation({
+      events,
+      request,
+      options,
+      dependencies,
+      releaseActive: (requestId) => {
+        if (active?.requestId === requestId) active = undefined;
+      },
+    });
+    active = delegation.active;
+    delegation.start();
+    return delegation.promise;
+  };
 
-export interface DelegateOptions {
-  signal?: AbortSignal;
-  startTimeoutMs?: number;
-  onUpdate?: (update: SubagentDelegationUpdate) => void;
-  /**
-   * Called when a terminal response arrives after the delegate promise already
-   * rejected locally. The child was still potentially alive until this event.
-   */
-  onLateTerminal?: (response: SubagentDelegationResponse) => void;
-}
+  const cancelActiveAndWait = (waitMs = 5_000): Promise<boolean> => {
+    const current = active;
+    if (!current) return Promise.resolve(true);
 
-interface ActiveDelegation {
-  requestId: string;
-  requestCancellation: () => void;
-  terminal: Promise<void>;
+    current.requestCancellation();
+    return new Promise<boolean>((resolve) => {
+      let isFinished = false;
+      const finish = (isConfirmed: boolean): void => {
+        if (isFinished) return;
+        isFinished = true;
+        dependencies.cancelTimeout(timer);
+        resolve(isConfirmed);
+      };
+      const timer = dependencies.scheduleTimeout(() => {
+        finish(false);
+      }, waitMs);
+      void current.terminal.then(() => {
+        finish(true);
+      });
+    });
+  };
+
+  return {
+    get activeRequestId() {
+      return active?.requestId;
+    },
+    delegate,
+    cancelActiveAndWait,
+  };
 }
 
-const DELEGATION_STATUSES = new Set<SubagentDelegationStatus>([
-  'completed',
-  'failed',
-  'timed_out',
-  'cancelled',
-  'interrupted',
-  'turn_budget_exhausted',
-  'tool_budget_exhausted',
-  'structured_output_failed',
-  'acceptance_failed',
-  'invalid_request',
-  'unavailable_context',
-]);
-
-function requestIdOf(value: unknown): string | undefined {
-  if (value === null || typeof value !== 'object') return undefined;
-  const requestId = (value as { requestId?: unknown }).requestId;
-  return typeof requestId === 'string' ? requestId : undefined;
-}
+/**
+ * Coordinates one foreground pi-subagents request at a time.
+ *
+ * Event and timer boundaries are constructor-injected; production defaults
+ * preserve the original runtime behavior.
+ */
+export class SubagentDelegationClient implements SubagentDelegationClientController {
+  readonly #controller: SubagentDelegationClientController;
 
-function parseResponse(value: unknown): SubagentDelegationResponse | undefined {
-  if (value === null || typeof value !== 'object') return undefined;
-  const response = value as Partial<SubagentDelegationResponse>;
-  if (
-    response.version !== SUBAGENT_DELEGATION_PROTOCOL_VERSION ||
-    typeof response.requestId !== 'string' ||
-    typeof response.status !== 'string' ||
-    !DELEGATION_STATUSES.has(response.status as SubagentDelegationStatus)
+  /**
+   * Creates a client over the supplied event and timer boundaries.
+   */
+  constructor(
+    events: SubagentEventBus,
+    dependencies: SubagentDelegationClientDependencies = DEFAULT_CLIENT_DEPENDENCIES,
   ) {
-    return undefined;
-  }
-  return response as SubagentDelegationResponse;
-}
-
-function parseUpdate(value: unknown): SubagentDelegationUpdate | undefined {
-  if (value === null || typeof value !== 'object') return undefined;
-  const update = value as Partial<SubagentDelegationUpdate>;
-  if (
-    update.version !== SUBAGENT_DELEGATION_PROTOCOL_VERSION ||
-    typeof update.requestId !== 'string'
-  ) {
-    return undefined;
-  }
-  return update as SubagentDelegationUpdate;
-}
-
-export class SubagentDelegationClient {
-  private readonly events: SubagentEventBus;
-  private active: ActiveDelegation | undefined;
-
-  constructor(events: SubagentEventBus) {
-    this.events = events;
+    this.#controller = createSubagentDelegationClient(events, dependencies);
   }
 
+  /** Returns the request currently owned by this client, if any. */
   get activeRequestId(): string | undefined {
-    return this.active?.requestId;
+    return this.#controller.activeRequestId;
   }
 
+  /**
+   * Starts a correlated delegation and resolves on its terminal event.
+   */
   delegate(
     request: SubagentDelegationRequest,
     options: DelegateOptions = {},
   ): Promise<SubagentDelegationResponse> {
-    if (this.active) {
-      return Promise.reject(
-        new Error(
-          `subagent request "${this.active.requestId}" is still active`,
-        ),
-      );
-    }
-    if (options.signal?.aborted) {
-      return Promise.reject(new Error('subagent delegation was cancelled'));
-    }
-
-    let start!: () => void;
-    let requestCancellation!: () => void;
-    let resolveTerminal!: () => void;
-    const terminal = new Promise<void>((resolve) => {
-      resolveTerminal = resolve;
-    });
-    const delegation = new Promise<SubagentDelegationResponse>(
-      (resolve, reject) => {
-        let settled = false;
-        let cancellationRequested = false;
-        const subscriptions: Array<() => void> = [];
-        const startTimeoutMs = options.startTimeoutMs ?? 3_000;
-        const overallTimeoutMs = (request.timeoutMs ?? 900_000) + 5_000;
-
-        const subscribe = (
-          event: string,
-          handler: (data: unknown) => void,
-        ): void => {
-          const unsubscribe = this.events.on(event, handler);
-          if (typeof unsubscribe === 'function')
-            subscriptions.push(unsubscribe);
-        };
-        const stopLocalWatchers = (): void => {
-          clearTimeout(startTimer);
-          clearTimeout(overallTimer);
-          options.signal?.removeEventListener('abort', abort);
-        };
-        const cleanup = (): void => {
-          stopLocalWatchers();
-          for (const unsubscribe of subscriptions) unsubscribe();
-          if (this.active?.requestId === request.requestId)
-            this.active = undefined;
-        };
-        const finish = (
-          result: { response: SubagentDelegationResponse } | { error: Error },
-        ): void => {
-          if (settled) return;
-          settled = true;
-          cleanup();
-          if ('response' in result) resolve(result.response);
-          else reject(result.error);
-        };
-        const emitCancel = (): void => {
-          if (cancellationRequested || settled) return;
-          cancellationRequested = true;
-          this.events.emit(SUBAGENT_DELEGATION_CANCEL_EVENT, {
-            version: SUBAGENT_DELEGATION_PROTOCOL_VERSION,
-            requestId: request.requestId,
-          });
-        };
-        const failAndCancel = (reason: string): void => {
-          if (settled) return;
-          emitCancel();
-          // A local timeout is not proof that the child process terminated. Reject
-          // the caller, but retain correlation listeners and active ownership
-          // until pi-subagents emits the terminal response.
-          if (settled) return;
-          settled = true;
-          stopLocalWatchers();
-          reject(new Error(reason));
-        };
-        const abort = (): void => {
-          failAndCancel('subagent delegation was cancelled');
-        };
-        requestCancellation = emitCancel;
-
-        subscribe(SUBAGENT_DELEGATION_STARTED_EVENT, (data) => {
-          if (requestIdOf(data) !== request.requestId) return;
-          clearTimeout(startTimer);
-        });
-        subscribe(SUBAGENT_DELEGATION_UPDATE_EVENT, (data) => {
-          const update = parseUpdate(data);
-          if (!update || update.requestId !== request.requestId) return;
-          options.onUpdate?.(update);
-        });
-        subscribe(SUBAGENT_DELEGATION_RESPONSE_EVENT, (data) => {
-          const response = parseResponse(data);
-          if (!response || response.requestId !== request.requestId) return;
-          resolveTerminal();
-          if (settled) {
-            cleanup();
-            options.onLateTerminal?.(response);
-            return;
-          }
-          finish({ response });
-        });
-
-        const startTimer = setTimeout(() => {
-          failAndCancel(
-            'pi-subagents did not accept the delegation request; verify it is installed and loaded',
-          );
-        }, startTimeoutMs);
-        const overallTimer = setTimeout(() => {
-          failAndCancel(
-            'pi-subagents did not settle the delegation request before its deadline',
-          );
-        }, overallTimeoutMs);
-        startTimer.unref?.();
-        overallTimer.unref?.();
-
-        options.signal?.addEventListener('abort', abort, { once: true });
-        start = () =>
-          this.events.emit(SUBAGENT_DELEGATION_REQUEST_EVENT, request);
-      },
-    );
-
-    this.active = {
-      requestId: request.requestId,
-      requestCancellation,
-      terminal,
-    };
-    start();
-    return delegation;
+    return this.#controller.delegate(request, options);
   }
 
-  async cancelActiveAndWait(waitMs = 5_000): Promise<boolean> {
-    const active = this.active;
-    if (!active) return true;
-    active.requestCancellation();
-    return new Promise<boolean>((resolve) => {
-      let finished = false;
-      const finish = (confirmed: boolean): void => {
-        if (finished) return;
-        finished = true;
-        clearTimeout(timer);
-        resolve(confirmed);
-      };
-      const timer = setTimeout(() => finish(false), waitMs);
-      void active.terminal.then(() => finish(true));
-    });
+  /**
+   * Requests cancellation and waits briefly for terminal confirmation.
+   */
+  cancelActiveAndWait(waitMs = 5_000): Promise<boolean> {
+    return this.#controller.cancelActiveAndWait(waitMs);
   }
 }

package/src/integrations/subagents/delegated-result.ts

@@ -0,0 +1,31 @@
+import { parseWorkflowStepResult } from '../../runtime/step-result.ts';
+import type { WorkflowStepResult } from '../../runtime/step-result.ts';
+import type { ChildStepPolicy } from './child-policy-types.ts';
+
+export type DelegatedStepResult = WorkflowStepResult;
+
+/**
+ * Validates a child completion value against its delegated step policy.
+ *
+ * @throws When the completion value violates the delegated step contract.
+ */
+export const parseDelegatedStepResult = (
+  value: unknown,
+  policy: ChildStepPolicy,
+): DelegatedStepResult => {
+  try {
+    return parseWorkflowStepResult(value, {
+      policyDigest: policy.policyDigest,
+      outcomes: [...policy.outcomes],
+      summaryMaxChars: policy.summaryMaxChars,
+      ...(policy.gateSubmitOutcome
+        ? { gateSubmitOutcome: policy.gateSubmitOutcome }
+        : {}),
+    });
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    throw new Error(message.replaceAll('workflow step', 'delegated step'), {
+      cause: error,
+    });
+  }
+};