agentfootprint 9.128.1 → 9.131.0

package/dist/esm/core/Agent.js

@@ -124,9 +124,11 @@ import { makeRouteTurnStage } from './agent/stages/routeTurn.js';
 import { applyOutputFallback, } from './outputFallback.js';
 import { assertContinuable, buildCheckpoint, classifyFailurePhase, RunCheckpointError, validateCheckpoint, } from './runCheckpoint.js';
 import { NoConversationError, PendingQuestionError, ResumeIdentityConflictError, RunInFlightError, } from './conversation.js';
-import { applyInputResponse, readAwaitingInput } from './inputRequest.js';
+import { applyInputResponse, readAwaitingInput, } from './inputRequest.js';
 import { applyOutputSchema, OutputSchemaError } from './outputSchema.js';
 import { InvalidRunInputError, normalizeRunInput } from './runInput.js';
+import { clockOf } from './time/rows.js';
+import { draftClock, readRunTime, readTimeOptions, } from './time/clock.js';
 import { buildOutputRetryStage } from './agent/stages/outputRetry.js';
 import { RunnerBase, makeRunId } from './RunnerBase.js';
 import { clampIterations, validateMemoryIdUniqueness, validateToolNameUniqueness, } from './agent/validators.js';
@@ -339,6 +341,20 @@ export class Agent extends RunnerBase {
      *  ask, and that undefined is the whole zero-cost guarantee: no stage, no
      *  witness row, no stamp, no event, no bridge. */
     answerLayerOption;
+    /** `.time()` (the time layer, `core/time/`): the fallback zone, as read.
+     *  Undefined on every agent that did not ask — then no clock is read, no
+     *  time row is filed and `time` on a run is refused. */
+    timeOptions;
+    /** The clock the CURRENT `run()`'s seed stamps — set by `run()` (refusing a
+     *  run with no zone), read by seed through `SeedStageDeps.timeClock`, and
+     *  cleared when `run()` ends, so a later turn this agent did not start (its
+     *  chart mounted in a composition) never stamps a clock nobody declared for
+     *  it (`seedClockDraft`). */
+    runClockDraft;
+    /** The `time` the CURRENT resume passed, as read — TAKEN once by the first
+     *  ToolCalls pass of the resumed leg (`ToolCallsHandlerDeps.time`), and
+     *  cleared when `run()` or `resume()` ends. */
+    resumePassedTime;
     /** Tool choice by classifier (9.105.0, `.toolChoice()`): the classifier,
      *  the serve dial and the app's own doors. Threaded to the tools slot (the
      *  pick and the narrowing), to call-llm (`toolChoice: true`, the outcome
@@ -778,6 +794,18 @@ export class Agent extends RunnerBase {
         else if (typeof opts.answerLayer === 'object' && opts.answerLayer !== null) {
             this.answerLayerOption = opts.answerLayer.standingLine === true ? { standingLine: true } : {};
         }
+        // The time layer's door (`.time()` / `AgentOptions.time`): `true` or the
+        // options, read once; a malformed zone is refused here, at build.
+        if (opts.time !== undefined) {
+            const read = readTimeOptions(opts.time === true ? undefined : opts.time);
+            if ('problem' in read)
+                throw new Error(`Agent: time ${read.problem}.`);
+            this.timeOptions = read.value;
+            // The reader reads only a person's message — a composition hands the
+            // `messageFrom: 'composed'` marker only to a runner that reads it.
+            if (read.value.reader !== undefined)
+                readsMessageFrom(this);
+        }
         if (opts.findings?.argumentSources === true || inputsLayer?.argumentSources === true) {
             this.argumentSourcesArmed = true;
             // Declared sources read `AgentInput.messageFrom` — a composition hands
@@ -1467,6 +1495,10 @@ export class Agent extends RunnerBase {
         // not at the resume of a pause it would have made impossible to resume.
         assertIdentityShape(runInput.identity, 'Agent.run');
         assertIdentityShape(options?.identity, 'Agent.run');
+        // The run's clock (the time layer): read or refused HERE, before the turn
+        // starts — a run with no zone anywhere never runs on the server's zone.
+        const clockDraft = this.clockDraftFor(runInput.time ?? options?.time, 'Agent.run');
+        const engineOptions = withoutTime(options);
         // Timing next, and before the executor exists: both of these refuse a call
         // that would have SUCCEEDED into corrupted per-instance state or an
         // orphaned human question. See ./conversation.ts for why they are throws.
@@ -1498,7 +1530,8 @@ export class Agent extends RunnerBase {
         // (helper used in the catch block below — module-private function
         // declared at file end via hoisting)
         this.answeredAsk = undefined;
-        const executor = this.createExecutor(options);
+        this.resumePassedTime = undefined;
+        const executor = this.createExecutor(engineOptions);
         this.inFlightRunId = this.currentRunContext.runId;
         // One disposition ledger per run (9.60.0) — registration mirrors what
         // this agent's configuration makes applicable; dev posture runs the
@@ -1523,22 +1556,28 @@ export class Agent extends RunnerBase {
         this.lastRunAnswer = undefined;
         // One run can never raise on another run's consent block.
         this.consentOutstanding.clear();
+        // Set here, beside the `try` whose `finally` clears it, so no exit path
+        // can leave it behind for a turn this `run()` did not start.
+        this.runClockDraft = clockDraft;
         try {
             const result = await executor.run({
                 input: {
                     message: runInput.message,
                     ...(this.lastRunIdentity !== undefined && { identity: this.lastRunIdentity }),
                     // A composed message reaches seed only on an agent that reads it
-                    // (declared sources) — every other run's input is the bytes it was.
+                    // (declared sources, or the time layer's reader) — every other run's
+                    // input is the bytes it was.
                     ...(messageFrom === 'composed' &&
-                        this.argumentSourcesArmed === true && { messageFrom: 'composed' }),
+                        (this.argumentSourcesArmed === true || this.timeOptions?.reader !== undefined) && {
+                        messageFrom: 'composed',
+                    }),
                 },
                 // Co-engineered boundary (#16): the engine's loop-iteration limit
                 // (footprintjs 9 default 1000) must never fire BELOW the agent's own
                 // budget — give it headroom (×2 + 10 covers double-hop loop shapes).
                 // Consumer-provided options win.
                 maxIterations: this.maxIterations * 2 + 10,
-                ...(options ?? {}),
+                ...(engineOptions ?? {}),
             });
             const finalized = this.finalizeResult(executor, result);
             if (typeof finalized === 'string')
@@ -1632,6 +1671,11 @@ export class Agent extends RunnerBase {
             throw cause;
         }
         finally {
+            // The time layer's per-run inputs end with the run: a stale draft would
+            // be stamped by the next seed this agent did not start (a composition
+            // mounting its chart) as if the app had declared it.
+            this.runClockDraft = undefined;
+            this.resumePassedTime = undefined;
             // The run's disposition rows, on EVERY path — success, failure, pause —
             // and BEFORE the recording stops, so a recording carries its run's
             // checker accounting (9.60.0).
@@ -1815,6 +1859,79 @@ export class Agent extends RunnerBase {
     identityFor(options, cp) {
         return options?.identity ?? cp.identity;
     }
+    /**
+     * A run's `time`, read into the turn's clock draft (the time layer) — or
+     * refused, before the turn starts: `time` on an agent without `.time()`, a
+     * malformed value, or no zone anywhere (the run's, else the builder's).
+     * `undefined` on an agent without the layer.
+     *
+     * @internal
+     */
+    clockDraftFor(time, runner) {
+        const passed = this.passedTimeFor(time, runner);
+        if (this.timeOptions === undefined)
+            return undefined;
+        const draft = draftClock(passed, this.timeOptions);
+        if (draft === 'no-zone') {
+            throw new InvalidRunInputError({
+                runner,
+                received: 'a run with no time zone',
+                hint: "this agent's time layer needs the person's zone — pass run({ message, time: { zone: " +
+                    "'America/Los_Angeles' } }) or declare a fallback with .time({ zone }); the server's " +
+                    'zone is never used',
+            });
+        }
+        return draft;
+    }
+    /**
+     * The clock draft seed stamps (the time layer): the one `run()` read — or,
+     * for a turn this agent's `run()` did not start (its chart mounted in a
+     * composition, which passes no `time`), the builder's fallback zone with
+     * the turn's start as `now` (`zoneSource: 'builder'`, `nowSource:
+     * 'default'` — the same record a `run()` with no `time` files). With no
+     * fallback zone that turn is refused, as `run()` refuses it: the server's
+     * zone is never used.
+     *
+     * @internal
+     */
+    seedClockDraft() {
+        if (this.runClockDraft !== undefined)
+            return this.runClockDraft;
+        const draft = draftClock(undefined, this.timeOptions ?? {});
+        if (draft === 'no-zone') {
+            throw new InvalidRunInputError({
+                runner: 'Agent (mounted in a composition)',
+                received: 'a turn with no time zone',
+                hint: "this agent's time layer needs the person's zone, and a composition passes no time to " +
+                    "the agents it mounts — declare a fallback with .time({ zone: 'America/Los_Angeles' }); " +
+                    "the server's zone is never used",
+            });
+        }
+        return draft;
+    }
+    /**
+     * A `time` passed to a run or a resume, read — or refused by name: passed to
+     * an agent without `.time()` (a door that ignored it would look configured
+     * and do nothing), or malformed.
+     *
+     * @internal
+     */
+    passedTimeFor(time, runner) {
+        if (time === undefined)
+            return undefined;
+        if (this.timeOptions === undefined) {
+            throw new InvalidRunInputError({
+                runner,
+                received: 'time',
+                hint: 'this agent reads no clock — arm the time layer with .time() to pass time',
+            });
+        }
+        const read = readRunTime(time);
+        if ('problem' in read) {
+            throw new InvalidRunInputError({ runner, received: 'a malformed time', hint: read.problem });
+        }
+        return read.value;
+    }
     /**
      * Install a per-run checkpoint tracker. Listens for the agent's
      * own iteration_end events on `this.dispatcher` and snapshots the
@@ -1910,6 +2027,11 @@ export class Agent extends RunnerBase {
         // answer is a value (often a string) and must stay accepted, so the only
         // sound question is "what was asked?".
         assertIdentityShape(options?.identity, 'Agent.resume');
+        // A resume's `time` (the time layer) is read or refused before anything
+        // moves; it is never applied — the paused turn's clock is kept, and a
+        // differing value is recorded by the ToolCalls resume door.
+        const passedTime = this.passedTimeFor(options?.time, 'Agent.resume');
+        options = withoutTime(options);
         const gate = pauseDemandsDecision(checkpoint.pauseData);
         if (gate && !isCheckInDecision(input))
             throw new DecisionRequiredError(gate, input);
@@ -1941,7 +2063,7 @@ export class Agent extends RunnerBase {
         let answeredAsk;
         if (awaitingInput !== undefined) {
             this.assertNotRunning('Agent.resume');
-            const answered = applyInputResponse(awaitingInput, input);
+            const answered = applyInputResponse(awaitingInput, input, this.timeAnswerContextOf(checkpoint.sharedState));
             if ('cancel' in answered) {
                 throw new TypeError('[input request] Cancel a hosted request through its host, or abandonPause() before starting another run.');
             }
@@ -2022,6 +2144,8 @@ export class Agent extends RunnerBase {
         this.lastRunAnswer = undefined;
         // One run can never raise on another run's consent block.
         this.consentOutstanding.clear();
+        // Beside the `try` whose `finally` clears it (the fresh-run path's terms).
+        this.resumePassedTime = passedTime;
         try {
             const result = await executor.resume(checkpoint, input, resumeOptions);
             const finalized = this.finalizeResult(executor, result);
@@ -2041,6 +2165,8 @@ export class Agent extends RunnerBase {
             throw cause;
         }
         finally {
+            // A resume's passed `time` ends with the resume (the fresh-run path's terms).
+            this.resumePassedTime = undefined;
             // Same terms as the fresh-run path: rows on every exit, before the
             // recording stops (9.60.0).
             this.fileIntegrityDisposition();
@@ -2216,6 +2342,26 @@ export class Agent extends RunnerBase {
             return undefined;
         return structuredClone(spans);
     }
+    /**
+     * What the resume door checks a time field's answer with (the time design
+     * § 6.2, step T4): the paused turn's clock zone — the kept `clock` row, so
+     * a resume that passes another `time` changes nothing — and the app's
+     * catalog overrides. `undefined` without `.time()`: a `format` field is
+     * then judged for shape, order and offset only, in the default words.
+     *
+     * @internal
+     */
+    timeAnswerContextOf(state) {
+        if (this.timeOptions === undefined)
+            return undefined;
+        const ledger = state?.findingsLedger;
+        const zone = clockOf(Array.isArray(ledger) ? ledger : undefined)?.zone;
+        const messages = this.timeOptions.messages;
+        return {
+            ...(zone !== undefined && { zone }),
+            ...(messages !== undefined && { messages }),
+        };
+    }
     /**
      * The findings ledger for a checkpoint (9.101.0) — `foldedSpansOf`'s twin:
      * one reader for `checkpoint()` and the crash carrier, `undefined` when the
@@ -3657,6 +3803,16 @@ export class Agent extends RunnerBase {
             get honestyLayers() {
                 return seededHonestyLayers;
             },
+            // The time layer's clock: the draft `run()` read (refusing a run with no
+            // zone), stamped by seed as the turn's one `clock` row. Absent → the
+            // deps object seed always had.
+            ...(this.timeOptions !== undefined && { timeClock: () => this.seedClockDraft() }),
+            // The time layer's reader: seed reads the person's words once per turn,
+            // after the clock. Absent → nothing is read.
+            ...(this.timeOptions?.reader !== undefined &&
+                this.timeOptions.policy !== undefined && {
+                timeReader: { reader: this.timeOptions.reader, policy: this.timeOptions.policy },
+            }),
             // Declared sources (honesty layer 2): the seed twin plants `_findings.from`
             // on ruled tools, and the run's `messageFrom` constant is written — only
             // under the arm (refused at build without the inputs layer).
@@ -3911,6 +4067,10 @@ export class Agent extends RunnerBase {
             });
             ledgerRestoreArmed = true;
         }
+        // The time layer's rows ride the same ledger: a continued conversation
+        // keeps its earlier turns' clocks (each turn files its own).
+        if (this.timeOptions !== undefined)
+            ledgerRestoreArmed = true;
         // The gate's admissible set, for the record (9.50.0): declared hops from
         // the cursor plus the open skills — the SAME two resolvers the read_skill
         // offer and the refusal messages are built from (`readSkillOfferFor`),
@@ -4126,6 +4286,16 @@ export class Agent extends RunnerBase {
             // The inputs layer (honesty layer 2): the same site decorates a ruled
             // tool's schema first — value-conditional, the same grammar.
             ...(inputsArmed && { inputsLayer: true }),
+            // …and, under `.time({ reader })` (step T6b), the ONE served time sentence on each tool
+            // that declares a period: the windows the reader settled this turn, in that tool's form.
+            ...(inputsArmed &&
+                this.timeOptions?.reader !== undefined && {
+                timeWindows: {
+                    ...(this.timeOptions.zone !== undefined && { appZone: this.timeOptions.zone }),
+                },
+            }),
+            // …and, under `.time()` (step T8), the turn's time limits in the same line.
+            ...(inputsArmed && this.timeOptions !== undefined && { timeLimits: true }),
             // …and, under declared sources, plants `_findings.from` on ruled tools only.
             ...(argumentSources && { argumentSources: true }),
             // Tool choice by classifier (9.105.0): the pick and the narrowing live
@@ -4177,6 +4347,10 @@ export class Agent extends RunnerBase {
             // constant on every call, under the one gate — an unarmed agent reads
             // no new key.
             ...(this.ontology !== undefined && { ontology: true }),
+            // The time layer's served line (step T6b): read only where the Tools
+            // mount can compose it — the `timeReader` arm of the chart deps.
+            // Step T8 widens it to `.time()`: the same line then carries the turn's time limits.
+            ...(inputsArmed && this.timeOptions !== undefined && { timeLine: true }),
             // The receipt's salt (9.88.0) — read per call, like seed's own accessor.
             getRunId: () => this.currentRunContext?.runId,
             // …and its off switch. Value-conditional, so an agent on the default
@@ -4343,6 +4517,9 @@ export class Agent extends RunnerBase {
                         return rules.ruled.find((r) => r.argument === argument)?.assume;
                     }),
                     answeredValues: answeredValuesOf,
+                    // Under `.time()` (step T7): the turn's time spellings by
+                    // lineage — said ones exempt, derived ones filed, not flagged.
+                    ...(this.timeOptions !== undefined && { timeLineage: true }),
                 }),
             }
             : undefined, 
@@ -4526,6 +4703,28 @@ export class Agent extends RunnerBase {
             // never allocates it.
             currentRun: () => this.toolRunFacts(),
             answeredAsk: () => this.answeredAsk,
+            // The time layer: each dispatched call files its `call` row, and the
+            // resume door compares a resume's passed `time` with the kept clock.
+            ...(this.timeOptions !== undefined && {
+                time: {
+                    takePassedOnResume: () => {
+                        const passed = this.resumePassedTime;
+                        this.resumePassedTime = undefined;
+                        return passed;
+                    },
+                    ...(this.timeOptions.zone !== undefined && { appZone: this.timeOptions.zone }),
+                    // The reader (step T6b): the batch ask asks an open mention's window.
+                    ...(this.timeOptions.reader !== undefined &&
+                        this.timeOptions.policy !== undefined && {
+                        reader: {
+                            policy: this.timeOptions.policy,
+                            ...(this.timeOptions.messages !== undefined && {
+                                messages: this.timeOptions.messages,
+                            }),
+                        },
+                    }),
+                },
+            }),
             emitForRun: (type, payload, runContext) => this.emitLateFact(type, payload, runContext),
             toolSessions: () => this.toolSessions(),
             // 8.6.0 — what a run does when a declared credential needs 3LO consent.
@@ -4617,6 +4816,13 @@ export class Agent extends RunnerBase {
                 inputsLayer: {
                     toolOf: (toolName) => resolveForLayer(toolName).tool,
                     ...(this.toolMiddleware.length > 0 && { rewrites: true }),
+                    // The time layer (step T5a): a tool whose period declares forms is filled from the
+                    // turn's one window, bound to the person's window, or recorded as the model's.
+                    ...(this.timeOptions !== undefined && {
+                        time: {
+                            ...(this.timeOptions.zone !== undefined && { appZone: this.timeOptions.zone }),
+                        },
+                    }),
                     // Declared sources: the layer reads `_findings.from` and checks it against
                     // the corpora the mount hands in — the app's `externalGrounds` among them.
                     ...(argumentSources && {
@@ -4677,6 +4883,12 @@ export class Agent extends RunnerBase {
             // gets the stage that appends nothing and carries the limits as data.
             ...(this.limitsTravelWithTheAnswerValue && !limitsAsData && { attachCoverageLimits: true }),
             ...(limitsAsData && { coverageLimitsAsData: true }),
+            // The time layer: the prose limits block renders its `Period:` lines in
+            // the run's clock zone. Absent → the final stage it always mounted.
+            ...(this.timeOptions !== undefined && { timeLayer: true }),
+            // The reader (step T6b): the Tools mount hands the slot the turn's settled windows.
+            ...(inputsArmed && this.timeOptions?.reader !== undefined && { timeReader: true }),
+            ...(inputsArmed && this.timeOptions !== undefined && { timeLimits: true }),
             ...(this.answerValidationConfig !== undefined && { hasAnswerValidation: true }),
             // The out-of-budget wrap-up branch (9.56.0) — the conditional-mount law
             // above, decided once beside the Route decider that routes to it so the
@@ -4739,4 +4951,16 @@ function boundInsertionOrder(held, max) {
         held.delete(oldest.value);
     }
 }
+/**
+ * The run options without the time layer's `time` — what the engine is handed.
+ * The SAME object when it carries no `time` key, so a run that passed none
+ * hands the executor exactly the options it always did.
+ */
+function withoutTime(options) {
+    if (options === undefined || !('time' in options))
+        return options;
+    const { time: _time, ...rest } = options;
+    void _time;
+    return rest;
+}
 //# sourceMappingURL=Agent.js.map