@armoriq/sdk-dev 0.6.2 → 0.6.3

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 (69) hide show
  1. package/dist/_build_env.d.ts.map +1 -1
  2. package/dist/_build_env.js +1 -1
  3. package/dist/_build_env.js.map +1 -1
  4. package/dist/cli/commands/auth.d.ts.map +1 -1
  5. package/dist/cli/commands/auth.js +4 -1
  6. package/dist/cli/commands/auth.js.map +1 -1
  7. package/dist/client.d.ts +35 -0
  8. package/dist/client.d.ts.map +1 -1
  9. package/dist/client.js +77 -1
  10. package/dist/client.js.map +1 -1
  11. package/dist/config.d.ts +17 -0
  12. package/dist/config.d.ts.map +1 -1
  13. package/dist/config.js +19 -1
  14. package/dist/config.js.map +1 -1
  15. package/dist/crypto_verify.d.ts +3 -0
  16. package/dist/crypto_verify.d.ts.map +1 -1
  17. package/dist/crypto_verify.js +77 -0
  18. package/dist/crypto_verify.js.map +1 -1
  19. package/dist/index.d.ts +4 -3
  20. package/dist/index.d.ts.map +1 -1
  21. package/dist/index.js +19 -3
  22. package/dist/index.js.map +1 -1
  23. package/dist/integrations/microsoft_copilot.d.ts +84 -0
  24. package/dist/integrations/microsoft_copilot.d.ts.map +1 -0
  25. package/dist/integrations/microsoft_copilot.js +126 -0
  26. package/dist/integrations/microsoft_copilot.js.map +1 -0
  27. package/dist/models.d.ts +17 -0
  28. package/dist/models.d.ts.map +1 -1
  29. package/dist/observability/handle.d.ts +41 -0
  30. package/dist/observability/handle.d.ts.map +1 -0
  31. package/dist/observability/handle.js +54 -0
  32. package/dist/observability/handle.js.map +1 -0
  33. package/dist/observability/index.d.ts +15 -0
  34. package/dist/observability/index.d.ts.map +1 -0
  35. package/dist/observability/index.js +39 -0
  36. package/dist/observability/index.js.map +1 -0
  37. package/dist/observability/model-prices.d.ts +39 -0
  38. package/dist/observability/model-prices.d.ts.map +1 -0
  39. package/dist/observability/model-prices.js +127 -0
  40. package/dist/observability/model-prices.js.map +1 -0
  41. package/dist/observability/recorder.d.ts +245 -0
  42. package/dist/observability/recorder.d.ts.map +1 -0
  43. package/dist/observability/recorder.js +475 -0
  44. package/dist/observability/recorder.js.map +1 -0
  45. package/dist/observability/schema.d.ts +163 -0
  46. package/dist/observability/schema.d.ts.map +1 -0
  47. package/dist/observability/schema.js +291 -0
  48. package/dist/observability/schema.js.map +1 -0
  49. package/dist/observability/shipper.d.ts +84 -0
  50. package/dist/observability/shipper.d.ts.map +1 -0
  51. package/dist/observability/shipper.js +206 -0
  52. package/dist/observability/shipper.js.map +1 -0
  53. package/dist/observability/trace-summary.d.ts +34 -0
  54. package/dist/observability/trace-summary.d.ts.map +1 -0
  55. package/dist/observability/trace-summary.js +108 -0
  56. package/dist/observability/trace-summary.js.map +1 -0
  57. package/dist/session.d.ts +148 -3
  58. package/dist/session.d.ts.map +1 -1
  59. package/dist/session.js +1035 -195
  60. package/dist/session.js.map +1 -1
  61. package/dist/token_usage.d.ts +18 -1
  62. package/dist/token_usage.d.ts.map +1 -1
  63. package/dist/token_usage.js +112 -2
  64. package/dist/token_usage.js.map +1 -1
  65. package/package.json +3 -2
  66. package/dist/integrations/google_adk_mcp_toolset.d.ts +0 -64
  67. package/dist/integrations/google_adk_mcp_toolset.d.ts.map +0 -1
  68. package/dist/integrations/google_adk_mcp_toolset.js +0 -91
  69. package/dist/integrations/google_adk_mcp_toolset.js.map +0 -1
