@hasna/loops 0.4.28 → 0.4.29

package/dist/lib/storage/tenant-backfill-s3.d.ts

@@ -0,0 +1,53 @@
+import type { PoolQueryClient } from "../../generated/storage-kit/query.js";
+import { loadTenantBackfillBundle } from "./tenant-backfill.js";
+export declare const TENANT_BACKFILL_MAX_BYTES: number;
+export interface TenantBackfillS3Client {
+    list(input: {
+        prefix: string;
+        maxKeys: number;
+    }): Promise<{
+        contents?: Array<{
+            key: string;
+            size?: number;
+        }>;
+        isTruncated?: boolean;
+    }>;
+    file(key: string): {
+        bytes(): Promise<Uint8Array>;
+    };
+    delete(key: string): Promise<void>;
+}
+interface TaskRoleCredentials {
+    accessKeyId: string;
+    secretAccessKey: string;
+    sessionToken: string;
+}
+export type TenantBackfillFetch = (input: string, init?: RequestInit) => Promise<Response>;
+interface TenantBackfillS3Options {
+    bucket: string;
+    region: string;
+    credentialsRelativeUri: string;
+}
+interface TenantBackfillS3Dependencies {
+    fetch?: TenantBackfillFetch;
+    createS3Client?: (options: TaskRoleCredentials & {
+        bucket: string;
+        region: string;
+        endpoint: string;
+    }) => TenantBackfillS3Client;
+    loadBundle?: typeof loadTenantBackfillBundle;
+}
+export interface TenantBackfillS3Result {
+    digest: string;
+    counts: {
+        tenants: number;
+        principals: number;
+        memberships: number;
+        keyBindings: number;
+        rowAssignments: number;
+    };
+}
+export declare function fetchEcsTaskRoleCredentials(relativeUri: string, fetchImpl?: TenantBackfillFetch): Promise<TaskRoleCredentials>;
+export declare function loadApprovedTenantBackfillBundle(queryClient: PoolQueryClient, options: TenantBackfillS3Options, dependencies?: TenantBackfillS3Dependencies): Promise<TenantBackfillS3Result>;
+export declare function logTenantBackfillS3Success(result: TenantBackfillS3Result): void;
+export {};

package/dist/lib/storage/tenant-backfill.d.ts

@@ -0,0 +1,40 @@
+import type { PoolQueryClient } from "../../generated/storage-kit/query.js";
+declare const BUNDLE_SCHEMA = "open-loops.tenant-backfill/v1";
+export interface TenantBackfillBundle {
+    schema: typeof BUNDLE_SCHEMA;
+    tenants: Array<{
+        id: string;
+        slug: string;
+        name: string;
+        status: "active" | "suspended";
+    }>;
+    principals: Array<{
+        id: string;
+        kind: "human" | "service" | "machine";
+        displayName: string;
+        status: "active" | "suspended";
+    }>;
+    memberships: Array<{
+        tenantId: string;
+        principalId: string;
+        status: "active" | "suspended";
+        roles: string[];
+    }>;
+    keyBindings: Array<{
+        kid: string;
+        tenantId: string;
+        principalId: string;
+        tokenKind: "api_key" | "service" | "machine";
+    }>;
+    rowAssignments: Array<{
+        table: string;
+        rowId: string;
+        tenantId: string;
+    }>;
+}
+export declare function parseTenantBackfillBundle(value: unknown): TenantBackfillBundle;
+export declare function loadTenantBackfillBundle(client: PoolQueryClient, bundle: TenantBackfillBundle): Promise<{
+    digest: string;
+    assignments: number;
+}>;
+export {};

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

