@wichayutdew/pi-workflows 0.1.1

package/src/config/ceiling.ts

@@ -0,0 +1,153 @@
+import type {
+  BashPermission,
+  BashRule,
+  PermissionCeiling,
+  WorkflowDefinition,
+} from './types.ts';
+
+function selectorAllowed(
+  requested: string,
+  ceiling: readonly string[],
+): boolean {
+  const separator = requested.indexOf('/');
+  if (separator === -1) return ceiling.includes(requested);
+  const server = requested.slice(0, separator);
+  return ceiling.includes(server) || ceiling.includes(requested);
+}
+
+function ruleKey(rule: BashRule): string {
+  return JSON.stringify([rule.executable, rule.argsPrefix]);
+}
+
+function bashWithinCeiling(
+  requested: BashPermission,
+  ceiling: BashPermission,
+): boolean {
+  if (ceiling.mode === 'unrestricted') return true;
+  if (requested.mode === 'deny') return true;
+  if (ceiling.mode === 'deny') return false;
+  if (ceiling.mode === 'read-only') return requested.mode === 'read-only';
+  if (requested.mode !== 'allow-list') return false;
+
+  const allowedRules = new Set(ceiling.allow.map(ruleKey));
+  const allowedSources = new Set(ceiling.approvedSources ?? []);
+  return (
+    requested.allow.every((rule) => allowedRules.has(ruleKey(rule))) &&
+    (requested.approvedSources ?? []).every((source) =>
+      allowedSources.has(source),
+    )
+  );
+}
+
+export function checkWorkflowAgainstCeiling(
+  workflow: WorkflowDefinition,
+  ceiling: PermissionCeiling,
+): string[] {
+  const errors: string[] = [];
+  for (const [stepId, step] of Object.entries(workflow.steps)) {
+    const path = `workflow.steps.${stepId}.permissions`;
+    const subagentPath = `workflow.steps.${stepId}.subagent`;
+    for (const tool of step.permissions.tools) {
+      if (!ceiling.tools.includes(tool)) {
+        errors.push(
+          `${path}.tools: "${tool}" exceeds the user permission ceiling`,
+        );
+      }
+    }
+    for (const selector of step.permissions.mcp) {
+      if (!selectorAllowed(selector, ceiling.mcp)) {
+        errors.push(
+          `${path}.mcp: "${selector}" exceeds the user permission ceiling`,
+        );
+      }
+    }
+    for (const extension of step.permissions.extensions) {
+      if (!ceiling.extensions.includes(extension)) {
+        errors.push(
+          `${path}.extensions: "${extension}" exceeds the user permission ceiling`,
+        );
+      }
+    }
+    for (const skill of step.permissions.skills) {
+      if (!ceiling.skills.includes(skill)) {
+        errors.push(
+          `${path}.skills: "${skill}" exceeds the user permission ceiling`,
+        );
+      }
+    }
+    if (!bashWithinCeiling(step.permissions.bash, ceiling.bash)) {
+      errors.push(`${path}.bash: exceeds the user permission ceiling`);
+    }
+    if (!step.subagent) continue;
+    if (!ceiling.subagent) {
+      errors.push(
+        `${subagentPath}: subagent execution exceeds the user permission ceiling`,
+      );
+      continue;
+    }
+    if (!ceiling.subagent.agents.includes(step.subagent.agent)) {
+      errors.push(
+        `${subagentPath}.agent: "${step.subagent.agent}" exceeds the user permission ceiling`,
+      );
+    }
+    if (!ceiling.subagent.contexts.includes(step.subagent.context)) {
+      errors.push(
+        `${subagentPath}.context: "${step.subagent.context}" exceeds the user permission ceiling`,
+      );
+    }
+    if (
+      step.subagent.model &&
+      !ceiling.subagent.models.includes(step.subagent.model)
+    ) {
+      errors.push(
+        `${subagentPath}.model: "${step.subagent.model}" exceeds the user permission ceiling`,
+      );
+    }
+    if (step.subagent.timeoutMs > ceiling.subagent.maxTimeoutMs) {
+      errors.push(
+        `${subagentPath}.timeoutMs: exceeds the user permission ceiling`,
+      );
+    }
+    if (step.subagent.artifacts && !ceiling.subagent.artifacts) {
+      errors.push(
+        `${subagentPath}.artifacts: exceeds the user permission ceiling`,
+      );
+    }
+    if (!step.subagent.turnBudget) {
+      errors.push(
+        `${subagentPath}.turnBudget: required for a project workflow`,
+      );
+    } else {
+      if (step.subagent.turnBudget.maxTurns > ceiling.subagent.maxTurns) {
+        errors.push(
+          `${subagentPath}.turnBudget.maxTurns: exceeds the user permission ceiling`,
+        );
+      }
+      if (
+        (step.subagent.turnBudget.graceTurns ?? 0) >
+        ceiling.subagent.maxGraceTurns
+      ) {
+        errors.push(
+          `${subagentPath}.turnBudget.graceTurns: exceeds the user permission ceiling`,
+        );
+      }
+    }
+    if (!step.subagent.toolBudget) {
+      errors.push(
+        `${subagentPath}.toolBudget: required for a project workflow`,
+      );
+    } else {
+      if (step.subagent.toolBudget.hard > ceiling.subagent.maxToolCalls) {
+        errors.push(
+          `${subagentPath}.toolBudget.hard: exceeds the user permission ceiling`,
+        );
+      }
+      if (step.subagent.toolBudget.block !== '*') {
+        errors.push(
+          `${subagentPath}.toolBudget.block: must be "*" for a project workflow`,
+        );
+      }
+    }
+  }
+  return errors;
+}

