@wichayutdew/pi-workflows 0.3.0 → 1.0.1

package/src/integrations/subagents/child-runtime-dependencies.ts

@@ -0,0 +1,47 @@
+import { randomUUID, timingSafeEqual } from 'node:crypto';
+import {
+  existsSync,
+  lstatSync,
+  readFileSync,
+  realpathSync,
+  renameSync,
+  statSync,
+  unlinkSync,
+  writeFileSync,
+} from 'node:fs';
+import { tmpdir } from 'node:os';
+import type { SubagentChildRuntimeDependencies } from './child-runtime-types.ts';
+
+const tokensAreEqual = (actual: string, expected: string): boolean => {
+  const actualBytes = Buffer.from(actual, 'utf8');
+  const expectedBytes = Buffer.from(expected, 'utf8');
+  return (
+    actualBytes.length === expectedBytes.length &&
+    timingSafeEqual(actualBytes, expectedBytes)
+  );
+};
+
+export const DEFAULT_CHILD_RUNTIME_DEPENDENCIES = {
+  fileSystem: {
+    exists: existsSync,
+    inspect: lstatSync,
+    readText: (path: string) => readFileSync(path, 'utf8'),
+    realPath: realpathSync,
+    rename: renameSync,
+    stat: statSync,
+    unlink: unlinkSync,
+    writeExclusive: (path: string, content: string) => {
+      writeFileSync(path, content, {
+        encoding: 'utf8',
+        flag: 'wx',
+        mode: 0o600,
+      });
+    },
+  },
+  createUniqueId: randomUUID,
+  currentWorkingDirectory: () => process.cwd(),
+  environmentChildAgent: () =>
+    process.env.PI_SUBAGENT_CHILD_AGENT?.trim() || undefined,
+  temporaryDirectory: tmpdir,
+  tokensAreEqual,
+} as const satisfies SubagentChildRuntimeDependencies;

package/src/integrations/subagents/child-runtime-files.ts

