@vorim/sdk 3.23.0 → 4.1.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 (152) hide show
  1. package/CHANGELOG.md +30 -0
  2. package/dist/_commerce-core-Dyr_dHVP.d.ts +156 -0
  3. package/dist/_commerce-core-wY2jC6rC.d.cts +156 -0
  4. package/dist/index.cjs +217 -14
  5. package/dist/index.cjs.map +1 -1
  6. package/dist/index.d.cts +200 -16
  7. package/dist/index.d.ts +200 -16
  8. package/dist/index.js +216 -14
  9. package/dist/index.js.map +1 -1
  10. package/dist/integrations/amazon.cjs +357 -0
  11. package/dist/integrations/amazon.cjs.map +1 -0
  12. package/dist/integrations/amazon.d.cts +88 -0
  13. package/dist/integrations/amazon.d.ts +88 -0
  14. package/dist/integrations/amazon.js +328 -0
  15. package/dist/integrations/amazon.js.map +1 -0
  16. package/dist/integrations/anthropic.d.cts +1 -1
  17. package/dist/integrations/anthropic.d.ts +1 -1
  18. package/dist/integrations/ap2.d.cts +1 -1
  19. package/dist/integrations/ap2.d.ts +1 -1
  20. package/dist/integrations/aws-iam.d.cts +1 -1
  21. package/dist/integrations/aws-iam.d.ts +1 -1
  22. package/dist/integrations/bank-rails.d.cts +1 -1
  23. package/dist/integrations/bank-rails.d.ts +1 -1
  24. package/dist/integrations/circle.d.cts +1 -1
  25. package/dist/integrations/circle.d.ts +1 -1
  26. package/dist/integrations/cloudflare.d.cts +1 -1
  27. package/dist/integrations/cloudflare.d.ts +1 -1
  28. package/dist/integrations/coinbase-cdp.d.cts +1 -1
  29. package/dist/integrations/coinbase-cdp.d.ts +1 -1
  30. package/dist/integrations/commerce-agents.d.cts +1 -1
  31. package/dist/integrations/commerce-agents.d.ts +1 -1
  32. package/dist/integrations/crewai.d.cts +1 -1
  33. package/dist/integrations/crewai.d.ts +1 -1
  34. package/dist/integrations/delivery.cjs +327 -0
  35. package/dist/integrations/delivery.cjs.map +1 -0
  36. package/dist/integrations/delivery.d.cts +33 -0
  37. package/dist/integrations/delivery.d.ts +33 -0
  38. package/dist/integrations/delivery.js +296 -0
  39. package/dist/integrations/delivery.js.map +1 -0
  40. package/dist/integrations/ebay.cjs +350 -0
  41. package/dist/integrations/ebay.cjs.map +1 -0
  42. package/dist/integrations/ebay.d.cts +73 -0
  43. package/dist/integrations/ebay.d.ts +73 -0
  44. package/dist/integrations/ebay.js +321 -0
  45. package/dist/integrations/ebay.js.map +1 -0
  46. package/dist/integrations/entra.d.cts +1 -1
  47. package/dist/integrations/entra.d.ts +1 -1
  48. package/dist/integrations/etsy.cjs +330 -0
  49. package/dist/integrations/etsy.cjs.map +1 -0
  50. package/dist/integrations/etsy.d.cts +41 -0
  51. package/dist/integrations/etsy.d.ts +41 -0
  52. package/dist/integrations/etsy.js +301 -0
  53. package/dist/integrations/etsy.js.map +1 -0
  54. package/dist/integrations/fhir.d.cts +1 -1
  55. package/dist/integrations/fhir.d.ts +1 -1
  56. package/dist/integrations/google-merchant.cjs +332 -0
  57. package/dist/integrations/google-merchant.cjs.map +1 -0
  58. package/dist/integrations/google-merchant.d.cts +43 -0
  59. package/dist/integrations/google-merchant.d.ts +43 -0
  60. package/dist/integrations/google-merchant.js +303 -0
  61. package/dist/integrations/google-merchant.js.map +1 -0
  62. package/dist/integrations/grok.d.cts +1 -1
  63. package/dist/integrations/grok.d.ts +1 -1
  64. package/dist/integrations/guidewire.d.cts +1 -1
  65. package/dist/integrations/guidewire.d.ts +1 -1
  66. package/dist/integrations/hermes.d.cts +1 -1
  67. package/dist/integrations/hermes.d.ts +1 -1
  68. package/dist/integrations/jira.d.cts +1 -1
  69. package/dist/integrations/jira.d.ts +1 -1
  70. package/dist/integrations/langchain.d.cts +1 -1
  71. package/dist/integrations/langchain.d.ts +1 -1
  72. package/dist/integrations/langgraph.d.cts +1 -1
  73. package/dist/integrations/langgraph.d.ts +1 -1
  74. package/dist/integrations/legal.d.cts +1 -1
  75. package/dist/integrations/legal.d.ts +1 -1
  76. package/dist/integrations/life-sciences.d.cts +1 -1
  77. package/dist/integrations/life-sciences.d.ts +1 -1
  78. package/dist/integrations/linear.d.cts +1 -1
  79. package/dist/integrations/linear.d.ts +1 -1
  80. package/dist/integrations/lithic.d.cts +1 -1
  81. package/dist/integrations/lithic.d.ts +1 -1
  82. package/dist/integrations/llamaindex.d.cts +1 -1
  83. package/dist/integrations/llamaindex.d.ts +1 -1
  84. package/dist/integrations/marqeta.d.cts +1 -1
  85. package/dist/integrations/marqeta.d.ts +1 -1
  86. package/dist/integrations/meta.cjs +375 -0
  87. package/dist/integrations/meta.cjs.map +1 -0
  88. package/dist/integrations/meta.d.cts +83 -0
  89. package/dist/integrations/meta.d.ts +83 -0
  90. package/dist/integrations/meta.js +346 -0
  91. package/dist/integrations/meta.js.map +1 -0
  92. package/dist/integrations/modern-treasury.d.cts +1 -1
  93. package/dist/integrations/modern-treasury.d.ts +1 -1
  94. package/dist/integrations/muse.d.cts +1 -1
  95. package/dist/integrations/muse.d.ts +1 -1
  96. package/dist/integrations/nekuda.d.cts +1 -1
  97. package/dist/integrations/nekuda.d.ts +1 -1
  98. package/dist/integrations/okta.d.cts +1 -1
  99. package/dist/integrations/okta.d.ts +1 -1
  100. package/dist/integrations/openai.d.cts +1 -1
  101. package/dist/integrations/openai.d.ts +1 -1
  102. package/dist/integrations/openrouter.d.cts +1 -1
  103. package/dist/integrations/openrouter.d.ts +1 -1
  104. package/dist/integrations/paypal-agent.d.cts +1 -1
  105. package/dist/integrations/paypal-agent.d.ts +1 -1
  106. package/dist/integrations/perplexity.d.cts +1 -1
  107. package/dist/integrations/perplexity.d.ts +1 -1
  108. package/dist/integrations/plaid.d.cts +1 -1
  109. package/dist/integrations/plaid.d.ts +1 -1
  110. package/dist/integrations/ramp.d.cts +1 -1
  111. package/dist/integrations/ramp.d.ts +1 -1
  112. package/dist/integrations/shopify.d.cts +1 -1
  113. package/dist/integrations/shopify.d.ts +1 -1
  114. package/dist/integrations/siem.d.cts +1 -1
  115. package/dist/integrations/siem.d.ts +1 -1
  116. package/dist/integrations/skyfire.d.cts +1 -1
  117. package/dist/integrations/skyfire.d.ts +1 -1
  118. package/dist/integrations/social-ads.cjs +328 -0
  119. package/dist/integrations/social-ads.cjs.map +1 -0
  120. package/dist/integrations/social-ads.d.cts +36 -0
  121. package/dist/integrations/social-ads.d.ts +36 -0
  122. package/dist/integrations/social-ads.js +297 -0
  123. package/dist/integrations/social-ads.js.map +1 -0
  124. package/dist/integrations/stripe-acp.d.cts +1 -1
  125. package/dist/integrations/stripe-acp.d.ts +1 -1
  126. package/dist/integrations/stripe-issuing.d.cts +1 -1
  127. package/dist/integrations/stripe-issuing.d.ts +1 -1
  128. package/dist/integrations/tiktok-shop.cjs +334 -0
  129. package/dist/integrations/tiktok-shop.cjs.map +1 -0
  130. package/dist/integrations/tiktok-shop.d.cts +44 -0
  131. package/dist/integrations/tiktok-shop.d.ts +44 -0
  132. package/dist/integrations/tiktok-shop.js +305 -0
  133. package/dist/integrations/tiktok-shop.js.map +1 -0
  134. package/dist/integrations/truanon.d.cts +1 -1
  135. package/dist/integrations/truanon.d.ts +1 -1
  136. package/dist/integrations/typesafe.d.cts +1 -1
  137. package/dist/integrations/typesafe.d.ts +1 -1
  138. package/dist/integrations/ucp.d.cts +1 -1
  139. package/dist/integrations/ucp.d.ts +1 -1
  140. package/dist/integrations/vercel-ai.d.cts +1 -1
  141. package/dist/integrations/vercel-ai.d.ts +1 -1
  142. package/dist/integrations/walmart.cjs +344 -0
  143. package/dist/integrations/walmart.cjs.map +1 -0
  144. package/dist/integrations/walmart.d.cts +60 -0
  145. package/dist/integrations/walmart.d.ts +60 -0
  146. package/dist/integrations/walmart.js +315 -0
  147. package/dist/integrations/walmart.js.map +1 -0
  148. package/dist/integrations/x402.d.cts +1 -1
  149. package/dist/integrations/x402.d.ts +1 -1
  150. package/dist/{types-BrDQAJdl.d.cts → types-DphtTyIC.d.cts} +72 -3
  151. package/dist/{types-BrDQAJdl.d.ts → types-DphtTyIC.d.ts} +72 -3
  152. package/package.json +92 -2
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
  *