@@ -0,0 +1,108 @@
1
+ "use strict";
2
+ /**
3
+ * Trace-level tag/output-summary derivation.
4
+ *
5
+ * A trace's own `tags`/`attributes.output` are never populated by callers
6
+ * today (every chokepoint only passes freeform `attributes` at
7
+ * `startTrace()` time, before any child span exists) — so without this
8
+ * module every trace ships with `tags: []` and no output summary, even
9
+ * though the information needed to compute both already lives on the
10
+ * trace's own spans by the time `endTrace()` runs.
11
+ *
12
+ * This is intentionally derived, not caller-supplied: it's computed once,
13
+ * in one place (`ObservabilityRecorder.endTrace`), from the same in-memory
14
+ * `spans` array the recorder already holds — no new public API surface,
15
+ * no risk of callers drifting from each other's tagging conventions.
16
+ *
17
+ * Kept deliberately conservative and low-cardinality (per the dashboard's
18
+ * TAGS column contract): product + distinct tool names + one decision
19
+ * verdict, nothing free-text or unbounded.
20
+ */
21
+ Object.defineProperty(exports, "__esModule", { value: true });
22
+ exports.deriveTraceSummary = deriveTraceSummary;
23
+ const MAX_TOOL_TAGS = 8;
24
+ function isPolicyCallAttributes(attrs) {
25
+ return attrs.kind === 'policy_call';
26
+ }
27
+ /**
28
+ * Distinct tool names referenced by any span on the trace. Reads
29
+ * `attributes.toolName` off `kind: 'span'` container spans (the shape
30
+ * `iap.check`/`tool.report`/generic tool spans use) — this covers every
31
+ * known emitter without needing parent/child span-kind coupling.
32
+ */
33
+ function collectToolNames(spans) {
34
+ const names = new Set();
35
+ for (const span of spans) {
36
+ const toolName = span.attributes.toolName;
37
+ if (typeof toolName === 'string' && toolName.length > 0) {
38
+ names.add(toolName);
39
+ }
40
+ }
41
+ return Array.from(names).slice(0, MAX_TOOL_TAGS);
42
+ }
43
+ function collectDecisionCounts(spans) {
44
+ const counts = { allow: 0, deny: 0, other: 0, total: 0 };
45
+ for (const span of spans) {
46
+ if (!isPolicyCallAttributes(span.attributes))
47
+ continue;
48
+ counts.total += 1;
49
+ if (span.attributes.decision === 'allow')
50
+ counts.allow += 1;
51
+ else if (span.attributes.decision === 'deny')
52
+ counts.deny += 1;
53
+ else
54
+ counts.other += 1;
55
+ }
56
+ return counts;
57
+ }
58
+ /** Overall verdict tag for the trace: 'allowed' | 'blocked' | 'mixed'. */
59
+ function decisionVerdict(counts) {
60
+ if (counts.total === 0)
61
+ return null;
62
+ if (counts.deny > 0 && counts.deny < counts.total)
63
+ return 'mixed';
64
+ if (counts.deny === counts.total)
65
+ return 'blocked';
66
+ if (counts.other > 0)
67
+ return 'mixed';
68
+ return 'allowed';
69
+ }
70
+ /** Concise, non-sensitive outcome summary, e.g. "5 checks · all allowed". */
71
+ function outputSummary(counts) {
72
+ if (counts.total === 0)
73
+ return null;
74
+ const noun = counts.total === 1 ? 'check' : 'checks';
75
+ if (counts.deny === 0 && counts.other === 0) {
76
+ return `${counts.total} ${noun} · all allowed`;
77
+ }
78
+ if (counts.deny === counts.total) {
79
+ return `${counts.total} ${noun} · all blocked`;
80
+ }
81
+ const parts = [];
82
+ if (counts.deny > 0)
83
+ parts.push(`${counts.deny} blocked`);
84
+ if (counts.other > 0)
85
+ parts.push(`${counts.other} pending`);
86
+ return `${counts.total} ${noun} · ${parts.join(', ')}`;
87
+ }
88
+ /**
89
+ * Derive `{ tags, output }` for a trace from its accumulated spans. Pure
90
+ * and read-only — never mutates `spans`. Callers merge the result onto the
91
+ * trace record themselves (see `ObservabilityRecorder.endTrace`), preserving
92
+ * any tags/output the caller already set explicitly.
93
+ */
94
+ function deriveTraceSummary(spans, product) {
95
+ const tags = [];
96
+ if (product)
97
+ tags.push(product);
98
+ tags.push(...collectToolNames(spans));
99
+ const counts = collectDecisionCounts(spans);
100
+ const verdict = decisionVerdict(counts);
101
+ if (verdict)
102
+ tags.push(verdict);
103
+ return {
104
+ tags,
105
+ output: outputSummary(counts),
106
+ };
107
+ }
108
+ //# sourceMappingURL=trace-summary.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"trace-summary.js","sourceRoot":"","sources":["../../src/observability/trace-summary.ts"],"names":[],"mappings":"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"}
package/dist/session.d.ts CHANGED
@@ -14,8 +14,10 @@
14
14
  * return session.dispatch(toolName, toolArgs);
