@e2edev/e2e 0.2.0

package/dist/agent/invocation.d.ts

@@ -0,0 +1,194 @@
+/**
+ * One bounded agent invocation (spec 02-test-api.md, 10-determinism.md).
+ *
+ * Every `agent.*` call is a separate invocation with a fresh observation, an
+ * explicit deadline, a model-call budget, and no shared model transcript.
+ */
+import type { StepExecutorContext } from './executor.ts';
+import type { JSONSchema7 } from 'ai';
+import type { AgentCacheContext } from '../cache/context.ts';
+import type { ResolvedConfig } from '../config/resolve.ts';
+import type { TargetSession } from '../backend/surface.ts';
+import type { DebugTrace } from '../internal/debug.ts';
+import { Deadline } from '../internal/time.ts';
+import type { LocatorEngine } from '../locator/engine.ts';
+import type { SecretResolver } from '../locator/screen.ts';
+import type { ArtifactSink } from '../run/fixtures.ts';
+import type { StepRecord, StepRecorder } from '../run/steps.ts';
+import type { VisionMode } from '../types.ts';
+import type { StepExecutor } from './executor.ts';
+import type { ModelRouter } from './model/router.ts';
+import { type AgentObservation } from './observation.ts';
+import type { ProtocolValidation } from './protocol.ts';
+import { type PromptInput } from './prompts.ts';
+/** Attempt-scoped services one agent fixture needs. */
+export interface AgentContext {
+    readonly engine: LocatorEngine;
+    readonly steps: StepRecorder;
+    /** The step executor `agent.act()` dispatches to (RFC0001 layer 4). */
+    readonly executor: StepExecutor;
+    /**
+     * True when the executor came from config rather than the built-in default.
+     * A custom executor also judges `agent.assert` through the socket; the
+     * default path keeps the optimized single-judgment tier.
+     */
+    readonly customExecutor: boolean;
+    /** Chooses the model for a call; a vision call may use a pinned one. */
+    readonly models: ModelRouter;
+    readonly config: ResolvedConfig;
+    /** The target this attempt runs on. */
+    readonly target: StepExecutorContext['target'];
+    /** Completed steps quoted as prior context; serial members see the whole group. */
+    readonly priorSteps: () => readonly StepRecord[];
+    /** Trusted project context: config.agent.context then test/group agentContext. */
+    readonly agentContext: string | undefined;
+    readonly secrets: SecretResolver;
+    /** The attempt's live redactor (SecretLedger); sees values the moment they exist. */
+    readonly redact: (text: string) => string;
+    /** Set once any secret is filled; the viewport stays pixel-tainted after. */
+    readonly taint: {
+        value: boolean;
+    };
+    readonly artifacts: ArtifactSink;
+    readonly signal: AbortSignal;
+    /** The attempt's trace cache, or undefined when caching is off. */
+    readonly cache?: AgentCacheContext;
+    /** `--debug` phase timings; absent when the caller collects none. */
+    readonly debug?: DebugTrace;
+}
+export interface InvocationOptions {
+    /** Public API name, e.g. `agent.assert`. */
+    readonly api: string;
+    /** Caller's instruction, e.g. the target phrase, used for debug step labels. */
+    readonly label?: string;
+    /** Short task description placed in the system message. */
+    readonly task: string;
+    readonly timeoutMs: number;
+    readonly maxModelCalls: number;
+    /**
+     * Whether masked viewport pixels travel alongside the semantic tree.
+     * Additive in every mode: the tree is always sent, and pixel evidence
+     * degrades away under taint or unprovable masking rather than failing the
+     * call. `'fallback'` behaves as `false` for the judgment methods.
+     */
+    readonly vision: VisionMode;
+}
+/** Model-call accounting plus observation/ledger metrics for one invocation. */
+export declare class Invocation {
+    private readonly runtime;
+    private readonly options;
+    readonly deadline: Deadline;
+    private readonly metrics;
+    /**
+     * Trusted system message and serialized prior-step ledger. Both are
+     * invariant for the invocation's lifetime — steps complete only between
+     * invocations — so they are computed exactly once.
+     */
+    private readonly system;
+    private readonly ledger;
+    private inputTokens;
+    private outputTokens;
+    private peakTokensPerCall;
+    private accounting;
+    private estimatedCostUsd;
+    private observationRevision;
+    private explanation;
+    private visionInput;
+    private visionDegraded;
+    /**
+     * Whether this invocation asks for pixel evidence. Readable so a caller can
+     * tell that comparing successive observation trees is meaningless here: an
+     * animation the tree cannot see is still a change a vision call must judge.
+     */
+    readonly pixelTier: boolean;
+    /** Byte size of the invariant system message, measured once. */
+    private readonly systemBytes;
+    constructor(runtime: AgentContext, options: InvocationOptions);
+    get session(): TargetSession;
+    /**
+     * The model this invocation talks to. It follows the pixel tier, so an
+     * escalated fallback invocation asks the pinned vision model — the reason
+     * for escalating is that the cheaper model's tree-only answer missed.
+     */
+    private get adapter();
+    /**
+     * Whether the semantic tree reaches the model.
+     *
+     * `'only'` withholds it: a tree sent next to pixels is a cheaper path to an
+     * answer than looking at them. The observation is still captured, because the
+     * runner hit-tests and reports against it.
+     */
+    get treeWithheld(): boolean;
+    /** Runs one phase through the shared accounting core (see phases.ts). */
+    private instrument;
+    /** Captures and redacts one fresh observation. */
+    observe(): Promise<AgentObservation>;
+    /** Captures one raw observation through the shared race-hardened path. */
+    private captureObservation;
+    /**
+     * Whether this observation should carry pixels. A tainted viewport degrades
+     * the call to tree-only input instead of failing it: the tree is still fully
+     * redacted, and only the unprovable evidence is dropped.
+     */
+    private pixelsRequested;
+    /** Records whether requested pixels actually became model input. */
+    private recordPixels;
+    /**
+     * Records that requested pixels did not become model input.
+     *
+     * Every mode that also sends the tree degrades to it. `'only'` has nothing to
+     * degrade to: continuing would answer a question about what the screen presents
+     * from the tree the caller deliberately excluded, so it fails instead.
+     */
+    private loseVision;
+    /**
+     * Bytes one observation may contribute to a request.
+     *
+     * `agent.maxObservationBytes` is the configured ceiling, but the per-call
+     * token limit binds first on a large screen. Deriving the budget from what the
+     * rest of the request actually costs makes a big screen truncate visibly rather
+     * than fail the adapter's pre-flight check.
+     */
+    private observationByteBudget;
+    /**
+     * Performs one model call, retrying invalid output while budget and deadline
+     * remain. Exhaustion is MODEL_OUTPUT_INVALID, never a guessed success.
+     */
+    ask<Value>(request: {
+        schemaName: string;
+        /** Closed response grammar, or undefined for runner-validated text mode. */
+        schema: JSONSchema7 | undefined;
+        validate: (value: unknown) => ProtocolValidation<Value>;
+        prompt: PromptInput;
+    }): Promise<Value>;
+    /** Records one rejected response payload as a child event. */
+    recordSchemaRejection(name: string): void;
+    /** Records one policy decision as a child event. */
+    recordPolicy(name: string, decision: 'allowed' | 'denied', code?: string): void;
+    /** Records one polling round as a child event. */
+    recordPoll(name: string, round: number): void;
+    /**
+     * Builds a backend operation context: `actionTimeout`, capped by this
+     * invocation's deadline. Each backend call is bounded independently so one
+     * hung observation cannot consume the invocation's whole clock.
+     */
+    operation(): ReturnType<LocatorEngine['operation']>;
+    /** Fails when the invocation deadline has elapsed (see checkStepClock). */
+    checkDeadline(cause?: unknown): void;
+    /** True while the model-call budget and deadline still allow one more call. */
+    canAsk(): boolean;
+    /**
+     * Records the judgment explanation that must survive a later failure, such
+     * as the one `agent.assert` reports. The observation revision is recorded by
+     * `observe()` itself.
+     */
+    note(details: {
+        explanation?: string;
+    }): void;
+    /** Attaches metrics, provenance, and cache status to the enclosing step. */
+    finish(): void;
+    private modelInfo;
+    private consumeModelCall;
+    private recordUsage;
+}
+//# sourceMappingURL=invocation.d.ts.map

