opencode-castlegate 0.1.0

package/src/prompts/intent-validate.ts

@@ -0,0 +1,106 @@
+export interface IntentValidatePromptArgs {
+  digest: string;
+  tool: string;
+  argsSummary: string;
+}
+
+export function buildIntentValidatePrompt(args: IntentValidatePromptArgs): string {
+  const { digest, tool, argsSummary } = args;
+
+  return `You are the castlegate intent validator. Decide whether a proposed tool call matches the user's stated session intent.
+
+# User intent digest
+${digest || "(no digest yet — answer conservatively, prefer mismatch)"}
+
+# Proposed tool call
+- Tool: ${tool}
+- Arguments: ${argsSummary}
+
+# Decision rules
+- "match" = the call directly advances, supports, or is a routine side-effect of the intent in the digest.
+- "mismatch" = the call is unrelated, contradicts, or exceeds the scope of the stated intent.
+- When in doubt, prefer mismatch and assign severity "medium".
+- Severity: "low" (mismatch but reversible + low blast radius), "medium" (file writes, network, install), "high" (destructive, irreversible, secret-bearing).
+
+# Output format (REQUIRED)
+Respond with a single JSON object, no prose, no fences:
+
+{"match": <bool>, "reason": "<short rationale>", "severity": "low" | "medium" | "high"}
+
+JSON:`;
+}
+
+export interface IntentValidateResult {
+  match: boolean;
+  reason: string;
+  severity: "low" | "medium" | "high";
+}
+
+export function parseIntentValidateResponse(raw: string): IntentValidateResult {
+  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: validator response is not valid JSON");
+    }
+    parsed = JSON.parse(objectMatch[0]);
+  }
+
+  if (!parsed || typeof parsed !== "object") {
+    throw new Error("castlegate: validator response is not a JSON object");
+  }
+
+  const obj = parsed as Record<string, unknown>;
+  const match = obj.match;
+  if (typeof match !== "boolean") {
+    throw new Error("castlegate: validator response missing boolean 'match'");
+  }
+
+  const reason = typeof obj.reason === "string" ? obj.reason.trim() : "";
+  let severity: "low" | "medium" | "high" = "medium";
+  if (obj.severity === "low" || obj.severity === "medium" || obj.severity === "high") {
+    severity = obj.severity;
+  }
+
+  return { match, reason, severity };
+}
+
+export function summarizeArgs(tool: string, args: unknown): string {
+  if (args === undefined || args === null) return "(no arguments)";
+  try {
+    let raw = "";
+    if (typeof args === "string") raw = args;
+    else raw = JSON.stringify(args);
+
+    if (raw.length <= 1200) return raw;
+
+    if (tool === "bash" && typeof args === "object" && args !== null) {
+      const cmd = (args as Record<string, unknown>).command;
+      if (typeof cmd === "string") {
+        return JSON.stringify({ command: cmd.length > 1200 ? cmd.slice(0, 1200) + "..." : cmd });
+      }
+    }
+    if (tool === "read" && typeof args === "object" && args !== null) {
+      const fp = (args as Record<string, unknown>).filePath;
+      if (typeof fp === "string") return JSON.stringify({ filePath: fp });
+    }
+    if (tool === "edit" && typeof args === "object" && args !== null) {
+      const fp = (args as Record<string, unknown>).filePath;
+      if (typeof fp === "string") return JSON.stringify({ filePath: fp });
+    }
+    if (tool === "webfetch" && typeof args === "object" && args !== null) {
+      const url = (args as Record<string, unknown>).url;
+      if (typeof url === "string") return JSON.stringify({ url });
+    }
+    return raw.slice(0, 1200) + "...";
+  } catch {
+    return "(unserializable arguments)";
+  }
+}

package/src/store.ts

