@capybara-hq/kernel 0.0.0-stage → 0.1.0-rc.0

package/dist/runtime/subagents/preamble.d.ts

@@ -0,0 +1,7 @@
+/**
+ * The sub-agent preamble (spec §6.3, model-visible): rendered in a child's system text after
+ * `BEHAVIOR_RULES` and before its instructions. Frozen into each child's `subagent_started` at
+ * dispatch, and request building reads it from there, so changing this text never alters an old
+ * child's requests.
+ */
+export declare const SUBAGENT_PREAMBLE: string;

package/dist/runtime/subagents/preamble.js

@@ -0,0 +1,11 @@
+/**
+ * The sub-agent preamble (spec §6.3, model-visible): rendered in a child's system text after
+ * `BEHAVIOR_RULES` and before its instructions. Frozen into each child's `subagent_started` at
+ * dispatch, and request building reads it from there, so changing this text never alters an old
+ * child's requests.
+ */
+export const SUBAGENT_PREAMBLE = "You are a sub-agent. Another agent dispatched you with the task in the first user message. " +
+    "Work on it on your own: the user does not watch this conversation and you cannot ask them " +
+    "questions. When you are done, reply with your final report. That reply is the only thing " +
+    "returned to the agent that dispatched you, so include everything it needs. If you cannot " +
+    "finish, say what is missing and why.";

package/dist/runtime/subagents/progress.d.ts

@@ -0,0 +1,26 @@
+import type { Logger } from "@capybara-hq/plugin-sdk";
+import type { KernelDb } from "../../db/kernel-schema.js";
+/** A finished step of a sub-agent run, as the loop reports it. */
+export interface SubagentStep {
+    /** The parent conversation, whose topic gets the message. */
+    parentConversationId: string;
+    /** The child conversation (the sub-agent's id). */
+    conversationId: string;
+    runId: string;
+    step: number;
+}
+export interface SubagentProgressDeps {
+    db: KernelDb;
+    bus: {
+        publish(topic: string, payload: unknown): Promise<void>;
+    };
+    log: Pick<Logger, "warn">;
+}
+/**
+ * Publishes `{ kind: "subagent_progress", subagentId, step, toolCalls, lastToolKey? }` on the
+ * parent conversation's topic after a child step (sub-agents spec §14.2). Ephemeral: not in any
+ * log, lost on reconnect (the summary API has the current numbers). The counts come from the
+ * child run's log (its `tool_result` events), never from process memory, so any replica running
+ * the step reports the same. Never throws: a lost progress message costs nothing.
+ */
+export declare function publishSubagentProgress(d: SubagentProgressDeps, s: SubagentStep): Promise<void>;

package/dist/runtime/subagents/progress.js

@@ -0,0 +1,36 @@
+import { sql } from "kysely";
+import { conversationTopic } from "../../conversations/event-log.js";
+/**
+ * Publishes `{ kind: "subagent_progress", subagentId, step, toolCalls, lastToolKey? }` on the
+ * parent conversation's topic after a child step (sub-agents spec §14.2). Ephemeral: not in any
+ * log, lost on reconnect (the summary API has the current numbers). The counts come from the
+ * child run's log (its `tool_result` events), never from process memory, so any replica running
+ * the step reports the same. Never throws: a lost progress message costs nothing.
+ */
+export async function publishSubagentProgress(d, s) {
+    try {
+        const { rows } = await sql `
+      SELECT count(*) AS n,
+        (array_agg(e.payload->>'toolKey' ORDER BY e.seq DESC))[1] AS last
+      FROM capybara.conversation_events e
+      WHERE e.conversation_id = ${s.conversationId} AND e.run_id = ${s.runId}
+        AND e.type = 'tool_result'
+    `.execute(d.db);
+        const row = rows[0];
+        const msg = {
+            kind: "subagent_progress",
+            subagentId: s.conversationId,
+            step: s.step,
+            toolCalls: Number(row?.n ?? 0),
+            ...(row?.last != null && { lastToolKey: row.last }),
+        };
+        await d.bus.publish(conversationTopic(s.parentConversationId), msg);
+    }
+    catch (err) {
+        d.log.warn("sub-agent progress publish failed", {
+            conversationId: s.conversationId,
+            runId: s.runId,
+            err,
+        });
+    }
+}

