@capybara-hq/kernel 0.1.0-rc.2 → 0.1.0-rc.20

package/dist/conversations/device-status.d.ts

@@ -0,0 +1,24 @@
+import { DevicesService, type DeviceView } from "../devices/devices.service.js";
+import { KernelDb } from "../infra/database/kernel-db.js";
+import { ConversationAccess } from "./access.js";
+import { ConversationsService } from "./conversations.service.js";
+/**
+ * The device a conversation works in, for its page (environments spec §9: shown read only):
+ * a conversation the viewer may not see → `conversation.not_found`. A sub-agent shows its root
+ * conversation's device. Null while the conversation is unbound, or when its device is
+ * deleted or no longer its owner's (its sandbox tools then fail).
+ */
+export declare class ConversationDeviceStatus {
+    /** Who may see the conversation (the rule of its event stream). */
+    private readonly access;
+    /** The conversation whose device it works in: a sub-agent's root, else itself. */
+    private readonly conversations;
+    private readonly devices;
+    private readonly db;
+    constructor(
+    /** Who may see the conversation (the rule of its event stream). */
+    access: Pick<ConversationAccess, "isAccessible">, 
+    /** The conversation whose device it works in: a sub-agent's root, else itself. */
+    conversations: Pick<ConversationsService, "sandboxConversationOf">, devices: Pick<DevicesService, "get">, db: KernelDb);
+    get(orgId: string, conversationId: string, viewerAccountId: string): Promise<DeviceView | null>;
+}

package/dist/conversations/device-status.js

@@ -0,0 +1,71 @@
+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 { DevicesService } from "../devices/devices.service.js";
+import { ApiError } from "../errors.js";
+import { KernelDb } from "../infra/database/kernel-db.js";
+import { UUID_RE } from "../ui/registry.js";
+import { ConversationAccess } from "./access.js";
+import { ConversationsService } from "./conversations.service.js";
+/**
+ * The device a conversation works in, for its page (environments spec §9: shown read only):
+ * a conversation the viewer may not see → `conversation.not_found`. A sub-agent shows its root
+ * conversation's device. Null while the conversation is unbound, or when its device is
+ * deleted or no longer its owner's (its sandbox tools then fail).
+ */
+let ConversationDeviceStatus = class ConversationDeviceStatus {
+    access;
+    conversations;
+    devices;
+    db;
+    constructor(
+    /** Who may see the conversation (the rule of its event stream). */
+    access, 
+    /** The conversation whose device it works in: a sub-agent's root, else itself. */
+    conversations, devices, db) {
+        this.access = access;
+        this.conversations = conversations;
+        this.devices = devices;
+        this.db = db;
+    }
+    async get(orgId, conversationId, viewerAccountId) {
+        if (!UUID_RE.test(conversationId) ||
+            !(await this.access.isAccessible(orgId, conversationId, viewerAccountId))) {
+            throw new ApiError("conversation.not_found", "Conversation not found");
+        }
+        // a sub-agent works in its root conversation's device (at every depth)
+        const root = await this.conversations.sandboxConversationOf(orgId, conversationId);
+        const conv = await this.db
+            .selectFrom("conversations")
+            .select(["account_id", "device_id"])
+            .where("id", "=", root)
+            .where("org_id", "=", orgId)
+            .executeTakeFirst();
+        if (!conv?.device_id)
+            return null;
+        try {
+            // the device as its owner sees it (only the owner may use a personal device)
+            return await this.devices.get(orgId, conv.account_id, conv.device_id);
+        }
+        catch (e) {
+            if (e instanceof ApiError && e.code === "device.not_found")
+                return null;
+            throw e;
+        }
+    }
+};
+ConversationDeviceStatus = __decorate([
+    Injectable(),
+    __param(0, Inject(ConversationAccess)),
+    __param(1, Inject(ConversationsService)),
+    __param(2, Inject(DevicesService)),
+    __param(3, Inject(KernelDb))
+], ConversationDeviceStatus);
+export { ConversationDeviceStatus };

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

@@ -28,13 +28,16 @@ export declare const conversationTopic: (conversationId: string) => string;
  * 会话频道上的总线消息：
  * - `events`：会话日志已推进到 `toSeq`（订阅方据此 `readAfter` 补读，消息本身不携带事件）；
  * - `delta`：运行的流式增量（文本 / 思考 / `step_reset`：丢弃该步此前推出的增量），只是草稿，
