@gr8ful/spf 0.9.2 → 0.10.0

package/dist/cli/index.js

@@ -11,6 +11,7 @@ import * as agentFlue from "../core/agent_flue.js";
 import * as notify from "../core/notify/notifier.js";
 import * as otel from "../core/otel.js";
 import * as paths from "../core/paths.js";
+import * as sandbox from "../core/sandbox.js";
 import { findChain, registerRepoChains, repoChainProblems } from "../chains/index.js";
 import { loadRepoChains } from "../chains/repo_chains.js";
 import { dispatchChain, usageFor } from "./commands/run.js";
@@ -28,6 +29,7 @@ import { abortCommand } from "./commands/abort.js";
 import { uiCommand } from "./commands/ui.js";
 import { watchCommand, watchInitCommand } from "./commands/watch.js";
 import { fanoutCommand } from "./commands/fanout.js";
+import { loopCommand } from "./commands/loop.js";
 import { versionCommand } from "./commands/version.js";
 const HELP = `spf — repeatable agents-plus-code workflows (ADWs)
 
@@ -35,6 +37,7 @@ const HELP = `spf — repeatable agents-plus-code workflows (ADWs)
   spf <chain> "<prompt>" [options]          run a chain (spf run <chain> ... works identically)
   spf fanout <chain> "<prompt>" [--n 3]     best-of-N: N isolated attempts, one deterministic winner branch — YOU merge it, spf never does
   spf fanout --clean <base-adw-id>          remove leftover worktrees/branches from a killed or discarded fanout run
+  spf loop <chain> "<goal>" --until-suite <name> --max N [--issue <id>]   run a chain repeatedly toward a goal until a named quality.suites check passes
   spf estimate <chain> "<prompt>" [--n N]   read-only: planned model routing + a token/cost projection from real trace history — starts nothing, exits 3 if there's no history yet
   spf init [--force] [--yes] [--template <name>] [--no-skills]  interview to seed .spf/spf.config.yaml + .env, and install the Claude Code skill unless --no-skills (--yes/--template skip the interview, not the skill install)
   spf install-skill [--user] [--force]      (re)install the Claude Code skill by hand — spf init already does this
