@hasna/loops 0.3.60 → 0.4.0

package/dist/lib/route/throttle.d.ts

@@ -0,0 +1,47 @@
+import type { Store } from "../store.js";
+/** Active-workflow admission throttles and canonical project-path handling. */
+export interface RouteThrottleLimits {
+    maxActive?: number;
+    maxActivePerProject?: number;
+    maxActivePerProjectGroup?: number;
+}
+export interface RouteThrottleDecision {
+    allowed: boolean;
+    reason?: string;
+    projectPath: string;
+    projectGroup?: string;
+    limits: RouteThrottleLimits;
+    counts: {
+        global: number;
+        project: number;
+        projectGroup?: number;
+    };
+}
+export declare function routeThrottleLimitsFromOpts(opts: {
+    maxActive?: string;
+    maxActivePerProject?: string;
+    maxActivePerProjectGroup?: string;
+}): RouteThrottleLimits;
+export declare function hasThrottleLimits(limits: RouteThrottleLimits): boolean;
+export declare function normalizeRoutePath(value: string | undefined): string | undefined;
+export declare function routeProjectGroup(optsGroup: string | undefined, data: Record<string, unknown>, metadata: Record<string, unknown>): string | undefined;
+export declare function routeThrottleDecision(store: Store, args: {
+    projectPath: string;
+    projectGroup?: string;
+    limits: RouteThrottleLimits;
+}): RouteThrottleDecision;
+export declare function routeThrottleDryRunPreview(args: {
+    projectPath: string;
+    projectGroup?: string;
+    limits: RouteThrottleLimits;
+}): {
+    limits: RouteThrottleLimits;
+    projectGroup?: string | undefined;
+    evaluated: boolean;
+    reason: string;
+    projectPath: string;
+};
+export declare function isExistingGitProjectPath(path: string): boolean;
+export declare function validateRequiredRouteWorktreeProjectPath(opts: {
+    worktreeMode?: string;
+}, projectPath: string): void;

package/dist/lib/route/todos-cli.d.ts

@@ -0,0 +1,21 @@
+/** Local `todos` CLI transport used by route drains and route-tasks commands. */
+export declare function defaultLoopsProject(): string;
+export interface LocalCommandResult {
+    ok: boolean;
+    status: number | null;
+    stdout: string;
+    stderr: string;
+    error: string;
+}
+export declare function runLocalCommand(command: string, args: string[], opts?: {
+    input?: string;
+    timeoutMs?: number;
+    maxBuffer?: number;
+}): LocalCommandResult;
+export declare function runLocalCommandWithStdoutFile(command: string, args: string[], opts?: {
+    input?: string;
+    timeoutMs?: number;
+    maxBuffer?: number;
+}): LocalCommandResult;
+export declare function ensureTodosTaskList(project: string, slug: string, name: string, description: string): string;
+export declare function todosMutationSummary(result: LocalCommandResult): Record<string, unknown>;

package/dist/lib/route/types.d.ts

