@usine/core 0.2.0 → 0.4.0

package/README.md

@@ -1,35 +1,62 @@
 # @usine/core
 
-Domain model for [usine](https://github.com/basaltbytes/usine), an agent-agnostic software factory: the Event → Run → Step → Attempt vocabulary every other block types against, plus the shared instance, repository, worker, and agent values.
+Domain model for [usine](https://github.com/basaltbytes/usine): event, run, step, and attempt types for every other block, plus shared instance, repo, worker, and agent values.
 
-Import each domain concept from its owning subpath. Identities, records, and operations share that domain module.
+0.x APIs change without notice. Supply the peer dependency `effect` at the pinned version.
+
+## Subpaths
 
 | Subpath | Exports |
 | --- | --- |
 | `@usine/core/event` | `Event`, `EventId`, `DedupKey` |
-| `@usine/core/run`, `@usine/core/run/state` | `Run`, `RunId`; the run state machine as a tagged union with typestate transitions (`RunState.start`, `RunState.supersede`, ...) |
+| `@usine/core/run`, `@usine/core/run/state` | `Run`, `RunId`; the run state machine as a tagged union with typestate transitions (`RunState.start`, `RunState.supersede`, and others) |
 | `@usine/core/step`, `@usine/core/step/result` | `Step`, `StepName`; `StepResult` and its facts (`Commit`, `PullRequest`, `Comment`) |
-| `@usine/core/attempt` | `Attempt`, `AttemptId`, `AttemptNumber`, `AttemptTask`, `shouldAutoRetry` |
+| `@usine/core/step/harvest` | `harvestFacts`, `harvestPostedComments`, `HarvestError`, `HarvestSpec`, `AttemptWindowsRead`: the commits and pull requests in an attempt's finished checkout, and the comments and reviews it posted on its item, read with the caller's `git`/`gh` runner |
+| `@usine/core/attempt` | `Attempt`, `AttemptId`, `AttemptNumber`, `AttemptTask`, `shouldAutoRetry`, and `AttemptWindow`, `windowOf`, `windowHolds`, `windowsOverlap`, `AttemptWindows` |
 | `@usine/core/attempt/outcome` | `AttemptSucceeded`, `AttemptFailed`, `AttemptCanceled`, `AttemptOutcome` |
 | `@usine/core/attempt/failure` | `InfraFailure`, `DefectFailure`, `AgentFailure`, `RunawayFailure`, `ChildSessionBudgetFailure`, `AttemptFailure`, `isAutoRetryableFailure` |
-| `@usine/core/attempt/channel` | The protocol-v4 attempt channel: `RunSpec`, `Start`, the envelopes, and the `admit` reducer. Import it as a namespace (`AttemptChannel.Started`) |
-| `@usine/core/agent`, `@usine/core/agent/brain`, `@usine/core/agent/session` | `Agent`, `AgentName`, `AgentPersona`, parent-model resolution; `BrainSpec`, `ModelId`, `Harness`, `Effort`; `AgentSessionId`, session descriptors, `AgentSessionEvent`, `ChildSessionBudget`, `ChildSessionCount` |
+| `@usine/core/attempt/salvage` | `SalvageRef`, `salvageRefFor`, `SalvagePushed`, `SalvageRetained`, `AttemptSalvage`, `AttemptRecovery`, `RecoverySink` (its `windows` reads the windows a recovered attempt's harvest needs) |
+| `@usine/core/attempt/start` | Why an attempt started: `StartedByEvent`, `StartedByRetry`, `StartedByEditAndRetry` (with the operator login), `StartedByInfraRetry`, `StartedAfterRestart`, `AttemptStart`, `OperatorRetryStart` |
+| `@usine/core/attempt/channel` | `RunSpec`, versioned envelopes, the `Sink` (stores envelopes, reads the `transcript` and the harvest's `windows`), and the `admit` reducer. Import as a namespace (`AttemptChannel.Started`). |
+| `@usine/core/agent`, `/agent/brain`, `/agent/session` | `Agent`, `AgentName`, `AgentPersona`, parent model resolution, `githubSignature` (the last line of an agent's GitHub comments); `BrainSpec`, `ModelId`, `Harness`, `Effort`; `AgentSessionId`, session descriptors, `AgentSessionEvent`, `ChildSessionBudget`, `ChildSessionCount` |
 | `@usine/core/agent/capability` | `HarnessCapability`, `HarnessReady`, `HarnessUnavailableError`, and the credential-free `HarnessReadiness` preflight response |
-| `@usine/core/repository` | `RepositoryName`, `RepositoryRevision`, `CommitSha`, `splitRepositoryName`, `canonicalRepositoryName` |
-| `@usine/core/worker`, `@usine/core/item`, `@usine/core/loop`, `@usine/core/instance` | `WorkerName`, `WorkerKind`; `ItemKey`, `ItemNumber`; `LoopName`, `ApprovalRequirement`; `InstanceDirectory` |
+| `@usine/core/repository` | `RepositoryName`, `RepositoryRevision`, `CommitSha`, `safeSegment`, `splitRepositoryName`, `canonicalRepositoryName` |
+| `@usine/core/worker`, `/item`, `/loop`, `/instance` | `WorkerName`, `WorkerKind`, `GatewayCredentialKind`; `ItemKey`, `ItemNumber`; `LoopName`, `ApprovalRequirement`; `InstanceDirectory` |
+| `@usine/core/cycle-budget` | `CycleLimit`, `CycleGeneration`, `CycleCount`, `LoopCycleCount`, `CycleBudgetAsk` |
+
+Branded schemas are exported under their brand name, as a value and a type. `PullRequest` and `Comment` facts use `URL` values in memory and strings in JSON, so step results round-trip through the channel and durable storage.
+
+## Runs
+
+The run state machine is `pending → waiting → queued → running → succeeded / failed / canceled`, plus `failed → running` on operator retry. `RunState.operatorActions(state)` returns which of approval, retry, failure resolution, cancel, and run again apply. Command handlers share these typed transitions.
+
+- Run again opens a new run for the item state of a succeeded or canceled run. `RunAgain` (`/run/again`) records the original run and who asked.
+- Failure resolution applies only in the failed state; operator views also hide it once the latest failed attempt is resolved.
+
+An item-level `CycleBudgetAsk`, which can exist before another run opens, records the exhausted loop, its limit, and the participating loops' admitted and completed runs.
+
+## Attempts
+
+Each attempt records its child `BrainSpec`, its effective Pi parent model, why it started (`start`, none for attempts from before usine recorded it), and when a restart last reattached it (`reattachedAt`). `RunSpec` is the immutable repo, payload, task, agent context, and child-session budget that the parent starts from.
+
+Only infra failures retry automatically, up to a cap. Agent failures wait for the operator. Runaway guard failures, exhausted child-session budgets, and `DefectFailure` never retry automatically; `DefectFailure` records a defect caught at a boundary that needs a serializable outcome, with its original cause.
+
+## Attempt windows
+
+`AttemptWindow` is when an attempt worked on its run's item: `startedAt` to `endedAt` from its record, with no end while open. `windowOf(attempt)` returns none for an attempt that ended before usine recorded end times. `windowHolds(window, at)` opens a window at its start second, since GitHub records times to the second. `windowsOverlap` says whether GitHub can record a time inside both windows.
 
-Branded schemas are exported under their brand name, and each has an `export type` twin of the same name so the name works in type positions too.
+Attempts on local and SSH workers all write as the same GitHub App, so a write inside two attempts' windows belongs to neither, in the run reader and in the harvest. The harvest keeps a comment only if the bot login wrote it with the agent's signature, after the worker prepared the checkout (creation, or a review's submission), inside the attempt's own window, and in no window of the agent's other overlapping attempts.
 
-`PullRequest` and `Comment` facts use `URL` values in memory and URL strings in JSON, so Step results round-trip through the Attempt channel and durable storage.
+The harvest reads `AttemptWindows` (`own`, `overlapping`) through `AttemptWindowsRead` after GitHub lists the comments, so they include attempts started during the harvest and any end the orchestrator recorded first, as a cancel does before the executor stops. Comments after that end, and attempts started after it, don't count.
 
-The run state machine is `pending → waiting → queued → running → succeeded / failed / canceled`, with `failed → running` on operator retry. The failure taxonomy separates infra failures (the only auto-retryable class, capped), agent failures (always wait for the operator), runaway guard failures, and exhausted child-session budgets. Guard failures never auto-retry.
+## Sessions and usage
 
-`RunState.operatorActions(state)` returns approval, retry, and cancel availability for operator views. The command handlers enforce the same lifecycle through the typed transitions.
+Outbound `SessionEvent` envelopes keep parent and first-level child session identity.
 
-Each Attempt records the child `BrainSpec` and effective Pi parent model used for that try. The attempt channel includes immutable repository, payload, task, agent context, and child-session budget in its `Start` frame; outbound `SessionEvent` envelopes retain parent and first-level child session identity.
+`SessionTokensUpdated` has a session's cumulative `TokenCount` and, as `costUsd`, the `UsdAmount` its harness priced it at: Pi from its model catalog, Claude Code from the Agent SDK. Codex sets no price. Older transcripts decode it to `Option.none()`.
 
-Everything is 0.x: APIs change without notice while the engine grows. `effect` is a peer dependency — supply it yourself at the pinned version.
+`ChildSession.gatewayCredential` is the `GatewayCredentialKind` the gateway in front of the child's worker used for its model requests: none if the child used its harness's login, and in older transcripts. `brainPool(brain, gatewayCredential)` returns a started session's billing pool; `sessionPool(session)` reads a recorded one's. A Claude Code child is in `apiKeys` if its gateway used an API key, otherwise in `claudePlan` (ADR 0013, ADR 0021).
 
-Import `CycleLimit`, `CycleGeneration`, `CycleCount`, `LoopCycleCount`, and `CycleBudgetAsk` from `@usine/core/cycle-budget`. An Item-level Ask records the exhausted Loop, its limit, and participating Loops’ admitted and completed Runs; it can exist before another Run is opened.
+The optional `SessionStarted.harnessSession` (`HarnessSession`) records the harness's `HarnessSessionId` and the worker `cwd`, apart from usine's session identity. Older transcripts decode it to `Option.none()`.
 
-`DefectFailure` records a programmer defect captured at a boundary that needs a serializable Attempt outcome. It retains the original cause and never qualifies for automatic retry.
+Envelopes include `PROTOCOL_VERSION` (7), which the transcript store uses to read older envelopes. Version 7 added the previous attempt's pushed salvage to `RunSpec` (`resume`); version 6 added harness session metadata.

package/dist/agent/agent.d.ts

@@ -1,27 +1,31 @@
 import { Schema, Option } from "effect";
 import { BrainSpec, Effort, ModelId } from "./brain.ts";
-/** Kebab-case name of a rostered Agent, taken from its filename. */
+/** The kebab-case name of an Agent, taken from its filename. */
 export declare const AgentName: Schema.brand<Schema.String, "AgentName">;
 export type AgentName = typeof AgentName.Type;
-/** Standing Markdown instructions for one Agent. */
+/**
+ * Returns the signature line that ends every GitHub comment, issue, pull request, or review the
+ * Agent writes. Harvesting uses it to separate Agents that post as the same bot login.
+ */
+export declare const githubSignature: (agent: AgentName) => string;
+/** The Agent's standing Markdown instructions. */
 export declare const AgentPersona: Schema.brand<Schema.String, "AgentPersona">;
 export type AgentPersona = typeof AgentPersona.Type;
 declare const Agent_base: Schema.Class<Agent, Schema.Struct<{
     readonly name: Schema.brand<Schema.String, "AgentName">;
-    /** Coding harness and settings used for this Agent's delegated child sessions. */
+    /** The harness, model, and effort of the Agent's child sessions. */
     readonly brain: typeof BrainSpec;
-    /** Preferred model for the coordinating Pi parent; an absent override uses the instance default. */
+    /** The model of the Pi parent session, or `None` for the instance default. */
     readonly parentModel: Schema.OptionFromNullOr<Schema.brand<Schema.String, "ModelId">>;
-    /** Parent reasoning effort; an absent override uses the instance default, then the child brain's effort. */
+    /** The parent session's reasoning effort, or `None` for the instance default, then `brain.effort`. */
     readonly parentEffort: Schema.OptionFromOptionalKey<Schema.Literals<readonly ["off", "minimal", "low", "medium", "high", "xhigh", "max"]>>;
     readonly persona: Schema.brand<Schema.String, "AgentPersona">;
 }>, {}>;
-/** One named member of the instance's team roster. */
 export declare class Agent extends Agent_base {
 }
-/** Selects the Agent's parent-model override, then the instance default; `None` leaves selection to Pi. */
+/** Returns the Agent's `parentModel`, else the instance default. Returns `None` if neither is set, so Pi selects the model. */
 export declare const resolveParentModel: (agent: Agent, instanceDefault: Option.Option<ModelId>) => Option.Option<ModelId>;
-/** The agent's parent-effort override, else the instance default, else the child brain's effort. */
+/** Returns the Agent's `parentEffort`, else the instance default, else `brain.effort`. */
 export declare const resolveParentEffort: (agent: Agent, instanceDefault: Option.Option<Effort>) => Effort;
 export {};
 //# sourceMappingURL=agent.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"agent.d.ts","sourceRoot":"","sources":["../../src/agent/agent.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AACxC,OAAO,EAAE,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AAExD,oEAAoE;AACpE,eAAO,MAAM,SAAS,0CAIW,CAAC;AAElC,MAAM,MAAM,SAAS,GAAG,OAAO,SAAS,CAAC,IAAI,CAAC;AAE9C,oDAAoD;AACpD,eAAO,MAAM,YAAY,6CAEW,CAAC;AACrC,MAAM,MAAM,YAAY,GAAG,OAAO,YAAY,CAAC,IAAI,CAAC;;;IAKlD,kFAAkF;;IAElF,oGAAoG;;IAGpG,4GAA4G;;;;AAR9G,sDAAsD;AACtD,qBAAa,KAAM,SAAQ,UAUzB;CAAG;AAEL,2GAA2G;AAC3G,eAAO,MAAM,kBAAkB,UACtB,KAAK,mBACK,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC,KACtC,MAAM,CAAC,MAAM,CAAC,OAAO,CAA6D,CAAC;AAEtF,oGAAoG;AACpG,eAAO,MAAM,mBAAmB,UAAW,KAAK,mBAAmB,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,KAAG,MAIxF,CAAC"}
+{"version":3,"file":"agent.d.ts","sourceRoot":"","sources":["../../src/agent/agent.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AACxC,OAAO,EAAE,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AAExD,gEAAgE;AAChE,eAAO,MAAM,SAAS,0CAIW,CAAC;AAElC,MAAM,MAAM,SAAS,GAAG,OAAO,SAAS,CAAC,IAAI,CAAC;AAE9C;;;GAGG;AACH,eAAO,MAAM,eAAe,UAAW,SAAS,KAAG,MAAmC,CAAC;AAEvF,kDAAkD;AAClD,eAAO,MAAM,YAAY,6CAEW,CAAC;AACrC,MAAM,MAAM,YAAY,GAAG,OAAO,YAAY,CAAC,IAAI,CAAC;;;IAIlD,oEAAoE;;IAEpE,8EAA8E;;IAG9E,sGAAsG;;;;AAPxG,qBAAa,KAAM,SAAQ,UAUzB;CAAG;AAEL,+HAA+H;AAC/H,eAAO,MAAM,kBAAkB,UACtB,KAAK,mBACK,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC,KACtC,MAAM,CAAC,MAAM,CAAC,OAAO,CAA6D,CAAC;AAEtF,0FAA0F;AAC1F,eAAO,MAAM,mBAAmB,UAAW,KAAK,mBAAmB,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,KAAG,MAIxF,CAAC"}

package/dist/agent/agent.js

@@ -1,26 +1,30 @@
 import { Schema, Option } from "effect";
 import { BrainSpec, Effort, ModelId } from "./brain.js";
-/** Kebab-case name of a rostered Agent, taken from its filename. */
+/** The kebab-case name of an Agent, taken from its filename. */
 export const AgentName = Schema.String.check(Schema.isPattern(/^[a-z0-9]+(?:-[a-z0-9]+)*$/u, {
-    message: "Expected a kebab-case Agent name",
+    message: "Expected a kebab-case agent name",
 })).pipe(Schema.brand("AgentName"));
-/** Standing Markdown instructions for one Agent. */
-export const AgentPersona = Schema.String.check(Schema.isPattern(/\S/u, { message: "Expected a non-blank Agent persona" })).pipe(Schema.brand("AgentPersona"));
-/** One named member of the instance's team roster. */
+/**
+ * Returns the signature line that ends every GitHub comment, issue, pull request, or review the
+ * Agent writes. Harvesting uses it to separate Agents that post as the same bot login.
+ */
+export const githubSignature = (agent) => `— usine agent: ${agent}`;
+/** The Agent's standing Markdown instructions. */
+export const AgentPersona = Schema.String.check(Schema.isPattern(/\S/u, { message: "Expected a non-blank agent persona" })).pipe(Schema.brand("AgentPersona"));
 export class Agent extends Schema.Class("Agent")({
     name: AgentName,
-    /** Coding harness and settings used for this Agent's delegated child sessions. */
+    /** The harness, model, and effort of the Agent's child sessions. */
     brain: BrainSpec,
-    /** Preferred model for the coordinating Pi parent; an absent override uses the instance default. */
+    /** The model of the Pi parent session, or `None` for the instance default. */
     parentModel: Schema.OptionFromNullOr(ModelId),
     // Optional key rather than null: older stored agent rows have no such key.
-    /** Parent reasoning effort; an absent override uses the instance default, then the child brain's effort. */
+    /** The parent session's reasoning effort, or `None` for the instance default, then `brain.effort`. */
     parentEffort: Schema.OptionFromOptionalKey(Effort),
     persona: AgentPersona,
 }) {
 }
-/** Selects the Agent's parent-model override, then the instance default; `None` leaves selection to Pi. */
+/** Returns the Agent's `parentModel`, else the instance default. Returns `None` if neither is set, so Pi selects the model. */
 export const resolveParentModel = (agent, instanceDefault) => Option.firstSomeOf([agent.parentModel, instanceDefault]);
-/** The agent's parent-effort override, else the instance default, else the child brain's effort. */
+/** Returns the Agent's `parentEffort`, else the instance default, else `brain.effort`. */
 export const resolveParentEffort = (agent, instanceDefault) => Option.getOrElse(Option.firstSomeOf([agent.parentEffort, instanceDefault]), () => agent.brain.effort);
 //# sourceMappingURL=agent.js.map

package/dist/agent/agent.js.map

@@ -1 +1 @@
-{"version":3,"file":"agent.js","sourceRoot":"","sources":["../../src/agent/agent.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AACxC,OAAO,EAAE,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AAExD,oEAAoE;AACpE,MAAM,CAAC,MAAM,SAAS,GAAG,MAAM,CAAC,MAAM,CAAC,KAAK,CAC1C,MAAM,CAAC,SAAS,CAAC,6BAA6B,EAAE;IAC9C,OAAO,EAAE,kCAAkC;CAC5C,CAAC,CACH,CAAC,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,WAAW,CAAC,CAAC,CAAC;AAIlC,oDAAoD;AACpD,MAAM,CAAC,MAAM,YAAY,GAAG,MAAM,CAAC,MAAM,CAAC,KAAK,CAC7C,MAAM,CAAC,SAAS,CAAC,KAAK,EAAE,EAAE,OAAO,EAAE,oCAAoC,EAAE,CAAC,CAC3E,CAAC,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,cAAc,CAAC,CAAC,CAAC;AAGrC,sDAAsD;AACtD,MAAM,OAAO,KAAM,SAAQ,MAAM,CAAC,KAAK,CAAQ,OAAO,CAAC,CAAC;IACtD,IAAI,EAAE,SAAS;IACf,kFAAkF;IAClF,KAAK,EAAE,SAAS;IAChB,oGAAoG;IACpG,WAAW,EAAE,MAAM,CAAC,gBAAgB,CAAC,OAAO,CAAC;IAC7C,2EAA2E;IAC3E,4GAA4G;IAC5G,YAAY,EAAE,MAAM,CAAC,qBAAqB,CAAC,MAAM,CAAC;IAClD,OAAO,EAAE,YAAY;CACtB,CAAC;CAAG;AAEL,2GAA2G;AAC3G,MAAM,CAAC,MAAM,kBAAkB,GAAG,CAChC,KAAY,EACZ,eAAuC,EACf,EAAE,CAAC,MAAM,CAAC,WAAW,CAAC,CAAC,KAAK,CAAC,WAAW,EAAE,eAAe,CAAC,CAAC,CAAC;AAEtF,oGAAoG;AACpG,MAAM,CAAC,MAAM,mBAAmB,GAAG,CAAC,KAAY,EAAE,eAAsC,EAAU,EAAE,CAClG,MAAM,CAAC,SAAS,CACd,MAAM,CAAC,WAAW,CAAC,CAAC,KAAK,CAAC,YAAY,EAAE,eAAe,CAAC,CAAC,EACzD,GAAG,EAAE,CAAC,KAAK,CAAC,KAAK,CAAC,MAAM,CACzB,CAAC"}
+{"version":3,"file":"agent.js","sourceRoot":"","sources":["../../src/agent/agent.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AACxC,OAAO,EAAE,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AAExD,gEAAgE;AAChE,MAAM,CAAC,MAAM,SAAS,GAAG,MAAM,CAAC,MAAM,CAAC,KAAK,CAC1C,MAAM,CAAC,SAAS,CAAC,6BAA6B,EAAE;IAC9C,OAAO,EAAE,kCAAkC;CAC5C,CAAC,CACH,CAAC,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,WAAW,CAAC,CAAC,CAAC;AAIlC;;;GAGG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG,CAAC,KAAgB,EAAU,EAAE,CAAC,kBAAkB,KAAK,EAAE,CAAC;AAEvF,kDAAkD;AAClD,MAAM,CAAC,MAAM,YAAY,GAAG,MAAM,CAAC,MAAM,CAAC,KAAK,CAC7C,MAAM,CAAC,SAAS,CAAC,KAAK,EAAE,EAAE,OAAO,EAAE,oCAAoC,EAAE,CAAC,CAC3E,CAAC,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,cAAc,CAAC,CAAC,CAAC;AAGrC,MAAM,OAAO,KAAM,SAAQ,MAAM,CAAC,KAAK,CAAQ,OAAO,CAAC,CAAC;IACtD,IAAI,EAAE,SAAS;IACf,oEAAoE;IACpE,KAAK,EAAE,SAAS;IAChB,8EAA8E;IAC9E,WAAW,EAAE,MAAM,CAAC,gBAAgB,CAAC,OAAO,CAAC;IAC7C,2EAA2E;IAC3E,sGAAsG;IACtG,YAAY,EAAE,MAAM,CAAC,qBAAqB,CAAC,MAAM,CAAC;IAClD,OAAO,EAAE,YAAY;CACtB,CAAC;CAAG;AAEL,+HAA+H;AAC/H,MAAM,CAAC,MAAM,kBAAkB,GAAG,CAChC,KAAY,EACZ,eAAuC,EACf,EAAE,CAAC,MAAM,CAAC,WAAW,CAAC,CAAC,KAAK,CAAC,WAAW,EAAE,eAAe,CAAC,CAAC,CAAC;AAEtF,0FAA0F;AAC1F,MAAM,CAAC,MAAM,mBAAmB,GAAG,CAAC,KAAY,EAAE,eAAsC,EAAU,EAAE,CAClG,MAAM,CAAC,SAAS,CACd,MAAM,CAAC,WAAW,CAAC,CAAC,KAAK,CAAC,YAAY,EAAE,eAAe,CAAC,CAAC,EACzD,GAAG,EAAE,CAAC,KAAK,CAAC,KAAK,CAAC,MAAM,CACzB,CAAC"}

package/dist/agent/brain.d.ts

@@ -1,15 +1,12 @@
 import { Schema } from "effect";
-/** A provider's model name; the selected harness checks its availability when the session starts. */
+/** A provider model name, which the harness checks when the session starts. */
 export declare const ModelId: Schema.brand<Schema.String, "ModelId">;
 export type ModelId = typeof ModelId.Type;
-/** Coding runtimes an Agent can select for delegated work. */
 export declare const HARNESSES: readonly ["claude", "codex", "pi"];
-/** The coding runtime that executes an Agent session. */
 export declare const Harness: Schema.Literals<readonly ["claude", "codex", "pi"]>;
 export type Harness = typeof Harness.Type;
-/** Reasoning levels accepted in Agent files; support depends on the chosen harness and model. */
+/** The reasoning levels; support depends on the harness and model. */
 export declare const EFFORTS: readonly ["off", "minimal", "low", "medium", "high", "xhigh", "max"];
-/** The requested amount of reasoning for a session; available levels depend on its harness and model. */
 export declare const Effort: Schema.Literals<readonly ["off", "minimal", "low", "medium", "high", "xhigh", "max"]>;
 export type Effort = typeof Effort.Type;
 declare const BrainSpec_base: Schema.Class<BrainSpec, Schema.Struct<{
@@ -17,7 +14,6 @@ declare const BrainSpec_base: Schema.Class<BrainSpec, Schema.Struct<{
     readonly model: Schema.brand<Schema.String, "ModelId">;
     readonly effort: Schema.Literals<readonly ["off", "minimal", "low", "medium", "high", "xhigh", "max"]>;
 }>, {}>;
-/** How an Agent session runs: its coding harness, model, and reasoning effort. */
 export declare class BrainSpec extends BrainSpec_base {
 }
 export {};

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

@@ -1 +1 @@
-{"version":3,"file":"brain.d.ts","sourceRoot":"","sources":["../../src/agent/brain.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAEhC,qGAAqG;AACrG,eAAO,MAAM,OAAO,wCAEW,CAAC;AAChC,MAAM,MAAM,OAAO,GAAG,OAAO,OAAO,CAAC,IAAI,CAAC;AAE1C,8DAA8D;AAC9D,eAAO,MAAM,SAAS,YAAI,QAAQ,EAAE,OAAO,EAAE,IAAI,CAAU,CAAC;AAC5D,yDAAyD;AACzD,eAAO,MAAM,OAAO,qDAA6B,CAAC;AAClD,MAAM,MAAM,OAAO,GAAG,OAAO,OAAO,CAAC,IAAI,CAAC;AAE1C,iGAAiG;AACjG,eAAO,MAAM,OAAO,YAAI,KAAK,EAAE,SAAS,EAAE,KAAK,EAAE,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,KAAK,CAAU,CAAC;AAC5F,yGAAyG;AACzG,eAAO,MAAM,MAAM,uFAA2B,CAAC;AAC/C,MAAM,MAAM,MAAM,GAAG,OAAO,MAAM,CAAC,IAAI,CAAC;;;;;;AAExC,kFAAkF;AAClF,qBAAa,SAAU,SAAQ,cAI7B;CAAG"}
+{"version":3,"file":"brain.d.ts","sourceRoot":"","sources":["../../src/agent/brain.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAEhC,+EAA+E;AAC/E,eAAO,MAAM,OAAO,wCAEW,CAAC;AAChC,MAAM,MAAM,OAAO,GAAG,OAAO,OAAO,CAAC,IAAI,CAAC;AAE1C,eAAO,MAAM,SAAS,YAAI,QAAQ,EAAE,OAAO,EAAE,IAAI,CAAU,CAAC;AAC5D,eAAO,MAAM,OAAO,qDAA6B,CAAC;AAClD,MAAM,MAAM,OAAO,GAAG,OAAO,OAAO,CAAC,IAAI,CAAC;AAE1C,sEAAsE;AACtE,eAAO,MAAM,OAAO,YAAI,KAAK,EAAE,SAAS,EAAE,KAAK,EAAE,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,KAAK,CAAU,CAAC;AAC5F,eAAO,MAAM,MAAM,uFAA2B,CAAC;AAC/C,MAAM,MAAM,MAAM,GAAG,OAAO,MAAM,CAAC,IAAI,CAAC;;;;;;AAExC,qBAAa,SAAU,SAAQ,cAI7B;CAAG"}

package/dist/agent/brain.js

@@ -1,15 +1,11 @@
 import { Schema } from "effect";
-/** A provider's model name; the selected harness checks its availability when the session starts. */
-export const ModelId = Schema.String.check(Schema.isPattern(/\S/u, { message: "Expected a non-blank model id" })).pipe(Schema.brand("ModelId"));
-/** Coding runtimes an Agent can select for delegated work. */
+/** A provider model name, which the harness checks when the session starts. */
+export const ModelId = Schema.String.check(Schema.isPattern(/\S/u, { message: "Expected a non-blank model ID" })).pipe(Schema.brand("ModelId"));
 export const HARNESSES = ["claude", "codex", "pi"];
-/** The coding runtime that executes an Agent session. */
 export const Harness = Schema.Literals(HARNESSES);
-/** Reasoning levels accepted in Agent files; support depends on the chosen harness and model. */
+/** The reasoning levels; support depends on the harness and model. */
 export const EFFORTS = ["off", "minimal", "low", "medium", "high", "xhigh", "max"];
-/** The requested amount of reasoning for a session; available levels depend on its harness and model. */
 export const Effort = Schema.Literals(EFFORTS);
-/** How an Agent session runs: its coding harness, model, and reasoning effort. */
 export class BrainSpec extends Schema.Class("Agent/BrainSpec")({
     harness: Harness,
     model: ModelId,

package/dist/agent/brain.js.map

@@ -1 +1 @@
-{"version":3,"file":"brain.js","sourceRoot":"","sources":["../../src/agent/brain.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAEhC,qGAAqG;AACrG,MAAM,CAAC,MAAM,OAAO,GAAG,MAAM,CAAC,MAAM,CAAC,KAAK,CACxC,MAAM,CAAC,SAAS,CAAC,KAAK,EAAE,EAAE,OAAO,EAAE,+BAA+B,EAAE,CAAC,CACtE,CAAC,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC,CAAC;AAGhC,8DAA8D;AAC9D,MAAM,CAAC,MAAM,SAAS,GAAG,CAAC,QAAQ,EAAE,OAAO,EAAE,IAAI,CAAU,CAAC;AAC5D,yDAAyD;AACzD,MAAM,CAAC,MAAM,OAAO,GAAG,MAAM,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAC;AAGlD,iGAAiG;AACjG,MAAM,CAAC,MAAM,OAAO,GAAG,CAAC,KAAK,EAAE,SAAS,EAAE,KAAK,EAAE,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,KAAK,CAAU,CAAC;AAC5F,yGAAyG;AACzG,MAAM,CAAC,MAAM,MAAM,GAAG,MAAM,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC;AAG/C,kFAAkF;AAClF,MAAM,OAAO,SAAU,SAAQ,MAAM,CAAC,KAAK,CAAY,iBAAiB,CAAC,CAAC;IACxE,OAAO,EAAE,OAAO;IAChB,KAAK,EAAE,OAAO;IACd,MAAM,EAAE,MAAM;CACf,CAAC;CAAG"}
+{"version":3,"file":"brain.js","sourceRoot":"","sources":["../../src/agent/brain.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAEhC,+EAA+E;AAC/E,MAAM,CAAC,MAAM,OAAO,GAAG,MAAM,CAAC,MAAM,CAAC,KAAK,CACxC,MAAM,CAAC,SAAS,CAAC,KAAK,EAAE,EAAE,OAAO,EAAE,+BAA+B,EAAE,CAAC,CACtE,CAAC,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC,CAAC;AAGhC,MAAM,CAAC,MAAM,SAAS,GAAG,CAAC,QAAQ,EAAE,OAAO,EAAE,IAAI,CAAU,CAAC;AAC5D,MAAM,CAAC,MAAM,OAAO,GAAG,MAAM,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAC;AAGlD,sEAAsE;AACtE,MAAM,CAAC,MAAM,OAAO,GAAG,CAAC,KAAK,EAAE,SAAS,EAAE,KAAK,EAAE,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,KAAK,CAAU,CAAC;AAC5F,MAAM,CAAC,MAAM,MAAM,GAAG,MAAM,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC;AAG/C,MAAM,OAAO,SAAU,SAAQ,MAAM,CAAC,KAAK,CAAY,iBAAiB,CAAC,CAAC;IACxE,OAAO,EAAE,OAAO;IAChB,KAAK,EAAE,OAAO;IACd,MAAM,EAAE,MAAM;CACf,CAAC;CAAG"}

package/dist/agent/capability.d.ts

@@ -1,5 +1,5 @@
 import { Schema } from "effect";
-/** A harness prerequisite that requires operator provisioning, never an automatic retry. */
+/** A harness prerequisite that the operator must provision; a missing one is never retried. */
 export declare const HarnessCapability: Schema.Literals<readonly ["binary", "version", "login"]>;
 export type HarnessCapability = typeof HarnessCapability.Type;
 declare const HarnessUnavailableError_base: Schema.Class<HarnessUnavailableError, Schema.TaggedStruct<"HarnessUnavailableError", {
@@ -7,16 +7,16 @@ declare const HarnessUnavailableError_base: Schema.Class<HarnessUnavailableError
     readonly capability: Schema.Literals<readonly ["binary", "version", "login"]>;
     readonly message: Schema.NonEmptyString;
 }>, import("effect/Cause").YieldableError>;
-/** The Worker cannot run the requested harness until the operator fixes its provisioning. */
+/** An error for a Worker that is missing `capability` for `harness`. */
 export declare class HarnessUnavailableError extends HarnessUnavailableError_base {
 }
 declare const HarnessReady_base: Schema.Class<HarnessReady, Schema.TaggedStruct<"HarnessReady", {
     readonly harness: Schema.Literals<readonly ["claude", "codex", "pi"]>;
 }>, {}>;
-/** A verify-only probe found the requested harness available in the Worker's environment. */
+/** The result of a verify-only probe that found the harness available on the Worker. */
 export declare class HarnessReady extends HarnessReady_base {
 }
-/** The run host's preflight response; contains no credentials or account identity. */
+/** The result of a harness preflight, without credentials or account identity. */
 export declare const HarnessReadiness: Schema.Union<readonly [typeof HarnessReady, typeof HarnessUnavailableError]>;
 export type HarnessReadiness = typeof HarnessReadiness.Type;
 export {};

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

@@ -1 +1 @@
-{"version":3,"file":"capability.d.ts","sourceRoot":"","sources":["../../src/agent/capability.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAGhC,4FAA4F;AAC5F,eAAO,MAAM,iBAAiB,0DAAkD,CAAC;AACjF,MAAM,MAAM,iBAAiB,GAAG,OAAO,iBAAiB,CAAC,IAAI,CAAC;;;;;;AAE9D,6FAA6F;AAC7F,qBAAa,uBAAwB,SAAQ,4BAM3C;CAAG;;;;AAEL,6FAA6F;AAC7F,qBAAa,YAAa,SAAQ,iBAEhC;CAAG;AAEL,sFAAsF;AACtF,eAAO,MAAM,gBAAgB,8EAAwD,CAAC;AACtF,MAAM,MAAM,gBAAgB,GAAG,OAAO,gBAAgB,CAAC,IAAI,CAAC"}
+{"version":3,"file":"capability.d.ts","sourceRoot":"","sources":["../../src/agent/capability.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAGhC,+FAA+F;AAC/F,eAAO,MAAM,iBAAiB,0DAAkD,CAAC;AACjF,MAAM,MAAM,iBAAiB,GAAG,OAAO,iBAAiB,CAAC,IAAI,CAAC;;;;;;AAE9D,wEAAwE;AACxE,qBAAa,uBAAwB,SAAQ,4BAM3C;CAAG;;;;AAEL,wFAAwF;AACxF,qBAAa,YAAa,SAAQ,iBAEhC;CAAG;AAEL,kFAAkF;AAClF,eAAO,MAAM,gBAAgB,8EAAwD,CAAC;AACtF,MAAM,MAAM,gBAAgB,GAAG,OAAO,gBAAgB,CAAC,IAAI,CAAC"}

package/dist/agent/capability.js

@@ -1,19 +1,19 @@
 import { Schema } from "effect";
 import { Harness } from "./brain.js";
-/** A harness prerequisite that requires operator provisioning, never an automatic retry. */
+/** A harness prerequisite that the operator must provision; a missing one is never retried. */
 export const HarnessCapability = Schema.Literals(["binary", "version", "login"]);
-/** The Worker cannot run the requested harness until the operator fixes its provisioning. */
+/** An error for a Worker that is missing `capability` for `harness`. */
 export class HarnessUnavailableError extends Schema.TaggedError("HarnessUnavailableError")("HarnessUnavailableError", {
     harness: Harness,
     capability: HarnessCapability,
     message: Schema.NonEmptyString,
 }) {
 }
-/** A verify-only probe found the requested harness available in the Worker's environment. */
+/** The result of a verify-only probe that found the harness available on the Worker. */
 export class HarnessReady extends Schema.TaggedClass("HarnessReady")("HarnessReady", {
     harness: Harness,
 }) {
 }
-/** The run host's preflight response; contains no credentials or account identity. */
+/** The result of a harness preflight, without credentials or account identity. */
 export const HarnessReadiness = Schema.Union([HarnessReady, HarnessUnavailableError]);
 //# sourceMappingURL=capability.js.map

package/dist/agent/capability.js.map

@@ -1 +1 @@
-{"version":3,"file":"capability.js","sourceRoot":"","sources":["../../src/agent/capability.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAChC,OAAO,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AAErC,4FAA4F;AAC5F,MAAM,CAAC,MAAM,iBAAiB,GAAG,MAAM,CAAC,QAAQ,CAAC,CAAC,QAAQ,EAAE,SAAS,EAAE,OAAO,CAAC,CAAC,CAAC;AAGjF,6FAA6F;AAC7F,MAAM,OAAO,uBAAwB,SAAQ,MAAM,CAAC,WAAW,CAC7D,yBAAyB,CAC1B,CAAC,yBAAyB,EAAE;IAC3B,OAAO,EAAE,OAAO;IAChB,UAAU,EAAE,iBAAiB;IAC7B,OAAO,EAAE,MAAM,CAAC,cAAc;CAC/B,CAAC;CAAG;AAEL,6FAA6F;AAC7F,MAAM,OAAO,YAAa,SAAQ,MAAM,CAAC,WAAW,CAAe,cAAc,CAAC,CAAC,cAAc,EAAE;IACjG,OAAO,EAAE,OAAO;CACjB,CAAC;CAAG;AAEL,sFAAsF;AACtF,MAAM,CAAC,MAAM,gBAAgB,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC,YAAY,EAAE,uBAAuB,CAAC,CAAC,CAAC"}
+{"version":3,"file":"capability.js","sourceRoot":"","sources":["../../src/agent/capability.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAChC,OAAO,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AAErC,+FAA+F;AAC/F,MAAM,CAAC,MAAM,iBAAiB,GAAG,MAAM,CAAC,QAAQ,CAAC,CAAC,QAAQ,EAAE,SAAS,EAAE,OAAO,CAAC,CAAC,CAAC;AAGjF,wEAAwE;AACxE,MAAM,OAAO,uBAAwB,SAAQ,MAAM,CAAC,WAAW,CAC7D,yBAAyB,CAC1B,CAAC,yBAAyB,EAAE;IAC3B,OAAO,EAAE,OAAO;IAChB,UAAU,EAAE,iBAAiB;IAC7B,OAAO,EAAE,MAAM,CAAC,cAAc;CAC/B,CAAC;CAAG;AAEL,wFAAwF;AACxF,MAAM,OAAO,YAAa,SAAQ,MAAM,CAAC,WAAW,CAAe,cAAc,CAAC,CAAC,cAAc,EAAE;IACjG,OAAO,EAAE,OAAO;CACjB,CAAC;CAAG;AAEL,kFAAkF;AAClF,MAAM,CAAC,MAAM,gBAAgB,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC,YAAY,EAAE,uBAAuB,CAAC,CAAC,CAAC"}

package/dist/agent/session.d.ts

@@ -1,12 +1,16 @@
-import { Schema } from "effect";
+import { Option, Schema } from "effect";
+import { GatewayCredentialKind } from "../worker.ts";
 import { BrainSpec } from "./brain.ts";
-/** Identity usine assigns to a parent or child session within an Attempt. */
+/** The usine ID of a parent or child session, distinct from `HarnessSessionId`. */
 export declare const AgentSessionId: Schema.brand<Schema.NonEmptyString, "AgentSessionId">;
 export type AgentSessionId = typeof AgentSessionId.Type;
-/** Maximum child sessions one Attempt may spawn over its lifetime, including sequential spawns. */
+/** The sum of output tokens and uncached input tokens (new prompt text and cache writes), excluding cache reads. */
+export declare const TokenCount: Schema.brand<Schema.Int, "TokenCount">;
+export type TokenCount = typeof TokenCount.Type;
+/** The maximum number of child sessions per Attempt, counting sequential spawns. */
 export declare const ChildSessionBudget: Schema.brand<Schema.Int, "ChildSessionBudget">;
 export type ChildSessionBudget = typeof ChildSessionBudget.Type;
-/** The 1-based child spawn request number within an Attempt, including requests rejected by the budget. */
+/** The 1-based number of a child spawn request in an Attempt, counting requests the budget rejected. */
 export declare const ChildSessionCount: Schema.brand<Schema.Int, "ChildSessionCount">;
 export type ChildSessionCount = typeof ChildSessionCount.Type;
 declare const ParentSession_base: Schema.Class<ParentSession, Schema.TaggedStruct<"ParentSession", {
@@ -14,7 +18,6 @@ declare const ParentSession_base: Schema.Class<ParentSession, Schema.TaggedStruc
     readonly agent: Schema.brand<Schema.String, "AgentName">;
     readonly brain: typeof BrainSpec;
 }>, {}>;
-/** The session coordinating an Attempt and delegating work to its coding children. */
 export declare class ParentSession extends ParentSession_base {
 }
 declare const ChildSession_base: Schema.Class<ChildSession, Schema.TaggedStruct<"ChildSession", {
@@ -22,24 +25,40 @@ declare const ChildSession_base: Schema.Class<ChildSession, Schema.TaggedStruct<
     readonly parentId: Schema.brand<Schema.NonEmptyString, "AgentSessionId">;
     readonly agent: Schema.brand<Schema.String, "AgentName">;
     readonly brain: typeof BrainSpec;
+    /**
+     * The credential kind the Gateway used for the child's model requests (ADR 0027), or `None`
+     * if the child used its harness's own login or the record is older.
+     */
+    readonly gatewayCredential: Schema.withConstructorDefault<Schema.OptionFromOptionalKey<Schema.Literals<readonly ["api-key", "subscription"]>>>;
 }>, {}>;
-/** A coding session delegated by the Attempt's parent; children cannot delegate to further children. */
+/** A session spawned by the parent session; a child can't spawn children. */
 export declare class ChildSession extends ChildSession_base {
 }
-/** A participant in an Attempt, with its role, Agent, and effective brain recorded. */
 export declare const AgentSession: Schema.Union<readonly [typeof ParentSession, typeof ChildSession]>;
 export type AgentSession = typeof AgentSession.Type;
+/** The harness's ID for its saved conversation, distinct from `AgentSessionId`. */
+export declare const HarnessSessionId: Schema.brand<Schema.NonEmptyString, "HarnessSessionId">;
+export type HarnessSessionId = typeof HarnessSessionId.Type;
+declare const HarnessSession_base: Schema.Class<HarnessSession, Schema.Struct<{
+    readonly id: Schema.brand<Schema.NonEmptyString, "HarnessSessionId">;
+    readonly cwd: Schema.NonEmptyString;
+}>, {}>;
+/** A saved harness conversation; `cwd` is the Worker checkout to resume it from. */
+export declare class HarnessSession extends HarnessSession_base {
+}
 declare const SessionStarted_base: Schema.Class<SessionStarted, Schema.TaggedStruct<"SessionStarted", {
     readonly session: Schema.Union<readonly [typeof ParentSession, typeof ChildSession]>;
+    /** `None` for older transcripts and for harnesses without a saved conversation. */
+    readonly harnessSession: Schema.withConstructorDefault<Schema.OptionFromOptionalKey<typeof HarnessSession>>;
 }>, {}>;
-/** Records the session identity and brain actually selected at launch. */
+/** The session identity and the brain selected at launch. */
 export declare class SessionStarted extends SessionStarted_base {
 }
 declare const TextOutput_base: Schema.Class<TextOutput, Schema.TaggedStruct<"TextOutput", {
     readonly session: Schema.Union<readonly [typeof ParentSession, typeof ChildSession]>;
     readonly text: Schema.NonEmptyString;
 }>, {}>;
-/** Completed assistant text emitted during the session, which may precede its final result. */
+/** Completed assistant text, which can come before the final result. */
 export declare class TextOutput extends TextOutput_base {
 }
 declare const ToolStarted_base: Schema.Class<ToolStarted, Schema.TaggedStruct<"ToolStarted", {
@@ -48,7 +67,7 @@ declare const ToolStarted_base: Schema.Class<ToolStarted, Schema.TaggedStruct<"T
     readonly tool: Schema.NonEmptyString;
     readonly input: Schema.Codec<Schema.Json, Schema.Json, never, never>;
 }>, {}>;
-/** A session began a tool call; `callId` pairs it with the corresponding result. */
+/** The start of a tool call; `callId` matches the corresponding `ToolFinished`. */
 export declare class ToolStarted extends ToolStarted_base {
 }
 declare const ToolFinished_base: Schema.Class<ToolFinished, Schema.TaggedStruct<"ToolFinished", {
@@ -58,27 +77,59 @@ declare const ToolFinished_base: Schema.Class<ToolFinished, Schema.TaggedStruct<
     readonly output: Schema.Codec<Schema.Json, Schema.Json, never, never>;
     readonly isError: Schema.Boolean;
 }>, {}>;
-/** A tool call returned its output; a tool error does not by itself close the session. */
+/** The result of a tool call; `isError` doesn't end the session. */
 export declare class ToolFinished extends ToolFinished_base {
 }
 declare const SessionFinished_base: Schema.Class<SessionFinished, Schema.TaggedStruct<"SessionFinished", {
     readonly session: Schema.Union<readonly [typeof ParentSession, typeof ChildSession]>;
 }>, {}>;
-/** Marks the end of a session's activity in the transcript; the Attempt's outcome is recorded separately. */
+/** The end of a session's activity; the Attempt's outcome is recorded separately. */
 export declare class SessionFinished extends SessionFinished_base {
 }
-/** The billing source whose meter produced a usage or rate-limit observation. */
+declare const SessionIdle_base: Schema.Class<SessionIdle, Schema.TaggedStruct<"SessionIdle", {
+    readonly session: Schema.Union<readonly [typeof ParentSession, typeof ChildSession]>;
+}>, {}>;
+/** A supervised session that finished a turn and accepts more operator messages. */
+export declare class SessionIdle extends SessionIdle_base {
+}
+declare const SessionResumed_base: Schema.Class<SessionResumed, Schema.TaggedStruct<"SessionResumed", {
+    readonly session: Schema.Union<readonly [typeof ParentSession, typeof ChildSession]>;
+}>, {}>;
+/** A live session that started another user turn in the same conversation. */
+export declare class SessionResumed extends SessionResumed_base {
+}
+/** An estimated amount in US dollars from the harness's own rate table, not a bill (ADR 0013). */
+export declare const UsdAmount: Schema.brand<Schema.Finite, "UsdAmount">;
+export type UsdAmount = typeof UsdAmount.Type;
+declare const SessionTokensUpdated_base: Schema.Class<SessionTokensUpdated, Schema.TaggedStruct<"SessionTokensUpdated", {
+    readonly session: Schema.Union<readonly [typeof ParentSession, typeof ChildSession]>;
+    readonly totalTokens: Schema.brand<Schema.Int, "TokenCount">;
+    readonly costUsd: Schema.withConstructorDefault<Schema.OptionFromOptionalKey<Schema.brand<Schema.Finite, "UsdAmount">>>;
+}>, {}>;
+/**
+ * The session's cumulative token count and price, including later operator turns. `costUsd` is
+ * `None` for harnesses that don't price usage, such as Codex, and for older transcripts.
+ */
+export declare class SessionTokensUpdated extends SessionTokensUpdated_base {
+}
 export declare const BillingPool: Schema.Literals<readonly ["apiKeys", "claudePlan", "chatgptPlan"]>;
 export type BillingPool = typeof BillingPool.Type;
+/**
+ * Returns the billing pool of a session with `brain` and the Gateway credential kind, if any.
+ *
+ * - Claude Code: `apiKeys` if the Gateway injects an API key, otherwise `claudePlan` (ADR 0013).
+ * - Codex: `chatgptPlan`.
+ * - Pi: `chatgptPlan` for `openai-codex/` models, otherwise `apiKeys` (ADR 0021).
+ */
+export declare const brainPool: (brain: BrainSpec, gatewayCredential: Option.Option<GatewayCredentialKind>) => BillingPool;
+/** Returns the billing pool of a recorded session; the parent never uses a Gateway credential. */
+export declare const sessionPool: (session: AgentSession) => BillingPool;
 declare const RateLimitWindow_base: Schema.Class<RateLimitWindow, Schema.Struct<{
-    /** Percentage of the allowance already consumed, including usage outside this Attempt. */
+    /** The percentage of the allowance used, including usage outside this Attempt. */
     readonly usedPercent: Schema.Number;
-    /** Length of the allowance window; absent when the provider omits it. */
     readonly windowDurationMinutes: Schema.OptionFromNullOr<Schema.Number>;
-    /** When the allowance resets; absent when the provider omits it. */
     readonly resetsAt: Schema.OptionFromNullOr<Schema.DateTimeUtcFromString>;
 }>, {}>;
-/** A billing pool's observed usage for one allowance window. */
 export declare class RateLimitWindow extends RateLimitWindow_base {
 }
 declare const RateLimitsSnapshot_base: Schema.Class<RateLimitsSnapshot, Schema.Struct<{
@@ -87,7 +138,7 @@ declare const RateLimitsSnapshot_base: Schema.Class<RateLimitsSnapshot, Schema.S
     readonly primary: Schema.OptionFromNullOr<typeof RateLimitWindow>;
     readonly secondary: Schema.OptionFromNullOr<typeof RateLimitWindow>;
 }>, {}>;
-/** The allowance windows reported together by a provider; omitted windows remain unknown. */
+/** The rate-limit windows from one provider report; a window is `None` if not reported. */
 export declare class RateLimitsSnapshot extends RateLimitsSnapshot_base {
 }
 declare const PoolRateLimitsUpdated_base: Schema.Class<PoolRateLimitsUpdated, Schema.TaggedStruct<"PoolRateLimitsUpdated", {
@@ -95,11 +146,34 @@ declare const PoolRateLimitsUpdated_base: Schema.Class<PoolRateLimitsUpdated, Sc
     readonly pool: Schema.Literals<readonly ["apiKeys", "claudePlan", "chatgptPlan"]>;
     readonly rateLimits: typeof RateLimitsSnapshot;
 }>, {}>;
-/** The latest rate windows observed for a billing pool during one session. */
+/** The latest rate-limit windows observed for `pool` during the session. */
 export declare class PoolRateLimitsUpdated extends PoolRateLimitsUpdated_base {
 }
-/** Session activity and billing observations recorded in an Attempt's transcript. */
-export declare const AgentSessionEvent: Schema.Union<readonly [typeof SessionStarted, typeof TextOutput, typeof ToolStarted, typeof ToolFinished, typeof PoolRateLimitsUpdated, typeof SessionFinished]>;
+/** The number of model provider retries in the current turn, starting at 1. */
+export declare const ProviderRetries: Schema.brand<Schema.Int, "ProviderRetries">;
+export type ProviderRetries = typeof ProviderRetries.Type;
+declare const ProviderRetrying_base: Schema.Class<ProviderRetrying, Schema.TaggedStruct<"ProviderRetrying", {
+    readonly session: Schema.Union<readonly [typeof ParentSession, typeof ChildSession]>;
+    /** The harness's failure message, verbatim if it provides one. */
+    readonly message: Schema.NonEmptyString;
+    /** The retries reported in the current turn, including this one. */
+    readonly retries: Schema.brand<Schema.Int, "ProviderRetries">;
+}>, {}>;
+/**
+ * A harness report of a failed model provider request that it retries, such as Codex's
+ * `Reconnecting...`. The session isn't stopped or failed (ADR 0013).
+ */
+export declare class ProviderRetrying extends ProviderRetrying_base {
+}
+declare const ProviderRecovered_base: Schema.Class<ProviderRecovered, Schema.TaggedStruct<"ProviderRecovered", {
+    readonly session: Schema.Union<readonly [typeof ParentSession, typeof ChildSession]>;
+    /** The retries in the turn before the response. */
+    readonly retries: Schema.brand<Schema.Int, "ProviderRetries">;
+}>, {}>;
+/** A model provider response after a `ProviderRetrying` in the same turn. */
+export declare class ProviderRecovered extends ProviderRecovered_base {
+}
+export declare const AgentSessionEvent: Schema.Union<readonly [typeof SessionStarted, typeof TextOutput, typeof ToolStarted, typeof ToolFinished, typeof PoolRateLimitsUpdated, typeof SessionFinished, typeof SessionIdle, typeof SessionResumed, typeof SessionTokensUpdated, typeof ProviderRetrying, typeof ProviderRecovered]>;
 export type AgentSessionEvent = typeof AgentSessionEvent.Type;
 export {};
 //# sourceMappingURL=session.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"session.d.ts","sourceRoot":"","sources":["../../src/agent/session.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAEhC,OAAO,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAEvC,6EAA6E;AAC7E,eAAO,MAAM,cAAc,uDAA6D,CAAC;AACzF,MAAM,MAAM,cAAc,GAAG,OAAO,cAAc,CAAC,IAAI,CAAC;AAIxD,mGAAmG;AACnG,eAAO,MAAM,kBAAkB,gDAAuD,CAAC;AACvF,MAAM,MAAM,kBAAkB,GAAG,OAAO,kBAAkB,CAAC,IAAI,CAAC;AAEhE,2GAA2G;AAC3G,eAAO,MAAM,iBAAiB,+CAAsD,CAAC;AACrF,MAAM,MAAM,iBAAiB,GAAG,OAAO,iBAAiB,CAAC,IAAI,CAAC;;;;;;AAE9D,sFAAsF;AACtF,qBAAa,aAAc,SAAQ,kBAOlC;CAAG;;;;;;;AAEJ,wGAAwG;AACxG,qBAAa,YAAa,SAAQ,iBAQjC;CAAG;AAEJ,uFAAuF;AACvF,eAAO,MAAM,YAAY,oEAA8C,CAAC;AACxE,MAAM,MAAM,YAAY,GAAG,OAAO,YAAY,CAAC,IAAI,CAAC;;;;AAEpD,0EAA0E;AAC1E,qBAAa,cAAe,SAAQ,mBAGnC;CAAG;;;;;AAEJ,+FAA+F;AAC/F,qBAAa,UAAW,SAAQ,eAG9B;CAAG;;;;;;;AAEL,oFAAoF;AACpF,qBAAa,WAAY,SAAQ,gBAQhC;CAAG;;;;;;;;AAEJ,0FAA0F;AAC1F,qBAAa,YAAa,SAAQ,iBASjC;CAAG;;;;AAEJ,6GAA6G;AAC7G,qBAAa,eAAgB,SAAQ,oBAGpC;CAAG;AAEJ,iFAAiF;AACjF,eAAO,MAAM,WAAW,oEAAqE,CAAC;AAC9F,MAAM,MAAM,WAAW,GAAG,OAAO,WAAW,CAAC,IAAI,CAAC;;IAIhD,0FAA0F;;IAE1F,yEAAyE;;IAEzE,oEAAoE;;;AANtE,gEAAgE;AAChE,qBAAa,eAAgB,SAAQ,oBAOnC;CAAG;;;;;;;AAEL,6FAA6F;AAC7F,qBAAa,kBAAmB,SAAQ,uBAOtC;CAAG;;;;;;AAEL,8EAA8E;AAC9E,qBAAa,qBAAsB,SAAQ,0BAMzC;CAAG;AAEL,qFAAqF;AACrF,eAAO,MAAM,iBAAiB,kKAO5B,CAAC;AACH,MAAM,MAAM,iBAAiB,GAAG,OAAO,iBAAiB,CAAC,IAAI,CAAC"}
+{"version":3,"file":"session.d.ts","sourceRoot":"","sources":["../../src/agent/session.ts"],"names":[],"mappings":"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"}