synabun 2.0.0 → 2.0.7

package/mcp-server/src/services/codex-config-heal.ts

@@ -7,8 +7,9 @@
  * Having both forms defines the same TOML key twice, so Codex rejects the
  * configuration and starts with defaults.
  *
- * This module deliberately edits only the SynaBun MCP tables. All unrelated
- * Codex configuration is left byte-for-byte intact. File writes are atomic,
+ * This module edits the SynaBun MCP tables and the known ignored feature keys
+ * emitted by its old Settings writer. All unrelated configuration is left
+ * byte-for-byte intact. Repairs keep a backup; file writes are atomic,
  * preserve the original mode, and are idempotent.
  */
 import {
@@ -56,6 +57,7 @@ export interface CodexMcpDefinition {
 }
 
 export type HealReason =
+  | 'removed_ignored_settings'
   | 'removed_duplicate_inline_env'
   | 'normalized_inline_env'
   | 'removed_managed_profile_override'
@@ -364,15 +366,20 @@ export function healCodexConfig(configPath: string): HealResult {
   }
 
   const before = inspectCodexConfigContent(content);
-  if (!before.connected && !before.issues.length) {
+  const cleaned = removeIgnoredCodexSettings(content);
+  if (cleaned === content && !before.connected && !before.issues.length) {
     return { healed: false, reason: 'no_synabun_section' };
   }
-  const repaired = repairCodexConfigContent(content);
+  const repaired = repairCodexConfigContent(cleaned);
+  if (cleaned !== content) repaired.reason = 'removed_ignored_settings';
   if (!repaired.reason || repaired.content === content) {
     return { healed: false, reason: 'no_duplicate', inspection: before };
   }
 
   try {
+    // Keep the exact original, including unrelated tables and its permissions.
+    const backup = `${configPath}.synabun-backup-${Date.now()}-${process.pid}`;
+    copyFileSync(configPath, backup);
     atomicWrite(configPath, repaired.content);
   } catch (err) {
     return { healed: false, reason: 'write_error', error: err instanceof Error ? err.message : String(err) };
@@ -384,6 +391,30 @@ export function healCodexConfig(configPath: string): HealResult {
   };
 }
 
+/** Narrow repair for keys emitted by the old Settings writer. These literal
+ * dotted keys are ignored by Codex; personality's feature flag is removed.
+ * Do not sweep arbitrary user flags or normalize unrelated TOML. */
+export function removeIgnoredCodexSettings(content: string): string {
+  let section = '';
+  let multiline: string | null = null;
+  return content.split(/(?<=\n)/).filter(line => {
+    // Avoid treating text inside TOML multiline strings as configuration.
+    const delimiters = line.match(/"""|'''/g) || [];
+    if (multiline) {
+      if (delimiters.filter(d => d === multiline).length % 2) multiline = null;
+      return true;
+    }
+    for (const delimiter of delimiters) if (delimiters.filter(d => d === delimiter).length % 2) multiline = delimiter;
+    const header = /^\s*\[([^\]]+)\]\s*(?:#.*)?$/.exec(line.trim());
+    if (header) section = header[1].replace(/["']/g, '').trim();
+    else if (/^\s*\[/.test(line)) section = '__other_table__';
+    if (!section && /^\s*["']features\.(?:personality|fast_mode|apps|unified_exec)["']\s*=\s*(?:true|false)\s*(?:#.*)?$/.test(line.trim())) return false;
+    if ((!section && /^\s*features\.personality\s*=\s*(?:true|false)\s*(?:#.*)?$/.test(line.trim()))
+      || (section === 'features' && /^\s*(?:personality|"personality"|'personality')\s*=\s*(?:true|false)\s*(?:#.*)?$/.test(line.trim()))) return false;
+    return true;
+  }).join('');
+}
+
 export function upsertCodexMcpConfig(configPath: string, definition: CodexMcpDefinition): CodexConfigInspection {
   let content = '';
   if (existsSync(configPath)) content = readFileSync(configPath, 'utf-8');

package/mcp-server/src/services/identity.ts

@@ -173,6 +173,33 @@ export function callerDesktopGrant(): string | null {
   return sanitizeDesktopGrant(process.env.SYNABUN_DESKTOP_GRANT);
 }
 
+/** WhatsApp brain credentials look exactly like the ones the Neural Interface mints (assistant-runtime.js mintBrainCredential). */
+export function sanitizeBrainCredential(v: string | undefined | null): string | null {
+  return typeof v === 'string' && /^sbb_[A-Za-z0-9_-]{43}$/.test(v.trim()) ? v.trim() : null;
+}
+
+// The brain credential of the request being handled (whatsapp_send_file). Its own context per HTTP
+// request, never a field of the CallerIdentity: identities are shared by every request that names the
+// same X-Synabun-Terminal pin (not a secret), so a credential kept there could be read by a concurrent
+// request that only forged the pin.
+const credentialAls = new AsyncLocalStorage<string | null>();
+
+/** Run `fn` with this request's brain credential (http.ts, around every transport.handleRequest). */
+export function runWithBrainCredential<T>(credential: string | null, fn: () => T): T {
+  return credentialAls.run(credential, fn);
+}
+
+/**
+ * The WhatsApp brain credential of the current caller (whatsapp_send_file sends it on its one request
+ * and nowhere else): the request's own header over HTTP (X-Synabun-Brain-Token, the Claude brain),
+ * SYNABUN_BRAIN_TOKEN for stdio children (the Codex and OpenCode brains). Never the host process's
+ * env for an HTTP caller.
+ */
+export function callerBrainCredential(): string | null {
+  if (httpMode) return credentialAls.getStore() ?? null;
+  return sanitizeBrainCredential(process.env.SYNABUN_BRAIN_TOKEN);
+}
+
 /**
  * Role of the current caller: the ALS identity's role over HTTP (derived from
  * X-Synabun-Role on every request), or SYNABUN_ROLE for stdio children —

package/mcp-server/src/services/neural-interface.ts

@@ -132,7 +132,8 @@ async function requestOnce(
   method: string,
   path: string,
   body?: Record<string, unknown>,
-  timeout = DEFAULT_TIMEOUT
+  timeout = DEFAULT_TIMEOUT,
+  extraHeaders: Record<string, string> = {},
 ): Promise<NiResponse> {
   const cancellation = browserCancellation.getStore();
   const callerSignal = cancellation?.signal;
@@ -166,6 +167,8 @@ async function requestOnce(
     headers['X-Synabun-Deadline'] = String(deadline);
     // Lets the server refuse advisory payloads and auto-heal for a batch step on its own authority.
     if (batchContext.getStore()) headers['X-Synabun-Batch'] = '1';
+    // One request's own headers (whatsappSendFile's brain credential): never sent on any other request.
+    for (const [name, value] of Object.entries(extraHeaders)) if (value) headers[name] = value;
     const opts: RequestInit = {
       method,
       headers,
@@ -199,7 +202,9 @@ async function requestOnce(
     if (controller.signal.aborted || /abort/i.test(msg)) {
       return { error: `Request timed out after ${timeout}ms; outcome may be uncertain. Inspect the page before retrying.`, code: 'REQUEST_TIMEOUT', outcome: 'uncertain' };
     }
-    return { error: `Neural Interface unreachable: ${msg}. Is the Neural Interface server running?`, code: 'TRANSPORT_ERROR', outcome: 'uncertain' };
+    // The system's own code for it (fetch puts it on `cause`): ECONNREFUSED means the request never left.
+    const cause = (err as { cause?: { code?: unknown }; code?: unknown } | null)?.cause?.code ?? (err as { code?: unknown } | null)?.code ?? /\b(E[A-Z_]{3,})\b/.exec(msg)?.[1];
+    return { error: `Neural Interface unreachable: ${msg}. Is the Neural Interface server running?`, code: 'TRANSPORT_ERROR', outcome: 'uncertain', ...(typeof cause === 'string' ? { transportCode: cause } : {}) };
   } finally {
     clearTimeout(timer);
     callerSignal?.removeEventListener('abort', cancel);
@@ -1486,3 +1491,30 @@ export async function assistantKillAll(body: { assistantSessionId?: string; work
 export async function assistantFocus(runId: string, focus: boolean): Promise<NiResponse> {
   return request('POST', assistantRunPath(runId, '/focus'), { focus });
 }
+
+// whatsapp_send_file: the server's own deadline for the send is 120 s (lib/whatsapp/manager.js); this
+// one outlives it so a server timeout is reported as the server's.
+const WHATSAPP_SEND_FILE_TIMEOUT = 130_000;
+export const WHATSAPP_SEND_FILE_UNCERTAIN = 'SynaBun did not answer in time: the file may or may not have arrived. Do not send it again unless the user asks.';
+export const WHATSAPP_SEND_FILE_LOST = 'SynaBun\'s answer was lost: the file may or may not have arrived. Do not send it again unless the user asks.';
+// The request never reached SynaBun (nothing listens, no route to it): nothing was sent, for certain.
+const WHATSAPP_SEND_FILE_NEVER_LEFT = new Set(['ECONNREFUSED', 'ENOTFOUND', 'EAI_AGAIN', 'EHOSTUNREACH', 'ENETUNREACH', 'EADDRNOTAVAIL']);
+
+/**
+ * whatsapp_send_file → POST /api/assistant/whatsapp/send-file: exactly one request (requestOnce, no
+ * retry of any kind), because a timeout may come after WhatsApp took the file. `credential` (the
+ * WhatsApp brain's own, identity.ts callerBrainCredential) rides on this request alone; without it
+ * the server refuses (403).
+ */
+export async function whatsappSendFile(body: { path: string; caption?: string; as?: string }, credential: string | null): Promise<NiResponse> {
+  const result = await requestOnce('POST', '/api/assistant/whatsapp/send-file', body as Record<string, unknown>, WHATSAPP_SEND_FILE_TIMEOUT,
+    credential ? { 'X-Synabun-Brain-Token': credential } : {});
+  if (result.code === 'REQUEST_TIMEOUT') return { ok: false, code: 'TIMEOUT', uncertain: true, error: WHATSAPP_SEND_FILE_UNCERTAIN };
+  // Any other failure of the transport after the request left (a reset socket, an answer that is not JSON) may
+  // come after WhatsApp took the file: as uncertain as a timeout, never "is the server running?".
+  if (result.code === 'TRANSPORT_ERROR') {
+    if (WHATSAPP_SEND_FILE_NEVER_LEFT.has(String(result.transportCode))) return { ok: false, code: 'UNREACHABLE', error: 'SynaBun is not reachable (is it running?): nothing was sent.' };
+    return { ok: false, code: 'TRANSPORT_ERROR', uncertain: true, error: WHATSAPP_SEND_FILE_LOST };
+  }
+  return result;
+}

package/mcp-server/src/services/typesafe-config.ts

@@ -31,7 +31,7 @@ export const SURFACES = [
   'browser-page-state', 'browser-target', 'browser-social',
   'task-boundary', 'session-lookup', 'user-learning', 'claim-check',
   'edit-stale', 'supersession', 'compact-digest', 'plan-conflict',
-  'worker-outcome', 'worker-claim', 'desktop-target',
+  'worker-outcome', 'worker-claim', 'desktop-target', 'budget-split',
 ] as const;
 export type SurfaceName = typeof SURFACES[number];
 
@@ -94,6 +94,7 @@ export const SURFACE_META: Record<SurfaceName, SurfaceMeta> = {
   'worker-outcome': { label: 'Worker outcome', description: 'Assistant workers: reads done / blocked / needs input from a final message that has no ## Result block (instead of spending a retry turn), and what kept a failed or blocked run from finishing (capability, access, needs the user, transient), which decides whether escalation is offered.', fallback: 'one result-retry worker turn; every failed, blocked or result-less run offers a one-tier escalation' },
   'worker-claim': { label: 'Worker claim', description: 'Assistant workers: whether a run reported done while claiming success (tests pass, fixed, verified) that its own command output does not show. Flags the run so the Assistant verifies before reporting; asked only when the turn exposed commands or tool results.', fallback: 'no check', ridesWith: 'worker-outcome' },
   'desktop-target': { label: 'Desktop target', description: 'Computer use: ranks the visible controls of the front window against a computer_ax intent. Advisory; one low-risk press by intent only behind the desktop benchmark gate.', fallback: 'the full accessibility tree, or a word-overlap ranking when an intent is given' },
+  'budget-split': { label: 'Budget split', description: 'Assistant sessions with a budget: how much of the money still to be spent will land on each provider (Claude Code, Codex, OpenCode), asked at the first route and at checkpoints (a share used up, a budget change, a run ending). It only divides what the user allowed: shares never add up to more than is left, and it never picks a model.', fallback: 'weights from the saved routes, the session\'s tasks and live runs, times the list price of the routed models; the brain keeps its reserve either way' },
 };
 
 const SURFACE_DEFAULTS: Record<SurfaceName, SurfaceSettings> = {
@@ -132,6 +133,8 @@ const SURFACE_DEFAULTS: Record<SurfaceName, SurfaceSettings> = {
   // Rider of worker-outcome. Flags a run for verification, so the bar is the claim-check bar.
   'worker-claim': { enabled: true, timeoutMs: 2500, minProbability: 0.9 },
   'desktop-target': { ...DESKTOP_TARGET_DEFAULTS },
+  // On the route path (agent_route waits for the first split), never per tick: one call per checkpoint.
+  'budget-split': { enabled: true, timeoutMs: 2000 },
 };
 
 // --- Config shape ---

package/mcp-server/src/tools/agents.ts

@@ -54,6 +54,7 @@ export const agentRouteSchema = {
     provider: z.enum(PROVIDERS).optional().describe('Worker provider for "dispatch" (ignored for "direct").'),
     model: z.string().max(200).optional().describe('Model id from the routing sheet / agent_catalog. Omit for the provider default (or a remembered route).'),
     effort: z.string().max(40).optional().describe('Reasoning effort for that model, per agent_catalog (e.g. low…max/ultra; OpenCode uses the model\'s variant names). Unsupported values are corrected to the nearest level the model runs.'),
+    account_id: z.string().max(64).optional().describe('Claude Code or Codex account id, or "auto" to choose the signed-in subscription with most usage left. API-key accounts are excluded from Auto. A limited pinned/default account falls back within the provider; corrections explain the selection. Another account runs on a worker when the proposal was direct.'),
     reason: z.string().max(240).optional().describe('Why this model (one short clause, shown on the card).'),
   })).min(1).max(3).describe('1-3 candidate routes, best first. The first is your pick.'),
   independent: z.boolean().optional().describe(
@@ -120,7 +121,7 @@ export const agentDispatchSchema = {
     'SynaBun MCP profile preset for the worker (agent_catalog mcpPresets): "core" for memory-only work, "standard" for coding, a platform preset for browser/social jobs (design runs default to "browser" unless uses_browser is false).'
   ),
   account_id: z.string().max(200).optional().describe(
-    'Account profile id: a Codex account for provider "codex" or a Claude account for provider "claude-code" (ignored for opencode). Omit for the default account.'
+    'Account profile id, or "auto" for the signed-in subscription with most usage left (API keys excluded; limited pinned/default accounts fall back within the provider, with corrections). An approved route binds its resolved account unless it becomes limited before dispatch. A Codex account for provider "codex" or a Claude account for provider "claude-code" (ignored for opencode), an id from agent_catalog accounts["codex"] / accounts["claude-code"]. The worker uses that account\'s own mode (its ChatGPT or Claude subscription, or its API key). Omit to use the user\'s worker account for that provider (agent_catalog codexWorkerAccount / claudeWorkerAccount; Default when null). A signed-out account is refused with ACCOUNT_SIGNED_OUT.'
   ),
   permission_policy: z.enum(['auto', 'ask', 'restricted']).optional().describe(
     '"auto" (default): fully autonomous. "ask": tool permissions and questions are relayed to you — collect them with agent_wait until="event" and answer with agent_send reply. "restricted": workspace-write sandbox without prompts (the Codex alternative to ask).'
@@ -129,10 +130,10 @@ export const agentDispatchSchema = {
     '"full" (default; "workspace" for design runs), "workspace" (edits limited to cwd) or "read-only" (reviews, research). Browser jobs with "full" require the tag "user-authorized-full".'
   ),
   max_minutes: z.number().int().min(1).max(240).optional().describe(
-    'Wall-clock cap in minutes (1-240, default 45; 60 for design runs); the run is stopped when exceeded.'
+    'Work-time cap in minutes (at most 240, default 45; 60 for design runs; values under 20 are raised to 20, never refused): only the time the worker is working a turn counts, not time queued, idle between turns or waiting on a permission or question, and a turn still working when it is used up is stopped. The run view shows workMs (used) and workLeftMs (left).'
   ),
-  budget_usd: z.number().min(0.1).max(50).optional().describe(
-    'Spend cap in USD (0.1-50; the user\'s Budget settings set the default and may lower the ceiling). Every provider is held to it: Claude between model calls, OpenCode per step, Codex after each turn (priced at list price). It is lowered to what the session hard cap (brain + all runs) has left.'
+  budget_usd: z.number().min(0.01).max(1000).optional().describe(
+    'Optional ceiling in USD for this one run (0.01-1000), inside its provider\'s share of the session budget. Omit it: the run may use what its provider\'s share has left (nothing is reserved; idle runs hold no money). Every provider is held to it: Claude between model calls, OpenCode per step, Codex per rollout record or turn (at list price). Ignored, with a correction, when the user chose No limit.'
   ),
   uses_browser: z.boolean().optional().describe(
     'true when the worker drives the SynaBun browser: it gets a loop browser tab and the browser enforcement block; page content is treated as untrusted data. Design runs default to true; false keeps one off the browser (no tab, no browser profile).'
@@ -231,28 +232,28 @@ export const agentUsageSchema = {
 // ── Descriptions (routing instructions) ──
 
 export const agentCatalogDescription =
-  'Discover what you can route to: providers (claude-code, codex, opencode) with models (tier, price per 1M tokens, vision, context, efforts), accounts, registered projects (cwd candidates), MCP profile presets, rails/limits and active runs. Without arguments it returns a compact routing view (OpenCode sampled); pass provider and/or search to list more models. Call it when the routing sheet in your instructions lacks a model, or after a MODEL_UNKNOWN rejection. Returns JSON.';
+  'Discover what you can route to: providers (claude-code, codex, opencode) with models (tier, price per 1M tokens, vision, context, efforts), accounts with subscription usage remaining (or usage unknown; API keys are n/a), registered projects (cwd candidates), MCP profile presets, rails/limits and active runs. Without arguments it returns a compact routing view (OpenCode sampled); pass provider and/or search to list more models. Call it when the routing sheet in your instructions lacks a model, or after a MODEL_UNKNOWN rejection. Returns JSON.';
 
 export const agentRouteDescription =
-  'Route an actionable task BEFORE starting it (you are the planner). Give task_class, a one-line summary, your honest confidence (0-1) and 1-3 proposals (direct = here on your model; dispatch = a worker provider/model). The server applies the session\'s route mode (always ask / ask when unsure / never ask): it approves at once, or shows the user a route card and waits briefly. Follow the returned status and next: approved+dispatch → agent_dispatch with route_id; approved+direct → do it yourself; continuation → end your turn (SynaBun continues on the chosen model); pending → end your turn, the choice arrives as a [SynaBun Mailbox] route_decided event; declined → do not start (reason no_capable_model: no model can make the image or video, or see for design; tell the user which Model routes row needs one); clarifying → end your turn, the user has not answered your agent_clarify questions yet (independent:true for a task that does not depend on them). image_gen / video_gen always route to a worker whose model generates the medium, design to a worker whose model can see. Never use it for conversation or bookkeeping. Returns JSON.';
+  'Route an actionable task BEFORE starting it (you are the planner). Give task_class, a one-line summary, your honest confidence (0-1) and 1-3 proposals (direct = here on your model; dispatch = a worker provider/model). proposals.account_id accepts an account id or "auto" (most subscription usage left); limited pinned/default accounts fall back within the provider. The returned target.account includes usage and corrections explain the choice. The server applies the session\'s route mode (always ask / ask when unsure / never ask): it approves at once, or shows the user a route card and waits briefly. Follow the returned status and next: approved+dispatch → agent_dispatch with route_id; approved+direct → do it yourself; continuation → end your turn (SynaBun continues on the chosen model); pending → end your turn, the choice arrives as a [SynaBun Mailbox] route_decided event; declined → do not start (reason no_capable_model: no model can make the image or video, or see for design; tell the user which Model routes row needs one); clarifying → end your turn, the user has not answered your agent_clarify questions yet (independent:true for a task that does not depend on them). image_gen / video_gen always route to a worker whose model generates the medium, design to a worker whose model can see. With a session budget, a provider whose share is used up cannot take the task: SynaBun first divides the unspent budget again, then moves the task to the next capable provider with money left (your next proposal, the same tier on another provider, then a free model) and says so in corrections (reason budget_share, "budget: codex share used up -> claude-code/sonnet"); the saved routes yield to this. When no provider can pay it declines with reason budget_exhausted and names the dry providers (dry). The result carries budget: each provider\'s share, spent and left. Never use it for conversation or bookkeeping. Returns JSON.';
 
 export const agentClarifyDescription =
   'Ask the user 1-3 targeted questions BEFORE routing a new request that is materially ambiguous: two plausible readings with different results, an unclear target (project, feature, files, audience), destructive or irreversible scope, spend, or memories that conflict with it. Not for clear requests, details a sensible default covers, anything the request, memory or the project answers, or the model (agent_route asks that). Each question gets 2-4 options (recommended first; the user can always type their own); add constraints (what the request fixes) and assumptions (what you will assume for the rest). The card waits briefly. Follow the returned status and next: answered → route, then agent_dispatch with the brief_id (SynaBun adds the user\'s original words, their answers, the constraints and assumptions to the worker\'s context); declined → proceed on your assumptions; pending → end your turn, the answers arrive as a [SynaBun Mailbox] clarify_answered event or as the user\'s next message, and dependent routes and dispatches wait until then. Returns JSON.';
 
 export const agentListDescription =
-  'List dispatched worker runs with status, provider/model, title, elapsed time and cost. Use it before dispatching more work, to recover run ids, or after a mailbox event. Filter with active_only, assistant_session_id (your own session) or workflow_id. Returns JSON.';
+  'List dispatched worker runs with status, provider/model, title, elapsed time, work time left (workLeftMs) and cost. Use it before dispatching more work, to recover run ids, or after a mailbox event. Filter with active_only, assistant_session_id (your own session) or workflow_id. Returns JSON.';
 
 export const agentDispatchDescription =
-  'Dispatch a task to a worker agent (Claude Code, Codex or OpenCode). Route it first with agent_route and pass the approved route_id (the server applies that provider/model/effort); without one, the dispatch may be held until the user picks a model (awaitingRoute:true — do not dispatch it again). After agent_clarify, pass its brief_id: the worker gets the user\'s own words and answers; while its questions are open a dependent dispatch is refused (CLARIFICATION_PENDING). The run attaches as a live automation tab in the matching sidepanel without stealing focus. Write a self-contained task that ends with a ## Result block, pass the absolute cwd and your assistant_session_id. Defaults: permission_policy "auto", capability "full", 45 minutes, $5. Use "ask" only for sensitive scopes (Codex cannot ask: use "restricted"). uses_computer:true for desktop work (one at a time, vision model). An image_gen / video_gen run makes the asset with its model\'s own generation tool; SynaBun collects the files into the run\'s result (media: path + url); with no model that generates the medium an un-routed dispatch is refused (NO_CAPABLE_MODEL), and a route_id approved for other work is refused for image_gen / video_gen / design (and the other way round: ROUTE_CLASS_MISMATCH; route the task again with its own class). A design run gets SynaBun\'s design rules and the project\'s style guide, defaults to capability "workspace", uses_browser true, mcp_profile "browser" and 60 minutes (explicit values win), runs only on a model confirmed to see (MODEL_CANNOT_SEE otherwise), and its screenshots land in the result\'s media. Group fan-outs with workflow_id, chain with parent_run_id, retry safely with idempotency_key. Over-limit dispatches are queued (queued:true, position). After dispatching, block with agent_wait rather than polling. Returns JSON.';
+  'Dispatch a task to a worker agent (Claude Code, Codex or OpenCode). Route it first with agent_route and pass the approved route_id (the server applies that provider/model/effort); without one, the dispatch may be held until the user picks a model (awaitingRoute:true — do not dispatch it again). After agent_clarify, pass its brief_id: the worker gets the user\'s own words and answers; while its questions are open a dependent dispatch is refused (CLARIFICATION_PENDING). The run attaches as a live automation tab in the matching sidepanel without stealing focus. Write a self-contained task that ends with a ## Result block, pass the absolute cwd and your assistant_session_id. Defaults: permission_policy "auto", capability "full", 45 minutes of work time (max_minutes, at least 20), no per-run dollar ceiling (with a budget the run draws from its provider\'s share; a provider whose share is used up and cannot get more is refused with BUDGET_SHARE_EXHAUSTED: route again). Use "ask" only for sensitive scopes (Codex cannot ask: use "restricted"). uses_computer:true for desktop work (one at a time, vision model). An image_gen / video_gen run makes the asset with its model\'s own generation tool; SynaBun collects the files into the run\'s result (media: path + url); with no model that generates the medium an un-routed dispatch is refused (NO_CAPABLE_MODEL), and a route_id approved for other work is refused for image_gen / video_gen / design (and the other way round: ROUTE_CLASS_MISMATCH; route the task again with its own class). A design run gets SynaBun\'s design rules and the project\'s style guide, defaults to capability "workspace", uses_browser true, mcp_profile "browser" and 60 minutes of work time (explicit values win), runs only on a model confirmed to see (MODEL_CANNOT_SEE otherwise), and its screenshots land in the result\'s media. Group fan-outs with workflow_id, chain with parent_run_id, retry safely with idempotency_key. Over-limit dispatches are queued (queued:true, position). After dispatching, block with agent_wait rather than polling. Returns JSON.';
 
 export const agentStatusDescription =
-  'Get one run\'s current descriptor: status (queued, running, completed, failed, stopped, interrupted), turnState (running, idle, awaiting_permission), provider/model/account, elapsed time, cost, the last parsed result summary and any pending permission or question requests. Cheap; use it between agent_wait calls or before agent_send / agent_stop. Returns JSON.';
+  'Get one run\'s current descriptor: status (queued, running, completed, failed, stopped, interrupted), turnState (running, idle, awaiting_permission), provider/model/account, elapsed time (elapsedMs, wall clock), work time used and left of max_minutes (workMs, workLeftMs), cost, the last parsed result summary and any pending permission or question requests. Cheap; use it between agent_wait calls or before agent_send / agent_stop. Returns JSON.';
 
 export const agentReadDescription =
   'Read a run\'s output. format "result" (default) returns the parsed ## Result contract (status, summary, changes, follow_ups, question, json, and media: the images / videos an image_gen or video_gen run generated or a design run captured, each { kind, path, url, mime, bytes } — show one with ![](url) plus its path); "tail" returns the last transcript events; "text" the worker\'s assistant text; "files" the files it reported. Call after agent_wait reports idle or terminal; keep max_chars small and read again if truncated. Returns JSON.';
 
 export const agentSendDescription =
-  'Continue a worker\'s conversation. text sends a follow-up turn (queue:true enqueues it while the worker is still running). reply answers a pending permission or question request: decision allow/deny for tools, answer (with answers) for questions, note as an optional message. Obtain request ids from agent_status or agent_wait until="event". Returns JSON.';
+  'Continue a worker\'s conversation. text sends a follow-up turn (queue:true enqueues it while the worker is still running). reply answers a pending permission or question request: decision allow/deny for tools, answer (with answers) for questions, note as an optional message. Obtain request ids from agent_status or agent_wait until="event". A follow-up to a run whose work time (max_minutes) is used up is refused with TIME_CAP: dispatch a new run with its result as context. Returns JSON.';
 
 export const agentWaitDescription =
   'Blocking barrier for orchestration. Waits up to timeout_seconds (max 120) for one run (run_id), several runs (run_ids with mode all/any) or a whole workflow to reach until="idle" (turn finished; default), "terminal" (completed, failed, stopped) or "event" (next mailbox event: result, needs_input, permission_request, failed). Returns the run descriptors and whether the wait timed out; call again to keep waiting. Prefer this over polling agent_status. Returns JSON.';
@@ -264,7 +265,7 @@ export const agentFocusDescription =
   'Bring a run\'s sidepanel automation tab to the front (focus:false releases it). Use when the user asks to watch a worker; dispatches never steal focus by themselves. Returns JSON.';
 
 export const agentUsageDescription =
-  'Get token usage for a task, run, or entire Assistant session. Returns compact JSON. `session` is the headline the panel shows: every task of this session added up (it only grows, and survives a restart), with a per-model breakdown (models: inputTotal, outputTotal, total, costUsd, costBasis). Below it the task asked for: tokens, USD cost, fidelity, unsynced (rows not on disk yet, normally 0), and each agent\'s key, title, provider, model, total, sub-agents total, fidelity and state (partialReason when a count is partial; calls on the Jev judgments row). Every tokens object has the five additive classes (input = uncached input, cacheWrite, cacheRead, output = visible output, reasoning), total, inputTotal (input + cacheWrite + cacheRead: everything sent to the model) and outputTotal (output + reasoning): the same meaning for every provider, nothing counted twice. costUsd is at API list prices; costBasis says how it is known: reported (the provider reported it), estimated (tokens at list price: Codex and other plan-billed work, where it is the list-price equivalent, not a charge), free, or unpriced (no list price: tokens counted, no dollars). Counts are exact provider counts when fidelity is exact; live marks provisional counts and partial marks incomplete counts. metered:false means this server keeps no usage ledger. No routing is needed.';
+  'Get token usage for a task, run, or entire Assistant session. Returns compact JSON. `session` is the headline the panel shows: every task of this session added up (it only grows, and survives a restart), with a per-model breakdown (models: inputTotal, outputTotal, total, costUsd, costBasis). Below it the task asked for: tokens, USD cost, fidelity, unsynced (rows not on disk yet, normally 0), and each agent\'s key, title, provider, model, total, sub-agents total, fidelity and state (partialReason when a count is partial; calls on the Jev judgments row). `budget` is the session budget: mode (limited / unlimited: the user chose No limit), the amount, spent and left, warned / exceeded, how the split was made (source jev | fallback, updatedAt) and each provider\'s share, spent and left (brain marks your own provider; leftUsd is what its workers may still spend), and dry: the providers whose share is used up. Every tokens object has the five additive classes (input = uncached input, cacheWrite, cacheRead, output = visible output, reasoning), total, inputTotal (input + cacheWrite + cacheRead: everything sent to the model) and outputTotal (output + reasoning): the same meaning for every provider, nothing counted twice. costUsd is at API list prices; costBasis says how it is known: reported (the provider reported it), estimated (tokens at list price: Codex and other plan-billed work, where it is the list-price equivalent, not a charge), free, or unpriced (no list price: tokens counted, no dollars). Counts are exact provider counts when fidelity is exact; live marks provisional counts and partial marks incomplete counts. metered:false means this server keeps no usage ledger. No routing is needed.';
 
 // ── Handlers ──
 
@@ -473,6 +474,23 @@ export function handleAgentUsage(args: AgentUsageArgs): Promise<ToolResult> {
       tasks: Array.isArray(session.tasks) ? session.tasks.length : session.tasks ?? 0,
       models: (Array.isArray(session.models) ? session.models : []).map(compactModel),
     });
+    /** The session budget: the mode, the total, and each provider's share / spent / left. */
+    const compactBudget = (b: any) => {
+      if (!b || typeof b !== 'object') return null;
+      if (b.unlimited) return { mode: 'unlimited', spentUsd: b.spentUsd ?? 0 };
+      return {
+        mode: 'limited', amountUsd: b.amountUsd ?? null, spentUsd: b.spentUsd ?? 0, leftUsd: b.leftUsd ?? null,
+        warnAtUsd: b.warnAtUsd ?? null, warned: !!b.warned, exceeded: !!b.exceeded,
+        split: b.split ? { source: b.split.source ?? null, reason: b.split.reason ?? null, updatedAt: b.split.updatedAt ?? null } : null,
+        providers: (Array.isArray(b.providers) ? b.providers : []).map((row: any) => ({
+          provider: row.provider, ...(row.isBrain ? { brain: true } : {}), eligible: row.eligible !== false,
+          shareUsd: row.shareUsd ?? null, spentUsd: row.spentUsd ?? 0, leftUsd: row.workerLeftUsd ?? row.leftUsd ?? null,
+          ...(row.isBrain ? { brainLeftUsd: row.leftUsd ?? null } : {}),
+        })),
+        dry: Array.isArray(b.dry) ? b.dry : [],
+      };
+    };
+    const budget = compactBudget((answer as any).budget);
     const compactAgent = (agent: any) => ({
       key: agent.key, title: agent.title ?? null, provider: agent.provider, model: agent.model,
       tokens: agent.tokens, total: agent.tokens?.total ?? 0, subagents: { total: agent.subagents?.total ?? 0 },
@@ -484,9 +502,9 @@ export function handleAgentUsage(args: AgentUsageArgs): Promise<ToolResult> {
     if (task === 'all') {
       const session = answer.session as any;
       // The server has no usage ledger: say so, never fail on the missing view.
-      if (!session) return text(JSON.stringify({ sessionId: args.assistant_session_id, metered: false, tokens: null, costUsd: 0, tasks: [] }));
+      if (!session) return text(JSON.stringify({ sessionId: args.assistant_session_id, metered: false, tokens: null, costUsd: 0, tasks: [], budget }));
       const { tasks: _taskCount, ...totals } = sessionHead(session);
-      const head = { sessionId: session.sessionId, ...totals, unsynced: session.unsynced ?? 0 };
+      const head = { sessionId: session.sessionId, ...totals, unsynced: session.unsynced ?? 0, budget };
       if (args.run_id) {
         const run = answer.run as any;
         const worked = new Set<string>(Array.isArray(run?.taskIds) ? run.taskIds : []);
@@ -500,7 +518,7 @@ export function handleAgentUsage(args: AgentUsageArgs): Promise<ToolResult> {
       return text(JSON.stringify({ ...head, tasks: session.tasks }));
     }
     const view = answer.usage as any;
-    if (!view) return text(JSON.stringify({ sessionId: args.assistant_session_id, metered: false, task: null, tokens: null, costUsd: 0, fidelity: null, agents: [] }));
+    if (!view) return text(JSON.stringify({ sessionId: args.assistant_session_id, metered: false, task: null, tokens: null, costUsd: 0, fidelity: null, agents: [], budget }));
     const detail = view.task;
     return text(JSON.stringify({
       sessionId: view.sessionId,
@@ -511,6 +529,7 @@ export function handleAgentUsage(args: AgentUsageArgs): Promise<ToolResult> {
       // Rows the ledger has not written to disk yet (normally 0).
       unsynced: view.session?.unsynced ?? 0,
       agents: (detail?.agents || []).filter((agent: any) => !args.run_id || agent.key === args.run_id || agent.runId === args.run_id).map(compactAgent),
+      budget,
     }));
   });
 }

package/mcp-server/src/tools/whatsapp-send-file.ts

@@ -0,0 +1,51 @@
+import { z } from 'zod';
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import * as ni from '../services/neural-interface.js';
+import { callerBrainCredential, callerRole } from '../services/identity.js';
+import { text } from './response.js';
+
+// ═══════════════════════════════════════════
+// whatsapp_send_file — a local file to the owner, in the WhatsApp conversation
+// ═══════════════════════════════════════════
+//
+// In the role-gated `agents` group (profiles.ts ROLE_GATED_GROUPS): advertised
+// to assistant brains only, and the handler refuses any other caller. One
+// POST to /api/assistant/whatsapp/send-file (neural-interface/lib/assistant-api.js)
+// carrying the brain's own credential (identity.ts callerBrainCredential), which
+// the server resolves to the WhatsApp conversation; the WhatsApp host checks and
+// reads the file (neural-interface/lib/whatsapp/local-file.js). Never retried:
+// a timeout may come after WhatsApp took the file. No recipient, no session id.
+
+export const WHATSAPP_SEND_FILE_DENIED = 'whatsapp_send_file is only available to the SynaBun assistant runtime.';
+
+export const WHATSAPP_SEND_AS = ['auto', 'document', 'image', 'video', 'audio'] as const;
+
+export const whatsappSendFileSchema = {
+  path: z.string().min(1).max(2048).describe('Absolute path of an existing regular file on this computer. No URL or network share.'),
+  caption: z.string().max(1024).optional().describe('Text shown under the file (at most 1024 characters). Audio has none: leave it out, or choose as "document".'),
+  as: z.enum(WHATSAPP_SEND_AS).optional().describe(
+    'Default "auto": JPEG/PNG/WebP as a photo, MP4 as a video, OGG/Opus/MP3/M4A as audio, everything else as a document. "document" sends the original file as it is. Photos, videos and audio over 16 MiB go as documents; nothing over 100 MiB is sent. A native form that does not match the extension is refused.'
+  ),
+};
+
+export const whatsappSendFileDescription = 'Send a file already on this computer as a real WhatsApp attachment to the owner, in THIS WhatsApp conversation. Use it only when the user asked you to send a file (a generated image or video they asked for included: take its local path from the worker result\'s media). Only the active WhatsApp conversation\'s own Assistant can use it: never workers, desktop chats or other contacts; there is no recipient or session parameter. Sensitive places (keys, credentials, browser and app data, SynaBun\'s own data) are refused, and links are resolved and checked too. Returns the delivery id, type, mimetype, size, file name and canonical path, or a clear error code. An answer with uncertain: true (a timeout, a lost answer), or a call of yours that times out, means delivery is uncertain: never retry it on your own.';
+
+export type WhatsAppSendFileArgs = z.infer<z.ZodObject<typeof whatsappSendFileSchema>>;
+
+/** Role guard, one request, never throws: every failure reaches the brain as data. */
+export async function handleWhatsAppSendFile(args: WhatsAppSendFileArgs): Promise<ReturnType<typeof text>> {
+  if (callerRole() !== 'assistant') return text(WHATSAPP_SEND_FILE_DENIED);
+  try {
+    const body: { path: string; caption?: string; as?: string } = { path: args.path };
+    if (typeof args.caption === 'string') body.caption = args.caption;
+    if (typeof args.as === 'string') body.as = args.as;
+    return text(JSON.stringify(await ni.whatsappSendFile(body, callerBrainCredential()), null, 2));
+  } catch (err) {
+    return text(JSON.stringify({ ok: false, error: err instanceof Error ? err.message : String(err), code: 'WHATSAPP_SEND_FILE_ERROR' }));
+  }
+}
+
+/** Registered into the `agents` group (index.ts): the returned handle is gated on the caller role. */
+export function registerWhatsAppSendFileTool(server: McpServer) {
+  return server.tool('whatsapp_send_file', whatsappSendFileDescription, whatsappSendFileSchema, (args) => handleWhatsAppSendFile(args));
+}

package/mcp-server/src/tui.ts

@@ -27,6 +27,7 @@ import { ensureCollection, scrollMemories, searchMemories, getMemory, deleteMemo
 import { getAllCategories, getCategories, getCustomCategories, getCategoryDescription, validateCategoryName, addCategory, removeCategory } from './services/categories.js';
 import { generateEmbedding } from './services/local-embeddings.js';
 import { detectProject } from './config.js';
+import { SERVER_VERSION } from './version.js';
 import type { MemoryPayload, MemorySource } from './types.js';
 
 // ── Box drawing characters ────────────────────────────────────────
@@ -228,7 +229,7 @@ function printLogo(): void {
   console.log(dboxRow(W, ''));
 
   // Tagline (centered)
-  const tagline = accent2('Vector-Powered') + dim(' \u2022 ') + info('SQLite') + dim(' \u2022 ') + chalk.white('v2.0.0');
+  const tagline = accent2('Vector-Powered') + dim(' \u2022 ') + info('SQLite') + dim(' \u2022 ') + chalk.white(`v${SERVER_VERSION}`);
   console.log(dboxRow(W, tagline));
 
   console.log(dim(BOX.dbl + BOX.dh.repeat(W) + BOX.dbr));

package/mcp-server/src/version.ts

@@ -0,0 +1,22 @@
+import { readFileSync } from 'fs';
+
+// The version the server reports (MCP initialize serverInfo, the TUI banner)
+// is the one in mcp-server/package.json, never a literal. src/ and dist/ both
+// sit one level under mcp-server/, so `../package.json` is that file in the
+// checkout, under vitest, in the npm package and in the packaged desktop app
+// (both ship mcp-server/package.json beside mcp-server/dist/).
+const PACKAGE_URL = new URL('../package.json', import.meta.url);
+const PACKAGE_NAME = 'claude-memory-mcp';
+
+/** Reported when the package file is missing, unreadable or another package's. */
+export const UNKNOWN_SERVER_VERSION = '0.0.0-unknown';
+
+export function readServerVersion(packageUrl: URL = PACKAGE_URL): string {
+  try {
+    const pkg = JSON.parse(readFileSync(packageUrl, 'utf-8')) as { name?: unknown; version?: unknown };
+    if (pkg?.name === PACKAGE_NAME && typeof pkg.version === 'string' && pkg.version.trim()) return pkg.version.trim();
+  } catch { /* missing or malformed: fall through */ }
+  return UNKNOWN_SERVER_VERSION;
+}
+
+export const SERVER_VERSION = readServerVersion();