@egoistmachines/opencode-switchboard 0.1.1

package/src/hostedTransport.js

@@ -0,0 +1,271 @@
+import { readFile, stat } from "node:fs/promises";
+
+import { GOVERNED_CATEGORIES } from "./config.js";
+import { OPENCODE_HOST_METADATA } from "./host.js";
+import { unavailableProposal, unavailableRead, withInternalReason } from "./outcomes.js";
+import { createTtlCache } from "./shared/cache.js";
+import { createCredentials } from "./shared/credentials.js";
+import { createPlaneTransport } from "./shared/transport.js";
+
+const QUERY_MAX_LENGTH = 256;
+const SESSION_KEY_MAX_LENGTH = 128;
+const LIMIT_MAX = 50;
+const PREFETCH_BUDGET_MAX = 30;
+const DEFAULT_CACHE_TTL_MS = 60_000;
+const SKIP_REASONS = new Set(["no_pass", "once_only", "locked"]);
+
+const boundedText = (value, max, collapseWhitespace = false) => {
+  if (typeof value !== "string") return null;
+  const normalized = collapseWhitespace ? value.replace(/\s+/g, " ").trim() : value.trim();
+  return normalized ? normalized.slice(0, max) : null;
+};
+
+const boundedLimit = (value, fallback = 20) => {
+  const candidate = typeof value === "number" && Number.isFinite(value) ? Math.round(value) : fallback;
+  return Math.min(LIMIT_MAX, Math.max(1, candidate));
+};
+
+const nullableString = (value) => value === null || typeof value === "string";
+
+function normalizeRow(row) {
+  if (
+    !row ||
+    typeof row !== "object" ||
+    Array.isArray(row) ||
+    typeof row.memory_id !== "string" ||
+    typeof row.content !== "string" ||
+    !nullableString(row.source) ||
+    !nullableString(row.created_at) ||
+    !nullableString(row.occurred_at) ||
+    !GOVERNED_CATEGORIES.includes(row.category) ||
+    !nullableString(row.client_id) ||
+    !nullableString(row.evidence_basis) ||
+    !nullableString(row.record_kind) ||
+    !nullableString(row.verified_issuer) ||
+    !nullableString(row.verified_at)
+  ) {
+    return null;
+  }
+  return {
+    memory_id: row.memory_id,
+    content: row.content,
+    source: row.source,
+    created_at: row.created_at,
+    occurred_at: row.occurred_at,
+    category: row.category,
+    client_id: row.client_id,
+    evidence_basis: row.evidence_basis,
+    record_kind: row.record_kind,
+    verified_issuer: row.verified_issuer,
+    verified_at: row.verified_at,
+  };
+}
+
+export function normalizeHostedPrefetch(payload, { categories, asOf }) {
+  if (!payload || typeof payload !== "object" || Array.isArray(payload)) return null;
+  if (!Array.isArray(payload.rows) || !Array.isArray(payload.skipped_categories)) return null;
+
+  const requested = new Set(categories);
+  const rows = payload.rows.map(normalizeRow);
+  if (rows.some((row) => !row) || rows.some((row) => !requested.has(row.category))) return null;
+
+  const skippedCategories = payload.skipped_categories.map((entry) => {
+    if (
+      !entry ||
+      typeof entry !== "object" ||
+      Array.isArray(entry) ||
+      !requested.has(entry.category) ||
+      !SKIP_REASONS.has(entry.reason)
+    ) {
+      return null;
+    }
+    return { category: entry.category, reason: entry.reason };
+  });
+  if (skippedCategories.some((entry) => !entry)) return null;
+
+  let status = "empty";
+  if (rows.length) status = "results";
+  else if (new Set(skippedCategories.map((entry) => entry.category)).size === requested.size) {
+    status = skippedCategories.every((entry) => entry.reason === "locked") ? "locked" : "blocked";
+  }
+
+  return {
+    status,
+    transport: "hosted",
+    connectivity: "online",
+    freshness: "fresh",
+    as_of: asOf,
+    rows,
+    skipped_categories: skippedCategories,
+  };
+}
+
+async function requireOwnerOnlyMode(credentialsPath) {
+  const metadata = await stat(credentialsPath);
+  if ((metadata.mode & 0o077) !== 0) {
+    const error = new Error("unsafe_hosted_credentials_mode");
+    error.code = "unsafe_hosted_credentials_mode";
+    throw error;
+  }
+}
+
+async function validateHostedCredentialsFile(credentialsPath) {
+  await requireOwnerOnlyMode(credentialsPath);
+  const record = JSON.parse(await readFile(credentialsPath, "utf8"));
+  if (!record || typeof record !== "object" || Array.isArray(record)) throw new Error("invalid_hosted_credentials");
+  for (const field of ["token_url", "client_id", "refresh_token"]) {
+    if (typeof record[field] !== "string" || !record[field].trim()) throw new Error("invalid_hosted_credentials");
+  }
+  const tokenUrl = new URL(record.token_url);
+  if (tokenUrl.protocol !== "https:" && tokenUrl.protocol !== "http:") throw new Error("invalid_hosted_credentials");
+}
+
+function guardedCredentials(credentials, credentialsPath) {
+  if (!credentialsPath) return credentials;
+  return {
+    async baseUrl() {
+      await validateHostedCredentialsFile(credentialsPath);
+      return credentials.baseUrl();
+    },
+    async accessToken(options) {
+      await validateHostedCredentialsFile(credentialsPath);
+      return credentials.accessToken(options);
+    },
+  };
+}
+
+function unavailableReason(state) {
+  if (state.backoffReason === "forbidden") return "hosted_plane_closed";
+  if (state.terminalReason) return `hosted_credentials_${state.terminalReason}`;
+  if (state.backoffReason) return `hosted_${state.backoffReason}`;
+  return "hosted_unavailable";
+}
+
+export function createHostedTransport({
+  credentialsPath,
+  timeoutMs = 1500,
+  cacheTtlMs = DEFAULT_CACHE_TTL_MS,
+  fetchImpl = globalThis.fetch,
+  now = () => Date.now(),
+  logger = null,
+  credentials: suppliedCredentials = null,
+} = {}) {
+  const rawCredentials =
+    suppliedCredentials ??
+    createCredentials({
+      credentialsPath,
+      fetchImpl,
+      now,
+      logger,
+      hostMetadata: OPENCODE_HOST_METADATA,
+    });
+  const credentials = guardedCredentials(rawCredentials, suppliedCredentials ? null : credentialsPath);
+  const plane = createPlaneTransport({
+    config: { baseUrl: null },
+    credentials,
+    fetchImpl,
+    logger,
+    now,
+    label: "prefetch",
+    budgetMax: PREFETCH_BUDGET_MAX,
+  });
+  const cache = createTtlCache({ ttlMs: cacheTtlMs, now });
+  const pending = new Map();
+  let lastOutcome = null;
+  let lastReason = null;
+
+  const read = async (input = {}) => {
+    const categories = Array.isArray(input.categories)
+      ? [...new Set(input.categories.filter((category) => GOVERNED_CATEGORIES.includes(category)))]
+      : [];
+    if (!categories.length) {
+      lastOutcome = "unavailable";
+      lastReason = "invalid_contract";
+      return unavailableRead("hosted", lastReason);
+    }
+    const query = boundedText(input.query, QUERY_MAX_LENGTH, true);
+    const sessionKey = boundedText(input.session_id ?? input.session_key, SESSION_KEY_MAX_LENGTH);
+    const limit = boundedLimit(input.limit);
+    const key = JSON.stringify([categories, limit, query ?? ""]);
+    const cached = cache.get(key);
+    if (cached.hit && cached.fresh) {
+      lastOutcome = cached.value.status;
+      lastReason = null;
+      return structuredClone(cached.value);
+    }
+    if (pending.has(key)) return pending.get(key);
+
+    const attempt = (async () => {
+      const unavailableOrStale = (reason) => {
+        lastReason = reason;
+        if (cached.hit) {
+          const stale = {
+            ...structuredClone(cached.value),
+            connectivity: "offline",
+            freshness: "stale",
+          };
+          lastOutcome = stale.status;
+          return withInternalReason(stale, reason);
+        }
+        lastOutcome = "unavailable";
+        return unavailableRead("hosted", reason);
+      };
+      const payload = await plane.request({
+        path: "/agent/prefetch",
+        method: "POST",
+        body: {
+          categories,
+          ...(query ? { query } : {}),
+          ...(sessionKey ? { session_key: sessionKey } : {}),
+          limit,
+        },
+        timeoutMs: typeof input.timeoutMs === "number" ? input.timeoutMs : timeoutMs,
+      });
+      if (!payload) {
+        return unavailableOrStale(unavailableReason(plane.state()));
+      }
+
+      const asOf = new Date(now()).toISOString();
+      const normalized = normalizeHostedPrefetch(payload, { categories, asOf });
+      if (!normalized) {
+        return unavailableOrStale("invalid_contract");
+      }
+      cache.set(key, normalized);
+      lastOutcome = normalized.status;
+      lastReason = null;
+      return structuredClone(normalized);
+    })().finally(() => pending.delete(key));
+    pending.set(key, attempt);
+    return attempt;
+  };
+
+  return {
+    async status() {
+      let paired = Boolean(suppliedCredentials);
+      if (!paired && credentialsPath) {
+        try {
+          await validateHostedCredentialsFile(credentialsPath);
+          paired = true;
+        } catch {}
+      }
+      return {
+        transport: "hosted",
+        paired,
+        lastOutcome,
+        lastReason,
+      };
+    },
+    prefetch: read,
+    recall(input = {}) {
+      return read({ ...input, ambient: false });
+    },
+    propose(input = {}) {
+      lastOutcome = "unavailable";
+      lastReason = "hosted_propose_unsupported";
+      return Promise.resolve(unavailableProposal("hosted", lastReason, input.save_id));
+    },
+    __state() {
+      return { ...plane.state(), cacheSize: cache.size, lastOutcome, lastReason };
+    },
+  };
+}

