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

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 };

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

@@ -1,15 +1,15 @@
 import type { Logger } from "@capybara-hq/plugin-sdk";
-import { type AgentDefinition } from "../../agents/definition.js";
+import type { AgentDefinition } from "../../agents/definition.js";
 import type { EventLog } from "../../conversations/event-log.js";
 import type { ConversationEvent, EventPayload } from "../../conversations/events.js";
 import type { ConversationKind, KernelSchemaDb } from "../../db/kernel-schema.js";
 import type { KernelConfigService } from "../../infra/config/kernel-config.service.js";
 import type { ModelPurposesService } from "../../models/purposes.js";
-import { type AgentToolInputT } from "../../tools/builtins/agent.js";
+import { AGENT_REFUSALS, type AgentToolInputT } from "../../tools/builtins/agent.js";
 import type { ToolStepContext } from "../../tools/pipeline.js";
 import type { ProviderRegistry } from "../providers.js";
 import { type RunJobData } from "../run-jobs.js";
-import { type CheckedOrgAgent } from "./definition.js";
+import { type CheckedOrgAgent, type FollowUpNarrowing } from "./definition.js";
 import { type RosterEntry } from "./roster.js";
 export interface DispatchDeps {
     /** The context's handle: inside {@link commitDispatchIn} it is the dispatch's transaction. */
@@ -33,7 +33,31 @@ export interface DispatchArgs {
     callId: string;
     input: AgentToolInputT;
     forSkill?: SkillForkDispatch;
+    /**
+     * The `Agent` call's own record (not for a fork invocation): the logged key its `tool_result`
+     * keeps (the rc `agent` for a call logged before the rename), the `tool.called` audit's
+     * authorization fields, and when the pipeline started it (the audit's duration).
+     */
+    call?: {
+        toolKey: string;
+        authorization: Record<string, unknown>;
+        startedAt: number;
+    };
+    /**
+     * A `SendMessage` that starts an idle sub-agent again (agent map spec §5.1, §6): its call's
+     * immediate result, written with the dispatch instead of `agentStartedText`, and the texts of
+     * the limit refusals. `input.description` is the sub-agent's task label, `input.prompt` the
+     * message.
+     */
+    sent?: {
+        content: string;
+        refusals: LimitRefusals;
+    };
 }
+/** The texts of the limit refusals of a dispatch (§4.5, agent map spec §6), and of a stopped run. */
+export type LimitRefusals = Pick<typeof AGENT_REFUSALS, "depthLimit" | "budget" | "tooManyDispatches" | "tooManyConcurrent"> & {
+    notAvailableHere: string;
+};
 /**
  * Writes the child's events in the dispatch's transaction (`db` is its handle); `checked` is the
  * org agent version the in-lock gates passed. Null refuses.
@@ -42,6 +66,9 @@ export type ChildWriter = (db: KernelSchemaDb, checked?: CheckedOrgAgent) => Pro
 export type DispatchOutcome = {
     kind: "dispatched";
     childRunId: string;
+    childConversationId: string;
+    /** The call's immediate result (`agentStartedText`). */
+    content: string;
 } | {
     kind: "refused";
     content: string;
@@ -62,6 +89,11 @@ export interface SkillForkDispatch {
     /** The task for the sub-agent's effective definition (replaces `input.prompt`). */
     task: (child: AgentDefinition) => string;
 }
+/**
+ * The depth of the run behind `ctx` below the root (agent map spec §6): 0 for a root
+ * conversation's run, its parent's depth plus one for a sub-agent's.
+ */
+export declare const runDepth: (ctx: Pick<ToolStepContext, "parent">) => number;
 /** Idempotency key of the parent's `subagent_dispatched` event. */
 export declare const dispatchedIdemKey: (runId: string, callId: string) => string;
 /** What one dispatch writes, decided before its transaction. */
@@ -83,28 +115,74 @@ export interface DispatchPlan {
     tierFallback: boolean;
 }
 /**
- * Dispatches the sub-agent of one `Agent` call (spec §7.1), after the pipeline's validation,
- * policy, approval and `tool.preExecute` stages. A new sub-agent: resolves its type and effective
- * definition, then in one transaction (holding the parent run's row lock, so the dispatches of one
- * run serialize) inserts the child conversation, appends `subagent_started` and the task message,
- * inserts the child run (`queued`) and the `subagent_dispatches` row, appends `subagent_dispatched`
- * to the parent and audits `subagent.dispatched`. A `resume` appends the follow-up message and
- * starts the child's next run the same way. After commit the child run is enqueued; a failed
- * enqueue only logs (the dispatch is durable, the wait sweep re-enqueues it).
+ * Dispatches the sub-agent of one `Agent` call (spec §7.1, agent map spec §4.1), after the
+ * pipeline's validation, policy, approval and `tool.preExecute` stages: resolves its type and
+ * effective definition, then in one transaction (holding the parent run's row lock, so the
+ * dispatches of one run serialize) inserts the child conversation, appends `subagent_started` and
+ * the task message, inserts the child run (`queued`) and the `subagent_dispatches` row, appends
+ * `subagent_dispatched` and the call's `tool_result` ({@link agentStartedText}: the sub-agent runs
+ * in the background) to the parent and audits `subagent.dispatched` and `tool.called`. After
+ * commit the child run is enqueued; a failed enqueue only logs (the dispatch is durable, the wait
+ * sweep re-enqueues it). A fork invocation (`forSkill`) writes no `tool_result`: its run waits on
+ * the child (`advanceSkillForks`).
  *
- * Refusals (§4.5) start nothing: a call from a sub-agent, an unknown type, an org agent that fails
- * one of its gates ({@link orgAgentGates}, at every dispatch and follow-up; audited
- * `subagent.refused`), `resume` with `subagent_type` / `model`, a `resume` id that is not a
- * sub-agent of this conversation (whatever it is otherwise: no detail about other conversations),
- * or one whose run is still active.
+ * Refusals (§4.5) start nothing: a call from a run at `subagents.maxDepth` (agent map spec §4.1:
+ * its definition has no `Agent`, so only a forged call or a lowered limit gets here), an unknown
+ * type, or an org agent that fails one of its gates ({@link orgAgentGates}, checked at every
+ * level; audited `subagent.refused`).
+ */
+export declare function dispatchSubagent(d: DispatchDeps, a: DispatchArgs): Promise<DispatchOutcome>;
+/**
+ * The gates of an org agent sub-agent (§5.5) for this call: the allowlist of the parent agent's
+ * **current** version (R5), the agent's `dispatchable`, its visibility to the person who started
+ * the parent run, and not deleted. A refusal is audited `subagent.refused` and answers with the
+ * §4.5 text, which names only the roster type. Checked before the dispatch transaction (a new
+ * sub-agent freezes the definition read here) and again inside it under the parent run's row lock
+ * ({@link commit}), so a gate revoked in between refuses (batch 9 review M1).
  */
-export declare function dispatchSubagent(d: DispatchDeps, a: {
+export declare function orgAgentGates(db: KernelSchemaDb, a: {
     ctx: ToolStepContext;
     callId: string;
-    input: AgentToolInputT;
-    /** Phase D: a person's fork invocation (see {@link SkillForkDispatch}). */
-    forSkill?: SkillForkDispatch;
-}): Promise<DispatchOutcome>;
+}, agentId: string, agentType: string, resumed: boolean): Promise<{
+    checked: CheckedOrgAgent;
+} | {
+    refused: DispatchOutcome;
+}>;
+/**
+ * A sub-agent's task message, or (`message`) a `SendMessage` from its parent (agent map spec
+ * §5.1: `dispatch.kind: "message"`, idempotent by the sending call, with the follow-up narrowing
+ * the run it triggers uses).
+ */
+export declare const taskMessage: (ctx: ToolStepContext, callId: string, prompt: string, narrowed?: FollowUpNarrowing, skill?: SkillForkDispatch["skill"], message?: boolean) => {
+    type: "user_message";
+    idemKey?: string;
+    payload: {
+        content: {
+            type: "text";
+            text: string;
+        }[];
+        skill?: {
+            id: string;
+            version: number;
+            source: string;
+            name: string;
+            plugin?: string | undefined;
+            arguments: string;
+            mode: "fork" | "inline";
+            agentType?: string | undefined;
+        };
+        authorAccountId: string;
+        dispatch: {
+            parentConversationId: string;
+            parentRunId: string;
+            callId: string;
+            kind?: "message";
+            narrowed?: FollowUpNarrowing;
+        };
+    };
+};
+/** Idempotency key of a `SendMessage`'s `user_message` in the sub-agent's log. */
+export declare const sentMessageIdemKey: (runId: string, callId: string) => string;
 /**
  * The dispatch transaction shared by new sub-agents and follow-ups: locks the parent conversation
  * row, then the parent run row (the order every terminal path uses),
@@ -115,20 +193,27 @@ export declare function dispatchSubagent(d: DispatchDeps, a: {
  *
  * Under the parent run's row lock it first re-checks what the pipeline checked without it: a call
  * already dispatched (a second holder of the same step, e.g. after a stalled-job takeover) gets
- * the existing child run back and writes nothing, and a parent run that is no longer `running`
- * (stopped, orphaned) dispatches nothing. Then the run's limits (§8.2, {@link subagentLimits}),
- * read fresh: its children's token counter at or over the cap, its dispatches (follow-ups
- * included) at the cap, or as many active children as may run at once each refuse with the §4.5
- * text. The lock serializes the dispatches of one run, so the counts cannot race.
+ * the existing child run back and writes nothing but a missing `Agent` result, and a parent run that is no longer `running`
+ * (stopped, orphaned) dispatches nothing. Then the limits (§8.2, agent map spec §6,
+ * {@link subagentLimits}), read fresh: the depth, the tree's token counter at or over the cap,
+ * its dispatches (follow-ups included) at the cap, or as many active children of the parent
+ * conversation as may run at once each refuse with the §4.5 text. The budget run's row lock
+ * serializes the dispatches of one tree, so the counts cannot race.
  */
 /** What the dispatch transaction did. */
 export type DispatchCommit = {
     kind: "existing";
     childRunId: string;
+    childConversationId: string;
     requeue: {
         conversationId: string;
         seq: number;
     } | null;
+    /** The call's logged result (null for a fork dispatch) and its seq, to notify. */
+    result: {
+        content: string;
+        seq: number;
+    } | null;
 } | {
     kind: "stopped";
 } | {
@@ -142,9 +227,13 @@ export type DispatchCommit = {
     childRunId: string;
     childSeq: number;
     parentSeq: number;
+    content: string;
 };
 /**
  * {@link commit}'s transaction (run by `SubagentsService.commitDispatch`, `d.db` its handle).
  * Null when `child` refused.
  */
 export declare function commitDispatchIn(d: Pick<DispatchDeps, "db" | "eventLog" | "config">, a: DispatchArgs, plan: DispatchPlan, child: ChildWriter): Promise<DispatchCommit | null>;
+export declare function commit(d: Pick<DispatchDeps, "commitDispatch" | "enqueue" | "log" | "eventLog">, a: DispatchArgs, plan: DispatchPlan, 
+/** Writes the child's events; `checked` is the org agent version the in-lock gates passed. */
+child: ChildWriter): Promise<DispatchOutcome | null>;