@downcity/agent 1.1.217 → 1.1.224

package/scripts/session-history-archive.test.mjs

@@ -1,188 +0,0 @@
-/**
- * @file 验证 session.records 的 compact archive 分层读取语义。
- *
- * 关键点（中文）
- * - compact summary 是模型上下文消息，但不应作为用户可见 history item 返回。
- * - 调用方通过 previous_archive_id 再传入 archive_id，读取上一层被覆盖历史。
- * - history 分页字段使用 snake_case，保持 SDK 对外数据命名一致。
- */
-
-import test from "node:test";
-import assert from "node:assert/strict";
-import os from "node:os";
-import path from "node:path";
-import fs from "node:fs/promises";
-
-import { Agent } from "../bin/index.js";
-
-function user_message(session_id, index) {
-  return {
-    id: `u:${index}`,
-    role: "user",
-    metadata: {
-      v: 1,
-      ts: index,
-      sessionId: session_id,
-      source: "ingress",
-    },
-    parts: [{ type: "text", text: `user ${index}` }],
-  };
-}
-
-function assistant_message(session_id, index) {
-  return {
-    id: `a:${index}`,
-    role: "assistant",
-    metadata: {
-      v: 1,
-      ts: index,
-      sessionId: session_id,
-      source: "egress",
-    },
-    parts: [{ type: "text", text: `assistant ${index}` }],
-  };
-}
-
-function compact_summary(session_id, archive_id, text) {
-  return {
-    id: `summary:${archive_id}`,
-    role: "assistant",
-    metadata: {
-      v: 1,
-      ts: 1000,
-      sessionId: session_id,
-      source: "compact",
-      kind: "summary",
-      archiveId: archive_id,
-      sourceRange: {
-        fromId: "start",
-        toId: "end",
-        count: 2,
-      },
-    },
-    parts: [{ type: "text", text }],
-  };
-}
-
-async function write_jsonl(file_path, messages) {
-  await fs.mkdir(path.dirname(file_path), { recursive: true });
-  await fs.writeFile(
-    file_path,
-    messages.map((message) => JSON.stringify(message)).join("\n") + "\n",
-    "utf8",
-  );
-}
-
-async function write_archive(file_path, session_id, messages) {
-  await fs.mkdir(path.dirname(file_path), { recursive: true });
-  await fs.writeFile(
-    file_path,
-    JSON.stringify(
-      {
-        v: 1,
-        sessionId: session_id,
-        archivedAt: Date.now(),
-        messages,
-      },
-      null,
-      2,
-    ),
-    "utf8",
-  );
-}
-
-test("session.records hides compact summary and reads archive layers by archive_id", async () => {
-  const agent_path = await fs.mkdtemp(
-    path.join(os.tmpdir(), "downcity-agent-history-archive-"),
-  );
-  const agent = new Agent({
-    id: "history_archive_agent",
-    path: agent_path,
-  });
-  const session = await agent.sessions.create({
-    sessionId: "history_archive_session",
-  });
-
-  const messages_dir = path.join(
-    agent_path,
-    ".downcity",
-    "agents",
-    encodeURIComponent("history_archive_agent"),
-    "sessions",
-    encodeURIComponent(session.id),
-    "messages",
-  );
-  const messages_path = path.join(messages_dir, "messages.jsonl");
-  const archive_dir = path.join(messages_dir, "archive");
-
-  try {
-    await write_jsonl(messages_path, [
-      compact_summary(session.id, "compact-B", "summary B"),
-      user_message(session.id, 31),
-      assistant_message(session.id, 32),
-    ]);
-    await write_archive(path.join(archive_dir, "compact-B.json"), session.id, [
-      compact_summary(session.id, "compact-A", "summary A"),
-      user_message(session.id, 16),
-      assistant_message(session.id, 17),
-    ]);
-    await write_archive(path.join(archive_dir, "compact-A.json"), session.id, [
-      user_message(session.id, 1),
-      assistant_message(session.id, 2),
-    ]);
-
-    const current_page = await session.records({
-      limit: 1,
-    });
-    assert.equal(current_page.total, 2);
-    assert.equal(current_page.has_more, true);
-    assert.equal(current_page.next_cursor, "1");
-    assert.equal(current_page.archive_id, undefined);
-    assert.equal(current_page.previous_archive_id, "compact-B");
-    assert.deepEqual(
-      current_page.items.map((message) => message.id),
-      ["u:31"],
-    );
-
-    const next_current_page = await session.records({
-      cursor: current_page.next_cursor,
-    });
-    assert.equal(next_current_page.has_more, false);
-    assert.deepEqual(
-      next_current_page.items.map((message) => message.id),
-      ["a:32"],
-    );
-
-    const previous_page = await session.records({
-      archive_id: current_page.previous_archive_id,
-    });
-    assert.equal(previous_page.archive_id, "compact-B");
-    assert.equal(previous_page.previous_archive_id, "compact-A");
-    assert.equal(previous_page.total, 2);
-    assert.deepEqual(
-      previous_page.items.map((message) => message.id),
-      ["u:16", "a:17"],
-    );
-
-    const oldest_page = await session.records({
-      archive_id: previous_page.previous_archive_id,
-    });
-    assert.equal(oldest_page.archive_id, "compact-A");
-    assert.equal(oldest_page.previous_archive_id, undefined);
-    assert.deepEqual(
-      oldest_page.items.map((message) => message.id),
-      ["u:1", "a:2"],
-    );
-
-    const timeline_page = await session.records({
-      view: "timeline",
-      archive_id: "compact-B",
-    });
-    assert.deepEqual(
-      timeline_page.items.map((event) => event.text),
-      ["user 16", "assistant 17"],
-    );
-  } finally {
-    await agent.dispose();
-  }
-});

