@wichayutdew/pi-workflows 0.1.1

package/src/policy/tools.ts

@@ -0,0 +1,150 @@
+import type { WorkflowStep } from '../config/types.ts';
+import { authorizeBash } from './bash.ts';
+
+export interface ToolSourceInfo {
+  source?: string;
+  path?: string;
+}
+
+export interface ToolInventoryItem {
+  name: string;
+  sourceInfo?: ToolSourceInfo;
+}
+
+export interface ToolAuthorization {
+  allowed: boolean;
+  reason?: string;
+}
+
+function reject(reason: string): ToolAuthorization {
+  return { allowed: false, reason };
+}
+
+function sourceText(tool: ToolInventoryItem): string {
+  return `${tool.sourceInfo?.source ?? ''}\n${tool.sourceInfo?.path ?? ''}`.toLowerCase();
+}
+
+function isMcpAdapterTool(tool: ToolInventoryItem): boolean {
+  return sourceText(tool).includes('pi-mcp-adapter');
+}
+
+export function matchesExtensionSelector(
+  tool: ToolInventoryItem,
+  selector: string,
+): boolean {
+  const source = tool.sourceInfo?.source;
+  if (source === 'builtin' || source === 'sdk') return false;
+  return sourceText(tool).includes(selector.toLowerCase());
+}
+
+export function resolveActiveTools(
+  inventory: readonly ToolInventoryItem[],
+  step: WorkflowStep,
+  completionToolName: string,
+): string[] {
+  const exact = new Set(step.permissions.tools);
+  const selected = inventory
+    .filter(
+      (tool) =>
+        tool.name === completionToolName ||
+        exact.has(tool.name) ||
+        (tool.name === 'mcp' && step.permissions.mcp.length > 0) ||
+        (!isMcpAdapterTool(tool) &&
+          step.permissions.extensions.some((selector) =>
+            matchesExtensionSelector(tool, selector),
+          )),
+    )
+    .map((tool) => tool.name);
+  return [...new Set(selected)];
+}
+
+function selectorAllows(
+  selectors: readonly string[],
+  server: string,
+  tool: string,
+): boolean {
+  return selectors.some((selector) => {
+    const separator = selector.indexOf('/');
+    if (separator === -1) return selector === server;
+    return (
+      selector.slice(0, separator) === server &&
+      selector.slice(separator + 1) === tool
+    );
+  });
+}
+
+export function authorizeMcpProxy(
+  input: Record<string, unknown>,
+  selectors: readonly string[],
+): ToolAuthorization {
+  if (selectors.length === 0) {
+    return reject('MCP access is disabled for this workflow step');
+  }
+
+  const unsupportedModes = [
+    'action',
+    'connect',
+    'describe',
+    'search',
+    'regex',
+    'includeSchemas',
+  ].filter((field) => input[field] !== undefined);
+  if (unsupportedModes.length > 0) {
+    return reject(
+      `MCP proxy mode "${unsupportedModes[0]}" is disabled; use an explicit server and tool`,
+    );
+  }
+  if (typeof input.server !== 'string' || !input.server.trim()) {
+    return reject('MCP proxy calls must name an explicit server');
+  }
+  if (typeof input.tool !== 'string' || !input.tool.trim()) {
+    return reject('MCP proxy calls must name an explicit tool');
+  }
+
+  const server = input.server.trim();
+  const tool = input.tool.trim();
+  if (!selectorAllows(selectors, server, tool)) {
+    return reject(
+      `MCP tool "${server}/${tool}" is not allowed for this workflow step`,
+    );
+  }
+  return { allowed: true };
+}
+
+export function authorizeToolCall(
+  toolName: string,
+  input: Record<string, unknown>,
+  step: WorkflowStep,
+  inventory: readonly ToolInventoryItem[],
+  approvedBashCommands: readonly string[] = [],
+): ToolAuthorization {
+  const tool = inventory.find((candidate) => candidate.name === toolName);
+  const allowedByName = step.permissions.tools.includes(toolName);
+  const allowedByExtension =
+    tool !== undefined &&
+    !isMcpAdapterTool(tool) &&
+    step.permissions.extensions.some((selector) =>
+      matchesExtensionSelector(tool, selector),
+    );
+
+  if (toolName === 'mcp') {
+    return authorizeMcpProxy(input, step.permissions.mcp);
+  }
+  if (!allowedByName && !allowedByExtension) {
+    return reject(`tool "${toolName}" is not allowed for this workflow step`);
+  }
+  if (toolName === 'bash') {
+    const command = input.command;
+    if (typeof command !== 'string')
+      return reject('Bash call is missing command text');
+    const result = authorizeBash(
+      command,
+      step.permissions.bash,
+      approvedBashCommands,
+    );
+    return result.allowed
+      ? { allowed: true }
+      : reject(result.reason ?? 'Bash command is not allowed');
+  }
+  return { allowed: true };
+}

