opencode-castlegate 0.1.0

package/src/index.ts

@@ -0,0 +1,245 @@
+import type { Plugin, Hooks } from "@opencode-ai/plugin";
+import { safeParseConfig, type CastlegateConfig } from "./config.ts";
+import { CastlegateIntentMismatchError, CASTLEGATE_TAG } from "./errors.ts";
+import {
+  clearValidatorCache,
+  shouldValidate,
+  validateToolCall,
+  fallbackDecision,
+} from "./validate.ts";
+import { createSidecar, updateDigest } from "./intent.ts";
+import { loadDigest, resolveStorageDir, deleteDigest } from "./store.ts";
+import { createLogger, redactedArgKeys } from "./log.ts";
+import { createIntentContextTool } from "./tools/intent-context.ts";
+
+interface SessionState {
+  pendingDigestUpdate: ReturnType<typeof setTimeout> | null;
+  debounceMs: number;
+}
+
+const DEBOUNCE_MS = 1000;
+
+export const CastlegatePlugin: Plugin = async (input, options) => {
+  const raw = (options ?? {}) as Record<string, unknown>;
+  const parsed = safeParseConfig(raw);
+  if (!parsed.ok) {
+    await input.client.app
+      .log({
+        body: {
+          service: "castlegate",
+          level: "error",
+          message: "invalid castlegate config; plugin disabled",
+          extra: { issues: parsed.error.issues },
+        },
+      })
+      .catch(() => {});
+    return {};
+  }
+
+  const cfg: CastlegateConfig = parsed.config;
+  const log = createLogger(input.client, cfg);
+  const sidecar = createSidecar();
+  const sessionStates = new Map<string, SessionState>();
+
+  function getSessionState(sessionID: string): SessionState {
+    let state = sessionStates.get(sessionID);
+    if (!state) {
+      state = { pendingDigestUpdate: null, debounceMs: DEBOUNCE_MS };
+      sessionStates.set(sessionID, state);
+    }
+    return state;
+  }
+
+  function scheduleDigestUpdate(sessionID: string): void {
+    const state = getSessionState(sessionID);
+    if (state.pendingDigestUpdate) clearTimeout(state.pendingDigestUpdate);
+    state.pendingDigestUpdate = setTimeout(() => {
+      state.pendingDigestUpdate = null;
+      void runDigestUpdate(sessionID);
+    }, state.debounceMs);
+  }
+
+  async function runDigestUpdate(sessionID: string): Promise<void> {
+    try {
+      const result = await updateDigest(
+        { client: input.client, sessionId: sessionID, cfg },
+        sidecar,
+      );
+      if (!result.skipped) {
+        await log.event("intent.updated", {
+          sessionID,
+          version: result.version,
+          compacted: result.compacted,
+          intentShift: result.intentShift,
+          chars: result.digest.length,
+        });
+      }
+    } catch (err) {
+      await log.event("intent.update_error", {
+        sessionID,
+        error: err instanceof Error ? err.message : String(err),
+      });
+    }
+  }
+
+  async function ensureInitialized(sessionID: string): Promise<void> {
+    const dir = resolveStorageDir(input.directory, cfg.storage.directory);
+    const existing = await loadDigest(dir, sessionID);
+    if (!existing) {
+      const { saveDigest } = await import("./store.ts");
+      await saveDigest(dir, sessionID, "", { baseVersion: 0, lastMessageId: null });
+    }
+  }
+
+  return {
+    dispose: async () => {
+      for (const state of sessionStates.values()) {
+        if (state.pendingDigestUpdate) clearTimeout(state.pendingDigestUpdate);
+      }
+      sessionStates.clear();
+      clearValidatorCache();
+    },
+
+    event: async ({ event }) => {
+      switch (event.type) {
+        case "session.created": {
+          const sessionID = (event.properties.info as { id?: string }).id;
+          if (!sessionID) return;
+          try {
+            await ensureInitialized(sessionID);
+            await log.event("session.initialized", { sessionID });
+          } catch (err) {
+            await log.event("session.init_error", {
+              sessionID,
+              error: err instanceof Error ? err.message : String(err),
+            });
+          }
+          break;
+        }
+        case "session.deleted": {
+          const sessionID = (event.properties.info as { id?: string }).id;
+          if (!sessionID) return;
+          try {
+            const dir = resolveStorageDir(input.directory, cfg.storage.directory);
+            await deleteDigest(dir, sessionID);
+            sessionStates.delete(sessionID);
+            await log.event("session.deleted", { sessionID });
+          } catch (err) {
+            await log.event("session.delete_error", {
+              sessionID,
+              error: err instanceof Error ? err.message : String(err),
+            });
+          }
+          break;
+        }
+        case "message.updated": {
+          const info = event.properties.info as { sessionID?: string; id?: string };
+          const sessionID = info.sessionID;
+          if (!sessionID) return;
+          scheduleDigestUpdate(sessionID);
+          break;
+        }
+        case "message.part.updated":
+        case "message.part.removed":
+        case "message.removed": {
+          const props = event.properties as { sessionID?: string };
+          if (props.sessionID) scheduleDigestUpdate(props.sessionID);
+          break;
+        }
+      }
+    },
+
+    "tool.execute.before": async (toolInput, output) => {
+      const { tool, sessionID } = toolInput;
+      if (!sessionID) return;
+      if (!shouldValidate(tool, cfg)) return;
+
+      const dir = resolveStorageDir(input.directory, cfg.storage.directory);
+      let file;
+      try {
+        file = await loadDigest(dir, sessionID);
+      } catch (err) {
+        await log.event("validate.digest_load_error", {
+          sessionID,
+          tool,
+          error: err instanceof Error ? err.message : String(err),
+        });
+        if (!cfg.validate.failOpenOnError) {
+          throw new CastlegateIntentMismatchError(
+            tool,
+            "castlegate: digest store unavailable",
+            "medium",
+          );
+        }
+        return;
+      }
+
+      const digest = file?.body ?? "";
+      const digestVersion = file?.header.digestVersion ?? 0;
+
+      if (!digest) {
+        await log.event("validate.skip_no_digest", { sessionID, tool });
+        return;
+      }
+
+      let decision;
+      try {
+        decision = await validateToolCall({
+          client: input.client,
+          cfg,
+          digest,
+          digestVersion,
+          tool,
+          callArgs: output.args,
+          sidecar,
+        });
+      } catch (err) {
+        await log.event("validate.error", {
+          sessionID,
+          tool,
+          error: err instanceof Error ? err.message : String(err),
+        });
+        const fallback = fallbackDecision(tool, cfg);
+        if (fallback.match) return;
+        throw new CastlegateIntentMismatchError(tool, fallback.reason, fallback.severity);
+      }
+
+      if (decision.result.match) {
+        await log.event("validate.match", {
+          sessionID,
+          tool,
+          cached: decision.cached,
+          severity: decision.result.severity,
+        });
+        return;
+      }
+
+      await log.event("validate.mismatch", {
+        sessionID,
+        tool,
+        reason: decision.result.reason,
+        severity: decision.result.severity,
+        argKeys: redactedArgKeys(output.args),
+      });
+
+      if (!cfg.validate.requireApprovalOnMismatch) {
+        await log.event("validate.mismatch_allowed_by_config", { sessionID, tool });
+        return;
+      }
+
+      throw new CastlegateIntentMismatchError(
+        tool,
+        decision.result.reason,
+        decision.result.severity,
+      );
+    },
+
+    tool: {
+      intent_context: createIntentContextTool(() => cfg),
+    },
+  } satisfies Hooks;
+};
+
+export default CastlegatePlugin;
+
+export { CastlegateIntentMismatchError, CASTLEGATE_TAG };

