@mcrescenzo/opencode-workflows 0.1.0

package/workflow-kernel/session-access.js

@@ -0,0 +1,56 @@
+import { hasFunction } from "./text-json.js";
+
+export function sessionShape(pluginContext) {
+  return pluginContext.__workflowSessionShape ?? pluginContext.client?.__workflowSessionShape ?? "v1";
+}
+
+export function sessionApi(pluginContext) {
+  const session = pluginContext.client?.session ?? {};
+  const useV2 = sessionShape(pluginContext) === "v2";
+  return {
+    raw: session,
+    has(name) {
+      return hasFunction(session, name);
+    },
+    async create(input = {}) {
+      const body = {
+        ...(input.parentID ? { parentID: input.parentID } : {}),
+        ...(input.title ? { title: input.title } : {}),
+        ...(input.agent ? { agent: input.agent } : {}),
+        ...(input.model ? { model: input.model } : {}),
+        ...(input.permission ? { permission: input.permission } : {}),
+      };
+      return useV2
+        ? await session.create({ directory: input.directory, ...body })
+        : await session.create({ body, query: { directory: input.directory } });
+    },
+    async prompt(input = {}) {
+      const body = input.body ?? {};
+      return useV2
+        ? await session.prompt({ sessionID: input.sessionID, directory: input.directory, ...body })
+        : await session.prompt({ path: { id: input.sessionID }, query: { directory: input.directory }, body });
+    },
+    async promptAsync(input = {}) {
+      const body = input.body ?? {};
+      return useV2
+        ? await session.promptAsync({ sessionID: input.sessionID, directory: input.directory, ...body })
+        : await session.promptAsync({ path: { id: input.sessionID }, query: { directory: input.directory }, body });
+    },
+    async abort(input = {}) {
+      return useV2
+        ? await session.abort({ sessionID: input.sessionID, directory: input.directory })
+        : await session.abort({ path: { id: input.sessionID }, query: { directory: input.directory } });
+    },
+    async messages(input = {}) {
+      return useV2
+        ? await session.messages({ sessionID: input.sessionID, directory: input.directory, limit: input.limit })
+        : await session.messages({ path: { id: input.sessionID }, query: { directory: input.directory, limit: input.limit } });
+    },
+    async shell(input = {}) {
+      const body = input.body ?? {};
+      return useV2
+        ? await session.shell({ sessionID: input.sessionID, directory: input.directory, ...body })
+        : await session.shell({ path: { id: input.sessionID }, query: { directory: input.directory }, body });
+    },
+  };
+}

package/workflow-kernel/structured-output.js

