@tt-a1i/openpi 0.1.0

package/extensions/workflows/journal.ts

@@ -0,0 +1,188 @@
+/**
+ * Resume journal: cache agent results by call content so a re-run can replay
+ * the calls that did not change.
+ *
+ * Keying is by content, NOT by call ordinal, and that is load-bearing.
+ * `pipeline()` deliberately has no barrier between stages, so the order in
+ * which agent calls are issued depends on how long each agent actually took:
+ *
+ *   stage1 latencies {a:40,b:5,c:20} -> s1:a#1 s1:b#2 s1:c#3 s2:b#4 s2:c#5 s2:a#6
+ *   stage1 latencies {a:5,b:40,c:20} -> s1:a#1 s1:b#2 s1:c#3 s2:a#4 s2:c#5 s2:b#6
+ *
+ * Same script, same args, but #4 is a different call each time. Replaying by
+ * ordinal would hand one item's cached result to another — a silently wrong
+ * answer, which is worse than no resume at all. Hashing the content makes
+ * replay order-independent.
+ *
+ * It also means non-determinism in a script (`Date.now()` in a prompt) can only
+ * cost cache hits, never correctness: a changed prompt simply misses.
+ */
+
+import { createHash } from "node:crypto";
+
+/** Cap on the whole journal artifact; oldest entries are dropped first. */
+export const JOURNAL_MAX_BYTES = 2 * 1024 * 1024;
+// Version 1 did not record side-effect eligibility or cwd/resource identity.
+// Reject it rather than risk replaying an old write-capable call.
+export const JOURNAL_VERSION = 2;
+
+/** The replay payload: exactly the fields a script observes from agent(). */
+export interface JournalEntry {
+  readonly key: string;
+  readonly output: string;
+  readonly structured?: unknown;
+}
+
+export interface WorkflowJournal {
+  readonly version: number;
+  readonly entries: readonly JournalEntry[];
+}
+
+/**
+ * Only semantic options change what an agent produces, so only these are
+ * hashed. Callers pass their whole options object; `label` and `phase` are
+ * display only, and renaming a label must not invalidate an identical call.
+ */
+interface KeyedCallOptions {
+  /** Canonical model/effort and resolved Agent Type semantics. */
+  readonly execution?: unknown;
+  readonly schema?: unknown;
+  readonly model?: unknown;
+  readonly provider?: unknown;
+  readonly effort?: unknown;
+}
+
+/** Content hash identifying one agent call for replay. */
+export function agentCallKey(
+  prompt: string,
+  options: Readonly<KeyedCallOptions> = {},
+) {
+  const canonical = options.execution !== undefined;
+  const payload = stableSerialize({
+    prompt,
+    execution: options.execution,
+    schema: options.schema,
+    // Callers without a canonical execution snapshot retain the legacy key.
+    model:
+      !canonical && typeof options.model === "string"
+        ? options.model
+        : undefined,
+    provider:
+      !canonical && typeof options.provider === "string"
+        ? options.provider
+        : undefined,
+    effort:
+      !canonical && typeof options.effort === "string"
+        ? options.effort
+        : undefined,
+  });
+  return createHash("sha256").update(payload).digest("hex").slice(0, 32);
+}
+
+function stableSerialize(value: unknown): string {
+  if (value === undefined) return "undefined";
+  if (value === null || typeof value !== "object") return JSON.stringify(value);
+  if (Array.isArray(value)) {
+    return `[${value.map(stableSerialize).join(",")}]`;
+  }
+  // Key order must not affect the hash: two schemas that differ only in
+  // property order are the same schema.
+  const record = value as Record<string, unknown>;
+  const parts = Object.keys(record)
+    .sort()
+    .filter((key) => record[key] !== undefined)
+    .map((key) => `${JSON.stringify(key)}:${stableSerialize(record[key])}`);
+  return `{${parts.join(",")}}`;
+}
+
+/**
+ * Replay lookup over a prior run's journal. A key can legitimately repeat (a
+ * script calling the same prompt twice), so each key keeps its own cursor and
+ * the Nth occurrence consumes the Nth recorded result.
+ */
+export function createReplayCache(journal: WorkflowJournal | undefined) {
+  const byKey = new Map<string, JournalEntry[]>();
+  for (const entry of journal?.entries ?? []) {
+    const bucket = byKey.get(entry.key);
+    if (bucket) bucket.push(entry);
+    else byKey.set(entry.key, [entry]);
+  }
+  const cursors = new Map<string, number>();
+  let replayed = 0;
+
+  return {
+    /** Consume the next cached result for this key, or undefined on a miss. */
+    take(key: string) {
+      const bucket = byKey.get(key);
+      if (!bucket) return undefined;
+      const cursor = cursors.get(key) ?? 0;
+      const entry = bucket[cursor];
+      if (!entry) return undefined;
+      cursors.set(key, cursor + 1);
+      replayed++;
+      return entry;
+    },
+    /** How many calls this run has replayed so far. */
+    get replayed() {
+      return replayed;
+    },
+    /** Entries available from the source run. */
+    get available() {
+      return journal?.entries.length ?? 0;
+    },
+  };
+}
+
+export type ReplayCache = ReturnType<typeof createReplayCache>;
+
+/**
+ * Trim to the artifact cap by dropping the OLDEST entries, so a long run keeps
+ * the results a re-run is most likely to still want. Reports what was dropped:
+ * silent truncation would read as a naturally poor hit rate.
+ *
+ * Sized with plain JSON.stringify, NOT safeStringify: the latter replaces an
+ * over-cap value with a `{truncated, preview}` stub, which is always small, so
+ * measuring with it would always look under budget and then hand the writer a
+ * journal that serializes to a useless preview string.
+ */
+export function boundedJournal(entries: readonly JournalEntry[]) {
+  const size = (kept: readonly JournalEntry[]) =>
+    Buffer.byteLength(
+      JSON.stringify({ version: JOURNAL_VERSION, entries: kept }, null, 2),
+      "utf8",
+    );
+
+  let kept = [...entries];
+  let dropped = 0;
+  while (kept.length > 0 && size(kept) > JOURNAL_MAX_BYTES) {
+    kept = kept.slice(1);
+    dropped++;
+  }
+  return { journal: { version: JOURNAL_VERSION, entries: kept }, dropped };
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/**
+ * Lenient parse: resume is an optimization, so anything unreadable degrades to
+ * "no cache" rather than failing the run.
+ */
+export function parseJournal(value: unknown): WorkflowJournal | undefined {
+  if (!isRecord(value)) return undefined;
+  if (value.version !== JOURNAL_VERSION) return undefined;
+  if (!Array.isArray(value.entries)) return undefined;
+  const entries: JournalEntry[] = [];
+  for (const raw of value.entries) {
+    if (!isRecord(raw)) continue;
+    if (typeof raw.key !== "string" || !raw.key) continue;
+    if (typeof raw.output !== "string") continue;
+    entries.push({
+      key: raw.key,
+      output: raw.output,
+      ...(raw.structured !== undefined ? { structured: raw.structured } : {}),
+    });
+  }
+  return { version: JOURNAL_VERSION, entries };
+}

package/extensions/workflows/meta.ts

@@ -0,0 +1,250 @@
+import {
+  parse,
+  type ArrayExpression,
+  type ExportNamedDeclaration,
+  type Expression,
+  type Identifier,
+  type Literal,
+  type ObjectExpression,
+  type Program,
+  type Property,
+  type VariableDeclaration,
+} from "acorn";
+import { sanitizeTerminalText } from "../shared/terminal-text.ts";
+
+/** Static workflow metadata and source preparation helpers. */
+
+export interface WorkflowPhase {
+  title: string;
+  detail?: string;
+}
+
+export interface WorkflowMeta {
+  name?: string;
+  description?: string;
+  phases: WorkflowPhase[];
+}
+
+export interface PreparedWorkflowScript {
+  /** Script body with the metadata declaration removed. */
+  source: string;
+  meta: WorkflowMeta;
+}
+
+function parseProgram(source: string): Program {
+  return parse(source, {
+    ecmaVersion: "latest",
+    sourceType: "module",
+    allowReturnOutsideFunction: true,
+  });
+}
+
+function isIdentifier(node: Expression, name?: string): node is Identifier {
+  return (
+    node.type === "Identifier" && (name === undefined || node.name === name)
+  );
+}
+
+function isLiteral(node: Expression): node is Literal {
+  return node.type === "Literal";
+}
+
+function isProperty(
+  node: ObjectExpression["properties"][number],
+): node is Property {
+  return node.type === "Property";
+}
+
+function propertyName(property: Property) {
+  if (property.computed || property.kind !== "init" || property.method) {
+    return undefined;
+  }
+  if (isIdentifier(property.key)) return property.key.name;
+  if (isLiteral(property.key) && typeof property.key.value === "string") {
+    return property.key.value;
+  }
+  return undefined;
+}
+
+/**
+ * Convert an Acorn expression to data without evaluating source. Only plain
+ * object/array/primitive literals are accepted. Getters, methods, spreads,
+ * computed keys, templates, identifiers, and calls all fail closed.
+ */
+function literalValue(node: Expression, depth = 0): unknown {
+  if (depth > 8) throw new Error("workflow metadata is nested too deeply");
+  if (isLiteral(node)) {
+    if (
+      node.value === null ||
+      typeof node.value === "string" ||
+      typeof node.value === "number" ||
+      typeof node.value === "boolean"
+    ) {
+      return node.value;
+    }
+    throw new Error("workflow metadata contains an unsupported literal");
+  }
+  if (node.type === "ArrayExpression") {
+    const arrayNode: ArrayExpression = node;
+    return arrayNode.elements.map((element) => {
+      if (!element || element.type === "SpreadElement") {
+        throw new Error(
+          "workflow metadata arrays cannot contain holes or spreads",
+        );
+      }
+      return literalValue(element, depth + 1);
+    });
+  }
+  if (node.type === "ObjectExpression") {
+    const objectNode: ObjectExpression = node;
+    const value: Record<string, unknown> = Object.create(null);
+    for (const item of objectNode.properties) {
+      if (!isProperty(item)) {
+        throw new Error("workflow metadata objects cannot contain spreads");
+      }
+      const key = propertyName(item);
+      if (key === undefined || item.shorthand) {
+        throw new Error(
+          "workflow metadata keys and values must be plain literals",
+        );
+      }
+      value[key] = literalValue(item.value, depth + 1);
+    }
+    return value;
+  }
+  throw new Error("workflow metadata must contain only static literals");
+}
+
+function cleanMetaLine(value: string, maxLength: number) {
+  return sanitizeTerminalText(value)
+    .replace(/\s+/g, " ")
+    .trim()
+    .slice(0, maxLength);
+}
+
+function sanitizeMeta(value: unknown): WorkflowMeta {
+  const meta: WorkflowMeta = { phases: [] };
+  if (!value || typeof value !== "object") return meta;
+  const raw = value as {
+    name?: unknown;
+    description?: unknown;
+    phases?: unknown;
+  };
+  if (typeof raw.name === "string") {
+    const name = cleanMetaLine(raw.name, 160);
+    if (name) meta.name = name;
+  }
+  if (typeof raw.description === "string") {
+    const description = cleanMetaLine(raw.description, 2_000);
+    if (description) meta.description = description;
+  }
+  if (Array.isArray(raw.phases)) {
+    for (const item of raw.phases.slice(0, 64)) {
+      if (!item || typeof item !== "object") continue;
+      const phase = item as { title?: unknown; detail?: unknown };
+      if (typeof phase.title !== "string") continue;
+      const title = cleanMetaLine(phase.title, 160);
+      if (!title) continue;
+      const detail =
+        typeof phase.detail === "string"
+          ? cleanMetaLine(phase.detail, 2_000)
+          : "";
+      meta.phases.push({ title, ...(detail ? { detail } : {}) });
+    }
+  }
+  return meta;
+}
+
+function metadataDeclaration(statement: Program["body"][number]) {
+  if (statement.type !== "ExportNamedDeclaration") return undefined;
+  const exported: ExportNamedDeclaration = statement;
+  if (
+    exported.source ||
+    exported.specifiers.length > 0 ||
+    exported.declaration?.type !== "VariableDeclaration"
+  ) {
+    throw new Error(
+      "workflow scripts may only export a static `const meta = {...}` declaration",
+    );
+  }
+  const declaration: VariableDeclaration = exported.declaration;
+  if (declaration.kind !== "const" || declaration.declarations.length !== 1) {
+    throw new Error(
+      "workflow metadata must be declared as `export const meta = {...}`",
+    );
+  }
+  const declarator = declaration.declarations[0];
+  if (
+    declarator.id.type !== "Identifier" ||
+    declarator.id.name !== "meta" ||
+    !declarator.init
+  ) {
+    throw new Error("workflow scripts may only export a `meta` declaration");
+  }
+  return { exported, initializer: declarator.init };
+}
+
+/**
+ * Parse a workflow as JavaScript, reject module syntax other than the metadata
+ * API, statically decode metadata, and remove that declaration from the body.
+ * Source inside strings, comments, regexes, and templates is never rewritten.
+ */
+export function prepareWorkflowScript(source: string): PreparedWorkflowScript {
+  const program = parseProgram(source);
+  let meta: WorkflowMeta = { phases: [] };
+  let metadataRange: { start: number; end: number } | undefined;
+
+  for (const statement of program.body) {
+    if (statement.type === "ImportDeclaration") {
+      throw new Error("workflow scripts cannot use static imports");
+    }
+    if (
+      statement.type === "ExportDefaultDeclaration" ||
+      statement.type === "ExportAllDeclaration"
+    ) {
+      throw new Error(
+        "workflow scripts may only export a static `const meta = {...}` declaration",
+      );
+    }
+    const declaration = metadataDeclaration(statement);
+    if (!declaration) continue;
+    if (metadataRange)
+      throw new Error("workflow metadata may only be declared once");
+    meta = sanitizeMeta(literalValue(declaration.initializer));
+    metadataRange = {
+      start: declaration.exported.start,
+      end: declaration.exported.end,
+    };
+  }
+
+  if (!metadataRange) return { source, meta };
+  // Preserve line numbers for parse/runtime errors while removing every byte of
+  // executable metadata. A semicolon keeps adjacent statements separated.
+  const removed = source.slice(metadataRange.start, metadataRange.end);
+  const replacement = `;${removed.slice(1).replace(/[^\n\r]/g, " ")}`;
+  return {
+    source:
+      source.slice(0, metadataRange.start) +
+      replacement +
+      source.slice(metadataRange.end),
+    meta,
+  };
+}
+
+const metaCache = new Map<string, WorkflowMeta>();
+const META_CACHE_LIMIT = 32;
+
+/** Safe metadata extraction for render paths. Invalid/partial scripts are empty. */
+export function extractMeta(script: string): WorkflowMeta {
+  const cached = metaCache.get(script);
+  if (cached) return cached;
+  let meta: WorkflowMeta = { phases: [] };
+  try {
+    meta = prepareWorkflowScript(script).meta;
+  } catch {
+    // Renderers must tolerate partial model output and invalid scripts.
+  }
+  if (metaCache.size >= META_CACHE_LIMIT) metaCache.clear();
+  metaCache.set(script, meta);
+  return meta;
+}