@@ -0,0 +1,156 @@
+import { dirname, isAbsolute, relative, resolve, sep } from 'node:path';
+import type { ChildStepPolicy } from './child-policy-types.ts';
+import type { SubagentChildRuntimeDependencies } from './child-runtime-types.ts';
+
+const FILE_MUTATION_TOOLS: ReadonlySet<string> = new Set(['edit', 'write']);
+
+const errorCode = (error: unknown): unknown =>
+  error !== null && typeof error === 'object' && 'code' in error
+    ? error.code
+    : undefined;
+
+const pathIsInside = (root: string, candidate: string): boolean => {
+  const relativePath = relative(root, candidate);
+  return (
+    relativePath !== '..' &&
+    !relativePath.startsWith(`..${sep}`) &&
+    !isAbsolute(relativePath)
+  );
+};
+
+const nearestCanonicalAncestor = (
+  path: string,
+  dependencies: SubagentChildRuntimeDependencies,
+): string | undefined => {
+  let candidate = path;
+  while (true) {
+    try {
+      dependencies.fileSystem.inspect(candidate);
+    } catch (error) {
+      if (errorCode(error) !== 'ENOENT') return undefined;
+      const parent = dirname(candidate);
+      if (parent === candidate) return undefined;
+      candidate = parent;
+      continue;
+    }
+    try {
+      return dependencies.fileSystem.realPath(candidate);
+    } catch {
+      return undefined;
+    }
+  }
+};
+
+type VerifyChildCapabilityOptions = {
+  readonly policy: ChildStepPolicy;
+  readonly childAgent: string;
+  readonly dependencies: SubagentChildRuntimeDependencies;
+};
+
+/**
+ * Verifies and consumes the one-time capability for a delegated child.
+ *
+ * @throws When the child identity or capability is invalid.
+ */
+export const verifyChildCapability = ({
+  policy,
+  childAgent,
+  dependencies,
+}: VerifyChildCapabilityOptions): void => {
+  if (childAgent !== policy.agent) {
+    throw new Error('child agent does not match the delegated workflow policy');
+  }
+
+  let actual: string;
+  try {
+    actual = dependencies.fileSystem.readText(policy.capabilityPath);
+  } catch {
+    throw new Error('delegated workflow capability is missing');
+  }
+  if (!dependencies.tokensAreEqual(actual, policy.capabilityToken)) {
+    throw new Error('delegated workflow capability is invalid');
+  }
+  dependencies.fileSystem.unlink(policy.capabilityPath);
+};
+
+type WriteChildResultOptions = {
+  readonly policy: ChildStepPolicy;
+  readonly result: unknown;
+  readonly dependencies: SubagentChildRuntimeDependencies;
+};
+
+/**
+ * Atomically writes a delegated result through injected file-system
+ * operations.
+ */
+export const writeChildResult = ({
+  policy,
+  result,
+  dependencies,
+}: WriteChildResultOptions): void => {
+  if (dependencies.fileSystem.exists(policy.resultPath)) {
+    throw new Error('Delegated workflow step already produced a result');
+  }
+
+  const temporaryPath = `${policy.resultPath}.${dependencies.createUniqueId()}.tmp`;
+  try {
+    dependencies.fileSystem.writeExclusive(
+      temporaryPath,
+      JSON.stringify(result),
+    );
+    dependencies.fileSystem.rename(temporaryPath, policy.resultPath);
+  } catch (error) {
+    try {
+      dependencies.fileSystem.unlink(temporaryPath);
+    } catch {
+      // The temporary file may not have been created.
+    }
+    throw error;
+  }
+};
+
+type RepositoryMutationOptions = {
+  readonly toolName: string;
+  readonly input: Readonly<Record<string, unknown>>;
+  readonly policy: ChildStepPolicy;
+  readonly dependencies: SubagentChildRuntimeDependencies;
+};
+
+/**
+ * Returns a policy error when a file mutation escapes the reviewed repository.
+ */
+export const repositoryMutationError = ({
+  toolName,
+  input,
+  policy,
+  dependencies,
+}: RepositoryMutationOptions): string | undefined => {
+  if (!policy.repositoryCwd || !FILE_MUTATION_TOOLS.has(toolName)) return;
+  if (typeof input.path !== 'string' || !input.path.trim()) {
+    return `${toolName} must name a path inside the reviewed repository root`;
+  }
+
+  const candidate = resolve(dependencies.currentWorkingDirectory(), input.path);
+  const root = resolve(policy.repositoryCwd);
+  if (!pathIsInside(root, candidate)) {
+    return `${toolName} path is outside the reviewed repository root "${policy.repositoryCwd}"`;
+  }
+
+  let canonicalRoot: string;
+  try {
+    if (!dependencies.fileSystem.stat(root).isDirectory()) {
+      throw new Error('not a directory');
+    }
+    canonicalRoot = dependencies.fileSystem.realPath(root);
+  } catch {
+    return `reviewed repository root is not an existing directory: ${policy.repositoryCwd}`;
+  }
+  const canonicalAncestor = nearestCanonicalAncestor(candidate, dependencies);
+  if (
+    canonicalAncestor === undefined ||
+    !pathIsInside(canonicalRoot, canonicalAncestor)
+  ) {
+    return `${toolName} path is outside the reviewed repository root "${policy.repositoryCwd}"`;
+  }
+  return;
+};

package/src/integrations/subagents/child-runtime-policy.ts

