@inetafrica/open-claudia 2.14.8 → 3.0.0

package/core/recall-filter.js

@@ -1,18 +1,16 @@
-// LLM relevance gate over keyword recall candidates. The FTS matchers in
-// packs.js/entities.js are high-recall but dumb — "zoom" pulls in the
-// video-gen pack, "kazee" pulls in every colleague. When keywords produce
-// candidates, a cheap model judges which are genuinely about the message.
-// Fail-open: any error, timeout, or unparseable reply keeps all candidates,
-// so recall never gets worse than the keyword baseline.
+"use strict";
 
-const { spawnSubagent } = require("./subagent");
+// LLM relevance gate over keyword recall candidates. Fail-open is deliberate:
+// an unavailable provider, timeout, or malformed judgement retains the
+// keyword baseline, so intelligence failure never makes classic recall worse.
 
-const FILTER_MODEL = process.env.RECALL_FILTER_MODEL || "haiku";
 const FILTER_TIMEOUT_MS = Number(process.env.RECALL_FILTER_TIMEOUT_MS || 20000);
 const MESSAGE_CLIP_CHARS = 1500;
-// Quote + a window of recent turns: roomier than the message clip so the
-// newest history lines at the tail don't get sliced off.
 const CONTEXT_CLIP_CHARS = 3500;
