@springbrand/agent-runtime 0.1.0

package/src/pi/session/index.ts

@@ -0,0 +1,24 @@
+import type { SqlTaggedTemplate } from "agents/chat";
+import {
+  PiTranscriptStore,
+  appendSessionMessageSync,
+  clearSessionSync,
+  moveSessionLeafSync,
+} from "./storage";
+
+export const piSession = Object.freeze({
+  appendMessage: appendSessionMessageSync,
+  clear: clearSessionSync,
+  /**
+   * 建库并返回回合事实源。
+   *
+   * 这里不再构造 pi 的 `Session` —— 会话所有权归这个 Durable Object,
+   * pi 只在需要压缩时被当作纯函数调用。理由见 `PiTranscriptStore` 的注释。
+   */
+  create(sql: SqlTaggedTemplate) {
+    return { store: new PiTranscriptStore(sql) };
+  },
+  moveLeaf: moveSessionLeafSync,
+});
+
+export * from "./storage";

package/src/pi/session/storage.ts

@@ -0,0 +1,353 @@
+import {
+  SessionError,
+  uuidv7,
+  type AgentMessage,
+  type CompactionEntry,
+  type SessionMetadata,
+  type SessionTreeEntry,
+} from "@earendil-works/pi-agent-core";
+import type { SqlTaggedTemplate } from "agents/chat";
+
+type EntryRow = {
+  id: string;
+  body: string;
+};
+
+type LeafRow = {
+  id: string;
+  type: string;
+  target_id: string | null;
+};
+
+function errorCause(error: unknown): Error {
+  return error instanceof Error ? error : new Error(String(error));
+}
+
+function parseEntry(row: EntryRow): SessionTreeEntry {
+  try {
+    return JSON.parse(row.body) as SessionTreeEntry;
+  } catch (error) {
+    throw new SessionError(
+      "invalid_entry",
+      `Invalid SQLite session entry ${row.id}`,
+      errorCause(error),
+    );
+  }
+}
+
+function sessionEntryTargetId(entry: SessionTreeEntry): string | null {
+  return entry.type === "leaf" || entry.type === "label"
+    ? entry.targetId
+    : null;
+}
+
+function getEntrySync(
+  sql: SqlTaggedTemplate,
+  id: string,
+): SessionTreeEntry | undefined {
+  const row = sql<EntryRow>`
+    SELECT id, body
+    FROM pi_session_entries
+    WHERE id = ${id}
+  `[0];
+  return row ? parseEntry(row) : undefined;
+}
+
+function getLeafIdSync(sql: SqlTaggedTemplate): string | null {
+  const row = sql<LeafRow>`
+    SELECT id, type, target_id
+    FROM pi_session_entries
+    ORDER BY seq DESC
+    LIMIT 1
+  `[0];
+  if (!row) return null;
+
+  const leafId = row.type === "leaf" ? row.target_id : row.id;
+  if (leafId !== null && !getEntrySync(sql, leafId)) {
+    throw new SessionError(
+      "invalid_session",
+      `Entry ${leafId} not found`,
+    );
+  }
+  return leafId;
+}
+
+function appendEntrySync(
+  sql: SqlTaggedTemplate,
+  entry: SessionTreeEntry,
+): boolean {
+  const before = sql<{ count: number }>`
+    SELECT COUNT(*) AS count
+    FROM pi_session_entries
+    WHERE id = ${entry.id}
+  `[0]?.count ?? 0;
+  if (before > 0) return false;
+
+  sql`
+    INSERT INTO pi_session_entries (
+      id, type, parent_id, target_id, body
+    ) VALUES (
+      ${entry.id},
+      ${entry.type},
+      ${entry.parentId},
+      ${sessionEntryTargetId(entry)},
+      ${JSON.stringify(entry)}
+    )
+  `;
+  return true;
+}
+
+/**
+ * 给 Durable Object 的 `transactionSync` 调用方用的同步写原语。
+ *
+ * 必须是同步的:admission 走在 DO 的同步事务里,任何 await 都会破坏那次事务的原子性。
+ */
+export function appendSessionMessageSync(
+  sql: SqlTaggedTemplate,
+  input: {
+    id: string;
+    message: AgentMessage;
+    submissionId?: string;
+    createdAt?: number;
+  },
+): boolean {
+  const timestamp = new Date(
+    input.createdAt ??
+      ("timestamp" in input.message &&
+        typeof input.message.timestamp === "number"
+        ? input.message.timestamp
+        : Date.now()),
+  ).toISOString();
+  const inserted = appendEntrySync(sql, {
+    type: "message",
+    id: input.id,
+    parentId: getLeafIdSync(sql),
+    timestamp,
+    message: input.message,
+  });
+  if (inserted && input.submissionId) {
+    sql`
+      INSERT INTO pi_session_message_submission (
+        message_id, submission_id
+      ) VALUES (
+        ${input.id}, ${input.submissionId}
+      )
+    `;
+  }
+  return inserted;
+}
+
+export function moveSessionLeafSync(
+  sql: SqlTaggedTemplate,
+  targetId: string | null,
+): void {
+  if (targetId !== null && !getEntrySync(sql, targetId)) {
+    throw new SessionError("not_found", `Entry ${targetId} not found`);
+  }
+  const id = uuidv7();
+  if (!appendEntrySync(sql, {
+    type: "leaf",
+    id,
+    parentId: getLeafIdSync(sql),
+    timestamp: new Date().toISOString(),
+    targetId,
+  })) {
+    throw new SessionError(
+      "storage",
+      `Session entry ${id} already exists`,
+    );
+  }
+}
+
+export function clearSessionSync(sql: SqlTaggedTemplate): void {
+  sql`DELETE FROM pi_session_message_submission`;
+  sql`DELETE FROM pi_session_entries`;
+}
+
+/**
+ * 回合事实源:这个 Durable Object 自己拥有的会话记录流。
+ *
+ * ## 为什么不再 implements pi 的 SessionStorage
+ *
+ * 我们只用到 branch / entry / appendCompaction 三件事,却曾为此实现一个十方法接口,
+ * 并把「一个回合到底长什么样」的定义权交给了 pi 的 **harness 层** —— 而 `SessionStorage`
+ * 住在 `dist/harness/types.d.ts`,是 pi 给本地 CLI 用的那一层,不是 pi 内核的必需品
+ * (`AgentOptions` 里根本没有 session 字段)。它也是 pi 发版最勤的一层:
+ * 0.81.0 已经把 `getPathToRoot` 改名成 `getPathToRootOrCompaction` 并新增两个必填方法,
+ * `[Unreleased]` 又要把整个 `SessionStorage` 换成 `SessionRepository` + caller-owned
+ * `SessionStore`。**实现别人的接口 = 别人改语义时编译器不会告诉我们。**
+ *
+ * 现在语义由我们定、写在我们的测试里(见 storage.test.ts 的差分对拍);pi 只作为
+ * 纯函数被调用(`prepareCompaction` / `compact` / `buildSessionContext`),
+ * 那些改签名编译器一定会报。
+ *
+ * ## 会话模型(读代码前先看这三条,否则会误改)
+ *
+ * 1. **leaf 是派生的,不是存的**:seq 最大的那一行;若它是 `leaf` 标记条目,则跟随它的
+ *    `targetId`。所以**追加任何 entry 都会自动成为新 leaf**,不需要额外「移动」。
+ * 2. **回退 leaf 靠追加标记**:`moveSessionLeafSync` append 一条 `leaf` 类型条目指向目标,
+ *    表本身始终 append-only,从不改写历史行。
+ * 3. **`leaf` 标记永远不会成为任何条目的 parent**:新条目的 parentId 取自
+ *    `getLeafIdSync()`,那已经是解析过标记之后的真实条目 id。所以按 parentId 上溯时
+ *    不会走进标记里。
+ */
+export class PiTranscriptStore {
+  constructor(
+    private readonly sql: SqlTaggedTemplate,
+    metadata?: SessionMetadata,
+  ) {
+    this.sql`
+      CREATE TABLE IF NOT EXISTS pi_session_metadata (
+        singleton INTEGER PRIMARY KEY CHECK (singleton = 1),
+        id TEXT NOT NULL,
+        created_at TEXT NOT NULL
+      )
+    `;
+    this.sql`
+      CREATE TABLE IF NOT EXISTS pi_session_entries (
+        seq INTEGER PRIMARY KEY AUTOINCREMENT,
+        id TEXT NOT NULL UNIQUE,
+        type TEXT NOT NULL,
+        parent_id TEXT,
+        target_id TEXT,
+        body TEXT NOT NULL
+      )
+    `;
+    this.sql`
+      CREATE INDEX IF NOT EXISTS pi_session_entries_type
+      ON pi_session_entries(type)
+    `;
+    this.sql`
+      CREATE INDEX IF NOT EXISTS pi_session_entries_target
+      ON pi_session_entries(type, target_id, seq)
+    `;
+    this.sql`
+      CREATE TABLE IF NOT EXISTS pi_session_message_submission (
+        message_id TEXT PRIMARY KEY,
+        submission_id TEXT NOT NULL
+      )
+    `;
+    this.sql`
+      CREATE INDEX IF NOT EXISTS pi_session_message_submission_id
+      ON pi_session_message_submission(submission_id)
+    `;
+    const initial = metadata ?? {
+      id: uuidv7(),
+      createdAt: new Date().toISOString(),
+    };
+    this.sql`
+      INSERT OR IGNORE INTO pi_session_metadata (
+        singleton, id, created_at
+      ) VALUES (
+        1, ${initial.id}, ${initial.createdAt}
+      )
+    `;
+  }
+
+  /**
+   * 从当前 leaf 上溯到 root 的完整路径。
+   *
+   * 用一条递归 CTE 取全路径。旧实现是 while 循环里每个祖先打一次 SELECT ——
+   * canonicalMessages / storedMessages 各调一次,等于每次刷 UI 都是 O(消息数) 次 SQL。
+   * JOIN 落在 `id` 上(UNIQUE,有索引),不需要为 parent_id 另建索引。
+   */
+  branch(): SessionTreeEntry[] {
+    const leafId = getLeafIdSync(this.sql);
+    if (leafId === null) return [];
+
+    const rows = this.sql<EntryRow>`
+      WITH RECURSIVE path(id, body, parent_id) AS (
+        SELECT id, body, parent_id
+        FROM pi_session_entries
+        WHERE id = ${leafId}
+        UNION ALL
+        SELECT e.id, e.body, e.parent_id
+        FROM pi_session_entries e
+        JOIN path p ON e.id = p.parent_id
+      )
+      SELECT id, body FROM path
+    `;
+    if (rows.length === 0) {
+      throw new SessionError("not_found", `Entry ${leafId} not found`);
+    }
+    // CTE 从 leaf 往上产出,这里翻成 root→leaf 与旧的 unshift 顺序一致。
+    const path = rows.map(parseEntry).reverse();
+    // 断链检测:旧实现在父条目缺失时抛 invalid_session,而 CTE 遇到断点只会静默停止
+    // 递归。顶端条目的 parentId 必须为空,否则说明中间有一条祖先不见了。
+    const root = path[0];
+    if (root?.parentId) {
+      throw new SessionError(
+        "invalid_session",
+        `Entry ${root.parentId} not found`,
+      );
+    }
+    return path;
+  }
+
+  entry(id: string): SessionTreeEntry | undefined {
+    return getEntrySync(this.sql, id);
+  }
+
+  /**
+   * 追加一条压缩条目,整对象写入。
+   *
+   * 旧路径是把 assembly 侧已经造好的完整 CompactionEntry 拆成 5 个位置参数喂给
+   * pi 的 `Session.appendCompaction` —— pi 0.81 把它加到 7 个参数(usage / retainedTail)
+   * 之后,多出来的两个会被静默丢掉,编译器不报。整对象写入让这类失败模式在结构上
+   * 不存在:调用方给什么就落什么。
+   *
+   * id / parentId / timestamp 由这里补齐,语义与 pi 的 `appendTypedEntry` 一致
+   * (parentId 取当前 leaf;追加后本条自动成为新 leaf)。
+   */
+  appendCompaction(
+    entry: Omit<CompactionEntry, "id" | "parentId" | "timestamp">,
+  ): string {
+    const id = this.createEntryId();
+    const appended = appendEntrySync(this.sql, {
+      ...entry,
+      id,
+      parentId: getLeafIdSync(this.sql),
+      timestamp: new Date().toISOString(),
+    });
+    if (!appended) {
+      throw new SessionError("storage", `Session entry ${id} already exists`);
+    }
+    return id;
+  }
+
+  /**
+   * 按类型取条目。生产路径无消费者,但压缩相关测试靠它断言「压缩条目真的落库了」,
+   * 是那条行为契约的观测口。
+   */
+  findEntries<TType extends SessionTreeEntry["type"]>(
+    type: TType,
+  ): Array<Extract<SessionTreeEntry, { type: TType }>> {
+    return this.sql<EntryRow>`
+      SELECT id, body
+      FROM pi_session_entries
+      WHERE type = ${type}
+      ORDER BY seq ASC
+    `.map(parseEntry) as Array<Extract<SessionTreeEntry, { type: TType }>>;
+  }
+
+  /** 全量条目(含 leaf 标记),按写入顺序。仅供测试观测整棵树用。 */
+  entries(): SessionTreeEntry[] {
+    return this.sql<EntryRow>`
+      SELECT id, body
+      FROM pi_session_entries
+      ORDER BY seq ASC
+    `.map(parseEntry);
+  }
+
+  /**
+   * 短 id,与 pi 的 `createEntryId` 同规则(uuidv7 尾 8 位 + 碰撞重试)。
+   * 必须保持一致:压缩条目的 firstKeptEntryId 引用的就是这种 id。
+   */
+  private createEntryId(): string {
+    for (let attempt = 0; attempt < 100; attempt += 1) {
+      const id = uuidv7().slice(-8);
+      if (!getEntrySync(this.sql, id)) return id;
+    }
+    return uuidv7();
+  }
+}

