@hasna/loops 0.3.60 → 0.4.0

package/dist/lib/accounts.d.ts

@@ -1,4 +1,9 @@
 import type { AccountRef, AgentProvider } from "../types.js";
 export declare function accountToolForProvider(provider: AgentProvider): string;
 export declare function parseAccountExportLines(output: string): Record<string, string>;
-export declare function resolveAccountEnv(account: AccountRef | undefined, toolHint?: string, env?: NodeJS.ProcessEnv): Record<string, string>;
+export declare function resolveAccountEnv(account: AccountRef | undefined, toolHint?: string, env?: NodeJS.ProcessEnv): Promise<Record<string, string>>;
+/**
+ * Synchronous variant reserved for the synchronous preflight path; execution
+ * paths must use the async resolveAccountEnv so the daemon event loop never blocks.
+ */
+export declare function resolveAccountEnvSync(account: AccountRef | undefined, toolHint?: string, env?: NodeJS.ProcessEnv): Record<string, string>;

package/dist/lib/agent-adapter.d.ts

@@ -0,0 +1,74 @@
+import type { AgentProvider, AgentSandbox, AgentTarget } from "../types.js";
+export type ProviderPromptChannel = "stdin" | "argv";
+export interface ProviderCapabilities {
+    /** Sandbox values the provider CLI accepts; empty when sandboxing is unsupported. */
+    sandbox: readonly AgentSandbox[];
+    /** Whether the provider runs as a durable background agent instead of a one-shot process. */
+    durable: boolean;
+    /** Whether the provider can be dispatched to a remote machine transport. */
+    remote: boolean;
+    /** How the prompt reaches the provider process. */
+    promptChannel: ProviderPromptChannel;
+}
+export interface AgentInvocation {
+    command: string;
+    args: string[];
+    /** Prompt delivered on stdin; unset only for argv-channel providers. */
+    stdin?: string;
+    /** Executables of which at least one must exist besides the command itself. */
+    preflightAnyOf?: string[];
+}
+export interface ProviderAdapter {
+    provider: AgentProvider;
+    capabilities: ProviderCapabilities;
+    validate(target: AgentTarget, label?: string): void;
+    buildInvocation(target: AgentTarget): AgentInvocation;
+}
+export declare const UNSAFE_CODEWITH_DURABLE_EXTRA_ARGS: Set<string>;
+export declare const PROVIDER_ADAPTERS: Record<AgentProvider, ProviderAdapter>;
+export declare const AGENT_PROVIDERS: AgentProvider[];
+export declare function providerAdapter(provider: AgentProvider): ProviderAdapter;
+export interface SpawnCaptureOptions {
+    cwd?: string;
+    env?: NodeJS.ProcessEnv;
+    timeoutMs: number;
+    maxOutputBytes?: number;
+}
+export interface CapturedProcessResult {
+    status: number | null;
+    signal: NodeJS.Signals | null;
+    stdout: string;
+    stderr: string;
+    error?: string;
+    timedOut: boolean;
+}
+export declare function killProcessGroup(pgid: number): void;
+/**
+ * Byte-bounded UTF-8 output accumulator shared by the capture paths
+ * (spawnCapture here, executeTarget/executeRemoteSpec in executor.ts).
+ *
+ * - Callers feed decoded strings (`stream.setEncoding("utf8")` keeps
+ *   multi-byte sequences split across pipe chunks intact); the buffer never
+ *   decodes chunks itself.
+ * - Truncation keeps at most `maxBytes` BYTES of tail, cutting at a UTF-8
+ *   sequence boundary so the retained text never starts mid-character.
+ * - The truncation marker reports the CUMULATIVE dropped byte count.
+ * - The accumulated text is scrubbed BEFORE every cut: truncation can bisect
+ *   a credential so the surviving fragment no longer matches any scrub
+ *   pattern, while scrubbing first turns the intact token into [SCRUBBED]
+ *   and the cut then slices through the marker harmlessly (scrubSecrets is
+ *   idempotent, so store-time re-scrubbing stays safe).
+ */
+export declare class BoundedOutputBuffer {
+    private readonly maxBytes;
+    private text;
+    private truncatedBytes;
+    constructor(maxBytes: number);
+    append(chunk: string): void;
+    value(): string;
+}
+/**
+ * Async replacement for short spawnSync calls: never blocks the event loop and
+ * always enforces an explicit timeout that kills the child's process group.
+ */
+export declare function spawnCapture(command: string, args: string[], opts: SpawnCaptureOptions): Promise<CapturedProcessResult>;

