@nodetool-ai/agents 0.7.0-rc.22 → 0.8.1

package/dist/codeact/codeact-executor.d.ts

@@ -0,0 +1,247 @@
+/**
+ * CodeActExecutor — executes a single step with JavaScript code as the action
+ * space instead of JSON tool calls (Wang et al., ICML 2024, arXiv:2402.01030).
+ *
+ * The provider sees exactly one tool, `execute_code`. Each call runs the
+ * model's program in the QuickJS sandbox where the step's toolbelt is exposed
+ * as imported capability modules, and `finish(result)` completes the step
+ * (host-validated against the step's output schema). The program's outcome —
+ * return value, logs, error — is the observation for the next turn. Results a
+ * later action or turn needs go through memory (`nodetool.memory.*`).
+ *
+ * The message contract (`task_update`, `step_result`, `tool_call_update`,
+ * `chunk`), memory writes, and failure semantics are byte-compatible with
+ * {@link StepExecutor}, so every consumer works unchanged.
+ */
+import type { BaseProvider, ProcessingContext, RunBudget, TurnBudget } from "@nodetool-ai/runtime";
+import { type ProcessingMessage } from "@nodetool-ai/protocol";
+import type { Step, Task } from "../types.js";
+import { Tool } from "../tools/base-tool.js";
+import { type SandboxClock, type SandboxLimits } from "../js-sandbox.js";
+import type { CapabilityRun } from "../capabilities/types.js";
+/**
+ * Code actions batch several tool calls per turn, so the turn budget is
+ * deliberately lower than tool mode's 30.
+ */
+export declare const DEFAULT_CODEACT_MAX_ITERATIONS = 20;
+/**
+ * Wall-clock limit per code action. Codeact actions await real tools —
+ * sub-agents, media generation, background-job waits — so the sandbox's 30 s
+ * default kills legitimate work mid-flight (`run_subtask` alone routinely
+ * takes a minute). The same value feeds QuickJS's interrupt deadline, so a
+ * pure CPU spin can now also run this long — acceptable here because every
+ * action is abortable via the run's signal, and tool-awaiting actions are the
+ * codeact norm.
+ */
+export declare const DEFAULT_CODEACT_ACTION_TIMEOUT_MS = 600000;
+/**
+ * The sandbox a step action runs in is closed: no bare `fetch` and no secret.
+ * The belt is the network — `nodetool.web.*`, `http_request`, the capability
+ * imports — and every one of those runs behind the permission gate and the
+ * SSRF guard, which a bare `fetch(url)` with a `getSecret(...)` header did
+ * not. Same shape the chat session passes.
+ */
+export declare const STEP_ACTION_SANDBOX_LIMITS: SandboxLimits;
+/**
+ * Consecutive actions with identical code and an identical error before the
+ * observation stops describing the failure and says the program was already
+ * run. A model resubmitting the same crashing program otherwise spends the
+ * whole iteration budget reading the same error.
+ */
+export declare const REPEATED_ACTION_LIMIT = 2;
+export { EXECUTE_CODE_INPUT_SCHEMA, EXECUTE_CODE_TOOL_NAME, executeCodeMessage, declaredActionRisk, admitCodeAction, ACTION_RISK_VALUES } from "./execute-code-contract.js";
+export type { ActionRisk, ActionAdmission } from "./execute-code-contract.js";
+/**
+ * Paths in a finish() payload whose string values carry the tell-tale
+ * `[object Object]` of an unread object coerced to a string, or a
+ * JSON-serialized envelope standing in for the value it wraps. A schema
+ * cannot catch these — the garbage is still a string — so the finish bridge
+ * rejects them and the model repairs the extraction inside the same action.
+ */
+export declare function coercionArtifactPaths(value: unknown, path?: string, depth?: number): string[];
+/**
+ * Tools documented in full in the prompt regardless of toolbelt size — the
+ * high-traffic set nearly every step reaches for (mirroring the chat
+ * runner's resident-toolbelt idea). Everything else is deferred: still
+ * callable, but discovered through `searchTools()` first, so a 70-tool belt
+ * does not cost 70 signatures of prompt.
+ */
+export declare const CODEACT_RESIDENT_TOOL_NAMES: ReadonlySet<string>;
+/**
+ * Toolbelts at or below this size skip the split entirely — deferring three
+ * tools saves nothing and costs a discovery round.
+ */
+export declare const CODEACT_DEFER_THRESHOLD = 16;
+export interface CodeActExecutorOptions {
+    task: Task;
+    step: Step;
+    context: ProcessingContext;
+    provider: BaseProvider;
+    model: string;
+    tools?: Tool[];
+    /** Preamble layered before the CodeAct contract; cannot override it. */
+    systemPrompt?: string;
+    maxIterations?: number;
+    maxTokens?: number;
+    /**
+     * Spend admission, consulted before every provider turn. A refusal ends the
+     * loop, so a caller's cost cap bounds the step rather than being overrun.
+     *
+     * A {@link RunBudget} carries the run's other bounds too, and the step then
+     * also checks the deadline before every action and every bridged tool call.
+     * A bare {@link TurnBudget} keeps its existing meaning — spend only.
+     */
+    turnBudget?: TurnBudget | RunBudget;
+    useFinishTask?: boolean;
+    threadId?: string;
+    upstreamMemoryKeys?: string[];
+    signal?: AbortSignal;
+    /** Wall-clock limit per code action. Defaults to {@link DEFAULT_CODEACT_ACTION_TIMEOUT_MS}. */
+    actionTimeoutMs?: number;
+    /** Tool calls one action may consume. Default 50. */
+    maxToolCallsPerAction?: number;
+    /**
+     * The action's wall clock, which the host stops while a bridged call waits on
+     * the user (a permission prompt). Without it, the time a person spends
+     * deciding is charged to the action budget and the program is killed
+     * mid-wait; the answer then resolves nothing.
+     */
+    clock?: SandboxClock;
+    /**
+     * Tools documented in full in the prompt. Defaults to
+     * {@link CODEACT_RESIDENT_TOOL_NAMES}; the rest of the toolbelt is
+     * deferred behind `searchTools()` once the belt exceeds
+     * {@link CODEACT_DEFER_THRESHOLD}.
+     */
+    residentToolNames?: Iterable<string>;
+    /**
+     * Sandbox package specifiers this session consents to. An action may import
+     * these and nothing else, and the prompt advertises exactly these.
+     *
+     * Defaults to none. Which packs are trusted is not knowable in here — the
+     * caller resolves that from agent/session configuration, user approval, or
+     * the task's own declarations — so the safe reading of "trusted packs only"
+     * is an empty list until a caller says otherwise.
+     */
+    sandboxPackages?: readonly string[];
+    /**
+     * The run whose capability modules this step's actions may import
+     * (`@nodetool-ai/sandbox-nodetool/<namespace>`). Optional because a step loop
+     * is constructed from a toolbelt, not from a run: the hosts that have one
+     * today are the chat surfaces. Without it nothing is mounted and such an
+     * import is refused by name — the belt is unaffected either way.
+     */
+    capabilityRun?: CapabilityRun;
+}
+/**
+ * Sent as a user message when a schema'd step's turn ended in prose. The model
+ * that built the right value and then described it is one sentence away from a
+ * passing step, and the prose message itself proves it never saw the contract.
+ */
+export declare const FINISH_CONTRACT_NUDGE: string;
+/**
+ * Re-prompts allowed per step. Bounded because a model that ignores the
+ * contract twice is not going to honor it on the third ask, and each nudge is
+ * a paid provider round.
+ */
+export declare const MAX_FINISH_NUDGES = 2;
+export declare class CodeActExecutor {
+    private readonly task;
+    private readonly step;
+    private readonly context;
+    private readonly provider;
+    private readonly model;
+    /** The sandbox toolbelt: everything the model can import into an action. */
+    private readonly tools;
+    /**
+     * The subset also offered to the provider as ordinary tools — see
+     * {@link splitCoreTools}. These stay on the belt so code can still compose
+     * them; what changes is that the prompt documents them as direct calls.
+     */
+    private readonly coreTools;
+    private readonly systemPrompt;
+    private readonly maxIterations;
+    private readonly maxTokens?;
+    private readonly turnBudget?;
+    /** The same budget when it carries the run's deadline; otherwise absent. */
+    private readonly runBudget?;
+    private readonly useFinishTask;
+    private readonly threadId?;
+    private readonly upstreamMemoryKeys;
+    private readonly signal?;
+    private readonly actionTimeoutMs?;
+    private readonly clock?;
+    private readonly maxToolCallsPerAction?;
+    private readonly resultSchema;
+    private readonly residentTools;
+    private readonly deferredTools;
+    /** Namespace → the belt names grafted onto it for this step. */
+    private readonly sessionModuleExports;
+    /** Belt name → the specifier the prompt tells the model to import from. */
+    private readonly graftedSpecifiers;
+    /** Guest prelude for each action: tool wrappers + the object models. */
+    private readonly prelude;
+    /** Specifiers this session's actions may import (flag-gated, may be empty). */
+    private readonly sandboxPackages;
+    /** Whether the graph DSL pack is among them — the prompt section turns on it. */
+    private readonly withGraphDsl;
+    private readonly withFlow;
+    private readonly withFabric;
+    /** The run whose capability modules an action may import, when a host has one. */
+    private readonly capabilityRun?;
+    /**
+     * Uncommitted graph-model op queues, carried across actions of the step.
+     * Internal plumbing for `openWorkflow()` — not a guest-facing contract;
+     * durable results belong in memory (`nodetool.memory.*`).
+     */
+    private readonly graphQueues;
+    private result;
+    private actionCount;
+    /** The last failed action, for {@link REPEATED_ACTION_LIMIT}. */
+    private lastFailure;
+    private repeatedFailures;
+    constructor(opts: CodeActExecutorOptions);
+    getResult(): unknown;
+    execute(): AsyncGenerator<ProcessingMessage>;
+    private _executeImpl;
+    /**
+     * The generations this step paid for, when it is failing before the code that
+     * would have written their asset ids down.
+     *
+     * A step killed by its deadline or budget loses everything the guest held in
+     * variables. Generations are the half of that which costs money: six clips
+     * came back, the action died before persisting the URIs, and the next turn
+     * had no way to know they existed — so it generated them again. The assets
+     * and their `predictions` rows are already saved; naming the ids here is what
+     * lets the next turn reuse them.
+     *
+     * The registry is user-scoped, and under a parallel plan every sibling step
+     * fails in the same window, so the list is cut down to the ids this step's
+     * own bridged calls answered with (`ownIds`). When no call returned an id,
+     * the user-scoped list stands and the note says so.
+     */
+    private paidWorkToRecover;
+    /**
+     * What to say about a stop the step ended on. A {@link RunBudget} knows which
+     * ceiling it was and says so ("turn budget of $5 reached"); a bare
+     * {@link TurnBudget} only knows that one refused, and the stop item's own
+     * text is all there is.
+     */
+    private stopDetail;
+    /**
+     * Whether to re-prompt after a generation round that produced no result.
+     *
+     * The recoverable case is narrow: a schema'd step whose last assistant
+     * message carried no tool calls — the model stopped to explain instead of
+     * calling `finish()`, and the work it did is recoverable in the next round.
+     * A round that ended on a tool call ran out of budget instead, which another user
+     * message does not fix, and a cancelled run must not spend a turn at all.
+     */
+    private shouldNudgeToFinish;
+    private loadResultSchema;
+    private buildUserMessage;
+    private storeCompletionResult;
+    private taskUpdate;
+    private stepResult;
+}
+//# sourceMappingURL=codeact-executor.d.ts.map

package/dist/codeact/codeact-executor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"codeact-executor.d.ts","sourceRoot":"","sources":["../../src/codeact/codeact-executor.ts"],"names":[],"mappings":"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"}