package/src/intent.ts

@@ -0,0 +1,196 @@
+import type { CastlegateConfig } from "./config.ts";
+import { loadDigest, saveDigest, needsCompact, resolveStorageDir } from "./store.ts";
+import {
+  buildIntentUpdatePrompt,
+  parseIntentUpdateResponse,
+  enforceMaxChars,
+} from "./prompts/intent-update.ts";
+import { buildSidecarPromptBody } from "./prompt-body.ts";
+import type { PluginInput } from "@opencode-ai/plugin";
+
+type PluginClient = PluginInput["client"];
+
+export interface UpdateDigestArgs {
+  client: PluginClient;
+  sessionId: string;
+  cfg: CastlegateConfig;
+  sinceMessageId?: string | null;
+  newMessages?: Array<{ role: string; author?: string; text: string }>;
+}
+
+export interface UpdateDigestResult {
+  digest: string;
+  version: number;
+  compacted: boolean;
+  intentShift: string;
+  skipped: boolean;
+}
+
+async function ensureSidecarSession(client: PluginClient): Promise<string> {
+  const created = await client.session.create({
+    body: { title: "[castlegate] validator sidecar" },
+  });
+  if (!created.data) {
+    throw new Error("castlegate: failed to create sidecar session");
+  }
+  return created.data.id;
+}
+
+async function getSidecarId(
+  client: PluginClient,
+  cache: { id: string | null; pending: Promise<string> | null },
+): Promise<string> {
+  if (cache.id) return cache.id;
+  if (!cache.pending) {
+    cache.pending = ensureSidecarSession(client).then((id) => {
+      cache.id = id;
+      return id;
+    });
+  }
+  return cache.pending;
+}
+
+export function createSidecar(): { id: string | null; pending: Promise<string> | null } {
+  return { id: null, pending: null };
+}
+
+async function fetchRecentMessages(
+  client: PluginClient,
+  sessionId: string,
+  sinceMessageId: string | null | undefined,
+  limit: number,
+): Promise<Array<{ id: string; role: string; author?: string; text: string }>> {
+  const result = await client.session.messages({ path: { id: sessionId } });
+  const data = result.data ?? [];
+  const collected: Array<{ id: string; role: string; author?: string; text: string }> = [];
+  let started = sinceMessageId == null;
+
+  for (let i = data.length - 1; i >= 0 && collected.length < limit; i--) {
+    const item = data[i]!;
+    if (!started && item.info.id === sinceMessageId) {
+      started = true;
+      continue;
+    }
+    if (!started) continue;
+
+    const role = (item.info as { role?: string }).role ?? "unknown";
+    const author = (item.info as { agent?: string }).agent;
+
+    const text = item.parts
+      .map((p: { type?: string; text?: string }) => {
+        const t = p.type;
+        if (t === "text" && typeof p.text === "string") {
+          return p.text;
+        }
+        return "";
+      })
+      .filter(Boolean)
+      .join("\n");
+
+    if (!text) continue;
+    collected.push({ id: item.info.id, role, ...(author ? { author } : {}), text });
+  }
+
+  return collected.reverse();
+}
+
+async function callLightweightModel(
+  client: PluginClient,
+  sidecarId: string,
+  cfg: CastlegateConfig,
+  prompt: string,
+): Promise<string> {
+  const result = await client.session.prompt({
+    path: { id: sidecarId },
+    body: buildSidecarPromptBody(cfg, prompt),
+  });
+
+  const parts = result.data?.parts ?? [];
+  const texts = parts
+    .map((p: { type?: string; text?: string }) => {
+      const t = p.type;
+      if (t === "text" && typeof p.text === "string") {
+        return p.text;
+      }
+      return "";
+    })
+    .filter(Boolean);
+  return texts.join("\n").trim();
+}
+
+export async function updateDigest(
+  args: UpdateDigestArgs,
+  sidecar: ReturnType<typeof createSidecar>,
+): Promise<UpdateDigestResult> {
+  const { client, sessionId, cfg, sinceMessageId, newMessages } = args;
+  const dir = resolveStorageDir(process.cwd(), cfg.storage.directory);
+  const existing = await loadDigest(dir, sessionId);
+
+  const freshMessages =
+    newMessages ??
+    (await fetchRecentMessages(
+      client,
+      sessionId,
+      sinceMessageId ?? existing?.header.lastMessageId ?? null,
+      cfg.intent.maxRecentMessages,
+    ));
+
+  if (freshMessages.length === 0 && existing) {
+    return {
+      digest: existing.body,
+      version: existing.header.digestVersion,
+      compacted: false,
+      intentShift: "",
+      skipped: true,
+    };
+  }
+
+  if (freshMessages.length === 0 && !existing) {
+    return {
+      digest: "",
+      version: 0,
+      compacted: false,
+      intentShift: "",
+      skipped: true,
+    };
+  }
+
+  const compact = existing
+    ? needsCompact(existing.body, cfg.intent.maxChars, cfg.intent.compactThreshold)
+    : false;
+
+  const prompt = buildIntentUpdatePrompt({
+    previousDigest: existing?.body ?? "",
+    maxChars: cfg.intent.maxChars,
+    newMessages: freshMessages.map((m) => ({
+      role: m.role,
+      ...(m.author ? { author: m.author } : {}),
+      text: m.text,
+    })),
+    compact,
+  });
+
+  const sidecarId = await getSidecarId(client, sidecar);
+  const raw = await callLightweightModel(client, sidecarId, cfg, prompt);
+  const parsed = parseIntentUpdateResponse(raw);
+
+  const safeDigest = enforceMaxChars(parsed.digest, cfg.intent.maxChars);
+  const lastFresh = freshMessages[freshMessages.length - 1] as
+    | { id: string; role: string; author?: string; text: string }
+    | undefined;
+  const lastId = lastFresh?.id ?? existing?.header.lastMessageId ?? null;
+  const baseVersion = existing?.header.digestVersion ?? 0;
+
+  const header = await saveDigest(dir, sessionId, safeDigest, {
+    baseVersion,
+    lastMessageId: lastId,
+  });
+
+  return {
+    digest: safeDigest,
+    version: header.digestVersion,
+    compacted: compact,
+    intentShift: parsed.intentShift,
+    skipped: false,
+  };
+}

