@topolo/cli 0.10.1 → 0.12.0

package/dist/index.js

@@ -9,13 +9,13 @@ import { platform as platform2 } from "os";
 import { createInterface } from "readline/promises";
 import { stdin as input } from "process";
 
-// node_modules/.pnpm/@topolo+sdk@0.14.4/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}`);
@@ -28,6 +28,58 @@ 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 calculateDpopJkt(privateJwk) {
+  const jwk = publicJwk(privateJwk);
+  return sha256Base64Url(JSON.stringify({ crv: jwk.crv, kty: jwk.kty, x: jwk.x, y: jwk.y }));
+}
+async function createDpopProof(input2) {
+  const jwk = publicJwk(input2.privateJwk);
+  const key = await crypto.subtle.importKey(
+    "jwk",
+    input2.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: input2.method.toUpperCase(),
+    htu: canonicalTargetUrl(input2.targetUrl),
+    ath: await sha256Base64Url(input2.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, message2) {
@@ -173,10 +225,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)) {
@@ -191,14 +243,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;
@@ -250,8 +302,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;
   }
@@ -718,6 +770,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, message2) {
+    super(`${path}: ${message2}`);
+    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, message2) {
+  throw new ActorEnvelopeValidationError(path, message2);
+}
 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.");
@@ -922,6 +1190,7 @@ var NEGATIVE_CACHE_TTL_MS = 60 * 1e3;
 var TopoloClient = class _TopoloClient {
   credential;
   agent;
+  actorContext;
   serviceUrls;
   environment;
   appIds;
@@ -929,7 +1198,7 @@ var TopoloClient = class _TopoloClient {
   timeoutMs;
   fetchImpl;
   credentialProvider;
-  credentialLoadInFlight = null;
+  credentialLoadsInFlight = /* @__PURE__ */ new Map();
   refreshCredential;
   refreshInFlight = null;
   debug;
@@ -952,6 +1221,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;
@@ -981,7 +1255,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}/`);
@@ -1004,12 +1287,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();
@@ -1034,9 +1320,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
         });
@@ -1067,13 +1363,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();
         }
       }
@@ -1163,18 +1459,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) {
@@ -1456,14 +1757,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. */
@@ -1504,6 +1805,14 @@ var TopoloClient = class _TopoloClient {
     const entry = await this.getAction(action);
     return this.executeResolvedAction(entry, input2, options);
   }
+  async issueExternalAgentCredential(input2) {
+    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, input2, { confirm: true }, true);
+  }
   async uploadAction(action, content, input2, options) {
     const entry = await this.getAction(action);
     const contract = parseTopoloActionUploadContract(entry.agentContract?.upload);
@@ -1635,7 +1944,7 @@ var TopoloClient = class _TopoloClient {
     }
     return this.executeResolvedAction(entry, input2, options);
   }
-  async executeResolvedAction(entry, input2, options) {
+  async executeResolvedAction(entry, input2, options, preserveSensitiveResult = false) {
     const agentAccess = entry.agentAccess ?? (entry.destructive ? "off" : entry.readOnly && !entry.requiresConfirmation ? "auto" : "confirm");
     if (agentAccess === "off") {
       throw new TopoloPermissionError(
@@ -1663,6 +1972,20 @@ var TopoloClient = class _TopoloClient {
       );
     }
     const mapped = mapActionInput(entry, input2);
+    const resolvedActorEnvelope = options.actorEnvelope ?? await this.buildVerifiedAgentActorEnvelope(entry.actionId, input2, 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(input2)) {
+        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,
@@ -1672,13 +1995,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, input2, 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(input2)
+      },
+      issuedAt: (/* @__PURE__ */ new Date()).toISOString()
+    });
   }
   /**
    * Introspect the current credential. Returns the caller's resolved identity,
@@ -1707,7 +2081,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,
@@ -2072,6 +2457,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;
@@ -2090,16 +2478,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);
       }
     }
@@ -2174,8 +2568,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);
@@ -2184,7 +2578,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;
   }
@@ -2948,10 +3342,15 @@ function createTopolo(options) {
   };
 }
 
-// node_modules/.pnpm/@topolo+sdk@0.14.4/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;
@@ -3071,10 +3470,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)) {
@@ -3089,14 +3488,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;
@@ -3148,8 +3547,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;
   }
@@ -3360,6 +3759,157 @@ 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 platform22 = options.platform ?? hostPlatform();
+  const spawn2 = options.spawn ?? ((command, args, spawnOptions) => spawnSync(command, args, spawnOptions));
+  const root = options.root ?? installationStorePath();
+  if (platform22 === "darwin") {
+    return {
+      async set(account, value) {
+        runOrThrow(spawn2("security", [
+          "add-generic-password",
+          "-U",
+          "-a",
+          account,
+          "-s",
+          KEYCHAIN_SERVICE,
+          "-w"
+        ], { input: `${value}
+`, encoding: "utf8" }), "macOS Keychain write");
+      },
+      async get(account) {
+        const result = spawn2("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 = spawn2("security", [
+          "delete-generic-password",
+          "-a",
+          account,
+          "-s",
+          KEYCHAIN_SERVICE
+        ], { encoding: "utf8" });
+        if (result.status !== 44) runOrThrow(result, "macOS Keychain delete");
+      }
+    };
+  }
+  if (platform22 === "linux") {
+    return {
+      async set(account, value) {
+        runOrThrow(spawn2("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 = spawn2("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 = spawn2("secret-tool", [
+          "clear",
+          "service",
+          KEYCHAIN_SERVICE,
+          "account",
+          account
+        ], { encoding: "utf8" });
+        if (result.status !== 1) runOrThrow(result, "Linux Secret Service delete");
+      }
+    };
+  }
+  if (platform22 === "win32") {
+    const secretPath = (account) => join(root, ".secrets", `${account.replace(":", "-")}.bin`);
+    const powershell = (script, path, input2) => spawn2(
+      "powershell.exe",
+      ["-NoProfile", "-NonInteractive", "-Command", script],
+      { input: input2, 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 ${platform22}.`);
+}
+async function writeExternalAgentInstallation(installation, secret, backend = createPlatformInstallationSecretBackend()) {
+  const path = installationPath(installation.environment, installation.id);
+  await backend.set(accountName(installation.environment, installation.id), JSON.stringify(secret));
+  const temporary = `${path}.${process.pid}.tmp`;
+  try {
+    await mkdir(dirname(path), { recursive: true, mode: 448 });
+    await writeFile(temporary, `${JSON.stringify(installation, null, 2)}
+`, { encoding: "utf8", mode: 384 });
+    await rename(temporary, path);
+    if (hostPlatform() !== "win32") await chmod(path, 384);
+  } catch (error) {
+    await backend.delete(accountName(installation.environment, installation.id)).catch(() => void 0);
+    await rm(temporary, { force: true });
+    throw error;
+  }
+}
+async function listExternalAgentInstallations(environment) {
+  const directory = join(installationStorePath(), environment);
+  if (!existsSync(directory)) return [];
+  const entries = await readdir(directory, { withFileTypes: true });
+  const installations = await Promise.all(entries.filter((entry) => entry.isFile() && entry.name.endsWith(".json")).map(async (entry) => JSON.parse(await readFile(join(directory, entry.name), "utf8"))));
+  return installations.sort((left, right) => left.createdAt.localeCompare(right.createdAt));
+}
+async function deleteExternalAgentInstallation(environment, id, backend = createPlatformInstallationSecretBackend()) {
+  await backend.delete(accountName(environment, id));
+  await rm(installationPath(environment, id), { force: true });
+}
 var TOPOLO_ENVIRONMENTS = TOPOLO_RUNTIME_ENVIRONMENTS;
 function contextKey(contextType, organizationId) {
   return contextType === "organization" && organizationId ? `org:${organizationId}` : "personal";
@@ -3368,14 +3918,14 @@ 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 {};
@@ -3383,11 +3933,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 {
     }
   }
@@ -3493,18 +4043,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) {
@@ -3520,7 +4070,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 = {}) {
@@ -3725,7 +4275,7 @@ function installOutputErrorHandlers(stdout = process.stdout, stderr = process.st
   stdout.on("error", handler);
   stderr.on("error", handler);
 }
-function fail(err, mode) {
+function fail2(err, mode) {
   const payload = normalizeError(err);
   if (mode === "json") {
     process.stderr.write(JSON.stringify({ error: payload }, null, 2) + "\n");
@@ -3772,14 +4322,14 @@ function normalizeError(err) {
 
 // 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 readCliVersion() {
   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 {
@@ -3834,7 +4384,7 @@ Visit ${apiKeyIssuanceUrl(environment)} to mint one, or configure an OAuth clien
           openBrowser: opts.browser !== false
         });
       } catch (err) {
-        fail(err, mode);
+        fail2(err, mode);
       }
     }
   );
@@ -3850,7 +4400,7 @@ Visit ${apiKeyIssuanceUrl(environment)} to mint one, or configure an OAuth clien
         () => `Logged out of Topolo ${environmentLabel(environment)}.`
       );
     } catch (err) {
-      fail(err, mode);
+      fail2(err, mode);
     }
   });
   auth.command("status").description("Show which credential source is in use (env vs config file)").option("--json", "Output JSON").option("--no-json", "Output human-readable text").action(async (opts) => {
@@ -3876,7 +4426,7 @@ Visit ${apiKeyIssuanceUrl(environment)} to mint one, or configure an OAuth clien
         ].join("\n")
       );
     } catch (err) {
-      fail(err, mode);
+      fail2(err, mode);
     }
   });
 }
