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

package/dist/conversations/conversations.controller.js

@@ -12,37 +12,52 @@ import { z } from "zod";
 import { ModelRef } from "../agents/definition.js";
 import { CurrentPrincipal, requireUser } from "../identity/principal.js";
 import { createZodDto } from "../infra/validation/create-zod-dto.js";
-import { ZBody, ZQuery } from "../infra/validation/zod-params.js";
+import { ZBody, ZParam, ZQuery } from "../infra/validation/zod-params.js";
 import { CurrentOrg, OrgAction } from "../orgs/org.guard.js";
 import { CONTROL_OR_HIDDEN_RE } from "../text.js";
 import { MAX_ATTACHMENTS } from "../tools/connector-content.js";
 import { ConversationToolInfo, TOOL_INFO_KEY_MAX, TOOL_INFO_MAX_KEYS, } from "../tools/info.js";
 import { ARTIFACT_DOWNLOAD_CACHE_SECONDS, ConversationArtifacts, } from "./artifacts.js";
 import { CONVERSATION_TITLE_MAX_CHARS, ConversationsService, } from "./conversations.service.js";
+import { ConversationEnvironmentStatus } from "./environment-status.js";
 import { ConversationFiles, FILE_CONTENT_MAX_BYTES, FILES_PAGE_MAX, } from "./files.js";
 import { ConversationOutputs, OUTPUT_PAGE_MAX_CHARS } from "./outputs-read.js";
 import { ConversationQueue } from "./queue.service.js";
-import { ConversationSandboxStatus } from "./sandbox-status.js";
+/** Shared by the list and groups queries: title search, run activity and the archived list. */
+const searchFields = {
+    q: z.string().min(1).max(100).optional(),
+    state: z.enum(["running", "waiting"]).optional(),
+    archived: z.enum(["1"]).optional(),
+};
 const ListQuery = z.object({
     after: z.string().min(1).max(100).optional(),
     limit: z.coerce.number().int().min(1).max(200).default(50),
     /** Only this agent's conversations (the sidebar's per-group "More"). */
     agentId: z.string().min(1).max(100).optional(),
+    ...searchFields,
 });
 const GroupsQuery = z.object({
     perGroup: z.coerce.number().int().min(1).max(20).default(5),
     limit: z.coerce.number().int().min(1).max(50).default(20),
     /** The last group's agent id from the previous page (`next`). */
     after: z.string().min(1).max(100).optional(),
+    ...searchFields,
 });
 const SubagentsQuery = z.object({
     /** The previous page's last sub-agent id (`next`). */
     after: z.string().min(1).max(100).optional(),
     limit: z.coerce.number().int().min(1).max(100).default(50),
 });
