@llm4ts/flow 2.7.2 → 2.9.0

package/dist/Roster.d.ts

@@ -0,0 +1,163 @@
+import * as Duration from "effect/Duration";
+import * as Effect from "effect/Effect";
+import * as Schema from "effect/Schema";
+import type * as Scope from "effect/Scope";
+import type { LlmError } from "@llm4ts/core/Errors";
+import { RosterExhausted, type FlowError } from "./FlowError.ts";
+import { type FlowEventsShape } from "./FlowEvents.ts";
+import { type PlainFileStoreShape } from "./Persistence.ts";
+export declare const Role: Schema.Literals<readonly ["planner", "coder", "reviewer", "judge", "verifier"]>;
+export type Role = typeof Role.Type;
+export declare const roles: ReadonlyArray<Role>;
+declare const Cooldown_base: Schema.Class<Cooldown, Schema.Struct<{
+    readonly usageLimit: Schema.optionalKey<Schema.String>;
+    readonly rateLimit: Schema.optionalKey<Schema.String>;
+    readonly outage: Schema.optionalKey<Schema.String>;
+}>, {}>;
+/** How long each exclusion lasts, as duration strings ("30 minutes"). */
+export declare class Cooldown extends Cooldown_base {
+}
+declare const ExecutorSpec_base: Schema.Class<ExecutorSpec, Schema.Struct<{
+    readonly id: Schema.String;
+    /** A CLI harness (`pi`, `claude`, `codex`, `opencode`, …) or an API provider (`lm-studio`, …). */
+    readonly harness: Schema.String;
+    readonly model: Schema.optionalKey<Schema.String>;
+    readonly flags: Schema.optionalKey<Schema.$Record<Schema.String, Schema.String>>;
+    /** Environment for the harness process; secrets only as `${VAR}` references. */
+    readonly env: Schema.optionalKey<Schema.$Record<Schema.String, Schema.String>>;
+    /** Endpoint for an API harness. */
+    readonly baseUrl: Schema.optionalKey<Schema.String>;
+    readonly roles: Schema.$Array<Schema.String>;
+    readonly slots: Schema.optionalKey<Schema.Number>;
+    /** Slots coders may use; default `slots - 1` when the executor also reasons. */
+    readonly coderSlots: Schema.optionalKey<Schema.Number>;
+    /** Lower first. A number for every role, or per role with a `default`. */
+    readonly priority: Schema.optionalKey<Schema.Union<readonly [Schema.Number, Schema.$Record<Schema.String, Schema.Number>]>>;
+    /** A URL that answers 2xx when the executor's serving engine is up. */
+    readonly health: Schema.optionalKey<Schema.String>;
+    readonly cooldown: Schema.optionalKey<typeof Cooldown>;
+    /** In a repository roster: removes the user roster's entry with this id. */
+    readonly disabled: Schema.optionalKey<Schema.Boolean>;
+}>, {}>;
+/** One executor: a harness and a model, the roles it takes, its slots and priorities. */
+export declare class ExecutorSpec extends ExecutorSpec_base {
+}
+declare const RosterDocument_base: Schema.Class<RosterDocument, Schema.Struct<{
+    readonly executors: Schema.$Array<typeof ExecutorSpec>;
+}>, {}>;
+export declare class RosterDocument extends RosterDocument_base {
+}
+export declare const ExclusionKind: Schema.Literals<readonly ["until", "health", "run", "manual"]>;
+export type ExclusionKind = typeof ExclusionKind.Type;
+declare const Exclusion_base: Schema.Class<Exclusion, Schema.Struct<{
+    readonly id: Schema.String;
+    readonly reason: Schema.String;
+    readonly kind: Schema.Literals<readonly ["until", "health", "run", "manual"]>;
+    /** Epoch milliseconds; for `until`, and as the next probe time for `health`. */
+    readonly until: Schema.optionalKey<Schema.Number>;
+}>, {}>;
+/**
+ * Why an executor is out of the pick-up round, and until when: `until` an
+ * instant, `health` its health URL answers, `run` the end of this run,
+ * `manual` an operator's resume.
+ */
+export declare class Exclusion extends Exclusion_base {
+}
+export declare const RosterStateVersion = 1;
+declare const RosterState_base: Schema.Class<RosterState, Schema.Struct<{
+    readonly exclusions: Schema.$Array<typeof Exclusion>;
+}>, {}>;
+export declare class RosterState extends RosterState_base {
+}
+export declare const isRole: (value: string) => value is Role;
+export declare const rolesOf: (spec: ExecutorSpec) => ReadonlyArray<Role>;
+export declare const hasRole: (spec: ExecutorSpec, role: Role) => boolean;
+export declare const slotsOf: (spec: ExecutorSpec) => number;
+/** Slots coders may hold: one stays free for reasoning on an executor that does both. */
+export declare const coderSlotsOf: (spec: ExecutorSpec) => number;
+export declare const priorityOf: (spec: ExecutorSpec, role: Role) => number;
+/** "30 minutes", "90s", "2h" — the cooldown vocabulary of a roster file. */
+export declare const parseDuration: (text: string) => Duration.Duration | undefined;
+export declare const usageLimitCooldown: (spec: ExecutorSpec) => Duration.Duration;
+export declare const rateLimitCooldown: (spec: ExecutorSpec) => Duration.Duration;
+export declare const outageCooldown: (spec: ExecutorSpec) => Duration.Duration;
+/** Rate limits in this window count towards an exclusion. */
+export declare const rateLimitWindow: Duration.Duration;
+/** Rate limits within the window that exclude an executor. */
+export declare const rateLimitsToExclude = 3;
+/** How often a health-excluded executor is probed while someone waits. */
+export declare const healthProbeInterval: Duration.Duration;
+/**
+ * Every violation of a roster document, in one pass: duplicate ids, unknown
+ * or missing roles, impossible slot counts, unparseable cooldowns. Harness
+ * checks need the connector table and live in the runner.
+ */
+export declare const rosterViolations: (document: RosterDocument) => ReadonlyArray<string>;
+/**
+ * A repository roster over the user's: an entry replaces the user entry
+ * with the same id, `disabled: true` removes it, a new id is added.
+ */
+export declare const mergeRosterDocuments: (user: RosterDocument | undefined, repo: RosterDocument | undefined) => RosterDocument;
+/** Only the named executors (`--executors a,b`); an empty list keeps all. */
+export declare const narrowRoster: (document: RosterDocument, ids: ReadonlyArray<string>) => RosterDocument;
+/**
+ * The exclusion a failure earns, or none. `recentRateLimits` holds the
+ * executor's rate-limit instants inside the window, this one included.
+ */
+export declare const exclusionFor: (error: LlmError, spec: ExecutorSpec, now: number, recentRateLimits: number) => Exclusion | undefined;
+export declare const describeExclusion: (exclusion: Exclusion) => string;
+export interface RosterStateStoreShape {
+    readonly load: Effect.Effect<ReadonlyArray<Exclusion>, FlowError>;
+    /** Replaces the entries of `ids` with `exclusions`, keeping everyone else's. */
+    readonly save: (ids: ReadonlyArray<string>, exclusions: ReadonlyArray<Exclusion>) => Effect.Effect<void, FlowError>;
+}
+export declare const makeRosterStateStore: (files: PlainFileStoreShape, path: string) => RosterStateStoreShape;
+export interface Lease {
+    readonly executor: ExecutorSpec;
+    readonly role: Role;
+    /** Frees the slot; idempotent, and also run when the lease's scope closes. */
+    readonly release: Effect.Effect<void>;
+}
+export interface LeaseOptions {
+    /** Executors this lease must not use (independence, or a handover away from one). */
+    readonly avoid?: ReadonlyArray<string>;
+    /** Taken first while free: the executor a resumed context held before. */
+    readonly prefer?: string;
+    /** Who is asking, for the events (a story's worktree). */
+    readonly label?: string;
+}
+export interface ExecutorStatus {
+    readonly executor: ExecutorSpec;
+    readonly busy: number;
+    readonly busyCoders: number;
+    readonly exclusion?: Exclusion;
+}
+export interface RosterShape {
+    readonly executors: ReadonlyArray<ExecutorSpec>;
+    /** Waits for a slot; fails `RosterExhausted` when none can ever come. */
+    readonly lease: (role: Role, options?: LeaseOptions) => Effect.Effect<Lease, RosterExhausted, Scope.Scope>;
+    /** A slot now, or `undefined`. */
+    readonly tryLease: (role: Role, options?: LeaseOptions) => Effect.Effect<Lease | undefined, never, Scope.Scope>;
+    /** Whether an executor outside `avoid` has the role and is not out for the run. */
+    readonly canEverServe: (role: Role, avoid?: ReadonlyArray<string>) => Effect.Effect<boolean>;
+    /** Free slots for `role` now, across executors in the round. */
+    readonly available: (role: Role) => Effect.Effect<number>;
+    /** Configured slots for `role`. */
+    readonly slots: (role: Role) => number;
+    /** Classifies a failure of `id`'s call; returns the exclusion it earned, if any. */
+    readonly report: (id: string, error: LlmError) => Effect.Effect<Exclusion | undefined>;
+    readonly exclude: (exclusion: Exclusion) => Effect.Effect<void>;
+    readonly resume: (id: string) => Effect.Effect<void>;
+    readonly snapshot: Effect.Effect<ReadonlyArray<ExecutorStatus>>;
+}
+export interface RosterOptions {
+    readonly executors: ReadonlyArray<ExecutorSpec>;
+    readonly events: FlowEventsShape;
+    /** Exclusions that outlive a run; omit to keep them in memory. */
+    readonly state?: RosterStateStoreShape;
+    /** Answers whether a health URL is up; omit and `health` exclusions wait out the outage cooldown. */
+    readonly probe?: (url: string) => Effect.Effect<boolean>;
+}
+export declare const makeRoster: (options: RosterOptions) => Effect.Effect<RosterShape, import("./FlowError.ts").PersistenceError | import("./FlowError.ts").PlanParseError | import("./FlowError.ts").UnsupportedSchemaVersion | import("./FlowError.ts").WorkspacePathError | import("./FlowError.ts").WorkspaceLimitError | import("./FlowError.ts").WorkspaceIoError | import("./FlowError.ts").FlowAborted | import("./FlowError.ts").ProcessError | import("./FlowError.ts").FlowLlmError | import("./FlowError.ts").FlowCapabilityDenied | import("./FlowError.ts").ColumnNotFound | import("./FlowError.ts").BudgetExceeded | import("./FlowError.ts").StoryPlanInvalid | import("./FlowError.ts").PerimeterViolation | import("./FlowError.ts").MissingDependency | import("./FlowError.ts").MergeConflict | import("./FlowError.ts").EpicCheckoutDirty | import("./FlowError.ts").RosterInvalid | RosterExhausted | import("./FlowError.ts").StoryFailed | import("./FlowError.ts").DecisionsInvalid | import("./FlowError.ts").OpenPointsPending | import("./FlowError.ts").ContractConflict, never>;
+export {};
+//# sourceMappingURL=Roster.d.ts.map

