@capybara-hq/kernel 0.1.0-rc.23 → 0.1.0-rc.25

package/dist/channels/jobs.js

@@ -11,14 +11,14 @@ import { createHash, randomUUID } from "node:crypto";
 import { getQueueToken } from "@nestjs/bullmq";
 import { Inject, Injectable } from "@nestjs/common";
 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 { OutboxService } from "../infra/outbox/outbox.service.js";
+import { OUTBOX_JOBS } from "../infra/outbox/registry.js";
 import { KERNEL_LOGGER } from "../infra/tokens.js";
-/** 渠道队列（出站投递与入站任务，不含 `:`），只在 worker 角色上消费。 */
-export const CHANNEL_QUEUE_NAME = "cap-kernel-channels";
-/** 投递任务名。 */
-export const DELIVER_JOB = "deliver";
-/** 投递任务 id（不含 `:`）：同一会话、同一日志位置只排一个任务。 */
-export const deliverJobId = (conversationId, seq) => `deliver-${conversationId}-${seq}`;
+import { CHANNEL_QUEUE_NAME, DELIVER_JOB, deliverJobId, oweDelivery, } from "./deliver-job.js";
+export { CHANNEL_QUEUE_NAME, DELIVER_JOB, deliverJobId, oweDelivery, } from "./deliver-job.js";
 /**
  * 结束后复核排的任务 id：每次唯一（带随机后缀，不含 `:`）。不能复用 `deliver-<会话>-<seq>`——同 id 的任务
  * 可能正因锁被占而即将直接结束，BullMQ 会把新任务去重进它，于是没人投递。
@@ -32,7 +32,7 @@ export function idempotencyKey(raw) {
     return createHash("sha256").update(raw).digest("base64url").slice(0, 32);
 }
 /** 可重试失败（限流、5xx、网络、超时）的总尝试次数。 */
-export const DELIVER_ATTEMPTS = 8;
+export const DELIVER_ATTEMPTS = OUTBOX_JOBS.deliver.opts.attempts;
 /** 入站任务名。 */
 export const INBOUND_JOB = "inbound";
 /**
@@ -40,7 +40,7 @@ export const INBOUND_JOB = "inbound";
  * 用户发来的消息不能排在它们后面。
  */
 export const INBOUND_PRIORITY = 1;
-export const DELIVER_PRIORITY = 10;
+export const DELIVER_PRIORITY = OUTBOX_JOBS.deliver.opts.priority;
 /** 入站任务的总尝试次数（处理失败由 BullMQ 指数退避重试：1s、2s、4s、8s）。 */
 export const INBOUND_ATTEMPTS = 5;
 const INBOUND_BACKOFF_MS = 1000;