-const EventsQuery = z.object({
-    after: z.coerce.number().int().min(0).default(0),
+const EventsQuery = z
+    .object({
+    after: z.coerce.number().int().min(0).optional(),
+    /** The page before this seq, or the log's last page (`end`); exclusive with `after`. */
+    before: z.union([z.literal("end"), z.coerce.number().int().min(1)]).optional(),
     limit: z.coerce.number().int().min(1).max(500).default(500),
+})
+    .refine((q) => q.after === undefined || q.before === undefined, {
+    message: "after and before are exclusive",
+    path: ["before"],
 });
 /** `?keys=a,b`: 1–100 comma-separated tool keys of 1–200 characters each. */
 const ToolsQuery = z.object({
@@ -117,10 +132,13 @@ const MessageBody = MessageFields.strict().refine(...textRule);
  * `POST /conversations`: `message` creates the conversation with its first message (create on
  * first send; `clientMessageId` is required and makes a retry return the same conversation).
  * Without it the conversation is created empty (API clients; the web never does).
+ * `environmentId` binds it to one of the caller's environments; without it the caller's default
+ * environment (environments spec §4.1 item 1).
  */
 const CreateBody = z
     .object({
     agentId: z.string().min(1).max(100),
+    environmentId: z.string().min(1).max(100).optional(),
     message: MessageFields.omit({ retryOf: true })
         .extend({ clientMessageId: z.string().min(1).max(200) })
         .strict()
@@ -129,9 +147,7 @@ const CreateBody = z
 })
     .strict();
 /**
- * `POST …/queue`: the message fields that can be queued (no retry). A model / effort pick is checked
- * now and applied when the message is sent (final review I1). A skill invocation is rendered now
- * and checked again when sent (phase D Task 9).
+ * `POST …/queue` (deprecated, behaves as `POST …/messages`): the message fields (no retry).
  */
 const QueueBody = MessageFields.omit({ retryOf: true })
     .extend({ clientMessageId: z.string().min(1).max(200) })
@@ -143,7 +159,7 @@ const QueueEditBody = z.object({ text: z.string().max(100_000) }).strict();
  * A rename: 1–120 characters counted in code points after trimming, with no control or format
  * (bidi, zero-width) characters, the same rule generated and tool titles follow.
  */
-const RenameBody = z
+const PatchBody = z
     .object({
     title: z
         .string()
@@ -151,12 +167,19 @@ const RenameBody = z
         .trim()
         .refine((t) => t.length > 0, "title must not be empty")
         .refine((t) => Array.from(t).length <= CONVERSATION_TITLE_MAX_CHARS, `title must be at most ${CONVERSATION_TITLE_MAX_CHARS} characters`)
-        .refine((t) => !CONTROL_OR_HIDDEN_RE.test(t), "title must not contain control or format characters"),
+        .refine((t) => !CONTROL_OR_HIDDEN_RE.test(t), "title must not contain control or format characters")
+        .optional(),
+    /** true archives (hidden from the default lists), false unarchives. */
+    archived: z.boolean().optional(),
 })
-    .strict();
+    .strict()
+    .refine((b) => b.title !== undefined || b.archived !== undefined, "title or archived is required");
+const IdParams = z.object({ id: z.string().min(1).max(100) });
 class ConversationCreateBodyDto extends createZodDto(CreateBody, "ConversationCreateBody") {
 }
-class ConversationRenameBodyDto extends createZodDto(RenameBody, "ConversationRenameBody") {
+class ConversationPatchBodyDto extends createZodDto(PatchBody, "ConversationPatchBody") {
+}
+class ConversationIdParamsDto extends createZodDto(IdParams, "ConversationIdParams") {
 }
 class ConversationListQueryDto extends createZodDto(ListQuery, "ConversationListQuery") {
 }
@@ -190,25 +213,30 @@ let ConversationsController = class ConversationsController {
     conversations;
     outputs;
     artifacts;
-    sandboxStatus;
+    environmentStatus;
     toolInfo;
     queue;
     files;
-    constructor(conversations, outputs, artifacts, sandboxStatus, toolInfo, queue, files) {
+    constructor(conversations, outputs, artifacts, environmentStatus, toolInfo, queue, files) {
         this.conversations = conversations;
         this.outputs = outputs;
         this.artifacts = artifacts;
-        this.sandboxStatus = sandboxStatus;
+        this.environmentStatus = environmentStatus;
         this.toolInfo = toolInfo;
         this.queue = queue;
         this.files = files;
     }
-    /** 201 when created; 200 when `message.clientMessageId` repeats an earlier first send. */
+    /**
+     * 201 when created; 200 when `message.clientMessageId` repeats an earlier first send. With a
+     * message the answer has `event` (the `user_message`) and `events`: every event the first send
+     * wrote, in seq order from seq 1 (a `model_switched` first when it switched).
+     */
     async create(principal, org, body, reply) {
         const p = requireUser(principal);
+        const pick = body.environmentId === undefined ? {} : { environmentId: body.environmentId };
         if (body.message === undefined) {
             return {
-                conversation: await this.conversations.create(org.orgId, p.account.id, body.agentId),
+                conversation: await this.conversations.create(org.orgId, p.account.id, body.agentId, pick),
             };
         }
         const m = body.message;
@@ -220,17 +248,34 @@ let ConversationsController = class ConversationsController {
             ...(m.model !== undefined && { model: m.model }),
             ...(m.effort !== undefined && { effort: m.effort }),
             ...(m.skill !== undefined && { skill: m.skill }),
-        });
+        }, pick);
         reply.status(out.created ? 201 : 200);
-        return { conversation: out.conversation, event: out.event };
+        return { conversation: out.conversation, event: out.event, events: out.events };
     }
-    /** Rename (owner only): `titleSource` becomes `manual` and the title is never regenerated. */
-    async rename(principal, org, id, body) {
+    /**
+     * Rename and / or archive (owner only). A rename makes `titleSource` `manual`, so the title is
+     * never regenerated; `archived` archives or unarchives. Returns the final view.
+     */
+    async patch(principal, org, id, body) {
         const p = requireUser(principal);
+        const renamed = body.title === undefined
+            ? undefined
+            : await this.conversations.rename(org.orgId, id, p.account.id, body.title);
+        if (body.archived === undefined) {
+            // The refine guarantees a title when there is no `archived`
+            return {
+                conversation: renamed ?? (await this.conversations.get(org.orgId, id, p.account.id)),
+            };
+        }
         return {
-            conversation: await this.conversations.rename(org.orgId, id, p.account.id, body.title),
+            conversation: await this.conversations.setArchived(org.orgId, id, p.account.id, body.archived),
         };
     }
+    /** Soft delete (owner only): stops an active run and hides the conversation everywhere. */
+    async remove(principal, org, { id }) {
+        const p = requireUser(principal);
+        await this.conversations.remove(org.orgId, id, p.account.id);
+    }
     /** 我的会话，最近更新的在前：`next` 为下一页游标（作为 `after` 传回），没有更多时为 null。 */
     async list(principal, org, q) {
         const p = requireUser(principal);
@@ -238,6 +283,9 @@ let ConversationsController = class ConversationsController {
             limit: q.limit + 1,
             ...(q.after !== undefined && { after: q.after }),
             ...(q.agentId !== undefined && { agentId: q.agentId }),
+            ...(q.q !== undefined && { q: q.q }),
+            ...(q.state !== undefined && { state: q.state }),
+            ...(q.archived !== undefined && { archived: true }),
         });
         const conversations = rows.slice(0, q.limit);
         const next = rows.length > q.limit ? (conversations.at(-1)?.id ?? null) : null;
@@ -254,17 +302,28 @@ let ConversationsController = class ConversationsController {
             perGroup: q.perGroup,
             limit: q.limit,
             ...(q.after !== undefined && { after: q.after }),
+            ...(q.q !== undefined && { q: q.q }),
+            ...(q.state !== undefined && { state: q.state }),
+            ...(q.archived !== undefined && { archived: true }),
         });
     }
     async get(principal, org, id) {
         const p = requireUser(principal);
         return { conversation: await this.conversations.get(org.orgId, id, p.account.id) };
     }
-    /** `after` 之后的事件（seq 升序，最多 `limit` 条）；客户端以最后一条的 seq 作为下一次的 `after`。 */
+    /**
+     * Events in ascending seq. `after`: those after it (at most `limit`; the client passes the last
+     * seq back as the next `after`). `before` (a seq, or `end` for the log's last page): the
+     * turn-aligned page before it, `{ events, turnsBefore }` (history paging spec §2).
+     */
     async events(principal, org, id, q) {
         const p = requireUser(principal);
+        if (q.before !== undefined) {
+            const before = q.before === "end" ? null : q.before;
+            return this.conversations.listEventsBefore(org.orgId, id, p.account.id, before, q.limit);
+        }
         return {
-            events: await this.conversations.listEvents(org.orgId, id, p.account.id, q.after, q.limit),
+            events: await this.conversations.listEvents(org.orgId, id, p.account.id, q.after ?? 0, q.limit),
         };
     }
     /**
@@ -279,6 +338,15 @@ let ConversationsController = class ConversationsController {
             ...(q.after !== undefined && { after: q.after }),
         });
     }
+    /**
+     * The agent tree of a root conversation (agent map spec §8, §9.2): `{ root }`, each node with its
+     * status, model, time, tokens, tool calls and children. Owner only; a sub-agent's id is
+     * `conversation.not_found`.
+     */
+    async agentTree(principal, org, { id }) {
+        const p = requireUser(principal);
+        return this.conversations.agentTree(org.orgId, id, p.account.id);
+    }
     /**
      * The conversation's token usage, its sub-agents' included (sub-agents spec §8.3):
      * `{ usage: { inputTokens, outputTokens, cacheReadTokens, cacheWriteTokens } }`. Owner only.
@@ -347,13 +415,13 @@ let ConversationsController = class ConversationsController {
         await reply.send(c.body);
     }
     /**
-     * 对话沙箱的状态。响应体**不套外层键**，直接是 `{ status: "running" | "suspended", lastUsedAt }`
-     * （不同于 `{ preview }`、`{ conversation }` 等；网页 `getSandboxStatus` 按此解析）；
-     * 没有可用的沙箱（未创建、已销毁）→ 404 `sandbox.not_found`。可见性与会话流相同。
+     * The environment the conversation works in (a sub-agent: its root's), as its owner sees it,
+     * with its instance state; `null` while unbound, or when the environment was deleted. Same
+     * visibility as the event stream.
      */
-    async sandbox(principal, org, id) {
+    async environment(principal, org, id) {
         const p = requireUser(principal);
-        return this.sandboxStatus.get(org.orgId, id, p.account.id);
+        return { environment: await this.environmentStatus.get(org.orgId, id, p.account.id) };
     }
     /**
      * Display metadata (title, kind, key arguments, source) of the tools a conversation's calls name,
@@ -387,22 +455,23 @@ let ConversationsController = class ConversationsController {
         return this.queue.list(org.orgId, id, p.account.id);
     }
     /**
-     * Queues a message (201). The same `clientMessageId` again: 200 with the queued item, or with
-     * `item: null` and the sent `event` once it went out. An idle conversation sends it at once.
+     * Deprecated: behaves as `POST …/messages` (202 `{ event }`): an interjection while a run is
+     * active, a new run otherwise; nothing is queued any more. Kept for older clients for one release;
+     * the leftover-item routes below keep working until the queue table is dropped (contract step).
      */
-    async enqueue(principal, org, id, body, reply) {
+    async enqueue(principal, org, id, body) {
         const p = requireUser(principal);
-        const out = await this.queue.add(org.orgId, id, p.account.id, {
-            text: body.text,
-            clientMessageId: body.clientMessageId,
-            ...(body.attachments !== undefined && { attachments: body.attachments }),
-            ...(body.files !== undefined && { files: body.files }),
-            ...(body.model !== undefined && { model: body.model }),
-            ...(body.effort !== undefined && { effort: body.effort }),
-            ...(body.skill !== undefined && { skill: body.skill }),
-        });
-        reply.status(out.created ? 201 : 200);
-        return { item: out.item, ...(out.event !== undefined && { event: out.event }) };
+        return {
+            event: await this.conversations.postUserMessage(org.orgId, id, p.account.id, {
+                text: body.text,
+                clientMessageId: body.clientMessageId,
+                ...(body.attachments !== undefined && { attachments: body.attachments }),
+                ...(body.files !== undefined && { files: body.files }),
+                ...(body.model !== undefined && { model: body.model }),
+                ...(body.effort !== undefined && { effort: body.effort }),
+                ...(body.skill !== undefined && { skill: body.skill }),
+            }),
+        };
     }
     /** "Continue sending" after a pause (202). Declared before `:itemId` routes. */
     async resumeQueue(principal, org, id) {
@@ -423,7 +492,13 @@ let ConversationsController = class ConversationsController {
         const p = requireUser(principal);
         return { event: await this.queue.sendNow(org.orgId, id, p.account.id, itemId) };
     }
-    /** 中止当前运行（会话所有者）：202 `{ runId }`；没有活跃运行 → 409 `run.not_active`。 */
+    /**
+     * Stops the current run (the conversation's owner): 202 `{ runId }`; nothing active → 409
+     * `run.not_active`. On a root conversation `runId` is the stopped run, and its background
+     * sub-agents keep working. On a sub-agent's conversation (the root's owner, at any depth) the
+     * sub-agent stops with every sub-agent below it, and `runId` is the sub-agent's latest run,
+     * which may already be finished when only its descendants were working (agent map spec §6).
+     */
     async abort(principal, org, id) {
         const p = requireUser(principal);
         return { runId: await this.conversations.abort(org.orgId, id, p.account.id) };
@@ -443,8 +518,16 @@ __decorate([
     __param(0, CurrentPrincipal()),
     __param(1, CurrentOrg()),
     __param(2, Param("id")),
-    __param(3, ZBody(ConversationRenameBodyDto))
-], ConversationsController.prototype, "rename", null);
+    __param(3, ZBody(ConversationPatchBodyDto))
+], ConversationsController.prototype, "patch", null);
+__decorate([
+    Delete(":id"),
+    HttpCode(204),
+    OrgAction("agents.use"),
+    __param(0, CurrentPrincipal()),
+    __param(1, CurrentOrg()),
+    __param(2, ZParam(ConversationIdParamsDto))
+], ConversationsController.prototype, "remove", null);
 __decorate([
     Get(),
     OrgAction("agents.use"),
@@ -483,6 +566,14 @@ __decorate([
     __param(2, Param("id")),
     __param(3, ZQuery(ConversationSubagentsQueryDto))
 ], ConversationsController.prototype, "subagents", null);
+__decorate([
+    Get(":id/agent-tree"),
+    Header("cache-control", "private, no-store"),
+    OrgAction("agents.use"),
+    __param(0, CurrentPrincipal()),
+    __param(1, CurrentOrg()),
+    __param(2, ZParam(ConversationIdParamsDto))
+], ConversationsController.prototype, "agentTree", null);
 __decorate([
     Get(":id/usage"),
     Header("cache-control", "private, no-store"),
@@ -539,13 +630,13 @@ __decorate([
     __param(5, Res())
 ], ConversationsController.prototype, "fileContent", null);
 __decorate([
-    Get(":id/sandbox"),
+    Get(":id/environment"),
     Header("cache-control", "private, no-store"),
     OrgAction("agents.use"),
     __param(0, CurrentPrincipal()),
     __param(1, CurrentOrg()),
     __param(2, Param("id"))
-], ConversationsController.prototype, "sandbox", null);
+], ConversationsController.prototype, "environment", null);
 __decorate([
     Get(":id/tools"),
     Header("cache-control", "private, no-store"),
@@ -574,12 +665,12 @@ __decorate([
 ], ConversationsController.prototype, "listQueue", null);
 __decorate([
     Post(":id/queue"),
+    HttpCode(202),
     OrgAction("agents.use"),
     __param(0, CurrentPrincipal()),
     __param(1, CurrentOrg()),
     __param(2, Param("id")),
-    __param(3, ZBody(ConversationQueueBodyDto)),
-    __param(4, Res({ passthrough: true }))
+    __param(3, ZBody(ConversationQueueBodyDto))
 ], ConversationsController.prototype, "enqueue", null);
 __decorate([
     Post(":id/queue/resume"),
@@ -629,7 +720,7 @@ ConversationsController = __decorate([
     __param(0, Inject(ConversationsService)),
     __param(1, Inject(ConversationOutputs)),
     __param(2, Inject(ConversationArtifacts)),
-    __param(3, Inject(ConversationSandboxStatus)),
+    __param(3, Inject(ConversationEnvironmentStatus)),
     __param(4, Inject(ConversationToolInfo)),
     __param(5, Inject(ConversationQueue)),
     __param(6, Inject(ConversationFiles))

package/dist/conversations/conversations.module.d.ts

@@ -1,7 +1,7 @@
 /**
  * Conversations: the one {@link ConversationsService} (messages, model switches, skill
  * invocations, sub-agent views, abort), the queue, the file / artifact / output reads and the
- * sandbox status. The event log, the access check and the attachments are their own modules (the
+ * conversation's environment. The event log, the access check and the attachments are their own modules (the
  * skills and tools use them too) and are re-exported here.
  */
 export declare class ConversationsModule {

package/dist/conversations/conversations.module.js

@@ -6,9 +6,10 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
 };
 import { Module } from "@nestjs/common";
 import { AgentLookupModule } from "../agents/agent-lookup.js";
+import { BackgroundModule } from "../background/background.module.js";
+import { EnvironmentsModule } from "../environments/environments.module.js";
 import { ProvidersModule } from "../runtime/providers.js";
 import { RuntimeModule } from "../runtime/runtime.module.js";
-import { SandboxModule } from "../sandbox/sandbox.module.js";
 import { SkillsModule } from "../skills/skills.module.js";
 import { StorageModule } from "../storage/storage.module.js";
 import { ToolsModule } from "../tools/tools.module.js";
@@ -16,15 +17,15 @@ import { ConversationAccessModule } from "./access.js";
 import { ConversationArtifacts } from "./artifacts.js";
 import { AttachmentsModule } from "./attachments.module.js";
 import { ConversationsService } from "./conversations.service.js";
+import { ConversationEnvironmentStatus } from "./environment-status.js";
 import { EventLogModule } from "./event-log.js";
 import { ConversationFiles } from "./files.js";
 import { ConversationOutputs } from "./outputs-read.js";
 import { ConversationQueue } from "./queue.service.js";
-import { ConversationSandboxStatus } from "./sandbox-status.js";
 /**
  * Conversations: the one {@link ConversationsService} (messages, model switches, skill
  * invocations, sub-agent views, abort), the queue, the file / artifact / output reads and the
- * sandbox status. The event log, the access check and the attachments are their own modules (the
+ * conversation's environment. The event log, the access check and the attachments are their own modules (the
  * skills and tools use them too) and are re-exported here.
  */
 let ConversationsModule = class ConversationsModule {
@@ -42,8 +43,10 @@ ConversationsModule = __decorate([
             // the run control (start a run after a message, stop runs) and the model provider registry
             RuntimeModule,
             ProvidersModule,
-            // the sandbox status
-            SandboxModule,
+            // the environment a conversation is bound to, and its view
+            EnvironmentsModule,
+            // the stop of a deleted conversation's background tasks
+            BackgroundModule,
         ],
         providers: [
             ConversationsService,
@@ -51,7 +54,7 @@ ConversationsModule = __decorate([
             ConversationOutputs,
             ConversationArtifacts,
             ConversationFiles,
-            ConversationSandboxStatus,
+            ConversationEnvironmentStatus,
         ],
         exports: [
             EventLogModule,
@@ -62,7 +65,7 @@ ConversationsModule = __decorate([
             ConversationOutputs,
             ConversationArtifacts,
             ConversationFiles,
-            ConversationSandboxStatus,
+            ConversationEnvironmentStatus,
         ],
     })
 ], ConversationsModule);