@hasna/loops 0.4.27 → 0.4.28

package/dist/api/index.js

@@ -3,7 +3,7 @@
 // package.json
 var package_default = {
   name: "@hasna/loops",
-  version: "0.4.27",
+  version: "0.4.28",
   description: "Persistent local loop and workflow runner for deterministic commands and headless AI coding agents",
   type: "module",
   main: "dist/index.js",
@@ -113,6 +113,7 @@ var package_default = {
     bun: ">=1.0.0"
   },
   dependencies: {
+    "@hasna/contracts": "^0.5.1",
     "@hasna/events": "^0.1.9",
     "@modelcontextprotocol/sdk": "^1.29.0",
     "@openrouter/ai-sdk-provider": "2.9.1",
@@ -122,8 +123,7 @@ var package_default = {
     zod: "4.4.3"
   },
   optionalDependencies: {
-    "@hasna/machines": "0.0.49",
-    "@hasna/contracts": "^0.4.2"
+    "@hasna/machines": "0.0.49"
   },
   devDependencies: {
     "@types/bun": "latest",
@@ -935,6 +935,14 @@ var loops_default = {
               type: "integer"
             }
           },
+          {
+            name: "offset",
+            in: "query",
+            required: false,
+            schema: {
+              type: "integer"
+            }
+          },
           {
             name: "includeArchived",
             in: "query",
@@ -1210,6 +1218,22 @@ var loops_default = {
             schema: {
               type: "integer"
             }
+          },
+          {
+            name: "offset",
+            in: "query",
+            required: false,
+            schema: {
+              type: "integer"
+            }
+          },
+          {
+            name: "showOutput",
+            in: "query",
+            required: false,
+            schema: {
+              type: "boolean"
+            }
           }
         ],
         responses: {
@@ -1266,6 +1290,14 @@ var loops_default = {
             schema: {
               type: "string"
             }
+          },
+          {
+            name: "showOutput",
+            in: "query",
+            required: false,
+            schema: {
+              type: "boolean"
+            }
           }
         ],
         responses: {
@@ -1286,7 +1318,7 @@ var loops_default = {
       post: {
         operationId: "importRows",
         summary: "Bulk id-preserving import (self-hosted backfill)",
-        description: "Upsert full workflow/loop/run rows by id (idempotent; ON CONFLICT(id) DO UPDATE). Preserves id, status, archived state, and timestamps. Applied FK-safe: workflows, then loops, then runs. Volatile running runs are skipped and reported.",
+        description: "Upsert full workflow/loop/run rows by id (idempotent; ON CONFLICT(id) DO UPDATE). Preserves ids, definitions, and timestamps while applying safe defaults: imported workflows are archived, imported loops are paused, and nextRunAt/retryScheduledFor are cleared by default so backfills never schedule immediately. Set preserveWorkflowActivation=true or preserveLoopScheduling=true only for intentional activation. Applied FK-safe: workflows, then loops, then runs. Volatile running runs are skipped and reported.",
         requestBody: {
           required: true,
           content: {
@@ -1311,6 +1343,260 @@ var loops_default = {
         }
       }
     },
+    "/v1/workflows": {
+      get: {
+        operationId: "listWorkflows",
+        summary: "List workflow specs",
+        parameters: [
+          {
+            name: "status",
+            in: "query",
+            required: false,
+            schema: {
+              type: "string",
+              enum: [
+                "active",
+                "archived"
+              ]
+            }
+          },
+          {
+            name: "limit",
+            in: "query",
+            required: false,
+            schema: {
+              type: "integer"
+            }
+          },
+          {
+            name: "offset",
+            in: "query",
+            required: false,
+            schema: {
+              type: "integer"
+            }
+          }
+        ],
+        responses: {
+          "200": {
+            description: "workflow specs",
+            content: {
+              "application/json": {
+                schema: {
+                  $ref: "#/components/schemas/WorkflowListResponse"
+                }
+              }
+            }
+          }
+        }
+      },
+      post: {
+        operationId: "createWorkflow",
+        summary: "Create a workflow spec",
+        requestBody: {
+          required: true,
+          content: {
+            "application/json": {
+              schema: {
+                $ref: "#/components/schemas/CreateWorkflowInput"
+              }
+            }
+          }
+        },
+        responses: {
+          "201": {
+            description: "workflow",
+            content: {
+              "application/json": {
+                schema: {
+                  $ref: "#/components/schemas/WorkflowResponse"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/v1/workflows/count": {
+      get: {
+        operationId: "countWorkflows",
+        summary: "Count workflow specs",
+        parameters: [
+          {
+            name: "status",
+            in: "query",
+            required: false,
+            schema: {
+              type: "string"
+            }
+          }
+        ],
+        responses: {
+          "200": {
+            description: "count",
+            content: {
+              "application/json": {
+                schema: {
+                  $ref: "#/components/schemas/CountResponse"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/v1/workflows/{id}": {
+      get: {
+        operationId: "getWorkflow",
+        summary: "Get a workflow spec by id",
+        parameters: [
+          {
+            name: "id",
+            in: "path",
+            required: true,
+            schema: {
+              type: "string"
+            }
+          }
+        ],
+        responses: {
+          "200": {
+            description: "workflow",
+            content: {
+              "application/json": {
+                schema: {
+                  $ref: "#/components/schemas/WorkflowResponse"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/v1/invocations": {
+      get: {
+        operationId: "listWorkflowInvocations",
+        summary: "List workflow route invocations",
+        parameters: [
+          {
+            name: "limit",
+            in: "query",
+            required: false,
+            schema: {
+              type: "integer"
+            }
+          }
+        ],
+        responses: {
+          "200": {
+            description: "workflow invocations",
+            content: {
+              "application/json": {
+                schema: {
+                  $ref: "#/components/schemas/WorkflowInvocationListResponse"
+                }
+              }
+            }
+          }
+        }
+      },
+      post: {
+        operationId: "createWorkflowInvocation",
+        summary: "Create an id-preserving workflow route invocation",
+        requestBody: {
+          required: true,
+          content: {
+            "application/json": {
+              schema: {
+                $ref: "#/components/schemas/CreateWorkflowInvocationInput"
+              }
+            }
+          }
+        },
+        responses: {
+          "201": {
+            description: "workflow invocation",
+            content: {
+              "application/json": {
+                schema: {
+                  $ref: "#/components/schemas/WorkflowInvocationResponse"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/v1/work-items": {
+      get: {
+        operationId: "listWorkflowWorkItems",
+        summary: "List workflow route work items",
+        parameters: [
+          {
+            name: "status",
+            in: "query",
+            required: false,
+            schema: {
+              type: "string"
+            }
+          },
+          {
+            name: "routeKey",
+            in: "query",
+            required: false,
+            schema: {
+              type: "string"
+            }
+          },
+          {
+            name: "limit",
+            in: "query",
+            required: false,
+            schema: {
+              type: "integer"
+            }
+          }
+        ],
+        responses: {
+          "200": {
+            description: "workflow work items",
+            content: {
+              "application/json": {
+                schema: {
+                  $ref: "#/components/schemas/WorkflowWorkItemListResponse"
+                }
+              }
+            }
+          }
+        }
+      },
+      post: {
+        operationId: "upsertWorkflowWorkItem",
+        summary: "Upsert an id-preserving workflow route work item",
+        requestBody: {
+          required: true,
+          content: {
+            "application/json": {
+              schema: {
+                $ref: "#/components/schemas/UpsertWorkflowWorkItemInput"
+              }
+            }
+          }
+        },
+        responses: {
+          "201": {
+            description: "workflow work item",
+            content: {
+              "application/json": {
+                schema: {
+                  $ref: "#/components/schemas/WorkflowWorkItemResponse"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
     "/v1/receipts": {
       get: {
         operationId: "listRunReceipts",
@@ -1913,22 +2199,368 @@ var loops_default = {
           "receipts"
         ]
       },
-      ImportInput: {
+      Workflow: {
         type: "object",
-        description: "Batches of full rows to upsert by id. Any array may be omitted.",
         properties: {
-          workflows: {
-            type: "array",
-            items: {
-              type: "object",
-              additionalProperties: true
-            }
+          id: {
+            type: "string"
           },
-          loops: {
-            type: "array",
-            items: {
-              type: "object",
-              additionalProperties: true
+          name: {
+            type: "string"
+          },
+          description: {
+            type: "string",
+            nullable: true
+          },
+          version: {
+            type: "integer"
+          },
+          status: {
+            type: "string"
+          },
+          steps: {
+            type: "array",
+            items: {
+              type: "object",
+              additionalProperties: true
+            }
+          },
+          goal: {
+            type: "object",
+            additionalProperties: true
+          },
+          createdAt: {
+            type: "string"
+          },
+          updatedAt: {
+            type: "string"
+          }
+        },
+        required: [
+          "id",
+          "name",
+          "version",
+          "status",
+          "steps"
+        ]
+      },
+      CreateWorkflowInput: {
+        type: "object",
+        properties: {
+          name: {
+            type: "string"
+          },
+          description: {
+            type: "string"
+          },
+          steps: {
+            type: "array",
+            items: {
+              type: "object",
+              additionalProperties: true
+            }
+          },
+          goal: {
+            type: "object",
+            additionalProperties: true
+          }
+        },
+        required: [
+          "name",
+          "steps"
+        ]
+      },
+      WorkflowResponse: {
+        type: "object",
+        properties: {
+          ok: {
+            type: "boolean"
+          },
+          workflow: {
+            $ref: "#/components/schemas/Workflow"
+          }
+        },
+        required: [
+          "ok",
+          "workflow"
+        ]
+      },
+      WorkflowListResponse: {
+        type: "object",
+        properties: {
+          ok: {
+            type: "boolean"
+          },
+          workflows: {
+            type: "array",
+            items: {
+              $ref: "#/components/schemas/Workflow"
+            }
+          }
+        },
+        required: [
+          "ok",
+          "workflows"
+        ]
+      },
+      CreateWorkflowInvocationInput: {
+        type: "object",
+        properties: {
+          id: {
+            type: "string"
+          },
+          workflowId: {
+            type: "string"
+          },
+          templateId: {
+            type: "string"
+          },
+          sourceRef: {
+            type: "object",
+            additionalProperties: true
+          },
+          subjectRef: {
+            type: "object",
+            additionalProperties: true
+          },
+          intent: {
+            type: "string"
+          },
+          scope: {
+            type: "object",
+            additionalProperties: true
+          },
+          outputPolicy: {
+            type: "object",
+            additionalProperties: true
+          }
+        },
+        required: [
+          "sourceRef",
+          "subjectRef",
+          "intent"
+        ]
+      },
+      WorkflowInvocation: {
+        allOf: [
+          {
+            $ref: "#/components/schemas/CreateWorkflowInvocationInput"
+          },
+          {
+            type: "object",
+            properties: {
+              id: {
+                type: "string"
+              },
+              createdAt: {
+                type: "string"
+              },
+              updatedAt: {
+                type: "string"
+              }
+            },
+            required: [
+              "id",
+              "createdAt",
+              "updatedAt"
+            ]
+          }
+        ]
+      },
+      WorkflowInvocationResponse: {
+        type: "object",
+        properties: {
+          ok: {
+            type: "boolean"
+          },
+          invocation: {
+            $ref: "#/components/schemas/WorkflowInvocation"
+          }
+        },
+        required: [
+          "ok",
+          "invocation"
+        ]
+      },
+      WorkflowInvocationListResponse: {
+        type: "object",
+        properties: {
+          ok: {
+            type: "boolean"
+          },
+          invocations: {
+            type: "array",
+            items: {
+              $ref: "#/components/schemas/WorkflowInvocation"
+            }
+          }
+        },
+        required: [
+          "ok",
+          "invocations"
+        ]
+      },
+      WorkflowWorkItem: {
+        type: "object",
+        additionalProperties: true,
+        properties: {
+          id: {
+            type: "string"
+          },
+          routeKey: {
+            type: "string"
+          },
+          idempotencyKey: {
+            type: "string"
+          },
+          invocationId: {
+            type: "string"
+          },
+          sourceType: {
+            type: "string"
+          },
+          sourceRef: {
+            type: "string"
+          },
+          subjectRef: {
+            type: "string"
+          },
+          status: {
+            type: "string"
+          },
+          priority: {
+            type: "integer"
+          },
+          createdAt: {
+            type: "string"
+          },
+          updatedAt: {
+            type: "string"
+          }
+        },
+        required: [
+          "id",
+          "routeKey",
+          "idempotencyKey",
+          "invocationId",
+          "sourceType",
+          "sourceRef",
+          "subjectRef",
+          "status",
+          "priority"
+        ]
+      },
+      UpsertWorkflowWorkItemInput: {
+        type: "object",
+        properties: {
+          id: {
+            type: "string"
+          },
+          routeKey: {
+            type: "string"
+          },
+          idempotencyKey: {
+            type: "string"
+          },
+          invocationId: {
+            type: "string"
+          },
+          sourceType: {
+            type: "string"
+          },
+          sourceRef: {
+            type: "string"
+          },
+          subjectRef: {
+            type: "string"
+          },
+          projectKey: {
+            type: "string"
+          },
+          projectGroup: {
+            type: "string"
+          },
+          machineId: {
+            type: "string"
+          },
+          routeScope: {
+            type: "string"
+          },
+          priority: {
+            type: "integer"
+          },
+          status: {
+            type: "string",
+            enum: [
+              "queued",
+              "deferred"
+            ]
+          },
+          nextAttemptAt: {
+            type: "string"
+          },
+          lastReason: {
+            type: "string"
+          }
+        },
+        required: [
+          "routeKey",
+          "idempotencyKey",
+          "invocationId",
+          "sourceType",
+          "sourceRef",
+          "subjectRef"
+        ]
+      },
+      WorkflowWorkItemResponse: {
+        type: "object",
+        properties: {
+          ok: {
+            type: "boolean"
+          },
+          workItem: {
+            $ref: "#/components/schemas/WorkflowWorkItem"
+          }
+        },
+        required: [
+          "ok",
+          "workItem"
+        ]
+      },
+      WorkflowWorkItemListResponse: {
+        type: "object",
+        properties: {
+          ok: {
+            type: "boolean"
+          },
+          workItems: {
+            type: "array",
+            items: {
+              $ref: "#/components/schemas/WorkflowWorkItem"
+            }
+          }
+        },
+        required: [
+          "ok",
+          "workItems"
+        ]
+      },
+      ImportInput: {
+        type: "object",
+        description: "Batches of full rows to upsert by id. Any array may be omitted.",
+        properties: {
+          workflows: {
+            type: "array",
+            items: {
+              type: "object",
+              additionalProperties: true
+            }
+          },
+          loops: {
+            type: "array",
+            items: {
+              type: "object",
+              additionalProperties: true
             }
           },
           runs: {
@@ -1940,7 +2572,15 @@ var loops_default = {
           },
           replace: {
             type: "boolean",
-            description: "Update existing rows whose id matches (default false: existing rows are left unchanged)."
+            description: "Update existing rows whose id matches. Default safe imports may still archive/pause same-id workflows/loops when preserve flags are false."
+          },
+          preserveLoopScheduling: {
+            type: "boolean",
+            description: "Default false. When false, imported loops are written paused with nextRunAt and retryScheduledFor cleared so backfills never schedule immediately."
+          },
+          preserveWorkflowActivation: {
+            type: "boolean",
+            description: "Default false. When false, imported workflows are written archived, including same-id active rows, so backfills cannot activate workflow execution unless explicitly requested."
           }
         }
       },
@@ -2175,6 +2815,21 @@ async function handleV1Request(ctx) {
     return errorResponse(error);
   }
 }
+function safeImportedWorkflow(workflow, opts) {
+  if (opts.preserveWorkflowActivation)
+    return workflow;
+  return { ...workflow, status: "archived" };
+}
+function safeImportedLoop(loop, opts) {
+  if (opts.preserveLoopScheduling)
+    return loop;
+  return {
+    ...loop,
+    status: "paused",
+    nextRunAt: undefined,
+    retryScheduledFor: undefined
+  };
+}
 async function handleImportRequest(ctx, segments) {
   if (segments.length !== 0 || ctx.request.method !== "POST")
     return fail("not_found", 404);
@@ -2184,14 +2839,20 @@ async function handleImportRequest(ctx, segments) {
   const workflows = Array.isArray(body.workflows) ? body.workflows : [];
   const loops = Array.isArray(body.loops) ? body.loops : [];
   const runs = Array.isArray(body.runs) ? body.runs : [];
+  const preserveWorkflowActivation = body.preserveWorkflowActivation === true;
+  const preserveLoopScheduling = body.preserveLoopScheduling === true;
   const imported = { workflows: 0, loops: 0, runs: 0 };
   let skippedRunning = 0;
   for (const workflow of workflows) {
-    await storage.upsertMigrationWorkflow(workflow, { replace });
+    await storage.upsertMigrationWorkflow(safeImportedWorkflow(workflow, { preserveWorkflowActivation }), {
+      replace: replace || !preserveWorkflowActivation
+    });
     imported.workflows += 1;
   }
   for (const loop of loops) {
-    await storage.upsertMigrationLoop(loop, { replace });
+    await storage.upsertMigrationLoop(safeImportedLoop(loop, { preserveLoopScheduling }), {
+      replace: replace || !preserveLoopScheduling
+    });
     imported.loops += 1;
   }
   for (const run of runs) {
@@ -2350,6 +3011,10 @@ async function handleWorkItemsRequest(ctx, segments) {
     });
     return ok({ workItems: items.map(publicWorkflowWorkItem) });
   }
+  if (segments.length === 0 && ctx.request.method === "POST") {
+    const body = await readJsonBody(ctx.request, ctx.bodyLimitBytes);
+    return ok({ workItem: publicWorkflowWorkItem(await storage.upsertWorkflowWorkItem(body)) }, { status: 201 });
+  }
   const id = segments[0];
   if (!id)
     return fail("not_found", 404);
@@ -2367,6 +3032,10 @@ async function handleInvocationsRequest(ctx, segments) {
     const invocations = await storage.listWorkflowInvocations({ limit: optionalLimit(ctx.url.searchParams.get("limit")) });
     return ok({ invocations: invocations.map(publicWorkflowInvocation) });
   }
+  if (segments.length === 0 && ctx.request.method === "POST") {
+    const body = await readJsonBody(ctx.request, ctx.bodyLimitBytes);
+    return ok({ invocation: publicWorkflowInvocation(await storage.createWorkflowInvocation(body)) }, { status: 201 });
+  }
   const id = segments[0];
   if (!id)
     return fail("not_found", 404);