@topolo/mcp 0.13.2 → 0.14.1

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,35 @@ 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"],
+      approval,
+      invocation
+    };
+  }
+  return {
+    state: terminal ? status : "running",
+    invocationId: invocation["invocationId"],
+    invocation
+  };
+}
 var TOOLS = [
   {
     name: "topolo_whoami",
@@ -351,6 +382,64 @@ 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.",
+    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."
+        }
+      },
+      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 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" && 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,35 @@ 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"],
+      approval,
+      invocation
+    };
+  }
+  return {
+    state: terminal ? status : "running",
+    invocationId: invocation["invocationId"],
+    invocation
+  };
+}
 var TOOLS = [
   {
     name: "topolo_whoami",
@@ -18078,6 +18109,64 @@ 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.",
+    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."
+        }
+      },
+      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 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" && 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,35 @@ 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"],
+      approval,
+      invocation
+    };
+  }
+  return {
+    state: terminal ? status : "running",
+    invocationId: invocation["invocationId"],
+    invocation
+  };
+}
 var TOOLS = [
   {
     name: "topolo_whoami",
@@ -4440,6 +4471,64 @@ 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.",
+    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."
+        }
+      },
+      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 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" && 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",
@@ -4968,6 +5057,10 @@ function audienceFor(context) {
   }
   return `app_topolo_${service.replace(/-/g, "_")}`;
 }
+function scopeFor(context, audience) {
+  if (context.service === "auth" && context.path === "/api/auth/me") return "app_topolo_auth:identity";
+  return `${audience}:actions:execute`;
+}
 function responseData(value) {
   if (!value || typeof value !== "object") return {};
   const record2 = value;
@@ -4985,22 +5078,24 @@ async function resolveExternalAgentInstallationCredential(environment, installat
   const fetchImpl = options.fetch ?? fetch;
   const now = options.now ?? Date.now;
   const authBaseUrl = resolveServiceUrl("auth", options.serviceUrls);
-  const tokenUrl = new URL("/api/developer-oauth/token", authBaseUrl).toString();
+  const tokenUrl = new URL("/oauth/token", authBaseUrl).toString();
   const cache = /* @__PURE__ */ new Map();
   const credentialProvider = async (context) => {
     const audience = audienceFor(context);
+    const scope = scopeFor(context, audience);
     const resource = context.resource ?? {
       resourceType: "organization",
       resourceId: stored.installation.organizationId
     };
     const boundTaskId = context.taskId?.trim() || taskId;
-    const key = JSON.stringify({ audience, taskId: boundTaskId, resource });
+    const key = JSON.stringify({ audience, scope, taskId: boundTaskId, resource });
     const cached = cache.get(key);
     if (cached && cached.expiresAt - 15e3 > now()) return cached.credential;
     const body = new URLSearchParams({
       grant_type: "client_credentials",
       client_id: stored.installation.clientId,
       client_secret: stored.secret.clientSecret,
+      scope,
       audience,
       task_id: boundTaskId,
       resource_type: resource.resourceType,

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@topolo/mcp",
   "packageManager": "pnpm@10.17.1",
-  "version": "0.13.2",
-  "topoloPublishedVersion": "0.13.2",
+  "version": "0.14.1",
+  "topoloPublishedVersion": "0.14.1",
   "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",