@loopingai/core 0.5.0 → 0.6.0

package/dist/db/schema.d.ts

@@ -164,8 +164,8 @@ export declare const notifyTasks: import("drizzle-orm/sqlite-core").SQLiteTableW
  *
  * The integer primary key assigns a caller-local, monotonically increasing
  * `SubtaskId` (autoincrement, so ids are never reused after cleanup deletes
- * rows). References, dependency edges, and result parts are stored as JSON text
- * and parsed back into the `Subtask` contract by `models/subtasks.ts`.
+ * rows). References and result parts are stored as JSON text and parsed back
+ * into the `Subtask` contract by `models/subtasks.ts`.
  * `recipe_id`/`recipe_version` are null until execution starts, then record the
  * resolved recipe after the fact.
  */
@@ -336,25 +336,6 @@ export declare const subtasks: import("drizzle-orm/sqlite-core").SQLiteTableWith
         }, {}, {
             length: number | undefined;
         }>;
-        dependsOnJson: import("drizzle-orm/sqlite-core").SQLiteColumn<{
-            name: "depends_on_json";
-            tableName: "subtasks";
-            dataType: "string";
-            columnType: "SQLiteText";
-            data: string;
-            driverParam: string;
-            notNull: true;
-            hasDefault: false;
-            isPrimaryKey: false;
-            isAutoincrement: false;
-            hasRuntimeDefault: false;
-            enumValues: [string, ...string[]];
-            baseColumn: never;
-            identity: undefined;
-            generated: undefined;
-        }, {}, {
-            length: number | undefined;
-        }>;
         paramsJson: import("drizzle-orm/sqlite-core").SQLiteColumn<{
             name: "params_json";
             tableName: "subtasks";
@@ -485,4 +466,3 @@ export declare const subtasks: import("drizzle-orm/sqlite-core").SQLiteTableWith
     };
     dialect: "sqlite";
 }>;
-//# sourceMappingURL=schema.d.ts.map

package/dist/db/schema.js

