@wichayutdew/pi-workflows 0.2.3 → 1.0.0

package/src/index.ts

@@ -1,19 +1,81 @@
 import type { ExtensionAPI } from '@earendil-works/pi-coding-agent';
+import type { KeyId } from '@earendil-works/pi-tui';
 import { defaultUserWorkflowDirectory, loadSettings } from './config/load.ts';
 import { WorkflowHarness } from './harness.ts';
 import { registerSubagentChildRuntime } from './integrations/subagents/child-runtime.ts';
 import { isSubagentRuntimeName } from './integrations/subagents/protocol.ts';
 
-export default async function piWorkflowsExtension(
-  pi: ExtensionAPI,
-): Promise<void> {
-  if (process.env.PI_SUBAGENT_CHILD === '1') {
-    const childAgent = process.env.PI_SUBAGENT_CHILD_AGENT?.trim();
-    if (isSubagentRuntimeName(childAgent)) {
-      registerSubagentChildRuntime(pi, { childAgent });
+/**
+ * Asynchronous entry point accepted by Pi's extension loader.
+ */
+export type PiWorkflowsExtension = (pi: ExtensionAPI) => Promise<void>;
+
+/**
+ * Process-role information used during extension registration.
+ */
+export type PiWorkflowsRuntimeEnvironment = {
+  readonly isSubagentChild: boolean;
+  readonly childAgent: string | undefined;
+};
+
+/**
+ * External effects required to create the extension entry point.
+ */
+export type PiWorkflowsExtensionDependencies = {
+  readonly loadSettings: typeof loadSettings;
+  readonly userWorkflowDirectory: () => string;
+  readonly runtimeEnvironment: () => PiWorkflowsRuntimeEnvironment;
+  readonly isSubagentRuntimeName: typeof isSubagentRuntimeName;
+  readonly registerChildRuntime: (pi: ExtensionAPI, childAgent: string) => void;
+  readonly createHarness: (pi: ExtensionAPI, statusShortcut: KeyId) => void;
+};
+
+const DEFAULT_DEPENDENCIES = {
+  loadSettings,
+  userWorkflowDirectory: defaultUserWorkflowDirectory,
+  runtimeEnvironment: (): PiWorkflowsRuntimeEnvironment => ({
+    isSubagentChild: process.env.PI_SUBAGENT_CHILD === '1',
+    childAgent: process.env.PI_SUBAGENT_CHILD_AGENT?.trim(),
+  }),
+  isSubagentRuntimeName,
+  registerChildRuntime: (pi, childAgent): void => {
+    registerSubagentChildRuntime(pi, { childAgent });
+  },
+  createHarness: (pi, statusShortcut): void => {
+    new WorkflowHarness(pi, statusShortcut);
+  },
+} as const satisfies PiWorkflowsExtensionDependencies;
+
+/**
+ * Creates the Pi extension entry point from explicit environment and runtime
+ * dependencies.
+ *
+ * @param dependencies - Configuration and runtime effects for the extension.
+ * @returns An asynchronous Pi extension factory.
+ */
+export function createPiWorkflowsExtension(
+  dependencies: PiWorkflowsExtensionDependencies,
+): PiWorkflowsExtension {
+  return async (pi): Promise<void> => {
+    const environment = dependencies.runtimeEnvironment();
+
+    if (environment.isSubagentChild) {
+      if (dependencies.isSubagentRuntimeName(environment.childAgent)) {
+        dependencies.registerChildRuntime(pi, environment.childAgent);
+      }
+      return;
     }
-    return;
-  }
-  const { settings } = await loadSettings(defaultUserWorkflowDirectory());
-  new WorkflowHarness(pi, settings.statusShortcut);
+
+    const { settings } = await dependencies.loadSettings(
+      dependencies.userWorkflowDirectory(),
+    );
+    dependencies.createHarness(pi, settings.statusShortcut);
+  };
 }
+
+/**
+ * Registers the workflow harness or delegated child policy runtime with Pi.
+ */
+const piWorkflowsExtension = createPiWorkflowsExtension(DEFAULT_DEPENDENCIES);
+
+export default piWorkflowsExtension;

package/src/integrations/plannotator-requests.ts

@@ -0,0 +1,127 @@
+import {
+  normalizePlannotatorStartResponse,
+  normalizePlannotatorStatusResponse,
+} from './plannotator-responses.ts';
+import type {
+  EventBusLike,
+  PlannotatorStartResponse,
+  PlannotatorStatusResponse,
+} from './plannotator-types.ts';
+
+export const PLANNOTATOR_REQUEST_CHANNEL = 'plannotator:request';
+export const PLANNOTATOR_RESULT_CHANNEL = 'plannotator:review-result';
+
+type TimeoutHandle = ReturnType<typeof setTimeout>;
+
+export type PlannotatorDependencies = {
+  readonly scheduleTimeout: (
+    callback: () => void,
+    timeoutMs: number,
+  ) => TimeoutHandle;
+  readonly cancelTimeout: (handle: TimeoutHandle) => void;
+};
+
+const DEFAULT_DEPENDENCIES = {
+  scheduleTimeout: (callback: () => void, timeoutMs: number) =>
+    setTimeout(callback, timeoutMs),
+  cancelTimeout: (handle: TimeoutHandle) => {
+    clearTimeout(handle);
+  },
+} as const satisfies PlannotatorDependencies;
+
+type RequestResponseOptions<TResponse> = {
+  readonly events: EventBusLike;
+  readonly request: Readonly<Record<string, unknown>>;
+  readonly timeoutMs: number;
+  readonly timeoutResponse: TResponse;
+  readonly normalize: (response: unknown) => TResponse;
+  readonly dependencies: PlannotatorDependencies;
+};
+
+const requestResponse = <TResponse>({
+  events,
+  request,
+  timeoutMs,
+  timeoutResponse,
+  normalize,
+  dependencies,
+}: RequestResponseOptions<TResponse>): Promise<TResponse> =>
+  new Promise((resolve) => {
+    let isSettled = false;
+    const finish = (response: unknown): void => {
+      if (isSettled) return;
+      isSettled = true;
+      dependencies.cancelTimeout(timer);
+      resolve(normalize(response));
+    };
+    const timer = dependencies.scheduleTimeout(() => {
+      finish(timeoutResponse);
+    }, timeoutMs);
+    timer.unref();
+
+    events.emit(PLANNOTATOR_REQUEST_CHANNEL, {
+      ...request,
+      respond: finish,
+    });
+  });
+
+/**
+ * Requests a new Plannotator plan review through the injected event bus.
+ *
+ * @param dependencies Timer boundaries, injectable for deterministic callers.
+ */
+export const requestPlannotatorReview = (
+  events: EventBusLike,
+  requestId: string,
+  content: string,
+  origin: string,
+  timeoutMs: number,
+  dependencies: PlannotatorDependencies = DEFAULT_DEPENDENCIES,
+): Promise<PlannotatorStartResponse> =>
+  requestResponse({
+    events,
+    request: {
+      requestId,
+      action: 'plan-review',
+      payload: {
+        planContent: content,
+        origin,
+      },
+    },
+    timeoutMs,
+    timeoutResponse: {
+      status: 'unavailable',
+      error: `Plannotator did not respond within ${timeoutMs}ms`,
+    },
+    normalize: normalizePlannotatorStartResponse,
+    dependencies,
+  });
+
+/**
+ * Requests the current durable status for a Plannotator review.
+ *
+ * @param dependencies Timer boundaries, injectable for deterministic callers.
+ */
+export const requestPlannotatorReviewStatus = (
+  events: EventBusLike,
+  requestId: string,
+  reviewId: string,
+  timeoutMs: number,
+  dependencies: PlannotatorDependencies = DEFAULT_DEPENDENCIES,
+): Promise<PlannotatorStatusResponse> =>
+  requestResponse({
+    events,
+    request: {
+      requestId,
+      action: 'review-status',
+      payload: { reviewId },
+    },
+    timeoutMs,
+    timeoutResponse: {
+      status: 'unavailable',
+      error: `Plannotator did not respond within ${timeoutMs}ms`,
+    },
+    normalize: (response) =>
+      normalizePlannotatorStatusResponse(response, reviewId),
+    dependencies,
+  });

package/src/integrations/plannotator-responses.ts

@@ -0,0 +1,141 @@
+import type {
+  PlannotatorReviewResult,
+  PlannotatorStartResponse,
+  PlannotatorStatusResponse,
+} from './plannotator-types.ts';
+
+const isRecord = (value: unknown): value is Record<string, unknown> =>
+  value !== null && typeof value === 'object' && !Array.isArray(value);
+
+const errorText = (
+  value: Readonly<Record<string, unknown>>,
+  fallback: string,
+): string =>
+  typeof value.error === 'string' && value.error.trim()
+    ? value.error
+    : fallback;
+
+/**
+ * Normalizes an untrusted response to a Plannotator start request.
+ */
+export const normalizePlannotatorStartResponse = (
+  value: unknown,
+): PlannotatorStartResponse => {
+  if (!isRecord(value)) {
+    return {
+      status: 'error',
+      error: 'Plannotator returned an invalid response',
+    };
+  }
+  if (value.status === 'unavailable') {
+    return {
+      status: 'unavailable',
+      error: errorText(value, 'Plannotator is unavailable'),
+    };
+  }
+  if (value.status === 'error') {
+    return {
+      status: 'error',
+      error: errorText(value, 'Plannotator failed'),
+    };
+  }
+
+  const result = isRecord(value.result) ? value.result : undefined;
+  if (
+    value.status === 'handled' &&
+    result?.status === 'pending' &&
+    typeof result.reviewId === 'string'
+  ) {
+    return {
+      status: 'handled',
+      result: { status: 'pending', reviewId: result.reviewId },
+    };
+  }
+  return {
+    status: 'error',
+    error: 'Plannotator returned an invalid start result',
+  };
+};
+
+/**
+ * Normalizes an untrusted response to a Plannotator status request.
+ */
+export const normalizePlannotatorStatusResponse = (
+  value: unknown,
+  requestedReviewId: string,
+): PlannotatorStatusResponse => {
+  if (!isRecord(value)) {
+    return {
+      status: 'error',
+      error: 'Plannotator returned an invalid response',
+    };
+  }
+  if (value.status === 'unavailable') {
+    return {
+      status: 'unavailable',
+      error: errorText(value, 'Plannotator is unavailable'),
+    };
+  }
+  if (value.status === 'error') {
+    return {
+      status: 'error',
+      error: errorText(value, 'Plannotator failed'),
+    };
+  }
+
+  const result = isRecord(value.result) ? value.result : undefined;
+  if (value.status !== 'handled' || !result) {
+    return {
+      status: 'error',
+      error: 'Plannotator returned an invalid status result',
+    };
+  }
+  if (result.status === 'pending' || result.status === 'missing') {
+    return { status: 'handled', result: { status: result.status } };
+  }
+  if (
+    result.status === 'completed' &&
+    typeof result.reviewId === 'string' &&
+    typeof result.approved === 'boolean'
+  ) {
+    if (result.reviewId !== requestedReviewId) {
+      return {
+        status: 'error',
+        error: 'Plannotator returned a result for a different review',
+      };
+    }
+    return {
+      status: 'handled',
+      result: {
+        status: 'completed',
+        reviewId: result.reviewId,
+        approved: result.approved,
+        feedback: typeof result.feedback === 'string' ? result.feedback : '',
+      },
+    };
+  }
+  return {
+    status: 'error',
+    error: 'Plannotator returned an invalid status result',
+  };
+};
+
+/**
+ * Parses a pushed Plannotator review result.
+ */
+export const parsePlannotatorResult = (
+  value: unknown,
+): PlannotatorReviewResult | undefined => {
+  if (!isRecord(value)) return undefined;
+  if (
+    typeof value.reviewId !== 'string' ||
+    typeof value.approved !== 'boolean'
+  ) {
+    return undefined;
+  }
+  return {
+    reviewId: value.reviewId,
+    approved: value.approved,
+    feedback: typeof value.feedback === 'string' ? value.feedback : '',
+  };
+};

package/src/integrations/plannotator-types.ts

@@ -0,0 +1,44 @@
+export type EventBusLike = {
+  readonly emit: (channel: string, data: unknown) => void;
+  readonly on: (
+    channel: string,
+    handler: (data: unknown) => void,
+  ) => () => void;
+};
+
+export type PlannotatorReviewStarted = {
+  readonly status: 'pending';
+  readonly reviewId: string;
+};
+
+export type PlannotatorStartResponse =
+  | {
+      readonly status: 'handled';
+      readonly result: PlannotatorReviewStarted;
+    }
+  | { readonly status: 'unavailable'; readonly error?: string }
+  | { readonly status: 'error'; readonly error: string };
+
+export type PlannotatorReviewStatus =
+  | { readonly status: 'pending' }
+  | {
+      readonly status: 'completed';
+      readonly reviewId: string;
+      readonly approved: boolean;
+      readonly feedback: string;
+    }
+  | { readonly status: 'missing' };
+
+export type PlannotatorStatusResponse =
+  | {
+      readonly status: 'handled';
+      readonly result: PlannotatorReviewStatus;
+    }
+  | { readonly status: 'unavailable'; readonly error?: string }
+  | { readonly status: 'error'; readonly error: string };
+
+export type PlannotatorReviewResult = {
+  readonly reviewId: string;
+  readonly approved: boolean;
+  readonly feedback: string;
+};

package/src/integrations/plannotator.ts

@@ -1,235 +1,16 @@
-export const PLANNOTATOR_REQUEST_CHANNEL = 'plannotator:request';
-export const PLANNOTATOR_RESULT_CHANNEL = 'plannotator:review-result';
-
-export interface EventBusLike {
-  emit(channel: string, data: unknown): void;
-  on(channel: string, handler: (data: unknown) => void): () => void;
-}
-
-export interface PlannotatorReviewStarted {
-  status: 'pending';
-  reviewId: string;
-}
-
-export type PlannotatorStartResponse =
-  | { status: 'handled'; result: PlannotatorReviewStarted }
-  | { status: 'unavailable'; error?: string }
-  | { status: 'error'; error: string };
-
-export type PlannotatorReviewStatus =
-  | { status: 'pending' }
-  | {
-      status: 'completed';
-      reviewId: string;
-      approved: boolean;
-      feedback: string;
-    }
-  | { status: 'missing' };
-
-export type PlannotatorStatusResponse =
-  | { status: 'handled'; result: PlannotatorReviewStatus }
-  | { status: 'unavailable'; error?: string }
-  | { status: 'error'; error: string };
-
-export interface PlannotatorReviewResult {
-  reviewId: string;
-  approved: boolean;
-  feedback: string;
-}
-
-function errorText(value: Record<string, unknown>, fallback: string): string {
-  return typeof value.error === 'string' && value.error.trim()
-    ? value.error
-    : fallback;
-}
-
-function normalizeStartResponse(value: unknown): PlannotatorStartResponse {
-  if (value === null || typeof value !== 'object') {
-    return {
-      status: 'error',
-      error: 'Plannotator returned an invalid response',
-    };
-  }
-  const response = value as Record<string, unknown>;
-  if (response.status === 'unavailable') {
-    return {
-      status: 'unavailable',
-      error: errorText(response, 'Plannotator is unavailable'),
-    };
-  }
-  if (response.status === 'error') {
-    return {
-      status: 'error',
-      error: errorText(response, 'Plannotator failed'),
-    };
-  }
-  const result =
-    response.result !== null && typeof response.result === 'object'
-      ? (response.result as Record<string, unknown>)
-      : undefined;
-  if (
-    response.status === 'handled' &&
-    result?.status === 'pending' &&
-    typeof result.reviewId === 'string'
-  ) {
-    return {
-      status: 'handled',
-      result: { status: 'pending', reviewId: result.reviewId },
-    };
-  }
-  return {
-    status: 'error',
-    error: 'Plannotator returned an invalid start result',
-  };
-}
-
-function normalizeStatusResponse(
-  value: unknown,
-  requestedReviewId: string,
-): PlannotatorStatusResponse {
-  if (value === null || typeof value !== 'object') {
-    return {
-      status: 'error',
-      error: 'Plannotator returned an invalid response',
-    };
-  }
-  const response = value as Record<string, unknown>;
-  if (response.status === 'unavailable') {
-    return {
-      status: 'unavailable',
-      error: errorText(response, 'Plannotator is unavailable'),
-    };
-  }
-  if (response.status === 'error') {
-    return {
-      status: 'error',
-      error: errorText(response, 'Plannotator failed'),
-    };
-  }
-  const result =
-    response.result !== null && typeof response.result === 'object'
-      ? (response.result as Record<string, unknown>)
-      : undefined;
-  if (response.status !== 'handled' || !result) {
-    return {
-      status: 'error',
-      error: 'Plannotator returned an invalid status result',
-    };
-  }
-  if (result.status === 'pending' || result.status === 'missing') {
-    return { status: 'handled', result: { status: result.status } };
-  }
-  if (
-    result.status === 'completed' &&
-    typeof result.reviewId === 'string' &&
-    typeof result.approved === 'boolean'
-  ) {
-    if (result.reviewId !== requestedReviewId) {
-      return {
-        status: 'error',
-        error: 'Plannotator returned a result for a different review',
-      };
-    }
-    return {
-      status: 'handled',
-      result: {
-        status: 'completed',
-        reviewId: result.reviewId,
-        approved: result.approved,
-        feedback: typeof result.feedback === 'string' ? result.feedback : '',
-      },
-    };
-  }
-  return {
-    status: 'error',
-    error: 'Plannotator returned an invalid status result',
-  };
-}
-
-export function parsePlannotatorResult(
-  value: unknown,
-): PlannotatorReviewResult | undefined {
-  if (value === null || typeof value !== 'object') return undefined;
-  const result = value as Record<string, unknown>;
-  if (
-    typeof result.reviewId !== 'string' ||
-    typeof result.approved !== 'boolean'
-  ) {
-    return undefined;
-  }
-  return {
-    reviewId: result.reviewId,
-    approved: result.approved,
-    feedback: typeof result.feedback === 'string' ? result.feedback : '',
-  };
-}
-
-export function requestPlannotatorReview(
-  events: EventBusLike,
-  requestId: string,
-  content: string,
-  origin: string,
-  timeoutMs: number,
-): Promise<PlannotatorStartResponse> {
-  return new Promise((resolve) => {
-    let settled = false;
-    const finish = (response: unknown) => {
-      if (settled) return;
-      settled = true;
-      clearTimeout(timer);
-      resolve(normalizeStartResponse(response));
-    };
-    const timer = setTimeout(
-      () =>
-        finish({
-          status: 'unavailable',
-          error: `Plannotator did not respond within ${timeoutMs}ms`,
-        }),
-      timeoutMs,
-    );
-    timer.unref?.();
-
-    events.emit(PLANNOTATOR_REQUEST_CHANNEL, {
-      requestId,
-      action: 'plan-review',
-      payload: {
-        planContent: content,
-        origin,
-      },
-      respond: finish,
-    });
-  });
-}
-
-export function requestPlannotatorReviewStatus(
-  events: EventBusLike,
-  requestId: string,
-  reviewId: string,
-  timeoutMs: number,
-): Promise<PlannotatorStatusResponse> {
-  return new Promise((resolve) => {
-    let settled = false;
-    const finish = (response: unknown) => {
-      if (settled) return;
-      settled = true;
-      clearTimeout(timer);
-      resolve(normalizeStatusResponse(response, reviewId));
-    };
-    const timer = setTimeout(
-      () =>
-        finish({
-          status: 'unavailable',
-          error: `Plannotator did not respond within ${timeoutMs}ms`,
-        }),
-      timeoutMs,
-    );
-    timer.unref?.();
-
-    events.emit(PLANNOTATOR_REQUEST_CHANNEL, {
-      requestId,
-      action: 'review-status',
-      payload: { reviewId },
-      respond: finish,
-    });
-  });
-}
+export {
+  PLANNOTATOR_REQUEST_CHANNEL,
+  PLANNOTATOR_RESULT_CHANNEL,
+  requestPlannotatorReview,
+  requestPlannotatorReviewStatus,
+} from './plannotator-requests.ts';
+export type { PlannotatorDependencies } from './plannotator-requests.ts';
+export { parsePlannotatorResult } from './plannotator-responses.ts';
+export type {
+  EventBusLike,
+  PlannotatorReviewResult,
+  PlannotatorReviewStarted,
+  PlannotatorReviewStatus,
+  PlannotatorStartResponse,
+  PlannotatorStatusResponse,
+} from './plannotator-types.ts';