@vorim/sdk 3.23.0 → 4.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (96) hide show
  1. package/CHANGELOG.md +23 -0
  2. package/dist/index.cjs +212 -14
  3. package/dist/index.cjs.map +1 -1
  4. package/dist/index.d.cts +195 -16
  5. package/dist/index.d.ts +195 -16
  6. package/dist/index.js +211 -14
  7. package/dist/index.js.map +1 -1
  8. package/dist/integrations/anthropic.d.cts +1 -1
  9. package/dist/integrations/anthropic.d.ts +1 -1
  10. package/dist/integrations/ap2.d.cts +1 -1
  11. package/dist/integrations/ap2.d.ts +1 -1
  12. package/dist/integrations/aws-iam.d.cts +1 -1
  13. package/dist/integrations/aws-iam.d.ts +1 -1
  14. package/dist/integrations/bank-rails.d.cts +1 -1
  15. package/dist/integrations/bank-rails.d.ts +1 -1
  16. package/dist/integrations/circle.d.cts +1 -1
  17. package/dist/integrations/circle.d.ts +1 -1
  18. package/dist/integrations/cloudflare.d.cts +1 -1
  19. package/dist/integrations/cloudflare.d.ts +1 -1
  20. package/dist/integrations/coinbase-cdp.d.cts +1 -1
  21. package/dist/integrations/coinbase-cdp.d.ts +1 -1
  22. package/dist/integrations/commerce-agents.d.cts +1 -1
  23. package/dist/integrations/commerce-agents.d.ts +1 -1
  24. package/dist/integrations/crewai.d.cts +1 -1
  25. package/dist/integrations/crewai.d.ts +1 -1
  26. package/dist/integrations/entra.d.cts +1 -1
  27. package/dist/integrations/entra.d.ts +1 -1
  28. package/dist/integrations/fhir.d.cts +1 -1
  29. package/dist/integrations/fhir.d.ts +1 -1
  30. package/dist/integrations/grok.d.cts +1 -1
  31. package/dist/integrations/grok.d.ts +1 -1
  32. package/dist/integrations/guidewire.d.cts +1 -1
  33. package/dist/integrations/guidewire.d.ts +1 -1
  34. package/dist/integrations/hermes.d.cts +1 -1
  35. package/dist/integrations/hermes.d.ts +1 -1
  36. package/dist/integrations/jira.d.cts +1 -1
  37. package/dist/integrations/jira.d.ts +1 -1
  38. package/dist/integrations/langchain.d.cts +1 -1
  39. package/dist/integrations/langchain.d.ts +1 -1
  40. package/dist/integrations/langgraph.d.cts +1 -1
  41. package/dist/integrations/langgraph.d.ts +1 -1
  42. package/dist/integrations/legal.d.cts +1 -1
  43. package/dist/integrations/legal.d.ts +1 -1
  44. package/dist/integrations/life-sciences.d.cts +1 -1
  45. package/dist/integrations/life-sciences.d.ts +1 -1
  46. package/dist/integrations/linear.d.cts +1 -1
  47. package/dist/integrations/linear.d.ts +1 -1
  48. package/dist/integrations/lithic.d.cts +1 -1
  49. package/dist/integrations/lithic.d.ts +1 -1
  50. package/dist/integrations/llamaindex.d.cts +1 -1
  51. package/dist/integrations/llamaindex.d.ts +1 -1
  52. package/dist/integrations/marqeta.d.cts +1 -1
  53. package/dist/integrations/marqeta.d.ts +1 -1
  54. package/dist/integrations/modern-treasury.d.cts +1 -1
  55. package/dist/integrations/modern-treasury.d.ts +1 -1
  56. package/dist/integrations/muse.d.cts +1 -1
  57. package/dist/integrations/muse.d.ts +1 -1
  58. package/dist/integrations/nekuda.d.cts +1 -1
  59. package/dist/integrations/nekuda.d.ts +1 -1
  60. package/dist/integrations/okta.d.cts +1 -1
  61. package/dist/integrations/okta.d.ts +1 -1
  62. package/dist/integrations/openai.d.cts +1 -1
  63. package/dist/integrations/openai.d.ts +1 -1
  64. package/dist/integrations/openrouter.d.cts +1 -1
  65. package/dist/integrations/openrouter.d.ts +1 -1
  66. package/dist/integrations/paypal-agent.d.cts +1 -1
  67. package/dist/integrations/paypal-agent.d.ts +1 -1
  68. package/dist/integrations/perplexity.d.cts +1 -1
  69. package/dist/integrations/perplexity.d.ts +1 -1
  70. package/dist/integrations/plaid.d.cts +1 -1
  71. package/dist/integrations/plaid.d.ts +1 -1
  72. package/dist/integrations/ramp.d.cts +1 -1
  73. package/dist/integrations/ramp.d.ts +1 -1
  74. package/dist/integrations/shopify.d.cts +1 -1
  75. package/dist/integrations/shopify.d.ts +1 -1
  76. package/dist/integrations/siem.d.cts +1 -1
  77. package/dist/integrations/siem.d.ts +1 -1
  78. package/dist/integrations/skyfire.d.cts +1 -1
  79. package/dist/integrations/skyfire.d.ts +1 -1
  80. package/dist/integrations/stripe-acp.d.cts +1 -1
  81. package/dist/integrations/stripe-acp.d.ts +1 -1
  82. package/dist/integrations/stripe-issuing.d.cts +1 -1
  83. package/dist/integrations/stripe-issuing.d.ts +1 -1
  84. package/dist/integrations/truanon.d.cts +1 -1
  85. package/dist/integrations/truanon.d.ts +1 -1
  86. package/dist/integrations/typesafe.d.cts +1 -1
  87. package/dist/integrations/typesafe.d.ts +1 -1
  88. package/dist/integrations/ucp.d.cts +1 -1
  89. package/dist/integrations/ucp.d.ts +1 -1
  90. package/dist/integrations/vercel-ai.d.cts +1 -1
  91. package/dist/integrations/vercel-ai.d.ts +1 -1
  92. package/dist/integrations/x402.d.cts +1 -1
  93. package/dist/integrations/x402.d.ts +1 -1
  94. package/dist/{types-BrDQAJdl.d.cts → types-DphtTyIC.d.cts} +72 -3
  95. package/dist/{types-BrDQAJdl.d.ts → types-DphtTyIC.d.ts} +72 -3
  96. package/package.json +1 -1