@@ -51,8 +51,8 @@ export const notifyTasks = sqliteTable("notify_tasks", {
  *
  * The integer primary key assigns a caller-local, monotonically increasing
  * `SubtaskId` (autoincrement, so ids are never reused after cleanup deletes
- * rows). References, dependency edges, and result parts are stored as JSON text
- * and parsed back into the `Subtask` contract by `models/subtasks.ts`.
+ * rows). References and result parts are stored as JSON text and parsed back
+ * into the `Subtask` contract by `models/subtasks.ts`.
  * `recipe_id`/`recipe_version` are null until execution starts, then record the
  * resolved recipe after the fact.
  */
@@ -71,8 +71,6 @@ export const subtasks = sqliteTable("subtasks", {
     prompt: text("prompt").notNull(),
     /** JSON `SubtaskReference[]` — verbatim role+text snapshots from decomposition. */
     referencesJson: text("references_json").notNull(),
-    /** JSON `SubtaskId[]` — resolved dependency edges. */
-    dependsOnJson: text("depends_on_json").notNull(),
     /** JSON `SubtaskParams` — the type's required inputs, validated at delegation. */
     paramsJson: text("params_json").notNull().default("{}"),
     status: text("status").notNull(),
@@ -88,4 +86,3 @@ export const subtasks = sqliteTable("subtasks", {
     index("idx_subtasks_status").on(table.status),
     index("idx_subtasks_created_at").on(table.createdAt)
 ]);
-//# sourceMappingURL=schema.js.map

package/dist/env.d.ts

@@ -51,4 +51,3 @@ export type CoreEnv = AiEnv & A2ASecretsEnv;
  * rather than as an empty allowlist that rejects every caller identically.
  */
 export declare function parseGatewayOrigins(raw: string): string[];
-//# sourceMappingURL=env.d.ts.map

package/dist/env.js

@@ -45,4 +45,3 @@ export function parseGatewayOrigins(raw) {
         throw new Error("GATEWAY_ORIGINS is empty");
     return parsed;
 }
-//# sourceMappingURL=env.js.map

package/dist/host/agent.d.ts

@@ -2,7 +2,7 @@ import { Agent, type Schedule } from "agents";
 import { type Task } from "@a2a-js/sdk";
 import { type AgentRuntime } from "../runtime/index.js";
 import type { AgentPlugin } from "../contract/plugin.js";
-import { type CoreConfig, type CoreConfigOverrides } from "../config.js";
+import { type CoreConfig, type CoreConfigOverrides, type ModelConfig } from "../config.js";
 import type { A2ASecretsEnv, AiEnv } from "../env.js";
 import { AgentDB } from "../db/index.js";
 import type { GatewayIdentity } from "../a2a/verify.js";
@@ -10,7 +10,7 @@ import type { PlainTask } from "../a2a/task.js";
 import type { TaskListQuery } from "../a2a/agent-stub.js";
 import { type PushChannel, type TurnPushContext } from "../a2a/push.js";
 import { type SessionLike } from "../agent/session.js";
-import { type GatewayMetadata, type ModelPair, type ModelRuntime } from "../agent/model.js";
+import type { GatewayMetadata, ModelPair, ModelRuntime } from "../agent/model.js";
 import type { PluginHost } from "./plugin-host.js";
 /**
  * The Durable Object body every Looping agent has, whatever loop it runs.
@@ -64,6 +64,9 @@ export declare abstract class LoopingAgent<TEnv extends Cloudflare.Env & AiEnv &
      * `onStart` runs before any request, so it is not known when `agentPlugins()`
      * is built — which is why anything per-caller takes a thunk. The DO is keyed
      * 1:1 by this value, so it is constant once set.
+     *
+     * In-memory, and deliberately so — see {@link requireIdentityKey}, which does
+     * not depend on it surviving.
      */
     private identityKey?;
     /**
@@ -95,7 +98,30 @@ export declare abstract class LoopingAgent<TEnv extends Cloudflare.Env & AiEnv &
     protected get config(): CoreConfig;
     /** The agent's database (drizzle + migrations), built once per DO instance. */
     protected get db(): AgentDB;
-    /** The model runtime for this instance, built lazily over the `AI` binding. */
+    /**
+     * Which provider this agent's loops run on. Defaults to Workers AI; override
+     * to run on something else.
+     *
+     * The seam is here rather than in `models` because `models` memoizes, and a
+     * subclass overriding a memoized getter has to remember to keep the caching —
+     * a trap that only shows up as a performance bug. This is called once.
+     *
+     * `ModelRuntime` is the whole contract: return anything satisfying it and
+     * every loop in core keeps working unchanged. Core ships two implementations,
+     * one directory each — {@link file://../agent/workers-ai/index.ts
+     * `agent/workers-ai`} (the default below) and `@loopingai/core/anthropic` —
+     * and a third provider is a third directory exporting one
+     * {@link file://../agent/model.ts ModelRuntimeFactory}, not a change to
+     * anything on this path.
+     *
+     * Takes the resolved {@link ModelConfig} rather than reading `this.config`, so
+     * that this signature matches
+     * {@link file://../round/subagent.ts RecipeSubagentHost.modelRuntime} — an
+     * agent and its facet **must** run the same provider, and identical seams are
+     * what let one factory serve both instead of two hand-copied bodies.
+     */
+    protected modelRuntime(model: ModelConfig): ModelRuntime;
+    /** The model runtime for this instance, built lazily and memoized. */
     protected get models(): ModelRuntime;
     /**
      * What this agent's plugins are handed. Built from
@@ -141,7 +167,35 @@ export declare abstract class LoopingAgent<TEnv extends Cloudflare.Env & AiEnv &
      * announces the loss, and the runtime fans it out to every plugin that asked.
      */
     getSession(identity: GatewayIdentity): SessionLike;
-    /** The caller key, which is present on every path that can reach a plugin. */
+    /**
+     * The caller key, which is present on every path that can reach a plugin.
+     *
+     * ## Why this does not just read the field
+     *
+     * `identityKey` is set on the first turn and lives in the isolate. An isolate
+     * does not live as long as the work does: it can be evicted between two rounds
+     * of the same task, and it can be reset outright — "Durable Object connection
+     * closed because the object was reset" — while a Workflow step is mid-flight.
+     * The next call arrives on a fresh instance where the field is empty, and
+     * every per-caller thunk built off it throws.
+     *
+     * That failure is disproportionate to its cause. A plugin asking which caller
+     * it is serving gets an exception, mid-task, on an object whose entire purpose
+     * is to be that caller's — and because the throw happens inside a tool or a
+     * runtime resolution rather than at the edge, it surfaces as a failed branch
+     * rather than as anything an operator can read.
+     *
+     * So the object answers from itself. `define-agent` routes with
+     * `ns.get(ns.idFromName(identity.key))`, which means the caller key *is* this
+     * object's name and the platform hands it back on `ctx.id.name` — durable, free
+     * and correct by construction: an object cannot disagree with the name it was
+     * addressed by.
+     *
+     * The field still wins when it is set. `id.name` is undefined for an object
+     * addressed by `newUniqueId()` or a raw id string, so it is a fallback rather
+     * than the source of truth, and the throw is kept for the case where neither
+     * exists.
+     */
     protected requireIdentityKey(): string;
     /** The gateway callback channel for one turn. See {@link PushChannel}. */
     protected push(context: TurnPushContext): PushChannel;
@@ -214,4 +268,3 @@ export declare abstract class LoopingAgent<TEnv extends Cloudflare.Env & AiEnv &
      */
     protected onTaskCanceled(_taskId: string): Promise<void>;
 }
-//# sourceMappingURL=agent.d.ts.map

package/dist/host/agent.js

@@ -6,7 +6,7 @@ import { AgentDB, stateOf } from "../db/index.js";
 import { callerContext } from "../a2a/caller.js";
 import { createPushChannel } from "../a2a/push.js";
 import { buildAgentSession } from "../agent/session.js";
-import { createModelRuntime } from "../agent/model.js";
+import { workersAIModels } from "../agent/workers-ai/index.js";
 /**
  * The Durable Object body every Looping agent has, whatever loop it runs.
  *
@@ -59,6 +59,9 @@ export class LoopingAgent extends Agent {
      * `onStart` runs before any request, so it is not known when `agentPlugins()`
      * is built — which is why anything per-caller takes a thunk. The DO is keyed
      * 1:1 by this value, so it is constant once set.
+     *
+     * In-memory, and deliberately so — see {@link requireIdentityKey}, which does
+     * not depend on it surviving.
      */
     identityKey;
     /**
@@ -101,12 +104,34 @@ export class LoopingAgent extends Agent {
             stores: this.runtime.stores
         }));
     }
-    /** The model runtime for this instance, built lazily over the `AI` binding. */
+    /**
+     * Which provider this agent's loops run on. Defaults to Workers AI; override
+     * to run on something else.
+     *
+     * The seam is here rather than in `models` because `models` memoizes, and a
+     * subclass overriding a memoized getter has to remember to keep the caching —
+     * a trap that only shows up as a performance bug. This is called once.
+     *
+     * `ModelRuntime` is the whole contract: return anything satisfying it and
+     * every loop in core keeps working unchanged. Core ships two implementations,
+     * one directory each — {@link file://../agent/workers-ai/index.ts
+     * `agent/workers-ai`} (the default below) and `@loopingai/core/anthropic` —
+     * and a third provider is a third directory exporting one
+     * {@link file://../agent/model.ts ModelRuntimeFactory}, not a change to
+     * anything on this path.
+     *
+     * Takes the resolved {@link ModelConfig} rather than reading `this.config`, so
+     * that this signature matches
+     * {@link file://../round/subagent.ts RecipeSubagentHost.modelRuntime} — an
+     * agent and its facet **must** run the same provider, and identical seams are
+     * what let one factory serve both instead of two hand-copied bodies.
+     */
+    modelRuntime(model) {
+        return workersAIModels(this.env, model);
+    }
+    /** The model runtime for this instance, built lazily and memoized. */
     get models() {
-        return (this._models ??= createModelRuntime({
-            ai: this.env.AI,
-            config: this.config.model
-        }));
+        return (this._models ??= this.modelRuntime(this.config.model));
     }
     /**
      * What this agent's plugins are handed. Built from
@@ -193,12 +218,41 @@ export class LoopingAgent extends Agent {
             onMessagesDisplaced: this.runtime.onMessagesDisplaced
         }));
     }
-    /** The caller key, which is present on every path that can reach a plugin. */
+    /**
+     * The caller key, which is present on every path that can reach a plugin.
+     *
+     * ## Why this does not just read the field
+     *
+     * `identityKey` is set on the first turn and lives in the isolate. An isolate
+     * does not live as long as the work does: it can be evicted between two rounds
+     * of the same task, and it can be reset outright — "Durable Object connection
+     * closed because the object was reset" — while a Workflow step is mid-flight.
+     * The next call arrives on a fresh instance where the field is empty, and
+     * every per-caller thunk built off it throws.
+     *
+     * That failure is disproportionate to its cause. A plugin asking which caller
+     * it is serving gets an exception, mid-task, on an object whose entire purpose
+     * is to be that caller's — and because the throw happens inside a tool or a
+     * runtime resolution rather than at the edge, it surfaces as a failed branch
+     * rather than as anything an operator can read.
+     *
+     * So the object answers from itself. `define-agent` routes with
+     * `ns.get(ns.idFromName(identity.key))`, which means the caller key *is* this
+     * object's name and the platform hands it back on `ctx.id.name` — durable, free
+     * and correct by construction: an object cannot disagree with the name it was
+     * addressed by.
+     *
+     * The field still wins when it is set. `id.name` is undefined for an object
+     * addressed by `newUniqueId()` or a raw id string, so it is a fallback rather
+     * than the source of truth, and the throw is kept for the case where neither
+     * exists.
+     */
     requireIdentityKey() {
-        if (!this.identityKey) {
+        const key = this.identityKey ?? this.ctx.id.name;
+        if (!key) {
             throw new Error("identity.key is required for per-caller isolation");
         }
-        return this.identityKey;
+        return (this.identityKey = key);
     }
     /** The gateway callback channel for one turn. See {@link PushChannel}. */
     push(context) {
@@ -301,4 +355,3 @@ export class LoopingAgent extends Agent {
      */
     async onTaskCanceled(_taskId) { }
 }
-//# sourceMappingURL=agent.js.map

package/dist/host/index.d.ts

@@ -18,4 +18,3 @@
  */
 export { LoopingAgent } from "./agent.js";
 export type { PluginHost } from "./plugin-host.js";
-//# sourceMappingURL=index.d.ts.map

package/dist/host/index.js

@@ -17,4 +17,3 @@
  * round loop, which is opt-in and takes its prompt copy from the agent.
  */
 export { LoopingAgent } from "./agent.js";
-//# sourceMappingURL=index.js.map

package/dist/host/plugin-host.d.ts

@@ -40,4 +40,3 @@ export interface PluginHost<TEnv extends object = object> {
     /** `config.model.aiGatewayId`, already resolved over core's baseline. */
     aiGatewayId: string;
 }
-//# sourceMappingURL=plugin-host.d.ts.map

package/dist/host/plugin-host.js

@@ -1,2 +1 @@
 export {};
-//# sourceMappingURL=plugin-host.js.map

package/dist/index.d.ts

@@ -9,12 +9,11 @@
  * production bundle.
  */
 export { createAgentRuntime, RuntimeSetupError, buildRecipeTools, collectToolFamilies, type AgentRuntime, type CreateAgentRuntimeOptions } from "./runtime/index.js";
-export { PLUGIN_CONTRACT_VERSION, definePlugin, type AgentPlugin, type EmitProgress, type EnrichResultContext, type MainAgentToolContext, type PluginRequirements, type RecipeToolSet, type ResolveRuntimeContext, type ToolFamilyBuilder, type ToolFamilyContext, type TurnGateContext } from "./contract/plugin.js";
+export { PLUGIN_CONTRACT_VERSION, definePlugin, restrictMainAgentTools, type AgentPlugin, type RestrictMainAgentToolsOptions, type EmitProgress, type EnrichResultContext, type MainAgentToolContext, type PluginRequirements, type RecipeToolSet, type ResolveRuntimeContext, type ToolFamilyBuilder, type ToolFamilyContext, type TurnGateContext } from "./contract/plugin.js";
 export type { DelegationNames, RecipeLimits, ResolvedRecipe, SubtaskParams, SubtaskParamsSchema, SubtaskParamsShape, SubtaskTypeSpec, ValidatedRecipe } from "./contract/recipe.js";
 export { RecipeValidationError, resolveLimits, validateRecipe, type RecipePolicy } from "./contract/validation.js";
 export { ConfigError, DEFAULT_CORE_CONFIG, resolveConfig, type AgentLimits, type CoreConfig, type CoreConfigOverrides, type ModelConfig, type SessionConfig } from "./config.js";
 export { parseGatewayOrigins, type A2ASecretsEnv, type AiEnv, type CoreEnv } from "./env.js";
-export { CHUNK_SOFT_MS, MAX_CHUNKS_PER_BRANCH, STEP_TIMEOUT_MS, STEPS_PER_INSTANCE } from "./platform.js";
+export { CHUNK_SOFT_MS, MAX_CHUNKS_PER_BRANCH, MAX_TOOL_CALL_MS, STEP_TIMEOUT_MS, STEPS_PER_INSTANCE } from "./platform.js";
 export type { PluginStore } from "./db/db.js";
 export { makeWorkspaceHandle, memoryWorkspaceBacking, WorkspaceLimitError, WORKSPACE_MAX_FILES, WORKSPACE_MAX_FILE_BYTES, type WorkspaceBacking, type WorkspaceEntry, type WorkspaceHandle } from "./subagent/workspace.js";
-//# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -9,10 +9,9 @@
  * production bundle.
  */
 export { createAgentRuntime, RuntimeSetupError, buildRecipeTools, collectToolFamilies } from "./runtime/index.js";
-export { PLUGIN_CONTRACT_VERSION, definePlugin } from "./contract/plugin.js";
+export { PLUGIN_CONTRACT_VERSION, definePlugin, restrictMainAgentTools } from "./contract/plugin.js";
 export { RecipeValidationError, resolveLimits, validateRecipe } from "./contract/validation.js";
 export { ConfigError, DEFAULT_CORE_CONFIG, resolveConfig } from "./config.js";
 export { parseGatewayOrigins } from "./env.js";
-export { CHUNK_SOFT_MS, MAX_CHUNKS_PER_BRANCH, STEP_TIMEOUT_MS, STEPS_PER_INSTANCE } from "./platform.js";
+export { CHUNK_SOFT_MS, MAX_CHUNKS_PER_BRANCH, MAX_TOOL_CALL_MS, STEP_TIMEOUT_MS, STEPS_PER_INSTANCE } from "./platform.js";
 export { makeWorkspaceHandle, memoryWorkspaceBacking, WorkspaceLimitError, WORKSPACE_MAX_FILES, WORKSPACE_MAX_FILE_BYTES } from "./subagent/workspace.js";
-//# sourceMappingURL=index.js.map

package/dist/platform.d.ts

@@ -4,20 +4,38 @@
  * for those, and note that no Recipe can reach these. They change when the
  * platform changes, and for no other reason.
  *
- * The distinction is worth keeping sharp, because collapsing it is what produced
- * the bug this file was extracted during: a *turn count* was used to keep a step
- * under the step timeout, which only works if you can predict how long a turn
- * takes. You cannot. Time bounds time here; turns bound cost, over in `config.ts`.
+ * The distinction is worth keeping sharp, because collapsing it produces a
+ * specific bug: using a *turn count* to keep a step under the step timeout only
+ * works if you can predict how long a turn takes. You cannot. Time bounds time
+ * here; turns bound cost, over in `config.ts`.
  */
 /**
- * Platform fact: a `step.do(...)` callback is killed at ~10 minutes (Workflows'
- * default step timeout). {@link CHUNK_SOFT_MS} is sized against this.
+ * The step timeout **we configure**, passed as `WorkflowStepConfig.timeout` on
+ * every step that can hold a model call or a container command.
+ *
+ * This is the one value in this file that is **not** a platform fact, and
+ * treating it as one is the mistake to avoid: ten minutes is Workflows'
+ * *default* step timeout, not its ceiling, and a step that never passes a config
+ * inherits it silently. Sizing {@link CHUNK_SOFT_MS} against that inherited
+ * default is what once ran a production task as ten four-minute slices, one of
+ * which blew the ten minutes anyway and was retried whole.
+ *
+ * The genuine platform facts are narrower and do not bind us: wall-clock time per
+ * step is effectively unlimited, and a step is bounded by **CPU** time. Measured
+ * over a 59-minute task, the chunk steps used ~100 ms of CPU against 3,146 s of
+ * wall — this ceiling is nowhere near the real one.
+ *
+ * It is still a ceiling worth having, because it is what turns a hung container
+ * into a retry rather than a task that never ends. {@link CHUNK_SOFT_MS} is sized
+ * against it, and that relationship is asserted in `platform.spec.ts`.
  */
 export declare const STEP_TIMEOUT_MS: number;
 /**
- * Platform fact: a single Workflow instance may run ~10,000 steps (paid plan).
- * {@link MAX_CHUNKS_PER_BRANCH} is sized against this — see the worst-case
- * product asserted in `platform.spec.ts`.
+ * Platform fact: a single Workflow instance may run 10,000 steps by default on the
+ * paid plan. Cloudflare will raise it to 25,000 on request — worth knowing, and
+ * worth not relying on: {@link MAX_CHUNKS_PER_BRANCH} is sized against the default
+ * so nothing here needs an account-level exception to be correct. See the
+ * worst-case product asserted in `platform.spec.ts`.
  */
 export declare const STEPS_PER_INSTANCE = 10000;
 /**
@@ -28,8 +46,52 @@ export declare const STEPS_PER_INSTANCE = 10000;
  * This is the *only* thing keeping a step under the timeout. A subagent otherwise
  * runs until its turn or wall-clock budget is spent, however many turns that takes
  * — which is the point: the runner no longer guesses at turn duration.
+ *
+ * ## Why this is 15 minutes and not 4
+ *
+ * A chunk boundary is not free. It checkpoints, returns through two RPC hops,
+ * starts a fresh step, and re-hydrates the subagent — and for a coding agent it
+ * also means the container connection is re-established. Four minutes bought a
+ * boundary roughly every third tool call: a task that edited one README line spent
+ * 59 minutes across **ten** chunks, and the model was idle for most of each one,
+ * blocked on a single `sb_exec` running the project's test gate.
+ *
+ * ## Why it is not larger, which is the part that bit us
+ *
+ * This is a **soft** deadline, checked between turns (`stopWhen` in
+ * `subagent/run.ts`). A turn that starts one millisecond before it trips still runs
+ * to completion, so the real worst case is:
+ *
+ *     chunk wall  ≤  CHUNK_SOFT_MS + one whole turn
+ *
+ * and one turn is a model call plus a tool call. The old pair ignored that: four
+ * minutes soft under a ten-minute timeout looked like six minutes of headroom, but
+ * a single `sb_exec` may run for {@link MAX_TOOL_CALL_MS}, so a turn could add ten.
+ * That is not a hypothetical — it is the `WorkflowTimeoutError` that cost a
+ * production task ten minutes and a full chunk replay.
+ *
+ * So the headroom is sized against a whole turn, not against a guess:
+ * `STEP_TIMEOUT_MS - CHUNK_SOFT_MS` is 15 minutes, covering
+ * {@link MAX_TOOL_CALL_MS} of tool call plus five minutes for the model call and
+ * its provider retries. Asserted in `platform.spec.ts` — raise the step timeout
+ * before raising this.
  */
 export declare const CHUNK_SOFT_MS: number;
+/**
+ * The longest a **single tool call** may run, and a contract rather than a
+ * mechanism: core has no way to enforce it, because core installs no tools.
+ *
+ * It exists because {@link CHUNK_SOFT_MS} cannot be reasoned about without it. The
+ * soft deadline is checked between turns, so a host that lets one tool block for
+ * longer than the headroom under {@link STEP_TIMEOUT_MS} reintroduces exactly the
+ * step-timeout kill this pair is sized to prevent — and it reintroduces it
+ * invisibly, in a plugin, a long way from this file.
+ *
+ * A host installing a tool that can block (a shell, a container command, a fetch
+ * with no ceiling of its own) must bound it at or below this. See the `timeoutMs`
+ * passed to `@loopingai/plugins/computer` in looping-starter.
+ */
+export declare const MAX_TOOL_CALL_MS: number;
 /**
  * Hard ceiling on durable chunk steps for one Subtask branch. A backstop, not a
  * budget: the Workflow *fails* a branch that reaches it, so reaching it is a bug.
@@ -39,9 +101,9 @@ export declare const CHUNK_SOFT_MS: number;
  * 1. It exceeds every Recipe's `maxTurns`. A chunk that yields always advanced at
  *    least one turn, so a run takes at most `maxTurns` chunks however short they
  *    are — and they do get short, because `CHUNK_SOFT_MS` and progress events both
- *    end one early. That bound survives both; a nominal `maxTurns / turnsPerChunk`
- *    estimate survived neither, which is why no such estimate exists any more.
+ *    end one early. Counting turns is what makes the bound survive that; any
+ *    estimate of turns-per-chunk would not, since neither of those two is
+ *    predictable.
  * 2. The worst-case step product stays under {@link STEPS_PER_INSTANCE}.
  */
 export declare const MAX_CHUNKS_PER_BRANCH = 40;
-//# sourceMappingURL=platform.d.ts.map

package/dist/platform.js

@@ -4,20 +4,38 @@
  * for those, and note that no Recipe can reach these. They change when the
  * platform changes, and for no other reason.
  *
- * The distinction is worth keeping sharp, because collapsing it is what produced
- * the bug this file was extracted during: a *turn count* was used to keep a step
- * under the step timeout, which only works if you can predict how long a turn
- * takes. You cannot. Time bounds time here; turns bound cost, over in `config.ts`.
+ * The distinction is worth keeping sharp, because collapsing it produces a
+ * specific bug: using a *turn count* to keep a step under the step timeout only
+ * works if you can predict how long a turn takes. You cannot. Time bounds time
+ * here; turns bound cost, over in `config.ts`.
  */
 /**
- * Platform fact: a `step.do(...)` callback is killed at ~10 minutes (Workflows'
- * default step timeout). {@link CHUNK_SOFT_MS} is sized against this.
+ * The step timeout **we configure**, passed as `WorkflowStepConfig.timeout` on
+ * every step that can hold a model call or a container command.
+ *
+ * This is the one value in this file that is **not** a platform fact, and
+ * treating it as one is the mistake to avoid: ten minutes is Workflows'
+ * *default* step timeout, not its ceiling, and a step that never passes a config
+ * inherits it silently. Sizing {@link CHUNK_SOFT_MS} against that inherited
+ * default is what once ran a production task as ten four-minute slices, one of
+ * which blew the ten minutes anyway and was retried whole.
+ *
+ * The genuine platform facts are narrower and do not bind us: wall-clock time per
+ * step is effectively unlimited, and a step is bounded by **CPU** time. Measured
+ * over a 59-minute task, the chunk steps used ~100 ms of CPU against 3,146 s of
+ * wall — this ceiling is nowhere near the real one.
+ *
+ * It is still a ceiling worth having, because it is what turns a hung container
+ * into a retry rather than a task that never ends. {@link CHUNK_SOFT_MS} is sized
+ * against it, and that relationship is asserted in `platform.spec.ts`.
  */
-export const STEP_TIMEOUT_MS = 10 * 60_000;
+export const STEP_TIMEOUT_MS = 30 * 60_000;
 /**
- * Platform fact: a single Workflow instance may run ~10,000 steps (paid plan).
- * {@link MAX_CHUNKS_PER_BRANCH} is sized against this — see the worst-case
- * product asserted in `platform.spec.ts`.
+ * Platform fact: a single Workflow instance may run 10,000 steps by default on the
+ * paid plan. Cloudflare will raise it to 25,000 on request — worth knowing, and
+ * worth not relying on: {@link MAX_CHUNKS_PER_BRANCH} is sized against the default
+ * so nothing here needs an account-level exception to be correct. See the
+ * worst-case product asserted in `platform.spec.ts`.
  */
 export const STEPS_PER_INSTANCE = 10_000;
 /**
@@ -28,8 +46,52 @@ export const STEPS_PER_INSTANCE = 10_000;
  * This is the *only* thing keeping a step under the timeout. A subagent otherwise
  * runs until its turn or wall-clock budget is spent, however many turns that takes
  * — which is the point: the runner no longer guesses at turn duration.
+ *
+ * ## Why this is 15 minutes and not 4
+ *
+ * A chunk boundary is not free. It checkpoints, returns through two RPC hops,
+ * starts a fresh step, and re-hydrates the subagent — and for a coding agent it
+ * also means the container connection is re-established. Four minutes bought a
+ * boundary roughly every third tool call: a task that edited one README line spent
+ * 59 minutes across **ten** chunks, and the model was idle for most of each one,
+ * blocked on a single `sb_exec` running the project's test gate.
+ *
+ * ## Why it is not larger, which is the part that bit us
+ *
+ * This is a **soft** deadline, checked between turns (`stopWhen` in
+ * `subagent/run.ts`). A turn that starts one millisecond before it trips still runs
+ * to completion, so the real worst case is:
+ *
+ *     chunk wall  ≤  CHUNK_SOFT_MS + one whole turn
+ *
+ * and one turn is a model call plus a tool call. The old pair ignored that: four
+ * minutes soft under a ten-minute timeout looked like six minutes of headroom, but
+ * a single `sb_exec` may run for {@link MAX_TOOL_CALL_MS}, so a turn could add ten.
+ * That is not a hypothetical — it is the `WorkflowTimeoutError` that cost a
+ * production task ten minutes and a full chunk replay.
+ *
+ * So the headroom is sized against a whole turn, not against a guess:
+ * `STEP_TIMEOUT_MS - CHUNK_SOFT_MS` is 15 minutes, covering
+ * {@link MAX_TOOL_CALL_MS} of tool call plus five minutes for the model call and
+ * its provider retries. Asserted in `platform.spec.ts` — raise the step timeout
+ * before raising this.
+ */
+export const CHUNK_SOFT_MS = 15 * 60_000;
+/**
+ * The longest a **single tool call** may run, and a contract rather than a
+ * mechanism: core has no way to enforce it, because core installs no tools.
+ *
+ * It exists because {@link CHUNK_SOFT_MS} cannot be reasoned about without it. The
+ * soft deadline is checked between turns, so a host that lets one tool block for
+ * longer than the headroom under {@link STEP_TIMEOUT_MS} reintroduces exactly the
+ * step-timeout kill this pair is sized to prevent — and it reintroduces it
+ * invisibly, in a plugin, a long way from this file.
+ *
+ * A host installing a tool that can block (a shell, a container command, a fetch
+ * with no ceiling of its own) must bound it at or below this. See the `timeoutMs`
+ * passed to `@loopingai/plugins/computer` in looping-starter.
  */
-export const CHUNK_SOFT_MS = 4 * 60_000;
+export const MAX_TOOL_CALL_MS = 10 * 60_000;
 /**
  * Hard ceiling on durable chunk steps for one Subtask branch. A backstop, not a
  * budget: the Workflow *fails* a branch that reaches it, so reaching it is a bug.
@@ -39,9 +101,9 @@ export const CHUNK_SOFT_MS = 4 * 60_000;
  * 1. It exceeds every Recipe's `maxTurns`. A chunk that yields always advanced at
  *    least one turn, so a run takes at most `maxTurns` chunks however short they
  *    are — and they do get short, because `CHUNK_SOFT_MS` and progress events both
- *    end one early. That bound survives both; a nominal `maxTurns / turnsPerChunk`
- *    estimate survived neither, which is why no such estimate exists any more.
+ *    end one early. Counting turns is what makes the bound survive that; any
+ *    estimate of turns-per-chunk would not, since neither of those two is
+ *    predictable.
  * 2. The worst-case step product stays under {@link STEPS_PER_INSTANCE}.
  */
 export const MAX_CHUNKS_PER_BRANCH = 40;
-//# sourceMappingURL=platform.js.map