agentfootprint-lens 0.68.1 → 0.70.0

package/README.md

@@ -1084,6 +1084,100 @@ summary card, the transport and the commentary under a native **More detail**
 Needs agentfootprint ≥ 9.116.0 (the release that ships `AnswerAccount` and the
 op) — the lens's peer floor since 0.68.0.
 
+## Time — what the run took "now" to be, and which window each call read
+
+**Every time decision an armed agent makes, as the record holds it.** With
+agentfootprint's time layer armed (`.time()`, 9.129.0), the run files rows on
+its honesty ledger: the clock it froze for the turn, what it read from the
+person's words, which window each call carries and how, whether a call reads
+MORE than was asked, and how far the wall clock had moved by the time the
+tool ran. `<TimeBand>` draws them; `<ContextView>` mounts it under the
+Findings band, so it moves with the one cursor.
+
+### Why
+
+A time bug is quiet. "Yesterday" sent to a tool that only takes a look-back
+reads from yesterday's midnight to NOW — a day and a half, not a day — and
+the answer looks fine. After a 30-minute pause, a "last hour" look-back reads
+a different hour than the person asked about. The library records each of
+these; this band is where a person sees them: a widened fill says **wider
+than asked** with the extra ranges, a drift says `redrawn` or `shifted` and by
+how much, a result whose held range is unknown says **clock unknown**.
+
+### Mount it
+
+```tsx
+import { ContextView, TimeBand } from 'agentfootprint-lens/context';
+
+<ContextView runner={recording} />            // the band appears once the ledger holds a time row
+
+// or on its own, over rows you already hold:
+<TimeBand rows={state.findingsLedger} coverage={state.coverageDeclared} />
+```
+
+A paused ask with a time field (`requestInput` with `format`) shows its time
+half inside `<AwaitingPane>` — the choices with the library's labels and, on
+a re-ask, the refused value with the library's reason. A `dataset/rows`
+artifact that declares a time axis shows it above the table
+(`<TimeAxisLine meta rows>`), judged by the library: column, unit, zone,
+grain, and how many values have no known clock.
+
+### The laws it keeps
+
+- **Omit, never deny.** No time row at the stop, no band — an unarmed run has
+  no band, never an empty one. A row prints no field it does not carry.
+- **Never infer.** Nothing here compares two instants. `wider than asked`
+  renders only on a row that carries `differs`; a drift only on a call row
+  that carries `drift`; `clock unknown` only where the record says `unknown`;
+  a result check only where the `period` row carries it; `settled by the
+  person` only where a `time-answer` row of the turn names the mention.
+- **No sentence of its own.** Every printed string is a value off the record
+  or a `TIME_LABELS` entry; the one sentence it shows — an ask's refusal
+  reason — is the library's, printed as data.
+
+### One tab: `<TimeView>` (agentfootprint 9.132.0)
+
+```tsx
+import { TimeView } from 'agentfootprint-lens';   // also on 'agentfootprint-lens/context'
+
+<TimeView
+  rows={agent.findings()}                  // the ledger: time rows + period rows
+  coverage={state.coverageDeclared}        // optional — each call's declared period
+  ask={pause}                              // optional — a paused ask with a time field
+  assessment={await agent.assessment()}    // optional — the library's standing
+/>
+```
+
+It draws, in one view: the **time reasons** the library filed on the answer
+(`period-differs-from-asked`, `period-beyond-retention`, `period-not-held`,
+`period-partly-held`, `period-unknown`, `period-undeclared`,
+`derived-from-reading`, and `argument-assumed` when its witness is a period
+argument), each with a plain line and the calls it names; the **time ask**;
+and the **band**. Since 9.132.0 the band also shows the person's **answer**
+to a reading (`settled by the person` · `confirmed` / `edited` · the window
+they settled — the reading's own `open` choice is still printed as filed),
+the values the library **derived from a reading**, each call's **source
+clock** zone, and the `period` row's result checks — **differs from asked**
+(against, the range compared, what was read, `missing`, `extra`), `shifted`
+by how much, and beyond retention.
+
+**The law: never compute a reason.** The standing section lists a reason
+only when the assessment you pass names it; the ledger is read only to
+resolve the library's own witness pointers to the calls they name. A period
+row that carries `differs` with no assessment passed shows the check in the
+band and no reason above it:
+
+```ts
+timeStandingOf(undefined, ledger);                    // undefined — nothing filed, nothing listed
+timeStandingOf(await agent.assessment(), ledger);
+// { standing: 'not-sure', reasons: [{ reason: 'period-differs-from-asked',
+//   calls: [{ toolCallId: 'c1', toolName: 'client_activity' }] }, …] }
+```
+
+Headless: `foldTimeRows(ledger, coverage?)`, `answerOfReading(turn, reading)`,
+`timeStandingOf(assessment, ledger?)`, `timeAskOf(pause)`,
+`datasetTimeAxisOf(meta, rows?)`.
+
 ## The Served tab
 
 **At every LLM call, exactly what the model was served — provable from the log.**