@sonenta/mcp 0.35.0 → 0.37.0

package/README.md

@@ -2,7 +2,7 @@
 
 Model Context Protocol server for **Sonenta** translation management — **pure TypeScript**, no Python, no `uv`, no bundled wheel. Runs on Node ≥18.
 
-Wires Claude Desktop and other MCP clients into your Sonenta project's keys, translations, accessibility surfaces, source-health, and glossary tools.
+Wires Claude Desktop and other MCP clients into your Sonenta project's keys, translations, accessibility surfaces, source-health, and glossary tools — plus **agent-observability** tools (`session_start` / `annotate` / `human_needed` / `session_end`) that surface an agent's run as a live, timestamped thread in the Sonenta dashboard.
 
 ## Use
 

package/bin/sonenta-mcp.js

@@ -8388,21 +8388,21 @@ var init_protocol = __esm({
        * the error appropriately (e.g., by failing the task, logging, etc.). The Protocol layer
        * simply propagates the error.
        */
-      async _enqueueTaskMessage(taskId, message, sessionId) {
+      async _enqueueTaskMessage(taskId, message, sessionId2) {
         if (!this._taskStore || !this._taskMessageQueue) {
           throw new Error("Cannot enqueue task message: taskStore and taskMessageQueue are not configured");
         }
         const maxQueueSize = this._options?.maxTaskQueueSize;
-        await this._taskMessageQueue.enqueue(taskId, message, sessionId, maxQueueSize);
+        await this._taskMessageQueue.enqueue(taskId, message, sessionId2, maxQueueSize);
       }
       /**
        * Clears the message queue for a task and rejects any pending request resolvers.
        * @param taskId The task ID whose queue should be cleared
        * @param sessionId Optional session ID for binding the operation to a specific session
        */
-      async _clearTaskQueue(taskId, sessionId) {
+      async _clearTaskQueue(taskId, sessionId2) {
         if (this._taskMessageQueue) {
-          const messages = await this._taskMessageQueue.dequeueAll(taskId, sessionId);
+          const messages = await this._taskMessageQueue.dequeueAll(taskId, sessionId2);
           for (const message of messages) {
             if (message.type === "request" && isJSONRPCRequest(message.message)) {
               const requestId = message.message.id;
@@ -8445,7 +8445,7 @@ var init_protocol = __esm({
           }, { once: true });
         });
       }
-      requestTaskStore(request, sessionId) {
+      requestTaskStore(request, sessionId2) {
         const taskStore = this._taskStore;
         if (!taskStore) {
           throw new Error("No task store configured");
@@ -8458,18 +8458,18 @@ var init_protocol = __esm({
             return await taskStore.createTask(taskParams, request.id, {
               method: request.method,
               params: request.params
-            }, sessionId);
+            }, sessionId2);
           },
           getTask: async (taskId) => {
-            const task = await taskStore.getTask(taskId, sessionId);
+            const task = await taskStore.getTask(taskId, sessionId2);
             if (!task) {
               throw new McpError(ErrorCode.InvalidParams, "Failed to retrieve task: Task not found");
             }
             return task;
           },
           storeTaskResult: async (taskId, status, result) => {
-            await taskStore.storeTaskResult(taskId, status, result, sessionId);
-            const task = await taskStore.getTask(taskId, sessionId);
+            await taskStore.storeTaskResult(taskId, status, result, sessionId2);
+            const task = await taskStore.getTask(taskId, sessionId2);
             if (task) {
               const notification = TaskStatusNotificationSchema.parse({
                 method: "notifications/tasks/status",
@@ -8482,18 +8482,18 @@ var init_protocol = __esm({
             }
           },
           getTaskResult: (taskId) => {
-            return taskStore.getTaskResult(taskId, sessionId);
+            return taskStore.getTaskResult(taskId, sessionId2);
           },
           updateTaskStatus: async (taskId, status, statusMessage) => {
-            const task = await taskStore.getTask(taskId, sessionId);
+            const task = await taskStore.getTask(taskId, sessionId2);
             if (!task) {
               throw new McpError(ErrorCode.InvalidParams, `Task "${taskId}" not found - it may have been cleaned up`);
             }
             if (isTerminal(task.status)) {
               throw new McpError(ErrorCode.InvalidParams, `Cannot update task "${taskId}" from terminal status "${task.status}" to "${status}". Terminal states (completed, failed, cancelled) cannot transition to other states.`);
             }
-            await taskStore.updateTaskStatus(taskId, status, statusMessage, sessionId);
-            const updatedTask = await taskStore.getTask(taskId, sessionId);
+            await taskStore.updateTaskStatus(taskId, status, statusMessage, sessionId2);
+            const updatedTask = await taskStore.getTask(taskId, sessionId2);
             if (updatedTask) {
               const notification = TaskStatusNotificationSchema.parse({
                 method: "notifications/tasks/status",
@@ -8506,7 +8506,7 @@ var init_protocol = __esm({
             }
           },
           listTasks: (cursor) => {
-            return taskStore.listTasks(cursor, sessionId);
+            return taskStore.listTasks(cursor, sessionId2);
           }
         };
       }
@@ -15724,8 +15724,8 @@ var init_server2 = __esm({
         this._serverInfo = _serverInfo;
         this._loggingLevels = /* @__PURE__ */ new Map();
         this.LOG_LEVEL_SEVERITY = new Map(LoggingLevelSchema.options.map((level, index) => [level, index]));
-        this.isMessageIgnored = (level, sessionId) => {
-          const currentLevel = this._loggingLevels.get(sessionId);
+        this.isMessageIgnored = (level, sessionId2) => {
+          const currentLevel = this._loggingLevels.get(sessionId2);
           return currentLevel ? this.LOG_LEVEL_SEVERITY.get(level) < this.LOG_LEVEL_SEVERITY.get(currentLevel) : false;
         };
         this._capabilities = options?.capabilities ?? {};
@@ -16068,9 +16068,9 @@ var init_server2 = __esm({
        * @param params
        * @param sessionId optional for stateless and backward compatibility
        */
-      async sendLoggingMessage(params, sessionId) {
+      async sendLoggingMessage(params, sessionId2) {
         if (this._capabilities.logging) {
-          if (!this.isMessageIgnored(params.level, sessionId)) {
+          if (!this.isMessageIgnored(params.level, sessionId2)) {
             return this.notification({ method: "notifications/message", params });
           }
         }
@@ -16873,7 +16873,7 @@ async function unpack(res) {
     const text2 = await res.text().catch(() => "");
     let body = text2;
     try {
-      body = JSON.parse(text2);
+      body = parse3(text2);
     } catch {
     }
     throw new SonentaApiError(res.status, body);
@@ -16904,12 +16904,32 @@ var init_client = __esm({
         this.config = config3;
       }
       config;
+      /**
+       * Active agent-observability session (contract §0). Set by `session_start`;
+       * while non-null it is attached as `X-MCP-Session-Id` to EVERY subsequent MCP
+       * request so the backend can auto-attach captured mutations to the thread.
+       * Cleared by `session_end` so later calls don't bind to a closed session.
+       */
+      sessionId = null;
+      setSession(id) {
+        this.sessionId = id;
+      }
+      clearSession() {
+        this.sessionId = null;
+      }
       buildUrl(path, params) {
         const base = this.config.apiBase.replace(/\/+$/, "");
         const url = new URL(`${base}${path}`);
         if (params) {
           for (const [k, v] of Object.entries(params)) {
-            if (v !== void 0 && v !== null) url.searchParams.set(k, String(v));
+            if (v === void 0 || v === null) continue;
+            if (Array.isArray(v)) {
+              for (const item of v) {
+                if (item !== void 0 && item !== null) url.searchParams.append(k, String(item));
+              }
+            } else {
+              url.searchParams.set(k, String(v));
+            }
           }
         }
         return url.toString();
@@ -16920,6 +16940,7 @@ var init_client = __esm({
           "User-Agent": this.config.userAgent,
           Accept: "application/json"
         });
+        if (this.sessionId) headers.set("X-MCP-Session-Id", this.sessionId);
         const init = { method, headers };
         if (opts.json !== void 0) {
           headers.set("Content-Type", "application/json");
@@ -17053,6 +17074,7 @@ function pyRepr(v) {
   if (v === null || v === void 0) return "None";
   if (v === true) return "True";
   if (v === false) return "False";
+  if (isLosslessNumber(v)) return v.toString();
   if (typeof v === "number") return String(v);
   if (typeof v === "string") {
     const esc2 = v.replace(/\\/g, "\\\\");
@@ -17079,6 +17101,7 @@ var ToolValidationError, ValueError;
 var init_errors3 = __esm({
   "src/errors.ts"() {
     "use strict";
+    init_esm2();
     init_client();
     ToolValidationError = class extends Error {
       constructor(message) {
@@ -18207,6 +18230,17 @@ var init_schemas_generated = __esm({
               "minimum": 1,
               "maximum": 200,
               "default": 50
+            },
+            "name_prefix": {
+              "type": "string",
+              "description": 'Return only keys whose name starts with this prefix \u2014 a cheap scoped lookup (e.g. name_prefix="nav.").'
+            },
+            "key_uuids": {
+              "type": "array",
+              "items": {
+                "type": "string"
+              },
+              "description": "Return only these specific keys, by UUID (repeated query param). Use for a cheap targeted fetch of a known set of keys."
             }
           },
           "additionalProperties": false
@@ -18289,7 +18323,7 @@ var init_schemas_generated = __esm({
         }
       },
       "list_source_duplicates": {
-        "description": "List groups of keys that SHARE an identical source-language value (Source Health duplicates, #1116). Each group = {source_value, key_count, key_names[], key_uuids[], status, note}. Duplicates inflate translation cost and drift (the same string translated N ways), so this is the worklist the sonenta-source-health agent repairs. Status is tracked PROJECT-WIDE per source_value: to_fix (needs attention; the default), allowed (intentional duplicate \u2014 listed+flagged but excluded from total_issues), resolved (already fixed \u2014 re-scan confirms). Filter by status to focus. When status=to_fix, a group may also carry a human-prepared `merge_plan` ({clusters: [{canonical_key_uuid, redundant_key_uuids[]}], survivor_outcome: allowed|differentiate}) authored in the dashboard \u2014 the consolidation an agent applies (merge each cluster onto its canonical key, then allow or differentiate whatever still shares the text). READ-ONLY.",
+        "description": "List groups of keys that SHARE an identical source-language value (Source Health duplicates, #1116). PAGINATED: returns an envelope {items, total, offset, limit, has_more} \u2014 read `.items` (each group = {source_value, key_count, key_names[], key_uuids[], status, note}) and page with offset/limit (default 50, max 200) until has_more is false. Duplicates inflate translation cost and drift (the same string translated N ways), so this is the worklist the sonenta-source-health agent repairs. Status is tracked PROJECT-WIDE per source_value: neutral (UNTRIAGED \u2014 the default for a freshly-detected duplicate; this is the batch auto-diagnostic backlog), to_fix (triaged for fixing \u2014 carries a merge_plan to apply), allowed (intentional duplicate \u2014 listed+flagged but excluded from total_issues), resolved (already fixed \u2014 re-scan confirms). Filter by status to focus (e.g. status=neutral for the untriaged backlog). A to_fix group carries a human- or agent-prepared `merge_plan` ({clusters: [{canonical_key_uuid, redundant_key_uuids[]}], survivor_outcome: allowed|differentiate}) \u2014 the consolidation an agent applies (merge each cluster onto its canonical key, then allow or differentiate whatever still shares the text). READ-ONLY.",
         "inputSchema": {
           "type": "object",
           "properties": {
@@ -18300,15 +18334,29 @@ var init_schemas_generated = __esm({
             "status": {
               "type": "string",
               "enum": [
-                "to_fix",
+                "neutral",
                 "allowed",
+                "to_fix",
                 "resolved"
               ],
-              "description": "Filter to duplicate groups in this triage status. Omit for all."
+              "description": "Filter to duplicate groups in this triage status: neutral (untriaged \u2014 the default), to_fix (triaged, carries a merge_plan), allowed (intentional), resolved (fixed). Omit for all."
             },
             "version_id": {
               "type": "string",
               "description": "Optional version UUID; defaults to the production version."
+            },
+            "offset": {
+              "type": "integer",
+              "minimum": 0,
+              "default": 0,
+              "description": "Pagination offset (0-based). Default 0."
+            },
+            "limit": {
+              "type": "integer",
+              "minimum": 1,
+              "maximum": 200,
+              "default": 50,
+              "description": "Max groups per page (1..200). Default 50."
             }
           },
           "additionalProperties": false
@@ -19395,6 +19443,125 @@ var init_schemas_generated = __esm({
   }
 });
 
+// src/tools/schemas.observability.ts
+var PROJECT_UUID, SESSION_ID, OBSERVABILITY_SCHEMAS, OBSERVABILITY_TOOL_NAMES;
+var init_schemas_observability = __esm({
+  "src/tools/schemas.observability.ts"() {
+    "use strict";
+    PROJECT_UUID = {
+      type: "string",
+      description: "Project UUID. Required when multiple projects are configured (SONENTA_PROJECTS); defaults to the single configured project otherwise."
+    };
+    SESSION_ID = {
+      type: "string",
+      description: "Agent session id returned by session_start. Optional: defaults to this server's active session, so you normally omit it after calling session_start."
+    };
+    OBSERVABILITY_SCHEMAS = {
+      session_start: {
+        description: "Open an observability session so your work shows up as a live, timestamped thread in the Sonenta dashboard. Call this ONCE at the very start of a task, before touching anything. After it returns, every later MCP call you make is automatically attached to this session's thread (no extra wiring) \u2014 so real mutations (keys created, translations proposed, variants set\u2026) are captured even if you never call annotate. Returns {session_id, status, channel}. Idempotent per (project, session_ref) while a running session with that ref exists. Observability is always free (0 credits).",
+        inputSchema: {
+          type: "object",
+          properties: {
+            project_uuid: PROJECT_UUID,
+            agent: {
+              type: "string",
+              description: "Stable agent label shown in the dashboard thread, e.g. 'sonenta-source-health' or 'sonenta-a11y'. Use your own agent name."
+            },
+            title: {
+              type: "string",
+              description: "Optional one-line human-readable title for this run, e.g. 'Repair placeholder drift'."
+            },
+            session_ref: {
+              type: "string",
+              description: "Optional client idempotency key; reusing it while a session is still running returns that same session."
+            },
+            metadata: {
+              type: "object",
+              description: "Optional opaque object echoed back in the session detail (free-form run context)."
+            }
+          },
+          required: ["agent"]
+        }
+      },
+      annotate: {
+        description: "Append one readable line to the current session's thread \u2014 a human-facing step summary, NOT structured data. Use it to narrate what you are doing at a level a project owner can follow ('Found 12 keys with fr placeholder drift; repairing'). Optional; the thread stays faithful without it because real mutations are auto-captured. Free (0 credits).",
+        inputSchema: {
+          type: "object",
+          properties: {
+            project_uuid: PROJECT_UUID,
+            session_id: SESSION_ID,
+            summary: {
+              type: "string",
+              description: "The readable one-line step summary to append to the thread."
+            },
+            level: {
+              type: "string",
+              enum: ["info", "warning"],
+              default: "info",
+              description: "info for normal progress; warning to flag something the human should notice."
+            },
+            payload: {
+              type: "object",
+              description: "Optional structured detail rendered when the line is expanded in the dashboard."
+            }
+          },
+          required: ["summary"]
+        }
+      },
+      human_needed: {
+        description: "Raise a decision you are waiting on a human for \u2014 it appears as a todo in the dashboard and pauses that branch of work until a person resolves it. Use this the moment you hit a choice that is the founder's to make (never guess a business rule): merge vs keep-separate, an ambiguous source, an irreversible action. Provide clear options when there is a discrete set. Free (0 credits).",
+        inputSchema: {
+          type: "object",
+          properties: {
+            project_uuid: PROJECT_UUID,
+            session_id: SESSION_ID,
+            question: {
+              type: "string",
+              description: `The decision, phrased for a human, e.g. "Merge duplicate 'Save' keys or keep them separate?".`
+            },
+            detail: {
+              type: "string",
+              description: "Optional context that helps the human decide."
+            },
+            deep_link: {
+              type: "string",
+              description: "Optional relative dashboard path to the thing needing attention; defaults to the session thread."
+            },
+            options: {
+              type: "array",
+              items: { type: "string" },
+              description: "Optional suggested choices, e.g. ['merge', 'keep separate']."
+            }
+          },
+          required: ["question"]
+        }
+      },
+      session_end: {
+        description: "Close the current observability session when the task is done (or aborted). Records a closing line, marks the thread ended, and triggers the opt-in end-of-session email to project devs. After this, later MCP calls no longer attach to this session. Idempotent \u2014 ending an already-ended session is a no-op. Free (0 credits).",
+        inputSchema: {
+          type: "object",
+          properties: {
+            project_uuid: PROJECT_UUID,
+            session_id: SESSION_ID,
+            summary: {
+              type: "string",
+              description: "Optional closing line, e.g. 'Repaired 12 keys, 1 decision pending'."
+            },
+            status: {
+              type: "string",
+              enum: ["ended", "aborted"],
+              default: "ended",
+              description: "ended for a normal finish; aborted if you stopped early."
+            }
+          },
+          required: []
+        }
+      }
+    };
+    OBSERVABILITY_TOOL_NAMES = Object.keys(OBSERVABILITY_SCHEMAS);
+  }
+});
+
 // src/tools/registry.ts
 var registry_exports = {};
 __export(registry_exports, {
@@ -19407,6 +19574,14 @@ function copyPresent(body, args, keys) {
 function copyTruthy(target, args, keys) {
   for (const k of keys) if (args[k]) target[k] = args[k];
 }
+function sessionId(args, client) {
+  const explicit = args["session_id"];
+  if (explicit) return str(explicit);
+  if (client.sessionId) return client.sessionId;
+  throw new ToolValidationError(
+    "session_id is required (call session_start first, or pass session_id explicitly)"
+  );
+}
 function a11yReportParams(args) {
   const params = {};
   if (args["version_id"]) params["version_id"] = str(args["version_id"]);
@@ -19446,6 +19621,7 @@ var init_registry = __esm({
     init_errors3();
     init_helpers2();
     init_schemas_generated();
+    init_schemas_observability();
     A11Y_SURFACES = ["aria_label", "alt_text", "screen_reader", "plain_language"];
     has = (args, k) => k in args;
     truthy = (args, k) => Boolean(args[k]);
@@ -19474,6 +19650,8 @@ var init_registry = __esm({
           namespace: args["namespace"],
           language_code: args["language_code"],
           status_filter: args["status_filter"],
+          name_prefix: args["name_prefix"],
+          key_uuids: Array.isArray(args["key_uuids"]) ? args["key_uuids"] : void 0,
           include_glossary_hints: truthy(args, "include_glossary_hints") ? "true" : void 0,
           cursor: args["cursor"],
           limit: args["limit"] ?? 50
@@ -19893,7 +20071,9 @@ var init_registry = __esm({
         const p = resolveProjectUuid(args, client);
         const params = {
           status: args["status"],
-          version_id: args["version_id"]
+          version_id: args["version_id"],
+          offset: args["offset"],
+          limit: args["limit"]
         };
         return client.get(`/v1/mcp/projects/${p}/source-duplicates`, params);
       },
@@ -19959,9 +20139,48 @@ var init_registry = __esm({
         let url = `/v1/mcp/projects/${p}/source-duplicates/propose-plan`;
         if (args["version_id"]) url += `?version_id=${str(args["version_id"])}`;
         return client.post(url, body);
+      },
+      // ---- agent observability (contract v1, task 1611) ----
+      async session_start(args, client) {
+        const p = resolveProjectUuid(args, client);
+        if (!truthy(args, "agent")) throw new ToolValidationError("agent is required");
+        const body = { agent: args["agent"] };
+        copyPresent(body, args, ["title", "session_ref", "metadata"]);
+        const data = await client.post(`/v1/mcp/projects/${p}/agent/sessions`, body);
+        const sid = data?.["session_id"];
+        if (typeof sid === "string" && sid) client.setSession(sid);
+        return data;
+      },
+      async annotate(args, client) {
+        const p = resolveProjectUuid(args, client);
+        const sid = sessionId(args, client);
+        if (!truthy(args, "summary")) throw new ToolValidationError("summary is required");
+        const body = { summary: args["summary"] };
+        copyPresent(body, args, ["level", "payload"]);
+        return client.post(`/v1/mcp/projects/${p}/agent/sessions/${sid}/annotate`, body);
+      },
+      async human_needed(args, client) {
+        const p = resolveProjectUuid(args, client);
+        const sid = sessionId(args, client);
+        if (!truthy(args, "question")) throw new ToolValidationError("question is required");
+        const body = { question: args["question"] };
+        copyPresent(body, args, ["detail", "deep_link", "options"]);
+        return client.post(`/v1/mcp/projects/${p}/agent/sessions/${sid}/human-needed`, body);
+      },
+      async session_end(args, client) {
+        const p = resolveProjectUuid(args, client);
+        const sid = sessionId(args, client);
+        const body = {};
+        copyPresent(body, args, ["summary", "status"]);
+        const data = await client.post(`/v1/mcp/projects/${p}/agent/sessions/${sid}/end`, body);
+        if (client.sessionId === sid) client.clearSession();
+        return data;
       }
     };
-    TOOLS = Object.entries(SCHEMAS).map(([name, schema]) => {
+    TOOLS = Object.entries({
+      ...SCHEMAS,
+      ...OBSERVABILITY_SCHEMAS
+    }).map(([name, schema]) => {
       const handler = HANDLERS[name];
       if (!handler) throw new Error(`registry: no handler ported for tool '${name}'`);
       return { name, description: schema.description, inputSchema: schema.inputSchema, handler };
@@ -20051,7 +20270,7 @@ var init_server3 = __esm({
     init_errors3();
     init_helpers2();
     init_registry();
-    VERSION = "0.35.0";
+    VERSION = "0.37.0";
   }
 });