@armoriq/sdk-dev 0.6.8 → 0.7.0

package/README.md

@@ -88,7 +88,7 @@ USER_ID=your-user-id
 AGENT_ID=your-agent-id
 
 # Optional
-ARMORIQ_ENV=production  # or 'development' for local
+ARMORIQ_ENV=production  # or 'local' for local development
 CONTEXT_ID=default
 IAP_ENDPOINT=https://iap.armoriq.ai
 PROXY_ENDPOINT=https://proxy.armoriq.ai
@@ -97,6 +97,167 @@ BACKEND_ENDPOINT=https://api.armoriq.ai
 
 ---
 
+## Native OpenTelemetry observability
+
+Version 0.7.0 has one native OpenTelemetry span tree per session. It supports
+exactly three exporter choices. Organization policy still governs every choice;
+when observability is off or policy authority is unavailable, the SDK does not
+export telemetry and agent execution continues.
+
+### 1. ArmorIQ OTLP
+
+ArmorIQ OTLP is the default. No endpoint configuration is needed.
+
+```typescript
+const session = client.startSession({ mode: 'sdk' });
+```
+
+### 2. Generic external OTLP endpoint
+
+Use a standards-compatible HTTP/protobuf endpoint through options or standard
+OpenTelemetry environment variables.
+
+```typescript
+const client = new ArmorIQClient({
+  apiKey: 'ak_your_key_here',
+  observability: {
+    exporter: 'external',
+    endpoint: 'https://collector.example.com/v1/traces',
+    headers: { Authorization: 'Bearer token' },
+  },
+});
+```
+
+```bash
+OTEL_SERVICE_NAME=my-agent
+OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=https://observability.example.com/v1/traces
+OTEL_EXPORTER_OTLP_TRACES_HEADERS=Authorization=Bearer%20token,x-tenant-id=my-tenant
+```
+
+You can instead supply a base endpoint. The SDK appends `/v1/traces` only for
+this base form:
+
+```bash
+OTEL_EXPORTER_OTLP_ENDPOINT=https://collector.example.com
+OTEL_EXPORTER_OTLP_HEADERS=Authorization=Bearer%20token
+```
+
+Trace-specific settings take precedence over general settings:
+
+```text
+OTEL_EXPORTER_OTLP_TRACES_ENDPOINT > OTEL_EXPORTER_OTLP_ENDPOINT
+OTEL_EXPORTER_OTLP_TRACES_HEADERS  > OTEL_EXPORTER_OTLP_HEADERS
+OTEL_EXPORTER_OTLP_TRACES_PROTOCOL > OTEL_EXPORTER_OTLP_PROTOCOL
+OTEL_EXPORTER_OTLP_TRACES_TIMEOUT  > OTEL_EXPORTER_OTLP_TIMEOUT
+```
+
+### 3. Caller-owned tracer provider
+
+Pass your own OpenTelemetry tracer provider when your application owns provider
+lifecycle and exporter setup.
+
+```typescript
+import { NodeTracerProvider } from '@opentelemetry/sdk-trace-node';
+
+const provider = new NodeTracerProvider();
+const session = client.startSession({
+  observability: { exporter: 'provider', tracerProvider: provider },
+});
+```
+
+Only `http/protobuf` is supported for the SDK-managed external exporter. gRPC,
+OTLP/JSON, compression, HTTP proxy configuration, and mTLS configuration are
+not supported by that exporter.
+Set those features on an OpenTelemetry Collector when they are required. The
+exporter is fail-open: a remote outage, bad response, or timeout never changes
+the result of an agent request. `content-type` headers are ignored because the
+SDK always sends `application/x-protobuf`.
+
+Before the first external trace, the SDK waits up to 1.4 seconds for the
+organization policy authority. This one-time bound prevents unauthorized data
+from reaching a third party. If authority is not available within the bound,
+external telemetry stays disabled for that session and the agent continues.
+
+One SDK runtime has one exporter choice. For fan-out to ArmorIQ and external
+tools, use an OpenTelemetry Collector to route permitted traces.
+
+### Langfuse example
+
+Langfuse is one OTLP-compatible destination. Configure its OTLP endpoint and
+standard headers in the environment; do not add Langfuse-specific runtime code
+to your agent:
+
+```bash
+OTEL_SERVICE_NAME=my-agent
+OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=https://cloud.langfuse.com/api/public/otel/v1/traces
+OTEL_EXPORTER_OTLP_TRACES_HEADERS=Authorization=Basic%20BASE64_PUBLIC_KEY_COLON_SECRET_KEY,x-langfuse-ingestion-version=4
+```
+
+For another vendor, use that vendor's documented OTLP trace endpoint and
+headers. The SDK does not infer vendor URLs, credentials, or private fields.
+
+### What is exported externally
+
+External OTLP export always includes the trace hierarchy, stable span names,
+service identity, supported GenAI model and token-use attributes, and safe
+resource attributes. API keys, policy payloads, private ArmorIQ IDs, and
+arbitrary user metadata are never exported to an external destination.
+
+Prompt content, outputs, and tool arguments/results are withheld by default.
+They are exported to an external destination only when the organization's
+policy lease grants both content capture and external content capture, and
+the effective capture mode is `enhanced` or `debug` — every other combination
+(including a policy fetch that is not currently authoritative) withholds
+them. Do not rely on external export being content-free by default if your
+organization runs with those grants and capture modes enabled; check your
+organization's observability policy if that guarantee matters to you.
+
+Supported safe resource attributes are:
+
+```bash
+OTEL_SERVICE_NAME=my-agent
+OTEL_RESOURCE_ATTRIBUTES=service.namespace=education,deployment.environment.name=staging
+```
+
+Do not put secrets or user content in resource attributes. Unsupported resource
+attributes, malformed attributes, and values that look like a phone number,
+SSN, or payment-card number are ignored before export.
+
+### Capture modes and per-session opt-out
+
+The capture modes are exactly `off`, `metadata`, `enhanced`, and `debug`.
+Select an upper bound with `ARMORIQ_OTEL_CAPTURE_MODE` or
+`observability.captureMode`; the organization policy can only narrow it.
+
+```typescript
+const noTelemetrySession = client.startSession({
+  observability: { enabled: false },
+});
+```
+
+### Transcript token usage
+
+Pass the session's native OTel bridge when you record transcript usage so model
+tokens and cost become `gen_ai.chat` spans on the same trace.
+
+```typescript
+await client.captureTranscriptTokens({
+  transcriptPath: '/tmp/transcript.jsonl',
+  product: 'armorclaude',
+  sessionId: session.sessionId,
+  otel: session.otelSession,
+});
+```
+
+### 0.7.0 breaking changes
+
+The prior pipeline selector, JSON recorder and shipper APIs, recorder handles,
+schema and trace-summary exports, and `defaultObservabilityConfig` are removed.
+Use `session.otelSession` for native spans. See the 0.7.0 breaking-change notes
+in [CHANGELOG.md](CHANGELOG.md) for the complete removed public surface.
+
+---
+
 ## Advanced Usage
 
 ### Delegation
