@capybara-hq/kernel 0.0.0-stage → 0.1.0-rc.1

package/dist/conversations/conversations.controller.d.ts

@@ -0,0 +1,288 @@
+import type { FastifyReply } from "fastify";
+import { z } from "zod";
+import { type Principal } from "../identity/principal.js";
+import { type OrgContext } from "../orgs/org.guard.js";
+import { type ConversationToolInfo, type ToolInfo } from "../tools/info.js";
+import { type ArtifactPreview, type ConversationArtifacts } from "./artifacts.js";
+import { type ConversationGroup, type ConversationsService, type ConversationView, type SubagentView, type UsageTotals } from "./conversations.service.js";
+import type { ConversationEvent } from "./events.js";
+import { type ConversationFiles, type FileOutput } from "./files.js";
+import { type ConversationOutputs, type OutputPage } from "./outputs-read.js";
+import type { ConversationQueue, QueueItem, QueuePauseReason } from "./queue.js";
+import type { ConversationSandboxStatus, SandboxStatusView } from "./sandbox-status.js";
+declare const ListQuery: z.ZodObject<{
+    after: z.ZodOptional<z.ZodString>;
+    limit: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+    agentId: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+declare const GroupsQuery: z.ZodObject<{
+    perGroup: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+    limit: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+    after: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+declare const SubagentsQuery: z.ZodObject<{
+    after: z.ZodOptional<z.ZodString>;
+    limit: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+}, z.core.$strip>;
+declare const EventsQuery: z.ZodObject<{
+    after: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+    limit: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+}, z.core.$strip>;
+/** `?keys=a,b`: 1–100 comma-separated tool keys of 1–200 characters each. */
+declare const ToolsQuery: z.ZodObject<{
+    keys: z.ZodPipe<z.ZodPipe<z.ZodString, z.ZodTransform<string[], string>>, z.ZodArray<z.ZodString>>;
+}, z.core.$strip>;
+declare const OutputQuery: z.ZodObject<{
+    offset: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+    limit: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+}, z.core.$strip>;
+declare const FilesQuery: z.ZodObject<{
+    after: z.ZodOptional<z.ZodString>;
+    limit: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+}, z.core.$strip>;
+declare const FileContentQuery: z.ZodObject<{
+    limit: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+}, z.core.$strip>;
+/** `inline=1`：要求以 inline 打开（只对位图生效，见 ConversationArtifacts）。 */
+declare const DownloadQuery: z.ZodObject<{
+    inline: z.ZodOptional<z.ZodEnum<{
+        0: "0";
+        1: "1";
+    }>>;
+}, z.core.$strip>;
+declare const MessageBody: z.ZodObject<{
+    text: z.ZodString;
+    clientMessageId: z.ZodOptional<z.ZodString>;
+    attachments: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        connectorId: z.ZodUUID;
+        uri: z.ZodString;
+    }, z.core.$strict>>>;
+    files: z.ZodOptional<z.ZodArray<z.ZodUUID>>;
+    model: z.ZodOptional<z.ZodObject<{
+        provider: z.ZodString;
+        model: z.ZodString;
+    }, z.core.$strict>>;
+    effort: z.ZodOptional<z.ZodEnum<{
+        high: "high";
+        low: "low";
+        max: "max";
+        medium: "medium";
+        xhigh: "xhigh";
+    }>>;
+    retryOf: z.ZodOptional<z.ZodNumber>;
+    skill: z.ZodOptional<z.ZodObject<{
+        name: z.ZodString;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+/**
+ * `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).
+ */
+declare const CreateBody: z.ZodObject<{
+    agentId: z.ZodString;
+    message: z.ZodOptional<z.ZodObject<{
+        text: z.ZodString;
+        attachments: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            connectorId: z.ZodUUID;
+            uri: z.ZodString;
+        }, z.core.$strict>>>;
+        files: z.ZodOptional<z.ZodArray<z.ZodUUID>>;
+        model: z.ZodOptional<z.ZodObject<{
+            provider: z.ZodString;
+            model: z.ZodString;
+        }, z.core.$strict>>;
+        effort: z.ZodOptional<z.ZodEnum<{
+            high: "high";
+            low: "low";
+            max: "max";
+            medium: "medium";
+            xhigh: "xhigh";
+        }>>;
+        skill: z.ZodOptional<z.ZodObject<{
+            name: z.ZodString;
+        }, z.core.$strict>>;
+        clientMessageId: z.ZodString;
+    }, z.core.$strict>>;
+}, z.core.$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).
+ */
+declare const QueueBody: z.ZodObject<{
+    text: z.ZodString;
+    attachments: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        connectorId: z.ZodUUID;
+        uri: z.ZodString;
+    }, z.core.$strict>>>;
+    files: z.ZodOptional<z.ZodArray<z.ZodUUID>>;
+    model: z.ZodOptional<z.ZodObject<{
+        provider: z.ZodString;
+        model: z.ZodString;
+    }, z.core.$strict>>;
+    effort: z.ZodOptional<z.ZodEnum<{
+        high: "high";
+        low: "low";
+        max: "max";
+        medium: "medium";
+        xhigh: "xhigh";
+    }>>;
+    skill: z.ZodOptional<z.ZodObject<{
+        name: z.ZodString;
+    }, z.core.$strict>>;
+    clientMessageId: z.ZodString;
+}, z.core.$strict>;
+/** `PATCH …/queue/:itemId`: only the text changes (the text rule is checked against the item). */
+declare const QueueEditBody: z.ZodObject<{
+    text: z.ZodString;
+}, z.core.$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.
+ */
+declare const RenameBody: z.ZodObject<{
+    title: z.ZodString;
+}, z.core.$strict>;
+/**
+ * 会话（`/api/v1/orgs/:orgId/conversations`）：`agents.use`（访客以上），只接受人类用户；
+ * 服务令牌 → 403 `forbidden`。只有会话所有者可见，其他人一律 `conversation.not_found`。
+ */
+export declare class ConversationsController {
+    private readonly conversations;
+    private readonly outputs;
+    private readonly artifacts;
+    private readonly sandboxStatus;
+    private readonly toolInfo;
+    private readonly queue;
+    private readonly files;
+    constructor(conversations: ConversationsService, outputs: ConversationOutputs, artifacts: ConversationArtifacts, sandboxStatus: ConversationSandboxStatus, toolInfo: ConversationToolInfo, queue: ConversationQueue, files: ConversationFiles);
+    /** 201 when created; 200 when `message.clientMessageId` repeats an earlier first send. */
+    create(principal: Principal, org: OrgContext, body: z.infer<typeof CreateBody>, reply: FastifyReply): Promise<{
+        conversation: ConversationView;
+        event?: ConversationEvent;
+    }>;
+    /** Rename (owner only): `titleSource` becomes `manual` and the title is never regenerated. */
+    rename(principal: Principal, org: OrgContext, id: string, body: z.infer<typeof RenameBody>): Promise<{
+        conversation: ConversationView;
+    }>;
+    /** 我的会话，最近更新的在前：`next` 为下一页游标（作为 `after` 传回），没有更多时为 null。 */
+    list(principal: Principal, org: OrgContext, q: z.infer<typeof ListQuery>): Promise<{
+        conversations: ConversationView[];
+        next: string | null;
+    }>;
+    /**
+     * My conversations grouped by agent, for the sidebar: groups by latest activity, `perGroup`
+     * newest conversations each with `more`; `next` is the last group's agent id (passed back as
+     * `after`), null when there are no more groups. Declared before `:id` so it is not captured.
+     */
+    groups(principal: Principal, org: OrgContext, q: z.infer<typeof GroupsQuery>): Promise<{
+        groups: ConversationGroup[];
+        next: string | null;
+    }>;
+    get(principal: Principal, org: OrgContext, id: string): Promise<{
+        conversation: ConversationView;
+    }>;
+    /** `after` 之后的事件（seq 升序，最多 `limit` 条）；客户端以最后一条的 seq 作为下一次的 `after`。 */
+    events(principal: Principal, org: OrgContext, id: string, q: z.infer<typeof EventsQuery>): Promise<{
+        events: ConversationEvent[];
+    }>;
+    /**
+     * The conversation's sub-agents, newest first (sub-agents spec §14.3): `{ subagents, next }`,
+     * `next` the cursor passed back as `after` (null when there are no more). Owner only, as the
+     * conversation itself (`conversation.not_found`).
+     */
+    subagents(principal: Principal, org: OrgContext, id: string, q: z.infer<typeof SubagentsQuery>): Promise<{
+        subagents: SubagentView[];
+        next: string | null;
+    }>;
+    /**
+     * The conversation's token usage, its sub-agents' included (sub-agents spec §8.3):
+     * `{ usage: { inputTokens, outputTokens, cacheReadTokens, cacheWriteTokens } }`. Owner only.
+     */
+    usage(principal: Principal, org: OrgContext, id: string): Promise<{
+        usage: UsageTotals;
+    }>;
+    /**
+     * 工具输出存档（内核截断并转存的大结果）的全文，按字符分页（`offset` / `limit`，`next` 为下一页起点）。
+     * 会话可见性与会话流相同，不可见 → `conversation.not_found`；存档不属于该会话或已过期 → `conversation.output_not_found`。
+     */
+    output(principal: Principal, org: OrgContext, id: string, outputId: string, q: z.infer<typeof OutputQuery>): Promise<{
+        output: OutputPage;
+    }>;
+    /**
+     * 下载 agent 交付的产物（`artifact_created`）：302 到预签名地址（一律 `attachment`，带文件名）。
+     * 会话可见性与会话流相同，不可见 → `conversation.not_found`；不是该会话的产物 → `conversation.artifact_not_found`。
+     */
+    downloadArtifact(principal: Principal, org: OrgContext, id: string, artifactId: string, q: z.infer<typeof DownloadQuery>, reply: FastifyReply): Promise<void>;
+    /**
+     * 文本产物的开头若干行（`{ preview: { text, truncated } }`，网页按纯文本显示）。
+     * 不是文本类、或开头有 NUL 字节 → `conversation.artifact_not_previewable`；可见性与下载相同。
+     */
+    previewArtifact(principal: Principal, org: OrgContext, id: string, artifactId: string): Promise<{
+        preview: ArtifactPreview;
+    }>;
+    /**
+     * The conversation's file outputs, newest first, grouped by source path into versions (UI
+     * refresh B). `next` is the last file's id (passed back as `after`), null at the end.
+     */
+    listFiles(principal: Principal, org: OrgContext, id: string, q: z.infer<typeof FilesQuery>): Promise<{
+        files: FileOutput[];
+        next: string | null;
+    }>;
+    /**
+     * The first `limit` bytes (≤ 1 MiB) of a text file version, always as `text/plain; charset=utf-8`
+     * with the stored type in `X-Content-Original-Type` (sandboxed, never sniffed);
+     * `X-Content-Truncated: true` when cut. Not text → 400 `conversation.artifact_not_previewable`;
+     * object gone → 410 `conversation.artifact_removed`.
+     */
+    fileContent(principal: Principal, org: OrgContext, id: string, fileId: string, q: z.infer<typeof FileContentQuery>, reply: FastifyReply): Promise<void>;
+    /**
+     * 对话沙箱的状态。响应体**不套外层键**，直接是 `{ status: "running" | "suspended", lastUsedAt }`
+     * （不同于 `{ preview }`、`{ conversation }` 等；网页 `getSandboxStatus` 按此解析）；
+     * 没有可用的沙箱（未创建、已销毁）→ 404 `sandbox.not_found`。可见性与会话流相同。
+     */
+    sandbox(principal: Principal, org: OrgContext, id: string): Promise<SandboxStatusView>;
+    /**
+     * Display metadata (title, kind, key arguments, source) of the tools a conversation's calls name,
+     * for the tool rows (UI refresh B). Same visibility as the event stream; never model-visible.
+     */
+    tools(principal: Principal, org: OrgContext, id: string, q: z.infer<typeof ToolsQuery>): Promise<{
+        tools: ToolInfo[];
+    }>;
+    postMessage(principal: Principal, org: OrgContext, id: string, body: z.infer<typeof MessageBody>): Promise<{
+        event: ConversationEvent;
+    }>;
+    /**
+     * Queued messages (owner only): `paused` after a run failed or was stopped with items queued, or
+     * the head item could not be sent; `pauseReason` says which (absent when not recorded).
+     */
+    listQueue(principal: Principal, org: OrgContext, id: string): Promise<{
+        items: QueueItem[];
+        paused: boolean;
+        pauseReason?: QueuePauseReason;
+    }>;
+    /**
+     * 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.
+     */
+    enqueue(principal: Principal, org: OrgContext, id: string, body: z.infer<typeof QueueBody>, reply: FastifyReply): Promise<{
+        item: QueueItem | null;
+        event?: ConversationEvent;
+    }>;
+    /** "Continue sending" after a pause (202). Declared before `:itemId` routes. */
+    resumeQueue(principal: Principal, org: OrgContext, id: string): Promise<Record<string, never>>;
+    editQueued(principal: Principal, org: OrgContext, id: string, itemId: string, body: z.infer<typeof QueueEditBody>): Promise<{
+        item: QueueItem;
+    }>;
+    deleteQueued(principal: Principal, org: OrgContext, id: string, itemId: string): Promise<void>;
+    /** Sends a queued message now, as an interjection when a run is active (202 `{ event }`). */
+    sendQueued(principal: Principal, org: OrgContext, id: string, itemId: string): Promise<{
+        event: ConversationEvent;
+    }>;
+    /** 中止当前运行（会话所有者）：202 `{ runId }`；没有活跃运行 → 409 `run.not_active`。 */
+    abort(principal: Principal, org: OrgContext, id: string): Promise<{
+        runId: string;
+    }>;
+}
+export {};