@capybara-hq/kernel 0.1.0-rc.4 → 0.1.0-rc.5

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

@@ -0,0 +1,95 @@
+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 type { ToolStepContext } from "../../tools/pipeline.js";
+import { RunJobs } from "../run-jobs.js";
+import { SubagentDeliveries } from "./deliveries.js";
+/** The message tools' test seams (`SUBAGENT_MESSAGES_HOOKS`; the kernel never provides them). */
+export interface SubagentMessagesHooks {
+    /**
+     * Called by {@link SubagentMessages.toChild} after it read whether the sub-agent has an active
+     * run and before it acts on that: a test ends the run here to race the send.
+     */
+    afterStatusRead?(childConversationId: string): Promise<void>;
+}
+/** Optional provider: {@link SubagentMessagesHooks} (tests). */
+export declare const SUBAGENT_MESSAGES_HOOKS: unique symbol;
+/**
+ * What a message tool call did. `logged`: its `tool_result` (and `tool.called` audit) is already
+ * in the log, written with the dispatch that started an idle sub-agent; otherwise the pipeline
+ * writes the result.
+ */
+export interface MessageOutcome {
+    content: string;
+    isError: boolean;
+    logged?: boolean;
+}
+/** Idempotency key of a report or note a sub-agent's call delivered to its parent. */
+export declare const toParentIdemKey: (runId: string, callId: string) => string;
+/**
+ * Messages between the agents of one tree (agent map spec §4.2, §4.3, §5): `SendMessage` and
+ * `SubagentHandback`, called by the tool pipeline.
+ *
+ * A message to a sub-agent ({@link toChild}) is a `user_message` in its log with
+ * `dispatch.kind: "message"`, idempotent by the sending call. While the sub-agent has an active run
+ * it is appended under the sub-agent's row lock, which every terminal path of its runs takes too:
+ * the run absorbs it at its next model call, or, when the run ends without another call, the end's
+ * `ensureRun` starts the next run from it (`RunQueue.childWakeIn`). An idle sub-agent is started
+ * again through the dispatch transaction (a follow-up: it counts as a dispatch and takes a
+ * concurrency slot, refused at the limits, agent map spec §6), with the gates of the sub-agent's
+ * type checked again and its frozen tools narrowed to what the sender's current version allows.
+ * A message never waits on a lock a running sub-agent holds while it waits for the sender's run
+ * row (the dispatch transaction locks the sub-agent's row only when it has no active run).
+ *
+ * A sub-agent's note or report to its parent ({@link toParent}) is one `subagent_delivery` in the
+ * parent's log (`SubagentDeliveries.deliverIn`), idempotent by the call.
+ */
+export declare class SubagentMessages {
+    private readonly kdb;
+    private readonly eventLog;
+    private readonly config;
+    private readonly deliveries;
+    readonly txHost: TransactionHost;
+    private readonly hooks?;
+    /** What the dispatch transaction of a restart needs (`commit`). */
+    private readonly deps;
+    constructor(kdb: KernelDb, eventLog: EventLog, config: KernelConfigService, jobs: RunJobs, log: KernelLogger, deliveries: SubagentDeliveries, txHost: TransactionHost, hooks?: SubagentMessagesHooks | undefined);
+    /** The restart's dispatch writes in a transaction of their own (see `commitDispatchIn`). */
+    private commitDispatch;
+    /** The context's handle (the transaction of a `@Transactional` method, else the pool). */
+    private get db();
+    /**
+     * `SendMessage` (agent map spec §4.2, §5.1): `to` is one of the caller's own sub-agents by id,
+     * or `"parent"` in a sub-agent. Anything else (a sibling, a grandchild, another conversation's
+     * sub-agent, an unknown id, `"parent"` at the root) is refused with the valid targets.
+     */
+    toChild(ctx: ToolStepContext, callId: string, childId: string, text: string, 
+    /** The pipeline's record of why the call was allowed (the `tool.called` audit of a restart). */
+    opts?: {
+        authorization?: Record<string, unknown>;
+    }): Promise<MessageOutcome>;
+    /**
+     * A sub-agent's note (`SendMessage` to `"parent"`) or report (`SubagentHandback`) to its parent
+     * (agent map spec §4.3, §5.2): one `subagent_delivery` of this run in the parent's log,
+     * idempotent by the call; an active parent run absorbs it, an idle parent is woken.
+     */
+    toParent(ctx: ToolStepContext, kind: "note" | "report", text: string, callId: string): Promise<MessageOutcome>;
+    /**
+     * Appends the message to a sub-agent whose run is active, under its row lock (a run's terminal
+     * write takes the same lock, so the run is still active when the message lands). Null when no
+     * run is active any more: the caller starts one.
+     */
+    private appendToRunning;
+    /**
+     * Starts an idle sub-agent again with the message (the dispatch transaction, `commit`): its row
+     * is locked only after no active run was found, and again checked under the lock. `"active"`
+     * when a run is active after all (the caller appends to it instead).
+     */
+    private restart;
+    /** The active run of a conversation, if any. */
+    private activeRunOf;
+    /** The unknown-target refusal, listing the caller's own sub-agents (newest first). */
+    private unknownTarget;
+}

