@armoriq/sdk-dev 0.6.2 → 0.6.5

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 (63) hide show
  1. package/dist/cli/commands/auth.d.ts.map +1 -1
  2. package/dist/cli/commands/auth.js +18 -3
  3. package/dist/cli/commands/auth.js.map +1 -1
  4. package/dist/cli/index.js +0 -0
  5. package/dist/client.d.ts +35 -0
  6. package/dist/client.d.ts.map +1 -1
  7. package/dist/client.js +77 -1
  8. package/dist/client.js.map +1 -1
  9. package/dist/config.d.ts +17 -0
  10. package/dist/config.d.ts.map +1 -1
  11. package/dist/config.js +19 -1
  12. package/dist/config.js.map +1 -1
  13. package/dist/crypto_verify.d.ts +3 -0
  14. package/dist/crypto_verify.d.ts.map +1 -1
  15. package/dist/crypto_verify.js +77 -0
  16. package/dist/crypto_verify.js.map +1 -1
  17. package/dist/index.d.ts +4 -3
  18. package/dist/index.d.ts.map +1 -1
  19. package/dist/index.js +19 -3
  20. package/dist/index.js.map +1 -1
  21. package/dist/models.d.ts +17 -0
  22. package/dist/models.d.ts.map +1 -1
  23. package/dist/observability/handle.d.ts +41 -0
  24. package/dist/observability/handle.d.ts.map +1 -0
  25. package/dist/observability/handle.js +54 -0
  26. package/dist/observability/handle.js.map +1 -0
  27. package/dist/observability/index.d.ts +15 -0
  28. package/dist/observability/index.d.ts.map +1 -0
  29. package/dist/observability/index.js +39 -0
  30. package/dist/observability/index.js.map +1 -0
  31. package/dist/observability/model-prices.d.ts +39 -0
  32. package/dist/observability/model-prices.d.ts.map +1 -0
  33. package/dist/observability/model-prices.js +127 -0
  34. package/dist/observability/model-prices.js.map +1 -0
  35. package/dist/observability/recorder.d.ts +245 -0
  36. package/dist/observability/recorder.d.ts.map +1 -0
  37. package/dist/observability/recorder.js +475 -0
  38. package/dist/observability/recorder.js.map +1 -0
  39. package/dist/observability/schema.d.ts +163 -0
  40. package/dist/observability/schema.d.ts.map +1 -0
  41. package/dist/observability/schema.js +291 -0
  42. package/dist/observability/schema.js.map +1 -0
  43. package/dist/observability/shipper.d.ts +84 -0
  44. package/dist/observability/shipper.d.ts.map +1 -0
  45. package/dist/observability/shipper.js +206 -0
  46. package/dist/observability/shipper.js.map +1 -0
  47. package/dist/observability/trace-summary.d.ts +34 -0
  48. package/dist/observability/trace-summary.d.ts.map +1 -0
  49. package/dist/observability/trace-summary.js +108 -0
  50. package/dist/observability/trace-summary.js.map +1 -0
  51. package/dist/session.d.ts +148 -3
  52. package/dist/session.d.ts.map +1 -1
  53. package/dist/session.js +1035 -195
  54. package/dist/session.js.map +1 -1
  55. package/dist/token_usage.d.ts +18 -1
  56. package/dist/token_usage.d.ts.map +1 -1
  57. package/dist/token_usage.js +112 -2
  58. package/dist/token_usage.js.map +1 -1
  59. package/package.json +2 -1
  60. package/dist/integrations/google_adk_mcp_toolset.d.ts +0 -64
  61. package/dist/integrations/google_adk_mcp_toolset.d.ts.map +0 -1
  62. package/dist/integrations/google_adk_mcp_toolset.js +0 -91
  63. package/dist/integrations/google_adk_mcp_toolset.js.map +0 -1