@@ -4068,6 +4618,7 @@ async function buildClient(options) {
   return createTopolo({
     credential,
     environment,
+    actorContext: { channel: "cli" },
     agent: {
       clientName: "topolo-cli",
       clientVersion: CLI_VERSION,
@@ -4125,7 +4676,7 @@ function registerWhoamiCommand(program2) {
       const info = await topolo.identity.whoami();
       emit(info, mode, () => formatPretty(info));
     } catch (err) {
-      fail(err, mode);
+      fail2(err, mode);
     }
   });
 }
@@ -4206,7 +4757,7 @@ function registerApiCommand(program2) {
         });
         emit(result, mode, () => JSON.stringify(result, null, 2));
       } catch (err) {
-        fail(err, mode);
+        fail2(err, mode);
       }
     }
   );
@@ -4270,7 +4821,7 @@ function registerActionsCommand(program2) {
       const output = opts.detail ? { ...result, actions: actions2 } : { actions: actions2.map(compactActionCatalogEntry), page: result.page };
       emit(output, mode, () => formatActionRows(actions2, result.page.nextCursor));
     } catch (err) {
-      fail(err, mode);
+      fail2(err, mode);
     }
   });
   actions.command("get <action>").description("Describe one Topolo action by exact action id").option("--json", "Output JSON").option("--no-json", "Output human-readable text").action(async (action, opts, command) => {
@@ -4283,7 +4834,7 @@ function registerActionsCommand(program2) {
       const entry = await topolo.client.getAction(action);
       emit(entry, mode, () => formatActionDetail(entry));
     } catch (err) {
-      fail(err, mode);
+      fail2(err, mode);
     }
   });
   actions.command("call <action>").description("Call a permission-scoped Topolo action").option("-d, --data <json-or-@file>", "JSON action input or @path to a JSON file", "{}").option("--resource-type <type>", "App-local resource alias, such as workspace").option("--resource-id <id>", "Resource id for the selected resource type").option("--confirm", "Acknowledge a mutating action").option("--detail", "Return the complete action response instead of a bounded agent projection").option("--json", "Output JSON").option("--no-json", "Output human-readable text").action(async (action, opts, command) => {
@@ -4302,7 +4853,7 @@ function registerActionsCommand(program2) {
       const output = detailRequested(opts.detail, command) ? result : compactActionResult(action, result);
       emit(output, mode, () => JSON.stringify(output, null, 2));
     } catch (err) {
-      fail(err, mode);
+      fail2(err, mode);
     }
   });
   actions.command("upload <action>").description("Upload one local file through an action-declared upload contract").requiredOption("--file <path>", "Local file to upload").option("--content-type <type>", "MIME type; inferred for common file extensions").option("-d, --data <json-or-@file>", "Additional JSON action input or @path to a JSON file", "{}").option("--complete-data <json-or-@file>", "Additional input for a declared completion action", "{}").option("--resource-type <type>", "App-local resource alias, such as workspace").option("--resource-id <id>", "Resource id for the selected resource type").option("--confirm", "Acknowledge a mutating upload action").option("--json", "Output JSON").option("--no-json", "Output human-readable text").action(async (action, opts, command) => {
@@ -4326,7 +4877,7 @@ function registerActionsCommand(program2) {
       );
       emit(result, mode, () => JSON.stringify(result, null, 2));
     } catch (err) {
-      fail(err, mode);
+      fail2(err, mode);
     }
   });
   actions.command("validate <action>").description("Validate action input locally against the published JSON Schema").option("-d, --data <json-or-@file>", "JSON action input or @path to a JSON file", "{}").option("--detail", "Include the full action contract").option("--json", "Output JSON").option("--no-json", "Output human-readable text").action(async (action, opts, command) => {
@@ -4337,7 +4888,7 @@ function registerActionsCommand(program2) {
       const output = detailRequested(opts.detail, command) ? result : compactActionValidation(result.action.actionId, result.validation);
       emit(output, mode, () => result.validation.valid ? `Valid input for ${result.action.actionId}.` : result.validation.errors.map((issue) => `${issue.path}: ${issue.message}`).join("\n"));
     } catch (err) {
-      fail(err, mode);
+      fail2(err, mode);
     }
   });
   actions.command("prepare <action>").description("Prepare one action with identity, example, validation, exact request, verification, and rollback").option("-d, --data <json-or-@file>", "JSON action input or @path; defaults to one valid published example").option("--resource-type <type>", "App-local resource alias, such as workspace").option("--resource-id <id>", "Resource id for the selected resource type").option("--confirm", "Include confirmation in the plan without executing it").option("--json", "Output compact JSON").option("--no-json", "Output human-readable text").action(async (action, opts, command) => {
@@ -4353,7 +4904,7 @@ function registerActionsCommand(program2) {
       const output = compactActionPreparation(preparation, await actionExecutionContext(topolo));
       emit(output, mode, () => formatActionPreparation(output));
     } catch (err) {
-      fail(err, mode);
+      fail2(err, mode);
     }
   });
   actions.command("plan <action>").description("Validate and preview the exact request, confirmation, verification, and rollback plan").option("-d, --data <json-or-@file>", "JSON action input or @path to a JSON file", "{}").option("--resource-type <type>", "App-local resource alias, such as workspace").option("--resource-id <id>", "Resource id for the selected resource type").option("--confirm", "Include confirmation in the plan without executing it").option("--detail", "Include the full action contract").option("--json", "Output JSON").option("--no-json", "Output human-readable text").action(async (action, opts, command) => {
@@ -4367,7 +4918,7 @@ function registerActionsCommand(program2) {
       });
       emit(detailRequested(opts.detail, command) ? plan : compactActionPlan(plan), mode, () => formatActionPlan(plan));
     } catch (err) {
-      fail(err, mode);
+      fail2(err, mode);
     }
   });
   actions.command("examples <action>").description("Show published examples and public docs for one action").option("--json", "Output JSON").option("--no-json", "Output human-readable text").action(async (action, opts, command) => {
@@ -4382,7 +4933,7 @@ function registerActionsCommand(program2) {
       };
       emit(result, mode, () => result.examples.length ? JSON.stringify(result, null, 2) : `No inline examples published. Docs: ${result.docsUrl || "not published"}`);
     } catch (err) {
-      fail(err, mode);
+      fail2(err, mode);
     }
   });
   actions.command("capabilities").description("List every published action for one application (its capability contract)").option("-s, --service <service>", "App id, slug, or name").option("--summary", "Return compact capability counts without action rows").option("--detail", "Include full schemas and agent contracts").option("--json", "Output JSON").option("--no-json", "Output human-readable table").action(async (opts, command) => {
@@ -4417,7 +4968,7 @@ function registerActionsCommand(program2) {
       const output = opts.summary ? summarizeActionCapabilities(resolvedService, discovered) : detailRequested(opts.detail, command) ? result : { actions: discovered.map(compactActionCatalogEntry), page: result.page };
       emit(output, mode, () => opts.summary ? formatActionCapabilitySummary(summarizeActionCapabilities(resolvedService, discovered)) : formatActionRows(discovered));
     } catch (err) {
-      fail(err, mode);
+      fail2(err, mode);
     }
   });
 }
@@ -4605,7 +5156,7 @@ function registerAppsCommand(program2) {
       const applications = publicApplicationRows(result.services);
       emit({ applications, page: result.page }, mode, () => formatPublicApplicationRows(applications));
     } catch (error) {
-      fail(error, mode);
+      fail2(error, mode);
     }
   });
   apps.command("get <application>").description("Show one application available to the current Topolo credential").option("--json", "Output JSON", true).option("--no-json", "Output human-readable details").action(async (application, opts) => {
@@ -4617,7 +5168,7 @@ function registerAppsCommand(program2) {
       if (!selected) throw new Error(`Application "${application}" is not a customer application.`);
       emit({ application: selected }, mode, () => formatPublicApplication(selected));
     } catch (error) {
-      fail(error, mode);
+      fail2(error, mode);
     }
   });
 }
