agentfootprint 9.46.3 → 9.48.0

package/dist/esm/recorders/observability/fileRecordingSink.js

@@ -0,0 +1,195 @@
+/**
+ * fileRecordingSink — one archived run, one JSON file, in a directory.
+ *
+ * The destination that needs nothing installed: an incident can be inspected
+ * with `ls` and `cat`, and a run archive is a folder you can tar. It is also
+ * the reference implementation of {@link RecordingSink} — a sink is one method,
+ * and this file is what "implement the other ones like this" points at.
+ *
+ * ## The file name is a key, and keys must be injective
+ *
+ * `runId` becomes a file name, which makes `runId ↦ name` a mapping used as a
+ * key: two different runs landing on one name means one archive silently
+ * overwrites another, and the evidence is gone with no error anywhere. So the
+ * mapping is `runId + '.json'` — appending a constant suffix, which is
+ * injective — over a DOMAIN that is asserted rather than assumed, and anything
+ * outside it is refused by name.
+ *
+ * The domain is `[a-z0-9]` followed by `[a-z0-9._-]*`, and every exclusion is
+ * load-bearing:
+ *
+ *   • **no uppercase.** This is the one that looks like fussiness and is not.
+ *     macOS/APFS and Windows/NTFS are case-INSENSITIVE by default, so `run-A`
+ *     and `run-a` are two distinct strings that name ONE file. A mapping that
+ *     is injective as a string can still collide as a file name, which is
+ *     exactly the bug artifacts/scopePath.ts found on a stock Mac in 9.44.0 —
+ *     its conformance battery had pairs for separators, absence markers and
+ *     pre-escaped values, and no pair differing only in case. Excluding
+ *     uppercase from the domain means no two valid ids differ by case alone, so
+ *     there is nothing for a case-folding filesystem to fold together.
+ *   • **no `/` or `\`.** A separator inside a field is separator donation: an
+ *     id containing one would silently become a path with a directory hop.
+ *   • **no leading `.` or `-`.** A leading dot hides the archive from `ls`; a
+ *     leading dash is read as a flag by every CLI tool that would then handle
+ *     it. Both are enforced by the first-character class.
+ *   • **no bare `.` / `..`.** Path navigation, not names.
+ *   • **length capped.** `NAME_MAX` is 255 on the common filesystems and the
+ *     suffixes here add to it.
+ *   • **no Windows reserved device names.** `con`, `nul`, `com1` … are devices
+ *     with OR without an extension: `con.json` opens the console, not a file.
+ *
+ * Ids this library mints all satisfy it: `makeRunId()` produces
+ * `run-<epoch ms>-<seq>` and the footprintjs engine produces
+ * `<epoch ms>-<padded counter>`. The assertion is there for the ids a CALLER
+ * states, which is the case that is neither controlled nor rare.
+ *
+ * ## Atomic, so a reader never sees half an archive
+ *
+ * The bytes go to a temporary file in the same directory and are then renamed
+ * into place. `rename` within one filesystem is atomic, so a crash mid-write
+ * leaves a `.tmp` nobody reads rather than a truncated `.json` that parses as
+ * far as it got — a half-written archive is the one failure a bug report cannot
+ * survive, because it looks like evidence.
+ *
+ * Writing the same `runId` twice REPLACES the file, atomically. That is the
+ * intended behaviour and worth stating: the run id is the archive's identity,
+ * so a second envelope for one run is a newer version of one archive (a partial
+ * crash dump later superseded by the finished run), not a second archive.
+ *
+ * Node-only. `node:fs` is reached through `lazyRequire`, the same law the other
+ * filesystem adapters follow, so importing the door costs a browser bundle
+ * nothing and constructing one where there is no filesystem refuses by name.
+ */
+import { lazyRequire } from '../../lib/lazyRequire.js';
+/** The archive file's extension. Also the tmp file's discriminator. */
+const ENVELOPE_EXTENSION = '.json';
+/** `NAME_MAX` is 255; leave room for the extension and the tmp suffix. */
+const MAX_RUN_ID_LENGTH = 200;
+/** Valid from the first character on — see the module header for each rule. */
+const SAFE_RUN_ID = /^[a-z0-9][a-z0-9._-]*$/;
+/**
+ * Reserved on Windows with any extension, so `con.json` is still the console.
+ * Checked against the whole id because the id IS the name's stem.
+ */
+const WINDOWS_RESERVED = new Set([
+    'con',
+    'prn',
+    'aux',
+    'nul',
+    ...Array.from({ length: 9 }, (_, i) => `com${String(i + 1)}`),
+    ...Array.from({ length: 9 }, (_, i) => `lpt${String(i + 1)}`),
+]);
+/**
+ * Raised when a run id cannot safely become a file name.
+ *
+ * Its own class because the fix is never a retry: the caller has to name the
+ * archive something a filesystem can hold one-to-one.
+ */
+export class UnsafeRecordingIdError extends Error {
+    code = 'ERR_UNSAFE_RECORDING_ID';
+    runId;
+    constructor(runId, reason) {
+        super(`[recording-sink] run id ${JSON.stringify(runId)} cannot become a file name: ${reason}\n\n` +
+            `A file name is a key: if two runs can land on one name, one archive overwrites the ` +
+            `other and the evidence is gone with nothing raised anywhere. So the safe set is ` +
+            `asserted rather than hoped for — lowercase letters, digits, '.', '_' and '-', ` +
+            `starting with a letter or digit, at most ${String(MAX_RUN_ID_LENGTH)} characters. ` +
+            `(Uppercase is excluded because macOS and Windows fold case: 'run-A' and 'run-a' are ` +
+            `two ids and one file.) Either state a run.runId in that set, or write to a sink whose ` +
+            `keys are not file names.`);
+        this.name = 'UnsafeRecordingIdError';
+        this.runId = runId;
+    }
+}
+/**
+ * The mapping under test: one run id → one file name, injectively.
+ *
+ * Exported so the collision battery can drive the mapping directly rather than
+ * inferring it from files on a disk.
+ *
+ * @throws {UnsafeRecordingIdError} for any id outside the safe domain.
+ */
+export function recordingFileName(runId) {
+    if (typeof runId !== 'string' || runId === '') {
+        throw new UnsafeRecordingIdError(String(runId), 'it is not a non-empty string.');
+    }
+    if (runId.length > MAX_RUN_ID_LENGTH) {
+        throw new UnsafeRecordingIdError(runId, `it is ${String(runId.length)} characters; the limit is ${String(MAX_RUN_ID_LENGTH)}.`);
+    }
+    if (/[A-Z]/.test(runId)) {
+        throw new UnsafeRecordingIdError(runId, 'it contains uppercase letters, and case-insensitive filesystems (macOS, Windows) would ' +
+            'let it share a file with its lowercase twin.');
+    }
+    if (!SAFE_RUN_ID.test(runId)) {
+        throw new UnsafeRecordingIdError(runId, 'it must start with a lowercase letter or digit and contain only [a-z0-9._-] — path ' +
+            'separators, spaces and control characters are not names.');
+    }
+    if (/^\.+$/.test(runId)) {
+        throw new UnsafeRecordingIdError(runId, 'it is only dots, which is path navigation.');
+    }
+    if (WINDOWS_RESERVED.has(runId)) {
+        throw new UnsafeRecordingIdError(runId, `'${runId}' is a reserved device name on Windows, with or without an extension.`);
+    }
+    return `${runId}${ENVELOPE_EXTENSION}`;
+}
+/** Process-local, so two sinks in one process cannot pick one tmp name. */
+let _tmpSeq = 0;
+/**
+ * A directory-backed recording sink — one JSON file per run, written atomically.
+ *
+ * @example
+ * ```ts
+ * const recorder = recordRun(agent);
+ * await agent.run({ message: 'hi' });
+ *
+ * await persistRecording(recorder, {
+ *   sink: fileRecordingSink({ directory: './run-archive' }),
+ *   run: { complete: true },
+ * });
+ * // → ./run-archive/run-1787093273110-1.json
+ * ```
+ */
+export function fileRecordingSink(options) {
+    const directory = options?.directory;
+    if (typeof directory !== 'string' || directory.trim() === '') {
+        throw new TypeError(`[recording-sink] fileRecordingSink({ directory: ${JSON.stringify(directory)} }) names no ` +
+            `directory. Give it a path — it will be created if it does not exist.`);
+    }
+    const fs = lazyRequire('node:fs');
+    const path = lazyRequire('node:path');
+    fs.mkdirSync(directory, { recursive: true });
+    return {
+        async write(envelope) {
+            // Assert the name BEFORE serializing: a refusal should cost nothing, and
+            // an id that cannot be filed should not first be turned into megabytes.
+            const name = recordingFileName(envelope?.run?.runId);
+            const target = path.join(directory, name);
+            let text;
+            try {
+                text = `${JSON.stringify(envelope, null, 2)}\n`;
+            }
+            catch (cause) {
+                // A circular reference or a BigInt inside the recording. Refuse by
+                // name: the alternative is a file that exists and is not the run.
+                throw new TypeError(`[recording-sink] this recording cannot be written as JSON: ${cause instanceof Error ? cause.message : String(cause)}. A run's state must survive structuredClone to be recorded at all, so this ` +
+                    `normally means a value was put into state after the run (a circular object, a ` +
+                    `BigInt). Nothing was written — a partial archive would be worse than none.`);
+            }
+            // Same directory, so the rename is a same-filesystem move and therefore
+            // atomic. `.tmp` can never collide with an archive name: archives always
+            // end in `.json`, these always end in `.tmp`.
+            const tmp = path.join(directory, `${name}.${String(process.pid)}.${String(++_tmpSeq)}.tmp`);
+            try {
+                await fs.promises.writeFile(tmp, text, 'utf8');
+                await fs.promises.rename(tmp, target);
+            }
+            catch (cause) {
+                // Leave no half-written debris behind, but never mask the real error.
+                await fs.promises.rm(tmp, { force: true }).catch(() => undefined);
+                throw cause;
+            }
+            return { id: name, uri: `file://${path.resolve(target)}` };
+        },
+    };
+}
+//# sourceMappingURL=fileRecordingSink.js.map