package/dist/index.d.cts CHANGED
@@ -1,5 +1,5 @@
1
- import { A as AgentRegistrationResult, R as RuntimeDecision, a as AgentRegistrationInput, T as TrustRecord, b as Agent, P as PermissionScope, c as PermissionCheckResult, D as DelegationLinkClaims, d as AgentDelegationRecord, W as WorkflowProvenanceGraph, C as CapabilityProfile, S as SharedMemoryWriteInput, e as SharedMemoryEntry, f as SharedMemoryListResult, B as BeforeActionInput, g as TokenBudgetInput, h as TokenBudget, i as BudgetSpend, j as AuditEventInput } from './types-BrDQAJdl.cjs';
2
- export { k as AgentStatus, l as ApprovalAttestation, m as AuditEventType, n as AuditResult, o as BudgetEnforcement, p as BudgetScope, q as DecisionVerdict, r as WorkflowGraphEdge, s as WorkflowGraphEvent, t as WorkflowGraphNode } from './types-BrDQAJdl.cjs';
1
+ import { A as AgentRegistrationResult, R as RuntimeDecision, a as AgentRegistrationInput, T as TrustRecord, b as Agent, S as SuspendPreview, P as PermissionScope, c as PermissionCheckResult, D as DelegationLinkClaims, d as AgentDelegationRecord, W as WorkflowProvenanceGraph, C as CapabilityProfile, e as SharedMemoryWriteInput, f as SharedMemoryEntry, g as SharedMemoryListResult, B as BeforeActionInput, h as TokenBudgetInput, i as TokenBudget, j as BudgetSpend, k as AuditEventInput, l as SwarmView } from './types-DphtTyIC.cjs';
2
+ export { m as AgentStatus, n as ApprovalAttestation, o as AuditEventType, p as AuditResult, q as BudgetEnforcement, r as BudgetScope, s as DecisionVerdict, t as WorkflowGraphEdge, u as WorkflowGraphEvent, v as WorkflowGraphNode } from './types-DphtTyIC.cjs';
3
3
  import { PortableSignedReceipt } from '@vorim/shared-types';
4
4
  export { PortableSignedReceipt, portableReceiptCanonicalBytes } from '@vorim/shared-types';
5
5
  import { HttpRequestLike, SignHttpRequestOptions, SignHttpRequestResult } from './httpSignatures.cjs';
