@wichayutdew/pi-workflows 2.5.1 → 2.7.0

package/src/integrations/subagents/client.ts

@@ -1,51 +1,188 @@
-import {
-  createDelegation,
-  DEFAULT_CLIENT_DEPENDENCIES,
-} from './client-delegation.ts';
-import type {
-  ActiveDelegation,
-  DelegateOptions,
-  SubagentDelegationClientDependencies,
-  SubagentEventBus,
-} from './client-types.ts';
+import { spawn, type ChildProcess } from 'node:child_process';
+import { StringDecoder } from 'node:string_decoder';
 import type {
   SubagentDelegationRequest,
   SubagentDelegationResponse,
+  SubagentDelegationUpdate,
 } from './protocol-events.ts';
 
-export type {
-  DelegateOptions,
-  SubagentDelegationClientDependencies,
-  SubagentEventBus,
-} from './client-types.ts';
+export type DelegateOptions = {
+  readonly signal?: AbortSignal;
+  readonly onUpdate?: (update: { readonly requestId: string }) => void;
+  readonly onLateTerminal?: (response: SubagentDelegationResponse) => void;
+};
 
-/**
- * Functional surface used by workflow orchestration.
- */
+/** A pi-workflows-owned foreground Pi process. */
 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 type DirectWorkerSpawn = (
+  command: string,
+  args: Array<string>,
+  options: {
+    readonly cwd: string;
+    readonly env: NodeJS.ProcessEnv;
+    readonly stdio: ['ignore', 'pipe', 'pipe'];
+  },
+) => ChildProcess & {
+  readonly stdout: NonNullable<ChildProcess['stdout']>;
+  readonly stderr: NonNullable<ChildProcess['stderr']>;
+};
+
+export const directWorkerCommand = (
+  request: SubagentDelegationRequest,
+): ReadonlyArray<string> => [
+  '--no-session',
+  '--mode',
+  'json',
+  ...(request.model ? ['--model', request.model] : []),
+  ...(request.thinking ? ['--thinking', request.thinking] : []),
+  '--print',
+  request.task,
+];
+
+export function directWorkerResponse(
+  request: SubagentDelegationRequest,
+  code: number | null,
+  signal: NodeJS.Signals | null,
+  stderr: string,
+): SubagentDelegationResponse {
+  const status = code === 0 ? 'completed' : signal ? 'cancelled' : 'failed';
+  return {
+    requestId: request.requestId,
+    agent: request.agent,
+    status,
+    ...(code === null ? {} : { exitCode: code }),
+    ...(status !== 'completed' && stderr.trim()
+      ? { error: stderr.trim().slice(-4_000) }
+      : {}),
+  };
+}
+
+type WorkerJsonEvent = {
+  readonly type?: unknown;
+  readonly toolName?: unknown;
+  readonly args?: unknown;
+  readonly message?: { readonly role?: unknown };
+  readonly assistantMessageEvent?: {
+    readonly type?: unknown;
+    readonly delta?: unknown;
+  };
+};
+
+type WorkerProgress = {
+  readonly toolCount: number;
+  readonly responseText: string;
+  readonly update?: SubagentDelegationUpdate;
+};
+
+const MAX_PROGRESS_DETAIL_CHARS = 480;
+const SECRET_KEY = /authorization|cookie|password|secret|token|api[-_]?key/i;
+
+function redactProgressValue(value: unknown, key = ''): unknown {
+  if (SECRET_KEY.test(key)) return '[redacted]';
+  if (typeof value === 'string') {
+    return value.length > MAX_PROGRESS_DETAIL_CHARS
+      ? `${value.slice(0, MAX_PROGRESS_DETAIL_CHARS - 1)}…`
+      : value;
+  }
+  if (Array.isArray(value))
+    return value.map((item) => redactProgressValue(item));
+  if (value && typeof value === 'object') {
+    return Object.fromEntries(
+      Object.entries(value).map(([entryKey, entryValue]) => [
+        entryKey,
+        redactProgressValue(entryValue, entryKey),
+      ]),
+    );
+  }
+  return value;
+}
+
+function formatToolCall(toolName: string, args: unknown): string {
+  const rendered = JSON.stringify(redactProgressValue(args));
+  return `call ${toolName} ${rendered}`.slice(0, MAX_PROGRESS_DETAIL_CHARS);
+}
+
+/** Converts one Pi JSONL event into safe, operator-visible worker progress. */
+export function workerProgressFromJsonLine(
+  line: string,
+  requestId: string,
+  toolCount: number,
+  responseText = '',
+): WorkerProgress {
+  let event: WorkerJsonEvent;
+  try {
+    const parsed: unknown = JSON.parse(line);
+    if (typeof parsed !== 'object' || parsed === null)
+      return { toolCount, responseText };
+    event = parsed;
+  } catch {
+    return { toolCount, responseText };
+  }
+  if (event.type === 'agent_start') {
+    return {
+      toolCount,
+      responseText,
+      update: { requestId, activity: 'thinking', toolCount },
+    };
+  }
+  if (event.type === 'message_start' && event.message?.role === 'assistant') {
+    return { toolCount, responseText: '' };
+  }
+  if (
+    event.type === 'message_update' &&
+    event.assistantMessageEvent?.type === 'text_delta' &&
+    typeof event.assistantMessageEvent.delta === 'string'
+  ) {
+    const nextResponseText =
+      `${responseText}${event.assistantMessageEvent.delta}`.slice(
+        -MAX_PROGRESS_DETAIL_CHARS,
+      );
+    return {
+      toolCount,
+      responseText: nextResponseText,
+      update: {
+        requestId,
+        activity: 'responding',
+        detail: `response: ${nextResponseText}`,
+        toolCount,
+      },
+    };
+  }
+  if (
+    (event.type === 'tool_execution_start' ||
+      event.type === 'tool_execution_update') &&
+    typeof event.toolName === 'string'
+  ) {
+    const nextToolCount =
+      event.type === 'tool_execution_start' ? toolCount + 1 : toolCount;
+    return {
+      toolCount: nextToolCount,
+      responseText,
+      update: {
+        requestId,
+        currentTool: event.toolName,
+        ...(event.type === 'tool_execution_start'
+          ? { detail: formatToolCall(event.toolName, event.args) }
+          : {}),
+        toolCount: nextToolCount,
+      },
+    };
+  }
+  return { toolCount, responseText };
+}
+
 export function createSubagentDelegationClient(
-  events: SubagentEventBus,
-  dependencies: SubagentDelegationClientDependencies = DEFAULT_CLIENT_DEPENDENCIES,
+  spawnWorker: DirectWorkerSpawn = spawn,
 ): SubagentDelegationClientController {
-  let active: ActiveDelegation | undefined;
+  let active: { requestId: string; process: ChildProcess } | undefined;
 
   const delegate = (
     request: SubagentDelegationRequest,
@@ -53,45 +190,67 @@ export function createSubagentDelegationClient(
   ): Promise<SubagentDelegationResponse> => {
     if (active) {
       return Promise.reject(
-        new Error(`subagent request "${active.requestId}" is still active`),
+        new Error(`workflow worker "${active.requestId}" is still active`),
       );
     }
     if (options.signal?.aborted) {
-      return Promise.reject(new Error('subagent delegation was cancelled'));
+      return Promise.reject(new Error('workflow worker was cancelled'));
     }
-
-    const delegation = createDelegation({
-      events,
-      request,
-      options,
-      dependencies,
-      releaseActive: (requestId) => {
-        if (active?.requestId === requestId) active = undefined;
-      },
-    });
-    active = delegation.active;
-    delegation.start();
-    return delegation.promise;
-  };
-
-  const cancelActiveAndWait = (waitMs = 5_000): Promise<boolean> => {
-    const current = active;
-    if (!current) return Promise.resolve(true);
-
-    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);
+    return new Promise((resolve, reject) => {
+      const child = spawnWorker('pi', [...directWorkerCommand(request)], {
+        cwd: request.cwd,
+        env: {
+          ...process.env,
+          PI_WORKFLOWS_CHILD: '1',
+          PI_WORKFLOWS_CHILD_AGENT: request.agent,
+        },
+        stdio: ['ignore', 'pipe', 'pipe'],
+      });
+      active = { requestId: request.requestId, process: child };
+      let stderr = '';
+      let stdoutBuffer = '';
+      let toolCount = 0;
+      let responseText = '';
+      const stdoutDecoder = new StringDecoder('utf8');
+      const consumeWorkerLines = (): void => {
+        while (true) {
+          const newline = stdoutBuffer.indexOf('\n');
+          if (newline === -1) return;
+          const line = stdoutBuffer.slice(0, newline);
+          stdoutBuffer = stdoutBuffer.slice(newline + 1);
+          const progress = workerProgressFromJsonLine(
+            line,
+            request.requestId,
+            toolCount,
+            responseText,
+          );
+          toolCount = progress.toolCount;
+          responseText = progress.responseText;
+          if (progress.update) options.onUpdate?.(progress.update);
+        }
+      };
+      const consumeWorkerOutput = (chunk: Buffer): void => {
+        stdoutBuffer += stdoutDecoder.write(chunk);
+        consumeWorkerLines();
       };
-      const timer = dependencies.scheduleTimeout(() => {
-        finish(false);
-      }, waitMs);
-      void current.terminal.then(() => {
-        finish(true);
+      child.stdout.on('data', consumeWorkerOutput);
+      child.stderr.on('data', (chunk: Buffer) => {
+        stderr += chunk.toString('utf8');
+      });
+      const abort = (): void => {
+        child.kill('SIGTERM');
+      };
+      options.signal?.addEventListener('abort', abort, { once: true });
+      child.once('error', (error) => {
+        if (active?.process === child) active = undefined;
+        reject(error);
+      });
+      child.once('close', (code, signal) => {
+        stdoutBuffer += stdoutDecoder.end();
+        consumeWorkerLines();
+        if (active?.process === child) active = undefined;
+        options.signal?.removeEventListener('abort', abort);
+        resolve(directWorkerResponse(request, code, signal, stderr));
       });
     });
   };
@@ -101,48 +260,31 @@ export function createSubagentDelegationClient(
       return active?.requestId;
     },
     delegate,
-    cancelActiveAndWait,
+    async cancelActiveAndWait(): Promise<boolean> {
+      const current = active;
+      if (!current) return true;
+      current.process.kill('SIGTERM');
+      return new Promise((resolve) => {
+        current.process.once('close', () => {
+          resolve(true);
+        });
+      });
+    },
   };
 }
 
-/**
- * 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;
-
-  /**
-   * Creates a client over the supplied event and timer boundaries.
-   */
-  constructor(
-    events: SubagentEventBus,
-    dependencies: SubagentDelegationClientDependencies = DEFAULT_CLIENT_DEPENDENCIES,
-  ) {
-    this.#controller = createSubagentDelegationClient(events, dependencies);
-  }
-
-  /** Returns the request currently owned by this client, if any. */
+  readonly #client = createSubagentDelegationClient();
   get activeRequestId(): string | undefined {
-    return this.#controller.activeRequestId;
+    return this.#client.activeRequestId;
   }
-
-  /**
-   * Starts a correlated delegation and resolves on its terminal event.
-   */
   delegate(
     request: SubagentDelegationRequest,
-    options: DelegateOptions = {},
+    options?: DelegateOptions,
   ): Promise<SubagentDelegationResponse> {
-    return this.#controller.delegate(request, options);
+    return this.#client.delegate(request, options);
   }
-
-  /**
-   * Requests cancellation and waits briefly for terminal confirmation.
-   */
-  cancelActiveAndWait(waitMs = 5_000): Promise<boolean> {
-    return this.#controller.cancelActiveAndWait(waitMs);
+  cancelActiveAndWait(waitMs?: number): Promise<boolean> {
+    return this.#client.cancelActiveAndWait(waitMs);
   }
 }

package/src/integrations/subagents/protocol-events.ts

@@ -1,14 +1,3 @@
-import type {
-  SubagentDelegationRequest as UpstreamDelegationRequest,
-  SubagentDelegationResponse as UpstreamDelegationResponse,
-  SubagentDelegationStatus as UpstreamDelegationStatus,
-  SubagentDelegationUpdate as UpstreamDelegationUpdate,
-} from 'pi-subagents/delegation';
-
-// These released v1 transport values are duplicated as literals because
-// pi-subagents 0.36.0 exports TypeScript source. Node's native type stripping
-// cannot execute TypeScript below node_modules; the public types above remain
-// the compile-time compatibility check.
 export const SUBAGENT_DELEGATION_PROTOCOL_VERSION = 1 as const;
 export const SUBAGENT_DELEGATION_REQUEST_EVENT =
   'prompt-template:subagent:request';
@@ -21,7 +10,35 @@ export const SUBAGENT_DELEGATION_RESPONSE_EVENT =
 export const SUBAGENT_DELEGATION_CANCEL_EVENT =
   'prompt-template:subagent:cancel';
 
-export type SubagentDelegationRequest = UpstreamDelegationRequest;
-export type SubagentDelegationUpdate = UpstreamDelegationUpdate;
-export type SubagentDelegationStatus = UpstreamDelegationStatus;
-export type SubagentDelegationResponse = UpstreamDelegationResponse;
+export type SubagentDelegationRequest = {
+  readonly version: 1;
+  readonly requestId: string;
+  readonly agent: string;
+  readonly task: string;
+  readonly cwd: string;
+  readonly timeoutMs?: number;
+  readonly model?: string;
+  readonly thinking?:
+    'off' | 'minimal' | 'low' | 'medium' | 'high' | 'xhigh' | 'max';
+  readonly [key: string]: unknown;
+};
+export type SubagentDelegationUpdate = {
+  readonly requestId: string;
+  readonly activity?: string;
+  /** Operator-visible detail; never used as workflow instruction or input. */
+  readonly detail?: string;
+  readonly currentTool?: string;
+  readonly toolCount?: number;
+  readonly tokens?: number;
+};
+export type SubagentDelegationStatus = 'completed' | 'failed' | 'cancelled';
+
+export type SubagentDelegationResponse = {
+  readonly version?: number;
+  readonly requestId: string;
+  readonly agent?: string;
+  readonly status: SubagentDelegationStatus;
+  readonly error?: string;
+  readonly exitCode?: number;
+  readonly warnings?: ReadonlyArray<string>;
+};

package/src/integrations/subagents/protocol.ts

@@ -11,7 +11,7 @@ export type {
   ChildStepPolicy,
   ExtractedChildPolicy,
 } from './child-policy-types.ts';
-export { isSubagentRuntimeName } from './child-policy-validation.ts';
+export { isAgentProfileName } from './child-policy-validation.ts';
 export { parseDelegatedStepResult } from './delegated-result.ts';
 export type { DelegatedStepResult } from './delegated-result.ts';
 export {

package/src/preflight.ts

@@ -69,19 +69,11 @@ export function preflightStep(
   const extensionResources = [...inventory.tools, ...inventory.commands];
   const hasExtension = (extension: string): boolean =>
     extensionResources.some((resource) => sourceMatches(resource, extension));
-  const hasSubagentTool = inventory.tools.some(
-    (tool) => tool.name === 'subagent' && sourceMatches(tool, 'pi-subagents'),
-  );
   const isPlannotatorRequired =
     step.gate?.provider === 'plannotator' &&
     !step.requires.extensions.includes('plannotator');
 
   return [
-    ...(step.subagent && !hasSubagentTool
-      ? [
-          'pi-subagents is required, but its "subagent" tool is not installed or detectable',
-        ]
-      : []),
     ...missingRequiredResources({
       requiredNames: step.requires.tools,
       hasResource: (toolName) => toolNames.has(toolName),

package/src/prompt/main-workflow-notice.ts

@@ -20,22 +20,15 @@ export function buildMainWorkflowNotice(
     throw new Error(`unknown workflow step "${run.currentStepId}"`);
   }
 
-  if (!step.subagent) {
-    return [
-      '# Active main-agent workflow',
-      '',
-      `Workflow "${workflow.definition.id}" is running step "${run.currentStepId}" (${step.title}) in this session.`,
-      'Perform only the active workflow step with its allowed resources.',
-      'Call `workflow_complete_step` exactly once when finished.',
-      'Use `/workflow-pause` to halt and repair the workflow before resuming.',
-    ].join('\n');
-  }
-
   return [
-    '# Active subagent workflow',
+    '# Active workflow',
     '',
-    `Workflow "${workflow.definition.id}" is running step "${run.currentStepId}" (${step.title}) in a separate pi-subagents child process.`,
-    'Do not perform the workflow step in this main session.',
-    `Use \`${statusShortcutLabel}\` or \`/workflow-status\` to open the workflow status overlay, or \`/workflow-pause\` to cancel the child and repair the workflow before resuming.`,
+    `Workflow "${workflow.definition.id}" is running step "${run.currentStepId}" (${step.title}) in this session.`,
+    ...(step.agent
+      ? [`Apply the "${step.agent.name}" workflow role prompt.`]
+      : []),
+    'Perform only the active workflow step with its allowed resources.',
+    'Call `workflow_complete_step` exactly once when finished.',
+    `Use \`${statusShortcutLabel}\` or \`/workflow-status\` to inspect status, or \`/workflow-pause\` to halt and repair the workflow before resuming.`,
   ].join('\n');
 }

package/src/prompt/step-task.ts

@@ -1,3 +1,4 @@
+import { loadAgentProfile } from '../agents/profile.ts';
 import type { LoadedWorkflow, WorkflowStep } from '../config/types.ts';
 import type { WorkflowRun } from '../engine/state.ts';
 import { createStepContract } from './step-contract.ts';
@@ -16,6 +17,8 @@ import {
 
 type StepExecution = 'delegated' | 'main';
 
+const rolePrompt = (name: string): string => loadAgentProfile(name).prompt;
+
 type BuildStepTaskOptions =
   | {
       readonly execution: 'delegated';
@@ -123,15 +126,13 @@ export function buildStepTask(options: BuildStepTaskOptions): string {
     `Run: ${run.runId}`,
     `Iteration: ${run.iteration ?? 1}`,
     `Step: ${run.currentStepId} (${step.title})`,
-    ...(isDelegated
-      ? [
-          `Agent profile: ${step.subagent?.agent ?? 'generalist'}`,
-          'Context: fresh workflow-step context; no parent or sibling transcript is inherited.',
-        ]
-      : []),
+    ...(step.agent ? [`Agent profile: ${step.agent.name}`] : []),
     '',
     '## Step instructions',
     '',
+    ...(step.agent
+      ? ['## Role prompt', '', rolePrompt(step.agent.name), '']
+      : []),
     prompt,
     '',
     ...(isDelegated ? buildDelegatedHandoffSection(handoff) : []),

package/src/workflow-status/format-status.ts

@@ -26,7 +26,11 @@ export function formatWorkflowProgressStatus(
   );
   const activity =
     run.status === 'awaiting-gate' ? 'awaiting review' : 'working';
-  return `${workflowStatusIcon(run, snapshot.now)} ${run.workflowId} · step ${currentStep} · ${activity} · ${statusShortcutLabel}`;
+  const workerProgress =
+    snapshot.execution?.kind === 'subagent'
+      ? ` · ${snapshot.execution.progress}`
+      : '';
+  return `${workflowStatusIcon(run, snapshot.now)} ${run.workflowId} · step ${currentStep} · ${activity}${workerProgress} · ${statusShortcutLabel}`;
 }
 
 /** Format a plain-text workflow status suitable for fallback notifications. */

package/src/workflow-status/render-step-detail.ts

@@ -262,6 +262,100 @@ function attemptDisplayOrdinal(
   return omittedAttempts + index + 1;
 }
 
+function renderLiveWorkerSession(
+  theme: WorkflowStatusTheme,
+  snapshot: WorkflowStatusSnapshot,
+  detail: SelectedStepDetail,
+  width: number,
+): Array<string> {
+  if (snapshot.execution?.kind !== 'subagent') return [];
+  const attempt = detail.attempts.at(-1);
+  const events = snapshot.execution.activityLog ?? [];
+  const eventLines = events.flatMap((event) => {
+    const isToolCall = event.startsWith('call ');
+    const isResponse = event.startsWith('response: ');
+    const label = isToolCall
+      ? '● Tool call'
+      : isResponse
+        ? '● Assistant'
+        : '● Worker';
+    const value = isResponse ? event.slice('response: '.length) : event;
+    return [
+      theme.bold(theme.fg(isToolCall ? 'warning' : 'accent', label)),
+      ...wrapPlain(value, width, theme),
+      '',
+    ];
+  });
+  return [
+    '',
+    theme.bold(theme.fg('accent', 'Live Worker Session')),
+    ...keyValueLines(
+      theme,
+      'worker',
+      snapshot.execution.agent,
+      width,
+      'accent',
+    ),
+    ...keyValueLines(
+      theme,
+      'state',
+      snapshot.execution.progress,
+      width,
+      'accent',
+    ),
+    '',
+    theme.bold(theme.fg('accent', '● Input prompt')),
+    ...wrapPlain(
+      attempt
+        ? `${attempt.task}${
+            attempt.taskTruncated
+              ? `\n… [${attempt.omittedTaskChars ?? 0} prompt characters omitted from the bounded checkpoint trace]`
+              : ''
+          }`
+        : 'The worker prompt is being prepared.',
+      width,
+      theme,
+    ),
+    '',
+    theme.bold(theme.fg('accent', '● Live message chain')),
+    ...(eventLines.length > 0
+      ? eventLines
+      : [theme.fg('muted', 'Waiting for the worker to emit activity…'), '']),
+  ];
+}
+
+/** Renders the active worker's prompt and live event chain as a step subpage. */
+export function renderLiveWorkerActivity(
+  theme: WorkflowStatusTheme,
+  snapshot: WorkflowStatusSnapshot,
+  selectedIndex: number,
+  width: number,
+): Array<string> {
+  const entry = buildPathEntries(snapshot)[selectedIndex];
+  const detail = selectedStepDetail(snapshot, selectedIndex);
+  if (!entry?.isCurrent || !detail || snapshot.execution?.kind !== 'subagent') {
+    return boxed(
+      theme,
+      'Live Worker Session',
+      width,
+      [
+        theme.fg(
+          'muted',
+          'Live activity is available only for the active worker step.',
+        ),
+      ],
+      'borderAccent',
+    );
+  }
+  return boxed(
+    theme,
+    `Live Worker Session · ${entry.title} · visit ${entry.visit}`,
+    width,
+    renderLiveWorkerSession(theme, snapshot, detail, width - 4),
+    'borderAccent',
+  );
+}
+
 /** Renders one selected execution-path row and its persisted evidence. */
 export function renderStepDetail(
   theme: WorkflowStatusTheme,

package/src/workflow-status/types.ts

@@ -14,6 +14,7 @@ export type WorkflowStatusExecution =
       readonly agent: string;
       readonly requestId: string;
       readonly progress: string;
+      readonly activityLog?: ReadonlyArray<string>;
     };
 
 export type WorkflowStatusSnapshot = {