@springbrand/agent-runtime 0.3.0-alpha.2 → 0.3.0-alpha.21

package/src/tools/compiler.ts

@@ -1,327 +0,0 @@
-import type {
-  AgentHarnessTool,
-  AgentTool,
-  AgentToolResult,
-} from "@earendil-works/pi-agent-core";
-import type { ApprovalReceipt } from "../submission/contracts";
-import {
-  boundDurableToolOutput,
-  type BudgetPolicy,
-  spillDurableToolOutput,
-} from "../context/memory/budget/gate";
-import {
-  type ArtifactRef,
-  serializeOutput,
-  type SpillWorkspace,
-} from "../lib/artifacts";
-import {
-  type ExecutionLevel,
-} from "../lib/execution-level";
-
-// 本文件沿用 `../../index.ts` 入口定义的 Tool Candidate 和 Tool Settlement 术语。
-
-// #region Public contracts
-
-/**
- * 声明一个 Tool 的结果由客户端投递，而不是由 `execute()` 产出。
- *
- * 带这个字段的 Tool 会在执行链里 park 住，等宿主经 `respondToolInteraction` 把响应送进来，
- * 再用 `settle` 把响应映射成这次 `toolCallId` 的权威 ToolResult。它的 `execute` 不会被调用。
- *
- * 这是 AI SDK 里「没有 execute 的 user-interaction tool」的等价物；差别是我们 park 住整个 Turn，
- * 而不是让 tool part 悬空到下一次请求 —— 我们的 transcript 是服务端权威的，悬空的 tool_use
- * 会让下一次模型调用非法。
- */
-export interface PiToolInteractionSpec {
-  /** 结合 Tool 输入校验客户端响应体；不通过则拒绝投递，park 保持不变。 */
-  readonly validateResponse: (input: unknown, response: unknown) => boolean;
-  /** 把通过校验的响应映射成 ToolResult；缺省是原样回传。 */
-  readonly settle?: (
-    input: unknown,
-    response: unknown,
-  ) => Omit<AgentToolResult<unknown>, "terminate">;
-}
-
-/** 描述一个尚未进入最终 Tool Surface 和结算包装的 Pi 工具。 */
-export type ToolExposureMode = "direct" | "codemode" | "both";
-
-export interface PiToolCandidate {
-  readonly owner: string;
-  readonly tool: AgentTool<any, any>;
-  /** @internal Send the complete schema but hide it until provider Tool Search finds it. */
-  readonly deferLoading?: true;
-  /** Omitted means visible both directly and through Code Mode. */
-  readonly exposureMode?: ToolExposureMode;
-  /** Conservative maximum used in the stable Runtime descriptor. */
-  readonly requiredExecutionLevel: ExecutionLevel;
-  /** Trusted parameter-level policy, evaluated before approval or dispatch. */
-  readonly requiredExecutionLevelForInput?: (
-    input: unknown,
-  ) => ExecutionLevel | Promise<ExecutionLevel>;
-  /**
-   * 无条件需要人来决定：不看执行档位矩阵，每次调用都 park 出审批。
-   *
-   * 档位差是「够不够格自己跑」，不是「该不该问人」。花用户钱、改变账户
-   * 状态这类工具，一旦 Agent 档位被 `allow_level` 永久拉高就会静默执行，
-   * 那是失效不是降级。`deny` 仍然优先，被 deny 的工具根本不会注入。
-   */
-  readonly alwaysRequiresApproval?: boolean;
-  /** Recovery may replay this Tool Call only when the candidate guarantees convergence. Omitted means non-idempotent. */
-  readonly retry?: "idempotent" | "non-idempotent";
-  readonly summary?: string;
-  readonly source?: ApprovalReceipt["source"];
-  readonly interaction?: PiToolInteractionSpec;
-  /** Large payloads spill by default; protocol-shaped results opt into structure. */
-  readonly outputBudget?: BudgetPolicy;
-}
-
-export interface CompileHarnessToolsOptions {
-  readonly workspace?: SpillWorkspace;
-  /** Recheck live authorization at the effect boundary, including safe replay. */
-  readonly authorize?: (
-    candidate: PiToolCandidate,
-    args: unknown,
-    invocation: { readonly toolCallId: string; readonly signal: AbortSignal },
-  ) => void | Promise<void>;
-  /** Return an already decided interaction result without invoking the handler. */
-  readonly resolveReplay?: (
-    candidate: PiToolCandidate,
-    toolCallId: string,
-    args: unknown,
-  ) => AgentToolResult<unknown> | undefined | Promise<AgentToolResult<unknown> | undefined>;
-  /** Optional business projection; Pi remains the authoritative Tool result. */
-  readonly onSettlement?: (
-    call: SettledPiToolCall,
-  ) => void | Promise<void>;
-}
-
-/** 描述一次已进入持久化结算边界的 Pi 工具调用。 */
-export interface SettledPiToolCall {
-  readonly toolCallId: string;
-  readonly toolName: string;
-  readonly args: unknown;
-  readonly result: AgentToolResult<unknown>;
-  readonly isError: boolean;
-  /** Diagnostic-only original error; callers must not persist or expose it. */
-  readonly cause?: unknown;
-  readonly summary?: string;
-  readonly source?: ApprovalReceipt["source"];
-}
-
-// DO SQLite rows also contain arguments and transcript/recovery envelopes.
-// Keep each serialized result below half the 2 MiB row limit.
-const DURABLE_TOOL_RESULT_MAX_BYTES = 1024 * 1024;
-const MEDIA_CAPTION_MAX_CHARS = 4 * 1024;
-
-// #endregion
-
-// #region Governance helpers
-
-// 把任意失败值收敛为可安全显示的简短消息。
-// 受治理工具在工具执行或结算抛错时调用它。
-// 读取错误自身也可能抛错，因此最外层必须保留固定回退文本。
-function errorMessage(error: unknown): string {
-  try {
-    if (error instanceof Error) {
-      return error.message || error.name;
-    }
-    return String(error);
-  } catch {
-    return "Tool execution failed";
-  }
-}
-
-// Most Pi adapters keep the original Tool value in details and its serialized
-// model form in one text block. Spill that original once instead of duplicating
-// it inside an AgentToolResult JSON envelope.
-function spillPayload(result: AgentToolResult<unknown>): unknown {
-  const text = result.content.length === 1 && result.content[0]?.type === "text"
-    ? result.content[0].text
-    : undefined;
-  if (text !== undefined && serializeOutput(result.details).text === text) {
-    return result.details;
-  }
-  return result;
-}
-
-function artifactResult(
-  result: AgentToolResult<unknown>,
-  ref: ArtifactRef,
-): AgentToolResult<unknown> {
-  const presentation = result.details !== null && typeof result.details === "object"
-    ? (result.details as Record<string, unknown>).presentation
-    : undefined;
-  let captionRemaining = MEDIA_CAPTION_MAX_CHARS;
-  const mediaContent = result.content.some((part) => part.type !== "text")
-    ? result.content.flatMap((part): AgentToolResult<unknown>["content"] => {
-        if (part.type !== "text") return [part];
-        const text = part.text.slice(0, captionRemaining);
-        captionRemaining -= text.length;
-        return text ? [{ ...part, text }] : [];
-      })
-    : [];
-  return {
-    ...result,
-    content: [{
-      type: "text",
-      text: [
-        ref.note,
-        `Path: ${ref.path}`,
-        `Bytes: ${ref.bytes}`,
-        `Preview:\n${ref.preview}`,
-      ].join("\n"),
-    }, ...mediaContent],
-    details: presentation === undefined ? ref : { ...ref, presentation },
-  };
-}
-
-async function durableResult(
-  result: AgentToolResult<unknown>,
-  candidate: PiToolCandidate,
-  workspace: SpillWorkspace | undefined,
-): Promise<AgentToolResult<unknown>> {
-  const spill = (candidate.outputBudget ?? { kind: "spill" }).kind === "spill";
-  let ref = spill
-    ? await spillDurableToolOutput(spillPayload(result), { workspace })
-    : null;
-  const bounded = ref
-    ? artifactResult(result, ref)
-    : boundDurableToolOutput(result) as AgentToolResult<unknown>;
-  const bytes = new TextEncoder().encode(JSON.stringify(bounded)).byteLength;
-  if (bytes <= DURABLE_TOOL_RESULT_MAX_BYTES) return bounded;
-
-  // Binary blocks cannot be truncated, and this boundary has no image resizer.
-  // Preserve the original where possible and fail before any SQLite write.
-  if (!spill) ref = await spillDurableToolOutput(spillPayload(result), { workspace });
-  throw new Error(
-    `Tool output exceeds the 1 MiB durable result limit (${bytes} bytes). ` +
-    "Return a smaller result, such as lower-resolution images or fewer media items; the original cannot be included inline. " +
-    (ref ? `Original output saved to Workspace: ${ref.path}` : "The original output could not be saved to Workspace."),
-  );
-}
-
-async function untilAborted<T>(
-  signal: AbortSignal | undefined,
-  run: () => T | Promise<T>,
-): Promise<T> {
-  // ponytail: 这会立即释放 Turn，但无法杀死不配合的进程内副作用；需要物理终止的 Tool 必须放进可销毁的隔离执行器。
-  signal?.throwIfAborted();
-  if (!signal) return run();
-  let onAbort!: () => void;
-  const aborted = new Promise<never>((_resolve, reject) => {
-    onAbort = () => reject(
-      signal.reason ?? new DOMException("Aborted", "AbortError"),
-    );
-    signal.addEventListener("abort", onAbort, { once: true });
-  });
-  try {
-    return await Promise.race([run(), aborted]);
-  } finally {
-    signal.removeEventListener("abort", onAbort);
-  }
-}
-
-// #endregion
-
-// #region Governance and compilation
-
-/**
- * Convert the configured candidate surface once at the AgentHarness boundary.
- * Schema, argument preparation, progress, cancellation, replay classification,
- * and output bounds stay attached to the original Tool declaration.
- */
-export function compileHarnessTools(
-  candidates: readonly PiToolCandidate[],
-  options: CompileHarnessToolsOptions = {},
-): AgentHarnessTool<object | undefined>[] {
-  return candidates.map((candidate) => {
-    const source = candidate.tool;
-    const tool = source.constrainedSampling === false
-      ? source
-      : {
-          ...source,
-          constrainedSampling: source.constrainedSampling ?? {
-            type: "json_schema" as const,
-            strict: "prefer" as const,
-          },
-        };
-    return {
-      ...tool,
-      replay: candidate.retry === "idempotent" &&
-          candidate.requiredExecutionLevel === "safe" &&
-          !candidate.alwaysRequiresApproval &&
-          !candidate.requiredExecutionLevelForInput &&
-          !candidate.interaction
-        ? "safe" as const
-        : "never" as const,
-      ...(candidate.deferLoading ? { deferLoading: true as const } : {}),
-      async execute(
-        toolCallId,
-        args,
-        onUpdate,
-        _toolContext,
-        _invocation,
-        context,
-      ) {
-        const signal = context.abortSignal ?? new AbortController().signal;
-        await options.authorize?.(candidate, args, {
-          toolCallId,
-          signal,
-        });
-        const replay = await options.resolveReplay?.(
-          candidate,
-          toolCallId,
-          args,
-        );
-        if (replay) return durableResult(replay, candidate, options.workspace);
-        let result: AgentToolResult<unknown>;
-        try {
-          result = await untilAborted(
-            signal,
-            async () => durableResult(
-              await source.execute(
-                toolCallId,
-                args,
-                signal,
-                (update) => onUpdate(update),
-              ),
-              candidate,
-              options.workspace,
-            ),
-          );
-        } catch (cause) {
-          const message = errorMessage(cause);
-          const failed = boundDurableToolOutput({
-            content: [{ type: "text", text: message }],
-            details: {},
-          }) as AgentToolResult<unknown>;
-          await options.onSettlement?.({
-            toolCallId,
-            toolName: source.name,
-            args,
-            result: failed,
-            isError: true,
-            cause,
-            summary: candidate.summary,
-            source: candidate.source,
-          });
-          throw cause instanceof Error && cause.message === message
-            ? cause
-            : new Error(message, { cause });
-        }
-        await options.onSettlement?.({
-          toolCallId,
-          toolName: source.name,
-          args,
-          result,
-          isError: false,
-          summary: candidate.summary,
-          source: candidate.source,
-        });
-        return result;
-      },
-    } satisfies AgentHarnessTool<object | undefined>;
-  });
-}
-
-// #endregion

