@topolo/sdk 0.15.0 → 0.17.1

package/dist/index.js

@@ -843,6 +843,242 @@ function isMultipleOf(value, divisor) {
   return Math.abs(quotient - Math.round(quotient)) < Number.EPSILON * Math.max(1, Math.abs(quotient)) * 4;
 }
 
+// src/actor-envelope.ts
+var ACTOR_ENVELOPE_VERSION = 1;
+var TOPOLO_ACTOR_ENVELOPE_HEADER = "X-Topolo-Actor-Envelope";
+var PRINCIPAL_TYPES = /* @__PURE__ */ new Set([
+  "human",
+  "managed_agent",
+  "external_agent",
+  "service",
+  "browser_automation"
+]);
+var ACCOUNTABLE_SUBJECT_TYPES = /* @__PURE__ */ new Set(["human", "organization"]);
+var CHANNELS = /* @__PURE__ */ new Set(["web", "mobile", "cli", "mcp", "api", "workflow", "browser_automation"]);
+var ASSURANCE_LEVELS = /* @__PURE__ */ new Set(["authenticated", "workload_identity", "user_verified"]);
+var HASH_PATTERN = /^sha256:[a-f0-9]{64}$/;
+var ActorEnvelopeValidationError = class extends Error {
+  path;
+  constructor(path, message) {
+    super(`${path}: ${message}`);
+    this.name = "ActorEnvelopeValidationError";
+    this.path = path;
+  }
+};
+function parseActorEnvelope(value) {
+  const envelope = record(value, "actorEnvelope");
+  exactKeys(envelope, [
+    "schemaVersion",
+    "organizationId",
+    "accountableSubject",
+    "performer",
+    "delegation",
+    "channel",
+    "assurance",
+    "action",
+    "issuedAt",
+    "expiresAt"
+  ], "actorEnvelope");
+  if (envelope.schemaVersion !== ACTOR_ENVELOPE_VERSION) {
+    fail("actorEnvelope.schemaVersion", `must equal ${ACTOR_ENVELOPE_VERSION}`);
+  }
+  const accountableSubject = parseAccountableSubject(envelope.accountableSubject);
+  const performer = parseIdentity(envelope.performer, "actorEnvelope.performer");
+  const organizationId = text(envelope.organizationId, "actorEnvelope.organizationId");
+  const channel = member(envelope.channel, CHANNELS, "actorEnvelope.channel");
+  const issuedAt = timestamp(envelope.issuedAt, "actorEnvelope.issuedAt");
+  const expiresAt = envelope.expiresAt === void 0 ? void 0 : timestamp(envelope.expiresAt, "actorEnvelope.expiresAt");
+  if (expiresAt && Date.parse(expiresAt) <= Date.parse(issuedAt)) {
+    fail("actorEnvelope.expiresAt", "must be later than issuedAt");
+  }
+  const assuranceValue = record(envelope.assurance, "actorEnvelope.assurance");
+  exactKeys(assuranceValue, ["level", "methods"], "actorEnvelope.assurance");
+  const assurance = {
+    level: member(assuranceValue.level, ASSURANCE_LEVELS, "actorEnvelope.assurance.level"),
+    methods: textArray(assuranceValue.methods, "actorEnvelope.assurance.methods")
+  };
+  const actionValue = record(envelope.action, "actorEnvelope.action");
+  exactKeys(actionValue, ["requestId", "actionId", "resourceType", "resourceId", "inputHash"], "actorEnvelope.action");
+  const inputHash = text(actionValue.inputHash, "actorEnvelope.action.inputHash");
+  if (!HASH_PATTERN.test(inputHash)) fail("actorEnvelope.action.inputHash", "must be a lowercase sha256 digest");
+  const action = {
+    requestId: text(actionValue.requestId, "actorEnvelope.action.requestId"),
+    actionId: text(actionValue.actionId, "actorEnvelope.action.actionId"),
+    ...actionValue.resourceType === void 0 ? {} : { resourceType: text(actionValue.resourceType, "actorEnvelope.action.resourceType") },
+    ...actionValue.resourceId === void 0 ? {} : { resourceId: text(actionValue.resourceId, "actorEnvelope.action.resourceId") },
+    inputHash
+  };
+  if (action.resourceType === void 0 !== (action.resourceId === void 0)) {
+    fail("actorEnvelope.action", "resourceType and resourceId must be provided together");
+  }
+  const delegation = parseDelegation(envelope.delegation);
+  const directHuman = performer.principalType === "human" && performer.principalId === accountableSubject.principalId;
+  if (directHuman && delegation !== null) fail("actorEnvelope.delegation", "must be null for direct human action");
+  if (!directHuman && delegation === null) fail("actorEnvelope.delegation", "is required when performer differs from accountable subject");
+  if (delegation) {
+    const finalHop = delegation.lineage.at(-1);
+    if (!finalHop || finalHop.principalId !== performer.principalId || finalHop.principalType !== performer.principalType) {
+      fail("actorEnvelope.delegation.lineage", "must end with the performer");
+    }
+  }
+  if (performer.principalType === "external_agent" && (!performer.installationId || !performer.provider)) {
+    fail("actorEnvelope.performer", "external_agent requires installationId and provider");
+  }
+  if (performer.principalType === "managed_agent" && !performer.agentInstanceId) {
+    fail("actorEnvelope.performer.agentInstanceId", "is required for managed_agent");
+  }
+  if (performer.principalType === "browser_automation" && (!performer.installationId || !performer.browserSessionId)) {
+    fail("actorEnvelope.performer", "browser_automation requires installationId and browserSessionId");
+  }
+  return {
+    schemaVersion: ACTOR_ENVELOPE_VERSION,
+    organizationId,
+    accountableSubject,
+    performer,
+    delegation,
+    channel,
+    assurance,
+    action,
+    issuedAt,
+    ...expiresAt ? { expiresAt } : {}
+  };
+}
+function canonicalizeActorEnvelope(value) {
+  return canonicalJson(parseActorEnvelope(value));
+}
+function encodeActorEnvelopeHeader(value) {
+  const bytes = new TextEncoder().encode(canonicalizeActorEnvelope(value));
+  const binary = Array.from(bytes, (byte) => String.fromCharCode(byte)).join("");
+  return btoa(binary).replaceAll("+", "-").replaceAll("/", "_").replace(/=+$/, "");
+}
+function decodeActorEnvelopeHeader(value) {
+  if (!/^[A-Za-z0-9_-]+$/.test(value)) {
+    fail("actorEnvelopeHeader", "must be unpadded base64url");
+  }
+  const padded = value.replaceAll("-", "+").replaceAll("_", "/") + "=".repeat((4 - value.length % 4) % 4);
+  let bytes;
+  try {
+    bytes = Uint8Array.from(atob(padded), (character) => character.charCodeAt(0));
+  } catch {
+    fail("actorEnvelopeHeader", "must be valid base64url");
+  }
+  try {
+    return parseActorEnvelope(JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(bytes)));
+  } catch (error) {
+    if (error instanceof ActorEnvelopeValidationError) throw error;
+    fail("actorEnvelopeHeader", "must contain a valid UTF-8 actor envelope");
+  }
+}
+function canonicalJson(value) {
+  if (value === null) return "null";
+  if (typeof value === "string" || typeof value === "boolean") return JSON.stringify(value);
+  if (typeof value === "number") {
+    if (!Number.isFinite(value)) throw new TypeError("Canonical JSON accepts finite numbers only.");
+    return JSON.stringify(value);
+  }
+  if (Array.isArray(value)) return `[${value.map(canonicalJson).join(",")}]`;
+  if (typeof value !== "object" || !value || ![Object.prototype, null].includes(Object.getPrototypeOf(value))) {
+    throw new TypeError("Canonical JSON accepts JSON objects, arrays, and primitives only.");
+  }
+  const entries = Object.entries(value).filter(([, item]) => item !== void 0).sort(([left], [right]) => left.localeCompare(right));
+  return `{${entries.map(([key, item]) => `${JSON.stringify(key)}:${canonicalJson(item)}`).join(",")}}`;
+}
+function parseAccountableSubject(value) {
+  const path = "actorEnvelope.accountableSubject";
+  const subject = record(value, path);
+  exactKeys(subject, ["principalType", "principalId", "displayName"], path);
+  return {
+    principalType: member(subject.principalType, ACCOUNTABLE_SUBJECT_TYPES, `${path}.principalType`),
+    principalId: text(subject.principalId, `${path}.principalId`),
+    ...subject.displayName === void 0 ? {} : { displayName: text(subject.displayName, `${path}.displayName`) }
+  };
+}
+async function sha256CanonicalValue(value) {
+  const bytes = new TextEncoder().encode(canonicalJson(value));
+  const digest = await crypto.subtle.digest("SHA-256", bytes);
+  return `sha256:${Array.from(new Uint8Array(digest), (byte) => byte.toString(16).padStart(2, "0")).join("")}`;
+}
+function parseIdentity(value, path) {
+  const identity = record(value, path);
+  exactKeys(identity, [
+    "principalType",
+    "principalId",
+    "displayName",
+    "installationId",
+    "agentInstanceId",
+    "browserSessionId",
+    "provider",
+    "model"
+  ], path);
+  return {
+    principalType: member(identity.principalType, PRINCIPAL_TYPES, `${path}.principalType`),
+    principalId: text(identity.principalId, `${path}.principalId`),
+    ...optionalTextFields(identity, path, [
+      "displayName",
+      "installationId",
+      "agentInstanceId",
+      "browserSessionId",
+      "provider",
+      "model"
+    ])
+  };
+}
+function parseDelegation(value) {
+  if (value === null) return null;
+  const delegation = record(value, "actorEnvelope.delegation");
+  exactKeys(delegation, ["taskId", "runId", "lineage"], "actorEnvelope.delegation");
+  if (!Array.isArray(delegation.lineage) || delegation.lineage.length === 0 || delegation.lineage.length > 16) {
+    fail("actorEnvelope.delegation.lineage", "must contain between 1 and 16 hops");
+  }
+  return {
+    taskId: text(delegation.taskId, "actorEnvelope.delegation.taskId"),
+    runId: text(delegation.runId, "actorEnvelope.delegation.runId"),
+    lineage: delegation.lineage.map((value2, index) => {
+      const hop = record(value2, `actorEnvelope.delegation.lineage[${index}]`);
+      exactKeys(hop, ["principalType", "principalId"], `actorEnvelope.delegation.lineage[${index}]`);
+      return {
+        principalType: member(hop.principalType, PRINCIPAL_TYPES, `actorEnvelope.delegation.lineage[${index}].principalType`),
+        principalId: text(hop.principalId, `actorEnvelope.delegation.lineage[${index}].principalId`)
+      };
+    })
+  };
+}
+function record(value, path) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) fail(path, "must be an object");
+  return value;
+}
+function exactKeys(value, allowed, path) {
+  const unknown = Object.keys(value).filter((key) => !allowed.includes(key));
+  if (unknown.length) fail(path, `contains unknown field ${unknown[0]}`);
+}
+function text(value, path) {
+  if (typeof value !== "string" || value.trim() !== value || value.length === 0 || value.length > 256) {
+    fail(path, "must be a non-empty trimmed string of at most 256 characters");
+  }
+  return value;
+}
+function timestamp(value, path) {
+  const result = text(value, path);
+  if (!/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{3})?Z$/.test(result) || Number.isNaN(Date.parse(result))) {
+    fail(path, "must be an RFC 3339 UTC timestamp");
+  }
+  return result;
+}
+function member(value, values, path) {
+  if (typeof value !== "string" || !values.has(value)) fail(path, "contains an unsupported value");
+  return value;
+}
+function textArray(value, path) {
+  if (!Array.isArray(value) || value.length === 0 || value.length > 16) fail(path, "must contain between 1 and 16 values");
+  return value.map((item, index) => text(item, `${path}[${index}]`));
+}
+function optionalTextFields(value, path, keys) {
+  return Object.fromEntries(keys.flatMap((key) => value[key] === void 0 ? [] : [[key, text(value[key], `${path}.${key}`)]]));
+}
+function fail(path, message) {
+  throw new ActorEnvelopeValidationError(path, message);
+}
+
 // src/action-upload.ts
 function parseTopoloActionUploadContract(value) {
   if (!isRecord2(value) || value.profile !== "inline-base64" && value.profile !== "url-session") {
@@ -1050,6 +1286,7 @@ var NEGATIVE_CACHE_TTL_MS = 60 * 1e3;
 var TopoloClient = class _TopoloClient {
   credential;
   agent;
+  actorContext;
   serviceUrls;
   environment;
   appIds;
@@ -1080,6 +1317,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;
@@ -1133,11 +1375,15 @@ var TopoloClient = class _TopoloClient {
     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();
@@ -1791,6 +2037,20 @@ var TopoloClient = class _TopoloClient {
       );
     }
     const mapped = mapActionInput(entry, input);
+    const resolvedActorEnvelope = options.actorEnvelope ?? await this.buildVerifiedAgentActorEnvelope(entry.actionId, input, options.resource);
+    if (resolvedActorEnvelope) {
+      const actorEnvelope = parseActorEnvelope(resolvedActorEnvelope);
+      if (actorEnvelope.action.actionId !== entry.actionId) {
+        throw new TopoloSdkError("actor_envelope_action_mismatch", "Actor envelope actionId does not match the executed action.");
+      }
+      if (actorEnvelope.action.inputHash !== await sha256CanonicalValue(input)) {
+        throw new TopoloSdkError("actor_envelope_input_mismatch", "Actor envelope inputHash does not match the executed action input.");
+      }
+      const envelopeResource = actorEnvelope.action.resourceType && actorEnvelope.action.resourceId ? { resourceType: actorEnvelope.action.resourceType, resourceId: actorEnvelope.action.resourceId } : void 0;
+      if (envelopeResource?.resourceType !== options.resource?.resourceType || envelopeResource?.resourceId !== options.resource?.resourceId) {
+        throw new TopoloSdkError("actor_envelope_resource_mismatch", "Actor envelope resource does not match the executed action resource.");
+      }
+    }
     const service = entry.appSlug || entry.appId;
     const result = await this.request({
       service,
@@ -1800,6 +2060,7 @@ 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
@@ -1808,6 +2069,56 @@ var TopoloClient = class _TopoloClient {
     });
     return redactActionResult(result);
   }
+  async buildVerifiedAgentActorEnvelope(actionId, input, resource) {
+    if (!this.actorContext) return void 0;
+    const identity = await this.introspect();
+    const principalType = identity.user.principalType;
+    if (principalType !== "agent_employee" && principalType !== "external_agent") return void 0;
+    if (!identity.organization || !identity.user.accountableUserId || !identity.user.principalId) {
+      throw new TopoloSdkError(
+        "incomplete_agent_identity",
+        "Verified agent credentials must resolve an organization, accountable user, and principal id."
+      );
+    }
+    const performer = principalType === "external_agent" ? {
+      principalType: "external_agent",
+      principalId: identity.user.principalId,
+      installationId: identity.user.installationId ?? void 0,
+      provider: identity.user.provider ?? void 0,
+      model: identity.user.model ?? void 0
+    } : {
+      principalType: "managed_agent",
+      principalId: identity.user.principalId,
+      agentInstanceId: identity.user.agentInstanceId ?? void 0,
+      model: identity.user.model ?? void 0
+    };
+    if (performer.principalType === "external_agent" && (!performer.installationId || !performer.provider) || performer.principalType === "managed_agent" && !performer.agentInstanceId) {
+      throw new TopoloSdkError(
+        "incomplete_agent_identity",
+        "Verified agent credentials are missing the performer identity required for provenance."
+      );
+    }
+    return parseActorEnvelope({
+      schemaVersion: 1,
+      organizationId: identity.organization.id,
+      accountableSubject: { principalType: "human", principalId: identity.user.accountableUserId },
+      performer,
+      delegation: {
+        taskId: this.actorContext.taskId,
+        runId: this.actorContext.runId,
+        lineage: [{ principalType: performer.principalType, principalId: performer.principalId }]
+      },
+      channel: this.actorContext.channel,
+      assurance: { level: "workload_identity", methods: ["client_credentials"] },
+      action: {
+        requestId: generateRequestId(),
+        actionId,
+        ...resource ? resource : {},
+        inputHash: await sha256CanonicalValue(input)
+      },
+      issuedAt: (/* @__PURE__ */ new Date()).toISOString()
+    });
+  }
   /**
    * Introspect the current credential. Returns the caller's resolved identity,
    * organization, and permission set. Used by CLI `whoami` and by MCP to gate
@@ -1835,7 +2146,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,
@@ -2200,6 +2522,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;
@@ -2924,218 +3249,6 @@ var IdentityModule = class {
   }
 };
 
-// src/actor-envelope.ts
-var ACTOR_ENVELOPE_VERSION = 1;
-var PRINCIPAL_TYPES = /* @__PURE__ */ new Set([
-  "human",
-  "managed_agent",
-  "external_agent",
-  "service",
-  "browser_automation"
-]);
-var ACCOUNTABLE_SUBJECT_TYPES = /* @__PURE__ */ new Set(["human", "organization"]);
-var CHANNELS = /* @__PURE__ */ new Set(["web", "mobile", "cli", "mcp", "api", "workflow", "browser_automation"]);
-var ASSURANCE_LEVELS = /* @__PURE__ */ new Set(["authenticated", "workload_identity", "user_verified"]);
-var HASH_PATTERN = /^sha256:[a-f0-9]{64}$/;
-var ActorEnvelopeValidationError = class extends Error {
-  path;
-  constructor(path, message) {
-    super(`${path}: ${message}`);
-    this.name = "ActorEnvelopeValidationError";
-    this.path = path;
-  }
-};
-function parseActorEnvelope(value) {
-  const envelope = record(value, "actorEnvelope");
-  exactKeys(envelope, [
-    "schemaVersion",
-    "organizationId",
-    "accountableSubject",
-    "performer",
-    "delegation",
-    "channel",
-    "assurance",
-    "action",
-    "issuedAt",
-    "expiresAt"
-  ], "actorEnvelope");
-  if (envelope.schemaVersion !== ACTOR_ENVELOPE_VERSION) {
-    fail("actorEnvelope.schemaVersion", `must equal ${ACTOR_ENVELOPE_VERSION}`);
-  }
-  const accountableSubject = parseAccountableSubject(envelope.accountableSubject);
-  const performer = parseIdentity(envelope.performer, "actorEnvelope.performer");
-  const organizationId = text(envelope.organizationId, "actorEnvelope.organizationId");
-  const channel = member(envelope.channel, CHANNELS, "actorEnvelope.channel");
-  const issuedAt = timestamp(envelope.issuedAt, "actorEnvelope.issuedAt");
-  const expiresAt = envelope.expiresAt === void 0 ? void 0 : timestamp(envelope.expiresAt, "actorEnvelope.expiresAt");
-  if (expiresAt && Date.parse(expiresAt) <= Date.parse(issuedAt)) {
-    fail("actorEnvelope.expiresAt", "must be later than issuedAt");
-  }
-  const assuranceValue = record(envelope.assurance, "actorEnvelope.assurance");
-  exactKeys(assuranceValue, ["level", "methods"], "actorEnvelope.assurance");
-  const assurance = {
-    level: member(assuranceValue.level, ASSURANCE_LEVELS, "actorEnvelope.assurance.level"),
-    methods: textArray(assuranceValue.methods, "actorEnvelope.assurance.methods")
-  };
-  const actionValue = record(envelope.action, "actorEnvelope.action");
-  exactKeys(actionValue, ["requestId", "actionId", "resourceType", "resourceId", "inputHash"], "actorEnvelope.action");
-  const inputHash = text(actionValue.inputHash, "actorEnvelope.action.inputHash");
-  if (!HASH_PATTERN.test(inputHash)) fail("actorEnvelope.action.inputHash", "must be a lowercase sha256 digest");
-  const action = {
-    requestId: text(actionValue.requestId, "actorEnvelope.action.requestId"),
-    actionId: text(actionValue.actionId, "actorEnvelope.action.actionId"),
-    ...actionValue.resourceType === void 0 ? {} : { resourceType: text(actionValue.resourceType, "actorEnvelope.action.resourceType") },
-    ...actionValue.resourceId === void 0 ? {} : { resourceId: text(actionValue.resourceId, "actorEnvelope.action.resourceId") },
-    inputHash
-  };
-  if (action.resourceType === void 0 !== (action.resourceId === void 0)) {
-    fail("actorEnvelope.action", "resourceType and resourceId must be provided together");
-  }
-  const delegation = parseDelegation(envelope.delegation);
-  const directHuman = performer.principalType === "human" && performer.principalId === accountableSubject.principalId;
-  if (directHuman && delegation !== null) fail("actorEnvelope.delegation", "must be null for direct human action");
-  if (!directHuman && delegation === null) fail("actorEnvelope.delegation", "is required when performer differs from accountable subject");
-  if (delegation) {
-    const finalHop = delegation.lineage.at(-1);
-    if (!finalHop || finalHop.principalId !== performer.principalId || finalHop.principalType !== performer.principalType) {
-      fail("actorEnvelope.delegation.lineage", "must end with the performer");
-    }
-  }
-  if (performer.principalType === "external_agent" && (!performer.installationId || !performer.provider)) {
-    fail("actorEnvelope.performer", "external_agent requires installationId and provider");
-  }
-  if (performer.principalType === "managed_agent" && !performer.agentInstanceId) {
-    fail("actorEnvelope.performer.agentInstanceId", "is required for managed_agent");
-  }
-  if (performer.principalType === "browser_automation" && (!performer.installationId || !performer.browserSessionId)) {
-    fail("actorEnvelope.performer", "browser_automation requires installationId and browserSessionId");
-  }
-  return {
-    schemaVersion: ACTOR_ENVELOPE_VERSION,
-    organizationId,
-    accountableSubject,
-    performer,
-    delegation,
-    channel,
-    assurance,
-    action,
-    issuedAt,
-    ...expiresAt ? { expiresAt } : {}
-  };
-}
-function canonicalizeActorEnvelope(value) {
-  return canonicalJson(parseActorEnvelope(value));
-}
-function canonicalJson(value) {
-  if (value === null) return "null";
-  if (typeof value === "string" || typeof value === "boolean") return JSON.stringify(value);
-  if (typeof value === "number") {
-    if (!Number.isFinite(value)) throw new TypeError("Canonical JSON accepts finite numbers only.");
-    return JSON.stringify(value);
-  }
-  if (Array.isArray(value)) return `[${value.map(canonicalJson).join(",")}]`;
-  if (typeof value !== "object" || !value || ![Object.prototype, null].includes(Object.getPrototypeOf(value))) {
-    throw new TypeError("Canonical JSON accepts JSON objects, arrays, and primitives only.");
-  }
-  const entries = Object.entries(value).filter(([, item]) => item !== void 0).sort(([left], [right]) => left.localeCompare(right));
-  return `{${entries.map(([key, item]) => `${JSON.stringify(key)}:${canonicalJson(item)}`).join(",")}}`;
-}
-function parseAccountableSubject(value) {
-  const path = "actorEnvelope.accountableSubject";
-  const subject = record(value, path);
-  exactKeys(subject, ["principalType", "principalId", "displayName"], path);
-  return {
-    principalType: member(subject.principalType, ACCOUNTABLE_SUBJECT_TYPES, `${path}.principalType`),
-    principalId: text(subject.principalId, `${path}.principalId`),
-    ...subject.displayName === void 0 ? {} : { displayName: text(subject.displayName, `${path}.displayName`) }
-  };
-}
-async function sha256CanonicalValue(value) {
-  const bytes = new TextEncoder().encode(canonicalJson(value));
-  const digest = await crypto.subtle.digest("SHA-256", bytes);
-  return `sha256:${Array.from(new Uint8Array(digest), (byte) => byte.toString(16).padStart(2, "0")).join("")}`;
-}
-function parseIdentity(value, path) {
-  const identity = record(value, path);
-  exactKeys(identity, [
-    "principalType",
-    "principalId",
-    "displayName",
-    "installationId",
-    "agentInstanceId",
-    "browserSessionId",
-    "provider",
-    "model"
-  ], path);
-  return {
-    principalType: member(identity.principalType, PRINCIPAL_TYPES, `${path}.principalType`),
-    principalId: text(identity.principalId, `${path}.principalId`),
-    ...optionalTextFields(identity, path, [
-      "displayName",
-      "installationId",
-      "agentInstanceId",
-      "browserSessionId",
-      "provider",
-      "model"
-    ])
-  };
-}
-function parseDelegation(value) {
-  if (value === null) return null;
-  const delegation = record(value, "actorEnvelope.delegation");
-  exactKeys(delegation, ["taskId", "runId", "lineage"], "actorEnvelope.delegation");
-  if (!Array.isArray(delegation.lineage) || delegation.lineage.length === 0 || delegation.lineage.length > 16) {
-    fail("actorEnvelope.delegation.lineage", "must contain between 1 and 16 hops");
-  }
-  return {
-    taskId: text(delegation.taskId, "actorEnvelope.delegation.taskId"),
-    runId: text(delegation.runId, "actorEnvelope.delegation.runId"),
-    lineage: delegation.lineage.map((value2, index) => {
-      const hop = record(value2, `actorEnvelope.delegation.lineage[${index}]`);
-      exactKeys(hop, ["principalType", "principalId"], `actorEnvelope.delegation.lineage[${index}]`);
-      return {
-        principalType: member(hop.principalType, PRINCIPAL_TYPES, `actorEnvelope.delegation.lineage[${index}].principalType`),
-        principalId: text(hop.principalId, `actorEnvelope.delegation.lineage[${index}].principalId`)
-      };
-    })
-  };
-}
-function record(value, path) {
-  if (!value || typeof value !== "object" || Array.isArray(value)) fail(path, "must be an object");
-  return value;
-}
-function exactKeys(value, allowed, path) {
-  const unknown = Object.keys(value).filter((key) => !allowed.includes(key));
-  if (unknown.length) fail(path, `contains unknown field ${unknown[0]}`);
-}
-function text(value, path) {
-  if (typeof value !== "string" || value.trim() !== value || value.length === 0 || value.length > 256) {
-    fail(path, "must be a non-empty trimmed string of at most 256 characters");
-  }
-  return value;
-}
-function timestamp(value, path) {
-  const result = text(value, path);
-  if (!/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{3})?Z$/.test(result) || Number.isNaN(Date.parse(result))) {
-    fail(path, "must be an RFC 3339 UTC timestamp");
-  }
-  return result;
-}
-function member(value, values, path) {
-  if (typeof value !== "string" || !values.has(value)) fail(path, "contains an unsupported value");
-  return value;
-}
-function textArray(value, path) {
-  if (!Array.isArray(value) || value.length === 0 || value.length > 16) fail(path, "must contain between 1 and 16 values");
-  return value.map((item, index) => text(item, `${path}[${index}]`));
-}
-function optionalTextFields(value, path, keys) {
-  return Object.fromEntries(keys.flatMap((key) => value[key] === void 0 ? [] : [[key, text(value[key], `${path}.${key}`)]]));
-}
-function fail(path, message) {
-  throw new ActorEnvelopeValidationError(path, message);
-}
-
 // src/modules/workspaces.ts
 var ACTIONS = {
   list: "app_topolo_auth.workspaces.list",
@@ -4632,6 +4745,7 @@ export {
   DEFAULT_APP_URLS,
   IdentityModule,
   P2PModule,
+  TOPOLO_ACTOR_ENVELOPE_HEADER,
   TOPOLO_ENVIRONMENT_SERVICE_URLS,
   TOPOLO_RUNTIME_ENVIRONMENTS,
   TOPOLO_WIDGET_CONTRACT_VERSION,
@@ -4664,12 +4778,14 @@ export {
   createTopoloAgentExecutionContext,
   createTopoloWidgetError,
   createTopoloWidgetResponse,
+  decodeActorEnvelopeHeader,
   defineTopoloActionsWidget,
   defineTopoloActivityWidget,
   defineTopoloChartWidget,
   defineTopoloNotificationsWidget,
   defineTopoloStatsWidget,
   digestTopoloActionCatalog,
+  encodeActorEnvelopeHeader,
   encodeTopoloActionBase64,
   enrichActionContract,
   extractTopoloServiceErrorCode,

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@topolo/sdk",
   "packageManager": "pnpm@10.17.1",
-  "version": "0.15.0",
-  "topoloPublishedVersion": "0.15.0",
+  "version": "0.17.1",
+  "topoloPublishedVersion": "0.17.1",
   "description": "Typed client SDK for the Topolo platform. Used by TopoloCli, TopoloMCP, and third-party agents.",
   "license": "UNLICENSED",
   "author": "Topolo",