@osolmaz/pi-workflows 0.12.0 → 0.13.0

package/schemas/human-decision-request-v2.schema.json

@@ -1,69 +0,0 @@
-{
-  "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://github.com/osolmaz/pi-workflows/schemas/human-decision-request-v2.schema.json",
-  "title": "pi-workflows human decision request v2",
-  "type": "object",
-  "additionalProperties": false,
-  "required": [
-    "schema",
-    "decisionId",
-    "requestDigest",
-    "subjectDigest",
-    "presentationDigest",
-    "runId",
-    "workflowName",
-    "nodeId",
-    "attemptId",
-    "audience",
-    "title",
-    "subject",
-    "presentation",
-    "revision",
-    "choices",
-    "createdAt"
-  ],
-  "properties": {
-    "schema": { "const": "pi-workflows.human-decision-request.v2" },
-    "decisionId": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,199}$" },
-    "requestDigest": { "type": "string", "pattern": "^sha256:[a-f0-9]{64}$" },
-    "subjectDigest": { "type": "string", "pattern": "^sha256:[a-f0-9]{64}$" },
-    "presentationDigest": { "type": "string", "pattern": "^sha256:[a-f0-9]{64}$" },
-    "runId": { "type": "string" },
-    "workflowName": { "type": "string" },
-    "nodeId": { "type": "string" },
-    "attemptId": { "type": "string" },
-    "audience": { "type": "string" },
-    "title": { "type": "string", "minLength": 1 },
-    "subject": true,
-    "presentation": {
-      "$ref": "decision-presentation-v1.schema.json"
-    },
-    "revision": { "type": "integer", "minimum": 1 },
-    "choices": {
-      "type": "object",
-      "minProperties": 1,
-      "additionalProperties": {
-        "type": "object",
-        "additionalProperties": false,
-        "required": ["label"],
-        "properties": {
-          "label": { "type": "string", "minLength": 1 },
-          "input": {
-            "type": "object",
-            "additionalProperties": false,
-            "required": ["kind", "name", "prompt", "minLength", "maxLength"],
-            "properties": {
-              "kind": { "const": "text" },
-              "name": { "type": "string" },
-              "prompt": { "type": "string", "minLength": 1 },
-              "minLength": { "type": "integer", "minimum": 0 },
-              "maxLength": { "type": "integer", "minimum": 1 }
-            }
-          }
-        }
-      }
-    },
-    "createdAt": { "type": "string", "format": "date-time" },
-    "expiresAt": { "type": "string", "format": "date-time" }
-  }
-}

package/schemas/human-decision-resolution-v2.schema.json

@@ -1,27 +0,0 @@
-{
-  "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://github.com/osolmaz/pi-workflows/schemas/human-decision-resolution-v2.schema.json",
-  "title": "pi-workflows human decision resolution v2",
-  "oneOf": [
-    {
-      "type": "object",
-      "additionalProperties": false,
-      "required": ["schema", "outcome", "decision"],
-      "properties": {
-        "schema": { "const": "pi-workflows.human-decision-resolution.v2" },
-        "outcome": { "const": "accepted" },
-        "decision": { "$ref": "human-decision-accepted-v2.schema.json" }
-      }
-    },
-    {
-      "type": "object",
-      "additionalProperties": false,
-      "required": ["schema", "outcome", "cancellation"],
-      "properties": {
-        "schema": { "const": "pi-workflows.human-decision-resolution.v2" },
-        "outcome": { "const": "cancelled" },
-        "cancellation": { "$ref": "human-decision-cancellation-v1.schema.json" }
-      }
-    }
-  ]
-}

package/src/builtins/sanity-check-session.ts

