agentfootprint 9.7.0 → 9.8.0

package/dist/adapters/identity/vault.js

@@ -0,0 +1,336 @@
+"use strict";
+/**
+ * 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();
+ * ```
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.vaultCredentials = void 0;
+const kinds_js_1 = require("../../identity/kinds.js");
+/** Auth methods a caller may ask for, and the option that would carry each one
+ *  when it is built. Naming them is the teaching: a refusal that says "not
+ *  supported" ends the conversation; one that says what it would take starts a
+ *  field report. */
+const UNBUILT_AUTH_METHODS = {
+    approle: '`roleId` + `secretId` (Vault `auth/approle/login`)',
+    kubernetes: '`role` + the projected service-account token path (`auth/kubernetes/login`)',
+    jwt: '`role` + a signed JWT/OIDC assertion (`auth/jwt/login`)',
+    oidc: '`role` + a signed JWT/OIDC assertion (`auth/jwt/login`)',
+    aws: '`role` + a signed STS identity document (`auth/aws/login`)',
+    cert: 'a client certificate + key, which is a TLS-agent decision, not a header',
+    userpass: '`username` + `password` (`auth/userpass/login`)',
+    ldap: '`username` + `password` (`auth/ldap/login`)',
+};
+// ─── Public factory ──────────────────────────────────────────────────
+/**
+ * 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.
+ */
+function vaultCredentials(options) {
+    const id = options.id ?? 'vault';
+    if (!options.address || typeof options.address !== 'string' || options.address.trim() === '') {
+        throw new TypeError(`${id}: \`address\` is required — the Vault base URL, e.g. ` +
+            `'https://vault.internal:8200'. It is not read from VAULT_ADDR on purpose: ` +
+            `an agent that picks its vault out of the environment reads a different vault ` +
+            `when the environment changes under it.`);
+    }
+    const address = options.address.replace(/\/+$/, '');
+    if (!/^https:\/\//i.test(address)) {
+        if (!/^http:\/\//i.test(address)) {
+            throw new TypeError(`${id}: \`address\` must be an http(s) URL (got '${address}').`);
+        }
+        if (!options.allowHttp) {
+            throw new TypeError(`${id}: refusing a plain-http address ('${address}'). The Vault token travels in ` +
+                `the \`X-Vault-Token\` request header, so over plaintext HTTP anyone on the path ` +
+                `reads a token that can usually read every secret it can reach — and a leaked ` +
+                `read token is not revoked by rotating one secret. Use https, or set ` +
+                `\`allowHttp: true\` deliberately for a loopback dev server.`);
+        }
+    }
+    if (options.auth !== undefined && options.auth !== 'token') {
+        const asked = String(options.auth).toLowerCase();
+        const wouldTake = UNBUILT_AUTH_METHODS[asked];
+        throw new TypeError(`${id}: \`auth: '${String(options.auth)}'\` is not built. V1 authenticates with a ` +
+            `TOKEN only — \`token\`, or the \`VAULT_TOKEN\` environment variable.` +
+            (wouldTake
+                ? ` ${asked} login would arrive on ${wouldTake}, plus a re-login when the ` +
+                    `returned lease expires.`
+                : ` A login method would need its own credentials and a re-login on lease expiry.`) +
+            ` This is field-gated rather than guessed: tell us your auth shape (which method, ` +
+            `which mount path, which lease behaviour) and it gets built against a real cluster ` +
+            `instead of an API document. Until then, exchange it yourself and pass the ` +
+            `resulting token as \`token\`.`);
+    }
+    if (options.paths && options.resolve) {
+        throw new TypeError(`${id}: pass \`paths\` OR \`resolve\`, not both — two spellings of one rule can ` +
+            `disagree, and the one that loses would do so silently. Use \`paths\` for a fixed ` +
+            `map, \`resolve\` when the path is computed from the service id.`);
+    }
+    const token = options.token ?? readEnv('VAULT_TOKEN');
+    if (!token) {
+        throw new TypeError(`${id}: no Vault token. Pass \`token\`, or set the VAULT_TOKEN environment variable. ` +
+            `(V1 authenticates with a token only — see \`auth\`.)`);
+    }
+    const mount = trimSlashes(options.mount ?? 'secret');
+    const timeoutMs = options.timeoutMs ?? 5000;
+    const apiKeyHeader = options.apiKeyHeader ?? 'x-api-key';
+    const doFetch = options._fetch ?? ((...args) => fetch(...args));
+    /** service → path inside the mount, by whichever arm was configured. */
+    function pathFor(service) {
+        if (options.paths) {
+            const mapped = options.paths[service];
+            if (mapped === undefined) {
+                throw new Error(`${id}: no secret path configured for service '${service}'. ` +
+                    `Known services: ${Object.keys(options.paths).join(', ') || '(none)'}.`);
+            }
+            return trimSlashes(mapped);
+        }
+        if (options.resolve) {
+            const mapped = options.resolve(service);
+            if (!mapped) {
+                throw new Error(`${id}: \`resolve('${service}')\` returned no path, so this service has no secret ` +
+                    `to read. Return a path inside the '${mount}' mount, or configure the service ` +
+                    `elsewhere.`);
+            }
+            return trimSlashes(mapped);
+        }
+        // No mapping configured: the service id IS the path.
+        return trimSlashes(service);
+    }
+    return {
+        id,
+        async getCredential(req) {
+            const secretPath = pathFor(req.service);
+            // KV v2's read shape. `/data/` is the v2 API segment, not part of your
+            // path — `secret/ci/github` in the UI is `secret/data/ci/github` here.
+            const url = `${address}/v1/${mount}/data/${secretPath}`;
+            const where = `'${mount}/${secretPath}'`;
+            const secret = await readSecret({
+                url,
+                where,
+                id,
+                service: req.service,
+                token,
+                namespace: options.namespace,
+                timeoutMs,
+                doFetch,
+            });
+            const custom = options.toCredential?.(secret, req.service);
+            if (custom)
+                return { status: 'issued', credential: custom };
+            const credential = mapFieldsToCredential(secret, apiKeyHeader);
+            if (!credential) {
+                throw new Error(`${id}: the secret at ${where} has none of the field shapes this adapter reads — ` +
+                    `\`token\`, \`api_key\`/\`apiKey\`/\`key\`, \`username\`+\`password\`, or ` +
+                    `\`headers\`. (The fields it DOES have are deliberately not named here: an ` +
+                    `error message reaches the model and the credential.failed event.) Rewrite the ` +
+                    `secret in one of those shapes, or pass \`toCredential\` to map your own.`);
+            }
+            // No `expiresAt`: a KV v2 secret has no lease, so there is no expiry to
+            // report and inventing one would be worse than absence. V1 re-reads on
+            // every call, which is the library's model since 9.7.0.
+            return { status: 'issued', credential };
+        },
+    };
+}
+exports.vaultCredentials = vaultCredentials;
+/**
+ * GET one KV v2 secret and return its inner `data.data` object.
+ *
+ * Every throw below names the provider id, the service, the mount path and (for
+ * an HTTP failure) the status. None of them can name the token, a response body
+ * or a field of the secret — that restraint IS the contract, because this
+ * message becomes a tool result the model reads and a `credential.failed`
+ * payload every observer receives.
+ */
+async function readSecret(args) {
+    const { id, where, service } = args;
+    let res;
+    try {
+        res = await args.doFetch(args.url, {
+            method: 'GET',
+            headers: {
+                'X-Vault-Token': args.token,
+                accept: 'application/json',
+                ...(args.namespace && { 'X-Vault-Namespace': args.namespace }),
+            },
+            signal: AbortSignal.timeout(args.timeoutMs),
+        });
+    }
+    catch (err) {
+        // Transport failure: DNS, TLS, refused connection, timeout. The cause is
+        // safe to name — it describes the socket, never the payload — but it is
+        // re-wrapped rather than rethrown so no fetch implementation can smuggle
+        // request headers into the text.
+        throw new Error(`${id}: could not reach Vault for service '${service}' (${where}): ` +
+            `${transportReason(err)}.`);
+    }
+    if (!res.ok) {
+        throw new Error(`${id}: Vault returned ${res.status} reading ${where} for service '${service}'` +
+            `${statusHint(res.status)}`);
+    }
+    let body;
+    try {
+        body = await res.json();
+    }
+    catch {
+        throw new Error(`${id}: Vault's response for ${where} was not JSON (status ${res.status}). ` +
+            `Check that \`address\` points at Vault's API and not at a proxy or login page.`);
+    }
+    const outer = body?.data;
+    if (!isRecord(outer)) {
+        throw new Error(`${id}: no secret data at ${where} (status ${res.status}). ` +
+            `Check the path exists in the KV v2 mount.`);
+    }
+    const inner = outer.data;
+    if (!isRecord(inner)) {
+        // A v1 mount answers with the fields directly under `data`, with no inner
+        // envelope. That is the one cheap, unambiguous v1 tell, so it is named
+        // rather than guessed at.
+        throw new Error(`${id}: the response for ${where} is not KV v2 shaped (no \`data.data\` envelope). ` +
+            `This adapter reads KV **v2** only, which is why the URL carries the \`/data/\` ` +
+            `segment. If '${where.split('/')[0]?.replace(/'/g, '') || 'that mount'}' is a KV v1 ` +
+            `mount, upgrade it (\`vault kv enable-versioning\`) or mount v2 — or tell us, and ` +
+            `\`kvVersion\` is the option a v1 reader would arrive on.`);
+    }
+    return inner;
+}
+/** A short, payload-free reason for a transport failure. */
+function transportReason(err) {
+    if (err instanceof Error) {
+        if (err.name === 'TimeoutError' || err.name === 'AbortError')
+            return 'the request timed out';
+        return err.name || 'network error';
+    }
+    return 'network error';
+}
+/** What a status usually means here. Static text keyed by number — it cannot
+ *  echo a response, because it never reads one. */
+function statusHint(status) {
+    if (status === 403) {
+        return '. The token is valid but its policy does not allow reading that path.';
+    }
+    if (status === 401)
+        return '. The token is missing, expired or revoked.';
+    if (status === 404) {
+        return ('. Either the path does not exist, or the mount is not a KV v2 mount ' +
+            '(the read URL carries the v2 `/data/` segment).');
+    }
+    if (status === 503)
+        return '. Vault is sealed or standby.';
+    return '.';
+}
+// ─── Field → kind ────────────────────────────────────────────────────
+/**
+ * The built-in field table, first match wins. Deliberately small: four shapes
+ * cover what secrets actually hold, and `toCredential` covers the rest without
+ * this function growing an option per spelling.
+ */
+function mapFieldsToCredential(secret, defaultApiKeyHeader) {
+    const token = str(secret.token);
+    if (token)
+        return (0, kinds_js_1.bearer)(token);
+    const key = str(secret.api_key) ?? str(secret.apiKey) ?? str(secret.key);
+    if (key)
+        return (0, kinds_js_1.apiKey)(key, str(secret.header) ?? defaultApiKeyHeader);
+    const username = str(secret.username);
+    const password = str(secret.password);
+    if (username && password)
+        return (0, kinds_js_1.basic)(username, password);
+    const map = secret.headers;
+    if (isRecord(map)) {
+        const flat = {};
+        for (const [k, v] of Object.entries(map)) {
+            const s = str(v);
+            if (s)
+                flat[k] = s;
+        }
+        if (Object.keys(flat).length > 0)
+            return (0, kinds_js_1.headers)(flat);
+    }
+    return undefined;
+}
+// ─── Small helpers ───────────────────────────────────────────────────
+function isRecord(v) {
+    return typeof v === 'object' && v !== null && !Array.isArray(v);
+}
+/** A non-empty string, or undefined. Numbers are NOT coerced: a secret field
+ *  that is not a string is not a credential this adapter knows how to apply. */
+function str(v) {
+    return typeof v === 'string' && v !== '' ? v : undefined;
+}
+function trimSlashes(s) {
+    return s.replace(/^\/+|\/+$/g, '');
+}
+/** Read one environment variable, in any runtime. Absent `process` (a browser,
+ *  a worker) simply means no fallback. */
+function readEnv(name) {
+    const p = globalThis.process;
+    return p?.env?.[name];
+}
+//# sourceMappingURL=vault.js.map

package/dist/adapters/identity/vault.js.map

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

package/dist/adapters/observability/file.js

@@ -0,0 +1,307 @@
+"use strict";
+/**
+ * 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
+ * ```
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.fileObservability = void 0;
+const lazyRequire_js_1 = require("../../lib/lazyRequire.js");
+const deliveryErrors_js_1 = require("./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.
+ */
+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 = (0, deliveryErrors_js_1.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;
+}
+exports.fileObservability = fileObservability;
+// ─── 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 = (0, lazyRequire_js_1.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