@hasna/loops 0.1.0 → 0.3.0

package/dist/types.d.ts

@@ -3,6 +3,10 @@ export type RunStatus = "running" | "succeeded" | "failed" | "timed_out" | "aban
 export type CatchUpPolicy = "none" | "latest" | "all";
 export type OverlapPolicy = "skip" | "allow";
 export type IntervalAnchor = "fixed_rate" | "fixed_delay";
+export interface AccountRef {
+    profile: string;
+    tool?: string;
+}
 export interface OnceSchedule {
     type: "once";
     at: string;
@@ -29,8 +33,9 @@ export interface CommandTarget {
     shell?: boolean;
     env?: Record<string, string>;
     timeoutMs?: number;
+    account?: AccountRef;
 }
-export type AgentProvider = "claude" | "cursor" | "codewith" | "aicopilot" | "opencode";
+export type AgentProvider = "claude" | "cursor" | "codewith" | "aicopilot" | "opencode" | "codex";
 export type AgentConfigIsolation = "safe" | "none";
 export interface AgentTarget {
     type: "agent";
@@ -42,8 +47,89 @@ export interface AgentTarget {
     extraArgs?: string[];
     timeoutMs?: number;
     configIsolation?: AgentConfigIsolation;
+    account?: AccountRef;
+}
+export interface WorkflowTarget {
+    type: "workflow";
+    workflowId: string;
+    input?: Record<string, string>;
+    timeoutMs?: number;
+}
+export type ExecutableTarget = CommandTarget | AgentTarget;
+export type LoopTarget = ExecutableTarget | WorkflowTarget;
+export type WorkflowStatus = "active" | "archived";
+export type WorkflowRunStatus = "running" | "succeeded" | "failed" | "timed_out" | "cancelled";
+export type WorkflowStepRunStatus = "pending" | "running" | "succeeded" | "failed" | "timed_out" | "skipped" | "cancelled";
+export interface WorkflowStep {
+    id: string;
+    name?: string;
+    description?: string;
+    target: ExecutableTarget;
+    dependsOn?: string[];
+    continueOnFailure?: boolean;
+    timeoutMs?: number;
+    account?: AccountRef;
+}
+export interface WorkflowSpec {
+    id: string;
+    name: string;
+    description?: string;
+    version: number;
+    status: WorkflowStatus;
+    steps: WorkflowStep[];
+    createdAt: string;
+    updatedAt: string;
+}
+export interface CreateWorkflowInput {
+    name: string;
+    description?: string;
+    steps: WorkflowStep[];
+    version?: number;
+}
+export interface WorkflowRun {
+    id: string;
+    workflowId: string;
+    workflowName: string;
+    loopId?: string;
+    loopRunId?: string;
+    scheduledFor?: string;
+    idempotencyKey?: string;
+    status: WorkflowRunStatus;
+    startedAt?: string;
+    finishedAt?: string;
+    durationMs?: number;
+    error?: string;
+    createdAt: string;
+    updatedAt: string;
+}
+export interface WorkflowStepRun {
+    id: string;
+    workflowRunId: string;
+    stepId: string;
+    sequence: number;
+    status: WorkflowStepRunStatus;
+    startedAt?: string;
+    finishedAt?: string;
+    exitCode?: number;
+    pid?: number;
+    durationMs?: number;
+    stdout?: string;
+    stderr?: string;
+    error?: string;
+    accountProfile?: string;
+    accountTool?: string;
+    createdAt: string;
+    updatedAt: string;
+}
+export interface WorkflowEvent {
+    id: string;
+    workflowRunId: string;
+    sequence: number;
+    eventType: string;
+    stepId?: string;
+    payload?: Record<string, unknown>;
+    createdAt: string;
 }
-export type LoopTarget = CommandTarget | AgentTarget;
 export interface Loop {
     id: string;
     name: string;

package/docs/USAGE.md

@@ -1,14 +1,15 @@
-# OpenLoops Usage
+# OpenLoops
 
-OpenLoops is a local CLI and daemon for persistent loops: scheduled or recurring work that survives process restarts and records every run.
+OpenLoops is a local CLI and daemon for persistent loops and workflows: scheduled or recurring work that survives process restarts and records every run.
 
-It supports deterministic command loops today and guarded CLI adapters for headless coding agents:
+It supports deterministic command loops, JSON-defined workflows, and guarded CLI adapters for headless coding agents:
 
 - `claude`
 - `cursor-agent`
 - `codewith exec`
 - `aicopilot run`
 - `opencode run`
+- `codex exec`
 
 ## Install
 
@@ -53,6 +54,18 @@ loops create agent morning-check \
   --prompt "Check whether this repo is healthy and summarize required action."
 ```
 
+Run a Claude loop with an isolated OpenAccounts profile:
+
+```bash
+loops create agent morning-check \
+  --provider claude \
+  --account work \
+  --account-tool claude \
+  --cron "0 8 * * *" \
+  --cwd /path/to/repo \
+  --prompt "Check whether this repo is healthy and summarize required action."
+```
+
 Run a Codewith loop every 15 minutes:
 
 ```bash
@@ -63,6 +76,74 @@ loops create agent supply-chain-watch \
   --prompt "Check for suspicious dependency or supply-chain changes. Report only concrete findings."
 ```
 
+For `codewith` and `aicopilot` account isolation, register matching OpenAccounts tools first if they are not built in on the machine:
+
+```bash
+accounts tools add codewith --label "Codewith" --env-var CODEWITH_HOME --bin codewith
+accounts tools add aicopilot --label "AI Copilot" --env-var AICOPILOT_CONFIG_DIR --bin aicopilot
+```
+
+## Workflows
+
+Create a workflow JSON file:
+
+```json
+{
+  "name": "repo-morning",
+  "steps": [
+    {
+      "id": "status",
+      "target": {
+        "type": "command",
+        "command": "git",
+        "args": ["status", "--short"],
+        "cwd": "/path/to/repo"
+      }
+    },
+    {
+      "id": "review",
+      "dependsOn": ["status"],
+      "target": {
+        "type": "agent",
+        "provider": "codex",
+        "account": { "profile": "work", "tool": "codex" },
+        "cwd": "/path/to/repo",
+        "prompt": "Review the repository status and summarize concrete next actions."
+      }
+    }
+  ]
+}
+```
+
+Save, run, inspect, and schedule it:
+
+```bash
+loops workflows validate repo-morning.json
+loops workflows validate repo-morning.json --preflight
+loops workflows create repo-morning.json
+loops workflows run repo-morning --show-output
+loops workflows runs repo-morning
+loops workflows inspect <workflow-run-id>
+loops workflows events <workflow-run-id>
+loops workflows cancel <workflow-run-id> --reason "no longer needed"
+loops workflows recover <workflow-run-id>
+loops create workflow repo-morning-loop --workflow repo-morning --cron "0 8 * * *"
+```
+
+Workflow specs are stored separately from loops. A loop can schedule a workflow, but workflow runs and step runs have their own durable rows and events. Steps run in dependency order and a scheduled workflow run is idempotent per loop slot.
+
+For command steps, `command` is the executable when `shell` is not true. Put flags in `args`:
+
+```json
+{ "type": "command", "command": "git", "args": ["status", "--short"] }
+```
+
+Use `shell: true` only when you intentionally want shell parsing:
+
+```json
+{ "type": "command", "command": "git status --short", "shell": true }
+```
+
 ## Manage
 
 ```bash
@@ -85,6 +166,7 @@ loops daemon start
 loops daemon status
 loops daemon logs
 loops daemon stop
+loops doctor
 ```
 
 Run in the foreground for supervised environments:
@@ -97,9 +179,10 @@ Install startup integration:
 
 ```bash
 loops daemon install
+loops daemon install --enable
 ```
 
-On Linux this writes a user systemd service. On macOS it writes a LaunchAgent plist. The command prints the exact enable/load commands to run.
+On Linux this writes a user systemd service. On macOS it writes a LaunchAgent plist. The command prints the exact enable/load commands to run. `--enable` runs the user-service enable/start command when supported.
 
 ## Scheduling Contract
 
@@ -123,5 +206,7 @@ The adapters intentionally use provider command surfaces instead of pretending e
 - Codewith uses `codewith exec --json --ephemeral --ask-for-approval never`.
 - AI Copilot and OpenCode use `run --format json --pure`.
 - Cursor is CLI-first for now via `cursor-agent -p`; treat output as less stable until a stronger public SDK contract is selected.
+- Codex uses `codex exec --json --ephemeral --ask-for-approval never`.
+- When `--account` or a step `account` is set, OpenLoops resolves `accounts env <profile> --tool <tool>` before spawning the target, strips inherited tool home/API-key variables, and applies the selected profile only to that process. Missing account profiles fail before the provider binary receives the prompt.
 
 For production loops that can mutate repos, prefer disposable worktrees and explicit prompts that name allowed write scope.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@hasna/loops",
-  "version": "0.1.0",
-  "description": "Persistent local loop runner for deterministic commands and headless AI coding agents",
+  "version": "0.3.0",
+  "description": "Persistent local loop and workflow runner for deterministic commands and headless AI coding agents",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",