@usine/executor 0.2.1 → 0.4.0

package/dist/executor.js

@@ -4,11 +4,13 @@ import { ChildSessionBudget } from "@usine/core/agent/session";
 import { AttemptTask, AttemptId } from "@usine/core/attempt";
 import * as AttemptChannel from "@usine/core/attempt/channel";
 import { AttemptFailure } from "@usine/core/attempt/failure";
+import { LoopName, LoopPermissions } from "@usine/core/loop";
+import { SalvagePushed, SalvageRef } from "@usine/core/attempt/salvage";
 import { RepositoryName, RepositoryRevision } from "@usine/core/repository";
-import { WorkerName, WorkerKind } from "@usine/core/worker";
+import { RunId } from "@usine/core/run";
+import { BotAccount, BotLogin, ContainerLimits, MachineId, MachineProvider, WorkerName, WorkerKind, } from "@usine/core/worker";
 import { StepResult } from "@usine/core/step/result";
-import { Context, Effect, Redacted, Schema, Scope } from "effect";
-/** The Worker operation that failed during readiness checks or an Attempt's lifecycle. */
+import { Context, Effect, Option, Predicate, Redacted, Schema, Scope } from "effect";
 export const ExecutorOperation = Schema.Literals([
     "preflight",
     "prepare",
@@ -16,43 +18,104 @@ export const ExecutorOperation = Schema.Literals([
     "cancel",
     "cleanup",
 ]);
-/** A prerequisite a Worker must satisfy before it can accept Attempts. */
 export const WorkerCapability = Schema.Literals([
     "machine",
     "toolchain",
-    "run-host",
+    "memory",
     "harness-login",
     "credentials",
+    "gateway",
+    "container",
+    "provider",
 ]);
-/** A Worker operation failed before its requested work completed. */
 export class ExecutorOperationError extends Schema.TaggedError("@usine/executor/ExecutorOperationError")("ExecutorOperationError", {
+    /** `cleanup` includes removing a checkout, its credential, or credentials left by an earlier process. */
     operation: ExecutorOperation,
+    /** An operator-facing summary without the Worker name. Not part of the contract; branch on `operation`. */
     message: Schema.NonEmptyString,
+    /** The underlying failure, for example an `Error` with the command's stderr, or a timeout. */
     cause: Schema.Defect(),
 }) {
 }
-/** A Worker could not obtain access to the repository assigned to an Attempt. */
+/**
+ * `refused` if a retry gets the same result: the installation doesn't cover the repository,
+ * lacks a permission, or is suspended, or an exe.dev Worker has no integration for it.
+ * `unreachable` if a retry can succeed: a GitHub outage or rate limit, or no response from a
+ * Gateway or exe.dev command.
+ */
+export const CredentialUnavailableReason = Schema.Literals(["refused", "unreachable"]);
 export class CredentialUnavailableError extends Schema.TaggedError("@usine/executor/CredentialUnavailableError")("CredentialUnavailableError", {
     repository: RepositoryName,
+    reason: CredentialUnavailableReason,
+    /** An operator-facing summary, including GitHub's reason for a refusal. */
     message: Schema.NonEmptyString,
+    /** The underlying failure, for example the GitHub API error from minting the token. */
     cause: Schema.Defect(),
 }) {
 }
-/** A verify-only preflight found a Worker capability missing or incompatible. */
+/** The error when preflight finds a Worker capability missing or incompatible. */
 export class WorkerCapabilityError extends Schema.TaggedError("@usine/executor/WorkerCapabilityError")("WorkerCapabilityError", {
     worker: WorkerName,
+    /**
+     * - `machine`: the machine or VM is absent, stopped, or unreachable, or its Worker directory
+     *   isn't writable.
+     * - `toolchain`: Git or a brain's harness doesn't run.
+     * - `memory`: less than 1.5 GiB per concurrent Attempt, no swap for more than one, or memory
+     *   not reported.
+     * - `harness-login`: a brain's harness isn't logged in.
+     * - `credentials`: an exe.dev integration isn't ready, or the Worker kind can't issue a
+     *   read-only credential for a `permissions: read` Loop.
+     * - `gateway`: the Gateway doesn't respond or isn't reachable from the machine.
+     * - `container`: the machine's Docker doesn't respond to the SSH user, the SSH user can use
+     *   Docker's socket without the `docker` CLI, the Attempt image can't be pulled, or its user ID
+     *   differs from the SSH user's.
+     * - `provider`: a provisioned Worker's provider refuses its token, or its image, SSH key,
+     *   network, server type, or location doesn't exist there.
+     */
     capability: WorkerCapability,
     message: Schema.NonEmptyString,
+    /** The observed value, for example unrecognized `git --version` output or the harness readiness report. */
     cause: Schema.Defect(),
 }) {
 }
-/** A readiness, access, or lifecycle failure reported by a Worker operation. */
+/**
+ * `capacity` if the provider has no machine of the configured type now, `quota` if the account's
+ * limits are reached, `refused` if the provider refuses the token or the request, `provider` for
+ * an API error or rate limit, `unreachable` if the API doesn't respond, and `timeout` if the
+ * machine didn't answer over SSH in time. Each is retried later.
+ */
+export const MachineUnavailableReason = Schema.Literals([
+    "capacity",
+    "quota",
+    "refused",
+    "provider",
+    "unreachable",
+    "timeout",
+]);
+/**
+ * The error when a provisioned Worker can't create a machine for an Attempt. The Run keeps
+ * waiting, and the scheduler tries again later; it isn't an Attempt failure.
+ */
+export class MachineUnavailableError extends Schema.TaggedError("@usine/executor/MachineUnavailableError")("MachineUnavailableError", {
+    worker: WorkerName,
+    provider: MachineProvider,
+    reason: MachineUnavailableReason,
+    /** An operator-facing summary with the provider's own message. Contains no token. */
+    message: Schema.NonEmptyString,
+}) {
+}
 export const ExecutorError = Schema.Union([
     ExecutorOperationError,
     CredentialUnavailableError,
     WorkerCapabilityError,
 ]);
-/** Logs every preflight refusal so a missing capability is explainable from logs alone. */
+/** The report of a Worker that runs Attempts as designed, without containers. */
+export const fullPreflight = {
+    degraded: Option.none(),
+    deferred: Option.none(),
+    containerLimits: Option.none(),
+};
+/** Logs each preflight failure at error level. */
 export const logPreflightFailure = (effect) => Effect.tapError(effect, (error) => error instanceof WorkerCapabilityError
     ? Effect.logError("Worker preflight failed", {
         error: error._tag,
@@ -64,37 +127,142 @@ export const logPreflightFailure = (effect) => Effect.tapError(effect, (error) =
         error: error._tag,
         message: error.message,
     }));
-/** The repository, revision, and Agent task assigned to a Worker for one fresh Attempt checkout. */
 export class CheckoutRequest extends Schema.Class("@usine/executor/CheckoutRequest")({
+    /** The checkout directory name, and the key for `cancel`, `intervene`, `isLive`, and `outcome`. */
     attemptId: AttemptId,
     worker: WorkerName,
+    /** The only repository the Attempt's credential can access (ADR 0011). */
     repository: RepositoryName,
+    /** The Loop of the Attempt's Run, shown in a `read` checkout's pre-push hook message. */
+    loop: LoopName,
+    /**
+     * The Attempt's access to `repository` (ADR 0011). With `read`, the credential can't push, a
+     * pre-push hook explains rejected pushes, and an unsuccessful Attempt's checkout is removed
+     * without salvage. A Worker kind that can't issue such a credential fails `prepare` with a
+     * `credentials` capability error.
+     */
+    permissions: LoopPermissions,
+    /** The revision to fetch, resolved to a commit during preparation and stored as the RunSpec's `baseCommit`. */
     revision: RepositoryRevision,
+    /** The payload of the event that triggered the Run, included as JSON in the parent's prompt. */
     payload: Schema.Json,
+    /** The parent's task text, after Loop interpolation or operator amendment. */
     task: AttemptTask,
+    /**
+     * The Agent whose persona and name go in the parent's prompt and whose brain runs the
+     * children. Preparation verifies the brain on the Worker.
+     */
     agent: Agent,
+    /**
+     * The Pi parent's model. If `None`, uses the configured default model, then the first model
+     * with a credential. A model unknown to Pi fails the launch.
+     */
     parentModel: Schema.Option(ModelId),
+    /** The maximum child sessions per Attempt. One more fails the Attempt with `ChildSessionBudgetFailure`. */
     maxChildren: ChildSessionBudget,
-    /** Maximum minutes of live run-host execution; preparation and resource cleanup are outside this budget. */
-    maxAttemptMinutes: Schema.Int.check(Schema.isGreaterThan(0)),
-    /** Maximum reported tokens across the parent and every child; operator Holds never pause this ceiling. */
-    maxAttemptTokens: Schema.Int.check(Schema.isGreaterThan(0)),
+    /** The maximum minutes of Attempt execution, excluding preparation and cleanup, or `None` for no limit. */
+    maxAttemptMinutes: Schema.Option(Schema.Int.check(Schema.isGreaterThan(0))),
+    /** The maximum tokens consumed by the parent and all children, or `None` for no limit. Holds don't pause it. */
+    maxAttemptTokens: Schema.Option(Schema.Int.check(Schema.isGreaterThan(0))),
+    /** The Pi parent's reasoning effort. The launch fails if the model doesn't support it. */
     parentEffort: Effort,
+    /** The ref that unfinished work is pushed to if the Attempt doesn't succeed. */
+    salvageRef: SalvageRef,
+    /** The previous Attempt's pushed salvage, checked out instead of `revision`. */
+    resume: Schema.Option(SalvagePushed),
+    /**
+     * Whether the parent task is still live after an orchestrator restart. If true, preparation
+     * reuses the existing checkout and launch reattaches to the parent.
+     */
+    reattach: Schema.Boolean.pipe(Schema.withConstructorDefault(Effect.succeed(false))),
+    /**
+     * The GitHub login the Attempt writes as, copied into the RunSpec; harvesting collects comments
+     * by this author. If `None`, harvesting asks GitHub for the credential's login.
+     */
+    botLogin: Schema.Option(BotLogin).pipe(Schema.withConstructorDefault(Effect.succeed(Option.none()))),
+    /**
+     * The author and committer of every commit that the Attempt's parent and children make. Their
+     * environment sets it, so no git config on the Worker's machine applies.
+     */
+    commitAuthor: BotAccount,
 }) {
 }
-/** One Attempt's disposable checkout directory. */
 export const WorktreePath = Schema.NonEmptyString.pipe(Schema.brand("WorktreePath"));
-/** The serializable location and RunSpec of an Attempt checkout. Owning this record does not grant access to live resources or credentials. */
+/** A serializable checkout location and RunSpec, without credentials or live resources. */
 export class AttemptWorkspace extends Schema.Class("@usine/executor/AttemptWorkspace")({
     worker: WorkerName,
+    /** The request's fields plus the commit that `revision` resolved to. */
     spec: AttemptChannel.RunSpec,
+    /** The checkout path on the Worker's machine, where the children run. */
     worktree: WorktreePath,
 }) {
 }
-/** Mints exactly one repository-scoped credential for each prepared Attempt. */
+/**
+ * A `Redacted` string, kept as the instance it was given, so wiping it wipes the token the
+ * provider issued. `Schema.Redacted` stores a copy instead.
+ */
+const IssuedToken = Schema.declare((input) => Redacted.isRedacted(input) && Predicate.isString(Redacted.value(input)), { expected: "Redacted<string>" });
+export class WorkerCredential extends Schema.Class("@usine/executor/WorkerCredential")({
+    /**
+     * The token for git and gh, never written inside the checkout. Wiped when the Attempt's scope
+     * closes; `Redacted.value` then throws.
+     */
+    value: IssuedToken,
+    /** A new credential is requested when five minutes or less remain. */
+    expiresAt: Schema.DateTimeUtc,
+}) {
+}
 export class CredentialProvider extends Context.Service()("@usine/executor/CredentialProvider") {
 }
-/** Prepares isolated checkouts, runs Attempts on a Worker, and releases their resources (ADR 0006). */
+/** The service that prepares checkouts, runs Attempts on a Worker, and releases their resources (ADR 0006). */
 export class Executor extends Context.Service()("@usine/executor/Executor") {
 }
+/** The executor's hold on one provisioned machine, which `WorkerMachines.release` ends. */
+export const MachineHold = Schema.NonEmptyString.pipe(Schema.brand("MachineHold"));
+/** The machine preflight of a provisioned Worker's first machine each day. */
+export class MachineCheck extends Schema.Class("@usine/executor/MachineCheck")({
+    brains: Schema.Array(BrainSpec),
+    /**
+     * The limits of each Attempt container that the Worker's machines get until the next check,
+     * or `None` if the machine has no Docker.
+     */
+    containerLimits: Schema.Option(ContainerLimits),
+}) {
+}
+/** A machine that a provisioned Worker created for an Attempt and holds until `release`. */
+export class MachineGrant extends Schema.Class("@usine/executor/MachineGrant")({
+    hold: MachineHold,
+    id: MachineId,
+    worker: WorkerName,
+    provider: MachineProvider,
+    /** The check that this machine got as the Worker's first each day, or `None` if it got none. */
+    checked: Schema.Option(MachineCheck),
+}) {
+}
+/**
+ * `creating` until the machine answers over SSH, `ready` while an Attempt holds it, and
+ * `deleting` until its deletion succeeds.
+ */
+export const MachineState = Schema.Literals(["creating", "ready", "deleting"]);
+/** A machine in flight on a provisioned Worker. */
+export class MachineStatus extends Schema.Class("@usine/executor/MachineStatus")({
+    worker: WorkerName,
+    provider: MachineProvider,
+    state: MachineState,
+    /** `None` until the provider accepts the creation. */
+    id: Schema.Option(MachineId),
+    /** The Run the machine was created for, or `None` for a machine found after a restart. */
+    runId: Schema.Option(RunId),
+    attemptId: Schema.Option(AttemptId),
+    /** When the creation started, or when the provider created a machine found after a restart. */
+    since: Schema.DateTimeUtc,
+}) {
+}
+/**
+ * The machines of the provisioned Workers, which create one machine per Attempt and delete it
+ * afterwards (#550). Only the SSH executor provides it.
+ */
+export class WorkerMachines extends Context.Service()("@usine/executor/WorkerMachines") {
+}
+export { claudeLoginLockLayer } from "./claude-login-lock.js";
 //# sourceMappingURL=executor.js.map

package/dist/executor.js.map

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

package/dist/guard.d.ts

@@ -1,11 +1,61 @@
 import type { AttemptId } from "@usine/core/attempt";
+import type { AgentSessionId } from "@usine/core/agent/session";
 import type * as AttemptChannel from "@usine/core/attempt/channel";
-import { AttemptFailure } from "@usine/core/attempt/failure";
-import { Effect } from "effect";
-/** Enforces Attempt ceilings: Holds pause elapsed execution time; reported tokens continue accumulating. */
-export declare const withAttemptGuard: <A>(limits: {
+import { AttemptFailure, RunawayCeiling, RunawayFailure } from "@usine/core/attempt/failure";
+import { Duration, Effect, Option } from "effect";
+export interface AttemptGuardLimits {
     readonly attemptId: AttemptId;
-    readonly maxAttemptMinutes: number;
-    readonly maxAttemptTokens: number;
-}, io: AttemptChannel.Sink, run: (sink: AttemptChannel.Sink) => Effect.Effect<A, AttemptFailure>) => Effect.Effect<A, AttemptFailure>;
+    /** The wall-clock ceiling in minutes, or `None` for no limit. */
+    readonly maxAttemptMinutes: Option.Option<number>;
+    /** The token ceiling across the parent and all children, or `None` for no limit. */
+    readonly maxAttemptTokens: Option.Option<number>;
+    /**
+     * Sends the warning steer to the parent session. Can wait for the parent's channel without
+     * delaying the ceiling checks; failures are logged and don't fail the Attempt.
+     */
+    readonly warn: (message: string) => Effect.Effect<void, AttemptFailure>;
+    /**
+     * Persists the unsupervised time counted so far, including the seed, for a later reattachment.
+     * Called every `RECORD_INTERVAL` while the count grows and once on stop; failures are logged.
+     */
+    readonly recordUnsupervised: (unsupervised: Duration.Duration) => Effect.Effect<void, AttemptFailure>;
+}
+/**
+ * The counts restored from earlier guards, so a reattached Attempt's guard continues instead of
+ * starting over (#178). Empty for a new Attempt.
+ */
+export interface AttemptGuardSeed {
+    /** The highest token count each session reported, including sessions that finished before the restart. */
+    readonly tokens: ReadonlyMap<AgentSessionId, number>;
+    /** The unsupervised time recorded by earlier guards, excluding time the orchestrator was stopped. */
+    readonly unsupervised: Duration.Duration;
+    /** Whether the parent was on Hold at the restart. A parent's Hold persists across restarts; a child's doesn't. */
+    readonly parentHeld: boolean;
+    /** The ceilings whose warning steer is already in the transcript. */
+    readonly warned: ReadonlySet<RunawayCeiling>;
+}
+/** Returns a reattached guard's seed from `unsupervised` and the transcript `envelopes` in append order. */
+export declare const guardSeed: (transcript: ReadonlyArray<AttemptChannel.Envelope>, unsupervised: Duration.Duration) => AttemptGuardSeed;
+export interface AttemptGuard {
+    /**
+     * The Attempt's sink, wrapped. The append that reaches the token ceiling fails with
+     * `RunawayFailure`. An append that reaches the warning point queues the warning for `tripped`
+     * without waiting, because awaiting delivery inside `append` would deadlock.
+     */
+    readonly sink: AttemptChannel.Sink;
+    /**
+     * Checks the restored token total, counts unsupervised time, and sends queued warnings through
+     * `limits.warn`. Fails with `RunawayFailure` when the restored token total or the wall-clock
+     * ceiling trips; never succeeds. On interruption, records the counted time within
+     * `LAST_RECORD_GRACE`.
+     */
+    readonly tripped: Effect.Effect<never, RunawayFailure>;
+}
+/**
+ * Arms the configured Attempt ceilings, each with one warning steer at `WARNING_FRACTION` of
+ * its limit. Holds pause the wall clock; tokens keep accumulating. Counts continue from `seed`,
+ * so a reattached Attempt trips at the same totals as without the restart. With no ceiling set,
+ * `sink` is `io` and `tripped` never completes.
+ */
+export declare const attemptGuard: (limits: AttemptGuardLimits, io: AttemptChannel.Sink, seed: AttemptGuardSeed) => Effect.Effect<AttemptGuard>;
 //# sourceMappingURL=guard.d.ts.map

package/dist/guard.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"guard.d.ts","sourceRoot":"","sources":["../src/guard.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AAErD,OAAO,KAAK,KAAK,cAAc,MAAM,6BAA6B,CAAC;AACnE,OAAO,EAAE,cAAc,EAAkB,MAAM,6BAA6B,CAAC;AAC7E,OAAO,EAAS,MAAM,EAAiB,MAAM,QAAQ,CAAC;AAEtD,4GAA4G;AAC5G,eAAO,MAAM,gBAAgB,GAAI,CAAC,UACxB;IACN,QAAQ,CAAC,SAAS,EAAE,SAAS,CAAC;IAC9B,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAC;IACnC,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;CACnC,MACG,cAAc,CAAC,IAAI,OAClB,CAAC,IAAI,EAAE,cAAc,CAAC,IAAI,KAAK,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,cAAc,CAAC,KACnE,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,cAAc,CAwE9B,CAAC"}
+{"version":3,"file":"guard.d.ts","sourceRoot":"","sources":["../src/guard.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AACrD,OAAO,KAAK,EAAgB,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAC9E,OAAO,KAAK,KAAK,cAAc,MAAM,6BAA6B,CAAC;AACnE,OAAO,EAAE,cAAc,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,6BAA6B,CAAC;AAC7F,OAAO,EAAS,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAS,MAAM,QAAQ,CAAC;AAyBhE,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,SAAS,EAAE,SAAS,CAAC;IAC9B,iEAAiE;IACjE,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;IAClD,oFAAoF;IACpF,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;IACjD;;;OAGG;IACH,QAAQ,CAAC,IAAI,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,cAAc,CAAC,CAAC;IACxE;;;OAGG;IACH,QAAQ,CAAC,kBAAkB,EAAE,CAC3B,YAAY,EAAE,QAAQ,CAAC,QAAQ,KAC5B,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,cAAc,CAAC,CAAC;CAC1C;AAED;;;GAGG;AACH,MAAM,WAAW,gBAAgB;IAC/B,0GAA0G;IAC1G,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC,cAAc,EAAE,MAAM,CAAC,CAAC;IACrD,qGAAqG;IACrG,QAAQ,CAAC,YAAY,EAAE,QAAQ,CAAC,QAAQ,CAAC;IACzC,kHAAkH;IAClH,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAC;IAC7B,qEAAqE;IACrE,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC,cAAc,CAAC,CAAC;CAC9C;AA8ED,4GAA4G;AAC5G,eAAO,MAAM,SAAS,eACR,aAAa,CAAC,cAAc,CAAC,QAAQ,CAAC,gBACpC,QAAQ,CAAC,QAAQ,KAC9B,gBAYF,CAAC;AAsLF,MAAM,WAAW,YAAY;IAC3B;;;;OAIG;IACH,QAAQ,CAAC,IAAI,EAAE,cAAc,CAAC,IAAI,CAAC;IACnC;;;;;OAKG;IACH,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,CAAC,KAAK,EAAE,cAAc,CAAC,CAAC;CACxD;AAED;;;;;GAKG;AACH,eAAO,MAAM,YAAY,WACf,kBAAkB,MACtB,cAAc,CAAC,IAAI,QACjB,gBAAgB,KACrB,MAAM,CAAC,MAAM,CAAC,YAAY,CA6E5B,CAAC"}