package/src/log.ts

@@ -0,0 +1,62 @@
+import type { PluginInput } from "@opencode-ai/plugin";
+import type { CastlegateConfig } from "./config.ts";
+
+type LogLevel = "debug" | "info" | "warn" | "error";
+
+export interface Logger {
+  event(name: string, fields: Record<string, unknown>): Promise<void>;
+  warn(name: string, fields: Record<string, unknown>): Promise<void>;
+  error(name: string, fields: Record<string, unknown>): Promise<void>;
+}
+
+export function createLogger(client: PluginInput["client"], cfg: CastlegateConfig): Logger {
+  const send = async (level: LogLevel, name: string, fields: Record<string, unknown>) => {
+    if (!cfg.logging && level !== "error") return;
+    try {
+      await client.app.log({
+        body: {
+          service: "castlegate",
+          level,
+          message: name,
+          extra: fields,
+        },
+      });
+    } catch {
+      // never let logging break the plugin
+    }
+  };
+
+  return {
+    async event(name, fields) {
+      await send("info", name, fields);
+    },
+    async warn(name, fields) {
+      await send("warn", name, fields);
+    },
+    async error(name, fields) {
+      await send("error", name, fields);
+    },
+  };
+}
+
+export function redactedArgKeys(args: unknown): string[] {
+  if (!args || typeof args !== "object") return [];
+  try {
+    return Object.keys(args as Record<string, unknown>);
+  } catch {
+    return [];
+  }
+}
+
+export function previewArgValue(value: unknown, maxLen = 80): string {
+  if (value == null) return String(value);
+  if (typeof value === "string") {
+    return value.length <= maxLen ? value : value.slice(0, maxLen) + "...";
+  }
+  try {
+    const s = JSON.stringify(value);
+    return s.length <= maxLen ? s : s.slice(0, maxLen) + "...";
+  } catch {
+    return "(unserializable)";
+  }
+}

