@topolo/sdk 0.14.4 → 0.15.0

package/README.md

@@ -86,6 +86,66 @@ Every request sends:
 Combined with the credential identity, this makes every platform API call
 traceable to a specific agent invocation.
 
+### Actor provenance
+
+`ActorEnvelope` is the versioned authority and provenance contract for work
+performed by humans, Topolo-managed agents, external harness installations,
+services, and declared browser automation. It always records the accountable
+subject and actual performer independently and binds them to one organization,
+task/run lineage, channel, assurance level, action, resource, and canonical
+input hash.
+
+```ts
+import {
+  parseActorEnvelope,
+  sha256CanonicalValue,
+  type ActorEnvelope,
+} from '@topolo/sdk';
+
+const actionInput = { designId: 'design_123', decision: 'approve' };
+const actorEnvelope: ActorEnvelope = parseActorEnvelope({
+  schemaVersion: 1,
+  organizationId: 'org_acme',
+  accountableSubject: {
+    principalType: 'human',
+    principalId: 'usr_ashley',
+    displayName: 'Ashley Lane',
+  },
+  performer: {
+    principalType: 'external_agent',
+    principalId: 'installation_codex_macbook',
+    installationId: 'installation_codex_macbook',
+    provider: 'openai',
+    model: 'gpt-5',
+  },
+  delegation: {
+    taskId: 'task_123',
+    runId: 'run_456',
+    lineage: [
+      { principalType: 'human', principalId: 'usr_ashley' },
+      { principalType: 'external_agent', principalId: 'installation_codex_macbook' },
+    ],
+  },
+  channel: 'mcp',
+  assurance: { level: 'workload_identity', methods: ['oauth_client'] },
+  action: {
+    requestId: 'req_789',
+    actionId: 'app_topolo_design.designs.approve',
+    resourceType: 'design',
+    resourceId: 'design_123',
+    inputHash: await sha256CanonicalValue(actionInput),
+  },
+  issuedAt: new Date().toISOString(),
+});
+```
+
+The parser rejects unknown fields, unsupported principal types, partial
+resource bindings, malformed hashes, and non-human performers without a
+delegation chain. External agents require an installation and provider;
+managed agents require an agent instance; browser automation requires both an
+installation and a browser-session identity. `X-Topolo-Agent` remains useful
+telemetry but is never trusted as provenance or approval authority.
+
 ## Modules
 
 | Surface      | Methods                               |

package/dist/index.cjs