@@ -1,205 +0,0 @@
-import fs from "node:fs/promises";
-import os from "node:os";
-import path from "node:path";
-import { runCommandBatch, type CommandBatchItemResult } from "../workflows/command-batch.js";
-import { extractJsonValue } from "../workflows/json.js";
-
-const SESSION_TIMEOUT_MS = 15 * 60_000;
-const SESSION_OUTPUT_CHARS = 1_000_000;
-const MAX_PROMPT_CHARS = 96_000;
-const MAX_ERROR_CHARS = 2_000;
-
-export type IsolatedReviewRequest = {
-  id: string;
-  prompt: string;
-};
-
-export type PiInvocation = {
-  command: string;
-  prefixArgs: string[];
-};
-
-export type IsolatedReviewOptions = {
-  invocation?: PiInvocation;
-  timeoutMs?: number;
-  maxOutputChars?: number;
-  maxConcurrency?: number;
-};
-
-export async function runIsolatedReviewSessions(
-  requests: IsolatedReviewRequest[],
-  cwd: string,
-  signal: AbortSignal,
-  options: IsolatedReviewOptions = {},
-): Promise<Record<string, unknown>> {
-  if (requests.length === 0) return {};
-  const ids = new Set<string>();
-  for (const request of requests) {
-    if (!/^[A-Za-z0-9][A-Za-z0-9._:-]{0,63}$/.test(request.id)) {
-      throw new Error(`Invalid isolated review id: ${request.id}`);
-    }
-    if (ids.has(request.id)) throw new Error(`Duplicate isolated review id: ${request.id}`);
-    ids.add(request.id);
-    if (request.prompt.length > MAX_PROMPT_CHARS) {
-      throw new Error(
-        `Isolated review prompt ${request.id} exceeds ${MAX_PROMPT_CHARS} characters`,
-      );
-    }
-  }
-
-  const promptDir = await fs.mkdtemp(path.join(os.tmpdir(), "pi-sanity-check-"));
-  try {
-    const invocation = options.invocation ?? resolvePiInvocation();
-    const items = await Promise.all(
-      requests.map(async (request) => {
-        const promptPath = path.join(promptDir, `${request.id}.md`);
-        await fs.writeFile(promptPath, request.prompt, { encoding: "utf8", mode: 0o600 });
-        return {
-          id: request.id,
-          command: invocation.command,
-          args: [
-            ...invocation.prefixArgs,
-            "--mode",
-            "json",
-            "--print",
-            "--no-session",
-            "--no-extensions",
-            "--no-skills",
-            "--no-context-files",
-            "--tools",
-            "read,grep,find,ls",
-            `@${promptPath}`,
-            "Follow the attached review instructions and return only the requested JSON.",
-          ],
-          cwd,
-          timeoutMs: options.timeoutMs ?? SESSION_TIMEOUT_MS,
-          maxOutputChars: options.maxOutputChars ?? SESSION_OUTPUT_CHARS,
-        };
-      }),
-    );
-    const batch = await runCommandBatch(
-      {
-        items,
-        maxConcurrency: options.maxConcurrency ?? requests.length,
-      },
-      { signal },
-    );
-    const outputs: Record<string, unknown> = {};
-    for (const item of batch.items) {
-      outputs[item.id] = parseSessionResult(item);
-    }
-    return outputs;
-  } finally {
-    await fs.rm(promptDir, { recursive: true, force: true });
-  }
-}
-
-export function resolvePiInvocation(): PiInvocation {
-  const currentScript = process.argv[1];
-  const isBunVirtualScript = currentScript?.startsWith("/$bunfs/root/");
-  const scriptName = currentScript === undefined ? "" : path.basename(currentScript).toLowerCase();
-  const isPiPackageCli =
-    scriptName === "cli.js" &&
-    currentScript?.split(path.sep).some((segment) => segment === "pi-coding-agent");
-  const isPiScript = /^(pi|pi\.[cm]?js)$/.test(scriptName) || isPiPackageCli;
-  if (currentScript && !isBunVirtualScript && isPiScript) {
-    return {
-      command: process.execPath,
-      prefixArgs: [currentScript, ...inheritedPiArgs(process.argv.slice(2))],
-    };
-  }
-  const execName = path.basename(process.execPath).toLowerCase();
-  if (/^pi(\.exe)?$/.test(execName)) {
-    return { command: process.execPath, prefixArgs: inheritedPiArgs(process.argv.slice(1)) };
-  }
-  return { command: "pi", prefixArgs: [] };
-}
-
-export function parsePiJsonOutput(stdout: string): unknown {
-  let finalText = "";
-  for (const line of stdout.split("\n")) {
-    if (!line.trim()) continue;
-    let event: Record<string, unknown>;
-    try {
-      event = JSON.parse(line) as Record<string, unknown>;
-    } catch {
-      continue;
-    }
-    if (event.type !== "message_end" || !isRecord(event.message)) continue;
-    const message = event.message;
-    if (message.role !== "assistant") continue;
-    if (message.stopReason === "error" || message.stopReason === "aborted") {
-      throw new Error(
-        boundedError(
-          typeof message.errorMessage === "string"
-            ? message.errorMessage
-            : `Pi session stopped with ${String(message.stopReason)}`,
-        ),
-      );
-    }
-    const text = messageText(message.content);
-    if (text.trim()) finalText = text;
-  }
-  if (!finalText) throw new Error("Isolated Pi session returned no assistant JSON output");
-  return extractJsonValue(finalText);
-}
-
-function parseSessionResult(result: CommandBatchItemResult): unknown {
-  if (result.outcome !== "succeeded") {
-    throw new Error(
-      `Isolated Pi session ${result.id} ${result.outcome}: ${boundedError(result.error ?? result.stderr)}`,
-    );
-  }
-  if (result.stdoutTruncated) {
-    throw new Error(`Isolated Pi session ${result.id} exceeded its output limit`);
-  }
-  try {
-    return parsePiJsonOutput(result.stdout);
-  } catch (error) {
-    throw new Error(
-      `Isolated Pi session ${result.id} returned invalid output: ${boundedError(errorMessage(error))}`,
-    );
-  }
-}
-
-function inheritedPiArgs(args: string[]): string[] {
-  const inherited: string[] = [];
-  for (let index = 0; index < args.length; index += 1) {
-    const arg = args[index];
-    if (arg === "--offline") {
-      inherited.push(arg);
-      continue;
-    }
-    if (arg !== "--provider" && arg !== "--model" && arg !== "--thinking") continue;
-    const value = args[index + 1];
-    if (value !== undefined) {
-      inherited.push(arg, value);
-      index += 1;
-    }
-  }
-  return inherited;
-}
-
-function messageText(content: unknown): string {
-  if (typeof content === "string") return content;
-  if (!Array.isArray(content)) return "";
-  return content
-    .map((part) =>
-      isRecord(part) && part.type === "text" && typeof part.text === "string" ? part.text : "",
-    )
-    .filter(Boolean)
-    .join("\n");
-}
-
-function isRecord(value: unknown): value is Record<string, unknown> {
-  return value !== null && typeof value === "object" && !Array.isArray(value);
-}
-
-function errorMessage(error: unknown): string {
-  return error instanceof Error ? error.message : String(error);
-}
-
-function boundedError(message: string): string {
-  const value = message.trim() || "unknown failure";
-  return value.length <= MAX_ERROR_CHARS ? value : `${value.slice(0, MAX_ERROR_CHARS)}…`;
-}

