@hasna/loops 0.3.11 → 0.3.13

package/dist/sdk/index.js

@@ -368,6 +368,35 @@ function validateTarget(value, label) {
       if (value.provider !== "codewith")
         throw new Error(`${label}.authProfile is currently supported only for provider codewith`);
     }
+    if (value.variant !== undefined)
+      assertString(value.variant, `${label}.variant`);
+    if (value.permissionMode !== undefined) {
+      assertString(value.permissionMode, `${label}.permissionMode`);
+      const permissionModes = ["default", "plan", "auto", "bypass"];
+      if (!permissionModes.includes(value.permissionMode)) {
+        throw new Error(`${label}.permissionMode must be one of ${permissionModes.join(", ")}`);
+      }
+      if (value.permissionMode === "plan" && !["claude", "cursor"].includes(value.provider)) {
+        throw new Error(`${label}.permissionMode plan is currently supported only for provider claude or cursor`);
+      }
+      if (value.permissionMode === "auto" && value.provider !== "claude") {
+        throw new Error(`${label}.permissionMode auto is currently supported only for provider claude`);
+      }
+    }
+    if (value.sandbox !== undefined) {
+      assertString(value.sandbox, `${label}.sandbox`);
+      const codexLike = ["read-only", "workspace-write", "danger-full-access"];
+      const cursorLike = ["enabled", "disabled"];
+      if (["codewith", "codex"].includes(value.provider)) {
+        if (!codexLike.includes(value.sandbox))
+          throw new Error(`${label}.sandbox must be one of ${codexLike.join(", ")}`);
+      } else if (value.provider === "cursor") {
+        if (!cursorLike.includes(value.sandbox))
+          throw new Error(`${label}.sandbox must be one of ${cursorLike.join(", ")}`);
+      } else {
+        throw new Error(`${label}.sandbox is currently supported only for provider codewith, codex, or cursor`);
+      }
+    }
     return value;
   }
   throw new Error(`${label}.type must be command or agent`);
@@ -2353,7 +2382,7 @@ function providerCommand(provider) {
     case "claude":
       return "claude";
     case "cursor":
-      return "cursor-agent";
+      return "sh";
     case "codewith":
       return "codewith";
     case "aicopilot":
@@ -2364,22 +2393,107 @@ function providerCommand(provider) {
       return "codex";
   }
 }