- *   最终内容以日志中的 assistant_message 为准。`offset`（仅 text）：本步本次尝试中此前已推出的文本字符数，
- *   中途才订阅的一方据此判断自己是否从头收到了该步的文本（渠道出站投递只在完整时发草稿）；
+ *   最终内容以日志中的 assistant_message 为准。`offset` (text and thinking): the characters of
+ *   that channel this attempt of the step streamed before the delta; a subscriber that joined midway
+ *   tells by it whether it has the step's text from the start (the channel outbound only drafts
+ *   complete text) and drops what a live draft already covers (spec 2026-11-07 §3.2);
  * - `ui`：插件经 `ctx.ui.invalidate` 告知这个会话的某个界面贡献变了（不进日志、不是模型可见内容），
  *   SSE 转发为 `event: ui`，网页据此重新取视图。
- * - `subagent_progress`: after each step of a sub-agent run, on its **parent's** topic (sub-agents
- *   spec §14.2): the child's step and tool call count so far, and its last tool's key. Not in any
- *   log; the SSE forwards it as `event: subagent_progress` (data without `kind`).
+ * - `subagent_progress`: after each step of a sub-agent run, on the topic of **every ancestor**
+ *   (sub-agents spec §14.2, agent map spec §8), `subagentId` the progressing agent: its step and
+ *   tool call count so far, and its last tool's key. Not in any log; the SSE forwards it as
+ *   `event: subagent_progress` (data without `kind`).
  */
 export type ConversationBusMessage = {
     kind: "events";
@@ -64,7 +67,7 @@ export type ConversationBusMessage = {
  * What changed about a conversation outside its event log (UI refresh B): the SSE stream sends it as
  * `event: changed` with `{ what }`, and the web refetches that part. Never model-visible.
  */
-export declare const CONVERSATION_CHANGES: readonly ["title", "queue", "selection", "files"];
+export declare const CONVERSATION_CHANGES: readonly ["title", "queue", "selection", "files", "archived", "deleted", "background"];
 export type ConversationChange = (typeof CONVERSATION_CHANGES)[number];
 /**
  * 会话事件日志：只追加，是 agent 运行的唯一事实来源。
@@ -94,6 +97,15 @@ export declare class EventLog {
      * commit with the highest seq it wrote.
      */
     appendIn(conversationId: string, events: AppendEvent[]): Promise<ConversationEvent[]>;
+    /**
+     * {@link appendIn} that also says, per input, whether this call wrote the event (`fresh[i]`) or
+     * returned an earlier one by its idempotency key (a retried message, reply-while-question spec
+     * §8.1). Same transaction contract: the caller's, `mandatory`.
+     */
+    appendInReport(conversationId: string, events: AppendEvent[]): Promise<{
+        events: ConversationEvent[];
+        fresh: boolean[];
+    }>;
     private appendOwn;
     /**
      * 发布「日志已推进到 toSeq」；发布失败只记日志（事件已提交，订阅方可按 seq 补读）。Then announces
@@ -107,6 +119,18 @@ export declare class EventLog {
     publishChanged(conversationId: string, what: ConversationChange): Promise<void>;
     /** 读 `afterSeq` 之后的事件，按 seq 升序，最多 `limit` 条。 */
     readAfter(conversationId: string, afterSeq: number, limit?: number): Promise<ConversationEvent[]>;
+    /**
+     * The page of the log that ends right before `beforeSeq` (`null`: the log's end), in ascending
+     * seq: the last `limit` events before it, extended back so the first event is the log's first or
+     * the first one after a run's end (`run_finished` / `run_failed` / `run_aborted`), at most
+     * `extend` events further back (a longer run then starts mid-run). `turnsBefore`: how many runs
+     * started (distinct `run_id` of `run_started`) before the page's first event. History paging
+     * spec §2.
+     */
+    readTurnPageBefore(conversationId: string, beforeSeq: number | null, limit: number, extend: number): Promise<{
+        events: ConversationEvent[];
+        turnsBefore: number;
+    }>;
     /**
      * 读 `afterSeq` 之后、属于 `runIds` 中某次运行的事件，按 seq 升序，最多 `limit` 条（轨迹按运行分页用）。
      * `runIds` 为空时返回空数组。走部分索引 `conversation_events_run_idx (conversation_id, run_id, seq)`（0027）：
@@ -116,13 +140,25 @@ export declare class EventLog {
     /** 按幂等键取事件；没有 → undefined。 */
     findByIdem(conversationId: string, idemKey: string): Promise<ConversationEvent | undefined>;
     /**
-     * 会话里某类事件的最新一条（按 seq）；没有 → undefined。`skills_catalog` 有部分索引
-     * （0025，按会话直接取到最新一条）；其他类型按 (conversation_id, seq) 主键倒序扫本会话的事件并按 type 过滤，
-     * 没有该类事件时会扫完整个会话。
+     * The conversation's latest event of `type` (by seq); undefined without one. `skills_catalog`
+     * (0025) and `device_paths` (0094) have partial indexes that answer it directly; other
+     * types scan the conversation's events backwards on the (conversation_id, seq) key, the whole
+     * conversation when it has none.
      */
     latestOfType<T extends ConversationEventType>(conversationId: string, type: T): Promise<Extract<ConversationEvent, {
         type: T;
     }> | undefined>;
+    /**
+     * The file state (`tool_result.view.file`) the latest `Read` / `Write` / `Edit` result of this
+     * conversation recorded for `path` (a normalized sandbox path); null when none did. One index
+     * probe per call: the partial index `conversation_events_file_state_idx` of migration 0063
+     * (conversation_id, view.file.path, seq DESC; tool_result rows only) answers it, also for a path
+     * never read (the query's predicate must keep matching that index's expression).
+     */
+    latestFileState(conversationId: string, path: string): Promise<{
+        size: number;
+        sha256: string;
+    } | null>;
     private validate;
     /** The append itself, in the context's transaction (both callers open or join one). */
     private write;

package/dist/conversations/event-log.js

@@ -41,7 +41,16 @@ export const conversationTopic = (conversationId) => `conv.${conversationId}`;
  * What changed about a conversation outside its event log (UI refresh B): the SSE stream sends it as
  * `event: changed` with `{ what }`, and the web refetches that part. Never model-visible.
  */
-export const CONVERSATION_CHANGES = ["title", "queue", "selection", "files"];
+export const CONVERSATION_CHANGES = [
+    "title",
+    "queue",
+    "selection",
+    "files",
+    "archived",
+    "deleted",
+    // the conversation's background tasks (or its sub-agents')
+    "background",
+];
 const notFound = () => new ApiError("conversation.not_found", "Conversation not found");
 function toEvent(r) {
     return {
@@ -101,11 +110,21 @@ let EventLog = class EventLog {
      * commit with the highest seq it wrote.
      */
     async appendIn(conversationId, events) {
+        return (await this.appendInReport(conversationId, events)).events;
+    }
+    /**
+     * {@link appendIn} that also says, per input, whether this call wrote the event (`fresh[i]`) or
+     * returned an earlier one by its idempotency key (a retried message, reply-while-question spec
+     * §8.1). Same transaction contract: the caller's, `mandatory`.
+     */
+    async appendInReport(conversationId, events) {
         const bodies = events.map((e) => this.validate(e));
-        return (await this.write(conversationId, events, bodies)).events;
+        const { events: out, fresh } = await this.write(conversationId, events, bodies);
+        return { events: out, fresh };
     }
     async appendOwn(conversationId, events, bodies) {
-        return this.write(conversationId, events, bodies);
+        const { events: out, toSeq } = await this.write(conversationId, events, bodies);
+        return { events: out, toSeq };
     }
     /**
      * 发布「日志已推进到 toSeq」；发布失败只记日志（事件已提交，订阅方可按 seq 补读）。Then announces
@@ -146,6 +165,66 @@ let EventLog = class EventLog {
             .execute();
         return rows.map(toEvent);
     }
+    /**
+     * The page of the log that ends right before `beforeSeq` (`null`: the log's end), in ascending
+     * seq: the last `limit` events before it, extended back so the first event is the log's first or
+     * the first one after a run's end (`run_finished` / `run_failed` / `run_aborted`), at most
+     * `extend` events further back (a longer run then starts mid-run). `turnsBefore`: how many runs
+     * started (distinct `run_id` of `run_started`) before the page's first event. History paging
+     * spec §2.
+     */
+    async readTurnPageBefore(conversationId, beforeSeq, limit, extend) {
+        let q = this.db
+            .selectFrom("conversation_events")
+            .select(EVENT_COLUMNS)
+            .where("conversation_id", "=", conversationId);
+        if (beforeSeq !== null)
+            q = q.where("seq", "<", String(beforeSeq));
+        const rows = (await q.orderBy("seq", "desc").limit(limit).execute()).reverse();
+        const first = rows[0] === undefined ? null : Number(rows[0].seq);
+        if (first === null)
+            return { events: [], turnsBefore: 0 };
+        let start = first;
+        if (first > 1) {
+            // the latest run end at or before the event just above the page, within the extension
+            const end = await this.db
+                .selectFrom("conversation_events")
+                .select((eb) => eb.fn.max("seq").as("seq"))
+                .where("conversation_id", "=", conversationId)
+                .where("seq", "<", String(first))
+                .where("seq", ">=", String(Math.max(1, first - 1 - extend)))
+                .where("type", "in", ["run_finished", "run_failed", "run_aborted"])
+                .executeTakeFirst();
+            // none within reach: the page starts at the log's start when that is in reach, else mid-run
+            if (end?.seq != null)
+                start = Number(end.seq) + 1;
+            else if (first - 1 <= extend)
+                start = 1;
+        }
+        const head = start < first
+            ? await this.db
+                .selectFrom("conversation_events")
+                .select(EVENT_COLUMNS)
+                .where("conversation_id", "=", conversationId)
+                .where("seq", ">=", String(start))
+                .where("seq", "<", String(first))
+                .orderBy("seq")
+                .execute()
+            : [];
+        const turns = start > 1
+            ? await this.db
+                .selectFrom("conversation_events")
+                .select((eb) => eb.fn.count("run_id").distinct().as("n"))
+                .where("conversation_id", "=", conversationId)
+                .where("type", "=", "run_started")
+                .where("seq", "<", String(start))
+                .executeTakeFirst()
+            : undefined;
+        return {
+            events: [...head, ...rows].map(toEvent),
+            turnsBefore: Number(turns?.n ?? 0),
+        };
+    }
     /**
      * 读 `afterSeq` 之后、属于 `runIds` 中某次运行的事件，按 seq 升序，最多 `limit` 条（轨迹按运行分页用）。
      * `runIds` 为空时返回空数组。走部分索引 `conversation_events_run_idx (conversation_id, run_id, seq)`（0027）：
@@ -176,9 +255,10 @@ let EventLog = class EventLog {
         return r && toEvent(r);
     }
     /**
-     * 会话里某类事件的最新一条（按 seq）；没有 → undefined。`skills_catalog` 有部分索引
-     * （0025，按会话直接取到最新一条）；其他类型按 (conversation_id, seq) 主键倒序扫本会话的事件并按 type 过滤，
-     * 没有该类事件时会扫完整个会话。
+     * The conversation's latest event of `type` (by seq); undefined without one. `skills_catalog`
+     * (0025) and `device_paths` (0094) have partial indexes that answer it directly; other
+     * types scan the conversation's events backwards on the (conversation_id, seq) key, the whole
+     * conversation when it has none.
      */
     async latestOfType(conversationId, type) {
         const r = await this.db
@@ -191,6 +271,25 @@ let EventLog = class EventLog {
             .executeTakeFirst();
         return r && toEvent(r);
     }
+    /**
+     * The file state (`tool_result.view.file`) the latest `Read` / `Write` / `Edit` result of this
+     * conversation recorded for `path` (a normalized sandbox path); null when none did. One index
+     * probe per call: the partial index `conversation_events_file_state_idx` of migration 0063
+     * (conversation_id, view.file.path, seq DESC; tool_result rows only) answers it, also for a path
+     * never read (the query's predicate must keep matching that index's expression).
+     */
+    async latestFileState(conversationId, path) {
+        const r = await this.db
+            .selectFrom("conversation_events")
+            .select(sql `payload->'view'->'file'`.as("file"))
+            .where("conversation_id", "=", conversationId)
+            .where("type", "=", "tool_result")
+            .where(sql `payload->'view'->'file'->>'path' = ${path}`)
+            .orderBy("seq", "desc")
+            .limit(1)
+            .executeTakeFirst();
+        return r ? { size: r.file.size, sha256: r.file.sha256 } : null;
+    }
     validate(e) {
         const r = ConversationEventSchema.safeParse({ type: e.type, payload: e.payload });
         if (!r.success) {
@@ -244,10 +343,14 @@ let EventLog = class EventLog {
                 fresh.push(i);
             }
         });
+        // written by this call: the first input of each new event (a repeat in the batch points to it)
+        const freshSet = new Set(fresh);
+        const isFresh = events.map((_, i) => freshSet.has(i));
         if (fresh.length === 0) {
             return {
                 events: plan.map((p) => p.event),
                 toSeq: null,
+                fresh: isFresh,
             };
         }
         const n = fresh.length;
@@ -279,12 +382,16 @@ let EventLog = class EventLog {
         return {
             events: plan.map((p) => p.kind === "old" ? p.event : bySeq.get(base + p.index + 1)),
             toSeq,
+            fresh: isFresh,
         };
     }
 };
 __decorate([
     Transactional({ propagation: "mandatory" })
 ], EventLog.prototype, "appendIn", null);
+__decorate([
+    Transactional({ propagation: "mandatory" })
+], EventLog.prototype, "appendInReport", null);
 __decorate([
     Transactional({ propagation: "requires_new" })
 ], EventLog.prototype, "appendOwn", null);