package/dist/runtime/subagents/roster.d.ts

@@ -0,0 +1,55 @@
+import type { AgentDefinition } from "../../agents/definition.js";
+import type { KernelDb } from "../../db/kernel-schema.js";
+/**
+ * The sub-agent roster of an agent version (phase C, spec §4.3, §5.1): the agent types its `agent`
+ * tool offers, in the order the description lists them.
+ */
+export interface RosterEntry {
+    /** `general-purpose` | inline name | `<plugin>:<name>` | an org agent's roster name (`as`). */
+    type: string;
+    source: "general" | "inline" | "plugin" | "agent";
+    /** When to use it (shown in the tool description), cut to {@link ROSTER_DESCRIPTION_MAX}. */
+    description: string;
+    /** Plugin templates: the `agent_templates` id. */
+    templateId?: string;
+    /** Org agents: the allowlisted agent id. */
+    agentId?: string;
+    /** Org agents: the agent's current name, when it is still a live agent of the org. */
+    agentName?: string;
+    /** Plugin templates: the plugin name. */
+    plugin?: string;
+}
+export declare const ROSTER_DESCRIPTION_MAX = 1024;
+/** The description of `general-purpose` in the roster (spec §4.3, model-visible). */
+export declare const GENERAL_PURPOSE_DESCRIPTION = "a copy of you with your tools and skills, for multi-step work.";
+/** Plugin template type: `<plugin>:<name>`. */
+export declare const templateType: (plugin: string, name: string) => string;
+/**
+ * Resolves the roster of `parent` (spec §4.3): `general-purpose` first unless
+ * `subagents.general === false`, then the plugin templates, inline templates and allowlisted org
+ * agents, each in the owner's order, at most {@link SUBAGENT_ROSTER_MAX} entries. Templates deleted
+ * since the save are skipped; allowlisted org agents stay listed (the dispatch checks their gates
+ * and refuses with the §4.5 text), with `agentName` only while the agent is live.
+ */
+export declare function resolveRoster(db: KernelDb, orgId: string, parent: Pick<AgentDefinition, "subagents">): Promise<RosterEntry[]>;
+/**
+ * The roster entry for a requested `subagent_type`: an exact type first; else a bare `<name>`
+ * matches the plugin template `<plugin>:<name>` when exactly one has it (as Claude Code accepts
+ * `reviewer` for `my-plugin:reviewer`). Null when nothing matches.
+ */
+export declare function findType(roster: RosterEntry[], requested: string): RosterEntry | null;
+/** A forked skill's `agent` that runs as `general-purpose` by definition (absent ones aside). */
+export declare const isGeneralAlias: (agent: string) => boolean;
+/**
+ * The sub-agent type a forked skill (`context: fork`, phase D spec §6.2) runs as for `parent`:
+ * `general-purpose` for no `agent` and Claude's built-in types; else a roster type (a bare name
+ * prefers the skill's own plugin's template `<plugin>:<name>`, then {@link findType}). An `agent`
+ * that does not resolve falls back to `general-purpose` and is returned as `unknown`. `inRoster`:
+ * the type is one the parent's `agent` tool offers (`general-purpose` is not when
+ * `subagents.general === false`, which does not block a person's fork invocation).
+ */
+export declare function resolveSkillForkType(db: KernelDb, orgId: string, parent: Pick<AgentDefinition, "subagents">, agent: string | undefined, plugin: string | undefined): Promise<{
+    agentType: string;
+    unknown?: string;
+    inRoster: boolean;
+}>;

package/dist/runtime/subagents/roster.js

