@topolo/sdk 0.16.0 → 0.17.1

package/dist/index.cjs

@@ -1381,6 +1381,7 @@ var NEGATIVE_CACHE_TTL_MS = 60 * 1e3;
 var TopoloClient = class _TopoloClient {
   credential;
   agent;
+  actorContext;
   serviceUrls;
   environment;
   appIds;
@@ -1411,6 +1412,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;
@@ -2126,8 +2132,9 @@ var TopoloClient = class _TopoloClient {
       );
     }
     const mapped = mapActionInput(entry, input);
-    if (options.actorEnvelope) {
-      const actorEnvelope = parseActorEnvelope(options.actorEnvelope);
+    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.");
       }
@@ -2148,7 +2155,7 @@ var TopoloClient = class _TopoloClient {
       ...mapped.query ? { query: mapped.query } : {},
       ...mapped.body !== void 0 ? { body: mapped.body } : {},
       ...options.resource ? { resource: options.resource } : {},
-      ...options.actorEnvelope ? { actorEnvelope: options.actorEnvelope } : {},
+      ...resolvedActorEnvelope ? { actorEnvelope: resolvedActorEnvelope } : {},
       headers: {
         [TOPOLO_ACTION_ID_HEADER]: entry.actionId,
         [TOPOLO_ACTION_NAME_HEADER]: entry.name
@@ -2157,6 +2164,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
@@ -2184,7 +2241,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,
@@ -2549,6 +2617,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;

package/dist/index.d.cts

@@ -146,6 +146,12 @@ declare function encodeTopoloActionBase64(bytes: Uint8Array): string;
 interface TopoloClientOptions {
     credential: TopoloCredential;
     agent: AgentIdentity;
+    /** Host surface used to attribute actions performed with verified agent credentials. */
+    actorContext?: {
+        channel: ActorChannel;
+        taskId?: string;
+        runId?: string;
+    };
     /** Per-service URL overrides. Useful for staging/dev. */
     serviceUrls?: Record<string, string>;
     /** Explicit environment used to reject cross-environment service and action origins. */
@@ -403,6 +409,7 @@ interface TopoloCatalogSearchOptions {
 declare class TopoloClient {
     private credential;
     private readonly agent;
+    private readonly actorContext?;
     private readonly serviceUrls?;
     private readonly environment?;
     private readonly appIds?;
@@ -534,6 +541,7 @@ declare class TopoloClient {
         actorEnvelope?: ActorEnvelope;
     }): Promise<T>;
     private executeResolvedAction;
+    private buildVerifiedAgentActorEnvelope;
     /**
      * Introspect the current credential. Returns the caller's resolved identity,
      * organization, and permission set. Used by CLI `whoami` and by MCP to gate
@@ -554,6 +562,15 @@ interface CredentialIntrospection {
         name: string | null;
         role: string;
         permissions: string[];
+        principalId?: string | null;
+        principalType?: 'agent_employee' | 'external_agent' | null;
+        accountableUserId?: string | null;
+        agentInstanceId?: string | null;
+        installationId?: string | null;
+        provider?: string | null;
+        model?: string | null;
+        serviceScopes?: string[];
+        policyRef?: string | null;
     };
     organization: {
         id: string;

package/dist/index.d.ts

@@ -146,6 +146,12 @@ declare function encodeTopoloActionBase64(bytes: Uint8Array): string;
 interface TopoloClientOptions {
     credential: TopoloCredential;
     agent: AgentIdentity;
+    /** Host surface used to attribute actions performed with verified agent credentials. */
+    actorContext?: {
+        channel: ActorChannel;
+        taskId?: string;
+        runId?: string;
+    };
     /** Per-service URL overrides. Useful for staging/dev. */
     serviceUrls?: Record<string, string>;
     /** Explicit environment used to reject cross-environment service and action origins. */
@@ -403,6 +409,7 @@ interface TopoloCatalogSearchOptions {
 declare class TopoloClient {
     private credential;
     private readonly agent;
+    private readonly actorContext?;
     private readonly serviceUrls?;
     private readonly environment?;
     private readonly appIds?;
@@ -534,6 +541,7 @@ declare class TopoloClient {
         actorEnvelope?: ActorEnvelope;
     }): Promise<T>;
     private executeResolvedAction;
+    private buildVerifiedAgentActorEnvelope;
     /**
      * Introspect the current credential. Returns the caller's resolved identity,
      * organization, and permission set. Used by CLI `whoami` and by MCP to gate
@@ -554,6 +562,15 @@ interface CredentialIntrospection {
         name: string | null;
         role: string;
         permissions: string[];
+        principalId?: string | null;
+        principalType?: 'agent_employee' | 'external_agent' | null;
+        accountableUserId?: string | null;
+        agentInstanceId?: string | null;
+        installationId?: string | null;
+        provider?: string | null;
+        model?: string | null;
+        serviceScopes?: string[];
+        policyRef?: string | null;
     };
     organization: {
         id: string;

package/dist/index.js

@@ -1286,6 +1286,7 @@ var NEGATIVE_CACHE_TTL_MS = 60 * 1e3;
 var TopoloClient = class _TopoloClient {
   credential;
   agent;
+  actorContext;
   serviceUrls;
   environment;
   appIds;
@@ -1316,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;
@@ -2031,8 +2037,9 @@ var TopoloClient = class _TopoloClient {
       );
     }
     const mapped = mapActionInput(entry, input);
-    if (options.actorEnvelope) {
-      const actorEnvelope = parseActorEnvelope(options.actorEnvelope);
+    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.");
       }
@@ -2053,7 +2060,7 @@ var TopoloClient = class _TopoloClient {
       ...mapped.query ? { query: mapped.query } : {},
       ...mapped.body !== void 0 ? { body: mapped.body } : {},
       ...options.resource ? { resource: options.resource } : {},
-      ...options.actorEnvelope ? { actorEnvelope: options.actorEnvelope } : {},
+      ...resolvedActorEnvelope ? { actorEnvelope: resolvedActorEnvelope } : {},
       headers: {
         [TOPOLO_ACTION_ID_HEADER]: entry.actionId,
         [TOPOLO_ACTION_NAME_HEADER]: entry.name
@@ -2062,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
@@ -2089,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,
@@ -2454,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;

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@topolo/sdk",
   "packageManager": "pnpm@10.17.1",
-  "version": "0.16.0",
-  "topoloPublishedVersion": "0.16.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",