+const FILTER_OUTPUT_SCHEMA = Object.freeze({
+  type: "array",
+  items: { type: "string" },
+});
 
 function enabled() {
   return (process.env.RECALL_FILTER || "on").toLowerCase() !== "off";
@@ -23,57 +21,84 @@ const FILTER_SYSTEM_PROMPT = [
   "Reply with ONLY a JSON array of candidate ids — no prose, no markdown fences.",
 ].join("\n");
 
-// candidates: [{ id, name, description }]. opts.context: surrounding
-// conversation text (the message the user replied to and/or the last
-// few chat turns) used to disambiguate pronouns and terse follow-ups
-// like "push" or "the app" — context only, not a topic source in its
-// own right. Returns a Set of kept ids, or null to signal fail-open
-// (caller decides what that keeps).
-async function judgeRelevance(message, candidates, opts = {}) {
-  if (!enabled() || candidates.length === 0) return null;
-  const msg = String(message || "").slice(0, MESSAGE_CLIP_CHARS);
-  const context = String(opts.context || "").slice(0, CONTEXT_CLIP_CHARS);
-  const lines = candidates.map((c) => `- ${c.id}: ${c.name}${c.description ? ` — ${c.description}` : ""}`);
-  const prompt = [
-    "A user sent this message to their assistant:",
-    "<<<",
-    msg,
-    ">>>",
-    ...(context
-      ? [
-          "",
-          "Surrounding conversation (the message it replied to and/or the most recent turns in this chat — context for resolving references like \"the app\", \"it\", or terse follow-ups like \"push\"; judge relevance against what the user's message is about in light of it):",
-          "<<<",
-          context,
-          ">>>",
-        ]
-      : []),
-    "",
-    "These stored memory notes were keyword-matched as possibly relevant.",
-    "Keep only the ones the message is GENUINELY about — the topic, project, or person itself.",
-    "Sharing an incidental word with the note (e.g. \"zoom\" matching a video tool, a person's employer matching a project name) is NOT relevance.",
-    "If the conversation context shows the user means a different project than a candidate (e.g. they are discussing app A, and a candidate is the unrelated app B that merely shares words like \"mobile\" or \"gradient\"), drop that candidate.",
-    "",
-    "Candidates:",
-    ...lines,
-    "",
-    `Reply with ONLY a JSON array of the relevant ids, e.g. ["${candidates[0].id}"]. Use [] if none are relevant.`,
-  ].join("\n");
-  try {
-    const { text } = await spawnSubagent(prompt, {
-      model: FILTER_MODEL,
-      systemPrompt: FILTER_SYSTEM_PROMPT,
-      timeoutMs: FILTER_TIMEOUT_MS,
-    });
-    const match = String(text || "").match(/\[[\s\S]*?\]/);
-    if (!match) return null;
-    const ids = JSON.parse(match[0]);
-    if (!Array.isArray(ids)) return null;
-    const known = new Set(candidates.map((c) => c.id));
-    return new Set(ids.filter((id) => typeof id === "string" && known.has(id)));
-  } catch (e) {
-    return null;
+function parseIds(result) {
+  if (Array.isArray(result?.json)) return result.json;
+  const match = String(result?.text || "").match(/\[[\s\S]*?\]/);
+  if (!match) return null;
+  const parsed = JSON.parse(match[0]);
+  return Array.isArray(parsed) ? parsed : null;
+}
+
+function createRecallFilter(dependencies = {}) {
+  const runUtility = dependencies.spawnUtilityAgent || require("./utility-agent").spawnUtilityAgent;
+
+  async function judgeRelevance(message, candidates, opts = {}) {
+    if (!enabled() || candidates.length === 0) return null;
+    const msg = String(message || "").slice(0, MESSAGE_CLIP_CHARS);
+    const context = String(opts.context || "").slice(0, CONTEXT_CLIP_CHARS);
+    const lines = candidates.map((candidate) => (
+      `- ${candidate.id}: ${candidate.name}${candidate.description ? ` — ${candidate.description}` : ""}`
+    ));
+    const prompt = [
+      "A user sent this message to their assistant:",
+      "<<<",
+      msg,
+      ">>>",
+      ...(context
+        ? [
+            "",
+            "Surrounding conversation (the message it replied to and/or the most recent turns in this chat — context for resolving references like \"the app\", \"it\", or terse follow-ups like \"push\"; judge relevance against what the user's message is about in light of it):",
+            "<<<",
+            context,
+            ">>>",
+          ]
+        : []),
+      "",
+      "These stored memory notes were keyword-matched as possibly relevant.",
+      "Keep only the ones the message is GENUINELY about — the topic, project, or person itself.",
+      "Sharing an incidental word with the note (e.g. \"zoom\" matching a video tool, a person's employer matching a project name) is NOT relevance.",
+      "If the conversation context shows the user means a different project than a candidate (e.g. they are discussing app A, and a candidate is the unrelated app B that merely shares words like \"mobile\" or \"gradient\"), drop that candidate.",
+      "",
+      "Candidates:",
+      ...lines,
+      "",
+      `Reply with ONLY a JSON array of the relevant ids, e.g. ["${candidates[0].id}"]. Use [] if none are relevant.`,
+    ].join("\n");
+    try {
+      const result = await runUtility(prompt, {
+        purpose: "recall",
+        activeProvider: opts.provider || null,
+        tier: "low",
+        model: opts.model || null,
+        modelEnvPrefix: "RECALL_FILTER_MODEL",
+        legacyClaudeModelEnv: "RECALL_FILTER_MODEL",
+        systemPrompt: FILTER_SYSTEM_PROMPT,
+        readOnly: true,
+        outputSchema: FILTER_OUTPUT_SCHEMA,
+        timeoutMs: FILTER_TIMEOUT_MS,
+        cwd: opts.cwd || process.cwd(),
+      });
+      const ids = parseIds(result);
+      if (!ids) return null;
+      const known = new Set(candidates.map((candidate) => candidate.id));
+      return new Set(ids.filter((id) => typeof id === "string" && known.has(id)));
+    } catch (_) {
+      return null;
+    }
   }
+
+  return { judgeRelevance };
 }
 
-module.exports = { judgeRelevance };
+const defaultFilter = createRecallFilter();
+
+module.exports = {
+  CONTEXT_CLIP_CHARS,
+  FILTER_OUTPUT_SCHEMA,
+  FILTER_SYSTEM_PROMPT,
+  FILTER_TIMEOUT_MS,
+  MESSAGE_CLIP_CHARS,
+  createRecallFilter,
+  enabled,
+  judgeRelevance: defaultFilter.judgeRelevance,
+};

package/core/router.js

@@ -11,7 +11,7 @@ const { isChatAuthorized } = require("./access");
 const introFlow = require("./intro-flow");
 const { send, deleteMessage } = require("./io");
 const { currentState, autoLinkOwnerChannel } = require("./state");
-const { runClaude } = require("./runner");
+const { admitRunContext, runAgent } = require("./runner");
 const { transcribeAudio } = require("./media");
 const { vault } = require("./vault-store");
 const { isOnboarded, handleOnboarding } = require("./onboarding");
@@ -26,6 +26,21 @@ const { MAX_FILE_SIZE, MAX_VOICE_SIZE, FILES_DIR } = require("./config");
 const channelWizard = require("./channel-wizard");
 require("./handlers"); // side-effect: register slash commands
 
+const USER_VISIBLE_PROVIDER_ERRORS = new Set([
+  "NO_AVAILABLE_PROVIDER",
+  "PROVIDER_UNAVAILABLE",
+  "PROVIDER_INCOMPATIBLE",
+  "PROVIDER_UNAUTHENTICATED",
+]);
+
+async function deliverRouterError(error) {
+  const code = error?.code || "ROUTER_ERROR";
+  if (!USER_VISIBLE_PROVIDER_ERRORS.has(code)) return null;
+  const message = error?.message || "No compatible provider is available.";
+  await send(`${message}\n\nOpen /backend to review providers, or run /doctor for local compatibility and authentication checks.`);
+  return { ok: false, status: "failed", error: { code, message } };
+}
+
 // Cross-channel dedup. Message ids are unique per adapter, not globally, so
 // the adapter stays in the key. Keying by canonical (not raw channelId) means
 // a message redelivered against a different channel that resolves to the same
@@ -109,6 +124,8 @@ async function onMessage(envelope) {
       if (envelope.type === "text") return handleText(envelope);
     } catch (e) {
       console.error("router:onMessage:", e.message);
+      const delivered = await deliverRouterError(e);
+      if (delivered) return delivered;
     }
   });
 }
