@renzrollon/interlock 1.1.0 → 1.2.0

package/lib/run-log.mjs

@@ -60,12 +60,38 @@ export const RUN_LOG_TYPES = Object.freeze([
   'wave-action',
   'cli-exit',
   'agent-spawn',
+  // What the host observed about one agent after it returned (design D8). Added
+  // under the same schema id: the type is additive, and every reader below
+  // skips a type it does not handle rather than reporting it.
+  'agent-result',
   'verify-judgement',
   'run-halt',
   'run-complete',
   'run-receipt'
 ])
 
+/**
+ * Where an `agent-result` observation came from: the runner host's `claude -p`
+ * envelope, or the agent's own transcript read by the recorder hooks on the
+ * Workflow host. Kept apart because the two do not see the same models
+ * (design D6): a reader must be able to tell which evidence a banner stood on.
+ */
+export const AGENT_RESULT_SOURCES = Object.freeze(['envelope', 'transcript'])
+
+/**
+ * Which observation a model-substitution verdict read (design D6): the agent's
+ * own assistant turns, or the session-wide per-model breakdown that also lists
+ * the host's internal calls.
+ */
+export const MODEL_SCOPES = Object.freeze(['turns', 'session'])
+
+/**
+ * The surfaces a run may record on `run-start` and its receipt (design D14).
+ * Anything else is recorded as absent, so a reader partitioning by surface
+ * counts it with the runs that recorded none rather than inventing a fifth.
+ */
+export const RUN_SURFACES = Object.freeze(['main', 'linked-worktree', 'lane-worktree', 'unknown'])
+
 /** The two modes a run starts in — mirrors `lib/outcomes.mjs`'s `MODES`. */
 export const RUN_MODES = Object.freeze(['checkpoint', 'continue'])
 