package/dist/runtime/subagents/messages.js

@@ -0,0 +1,328 @@
+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, Optional } from "@nestjs/common";
+import { normalizeStoredDefinition } from "../../agents/definition.js";
+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 { Transactional } from "../../infra/database/transactional.decorator.js";
+import { KERNEL_LOGGER } from "../../infra/tokens.js";
+import { SEND_MESSAGE } from "../../tools/builtin-names.js";
+import { AGENT_REFUSALS } from "../../tools/builtins/agent.js";
+import { HANDBACK_FORK_TEXT, HANDBACK_NOT_A_CHILD_TEXT, HANDBACK_RESULT_TEXT, } from "../../tools/builtins/handback.js";
+import { PARENT_TARGET, SEND_MESSAGE_REFUSALS, SEND_TARGETS_LISTED, SENT_TO_PARENT_TEXT, sentToIdleText, sentToRunningText, } from "../../tools/builtins/send-message.js";
+import { ACTIVE_RUN_STATUSES, RunJobs } from "../run-jobs.js";
+import { deliveryRowOfChildRun, dispatchOfCall } from "./child.js";
+import { narrowFollowUp } from "./definition.js";
+import { SubagentDeliveries } from "./deliveries.js";
+import { commit, commitDispatchIn, orgAgentGates, sentMessageIdemKey, taskMessage, } from "./dispatch.js";
+import { findType, resolveRoster } from "./roster.js";
+/** Optional provider: {@link SubagentMessagesHooks} (tests). */
+export const SUBAGENT_MESSAGES_HOOKS = Symbol("SUBAGENT_MESSAGES_HOOKS");
+/** How often a send re-reads a sub-agent whose run started or ended while it acted. */
+const SEND_ATTEMPTS = 3;
+/** The sub-agent's state changed on every attempt (a run starting and ending each time). */
+const SEND_RETRY_TEXT = "The sub-agent changed state while the message was being sent; call SendMessage again.";
+const refused = (content) => ({ content, isError: true });
+/** Idempotency key of a report or note a sub-agent's call delivered to its parent. */
+export const toParentIdemKey = (runId, callId) => `subagent_delivery:${runId}:${callId}`;
+/**
+ * Messages between the agents of one tree (agent map spec §4.2, §4.3, §5): `SendMessage` and
+ * `SubagentHandback`, called by the tool pipeline.
+ *
+ * A message to a sub-agent ({@link toChild}) is a `user_message` in its log with
+ * `dispatch.kind: "message"`, idempotent by the sending call. While the sub-agent has an active run
+ * it is appended under the sub-agent's row lock, which every terminal path of its runs takes too:
+ * the run absorbs it at its next model call, or, when the run ends without another call, the end's
+ * `ensureRun` starts the next run from it (`RunQueue.childWakeIn`). An idle sub-agent is started
+ * again through the dispatch transaction (a follow-up: it counts as a dispatch and takes a
+ * concurrency slot, refused at the limits, agent map spec §6), with the gates of the sub-agent's
+ * type checked again and its frozen tools narrowed to what the sender's current version allows.
+ * A message never waits on a lock a running sub-agent holds while it waits for the sender's run
+ * row (the dispatch transaction locks the sub-agent's row only when it has no active run).
+ *
+ * A sub-agent's note or report to its parent ({@link toParent}) is one `subagent_delivery` in the
+ * parent's log (`SubagentDeliveries.deliverIn`), idempotent by the call.
+ */
+let SubagentMessages = class SubagentMessages {
+    kdb;
+    eventLog;
+    config;
+    deliveries;
+    txHost;
+    hooks;
+    /** What the dispatch transaction of a restart needs (`commit`). */
+    deps;
+    constructor(kdb, eventLog, config, jobs, log, deliveries, txHost, hooks) {
+        this.kdb = kdb;
+        this.eventLog = eventLog;
+        this.config = config;
+        this.deliveries = deliveries;
+        this.txHost = txHost;
+        this.hooks = hooks;
+        this.deps = {
+            eventLog,
+            enqueue: (data, jobId, kind) => jobs.enqueue(data, jobId, kind),
+            log,
+            commitDispatch: (a, plan, child) => this.commitDispatch(a, plan, child),
+        };
+    }
+    /** The restart's dispatch writes in a transaction of their own (see `commitDispatchIn`). */
+    commitDispatch(a, plan, child) {
+        return commitDispatchIn({ db: this.db, eventLog: this.eventLog, config: this.config }, a, plan, child);
+    }
+    /** The context's handle (the transaction of a `@Transactional` method, else the pool). */
+    get db() {
+        return this.kdb.db;
+    }
+    /**
+     * `SendMessage` (agent map spec §4.2, §5.1): `to` is one of the caller's own sub-agents by id,
+     * or `"parent"` in a sub-agent. Anything else (a sibling, a grandchild, another conversation's
+     * sub-agent, an unknown id, `"parent"` at the root) is refused with the valid targets.
+     */
+    async toChild(ctx, callId, childId, text, 
+    /** The pipeline's record of why the call was allowed (the `tool.called` audit of a restart). */
+    opts = {}) {
+        if (childId === PARENT_TARGET && ctx.parent !== undefined) {
+            return this.toParent(ctx, "note", text, callId);
+        }
+        const child = await this.db
+            .selectFrom("conversations")
+            .select(["id", "title", "subagent_type"])
+            .where("id", "=", childId)
+            .where("org_id", "=", ctx.orgId)
+            .where("kind", "=", "subagent")
+            .where("parent_conversation_id", "=", ctx.conversationId)
+            .where("deleted_at", "is", null)
+            .executeTakeFirst();
+        const started = child && (await this.eventLog.findByIdem(child.id, "subagent_started"));
+        if (!child || started?.type !== "subagent_started")
+            return this.unknownTarget(ctx, childId);
+        const target = { id: child.id, description: child.title ?? "" };
+        const { template } = started.payload;
+        const agentType = child.subagent_type ?? started.payload.agentType;
+        // a retried call (its holder died after sending): the same answer, nothing sent twice
+        const prior = await this.eventLog.findByIdem(child.id, sentMessageIdemKey(ctx.runId, callId));
+        if (prior && !(await dispatchOfCall(this.db, ctx.runId, callId))) {
+            return { content: sentToRunningText(target), isError: false };
+        }
+        // the sub-agent's type stays available to the sender (§4.1, checked at every message): an org
+        // agent passes its gates, any other type is still in the sender's roster
+        let current = ctx.agent;
+        if (template.source === "agent") {
+            const gates = await orgAgentGates(this.db, { ctx, callId }, template.id ?? "", agentType, true);
+            if ("refused" in gates)
+                return refused(SEND_MESSAGE_REFUSALS.notAvailable(child.id, agentType));
+            current = gates.checked.definition;
+        }
+        else {
+            const roster = await resolveRoster(this.db, ctx.orgId, ctx.agent, this.deps.log);
+            // a plugin template by its template id: an org template's, a linked copy's own or a
+            // platform template's, or an alias of the entry
+            const entry = template.source === "plugin"
+                ? roster.find((e) => e.source === "plugin" &&
+                    template.id !== undefined &&
+                    (e.templateId === template.id || e.aliasTemplateIds?.includes(template.id)))
+                : findType(roster, agentType);
+            if (entry?.source !== template.source) {
+                return refused(SEND_MESSAGE_REFUSALS.notAvailable(child.id, agentType));
+            }
+        }
+        const frozen = normalizeStoredDefinition(started.payload.definition);
+        for (let attempt = 0; attempt < SEND_ATTEMPTS; attempt++) {
+            const active = prior === undefined && (await this.activeRunOf(child.id)) !== undefined;
+            await this.hooks?.afterStatusRead?.(child.id);
+            if (active) {
+                const seq = await this.appendToRunning(ctx, callId, child.id, text, narrowFollowUp(frozen, current));
+                if (seq !== null) {
+                    await this.eventLog.notify(child.id, seq);
+                    return { content: sentToRunningText(target), isError: false };
+                }
+                continue;
+            }
+            const out = await this.restart(ctx, callId, text, target, opts.authorization, {
+                childConversationId: child.id,
+                agentType,
+                source: template.source,
+                agentId: template.source === "agent" ? (template.id ?? "") : ctx.agentId,
+                agentVersion: template.source === "agent" ? (template.version ?? ctx.agentVersion) : ctx.agentVersion,
+                resumed: true,
+                model: started.payload.definition.model,
+                tierFallback: false,
+            }, frozen);
+            if (out === "active")
+                continue;
+            return out;
+        }
+        return refused(SEND_RETRY_TEXT);
+    }
+    /**
+     * A sub-agent's note (`SendMessage` to `"parent"`) or report (`SubagentHandback`) to its parent
+     * (agent map spec §4.3, §5.2): one `subagent_delivery` of this run in the parent's log,
+     * idempotent by the call; an active parent run absorbs it, an idle parent is woken.
+     */
+    async toParent(ctx, kind, text, callId) {
+        if (ctx.parent === undefined)
+            return refused(HANDBACK_NOT_A_CHILD_TEXT);
+        const row = await deliveryRowOfChildRun(this.db, ctx.runId);
+        if (!row)
+            return refused(SEND_MESSAGE_REFUSALS.notAvailableHere);
+        // a fork invocation's parent run waits for the final reply (phase D, agent map spec §5.4)
+        if (row.forSkill === true)
+            return refused(HANDBACK_FORK_TEXT);
+        await this.deliveries.deliverIn(row, { kind, text }, { idemKey: toParentIdemKey(ctx.runId, callId) });
+        return {
+            content: kind === "report" ? HANDBACK_RESULT_TEXT : SENT_TO_PARENT_TEXT,
+            isError: false,
+        };
+    }
+    /**
+     * Appends the message to a sub-agent whose run is active, under its row lock (a run's terminal
+     * write takes the same lock, so the run is still active when the message lands). Null when no
+     * run is active any more: the caller starts one.
+     */
+    async appendToRunning(ctx, callId, childId, text, narrowed) {
+        await this.db
+            .selectFrom("conversations")
+            .select("id")
+            .where("id", "=", childId)
+            .forUpdate()
+            .executeTakeFirst();
+        if ((await this.activeRunOf(childId)) === undefined)
+            return null;
+        const [ev] = await this.eventLog.appendIn(childId, [
+            taskMessage(ctx, callId, text, narrowed, undefined, true),
+        ]);
+        return ev?.seq ?? null;
+    }
+    /**
+     * Starts an idle sub-agent again with the message (the dispatch transaction, `commit`): its row
+     * is locked only after no active run was found, and again checked under the lock. `"active"`
+     * when a run is active after all (the caller appends to it instead).
+     */
+    async restart(ctx, callId, text, target, authorization, plan, frozen) {
+        const a = {
+            ctx,
+            callId,
+            input: { description: target.description || target.id, prompt: text },
+            call: {
+                toolKey: SEND_MESSAGE,
+                authorization: authorization ?? { policy: "allow" },
+                startedAt: Date.now(),
+            },
+            sent: { content: sentToIdleText(target), refusals: SEND_MESSAGE_REFUSALS },
+        };
+        const out = await commit(this.deps, a, plan, async (t, checked) => {
+            const current = plan.source === "agent" ? checked?.definition : ctx.agent;
+            if (current === undefined)
+                throw new Error("org agent message without its checked version");
+            const activeRun = () => t
+                .selectFrom("runs")
+                .select("id")
+                .where("conversation_id", "=", plan.childConversationId)
+                .where("status", "in", ACTIVE_RUN_STATUSES)
+                .executeTakeFirst();
+            // an active sub-agent is not waited for here: its token append locks its row and then the
+            // sender's run row, which this transaction already holds (review I1 of phase C)
+            if (await activeRun())
+                return null;
+            // A brief inverted-order window remains: this transaction holds the tree's budget run
+            // (`commit`) and now takes the child's row, while a run of the child that started between the
+            // check above and this lock (a wake run, `RunQueue.childWakeIn`) takes the child's row and
+            // then the budget run in its token append (`StepLog.appendCounted`). PostgreSQL's deadlock
+            // detection aborts one of the two transactions and the other goes on: either this
+            // `SendMessage` call errors (nothing written; a repeat finds the running sub-agent and
+            // appends to it) or that step's append errors as any database error of a step does. Accepted
+            // rather than a lock reordering, for a window of a few statements.
+            await t
+                .selectFrom("conversations")
+                .select("id")
+                .where("id", "=", plan.childConversationId)
+                .forUpdate()
+                .executeTakeFirst();
+            if (await activeRun())
+                return null;
+            const [task] = await this.eventLog.appendIn(plan.childConversationId, [
+                taskMessage(ctx, callId, text, narrowFollowUp(frozen, current), undefined, true),
+            ]);
+            return task ?? null;
+        });
+        if (out === null)
+            return "active";
+        if (out.kind === "dispatched")
+            return { content: out.content, isError: false, logged: true };
+        // a gate revoked since the check above, under the dispatch's locks
+        if (out.content === AGENT_REFUSALS.agentNotAvailable(plan.agentType)) {
+            return refused(SEND_MESSAGE_REFUSALS.notAvailable(target.id, plan.agentType));
+        }
+        // a limit refusal counts the sub-agent's slot as free: when a run of it started meanwhile,
+        // the message goes to that run instead
+        if ((await this.activeRunOf(plan.childConversationId)) !== undefined)
+            return "active";
+        return refused(out.content);
+    }
+    /** The active run of a conversation, if any. */
+    activeRunOf(conversationId) {
+        return this.db
+            .selectFrom("runs")
+            .select("id")
+            .where("conversation_id", "=", conversationId)
+            .where("status", "in", ACTIVE_RUN_STATUSES)
+            .executeTakeFirst();
+    }
+    /** The unknown-target refusal, listing the caller's own sub-agents (newest first). */
+    async unknownTarget(ctx, to) {
+        const rows = await this.db
+            .selectFrom("conversations")
+            .select(["id", "title"])
+            .where("org_id", "=", ctx.orgId)
+            .where("kind", "=", "subagent")
+            .where("parent_conversation_id", "=", ctx.conversationId)
+            .where("deleted_at", "is", null)
+            .orderBy("created_at", "desc")
+            .orderBy("id")
+            .limit(SEND_TARGETS_LISTED + 1)
+            .execute();
+        const listed = rows.slice(0, SEND_TARGETS_LISTED);
+        let more = 0;
+        if (rows.length > SEND_TARGETS_LISTED) {
+            const total = await this.db
+                .selectFrom("conversations")
+                .select((eb) => eb.fn.countAll().as("n"))
+                .where("org_id", "=", ctx.orgId)
+                .where("kind", "=", "subagent")
+                .where("parent_conversation_id", "=", ctx.conversationId)
+                .where("deleted_at", "is", null)
+                .executeTakeFirstOrThrow();
+            more = Number(total.n) - listed.length;
+        }
+        return refused(SEND_MESSAGE_REFUSALS.unknownTarget(to, listed.map((r) => ({ id: r.id, description: r.title ?? "" })), { hasParent: ctx.parent !== undefined, more }));
+    }
+};
+__decorate([
+    Transactional({ propagation: "requires_new" })
+], SubagentMessages.prototype, "commitDispatch", null);
+__decorate([
+    Transactional({ propagation: "requires_new" })
+], SubagentMessages.prototype, "appendToRunning", null);
+SubagentMessages = __decorate([
+    Injectable(),
+    __param(0, Inject(KernelDb)),
+    __param(1, Inject(EventLog)),
+    __param(2, Inject(KernelConfigService)),
+    __param(3, Inject(RunJobs)),
+    __param(4, Inject(KERNEL_LOGGER)),
+    __param(5, Inject(SubagentDeliveries)),
+    __param(6, Inject(TransactionHost)),
+    __param(7, Optional()),
+    __param(7, Inject(SUBAGENT_MESSAGES_HOOKS))
+], SubagentMessages);
+export { SubagentMessages };

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