@@ -0,0 +1,162 @@
+import { promises as fs } from "node:fs";
+import * as path from "node:path";
+import * as os from "node:os";
+
+export interface DigestHeader {
+  digestVersion: number;
+  lastMessageId: string | null;
+  updatedAt: string;
+  charCount: number;
+}
+
+export interface DigestFile {
+  header: DigestHeader;
+  body: string;
+}
+
+const FRONTMATTER_RE = /^---\n([\s\S]*?)\n---\n?([\s\S]*)$/;
+
+function nowIso(): string {
+  return new Date().toISOString();
+}
+
+export function sanitizeId(id: string): string {
+  return id.replace(/[^a-zA-Z0-9._-]/g, "_").slice(0, 200);
+}
+
+export function digestPath(dir: string, sessionId: string): string {
+  return path.join(dir, `${sanitizeId(sessionId)}.md`);
+}
+
+export function needsCompact(body: string, maxChars: number, threshold: number): boolean {
+  if (maxChars <= 0) return false;
+  return body.length >= Math.floor(maxChars * threshold);
+}
+
+function parseFrontmatter(raw: string): DigestFile | null {
+  const match = FRONTMATTER_RE.exec(raw);
+  if (!match) return null;
+
+  const fmBlock = match[1] ?? "";
+  const body = match[2] ?? "";
+
+  const header: Partial<DigestHeader> = {};
+  for (const line of fmBlock.split("\n")) {
+    const idx = line.indexOf(":");
+    if (idx === -1) continue;
+    const key = line.slice(0, idx).trim();
+    const value = line.slice(idx + 1).trim();
+    if (key === "digestVersion") {
+      const n = Number(value);
+      if (Number.isFinite(n)) header.digestVersion = n;
+    } else if (key === "lastMessageId") {
+      header.lastMessageId = value === "" || value === "null" ? null : value;
+    } else if (key === "updatedAt") {
+      header.updatedAt = value;
+    } else if (key === "charCount") {
+      const n = Number(value);
+      if (Number.isFinite(n)) header.charCount = n;
+    }
+  }
+
+  if (
+    typeof header.digestVersion !== "number" ||
+    typeof header.updatedAt !== "string" ||
+    typeof header.charCount !== "number"
+  ) {
+    return null;
+  }
+
+  return {
+    header: header as DigestHeader,
+    body,
+  };
+}
+
+function serialize(header: DigestHeader, body: string): string {
+  const fm = [
+    "---",
+    `digestVersion: ${header.digestVersion}`,
+    `lastMessageId: ${header.lastMessageId ?? "null"}`,
+    `updatedAt: ${header.updatedAt}`,
+    `charCount: ${header.charCount}`,
+    "---",
+    "",
+  ].join("\n");
+  return `${fm}${body}`;
+}
+
+export async function loadDigest(dir: string, sessionId: string): Promise<DigestFile | null> {
+  try {
+    const raw = await fs.readFile(digestPath(dir, sessionId), "utf8");
+    return parseFrontmatter(raw);
+  } catch (err) {
+    if ((err as NodeJS.ErrnoException).code === "ENOENT") return null;
+    throw err;
+  }
+}
+
+export interface SaveOptions {
+  baseVersion?: number;
+  lastMessageId?: string | null;
+}
+
+export async function saveDigest(
+  dir: string,
+  sessionId: string,
+  body: string,
+  opts: SaveOptions = {},
+): Promise<DigestHeader> {
+  await fs.mkdir(dir, { recursive: true });
+
+  const previous = await loadDigest(dir, sessionId);
+  const header: DigestHeader = {
+    digestVersion: (opts.baseVersion ?? previous?.header.digestVersion ?? 0) + 1,
+    lastMessageId: opts.lastMessageId ?? previous?.header.lastMessageId ?? null,
+    updatedAt: nowIso(),
+    charCount: body.length,
+  };
+
+  const file = digestPath(dir, sessionId);
+  const tmp = path.join(
+    dir,
+    `.${sanitizeId(sessionId)}.${process.pid}.${Date.now()}.tmp`,
+  );
+
+  const handle = await fs.open(tmp, "w");
+  try {
+    await handle.writeFile(serialize(header, body), "utf8");
+    await handle.sync();
+  } finally {
+    await handle.close();
+  }
+
+  await fs.rename(tmp, file);
+  return header;
+}
+
+export async function deleteDigest(dir: string, sessionId: string): Promise<void> {
+  try {
+    await fs.unlink(digestPath(dir, sessionId));
+  } catch (err) {
+    if ((err as NodeJS.ErrnoException).code !== "ENOENT") throw err;
+  }
+}
+
+export function resolveStorageDir(directory: string, storageDir: string): string {
+  if (path.isAbsolute(storageDir)) return storageDir;
+  return path.resolve(directory, storageDir);
+}
+
+export function tmpPathFor(dir: string, sessionId: string): string {
+  return path.join(
+    dir,
+    `.${sanitizeId(sessionId)}.${process.pid}.${Date.now()}.tmp`,
+  );
+}
+
+export const _internal = {
+  parseFrontmatter,
+  serialize,
+  os,
+};