@@ -53,30 +53,31 @@ export const inboundJobId = (connectionId, messageId) => `inbound-${connectionId
  * The producer side of the channel queue `cap-kernel-channels` (any role): delivery jobs for a
  * conversation with an IM target, inbound jobs (Ruling A21), and the catch-up of a connection that
  * can deliver again. Its consumer is {@link ChannelOutbound} through the `@Processor` of the worker
- * role. Delivery jobs follow the kernel's domain events (spec §3b): every published log advance
- * (`conversation.event-appended`), a run starting here (`run.started`), a stopped wait
- * (`run.wait-stopped`), a decided approval and an answered question (their cards change). Each is
- * lost-tolerant: the next append enqueues again, and a finished delivery job re-checks the log.
+ * role. A delivery is owed (transactional outbox spec §8.1): every event append of a conversation
+ * with a channel target adds its deliver job to the outbox in the append's transaction (a reply, an
+ * approval decision, a question answer, a wait stop all append), and {@link bind} owes the first
+ * one with the target. The direct {@link enqueue} is left for hints and catch-ups: a run starting
+ * here (`run.started`, so its streaming drafts start at once), a finished delivery job's re-check,
+ * a card click's thread and a connection that can deliver again.
  */
 let ChannelJobs = class ChannelJobs {
     db;
     queue;
     log;
+    outbox;
+    txHost;
     /** Stopped (the stop's channel-outbound phase): enqueues do nothing, inbound enqueues throw. */
     closed = false;
     unsubscribe;
-    constructor(db, queue, events, log) {
+    constructor(db, queue, events, log, outbox, txHost) {
         this.db = db;
         this.queue = queue;
         this.log = log;
+        this.outbox = outbox;
+        this.txHost = txHost;
         queue.on("error", (err) => this.log.error("channel outbound queue error", { err }));
-        const soon = ({ conversationId }) => this.enqueueSoon(conversationId);
         this.unsubscribe = [
-            events.on("conversation.event-appended", soon),
-            events.on("run.started", soon),
-            events.on("run.wait-stopped", soon),
-            events.on("approval.decided", soon),
-            events.on("question.answered", soon),
+            events.on("run.started", ({ conversationId }) => this.enqueueSoon(conversationId)),
         ];
     }
     /** Unsubscribes after the stop phases: events emitted while they drain are still handled. */
@@ -84,11 +85,46 @@ let ChannelJobs = class ChannelJobs {
         for (const off of this.unsubscribe)
             off();
     }
+    /**
+     * Makes `target` (on `connectionId`) the conversation's delivery target and owes its delivery
+     * from the current log position, in one transaction. A new target starts delivering after
+     * `seq` (the message that bound it); a known one keeps its progress. The conversation row is
+     * locked first, as an append locks it: an append either committed before (its events are below
+     * the owed position) or reads the target (and owes its own job).
+     */
+    async bind(orgId, conversationId, connectionId, target, seq) {
+        const conv = await this.db
+            .selectFrom("conversations")
+            .select("last_seq")
+            .where("id", "=", conversationId)
+            .forUpdate()
+            .executeTakeFirst();
+        if (!conv)
+            return;
+        await this.db
+            .insertInto("channel_deliveries")
+            .values({
+            conversation_id: conversationId,
+            connection_id: connectionId,
+            target: JSON.stringify(target),
+            last_seq: seq,
+        })
+            .onConflict((oc) => oc.column("conversation_id").doUpdateSet({
+            connection_id: connectionId,
+            target: JSON.stringify(target),
+            updated_at: new Date(),
+        }))
+            .execute();
+        await oweDelivery(this.outbox, { conversationId, orgId, seq: Number(conv.last_seq) });
+    }
     /** 会话有 IM 投递目标时排一个出站任务，不等入队完成；失败只记日志。 */
     enqueueSoon(conversationId) {
         this.enqueue(conversationId).catch((err) => this.log.warn("cannot enqueue channel delivery", { conversationId, err }));
     }
-    /** 会话有 IM 投递目标时投递一个出站任务（同一日志位置重复调用只排一个）；已关闭时什么都不做。 */
+    /**
+     * A hint (not owed work, see the class): a delivery job for a conversation with an IM target (one
+     * per log position; `followUp` gets a fresh id); does nothing once closed.
+     */
     async enqueue(conversationId, opts = {}) {
         if (this.closed)
             return;
@@ -101,14 +137,10 @@ let ChannelJobs = class ChannelJobs {
         if (!row || this.closed)
             return;
         await this.queue.add(DELIVER_JOB, { conversationId }, {
+            ...OUTBOX_JOBS.deliver.opts,
             jobId: opts.followUp
                 ? followUpJobId(conversationId, Number(row.last_seq))
                 : deliverJobId(conversationId, Number(row.last_seq)),
-            attempts: DELIVER_ATTEMPTS,
-            backoff: { type: "deliver" },
-            priority: DELIVER_PRIORITY,
-            removeOnComplete: true,
-            removeOnFail: true,
         });
     }
     /**
@@ -147,11 +179,16 @@ let ChannelJobs = class ChannelJobs {
         this.closed = true;
     }
 };
+__decorate([
+    Transactional()
+], ChannelJobs.prototype, "bind", null);
 ChannelJobs = __decorate([
     Injectable(),
     __param(0, Inject(KernelDb)),
     __param(1, Inject(getQueueToken(CHANNEL_QUEUE_NAME))),
     __param(2, Inject(KernelEvents)),
-    __param(3, Inject(KERNEL_LOGGER))
+    __param(3, Inject(KERNEL_LOGGER)),
+    __param(4, Inject(OutboxService)),
+    __param(5, Inject(TransactionHost))
 ], ChannelJobs);
 export { ChannelJobs };

package/dist/channels/threads.d.ts

@@ -21,9 +21,10 @@ export declare class AnonymousGuests {
     readonly txHost: TransactionHost;
     constructor(db: KernelDb, guestLock: AnonymousGuestLock, txHost: TransactionHost);
     /**
-     * 该组织唯一的匿名访客账号 id；首次使用时创建（`accounts.status = active`、没有任何登录方式、组织角色 guest）。
-     * 每次都确保成员关系存在（被移出后再次使用会补回 guest）：运行的兜底扫描会中止「发起人已不是该组织成员」的运行。
-     * 跨副本并发首次创建由 {@link AnonymousGuestLock} 串行化，只建一个账号。
+     * The org's one anonymous guest account id, created on first use (`accounts.status = active`, no
+     * way to sign in, org role guest). Every call makes sure the membership exists (a removed guest
+     * is added back on its next use). Concurrent first creations across replicas are serialized by
+     * {@link AnonymousGuestLock}: one account.
      */
     ensure(orgId: string): Promise<string>;
 }

package/dist/channels/threads.js

@@ -55,9 +55,10 @@ let AnonymousGuests = class AnonymousGuests {
         this.txHost = txHost;
     }
     /**
-     * 该组织唯一的匿名访客账号 id；首次使用时创建（`accounts.status = active`、没有任何登录方式、组织角色 guest）。
-     * 每次都确保成员关系存在（被移出后再次使用会补回 guest）：运行的兜底扫描会中止「发起人已不是该组织成员」的运行。
-     * 跨副本并发首次创建由 {@link AnonymousGuestLock} 串行化，只建一个账号。
+     * The org's one anonymous guest account id, created on first use (`accounts.status = active`, no
+     * way to sign in, org role guest). Every call makes sure the membership exists (a removed guest
+     * is added back on its next use). Concurrent first creations across replicas are serialized by
+     * {@link AnonymousGuestLock}: one account.
      */
     async ensure(orgId) {
         await this.guestLock.lock(orgId);

package/dist/config/schema.d.ts

@@ -11,8 +11,6 @@ export interface FieldMeta {
  * 用法：`z.string().meta(meta({ secret: true, description: "..." }))`。
  */
 export declare function meta(opts: FieldMeta): FieldMeta;
-/** `runtime.maxRunSeconds` 的默认值。 */
-export declare const DEFAULT_MAX_RUN_SECONDS = 900;
 /** `sandbox.limits.maxCommandSeconds` 的默认值。 */
 export declare const DEFAULT_MAX_COMMAND_SECONDS = 7200;
 /** access token 寿命上限（秒）；会话吊销标记的 TTL 按它计算，与实例当前配置无关。 */
@@ -268,7 +266,6 @@ export declare const KernelConfigSchema: z.ZodObject<{
     hooks: z.ZodPrefault<z.ZodObject<{
         timeoutMs: z.ZodDefault<z.ZodNumber>;
         usageReportConcurrency: z.ZodDefault<z.ZodNumber>;
-        usageReportKeepHours: z.ZodDefault<z.ZodNumber>;
     }, z.core.$strip>>;
     log: z.ZodPrefault<z.ZodObject<{
         level: z.ZodDefault<z.ZodEnum<{

package/dist/config/schema.js

@@ -22,8 +22,6 @@ function isValidMasterKey(value) {
  * 插件名同清单规则（不能是 `local`），租户 id 非空、不含空白；与 identity/external.ts 的身份源键规则一致。
  */
 const TRUSTED_SOURCE_RE = /^(?!local:)[a-z0-9][a-z0-9._-]{0,213}:\S{1,256}$/;
-/** `runtime.maxRunSeconds` 的默认值。 */
-export const DEFAULT_MAX_RUN_SECONDS = 900;
 /** `sandbox.limits.maxCommandSeconds` 的默认值。 */
 export const DEFAULT_MAX_COMMAND_SECONDS = 7200;
 /** access token 寿命上限（秒）；会话吊销标记的 TTL 按它计算，与实例当前配置无关。 */
@@ -573,9 +571,11 @@ export const KernelConfigSchema = z.object({
         maxSteps: z
             .number()
             .int()
-            .positive()
-            .default(50)
-            .meta(meta({ description: "Maximum model steps per agent run before the final wrap-up" })),
+            .nonnegative()
+            .default(0)
+            .meta(meta({
+            description: "Maximum model steps per agent run before the final wrap-up; 0 (the default) means no limit: a run goes on until the model stops calling tools or someone stops it",
+        })),
         wakeOnBackgroundTask: z
             .boolean()
             .default(true)
@@ -585,10 +585,10 @@ export const KernelConfigSchema = z.object({
         maxRunSeconds: z
             .number()
             .int()
-            .positive()
-            .default(DEFAULT_MAX_RUN_SECONDS)
+            .nonnegative()
+            .default(0)
             .meta(meta({
-            description: "Maximum wall-clock duration of one agent run in seconds (time spent waiting for people is not counted). Sandbox commands are limited to the time left in the run, so agents that need long commands need maxRunSeconds >= sandbox.limits.maxCommandSeconds",
+            description: "Maximum wall-clock duration of one agent run in seconds (time spent waiting for people is not counted); 0 (the default) means no limit. With a limit, sandbox commands are limited to the time left in the run, so agents that need long commands need maxRunSeconds >= sandbox.limits.maxCommandSeconds; without one, commands are limited only by sandbox.limits.maxCommandSeconds and the tool timeouts",
         })),
         streamIdleMs: z
             .number()
@@ -669,9 +669,9 @@ export const KernelConfigSchema = z.object({
         })),
     })
         .default({
-        maxSteps: 50,
+        maxSteps: 0,
         wakeOnBackgroundTask: true,
-        maxRunSeconds: DEFAULT_MAX_RUN_SECONDS,
+        maxRunSeconds: 0,
         streamIdleMs: 60000,
         maxOutputTokens: 16000,
         compactionThreshold: 0.8,
@@ -1178,7 +1178,7 @@ export const KernelConfigSchema = z.object({
                 .positive()
                 .default(DEFAULT_MAX_COMMAND_SECONDS)
                 .meta(meta({
-                description: "Longest a single sandbox command may run, in seconds. A command also stops when its run is about to reach runtime.maxRunSeconds, so long commands need runtime.maxRunSeconds >= maxCommandSeconds (a startup warning is logged otherwise)",
+                description: "Longest a single sandbox command may run, in seconds. When runtime.maxRunSeconds is set (not 0), a command also stops when its run is about to reach it, so long commands need runtime.maxRunSeconds >= maxCommandSeconds (a startup warning is logged otherwise)",
             })),
             suspendAfterIdleMinutes: z
                 .number()
@@ -1443,15 +1443,6 @@ export const KernelConfigSchema = z.object({
             .meta(meta({
             description: "usage.report delivery jobs one worker replica processes at the same time",
         })),
-        usageReportKeepHours: z
-            .number()
-            .int()
-            .min(1)
-            .max(720)
-            .default(24)
-            .meta(meta({
-            description: "Hours a finished usage.report job is kept in Redis so re-enqueueing the same usage event (resumed step, sweeper) is deduplicated; at least 1, well above the sweeper's 10-minute overlap",
-        })),
     })
         .prefault({}),
     log: z

package/dist/conversations/agent-tree.d.ts

@@ -44,3 +44,19 @@ export interface AgentTreeNode {
  * check of the root.
  */
 export declare function readAgentTree(db: KernelSchemaDb, orgId: string, rootId: string): Promise<AgentTreeNode | null>;
+/** One sub-agent a conversation dispatched, as `TaskList` lists it. */
+export interface ChildAgent {
+    /** The child conversation's id: the agentId the parent saw. */
+    id: string;
+    /** The dispatched description (the child's title when no dispatch event has one). */
+    description: string;
+    /** The latest run's status; `queued` before the first run is recorded. */
+    status: "queued" | "running" | "waiting" | "completed" | "failed" | "aborted";
+    /** When the latest run ended; null while it is active. */
+    finishedAt: Date | null;
+}
+/**
+ * The sub-agents `parentId` of org `orgId` dispatched itself (not their own sub-agents), oldest
+ * first: live sub-agent conversations with a dispatch row, as {@link readAgentTree} counts them.
+ */
+export declare function readChildAgents(db: KernelSchemaDb, orgId: string, parentId: string): Promise<ChildAgent[]>;

package/dist/conversations/agent-tree.js

@@ -90,3 +90,39 @@ function toNode(r, isRoot) {
     };
 }
 const modelOf = (m) => m ? { provider: m.provider, model: m.model } : null;
+/**
+ * The sub-agents `parentId` of org `orgId` dispatched itself (not their own sub-agents), oldest
+ * first: live sub-agent conversations with a dispatch row, as {@link readAgentTree} counts them.
+ */
+export async function readChildAgents(db, orgId, parentId) {
+    const { rows } = await sql `
+    SELECT c.id, c.title,
+      (SELECT e.payload->>'description' FROM capybara.conversation_events e
+        WHERE e.conversation_id = c.parent_conversation_id AND e.type = 'subagent_dispatched'
+          AND e.payload->>'subagentId' = c.id
+        ORDER BY e.seq DESC LIMIT 1) AS description,
+      latest.status AS last_status, latest.finished_at AS last_finished_at
+    FROM capybara.conversations c
+    LEFT JOIN LATERAL (
+      SELECT r.status, r.finished_at FROM capybara.runs r
+      WHERE r.conversation_id = c.id
+      ORDER BY r.created_at DESC, r.id DESC
+      LIMIT 1
+    ) latest ON true
+    WHERE c.parent_conversation_id = ${parentId} AND c.org_id = ${orgId}
+      AND c.kind = 'subagent' AND c.deleted_at IS NULL
+      AND EXISTS (
+        SELECT 1 FROM capybara.subagent_dispatches sd WHERE sd.child_conversation_id = c.id
+      )
+    ORDER BY c.created_at, c.id
+  `.execute(db);
+    return rows.map((r) => {
+        const status = r.last_status ?? "queued";
+        return {
+            id: r.id,
+            description: r.description ?? r.title ?? "",
+            status,
+            finishedAt: ACTIVE.has(status) ? null : (r.last_finished_at ?? null),
+        };
+    });
+}

package/dist/conversations/conversations.controller.js

@@ -190,7 +190,9 @@ let ConversationsController = class ConversationsController {
         const pick = body.deviceId === undefined ? {} : { deviceId: body.deviceId };
         if (body.message === undefined) {
             return {
-                conversation: await this.conversations.create(org.orgId, p.account.id, body.agentId, pick),
+                conversation: await this.conversations.create(org.orgId, p.account.id, body.agentId, pick, {
+                    source: "web",
+                }),
             };
         }
         const m = body.message;
@@ -204,7 +206,7 @@ let ConversationsController = class ConversationsController {
             ...(m.skill !== undefined && { skill: m.skill }),
             ...(m.timeZone !== undefined && { timeZone: m.timeZone }),
             ...(m.locale !== undefined && { locale: m.locale }),
-        }, pick);
+        }, pick, { source: "web" });
         reply.status(out.created ? 201 : 200);
         return { conversation: out.conversation, event: out.event, events: out.events };
     }

package/dist/conversations/conversations.service.d.ts

@@ -1,3 +1,4 @@
+import type { ConversationSource } from "@capybara-hq/plugin-sdk";
 import { AgentLookup } from "../agents/agent-lookup.js";
 import type { ModelRef } from "../agents/definition.js";
 import type { AgentAvatar } from "../agents/profile.js";
@@ -7,7 +8,6 @@ import { ConversationDevices, type NewConversationDevice } from "../devices/conv
 import { KernelDb } from "../infra/database/kernel-db.js";
 import { TransactionHost } from "../infra/database/transaction-host.js";
 import { KernelEvents } from "../infra/events/kernel-events.js";
-import type { KernelLogger } from "../log.js";
 import { ProviderRegistry } from "../runtime/providers.js";
 import type { ScheduleMarker } from "../schedules/types.js";
 import { type RenderedInvocation, SkillInvoker } from "../skills/invoke.js";
@@ -118,15 +118,37 @@ export interface ReplySkips {
 export declare const NO_REPLY_SKIPS: ReplySkips;
 /** 会话服务用到的运行控制：投递运行（RunQueue）与跨副本中止（RunAbort）。 */
 export interface RunControl {
-    /** 有未消费的消息且没有进行中的运行时投递一轮运行；返回 runId 或 null。 */
-    ensureRun(conversationId: string): Promise<string | null>;
+    /**
+     * The direct `ensureRun` after a commit that owes the ensure-run backstop: a failure is logged,
+     * never thrown (transactional outbox spec §6).
+     */
+    ensureRunAfterCommit(conversationId: string): Promise<void>;
+    /**
+     * Owes the ensure-run backstop in the caller's transaction (transactional outbox spec §6): `seq`
+     * is the event it wrote (or the conversation's newest), `orgId` the conversation's.
+     */
+    oweEnsureRun(conversationId: string, seq: number | string, orgId: string): Promise<boolean>;
     /** After a root's queue was unpaused: the wakes it held for its tree (agent map spec §5.3). */
     wakeHeldTree(rootId: string): Promise<void>;
+    /**
+     * In the transaction that may release a root's hold: owes the ensure-run backstop of each
+     * sub-agent {@link wakeHeldTree} wakes after the commit (transactional outbox spec §6).
+     */
+    oweHeldTreeIn(rootId: string): Promise<void>;
+    /**
+     * In a decision's transaction, after its decided rows: resumes the waiting run when it waits on
+     * nothing else (lock order: conversations, decided rows, runs).
+     */
+    resumeIn(runId: string, waitId: string): Promise<unknown>;
+    /** In a root's delete transaction: owes the stop of its sub-agent tree (`stop-tree`). */
+    oweStopDeletedTree(conversationId: string, byAccountId: string | null, orgId: string): Promise<boolean>;
     /**
      * 运行是孤儿（会话锁空闲、任务已不存在，没有 worker 会收到中止广播）时直接把它写成 aborted，返回 true；
      * 否则返回 false。
      */
     abortIfOrphaned(conversationId: string, runId: string, byAccountId: string): Promise<boolean>;
+    /** Ends a run still `queued` in PG before a worker started it (`RunQueue.abortQueued`): true. */
+    abortQueued(conversationId: string, runId: string, byAccountId: string): Promise<boolean>;
     /**
      * 运行在等人处理（waiting）时直接中止：取消等待、写 `run_aborted`、删除 checkpoint，返回 true；
      * 运行已不是 waiting（例如刚被续跑）→ false。
@@ -209,6 +231,14 @@ export interface InternalMessageOptions {
     schedule?: ScheduleMarker;
     timeZoneOverride?: string;
 }
+/** Options of a conversation created by a kernel caller (never an HTTP body). */
+export interface NewConversationOptions {
+    /**
+     * Where it comes from (memory plugin spec §6.2), fixed at creation. Required: a channel or group
+     * conversation that fell back to `web` would be offered what only the web and DMs may see.
+     */
+    source: ConversationSource;
+}
 /**
  * 会话：只有所有者可见；每次访问都实时复核 agent 对所有者仍可用（spec 3.6 R5），
  * 不可用时会话也按不存在处理（`conversation.not_found`）。
@@ -222,7 +252,6 @@ export declare class ConversationsService {
     private readonly runs;
     /** Resolves a switched-to model and its declared parameters (UI refresh B). */
     private readonly providers;
-    private readonly log;
     /** Reads `@` resources with the sender's credentials. */
     private readonly content;
     /** Binds uploaded files to the conversation in the message's transaction. */
@@ -243,7 +272,7 @@ export declare class ConversationsService {
     /** Starts and stops the conversation's runs. */
     runs: RunControl, 
     /** Resolves a switched-to model and its declared parameters (UI refresh B). */
-    providers: Pick<ProviderRegistry, "resolve">, log: Pick<KernelLogger, "warn">, 
+    providers: Pick<ProviderRegistry, "resolve">, 
     /** Reads `@` resources with the sender's credentials. */
     content: Pick<ConnectorContent, "resolveAttachments">, 
     /** Binds uploaded files to the conversation in the message's transaction. */
@@ -258,18 +287,14 @@ export declare class ConversationsService {
     questions: Pick<QuestionsService, "skipPendingIn">, 
     /** ... and its pending network asks (network ask-to-allow spec §6.7). */
     approvals: Pick<ApprovalsService, "skipNetworkIn">, events: Pick<KernelEvents, "emit">, txHost: TransactionHost);
-    /**
-     * 不阻塞地调用一次 `ensureRun`（打开 SSE、读事件时）：它幂等，并顺带清理孤儿运行，
-     * 会话不会因为某次运行结束后的投递失败而永远停在「运行中」。失败只记日志。
-     */
-    kickRun(conversationId: string): void;
     /**
      * Creates an empty conversation bound to its device (`pick`, see
      * {@link ConversationDevices.forNew}); an agent the account cannot use →
      * `agent.not_found`, a device it may not use → `device.not_found` /
-     * `device.unavailable`, and nothing is created.
+     * `device.unavailable`, and nothing is created. `opts.source` records where the conversation
+     * comes from.
      */
-    create(orgId: string, accountId: string, agentId: string, pick?: NewConversationDevice): Promise<ConversationView>;
+    create(orgId: string, accountId: string, agentId: string, pick: NewConversationDevice | undefined, opts: NewConversationOptions): Promise<ConversationView>;
     /**
      * Creates a conversation together with its first message (UI refresh B, create on first send):
      * the conversation row and the `user_message` are written in one transaction, keyed by the
@@ -278,12 +303,12 @@ export declare class ConversationsService {
      * `agent.not_found` and nothing is written. Queues a run afterwards, like `postUserMessage`.
      * `events` are every event the create wrote, in seq order from seq 1 (a `model_switched` before
      * the message when the send switched), so a client can seed the new conversation's log whole.
-     * `internal` (kernel callers only): a scheduled task's marker, which also sets
-     * `conversations.scheduled_task_id`, and its zone override.
+     * `internal`: the conversation's source and, for kernel callers only, a scheduled task's marker,
+     * which also sets `conversations.scheduled_task_id`, and its zone override.
      */
     createWithMessage(orgId: string, accountId: string, agentId: string, input: UserMessageInput & {
         clientMessageId: string;
-    }, pick?: NewConversationDevice, internal?: InternalMessageOptions): Promise<{
+    }, pick: NewConversationDevice | undefined, internal: InternalMessageOptions & NewConversationOptions): Promise<{
         conversation: ConversationView;
         event: ConversationEvent;
         events: ConversationEvent[];
@@ -297,6 +322,11 @@ export declare class ConversationsService {
      * the other conversation is never returned).
      */
     private findCreated;
+    /**
+     * The direct `ensureRun` after a message's commit ({@link RunControl.ensureRunAfterCommit}): a
+     * failure never fails the request, since the message's transaction owes the ensure-run backstop.
+     */
+    private startRun;
     private rowView;
     /**
      * Renames a conversation (owner only, as {@link get}): `title_source = 'manual'`, so the title
@@ -399,12 +429,15 @@ export declare class ConversationsService {
      * only after an access check.
      */
     sandboxConversationOf(orgId: string, conversationId: string): Promise<string>;
-    /** 读事件（先做 `get` 的可见性判定）；顺带不阻塞地 {@link kickRun}。 */
+    /**
+     * 读事件（先做 `get` 的可见性判定）. A read never changes run state (transactional outbox spec
+     * §6): a run nobody runs is the `run-orphan-check`'s to repair.
+     */
     listEvents(orgId: string, conversationId: string, viewerAccountId: string, afterSeq: number, limit: number): Promise<ConversationEvent[]>;
     /**
      * The turn-aligned page of events before `beforeSeq` (`null`: the log's last page), with how
      * many runs started before it ({@link EventLog.readTurnPageBefore}; history paging spec §2).
-     * Visibility as {@link get}; kicks a stalled run as {@link listEvents} does.
+     * Visibility as {@link get}; a read only, as {@link listEvents}.
      */
     listEventsBefore(orgId: string, conversationId: string, viewerAccountId: string, beforeSeq: number | null, limit: number): Promise<{
         events: ConversationEvent[];
@@ -413,7 +446,8 @@ export declare class ConversationsService {
     /**
      * 追加一条用户消息；带 `clientMessageId` 时重复提交返回同一事件。写入后调用 `ensureRun`：
      * 没有进行中的运行时投递一轮；运行中则由当前运行在步骤间隙吸收，或在它结束时再次 `ensureRun`。
-     * 投递失败时抛错（消息已写入；客户端带同一 `clientMessageId` 重试会再次触发投递）。
+     * A failed `ensureRun` is logged, not thrown: the message's transaction owes the ensure-run
+     * backstop, which starts the run once the queue is reachable (transactional outbox spec §6).
      *
      * `attachments`（`@` 资源引用）：内核以发送者的凭据读取资源（打码、限长），作为用户文本之后的额外文本块写入同一条
      * user_message，并在 `payload.attachments` 记录元数据（第 i 个附件对应 `content[i + 1]`）。读取失败整条不写。
@@ -452,6 +486,13 @@ export declare class ConversationsService {
      * conversations (network ask-to-allow spec §6.7). The queue's "send now" uses it as the direct
      * send does; announce after the commit with {@link announceSkipped}. `toSeq` is the highest seq
      * written in this conversation (null: none).
+     *
+     * Lock order: this (root) conversation (the caller's), its pending questions, the sub-agents'
+     * conversations with a pending network ask (id order), the asks themselves (the root's and the
+     * sub-agents'), and only then the run rows, as each skipped wait's run resumes in this
+     * transaction. Every run row comes after every conversation and decided row (ruling R19); a
+     * sub-agent's conversation comes after the root's questions, which only this path locks with a
+     * sub-agent conversation after them.
      */
     skipWaitsIn(conversationId: string, accountId: string, messageSeq: number): Promise<{
         skipped: ReplySkips;
@@ -460,7 +501,8 @@ export declare class ConversationsService {
     /**
      * After the commit: announces each skipped question (`question.answered`, outcome `skipped`) and
      * network ask (`approval.decided`, status `skipped`; a sub-agent's conversation is notified
-     * first), so its run resumes (waits) and its IM card updates (channel jobs).
+     * first) as domain events with no kernel subscriber: the IM card updates are owed by the skips'
+     * appends (transactional outbox spec §8.1); the run resumed in the message's transaction.
      */
     announceSkipped(skipped: ReplySkips): Promise<void>;
     /**