@sonenta/mcp 0.36.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 });
           }
         }
@@ -16904,6 +16904,19 @@ 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}`);
@@ -16927,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");
@@ -19429,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, {
@@ -19441,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"]);
@@ -19480,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]);
@@ -19997,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 };
@@ -20089,7 +20270,7 @@ var init_server3 = __esm({
     init_errors3();
     init_helpers2();
     init_registry();
-    VERSION = "0.35.0";
+    VERSION = "0.37.0";
   }
 });