@axiom-lattice/core 6.4.0 → 6.4.1

package/dist/index.js

@@ -1929,6 +1929,7 @@ __export(index_exports, {
   globSearchFiles: () => globSearchFiles,
   grepMatchesFromFiles: () => grepMatchesFromFiles,
   grepSearchFiles: () => grepSearchFiles,
+  handlerResultText: () => handlerResultText,
   hasChunkBuffer: () => hasChunkBuffer,
   hasDelegatedWorkerToken: () => hasDelegatedWorkerToken,
   hasRuntimeCapabilityPolicy: () => hasRuntimeCapabilityPolicy,
@@ -15322,6 +15323,12 @@ function capResult(result, cap) {
   const serialized = typeof result === "string" ? result : JSON.stringify(result ?? null);
   return Buffer.byteLength(serialized, "utf8") <= cap ? result : truncate(serialized, cap);
 }
+function handlerResultText(result) {
+  const value = result.result;
+  if (typeof value === "string") return value;
+  if (value === void 0) return (result.stdout ?? "").trim();
+  return JSON.stringify(value);
+}
 function errorFromStdout(stdout) {
   let text = stdout;
   try {
@@ -16253,7 +16260,7 @@ function compileSandboxPlugin(args) {
               maxResultBytes: t.maxResultBytes
             });
             if (!result.ok) return result.error ?? "sandbox plugin execution failed";
-            const text = typeof result.result === "string" ? result.result : JSON.stringify(result.result ?? null);
+            const text = handlerResultText(result);
             const ref = t.ui ? { kind: "plugin", pluginType: manifest.type, resource: t.ui.resource, displayMode: t.ui.displayMode ?? "inline" } : null;
             return ref ? appendUiFence(text, ref) : text;
           },
@@ -16649,7 +16656,7 @@ var TenantPluginCatalog = class {
 // src/sandbox_plugin/sandboxPluginRuntime.ts
 var catalog = null;
 function buildResidentRouting() {
-  const baseUrl = process.env.MICROSANDBOX_SERVICE_URL;
+  const baseUrl = process.env.MICROSANDBOX_SERVICE_BASE_URL;
   if (!baseUrl) return void 0;
   return {
     getDeployment: async (tenantId2, pluginType) => await getPluginDeploymentService()?.getDeployment(tenantId2, pluginType) ?? void 0,
@@ -35469,7 +35476,9 @@ var MicrosandboxServiceClient = class {
         }
       } catch {
       }
-      throw new Error(`Microsandbox service request failed: ${detail}`);
+      const error = new Error(`Microsandbox service request failed: ${detail}`);
+      error.statusCode = response.status;
+      throw error;
     }
     const payload = await response.json();
     if (payload?.success === false) {
@@ -38918,6 +38927,7 @@ var OutboxPoller = class {
 };
 
 // src/services/ProjectMutationMutex.ts
+var import_node_async_hooks = require("async_hooks");
 var import_protocols28 = require("@axiom-lattice/protocols");
 
 // src/services/coordinationLease.ts
@@ -38987,16 +38997,24 @@ var ProjectMutationMutex = class {
   constructor() {
     this.queues = /* @__PURE__ */ new Map();
     this.active = /* @__PURE__ */ new Set();
+    /** Project keys already held by the current async context (reentrancy). */
+    this.held = new import_node_async_hooks.AsyncLocalStorage();
   }
   /** Runs one mutation after all earlier mutations for the same Tenant and Project. */
   async runExclusive(scope, operation, signal) {
     const key5 = projectKey(scope);
+    const inherited = this.held.getStore();
+    if (inherited?.has(key5)) return operation();
     const leaseKey = `project-mutation:${encodeURIComponent(scope.tenantId)}:${encodeURIComponent(scope.projectId)}`;
     await this.acquire(key5, signal);
+    const held = new Set(inherited);
+    held.add(key5);
     try {
-      const store = getCoordinationLeaseStore();
-      if (!store) return await operation();
-      return await withLease(store, leaseKey, getReplicaId(), operation, MUTATION_LEASE_OPTIONS);
+      return await this.held.run(held, async () => {
+        const store = getCoordinationLeaseStore();
+        if (!store) return await operation();
+        return await withLease(store, leaseKey, getReplicaId(), operation, MUTATION_LEASE_OPTIONS);
+      });
     } finally {
       this.release(key5);
     }
@@ -39070,6 +39088,7 @@ var INPUT_KEYS = [
 ];
 var REPLY_INPUT_KEYS = ["tenantId", "membershipId", "text", "sourceRoomMessageId", "inputMessageId", "sourceId", "idempotencyKey"];
 var INTERRUPT_INPUT_KEYS = ["tenantId", "membershipId", "text", "sourceRoomMessageId", "inputMessageId"];
+var CORRELATED_INTERRUPT_INPUT_KEYS = ["tenantId", "membershipId", "correlationKey", "text"];
 var RoomAgentMessageService = class {
   /**
    * Creates a room writer over the durable membership and message stores.
@@ -39117,6 +39136,50 @@ var RoomAgentMessageService = class {
       idempotencyKey: `room-interrupt:${snapshot.sourceRoomMessageId}:${snapshot.membershipId}:${sourceId}`
     });
   }
+  /**
+   * Persists a correlated HITL interrupt that has no human source message.
+   *
+   * @param input Explicit tenant, active membership, caller-supplied correlation key, and text.
+   * @returns A deep clone of the canonical idempotent room message.
+   * @remarks Business-agnostic: the caller owns the correlation key. Scope is
+   * validated against the durable membership; no source message is required.
+   */
+  postCorrelatedInterrupt(input) {
+    const snapshot = exactStringRecord(input, CORRELATED_INTERRUPT_INPUT_KEYS, "Invalid project room interrupt input");
+    return this.persistScoped({
+      tenantId: snapshot.tenantId,
+      membershipId: snapshot.membershipId,
+      text: snapshot.text,
+      sourceId: `interrupt:${snapshot.correlationKey}`,
+      idempotencyKey: `room-interrupt:${snapshot.membershipId}:${snapshot.correlationKey}`
+    });
+  }
+  async persistScoped(input) {
+    const text = input.text.trim();
+    if (text.length < 1 || text.length > 2e4) throw new Error("Invalid project room message text");
+    const member = snapshotMembership(await this.deps.memberships.findById(input.tenantId, input.membershipId));
+    if (!member || member.id !== input.membershipId || member.status !== "active" || member.tenantId !== input.tenantId) {
+      throw new Error("Invalid project room membership");
+    }
+    const candidate = {
+      id: (this.deps.idFactory ?? import_crypto8.randomUUID)(),
+      tenantId: member.tenantId,
+      workspaceId: member.workspaceId,
+      projectId: member.projectId,
+      roomId: member.roomId,
+      author: { type: "bot", membershipId: member.id, assistantId: member.assistantId },
+      content: { type: "text", text },
+      mentions: [],
+      source: "agent",
+      sourceId: input.sourceId,
+      idempotencyKey: input.idempotencyKey
+    };
+    const canonical = snapshotCanonicalScoped(await this.deps.messages.createIdempotent(candidate), candidate);
+    if (!canonical) throw new Error("Invalid canonical project room message");
+    const result = structuredClone(canonical);
+    this.notifyCommitted(result);
+    return result;
+  }
   async persistDerived(input) {
     const source = snapshotSource(await this.deps.messages.findById(input.tenantId, input.sourceRoomMessageId));
     if (!source || source.id !== input.sourceRoomMessageId || source.tenantId !== input.tenantId) throw new Error("Invalid project room message");
@@ -39272,6 +39335,27 @@ function snapshotCanonical(value, expected) {
     createdAt
   };
 }
+function snapshotCanonicalScoped(value, expected) {
+  const values = exactValues(value, ["id", "tenantId", "workspaceId", "projectId", "roomId", "author", "content", "mentions", "source", "sourceId", "idempotencyKey", "createdAt"], ["replyToMessageId"]);
+  const author = exactValues(values?.author, ["type", "membershipId", "assistantId"]);
+  const content = exactValues(values?.content, ["type", "text"]);
+  const createdAt = date(values?.createdAt);
+  if (!values || !createdAt || typeof values.id !== "string" || values.id.length === 0 || (0, import_protocols29.snapshotExactArray)(values.mentions)?.length !== 0 || author?.type !== "bot" || expected.author.type !== "bot" || author.membershipId !== expected.author.membershipId || author.assistantId !== expected.author.assistantId || content?.type !== "text" || content.text !== expected.content.text || values.tenantId !== expected.tenantId || values.workspaceId !== expected.workspaceId || values.projectId !== expected.projectId || values.roomId !== expected.roomId || values.source !== "agent" || values.sourceId !== expected.sourceId || values.idempotencyKey !== expected.idempotencyKey) return void 0;
+  return {
+    id: values.id,
+    tenantId: expected.tenantId,
+    workspaceId: expected.workspaceId,
+    projectId: expected.projectId,
+    roomId: expected.roomId,
+    author: { type: "bot", membershipId: expected.author.membershipId, assistantId: expected.author.assistantId },
+    content: { type: "text", text: expected.content.text },
+    mentions: [],
+    source: "agent",
+    sourceId: expected.sourceId,
+    idempotencyKey: expected.idempotencyKey,
+    createdAt
+  };
+}
 
 // src/services/ProjectTaskOwnerPolicy.ts
 var import_protocols30 = require("@axiom-lattice/protocols");
@@ -49141,6 +49225,18 @@ On top of that, add any of three combinable classes:
 ## Combinations
 A plugin is the SET of classes it needs, e.g. \`connection + tools + skills\` or \`UI + connection\`.
 
+## Scenarios \u2192 skills
+| Scenario | Read |
+|---|---|
+| Tool that returns/transforms data | \`sandbox-plugins-manifest\` + \`sandbox-plugins-handlers\` |
+| Skills-only (procedural knowledge, no tools) | \`sandbox-plugins-authoring\` (skills) |
+| Tool needs credentials / resource discovery | \`sandbox-plugins-connection\` |
+| Tool shows an interactive panel | \`sandbox-plugins-ui\` |
+| Tool orchestrates platform tools/agents | \`sandbox-plugins-consume-open\` |
+| Tool callable by external MCP clients | \`sandbox-plugins-expose\` |
+| Run as a long-lived resident service | \`sandbox-plugins-deploy\` |
+| Validate / test / debug | \`sandbox-plugins-testing\` |
+
 ## Agents (not a supported authoring path)
 The manifest schema accepts an \`agents\` block and tenant plugin agents are
 registered, but building agents this way is not supported or designed for tenant
@@ -49351,10 +49447,38 @@ lifecycle handshake:
    - \`ui/notifications/tool-result\` \u2192 a \`CallToolResult\` \`{ content: [{ type: "text", text }] }\` (the tool output text, with any \`mcp_app\` fence stripped).
 
 Register the \`message\` listener **before** \`ui/initialize\` so nothing is missed.
-The result carries **TEXT content only** \u2014 no \`structuredContent\` or \`artifact\`;
-parse the JSON yourself if the tool emitted JSON. To re-query or refresh, call
-\`tools/call\` from the View and render its response (the host does not re-push
-\`tool-result\` for your own calls).
+Read the payload from \`params.content[0].text\` \u2014 the notification is a
+\`CallToolResult\`, **not** your handler payload at the top level. The result
+carries **TEXT content only** \u2014 no \`structuredContent\` or \`artifact\`; parse the
+JSON yourself if the tool emitted JSON (it is the handler's \`result\`, so the
+handler must wrap it under \`result\`). To re-query or refresh, call \`tools/call\`
+from the View and render its response (the host does not re-push \`tool-result\`
+for your own calls).
+
+When you call \`tools/call\` from the View, the JSON-RPC response \`result\` is the
+handler's own \`result\` value **directly** \u2014 it is **not wrapped in a**
+\`CallToolResult\` \`{ content: [...] }\` (that wrapper is only used for the host's
+\`tool-result\` push). Parse it as your tool's data.
+
+## Push vs re-execute (key for debugging)
+The host pushes \`tool-result\` from the tool result **recorded when the agent ran** \u2014
+it does **not** re-execute the handler. The push therefore always reflects that
+run's output (and the handler's \`result\` at that time). A \`tools/call\` from the
+View, by contrast, **re-executes** the handler live every time.
+
+So if the push looks stale/wrong but a fresh \`tools/call\` returns the right data,
+the recorded run predates your change \u2014 re-run the tool (a new agent call) to get
+a fresh push. Do not assume the push re-reads the handler.
+
+## Self-check / debug
+- Log the raw frame: \`console.log(JSON.stringify(ev.data))\` in the \`message\`
+  listener, and open the browser console inside the sandboxed frame.
+- If the pushed text looks like the raw handler envelope (e.g. it starts with
+  \`{"ok":true,...\`), the handler omitted the \`result\` wrapper \u2014 the host falls
+  back to the raw stdout instead of your payload. Fix the handler (see
+  \`sandbox-plugins-handlers\`).
+- The push only happens after \`ui/initialize\` **and**
+  \`ui/notifications/initialized\`; a listener registered later misses it.
 
 \`templates/ui.html\` implements all of this in vanilla JS and renders both payloads
 into a \`#data\` element.
@@ -49474,6 +49598,76 @@ Templates: see \`sandbox-plugins-manifest\` for the exact \`tools[]\` fields; th
 \`templates/plugin.json\` already includes \`"expose": true\` (the tool is grantable via
 an API key but not callable until a key grants it). Remove it for tools that should
 not be externally grantable at all.
+`,
+    resources: {}
+  },
+  "sandbox-plugins-consume-open": {
+    version: "1.0.0",
+    content: `---
+name: sandbox-plugins-consume-open
+description: Call the platform's Open MCP surface from a tenant plugin handler (discover and invoke other tools/agents). Trigger: a plugin tool must orchestrate platform capabilities, call another tool or agent, or reuse an existing capability instead of re-implementing it.
+---
+
+# Calling the platform from a handler (Open MCP)
+
+A plugin handler can call **the platform's own tools and agents** through the Open
+MCP endpoint. Reach for this when a tool should orchestrate existing capabilities
+(read the knowledge base, create a task, invoke an agent) instead of
+re-implementing them.
+
+## What the handler gets
+When the gateway injects the credential, each handler process starts with:
+- \`API_GATEWAY_URL\` \u2014 the gateway base URL.
+- \`OPEN_API_TOKEN\` \u2014 a short-lived bearer **scoped to this tenant's plugin callers**.
+
+If the deployment does not inject them (no \`PUBLIC_GATEWAY_URL\`), the variables are
+**absent** \u2014 detect that and degrade gracefully (report "platform tools
+unavailable") rather than crashing.
+
+## Discover, then call
+Never hardcode the tool list: the callable set is **reflected per tenant** and
+changes as plugins are exposed. Call \`listTools()\` at runtime.
+\`\`\`js
+const { OpenMcpClient } = require("@axiom-lattice/open-mcp-client");
+// or require("/root/.agents/sdk/open-mcp-client/index.js") when provisioned there
+
+async function main() {
+  const input = process.env.PLUGIN_INPUT_FILE
+    ? JSON.parse(require("fs").readFileSync(process.env.PLUGIN_INPUT_FILE, "utf8"))
+    : JSON.parse(process.env.PLUGIN_INPUT || "{}");
+
+  const client = OpenMcpClient.fromEnv(); // API_GATEWAY_URL + OPEN_API_TOKEN
+  const tools = await client.listTools(); // exactly what this handler may call
+  const kb = await client.callTool("kb_search", { collection: "docs", query: input.q });
+
+  process.stdout.write(JSON.stringify({ ok: true, result: kb }));
+}
+main().catch((err) => {
+  process.stdout.write(JSON.stringify({ ok: false, error: String(err && err.message ? err.message : err) }));
+});
+\`\`\`
+
+- Tool names are \`{domain}_{action}\` (e.g. \`kb_search\`, \`task_manage_task\`).
+- Args follow the tool's \`inputSchema\`; \`listTools()\` returns name/description.
+- Return the result through the normal handler envelope (\`{ ok: true, result }\`)
+  so it becomes this tool's output \u2014 see \`sandbox-plugins-handlers\`.
+
+## What the handler may call
+The token carries the conservative sandbox defaults (\`sandbox_*\`, \`kb_search\`)
+**plus the tenant's grantable Open catalog**: every exposed tenant/global plugin
+tool and the tenant's agents. A call outside that set fails (tool-not-found or
+\`GRANT_DENIED\`); retrying will not help.
+
+## Client availability
+The zero-dependency \`@axiom-lattice/open-mcp-client\` must be present in the
+sandbox: preinstalled in the image, at \`/root/.agents/sdk/open-mcp-client\`, or
+installed in this run (\`npm install @axiom-lattice/open-mcp-client\`). The CLI is
+also available: \`npx @axiom-lattice/open-mcp-client tools list --json\`.
+
+## Limits
+- Nested sandbox orchestration is depth-limited (5); past the cap no token is
+  re-issued, so deep recursion fails fast.
+- Only call what \`listTools()\` returns, and handle a missing tool gracefully.
 `,
     resources: {}
   },
@@ -49514,10 +49708,23 @@ for the single/first connection, or \`data.connections\` (entries of
 \`{ key, config }\`) when the plugin selects multiple connections.
 
 ## Writing output
-Print a JSON envelope to stdout:
+Every tool handler must print **one** JSON envelope to stdout, with your payload
+under \`result\`:
 \`\`\`js
-process.stdout.write(JSON.stringify({ ok: true, result: "done" }));
+process.stdout.write(JSON.stringify({ ok: true, result: <payload> }));
 \`\`\`
+
+> **The payload MUST go under \`result\`.** \`result\` may be any JSON value
+> (object, array, string, number).
+> \`\`\`js
+> // \u2705 correct \u2014 data under \`result\`
+> process.stdout.write(JSON.stringify({ ok: true, result: { tasks, count } }));
+>
+> // \u274C wrong \u2014 \`result\` missing; the host surfaces the raw stdout (this
+> //    envelope), so callers and MCP App UIs never see \`tasks\`
+> process.stdout.write(JSON.stringify({ ok: true, tasks, count }));
+> \`\`\`
+
 Non-JSON stdout is treated as a plain-text result. To fail, either print
 \`{ ok: false, error }\` or exit non-zero (stderr is not required; stdout is
 captured).
@@ -49703,6 +49910,8 @@ Follow the authoring skill's "Decide first" steps to confirm the goal
 (inputs/outputs). If the UI class applies, load "sandbox-plugins-ui" before
 authoring it. If the tool must be callable by external MCP clients via an API key,
 load "sandbox-plugins-expose" and follow it (\`expose: true\` + key grants).
+If a tool must call the platform's own tools/agents from its handler, load
+"sandbox-plugins-consume-open".
 
 Plan with persistent Tasks: MANDATORY until you load "task-tracking" with the
 \`skill\` tool, call neither \`manage_task\` nor any other task operation. Use
@@ -49909,7 +50118,6 @@ var SANDBOX_PLUGINS_UI_REF = {
   resource: SANDBOX_PLUGINS_UI_RESOURCE,
   displayMode: "inline"
 };
-var PLUGIN_BUILDER_SKILLS = [...Object.keys(SANDBOX_PLUGIN_SKILLS), "task-tracking"];
 function tenantIdFrom(exeConfig) {
   const c = exeConfig;
   return c?.configurable?.runConfig?.tenantId ?? "default";
@@ -50025,9 +50233,9 @@ var sandboxPluginsPlugin = {
           id: "skill",
           type: "skill",
           name: "Skill",
-          description: "Load the sandbox-plugins authoring, patterns, manifest, handler, connection, UI, and testing skills",
+          description: "Load any available skill, including the sandbox-plugins authoring, patterns, manifest, handler, connection, UI, and testing skills",
           enabled: true,
-          config: { readAll: false, skills: PLUGIN_BUILDER_SKILLS }
+          config: { readAll: true }
         },
         {
           id: "task",
@@ -50208,7 +50416,7 @@ var sandboxPluginsPlugin = {
                     assistantId: typeof runCfg.assistant_id === "string" ? runCfg.assistant_id : void 0
                   }
                 });
-                return JSON.stringify(redactSecretValues(result, secrets));
+                return handlerResultText(redactSecretValues(result, secrets));
               } catch (err) {
                 return JSON.stringify(redactSecretValues({ ok: false, error: errorText(err) }, secrets));
               }
@@ -51593,6 +51801,7 @@ registerBuiltinPlugins();
   globSearchFiles,
   grepMatchesFromFiles,
   grepSearchFiles,
+  handlerResultText,
   hasChunkBuffer,
   hasDelegatedWorkerToken,
   hasRuntimeCapabilityPolicy,