agentfootprint 9.127.0 → 9.129.0

package/dist/core/Agent.js

@@ -153,6 +153,8 @@ const conversation_js_1 = require("./conversation.js");
 const inputRequest_js_1 = require("./inputRequest.js");
 const outputSchema_js_1 = require("./outputSchema.js");
 const runInput_js_1 = require("./runInput.js");
+const rows_js_1 = require("./time/rows.js");
+const clock_js_1 = require("./time/clock.js");
 const outputRetry_js_1 = require("./agent/stages/outputRetry.js");
 const RunnerBase_js_1 = require("./RunnerBase.js");
 const validators_js_1 = require("./agent/validators.js");
@@ -365,6 +367,20 @@ class Agent extends RunnerBase_js_1.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
@@ -804,6 +820,18 @@ class Agent extends RunnerBase_js_1.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 = (0, clock_js_1.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)
+                (0, messageFrom_js_1.readsMessageFrom)(this);
+        }
         if (opts.findings?.argumentSources === true || inputsLayer?.argumentSources === true) {
             this.argumentSourcesArmed = true;
             // Declared sources read `AgentInput.messageFrom` — a composition hands
@@ -1493,6 +1521,10 @@ class Agent extends RunnerBase_js_1.RunnerBase {
         // not at the resume of a pause it would have made impossible to resume.
         (0, callerIdentity_js_1.assertIdentityShape)(runInput.identity, 'Agent.run');
         (0, callerIdentity_js_1.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.
@@ -1524,7 +1556,8 @@ class Agent extends RunnerBase_js_1.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
@@ -1549,22 +1582,28 @@ class Agent extends RunnerBase_js_1.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')
@@ -1658,6 +1697,11 @@ class Agent extends RunnerBase_js_1.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).
@@ -1841,6 +1885,79 @@ class Agent extends RunnerBase_js_1.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 = (0, clock_js_1.draftClock)(passed, this.timeOptions);
+        if (draft === 'no-zone') {
+            throw new runInput_js_1.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 = (0, clock_js_1.draftClock)(undefined, this.timeOptions ?? {});
+        if (draft === 'no-zone') {
+            throw new runInput_js_1.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 runInput_js_1.InvalidRunInputError({
+                runner,
+                received: 'time',
+                hint: 'this agent reads no clock — arm the time layer with .time() to pass time',
+            });
+        }
+        const read = (0, clock_js_1.readRunTime)(time);
+        if ('problem' in read) {
+            throw new runInput_js_1.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
@@ -1936,6 +2053,11 @@ class Agent extends RunnerBase_js_1.RunnerBase {
         // answer is a value (often a string) and must stay accepted, so the only
         // sound question is "what was asked?".
         (0, callerIdentity_js_1.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 = (0, pause_js_1.pauseDemandsDecision)(checkpoint.pauseData);
         if (gate && !(0, checkin_js_1.isCheckInDecision)(input))
             throw new pause_js_1.DecisionRequiredError(gate, input);
@@ -1967,7 +2089,7 @@ class Agent extends RunnerBase_js_1.RunnerBase {
         let answeredAsk;
         if (awaitingInput !== undefined) {
             this.assertNotRunning('Agent.resume');
-            const answered = (0, inputRequest_js_1.applyInputResponse)(awaitingInput, input);
+            const answered = (0, inputRequest_js_1.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.');
             }
@@ -2048,6 +2170,8 @@ class Agent extends RunnerBase_js_1.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);
@@ -2067,6 +2191,8 @@ class Agent extends RunnerBase_js_1.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();
@@ -2242,6 +2368,26 @@ class Agent extends RunnerBase_js_1.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 = (0, rows_js_1.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
@@ -3683,6 +3829,16 @@ class Agent extends RunnerBase_js_1.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).
@@ -3937,6 +4093,10 @@ class Agent extends RunnerBase_js_1.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`),
@@ -4552,6 +4712,18 @@ class Agent extends RunnerBase_js_1.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 }),
+                },
+            }),
             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.
@@ -4643,6 +4815,13 @@ class Agent extends RunnerBase_js_1.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 && {
@@ -4703,6 +4882,9 @@ class Agent extends RunnerBase_js_1.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 }),
             ...(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
@@ -4766,4 +4948,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