@@ -0,0 +1,143 @@
+import Ajv from "ajv";
+
+import { MAX_RESULT_BYTES } from "./constants.js";
+import { hash, stableStringify } from "./text-json.js";
+
+export const ajv = new Ajv({ allErrors: true, strict: false });
+export const MAX_SCHEMA_SNAPSHOT_BYTES = 16 * 1024;
+
+const VALIDATOR_HASH_CACHE_MAX = 256;
+
+// Bounded, insertion-ordered validator cache keyed by canonical schema hash.
+// schema values originate from guest workflow source (untrusted per AGENTS.md/SECURITY.md)
+// and this cache lives for the whole plugin process, shared across every workflow run, so
+// it must be bounded to honor the "bound all module-level maps / no unbounded accumulation"
+// invariant. Uses the same oldest-first eviction as BoundedTimestampSet in
+// workflow-kernel/lifecycle-control.js (Map preserves insertion order).
+class BoundedValidatorCache {
+  constructor({ max = VALIDATOR_HASH_CACHE_MAX } = {}) {
+    this.max = max;
+    this.items = new Map();
+  }
+
+  get(key) {
+    return this.items.get(key);
+  }
+
+  set(key, value) {
+    if (this.items.has(key)) this.items.delete(key);
+    this.items.set(key, value);
+    while (this.items.size > this.max) {
+      const oldest = this.items.keys().next().value;
+      if (oldest === undefined) break;
+      this.items.delete(oldest);
+    }
+    return this;
+  }
+
+  get size() {
+    return this.items.size;
+  }
+}
+
+const validatorCache = new WeakMap();
+const validatorHashCache = new BoundedValidatorCache();
+
+// Maps a schema $id to the canonical content hash of the schema last compiled under it.
+// Ajv treats $id as a stable, unique content identity: ajv.getSchema($id) returns whatever
+// validator was FIRST registered under that id and never re-checks it against the schema
+// passed on this call. Guest workflow schemas are untrusted (AGENTS.md/SECURITY.md) and can
+// reuse one $id for a differently-shaped schema, which would otherwise be validated with the
+// stale wrong rules. We record the content hash per id so we can detect drift and
+// remove+recompile instead of trusting the id string forever. Bounded for the same
+// module-level-map reason as validatorHashCache.
+const registeredSchemaIdHashes = new BoundedValidatorCache();
+
+// Compile `schema` into an AJV validator, reusing an already-registered $id validator ONLY when
+// the schema content still hashes to what was registered under that $id. On content drift (a reused
+// $id carrying a different shape) the stale registration is removed before recompiling, so a payload
+// is never silently validated against a different schema's rules. Falls back to a plain compile for
+// schemas without a usable $id (AJV never rejects those as duplicate ids).
+export function compileSchemaWithIdentity(schema) {
+  if (!schema || typeof schema !== "object" || Array.isArray(schema)) return ajv.compile(schema);
+  const id = typeof schema.$id === "string" && schema.$id.trim() ? schema.$id : null;
+  if (!id) return ajv.compile(schema);
+  const schemaKey = hash(stableStringify(schema));
+  const existing = ajv.getSchema(id);
+  if (existing && registeredSchemaIdHashes.get(id) === schemaKey) return existing;
+  // Either the $id is registered with a different (or unverified) schema, or we hold no proof its
+  // content matches: drop the stale registration before compiling the schema passed on this call.
+  if (existing) ajv.removeSchema(id);
+  const validate = ajv.compile(schema);
+  registeredSchemaIdHashes.set(id, schemaKey);
+  return validate;
+}
+
+function compiledValidator(schema) {
+  if (!schema || typeof schema !== "object") return ajv.compile(schema);
+  let validate = validatorCache.get(schema);
+  if (validate) return validate;
+  const schemaKey = hash(stableStringify(schema));
+  validate = validatorHashCache.get(schemaKey);
+  if (!validate) {
+    // Content-cache miss: compile via the identity-checked path so a reused $id can't return a
+    // stale validator compiled for a different schema.
+    validate = compileSchemaWithIdentity(schema);
+    validatorHashCache.set(schemaKey, validate);
+  }
+  validatorCache.set(schema, validate);
+  return validate;
+}
+
+export function validateStructuredResult(schema, value) {
+  const validate = compiledValidator(schema);
+  if (validate(value)) return;
+  throw new Error(ajv.errorsText(validate.errors, { separator: "\n", dataVar: "result" }));
+}
+
+export function structuredFormat(schema) {
+  return { type: "json_schema", schema };
+}
+
+export function boundedSchemaSnapshot(schema, maxBytes = MAX_SCHEMA_SNAPSHOT_BYTES) {
+  if (!schema) return { status: "absent" };
+  const canonical = stableStringify(schema);
+  const bytes = Buffer.byteLength(canonical, "utf8");
+  const schemaHash = hash(canonical);
+  if (bytes > maxBytes) return { status: "oversized", bytes, hash: schemaHash };
+  return { status: "present", bytes, hash: schemaHash, schema };
+}
+
+
+export function structuredTextInstruction(schema) {
+  return [
+    "Your final response MUST be a single valid JSON object matching this JSON Schema.",
+    "Do not include markdown, code fences, commentary, or any text before or after the JSON.",
+    "JSON Schema:\n" + JSON.stringify(schema),
+  ].join("\n\n");
+}
+
+export function structuredCorrectiveInstruction(schema, validationMessage) {
+  return [
+    `Your previous response failed validation: ${String(validationMessage ?? "unknown validation error")}.`,
+    "Reply again with ONLY a corrected JSON object. Do not include markdown, code fences, commentary, or any text before or after the JSON.",
+    "JSON Schema:\n" + JSON.stringify(schema),
+  ].join("\n\n");
+}
+
+export function parseStructuredTextResult(text) {
+  const raw = String(text ?? "").trim();
+  if (!raw) throw new Error("Structured text fallback returned an empty response");
+  try {
+    return JSON.parse(raw);
+  } catch (e) {
+    const s = raw.indexOf("{"), t = raw.lastIndexOf("}");
+    if (s >= 0 && t > s) return JSON.parse(raw.slice(s, t + 1));
+    throw e;
+  }
+}
+
+export function assertResultSize(value) {
+  const bytes = Buffer.byteLength(JSON.stringify(value ?? null), "utf8");
+  if (bytes > MAX_RESULT_BYTES) throw new Error(`Workflow output exceeds ${MAX_RESULT_BYTES} bytes`);
+}

