@mortz.prk/opencode-auto-mode 1.0.1 → 1.1.1

package/src/debug-events.ts

@@ -0,0 +1,223 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+
+/** Unsafe debugging only: payloads are original and may contain secrets. */
+export interface DebugEvent {
+  ts: string;
+  type: string;
+  payload: unknown;
+  [key: string]: unknown;
+}
+
+export interface JsonlOptions {
+  path: string;
+  /** Zero disables rotation. Rotated files are retained, never overwritten. */
+  maxBytes: number;
+}
+export type DebugLogSetting = JsonlOptions | undefined;
+export interface EventLog { readonly sinkPath: string; write(event: DebugEvent): void }
+export interface JsonlLog { write(value: unknown): void }
+
+/** Preserve JSON data without redaction or bounds; explicitly report non-JSON values. */
+export function serializeDebugValue(value: unknown): string {
+  const issues: string[] = [];
+  const ancestors = new Set<object>();
+  const visit = (item: unknown, location: string): unknown => {
+    if (item === null || typeof item === "string" || typeof item === "boolean") return item;
+    if (typeof item === "number" && Number.isFinite(item)) return item;
+    if (typeof item !== "object") {
+      issues.push(`${location}: ${typeof item} is not JSON-compatible`);
+      return { serializationError: typeof item, value: String(item) };
+    }
+    if (ancestors.has(item)) {
+      issues.push(`${location}: circular reference`);
+      return { serializationError: "circular reference" };
+    }
+    ancestors.add(item);
+    try {
+      if (item instanceof Date) return item.toISOString();
+      if (Array.isArray(item)) return Array.from(item, (entry, index) => visit(entry, `${location}[${index}]`));
+      if (item instanceof Map) {
+        issues.push(`${location}: Map represented as entries`);
+        return { serializationError: "Map", entries: Array.from(item, ([key, entry], index) => [visit(key, `${location}.keys[${index}]`), visit(entry, `${location}.values[${index}]`)]) };
+      }
+      if (item instanceof Set) {
+        issues.push(`${location}: Set represented as values`);
+        return { serializationError: "Set", values: Array.from(item, (entry, index) => visit(entry, `${location}[${index}]`)) };
+      }
+      const keys = new Set(Object.keys(item));
+      if (item instanceof Error) {
+        for (const key of ["name", "message", "stack", ...Object.getOwnPropertyNames(item)]) keys.add(key);
+      }
+      const result: Record<string, unknown> = Object.create(null) as Record<string, unknown>;
+      for (const key of keys) {
+        try { result[key] = visit((item as Record<string, unknown>)[key], `${location}.${key}`); }
+        catch (error) {
+          const message = error instanceof Error ? error.message : String(error);
+          issues.push(`${location}.${key}: ${message}`);
+          result[key] = { serializationError: message };
+        }
+      }
+      for (const key of Object.getOwnPropertySymbols(item)) {
+        issues.push(`${location}: symbol key ${String(key)} is not JSON-compatible`);
+      }
+      return result;
+    } finally { ancestors.delete(item); }
+  };
+  try {
+    const payload = visit(value, "$");
+    if (issues.length === 0) return JSON.stringify(payload);
+    // Keep the normal event/decision shape available to replay tools.
+    if (payload && typeof payload === "object" && !Array.isArray(payload)) {
+      return JSON.stringify({ ...payload, ...(Object.hasOwn(payload, "serializationError") ? { originalSerializationError: (payload as Record<string, unknown>).serializationError } : {}), serializationError: issues });
+    }
+    return JSON.stringify({ payload, serializationError: issues });
+  } catch (error) {
+    return JSON.stringify({ serializationError: error instanceof Error ? error.message : String(error) });
+  }
+}
+
+/** Opens the sink for append, rejecting FIFOs/devices before the write can block indefinitely. */
+function openRegularFileForAppend(file: string): number {
+  const fd = fs.openSync(file, fs.constants.O_WRONLY | fs.constants.O_CREAT | fs.constants.O_APPEND | fs.constants.O_NOFOLLOW | fs.constants.O_NONBLOCK, 0o600);
+  if (fs.fstatSync(fd).isFile()) return fd;
+  fs.closeSync(fd);
+  throw new Error("Refusing to write to a non-regular file");
+}
+
+/** Opt-in, local-only, best-effort sink. Rotation is controlled by the caller. */
+export function createJsonlLog(setting: DebugLogSetting): JsonlLog | undefined {
+  if (!setting) return undefined;
+  const { path: file, maxBytes } = setting;
+  if (!file || !Number.isFinite(maxBytes) || maxBytes < 0) return undefined;
+  return {
+    write(value) {
+      let fd: number | undefined;
+      try {
+        const line = `${serializeDebugValue(value)}\n`;
+        fs.mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 });
+        try {
+          const stat = fs.lstatSync(file);
+          const size = stat.size;
+          if (stat.isFile() && maxBytes > 0 && size > 0 && size + Buffer.byteLength(line) > maxBytes) {
+            let sequence = 1;
+            while (fs.existsSync(`${file}.${sequence}`)) sequence++;
+            // Exclusive link creation prevents a racing writer from replacing an archive.
+            fs.linkSync(file, `${file}.${sequence}`);
+            fs.unlinkSync(file);
+          }
+        } catch { /* No file yet, or rotation unavailable: append rather than lose the event. */ }
+        fd = openRegularFileForAppend(file);
+        fs.fchmodSync(fd, 0o600);
+        fs.writeFileSync(fd, line);
+      } catch { /* Audit I/O must never fail a permission or tool request. */ }
+      finally {
+        if (fd !== undefined) { try { fs.closeSync(fd); } catch { /* Best effort. */ } }
+      }
+    },
+  };
+}
+
+export function createEventLog(setting: DebugLogSetting): EventLog | undefined {
+  const log = createJsonlLog(setting);
+  if (!log || setting === undefined) return undefined;
+  return { sinkPath: canonicalSinkPath(setting.path), write: log.write };
+}
+
+/** Resolve existing ancestors too, so aliases agree before the log is created. */
+function canonicalSinkPath(file: string): string {
+  let parent = path.resolve(file);
+  const suffix: string[] = [];
+  for (;;) {
+    try { return path.join(fs.realpathSync(parent), ...suffix); }
+    catch {
+      const next = path.dirname(parent);
+      if (next === parent) return path.resolve(file);
+      suffix.unshift(path.basename(parent));
+      parent = next;
+    }
+  }
+}
+
+type CaptureMember = { unavailable: boolean; start(signal: AbortSignal, isOwner: () => boolean, handoff: boolean, markFailure: () => void): void };
+type CaptureEntry = { members: Set<CaptureMember>; owner?: CaptureMember; controller?: AbortController };
+const captureRegistryKey = Symbol.for("opencode-auto-mode.debug-capture.v2");
+const legacyCaptureRegistryKey = Symbol.for("opencode-auto-mode.debug-capture.v1");
+type LegacyCaptureEntry = { members: Set<unknown>; owner?: unknown; controller?: AbortController };
+
+/** One server-global subscriber per sink in this JS process, including module reloads.
+ * No machine lock or payload deduplication: different processes remain independent.
+ */
+export function registerGlobalCapture(sinkPath: string, start: CaptureMember["start"]): () => void {
+  const shared = globalThis as typeof globalThis & {
+    [captureRegistryKey]?: Map<string, CaptureEntry>;
+    [legacyCaptureRegistryKey]?: Map<string, LegacyCaptureEntry>;
+  };
+  const legacy = shared[legacyCaptureRegistryKey];
+  const retiredLegacy = legacy !== undefined;
+  if (legacy) {
+    // v1 callbacks do not implement failure handoff. Never migrate their stale closures.
+    // Detach every owner before aborting: abort listeners can register synchronously.
+    const controllers: AbortController[] = [];
+    for (const entry of legacy.values()) {
+      entry.owner = undefined;
+      if (entry.controller) controllers.push(entry.controller);
+      entry.controller = undefined;
+      entry.members.clear();
+    }
+    legacy.clear();
+    delete shared[legacyCaptureRegistryKey];
+    for (const controller of controllers) controller.abort();
+  }
+  const registry = shared[captureRegistryKey] ??= new Map<string, CaptureEntry>();
+  let entry = registry.get(sinkPath);
+  if (!entry) { entry = { members: new Set() }; registry.set(sinkPath, entry); }
+  const group = entry;
+  const member: CaptureMember = { start, unavailable: false };
+  group.members.add(member);
+  let promoting = false;
+  const promote = (handoff: boolean) => {
+    if (promoting) return;
+    promoting = true;
+    try {
+      // Failed members stay ineligible until unloaded. Each registration gets one attempt,
+      // even when subscribe throws synchronously or every existing stream is already closed.
+      while (!group.owner) {
+        const next = [...group.members].find((candidate) => !candidate.unavailable);
+        if (!next) break;
+        const controller = new AbortController();
+        group.owner = next;
+        group.controller = controller;
+        const markFailure = () => {
+          if (group.owner !== next || controller.signal.aborted) return;
+          next.unavailable = true;
+          group.owner = undefined;
+          group.controller = undefined;
+          controller.abort();
+          promote(true);
+        };
+        try { next.start(controller.signal, () => group.owner === next && !controller.signal.aborted, handoff, markFailure); }
+        catch { markFailure(); }
+        handoff = true;
+      }
+    } finally { promoting = false; }
+  };
+  if (!group.owner) promote(retiredLegacy || group.members.size > 1);
+  let disposed = false;
+  return () => {
+    if (disposed) return;
+    disposed = true;
+    group.members.delete(member);
+    if (group.owner === member) {
+      group.owner = undefined;
+      const controller = group.controller;
+      group.controller = undefined;
+      controller?.abort();
+      promote(true);
+    }
+    if (group.members.size === 0) {
+      registry.delete(sinkPath);
+      if (registry.size === 0) delete shared[captureRegistryKey];
+    }
+  };
+}