package/src/index.js

@@ -0,0 +1,12 @@
+import { tool } from "@opencode-ai/plugin";
+
+import { createPassportHooks } from "./plugin.js";
+
+// This is the only module that imports the host. Runtime logic remains
+// testable without installing OpenCode or its plugin package.
+export const AIPassportPlugin = async (input, options = {}) =>
+  (await createPassportHooks({
+    rawConfig: options,
+    tool,
+    project: typeof input?.directory === "string" ? input.directory : null,
+  })).hooks;

package/src/localTransport.js

@@ -0,0 +1,213 @@
+import { spawn as nodeSpawn } from "node:child_process";
+import { readFile, stat } from "node:fs/promises";
+import path from "node:path";
+
+import { normalizeProposalOutcome, normalizeReadOutcome, unavailableProposal, unavailableRead } from "./outcomes.js";
+
+const MAX_STDOUT_BYTES = 1024 * 1024;
+
+function normalizeHandoffClaimOutcome(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return null;
+  if (value.status === "none_pending") {
+    return { status: "none_pending", handoff_id: null, snapshot: null, expires_at: null };
+  }
+  if (value.status === "claimed") {
+    if (
+      typeof value.handoff_id !== "string" ||
+      !value.handoff_id ||
+      typeof value.snapshot !== "string" ||
+      !value.snapshot ||
+      typeof value.expires_at !== "string" ||
+      !value.expires_at
+    ) {
+      return null;
+    }
+    return {
+      status: "claimed",
+      handoff_id: value.handoff_id,
+      snapshot: value.snapshot,
+      expires_at: value.expires_at,
+    };
+  }
+  if (value.status === "expired") {
+    if (
+      typeof value.handoff_id !== "string" ||
+      !value.handoff_id ||
+      typeof value.expires_at !== "string" ||
+      !value.expires_at
+    ) {
+      return null;
+    }
+    return { status: "expired", handoff_id: value.handoff_id, snapshot: null, expires_at: value.expires_at };
+  }
+  return null;
+}
+
+const unavailableHandoffClaim = (_transport, reason) => ({
+  status: "unavailable",
+  handoff_id: null,
+  snapshot: null,
+  expires_at: null,
+  internalReason: reason,
+});
+
+async function readJson(filePath) {
+  const body = await readFile(filePath, "utf8");
+  const value = JSON.parse(body);
+  if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error("invalid_json_object");
+  return value;
+}
+
+async function loadRuntime(discoveryPath) {
+  const record = await readJson(discoveryPath);
+  if (typeof record.bin !== "string" || !path.isAbsolute(record.bin)) throw new Error("invalid_discovery_record");
+  return record.bin;
+}
+
+async function loadCredentials(credentialsPath) {
+  const metadata = await stat(credentialsPath);
+  if ((metadata.mode & 0o077) !== 0) throw new Error("unsafe_credentials_mode");
+  const record = await readJson(credentialsPath);
+  const secret = typeof record.client_secret === "string" ? record.client_secret : record.secret;
+  if (typeof record.client_id !== "string" || !record.client_id || typeof secret !== "string" || !secret) {
+    throw new Error("invalid_credentials");
+  }
+  return { client_id: record.client_id, client_secret: secret };
+}
+
+function runJsonCommand({ bin, command, payload, timeoutMs, spawnImpl }) {
+  return new Promise((resolve) => {
+    let settled = false;
+    let stdout = "";
+    const finish = (result) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      resolve(result);
+    };
+    let child;
+    try {
+      child = spawnImpl(bin, [command, "--json"], {
+        stdio: ["pipe", "pipe", "ignore"],
+        windowsHide: true,
+      });
+    } catch {
+      resolve({ ok: false, reason: "spawn_failed" });
+      return;
+    }
+    const timer = setTimeout(() => {
+      child.kill("SIGKILL");
+      finish({ ok: false, reason: "deadline_exceeded" });
+    }, timeoutMs);
+    timer.unref?.();
+
+    child.once("error", () => finish({ ok: false, reason: "spawn_failed" }));
+    child.stdout.setEncoding("utf8");
+    child.stdout.on("data", (chunk) => {
+      stdout += chunk;
+      if (Buffer.byteLength(stdout) > MAX_STDOUT_BYTES) {
+        child.kill("SIGKILL");
+        finish({ ok: false, reason: "stdout_too_large" });
+      }
+    });
+    child.once("close", (code) => {
+      if (settled) return;
+      if (code !== 0) {
+        finish({ ok: false, reason: "nonzero_exit" });
+        return;
+      }
+      try {
+        const parsed = JSON.parse(stdout);
+        if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) throw new Error("invalid_stdout");
+        finish({ ok: true, payload: parsed });
+      } catch {
+        finish({ ok: false, reason: "malformed_stdout" });
+      }
+    });
+    child.stdin.once("error", () => finish({ ok: false, reason: "stdin_failed" }));
+    child.stdin.end(`${JSON.stringify(payload)}\n`);
+  });
+}
+
+export function createLocalTransport({
+  discoveryPath,
+  credentialsPath,
+  timeoutMs = 1500,
+  spawnImpl = nodeSpawn,
+} = {}) {
+  let lastOutcome = null;
+  let lastReason = null;
+
+  const invoke = async (command, input, normalize, unavailable) => {
+    try {
+      const [bin, credentials] = await Promise.all([loadRuntime(discoveryPath), loadCredentials(credentialsPath)]);
+      const { timeoutMs: callTimeoutMs, ...commandInput } = input ?? {};
+      const executed = await runJsonCommand({
+        bin,
+        command,
+        payload: { ...commandInput, ...credentials },
+        timeoutMs: callTimeoutMs ?? timeoutMs,
+        spawnImpl,
+      });
+      if (!executed.ok) {
+        lastReason = executed.reason;
+        lastOutcome = "unavailable";
+        return unavailable("local", executed.reason, input?.save_id);
+      }
+      const outcome = normalize(executed.payload, "local");
+      const requestedCategories = Array.isArray(input?.categories) ? new Set(input.categories) : null;
+      const crossedCategoryBoundary =
+        command === "prefetch" &&
+        requestedCategories &&
+        [...(outcome?.rows ?? []), ...(outcome?.skipped_categories ?? [])].some(
+          (entry) => !requestedCategories.has(entry.category)
+        );
+      if (!outcome || crossedCategoryBoundary) {
+        lastReason = "invalid_contract";
+        lastOutcome = "unavailable";
+        return unavailable("local", "invalid_contract", input?.save_id);
+      }
+      lastReason = null;
+      lastOutcome = outcome.status;
+      return outcome;
+    } catch (error) {
+      const reason = error?.code === "ENOENT" ? "missing_local_state" : error?.message || "local_state_unavailable";
+      lastReason = reason;
+      lastOutcome = "unavailable";
+      return unavailable("local", reason, input?.save_id);
+    }
+  };
+
+  return {
+    async status() {
+      const result = {
+        transport: "local",
+        discoveryFound: false,
+        paired: false,
+        lastOutcome,
+        lastReason,
+      };
+      try {
+        await loadRuntime(discoveryPath);
+        result.discoveryFound = true;
+      } catch {}
+      try {
+        await loadCredentials(credentialsPath);
+        result.paired = true;
+      } catch {}
+      return result;
+    },
+    prefetch(input = {}) {
+      return invoke("prefetch", input, normalizeReadOutcome, unavailableRead);
+    },
+    recall(input = {}) {
+      return invoke("prefetch", { ...input, ambient: false }, normalizeReadOutcome, unavailableRead);
+    },
+    propose(input = {}) {
+      return invoke("propose", input, normalizeProposalOutcome, unavailableProposal);
+    },
+    claimHandoff(input = {}) {
+      return invoke("handoff-claim", input, normalizeHandoffClaimOutcome, unavailableHandoffClaim);
+    },
+  };
+}