package/src/tools/intent-context.ts

@@ -0,0 +1,59 @@
+import { z } from "zod";
+import { tool } from "@opencode-ai/plugin";
+import { loadDigest, resolveStorageDir } from "../store.ts";
+import type { CastlegateConfig } from "../config.ts";
+
+export function createIntentContextTool(getCfg: () => CastlegateConfig) {
+  return tool({
+    description:
+      "Return the current castlegate intent digest for this session. Use this to inspect what the auto-approve guardrail currently believes the session's intent is.",
+    args: {
+      format: z.enum(["summary", "raw"]).default("summary"),
+    },
+    async execute(args, context) {
+      const cfg = getCfg();
+      const dir = resolveStorageDir(context.directory, cfg.storage.directory);
+      const file = await loadDigest(dir, context.sessionID);
+
+      if (!file) {
+        const out = "(no intent digest yet for this session)";
+        return { title: "castlegate intent_context", output: out, metadata: { exists: false } };
+      }
+
+      if (args.format === "raw") {
+        return {
+          title: "castlegate intent_context",
+          output: `# castlegate intent digest\n\n${file.body}`,
+          metadata: {
+            version: file.header.digestVersion,
+            lastMessageId: file.header.lastMessageId,
+            updatedAt: file.header.updatedAt,
+            charCount: file.header.charCount,
+          },
+        };
+      }
+
+      const out = [
+        `# castlegate intent digest`,
+        ``,
+        `Version: ${file.header.digestVersion}`,
+        `Updated: ${file.header.updatedAt}`,
+        `Chars:   ${file.header.charCount}`,
+        `LastMsg: ${file.header.lastMessageId ?? "(none)"}`,
+        ``,
+        file.body,
+      ].join("\n");
+
+      return {
+        title: "castlegate intent_context",
+        output: out,
+        metadata: {
+          version: file.header.digestVersion,
+          lastMessageId: file.header.lastMessageId,
+          updatedAt: file.header.updatedAt,
+          charCount: file.header.charCount,
+        },
+      };
+    },
+  });
+}

package/src/validate.ts

