agentfootprint 9.7.0 → 9.9.0

package/dist/observe.js

@@ -47,7 +47,7 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.ledgerGated = exports.ledgerEntryScorer = exports.ledgerToolGate = exports.contextLedger = exports.formatRouteHop = exports.routeRecorder = exports.toolChoiceRecorder = exports.buildChoiceContext = exports.typedEmit = exports.agentThinkingTrace = exports.toolLineageRecorder = exports.attachStatus = exports.LoggingDomains = exports.attachLogging = exports.resilienceRecorder = exports.skillRecorder = exports.permissionRecorder = exports.embeddingRecorder = exports.memoryRecorder = exports.evalRecorder = exports.contextEvaluatedRecorder = exports.toolsRecorder = exports.costRecorder = exports.LiveAgentTurnTracker = exports.LiveToolTracker = exports.LiveLLMTracker = exports.LiveStateRecorder = exports.liveStateRecorder = exports.attachLocalObservability = exports.traceToStepGraph = exports.redactContent = exports.serializeTrace = exports.summarizeVector = exports.summarizeEmbeddings = exports.recordRun = exports.buildStepGraphFromEvents = exports.buildStepGraph = exports.attachFlowchart = exports.runStepRecorder = exports.RunStepRecorder = exports.buildRunSteps = exports.BoundaryRecorder = exports.boundaryRecorder = exports.agentRecorder = exports.compositionRecorder = exports.streamRecorder = exports.ContextRecorder = void 0;
+exports.ledgerGated = exports.ledgerEntryScorer = exports.ledgerToolGate = exports.contextLedger = exports.formatRouteHop = exports.routeRecorder = exports.toolChoiceRecorder = exports.buildChoiceContext = exports.typedEmit = exports.agentThinkingTrace = exports.toolLineageRecorder = exports.attachStatus = exports.LoggingDomains = exports.attachLogging = exports.resilienceRecorder = exports.skillRecorder = exports.permissionRecorder = exports.embeddingRecorder = exports.memoryRecorder = exports.evalRecorder = exports.contextEvaluatedRecorder = exports.toolsRecorder = exports.costRecorder = exports.LiveAgentTurnTracker = exports.LiveToolTracker = exports.LiveLLMTracker = exports.LiveStateRecorder = exports.liveStateRecorder = exports.attachLocalObservability = exports.traceToStepGraph = exports.redactContent = exports.serializeTrace = exports.summarizeVector = exports.summarizeEmbeddings = exports.exportBugReport = exports.describeBugReport = exports.recordRun = exports.buildStepGraphFromEvents = exports.buildStepGraph = exports.attachFlowchart = exports.runStepRecorder = exports.RunStepRecorder = exports.buildRunSteps = exports.BoundaryRecorder = exports.boundaryRecorder = exports.agentRecorder = exports.compositionRecorder = exports.streamRecorder = exports.ContextRecorder = void 0;
 // Tier 1 — context + stream
 var ContextRecorder_js_1 = require("./recorders/core/ContextRecorder.js");
 Object.defineProperty(exports, "ContextRecorder", { enumerable: true, get: function () { return ContextRecorder_js_1.ContextRecorder; } });