package/src/preflight.ts

@@ -0,0 +1,76 @@
+import type { WorkflowStep } from './config/types.ts';
+
+interface SourceInfoLike {
+  source?: string;
+  path?: string;
+}
+
+interface NamedResource {
+  name: string;
+  sourceInfo?: SourceInfoLike;
+}
+
+export interface PreflightInventory {
+  tools: readonly NamedResource[];
+  commands: readonly NamedResource[];
+  skills: ReadonlySet<string>;
+}
+
+function sourceMatches(resource: NamedResource, selector: string): boolean {
+  const source = `${resource.sourceInfo?.source ?? ''}\n${resource.sourceInfo?.path ?? ''}`;
+  return source.toLowerCase().includes(selector.toLowerCase());
+}
+
+export function preflightStep(
+  step: WorkflowStep,
+  inventory: PreflightInventory,
+): string[] {
+  const errors: string[] = [];
+  const toolNames = new Set(inventory.tools.map((tool) => tool.name));
+  const subagentTool = inventory.tools.find(
+    (tool) => tool.name === 'subagent' && sourceMatches(tool, 'pi-subagents'),
+  );
+
+  if (step.subagent && !subagentTool) {
+    errors.push(
+      'pi-subagents is required, but its "subagent" tool is not installed or detectable',
+    );
+  }
+
+  for (const tool of step.requires.tools) {
+    if (!toolNames.has(tool)) {
+      errors.push(`required tool "${tool}" is not installed`);
+    }
+  }
+  if (step.permissions.mcp.length > 0 && !toolNames.has('mcp')) {
+    errors.push(
+      'MCP selectors are configured, but the "mcp" proxy tool is not installed',
+    );
+  }
+
+  const extensionResources = [...inventory.tools, ...inventory.commands];
+  if (
+    step.gate?.provider === 'plannotator' &&
+    !step.requires.extensions.includes('plannotator') &&
+    !extensionResources.some((resource) =>
+      sourceMatches(resource, 'plannotator'),
+    )
+  ) {
+    errors.push(
+      'Plannotator is required by this gate, but its extension is not installed or detectable',
+    );
+  }
+  for (const extension of step.requires.extensions) {
+    if (
+      !extensionResources.some((resource) => sourceMatches(resource, extension))
+    ) {
+      errors.push(`required extension "${extension}" is not detectable`);
+    }
+  }
+  for (const skill of step.requires.skills) {
+    if (!inventory.skills.has(skill)) {
+      errors.push(`required skill "${skill}" is not loaded`);
+    }
+  }
+  return errors;
+}

package/src/prompt.ts