@@ -4676,7 +5227,7 @@ function registerServicesCommand(program2) {
       const rows = buildRows(result.services, config.serviceUrls, environment);
       emit({ environment, services: rows, page: result.page }, mode, () => formatRows(rows, environment, result.page.nextCursor));
     } catch (err) {
-      fail(err, mode);
+      fail2(err, mode);
     }
   });
 }
@@ -4769,7 +5320,7 @@ function registerOAuthCommands(program2) {
         return clients2.map((client) => `${client.client_id}	${client.name}	${client.status}`).join("\n");
       });
     } catch (err) {
-      fail(err, mode);
+      fail2(err, mode);
     }
   });
   clients.command("create").description("Create a Login with Topolo OAuth client.").requiredOption("--name <name>", "Client display name").requiredOption("--developer-id <id>", "Topolo developer id that owns this client").option("--developer-app-id <id>", "Developer app id to associate with this client").option("--description <description>", "Client description").option("--redirect-uri <uri...>", "Allowed callback URI. Repeat or pass a space-separated list.").option("--scope <scope...>", "Allowed scope. Defaults to openid profile email.").option("--public", "Create a public PKCE client instead of a confidential client").option("--homepage-url <url>", "Client homepage URL").option("--logo-url <url>", "Client logo URL").option("--json", "Emit JSON output").action(async (options) => {
@@ -4789,7 +5340,7 @@ function registerOAuthCommands(program2) {
         ].join("\n");
       });
     } catch (err) {
-      fail(err, mode);
+      fail2(err, mode);
     }
   });
   clients.command("revoke").description("Revoke an OAuth client for all users.").argument("<id>", "OAuth client record id, for example oac_...").option("--json", "Emit JSON output").action(async (id, options) => {
@@ -4800,7 +5351,7 @@ function registerOAuthCommands(program2) {
       });
       emit(payload, mode, () => `Revoked OAuth client ${id}`);
     } catch (err) {
-      fail(err, mode);
+      fail2(err, mode);
     }
   });
   clients.command("rotate-secret").description("Rotate a confidential OAuth client secret.").argument("<id>", "OAuth client record id, for example oac_...").option("--json", "Emit JSON output").action(async (id, options) => {
@@ -4811,7 +5362,7 @@ function registerOAuthCommands(program2) {
       });
       emit(payload, mode, () => `New client secret: ${payload.data?.client_secret ?? ""}`);
     } catch (err) {
-      fail(err, mode);
+      fail2(err, mode);
     }
   });
 }
@@ -4856,8 +5407,8 @@ async function authFetchJson(path, init = {}) {
   }
   headers.set("Authorization", `Bearer ${credential.accessToken}`);
   const response = await fetch(`${authBaseUrl}${path}`, { ...init, headers });