package/dist/esm/recorders/observability/fileRecordingSink.js.map

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

package/dist/esm/recorders/observability/recordingEnvelope.d.ts

@@ -0,0 +1,292 @@
+/**
+ * recordingEnvelope — the versioned, serialized contract around a recording.
+ *
+ * `recordRun` already freezes a run into `{ events, snapshot, structure }`, and
+ * that shape is exactly right for handing to a viewer in the same process. What
+ * it is NOT is a thing you can put on disk and read back next quarter: it
+ * carries no format marker, no producer version, no statement of which run it
+ * is, and no statement of whether it is the WHOLE run. So every consumer that
+ * wanted to archive one, attach one to a bug report, or feed one to an analysis
+ * tool invented its own wrapper — and each wrapper made a different guess about
+ * the same missing facts.
+ *
+ * This is the producer-owned answer: one envelope, one format string, and every
+ * field either a fact the library can prove or a fact the caller stated.
+ *
+ *   import { persistRecording, fileRecordingSink } from 'agentfootprint/observe';
+ *
+ *   const recorder = recordRun(agent);
+ *   await agent.run({ message });
+ *   await persistRecording(recorder, {
+ *     sink: fileRecordingSink({ directory: './run-archive' }),
+ *     run: { complete: true },
+ *   });
+ *
+ * ## The rule this file exists to keep: never stamp a fact you had to guess
+ *
+ * An envelope is read by people and tools that were not there when the run
+ * happened. That makes every field a claim, and a claim that turns out to be a
+ * guess is worse than a missing field — a missing field sends the reader to
+ * look, a wrong field stops them looking. So each one has a stated source:
+ *
+ *   runId, sessionId,      derived from the EVENT META, which is the only
+ *   principal, tenant      place these are recorded, or stated by the caller.
+ *                          Never synthesized. See "identity" below.
+ *   startedAt / endedAt    derived from event wall clocks, but only where the
+ *                          stream can honestly supply them (see below).
+ *   complete               CALLER INPUT, always. Nothing in a finished
+ *                          recording says whether the run reached its end.
+ *   droppedEvents          read off the live recorder, which counts them; a
+ *                          bare recording carries no count, so it is asked for
+ *                          rather than assumed to be 0.
+ *   configuration          lifted from the run's own `run_configured` event —
+ *                          the manifest, which is names-and-ids only by law.
+ *   producer               read from the package manifests at runtime.
+ *
+ * Where a fact is neither derivable nor supplied, this REFUSES
+ * ({@link IndeterminateRunFactError}) instead of filling in a plausible value.
+ *
+ * ## Identity is never invented
+ *
+ * `principal` and `tenant` come from `EventMeta`, and `EventMeta`'s own law
+ * (see src/events/types.ts) is that they are stamped ONLY from an explicit
+ * `run(input, { identity })` — never from the run's internal identity, and
+ * never from a session id, because "a conversation id is not an actor". By
+ * sourcing them from the meta and nowhere else, this envelope inherits that
+ * guarantee whole: an anonymous run produces an envelope with no `principal`
+ * key at all, not a placeholder and not a session id wearing an actor's name.
+ *
+ * ## `runId` has two namespaces, and this one is deliberate
+ *
+ * A footprintjs snapshot carries its OWN engine-level `runId`
+ * (`<timestamp>-<padded counter>`, minted per `executor.run()`), while the
+ * agentfootprint events carry `run-<timestamp>-<seq>` from `makeRunId()`. They
+ * are different ids for different layers and they do not match. This envelope
+ * uses the EVENT-meta one exclusively, because that is the id `sessionId`,
+ * `principal` and `tenant` ride beside and the one every typed-event consumer
+ * correlates on. When the events cannot supply it, this refuses rather than
+ * falling back to the snapshot's — quietly substituting an id from another
+ * namespace would make two envelopes look comparable when they are not.
+ */
+import type { RunManifestLike } from '../../lib/context-bisect/arms/types.js';
+import type { Recording, RunRecorder } from './recordRun.js';
+/**
+ * The format marker. Bumped only for a change an older reader could not
+ * survive — a reader that does not recognise the string must refuse the file,
+ * never half-read it.
+ */
+export declare const RECORDING_ENVELOPE_FORMAT = "agentfootprint.recording.v1";
+/**
+ * The privacy policy id a `'full'` envelope carries when the caller names none.
+ * A stable string so a retention rule can match on it rather than on prose.
+ */
+export declare const FULL_PRIVACY_POLICY_ID = "agentfootprint.privacy.full.v1";
+/**
+ * What a caller may ASK for. Only `'full'` is implemented in v1; the other two
+ * are named here so the refusal can name them back, and so a consumer writing
+ * against a future version gets a compile-time hint rather than a typo.
+ */
+export type RecordingPrivacyMode = 'full' | 'structure-only' | 'redacted';
+/** Versions of the two libraries that produced the bytes. */
+export interface RecordingProducer {
+    /** This library's version, or `'unknown'` when the manifest is unreadable. */
+    readonly agentfootprintVersion: string;
+    /** The engine underneath it, or `'unknown'`. */
+    readonly footprintjsVersion: string;
+}
+/**
+ * WHICH run this is, and how much of it this is.
+ *
+ * Every field is either derived from the recording's own events or stated by
+ * the caller — see the module header for the per-field source.
+ */
+export interface RecordingRun {
+    /** From `EventMeta.runId` — the agentfootprint run id, not the engine's. */
+    readonly runId: string;
+    /** Present only when the run was session-bound. Never invented. */
+    readonly sessionId?: string;
+    /** The actor the caller NAMED. Absent for an anonymous run. */
+    readonly principal?: string;
+    /** The tenant boundary the caller NAMED. Absent for a single-tenant run. */
+    readonly tenant?: string;
+    /** ISO 8601. The first recorded event's wall clock, unless the caller said. */
+    readonly startedAt: string;
+    /**
+     * ISO 8601. Absent when the recording is not `complete` and the caller named
+     * no end — a run that had not finished has no end time to report.
+     */
+    readonly endedAt?: string;
+    /**
+     * Did this recording capture the run through to its end?
+     *
+     * ALWAYS the caller's statement. A frozen recording looks identical whether
+     * it was taken after the run or from a crash handler mid-run, and there is no
+     * run-terminal event in the registry to check, so the library cannot know.
+     * Defaulting it to `true` would make every crash dump claim to be whole.
+     */
+    readonly complete: boolean;
+    /**
+     * Events discarded to stay under the recorder's `maxEvents` cap. `0` means
+     * "none were dropped", proven — never "we did not look".
+     */
+    readonly droppedEvents: number;
+}
+/** What the agent was configured as — names and ids only, no values. */
+export interface RecordingConfiguration {
+    readonly agentId?: string;
+    /**
+     * The run manifest, as the run itself declared it in
+     * `agentfootprint.agent.run_configured`.
+     *
+     * Safe to archive by construction: the manifest's own law is NAMES AND IDS
+     * ONLY — no endpoints, directories, connection strings or keys — precisely
+     * because it was built to ride into recordings and shared traces.
+     */
+    readonly manifest?: RunManifestLike;
+}
+/** What was done to the bytes before they were stored. */
+export interface RecordingPrivacy {
+    /**
+     * `'full'` — the recording is exactly what `recordRun` captured, unredacted.
+     *
+     * A v1 envelope can say nothing else: the redacting modes are not built, and
+     * this refuses to produce a label it cannot honour.
+     */
+    readonly mode: 'full';
+    /** Names the policy the producer applied. See {@link FULL_PRIVACY_POLICY_ID}. */
+    readonly policyId: string;
+}
+/**
+ * One archived run: the recording, plus everything a reader needs to know what
+ * they are holding.
+ *
+ * Plain JSON by construction — no Dates, no Maps, no live handles — so
+ * `JSON.parse(JSON.stringify(envelope))` is the same envelope. Absent optional
+ * fields are absent KEYS rather than keys with `undefined`, which is what makes
+ * that round trip exact.
+ */
+export interface RecordingEnvelope {
+    readonly format: typeof RECORDING_ENVELOPE_FORMAT;
+    readonly producer: RecordingProducer;
+    readonly run: RecordingRun;
+    readonly configuration?: RecordingConfiguration;
+    readonly privacy: RecordingPrivacy;
+    /** The recording itself, unmodified — `{ snapshot, events, structure }`. */
+    readonly recording: Recording;
+}
+/** A timestamp a caller may state, in any of the three obvious spellings. */
+export type RecordingTimestamp = string | number | Date;
+/** The run facts a caller states — the half the library cannot derive. */
+export interface RecordingRunFacts {
+    /**
+     * Did the recording capture the run through to its end?
+     *
+     * Required, and deliberately so: this is the one field with no derivation and
+     * no safe default, so the API asks rather than guesses. Say `false` for a
+     * recording frozen from a crash handler, a timeout, or mid-stream.
+     */
+    readonly complete: boolean;
+    /** Override the event-derived run id, or supply it when events cannot. */
+    readonly runId?: string;
+    readonly sessionId?: string;
+    readonly principal?: string;
+    readonly tenant?: string;
+    readonly startedAt?: RecordingTimestamp;
+    readonly endedAt?: RecordingTimestamp;
+    /**
+     * Events lost to the recorder's cap. Read off a live `recordRun` handle
+     * automatically; state it when persisting a bare `Recording`, whose shape
+     * carries no count.
+     */
+    readonly droppedEvents?: number;
+}
+/**
+ * Where an envelope goes. One method, so a destination is a few lines: a
+ * directory, an object store, a table, an HTTP endpoint.
+ */
+export interface RecordingSink {
+    /**
+     * Store one envelope.
+     *
+     * @returns `id`   the sink's own handle for what it just stored.
+     *          `uri`  where it landed, when the sink has a meaningful address.
+     */
+    write(envelope: RecordingEnvelope): Promise<{
+        id: string;
+        uri?: string;
+    }>;
+}
+/** Options for {@link persistRecording}. */
+export interface PersistRecordingOptions {
+    readonly sink: RecordingSink;
+    /**
+     * The run facts. Required because {@link RecordingRunFacts.complete} is:
+     * an envelope that did not state whether it holds a whole run is an envelope
+     * whose reader has to guess.
+     */
+    readonly run: RecordingRunFacts;
+    /** Override the manifest lifted from the run's own `run_configured` event. */
+    readonly configuration?: RecordingConfiguration;
+    readonly privacy?: {
+        readonly mode?: RecordingPrivacyMode;
+        readonly policyId?: string;
+    };
+}
+/** Options for {@link buildRecordingEnvelope}. */
+export type BuildRecordingEnvelopeOptions = Omit<PersistRecordingOptions, 'sink'>;
+/** A recording to envelope, or the live handle that is still collecting one. */
+export type RecordingSource = Recording | RunRecorder;
+/**
+ * Raised when a privacy mode is asked for that this version cannot honour.
+ *
+ * Its own class because the answer is never "retry": a caller catching this has
+ * to change what they store or how they store it.
+ */
+export declare class UnsupportedPrivacyModeError extends Error {
+    readonly code: "ERR_UNSUPPORTED_PRIVACY_MODE";
+    readonly mode: string;
+    constructor(mode: string);
+}
+/**
+ * Raised when a required run fact is neither derivable from the recording nor
+ * stated by the caller.
+ *
+ * Carries the `field` so a caller can catch it and supply exactly that one.
+ */
+export declare class IndeterminateRunFactError extends Error {
+    readonly code: "ERR_INDETERMINATE_RUN_FACT";
+    readonly field: string;
+    constructor(field: string, detail: string);
+}
+/**
+ * Freeze a recording into an archivable envelope, without storing it.
+ *
+ * The half of {@link persistRecording} that has no destination — useful when
+ * the envelope goes somewhere this library should not know about (a request
+ * body, a queue), and the unit under test for the contract itself.
+ */
+export declare function buildRecordingEnvelope(source: RecordingSource, options: BuildRecordingEnvelopeOptions): RecordingEnvelope;
+/**
+ * Build the envelope and hand it to a sink.
+ *
+ * @param source   the handle from `recordRun(agent)`, or the recording it made.
+ *                 Prefer the handle: it is the only thing that knows how many
+ *                 events the cap discarded.
+ * @param options  the destination, the run facts, and the privacy statement.
+ *
+ * @example
+ * ```ts
+ * const recorder = recordRun(agent);
+ * await agent.run({ message: 'Weather in San Francisco?' });
+ *
+ * const { uri } = await persistRecording(recorder, {
+ *   sink: fileRecordingSink({ directory: './run-archive' }),
+ *   run: { complete: true },
+ * });
+ * recorder.stop();
+ * ```
+ */
+export declare function persistRecording(source: RecordingSource, options: PersistRecordingOptions): Promise<{
+    id: string;
+    uri?: string;
+}>;