@@ -1,7 +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.
+ * The sub-agent preamble (spec §6.3, agent map spec §4.4, 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

@@ -1,11 +1,13 @@
 /**
- * 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.
+ * The sub-agent preamble (spec §6.3, agent map spec §4.4, 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.";
+    "questions. When you are done, hand your report back with SubagentHandback and include " +
+    "everything the agent that dispatched you needs; if you end your turn without handing back, " +
+    "your final reply is delivered as your report. While you work you can send that agent a short " +
+    'note with SendMessage to "parent", and messages from it may arrive in this conversation. If ' +
+    "you cannot finish, say what is missing and why.";

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

@@ -2,7 +2,7 @@ import type { Logger } from "@capybara-hq/plugin-sdk";
 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. */
+    /** The parent conversation: its topic and those of every conversation above it get the message. */
     parentConversationId: string;
     /** The child conversation (the sub-agent's id). */
     conversationId: string;
@@ -17,10 +17,12 @@ export interface SubagentProgressDeps {
     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.
+ * Publishes `{ kind: "subagent_progress", subagentId, step, toolCalls, lastToolKey? }` after a
+ * child step on the topic of every ancestor (sub-agents spec §14.2; agent map spec §8: the root's
+ * agent map follows a sub-agent at any depth), `subagentId` naming the progressing agent.
+ * Ephemeral: not in any log, lost on reconnect (the tree and summary APIs have 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

@@ -1,11 +1,14 @@
 import { sql } from "kysely";
 import { conversationTopic } from "../../conversations/event-log.js";
+import { conversationAncestors } from "../../conversations/tree.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.
+ * Publishes `{ kind: "subagent_progress", subagentId, step, toolCalls, lastToolKey? }` after a
+ * child step on the topic of every ancestor (sub-agents spec §14.2; agent map spec §8: the root's
+ * agent map follows a sub-agent at any depth), `subagentId` naming the progressing agent.
+ * Ephemeral: not in any log, lost on reconnect (the tree and summary APIs have 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 {
@@ -24,7 +27,9 @@ export async function publishSubagentProgress(d, s) {
             toolCalls: Number(row?.n ?? 0),
             ...(row?.last != null && { lastToolKey: row.last }),
         };
-        await d.bus.publish(conversationTopic(s.parentConversationId), msg);
+        const ancestors = await conversationAncestors(d.db, s.conversationId);
+        const topics = new Set([s.parentConversationId, ...ancestors]);
+        await Promise.all([...topics].map((id) => d.bus.publish(conversationTopic(id), msg)));
     }
     catch (err) {
         d.log.warn("sub-agent progress publish failed", {

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

@@ -0,0 +1,30 @@
+import type { EventPayload } from "../../conversations/events.js";
+type Delivery = EventPayload<"subagent_delivery">;
+/**
+ * The model-visible text of a `subagent_delivery` event, rendered as a system message in the
+ * parent's request (agent map spec §4.5):
+ *
+ * ```
+ * Sub-agent <id> ("<description>") handed back a report:
+ * <text>
+ * Sub-agent <id> ("<description>") sent a message:
+ * <text>
+ * Sub-agent <id> ("<description>") completed; its report was already delivered.
+ * Sub-agent <id> ("<description>") completed. Final reply:
+ * <text>
+ * Sub-agent <id> ("<description>") failed (<code>): <message>
+ * Sub-agent <id> ("<description>") stopped by the user.
+ * ```
+ *
+ * A finish uses `agentResultText`'s status wording (`subagentStatusText`, with the error code and
+ * who stopped it); after a handback only the status itself (up to its first `;`), and without a
+ * reply `It produced no reply.` A failed finish's `text` is the error message, an aborted one has
+ * none. Read only from the payload, so a replay renders it identically.
+ *
+ * A run that handed back and then `completed` no longer gets a finished delivery (acceptance
+ * 2026-11-07, `SubagentDeliveries.finishIn`); the "already delivered" line stays for the other
+ * statuses after a handback and for the completed ones older logs recorded, which rebuild byte for
+ * byte. The switch is the delivery's absence in the log, so it needs no `DriftReason`.
+ */
+export declare function renderSubagentDelivery(p: Delivery): string;
+export {};

package/dist/runtime/subagents/render.js

@@ -0,0 +1,53 @@
+import { subagentStatusText } from "./status.js";
+/**
+ * The model-visible text of a `subagent_delivery` event, rendered as a system message in the
+ * parent's request (agent map spec §4.5):
+ *
+ * ```
+ * Sub-agent <id> ("<description>") handed back a report:
+ * <text>
+ * Sub-agent <id> ("<description>") sent a message:
+ * <text>
+ * Sub-agent <id> ("<description>") completed; its report was already delivered.
+ * Sub-agent <id> ("<description>") completed. Final reply:
+ * <text>
+ * Sub-agent <id> ("<description>") failed (<code>): <message>
+ * Sub-agent <id> ("<description>") stopped by the user.
+ * ```
+ *
+ * A finish uses `agentResultText`'s status wording (`subagentStatusText`, with the error code and
+ * who stopped it); after a handback only the status itself (up to its first `;`), and without a
+ * reply `It produced no reply.` A failed finish's `text` is the error message, an aborted one has
+ * none. Read only from the payload, so a replay renders it identically.
+ *
+ * A run that handed back and then `completed` no longer gets a finished delivery (acceptance
+ * 2026-11-07, `SubagentDeliveries.finishIn`); the "already delivered" line stays for the other
+ * statuses after a handback and for the completed ones older logs recorded, which rebuild byte for
+ * byte. The switch is the delivery's absence in the log, so it needs no `DriftReason`.
+ */
+export function renderSubagentDelivery(p) {
+    const head = `Sub-agent ${p.subagentId} (${JSON.stringify(p.description)})`;
+    switch (p.kind) {
+        case "report":
+            return `${head} handed back a report:\n${p.text}`;
+        case "note":
+            return `${head} sent a message:\n${p.text}`;
+        case "finished": {
+            const status = subagentStatusText(p.status ?? "completed", {
+                errorCode: p.errorCode,
+                abortedBy: p.abortedBy,
+            });
+            if (p.handedBack === true) {
+                return `${head} ${status.split(";")[0]}; its report was already delivered.`;
+            }
+            const text = p.text.trim();
+            if (p.status === "failed")
+                return text === "" ? `${head} ${status}.` : `${head} ${status}: ${text}`;
+            if (p.status === "aborted" || p.status === "timed_out")
+                return `${head} ${status}.`;
+            return text === ""
+                ? `${head} ${status}. It produced no reply.`
+                : `${head} ${status}. Final reply:\n${p.text}`;
+        }
+    }
+}