@wichayutdew/pi-workflows 0.3.0 → 1.0.1

package/src/config/validation/step.ts

@@ -0,0 +1,228 @@
+import type { PromptSpec, WorkflowGate, WorkflowStep } from '../types.ts';
+import { parsePermissions, parseRequirements } from './permissions.ts';
+import {
+  isJsonObject,
+  OUTCOME_PATTERN,
+  readInteger,
+  readString,
+  rejectUnknownKeys,
+  type ValidationErrors,
+} from './shared.ts';
+import { parseStepSubagent } from './subagent.ts';
+
+function parsePrompt(
+  value: unknown,
+  path: string,
+  errors: ValidationErrors,
+): PromptSpec | undefined {
+  if (typeof value === 'string') {
+    const inline = readString(value, path, errors);
+    return inline ? { inline } : undefined;
+  }
+  if (!isJsonObject(value)) {
+    errors.push(`${path}: expected a string or an object`);
+    return undefined;
+  }
+  rejectUnknownKeys(value, ['file'], path, errors);
+  const file = readString(value.file, `${path}.file`, errors);
+  if (!file) return undefined;
+  if (file.startsWith('/') || file.includes('\0')) {
+    errors.push(`${path}.file: expected a safe relative path`);
+    return undefined;
+  }
+  return { file };
+}
+
+function parseTransitions(
+  value: unknown,
+  path: string,
+  errors: ValidationErrors,
+): Record<string, string> {
+  if (!isJsonObject(value)) {
+    errors.push(`${path}: expected an object`);
+    return {};
+  }
+  const transitions = Object.entries(value).reduce<Record<string, string>>(
+    (result, [outcome, targetValue]) => {
+      if (!OUTCOME_PATTERN.test(outcome)) {
+        errors.push(`${path}: invalid outcome "${outcome}"`);
+        return result;
+      }
+      const target = readString(targetValue, `${path}.${outcome}`, errors);
+      return target ? { ...result, [outcome]: target } : result;
+    },
+    {},
+  );
+  if (Object.keys(transitions).length === 0) {
+    errors.push(`${path}: at least one transition is required`);
+  }
+  return transitions;
+}
+
+function parseGate(
+  value: unknown,
+  path: string,
+  errors: ValidationErrors,
+): WorkflowGate | undefined {
+  if (value === undefined) return undefined;
+  if (!isJsonObject(value)) {
+    errors.push(`${path}: expected an object`);
+    return undefined;
+  }
+  rejectUnknownKeys(
+    value,
+    [
+      'provider',
+      'submitOutcome',
+      'approvedOutcome',
+      'rejectedOutcome',
+      'timeoutMs',
+    ],
+    path,
+    errors,
+  );
+
+  const providerValue =
+    value.provider === undefined
+      ? 'prompt'
+      : readString(value.provider, `${path}.provider`, errors);
+  const provider =
+    providerValue === 'prompt' || providerValue === 'plannotator'
+      ? providerValue
+      : undefined;
+  if (!provider) {
+    errors.push(`${path}.provider: expected prompt or plannotator`);
+  }
+  const submitOutcome = readString(
+    value.submitOutcome,
+    `${path}.submitOutcome`,
+    errors,
+    { pattern: OUTCOME_PATTERN },
+  );
+  const approvedOutcome = readString(
+    value.approvedOutcome,
+    `${path}.approvedOutcome`,
+    errors,
+    { pattern: OUTCOME_PATTERN },
+  );
+  const rejectedOutcome = readString(
+    value.rejectedOutcome,
+    `${path}.rejectedOutcome`,
+    errors,
+    { pattern: OUTCOME_PATTERN },
+  );
+  if (provider === 'prompt' && value.timeoutMs !== undefined) {
+    errors.push(`${path}.timeoutMs: only valid with provider "plannotator"`);
+  }
+  if (!submitOutcome || !approvedOutcome || !rejectedOutcome || !provider) {
+    return undefined;
+  }
+  if (approvedOutcome === rejectedOutcome) {
+    errors.push(`${path}: approvedOutcome and rejectedOutcome must differ`);
+  }
+
+  return provider === 'prompt'
+    ? {
+        provider,
+        submitOutcome,
+        approvedOutcome,
+        rejectedOutcome,
+      }
+    : {
+        provider,
+        submitOutcome,
+        approvedOutcome,
+        rejectedOutcome,
+        timeoutMs: readInteger(
+          value.timeoutMs,
+          5_000,
+          `${path}.timeoutMs`,
+          errors,
+          { min: 1_000, max: 30_000 },
+        ),
+      };
+}
+
+/** Parse one workflow step and validate relationships within that step. */
+export function parseWorkflowStep(
+  value: unknown,
+  stepId: string,
+  path: string,
+  errors: ValidationErrors,
+): WorkflowStep | undefined {
+  if (!isJsonObject(value)) {
+    errors.push(`${path}: expected an object`);
+    return undefined;
+  }
+  rejectUnknownKeys(
+    value,
+    [
+      'title',
+      'prompt',
+      'subagent',
+      'permissions',
+      'requires',
+      'transitions',
+      'gate',
+    ],
+    path,
+    errors,
+  );
+
+  const title =
+    value.title === undefined
+      ? stepId
+      : readString(value.title, `${path}.title`, errors);
+  const prompt = parsePrompt(value.prompt, `${path}.prompt`, errors);
+  const subagent = parseStepSubagent(
+    value.subagent,
+    `${path}.subagent`,
+    errors,
+  );
+  const permissions = parsePermissions(
+    value.permissions,
+    `${path}.permissions`,
+    errors,
+  );
+  const requires = parseRequirements(
+    value.requires,
+    permissions,
+    `${path}.requires`,
+    errors,
+  );
+  const transitions = parseTransitions(
+    value.transitions,
+    `${path}.transitions`,
+    errors,
+  );
+  const gate = parseGate(value.gate, `${path}.gate`, errors);
+
+  if (gate) {
+    if (!Object.hasOwn(transitions, gate.approvedOutcome)) {
+      errors.push(
+        `${path}.transitions: missing gate outcome "${gate.approvedOutcome}"`,
+      );
+    }
+    if (!Object.hasOwn(transitions, gate.rejectedOutcome)) {
+      errors.push(
+        `${path}.transitions: missing gate outcome "${gate.rejectedOutcome}"`,
+      );
+    }
+    if (Object.hasOwn(transitions, gate.submitOutcome)) {
+      errors.push(
+        `${path}.transitions: submitOutcome is handled by the gate and must not be a transition`,
+      );
+    }
+  }
+
+  if (!title || !prompt) return undefined;
+  return {
+    title,
+    prompt,
+    ...(subagent ? { subagent } : {}),
+    permissions,
+    requires,
+    transitions,
+    ...(gate ? { gate } : {}),
+  };
+}