package/src/session/SessionEventMapper.ts

@@ -1,148 +0,0 @@
-/**
- * Session 事件映射辅助。
- *
- * 关键点（中文）
- * - 把底层 AI SDK `UIMessageChunk` 归一到内部 `InternalUiChunkEvent`。
- * - 再把内部 chunk 事件转换为 `session.subscribe()` 可见的 Session 事件。
- */
-
-import type { UIMessageChunk } from "ai";
-import type { JsonValue } from "@/types/common/Json.js";
-import type { AgentSessionEvent } from "@/types/sdk/AgentSessionEvent.js";
-import type { InternalUiChunkEvent } from "@/types/sdk/InternalUiChunkEvent.js";
-
-function toJsonValue(value: unknown): JsonValue {
-  if (value === undefined) return null;
-  if (value === null) return null;
-  if (
-    typeof value === "string" ||
-    typeof value === "number" ||
-    typeof value === "boolean"
-  ) {
-    return value;
-  }
-  try {
-    return JSON.parse(JSON.stringify(value)) as JsonValue;
-  } catch {
-    return String(value);
-  }
-}
-
-/**
- * 把单个 UI chunk 映射为内部 chunk 事件。
- */
-export function mapUiMessageChunkToAgentEvent(
-  chunk: UIMessageChunk,
-): InternalUiChunkEvent | null {
-  switch (chunk.type) {
-    case "text-delta":
-      return {
-        type: "text-delta",
-        text: chunk.delta,
-      };
-    case "reasoning-delta":
-      return {
-        type: "reasoning-delta",
-        text: chunk.delta,
-      };
-    case "tool-input-available":
-      return {
-        type: "tool-call",
-        toolCallId: chunk.toolCallId,
-        toolName: chunk.toolName,
-        args: toJsonValue(chunk.input),
-      };
-    case "tool-output-available":
-      return {
-        type: "tool-result",
-        toolCallId: chunk.toolCallId,
-        toolName: "unknown",
-        result: toJsonValue(chunk.output),
-      };
-    case "tool-output-error":
-      return {
-        type: "tool-error",
-        toolCallId: chunk.toolCallId,
-        toolName: "unknown",
-        error: chunk.errorText,
-      };
-    case "tool-input-error":
-      return {
-        type: "tool-error",
-        toolCallId: chunk.toolCallId,
-        toolName: chunk.toolName,
-        error: chunk.errorText,
-      };
-    case "finish":
-      return {
-        type: "finish",
-        ...(typeof chunk.finishReason === "string"
-          ? { finishReason: chunk.finishReason }
-          : {}),
-      };
-    case "error":
-      return {
-        type: "error",
-        error: chunk.errorText,
-      };
-    case "abort":
-      return {
-        type: "error",
-        error: String(chunk.reason || "execution aborted"),
-      };
-    default:
-      return null;
-  }
-}
-
-/**
- * 把内部 chunk 事件映射为 Session actor 事件。
- *
- * 关键点（中文）
- * - Session 级事件只保留 turn 维度所需的最小字段。
- * - `finish` 与通用 `error` 由 turn 生命周期统一表达，不在这里直接透出。
- */
-export function mapAgentEventToSessionEvent(params: {
-  /**
-   * 当前内部 chunk 事件。
-   */
-  event: InternalUiChunkEvent;
-  /**
-   * 当前 turn 标识。
-   */
-  turnId: string;
-}): AgentSessionEvent | null {
-  const { event, turnId } = params;
-  switch (event.type) {
-    case "text-delta":
-      return {
-        type: "text-delta",
-        turnId,
-        text: event.text,
-      };
-    case "reasoning-delta":
-      return {
-        type: "reasoning-delta",
-        turnId,
-        text: event.text,
-      };
-    case "tool-call":
-      return {
-        type: "tool-call",
-        turnId,
-        toolCallId: event.toolCallId,
-        toolName: event.toolName,
-        args: event.args,
-      };
-    case "tool-result":
-      return {
-        type: "tool-result",
-        turnId,
-        toolCallId: event.toolCallId,
-        toolName: event.toolName,
-        result: event.result,
-      };
-    default:
-      return null;
-  }
-}