@@ -0,0 +1,111 @@
+import { SUBAGENT_ROSTER_MAX } from "../../agents/agents.service.js";
+import { loadTemplates } from "../../agents/templates.js";
+export const ROSTER_DESCRIPTION_MAX = 1024;
+/** The description of `general-purpose` in the roster (spec §4.3, model-visible). */
+export const GENERAL_PURPOSE_DESCRIPTION = "a copy of you with your tools and skills, for multi-step work.";
+const cut = (s) => s.slice(0, ROSTER_DESCRIPTION_MAX);
+/** Plugin template type: `<plugin>:<name>`. */
+export const templateType = (plugin, name) => `${plugin}:${name}`;
+/**
+ * Resolves the roster of `parent` (spec §4.3): `general-purpose` first unless
+ * `subagents.general === false`, then the plugin templates, inline templates and allowlisted org
+ * agents, each in the owner's order, at most {@link SUBAGENT_ROSTER_MAX} entries. Templates deleted
+ * since the save are skipped; allowlisted org agents stay listed (the dispatch checks their gates
+ * and refuses with the §4.5 text), with `agentName` only while the agent is live.
+ */
+export async function resolveRoster(db, orgId, parent) {
+    const sub = parent.subagents;
+    const out = [];
+    if (sub?.general !== false) {
+        out.push({
+            type: "general-purpose",
+            source: "general",
+            description: GENERAL_PURPOSE_DESCRIPTION,
+        });
+    }
+    const templateIds = sub?.templates ?? [];
+    const templates = await loadTemplates(db, orgId, templateIds);
+    for (const id of templateIds) {
+        const r = templates.get(id);
+        if (!r)
+            continue;
+        const description = r.template.description;
+        out.push({
+            type: templateType(r.plugin, r.name),
+            source: "plugin",
+            description: cut(typeof description === "string" ? description : ""),
+            templateId: r.id,
+            plugin: r.plugin,
+        });
+    }
+    for (const t of sub?.inline ?? []) {
+        out.push({ type: t.name, source: "inline", description: cut(t.description) });
+    }
+    const agents = sub?.agents ?? [];
+    if (agents.length > 0) {
+        const rows = await db
+            .selectFrom("agents")
+            .innerJoin("agent_versions", (j) => j
+            .onRef("agent_versions.agent_id", "=", "agents.id")
+            .onRef("agent_versions.version", "=", "agents.current_version"))
+            .select(["agents.id", "agent_versions.definition"])
+            .where("agents.org_id", "=", orgId)
+            .where("agents.deleted_at", "is", null)
+            .where("agents.id", "in", agents.map((a) => a.agentId))
+            .execute();
+        const names = new Map(rows.map((r) => [r.id, r.definition.name]));
+        for (const a of agents) {
+            const agentName = names.get(a.agentId);
+            out.push({
+                type: a.as,
+                source: "agent",
+                description: cut(a.description),
+                agentId: a.agentId,
+                ...(agentName !== undefined && { agentName }),
+            });
+        }
+    }
+    return out.slice(0, SUBAGENT_ROSTER_MAX);
+}
+/**
+ * The roster entry for a requested `subagent_type`: an exact type first; else a bare `<name>`
+ * matches the plugin template `<plugin>:<name>` when exactly one has it (as Claude Code accepts
+ * `reviewer` for `my-plugin:reviewer`). Null when nothing matches.
+ */
+export function findType(roster, requested) {
+    const exact = roster.find((e) => e.type === requested);
+    if (exact)
+        return exact;
+    if (requested.includes(":"))
+        return null;
+    const bare = roster.filter((e) => e.source === "plugin" && e.type.endsWith(`:${requested}`));
+    return bare.length === 1 ? bare[0] : null;
+}
+/** Claude Code's built-in agent types a forked skill may name; they run as `general-purpose`. */
+const GENERAL_ALIASES = new Set(["general-purpose", "Explore", "Plan"]);
+/** A forked skill's `agent` that runs as `general-purpose` by definition (absent ones aside). */
+export const isGeneralAlias = (agent) => GENERAL_ALIASES.has(agent);
+/**
+ * The sub-agent type a forked skill (`context: fork`, phase D spec §6.2) runs as for `parent`:
+ * `general-purpose` for no `agent` and Claude's built-in types; else a roster type (a bare name
+ * prefers the skill's own plugin's template `<plugin>:<name>`, then {@link findType}). An `agent`
+ * that does not resolve falls back to `general-purpose` and is returned as `unknown`. `inRoster`:
+ * the type is one the parent's `agent` tool offers (`general-purpose` is not when
+ * `subagents.general === false`, which does not block a person's fork invocation).
+ */
+export async function resolveSkillForkType(db, orgId, parent, agent, plugin) {
+    const roster = await resolveRoster(db, orgId, parent);
+    const general = () => ({
+        agentType: "general-purpose",
+        inRoster: roster.some((e) => e.type === "general-purpose"),
+    });
+    if (agent === undefined || GENERAL_ALIASES.has(agent))
+        return general();
+    if (plugin !== undefined && !agent.includes(":")) {
+        const own = roster.find((e) => e.type === templateType(plugin, agent));
+        if (own)
+            return { agentType: own.type, inRoster: true };
+    }
+    const e = findType(roster, agent);
+    return e ? { agentType: e.type, inRoster: true } : { ...general(), unknown: agent };
+}

