agentfootprint 9.7.0 → 9.8.0

package/dist/types/adapters/observability/file.d.ts

@@ -0,0 +1,146 @@
+/**
+ * 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 type { AgentfootprintEvent, AgentfootprintEventType } from '../../events/registry.js';
+import type { ObservabilityStrategy } from '../../strategies/types.js';
+export interface FileObservabilityOptions {
+    /** Absolute or relative path to the NDJSON file. **Required.** Its parent
+     *  directories are created (`recursive`) and the file itself is claimed at
+     *  construction, so an unwritable path fails where you wrote it rather than
+     *  at the first event — the only moment a caller is still watching. */
+    readonly path: string;
+    /** Rotation ceiling in bytes. Omitted → **never rotates** (the right choice
+     *  when `logrotate` or a shipper already owns the file). Set → a batch that
+     *  would cross the ceiling first renames the file to `<path>.1`, replacing
+     *  any previous `.1`, and starts fresh. ONE generation, no compression, no
+     *  cross-process coordination — see the note in this module's docstring. */
+    readonly maxBytes?: number;
+    /** Max events buffered before a forced append. Default 100. */
+    readonly maxBufferEvents?: number;
+    /** Max buffered payload bytes (UTF-8) before a forced append. Default 65536
+     *  (64 KB) — a local write is cheap, so this is far larger than the network
+     *  adapters' 10 KB. */
+    readonly maxBufferBytes?: number;
+    /** Forced-append interval when traffic is sparse, in ms. Default 1000.
+     *  `0` disables the timer — only size triggers and `flush()` write. */
+    readonly flushIntervalMs?: number;
+    /** Narrow what lands on the disk. Becomes the strategy's
+     *  {@link ObservabilityStrategy.relevantEventTypes}, so the dispatcher does
+     *  not even forward the rest — the filter costs nothing at the hot path.
+     *  Omitted → every event the `tier` lets through is written. */
+    readonly eventTypes?: readonly AgentfootprintEventType[];
+    /**
+     * Where delivery failures go — a full disk, a revoked permission, a path
+     * whose directory was removed under a long-running process.
+     *
+     * Same law as the network adapters (8.11.0): **telemetry that fails
+     * invisibly is indistinguishable from telemetry that works.** Unhandled,
+     * failures reach a rate-limited `console.error`. The batch that failed is
+     * dropped, never requeued, so a disk that has been full for an hour cannot
+     * grow the buffer without bound.
+     */
+    readonly onError?: (error: Error, event?: AgentfootprintEvent) => void;
+    /** Test seam — inject a filesystem. Bypasses `node:fs` entirely, which is
+     *  also what lets the rotation policy be asserted without a real disk. */
+    readonly _fs?: FileSinkFs;
+}
+/**
+ * The slice of the filesystem this adapter touches — five calls, named by what
+ * the adapter uses them FOR rather than by their `node:fs` signatures.
+ *
+ * Sync members run once, at construction; the append path is async so the agent
+ * loop never waits on a disk.
+ */
+export interface FileSinkFs {
+    /** Create the log file's parent directory chain. */
+    mkdirSync(dir: string, options: {
+        readonly recursive: boolean;
+    }): void;
+    /** Claim the file at construction. This is the writability refusal: an
+     *  unwritable path throws HERE, with the caller still on the stack. */
+    appendFileSync(file: string, data: string): void;
+    /** Current size, so the rotation counter starts from what is already there
+     *  rather than from zero on every restart. */
+    statSync(file: string): {
+        readonly size: number;
+    };
+    /** Append one batch of NDJSON lines. */
+    appendFile(file: string, data: string): Promise<void>;
+    /** Rotate: `<path>` → `<path>.1`, replacing any previous `.1`. */
+    rename(from: string, to: string): Promise<void>;
+}
+/**
+ * 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 declare function fileObservability(opts: FileObservabilityOptions): ObservabilityStrategy;
+//# sourceMappingURL=file.d.ts.map

package/dist/types/adapters/observability/file.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"file.d.ts","sourceRoot":"","sources":["../../../../src/adapters/observability/file.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsEG;AAEH,OAAO,KAAK,EAAE,mBAAmB,EAAE,uBAAuB,EAAE,MAAM,0BAA0B,CAAC;AAE7F,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,2BAA2B,CAAC;AAMvE,MAAM,WAAW,wBAAwB;IACvC;;;2EAGuE;IACvE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB;;;;gFAI4E;IAC5E,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,+DAA+D;IAC/D,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,CAAC;IAClC;;2BAEuB;IACvB,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;IACjC;2EACuE;IACvE,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,CAAC;IAClC;;;oEAGgE;IAChE,QAAQ,CAAC,UAAU,CAAC,EAAE,SAAS,uBAAuB,EAAE,CAAC;IACzD;;;;;;;;;OASG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,EAAE,KAAK,CAAC,EAAE,mBAAmB,KAAK,IAAI,CAAC;IACvE;8EAC0E;IAC1E,QAAQ,CAAC,GAAG,CAAC,EAAE,UAAU,CAAC;CAC3B;AAED;;;;;;GAMG;AACH,MAAM,WAAW,UAAU;IACzB,oDAAoD;IACpD,SAAS,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE;QAAE,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAA;KAAE,GAAG,IAAI,CAAC;IACvE;2EACuE;IACvE,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACjD;kDAC8C;IAC9C,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG;QAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC;IAClD,wCAAwC;IACxC,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACtD,kEAAkE;IAClE,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACjD;AAID;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,wBAAwB,GAAG,qBAAqB,CA2LvF"}

package/dist/types/identity.d.ts

@@ -35,4 +35,5 @@ 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';
 //# sourceMappingURL=identity.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"identity.d.ts","sourceRoot":"","sources":["../../src/identity.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,YAAY,EACV,UAAU,EACV,kBAAkB,EAClB,iBAAiB,EACjB,gBAAgB,EAChB,gBAAgB,EAChB,+BAA+B,EAC/B,cAAc,GACf,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAE,kBAAkB,EAAE,8BAA8B,EAAE,MAAM,qBAAqB,CAAC;AACzF,OAAO,EACL,MAAM,EACN,MAAM,EACN,KAAK,EACL,OAAO,EACP,KAAK,gBAAgB,EACrB,KAAK,gBAAgB,EACrB,KAAK,eAAe,EACpB,KAAK,iBAAiB,GACvB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAE,YAAY,EAAE,KAAK,mBAAmB,EAAE,MAAM,4BAA4B,CAAC;AAIpF,YAAY,EAAE,yBAAyB,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AACvF,OAAO,EACL,8BAA8B,EAC9B,KAAK,gCAAgC,GACtC,MAAM,8CAA8C,CAAC;AACtD,OAAO,EACL,mBAAmB,EACnB,KAAK,0BAA0B,GAChC,MAAM,mCAAmC,CAAC;AAC3C,OAAO,EACL,iBAAiB,EACjB,KAAK,wBAAwB,EAC7B,KAAK,2BAA2B,EAChC,KAAK,sBAAsB,GAC5B,MAAM,kCAAkC,CAAC"}
+{"version":3,"file":"identity.d.ts","sourceRoot":"","sources":["../../src/identity.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,YAAY,EACV,UAAU,EACV,kBAAkB,EAClB,iBAAiB,EACjB,gBAAgB,EAChB,gBAAgB,EAChB,+BAA+B,EAC/B,cAAc,GACf,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAE,kBAAkB,EAAE,8BAA8B,EAAE,MAAM,qBAAqB,CAAC;AACzF,OAAO,EACL,MAAM,EACN,MAAM,EACN,KAAK,EACL,OAAO,EACP,KAAK,gBAAgB,EACrB,KAAK,gBAAgB,EACrB,KAAK,eAAe,EACpB,KAAK,iBAAiB,GACvB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAE,YAAY,EAAE,KAAK,mBAAmB,EAAE,MAAM,4BAA4B,CAAC;AAIpF,YAAY,EAAE,yBAAyB,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AACvF,OAAO,EACL,8BAA8B,EAC9B,KAAK,gCAAgC,GACtC,MAAM,8CAA8C,CAAC;AACtD,OAAO,EACL,mBAAmB,EACnB,KAAK,0BAA0B,GAChC,MAAM,mCAAmC,CAAC;AAC3C,OAAO,EACL,iBAAiB,EACjB,KAAK,wBAAwB,EAC7B,KAAK,2BAA2B,EAChC,KAAK,sBAAsB,GAC5B,MAAM,kCAAkC,CAAC;AAI1C,OAAO,EAAE,gBAAgB,EAAE,KAAK,uBAAuB,EAAE,MAAM,8BAA8B,CAAC"}

package/dist/types/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,6 +48,7 @@ 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';
 //# sourceMappingURL=observability-providers.d.ts.map

package/dist/types/observability-providers.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"observability-providers.d.ts","sourceRoot":"","sources":["../../src/observability-providers.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AAEH,OAAO,EACL,sBAAsB,EACtB,KAAK,6BAA6B,GACnC,MAAM,uCAAuC,CAAC;AAC/C,OAAO,EACL,uBAAuB,EACvB,KAAK,8BAA8B,GACpC,MAAM,wCAAwC,CAAC;AAChD,OAAO,EACL,iBAAiB,EACjB,KAAK,wBAAwB,EAC7B,KAAK,cAAc,GACpB,MAAM,kCAAkC,CAAC;AAC1C,OAAO,EACL,iBAAiB,EACjB,KAAK,wBAAwB,EAC7B,KAAK,yBAAyB,EAC9B,KAAK,4BAA4B,EACjC,KAAK,cAAc,EACnB,KAAK,YAAY,EACjB,KAAK,eAAe,EACpB,KAAK,kBAAkB,GACxB,MAAM,kCAAkC,CAAC;AAI1C,OAAO,EACL,WAAW,EACX,iBAAiB,EACjB,mBAAmB,EACnB,wBAAwB,EACxB,eAAe,EACf,KAAK,WAAW,EAChB,KAAK,iBAAiB,EACtB,KAAK,kBAAkB,EACvB,KAAK,mBAAmB,EACxB,KAAK,WAAW,EAChB,KAAK,iBAAiB,GACvB,MAAM,mCAAmC,CAAC;AAC3C,OAAO,EAAE,aAAa,EAAE,sBAAsB,EAAE,MAAM,wBAAwB,CAAC"}
+{"version":3,"file":"observability-providers.d.ts","sourceRoot":"","sources":["../../src/observability-providers.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;AAEH,OAAO,EACL,sBAAsB,EACtB,KAAK,6BAA6B,GACnC,MAAM,uCAAuC,CAAC;AAC/C,OAAO,EACL,uBAAuB,EACvB,KAAK,8BAA8B,GACpC,MAAM,wCAAwC,CAAC;AAChD,OAAO,EACL,iBAAiB,EACjB,KAAK,wBAAwB,EAC7B,KAAK,cAAc,GACpB,MAAM,kCAAkC,CAAC;AAC1C,OAAO,EACL,iBAAiB,EACjB,KAAK,wBAAwB,EAC7B,KAAK,yBAAyB,EAC9B,KAAK,4BAA4B,EACjC,KAAK,cAAc,EACnB,KAAK,YAAY,EACjB,KAAK,eAAe,EACpB,KAAK,kBAAkB,GACxB,MAAM,kCAAkC,CAAC;AAI1C,OAAO,EACL,iBAAiB,EACjB,KAAK,wBAAwB,EAC7B,KAAK,UAAU,GAChB,MAAM,kCAAkC,CAAC;AAI1C,OAAO,EACL,WAAW,EACX,iBAAiB,EACjB,mBAAmB,EACnB,wBAAwB,EACxB,eAAe,EACf,KAAK,WAAW,EAChB,KAAK,iBAAiB,EACtB,KAAK,kBAAkB,EACvB,KAAK,mBAAmB,EACxB,KAAK,WAAW,EAChB,KAAK,iBAAiB,GACvB,MAAM,mCAAmC,CAAC;AAC3C,OAAO,EAAE,aAAa,EAAE,sBAAsB,EAAE,MAAM,wBAAwB,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentfootprint",
-  "version": "9.7.0",
+  "version": "9.8.0",
   "description": "The explainable agent framework — backtrack a wrong answer to the exact context that caused it (evidence, not guesses). Built on footprintjs.",
   "license": "MIT",
   "type": "commonjs",