package/src/pi/tool/ai-adapter.ts

@@ -0,0 +1,100 @@
+// 本文件把 ai-sdk Tool 转成 Pi AgentTool。
+// `@cloudflare/think`、Agents Skills 和 Workspace 等上游工厂生成 ai-sdk Tool 时调用这个边界。
+// 转换只保留在这里，才能让后续治理和结算始终看到同一种 AgentTool 结果；核心术语见 `../../index.ts` 入口说明。
+
+import type {
+  AgentTool,
+  AgentToolResult,
+} from "@earendil-works/pi-agent-core";
+import { asSchema, type Tool as AiTool } from "ai";
+import { serializeOutput } from "../../lib/artifacts";
+
+/** 控制一个 ai-sdk Tool 如何投影到 Pi AgentTool。 */
+export interface AiToolAdapterOptions {
+  /** AgentTool requires a label; ai-sdk tools have no equivalent field. */
+  readonly label?: string;
+  /** Overrides the upstream description (used for `[ext] ` prefixes). */
+  readonly description?: string;
+  /** Wraps the raw ai-sdk return value before it becomes `details`. */
+  readonly details?: (output: unknown) => unknown;
+}
+
+// 把 ai-sdk Tool 的静态或动态 description 解析成文本。
+// `aiToolToPi()` 在没有显式 description 覆盖时调用它。
+// 当前 ai@7 允许 description 是函数，所以适配器在无请求上下文中安全求值，失败时退回空文本而不阻断工具组装。
+function resolveDescription(tool: AiTool): string {
+  const raw = (tool as { description?: unknown }).description;
+  if (typeof raw === "function") {
+    try {
+      return String(
+        (raw as (options: { context: undefined }) => unknown)({
+          context: undefined,
+        }) ?? "",
+      );
+    } catch {
+      return "";
+    }
+  }
+  return typeof raw === "string" ? raw : "";
+}
+
+/**
+ * 把一个可执行的 ai-sdk Tool 转成 Pi AgentTool。
+ *
+ * Workspace、Skill 和其他 ai-sdk 工具工厂在把候选项交给 `compilePiTools()` 前调用。
+ *
+ * 实现必须在一处同时对齐 schema、execute 参数和结果形状，否则 Pi 的校验、取消信号和 artifact 计量会绕过统一工具边界。
+ *
+ * @remarks `inputSchema` 经 ai@7 `asSchema()` 转为 JSON Schema；原始返回值保留在 `details` 中，供 `resultPressure()` 识别 `artifact_ref`。
+ */
+export function aiToolToPi(
+  name: string,
+  tool: AiTool,
+  options: AiToolAdapterOptions = {},
+): AgentTool<any, unknown> {
+  const inputSchema = (tool as { inputSchema?: unknown }).inputSchema;
+  const parameters = asSchema(
+    inputSchema as Parameters<typeof asSchema>[0],
+  ).jsonSchema as AgentTool["parameters"];
+  const execute = (tool as { execute?: unknown }).execute;
+  if (typeof execute !== "function") {
+    throw new Error(`ai tool is not executable: ${name}`);
+  }
+
+  return {
+    name,
+    label: options.label
+      ?? (tool as { title?: string }).title
+      ?? name,
+    description: options.description ?? resolveDescription(tool),
+    parameters,
+    // 用 Pi 的调用签名执行底层 ai-sdk Tool 并返回 AgentToolResult。
+    // Pi 工具循环选中这个适配后的工具时调用，参数和 AbortSignal 被转交到 ai-sdk execute 上下文。
+    // ai-sdk 结果既要序列化成模型可见文本又要原样保留 details，不能只返回其中一份。
+    async execute(
+      toolCallId: string,
+      params: unknown,
+      signal?: AbortSignal,
+    ): Promise<AgentToolResult<unknown>> {
+      const raw = await (execute as (
+        input: unknown,
+        context: {
+          toolCallId: string;
+          messages: never[];
+          abortSignal?: AbortSignal;
+          context: undefined;
+        },
+      ) => unknown)(params, {
+        toolCallId,
+        messages: [],
+        abortSignal: signal,
+        context: undefined,
+      });
+      const details = options.details ? options.details(raw) : raw;
+      return {
+        content: [{ type: "text", text: serializeOutput(details).text }],
+        details,
+      };
+    },
+  };
+}