package/dist/runtime/subagents/skill-fork.d.ts

@@ -0,0 +1,123 @@
+import type { Transaction } from "kysely";
+import type { EventLog } from "../../conversations/event-log.js";
+import type { ConversationEvent, EventPayload } from "../../conversations/events.js";
+import type { KernelDatabase } from "../../db/kernel-schema.js";
+import { ApiError } from "../../errors.js";
+import type { SkillInvoker } from "../../skills/invoke.js";
+import type { LoopContext, WaitingFor } from "../loop.js";
+import { type DispatchDeps } from "./dispatch.js";
+/**
+ * Forked skills (phase D spec §6): a person's invocation of a `context: fork` skill starts its own
+ * run (the run boundary, {@link forkBoundary}), whose `prepare` node dispatches the sub-agent
+ * through phase C's `dispatchSubagent` before any model call and waits on it like an `agent` call
+ * (`subagents` wait `sa-<runId>-0`). When the child has ended, `prepare` appends the model-visible
+ * `skill_fork_result` and the parent's model answers. Every terminal path of the run (and the wait
+ * sweep) pairs a fork invocation without a report ({@link pairStoppedForks}), so the log never holds
+ * a fork lead whose report is missing before the next model call.
+ */
+type KernelTrx = Transaction<KernelDatabase>;
+/** The dispatch's parent call id (no `:`; there is no tool call). */
+export declare const skillCallId: (seq: number) => string;
+/** Idempotency key of a fork invocation's report (one per invocation, whatever the run). */
+export declare const forkResultIdemKey: (seq: number) => string;
+/** A fork dispatch's step: before the run's first model step (steps start at 1). */
+export declare const FORK_STEP = 0;
+/** The invocation seq of a fork dispatch row (`skill-<seq>` at step 0), else null. */
+export declare const forkSeqOfCall: (callId: string, step: number) => number | null;
+export type ForkInvocation = ConversationEvent & {
+    type: "user_message";
+    payload: EventPayload<"user_message"> & {
+        skill: NonNullable<EventPayload<"user_message">["skill"]>;
+    };
+};
+/** A person's fork invocation (`user_message.skill.mode === "fork"`). */
+export declare const isForkInvocation: (e: ConversationEvent) => e is ForkInvocation;
+/**
+ * The run boundary (spec §6.3): the messages a run absorbs, in order, stopping before any fork
+ * invocation other than the run's own trigger message, and right after its own. A fork invocation
+ * is therefore only ever absorbed by the run it triggers (`RunQueue.ensureRun` makes the first
+ * unconsumed fork invocation a run's trigger), at that run's first step, and is its last message
+ * there; messages posted after it (also during the sub-agent wait) come at a later step or in the
+ * next run, after the report (batch 3 review C1).
+ */
+export declare function forkBoundary<E extends ConversationEvent>(messages: readonly E[], triggerSeq: number): E[];
+/** The model-visible report text (spec §6.3). */
+export declare const forkReportText: (name: string, body: string) => string;
+/** The report when the run ended before the sub-agent was dispatched. */
+export declare const FORK_NOT_STARTED_TEXT = "The run ended before the sub-agent started; the skill did not run.";
+/** The report when the skill's instructions could not be read at dispatch. */
+export declare const FORK_UNREADABLE_TEXT = "The sub-agent did not start: the skill's instructions could not be read. The user can run the skill again.";
+/** The report when storage was down at dispatch (batch 3 review m5). */
+export declare const FORK_STORAGE_DOWN_TEXT = "The sub-agent did not start: the skill's instructions could not be read right now. The user can try again.";
+/**
+ * The report for a task that could not be rendered at dispatch: the version is gone or its
+ * SKILL.md unreadable (`skill_unreadable`), or storage was down.
+ */
+export declare const forkRenderFailureText: (e: ApiError) => string;
+/** What `prepare` does with the run's fork invocation. */
+export type SkillForkStep = 
+/** The report is in the log: go on to the model step. */
+{
+    kind: "ready";
+}
+/** The sub-agent runs: suspend on it. */
+ | {
+    kind: "suspend";
+    waitingFor: WaitingFor;
+}
+/** The run is being stopped: end it; its terminal path writes the report. */
+ | {
+    kind: "aborted";
+}
+/**
+ * End the run without a model call (full-run replay of a run whose recording has no report:
+ * the original ended before it, so the replay ends there too, as a finished run with no reply).
+ */
+ | {
+    kind: "end";
+};
+/** The loop's fork handler (`LoopDeps.skillForks`): live dispatch, or the recorded report. */
+export interface SkillForks {
+    advance(a: {
+        ctx: LoopContext;
+        fork: ForkInvocation;
+    }): Promise<SkillForkStep>;
+}
+export interface SkillForkDeps extends DispatchDeps {
+    invoker: Pick<SkillInvoker, "renderTask">;
+}
+/**
+ * In `prepare`, for the run's fork invocation: dispatch it when it has no dispatch row (rendering
+ * the task from the recorded version, `SkillInvoker.renderTask`) and suspend; append the report once
+ * the child has ended. Phase C's dispatch transaction applies unchanged: limits, the parent run
+ * lock, the starter's credentials, the org agent gates, the stop cascade. A refusal, or a SKILL.md
+ * that cannot be read, is reported as the sub-agent's result.
+ */
+export declare function advanceSkillForks(d: SkillForkDeps, a: {
+    ctx: LoopContext;
+    fork: ForkInvocation;
+}): Promise<SkillForkStep>;
+/** The live handler for the loop (`LoopDeps.skillForks`). */
+export declare const liveSkillForks: (d: SkillForkDeps) => SkillForks;
+/**
+ * The full-run replay's handler (spec §7, A5): never dispatches. The recorded report of the
+ * original run (`skill_fork_result` with this `invokedSeq`) is appended as it was; without one (the
+ * original run ended before its report) the replayed run ends there, before any model call.
+ */
+export declare const recordedSkillForks: (eventLog: Pick<EventLog, "append" | "findByIdem">, recorded: readonly {
+    type: string;
+    payload: unknown;
+}[]) => SkillForks;
+/**
+ * In the transaction `t` of a run's terminal path (or the wait sweep): the run's fork invocation
+ * (its trigger message, by the run boundary) without a report gets one now: the ended child's
+ * result (and the parent's missing `subagent_finished`), {@link AGENT_STOPPED_WITH_RUN_TEXT} for a
+ * child still active (the caller stops it after its commit, as for `agent` calls), or
+ * {@link FORK_NOT_STARTED_TEXT} when nothing was dispatched. Returns the call ids written
+ * (`skill-<seq>`) and the highest seq; the caller notifies after its commit.
+ */
+export declare function pairStoppedForks(t: KernelTrx, eventLog: EventLog, runId: string): Promise<{
+    callIds: string[];
+    toSeq: number | null;
+}>;
+export {};