package/src/decision.ts

@@ -0,0 +1,72 @@
+import { Model } from "@opencode/schema/model";
+import type { Generate } from "@opencode/schema/generate";
+import { errorKindOf, ReviewFailure } from "./errors.js";
+import { AUTHORITY_RULES, reviewEvidence, type PermissionRequest, type ReviewErrorObserver, type StageResult } from "./reviewer.js";
+import { withTimeout } from "./timeout.js";
+
+export interface DecisionOptions { model: string; timeoutMs?: number; minConfidence?: number }
+export type DecisionInput = Omit<Generate.DecisionRequest, "input"> & { input: readonly { type: "text"; text: string }[] };
+export interface DecisionContext {
+  experimental: { generate: {
+    decisions(input: DecisionInput, options: { signal: AbortSignal }): Promise<unknown>;
+  } };
+}
+const criteria = {
+  allow: "The whole action is safe and authorized for this exact scope.",
+  deny: "The action is unsafe or attempts to bypass a safety block.",
+  ask: "Safety, authorization or impact is uncertain; abstain from this decision.",
+};
+const object = (value: unknown): value is Record<string, unknown> => typeof value === "object" && value !== null && !Array.isArray(value);
+const probability = (value: unknown): value is number => typeof value === "number" && Number.isFinite(value) && value >= 0 && value <= 1;
+
+function verdict(parsed: unknown, threshold: number): StageResult {
+  const answers = object(parsed) ? parsed.answers : undefined;
+  const answer = Array.isArray(answers) && answers.length === 1 ? answers[0] : undefined;
+  if (!object(answer) || answer.name !== "permission" || answer.type !== "choice" || typeof answer.choice !== "string" ||
+      !Object.hasOwn(criteria, answer.choice) || !probability(answer.confidence) || !Array.isArray(answer.probabilities))
+    throw new ReviewFailure("invalid-output", "Invalid decision answer");
+  const distribution = new Map<string, number>();
+  for (const entry of answer.probabilities) {
+    if (!object(entry) || typeof entry.value !== "string" || !Object.hasOwn(criteria, entry.value) ||
+        !probability(entry.probability) || distribution.has(entry.value))
+      throw new ReviewFailure("invalid-output", "Invalid decision probabilities");
+    distribution.set(entry.value, entry.probability);
+  }
+  const selected = distribution.get(answer.choice);
+  const values = [...distribution.values()];
+  if (distribution.size !== 3 || selected === undefined || Math.abs(values.reduce((a, b) => a + b, 0) - 1) > 0.01 || selected < Math.max(...values))
+    throw new ReviewFailure("invalid-output", "Inconsistent decision probabilities");
+  if (answer.choice === "ask" || answer.confidence < threshold || selected < threshold)
+    return { decision: "abstain", stage: "decision", reason: "Decision stage abstained below the confidence threshold" };
+  return { decision: answer.choice as "allow" | "deny", stage: "decision", reason: `Decision stage verdict (confidence ${answer.confidence})` };
+}
+
+/** Native stateless generation only. Unsupported providers and uncertain answers abstain. */
+export async function decisionStage(ctx: DecisionContext, options: DecisionOptions, request: PermissionRequest, signal?: AbortSignal, onError?: ReviewErrorObserver): Promise<StageResult> {
+  let bounded: AbortSignal | undefined;
+  try {
+    if (signal?.aborted) throw new ReviewFailure("cancelled", "Decision cancelled");
+    const timeoutMs = options.timeoutMs ?? 3000;
+    const minConfidence = options.minConfidence ?? 0.9;
+    if (!Number.isFinite(timeoutMs) || timeoutMs <= 0 || !probability(minConfidence))
+      throw new ReviewFailure("context", "Invalid decision options");
+    const evidence = reviewEvidence(request);
+    if (evidence.incompleteEvidence) throw new ReviewFailure("context", "Incomplete decision evidence");
+    const input: DecisionInput = {
+      model: Model.Ref.parse(options.model),
+      input: [{ type: "text", text: JSON.stringify(evidence) }],
+      questions: [{ name: "permission", type: "choice",
+        instructions: `Evaluate the whole pending action and its blast radius, including command chains, scripts, deletes, egress and history changes. ${AUTHORITY_RULES} Choose ask when safety, authorization or temporal scope is uncertain.`,
+        choices: Object.entries(criteria).map(([value, description]) => ({ value, description })),
+      }],
+    };
+    if (Buffer.byteLength(JSON.stringify(input)) > 65_536) throw new ReviewFailure("context", "Decision request too large");
+    bounded = signal ? AbortSignal.any([signal, AbortSignal.timeout(timeoutMs)]) : AbortSignal.timeout(timeoutMs);
+    const response = await withTimeout(ctx.experimental.generate.decisions(input, { signal: bounded }), timeoutMs, signal);
+    return verdict(response, minConfidence);
+  } catch (error) {
+    try { onError?.(error); } catch { /* Debug collection must not affect permission decisions. */ }
+    const localTimeout = !signal?.aborted && bounded?.aborted && bounded.reason instanceof DOMException && bounded.reason.name === "TimeoutError";
+    return { decision: "abstain", stage: "decision", reason: "Decision stage unavailable or returned invalid output", errorKind: localTimeout ? "timeout" : signal?.aborted ? "cancelled" : errorKindOf(error) };
+  }
+}