package/src/config/validation/subagent.ts

@@ -0,0 +1,288 @@
+import {
+  DEFAULT_STEP_SUBAGENT,
+  SUBAGENT_RUNTIME_NAME_PATTERN,
+  type StepSubagent,
+  type SubagentContext,
+  type SubagentPermissionCeiling,
+  type SubagentToolBudget,
+  type SubagentTurnBudget,
+} from '../types.ts';
+import {
+  isJsonObject,
+  readBoolean,
+  readInteger,
+  readString,
+  readStringList,
+  rejectUnknownKeys,
+  RESOURCE_SELECTOR_PATTERN,
+  TOOL_PATTERN,
+  type ValidationErrors,
+} from './shared.ts';
+
+function parseSubagentTurnBudget(
+  value: unknown,
+  path: string,
+  errors: ValidationErrors,
+): SubagentTurnBudget | undefined {
+  if (value === undefined) return undefined;
+  if (!isJsonObject(value)) {
+    errors.push(`${path}: expected an object`);
+    return undefined;
+  }
+  rejectUnknownKeys(value, ['maxTurns', 'graceTurns'], path, errors);
+  const maxTurns = readInteger(value.maxTurns, 0, `${path}.maxTurns`, errors, {
+    min: 1,
+    max: 1_000,
+  });
+  const graceTurns =
+    value.graceTurns === undefined
+      ? undefined
+      : readInteger(value.graceTurns, 0, `${path}.graceTurns`, errors, {
+          min: 0,
+          max: 100,
+        });
+  if (maxTurns === 0) return undefined;
+  return {
+    maxTurns,
+    ...(graceTurns !== undefined ? { graceTurns } : {}),
+  };
+}
+
+function parseSubagentToolBudget(
+  value: unknown,
+  path: string,
+  errors: ValidationErrors,
+): SubagentToolBudget | undefined {
+  if (value === undefined) return undefined;
+  if (!isJsonObject(value)) {
+    errors.push(`${path}: expected an object`);
+    return undefined;
+  }
+  rejectUnknownKeys(value, ['soft', 'hard', 'block'], path, errors);
+  const hard = readInteger(value.hard, 0, `${path}.hard`, errors, {
+    min: 1,
+    max: 100_000,
+  });
+  const soft =
+    value.soft === undefined
+      ? undefined
+      : readInteger(value.soft, 0, `${path}.soft`, errors, {
+          min: 1,
+          max: 100_000,
+        });
+
+  let block: Array<string> | '*' | undefined;
+  if (value.block === '*') {
+    block = '*';
+  } else if (value.block !== undefined) {
+    block = readStringList(value.block, `${path}.block`, errors, TOOL_PATTERN);
+    if (block.length === 0) {
+      errors.push(`${path}.block: expected "*" or at least one tool name`);
+    }
+  }
+  if (soft !== undefined && hard > 0 && soft > hard) {
+    errors.push(`${path}.soft: must not exceed hard`);
+  }
+  if (hard === 0) return undefined;
+  return {
+    hard,
+    ...(soft !== undefined ? { soft } : {}),
+    ...(block !== undefined ? { block } : {}),
+  };
+}
+
+/** Parse an optional isolated-step subagent configuration. */
+export function parseStepSubagent(
+  value: unknown,
+  path: string,
+  errors: ValidationErrors,
+): StepSubagent | undefined {
+  if (value === undefined) return undefined;
+  if (typeof value === 'string') {
+    const agent =
+      readString(value, path, errors, {
+        pattern: SUBAGENT_RUNTIME_NAME_PATTERN,
+      }) ?? DEFAULT_STEP_SUBAGENT.agent;
+    return { ...DEFAULT_STEP_SUBAGENT, agent };
+  }
+  if (!isJsonObject(value)) {
+    errors.push(`${path}: expected an agent profile name or object`);
+    return undefined;
+  }
+  rejectUnknownKeys(
+    value,
+    [
+      'agent',
+      'context',
+      'model',
+      'timeoutMs',
+      'turnBudget',
+      'toolBudget',
+      'artifacts',
+      'retryToolFailures',
+    ],
+    path,
+    errors,
+  );
+
+  const agent =
+    value.agent === undefined
+      ? DEFAULT_STEP_SUBAGENT.agent
+      : (readString(value.agent, `${path}.agent`, errors, {
+          pattern: SUBAGENT_RUNTIME_NAME_PATTERN,
+        }) ?? DEFAULT_STEP_SUBAGENT.agent);
+  const contextValue =
+    value.context === undefined
+      ? DEFAULT_STEP_SUBAGENT.context
+      : readString(value.context, `${path}.context`, errors);
+  const context: SubagentContext = DEFAULT_STEP_SUBAGENT.context;
+  if (contextValue !== 'fresh') {
+    errors.push(`${path}.context: expected fresh`);
+  }
+  const model =
+    value.model === undefined
+      ? undefined
+      : readString(value.model, `${path}.model`, errors, {
+          pattern: RESOURCE_SELECTOR_PATTERN,
+        });
+  const timeoutMs = readInteger(
+    value.timeoutMs,
+    DEFAULT_STEP_SUBAGENT.timeoutMs,
+    `${path}.timeoutMs`,
+    errors,
+    { min: 1_000, max: 86_400_000 },
+  );
+  const turnBudget = parseSubagentTurnBudget(
+    value.turnBudget,
+    `${path}.turnBudget`,
+    errors,
+  );
+  const toolBudget = parseSubagentToolBudget(
+    value.toolBudget,
+    `${path}.toolBudget`,
+    errors,
+  );
+  const artifacts = readBoolean(
+    value.artifacts,
+    DEFAULT_STEP_SUBAGENT.artifacts,
+    `${path}.artifacts`,
+    errors,
+  );
+  const retryToolFailures = readBoolean(
+    value.retryToolFailures,
+    DEFAULT_STEP_SUBAGENT.retryToolFailures,
+    `${path}.retryToolFailures`,
+    errors,
+  );
+  return {
+    agent,
+    context,
+    ...(model ? { model } : {}),
+    timeoutMs,
+    ...(turnBudget ? { turnBudget } : {}),
+    ...(toolBudget ? { toolBudget } : {}),
+    artifacts,
+    retryToolFailures,
+  };
+}
+
+/** Parse the subagent limits inside the user permission ceiling. */
+export function parseSubagentPermissionCeiling(
+  value: unknown,
+  path: string,
+  errors: ValidationErrors,
+): SubagentPermissionCeiling | undefined {
+  if (!isJsonObject(value)) {
+    errors.push(`${path}: expected an object`);
+    return undefined;
+  }
+  rejectUnknownKeys(
+    value,
+    [
+      'agents',
+      'contexts',
+      'models',
+      'maxTimeoutMs',
+      'maxTurns',
+      'maxGraceTurns',
+      'maxToolCalls',
+      'artifacts',
+      'retryToolFailures',
+    ],
+    path,
+    errors,
+  );
+  const agents = readStringList(
+    value.agents,
+    `${path}.agents`,
+    errors,
+    SUBAGENT_RUNTIME_NAME_PATTERN,
+  );
+  const contexts = readStringList(
+    value.contexts,
+    `${path}.contexts`,
+    errors,
+    /^fresh$/,
+  ).filter((context): context is SubagentContext => context === 'fresh');
+  const models = readStringList(
+    value.models,
+    `${path}.models`,
+    errors,
+    RESOURCE_SELECTOR_PATTERN,
+  );
+  if (agents.length === 0) {
+    errors.push(`${path}.agents: at least one subagent is required`);
+  }
+  if (contexts.length === 0) {
+    errors.push(`${path}.contexts: at least one context mode is required`);
+  }
+  (
+    [
+      'maxTimeoutMs',
+      'maxTurns',
+      'maxGraceTurns',
+      'maxToolCalls',
+      'artifacts',
+    ] as const
+  )
+    .filter((field) => value[field] === undefined)
+    .forEach((field) => errors.push(`${path}.${field}: required`));
+
+  return {
+    agents,
+    contexts,
+    models,
+    maxTimeoutMs: readInteger(
+      value.maxTimeoutMs,
+      0,
+      `${path}.maxTimeoutMs`,
+      errors,
+      { min: 1_000, max: 86_400_000 },
+    ),
+    maxTurns: readInteger(value.maxTurns, 0, `${path}.maxTurns`, errors, {
+      min: 1,
+      max: 1_000,
+    }),
+    maxGraceTurns: readInteger(
+      value.maxGraceTurns,
+      0,
+      `${path}.maxGraceTurns`,
+      errors,
+      { min: 0, max: 100 },
+    ),
+    maxToolCalls: readInteger(
+      value.maxToolCalls,
+      0,
+      `${path}.maxToolCalls`,
+      errors,
+      { min: 1, max: 100_000 },
+    ),
+    artifacts: readBoolean(value.artifacts, false, `${path}.artifacts`, errors),
+    retryToolFailures: readBoolean(
+      value.retryToolFailures,
+      false,
+      `${path}.retryToolFailures`,
+      errors,
+    ),
+  };
+}