package/src/tools/schedule.ts

@@ -1,261 +0,0 @@
-import type {
-  AgentTool,
-  AgentToolResult,
-} from "@earendil-works/pi-agent-core";
-import { Type, type TSchema } from "@earendil-works/pi-ai";
-import type {
-  RuntimeSchedulePort,
-  RuntimeScheduleUpdate,
-} from "../config/ports";
-import type { ScheduleSpec } from "../submission/contracts";
-import { serializeOutput } from "../lib/artifacts";
-import type { PiToolCandidate } from "./compiler";
-
-const scheduleTriggerParameters = Type.Union([
-  Type.Object({
-    kind: Type.Literal("once-in"),
-    seconds: Type.Integer({
-      minimum: 1,
-      description: "Fire once, this many seconds from now.",
-    }),
-  }, { additionalProperties: false }),
-  Type.Object({
-    kind: Type.Literal("once-at"),
-    at: Type.String({
-      description:
-        "Fire once at this absolute UTC ISO time, e.g. 2026-07-20T09:00:00Z.",
-    }),
-  }, { additionalProperties: false }),
-  Type.Object({
-    kind: Type.Literal("cron"),
-    cron: Type.String({
-      description:
-        "Repeat on a standard UTC cron, e.g. '0 9 * * *' = daily 09:00 UTC.",
-    }),
-  }, { additionalProperties: false }),
-  Type.Object({
-    kind: Type.Literal("interval"),
-    seconds: Type.Integer({
-      minimum: 1,
-      description: "Repeat every this many seconds.",
-    }),
-  }, { additionalProperties: false }),
-], { description: "When to fire." });
-
-const scheduleParameters = Type.Object({
-  prompt: Type.String({
-    description:
-      "The standalone instruction to run when the schedule fires. The future turn has no context from this chat, so make it self-contained.",
-  }),
-  trigger: scheduleTriggerParameters,
-  label: Type.String({
-    description:
-      "A short human-readable name for this task (e.g. '每日周报提醒'). Required — it is how the user recognises the task in their schedule list and how they will refer to it when asking you to cancel it later.",
-  }),
-  timezone: Type.Optional(Type.String({
-    description:
-      "IANA timezone the clock times in `trigger` should be interpreted in, e.g. 'Asia/Shanghai'. Pass the user's own timezone whenever they state a wall-clock time. Omit only for delays and intervals. Defaults to UTC.",
-  })),
-}, { additionalProperties: false });
-
-const noParameters = Type.Object({}, { additionalProperties: false });
-const scheduleIdParameters = Type.Object({
-  id: Type.String({
-    description: "The schedule id, as returned by `list_schedules`.",
-  }),
-}, { additionalProperties: false });
-const updateScheduleParameters = Type.Object({
-  id: Type.String({ description: "The exact id returned by `list_schedules`." }),
-  prompt: Type.Optional(Type.String()),
-  trigger: Type.Optional(scheduleTriggerParameters),
-  label: Type.Optional(Type.String()),
-  timezone: Type.Optional(Type.String()),
-}, { additionalProperties: false });
-const changeScheduleAgentParameters = Type.Object({
-  id: Type.String({
-    description: "The exact schedule id returned by `list_schedules`.",
-  }),
-  userAgentId: Type.String({
-    description: "The exact User Agent id selected by the user.",
-  }),
-}, { additionalProperties: false });
-
-function result<T>(details: T): AgentToolResult<T> {
-  return {
-    content: [{ type: "text", text: serializeOutput(details).text }],
-    details,
-  };
-}
-
-function candidate<T extends TSchema>(
-  tool: AgentTool<T>,
-  options: Partial<
-    Pick<
-      PiToolCandidate,
-      "alwaysRequiresApproval" | "exposureMode" | "owner" | "requiredExecutionLevel" | "retry" | "summary"
-    >
-  > = {},
-): PiToolCandidate {
-  return {
-    owner: options.owner ?? "runtime-base",
-    exposureMode: options.exposureMode ?? "direct",
-    requiredExecutionLevel: options.requiredExecutionLevel ?? "safe",
-    source: "action",
-    tool,
-    ...(options.alwaysRequiresApproval
-      ? { alwaysRequiresApproval: true }
-      : {}),
-    ...(options.summary ? { summary: options.summary } : {}),
-    ...(options.retry ? { retry: options.retry } : {}),
-  };
-}
-
-export function schedulePiToolCandidates(
-  schedule: RuntimeSchedulePort,
-): PiToolCandidate[] {
-  return [
-    candidate(
-      {
-        name: "schedule",
-        label: "Schedule prompt",
-        description:
-          "Schedule a prompt to run LATER, autonomously. Use when the user asks to be reminded, or to run something after a delay / at a time / on a recurring basis. The user always reviews the proposed schedule before it is created. The scheduled prompt runs in its own dedicated session at each trigger with NO memory of this conversation, so phrase `prompt` as a fully standalone instruction. After scheduling, tell the user what you set.",
-        parameters: scheduleParameters,
-        async execute(_toolCallId, input, signal) {
-          signal?.throwIfAborted();
-          const spec: ScheduleSpec = {
-            trigger: input.trigger,
-            job: { kind: "prompt", prompt: input.prompt },
-            label: input.label,
-            ...(input.timezone ? { tz: input.timezone } : {}),
-          };
-          const { id } = await schedule.create(spec);
-          return result({ scheduled: true, id });
-        },
-      },
-      {
-        alwaysRequiresApproval: true,
-        exposureMode: "direct",
-        summary: "Create a scheduled task",
-      },
-    ),
-    candidate(
-      {
-        name: "list_schedules",
-        label: "List schedules",
-        description:
-          "List the user's existing scheduled tasks. Call this when the user asks what they have scheduled, or before cancelling one — you need the id, and the user will refer to a task by what it does, not by its id.",
-        parameters: noParameters,
-        async execute(_toolCallId, _input, signal) {
-          signal?.throwIfAborted();
-          return result({ schedules: await schedule.list() });
-        },
-      },
-      { retry: "idempotent" },
-    ),
-    candidate({
-      name: "update_schedule",
-      label: "Update schedule",
-      description:
-        "Update one scheduled task without changing its id or history. Call `list_schedules` first and use an exact id. If multiple tasks plausibly match the user's wording, ask which one instead of guessing.",
-      parameters: updateScheduleParameters,
-      async execute(_toolCallId, input, signal) {
-        signal?.throwIfAborted();
-        const changes: RuntimeScheduleUpdate = {
-          ...(input.prompt !== undefined ? { prompt: input.prompt } : {}),
-          ...(input.trigger !== undefined ? { trigger: input.trigger } : {}),
-          ...(input.label !== undefined ? { label: input.label } : {}),
-          ...(input.timezone !== undefined ? { tz: input.timezone } : {}),
-        };
-        const { ok } = await schedule.update(input.id, changes);
-        return result({ updated: ok, id: input.id });
-      },
-    }),
-    candidate({
-      name: "pause_schedule",
-      label: "Pause schedule",
-      description:
-        "Pause one scheduled task. Call `list_schedules` first and use an exact id; ask the user if the target is ambiguous.",
-      parameters: scheduleIdParameters,
-      async execute(_toolCallId, input, signal) {
-        signal?.throwIfAborted();
-        const { ok } = await schedule.pause(input.id);
-        return result({ paused: ok, id: input.id });
-      },
-    }),
-    candidate({
-      name: "resume_schedule",
-      label: "Resume schedule",
-      description:
-        "Resume one paused scheduled task. Call `list_schedules` first and use an exact id; ask the user if the target is ambiguous.",
-      parameters: scheduleIdParameters,
-      async execute(_toolCallId, input, signal) {
-        signal?.throwIfAborted();
-        const { ok } = await schedule.resume(input.id);
-        return result({ resumed: ok, id: input.id });
-      },
-    }),
-    candidate(
-      {
-        name: "cancel_schedule",
-        label: "Cancel schedule",
-        description:
-          "Cancel a scheduled task by id. Call `list_schedules` first to find the id that matches what the user described. If more than one plausibly matches, ask the user which one instead of guessing — cancelling is not reversible.",
-        parameters: scheduleIdParameters,
-        async execute(_toolCallId, input, signal) {
-          signal?.throwIfAborted();
-          const { ok } = await schedule.cancel(input.id);
-          return result(ok
-            ? { cancelled: true, id: input.id }
-            : {
-              cancelled: false,
-              id: input.id,
-              reason: "no schedule with that id",
-            });
-        },
-      },
-      {
-        requiredExecutionLevel: "high",
-        summary: "Cancel a scheduled task",
-      },
-    ),
-    candidate(
-      {
-        name: "list_user_agents",
-        label: "List User Agents",
-        description:
-          "List the enabled User Agents available for scheduled tasks. " +
-          "Use this before changing a schedule Agent.",
-        parameters: noParameters,
-        async execute(_toolCallId, _input, signal) {
-          signal?.throwIfAborted();
-          return result({ agents: await schedule.listAgents() });
-        },
-      },
-      { owner: "schedule-host" },
-    ),
-    candidate(
-      {
-        name: "change_schedule_agent",
-        label: "Change schedule Agent",
-        description:
-          "Change which User Agent executes one scheduled task without " +
-          "changing its id or history. Call `list_schedules` and " +
-          "`list_user_agents` first and use exact ids; ask the user when " +
-          "the target is ambiguous.",
-        parameters: changeScheduleAgentParameters,
-        async execute(_toolCallId, input, signal) {
-          signal?.throwIfAborted();
-          const { ok } = await schedule.changeAgent(
-            input.id,
-            input.userAgentId,
-          );
-          return result({ updated: ok, id: input.id });
-        },
-      },
-      { owner: "schedule-host" },
-    ),
-  ];
-}
-
-/** 从 {@link RuntimeSchedulePort} 生成定时任务 Tool 集。 */