agentfootprint 9.7.0 → 9.8.0

package/dist/esm/adapters/observability/file.js

@@ -0,0 +1,303 @@
+/**
+ * fileObservability — the typed event stream, one JSON line per event, in a
+ * local file.
+ *
+ * The sink for the shop that has no collector. Every other adapter in this
+ * folder ships somewhere: CloudWatch, X-Ray, an OTLP endpoint. A great many
+ * on-premises deployments have none of those — they have a directory, a log
+ * shipper (Filebeat, Fluent Bit, Vector, `promtail`, `journald`, or a person
+ * with `grep`), and a rule that nothing leaves the network. NDJSON on disk is
+ * the format all of those already read, so the sink is the file.
+ *
+ * Zero dependencies: `node:fs`, lazily required at construction so merely
+ * importing `agentfootprint/observe` stays browser-safe (this factory is
+ * Node-only; calling it in a browser throws by name).
+ *
+ * ## The line
+ *
+ * One `JSON.stringify(event)` per line, newline-terminated, appended in
+ * dispatch order — the SAME envelope `cloudwatchObservability` puts in a log
+ * event, so a query written against one reads the other:
+ *
+ * ```jsonl
+ * {"type":"agentfootprint.agent.turn_start","payload":{…},"meta":{"runId":"…","sessionId":"…"}}
+ * {"type":"agentfootprint.stream.tool_end","payload":{…},"meta":{…}}
+ * ```
+ *
+ * Nothing is summarized, bounded or redacted on the way out. **A payload that
+ * must not be on that disk must not reach this strategy** — narrow it with
+ * `eventTypes` / `tier` / `sampleRate`, or apply a footprintjs
+ * `RedactionPolicy` upstream, exactly as with every other sink. (For a bounded
+ * record by construction, `auditExport({ payloadMode: 'bounded' })` is the
+ * adapter that does that job.)
+ *
+ * ## Buffered, not synchronous
+ *
+ * `exportEvent` is sync and never touches the disk: it serializes, buffers, and
+ * returns. Batches are appended asynchronously on a size trigger
+ * (`maxBufferEvents` / `maxBufferBytes`), on a timer (`flushIntervalMs`), and on
+ * `flush()`. A hard kill therefore loses at most the buffer — the price of not
+ * making telemetry a term in agent-loop latency. Call `flush()` (or
+ * `agent.shutdown()`, which does) at process end; see the 8.12.0 lifecycle laws
+ * on {@link BaseStrategy.flush}.
+ *
+ * ## Rotation is ONE generation, and that is deliberate
+ *
+ * With `maxBytes` set, a batch that would push the file past the ceiling first
+ * renames it to `<path>.1` — **replacing any previous `.1`** — and starts a
+ * fresh file. That is the whole policy. There is no `.2`, no compression, no
+ * time-based schedule, no cross-process coordination (two processes writing one
+ * file each keep their own byte count and will both rotate it). It exists so an
+ * unattended agent cannot fill a disk, and for nothing else: **retention is a
+ * log-management daemon's job**, and `logrotate` with `copytruncate`, Fluent Bit,
+ * or a systemd timer will do it properly. Omit `maxBytes` — the default — and
+ * this adapter never renames anything, which is the right choice when a real
+ * rotator already owns the file.
+ *
+ * @example
+ * ```ts
+ * import { fileObservability } from 'agentfootprint/observe';
+ *
+ * const telemetry = agent.enable.observability({
+ *   strategy: fileObservability({
+ *     path: '/var/log/agentfootprint/events.ndjson',
+ *     maxBytes: 64 * 1024 * 1024,   // safety ceiling; logrotate owns retention
+ *   }),
+ * });
+ *
+ * // … run …
+ * await agent.shutdown();           // flushes + stops everything enabled
+ * ```
+ */
+import { lazyRequire } from '../../lib/lazyRequire.js';
+import { rateLimitedConsoleSink } from './deliveryErrors.js';
+// ─── Public factory ──────────────────────────────────────────────────
+/**
+ * NDJSON-to-a-local-file observability strategy. See
+ * {@link FileObservabilityOptions} for the per-option contract, and this
+ * module's docstring for the rotation policy and what is NOT bounded.
+ */
+export function fileObservability(opts) {
+    const strategyName = 'file';
+    if (!opts.path || typeof opts.path !== 'string' || opts.path.trim() === '') {
+        throw new TypeError(`[${strategyName}Observability] \`path\` is required — the file this sink writes. ` +
+            `Pass one, e.g. '/var/log/agentfootprint/events.ndjson'. There is no default: ` +
+            `where a run's telemetry lands on your disk is not a decision this library makes.`);
+    }
+    if (opts.maxBytes !== undefined && !(opts.maxBytes > 0)) {
+        throw new TypeError(`[${strategyName}Observability] \`maxBytes\` must be a positive number of bytes ` +
+            `(got ${String(opts.maxBytes)}). Omit it for no rotation at all, which is the ` +
+            `right choice when logrotate or a log shipper already owns '${opts.path}'.`);
+    }
+    const path = opts.path;
+    const rotatedPath = `${path}.1`;
+    const maxBufferEvents = opts.maxBufferEvents ?? 100;
+    const maxBufferBytes = opts.maxBufferBytes ?? 65_536;
+    const flushIntervalMs = opts.flushIntervalMs ?? 1000;
+    const fs = opts._fs ?? createNodeFileSink(strategyName);
+    // Claim the file NOW. Two things this buys, both worth the syscall:
+    //   1. an unwritable path (no directory, no permission, a directory where a
+    //      file should be, a read-only mount) is refused at construction, where
+    //      the caller can still read the message;
+    //   2. `statSync` below gives the rotation counter a true starting size, so a
+    //      restart appends to an existing file rather than believing it is empty.
+    let bytesOnDisk = 0;
+    try {
+        const dir = parentDir(path);
+        if (dir)
+            fs.mkdirSync(dir, { recursive: true });
+        fs.appendFileSync(path, '');
+        bytesOnDisk = fs.statSync(path).size;
+    }
+    catch (err) {
+        throw new Error(`[${strategyName}Observability] cannot write '${path}': ${errorMessage(err)}. ` +
+            `The parent directory is created for you; a failure here means the path is a ` +
+            `directory, the mount is read-only, or the process user lacks permission. ` +
+            `Fix the path or the permission — this sink refuses to start rather than ` +
+            `silently drop every event.`);
+    }
+    // Buffered lines — drained by `flush()` / size trigger / timer.
+    const buffer = [];
+    let bufferBytes = 0;
+    let lastFlushPromise = Promise.resolve();
+    let timer;
+    let stopped = false;
+    // The fallback when the consumer wires nothing. Rate-limited; a
+    // consumer-supplied sink is not.
+    const consoleSink = rateLimitedConsoleSink(strategyName);
+    function scheduleTimedFlush() {
+        if (timer || flushIntervalMs <= 0 || stopped)
+            return;
+        timer = setTimeout(() => {
+            timer = undefined;
+            void doFlush();
+        }, flushIntervalMs);
+        // Never hold the process open for telemetry. `unref` exists on Node's
+        // Timeout and not on the browser's number — feature-detected, so a
+        // non-Node runtime with an injected `_fs` still works.
+        timer.unref?.();
+    }
+    /** Route a delivery failure through whatever `_onError` IS RIGHT NOW —
+     *  reading it at call time, so a consumer who assigns `_onError` after
+     *  construction still receives them (the 8.11.0 fix). */
+    function reportFailure(err) {
+        strategy._onError?.(err);
+    }
+    /** ONE generation. A file already at or over the ceiling is renamed to
+     *  `<path>.1` (replacing any previous `.1`) and the counter resets. A batch
+     *  bigger than the whole ceiling is still written — truncating a run's
+     *  telemetry to fit a dial nobody set for that purpose would be worse. */
+    async function rotateIfNeeded(incomingBytes) {
+        const ceiling = opts.maxBytes;
+        if (ceiling === undefined)
+            return;
+        if (bytesOnDisk === 0)
+            return;
+        if (bytesOnDisk + incomingBytes <= ceiling)
+            return;
+        await fs.rename(path, rotatedPath);
+        bytesOnDisk = 0;
+    }
+    async function doFlush() {
+        // `stopped` is deliberately NOT a guard here — same stance as the AWS
+        // adapters since 8.11.1. `stop()` stops this strategy ACCEPTING events; it
+        // does not authorise throwing away events already accepted, and a `flush()`
+        // that cannot make progress after a `stop()` is how shutdown spins forever.
+        if (buffer.length === 0)
+            return;
+        // Snapshot + clear so events emitted during the in-flight write accumulate
+        // into the next batch.
+        const batch = buffer.splice(0);
+        const batchBytes = bufferBytes;
+        bufferBytes = 0;
+        const data = `${batch.join('\n')}\n`;
+        try {
+            await rotateIfNeeded(batchBytes);
+            await fs.appendFile(path, data);
+            bytesOnDisk += byteLength(data);
+        }
+        catch (err) {
+            reportFailure(new Error(`${batch.length} event(s) dropped writing to '${path}': ${errorMessage(err)}`));
+        }
+    }
+    function enqueue(event) {
+        if (stopped)
+            return;
+        // The hot path must not throw (port law). `JSON.stringify` can — a cycle, a
+        // BigInt, a throwing getter — and an event that cannot be serialized is a
+        // reportable fact, not a reason to break the agent loop.
+        let line;
+        try {
+            line = JSON.stringify(event);
+        }
+        catch (err) {
+            reportFailure(new Error(`event '${event?.type ?? 'unknown'}' could not be serialized: ` + errorMessage(err)));
+            return;
+        }
+        // `JSON.stringify` returns undefined for an undefined input — nothing to
+        // write, and a bare "undefined" line would corrupt the NDJSON stream.
+        if (line === undefined)
+            return;
+        buffer.push(line);
+        bufferBytes += byteLength(line) + 1; // + the newline this line will carry
+        if (buffer.length >= maxBufferEvents || bufferBytes >= maxBufferBytes) {
+            // Size trigger. Chain onto the last write rather than racing it — the
+            // file's line order IS the dispatch order, and that is the only thing an
+            // offline reader can rely on.
+            lastFlushPromise = lastFlushPromise.then(doFlush, doFlush);
+        }
+        else {
+            scheduleTimedFlush();
+        }
+    }
+    const strategy = {
+        name: strategyName,
+        capabilities: { events: true, logs: true },
+        ...(opts.eventTypes && { relevantEventTypes: opts.eventTypes }),
+        exportEvent: enqueue,
+        /**
+         * Write what is buffered. Called for you on shutdown (8.12.0) — by the
+         * handle `enable.observability()` returns, by `agent.shutdown()`, and by a
+         * `standingAgent` closing. Safe at any time, including after `stop()`.
+         */
+        async flush() {
+            // BOUNDED BY CONSTRUCTION — every pass must remove at least one buffered
+            // line; a pass that removes none ends the drain instead of retrying. The
+            // shape the CloudWatch adapter arrived at in 8.11.1, for the same reason:
+            // a drain that cannot finish must return, never spin.
+            for (;;) {
+                const pending = buffer.length;
+                lastFlushPromise = lastFlushPromise.then(doFlush, doFlush);
+                await lastFlushPromise;
+                if (buffer.length === 0)
+                    return;
+                if (buffer.length >= pending)
+                    return;
+            }
+        },
+        /** Clear the timer and stop accepting events. Terminal: there is no
+         *  restart. What it does NOT do is discard the buffer — `flush()` after
+         *  `stop()` still writes it. */
+        stop() {
+            stopped = true;
+            if (timer) {
+                clearTimeout(timer);
+                timer = undefined;
+            }
+        },
+        /** Where failures go. Two callers: the dispatch layer (when `exportEvent`
+         *  itself throws) and this adapter's own write path. */
+        _onError(err, event) {
+            (opts.onError ?? consoleSink)(err, event);
+        },
+    };
+    return strategy;
+}
+// ─── node:fs binding (lazy) ──────────────────────────────────────────
+/**
+ * Bind {@link FileSinkFs} to `node:fs`. Lazily required so that importing
+ * `agentfootprint/observe` in a browser bundle never resolves `node:fs` — only
+ * CALLING this factory does, and a runtime without it is refused by name.
+ */
+function createNodeFileSink(strategyName) {
+    let mod;
+    try {
+        mod = lazyRequire('node:fs');
+    }
+    catch {
+        throw new Error(`[${strategyName}Observability] needs \`node:fs\`, and this runtime has none. ` +
+            `It is a Node-only sink by definition — a browser has no local file to append to. ` +
+            `In a browser, ship events over your own transport, or pass \`_fs\` to write ` +
+            `somewhere you control.`);
+    }
+    return {
+        mkdirSync: (dir, options) => void mod.mkdirSync(dir, options),
+        appendFileSync: (file, data) => mod.appendFileSync(file, data),
+        statSync: (file) => mod.statSync(file),
+        appendFile: (file, data) => mod.promises.appendFile(file, data),
+        rename: (from, to) => mod.promises.rename(from, to),
+    };
+}
+// ─── Small helpers ───────────────────────────────────────────────────
+function errorMessage(err) {
+    return err instanceof Error ? err.message : String(err);
+}
+/** UTF-8 byte length. `Buffer` where there is one, `TextEncoder` otherwise —
+ *  the byte count decides rotation, so a multi-byte prompt must not be counted
+ *  as its character length. */
+function byteLength(s) {
+    const B = globalThis.Buffer;
+    if (B)
+        return B.byteLength(s, 'utf8');
+    return new TextEncoder().encode(s).length;
+}
+/** The directory part of a path, POSIX or Windows separators, or `''` for a
+ *  bare filename (nothing to create). Done by hand rather than through
+ *  `node:path` so the module has exactly one Node import, behind one seam. */
+function parentDir(file) {
+    const idx = Math.max(file.lastIndexOf('/'), file.lastIndexOf('\\'));
+    if (idx <= 0)
+        return '';
+    return file.slice(0, idx);
+}
+//# sourceMappingURL=file.js.map