package/src/config/command-conflicts.ts

@@ -0,0 +1,31 @@
+interface CommandLike {
+  name: string;
+}
+
+function isSuffixedInvocation(name: string, command: string): boolean {
+  if (!name.startsWith(`${command}:`)) return false;
+  return /^\d+$/.test(name.slice(command.length + 1));
+}
+
+/**
+ * Pi adds numeric suffixes when extensions register the same command. Existing
+ * aliases owned by this harness are safe to replace on reload; a suffixed name
+ * proves at least one other command owns the same base invocation.
+ */
+export function hasRuntimeCommandConflict(
+  command: string,
+  availableCommands: readonly CommandLike[],
+  ownedAliases: ReadonlySet<string>,
+): boolean {
+  if (
+    availableCommands.some((candidate) =>
+      isSuffixedInvocation(candidate.name, command),
+    )
+  ) {
+    return true;
+  }
+  return (
+    !ownedAliases.has(command) &&
+    availableCommands.some((candidate) => candidate.name === command)
+  );
+}

package/src/config/load.ts

@@ -0,0 +1,327 @@
+import { readdir, readFile, realpath } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
+import { parseDocument } from 'yaml';
+import { digest } from '../digest.ts';
+import { checkWorkflowAgainstCeiling } from './ceiling.ts';
+import {
+  DEFAULT_SETTINGS,
+  type ConfigDiagnostic,
+  type LoadedWorkflow,
+  type WorkflowCatalog,
+  type WorkflowDefinition,
+  type WorkflowSettings,
+  type WorkflowSourceKind,
+} from './types.ts';
+import {
+  validatePromptText,
+  validateSettings,
+  validateWorkflow,
+} from './validate.ts';
+
+export interface LoadCatalogOptions {
+  cwd: string;
+  projectTrusted: boolean;
+  userDirectory?: string;
+}
+
+interface LoadedDirectory {
+  workflows: LoadedWorkflow[];
+  diagnostics: ConfigDiagnostic[];
+}
+
+function diagnostic(
+  path: string,
+  message: string,
+  level: ConfigDiagnostic['level'] = 'error',
+): ConfigDiagnostic {
+  return { path, message, level };
+}
+
+async function readYaml(
+  path: string,
+  kind: 'settings' | 'workflow',
+): Promise<unknown> {
+  const text = await readFile(path, 'utf8');
+  const document = parseDocument(text, {
+    customTags: [],
+    merge: false,
+    prettyErrors: true,
+    resolveKnownTags: false,
+    schema: 'core',
+    strict: true,
+    stringKeys: true,
+    uniqueKeys: true,
+    version: '1.2',
+  });
+  const issues = [...document.errors, ...document.warnings];
+  if (issues.length > 0) {
+    throw new Error(issues.map((issue) => issue.message).join('\n'));
+  }
+  if (
+    document.directives.yaml.explicit &&
+    document.directives.yaml.version !== '1.2'
+  ) {
+    throw new Error(`${kind} YAML must use version 1.2`);
+  }
+  return document.toJS({ maxAliasCount: 100 }) as unknown;
+}
+
+function isInside(root: string, candidate: string): boolean {
+  const pathFromRoot = relative(root, candidate);
+  return (
+    pathFromRoot === '' ||
+    (pathFromRoot !== '..' &&
+      !pathFromRoot.startsWith(`..${sep}`) &&
+      !isAbsolute(pathFromRoot))
+  );
+}
+
+async function loadPrompt(
+  sourcePath: string,
+  definition: WorkflowDefinition,
+  stepId: string,
+): Promise<string> {
+  const prompt = definition.steps[stepId]?.prompt;
+  if (!prompt) throw new Error(`unknown step "${stepId}"`);
+  if ('inline' in prompt) return prompt.inline;
+
+  const sourceDirectory = await realpath(dirname(sourcePath));
+  const requestedPath = resolve(sourceDirectory, prompt.file);
+  if (!isInside(sourceDirectory, requestedPath)) {
+    throw new Error(`prompt file escapes workflow directory: ${prompt.file}`);
+  }
+
+  const actualPath = await realpath(requestedPath);
+  if (!isInside(sourceDirectory, actualPath)) {
+    throw new Error(
+      `prompt file symlink escapes workflow directory: ${prompt.file}`,
+    );
+  }
+  return readFile(actualPath, 'utf8');
+}
+
+async function loadWorkflowFile(
+  sourcePath: string,
+  sourceKind: WorkflowSourceKind,
+): Promise<LoadedWorkflow> {
+  const raw = await readYaml(sourcePath, 'workflow');
+  const validation = validateWorkflow(raw);
+  if (!validation.value) {
+    throw new Error(validation.errors.join('\n'));
+  }
+
+  const definition = validation.value;
+  const prompts: Record<string, string> = {};
+  for (const stepId of Object.keys(definition.steps)) {
+    const text = await loadPrompt(sourcePath, definition, stepId);
+    const promptErrors = validatePromptText(
+      text,
+      `workflow.steps.${stepId}.prompt`,
+    );
+    if (promptErrors.length > 0) {
+      throw new Error(promptErrors.join('\n'));
+    }
+    prompts[stepId] = text;
+  }
+
+  const stepDigests = Object.fromEntries(
+    Object.entries(definition.steps).map(([stepId, step]) => [
+      stepId,
+      digest({ step, prompt: prompts[stepId] }),
+    ]),
+  );
+  return {
+    definition,
+    prompts,
+    digest: digest({ definition, prompts }),
+    stepDigests,
+    sourcePath,
+    sourceKind,
+  };
+}
+
+async function loadWorkflowDirectory(
+  directory: string,
+  sourceKind: WorkflowSourceKind,
+): Promise<LoadedDirectory> {
+  let entries;
+  try {
+    entries = await readdir(directory, { withFileTypes: true });
+  } catch (error) {
+    const code = (error as NodeJS.ErrnoException).code;
+    if (code === 'ENOENT') return { workflows: [], diagnostics: [] };
+    return {
+      workflows: [],
+      diagnostics: [
+        diagnostic(
+          directory,
+          `cannot read workflow directory: ${String(error)}`,
+        ),
+      ],
+    };
+  }
+
+  const workflows: LoadedWorkflow[] = [];
+  const diagnostics: ConfigDiagnostic[] = [];
+  const files = entries
+    .filter((entry) => entry.isFile() && /\.workflow\.ya?ml$/i.test(entry.name))
+    .map((entry) => join(directory, entry.name))
+    .sort();
+
+  for (const path of files) {
+    try {
+      workflows.push(await loadWorkflowFile(path, sourceKind));
+    } catch (error) {
+      diagnostics.push(
+        diagnostic(
+          path,
+          error instanceof Error ? error.message : String(error),
+        ),
+      );
+    }
+  }
+  return { workflows, diagnostics };
+}
+
+async function loadSettings(userDirectory: string): Promise<{
+  settings: WorkflowSettings;
+  diagnostics: ConfigDiagnostic[];
+}> {
+  const path = join(userDirectory, 'settings.yaml');
+  try {
+    const validation = validateSettings(await readYaml(path, 'settings'));
+    if (!validation.value) {
+      return {
+        settings: DEFAULT_SETTINGS,
+        diagnostics: validation.errors.map((message) =>
+          diagnostic(path, message),
+        ),
+      };
+    }
+    return { settings: validation.value, diagnostics: [] };
+  } catch (error) {
+    const code = (error as NodeJS.ErrnoException).code;
+    if (code === 'ENOENT')
+      return { settings: DEFAULT_SETTINGS, diagnostics: [] };
+    return {
+      settings: DEFAULT_SETTINGS,
+      diagnostics: [
+        diagnostic(
+          path,
+          `cannot read settings: ${error instanceof Error ? error.message : String(error)}`,
+        ),
+      ],
+    };
+  }
+}
+
+function addWorkflow(
+  catalog: Map<string, LoadedWorkflow>,
+  commands: Map<string, string>,
+  workflow: LoadedWorkflow,
+  diagnostics: ConfigDiagnostic[],
+): void {
+  const id = workflow.definition.id;
+  const command = workflow.definition.command;
+  const existing = catalog.get(id);
+  if (existing) {
+    diagnostics.push(
+      diagnostic(
+        workflow.sourcePath,
+        `workflow id "${id}" already belongs to ${existing.sourcePath}; overrides are not allowed`,
+      ),
+    );
+    return;
+  }
+  const existingCommand = commands.get(command);
+  if (existingCommand) {
+    diagnostics.push(
+      diagnostic(
+        workflow.sourcePath,
+        `command "/${command}" already belongs to workflow "${existingCommand}"`,
+      ),
+    );
+    return;
+  }
+  catalog.set(id, workflow);
+  commands.set(command, id);
+}
+
+export function defaultUserWorkflowDirectory(): string {
+  const explicit = process.env.PI_WORKFLOWS_DIR?.trim();
+  if (explicit) return resolve(explicit);
+  const agentDirectory =
+    process.env.PI_CODING_AGENT_DIR?.trim() || join(homedir(), '.pi', 'agent');
+  return join(agentDirectory, 'workflows');
+}
+
+export async function loadCatalog(
+  options: LoadCatalogOptions,
+): Promise<WorkflowCatalog> {
+  const userDirectory = resolve(
+    options.userDirectory ?? defaultUserWorkflowDirectory(),
+  );
+  const diagnostics: ConfigDiagnostic[] = [];
+  const settingsResult = await loadSettings(userDirectory);
+  diagnostics.push(...settingsResult.diagnostics);
+
+  const catalog = new Map<string, LoadedWorkflow>();
+  const commands = new Map<string, string>();
+  const userResult = await loadWorkflowDirectory(userDirectory, 'user');
+  diagnostics.push(...userResult.diagnostics);
+  for (const workflow of userResult.workflows) {
+    addWorkflow(catalog, commands, workflow, diagnostics);
+  }
+
+  const projectDirectory = join(resolve(options.cwd), '.pi', 'workflows');
+  if (settingsResult.settings.allowProjectWorkflows) {
+    if (!options.projectTrusted) {
+      diagnostics.push(
+        diagnostic(
+          projectDirectory,
+          'project workflows were skipped because the project is not trusted',
+          'warning',
+        ),
+      );
+    } else if (!settingsResult.settings.permissionCeiling) {
+      diagnostics.push(
+        diagnostic(
+          projectDirectory,
+          'project workflows were skipped because no user permission ceiling is configured',
+        ),
+      );
+    } else {
+      const projectResult = await loadWorkflowDirectory(
+        projectDirectory,
+        'project',
+      );
+      diagnostics.push(...projectResult.diagnostics);
+      for (const workflow of projectResult.workflows) {
+        const ceilingErrors = checkWorkflowAgainstCeiling(
+          workflow.definition,
+          settingsResult.settings.permissionCeiling,
+        );
+        if (ceilingErrors.length > 0) {
+          diagnostics.push(
+            ...ceilingErrors.map((message) =>
+              diagnostic(workflow.sourcePath, message),
+            ),
+          );
+          continue;
+        }
+        addWorkflow(catalog, commands, workflow, diagnostics);
+      }
+    }
+  }
+
+  return {
+    workflows: catalog,
+    settings: settingsResult.settings,
+    diagnostics,
+    userDirectory,
+    ...(settingsResult.settings.allowProjectWorkflows
+      ? { projectDirectory }
+      : {}),
+  };
+}