package/dist/lib/backup.d.ts

@@ -0,0 +1,25 @@
+export interface BackupDatabaseOptions {
+    /** Why this backup is being taken (e.g. "pre-migration", "daily"). Debounce and retention are tracked per reason. */
+    reason: string;
+    /** How many backups to retain per reason (newest first). */
+    keep?: number;
+    /** Source database file; defaults to the live store path. Tests must pass a temp path. */
+    dbFile?: string;
+    /** Directory for backup files; defaults to `<db dir>/backups`. */
+    backupsDir?: string;
+    /** Injectable clock for tests. */
+    now?: Date;
+}
+export interface BackupDatabaseResult {
+    /** Absolute path of the backup that was written (absent when skipped). */
+    path?: string;
+    skipped: boolean;
+    skipReason?: string;
+    /** Backups removed by retention pruning. */
+    prunedPaths: string[];
+}
+/**
+ * Snapshot the loops database with `VACUUM INTO`. Per-reason backups are
+ * debounced to at most one per hour and pruned to the `keep` most recent.
+ */
+export declare function backupDatabase(opts: BackupDatabaseOptions): BackupDatabaseResult;

package/dist/lib/errors.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Coded errors thrown by the store and CLI layers. Each class carries a stable
+ * machine-readable `.code` so callers can branch on failure kind without
+ * parsing human-readable messages.
+ */
+export declare class CodedError extends Error {
+    readonly code: string;
+    constructor(code: string, message: string);
+}
+export declare class LoopNotFoundError extends CodedError {
+    constructor(idOrName: string);
+}
+export declare class LoopArchivedError extends CodedError {
+    constructor(idOrName: string);
+}
+export declare class AmbiguousNameError extends CodedError {
+    constructor(name: string);
+}
+export declare class ValidationError extends CodedError {
+    constructor(message: string);
+}

package/dist/lib/executor.d.ts

@@ -1,5 +1,10 @@
 import type { LanguageModel } from "ai";