package/src/outcomes.js

@@ -0,0 +1,104 @@
+import { GOVERNED_CATEGORIES } from "./config.js";
+
+export const READ_STATUSES = Object.freeze(["results", "empty", "blocked", "locked", "unavailable"]);
+export const PROPOSAL_STATUSES = Object.freeze(["recorded", "duplicate", "rejected", "unavailable"]);
+
+export function unavailableRead(transport, internalReason) {
+  return withInternalReason(
+    {
+      status: "unavailable",
+      transport,
+      connectivity: "offline",
+      freshness: "stale",
+      as_of: null,
+      rows: [],
+      skipped_categories: [],
+    },
+    internalReason
+  );
+}
+
+export function unavailableProposal(transport, internalReason, saveId = null) {
+  return withInternalReason(
+    {
+      status: "unavailable",
+      proposal_id: null,
+      save_id: typeof saveId === "string" && saveId ? saveId : null,
+      disposition: "pending",
+    },
+    internalReason
+  );
+}
+
+export function withInternalReason(outcome, internalReason) {
+  Object.defineProperty(outcome, "internalReason", {
+    configurable: false,
+    enumerable: false,
+    writable: false,
+    value: internalReason,
+  });
+  return outcome;
+}
+
+export function normalizeReadOutcome(payload, transport) {
+  if (!payload || typeof payload !== "object" || Array.isArray(payload)) return null;
+  if (!READ_STATUSES.includes(payload.status)) return null;
+  if (!Array.isArray(payload.rows) || !Array.isArray(payload.skipped_categories)) return null;
+  if (payload.transport !== transport) return null;
+  if (payload.connectivity !== "online" && payload.connectivity !== "offline") return null;
+  if (payload.freshness !== "fresh" && payload.freshness !== "stale") return null;
+  if (payload.as_of !== null && typeof payload.as_of !== "string") return null;
+  if (payload.status === "results" && payload.rows.length === 0) return null;
+  if (payload.status !== "results" && payload.rows.length > 0) return null;
+  const nullableString = (value) => value === null || typeof value === "string";
+  const rows = payload.rows.filter(
+    (row) =>
+      row &&
+      typeof row === "object" &&
+      typeof row.memory_id === "string" &&
+      typeof row.content === "string" &&
+      nullableString(row.source) &&
+      typeof row.created_at === "string" &&
+      GOVERNED_CATEGORIES.includes(row.category) &&
+      nullableString(row.occurred_at) &&
+      nullableString(row.client_id) &&
+      nullableString(row.evidence_basis) &&
+      nullableString(row.record_kind) &&
+      nullableString(row.verified_issuer) &&
+      nullableString(row.verified_at)
+  );
+  if (rows.length !== payload.rows.length) return null;
+  const skippedCategories = payload.skipped_categories.filter(
+    (entry) =>
+      entry &&
+      typeof entry === "object" &&
+      GOVERNED_CATEGORIES.includes(entry.category) &&
+      GOVERNED_SKIP_REASONS.has(entry.reason)
+  );
+  if (skippedCategories.length !== payload.skipped_categories.length) return null;
+  return {
+    status: payload.status,
+    transport,
+    connectivity: payload.connectivity,
+    freshness: payload.freshness,
+    as_of: payload.as_of,
+    rows,
+    skipped_categories: skippedCategories,
+  };
+}
+
+export function normalizeProposalOutcome(payload) {
+  if (!payload || typeof payload !== "object" || Array.isArray(payload)) return null;
+  if (!PROPOSAL_STATUSES.includes(payload.status)) return null;
+  if (payload.disposition !== "auto_approved" && payload.disposition !== "pending") return null;
+  if (typeof payload.save_id !== "string" || !payload.save_id) return null;
+  if (payload.proposal_id !== null && typeof payload.proposal_id !== "string") return null;
+  return {
+    status: payload.status,
+    proposal_id: payload.proposal_id,
+    save_id: payload.save_id,
+    disposition: payload.disposition,
+  };
+}
+
+const GOVERNED_SKIP_REASONS = new Set(["no_pass", "once_only", "locked"]);