@@ -133,6 +150,10 @@ async function handleVoice(envelope) {
     if (media.size && media.size > MAX_VOICE_SIZE) {
       return send(`Voice note too large (${Math.round(media.size / 1024 / 1024)}MB). Max: ${MAX_VOICE_SIZE / 1024 / 1024}MB`);
     }
+    const runContext = admitRunContext("", state.currentSession.dir, envelope.messageId, {
+      purpose: "foreground",
+      attachments: [{ type: "voice", mimeType: media.mimeType || "audio/ogg", fileName: media.fileName || null }],
+    });
     envelope.adapter.typing(envelope.channelId).catch(() => {});
     const tStart = Date.now();
     const oggPath = await envelope.adapter.downloadMedia(media);
@@ -145,7 +166,12 @@ async function handleVoice(envelope) {
     state.lastInputWasVoice = true;
     // Per-stage latency for the voice pipeline; the runner fills in the rest.
     state.voiceLat = { startAt: tStart, downloadMs: tAfterDownload - tStart, sttMs: tAfterStt - tAfterDownload };
-    await runClaude(transcript, state.currentSession.dir, envelope.messageId);
+    return runAgent(transcript, runContext.cwd, envelope.messageId, {
+      runContext,
+      attachments: [{ type: "voice", path: oggPath, mimeType: media.mimeType || "audio/ogg", fileName: media.fileName || null }],
+      lastInputWasVoice: true,
+      voiceStream: envelope.adapter?.type === "voice",
+    });
   } catch (err) { await send(`Voice failed: ${err.message}`); }
 }
 
@@ -156,13 +182,20 @@ async function handleAudio(envelope) {
   try {
     const media = envelope.media?.[0];
     if (!media) return;
+    const runContext = admitRunContext("", state.currentSession.dir, envelope.messageId, {
+      purpose: "foreground",
+      attachments: [{ type: "audio", mimeType: media.mimeType || null, fileName: media.fileName || null }],
+    });
     envelope.adapter.typing(envelope.channelId).catch(() => {});
     const p = await envelope.adapter.downloadMedia(media);
     const t = transcribeAudio(p);
     try { fs.unlinkSync(p); } catch (e) {}
     if (!t) return send("Couldn't transcribe.");
     await send(`Heard: "${t}"`, { replyTo: envelope.messageId });
-    await runClaude(t, state.currentSession.dir, envelope.messageId);
+    return runAgent(t, runContext.cwd, envelope.messageId, {
+      runContext,
+      attachments: [{ type: "audio", path: p, mimeType: media.mimeType || null, fileName: media.fileName || null }],
+    });
   } catch (err) { await send(`Audio failed: ${err.message}`); }
 }
 
