@mcrescenzo/opencode-workflows 0.1.0

package/workflow-kernel/constants.js

@@ -0,0 +1,117 @@
+import path from "node:path";
+import { existsSync } from "node:fs";
+import os from "node:os";
+
+import { DEFAULT_SECRET_GLOBS } from "./path-policy.js";
+
+export const PLUGIN_DIR = path.resolve(import.meta.dirname, "..");
+
+// Detect the in-monorepo copy STRUCTURALLY: it lives at <root>/plugins/opencode-workflows/. Standalone
+// it lives under <project>/node_modules/@mcrescenzo/opencode-workflows, whose parent dir is the npm
+// scope ("@mcrescenzo"), never "plugins" — so this can't false-match a user project that merely has
+// opencode.json + a workflows/ dir (the [Major] false-positive the advisor flagged).
+export function detectLegacyConfigDir(startDir = PLUGIN_DIR) {
+  const pluginsDir = path.dirname(path.resolve(startDir)); // candidate <root>/plugins
+  if (path.basename(pluginsDir) !== "plugins") return null;
+  const root = path.dirname(pluginsDir);                   // candidate <root>
+  if (existsSync(path.join(root, "opencode.json")) && existsSync(path.join(root, "workflows"))) return root;
+  return null;
+}
+
+// opencode's config dir (where opencode.json lives). Order: explicit OPENCODE_CONFIG_DIR →
+// $XDG_CONFIG_HOME/opencode → <home>/.config/opencode. PluginInput exposes no config dir, and
+// (verified on the opencode 1.17.11 runtime) no OPENCODE_CONFIG* env var is set, so we derive it.
+// Cross-platform via os.homedir()/path.join; the env override is the escape hatch for any platform
+// whose opencode config dir is not <home>/.config/opencode (e.g. Windows %APPDATA%).
+export function resolveOpencodeConfigDir(env = process.env, home = os.homedir()) {
+  if (env.OPENCODE_CONFIG_DIR) return path.resolve(env.OPENCODE_CONFIG_DIR);
+  const configHome = env.XDG_CONFIG_HOME ? path.resolve(env.XDG_CONFIG_HOME) : path.join(home, ".config");
+  return path.join(configHome, "opencode");
+}
+
+// Global/shared workflow dir (user-authored global workflows, runs, materialized roles/templates).
+// Order: explicit env → legacy monorepo (marker-gated) → opencode config dir.
+// User-authored content lives in the CONFIG dir (~/.config/opencode/workflows), not XDG state.
+// ⚠️ To force the config-dir branch even inside the monorepo, move its return above the legacy block.
+export function resolveGlobalWorkflowDir(env = process.env, startDir = PLUGIN_DIR, home = os.homedir()) {
+  if (env.OPENCODE_WORKFLOWS_DIR) return path.resolve(env.OPENCODE_WORKFLOWS_DIR);
+  const legacy = detectLegacyConfigDir(startDir);
+  if (legacy) return path.join(legacy, "workflows");
+  return path.join(resolveOpencodeConfigDir(env, home), "workflows");
+}
+
+export const GLOBAL_WORKFLOW_DIR = resolveGlobalWorkflowDir();
+export const BUNDLED_WORKFLOW_DIR = path.join(PLUGIN_DIR, "workflows");
+export const BUNDLED_COMMAND_DIR = path.join(PLUGIN_DIR, "commands");
+export const BUNDLED_SKILL_DIR = path.join(PLUGIN_DIR, "skills");
+export const ROLE_DIR = path.join(GLOBAL_WORKFLOW_DIR, "roles");
+export const TEMPLATE_DIR = path.join(GLOBAL_WORKFLOW_DIR, "templates");
+export const MAX_SOURCE_BYTES = 512 * 1024;
+export const MAX_RESULT_BYTES = 256 * 1024;
+export const MAX_INLINE_RESULT_BYTES = 32 * 1024;
+export const MAX_RESULT_READBACK_BYTES = MAX_RESULT_BYTES;
+export const MAX_RESULT_READ_FILE_BYTES = 16 * 1024 * 1024;
+export const OPENCODE_WORKFLOWS_DEBUG_CAPTURE_ENV = "OPENCODE_WORKFLOWS_DEBUG_CAPTURE";
+export const MAX_DEBUG_CAPTURE_FILE_BYTES = MAX_RESULT_READ_FILE_BYTES;
+export const MAX_EVENT_MESSAGE_CHARS = 4000;
+export const MAX_STATUS_STRING_CHARS = 600;
+export const DEFAULT_WORKFLOW_EVENTS_LIMIT = 100;
+export const MAX_WORKFLOW_EVENTS_LIMIT = 500;
+export const MAX_ARGS_PREVIEW_CHARS = 2000;
+export const MAX_HOST_CALLS = 10000;
+export const MAX_PENDING_JOB_DRAIN_ITERATIONS = 10000;
+export const HOST_CALLS_PER_MAX_AGENT = 1;
+export const HOST_CALL_MARGIN = 1000;
+export const MAX_EVENTS = 200000;
+export const MAX_JOURNAL_RECORDS = 200000;
+export const DEFAULT_MAX_AGENTS = 64;
+export const DEFAULT_HARD_CONCURRENCY_LIMIT = 64;
+export const MAX_CONFIGURABLE_CONCURRENCY_LIMIT = 100000;
+export const HARD_CONCURRENCY_LIMIT_ENV = "OPENCODE_WORKFLOWS_HARD_CONCURRENCY_LIMIT";
+
+export function normalizeHardConcurrencyLimit(value, fallback = DEFAULT_HARD_CONCURRENCY_LIMIT) {
+  const parsed = typeof value === "string" && value.trim() !== "" ? Number(value) : value;
+  if (Number.isInteger(parsed) && parsed >= 1 && parsed <= MAX_CONFIGURABLE_CONCURRENCY_LIMIT) return parsed;
+  const fallbackParsed = typeof fallback === "string" && fallback.trim() !== "" ? Number(fallback) : fallback;
+  if (Number.isInteger(fallbackParsed) && fallbackParsed >= 1 && fallbackParsed <= MAX_CONFIGURABLE_CONCURRENCY_LIMIT) return fallbackParsed;
+  return DEFAULT_HARD_CONCURRENCY_LIMIT;
+}
+
+export function resolveHardConcurrencyLimit(env = process.env, fallback = DEFAULT_HARD_CONCURRENCY_LIMIT) {
+  return normalizeHardConcurrencyLimit(env?.[HARD_CONCURRENCY_LIMIT_ENV], fallback);
+}
+
+// Conservative default. Concurrent blocking child prompts (session.prompt) have been
+// observed stalling as an entire wave at high fan-out (12 lanes all timed out at the lane
+// limit with 0 tokens, while single lanes completed). 4 remains the default pending live
+// evidence. The ceiling is a separate operator policy knob: set
+// OPENCODE_WORKFLOWS_HARD_CONCURRENCY_LIMIT or plugin option `hardConcurrencyLimit` to
+// raise/lower the schema/runtime clamp. Larger bursts can amplify provider rate limits or
+// reproduce the 2026-06-22 stall, so use workflow_live_gates({probeConcurrencyCapacity})
+// to characterize a runtime before treating higher values as safe production headroom.
+export const DEFAULT_CONCURRENCY = 4;
+export const HARD_CONCURRENCY_LIMIT = resolveHardConcurrencyLimit();
+export const DEFAULT_CONCURRENCY_PROBE_LIMIT = 16;
+export const DEFAULT_RETRY_COUNT = 1;
+export const DEFAULT_CORRECTIVE_RETRY_COUNT = 1;
+export const MAX_CORRECTIVE_RETRY_COUNT = 2;
+export const DEFAULT_CHILD_CREATE_TIMEOUT_MS = 30_000;
+export const DEFAULT_CHILD_PROMPT_TIMEOUT_MS = 10 * 60 * 1000;
+export const MAX_CHILD_PROMPT_TIMEOUT_MS = 60 * 60 * 1000;
+export const DEFAULT_LIVE_PROBE_TIMEOUT_MS = 60_000;
+export const DEFAULT_SUBPROCESS_TIMEOUT_MS = 2 * 60 * 1000;
+export const DEFAULT_SUBPROCESS_MAX_BUFFER = 10 * 1024 * 1024;
+export const DEFAULT_KEEP_RUNS = 30;
+export const DEFAULT_GUEST_DEADLINE_MS = 5_000;
+export const WORKFLOW_TOAST_DURATION_MS = 90_000;
+export const WORKFLOW_PROGRESS_TOAST_INTERVAL_MS = 45_000;
+export const WORKFLOW_PROGRESS_TOAST_FORCE_MS = 75_000;
+export const RUN_ID_RE = /^[a-zA-Z0-9][a-zA-Z0-9_.-]{0,127}$/;
+
+export const ACTIVE_STATUSES = new Set(["running", "cancelling", "pausing", "apply-running", "active-unknown", "stale-active"]);
+export const AMBIGUOUS_EDIT_STATUSES = new Set(["awaiting-diff-approval", "apply-running", "review-required", "failed-with-diff-plan"]);
+export const LANE_OUTCOMES = ["success", "failure", "cancelled", "timeout", "budget_stopped"];
+export const DURABLE_STATE_VERSION = 2;
+export const DURABLE_LEDGER_FILES = ["integration-ledger.jsonl", "validation-ledger.jsonl", "domain-ledger.jsonl", "apply-ledger.jsonl"];
+export const SENSITIVE_KEY_RE = /(api[_-]?key|authorization|credential|password|secret|token)/i;
+export const SECRET_GLOBS = DEFAULT_SECRET_GLOBS;