-import type { ExecutableTarget, ExecutorResult, Loop, LoopMachineRef, LoopRun, PersistGuardOptions } from "../types.js";
+import type { AgentTarget, ExecutableTarget, ExecutorResult, Loop, LoopMachineRef, LoopRun, PersistGuardOptions } from "../types.js";
+export interface SpawnedProcessInfo {
+    pid: number;
+    pgid: number;
+    processStartedAt: string;
+}
 export interface ExecuteOptions extends PersistGuardOptions {
     maxOutputBytes?: number;
     env?: NodeJS.ProcessEnv;
@@ -7,6 +12,8 @@ export interface ExecuteOptions extends PersistGuardOptions {
     log?: (message: string) => void;
     signal?: AbortSignal;
     onSpawn?: (pid: number) => void;
+    /** Children are spawned detached in their own process group, so pgid === pid. */
+    onSpawnProcess?: (info: SpawnedProcessInfo) => void;
     machine?: LoopMachineRef;
     machineResolver?: (machine: LoopMachineRef) => LoopMachineRef;
     machineCommandResolver?: (machineId: string, command: string) => MachineCommandPlan;
@@ -34,6 +41,8 @@ interface MachineCommandPlan {
     args: string[];
     source: string;
 }
+/** Exported for tests: resolves the default idle watchdog for agent targets. */
+export declare function defaultAgentIdleTimeoutMs(target: AgentTarget, opts: ExecuteOptions): number | undefined;
 export declare function preflightTarget(target: ExecutableTarget, metadata?: ExecutionMetadata, opts?: ExecuteOptions): PreflightResult;
 export declare function executeTarget(target: ExecutableTarget, metadata?: ExecutionMetadata, opts?: ExecuteOptions): Promise<ExecutorResult>;
 export declare function executeLoop(loop: Loop, run: LoopRun, opts?: ExecuteOptions): Promise<ExecutorResult>;

package/dist/lib/goal/metadata.d.ts

@@ -0,0 +1,16 @@
+import type { Loop, LoopRun, WorkflowSpec } from "../../types.js";
+import type { Goal, GoalExecutionContext, GoalPlanNode } from "./types.js";
+export interface GoalContextParts {
+    loop?: Pick<Loop, "id" | "name">;
+    loopRun?: Pick<LoopRun, "id" | "scheduledFor">;
+    scheduledFor?: string;
+    workflow?: Pick<WorkflowSpec, "id" | "name">;
+    workflowRunId?: string;
+    workflowStepId?: string;
+}
+/** Single source for the goal execution context previously copy-pasted across runners. */
+export declare function goalExecutionContext(parts: GoalContextParts): GoalExecutionContext;
+/** Executor metadata (LOOPS_* env) derived from a goal execution context; loopRunId maps to runId. */
+export declare function executionMetadata(context: GoalExecutionContext | undefined, goal?: Pick<Goal, "goalId" | "objective">, node?: Pick<GoalPlanNode, "key">): Record<string, string | undefined>;
+/** Exposes the executing plan node to child processes so command targets can honor node objectives. */
+export declare function withGoalNodeEnv(env: NodeJS.ProcessEnv | undefined, node: Pick<GoalPlanNode, "key" | "objective">): NodeJS.ProcessEnv;

package/dist/lib/goal/model-factory.d.ts

@@ -7,3 +7,4 @@ export interface ResolveGoalModelOptions {
 }
 export declare const DEFAULT_GOAL_MODEL = "openai/gpt-4o-mini";
 export declare function resolveGoalModel(opts?: ResolveGoalModelOptions): LanguageModel;
+export declare function resolveGoalVerifierModel(opts?: ResolveGoalModelOptions): LanguageModel;

package/dist/lib/goal/prompts.d.ts

@@ -1,4 +1,6 @@
+import type { ExecutableTarget } from "../../types.js";
 import type { Goal, GoalPlanNode, GoalSpec } from "./types.js";
 export declare function planPrompt(spec: GoalSpec): string;
-export declare function iterationPrompt(goal: Goal, readyNodes: GoalPlanNode[]): string;
+export declare function iterationPrompt(goal: Pick<Goal, "objective">, node: Pick<GoalPlanNode, "key" | "objective">): string;
+export declare function goalNodeTarget(target: ExecutableTarget, goal: Pick<Goal, "objective">, node: Pick<GoalPlanNode, "key" | "objective">): ExecutableTarget;
 export declare function achievementPrompt(goal: Goal, nodes: GoalPlanNode[], evidence: string[]): string;

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

@@ -11,6 +11,8 @@ export interface GoalSpec {
     objective: string;
     tokenBudget?: number;
     model?: string;
+    /** Independent model for the achievement audit; defaults to LOOPS_GOAL_VERIFIER_MODEL, then the planner model. */
+    verifierModel?: string;
     maxTurns?: number;
     maxTokens?: number;
     autoExecute?: GoalAutoExecute;
@@ -105,6 +107,7 @@ export interface GoalExecutionContext {
 export interface RunGoalOptions {
     store?: Store;
     model?: LanguageModel;
+    verifierModel?: LanguageModel;
     target?: ExecutableTarget;
     executeNode?: (node: GoalPlanNode, metadata: Record<string, string | undefined>) => Promise<ExecutorResult>;
     env?: NodeJS.ProcessEnv;

package/dist/lib/health.d.ts

@@ -1,6 +1,6 @@
 import type { Loop, LoopRun } from "../types.js";
 import type { Store } from "./store.js";
-export type RunFailureClassification = "rate_limit" | "auth" | "model_not_found" | "context_length" | "schema_response_format" | "node_init" | "preflight" | "route_functional" | "timeout" | "sigsegv" | "skipped_previous_active" | "unknown";
+export type RunFailureClassification = "rate_limit" | "auth" | "model_not_found" | "context_length" | "schema_response_format" | "node_init" | "preflight" | "route_functional" | "timeout" | "sigsegv" | "skipped_previous_active" | "circuit_breaker" | "unknown";
 export interface RunFailureSignal {
     classification: RunFailureClassification;
     fingerprint: string;

package/dist/lib/ids.d.ts

@@ -1,2 +1,9 @@
-export declare function genId(length?: number): string;
+/**
+ * Generate a 128-bit, time-sortable identifier (ULID-like): a 48-bit
+ * millisecond timestamp prefix (12 lowercase hex chars) followed by 80 random
+ * bits (20 lowercase hex chars). Fixed width keeps lexicographic order aligned
+ * with creation time, and plain lowercase hex stays compatible with the
+ * existing TEXT primary keys written by earlier releases.
+ */
+export declare function genId(): string;
 export declare function nowIso(): string;

package/dist/lib/machines.d.ts

@@ -1,4 +1,9 @@
 import type { LoopMachineRef } from "../types.js";
+export interface MachineCommandPlan {
+    command: string;
+    args: string[];
+    source: string;
+}
 export interface OpenMachineSummary {
     id: string;
     hostname?: string;
@@ -13,4 +18,5 @@ export interface OpenMachineSummary {
 }
 export declare function listOpenMachines(): OpenMachineSummary[];
 export declare function resolveLoopMachine(machineId: string): LoopMachineRef;
+export declare function resolveMachineCommand(machineId: string, command: string): MachineCommandPlan;
 export declare function refreshLoopMachine(machine: LoopMachineRef): LoopMachineRef;

package/dist/lib/process-identity.d.ts

@@ -0,0 +1,16 @@
+export declare const START_TIME_TOLERANCE_MS = 5000;
+export declare function procStatFields(path: string): string[] | undefined;
+export declare function processStartTimeMs(pid: number): number | undefined;
+/**
+ * Lenient fingerprint comparison: unknown data (no recorded start time, an
+ * unparsable record, or an unresolvable actual start time) counts as a match.
+ * Use for non-destructive liveness checks where "possibly alive" is the safe
+ * answer (pidfile checks, deciding not to take over a lease).
+ */
+export declare function sameProcessStart(recorded: string | number | undefined, actualMs: number | undefined, toleranceMs?: number): boolean;
+/**
+ * Strict fingerprint comparison for destructive paths (signalling processes):
+ * true only when both the recorded and actual start times resolve and match
+ * within tolerance. Unverifiable identity fails closed as a mismatch.
+ */
+export declare function verifiedProcessStart(recorded: string | number | undefined, actualMs: number | undefined, toleranceMs?: number): boolean;

package/dist/lib/{schedule.d.ts → recurrence.d.ts}

@@ -16,6 +16,7 @@ export interface DuePlan {
     slots: string[];
     skippedToNextRunAt?: string;
 }
+export declare const MAX_CATCH_UP_SLOTS = 1000;
 export declare function dueSlots(loop: Loop, now: Date): DuePlan;
 export declare function parseDuration(input: string): number;
 export {};

package/dist/lib/redact.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Write-path secret scrubbing. `scrubSecrets` removes credential material from
+ * text before it is persisted (run stdout/stderr/error, goal evidence, raw
+ * model responses). Display-layer truncation/redaction lives in format.ts;
+ * this module is about never writing recoverable secrets to disk at all.
+ *
+ * The function is idempotent (`scrubSecrets(scrubSecrets(x)) === scrubSecrets(x)`)
+ * and linear over the input, so it stays fast on multi-hundred-KB outputs.
+ */
+/**
+ * Replace credential tokens in `text` with "[SCRUBBED]". Idempotent and safe
+ * to run on JSON-encoded payloads (replacements never introduce quotes).
+ */
+export declare function scrubSecrets(text: string): string;
+/**
+ * Recursively scrub the string leaves of a JSON-serializable value. Run this
+ * BEFORE `JSON.stringify` when persisting structured payloads (goal evidence,
+ * raw model responses): stringify escapes quotes, which would otherwise hide
+ * quoted secrets from the flat text patterns above.
+ */
+export declare function scrubSecretsDeep<T>(value: T): T;

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

@@ -0,0 +1,18 @@
+export interface RouteSelection<T> {
+    selected: T[];
+    cursor: {
+        key: string;
+        total: number;
+        maxActions: number;
+        previousFingerprint?: string;
+        startIndex: number;
+        lastFingerprint?: string;
+    };
+}
+export declare function writeRouteCursor(key: string, lastFingerprint: string | undefined): void;
+export declare function writeRouteEvidence(kind: string, value: unknown, evidenceDir: string | undefined): string | undefined;
+export declare function selectRouteItems<T>(items: T[], maxActions: number, cursorKey: string, fingerprintOf: (item: T) => string): RouteSelection<T>;
+export declare function routeCursorKey(kind: "health" | "hygiene", parts: unknown[], opts: {
+    autoRoute?: boolean;
+    routeProjectPath?: string;
+}): string;

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

@@ -0,0 +1,6 @@
+import type { TodosDrainOptions } from "./types.js";
+export interface DrainResult {
+    value: Record<string, unknown>;
+    human: string;
+}
+export declare function drainTodosTaskRoutes(opts: TodosDrainOptions): DrainResult;

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

@@ -0,0 +1,27 @@
+import type { EventEnvelope } from "@hasna/events";
+/** Deep field extraction over Hasna event envelopes and todos task records. */
+export declare function eventData(event: EventEnvelope): Record<string, unknown>;
+export declare function eventMetadata(event: EventEnvelope): Record<string, unknown>;
+export declare function stringField(value: unknown): string | undefined;
+export declare function slugSegment(value: string, fallback?: string): string;
+export declare function stableSuffix(value: string): string;
+export declare function stableHash(parts: unknown[]): string;
+export declare function taskEventField(data: Record<string, unknown>, keys: string[]): string | undefined;
+export declare function objectField(value: unknown): Record<string, unknown> | undefined;
+export declare function taskEventRecords(data: Record<string, unknown>, metadata: Record<string, unknown>): Record<string, unknown>[];
+export declare function booleanLike(value: unknown): boolean;
+export declare function hasTruthyField(records: Record<string, unknown>[], keys: string[]): boolean;
+export declare function firstTruthyField(records: Record<string, unknown>[], keys: string[]): string | undefined;
+export declare function automationRecords(data: Record<string, unknown>, metadata: Record<string, unknown>): Record<string, unknown>[];
+export declare function tagsFromValue(value: unknown): string[];
+export declare function taskEventTags(records: Record<string, unknown>[]): string[];
+export declare function taskRouteEligibility(data: Record<string, unknown>, metadata: Record<string, unknown>): {
+    eligible: boolean;
+    reason?: string;
+    tags: string[];
+};
+export declare function canonicalRouteField(value: string): string;
+export declare function recordFieldValues(record: Record<string, unknown>, field: string): string[];
+export declare function routeFieldValues(records: Record<string, unknown>[], field: string): string[];
+export declare function firstRouteField(records: Record<string, unknown>[], fields: string[]): string | undefined;
+export declare function routeFieldList(records: Record<string, unknown>[], fields: string[]): string[] | undefined;

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

@@ -0,0 +1,26 @@
+import type { CreateWorkflowInput, LoopTarget, WorkflowSpec } from "../../types.js";
+import { CodedError } from "../errors.js";
+import { preflightTarget } from "../executor.js";
+import { preflightWorkflow } from "../workflow-runner.js";
+/**
+ * Validation/preflight gates shared by CLI commands and route engines. Failures
+ * throw a `GateError` carrying the gate kind and structured context so the CLI
+ * error runner can render the stable `{ok:false, created:false, ...}` JSON shape.
+ */
+export declare class GateError extends CodedError {
+    readonly gate: "validation" | "preflight";
+    readonly context: Record<string, unknown>;
+    constructor(gate: "validation" | "preflight", message: string, context: Record<string, unknown>);
+}
+export declare function normalizeLoopTargetForStorage(target: unknown, context: Record<string, unknown>, opts?: {
+    baseDir?: string;
+}): Exclude<LoopTarget, {
+    type: "workflow";
+}>;
+export declare function normalizeWorkflowForStorage(body: CreateWorkflowInput, context: Record<string, unknown>): CreateWorkflowInput;
+export declare function workflowBodyFromFile(file: string, fallbackName: string | undefined, context: Record<string, unknown>): CreateWorkflowInput;
+export declare function preflightLoopTarget(target: Exclude<LoopTarget, {
+    type: "workflow";
+}>, context: Record<string, unknown>, metadata: Parameters<typeof preflightTarget>[1], opts: Parameters<typeof preflightTarget>[2]): ReturnType<typeof preflightTarget>;
+export declare function preflightStoredWorkflow(workflow: Parameters<typeof preflightWorkflow>[0], context: Record<string, unknown>, opts: Parameters<typeof preflightWorkflow>[1]): ReturnType<typeof preflightWorkflow>;
+export declare function workflowSpecForPreflight(body: CreateWorkflowInput, id?: string): WorkflowSpec;

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

@@ -0,0 +1,18 @@
+/**
+ * Route engine: turns Hasna events, todos ready queues, and health/hygiene
+ * findings into deduped, throttled OpenLoops workflow loops and todos tasks.
+ * Extracted from the CLI so commands stay thin and the SDK/daemon can reuse it.
+ */
+export * from "./types.js";
+export * from "./parse.js";
+export { eventData, eventMetadata, objectField, slugSegment, stableHash, stableSuffix, stringField, tagsFromValue, taskEventField, taskEventTags, taskRouteEligibility, } from "./fields.js";
+export { routeCursorKey, selectRouteItems, writeRouteCursor, writeRouteEvidence, type RouteSelection } from "./cursors.js";
+export { GateError, normalizeLoopTargetForStorage, normalizeWorkflowForStorage, preflightLoopTarget, preflightStoredWorkflow, workflowBodyFromFile, workflowSpecForPreflight, } from "./gates.js";
+export { accountPoolFromOpts, normalizeAgentProvider, permissionModeFromOpts, providerAuthProfileFromOpts, providerRoutingPublic, resolveProviderRouting, roleAccountFromOpts, sandboxFromOpts, SUPPORTED_AGENT_PROVIDERS, type ProviderRoutingDecision, } from "./provider.js";
+export { prReviewRoutingDecision, type PrReviewRoutingDecision } from "./pr-review.js";
+export { hasThrottleLimits, normalizeRoutePath, routeThrottleDecision, routeThrottleLimitsFromOpts, type RouteThrottleDecision, type RouteThrottleLimits, } from "./throttle.js";
+export { generatedRouteSandboxPreflight, readEventEnvelopeInput, routeEventByKind, routeGenericEvent, routeTodosTaskEvent, todosTaskRouteTemplateId, } from "./route-event.js";
+export { drainTodosTaskRoutes, type DrainResult } from "./drain.js";
+export { buildHygieneRouteTasks, parseHygieneChecks, taskAutoRoute, upsertRouteTasks, type HygieneCheckKind, type HygieneRouteTask, type RouteTaskSpec, type UpsertRouteTasksOptions, } from "./route-tasks.js";
+export { defaultLoopsProject, ensureTodosTaskList, runLocalCommand, runLocalCommandWithStdoutFile } from "./todos-cli.js";
+export { addAgentRoutingOptions, addRouteEventOptions, addTodosDrainOptions, routeDrainArgs, type AgentRoutingOptionConfig } from "./options.js";

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

@@ -0,0 +1,31 @@
+import type { Command } from "commander";
+import type { TodosDrainOptions } from "./types.js";
+export interface AgentRoutingOptionConfig {
+    /** Include event input options (--event-file/--event-json). */
+    eventInput?: boolean;
+    /** Include todos-task-only options (template, triage/planner roles, PR gating). */
+    todosTask?: boolean;
+    /** Default for --provider; when set the option description drops the codewith hint. */
+    providerDefault?: string;
+    /** Default for --name-prefix. */
+    namePrefixDefault?: string;
+    /** Override the --preflight help text. */
+    preflightDescription?: string;
+    /** Include --dry-run with this help text; omit the flag entirely when absent. */
+    dryRunDescription?: string;
+}
+/** Compose the shared agent-routing flag block onto a route command. */
+export declare function addAgentRoutingOptions(command: Command, config?: AgentRoutingOptionConfig): Command;
+/** Options for `routes create/preview <kind>` and the deprecated `events handle` aliases. */
+export declare function addRouteEventOptions(command: Command, config?: AgentRoutingOptionConfig): Command;
+/** Options for `routes drain/schedule todos-task` and the deprecated `events drain` alias. */
+export declare function addTodosDrainOptions(command: Command, opts?: {
+    includeDryRun?: boolean;
+    preflightDescription?: string;
+}): Command;
+/**
+ * Rebuild the argv for a scheduled route drain loop from the same option specs
+ * used to declare the flags, so scheduled drains replay exactly the options the
+ * operator passed to `routes schedule`.
+ */
+export declare function routeDrainArgs(opts: TodosDrainOptions): string[];

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

@@ -0,0 +1,8 @@
+export declare function positiveInteger(raw: string | undefined, label: string): number | undefined;
+export declare function nonNegativeInteger(raw: string | undefined, label: string): number | undefined;
+export declare function positiveDuration(raw: string | undefined, label: string): number | undefined;
+export declare function timeoutDuration(raw: string | undefined, label: string): number | null | undefined;
+export declare function idleTimeoutDuration(raw: string | undefined, label: string): number | undefined;
+export declare function splitList(value: string | undefined): string[] | undefined;
+export declare function listFromRepeatedOpts(value: string[] | undefined): string[] | undefined;
+export declare function collectValues(value: string, previous?: string[]): string[];

package/dist/lib/route/pr-review.d.ts

@@ -0,0 +1,11 @@
+import type { TodosTaskRouteOptions } from "./types.js";
+export interface PrReviewRoutingDecision {
+    required: boolean;
+    allowed: boolean;
+    reason?: string;
+    author?: string;
+    reviewers: string[];
+    selectedReviewer?: string;
+    signals: string[];
+}
+export declare function prReviewRoutingDecision(data: Record<string, unknown>, metadata: Record<string, unknown>, opts: TodosTaskRouteOptions): PrReviewRoutingDecision;

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

@@ -0,0 +1,41 @@
+import type { AccountRef, AgentPermissionMode, AgentProvider, AgentSandbox } from "../../types.js";
+import type { TodosTaskRouteOptions } from "./types.js";
+export declare const SUPPORTED_AGENT_PROVIDERS: Set<AgentProvider>;
+export type ProviderRoutingSource = "default" | "option" | "rule" | "metadata";
+export interface ProviderRoutingRule {
+    raw: string;
+    field: string;
+    value: string;
+    provider: AgentProvider;
+    profiles?: string[];
+}
+export interface ProviderRoutingDecision {
+    provider: AgentProvider;
+    source: ProviderRoutingSource;
+    reason: string;
+    rule?: Pick<ProviderRoutingRule, "raw" | "field" | "value" | "provider" | "profiles">;
+    authProfile?: string;
+    authProfilePool?: string[];
+    account?: AccountRef;
+    accountPool?: AccountRef[];
+}
+export declare function normalizeAgentProvider(value: string | undefined, source: string): AgentProvider;
+export declare function parseProviderRoutingRule(raw: string): ProviderRoutingRule;
+export declare function accountPoolFromOpts(opts: {
+    accountPool?: string;
+    accountTool?: string;
+}): AccountRef[] | undefined;
+export declare function roleAccountFromOpts(opts: {
+    accountTool?: string;
+}, profile: string | undefined): AccountRef | undefined;
+export declare function providerRoutingPublic(decision: ProviderRoutingDecision): Record<string, unknown>;
+export declare function resolveProviderRouting(data: Record<string, unknown>, metadata: Record<string, unknown>, opts: TodosTaskRouteOptions): ProviderRoutingDecision;
+export declare function providerAuthProfileFromOpts(opts: {
+    authProfile?: string;
+}, provider: AgentProvider): string | undefined;
+export declare function sandboxFromOpts(opts: {
+    sandbox?: string;
+}, provider: AgentProvider): AgentSandbox | undefined;
+export declare function permissionModeFromOpts(opts: {
+    permissionMode?: string;
+}, provider: AgentProvider): AgentPermissionMode | undefined;

package/dist/lib/route/route-event.d.ts

@@ -0,0 +1,23 @@
+import type { EventEnvelope } from "@hasna/events";
+import type { AgentProvider, AgentSandbox, CreateWorkflowInput } from "../../types.js";
+import type { TodosTaskRouteOptions, TodosTaskRoutePrint } from "./types.js";
+/** Shared event-to-workflow route engine behind `routes create/preview` and the deprecated `events handle` aliases. */
+interface RouteSandboxPreflight {
+    stepId: string;
+    provider: AgentProvider;
+    sandbox?: AgentSandbox;
+    worktreeEnabled?: boolean;
+    method: "provider-native-sandbox" | "isolated-worktree" | "manual-break-glass";
+}
+export declare function generatedRouteSandboxPreflight(workflow: CreateWorkflowInput): RouteSandboxPreflight[];
+export declare function todosTaskRouteTemplateId(opts: {
+    template?: string;
+}): string;
+export declare function readEventEnvelopeInput(opts?: {
+    eventJson?: string;
+    eventFile?: string;
+}): Promise<EventEnvelope>;
+export declare function routeTodosTaskEvent(event: EventEnvelope, opts: TodosTaskRouteOptions): TodosTaskRoutePrint;
+export declare function routeGenericEvent(event: EventEnvelope, opts: TodosTaskRouteOptions): TodosTaskRoutePrint;
+export declare function routeEventByKind(kind: string, event: EventEnvelope, opts: TodosTaskRouteOptions): TodosTaskRoutePrint;
+export {};

package/dist/lib/route/route-tasks.d.ts

@@ -0,0 +1,75 @@
+import type { Store } from "../store.js";
+/** Deduped todos task upserts shared by `health route-tasks` and `hygiene route-tasks`. */
+export interface TaskRouteOptions {
+    autoRoute?: boolean;
+    routeProjectPath?: string;
+    source: string;
+}
+export declare function taskAutoRoute(tags: string[], base: Record<string, unknown>, opts: TaskRouteOptions): {
+    tags: string[];
+    metadata: Record<string, unknown>;
+    autoRoute: {
+        requested: boolean;
+        enabled: boolean;
+        skippedReason?: string;
+    };
+};
+export interface RouteTaskSpec {
+    title: string;
+    description: string;
+    priority: string;
+    tags: string[];
+    fingerprint: string;
+    /** Base metadata handed to taskAutoRoute (before route flags are merged in). */
+    metadata: Record<string, unknown>;
+    /** Extra fields copied onto every action record for this task (e.g. hygiene `check`). */
+    extra?: Record<string, unknown>;
+}
+export interface UpsertRouteTasksOptions {
+    project: string;
+    taskList: {
+        slug: string;
+        name: string;
+        description: string;
+    };
+    cursorKey: string;
+    maxActions: number;
+    dryRun?: boolean;
+    autoRoute?: boolean;
+    routeProjectPath?: string;
+    source: string;
+    evidence: {
+        kind: string;
+        dir?: string;
+    };
+    /** Command-specific summary fields merged into the output before routing/actions. */
+    summary: Record<string, unknown>;
+    tasks: RouteTaskSpec[];
+}
+export interface UpsertRouteTasksResult {
+    ok: boolean;
+    output: Record<string, unknown>;
+    evidencePath?: string;
+}
+export declare function upsertRouteTasks(opts: UpsertRouteTasksOptions): UpsertRouteTasksResult;
+export type HygieneCheckKind = "names" | "duplicates" | "scripts";
+export interface HygieneRouteTask {
+    check: HygieneCheckKind;
+    title: string;
+    description: string;
+    priority: "critical" | "high" | "medium" | "low";
+    tags: string[];
+    fingerprint: string;
+    metadata: Record<string, unknown>;
+}
+export declare function parseHygieneChecks(value: string | undefined): HygieneCheckKind[];
+export declare function buildHygieneRouteTasks(store: Store, opts: {
+    checks: HygieneCheckKind[];
+    includeInactive?: boolean;
+    limit?: number;
+    scriptsDir?: string;
+}): {
+    checked: Record<HygieneCheckKind, number>;
+    findings: number;
+    tasks: HygieneRouteTask[];
+};