mercury-agent 0.13.0 → 0.14.0

package/docs/container-lifecycle.md

@@ -96,8 +96,9 @@ Containers have a maximum runtime to prevent runaway processes.
 When a container exceeds the timeout:
 1. Container is killed via `docker kill`
 2. `ContainerError` thrown with `reason: "timeout"`
-3. User sees: "Container timed out."
-4. Queue unblocks, next message can proceed
+3. User sees: "I ran out of time before finishing. Partial work may be saved in the workspace — ask me to continue."
+4. A marker assistant message ("[System: this run was killed at the container time limit before replying. …]") is recorded in chat history, so the next run's agent knows the previous run was cut off and can check the workspace for partial work
+5. Queue unblocks, next message can proceed
 
 The host always injects a resolved **model chain** into the container (after `MERCURY_*` passthrough) so retries and fallbacks use the same policy Mercury loaded at startup:
 
@@ -113,7 +114,7 @@ Container failures are classified by `ContainerError`:
 
 | Reason | Exit Code | Cause | User Message |
 |--------|-----------|-------|--------------|
-| `timeout` | — | Exceeded `containerTimeoutMs` | "Container timed out." |
+| `timeout` | — | Exceeded `containerTimeoutMs` | "I ran out of time before finishing. Partial work may be saved in the workspace — ask me to continue." |
 | `oom` | 137 | SIGKILL (OOM, resource limits, or manual kill) | "Container was killed (possibly out of memory)." |
 | `aborted` | — | User sent `stop` command | "Stopped current run." |
 | `error` | non-zero | Agent crashed or failed | *(error thrown, logged)* |

package/docs/permissions.md

@@ -28,7 +28,7 @@ Message arrives
 |------|---------------------|-------------|
 | `system` | All | Internal system caller (scheduler, etc.) — not assignable |
 | `admin` | All | Full control over the space |
-| `member` | `prompt`, `prefs.get`, `media.receive`, `media.send` | Can chat, read space preferences, and exchange files (default for new users) |
+| `member` | `prompt`, `prefs.get`, `media.receive`, `media.send`, `model.list` | Can chat, read space preferences, exchange files, and list models (default for new users) |
 
 Custom roles can be created by assigning permissions to any role name.
 
@@ -56,6 +56,8 @@ Custom roles can be created by assigning permissions to any role name.
 | `spaces.list` | View all spaces |
 | `spaces.rename` | Rename a space and link/unlink conversations |
 | `spaces.delete` | Delete current space and all related DB data |
+| `model.list` | List the configured model chain (`mrctl model list`, chat `/model list`) |
+| `model.switch` | Switch the active model for the space (`mrctl model switch`, chat `/model switch`) — takes effect on the next agent run |
 | `media.receive` | Incoming attachments are saved to `inbox/` and shown to the agent |
 | `media.send` | Outbox files produced on this caller's turn are delivered back to the chat |
 

package/examples/extensions/gws/README.md

@@ -28,19 +28,38 @@ npm i -g @googleworkspace/cli
 gws auth login
 ```
 
-2. Export credentials once:
+2. Export the credentials and put the JSON (as a single line) into `.env`:
 
 ```bash
-gws auth export --unmasked > .mercury/global/gws-credentials.json
+gws auth export --unmasked
 ```
 
-3. Add to `.env`:
-
 ```bash
