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

package/dist/conversations/events.js

@@ -0,0 +1,639 @@
+import { DOCUMENT_MEDIA_TYPES, hasControlChars, IMAGE_MEDIA_TYPES, isAttachmentId, isSkillName, MEDIA_NAME_MAX_CHARS, } from "@capybara-hq/plugin-sdk";
+import { z } from "zod";
+import { AgentDefinitionSchema, AgentToolRef, ModelRef } from "../agents/definition.js";
+import { TOOL_VIEW_DIFF_MAX_LINES, TOOL_VIEW_LINE_MAX_CHARS, TOOL_VIEW_PATH_MAX_CHARS, } from "../tools/view.js";
+/** 供应商私有数据（`ProviderOpaque`）：原样保存、只回放给同一供应商。 */
+const ProviderOpaqueSchema = z.object({
+    provider: z.string(),
+    model: z.string(),
+    data: z.unknown(),
+});
+/**
+ * 日志里的媒体来源：只有附件引用。字节（`base64`）绝不进事件日志——日志是事实源、字节不是；
+ * 构建模型请求时内核按 `attachmentId` 取字节换成 `base64`（见 {@link LogContentBlock}）。
+ */
+const AttachmentIdSchema = z.string().refine(isAttachmentId, "attachmentId must be a UUID");
+const RefMediaSourceSchema = z.object({
+    kind: z.literal("ref"),
+    attachmentId: AttachmentIdSchema,
+});
+/** The longest deny reason (characters): the decision route's limit and `approval_decided.reason`'s. */
+export const APPROVAL_DENY_REASON_MAX_CHARS = 500;
+/** 一条 `media_excluded` 事件最多的附件数。 */
+export const MEDIA_EXCLUDED_MAX_IDS = 50;
+/** 一份 `skills_catalog` 快照最多的技能数（组织技能引用上限 100，余量给 agent 自己的技能）。 */
+export const SKILLS_CATALOG_MAX = 1000;
+/** The longest pinned skill body in a `skills_catalog` snapshot (the pinned total is ≤ 32768 bytes). */
+export const PINNED_BODY_MAX_CHARS = 32768;
+/** 媒体块的名字：与 plugin-sdk `validateMediaBlock` 同规则（≤255 字符、不含控制字符）。 */
+const MediaNameSchema = z
+    .string()
+    .max(MEDIA_NAME_MAX_CHARS)
+    .refine((s) => !hasControlChars(s), "name must not contain control characters");
+const ArtifactNameSchema = MediaNameSchema.min(1);
+/** 产物名（`artifact_created.name`）是否合法：与日志 schema 同一规则（非空、≤255、不含控制字符）。 */
+export const isValidArtifactName = (name) => ArtifactNameSchema.safeParse(name).success;
+/**
+ * 日志里的内容块：plugin-sdk 的 `ContentBlock`，但 image / document 的 `source` 只能是 `ref`
+ * （写入时用这个 schema 校验，带 `base64` 的块被拒绝）。
+ */
+export const ContentBlockSchema = z.discriminatedUnion("type", [
+    z.object({ type: z.literal("text"), text: z.string(), opaque: ProviderOpaqueSchema.optional() }),
+    z.object({
+        type: z.literal("thinking"),
+        text: z.string(),
+        opaque: ProviderOpaqueSchema.optional(),
+    }),
+    z.object({
+        type: z.literal("tool_call"),
+        id: z.string(),
+        name: z.string(),
+        input: z.unknown(),
+        opaque: ProviderOpaqueSchema.optional(),
+    }),
+    z.object({
+        type: z.literal("tool_result"),
+        callId: z.string(),
+        content: z.string(),
+        isError: z.boolean(),
+    }),
+    z.object({
+        type: z.literal("image"),
+        mediaType: z.enum(IMAGE_MEDIA_TYPES),
+        source: RefMediaSourceSchema,
+        name: MediaNameSchema.optional(),
+    }),
+    z.object({
+        type: z.literal("document"),
+        mediaType: z.enum(DOCUMENT_MEDIA_TYPES),
+        source: RefMediaSourceSchema,
+        name: MediaNameSchema.optional(),
+    }),
+]);
+const STOP_REASONS = ["end_turn", "tool_use", "max_tokens", "refusal", "other"];
+/** The standard effort values (plugin-sdk `EFFORT_VALUES`, as a tuple for zod). */
+const EFFORT_ENUM = ["low", "medium", "high", "xhigh", "max"];
+const seqNo = z.number().int().nonnegative();
+const count = z.number().int().nonnegative();
+/**
+ * Structured view of a builtin tool's result (UI refresh B, spec §5.5 / §5.9): display only, like
+ * `display`. `command`: `sandbox_bash` (the model's `description`, the exit code, null when the
+ * command was stopped, and whether it timed out; the web shows "Failed" for a non-zero exit even
+ * though `isError` stays false); `edit`: `sandbox_edit` / `sandbox_write` (a capped line diff);
+ * `read`: `sandbox_read` (the line range shown).
+ */
+export const ToolViewSchema = z.discriminatedUnion("kind", [
+    z.object({
+        kind: z.literal("command"),
+        description: z.string().max(120).optional(),
+        exitCode: z.number().int().nullable(),
+        timedOut: z.boolean(),
+    }),
+    z.object({
+        kind: z.literal("edit"),
+        path: z.string().max(TOOL_VIEW_PATH_MAX_CHARS),
+        created: z.boolean(),
+        added: count,
+        removed: count,
+        truncated: z.boolean(),
+        hunks: z
+            .array(z.object({
+            oldStart: count,
+            newStart: count,
+            lines: z
+                .array(z.object({
+                kind: z.enum(["ctx", "add", "del"]),
+                text: z.string().max(TOOL_VIEW_LINE_MAX_CHARS),
+            }))
+                .max(TOOL_VIEW_DIFF_MAX_LINES),
+        }))
+            .max(TOOL_VIEW_DIFF_MAX_LINES),
+    }),
+    z.object({
+        kind: z.literal("read"),
+        path: z.string().max(TOOL_VIEW_PATH_MAX_CHARS),
+        fromLine: count.optional(),
+        toLine: count.optional(),
+    }),
+]);
+const ModelUsageShape = {
+    inputTokens: count,
+    outputTokens: count,
+    cacheReadTokens: count,
+    cacheWriteTokens: count,
+};
+/** 双语或纯文本（plugin-sdk `InputForm` 的文案字段）。 */
+const FormTextSchema = z.union([z.string(), z.object({ zh: z.string(), en: z.string() })]);
+/** 交互表单（plugin-sdk 的 `InputForm`；字段 schema 已由 `validateInputForm` 校验过，这里只记形状）。 */
+const InputFormSchema = z.object({
+    title: FormTextSchema,
+    /** 需要用户在浏览器里打开的外部页面（MCP URL 模式的 elicitation）。较早的事件没有。 */
+    url: z.string().optional(),
+    fields: z.array(z.object({
+        key: z.string(),
+        label: FormTextSchema,
+        description: FormTextSchema.optional(),
+        schema: z.record(z.string(), z.unknown()),
+        multiSelect: z.boolean().optional(),
+        allowOther: z.boolean().optional(),
+        required: z.boolean().optional(),
+    })),
+});
+/** 表单答案（plugin-sdk 的 `FormAnswer`）。 */
+const FormAnswerSchema = z.record(z.string(), z.union([z.string(), z.number(), z.boolean(), z.array(z.string())]));
+const ev = (type, payload) => z.object({ type: z.literal(type), payload });
+/**
+ * 会话事件（`type` + `payload`）的判别联合。事件日志只追加，写入前用它校验 payload；
+ * 读出时按写入时的形状原样返回。
+ */
+export const ConversationEventSchema = z.discriminatedUnion("type", [
+    ev("user_message", z.object({
+        content: z.array(ContentBlockSchema),
+        /**
+         * `@` 资源引用的附件元数据：第 i 个附件的正文是 `content[i + 1]`（`content[0]` 是用户输入的文本）。
+         * 界面据此把附件显示为条目而不是正文。较早的事件没有。`appId` / `appName` 是连接器的 id 与名称：
+         * 「应用」改名「连接器」后字段名不变（D17 / C27：日志确定性）。
+         */
+        attachments: z
+            .array(z.object({ appId: z.string(), appName: z.string(), uri: z.string(), name: z.string() }))
+            .optional(),
+        authorAccountId: z.string(),
+        clientMessageId: z.string().optional(),
+        /**
+         * A retry after a failed run (UI refresh B): the seq of the message it repeats. Display only
+         * (the page folds it into the failed divider); the model sees the message itself.
+         */
+        retryOf: seqNo.optional(),
+        /**
+         * A person's skill invocation (`/name args`, phase D spec §4.3): which skill version was
+         * rendered into `content[0]`, with the arguments as typed (trimmed). Not model-visible (the
+         * rendered text is); the web renders the chip and the arguments from it. `name` is the
+         * skill's bare name, `plugin` its catalog item; `agentType` is set for `mode: "fork"`.
+         */
+        skill: z
+            .object({
+            id: z.string(),
+            version: z.number().int(),
+            source: z.string(),
+            name: z.string(),
+            plugin: z.string().optional(),
+            arguments: z.string(),
+            mode: z.enum(["inline", "fork"]),
+            agentType: z.string().optional(),
+        })
+            .optional(),
+        /**
+         * Set on a sub-agent's task message (phase C, spec §6.3): which parent call dispatched it.
+         * Not model-visible; the web renders the message as the task block.
+         */
+        dispatch: z
+            .object({
+            parentConversationId: z.string(),
+            parentRunId: z.string(),
+            callId: z.string(),
+            /**
+             * A follow-up (`resume`, final review I1): the frozen tools and org skills intersected
+             * with the current version (`narrowFollowUp`); the child's run uses these instead of
+             * the frozen ones. Absent on a first dispatch and in older logs.
+             */
+            narrowed: z
+                .object({
+                tools: z.array(AgentToolRef),
+                skills: z
+                    .object({ orgSkills: z.array(z.string()), pinned: z.array(z.string()).optional() })
+                    .optional(),
+            })
+                .optional(),
+        })
+            .optional(),
+    })),
+    /**
+     * The person switched the conversation's model or effort (UI refresh B), written just before the
+     * message that carried the switch; or the kernel fell back to the agent's model because the
+     * switched-to one no longer resolves (`reason: "unavailable"`, `byAccountId: null`, written by
+     * that run before its `run_started`). Applies from the next run that starts (`selectionAt`). Not
+     * model-visible itself: its effect is recorded per request in `model_call` (model and params).
+     */
+    ev("model_switched", z.object({
+        /** null = back to the agent's model. */
+        model: ModelRef.nullable(),
+        /** null = the agent's saved effort or the model's default. */
+        effort: z.enum(EFFORT_ENUM).nullable(),
+        /** null = the kernel (fallback). */
+        byAccountId: z.string().nullable(),
+        reason: z.enum(["user", "unavailable"]),
+    })),
+    ev("run_started", z.object({
+        agentVersion: z.number().int().positive(),
+        model: ModelRef,
+        triggerAccountId: z.string(),
+    })),
+    ev("model_call", z.object({
+        step: count,
+        attempt: count,
+        provider: z.string(),
+        model: z.string(),
+        fallback: z.boolean(),
+        request: z.object({
+            fromSeq: seqNo,
+            toSeq: seqNo,
+            summarySeq: seqNo.nullable(),
+            systemHash: z.string(),
+            reminderSeqs: z.array(seqNo),
+            /** 本次请求的输出上限（`min(模型上限, maxOutputTokens 旋钮 ?? runtime.maxOutputTokens)`）。较早的事件可能没有。 */
+            maxOutputTokens: count.optional(),
+            /**
+             * 本次请求的模型参数（`ModelRequest.params`）：agent 保存的参数按该模型声明 sanitize 后的结果
+             * （已补默认值）。主模型尝试来自 `modelParams`，兜底尝试来自 `fallbackParams`。较早的事件可能没有。
+             */
+            params: z.record(z.string(), z.union([z.string(), z.number(), z.boolean()])).optional(),
+            /** sanitize 时丢弃的参数键（未声明或值不再合法，如插件升级后）；没有丢弃时不写。 */
+            droppedParams: z.array(z.string()).optional(),
+            /**
+             * 发出请求时的输入 token 估算（未校正）。与随后 `usage.inputTokens` 一起供下一次
+             * `calibrate` 使用。较早的事件可能没有。
+             */
+            estimatedInputTokens: count.optional(),
+            /**
+             * 发出请求时 loop 已吸收到的 user_message seq（R31）：seq 更大的 user_message 不进本次请求
+             * （由后续步骤吸收或触发下一轮）。还原请求时据此放置 / 排除用户消息。较早的事件可能没有。
+             */
+            absorbedUpToSeq: seqNo.optional(),
+            /**
+             * 本次请求带给模型的工具（按发送顺序：未启用 tool_search 时按 key 排序；启用时为内置工具按 key 排序，
+             * 其后是已加载工具按首次加载顺序）及其定义指纹（`ResolvedTool.specHash`）。
+             * 模型不支持工具时为空数组。较早的事件可能没有。
+             */
+            tools: z.array(z.object({ key: z.string(), specHash: z.string() })).optional(),
+            /**
+             * 启用 tool_search 时 system 第二块目录里的工具（按 key 排序）及定义指纹；定义同样存在
+             * `capybara.tool_specs`，目录文本可由它们还原。未启用时不写。
+             */
+            catalog: z.array(z.object({ key: z.string(), specHash: z.string() })).optional(),
+            /**
+             * 本次请求的 `toolChoice`：收尾调用为 `"none"`（照常带工具，但不得调用）；普通步骤不写（由模型决定）。
+             * 定义本身按 specHash 存在 `capybara.tool_specs`。
+             */
+            toolChoice: z.enum(["auto", "none"]).optional(),
+            /**
+             * 请求里每个附件的处理结果（Ruling M8，按首次出现，同一附件一条）：发了字节（`bytes`，带 finalize 时的
+             * etag）、内联文本、模型不支持的占位、因请求媒体预算省略（`omitted`）、图片太多（`too_many_images`）、
+             * 单个超过供应商上限（`too_large`）、不再可用、PDF 页数太多、
+             * 被 `media_excluded` 排除。没有媒体时不写；较早的事件没有。
+             */
+            media: z
+                .array(z.object({
+                attachmentId: AttachmentIdSchema,
+                outcome: z.enum([
+                    "bytes",
+                    "inline",
+                    "placeholder_unsupported",
+                    "omitted",
+                    "too_many_images",
+                    "too_large",
+                    "unavailable",
+                    "too_many_pages",
+                    "excluded",
+                ]),
+                etag: z.string().max(1024).optional(),
+            }))
+                .optional(),
+            /**
+             * 本次请求的媒体字节预算（`attachments.requestMediaBytes`，见 planMedia）：请求里有媒体时才写，
+             * 还原时用它重现同样的省略结果。较早的事件没有。
+             */
+            mediaBudgetBytes: count.optional(),
+        }),
+    })),
+    ev("assistant_message", z.object({
+        step: count,
+        content: z.array(ContentBlockSchema),
+        stopReason: z.enum([...STOP_REASONS, "aborted"]),
+    })),
+    /**
+     * Usage of one model call. Absent `purpose` = the step's call (written with its
+     * `assistant_message`); `compaction` = the compaction call before the step (I-1: billed and
+     * reported, but no step consumer may pair it with the step's `model_call`); `title` = the
+     * conversation title call (UI refresh B: no run, `step` 0, not model-visible, billed and reported).
+     */
+    ev("usage", z.object({
+        step: count,
+        provider: z.string(),
+        model: z.string(),
+        ...ModelUsageShape,
+        purpose: z.enum(["compaction", "title"]).optional(),
+    })),
+    ev("reminder", z.object({ step: count, text: z.string() })),
+    /** 工具调用开始执行之前写入（续跑时「有开始无结果」的调用记为结果未知，不再执行）。 */
+    ev("tool_call_started", z.object({ step: count, callId: z.string(), toolKey: z.string(), specHash: z.string() })),
+    /**
+     * 工具调用的结果（模型看到的文本）。构建请求时还原为紧随该步 assistant 消息的 user 消息中的
+     * `tool_result` 块。`outputId`：超长结果转存后的存档 id；`contentTypes`：结果里出现的内容类型。
+     */
+    ev("tool_result", z.object({
+        step: count,
+        callId: z.string(),
+        toolKey: z.string(),
+        content: z.string(),
+        isError: z.boolean(),
+        outputId: z.string().optional(),
+        contentTypes: z.array(z.string()).optional(),
+        /**
+         * `tool_search` 本次加载的工具 key（没有匹配时不写）。已加载集合 = 会话中全部 tool_result 的
+         * `loadedTools` 并集（含已被摘要覆盖的部分），构建请求时由日志还原，不放进程内存。
+         */
+        loadedTools: z.array(z.string()).optional(),
+        /**
+         * 工具给的一句话说明（`ToolResult.display`，中英文），只给界面显示：不进模型请求（重建请求只用
+         * callId / content / isError），也不进压缩记录。插件 / 内置工具给出且通过 `validateToolDisplay` 时才写。
+         */
+        display: z.object({ summary: z.object({ zh: z.string(), en: z.string() }) }).optional(),
+        /** Structured view ({@link ToolViewSchema}); builtins only, display only, not in compaction. */
+        view: ToolViewSchema.optional(),
+        /**
+         * An inline card under the call (`ToolResult.card`, UI refresh B): an `inline` ui contribution
+         * of the extension that ran the tool. Display only: never in the model request or compaction.
+         */
+        card: z
+            .object({
+            plugin: z.string().min(1).max(100),
+            view: z.string().min(1).max(100),
+            key: z.string().min(1).max(200).optional(),
+        })
+            .optional(),
+    })),
+    /**
+     * 工具调用时发现发起人尚未连接个人凭据的连接器：界面据此显示连接卡片（不进模型请求；模型看到的是
+     * 同一调用的 tool_result 错误说明）。组织凭据缺失不写此事件。`appId` / `appName` 是连接器的 id 与名称，
+     * 改名后字段名不变（D17 / C27）。
+     */
+    ev("connection_required", z.object({ step: count, callId: z.string(), appId: z.string(), appName: z.string() })),
+    /**
+     * 工具调用需要人审批（策略为 `ask`）：审批记录已建，run 暂停等待处理。界面据此显示审批卡片
+     * （不进模型请求；该调用的结果在审批处理后写入）。
+     */
+    ev("approval_requested", z.object({
+        step: count,
+        callId: z.string(),
+        approvalId: z.string(),
+        toolKey: z.string(),
+        expiresAt: z.string(),
+        /** Which rule asked (UI refresh B; display only, absent in older logs). */
+        policy: z.enum(["agent", "connector", "default", "role", "org", "fixed"]).optional(),
+    })),
+    /** 审批已处理（批准 / 拒绝 / 超时 / 取消）；`scope` 只在批准时出现，`byAccountId` 为处理人（超时 / 取消为 null）。 */
+    ev("approval_decided", z.object({
+        approvalId: z.string(),
+        callId: z.string(),
+        decision: z.enum(["approved", "denied", "expired", "cancelled"]),
+        scope: z.enum(["once", "session", "always"]).optional(),
+        byAccountId: z.string().nullable(),
+        /**
+         * The reason given with a denial (UI refresh B; display only here: the model sees it in the
+         * denied call's `tool_result`).
+         */
+        reason: z.string().max(APPROVAL_DENY_REASON_MAX_CHARS).optional(),
+    })),
+    /**
+     * 工具调用需要用户输入（`ask_user`、插件工具的 `input_required`、MCP elicitation）：输入请求已建，
+     * run 暂停等待回答。界面据此显示表单卡片（不进模型请求）。
+     */
+    ev("question_asked", z.object({
+        step: count,
+        callId: z.string(),
+        questionId: z.string(),
+        form: InputFormSchema,
+        expiresAt: z.string(),
+    })),
+    /** 输入请求已结束：回答 / 超时 / 取消（后两者 `answer` 与 `byAccountId` 为 null）。 */
+    ev("question_answered", z.object({
+        questionId: z.string(),
+        callId: z.string(),
+        answer: FormAnswerSchema.nullable(),
+        byAccountId: z.string().nullable(),
+        outcome: z.enum(["answered", "expired", "cancelled"]),
+    })),
+    /**
+     * 带媒体的模型请求被供应商以不可重试的 `invalid_request` / `context_overflow` 拒绝（Ruling M8）：这些附件
+     * （该请求里发了字节的）此后一律换成「被供应商拒绝」的占位，会话不会因同一个附件永久卡住。不进模型请求
+     * 本身，只影响之后的请求构建（可由日志推出）。
+     */
+    ev("media_excluded", z.object({
+        attachmentIds: z.array(AttachmentIdSchema).min(1).max(MEDIA_EXCLUDED_MAX_IDS),
+        reason: z.enum(["provider_rejected"]),
+    })),
+    /**
+     * agent 经 `sandbox_deliver` 把沙箱里的文件交付给用户（M5 T8，C3）：字节在对象存储
+     * `kernel/<orgId>/<objectKey>`（`objectKey` = `artifacts/<conversationId>/<artifactId>`，相对内核前缀），
+     * 这里只有元数据。网页从日志重建产物列表；不进模型请求（模型看到的是同一调用的 tool_result 确认）。
+     */
+    ev("artifact_created", z.object({
+        artifactId: z.uuid(),
+        name: ArtifactNameSchema,
+        contentType: z.string().min(1).max(200),
+        size: z.number().int().nonnegative(),
+        objectKey: z.string().min(1),
+        sourcePath: z.string().min(1),
+        callId: z.string(),
+    })),
+    /**
+     * 本对话此刻生效的技能（M5 T14，Ruling M17）：运行开始时内核解析生效的技能集合（agent 版本选中的组织技能 +
+     * agent 自己的技能，未删除，取 current_version），与日志里上一份快照不同才写。模型看到的技能目录只来自这里：
+     * 第一份（在任何 `model_call` 之前）进 system 缓存段，之后的在所在位置渲染为英文变更提醒；`skill_load` 按最新一份
+     * 把名字解析为 id 与版本。按 name 排序。
+     */
+    ev("skills_catalog", z.object({
+        skills: z
+            .array(z.object({
+            id: z.string().min(1).max(100),
+            name: z.string().refine(isSkillName, "invalid skill name"),
+            description: z.string().max(4096),
+            version: z.number().int().positive(),
+            /**
+             * 内容来源（对象前缀，T15）：已生成的版本为 `skill_versions.object_prefix`，试用中的草稿为申请的
+             * `object_prefix`。同号的草稿与正式版本靠它区分；`skill_load` 只按它解析。
+             */
+            source: z.string().min(1).max(512),
+            /**
+             * The catalog item (plugin) name the skill came from (phase B); absent for the org's
+             * own and the agent's skills, and in snapshots written before phase B. `skill_load`
+             * resolves `<plugin>:<name>` with it; it is not model-visible otherwise.
+             */
+            plugin: z.string().min(1).max(64).optional(),
+        }))
+            .max(SKILLS_CATALOG_MAX),
+        /**
+         * Pinned skills (phase B, spec §9.1) in the agent's order: each a skill of `skills` (same
+         * id, version and source) with its SKILL.md body as read at run start or written by
+         * skill_write. Absent means none (every snapshot before phase B).
+         */
+        pinned: z
+            .array(z.object({
+            id: z.string().min(1).max(100),
+            version: z.number().int().positive(),
+            name: z.string().refine(isSkillName, "invalid skill name"),
+            source: z.string().min(1).max(512),
+            body: z.string().max(PINNED_BODY_MAX_CHARS),
+        }))
+            .max(3)
+            .optional(),
+        /**
+         * The Claude Code tool-name map text (`CLAUDE_CODE_TOOL_MAP`), present iff a skill in
+         * `skills` came from a Claude Code plugin.
+         */
+        toolMap: z.string().max(4000).optional(),
+    })),
+    /**
+     * A plugin policy hook denied a model request or a tool call (E6). Not model-visible: request building
+     * skips it; the model sees only `reason`, inside the tool error of a denied tool call (and nothing for a
+     * denied model request, whose run fails with `run.hook_denied`). No raw hook error here (Ruling R12):
+     * the events API reaches conversation participants, so the raw text lives in the `hook.denied` audit
+     * row only.
+     */
+    ev("hook_denied", z.object({
+        mount: z.enum(["model.request", "tool.preExecute"]),
+        plugin: z.string(),
+        reason: z.string().max(500),
+        cause: z.enum(["deny", "hook_error", "timeout"]),
+        step: count,
+        attempt: count.optional(),
+        callId: z.string().optional(),
+    })),
+    /**
+     * The first event of a sub-agent's (child) conversation (phase C, spec §6.3), written once in the
+     * dispatch transaction. Request building for a `subagent` conversation takes the definition and
+     * the preamble from here, never from `agent_versions`, so later changes never alter an old
+     * child's request. The event itself is not rendered as a message.
+     */
+    ev("subagent_started", z.object({
+        parent: z.object({
+            conversationId: z.string(),
+            runId: z.string(),
+            callId: z.string(),
+            step: count,
+        }),
+        agentType: z.string().min(1).max(130),
+        template: z.object({
+            source: z.enum(["general", "inline", "plugin", "agent"]),
+            id: z.string().optional(),
+            version: z.number().int().positive().optional(),
+            plugin: z.string().optional(),
+            /**
+             * Phase D: the child runs a forked skill a person invoked (display and eval metadata, not
+             * model-visible).
+             */
+            invokedSkill: z
+                .object({ id: z.string(), version: z.number().int(), name: z.string() })
+                .optional(),
+        }),
+        /** The effective (narrowed) definition, frozen at dispatch. */
+        definition: AgentDefinitionSchema,
+        /** `SUBAGENT_PREAMBLE` at dispatch time. */
+        preamble: z.string(),
+        maxSteps: z.number().int().positive(),
+        warnings: z.array(z.string()).optional(),
+    })),
+    /**
+     * Parent log (phase C, spec §14.1): the `agent` call `callId` started (or resumed) the sub-agent
+     * `subagentId` (its child conversation id) with run `childRunId`. Not model-visible: the model
+     * sees the call's tool_call / tool_result pair.
+     */
+    ev("subagent_dispatched", z.object({
+        step: count,
+        callId: z.string(),
+        subagentId: z.string(),
+        childRunId: z.string(),
+        agentType: z.string(),
+        description: z.string(),
+        resumed: z.boolean(),
+        model: z.object({ provider: z.string(), model: z.string() }),
+        tierFallback: z.boolean().optional(),
+        /**
+         * Phase D: the seq of the person's fork invocation this dispatch runs (`callId` is
+         * `skill-<seq>`, step 0, no tool call); absent for an `agent` call.
+         */
+        invokedSeq: seqNo.optional(),
+    })),
+    /** Parent log: a sub-agent waits for a person (approval, input or a connection). Not model-visible. */
+    ev("subagent_waiting", z.object({
+        subagentId: z.string(),
+        childRunId: z.string(),
+        kind: z.enum(["approval", "input", "connect"]),
+        approvalId: z.string().optional(),
+        questionId: z.string().optional(),
+        toolKey: z.string(),
+        expiresAt: z.string().optional(),
+    })),
+    /** Parent log: a sub-agent's run ended. Not model-visible (its reply is the call's tool_result). */
+    ev("subagent_finished", z.object({
+        subagentId: z.string(),
+        childRunId: z.string(),
+        callId: z.string(),
+        /** `timed_out`: stopped by the parent's sub-agents wait timeout (`run_aborted.detail`). */
+        status: z.enum([
+            "completed",
+            "max_steps",
+            "max_duration",
+            "budget",
+            "aborted",
+            "timed_out",
+            "failed",
+        ]),
+        errorCode: z.string().optional(),
+        toolCalls: count,
+        durationMs: count,
+        usage: z.object(ModelUsageShape),
+    })),
+    /**
+     * Phase D (spec §6.3): the report of the sub-agent that ran a person's fork invocation
+     * (`invokedSeq`), written once (idem `skill_fork_result:<seq>`) before the parent's next model
+     * call. **Model-visible**: request building renders `text` as user content right after the
+     * invocation message. `subagentId` / `childRunId` are absent when no sub-agent ran (refused, or
+     * the run ended before it started).
+     */
+    ev("skill_fork_result", z.object({
+        invokedSeq: seqNo,
+        subagentId: z.string().optional(),
+        childRunId: z.string().optional(),
+        text: z.string(),
+    })),
+    ev("compaction_summary", z.object({ coversUpToSeq: seqNo, text: z.string() })),
+    ev("compaction_failed", z.object({ attempt: count, reason: z.string() })),
+    ev("run_finished", z.object({
+        /** `budget`: a sub-agent stopped at its parent run's token cap (phase C, spec §8.3). */
+        reason: z.enum(["completed", "max_steps", "max_duration", "budget"]),
+        consumedUpToSeq: seqNo,
+    })),
+    ev("run_failed", z.object({ error: z.object({ code: z.string(), message: z.string() }) })),
+    ev("run_aborted", z.object({
+        byAccountId: z.string().nullable(),
+        /** `eval_stopped`：评测整轮回放被评测运行停下（只出现在 `kind = 'eval'` 的对话里），原因见 `detail`。 */
+        reason: z.enum(["user", "shutdown_exhausted", "eval_stopped"]),
+        /**
+         * Why an eval replay stopped (`eval_stopped`), or `wait_timeout`: a sub-agent run stopped
+         * (`user`, no account) because its parent's sub-agents wait timed out (phase C).
+         */
+        detail: z
+            .enum(["cancelled", "capped", "too_many_errors", "claim_lost", "shutdown", "wait_timeout"])
+            .optional(),
+    })),
+]);
+/**
+ * What the person typed for a skill invocation (phase D): `/<plugin>:<name> <arguments>` (no
+ * plugin: `/<name>`). Titles and eval case titles use it instead of the rendered skill in
+ * `content[0]`.
+ */
+export const typedInvocation = (skill) => `/${skill.plugin === undefined ? "" : `${skill.plugin}:`}${skill.name}${skill.arguments === "" ? "" : ` ${skill.arguments}`}`;
+// 日志 schema 对的是收窄后的 LogContentBlock（媒体块只认 ref）；再核对它确是 ContentBlock 的子类型。
+const _blocks = true;
+const _logIsBlock = true;
+const _stop = true;
+const _effort = true;
+void _effort;
+const _usage = true;
+const _toolResult = true;
+void _toolResult;
+void _blocks;
+void _logIsBlock;
+void _stop;
+void _usage;