agentfootprint 9.7.0 → 9.8.0

package/dist/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/adapters/identity/vault.d.ts

@@ -0,0 +1,146 @@
+/**
+ * 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 {};

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

@@ -0,0 +1,332 @@
+/**
+ * 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 { apiKey, basic, bearer, headers } from '../../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.
+ */
+export 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 };
+        },
+    };
+}
+/**
+ * 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 bearer(token);
+    const key = str(secret.api_key) ?? str(secret.apiKey) ?? str(secret.key);
+    if (key)
+        return apiKey(key, str(secret.header) ?? defaultApiKeyHeader);
+    const username = str(secret.username);
+    const password = str(secret.password);
+    if (username && password)
+        return 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 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/esm/adapters/identity/vault.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"vault.js","sourceRoot":"","sources":["../../../../src/adapters/identity/vault.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoEG;AAQH,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,yBAAyB,CAAC;AAkFzE;;;oBAGoB;AACpB,MAAM,oBAAoB,GAAqC;IAC7D,OAAO,EAAE,oDAAoD;IAC7D,UAAU,EAAE,6EAA6E;IACzF,GAAG,EAAE,yDAAyD;IAC9D,IAAI,EAAE,yDAAyD;IAC/D,GAAG,EAAE,4DAA4D;IACjE,IAAI,EAAE,yEAAyE;IAC/E,QAAQ,EAAE,iDAAiD;IAC3D,IAAI,EAAE,6CAA6C;CACpD,CAAC;AAEF,wEAAwE;AAExE;;;;GAIG;AACH,MAAM,UAAU,gBAAgB,CAAC,OAAgC;IAC/D,MAAM,EAAE,GAAG,OAAO,CAAC,EAAE,IAAI,OAAO,CAAC;IAEjC,IAAI,CAAC,OAAO,CAAC,OAAO,IAAI,OAAO,OAAO,CAAC,OAAO,KAAK,QAAQ,IAAI,OAAO,CAAC,OAAO,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC;QAC7F,MAAM,IAAI,SAAS,CACjB,GAAG,EAAE,uDAAuD;YAC1D,4EAA4E;YAC5E,+EAA+E;YAC/E,wCAAwC,CAC3C,CAAC;IACJ,CAAC;IAED,MAAM,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;IACpD,IAAI,CAAC,cAAc,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC;QAClC,IAAI,CAAC,aAAa,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC;YACjC,MAAM,IAAI,SAAS,CAAC,GAAG,EAAE,8CAA8C,OAAO,KAAK,CAAC,CAAC;QACvF,CAAC;QACD,IAAI,CAAC,OAAO,CAAC,SAAS,EAAE,CAAC;YACvB,MAAM,IAAI,SAAS,CACjB,GAAG,EAAE,qCAAqC,OAAO,iCAAiC;gBAChF,kFAAkF;gBAClF,+EAA+E;gBAC/E,sEAAsE;gBACtE,6DAA6D,CAChE,CAAC;QACJ,CAAC;IACH,CAAC;IAED,IAAI,OAAO,CAAC,IAAI,KAAK,SAAS,IAAI,OAAO,CAAC,IAAI,KAAK,OAAO,EAAE,CAAC;QAC3D,MAAM,KAAK,GAAG,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,WAAW,EAAE,CAAC;QACjD,MAAM,SAAS,GAAG,oBAAoB,CAAC,KAAK,CAAC,CAAC;QAC9C,MAAM,IAAI,SAAS,CACjB,GAAG,EAAE,cAAc,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,4CAA4C;YACjF,sEAAsE;YACtE,CAAC,SAAS;gBACR,CAAC,CAAC,IAAI,KAAK,0BAA0B,SAAS,6BAA6B;oBACzE,yBAAyB;gBAC3B,CAAC,CAAC,gFAAgF,CAAC;YACrF,mFAAmF;YACnF,oFAAoF;YACpF,4EAA4E;YAC5E,+BAA+B,CAClC,CAAC;IACJ,CAAC;IAED,IAAI,OAAO,CAAC,KAAK,IAAI,OAAO,CAAC,OAAO,EAAE,CAAC;QACrC,MAAM,IAAI,SAAS,CACjB,GAAG,EAAE,4EAA4E;YAC/E,mFAAmF;YACnF,iEAAiE,CACpE,CAAC;IACJ,CAAC;IAED,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,IAAI,OAAO,CAAC,aAAa,CAAC,CAAC;IACtD,IAAI,CAAC,KAAK,EAAE,CAAC;QACX,MAAM,IAAI,SAAS,CACjB,GAAG,EAAE,iFAAiF;YACpF,sDAAsD,CACzD,CAAC;IACJ,CAAC;IAED,MAAM,KAAK,GAAG,WAAW,CAAC,OAAO,CAAC,KAAK,IAAI,QAAQ,CAAC,CAAC;IACrD,MAAM,SAAS,GAAG,OAAO,CAAC,SAAS,IAAI,IAAI,CAAC;IAC5C,MAAM,YAAY,GAAG,OAAO,CAAC,YAAY,IAAI,WAAW,CAAC;IACzD,MAAM,OAAO,GAAG,OAAO,CAAC,MAAM,IAAI,CAAC,CAAC,GAAG,IAA8B,EAAE,EAAE,CAAC,KAAK,CAAC,GAAG,IAAI,CAAC,CAAC,CAAC;IAE1F,wEAAwE;IACxE,SAAS,OAAO,CAAC,OAAe;QAC9B,IAAI,OAAO,CAAC,KAAK,EAAE,CAAC;YAClB,MAAM,MAAM,GAAG,OAAO,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;YACtC,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;gBACzB,MAAM,IAAI,KAAK,CACb,GAAG,EAAE,4CAA4C,OAAO,KAAK;oBAC3D,mBAAmB,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,QAAQ,GAAG,CAC1E,CAAC;YACJ,CAAC;YACD,OAAO,WAAW,CAAC,MAAM,CAAC,CAAC;QAC7B,CAAC;QACD,IAAI,OAAO,CAAC,OAAO,EAAE,CAAC;YACpB,MAAM,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;YACxC,IAAI,CAAC,MAAM,EAAE,CAAC;gBACZ,MAAM,IAAI,KAAK,CACb,GAAG,EAAE,gBAAgB,OAAO,uDAAuD;oBACjF,sCAAsC,KAAK,oCAAoC;oBAC/E,YAAY,CACf,CAAC;YACJ,CAAC;YACD,OAAO,WAAW,CAAC,MAAM,CAAC,CAAC;QAC7B,CAAC;QACD,qDAAqD;QACrD,OAAO,WAAW,CAAC,OAAO,CAAC,CAAC;IAC9B,CAAC;IAED,OAAO;QACL,EAAE;QACF,KAAK,CAAC,aAAa,CAAC,GAAsB;YACxC,MAAM,UAAU,GAAG,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;YACxC,uEAAuE;YACvE,uEAAuE;YACvE,MAAM,GAAG,GAAG,GAAG,OAAO,OAAO,KAAK,SAAS,UAAU,EAAE,CAAC;YACxD,MAAM,KAAK,GAAG,IAAI,KAAK,IAAI,UAAU,GAAG,CAAC;YAEzC,MAAM,MAAM,GAAG,MAAM,UAAU,CAAC;gBAC9B,GAAG;gBACH,KAAK;gBACL,EAAE;gBACF,OAAO,EAAE,GAAG,CAAC,OAAO;gBACpB,KAAK;gBACL,SAAS,EAAE,OAAO,CAAC,SAAS;gBAC5B,SAAS;gBACT,OAAO;aACR,CAAC,CAAC;YAEH,MAAM,MAAM,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC,MAAM,EAAE,GAAG,CAAC,OAAO,CAAC,CAAC;YAC3D,IAAI,MAAM;gBAAE,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,UAAU,EAAE,MAAM,EAAE,CAAC;YAE5D,MAAM,UAAU,GAAG,qBAAqB,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC;YAC/D,IAAI,CAAC,UAAU,EAAE,CAAC;gBAChB,MAAM,IAAI,KAAK,CACb,GAAG,EAAE,mBAAmB,KAAK,qDAAqD;oBAChF,2EAA2E;oBAC3E,4EAA4E;oBAC5E,gFAAgF;oBAChF,0EAA0E,CAC7E,CAAC;YACJ,CAAC;YACD,wEAAwE;YACxE,uEAAuE;YACvE,wDAAwD;YACxD,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,UAAU,EAAE,CAAC;QAC1C,CAAC;KACF,CAAC;AACJ,CAAC;AAgBD;;;;;;;;GAQG;AACH,KAAK,UAAU,UAAU,CAAC,IAAoB;IAC5C,MAAM,EAAE,EAAE,EAAE,KAAK,EAAE,OAAO,EAAE,GAAG,IAAI,CAAC;IAEpC,IAAI,GAAsC,CAAC;IAC3C,IAAI,CAAC;QACH,GAAG,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,GAAG,EAAE;YACjC,MAAM,EAAE,KAAK;YACb,OAAO,EAAE;gBACP,eAAe,EAAE,IAAI,CAAC,KAAK;gBAC3B,MAAM,EAAE,kBAAkB;gBAC1B,GAAG,CAAC,IAAI,CAAC,SAAS,IAAI,EAAE,mBAAmB,EAAE,IAAI,CAAC,SAAS,EAAE,CAAC;aAC/D;YACD,MAAM,EAAE,WAAW,CAAC,OAAO,CAAC,IAAI,CAAC,SAAS,CAAC;SAC5C,CAAC,CAAC;IACL,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,yEAAyE;QACzE,wEAAwE;QACxE,yEAAyE;QACzE,iCAAiC;QACjC,MAAM,IAAI,KAAK,CACb,GAAG,EAAE,wCAAwC,OAAO,MAAM,KAAK,KAAK;YAClE,GAAG,eAAe,CAAC,GAAG,CAAC,GAAG,CAC7B,CAAC;IACJ,CAAC;IAED,IAAI,CAAC,GAAG,CAAC,EAAE,EAAE,CAAC;QACZ,MAAM,IAAI,KAAK,CACb,GAAG,EAAE,oBAAoB,GAAG,CAAC,MAAM,YAAY,KAAK,iBAAiB,OAAO,GAAG;YAC7E,GAAG,UAAU,CAAC,GAAG,CAAC,MAAM,CAAC,EAAE,CAC9B,CAAC;IACJ,CAAC;IAED,IAAI,IAAa,CAAC;IAClB,IAAI,CAAC;QACH,IAAI,GAAG,MAAM,GAAG,CAAC,IAAI,EAAE,CAAC;IAC1B,CAAC;IAAC,MAAM,CAAC;QACP,MAAM,IAAI,KAAK,CACb,GAAG,EAAE,0BAA0B,KAAK,yBAAyB,GAAG,CAAC,MAAM,KAAK;YAC1E,gFAAgF,CACnF,CAAC;IACJ,CAAC;IAED,MAAM,KAAK,GAAI,IAAkC,EAAE,IAAI,CAAC;IACxD,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC;QACrB,MAAM,IAAI,KAAK,CACb,GAAG,EAAE,uBAAuB,KAAK,YAAY,GAAG,CAAC,MAAM,KAAK;YAC1D,2CAA2C,CAC9C,CAAC;IACJ,CAAC;IACD,MAAM,KAAK,GAAI,KAA4B,CAAC,IAAI,CAAC;IACjD,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC;QACrB,0EAA0E;QAC1E,uEAAuE;QACvE,0BAA0B;QAC1B,MAAM,IAAI,KAAK,CACb,GAAG,EAAE,sBAAsB,KAAK,oDAAoD;YAClF,iFAAiF;YACjF,gBAAgB,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,OAAO,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,YAAY,eAAe;YACrF,mFAAmF;YACnF,0DAA0D,CAC7D,CAAC;IACJ,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED,4DAA4D;AAC5D,SAAS,eAAe,CAAC,GAAY;IACnC,IAAI,GAAG,YAAY,KAAK,EAAE,CAAC;QACzB,IAAI,GAAG,CAAC,IAAI,KAAK,cAAc,IAAI,GAAG,CAAC,IAAI,KAAK,YAAY;YAAE,OAAO,uBAAuB,CAAC;QAC7F,OAAO,GAAG,CAAC,IAAI,IAAI,eAAe,CAAC;IACrC,CAAC;IACD,OAAO,eAAe,CAAC;AACzB,CAAC;AAED;mDACmD;AACnD,SAAS,UAAU,CAAC,MAAc;IAChC,IAAI,MAAM,KAAK,GAAG,EAAE,CAAC;QACnB,OAAO,uEAAuE,CAAC;IACjF,CAAC;IACD,IAAI,MAAM,KAAK,GAAG;QAAE,OAAO,6CAA6C,CAAC;IACzE,IAAI,MAAM,KAAK,GAAG,EAAE,CAAC;QACnB,OAAO,CACL,sEAAsE;YACtE,iDAAiD,CAClD,CAAC;IACJ,CAAC;IACD,IAAI,MAAM,KAAK,GAAG;QAAE,OAAO,+BAA+B,CAAC;IAC3D,OAAO,GAAG,CAAC;AACb,CAAC;AAED,wEAAwE;AAExE;;;;GAIG;AACH,SAAS,qBAAqB,CAC5B,MAAyC,EACzC,mBAA2B;IAE3B,MAAM,KAAK,GAAG,GAAG,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;IAChC,IAAI,KAAK;QAAE,OAAO,MAAM,CAAC,KAAK,CAAC,CAAC;IAEhC,MAAM,GAAG,GAAG,GAAG,CAAC,MAAM,CAAC,OAAO,CAAC,IAAI,GAAG,CAAC,MAAM,CAAC,MAAM,CAAC,IAAI,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;IACzE,IAAI,GAAG;QAAE,OAAO,MAAM,CAAC,GAAG,EAAE,GAAG,CAAC,MAAM,CAAC,MAAM,CAAC,IAAI,mBAAmB,CAAC,CAAC;IAEvE,MAAM,QAAQ,GAAG,GAAG,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;IACtC,MAAM,QAAQ,GAAG,GAAG,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;IACtC,IAAI,QAAQ,IAAI,QAAQ;QAAE,OAAO,KAAK,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAC;IAE3D,MAAM,GAAG,GAAG,MAAM,CAAC,OAAO,CAAC;IAC3B,IAAI,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC;QAClB,MAAM,IAAI,GAA2B,EAAE,CAAC;QACxC,KAAK,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC;YACzC,MAAM,CAAC,GAAG,GAAG,CAAC,CAAC,CAAC,CAAC;YACjB,IAAI,CAAC;gBAAE,IAAI,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;QACrB,CAAC;QACD,IAAI,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,MAAM,GAAG,CAAC;YAAE,OAAO,OAAO,CAAC,IAAI,CAAC,CAAC;IACzD,CAAC;IAED,OAAO,SAAS,CAAC;AACnB,CAAC;AAED,wEAAwE;AAExE,SAAS,QAAQ,CAAC,CAAU;IAC1B,OAAO,OAAO,CAAC,KAAK,QAAQ,IAAI,CAAC,KAAK,IAAI,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;AAClE,CAAC;AAED;gFACgF;AAChF,SAAS,GAAG,CAAC,CAAU;IACrB,OAAO,OAAO,CAAC,KAAK,QAAQ,IAAI,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;AAC3D,CAAC;AAED,SAAS,WAAW,CAAC,CAAS;IAC5B,OAAO,CAAC,CAAC,OAAO,CAAC,YAAY,EAAE,EAAE,CAAC,CAAC;AACrC,CAAC;AAED;0CAC0C;AAC1C,SAAS,OAAO,CAAC,IAAY;IAC3B,MAAM,CAAC,GAAI,UAAyE,CAAC,OAAO,CAAC;IAC7F,OAAO,CAAC,EAAE,GAAG,EAAE,CAAC,IAAI,CAAC,CAAC;AACxB,CAAC"}

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

@@ -0,0 +1,145 @@
+/**
+ * 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;