-  const text = await response.text();
-  const payload = text ? JSON.parse(text) : {};
+  const text2 = await response.text();
+  const payload = text2 ? JSON.parse(text2) : {};
   if (!response.ok || payload.success === false) {
     const err = new Error(payload.message || payload.error_description || payload.error || "Topolo Auth request failed");
     err.code = payload.code || payload.error;
@@ -4871,8 +5422,8 @@ function normalizeList(values, fallback = []) {
 }
 
 // src/commands/integrations.ts
-import { readdir, readFile as readFile2, stat as stat2 } from "fs/promises";
-import { join as join3, relative } from "path";
+import { readdir as readdir2, readFile as readFile3, stat as stat2 } from "fs/promises";
+import { join as join4, relative } from "path";
 function registerIntegrationsCommand(program2) {
   const integrations = program2.command("integrations").description("Generate and validate Topolo integration handoffs.");
   integrations.command("prompt").description("Print an agent prompt for adding a Topolo integration.").argument("<integration>", "Integration prompt id, currently login-with-topolo").option("--framework <framework>", "auto, authjs, express, or generic", "auto").option("--json", "Emit JSON output").action((integration, options) => {
@@ -4883,7 +5434,7 @@ function registerIntegrationsCommand(program2) {
       const prompt = buildLoginWithTopoloPrompt(framework);
       emit({ integration, framework, prompt }, mode, () => prompt);
     } catch (err) {
-      fail(err, mode);
+      fail2(err, mode);
     }
   });
   integrations.command("check").description("Check whether a repo has the Login with Topolo integration pieces.").argument("<integration>", "Integration check id, currently login-with-topolo").option("--repo-root <path>", "Repository root to inspect", ".").option("--json", "Emit JSON output").action(async (integration, options) => {
@@ -4894,7 +5445,7 @@ function registerIntegrationsCommand(program2) {
       emit(result, mode, () => formatCheckResult(result));
       if (!result.passed) process.exitCode = 1;
     } catch (err) {
-      fail(err, mode);
+      fail2(err, mode);
     }
   });
 }
@@ -5015,7 +5566,7 @@ function detectFramework(packageJson, haystack) {
 }
 async function readPackageJson(repoRoot) {
   try {
-    return JSON.parse(await readFile2(join3(repoRoot, "package.json"), "utf8"));
+    return JSON.parse(await readFile3(join4(repoRoot, "package.json"), "utf8"));
   } catch {
     return null;
   }
@@ -5025,9 +5576,9 @@ async function collectFiles(repoRoot) {
   const root = repoRoot;
   async function walk(dir) {
     if (result.length > 2e3) return;
-    const entries = await readdir(dir, { withFileTypes: true });
+    const entries = await readdir2(dir, { withFileTypes: true });
     for (const entry of entries) {
-      const fullPath = join3(dir, entry.name);
+      const fullPath = join4(dir, entry.name);
       if (entry.isDirectory()) {
         if ([".git", "node_modules", "dist", "build", ".next", "coverage"].includes(entry.name)) continue;
         await walk(fullPath);
@@ -5038,7 +5589,7 @@ async function collectFiles(repoRoot) {
       if (info.size > 25e4) continue;
       result.push({
         path: relative(root, fullPath),
-        content: await readFile2(fullPath, "utf8")
+        content: await readFile3(fullPath, "utf8")
       });
     }
   }
@@ -5054,20 +5605,20 @@ function formatCheckResult(result) {
 }
 
 // src/commands/skills.ts
-import { spawnSync as spawnSync2 } from "child_process";
-import { existsSync as existsSync4 } from "fs";
-import { readFile as readFile5, rm as rm2 } from "fs/promises";
-import { homedir as homedir3 } from "os";
-import { dirname as dirname4, join as join5, resolve } from "path";
+import { spawnSync as spawnSync3 } from "child_process";
+import { existsSync as existsSync5 } from "fs";
+import { readFile as readFile6, rm as rm3 } from "fs/promises";
+import { homedir as homedir4 } from "os";
+import { dirname as dirname5, join as join6, resolve } from "path";
 import { fileURLToPath as fileURLToPath2 } from "url";
 import { createRequire } from "module";
 
 // src/commands/agent-host.ts
-import { spawnSync } from "child_process";
-import { existsSync as existsSync2 } from "fs";
-import { readFile as readFile3 } from "fs/promises";
-import { homedir as homedir2 } from "os";
-import { isAbsolute, join as join4 } from "path";
+import { spawnSync as spawnSync2 } from "child_process";
+import { existsSync as existsSync3 } from "fs";
+import { readFile as readFile4 } from "fs/promises";
+import { homedir as homedir3 } from "os";
+import { isAbsolute, join as join5 } from "path";
 var SUPPORTED_AGENT_IDS = [
   "claude",
   "claude-desktop",
@@ -5116,41 +5667,41 @@ function selectStableNodeCommand(whichOutput, fallback = process.execPath) {
   return candidate && isAbsolute(candidate) ? candidate : fallback;
 }
 function stableNodeCommand() {
-  const probe = spawnSync(process.platform === "win32" ? "where" : "which", ["node"], {
+  const probe = spawnSync2(process.platform === "win32" ? "where" : "which", ["node"], {
     encoding: "utf8",
     stdio: ["ignore", "pipe", "ignore"]
   });
   return selectStableNodeCommand(probe.status === 0 ? probe.stdout : void 0);
 }
-function agentSkillPath(agent, homeDir = homedir2(), projectDir) {
+function agentSkillPath(agent, homeDir = homedir3(), projectDir) {
   switch (agent) {
     case "claude":
-      return projectDir ? join4(projectDir, ".claude", "skills", "topolo", "SKILL.md") : join4(homeDir, ".claude", "skills", "topolo", "SKILL.md");
+      return projectDir ? join5(projectDir, ".claude", "skills", "topolo", "SKILL.md") : join5(homeDir, ".claude", "skills", "topolo", "SKILL.md");
     case "claude-desktop":
-      return join4(homeDir, ".claude", "skills", "topolo", "SKILL.md");
+      return join5(homeDir, ".claude", "skills", "topolo", "SKILL.md");
     case "codex":
-      return join4(homeDir, ".codex", "skills", "topolo", "SKILL.md");
+      return join5(homeDir, ".codex", "skills", "topolo", "SKILL.md");
     case "cursor":
-      return join4(projectDir ?? homeDir, ".cursor", "rules", "topolo.mdc");
+      return join5(projectDir ?? homeDir, ".cursor", "rules", "topolo.mdc");
     case "grok":
-      return join4(projectDir ?? homeDir, ".grok", "skills", "topolo", "SKILL.md");
+      return join5(projectDir ?? homeDir, ".grok", "skills", "topolo", "SKILL.md");
     case "gemini":
-      return join4(projectDir ?? homeDir, ".gemini", "skills", "topolo", "SKILL.md");
+      return join5(projectDir ?? homeDir, ".gemini", "skills", "topolo", "SKILL.md");
     case "copilot":
-      return projectDir ? join4(projectDir, ".github", "skills", "topolo", "SKILL.md") : join4(homeDir, ".copilot", "skills", "topolo", "SKILL.md");
+      return projectDir ? join5(projectDir, ".github", "skills", "topolo", "SKILL.md") : join5(homeDir, ".copilot", "skills", "topolo", "SKILL.md");
     case "windsurf":
-      return projectDir ? join4(projectDir, ".windsurf", "rules", "topolo.md") : void 0;
+      return projectDir ? join5(projectDir, ".windsurf", "rules", "topolo.md") : void 0;
     case "cline":
-      return join4(projectDir ?? homeDir, ".cline", "skills", "topolo", "SKILL.md");
+      return join5(projectDir ?? homeDir, ".cline", "skills", "topolo", "SKILL.md");
     case "goose":
     case "amazon-q":
       return void 0;
   }
 }
-function agentConfigPaths(agent, homeDir = homedir2(), projectDir) {
+function agentConfigPaths(agent, homeDir = homedir3(), projectDir) {
   switch (agent) {
     case "claude":
-      return [{ path: join4(homeDir, ".claude.json"), format: "json", rootKey: "mcpServers" }];
+      return [{ path: join5(homeDir, ".claude.json"), format: "json", rootKey: "mcpServers" }];
     case "claude-desktop":
       return [{
         path: claudeDesktopConfigPath(homeDir),
@@ -5158,31 +5709,31 @@ function agentConfigPaths(agent, homeDir = homedir2(), projectDir) {
         rootKey: "mcpServers"
       }];
     case "codex":
-      return [{ path: join4(homeDir, ".codex", "config.toml"), format: "toml" }];
+      return [{ path: join5(homeDir, ".codex", "config.toml"), format: "toml" }];
     case "cursor":
       return [{
-        path: projectDir ? join4(projectDir, ".cursor", "mcp.json") : join4(homeDir, ".cursor", "mcp.json"),
+        path: projectDir ? join5(projectDir, ".cursor", "mcp.json") : join5(homeDir, ".cursor", "mcp.json"),
         format: "json",
         rootKey: "mcpServers"
       }];
     case "grok":
       return [{
-        path: projectDir ? join4(projectDir, ".grok", "config.toml") : join4(homeDir, ".grok", "config.toml"),
+        path: projectDir ? join5(projectDir, ".grok", "config.toml") : join5(homeDir, ".grok", "config.toml"),
         format: "toml"
       }];
     case "gemini":
       return [{
-        path: projectDir ? join4(projectDir, ".gemini", "settings.json") : join4(homeDir, ".gemini", "settings.json"),
+        path: projectDir ? join5(projectDir, ".gemini", "settings.json") : join5(homeDir, ".gemini", "settings.json"),
         format: "json",
         rootKey: "mcpServers"
       }];
     case "copilot":
       return projectDir ? [
-        { path: join4(projectDir, ".mcp.json"), format: "json", rootKey: "mcpServers" },
-        { path: join4(projectDir, ".vscode", "mcp.json"), format: "json", rootKey: "servers" }
+        { path: join5(projectDir, ".mcp.json"), format: "json", rootKey: "mcpServers" },
+        { path: join5(projectDir, ".vscode", "mcp.json"), format: "json", rootKey: "servers" }
       ] : [
         {
-          path: join4(homeDir, ".copilot", "mcp-config.json"),
+          path: join5(homeDir, ".copilot", "mcp-config.json"),
           format: "json",
           rootKey: "mcpServers"
         },
@@ -5190,24 +5741,24 @@ function agentConfigPaths(agent, homeDir = homedir2(), projectDir) {
       ];
     case "windsurf":
       return [{
-        path: join4(homeDir, ".codeium", "windsurf", "mcp_config.json"),
+        path: join5(homeDir, ".codeium", "windsurf", "mcp_config.json"),
         format: "json",
         rootKey: "mcpServers"
       }];
     case "cline":
       return [{
-        path: projectDir ? join4(projectDir, ".cline", "mcp.json") : join4(homeDir, ".cline", "mcp.json"),
+        path: projectDir ? join5(projectDir, ".cline", "mcp.json") : join5(homeDir, ".cline", "mcp.json"),
         format: "json",
         rootKey: "mcpServers"
       }];
     case "goose":
-      return [{ path: join4(homeDir, ".config", "goose", "config.yaml"), format: "yaml" }];
+      return [{ path: join5(homeDir, ".config", "goose", "config.yaml"), format: "yaml" }];
     case "amazon-q":
       if (projectDir) {
-        return [{ path: join4(projectDir, ".amazonq", "mcp.json"), format: "json", rootKey: "mcpServers" }];
+        return [{ path: join5(projectDir, ".amazonq", "mcp.json"), format: "json", rootKey: "mcpServers" }];
       }
       return [{
-        path: existsSync2(join4(homeDir, ".aws", "amazonq", "mcp.json")) ? join4(homeDir, ".aws", "amazonq", "mcp.json") : join4(homeDir, ".aws", "amazonq", "default.json"),
+        path: existsSync3(join5(homeDir, ".aws", "amazonq", "mcp.json")) ? join5(homeDir, ".aws", "amazonq", "mcp.json") : join5(homeDir, ".aws", "amazonq", "default.json"),
         format: "json",
         rootKey: "mcpServers"
       }];
@@ -5239,23 +5790,23 @@ function agentCliNames(agent) {
       return ["qchat", "q"];
   }
 }
-function agentConfigExists(agent, homeDir = homedir2(), projectDir) {
-  return agentConfigPaths(agent, homeDir, projectDir).some((config) => existsSync2(config.path));
+function agentConfigExists(agent, homeDir = homedir3(), projectDir) {
+  return agentConfigPaths(agent, homeDir, projectDir).some((config) => existsSync3(config.path));
 }
 function claudeDesktopConfigPath(homeDir) {
-  if (process.platform === "darwin") return join4(homeDir, "Library", "Application Support", "Claude", "claude_desktop_config.json");
-  if (process.platform === "win32") return join4(process.env.APPDATA ?? join4(homeDir, "AppData", "Roaming"), "Claude", "claude_desktop_config.json");
-  return join4(process.env.XDG_CONFIG_HOME ?? join4(homeDir, ".config"), "Claude", "claude_desktop_config.json");
+  if (process.platform === "darwin") return join5(homeDir, "Library", "Application Support", "Claude", "claude_desktop_config.json");
+  if (process.platform === "win32") return join5(process.env.APPDATA ?? join5(homeDir, "AppData", "Roaming"), "Claude", "claude_desktop_config.json");
+  return join5(process.env.XDG_CONFIG_HOME ?? join5(homeDir, ".config"), "Claude", "claude_desktop_config.json");
 }
 function vscodeUserConfigPath(homeDir) {
-  if (process.platform === "darwin") return join4(homeDir, "Library", "Application Support", "Code", "User", "mcp.json");
-  if (process.platform === "win32") return join4(process.env.APPDATA ?? join4(homeDir, "AppData", "Roaming"), "Code", "User", "mcp.json");
-  return join4(process.env.XDG_CONFIG_HOME ?? join4(homeDir, ".config"), "Code", "User", "mcp.json");
+  if (process.platform === "darwin") return join5(homeDir, "Library", "Application Support", "Code", "User", "mcp.json");
+  if (process.platform === "win32") return join5(process.env.APPDATA ?? join5(homeDir, "AppData", "Roaming"), "Code", "User", "mcp.json");
+  return join5(process.env.XDG_CONFIG_HOME ?? join5(homeDir, ".config"), "Code", "User", "mcp.json");
 }
-async function readAgentRegistrations(agent, homeDir = homedir2(), projectDir) {
+async function readAgentRegistrations(agent, homeDir = homedir3(), projectDir) {
   const registrations = [];
   for (const config of agentConfigPaths(agent, homeDir, projectDir)) {
-    if (!existsSync2(config.path)) continue;
+    if (!existsSync3(config.path)) continue;
     if (config.format === "json") {
       registrations.push(...await readJsonRegistrations(config.path, config.rootKey ?? "mcpServers", agent));
     } else if (config.format === "toml") {
@@ -5269,7 +5820,7 @@ async function readAgentRegistrations(agent, homeDir = homedir2(), projectDir) {
 async function readJsonRegistrations(path, rootKey, agent) {
   let parsed;
   try {
-    parsed = JSON.parse(await readFile3(path, "utf8"));
+    parsed = JSON.parse(await readFile4(path, "utf8"));
   } catch (error) {
     throw new Error("Cannot read malformed " + (agent === "claude" ? "Claude" : AGENT_LABELS[agent]) + " configuration at " + path + ": " + message(error));
   }
@@ -5281,7 +5832,7 @@ async function readTomlRegistrations(path, agent) {
   const registrations = /* @__PURE__ */ new Map();
   let section;
   let pending;
-  for (const rawLine of (await readFile3(path, "utf8")).split(/\r?\n/)) {
+  for (const rawLine of (await readFile4(path, "utf8")).split(/\r?\n/)) {
     const line = stripTomlComment(rawLine).trim();
     if (pending) {
       if (line.startsWith("[")) {
@@ -5320,9 +5871,9 @@ async function readTomlRegistrations(path, agent) {
   return [...registrations.values()].filter((registration) => registration.command);
 }
 async function readGooseRegistrations(path) {
-  const text = await readFile3(path, "utf8");
+  const text2 = await readFile4(path, "utf8");
   const registrations = [];
-  const lines = text.split(/\r?\n/);
+  const lines = text2.split(/\r?\n/);
   let inExtensions = false;
   let inTopolo = false;
   let current;
@@ -5516,9 +6067,9 @@ function message(error) {
 }
 
 // src/commands/agent-config.ts
-import { existsSync as existsSync3 } from "fs";
-import { mkdir as mkdir2, readFile as readFile4, rename, writeFile as writeFile2 } from "fs/promises";
-import { dirname as dirname3 } from "path";
+import { existsSync as existsSync4 } from "fs";
+import { mkdir as mkdir3, readFile as readFile5, rename as rename2, writeFile as writeFile3 } from "fs/promises";
+import { dirname as dirname4 } from "path";
 async function installAgentSkill(agent, source, homeDir, projectDir) {
   const path = agentSkillPath(agent, homeDir, projectDir);
   if (!path) return { installed: false };
@@ -5539,12 +6090,12 @@ async function registerAgentConfig(agent, mcp, homeDir, registration, projectDir
 }
 async function unregisterAgentConfig(agent, homeDir, name, projectDir) {
   for (const config of agentConfigPaths(agent, homeDir, projectDir)) {
-    if (!existsSync3(config.path)) continue;
+    if (!existsSync4(config.path)) continue;
     if (config.format === "json") {
       await unregisterJson(config, agent, name);
     } else if (config.format === "toml") {
-      const text = withoutMcpServerSections(await readFile4(config.path, "utf8"), name);
-      await atomicWrite(config.path, text ? text + "\n" : "");
+      const text2 = withoutMcpServerSections(await readFile5(config.path, "utf8"), name);
+      await atomicWrite(config.path, text2 ? text2 + "\n" : "");
     } else {
       await unregisterGoose(config.path, name);
     }
@@ -5553,14 +6104,15 @@ async function unregisterAgentConfig(agent, homeDir, name, projectDir) {
 function registrationEnvironment(agent, registration) {
   return {
     TOPOLO_AGENT_NAME: AGENT_NAME_FOR[agent],
+    ...registration.installationId ? { TOPOLO_AGENT_INSTALLATION_ID: registration.installationId } : {},
     ...registration.context ? { TOPOLO_CONTEXT: registration.context, TOPOLO_ENV: registration.environment } : {}
   };
 }
 async function registerJson(config, agent, mcp, registration) {
   let parsed = {};
-  if (existsSync3(config.path)) {
+  if (existsSync4(config.path)) {
     try {
-      parsed = JSON.parse(await readFile4(config.path, "utf8"));
+      parsed = JSON.parse(await readFile5(config.path, "utf8"));
     } catch (error) {
       throw new Error(
         "Cannot update malformed " + (agent === "claude" ? "Claude" : AGENT_LABELS[agent]) + " configuration at " + config.path + ": " + (error instanceof Error ? error.message : String(error))
@@ -5586,7 +6138,7 @@ async function registerJson(config, agent, mcp, registration) {
 async function unregisterJson(config, agent, name) {
   let parsed;
   try {
-    parsed = JSON.parse(await readFile4(config.path, "utf8"));
+    parsed = JSON.parse(await readFile5(config.path, "utf8"));
   } catch (error) {
     throw new Error(
       "Cannot update malformed " + AGENT_LABELS[agent] + " configuration at " + config.path + ": " + (error instanceof Error ? error.message : String(error))
@@ -5603,16 +6155,16 @@ async function unregisterJson(config, agent, name) {
   await atomicWrite(config.path, JSON.stringify(parsed, null, 2) + "\n");
 }
 async function registerToml(path, agent, mcp, registration) {
-  const existing = existsSync3(path) ? await readFile4(path, "utf8") : "";
-  const text = withoutMcpServerSections(existing, registration.name);
+  const existing = existsSync4(path) ? await readFile5(path, "utf8") : "";
+  const text2 = withoutMcpServerSections(existing, registration.name);
   const args = mcp.args.length ? "\nargs = [" + mcp.args.map((item) => JSON.stringify(item)).join(", ") + "]" : "";
   const environment = registrationEnvironment(agent, registration);
   const environmentText = Object.entries(environment).map(([key, value]) => JSON.stringify(key) + " = " + JSON.stringify(value)).join(", ");
   const block = agent === "grok" ? "\n\n[mcp_servers." + registration.name + "]\ncommand = " + JSON.stringify(mcp.command) + args + "\nenv = { " + environmentText + " }\n" : "\n\n[mcp_servers." + registration.name + "]\ncommand = " + JSON.stringify(mcp.command) + args + "\n\n[mcp_servers." + registration.name + ".env]\n" + Object.entries(environment).map(([key, value]) => key + " = " + JSON.stringify(value)).join("\n") + "\n";
-  await atomicWrite(path, text + block);
+  await atomicWrite(path, text2 + block);
 }
 async function registerGoose(path, mcp, registration) {
-  const existing = existsSync3(path) ? await readFile4(path, "utf8") : "";
+  const existing = existsSync4(path) ? await readFile5(path, "utf8") : "";
   const withoutTopolo = removeGooseExtension(existing, registration.name);
   const environment = registrationEnvironment("goose", registration);
   const block = [
@@ -5629,11 +6181,11 @@ async function registerGoose(path, mcp, registration) {
   await atomicWrite(path, insertGooseExtension(withoutTopolo, block));
 }
 async function unregisterGoose(path, name) {
-  const existing = await readFile4(path, "utf8");
+  const existing = await readFile5(path, "utf8");
   await atomicWrite(path, removeGooseExtension(existing, name));
 }
-function removeGooseExtension(text, name) {
-  const lines = text.split(/\r?\n/);
+function removeGooseExtension(text2, name) {
+  const lines = text2.split(/\r?\n/);
   const kept = [];
   let inExtensions = false;
   let skipping = false;
@@ -5653,11 +6205,11 @@ function removeGooseExtension(text, name) {
   }
   return kept.join("\n").replace(/\n{3,}/g, "\n\n").trimEnd();
 }
-function insertGooseExtension(text, block) {
-  if (!text.trim()) return "extensions:\n" + block + "\n";
-  const lines = text.split(/\r?\n/);
+function insertGooseExtension(text2, block) {
+  if (!text2.trim()) return "extensions:\n" + block + "\n";
+  const lines = text2.split(/\r?\n/);
   const extensionIndex = lines.findIndex((line) => /^extensions:\s*$/.test(line));
-  if (extensionIndex < 0) return text.trimEnd() + "\n\nextensions:\n" + block + "\n";
+  if (extensionIndex < 0) return text2.trimEnd() + "\n\nextensions:\n" + block + "\n";
   let end = lines.length;
   for (let index = extensionIndex + 1; index < lines.length; index += 1) {
     if (/^\S/.test(lines[index]) && lines[index].trim()) {
@@ -5680,16 +6232,16 @@ function formatSkillForAgent(agent, source) {
   return "---\ntrigger: model_decision\ndescription: Use Topolo MCP for Topolo platform operations.\n---\n\n" + body;
 }
 async function atomicWrite(path, contents) {
-  await mkdir2(dirname3(path), { recursive: true });
+  await mkdir3(dirname4(path), { recursive: true });
   const temporaryPath = path + ".topolo-" + process.pid + ".tmp";
-  await writeFile2(temporaryPath, contents, { encoding: "utf8", mode: 384 });
-  await rename(temporaryPath, path);
+  await writeFile3(temporaryPath, contents, { encoding: "utf8", mode: 384 });
+  await rename2(temporaryPath, path);
 }
-function withoutMcpServerSections(text, name) {
+function withoutMcpServerSections(text2, name) {
   const section = "[mcp_servers." + name + "]";
   const environmentSection = "[mcp_servers." + name + ".env]";
   let skipping = false;
-  return text.split(/\r?\n/).filter((line) => {
+  return text2.split(/\r?\n/).filter((line) => {
     const trimmed = line.trim();
     if (trimmed === section || trimmed === environmentSection) {
       skipping = true;
@@ -5703,11 +6255,11 @@ function withoutMcpServerSections(text, name) {
 // src/commands/skills.ts
 var AGENT_LABELS2 = AGENT_LABELS;
 function skillsSourceDir() {
-  const here = dirname4(fileURLToPath2(import.meta.url));
+  const here = dirname5(fileURLToPath2(import.meta.url));
   const distCandidate = resolve(here, "../skills");
   const srcCandidate = resolve(here, "../../skills");
   for (const candidate of [distCandidate, srcCandidate]) {
-    if (existsSync4(join5(candidate, "topolo", "SKILL.md"))) return candidate;
+    if (existsSync5(join6(candidate, "topolo", "SKILL.md"))) return candidate;
   }
   return distCandidate;
 }
@@ -5717,7 +6269,7 @@ function resolveMcpCommand() {
 }
 function agentBinaryExists(agent) {
   return agentCliNames(agent).some((bin) => {
-    const probe = spawnSync2(process.platform === "win32" ? "where" : "which", [bin], {
+    const probe = spawnSync3(process.platform === "win32" ? "where" : "which", [bin], {
       stdio: "ignore"
     });
     return probe.status === 0;
@@ -5743,10 +6295,14 @@ function resolveMcpRegistration(options) {
   if (!["production", "staging", "development", "local"].includes(environment)) {
     throw new Error("Environment must be production, staging, development, or local.");
   }
-  return { name, ...context ? { context } : {}, environment };
+  const installationId = options.installationId?.trim();
+  if (installationId && /[\r\n]/.test(installationId)) {
+    throw new Error("Installation id must be a single-line identifier.");
+  }
+  return { name, ...context ? { context } : {}, environment, ...installationId ? { installationId } : {} };
 }
 async function installForAgent(agent, sourceDir, mcp, opts) {
-  const source = await readFile5(join5(sourceDir, "topolo", "SKILL.md"), "utf8");
+  const source = await readFile6(join6(sourceDir, "topolo", "SKILL.md"), "utf8");
   const skill = await installAgentSkill(agent, source, opts.homeDir, opts.projectDir);
   if (!opts.withMcp) {
     return { agent, skillPath: skill.path, skillInstalled: skill.installed, mcp: "skipped" };
@@ -5785,22 +6341,26 @@ function resolveTargets(opts) {
     }))];
   }
   if (opts.all) return [...SUPPORTED_AGENT_IDS];
-  const homeDir = opts.homeDir ?? homedir3();
-  const detectBinaries = homeDir === homedir3();
+  const homeDir = opts.homeDir ?? homedir4();
+  const detectBinaries = homeDir === homedir4();
   const detected = SUPPORTED_AGENT_IDS.filter((agent) => agentConfigExists(agent, homeDir, opts.project) || detectBinaries && agentBinaryExists(agent));
   return [.../* @__PURE__ */ new Set(["claude", "codex", ...detected])];
 }
 function registerSkillsCommand(program2) {
   const skills = program2.command("skills").description("Install the Topolo agent skill + MCP server into supported agent hosts");
-  skills.command("install").description("Copy the skill file and register the topolo MCP server (credential-free)").option("--claude", "Target Claude Code only").option("--codex", "Target Codex only").option("--agent <host...>", "Target one or more hosts by id (for example cursor gemini)").option("--all", "Configure every supported local host").option("--project <dir>", "Write project-scoped host files under <dir> where supported").option("--agent-home <dir>", "Target an alternate agent home (managed installs and clean-room verification)").option("--name <name>", "Register a named pinned MCP, such as topolo-acme").option("--context <context>", "Pin the named MCP to an exact context returned by topolo context ls").option("--no-mcp", "Copy the skill file but do not register the MCP server").option("--json", "Output JSON", true).option("--no-json", "Output human-readable text").action(
+  skills.command("install").description("Copy the skill file and register the topolo MCP server (credential-free)").option("--claude", "Target Claude Code only").option("--codex", "Target Codex only").option("--agent <host...>", "Target one or more hosts by id (for example cursor gemini)").option("--all", "Configure every supported local host").option("--project <dir>", "Write project-scoped host files under <dir> where supported").option("--agent-home <dir>", "Target an alternate agent home (managed installs and clean-room verification)").option("--name <name>", "Register a named pinned MCP, such as topolo-acme").option("--context <context>", "Pin the named MCP to an exact context returned by topolo context ls").option("--installation <id>", "Bind the MCP runtime to a registered external-agent installation").option("--no-mcp", "Copy the skill file but do not register the MCP server").option("--json", "Output JSON", true).option("--no-json", "Output human-readable text").action(
     async (opts) => {
       const mode = resolveOutputMode(opts.json);
       try {
-        const { results, mcp } = await installAgentSurfaces({ ...opts, homeDir: opts.agentHome });
+        const { results, mcp } = await installAgentSurfaces({
+          ...opts,
+          installationId: opts.installation,
+          homeDir: opts.agentHome
+        });
         assertAgentSetupSucceeded(results);
         emit({ installed: results, mcpCommand: mcp }, mode, () => formatInstall(results, mcp));
       } catch (err) {
-        fail(err, mode);
+        fail2(err, mode);
       }
     }
   );
@@ -5816,7 +6376,7 @@ function registerSkillsCommand(program2) {
       });
       emit({ agents: rows }, mode, () => formatStatus(rows));
     } catch (err) {
-      fail(err, mode);
+      fail2(err, mode);
     }
   });
   skills.command("uninstall").description("Remove the skill file and MCP registration for each agent").option("--claude", "Target Claude Code only").option("--codex", "Target Codex only").option("--agent <host...>", "Target one or more hosts by id").option("--all", "Remove from every supported host").option("--project <dir>", "Remove project-scoped host files under <dir>").option("--agent-home <dir>", "Target an alternate agent home (managed installs and clean-room verification)").option("--name <name>", "Remove one registration (defaults to topolo)").option("--json", "Output JSON", true).option("--no-json", "Output human-readable text").action(async (opts) => {
@@ -5832,18 +6392,18 @@ function registerSkillsCommand(program2) {
         () => removed.map((r) => `${AGENT_LABELS2[r.agent]}: ${r.name} removed=${r.registrationRemoved}, skill removed=${r.skillRemoved}`).join("\n")
       );
     } catch (err) {
-      fail(err, mode);
+      fail2(err, mode);
     }
   });
 }
 async function installAgentSurfaces(opts) {
   const sourceDir = skillsSourceDir();
-  if (!existsSync4(join5(sourceDir, "topolo", "SKILL.md"))) {
+  if (!existsSync5(join6(sourceDir, "topolo", "SKILL.md"))) {
     throw new Error("Bundled skill file not found. Reinstall the CLI: npm install -g @topolo/cli");
   }
   const mcp = resolveMcpCommand();
   const registration = resolveMcpRegistration(opts);
-  const homeDir = opts.homeDir ?? homedir3();
+  const homeDir = opts.homeDir ?? homedir4();
   const results = [];
   for (const agent of resolveTargets({ ...opts, homeDir, project: opts.project })) {
     results.push(await installForAgent(agent, sourceDir, mcp, {
@@ -5856,14 +6416,18 @@ async function installAgentSurfaces(opts) {
   return { results, mcp };
 }
 function registerSetupCommand(program2) {
-  program2.command("setup").description("Install the Topolo skill and deterministic local MCP server for supported agent hosts").option("--claude", "Target Claude Code only").option("--codex", "Target Codex only").option("--agent <host...>", "Target one or more hosts by id").option("--all", "Configure every supported local host").option("--project <dir>", "Write project-scoped host files under <dir> where supported").option("--agent-home <dir>", "Target an alternate agent home (managed installs and clean-room verification)").option("--name <name>", "Register a named pinned MCP, such as topolo-acme").option("--context <context>", "Pin the named MCP to an exact context returned by topolo context ls").option("--json", "Output JSON", true).option("--no-json", "Output human-readable text").action(async (opts) => {
+  program2.command("setup").description("Install the Topolo skill and deterministic local MCP server for supported agent hosts").option("--claude", "Target Claude Code only").option("--codex", "Target Codex only").option("--agent <host...>", "Target one or more hosts by id").option("--all", "Configure every supported local host").option("--project <dir>", "Write project-scoped host files under <dir> where supported").option("--agent-home <dir>", "Target an alternate agent home (managed installs and clean-room verification)").option("--name <name>", "Register a named pinned MCP, such as topolo-acme").option("--context <context>", "Pin the named MCP to an exact context returned by topolo context ls").option("--installation <id>", "Bind the MCP runtime to a registered external-agent installation").option("--json", "Output JSON", true).option("--no-json", "Output human-readable text").action(async (opts) => {
     const mode = resolveOutputMode(opts.json);
     try {
-      const { results, mcp } = await installAgentSurfaces({ ...opts, homeDir: opts.agentHome });
+      const { results, mcp } = await installAgentSurfaces({
+        ...opts,
+        installationId: opts.installation,
+        homeDir: opts.agentHome
+      });
       assertAgentSetupSucceeded(results);
       emit({ installed: results, mcpCommand: mcp }, mode, () => formatInstall(results, mcp));
     } catch (error) {
-      fail(error, mode);
+      fail2(error, mode);
     }
   });
 }
@@ -5874,8 +6438,8 @@ function assertAgentSetupSucceeded(results) {
   }
 }
 async function agentSurfaceStatus(options = {}) {
-  const homeDir = options.homeDir ?? homedir3();
-  const sourceSkill = await readFile5(join5(skillsSourceDir(), "topolo", "SKILL.md"), "utf8");
+  const homeDir = options.homeDir ?? homedir4();
+  const sourceSkill = await readFile6(join6(skillsSourceDir(), "topolo", "SKILL.md"), "utf8");
   const agents = resolveTargets({
     agent: options.agent,
     all: options.all,
@@ -5884,7 +6448,7 @@ async function agentSurfaceStatus(options = {}) {
   });
   return Promise.all(agents.map(async (agent) => {
     const skillPath = agentSkillPath(agent, homeDir, options.project);
-    const installedSkill = skillPath && existsSync4(skillPath) ? await readFile5(skillPath, "utf8") : void 0;
+    const installedSkill = skillPath && existsSync5(skillPath) ? await readFile6(skillPath, "utf8") : void 0;
     const registrations = (await readAgentRegistrations(agent, homeDir, options.project)).filter((registration) => !options.name || registration.name === options.name);
     return {
       agent,
@@ -5898,7 +6462,7 @@ async function agentSurfaceStatus(options = {}) {
   }));
 }
 async function uninstallAgentSurfaces(options) {
-  const homeDir = options.homeDir ?? homedir3();
+  const homeDir = options.homeDir ?? homedir4();
   const name = options.name?.trim() || "topolo";
   resolveMcpRegistration({ name, ...name === "topolo" ? {} : { context: "uninstall-validation" } });
   const removed = [];
@@ -5908,8 +6472,8 @@ async function uninstallAgentSurfaces(options) {
     await unregisterAgentConfig(agent, homeDir, name, options.project);
     const remaining = await readAgentRegistrations(agent, homeDir, options.project);
     const skillPath = agentSkillPath(agent, homeDir, options.project);
-    const skillRemoved = remaining.length === 0 && Boolean(skillPath && existsSync4(skillPath));
-    if (skillRemoved && skillPath) await rm2(dirname4(skillPath), { recursive: true, force: true });
+    const skillRemoved = remaining.length === 0 && Boolean(skillPath && existsSync5(skillPath));
+    if (skillRemoved && skillPath) await rm3(dirname5(skillPath), { recursive: true, force: true });
     removed.push({ agent, name, registrationRemoved, skillRemoved });
   }
   return removed;
@@ -5939,7 +6503,7 @@ function formatStatus(rows) {
 
 // src/commands/doctor.ts
 import { access } from "fs/promises";
-import { homedir as homedir4 } from "os";
+import { homedir as homedir5 } from "os";
 import { resolve as resolve2 } from "path";
 import { Client } from "@modelcontextprotocol/sdk/client/index.js";
 import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
@@ -6002,7 +6566,7 @@ async function verifyMcpProtocol(command, args, env = definedEnvironment(process
 }
 async function resolveInstalledDoctorTarget(options) {
   const name = options.name?.trim() || "topolo";
-  const homeDir = options.agentHome ? resolve2(options.agentHome) : homedir4();
+  const homeDir = options.agentHome ? resolve2(options.agentHome) : homedir5();
   const expected = resolveMcpCommand();
   const requestedAgents = resolveTargets({
     ...options,
@@ -6051,7 +6615,7 @@ function registerDoctorCommand(program2) {
       if (!result.ok) throw new Error(formatDoctor(result));
       emit(result, mode, () => formatDoctor(result));
     } catch (error) {
-      fail(error, mode);
+      fail2(error, mode);
     }
   });
 }
@@ -6242,7 +6806,7 @@ function registerContextCommand(program2) {
         return lines.join("\n");
       });
     } catch (err) {
-      fail(err, mode);
+      fail2(err, mode);
     }
   });
   context.command("use <target>").description('Switch the active context (an organization name/slug, or "personal")').option("--json", "Output JSON", true).option("--no-json", "Output human-readable text").action(async (target, opts) => {
@@ -6345,7 +6909,7 @@ function registerContextCommand(program2) {
   \u2713 Now acting as ${labelFor(resolved)} (${resolved.contextType}).`
       );
     } catch (err) {
-      fail(err, mode);
+      fail2(err, mode);
     }
   });
 }
@@ -6362,7 +6926,7 @@ function registerResourcesCommand(program2) {
       const result = await topolo.client.listBindableResources(selector);
       emit(result, mode, () => formatResources(result));
     } catch (err) {
-      fail(err, mode);
+      fail2(err, mode);
     }
   });
 }
@@ -6390,7 +6954,7 @@ function registerWorkspacesCommand(program2) {
       const result = await topolo.workspaces.list(application);
       emit(result, mode, () => formatWorkspaceList(result));
     } catch (error) {
-      fail(error, mode);
+      fail2(error, mode);
     }
   });
   workspaces.command("create <application>").description("Create a workspace when the target application policy permits it").requiredOption("--name <name>", "Workspace display name").option("--default", "Make the new workspace the application default").option("--confirm", "Acknowledge workspace creation").option("--json", "Output JSON").option("--no-json", "Output human-readable text").action(async (application, opts) => {
@@ -6404,7 +6968,7 @@ function registerWorkspacesCommand(program2) {
       });
       emit(result, mode, () => formatWorkspaceMutation(result));
     } catch (error) {
-      fail(error, mode);
+      fail2(error, mode);
     }
   });
   workspaces.command("rename <application> <workspace-id>").description("Rename a caller-authorized workspace without changing its stable id").requiredOption("--name <name>", "New workspace display name").option("--confirm", "Acknowledge workspace rename").option("--json", "Output JSON").option("--no-json", "Output human-readable text").action(async (application, workspaceId, opts) => {
@@ -6414,7 +6978,7 @@ function registerWorkspacesCommand(program2) {
       const result = await topolo.workspaces.rename(application, workspaceId, opts.name.trim(), opts.confirm === true);
       emit(result, mode, () => formatWorkspaceMutation(result));
     } catch (error) {
-      fail(error, mode);
+      fail2(error, mode);
     }
   });
   workspaces.command("default <application> <workspace-id>").description("Set the default workspace for one application").option("--confirm", "Acknowledge the default-workspace change").option("--json", "Output JSON").option("--no-json", "Output human-readable text").action(async (application, workspaceId, opts) => {
@@ -6424,7 +6988,7 @@ function registerWorkspacesCommand(program2) {
       const result = await topolo.workspaces.setDefault(application, workspaceId, opts.confirm === true);
       emit(result, mode, () => formatWorkspaceMutation(result));
     } catch (error) {
-      fail(error, mode);
+      fail2(error, mode);
     }
   });
 }
@@ -6453,6 +7017,195 @@ function formatWorkspaceMutation(result) {
 Workspace: ${workspace.name} (${workspace.id})${workspace.isDefault ? "\nDefault: yes" : ""}`;
 }
 
+// src/commands/installations.ts
+var CREATE_PRINCIPAL = "app_topolo_auth.organization_principals.create";
+var UPDATE_PRINCIPAL = "app_topolo_auth.organization_principals.update";
+var REVOKE_CREDENTIAL = "app_topolo_auth.principal_credentials.revoke";
+var INSTALLATION_BOOTSTRAP_GRANT = "app_topolo_auth:identity";
+function actionData(value) {
+  if (!value || typeof value !== "object") throw new Error("Topolo returned an invalid action response.");
+  const record2 = value;
+  const data = record2.data;
+  return data && typeof data === "object" ? data : record2;
+}
+function requiredRecord(value, name) {
+  if (!value || typeof value !== "object") throw new Error(`Topolo did not return ${name}.`);
+  return value;
+}
+function requiredString(record2, key) {
+  const value = record2[key];
+  if (typeof value !== "string" || !value.trim()) throw new Error(`Topolo did not return ${key}.`);
+  return value;
+}
+async function createInstallationKey() {
+  const keyPair = await crypto.subtle.generateKey(
+    { name: "ECDSA", namedCurve: "P-256" },
+    true,
+    ["sign", "verify"]
+  );
+  const privateJwk = await crypto.subtle.exportKey("jwk", keyPair.privateKey);
+  return { privateJwk, dpopJkt: await calculateDpopJkt(privateJwk) };
+}
+async function registerExternalAgentInstallation(input2, dependencies) {
+  const organizationId = dependencies.identity.organization?.id;
+  if (!organizationId) throw new Error("Select an organization context before registering an installation.");
+  const serviceGrants = Array.from(/* @__PURE__ */ new Set([
+    INSTALLATION_BOOTSTRAP_GRANT,
+    ...input2.serviceGrants.map((grant) => grant.trim()).filter(Boolean)
+  ]));
+  const { privateJwk, dpopJkt } = await createInstallationKey();
+  const principalResult = actionData(await dependencies.client.callAction(CREATE_PRINCIPAL, {
+    orgId: organizationId,
+    principalType: "external_agent",
+    displayName: input2.displayName,
+    accountableUserId: dependencies.identity.user.id,
+    provider: input2.provider,
+    ...input2.model ? { model: input2.model } : {},
+    serviceGrants
+  }, { confirm: true }));
+  const principal = requiredRecord(principalResult.principal, "principal");
+  const principalId = requiredString(principal, "id");
+  const installationId = typeof principal.installationId === "string" ? principal.installationId : principalId;
+  let credentialId = null;
+  try {
+    const credentialResult = actionData(await dependencies.client.issueExternalAgentCredential({
+      orgId: organizationId,
+      principalId,
+      displayName: `${input2.displayName} installation credential`,
+      expiresAt: input2.expiresAt ?? null,
+      dpopJkt
+    }));
+    const credential = requiredRecord(credentialResult.credential, "credential");
+    credentialId = requiredString(credential, "id");
+    const installation = {
+      id: installationId,
+      environment: dependencies.environment,
+      organizationId,
+      principalId,
+      credentialId,
+      clientId: requiredString(credential, "clientId"),
+      displayName: input2.displayName,
+      provider: input2.provider,
+      host: input2.host,
+      ...input2.model ? { model: input2.model } : {},
+      dpopJkt,
+      createdAt: (/* @__PURE__ */ new Date()).toISOString()
+    };
+    await (dependencies.write ?? writeExternalAgentInstallation)(installation, {
+      clientSecret: requiredString(credential, "clientSecret"),
+      privateJwk
+    });
+    return installation;
+  } catch (error) {
+    if (credentialId) {
+      await dependencies.client.callAction(REVOKE_CREDENTIAL, {
+        orgId: organizationId,
+        principalId,
+        credentialId
+      }, { confirm: true }).catch(() => void 0);
+    }
+    await dependencies.client.callAction(UPDATE_PRINCIPAL, {
+      orgId: organizationId,
+      principalId,
+      status: "suspended"
+    }, { confirm: true }).catch(() => void 0);
+    throw error;
+  }
+}
+async function revokeInstallation(client, installation) {
+  await client.callAction(REVOKE_CREDENTIAL, {
+    orgId: installation.organizationId,
+    principalId: installation.principalId,
+    credentialId: installation.credentialId
+  }, { confirm: true });
+  await client.callAction(UPDATE_PRINCIPAL, {
+    orgId: installation.organizationId,
+    principalId: installation.principalId,
+    status: "suspended"
+  }, { confirm: true });
+  await deleteExternalAgentInstallation(installation.environment, installation.id);
+}
+function parseExpiry(value) {
+  if (value === void 0) return void 0;
+  if (value === "never") return null;
+  const timestamp2 = Math.floor(new Date(value).getTime() / 1e3);
+  if (!Number.isSafeInteger(timestamp2) || timestamp2 <= Math.floor(Date.now() / 1e3)) {
+    throw new Error('--expires-at must be a future ISO-8601 timestamp or "never".');
+  }
+  return timestamp2;
+}
+async function requiredClient3() {
+  const client = await buildClient({ requireConfirmForWrites: true });
+  if (!client) throw new Error("No credential configured. Run `topolo auth login`.");
+  return client;
+}
+function registerInstallationsCommand(program2) {
+  const installations = program2.command("installations").description("Register and manage accountable external agent installations");
+  installations.command("register").requiredOption("--name <name>", "Human-readable installation name").requiredOption("--provider <provider>", "Agent provider, such as openai or anthropic").requiredOption("--host <host>", "Agent host, such as codex or claude").option("--model <model>", "Model identifier recorded for audit attribution").option("--grant <app:scope...>", "One or more explicit application grants", []).option("--expires-at <timestamp>", "Credential expiry in ISO-8601 form, or never", "never").option("--project <dir>", "Write project-scoped host files under <dir> where supported").option("--agent-home <dir>", "Target an alternate agent home").option("--json", "Output JSON").option("--no-json", "Output human-readable text").action(async (opts) => {
+    const mode = resolveOutputMode(opts.json);
+    try {
+      const host = opts.host.trim();
+      if (!SUPPORTED_AGENT_IDS.includes(host)) {
+        throw new Error(`Unsupported agent host "${opts.host}". Supported hosts: ${SUPPORTED_AGENT_IDS.join(", ")}.`);
+      }
+      const topolo = await requiredClient3();
+      const installation = await registerExternalAgentInstallation({
+        displayName: opts.name.trim(),
+        provider: opts.provider.trim(),
+        host,
+        model: opts.model?.trim(),
+        serviceGrants: opts.grant,
+        expiresAt: parseExpiry(opts.expiresAt)
+      }, {
+        client: topolo.client,
+        identity: await topolo.identity.whoami(),
+        environment: selectedEnvironment()
+      });
+      try {
+        const configured = await installAgentSurfaces({
+          agent: [host],
+          project: opts.project,
+          homeDir: opts.agentHome,
+          installationId: installation.id
+        });
+        assertAgentSetupSucceeded(configured.results);
+      } catch (error) {
+        await revokeInstallation(topolo.client, installation).catch(() => void 0);
+        throw error;
+      }
+      emit(
+        { installation },
+        mode,
+        () => `Registered ${installation.displayName} (${installation.id}) for ${installation.host}.`
+      );
+    } catch (error) {
+      fail2(error, mode);
+    }
+  });
+  installations.command("list").option("--json", "Output JSON").option("--no-json", "Output human-readable text").action(async (opts) => {
+    const mode = resolveOutputMode(opts.json);
+    try {
+      const rows = await listExternalAgentInstallations(selectedEnvironment());
+      emit({ installations: rows }, mode, () => rows.length ? rows.map((row) => `${row.id}	${row.displayName}	${row.host}	${row.provider}`).join("\n") : "No external agent installations are registered on this device.");
+    } catch (error) {
+      fail2(error, mode);
+    }
+  });
+  installations.command("revoke <installation-id>").description("Revoke the remote credential and remove its protected local installation").option("--json", "Output JSON").option("--no-json", "Output human-readable text").action(async (installationId, opts) => {
+    const mode = resolveOutputMode(opts.json);
+    try {
+      const environment = selectedEnvironment();
+      const row = (await listExternalAgentInstallations(environment)).find((installation) => installation.id === installationId);
+      if (!row) throw new Error(`Installation ${installationId} was not found on this device.`);
+      const topolo = await requiredClient3();
+      await revokeInstallation(topolo.client, row);
+      emit({ revoked: true, installationId }, mode, () => `Revoked ${installationId}.`);
+    } catch (error) {
+      fail2(error, mode);
+    }
+  });
+}
+
 // src/index.ts
 installOutputErrorHandlers();
 var program = new Command();
@@ -6506,6 +7259,7 @@ registerDoctorCommand(program);
 registerContextCommand(program);
 registerResourcesCommand(program);
 registerWorkspacesCommand(program);
+registerInstallationsCommand(program);
 program.parseAsync(argv).catch((err) => {
   process.stderr.write(`Unexpected error: ${err instanceof Error ? err.message : String(err)}
 `);