@@ -0,0 +1,146 @@
+import type { LoadedWorkflow, WorkflowStep } from './config/types.ts';
+import type { WorkflowRun } from './engine/state.ts';
+import { allowedOutcomes } from './engine/transitions.ts';
+
+interface TemplateValues {
+  [key: string]: string;
+}
+
+function formatList(values: readonly string[]): string {
+  return values.length > 0 ? values.join(', ') : '(none)';
+}
+
+function currentStepHandoff(run: WorkflowRun): string {
+  const incoming = run.stepHandoff ?? '';
+  if (!incoming || incoming === run.lastSummary) return run.lastSummary;
+  if (!run.lastSummary) return incoming;
+  return [
+    'Incoming approved or previous-step handoff:',
+    incoming,
+    '',
+    'Latest paused attempt:',
+    run.lastSummary,
+  ].join('\n');
+}
+
+export function renderTemplate(
+  template: string,
+  values: TemplateValues,
+): string {
+  return template.replace(/\{\{([^{}]+)\}\}/g, (_match, rawName: string) => {
+    const name = rawName.trim();
+    return values[name] ?? '';
+  });
+}
+
+function templateValues(
+  workflow: LoadedWorkflow,
+  run: WorkflowRun,
+  step: WorkflowStep,
+): TemplateValues {
+  return {
+    'workflow.input': run.input,
+    'workflow.id': workflow.definition.id,
+    'run.id': run.runId,
+    'step.id': run.currentStepId,
+    'step.title': step.title,
+    'last.summary': currentStepHandoff(run),
+    'gate.feedback': run.gateFeedback,
+  };
+}
+
+function buildStepTask(
+  workflow: LoadedWorkflow,
+  run: WorkflowRun,
+  execution: 'delegated' | 'main',
+  policyEnvelope?: string,
+): string {
+  const step = workflow.definition.steps[run.currentStepId];
+  if (!step) throw new Error(`unknown workflow step "${run.currentStepId}"`);
+  const prompt = renderTemplate(
+    workflow.prompts[run.currentStepId] ?? '',
+    templateValues(workflow, run, step),
+  );
+  const outcomes = allowedOutcomes(workflow, run);
+  const allowedOutcomeSet = new Set(outcomes);
+  const transitionLines = Object.entries(step.transitions)
+    .filter(([outcome]) => allowedOutcomeSet.has(outcome))
+    .map(([outcome, target]) => `- ${outcome}: ${target}`)
+    .join('\n');
+  const gateLine = step.gate
+    ? `- ${step.gate.submitOutcome}: submit the artifact to ${step.gate.provider}; include the full artifact argument`
+    : '';
+  const delegated = execution === 'delegated';
+
+  return [
+    ...(policyEnvelope ? [policyEnvelope, ''] : []),
+    `# ${delegated ? 'Delegated' : 'Main-agent'} declarative workflow step`,
+    '',
+    `Workflow: ${workflow.definition.id}`,
+    `Run: ${run.runId}`,
+    `Step: ${run.currentStepId} (${step.title})`,
+    '',
+    '## Step instructions',
+    '',
+    prompt,
+    '',
+    `## Enforced ${delegated ? 'child' : 'step'} resources`,
+    '',
+    `Pi tools: ${formatList(step.permissions.tools)}`,
+    `MCP selectors: ${formatList(step.permissions.mcp)}`,
+    `Extension selectors: ${formatList(step.permissions.extensions)}`,
+    `Skills: ${formatList(step.permissions.skills)}`,
+    `Bash policy: ${step.permissions.bash.mode}`,
+    '',
+    `Use only the listed skills for this step. Tool calls are enforced ${delegated ? 'inside this child process' : 'by the workflow harness'}.`,
+    '',
+    '## Completion contract',
+    '',
+    `Call \`workflow_complete_step\` exactly once, after all work for this ${delegated ? 'delegated' : 'main-agent'} step is complete.`,
+    `Valid outcomes: ${outcomes.join(', ')}`,
+    transitionLines,
+    gateLine,
+    '',
+    'Put a concise handoff in `summary`. Do not call the completion tool alongside other tool calls. If the workflow definition or environment is wrong, use an outcome that transitions to `$pause`.',
+  ].join('\n');
+}
+
+export function buildDelegatedStepTask(
+  workflow: LoadedWorkflow,
+  run: WorkflowRun,
+  policyEnvelope: string,
+): string {
+  return buildStepTask(workflow, run, 'delegated', policyEnvelope);
+}
+
+export function buildMainStepTask(
+  workflow: LoadedWorkflow,
+  run: WorkflowRun,
+): string {
+  return buildStepTask(workflow, run, 'main');
+}
+
+export function buildMainWorkflowNotice(
+  workflow: LoadedWorkflow,
+  run: WorkflowRun,
+): string {
+  const step = workflow.definition.steps[run.currentStepId];
+  if (!step) 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',
+    '',
+    `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 `/workflow-status` to inspect it or `/workflow-pause` to cancel the child and repair the workflow before resuming.',
+  ].join('\n');
+}

package/src/runtime/completion-tool.ts

@@ -0,0 +1,22 @@
+import { Type } from 'typebox';
+
+export const WORKFLOW_COMPLETION_TOOL = 'workflow_complete_step';
+
+export const WORKFLOW_COMPLETION_PARAMETERS = Type.Object(
+  {
+    outcome: Type.String({
+      description: 'One exact outcome allowed by the active workflow step',
+    }),
+    summary: Type.String({
+      description: 'Concise checkpoint and handoff for the next workflow step',
+      maxLength: 50_000,
+    }),
+    artifact: Type.Optional(
+      Type.String({
+        description: 'Full artifact required when submitting to a review gate',
+        maxLength: 200_000,
+      }),
+    ),
+  },
+  { additionalProperties: false },
+);

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

@@ -0,0 +1,227 @@
+import type {
+  ExtensionAPI,
+  ExtensionContext,
+} from '@earendil-works/pi-coding-agent';
+import type { WorkflowStep } from '../config/types.ts';
+import { invalidCompletionCallIds } from '../policy/completion-batch.ts';
+import { freezeToolInput } from '../policy/immutable-input.ts';
+import { authorizeToolCall, resolveActiveTools } from '../policy/tools.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;
+}
+
+export class MainStepRuntime {
+  private active: MainStepExecution | undefined;
+  private pendingResult: WorkflowStepResult | undefined;
+  private invalidCompletionCalls = new Set<string>();
+  private suspended = false;
+
+  constructor(private readonly pi: ExtensionAPI) {
+    this.registerLifecycle();
+    this.registerPolicy();
+    this.registerCompletionTool();
+  }
+
+  get activeStepId(): string | undefined {
+    return this.active?.stepId;
+  }
+
+  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(),
+        execution.step,
+        WORKFLOW_COMPLETION_TOOL,
+      ),
+    );
+  }
+
+  deactivate(): boolean {
+    const wasActive = this.active !== undefined;
+    this.active = undefined;
+    this.pendingResult = undefined;
+    this.invalidCompletionCalls.clear();
+    return wasActive;
+  }
+
+  suspend(): boolean {
+    const wasActive = this.deactivate();
+    if (wasActive) {
+      this.suspended = true;
+      this.pi.setActiveTools([]);
+    }
+    return wasActive;
+  }
+
+  release(): void {
+    this.suspended = false;
+  }
+
+  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);
+    });
+  }
+
+  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);
+    });
+  }
+
+  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,
+        };
+      },
+    });
+  }
+}

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

@@ -0,0 +1,17 @@
+/**
+ * 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.
+ */
+export class SerialTaskQueue {
+  private tail: Promise<void> = Promise.resolve();
+
+  run<T>(task: () => Promise<T>): Promise<T> {
+    const result = this.tail.then(task, task);
+    this.tail = result.then(
+      () => undefined,
+      () => undefined,
+    );
+    return result;
+  }
+}