@usine/core 0.1.0 → 0.2.0

package/README.md

@@ -1,29 +1,35 @@
 # @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 shared instance and repository value objects.
+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.
 
-Everything lives in the `lifecycle` cluster: a deduplicated Event opens a Run, the Run's named Step is tried as Attempts, and the state machine closes it.
+Import each domain concept from its owning subpath. Identities, records, and operations share that domain module.
 
-## What each export is
-
-| Export | Kind |
+| Subpath | Exports |
 | --- | --- |
-| `Event`, `Run`, `Step`, `Attempt` | Entities — the four ledger rows, identity plus validated construction |
-| `EventId`, `RunId`, `AttemptId` | Value objects — branded ids; identities that cannot be swapped for each other |
-| `DedupKey`, `ItemKey`, `Item.Number`, `LoopName`, `StepName`, `AttemptNumber` | Value objects — branded primitives carrying a domain constraint; Item numbers are positive integers |
-| `Instance.Directory`, `Repository.Name`, `Repository.Revision`, `Repository.CommitSha` | Shared value objects — paths and validated Git identities |
-| `Worker.Name`, `Worker.Kind` | Value objects — a Worker identity and its local or exe.dev adapter kind |
-| `Agent.Agent`, `Agent.BrainSpec` | Agent values — a named persona, its child brain, and optional Pi parent-model override |
-| `Agent.SessionEvent` | Session events — typed parent or first-level child lifecycle, text, and tool events |
-| `AttemptChannel.*` | Protocol values: the secret-free run spec, framed input, and protocol-v3 Attempt envelopes (`Started` carries the effective parent model) |
-| `StepResult.*` | Result values — the final agent message plus commit, pull-request, and comment facts |
-| `RunState.*`, `CancelReason`, `Attempt.Outcome` | State value objects — discriminated unions, including a distinct canceled Attempt outcome |
-| `RunState.awaitApproval/start/succeed/fail/retry/cancelByOperator/supersede/revoke` | Typestate transitions — each accepts only the states it is legal on, so an illegal transition is a compile error |
-| `InfraFailure`, `AgentFailure`, `RunawayFailure` | Typed errors — the attempt-failure taxonomy |
-| `AttemptFailure.isAutoRetryable`, `Attempt.shouldAutoRetry` | Derivers — pure decision functions stating the auto-retry law (class rule; class rule capped by attempt count) |
-
-The run state machine is `pending → waiting → 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), and the runaway guard tripping (never auto-retried).
-
-Each Attempt records the child `BrainSpec` and effective Pi parent model used for that try. The attempt channel carries immutable repository, payload, task, and agent context in its `Start` frame; outbound `SessionEvent` envelopes retain parent and first-level child session identity.
+| `@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/step`, `@usine/core/step/result` | `Step`, `StepName`; `StepResult` and its facts (`Commit`, `PullRequest`, `Comment`) |
+| `@usine/core/attempt` | `Attempt`, `AttemptId`, `AttemptNumber`, `AttemptTask`, `shouldAutoRetry` |
+| `@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/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` |
+
+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.
+
+`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 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.
+
+`RunState.operatorActions(state)` returns approval, retry, and cancel availability for operator views. The command handlers enforce the same lifecycle through the typed transitions.
+
+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.
 
 Everything is 0.x: APIs change without notice while the engine grows. `effect` is a peer dependency — supply it yourself at the pinned version.