@@ -251,11 +251,13 @@ interface VorimConfig {
251
251
  /**
252
252
  * Client-side fail-open behaviour for {@link VorimSDK.beforeAction} when
253
253
  * the runtime decision API itself is unreachable (network error, DNS,
254
- * timeout, or 5xx). Default `true`: a transport failure returns a
255
- * synthetic `fallback` decision (`decision: 'fallback'`, `isFallback:
256
- * true`) so a momentary control-plane outage does not block the agent.
257
- * Set `false` to fail closed — `beforeAction` re-throws the transport
258
- * error and the caller must decide.
254
+ * timeout, or 5xx). Default `false` (since 4.0.0): a transport failure
255
+ * re-throws and the caller must decide, so an outage or a blocked path
256
+ * to Vorim cannot be turned into an allow. Set `true` to fail open — a
257
+ * transport failure then returns a synthetic `fallback` decision
258
+ * (`decision: 'fallback'`, `isFallback: true`) so a momentary
259
+ * control-plane outage does not block the agent. Choose that
260
+ * deliberately, per deployment.
259
261
  *
260
262
  * Note: this governs only transport failures. A reachable server that
261
263
  * returns `deny` still denies regardless of this flag.
@@ -302,6 +304,17 @@ declare function canonicalPayloadV1(event: AuditEventInput): string;
302
304
  * unique handle.
303
305
  */
304
306
  declare function eventDigest(event: AuditEventInput): Promise<string>;
307
+ /**
308
+ * Turn a W3C `traceparent` (00-<trace_id>-<span_id>-<flags>) into the
309
+ * `trace_id` / `span_id` fields Vorim stores. Explicit ids win; a malformed
310
+ * header is dropped rather than sent (the server would 400 on a decision and
311
+ * ignore it on an event). Exported for the OTel helpers.
312
+ */
313
+ declare function foldTraceparent<T extends {
314
+ trace_id?: string;
315
+ span_id?: string;
316
+ traceparent?: string;
317
+ }>(input: T): T;
305
318
  declare class VorimSDK {
306
319
  private apiKey;
307
320
  private baseUrl;
@@ -410,9 +423,30 @@ declare class VorimSDK {
410
423
  meta: any;
411
424
  }>;
412
425
  /**
413
- * Update an agent's metadata.
426
+ * Update an agent's metadata or status.
427
+ *
428
+ * `status: 'suspended'` is the kill switch and, since 4.0.0, cascades to
429
+ * every agent reachable through the agent's active identity delegations
430
+ * unless `cascade: false`. Setting `status: 'active'` on a suspended agent
431
+ * reverses exactly that cascade. The returned agent carries
432
+ * `cascade.suspended` / `cascade.reactivated` with the agent ids touched.
433
+ * See {@link suspendPreview} for the blast radius before acting.
434
+ */
435
+ updateAgent(agentId: string, updates: Partial<Pick<Agent, 'name' | 'description' | 'status' | 'capabilities'>> & {
436
+ cascade?: boolean;
437
+ }): Promise<Agent & {
438
+ cascade?: {
439
+ suspended?: string[];
440
+ reactivated?: string[];
441
+ delegations_revoked?: number;
442
+ };
443
+ }>;
444
+ /**
445
+ * What suspending (or revoking) this agent would touch: its delegation
446
+ * subtree, how many of those agents are still active, open escalations
447
+ * across the subtree, and live delegation links. Writes nothing.
414
448
  */
415
- updateAgent(agentId: string, updates: Partial<Pick<Agent, 'name' | 'description' | 'status' | 'capabilities'>>): Promise<Agent>;
449
+ suspendPreview(agentId: string): Promise<SuspendPreview>;
416
450
  /**
417
451
  * Revoke an agent (permanent deactivation).
418
452
  */
@@ -466,6 +500,13 @@ declare class VorimSDK {
466
500
  scopes_delegated: PermissionScope[];
467
501
  max_chain_depth?: number;
468
502
  valid_until?: string;
503
+ /**
504
+ * The delegate's share of the swarm token budget per window, granted
505
+ * out of the delegator's own share (conservation ledger). The server
506
+ * refuses a share the delegator cannot cover (409 ALLOCATION_EXCEEDED
507
+ * with the numbers). Needs the delegator to be in a swarm with a budget.
508
+ */
509
+ budget_tokens?: number;
469
510
  /**
470
511
  * Optional Ed25519-signed delegation link (VAIP -02 § 5). When
471
512
  * provided, the server verifies the signature against the
@@ -690,9 +731,9 @@ declare class VorimSDK {
690
731
  * poll {@link waitForDecisionResolution} for the human decision.
691
732
  *
692
733
  * Transport failures (network/DNS/timeout/5xx) respect the constructor's
693
- * `runtimeFailOpen` flag: when true (default) a synthetic `fallback`
694
- * decision is returned so a control-plane blip does not block the agent;
695
- * when false the underlying error is re-thrown.
734
+ * `runtimeFailOpen` flag: when false (default) the underlying error is
735
+ * re-thrown; when true a synthetic `fallback` decision is returned so a
736
+ * control-plane blip does not block the agent.
696
737
  *
697
738
  * Always pass the public `agid_*` id as `agentId`.
698
739
  *
@@ -777,9 +818,10 @@ declare class VorimSDK {
777
818
  * row's `decision` column off `'escalate'`. If we returned that verbatim,
778
819
  * a caller's obvious `if (d.decision === 'deny')` check would never fire
779
820
  * on a human DENIAL — a silent fail-open. So when a resolution is present
780
- * we translate the verdict: approved → 'allow', denied → 'deny'. The raw
781
- * resolution is also surfaced as `escalationResolution` for callers that
782
- * want it explicitly.
821
+ * we translate the verdict: approved → 'allow', denied → 'deny', and
822
+ * timed_out (nobody answered within the org's escalation window) → 'deny'.
823
+ * The raw resolution is also surfaced as `escalationResolution` for
824
+ * callers that want it explicitly.
783
825
  *
784
826
  * A missing verdict (malformed/truncated response) fails CLOSED to 'deny'
785
827
  * rather than 'fallback', so the deny check fires on garbled input.
@@ -911,7 +953,144 @@ declare class VorimSDK {
911
953
  capabilities: string[];
912
954
  scopes: string[];
913
955
  ttl_seconds?: number;
956
+ /**
957
+ * The agent this worker is spawned for. The worker joins the parent's
958
+ * swarm (minted on the parent if it has none), so swarm budgets,
959
+ * behaviour windows and cascading suspend cover it.
960
+ */
961
+ parent_agent_id?: string;
962
+ /**
963
+ * The worker's share of the swarm token budget per window, granted out
964
+ * of the parent's own share (conservation ledger). Needs parent_agent_id
965
+ * and a swarm budget; refused when the parent cannot cover it.
966
+ */
967
+ budget_tokens?: number;
914
968
  }): Promise<any>;
969
+ /**
970
+ * The server-minted swarm an agent belongs to and every member of it.
971
+ * `{ swarm_id: null, members: [] }` for a standalone agent.
972
+ */
973
+ getSwarm(agentId: string): Promise<SwarmView>;
974
+ /**
975
+ * Register up to 50 agents in one call: an explicit list, or a template
976
+ * repeated `count` times (names `<prefix>-1` .. `<prefix>-N`), optionally
977
+ * grouped into a new swarm (`swarm: { name?, root? }`; the first created
978
+ * agent roots it when `root` is absent). Each created agent's private key
979
+ * is cached, like `register()`, so the SDK can sign for it at once. The
980
+ * plan allowance is checked for the whole batch first; a single failure is
981
+ * listed in `failed`, not thrown.
982
+ */
983
+ registerMany(input: {
984
+ agents?: Array<{
985
+ name: string;
986
+ description?: string;
987
+ capabilities?: string[];
988
+ scopes: string[];
989
+ }>;
990
+ template?: {
991
+ name_prefix: string;
992
+ description?: string;
993
+ capabilities?: string[];
994
+ scopes: string[];
995
+ };
996
+ count?: number;
997
+ swarm?: {
998
+ name?: string;
999
+ root?: string;
1000
+ };
1001
+ }): Promise<{
1002
+ created: any[];
1003
+ failed: Array<{
1004
+ name: string;
1005
+ error: string;
1006
+ }>;
1007
+ swarm: {
1008
+ swarm_id: string;
1009
+ name: string | null;
1010
+ root_agent_id: string;
1011
+ } | null;
1012
+ }>;
1013
+ /**
1014
+ * Create or update a swarm from a spec: root, members and who they report
1015
+ * to, guardians, charter, budget and shares, breakers, tripwires. Pass the
1016
+ * YAML or JSON text, or the parsed object. `dryRun` returns the plan
1017
+ * without writing. Needs an org key with `runtime:manage`.
1018
+ */
1019
+ applySwarmSpec(spec: string | Record<string, unknown>, opts?: {
1020
+ dryRun?: boolean;
1021
+ }): Promise<any>;
1022
+ /**
1023
+ * Rehearse a swarm: every active member against a scenario set, through
1024
+ * the real decision pipeline with nothing written, signed with the roster,
1025
+ * charter, budget and policy version it ran under. `preset: 'hazards'`
1026
+ * (default) runs generic side tasks plus one main task; `'replay'` re-judges
1027
+ * the swarm's last 100 decisions; `scenarios` runs your own (each with
1028
+ * `expect: 'allow' | 'not_allow' | 'deny' | 'escalate'`). Verdict is pass,
1029
+ * pass_with_findings or fail. Needs `runtime:manage`.
1030
+ */
1031
+ rehearseSwarm(swarmId: string, input?: {
1032
+ preset?: 'hazards' | 'replay';
1033
+ scenarios?: Array<Record<string, unknown>>;
1034
+ label?: string;
1035
+ }): Promise<any>;
1036
+ /** Past rehearsals, newest first (summary only; fetch `/swarms/:id/rehearsals/:rid` for the signed payload). */
1037
+ listSwarmRehearsals(swarmId: string): Promise<any[]>;
1038
+ /**
1039
+ * A swarm's trust: `min` (gate on it: the least trusted active member),
1040
+ * `weighted_mean` (display, weighted by recent activity), `trimmed_mean`
1041
+ * (for anything derived from peer reports), per member.
1042
+ */
1043
+ getSwarmScore(swarmId: string): Promise<any>;
1044
+ /**
1045
+ * Issue a platform-signed attestation of the swarm as it is now: roster
1046
+ * and its hash, policy version and rules hash, charter, budget, kills,
1047
+ * latest rehearsal, receipt chain head and the three scores. Valid 24 h.
1048
+ * Hand it to a counterparty; they verify it against GET /trust/keys.
1049
+ */
1050
+ attestSwarm(swarmId: string): Promise<any>;
1051
+ /** Past attestations, newest first (fetch one by id for the signed payload). */
1052
+ listSwarmAttestations(swarmId: string): Promise<any[]>;
1053
+ /** A swarm as it is now, as a spec: `{ spec, yaml }`. Keep the YAML in git and apply it again. */
1054
+ getSwarmSpec(swarmId: string): Promise<{
1055
+ spec: Record<string, unknown>;
1056
+ yaml: string;
1057
+ }>;
1058
+ /**
1059
+ * A swarm's attention picture: escalations in the last hour against its
1060
+ * budget, the rate to expect, median time to resolve, mean time between
1061
+ * interventions, and the fan-out estimate after Olsen and Goodrich (how
1062
+ * many swarms like this one person could supervise).
1063
+ */
1064
+ getSwarmAttention(swarmId: string): Promise<any>;
1065
+ /**
1066
+ * Set the swarm's attention budget: `perHour` escalations per rolling hour
1067
+ * a person may be asked to read (null = no budget). Past it `onExceed`
1068
+ * decides: 'deny' (the escalation is denied unread, the default) or
1069
+ * 'suspend' (the whole swarm stops). Returns the swarm detail.
1070
+ */
1071
+ setSwarmAttention(swarmId: string, input: {
1072
+ perHour?: number | null;
1073
+ onExceed?: 'deny' | 'suspend';
1074
+ }): Promise<any>;
1075
+ /**
1076
+ * Attributes for the agent's own spans: the OTel GenAI `gen_ai.agent.id`
1077
+ * plus Vorim's swarm and parent-agent ids (the conventions have no field
1078
+ * for either), so any OTel backend can group a swarm's spans. Cached for
1079
+ * 60 seconds per agent. Pass the active span's trace/span id back to
1080
+ * `beforeAction` / `emit` and Vorim's OTLP connector parents its spans
1081
+ * under yours.
1082
+ */
1083
+ otelAttributes(agentId: string): Promise<Record<string, string>>;
1084
+ private otelCache;
1085
+ /** Pending escalations this guardian may judge (empty for a non-guardian). */
1086
+ listGuardianEscalations(agentId: string): Promise<any[]>;
1087
+ /**
1088
+ * Approve or veto an escalation as a guardian. Needs the agent's private
1089
+ * key (loaded by register(), registerEphemeral() or useAgentKey()). A
1090
+ * quorum rule returns `{ status: 'partial', approvals, required_approvals }`
1091
+ * until enough distinct approvals arrive; one veto denies at once.
1092
+ */
1093
+ guardianResolve(agentId: string, decisionId: string, resolution: 'approved' | 'denied'): Promise<any>;
915
1094
  /**
916
1095
  * Register an OAuth provider for credential delegation.
917
1096
  */
@@ -1121,4 +1300,4 @@ interface DeviceLoginResult {
1121
1300
  */
1122
1301
  declare function deviceLogin(opts: DeviceLoginOptions): Promise<DeviceLoginResult>;
1123
1302
 
1124
- export { Agent, AgentDelegationRecord, AgentRegistrationInput, AgentRegistrationResult, AuditEventInput, BeforeActionInput, BudgetSpend, CANONICAL_TOOL_CATALOGUE_VERSION, type CatalogueTool, type CommitmentKey, DelegationLinkClaims, type DeviceLoginOptions, type DeviceLoginResult, HMAC_SHA256_PREFIX, HttpRequestLike, type HttpSignatureVerification, PermissionCheckResult, PermissionScope, type ReplayContext, type ReplayInputs, RuntimeDecision, SHA256_PREFIX, SharedMemoryEntry, SharedMemoryListResult, SharedMemoryWriteInput, SignHttpRequestOptions, SignHttpRequestResult, TokenBudget, TokenBudgetInput, TrustRecord, type VorimConfig, VorimDeniedError, VorimError, VorimSDK, WorkflowProvenanceGraph, canonicalPayloadV0, canonicalPayloadV1, commitPayload, createVorim as default, deviceLogin, eventDigest, hashPayload, hashPreviousEvent, hashSystemPrompt, hashTool, hashToolCatalogue, isDigest, isKeyedCommitment, jcsCanonicalise, prepareReplayContext };
1303
+ export { Agent, AgentDelegationRecord, AgentRegistrationInput, AgentRegistrationResult, AuditEventInput, BeforeActionInput, BudgetSpend, CANONICAL_TOOL_CATALOGUE_VERSION, type CatalogueTool, type CommitmentKey, DelegationLinkClaims, type DeviceLoginOptions, type DeviceLoginResult, HMAC_SHA256_PREFIX, HttpRequestLike, type HttpSignatureVerification, PermissionCheckResult, PermissionScope, type ReplayContext, type ReplayInputs, RuntimeDecision, SHA256_PREFIX, SharedMemoryEntry, SharedMemoryListResult, SharedMemoryWriteInput, SignHttpRequestOptions, SignHttpRequestResult, SuspendPreview, SwarmView, TokenBudget, TokenBudgetInput, TrustRecord, type VorimConfig, VorimDeniedError, VorimError, VorimSDK, WorkflowProvenanceGraph, canonicalPayloadV0, canonicalPayloadV1, commitPayload, createVorim as default, deviceLogin, eventDigest, foldTraceparent, hashPayload, hashPreviousEvent, hashSystemPrompt, hashTool, hashToolCatalogue, isDigest, isKeyedCommitment, jcsCanonicalise, prepareReplayContext };
package/dist/index.d.ts CHANGED
@@ -1,5 +1,5 @@
1
- import { A as AgentRegistrationResult, R as RuntimeDecision, a as AgentRegistrationInput, T as TrustRecord, b as Agent, P as PermissionScope, c as PermissionCheckResult, D as DelegationLinkClaims, d as AgentDelegationRecord, W as WorkflowProvenanceGraph, C as CapabilityProfile, S as SharedMemoryWriteInput, e as SharedMemoryEntry, f as SharedMemoryListResult, B as BeforeActionInput, g as TokenBudgetInput, h as TokenBudget, i as BudgetSpend, j as AuditEventInput } from './types-BrDQAJdl.js';
2
- export { k as AgentStatus, l as ApprovalAttestation, m as AuditEventType, n as AuditResult, o as BudgetEnforcement, p as BudgetScope, q as DecisionVerdict, r as WorkflowGraphEdge, s as WorkflowGraphEvent, t as WorkflowGraphNode } from './types-BrDQAJdl.js';
1
+ import { A as AgentRegistrationResult, R as RuntimeDecision, a as AgentRegistrationInput, T as TrustRecord, b as Agent, S as SuspendPreview, P as PermissionScope, c as PermissionCheckResult, D as DelegationLinkClaims, d as AgentDelegationRecord, W as WorkflowProvenanceGraph, C as CapabilityProfile, e as SharedMemoryWriteInput, f as SharedMemoryEntry, g as SharedMemoryListResult, B as BeforeActionInput, h as TokenBudgetInput, i as TokenBudget, j as BudgetSpend, k as AuditEventInput, l as SwarmView } from './types-DphtTyIC.js';
2
+ export { m as AgentStatus, n as ApprovalAttestation, o as AuditEventType, p as AuditResult, q as BudgetEnforcement, r as BudgetScope, s as DecisionVerdict, t as WorkflowGraphEdge, u as WorkflowGraphEvent, v as WorkflowGraphNode } from './types-DphtTyIC.js';
3
3
  import { PortableSignedReceipt } from '@vorim/shared-types';
4
4
  export { PortableSignedReceipt, portableReceiptCanonicalBytes } from '@vorim/shared-types';
5
5
  import { HttpRequestLike, SignHttpRequestOptions, SignHttpRequestResult } from './httpSignatures.js';
@@ -251,11 +251,13 @@ interface VorimConfig {
251
251
  /**
252
252
  * Client-side fail-open behaviour for {@link VorimSDK.beforeAction} when
253
253
  * the runtime decision API itself is unreachable (network error, DNS,
254
- * timeout, or 5xx). Default `true`: a transport failure returns a
255
- * synthetic `fallback` decision (`decision: 'fallback'`, `isFallback:
256
- * true`) so a momentary control-plane outage does not block the agent.
257
- * Set `false` to fail closed — `beforeAction` re-throws the transport
258
- * error and the caller must decide.
254
+ * timeout, or 5xx). Default `false` (since 4.0.0): a transport failure
255
+ * re-throws and the caller must decide, so an outage or a blocked path
256
+ * to Vorim cannot be turned into an allow. Set `true` to fail open — a
257
+ * transport failure then returns a synthetic `fallback` decision
258
+ * (`decision: 'fallback'`, `isFallback: true`) so a momentary
259
+ * control-plane outage does not block the agent. Choose that
260
+ * deliberately, per deployment.
259
261
  *
260
262
  * Note: this governs only transport failures. A reachable server that
261
263
  * returns `deny` still denies regardless of this flag.
@@ -302,6 +304,17 @@ declare function canonicalPayloadV1(event: AuditEventInput): string;
302
304
  * unique handle.
303
305
  */
304
306
  declare function eventDigest(event: AuditEventInput): Promise<string>;
307
+ /**
308
+ * Turn a W3C `traceparent` (00-<trace_id>-<span_id>-<flags>) into the
309
+ * `trace_id` / `span_id` fields Vorim stores. Explicit ids win; a malformed
310
+ * header is dropped rather than sent (the server would 400 on a decision and
311
+ * ignore it on an event). Exported for the OTel helpers.
312
+ */
313
+ declare function foldTraceparent<T extends {
314
+ trace_id?: string;
315
+ span_id?: string;
316
+ traceparent?: string;
317
+ }>(input: T): T;
305
318
  declare class VorimSDK {
306
319
  private apiKey;
307
320
  private baseUrl;
@@ -410,9 +423,30 @@ declare class VorimSDK {
410
423
  meta: any;
411
424
  }>;
412
425
  /**
413
- * Update an agent's metadata.
426
+ * Update an agent's metadata or status.
427
+ *
428
+ * `status: 'suspended'` is the kill switch and, since 4.0.0, cascades to
429
+ * every agent reachable through the agent's active identity delegations
430
+ * unless `cascade: false`. Setting `status: 'active'` on a suspended agent
431
+ * reverses exactly that cascade. The returned agent carries
432
+ * `cascade.suspended` / `cascade.reactivated` with the agent ids touched.
433
+ * See {@link suspendPreview} for the blast radius before acting.
434
+ */
435
+ updateAgent(agentId: string, updates: Partial<Pick<Agent, 'name' | 'description' | 'status' | 'capabilities'>> & {
436
+ cascade?: boolean;
437
+ }): Promise<Agent & {
438
+ cascade?: {
439
+ suspended?: string[];
440
+ reactivated?: string[];
441
+ delegations_revoked?: number;
442
+ };
443
+ }>;
444
+ /**
445
+ * What suspending (or revoking) this agent would touch: its delegation
446
+ * subtree, how many of those agents are still active, open escalations
447
+ * across the subtree, and live delegation links. Writes nothing.
414
448
  */
415
- updateAgent(agentId: string, updates: Partial<Pick<Agent, 'name' | 'description' | 'status' | 'capabilities'>>): Promise<Agent>;
449
+ suspendPreview(agentId: string): Promise<SuspendPreview>;
416
450
  /**
417
451
  * Revoke an agent (permanent deactivation).
418
452
  */
@@ -466,6 +500,13 @@ declare class VorimSDK {
466
500
  scopes_delegated: PermissionScope[];
467
501
  max_chain_depth?: number;
468
502
  valid_until?: string;
503
+ /**
504
+ * The delegate's share of the swarm token budget per window, granted
505
+ * out of the delegator's own share (conservation ledger). The server
506
+ * refuses a share the delegator cannot cover (409 ALLOCATION_EXCEEDED
507
+ * with the numbers). Needs the delegator to be in a swarm with a budget.
508
+ */
509
+ budget_tokens?: number;
469
510
  /**
470
511
  * Optional Ed25519-signed delegation link (VAIP -02 § 5). When
471
512
  * provided, the server verifies the signature against the
@@ -690,9 +731,9 @@ declare class VorimSDK {
690
731
  * poll {@link waitForDecisionResolution} for the human decision.
691
732
  *
692
733
  * Transport failures (network/DNS/timeout/5xx) respect the constructor's
693
- * `runtimeFailOpen` flag: when true (default) a synthetic `fallback`
694
- * decision is returned so a control-plane blip does not block the agent;
695
- * when false the underlying error is re-thrown.
734
+ * `runtimeFailOpen` flag: when false (default) the underlying error is
735
+ * re-thrown; when true a synthetic `fallback` decision is returned so a
736
+ * control-plane blip does not block the agent.
696
737
  *
697
738
  * Always pass the public `agid_*` id as `agentId`.
698
739
  *
@@ -777,9 +818,10 @@ declare class VorimSDK {
777
818
  * row's `decision` column off `'escalate'`. If we returned that verbatim,
778
819
  * a caller's obvious `if (d.decision === 'deny')` check would never fire
779
820
  * on a human DENIAL — a silent fail-open. So when a resolution is present
780
- * we translate the verdict: approved → 'allow', denied → 'deny'. The raw
781
- * resolution is also surfaced as `escalationResolution` for callers that
782
- * want it explicitly.
821
+ * we translate the verdict: approved → 'allow', denied → 'deny', and
822
+ * timed_out (nobody answered within the org's escalation window) → 'deny'.
823
+ * The raw resolution is also surfaced as `escalationResolution` for
824
+ * callers that want it explicitly.
783
825
  *
784
826
  * A missing verdict (malformed/truncated response) fails CLOSED to 'deny'
785
827
  * rather than 'fallback', so the deny check fires on garbled input.
@@ -911,7 +953,144 @@ declare class VorimSDK {
911
953
  capabilities: string[];
912
954
  scopes: string[];
913
955
  ttl_seconds?: number;
956
+ /**
957
+ * The agent this worker is spawned for. The worker joins the parent's
958
+ * swarm (minted on the parent if it has none), so swarm budgets,
959
+ * behaviour windows and cascading suspend cover it.
960
+ */
961
+ parent_agent_id?: string;
962
+ /**
963
+ * The worker's share of the swarm token budget per window, granted out
964
+ * of the parent's own share (conservation ledger). Needs parent_agent_id
965
+ * and a swarm budget; refused when the parent cannot cover it.
966
+ */
967
+ budget_tokens?: number;
914
968
  }): Promise<any>;
969
+ /**
970
+ * The server-minted swarm an agent belongs to and every member of it.
971
+ * `{ swarm_id: null, members: [] }` for a standalone agent.
972
+ */
973
+ getSwarm(agentId: string): Promise<SwarmView>;
974
+ /**
975
+ * Register up to 50 agents in one call: an explicit list, or a template
976
+ * repeated `count` times (names `<prefix>-1` .. `<prefix>-N`), optionally
977
+ * grouped into a new swarm (`swarm: { name?, root? }`; the first created
978
+ * agent roots it when `root` is absent). Each created agent's private key
979
+ * is cached, like `register()`, so the SDK can sign for it at once. The
980
+ * plan allowance is checked for the whole batch first; a single failure is
981
+ * listed in `failed`, not thrown.
982
+ */
983
+ registerMany(input: {
984
+ agents?: Array<{
985
+ name: string;
986
+ description?: string;
987
+ capabilities?: string[];
988
+ scopes: string[];
989
+ }>;
990
+ template?: {
991
+ name_prefix: string;
992
+ description?: string;
993
+ capabilities?: string[];
994
+ scopes: string[];
995
+ };
996
+ count?: number;
997
+ swarm?: {
998
+ name?: string;
999
+ root?: string;
1000
+ };
1001
+ }): Promise<{
1002
+ created: any[];
1003
+ failed: Array<{
1004
+ name: string;
1005
+ error: string;
1006
+ }>;
1007
+ swarm: {
1008
+ swarm_id: string;
1009
+ name: string | null;
1010
+ root_agent_id: string;
1011
+ } | null;
1012
+ }>;
1013
+ /**
1014
+ * Create or update a swarm from a spec: root, members and who they report
1015
+ * to, guardians, charter, budget and shares, breakers, tripwires. Pass the
1016
+ * YAML or JSON text, or the parsed object. `dryRun` returns the plan
1017
+ * without writing. Needs an org key with `runtime:manage`.
1018
+ */
1019
+ applySwarmSpec(spec: string | Record<string, unknown>, opts?: {
1020
+ dryRun?: boolean;
1021
+ }): Promise<any>;
1022
+ /**
1023
+ * Rehearse a swarm: every active member against a scenario set, through
1024
+ * the real decision pipeline with nothing written, signed with the roster,
1025
+ * charter, budget and policy version it ran under. `preset: 'hazards'`
1026
+ * (default) runs generic side tasks plus one main task; `'replay'` re-judges
1027
+ * the swarm's last 100 decisions; `scenarios` runs your own (each with
1028
+ * `expect: 'allow' | 'not_allow' | 'deny' | 'escalate'`). Verdict is pass,
1029
+ * pass_with_findings or fail. Needs `runtime:manage`.
1030
+ */
1031
+ rehearseSwarm(swarmId: string, input?: {
1032
+ preset?: 'hazards' | 'replay';
1033
+ scenarios?: Array<Record<string, unknown>>;
1034
+ label?: string;
1035
+ }): Promise<any>;
1036
+ /** Past rehearsals, newest first (summary only; fetch `/swarms/:id/rehearsals/:rid` for the signed payload). */
1037
+ listSwarmRehearsals(swarmId: string): Promise<any[]>;
1038
+ /**
1039
+ * A swarm's trust: `min` (gate on it: the least trusted active member),
1040
+ * `weighted_mean` (display, weighted by recent activity), `trimmed_mean`
1041
+ * (for anything derived from peer reports), per member.
1042
+ */
1043
+ getSwarmScore(swarmId: string): Promise<any>;
1044
+ /**
1045
+ * Issue a platform-signed attestation of the swarm as it is now: roster
1046
+ * and its hash, policy version and rules hash, charter, budget, kills,
1047
+ * latest rehearsal, receipt chain head and the three scores. Valid 24 h.
1048
+ * Hand it to a counterparty; they verify it against GET /trust/keys.
1049
+ */
1050
+ attestSwarm(swarmId: string): Promise<any>;
1051
+ /** Past attestations, newest first (fetch one by id for the signed payload). */
1052
+ listSwarmAttestations(swarmId: string): Promise<any[]>;
1053
+ /** A swarm as it is now, as a spec: `{ spec, yaml }`. Keep the YAML in git and apply it again. */
1054
+ getSwarmSpec(swarmId: string): Promise<{
1055
+ spec: Record<string, unknown>;
1056
+ yaml: string;
1057
+ }>;
1058
+ /**
1059
+ * A swarm's attention picture: escalations in the last hour against its
1060
+ * budget, the rate to expect, median time to resolve, mean time between
1061
+ * interventions, and the fan-out estimate after Olsen and Goodrich (how
1062
+ * many swarms like this one person could supervise).
1063
+ */
1064
+ getSwarmAttention(swarmId: string): Promise<any>;
1065
+ /**
1066
+ * Set the swarm's attention budget: `perHour` escalations per rolling hour
1067
+ * a person may be asked to read (null = no budget). Past it `onExceed`
1068
+ * decides: 'deny' (the escalation is denied unread, the default) or
1069
+ * 'suspend' (the whole swarm stops). Returns the swarm detail.
1070
+ */
1071
+ setSwarmAttention(swarmId: string, input: {
1072
+ perHour?: number | null;
1073
+ onExceed?: 'deny' | 'suspend';
1074
+ }): Promise<any>;
1075
+ /**
1076
+ * Attributes for the agent's own spans: the OTel GenAI `gen_ai.agent.id`
1077
+ * plus Vorim's swarm and parent-agent ids (the conventions have no field
1078
+ * for either), so any OTel backend can group a swarm's spans. Cached for
1079
+ * 60 seconds per agent. Pass the active span's trace/span id back to
1080
+ * `beforeAction` / `emit` and Vorim's OTLP connector parents its spans
1081
+ * under yours.
1082
+ */
1083
+ otelAttributes(agentId: string): Promise<Record<string, string>>;
1084
+ private otelCache;
1085
+ /** Pending escalations this guardian may judge (empty for a non-guardian). */
1086
+ listGuardianEscalations(agentId: string): Promise<any[]>;
1087
+ /**
1088
+ * Approve or veto an escalation as a guardian. Needs the agent's private
1089
+ * key (loaded by register(), registerEphemeral() or useAgentKey()). A
1090
+ * quorum rule returns `{ status: 'partial', approvals, required_approvals }`
1091
+ * until enough distinct approvals arrive; one veto denies at once.
1092
+ */
1093
+ guardianResolve(agentId: string, decisionId: string, resolution: 'approved' | 'denied'): Promise<any>;
915
1094
  /**
916
1095
  * Register an OAuth provider for credential delegation.
917
1096
  */
@@ -1121,4 +1300,4 @@ interface DeviceLoginResult {
1121
1300
  */
1122
1301
  declare function deviceLogin(opts: DeviceLoginOptions): Promise<DeviceLoginResult>;
1123
1302
 
1124
- export { Agent, AgentDelegationRecord, AgentRegistrationInput, AgentRegistrationResult, AuditEventInput, BeforeActionInput, BudgetSpend, CANONICAL_TOOL_CATALOGUE_VERSION, type CatalogueTool, type CommitmentKey, DelegationLinkClaims, type DeviceLoginOptions, type DeviceLoginResult, HMAC_SHA256_PREFIX, HttpRequestLike, type HttpSignatureVerification, PermissionCheckResult, PermissionScope, type ReplayContext, type ReplayInputs, RuntimeDecision, SHA256_PREFIX, SharedMemoryEntry, SharedMemoryListResult, SharedMemoryWriteInput, SignHttpRequestOptions, SignHttpRequestResult, TokenBudget, TokenBudgetInput, TrustRecord, type VorimConfig, VorimDeniedError, VorimError, VorimSDK, WorkflowProvenanceGraph, canonicalPayloadV0, canonicalPayloadV1, commitPayload, createVorim as default, deviceLogin, eventDigest, hashPayload, hashPreviousEvent, hashSystemPrompt, hashTool, hashToolCatalogue, isDigest, isKeyedCommitment, jcsCanonicalise, prepareReplayContext };
1303
+ export { Agent, AgentDelegationRecord, AgentRegistrationInput, AgentRegistrationResult, AuditEventInput, BeforeActionInput, BudgetSpend, CANONICAL_TOOL_CATALOGUE_VERSION, type CatalogueTool, type CommitmentKey, DelegationLinkClaims, type DeviceLoginOptions, type DeviceLoginResult, HMAC_SHA256_PREFIX, HttpRequestLike, type HttpSignatureVerification, PermissionCheckResult, PermissionScope, type ReplayContext, type ReplayInputs, RuntimeDecision, SHA256_PREFIX, SharedMemoryEntry, SharedMemoryListResult, SharedMemoryWriteInput, SignHttpRequestOptions, SignHttpRequestResult, SuspendPreview, SwarmView, TokenBudget, TokenBudgetInput, TrustRecord, type VorimConfig, VorimDeniedError, VorimError, VorimSDK, WorkflowProvenanceGraph, canonicalPayloadV0, canonicalPayloadV1, commitPayload, createVorim as default, deviceLogin, eventDigest, foldTraceparent, hashPayload, hashPreviousEvent, hashSystemPrompt, hashTool, hashToolCatalogue, isDigest, isKeyedCommitment, jcsCanonicalise, prepareReplayContext };