@topolo/mcp 0.13.3 → 0.14.2

package/README.md

@@ -145,6 +145,7 @@ deletion, encryption, and audit storage for the data they own.
 | `topolo_prepare_action`      | credential-scoped     | no               |
 | `topolo_read_action`         | catalog or target policy | no            |
 | `topolo_call_action`         | catalog or target policy | yes           |
+| `topolo_run_agent`           | Agent runtime policy    | yes              |
 | `topolo_upload_action`       | catalog or target policy | yes           |
 | `topolo_list_workspaces`     | target app runtime policy | no            |
 | `topolo_create_workspace`    | target app runtime policy | yes           |
@@ -194,6 +195,13 @@ personal or organization context. This lets agents address many workspaces
 independently; providing only one of the pair is rejected before the request is
 sent.
 
+`topolo_run_agent` is the bounded external-harness path for Codex, Claude, and
+other MCP clients. It creates or replays one invocation using the caller's
+stable `idempotencyKey`, polls the same invocation, and returns either its
+terminal result or `state: "approval_required"` with the exact Topolo
+verification URL. Calling it again with the same input resumes the durable
+invocation instead of starting duplicate work.
+
 ## Safety rails
 
 - **No `orgId` parameter** on any tool. The organization is derived entirely

package/dist/dispatch.js