package/src/workflows/artifacts.ts

@@ -1,188 +0,0 @@
-import { createHash } from "node:crypto";
-import fs from "node:fs/promises";
-import path from "node:path";
-import type { ArtifactRef, ArtifactValue } from "./types.js";
-
-/**
- * Value externalization for run bundles (see docs/run-bundles.md): string
- * leaves larger than the threshold are written once, content-addressed, under
- * `artifacts/` and replaced by `{ "$artifact": ref }`. Because artifacts are
- * immutable and deduplicated by hash, the same output appearing in `outputs`,
- * `results`, `steps`, and the trace costs one file plus small references.
- */
-
-export const ARTIFACT_THRESHOLD_BYTES = 4096;
-export const ARTIFACTS_DIR = "artifacts";
-
-const ARTIFACT_KEY = "$artifact";
-const ESCAPED_KEY = "$escaped";
-
-export function isArtifactValue(value: unknown): value is ArtifactValue {
-  return (
-    typeof value === "object" &&
-    value !== null &&
-    !Array.isArray(value) &&
-    Object.keys(value).length === 1 &&
-    ARTIFACT_KEY in value
-  );
-}
-
-function isEscapedValue(value: unknown): value is { $escaped: Record<string, unknown> } {
-  return (
-    typeof value === "object" &&
-    value !== null &&
-    !Array.isArray(value) &&
-    Object.keys(value).length === 1 &&
-    ESCAPED_KEY in value
-  );
-}
-
-/** True for a single-key object that would be misread as a sentinel. */
-function needsEscape(value: Record<string, unknown>): boolean {
-  const keys = Object.keys(value);
-  return keys.length === 1 && (keys[0] === ARTIFACT_KEY || keys[0] === ESCAPED_KEY);
-}
-
-/**
- * Writes externalized string leaves for one run bundle. Instances serialize
- * their writes and deduplicate by content hash, so encoding the same large
- * string in several value positions touches the filesystem once.
- */
-export class ArtifactWriter {
-  private readonly runDir: string;
-  private readonly written = new Set<string>();
-  private chain: Promise<unknown> = Promise.resolve();
-  private dirCreated = false;
-
-  constructor(runDir: string) {
-    this.runDir = runDir;
-  }
-
-  /** True once any artifact exists for this run. */
-  get hasArtifacts(): boolean {
-    return this.written.size > 0;
-  }
-
-  async externalize(text: string): Promise<ArtifactValue> {
-    const bytes = Buffer.from(text, "utf8");
-    const sha256 = createHash("sha256").update(bytes).digest("hex");
-    const relativePath = `${ARTIFACTS_DIR}/sha256-${sha256}.txt`;
-    const task = this.chain.then(async () => {
-      if (this.written.has(sha256)) {
-        return;
-      }
-      if (!this.dirCreated) {
-        await fs.mkdir(path.join(this.runDir, ARTIFACTS_DIR), { recursive: true, mode: 0o700 });
-        this.dirCreated = true;
-      }
-      const filePath = path.join(this.runDir, relativePath);
-      // Content-addressed files are immutable; an existing file is complete
-      // unless a previous crash left a partial write, which the temp-rename
-      // pattern prevents.
-      const tempPath = `${filePath}.${process.pid}.tmp`;
-      await fs.writeFile(tempPath, bytes, { mode: 0o600 });
-      await fs.rename(tempPath, filePath);
-      this.written.add(sha256);
-    });
-    this.chain = task.catch(() => undefined);
-    await task;
-    return {
-      $artifact: {
-        path: relativePath,
-        mediaType: "text/plain",
-        bytes: bytes.byteLength,
-        sha256,
-      },
-    };
-  }
-}
-
-/**
- * Encode a persisted value: externalize large string leaves and escape
- * single-key `$artifact`/`$escaped` objects so the sentinel stays
- * unambiguous. Returns the original value when nothing changed.
- */
-export async function encodeValue(
-  value: unknown,
-  writer: ArtifactWriter,
-  thresholdBytes: number = ARTIFACT_THRESHOLD_BYTES,
-): Promise<unknown> {
-  if (typeof value === "string") {
-    if (Buffer.byteLength(value, "utf8") <= thresholdBytes) {
-      return value;
-    }
-    return await writer.externalize(value);
-  }
-  if (Array.isArray(value)) {
-    const encoded = await Promise.all(
-      value.map((item) => encodeValue(item, writer, thresholdBytes)),
-    );
-    return encoded.some((item, index) => item !== value[index]) ? encoded : value;
-  }
-  if (typeof value === "object" && value !== null) {
-    const record = value as Record<string, unknown>;
-    const entries = await Promise.all(
-      Object.entries(record).map(
-        async ([key, item]) => [key, await encodeValue(item, writer, thresholdBytes)] as const,
-      ),
-    );
-    const changed = entries.some(([key, item]) => item !== record[key]);
-    const encoded = changed ? Object.fromEntries(entries) : record;
-    return needsEscape(record) ? { [ESCAPED_KEY]: encoded } : encoded;
-  }
-  return value;
-}
-
-/**
- * Walk a persisted value, replacing every `$artifact` sentinel via `resolve`
- * and unwrapping `$escaped` objects. `resolve` may return the artifact
- * contents or a placeholder; it receives the reference untouched.
- */
-export function decodeValueWith(value: unknown, resolve: (ref: ArtifactRef) => unknown): unknown {
-  if (isArtifactValue(value)) {
-    return resolve(value.$artifact);
-  }
-  if (isEscapedValue(value)) {
-    // The unwrapped object is user data: process its children but do not
-    // re-test the object itself as a sentinel.
-    return decodeChildren(value.$escaped, resolve);
-  }
-  if (Array.isArray(value)) {
-    return value.map((item) => decodeValueWith(item, resolve));
-  }
-  if (typeof value === "object" && value !== null) {
-    return decodeChildren(value as Record<string, unknown>, resolve);
-  }
-  return value;
-}
-
-function decodeChildren(
-  record: Record<string, unknown>,
-  resolve: (ref: ArtifactRef) => unknown,
-): Record<string, unknown> {
-  return Object.fromEntries(
-    Object.entries(record).map(([key, item]) => [key, decodeValueWith(item, resolve)]),
-  );
-}
-
-/** Resolve every artifact reference in `value` by reading the bundle files. */
-export async function resolveArtifacts(value: unknown, runDir: string): Promise<unknown> {
-  const refs: ArtifactRef[] = [];
-  decodeValueWith(value, (ref) => {
-    refs.push(ref);
-    return null;
-  });
-  const contents = new Map<string, string>();
-  for (const ref of refs) {
-    if (contents.has(ref.path)) {
-      continue;
-    }
-    const resolved = path.resolve(runDir, ref.path);
-    // A reference must never escape the bundle directory.
-    if (!resolved.startsWith(path.resolve(runDir) + path.sep)) {
-      throw new Error(`Artifact path escapes the bundle: ${ref.path}`);
-    }
-    contents.set(ref.path, await fs.readFile(resolved, "utf8"));
-  }
-  return decodeValueWith(value, (ref) => contents.get(ref.path) ?? null);
-}