@@ -0,0 +1,151 @@
+import { createHash } from "node:crypto";
+import type { PluginInput } from "@opencode-ai/plugin";
+import type { CastlegateConfig } from "./config.ts";
+import {
+  buildIntentValidatePrompt,
+  parseIntentValidateResponse,
+  summarizeArgs,
+  type IntentValidateResult,
+} from "./prompts/intent-validate.ts";
+import { buildSidecarPromptBody } from "./prompt-body.ts";
+
+type PluginClient = PluginInput["client"];
+
+export interface ValidateToolCallArgs {
+  client: PluginClient;
+  cfg: CastlegateConfig;
+  digest: string;
+  digestVersion: number;
+  tool: string;
+  callArgs: unknown;
+  sidecar: { id: string | null; pending: Promise<string> | null };
+}
+
+export interface ValidatorDecision {
+  result: IntentValidateResult;
+  cached: boolean;
+}
+
+interface CacheEntry {
+  result: IntentValidateResult;
+  expiresAt: number;
+}
+
+const cacheState = new Map<string, CacheEntry>();
+
+function cacheKey(tool: string, args: unknown, digestVersion: number): string {
+  const argsStr = (() => {
+    try {
+      return JSON.stringify(args);
+    } catch {
+      return String(args);
+    }
+  })();
+  return createHash("sha256")
+    .update(tool)
+    .update("\u0000")
+    .update(argsStr)
+    .update("\u0000")
+    .update(String(digestVersion))
+    .digest("hex");
+}
+
+function cacheGet(key: string, ttlMs: number): IntentValidateResult | null {
+  if (ttlMs <= 0) return null;
+  const entry = cacheState.get(key);
+  if (!entry) return null;
+  if (entry.expiresAt < Date.now()) {
+    cacheState.delete(key);
+    return null;
+  }
+  return entry.result;
+}
+
+function cachePut(key: string, result: IntentValidateResult, ttlMs: number): void {
+  if (ttlMs <= 0) return;
+  cacheState.set(key, { result, expiresAt: Date.now() + ttlMs });
+}
+
+export function clearValidatorCache(): void {
+  cacheState.clear();
+}
+
+export function shouldValidate(tool: string, cfg: CastlegateConfig): boolean {
+  if (cfg.validate.skip.includes(tool)) return false;
+  if (cfg.validate.tools && cfg.validate.tools.length > 0) {
+    return cfg.validate.tools.includes(tool);
+  }
+  return true;
+}
+
+async function ensureSidecar(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 validator sidecar session");
+  return created.data.id;
+}
+
+async function getSidecarId(
+  client: PluginClient,
+  sidecar: { id: string | null; pending: Promise<string> | null },
+): Promise<string> {
+  if (sidecar.id) return sidecar.id;
+  if (!sidecar.pending) {
+    sidecar.pending = ensureSidecar(client).then((id) => {
+      sidecar.id = id;
+      return id;
+    });
+  }
+  return sidecar.pending;
+}
+
+async function callValidator(
+  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 ?? [];
+  return parts
+    .map((p: { type?: string; text?: string }) => {
+      if (p.type === "text" && typeof p.text === "string") return p.text;
+      return "";
+    })
+    .filter(Boolean)
+    .join("\n")
+    .trim();
+}
+
+export async function validateToolCall(args: ValidateToolCallArgs): Promise<ValidatorDecision> {
+  const { client, cfg, digest, digestVersion, tool, callArgs, sidecar } = args;
+
+  const key = cacheKey(tool, callArgs, digestVersion);
+  const cached = cacheGet(key, cfg.validate.cacheTtlMs);
+  if (cached) return { result: cached, cached: true };
+
+  const argsSummary = summarizeArgs(tool, callArgs);
+  const prompt = buildIntentValidatePrompt({ digest, tool, argsSummary });
+  const sidecarId = await getSidecarId(client, sidecar);
+  const raw = await callValidator(client, sidecarId, cfg, prompt);
+  const result = parseIntentValidateResponse(raw);
+
+  cachePut(key, result, cfg.validate.cacheTtlMs);
+  return { result, cached: false };
+}
+
+export function fallbackDecision(tool: string, cfg: CastlegateConfig): IntentValidateResult {
+  if (cfg.validate.failOpenOnError) {
+    return { match: true, reason: "validator unavailable (fail-open)", severity: "low" };
+  }
+  return {
+    match: false,
+    reason: "validator unavailable (fail-closed)",
+    severity: tool === "bash" ? "high" : "medium",
+  };
+}