@@ -167,6 +170,9 @@ export async function main() {
             case "fanout":
                 process.exitCode = await fanoutCommand(rest);
                 return;
+            case "loop":
+                process.exitCode = await loopCommand(rest);
+                return;
             case "estimate":
                 process.exitCode = await estimateCommand(rest);
                 return;
@@ -237,6 +243,14 @@ export async function main() {
         // agent_cc.ts's shutdown() just kills any still-running claude children.
         await agentFlue.shutdown();
         await agentCc.shutdown();
+        // Belt-and-braces alongside the per-run `sandbox.withRunScope` wraps in
+        // dispatchChain/watch/fanout: catches any sandboxed run's lease this
+        // process still holds when the CLI exits (a per-run wrap that itself
+        // throws before reaching its own teardown, a chain invoked through a
+        // path that predates a wrap, etc.) — without this, `backend: opensandbox`
+        // + default `scope: agent` leaks one container per dispatched agent for
+        // the process's entire lifetime. A no-op when no sandbox was ever created.
+        await sandbox.teardownAll();
         // A no-op if notifications are off/unconfigured — awaits any in-flight
         // webhook POST so a fast-exiting command doesn't drop it mid-flight.
         await notify.flushAll();

package/dist/core/agent_cc.d.ts

@@ -123,6 +123,17 @@ export declare function isKnownToolName(name: string): boolean;
  * substitution is unit-testable without spawning a real subprocess.
  */
 export declare function resolveClaudeCmdSpec(model: string): string;
+/**
+ * Whether a resolved `cmdSpec` launches `claude` through `ollama launch` —
+ * the one wrapper shape that needs its own `--` separator (see the module
+ * doc comment) AND the one whose reported `total_cost_usd` isn't a real
+ * Anthropic-billed dollar figure (see the cost note at this module's `run()`
+ * call site): Ollama bills these sessions by flat subscription or local
+ * compute, never per token, so whatever price `claude`'s own internal
+ * (Anthropic) pricing table assigns to the actual serving model is fiction.
+ * Exported as its own pure function, same reasoning as `resolveClaudeCmdSpec`.
+ */
+export declare function isOllamaLaunchCmd(cmdSpec: string): boolean;
 /** Kill any still-running `claude` children — call once, at process exit. Safe if none are running. */
 export declare function shutdown(): Promise<void>;
 /**

package/dist/core/agent_cc.js

@@ -249,6 +249,20 @@ const EFFORT_MAP = {
 export function resolveClaudeCmdSpec(model) {
     return (process.env.SPF_CLAUDE_CMD || "claude").replaceAll("{model}", model);
 }
+/**
+ * Whether a resolved `cmdSpec` launches `claude` through `ollama launch` —
+ * the one wrapper shape that needs its own `--` separator (see the module
+ * doc comment) AND the one whose reported `total_cost_usd` isn't a real
+ * Anthropic-billed dollar figure (see the cost note at this module's `run()`
+ * call site): Ollama bills these sessions by flat subscription or local
+ * compute, never per token, so whatever price `claude`'s own internal
+ * (Anthropic) pricing table assigns to the actual serving model is fiction.
+ * Exported as its own pure function, same reasoning as `resolveClaudeCmdSpec`.
+ */
+export function isOllamaLaunchCmd(cmdSpec) {
+    const [first, second] = cmdSpec.split(/\s+/).filter(Boolean);
+    return first === "ollama" && second === "launch";
+}
 // ── process lifecycle ────────────────────────────────────────────────────────
 const inFlight = new Set();
 /** Kill any still-running `claude` children — call once, at process exit. Safe if none are running. */
@@ -311,7 +325,8 @@ export async function run(request, onEvent, onSpawn, onExit) {
     // ever reached. Any cmdSpec that already contains a literal `--` token is
     // left completely alone — `args` is appended after it exactly as written,
     // never a second separator.
-    const needsOllamaLaunchSeparator = cmdTokens[0] === "ollama" && cmdTokens[1] === "launch" && !cmdArgs.includes("--");
+    const isOllamaLaunch = isOllamaLaunchCmd(cmdSpec);
+    const needsOllamaLaunchSeparator = isOllamaLaunch && !cmdArgs.includes("--");
     const fullArgs = needsOllamaLaunchSeparator ? [...cmdArgs, "--", ...args] : [...cmdArgs, ...args];
     const child = spawn(cmd, fullArgs, { cwd: request.cwd, env: request.env ?? operatorEnv() });
     // The prompt travels as a positional argv element, not stdin — closing it
@@ -377,7 +392,15 @@ export async function run(request, onEvent, onSpawn, onExit) {
         reasoning: u.output_tokens_details?.thinking_tokens ?? 0,
         // CC gives one total cost, not a per-component breakdown like Flue/pi-ai
         // do — folded honestly under `total`, not split up to fabricate one.
-        cost: { total: final.total_cost_usd ?? 0 },
+        // Under `ollama launch`, though, `total_cost_usd` isn't honest at all:
+        // it's `claude`'s own internal (Anthropic) per-token price table applied
+        // to whatever model actually served the request, and Ollama bills
+        // these sessions by flat subscription/local compute, not per token — so
+        // the number has no relationship to what the operator is actually
+        // charged. Zeroed here, matching the same-situation call already made
+        // for the Flue backend's own Ollama models (see `ollama_provider.ts`'s
+        // `modelFor()`).
+        cost: { total: isOllamaLaunch ? 0 : (final.total_cost_usd ?? 0) },
     }, totalTokens);
     const modelUsages = final.modelUsage ?? {};
     const contextWindow = Object.values(modelUsages)[0]?.contextWindow ?? 0;

package/dist/core/agent_flue.js

@@ -26,6 +26,7 @@ import { AgentRunError, createBashTool, createEditTool, createGlobTool, createGr
 import { local, sqlite, start } from "@flue/runtime/node";
 import { UsageBreakdown, makeAgentResult } from "./data_types.js";
 import { registerOllamaModel } from "./ollama_provider.js";
+import * as sandbox from "./sandbox.js";
 import { nowIso, operatorEnv } from "./utils.js";
 const RESULT_SNIPPET_CHARS = 20_000; // tool output rides along whole; clip only guards pathological cases
 const ARG_VALUE_CHARS = 20_000; // args too — the UI scrolls, it must not be handed cut-off data
@@ -160,12 +161,19 @@ function resolveBuiltinTools(names) {
  * USER/LANG/TERM/TMPDIR) — `env` is `request.env ?? operatorEnv()` from the
  * caller, restoring today's actual behavior unless the agent's own
  * `env_allowlist` narrowed it (see agents.ts).
+ *
+ * `spec.sandbox` (SPF #15) is absent for every agent today — byte-identical
+ * to before this field existed. Set, it routes to `sandbox.factoryFor()`
+ * instead of `local()`; note NO `cwd` reaches `useSandbox` for a remote
+ * backend either way (a `cwd` override on `useSandbox` drops adapter-added
+ * properties — see the sandbox design doc §2). The workspace dir travels on
+ * the spec itself (`spec.sandbox.workspace_dir`), read by the adapter.
  */
-function sandboxFor(toolNames, cwd, env) {
-    const base = local({ cwd, env });
-    if (!toolNames)
+function sandboxFor(spec) {
+    const base = spec.sandbox ? sandbox.factoryFor(spec.sandbox) : local({ cwd: spec.cwd, env: spec.env });
+    if (!spec.toolNames)
         return base;
-    const factories = resolveBuiltinTools(toolNames);
+    const factories = resolveBuiltinTools(spec.toolNames);
     return { ...base, tools: (env) => factories.map((f) => f(env)) };
 }
 // ── model pattern validation ─────────────────────────────────────────────────
@@ -191,7 +199,7 @@ function sfAgentRender({ id }) {
     if (!spec)
         throw new Error(`agent_flue: no render spec registered for conversation ${id} — run() must set it before dispatching`);
     useModel(spec.model, { thinkingLevel: spec.thinking });
-    useSandbox(sandboxFor(spec.toolNames, spec.cwd, spec.env));
+    useSandbox(sandboxFor(spec));
     const writeReport = useDataWriter("sf_report");
     useTool({
         name: "sf_report",
@@ -298,6 +306,7 @@ export async function run(request, onEvent, onSpawn, onExit) {
         outputSchema: request.output_schema,
         outputTypeName: request.output_type_name,
         env: request.env ?? operatorEnv(),
+        sandbox: request.sandbox,
     });
     const pid = process.pid ?? -1;
     onSpawn?.(pid);

package/dist/core/agents.d.ts

@@ -8,7 +8,7 @@
  * disposes.
  */
 import { type TierResolution } from "./tiering.ts";
-import { GateReport, makeEventRecord, type AgentCall, type AgentConfig, type EnvelopeBase, type Phase, type SFConfig } from "./data_types.ts";
+import { GateReport, makeEventRecord, type AgentCall, type AgentConfig, type EnvelopeBase, type Phase, type SFConfig, type SandboxSpec } from "./data_types.ts";
 /**
  * `undefined` (no `env_allowlist` configured — the default) means "don't
  * filter at all"; both backends treat that as `request.env ?? operatorEnv()`,
@@ -98,6 +98,24 @@ export declare function applyConfigEnv(env: Record<string, string>): void;
 export declare function resolve(cfg: SFConfig, name: string): AgentConfig;
 /** Fail fast: every required name must resolve to a usable agent. */
 export declare function validate(cfg: SFConfig, required: string[], requiredSuites?: string[], cwd?: string): void;
+/**
+ * Config-only, per-agent — no `Run`, no session id, no network, no fs
+ * beyond the config already in hand. Called from `validate()`'s existing
+ * per-agent loop, chain-scoped (only agents the resolved chain requires).
+ * `spf doctor`'s equivalents (checks #7/#12/#13/#14/#17) walk the WHOLE
+ * roster instead — a deliberately wider, separate scope; see `validate()`'s
+ * own comment for why the two are not the same check.
+ */
+export declare function validateSandboxConfig(cfg: SFConfig, agent: AgentConfig): string[];
+/**
+ * `scope: "run"` is safe only when every required agent's create-time spec
+ * is provably identical — compared as backend + resolved env KEY NAMES
+ * (never values) + the create-time-reachable rest of the spec (image,
+ * setup, egress, workspace_dir, handoff_dir). A no-op for `scope: "agent"`
+ * (the default) and for a chain whose required agents all resolve to
+ * `local` — the common path pays nothing.
+ */
+export declare function validateSandboxRunScope(cfg: SFConfig, required: string[]): string[];
 interface RunForAgents {
     cfg: SFConfig;
     adw_id: string;
@@ -143,6 +161,48 @@ interface RunForAgents {
         coding_agent: string;
     }) => void;
 }
+/**
+ * PURE, SYNC — no network, no filesystem, no session id (session ids exist
+ * only after `agentSessionId()`, which runs after this — SPF #15's design
+ * doc §4.4 walks through exactly why the ordering forces that). `run.cfg` +
+ * `run.adw_id` + `run.repo_root` + `run.context_handoff_dir` + the agent in,
+ * `SandboxSpec | undefined` out. `undefined` (the resolved backend is
+ * "local") means `AgentRequest.sandbox` stays unset — byte-identical to
+ * before this feature existed.
+ *
+ * `handoff_sandbox` PRESERVES `handoff_host`'s shape —
+ * `<handoff_dir>/sessions/<adw_id>/context_handoff`, mirroring
+ * `run.context_handoff_dir` — because two shipped prompts
+ * (planner/user.md, documenter/user.md) parse `<adw_id>` out of that exact
+ * shape to name `specs/<adw_id>_<slug>.md`/`app_docs/<adw_id>_<slug>.md`. A
+ * bare `handoff_dir` would silently cost those filenames their provenance,
+ * with `gates.artifactsExist` still green (it only checks the CLAIMED path).
+ */
+export declare function sandboxSpecFor(run: RunForAgents, agent: AgentConfig): SandboxSpec | undefined;
+/**
+ * OUTBOUND (sandbox -> host), mutates the freshly parsed envelope in place.
+ * Rewrites `artifacts` and, when present, `changed_files` — the handoff
+ * rule is checked FIRST (disjoint from workspace_dir by validation, so
+ * order is not load-bearing here, but the implementation still checks it
+ * first so it stays correct if that invariant is ever relaxed). Applied
+ * immediately after every parse (the first prompt AND every JSON-repair/
+ * gate-correction re-parse), so it is total over every dispatch.
+ */
+export declare function translateEnvelopePaths(envelope: EnvelopeBase, spec: SandboxSpec): void;
+/**
+ * INBOUND (host -> sandbox), the exact inverse — applied to `call.previous`
+ * at the `variables` build site ONLY, before `JSON.stringify`. Returns a
+ * COPY: the persisted envelope and the caller's own object must keep host
+ * paths, so this one does not mutate where `translateEnvelopePaths` does.
+ *
+ * Rule order IS load-bearing here, unlike the outbound direction:
+ * `handoff_host` is `<data_dir>/sessions/<adw_id>/context_handoff` and
+ * `data_dir` resolves against `repo_root` by default, so `handoff_host` is
+ * normally UNDER `host_root`. Checking `host_root` first would rewrite a
+ * handoff-plane path to somewhere under `workspace_dir` the mirror never
+ * populates — so `handoff_host` is checked FIRST, always.
+ */
+export declare function translateEnvelopeToSandbox(envelope: EnvelopeBase, spec: SandboxSpec): EnvelopeBase;
 /** One agent call: render prompts -> pi run -> typed parse -> gates -> envelope. */
 export declare function execute(run: RunForAgents, phase: Phase, call: AgentCall): Promise<EnvelopeBase>;
 export {};