@@ -21,6 +21,8 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var index_exports = {};
 __export(index_exports, {
   ACTION_CATALOG_DIGEST_ALGORITHM: () => ACTION_CATALOG_DIGEST_ALGORITHM,
+  ACTOR_ENVELOPE_VERSION: () => ACTOR_ENVELOPE_VERSION,
+  ActorEnvelopeValidationError: () => ActorEnvelopeValidationError,
   CrmModule: () => CrmModule,
   DEFAULT_APP_URLS: () => DEFAULT_APP_URLS,
   IdentityModule: () => IdentityModule,
@@ -42,10 +44,12 @@ __export(index_exports, {
   actionContractCompleteness: () => actionContractCompleteness,
   applicationEntryFromCatalog: () => applicationEntryFromCatalog,
   assertTopoloServiceUrlEnvironment: () => assertTopoloServiceUrlEnvironment,
+  canonicalJson: () => canonicalJson,
   canonicalTopoloErrorCode: () => canonicalTopoloErrorCode,
   canonicalTopoloRequestId: () => canonicalTopoloRequestId,
   canonicalTopoloRequired: () => canonicalTopoloRequired,
   canonicalTopoloRetryAfter: () => canonicalTopoloRetryAfter,
+  canonicalizeActorEnvelope: () => canonicalizeActorEnvelope,
   compactActionCatalogEntry: () => compactActionCatalogEntry,
   compactActionPlan: () => compactActionPlan,
   compactActionPreparation: () => compactActionPreparation,
@@ -69,6 +73,7 @@ __export(index_exports, {
   friendlyAppId: () => friendlyAppId,
   isTopoloWidgetOutputSchema: () => isTopoloWidgetOutputSchema,
   listApplicationDirectory: () => listApplicationDirectory,
+  parseActorEnvelope: () => parseActorEnvelope,
   parseTopoloActionUploadContract: () => parseTopoloActionUploadContract,
   preferExactActionMatches: () => preferExactActionMatches,
   prepareTopoloActionBase64UploadInput: () => prepareTopoloActionBase64UploadInput,
@@ -77,6 +82,7 @@ __export(index_exports, {
   resolveApplicationDirectoryEntry: () => resolveApplicationDirectoryEntry,
   resolveCatalogServiceUrl: () => resolveCatalogServiceUrl,
   resolveServiceUrl: () => resolveServiceUrl,
+  sha256CanonicalValue: () => sha256CanonicalValue,
   topoloErrorHint: () => topoloErrorHint,
   topoloServiceOrigins: () => topoloServiceOrigins,
   validateTopoloActionInput: () => validateTopoloActionInput,
@@ -250,10 +256,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)) {
@@ -268,14 +274,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;
@@ -327,8 +333,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;
   }
@@ -1670,14 +1676,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. */
@@ -2310,10 +2316,10 @@ function extractRequired(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);
       }
     }
@@ -2390,8 +2396,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);
@@ -2400,7 +2406,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;
   }
@@ -2516,8 +2522,8 @@ function canonicalPermission(value, appId) {
 function stableJson(value) {
   if (Array.isArray(value)) return `[${value.map(stableJson).join(",")}]`;
   if (value && typeof value === "object") {
-    const record = value;
-    return `{${Object.keys(record).sort().map((key) => `${JSON.stringify(key)}:${stableJson(record[key])}`).join(",")}}`;
+    const record2 = value;
+    return `{${Object.keys(record2).sort().map((key) => `${JSON.stringify(key)}:${stableJson(record2[key])}`).join(",")}}`;
   }
   return JSON.stringify(value);
 }
@@ -2658,8 +2664,8 @@ function resourceSchema(resource) {
 function derivedOutputSchema(action) {
   const resource = resourceFor(action);
   const operation = operationFor(action);
-  const record = resourceSchema(resource);
-  const records = { type: "array", items: record };
+  const record2 = resourceSchema(resource);
+  const records = { type: "array", items: record2 };
   const provenance = {
     "x-topolo-contract-source": "derived-action-metadata",
     "x-topolo-contract-precision": "structural"
@@ -2691,12 +2697,12 @@ function derivedOutputSchema(action) {
       title: `${action.title || action.name} response`,
       description: `Resource response returned by ${action.name}. The service may return the resource directly or in an envelope.`,
       oneOf: [
-        record,
+        record2,
         {
           type: "object",
           properties: {
-            data: record,
-            [resource]: record
+            data: record2,
+            [resource]: record2
           },
           additionalProperties: true
         }
@@ -2711,7 +2717,7 @@ function derivedOutputSchema(action) {
     properties: {
       success: { type: "boolean" },
       id: { type: "string" },
-      data: { oneOf: [record, { type: "object", additionalProperties: true }] },
+      data: { oneOf: [record2, { type: "object", additionalProperties: true }] },
       result: { type: "object", additionalProperties: true },
       message: { type: "string" }
     },
@@ -3010,6 +3016,218 @@ 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",
@@ -4501,6 +4719,8 @@ function createTopolo(options) {
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   ACTION_CATALOG_DIGEST_ALGORITHM,
+  ACTOR_ENVELOPE_VERSION,
+  ActorEnvelopeValidationError,
   CrmModule,
   DEFAULT_APP_URLS,
   IdentityModule,
@@ -4522,10 +4742,12 @@ function createTopolo(options) {
   actionContractCompleteness,
   applicationEntryFromCatalog,
   assertTopoloServiceUrlEnvironment,
+  canonicalJson,
   canonicalTopoloErrorCode,
   canonicalTopoloRequestId,
   canonicalTopoloRequired,
   canonicalTopoloRetryAfter,
+  canonicalizeActorEnvelope,
   compactActionCatalogEntry,
   compactActionPlan,
   compactActionPreparation,
@@ -4549,6 +4771,7 @@ function createTopolo(options) {
   friendlyAppId,
   isTopoloWidgetOutputSchema,
   listApplicationDirectory,
+  parseActorEnvelope,
   parseTopoloActionUploadContract,
   preferExactActionMatches,
   prepareTopoloActionBase64UploadInput,
@@ -4557,6 +4780,7 @@ function createTopolo(options) {
   resolveApplicationDirectoryEntry,
   resolveCatalogServiceUrl,
   resolveServiceUrl,
+  sha256CanonicalValue,
   topoloErrorHint,
   topoloServiceOrigins,
   validateTopoloActionInput,

package/dist/index.d.cts

@@ -254,6 +254,7 @@ interface TopoloActionCatalogEntry {
 }
 interface TopoloActionAgentContract {
     docsUrl?: string;
+    requiredReleaseCapability?: string;
     resourceContext?: {
         kind?: string;
         required?: boolean;
@@ -901,6 +902,64 @@ declare class IdentityModule {
     whoami(): Promise<CredentialIntrospection>;
 }
 
+declare const ACTOR_ENVELOPE_VERSION: 1;
+type ActorPrincipalType = 'human' | 'managed_agent' | 'external_agent' | 'service' | 'browser_automation';
+type AccountableSubjectType = 'human' | 'organization';
+type ActorChannel = 'web' | 'mobile' | 'cli' | 'mcp' | 'api' | 'workflow' | 'browser_automation';
+type ActorAssurance = 'authenticated' | 'workload_identity' | 'user_verified';
+interface ActorIdentity {
+    principalType: ActorPrincipalType;
+    principalId: string;
+    displayName?: string;
+    installationId?: string;
+    agentInstanceId?: string;
+    browserSessionId?: string;
+    provider?: string;
+    model?: string;
+}
+interface AccountableSubject {
+    principalType: AccountableSubjectType;
+    principalId: string;
+    displayName?: string;
+}
+interface ActorDelegationHop {
+    principalType: ActorPrincipalType;
+    principalId: string;
+}
+interface ActorEnvelope {
+    schemaVersion: typeof ACTOR_ENVELOPE_VERSION;
+    organizationId: string;
+    accountableSubject: AccountableSubject;
+    performer: ActorIdentity;
+    delegation: {
+        taskId: string;
+        runId: string;
+        lineage: ActorDelegationHop[];
+    } | null;
+    channel: ActorChannel;
+    assurance: {
+        level: ActorAssurance;
+        methods: string[];
+    };
+    action: {
+        requestId: string;
+        actionId: string;
+        resourceType?: string;
+        resourceId?: string;
+        inputHash: string;
+    };
+    issuedAt: string;
+    expiresAt?: string;
+}
+declare class ActorEnvelopeValidationError extends Error {
+    readonly path: string;
+    constructor(path: string, message: string);
+}
+declare function parseActorEnvelope(value: unknown): ActorEnvelope;
+declare function canonicalizeActorEnvelope(value: unknown): string;
+declare function canonicalJson(value: unknown): string;
+declare function sha256CanonicalValue(value: unknown): Promise<string>;
+
 interface TopoloWorkspace {
     id: string;
     appId: string;
@@ -1593,4 +1652,4 @@ declare function createTopolo(options: TopoloClientOptions): {
 };
 type Topolo = ReturnType<typeof createTopolo>;
 
-export { ACTION_CATALOG_DIGEST_ALGORITHM, type ActionContractManifest, type ActionContractSource, type AgentIdentity, type AppApiId, type ApplicationCatalogEntry, type ApplicationDeployTarget, type ApplicationDirectory, type ApplicationDirectoryApplication, type ApplicationDirectoryClient, type ApplicationDirectorySource, type ApplicationId, type CredentialIntrospection, type CrmContactSummary, CrmModule, DEFAULT_APP_URLS, type DeviceAuthorizationResponse, IdentityModule, type ListContactsOptions, type ListContactsResult, type OAuthHelperOptions, type P2PActionDetail, type P2PActionRequestInput, type P2PActionRequestResult, type P2PActionRow, type P2PActionRun, type P2PCapability, type P2PConnection, type P2PHold, type P2PLedgerEntry, P2PModule, type P2PPolicy, type P2PPricingModel, type P2PSettlementBatch, type P2PSettlementGroup, type PublishCapabilityInput, type RequestOptions, type ServiceCatalogUrlEntry, TOPOLO_ENVIRONMENT_SERVICE_URLS, TOPOLO_RUNTIME_ENVIRONMENTS, TOPOLO_WIDGET_CONTRACT_VERSION, TOPOLO_WIDGET_ENDPOINT, TOPOLO_WIDGET_OUTPUT_SCHEMA, TOPOLO_WIDGET_REFRESH_INTERVAL_MS, type TokenResponse, type Topolo, type TopoloActionAgentContract, type TopoloActionCatalogEntry, type TopoloActionCatalogSummary, type TopoloActionDigestInput, type TopoloActionPlan, type TopoloActionPreparation, type TopoloActionUploadOptions, type TopoloActionValidationIssue, type TopoloActionValidationResult, type TopoloActionsWidget, type TopoloActivityWidget, type TopoloAgentExecutionContext, type TopoloApiKeyResourceMetadata, TopoloAuthError, type TopoloBinaryResponse, type TopoloBindableResource, type TopoloBindableResourceCatalog, type TopoloChartWidget, TopoloClient, type TopoloClientOptions, TopoloConfirmationRequiredError, type TopoloCredential, type TopoloDebugEvent, TopoloHttpError, type TopoloInlineBase64UploadContract, type TopoloJsonSchema, type TopoloNotificationsWidget, TopoloOAuth, TopoloPermissionError, type TopoloRuntimeEnvironment, TopoloSdkError, type TopoloServiceCatalogEntry, type TopoloStatsWidget, type TopoloWidget, type TopoloWidgetAccessibility, type TopoloWidgetActionBinding, type TopoloWidgetActionRecovery, type TopoloWidgetActivityItem, type TopoloWidgetApiError, type TopoloWidgetApiErrorResponse, type TopoloWidgetApiResponse, type TopoloWidgetApiSuccessResponse, type TopoloWidgetBase, type TopoloWidgetConfig, type TopoloWidgetConfiguration, type TopoloWidgetConfigurationField, type TopoloWidgetConfigurationOption, type TopoloWidgetContext, type TopoloWidgetContribution, type TopoloWidgetDatasetDefinition, type TopoloWidgetDimension, type TopoloWidgetDimensionDefinition, type TopoloWidgetDraft, type TopoloWidgetDrilldown, type TopoloWidgetErrorResponseOptions, type TopoloWidgetEventDefinition, type TopoloWidgetLifecycleStage, type TopoloWidgetLocalization, type TopoloWidgetMetric, type TopoloWidgetMetricAggregation, type TopoloWidgetMetricComparison, type TopoloWidgetMetricDefinition, type TopoloWidgetMetricSemantic, type TopoloWidgetNotificationItem, type TopoloWidgetPeriod, type TopoloWidgetPresentation, type TopoloWidgetRefreshPolicy, type TopoloWidgetResourceBinding, type TopoloWidgetResponseOptions, type TopoloWidgetSeries, type TopoloWidgetSeriesDefinition, type TopoloWidgetSeriesPoint, type TopoloWidgetSize, type TopoloWidgetState, type TopoloWidgetStatus, type TopoloWidgetType, type TopoloWidgetValidationResult, type TopoloWidgetVisualizationFamily, type TopoloWidgetWorkspaceSelector, type TopoloWorkspace, type TopoloWorkspaceListResult, type TopoloWorkspaceMutationResult, type TopoloWorkspacePolicy, WorkspacesModule, actionContractCompleteness, applicationEntryFromCatalog, assertTopoloServiceUrlEnvironment, canonicalTopoloErrorCode, canonicalTopoloRequestId, canonicalTopoloRequired, canonicalTopoloRetryAfter, compactActionCatalogEntry, compactActionPlan, compactActionPreparation, compactActionResult, compactActionValidation, createTopolo, createTopoloAgentExecutionContext, createTopoloWidgetError, createTopoloWidgetResponse, defineTopoloActionsWidget, defineTopoloActivityWidget, defineTopoloChartWidget, defineTopoloNotificationsWidget, defineTopoloStatsWidget, digestTopoloActionCatalog, encodeTopoloActionBase64, enrichActionContract, extractTopoloServiceErrorCode, extractTopoloServiceErrorDetails, formatDirectoryApplicationIds, friendlyAppId, isTopoloWidgetOutputSchema, listApplicationDirectory, parseTopoloActionUploadContract, preferExactActionMatches, prepareTopoloActionBase64UploadInput, prepareTopoloActionUploadInput, publicTopoloErrorMessage, resolveApplicationDirectoryEntry, resolveCatalogServiceUrl, resolveServiceUrl, topoloErrorHint, topoloServiceOrigins, validateTopoloActionInput, validateTopoloWidgetResponse };
+export { ACTION_CATALOG_DIGEST_ALGORITHM, ACTOR_ENVELOPE_VERSION, type AccountableSubject, type AccountableSubjectType, type ActionContractManifest, type ActionContractSource, type ActorAssurance, type ActorChannel, type ActorDelegationHop, type ActorEnvelope, ActorEnvelopeValidationError, type ActorIdentity, type ActorPrincipalType, type AgentIdentity, type AppApiId, type ApplicationCatalogEntry, type ApplicationDeployTarget, type ApplicationDirectory, type ApplicationDirectoryApplication, type ApplicationDirectoryClient, type ApplicationDirectorySource, type ApplicationId, type CredentialIntrospection, type CrmContactSummary, CrmModule, DEFAULT_APP_URLS, type DeviceAuthorizationResponse, IdentityModule, type ListContactsOptions, type ListContactsResult, type OAuthHelperOptions, type P2PActionDetail, type P2PActionRequestInput, type P2PActionRequestResult, type P2PActionRow, type P2PActionRun, type P2PCapability, type P2PConnection, type P2PHold, type P2PLedgerEntry, P2PModule, type P2PPolicy, type P2PPricingModel, type P2PSettlementBatch, type P2PSettlementGroup, type PublishCapabilityInput, type RequestOptions, type ServiceCatalogUrlEntry, TOPOLO_ENVIRONMENT_SERVICE_URLS, TOPOLO_RUNTIME_ENVIRONMENTS, TOPOLO_WIDGET_CONTRACT_VERSION, TOPOLO_WIDGET_ENDPOINT, TOPOLO_WIDGET_OUTPUT_SCHEMA, TOPOLO_WIDGET_REFRESH_INTERVAL_MS, type TokenResponse, type Topolo, type TopoloActionAgentContract, type TopoloActionCatalogEntry, type TopoloActionCatalogSummary, type TopoloActionDigestInput, type TopoloActionPlan, type TopoloActionPreparation, type TopoloActionUploadOptions, type TopoloActionValidationIssue, type TopoloActionValidationResult, type TopoloActionsWidget, type TopoloActivityWidget, type TopoloAgentExecutionContext, type TopoloApiKeyResourceMetadata, TopoloAuthError, type TopoloBinaryResponse, type TopoloBindableResource, type TopoloBindableResourceCatalog, type TopoloChartWidget, TopoloClient, type TopoloClientOptions, TopoloConfirmationRequiredError, type TopoloCredential, type TopoloDebugEvent, TopoloHttpError, type TopoloInlineBase64UploadContract, type TopoloJsonSchema, type TopoloNotificationsWidget, TopoloOAuth, TopoloPermissionError, type TopoloRuntimeEnvironment, TopoloSdkError, type TopoloServiceCatalogEntry, type TopoloStatsWidget, type TopoloWidget, type TopoloWidgetAccessibility, type TopoloWidgetActionBinding, type TopoloWidgetActionRecovery, type TopoloWidgetActivityItem, type TopoloWidgetApiError, type TopoloWidgetApiErrorResponse, type TopoloWidgetApiResponse, type TopoloWidgetApiSuccessResponse, type TopoloWidgetBase, type TopoloWidgetConfig, type TopoloWidgetConfiguration, type TopoloWidgetConfigurationField, type TopoloWidgetConfigurationOption, type TopoloWidgetContext, type TopoloWidgetContribution, type TopoloWidgetDatasetDefinition, type TopoloWidgetDimension, type TopoloWidgetDimensionDefinition, type TopoloWidgetDraft, type TopoloWidgetDrilldown, type TopoloWidgetErrorResponseOptions, type TopoloWidgetEventDefinition, type TopoloWidgetLifecycleStage, type TopoloWidgetLocalization, type TopoloWidgetMetric, type TopoloWidgetMetricAggregation, type TopoloWidgetMetricComparison, type TopoloWidgetMetricDefinition, type TopoloWidgetMetricSemantic, type TopoloWidgetNotificationItem, type TopoloWidgetPeriod, type TopoloWidgetPresentation, type TopoloWidgetRefreshPolicy, type TopoloWidgetResourceBinding, type TopoloWidgetResponseOptions, type TopoloWidgetSeries, type TopoloWidgetSeriesDefinition, type TopoloWidgetSeriesPoint, type TopoloWidgetSize, type TopoloWidgetState, type TopoloWidgetStatus, type TopoloWidgetType, type TopoloWidgetValidationResult, type TopoloWidgetVisualizationFamily, type TopoloWidgetWorkspaceSelector, type TopoloWorkspace, type TopoloWorkspaceListResult, type TopoloWorkspaceMutationResult, type TopoloWorkspacePolicy, WorkspacesModule, actionContractCompleteness, applicationEntryFromCatalog, assertTopoloServiceUrlEnvironment, canonicalJson, canonicalTopoloErrorCode, canonicalTopoloRequestId, canonicalTopoloRequired, canonicalTopoloRetryAfter, canonicalizeActorEnvelope, compactActionCatalogEntry, compactActionPlan, compactActionPreparation, compactActionResult, compactActionValidation, createTopolo, createTopoloAgentExecutionContext, createTopoloWidgetError, createTopoloWidgetResponse, defineTopoloActionsWidget, defineTopoloActivityWidget, defineTopoloChartWidget, defineTopoloNotificationsWidget, defineTopoloStatsWidget, digestTopoloActionCatalog, encodeTopoloActionBase64, enrichActionContract, extractTopoloServiceErrorCode, extractTopoloServiceErrorDetails, formatDirectoryApplicationIds, friendlyAppId, isTopoloWidgetOutputSchema, listApplicationDirectory, parseActorEnvelope, parseTopoloActionUploadContract, preferExactActionMatches, prepareTopoloActionBase64UploadInput, prepareTopoloActionUploadInput, publicTopoloErrorMessage, resolveApplicationDirectoryEntry, resolveCatalogServiceUrl, resolveServiceUrl, sha256CanonicalValue, topoloErrorHint, topoloServiceOrigins, validateTopoloActionInput, validateTopoloWidgetResponse };

package/dist/index.d.ts

@@ -254,6 +254,7 @@ interface TopoloActionCatalogEntry {
 }
 interface TopoloActionAgentContract {
     docsUrl?: string;
+    requiredReleaseCapability?: string;
     resourceContext?: {
         kind?: string;
         required?: boolean;
@@ -901,6 +902,64 @@ declare class IdentityModule {
     whoami(): Promise<CredentialIntrospection>;
 }
 
+declare const ACTOR_ENVELOPE_VERSION: 1;
+type ActorPrincipalType = 'human' | 'managed_agent' | 'external_agent' | 'service' | 'browser_automation';
+type AccountableSubjectType = 'human' | 'organization';
+type ActorChannel = 'web' | 'mobile' | 'cli' | 'mcp' | 'api' | 'workflow' | 'browser_automation';
+type ActorAssurance = 'authenticated' | 'workload_identity' | 'user_verified';
+interface ActorIdentity {
+    principalType: ActorPrincipalType;
+    principalId: string;
+    displayName?: string;
+    installationId?: string;
+    agentInstanceId?: string;
+    browserSessionId?: string;
+    provider?: string;
+    model?: string;
+}
+interface AccountableSubject {
+    principalType: AccountableSubjectType;
+    principalId: string;
+    displayName?: string;
+}
+interface ActorDelegationHop {
+    principalType: ActorPrincipalType;
+    principalId: string;
+}
+interface ActorEnvelope {
+    schemaVersion: typeof ACTOR_ENVELOPE_VERSION;
+    organizationId: string;
+    accountableSubject: AccountableSubject;
+    performer: ActorIdentity;
+    delegation: {
+        taskId: string;
+        runId: string;
+        lineage: ActorDelegationHop[];
+    } | null;
+    channel: ActorChannel;
+    assurance: {
+        level: ActorAssurance;
+        methods: string[];
+    };
+    action: {
+        requestId: string;
+        actionId: string;
+        resourceType?: string;
+        resourceId?: string;
+        inputHash: string;
+    };
+    issuedAt: string;
+    expiresAt?: string;
+}
+declare class ActorEnvelopeValidationError extends Error {
+    readonly path: string;
+    constructor(path: string, message: string);
+}
+declare function parseActorEnvelope(value: unknown): ActorEnvelope;
+declare function canonicalizeActorEnvelope(value: unknown): string;
+declare function canonicalJson(value: unknown): string;
+declare function sha256CanonicalValue(value: unknown): Promise<string>;
+
 interface TopoloWorkspace {
     id: string;
     appId: string;
@@ -1593,4 +1652,4 @@ declare function createTopolo(options: TopoloClientOptions): {
 };
 type Topolo = ReturnType<typeof createTopolo>;
 
-export { ACTION_CATALOG_DIGEST_ALGORITHM, type ActionContractManifest, type ActionContractSource, type AgentIdentity, type AppApiId, type ApplicationCatalogEntry, type ApplicationDeployTarget, type ApplicationDirectory, type ApplicationDirectoryApplication, type ApplicationDirectoryClient, type ApplicationDirectorySource, type ApplicationId, type CredentialIntrospection, type CrmContactSummary, CrmModule, DEFAULT_APP_URLS, type DeviceAuthorizationResponse, IdentityModule, type ListContactsOptions, type ListContactsResult, type OAuthHelperOptions, type P2PActionDetail, type P2PActionRequestInput, type P2PActionRequestResult, type P2PActionRow, type P2PActionRun, type P2PCapability, type P2PConnection, type P2PHold, type P2PLedgerEntry, P2PModule, type P2PPolicy, type P2PPricingModel, type P2PSettlementBatch, type P2PSettlementGroup, type PublishCapabilityInput, type RequestOptions, type ServiceCatalogUrlEntry, TOPOLO_ENVIRONMENT_SERVICE_URLS, TOPOLO_RUNTIME_ENVIRONMENTS, TOPOLO_WIDGET_CONTRACT_VERSION, TOPOLO_WIDGET_ENDPOINT, TOPOLO_WIDGET_OUTPUT_SCHEMA, TOPOLO_WIDGET_REFRESH_INTERVAL_MS, type TokenResponse, type Topolo, type TopoloActionAgentContract, type TopoloActionCatalogEntry, type TopoloActionCatalogSummary, type TopoloActionDigestInput, type TopoloActionPlan, type TopoloActionPreparation, type TopoloActionUploadOptions, type TopoloActionValidationIssue, type TopoloActionValidationResult, type TopoloActionsWidget, type TopoloActivityWidget, type TopoloAgentExecutionContext, type TopoloApiKeyResourceMetadata, TopoloAuthError, type TopoloBinaryResponse, type TopoloBindableResource, type TopoloBindableResourceCatalog, type TopoloChartWidget, TopoloClient, type TopoloClientOptions, TopoloConfirmationRequiredError, type TopoloCredential, type TopoloDebugEvent, TopoloHttpError, type TopoloInlineBase64UploadContract, type TopoloJsonSchema, type TopoloNotificationsWidget, TopoloOAuth, TopoloPermissionError, type TopoloRuntimeEnvironment, TopoloSdkError, type TopoloServiceCatalogEntry, type TopoloStatsWidget, type TopoloWidget, type TopoloWidgetAccessibility, type TopoloWidgetActionBinding, type TopoloWidgetActionRecovery, type TopoloWidgetActivityItem, type TopoloWidgetApiError, type TopoloWidgetApiErrorResponse, type TopoloWidgetApiResponse, type TopoloWidgetApiSuccessResponse, type TopoloWidgetBase, type TopoloWidgetConfig, type TopoloWidgetConfiguration, type TopoloWidgetConfigurationField, type TopoloWidgetConfigurationOption, type TopoloWidgetContext, type TopoloWidgetContribution, type TopoloWidgetDatasetDefinition, type TopoloWidgetDimension, type TopoloWidgetDimensionDefinition, type TopoloWidgetDraft, type TopoloWidgetDrilldown, type TopoloWidgetErrorResponseOptions, type TopoloWidgetEventDefinition, type TopoloWidgetLifecycleStage, type TopoloWidgetLocalization, type TopoloWidgetMetric, type TopoloWidgetMetricAggregation, type TopoloWidgetMetricComparison, type TopoloWidgetMetricDefinition, type TopoloWidgetMetricSemantic, type TopoloWidgetNotificationItem, type TopoloWidgetPeriod, type TopoloWidgetPresentation, type TopoloWidgetRefreshPolicy, type TopoloWidgetResourceBinding, type TopoloWidgetResponseOptions, type TopoloWidgetSeries, type TopoloWidgetSeriesDefinition, type TopoloWidgetSeriesPoint, type TopoloWidgetSize, type TopoloWidgetState, type TopoloWidgetStatus, type TopoloWidgetType, type TopoloWidgetValidationResult, type TopoloWidgetVisualizationFamily, type TopoloWidgetWorkspaceSelector, type TopoloWorkspace, type TopoloWorkspaceListResult, type TopoloWorkspaceMutationResult, type TopoloWorkspacePolicy, WorkspacesModule, actionContractCompleteness, applicationEntryFromCatalog, assertTopoloServiceUrlEnvironment, canonicalTopoloErrorCode, canonicalTopoloRequestId, canonicalTopoloRequired, canonicalTopoloRetryAfter, compactActionCatalogEntry, compactActionPlan, compactActionPreparation, compactActionResult, compactActionValidation, createTopolo, createTopoloAgentExecutionContext, createTopoloWidgetError, createTopoloWidgetResponse, defineTopoloActionsWidget, defineTopoloActivityWidget, defineTopoloChartWidget, defineTopoloNotificationsWidget, defineTopoloStatsWidget, digestTopoloActionCatalog, encodeTopoloActionBase64, enrichActionContract, extractTopoloServiceErrorCode, extractTopoloServiceErrorDetails, formatDirectoryApplicationIds, friendlyAppId, isTopoloWidgetOutputSchema, listApplicationDirectory, parseTopoloActionUploadContract, preferExactActionMatches, prepareTopoloActionBase64UploadInput, prepareTopoloActionUploadInput, publicTopoloErrorMessage, resolveApplicationDirectoryEntry, resolveCatalogServiceUrl, resolveServiceUrl, topoloErrorHint, topoloServiceOrigins, validateTopoloActionInput, validateTopoloWidgetResponse };
+export { ACTION_CATALOG_DIGEST_ALGORITHM, ACTOR_ENVELOPE_VERSION, type AccountableSubject, type AccountableSubjectType, type ActionContractManifest, type ActionContractSource, type ActorAssurance, type ActorChannel, type ActorDelegationHop, type ActorEnvelope, ActorEnvelopeValidationError, type ActorIdentity, type ActorPrincipalType, type AgentIdentity, type AppApiId, type ApplicationCatalogEntry, type ApplicationDeployTarget, type ApplicationDirectory, type ApplicationDirectoryApplication, type ApplicationDirectoryClient, type ApplicationDirectorySource, type ApplicationId, type CredentialIntrospection, type CrmContactSummary, CrmModule, DEFAULT_APP_URLS, type DeviceAuthorizationResponse, IdentityModule, type ListContactsOptions, type ListContactsResult, type OAuthHelperOptions, type P2PActionDetail, type P2PActionRequestInput, type P2PActionRequestResult, type P2PActionRow, type P2PActionRun, type P2PCapability, type P2PConnection, type P2PHold, type P2PLedgerEntry, P2PModule, type P2PPolicy, type P2PPricingModel, type P2PSettlementBatch, type P2PSettlementGroup, type PublishCapabilityInput, type RequestOptions, type ServiceCatalogUrlEntry, TOPOLO_ENVIRONMENT_SERVICE_URLS, TOPOLO_RUNTIME_ENVIRONMENTS, TOPOLO_WIDGET_CONTRACT_VERSION, TOPOLO_WIDGET_ENDPOINT, TOPOLO_WIDGET_OUTPUT_SCHEMA, TOPOLO_WIDGET_REFRESH_INTERVAL_MS, type TokenResponse, type Topolo, type TopoloActionAgentContract, type TopoloActionCatalogEntry, type TopoloActionCatalogSummary, type TopoloActionDigestInput, type TopoloActionPlan, type TopoloActionPreparation, type TopoloActionUploadOptions, type TopoloActionValidationIssue, type TopoloActionValidationResult, type TopoloActionsWidget, type TopoloActivityWidget, type TopoloAgentExecutionContext, type TopoloApiKeyResourceMetadata, TopoloAuthError, type TopoloBinaryResponse, type TopoloBindableResource, type TopoloBindableResourceCatalog, type TopoloChartWidget, TopoloClient, type TopoloClientOptions, TopoloConfirmationRequiredError, type TopoloCredential, type TopoloDebugEvent, TopoloHttpError, type TopoloInlineBase64UploadContract, type TopoloJsonSchema, type TopoloNotificationsWidget, TopoloOAuth, TopoloPermissionError, type TopoloRuntimeEnvironment, TopoloSdkError, type TopoloServiceCatalogEntry, type TopoloStatsWidget, type TopoloWidget, type TopoloWidgetAccessibility, type TopoloWidgetActionBinding, type TopoloWidgetActionRecovery, type TopoloWidgetActivityItem, type TopoloWidgetApiError, type TopoloWidgetApiErrorResponse, type TopoloWidgetApiResponse, type TopoloWidgetApiSuccessResponse, type TopoloWidgetBase, type TopoloWidgetConfig, type TopoloWidgetConfiguration, type TopoloWidgetConfigurationField, type TopoloWidgetConfigurationOption, type TopoloWidgetContext, type TopoloWidgetContribution, type TopoloWidgetDatasetDefinition, type TopoloWidgetDimension, type TopoloWidgetDimensionDefinition, type TopoloWidgetDraft, type TopoloWidgetDrilldown, type TopoloWidgetErrorResponseOptions, type TopoloWidgetEventDefinition, type TopoloWidgetLifecycleStage, type TopoloWidgetLocalization, type TopoloWidgetMetric, type TopoloWidgetMetricAggregation, type TopoloWidgetMetricComparison, type TopoloWidgetMetricDefinition, type TopoloWidgetMetricSemantic, type TopoloWidgetNotificationItem, type TopoloWidgetPeriod, type TopoloWidgetPresentation, type TopoloWidgetRefreshPolicy, type TopoloWidgetResourceBinding, type TopoloWidgetResponseOptions, type TopoloWidgetSeries, type TopoloWidgetSeriesDefinition, type TopoloWidgetSeriesPoint, type TopoloWidgetSize, type TopoloWidgetState, type TopoloWidgetStatus, type TopoloWidgetType, type TopoloWidgetValidationResult, type TopoloWidgetVisualizationFamily, type TopoloWidgetWorkspaceSelector, type TopoloWorkspace, type TopoloWorkspaceListResult, type TopoloWorkspaceMutationResult, type TopoloWorkspacePolicy, WorkspacesModule, actionContractCompleteness, applicationEntryFromCatalog, assertTopoloServiceUrlEnvironment, canonicalJson, canonicalTopoloErrorCode, canonicalTopoloRequestId, canonicalTopoloRequired, canonicalTopoloRetryAfter, canonicalizeActorEnvelope, compactActionCatalogEntry, compactActionPlan, compactActionPreparation, compactActionResult, compactActionValidation, createTopolo, createTopoloAgentExecutionContext, createTopoloWidgetError, createTopoloWidgetResponse, defineTopoloActionsWidget, defineTopoloActivityWidget, defineTopoloChartWidget, defineTopoloNotificationsWidget, defineTopoloStatsWidget, digestTopoloActionCatalog, encodeTopoloActionBase64, enrichActionContract, extractTopoloServiceErrorCode, extractTopoloServiceErrorDetails, formatDirectoryApplicationIds, friendlyAppId, isTopoloWidgetOutputSchema, listApplicationDirectory, parseActorEnvelope, parseTopoloActionUploadContract, preferExactActionMatches, prepareTopoloActionBase64UploadInput, prepareTopoloActionUploadInput, publicTopoloErrorMessage, resolveApplicationDirectoryEntry, resolveCatalogServiceUrl, resolveServiceUrl, sha256CanonicalValue, topoloErrorHint, topoloServiceOrigins, validateTopoloActionInput, validateTopoloWidgetResponse };

package/dist/index.js

@@ -164,10 +164,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)) {
@@ -182,14 +182,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;
@@ -241,8 +241,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;
   }
@@ -1584,14 +1584,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. */
@@ -2224,10 +2224,10 @@ function extractRequired(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);
       }
     }
@@ -2304,8 +2304,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);
@@ -2314,7 +2314,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;
   }
@@ -2430,8 +2430,8 @@ function canonicalPermission(value, appId) {
 function stableJson(value) {
   if (Array.isArray(value)) return `[${value.map(stableJson).join(",")}]`;
   if (value && typeof value === "object") {
-    const record = value;
-    return `{${Object.keys(record).sort().map((key) => `${JSON.stringify(key)}:${stableJson(record[key])}`).join(",")}}`;
+    const record2 = value;
+    return `{${Object.keys(record2).sort().map((key) => `${JSON.stringify(key)}:${stableJson(record2[key])}`).join(",")}}`;
   }
   return JSON.stringify(value);
 }
@@ -2572,8 +2572,8 @@ function resourceSchema(resource) {
 function derivedOutputSchema(action) {
   const resource = resourceFor(action);
   const operation = operationFor(action);
-  const record = resourceSchema(resource);
-  const records = { type: "array", items: record };
+  const record2 = resourceSchema(resource);
+  const records = { type: "array", items: record2 };
   const provenance = {
     "x-topolo-contract-source": "derived-action-metadata",
     "x-topolo-contract-precision": "structural"
@@ -2605,12 +2605,12 @@ function derivedOutputSchema(action) {
       title: `${action.title || action.name} response`,
       description: `Resource response returned by ${action.name}. The service may return the resource directly or in an envelope.`,
       oneOf: [
-        record,
+        record2,
         {
           type: "object",
           properties: {
-            data: record,
-            [resource]: record
+            data: record2,
+            [resource]: record2
           },
           additionalProperties: true
         }
@@ -2625,7 +2625,7 @@ function derivedOutputSchema(action) {
     properties: {
       success: { type: "boolean" },
       id: { type: "string" },
-      data: { oneOf: [record, { type: "object", additionalProperties: true }] },
+      data: { oneOf: [record2, { type: "object", additionalProperties: true }] },
       result: { type: "object", additionalProperties: true },
       message: { type: "string" }
     },
@@ -2924,6 +2924,218 @@ 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",
@@ -4414,6 +4626,8 @@ function createTopolo(options) {
 }
 export {
   ACTION_CATALOG_DIGEST_ALGORITHM,
+  ACTOR_ENVELOPE_VERSION,
+  ActorEnvelopeValidationError,
   CrmModule,
   DEFAULT_APP_URLS,
   IdentityModule,
@@ -4435,10 +4649,12 @@ export {
   actionContractCompleteness,
   applicationEntryFromCatalog,
   assertTopoloServiceUrlEnvironment,
+  canonicalJson,
   canonicalTopoloErrorCode,
   canonicalTopoloRequestId,
   canonicalTopoloRequired,
   canonicalTopoloRetryAfter,
+  canonicalizeActorEnvelope,
   compactActionCatalogEntry,
   compactActionPlan,
   compactActionPreparation,
@@ -4462,6 +4678,7 @@ export {
   friendlyAppId,
   isTopoloWidgetOutputSchema,
   listApplicationDirectory,
+  parseActorEnvelope,
   parseTopoloActionUploadContract,
   preferExactActionMatches,
   prepareTopoloActionBase64UploadInput,
@@ -4470,6 +4687,7 @@ export {
   resolveApplicationDirectoryEntry,
   resolveCatalogServiceUrl,
   resolveServiceUrl,
+  sha256CanonicalValue,
   topoloErrorHint,
   topoloServiceOrigins,
   validateTopoloActionInput,

package/package.json

@@ -1,7 +1,8 @@
 {
   "name": "@topolo/sdk",
-  "version": "0.14.4",
-  "topoloPublishedVersion": "0.14.4",
+  "packageManager": "pnpm@10.17.1",
+  "version": "0.15.0",
+  "topoloPublishedVersion": "0.15.0",
   "description": "Typed client SDK for the Topolo platform. Used by TopoloCli, TopoloMCP, and third-party agents.",
   "license": "UNLICENSED",
   "author": "Topolo",
@@ -32,7 +33,7 @@
     "test": "vitest run",
     "test:watch": "vitest",
     "prepublishOnly": "npm run build && npm run verify:package",
-    "verify:package": "node ../../tooling/verify-npm-package.mjs .",
+    "verify:package": "npm pack --dry-run",
     "coverage": "vitest run --coverage"
   },
   "topolo_quality": {
@@ -50,7 +51,7 @@
             "tsconfig.json",
             "vitest.config.ts"
           ],
-          "digest": "2bb3a53e5241cde11d06fe2bd355cac5cd9141b1b5ad5f71ebc2d621c1c33fb0"
+          "digest": "764b584c653234937a1ba11f34a898941c62ebd8bf973db6ed0869b7f4a11951"
         }
       }
     ]
@@ -64,5 +65,9 @@
   },
   "engines": {
     "node": ">=20"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Topolo-io/topolo-sdk.git"
   }
 }