package/src/pi/tool/base.ts

@@ -0,0 +1,110 @@
+import type {
+  AgentTool,
+  AgentToolResult,
+} from "@earendil-works/pi-agent-core";
+import { Type, type TSchema } from "@earendil-works/pi-ai";
+import { serializeOutput } from "../../lib/artifacts";
+import type { PiToolCandidate } from "./compiler";
+import { webSearchPiToolCandidate } from "./web-search";
+import type { WebSearch } from "./web-search/api";
+
+const askUserParameters = Type.Object({
+  question: Type.String({
+    description: "The question to put to the user.",
+  }),
+  options: Type.Array(Type.String(), {
+    minItems: 2,
+    maxItems: 6,
+    description: "2-6 mutually distinct options for the user to choose from.",
+  }),
+  multiSelect: Type.Optional(Type.Boolean({
+    description:
+      "Whether the user may select more than one option. Defaults to false.",
+  })),
+});
+
+const suggestFollowupsParameters = Type.Object({
+  items: Type.Array(Type.String({
+    description: "A follow-up the user could ask next, phrased as a request.",
+  }), {
+    minItems: 2,
+    maxItems: 4,
+    description: "2-4 concrete, distinct follow-up directions.",
+  }),
+});
+
+const updatePlanParameters = Type.Object({
+  steps: Type.Array(Type.Object({
+    text: Type.String({
+      description: "The step, phrased as a short imperative.",
+    }),
+    status: Type.Union([
+      Type.Literal("pending"),
+      Type.Literal("in_progress"),
+      Type.Literal("done"),
+    ], { description: "Current status of this step." }),
+  }), {
+    description:
+      "The complete, ordered plan. Overwrites any previously reported plan.",
+  }),
+});
+
+function result<T>(details: T): AgentToolResult<T> {
+  return {
+    content: [{ type: "text", text: serializeOutput(details).text }],
+    details,
+  };
+}
+
+function candidate<T extends TSchema>(tool: AgentTool<T>): PiToolCandidate {
+  return {
+    owner: "runtime-base",
+    authorized: true,
+    requiredExecutionLevel: "safe",
+    source: "action",
+    tool,
+  };
+}
+
+/** Runtime-permanent Pi tools, independent of optional Host plugins. */
+export function basePiToolCandidates(
+  webSearch: WebSearch,
+): PiToolCandidate[] {
+  return [
+    candidate({
+      name: "ask_user",
+      label: "Ask user",
+      description:
+        "Ask the user to choose among a small set of options. Call this tool whenever you need the user to make a choice from limited options — do NOT write plain text like 'please pick A / B / C'. After calling this tool, end your turn and wait for the user's reply.",
+      parameters: askUserParameters,
+      async execute() {
+        return result({ asked: true });
+      },
+    }),
+    candidate({
+      name: "suggest_followups",
+      label: "Suggest follow-ups",
+      description:
+        "Offer the user 2-4 optional follow-up directions after completing a substantive task (a report, an analysis, a multi-step job). Call this at most once, and it MUST be the very last thing you do: finish all of your prose FIRST, then call this tool and END the turn immediately — do NOT write any text after calling it. Do NOT call it for small talk, quick answers, or while a task is still in progress.",
+      parameters: suggestFollowupsParameters,
+      async execute(_toolCallId, input) {
+        return result({ noted: true, count: input.items.length });
+      },
+    }),
+    candidate({
+      name: "update_plan",
+      label: "Update plan",
+      description:
+        "Maintain the user-visible plan for the current task. Call this whenever a task involves 2 or more steps, and again every time the plan or a step's status changes. Always pass the FULL plan — it replaces the previous plan entirely (idempotent overwrite), so omitted steps disappear.",
+      parameters: updatePlanParameters,
+      async execute(_toolCallId, input) {
+        return result({
+          ok: true,
+          total: input.steps.length,
+          done: input.steps.filter((step) => step.status === "done").length,
+        });
+      },
+    }),
+    webSearchPiToolCandidate(webSearch),
+  ];
+}