@topolo/mcp 0.11.12 → 0.13.0

package/dist/index.js

@@ -3,13 +3,13 @@
 // src/index.ts
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 
-// node_modules/@topolo/sdk/dist/index.js
+// node_modules/.pnpm/@topolo+sdk@0.21.0/node_modules/@topolo/sdk/dist/index.js
 function applyAuthHeaders(headers, credential) {
   if (credential.kind === "api_key") {
     headers.set("X-Api-Key", credential.apiKey);
     return;
   }
-  headers.set("Authorization", `Bearer ${credential.accessToken}`);
+  headers.set("Authorization", `${credential.kind === "dpop_access_token" ? "DPoP" : "Bearer"} ${credential.accessToken}`);
 }
 function applyAuditHeaders(headers, agent, requestId) {
   headers.set("X-Topolo-Client", `${agent.clientName}/${agent.clientVersion}`);
@@ -22,6 +22,54 @@ function generateRequestId() {
   }
   return `req_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 10)}`;
 }
+var encoder = new TextEncoder();
+function encodeBase64Url(value) {
+  const bytes = value instanceof Uint8Array ? value : new Uint8Array(value);
+  let binary = "";
+  for (const byte of bytes) binary += String.fromCharCode(byte);
+  return btoa(binary).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/g, "");
+}
+function encodeJson(value) {
+  return encodeBase64Url(encoder.encode(JSON.stringify(value)));
+}
+async function sha256Base64Url(value) {
+  return encodeBase64Url(await crypto.subtle.digest("SHA-256", encoder.encode(value)));
+}
+function publicJwk(privateJwk) {
+  const { crv, kty, x, y } = privateJwk;
+  if (kty !== "EC" || crv !== "P-256" || !x || !y || !privateJwk.d) {
+    throw new TypeError("A private P-256 JSON Web Key is required for DPoP signing.");
+  }
+  return { crv, kty, x, y };
+}
+function canonicalTargetUrl(value) {
+  const url = new URL(value);
+  return `${url.origin}${url.pathname}`;
+}
+async function createDpopProof(input) {
+  const jwk = publicJwk(input.privateJwk);
+  const key = await crypto.subtle.importKey(
+    "jwk",
+    input.privateJwk,
+    { name: "ECDSA", namedCurve: "P-256" },
+    false,
+    ["sign"]
+  );
+  const header = encodeJson({ alg: "ES256", typ: "dpop+jwt", jwk });
+  const claims = encodeJson({
+    jti: crypto.randomUUID(),
+    iat: Math.floor(Date.now() / 1e3),
+    htm: input.method.toUpperCase(),
+    htu: canonicalTargetUrl(input.targetUrl),
+    ath: await sha256Base64Url(input.accessToken)
+  });
+  const signature = await crypto.subtle.sign(
+    { name: "ECDSA", hash: "SHA-256" },
+    key,
+    encoder.encode(`${header}.${claims}`)
+  );
+  return `${header}.${claims}.${encodeBase64Url(signature)}`;
+}
 var TopoloSdkError = class extends Error {
   code;
   constructor(code, message) {
@@ -167,10 +215,10 @@ var TopoloPermissionError = class extends TopoloSdkError {
 };
 function extractTopoloServiceErrorCode(body) {
   if (!body || typeof body !== "object" || Array.isArray(body)) return null;
-  const record = body;
-  const topLevel = canonicalTopoloErrorCode(record.code);
+  const record2 = body;
+  const topLevel = canonicalTopoloErrorCode(record2.code);
   if (topLevel) return topLevel;
-  const nested = record.error;
+  const nested = record2.error;
   const nestedString = canonicalTopoloErrorCode(nested);
   if (nestedString) return nestedString;
   if (nested && typeof nested === "object" && !Array.isArray(nested)) {
@@ -185,14 +233,14 @@ function serviceErrorCode(body, fallback) {
 }
 function extractTopoloServiceErrorDetails(body) {
   if (!body || typeof body !== "object" || Array.isArray(body)) return void 0;
-  const record = body;
-  let candidate = record.details;
-  const nested = record.error;
+  const record2 = body;
+  let candidate = record2.details;
+  const nested = record2.error;
   if (nested && typeof nested === "object" && !Array.isArray(nested)) {
     const nestedRecord = nested;
     if (candidate === void 0) candidate = nestedRecord.details ?? nestedRecord;
   }
-  if (candidate === void 0) candidate = record;
+  if (candidate === void 0) candidate = record2;
   if (Array.isArray(candidate)) {
     const paths = canonicalTopoloValidationPaths(candidate);
     return paths.length ? { paths } : void 0;
@@ -244,8 +292,8 @@ function canonicalTopoloValidationPaths(issues) {
   const paths = [];
   for (const issue of issues) {
     if (!issue || typeof issue !== "object" || Array.isArray(issue)) continue;
-    const record = issue;
-    const path = canonicalTopoloValidationPath(record.field) ?? canonicalTopoloValidationPath(record.path);
+    const record2 = issue;
+    const path = canonicalTopoloValidationPath(record2.field) ?? canonicalTopoloValidationPath(record2.path);
     if (path && !paths.includes(path)) paths.push(path);
     if (paths.length === 32) break;
   }
@@ -712,6 +760,222 @@ function isMultipleOf(value, divisor) {
   const quotient = value / divisor;
   return Math.abs(quotient - Math.round(quotient)) < Number.EPSILON * Math.max(1, Math.abs(quotient)) * 4;
 }
+var ACTOR_ENVELOPE_VERSION = 1;
+var TOPOLO_ACTOR_ENVELOPE_HEADER = "X-Topolo-Actor-Envelope";
+var PRINCIPAL_TYPES = /* @__PURE__ */ new Set([
+  "human",
+  "managed_agent",
+  "external_agent",
+  "service",
+  "browser_automation"
+]);
+var ACCOUNTABLE_SUBJECT_TYPES = /* @__PURE__ */ new Set(["human", "organization"]);
+var CHANNELS = /* @__PURE__ */ new Set(["web", "mobile", "cli", "mcp", "api", "workflow", "browser_automation"]);
+var ASSURANCE_LEVELS = /* @__PURE__ */ new Set(["authenticated", "workload_identity", "user_verified"]);
+var HASH_PATTERN = /^sha256:[a-f0-9]{64}$/;
+var ActorEnvelopeValidationError = class extends Error {
+  path;
+  constructor(path, message) {
+    super(`${path}: ${message}`);
+    this.name = "ActorEnvelopeValidationError";
+    this.path = path;
+  }
+};
+function parseActorEnvelope(value) {
+  const envelope = record(value, "actorEnvelope");
+  exactKeys(envelope, [
+    "schemaVersion",
+    "organizationId",
+    "accountableSubject",
+    "performer",
+    "delegation",
+    "channel",
+    "assurance",
+    "action",
+    "issuedAt",
+    "expiresAt"
+  ], "actorEnvelope");
+  if (envelope.schemaVersion !== ACTOR_ENVELOPE_VERSION) {
+    fail("actorEnvelope.schemaVersion", `must equal ${ACTOR_ENVELOPE_VERSION}`);
+  }
+  const accountableSubject = parseAccountableSubject(envelope.accountableSubject);
+  const performer = parseIdentity(envelope.performer, "actorEnvelope.performer");
+  const organizationId = text(envelope.organizationId, "actorEnvelope.organizationId");
+  const channel = member(envelope.channel, CHANNELS, "actorEnvelope.channel");
+  const issuedAt = timestamp(envelope.issuedAt, "actorEnvelope.issuedAt");
+  const expiresAt = envelope.expiresAt === void 0 ? void 0 : timestamp(envelope.expiresAt, "actorEnvelope.expiresAt");
+  if (expiresAt && Date.parse(expiresAt) <= Date.parse(issuedAt)) {
+    fail("actorEnvelope.expiresAt", "must be later than issuedAt");
+  }
+  const assuranceValue = record(envelope.assurance, "actorEnvelope.assurance");
+  exactKeys(assuranceValue, ["level", "methods"], "actorEnvelope.assurance");
+  const assurance = {
+    level: member(assuranceValue.level, ASSURANCE_LEVELS, "actorEnvelope.assurance.level"),
+    methods: textArray(assuranceValue.methods, "actorEnvelope.assurance.methods")
+  };
+  const actionValue = record(envelope.action, "actorEnvelope.action");
+  exactKeys(actionValue, ["requestId", "actionId", "resourceType", "resourceId", "inputHash"], "actorEnvelope.action");
+  const inputHash = text(actionValue.inputHash, "actorEnvelope.action.inputHash");
+  if (!HASH_PATTERN.test(inputHash)) fail("actorEnvelope.action.inputHash", "must be a lowercase sha256 digest");
+  const action = {
+    requestId: text(actionValue.requestId, "actorEnvelope.action.requestId"),
+    actionId: text(actionValue.actionId, "actorEnvelope.action.actionId"),
+    ...actionValue.resourceType === void 0 ? {} : { resourceType: text(actionValue.resourceType, "actorEnvelope.action.resourceType") },
+    ...actionValue.resourceId === void 0 ? {} : { resourceId: text(actionValue.resourceId, "actorEnvelope.action.resourceId") },
+    inputHash
+  };
+  if (action.resourceType === void 0 !== (action.resourceId === void 0)) {
+    fail("actorEnvelope.action", "resourceType and resourceId must be provided together");
+  }
+  const delegation = parseDelegation(envelope.delegation);
+  const directHuman = performer.principalType === "human" && performer.principalId === accountableSubject.principalId;
+  if (directHuman && delegation !== null) fail("actorEnvelope.delegation", "must be null for direct human action");
+  if (!directHuman && delegation === null) fail("actorEnvelope.delegation", "is required when performer differs from accountable subject");
+  if (delegation) {
+    const finalHop = delegation.lineage.at(-1);
+    if (!finalHop || finalHop.principalId !== performer.principalId || finalHop.principalType !== performer.principalType) {
+      fail("actorEnvelope.delegation.lineage", "must end with the performer");
+    }
+  }
+  if (performer.principalType === "external_agent" && (!performer.installationId || !performer.provider)) {
+    fail("actorEnvelope.performer", "external_agent requires installationId and provider");
+  }
+  if (performer.principalType === "managed_agent" && !performer.agentInstanceId) {
+    fail("actorEnvelope.performer.agentInstanceId", "is required for managed_agent");
+  }
+  if (performer.principalType === "browser_automation" && (!performer.installationId || !performer.browserSessionId)) {
+    fail("actorEnvelope.performer", "browser_automation requires installationId and browserSessionId");
+  }
+  return {
+    schemaVersion: ACTOR_ENVELOPE_VERSION,
+    organizationId,
+    accountableSubject,
+    performer,
+    delegation,
+    channel,
+    assurance,
+    action,
+    issuedAt,
+    ...expiresAt ? { expiresAt } : {}
+  };
+}
+function canonicalizeActorEnvelope(value) {
+  return canonicalJson(parseActorEnvelope(value));
+}
+function encodeActorEnvelopeHeader(value) {
+  const bytes = new TextEncoder().encode(canonicalizeActorEnvelope(value));
+  const binary = Array.from(bytes, (byte) => String.fromCharCode(byte)).join("");
+  return btoa(binary).replaceAll("+", "-").replaceAll("/", "_").replace(/=+$/, "");
+}
+function canonicalJson(value) {
+  if (value === null) return "null";
+  if (typeof value === "string" || typeof value === "boolean") return JSON.stringify(value);
+  if (typeof value === "number") {
+    if (!Number.isFinite(value)) throw new TypeError("Canonical JSON accepts finite numbers only.");
+    return JSON.stringify(value);
+  }
+  if (Array.isArray(value)) return `[${value.map(canonicalJson).join(",")}]`;
+  if (typeof value !== "object" || !value || ![Object.prototype, null].includes(Object.getPrototypeOf(value))) {
+    throw new TypeError("Canonical JSON accepts JSON objects, arrays, and primitives only.");
+  }
+  const entries = Object.entries(value).filter(([, item]) => item !== void 0).sort(([left], [right]) => left.localeCompare(right));
+  return `{${entries.map(([key, item]) => `${JSON.stringify(key)}:${canonicalJson(item)}`).join(",")}}`;
+}
+function parseAccountableSubject(value) {
+  const path = "actorEnvelope.accountableSubject";
+  const subject = record(value, path);
+  exactKeys(subject, ["principalType", "principalId", "displayName"], path);
+  return {
+    principalType: member(subject.principalType, ACCOUNTABLE_SUBJECT_TYPES, `${path}.principalType`),
+    principalId: text(subject.principalId, `${path}.principalId`),
+    ...subject.displayName === void 0 ? {} : { displayName: text(subject.displayName, `${path}.displayName`) }
+  };
+}
+async function sha256CanonicalValue(value) {
+  const bytes = new TextEncoder().encode(canonicalJson(value));
+  const digest = await crypto.subtle.digest("SHA-256", bytes);
+  return `sha256:${Array.from(new Uint8Array(digest), (byte) => byte.toString(16).padStart(2, "0")).join("")}`;
+}
+function parseIdentity(value, path) {
+  const identity = record(value, path);
+  exactKeys(identity, [
+    "principalType",
+    "principalId",
+    "displayName",
+    "installationId",
+    "agentInstanceId",
+    "browserSessionId",
+    "provider",
+    "model"
+  ], path);
+  return {
+    principalType: member(identity.principalType, PRINCIPAL_TYPES, `${path}.principalType`),
+    principalId: text(identity.principalId, `${path}.principalId`),
+    ...optionalTextFields(identity, path, [
+      "displayName",
+      "installationId",
+      "agentInstanceId",
+      "browserSessionId",
+      "provider",
+      "model"
+    ])
+  };
+}
+function parseDelegation(value) {
+  if (value === null) return null;
+  const delegation = record(value, "actorEnvelope.delegation");
+  exactKeys(delegation, ["taskId", "runId", "lineage"], "actorEnvelope.delegation");
+  if (!Array.isArray(delegation.lineage) || delegation.lineage.length === 0 || delegation.lineage.length > 16) {
+    fail("actorEnvelope.delegation.lineage", "must contain between 1 and 16 hops");
+  }
+  return {
+    taskId: text(delegation.taskId, "actorEnvelope.delegation.taskId"),
+    runId: text(delegation.runId, "actorEnvelope.delegation.runId"),
+    lineage: delegation.lineage.map((value2, index) => {
+      const hop = record(value2, `actorEnvelope.delegation.lineage[${index}]`);
+      exactKeys(hop, ["principalType", "principalId"], `actorEnvelope.delegation.lineage[${index}]`);
+      return {
+        principalType: member(hop.principalType, PRINCIPAL_TYPES, `actorEnvelope.delegation.lineage[${index}].principalType`),
+        principalId: text(hop.principalId, `actorEnvelope.delegation.lineage[${index}].principalId`)
+      };
+    })
+  };
+}
+function record(value, path) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) fail(path, "must be an object");
+  return value;
+}
+function exactKeys(value, allowed, path) {
+  const unknown = Object.keys(value).filter((key) => !allowed.includes(key));
+  if (unknown.length) fail(path, `contains unknown field ${unknown[0]}`);
+}
+function text(value, path) {
+  if (typeof value !== "string" || value.trim() !== value || value.length === 0 || value.length > 256) {
+    fail(path, "must be a non-empty trimmed string of at most 256 characters");
+  }
+  return value;
+}
+function timestamp(value, path) {
+  const result = text(value, path);
+  if (!/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{3})?Z$/.test(result) || Number.isNaN(Date.parse(result))) {
+    fail(path, "must be an RFC 3339 UTC timestamp");
+  }
+  return result;
+}
+function member(value, values, path) {
+  if (typeof value !== "string" || !values.has(value)) fail(path, "contains an unsupported value");
+  return value;
+}
+function textArray(value, path) {
+  if (!Array.isArray(value) || value.length === 0 || value.length > 16) fail(path, "must contain between 1 and 16 values");
+  return value.map((item, index) => text(item, `${path}[${index}]`));
+}
+function optionalTextFields(value, path, keys) {
+  return Object.fromEntries(keys.flatMap((key) => value[key] === void 0 ? [] : [[key, text(value[key], `${path}.${key}`)]]));
+}
+function fail(path, message) {
+  throw new ActorEnvelopeValidationError(path, message);
+}
 function parseTopoloActionUploadContract(value) {
   if (!isRecord2(value) || value.profile !== "inline-base64" && value.profile !== "url-session") {
     throw new TopoloSdkError("upload_contract_unavailable", "This action does not publish a supported upload contract.");
@@ -916,6 +1180,7 @@ var NEGATIVE_CACHE_TTL_MS = 60 * 1e3;
 var TopoloClient = class _TopoloClient {
   credential;
   agent;
+  actorContext;
   serviceUrls;
   environment;
   appIds;
@@ -923,7 +1188,7 @@ var TopoloClient = class _TopoloClient {
   timeoutMs;
   fetchImpl;
   credentialProvider;
-  credentialLoadInFlight = null;
+  credentialLoadsInFlight = /* @__PURE__ */ new Map();
   refreshCredential;
   refreshInFlight = null;
   debug;
@@ -946,6 +1211,11 @@ var TopoloClient = class _TopoloClient {
     if (!options.agent?.clientName) throw new TopoloAuthError("agent.clientName is required");
     this.credential = options.credential;
     this.agent = options.agent;
+    this.actorContext = options.actorContext ? {
+      channel: options.actorContext.channel,
+      taskId: options.actorContext.taskId ?? `task_${generateRequestId()}`,
+      runId: options.actorContext.runId ?? `run_${generateRequestId()}`
+    } : void 0;
     this.environment = options.environment;
     this.serviceUrls = options.environment ? topoloServiceOrigins(options.serviceUrls, options.environment) : options.serviceUrls;
     this.appIds = options.appIds;
@@ -975,7 +1245,16 @@ var TopoloClient = class _TopoloClient {
         `Mutating ${method} requests require { confirm: true }. This guardrail prevents agents from issuing writes without an explicit human-in-the-loop acknowledgement.`
       );
     }
-    await this.loadCurrentCredential();
+    const actionId = requestActionId(opts.headers);
+    const taskId = opts.actorEnvelope?.delegation?.taskId ?? this.actorContext?.taskId;
+    let requestCredential = await this.loadCurrentCredential({
+      service: normalizeLookupKey(opts.service),
+      method,
+      path: opts.path,
+      ...actionId ? { actionId } : {},
+      ...taskId ? { taskId } : {},
+      ...opts.resource ? { resource: opts.resource } : {}
+    });
     const resolvedService = opts.baseUrl ? { serviceKey: normalizeLookupKey(opts.service), baseUrl: this.validatedServiceOrigin(opts.service, opts.baseUrl) } : await this.resolveRequestService(opts.service);
     const baseUrl = resolvedService.baseUrl;
     const url = new URL(opts.path, baseUrl.endsWith("/") ? baseUrl : `${baseUrl}/`);
@@ -998,12 +1277,15 @@ var TopoloClient = class _TopoloClient {
     if (opts.body !== void 0) headers.set("Content-Type", "application/json");
     const platformAppId = resolveConfiguredAppId(resolvedService.serviceKey, this.appIds);
     if (platformAppId) headers.set("X-App-ID", platformAppId);
-    applyAuthHeaders(headers, this.credential);
-    const requestId = generateRequestId();
+    const actorEnvelope = opts.actorEnvelope === void 0 ? void 0 : parseActorEnvelope(opts.actorEnvelope);
+    const requestId = actorEnvelope?.action.requestId ?? generateRequestId();
     applyAuditHeaders(headers, this.agent, requestId);
     if (opts.headers) {
       for (const [k, v] of Object.entries(opts.headers)) headers.set(k, v);
     }
+    if (actorEnvelope) {
+      headers.set(TOPOLO_ACTOR_ENVELOPE_HEADER, encodeActorEnvelopeHeader(actorEnvelope));
+    }
     if (opts.resource) {
       const resourceType = opts.resource.resourceType.trim();
       const resourceId = opts.resource.resourceId.trim();
@@ -1028,9 +1310,19 @@ var TopoloClient = class _TopoloClient {
       }, this.timeoutMs);
       const signal = opts.signal ? mergeSignals(opts.signal, controller.signal) : controller.signal;
       try {
+        const requestHeaders = new Headers(headers);
+        applyAuthHeaders(requestHeaders, requestCredential);
+        if (requestCredential.kind === "dpop_access_token") {
+          requestHeaders.set("DPoP", await createDpopProof({
+            accessToken: requestCredential.accessToken,
+            method,
+            targetUrl: urlStr,
+            privateJwk: requestCredential.privateJwk
+          }));
+        }
         return await this.fetchImpl(urlStr, {
           method,
-          headers: new Headers(headers),
+          headers: requestHeaders,
           body: opts.rawBody ?? (opts.body !== void 0 ? JSON.stringify(opts.body) : null),
           signal
         });
@@ -1061,13 +1353,13 @@ var TopoloClient = class _TopoloClient {
     };
     let res;
     try {
-      const attemptedCredential = this.credential;
+      const attemptedCredential = requestCredential;
       res = await fetchWithReadRetry();
       if (res.status === 401 && attemptedCredential.kind === "access_token" && this.refreshCredential) {
         await res.body?.cancel().catch(() => void 0);
         const refreshed = await this.refreshRejectedAccessToken(attemptedCredential.accessToken);
         if (refreshed) {
-          applyAuthHeaders(headers, refreshed);
+          requestCredential = refreshed;
           res = await fetchWithReadRetry();
         }
       }
@@ -1157,18 +1449,23 @@ var TopoloClient = class _TopoloClient {
     });
     return parsed;
   }
-  async loadCurrentCredential() {
-    if (!this.credentialProvider) return;
-    this.credentialLoadInFlight ??= this.credentialProvider().then((credential) => {
-      if (!credential) {
-        throw new TopoloAuthError("The configured Topolo credential is no longer available.");
-      }
-      this.credential = credential;
-      return credential;
-    }).finally(() => {
-      this.credentialLoadInFlight = null;
-    });
-    await this.credentialLoadInFlight;
+  async loadCurrentCredential(context) {
+    if (!this.credentialProvider) return this.credential;
+    const key = JSON.stringify(context);
+    let load = this.credentialLoadsInFlight.get(key);
+    if (!load) {
+      load = this.credentialProvider(context).then((credential) => {
+        if (!credential) {
+          throw new TopoloAuthError("The configured Topolo credential is no longer available.");
+        }
+        this.credential = credential;
+        return credential;
+      }).finally(() => {
+        this.credentialLoadsInFlight.delete(key);
+      });
+      this.credentialLoadsInFlight.set(key, load);
+    }
+    return load;
   }
   async refreshRejectedAccessToken(attemptedAccessToken) {
     if (this.credential.kind === "access_token" && this.credential.accessToken !== attemptedAccessToken) {
@@ -1450,14 +1747,14 @@ var TopoloClient = class _TopoloClient {
     if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
       throw new TopoloSdkError("action_catalog_summary_unavailable", "Action catalog summary is unavailable.");
     }
-    const record = raw;
-    if (record.algorithm !== "sha256-v1" || typeof record.digest !== "string" || !/^[a-f0-9]{64}$/.test(record.digest) || !Number.isSafeInteger(record.actionCount) || Number(record.actionCount) < 0) {
+    const record2 = raw;
+    if (record2.algorithm !== "sha256-v1" || typeof record2.digest !== "string" || !/^[a-f0-9]{64}$/.test(record2.digest) || !Number.isSafeInteger(record2.actionCount) || Number(record2.actionCount) < 0) {
       throw new TopoloSdkError("action_catalog_summary_unavailable", "Action catalog summary is invalid.");
     }
     return {
       algorithm: "sha256-v1",
-      digest: record.digest,
-      actionCount: Number(record.actionCount)
+      digest: record2.digest,
+      actionCount: Number(record2.actionCount)
     };
   }
   /** @deprecated Prefer searchActions() so callers retain the continuation cursor. */
@@ -1498,6 +1795,14 @@ var TopoloClient = class _TopoloClient {
     const entry = await this.getAction(action);
     return this.executeResolvedAction(entry, input, options);
   }
+  async issueExternalAgentCredential(input) {
+    const actionId = "app_topolo_auth.principal_credentials.issue";
+    const entry = await this.getAction(actionId);
+    if (entry.actionId !== actionId) {
+      throw new TopoloSdkError("unexpected_action", "External agent credential issuance resolved an unexpected action.");
+    }
+    return this.executeResolvedAction(entry, input, { confirm: true }, true);
+  }
   async uploadAction(action, content, input, options) {
     const entry = await this.getAction(action);
     const contract = parseTopoloActionUploadContract(entry.agentContract?.upload);
@@ -1629,7 +1934,7 @@ var TopoloClient = class _TopoloClient {
     }
     return this.executeResolvedAction(entry, input, options);
   }
-  async executeResolvedAction(entry, input, options) {
+  async executeResolvedAction(entry, input, options, preserveSensitiveResult = false) {
     const agentAccess = entry.agentAccess ?? (entry.destructive ? "off" : entry.readOnly && !entry.requiresConfirmation ? "auto" : "confirm");
     if (agentAccess === "off") {
       throw new TopoloPermissionError(
@@ -1657,6 +1962,20 @@ var TopoloClient = class _TopoloClient {
       );
     }
     const mapped = mapActionInput(entry, input);
+    const resolvedActorEnvelope = options.actorEnvelope ?? await this.buildVerifiedAgentActorEnvelope(entry.actionId, input, options.resource);
+    if (resolvedActorEnvelope) {
+      const actorEnvelope = parseActorEnvelope(resolvedActorEnvelope);
+      if (actorEnvelope.action.actionId !== entry.actionId) {
+        throw new TopoloSdkError("actor_envelope_action_mismatch", "Actor envelope actionId does not match the executed action.");
+      }
+      if (actorEnvelope.action.inputHash !== await sha256CanonicalValue(input)) {
+        throw new TopoloSdkError("actor_envelope_input_mismatch", "Actor envelope inputHash does not match the executed action input.");
+      }
+      const envelopeResource = actorEnvelope.action.resourceType && actorEnvelope.action.resourceId ? { resourceType: actorEnvelope.action.resourceType, resourceId: actorEnvelope.action.resourceId } : void 0;
+      if (envelopeResource?.resourceType !== options.resource?.resourceType || envelopeResource?.resourceId !== options.resource?.resourceId) {
+        throw new TopoloSdkError("actor_envelope_resource_mismatch", "Actor envelope resource does not match the executed action resource.");
+      }
+    }
     const service = entry.appSlug || entry.appId;
     const result = await this.request({
       service,
@@ -1666,13 +1985,64 @@ var TopoloClient = class _TopoloClient {
       ...mapped.query ? { query: mapped.query } : {},
       ...mapped.body !== void 0 ? { body: mapped.body } : {},
       ...options.resource ? { resource: options.resource } : {},
+      ...resolvedActorEnvelope ? { actorEnvelope: resolvedActorEnvelope } : {},
       headers: {
         [TOPOLO_ACTION_ID_HEADER]: entry.actionId,
         [TOPOLO_ACTION_NAME_HEADER]: entry.name
       },
       confirm: options.confirm === true || entry.readOnly && !entry.destructive && !entry.requiresConfirmation
     });
-    return redactActionResult(result);
+    return preserveSensitiveResult ? result : redactActionResult(result);
+  }
+  async buildVerifiedAgentActorEnvelope(actionId, input, resource) {
+    if (!this.actorContext) return void 0;
+    const identity = await this.introspect();
+    const principalType = identity.user.principalType;
+    if (principalType !== "agent_employee" && principalType !== "external_agent") return void 0;
+    if (!identity.organization || !identity.user.accountableUserId || !identity.user.principalId) {
+      throw new TopoloSdkError(
+        "incomplete_agent_identity",
+        "Verified agent credentials must resolve an organization, accountable user, and principal id."
+      );
+    }
+    const performer = principalType === "external_agent" ? {
+      principalType: "external_agent",
+      principalId: identity.user.principalId,
+      installationId: identity.user.installationId ?? void 0,
+      provider: identity.user.provider ?? void 0,
+      model: identity.user.model ?? void 0
+    } : {
+      principalType: "managed_agent",
+      principalId: identity.user.principalId,
+      agentInstanceId: identity.user.agentInstanceId ?? void 0,
+      model: identity.user.model ?? void 0
+    };
+    if (performer.principalType === "external_agent" && (!performer.installationId || !performer.provider) || performer.principalType === "managed_agent" && !performer.agentInstanceId) {
+      throw new TopoloSdkError(
+        "incomplete_agent_identity",
+        "Verified agent credentials are missing the performer identity required for provenance."
+      );
+    }
+    return parseActorEnvelope({
+      schemaVersion: 1,
+      organizationId: identity.organization.id,
+      accountableSubject: { principalType: "human", principalId: identity.user.accountableUserId },
+      performer,
+      delegation: {
+        taskId: this.actorContext.taskId,
+        runId: this.actorContext.runId,
+        lineage: [{ principalType: performer.principalType, principalId: performer.principalId }]
+      },
+      channel: this.actorContext.channel,
+      assurance: { level: "workload_identity", methods: ["client_credentials"] },
+      action: {
+        requestId: generateRequestId(),
+        actionId,
+        ...resource ? resource : {},
+        inputHash: await sha256CanonicalValue(input)
+      },
+      issuedAt: (/* @__PURE__ */ new Date()).toISOString()
+    });
   }
   /**
    * Introspect the current credential. Returns the caller's resolved identity,
@@ -1701,7 +2071,18 @@ var TopoloClient = class _TopoloClient {
         email: user.email,
         name: user.name ?? null,
         role: user.role ?? (kind === "api_key" ? "service" : "member"),
-        permissions: payload.permissions ?? user.permissions ?? []
+        permissions: payload.permissions ?? user.permissions ?? [],
+        ...normalizeAgentPrincipalType(user.principalType) ? {
+          principalId: readOptionalString(user.principalId),
+          principalType: normalizeAgentPrincipalType(user.principalType),
+          accountableUserId: readOptionalString(user.accountableUserId),
+          agentInstanceId: readOptionalString(user.agentInstanceId),
+          installationId: readOptionalString(user.installationId),
+          provider: readOptionalString(user.provider),
+          model: readOptionalString(user.model),
+          serviceScopes: stringArray(user.serviceScopes),
+          policyRef: readOptionalString(user.policyRef)
+        } : {}
       },
       organization: organization ? {
         id: organization.id,
@@ -1830,12 +2211,21 @@ function redactActionResult(value) {
   if (!isRecord3(value)) return value;
   return Object.fromEntries(Object.entries(value).map(([key, item]) => [
     key,
-    isSensitiveActionResultKey(key) ? "[REDACTED]" : redactActionResult(item)
+    isSensitiveActionResultKey(key, item) ? "[REDACTED]" : redactActionResult(item)
   ]));
 }
-function isSensitiveActionResultKey(key) {
+function isSensitiveActionResultKey(key, value) {
   const normalized = key.toLowerCase().replace(/[^a-z0-9]/g, "");
-  return ["authorization", "cookie", "setcookie", "proxyauthorization", "capability"].includes(normalized) || /(token|secret|password|privatekey|apikey)$/.test(normalized);
+  if (normalized === "capability") return isCredentialShaped(value);
+  return ["authorization", "cookie", "setcookie", "proxyauthorization"].includes(normalized) || /(token|secret|password|privatekey|apikey)$/.test(normalized);
+}
+var PLAIN_ENUM_VALUE = /^[a-z][a-z0-9_-]{0,31}$/;
+function isCredentialShaped(value) {
+  if (typeof value !== "string") return value !== null && value !== void 0 && typeof value !== "boolean" && typeof value !== "number";
+  const trimmed = value.trim();
+  if (!trimmed) return false;
+  if (/^[a-z][a-z0-9+.-]*:\/\//i.test(trimmed)) return true;
+  return !PLAIN_ENUM_VALUE.test(trimmed);
 }
 function resolveConfiguredServiceUrl(slug, serviceUrls) {
   for (const serviceKey of serviceKeyCandidates2(slug)) {
@@ -2057,6 +2447,9 @@ function normalizeCredentialAuthorizationMode(value, kind) {
   if (value === "context_rbac" || value === "oauth_scopes" || value === "session_rbac") return value;
   return "unknown";
 }
+function normalizeAgentPrincipalType(value) {
+  return value === "agent_employee" || value === "external_agent" ? value : null;
+}
 function describeError(body, fallback) {
   if (body && typeof body === "object") {
     const maybe = body;
@@ -2075,16 +2468,22 @@ function pickString(value) {
   }
   return void 0;
 }
+function requestActionId(headers) {
+  const value = Object.entries(headers ?? {}).find(
+    ([name]) => name.toLowerCase() === TOPOLO_ACTION_ID_HEADER.toLowerCase()
+  )?.[1];
+  return value?.trim() || void 0;
+}
 function extractRequired(body) {
   if (body && typeof body === "object") {
     const maybe = body;
     if (Array.isArray(maybe.required)) return canonicalTopoloRequired(maybe.required);
     for (const nested of [maybe.details, maybe.error]) {
       if (!nested || typeof nested !== "object" || Array.isArray(nested)) continue;
-      const record = nested;
-      if (Array.isArray(record.required)) return canonicalTopoloRequired(record.required);
-      if (record.details && typeof record.details === "object" && !Array.isArray(record.details)) {
-        const required = record.details.required;
+      const record2 = nested;
+      if (Array.isArray(record2.required)) return canonicalTopoloRequired(record2.required);
+      if (record2.details && typeof record2.details === "object" && !Array.isArray(record2.details)) {
+        const required = record2.details.required;
         if (Array.isArray(required)) return canonicalTopoloRequired(required);
       }
     }
@@ -2159,8 +2558,8 @@ function compactResultValue(value, depth, budget) {
     return value.length > ACTION_RESULT_MAX_ITEMS ? { count: value.length, items, omittedItems: value.length - ACTION_RESULT_MAX_ITEMS } : items;
   }
   if (typeof value === "object") {
-    const record = value;
-    const allKeys = Object.keys(record);
+    const record2 = value;
+    const allKeys = Object.keys(record2);
     const ranked = allKeys.sort((left, right) => resultKeyPriority(left) - resultKeyPriority(right));
     const prioritized = ranked.filter((key) => resultKeyPriority(key) < 2);
     const ordinary = ranked.filter((key) => resultKeyPriority(key) === 2);
@@ -2169,7 +2568,7 @@ function compactResultValue(value, depth, budget) {
       ...prioritized,
       ...ordinary.slice(0, ordinaryLimit)
     ].slice(0, ACTION_RESULT_MAX_KEYS);
-    const compact = Object.fromEntries(keys.map((key) => [key, compactResultValue(record[key], depth + 1, budget)]));
+    const compact = Object.fromEntries(keys.map((key) => [key, compactResultValue(record2[key], depth + 1, budget)]));
     if (allKeys.length > keys.length) compact["_omittedKeys"] = allKeys.length - keys.length;
     return compact;
   }
@@ -2390,6 +2789,461 @@ var WorkspacesModule = class {
     return { organizationId: identity.organization.id, appId: service.appId };
   }
 };
+var nonEmptyString2 = { type: "string", minLength: 1 };
+var stringArray3 = { type: "array", items: nonEmptyString2 };
+var actionBinding = {
+  type: "object",
+  properties: {
+    id: nonEmptyString2,
+    label: nonEmptyString2,
+    actionId: nonEmptyString2,
+    resourceType: nonEmptyString2,
+    resourceId: nonEmptyString2,
+    input: { type: "object" },
+    requiresConfirmation: { type: "boolean" },
+    destructive: { type: "boolean" },
+    effects: stringArray3,
+    verification: stringArray3,
+    recovery: {
+      type: "object",
+      properties: {
+        mode: { enum: ["not_applicable", "retry", "compensating_action"] },
+        actionId: nonEmptyString2,
+        instructions: nonEmptyString2
+      },
+      required: ["mode", "instructions"],
+      additionalProperties: false
+    }
+  },
+  required: [
+    "id",
+    "label",
+    "actionId",
+    "resourceType",
+    "input",
+    "requiresConfirmation",
+    "destructive",
+    "effects",
+    "verification",
+    "recovery"
+  ],
+  additionalProperties: false
+};
+var dimension = {
+  type: "object",
+  properties: { key: nonEmptyString2, label: nonEmptyString2, value: nonEmptyString2 },
+  required: ["key", "label", "value"],
+  additionalProperties: false
+};
+var period = {
+  type: "object",
+  properties: {
+    start: nonEmptyString2,
+    end: nonEmptyString2,
+    timezone: nonEmptyString2
+  },
+  required: ["start", "end", "timezone"],
+  additionalProperties: false
+};
+var series = {
+  type: "object",
+  properties: {
+    id: nonEmptyString2,
+    label: nonEmptyString2,
+    unit: nonEmptyString2,
+    points: {
+      type: "array",
+      items: {
+        type: "object",
+        properties: {
+          timestamp: nonEmptyString2,
+          value: { type: "number" },
+          dimensions: { type: "array", items: dimension }
+        },
+        required: ["timestamp", "value", "dimensions"],
+        additionalProperties: false
+      }
+    }
+  },
+  required: ["id", "label", "unit", "points"],
+  additionalProperties: false
+};
+var contribution = {
+  type: "object",
+  properties: {
+    summary: nonEmptyString2,
+    identity: {
+      type: "object",
+      properties: { iconSource: { const: "catalog" } },
+      required: ["iconSource"],
+      additionalProperties: false
+    },
+    workspaceSelector: {
+      type: "object",
+      properties: {
+        mode: { enum: ["none", "optional", "required"] },
+        resourceType: nonEmptyString2,
+        label: nonEmptyString2,
+        supportsMultiple: { type: "boolean" }
+      },
+      required: ["mode", "resourceType", "label", "supportsMultiple"],
+      additionalProperties: false
+    },
+    metricDefinitions: {
+      type: "array",
+      items: {
+        type: "object",
+        properties: {
+          key: nonEmptyString2,
+          label: nonEmptyString2,
+          description: nonEmptyString2,
+          unit: nonEmptyString2,
+          semantic: {
+            enum: ["gauge", "counter", "rate", "duration", "currency", "percentage"]
+          },
+          aggregation: {
+            enum: ["last", "sum", "average", "minimum", "maximum", "count", "distinct_count"]
+          }
+        },
+        required: ["key", "label", "description", "unit", "semantic", "aggregation"],
+        additionalProperties: false
+      }
+    },
+    seriesDefinitions: {
+      type: "array",
+      items: {
+        type: "object",
+        properties: {
+          key: nonEmptyString2,
+          label: nonEmptyString2,
+          metricKey: nonEmptyString2,
+          unit: nonEmptyString2
+        },
+        required: ["key", "label", "metricKey", "unit"],
+        additionalProperties: false
+      }
+    },
+    dimensions: {
+      type: "array",
+      items: {
+        type: "object",
+        properties: {
+          key: nonEmptyString2,
+          label: nonEmptyString2,
+          description: nonEmptyString2,
+          valueType: { enum: ["string", "number", "boolean", "date", "datetime"] }
+        },
+        required: ["key", "label", "description", "valueType"],
+        additionalProperties: false
+      }
+    },
+    lifecycleStages: {
+      type: "array",
+      items: {
+        type: "object",
+        properties: {
+          key: nonEmptyString2,
+          label: nonEmptyString2,
+          order: { type: "number" },
+          terminal: { type: "boolean" }
+        },
+        required: ["key", "label", "order", "terminal"],
+        additionalProperties: false
+      }
+    },
+    events: {
+      type: "array",
+      items: {
+        type: "object",
+        properties: {
+          key: nonEmptyString2,
+          label: nonEmptyString2,
+          description: nonEmptyString2
+        },
+        required: ["key", "label", "description"],
+        additionalProperties: false
+      }
+    },
+    datasets: {
+      type: "array",
+      minItems: 1,
+      items: {
+        type: "object",
+        properties: {
+          id: nonEmptyString2,
+          label: nonEmptyString2,
+          description: nonEmptyString2,
+          grain: nonEmptyString2,
+          metricKeys: stringArray3,
+          seriesKeys: stringArray3,
+          dimensionKeys: stringArray3,
+          eventKeys: stringArray3,
+          actionIds: stringArray3
+        },
+        required: [
+          "id",
+          "label",
+          "description",
+          "grain",
+          "metricKeys",
+          "seriesKeys",
+          "dimensionKeys",
+          "eventKeys",
+          "actionIds"
+        ],
+        additionalProperties: false
+      }
+    },
+    compatibleVisualizations: {
+      type: "array",
+      minItems: 1,
+      items: {
+        enum: ["number", "line", "area", "bar", "donut", "table", "funnel", "timeline", "actions"]
+      }
+    },
+    defaultVisualization: {
+      enum: ["number", "line", "area", "bar", "donut", "table", "funnel", "timeline", "actions"]
+    }
+  },
+  required: [
+    "summary",
+    "identity",
+    "workspaceSelector",
+    "metricDefinitions",
+    "seriesDefinitions",
+    "dimensions",
+    "lifecycleStages",
+    "events",
+    "datasets",
+    "compatibleVisualizations",
+    "defaultVisualization"
+  ],
+  additionalProperties: false
+};
+var widgetItem = {
+  type: "object",
+  properties: {
+    id: nonEmptyString2,
+    version: nonEmptyString2,
+    appId: nonEmptyString2,
+    serviceName: nonEmptyString2,
+    lastUpdated: nonEmptyString2,
+    type: { enum: ["stats", "chart", "activity", "notifications", "actions"] },
+    presentation: {
+      type: "object",
+      properties: {
+        title: nonEmptyString2,
+        description: nonEmptyString2,
+        contexts: {
+          type: "array",
+          minItems: 1,
+          items: { enum: ["personal", "organization", "workspace", "resource"] }
+        },
+        supportedSizes: {
+          type: "array",
+          minItems: 1,
+          items: { enum: ["compact", "medium", "wide", "full"] }
+        },
+        defaultSize: { enum: ["compact", "medium", "wide", "full"] }
+      },
+      required: ["title", "contexts", "supportedSizes", "defaultSize"],
+      additionalProperties: false
+    },
+    resource: {
+      type: "object",
+      properties: {
+        resourceType: nonEmptyString2,
+        resourceId: nonEmptyString2,
+        requiredPermissions: stringArray3
+      },
+      required: ["resourceType", "requiredPermissions"],
+      additionalProperties: false
+    },
+    state: {
+      type: "object",
+      properties: {
+        status: { enum: ["ready", "empty", "unavailable", "stale", "error"] },
+        observedAt: nonEmptyString2,
+        lastSuccessfulAt: nonEmptyString2,
+        code: nonEmptyString2,
+        message: nonEmptyString2
+      },
+      required: ["status", "observedAt"],
+      additionalProperties: false
+    },
+    refresh: {
+      type: "object",
+      properties: {
+        intervalSeconds: { type: "number" },
+        timeoutSeconds: { type: "number" },
+        maxAgeSeconds: { type: "number" },
+        staleWhileRevalidateSeconds: { type: "number" }
+      },
+      required: ["intervalSeconds", "timeoutSeconds", "maxAgeSeconds", "staleWhileRevalidateSeconds"],
+      additionalProperties: false
+    },
+    configuration: {
+      type: "object",
+      properties: {
+        allowMultipleInstances: { type: "boolean" },
+        fields: {
+          type: "array",
+          items: {
+            type: "object",
+            properties: {
+              key: nonEmptyString2,
+              label: nonEmptyString2,
+              type: { enum: ["string", "number", "boolean", "select", "multi-select", "date-range"] },
+              required: { type: "boolean" },
+              options: {
+                type: "array",
+                items: {
+                  type: "object",
+                  properties: { value: nonEmptyString2, label: nonEmptyString2 },
+                  required: ["value", "label"],
+                  additionalProperties: false
+                }
+              }
+            },
+            required: ["key", "label", "type", "required"],
+            additionalProperties: false
+          }
+        },
+        defaults: { type: "object" }
+      },
+      required: ["allowMultipleInstances", "fields", "defaults"],
+      additionalProperties: false
+    },
+    drilldowns: {
+      type: "array",
+      items: {
+        type: "object",
+        properties: { id: nonEmptyString2, label: nonEmptyString2, href: nonEmptyString2 },
+        required: ["id", "label", "href"],
+        additionalProperties: false
+      }
+    },
+    controls: { type: "array", items: actionBinding },
+    localization: {
+      type: "object",
+      properties: {
+        locale: nonEmptyString2,
+        titleKey: nonEmptyString2,
+        descriptionKey: nonEmptyString2,
+        title: nonEmptyString2,
+        description: nonEmptyString2
+      },
+      required: ["locale", "titleKey"],
+      additionalProperties: false
+    },
+    accessibility: {
+      type: "object",
+      properties: { label: nonEmptyString2, description: nonEmptyString2 },
+      required: ["label"],
+      additionalProperties: false
+    },
+    contribution,
+    metrics: {
+      type: "array",
+      items: {
+        type: "object",
+        properties: {
+          key: nonEmptyString2,
+          label: nonEmptyString2,
+          value: { type: "number" },
+          unit: nonEmptyString2,
+          semantic: {
+            enum: ["gauge", "counter", "rate", "duration", "currency", "percentage"]
+          },
+          aggregation: {
+            enum: ["last", "sum", "average", "minimum", "maximum", "count", "distinct_count"]
+          },
+          period,
+          dimensions: { type: "array", items: dimension },
+          series
+        },
+        required: ["key", "label", "value", "unit", "semantic", "aggregation", "period", "dimensions"],
+        additionalProperties: false
+      }
+    },
+    chartType: { enum: ["line", "bar", "area", "pie", "donut"] },
+    series: { type: "array", items: series },
+    activities: { type: "array", items: { type: "object" } },
+    notifications: { type: "array", items: { type: "object" } },
+    unreadCount: { type: "number" },
+    actions: { type: "array", items: actionBinding }
+  },
+  required: [
+    "id",
+    "version",
+    "appId",
+    "serviceName",
+    "lastUpdated",
+    "type",
+    "presentation",
+    "resource",
+    "state",
+    "refresh",
+    "configuration",
+    "drilldowns",
+    "controls",
+    "localization",
+    "accessibility",
+    "contribution"
+  ],
+  allOf: [
+    { if: { properties: { type: { const: "stats" } } }, then: { required: ["metrics"] } },
+    { if: { properties: { type: { const: "chart" } } }, then: { required: ["chartType", "series"] } },
+    { if: { properties: { type: { const: "activity" } } }, then: { required: ["activities"] } },
+    {
+      if: { properties: { type: { const: "notifications" } } },
+      then: { required: ["notifications", "unreadCount"] }
+    },
+    { if: { properties: { type: { const: "actions" } } }, then: { required: ["actions"] } }
+  ],
+  additionalProperties: false
+};
+var TOPOLO_WIDGET_OUTPUT_SCHEMA = Object.freeze({
+  $schema: "https://json-schema.org/draft/2020-12/schema",
+  type: "object",
+  properties: {
+    success: { type: "boolean", const: true },
+    contractVersion: { type: "string", const: "3.0.0" },
+    appId: nonEmptyString2,
+    serviceName: nonEmptyString2,
+    generatedAt: nonEmptyString2,
+    widgets: { type: "array", minItems: 1, items: widgetItem },
+    workspace: {
+      anyOf: [
+        {
+          type: "object",
+          properties: {
+            id: { anyOf: [{ type: "string" }, { type: "number" }] },
+            name: nonEmptyString2
+          },
+          required: ["id", "name"],
+          additionalProperties: true
+        },
+        { type: "null" }
+      ]
+    },
+    workspaces: {
+      type: "array",
+      items: {
+        type: "object",
+        properties: {
+          id: { anyOf: [{ type: "string" }, { type: "number" }] },
+          name: nonEmptyString2,
+          isDefault: { type: "boolean" }
+        },
+        required: ["id", "name"],
+        additionalProperties: false
+      }
+    }
+  },
+  required: ["success", "contractVersion", "appId", "serviceName", "generatedAt", "widgets"],
+  additionalProperties: false
+});
 function createTopolo(options) {
   const client = new TopoloClient(options);
   return {
@@ -2400,10 +3254,15 @@ function createTopolo(options) {
   };
 }
 
-// node_modules/@topolo/sdk/dist/node/credential-store.js
-import { mkdir, readFile, writeFile, chmod, rm, stat } from "fs/promises";
+// node_modules/.pnpm/@topolo+sdk@0.21.0/node_modules/@topolo/sdk/dist/node/credential-store.js
+import { mkdir as mkdir2, readFile as readFile2, writeFile as writeFile2, chmod as chmod2, rm as rm2, stat } from "fs/promises";
+import { existsSync as existsSync2 } from "fs";
+import { homedir as homedir2, platform } from "os";
+import { dirname as dirname2, join as join2 } from "path";
+import { spawnSync } from "child_process";
+import { mkdir, readFile, readdir, rename, rm, writeFile, chmod } from "fs/promises";
 import { existsSync } from "fs";
-import { homedir, platform } from "os";
+import { homedir, platform as hostPlatform } from "os";
 import { dirname, join } from "path";
 var TopoloSdkError2 = class extends Error {
   code;
@@ -2523,10 +3382,10 @@ var TopoloAuthError2 = class extends TopoloSdkError2 {
 };
 function extractTopoloServiceErrorCode2(body) {
   if (!body || typeof body !== "object" || Array.isArray(body)) return null;
-  const record = body;
-  const topLevel = canonicalTopoloErrorCode2(record.code);
+  const record2 = body;
+  const topLevel = canonicalTopoloErrorCode2(record2.code);
   if (topLevel) return topLevel;
-  const nested = record.error;
+  const nested = record2.error;
   const nestedString = canonicalTopoloErrorCode2(nested);
   if (nestedString) return nestedString;
   if (nested && typeof nested === "object" && !Array.isArray(nested)) {
@@ -2541,14 +3400,14 @@ function serviceErrorCode2(body, fallback) {
 }
 function extractTopoloServiceErrorDetails2(body) {
   if (!body || typeof body !== "object" || Array.isArray(body)) return void 0;
-  const record = body;
-  let candidate = record.details;
-  const nested = record.error;
+  const record2 = body;
+  let candidate = record2.details;
+  const nested = record2.error;
   if (nested && typeof nested === "object" && !Array.isArray(nested)) {
     const nestedRecord = nested;
     if (candidate === void 0) candidate = nestedRecord.details ?? nestedRecord;
   }
-  if (candidate === void 0) candidate = record;
+  if (candidate === void 0) candidate = record2;
   if (Array.isArray(candidate)) {
     const paths = canonicalTopoloValidationPaths2(candidate);
     return paths.length ? { paths } : void 0;
@@ -2600,8 +3459,8 @@ function canonicalTopoloValidationPaths2(issues) {
   const paths = [];
   for (const issue of issues) {
     if (!issue || typeof issue !== "object" || Array.isArray(issue)) continue;
-    const record = issue;
-    const path = canonicalTopoloValidationPath2(record.field) ?? canonicalTopoloValidationPath2(record.path);
+    const record2 = issue;
+    const path = canonicalTopoloValidationPath2(record2.field) ?? canonicalTopoloValidationPath2(record2.path);
     if (path && !paths.includes(path)) paths.push(path);
     if (paths.length === 32) break;
   }
@@ -2811,18 +3670,150 @@ function topoloServiceOrigins2(serviceUrls, environment) {
     ])
   );
 }
+var KEYCHAIN_SERVICE = "topolo-external-agent-installation";
+function installationStorePath() {
+  const override = process.env.TOPOLO_INSTALLATIONS_PATH?.trim();
+  if (override) return override;
+  const base = process.env.XDG_CONFIG_HOME || (hostPlatform() === "win32" ? join(homedir(), "AppData", "Roaming") : join(homedir(), ".config"));
+  return join(base, "topolo", "installations");
+}
+function installationPath(environment, id) {
+  if (!/^[A-Za-z0-9_-]+$/.test(id)) throw new TypeError("Installation id contains unsupported characters.");
+  return join(installationStorePath(), environment, `${id}.json`);
+}
+function accountName(environment, id) {
+  return `${environment}:${id}`;
+}
+function runOrThrow(result, operation) {
+  if (result.status !== 0) {
+    throw new Error(`${operation} failed: ${(result.stderr || result.error?.message || "platform credential store unavailable").trim()}`);
+  }
+  return result.stdout.trim();
+}
+function createPlatformInstallationSecretBackend(options = {}) {
+  const platform2 = options.platform ?? hostPlatform();
+  const spawn = options.spawn ?? ((command, args, spawnOptions) => spawnSync(command, args, spawnOptions));
+  const root = options.root ?? installationStorePath();
+  if (platform2 === "darwin") {
+    return {
+      async set(account, value) {
+        runOrThrow(spawn("security", [
+          "add-generic-password",
+          "-U",
+          "-a",
+          account,
+          "-s",
+          KEYCHAIN_SERVICE,
+          "-w"
+        ], { input: `${value}
+`, encoding: "utf8" }), "macOS Keychain write");
+      },
+      async get(account) {
+        const result = spawn("security", [
+          "find-generic-password",
+          "-a",
+          account,
+          "-s",
+          KEYCHAIN_SERVICE,
+          "-w"
+        ], { encoding: "utf8" });
+        if (result.status === 44) return null;
+        return runOrThrow(result, "macOS Keychain read");
+      },
+      async delete(account) {
+        const result = spawn("security", [
+          "delete-generic-password",
+          "-a",
+          account,
+          "-s",
+          KEYCHAIN_SERVICE
+        ], { encoding: "utf8" });
+        if (result.status !== 44) runOrThrow(result, "macOS Keychain delete");
+      }
+    };
+  }
+  if (platform2 === "linux") {
+    return {
+      async set(account, value) {
+        runOrThrow(spawn("secret-tool", [
+          "store",
+          "--label=Topolo external agent installation",
+          "service",
+          KEYCHAIN_SERVICE,
+          "account",
+          account
+        ], { input: value, encoding: "utf8" }), "Linux Secret Service write");
+      },
+      async get(account) {
+        const result = spawn("secret-tool", [
+          "lookup",
+          "service",
+          KEYCHAIN_SERVICE,
+          "account",
+          account
+        ], { encoding: "utf8" });
+        if (result.status === 1) return null;
+        return runOrThrow(result, "Linux Secret Service read");
+      },
+      async delete(account) {
+        const result = spawn("secret-tool", [
+          "clear",
+          "service",
+          KEYCHAIN_SERVICE,
+          "account",
+          account
+        ], { encoding: "utf8" });
+        if (result.status !== 1) runOrThrow(result, "Linux Secret Service delete");
+      }
+    };
+  }
+  if (platform2 === "win32") {
+    const secretPath = (account) => join(root, ".secrets", `${account.replace(":", "-")}.bin`);
+    const powershell = (script, path, input) => spawn(
+      "powershell.exe",
+      ["-NoProfile", "-NonInteractive", "-Command", script],
+      { input, encoding: "utf8", env: { ...process.env, TOPOLO_SECRET_PATH: path } }
+    );
+    return {
+      async set(account, value) {
+        const path = secretPath(account);
+        await mkdir(dirname(path), { recursive: true });
+        const script = "$p=$env:TOPOLO_SECRET_PATH;$v=[Console]::In.ReadToEnd();$b=[Text.Encoding]::UTF8.GetBytes($v);$e=[Security.Cryptography.ProtectedData]::Protect($b,$null,[Security.Cryptography.DataProtectionScope]::CurrentUser);[IO.File]::WriteAllBytes($p,$e)";
+        runOrThrow(powershell(script, path, value), "Windows DPAPI write");
+      },
+      async get(account) {
+        const path = secretPath(account);
+        if (!existsSync(path)) return null;
+        const script = "$p=$env:TOPOLO_SECRET_PATH;$b=[IO.File]::ReadAllBytes($p);$d=[Security.Cryptography.ProtectedData]::Unprotect($b,$null,[Security.Cryptography.DataProtectionScope]::CurrentUser);[Console]::Out.Write([Text.Encoding]::UTF8.GetString($d))";
+        return runOrThrow(powershell(script, path), "Windows DPAPI read");
+      },
+      async delete(account) {
+        await rm(secretPath(account), { force: true });
+      }
+    };
+  }
+  throw new Error(`Secure external-agent installation storage is unsupported on ${platform2}.`);
+}
+async function readExternalAgentInstallation(environment, id, backend = createPlatformInstallationSecretBackend()) {
+  const path = installationPath(environment, id);
+  if (!existsSync(path)) return null;
+  const installation = JSON.parse(await readFile(path, "utf8"));
+  const encodedSecret = await backend.get(accountName(environment, id));
+  if (!encodedSecret) throw new Error(`Protected secret is missing for installation ${id}.`);
+  return { installation, secret: JSON.parse(encodedSecret) };
+}
 var ENVIRONMENT_DEFAULT_SERVICE_URLS = TOPOLO_ENVIRONMENT_SERVICE_URLS;
 function configPath() {
   const override = process.env.TOPOLO_CONFIG_PATH;
   if (override) return override;
-  const base = process.env.XDG_CONFIG_HOME || (platform() === "win32" ? join(homedir(), "AppData", "Roaming") : join(homedir(), ".config"));
-  return join(base, "topolo", "config.json");
+  const base = process.env.XDG_CONFIG_HOME || (platform() === "win32" ? join2(homedir2(), "AppData", "Roaming") : join2(homedir2(), ".config"));
+  return join2(base, "topolo", "config.json");
 }
 async function readConfig() {
   const path = configPath();
-  if (!existsSync(path)) return {};
+  if (!existsSync2(path)) return {};
   try {
-    const raw = await readFile(path, "utf8");
+    const raw = await readFile2(path, "utf8");
     return JSON.parse(raw);
   } catch {
     return {};
@@ -2830,11 +3821,11 @@ async function readConfig() {
 }
 async function writeConfig(config) {
   const path = configPath();
-  await mkdir(dirname(path), { recursive: true });
-  await writeFile(path, JSON.stringify(config, null, 2) + "\n", "utf8");
+  await mkdir2(dirname2(path), { recursive: true });
+  await writeFile2(path, JSON.stringify(config, null, 2) + "\n", "utf8");
   if (platform() !== "win32") {
     try {
-      await chmod(path, 384);
+      await chmod2(path, 384);
     } catch {
     }
   }
@@ -2905,18 +3896,18 @@ var CONFIG_LOCK_TIMEOUT_MS = 5e3;
 var CONFIG_LOCK_STALE_MS = 12e4;
 async function withConfigWriteLock(operation) {
   const lockPath = `${configPath()}.lock`;
-  await mkdir(dirname(lockPath), { recursive: true });
+  await mkdir2(dirname2(lockPath), { recursive: true });
   const startedAt = Date.now();
   while (true) {
     try {
-      await mkdir(lockPath);
+      await mkdir2(lockPath);
       break;
     } catch (error) {
       if (error.code !== "EEXIST") throw error;
       try {
         const lock = await stat(lockPath);
         if (Date.now() - lock.mtimeMs > CONFIG_LOCK_STALE_MS) {
-          await rm(lockPath, { recursive: true, force: true });
+          await rm2(lockPath, { recursive: true, force: true });
           continue;
         }
       } catch (inspectionError) {
@@ -2932,7 +3923,7 @@ async function withConfigWriteLock(operation) {
   try {
     return await operation();
   } finally {
-    await rm(lockPath, { recursive: true, force: true });
+    await rm2(lockPath, { recursive: true, force: true });
   }
 }
 async function refreshCredentialIfNeeded(environment = selectedEnvironment(), options = {}) {
@@ -3770,14 +4761,14 @@ function displayAppId(entry) {
 
 // src/version.ts
 import { readFileSync } from "fs";
-import { dirname as dirname2, join as join2 } from "path";
+import { dirname as dirname3, join as join3 } from "path";
 import { fileURLToPath } from "url";
 function readMcpVersion() {
   try {
-    const here = dirname2(fileURLToPath(import.meta.url));
+    const here = dirname3(fileURLToPath(import.meta.url));
     const candidates = [
-      join2(here, "package.json"),
-      join2(here, "..", "package.json")
+      join3(here, "package.json"),
+      join3(here, "..", "package.json")
     ];
     for (const path of candidates) {
       try {
@@ -3899,6 +4890,9 @@ function toolError(context, error) {
   };
 }
 
+// src/context-credential.ts
+import { randomUUID } from "crypto";
+
 // src/auth.ts
 function resolveCredentialFromEnv(environment = "production") {
   const prefix = environment === "production" ? "TOPOLO_PRODUCTION" : `TOPOLO_${environment.toUpperCase()}`;
@@ -3909,12 +4903,102 @@ function resolveCredentialFromEnv(environment = "production") {
   return null;
 }
 
+// src/installation-credential.ts
+function audienceFor(context) {
+  const actionAudience = context.actionId?.match(/^(app_[A-Za-z0-9_]+)\./)?.[1];
+  if (actionAudience) return actionAudience;
+  if (context.actionId) {
+    throw new TopoloMcpPublicError("The requested Topolo action has an invalid audience.");
+  }
+  const service = context.service.trim().toLowerCase();
+  if (/^app_[a-z0-9_]+$/.test(service)) return service;
+  if (!/^[a-z0-9_-]+$/.test(service)) {
+    throw new TopoloMcpPublicError("The requested Topolo service cannot be bound to this installation.");
+  }
+  return `app_topolo_${service.replace(/-/g, "_")}`;
+}
+function responseData(value) {
+  if (!value || typeof value !== "object") return {};
+  const record2 = value;
+  return record2.data && typeof record2.data === "object" ? record2.data : record2;
+}
+async function resolveExternalAgentInstallationCredential(environment, installationId, taskId, options = {}) {
+  const stored = await (options.readInstallation ?? readExternalAgentInstallation)(environment, installationId);
+  if (!stored) throw new TopoloMcpPublicError(`Installation ${installationId} is not registered on this device.`);
+  if (stored.installation.id !== installationId || stored.installation.environment !== environment) {
+    throw new TopoloMcpPublicError(`Installation ${installationId} is not registered for ${environment}.`);
+  }
+  if (!stored.installation.clientId.trim() || !stored.installation.organizationId.trim() || !/^[A-Za-z0-9_-]{43}$/.test(stored.installation.dpopJkt) || !stored.secret.clientSecret.trim() || !stored.secret.privateJwk.d) {
+    throw new TopoloMcpPublicError(`Installation ${installationId} is incomplete or corrupted.`);
+  }
+  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 cache = /* @__PURE__ */ new Map();
+  const credentialProvider = async (context) => {
+    const audience = audienceFor(context);
+    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 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,
+      audience,
+      task_id: boundTaskId,
+      resource_type: resource.resourceType,
+      resource_id: resource.resourceId,
+      dpop_jkt: stored.installation.dpopJkt
+    });
+    const response = await fetchImpl(tokenUrl, {
+      method: "POST",
+      headers: {
+        Accept: "application/json",
+        "Content-Type": "application/x-www-form-urlencoded"
+      },
+      body: body.toString()
+    });
+    const payload = await response.json().catch(() => null);
+    const data = responseData(payload);
+    const accessToken = typeof data.access_token === "string" ? data.access_token : "";
+    const expiresIn = Number(data.expires_in);
+    if (!response.ok || !accessToken || !Number.isFinite(expiresIn) || expiresIn <= 0) {
+      throw new TopoloMcpPublicError("The external-agent installation credential was rejected.");
+    }
+    const credential2 = {
+      kind: "dpop_access_token",
+      accessToken,
+      privateJwk: stored.secret.privateJwk
+    };
+    cache.set(key, { credential: credential2, expiresAt: now() + expiresIn * 1e3 });
+    return credential2;
+  };
+  const credential = await credentialProvider({
+    service: "auth",
+    method: "GET",
+    path: "/api/auth/me",
+    taskId,
+    resource: {
+      resourceType: "organization",
+      resourceId: stored.installation.organizationId
+    }
+  });
+  return { credential, credentialProvider, installation: stored.installation, taskId };
+}
+
 // src/context-credential.ts
 var DEFAULT_DEPENDENCIES = {
   readConfig,
   refreshContextCredentialIfNeeded,
   refreshCredentialIfNeeded,
-  resolveCredentialFromEnv
+  resolveCredentialFromEnv,
+  resolveInstallationCredential: resolveExternalAgentInstallationCredential
 };
 function resolvePinnedContextKey(profile, selector) {
   const normalized = selector.trim().toLowerCase();
@@ -3935,9 +5019,35 @@ function resolvePinnedContextKey(profile, selector) {
   }
   throw new TopoloMcpPublicError(`TOPOLO_CONTEXT "${selector}" is not signed in for this environment`);
 }
-async function resolveMcpCredential(environment, selector = process.env.TOPOLO_CONTEXT, dependencies = DEFAULT_DEPENDENCIES) {
+async function resolveMcpCredential(environment, selector = process.env.TOPOLO_CONTEXT, dependencies = DEFAULT_DEPENDENCIES, installationSelector = process.env.TOPOLO_AGENT_INSTALLATION_ID, taskSelector = process.env.TOPOLO_AGENT_TASK_ID) {
   const environmentCredential = dependencies.resolveCredentialFromEnv(environment);
   const requestedSelector = selector?.trim();
+  const installationId = installationSelector?.trim();
+  if (installationId) {
+    if (requestedSelector || environmentCredential) {
+      throw new TopoloMcpPublicError(
+        "TOPOLO_AGENT_INSTALLATION_ID cannot be combined with TOPOLO_CONTEXT or an environment credential"
+      );
+    }
+    const taskId = taskSelector?.trim() || `task_${randomUUID()}`;
+    const config2 = await dependencies.readConfig();
+    const serviceUrls = resolveServiceUrls(
+      profileForEnvironment(config2, environment).serviceUrls,
+      environment
+    );
+    const resolved = await dependencies.resolveInstallationCredential(
+      environment,
+      installationId,
+      taskId,
+      { serviceUrls }
+    );
+    return {
+      credential: resolved.credential,
+      contextKey: null,
+      credentialProvider: resolved.credentialProvider,
+      taskId: resolved.taskId
+    };
+  }
   if (environmentCredential) {
     if (requestedSelector) {
       throw new TopoloMcpPublicError("TOPOLO_CONTEXT cannot be combined with an environment credential");
@@ -4040,6 +5150,10 @@ async function runStdioMcp(dependencies = DEFAULT_DEPENDENCIES2) {
   const topolo = dependencies.createTopolo({
     credential,
     environment,
+    actorContext: {
+      channel: "mcp",
+      ...resolvedCredential.taskId ? { taskId: resolvedCredential.taskId } : {}
+    },
     agent: {
       clientName: "topolo-mcp",
       clientVersion: MCP_VERSION,