@capybara-hq/kernel 0.1.0-rc.1 → 0.1.0-rc.3

package/dist/runtime/subagents/dispatch.js

@@ -4,7 +4,7 @@ import { normalizeStoredDefinition } from "../../agents/definition.js";
 import { audit } from "../../identity/audit.js";
 import { forkAgentUnknownText } from "../../skills/invoke.js";
 import { AGENT_REFUSALS } from "../../tools/builtins/agent.js";
-import { ACTIVE_RUN_STATUSES, runJobId } from "../run-queue.js";
+import { ACTIVE_RUN_STATUSES, runJobId } from "../run-jobs.js";
 import { effectiveDefinition, narrowFollowUp, SubagentTypeGoneError, } from "./definition.js";
 import { subagentLimits } from "./limits.js";
 import { auditRefusal, checkOrgAgent, currentAgentDefinition } from "./org-agents.js";
@@ -20,7 +20,7 @@ const GENERAL_ENTRY = {
 /** Idempotency key of the parent's `subagent_dispatched` event. */
 export const dispatchedIdemKey = (runId, callId) => `subagent_dispatched:${runId}:${callId}`;
 /**
- * Dispatches the sub-agent of one `agent` call (spec §7.1), after the pipeline's validation,
+ * Dispatches the sub-agent of one `Agent` call (spec §7.1), after the pipeline's validation,
  * policy, approval and `tool.preExecute` stages. A new sub-agent: resolves its type and effective
  * definition, then in one transaction (holding the parent run's row lock, so the dispatches of one
  * run serialize) inserts the child conversation, appends `subagent_started` and the task message,
@@ -118,7 +118,7 @@ export async function dispatchSubagent(d, a) {
             subagent_type: entry.type,
         })
             .execute();
-        const [, task] = await d.eventLog.append(childId, [
+        const [, task] = await d.eventLog.appendIn(childId, [
             {
                 type: "subagent_started",
                 idemKey: "subagent_started",
@@ -149,7 +149,7 @@ export async function dispatchSubagent(d, a) {
                 },
             },
             taskMessage(ctx, a.callId, fork === undefined ? input.prompt : fork.task(eff.definition), undefined, fork?.skill),
-        ], t);
+        ]);
         return task;
     });
     // a new sub-agent's writer never refuses
@@ -234,7 +234,9 @@ async function resume(d, a) {
             .executeTakeFirst();
         if (await activeRun())
             return null;
-        const [task] = await d.eventLog.append(child.id, [taskMessage(ctx, a.callId, a.input.prompt, narrowFollowUp(frozen, current))], t);
+        const [task] = await d.eventLog.appendIn(child.id, [
+            taskMessage(ctx, a.callId, a.input.prompt, narrowFollowUp(frozen, current)),
+        ]);
         return task;
     }).then((r) => r ?? refused(AGENT_REFUSALS.stillRunning(a.id)));
 }
@@ -272,7 +274,7 @@ async function orgAgentGates(db, a, agentId, agentType, resumed) {
 }
 const taskMessage = (ctx, callId, prompt, narrowed, 
 /**
- * A fork invocation's record: the child's log then holds the invocation, so its `skill_load`
+ * A fork invocation's record: the child's log then holds the invocation, so its `Skill`
  * is offered and resolves the invoked version (phase D).
  */
 skill) => ({
@@ -290,153 +292,145 @@ skill) => ({
     },
 });
 /**
- * The dispatch transaction shared by new sub-agents and follow-ups: locks the parent conversation
- * row, then the parent run row (the order every terminal path uses),
- * runs `child` (writes the child conversation's first events and returns the task message, or
- * null to refuse), then inserts the child run and the dispatch row, appends `subagent_dispatched`
- * and the audit row. After commit: notifies both conversations and enqueues the child run.
- * Returns null when `child` refused.
- *
- * Under the parent run's row lock it first re-checks what the pipeline checked without it: a call
- * already dispatched (a second holder of the same step, e.g. after a stalled-job takeover) gets
- * the existing child run back and writes nothing, and a parent run that is no longer `running`
- * (stopped, orphaned) dispatches nothing. Then the run's limits (§8.2, {@link subagentLimits}),
- * read fresh: its children's token counter at or over the cap, its dispatches (follow-ups
- * included) at the cap, or as many active children as may run at once each refuse with the §4.5
- * text. The lock serializes the dispatches of one run, so the counts cannot race.
+ * {@link commit}'s transaction (run by `SubagentsService.commitDispatch`, `d.db` its handle).
+ * Null when `child` refused.
  */