package/dist/runtime/subagents/skill-fork.js

@@ -0,0 +1,259 @@
+import { ApiError } from "../../errors.js";
+import { AGENT_STOPPED_WITH_RUN_TEXT } from "../../tools/builtins/agent.js";
+import { subagentsWait } from "../../tools/pipeline.js";
+import { TERMINAL_STATUSES } from "../run-finish.js";
+import { childResult, dispatchOfCall, finishedEvent } from "./child.js";
+import { dispatchSubagent } from "./dispatch.js";
+/** The dispatch's parent call id (no `:`; there is no tool call). */
+export const skillCallId = (seq) => `skill-${seq}`;
+/** Idempotency key of a fork invocation's report (one per invocation, whatever the run). */
+export const forkResultIdemKey = (seq) => `skill_fork_result:${seq}`;
+/** A fork dispatch's step: before the run's first model step (steps start at 1). */
+export const FORK_STEP = 0;
+const SKILL_CALL_RE = /^skill-(\d+)$/;
+/** The invocation seq of a fork dispatch row (`skill-<seq>` at step 0), else null. */
+export const forkSeqOfCall = (callId, step) => {
+    const m = step === FORK_STEP ? SKILL_CALL_RE.exec(callId) : null;
+    return m ? Number(m[1]) : null;
+};
+/** A person's fork invocation (`user_message.skill.mode === "fork"`). */
+export const isForkInvocation = (e) => e.type === "user_message" && e.payload.skill?.mode === "fork";
+/**
+ * The run boundary (spec §6.3): the messages a run absorbs, in order, stopping before any fork
+ * invocation other than the run's own trigger message, and right after its own. A fork invocation
+ * is therefore only ever absorbed by the run it triggers (`RunQueue.ensureRun` makes the first
+ * unconsumed fork invocation a run's trigger), at that run's first step, and is its last message
+ * there; messages posted after it (also during the sub-agent wait) come at a later step or in the
+ * next run, after the report (batch 3 review C1).
+ */
+export function forkBoundary(messages, triggerSeq) {
+    const out = [];
+    for (const m of messages) {
+        if (isForkInvocation(m) && m.seq !== triggerSeq)
+            break;
+        out.push(m);
+        if (isForkInvocation(m))
+            break;
+    }
+    return out;
+}
+/** The model-visible report text (spec §6.3). */
+export const forkReportText = (name, body) => `Report from the sub-agent that ran the skill "${name}":\n\n${body}`;
+/** The report when the run ended before the sub-agent was dispatched. */
+export const FORK_NOT_STARTED_TEXT = "The run ended before the sub-agent started; the skill did not run.";
+/** The report when the skill's instructions could not be read at dispatch. */
+export const FORK_UNREADABLE_TEXT = "The sub-agent did not start: the skill's instructions could not be read. The user can run the skill again.";
+/** The report when storage was down at dispatch (batch 3 review m5). */
+export const FORK_STORAGE_DOWN_TEXT = "The sub-agent did not start: the skill's instructions could not be read right now. The user can try again.";
+/**
+ * The report for a task that could not be rendered at dispatch: the version is gone or its
+ * SKILL.md unreadable (`skill_unreadable`), or storage was down.
+ */
+export const forkRenderFailureText = (e) => e.details?.some((d) => d?.reason === "skill_unreadable")
+    ? FORK_UNREADABLE_TEXT
+    : FORK_STORAGE_DOWN_TEXT;
+const reportEvent = (runId, seq, text, row) => ({
+    type: "skill_fork_result",
+    runId,
+    idemKey: forkResultIdemKey(seq),
+    payload: {
+        invokedSeq: seq,
+        ...(row !== undefined && { subagentId: row.childConversationId, childRunId: row.childRunId }),
+        text,
+    },
+});
+/**
+ * In `prepare`, for the run's fork invocation: dispatch it when it has no dispatch row (rendering
+ * the task from the recorded version, `SkillInvoker.renderTask`) and suspend; append the report once
+ * the child has ended. Phase C's dispatch transaction applies unchanged: limits, the parent run
+ * lock, the starter's credentials, the org agent gates, the stop cascade. A refusal, or a SKILL.md
+ * that cannot be read, is reported as the sub-agent's result.
+ */
+export async function advanceSkillForks(d, a) {
+    const { ctx, fork } = a;
+    const seq = fork.seq;
+    const skill = fork.payload.skill;
+    const ready = { kind: "ready" };
+    if (await d.eventLog.findByIdem(ctx.conversationId, forkResultIdemKey(seq)))
+        return ready;
+    const report = (text, row, extra = []) => d.eventLog.append(ctx.conversationId, [
+        ...extra,
+        reportEvent(ctx.runId, seq, forkReportText(skill.name, text), row),
+    ]);
+    const callId = skillCallId(seq);
+    const row = await dispatchOfCall(d.db, ctx.runId, callId);
+    if (row) {
+        const r = await childResult(d.eventLog, row, { forSkill: true });
+        if (!r)
+            return ctx.signal.aborted ? { kind: "aborted" } : suspend(d, ctx);
+        await report(r.content, row, [finishedEvent(row, r.finished)]);
+        return ready;
+    }
+    if (ctx.signal.aborted)
+        return { kind: "aborted" };
+    let rendered;
+    try {
+        rendered = await d.invoker.renderTask({
+            orgId: ctx.orgId,
+            conversationId: ctx.conversationId,
+            skill,
+        });
+    }
+    catch (e) {
+        if (!(e instanceof ApiError))
+            throw e;
+        await report(forkRenderFailureText(e));
+        return ready;
+    }
+    const out = await dispatchSubagent(d, {
+        ctx: {
+            orgId: ctx.orgId,
+            conversationId: ctx.conversationId,
+            runId: ctx.runId,
+            step: FORK_STEP,
+            agentId: ctx.agentId,
+            agentVersion: ctx.agentVersion,
+            agent: ctx.agent,
+            accountId: ctx.triggerAccountId,
+            signal: ctx.signal,
+            deadline: ctx.limits.deadline,
+            ...(ctx.conversationKind !== undefined &&
+                ctx.conversationKind !== "eval" && { conversationKind: ctx.conversationKind }),
+        },
+        callId,
+        input: {
+            description: skill.name.slice(0, 80),
+            // the task message renders `forSkill.task` for the sub-agent's definition
+            prompt: rendered.task(ctx.agent),
+            subagent_type: skill.agentType ?? "general-purpose",
+        },
+        forSkill: {
+            seq,
+            skill,
+            warnings: rendered.warning === undefined ? [] : [rendered.warning],
+            task: rendered.task,
+        },
+    });
+    if (out.kind === "refused") {
+        // a refusal because the run is being stopped: its terminal path reports
+        if (ctx.signal.aborted)
+            return { kind: "aborted" };
+        await report(out.content);
+        return ready;
+    }
+    // a stop that arrived meanwhile never suspends on the sub-agent (phase C's rule for agent calls)
+    return ctx.signal.aborted ? { kind: "aborted" } : suspend(d, ctx);
+}
+const suspend = (d, ctx) => ({
+    kind: "suspend",
+    waitingFor: subagentsWait(ctx.runId, FORK_STEP, d.config()),
+});
+/** The live handler for the loop (`LoopDeps.skillForks`). */
+export const liveSkillForks = (d) => ({
+    advance: (a) => advanceSkillForks(d, a),
+});
+/**
+ * The full-run replay's handler (spec §7, A5): never dispatches. The recorded report of the
+ * original run (`skill_fork_result` with this `invokedSeq`) is appended as it was; without one (the
+ * original run ended before its report) the replayed run ends there, before any model call.
+ */
+export const recordedSkillForks = (eventLog, recorded) => ({
+    async advance({ ctx, fork }) {
+        if (await eventLog.findByIdem(ctx.conversationId, forkResultIdemKey(fork.seq))) {
+            return { kind: "ready" };
+        }
+        const r = recorded.find((e) => e.type === "skill_fork_result" &&
+            e.payload.invokedSeq === fork.seq);
+        if (!r)
+            return { kind: "end" };
+        await eventLog.append(ctx.conversationId, [
+            {
+                type: "skill_fork_result",
+                runId: ctx.runId,
+                idemKey: forkResultIdemKey(fork.seq),
+                payload: r.payload,
+            },
+        ]);
+        return { kind: "ready" };
+    },
+});
+/**
+ * In the transaction `t` of a run's terminal path (or the wait sweep): the run's fork invocation
+ * (its trigger message, by the run boundary) without a report gets one now: the ended child's
+ * result (and the parent's missing `subagent_finished`), {@link AGENT_STOPPED_WITH_RUN_TEXT} for a
+ * child still active (the caller stops it after its commit, as for `agent` calls), or
+ * {@link FORK_NOT_STARTED_TEXT} when nothing was dispatched. Returns the call ids written
+ * (`skill-<seq>`) and the highest seq; the caller notifies after its commit.
+ */
+export async function pairStoppedForks(t, eventLog, runId) {
+    const none = { callIds: [], toSeq: null };
+    const run = await t
+        .selectFrom("runs as r")
+        .innerJoin("conversations as c", "c.id", "r.conversation_id")
+        .select(["r.conversation_id", "r.trigger_seq", "c.kind"])
+        .where("r.id", "=", runId)
+        .executeTakeFirst();
+    if (run?.kind !== "chat")
+        return none;
+    const conversationId = run.conversation_id;
+    const seq = Number(run.trigger_seq);
+    const trigger = await t
+        .selectFrom("conversation_events")
+        .select(["type", "payload"])
+        .where("conversation_id", "=", conversationId)
+        .where("seq", "=", run.trigger_seq)
+        .executeTakeFirst();
+    const skill = trigger?.type === "user_message"
+        ? trigger.payload.skill
+        : undefined;
+    if (skill?.mode !== "fork")
+        return none;
+    const written = await t
+        .selectFrom("conversation_events")
+        .select("seq")
+        .where("conversation_id", "=", conversationId)
+        .where("idem_key", "=", forkResultIdemKey(seq))
+        .executeTakeFirst();
+    if (written)
+        return none;
+    const callId = skillCallId(seq);
+    const d = await t
+        .selectFrom("subagent_dispatches")
+        .select([
+        "parent_run_id",
+        "parent_call_id",
+        "parent_conversation_id",
+        "child_conversation_id",
+        "child_run_id",
+    ])
+        .where("parent_run_id", "=", runId)
+        .where("parent_call_id", "=", callId)
+        .executeTakeFirst();
+    const events = [];
+    if (!d) {
+        events.push(reportEvent(runId, seq, forkReportText(skill.name, FORK_NOT_STARTED_TEXT)));
+    }
+    else {
+        const row = {
+            parentRunId: d.parent_run_id,
+            parentCallId: d.parent_call_id,
+            parentConversationId: d.parent_conversation_id,
+            childConversationId: d.child_conversation_id,
+            childRunId: d.child_run_id,
+        };
+        const child = await t
+            .selectFrom("runs")
+            .select("status")
+            .where("id", "=", row.childRunId)
+            .executeTakeFirst();
+        // a child that already ended keeps its own result (its log is committed)
+        const ended = child !== undefined && TERMINAL_STATUSES.has(child.status)
+            ? await childResult(eventLog, row, { forSkill: true })
+            : null;
+        if (ended)
+            events.push(finishedEvent(row, ended.finished));
+        events.push(reportEvent(runId, seq, forkReportText(skill.name, ended ? ended.content : AGENT_STOPPED_WITH_RUN_TEXT), row));
+    }
+    const out = await eventLog.append(conversationId, events, t);
+    return { callIds: [callId], toSeq: Math.max(...out.map((e) => e.seq)) };
+}