package/dist/agent/invocation.d.ts.map

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

package/dist/agent/invocation.js

@@ -0,0 +1,389 @@
+/**
+ * One bounded agent invocation (spec 02-test-api.md, 10-determinism.md).
+ *
+ * Every `agent.*` call is a separate invocation with a fresh observation, an
+ * explicit deadline, a model-call budget, and no shared model transcript.
+ */
+import { timestamp } from '../internal/ids.js';
+import { Deadline } from '../internal/time.js';
+import { agentTrace, observationTrace } from '../internal/trace.js';
+import { AgentError } from './error.js';
+import { boundedOperation, checkStepClock, instrumentPhase, recordPolicyEvent, retryingObserve, } from './phases.js';
+import { serializeLedger } from './ledger.js';
+import { imageTokenUpperBound, ModelOutputInvalidError, tokenUpperBound, } from './model/adapter.js';
+import { prepareObservation } from './observation.js';
+import { POLICY_VERSION, buildPrompt, buildSystem } from './prompts.js';
+const MAX_OUTPUT_TOKENS = 2048;
+/**
+ * Headroom reserved for the method instruction and parameters, in the
+ * byte-scaled units `tokenUpperBound` works in.
+ */
+const INSTRUCTION_RESERVE = 4_096;
+/**
+ * Headroom reserved for one attached screenshot on a vision call, in the same
+ * units.
+ *
+ * The exact cost is only known once the observation reports its viewport, which
+ * is after the observation budget has to be fixed, so this reserves for the
+ * largest viewport worth planning for. It is derived through the same function
+ * the adapter bills with, rather than guessed, so the two cannot drift: a
+ * hard-coded 4,096 was already short of a 1440p capture at 4,784.
+ *
+ * Reserving too much only costs observation bytes when the per-call token ceiling
+ * binds, and there a truncated tree the model can see is better than the
+ * adapter's pre-flight rejecting the call outright. A viewport beyond this is
+ * still safe for that reason: the pre-flight computes the real figure.
+ */
+const PIXEL_RESERVE = imageTokenUpperBound({ width: 2_560, height: 1_440 });
+/** Model-call accounting plus observation/ledger metrics for one invocation. */
+export class Invocation {
+    runtime;
+    options;
+    deadline;
+    metrics = {
+        modelCalls: 0,
+        actionSteps: 0,
+        observationBytes: 0,
+        contextBytes: 0,
+        ledgerBytes: 0,
+    };
+    /**
+     * Trusted system message and serialized prior-step ledger. Both are
+     * invariant for the invocation's lifetime — steps complete only between
+     * invocations — so they are computed exactly once.
+     */
+    system;
+    ledger;
+    inputTokens = 0;
+    outputTokens = 0;
+    peakTokensPerCall = 0;
+    accounting = 'provider';
+    estimatedCostUsd;
+    observationRevision;
+    explanation;
+    visionInput = false;
+    visionDegraded;
+    /**
+     * Whether this invocation asks for pixel evidence. Readable so a caller can
+     * tell that comparing successive observation trees is meaningless here: an
+     * animation the tree cannot see is still a change a vision call must judge.
+     */
+    pixelTier;
+    /** Byte size of the invariant system message, measured once. */
+    systemBytes;
+    constructor(runtime, options) {
+        this.runtime = runtime;
+        this.options = options;
+        this.deadline = runtime.engine.deadline(options.timeoutMs);
+        this.pixelTier = options.vision === true || options.vision === 'only';
+        this.system = buildSystem(options.task, runtime.agentContext);
+        this.systemBytes = tokenUpperBound(this.system);
+        this.ledger = serializeLedger(runtime.priorSteps(), runtime.config.limits.maxLedgerBytes);
+        agentTrace(() => `${options.api} ${JSON.stringify(options.label ?? '')} start ` +
+            `(timeout ${options.timeoutMs}ms, budget ${options.maxModelCalls} calls, ledger ${this.ledger.bytes}B)`);
+    }
+    get session() {
+        return this.runtime.engine.session;
+    }
+    /**
+     * The model this invocation talks to. It follows the pixel tier, so an
+     * escalated fallback invocation asks the pinned vision model — the reason
+     * for escalating is that the cheaper model's tree-only answer missed.
+     */
+    get adapter() {
+        return this.runtime.models.select(this.pixelTier);
+    }
+    /**
+     * Whether the semantic tree reaches the model.
+     *
+     * `'only'` withholds it: a tree sent next to pixels is a cheaper path to an
+     * answer than looking at them. The observation is still captured, because the
+     * runner hit-tests and reports against it.
+     */
+    get treeWithheld() {
+        return this.options.vision === 'only';
+    }
+    /** Runs one phase through the shared accounting core (see phases.ts). */
+    instrument(spec, body, detail) {
+        return instrumentPhase(this.runtime, { ...spec, api: this.options.api }, body, detail);
+    }
+    /** Captures and redacts one fresh observation. */
+    async observe() {
+        this.checkDeadline();
+        const pixels = this.pixelsRequested();
+        const observation = await this.instrument({ kind: 'observation', phase: 'agent.observe' }, async () => {
+            const raw = await this.captureObservation(pixels);
+            return prepareObservation(raw, {
+                redact: this.runtime.redact,
+                maxBytes: this.observationByteBudget(),
+                testIdAttribute: this.runtime.config.testIdAttribute,
+            });
+        }, (prepared) => ({ count: prepared.nodes.size, bytes: prepared.bytes }));
+        // Bytes the request carried, so a withheld tree reads as the zero it is.
+        if (!this.treeWithheld) {
+            this.metrics.observationBytes = Math.max(this.metrics.observationBytes, observation.bytes);
+        }
+        this.observationRevision = observation.revision;
+        if (pixels)
+            this.recordPixels(observation);
+        observationTrace(() => `${this.options.api} ${observation.revision} (${observation.nodes.size} nodes, ${observation.bytes}B${observation.truncated ? ', truncated' : ''}${describePixels(observation)})`, observation.text);
+        return observation;
+    }
+    /** Captures one raw observation through the shared race-hardened path. */
+    captureObservation(pixels) {
+        return retryingObserve({
+            observe: (operation) => this.session.observe(operation, { pixels }),
+            operation: () => this.operation(),
+            guard: (cause) => this.checkDeadline(cause),
+            signal: this.runtime.signal,
+            api: this.options.api,
+        });
+    }
+    /**
+     * Whether this observation should carry pixels. A tainted viewport degrades
+     * the call to tree-only input instead of failing it: the tree is still fully
+     * redacted, and only the unprovable evidence is dropped.
+     */
+    pixelsRequested() {
+        if (!this.pixelTier)
+            return false;
+        if (this.runtime.taint.value) {
+            this.loseVision('PIXEL_TAINTED');
+            return false;
+        }
+        return true;
+    }
+    /** Records whether requested pixels actually became model input. */
+    recordPixels(observation) {
+        const pixels = observation.pixels;
+        if (pixels === undefined) {
+            this.loseVision(observation.pixelsWithheld ?? 'UNSUPPORTED_CAPABILITY');
+            return;
+        }
+        this.visionInput = true;
+        this.metrics.pixelBytes = Math.max(this.metrics.pixelBytes ?? 0, pixels.bytes);
+        this.recordPolicy('vision.pixels', 'allowed');
+    }
+    /**
+     * Records that requested pixels did not become model input.
+     *
+     * Every mode that also sends the tree degrades to it. `'only'` has nothing to
+     * degrade to: continuing would answer a question about what the screen presents
+     * from the tree the caller deliberately excluded, so it fails instead.
+     */
+    loseVision(code) {
+        if (this.visionDegraded !== code) {
+            this.visionDegraded = code;
+            this.recordPolicy('vision.pixels', 'denied', code);
+        }
+        if (this.options.vision !== 'only')
+            return;
+        throw new AgentError('POLICY_DENIED', `${this.options.api} was called with vision: 'only', so the screenshot is its only ` +
+            `evidence, but pixel evidence is unavailable (${code}); it will not answer from the ` +
+            'semantic tree instead');
+    }
+    /**
+     * Bytes one observation may contribute to a request.
+     *
+     * `agent.maxObservationBytes` is the configured ceiling, but the per-call
+     * token limit binds first on a large screen. Deriving the budget from what the
+     * rest of the request actually costs makes a big screen truncate visibly rather
+     * than fail the adapter's pre-flight check.
+     */
+    observationByteBudget() {
+        const { config } = this.runtime;
+        // Nothing of the tree reaches the request, so the per-call token ceiling
+        // does not bind it. The configured ceiling still bounds the walk, and a
+        // fuller node map means a better hit-test for the point that comes back.
+        if (this.treeWithheld)
+            return config.agent.maxObservationBytes;
+        const overhead = this.systemBytes +
+            this.ledger.bytes +
+            INSTRUCTION_RESERVE +
+            (this.pixelTier ? PIXEL_RESERVE : 0);
+        const withinTokenCeiling = Math.max(1_024, config.limits.maxModelTokensPerCall - overhead);
+        return Math.min(config.agent.maxObservationBytes, withinTokenCeiling);
+    }
+    /**
+     * Performs one model call, retrying invalid output while budget and deadline
+     * remain. Exhaustion is MODEL_OUTPUT_INVALID, never a guessed success.
+     */
+    async ask(request) {
+        let repair = request.prompt.repair;
+        this.metrics.contextBytes = tokenUpperBound(this.runtime.agentContext ?? '');
+        this.metrics.ledgerBytes = this.ledger.bytes;
+        for (;;) {
+            this.checkDeadline();
+            this.consumeModelCall();
+            const prompt = buildPrompt({
+                ...request.prompt,
+                ...(this.treeWithheld ? { withholdTree: true } : {}),
+                ledger: this.ledger.text,
+                ...(repair === undefined ? {} : { repair }),
+            });
+            // Pixels travel with the observation they were captured for, so the
+            // image and the tree in one request always describe one revision.
+            const images = imagesFor(request.prompt.observation);
+            try {
+                const result = await this.instrument({ kind: 'model', phase: 'agent.model', name: request.schemaName }, () => this.adapter.generate({
+                    system: this.system,
+                    prompt,
+                    ...(images === undefined ? {} : { images }),
+                    schemaName: request.schemaName,
+                    schema: request.schema,
+                    validate: request.validate,
+                    maxOutputTokens: MAX_OUTPUT_TOKENS,
+                    maxInputTokens: this.runtime.config.limits.maxModelTokensPerCall,
+                    signal: this.runtime.signal,
+                    timeoutMs: Math.max(1, this.deadline.remaining()),
+                }), (generated) => ({
+                    count: generated.usage.inputTokens + generated.usage.outputTokens,
+                }));
+                this.recordUsage(result.usage);
+                return result.value;
+            }
+            catch (cause) {
+                if (cause instanceof ModelOutputInvalidError &&
+                    this.metrics.modelCalls < this.options.maxModelCalls &&
+                    !this.deadline.expired()) {
+                    this.recordSchemaRejection(request.schemaName);
+                    agentTrace(() => `${this.options.api} repair round: ${cause.explanation}`);
+                    repair = {
+                        issue: cause.explanation,
+                        rawText: cause.rawText,
+                    };
+                    continue;
+                }
+                throw cause;
+            }
+        }
+    }
+    /** Records one rejected response payload as a child event. */
+    recordSchemaRejection(name) {
+        this.runtime.steps.recordEvent({
+            kind: 'schema',
+            startedAt: timestamp(),
+            durationMs: 0,
+            status: 'failed',
+            name,
+            code: 'MODEL_OUTPUT_INVALID',
+        });
+    }
+    /** Records one policy decision as a child event. */
+    recordPolicy(name, decision, code) {
+        recordPolicyEvent(this.runtime.steps, name, decision, code);
+    }
+    /** Records one polling round as a child event. */
+    recordPoll(name, round) {
+        this.runtime.steps.recordEvent({
+            kind: 'poll',
+            startedAt: timestamp(),
+            durationMs: 0,
+            status: 'passed',
+            name,
+            count: round,
+        });
+    }
+    /**
+     * Builds a backend operation context: `actionTimeout`, capped by this
+     * invocation's deadline. Each backend call is bounded independently so one
+     * hung observation cannot consume the invocation's whole clock.
+     */
+    operation() {
+        return boundedOperation(this.runtime.engine, this.runtime.config.actionTimeout, this.deadline);
+    }
+    /** Fails when the invocation deadline has elapsed (see checkStepClock). */
+    checkDeadline(cause) {
+        checkStepClock({
+            signal: this.runtime.signal,
+            deadline: this.deadline,
+            api: this.options.api,
+            timeoutMs: this.options.timeoutMs,
+            ...(cause === undefined ? {} : { cause }),
+        });
+    }
+    /** True while the model-call budget and deadline still allow one more call. */
+    canAsk() {
+        return this.metrics.modelCalls < this.options.maxModelCalls && !this.deadline.expired();
+    }
+    /**
+     * Records the judgment explanation that must survive a later failure, such
+     * as the one `agent.assert` reports. The observation revision is recorded by
+     * `observe()` itself.
+     */
+    note(details) {
+        if (details.explanation !== undefined)
+            this.explanation = details.explanation;
+    }
+    /** Attaches metrics, provenance, and cache status to the enclosing step. */
+    finish() {
+        this.runtime.steps.attachAgentDetails({
+            metrics: { ...this.metrics },
+            ...(this.metrics.modelCalls > 0 ? { model: this.modelInfo() } : {}),
+            ...(this.observationRevision !== undefined
+                ? { observationRevision: this.observationRevision }
+                : {}),
+            ...(this.explanation !== undefined ? { explanation: this.explanation } : {}),
+            ...(this.visionInput ? { visionInput: true } : {}),
+            ...(this.treeWithheld ? { visionOnly: true } : {}),
+            ...(this.visionDegraded !== undefined ? { visionDegraded: this.visionDegraded } : {}),
+        });
+    }
+    modelInfo() {
+        const provenance = this.adapter.provenance;
+        return {
+            provider: provenance.provider,
+            model: provenance.model,
+            endpoint: provenance.endpoint,
+            adapterVersion: provenance.adapterVersion,
+            policyVersion: POLICY_VERSION,
+            calls: this.metrics.modelCalls,
+            tokenAccounting: this.accounting,
+            peakTokensPerCall: this.peakTokensPerCall,
+            inputTokens: this.inputTokens,
+            outputTokens: this.outputTokens,
+            ...(this.estimatedCostUsd !== undefined ? { estimatedCostUsd: this.estimatedCostUsd } : {}),
+        };
+    }
+    consumeModelCall() {
+        if (this.metrics.modelCalls >= this.options.maxModelCalls) {
+            throw new AgentError('STEP_BUDGET_EXHAUSTED', `${this.options.api} exhausted its model-call budget of ${this.options.maxModelCalls}`);
+        }
+        this.metrics.modelCalls += 1;
+    }
+    recordUsage(usage) {
+        this.inputTokens += usage.inputTokens;
+        this.outputTokens += usage.outputTokens;
+        this.peakTokensPerCall = Math.max(this.peakTokensPerCall, usage.inputTokens + usage.outputTokens);
+        if (usage.accounting === 'adapter-upper-bound')
+            this.accounting = 'adapter-upper-bound';
+        if (usage.estimatedCostUsd !== undefined) {
+            this.estimatedCostUsd = (this.estimatedCostUsd ?? 0) + usage.estimatedCostUsd;
+        }
+    }
+}
+/** Trace fragment describing what pixel evidence an observation carried. */
+function describePixels(observation) {
+    if (observation.pixels !== undefined) {
+        const { width, height, bytes, maskedRegionCount } = observation.pixels;
+        return `, pixels ${width}x${height} ${bytes}B, ${maskedRegionCount} masked`;
+    }
+    return observation.pixelsWithheld === undefined
+        ? ''
+        : `, pixels withheld (${observation.pixelsWithheld})`;
+}
+/** Image parts for one request, derived from the observation it quotes. */
+function imagesFor(observation) {
+    const pixels = observation?.pixels;
+    if (pixels === undefined)
+        return undefined;
+    return [
+        {
+            data: pixels.data,
+            mediaType: pixels.mediaType,
+            width: pixels.width,
+            height: pixels.height,
+        },
+    ];
+}
+//# sourceMappingURL=invocation.js.map