+
+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.
+
+`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.

package/dist/agent/agent.d.ts

@@ -0,0 +1,27 @@
+import { Schema, Option } from "effect";
+import { BrainSpec, Effort, ModelId } from "./brain.ts";
+/** Kebab-case name of a rostered 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. */
+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. */
+    readonly brain: typeof BrainSpec;
+    /** Preferred model for the coordinating Pi parent; an absent override uses 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. */
+    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. */
+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. */
+export declare const resolveParentEffort: (agent: Agent, instanceDefault: Option.Option<Effort>) => Effort;
+export {};
+//# sourceMappingURL=agent.d.ts.map

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

@@ -0,0 +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"}

package/dist/agent/agent.js

@@ -0,0 +1,26 @@
+import { Schema, Option } from "effect";
+import { BrainSpec, Effort, ModelId } from "./brain.js";
+/** Kebab-case name of a rostered 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",
+})).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. */
+export class Agent extends Schema.Class("Agent")({
+    name: AgentName,
+    /** Coding harness and settings used for this Agent's delegated child sessions. */
+    brain: BrainSpec,
+    /** Preferred model for the coordinating Pi parent; an absent override uses 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. */
+    parentEffort: Schema.OptionFromOptionalKey(Effort),
+    persona: AgentPersona,
+}) {
+}
+/** Selects the Agent's parent-model override, then the instance default; `None` leaves selection to Pi. */
+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. */
+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

@@ -0,0 +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"}

package/dist/agent/brain.d.ts

@@ -0,0 +1,24 @@
+import { Schema } from "effect";
+/** A provider's model name; the selected harness checks its availability 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. */
+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<{
+    readonly harness: Schema.Literals<readonly ["claude", "codex", "pi"]>;
+    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 {};
+//# sourceMappingURL=brain.d.ts.map

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

@@ -0,0 +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"}

package/dist/agent/brain.js

@@ -0,0 +1,19 @@
+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. */
+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. */
+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,
+    effort: Effort,
+}) {
+}
+//# sourceMappingURL=brain.js.map

package/dist/agent/brain.js.map

@@ -0,0 +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"}

package/dist/agent/capability.d.ts

@@ -0,0 +1,23 @@
+import { Schema } from "effect";
+/** A harness prerequisite that requires operator provisioning, never an automatic retry. */
+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", {
+    readonly harness: Schema.Literals<readonly ["claude", "codex", "pi"]>;
+    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. */
+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. */
+export declare class HarnessReady extends HarnessReady_base {
+}
+/** The run host's preflight response; contains no credentials or account identity. */
+export declare const HarnessReadiness: Schema.Union<readonly [typeof HarnessReady, typeof HarnessUnavailableError]>;
+export type HarnessReadiness = typeof HarnessReadiness.Type;
+export {};
+//# sourceMappingURL=capability.d.ts.map

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

@@ -0,0 +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"}

package/dist/agent/capability.js

@@ -0,0 +1,19 @@
+import { Schema } from "effect";
+import { Harness } from "./brain.js";
+/** A harness prerequisite that requires operator provisioning, never an automatic retry. */
+export const HarnessCapability = Schema.Literals(["binary", "version", "login"]);
+/** The Worker cannot run the requested harness until the operator fixes its provisioning. */
+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. */
+export class HarnessReady extends Schema.TaggedClass("HarnessReady")("HarnessReady", {
+    harness: Harness,
+}) {
+}
+/** The run host's preflight response; contains no credentials or account identity. */
+export const HarnessReadiness = Schema.Union([HarnessReady, HarnessUnavailableError]);
+//# sourceMappingURL=capability.js.map

package/dist/agent/capability.js.map

@@ -0,0 +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"}

package/dist/{agent.d.ts → agent/session.d.ts}

@@ -1,45 +1,20 @@
-import { Option, Schema } from "effect";
-/** Value object: the filename-keyed identity of one rostered Agent. */
-export declare const Name: Schema.brand<Schema.String, "AgentName">;
-export type Name = typeof Name.Type;
-/** Value object: an opaque vendor model identifier. */
-export declare const ModelId: Schema.brand<Schema.String, "ModelId">;
-export type ModelId = typeof ModelId.Type;
-/** Value object: standing Markdown instructions for one Agent. */
-export declare const Persona: Schema.brand<Schema.String, "AgentPersona">;
-export type Persona = typeof Persona.Type;
-export declare const HARNESSES: readonly ["claude", "codex", "pi"];
-export declare const Harness: Schema.Literals<readonly ["claude", "codex", "pi"]>;
-export type Harness = typeof Harness.Type;
-export declare const EFFORTS: readonly ["off", "minimal", "low", "medium", "high", "xhigh", "max"];
-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<{
-    readonly harness: Schema.Literals<readonly ["claude", "codex", "pi"]>;
-    readonly model: Schema.brand<Schema.String, "ModelId">;
-    readonly effort: Schema.Literals<readonly ["off", "minimal", "low", "medium", "high", "xhigh", "max"]>;
-}>, {}>;
-/** Value object: the harness child that a run is declared to spawn. */
-export declare class BrainSpec extends BrainSpec_base {
-}
-declare const Agent_base: Schema.Class<Agent, Schema.Struct<{
-    readonly name: Schema.brand<Schema.String, "AgentName">;
-    readonly brain: typeof BrainSpec;
-    readonly parentModel: Schema.OptionFromNullOr<Schema.brand<Schema.String, "ModelId">>;
-    readonly persona: Schema.brand<Schema.String, "AgentPersona">;
-}>, {}>;
-/** Entity: one named member of the instance's authored team roster. */
-export declare class Agent extends Agent_base {
-}
-/** Value object: SDK-local identity of one parent or child agent session. */
-export declare const SessionId: Schema.brand<Schema.NonEmptyString, "AgentSessionId">;
-export type SessionId = typeof SessionId.Type;
+import { Schema } from "effect";
+import { BrainSpec } from "./brain.ts";
+/** Identity usine assigns to a parent or child session within an Attempt. */
+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. */
+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. */
+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", {
     readonly id: Schema.brand<Schema.NonEmptyString, "AgentSessionId">;
     readonly agent: Schema.brand<Schema.String, "AgentName">;
     readonly brain: typeof BrainSpec;
 }>, {}>;
-/** Parent session descriptor. It cannot name a parent, so recursive nesting is unrepresentable. */
+/** 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", {
@@ -48,20 +23,23 @@ declare const ChildSession_base: Schema.Class<ChildSession, Schema.TaggedStruct<
     readonly agent: Schema.brand<Schema.String, "AgentName">;
     readonly brain: typeof BrainSpec;
 }>, {}>;
-/** Child session descriptor. Exactly one parent id keeps session nesting one level deep. */
+/** A coding session delegated by the Attempt's parent; children cannot delegate to further children. */
 export declare class ChildSession extends ChildSession_base {
 }
-export declare const Session: Schema.Union<readonly [typeof ParentSession, typeof ChildSession]>;
-export type Session = typeof Session.Type;
+/** 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;
 declare const SessionStarted_base: Schema.Class<SessionStarted, Schema.TaggedStruct<"SessionStarted", {
     readonly session: Schema.Union<readonly [typeof ParentSession, typeof ChildSession]>;
 }>, {}>;
+/** Records the session identity and brain actually 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. */
 export declare class TextOutput extends TextOutput_base {
 }
 declare const ToolStarted_base: Schema.Class<ToolStarted, Schema.TaggedStruct<"ToolStarted", {
@@ -70,6 +48,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. */
 export declare class ToolStarted extends ToolStarted_base {
 }
 declare const ToolFinished_base: Schema.Class<ToolFinished, Schema.TaggedStruct<"ToolFinished", {
@@ -79,21 +58,27 @@ 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. */
 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. */
 export declare class SessionFinished extends SessionFinished_base {
 }
-/** Billing source whose native meter produced a usage or health observation. */
-export declare const Pool: Schema.Literals<readonly ["apiKeys", "claudePlan", "chatgptPlan"]>;
-export type Pool = typeof Pool.Type;
+/** The billing source whose meter produced a usage or rate-limit observation. */
+export declare const BillingPool: Schema.Literals<readonly ["apiKeys", "claudePlan", "chatgptPlan"]>;
+export type BillingPool = typeof BillingPool.Type;
 declare const RateLimitWindow_base: Schema.Class<RateLimitWindow, Schema.Struct<{
+    /** Percentage of the allowance already consumed, 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<{
@@ -102,6 +87,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. */
 export declare class RateLimitsSnapshot extends RateLimitsSnapshot_base {
 }
 declare const PoolRateLimitsUpdated_base: Schema.Class<PoolRateLimitsUpdated, Schema.TaggedStruct<"PoolRateLimitsUpdated", {
@@ -109,13 +95,11 @@ declare const PoolRateLimitsUpdated_base: Schema.Class<PoolRateLimitsUpdated, Sc
     readonly pool: Schema.Literals<readonly ["apiKeys", "claudePlan", "chatgptPlan"]>;
     readonly rateLimits: typeof RateLimitsSnapshot;
 }>, {}>;
-/** Latest native billing-pool rate windows observed during one session. */
+/** The latest rate windows observed for a billing pool during one session. */
 export declare class PoolRateLimitsUpdated extends PoolRateLimitsUpdated_base {
 }
-/** Normalized events emitted by every parent and child SDK backend. */
-export declare const SessionEvent: Schema.Union<readonly [typeof SessionStarted, typeof TextOutput, typeof ToolStarted, typeof ToolFinished, typeof PoolRateLimitsUpdated, typeof SessionFinished]>;
-export type SessionEvent = typeof SessionEvent.Type;
-/** Pure deriver: a per-Agent parent override wins over the instance default. */
-export declare const resolveParentModel: (agent: Agent, instanceDefault: Option.Option<ModelId>) => Option.Option<ModelId>;
+/** 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]>;
+export type AgentSessionEvent = typeof AgentSessionEvent.Type;
 export {};
-//# sourceMappingURL=agent.d.ts.map
+//# sourceMappingURL=session.d.ts.map

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

@@ -0,0 +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"}

package/dist/agent/session.js

@@ -0,0 +1,93 @@
+import { Schema } from "effect";
+import { AgentName } from "./agent.js";
+import { BrainSpec } from "./brain.js";
+/** Identity usine assigns to a parent or child session within an Attempt. */
+export const AgentSessionId = Schema.NonEmptyString.pipe(Schema.brand("AgentSessionId"));
+const PositiveInt = Schema.Int.check(Schema.isGreaterThanOrEqualTo(1));
+/** Maximum child sessions one Attempt may spawn over its lifetime, including sequential spawns. */
+export const ChildSessionBudget = PositiveInt.pipe(Schema.brand("ChildSessionBudget"));
+/** The 1-based child spawn request number within an Attempt, including requests rejected by the budget. */
+export const ChildSessionCount = PositiveInt.pipe(Schema.brand("ChildSessionCount"));
+/** The session coordinating an Attempt and delegating work to its coding children. */
+export class ParentSession extends Schema.TaggedClass("Agent/ParentSession")("ParentSession", {
+    id: AgentSessionId,
+    agent: AgentName,
+    brain: BrainSpec,
+}) {
+}
+/** A coding session delegated by the Attempt's parent; children cannot delegate to further children. */
+export class ChildSession extends Schema.TaggedClass("Agent/ChildSession")("ChildSession", {
+    id: AgentSessionId,
+    parentId: AgentSessionId,
+    agent: AgentName,
+    brain: BrainSpec,
+}) {
+}
+/** A participant in an Attempt, with its role, Agent, and effective brain recorded. */
+export const AgentSession = Schema.Union([ParentSession, ChildSession]);
+/** Records the session identity and brain actually selected at launch. */
+export class SessionStarted extends Schema.TaggedClass("Agent/SessionStarted")("SessionStarted", { session: AgentSession }) {
+}
+/** Completed assistant text emitted during the session, which may precede its final result. */
+export class TextOutput extends Schema.TaggedClass("Agent/TextOutput")("TextOutput", {
+    session: AgentSession,
+    text: Schema.NonEmptyString,
+}) {
+}
+/** A session began a tool call; `callId` pairs it with the corresponding result. */
+export class ToolStarted extends Schema.TaggedClass("Agent/ToolStarted")("ToolStarted", {
+    session: AgentSession,
+    callId: Schema.NonEmptyString,
+    tool: Schema.NonEmptyString,
+    input: Schema.Json,
+}) {
+}
+/** A tool call returned its output; a tool error does not by itself close the session. */
+export class ToolFinished extends Schema.TaggedClass("Agent/ToolFinished")("ToolFinished", {
+    session: AgentSession,
+    callId: Schema.NonEmptyString,
+    tool: Schema.NonEmptyString,
+    output: Schema.Json,
+    isError: Schema.Boolean,
+}) {
+}
+/** Marks the end of a session's activity in the transcript; the Attempt's outcome is recorded separately. */
+export class SessionFinished extends Schema.TaggedClass("Agent/SessionFinished")("SessionFinished", { session: AgentSession }) {
+}
+/** The billing source whose meter produced a usage or rate-limit observation. */
+export const BillingPool = Schema.Literals(["apiKeys", "claudePlan", "chatgptPlan"]);
+/** A billing pool's observed usage for one allowance window. */
+export class RateLimitWindow extends Schema.Class("Agent/RateLimitWindow")({
+    /** Percentage of the allowance already consumed, including usage outside this Attempt. */
+    usedPercent: Schema.Number,
+    /** Length of the allowance window; absent when the provider omits it. */
+    windowDurationMinutes: Schema.OptionFromNullOr(Schema.Number),
+    /** When the allowance resets; absent when the provider omits it. */
+    resetsAt: Schema.OptionFromNullOr(Schema.DateTimeUtcFromString),
+}) {
+}
+/** The allowance windows reported together by a provider; omitted windows remain unknown. */
+export class RateLimitsSnapshot extends Schema.Class("Agent/RateLimitsSnapshot")({
+    limitId: Schema.OptionFromNullOr(Schema.String),
+    limitName: Schema.OptionFromNullOr(Schema.String),
+    primary: Schema.OptionFromNullOr(RateLimitWindow),
+    secondary: Schema.OptionFromNullOr(RateLimitWindow),
+}) {
+}
+/** The latest rate windows observed for a billing pool during one session. */
+export class PoolRateLimitsUpdated extends Schema.TaggedClass("Agent/PoolRateLimitsUpdated")("PoolRateLimitsUpdated", {
+    session: AgentSession,
+    pool: BillingPool,
+    rateLimits: RateLimitsSnapshot,
+}) {
+}
+/** Session activity and billing observations recorded in an Attempt's transcript. */
+export const AgentSessionEvent = Schema.Union([
+    SessionStarted,
+    TextOutput,
+    ToolStarted,
+    ToolFinished,
+    PoolRateLimitsUpdated,
+    SessionFinished,
+]);
+//# sourceMappingURL=session.js.map

package/dist/agent/session.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"session.js","sourceRoot":"","sources":["../../src/agent/session.ts"],"names":[],"mappings":"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"}

package/dist/attempt/attempt.d.ts

@@ -0,0 +1,41 @@
+import { Schema } from "effect";
+import { BrainSpec } from "../agent/brain.ts";
+import { AttemptFailure } from "./failure.ts";
+/** Identity of one execution try; each retry receives a new identity under the same Run and Step. */
+export declare const AttemptId: Schema.brand<Schema.NonEmptyString, "AttemptId">;
+export type AttemptId = typeof AttemptId.Type;
+/**
+ * 1-based position of a try under its step. Retries are attempt N+1 under the
+ * same step, and the auto-retry cap counts total attempts.
+ */
+export declare const AttemptNumber: Schema.brand<Schema.Int, "AttemptNumber">;
+export type AttemptNumber = typeof AttemptNumber.Type;
+/** Task text given to the agent after loop interpolation or an operator's edit-and-retry amendment. */
+export declare const AttemptTask: Schema.brand<Schema.String, "AttemptTask">;
+export type AttemptTask = typeof AttemptTask.Type;
+declare const Attempt_base: Schema.Class<Attempt, Schema.Struct<{
+    readonly id: Schema.brand<Schema.NonEmptyString, "AttemptId">;
+    readonly runId: Schema.brand<Schema.NonEmptyString, "RunId">;
+    readonly stepName: Schema.brand<Schema.NonEmptyString, "StepName">;
+    readonly worker: Schema.brand<Schema.String, "WorkerName">;
+    readonly number: Schema.brand<Schema.Int, "AttemptNumber">;
+    readonly brain: typeof BrainSpec;
+    readonly parentModel: Schema.OptionFromNullOr<Schema.brand<Schema.String, "ModelId">>;
+    readonly startedAt: Schema.DateTimeUtc;
+    readonly outcome: Schema.Option<Schema.Union<readonly [typeof import("./outcome.ts").AttemptSucceeded, typeof import("./outcome.ts").AttemptFailed, typeof import("./outcome.ts").AttemptCanceled]>>;
+}>, {}>;
+/** One try of a step on a worker. `outcome` is none while the attempt is in flight. */
+export declare class Attempt extends Attempt_base {
+}
+/**
+ * The auto-retry law: only an infra failure retries, and only while the attempt
+ * number is below `maxAutoAttempts` (ADR 0002).
+ * `number` is the failed try's position; `maxAutoAttempts` includes the first try.
+ */
+export declare const shouldAutoRetry: (options: {
+    readonly failure: AttemptFailure;
+    readonly number: AttemptNumber;
+    readonly maxAutoAttempts: AttemptNumber;
+}) => boolean;
+export {};
+//# sourceMappingURL=attempt.d.ts.map

package/dist/attempt/attempt.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"attempt.d.ts","sourceRoot":"","sources":["../../src/attempt/attempt.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAChC,OAAO,EAAE,SAAS,EAAW,MAAM,mBAAmB,CAAC;AAIvD,OAAO,EAAE,cAAc,EAA0B,MAAM,cAAc,CAAC;AAGtE,qGAAqG;AACrG,eAAO,MAAM,SAAS,kDAAwD,CAAC;AAE/E,MAAM,MAAM,SAAS,GAAG,OAAO,SAAS,CAAC,IAAI,CAAC;AAE9C;;;GAGG;AACH,eAAO,MAAM,aAAa,2CAEzB,CAAC;AACF,MAAM,MAAM,aAAa,GAAG,OAAO,aAAa,CAAC,IAAI,CAAC;AAEtD,uGAAuG;AACvG,eAAO,MAAM,WAAW,4CAEW,CAAC;AACpC,MAAM,MAAM,WAAW,GAAG,OAAO,WAAW,CAAC,IAAI,CAAC;;;;;;;;;;;;AAElD,uFAAuF;AACvF,qBAAa,OAAQ,SAAQ,YAU3B;CAAG;AAEL;;;;GAIG;AACH,eAAO,MAAM,eAAe,YAAa;IACvC,QAAQ,CAAC,OAAO,EAAE,cAAc,CAAC;IACjC,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC;IAC/B,QAAQ,CAAC,eAAe,EAAE,aAAa,CAAC;CACzC,KAAG,OAA8F,CAAC"}

package/dist/attempt/attempt.js

@@ -0,0 +1,36 @@
+import { Schema } from "effect";
+import { BrainSpec, ModelId } from "../agent/brain.js";
+import { RunId } from "../run/run.js";
+import { StepName } from "../step/step.js";
+import { WorkerName } from "../worker.js";
+import { AttemptFailure, isAutoRetryableFailure } from "./failure.js";
+import { AttemptOutcome } from "./outcome.js";
+/** Identity of one execution try; each retry receives a new identity under the same Run and Step. */
+export const AttemptId = Schema.NonEmptyString.pipe(Schema.brand("AttemptId"));
+/**
+ * 1-based position of a try under its step. Retries are attempt N+1 under the
+ * same step, and the auto-retry cap counts total attempts.
+ */
+export const AttemptNumber = Schema.Int.check(Schema.isGreaterThanOrEqualTo(1)).pipe(Schema.brand("AttemptNumber"));
+/** Task text given to the agent after loop interpolation or an operator's edit-and-retry amendment. */
+export const AttemptTask = Schema.String.check(Schema.isPattern(/\S/u, { message: "Expected non-blank task text" })).pipe(Schema.brand("AttemptTask"));
+/** One try of a step on a worker. `outcome` is none while the attempt is in flight. */
+export class Attempt extends Schema.Class("Attempt")({
+    id: AttemptId,
+    runId: RunId,
+    stepName: StepName,
+    worker: WorkerName,
+    number: AttemptNumber,
+    brain: BrainSpec,
+    parentModel: Schema.OptionFromNullOr(ModelId),
+    startedAt: Schema.DateTimeUtc,
+    outcome: Schema.Option(AttemptOutcome),
+}) {
+}
+/**
+ * The auto-retry law: only an infra failure retries, and only while the attempt
+ * number is below `maxAutoAttempts` (ADR 0002).
+ * `number` is the failed try's position; `maxAutoAttempts` includes the first try.
+ */
+export const shouldAutoRetry = (options) => isAutoRetryableFailure(options.failure) && options.number < options.maxAutoAttempts;
+//# sourceMappingURL=attempt.js.map

package/dist/attempt/attempt.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"attempt.js","sourceRoot":"","sources":["../../src/attempt/attempt.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAChC,OAAO,EAAE,SAAS,EAAE,OAAO,EAAE,MAAM,mBAAmB,CAAC;AACvD,OAAO,EAAE,KAAK,EAAE,MAAM,eAAe,CAAC;AACtC,OAAO,EAAE,QAAQ,EAAE,MAAM,iBAAiB,CAAC;AAC3C,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAC1C,OAAO,EAAE,cAAc,EAAE,sBAAsB,EAAE,MAAM,cAAc,CAAC;AACtE,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAE9C,qGAAqG;AACrG,MAAM,CAAC,MAAM,SAAS,GAAG,MAAM,CAAC,cAAc,CAAC,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,WAAW,CAAC,CAAC,CAAC;AAI/E;;;GAGG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG,MAAM,CAAC,GAAG,CAAC,KAAK,CAAC,MAAM,CAAC,sBAAsB,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAClF,MAAM,CAAC,KAAK,CAAC,eAAe,CAAC,CAC9B,CAAC;AAGF,uGAAuG;AACvG,MAAM,CAAC,MAAM,WAAW,GAAG,MAAM,CAAC,MAAM,CAAC,KAAK,CAC5C,MAAM,CAAC,SAAS,CAAC,KAAK,EAAE,EAAE,OAAO,EAAE,8BAA8B,EAAE,CAAC,CACrE,CAAC,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,aAAa,CAAC,CAAC,CAAC;AAGpC,uFAAuF;AACvF,MAAM,OAAO,OAAQ,SAAQ,MAAM,CAAC,KAAK,CAAU,SAAS,CAAC,CAAC;IAC5D,EAAE,EAAE,SAAS;IACb,KAAK,EAAE,KAAK;IACZ,QAAQ,EAAE,QAAQ;IAClB,MAAM,EAAE,UAAU;IAClB,MAAM,EAAE,aAAa;IACrB,KAAK,EAAE,SAAS;IAChB,WAAW,EAAE,MAAM,CAAC,gBAAgB,CAAC,OAAO,CAAC;IAC7C,SAAS,EAAE,MAAM,CAAC,WAAW;IAC7B,OAAO,EAAE,MAAM,CAAC,MAAM,CAAC,cAAc,CAAC;CACvC,CAAC;CAAG;AAEL;;;;GAIG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG,CAAC,OAI/B,EAAW,EAAE,CAAC,sBAAsB,CAAC,OAAO,CAAC,OAAO,CAAC,IAAI,OAAO,CAAC,MAAM,GAAG,OAAO,CAAC,eAAe,CAAC"}