@@ -75,6 +75,14 @@ Object.defineProperty(exports, "buildStepGraphFromEvents", { enumerable: true, g
 // every integration used to assemble by hand, each missing a different piece.
 var recordRun_js_1 = require("./recorders/observability/recordRun.js");
 Object.defineProperty(exports, "recordRun", { enumerable: true, get: function () { return recordRun_js_1.recordRun; } });
+// exportBugReport — a bug report IS the evidence. `describeBugReport` measures
+// the run first (selectable units, sizes, the redacted keys by NAME) so a human
+// can consent to exactly what leaves; `exportBugReport` bundles the units they
+// kept as named files plus a real (stored) zip. `githubBugReporter` — in this
+// same door, from the providers barrel — files that bundle.
+var index_js_1 = require("./lib/bug-report/index.js");
+Object.defineProperty(exports, "describeBugReport", { enumerable: true, get: function () { return index_js_1.describeBugReport; } });
+Object.defineProperty(exports, "exportBugReport", { enumerable: true, get: function () { return index_js_1.exportBugReport; } });
 // What a recording keeps of a vector: `{ dims, norm }`, not the bytes (8.20.0).
 // Applied by BoundaryRecorder and recordRun unless `recordEmbeddings: true`;
 // exported so consumers that render or post-process recordings can apply or
@@ -159,9 +167,9 @@ Object.defineProperty(exports, "formatRouteHop", { enumerable: true, get: functi
 // context-ledger — which context pieces EARNED their tokens? Post-run
 // bookkeeping (offers/uses/outcomes from the commit log) feeding the gating
 // seams. See src/lib/context-ledger/README.md.
-var index_js_1 = require("./lib/context-ledger/index.js");
-Object.defineProperty(exports, "contextLedger", { enumerable: true, get: function () { return index_js_1.contextLedger; } });
-Object.defineProperty(exports, "ledgerToolGate", { enumerable: true, get: function () { return index_js_1.ledgerToolGate; } });
-Object.defineProperty(exports, "ledgerEntryScorer", { enumerable: true, get: function () { return index_js_1.ledgerEntryScorer; } });
-Object.defineProperty(exports, "ledgerGated", { enumerable: true, get: function () { return index_js_1.ledgerGated; } });
+var index_js_2 = require("./lib/context-ledger/index.js");
+Object.defineProperty(exports, "contextLedger", { enumerable: true, get: function () { return index_js_2.contextLedger; } });
+Object.defineProperty(exports, "ledgerToolGate", { enumerable: true, get: function () { return index_js_2.ledgerToolGate; } });
+Object.defineProperty(exports, "ledgerEntryScorer", { enumerable: true, get: function () { return index_js_2.ledgerEntryScorer; } });
+Object.defineProperty(exports, "ledgerGated", { enumerable: true, get: function () { return index_js_2.ledgerGated; } });
 //# sourceMappingURL=observe.js.map

package/dist/observe.js.map

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

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"}

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

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

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/adapters/observability/githubBugReporter.d.ts

@@ -0,0 +1,155 @@
+/**
+ * githubBugReporter — file a bug report, with the run attached, into GitHub.
+ *
+ *   import { exportBugReport, githubBugReporter } from 'agentfootprint/observe';
+ *
+ *   const reporter = githubBugReporter({
+ *     issueRepo: 'acme/checkout-agent',      // where the ISSUE goes
+ *     evidenceRepo: 'acme/agent-evidence',   // where the ZIP goes (default: issueRepo)
+ *   });                                      // token: GITHUB_TOKEN, or `token`
+ *
+ *   const { issueUrl, zipUrl } = await reporter.file(report);
+ *
+ * Two HTTP calls and no SDK: `PUT /repos/{evidenceRepo}/contents/{path}` commits
+ * the zip, `POST /repos/{issueRepo}/issues` files the issue with a manifest
+ * table and a link to the committed bundle. Plain `fetch`, zero dependencies,
+ * `apiBase` for GitHub Enterprise Server — so this works unchanged on a network
+ * that never reaches github.com.
+ *
+ * ## TWIN TARGETS: the issue and the evidence may live in different repos
+ *
+ * The case this exists for: a field tester finds a bug in a LIBRARY. The issue
+ * belongs in the library's public repo, where the maintainers and the next
+ * person to hit it will find it. The evidence — a real run, with real prompts,
+ * real tool arguments and real retrieved documents — does not. So the zip goes
+ * into a PRIVATE repo the maintainers can read, and the issue links it and says
+ * plainly that the evidence is private.
+ *
+ * ```ts
+ * githubBugReporter({
+ *   issueRepo: 'footprintjs/agentfootprint',   // public — the conversation
+ *   evidenceRepo: 'acme/af-bug-evidence',      // private — the run
+ * });
+ * ```
+ *
+ * ## DEFAULT-TARGET DOCTRINE
+ *
+ * **File into the application's OWN repo.** That is the default (`evidenceRepo`
+ * defaults to `issueRepo`) and it is the right default: the run belongs to the
+ * organisation that produced it. Sending a run's evidence across an
+ * organisational boundary — to a vendor, to an upstream library, to anyone
+ * whose access your company did not grant — is a HUMAN act with consequences a
+ * library cannot weigh. This adapter will do it, because a field tester filing
+ * upstream is a real and valuable thing; it will not do it quietly. The
+ * consent manifest (`describeBugReport`) exists so a person sees exactly what
+ * would leave before it does, and this reporter refuses to commit evidence to a
+ * PUBLIC repo unless the caller says `acknowledgePublicEvidence: true` out loud.
+ *
+ * ## Provisioning the token: fine-grained, and scoped to two repos
+ *
+ * Use a **fine-grained personal access token** (GitHub → Settings → Developer
+ * settings → Fine-grained tokens), scoped to ONLY `issueRepo` and
+ * `evidenceRepo`, with exactly two permissions — **Contents: read and write**
+ * (to commit the zip) and **Issues: read and write** (to file the issue) — and
+ * an expiry date. Put it in the server's environment as `GITHUB_TOKEN`, or pass
+ * it as `token`.
+ *
+ * The contrast matters: a CLASSIC PAT's `repo` scope is coarse — it grants
+ * read/write across every repository the account can reach, so a leaked
+ * bug-report token is a leaked key to the whole account. With a fine-grained
+ * token scoped as above, the blast radius of a leak is filing bug reports and
+ * committing files to one evidence repo, and nothing else. GitHub App
+ * installation tokens (short-lived, org-installed, revocable centrally) are the
+ * next rung for an organisation that wants one; this adapter does not mint
+ * them — hand it the token your app already obtained.
+ *
+ * ## Secrecy (the two-clause law)
+ *
+ * The token appears in no message, no error and no log this adapter can
+ * produce, and neither does the bundle's content. A failed request is reported
+ * as **the status and GitHub's own `message` field** — never the request, never
+ * the headers, never the body that carried the token, never a byte of
+ * evidence. Transport failures are re-wrapped rather than rethrown, because a
+ * `fetch` implementation is free to put the request (headers included) into the
+ * error it throws. Nothing here writes to a console. Pinned by a suite that
+ * forces every failure path and greps the message, the stack and the JSON
+ * projection for the token.
+ *
+ * @example  A server route (the app's own repo, the default target)
+ * ```ts
+ * const reporter = githubBugReporter({ issueRepo: 'acme/checkout-agent' });
+ * app.post('/bug-report', async (req, res) => {
+ *   const report = exportBugReport(recordings.get(req.body.runId), req.body.fields);
+ *   res.json(await reporter.file(report));
+ * });
+ * ```
+ */
+import type { BugReport } from '../../lib/bug-report/index.js';
+export interface GithubBugReporterOptions {
+    /** `owner/name` of the repo the ISSUE is filed in. Required. */
+    readonly issueRepo: string;
+    /**
+     * `owner/name` of the repo the evidence ZIP is committed to. Defaults to
+     * {@link issueRepo}. Point it at a PRIVATE repo when the issue itself is
+     * public — see the twin-target section above.
+     */
+    readonly evidenceRepo?: string;
+    /**
+     * The GitHub token. Falls back to the `GITHUB_TOKEN` environment variable.
+     * It needs **Contents: read/write on `evidenceRepo`** and **Issues:
+     * read/write on `issueRepo`**; filing an issue on a public repo needs only a
+     * valid account token. This is a secret: it is sent as an `Authorization`
+     * header and appears in no message this adapter can throw.
+     */
+    readonly token?: string;
+    /** Directory inside `evidenceRepo` for the bundles. Default `'bug-reports'`. */
+    readonly dir?: string;
+    /** Labels applied to the issue. Default: none. */
+    readonly labels?: readonly string[];
+    /** Branch to commit the evidence to. Default: the repo's default branch. */
+    readonly branch?: string;
+    /** API root. Default `https://api.github.com`; for GitHub Enterprise Server
+     *  it is `https://github.your-company.com/api/v3`. */
+    readonly apiBase?: string;
+    /**
+     * Commit evidence to a PUBLIC repo deliberately.
+     *
+     * Off by default: a bundle carries a real run — prompts, tool arguments,
+     * retrieved documents — and a public repo publishes it to the internet
+     * permanently. Set this only when the evidence is synthetic, or when a human
+     * has read the manifest and decided.
+     */
+    readonly acknowledgePublicEvidence?: boolean;
+    /** Refuse a zip larger than this before uploading. Default 24 MB. */
+    readonly maxZipBytes?: number;
+    /** Test seam — inject `fetch`. Bypasses the network entirely. */
+    readonly _fetch?: typeof fetch;
+}
+/** What a filed report leaves behind. */
+export interface FiledBugReport {
+    /** The issue, on `issueRepo`. */
+    readonly issueUrl: string;
+    /** The committed bundle's blob page, on `evidenceRepo`. */
+    readonly zipUrl: string;
+    /** Path inside `evidenceRepo`. */
+    readonly zipPath: string;
+    /** `owner/name` the evidence went to. */
+    readonly evidenceRepo: string;
+    /**
+     * Whether the evidence repo's visibility was actually READ before committing.
+     *
+     * `false` means the metadata call failed — usually a token that can write
+     * contents but not read repository metadata. The commit proceeds (a
+     * permissions quirk must not block a bug report) and this field says the
+     * guard did not run, so nobody mistakes an unchecked upload for a checked one.
+     */
+    readonly checkedVisibility: boolean;
+    /** The answer, when the check ran. */
+    readonly evidenceRepoPrivate?: boolean;
+}
+/** Files a finished {@link BugReport}. */
+export interface BugReporter {
+    file(report: BugReport): Promise<FiledBugReport>;
+}
+export declare function githubBugReporter(options: GithubBugReporterOptions): BugReporter;
+//# sourceMappingURL=githubBugReporter.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"githubBugReporter.d.ts","sourceRoot":"","sources":["../../../../src/adapters/observability/githubBugReporter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqFG;AAGH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,+BAA+B,CAAC;AAW/D,MAAM,WAAW,wBAAwB;IACvC,gEAAgE;IAChE,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B;;;;OAIG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B;;;;;;OAMG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,gFAAgF;IAChF,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IACtB,kDAAkD;IAClD,QAAQ,CAAC,MAAM,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACpC,4EAA4E;IAC5E,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB;0DACsD;IACtD,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B;;;;;;;OAOG;IACH,QAAQ,CAAC,yBAAyB,CAAC,EAAE,OAAO,CAAC;IAC7C,qEAAqE;IACrE,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,iEAAiE;IACjE,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,KAAK,CAAC;CAChC;AAED,yCAAyC;AACzC,MAAM,WAAW,cAAc;IAC7B,iCAAiC;IACjC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,2DAA2D;IAC3D,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,kCAAkC;IAClC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,yCAAyC;IACzC,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B;;;;;;;OAOG;IACH,QAAQ,CAAC,iBAAiB,EAAE,OAAO,CAAC;IACpC,sCAAsC;IACtC,QAAQ,CAAC,mBAAmB,CAAC,EAAE,OAAO,CAAC;CACxC;AAED,0CAA0C;AAC1C,MAAM,WAAW,WAAW;IAC1B,IAAI,CAAC,MAAM,EAAE,SAAS,GAAG,OAAO,CAAC,cAAc,CAAC,CAAC;CAClD;AAED,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,wBAAwB,GAAG,WAAW,CAsGhF"}