package/dist/esm/adapters/observability/file.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"file.js","sourceRoot":"","sources":["../../../../src/adapters/observability/file.ts"],"names":[],"mappings":"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"}

package/dist/esm/identity.d.ts

@@ -35,3 +35,4 @@ export type { AuthorizationRequiredMode, ConsentRequest } from './identity/conse
 export { CredentialConsentRequiredError, type CredentialConsentRequiredContext, } from './identity/CredentialConsentRequiredError.js';
 export { withCredentialRetry, type WithCredentialRetryOptions, } from './identity/withCredentialRetry.js';
 export { agentCoreIdentity, type AgentCoreIdentityOptions, type AgentCoreIdentityClientLike, type AgentCoreOauthResponse, } from './adapters/identity/agentcore.js';
+export { vaultCredentials, type VaultCredentialsOptions } from './adapters/identity/vault.js';

package/dist/esm/identity.js

@@ -33,4 +33,8 @@ export { staticTokens } from './identity/staticTokens.js';
 export { CredentialConsentRequiredError, } from './identity/CredentialConsentRequiredError.js';
 export { withCredentialRetry, } from './identity/withCredentialRetry.js';
 export { agentCoreIdentity, } from './adapters/identity/agentcore.js';
+// HashiCorp-Vault-compatible KV v2, over plain HTTP (9.8.0) — no SDK, no
+// vendor client. V1 is token auth + KV v2 + no leases, and every other shape
+// is refused by name rather than guessed at; see the module docstring.
+export { vaultCredentials } from './adapters/identity/vault.js';
 //# sourceMappingURL=identity.js.map