@@ -173,13 +206,26 @@ async function handlePhoto(envelope) {
   try {
     const items = envelope.media || [];
     if (!items.length) return;
+    const runContext = admitRunContext(envelope.caption || "", state.currentSession.dir, envelope.messageId, {
+      purpose: "foreground",
+      attachments: items.map((item) => ({ type: "image", mimeType: item.mimeType || "image/*", fileName: item.fileName || null })),
+    });
     const paths = [];
     for (const m of items) paths.push(await envelope.adapter.downloadMedia(m));
     const caption = envelope.caption || "Describe this image. If code/UI/error — explain and fix.";
     const prompt = paths.length === 1
       ? `Image at ${paths[0]}\n\nView it, then: ${caption}`
       : `Images:\n${paths.map((p, i) => `${i + 1}. ${p}`).join("\n")}\n\nView all ${paths.length}, then: ${caption}`;
-    await runClaude(prompt, state.currentSession.dir, envelope.messageId);
+    return runAgent(prompt, runContext.cwd, envelope.messageId, {
+      runContext,
+      imagePaths: paths,
+      attachments: paths.map((imagePath, index) => ({
+        type: "image",
+        path: imagePath,
+        mimeType: items[index]?.mimeType || "image/*",
+        fileName: items[index]?.fileName || path.basename(imagePath),
+      })),
+    });
   } catch (err) { await send(`Image failed: ${err.message}`); }
 }
 
@@ -193,6 +239,10 @@ async function handleDocument(envelope) {
     if (media.size && media.size > MAX_FILE_SIZE) {
       return send(`File too large (${Math.round(media.size / 1024 / 1024)}MB). Max: ${MAX_FILE_SIZE / 1024 / 1024}MB`);
     }
+    const runContext = admitRunContext(envelope.caption || "", state.currentSession.dir, envelope.messageId, {
+      purpose: "foreground",
+      attachments: [{ type: "document", mimeType: media.mimeType || null, fileName: media.fileName || null }],
+    });
     const savePath = await envelope.adapter.downloadMedia(media);
     const fileName = media.fileName || path.basename(savePath);
     const mime = media.mimeType || "";
@@ -202,7 +252,11 @@ async function handleDocument(envelope) {
       ? `Image file saved at ${savePath}\n\nView it, then: ${caption || "Describe this image. If code/UI/error — explain and fix."}`
       : `File received: ${fileName} (${mime})\nSaved at: ${savePath}\n\nRead this file and ${caption || "summarize its contents. If it's code, explain what it does. If it's a document, give key points."}`;
     await send(`File saved: ${fileName}`, { replyTo: envelope.messageId });
-    await runClaude(prompt, state.currentSession.dir, envelope.messageId);
+    return runAgent(prompt, runContext.cwd, envelope.messageId, {
+      runContext,
+      imagePaths: isImage ? [savePath] : [],
+      attachments: [{ type: isImage ? "image" : "document", path: savePath, mimeType: mime, fileName }],
+    });
   } catch (err) { await send(`Failed: ${err.message}`); }
 }
 
@@ -339,6 +393,9 @@ async function handleText(envelope) {
   }
 
   const text = envelope.text || "";
+  const runContext = admitRunContext(text, state.currentSession.dir, envelope.messageId, { purpose: "foreground" });
+  const attachments = [];
+  const imagePaths = [];
   const credPatterns = [
     /^(sk-ant-|sk-|glpat-|ghp_|gho_|github_pat_|xoxb-|xoxp-|AKIA|AIza)/,
     /^[A-Za-z0-9_-]{20,}$/,
@@ -358,6 +415,9 @@ async function handleText(envelope) {
       const fileName = reply.document.file_name || reply.document.fileName || "unknown";
       const filePath = path.join(FILES_DIR, fileName);
       if (fs.existsSync(filePath)) {
+        const mimeType = reply.document.mime_type || reply.document.mimeType || null;
+        attachments.push({ type: mimeType?.startsWith("image/") ? "image" : "document", path: filePath, fileName, mimeType });
+        if (mimeType?.startsWith("image/")) imagePaths.push(filePath);
         ctx += (ctx ? "\n" : "") + `[Attached file: ${fileName} at ${filePath}]`;
       } else if (reply.document.file_id) {
         // Attempt to fetch via adapter so this works on every channel.
@@ -368,6 +428,14 @@ async function handleText(envelope) {
             fileName,
             mimeType: reply.document.mime_type,
           });
+          const mimeType = reply.document.mime_type || reply.document.mimeType || null;
+          attachments.push({
+            type: mimeType?.startsWith("image/") ? "image" : "document",
+            path: localPath,
+            fileName,
+            mimeType,
+          });
+          if (mimeType?.startsWith("image/")) imagePaths.push(localPath);
           ctx += (ctx ? "\n" : "") + `[Attached file: ${fileName} at ${localPath}]`;
         } catch (e) {
           ctx += (ctx ? "\n" : "") + `[Attached file: ${fileName} — could not download]`;
@@ -383,7 +451,11 @@ async function handleText(envelope) {
     }
   }
 
-  await runClaude(prompt, state.currentSession.dir, envelope.messageId);
+  return runAgent(prompt, runContext.cwd, envelope.messageId, {
+    runContext,
+    imagePaths,
+    attachments,
+  });
 }
 