@@ -0,0 +1,127 @@
1
+ "use strict";
2
+ /**
3
+ * Static per-model token cost table.
4
+ *
5
+ * Best-effort, NOT billing-grade. Prices reflect Anthropic and OpenAI public
6
+ * list prices as of 2026-07-15. Update this table via PR when list prices change;
7
+ * we do not auto-sync because a billing-grade number must be auditable and
8
+ * versioned.
9
+ *
10
+ * All prices are USD **per 1,000 tokens** (per-1k, not per-million). This
11
+ * matches the precision the backend's `obs_spans.cost_usd` column keeps
12
+ * (Decimal(12, 6)) and avoids float drift on small numbers.
13
+ *
14
+ * Cache pricing:
15
+ * - Anthropic: separate `cacheReadPer1kUsd` (cache hit) and
16
+ * `cacheWritePer1kUsd` (cache creation, 5-minute TTL).
17
+ * - OpenAI: no first-class cache tokens; we approximate cache reads as
18
+ * 50% of the input price (matches OpenAI's "cached input" discount).
19
+ * Cache writes are charged as regular input.
20
+ */
21
+ Object.defineProperty(exports, "__esModule", { value: true });
22
+ exports.MODEL_PRICES = void 0;
23
+ exports.computeCostUsd = computeCostUsd;
24
+ exports.MODEL_PRICES = {
25
+ // Anthropic Claude 4 family (claude-sonnet-4-20250514: $3 in / $15 out per MTok)
26
+ 'claude-sonnet-4-20250514': {
27
+ inputPer1kUsd: 0.003,
28
+ outputPer1kUsd: 0.015,
29
+ cacheReadPer1kUsd: 0.0003,
30
+ cacheWritePer1kUsd: 0.00375,
31
+ },
32
+ 'claude-opus-4-20250514': {
33
+ inputPer1kUsd: 0.015,
34
+ outputPer1kUsd: 0.075,
35
+ cacheReadPer1kUsd: 0.0015,
36
+ cacheWritePer1kUsd: 0.01875,
37
+ },
38
+ 'claude-haiku-4-20250514': {
39
+ inputPer1kUsd: 0.001,
40
+ outputPer1kUsd: 0.005,
41
+ cacheReadPer1kUsd: 0.0001,
42
+ cacheWritePer1kUsd: 0.00125,
43
+ },
44
+ // Anthropic Claude 5 family (same tier list prices as the 4 family:
45
+ // Sonnet $3 in / $15 out, Opus $15 / $75, Haiku $1 / $5 per MTok).
46
+ 'claude-sonnet-5': {
47
+ inputPer1kUsd: 0.003,
48
+ outputPer1kUsd: 0.015,
49
+ cacheReadPer1kUsd: 0.0003,
50
+ cacheWritePer1kUsd: 0.00375,
51
+ },
52
+ 'claude-opus-4-8': {
53
+ inputPer1kUsd: 0.015,
54
+ outputPer1kUsd: 0.075,
55
+ cacheReadPer1kUsd: 0.0015,
56
+ cacheWritePer1kUsd: 0.01875,
57
+ },
58
+ 'claude-haiku-4-5-20251001': {
59
+ inputPer1kUsd: 0.001,
60
+ outputPer1kUsd: 0.005,
61
+ cacheReadPer1kUsd: 0.0001,
62
+ cacheWritePer1kUsd: 0.00125,
63
+ },
64
+ 'claude-haiku-4-5': {
65
+ inputPer1kUsd: 0.001,
66
+ outputPer1kUsd: 0.005,
67
+ cacheReadPer1kUsd: 0.0001,
68
+ cacheWritePer1kUsd: 0.00125,
69
+ },
70
+ // OpenAI GPT-5.6 Standard, short context:
71
+ // https://developers.openai.com/api/docs/pricing
72
+ 'gpt-5.6-sol': {
73
+ inputPer1kUsd: 0.005,
74
+ outputPer1kUsd: 0.03,
75
+ cacheReadPer1kUsd: 0.0005,
76
+ cacheWritePer1kUsd: 0.00625,
77
+ },
78
+ // OpenAI GPT-4o family
79
+ 'gpt-4o': {
80
+ inputPer1kUsd: 0.0025,
81
+ outputPer1kUsd: 0.01,
82
+ cacheReadPer1kUsd: 0.00125,
83
+ cacheWritePer1kUsd: 0.0025,
84
+ },
85
+ 'gpt-4o-mini': {
86
+ inputPer1kUsd: 0.00015,
87
+ outputPer1kUsd: 0.0006,
88
+ cacheReadPer1kUsd: 0.000075,
89
+ cacheWritePer1kUsd: 0.00015,
90
+ },
91
+ // OpenAI GPT-4.1 family
92
+ 'gpt-4.1': {
93
+ inputPer1kUsd: 0.002,
94
+ outputPer1kUsd: 0.008,
95
+ cacheReadPer1kUsd: 0.001,
96
+ cacheWritePer1kUsd: 0.002,
97
+ },
98
+ 'gpt-4.1-mini': {
99
+ inputPer1kUsd: 0.0004,
100
+ outputPer1kUsd: 0.0016,
101
+ cacheReadPer1kUsd: 0.0002,
102
+ cacheWritePer1kUsd: 0.0004,
103
+ },
104
+ };
105
+ /**
106
+ * Compute the USD cost of an LLM call given token counts.
107
+ *
108
+ * Unknown models return 0 (no pricing data) — the span still records the
109
+ * tokens; the cost field is just `0` instead of estimated. This keeps the
110
+ * aggregator safe when a new model is added before the price table is
111
+ * updated.
112
+ *
113
+ * Returns a non-negative number, rounded to 6 decimal places to match the
114
+ * backend's `obs_spans.cost_usd` column precision.
115
+ */
116
+ function computeCostUsd(model, inputTokens, outputTokens, cacheReadTokens = 0, cacheWriteTokens = 0) {
117
+ const price = exports.MODEL_PRICES[model];
118
+ if (!price)
119
+ return 0;
120
+ const safe = (n) => (Number.isFinite(n) && n > 0 ? n : 0);
121
+ const cost = (safe(inputTokens) / 1000) * price.inputPer1kUsd +
122
+ (safe(outputTokens) / 1000) * price.outputPer1kUsd +
123
+ (safe(cacheReadTokens) / 1000) * price.cacheReadPer1kUsd +
124
+ (safe(cacheWriteTokens) / 1000) * price.cacheWritePer1kUsd;
125
+ return Math.round(cost * 1_000_000) / 1_000_000;
126
+ }
127
+ //# sourceMappingURL=model-prices.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"model-prices.js","sourceRoot":"","sources":["../../src/observability/model-prices.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,245 @@
1
+ /**
2
+ * ObservabilityRecorder — in-memory ring buffer for traces + spans.
3
+ *
4
+ * The recorder is the only place in the SDK that mints trace/span IDs. The
5
+ * session chokepoints (peer subagent's wrap) call `startTrace` /
6
+ * `recordPolicyCall` / `endTrace` and the recorder takes care of:
7
+ * 1. Validating each emit (cheap shape checks; bad data is logged + dropped,
8
+ * never thrown into the SDK consumer).
9
+ * 2. Minting IDs and computing endTime/durationMs.
10
+ * 3. Holding the in-memory ring buffer (default 1000 traces). On overflow,
11
+ * the oldest trace AND all its spans are dropped (we never want a partial
12
+ * trace at the backend).
13
+ * 4. Pushing ended traces onto the shipper's queue.
14
+ * 5. Forwarding every emit to the test sink (if set) so tests can assert
15
+ * on the exact lifecycle.
16
+ *
17
+ * Per plan §9 Q3: in-memory only. `durable: true` is parsed and stored but
18
+ * does nothing in v1 — a one-time warning is logged the first time a
19
+ * consumer opts in.
20
+ */
21
+ import { AxiosInstance } from 'axios';
22
+ import { ObservabilityShipper } from './shipper';
23
+ import { type SpanRecord, type SpanStatus, type TraceContext, type TraceRecord } from './schema';
24
+ export interface ObservabilityConfig {
25
+ /** Master kill switch. Default: true. */
26
+ enabled: boolean;
27
+ /** Full URL of the ingest endpoint, e.g. https://api.armoriq.ai/observability/spans. */
28
+ endpoint: string;
29
+ /** API key used in the X-API-Key header. */
30
+ apiKey: string;
31
+ /** Product tag sent with every ingest payload (e.g. 'armorclaude'). */
32
+ product: string;
33
+ /**
34
+ * Default session id applied to every trace started on this recorder when
35
+ * the caller doesn't pass an explicit `sessionId` to `startTrace()`. This
36
+ * is how `ArmorIQSession` stamps ITS one stable (UUID) session id onto
37
+ * every trace uniformly, without every chokepoint having to pass it
38
+ * explicitly. Must be a valid UUID or `null` — the backend's
39
+ * `obs_sessions.id` column is a UUID column, so a non-UUID value can never
40
+ * form a session.
41
+ */
42
+ sessionId?: string | null;
43
+ /** SDK user id (denormalized onto every trace). May be null for multi-user flows. */
44
+ userId?: string | null;
45
+ /** SDK agent id (denormalized onto every trace). May be null for multi-user flows. */
46
+ agentId?: string | null;
47
+ /** Override the SDK's HTTP client (axios instance). Used for tests. */
48
+ httpClient?: AxiosInstance;
49
+ /** Max traces in the in-memory ring buffer. Default 1000. */
50
+ maxBufferSize?: number;
51
+ /** Auto-flush interval (ms). Default 5000. */
52
+ flushIntervalMs?: number;
53
+ /**
54
+ * Max batches per ingest POST. Default 100. The shipper chunks the queue
55
+ * into groups of at most this size at flush time, so a burst of traces
56
+ * never sends a single unbounded giant POST.
57
+ */
58
+ batchSize?: number;
59
+ /** Optional onSpan hook. Called for every span after it's validated. */
60
+ onSpan?: (span: SpanRecord) => void;
61
+ /** Disk-backed WAL opt-in. Parsed and stored; unused in v1. */
62
+ durable?: boolean;
63
+ /** Data dir for the future WAL. Stored; unused in v1. */
64
+ dataDir?: string;
65
+ }
66
+ export type SinkEvent = {
67
+ kind: 'trace_started';
68
+ trace: TraceRecord;
69
+ sessionId: string | null;
70
+ } | {
71
+ kind: 'span_recorded';
72
+ traceId: string;
73
+ traceSessionId: string | null;
74
+ span: SpanRecord;
75
+ } | {
76
+ kind: 'trace_ended';
77
+ trace: TraceRecord;
78
+ spans: SpanRecord[];
79
+ };
80
+ export type ObservabilitySink = (event: SinkEvent) => void;
81
+ export declare function __setObservabilitySinkForTests(sink: ObservabilitySink | null): void;
82
+ export declare class ObservabilityRecorder {
83
+ private readonly enabled;
84
+ private readonly product;
85
+ private readonly userId;
86
+ private readonly agentId;
87
+ private readonly defaultSessionId;
88
+ private readonly maxBufferSize;
89
+ private readonly onSpan?;
90
+ private readonly buffer;
91
+ private readonly bufferIndex;
92
+ private readonly shipper;
93
+ private warnedDurable;
94
+ constructor(config: ObservabilityConfig);
95
+ /** Internal accessor for tests; not part of the public API. */
96
+ get __shipper(): ObservabilityShipper;
97
+ /** True when the consumer passed `enabled: true` (the default). */
98
+ get isEnabled(): boolean;
99
+ /**
100
+ * Mint a new trace and return its context. The trace is added to the
101
+ * in-memory buffer (dropping the oldest if at capacity) and the context
102
+ * is passed to subsequent `recordSpan` / `endTrace` calls.
103
+ */
104
+ startTrace(name: string, attributes?: Record<string, unknown>, sessionId?: string | null): TraceContext;
105
+ /**
106
+ * Append a span to an existing trace. The span is validated against the
107
+ * wire schema; an invalid span is logged and dropped (never thrown).
108
+ */
109
+ recordSpan(ctx: TraceContext, span: SpanRecord): void;
110
+ /**
111
+ * Construct a `kind: 'policy_call'` span from the supplied fields and
112
+ * record it under the given trace. Returns the constructed span (useful
113
+ * for tests); otherwise the return value can be ignored.
114
+ */
115
+ recordPolicyCall(ctx: TraceContext, attrs: {
116
+ policyId: string | null;
117
+ policyName: string | null;
118
+ decision: 'allow' | 'deny' | 'hold' | 'ask';
119
+ reason: string | null;
120
+ source: 'native' | 'sdk-local' | 'sdk' | 'proxy' | 'opa' | 'opa_fallback';
121
+ input: unknown;
122
+ output: unknown;
123
+ policyHash?: string | null;
124
+ policyVersion?: string | null;
125
+ matchedRuleId?: string | null;
126
+ dataClasses?: string[];
127
+ enforcementAction?: 'allow' | 'allow_log' | 'hold' | 'block' | null;
128
+ obligations?: unknown;
129
+ delegationId?: string | null;
130
+ durationMs?: number | null;
131
+ }, parentSpanId?: string | null): SpanRecord;
132
+ /**
133
+ * Construct a `kind: 'generation'` span from the supplied fields,
134
+ * compute `costUsd` from the static price table, and record it.
135
+ * Unknown models yield costUsd=0 (the span is still recorded).
136
+ * Pass `costUsd` to override the computed value (e.g. when the caller
137
+ * already has a precomputed cost from a third-party billing system).
138
+ */
139
+ recordGeneration(ctx: TraceContext, attrs: {
140
+ model: string;
141
+ inputTokens: number;
142
+ outputTokens: number;
143
+ cacheReadTokens?: number | null;
144
+ cacheWriteTokens?: number | null;
145
+ prompt?: string | null;
146
+ completion?: string | null;
147
+ finishReason?: string | null;
148
+ costUsd?: number | null;
149
+ }, parentSpanId?: string | null): SpanRecord;
150
+ /**
151
+ * Record a `kind: 'event'` span — a point-in-time annotation (e.g.
152
+ * "plan growth", "approval polled"). Use sparingly; events are cheap
153
+ * but they still count toward the ring buffer.
154
+ */
155
+ recordEvent(ctx: TraceContext, attrs: {
156
+ message: string;
157
+ level?: 'info' | 'warn' | 'error';
158
+ }, parentSpanId?: string | null): SpanRecord;
159
+ /**
160
+ * Mint + record a `kind: 'span'` CONTAINER span — a nesting point that
161
+ * groups the child spans emitted by one chokepoint (e.g. `iap.enforce.local`)
162
+ * under the session's single active plan trace (Model A: trace-per-plan).
163
+ *
164
+ * The container starts open (`status: 'ok'`, `endTime: null`,
165
+ * `durationMs: null`) and MUST be finalized with `closeSpan()` once the
166
+ * chokepoint's work completes (success or error). A container span with a
167
+ * null `endTime` is intentionally valid mid-flight — see
168
+ * `isValidGenericSpanAttributes`/`isValidSpanRecord`, which permit a
169
+ * null `endTime`/`durationMs` for exactly this reason (Task 1 risk #1).
170
+ *
171
+ * Returns the minted span id — even when the recorder is disabled, so
172
+ * call sites can pass it along unconditionally as a `parentSpanId` to
173
+ * `recordPolicyCall`/`recordGeneration`/`recordEvent` without special-casing
174
+ * the disabled path.
175
+ */
176
+ openSpan(ctx: TraceContext, opts: {
177
+ name: string;
178
+ attributes?: Record<string, unknown>;
179
+ parentSpanId?: string | null;
180
+ }): string;
181
+ /**
182
+ * Finalize a container span previously opened with `openSpan()`: sets
183
+ * `endTime`, optionally `durationMs`/`status`/`attributes.errorMessage`.
184
+ * No-op (never throws) when the recorder is disabled, the trace is
185
+ * unknown, or the spanId doesn't match a buffered span (e.g. it already
186
+ * shipped) — mirrors `endTrace`'s defensive lookup.
187
+ */
188
+ closeSpan(ctx: TraceContext, spanId: string, opts?: {
189
+ status?: SpanStatus;
190
+ durationMs?: number;
191
+ errorMessage?: string;
192
+ }): void;
193
+ /**
194
+ * Finalize a trace: set endTime, compute durationMs, apply optional
195
+ * status / errorMessage. Pushes the (trace, spans) batch to the
196
+ * shipper's queue, then REMOVES the entry from the in-memory ring buffer
197
+ * — once a trace has been handed to the shipper, the shipper's own queue
198
+ * is the durable record; keeping a second copy in the ring buffer would
199
+ * let ended/shipped traces occupy buffer slots until overflow/flush,
200
+ * needlessly evicting still-in-flight traces sooner. No-op when disabled
201
+ * or when the trace is unknown.
202
+ */
203
+ endTrace(ctx: TraceContext, opts?: {
204
+ status?: 'ok' | 'error' | 'denied';
205
+ errorMessage?: string;
206
+ }): void;
207
+ /**
208
+ * Drain the in-memory buffer. Returns a readonly array of the current
209
+ * (trace, spans) pairs. The buffer is NOT cleared by this call — that
210
+ * is `flush()`'s job. `drain()` is for inspection (tests, debugging).
211
+ *
212
+ * Note: since `endTrace()` removes entries once they're handed to the
213
+ * shipper (see #8), `drain()` only ever reflects traces that are still
214
+ * in-flight (started but not yet ended).
215
+ */
216
+ drain(): ReadonlyArray<{
217
+ trace: TraceRecord;
218
+ spans: SpanRecord[];
219
+ }>;
220
+ /**
221
+ * POST any queued (ended) batches via the shipper. Returns the shipper's
222
+ * accepted/rejected counts. NEVER throws — observability failures must
223
+ * not break the SDK consumer.
224
+ *
225
+ * Only ended traces (`trace.endTime !== null`) are ever handed to the
226
+ * shipper (see `endTrace()`); in-flight (un-ended) traces stay in the
227
+ * in-memory ring buffer untouched — flushing must never drop a trace
228
+ * that's still being built. As an extra safety net (in case some future
229
+ * caller enqueues directly), any buffer entries whose trace happens to
230
+ * already carry an `endTime` are also handed to the shipper and removed
231
+ * here; anything without an `endTime` is left alone and a warning is
232
+ * logged with the retained count.
233
+ */
234
+ flush(): Promise<{
235
+ accepted: number;
236
+ rejected: number;
237
+ }>;
238
+ /**
239
+ * Stop the underlying shipper (clears the periodic interval + final
240
+ * flush). Call on session close. Safe to call multiple times.
241
+ */
242
+ stop(): Promise<void>;
243
+ private appendToBuffer;
244
+ }
245
+ //# sourceMappingURL=recorder.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"recorder.d.ts","sourceRoot":"","sources":["../../src/observability/recorder.ts"],"names":[],"mappings":"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"}