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

package/dist/conversations/conversations.service.js

@@ -19,7 +19,6 @@ 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 { ProviderRegistry } from "../runtime/providers.js";
 import { RunControl as RunControlService } from "../runtime/run-control.js";
 import { rootConversationOf } from "../runtime/subagents/child.js";
@@ -130,7 +129,6 @@ let ConversationsService = class ConversationsService {
     access;
     runs;
     providers;
-    log;
     content;
     attachments;
     invoker;
@@ -144,7 +142,7 @@ let ConversationsService = class ConversationsService {
     /** Starts and stops the conversation's runs. */
     runs, 
     /** Resolves a switched-to model and its declared parameters (UI refresh B). */
-    providers, log, 
+    providers, 
     /** Reads `@` resources with the sender's credentials. */
     content, 
     /** Binds uploaded files to the conversation in the message's transaction. */
@@ -165,7 +163,6 @@ let ConversationsService = class ConversationsService {
         this.access = access;
         this.runs = runs;
         this.providers = providers;
-        this.log = log;
         this.content = content;
         this.attachments = attachments;
         this.invoker = invoker;
@@ -176,22 +173,14 @@ let ConversationsService = class ConversationsService {
         this.events = events;
         this.txHost = txHost;
     }
-    /**
-     * 不阻塞地调用一次 `ensureRun`（打开 SSE、读事件时）：它幂等，并顺带清理孤儿运行，
-     * 会话不会因为某次运行结束后的投递失败而永远停在「运行中」。失败只记日志。
-     */
-    kickRun(conversationId) {
-        this.runs
-            .ensureRun(conversationId)
-            .catch((err) => this.log.warn("ensureRun on conversation open failed", { conversationId, err }));
-    }
     /**
      * 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.
      */
-    async create(orgId, accountId, agentId, pick = {}) {
+    async create(orgId, accountId, agentId, pick = {}, opts) {
         await this.agents.get(orgId, agentId, accountId);
         const deviceId = await this.devices.forNew(orgId, accountId, pick);
         const row = await this.db
@@ -202,6 +191,7 @@ let ConversationsService = class ConversationsService {
             agent_id: agentId,
             account_id: accountId,
             device_id: deviceId,
+            source: opts.source,
         })
             .returning(COLUMNS)
             .executeTakeFirstOrThrow();
@@ -215,10 +205,10 @@ let ConversationsService = 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.
      */
-    async createWithMessage(orgId, accountId, agentId, input, pick = {}, internal = {}) {
+    async createWithMessage(orgId, accountId, agentId, input, pick = {}, internal) {
         const agent = await this.agents.get(orgId, agentId, accountId);
         const prior = await this.findCreated(orgId, accountId, agentId, input.clientMessageId);
         if (prior)
@@ -237,7 +227,7 @@ let ConversationsService = class ConversationsService {
             return raced;
         }
         await this.eventLog.notify(id, written.seq);
-        await this.runs.ensureRun(id);
+        await this.startRun(id);
         return { conversation: await this.rowView(id), event: written, events: all, created: true };
     }
     /** The conversation row and its first message (undefined: a concurrent retry committed first). */
@@ -254,6 +244,7 @@ let ConversationsService = class ConversationsService {
             device_id: conv.deviceId,
             create_request_id: input.clientMessageId,
             scheduled_task_id: internal.schedule?.taskId ?? null,
+            source: internal.source,
         })
             .onConflict((oc) => oc
             .columns(["org_id", "account_id", "create_request_id"])
@@ -292,9 +283,16 @@ let ConversationsService = class ConversationsService {
             return null;
         // what the first send wrote: the log from its start up to the message
         const events = (await this.eventLog.readAfter(row.id, 0, event.seq)).filter((e) => e.seq <= event.seq);
-        await this.runs.ensureRun(row.id);
+        await this.startRun(row.id);
         return { conversation: toView(row), event, events, created: false };
     }
+    /**
+     * 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.
+     */
+    startRun(conversationId) {
+        return this.runs.ensureRunAfterCommit(conversationId);
+    }
     async rowView(id) {
         return toView(await this.db
             .selectFrom("conversations")
@@ -352,7 +350,7 @@ let ConversationsService = class ConversationsService {
             if (!(e instanceof ApiError && e.code === "run.not_active"))
                 throw e;
         }
-        await this.markDeleted(conversationId);
+        await this.markDeleted(orgId, conversationId, accountId);
         // after the mark, so no finish or delivery of the stops below can start a run on the deleted
         // root (`ensureRun` refuses it). The sandbox's tasks stop first, so the sub-agents' tasks end
         // as a deletion; the tree stop then only stops a task a sub-agent started in between
@@ -362,13 +360,15 @@ let ConversationsService = class ConversationsService {
         await this.runs.stopTree(conversationId, accountId, { includeSelf: false });
         await this.eventLog.publishChanged(conversationId, "deleted");
     }
-    // the publish happens after the commit, in the caller
-    async markDeleted(conversationId) {
+    // the publish happens after the commit, in the caller; the tree stop after it is owed here
+    // (transactional outbox spec §6), so a process that dies before it still stops the tree
+    async markDeleted(orgId, conversationId, accountId) {
         await this.db
             .updateTable("conversations")
             .set({ deleted_at: sql `now()` })
             .where("id", "=", conversationId)
             .execute();
+        await this.runs.oweStopDeletedTree(conversationId, accountId, orgId);
         // Queued messages must not start a run on a deleted conversation
         await this.db
             .deleteFrom("conversation_queue")
@@ -681,26 +681,28 @@ let ConversationsService = class ConversationsService {
             return conversationId;
         return rootConversationOf(this.db.db, row.parent_conversation_id);
     }
-    /** 读事件（先做 `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.
+     */
     async listEvents(orgId, conversationId, viewerAccountId, afterSeq, limit) {
         await this.get(orgId, conversationId, viewerAccountId);
-        this.kickRun(conversationId);
         return this.eventLog.readAfter(conversationId, afterSeq, limit);
     }
     /**
      * 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}.
      */
     async listEventsBefore(orgId, conversationId, viewerAccountId, beforeSeq, limit) {
         await this.get(orgId, conversationId, viewerAccountId);
-        this.kickRun(conversationId);
         return this.eventLog.readTurnPageBefore(conversationId, beforeSeq, limit, EVENTS_TURN_EXTEND);
     }
     /**
      * 追加一条用户消息；带 `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]`）。读取失败整条不写。
@@ -719,7 +721,7 @@ let ConversationsService = class ConversationsService {
             input.clientMessageId !== undefined) {
             const existing = await this.eventLog.findByIdem(conversationId, userMessageIdemKey(input.clientMessageId));
             if (existing) {
-                await this.runs.ensureRun(conversationId);
+                await this.startRun(conversationId);
                 return existing;
             }
         }
@@ -750,7 +752,7 @@ let ConversationsService = class ConversationsService {
                 .execute();
             await this.eventLog.publishChanged(conversationId, "archived");
         }
-        await this.runs.ensureRun(conversationId);
+        await this.startRun(conversationId);
         return event;
     }
     /**
@@ -812,10 +814,19 @@ let ConversationsService = 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.
      */
     async skipWaitsIn(conversationId, accountId, messageSeq) {
         const q = await this.questions.skipPendingIn(conversationId, accountId, messageSeq);
         const n = await this.approvals.skipNetworkIn(conversationId, accountId);
+        for (const w of [...q.records, ...n.records])
+            await this.runs.resumeIn(w.runId, w.id);
         const here = n.seqs.get(conversationId);
         const toSeq = q.toSeq === null && here === undefined ? null : Math.max(q.toSeq ?? 0, here ?? 0);
         return { skipped: { questions: q.records, network: n.records, seqs: n.seqs }, toSeq };
@@ -823,7 +834,8 @@ let ConversationsService = 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.
      */
     async announceSkipped(skipped) {
         for (const q of skipped.questions) {
@@ -877,6 +889,10 @@ let ConversationsService = class ConversationsService {
         events.push(this.userMessage(accountId, input, extra, blocks, invoked, context, internal.schedule));
         const { events: written, fresh } = await this.eventLog.appendInReport(conversationId, events);
         const message = written.at(-1);
+        // the run this message starts is owed with it: the direct ensureRun after the commit may never
+        // happen (the process died) or fail (transactional outbox spec §6)
+        if (fresh.at(-1) === true)
+            await this.runs.oweEnsureRun(conversationId, message.seq, orgId);
         const skips = fresh.at(-1) === true
             ? await this.skipWaitsIn(conversationId, accountId, message.seq)
             : { skipped: NO_REPLY_SKIPS, toSeq: null };
@@ -995,13 +1011,24 @@ let ConversationsService = class ConversationsService {
             throw new ApiError("run.not_active", "No active run to abort");
         const runs = this.runs;
         // 等待中：直接结束；没成功（刚被续跑、已回到 queued）则按下面的常规路径中止。
+        // the stop's terminal transaction owed the ensure-run backstop; the direct call starts what
+        // waited for the stopped run now
         if (run.status === "waiting" && (await runs.abortWaiting(conversationId, run.id, accountId))) {
-            this.kickRun(conversationId);
+            await runs.ensureRunAfterCommit(conversationId);
+            return run.id;
+        }
+        // a queued run no worker has started yet is ended in PG (ruling R27), never left to the stop
+        // marker's TTL: the marker first, so a worker that takes it meanwhile stops too
+        if (run.status === "queued") {
+            await runs.requestAbort(run.id, accountId);
+            if (await runs.abortQueued(conversationId, run.id, accountId)) {
+                await runs.ensureRunAfterCommit(conversationId);
+            }
             return run.id;
         }
         // 孤儿运行没有 worker 在听中止广播：直接写成 aborted，之后再看有没有等待中的消息要起新一轮。
         if (await runs.abortIfOrphaned(conversationId, run.id, accountId)) {
-            this.kickRun(conversationId);
+            await runs.ensureRunAfterCommit(conversationId);
             return run.id;
         }
         await runs.requestAbort(run.id, accountId);
@@ -1034,15 +1061,14 @@ ConversationsService = __decorate([
     __param(3, Inject(ConversationAccess)),
     __param(4, Inject(RunControlService)),
     __param(5, Inject(ProviderRegistry)),
-    __param(6, Inject(KERNEL_LOGGER)),
-    __param(7, Inject(ConnectorContent)),
-    __param(8, Inject(AttachmentsService)),
-    __param(9, Inject(SkillInvoker)),
-    __param(10, Inject(BackgroundTaskStopper)),
-    __param(11, Inject(ConversationDevices)),
-    __param(12, Inject(QuestionsService)),
-    __param(13, Inject(ApprovalsService)),
-    __param(14, Inject(KernelEvents)),
-    __param(15, Inject(TransactionHost))
+    __param(6, Inject(ConnectorContent)),
+    __param(7, Inject(AttachmentsService)),
+    __param(8, Inject(SkillInvoker)),
+    __param(9, Inject(BackgroundTaskStopper)),
+    __param(10, Inject(ConversationDevices)),
+    __param(11, Inject(QuestionsService)),
+    __param(12, Inject(ApprovalsService)),
+    __param(13, Inject(KernelEvents)),
+    __param(14, Inject(TransactionHost))
 ], ConversationsService);
 export { ConversationsService };

package/dist/conversations/event-log.d.ts

@@ -1,6 +1,6 @@
 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 { OutboxService } from "../infra/outbox/outbox.service.js";
 import type { KernelLogger } from "../log.js";
 import { type ConversationEvent, type ConversationEventType } from "./events.js";
 /** 事件日志依赖的总线：内核 bus（命名空间 `kernel`）。 */
@@ -74,17 +74,17 @@ export type ConversationChange = (typeof CONVERSATION_CHANGES)[number];
  * seq 由 `conversations.last_seq` 在会话行锁内连续分配（多副本并发写同一会话时串行化）；
  * 幂等键的「先查后写」也在同一把行锁内完成。
  *
- * Every published advance (`notify`) is also announced in-process as `conversation.event-appended`
- * on {@link KernelEvents} (the channel outbound delivery enqueues from it), on this replica, right
- * after the bus publish, in append order.
+ * An append to a conversation with a channel target (`channel_deliveries`, read with the row lock)
+ * owes the conversation's IM delivery in the append's transaction (transactional outbox spec
+ * §8.1); a conversation without one writes nothing more.
  */
 export declare class EventLog {
     private readonly db;
     private readonly bus;
     private readonly log;
-    private readonly events;
+    private readonly outbox;
     readonly txHost: TransactionHost;
-    constructor(db: KernelDb, bus: EventBus, log: Pick<KernelLogger, "warn">, events: Pick<KernelEvents, "emit">, txHost: TransactionHost);
+    constructor(db: KernelDb, bus: EventBus, log: Pick<KernelLogger, "warn">, outbox: Pick<OutboxService, "add">, txHost: TransactionHost);
     /**
      * 追加事件，返回与输入一一对应的事件（幂等命中的为已有事件）。
      * 自开一个独立事务（`requires_new`，与调用方的事务无关），提交后发布 `conv.<id>`。
@@ -107,10 +107,7 @@ export declare class EventLog {
         fresh: boolean[];
     }>;
     private appendOwn;
-    /**
-     * 发布「日志已推进到 toSeq」；发布失败只记日志（事件已提交，订阅方可按 seq 补读）。Then announces
-     * it in-process (`conversation.event-appended`); a failing subscriber is logged by KernelEvents.
-     */
+    /** 发布「日志已推进到 toSeq」；发布失败只记日志（事件已提交，订阅方可按 seq 补读）。 */
     notify(conversationId: string, toSeq: number): Promise<void>;
     /**
      * Publishes a `changed` frame on the conversation topic (rename, generated title, selection, ...).

package/dist/conversations/event-log.js

@@ -9,11 +9,12 @@ var __param = (this && this.__param) || function (paramIndex, decorator) {
 };
 import { Inject, Injectable, Module } from "@nestjs/common";
 import { sql } from "kysely";
+import { oweDelivery } from "../channels/deliver-job.js";
 import { ApiError } from "../errors.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 { OutboxService } from "../infra/outbox/outbox.service.js";
 import { KERNEL_BUS, KERNEL_LOGGER } from "../infra/tokens.js";
 import { ConversationEventSchema, } from "./events.js";
 /**
@@ -75,21 +76,21 @@ const EVENT_COLUMNS = [
  * seq 由 `conversations.last_seq` 在会话行锁内连续分配（多副本并发写同一会话时串行化）；
  * 幂等键的「先查后写」也在同一把行锁内完成。
  *
- * Every published advance (`notify`) is also announced in-process as `conversation.event-appended`
- * on {@link KernelEvents} (the channel outbound delivery enqueues from it), on this replica, right
- * after the bus publish, in append order.
+ * An append to a conversation with a channel target (`channel_deliveries`, read with the row lock)
+ * owes the conversation's IM delivery in the append's transaction (transactional outbox spec
+ * §8.1); a conversation without one writes nothing more.
  */
 let EventLog = class EventLog {
     db;
     bus;
     log;
-    events;
+    outbox;
     txHost;
-    constructor(db, bus, log, events, txHost) {
+    constructor(db, bus, log, outbox, txHost) {
         this.db = db;
         this.bus = bus;
         this.log = log;
-        this.events = events;
+        this.outbox = outbox;
         this.txHost = txHost;
     }
     /**
@@ -126,10 +127,7 @@ let EventLog = class EventLog {
         const { events: out, toSeq } = await this.write(conversationId, events, bodies);
         return { events: out, toSeq };
     }
-    /**
-     * 发布「日志已推进到 toSeq」；发布失败只记日志（事件已提交，订阅方可按 seq 补读）。Then announces
-     * it in-process (`conversation.event-appended`); a failing subscriber is logged by KernelEvents.
-     */
+    /** 发布「日志已推进到 toSeq」；发布失败只记日志（事件已提交，订阅方可按 seq 补读）。 */
     async notify(conversationId, toSeq) {
         const msg = { kind: "events", toSeq };
         try {
@@ -138,7 +136,6 @@ let EventLog = class EventLog {
         catch (err) {
             this.log.warn("conversation event notify failed", { conversationId, toSeq, err });
         }
-        await this.events.emit("conversation.event-appended", { conversationId, toSeq });
     }
     /**
      * Publishes a `changed` frame on the conversation topic (rename, generated title, selection, ...).
@@ -300,10 +297,20 @@ let EventLog = class EventLog {
     /** The append itself, in the context's transaction (both callers open or join one). */
     async write(conversationId, events, bodies) {
         const t = this.db;
-        // 先锁会话行：之后的幂等查询与 seq 分配都在这把锁内，并发 append 依次执行。
+        // 先锁会话行：之后的幂等查询与 seq 分配都在这把锁内，并发 append 依次执行。The same statement
+        // reads whether the conversation has a channel target (its primary key), under the lock that
+        // `ChannelJobs.bind` takes too
         const conv = await t
             .selectFrom("conversations")
-            .select("id")
+            .select((eb) => [
+            "org_id",
+            eb
+                .exists(eb
+                .selectFrom("channel_deliveries")
+                .select("channel_deliveries.conversation_id")
+                .whereRef("channel_deliveries.conversation_id", "=", "conversations.id"))
+                .as("im"),
+        ])
             .where("id", "=", conversationId)
             .forUpdate()
             .executeTakeFirst();
@@ -378,6 +385,8 @@ let EventLog = class EventLog {
         }))
             .returning(EVENT_COLUMNS)
             .execute();
+        if (conv.im)
+            await oweDelivery(this.outbox, { conversationId, orgId: conv.org_id, seq: toSeq });
         const bySeq = new Map(inserted.map((r) => [Number(r.seq), toEvent(r)]));
         return {
             events: plan.map((p) => p.kind === "old" ? p.event : bySeq.get(base + p.index + 1)),
@@ -400,7 +409,7 @@ EventLog = __decorate([
     __param(0, Inject(KernelDb)),
     __param(1, Inject(KERNEL_BUS)),
     __param(2, Inject(KERNEL_LOGGER)),
-    __param(3, Inject(KernelEvents)),
+    __param(3, Inject(OutboxService)),
     __param(4, Inject(TransactionHost))
 ], EventLog);
 export { EventLog };

package/dist/conversations/events.d.ts

@@ -200,6 +200,20 @@ export declare const RunContextSchema: z.ZodObject<{
         person: z.ZodString;
     }, z.core.$strip>>;
 }, z.core.$strip>;
+/**
+ * The most UTF-8 bytes a `plugin_context` event's text may hold (memory spec §6.1): the providers'
+ * limit, so the log takes every text a provider may return.
+ */
+export declare const PLUGIN_CONTEXT_MAX_BYTES: number;
+/**
+ * `plugin_context` (memory spec §6.1): the text a `context@1` provider added at a run start. Empty
+ * text means the provider has nothing (any more); `hash` is the sha256 (hex) of `text`.
+ */
+export declare const PluginContextSchema: z.ZodObject<{
+    plugin: z.ZodString;
+    text: z.ZodString;
+    hash: z.ZodString;
+}, z.core.$strip>;
 /**
  * 会话事件（`type` + `payload`）的判别联合。事件日志只追加，写入前用它校验 payload；
  * 读出时按写入时的形状原样返回。
@@ -547,6 +561,13 @@ export declare const ConversationEventSchema: z.ZodDiscriminatedUnion<[z.ZodObje
             person: z.ZodString;
         }, z.core.$strip>>;
     }, z.core.$strip>;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"plugin_context">;
+    payload: z.ZodObject<{
+        plugin: z.ZodString;
+        text: z.ZodString;
+        hash: z.ZodString;
+    }, z.core.$strip>;
 }, z.core.$strip>, z.ZodObject<{
     type: z.ZodLiteral<"tools_changed">;
     payload: z.ZodObject<{

package/dist/conversations/events.js

@@ -1,4 +1,4 @@
-import { DOCUMENT_MEDIA_TYPES, hasControlChars, IMAGE_MEDIA_TYPES, isAttachmentId, isSkillName, MEDIA_NAME_MAX_CHARS, } from "@capybara-hq/plugin-sdk";
+import { CONTEXT_LIMITS, DOCUMENT_MEDIA_TYPES, hasControlChars, IMAGE_MEDIA_TYPES, isAttachmentId, isSkillName, MEDIA_NAME_MAX_CHARS, } from "@capybara-hq/plugin-sdk";
 import { z } from "zod";
 import { AgentDefinitionSchema, DisabledSkillRef, DisabledToolRef, ModelRef, } from "../agents/definition.js";
 import { ORG_ROLES } from "../orgs/roles.js";
@@ -228,6 +228,22 @@ export const RunContextSchema = z.object({
         .optional(),
 });
 const ev = (type, payload) => z.object({ type: z.literal(type), payload });
+/**
+ * The most UTF-8 bytes a `plugin_context` event's text may hold (memory spec §6.1): the providers'
+ * limit, so the log takes every text a provider may return.
+ */
+export const PLUGIN_CONTEXT_MAX_BYTES = CONTEXT_LIMITS.maxBytes;
+/**
+ * `plugin_context` (memory spec §6.1): the text a `context@1` provider added at a run start. Empty
+ * text means the provider has nothing (any more); `hash` is the sha256 (hex) of `text`.
+ */
+export const PluginContextSchema = z.object({
+    plugin: z.string().min(1).max(64),
+    text: z.string().refine((t) => Buffer.byteLength(t, "utf8") <= PLUGIN_CONTEXT_MAX_BYTES, {
+        message: `at most ${PLUGIN_CONTEXT_MAX_BYTES} UTF-8 bytes`,
+    }),
+    hash: z.string().regex(/^[0-9a-f]{64}$/),
+});
 /**
  * An agent definition frozen into a log (`subagent_started`): the current schema, with the
  * selected and pinned skills of older logs still accepted (skills default-on spec §4: history
@@ -485,6 +501,13 @@ export const ConversationEventSchema = z.discriminatedUnion("type", [
      * system message (`runContextText`); a summary covering it restores the current values.
      */
     ev("run_context", RunContextSchema),
+    /**
+     * Text a `context@1` provider added at a run start (memory spec §6.1), written only when its
+     * hash differs from the plugin's previous one in the conversation. **Model-visible**: rendered
+     * at its position as a system message (`pluginContextText`, nothing for empty text); a summary
+     * covering it is followed by the latest non-empty one per plugin again.
+     */
+    ev("plugin_context", PluginContextSchema),
     /**
      * The step's resolved tool set differs from the one the conversation's previous model request
      * offered (`toolSetChange`): tool names as the model sees them, sorted. Written before that
@@ -776,7 +799,8 @@ export const ConversationEventSchema = z.discriminatedUnion("type", [
          * naming a template's skills the child loads first (skills default-on spec §6.1).
          */
         preamble: z.string(),
-        maxSteps: z.number().int().positive(),
+        /** The child's step limit; 0 = no limit (`runtime.maxSteps` 0, no template limit). */
+        maxSteps: z.number().int().nonnegative(),
         warnings: z.array(z.string()).optional(),
     })),
     /**

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

@@ -12,12 +12,12 @@ export declare class ConversationQueue {
     private readonly db;
     private readonly eventLog;
     private readonly conversations;
-    /** Starts the conversation's next run (`ensureRun`). */
+    /** Starts the conversation's next run after a commit (a failure is logged, never thrown). */
     private readonly runs;
     readonly txHost: TransactionHost;
     constructor(db: KernelDb, eventLog: Pick<EventLog, "appendIn" | "notify" | "publishChanged" | "findByIdem">, conversations: Pick<ConversationsService, "get" | "writable" | "resolveExtra" | "bindIn" | "checkPick" | "prepareQueuedSkill" | "skipWaitsIn" | "announceSkipped">, 
-    /** Starts the conversation's next run (`ensureRun`). */
-    runs: Pick<RunControl, "ensureRun" | "wakeHeldTree">, txHost: TransactionHost);
+    /** Starts the conversation's next run after a commit (a failure is logged, never thrown). */
+    runs: Pick<RunControl, "ensureRunAfterCommit" | "oweEnsureRun" | "wakeHeldTree" | "oweHeldTreeIn">, txHost: TransactionHost);
     list(orgId: string, conversationId: string, accountId: string): Promise<{
         items: QueueItem[];
         paused: boolean;
@@ -60,6 +60,11 @@ export declare class ConversationQueue {
     private sendNowIn;
     /** "Continue sending": clears the pause and lets `ensureRun` send the head item. */
     resume(orgId: string, conversationId: string, accountId: string): Promise<void>;
+    /**
+     * Clears the pause and owes the ensure-run backstop that sends the head item (no event of its
+     * own, so under the conversation's newest seq; transactional outbox spec §6).
+     */
+    private resumeIn;
     /** A queued item or a sent message for this client id (outside any transaction). */
     private prior;
     private lockConversation;