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

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

@@ -1,9 +1,18 @@
-import type { Transaction } from "kysely";
 import { type KernelConfig } from "../../config/schema.js";
-import type { KernelDatabase, KernelDb } from "../../db/kernel-schema.js";
-/** The sub-agent limits of one parent run (sub-agents spec §8.2). */
+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 an organization (sub-agents spec §8.2, agent map spec §6): the depth
+ * below the root, the active children of one conversation, and the dispatches and tokens of one
+ * tree, counted on its budget run ({@link budgetRunOf}). `maxDispatchesPerRun` and
+ * `maxTokensPerRun` of 0 mean no limit.
+ */
 export interface SubagentLimits {
-    maxConcurrentPerRun: number;
+    maxDepth: number;
+    maxConcurrentPerConversation: number;
     maxDispatchesPerRun: number;
     maxTokensPerRun: number;
 }
@@ -14,10 +23,25 @@ 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>;
+/**
+ * The budget run of `runId` (agent map spec §6): its `budget_run_id`, or the run itself when it has
+ * none (a person-triggered run opens its own window) or does not exist. The dispatch count and the
+ * token counter of a whole tree live on this run.
+ */
+export declare function budgetRunOf(db: KernelSchemaDb, runId: string): Promise<string>;
+/**
+ * The current budget window of the tree rooted at `rootConversationId` (agent map spec §6): its
+ * newest run that opened its own window (`budget_run_id` null: a person-triggered run), or null
+ * when it has none. A wake run of any conversation of the tree carries it as its `budget_run_id`,
+ * so a chain of wakes never opens a new window.
+ */
+export declare function budgetWindowOf(db: KernelSchemaDb, rootConversationId: string): Promise<string | null>;
 /**
- * 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
+ * Whether the sub-agents of a tree have used their token budget (§8.3): the budget run's
+ * `subagent_tokens_used`, read fresh, at or over `maxTokensPerRun` (never when it is 0: no limit). 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, budgetRunId: string): Promise<boolean>;

package/dist/runtime/subagents/limits.js

@@ -7,28 +7,64 @@ 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,
+        maxDepth: over?.maxDepth ?? base.maxDepth,
+        maxConcurrentPerConversation: over?.maxConcurrentPerConversation ?? base.maxConcurrentPerConversation,
         maxDispatchesPerRun: over?.maxDispatchesPerRun ?? base.maxDispatchesPerRun,
         maxTokensPerRun: over?.maxTokensPerRun ?? base.maxTokensPerRun,
     };
 }
 /**
- * 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
+ * The budget run of `runId` (agent map spec §6): its `budget_run_id`, or the run itself when it has
+ * none (a person-triggered run opens its own window) or does not exist. The dispatch count and the
+ * token counter of a whole tree live on this run.
+ */
+export async function budgetRunOf(db, runId) {
+    const row = await db
+        .selectFrom("runs")
+        .select("budget_run_id")
+        .where("id", "=", runId)
+        .executeTakeFirst();
+    return row?.budget_run_id ?? runId;
+}
+/**
+ * The current budget window of the tree rooted at `rootConversationId` (agent map spec §6): its
+ * newest run that opened its own window (`budget_run_id` null: a person-triggered run), or null
+ * when it has none. A wake run of any conversation of the tree carries it as its `budget_run_id`,
+ * so a chain of wakes never opens a new window.
+ */
+export async function budgetWindowOf(db, rootConversationId) {
+    const row = await db
+        .selectFrom("runs")
+        .select("id")
+        .where("conversation_id", "=", rootConversationId)
+        .where("budget_run_id", "is", null)
+        .orderBy("created_at", "desc")
+        .limit(1)
+        .executeTakeFirst();
+    return row?.id ?? null;
+}
+/**
+ * Whether the sub-agents of a tree have used their token budget (§8.3): the budget run's
+ * `subagent_tokens_used`, read fresh, at or over `maxTokensPerRun` (never when it is 0: no limit). A sub-agent's step checks it
  * before every model request and ends its run with `budget` when it is.
  */
-export async function subagentBudgetUsedUp(db, config, orgId, parentRunId) {
+export async function subagentBudgetUsedUp(db, config, orgId, budgetRunId) {
+    const { maxTokensPerRun } = await subagentLimits(db, config, orgId);
+    // 0: no limit
+    if (maxTokensPerRun === 0)
+        return false;
     const row = await db
         .selectFrom("runs")
         .select("subagent_tokens_used")
-        .where("id", "=", parentRunId)
+        .where("id", "=", budgetRunId)
         .executeTakeFirst();
     if (!row)
         return false;
-    const { maxTokensPerRun } = await subagentLimits(db, config, orgId);
     return Number(row.subagent_tokens_used) >= maxTokensPerRun;
 }

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/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/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.";