@@ -97,7 +123,8 @@ export const AGENT_KINDS = Object.freeze([
 /** Wave-state sources a `wave-action` event may report. */
 export const WAVE_SOURCES = Object.freeze(['create', 'next', 'record-batch', 'record-verify', 'replan'])
 
-const MAX_TEXT = 500
+/** The bound on one free-text field. `lib/interrupted.mjs` bounds a note's reason to the same length. */
+export const MAX_TEXT = 500
 const MAX_NAME = 120
 const MAX_LABEL = 200
 const MAX_COMMAND = 120
@@ -113,6 +140,20 @@ const MAX_HASH = 80
 const MAX_PATH_SET = 200
 const MAX_PATH = 300
 
+/**
+ * How many error strings one `agent-result` may carry, each bounded to
+ * `MAX_TEXT`. A record-shape bound like `MAX_PATH_SET`, for the same reason it
+ * lives here rather than in `lib/limits.mjs`: nothing halts on it, it only
+ * bounds what one event writes. Exported because the runner's adapter bounds
+ * the host record to the same figure before the record reaches the CLI.
+ */
+export const MAX_AGENT_ERRORS = 10
+
+// How many model ids or denied tool names one `agent-result` may carry. A
+// record-shape bound in the same class: a transcript names eight models at most
+// (design D3), and a denial list's whole size travels on its `count`.
+const MAX_AGENT_LIST = 20
+
 function messageOf(err) {
   return (err && err.message) || String(err)
 }
@@ -248,14 +289,83 @@ function hostBlock(value) {
     // Declared separately from `usage` and recorded separately, so a reader can
     // partition a corpus by whether cache figures were obtainable at all rather
     // than averaging a measured figure against an absent one.
-    cacheAccounting: nullableBool(value.cacheAccounting)
+    cacheAccounting: cacheAccountingValue(value.cacheAccounting),
+    // Bounded text, not an enum: a receipt written before the effort
+    // capability existed reads `null` (not recorded), never `flag` or
+    // `unsupported`.
+    effort: nullableText(value.effort, MAX_NAME)
   }
 }
 
+// `true` and `false` as a host declared them, or `'hook'` — the value only a
+// close whose every briefed spawn joined with recorded usage may set (design
+// D5). Tri-state like `nullableBool` for everything else, so a receipt written
+// before `hook` existed reads its boolean exactly as it always did, and a
+// reader partitions "figures obtainable" as `true` or `'hook'`.
+function cacheAccountingValue(value) {
+  if (value === true || value === false || value === 'hook') return value
+  return null
+}
+
 function enumOf(allowed, value, fallback = null) {
   return typeof value === 'string' && allowed.includes(value) ? value : fallback
 }
 
+// A cost the host estimated, in dollars. A number or nothing: `nullableCount`
+// would truncate it to whole dollars and read a numeric string or `true` as a
+// figure. Never added to a price table — it is the host's client-side
+// estimate, kept beside the token figures rather than reconciled with them.
+function nullableAmount(value) {
+  if (typeof value !== 'number' || !Number.isFinite(value) || value < 0) return null
+  return value
+}
+
+// The cache-creation figure of one agent, in the two shapes the sources report
+// (design D2/D3): both lifetime tiers when the source split them, or `{ total }`
+// when it carried only a total and the split is unknown. Tiers win when both
+// are present, and the total is never derived from them nor they from it — the
+// tiers are priced differently and a flattening cannot be undone. `null` for a
+// source that reported no decomposition at all, which is not `{}` and not 0.
+function agentCacheCreation(value) {
+  if (!isObject(value)) return null
+  if ('ephemeral_5m' in value || 'ephemeral_1h' in value) {
+    return { ephemeral_5m: nullableCount(value.ephemeral_5m), ephemeral_1h: nullableCount(value.ephemeral_1h) }
+  }
+  if ('total' in value) return { total: nullableCount(value.total) }
+  return null
+}
+
+// One agent's own usage, element by element. Absent as a whole when the source
+// carried none; a figure the source omitted is `null` inside a present block.
+function agentUsage(value) {
+  if (!isObject(value)) return null
+  return {
+    inputTokens: nullableCount(value.inputTokens),
+    outputTokens: nullableCount(value.outputTokens),
+    cacheReadInputTokens: nullableCount(value.cacheReadInputTokens),
+    cacheCreationInputTokens: agentCacheCreation(value.cacheCreationInputTokens)
+  }
+}
+
+// The host's permission denials for one lane: how many, and which tools. Never
+// the tool input — the host record carries it beside the tool name, and it is
+// whatever command or file body the lane tried to run.
+function permissionDenials(value) {
+  if (!isObject(value)) return null
+  return {
+    count: nullableCount(value.count),
+    tools: nullableStringArray(value.tools, MAX_AGENT_LIST, MAX_NAME)
+  }
+}
+
+// An agent kind that was given is coerced the way `agent-spawn` coerces it, so
+// an unlisted one reads as `other`; one that was never given is absent, because
+// a host record on its own does not say what kind of agent it observed.
+function agentKind(value) {
+  if (typeof value !== 'string' || !value.trim()) return null
+  return enumOf(AGENT_KINDS, value, 'other')
+}
+
 function stringArray(value, max = MAX_TEXT) {
   if (!Array.isArray(value)) return []
   return value.filter(v => typeof v === 'string').map(v => text(v, max))
@@ -314,7 +424,18 @@ const TYPE_FIELDS = {
     // session id records absent; deriving one from the runId, the pid or the
     // timestamp would put a key in the corpus that joins to nothing and looks
     // exactly like one that joins to something.
-    sessionId: source => nullableText(source.sessionId, MAX_NAME)
+    sessionId: source => nullableText(source.sessionId, MAX_NAME),
+    // Where the run ran and where its corpora went (design D14): the surface
+    // the state-home resolver classified, the absolute home this run's
+    // trajectory, outcome line, metrics and resume card were written under, and
+    // the absolute working directory it ran in. A run in a linked worktree
+    // writes its corpora to the main checkout, and a reader of the trajectory
+    // there would otherwise not know which tree the run operated on. Absent on
+    // a trajectory written before these existed, which a reader counts as
+    // surface-unrecorded rather than as any named surface.
+    surface: source => enumOf(RUN_SURFACES, source.surface, null),
+    stateHome: source => nullableText(source.stateHome),
+    cwd: source => nullableText(source.cwd)
   },
   'wave-action': {
     action: source => nullableText(source.action, MAX_ACTION),
@@ -352,6 +473,49 @@ const TYPE_FIELDS = {
     kind: source => enumOf(AGENT_KINDS, source.kind, 'other'),
     taskId: source => nullableText(source.taskId, MAX_NAME)
   },
+  // What the host observed about one agent after it returned (design D8): one
+  // per host record on the runner, appended at the record path before any
+  // tick, and one per joined agent on the Workflow host, appended at close
+  // before the receipt. In the trajectory's fatal class like every other event
+  // here — the caller decides that; this writer only reports.
+  //
+  // The source is a whole host record or a whole sidecar file, which carry the
+  // lane's stdout, its result body and its tool inputs beside these fields, so
+  // every field is named and the three nested groups are built field by field.
+  //
+  // Absent, never zero, throughout: each figure is something a host may or may
+  // not have said, and a reader must be able to tell a lane that was denied
+  // nothing from a lane nobody asked about.
+  'agent-result': {
+    label: source => text(source.label, MAX_LABEL),
+    kind: source => agentKind(source.kind),
+    agentId: source => nullableText(source.agentId, MAX_NAME),
+    source: source => enumOf(AGENT_RESULT_SOURCES, source.source, null),
+    subtype: source => nullableText(source.subtype, MAX_NAME),
+    isError: source => nullableBool(source.isError),
+    terminalReason: source => nullableText(source.terminalReason, MAX_NAME),
+    errors: source => nullableStringArray(source.errors, MAX_AGENT_ERRORS, MAX_TEXT),
+    permissionDenials: source => permissionDenials(source.permissionDenials),
+    sessionId: source => nullableText(source.sessionId, MAX_NAME),
+    numTurns: source => nullableCount(source.numTurns),
+    // The model the run asked for, after the host's model map — the value a
+    // substitution verdict compared against.
+    modelRouted: source => nullableText(source.modelRouted, 60),
+    // Two observations that do not mean the same thing (design D6): the models
+    // of the agent's own assistant turns, and every model the session called,
+    // the host's internal calls included. Both are kept, with the scope the
+    // verdict read, so a reader can see which evidence a banner stood on and
+    // every id the session called, not only the ones that decided.
+    servedModels: source => nullableStringArray(source.servedModels, MAX_AGENT_LIST, MAX_NAME),
+    sessionModels: source => nullableStringArray(source.sessionModels, MAX_AGENT_LIST, MAX_NAME),
+    modelScope: source => enumOf(MODEL_SCOPES, source.modelScope, null),
+    substituted: source => nullableBool(source.substituted),
+    resultMissing: source => nullableBool(source.resultMissing),
+    // The agent's own figures, not the wave's aggregate: a later per-agent
+    // reader's input, and never folded into the receipt's output tokens.
+    usage: source => agentUsage(source.usage),
+    hostCostUsd: source => nullableAmount(source.hostCostUsd)
+  },
   'verify-judgement': {
     context: source => enumOf(VERIFY_CONTEXTS, source.context, null),
     halt: source => boolStrict(source.halt),
@@ -443,7 +607,24 @@ const TYPE_FIELDS = {
     predictedPathsTruncated: source => pathSetTruncated(source.predictedPaths),
     predictedPathsComplete: source => nullableBool(source.predictedPathsComplete),
     predictedPathsReason: source => nullableText(source.predictedPathsReason),
-    degradations: source => stringArray(source.degradations)
+    degradations: source => stringArray(source.degradations),
+    // What the run observed about its agents (design D8): lanes the host
+    // stopped, success envelopes with no structured result, lanes with
+    // permission denials, model substitutions, permission prompts and
+    // auto-mode denials. `null` when no host record and no sidecar was ever
+    // seen, and a measured zero otherwise — a Workflow run with no recorder
+    // saw no agent at all, and filing it as zero would put it beside a run that
+    // watched every lane and found nothing wrong.
+    lanesStoppedByHost: source => nullableCount(source.lanesStoppedByHost),
+    schemaResultsMissing: source => nullableCount(source.schemaResultsMissing),
+    toolsDeniedInLanes: source => nullableCount(source.toolsDeniedInLanes),
+    modelSubstitutions: source => nullableCount(source.modelSubstitutions),
+    permissionPrompts: source => nullableCount(source.permissionPrompts),
+    autoModeDenials: source => nullableCount(source.autoModeDenials),
+    // Where the run ran and where its corpora went, on the same terms as
+    // `run-start` (design D14), so a receipt read on its own still says so.
+    surface: source => enumOf(RUN_SURFACES, source.surface, null),
+    stateHome: source => nullableText(source.stateHome)
   }
 }
 
@@ -513,7 +694,7 @@ function nextSeq(file) {
  * @param {string} root repo root; `.claude/ship/runs` is created beneath it
  * @param {{
  *   runId?: string,
- *   type?: 'run-start'|'wave-action'|'cli-exit'|'agent-spawn'|'verify-judgement'|'run-halt'|'run-complete'|'run-receipt',
+ *   type?: 'run-start'|'wave-action'|'cli-exit'|'agent-spawn'|'agent-result'|'verify-judgement'|'run-halt'|'run-complete'|'run-receipt',
  *   change?: string,
  *   now?: Date|string,
  *   [field: string]: unknown
@@ -762,6 +943,12 @@ export function deriveWaveElapsed(records) {
       current = null
       continue
     }
+    // An `agent-result` is timestamped when the CLI recorded the observation,
+    // not when the agent ran: on the Workflow host that is the close, and
+    // folding it in would pad the last wave with everything between its last
+    // event and the close. On the runner it lands beside the record path's own
+    // events, which already bound the wave, so skipping it loses nothing.
+    if (r.type === 'agent-result') continue
     if (r.type === 'wave-action' && r.wave !== null && r.wave !== undefined && String(r.wave).trim()) {
       current = String(r.wave)
     }