@@ -1,4 +1,4 @@
-import type { CreateLoopInput, CreateWorkflowInput, Loop, LoopRun, LoopStatus, RunReceipt, RunStatus, WorkflowEvent, WorkflowInvocation, WorkflowRun, WorkflowSpec, WorkflowStepRun, WorkflowWorkItem, WorkflowWorkItemStatus, WriteRunReceiptInput } from "../../types.js";
+import type { CreateLoopInput, CreateWorkflowInput, Loop, LoopRun, LoopStatus, PublicWorkflowEvent, RunReceipt, RunStatus, WorkflowInvocation, WorkflowRun, WorkflowSpec, WorkflowStepRun, WorkflowWorkItem, WorkflowWorkItemStatus, WriteRunReceiptInput } from "../../types.js";
 import type { Goal, GoalPlanNode, GoalRun, GoalStatus } from "../goal/types.js";
 import type { HasnaStorageClient } from "../cloud/storage.js";
 import type { Env } from "../cloud/mode.js";
@@ -16,7 +16,7 @@ export declare class CloudUnsupportedError extends Error {
     constructor(operation: string);
 }
 /**
- * The single data interface for the OpenLoops client. Both {@link LocalStore}
+ * The single data interface for the Loops client. Both {@link LocalStore}
  * and {@link ApiStore} implement it; callers hold a `LoopStore` and never know
  * (or branch on) which one. Every method is async so the two transports share
  * one surface.
@@ -31,6 +31,7 @@ export interface LoopStore {
     requireUniqueLoop(idOrName: string): Promise<Loop>;
     listLoops(opts?: {
         status?: LoopStatus;
+        labels?: string[];
         limit?: number;
         offset?: number;
         archived?: boolean;
@@ -41,7 +42,7 @@ export interface LoopStore {
         archived?: boolean;
         includeArchived?: boolean;
     }): Promise<number>;
-    updateLoop(id: string, patch: Partial<Pick<Loop, "status" | "nextRunAt" | "retryScheduledFor" | "expiresAt">>): Promise<Loop>;
+    updateLoop(id: string, patch: Partial<Pick<Loop, "status" | "nextRunAt" | "retryScheduledFor" | "expiresAt" | "labels">>): Promise<Loop>;
     renameLoop(id: string, name: string): Promise<Loop>;
     archiveLoop(idOrName: string): Promise<Loop>;
     unarchiveLoop(idOrName: string): Promise<Loop>;
@@ -67,7 +68,7 @@ export interface LoopStore {
         limit?: number;
     }): Promise<WorkflowRun[]>;
     listWorkflowStepRuns(workflowRunId: string): Promise<WorkflowStepRun[]>;
-    listWorkflowEvents(workflowRunId: string, limit?: number): Promise<WorkflowEvent[]>;
+    listWorkflowEvents(workflowRunId: string, limit?: number): Promise<PublicWorkflowEvent[]>;
     recoverWorkflowRun(workflowRunId: string, reason?: string): Promise<{
         run: WorkflowRun;
         recoveredSteps: WorkflowStepRun[];
@@ -103,6 +104,7 @@ export interface LoopStore {
     listRuns(opts?: {
         loopId?: string;
         status?: RunStatus;
+        labels?: string[];
         limit?: number;
         offset?: number;
     }): Promise<LoopRun[]>;
@@ -147,7 +149,7 @@ export declare class LocalStore implements LoopStore {
         archived?: boolean;
         includeArchived?: boolean;
     }): Promise<number>;
-    updateLoop(id: string, patch: Partial<Pick<Loop, "status" | "nextRunAt" | "retryScheduledFor" | "expiresAt">>): Promise<Loop>;
+    updateLoop(id: string, patch: Partial<Pick<Loop, "status" | "nextRunAt" | "retryScheduledFor" | "expiresAt" | "labels">>): Promise<Loop>;
     renameLoop(id: string, name: string): Promise<Loop>;
     archiveLoop(idOrName: string): Promise<Loop>;
     unarchiveLoop(idOrName: string): Promise<Loop>;
@@ -165,7 +167,7 @@ export declare class LocalStore implements LoopStore {
     requireWorkflowRun(id: string): Promise<WorkflowRun>;
     listWorkflowRuns(opts?: Parameters<Store["listWorkflowRuns"]>[0]): Promise<WorkflowRun[]>;
     listWorkflowStepRuns(workflowRunId: string): Promise<WorkflowStepRun[]>;
-    listWorkflowEvents(workflowRunId: string, limit?: number): Promise<WorkflowEvent[]>;
+    listWorkflowEvents(workflowRunId: string, limit?: number): Promise<PublicWorkflowEvent[]>;
     recoverWorkflowRun(workflowRunId: string, reason?: string): Promise<{
         run: WorkflowRun;
         recoveredSteps: WorkflowStepRun[];
@@ -216,10 +218,11 @@ export declare class ApiStore implements LoopStore {
         archived?: boolean;
         includeArchived?: boolean;
     }): Promise<number>;
-    updateLoop(id: string, patch: Partial<Pick<Loop, "status" | "nextRunAt" | "retryScheduledFor" | "expiresAt">>): Promise<Loop>;
+    updateLoop(id: string, patch: Partial<Pick<Loop, "status" | "nextRunAt" | "retryScheduledFor" | "expiresAt" | "labels">>): Promise<Loop>;
     renameLoop(id: string, name: string): Promise<Loop>;
     archiveLoop(idOrName: string): Promise<Loop>;
     unarchiveLoop(idOrName: string): Promise<Loop>;
+    private mutateArchiveState;
     deleteLoop(idOrName: string): Promise<boolean>;
     createWorkflow(input: CreateWorkflowInput): Promise<WorkflowSpec>;
     getWorkflow(id: string): Promise<WorkflowSpec | undefined>;
@@ -234,7 +237,7 @@ export declare class ApiStore implements LoopStore {
     requireWorkflowRun(id: string): Promise<WorkflowRun>;
     listWorkflowRuns(opts?: Parameters<LoopStore["listWorkflowRuns"]>[0]): Promise<WorkflowRun[]>;
     listWorkflowStepRuns(workflowRunId: string): Promise<WorkflowStepRun[]>;
-    listWorkflowEvents(workflowRunId: string, limit?: number): Promise<WorkflowEvent[]>;
+    listWorkflowEvents(workflowRunId: string, limit?: number): Promise<PublicWorkflowEvent[]>;
     recoverWorkflowRun(workflowRunId: string, reason?: string): Promise<{
         run: WorkflowRun;
         recoveredSteps: WorkflowStepRun[];

package/dist/lib/store.d.ts

@@ -1,13 +1,31 @@
-import type { CreateLoopInput, CreateWorkflowInvocationInput, CreateWorkflowInput, Goal, GoalAutoExecute, GoalPlanNode, GoalRun, GoalStatus, Loop, LoopRun, LoopStatus, RunReceipt, RunStatus, TimeoutMs, WriteRunReceiptInput, WorkflowEvent, WorkflowInvocation, WorkflowRun, WorkflowRunStatus, WorkflowSpec, WorkflowStepRun, WorkflowWorkItem, WorkflowWorkItemStatus, UpsertWorkflowWorkItemInput } from "../types.js";
+import type { CreateLoopInput, CreateWorkflowInvocationInput, CreateWorkflowInput, Goal, GoalAutoExecute, GoalPlanNode, GoalRun, GoalStatus, Loop, LoopRun, LoopStatus, RecoveredLeaseRunSnapshotEntry, RunReceipt, RunStatus, TimeoutMs, StoredWorkflowEvent, WriteRunReceiptInput, WorkflowInvocation, WorkflowRun, WorkflowRunStatus, WorkflowSpec, WorkflowStepRun, WorkflowWorkItem, WorkflowWorkItemStatus, UpsertWorkflowWorkItemInput } from "../types.js";
+import { type InitialAgentSessionContractEvent } from "./workflow-provenance.js";
 interface DaemonLeaseFence {
     daemonLeaseId?: string;
     now?: Date;
     claimToken?: string;
+    recoveredRun?: RecoveredLeaseRunSnapshotEntry;
 }
+export interface WorkflowRecoveryContext {
+    mode?: "internal" | "operator" | "runner";
+    now?: Date;
+    loopRunId?: string;
+    claimedBy?: string;
+    claimToken?: string;
+}
+export type LoopSchedulingState = Pick<Loop, "status" | "nextRunAt" | "retryScheduledFor">;
+export interface CircuitBreakerTransitionResult {
+    loop: Loop;
+    marker: LoopRun;
+}
+export declare const GENERATED_ROUTE_TEMPLATE_IDS: Set<string>;
+export declare const GENERATED_ROUTE_KEYS: Set<string>;
+export declare function isGeneratedRouteTemplate(routeKey: string, templateId: string): boolean;
 export interface LoopRow {
     id: string;
     name: string;
     description: string | null;
+    labels_json: string | null;
     status: string;
     archived_at: string | null;
     archived_from_status: string | null;
@@ -89,6 +107,7 @@ export interface WorkflowRunRow {
     work_item_id: string | null;
     scheduled_for: string | null;
     idempotency_key: string | null;
+    workflow_definition_hash: string | null;
     manifest_path: string | null;
     status: string;
     started_at: string | null;
@@ -258,12 +277,13 @@ export declare function rowToWorkflowStepRun(row: WorkflowStepRunRow): WorkflowS
 export declare function rowToGoal(row: GoalRow): Goal;
 export declare function rowToGoalPlanNode(row: GoalPlanNodeRow): GoalPlanNode;
 export declare function rowToGoalRun(row: GoalRunRow): GoalRun;
-export declare function rowToWorkflowEvent(row: WorkflowEventRow): WorkflowEvent;
+export declare function rowToWorkflowEvent(row: WorkflowEventRow): StoredWorkflowEvent;
+export declare function isLiveStepProcess(pid: number, stepStartedAt: string | null | undefined): boolean;
 export declare function rowToLease(row: LeaseRow): DaemonLease;
 export interface ClaimRunResult {
     run: LoopRun;
     loop: Loop;
-    claimToken?: string;
+    claimToken: string;
 }
 export interface CreateWorkflowRunInput {
     workflow: WorkflowSpec;
@@ -274,6 +294,8 @@ export interface CreateWorkflowRunInput {
     invocationId?: string;
     workItemId?: string;
     daemonLeaseId?: string;
+    /** Internal deterministic fault-injection seam used to verify atomic initial event persistence. */
+    beforeInitialWorkflowEventPersist?: (event: InitialAgentSessionContractEvent) => void;
 }
 export interface CreateGoalInput {
     objective: string;
@@ -306,6 +328,11 @@ export interface RecoverExpiredRunLeasesResult {
     /** Runs whose lease expired while their process (group) is still alive; lease deferred. */
     deferred: LoopRun[];
 }
+export interface RecoveredLeaseRunPage {
+    runs: LoopRun[];
+    snapshot?: RecoveredLeaseRunSnapshotEntry[];
+    nextOffset?: number;
+}
 export interface PruneHistoryOptions {
     /** Delete terminal runs whose created_at is older than this many days. */
     maxAgeDays?: number;
@@ -416,6 +443,9 @@ export declare function classifyNonProductiveStepFailure(steps: ClassifiableStep
 export declare function scrubbedOrNull(value: string | undefined | null): string | null;
 /** Scrub secrets then bound size before persisting run stdout/stderr. */
 export declare function persistedRunOutput(value: string | undefined | null): string | null;
+/** Scrub structured string leaves before stringify, then scrub the encoded JSON. */
+export declare function persistedJson(value: unknown): string;
+export declare function persistedWorkflowEventPayload(payload: Record<string, unknown> | undefined | null): string | null;
 export declare class Store {
     private db;
     private rootDir;
@@ -443,9 +473,11 @@ export declare class Store {
     getLoop(id: string): Loop | undefined;
     findLoopByName(name: string): Loop | undefined;
     requireUniqueLoop(idOrName: string): Loop;
+    private requireArchiveMutationLoop;
     requireLoop(idOrName: string): Loop;
     listLoops(opts?: {
         status?: LoopStatus;
+        labels?: string[];
         limit?: number;
         offset?: number;
         archived?: boolean;
@@ -454,7 +486,12 @@ export declare class Store {
     }): Loop[];
     private withLatestRunSummaries;
     dueLoops(now: Date, limit?: number): Loop[];
-    updateLoop(id: string, patch: Partial<Pick<Loop, "status" | "nextRunAt" | "retryScheduledFor" | "expiresAt">>, opts?: DaemonLeaseFence): Loop;
+    updateLoop(id: string, patch: Partial<Pick<Loop, "status" | "nextRunAt" | "retryScheduledFor" | "expiresAt" | "labels">>, opts?: DaemonLeaseFence): Loop;
+    advanceLoopIfCurrent(id: string, expected: LoopSchedulingState, patch: Partial<Pick<Loop, "status" | "nextRunAt" | "retryScheduledFor">>, opts?: DaemonLeaseFence): Loop | undefined;
+    tripCircuitBreakerIfCurrent(id: string, expected: LoopSchedulingState, patch: Partial<Pick<Loop, "status" | "nextRunAt" | "retryScheduledFor">>, marker: {
+        scheduledFor: string;
+        reason: string;
+    }, opts?: DaemonLeaseFence): CircuitBreakerTransitionResult | undefined;
     private activeLoopReferenceCount;
     private archiveWorkflowIfUnreferenced;
     retargetWorkflowLoop(idOrName: string, workflowId: string, opts?: DaemonLeaseFence & {
@@ -630,7 +667,7 @@ export declare class Store {
         stderr?: string;
         payload?: Record<string, unknown>;
     }, opts?: DaemonLeaseFence): WorkflowStepRun;
-    recoverWorkflowRun(workflowRunId: string, reason?: string): {
+    recoverWorkflowRun(workflowRunId: string, reason?: string, _context?: WorkflowRecoveryContext): {
         run: WorkflowRun;
         recoveredSteps: WorkflowStepRun[];
     };
@@ -638,8 +675,8 @@ export declare class Store {
     skipWorkflowStepRun(workflowRunId: string, stepId: string, reason: string, opts?: DaemonLeaseFence): WorkflowStepRun;
     finalizeWorkflowRun(workflowRunId: string, status: WorkflowRunStatus, patch?: Partial<Pick<WorkflowRun, "finishedAt" | "durationMs" | "error">>, opts?: DaemonLeaseFence): WorkflowRun;
     cancelWorkflowRun(workflowRunId: string, reason?: string): WorkflowRun;
-    appendWorkflowEvent(workflowRunId: string, eventType: string, stepId?: string, payload?: Record<string, unknown>): WorkflowEvent;
-    listWorkflowEvents(workflowRunId: string, limit?: number): WorkflowEvent[];
+    appendWorkflowEvent(workflowRunId: string, eventType: string, stepId?: string, payload?: Record<string, unknown>): StoredWorkflowEvent;
+    listWorkflowEvents(workflowRunId: string, limit?: number): StoredWorkflowEvent[];
     hasRunningRun(loopId: string): boolean;
     hasRunningRunForSlot(loopId: string, scheduledFor: string): boolean;
     private hasBlockingRunningRunForOtherSlot;
@@ -665,9 +702,15 @@ export declare class Store {
     listRuns(opts?: {
         loopId?: string;
         status?: RunStatus;
+        labels?: string[];
         limit?: number;
         offset?: number;
     }): LoopRun[];
+    listRecoveredLeaseRunsPage(opts?: {
+        snapshot?: RecoveredLeaseRunSnapshotEntry[];
+        offset?: number;
+        limit?: number;
+    }): RecoveredLeaseRunPage;
     writeRunReceipt(input: WriteRunReceiptInput, opts?: {
         now?: Date;
     }): RunReceipt;
@@ -684,6 +727,7 @@ export declare class Store {
     recoverExpiredRunLeases(now?: Date, opts?: DaemonLeaseFence & {
         limit?: number;
         scanLimit?: number;
+        runId?: string;
     }): LoopRun[];
     /**
      * Recover expired run leases and report both outcomes: runs abandoned (no
@@ -694,6 +738,7 @@ export declare class Store {
     recoverExpiredRunLeasesDetailed(now?: Date, opts?: DaemonLeaseFence & {
         limit?: number;
         scanLimit?: number;
+        runId?: string;
     }): RecoverExpiredRunLeasesResult;
     expireLoops(now?: Date, opts?: DaemonLeaseFence): Loop[];
     countLoops(status?: LoopStatus, opts?: {