@@ -0,0 +1,88 @@
+/** Typed option bags shared by the route engine, drain engine, and CLI commands. */
+export interface TodosTaskRouteOptions {
+    eventFile?: string;
+    eventJson?: string;
+    template?: string;
+    provider?: string;
+    providerRule?: string[];
+    authProfile?: string;
+    authProfilePool?: string;
+    triageAuthProfile?: string;
+    plannerAuthProfile?: string;
+    workerAuthProfile?: string;
+    verifierAuthProfile?: string;
+    account?: string;
+    accountPool?: string;
+    triageAccount?: string;
+    plannerAccount?: string;
+    workerAccount?: string;
+    verifierAccount?: string;
+    accountTool?: string;
+    model?: string;
+    variant?: string;
+    agent?: string;
+    addDir?: string[];
+    timeout?: string;
+    verifierIdleTimeout?: string;
+    permissionMode?: string;
+    sandbox?: string;
+    manualBreakGlass?: boolean;
+    projectPath?: string;
+    projectGroup?: string;
+    maxActive?: string;
+    maxActivePerProject?: string;
+    maxActivePerProjectGroup?: string;
+    worktreeMode?: string;
+    worktreeRoot?: string;
+    worktreeBranchPrefix?: string;
+    prHandoff?: boolean;
+    githubReviewer?: string;
+    githubReviewerPool?: string;
+    namePrefix?: string;
+    preflight?: boolean;
+    dryRun?: boolean;
+    todosProject?: string;
+}
+export interface TodosReadyTask {
+    id?: string;
+    task_id?: string;
+    taskId?: string;
+    title?: string;
+    description?: string;
+    body?: string;
+    status?: string;
+    working_dir?: string;
+    workingDir?: string;
+    project_path?: string;
+    projectPath?: string;
+    cwd?: string;
+    tags?: string[] | string;
+    metadata?: Record<string, unknown>;
+    project_id?: string;
+    projectId?: string;
+    task_list_id?: string;
+    taskListId?: string;
+    task_list?: {
+        id?: string;
+        slug?: string;
+    };
+    [key: string]: unknown;
+}
+export interface TodosDrainOptions extends TodosTaskRouteOptions {
+    todosProject?: string;
+    todosProjectId?: string;
+    taskList?: string;
+    tags?: string;
+    tag?: string;
+    projectPathPrefix?: string;
+    limit?: string;
+    scanLimit?: string;
+    maxDispatch?: string;
+    evidenceDir?: string;
+    compact?: boolean;
+}
+export interface TodosTaskRoutePrint {
+    kind: "skipped" | "deduped" | "throttled" | "created";
+    value: Record<string, unknown>;
+    human: string;
+}

package/dist/lib/run-artifacts.d.ts

@@ -1,7 +1,7 @@
 export declare function safeRunPathSlug(value: string | undefined, fallback: string): string;
 export declare function workflowRunSubjectKey(kind: string | undefined, rawSubjectRef: string | undefined): string;
 export declare function workflowRunProjectSlug(projectKey: string | undefined): string;