package/dist/esm/identity.js.map

@@ -1 +1 @@
-{"version":3,"file":"identity.js","sourceRoot":"","sources":["../../src/identity.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAWH,OAAO,EAAE,kBAAkB,EAAE,8BAA8B,EAAE,MAAM,qBAAqB,CAAC;AACzF,OAAO,EACL,MAAM,EACN,MAAM,EACN,KAAK,EACL,OAAO,GAKR,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAE,YAAY,EAA4B,MAAM,4BAA4B,CAAC;AAKpF,OAAO,EACL,8BAA8B,GAE/B,MAAM,8CAA8C,CAAC;AACtD,OAAO,EACL,mBAAmB,GAEpB,MAAM,mCAAmC,CAAC;AAC3C,OAAO,EACL,iBAAiB,GAIlB,MAAM,kCAAkC,CAAC"}
+{"version":3,"file":"identity.js","sourceRoot":"","sources":["../../src/identity.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAWH,OAAO,EAAE,kBAAkB,EAAE,8BAA8B,EAAE,MAAM,qBAAqB,CAAC;AACzF,OAAO,EACL,MAAM,EACN,MAAM,EACN,KAAK,EACL,OAAO,GAKR,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAE,YAAY,EAA4B,MAAM,4BAA4B,CAAC;AAKpF,OAAO,EACL,8BAA8B,GAE/B,MAAM,8CAA8C,CAAC;AACtD,OAAO,EACL,mBAAmB,GAEpB,MAAM,mCAAmC,CAAC;AAC3C,OAAO,EACL,iBAAiB,GAIlB,MAAM,kCAAkC,CAAC;AAC1C,yEAAyE;AACzE,6EAA6E;AAC7E,uEAAuE;AACvE,OAAO,EAAE,gBAAgB,EAAgC,MAAM,8BAA8B,CAAC"}

package/dist/esm/observability-providers.d.ts

@@ -30,7 +30,9 @@
  *   - agentcoreObservability   ← v2.8.1
  *   - cloudwatchObservability  ← v2.8.2
  *   - xrayObservability        ← v2.8.3
- *   - otelObservability        ← v2.9.0 (this release)
+ *   - otelObservability        ← v2.9.0
+ *   - fileObservability        ← 9.8.0 (no vendor at all — NDJSON on disk,
+ *                                 for the on-premises shop with no collector)
  *
  * Note: `datadogObservability` was on the v2.9 roadmap, but Datadog
  * APM accepts OTLP — point your OTel SDK at Datadog's OTLP endpoint
@@ -46,5 +48,6 @@ export { agentcoreObservability, type AgentcoreObservabilityOptions, } from './a
 export { cloudwatchObservability, type CloudwatchObservabilityOptions, } from './adapters/observability/cloudwatch.js';
 export { xrayObservability, type XrayObservabilityOptions, type XRayLikeClient, } from './adapters/observability/xray.js';
 export { otelObservability, type OtelObservabilityOptions, type OtelObservabilityStrategy, type OtelDecisionEvidenceRecorder, type OtelTracerLike, type OtelSpanLike, type OtelSpanOptions, type OtelAttributeValue, } from './adapters/observability/otel.js';
+export { fileObservability, type FileObservabilityOptions, type FileSinkFs, } from './adapters/observability/file.js';
 export { auditExport, verifyAuditBundle, AUDIT_BUNDLE_FORMAT, AUDIT_GENESIS_EVENT_TYPE, AUDIT_ZERO_HASH, type AuditBundle, type AuditBundleHeader, type AuditExportOptions, type AuditExportStrategy, type AuditRecord, type AuditVerifyResult, } from './adapters/observability/audit.js';
 export { canonicalJson, CANONICAL_JSON_VERSION } from './lib/canonicalJson.js';

package/dist/esm/observability-providers.js

@@ -30,7 +30,9 @@
  *   - agentcoreObservability   ← v2.8.1
  *   - cloudwatchObservability  ← v2.8.2
  *   - xrayObservability        ← v2.8.3
- *   - otelObservability        ← v2.9.0 (this release)
+ *   - otelObservability        ← v2.9.0
+ *   - fileObservability        ← 9.8.0 (no vendor at all — NDJSON on disk,
+ *                                 for the on-premises shop with no collector)
  *
  * Note: `datadogObservability` was on the v2.9 roadmap, but Datadog
  * APM accepts OTLP — point your OTel SDK at Datadog's OTLP endpoint
@@ -46,6 +48,10 @@ export { agentcoreObservability, } from './adapters/observability/agentcore.js';
 export { cloudwatchObservability, } from './adapters/observability/cloudwatch.js';
 export { xrayObservability, } from './adapters/observability/xray.js';
 export { otelObservability, } from './adapters/observability/otel.js';
+// NDJSON to a local file (9.8.0) — the sink for a deployment with no
+// collector to ship to. Vendor-free: `node:fs`, lazily required the same
+// way the vendor SDKs are, so importing this barrel stays browser-safe.
+export { fileObservability, } from './adapters/observability/file.js';
 // Tamper-evident audit export (#20) — the one vendor-free strategy in
 // this subpath (its only runtime requirement is `node:crypto`, lazily
 // imported the same way the vendor SDKs are).

package/dist/esm/observability-providers.js.map

@@ -1 +1 @@
-{"version":3,"file":"observability-providers.js","sourceRoot":"","sources":["../../src/observability-providers.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AAEH,OAAO,EACL,sBAAsB,GAEvB,MAAM,uCAAuC,CAAC;AAC/C,OAAO,EACL,uBAAuB,GAExB,MAAM,wCAAwC,CAAC;AAChD,OAAO,EACL,iBAAiB,GAGlB,MAAM,kCAAkC,CAAC;AAC1C,OAAO,EACL,iBAAiB,GAQlB,MAAM,kCAAkC,CAAC;AAC1C,sEAAsE;AACtE,sEAAsE;AACtE,8CAA8C;AAC9C,OAAO,EACL,WAAW,EACX,iBAAiB,EACjB,mBAAmB,EACnB,wBAAwB,EACxB,eAAe,GAOhB,MAAM,mCAAmC,CAAC;AAC3C,OAAO,EAAE,aAAa,EAAE,sBAAsB,EAAE,MAAM,wBAAwB,CAAC"}
+{"version":3,"file":"observability-providers.js","sourceRoot":"","sources":["../../src/observability-providers.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;AAEH,OAAO,EACL,sBAAsB,GAEvB,MAAM,uCAAuC,CAAC;AAC/C,OAAO,EACL,uBAAuB,GAExB,MAAM,wCAAwC,CAAC;AAChD,OAAO,EACL,iBAAiB,GAGlB,MAAM,kCAAkC,CAAC;AAC1C,OAAO,EACL,iBAAiB,GAQlB,MAAM,kCAAkC,CAAC;AAC1C,qEAAqE;AACrE,yEAAyE;AACzE,wEAAwE;AACxE,OAAO,EACL,iBAAiB,GAGlB,MAAM,kCAAkC,CAAC;AAC1C,sEAAsE;AACtE,sEAAsE;AACtE,8CAA8C;AAC9C,OAAO,EACL,WAAW,EACX,iBAAiB,EACjB,mBAAmB,EACnB,wBAAwB,EACxB,eAAe,GAOhB,MAAM,mCAAmC,CAAC;AAC3C,OAAO,EAAE,aAAa,EAAE,sBAAsB,EAAE,MAAM,wBAAwB,CAAC"}

package/dist/identity.js

@@ -29,7 +29,7 @@
  * symbols, one door. Import from the door.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.agentCoreIdentity = exports.withCredentialRetry = exports.CredentialConsentRequiredError = exports.staticTokens = exports.headers = exports.basic = exports.apiKey = exports.bearer = exports.unconfiguredCredentialProvider = exports.isCredentialIssued = void 0;
+exports.vaultCredentials = exports.agentCoreIdentity = exports.withCredentialRetry = exports.CredentialConsentRequiredError = exports.staticTokens = exports.headers = exports.basic = exports.apiKey = exports.bearer = exports.unconfiguredCredentialProvider = exports.isCredentialIssued = void 0;
 var types_js_1 = require("./identity/types.js");
 Object.defineProperty(exports, "isCredentialIssued", { enumerable: true, get: function () { return types_js_1.isCredentialIssued; } });
 Object.defineProperty(exports, "unconfiguredCredentialProvider", { enumerable: true, get: function () { return types_js_1.unconfiguredCredentialProvider; } });
@@ -46,4 +46,9 @@ var withCredentialRetry_js_1 = require("./identity/withCredentialRetry.js");
 Object.defineProperty(exports, "withCredentialRetry", { enumerable: true, get: function () { return withCredentialRetry_js_1.withCredentialRetry; } });
 var agentcore_js_1 = require("./adapters/identity/agentcore.js");
 Object.defineProperty(exports, "agentCoreIdentity", { enumerable: true, get: function () { return agentcore_js_1.agentCoreIdentity; } });
+// HashiCorp-Vault-compatible KV v2, over plain HTTP (9.8.0) — no SDK, no
+// vendor client. V1 is token auth + KV v2 + no leases, and every other shape
+// is refused by name rather than guessed at; see the module docstring.
+var vault_js_1 = require("./adapters/identity/vault.js");
+Object.defineProperty(exports, "vaultCredentials", { enumerable: true, get: function () { return vault_js_1.vaultCredentials; } });
 //# sourceMappingURL=identity.js.map

package/dist/identity.js.map

@@ -1 +1 @@
-{"version":3,"file":"identity.js","sourceRoot":"","sources":["../src/identity.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;;;AAWH,gDAAyF;AAAhF,8GAAA,kBAAkB,OAAA;AAAE,0HAAA,8BAA8B,OAAA;AAC3D,gDAS6B;AAR3B,kGAAA,MAAM,OAAA;AACN,kGAAA,MAAM,OAAA;AACN,iGAAA,KAAK,OAAA;AACL,mGAAA,OAAO,OAAA;AAMT,8DAAoF;AAA3E,+GAAA,YAAY,OAAA;AAKrB,kGAGsD;AAFpD,mJAAA,8BAA8B,OAAA;AAGhC,4EAG2C;AAFzC,6HAAA,mBAAmB,OAAA;AAGrB,iEAK0C;AAJxC,iHAAA,iBAAiB,OAAA"}
+{"version":3,"file":"identity.js","sourceRoot":"","sources":["../src/identity.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;;;AAWH,gDAAyF;AAAhF,8GAAA,kBAAkB,OAAA;AAAE,0HAAA,8BAA8B,OAAA;AAC3D,gDAS6B;AAR3B,kGAAA,MAAM,OAAA;AACN,kGAAA,MAAM,OAAA;AACN,iGAAA,KAAK,OAAA;AACL,mGAAA,OAAO,OAAA;AAMT,8DAAoF;AAA3E,+GAAA,YAAY,OAAA;AAKrB,kGAGsD;AAFpD,mJAAA,8BAA8B,OAAA;AAGhC,4EAG2C;AAFzC,6HAAA,mBAAmB,OAAA;AAGrB,iEAK0C;AAJxC,iHAAA,iBAAiB,OAAA;AAKnB,yEAAyE;AACzE,6EAA6E;AAC7E,uEAAuE;AACvE,yDAA8F;AAArF,4GAAA,gBAAgB,OAAA"}

package/dist/observability-providers.js

@@ -31,7 +31,9 @@
  *   - agentcoreObservability   ← v2.8.1
  *   - cloudwatchObservability  ← v2.8.2
  *   - xrayObservability        ← v2.8.3
- *   - otelObservability        ← v2.9.0 (this release)
+ *   - otelObservability        ← v2.9.0
+ *   - fileObservability        ← 9.8.0 (no vendor at all — NDJSON on disk,
+ *                                 for the on-premises shop with no collector)
  *
  * Note: `datadogObservability` was on the v2.9 roadmap, but Datadog
  * APM accepts OTLP — point your OTel SDK at Datadog's OTLP endpoint
@@ -44,7 +46,7 @@
  * symbols, one door. Import from the door.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.CANONICAL_JSON_VERSION = exports.canonicalJson = exports.AUDIT_ZERO_HASH = exports.AUDIT_GENESIS_EVENT_TYPE = exports.AUDIT_BUNDLE_FORMAT = exports.verifyAuditBundle = exports.auditExport = exports.otelObservability = exports.xrayObservability = exports.cloudwatchObservability = exports.agentcoreObservability = void 0;
+exports.CANONICAL_JSON_VERSION = exports.canonicalJson = exports.AUDIT_ZERO_HASH = exports.AUDIT_GENESIS_EVENT_TYPE = exports.AUDIT_BUNDLE_FORMAT = exports.verifyAuditBundle = exports.auditExport = exports.fileObservability = exports.otelObservability = exports.xrayObservability = exports.cloudwatchObservability = exports.agentcoreObservability = void 0;
 var agentcore_js_1 = require("./adapters/observability/agentcore.js");
 Object.defineProperty(exports, "agentcoreObservability", { enumerable: true, get: function () { return agentcore_js_1.agentcoreObservability; } });
 var cloudwatch_js_1 = require("./adapters/observability/cloudwatch.js");
@@ -53,6 +55,11 @@ var xray_js_1 = require("./adapters/observability/xray.js");
 Object.defineProperty(exports, "xrayObservability", { enumerable: true, get: function () { return xray_js_1.xrayObservability; } });
 var otel_js_1 = require("./adapters/observability/otel.js");
 Object.defineProperty(exports, "otelObservability", { enumerable: true, get: function () { return otel_js_1.otelObservability; } });
+// NDJSON to a local file (9.8.0) — the sink for a deployment with no
+// collector to ship to. Vendor-free: `node:fs`, lazily required the same
+// way the vendor SDKs are, so importing this barrel stays browser-safe.
+var file_js_1 = require("./adapters/observability/file.js");
+Object.defineProperty(exports, "fileObservability", { enumerable: true, get: function () { return file_js_1.fileObservability; } });
 // Tamper-evident audit export (#20) — the one vendor-free strategy in
 // this subpath (its only runtime requirement is `node:crypto`, lazily
 // imported the same way the vendor SDKs are).

package/dist/observability-providers.js.map

@@ -1 +1 @@
-{"version":3,"file":"observability-providers.js","sourceRoot":"","sources":["../src/observability-providers.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;;;AAEH,sEAG+C;AAF7C,sHAAA,sBAAsB,OAAA;AAGxB,wEAGgD;AAF9C,wHAAA,uBAAuB,OAAA;AAGzB,4DAI0C;AAHxC,4GAAA,iBAAiB,OAAA;AAInB,4DAS0C;AARxC,4GAAA,iBAAiB,OAAA;AASnB,sEAAsE;AACtE,sEAAsE;AACtE,8CAA8C;AAC9C,8DAY2C;AAXzC,uGAAA,WAAW,OAAA;AACX,6GAAA,iBAAiB,OAAA;AACjB,+GAAA,mBAAmB,OAAA;AACnB,oHAAA,wBAAwB,OAAA;AACxB,2GAAA,eAAe,OAAA;AAQjB,2DAA+E;AAAtE,iHAAA,aAAa,OAAA;AAAE,0HAAA,sBAAsB,OAAA"}
+{"version":3,"file":"observability-providers.js","sourceRoot":"","sources":["../src/observability-providers.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;;;AAEH,sEAG+C;AAF7C,sHAAA,sBAAsB,OAAA;AAGxB,wEAGgD;AAF9C,wHAAA,uBAAuB,OAAA;AAGzB,4DAI0C;AAHxC,4GAAA,iBAAiB,OAAA;AAInB,4DAS0C;AARxC,4GAAA,iBAAiB,OAAA;AASnB,qEAAqE;AACrE,yEAAyE;AACzE,wEAAwE;AACxE,4DAI0C;AAHxC,4GAAA,iBAAiB,OAAA;AAInB,sEAAsE;AACtE,sEAAsE;AACtE,8CAA8C;AAC9C,8DAY2C;AAXzC,uGAAA,WAAW,OAAA;AACX,6GAAA,iBAAiB,OAAA;AACjB,+GAAA,mBAAmB,OAAA;AACnB,oHAAA,wBAAwB,OAAA;AACxB,2GAAA,eAAe,OAAA;AAQjB,2DAA+E;AAAtE,iHAAA,aAAa,OAAA;AAAE,0HAAA,sBAAsB,OAAA"}

package/dist/types/adapters/identity/vault.d.ts

@@ -0,0 +1,147 @@
+/**
+ * vaultCredentials — a {@link CredentialProvider} over a HashiCorp-Vault-compatible
+ * KV v2 secret store, spoken as plain HTTP.
+ *
+ *   import { vaultCredentials } from 'agentfootprint/security';
+ *
+ *   const credentials = vaultCredentials({
+ *     address: 'https://vault.internal:8200',   // https, or say `allowHttp` out loud
+ *     mount: 'secret',                          // KV v2 mount, default 'secret'
+ *     paths: { github: 'ci/github' },           // service → path INSIDE the mount
+ *   });                                         // token: VAULT_TOKEN, or `token`
+ *
+ * Zero dependencies and no SDK: one `GET` per resolution through the runtime's
+ * own `fetch`. Vault's HTTP API is small, stable and the thing every
+ * Vault-compatible store (OpenBao, and the Vault-API modes of several managed
+ * stores) implements — so the adapter that speaks HTTP works against more
+ * backends than the adapter that imports one vendor's client.
+ *
+ * ## V1 is deliberately one shape, and says so by name
+ *
+ * | Axis | V1 | Anything else |
+ * |---|---|---|
+ * | Auth | a **token** (`token` option, else `VAULT_TOKEN`) | AppRole / Kubernetes / JWT / AWS IAM login are **refused by name**, naming the option that would carry them |
+ * | Secret engine | **KV v2** (`<mount>/data/<path>`, the `data.data` envelope) | a KV v1 mount is refused by name once the response shape gives it away |
+ * | Leases / renewal | **none** — every `getCredential` re-reads the secret | a lease-aware provider is a different object, and the library's model since 9.7.0 is re-resolve-per-call |
+ *
+ * That is not modesty, it is the honest edge: an auth method the author cannot
+ * exercise against a real cluster would be a guess wearing an adapter's clothes.
+ * Each refusal names the option it would arrive on, so "tell us your auth shape"
+ * is a field report rather than an issue title.
+ *
+ * ## Field → credential kind
+ *
+ * A KV v2 read returns `{ data: { data: { …your fields… }, metadata: {…} } }`.
+ * The inner object is mapped to a {@link Credential} by the FIRST rule that
+ * matches, so a secret written the ordinary way needs no configuration:
+ *
+ * | Fields present | Becomes | Header it applies |
+ * |---|---|---|
+ * | `token` | `bearer(token)` | `authorization: Bearer …` |
+ * | `api_key` \| `apiKey` \| `key` | `apiKey(value, header ?? 'x-api-key')` | that header |
+ * | `username` + `password` | `basic(username, password)` | `authorization: Basic …` |
+ * | `headers` (an object of strings) | `headers(map)` | all of them |
+ *
+ * A secret matching none of them is refused — naming the PATH and the four
+ * shapes, never the secret. `toCredential` is the seam for a shop whose fields
+ * are named otherwise; it sees the secret and returns a `Credential`, and
+ * returning `undefined` falls back to the table above.
+ *
+ * ## Secrecy (the 8.6.0 two-clause law, applied here)
+ *
+ * A thrown message reaches the model as a tool result AND rides
+ * `agentfootprint.credential.failed`. So every error this adapter raises names
+ * **the service, the path and the HTTP status, and nothing from the response
+ * body or the token**. Nothing here logs, and no secret value, no `X-Vault-Token`
+ * header and no field name from the payload appears in any message it can throw
+ * — pinned by a grep-shaped test over every failure path. The credential it
+ * returns hides its own secret fields (non-enumerable) and carries `toHeaders`,
+ * so `structuredClone` rejects it and it cannot enter tracked scope by accident.
+ *
+ * @example Dev → prod is the same two lines
+ * ```ts
+ * // dev
+ * const credentials = staticTokens({ github: 'ghp_dev_xxx' });
+ * // prod — the tool code does not change
+ * const credentials = vaultCredentials({ address: process.env.VAULT_ADDR! });
+ * Agent.create({ provider, model, credentials }).build();
+ * ```
+ */
+import type { Credential, CredentialProvider } from '../../identity/types.js';
+/** The base options every form shares. */
+interface VaultCredentialsBase {
+    /** Vault's base URL, e.g. `https://vault.internal:8200` — **required**, and
+     *  **https** unless {@link VaultCredentialsBase.allowHttp} says otherwise. No
+     *  `VAULT_ADDR` fallback: an agent that silently picks up an address from the
+     *  environment is an agent that reads a different vault when the environment
+     *  changes under it. Name it. */
+    readonly address: string;
+    /** The Vault token. Falls back to `VAULT_TOKEN` (the variable every Vault
+     *  tool already sets). This is a secret: it is sent as `X-Vault-Token` and
+     *  appears in no message this adapter can throw. */
+    readonly token?: string;
+    /** Auth method. **`'token'` is the only one V1 implements.** Anything else is
+     *  refused at construction, by name, with what it would take — see
+     *  {@link vaultCredentials}. */
+    readonly auth?: 'token';
+    /** KV v2 mount point. Default `'secret'` (Vault's own default for the KV v2
+     *  engine). The read URL is `<address>/v1/<mount>/data/<path>`. */
+    readonly mount?: string;
+    /** Vault Enterprise / HCP namespace, sent as `X-Vault-Namespace`. Omit for
+     *  open-source Vault and OpenBao, which have no namespaces. */
+    readonly namespace?: string;
+    /** Map the secret's fields to a {@link Credential} yourself. Returns
+     *  `undefined` to fall back to the built-in table (`token` / `api_key` /
+     *  `username`+`password` / `headers`). The seam for a shop whose field names
+     *  are its own — and the reason this adapter does not need an option per
+     *  spelling. **Never log or return the fields from here**; they are the
+     *  secret. */
+    readonly toCredential?: (secret: Readonly<Record<string, unknown>>, service: string) => Credential | undefined;
+    /** Header name for the `api_key` shape when the secret does not carry its own
+     *  `header` field. Default `'x-api-key'`. */
+    readonly apiKeyHeader?: string;
+    /** Request timeout in ms. Default 5000 — a credential resolution sits in
+     *  front of a tool call, so a hung vault must fail rather than hang a run. */
+    readonly timeoutMs?: number;
+    /** Allow a plain-`http://` address. **Refused unless you set this**, because
+     *  the Vault token travels in a request header: over plaintext HTTP, anyone
+     *  on the path reads a token that can usually read every secret it can reach.
+     *  Set it only for a loopback dev server (`http://127.0.0.1:8200`). */
+    readonly allowHttp?: boolean;
+    /** Stable provider id (default `'vault'`). Shows up in "which provider vended
+     *  this". */
+    readonly id?: string;
+    /** Test seam — inject `fetch`. Bypasses the network entirely. */
+    readonly _fetch?: typeof fetch;
+}
+/**
+ * How a `service` becomes a path inside the mount. Three arms, and they
+ * EXCLUDE each other — two spellings of one rule can disagree, so the type
+ * refuses the pair and so does the constructor.
+ */
+type VaultPathMapping = {
+    /** `service → path inside the mount`, the {@link staticTokens} shape one
+     *  level up: the same literal map, holding a path instead of a token. An
+     *  unknown service is refused by name, listing the known ones. */
+    readonly paths: Readonly<Record<string, string>>;
+    readonly resolve?: never;
+} | {
+    /** `service → path`, computed. Return `undefined` to refuse a service.
+     *  For the convention-driven shop: ``(s) => `agents/${s}` ``. */
+    readonly resolve: (service: string) => string | undefined;
+    readonly paths?: never;
+} | {
+    /** Neither: the **service id IS the path** under the mount, so
+     *  `service: 'github'` reads `<mount>/data/github`. */
+    readonly paths?: undefined;
+    readonly resolve?: undefined;
+};
+export type VaultCredentialsOptions = VaultCredentialsBase & VaultPathMapping;
+/**
+ * Build a {@link CredentialProvider} that reads KV v2 secrets from a
+ * Vault-compatible store. See {@link VaultCredentialsOptions} for the
+ * per-option contract and this module's docstring for the V1 boundary.
+ */
+export declare function vaultCredentials(options: VaultCredentialsOptions): CredentialProvider;
+export {};
+//# sourceMappingURL=vault.d.ts.map

package/dist/types/adapters/identity/vault.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"vault.d.ts","sourceRoot":"","sources":["../../../../src/adapters/identity/vault.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoEG;AAEH,OAAO,KAAK,EACV,UAAU,EACV,kBAAkB,EAGnB,MAAM,yBAAyB,CAAC;AAKjC,0CAA0C;AAC1C,UAAU,oBAAoB;IAC5B;;;;qCAIiC;IACjC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB;;wDAEoD;IACpD,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB;;oCAEgC;IAChC,QAAQ,CAAC,IAAI,CAAC,EAAE,OAAO,CAAC;IACxB;uEACmE;IACnE,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB;mEAC+D;IAC/D,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B;;;;;kBAKc;IACd,QAAQ,CAAC,YAAY,CAAC,EAAE,CACtB,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,EACzC,OAAO,EAAE,MAAM,KACZ,UAAU,GAAG,SAAS,CAAC;IAC5B;iDAC6C;IAC7C,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B;kFAC8E;IAC9E,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B;;;2EAGuE;IACvE,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,CAAC;IAC7B;iBACa;IACb,QAAQ,CAAC,EAAE,CAAC,EAAE,MAAM,CAAC;IACrB,iEAAiE;IACjE,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,KAAK,CAAC;CAChC;AAED;;;;GAIG;AACH,KAAK,gBAAgB,GACjB;IACE;;sEAEkE;IAClE,QAAQ,CAAC,KAAK,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IACjD,QAAQ,CAAC,OAAO,CAAC,EAAE,KAAK,CAAC;CAC1B,GACD;IACE;qEACiE;IACjE,QAAQ,CAAC,OAAO,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,MAAM,GAAG,SAAS,CAAC;IAC1D,QAAQ,CAAC,KAAK,CAAC,EAAE,KAAK,CAAC;CACxB,GACD;IACE;2DACuD;IACvD,QAAQ,CAAC,KAAK,CAAC,EAAE,SAAS,CAAC;IAC3B,QAAQ,CAAC,OAAO,CAAC,EAAE,SAAS,CAAC;CAC9B,CAAC;AAEN,MAAM,MAAM,uBAAuB,GAAG,oBAAoB,GAAG,gBAAgB,CAAC;AAmB9E;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,uBAAuB,GAAG,kBAAkB,CAoIrF"}