package/workflow-kernel/test-fix-drain-adapter.js

@@ -0,0 +1,119 @@
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+
+const execFileAsync = promisify(execFile);
+const DEFAULT_COMMAND_TIMEOUT_MS = 2 * 60 * 1000;
+const DEFAULT_COMMAND_MAX_BUFFER = 10 * 1024 * 1024;
+
+export async function defaultRunCommand(command, options = {}) {
+  const [bin, ...args] = Array.isArray(command) ? command : String(command).split(/\s+/).filter(Boolean);
+  if (!bin) throw new Error("test-fix adapter requires a test command");
+  try {
+    const result = await execFileAsync(bin, args, {
+      cwd: options.cwd,
+      encoding: "utf8",
+      timeout: Number.isFinite(options.timeoutMs) ? options.timeoutMs : DEFAULT_COMMAND_TIMEOUT_MS,
+      maxBuffer: Number.isFinite(options.maxBuffer) ? options.maxBuffer : DEFAULT_COMMAND_MAX_BUFFER,
+      signal: options.signal,
+    });
+    return { exitCode: 0, stdout: result.stdout ?? "", stderr: result.stderr ?? "" };
+  } catch (error) {
+    return { exitCode: Number.isInteger(error.code) ? error.code : 1, stdout: error.stdout ?? "", stderr: error.stderr ?? error.message ?? "" };
+  }
+}
+
+function commandText(command) {
+  return Array.isArray(command) ? command.join(" ") : String(command);
+}
+
+export function groupTestFailures(output) {
+  const text = String(output ?? "");
+  const failures = [];
+  for (const line of text.split(/\r?\n/)) {
+    const trimmed = line.trim();
+    if (!trimmed) continue;
+    const failMatch = trimmed.match(/^(?:FAIL|not ok)\s+(.+?)(?::\s*(.+))?$/i);
+    if (failMatch) {
+      const target = failMatch[1].trim();
+      failures.push({ id: `test:${target}`, target, summary: failMatch[2]?.trim() || trimmed, raw: trimmed });
+    }
+  }
+  if (failures.length === 0 && text.trim()) failures.push({ id: "test:unknown", target: "unknown", summary: text.trim().slice(0, 300), raw: text.trim() });
+  return failures;
+}
+
+export function createTestFixDrainAdapter(options = {}) {
+  const cwd = options.cwd ?? process.cwd();
+  const testCommand = options.testCommand ?? ["npm", "test"];
+  const runCommand = options.runCommand ?? defaultRunCommand;
+  const createdFollowups = [];
+  const commandRuns = [];
+
+  async function runTests(context = {}) {
+    const result = await runCommand(testCommand, { cwd, phase: context.phase ?? "test", signal: options.signal, timeoutMs: options.timeoutMs, maxBuffer: options.maxBuffer });
+    commandRuns.push({ command: commandText(testCommand), phase: context.phase ?? "test", exitCode: result.exitCode });
+    return result;
+  }
+
+  return {
+    name: "test-fix",
+    commandRuns,
+    async discover() {
+      const result = await runTests({ phase: "discover" });
+      if (result.exitCode === 0) return [];
+      return groupTestFailures(`${result.stdout}\n${result.stderr}`).map((failure) => ({
+        ...failure,
+        status: "open",
+        issue_type: "test-failure",
+        output: `${result.stdout}\n${result.stderr}`.trim(),
+      }));
+    },
+    async classify(item) {
+      if (!item?.target || item.target === "unknown") return { status: "human-gated", reason: "failure target could not be isolated" };
+      if (item.humanGated === true) return { status: "human-gated", reason: "failure marked human-gated" };
+      return { status: "ready", reason: "isolated failing test target" };
+    },
+    async claim(item) {
+      return { itemId: item.id, claimed: true, target: item.target };
+    },
+    async buildLanePacket(item, context = {}) {
+      return {
+        itemId: item.id,
+        target: item.target,
+        summary: item.summary,
+        failingOutput: item.output,
+        attempt: context.attempt,
+        instructions: [
+          "Repair only the failing test target and directly related implementation.",
+          "Return a generic lane report with changed files, commands, evidence, risks, and followups.",
+        ],
+      };
+    },
+    async validate(item, integrationState, context = {}) {
+      const result = await runTests({ phase: "validate" });
+      const accepted = result.exitCode === 0 && context.laneReport?.readyForIntegration === true;
+      return {
+        itemId: item.id,
+        accepted,
+        reason: accepted ? "test command passed after repair" : "test command still fails after repair",
+        diffScopeOk: integrationState?.status !== "review-required",
+        followupsHandled: true,
+        acceptanceChecklist: ["test command rerun", "lane report ready for integration"],
+        validationCommands: [commandText(testCommand)],
+        followups: accepted ? [] : [{ title: `Unresolved test failure: ${item.target}`, description: `${result.stdout}\n${result.stderr}`.trim() }],
+      };
+    },
+    async close(item, evidence = {}) {
+      return { itemId: item.id, status: "closed", reason: evidence.validationReport?.reason ?? "test repaired" };
+    },
+    async createFollowup(followup = {}) {
+      const created = { id: `test-followup-${createdFollowups.length + 1}`, ...followup };
+      createdFollowups.push(created);
+      return created;
+    },
+    async proveDry() {
+      const result = await runTests({ phase: "proveDry" });
+      return { dry: result.exitCode === 0, command: commandText(testCommand), output: `${result.stdout}\n${result.stderr}`.trim() };
+    },
+  };
+}

