@hasna/loops 0.3.59 → 0.3.60

package/dist/sdk/index.js

@@ -356,6 +356,20 @@ function optionalStringArray(value, label) {
   }).filter(Boolean);
   return values.length ? values : undefined;
 }
+var UNSAFE_CODEWITH_DURABLE_EXTRA_ARGS = new Set([
+  "e",
+  "exec",
+  "agent",
+  "start",
+  "--ephemeral",
+  "--ignore-rules",
+  "--skip-git-repo-check",
+  "--json",
+  "--output-last-message",
+  "-o",
+  "--output-schema",
+  "--dangerously-bypass-approvals-and-sandbox"
+]);
 function optionalAccountRef(value, label) {
   if (value === undefined)
     return;
@@ -470,6 +484,15 @@ function validateTarget(value, label, opts) {
       throw new Error(`${label}.variant is not supported for provider cursor`);
     if (value.provider === "codex" && value.agent !== undefined)
       throw new Error(`${label}.agent is not supported for provider codex`);
+    if (value.provider === "codewith" && value.agent !== undefined) {
+      throw new Error(`${label}.agent is not supported for provider codewith durable background-agent execution`);
+    }
+    const extraArgs = optionalStringArray(value.extraArgs, `${label}.extraArgs`);
+    if (value.provider === "codewith") {
+      const unsafe = extraArgs?.find((arg) => UNSAFE_CODEWITH_DURABLE_EXTRA_ARGS.has(arg));
+      if (unsafe)
+        throw new Error(`${label}.extraArgs cannot include ${unsafe}; codewith agent steps use durable agent start, not exec/ephemeral flags`);
+    }
     optionalStringArray(value.addDirs, `${label}.addDirs`);
     if (Array.isArray(value.addDirs) && value.addDirs.length > 0 && !["codewith", "codex"].includes(value.provider)) {
       throw new Error(`${label}.addDirs is currently supported only for provider codewith or codex`);
@@ -545,7 +568,9 @@ function validateTarget(value, label, opts) {
       if (value.routing.eventSource !== undefined)
         assertString(value.routing.eventSource, `${label}.routing.eventSource`);
     }
-    const target = { ...value };
+    const target = { ...value, extraArgs };
+    if (!extraArgs)
+      delete target.extraArgs;
     delete target.promptFile;
     delete target.promptSource;
     return { ...target, ...promptFields };
@@ -3478,6 +3503,9 @@ function appendBounded(current, chunk, maxBytes) {
   return `[truncated ${overflow} bytes]
 ${next.slice(-maxBytes)}`;
 }
+function appendBoundedText(current, chunk, maxBytes) {
+  return appendBounded(current, Buffer.from(chunk, "utf8"), maxBytes);
+}
 function killProcessGroup(pid) {
   try {
     process.kill(-pid, "SIGTERM");
@@ -3525,6 +3553,21 @@ function metadataEnv(metadata) {
     env.LOOPS_GOAL_NODE_KEY = metadata.goalNodeKey;
   return env;
 }
+function codewithAgentIdempotencyKey(metadata) {
+  const parts = [
+    "openloops",
+    metadata.workflowRunId ? `workflow-run:${metadata.workflowRunId}` : undefined,
+    metadata.workflowStepId ? `step:${metadata.workflowStepId}` : undefined,
+    metadata.runId ? `loop-run:${metadata.runId}` : undefined,
+    metadata.loopId ? `loop:${metadata.loopId}` : undefined,
+    metadata.scheduledFor ? `scheduled:${metadata.scheduledFor}` : undefined,
+    metadata.goalId ? `goal:${metadata.goalId}` : undefined,
+    metadata.goalNodeKey ? `node:${metadata.goalNodeKey}` : undefined
+  ].filter(Boolean);
+  if (parts.length > 1)
+    return parts.join(":");
+  return `openloops:adhoc:${randomBytes2(16).toString("hex")}`;
+}
 function allowlistEnv(allowlist) {
   const env = {};
   if (allowlist?.tools?.length)
@@ -3561,6 +3604,20 @@ function codewithLikeSandbox(target) {
 function configStringValue(value) {
   return JSON.stringify(value);
 }
+var UNSAFE_CODEWITH_DURABLE_EXTRA_ARGS2 = new Set([
+  "e",
+  "exec",
+  "agent",
+  "start",
+  "--ephemeral",
+  "--ignore-rules",
+  "--skip-git-repo-check",
+  "--json",
+  "--output-last-message",
+  "-o",
+  "--output-schema",
+  "--dangerously-bypass-approvals-and-sandbox"
+]);
 function assertStringOption(value, label) {
   if (value !== undefined && typeof value !== "string")
     throw new Error(`${label} must be a string`);
@@ -3591,6 +3648,14 @@ function assertSupportedAgentOptions(target) {
   }
   if (target.provider === "codex" && target.agent !== undefined)
     throw new Error("codex.agent is not supported");
+  if (target.provider === "codewith" && target.agent !== undefined) {
+    throw new Error("codewith.agent is not supported by the durable background-agent adapter");
+  }
+  if (target.provider === "codewith") {
+    const unsafe = target.extraArgs?.find((arg) => UNSAFE_CODEWITH_DURABLE_EXTRA_ARGS2.has(arg));
+    if (unsafe)
+      throw new Error(`codewith.extraArgs cannot include ${unsafe}; durable agent steps use codewith agent start, not exec/ephemeral flags`);
+  }
   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`);
@@ -3674,18 +3739,18 @@ function agentArgs(target) {
       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");
+      args.push("--ask-for-approval", "never", "--sandbox", codewithLikeSandbox(target));
       if (target.cwd)
         args.push("--cd", target.cwd);
       for (const dir of target.addDirs ?? [])
         args.push("--add-dir", dir);
       if (target.model)
         args.push("--model", target.model);
-      if (target.agent)
-        args.push("--agent", target.agent);
       args.push(...target.extraArgs ?? []);
+      args.push("agent", "start");
+      if (target.cwd)
+        args.push("--cwd", target.cwd);
+      args.push(target.prompt);
       return args;
     case "codex":
       if (target.variant)
@@ -3761,8 +3826,9 @@ function commandSpec(target) {
     accountTool: agentTarget.account?.tool ?? accountToolForProvider(agentTarget.provider),
     nativeAuthProfile: agentTarget.authProfile ? { provider: agentTarget.provider, profile: agentTarget.authProfile } : undefined,
     preflightAnyOf: agentTarget.provider === "cursor" ? ["agent"] : undefined,
-    stdin: agentTarget.prompt,
-    allowlist: agentTarget.allowlist
+    stdin: agentTarget.provider === "codewith" ? undefined : agentTarget.prompt,
+    allowlist: agentTarget.allowlist,
+    codewithDurableAgent: agentTarget.provider === "codewith" ? { target: agentTarget } : undefined
   };
 }
 function executionEnv(spec, metadata, opts) {
@@ -3882,6 +3948,238 @@ function preflightNativeAuthProfile(spec, env) {
     throw new Error(`codewith auth profile not found: ${spec.nativeAuthProfile.profile}`);
   }
 }
+function codewithAgentStartArgs(target, idempotencyKey) {
+  const args = agentArgs(target);
+  const startIndex = args.findIndex((arg, index) => arg === "start" && args[index - 1] === "agent");
+  if (startIndex === -1)
+    throw new Error("internal error: codewith durable agent args missing agent start");
+  args.splice(startIndex + 1, 0, "--idempotency-key", idempotencyKey);
+  return args;
+}
+function codewithAgentControlArgs(target, command, agentId) {
+  return [
+    ...target.authProfile ? ["--auth-profile", target.authProfile] : [],
+    "agent",
+    command,
+    ...command === "logs" ? ["--limit", "20"] : [],
+    agentId
+  ];
+}
+function parseJsonOutput(stdout, label) {
+  try {
+    const value = JSON.parse(stdout || "{}");
+    if (!value || typeof value !== "object" || Array.isArray(value))
+      throw new Error("not an object");
+    return value;
+  } catch (error) {
+    throw new Error(`${label} did not return JSON${error instanceof Error ? `: ${error.message}` : ""}`);
+  }
+}
+function recordField(value, key) {
+  if (!value || typeof value !== "object" || Array.isArray(value))
+    return;
+  const field = value[key];
+  return field && typeof field === "object" && !Array.isArray(field) ? field : undefined;
+}
+function stringField(value, key) {
+  const field = value?.[key];
+  return typeof field === "string" ? field : undefined;
+}
+function numberField(value, key) {
+  const field = value?.[key];
+  return typeof field === "number" && Number.isFinite(field) ? field : undefined;
+}
+function codewithAgentStatus(readJson) {
+  return stringField(recordField(readJson, "agent"), "status") ?? stringField(recordField(readJson, "statusSnapshot"), "status");
+}
+function codewithAgentEvidence(startJson, readJson, logsJson) {
+  const agent = recordField(readJson, "agent") ?? recordField(startJson, "agent");
+  const statusSnapshot = recordField(readJson, "statusSnapshot");
+  const events = Array.isArray(logsJson?.data) ? logsJson.data.filter((event) => Boolean(event) && typeof event === "object" && !Array.isArray(event)).map((event) => ({
+    seq: numberField(event, "seq"),
+    eventType: stringField(event, "eventType"),
+    createdAt: numberField(event, "createdAt")
+  })) : undefined;
+  return JSON.stringify({
+    codewithAgent: {
+      agentId: stringField(agent, "agentId"),
+      status: stringField(agent, "status"),
+      desiredState: stringField(agent, "desiredState"),
+      statusReason: stringField(agent, "statusReason"),
+      threadId: stringField(agent, "threadId"),
+      rolloutPath: stringField(agent, "rolloutPath"),
+      pid: numberField(agent, "pid"),
+      exitCode: numberField(agent, "exitCode"),
+      created: typeof startJson.created === "boolean" ? startJson.created : undefined
+    },
+    statusSnapshot: statusSnapshot ? {
+      seq: numberField(statusSnapshot, "seq"),
+      status: stringField(statusSnapshot, "status"),
+      summary: stringField(statusSnapshot, "summary"),
+      pendingInteractionCount: numberField(statusSnapshot, "pendingInteractionCount"),
+      lastEventSeq: numberField(statusSnapshot, "lastEventSeq")
+    } : undefined,
+    events
+  }, null, 2);
+}
+function sleep(ms) {
+  return new Promise((resolve2) => setTimeout(resolve2, ms));
+}
+async function executeCodewithDurableAgent(spec, metadata, opts, env, startedAt) {
+  const target = spec.codewithDurableAgent?.target;
+  if (!target)
+    throw new Error("internal error: missing codewith durable target");
+  const maxOutputBytes = opts.maxOutputBytes ?? DEFAULT_MAX_OUTPUT_BYTES;
+  const idempotencyKey = codewithAgentIdempotencyKey(metadata);
+  const start = spawnSync2(spec.command, codewithAgentStartArgs(target, idempotencyKey), {
+    cwd: spec.cwd,
+    env,
+    encoding: "utf8",
+    stdio: ["ignore", "pipe", "pipe"],
+    timeout: 30000
+  });
+  let stderr = start.stderr || "";
+  if (start.error || (start.status ?? 1) !== 0) {
+    const finishedAt = nowIso();
+    return {
+      status: "failed",
+      exitCode: start.status ?? undefined,
+      stdout: start.stdout || "",
+      stderr,
+      error: start.error?.message ?? `codewith agent start exited with code ${start.status ?? "unknown"}`,
+      startedAt,
+      finishedAt,
+      durationMs: new Date(finishedAt).getTime() - new Date(startedAt).getTime()
+    };
+  }
+  let startJson;
+  try {
+    startJson = parseJsonOutput(start.stdout || "{}", "codewith agent start");
+  } catch (error) {
+    const finishedAt = nowIso();
+    return {
+      status: "failed",
+      stdout: start.stdout || "",
+      stderr,
+      error: error instanceof Error ? error.message : String(error),
+      startedAt,
+      finishedAt,
+      durationMs: new Date(finishedAt).getTime() - new Date(startedAt).getTime()
+    };
+  }
+  const agentId = stringField(recordField(startJson, "agent"), "agentId");
+  if (!agentId) {
+    const finishedAt = nowIso();
+    return {
+      status: "failed",
+      stdout: start.stdout || "",
+      stderr,
+      error: "codewith agent start did not return agent.agentId",
+      startedAt,
+      finishedAt,
+      durationMs: new Date(finishedAt).getTime() - new Date(startedAt).getTime()
+    };
+  }
+  const pollMs = Math.max(100, Number(opts.env?.LOOPS_CODEWITH_AGENT_POLL_MS ?? process.env.LOOPS_CODEWITH_AGENT_POLL_MS ?? 2000) || 2000);
+  let lastReadJson = startJson;
+  let lastLogsJson;
+  let stdout = "";
+  while (true) {
+    if (opts.signal?.aborted) {
+      spawnSync2(spec.command, codewithAgentControlArgs(target, "stop", agentId), { cwd: spec.cwd, env, stdio: "ignore", timeout: 15000 });
+      const finishedAt = nowIso();
+      return {
+        status: "failed",
+        stdout: appendBoundedText(stdout, codewithAgentEvidence(startJson, lastReadJson, lastLogsJson), maxOutputBytes),
+        stderr,
+        error: "cancelled",
+        startedAt,
+        finishedAt,
+        durationMs: new Date(finishedAt).getTime() - new Date(startedAt).getTime()
+      };
+    }
+    const read = spawnSync2(spec.command, codewithAgentControlArgs(target, "read", agentId), {
+      cwd: spec.cwd,
+      env,
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "pipe"],
+      timeout: 30000
+    });
+    stderr = appendBoundedText(stderr, read.stderr || "", maxOutputBytes);
+    if (read.error || (read.status ?? 1) !== 0) {
+      const finishedAt = nowIso();
+      return {
+        status: "failed",
+        exitCode: read.status ?? undefined,
+        stdout: appendBoundedText(stdout, codewithAgentEvidence(startJson, lastReadJson, lastLogsJson), maxOutputBytes),
+        stderr,
+        error: read.error?.message ?? `codewith agent read exited with code ${read.status ?? "unknown"}`,
+        startedAt,
+        finishedAt,
+        durationMs: new Date(finishedAt).getTime() - new Date(startedAt).getTime()
+      };
+    }
+    try {
+      lastReadJson = parseJsonOutput(read.stdout || "{}", "codewith agent read");
+    } catch (error) {
+      const finishedAt = nowIso();
+      return {
+        status: "failed",
+        stdout: appendBoundedText(stdout, read.stdout || "", maxOutputBytes),
+        stderr,
+        error: error instanceof Error ? error.message : String(error),
+        startedAt,
+        finishedAt,
+        durationMs: new Date(finishedAt).getTime() - new Date(startedAt).getTime()
+      };
+    }
+    const status = codewithAgentStatus(lastReadJson);
+    if (status === "completed" || status === "failed" || status === "cancelled") {
+      const logs = spawnSync2(spec.command, codewithAgentControlArgs(target, "logs", agentId), {
+        cwd: spec.cwd,
+        env,
+        encoding: "utf8",
+        stdio: ["ignore", "pipe", "pipe"],
+        timeout: 30000
+      });
+      if (!logs.error && (logs.status ?? 1) === 0) {
+        try {
+          lastLogsJson = parseJsonOutput(logs.stdout || "{}", "codewith agent logs");
+        } catch {
+          lastLogsJson = undefined;
+        }
+      } else {
+        stderr = appendBoundedText(stderr, logs.stderr || logs.error?.message || "", maxOutputBytes);
+      }
+      const finishedAt = nowIso();
+      const resultStatus = status === "completed" ? "succeeded" : "failed";
+      return {
+        status: resultStatus,
+        exitCode: resultStatus === "succeeded" ? 0 : 1,
+        stdout: appendBoundedText(stdout, codewithAgentEvidence(startJson, lastReadJson, lastLogsJson), maxOutputBytes),
+        stderr,
+        error: resultStatus === "succeeded" ? undefined : stringField(recordField(lastReadJson, "agent"), "statusReason") ?? `codewith agent ${status}`,
+        startedAt,
+        finishedAt,
+        durationMs: new Date(finishedAt).getTime() - new Date(startedAt).getTime()
+      };
+    }
+    if (typeof spec.timeoutMs === "number" && new Date(nowIso()).getTime() - new Date(startedAt).getTime() >= spec.timeoutMs) {
+      spawnSync2(spec.command, codewithAgentControlArgs(target, "stop", agentId), { cwd: spec.cwd, env, stdio: "ignore", timeout: 15000 });
+      const finishedAt = nowIso();
+      return {
+        status: "timed_out",
+        stdout: appendBoundedText(stdout, codewithAgentEvidence(startJson, lastReadJson, lastLogsJson), maxOutputBytes),
+        stderr,
+        error: `timed out after ${spec.timeoutMs}ms`,
+        startedAt,
+        finishedAt,
+        durationMs: new Date(finishedAt).getTime() - new Date(startedAt).getTime()
+      };
+    }
+    await sleep(pollMs);
+  }
+}
 function preflightRemoteSpec(spec, machine, metadata, opts) {
   const plan = (opts.machineCommandResolver ?? resolveMachineCommand)(machine.id, "bash -s");
   const result = spawnSync2(plan.command, plan.args, {
@@ -4053,6 +4351,19 @@ function preflightTarget(target, metadata = {}, opts = {}) {
 async function executeTarget(target, metadata = {}, opts = {}) {
   const spec = commandSpec(target);
   const machine = resolvedMachine(opts);
+  if (machine && !machine.local && spec.codewithDurableAgent) {
+    const startedAt2 = nowIso();
+    const finishedAt2 = nowIso();
+    return {
+      status: "failed",
+      stdout: "",
+      stderr: "",
+      error: "remote Codewith durable background-agent steps require remote status polling support; run this Codewith step locally or add remote durable readback before dispatch",
+      startedAt: startedAt2,
+      finishedAt: finishedAt2,
+      durationMs: new Date(finishedAt2).getTime() - new Date(startedAt2).getTime()
+    };
+  }
   if (machine && !machine.local)
     return executeRemoteSpec(spec, machine, metadata, opts);
   const maxOutputBytes = opts.maxOutputBytes ?? DEFAULT_MAX_OUTPUT_BYTES;
@@ -4099,6 +4410,9 @@ async function executeTarget(target, metadata = {}, opts = {}) {
       durationMs: 0
     };
   }
+  if (spec.codewithDurableAgent) {
+    return executeCodewithDurableAgent(spec, metadata, opts, env, startedAt);
+  }
   const child = spawn(spec.command, spec.args, {
     cwd: spec.cwd,
     env,

package/docs/USAGE.md

@@ -6,7 +6,7 @@ It supports deterministic command loops, JSON-defined workflows, and guarded CLI
 
 - `claude`
 - `agent` (Cursor Agent CLI)
-- `codewith exec`
+- `codewith agent start`
 - `aicopilot run`
 - `opencode run`
 - `codex exec`
@@ -893,13 +893,13 @@ On Linux this writes a user systemd service. On macOS it writes a LaunchAgent pl
 The adapters intentionally use provider command surfaces instead of pretending every agent has one SDK:
 
 - 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`, with `--add-dir` for explicit extra writable directories.
+- Codewith uses durable `codewith --ask-for-approval never agent start` background-agent runs by default, then polls `codewith agent read` until the run is terminal and records compact status/event evidence. Remote Codewith agent steps fail closed until remote durable readback is implemented, so workflows do not advance immediately after enqueue. OpenLoops rejects Codewith `extraArgs` that try to force `exec`, `--ephemeral`, or other non-durable exec-only flags for task-lifecycle, planner, worker, verifier, reviewer, release, or other long-running agentic work.
 - AI Copilot and OpenCode use `run --format json --pure`. OpenCode requires an explicit provider/model id because ambient OpenCode config is machine-specific.
 - Cursor is CLI-first for now via the standalone `agent -p` binary. OpenLoops no longer falls back to `cursor agent`; install the standalone Cursor Agent CLI so preflight and scheduled runs use the same executable.
 - Codex uses `codex --ask-for-approval never exec --json --ephemeral --skip-git-repo-check`, with `--add-dir` for explicit extra writable directories where supported.
-- Agent prompts are sent through child stdin instead of argv so prompt bodies do not appear in process listings.
+- Agent prompts are sent through child stdin instead of argv where the provider supports stdin. Codewith durable background agents currently accept prompts as native `agent start` arguments, so OpenLoops stores only bounded status/event evidence and omits raw Codewith event payloads from workflow stdout.
 - 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.
+- `--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 `agent start/read/logs`; 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`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hasna/loops",
-  "version": "0.3.59",
+  "version": "0.3.60",
   "description": "Persistent local loop and workflow runner for deterministic commands and headless AI coding agents",
   "type": "module",
   "main": "dist/index.js",