+function codewithLikeSandbox(target) {
+  const sandbox = target.sandbox ?? (target.permissionMode === "bypass" ? "danger-full-access" : "workspace-write");
+  if (sandbox !== "read-only" && sandbox !== "workspace-write" && sandbox !== "danger-full-access") {
+    throw new Error(`${target.provider} sandbox must be read-only, workspace-write, or danger-full-access`);
+  }
+  return sandbox;
+}
+function configStringValue(value) {
+  return JSON.stringify(value);
+}
+function assertStringOption(value, label) {
+  if (value !== undefined && typeof value !== "string")
+    throw new Error(`${label} must be a string`);
+}
+function assertSupportedAgentOptions(target) {
+  assertStringOption(target.variant, `${target.provider}.variant`);
+  assertStringOption(target.model, `${target.provider}.model`);
+  assertStringOption(target.agent, `${target.provider}.agent`);
+  assertStringOption(target.authProfile, `${target.provider}.authProfile`);
+  if (target.authProfile !== undefined && target.provider !== "codewith") {
+    throw new Error(`${target.provider}.authProfile is supported only for codewith`);
+  }
+  if (target.permissionMode && !["default", "plan", "auto", "bypass"].includes(target.permissionMode)) {
+    throw new Error(`${target.provider}.permissionMode must be default, plan, auto, or bypass`);
+  }
+  if (target.sandbox && !["read-only", "workspace-write", "danger-full-access", "enabled", "disabled"].includes(target.sandbox)) {
+    throw new Error(`${target.provider}.sandbox is not supported: ${target.sandbox}`);
+  }
+  if (["codewith", "codex"].includes(target.provider)) {
+    if (target.permissionMode && !["default", "bypass"].includes(target.permissionMode)) {
+      throw new Error(`${target.provider}.permissionMode supports only default or bypass`);
+    }
+    if (target.sandbox)
+      codewithLikeSandbox(target);
+    return;
+  }
+  if (target.provider === "claude") {
+    if (target.sandbox !== undefined)
+      throw new Error("claude.sandbox is not supported");
+    return;
+  }
+  if (target.provider === "cursor") {
+    if (target.permissionMode === "auto")
+      throw new Error("cursor.permissionMode auto is not supported; use provider-specific extraArgs for Cursor auto-review");
+    if (target.sandbox !== undefined && target.sandbox !== "enabled" && target.sandbox !== "disabled") {
+      throw new Error("cursor.sandbox must be enabled or disabled");
+    }
+    return;
+  }
+  if (target.permissionMode && !["default", "bypass"].includes(target.permissionMode)) {
+    throw new Error(`${target.provider}.permissionMode supports only default or bypass`);
+  }
+  if (target.sandbox !== undefined)
+    throw new Error(`${target.provider}.sandbox is not supported`);
+}
 function agentArgs(target) {
+  assertSupportedAgentOptions(target);
   const isolation = target.configIsolation ?? "safe";
+  const permissionMode = target.permissionMode ?? "default";
   const args = [];
   switch (target.provider) {
     case "claude":
       if (isolation === "safe")
         args.push("--safe-mode", "--setting-sources", "local", "--no-session-persistence");
+      if (permissionMode !== "default") {
+        const mode = permissionMode === "bypass" ? "bypassPermissions" : permissionMode === "plan" || permissionMode === "auto" ? permissionMode : undefined;
+        if (mode)
+          args.push("--permission-mode", mode);
+      }
       args.push("-p", "--output-format", "json");
       if (target.model)
         args.push("--model", target.model);
+      if (target.variant)
+        args.push("--effort", target.variant);
       if (target.agent)
         args.push("--agent", target.agent);
       args.push(...target.extraArgs ?? []);
       return args;
     case "cursor":
-      args.push("-p");
+      args.push("-c", [
+        "set -eu",
+        "if command -v cursor >/dev/null 2>&1; then",
+        '  exec cursor agent "$@"',
+        "elif command -v agent >/dev/null 2>&1; then",
+        '  exec agent "$@"',
+        "else",
+        "  echo 'Executable not found in PATH: cursor agent or agent' >&2",
+        "  exit 127",
+        "fi"
+      ].join(`
+`), "openloops-cursor", "-p");
+      if (permissionMode === "plan")
+        args.push("--mode", "plan");
+      if (permissionMode === "bypass")
+        args.push("--force");
+      const cursorSandbox = target.sandbox ?? (isolation === "safe" ? "enabled" : undefined);
+      if (cursorSandbox) {
+        if (cursorSandbox !== "enabled" && cursorSandbox !== "disabled")
+          throw new Error("cursor sandbox must be enabled or disabled");
+        args.push("--sandbox", cursorSandbox);
+      }
       if (target.model)
         args.push("--model", target.model);
       if (target.agent)
@@ -2387,7 +2501,10 @@ function agentArgs(target) {
       args.push(...target.extraArgs ?? []);
       return args;
     case "codewith":
-      args.push(...target.authProfile ? ["--auth-profile", target.authProfile] : [], "--ask-for-approval", "never", "exec", "--json", "--ephemeral", "--sandbox", "workspace-write", "--skip-git-repo-check");
+      args.push(...target.authProfile ? ["--auth-profile", target.authProfile] : []);
+      if (target.variant)
+        args.push("-c", `model_reasoning_effort=${configStringValue(target.variant)}`);
+      args.push("--ask-for-approval", "never", "exec", "--json", "--ephemeral", "--sandbox", codewithLikeSandbox(target), "--skip-git-repo-check");
       if (isolation === "safe")
         args.push("--ignore-rules");
       if (target.cwd)
@@ -2399,7 +2516,9 @@ function agentArgs(target) {
       args.push(...target.extraArgs ?? []);
       return args;
     case "codex":
-      args.push("exec", "--json", "--ephemeral", "--ask-for-approval", "never", "--sandbox", "workspace-write");
+      if (target.variant)
+        args.push("-c", `model_reasoning_effort=${configStringValue(target.variant)}`);
+      args.push("exec", "--json", "--ephemeral", "--ask-for-approval", "never", "--sandbox", codewithLikeSandbox(target));
       if (isolation === "safe")
         args.push("--ignore-rules");
       if (target.cwd)
@@ -2412,10 +2531,14 @@ function agentArgs(target) {
       args.push("run", "--format", "json");
       if (isolation === "safe")
         args.push("--pure");
+      if (permissionMode === "bypass")
+        args.push("--dangerously-skip-permissions");
       if (target.cwd)
         args.push("--dir", target.cwd);
       if (target.model)
         args.push("--model", target.model);
+      if (target.variant)
+        args.push("--variant", target.variant);
       if (target.agent)
         args.push("--agent", target.agent);
       args.push(...target.extraArgs ?? []);
@@ -2424,10 +2547,14 @@ function agentArgs(target) {
       args.push("run", "--format", "json");
       if (isolation === "safe")
         args.push("--pure");
+      if (permissionMode === "bypass")
+        args.push("--dangerously-skip-permissions");
       if (target.cwd)
         args.push("--dir", target.cwd);
       if (target.model)
         args.push("--model", target.model);
+      if (target.variant)
+        args.push("--variant", target.variant);
       if (target.agent)
         args.push("--agent", target.agent);
       args.push(...target.extraArgs ?? []);
@@ -2456,6 +2583,7 @@ function commandSpec(target) {
     timeoutMs: agentTarget.timeoutMs ?? DEFAULT_TIMEOUT_MS,
     account: agentTarget.account,
     accountTool: agentTarget.account?.tool ?? accountToolForProvider(agentTarget.provider),
+    preflightAnyOf: agentTarget.provider === "cursor" ? ["cursor", "agent"] : undefined,
     stdin: agentTarget.prompt
   };
 }
@@ -2523,11 +2651,15 @@ function remoteScript(spec, metadata) {
 `;
 }
 function remotePreflightScript(spec, metadata) {
-  return [
+  const lines = [
     ...remoteBootstrapLines(spec, metadata),
     "command -v bash >/dev/null 2>&1",
     `command -v ${shellQuote(spec.shell ? "sh" : spec.command)} >/dev/null 2>&1`
-  ].join(`
+  ];
+  if (spec.preflightAnyOf?.length) {
+    lines.push(`if ! ${spec.preflightAnyOf.map((command) => `command -v ${shellQuote(command)} >/dev/null 2>&1`).join(" && ! ")}; then`, `  echo 'none of required executables found: ${spec.preflightAnyOf.join(", ")}' >&2`, "  exit 127", "fi");
+  }
+  return lines.join(`
 `);
 }
 function transportEnv(opts) {
@@ -2680,6 +2812,9 @@ function preflightTarget(target, metadata = {}, opts = {}) {
   if (!spec.shell && !executableExists(spec.command, env)) {
     throw new Error(commandNotFoundMessage(spec.command, env));
   }
+  if (spec.preflightAnyOf?.length && !spec.preflightAnyOf.some((command) => executableExists(command, env))) {
+    throw new Error(`none of required executables found: ${spec.preflightAnyOf.join(", ")}`);
+  }
   return {
     command: spec.command,
     accountProfile: spec.account?.profile,
@@ -2710,6 +2845,17 @@ async function executeTarget(target, metadata = {}, opts = {}) {
       durationMs: 0
     };
   }
+  if (spec.preflightAnyOf?.length && !spec.preflightAnyOf.some((command) => executableExists(command, env))) {
+    return {
+      status: "failed",
+      stdout,
+      stderr,
+      error: `none of required executables found: ${spec.preflightAnyOf.join(", ")}`,
+      startedAt,
+      finishedAt: nowIso(),
+      durationMs: 0
+    };
+  }
   const child = spawn(spec.command, spec.args, {
     cwd: spec.cwd,
     env,

package/dist/types.d.ts

@@ -52,17 +52,22 @@ export interface CommandTarget {
 }
 export type AgentProvider = "claude" | "cursor" | "codewith" | "aicopilot" | "opencode" | "codex";
 export type AgentConfigIsolation = "safe" | "none";
+export type AgentPermissionMode = "default" | "plan" | "auto" | "bypass";
+export type AgentSandbox = "read-only" | "workspace-write" | "danger-full-access" | "enabled" | "disabled";
 export interface AgentTarget {
     type: "agent";
     provider: AgentProvider;
     prompt: string;
     cwd?: string;
     model?: string;
+    variant?: string;
     agent?: string;
     authProfile?: string;
     extraArgs?: string[];
     timeoutMs?: number;
     configIsolation?: AgentConfigIsolation;
+    permissionMode?: AgentPermissionMode;
+    sandbox?: AgentSandbox;
     account?: AccountRef;
 }
 export interface WorkflowTarget {
@@ -105,6 +110,20 @@ export interface CreateWorkflowInput {
     steps: WorkflowStep[];
     version?: number;
 }
+export type LoopTemplateKind = "workflow" | "loop";
+export interface LoopTemplateVariable {
+    name: string;
+    description?: string;
+    required?: boolean;
+    default?: string;
+}
+export interface LoopTemplateSummary {
+    id: string;
+    name: string;
+    description: string;
+    kind: LoopTemplateKind;
+    variables: LoopTemplateVariable[];
+}
 export interface WorkflowRun {
     id: string;
     workflowId: string;

package/docs/USAGE.md

@@ -5,7 +5,7 @@ OpenLoops is a local CLI and daemon for persistent loops and workflows: schedule
 It supports deterministic command loops, JSON-defined workflows, and guarded CLI adapters for headless coding agents:
 
 - `claude`
-- `cursor-agent`
+- `cursor agent` or `agent`
 - `codewith exec`
 - `aicopilot run`
 - `opencode run`
@@ -78,6 +78,7 @@ loops create agent supply-chain-watch \
   --provider codewith \
   --every 15m \
   --cwd /path/to/repo \
+  --sandbox danger-full-access \
   --prompt "Check for suspicious dependency or supply-chain changes. Report only concrete findings."
 ```
 
@@ -89,6 +90,7 @@ loops create agent supply-chain-watch \
   --auth-profile account001 \
   --every 15m \
   --cwd /path/to/repo \
+  --sandbox danger-full-access \
   --prompt "Check for suspicious dependency or supply-chain changes. Report only concrete findings."
 ```
 
@@ -160,6 +162,63 @@ Use `shell: true` only when you intentionally want shell parsing:
 { "type": "command", "command": "git status --short", "shell": true }
 ```
 
+## Templates And Task Events
+
+Built-in templates turn common orchestration flows into reusable workflow JSON.
+`todos-task-worker-verifier` performs one todos task and then verifies it.
+`event-worker-verifier` handles any Hasna event envelope and then verifies the
+handling.
+
+```bash
+loops templates list
+loops templates render todos-task-worker-verifier \
+  --var taskId=<task-id> \
+  --var taskTitle="Fix parser" \
+  --var projectPath=/path/to/repo \
+  --var provider=codewith \
+  --var authProfile=account005 \
+  --var sandbox=danger-full-access
+loops templates create-workflow todos-task-worker-verifier \
+  --var taskId=<task-id> \
+  --var projectPath=/path/to/repo
+loops templates render event-worker-verifier \
+  --var eventId=<event-id> \
+  --var eventType=knowledge.record.created \
+  --var eventSource=knowledge \
+  --var eventJson='{"id":"<event-id>"}' \
+  --var projectPath=/path/to/repo
+```
+
+For event-driven task automation, `loops events handle todos-task` reads a
+Hasna event envelope from stdin or `HASNA_EVENT_JSON`, renders the template, and
+schedules a deduped one-shot workflow loop:
+
+```bash
+cat task-created-event.json | loops events handle todos-task \
+  --provider codewith \
+  --auth-profile account005 \
+  --permission-mode bypass \
+  --sandbox danger-full-access
+```
+
+For other Hasna apps that expose `@hasna/events` webhooks, use the generic
+handler:
+
+```bash
+cat event.json | loops events handle generic \
+  --provider codewith \
+  --auth-profile account005 \
+  --permission-mode bypass \
+  --sandbox danger-full-access \
+  --project-path /path/to/repo
+```
+
+This is the intended deterministic-to-agentic path: a producer creates a todos
+task, `@hasna/events` delivers `task.created`, OpenLoops creates a worker and a
+verifier workflow, and the workflow updates todos with evidence. Use
+`--dry-run` to inspect the rendered workflow and loop input without storing
+anything.
+
 ## Transcript-Driven Loops
 
 OpenLoops can turn long-form media or meeting transcripts into recurring workflow work when paired with `iapp-transcriber`. The template at `docs/workflows/transcript-feedback-to-loops.json` transcribes an authorized media URL, asks an agent to extract recurring loop candidates, authors workflow specs, and validates generated workflows before scheduling. Copy it into the target repo, replace `/path/to/repo` with that repo's absolute path, and provide `TRANSCRIBER_SOURCE_URL` through the runner environment or a private, uncommitted workflow copy before storing or scheduling it. Do not commit private or signed media URLs.
@@ -240,11 +299,14 @@ The adapters intentionally use provider command surfaces instead of pretending e
 - Claude uses `claude -p --output-format json` and safe-mode/local setting sources by default.
 - Codewith uses `codewith --ask-for-approval never exec --json --ephemeral --skip-git-repo-check`.
 - 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.
+- Cursor is CLI-first for now via `cursor agent -p`, with `agent -p` as the fallback launcher on machines that expose the standalone Cursor Agent binary; treat output as less stable until a stronger public SDK contract is selected.
 - Codex uses `codex exec --json --ephemeral --ask-for-approval never`.
 - Agent prompts are sent through child stdin instead of argv so prompt bodies do not appear in process listings.
 - 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.
 - `--auth-profile` and step `authProfile` are provider-native auth selectors. They currently apply to Codewith and are passed to Codewith as `--auth-profile <name>` before `exec`; they do not call OpenAccounts.
+- `--sandbox` maps to provider-native sandbox flags. Codewith/Codex accept `read-only`, `workspace-write`, or `danger-full-access`; Cursor accepts `enabled` or `disabled`.
+- `--permission-mode` maps `plan`, `auto`, and `bypass` where the provider supports it. Claude uses native permission modes, Cursor maps bypass to `--force`, and OpenCode/AICopilot map bypass to `--dangerously-skip-permissions`.
+- `--variant` is provider-specific reasoning/model effort. Claude maps it to `--effort`, Codewith/Codex map it to `model_reasoning_effort`, and OpenCode/AICopilot pass `--variant`.
 - Daemon and scheduled runs prepend common user executable directories such as `~/.local/bin` and `~/.bun/bin` before resolving provider CLIs.
 
 For production loops that can mutate repos, prefer disposable worktrees and explicit prompts that name allowed write scope.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hasna/loops",
-  "version": "0.3.11",
+  "version": "0.3.13",
   "description": "Persistent local loop and workflow runner for deterministic commands and headless AI coding agents",
   "type": "module",
   "main": "dist/index.js",
@@ -64,6 +64,7 @@
     "bun": ">=1.0.0"
   },
   "dependencies": {
+    "@hasna/events": "^0.1.8",
     "@hasna/machines": "0.0.49",
     "@openrouter/ai-sdk-provider": "2.9.1",
     "ai": "6.0.204",