package/src/workflows/migrate-sources.ts

@@ -1,178 +0,0 @@
-import { randomUUID } from "node:crypto";
-import fs from "node:fs/promises";
-import path from "node:path";
-import type { BuiltinWorkflowCatalog } from "./catalog.js";
-import { WorkflowRunStore, listRunBundles } from "./store.js";
-import type { WorkflowRunState, WorkflowSource } from "./types.js";
-
-export type LegacySourceMigrationQueue = {
-  repairCanonicalWorkflowSourceRun(options: {
-    runId: string;
-    workflowName: string;
-    workflowSourceRef: string;
-    runnerId: string;
-    claimToken: string;
-    leaseMs: number;
-  }): "unchanged" | "claimed" | false;
-  claimLegacyWorkflowSourceRun(options: {
-    runId: string;
-    workflowName: string;
-    oldWorkflowPath: string;
-    workflowSourceRef: string;
-    runnerId: string;
-    claimToken: string;
-    leaseMs: number;
-  }): boolean;
-  parkWorkflowRun(options: { runId: string; claimToken: string }): boolean;
-  getWorkflowRun(runId: string):
-    | {
-        status: "queued" | "starting" | "running" | "parked" | "done" | "failed" | "cancelled";
-      }
-    | undefined;
-  setWorkflowRunOriginSession?(runId: string, originSessionId: string): boolean;
-};
-
-const MIGRATION_LEASE_MS = 30_000;
-
-export type LegacySourceMigrationResult = {
-  migratedRunIds: string[];
-  blocked: { runId: string; reason: string }[];
-};
-
-/** One bounded migration for nonterminal runs created before canonical sources. */
-export async function migrateLegacyWorkflowSources(options: {
-  catalog: BuiltinWorkflowCatalog;
-  store?: WorkflowRunStore;
-  queue?: LegacySourceMigrationQueue;
-}): Promise<LegacySourceMigrationResult> {
-  const store = options.store ?? new WorkflowRunStore();
-  const result: LegacySourceMigrationResult = { migratedRunIds: [], blocked: [] };
-  for (const bundle of await listRunBundles(store.outputRoot)) {
-    const state = bundle.state;
-    if (state.status !== "running" && state.status !== "waiting") continue;
-    if (
-      options.queue?.setWorkflowRunOriginSession !== undefined &&
-      bundle.sessionBinding !== null
-    ) {
-      options.queue.setWorkflowRunOriginSession(state.runId, bundle.sessionBinding.piSessionId);
-    }
-    if (state.workflowSource !== undefined) {
-      if (options.queue === undefined) continue;
-      const claimToken = randomUUID();
-      const repaired = options.queue.repairCanonicalWorkflowSourceRun({
-        runId: state.runId,
-        workflowName: state.workflowName,
-        workflowSourceRef: sourceRef(state.workflowSource),
-        runnerId: `source-migration-${process.pid}`,
-        claimToken,
-        leaseMs: MIGRATION_LEASE_MS,
-      });
-      if (repaired === false) {
-        // Another runner can own a canonical run during startup. Its source is
-        // already safe; the normal queue lease will make it claimable later.
-      } else if (
-        repaired === "claimed" &&
-        !options.queue.parkWorkflowRun({ runId: state.runId, claimToken })
-      ) {
-        result.blocked.push({
-          runId: state.runId,
-          reason: "canonical queue repair could not release its claim",
-        });
-      }
-      continue;
-    }
-    if (state.workflowPath === undefined || state.workflowHash === undefined) {
-      result.blocked.push({ runId: state.runId, reason: "legacy workflow identity is incomplete" });
-      continue;
-    }
-    const legacyPath = {
-      workflowName: state.workflowName,
-      workflowPath: state.workflowPath,
-    };
-    const pathEntry = options.catalog.legacyPathEntry(legacyPath);
-    let workflowSource: WorkflowSource;
-    let workflowSourceRef: string;
-    if (pathEntry === undefined) {
-      workflowSource = {
-        kind: "file",
-        path: path.resolve(state.workflowPath),
-        hash: state.workflowHash,
-      };
-      workflowSourceRef = workflowSource.path;
-    } else {
-      const legacy = options.catalog.matchLegacy({
-        ...legacyPath,
-        workflowHash: state.workflowHash,
-      });
-      if (legacy === undefined) {
-        const reason = `legacy built-in ${pathEntry.id} has an unknown source revision`;
-        result.blocked.push({ runId: state.runId, reason });
-        continue;
-      }
-      workflowSource = {
-        kind: "builtin",
-        id: legacy.entry.id,
-        revision: legacy.revision,
-      };
-      workflowSourceRef = legacy.entry.ref;
-    }
-    const claimToken = randomUUID();
-    const queueIsDone = options.queue?.getWorkflowRun(state.runId)?.status === "done";
-    if (
-      options.queue !== undefined &&
-      !queueIsDone &&
-      !options.queue.claimLegacyWorkflowSourceRun({
-        runId: state.runId,
-        workflowName: state.workflowName,
-        oldWorkflowPath: state.workflowPath,
-        workflowSourceRef,
-        runnerId: `source-migration-${process.pid}`,
-        claimToken,
-        leaseMs: MIGRATION_LEASE_MS,
-      })
-    ) {
-      result.blocked.push({
-        runId: state.runId,
-        reason: "matching queue row is active or unavailable",
-      });
-      continue;
-    }
-    const migrated: WorkflowRunState = {
-      ...state,
-      workflowSource,
-    };
-    delete migrated.workflowPath;
-    delete migrated.workflowHash;
-    const migratedManifest = {
-      ...bundle.manifest,
-      workflowSource: migrated.workflowSource,
-    };
-    delete (migratedManifest as typeof migratedManifest & { workflowPath?: string }).workflowPath;
-    // State is the migration commit point. Queue and manifest updates are
-    // idempotent, so a crash before this write can safely retry.
-    await writeJsonAtomic(path.join(bundle.runDir, "manifest.json"), migratedManifest);
-    await writeJsonAtomic(path.join(bundle.runDir, "state.json"), migrated);
-    if (
-      options.queue !== undefined &&
-      !queueIsDone &&
-      !options.queue.parkWorkflowRun({ runId: state.runId, claimToken })
-    ) {
-      result.blocked.push({
-        runId: state.runId,
-        reason: "migration completed but its queue claim could not be released",
-      });
-    }
-    result.migratedRunIds.push(state.runId);
-  }
-  return result;
-}
-
-function sourceRef(source: WorkflowSource): string {
-  return source.kind === "builtin" ? `builtin:${source.id}` : source.path;
-}
-
-async function writeJsonAtomic(filePath: string, value: unknown): Promise<void> {
-  const tempPath = `${filePath}.${process.pid}.${randomUUID()}.source-migration.tmp`;
-  await fs.writeFile(tempPath, `${JSON.stringify(value, null, 2)}\n`, { mode: 0o600 });
-  await fs.rename(tempPath, filePath);
-}