@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/CHANGELOG.md CHANGED
@@ -1,5 +1,28 @@
1
1
  # Changelog — @vorim/sdk
2
2
 
3
+ ## 4.0.0
4
+
5
+ ### Changed (breaking)
6
+
7
+ - **`beforeAction` fails closed by default.** `runtimeFailOpen` now defaults to `false`: when the runtime decision API is unreachable (network error, DNS, timeout, 5xx) the transport error is re-thrown instead of returning a synthetic `fallback` allow. A blocked or slowed path to Vorim could previously be turned into an allow. Pass `runtimeFailOpen: true` to keep the old behaviour; choose it per deployment. A reachable server that returns `deny` still denies either way, and the framework integration gates already failed closed. The server default changed on the same day: `runtime_settings.fail_open` is `false` for new orgs.
8
+
9
+ ### Fixed
10
+
11
+ - `setBudget`, `listBudgets`, `getBudgetSpend` and `deleteBudget` work with an API key. The routes were session-only, so every call from the SDK got `401 WRONG_CREDENTIAL_TYPE` while these docs said an API key worked. The key needs the new `runtime:manage` scope (separate from `runtime:decide`, so an agent's own key cannot raise its ceiling).
12
+
13
+ ### Added
14
+
15
+ - **Server-minted swarm id.** Agents gain `swarm_id`: minted on a root agent at its first delegation or ephemeral spawn and inherited by every member; nothing in a request can set it. The server stamps it on runtime decisions (`RuntimeDecision.swarmId`), audit events (in the signed bundle's attestation envelope, not the signed body) and shared-memory writes. `registerEphemeral({ parent_agent_id })` puts a spawned worker in its parent's swarm. `getSwarm(agentId)` lists a swarm. Budgets accept `scope: 'swarm'`, and a policy rule can set `behavior_scope: 'swarm'` so velocity, fan-out and `sod_conflict` read the whole swarm's window instead of one agent's. `workflow_id` remains a caller-supplied label.
16
+ - **Suspend cascades through delegation subtrees.** `updateAgent(id, { status: 'suspended' })` now also suspends every agent reachable through the agent's active identity delegations (pass `cascade: false` to stop only the one agent); `status: 'active'` on a suspended agent reverses exactly that cascade, leaving directly suspended descendants alone. `revoke()` suspends the subtree and revokes the identity links beneath the agent. Every affected agent is announced individually (webhooks, SSF/CAEP). The returned agent carries `cascade.suspended` / `cascade.reactivated`. New `suspendPreview(id)` returns the blast radius first (descendants, how many are active, open escalations, live delegation links).
17
+ - `escalationResolution` can now be `'timed_out'`. The server resolves escalations nobody answers within the org's `escalation_timeout_ms` as `timed_out` (platform-signed, like a human resolution), and `waitForDecisionResolution` translates it to `decision: 'deny'`, the same as a human denial. Previously polling stopped on the resolution but the verdict stayed `escalate`, so a caller's deny check never fired.
18
+ - **Swarm charter and conservation ledger.** `getSwarm()` members carry `parent_agent_id`, `is_ephemeral` and `is_guardian`. `delegateToAgent(...)` and `registerEphemeral(...)` accept `budget_tokens`: a share of the swarm's token budget granted out of the delegator's or parent's own share, refused with `409 ALLOCATION_EXCEEDED` when it would not fit (the ledger's invariant: granted to children plus own spend never exceeds what you hold). Joins that would break the swarm's charter (depth, children per parent, live members, lifetime) are refused with `409 SWARM_CHARTER_EXCEEDED` or `SWARM_EXPIRED`.
19
+ - **Guardian agents.** `listGuardianEscalations(agentId)` returns the pending escalations assigned to the guardians of the agent's swarm, and `guardianResolve(agentId, decisionId, resolution)` signs the canonical approval line (`vorim-escalation-approval|v1|…`) with the agent's cached key and submits it. A rule with `approver_role: 'guardian'` and `quorum_n` needs that many distinct approvals; one veto denies.
20
+ - **Trace context.** `beforeAction()` and `emit()` accept `trace_id` / `span_id` or a W3C `traceparent`; `foldTraceparent()` folds the header into the two ids before signing, so a v1 signature covers stored columns only. `otelAttributes(agentId)` returns `gen_ai.agent.id`, `vorim.swarm.id` and `vorim.parent_agent.id` for the agent's own spans (cached 60 s). Trace ids are correlation only, never authorisation.
21
+ - **Bulk registration.** `registerMany({ agents })` or `registerMany({ template, count })` registers up to 50 agents in one call, optionally grouped into a new swarm; each returned private key is cached like `register()`.
22
+ - **Declarative swarm spec.** `applySwarmSpec(yamlOrObject, { dryRun })` plans or applies a `vorim.swarm/v1` document (members, guardians, charter, budget and shares, breakers, tripwires, attention budget); `getSwarmSpec(swarmId)` exports the current swarm as `{ spec, yaml }`.
23
+ - **Rehearsals, score and attestation.** `rehearseSwarm(swarmId, { preset: 'hazards' | 'replay' } | { scenarios })` runs every active member through the real decision pipeline with nothing written and stores a platform-signed attestation; `listSwarmRehearsals(swarmId)`. `getSwarmScore(swarmId)` gives the members' trust as `min` (gate on it), `weighted_mean` (display) and `trimmed_mean` (peer-derived). `attestSwarm(swarmId)` issues a platform-signed statement of the swarm now (roster hash, policy hash, charter, budget, kills, rehearsal, receipt head, scores), valid 24 hours and verifiable offline against `GET /trust/keys`; `listSwarmAttestations(swarmId)`.
24
+ - **Attention budget.** `getSwarmAttention(swarmId)` reports escalations per hour against the swarm's budget, median time to resolve, mean time between interventions and the fan-out estimate after Olsen and Goodrich; `setSwarmAttention(swarmId, { perHour, onExceed })` sets the budget (past it, escalations are denied unread or the swarm is suspended).
25
+
3
26
  ## 3.23.0
4
27
 
5
28
  ### Added
package/dist/index.cjs CHANGED
@@ -45,6 +45,7 @@ __export(index_exports, {
45
45
  default: () => createVorim,
46
46
  deviceLogin: () => deviceLogin,
47
47
  eventDigest: () => eventDigest,
48
+ foldTraceparent: () => foldTraceparent,
48
49
  hashPayload: () => hashPayload,
49
50
  hashPreviousEvent: () => hashPreviousEvent,
50
51
  hashSystemPrompt: () => hashSystemPrompt,
@@ -930,7 +931,7 @@ async function verifyHttpRequest(request, options) {
930
931
  }
931
932
 
932
933
  // src/index.ts
933
- var SDK_VERSION = true ? "3.23.0" : "0.0.0";
934
+ var SDK_VERSION = true ? "4.0.0" : "0.0.0";
934
935
  var USER_AGENT = `vorim-sdk/${SDK_VERSION}`;
935
936
  function sleep(ms) {
936
937
  return new Promise((resolve) => setTimeout(resolve, ms));
@@ -973,6 +974,17 @@ function toApprovalAttestation(raw) {
973
974
  signature: raw.signature
974
975
  };
975
976
  }
977
+ function foldTraceparent(input) {
978
+ if (!input.traceparent) return input;
979
+ const { traceparent, ...rest } = input;
980
+ const m = /^[0-9a-f]{2}-([0-9a-f]{32})-([0-9a-f]{16})-[0-9a-f]{2}$/i.exec(traceparent.trim());
981
+ const out = { ...rest };
982
+ if (m) {
983
+ if (!out.trace_id) out.trace_id = m[1].toLowerCase();
984
+ if (!out.span_id) out.span_id = m[2].toLowerCase();
985
+ }
986
+ return out;
987
+ }
976
988
  var VorimSDK = class _VorimSDK {
977
989
  apiKey;
978
990
  baseUrl;
@@ -1028,7 +1040,7 @@ var VorimSDK = class _VorimSDK {
1028
1040
  }
1029
1041
  }
1030
1042
  this.chainEvents = config.chainEvents ?? false;
1031
- this.runtimeFailOpen = config.runtimeFailOpen ?? true;
1043
+ this.runtimeFailOpen = config.runtimeFailOpen ?? false;
1032
1044
  this.noPayload = config.noPayload !== void 0 && config.noPayload !== false;
1033
1045
  this.maxMetadataChars = typeof config.noPayload === "object" && typeof config.noPayload.maxMetadataChars === "number" ? config.noPayload.maxMetadataChars : 256;
1034
1046
  }
@@ -1131,11 +1143,26 @@ var VorimSDK = class _VorimSDK {
1131
1143
  return { agents: env.data ?? [], meta: env.meta ?? null };
1132
1144
  }
1133
1145
  /**
1134
- * Update an agent's metadata.
1146
+ * Update an agent's metadata or status.
1147
+ *
1148
+ * `status: 'suspended'` is the kill switch and, since 4.0.0, cascades to
1149
+ * every agent reachable through the agent's active identity delegations
1150
+ * unless `cascade: false`. Setting `status: 'active'` on a suspended agent
1151
+ * reverses exactly that cascade. The returned agent carries
1152
+ * `cascade.suspended` / `cascade.reactivated` with the agent ids touched.
1153
+ * See {@link suspendPreview} for the blast radius before acting.
1135
1154
  */
1136
1155
  async updateAgent(agentId, updates) {
1137
1156
  return this.patch(`/agents/${agentId}`, updates);
1138
1157
  }
1158
+ /**
1159
+ * What suspending (or revoking) this agent would touch: its delegation
1160
+ * subtree, how many of those agents are still active, open escalations
1161
+ * across the subtree, and live delegation links. Writes nothing.
1162
+ */
1163
+ async suspendPreview(agentId) {
1164
+ return this.get(`/agents/${agentId}/suspend-preview`);
1165
+ }
1139
1166
  /**
1140
1167
  * Revoke an agent (permanent deactivation).
1141
1168
  */
@@ -1495,9 +1522,9 @@ var VorimSDK = class _VorimSDK {
1495
1522
  * poll {@link waitForDecisionResolution} for the human decision.
1496
1523
  *
1497
1524
  * Transport failures (network/DNS/timeout/5xx) respect the constructor's
1498
- * `runtimeFailOpen` flag: when true (default) a synthetic `fallback`
1499
- * decision is returned so a control-plane blip does not block the agent;
1500
- * when false the underlying error is re-thrown.
1525
+ * `runtimeFailOpen` flag: when false (default) the underlying error is
1526
+ * re-thrown; when true a synthetic `fallback` decision is returned so a
1527
+ * control-plane blip does not block the agent.
1501
1528
  *
1502
1529
  * Always pass the public `agid_*` id as `agentId`.
1503
1530
  *
@@ -1522,7 +1549,10 @@ var VorimSDK = class _VorimSDK {
1522
1549
  required_scope: input.requiredScope,
1523
1550
  idempotency_key: input.idempotencyKey,
1524
1551
  workflow_id: input.workflowId,
1525
- estimated_tokens: input.estimatedTokens
1552
+ estimated_tokens: input.estimatedTokens,
1553
+ trace_id: input.traceId,
1554
+ span_id: input.spanId,
1555
+ traceparent: input.traceparent
1526
1556
  };
1527
1557
  let raw;
1528
1558
  try {
@@ -1542,6 +1572,7 @@ var VorimSDK = class _VorimSDK {
1542
1572
  latencyMs: 0,
1543
1573
  isFallback: true,
1544
1574
  policyVersion: 0,
1575
+ swarmId: null,
1545
1576
  escalationResolution: null,
1546
1577
  approval: null
1547
1578
  };
@@ -1560,8 +1591,9 @@ var VorimSDK = class _VorimSDK {
1560
1591
  // Enforcement runs inside beforeAction(): pass `workflowId` + `estimatedTokens`
1561
1592
  // on the action, and a `token_budget_gt` policy rule denies the action before
1562
1593
  // the spend if it would breach the budget. These methods manage the budgets
1563
- // and read live spend (dashboard-oriented; require a JWT-authed client or an
1564
- // owner/admin API key).
1594
+ // and read live spend. They need an API key holding the `runtime:manage`
1595
+ // scope (deliberately separate from `runtime:decide`, so an agent's own key
1596
+ // cannot raise its ceiling).
1565
1597
  /**
1566
1598
  * Create or update a token budget for an agent or workflow. One budget per
1567
1599
  * (scope, scope_ref) — calling this again for the same target updates it.
@@ -1656,19 +1688,20 @@ var VorimSDK = class _VorimSDK {
1656
1688
  * row's `decision` column off `'escalate'`. If we returned that verbatim,
1657
1689
  * a caller's obvious `if (d.decision === 'deny')` check would never fire
1658
1690
  * on a human DENIAL — a silent fail-open. So when a resolution is present
1659
- * we translate the verdict: approved → 'allow', denied → 'deny'. The raw
1660
- * resolution is also surfaced as `escalationResolution` for callers that
1661
- * want it explicitly.
1691
+ * we translate the verdict: approved → 'allow', denied → 'deny', and
1692
+ * timed_out (nobody answered within the org's escalation window) → 'deny'.
1693
+ * The raw resolution is also surfaced as `escalationResolution` for
1694
+ * callers that want it explicitly.
1662
1695
  *
1663
1696
  * A missing verdict (malformed/truncated response) fails CLOSED to 'deny'
1664
1697
  * rather than 'fallback', so the deny check fires on garbled input.
1665
1698
  */
1666
1699
  toRuntimeDecision(raw) {
1667
- const resolution = raw?.escalation_resolution === "approved" ? "approved" : raw?.escalation_resolution === "denied" ? "denied" : null;
1700
+ const resolution = raw?.escalation_resolution === "approved" ? "approved" : raw?.escalation_resolution === "denied" ? "denied" : raw?.escalation_resolution === "timed_out" ? "timed_out" : null;
1668
1701
  const hasVerdict = typeof raw?.decision === "string";
1669
1702
  let decision;
1670
1703
  if (raw?.decision === "escalate" && resolution === "approved") decision = "allow";
1671
- else if (raw?.decision === "escalate" && resolution === "denied") decision = "deny";
1704
+ else if (raw?.decision === "escalate" && (resolution === "denied" || resolution === "timed_out")) decision = "deny";
1672
1705
  else if (hasVerdict) decision = raw.decision;
1673
1706
  else decision = "deny";
1674
1707
  return {
@@ -1683,6 +1716,7 @@ var VorimSDK = class _VorimSDK {
1683
1716
  latencyMs: raw?.latency_ms ?? 0,
1684
1717
  isFallback: raw?.is_fallback ?? !hasVerdict,
1685
1718
  policyVersion: raw?.policy_version ?? 0,
1719
+ swarmId: typeof raw?.swarm_id === "string" ? raw.swarm_id : null,
1686
1720
  escalationResolution: resolution,
1687
1721
  approval: toApprovalAttestation(raw?.approval)
1688
1722
  };
@@ -1817,6 +1851,7 @@ var VorimSDK = class _VorimSDK {
1817
1851
  }
1818
1852
  async prepareEvent(event, signOverride) {
1819
1853
  this.assertNoPayload(event);
1854
+ event = foldTraceparent(event);
1820
1855
  const shouldSign = signOverride ?? this.autoSign;
1821
1856
  if (!shouldSign && !this.chainEvents) return event;
1822
1857
  if (this.chainEvents) {
@@ -1936,6 +1971,168 @@ var VorimSDK = class _VorimSDK {
1936
1971
  }
1937
1972
  return result;
1938
1973
  }
1974
+ /**
1975
+ * The server-minted swarm an agent belongs to and every member of it.
1976
+ * `{ swarm_id: null, members: [] }` for a standalone agent.
1977
+ */
1978
+ async getSwarm(agentId) {
1979
+ return this.get(`/agents/${agentId}/swarm`);
1980
+ }
1981
+ // ─── Many agents at once ─────────────────────────────────────────────
1982
+ /**
1983
+ * Register up to 50 agents in one call: an explicit list, or a template
1984
+ * repeated `count` times (names `<prefix>-1` .. `<prefix>-N`), optionally
1985
+ * grouped into a new swarm (`swarm: { name?, root? }`; the first created
1986
+ * agent roots it when `root` is absent). Each created agent's private key
1987
+ * is cached, like `register()`, so the SDK can sign for it at once. The
1988
+ * plan allowance is checked for the whole batch first; a single failure is
1989
+ * listed in `failed`, not thrown.
1990
+ */
1991
+ async registerMany(input) {
1992
+ const result = await this.post("/agents/bulk", input);
1993
+ for (const c of result?.created ?? []) {
1994
+ const id = c?.agent?.agent_id;
1995
+ if (id && c?.private_key) this.agentKeys.set(id, c.private_key);
1996
+ }
1997
+ return result;
1998
+ }
1999
+ // ─── Declarative swarm spec (vorim.swarm/v1) ─────────────────────────
2000
+ /**
2001
+ * Create or update a swarm from a spec: root, members and who they report
2002
+ * to, guardians, charter, budget and shares, breakers, tripwires. Pass the
2003
+ * YAML or JSON text, or the parsed object. `dryRun` returns the plan
2004
+ * without writing. Needs an org key with `runtime:manage`.
2005
+ */
2006
+ async applySwarmSpec(spec, opts = {}) {
2007
+ const body = typeof spec === "string" ? { spec } : spec;
2008
+ return this.post(`/swarms/apply?dry_run=${opts.dryRun ? "true" : "false"}`, body);
2009
+ }
2010
+ /**
2011
+ * Rehearse a swarm: every active member against a scenario set, through
2012
+ * the real decision pipeline with nothing written, signed with the roster,
2013
+ * charter, budget and policy version it ran under. `preset: 'hazards'`
2014
+ * (default) runs generic side tasks plus one main task; `'replay'` re-judges
2015
+ * the swarm's last 100 decisions; `scenarios` runs your own (each with
2016
+ * `expect: 'allow' | 'not_allow' | 'deny' | 'escalate'`). Verdict is pass,
2017
+ * pass_with_findings or fail. Needs `runtime:manage`.
2018
+ */
2019
+ async rehearseSwarm(swarmId, input = {}) {
2020
+ return this.post(`/swarms/${encodeURIComponent(swarmId)}/rehearse`, input);
2021
+ }
2022
+ /** Past rehearsals, newest first (summary only; fetch `/swarms/:id/rehearsals/:rid` for the signed payload). */
2023
+ async listSwarmRehearsals(swarmId) {
2024
+ return this.get(`/swarms/${encodeURIComponent(swarmId)}/rehearsals`);
2025
+ }
2026
+ /**
2027
+ * A swarm's trust: `min` (gate on it: the least trusted active member),
2028
+ * `weighted_mean` (display, weighted by recent activity), `trimmed_mean`
2029
+ * (for anything derived from peer reports), per member.
2030
+ */
2031
+ async getSwarmScore(swarmId) {
2032
+ return this.get(`/swarms/${encodeURIComponent(swarmId)}/score`);
2033
+ }
2034
+ /**
2035
+ * Issue a platform-signed attestation of the swarm as it is now: roster
2036
+ * and its hash, policy version and rules hash, charter, budget, kills,
2037
+ * latest rehearsal, receipt chain head and the three scores. Valid 24 h.
2038
+ * Hand it to a counterparty; they verify it against GET /trust/keys.
2039
+ */
2040
+ async attestSwarm(swarmId) {
2041
+ return this.post(`/swarms/${encodeURIComponent(swarmId)}/attest`, {});
2042
+ }
2043
+ /** Past attestations, newest first (fetch one by id for the signed payload). */
2044
+ async listSwarmAttestations(swarmId) {
2045
+ return this.get(`/swarms/${encodeURIComponent(swarmId)}/attestations`);
2046
+ }
2047
+ /** A swarm as it is now, as a spec: `{ spec, yaml }`. Keep the YAML in git and apply it again. */
2048
+ async getSwarmSpec(swarmId) {
2049
+ return this.get(`/swarms/${encodeURIComponent(swarmId)}/spec`);
2050
+ }
2051
+ /**
2052
+ * A swarm's attention picture: escalations in the last hour against its
2053
+ * budget, the rate to expect, median time to resolve, mean time between
2054
+ * interventions, and the fan-out estimate after Olsen and Goodrich (how
2055
+ * many swarms like this one person could supervise).
2056
+ */
2057
+ async getSwarmAttention(swarmId) {
2058
+ return this.get(`/swarms/${encodeURIComponent(swarmId)}/attention`);
2059
+ }
2060
+ /**
2061
+ * Set the swarm's attention budget: `perHour` escalations per rolling hour
2062
+ * a person may be asked to read (null = no budget). Past it `onExceed`
2063
+ * decides: 'deny' (the escalation is denied unread, the default) or
2064
+ * 'suspend' (the whole swarm stops). Returns the swarm detail.
2065
+ */
2066
+ async setSwarmAttention(swarmId, input) {
2067
+ const body = {};
2068
+ if (input.perHour !== void 0) body.attention_budget_per_hour = input.perHour;
2069
+ if (input.onExceed !== void 0) body.attention_exceeded_action = input.onExceed;
2070
+ return this.patch(`/swarms/${encodeURIComponent(swarmId)}`, body);
2071
+ }
2072
+ // ─── OpenTelemetry ───────────────────────────────────────────────────
2073
+ /**
2074
+ * Attributes for the agent's own spans: the OTel GenAI `gen_ai.agent.id`
2075
+ * plus Vorim's swarm and parent-agent ids (the conventions have no field
2076
+ * for either), so any OTel backend can group a swarm's spans. Cached for
2077
+ * 60 seconds per agent. Pass the active span's trace/span id back to
2078
+ * `beforeAction` / `emit` and Vorim's OTLP connector parents its spans
2079
+ * under yours.
2080
+ */
2081
+ async otelAttributes(agentId) {
2082
+ const cached = this.otelCache.get(agentId);
2083
+ if (cached && cached.expires > Date.now()) return cached.attrs;
2084
+ const attrs = { "gen_ai.agent.id": agentId, "vorim.agent.id": agentId };
2085
+ try {
2086
+ const swarm = await this.getSwarm(agentId);
2087
+ if (swarm?.swarm_id) {
2088
+ attrs["vorim.swarm.id"] = swarm.swarm_id;
2089
+ const me = swarm.members?.find((m) => m.agent_id === agentId);
2090
+ if (me?.parent_agent_id) attrs["vorim.parent_agent.id"] = me.parent_agent_id;
2091
+ }
2092
+ } catch {
2093
+ }
2094
+ this.otelCache.set(agentId, { attrs, expires: Date.now() + 6e4 });
2095
+ return attrs;
2096
+ }
2097
+ otelCache = /* @__PURE__ */ new Map();
2098
+ // ─── Guardian agents ─────────────────────────────────────────────────
2099
+ //
2100
+ // An agent with metadata.class = 'guardian' judges escalations that a rule
2101
+ // with approver_role 'guardian' assigned to its swarm. It reads the queue
2102
+ // from the server (never from a peer) and answers with a verdict signed by
2103
+ // its own key over one canonical line, so the approval is verifiable
2104
+ // offline against the agent's registered public key. An unanswered
2105
+ // escalation times out as denied: an absent guardian fails closed.
2106
+ /** Pending escalations this guardian may judge (empty for a non-guardian). */
2107
+ async listGuardianEscalations(agentId) {
2108
+ return this.get(`/runtime/guardian/escalations?agent_id=${encodeURIComponent(agentId)}`);
2109
+ }
2110
+ /**
2111
+ * Approve or veto an escalation as a guardian. Needs the agent's private
2112
+ * key (loaded by register(), registerEphemeral() or useAgentKey()). A
2113
+ * quorum rule returns `{ status: 'partial', approvals, required_approvals }`
2114
+ * until enough distinct approvals arrive; one veto denies at once.
2115
+ */
2116
+ async guardianResolve(agentId, decisionId, resolution) {
2117
+ const key = this.agentKeys.get(agentId);
2118
+ if (!key) {
2119
+ throw new VorimError(
2120
+ 400,
2121
+ "AGENT_KEY_NOT_LOADED",
2122
+ `No private key is cached for agent ${agentId}. Call register() or useAgentKey(agentId, privateKeyPem) first.`
2123
+ );
2124
+ }
2125
+ const signedAt = (/* @__PURE__ */ new Date()).toISOString();
2126
+ const line = `vorim-escalation-approval|v1|${decisionId}|${resolution}|agent:${agentId}|${signedAt}`;
2127
+ const signature = await this.sign(line, key);
2128
+ return this.post("/runtime/guardian/resolve", {
2129
+ agent_id: agentId,
2130
+ decision_id: decisionId,
2131
+ resolution,
2132
+ signed_at: signedAt,
2133
+ signature
2134
+ });
2135
+ }
1939
2136
  // ─── Credential Delegation ──────────────────────────────────────────
1940
2137
  /**
1941
2138
  * Register an OAuth provider for credential delegation.
@@ -2251,6 +2448,7 @@ async function deviceLogin(opts) {
2251
2448
  createSignatureBase,
2252
2449
  deviceLogin,
2253
2450
  eventDigest,
2451
+ foldTraceparent,
2254
2452
  hashPayload,
2255
2453
  hashPreviousEvent,
2256
2454
  hashSystemPrompt,