@agent-phonon/protocol 0.2.0

package/dist/schemas/session.d.ts

@@ -0,0 +1,730 @@
+import { z } from "zod";
+/**
+ * L1 Session 协议原语（design §4）。
+ *
+ * 铁律：session 必须绑定 agent（D15）。每条 session 天生属于某个 agent + model，
+ * 这是 session 的一等身份，不是可选配置。发任务 = 在 session 里对话。
+ */
+/** session 状态。 */
+/**
+ * session 状态（design D19）。
+ * - idle       : 活着、空闲、就绪可接 send（create 后初始态；turn 结束/interrupt 后回到这）
+ * - running    : agent 正在执行一个 turn
+ * - paused     : 挂起（重启后从 DB 恢复、原生 ref 尚未 re-attach；或被显式暂停），需恢复才能用
+ * - terminated : 已结束销毁
+ */
+export declare const SessionStatus: z.ZodEnum<["idle", "running", "paused", "terminated"]>;
+export type SessionStatus = z.infer<typeof SessionStatus>;
+/**
+ * 上下文条目 —— 用于 initialContext / inject。
+ * 设计成「角色 + 文本」的最小通用形态，具体 adapter 自行翻译成原生格式。
+ */
+export declare const ContextItem: z.ZodObject<{
+    role: z.ZodEnum<["system", "user", "assistant"]>;
+    content: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    role: "system" | "user" | "assistant";
+    content: string;
+}, {
+    role: "system" | "user" | "assistant";
+    content: string;
+}>;
+export type ContextItem = z.infer<typeof ContextItem>;
+export declare const SessionCreateParams: z.ZodObject<{
+    /** 可选：幂等键（P0-3，断线重发去重）。 */
+    clientRequestId: z.ZodOptional<z.ZodString>;
+    /** 必填：绑定的项目（所有 session 必须有项目目录，D23）。 */
+    project: z.ZodBranded<z.ZodString, "ProjectId">;
+    /** 可选：跑在哪个 worktree（缺省用项目主工作区，D25）。 */
+    worktreeId: z.ZodOptional<z.ZodString>;
+    /** 必填：绑定的 agent（来自 discovery 的 agentId）。 */
+    agent: z.ZodBranded<z.ZodString, "AgentId">;
+    /** 必填：绑定的模型（必须在该 agent 的可用模型列表内）。 */
+    model: z.ZodString;
+    /** 透传给 adapter 的 agent 私有配置（cwd、工具白名单、thinking 等）。 */
+    agentConfig: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    /** 初始上下文设置（system prompt / 预置对话）。 */
+    initialContext: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        role: z.ZodEnum<["system", "user", "assistant"]>;
+        content: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        role: "system" | "user" | "assistant";
+        content: string;
+    }, {
+        role: "system" | "user" | "assistant";
+        content: string;
+    }>, "many">>;
+    /** 默认返回详细度，send 可覆盖。默认 messages。 */
+    verbosity: z.ZodDefault<z.ZodEnum<["final", "messages", "tools", "trace"]>>;
+    /** 可选：调用方自带的标签，便于服务端侧对账（phonon 原样回显）。 */
+    clientTag: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    agent: string & z.BRAND<"AgentId">;
+    project: string & z.BRAND<"ProjectId">;
+    model: string;
+    verbosity: "final" | "messages" | "tools" | "trace";
+    clientRequestId?: string | undefined;
+    worktreeId?: string | undefined;
+    agentConfig?: Record<string, unknown> | undefined;
+    initialContext?: {
+        role: "system" | "user" | "assistant";
+        content: string;
+    }[] | undefined;
+    clientTag?: string | undefined;
+}, {
+    agent: string;
+    project: string;
+    model: string;
+    clientRequestId?: string | undefined;
+    worktreeId?: string | undefined;
+    agentConfig?: Record<string, unknown> | undefined;
+    initialContext?: {
+        role: "system" | "user" | "assistant";
+        content: string;
+    }[] | undefined;
+    verbosity?: "final" | "messages" | "tools" | "trace" | undefined;
+    clientTag?: string | undefined;
+}>;
+export type SessionCreateParams = z.infer<typeof SessionCreateParams>;
+export declare const SessionCreateResult: z.ZodObject<{
+    sessionId: z.ZodBranded<z.ZodString, "SessionId">;
+    /** 回显绑定身份，方便调用方确认。 */
+    project: z.ZodBranded<z.ZodString, "ProjectId">;
+    agent: z.ZodBranded<z.ZodString, "AgentId">;
+    model: z.ZodString;
+    status: z.ZodEnum<["idle", "running", "paused", "terminated"]>;
+    createdAt: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    status: "idle" | "running" | "paused" | "terminated";
+    sessionId: string & z.BRAND<"SessionId">;
+    agent: string & z.BRAND<"AgentId">;
+    project: string & z.BRAND<"ProjectId">;
+    model: string;
+    createdAt: string;
+}, {
+    status: "idle" | "running" | "paused" | "terminated";
+    sessionId: string;
+    agent: string;
+    project: string;
+    model: string;
+    createdAt: string;
+}>;
+export type SessionCreateResult = z.infer<typeof SessionCreateResult>;
+/**
+ * 忙碌处理模式（D18）—— 新消息进来时上一轮还没结束怎么办：
+ * - queue    ：等待，上一轮结束后自动发送积压消息（默认，最安全）。
+ * - interrupt：中断当前 turn（session 存活），再发新消息；需 capability.interrupt。
+ * - inject   ：不中断，在下一次 tool call 边界插入输入让 agent 接着处理；
+ *              需 capability.injectMidTurn（agent 原生接口或通过 hook 实现）。
+ * 不论哪种模式，**消息不丢**：要么按序送达、要么明确拒绝并告知原因。
+ */
+export declare const WhenBusy: z.ZodEnum<["queue", "interrupt", "inject"]>;
+export type WhenBusy = z.infer<typeof WhenBusy>;
+export declare const SessionSendParams: z.ZodObject<{
+    sessionId: z.ZodBranded<z.ZodString, "SessionId">;
+    /** 用户输入 / 任务内容。 */
+    input: z.ZodString;
+    /**
+     * 可选：幂等键（P0-3）。服务端断线重发同一 send 时带相同值，
+     * phonon 去重，避免 agent 收两遍同样消息；重复回 `errDuplicateRequest` 或原 turnId。
+     */
+    clientRequestId: z.ZodOptional<z.ZodString>;
+    /**
+     * 可选：本轮指定要用的 skill（D26）。每项可是简单名字（string），
+     * 或结构体 {name,version?,scope?,force?}（P2-12，消除同名 global/project 歧义）。
+     * phonon 保证：(1) skill 在 agent 能访问到的位置；(2) 上下文注入强制加载指令。
+     * 优先级：send 指定 > project skill > global skill。
+     */
+    skills: z.ZodOptional<z.ZodArray<z.ZodUnion<[z.ZodString, z.ZodObject<{
+        name: z.ZodString;
+        version: z.ZodOptional<z.ZodString>;
+        scope: z.ZodOptional<z.ZodEnum<["global", "project"]>>;
+        force: z.ZodOptional<z.ZodBoolean>;
+    }, "strip", z.ZodTypeAny, {
+        name: string;
+        version?: string | undefined;
+        scope?: "project" | "global" | undefined;
+        force?: boolean | undefined;
+    }, {
+        name: string;
+        version?: string | undefined;
+        scope?: "project" | "global" | undefined;
+        force?: boolean | undefined;
+    }>]>, "many">>;
+    /** 可选：覆盖本轮详细度。 */
+    verbosity: z.ZodOptional<z.ZodEnum<["final", "messages", "tools", "trace"]>>;
+    /**
+     * 忙碌时的处理模式（D18）。缺省 queue。
+     * 若选的模式该 agent 不支持（看 capability）且未设 fallback → errCapabilityUnsupported。
+     */
+    whenBusy: z.ZodDefault<z.ZodEnum<["queue", "interrupt", "inject"]>>;
+    /**
+     * 可选：降级模式（P1-11）。当 whenBusy 该 agent 不支持时，不报错而自动降级为它，
+     * 保证自动化编排连贯。如 whenBusy="inject", fallback="queue"。
+     */
+    fallback: z.ZodOptional<z.ZodEnum<["queue", "interrupt", "inject"]>>;
+    /**
+     * 可选：本轮关联 id。phonon 会把该轮所有 stream.event 标上同一 turnId，
+     * 调用方据此聚合流式输出。缺省由 phonon 生成并在 ack 中返回。
+     */
+    turnId: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    sessionId: string & z.BRAND<"SessionId">;
+    input: string;
+    whenBusy: "interrupt" | "queue" | "inject";
+    clientRequestId?: string | undefined;
+    verbosity?: "final" | "messages" | "tools" | "trace" | undefined;
+    skills?: (string | {
+        name: string;
+        version?: string | undefined;
+        scope?: "project" | "global" | undefined;
+        force?: boolean | undefined;
+    })[] | undefined;
+    fallback?: "interrupt" | "queue" | "inject" | undefined;
+    turnId?: string | undefined;
+}, {
+    sessionId: string;
+    input: string;
+    clientRequestId?: string | undefined;
+    verbosity?: "final" | "messages" | "tools" | "trace" | undefined;
+    skills?: (string | {
+        name: string;
+        version?: string | undefined;
+        scope?: "project" | "global" | undefined;
+        force?: boolean | undefined;
+    })[] | undefined;
+    whenBusy?: "interrupt" | "queue" | "inject" | undefined;
+    fallback?: "interrupt" | "queue" | "inject" | undefined;
+    turnId?: string | undefined;
+}>;
+export type SessionSendParams = z.infer<typeof SessionSendParams>;
+/** send 的同步 ack（真正的内容走 stream.event 异步推）。 */
+export declare const SessionSendAck: z.ZodObject<{
+    sessionId: z.ZodBranded<z.ZodString, "SessionId">;
+    turnId: z.ZodString;
+    accepted: z.ZodLiteral<true>;
+    /**
+     * 本次 send 的实际处由：
+     * - started   ：立即开始执行（session 空闲）
+     * - queued    ：已排队（whenBusy=queue 且正忙）
+     * - interrupted：已中断上一轮并开始本轮（whenBusy=interrupt）
+     * - injected  ：将在下一 tool call 边界插入（whenBusy=inject）
+     */
+    disposition: z.ZodEnum<["started", "queued", "interrupted", "injected"]>;
+    /** queued 时的队列位置（从 1 起）。 */
+    queuePosition: z.ZodOptional<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    sessionId: string & z.BRAND<"SessionId">;
+    turnId: string;
+    accepted: true;
+    disposition: "started" | "queued" | "interrupted" | "injected";
+    queuePosition?: number | undefined;
+}, {
+    sessionId: string;
+    turnId: string;
+    accepted: true;
+    disposition: "started" | "queued" | "interrupted" | "injected";
+    queuePosition?: number | undefined;
+}>;
+export type SessionSendAck = z.infer<typeof SessionSendAck>;
+export declare const SessionInterruptParams: z.ZodObject<{
+    sessionId: z.ZodBranded<z.ZodString, "SessionId">;
+    /** 可选：中断原因（传给 agent / 记录）。 */
+    reason: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    sessionId: string & z.BRAND<"SessionId">;
+    reason?: string | undefined;
+}, {
+    sessionId: string;
+    reason?: string | undefined;
+}>;
+export type SessionInterruptParams = z.infer<typeof SessionInterruptParams>;
+export declare const SessionInterruptResult: z.ZodObject<{
+    sessionId: z.ZodBranded<z.ZodString, "SessionId">;
+    /** 被中断的 turn（若当时有在跑的）。 */
+    interruptedTurnId: z.ZodOptional<z.ZodString>;
+    /** 中断后 session 状态（通常回到 active 空闲）。 */
+    status: z.ZodEnum<["idle", "running", "paused", "terminated"]>;
+}, "strip", z.ZodTypeAny, {
+    status: "idle" | "running" | "paused" | "terminated";
+    sessionId: string & z.BRAND<"SessionId">;
+    interruptedTurnId?: string | undefined;
+}, {
+    status: "idle" | "running" | "paused" | "terminated";
+    sessionId: string;
+    interruptedTurnId?: string | undefined;
+}>;
+export type SessionInterruptResult = z.infer<typeof SessionInterruptResult>;
+export declare const SessionInjectParams: z.ZodObject<{
+    sessionId: z.ZodBranded<z.ZodString, "SessionId">;
+    context: z.ZodArray<z.ZodObject<{
+        role: z.ZodEnum<["system", "user", "assistant"]>;
+        content: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        role: "system" | "user" | "assistant";
+        content: string;
+    }, {
+        role: "system" | "user" | "assistant";
+        content: string;
+    }>, "many">;
+}, "strip", z.ZodTypeAny, {
+    sessionId: string & z.BRAND<"SessionId">;
+    context: {
+        role: "system" | "user" | "assistant";
+        content: string;
+    }[];
+}, {
+    sessionId: string;
+    context: {
+        role: "system" | "user" | "assistant";
+        content: string;
+    }[];
+}>;
+export type SessionInjectParams = z.infer<typeof SessionInjectParams>;
+export declare const SessionInjectResult: z.ZodObject<{
+    sessionId: z.ZodBranded<z.ZodString, "SessionId">;
+    injected: z.ZodNumber;
+}, "strip", z.ZodTypeAny, {
+    sessionId: string & z.BRAND<"SessionId">;
+    injected: number;
+}, {
+    sessionId: string;
+    injected: number;
+}>;
+export type SessionInjectResult = z.infer<typeof SessionInjectResult>;
+export declare const CompressMode: z.ZodEnum<["native", "custom"]>;
+export type CompressMode = z.infer<typeof CompressMode>;
+export declare const SessionCompressParams: z.ZodObject<{
+    sessionId: z.ZodBranded<z.ZodString, "SessionId">;
+    /** native = 透传 agent 原生压缩；custom = phonon 自有压缩引擎。 */
+    mode: z.ZodEnum<["native", "custom"]>;
+    /**
+     * custom 模式下的策略名（P2-15）。**server-private：phonon 不做协议层枚举校验**，
+     * 透传给 adapter/压缩引擎自行解释（如 summary / truncate_keep_recent）。
+     */
+    strategy: z.ZodOptional<z.ZodString>;
+    /** dropToolIO 策略：保留最近 N 个 tool call 及其 result，默认 3。 */
+    keepRecentToolCalls: z.ZodOptional<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    sessionId: string & z.BRAND<"SessionId">;
+    mode: "custom" | "native";
+    strategy?: string | undefined;
+    keepRecentToolCalls?: number | undefined;
+}, {
+    sessionId: string;
+    mode: "custom" | "native";
+    strategy?: string | undefined;
+    keepRecentToolCalls?: number | undefined;
+}>;
+export type SessionCompressParams = z.infer<typeof SessionCompressParams>;
+export declare const SessionCompressResult: z.ZodObject<{
+    sessionId: z.ZodBranded<z.ZodString, "SessionId">;
+    mode: z.ZodEnum<["native", "custom"]>;
+    /** 压缩前后的 token 估算（若可得）。 */
+    tokensBefore: z.ZodOptional<z.ZodNumber>;
+    tokensAfter: z.ZodOptional<z.ZodNumber>;
+    /** 简短摘要/说明。 */
+    summary: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    sessionId: string & z.BRAND<"SessionId">;
+    mode: "custom" | "native";
+    tokensBefore?: number | undefined;
+    tokensAfter?: number | undefined;
+    summary?: string | undefined;
+}, {
+    sessionId: string;
+    mode: "custom" | "native";
+    tokensBefore?: number | undefined;
+    tokensAfter?: number | undefined;
+    summary?: string | undefined;
+}>;
+export type SessionCompressResult = z.infer<typeof SessionCompressResult>;
+export declare const SessionTerminateParams: z.ZodObject<{
+    sessionId: z.ZodBranded<z.ZodString, "SessionId">;
+    /**
+     * 可选：销毁会话时顺手清理其专用 worktree（P1-10）。
+     * 仅当该 session 跑在一个专为它建的 worktree 上才生效；主工作区不清。
+     */
+    cleanWorktree: z.ZodDefault<z.ZodBoolean>;
+}, "strip", z.ZodTypeAny, {
+    sessionId: string & z.BRAND<"SessionId">;
+    cleanWorktree: boolean;
+}, {
+    sessionId: string;
+    cleanWorktree?: boolean | undefined;
+}>;
+export type SessionTerminateParams = z.infer<typeof SessionTerminateParams>;
+export declare const SessionTerminateResult: z.ZodObject<{
+    sessionId: z.ZodBranded<z.ZodString, "SessionId">;
+    status: z.ZodLiteral<"terminated">;
+    /** 若 cleanWorktree 且确实清了，返回被清理的 worktreeId。 */
+    cleanedWorktreeId: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    status: "terminated";
+    sessionId: string & z.BRAND<"SessionId">;
+    cleanedWorktreeId?: string | undefined;
+}, {
+    status: "terminated";
+    sessionId: string;
+    cleanedWorktreeId?: string | undefined;
+}>;
+export type SessionTerminateResult = z.infer<typeof SessionTerminateResult>;
+export declare const SessionSwitchModelParams: z.ZodObject<{
+    sessionId: z.ZodBranded<z.ZodString, "SessionId">;
+    /** 新模型，必须在该 session 绑定 agent 的可用模型列表内。 */
+    model: z.ZodString;
+    /**
+     * running 时的策略（P1-8）：
+     * - reject（默认）     ：running 时拒绝切换，避免 adapter 状态不一致
+     * - afterCurrentTurn：等当前 turn 结束后再切
+     * - interrupt        ：打断当前 turn 立即切
+     * idle 时忽略此参数，直接切。
+     */
+    whenRunning: z.ZodDefault<z.ZodEnum<["reject", "afterCurrentTurn", "interrupt"]>>;
+}, "strip", z.ZodTypeAny, {
+    sessionId: string & z.BRAND<"SessionId">;
+    model: string;
+    whenRunning: "interrupt" | "reject" | "afterCurrentTurn";
+}, {
+    sessionId: string;
+    model: string;
+    whenRunning?: "interrupt" | "reject" | "afterCurrentTurn" | undefined;
+}>;
+export type SessionSwitchModelParams = z.infer<typeof SessionSwitchModelParams>;
+export declare const SessionSwitchModelResult: z.ZodObject<{
+    sessionId: z.ZodBranded<z.ZodString, "SessionId">;
+    /** 切换前的模型（便于调用方记录/回滚）。 */
+    previousModel: z.ZodString;
+    model: z.ZodString;
+    /**
+     * 可选警告（P1-8 / Minimax）：adapter 发现潜在不兼容（系统提示格式/tool schema 变化）
+     * 时填入，server 据此决定是否继续。
+     */
+    warnings: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    /** 若 whenRunning=afterCurrentTurn 且当时 running，表示已排期未立即生效。 */
+    deferred: z.ZodOptional<z.ZodBoolean>;
+}, "strip", z.ZodTypeAny, {
+    sessionId: string & z.BRAND<"SessionId">;
+    model: string;
+    previousModel: string;
+    warnings?: string[] | undefined;
+    deferred?: boolean | undefined;
+}, {
+    sessionId: string;
+    model: string;
+    previousModel: string;
+    warnings?: string[] | undefined;
+    deferred?: boolean | undefined;
+}>;
+export type SessionSwitchModelResult = z.infer<typeof SessionSwitchModelResult>;
+export declare const SessionMeta: z.ZodObject<{
+    sessionId: z.ZodBranded<z.ZodString, "SessionId">;
+    /** 绑定的项目（一等身份，D23）。 */
+    project: z.ZodBranded<z.ZodString, "ProjectId">;
+    /** 绑定的 agent 身份，全程携带。 */
+    agent: z.ZodBranded<z.ZodString, "AgentId">;
+    model: z.ZodString;
+    status: z.ZodEnum<["idle", "running", "paused", "terminated"]>;
+    /** 当 status=running 时，正在执行的 turnId（服务端据此知道「在跑哪一轮」）。 */
+    currentTurnId: z.ZodOptional<z.ZodString>;
+    /** 队列中等待的 send 数（whenBusy=queue 积压，D18）。 */
+    queuedCount: z.ZodOptional<z.ZodNumber>;
+    /**
+     * 上下文信息（D33）——adapter 能提供时填，便于 server 监控上下文压力。
+     */
+    context: z.ZodOptional<z.ZodObject<{
+        /** 上下文窗口总容量（token）。 */
+        contextWindow: z.ZodOptional<z.ZodNumber>;
+        /** 已用上下文（token，若可估）。 */
+        usedTokens: z.ZodOptional<z.ZodNumber>;
+        /** 已用上下文占比 0-100。 */
+        usagePercent: z.ZodOptional<z.ZodNumber>;
+        /** 已发生的压缩次数。 */
+        compactions: z.ZodOptional<z.ZodNumber>;
+    }, "strip", z.ZodTypeAny, {
+        contextWindow?: number | undefined;
+        usedTokens?: number | undefined;
+        usagePercent?: number | undefined;
+        compactions?: number | undefined;
+    }, {
+        contextWindow?: number | undefined;
+        usedTokens?: number | undefined;
+        usagePercent?: number | undefined;
+        compactions?: number | undefined;
+    }>>;
+    verbosity: z.ZodEnum<["final", "messages", "tools", "trace"]>;
+    clientTag: z.ZodOptional<z.ZodString>;
+    createdAt: z.ZodString;
+    lastActiveAt: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    status: "idle" | "running" | "paused" | "terminated";
+    sessionId: string & z.BRAND<"SessionId">;
+    agent: string & z.BRAND<"AgentId">;
+    project: string & z.BRAND<"ProjectId">;
+    model: string;
+    verbosity: "final" | "messages" | "tools" | "trace";
+    createdAt: string;
+    clientTag?: string | undefined;
+    context?: {
+        contextWindow?: number | undefined;
+        usedTokens?: number | undefined;
+        usagePercent?: number | undefined;
+        compactions?: number | undefined;
+    } | undefined;
+    currentTurnId?: string | undefined;
+    queuedCount?: number | undefined;
+    lastActiveAt?: string | undefined;
+}, {
+    status: "idle" | "running" | "paused" | "terminated";
+    sessionId: string;
+    agent: string;
+    project: string;
+    model: string;
+    verbosity: "final" | "messages" | "tools" | "trace";
+    createdAt: string;
+    clientTag?: string | undefined;
+    context?: {
+        contextWindow?: number | undefined;
+        usedTokens?: number | undefined;
+        usagePercent?: number | undefined;
+        compactions?: number | undefined;
+    } | undefined;
+    currentTurnId?: string | undefined;
+    queuedCount?: number | undefined;
+    lastActiveAt?: string | undefined;
+}>;
+export type SessionMeta = z.infer<typeof SessionMeta>;
+export declare const SessionStatusParams: z.ZodObject<{
+    sessionId: z.ZodBranded<z.ZodString, "SessionId">;
+}, "strip", z.ZodTypeAny, {
+    sessionId: string & z.BRAND<"SessionId">;
+}, {
+    sessionId: string;
+}>;
+export type SessionStatusParams = z.infer<typeof SessionStatusParams>;
+export declare const SessionStatusResult: z.ZodObject<{
+    sessionId: z.ZodBranded<z.ZodString, "SessionId">;
+    /** 绑定的项目（一等身份，D23）。 */
+    project: z.ZodBranded<z.ZodString, "ProjectId">;
+    /** 绑定的 agent 身份，全程携带。 */
+    agent: z.ZodBranded<z.ZodString, "AgentId">;
+    model: z.ZodString;
+    status: z.ZodEnum<["idle", "running", "paused", "terminated"]>;
+    /** 当 status=running 时，正在执行的 turnId（服务端据此知道「在跑哪一轮」）。 */
+    currentTurnId: z.ZodOptional<z.ZodString>;
+    /** 队列中等待的 send 数（whenBusy=queue 积压，D18）。 */
+    queuedCount: z.ZodOptional<z.ZodNumber>;
+    /**
+     * 上下文信息（D33）——adapter 能提供时填，便于 server 监控上下文压力。
+     */
+    context: z.ZodOptional<z.ZodObject<{
+        /** 上下文窗口总容量（token）。 */
+        contextWindow: z.ZodOptional<z.ZodNumber>;
+        /** 已用上下文（token，若可估）。 */
+        usedTokens: z.ZodOptional<z.ZodNumber>;
+        /** 已用上下文占比 0-100。 */
+        usagePercent: z.ZodOptional<z.ZodNumber>;
+        /** 已发生的压缩次数。 */
+        compactions: z.ZodOptional<z.ZodNumber>;
+    }, "strip", z.ZodTypeAny, {
+        contextWindow?: number | undefined;
+        usedTokens?: number | undefined;
+        usagePercent?: number | undefined;
+        compactions?: number | undefined;
+    }, {
+        contextWindow?: number | undefined;
+        usedTokens?: number | undefined;
+        usagePercent?: number | undefined;
+        compactions?: number | undefined;
+    }>>;
+    verbosity: z.ZodEnum<["final", "messages", "tools", "trace"]>;
+    clientTag: z.ZodOptional<z.ZodString>;
+    createdAt: z.ZodString;
+    lastActiveAt: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    status: "idle" | "running" | "paused" | "terminated";
+    sessionId: string & z.BRAND<"SessionId">;
+    agent: string & z.BRAND<"AgentId">;
+    project: string & z.BRAND<"ProjectId">;
+    model: string;
+    verbosity: "final" | "messages" | "tools" | "trace";
+    createdAt: string;
+    clientTag?: string | undefined;
+    context?: {
+        contextWindow?: number | undefined;
+        usedTokens?: number | undefined;
+        usagePercent?: number | undefined;
+        compactions?: number | undefined;
+    } | undefined;
+    currentTurnId?: string | undefined;
+    queuedCount?: number | undefined;
+    lastActiveAt?: string | undefined;
+}, {
+    status: "idle" | "running" | "paused" | "terminated";
+    sessionId: string;
+    agent: string;
+    project: string;
+    model: string;
+    verbosity: "final" | "messages" | "tools" | "trace";
+    createdAt: string;
+    clientTag?: string | undefined;
+    context?: {
+        contextWindow?: number | undefined;
+        usedTokens?: number | undefined;
+        usagePercent?: number | undefined;
+        compactions?: number | undefined;
+    } | undefined;
+    currentTurnId?: string | undefined;
+    queuedCount?: number | undefined;
+    lastActiveAt?: string | undefined;
+}>;
+export type SessionStatusResult = z.infer<typeof SessionStatusResult>;
+export declare const SessionListParams: z.ZodObject<{
+    /** 可选：按项目过滤。 */
+    project: z.ZodOptional<z.ZodBranded<z.ZodString, "ProjectId">>;
+    /** 可选：按 agent 过滤。 */
+    agent: z.ZodOptional<z.ZodBranded<z.ZodString, "AgentId">>;
+    /** 可选：按状态过滤。 */
+    status: z.ZodOptional<z.ZodEnum<["idle", "running", "paused", "terminated"]>>;
+    /** 可选：分页上限（P2-14）。 */
+    limit: z.ZodOptional<z.ZodNumber>;
+    /** 可选：分页游标（上一页返回的 nextCursor）。 */
+    cursor: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    status?: "idle" | "running" | "paused" | "terminated" | undefined;
+    agent?: (string & z.BRAND<"AgentId">) | undefined;
+    project?: (string & z.BRAND<"ProjectId">) | undefined;
+    limit?: number | undefined;
+    cursor?: string | undefined;
+}, {
+    status?: "idle" | "running" | "paused" | "terminated" | undefined;
+    agent?: string | undefined;
+    project?: string | undefined;
+    limit?: number | undefined;
+    cursor?: string | undefined;
+}>;
+export type SessionListParams = z.infer<typeof SessionListParams>;
+export declare const SessionListResult: z.ZodObject<{
+    sessions: z.ZodArray<z.ZodObject<{
+        sessionId: z.ZodBranded<z.ZodString, "SessionId">;
+        /** 绑定的项目（一等身份，D23）。 */
+        project: z.ZodBranded<z.ZodString, "ProjectId">;
+        /** 绑定的 agent 身份，全程携带。 */
+        agent: z.ZodBranded<z.ZodString, "AgentId">;
+        model: z.ZodString;
+        status: z.ZodEnum<["idle", "running", "paused", "terminated"]>;
+        /** 当 status=running 时，正在执行的 turnId（服务端据此知道「在跑哪一轮」）。 */
+        currentTurnId: z.ZodOptional<z.ZodString>;
+        /** 队列中等待的 send 数（whenBusy=queue 积压，D18）。 */
+        queuedCount: z.ZodOptional<z.ZodNumber>;
+        /**
+         * 上下文信息（D33）——adapter 能提供时填，便于 server 监控上下文压力。
+         */
+        context: z.ZodOptional<z.ZodObject<{
+            /** 上下文窗口总容量（token）。 */
+            contextWindow: z.ZodOptional<z.ZodNumber>;
+            /** 已用上下文（token，若可估）。 */
+            usedTokens: z.ZodOptional<z.ZodNumber>;
+            /** 已用上下文占比 0-100。 */
+            usagePercent: z.ZodOptional<z.ZodNumber>;
+            /** 已发生的压缩次数。 */
+            compactions: z.ZodOptional<z.ZodNumber>;
+        }, "strip", z.ZodTypeAny, {
+            contextWindow?: number | undefined;
+            usedTokens?: number | undefined;
+            usagePercent?: number | undefined;
+            compactions?: number | undefined;
+        }, {
+            contextWindow?: number | undefined;
+            usedTokens?: number | undefined;
+            usagePercent?: number | undefined;
+            compactions?: number | undefined;
+        }>>;
+        verbosity: z.ZodEnum<["final", "messages", "tools", "trace"]>;
+        clientTag: z.ZodOptional<z.ZodString>;
+        createdAt: z.ZodString;
+        lastActiveAt: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        status: "idle" | "running" | "paused" | "terminated";
+        sessionId: string & z.BRAND<"SessionId">;
+        agent: string & z.BRAND<"AgentId">;
+        project: string & z.BRAND<"ProjectId">;
+        model: string;
+        verbosity: "final" | "messages" | "tools" | "trace";
+        createdAt: string;
+        clientTag?: string | undefined;
+        context?: {
+            contextWindow?: number | undefined;
+            usedTokens?: number | undefined;
+            usagePercent?: number | undefined;
+            compactions?: number | undefined;
+        } | undefined;
+        currentTurnId?: string | undefined;
+        queuedCount?: number | undefined;
+        lastActiveAt?: string | undefined;
+    }, {
+        status: "idle" | "running" | "paused" | "terminated";
+        sessionId: string;
+        agent: string;
+        project: string;
+        model: string;
+        verbosity: "final" | "messages" | "tools" | "trace";
+        createdAt: string;
+        clientTag?: string | undefined;
+        context?: {
+            contextWindow?: number | undefined;
+            usedTokens?: number | undefined;
+            usagePercent?: number | undefined;
+            compactions?: number | undefined;
+        } | undefined;
+        currentTurnId?: string | undefined;
+        queuedCount?: number | undefined;
+        lastActiveAt?: string | undefined;
+    }>, "many">;
+    /** 下一页游标；缺省/null 表示已到末尾。 */
+    nextCursor: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    sessions: {
+        status: "idle" | "running" | "paused" | "terminated";
+        sessionId: string & z.BRAND<"SessionId">;
+        agent: string & z.BRAND<"AgentId">;
+        project: string & z.BRAND<"ProjectId">;
+        model: string;
+        verbosity: "final" | "messages" | "tools" | "trace";
+        createdAt: string;
+        clientTag?: string | undefined;
+        context?: {
+            contextWindow?: number | undefined;
+            usedTokens?: number | undefined;
+            usagePercent?: number | undefined;
+            compactions?: number | undefined;
+        } | undefined;
+        currentTurnId?: string | undefined;
+        queuedCount?: number | undefined;
+        lastActiveAt?: string | undefined;
+    }[];
+    nextCursor?: string | undefined;
+}, {
+    sessions: {
+        status: "idle" | "running" | "paused" | "terminated";
+        sessionId: string;
+        agent: string;
+        project: string;
+        model: string;
+        verbosity: "final" | "messages" | "tools" | "trace";
+        createdAt: string;
+        clientTag?: string | undefined;
+        context?: {
+            contextWindow?: number | undefined;
+            usedTokens?: number | undefined;
+            usagePercent?: number | undefined;
+            compactions?: number | undefined;
+        } | undefined;
+        currentTurnId?: string | undefined;
+        queuedCount?: number | undefined;
+        lastActiveAt?: string | undefined;
+    }[];
+    nextCursor?: string | undefined;
+}>;
+export type SessionListResult = z.infer<typeof SessionListResult>;
+//# sourceMappingURL=session.d.ts.map