15
15
  */
16
16
  import { ArmorIQClient } from './client';
17
+ import { ObservabilityConfig } from './config';
17
18
  import { IntentToken, ToolCall } from './models';
18
19
  import { ToolNameParser } from './plan_builder';
20
+ import { ObservabilityRecorder, type TraceContext } from './observability';
19
21
  export type SessionMode = 'local' | 'proxy' | 'sdk';
20
22
  export interface SessionOptions {
21
23
  toolNameParser?: ToolNameParser;
@@ -62,6 +64,30 @@ export interface SessionOptions {
62
64
  * unset.
63
65
  */
64
66
  reanchorGranularity?: 'eager' | 'deferred';
67
+ /**
68
+ * Observability emitter overrides for this session. Falls back to the
69
+ * client-level `SDKConfig.observability` when unset. Setting
70
+ * `enabled: false` disables the recorder entirely.
71
+ */
72
+ observability?: ObservabilityConfig;
73
+ /**
74
+ * Stable session id stamped onto every observability trace emitted by
75
+ * this session (`obs_traces.session_id` / groups into one `obs_sessions`
76
+ * row). Must be a valid UUID — the backend's `obs_sessions.id` column is
77
+ * a UUID column, so a non-UUID value is ignored (never emitted) and the
78
+ * SDK mints a fresh `crypto.randomUUID()` instead.
79
+ *
80
+ * If unset, `contextId` is used as a fallback (also validated as a UUID).
81
+ * If neither is a valid UUID, the SDK mints one UUID per session and uses
82
+ * it for every trace that session emits.
83
+ */
84
+ sessionId?: string;
85
+ /**
86
+ * Alias for `sessionId` — accepted so callers who already track a plan
87
+ * `contextId` (e.g. from `ArmorIQConfig`/`SDKConfig`) can pass it straight
88
+ * through without renaming. Ignored if `sessionId` is also set.
89
+ */
90
+ contextId?: string;
65
91
  }
66
92
  /**
67
93
  * A policy obligation surfaced from the enforce decision. The backend collapses
@@ -119,11 +145,97 @@ export declare class ArmorIQSession {
119
145
  private currentToken?;
120
146
  private mcpByAction;
121
147
  private declaredTools;
148
+ private obs;
149
+ /**
150
+ * This session's one stable observability session id — stamped onto every
151
+ * trace this session emits (via the recorder's `defaultSessionId`, see
152
+ * `ObservabilityConfig.sessionId`). Always a valid UUID; the backend's
153
+ * `obs_sessions.id` column is UUID-typed, so a non-UUID id (e.g. the
154
+ * legacy `contextId` default of the literal string `'default'`) can never
155
+ * form a session and traces stamped with it can never be grouped.
156
+ *
157
+ * Resolution order:
158
+ * 1. `opts.sessionId` if it's a valid UUID.
159
+ * 2. `opts.contextId` if it's a valid UUID.
160
+ * 3. A freshly minted `crypto.randomUUID()` (default — no arg needed).
161
+ */
162
+ readonly sessionId: string;
163
+ /**
164
+ * Model A (trace-per-plan): the ONE active observability trace for the
165
+ * current plan. Every chokepoint (enforce/check/report/dispatch/...)
166
+ * records a container span under this trace via `ensurePlanTrace()`
167
+ * instead of opening its own trace — matching Langfuse/OTel's
168
+ * Session → Trace → Observation hierarchy (one IAP plan = one trace).
169
+ *
170
+ * Lifecycle: opened by `ensurePlanTrace()` (called from `startPlan()` or
171
+ * lazily by any chokepoint invoked before `startPlan()` — back-compat);
172
+ * ended by `endPlanTrace()`, called on the NEXT `startPlan()`, on
173
+ * `close()`/`dispose()`, and on `flushObservability()`.
174
+ */
175
+ private activePlanTrace;
122
176
  constructor(client: ArmorIQClient, opts?: SessionOptions);
177
+ /**
178
+ * The session's `ObservabilityRecorder`, or `null` when observability is
179
+ * disabled for this session. Pass this explicitly to
180
+ * `summarizeTranscriptUsage(path, recorder, ctx)` / `client.captureTranscriptTokens({
181
+ * ..., observabilityRecorder, planTraceCtx })` so transcript-derived generation spans are
182
+ * attributed to the correct session — the SDK no longer keeps a
183
+ * process-global "active recorder" (see #4: concurrent sessions would
184
+ * otherwise misattribute usage to whichever session constructed last).
185
+ */
186
+ get observabilityRecorder(): ObservabilityRecorder | null;
187
+ /**
188
+ * Model A (Task 4): the session's active plan trace context, or `null` if
189
+ * none is open yet (lazily opens on first use — same as every chokepoint).
190
+ * Pass this as `summarizeTranscriptUsage(path, session.observabilityRecorder,
191
+ * session.activePlanTraceContext)` (or via
192
+ * `client.captureTranscriptTokens({ ..., planTraceCtx: session.activePlanTraceContext })`)
193
+ * so transcript-derived generation spans nest under the SAME plan trace as
194
+ * every other chokepoint this session recorded, instead of opening a
195
+ * standalone `llm.usage.report` trace.
196
+ */
197
+ get activePlanTraceContext(): TraceContext | null;
198
+ /**
199
+ * Return the session's active plan trace, lazily opening one if none is
200
+ * active. This is the ONE trace every chokepoint's container span nests
201
+ * under (Model A: trace-per-plan). Returns `null` when observability is
202
+ * disabled — every call site already treats a null ctx as "skip emit".
203
+ *
204
+ * Back-compat (plan §"Global Constraints"): a chokepoint invoked with no
205
+ * prior `startPlan()` (e.g. a standalone `enforceLocal()`/`report()` call)
206
+ * still needs to emit — so this opens a plan trace lazily on first use
207
+ * rather than requiring `startPlan()` to have run first.
208
+ */
209
+ private ensurePlanTrace;
210
+ /**
211
+ * End the active plan trace (if any) and clear it. Called on the NEXT
212
+ * `startPlan()` (closing the PRIOR plan before opening a new one),
213
+ * `close()`/`dispose()`, and `flushObservability()` — so the in-flight
214
+ * plan trace always ships before the process exits or a new plan begins.
215
+ */
216
+ private endPlanTrace;
217
+ private reanchorCall;
218
+ private getIntentTokenCall;
123
219
  startPlan(toolCalls: ToolCallInput[], goal?: string): Promise<IntentToken>;
124
- enforceLocal(toolName: string, toolArgs: Record<string, unknown>): EnforceResult;
125
- enforceSdk(toolName: string, toolArgs: Record<string, unknown>, userEmail?: string): Promise<EnforceResult>;
126
- enforce(toolName: string, toolArgs: Record<string, unknown>): Promise<EnforceResult>;
220
+ private _startPlanImpl;
221
+ /**
222
+ * `parentContainerSpanId` is an internal-only hook (not part of the public
223
+ * signature contract other SDK consumers rely on — it's simply an extra
224
+ * optional trailing arg) so `check()` can nest this call's container span
225
+ * under `iap.check`'s own container span instead of both sitting as
226
+ * siblings directly under the plan trace (Task 3 risk: "check → enforce
227
+ * double-open" — `iap.check`'s span wraps the dispatched enforce span,
228
+ * it never opens a second redundant plan trace or duplicate container).
229
+ */
230
+ enforceLocal(toolName: string, toolArgs: Record<string, unknown>, parentContainerSpanId?: string | null): EnforceResult;
231
+ private _enforceLocalImpl;
232
+ private _emitEnforcePolicyCall;
233
+ /** See `enforceLocal`'s doc comment re: `parentContainerSpanId` (internal-only hook for `check()`). */
234
+ enforceSdk(toolName: string, toolArgs: Record<string, unknown>, userEmail?: string, parentContainerSpanId?: string | null): Promise<EnforceResult>;
235
+ private _enforceSdkImpl;
236
+ /** See `enforceLocal`'s doc comment re: `parentContainerSpanId` (internal-only hook for `check()`). */
237
+ enforce(toolName: string, toolArgs: Record<string, unknown>, parentContainerSpanId?: string | null): Promise<EnforceResult>;
238
+ private _enforceImpl;
127
239
  check(toolName: string, toolArgs: Record<string, unknown>, userEmail?: string): Promise<EnforceResult>;
128
240
  report(toolName: string, toolArgs: Record<string, unknown>, result: unknown, opts?: ReportOptions): Promise<void>;
129
241
  dispatch(toolName: string, toolArgs: Record<string, unknown>): Promise<unknown>;
@@ -162,6 +274,39 @@ export declare class ArmorIQSession {
162
274
  }>;
163
275
  get currentTokenValue(): IntentToken | undefined;
164
276
  get currentMode(): SessionMode;
277
+ /**
278
+ * Force-flush all buffered observability traces/spans to the backend ingest
279
+ * endpoint. No-op when observability is disabled (`observability.enabled: false`).
280
+ *
281
+ * Call this at the request boundary (e.g. Stop hook in armorClaude, end of
282
+ * turn in ADK consumers) to guarantee all spans for the current session have
283
+ * been POSTed before the process exits. The underlying shipper retries with
284
+ * exponential backoff and **never throws** into the SDK consumer — a flush
285
+ * failure is logged and the spans are dropped.
286
+ */
287
+ flushObservability(): Promise<void>;
288
+ /**
289
+ * Stop the session's observability lifecycle: clears the shipper's
290
+ * repeating flush interval (`setInterval`, see `ObservabilityShipper`) and
291
+ * performs one final drain/flush of anything still queued. Safe to call
292
+ * multiple times; a no-op when observability is disabled.
293
+ *
294
+ * **Required at session end.** Without calling this, the recorder's
295
+ * shipper keeps its interval timer alive indefinitely — in long-running
296
+ * processes this is a resource leak, and in tests it is why processes
297
+ * (and jest) can hang or emit "cannot log after tests done" / stray
298
+ * network activity after teardown. `flushObservability()` alone does NOT
299
+ * stop the interval — it only flushes; call `close()` (or `dispose()`) at
300
+ * the natural end of the session's lifetime (e.g. Stop hook in armorClaude,
301
+ * end of process, or end of a request/turn in ADK consumers) instead of
302
+ * (or in addition to) `flushObservability()`.
303
+ *
304
+ * NEVER throws — observability teardown failures must not propagate into
305
+ * the SDK consumer, matching every other observability code path.
306
+ */
307
+ close(): Promise<void>;
308
+ /** Alias for `close()`. Use whichever reads better at the call site. */
309
+ dispose(): Promise<void>;
165
310
  }
166
311
  export {};
167
312
  //# sourceMappingURL=session.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"session.d.ts","sourceRoot":"","sources":["../src/session.ts"],"names":[],"mappings":"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"}
1
+ {"version":3,"file":"session.d.ts","sourceRoot":"","sources":["../src/session.ts"],"names":[],"mappings":"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"}