-MERCURY_GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE=/home/mercury/.pi/agent/gws-credentials.json
+MERCURY_GWS_CREDENTIALS_JSON={"client_id":"...","client_secret":"...","refresh_token":"...","type":"authorized_user"}
 ```
 
-(You can also use `MERCURY_GOOGLE_WORKSPACE_CLI_TOKEN`, but it expires quickly.)
+3. Restart Mercury. The extension's `before_container` hook passes the JSON
+   into the inner container, and the skill materializes it as a credentials
+   file at runtime.
+
+> **Do not use the file-based path.** Older versions of this README said to
+> export to `.mercury/global/gws-credentials.json` and set
+> `MERCURY_GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE`. That no longer works: the
+> runtime mounts the global dir into the inner container entry-by-entry via an
+> allowlist (`PI_AGENT_RESOURCE_ENTRIES` in `container-runner.ts`), and the
+> credentials file is not on it — the container never sees it.
+>
+> **Windows/PowerShell note:** if you do redirect `gws auth export` output to a
+> file, PowerShell's `>` writes UTF-16 — invalid for JSON readers. Use
+> `gws auth export --unmasked | Out-File -Encoding utf8 <path>` instead.
+>
+> (`MERCURY_GOOGLE_WORKSPACE_CLI_TOKEN` also exists, but it expires quickly.)
+
+## Refreshing credentials
+
+Re-run `gws auth login` + `gws auth export --unmasked`, replace the
+`MERCURY_GWS_CREDENTIALS_JSON` value in `.env` (the refresh token changes),
+and restart Mercury.
 
 ## Verify
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mercury-agent",
-  "version": "0.13.0",
+  "version": "0.14.0",
   "description": "Personal AI assistant for chat platforms (WhatsApp, Slack, Discord, Telegram)",
   "license": "MIT",
   "author": "Avishai Tsabari",

package/resources/templates/AGENTS.md

@@ -53,6 +53,14 @@ mrctl config set <key> <value>  # Set config value
 #             context.mode (clear|context), context.reply_chain_depth (1-50)
 ```
 
