@capybara-hq/kernel 0.1.0-rc.2 → 0.1.0-rc.21

package/dist/runtime/subagents/definition.js

@@ -1,13 +1,11 @@
 import { SKILL_ENTRY_FILE, sanitizeParams, } from "@capybara-hq/plugin-sdk";
+import { canonicalDisabledTools, } from "../../agents/definition.js";
 import { loadTemplates } from "../../agents/templates.js";
 import { ApiError } from "../../errors.js";
 import { PINNED_SKILLS_LIMITS } from "../../skills/catalog.js";
-import { toolKey } from "../../tools/naming.js";
-/**
- * Tools a sub-agent never gets (spec §5.3, §5.5): `agent` (depth 1), `ask_user` (the person does not
- * see the child), `sandbox_deliver` (delivering files is the parent's job) and `skill_write`.
- */
-export const CHILD_REMOVED_TOOLS = ["agent", "ask_user", "sandbox_deliver", "skill_write"];
+import { selectedSkills } from "../../skills/usable.js";
+import { AGENT_TOOL, CHILD_REMOVED_TOOLS } from "../../tools/builtin-names.js";
+export { CHILD_REMOVED_TOOLS } from "../../tools/builtin-names.js";
 /**
  * The roster entry's template is gone (an inline template edited away, a plugin template
  * uninstalled) between resolving the roster and reading it. The dispatch refuses the call as an
@@ -25,7 +23,8 @@ const RANK = { ask: 1, deny: 2 };
 const isPolicy = (p) => p === "ask" || p === "deny";
 /**
  * `base` with `over` applied on top, the stricter value winning per key (`deny` > `ask`). Values
- * other than `ask` / `deny` (stored template data is not re-validated) are skipped on both sides.
+ * other than `ask` / `deny` (stored template data is not re-validated; an agent's connector-tool
+ * `allow`, which the policy check reads from the agent's current version) are skipped on both sides.
  */
 export function stricterPolicies(base, over) {
     const out = {};
@@ -41,73 +40,28 @@ export function stricterPolicies(base, over) {
     }
     return out;
 }
-async function loadConnectors(db, orgId, refs) {
-    const ids = [...new Set(refs.flatMap((r) => (r.kind === "connector" ? [r.connectorId] : [])))];
-    const out = new Map();
-    if (ids.length === 0)
-        return out;
-    const rows = await db
-        .selectFrom("connectors")
-        .select(["id", "slug"])
-        .where("org_id", "=", orgId)
-        .where("deleted_at", "is", null)
-        .where("id", "in", ids)
-        .execute();
-    const tools = rows.length === 0
-        ? []
-        : await db
-            .selectFrom("connector_tools")
-            .select(["connector_id", "name"])
-            .where("connector_id", "in", rows.map((r) => r.id))
-            .orderBy("name")
-            .execute();
-    for (const r of rows) {
-        out.set(r.id, {
-            slug: r.slug,
-            tools: tools.filter((t) => t.connector_id === r.id).map((t) => t.name),
-        });
-    }
-    return out;
-}
 /**
- * Narrows tool refs by resolved key (spec §5.3): keeps a key when `allow` (if given) lists it and
- * neither `deny` nor {@link CHILD_REMOVED_TOOLS} does. A connector ref with `tools: "all"` stays
- * live only when nothing can narrow it (no allowlist and no deny key under `<slug>__`), so a tool
- * the connector gains later never slips past the template; otherwise it becomes the kept names, or
- * is dropped. A connector that no longer exists keeps its ref only without an allowlist.
+ * A child's key filter (tools default-on spec §4): `deny` = the parent's own filter's (a nested
+ * child), {@link CHILD_REMOVED_TOOLS}, `Agent` when the child is at the depth limit, and the
+ * template's `disallowedTools`; `allow` = the template's `tools` allowlist met with the parent's
+ * (absent on both = everything the parent has). Keys are deduplicated in first-seen order.
  */
