agentfootprint 9.7.0 → 9.9.0

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

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

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

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

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

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