-async function commit(d, a, plan, 
-/** Writes the child's events; `checked` is the org agent version the in-lock gates passed. */
-child) {
+export async function commitDispatchIn(d, a, plan, child) {
     const { ctx, callId, input } = a;
     const childRunId = randomUUID();
-    const out = await d.db.transaction().execute(async (t) => {
-        // the documented order, conversation row then run row (run-finish.ts, abortWaiting): the
-        // append to the parent below takes the conversation row, so it is taken first here, or a stop
-        // racing this commit could deadlock (final review m2); the child's row comes last
+    const t = d.db;
+    // the documented order, conversation row then run row (run-finish.ts, abortWaiting): the
+    // append to the parent below takes the conversation row, so it is taken first here, or a stop
+    // racing this commit could deadlock (final review m2); the child's row comes last
+    await t
+        .selectFrom("conversations")
+        .select("id")
+        .where("id", "=", ctx.conversationId)
+        .forUpdate()
+        .executeTakeFirst();
+    const parent = await t
+        .selectFrom("runs")
+        .select(["status", "subagent_tokens_used"])
+        .where("id", "=", ctx.runId)
+        .forUpdate()
+        .executeTakeFirst();
+    const existing = await t
+        .selectFrom("subagent_dispatches as sd")
+        .leftJoin("runs as cr", "cr.id", "sd.child_run_id")
+        .select(["sd.child_run_id", "sd.child_conversation_id", "cr.status", "cr.trigger_seq"])
+        .where("sd.parent_run_id", "=", ctx.runId)
+        .where("sd.parent_call_id", "=", callId)
+        .executeTakeFirst();
+    if (existing) {
+        return {
+            kind: "existing",
+            childRunId: existing.child_run_id,
+            // still queued: the first holder may have died before its enqueue (review M4)
+            requeue: existing.status === "queued" && existing.trigger_seq !== null
+                ? {
+                    conversationId: existing.child_conversation_id,
+                    seq: Number(existing.trigger_seq),
+                }
+                : null,
+        };
+    }
+    if (parent?.status !== "running")
+        return { kind: "stopped" };
+    const limit = await limitRefusal(t, d, ctx, parent.subagent_tokens_used);
+    if (limit !== null)
+        return { kind: "limit", content: limit };
+    let checked;
+    if (plan.source === "agent") {
+        // the org agent's gates again, under the parent run's lock, with both agents' rows held
+        // FOR SHARE (in id order) so a concurrent save of either serializes with this dispatch
         await t
-            .selectFrom("conversations")
+            .selectFrom("agents")
             .select("id")
-            .where("id", "=", ctx.conversationId)
-            .forUpdate()
-            .executeTakeFirst();
-        const parent = await t
-            .selectFrom("runs")
-            .select(["status", "subagent_tokens_used"])
-            .where("id", "=", ctx.runId)
-            .forUpdate()
-            .executeTakeFirst();
-        const existing = await t
-            .selectFrom("subagent_dispatches as sd")
-            .leftJoin("runs as cr", "cr.id", "sd.child_run_id")
-            .select(["sd.child_run_id", "sd.child_conversation_id", "cr.status", "cr.trigger_seq"])
-            .where("sd.parent_run_id", "=", ctx.runId)
-            .where("sd.parent_call_id", "=", callId)
-            .executeTakeFirst();
-        if (existing) {
-            return {
-                kind: "existing",
-                childRunId: existing.child_run_id,
-                // still queued: the first holder may have died before its enqueue (review M4)
-                requeue: existing.status === "queued" && existing.trigger_seq !== null
-                    ? {
-                        conversationId: existing.child_conversation_id,
-                        seq: Number(existing.trigger_seq),
-                    }
-                    : null,
-            };
-        }
-        if (parent?.status !== "running")
-            return { kind: "stopped" };
-        const limit = await limitRefusal(t, d, ctx, parent.subagent_tokens_used);
-        if (limit !== null)
-            return { kind: "limit", content: limit };
-        let checked;
-        if (plan.source === "agent") {
-            // the org agent's gates again, under the parent run's lock, with both agents' rows held
-            // FOR SHARE (in id order) so a concurrent save of either serializes with this dispatch
-            await t
-                .selectFrom("agents")
-                .select("id")
-                .where("id", "in", [ctx.agentId, plan.agentId])
-                .orderBy("id")
-                .forShare()
-                .execute();
-            const gates = await orgAgentGates(t, a, plan.agentId, plan.agentType, plan.resumed);
-            if ("refused" in gates)
-                return { kind: "gate", outcome: gates.refused };
-            checked = gates.checked;
-        }
-        const task = await child(t, checked);
-        if (task === null)
-            return null;
-        await t
-            .insertInto("runs")
-            .values({
-            id: childRunId,
-            conversation_id: plan.childConversationId,
-            status: "queued",
-            agent_version: plan.agentVersion,
-            trigger_account_id: ctx.accountId,
-            trigger_seq: task.seq,
-        })
+            .where("id", "in", [ctx.agentId, plan.agentId])
+            .orderBy("id")
+            .forShare()
             .execute();
-        await t
-            .insertInto("subagent_dispatches")
-            .values({
-            parent_run_id: ctx.runId,
-            parent_call_id: callId,
-            parent_conversation_id: ctx.conversationId,
-            step: ctx.step,
-            child_conversation_id: plan.childConversationId,
-            child_run_id: childRunId,
-            resumed: plan.resumed,
-        })
-            .execute();
-        const [dispatched] = await d.eventLog.append(ctx.conversationId, [
-            {
-                type: "subagent_dispatched",
-                runId: ctx.runId,
-                idemKey: dispatchedIdemKey(ctx.runId, callId),
-                payload: {
-                    step: ctx.step,
-                    callId,
-                    subagentId: plan.childConversationId,
-                    childRunId,
-                    agentType: plan.agentType,
-                    description: input.description,
-                    resumed: plan.resumed,
-                    model: { provider: plan.model.provider, model: plan.model.model },
-                    ...(plan.tierFallback && { tierFallback: true }),
-                    ...(a.forSkill !== undefined && { invokedSeq: a.forSkill.seq }),
-                },
-            },
-        ], t);
-        await audit(t, {
-            actorAccountId: ctx.accountId,
-            orgId: ctx.orgId,
-            action: "subagent.dispatched",
-            target: plan.childConversationId,
-            detail: {
-                parentConversationId: ctx.conversationId,
-                parentRunId: ctx.runId,
+        const gates = await orgAgentGates(t, a, plan.agentId, plan.agentType, plan.resumed);
+        if ("refused" in gates)
+            return { kind: "gate", outcome: gates.refused };
+        checked = gates.checked;
+    }
+    const task = await child(t, checked);
+    if (task === null)
+        return null;
+    await t
+        .insertInto("runs")
+        .values({
+        id: childRunId,
+        conversation_id: plan.childConversationId,
+        status: "queued",
+        agent_version: plan.agentVersion,
+        trigger_account_id: ctx.accountId,
+        trigger_seq: task.seq,
+    })
+        .execute();
+    await t
+        .insertInto("subagent_dispatches")
+        .values({
+        parent_run_id: ctx.runId,
+        parent_call_id: callId,
+        parent_conversation_id: ctx.conversationId,
+        step: ctx.step,
+        child_conversation_id: plan.childConversationId,
+        child_run_id: childRunId,
+        resumed: plan.resumed,
+    })
+        .execute();
+    const [dispatched] = await d.eventLog.appendIn(ctx.conversationId, [
+        {
+            type: "subagent_dispatched",
+            runId: ctx.runId,
+            idemKey: dispatchedIdemKey(ctx.runId, callId),
+            payload: {
+                step: ctx.step,
                 callId,
+                subagentId: plan.childConversationId,
+                childRunId,
                 agentType: plan.agentType,
-                source: plan.source,
-                ...(plan.source === "agent" && {
-                    agentId: plan.agentId,
-                    agentVersion: plan.agentVersion,
-                }),
+                description: input.description,
                 resumed: plan.resumed,
-                childRunId,
+                model: { provider: plan.model.provider, model: plan.model.model },
+                ...(plan.tierFallback && { tierFallback: true }),
+                ...(a.forSkill !== undefined && { invokedSeq: a.forSkill.seq }),
             },
-        });
-        return {
-            kind: "written",
-            childSeq: task.seq,
-            parentSeq: dispatched.seq,
-        };
+        },
+    ]);
+    await audit(t, {
+        actorAccountId: ctx.accountId,
+        orgId: ctx.orgId,
+        action: "subagent.dispatched",
+        target: plan.childConversationId,
+        detail: {
+            parentConversationId: ctx.conversationId,
+            parentRunId: ctx.runId,
+            callId,
+            agentType: plan.agentType,
+            source: plan.source,
+            ...(plan.source === "agent" && {
+                agentId: plan.agentId,
+                agentVersion: plan.agentVersion,
+            }),
+            resumed: plan.resumed,
+            childRunId,
+        },
     });
+    return {
+        kind: "written",
+        childRunId,
+        childSeq: task.seq,
+        parentSeq: dispatched.seq,
+    };
+}
+async function commit(d, a, plan, 
+/** Writes the child's events; `checked` is the org agent version the in-lock gates passed. */
+child) {
+    const { ctx } = a;
+    const out = await d.commitDispatch(a, plan, child);
     if (out === null)
         return null;
     if (out.kind === "existing") {
@@ -464,6 +458,7 @@ child) {
         return out.outcome;
     await d.eventLog.notify(plan.childConversationId, out.childSeq);
     await d.eventLog.notify(ctx.conversationId, out.parentSeq);
+    const childRunId = out.childRunId;
     const jobId = runJobId(plan.childConversationId, out.childSeq);
     try {
         await d.enqueue({ runId: childRunId, conversationId: plan.childConversationId }, jobId, "subagent");

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

@@ -1,6 +1,9 @@
-import type { Transaction } from "kysely";
 import { type KernelConfig } from "../../config/schema.js";
-import type { KernelDatabase, KernelDb } from "../../db/kernel-schema.js";
+import type { KernelSchemaDb } from "../../db/kernel-schema.js";
+/** The config the limits read (`KernelConfigService`, live: `subagents.*` is hot). */
+export interface SubagentsConfig {
+    get(): Pick<KernelConfig, "subagents">;
+}
 /** The sub-agent limits of one parent run (sub-agents spec §8.2). */
 export interface SubagentLimits {
     maxConcurrentPerRun: number;
@@ -14,10 +17,12 @@ export declare const SUBAGENT_LIMIT_DEFAULTS: SubagentLimits;
  * `subagentLimitOverrides`, value by value, over the hot config `subagents.*`. Read live (no cache),
  * in the caller's transaction when one is given, so every replica applies a change at once.
  */
-export declare function subagentLimits(db: KernelDb | Transaction<KernelDatabase>, config: () => Pick<KernelConfig, "subagents">, orgId: string): Promise<SubagentLimits>;
+export declare function subagentLimits(
+/** The pool, or the context's handle (a `@Transactional` caller's transaction). */
+db: KernelSchemaDb, config: SubagentsConfig, orgId: string): Promise<SubagentLimits>;
 /**
  * Whether the sub-agents of `parentRunId` have used their token budget (§8.3): its
  * `subagent_tokens_used`, read fresh, at or over `maxTokensPerRun`. A sub-agent's step checks it
  * before every model request and ends its run with `budget` when it is.
  */
-export declare function subagentBudgetUsedUp(db: KernelDb, config: () => Pick<KernelConfig, "subagents">, orgId: string, parentRunId: string): Promise<boolean>;
+export declare function subagentBudgetUsedUp(db: KernelSchemaDb, config: SubagentsConfig, orgId: string, parentRunId: string): Promise<boolean>;

package/dist/runtime/subagents/limits.js

@@ -7,8 +7,10 @@ export const SUBAGENT_LIMIT_DEFAULTS = KernelConfigSchema.shape.subagents.parse(
  * `subagentLimitOverrides`, value by value, over the hot config `subagents.*`. Read live (no cache),
  * in the caller's transaction when one is given, so every replica applies a change at once.
  */
-export async function subagentLimits(db, config, orgId) {
-    const base = config().subagents;
+export async function subagentLimits(
+/** The pool, or the context's handle (a `@Transactional` caller's transaction). */
+db, config, orgId) {
+    const base = config.get().subagents;
     const over = await readSubagentLimitOverride(db, orgId);
     return {
         maxConcurrentPerRun: over?.maxConcurrentPerRun ?? base.maxConcurrentPerRun,

package/dist/runtime/subagents/org-agents.d.ts

@@ -1,5 +1,5 @@
 import { type AgentDefinition } from "../../agents/definition.js";
-import type { KernelDb } from "../../db/kernel-schema.js";
+import type { KernelSchemaDb } from "../../db/kernel-schema.js";
 /**
  * The gates an org agent sub-agent passes (spec §5.5), checked at every dispatch and every
  * follow-up: `deleted` (the agent is gone, or not of this org), `allowlist` (the parent agent's
@@ -22,7 +22,7 @@ export type OrgAgentCheck = {
  * dispatches at once). On success returns the agent's current version and definition, which the
  * caller freezes as is (never read again, so the frozen version is the one the gates saw).
  */
-export declare function checkOrgAgent(db: KernelDb, a: {
+export declare function checkOrgAgent(db: KernelSchemaDb, a: {
     orgId: string;
     parentDefinition: Pick<AgentDefinition, "subagents">;
     agentId: string;
@@ -32,12 +32,12 @@ export declare function checkOrgAgent(db: KernelDb, a: {
  * The parent agent's current definition (the allowlist gate reads it, not the run's version), or
  * null when the agent no longer exists or is deleted.
  */
-export declare function currentAgentDefinition(db: KernelDb, agentId: string): Promise<AgentDefinition | null>;
+export declare function currentAgentDefinition(db: KernelSchemaDb, agentId: string): Promise<AgentDefinition | null>;
 /**
  * Audits a refused org agent dispatch (`subagent.refused`, spec §5.5): actor the person who
  * started the parent run, target the refused agent, so its owner can see attempts to use it.
  */
-export declare function auditRefusal(db: KernelDb, a: {
+export declare function auditRefusal(db: KernelSchemaDb, a: {
     orgId: string;
     triggerAccountId: string;
     agentId: string;

package/dist/runtime/subagents/org-agents.js

@@ -1,6 +1,7 @@
-import { isAgentVisibleTo } from "../../agents/agents.service.js";
+import { isAgentVisibleTo } from "../../agents/agent-lookup.js";
 import { normalizeStoredDefinition } from "../../agents/definition.js";
 import { audit } from "../../identity/audit.js";
+import { normalizeStoredDefinitionIn } from "../../tools/legacy-data.js";
 /**
  * Checks the gates for dispatching `agentId` from a parent whose current definition is
  * `parentDefinition` (read live by the caller: R5, removing an allowlist entry stops new
@@ -23,7 +24,7 @@ export async function checkOrgAgent(db, a) {
     if (!(a.parentDefinition.subagents?.agents ?? []).some((x) => x.agentId === a.agentId)) {
         return { ok: false, gate: "allowlist" };
     }
-    const definition = normalizeStoredDefinition(row.definition);
+    const definition = await normalizeStoredDefinitionIn(db, a.orgId, row.definition);
     if (definition.subagents?.dispatchable !== true)
         return { ok: false, gate: "dispatchable" };
     if (!(await isAgentVisibleTo(db, a.agentId, a.triggerAccountId))) {

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

@@ -1,5 +1,5 @@
 import type { Logger } from "@capybara-hq/plugin-sdk";
-import type { KernelDb } from "../../db/kernel-schema.js";
+import type { KernelSchemaDb } 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. */
@@ -10,7 +10,7 @@ export interface SubagentStep {
     step: number;
 }
 export interface SubagentProgressDeps {
-    db: KernelDb;
+    db: KernelSchemaDb;
     bus: {
         publish(topic: string, payload: unknown): Promise<void>;
     };

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

@@ -1,5 +1,5 @@
 import type { AgentDefinition } from "../../agents/definition.js";
-import type { KernelDb } from "../../db/kernel-schema.js";
+import type { KernelSchemaDb } 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.
@@ -31,7 +31,7 @@ export declare const templateType: (plugin: string, name: string) => string;
  * 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[]>;
+export declare function resolveRoster(db: KernelSchemaDb, 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
@@ -45,10 +45,10 @@ export declare const isGeneralAlias: (agent: string) => boolean;
  * `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
+ * 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<{
+export declare function resolveSkillForkType(db: KernelSchemaDb, 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

@@ -1,4 +1,4 @@
-import { SUBAGENT_ROSTER_MAX } from "../../agents/agents.service.js";
+import { SUBAGENT_ROSTER_MAX } from "../../agents/definition.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). */
@@ -90,7 +90,7 @@ export const isGeneralAlias = (agent) => GENERAL_ALIASES.has(agent);
  * `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
+ * 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) {

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

@@ -1,21 +1,19 @@
-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 type { KernelSchemaDb } 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 LoopContext, type 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
+ * 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). */
@@ -109,15 +107,16 @@ export declare const recordedSkillForks: (eventLog: Pick<EventLog, "append" | "f
     payload: unknown;
 }[]) => SkillForks;
 /**
- * In the transaction `t` of a run's terminal path (or the wait sweep): the run's fork invocation
+ * In the transaction 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
+ * 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<{
+export declare function pairStoppedForks(
+/** The caller's transaction (the context's handle). */
+t: KernelSchemaDb, eventLog: EventLog, runId: string): Promise<{
     callIds: string[];
     toSeq: number | null;
 }>;
-export {};

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

@@ -1,9 +1,18 @@
 import { ApiError } from "../../errors.js";
 import { AGENT_STOPPED_WITH_RUN_TEXT } from "../../tools/builtins/agent.js";
-import { subagentsWait } from "../../tools/pipeline.js";
+import { subagentsWait } from "../loop.js";
 import { TERMINAL_STATUSES } from "../run-finish.js";
 import { childResult, dispatchOfCall, finishedEvent } from "./child.js";
 import { dispatchSubagent } 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.
+ */
 /** 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). */
@@ -146,7 +155,7 @@ export async function advanceSkillForks(d, a) {
 }
 const suspend = (d, ctx) => ({
     kind: "suspend",
-    waitingFor: subagentsWait(ctx.runId, FORK_STEP, d.config()),
+    waitingFor: subagentsWait(ctx.runId, FORK_STEP, d.config.get()),
 });
 /** The live handler for the loop (`LoopDeps.skillForks`). */
 export const liveSkillForks = (d) => ({
@@ -178,14 +187,16 @@ export const recordedSkillForks = (eventLog, recorded) => ({
     },
 });
 /**
- * In the transaction `t` of a run's terminal path (or the wait sweep): the run's fork invocation
+ * In the transaction 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
+ * 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) {
+export async function pairStoppedForks(
+/** The caller's transaction (the context's handle). */
+t, eventLog, runId) {
     const none = { callIds: [], toSeq: null };
     const run = await t
         .selectFrom("runs as r")
@@ -254,6 +265,6 @@ export async function pairStoppedForks(t, eventLog, runId) {
             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);
+    const out = await eventLog.appendIn(conversationId, events);
     return { callIds: [callId], toSeq: Math.max(...out.map((e) => e.seq)) };
 }

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

@@ -0,0 +1,40 @@
+import type { ExtensionContext } from "@capybara-hq/plugin-sdk";
+import { EventLog } from "../../conversations/event-log.js";
+import { KernelConfigService } from "../../infra/config/kernel-config.service.js";
+import { KernelDb } from "../../infra/database/kernel-db.js";
+import { TransactionHost } from "../../infra/database/transaction-host.js";
+import type { KernelLogger } from "../../log.js";
+import { ModelPurposesService } from "../../models/purposes.js";
+import { SkillInvoker } from "../../skills/invoke.js";
+import { ProviderRegistry } from "../providers.js";
+import { RunJobs } from "../run-jobs.js";
+import { type ChildWriter, type DispatchArgs, type DispatchCommit, type DispatchOutcome, type DispatchPlan } from "./dispatch.js";
+import { type SubagentStep } from "./progress.js";
+import { type SkillForkDeps, type SkillForks } from "./skill-fork.js";
+/**
+ * Sub-agents (phase C, spec §7) and forked skills (phase D): the `Agent` tool's dispatch (the
+ * tool pipeline calls {@link dispatch}), a run's fork invocation ({@link skillForks}, the loop's
+ * `prepare`) and a child step's progress on the parent's stream ({@link progress}). Child runs go
+ * to the sub-agent run queue through {@link RunJobs}. The child lifecycle after dispatch (a
+ * finished child resumes its parent, a stopped parent stops its children) is the waits'
+ * (`Waits.childFinished` / `stopChildren`).
+ */
+export declare class SubagentsService {
+    private readonly bus;
+    private readonly log;
+    readonly txHost: TransactionHost;
+    /** The dispatch's dependencies (`dispatch.ts`, `skill-fork.ts`). */
+    readonly deps: SkillForkDeps;
+    /** The live fork handler of the loop (`LoopDeps.skillForks`). */
+    readonly skillForks: SkillForks;
+    constructor(kdb: KernelDb, eventLog: EventLog, purposes: ModelPurposesService, registry: ProviderRegistry, config: KernelConfigService, jobs: RunJobs, invoker: SkillInvoker, bus: ExtensionContext["bus"], log: KernelLogger, txHost: TransactionHost);
+    /** Dispatches the sub-agent of one `Agent` call (`dispatchSubagent`). */
+    dispatch(a: DispatchArgs): Promise<DispatchOutcome>;
+    /** The dispatch's writes in a transaction of their own (see `commitDispatchIn`). */
+    commitDispatch(a: DispatchArgs, plan: DispatchPlan, child: ChildWriter): Promise<DispatchCommit | null>;
+    /** A sub-agent's finished step on its parent's stream (sub-agents spec §14.2). Never throws. */
+    progress(s: SubagentStep): Promise<void>;
+}
+/** Sub-agent dispatch (the tools domain's `Agent` tool and the run loop use it). */
+export declare class SubagentsModule {
+}