+### Models
+```bash
+mrctl model list                # List configured models (active one marked)
+mrctl model switch <N|MODEL_ID> # Switch active model — takes effect on the NEXT agent run
+```
+
+**Note:** A switch never changes the run you are in — say so when reporting it. Switching requires the `model.switch` permission (admin by default); a 403 means the caller must ask an admin.
+
 ### Spaces
 ```bash
 mrctl spaces list               # List all spaces with names (admin-only)

package/src/adapters/whatsapp.ts

@@ -63,7 +63,7 @@ function extractText(rawMessage?: proto.IMessage | null): string {
   );
 }
 
-function getContextInfo(
+export function getContextInfo(
   rawMessage?: proto.IMessage | null,
 ): proto.IContextInfo | undefined {
   const message = normalizeMessageContent(rawMessage ?? undefined);
@@ -72,6 +72,9 @@ function getContextInfo(
     message.extendedTextMessage?.contextInfo ||
     message.imageMessage?.contextInfo ||
     message.videoMessage?.contextInfo ||
+    message.ptvMessage?.contextInfo ||
+    message.audioMessage?.contextInfo ||
+    message.stickerMessage?.contextInfo ||
     message.documentMessage?.contextInfo ||
     message.buttonsResponseMessage?.contextInfo ||
     message.templateButtonReplyMessage?.contextInfo ||

package/src/bridges/whatsapp.ts

@@ -1,12 +1,11 @@
 import fs from "node:fs";
 import path from "node:path";
-import {
-  normalizeMessageContent,
-  type proto,
-  type WAMessage,
-} from "@whiskeysockets/baileys";
+import type { proto, WAMessage } from "@whiskeysockets/baileys";
 import type { Message } from "chat";
-import type { WhatsAppBaileysAdapter } from "../adapters/whatsapp.js";
+import {
+  getContextInfo,
+  type WhatsAppBaileysAdapter,
+} from "../adapters/whatsapp.js";
 import {
   detectWhatsAppMedia,
   downloadQuotedMedia,
@@ -97,14 +96,7 @@ export class WhatsAppBridge implements PlatformBridge {
       }
 
       if (attachments.length === 0) {
-        const content = normalizeMessageContent(rawMsg.message ?? undefined);
-        const contextInfo =
-          content?.extendedTextMessage?.contextInfo ||
-          content?.audioMessage?.contextInfo ||
-          content?.imageMessage?.contextInfo ||
-          content?.videoMessage?.contextInfo ||
-          content?.documentMessage?.contextInfo ||
-          content?.stickerMessage?.contextInfo;
+        const contextInfo = getContextInfo(rawMsg.message);
         if (contextInfo?.quotedMessage) {
           if (await ctx.isOverQuota()) {
             logger.warn(

package/src/cli/mrctl.ts

@@ -82,6 +82,7 @@ Built-in commands:
   mrctl prefs list|get|set|delete
   mrctl roles list|grant|revoke
   mrctl permissions show|set
+  mrctl model list|switch <N|MODEL_ID>        (switch takes effect on the NEXT agent run)
   mrctl spaces list|name [<name>]|delete      (delete: CURRENT space only, takes no argument)
   mrctl conversations list
   mrctl mute <platform-user-id> <duration> [--reason <reason>]
@@ -405,6 +406,49 @@ async function main() {
       break;
     }
 
+    case "model": {
+      if (!sub) usage();
+      switch (sub) {
+        case "list": {
+          const data = (await api("GET", "/api/model")) as {
+            models: Array<{
+              index: number;
+              provider: string;
+              model: string;
+              active: boolean;
+            }>;
+          };
+          if (data.models.length === 0) {
+            process.stdout.write("No models configured.\n");
+            break;
+          }
+          // Same shape as chat /model list so the agent can relay it verbatim
+          process.stdout.write("Configured models:\n");
+          for (const m of data.models) {
+            process.stdout.write(
+              `  [${m.index}] ${m.provider} / ${m.model}${m.active ? "   ← active" : ""}\n`,
+            );
+          }
+          break;
+        }
+        case "switch": {
+          const target = requireArg(args, 2, "target (<N|MODEL_ID>)");
+          const data = (await api("POST", "/api/model/switch", { target })) as {
+            provider: string;
+            model: string;
+            note: string;
+          };
+          process.stdout.write(
+            `Switched to ${data.provider} / ${data.model}. ${data.note}\n`,
+          );
+          break;
+        }
+        default:
+          fatal(`Unknown model subcommand: ${sub}`);
+      }
+      break;
+    }
+
     case "conversations": {
       const action = sub ?? "list";
       switch (action) {

package/src/core/api.ts

@@ -15,6 +15,7 @@ import {
   extensions,
   media,
   messages,
+  model,
   mutes,
   permissions,
   prefs,
@@ -114,6 +115,7 @@ export function createApiApp(apiCtx: ApiContext): Hono<Env> {
   app.route("/conversations", conversations);
   app.route("/media", media);
   app.route("/messages", messages);
+  app.route("/model", model);
   app.route("/mutes", mutes);
   app.route("/ext", extensions);
   app.route("/connections", connections);

package/src/core/model-command.ts

@@ -0,0 +1,55 @@
+import type { ModelLeg } from "../config.js";
+
+/**
+ * Shared resolution logic for the model chain — the single source of truth
+ * behind both the chat `/model list|switch` command (runtime.ts) and the
+ * `/api/model` route (routes/model.ts). Semantics live here so the two
+ * surfaces cannot drift.
+ */
+
+/**
+ * Index of the active leg in the chain: the leg named by the stored
+ * `model.active` value (`provider:model`) when it still exists in the chain,
+ * otherwise leg 0. A stale value (host config changed since the switch) falls
+ * back to the primary leg, matching what container start does when it ignores
+ * an unknown override.
+ *
+ * Returns -1 only for an empty chain.
+ */
+export function resolveActiveIndex(
+  chain: ModelLeg[],
+  activeRaw: string | null,
+): number {
+  if (chain.length === 0) return -1;
+  if (activeRaw) {
+    const idx = chain.findIndex(
+      (l) => `${l.provider}:${l.model}` === activeRaw,
+    );
+    if (idx !== -1) return idx;
+  }
+  return 0;
+}
+
+/**
+ * Resolve a switch target to a chain leg, or null if it names none.
+ * Accepted forms, in resolution order:
+ *  1. 1-based index into the chain ("2") — numeric parse wins over a model
+ *     literally named like an in-range number
+ *  2. bare model id ("claude-opus-4-8")
+ *  3. provider-qualified id ("anthropic:claude-opus-4-8")
+ */
+export function resolveSwitchTarget(
+  chain: ModelLeg[],
+  arg: string,
+): ModelLeg | null {
+  // Strict digits only: parseInt("2junk") is 2, and a typo silently switching
+  // to a real leg is exactly the failure this validated path exists to prevent.
+  if (/^\d+$/.test(arg)) {
+    const num = Number.parseInt(arg, 10);
+    if (num >= 1 && num <= chain.length) return chain[num - 1];
+  }
+  return (
+    chain.find((l) => l.model === arg || `${l.provider}:${l.model}` === arg) ??
+    null
+  );
+}

package/src/core/permissions.ts

@@ -34,6 +34,10 @@ const BUILT_IN_PERMISSIONS = new Set([
   "media.receive",
   /** Outbox files produced on this caller's turn are delivered back. */
   "media.send",
+  /** List the configured model chain (/api/model, chat /model list). */
+  "model.list",
+  /** Switch the active model (/api/model/switch, chat /model switch); admin-only by default. */
+  "model.switch",
   /** Host Text-to-Speech (/api/tts); admin-only by default. */
   "tts.synthesize",
   /** Mute/unmute users and list mutes; admin-only by default. */
@@ -194,6 +198,9 @@ const DEFAULT_MEMBER_PERMISSIONS = new Set([
   "prefs.get",
   "media.receive",
   "media.send",
+  // Read-only, like prefs.get: lets the agent answer "which models do I have?"
+  // for any caller. model.switch is deliberately absent — admin-only default.
+  "model.list",
 ]);
 
 /**
@@ -201,7 +208,7 @@ const DEFAULT_MEMBER_PERMISSIONS = new Set([
  * with extension-registered defaults.
  *
  * - `admin` and `system` get all permissions (built-in + extension)
- * - `member` gets `prompt`, `prefs.get`, `media.receive`, `media.send`, plus any extension permissions that list "member" in defaultRoles
+ * - `member` gets `prompt`, `prefs.get`, `media.receive`, `media.send`, `model.list`, plus any extension permissions that list "member" in defaultRoles
  * - Other roles get extension permissions that list them in defaultRoles
  */
 function getDefaultPermissions(role: string): Set<string> {

package/src/core/routes/index.ts

@@ -8,6 +8,7 @@ export { conversations } from "./conversations.js";
 export { extensions } from "./extensions.js";
 export { media } from "./media.js";
 export { messages } from "./messages.js";
+export { model } from "./model.js";
 export { mutes } from "./mutes.js";
 export { prefs } from "./prefs.js";
 export { permissions, roles } from "./roles.js";

package/src/core/routes/model.ts

@@ -0,0 +1,68 @@
+import { Hono } from "hono";
+import { checkPerm, type Env, getApiCtx, getAuth } from "../api-types.js";
+import { resolveActiveIndex, resolveSwitchTarget } from "../model-command.js";
+
+export const model = new Hono<Env>();
+
+model.get("/", (c) => {
+  const { spaceId } = getAuth(c);
+  const denied = checkPerm(c, "model.list");
+  if (denied) return denied;
+
+  const { db, config } = getApiCtx(c);
+  const chain = config.resolvedModelChain;
+  const activeIdx = resolveActiveIndex(
+    chain,
+    db.getSpaceConfig(spaceId, "model.active"),
+  );
+
+  return c.json({
+    models: chain.map((leg, i) => ({
+      // 1-based to match chat /model list and the switch target form
+      index: i + 1,
+      provider: leg.provider,
+      model: leg.model,
+      active: i === activeIdx,
+    })),
+  });
+});
+
+model.post("/switch", async (c) => {
+  const { spaceId, callerId } = getAuth(c);
+  const denied = checkPerm(c, "model.switch");
+  if (denied) return denied;
+
+  const { db, config } = getApiCtx(c);
+  const body = await c.req
+    .json<{ target?: string }>()
+    .catch(() => ({}) as { target?: string });
+
+  const target = typeof body.target === "string" ? body.target.trim() : "";
+  if (!target) return c.json({ error: "Missing target" }, 400);
+
+  const chain = config.resolvedModelChain;
+  if (chain.length === 0) {
+    return c.json({ error: "No models configured." }, 400);
+  }
+
+  const leg = resolveSwitchTarget(chain, target);
+  if (!leg) {
+    return c.json(
+      { error: "Model not found. Use mrctl model list to see your options." },
+      400,
+    );
+  }
+
+  db.setSpaceConfig(
+    spaceId,
+    "model.active",
+    `${leg.provider}:${leg.model}`,
+    callerId,
+  );
+
+  return c.json({
+    provider: leg.provider,
+    model: leg.model,
+    note: "Takes effect on the next agent run; the current run keeps its model.",
+  });
+});

package/src/core/runtime.ts

@@ -33,6 +33,7 @@ import {
   resolveRecipientSpaceId,
 } from "./direct-send.js";
 import { gateIncomingMedia, gateOutgoingMedia } from "./media-gate.js";
+import { resolveActiveIndex, resolveSwitchTarget } from "./model-command.js";
 import { hasPermission, resolveRole } from "./permissions.js";
 import { getActiveProfilePrompt } from "./profiles.js";
 import { RateLimiter } from "./rate-limiter.js";
@@ -587,6 +588,7 @@ export class MercuryCoreRuntime {
         message.spaceId,
         route.command,
         route.callerId,
+        route.role,
         route.verb,
         route.arg,
         {
@@ -803,6 +805,7 @@ export class MercuryCoreRuntime {
     spaceId: string,
     command: string,
     callerId: string,
+    role: string,
     verb?: string,
     arg?: string,
     conversationContext?: { platform: string; externalId: string },
@@ -833,7 +836,7 @@ export class MercuryCoreRuntime {
         return formatHelp();
       }
       case "model":
-        return this.executeModelsCommand(spaceId, callerId, verb, arg);
+        return this.executeModelsCommand(spaceId, callerId, role, verb, arg);
       case "spaces":
         return this.executeSpacesCommand(
           spaceId,
@@ -854,6 +857,7 @@ export class MercuryCoreRuntime {
   private executeModelsCommand(
     spaceId: string,
     callerId: string,
+    role: string,
     verb?: string,
     arg?: string,
   ): string {
@@ -865,19 +869,18 @@ export class MercuryCoreRuntime {
 
     switch (verb) {
       case "list": {
+        // Deliberately NOT gated on model.list: chat list is read-only, members
+        // hold model.list by default anyway, and pre-gate behavior is kept
+        // byte-identical. Only the API surface enforces model.list (an admin
+        // revoking it blocks mrctl/API listing but not chat).
         if (chain.length === 0) return "No models configured.";
         const activeRaw = this.db.getSpaceConfig(spaceId, "model.active");
-        const activeFound = activeRaw
-          ? chain.some((l) => `${l.provider}:${l.model}` === activeRaw)
-          : false;
+        const activeIdx = resolveActiveIndex(chain, activeRaw);
         const lines = ["Configured models:"];
         for (let i = 0; i < chain.length; i++) {
           const leg = chain[i];
-          const isActive = activeFound
-            ? activeRaw === `${leg.provider}:${leg.model}`
-            : i === 0;
           lines.push(
-            `  [${i + 1}] ${leg.provider} / ${leg.model}${isActive ? "   ← active" : ""}`,
+            `  [${i + 1}] ${leg.provider} / ${leg.model}${i === activeIdx ? "   ← active" : ""}`,
           );
         }
         return lines.join("\n");
@@ -890,20 +893,17 @@ export class MercuryCoreRuntime {
         return "`/model active` has been removed — `/model list` marks the active model.";
 
       case "switch": {
+        // The router only admin-gates slash commands in GROUP chats; in DMs any
+        // prompt-holder reaches this point. Same permission as /api/model/switch
+        // so the two surfaces cannot disagree.
+        if (!hasPermission(this.db, spaceId, role, "model.switch")) {
+          return "Switching models requires the 'model.switch' permission — ask an admin.";
+        }
         if (!arg)
           return "Usage: /model switch <N|MODEL_ID>. Use /model list to see options.";
         if (chain.length === 0) return "No models configured.";
 
-        let leg: (typeof chain)[number] | undefined;
-        const num = Number.parseInt(arg, 10);
-        if (!Number.isNaN(num) && num >= 1 && num <= chain.length) {
-          leg = chain[num - 1];
-        } else {
-          leg = chain.find(
-            (l) => l.model === arg || `${l.provider}:${l.model}` === arg,
-          );
-        }
-
+        const leg = resolveSwitchTarget(chain, arg);
         if (!leg)
           return "Model not found. Use /model list to see your options.";
 
@@ -1870,6 +1870,19 @@ export class MercuryCoreRuntime {
         });
       } catch (err) {
         this.db.updateMessageRunMeta(userMessageId, userTurnRunMeta(undefined));
+        // Timeout kills the container mid-task with no assistant reply, so the
+        // next run's history would show an unanswered turn with no explanation.
+        // Record why, so the agent knows the run was cut off rather than
+        // guessing — workspace files written before the kill survive.
+        if (err instanceof ContainerError && err.reason === "timeout") {
+          this.db.addMessage(
+            spaceId,
+            "assistant",
+            "[System: this run was killed at the container time limit before replying. Partial work may exist in the workspace.]",
+            undefined,
+            userMessageId,
+          );
+        }
         throw err;
       }
 

package/src/core/system-messages.ts

@@ -8,8 +8,8 @@
  * space switch them to another locale via the `messages.locale` config key.
  *
  * Resolution chain: per-space → `@global` → `config.messagesLocale` → `"en"`.
- * The `en` strings are byte-identical to the original literals — tests and
- * downstream matching depend on them.
+ * The `en` strings are pinned byte-for-byte by tests — downstream matching
+ * depends on them, so change them deliberately and update the test together.
  */
 
 import type { AppConfig } from "../config.js";
@@ -63,7 +63,8 @@ export const SYSTEM_MESSAGES: Record<
     attachment_failed:
       "Could not use your attachment (media disabled, over the size limit, or download failed). Check MERCURY_MEDIA_ENABLED and logs.",
     run_stopped: "Stopped current run.",
-    container_timeout: "Container timed out.",
+    container_timeout:
+      "I ran out of time before finishing. Partial work may be saved in the workspace — ask me to continue.",
     container_oom: "Container was killed (possibly out of memory).",
     no_permission_prompt:
       "You don't have permission to use the agent in this group.",
@@ -114,7 +115,8 @@ export const SYSTEM_MESSAGES: Record<
     attachment_failed:
       "לא ניתן היה להשתמש בקובץ המצורף (מדיה מושבתת, חריגה ממגבלת הגודל, או שההורדה נכשלה). בדקו את MERCURY_MEDIA_ENABLED ואת הלוגים.",
     run_stopped: "הריצה הנוכחית הופסקה.",
-    container_timeout: "זמן הריצה של הקונטיינר פג.",
+    container_timeout:
+      "נגמר לי הזמן לפני שסיימתי. ייתכן שעבודה חלקית נשמרה בסביבת העבודה — בקשו ממני להמשיך.",
     container_oom: "הקונטיינר הופסק (ייתכן שבשל מחסור בזיכרון).",
     no_permission_prompt: "אין לכם הרשאה להשתמש בסוכן בקבוצה זו.",
     no_permission_slash: "אין לכם הרשאה להשתמש ב-'/{command}'.",