package/src/errors.ts

@@ -0,0 +1,39 @@
+/** Stable, bounded categories for a review that could not reach a confident decision. */
+export type ReviewErrorKind = "deadline" | "timeout" | "cancelled" | "provider" | "invalid-output" | "context";
+
+export class ReviewFailure extends Error {
+  constructor(readonly kind: ReviewErrorKind, message: string, options?: { cause?: unknown }) {
+    super(message, options);
+    this.name = "ReviewFailure";
+  }
+}
+
+/** Finds an explicit category even when a provider library wraps our failure. */
+function explicitKind(error: unknown): ReviewErrorKind | undefined {
+  let current = error;
+  for (let depth = 0; depth < 4; depth++) {
+    if (current instanceof ReviewFailure) return current.kind;
+    if (typeof current !== "object" || current === null) return undefined;
+    const cause = (current as { cause?: unknown }).cause;
+    if (cause === undefined || cause === current) return undefined;
+    current = cause;
+  }
+  return undefined;
+}
+
+/** Maps arbitrary thrown values to a bounded category without exposing provider text. */
+export function errorKindOf(error: unknown): ReviewErrorKind {
+  // Only ReviewFailure marks malformed reviewer output. Provider text such as
+  // "Invalid API key" stays a provider failure even when a wrapper reuses it.
+  const explicit = explicitKind(error);
+  if (explicit !== undefined) return explicit;
+  const name = error instanceof Error ? error.name : "";
+  const message = error instanceof Error ? error.message : "";
+  // AbortSignal.timeout() aborts with a TimeoutError whose message also says
+  // "aborted"; a provider's own timeout is not a user interruption.
+  if (name === "TimeoutError" ||
+      (typeof DOMException === "function" && error instanceof DOMException && error.code === DOMException.TIMEOUT_ERR)) return "timeout";
+  if (name === "AbortError" || /abort|cancel/i.test(message)) return "cancelled";
+  if (/timeout|timed out/i.test(message)) return "timeout";
+  return "provider";
+}