package/src/config/types.ts

@@ -0,0 +1,187 @@
+export const WORKFLOW_SCHEMA_VERSION = 1 as const;
+export const SUBAGENT_RUNTIME_NAME_PATTERN =
+  /^[a-z0-9][a-z0-9-]*(?:\.[a-z0-9][a-z0-9-]*)*$/;
+
+export const TERMINAL_TARGETS = ['$done', '$pause'] as const;
+export type TerminalTarget = (typeof TERMINAL_TARGETS)[number];
+export type StepTarget = string | TerminalTarget;
+
+export type BashMode = 'deny' | 'read-only' | 'allow-list' | 'unrestricted';
+export type BashApprovalSource =
+  'verification-worker' | 'verification-reviewer' | 'remote-actions';
+
+export interface BashRule {
+  executable: string;
+  argsPrefix: string[];
+}
+
+export interface BashPermission {
+  mode: BashMode;
+  allow: BashRule[];
+  /**
+   * Exact commands extracted from the most recent human-approved artifact.
+   * They supplement `allow` only inside the correlated step execution.
+   */
+  approvedSources?: BashApprovalSource[];
+}
+
+export interface StepPermissions {
+  /** Exact Pi tool names, including direct MCP tools. */
+  tools: string[];
+  /** MCP proxy selectors in `server` or `server/tool` form. */
+  mcp: string[];
+  /** Source-name/path fragments whose registered tools may be used. */
+  extensions: string[];
+  /** Skills the step prompt is allowed to use. */
+  skills: string[];
+  bash: BashPermission;
+}
+
+export interface StepRequirements {
+  tools: string[];
+  extensions: string[];
+  skills: string[];
+}
+
+export type SubagentContext = 'fresh' | 'fork';
+
+export interface SubagentTurnBudget {
+  maxTurns: number;
+  graceTurns?: number;
+}
+
+export interface SubagentToolBudget {
+  hard: number;
+  soft?: number;
+  block?: string[] | '*';
+}
+
+export interface StepSubagent {
+  /** Configured pi-subagents agent name. */
+  agent: string;
+  /** Fresh keeps workflow work out of the parent transcript. */
+  context: SubagentContext;
+  model?: string;
+  timeoutMs: number;
+  turnBudget?: SubagentTurnBudget;
+  toolBudget?: SubagentToolBudget;
+  artifacts: boolean;
+}
+
+export type PromptSpec = { inline: string } | { file: string };
+
+interface GateDefinition {
+  submitOutcome: string;
+  approvedOutcome: string;
+  rejectedOutcome: string;
+}
+
+export interface PromptGate extends GateDefinition {
+  provider: 'prompt';
+}
+
+export interface PlannotatorGate extends GateDefinition {
+  provider: 'plannotator';
+  timeoutMs: number;
+}
+
+export type WorkflowGate = PromptGate | PlannotatorGate;
+
+export interface WorkflowStep {
+  title: string;
+  prompt: PromptSpec;
+  /** Omit to execute this step in the main Pi agent. */
+  subagent?: StepSubagent;
+  permissions: StepPermissions;
+  requires: StepRequirements;
+  transitions: Record<string, StepTarget>;
+  gate?: WorkflowGate;
+}
+
+export interface WorkflowDefinition {
+  version: typeof WORKFLOW_SCHEMA_VERSION;
+  id: string;
+  command: string;
+  description: string;
+  start: string;
+  maxStepVisits: number;
+  summaryMaxChars: number;
+  steps: Record<string, WorkflowStep>;
+}
+
+export type WorkflowSourceKind = 'user' | 'project';
+
+export interface LoadedWorkflow {
+  definition: WorkflowDefinition;
+  prompts: Record<string, string>;
+  digest: string;
+  stepDigests: Record<string, string>;
+  sourcePath: string;
+  sourceKind: WorkflowSourceKind;
+}
+
+export interface PermissionCeiling {
+  tools: string[];
+  mcp: string[];
+  extensions: string[];
+  skills: string[];
+  bash: BashPermission;
+  subagent?: SubagentPermissionCeiling;
+}
+
+export interface SubagentPermissionCeiling {
+  agents: string[];
+  contexts: SubagentContext[];
+  models: string[];
+  maxTimeoutMs: number;
+  maxTurns: number;
+  maxGraceTurns: number;
+  maxToolCalls: number;
+  artifacts: boolean;
+}
+
+export interface WorkflowSettings {
+  version: typeof WORKFLOW_SCHEMA_VERSION;
+  allowProjectWorkflows: boolean;
+  permissionCeiling?: PermissionCeiling;
+}
+
+export interface ConfigDiagnostic {
+  level: 'warning' | 'error';
+  path: string;
+  message: string;
+}
+
+export interface WorkflowCatalog {
+  workflows: Map<string, LoadedWorkflow>;
+  settings: WorkflowSettings;
+  diagnostics: ConfigDiagnostic[];
+  userDirectory: string;
+  projectDirectory?: string;
+}
+
+export const EMPTY_PERMISSIONS: StepPermissions = {
+  tools: [],
+  mcp: [],
+  extensions: [],
+  skills: [],
+  bash: { mode: 'deny', allow: [] },
+};
+
+export const EMPTY_REQUIREMENTS: StepRequirements = {
+  tools: [],
+  extensions: [],
+  skills: [],
+};
+
+export const DEFAULT_STEP_SUBAGENT: StepSubagent = {
+  agent: 'pi-workflows.step',
+  context: 'fresh',
+  timeoutMs: 900_000,
+  artifacts: false,
+};
+
+export const DEFAULT_SETTINGS: WorkflowSettings = {
+  version: WORKFLOW_SCHEMA_VERSION,
+  allowProjectWorkflows: false,
+};