package/src/config/validation/workflow.ts

@@ -0,0 +1,156 @@
+import { RESERVED_COMMAND_NAMES } from '../../command-names.ts';
+import {
+  WORKFLOW_SCHEMA_VERSION,
+  type WorkflowDefinition,
+  type WorkflowStep,
+} from '../types.ts';
+import {
+  IDENTIFIER_PATTERN,
+  isJsonObject,
+  readInteger,
+  readString,
+  rejectUnknownKeys,
+  type ValidationErrors,
+  type ValidationResult,
+} from './shared.ts';
+import { parseWorkflowStep } from './step.ts';
+
+function parseSteps(
+  value: unknown,
+  errors: ValidationErrors,
+): Record<string, WorkflowStep> {
+  if (!isJsonObject(value)) {
+    errors.push('workflow.steps: expected an object');
+    return {};
+  }
+
+  const steps = Object.entries(value).reduce<Record<string, WorkflowStep>>(
+    (result, [stepId, stepValue]) => {
+      if (!IDENTIFIER_PATTERN.test(stepId)) {
+        errors.push(`workflow.steps: invalid step id "${stepId}"`);
+        return result;
+      }
+      const step = parseWorkflowStep(
+        stepValue,
+        stepId,
+        `workflow.steps.${stepId}`,
+        errors,
+      );
+      return step ? { ...result, [stepId]: step } : result;
+    },
+    {},
+  );
+  if (Object.keys(steps).length === 0) {
+    errors.push('workflow.steps: at least one step is required');
+  }
+  return steps;
+}
+
+function validateGraph(
+  steps: Readonly<Record<string, WorkflowStep>>,
+  start: string | undefined,
+  errors: ValidationErrors,
+): void {
+  if (start && !Object.hasOwn(steps, start)) {
+    errors.push(`workflow.start: unknown step "${start}"`);
+  }
+  Object.entries(steps).forEach(([stepId, step]) => {
+    Object.entries(step.transitions).forEach(([outcome, target]) => {
+      if (
+        target !== '$done' &&
+        target !== '$pause' &&
+        !Object.hasOwn(steps, target)
+      ) {
+        errors.push(
+          `workflow.steps.${stepId}.transitions.${outcome}: unknown target "${target}"`,
+        );
+      }
+    });
+  });
+}
+
+/** Validate and normalize an untrusted workflow definition. */
+export function validateWorkflow(
+  value: unknown,
+): ValidationResult<WorkflowDefinition> {
+  const errors: ValidationErrors = [];
+  if (!isJsonObject(value)) {
+    return { errors: ['workflow: expected an object'] };
+  }
+  rejectUnknownKeys(
+    value,
+    [
+      '$schema',
+      'version',
+      'id',
+      'command',
+      'description',
+      'start',
+      'maxStepVisits',
+      'summaryMaxChars',
+      'steps',
+    ],
+    'workflow',
+    errors,
+  );
+  if (value.$schema !== undefined && typeof value.$schema !== 'string') {
+    errors.push('workflow.$schema: expected a string');
+  }
+  if (value.version !== WORKFLOW_SCHEMA_VERSION) {
+    errors.push(`workflow.version: expected ${WORKFLOW_SCHEMA_VERSION}`);
+  }
+
+  const id = readString(value.id, 'workflow.id', errors, {
+    pattern: IDENTIFIER_PATTERN,
+  });
+  const command = readString(value.command, 'workflow.command', errors, {
+    pattern: IDENTIFIER_PATTERN,
+  });
+  const description = readString(
+    value.description,
+    'workflow.description',
+    errors,
+  );
+  const start = readString(value.start, 'workflow.start', errors, {
+    pattern: IDENTIFIER_PATTERN,
+  });
+  const maxStepVisits = readInteger(
+    value.maxStepVisits,
+    5,
+    'workflow.maxStepVisits',
+    errors,
+    { min: 1, max: 100 },
+  );
+  const summaryMaxChars = readInteger(
+    value.summaryMaxChars,
+    4_000,
+    'workflow.summaryMaxChars',
+    errors,
+    { min: 100, max: 50_000 },
+  );
+
+  if (command && RESERVED_COMMAND_NAMES.has(command)) {
+    errors.push(
+      `workflow.command: "${command}" is reserved by Pi or the harness`,
+    );
+  }
+
+  const steps = parseSteps(value.steps, errors);
+  validateGraph(steps, start, errors);
+  if (errors.length > 0 || !id || !command || !description || !start) {
+    return { errors };
+  }
+  return {
+    value: {
+      version: WORKFLOW_SCHEMA_VERSION,
+      id,
+      command,
+      description,
+      start,
+      maxStepVisits,
+      summaryMaxChars,
+      steps,
+    },
+    errors,
+  };
+}

package/src/config/yaml.ts

@@ -0,0 +1,29 @@
+import { parseDocument } from 'yaml';
+
+export type YamlDocumentKind = 'settings' | 'workflow';
+
+/** Parse one strict, single-document YAML 1.2 configuration value. */
+export function parseYaml(text: string, kind: YamlDocumentKind): unknown {
+  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;
+}