-module.exports = { onMessage, onAction };
+module.exports = { onMessage, onAction, deliverRouterError };

package/core/run-context.js

@@ -0,0 +1,185 @@
+"use strict";
+
+const crypto = require("crypto");
+const path = require("path");
+
+function cloneSerializable(value, label = "run context value") {
+  if (value === undefined) return undefined;
+  try {
+    return structuredClone(value);
+  } catch (error) {
+    const wrapped = new TypeError(`${label} must be serializable`);
+    wrapped.code = "INVALID_RUN_CONTEXT";
+    wrapped.cause = error;
+    throw wrapped;
+  }
+}
+
+function deepFreeze(value, seen = new Set()) {
+  if (!value || typeof value !== "object" || Object.isFrozen(value) || seen.has(value)) return value;
+  seen.add(value);
+  for (const child of Object.values(value)) deepFreeze(child, seen);
+  return Object.freeze(value);
+}
+
+function projectSnapshot(state, cwd, requestedProject) {
+  const value = requestedProject !== undefined ? requestedProject : state.currentSession;
+  if (value && typeof value === "object") {
+    const dir = value.dir || value.path || cwd || null;
+    return {
+      name: value.name || (dir ? path.basename(dir) : null),
+      dir,
+    };
+  }
+  if (typeof value === "string" && value) {
+    return { name: value, dir: cwd || null };
+  }
+  const dir = cwd || null;
+  return { name: dir ? path.basename(dir) : null, dir };
+}
+
+function serializableOrigin(origin, fallback = {}) {
+  const source = origin || fallback || {};
+  return {
+    adapterId: source.adapterId || source.adapter?.id || null,
+    transport: source.transport || source.adapter?.type || null,
+    channelId: source.channelId != null ? String(source.channelId) : null,
+    userId: source.userId != null ? String(source.userId) : null,
+    canonicalUserId: source.canonicalUserId || null,
+  };
+}
+
+function captureRunContext({
+  state,
+  store = null,
+  prompt = "",
+  cwd = null,
+  replyToMsgId = null,
+  opts = {},
+  channelId = null,
+  canonicalUserId = null,
+  runId = null,
+  now = Date.now(),
+} = {}) {
+  if (!state || typeof state !== "object") {
+    const error = new TypeError("state is required to capture a run context");
+    error.code = "INVALID_RUN_CONTEXT";
+    throw error;
+  }
+  if (typeof prompt !== "string") {
+    const error = new TypeError("prompt must be a string");
+    error.code = "INVALID_RUN_CONTEXT";
+    throw error;
+  }
+
+  const provider = String(opts.provider || state.settings?.backend || "").trim().toLowerCase();
+  if (provider === "cursor") {
+    const error = new Error("Cursor Agent support has been removed; choose Claude Code or OpenAI Codex");
+    error.code = "REMOVED_PROVIDER";
+    throw error;
+  }
+  if (!new Set(["claude", "codex"]).has(provider)) {
+    const error = new Error("Choose Claude Code or OpenAI Codex before starting a model turn");
+    error.code = "NO_AVAILABLE_PROVIDER";
+    throw error;
+  }
+  const project = projectSnapshot(state, cwd, opts.project);
+  const activeSessionId = state.activeSessions?.[project.name]?.[provider] || null;
+  const admittedSessionId = opts.fresh
+    ? null
+    : (opts.resumeSessionId || activeSessionId || null);
+  const origin = serializableOrigin(opts.origin, store || {});
+  const resolvedChannelId = channelId != null
+    ? String(channelId)
+    : (origin.channelId || (state.channelId != null ? String(state.channelId) : null));
+  const providerSettings = cloneSerializable({
+    ...(state.providerSettings?.[provider] || state.settings || {}),
+    ...(opts.providerSettings || {}),
+  }, "provider settings");
+  delete providerSettings.backend;
+
+  const context = {
+    runId: runId || (typeof crypto.randomUUID === "function"
+      ? crypto.randomUUID()
+      : `run-${now}-${Math.random().toString(36).slice(2, 10)}`),
+    admittedAt: now,
+    canonicalUserId: canonicalUserId || state.userId || origin.canonicalUserId || null,
+    project,
+    provider,
+    providerSettings,
+    sessionId: admittedSessionId,
+    admittedSessionId,
+    previousSessionId: activeSessionId,
+    purpose: opts.purpose || (opts.label ? String(opts.label) : "foreground"),
+    channelId: resolvedChannelId,
+    origin,
+    cwd: cwd || project.dir || null,
+    replyToMsgId: replyToMsgId == null ? null : String(replyToMsgId),
+    userPrompt: prompt,
+    fresh: !!opts.fresh,
+    continueSession: !!opts.continueSession,
+    resumeSessionId: opts.resumeSessionId || null,
+    skipAutoCompact: !!opts.skipAutoCompact,
+    timeoutMs: Number.isFinite(opts.timeoutMs) ? opts.timeoutMs : null,
+    maxTurns: Number.isFinite(opts.maxTurns) ? opts.maxTurns : null,
+    imagePaths: cloneSerializable(opts.imagePaths || opts.images || [], "image paths"),
+    attachments: cloneSerializable(opts.attachments || [], "attachments"),
+    lastInputWasVoice: !!state.lastInputWasVoice,
+    voiceStream: !!opts.voiceStream || (!!state.lastInputWasVoice && origin.transport === "voice"),
+    readOnly: opts.readOnly === true,
+    permissionMode: opts.permissionMode || null,
+    transcriptRole: opts.transcriptRole || null,
+    label: opts.label || null,
+    toolHookSettings: opts.toolHookSettings || null,
+    allowReadOnlyWithoutToolHook: opts.allowReadOnlyWithoutToolHook === true,
+    requiredDelivery: opts.requiredDelivery !== false,
+    attachSession: opts.attachSession !== false,
+    occurrenceId: opts.occurrenceId || null,
+    scheduledJobId: opts.scheduledJobId || null,
+    originRunId: opts.originRunId || null,
+  };
+
+  return deepFreeze(context);
+}
+
+function sameCapturedProject(state, runContext) {
+  const live = state?.currentSession;
+  const captured = runContext?.project;
+  if (!live || !captured) return !live && !captured;
+  return String(live.name || "") === String(captured.name || "")
+    && String(live.dir || live.path || "") === String(captured.dir || captured.path || "");
+}
+
+function bindRunInputs(runContext, inputs = {}) {
+  if (!runContext || typeof runContext !== "object") {
+    const error = new TypeError("captured run context is required");
+    error.code = "INVALID_RUN_CONTEXT";
+    throw error;
+  }
+  const next = {
+    ...runContext,
+    userPrompt: inputs.userPrompt !== undefined ? String(inputs.userPrompt) : runContext.userPrompt,
+    imagePaths: cloneSerializable(
+      inputs.imagePaths !== undefined ? inputs.imagePaths : runContext.imagePaths,
+      "image paths",
+    ),
+    attachments: cloneSerializable(
+      inputs.attachments !== undefined ? inputs.attachments : runContext.attachments,
+      "attachments",
+    ),
+    lastInputWasVoice: inputs.lastInputWasVoice !== undefined
+      ? !!inputs.lastInputWasVoice
+      : runContext.lastInputWasVoice,
+    voiceStream: inputs.voiceStream !== undefined ? !!inputs.voiceStream : runContext.voiceStream,
+  };
+  return deepFreeze(next);
+}
+
+module.exports = {
+  captureRunContext,
+  bindRunInputs,
+  cloneSerializable,
+  deepFreeze,
+  sameCapturedProject,
+  serializableOrigin,
+};