@@ -713,6 +754,11 @@ declare class VorimSDK {
713
754
  * Create or update a token budget for an agent or workflow. One budget per
714
755
  * (scope, scope_ref) — calling this again for the same target updates it.
715
756
  *
757
+ * A budget is a ceiling; a policy rule enforces it. Add a rule with
758
+ * `match_conditions: { token_budget_gt: { scope } }` and a `deny` (or
759
+ * `escalate`) decision, otherwise actions are still allowed once the budget
760
+ * is used up.
761
+ *
716
762
  * @example
717
763
  * await vorim.setBudget({
718
764
  * scope: 'workflow', scope_ref: 'nightly-summariser',
@@ -777,9 +823,10 @@ declare class VorimSDK {
777
823
  * row's `decision` column off `'escalate'`. If we returned that verbatim,
778
824
  * a caller's obvious `if (d.decision === 'deny')` check would never fire
779
825
  * 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.
826
+ * we translate the verdict: approved → 'allow', denied → 'deny', and
827
+ * timed_out (nobody answered within the org's escalation window) → 'deny'.
828
+ * The raw resolution is also surfaced as `escalationResolution` for
829
+ * callers that want it explicitly.
783
830
  *
784
831
  * A missing verdict (malformed/truncated response) fails CLOSED to 'deny'
785
832
  * rather than 'fallback', so the deny check fires on garbled input.
@@ -911,7 +958,144 @@ declare class VorimSDK {
911
958
  capabilities: string[];
912
959
  scopes: string[];
913
960
  ttl_seconds?: number;
961
+ /**
962
+ * The agent this worker is spawned for. The worker joins the parent's
963
+ * swarm (minted on the parent if it has none), so swarm budgets,
964
+ * behaviour windows and cascading suspend cover it.
965
+ */
966
+ parent_agent_id?: string;
967
+ /**
968
+ * The worker's share of the swarm token budget per window, granted out
969
+ * of the parent's own share (conservation ledger). Needs parent_agent_id
970
+ * and a swarm budget; refused when the parent cannot cover it.
971
+ */
972
+ budget_tokens?: number;
973
+ }): Promise<any>;
974
+ /**
975
+ * The server-minted swarm an agent belongs to and every member of it.
976
+ * `{ swarm_id: null, members: [] }` for a standalone agent.
977
+ */
978
+ getSwarm(agentId: string): Promise<SwarmView>;
979
+ /**
980
+ * Register up to 50 agents in one call: an explicit list, or a template
981
+ * repeated `count` times (names `<prefix>-1` .. `<prefix>-N`), optionally
982
+ * grouped into a new swarm (`swarm: { name?, root? }`; the first created
983
+ * agent roots it when `root` is absent). Each created agent's private key
984
+ * is cached, like `register()`, so the SDK can sign for it at once. The
985
+ * plan allowance is checked for the whole batch first; a single failure is
986
+ * listed in `failed`, not thrown.
987
+ */
988
+ registerMany(input: {
989
+ agents?: Array<{
990
+ name: string;
991
+ description?: string;
992
+ capabilities?: string[];
993
+ scopes: string[];
994
+ }>;
995
+ template?: {
996
+ name_prefix: string;
997
+ description?: string;
998
+ capabilities?: string[];
999
+ scopes: string[];
1000
+ };
1001
+ count?: number;
1002
+ swarm?: {
1003
+ name?: string;
1004
+ root?: string;
1005
+ };
1006
+ }): Promise<{
1007
+ created: any[];
1008
+ failed: Array<{
1009
+ name: string;
1010
+ error: string;
1011
+ }>;
1012
+ swarm: {
1013
+ swarm_id: string;
1014
+ name: string | null;
1015
+ root_agent_id: string;
1016
+ } | null;
1017
+ }>;
1018
+ /**
1019
+ * Create or update a swarm from a spec: root, members and who they report
1020
+ * to, guardians, charter, budget and shares, breakers, tripwires. Pass the
1021
+ * YAML or JSON text, or the parsed object. `dryRun` returns the plan
1022
+ * without writing. Needs an org key with `runtime:manage`.
1023
+ */
1024
+ applySwarmSpec(spec: string | Record<string, unknown>, opts?: {
1025
+ dryRun?: boolean;
914
1026
  }): Promise<any>;
1027
+ /**
1028
+ * Rehearse a swarm: every active member against a scenario set, through
1029
+ * the real decision pipeline with nothing written, signed with the roster,
1030
+ * charter, budget and policy version it ran under. `preset: 'hazards'`
1031
+ * (default) runs generic side tasks plus one main task; `'replay'` re-judges
1032
+ * the swarm's last 100 decisions; `scenarios` runs your own (each with
1033
+ * `expect: 'allow' | 'not_allow' | 'deny' | 'escalate'`). Verdict is pass,
1034
+ * pass_with_findings or fail. Needs `runtime:manage`.
1035
+ */
1036
+ rehearseSwarm(swarmId: string, input?: {
1037
+ preset?: 'hazards' | 'replay';
1038
+ scenarios?: Array<Record<string, unknown>>;
1039
+ label?: string;
1040
+ }): Promise<any>;
1041
+ /** Past rehearsals, newest first (summary only; fetch `/swarms/:id/rehearsals/:rid` for the signed payload). */
1042
+ listSwarmRehearsals(swarmId: string): Promise<any[]>;
1043
+ /**
1044
+ * A swarm's trust: `min` (gate on it: the least trusted active member),
1045
+ * `weighted_mean` (display, weighted by recent activity), `trimmed_mean`
1046
+ * (for anything derived from peer reports), per member.
1047
+ */
1048
+ getSwarmScore(swarmId: string): Promise<any>;
1049
+ /**
1050
+ * Issue a platform-signed attestation of the swarm as it is now: roster
1051
+ * and its hash, policy version and rules hash, charter, budget, kills,
1052
+ * latest rehearsal, receipt chain head and the three scores. Valid 24 h.
1053
+ * Hand it to a counterparty; they verify it against GET /trust/keys.
1054
+ */
1055
+ attestSwarm(swarmId: string): Promise<any>;
1056
+ /** Past attestations, newest first (fetch one by id for the signed payload). */
1057
+ listSwarmAttestations(swarmId: string): Promise<any[]>;
1058
+ /** A swarm as it is now, as a spec: `{ spec, yaml }`. Keep the YAML in git and apply it again. */
1059
+ getSwarmSpec(swarmId: string): Promise<{
1060
+ spec: Record<string, unknown>;
1061
+ yaml: string;
1062
+ }>;
1063
+ /**
1064
+ * A swarm's attention picture: escalations in the last hour against its
1065
+ * budget, the rate to expect, median time to resolve, mean time between
1066
+ * interventions, and the fan-out estimate after Olsen and Goodrich (how
1067
+ * many swarms like this one person could supervise).
1068
+ */
1069
+ getSwarmAttention(swarmId: string): Promise<any>;
1070
+ /**
1071
+ * Set the swarm's attention budget: `perHour` escalations per rolling hour
1072
+ * a person may be asked to read (null = no budget). Past it `onExceed`
1073
+ * decides: 'deny' (the escalation is denied unread, the default) or
1074
+ * 'suspend' (the whole swarm stops). Returns the swarm detail.
1075
+ */
1076
+ setSwarmAttention(swarmId: string, input: {
1077
+ perHour?: number | null;
1078
+ onExceed?: 'deny' | 'suspend';
1079
+ }): Promise<any>;
1080
+ /**
1081
+ * Attributes for the agent's own spans: the OTel GenAI `gen_ai.agent.id`
1082
+ * plus Vorim's swarm and parent-agent ids (the conventions have no field
1083
+ * for either), so any OTel backend can group a swarm's spans. Cached for
1084
+ * 60 seconds per agent. Pass the active span's trace/span id back to
1085
+ * `beforeAction` / `emit` and Vorim's OTLP connector parents its spans
1086
+ * under yours.
1087
+ */
1088
+ otelAttributes(agentId: string): Promise<Record<string, string>>;
1089
+ private otelCache;
1090
+ /** Pending escalations this guardian may judge (empty for a non-guardian). */
1091
+ listGuardianEscalations(agentId: string): Promise<any[]>;
1092
+ /**
1093
+ * Approve or veto an escalation as a guardian. Needs the agent's private
1094
+ * key (loaded by register(), registerEphemeral() or useAgentKey()). A
1095
+ * quorum rule returns `{ status: 'partial', approvals, required_approvals }`
1096
+ * until enough distinct approvals arrive; one veto denies at once.
1097
+ */
1098
+ guardianResolve(agentId: string, decisionId: string, resolution: 'approved' | 'denied'): Promise<any>;
915
1099
  /**
916
1100
  * Register an OAuth provider for credential delegation.
917
1101
  */
@@ -1121,4 +1305,4 @@ interface DeviceLoginResult {
1121
1305
  */
1122
1306
  declare function deviceLogin(opts: DeviceLoginOptions): Promise<DeviceLoginResult>;
1123
1307
 
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 };
1308
+ 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
  *
@@ -713,6 +754,11 @@ declare class VorimSDK {
713
754
  * Create or update a token budget for an agent or workflow. One budget per
714
755
  * (scope, scope_ref) — calling this again for the same target updates it.
715
756
  *
757
+ * A budget is a ceiling; a policy rule enforces it. Add a rule with
758
+ * `match_conditions: { token_budget_gt: { scope } }` and a `deny` (or
759
+ * `escalate`) decision, otherwise actions are still allowed once the budget
760
+ * is used up.
761
+ *
716
762
  * @example
717
763
  * await vorim.setBudget({
718
764
  * scope: 'workflow', scope_ref: 'nightly-summariser',
@@ -777,9 +823,10 @@ declare class VorimSDK {
777
823
  * row's `decision` column off `'escalate'`. If we returned that verbatim,
778
824
  * a caller's obvious `if (d.decision === 'deny')` check would never fire
779
825
  * 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.
826
+ * we translate the verdict: approved → 'allow', denied → 'deny', and
827
+ * timed_out (nobody answered within the org's escalation window) → 'deny'.
828
+ * The raw resolution is also surfaced as `escalationResolution` for
829
+ * callers that want it explicitly.
783
830
  *
784
831
  * A missing verdict (malformed/truncated response) fails CLOSED to 'deny'
785
832
  * rather than 'fallback', so the deny check fires on garbled input.
@@ -911,7 +958,144 @@ declare class VorimSDK {
911
958
  capabilities: string[];
912
959
  scopes: string[];
913
960
  ttl_seconds?: number;
961
+ /**
962
+ * The agent this worker is spawned for. The worker joins the parent's
963
+ * swarm (minted on the parent if it has none), so swarm budgets,
964
+ * behaviour windows and cascading suspend cover it.
965
+ */
966
+ parent_agent_id?: string;
967
+ /**
968
+ * The worker's share of the swarm token budget per window, granted out
969
+ * of the parent's own share (conservation ledger). Needs parent_agent_id
970
+ * and a swarm budget; refused when the parent cannot cover it.
971
+ */
972
+ budget_tokens?: number;
973
+ }): Promise<any>;
974
+ /**
975
+ * The server-minted swarm an agent belongs to and every member of it.
976
+ * `{ swarm_id: null, members: [] }` for a standalone agent.
977
+ */
978
+ getSwarm(agentId: string): Promise<SwarmView>;
979
+ /**
980
+ * Register up to 50 agents in one call: an explicit list, or a template
981
+ * repeated `count` times (names `<prefix>-1` .. `<prefix>-N`), optionally
982
+ * grouped into a new swarm (`swarm: { name?, root? }`; the first created
983
+ * agent roots it when `root` is absent). Each created agent's private key
984
+ * is cached, like `register()`, so the SDK can sign for it at once. The
985
+ * plan allowance is checked for the whole batch first; a single failure is
986
+ * listed in `failed`, not thrown.
987
+ */
988
+ registerMany(input: {
989
+ agents?: Array<{
990
+ name: string;
991
+ description?: string;
992
+ capabilities?: string[];
993
+ scopes: string[];
994
+ }>;
995
+ template?: {
996
+ name_prefix: string;
997
+ description?: string;
998
+ capabilities?: string[];
999
+ scopes: string[];
1000
+ };
1001
+ count?: number;
1002
+ swarm?: {
1003
+ name?: string;
1004
+ root?: string;
1005
+ };
1006
+ }): Promise<{
1007
+ created: any[];
1008
+ failed: Array<{
1009
+ name: string;
1010
+ error: string;
1011
+ }>;
1012
+ swarm: {
1013
+ swarm_id: string;
1014
+ name: string | null;
1015
+ root_agent_id: string;
1016
+ } | null;
1017
+ }>;
1018
+ /**
1019
+ * Create or update a swarm from a spec: root, members and who they report
1020
+ * to, guardians, charter, budget and shares, breakers, tripwires. Pass the
1021
+ * YAML or JSON text, or the parsed object. `dryRun` returns the plan
1022
+ * without writing. Needs an org key with `runtime:manage`.
1023
+ */
1024
+ applySwarmSpec(spec: string | Record<string, unknown>, opts?: {
1025
+ dryRun?: boolean;
914
1026
  }): Promise<any>;
1027
+ /**
1028
+ * Rehearse a swarm: every active member against a scenario set, through
1029
+ * the real decision pipeline with nothing written, signed with the roster,
1030
+ * charter, budget and policy version it ran under. `preset: 'hazards'`
1031
+ * (default) runs generic side tasks plus one main task; `'replay'` re-judges
1032
+ * the swarm's last 100 decisions; `scenarios` runs your own (each with
1033
+ * `expect: 'allow' | 'not_allow' | 'deny' | 'escalate'`). Verdict is pass,
1034
+ * pass_with_findings or fail. Needs `runtime:manage`.
1035
+ */
1036
+ rehearseSwarm(swarmId: string, input?: {
1037
+ preset?: 'hazards' | 'replay';
1038
+ scenarios?: Array<Record<string, unknown>>;
1039
+ label?: string;
1040
+ }): Promise<any>;
1041
+ /** Past rehearsals, newest first (summary only; fetch `/swarms/:id/rehearsals/:rid` for the signed payload). */
1042
+ listSwarmRehearsals(swarmId: string): Promise<any[]>;
1043
+ /**
1044
+ * A swarm's trust: `min` (gate on it: the least trusted active member),
1045
+ * `weighted_mean` (display, weighted by recent activity), `trimmed_mean`
1046
+ * (for anything derived from peer reports), per member.
1047
+ */
1048
+ getSwarmScore(swarmId: string): Promise<any>;
1049
+ /**
1050
+ * Issue a platform-signed attestation of the swarm as it is now: roster
1051
+ * and its hash, policy version and rules hash, charter, budget, kills,
1052
+ * latest rehearsal, receipt chain head and the three scores. Valid 24 h.
1053
+ * Hand it to a counterparty; they verify it against GET /trust/keys.
1054
+ */
1055
+ attestSwarm(swarmId: string): Promise<any>;
1056
+ /** Past attestations, newest first (fetch one by id for the signed payload). */
1057
+ listSwarmAttestations(swarmId: string): Promise<any[]>;
1058
+ /** A swarm as it is now, as a spec: `{ spec, yaml }`. Keep the YAML in git and apply it again. */
1059
+ getSwarmSpec(swarmId: string): Promise<{
1060
+ spec: Record<string, unknown>;
1061
+ yaml: string;
1062
+ }>;
1063
+ /**
1064
+ * A swarm's attention picture: escalations in the last hour against its
1065
+ * budget, the rate to expect, median time to resolve, mean time between
1066
+ * interventions, and the fan-out estimate after Olsen and Goodrich (how
1067
+ * many swarms like this one person could supervise).
1068
+ */
1069
+ getSwarmAttention(swarmId: string): Promise<any>;
1070
+ /**
1071
+ * Set the swarm's attention budget: `perHour` escalations per rolling hour
1072
+ * a person may be asked to read (null = no budget). Past it `onExceed`
1073
+ * decides: 'deny' (the escalation is denied unread, the default) or
1074
+ * 'suspend' (the whole swarm stops). Returns the swarm detail.
1075
+ */
1076
+ setSwarmAttention(swarmId: string, input: {
1077
+ perHour?: number | null;
1078
+ onExceed?: 'deny' | 'suspend';
1079
+ }): Promise<any>;
1080
+ /**
1081
+ * Attributes for the agent's own spans: the OTel GenAI `gen_ai.agent.id`
1082
+ * plus Vorim's swarm and parent-agent ids (the conventions have no field
1083
+ * for either), so any OTel backend can group a swarm's spans. Cached for
1084
+ * 60 seconds per agent. Pass the active span's trace/span id back to
1085
+ * `beforeAction` / `emit` and Vorim's OTLP connector parents its spans
1086
+ * under yours.
1087
+ */
1088
+ otelAttributes(agentId: string): Promise<Record<string, string>>;
1089
+ private otelCache;
1090
+ /** Pending escalations this guardian may judge (empty for a non-guardian). */
1091
+ listGuardianEscalations(agentId: string): Promise<any[]>;
1092
+ /**
1093
+ * Approve or veto an escalation as a guardian. Needs the agent's private
1094
+ * key (loaded by register(), registerEphemeral() or useAgentKey()). A
1095
+ * quorum rule returns `{ status: 'partial', approvals, required_approvals }`
1096
+ * until enough distinct approvals arrive; one veto denies at once.
1097
+ */
1098
+ guardianResolve(agentId: string, decisionId: string, resolution: 'approved' | 'denied'): Promise<any>;
915
1099
  /**
916
1100
  * Register an OAuth provider for credential delegation.
917
1101
  */
@@ -1121,4 +1305,4 @@ interface DeviceLoginResult {
1121
1305
  */
1122
1306
  declare function deviceLogin(opts: DeviceLoginOptions): Promise<DeviceLoginResult>;
1123
1307
 
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 };
1308
+ 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 };