package/dist/agent/invocation.js.map

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

package/dist/agent/ledger.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Prior-step context for agent prompts (spec 10-determinism.md).
+ *
+ * The ledger is not stored anywhere: it is derived on demand from the step
+ * timeline the run layer already records, so there is exactly one account of
+ * what happened. Serial-group members see each other's prior steps through the
+ * shared accumulator the run layer maintains; independent tests never do.
+ * Entries are untrusted quoted evidence and never carry policy authority.
+ */
+import type { StepRecord } from '../run/steps.ts';
+/** Maximum size of one handoff, before ledger-wide compaction. */
+export declare const MAX_HANDOFF_BYTES = 700;
+export interface LedgerContext {
+    readonly text: string;
+    readonly bytes: number;
+}
+/**
+ * Serializes completed steps as prompt context: newest entries first until the
+ * byte budget is reached, then emitted chronologically with the dropped count
+ * prepended. Labels and handoffs are sanitized and bounded here, at the trust
+ * boundary where they become model input.
+ */
+export declare function serializeLedger(steps: readonly StepRecord[], maxBytes: number): LedgerContext;
+//# sourceMappingURL=ledger.d.ts.map

package/dist/agent/ledger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ledger.d.ts","sourceRoot":"","sources":["../../src/agent/ledger.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAGH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAElD,kEAAkE;AAClE,eAAO,MAAM,iBAAiB,MAAM,CAAC;AAIrC,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,SAAS,UAAU,EAAE,EAAE,QAAQ,EAAE,MAAM,GAAG,aAAa,CAiB7F"}