agentfootprint
Version:
The explainable agent framework — backtrack a wrong answer to the exact context that caused it (evidence, not guesses). Built on footprintjs.
232 lines (231 loc) • 13.4 kB
TypeScript
/**
* hosting/ingressRecord — what the door decided, for the requests that never
* became a run.
*
* await standingAgent({
* agent, sessions, host,
* identity: { verify },
* admission: turnsPerHour({ limit: 60 }),
* onIngressDecision: (record) => myAuditSink.write(record),
* });
*
* ── The gap this closes, named exactly ───────────────────────────────────────
* `auditExport()` is a record of RUNS. A 401 out of `identity.verify` and a 429
* out of `admission.decide` both happen before a run exists — no agent has been
* built, no observer is attached, no typed event is emitted — so neither is in
* the bundle. Two independent review rounds wrote that down as the same finding,
* and the honest consequence is the sharp one: **an empty bundle is not evidence
* that nobody was turned away.** It is evidence that nobody ran.
*
* This is the seam where the turned-away go. One record per request the composer
* decided, handed to a sink you own, at the moment the reply reaches its
* terminal.
*
* ── What it is NOT, said before anything else ────────────────────────────────
* **It does not join the audit hash chain.** Nothing here is hashed, chained,
* sequenced against `auditExport()`'s records, or verifiable by
* `verifyAuditBundle`. It is a STREAM you chain into your own sink. Saying
* otherwise would make this fix the exact failure it exists to close — a
* mechanism that looks like evidence and is not. If you need ingress decisions
* inside a tamper-evident chain, write them into the same store your audit
* bundle lands in and chain them there, where the sequence is yours to define.
*
* ── Secrets never travel ─────────────────────────────────────────────────────
* A record carries the CLASS of what happened and the identifiers the caller
* already knew. Never the bearer token, never a header, never a claim set,
* never an error's message — the `sdkFailure` law, applied to the front door.
* `errorName` and `errorCode` are this package's own vocabulary; a message may
* carry an SDK's text, an operator's sentence or a store's detail, so no message
* is copied. The one identity field is `userId`, and it is the id the token
* PROVED — never one a request merely claimed.
*
* ── What the composer can decide, and what it never sees ─────────────────────
* Every ingress exit of `standingAgent` funnels through one reply terminal, so
* all of these land here — including the ones a consumer's own `verify` and
* `decide` never observe:
*
* - a request with no `Authorization: Bearer …` at all (`verify` is never
* called, so nothing you wrote could have logged it);
* - a verifier that could not answer (503) as distinct from a bad credential;
* - an admission refusal, and also an admission ALLOW — the census is what
* makes an absence readable;
* - a turn or a transcript naming somebody else's session (the 404 that is
* deliberately indistinguishable from "no such session");
* - a session op at a door with no verifier, a store with no owner index, a
* concurrent-run refusal, an artifact ref that did not resolve;
* - and a request that was SERVED.
*
* The HOST's own decisions land here too, though no handler ever saw them: a
* request its door guard turned away (a content type any page can send, a
* foreign Origin, a Host it was not configured for — `'cross-site-refused'`)
* and a session id over the bound (`'refused'`), at the request door and the
* conversation door alike. They arrive through the host's `onRefusal`, which
* the composer subscribes to whenever a sink is set, and they carry the same
* classes and nothing more — door `'request'` or `'conversation'`, because a
* forged request is refused before its body says which of the three doors it
* wanted.
*
* What it does not carry, stated rather than implied: a body the TRANSPORT
* refused as MALFORMED — unparseable JSON, a body over `maxBodyBytes`, or an
* `op` this host's wire grammar does not speak (`InvalidWireOpError`, answered
* 400 by `httpHost` inside its own request reader). That is a broken request
* rather than a decision about a caller, and the composer does not claim it.
* Your HTTP access log has it.
*
* Pattern: Observer at a composition boundary. Zero-cost when unset — with no
* sink configured nothing is built, nothing is wrapped, and the reply object the
* handler uses is the host's own, to the byte.
*/
import { type VerifiedIdentity } from './identityVerification.js';
import { type IdentityFailureClass } from './errors.js';
import type { ArtifactHandOverFailedPayload } from '../events/payloads.js';
import type { HostRefusal, HostReply, HostRequest } from './types.js';
/**
* Which door this request knocked at.
*
* - `'turn'`, `'session-op'`, `'artifact'` — the composer's three doors, for
* every request the host handed on.
* - `'request'` — the host's one-exchange door, for a request the HOST refused
* before the composer saw it (the door guard; the session-id bound). Which
* of the three it was headed for is deliberately not recorded: a forged
* request is refused on its headers, and its body is never parsed.
* - `'conversation'` — a conversation upgrade the host refused before the 101.
* Recorded here because it is the same host's door and the same census,
* though the composer itself never serves conversations.
*/
export type IngressDoor = 'turn' | 'session-op' | 'artifact' | 'request' | 'conversation';
/**
* How the door answered — coarse on purpose, because this is the field a
* dashboard groups by. `errorCode` carries the precision beside it.
*
* - `'served'` — the reply reached a DELIVERING terminal: an answer, a
* question a person must answer, a transcript, a listing, an artifact.
*
* Read it as **delivered**, not as *admitted*. The record is filed at the
* terminal the reply actually reached, and a failure is not a delivery — so
* a request the door admitted whose RUN, store or provider then broke ends
* at `reply.fail` and is filed `'failed'` (or `'refused'`, when the error
* names itself with an `ERR_…` code), carrying that error's class. It is
* NOT `'served'`. To count what the door let through, count everything that
* is not one of the door's own refusals — `'identity-refused'`,
* `'verifier-unavailable'`, `'admission-refused'`, `'session-refused'` — or
* read `admission`, which is the verdict a policy actually returned and is
* present on a refused record and a broken one alike.
* - `'identity-refused'` — 401. The credential did not identify anybody, or
* none arrived at a door that insists.
* - `'verifier-unavailable'` — 503. The verifier could not do its job; the
* caller's token was never judged and this is not their fault.
* - `'admission-refused'` — 429. A policy said no before any work started.
* - `'session-refused'` — the one indistinguishable not-found: a session that
* does not exist, belongs to somebody else, or names no owner.
* - `'cross-site-refused'` — the host's door guard turned it away before any
* handler saw it: a content type a page on any site can send (415), a
* browser Origin this door does not allow (403), a Host it was not
* configured for (421). `errorCode` says which. Not proof of an attack — a
* script that forgot `content-type: application/json` lands here too — but
* the shape every forged request has, counted where it can be seen.
* - `'refused'` — every other refusal the door made by name (a session op with
* no verifier configured, a store with no owner index, a concurrent run, an
* artifact ref that did not resolve, a pause the wire could not carry, a
* session id over the ceiling).
* - `'failed'` — the request ended in an error that is not one of the door's
* own refusals. Usually the run, the store or the provider — which is why
* an admitted request that then broke lands HERE and not in `'served'`.
*/
export type IngressOutcome = 'served' | 'identity-refused' | 'verifier-unavailable' | 'admission-refused' | 'session-refused' | 'cross-site-refused' | 'refused' | 'failed';
/** What an admission policy answered, when one was consulted. */
export type IngressAdmissionVerdict = 'allow' | 'queue' | 'refuse';
/**
* One decision the door made, as plain data.
*
* Every field is either a class of what happened or an identifier the caller
* already had. Nothing here is a secret, and nothing here is a message.
*/
export interface IngressRecord {
/** When the request left the door, `Date.now()`. */
readonly at: number;
/** Which door it knocked at. */
readonly door: IngressDoor;
/** The wire op it named, in the spelling a body uses. Absent for a turn. */
readonly op?: string;
/** How the door answered. */
readonly outcome: IngressOutcome;
/** The refusal's own `code` (`'ERR_IDENTITY_NOT_VERIFIED'`, …). Never a message. */
readonly errorCode?: string;
/** The error's class name, for a failure this package did not author. */
readonly errorName?: string;
/** WHICH token check failed — the whole vocabulary a refusal may say about a
* credential, and never one character of the credential. */
readonly identityFailure?: IdentityFailureClass;
/** `true` when the refused request also NAMED a user it could not prove —
* the impersonation shape, kept separate so a sink can count it. */
readonly claimedUser?: boolean;
/** The id the token PROVED, when one was proven. Never a claimed one. */
readonly userId?: string;
/** The conversation this request named, when it named one. */
readonly sessionId?: string;
/** Whether a bearer credential was PRESENT. Never its value. */
readonly bearerPresent: boolean;
/** What the admission policy answered, when one was consulted. */
readonly admission?: IngressAdmissionVerdict;
/**
* This turn's artifact hand-over (`HostReply.turnArtifacts`) did not go
* cleanly — the FIRST failure of it: the host's hook threw, an operation it
* started failed, it outran `turnArtifactsTimeoutMs`, or the caller hung up
* first. The reply was delivered regardless — the hand-over never decides the
* terminal, so `outcome` still says what the caller got. The per-request
* census of what `agentfootprint.artifacts.hand_over_failed` reports on the
* serving agent's stream, in the same shape: class only, never the message.
*/
readonly turnArtifactsFailure?: ArtifactHandOverFailedPayload;
}
/**
* Where records go — {@link StandingAgentBaseOptions.onIngressDecision}.
*
* Called once per request, synchronously, at the moment the reply reaches its
* terminal. A sink that throws is contained (a broken log must not turn a served
* request into a failed one) and reported once on `console.warn`, because a
* silently-dropped security record is the failure this whole seam exists to
* close. Do the slow part yourself: buffer, batch, and never `await` the network
* inside it.
*/
export type IngressSink = (record: IngressRecord) => void;
/**
* The per-request bookkeeping: the facts known at the door, the facts learned
* on the way in, and the ONE record that leaves.
*
* Built only when a sink is configured. `settle` is idempotent — the first
* terminal wins, and a reply that somehow reaches two of them (a host that
* completes and then fails) still produces exactly one record, because two
* records for one request would be a census that over-counts.
*/
export interface IngressNote {
/** Wrap the host's reply so its first terminal files the record. */
watch(reply: HostReply): HostReply;
/** The verifier proved somebody — record the proven id, never a claimed one. */
identified(verified: VerifiedIdentity | undefined): void;
/** An admission policy answered. */
admitted(verdict: IngressAdmissionVerdict): void;
/** The turn's artifact hand-over failed — the first failure is recorded. */
turnArtifactsFailed(failure: ArtifactHandOverFailedPayload): void;
/** File the record for a request that left without any terminal at all. */
settle(): void;
}
/**
* File the record for a request the HOST refused before the composer saw it —
* what `standingAgent` hands to the host's `onRefusal` when a sink is set.
*
* Built from the refusal's class and the fact of a credential, exactly as a
* composer refusal is: no message, no header, no session id (a session id the
* bound refused is the one thing this record must never carry), no user —
* nothing was verified, because nothing got that far.
*
* @internal — the option is public, this bookkeeping is not.
*/
export declare function recordHostRefusal(refusal: HostRefusal, sink: IngressSink): void;
/**
* Begin one request's ingress record.
*
* @internal — the option is public, this bookkeeping is not.
*/
export declare function beginIngress(request: HostRequest, sink: IngressSink): IngressNote;