@dynamicagents/core 0.9.0

package/dist/round/turn.js

@@ -0,0 +1,564 @@
+import { generateText, hasToolCall, isStepCount } from "ai";
+import { appendOnce } from "../agent/session.js";
+import { deterministicSessionMessage, finalReplyMessageId, parseRoundAckMessageId, roundAckMessageId, sessionText, taskUserMessageId } from "../agent/history.js";
+import { buildIntermediateContentHandler, isTransientAiError, nonRecoverableKind } from "../agent/inference.js";
+import { controlTools, controlToolSet } from "../agent/control.js";
+import { FINAL_REPLY_TOOL_NAME } from "../agent/final-reply.js";
+import { stepAllowance } from "../agent/budget.js";
+import { DELEGATE_TOOL_NAME, delegateCallInput, delegateCallOutput, delegateToolCallId } from "../subtasks/delegate.js";
+import { isCatalogEligible } from "../subtasks/catalog.js";
+/**
+ * Build both prompt suffixes for one configured agent.
+ *
+ * The agent's contract, then whatever the delegable types have to say about being
+ * delegated — each declared by the type that owns it (`SubtaskTypeSpec`) and
+ * collected by the runtime's registry, so no domain is named by the policy. That
+ * is the rule the two prompt fields on a subtask type exist to hold: everything
+ * the main agent is told about a domain is declared by the plugin that owns it,
+ * never written inside the loop.
+ */
+export function buildTurnInstructions(policy, types, maxSubtasks, limits) {
+    const guidance = types.renderDelegationGuidance({
+        delegateTool: DELEGATE_TOOL_NAME,
+        finalReplyTool: FINAL_REPLY_TOOL_NAME
+    });
+    const open = policy.roundContract({ typeKeys: types.keys, maxSubtasks }) +
+        (guidance ? `\n\n${guidance}` : "");
+    return { open, final: open + policy.finalRoundNote(limits) };
+}
+/** Join one branch's parts into its text block. */
+function branchText(branch) {
+    return (branch.resultParts ?? []).map((p) => p.text).join("\n");
+}
+/** Group every branch by the round that delegated it, preserving ordinal order. */
+function byRound(branches) {
+    const rounds = new Map();
+    for (const branch of branches) {
+        const existing = rounds.get(branch.round);
+        if (existing)
+            existing.push(branch);
+        else
+            rounds.set(branch.round, [branch]);
+    }
+    return rounds;
+}
+/**
+ * Rebuild one round's `delegate` call and pair it with its result.
+ *
+ * Both halves are real. That round's model genuinely emitted this call; the
+ * subagents genuinely produced these outcomes. All that separates them is a
+ * Workflow boundary and, often, hours — so the pair is reconstructed here rather
+ * than carried, from the durable rows that are the record of what happened.
+ *
+ * Failed and skipped branches are included so the model can disclose them rather
+ * than quietly answering as if the work had been done — and, since a failed
+ * branch carries its reason in `output`, so it can tell a wall it should stop
+ * at from a hiccup worth retrying (see `delegateCallOutput`).
+ */
+function delegationPair(taskId, round, replyText, branches) {
+    const toolCallId = delegateToolCallId(taskId, round);
+    const content = [];
+    // The acknowledgment the user already saw, if it is still in history.
+    if (replyText)
+        content.push({ type: "text", text: replyText });
+    content.push({
+        type: "tool-call",
+        toolCallId,
+        toolName: DELEGATE_TOOL_NAME,
+        input: delegateCallInput(replyText ?? "", branches)
+    });
+    return [
+        { role: "assistant", content },
+        {
+            role: "tool",
+            content: [
+                {
+                    type: "tool-result",
+                    toolCallId,
+                    toolName: DELEGATE_TOOL_NAME,
+                    output: { type: "json", value: delegateCallOutput(branches) }
+                }
+            ]
+        }
+    ];
+}
+/**
+ * Render the model's view for one round: the conversation, with every earlier
+ * round's delegation restored as the call-and-result it actually was, and every
+ * referenceable turn marked with the catalog index the model selects it by.
+ *
+ * One pass, two jobs, because they have to agree. The `[ref N]` markers use
+ * `isCatalogEligible` — the same predicate the catalog is numbered with — so a
+ * marker and its entry can never drift: compaction summaries (`assistant` role,
+ * generated) stay in the messages unmarked, readable for context but structurally
+ * uncitable as conversation evidence, which is exactly the intent.
+ *
+ * A round's acknowledgment is stored as plain assistant text (history is
+ * text-only, and stays that way — `sessionText`, the catalog, compaction, and
+ * recall all read text parts). So its `delegate` call is re-attached to that
+ * message here, and the result appended after it, for this one inference call. The
+ * pair is emitted together, anchored on the ack's deterministic id, so a `tool`
+ * message can never be orphaned from its call — and an ack that has been compacted
+ * away still gets its pair, appended at the end minus the acknowledgment text: a
+ * result the model cannot place beats a malformed history.
+ *
+ * Acks are deliberately **not** catalog-eligible: they are the agent's own
+ * scaffolding, and a subtask referencing "I'm on it" as verbatim conversation
+ * evidence would be noise. That holds for every ack in the Session, not only the
+ * ones this render can pair with branches — see `parseRoundAckMessageId`.
+ *
+ * Everything here is ephemeral — scaffolding for this call only. Reference text is
+ * snapshotted from the catalog, so no `[ref N]` prefix ever reaches a Subtask, and
+ * the Session never sees any of this markup.
+ */
+export function renderTurnMessages(history, taskId, branches) {
+    const rounds = byRound(branches);
+    const ackIds = new Map([...rounds.keys()].map((round) => [roundAckMessageId(taskId, round), round]));
+    const catalog = [];
+    const messages = [];
+    const anchored = new Set();
+    for (const message of history) {
+        if (message.role !== "user" && message.role !== "assistant")
+            continue;
+        const role = message.role;
+        const text = sessionText(message);
+        const round = ackIds.get(message.id);
+        if (round !== undefined) {
+            messages.push(...delegationPair(taskId, round, text, rounds.get(round) ?? []));
+            anchored.add(round);
+            continue;
+        }
+        // An acknowledgment with no branches behind it — recognized by id, since
+        // nothing in the message body distinguishes an ack from ordinary assistant
+        // prose. This Task's own is the crash-window leftover: the ack landed, the
+        // rows did not, and this render belongs to the retry that will decide the
+        // round again. Dropping it is what makes that retry a clean re-decision —
+        // left in, it reads as "already delegated" and invites the model to answer
+        // instead of delegating, ending the Task with no work done. Another Task's
+        // ack is real history the user saw, so it stays as context, but uncitable:
+        // no round of *this* Task can hold it up as conversation evidence.
+        const ack = parseRoundAckMessageId(message.id);
+        if (ack) {
+            if (ack.taskId !== taskId)
+                messages.push({ role, content: text });
+            continue;
+        }
+        if (!isCatalogEligible(message)) {
+            // Not referenceable (a compaction summary): still context for reasoning.
+            messages.push({ role, content: text });
+            continue;
+        }
+        const index = catalog.length + 1;
+        catalog.push({ index, role, text });
+        messages.push({ role, content: `[ref ${index}] ${text}` });
+    }
+    // Rounds whose acknowledgment is no longer in history (compacted away by a
+    // concurrent task), in round order so the results still read chronologically.
+    const orphaned = [...rounds.entries()]
+        .filter(([round]) => !anchored.has(round))
+        .sort(([a], [b]) => a - b);
+    for (const [round, roundBranches] of orphaned) {
+        messages.push(...delegationPair(taskId, round, null, roundBranches));
+    }
+    return { messages, catalog };
+}
+/**
+ * Deterministic fallback reply: the successful branches' text in ordinal order,
+ * plus the policy's short note when some branches did not succeed.
+ *
+ * Used when a round's inference is unavailable but its predecessors' work is
+ * durable. Failing the whole Task because the answering model is down would throw
+ * away good results the user asked for.
+ */
+export function joinSuccessfulBranches(branches, partialNote) {
+    const successes = branches.filter((b) => b.status === "completed");
+    const body = successes.map(branchText).join("\n\n");
+    const incomplete = branches.length > successes.length;
+    return incomplete ? `${body}\n\n${partialNote}` : body;
+}
+/**
+ * One attempt against a single model: let it work, and take whichever ending it
+ * lands on.
+ *
+ * Takes the model **factory**, not a model: resolving it can throw (a missing
+ * binding, a bad id), and that has to count as this attempt failing so the other
+ * model still gets its turn.
+ *
+ * The model uses its work tools freely — answering well can genuinely need a
+ * lookup or a recall — and the loop ends by calling a control tool. None has an
+ * `execute`, so there is nothing to continue from and the loop halts on the call.
+ * Two endings in one step are resolved by `ControlTool.precedence`.
+ *
+ * Every control call is then parsed by the tool that owns it, because nothing else
+ * has: an execute-less tool's input never passes through the SDK's validation. A
+ * parse failure comes back as `rejected` — a repairable failure, not a dead
+ * attempt.
+ *
+ * Charges the budget as it goes, whether it succeeds or not: a failed attempt cost
+ * exactly as much as a successful one, and a call that died on its fourth step
+ * still spent four turns.
+ */
+async function attempt(args, control, model, instructions, messages) {
+    const final = args.mode === "final";
+    // A `final` round is handed nothing to work with, only the way out. Leaving the
+    // work tools on would invite it to spend a budget it has already spent — and
+    // the composing round has every branch result in its messages already, so the
+    // thing it needs is not a lookup but an ending.
+    const workTools = final ? {} : args.tools;
+    // One step per attempt for a `final` round: it exists to produce the answer, and
+    // that answer is deliberately spent *beyond* the budget rather than out of it.
+    //
+    // An `open` round gets whatever the shared budget still holds, read here rather
+    // than at the top of the round — so the fallback sees what the primary spent
+    // without anyone having to subtract it. See `stepAllowance` for the floor.
+    const stepBudget = final
+        ? 1
+        : stepAllowance(args.budget.allowance, args.budget.spent);
+    const content = args.onContent
+        ? buildIntermediateContentHandler(args.onContent, [
+            DELEGATE_TOOL_NAME,
+            FINAL_REPLY_TOOL_NAME
+        ])
+        : undefined;
+    try {
+        const result = await generateText({
+            model: model(),
+            instructions,
+            messages,
+            // Control tools are declared *first*: tool order is part of the prompt, and
+            // the two endings are the thing every round has to reach. Work tool names
+            // are compile-time constants and none collides with a control name, so the
+            // spread order costs nothing.
+            tools: { ...controlToolSet(control), ...workTools },
+            // Every ending is a control call, so the model must always call something.
+            // Work tools stay freely available — `required` constrains the *shape* of a
+            // step's output, not which tool is chosen.
+            toolChoice: "required",
+            maxOutputTokens: args.maxOutputTokens,
+            stopWhen: [
+                isStepCount(stepBudget),
+                // Halt on any ending this round declares, so a new control tool needs no
+                // change here.
+                ...control.map((c) => hasToolCall(c.name))
+            ],
+            // Retries on *this* model before the slot is given up, honouring the
+            // provider's own `retry-after`. Not a duplicate of the fallback: the
+            // fallback answers "this model cannot do it", and a 429 says "not yet" —
+            // and when both slots share a credential the fallback cannot even answer
+            // that. See `ModelConfig.maxRetries`.
+            maxRetries: args.maxRetries,
+            // Charged here rather than from `result.steps` so a throw mid-loop still
+            // bills the steps already spent — the `catch` below has no `result` to read.
+            onStepEnd: async (step) => {
+                args.budget.spent += 1;
+                if (content)
+                    await content(step);
+            }
+        });
+        // The most committal ending the model reached, and every call it made to that
+        // tool. Ranking by precedence rather than by position keeps "which ending
+        // wins" a property the tools declare, not a chain of ifs here.
+        const reached = control
+            .map((c) => ({
+            control: c,
+            inputs: result.toolCalls
+                .filter((call) => call.toolName === c.name)
+                .map((call) => call.input)
+        }))
+            .filter((c) => c.inputs.length > 0)
+            .sort((a, b) => b.control.precedence - a.control.precedence)[0];
+        if (reached) {
+            // The call that counts, per the tool — a repeated `final_reply` means its
+            // last one. Held outside the `try` so a rejection shows the model *that*
+            // call and not whichever came first, which it may already have moved past.
+            // Only a `select` that throws leaves it unresolved, and that error is about
+            // the repeats themselves, so the first call represents them as well as any.
+            let subject = reached.inputs[0];
+            try {
+                subject = reached.control.select(reached.inputs);
+                return { ok: true, decision: reached.control.parse(subject) };
+            }
+            catch (error) {
+                // The model ended the round but the call cannot be used. Repairable: it is
+                // handed this error and asked again, rather than costing the whole slot.
+                return {
+                    ok: false,
+                    error,
+                    rejected: {
+                        toolName: reached.control.name,
+                        input: subject
+                    }
+                };
+            }
+        }
+        // No control call. Either the model ran out of steps mid-tool-use, or it
+        // ignored `toolChoice: "required"` and narrated an action instead of taking
+        // one — the failure this whole design exists to catch. Failing the attempt
+        // hands the round to the fallback model rather than shipping the narration to
+        // the user as if it were an answer.
+        if (result.finishReason === "length") {
+            console.warn("[turn] model output truncated", {
+                taskId: args.taskId,
+                round: args.round,
+                maxOutputTokens: args.maxOutputTokens
+            });
+        }
+        return {
+            ok: false,
+            error: new Error(`round produced no decision (finishReason=${result.finishReason}, textLength=${result.text.trim().length})`)
+        };
+    }
+    catch (error) {
+        return { ok: false, error };
+    }
+}
+/**
+ * How many times one model may be shown its own rejected control call and asked
+ * again, before the round gives up on that slot.
+ *
+ * Repair belongs to the **slot**, not the round. A rejected call is not evidence
+ * that a model is unavailable — it is a model that understood the request and got
+ * the shape wrong, which is the one failure it can actually fix once it is shown
+ * the rejection. Falling straight through to the fallback instead spends a whole
+ * second model on a fresh guess that has no idea the first one failed: that is how
+ * two slots produced the identical missing-param error and killed a round either
+ * of them could have repaired.
+ *
+ * The fallback keeps its real job — covering a primary that could not answer at
+ * all — and is still reached once repairs run out, since a model that cannot get
+ * the shape right in four tries has earned a second opinion.
+ */
+const MAX_REPAIR_ATTEMPTS = 3;
+/**
+ * The id a repaired exchange is anchored on, derived from the Task and round like
+ * every other id here. Suffixed per repair, so several rejected calls can sit in
+ * one attempt's messages without colliding.
+ *
+ * Underscore-separated for the same reason as
+ * {@link file://../subtasks/delegate.ts delegateToolCallId}: this reaches a
+ * provider as a `tool_use.id`, and Anthropic rejects anything outside
+ * `^[a-zA-Z0-9_-]+$`. A repair exchange is exactly the moment a round is already
+ * in trouble, so an id that 400s here turns a recoverable bad call into a dead
+ * round.
+ */
+function controlCallId(taskId, round) {
+    return `task_${taskId}_round_${round}_control`;
+}
+/**
+ * A rejected control call paired with its rejection, as the exchange the model has
+ * to see in order to fix it.
+ *
+ * This is deliberately the same shape the SDK produces for a work tool that failed
+ * — the call, then an `error-text` result carrying the reason. A work tool gets
+ * this for free and models already know how to read it; a control tool halts the
+ * loop before the SDK can, so the round builds it by hand. Nothing here is
+ * specific to which control tool was refused.
+ *
+ * Shaped as a real tool exchange rather than a prose "that was wrong" user turn,
+ * because that is what it is — and an assistant tool-call with no matching result
+ * is a malformed message list to every provider.
+ *
+ * Entirely ephemeral. These messages exist for the next `generateText` call and are
+ * never appended to the Session: the durable record of a round is the ending it
+ * landed on, and a call that was thrown out is not something a later round should
+ * be able to read back as history.
+ */
+function repairExchange(toolCallId, rejected, error) {
+    return [
+        {
+            role: "assistant",
+            content: [
+                {
+                    type: "tool-call",
+                    toolCallId,
+                    toolName: rejected.toolName,
+                    input: rejected.input
+                }
+            ]
+        },
+        {
+            role: "tool",
+            content: [
+                {
+                    type: "tool-result",
+                    toolCallId,
+                    toolName: rejected.toolName,
+                    output: {
+                        type: "error-text",
+                        value: `${String(error)}\n\n` +
+                            `The round did not end and nothing was started. Call ${rejected.toolName} ` +
+                            `again, keeping the parts that were fine and fixing only what the error names.`
+                    }
+                }
+            ]
+        }
+    ];
+}
+/**
+ * Run one round against the continuous Session: append the user turn (round 0),
+ * let the model decide over the indexed history, validate any delegation against
+ * this round's catalog, and persist what the user will see.
+ *
+ * Every append uses a deterministic id, so a Workflow-step re-run neither
+ * duplicates the turn nor changes an already-delivered reply.
+ *
+ * Two nested recoveries, and they answer different failures. Within a slot, a
+ * decomposition the catalog rejects is handed back to the *same* model as a failed
+ * tool result, up to {@link MAX_REPAIR_ATTEMPTS} times — a shape error is the one
+ * thing a model can fix once it sees it. Across slots, an attempt that produced no
+ * decision at all moves to the fallback model, which is what that slot is for.
+ *
+ * Throws only on a transient platform fault (for the Workflow step to retry).
+ * A deterministic failure that outlasts every repair on both slots, with durable
+ * work behind it, degrades to {@link joinSuccessfulBranches} rather than discarding
+ * completed branches; with nothing behind it, it resolves to
+ * `{ status: "failed", kind: "exhausted" }`.
+ *
+ * The third failure is neither, and it short-circuits the *model* recoveries
+ * above: a {@link nonRecoverableKind} error ends the round from wherever it
+ * happens, carrying that kind — without repairing and **without reaching the
+ * fallback slot**, both of which would only present the same dead credential
+ * again. See that function for why the transient/deterministic split cannot
+ * express it.
+ *
+ * It does **not** skip the deterministic join. That path needs no credential —
+ * it is string concatenation over rows that are already durable — so completed
+ * branches are still delivered, and the credential fault reaches the operator
+ * through the log rather than by throwing away finished work.
+ */
+export async function runTurn(args) {
+    const { session, taskId, round, text, systemSuffix, models, branches } = args;
+    if (round === 0) {
+        await appendOnce(session, deterministicSessionMessage(taskUserMessageId(taskId), "user", text));
+    }
+    const history = await session.getHistory();
+    const { messages, catalog } = renderTurnMessages(history, taskId, branches);
+    const system = (await session.refreshSystemPrompt()) +
+        systemSuffix +
+        (args.mode === "final" ? args.instructions.final : args.instructions.open);
+    // This round's endings, built with the catalog a `delegate` is checked against.
+    const control = controlTools({
+        catalog,
+        delegable: args.mode !== "final",
+        types: args.types,
+        maxSubtasks: args.maxSubtasks
+    });
+    const diagnostics = [];
+    const errors = [];
+    for (const slot of ["primary", "fallback"]) {
+        const modelId = slot === "primary" ? models.primaryId() : models.fallbackId();
+        const model = slot === "primary" ? models.primary : models.fallback;
+        // This slot's own view: the round's messages plus whatever repair exchange it
+        // accumulates. A fresh copy per slot, so a fallback that is reached is never
+        // handed the primary's rejected calls to be confused by.
+        const slotMessages = [...messages];
+        for (let repair = 0; repair <= MAX_REPAIR_ATTEMPTS; repair += 1) {
+            // Both slots draw on the one `args.budget`, which each attempt reads on entry
+            // and charges as it works. A fallback attempt is spend, not a free retry —
+            // and so is a repair.
+            const outcome = await attempt(args, control, model, system, slotMessages);
+            if (!outcome.ok) {
+                // Before anything else, and before the fallback slot exists as an
+                // option: a failure nothing can clear ends the round here. Repairing
+                // asks a dead credential to try again; falling through spends the
+                // second slot presenting the *same* dead credential. Both are pure
+                // cost, and both delay the only useful outcome — telling an operator
+                // what to fix.
+                const nonRecoverable = nonRecoverableKind(outcome.error);
+                if (nonRecoverable) {
+                    console.error("[turn] non-recoverable model failure", {
+                        taskId,
+                        round,
+                        model: modelId,
+                        kind: nonRecoverable,
+                        error: String(outcome.error)
+                    });
+                    // What ends here is *inference*, not the round's ability to answer.
+                    // Branches that already completed are durable rows, and joining them
+                    // costs no credential — so the same rescue the exhausted path takes
+                    // applies, and the operator hears about the fault from the log above.
+                    const joined = await deterministicJoin(args);
+                    if (joined)
+                        return joined;
+                    return {
+                        status: "failed",
+                        kind: nonRecoverable,
+                        error: String(outcome.error)
+                    };
+                }
+                errors.push(outcome.error);
+                const { rejected } = outcome;
+                diagnostics.push(rejected
+                    ? `${slot} (${modelId}, attempt ${repair + 1}): ${String(outcome.error)}`
+                    : `${slot} (${modelId}): ${String(outcome.error)}`);
+                console.warn(rejected
+                    ? "[turn] control call rejected"
+                    : "[turn] model attempt failed", {
+                    taskId,
+                    round,
+                    model: modelId,
+                    ...(rejected ? { tool: rejected.toolName, repair } : {}),
+                    error: String(outcome.error)
+                });
+                // No rejected call means no ending to correct — the attempt produced
+                // nothing, which is the failure the fallback slot exists for.
+                //
+                // Otherwise repair, while this slot has both attempts and turns left. Past
+                // the allowance every attempt gets `stepAllowance`'s one-step floor, which
+                // is enough to reach an ending but not to reconsider one — so retrying
+                // there buys a worse call at a real cost.
+                if (rejected &&
+                    repair < MAX_REPAIR_ATTEMPTS &&
+                    args.budget.spent < args.budget.allowance) {
+                    slotMessages.push(...repairExchange(`${controlCallId(taskId, round)}_repair_${repair}`, rejected, outcome.error));
+                    continue;
+                }
+                break;
+            }
+            if (outcome.decision.kind === "reply") {
+                // A throw here is a storage fault: it propagates so the step retries.
+                const reply = await appendOnce(session, deterministicSessionMessage(finalReplyMessageId(taskId), "assistant", outcome.decision.text));
+                return { status: "replied", reply };
+            }
+            const stored = await appendOnce(session, deterministicSessionMessage(roundAckMessageId(taskId, round), "assistant", outcome.decision.reply));
+            return {
+                status: "delegated",
+                reply: stored,
+                drafts: outcome.decision.drafts
+            };
+        }
+    }
+    // A transient fault is not a decision failure — let the step retry rather than
+    // failing the user's Task over Workers-AI capacity.
+    const transient = errors.find((e) => isTransientAiError(e));
+    if (transient)
+        throw transient;
+    const detail = `round ${round} exhausted both models — ${diagnostics.join("; ")}`;
+    // Both models failed deterministically. Any branch results behind us are durable
+    // and useful; deliver them joined rather than failing a Task whose work is done.
+    const joined = await deterministicJoin(args);
+    if (joined)
+        return joined;
+    return { status: "failed", kind: "exhausted", error: detail };
+}
+/**
+ * Deliver the branch results this round already has, when no model will produce
+ * an answer over them.
+ *
+ * The one recovery on this file that needs **no** model: a filter, a join and a
+ * durable append. That is why both failure paths reach it — a ladder that ran out
+ * of attempts, and one that stopped on a fault no attempt could clear. Neither
+ * has an answer to write; both have work worth returning.
+ *
+ * `undefined` when nothing completed, which is the caller's signal to fail with
+ * its own kind. No branches means nothing to join, and a Task with no work behind
+ * it should not report success.
+ */
+async function deterministicJoin(args) {
+    const { session, taskId, round, branches } = args;
+    if (!branches.some((b) => b.status === "completed"))
+        return undefined;
+    console.warn("[turn] falling back to deterministic join", { taskId, round });
+    const reply = await appendOnce(session, deterministicSessionMessage(finalReplyMessageId(taskId), "assistant", joinSuccessfulBranches(branches, args.partialNote)));
+    return { status: "replied", reply };
+}