package/dist/Roster.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Roster.d.ts","sourceRoot":"","sources":["../src/Roster.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,QAAQ,MAAM,iBAAiB,CAAA;AAC3C,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AAEvC,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AACvC,OAAO,KAAK,KAAK,KAAK,MAAM,cAAc,CAAA;AAE1C,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAA;AACnD,OAAO,EAAE,eAAe,EAAE,KAAK,SAAS,EAAE,MAAM,gBAAgB,CAAA;AAChE,OAAO,EAAQ,KAAK,eAAe,EAAE,MAAM,iBAAiB,CAAA;AAC5D,OAAO,EAAgC,KAAK,mBAAmB,EAAE,MAAM,kBAAkB,CAAA;AAKzF,eAAO,MAAM,IAAI,iFAAyE,CAAA;AAC1F,MAAM,MAAM,IAAI,GAAG,OAAO,IAAI,CAAC,IAAI,CAAA;AAEnC,eAAO,MAAM,KAAK,EAAE,aAAa,CAAC,IAAI,CAAyD,CAAA;;;;;;AAE/F,yEAAyE;AACzE,qBAAa,QAAS,SAAQ,aAI5B;CAAG;;;IAKH,kGAAkG;;;;IAIlG,gFAAgF;;IAEhF,mCAAmC;;;;IAInC,gFAAgF;;IAEhF,0EAA0E;;IAI1E,uEAAuE;;;IAGvE,4EAA4E;;;AAtB9E,yFAAyF;AACzF,qBAAa,YAAa,SAAQ,iBAuBhC;CAAG;;;;AAEL,qBAAa,cAAe,SAAQ,mBAElC;CAAG;AAEL,eAAO,MAAM,aAAa,gEAAwD,CAAA;AAClF,MAAM,MAAM,aAAa,GAAG,OAAO,aAAa,CAAC,IAAI,CAAA;;;;;IAWnD,gFAAgF;;;AATlF;;;;GAIG;AACH,qBAAa,SAAU,SAAQ,cAM7B;CAAG;AAEL,eAAO,MAAM,kBAAkB,IAAI,CAAA;;;;AAEnC,qBAAa,WAAY,SAAQ,gBAE/B;CAAG;AAML,eAAO,MAAM,MAAM,GAAI,OAAO,MAAM,KAAG,KAAK,IAAI,IAA4C,CAAA;AAE5F,eAAO,MAAM,OAAO,GAAI,MAAM,YAAY,KAAG,aAAa,CAAC,IAAI,CAA8B,CAAA;AAE7F,eAAO,MAAM,OAAO,GAAI,MAAM,YAAY,EAAE,MAAM,IAAI,KAAG,OAAuC,CAAA;AAEhG,eAAO,MAAM,OAAO,GAAI,MAAM,YAAY,KAAG,MAAkD,CAAA;AAE/F,yFAAyF;AACzF,eAAO,MAAM,YAAY,GAAI,MAAM,YAAY,KAAG,MAOjD,CAAA;AAED,eAAO,MAAM,UAAU,GAAI,MAAM,YAAY,EAAE,MAAM,IAAI,KAAG,MAS3D,CAAA;AASD,4EAA4E;AAC5E,eAAO,MAAM,aAAa,GAAI,MAAM,MAAM,KAAG,QAAQ,CAAC,QAAQ,GAAG,SAShE,CAAA;AAKD,eAAO,MAAM,kBAAkB,GAAI,MAAM,YAAY,KAAG,QAAQ,CAAC,QACZ,CAAA;AACrD,eAAO,MAAM,iBAAiB,GAAI,MAAM,YAAY,KAAG,QAAQ,CAAC,QACZ,CAAA;AACpD,eAAO,MAAM,cAAc,GAAI,MAAM,YAAY,KAAG,QAAQ,CAAC,QACb,CAAA;AAEhD,6DAA6D;AAC7D,eAAO,MAAM,eAAe,mBAAuB,CAAA;AACnD,8DAA8D;AAC9D,eAAO,MAAM,mBAAmB,IAAI,CAAA;AACpC,0EAA0E;AAC1E,eAAO,MAAM,mBAAmB,mBAAuB,CAAA;AAEvD;;;;GAIG;AACH,eAAO,MAAM,gBAAgB,GAAI,UAAU,cAAc,KAAG,aAAa,CAAC,MAAM,CAwC/E,CAAA;AAED;;;GAGG;AACH,eAAO,MAAM,oBAAoB,GAC/B,MAAM,cAAc,GAAG,SAAS,EAChC,MAAM,cAAc,GAAG,SAAS,KAC/B,cAWF,CAAA;AAED,6EAA6E;AAC7E,eAAO,MAAM,YAAY,GACvB,UAAU,cAAc,EACxB,KAAK,aAAa,CAAC,MAAM,CAAC,KACzB,cAKK,CAAA;AAIR;;;GAGG;AACH,eAAO,MAAM,YAAY,GACvB,OAAO,QAAQ,EACf,MAAM,YAAY,EAClB,KAAK,MAAM,EACX,kBAAkB,MAAM,KACvB,SAAS,GAAG,SAkDd,CAAA;AAED,eAAO,MAAM,iBAAiB,GAAI,WAAW,SAAS,KAAG,MAWxD,CAAA;AAID,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,CAAC,aAAa,CAAC,SAAS,CAAC,EAAE,SAAS,CAAC,CAAA;IACjE,gFAAgF;IAChF,QAAQ,CAAC,IAAI,EAAE,CACb,GAAG,EAAE,aAAa,CAAC,MAAM,CAAC,EAC1B,UAAU,EAAE,aAAa,CAAC,SAAS,CAAC,KACjC,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,SAAS,CAAC,CAAA;CACpC;AAKD,eAAO,MAAM,oBAAoB,GAC/B,OAAO,mBAAmB,EAC1B,MAAM,MAAM,KACX,qBAyBF,CAAA;AAID,MAAM,WAAW,KAAK;IACpB,QAAQ,CAAC,QAAQ,EAAE,YAAY,CAAA;IAC/B,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAA;IACnB,8EAA8E;IAC9E,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,CAAA;CACtC;AAED,MAAM,WAAW,YAAY;IAC3B,qFAAqF;IACrF,QAAQ,CAAC,KAAK,CAAC,EAAE,aAAa,CAAC,MAAM,CAAC,CAAA;IACtC,0EAA0E;IAC1E,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAA;IACxB,0DAA0D;IAC1D,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CACxB;AAED,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,QAAQ,EAAE,YAAY,CAAA;IAC/B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;IAC3B,QAAQ,CAAC,SAAS,CAAC,EAAE,SAAS,CAAA;CAC/B;AAED,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,SAAS,EAAE,aAAa,CAAC,YAAY,CAAC,CAAA;IAC/C,yEAAyE;IACzE,QAAQ,CAAC,KAAK,EAAE,CACd,IAAI,EAAE,IAAI,EACV,OAAO,CAAC,EAAE,YAAY,KACnB,MAAM,CAAC,MAAM,CAAC,KAAK,EAAE,eAAe,EAAE,KAAK,CAAC,KAAK,CAAC,CAAA;IACvD,kCAAkC;IAClC,QAAQ,CAAC,QAAQ,EAAE,CACjB,IAAI,EAAE,IAAI,EACV,OAAO,CAAC,EAAE,YAAY,KACnB,MAAM,CAAC,MAAM,CAAC,KAAK,GAAG,SAAS,EAAE,KAAK,EAAE,KAAK,CAAC,KAAK,CAAC,CAAA;IACzD,mFAAmF;IACnF,QAAQ,CAAC,YAAY,EAAE,CAAC,IAAI,EAAE,IAAI,EAAE,KAAK,CAAC,EAAE,aAAa,CAAC,MAAM,CAAC,KAAK,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC,CAAA;IAC5F,gEAAgE;IAChE,QAAQ,CAAC,SAAS,EAAE,CAAC,IAAI,EAAE,IAAI,KAAK,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,CAAA;IACzD,mCAAmC;IACnC,QAAQ,CAAC,KAAK,EAAE,CAAC,IAAI,EAAE,IAAI,KAAK,MAAM,CAAA;IACtC,oFAAoF;IACpF,QAAQ,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,QAAQ,KAAK,MAAM,CAAC,MAAM,CAAC,SAAS,GAAG,SAAS,CAAC,CAAA;IACtF,QAAQ,CAAC,OAAO,EAAE,CAAC,SAAS,EAAE,SAAS,KAAK,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,CAAA;IAC/D,QAAQ,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,CAAA;IACpD,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC,MAAM,CAAC,aAAa,CAAC,cAAc,CAAC,CAAC,CAAA;CAChE;AAED,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,SAAS,EAAE,aAAa,CAAC,YAAY,CAAC,CAAA;IAC/C,QAAQ,CAAC,MAAM,EAAE,eAAe,CAAA;IAChC,kEAAkE;IAClE,QAAQ,CAAC,KAAK,CAAC,EAAE,qBAAqB,CAAA;IACtC,qGAAqG;IACrG,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC,CAAA;CACzD;AAOD,eAAO,MAAM,UAAU,ghCAsZrB,CAAA"}