@@ -189,6 +350,12 @@ interface SDKConfig {
 
 For complete documentation, visit [docs.armoriq.ai](https://docs.armoriq.ai)
 
+For native framework adapter versions, lifecycle hooks, callback chaining, and
+known limits, see the [framework compatibility matrix](docs/integrations/compatibility-matrix.md).
+
+For the OTLP-only 0.7.0 release sequence, see the
+[release runbook](docs/release-0.7.0-otlp-only.md).
+
 ---
 
 ## Links

package/dist/_version.d.ts

@@ -8,5 +8,5 @@
  * Must match `version` in package.json and the locked version in
  * package-lock.json. tests/package_metadata.test.ts enforces they agree.
  */
-export declare const VERSION = "0.6.8";
+export declare const VERSION = "0.7.0";
 //# sourceMappingURL=_version.d.ts.map

package/dist/_version.js

@@ -11,5 +11,5 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.VERSION = void 0;
-exports.VERSION = '0.6.8';
+exports.VERSION = '0.7.0';
 //# sourceMappingURL=_version.js.map

package/dist/cli/commands/auth.d.ts

@@ -6,6 +6,17 @@
  * local callback with the key, or — if the callback can't be reached —
  * we fall back to polling /auth/device/token.
  */
+import * as fs from 'fs';
+type DeviceIdentityFs = Pick<typeof fs, 'readFileSync' | 'mkdirSync' | 'writeFileSync' | 'unlinkSync' | 'linkSync' | 'statSync' | 'openSync' | 'writeSync' | 'fsyncSync' | 'closeSync'>;
+/**
+ * The installation's stable, opaque device id, or null when it could not be
+ * persisted.
+ *
+ * Null rather than an unpersisted UUID: a value that is not on disk differs on
+ * every login, and the backend keys per-device key rotation on it, so returning
+ * one would provision a new key each time for what is one installation.
+ */
+export declare function loadOrCreateDeviceId(identityFs?: DeviceIdentityFs): string | null;
 export declare function cmdLogin(args: {
     backend?: string;
     org?: string;
@@ -14,4 +25,5 @@ export declare function cmdLogin(args: {
 }): Promise<number>;
 export declare function cmdLogout(): number;
 export declare function cmdWhoami(): number;
+export {};
 //# sourceMappingURL=auth.d.ts.map

package/dist/cli/commands/auth.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/auth.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAiPH,wBAAsB,QAAQ,CAAC,IAAI,EAAE;IACnC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB,GAAG,OAAO,CAAC,MAAM,CAAC,CAkIlB;AAED,wBAAgB,SAAS,IAAI,MAAM,CAOlC;AAED,wBAAgB,SAAS,IAAI,MAAM,CAkBlC"}
+{"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/auth.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,KAAK,EAAE,MAAM,IAAI,CAAC;AAkCzB,KAAK,gBAAgB,GAAG,IAAI,CAC1B,OAAO,EAAE,EACP,cAAc,GACd,WAAW,GACX,eAAe,GACf,YAAY,GACZ,UAAU,GACV,UAAU,GACV,UAAU,GACV,WAAW,GACX,WAAW,GACX,WAAW,CACd,CAAC;AAqHF;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAAC,UAAU,GAAE,gBAAqB,GAAG,MAAM,GAAG,IAAI,CAkCrF;AA2bD,wBAAsB,QAAQ,CAAC,IAAI,EAAE;IACnC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB,GAAG,OAAO,CAAC,MAAM,CAAC,CAoNlB;AAED,wBAAgB,SAAS,IAAI,MAAM,CAOlC;AAED,wBAAgB,SAAS,IAAI,MAAM,CAkBlC"}