@@ -0,0 +1,83 @@
+import type { WorkflowStep } from '../../config/types.ts';
+import type { ChildStepPolicy } from './child-policy-types.ts';
+
+/**
+ * Projects a delegated policy into the workflow step shape used by policy
+ * authorization.
+ */
+export const childPolicyStep = (policy: ChildStepPolicy): WorkflowStep => ({
+  title: policy.stepTitle,
+  prompt: { inline: 'Delegated workflow step' },
+  subagent: {
+    agent: policy.agent,
+    context: 'fresh',
+    timeoutMs: 900_000,
+    artifacts: false,
+    retryToolFailures: false,
+  },
+  permissions: policy.permissions,
+  requires: { tools: [], extensions: [], skills: [] },
+  transitions: {},
+});
+
+/**
+ * Builds the deterministic system prompt that describes the active child
+ * policy.
+ */
+export const childSystemPrompt = (policy: ChildStepPolicy): string => {
+  const hasPauseOutcome = policy.pauseOutcomes.length > 0;
+  return [
+    '# Pi Workflows delegated step',
+    '',
+    `Workflow: ${policy.workflowId}`,
+    `Run: ${policy.runId}`,
+    `Step: ${policy.stepId} (${policy.stepTitle})`,
+    '',
+    'The parent workflow harness owns orchestration and state transitions.',
+    'Perform only this delegated step. Its child-side tool policy is enforced.',
+    'When finished, call `structured_output` exactly once and as the only tool call in that message.',
+    'Pass the workflow result as its `value`: outcome, summary, and optional artifact.',
+    `Valid outcomes: ${policy.outcomes.join(', ')}`,
+    `Pause outcomes: ${policy.pauseOutcomes.join(', ') || '(none)'}`,
+    `Summary limit: ${policy.summaryMaxChars} characters`,
+    ...(policy.gateSubmitOutcome
+      ? [
+          `Outcome "${policy.gateSubmitOutcome}" requires the complete gate artifact.`,
+        ]
+      : []),
+    ...(hasPauseOutcome
+      ? [
+          `If the workflow definition or environment is wrong, choose a pause outcome (${policy.pauseOutcomes.join(', ')}).`,
+        ]
+      : [
+          'If the workflow definition or environment is wrong, do not fabricate success or call the completion tool; end with a concise declarative error so the parent pauses the step.',
+        ]),
+    'This is a non-interactive workflow child. Never call contact_supervisor, subagent_supervisor, or intercom.',
+    ...(policy.gateSubmitOutcome
+      ? [
+          'Put every unresolved decision in the gate artifact with evidence, options, a recommendation, and an adopted default; do not ask a terminal question.',
+        ]
+      : hasPauseOutcome
+        ? [
+            'Treat the step instructions and incoming handoff as the final execution contract.',
+            'If that contract is missing, stale, or contradictory, finish with a pause outcome and describe the unresolved contract and evidence declaratively in the summary; do not ask a terminal question.',
+          ]
+        : [
+            'Treat the step instructions and incoming handoff as the final execution contract.',
+            'If that contract is missing, stale, or contradictory, do not fabricate success or call the completion tool; end with a concise declarative error so the parent pauses the step. Do not ask a terminal question.',
+          ]),
+    ...(policy.repositoryCwd
+      ? [
+          `Reviewed repository root: ${policy.repositoryCwd}`,
+          ...(policy.bootstrapCwd
+            ? [
+                `Bootstrap directory: ${policy.bootstrapCwd}`,
+                'The reviewed repository root does not exist yet. Run only its exact approved setup command first, then use absolute paths under the reviewed repository root for every edit and write. Never mutate the bootstrap directory.',
+              ]
+            : [
+                'Keep every edit and write inside the reviewed repository root.',
+              ]),
+        ]
+      : []),
+  ].join('\n');
+};

package/src/integrations/subagents/child-runtime-types.ts

@@ -0,0 +1,30 @@
+export type ChildRuntimePathInspection = {
+  readonly isDirectory: () => boolean;
+  readonly isFile: () => boolean;
+  readonly isSymbolicLink: () => boolean;
+};
+
+export type ChildRuntimeFileSystem = {
+  readonly exists: (path: string) => boolean;
+  readonly inspect: (path: string) => ChildRuntimePathInspection;
+  readonly readText: (path: string) => string;
+  readonly realPath: (path: string) => string;
+  readonly rename: (source: string, destination: string) => void;
+  readonly stat: (path: string) => ChildRuntimePathInspection;
+  readonly unlink: (path: string) => void;
+  readonly writeExclusive: (path: string, content: string) => void;
+};
+
+export type SubagentChildRuntimeDependencies = {
+  readonly fileSystem: ChildRuntimeFileSystem;
+  readonly createUniqueId: () => string;
+  readonly currentWorkingDirectory: () => string;
+  readonly environmentChildAgent: () => string | undefined;
+  readonly temporaryDirectory: () => string;
+  readonly tokensAreEqual: (actual: string, expected: string) => boolean;
+};
+
+export type SubagentChildRuntimeOptions = {
+  readonly childAgent?: string;
+  readonly dependencies?: SubagentChildRuntimeDependencies;
+};