@usine/durable 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Philippe L'ATTENTION
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,82 @@
-# Temporary Holding Version
+# @usine/durable
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Runs an attempt's Pi parent in the orchestrator on [`@earendil-works/pi-durable`](https://www.npmjs.com/package/@earendil-works/pi-durable) storage. Each attempt is one durable task, `usine.attempt`, with one parent conversation. The parent's only tool, `subagent`, starts the agent's Claude Code, Codex, or Pi child in the attempt's checkout. After an orchestrator restart, unfinished attempts continue from their last committed step. [Attempt execution](https://docs.usine.dev/architecture/execution/) covers the durable layer and live channel.
+
+## Entry points
+
+- `/attempt-runtime`: the `AttemptRuntime` contract that the executor calls, with `AttemptRequest`, `StoredRequest`, and `AttemptReport`.
+- `/harness`: the `DurableHarness` service, which manages the open pi-durable harness, and its platform-free `layer(options)`.
+- `/backup`: `backup(instanceDirectory, destination)`, an online copy of `.usine/durable.sqlite` through SQLite's backup API, hard-linked into place so it never overwrites a file. `usine backup` writes it next to the runtime database copy.
+- `/live`: the Node composition: the harness on `<instance>/.usine/durable.sqlite`, Pi's configured models and credentials, and the child backends from `@usine/agents`.
+- `/testing`: a scripted parent model and stub children for whole-attempt tests, and a stub `AttemptRuntime` for executor tests.
+
+```ts
+import { layer as durableLayer } from "@usine/durable/live";
+
+// Provides AttemptRuntime and DurableHarness; requires ChildProcessSpawner and ClaudeLoginLock,
+// the per-Worker lock the executor's preflight shares (claudeLoginLockLayer from @usine/executor).
+const attempts = durableLayer(instanceDirectory);
+```
+
+Building the layer installs the usine extension and resumes tasks. Closing it writes no task outcome, so the next start resumes the same work.
+
+## Run an attempt
+
+`execute(request, io)` creates the attempt's task, or finds it by attempt id after a restart, and waits for the outcome. Attempt and task ids are committed together, so a later call always finds the task. `isLive(attemptId)` is true from the first `execute` until the terminal envelope is sent or the task is canceled, so a restarted orchestrator reattaches the attempt.
+
+After the terminal envelope, `finished(attemptId)` returns `ParentReported` with the report, `ParentFailed` with the failure, or `ResultRecorded` once the executor calls `recordResult(attemptId, result)` with the harvested result. If the orchestrator stopped before the engine recorded the outcome, it finishes the attempt with this instead of running the agent again. A canceled task leaves nothing.
+
+`recordUnsupervised(attemptId, unsupervised)` stores the unsupervised time that the runaway guard counted, and `unsupervised(attemptId)` reads it back for a reattached attempt's guard (#178). It never decreases and is none until a guard records it.
+
+`io` receives `Started` with the resolved parent model, `SessionEvent`s for the parent's committed entries and the children's events in order, `InterventionApplied` or `InterventionRejected`, and one `Final`, `Failed`, or `Interrupted`. The next sequence is stored, so a reattached `execute` continues the numbering. Progress is committed once per parent entry, after its envelopes are appended, and once per other envelope. After a crash before a commit, the same envelopes are relayed with the same sequences, and the transcript keeps one copy.
+
+`AttemptRequest.host` (`@usine/agents/child-host`) is where the worker runs children: `LocalProcess` here or `RemoteShell` over SSH. The `subagent` tool passes it and the worker's name to every child, and tags child logs with the attempt id. `AttemptRequest.environment` is the whole environment of every local child and its commands; on `RemoteShell`, it's exported over the machine's own.
+
+The task doesn't store the host or environment. It stores the run spec, worker, and worktree as a `StoredRequest`, which `request(attemptId)` returns, so a reattachment knows its run spec, base commit, and worktree. After a restart, the parent waits for the next `execute` to supply the host and environment before launching another child.
+
+`AttemptRequest.gatewayCredential`, supplied the same way, is the credential kind that the worker's gateway uses for the children, from the worker's latest preflight, or none if they use their harness's login. The `subagent` tool records it on each child's `ChildSession` at start, so usage counts the child in the right pool. A preflight during the attempt applies to its next child.
+
+Children aren't resumed after a restart: the tool call ends as interrupted with the output committed so far, and the parent model decides next.
+
+## Operator input
+
+`intervene(attemptId, intervention)` needs a live `execute`. It records the inbound envelope, applies the action, and records the result, in order with the relay's envelopes, so a sink's `append` must not wait for it. Input sent before `execute` has read durable storage and started relaying fails. `attached(attemptId)` completes once an `execute` in this process relays the channel; the runaway guard waits on it to deliver a reattached attempt's due warning (#178).
+
+- `OperatorMessage` places a hold on the parent or a child; `Release` ends it. A held parent's answers wait for the operator instead of ending the attempt, and a released waiting parent continues with a new turn. A held child's report goes to the parent only after `Release`. `Steer` places no hold.
+- Input to a working parent joins after the current tool round; to a working child, at its next step. Until then, `InterventionApplied` says `queued` and `AttemptRecordDoc.queuedInputs` keeps it. A second receipt for the same input sequence reports the read, with a child's state, or `InterventionRejected` if it never happens, including for a child lost to a restart.
+- Input to a paused or waiting parent, or an idle or paused child, starts its next turn.
+- `Interrupt` aborts the parent's turn and children, withdraws queued input, and holds the parent until a `Steer`, `OperatorMessage`, or `Release` resumes it.
+
+`AttemptReport.answeredOperator` is true if the parent's last turn replied to an operator message or steer, not to the release guidance, without delegating after it. `harvestedResult(report, facts)` builds the `StepResult`, and fails such a report with `AgentFailure` if the checkout has no facts.
+
+`cancel(attemptId)` aborts the task bottom-up, waits until it's terminal, and ends `execute` with `Interrupted`. A child whose launch hasn't returned, such as a Claude child waiting to relaunch, starts no process.
+
+## Recovery from a poisoned session or a stuck step
+
+Each time the harness opens, before tasks resume, the runtime reads every live task's `pi.live`, `pi.inbox`, `pi.usage`, `pi.agent`, and `pi.provider` documents. An unreadable document, for example one whose delta chain doesn't apply, stops every step that needs it. In one commit, the runtime retires it unread, recreates it with its initial value, and records the reason on the attempt whose `usine.attempt` task has the conversation. It then aborts that task: the abort applies to the generation and tool tasks first, and the abort handler fails the attempt with an `InfraFailure` giving the reason, which `execute` and a reattachment report. Other attempts keep running.
+
+A pi-durable commit that fails after storage admission poisons the session. `DurableHarness` logs the cause, closes the session, reopens the storage, and resumes. A `DurableHarness.use` call failed by the reopen runs once more.
+
+pi-durable reports failures that don't fail their caller through `onReport`. The harness logs a failure's first report, then its repeat count at most every five seconds. 1,000 reports of one failure with no commit adopted means a step that can't succeed. pi-durable retries it in microtasks, with no timer or I/O until the harness closes, so the harness closes from inside the report and reopens the storage. That clears stale scheduler state and repeats the document check.
+
+If the reopened harness is stuck again within a minute, it stops for good: it logs the cause as an error, later calls fail with a `DurableHarnessError` naming it, and running attempts fail with `InfraFailure`. The next orchestrator start reopens the storage.
+
+pi-durable has no cross-process locking: tasks and documents from a second writer can't be read back. `usine up` locks the instance folder to prevent this.
+
+## Testing
+
+```ts
+import { answer, delegate, layer, StubChildren } from "@usine/durable/testing";
+
+const attempts = layer({
+  database: "/tmp/attempt.sqlite",
+  parent: [delegate("Fix the flaky test"), answer("Fixed it.")],
+});
+```
+
+- `layer({ database, parent })` provides `AttemptRuntime`, `DurableHarness`, `ChildBackend`, and `StubChildren` on a SQLite file. To simulate a restart, build a second layer on the file with the remaining answers.
+- `parent` lists the parent model's answers, one per request: `delegate(task)` calls `subagent`, `answer(text)` is a final answer, and a function gets the request's context and returns an answer.
+- `PARENT_MODEL`, `faux/faux-1`, is the scripted model. It accepts efforts up to `high`; an empty `RunSpec.parentModel` selects it.
+- `StubChildren.next` waits for the next child. A `StubChild` exposes `request`, `emit(event)`, `reply(message)`, `block(message)`, `interrupted`, and its `interventions`. A held child replies after `Release`.
+- `fauxParent(steps)` and `stubChildBackendLayer` are the two halves, to compose `DurableHarness` with other storage.
+- `stubAttemptRuntime(storage, parent)` is an in-memory `AttemptRuntime` for executor and engine tests without a parent model. `parent` scripts each attempt's final message or `AttemptReport` (`completes`, `worksFor(millis)`, or a `StubParent`). Rebuilding it on the same `StubStorage` simulates a restart. `StubStorage.unsupervised` contains what `recordUnsupervised` stored, and `attached` completes when `execute` starts recording.

package/dist/attempt/documents.d.ts

@@ -0,0 +1,86 @@
+import { type ConversationId, type SubmissionId, type TaskId } from "@earendil-works/pi-durable";
+import type * as AttemptChannel from "@usine/core/attempt/channel";
+/**
+ * The return value of a completed `usine.attempt` task. `answeredOperator` is absent on older
+ * results.
+ */
+export type AttemptResult = {
+    message: string;
+    answeredOperator?: boolean;
+};
+/**
+ * An accepted, unread operator input, queued either by the busy parent (with its submission) or by
+ * a working child (with its session ID).
+ */
+type QueuedInput = {
+    inputSequence: number;
+    submission: SubmissionId;
+    intervention: typeof AttemptChannel.Intervention.Encoded;
+} | {
+    inputSequence: number;
+    child: string;
+    intervention: typeof AttemptChannel.Intervention.Encoded;
+};
+/** The durable record of one Attempt, keyed by Attempt ID and kept after the task ends. */
+export type AttemptRecord = {
+    /** Written in the same commit as the task. */
+    taskId: TaskId<AttemptResult> | null;
+    /** The parent model resolved at start. */
+    parentModel: string | null;
+    parentConversation: ConversationId | null;
+    /** The number of child spawn requests, including those rejected by the child-session budget. */
+    children: number;
+    /**
+     * The first blocker, question, or harness failure reported by a child, which fails the Attempt
+     * unless the parent relays one. A missing `kind` means `blocked`.
+     */
+    childBlocker: {
+        sessionId: string;
+        message: string;
+        kind?: "blocked" | "question" | "failed";
+    } | null;
+    childBudgetExceeded: {
+        attempted: number;
+        max: number;
+    } | null;
+    /** The next outbound and inbound sequence numbers. */
+    nextOutbound: number;
+    nextInbound: number;
+    /**
+     * The newest parent entry whose session events were all relayed, and the parent's last relayed
+     * token count.
+     */
+    relayedEntry: number;
+    relayedTokens: number;
+    terminalRelayed: boolean;
+    /** The harvested `StepResult` as JSON, absent until the executor records it. */
+    result?: string;
+    /**
+     * The reason the parent conversation couldn't be read from storage. Written before the task is
+     * aborted, so the Attempt fails with it.
+     */
+    storageFailure?: string;
+    /** Operator inputs with a queued receipt and no delivery receipt, oldest first. */
+    queuedInputs?: QueuedInput[];
+    /**
+     * The unsupervised time in milliseconds, as last recorded by a runaway guard with a wall-clock
+     * ceiling.
+     */
+    unsupervisedMillis?: number;
+};
+export declare const ATTEMPT_RECORD_KIND = "usine.attempt";
+export declare const AttemptRecordDoc: import("@earendil-works/pi-durable").SessionDocFamilyToken<AttemptRecord, null>;
+/**
+ * The operator supervision state of one running Attempt (ADR 0018), scoped to its task. `held`
+ * lists the session IDs under a Hold, including the parent's.
+ */
+export type Hold = {
+    paused: boolean;
+    guidance: string[];
+    held: string[];
+};
+/** The message sent to a released parent if the operator provided none. */
+export declare const RELEASE_GUIDANCE = "The operator released you without further guidance. Continue the task; if it is already done, give your final answer.";
+export declare const HoldDoc: import("@earendil-works/pi-durable").TaskDocToken<Hold>;
+export {};
+//# sourceMappingURL=documents.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"documents.d.ts","sourceRoot":"","sources":["../../src/attempt/documents.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,cAAc,EAGnB,KAAK,YAAY,EACjB,KAAK,MAAM,EACZ,MAAM,4BAA4B,CAAC;AACpC,OAAO,KAAK,KAAK,cAAc,MAAM,6BAA6B,CAAC;AAEnE;;;GAGG;AACH,MAAM,MAAM,aAAa,GAAG;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,gBAAgB,CAAC,EAAE,OAAO,CAAA;CAAE,CAAC;AAE5E;;;GAGG;AACH,KAAK,WAAW,GACZ;IACE,aAAa,EAAE,MAAM,CAAC;IACtB,UAAU,EAAE,YAAY,CAAC;IACzB,YAAY,EAAE,OAAO,cAAc,CAAC,YAAY,CAAC,OAAO,CAAC;CAC1D,GACD;IACE,aAAa,EAAE,MAAM,CAAC;IACtB,KAAK,EAAE,MAAM,CAAC;IACd,YAAY,EAAE,OAAO,cAAc,CAAC,YAAY,CAAC,OAAO,CAAC;CAC1D,CAAC;AAEN,2FAA2F;AAC3F,MAAM,MAAM,aAAa,GAAG;IAC1B,8CAA8C;IAC9C,MAAM,EAAE,MAAM,CAAC,aAAa,CAAC,GAAG,IAAI,CAAC;IACrC,0CAA0C;IAC1C,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,kBAAkB,EAAE,cAAc,GAAG,IAAI,CAAC;IAC1C,gGAAgG;IAChG,QAAQ,EAAE,MAAM,CAAC;IACjB;;;OAGG;IACH,YAAY,EAAE;QACZ,SAAS,EAAE,MAAM,CAAC;QAClB,OAAO,EAAE,MAAM,CAAC;QAChB,IAAI,CAAC,EAAE,SAAS,GAAG,UAAU,GAAG,QAAQ,CAAC;KAC1C,GAAG,IAAI,CAAC;IACT,mBAAmB,EAAE;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;IAC/D,sDAAsD;IACtD,YAAY,EAAE,MAAM,CAAC;IACrB,WAAW,EAAE,MAAM,CAAC;IACpB;;;OAGG;IACH,YAAY,EAAE,MAAM,CAAC;IACrB,aAAa,EAAE,MAAM,CAAC;IACtB,eAAe,EAAE,OAAO,CAAC;IACzB,gFAAgF;IAChF,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;OAGG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,mFAAmF;IACnF,YAAY,CAAC,EAAE,WAAW,EAAE,CAAC;IAC7B;;;OAGG;IACH,kBAAkB,CAAC,EAAE,MAAM,CAAC;CAC7B,CAAC;AAEF,eAAO,MAAM,mBAAmB,kBAAkB,CAAC;AAEnD,eAAO,MAAM,gBAAgB,iFAkB3B,CAAC;AAEH;;;GAGG;AACH,MAAM,MAAM,IAAI,GAAG;IACjB,MAAM,EAAE,OAAO,CAAC;IAChB,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,IAAI,EAAE,MAAM,EAAE,CAAC;CAChB,CAAC;AAEF,2EAA2E;AAC3E,eAAO,MAAM,gBAAgB,0HAC4F,CAAC;AAE1H,eAAO,MAAM,OAAO,yDAKlB,CAAC"}

package/dist/attempt/documents.js

@@ -0,0 +1,30 @@
+import { defineDoc, defineDocFamily, } from "@earendil-works/pi-durable";
+export const ATTEMPT_RECORD_KIND = "usine.attempt";
+export const AttemptRecordDoc = defineDocFamily({
+    kind: ATTEMPT_RECORD_KIND,
+    version: 1,
+    scope: "session",
+    family: true,
+    initial: () => ({
+        taskId: null,
+        parentModel: null,
+        parentConversation: null,
+        children: 0,
+        childBlocker: null,
+        childBudgetExceeded: null,
+        nextOutbound: 1,
+        nextInbound: 1,
+        relayedEntry: 0,
+        relayedTokens: 0,
+        terminalRelayed: false,
+    }),
+});
+/** The message sent to a released parent if the operator provided none. */
+export const RELEASE_GUIDANCE = "The operator released you without further guidance. Continue the task; if it is already done, give your final answer.";
+export const HoldDoc = defineDoc({
+    kind: "usine.hold",
+    version: 1,
+    scope: "task",
+    initial: () => ({ paused: false, guidance: [], held: [] }),
+});
+//# sourceMappingURL=documents.js.map

package/dist/attempt/documents.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"documents.js","sourceRoot":"","sources":["../../src/attempt/documents.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,SAAS,EACT,eAAe,GAGhB,MAAM,4BAA4B,CAAC;AAsEpC,MAAM,CAAC,MAAM,mBAAmB,GAAG,eAAe,CAAC;AAEnD,MAAM,CAAC,MAAM,gBAAgB,GAAG,eAAe,CAAsB;IACnE,IAAI,EAAE,mBAAmB;IACzB,OAAO,EAAE,CAAC;IACV,KAAK,EAAE,SAAS;IAChB,MAAM,EAAE,IAAI;IACZ,OAAO,EAAE,GAAG,EAAE,CAAC,CAAC;QACd,MAAM,EAAE,IAAI;QACZ,WAAW,EAAE,IAAI;QACjB,kBAAkB,EAAE,IAAI;QACxB,QAAQ,EAAE,CAAC;QACX,YAAY,EAAE,IAAI;QAClB,mBAAmB,EAAE,IAAI;QACzB,YAAY,EAAE,CAAC;QACf,WAAW,EAAE,CAAC;QACd,YAAY,EAAE,CAAC;QACf,aAAa,EAAE,CAAC;QAChB,eAAe,EAAE,KAAK;KACvB,CAAC;CACH,CAAC,CAAC;AAYH,2EAA2E;AAC3E,MAAM,CAAC,MAAM,gBAAgB,GAC3B,uHAAuH,CAAC;AAE1H,MAAM,CAAC,MAAM,OAAO,GAAG,SAAS,CAAO;IACrC,IAAI,EAAE,YAAY;IAClB,OAAO,EAAE,CAAC;IACV,KAAK,EAAE,MAAM;IACb,OAAO,EAAE,GAAG,EAAE,CAAC,CAAC,EAAE,MAAM,EAAE,KAAK,EAAE,QAAQ,EAAE,EAAE,EAAE,IAAI,EAAE,EAAE,EAAE,CAAC;CAC3D,CAAC,CAAC"}

package/dist/attempt/events.d.ts

@@ -0,0 +1,22 @@
+import { type EntryRecord, type UsageState } from "@earendil-works/pi-durable";
+import { type AgentSession, type AgentSessionEvent, TokenCount, UsdAmount } from "@usine/core/agent/session";
+import { Option } from "effect";
+/** Returns the trimmed text of an assistant entry, or `None` if it has no text. */
+export declare const assistantText: (entry: EntryRecord) => Option.Option<string>;
+/**
+ * Returns the session events for one committed parent entry, in Pi SDK emission order. User input,
+ * prompt changes, and compaction summaries produce no events.
+ */
+export declare const entryEvents: (entry: EntryRecord, session: AgentSession) => ReadonlyArray<AgentSessionEvent>;
+/** A conversation's token count and cost. `costUsd` is `None` if no model was priced. */
+interface LedgerUsage {
+    readonly totalTokens: TokenCount;
+    readonly costUsd: Option.Option<UsdAmount>;
+}
+/**
+ * Sums a conversation's `pi.usage` ledger over every model. Tokens are output plus uncached input,
+ * where cache writes count and cache reads don't.
+ */
+export declare const ledgerUsage: (usage: Readonly<UsageState> | undefined) => LedgerUsage;
+export {};
+//# sourceMappingURL=events.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"events.d.ts","sourceRoot":"","sources":["../../src/attempt/events.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,WAAW,EAEhB,KAAK,UAAU,EAChB,MAAM,4BAA4B,CAAC;AACpC,OAAO,EACL,KAAK,YAAY,EACjB,KAAK,iBAAiB,EAEtB,UAAU,EAGV,SAAS,EACV,MAAM,2BAA2B,CAAC;AACnC,OAAO,EAAE,MAAM,EAAU,MAAM,QAAQ,CAAC;AA0BxC,mFAAmF;AACnF,eAAO,MAAM,aAAa,UAAW,WAAW,KAAG,MAAM,CAAC,MAAM,CAAC,MAAM,CAQnE,CAAC;AAEL;;;GAGG;AACH,eAAO,MAAM,WAAW,UACf,WAAW,WACT,YAAY,KACpB,aAAa,CAAC,iBAAiB,CA2CjC,CAAC;AAiBF,yFAAyF;AACzF,UAAU,WAAW;IACnB,QAAQ,CAAC,WAAW,EAAE,UAAU,CAAC;IACjC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;CAC5C;AAED;;;GAGG;AACH,eAAO,MAAM,WAAW,UAAW,QAAQ,CAAC,UAAU,CAAC,GAAG,SAAS,KAAG,WAerE,CAAC"}

package/dist/attempt/events.js

@@ -0,0 +1,110 @@
+import { AssistantEntry, ToolResultEntry, } from "@earendil-works/pi-durable";
+import { TextOutput, TokenCount, ToolFinished, ToolStarted, UsdAmount, } from "@usine/core/agent/session";
+import { Option, Schema } from "effect";
+const TextBlock = Schema.Struct({ type: Schema.Literal("text"), text: Schema.String });
+const ToolCallBlock = Schema.Struct({
+    type: Schema.Literal("toolCall"),
+    id: Schema.NonEmptyString,
+    name: Schema.NonEmptyString,
+    arguments: Schema.Json,
+});
+const AssistantMessage = Schema.Struct({
+    role: Schema.Literal("assistant"),
+    content: Schema.Array(Schema.Json),
+});
+const ToolResultMessage = Schema.Struct({
+    role: Schema.Literal("toolResult"),
+    toolCallId: Schema.NonEmptyString,
+    toolName: Schema.NonEmptyString,
+    content: Schema.Json,
+    details: Schema.optionalKey(Schema.Json),
+    isError: Schema.Boolean,
+});
+const decodeAssistant = Schema.decodeUnknownOption(AssistantMessage);
+const decodeToolResult = Schema.decodeUnknownOption(ToolResultMessage);
+const isTextBlock = Schema.is(TextBlock);
+const isToolCallBlock = Schema.is(ToolCallBlock);
+/** Returns the trimmed text of an assistant entry, or `None` if it has no text. */
+export const assistantText = (entry) => Option.flatMap(decodeAssistant(entry.model?.[0]), (message) => {
+    const text = message.content
+        .filter(isTextBlock)
+        .map(({ text }) => text)
+        .join("")
+        .trim();
+    return text.length > 0 ? Option.some(text) : Option.none();
+});
+/**
+ * Returns the session events for one committed parent entry, in Pi SDK emission order. User input,
+ * prompt changes, and compaction summaries produce no events.
+ */
+export const entryEvents = (entry, session) => {
+    if (entry.kind === AssistantEntry.kind) {
+        return Option.match(decodeAssistant(entry.model?.[0]), {
+            onNone: () => [],
+            onSome: (message) => {
+                const events = [];
+                const text = assistantText(entry);
+                if (Option.isSome(text))
+                    events.push(new TextOutput({ session, text: text.value }));
+                for (const block of message.content.filter(isToolCallBlock)) {
+                    events.push(new ToolStarted({
+                        session,
+                        callId: block.id,
+                        tool: block.name,
+                        input: block.arguments,
+                    }));
+                }
+                return events;
+            },
+        });
+    }
+    if (entry.kind === ToolResultEntry.kind) {
+        return Option.match(decodeToolResult(entry.model?.[0]), {
+            onNone: () => [],
+            onSome: (result) => {
+                const output = result.details === undefined
+                    ? { content: result.content }
+                    : { content: result.content, details: result.details };
+                return [
+                    new ToolFinished({
+                        session,
+                        callId: result.toolCallId,
+                        tool: result.toolName,
+                        output,
+                        isError: result.isError,
+                    }),
+                ];
+            },
+        });
+    }
+    return [];
+};
+const Count = Schema.Int.check(Schema.isGreaterThanOrEqualTo(0));
+const Dollars = Schema.Finite.check(Schema.isGreaterThanOrEqualTo(0));
+const UsageLedger = Schema.Struct({
+    models: Schema.Record(Schema.String, Schema.Struct({
+        input: Count,
+        output: Count,
+        cacheWrite: Count,
+        cost: Schema.optionalKey(Schema.Struct({ total: Dollars })),
+    })),
+});
+const decodeUsage = Schema.decodeUnknownOption(UsageLedger);
+/**
+ * Sums a conversation's `pi.usage` ledger over every model. Tokens are output plus uncached input,
+ * where cache writes count and cache reads don't.
+ */
+export const ledgerUsage = (usage) => {
+    const models = Option.match(decodeUsage(usage), {
+        onNone: () => [],
+        onSome: ({ models }) => Object.values(models),
+    });
+    const priced = models.flatMap(({ cost }) => (cost === undefined ? [] : [cost.total]));
+    return {
+        totalTokens: TokenCount.make(models.reduce((total, model) => total + model.output + model.input + model.cacheWrite, 0)),
+        costUsd: priced.length === 0
+            ? Option.none()
+            : Option.some(UsdAmount.make(priced.reduce((total, value) => total + value, 0))),
+    };
+};
+//# sourceMappingURL=events.js.map

package/dist/attempt/events.js.map

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

package/dist/attempt/extension.d.ts

@@ -0,0 +1,48 @@
+import { type Extension } from "@earendil-works/pi-durable";
+import type { ExtensionServices } from "./services.ts";
+/**
+ * Returns the usine extension: the `usine.attempt` task, the `subagent` tool, and the parent's
+ * guidance section.
+ */
+export declare const usineExtension: (services: ExtensionServices) => {
+    extension: Extension<import("@earendil-works/pi-durable").ToolRegistration<import("@earendil-works/pi-ai").TSchema, import("@earendil-works/chord").JsonValue>>;
+    task: import("@earendil-works/pi-durable").Task<{
+        readonly spec: {
+            readonly attemptId: string;
+            readonly repository: string;
+            readonly revision: string;
+            readonly baseCommit: string;
+            readonly payload: import("effect/Schema").Json;
+            readonly task: string;
+            readonly agent: {
+                readonly name: string;
+                readonly brain: {
+                    readonly harness: "claude" | "codex" | "pi";
+                    readonly model: string;
+                    readonly effort: "high" | "low" | "max" | "medium" | "minimal" | "off" | "xhigh";
+                };
+                readonly parentModel: string | null;
+                readonly parentEffort?: "high" | "low" | "max" | "medium" | "minimal" | "off" | "xhigh";
+                readonly persona: string;
+            };
+            readonly parentModel: string | null;
+            readonly maxChildren: number;
+            readonly parentEffort: "high" | "low" | "max" | "medium" | "minimal" | "off" | "xhigh";
+            readonly resume: {
+                readonly _tag: "Pushed";
+                readonly ref: string;
+                readonly commit: string;
+            } | null;
+            readonly conflictingSalvage?: {
+                readonly _tag: "Pushed";
+                readonly ref: string;
+                readonly commit: string;
+            } | null;
+            readonly preparedAt?: string | null;
+            readonly botLogin?: string | null;
+        };
+        readonly worker: string;
+        readonly cwd: string;
+    }, import("./task.ts").AttemptCheckpoint, import("./documents.ts").AttemptResult, object>;
+};
+//# sourceMappingURL=extension.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"extension.d.ts","sourceRoot":"","sources":["../../src/attempt/extension.ts"],"names":[],"mappings":"AAAA,OAAO,EAAmB,KAAK,SAAS,EAAW,MAAM,4BAA4B,CAAC;AAEtF,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AAevD;;;GAGG;AACH,eAAO,MAAM,cAAc,aAAc,iBAAiB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAczD,CAAC"}

package/dist/attempt/extension.js

@@ -0,0 +1,34 @@
+import { defineExtension, section } from "@earendil-works/pi-durable";
+import { BLOCKED_MARKER, FAILED_MARKER, QUESTION_MARKER } from "@usine/agents/runtime";
+import { subagentTool } from "./subagent.js";
+import { attemptTask } from "./task.js";
+/** The extension name, stored in every parent conversation that selects it. */
+const USINE_EXTENSION = "usine";
+const parentGuidance = [
+    "You coordinate one usine Attempt. Your only tool is `subagent`: it delegates one focused task to a child agent working in the Attempt's checkout and returns the child's report.",
+    "- Delegate only independent, focused work; the child cannot create more children.",
+    `- When a child's report starts with ${BLOCKED_MARKER}, ${QUESTION_MARKER}, or ${FAILED_MARKER}, return that report verbatim as your own final answer instead of summarising it.`,
+    "- A `subagent` call that ends as interrupted is not a blocker: the orchestrator restarted and the checkout keeps everything the child did. Delegate again with a task that tells the child to inspect the checkout and continue from its current state.",
+    "- The operator can write to you while you work; a message sent during a delegation reaches you when the delegation returns. Treat it as part of this task. Answer a question and end your turn: the operator then replies or releases you to continue. Follow guidance and keep working. A reply to the operator is never the task's final answer; give the final answer only when the task is done or blocked.",
+].join("\n");
+/**
+ * Returns the usine extension: the `usine.attempt` task, the `subagent` tool, and the parent's
+ * guidance section.
+ */
+export const usineExtension = (services) => {
+    const tool = subagentTool(services);
+    let extension;
+    const task = attemptTask(services, () => {
+        if (extension === undefined)
+            throw new Error("The usine extension is not built yet");
+        return { extension, tool };
+    });
+    extension = defineExtension({
+        name: USINE_EXTENSION,
+        tools: [tool],
+        sections: [section(USINE_EXTENSION, () => parentGuidance, { tag: false })],
+        tasks: [task],
+    });
+    return { extension, task };
+};
+//# sourceMappingURL=extension.js.map

package/dist/attempt/extension.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"extension.js","sourceRoot":"","sources":["../../src/attempt/extension.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAkB,OAAO,EAAE,MAAM,4BAA4B,CAAC;AACtF,OAAO,EAAE,cAAc,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAEvF,OAAO,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAC7C,OAAO,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AAExC,+EAA+E;AAC/E,MAAM,eAAe,GAAG,OAAO,CAAC;AAEhC,MAAM,cAAc,GAAG;IACrB,kLAAkL;IAClL,mFAAmF;IACnF,uCAAuC,cAAc,KAAK,eAAe,QAAQ,aAAa,mFAAmF;IACjL,yPAAyP;IACzP,iZAAiZ;CAClZ,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAEb;;;GAGG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG,CAAC,QAA2B,EAAE,EAAE;IAC5D,MAAM,IAAI,GAAG,YAAY,CAAC,QAAQ,CAAC,CAAC;IACpC,IAAI,SAAgC,CAAC;IACrC,MAAM,IAAI,GAAG,WAAW,CAAC,QAAQ,EAAE,GAAG,EAAE;QACtC,IAAI,SAAS,KAAK,SAAS;YAAE,MAAM,IAAI,KAAK,CAAC,sCAAsC,CAAC,CAAC;QACrF,OAAO,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC;IAC7B,CAAC,CAAC,CAAC;IACH,SAAS,GAAG,eAAe,CAAC;QAC1B,IAAI,EAAE,eAAe;QACrB,KAAK,EAAE,CAAC,IAAI,CAAC;QACb,QAAQ,EAAE,CAAC,OAAO,CAAC,eAAe,EAAE,GAAG,EAAE,CAAC,cAAc,EAAE,EAAE,GAAG,EAAE,KAAK,EAAE,CAAC,CAAC;QAC1E,KAAK,EAAE,CAAC,IAAI,CAAC;KACd,CAAC,CAAC;IACH,OAAO,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC;AAC7B,CAAC,CAAC"}

package/dist/attempt/hubs.d.ts

@@ -0,0 +1,117 @@
+import type { ConversationId, EntryId, TaskId } from "@earendil-works/pi-durable";
+import type { RunningSession } from "@usine/agents/runtime";
+import type { AgentSessionEvent, AgentSessionId } from "@usine/core/agent/session";
+import type { AttemptId } from "@usine/core/attempt";
+import type * as AttemptChannel from "@usine/core/attempt/channel";
+import { Deferred, Effect, Option, Queue, Semaphore } from "effect";
+import type { AttemptRequest } from "../attempt-runtime.ts";
+import type { HarnessListener } from "../harness.ts";
+/**
+ * Whether a child read a queued operator input, with the child's state when it read it, or `None`
+ * if it stopped first.
+ */
+export interface ChildDelivery {
+    readonly _tag: "Delivery";
+    readonly inputSequence: AttemptChannel.Sequence;
+    readonly intervention: AttemptChannel.Intervention;
+    readonly delivered: Option.Option<AttemptChannel.InterventionState>;
+}
+/** Activity queued for relay, in order of occurrence. */
+export type RelayItem = {
+    readonly _tag: "Entry";
+    readonly entry: EntryId;
+} | {
+    readonly _tag: "Event";
+    readonly event: AgentSessionEvent;
+} | {
+    readonly _tag: "Notice";
+    readonly notice: AttemptChannel.WorkerNotice;
+} | ChildDelivery | {
+    readonly _tag: "Wake";
+};
+/**
+ * The relay position of the attached channel, persisted in the Attempt record after each parent
+ * entry and envelope.
+ */
+export interface RelayProgress {
+    outbound: AttemptChannel.Progress;
+    inbound: number;
+    entry: number;
+    tokens: number;
+}
+/** The sink of the `execute` call relaying this Attempt. */
+interface AttachedChannel {
+    readonly io: AttemptChannel.Sink;
+    readonly progress: RelayProgress;
+}
+/** The in-process state of one Attempt. */
+export interface AttemptHub {
+    readonly attemptId: AttemptId;
+    readonly taskId: TaskId;
+    readonly queue: Queue.Queue<RelayItem>;
+    /** Serializes outbound envelopes between the relay and interventions. */
+    readonly emission: Semaphore.Semaphore;
+    /** Serializes operator interventions. */
+    readonly routing: Semaphore.Semaphore;
+    /** The live children by session ID. */
+    readonly children: Map<AgentSessionId, RunningSession>;
+    /**
+     * The sequence numbers of operator inputs queued by children in this process and not yet reported
+     * read or unread. An input missing from this set was queued by a previous process.
+     */
+    readonly childInputs: Set<number>;
+    parent: Option.Option<ConversationId>;
+    channel: Option.Option<AttachedChannel>;
+    /** The Worker notices received before the parent started, sent right after `Started`. */
+    early: ReadonlyArray<AttemptChannel.WorkerNotice>;
+    /**
+     * Completes with the request of the `execute` call relaying this Attempt. Replaced when that call
+     * detaches.
+     */
+    attached: Deferred.Deferred<AttemptRequest>;
+}
+/**
+ * Returns the notices to buffer after `notice`: the latest one, preceded by the last
+ * `WorkerUnresponsive` if the latest is a `WorkerResponsive`.
+ */
+export declare const keepNotice: (kept: ReadonlyArray<AttemptChannel.WorkerNotice>, notice: AttemptChannel.WorkerNotice) => ReadonlyArray<AttemptChannel.WorkerNotice>;
+/** The result of `AttemptHubs.notice`. */
+export type NoticeRouting = {
+    readonly _tag: "Queued";
+} | {
+    readonly _tag: "Kept";
+    readonly kept: ReadonlyArray<AttemptChannel.WorkerNotice>;
+};
+export interface AttemptHubs {
+    /** Returns the Attempt's hub, creating it on first use with the buffered Worker notices. */
+    readonly hub: (attemptId: AttemptId, taskId: TaskId) => Effect.Effect<AttemptHub>;
+    readonly find: (attemptId: AttemptId) => Option.Option<AttemptHub>;
+    /** Routes the parent conversation's entries to the hub from now on. */
+    readonly bindParent: (hub: AttemptHub, parent: ConversationId) => void;
+    /** Queues a session event that has no parent entry. */
+    readonly event: (hub: AttemptHub, event: AgentSessionEvent) => Effect.Effect<void>;
+    /**
+     * Queues a Worker notice. If the Attempt has no hub in this process, buffers it with `keepNotice`
+     * until the hub is created.
+     */
+    readonly notice: (attemptId: AttemptId, notice: AttemptChannel.WorkerNotice) => Effect.Effect<NoticeRouting>;
+    readonly delivery: (hub: AttemptHub, delivery: ChildDelivery) => Effect.Effect<void>;
+    /**
+     * Completes when an `execute` call is relaying the Attempt, even if the hub doesn't exist yet.
+     */
+    readonly attached: (attemptId: AttemptId) => Effect.Effect<void>;
+    /** Routes commits to hubs and wakes every hub after a reopen or stop. */
+    readonly listener: HarnessListener;
+}
+export declare const attemptHubs: Effect.Effect<{
+    hub: (attemptId: AttemptId, taskId: TaskId) => Effect.Effect<AttemptHub, never, never>;
+    find: (attemptId: string & import("effect/Brand").Brand<"AttemptId">) => Option.Option<AttemptHub>;
+    bindParent: (hub: AttemptHub, parent: ConversationId) => void;
+    event: (target: AttemptHub, event: import("@usine/core/agent/session").PoolRateLimitsUpdated | import("@usine/core/agent/session").ProviderRecovered | import("@usine/core/agent/session").ProviderRetrying | import("@usine/core/agent/session").SessionFinished | import("@usine/core/agent/session").SessionIdle | import("@usine/core/agent/session").SessionResumed | import("@usine/core/agent/session").SessionStarted | import("@usine/core/agent/session").SessionTokensUpdated | import("@usine/core/agent/session").TextOutput | import("@usine/core/agent/session").ToolFinished | import("@usine/core/agent/session").ToolStarted) => Effect.Effect<void, never, never>;
+    notice: (attemptId: string & import("effect/Brand").Brand<"AttemptId">, notice: AttemptChannel.WorkerResponsive | AttemptChannel.WorkerUnresponsive) => Effect.Effect<NoticeRouting, never, never>;
+    delivery: (target: AttemptHub, delivery: ChildDelivery) => Effect.Effect<void, never, never>;
+    attached: (attemptId: string & import("effect/Brand").Brand<"AttemptId">) => Effect.Effect<void, never, never>;
+    listener: HarnessListener;
+}, never, never>;
+export {};
+//# sourceMappingURL=hubs.d.ts.map

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

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