-function narrowTools(refs, connectors, allow, deny) {
-    const removed = new Set(CHILD_REMOVED_TOOLS);
-    const keep = (key) => !removed.has(key) && !deny.has(key) && (allow === null || allow.has(key));
-    const out = [];
-    for (const ref of refs) {
-        if (ref.kind === "builtin") {
-            if (keep(ref.name))
-                out.push(ref);
-        }
-        else if (ref.kind === "plugin") {
-            if (keep(toolKey(ref.plugin, ref.name)))
-                out.push(ref);
-        }
-        else {
-            const c = connectors.get(ref.connectorId);
-            if (!c) {
-                if (allow === null)
-                    out.push(ref);
-                continue;
-            }
-            const prefix = toolKey(c.slug, "");
-            if (ref.tools === "all" && allow === null && ![...deny].some((k) => k.startsWith(prefix))) {
-                out.push(ref);
-                continue;
-            }
-            const names = ref.tools === "all" ? c.tools : ref.tools;
-            const kept = names.filter((name) => keep(toolKey(c.slug, name)));
-            if (kept.length > 0)
-                out.push({ ...ref, tools: kept });
-        }
-    }
-    return out;
+function childFilter(removeAgent, template, parent) {
+    const deny = [
+        ...new Set([
+            ...(parent?.deny ?? []),
+            ...CHILD_REMOVED_TOOLS,
+            ...(removeAgent ? [AGENT_TOOL] : []),
+            ...(template?.disallowedTools ?? []),
+        ]),
+    ];
+    const own = template?.tools === undefined ? undefined : [...new Set(template.tools)];
+    const allow = own === undefined
+        ? parent?.allow
+        : parent?.allow === undefined
+            ? own
+            : own.filter((k) => parent.allow?.includes(k));
+    return { ...(allow !== undefined && { allow: [...allow] }), deny };
 }
 /**
  * The template's skills the parent selects (its `orgSkills` or the parent agent's own skills),
@@ -116,25 +70,17 @@ function narrowTools(refs, connectors, allow, deny) {
  * this order, the skill from the template's own plugin, the agent's own skill, the org skill (ties
  * by id), with a warning. Dropped ones get a warning.
  */
-async function pinnedFor(db, a, refs, byName) {
-    if (refs.length === 0)
+async function pinnedFor(db, a, refs, byName, 
+/** Further names the template lists (`selectedSkills`): resolved the same way, never pinned. */
+selected = []) {
+    if (refs.length === 0 && selected.length === 0)
         return { pinned: [], warnings: [] };
-    const orgSkills = a.parent.skills?.orgSkills ?? [];
-    const rows = (await db
-        .selectFrom("skills as s")
-        .innerJoin("skill_versions as v", (j) => j.onRef("v.skill_id", "=", "s.id").onRef("v.version", "=", "s.current_version"))
-        .leftJoin("catalog_items as c", "c.id", "s.catalog_item_id")
-        .select(["s.id", "s.name", "s.scope", "v.manifest", "c.name as plugin"])
-        .where("s.org_id", "=", a.orgId)
-        .where("s.deleted_at", "is", null)
-        .where((eb) => {
-        const own = eb.and([eb("s.scope", "=", "agent"), eb("s.agent_id", "=", a.parentAgentId)]);
-        return orgSkills.length === 0
-            ? own
-            : eb.or([own, eb.and([eb("s.scope", "=", "org"), eb("s.id", "in", orgSkills)])]);
-    })
-        .orderBy("s.id")
-        .execute()).map((r) => ({
+    // org and agent skills, linked org copies and platform skills on in the org (phase 2), by id
+    const rows = (await selectedSkills(db, {
+        orgId: a.orgId,
+        agentId: a.parentAgentId,
+        orgSkills: a.parent.skills?.orgSkills ?? [],
+    })).map((r) => ({
         id: r.id,
         name: r.name,
         scope: r.scope,
@@ -180,12 +126,19 @@ async function pinnedFor(db, a, refs, byName) {
         total += r.bytes;
         pinned.push(r.id);
     }
+    for (const ref of selected) {
+        if (refs.includes(ref))
+            continue;
+        if (!match(ref)) {
+            warnings.push(`The skill "${ref}" is not available: the agent does not select it.`);
+        }
+    }
     return { pinned, warnings };
 }
 /** The `effort` declaration of `model`, or null (or when the model cannot be resolved). */
-async function effortDecl(registry, model) {
+async function effortDecl(registry, orgId, model) {
     try {
-        const { info } = await registry.resolve(model);
+        const { info } = await registry.resolve(orgId, model);
         return info.parameters.find((p) => p.standard === "effort") ?? null;
     }
     catch {
@@ -221,6 +174,7 @@ async function resolveTier(d, orgId, parent, tier) {
 }
 /** `"{parent name} › {agent type}"`, within the 80-character name limit. */
 const childName = (parent, type) => `${parent} › ${type}`.slice(0, 80);
+const atMaxDepth = (a) => a.childDepth >= a.maxDepth;
 function orgAgentDefinition(d, a) {
     // the version the gates checked (checkOrgAgent), never read again here: a version saved in
     // between could be one the gates never saw (batch 3 review M1)
@@ -229,11 +183,17 @@ function orgAgentDefinition(d, a) {
     }
     const agentId = a.entry.agentId ?? "";
     const own = a.orgAgent.definition;
-    const { subagents: _subagents, skills, ...rest } = own;
+    // prompt files are authoring data: the child's model sees only `instructions` (their join), and
+    // `subagent_started.definition` keeps its shape (spec 2026-11-04 §3.3); its own `subagents`
+    // block stays: it is the roster the child dispatches from (agent map spec §4.1); pending
+    // connectors are authoring data too (ruling P4-6)
+    const { skills, instructionFiles: _files, pendingConnectors: _pending, ...rest } = own;
+    const { subagentTools: _filter, ...ownRest } = rest;
     const definition = {
-        ...rest,
+        ...ownRest,
         // its own tools, not intersected with the parent's; only the child-removed ones go
-        tools: narrowTools(own.tools, new Map(), null, new Set()),
+        disabledTools: own.disabledTools ?? [],
+        subagentTools: childFilter(atMaxDepth(a), null),
         // its policies, then the parent's on top, stricter wins (keys outside its tools are inert)
         toolPolicies: stricterPolicies(own.toolPolicies ?? {}, a.parent.toolPolicies ?? {}),
         ...(skills !== undefined && {
@@ -262,8 +222,10 @@ function orgAgentDefinition(d, a) {
  *   (`tierFallback`); a template `effort` is set when the resolved model declares it;
  * - `agent`: the org agent's version that passed the gates (`orgAgent`, from {@link checkOrgAgent}),
  *   its own tools minus the child-removed ones, its policies with the parent's on top (stricter
- *   wins), its skills and model; `tier` ignored.
- * The `subagents` block is never part of a child's definition (depth 1).
+ *   wins), its skills, model and `subagents` block; `tier` ignored.
+ * Nesting (agent map spec §4.1): `Agent` stays unless the child is at `maxDepth`; the frozen
+ * definition keeps a `subagents` block, the roster the child dispatches from: an org agent's own,
+ * otherwise the parent definition's (a general-purpose, inline or plugin child inherits it).
  */
 export async function effectiveDefinition(d, a) {
     if (a.entry.source === "agent")
@@ -282,17 +244,21 @@ export async function effectiveDefinition(d, a) {
         if (!row)
             throw new SubagentTypeGoneError(entry.type);
         template = row.template;
-        ref = { source: "plugin", id: row.id, version: row.version, plugin: row.plugin };
+        ref = {
+            source: "plugin",
+            id: row.id,
+            version: row.version,
+            ...(row.plugin ? { plugin: row.plugin } : {}),
+            ...(row.platformTemplateId !== undefined && { platformTemplateId: row.platformTemplateId }),
+        };
     }
-    const connectors = await loadConnectors(d.db, a.orgId, parent.tools);
-    const tools = narrowTools(parent.tools, connectors, template?.tools !== undefined ? new Set(template.tools) : null, new Set(template?.disallowedTools ?? []));
     const toolPolicies = stricterPolicies(parent.toolPolicies ?? {}, template?.toolPolicies ?? {});
-    const { pinned, warnings } = await pinnedFor(d.db, a, template?.skills ?? [], entry.source === "plugin" ? { plugin: entry.plugin } : null);
+    const { pinned, warnings } = await pinnedFor(d.db, a, template?.skills ?? [], entry.source === "plugin" ? { plugin: entry.plugin } : null, template?.selectedSkills ?? []);
     const tier = a.tier ?? template?.model ?? "inherit";
     const m = await resolveTier(d, a.orgId, parent, tier);
     let modelParams = m.modelParams;
     if (template?.effort !== undefined) {
-        const decl = await effortDecl(d.registry, m.model);
+        const decl = await effortDecl(d.registry, a.orgId, m.model);
         if (decl) {
             const v = sanitizeParams([decl], { [decl.key]: template.effort }).value[decl.key];
             if (v !== undefined)
@@ -308,7 +274,8 @@ export async function effectiveDefinition(d, a) {
         fallback: m.fallback,
         modelParams,
         fallbackParams: m.fallbackParams,
-        tools,
+        disabledTools: parent.disabledTools ?? [],
+        subagentTools: childFilter(atMaxDepth(a), template, parent.subagentTools),
         toolPolicies,
         ...((parentSkills !== undefined || pinned.length > 0) && {
             skills: {
@@ -316,6 +283,7 @@ export async function effectiveDefinition(d, a) {
                 ...(pinned.length > 0 && { pinned }),
             },
         }),
+        ...(parent.subagents !== undefined && { subagents: parent.subagents }),
     };
     return {
         definition,
@@ -326,57 +294,32 @@ export async function effectiveDefinition(d, a) {
         tierFallback: m.tierFallback,
     };
 }
-/**
- * The refs of `frozen` that `current` still has: a builtin or plugin tool by name, a connector by
- * id; a connector's `all` meets the other side's names (`all` on both stays `all`), and a
- * connector left with no names is dropped. Pure: a connector `current` lists is not looked up.
- */
-export function intersectTools(frozen, current) {
-    const out = [];
-    for (const ref of frozen) {
-        if (ref.kind === "builtin") {
-            if (current.some((c) => c.kind === "builtin" && c.name === ref.name))
-                out.push(ref);
-        }
-        else if (ref.kind === "plugin") {
-            if (current.some((c) => c.kind === "plugin" && c.plugin === ref.plugin && c.name === ref.name)) {
-                out.push(ref);
-            }
-        }
-        else {
-            const c = current.find((x) => x.kind === "connector" && x.connectorId === ref.connectorId);
-            if (!c)
-                continue;
-            if (c.tools === "all") {
-                out.push(ref);
-                continue;
-            }
-            const names = ref.tools === "all" ? c.tools : ref.tools.filter((n) => c.tools.includes(n));
-            if (names.length > 0)
-                out.push({ ...ref, tools: names });
-        }
-    }
-    return out;
-}
 /**
  * The narrowing of a follow-up (final review I1): `frozen` (the child's `subagent_started`
  * definition) against `current`, the definition a fresh dispatch would read now: the dispatching
  * parent run's version for `general` / inline / plugin children, the dispatched org agent's
  * current version for an org agent child (whose tools are its own at dispatch too, §5.5). Its
- * `orgSkills` keep only those `current` still selects; a pinned id that was one of the frozen org
- * skills goes with it (the agent's own skills stay).
+ * `disabledTools` are both lists together; its `orgSkills` keep only those `current` still
+ * selects; a pinned id that was one of the frozen org skills goes with it (the agent's own skills
+ * stay).
  */
 export function narrowFollowUp(frozen, current) {
-    const tools = intersectTools(frozen.tools, current.tools);
+    const disabledTools = canonicalDisabledTools([
+        ...(frozen.disabledTools ?? []),
+        ...(current.disabledTools ?? []),
+    ]);
     if (frozen.skills === undefined)
-        return { tools };
+        return { disabledTools };
     const frozenOrg = new Set(frozen.skills.orgSkills);
     const now = new Set(current.skills?.orgSkills ?? []);
     const orgSkills = frozen.skills.orgSkills.filter((id) => now.has(id));
     const pinned = frozen.skills.pinned?.filter((id) => !frozenOrg.has(id) || now.has(id));
-    return { tools, skills: { orgSkills, ...(pinned !== undefined && { pinned }) } };
+    return { disabledTools, skills: { orgSkills, ...(pinned !== undefined && { pinned }) } };
 }
-/** The definition a child run uses: the frozen one with its trigger's follow-up narrowing. */
+/**
+ * The definition a child run uses: the frozen one with its trigger's follow-up narrowing. A
+ * narrowing logged before tools were on by default (no `disabledTools`) narrows only skills.
+ */
 export function childRunDefinition(frozen, narrowed) {
     if (narrowed === undefined)
         return frozen;
@@ -388,5 +331,9 @@ export function childRunDefinition(frozen, narrowed) {
             orgSkills: narrowed.skills.orgSkills,
             ...(narrowed.skills.pinned !== undefined && { pinned: narrowed.skills.pinned }),
         };
-    return { ...rest, tools: narrowed.tools, ...(kept !== undefined && { skills: kept }) };
+    return {
+        ...rest,
+        ...(Array.isArray(narrowed.disabledTools) && { disabledTools: narrowed.disabledTools }),
+        ...(kept !== undefined && { skills: kept }),
+    };
 }

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

@@ -0,0 +1,71 @@
+import { EventLog } from "../../conversations/event-log.js";
+import type { EventPayload } from "../../conversations/events.js";
+import { KernelDb } from "../../infra/database/kernel-db.js";
+import { TransactionHost } from "../../infra/database/transaction-host.js";
+import { KernelEvents } from "../../infra/events/kernel-events.js";
+import type { KernelLogger } from "../../log.js";
+import { type DispatchRow } from "./child.js";
+/** What a caller of {@link SubagentDeliveries.deliverIn} gives; the rest comes from the dispatch. */
+export type DeliveryInput = Omit<EventPayload<"subagent_delivery">, "subagentId" | "childRunId" | "description" | "triggerAccountId">;
+/** Idempotency key of a child run's finished delivery (one per child run). */
+export declare const finishedDeliveryIdemKey: (childRunId: string) => string;
+/**
+ * Deliveries from a sub-agent to its parent conversation (agent map spec §4.5, §5.2): each is one
+ * model-visible, absorbable `subagent_delivery` event in the parent's log. A parent run that is
+ * active absorbs it at its next model call; an idle parent is woken from the `subagent.delivered`
+ * domain event (emitted after the commit, with the log's notify).
+ *
+ * A background child's run reaching a terminal state ({@link childFinished}) writes the
+ * display-only `subagent_finished` and a `finished` delivery in one transaction, both idempotent by
+ * the child run, so of two finishers (the worker and a stop, the orphan sweep) exactly one writes
+ * them. A run that handed back a report and then completed writes no delivery (acceptance
+ * 2026-11-07): the report already told the parent everything, and a content-free "completed" line
+ * only woke an idle parent for nothing and pushed the report away from the end of its request. Fork invocations (phase D, `for_skill`) do not deliver: their parent run waits on the child
+ * and writes the report itself (`advanceSkillForks`).
+ */
+export declare class SubagentDeliveries {
+    private readonly kdb;
+    private readonly eventLog;
+    private readonly events;
+    private readonly log;
+    readonly txHost: TransactionHost;
+    constructor(kdb: KernelDb, eventLog: EventLog, events: KernelEvents, log: Pick<KernelLogger, "warn">, txHost: TransactionHost);
+    /** The context's handle (the transaction of a `@Transactional` method, else the pool). */
+    private get db();
+    /**
+     * Appends one delivery of the dispatch `row` to the parent log, in the caller's transaction or
+     * one of its own: the description is the dispatch's (`subagent_dispatched`), the trigger account
+     * the child run's (a wake runs as that person, §7). Idempotent by `opts.idemKey` (a finish's
+     * default is {@link finishedDeliveryIdemKey}; a report or a note must name its own): under the
+     * parent conversation's row lock, an existing delivery returns null and writes nothing. After
+     * the commit: the log's notify and `subagent.delivered`. Returns the new event's seq.
+     */
+    deliverIn(row: DispatchRow, d: DeliveryInput, opts?: {
+        idemKey?: string;
+    }): Promise<number | null>;
+    /**
+     * A background child run reached a terminal state (agent map spec §4.5, §5.2): appends the
+     * parent's `subagent_finished` (display only) and a `finished` delivery in one transaction, for
+     * every run of a child conversation (dispatched, sent a message or woken;
+     * {@link deliveryRowOfChildRun}), each once by its run. The delivery
+     * carries the final reply when the run handed back no report, else no text and `handedBack`; a
+     * failed run's error message and code, an aborted run who stopped it. A run that handed back and
+     * then `completed` gets only `subagent_finished` (not model-visible, wakes nothing); the log's
+     * notify still announces it to viewers. A run of a conversation never dispatched, a fork
+     * invocation's child, or not terminal yet is left alone. True when this call wrote the finish.
+     */
+    childFinished(childRunId: string): Promise<boolean>;
+    /** {@link childFinished}'s transaction. */
+    private finishIn;
+    /**
+     * {@link finishIn} for a run that handed back and completed: only `subagent_finished`, written
+     * once under the parent conversation's row lock (idempotent by the child run), then the log's
+     * notify after the commit. No `subagent.delivered`: nothing model-visible arrived, so no wake.
+     * True when this call wrote it.
+     */
+    private finishSilentlyIn;
+    /** Whether the child run handed back a report (`SubagentHandback`) before it finished. */
+    private handedBack;
+    /** The dispatch's task label (`subagent_dispatched.description`), else the child's title. */
+    private descriptionOf;
+}

package/dist/runtime/subagents/deliveries.js

@@ -0,0 +1,228 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+import { Inject, Injectable } from "@nestjs/common";
+import { sql } from "kysely";
+import { EventLog } from "../../conversations/event-log.js";
+import { afterCommit } from "../../infra/database/after-commit.js";
+import { KernelDb } from "../../infra/database/kernel-db.js";
+import { TransactionHost } from "../../infra/database/transaction-host.js";
+import { Transactional } from "../../infra/database/transactional.decorator.js";
+import { KernelEvents } from "../../infra/events/kernel-events.js";
+import { KERNEL_LOGGER } from "../../infra/tokens.js";
+import { TERMINAL_STATUSES } from "../run-finish.js";
+import { childResult, deliveryRowOfChildRun, finishedEvent } from "./child.js";
+import { dispatchedIdemKey } from "./dispatch.js";
+/** Idempotency key of a child run's finished delivery (one per child run). */
+export const finishedDeliveryIdemKey = (childRunId) => `subagent_delivery:${childRunId}:finished`;
+/** The longest `subagent_delivery.text` (the event schema's bound). */
+const DELIVERY_TEXT_MAX = 200_000;
+/**
+ * Deliveries from a sub-agent to its parent conversation (agent map spec §4.5, §5.2): each is one
+ * model-visible, absorbable `subagent_delivery` event in the parent's log. A parent run that is
+ * active absorbs it at its next model call; an idle parent is woken from the `subagent.delivered`
+ * domain event (emitted after the commit, with the log's notify).
+ *
+ * A background child's run reaching a terminal state ({@link childFinished}) writes the
+ * display-only `subagent_finished` and a `finished` delivery in one transaction, both idempotent by
+ * the child run, so of two finishers (the worker and a stop, the orphan sweep) exactly one writes
+ * them. A run that handed back a report and then completed writes no delivery (acceptance
+ * 2026-11-07): the report already told the parent everything, and a content-free "completed" line
+ * only woke an idle parent for nothing and pushed the report away from the end of its request. Fork invocations (phase D, `for_skill`) do not deliver: their parent run waits on the child
+ * and writes the report itself (`advanceSkillForks`).
+ */
+let SubagentDeliveries = class SubagentDeliveries {
+    kdb;
+    eventLog;
+    events;
+    log;
+    txHost;
+    constructor(kdb, eventLog, events, log, txHost) {
+        this.kdb = kdb;
+        this.eventLog = eventLog;
+        this.events = events;
+        this.log = log;
+        this.txHost = txHost;
+    }
+    /** The context's handle (the transaction of a `@Transactional` method, else the pool). */
+    get db() {
+        return this.kdb.db;
+    }
+    /**
+     * Appends one delivery of the dispatch `row` to the parent log, in the caller's transaction or
+     * one of its own: the description is the dispatch's (`subagent_dispatched`), the trigger account
+     * the child run's (a wake runs as that person, §7). Idempotent by `opts.idemKey` (a finish's
+     * default is {@link finishedDeliveryIdemKey}; a report or a note must name its own): under the
+     * parent conversation's row lock, an existing delivery returns null and writes nothing. After
+     * the commit: the log's notify and `subagent.delivered`. Returns the new event's seq.
+     */
+    async deliverIn(row, d, opts = {}) {
+        const idemKey = opts.idemKey ?? (d.kind === "finished" ? finishedDeliveryIdemKey(row.childRunId) : undefined);
+        if (idemKey === undefined)
+            throw new Error(`a ${d.kind} delivery needs its idempotency key`);
+        const t = this.db;
+        const parent = row.parentConversationId;
+        await t
+            .selectFrom("conversations")
+            .select("id")
+            .where("id", "=", parent)
+            .forUpdate()
+            .executeTakeFirst();
+        const existing = await t
+            .selectFrom("conversation_events")
+            .select("seq")
+            .where("conversation_id", "=", parent)
+            .where("idem_key", "=", idemKey)
+            .executeTakeFirst();
+        if (existing)
+            return null;
+        const run = await t
+            .selectFrom("runs")
+            .select("trigger_account_id")
+            .where("id", "=", row.childRunId)
+            .executeTakeFirstOrThrow();
+        const [event] = await this.eventLog.appendIn(parent, [
+            {
+                type: "subagent_delivery",
+                idemKey,
+                payload: {
+                    subagentId: row.childConversationId,
+                    childRunId: row.childRunId,
+                    description: await this.descriptionOf(row),
+                    ...d,
+                    text: d.text.length > DELIVERY_TEXT_MAX ? d.text.slice(0, DELIVERY_TEXT_MAX) : d.text,
+                    triggerAccountId: run.trigger_account_id,
+                },
+            },
+        ]);
+        if (!event)
+            return null;
+        afterCommit(async () => {
+            await this.eventLog.notify(parent, event.seq);
+            await this.events.emit("subagent.delivered", { conversationId: parent });
+        });
+        return event.seq;
+    }
+    /**
+     * A background child run reached a terminal state (agent map spec §4.5, §5.2): appends the
+     * parent's `subagent_finished` (display only) and a `finished` delivery in one transaction, for
+     * every run of a child conversation (dispatched, sent a message or woken;
+     * {@link deliveryRowOfChildRun}), each once by its run. The delivery
+     * carries the final reply when the run handed back no report, else no text and `handedBack`; a
+     * failed run's error message and code, an aborted run who stopped it. A run that handed back and
+     * then `completed` gets only `subagent_finished` (not model-visible, wakes nothing); the log's
+     * notify still announces it to viewers. A run of a conversation never dispatched, a fork
+     * invocation's child, or not terminal yet is left alone. True when this call wrote the finish.
+     */
+    async childFinished(childRunId) {
+        const row = await deliveryRowOfChildRun(this.db, childRunId);
+        if (!row || row.forSkill === true)
+            return false;
+        const run = await this.db
+            .selectFrom("runs")
+            .select("status")
+            .where("id", "=", childRunId)
+            .executeTakeFirst();
+        if (!run || !TERMINAL_STATUSES.has(run.status))
+            return false;
+        const r = await childResult(this.eventLog, row);
+        if (!r) {
+            this.log.warn("sub-agent run is terminal without a terminal event", { childRunId });
+            return false;
+        }
+        return this.finishIn(row, r);
+    }
+    /** {@link childFinished}'s transaction. */
+    async finishIn(row, r) {
+        const { status, errorCode } = r.finished;
+        const handedBack = await this.handedBack(row);
+        if (handedBack && status === "completed")
+            return this.finishSilentlyIn(row, r.finished);
+        await this.eventLog.appendIn(row.parentConversationId, [finishedEvent(row, r.finished)]);
+        const text = handedBack
+            ? ""
+            : status === "failed"
+                ? (r.errorMessage ?? "")
+                : status === "aborted" || status === "timed_out"
+                    ? ""
+                    : r.reply;
+        const seq = await this.deliverIn(row, {
+            kind: "finished",
+            status,
+            text,
+            ...(handedBack && { handedBack: true }),
+            ...(errorCode !== undefined && { errorCode }),
+            ...(r.abortedBy !== undefined && { abortedBy: r.abortedBy }),
+        });
+        return seq !== null;
+    }
+    /**
+     * {@link finishIn} for a run that handed back and completed: only `subagent_finished`, written
+     * once under the parent conversation's row lock (idempotent by the child run), then the log's
+     * notify after the commit. No `subagent.delivered`: nothing model-visible arrived, so no wake.
+     * True when this call wrote it.
+     */
+    async finishSilentlyIn(row, finished) {
+        const parent = row.parentConversationId;
+        const event = finishedEvent(row, finished);
+        await this.db
+            .selectFrom("conversations")
+            .select("id")
+            .where("id", "=", parent)
+            .forUpdate()
+            .executeTakeFirst();
+        if (event.idemKey !== undefined && (await this.eventLog.findByIdem(parent, event.idemKey)))
+            return false;
+        const [written] = await this.eventLog.appendIn(parent, [event]);
+        if (!written)
+            return false;
+        afterCommit(() => this.eventLog.notify(parent, written.seq));
+        return true;
+    }
+    /** Whether the child run handed back a report (`SubagentHandback`) before it finished. */
+    async handedBack(row) {
+        const hit = await this.db
+            .selectFrom("conversation_events")
+            .select("seq")
+            .where("conversation_id", "=", row.parentConversationId)
+            .where("type", "=", "subagent_delivery")
+            .where(sql `payload ->> 'childRunId'`, "=", row.childRunId)
+            .where(sql `payload ->> 'kind'`, "=", "report")
+            .limit(1)
+            .executeTakeFirst();
+        return hit !== undefined;
+    }
+    /** The dispatch's task label (`subagent_dispatched.description`), else the child's title. */
+    async descriptionOf(row) {
+        const dispatched = await this.eventLog.findByIdem(row.parentConversationId, dispatchedIdemKey(row.parentRunId, row.parentCallId));
+        if (dispatched?.type === "subagent_dispatched")
+            return dispatched.payload.description;
+        const conv = await this.db
+            .selectFrom("conversations")
+            .select("title")
+            .where("id", "=", row.childConversationId)
+            .executeTakeFirst();
+        return conv?.title ?? "";
+    }
+};
+__decorate([
+    Transactional()
+], SubagentDeliveries.prototype, "deliverIn", null);
+__decorate([
+    Transactional()
+], SubagentDeliveries.prototype, "finishIn", null);
+SubagentDeliveries = __decorate([
+    Injectable(),
+    __param(0, Inject(KernelDb)),
+    __param(1, Inject(EventLog)),
+    __param(2, Inject(KernelEvents)),
+    __param(3, Inject(KERNEL_LOGGER)),
+    __param(4, Inject(TransactionHost))
+], SubagentDeliveries);
+export { SubagentDeliveries };