@@ -65,6 +65,8 @@ function publicMcpErrorMessage(error, fallback) {
 
 // src/tools.ts
 var HTTP_METHODS = ["GET", "POST", "PUT", "PATCH", "DELETE"];
+var AGENT_INVOCATIONS_CREATE = "app_topolo_agent.agent_invocations.create";
+var AGENT_INVOCATIONS_GET = "app_topolo_agent.agent_invocations.get";
 function requiredString(args, name) {
   const value = typeof args[name] === "string" ? args[name].trim() : "";
   if (!value) throw new TopoloMcpPublicError(`${name} is required.`);
@@ -104,6 +106,40 @@ function coerceObjectParam(value, name) {
   }
   return candidate;
 }
+function recordValue(value) {
+  return value && typeof value === "object" && !Array.isArray(value) ? value : null;
+}
+function invocationFrom(value) {
+  const invocation = recordValue(recordValue(value)?.["invocation"]);
+  if (!invocation || typeof invocation["invocationId"] !== "string") {
+    throw new TopoloMcpPublicError("Topolo Agent returned an invalid invocation response.");
+  }
+  return invocation;
+}
+function agentRunResult(invocation) {
+  const status = typeof invocation["status"] === "string" ? invocation["status"] : "running";
+  const terminal = invocation["terminal"] === true;
+  const approval = recordValue(invocation["approval"]);
+  if (status === "awaiting_approval" && approval) {
+    return {
+      state: "approval_required",
+      invocationId: invocation["invocationId"],
+      verificationUrl: approval["verificationUrl"],
+      continuation: {
+        tool: "topolo_run_agent",
+        reuseSameInvocation: true,
+        arguments: { waitForApproval: true, waitSeconds: 120 }
+      },
+      approval,
+      invocation
+    };
+  }
+  return {
+    state: terminal ? status : "running",
+    invocationId: invocation["invocationId"],
+    invocation
+  };
+}
 var TOOLS = [
   {
     name: "topolo_whoami",
@@ -351,6 +387,70 @@ var TOOLS = [
       );
     }
   },
+  {
+    name: "topolo_run_agent",
+    title: "Run a Topolo agent to a durable checkpoint",
+    description: "Creates or replays one idempotent Topolo Agent invocation, polls its published status, and returns either the terminal result or an approval_required handoff with the exact Topolo verification URL. Reusing the same idempotencyKey never starts a duplicate invocation. After showing the verification URL, immediately call this tool again with the same invocation and waitForApproval=true so the terminal result returns here.",
+    requiredScopes: [],
+    destructive: true,
+    inputSchema: {
+      type: "object",
+      properties: {
+        invocation: {
+          type: "object",
+          description: "Input for app_topolo_agent.agent_invocations.create, including a stable idempotencyKey.",
+          additionalProperties: true
+        },
+        resourceType: { type: "string", description: "Optional resource-scoping alias for the Agent workspace." },
+        resourceId: { type: "string", description: "Resource id. Required when resourceType is provided." },
+        waitSeconds: {
+          type: "integer",
+          minimum: 0,
+          maximum: 120,
+          default: 30,
+          description: "Maximum time to poll. Returns state=running when the bounded wait elapses."
+        },
+        waitForApproval: {
+          type: "boolean",
+          default: false,
+          description: "Set only when resuming an approval_required handoff already shown to the human. Keeps polling the same idempotent invocation while approval is pending."
+        }
+      },
+      required: ["invocation"],
+      additionalProperties: false
+    },
+    handler: async (topolo, args) => {
+      const invocationInput = coerceObjectParam(args["invocation"], "invocation");
+      const idempotencyKey = typeof invocationInput["idempotencyKey"] === "string" ? invocationInput["idempotencyKey"].trim() : "";
+      if (!idempotencyKey) {
+        throw new TopoloMcpPublicError("invocation.idempotencyKey is required.");
+      }
+      const resource = optionalResourceContext(args);
+      const waitSeconds = typeof args["waitSeconds"] === "number" ? Math.max(0, Math.min(120, Math.floor(args["waitSeconds"]))) : 30;
+      const waitForApproval = args["waitForApproval"] === true;
+      const createResult = await topolo.client.callAction(
+        AGENT_INVOCATIONS_CREATE,
+        invocationInput,
+        { confirm: true, ...resource ? { resource } : {} }
+      );
+      let invocation = invocationFrom(createResult);
+      const deadline = Date.now() + waitSeconds * 1e3;
+      while (invocation["terminal"] !== true && (invocation["status"] !== "awaiting_approval" || waitForApproval) && Date.now() < deadline) {
+        const recommended = typeof invocation["recommendedPollAfterSeconds"] === "number" ? invocation["recommendedPollAfterSeconds"] : 2;
+        const delayMs = Math.min(
+          Math.max(250, recommended * 1e3),
+          Math.max(0, deadline - Date.now())
+        );
+        if (delayMs > 0) await new Promise((resolve) => setTimeout(resolve, delayMs));
+        invocation = invocationFrom(await topolo.client.readAction(
+          AGENT_INVOCATIONS_GET,
+          { invocationId: invocation["invocationId"] },
+          resource ? { resource } : {}
+        ));
+      }
+      return agentRunResult(invocation);
+    }
+  },
   {
     name: "topolo_validate_action",
     title: "Validate Topolo action input",

package/dist/http.js

@@ -17792,6 +17792,8 @@ function splitService(servicePart) {
 
 // src/tools.ts
 var HTTP_METHODS = ["GET", "POST", "PUT", "PATCH", "DELETE"];
+var AGENT_INVOCATIONS_CREATE = "app_topolo_agent.agent_invocations.create";
+var AGENT_INVOCATIONS_GET = "app_topolo_agent.agent_invocations.get";
 function requiredString(args, name) {
   const value = typeof args[name] === "string" ? args[name].trim() : "";
   if (!value) throw new TopoloMcpPublicError(`${name} is required.`);
@@ -17831,6 +17833,40 @@ function coerceObjectParam(value, name) {
   }
   return candidate;
 }
+function recordValue(value) {
+  return value && typeof value === "object" && !Array.isArray(value) ? value : null;
+}
+function invocationFrom(value) {
+  const invocation = recordValue(recordValue(value)?.["invocation"]);
+  if (!invocation || typeof invocation["invocationId"] !== "string") {
+    throw new TopoloMcpPublicError("Topolo Agent returned an invalid invocation response.");
+  }
+  return invocation;
+}
+function agentRunResult(invocation) {
+  const status = typeof invocation["status"] === "string" ? invocation["status"] : "running";
+  const terminal = invocation["terminal"] === true;
+  const approval = recordValue(invocation["approval"]);
+  if (status === "awaiting_approval" && approval) {
+    return {
+      state: "approval_required",
+      invocationId: invocation["invocationId"],
+      verificationUrl: approval["verificationUrl"],
+      continuation: {
+        tool: "topolo_run_agent",
+        reuseSameInvocation: true,
+        arguments: { waitForApproval: true, waitSeconds: 120 }
+      },
+      approval,
+      invocation
+    };
+  }
+  return {
+    state: terminal ? status : "running",
+    invocationId: invocation["invocationId"],
+    invocation
+  };
+}
 var TOOLS = [
   {
     name: "topolo_whoami",
@@ -18078,6 +18114,70 @@ var TOOLS = [
       );
     }
   },
+  {
+    name: "topolo_run_agent",
+    title: "Run a Topolo agent to a durable checkpoint",
+    description: "Creates or replays one idempotent Topolo Agent invocation, polls its published status, and returns either the terminal result or an approval_required handoff with the exact Topolo verification URL. Reusing the same idempotencyKey never starts a duplicate invocation. After showing the verification URL, immediately call this tool again with the same invocation and waitForApproval=true so the terminal result returns here.",
+    requiredScopes: [],
+    destructive: true,
+    inputSchema: {
+      type: "object",
+      properties: {
+        invocation: {
+          type: "object",
+          description: "Input for app_topolo_agent.agent_invocations.create, including a stable idempotencyKey.",
+          additionalProperties: true
+        },
+        resourceType: { type: "string", description: "Optional resource-scoping alias for the Agent workspace." },
+        resourceId: { type: "string", description: "Resource id. Required when resourceType is provided." },
+        waitSeconds: {
+          type: "integer",
+          minimum: 0,
+          maximum: 120,
+          default: 30,
+          description: "Maximum time to poll. Returns state=running when the bounded wait elapses."
+        },
+        waitForApproval: {
+          type: "boolean",
+          default: false,
+          description: "Set only when resuming an approval_required handoff already shown to the human. Keeps polling the same idempotent invocation while approval is pending."
+        }
+      },
+      required: ["invocation"],
+      additionalProperties: false
+    },
+    handler: async (topolo, args) => {
+      const invocationInput = coerceObjectParam(args["invocation"], "invocation");
+      const idempotencyKey = typeof invocationInput["idempotencyKey"] === "string" ? invocationInput["idempotencyKey"].trim() : "";
+      if (!idempotencyKey) {
+        throw new TopoloMcpPublicError("invocation.idempotencyKey is required.");
+      }
+      const resource = optionalResourceContext(args);
+      const waitSeconds = typeof args["waitSeconds"] === "number" ? Math.max(0, Math.min(120, Math.floor(args["waitSeconds"]))) : 30;
+      const waitForApproval = args["waitForApproval"] === true;
+      const createResult = await topolo.client.callAction(
+        AGENT_INVOCATIONS_CREATE,
+        invocationInput,
+        { confirm: true, ...resource ? { resource } : {} }
+      );
+      let invocation = invocationFrom(createResult);
+      const deadline = Date.now() + waitSeconds * 1e3;
+      while (invocation["terminal"] !== true && (invocation["status"] !== "awaiting_approval" || waitForApproval) && Date.now() < deadline) {
+        const recommended = typeof invocation["recommendedPollAfterSeconds"] === "number" ? invocation["recommendedPollAfterSeconds"] : 2;
+        const delayMs = Math.min(
+          Math.max(250, recommended * 1e3),
+          Math.max(0, deadline - Date.now())
+        );
+        if (delayMs > 0) await new Promise((resolve) => setTimeout(resolve, delayMs));
+        invocation = invocationFrom(await topolo.client.readAction(
+          AGENT_INVOCATIONS_GET,
+          { invocationId: invocation["invocationId"] },
+          resource ? { resource } : {}
+        ));
+      }
+      return agentRunResult(invocation);
+    }
+  },
   {
     name: "topolo_validate_action",
     title: "Validate Topolo action input",

package/dist/index.js

@@ -4154,6 +4154,8 @@ function publicMcpErrorMessage(error, fallback) {
 
 // src/tools.ts
 var HTTP_METHODS = ["GET", "POST", "PUT", "PATCH", "DELETE"];
+var AGENT_INVOCATIONS_CREATE = "app_topolo_agent.agent_invocations.create";
+var AGENT_INVOCATIONS_GET = "app_topolo_agent.agent_invocations.get";
 function requiredString(args, name) {
   const value = typeof args[name] === "string" ? args[name].trim() : "";
   if (!value) throw new TopoloMcpPublicError(`${name} is required.`);
@@ -4193,6 +4195,40 @@ function coerceObjectParam(value, name) {
   }
   return candidate;
 }
+function recordValue(value) {
+  return value && typeof value === "object" && !Array.isArray(value) ? value : null;
+}
+function invocationFrom(value) {
+  const invocation = recordValue(recordValue(value)?.["invocation"]);
+  if (!invocation || typeof invocation["invocationId"] !== "string") {
+    throw new TopoloMcpPublicError("Topolo Agent returned an invalid invocation response.");
+  }
+  return invocation;
+}
+function agentRunResult(invocation) {
+  const status = typeof invocation["status"] === "string" ? invocation["status"] : "running";
+  const terminal = invocation["terminal"] === true;
+  const approval = recordValue(invocation["approval"]);
+  if (status === "awaiting_approval" && approval) {
+    return {
+      state: "approval_required",
+      invocationId: invocation["invocationId"],
+      verificationUrl: approval["verificationUrl"],
+      continuation: {
+        tool: "topolo_run_agent",
+        reuseSameInvocation: true,
+        arguments: { waitForApproval: true, waitSeconds: 120 }
+      },
+      approval,
+      invocation
+    };
+  }
+  return {
+    state: terminal ? status : "running",
+    invocationId: invocation["invocationId"],
+    invocation
+  };
+}
 var TOOLS = [
   {
     name: "topolo_whoami",
@@ -4440,6 +4476,70 @@ var TOOLS = [
       );
     }
   },
+  {
+    name: "topolo_run_agent",
+    title: "Run a Topolo agent to a durable checkpoint",
+    description: "Creates or replays one idempotent Topolo Agent invocation, polls its published status, and returns either the terminal result or an approval_required handoff with the exact Topolo verification URL. Reusing the same idempotencyKey never starts a duplicate invocation. After showing the verification URL, immediately call this tool again with the same invocation and waitForApproval=true so the terminal result returns here.",
+    requiredScopes: [],
+    destructive: true,
+    inputSchema: {
+      type: "object",
+      properties: {
+        invocation: {
+          type: "object",
+          description: "Input for app_topolo_agent.agent_invocations.create, including a stable idempotencyKey.",
+          additionalProperties: true
+        },
+        resourceType: { type: "string", description: "Optional resource-scoping alias for the Agent workspace." },
+        resourceId: { type: "string", description: "Resource id. Required when resourceType is provided." },
+        waitSeconds: {
+          type: "integer",
+          minimum: 0,
+          maximum: 120,
+          default: 30,
+          description: "Maximum time to poll. Returns state=running when the bounded wait elapses."
+        },
+        waitForApproval: {
+          type: "boolean",
+          default: false,
+          description: "Set only when resuming an approval_required handoff already shown to the human. Keeps polling the same idempotent invocation while approval is pending."
+        }
+      },
+      required: ["invocation"],
+      additionalProperties: false
+    },
+    handler: async (topolo, args) => {
+      const invocationInput = coerceObjectParam(args["invocation"], "invocation");
+      const idempotencyKey = typeof invocationInput["idempotencyKey"] === "string" ? invocationInput["idempotencyKey"].trim() : "";
+      if (!idempotencyKey) {
+        throw new TopoloMcpPublicError("invocation.idempotencyKey is required.");
+      }
+      const resource = optionalResourceContext(args);
+      const waitSeconds = typeof args["waitSeconds"] === "number" ? Math.max(0, Math.min(120, Math.floor(args["waitSeconds"]))) : 30;
+      const waitForApproval = args["waitForApproval"] === true;
+      const createResult = await topolo.client.callAction(
+        AGENT_INVOCATIONS_CREATE,
+        invocationInput,
+        { confirm: true, ...resource ? { resource } : {} }
+      );
+      let invocation = invocationFrom(createResult);
+      const deadline = Date.now() + waitSeconds * 1e3;
+      while (invocation["terminal"] !== true && (invocation["status"] !== "awaiting_approval" || waitForApproval) && Date.now() < deadline) {
+        const recommended = typeof invocation["recommendedPollAfterSeconds"] === "number" ? invocation["recommendedPollAfterSeconds"] : 2;
+        const delayMs = Math.min(
+          Math.max(250, recommended * 1e3),
+          Math.max(0, deadline - Date.now())
+        );
+        if (delayMs > 0) await new Promise((resolve2) => setTimeout(resolve2, delayMs));
+        invocation = invocationFrom(await topolo.client.readAction(
+          AGENT_INVOCATIONS_GET,
+          { invocationId: invocation["invocationId"] },
+          resource ? { resource } : {}
+        ));
+      }
+      return agentRunResult(invocation);
+    }
+  },
   {
     name: "topolo_validate_action",
     title: "Validate Topolo action input",

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@topolo/mcp",
   "packageManager": "pnpm@10.17.1",
-  "version": "0.13.3",
-  "topoloPublishedVersion": "0.13.3",
+  "version": "0.14.2",
+  "topoloPublishedVersion": "0.14.2",
   "description": "Model Context Protocol server for the Topolo platform. Exposes scope-gated tools that third-party agents (Claude, Codex, etc.) can call natively.",
   "license": "UNLICENSED",
   "author": "Topolo",