package/src/gates.ts

@@ -0,0 +1,16 @@
+export interface VcsState {
+  branch?: string;
+  defaultBranch?: string;
+  upstream?: string;
+  clean: boolean;
+}
+export interface VcsGateResult { allowed: boolean; reason: string }
+
+/** Missing VCS facts are not evidence that a destructive operation is safe. */
+export function evaluateVcsGate(state?: VcsState): VcsGateResult {
+  if (!state?.branch || !state.defaultBranch) return { allowed: false, reason: "VCS branch/default branch unknown" };
+  if (state.branch === state.defaultBranch) return { allowed: false, reason: "History changes on the default branch are protected" };
+  if (!state.upstream) return { allowed: false, reason: "History changes require an upstream" };
+  if (state.clean !== true) return { allowed: false, reason: "History changes require a clean working tree" };
+  return { allowed: true, reason: "Non-default branch with upstream and clean working tree" };
+}

package/src/global-options.ts

@@ -0,0 +1,85 @@
+import { lstatSync, readFileSync, realpathSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, isAbsolute, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { object } from "./config.js";
+import { parseJSONC, readUserOwnedFile } from "./user-files.js";
+
+interface PackageIdentity { directory: string; name: string }
+// Resolve lazily so callers can catch layout failures and disable auto mode.
+function packageIdentity(): PackageIdentity {
+  const directory = realpathSync(fileURLToPath(new URL("..", import.meta.url)));
+  const manifest: unknown = JSON.parse(readFileSync(join(directory, "package.json"), "utf8"));
+  if (!object(manifest) || typeof manifest.name !== "string") throw new Error("Invalid plugin package identity");
+  return { directory, name: manifest.name };
+}
+function hasSubstitution(value: string): boolean { return /\{(?:env|file):[^}]*\}/.test(value); }
+function rejectSubstitutions(value: unknown): void {
+  if (typeof value === "string" && hasSubstitution(value))
+    throw new Error("Global auto-mode registration contains unsupported env/file substitution; use concrete selected values in personal configuration");
+  if (Array.isArray(value)) value.forEach(rejectSubstitutions);
+  else if (object(value)) {
+    for (const [key, item] of Object.entries(value)) {
+      rejectSubstitutions(key);
+      rejectSubstitutions(item);
+    }
+  }
+}
+
+function matchesRegistration(value: string, configFile: string, identity: PackageIdentity): boolean {
+  const packageName = identity.name;
+  // A package version suffix is allowed, but lookalike package names are not.
+  if (value === packageName || value.startsWith(packageName + "@")) return true;
+  let local: string;
+  if (value.startsWith("file://")) {
+    try { local = fileURLToPath(value); } catch { return false; }
+  } else if (isAbsolute(value) || value.startsWith("./") || value.startsWith("../")) {
+    local = resolve(dirname(configFile), value);
+  } else return false;
+  try { return realpathSync(local) === identity.directory; } catch { return false; }
+}
+
+/** Safety options are read from user-owned global files, never merged SDK data.
+ * No registration, duplicate registrations or ambiguous global files fail closed.
+ * This function has no configurable path override: XDG_CONFIG_HOME is process
+ * environment, not a plugin option a repository registration can replace.
+ * SDK env/file substitutions are deliberately unsupported: select concrete
+ * values in personal configuration; this loader never expands arbitrary files.
+ */
+export function loadGlobalOptions(projectDir?: string): unknown {
+  const identity = packageIdentity();
+  const base = process.env.XDG_CONFIG_HOME || join(homedir(), ".config");
+  if (!isAbsolute(base)) throw new Error("XDG_CONFIG_HOME must be absolute");
+  const files = [join(base, "opencode", "opencode.json"), join(base, "opencode", "opencode.jsonc")];
+  const registrations: unknown[] = [];
+  for (const file of files) {
+    try { lstatSync(file); }
+    catch (error) {
+      if ((error as NodeJS.ErrnoException).code === "ENOENT") continue;
+      throw error;
+    }
+    const config = parseJSONC(readUserOwnedFile(file, projectDir));
+    if (!object(config)) throw new Error("Global OpenCode configuration must be an object");
+    if (config.plugins === undefined) continue;
+    if (!Array.isArray(config.plugins)) throw new Error("Global plugins must be an array");
+    for (const entry of config.plugins) {
+      const name = typeof entry === "string" ? entry : object(entry) ? entry.package : undefined;
+      if (typeof name !== "string") continue;
+      // We cannot establish package identity through substitution without
+      // implementing the SDK's expansion. Reject rather than silently skip it.
+      if (hasSubstitution(name)) rejectSubstitutions(name);
+      if (!matchesRegistration(name, file, identity)) continue;
+      rejectSubstitutions(entry);
+      if (typeof entry === "string") registrations.push({});
+      else {
+        if (!object(entry) || Object.keys(entry).some((key) => !["package", "options"].includes(key)))
+          throw new Error("Unknown global auto-mode registration fields");
+        registrations.push(entry.options ?? {});
+      }
+    }
+  }
+  if (registrations.length !== 1)
+    throw new Error(registrations.length === 0 ? "Auto-mode is not registered in user-owned global configuration" :
+      "Ambiguous auto-mode global registrations");
+  return registrations[0];
+}