package/workflow-kernel/text-json.js

@@ -0,0 +1,136 @@
+import crypto from "node:crypto";
+
+import { MAX_ARGS_PREVIEW_CHARS, MAX_STATUS_STRING_CHARS, SENSITIVE_KEY_RE } from "./constants.js";
+import { redactFreeTextSecrets } from "./free-text-redactor.js";
+
+const SAFE_USAGE_KEY_RE = /^(tokens|tokenUsage|usageTokens)$/i;
+const SAFE_USAGE_METRIC_KEYS = new Set(["input", "output", "reasoning", "total", "cached"]);
+
+export function stableStringify(value) {
+  // R29: mirror JSON.stringify / writeJsonAtomic for undefined so an in-memory hash
+  // matches the hash recomputed from the persisted (JSON.stringify'd) file. JSON.stringify
+  // drops undefined-valued object keys and coerces undefined array elements to null; a
+  // standalone undefined serializes to the JS value undefined, which we represent with a
+  // stable sentinel only at the top level (object/array recursion never reaches it).
+  if (value === undefined) return "undefined";
+  if (typeof value === "bigint") return JSON.stringify(String(value));
+  if (value === null || typeof value !== "object") return JSON.stringify(value);
+  if (Array.isArray(value)) return `[${value.map((item) => (item === undefined ? "null" : stableStringify(item))).join(",")}]`;
+  return `{${Object.keys(value)
+    .sort()
+    .filter((key) => value[key] !== undefined)
+    .map((key) => `${JSON.stringify(key)}:${stableStringify(value[key])}`)
+    .join(",")}}`;
+}
+
+export function hash(value) {
+  return crypto.hash("sha256", value, "hex");
+}
+
+export function hashStable(value) {
+  return hash(stableStringify(value));
+}
+
+export function jsonLine(value) {
+  return `${JSON.stringify(value)}\n`;
+}
+
+export function hasFunction(value, key) {
+  return typeof value?.[key] === "function";
+}
+
+export function textPart(text) {
+  return { type: "text", text };
+}
+
+// Cap a string to at most `max` characters without ever appending the (oversized)
+// truncation marker. Used only for the degenerate small-max branch of truncateText,
+// where the marker itself would not fit. Prefers a short "..." ellipsis when there is
+// room for it, otherwise falls back to a plain slice; never splits a trailing surrogate.
+function hardTruncate(string, max) {
+  if (max <= 0) return "";
+  if (max <= 3) return string.slice(0, max);
+  let head = string.slice(0, max - 3);
+  const last = head.charCodeAt(head.length - 1);
+  if (last >= 0xd800 && last <= 0xdbff) head = head.slice(0, -1);
+  return `${head}...`;
+}
+
+export function truncateText(text, max = MAX_STATUS_STRING_CHARS) {
+  const string = String(text ?? "");
+  if (string.length <= max) return string;
+  // The reported drop-count must reflect how many characters are ACTUALLY dropped
+  // (string.length - head.length), not string.length - max: the suffix is carved out
+  // of the max-character budget, so the head keeps fewer than max chars. There is a
+  // mutual dependency — the suffix length depends on the count's digits, and the head
+  // length depends on the suffix length — so iterate to a fixed point (converges in a
+  // few steps because the count changes by at most one digit per pass).
+  let n = string.length - max;
+  let head = "";
+  let suffix = "";
+  for (let i = 0; i < 5; i++) {
+    suffix = `...[truncated ${n} chars]`;
+    // Degenerate case: when the truncation marker alone is at least as long as the
+    // whole budget, appending it to any head would blow past max. Hard-cap at exactly
+    // max characters instead so the result.length <= max invariant holds for every max.
+    if (suffix.length >= max) return hardTruncate(string, max);
+    head = string.slice(0, Math.max(0, max - suffix.length));
+    const last = head.charCodeAt(head.length - 1);
+    if (last >= 0xd800 && last <= 0xdbff) head = head.slice(0, -1);
+    const dropped = string.length - head.length;
+    if (dropped === n) break;
+    n = dropped;
+  }
+  return `${head}${suffix}`;
+}
+
+function isSafeUsageObject(key, value) {
+  if (!SAFE_USAGE_KEY_RE.test(key) || !value || typeof value !== "object" || Array.isArray(value)) return false;
+  const entries = Object.entries(value);
+  return entries.length > 0 && entries.every(([metric, child]) => SAFE_USAGE_METRIC_KEYS.has(metric) && Number.isFinite(child));
+}
+
+export function redactValue(value, { depth = 0, maxDepth = 5, maxString = MAX_STATUS_STRING_CHARS, maxArray = 50 } = {}) {
+  if (value === null || value === undefined) return value;
+  if (typeof value === "string") return truncateText(redactFreeTextSecrets(value), maxString);
+  if (typeof value === "number" || typeof value === "boolean") return value;
+  if (typeof value === "bigint") return String(value);
+  if (depth >= maxDepth) return "[redacted:depth]";
+  if (Array.isArray(value)) {
+    const limit = Number.isFinite(maxArray) ? maxArray : value.length;
+    return value.slice(0, limit).map((item) => redactValue(item, { depth: depth + 1, maxDepth, maxString, maxArray }));
+  }
+  if (typeof value === "object") {
+    const redacted = {};
+    for (const [key, child] of Object.entries(value)) {
+      redacted[key] = SENSITIVE_KEY_RE.test(key) && !isSafeUsageObject(key, child) ? "[redacted]" : redactValue(child, { depth: depth + 1, maxDepth, maxString, maxArray });
+    }
+    return redacted;
+  }
+  return `[redacted:${typeof value}]`;
+}
+
+export function redactDurableValue(value) {
+  return redactValue(value, {
+    maxDepth: Number.POSITIVE_INFINITY,
+    maxString: Number.POSITIVE_INFINITY,
+    maxArray: Number.POSITIVE_INFINITY,
+  });
+}
+
+export function jsonPreview(value, max = MAX_ARGS_PREVIEW_CHARS) {
+  const text = JSON.stringify(redactValue(value), null, 2);
+  return truncateText(text, max);
+}
+
+export function responseText(result) {
+  return (result?.data?.parts ?? [])
+    .filter((part) => part?.type === "text" && typeof part.text === "string")
+    .map((part) => part.text)
+    .join("\n")
+    .trim();
+}
+
+export function extractTextFromError(error) {
+  return error?.message || String(error);
+}