package/src/prompt-body.ts

@@ -0,0 +1,27 @@
+import type { CastlegateConfig } from "./config.ts";
+
+export interface SidecarPromptBody {
+  model?: { providerID: string; modelID: string };
+  system: string;
+  parts: Array<{ type: "text"; text: string }>;
+}
+
+const SYSTEM_PROMPT =
+  "You are a precise, terse JSON-producing subagent. Respond only with the requested JSON, no preamble, no fences.";
+
+export function buildSidecarPromptBody(
+  cfg: CastlegateConfig,
+  prompt: string,
+): SidecarPromptBody {
+  const body: SidecarPromptBody = {
+    system: SYSTEM_PROMPT,
+    parts: [{ type: "text", text: prompt }],
+  };
+  if (cfg.model) {
+    body.model = {
+      providerID: cfg.model.providerID,
+      modelID: cfg.model.modelID,
+    };
+  }
+  return body;
+}

package/src/prompts/intent-update.ts

@@ -0,0 +1,107 @@
+import type { CastlegateConfig } from "../config.ts";
+
+export interface IntentUpdatePromptArgs {
+  previousDigest: string;
+  maxChars: number;
+  newMessages: Array<{
+    role: string;
+    author?: string;
+    text: string;
+  }>;
+  compact: boolean;
+}
+
+export function buildIntentUpdatePrompt(args: IntentUpdatePromptArgs): string {
+  const { previousDigest, maxChars, newMessages, compact } = args;
+
+  const messagesBlock = newMessages
+    .map((m) => {
+      const who = m.author ? `${m.role}/${m.author}` : m.role;
+      return `[${who}] ${m.text}`;
+    })
+    .join("\n\n");
+
+  const digestBlock = previousDigest
+    ? previousDigest
+    : "(no prior digest — first update for this session)";
+
+  const instruction = compact
+    ? "This update must REPLACE the previous digest with a shorter summary while preserving the anchor intent (the user's original goal)."
+    : "This update MERGES the previous digest with new context. Preserve everything that still matters; drop nothing important.";
+
+  return `You are the castlegate intent synthesizer. Maintain a compact digest of the user's session intent so downstream code can validate tool calls against it.
+
+${instruction}
+
+# Hard rules
+- Stay under ${maxChars} characters total.
+- Always preserve the ANCHOR INTENT (the user's original overarching goal) verbatim if it still appears to be the goal.
+- Capture: (a) current objective, (b) active constraints/scope, (c) in-progress tasks, (d) explicit out-of-scope items, (e) recent intent shifts.
+- Be terse. No prose, only structured bullets.
+- NEVER execute actions or call tools — your only job is to update the digest text.
+
+# Previous digest
+${digestBlock}
+
+# New messages since last digest update
+${messagesBlock || "(none)"}
+
+# Output format (REQUIRED)
+Respond with a single JSON object, no prose, no code fences:
+
+{"digest": "<the new digest body, ${maxChars} chars max>", "intentShift": "<one-sentence summary of any intent shift, or empty string if none>"}
+
+JSON:`;
+}
+
+export function parseIntentUpdateResponse(raw: string): {
+  digest: string;
+  intentShift: string;
+} {
+  const trimmed = raw.trim();
+
+  const fenceMatch = /```(?:json)?\s*([\s\S]*?)```/.exec(trimmed);
+  const candidate = fenceMatch ? fenceMatch[1]!.trim() : trimmed;
+
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(candidate);
+  } catch {
+    const objectMatch = /\{[\s\S]*\}/.exec(candidate);
+    if (!objectMatch) {
+      throw new Error("castlegate: intent update response is not valid JSON");
+    }
+    parsed = JSON.parse(objectMatch[0]);
+  }
+
+  if (
+    !parsed ||
+    typeof parsed !== "object" ||
+    typeof (parsed as Record<string, unknown>).digest !== "string"
+  ) {
+    throw new Error("castlegate: intent update response missing 'digest' string field");
+  }
+
+  const obj = parsed as Record<string, unknown>;
+  return {
+    digest: (obj.digest as string).trim(),
+    intentShift: typeof obj.intentShift === "string" ? obj.intentShift.trim() : "",
+  };
+}
+
+export function enforceMaxChars(digest: string, maxChars: number): string {
+  if (maxChars <= 0 || digest.length <= maxChars) return digest;
+  return digest.slice(0, maxChars);
+}
+
+export function configForPrompt(cfg: CastlegateConfig): {
+  maxChars: number;
+  compactThreshold: number;
+  maxRecentMessages: number;
+} {
+  return {
+    maxChars: cfg.intent.maxChars,
+    compactThreshold: cfg.intent.compactThreshold,
+    maxRecentMessages: cfg.intent.maxRecentMessages,
+  };
+}