package/workflow-kernel/diagnostics.js

@@ -0,0 +1,152 @@
+import { createHash } from "node:crypto";
+import { appendFile, chmod, mkdir, realpath } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { redactFreeTextSecrets } from "./free-text-redactor.js";
+
+const SCHEMA = "opencode.plugin.diagnostic.v1";
+const PLUGIN = "opencode-workflows";
+const LEVELS = new Set(["debug", "info", "warn", "error"]);
+const MAX_STRING = 4_000;
+const MAX_RECORD = 16_000;
+const MAX_DEPTH = 6;
+const MAX_ENTRIES = 100;
+const SECRET_KEY_RE = /(^|_|-|\.)(authorization|cookie|password|passwd|secret|token|api[_-]?key|apikey|access[_-]?key|private[_-]?key|refresh[_-]?token|serverPassword)($|_|-|\.)/i;
+
+const EVENT_MAP = new Map([
+  ["run.started", { level: "info", event: "workflow_run_started", message: "Workflow run started", outcome: "started" }],
+  ["run.completed", { level: "info", event: "workflow_run_completed", message: "Workflow run completed", outcome: "success" }],
+  ["run.awaiting_diff_approval", { level: "warn", event: "workflow_run_awaiting_diff_approval", message: "Workflow run awaits diff approval", outcome: "blocked" }],
+  ["run.failed_with_diff_plan", { level: "warn", event: "workflow_run_failed_with_diff_plan", message: "Workflow run failed with a diff plan for review", outcome: "failure" }],
+  ["run.apply_failed", { level: "error", event: "workflow_apply_failed", message: "Workflow auto-apply failed", outcome: "failure" }],
+  ["run.failed", { level: "error", event: "workflow_run_failed", message: "Workflow run failed", outcome: "failure" }],
+  ["run.cancelled", { level: "warn", event: "workflow_run_cancelled", message: "Workflow run cancelled", outcome: "cancelled" }],
+  ["run.paused", { level: "warn", event: "workflow_run_paused", message: "Workflow run paused", outcome: "paused" }],
+  ["agent.failure", { level: "error", event: "workflow_lane_failed", message: "Workflow child lane failed", outcome: "failure" }],
+  ["agent.timeout", { level: "error", event: "workflow_lane_timed_out", message: "Workflow child lane timed out", outcome: "timeout" }],
+  ["agent.cancelled", { level: "warn", event: "workflow_lane_cancelled", message: "Workflow child lane cancelled", outcome: "cancelled" }],
+  ["agent.budget_stopped", { level: "warn", event: "workflow_lane_budget_stopped", message: "Workflow child lane stopped by budget", outcome: "budget_stopped" }],
+  ["agent.salvageable_dirty_failure", { level: "warn", event: "workflow_lane_salvageable_dirty_failure", message: "Workflow lane failed with dirty salvageable worktree", outcome: "failure" }],
+  ["cache.checkpoint_write_failed", { level: "warn", event: "workflow_checkpoint_write_failed", message: "Workflow checkpoint write failed", outcome: "degraded" }],
+  ["fanout.lane_dropped", { level: "warn", event: "workflow_fanout_lane_dropped", message: "Workflow fanout lane was dropped", outcome: "failure" }],
+  ["fanout.sequential", { level: "info", event: "workflow_fanout_sequential", message: "Workflow fanout intentionally ran sequentially", outcome: "success" }],
+  ["integration.review_required", { level: "warn", event: "workflow_integration_review_required", message: "Workflow integration requires review", outcome: "blocked" }],
+]);
+
+function redactText(value) {
+  if (value === undefined || value === null) return "";
+  const text = redactFreeTextSecrets(String(value));
+  if (text.length <= MAX_STRING) return text;
+  return `${text.slice(0, MAX_STRING)}\n[truncated ${text.length - MAX_STRING} chars]`;
+}
+
+function redactValue(value, seen = new WeakSet(), depth = 0) {
+  if (value === null || value === undefined) return value;
+  if (typeof value === "string") return redactText(value);
+  if (typeof value === "number" || typeof value === "boolean") return value;
+  if (typeof value === "bigint") return String(value);
+  if (typeof value === "function") return "[function]";
+  if (typeof value !== "object") return redactText(String(value));
+  if (seen.has(value)) return "[circular]";
+  if (depth >= MAX_DEPTH) return "[max-depth]";
+  seen.add(value);
+  if (Array.isArray(value)) {
+    const items = value.slice(0, MAX_ENTRIES).map((item) => redactValue(item, seen, depth + 1));
+    if (value.length > MAX_ENTRIES) items.push(`[${value.length - MAX_ENTRIES} more items]`);
+    return items;
+  }
+  const out = {};
+  let count = 0;
+  for (const [key, item] of Object.entries(value)) {
+    if (count >= MAX_ENTRIES) {
+      out.__truncated_entries = Object.keys(value).length - MAX_ENTRIES;
+      break;
+    }
+    out[key] = SECRET_KEY_RE.test(String(key)) ? "[redacted]" : redactValue(item, seen, depth + 1);
+    count += 1;
+  }
+  return out;
+}
+
+function diagnosticsRoot() {
+  if (process.env.OPENCODE_PLUGIN_DIAGNOSTICS_DIR) return path.resolve(process.env.OPENCODE_PLUGIN_DIAGNOSTICS_DIR);
+  const base = process.env.XDG_STATE_HOME ? path.resolve(process.env.XDG_STATE_HOME) : path.join(os.homedir(), ".local", "state");
+  return path.join(base, "opencode", "plugin-diagnostics");
+}
+
+function safeName(value, fallback = "project") {
+  return (String(value || fallback).replace(/[^a-zA-Z0-9._-]/g, "_").slice(0, 40) || fallback);
+}
+
+function projectFromRunDir(runDir) {
+  const marker = `${path.sep}.opencode${path.sep}workflows${path.sep}runs${path.sep}`;
+  const index = String(runDir || "").indexOf(marker);
+  return index > 0 ? String(runDir).slice(0, index) : undefined;
+}
+
+async function projectKey(directory) {
+  const resolved = path.resolve(directory || process.cwd());
+  let canonical = resolved;
+  try { canonical = await realpath(resolved); } catch {}
+  return `${safeName(path.basename(canonical || resolved))}-${createHash("sha256").update(canonical).digest("hex").slice(0, 16)}`;
+}
+
+function jsonLine(record) {
+  let text = JSON.stringify(record);
+  if (text.length <= MAX_RECORD) return `${text}\n`;
+  text = JSON.stringify({ ...record, data: record.data === undefined ? undefined : "[omitted: record too large]" });
+  return `${text}\n`;
+}
+
+function summaryData(event) {
+  return redactValue({
+    type: event.type,
+    callId: event.callId,
+    childID: event.childID,
+    reason: event.reason,
+    culpritLane: event.culpritLane,
+    conflictCount: event.conflictCount,
+    changedFileCount: event.changedFileCount,
+    drainStatus: event.drainStatus,
+    diffPlanHash: event.diffPlanHash,
+    error: event.error,
+    kind: event.kind,
+    // Lane failure taxonomy (transient / transient_exhausted / terminal) so the diagnostic
+    // sink distinguishes a rate-limit/overload lane that exhausted its retries from a terminal
+    // one (bad model id, auth, schema). Set on agent.* failure/retry events (jbs3.2).
+    failureClass: event.failureClass,
+  });
+}
+
+export async function emitWorkflowDiagnostic(run, event) {
+  if (process.env.OPENCODE_PLUGIN_DIAGNOSTICS_DISABLED === "1") return;
+  const mapped = EVENT_MAP.get(event?.type);
+  if (!mapped) return;
+  try {
+    const directory = run?.projectDirectory || projectFromRunDir(run?.dir) || process.cwd();
+    const dir = path.join(diagnosticsRoot(), await projectKey(directory), PLUGIN);
+    await mkdir(dir, { recursive: true, mode: 0o700 });
+    await chmod(dir, 0o700).catch(() => {});
+    const record = redactValue({
+      schema: SCHEMA,
+      ts: new Date().toISOString(),
+      plugin: PLUGIN,
+      level: LEVELS.has(mapped.level) ? mapped.level : "info",
+      event: mapped.event,
+      message: mapped.message,
+      runID: run?.id,
+      childID: event.childID,
+      operation: event.type,
+      outcome: mapped.outcome,
+      error: event.error ? { message: event.error } : undefined,
+      data: summaryData(event),
+    });
+    const file = path.join(dir, `${PLUGIN}-${new Date().toISOString().slice(0, 10)}-${process.pid}.jsonl`);
+    await appendFile(file, jsonLine(record), { mode: 0o600 });
+    await chmod(file, 0o600).catch(() => {});
+  } catch {
+    // Diagnostics are best effort and must never affect workflow execution.
+  }
+}
+
+export const __test = { redactText, redactValue, projectFromRunDir, EVENT_MAP };