-export declare function writeWorkflowRunManifest(args: {
+export interface WorkflowRunManifestArgs {
     loopsDataDir: string;
     workflowRunId: string;
     workflowId: string;
@@ -12,4 +12,19 @@ export declare function writeWorkflowRunManifest(args: {
     subjectKind?: string;
     rawSubjectRef?: string;
     payload: Record<string, unknown>;
-}): string;
+}
+export interface StagedWorkflowRunManifest {
+    /** Final manifest.json location, valid only after {@link commitWorkflowRunManifest}. */
+    manifestPath: string;
+    /** Temp file holding the staged manifest content. */
+    tmpPath: string;
+}
+/**
+ * Write the manifest to `manifest.json.tmp` so callers can stage the
+ * filesystem side effect before opening a database transaction and promote it
+ * with {@link commitWorkflowRunManifest} only after COMMIT succeeds.
+ */
+export declare function stageWorkflowRunManifest(args: WorkflowRunManifestArgs): StagedWorkflowRunManifest;
+export declare function commitWorkflowRunManifest(staged: StagedWorkflowRunManifest): string;
+export declare function discardWorkflowRunManifest(staged: StagedWorkflowRunManifest): void;
+export declare function writeWorkflowRunManifest(args: WorkflowRunManifestArgs): string;

package/dist/lib/run-envelope.d.ts

@@ -0,0 +1,41 @@
+import type { ExecutorResult, WorkflowRun, WorkflowStepRun, WorkflowStepRunStatus } from "../types.js";
+/** Maximum characters kept from each end of a child output when building parent envelopes. */
+export declare const ENVELOPE_EXCERPT_CHARS = 2048;
+/** Stable marker prefix recorded on skipped step runs that were blocked by policy exit codes. */
+export declare const BLOCKED_STEP_ERROR_PREFIX = "blocked:";
+/**
+ * Excerpts scrub BEFORE truncating: cutting raw output at fixed character
+ * boundaries can bisect a credential (e.g. an `sk-ant-…` key whose prefix
+ * falls in the omitted middle), leaving a fragment no scrub pattern matches.
+ * scrubSecrets is idempotent, so store-time re-scrubbing stays safe.
+ */
+export declare function boundedExcerpt(text: string | undefined, limit?: number): string | undefined;
+export interface OutputSummary {
+    stdoutBytes: number;
+    stderrBytes: number;
+    stdoutExcerpt?: string;
+    stderrExcerpt?: string;
+}
+export declare function summarizeOutput(stdout: string | undefined, stderr: string | undefined): OutputSummary;
+export interface ExecutorResultSummary extends OutputSummary {
+    status: ExecutorResult["status"];
+    exitCode?: number;
+    durationMs: number;
+    error?: string;
+}
+export declare function summarizeExecutorResult(result: Pick<ExecutorResult, "status" | "exitCode" | "durationMs" | "stdout" | "stderr" | "error">): ExecutorResultSummary;
+export interface WorkflowStepRunSummary extends OutputSummary {
+    stepId: string;
+    status: WorkflowStepRunStatus;
+    exitCode?: number;
+    durationMs?: number;
+    error?: string;
+    blocked: boolean;
+}
+export declare function isBlockedStepRun(step: Pick<WorkflowStepRun, "status" | "error"> | undefined): boolean;
+export declare function summarizeWorkflowStepRun(step: WorkflowStepRun): WorkflowStepRunSummary;
+/**
+ * Parent-run result envelope: per-step summaries only. Full child output stays on the
+ * workflow step run rows; duplicating it here bloated the database and propagated secrets.
+ */
+export declare function workflowRunEnvelope(run: WorkflowRun, steps: WorkflowStepRun[]): string;

package/dist/lib/scheduler.d.ts

@@ -10,6 +10,10 @@ export interface SchedulerDeps {
     execute?: (loop: Loop, run: LoopRun) => Promise<ExecutorResult>;
     onError?: (loop: Loop, error: unknown) => void;
     onRun?: (run: LoopRun) => void;
+    /** randomness source for retry jitter; injectable for deterministic tests */
+    random?: () => number;
+    /** consecutive-final-failure count that trips the circuit breaker; number, per-loop resolver, or <= 0 to disable */
+    circuitBreakerThreshold?: number | ((loop: Loop) => number | undefined);
 }
 export interface TickResult {
     claimed: LoopRun[];
@@ -29,9 +33,81 @@ export declare function manualRunScheduledFor(loop: Loop, now?: Date): string;
 export declare function shouldAdvanceManualRun(loop: Loop, scheduledFor: string, now?: Date): boolean;
 export type ManualRunSource = "ad_hoc" | "due_slot" | "retry_slot";
 export declare function manualRunSource(loop: Loop, scheduledFor: string, now?: Date): ManualRunSource;
-export declare function advanceLoop(store: Store, loop: Loop, run: LoopRun, finishedAt: Date, succeeded: boolean, opts?: {
+/**
+ * Inline (non-daemon) runners claim runs as `<surface>:<pid>`: `manual:<pid>`
+ * (CLI run-now), `manual-tick:<pid>` (CLI tick), `sdk:<pid>` (LoopsClient
+ * default), and caller-supplied SDK runner ids following the same convention.
+ * The daemon claims as `${hostname}:${pid}:${leaseId}` (three segments) and
+ * MCP run-now uses schedule mode, so neither ever matches. Centralized here so
+ * the daemon's "spare runs owned by a live inline runner" check cannot drift
+ * from the surfaces that share runLoopNow/executeClaimedRun semantics.
+ */
+export declare const INLINE_RUNNER_ID_PATTERN: RegExp;
+/** Owner pid of an inline runner claim, or undefined for daemon/unknown claims. */
+export declare function inlineRunnerOwnerPid(claimedBy: string | undefined): number | undefined;
+export type RunLoopNowMode = "inline" | "schedule";
+export interface RunLoopNowDeps {
+    store: Store;
+    /** loop id or exact loop name */
+    idOrName: string;
+    runnerId: string;
+    /**
+     * "inline" claims and executes the run in this process (CLI/SDK semantics);
+     * "schedule" only marks the loop due now for daemon pickup (MCP semantics).
+     */
+    mode?: RunLoopNowMode;
+    now?: () => Date;
+    execute?: (loop: Loop, run: LoopRun) => Promise<ExecutorResult>;
+}
+export interface RunLoopNowScheduled {
+    mode: "schedule";
+    loop: Loop;
+    scheduledFor: string;
+}
+export interface RunLoopNowExecuted {
+    mode: "inline";
+    loop: Loop;
+    run: LoopRun;
+    source: ManualRunSource;
+    advancedLoop: boolean;
+}
+export type RunLoopNowResult = RunLoopNowScheduled | RunLoopNowExecuted;
+export declare function runLoopNow(deps: RunLoopNowDeps & {
+    mode: "schedule";
+}): Promise<RunLoopNowScheduled>;
+export declare function runLoopNow(deps: RunLoopNowDeps & {
+    mode?: "inline";
+}): Promise<RunLoopNowExecuted>;
+export declare const MAX_RETRY_DELAY_MS: number;
+export declare const DEFAULT_CIRCUIT_BREAKER_THRESHOLD = 5;
+export declare const CIRCUIT_BREAKER_REASON_PREFIX = "circuit breaker open";
+export declare const MAX_SKIPS_PER_LOOP_PER_TICK = 10;
+/**
+ * Exponential retry backoff with jitter:
+ * delay = retryDelayMs * 2^(attempt-1) * (0.5 + random), capped at 6h.
+ * Failures classified as rate_limit/auth back off 4x harder, since hammering
+ * a throttled or misconfigured provider only makes things worse.
+ */
+export declare function retryBackoffDelayMs(loop: Loop, run: LoopRun, random?: () => number): number;
+export interface AdvanceLoopOptions {
     daemonLeaseId?: string;
-}): void;
+    random?: () => number;
+    circuitBreakerThreshold?: number | ((loop: Loop) => number | undefined);
+    onRun?: (run: LoopRun) => void;
+}
+/**
+ * Count consecutive final failures (failed/timed_out/abandoned) in recent run
+ * history. Skipped bookkeeping runs and in-flight runs are neutral; a success
+ * resets the streak. Failed runs with attempts remaining (attempt <
+ * maxAttempts) are pending retries by the scheduler's own semantics, so they
+ * are neutral too — only exhausted slots count as final failures. A previous
+ * circuit-breaker marker acts as a watermark (compared via scheduledFor, which
+ * shares the scheduler clock with run slots, unlike the marker's wall-clock
+ * createdAt): only failures after it count, so a manual resume requires a
+ * fresh streak before the breaker can trip again.
+ */
+export declare function consecutiveFailureCount(store: Store, loopId: string, maxAttempts?: number, scanLimit?: number): number;
+export declare function advanceLoop(store: Store, loop: Loop, run: LoopRun, finishedAt: Date, succeeded: boolean, opts?: AdvanceLoopOptions): void;
 export declare function executeClaimedRun(deps: {
     store: Store;
     runnerId: string;

package/dist/lib/store.d.ts

@@ -46,6 +46,35 @@ export interface CreateGoalPlanNodeInput {
     priority?: number;
     tokenBudget?: number;
 }
+export interface RecordRunProcessInput {
+    pid: number;
+    pgid?: number;
+    processStartedAt?: string;
+}
+export interface RecoverExpiredRunLeasesResult {
+    /** Runs whose lease expired with no live process; marked abandoned. */
+    abandoned: LoopRun[];
+    /** Runs whose lease expired while their process (group) is still alive; lease deferred. */
+    deferred: LoopRun[];
+}
+export interface PruneHistoryOptions {
+    /** Delete terminal runs whose created_at is older than this many days. */
+    maxAgeDays?: number;
+    /** Always retain at least this many of the most recent runs per loop. */
+    keepPerLoop?: number;
+    /** Report what would be deleted without deleting anything. */
+    dryRun?: boolean;
+    /** Injectable clock for tests. */
+    now?: Date;
+}
+export interface PruneHistorySummary {
+    dryRun: boolean;
+    cutoff?: string;
+    keepPerLoop?: number;
+    loopRuns: number;
+    workflowRuns: number;
+    goalRuns: number;
+}
 export interface RecordGoalEventInput {
     goalId: string;
     turn?: number;
@@ -61,6 +90,8 @@ export declare class Store {
     private rootDir;
     constructor(path?: string);
     private migrate;
+    private migrations;
+    private createBaseSchema;
     /**
      * Add a column only if it does not already exist. Idempotent — avoids the
      * "duplicate column name" error that SQLite logs (via libsqlite3, before any
@@ -70,6 +101,8 @@ export declare class Store {
      */
     private addColumnIfMissing;
     private createWorkflowRunBackfillIndexes;
+    /** Run `fn` inside a write transaction unless the caller already opened one. */
+    private transact;
     private assertDaemonLeaseFence;
     private assertNoNestedWorkflowGoal;
     createLoop(input: CreateLoopInput, from?: Date): Loop;
@@ -179,6 +212,13 @@ export declare class Store {
         limit?: number;
     }): Goal[];
     createGoalPlanNodes(goalId: string, nodes: CreateGoalPlanNodeInput[], opts?: DaemonLeaseFence): GoalPlanNode[];
+    /**
+     * Insert a plan node, detecting (rather than silently ignoring) conflicts:
+     * an existing (plan_id, key) row means the node is already planned and is
+     * kept; a primary-key collision retries with a fresh id instead of dropping
+     * the node on the floor.
+     */
+    private insertGoalPlanNode;
     listGoalPlanNodes(goalIdOrPlanId: string): GoalPlanNode[];
     updateGoalStatus(goalId: string, status: GoalStatus, opts?: DaemonLeaseFence): Goal;
     addGoalUsage(goalId: string, tokens: number, timeUsedSeconds?: number, opts?: DaemonLeaseFence): Goal;
@@ -215,6 +255,11 @@ export declare class Store {
     hasRunningRun(loopId: string): boolean;
     hasRunningRunForSlot(loopId: string, scheduledFor: string): boolean;
     markRunPid(id: string, pid: number, claimedBy?: string, opts?: DaemonLeaseFence): LoopRun | undefined;
+    /**
+     * Record the spawned child's process identity (pid, process group id, start
+     * time) so recovery can signal the whole process group later.
+     */
+    recordRunProcess(runId: string, info: RecordRunProcessInput, opts?: DaemonLeaseFence): LoopRun | undefined;
     private hasLiveWorkflowStepProcesses;
     createSkippedRun(loop: Loop, scheduledFor: string, reason: string, opts?: DaemonLeaseFence): LoopRun;
     getRun(id: string): LoopRun | undefined;
@@ -237,12 +282,30 @@ export declare class Store {
         limit?: number;
         scanLimit?: number;
     }): LoopRun[];
+    /**
+     * Recover expired run leases and report both outcomes: runs abandoned (no
+     * live process) and runs deferred because their process (group) is still
+     * alive. Entries carry pid/pgid/processStartedAt so the daemon can signal
+     * orphaned process groups (SIGTERM then SIGKILL) after recovery.
+     */
+    recoverExpiredRunLeasesDetailed(now?: Date, opts?: DaemonLeaseFence & {
+        limit?: number;
+        scanLimit?: number;
+    }): RecoverExpiredRunLeasesResult;
     expireLoops(now?: Date, opts?: DaemonLeaseFence): Loop[];
     countLoops(status?: LoopStatus, opts?: {
         archived?: boolean;
         includeArchived?: boolean;
     }): number;
     countRuns(status?: RunStatus): number;
+    /**
+     * Delete old terminal run history: loop runs plus their attached workflow
+     * runs (step runs and events cascade), goal run events, and per-run manifest
+     * directories. At least one of maxAgeDays / keepPerLoop must be provided;
+     * when both are given a run is only deleted when it is older than the cutoff
+     * AND beyond the per-loop retention floor. Running runs are never touched.
+     */
+    pruneHistory(opts: PruneHistoryOptions): PruneHistorySummary;
     acquireDaemonLease(input: {
         id: string;
         pid: number;