package/src/types/sdk/AgentSessionEvent.ts

@@ -1,370 +0,0 @@
-/**
- * Agent Session 事件类型定义。
- *
- * 关键点（中文）
- * - `subscribe()` 暴露的是 session 级长期事件序列，而不是单次执行的局部结果。
- * - 事件只表达“当前 turn 正在发生什么”，不负责历史回放。
- */
-
-import type { JsonValue } from "@/types/common/Json.js";
-import type { SessionAssistantStepVisibility } from "@/executor/types/SessionRun.js";
-import type { AgentSessionActionEvent } from "@/types/sdk/AgentSessionAction.js";
-
-/**
- * 单个 turn 开始事件。
- */
-export interface AgentSessionTurnStartEvent {
-  /**
-   * 当前事件类型。
-   */
-  type: "turn-start";
-
-  /**
-   * 当前 turn 的稳定标识。
-   *
-   * 说明（中文）
-   * - 同一个 turn 内的全部增量事件都会复用这个 turnId。
-   * - 当 Session 排队进入下一轮时，会生成新的 turnId。
-   */
-  turnId: string;
-}
-
-/**
- * 普通文本增量事件。
- */
-export interface AgentSessionTextDeltaEvent {
-  /**
-   * 当前事件类型。
-   */
-  type: "text-delta";
-
-  /**
-   * 当前文本所属 turn。
-   */
-  turnId: string;
-
-  /**
-   * 当前这次新增的可见文本片段。
-   */
-  text: string;
-}
-
-/**
- * reasoning 文本增量事件。
- */
-export interface AgentSessionReasoningDeltaEvent {
-  /**
-   * 当前事件类型。
-   */
-  type: "reasoning-delta";
-
-  /**
-   * 当前 reasoning 所属 turn。
-   */
-  turnId: string;
-
-  /**
-   * 当前这次新增的 reasoning 文本片段。
-   */
-  text: string;
-}
-
-/**
- * 工具调用事件。
- */
-export interface AgentSessionToolCallEvent {
-  /**
-   * 当前事件类型。
-   */
-  type: "tool-call";
-
-  /**
-   * 当前工具调用所属 turn。
-   */
-  turnId: string;
-
-  /**
-   * 当前工具调用唯一标识。
-   */
-  toolCallId: string;
-
-  /**
-   * 当前工具名称。
-   */
-  toolName: "shell_exec" | "shell_session" | "shell_write" | string;
-
-  /**
-   * 当前工具输入参数。
-   */
-  args: JsonValue;
-}
-
-/**
- * 工具结果事件。
- */
-export interface AgentSessionToolResultEvent {
-  /**
-   * 当前事件类型。
-   */
-  type: "tool-result";
-
-  /**
-   * 当前工具结果所属 turn。
-   */
-  turnId: string;
-
-  /**
-   * 当前工具调用唯一标识。
-   */
-  toolCallId: string;
-
-  /**
-   * 当前工具名称。
-   */
-  toolName: "shell_exec" | "shell_session" | "shell_write" | string;
-
-  /**
-   * 当前工具输出结果。
-   */
-  result: JsonValue;
-}
-
-/**
- * 工具审批请求事件。
- */
-export interface AgentSessionToolApprovalRequestEvent {
-  /**
-   * 当前事件类型。
-   */
-  type: "tool-approval-request";
-
-  /**
-   * 当前审批所属 turn。
-   */
-  turnId: string;
-
-  /**
-   * 当前工具调用唯一标识。
-   */
-  toolCallId: string;
-
-  /**
-   * 当前工具名称。
-   */
-  toolName: "shell_exec" | "shell_session" | "shell_write" | string;
-
-  /**
-   * 当前审批请求唯一标识。
-   */
-  approvalId: string;
-
-  /**
-   * 请求执行的 sandbox 模式。
-   */
-  sandbox: "unrestricted";
-
-  /**
-   * 请求执行的命令文本。
-   *
-   * 说明（中文）
-   * - `shell_exec` / `shell_session` start 中是命令文本。
-   * - `shell_write` 中是 stdin 写入内容，用于兼容内部审批展示。
-   */
-  cmd: string;
-
-  /**
-   * 当前审批动作类型。
-   */
-  operation?: "exec" | "start" | "write";
-
-  /**
-   * 关联 shell_id；session 输入审批时用于标识目标会话。
-   */
-  shellId?: string;
-
-  /**
-   * stdin 写入内容预览；仅 session 输入审批存在。
-   */
-  inputPreview?: string;
-
-  /**
-   * stdin 写入字符数；仅 session 输入审批存在。
-   */
-  inputChars?: number;
-
-  /**
-   * 命令执行目录。
-   */
-  cwd: string;
-
-  /**
-   * Agent 给用户展示的申请原因。
-   */
-  reason: string;
-
-  /**
-   * 当前审批状态。
-   */
-  status: "pending";
-}
-
-/**
- * 工具审批结果事件。
- */
-export interface AgentSessionToolApprovalResultEvent {
-  /**
-   * 当前事件类型。
-   */
-  type: "tool-approval-result";
-
-  /**
-   * 当前审批所属 turn。
-   */
-  turnId: string;
-
-  /**
-   * 当前工具调用唯一标识。
-   */
-  toolCallId: string;
-
-  /**
-   * 当前工具名称。
-   */
-  toolName: "shell_exec" | "shell_session" | "shell_write" | string;
-
-  /**
-   * 当前审批请求唯一标识。
-   */
-  approvalId: string;
-
-  /**
-   * 用户最终决策。
-   */
-  decision: "approved" | "denied" | "expired";
-}
-
-/**
- * assistant step 完成事件。
- */
-export interface AgentSessionAssistantStepEvent {
-  /**
-   * 当前事件类型。
-   */
-  type: "assistant-step";
-
-  /**
-   * 当前 assistant step 所属 turn。
-   */
-  turnId: string;
-
-  /**
-   * 当前 step 文本。
-   */
-  text: string;
-
-  /**
-   * 当前 step 序号（从 1 开始）。
-   */
-  stepIndex: number;
-
-  /**
-   * 当前 step 可见性。
-   */
-  visibility?: SessionAssistantStepVisibility;
-}
-
-/**
- * Session 标题更新事件。
- */
-export interface AgentSessionTitleEvent {
-  /**
-   * 当前事件类型。
-   */
-  type: "session-title";
-
-  /**
-   * 当前 session 唯一标识。
-   */
-  sessionId: string;
-
-  /**
-   * 当前 session 最新标题。
-   *
-   * 说明（中文）
-   * - 标题已持久化到 session meta。
-   * - 新 session 通常在首条 user message 落盘后生成标题。
-   */
-  title: string;
-}
-
-/**
- * 单个 turn 完成事件。
- */
-export interface AgentSessionTurnFinishEvent {
-  /**
-   * 当前事件类型。
-   */
-  type: "turn-finish";
-
-  /**
-   * 当前已完成 turn 的稳定标识。
-   */
-  turnId: string;
-
-  /**
-   * 当前 turn 最终可见文本。
-   */
-  text: string;
-
-  /**
-   * 当前 turn 是否成功结束。
-   */
-  success: boolean;
-
-  /**
-   * 当前 turn 失败时的错误文本。
-   */
-  error?: string;
-}
-
-/**
- * Session 级错误事件。
- */
-export interface AgentSessionErrorEvent {
-  /**
-   * 当前事件类型。
-   */
-  type: "error";
-
-  /**
-   * 当前错误文本。
-   */
-  message: string;
-}
-
-/**
- * Session 订阅可见事件联合类型。
- */
-export type AgentSessionEvent =
-  | AgentSessionTurnStartEvent
-  | AgentSessionTextDeltaEvent
-  | AgentSessionReasoningDeltaEvent
-  | AgentSessionToolCallEvent
-  | AgentSessionToolResultEvent
-  | AgentSessionToolApprovalRequestEvent
-  | AgentSessionToolApprovalResultEvent
-  | AgentSessionAssistantStepEvent
-  | AgentSessionTitleEvent
-  | AgentSessionActionEvent
-  | AgentSessionTurnFinishEvent
-  | AgentSessionErrorEvent;
-
-/**
- * Session 事件订阅回调。
- */
-export type AgentSessionSubscriber = (event: AgentSessionEvent) => void;
-
-/**
- * 取消 Session 订阅的返回函数。
- */
-export type AgentSessionUnsubscribe = () => void;