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

package/src/tools/assistant/ask-user.ts

@@ -0,0 +1,319 @@
+import { StringEnum, Type, type Static } from "@earendil-works/pi-ai";
+import { modelAttachmentText } from "../../conversation/message/conversion";
+import type { PiToolCandidate } from "../runtime/contracts";
+import { candidate } from "./candidate";
+
+export const ASK_USER_TOOL_NAME = "ask_user";
+
+const askUserResponseTypes = [
+  "text",
+  "single_select",
+  "multi_select",
+  "attachment",
+] as const;
+
+const askUserQuestion = Type.Object({
+  question: Type.String({
+    minLength: 1,
+    description: "The question or file request to put to the user.",
+  }),
+  responseType: StringEnum(askUserResponseTypes, {
+    description:
+      "Required response UI: text, single_select, multi_select, or attachment.",
+  }),
+  options: Type.Optional(Type.Array(Type.String({ minLength: 1 }), {
+    minItems: 2,
+    maxItems: 6,
+    uniqueItems: true,
+    description:
+      "Required only for single_select or multi_select. Provide 2-6 distinct options; omit for text and attachment.",
+  })),
+  allowCustom: Type.Optional(Type.Boolean({
+    description:
+      "For single_select or multi_select, whether the user may also add free text. Defaults to false.",
+  })),
+  required: Type.Optional(Type.Boolean({
+    default: false,
+    description:
+      "Whether the user must answer this question to submit. Defaults to false.",
+  })),
+}, { additionalProperties: false });
+
+const askUserParameters = Type.Object({
+  questions: Type.Array(askUserQuestion, {
+    minItems: 1,
+    maxItems: 10,
+    description:
+      "All user decisions and files needed to continue. Every question requires responseType. At most one question may use attachment.",
+  }),
+}, { additionalProperties: false });
+
+/**
+ * `ask_user` 的客户端响应体。
+ *
+ * `answers` 与 Tool 输入的 `questions` 按下标一一对应。
+ * 刻意用结构化数组而不是拼好的字符串 —— 选项本身可能含分隔符，拼了再拆是有损的。
+ */
+type AskUserInput = Static<typeof askUserParameters>;
+
+type AskUserFile = {
+  readonly type: "file";
+  readonly url: string;
+  readonly filename: string;
+  readonly mediaType: string;
+  readonly providerMetadata?: unknown;
+};
+
+type AskUserResponse = {
+  readonly answers: ReadonlyArray<{
+    readonly selections: readonly string[];
+    readonly text: string;
+    readonly attachments: readonly AskUserFile[];
+  }>;
+};
+
+function recordOf(value: unknown): Record<string, unknown> | null {
+  return typeof value === "object" && value !== null && !Array.isArray(value)
+    ? value as Record<string, unknown>
+    : null;
+}
+
+function questionsOf(value: unknown): AskUserInput["questions"] | null {
+  const questions = recordOf(value)?.questions;
+  if (!Array.isArray(questions) || questions.length < 1 || questions.length > 10) {
+    return null;
+  }
+  const normalized: AskUserInput["questions"] = [];
+  let attachmentQuestions = 0;
+  for (const value of questions) {
+    const question = recordOf(value);
+    if (!question || typeof question.question !== "string" || !question.question) {
+      return null;
+    }
+    if (Object.keys(question).some((key) =>
+      key !== "question" && key !== "responseType" && key !== "options" &&
+      key !== "allowCustom" && key !== "required"
+    )) return null;
+    if (
+      question.required !== undefined && typeof question.required !== "boolean"
+    ) return null;
+    const required = question.required === true;
+    let responseType = question.responseType;
+    if (
+      typeof responseType !== "string" ||
+      !askUserResponseTypes.includes(
+        responseType as typeof askUserResponseTypes[number],
+      )
+    ) {
+      return null;
+    }
+    const normalizedQuestion = {
+      question: question.question,
+      responseType: responseType as typeof askUserResponseTypes[number],
+      required,
+    };
+    if (responseType === "attachment") {
+      attachmentQuestions += 1;
+      if (
+        attachmentQuestions > 1 ||
+        question.options !== undefined ||
+        question.allowCustom !== undefined
+      ) return null;
+      normalized.push(normalizedQuestion);
+      continue;
+    }
+    if (responseType === "text") {
+      if (
+        question.options !== undefined ||
+        question.allowCustom !== undefined
+      ) {
+        return null;
+      }
+      normalized.push(normalizedQuestion);
+      continue;
+    }
+    if (
+      !Array.isArray(question.options) ||
+      question.options.length < 2 ||
+      question.options.length > 6 ||
+      !question.options.every((option) =>
+        typeof option === "string" && option.length > 0
+      ) ||
+      new Set(question.options).size !== question.options.length ||
+      (question.allowCustom !== undefined &&
+        typeof question.allowCustom !== "boolean")
+    ) return null;
+    normalized.push({
+      ...normalizedQuestion,
+      options: question.options,
+      ...(question.allowCustom === undefined
+        ? {}
+        : { allowCustom: question.allowCustom }),
+    });
+  }
+  return normalized;
+}
+
+function prepareAskUserArguments(input: unknown): AskUserInput {
+  const value = recordOf(input);
+  if (!value) throw new Error("Invalid ask_user questions");
+  let questions = value.questions;
+  if (typeof questions === "string") {
+    try {
+      questions = JSON.parse(questions);
+    } catch {
+      throw new Error("Invalid ask_user questions");
+    }
+  }
+  const prepared = { ...value, questions };
+  if (!questionsOf(prepared)) throw new Error("Invalid ask_user questions");
+  return prepared as AskUserInput;
+}
+
+// 手写校验而不是拉 TypeBox compiler：这里只需要判真假，
+// 且校验位于 Worker 响应信任边界，不应为每次回答编译 schema。
+function isAskUserResponse(input: unknown, value: unknown): boolean {
+  const questions = questionsOf(input);
+  const answers = recordOf(value)?.answers;
+  if (!questions || !Array.isArray(answers) || answers.length !== questions.length) {
+    return false;
+  }
+
+  return questions.every((question, index) => {
+    const answer = recordOf(answers[index]);
+    if (
+      !answer ||
+      !Array.isArray(answer.selections) ||
+      typeof answer.text !== "string" ||
+      !Array.isArray(answer.attachments) ||
+      Object.keys(answer).some((key) =>
+        key !== "selections" && key !== "text" && key !== "attachments"
+      )
+    ) return false;
+    if (!answer.selections.every((item) => typeof item === "string")) {
+      return false;
+    }
+    if (answer.text.length > 2_000) return false;
+    if (!answer.attachments.every((value) => {
+      const file = recordOf(value);
+      return Boolean(
+        file &&
+        file.type === "file" &&
+        typeof file.url === "string" && file.url.length > 0 &&
+        typeof file.filename === "string" && file.filename.length > 0 &&
+        typeof file.mediaType === "string" && file.mediaType.length > 0 &&
+        (file.providerMetadata === undefined || recordOf(file.providerMetadata)) &&
+        Object.keys(file).every((key) =>
+          key === "type" || key === "url" || key === "filename" ||
+          key === "mediaType" || key === "providerMetadata"
+        )
+      );
+    })) return false;
+
+    if (
+      answer.selections.length === 0 &&
+      !answer.text.trim() &&
+      answer.attachments.length === 0
+    ) return question.required !== true;
+
+    if (question.responseType === "attachment") {
+      return answer.selections.length === 0 && !answer.text &&
+        answer.attachments.length >= 1 && answer.attachments.length <= 8;
+    }
+    if (answer.attachments.length > 0) return false;
+    if (question.responseType === "text") {
+      return answer.selections.length === 0 && answer.text.trim().length > 0;
+    }
+
+    const options = question.options ?? [];
+    if (answer.selections.some((selection) => !options.includes(selection))) {
+      return false;
+    }
+    if (new Set(answer.selections).size !== answer.selections.length) return false;
+    if (
+      question.responseType === "single_select" &&
+      answer.selections.length > 1
+    ) return false;
+    if (!question.allowCustom && answer.text.trim()) return false;
+    return answer.selections.length > 0 || answer.text.trim().length > 0;
+  });
+}
+
+export function askUserPiToolCandidate(): PiToolCandidate {
+  return {
+    ...candidate({
+      name: ASK_USER_TOOL_NAME,
+      label: "Ask user",
+      description:
+        "Ask all 1-10 user questions needed to continue in one call. Required input for every question: question and responseType; required defaults to false, so set it to true only when progress cannot continue without an answer. Use responseType text for free text, single_select or multi_select with 2-6 distinct options for choices, and attachment for files. At most one attachment question is allowed and it accepts multiple files. Do not add file-specific fields such as accept or tell the user to use the normal chat composer. The answers return as this tool's result, so continue the same turn after calling it.",
+      parameters: askUserParameters,
+      prepareArguments: prepareAskUserArguments,
+      // 永远不会被调用：执行链在 interaction 闸就 park 住了。留一个失败关闭的
+      // 实现，是为了万一哪次改动绕过了那道闸，能立刻炸出来而不是静默返回空答案。
+      async execute() {
+        throw new Error(
+          "ask_user is client-settled and must not execute on the server",
+        );
+      },
+    }),
+    interaction: {
+      validateResponse: isAskUserResponse,
+      settle: (input, response) => {
+        const questions = questionsOf(input)!;
+        const responseAnswers = (response as AskUserResponse).answers;
+        const answers = questions.map((question, index) => {
+          const answer = responseAnswers[index]!;
+          return {
+            question: question.question,
+            selections: [...answer.selections],
+            text: answer.text.trim(),
+            attachments: answer.attachments.map((file) => {
+              const springbrand = recordOf(
+                recordOf(file.providerMetadata)?.springbrand,
+              );
+              return {
+                name: file.filename,
+                mediaType: file.mediaType,
+                size: typeof springbrand?.size === "number"
+                  ? springbrand.size
+                  : 0,
+                cdnUrl: typeof springbrand?.cdnUrl === "string"
+                  ? springbrand.cdnUrl
+                  : file.url,
+                workspacePath: typeof springbrand?.path === "string"
+                  ? springbrand.path
+                  : "",
+                attachmentId: typeof springbrand?.attachmentId === "string"
+                  ? springbrand.attachmentId
+                  : "",
+                contentVersion:
+                  typeof springbrand?.contentVersion === "string"
+                    ? springbrand.contentVersion
+                    : "",
+              };
+            }),
+          };
+        });
+        return {
+          content: [{
+            type: "text",
+            text: `The user answered:\n${answers.map((answer, index) => {
+              if (answer.attachments.length > 0) {
+                const responseAnswer = responseAnswers[index]!;
+                return `${index + 1}. ${answer.question}\n${responseAnswer.attachments
+                  .map((file) => `   - ${modelAttachmentText(file)}`)
+                  .join("\n")}`;
+              }
+              const parts = [
+                ...answer.selections,
+                ...(answer.text ? [answer.text] : []),
+              ];
+              return `${index + 1}. ${answer.question}\n   ${parts.join(" / ")}`;
+            }).join("\n")}`,
+          }],
+          details: { answers },
+        };
+      },
+    },
+  };
+}

package/src/tools/assistant/candidate.ts

@@ -0,0 +1,15 @@
+import type { AgentTool } from "@earendil-works/pi-agent-core";
+import { type TSchema } from "@earendil-works/pi-ai";
+import type { PiToolCandidate } from "../runtime/contracts";
+
+export function candidate<T extends TSchema, D = any>(tool: AgentTool<T, D>): PiToolCandidate<T, D> {
+  return {
+    owner: "runtime-base",
+    requiredExecutionLevel: "safe",
+    source: "action",
+    tool: {
+      ...tool,
+      constrainedSampling: { type: "json_schema", strict: "prefer" },
+    } as AgentTool<T, D>,
+  };
+}

package/src/tools/assistant/followups.ts

@@ -0,0 +1,34 @@
+import { Type } from "@earendil-works/pi-ai";
+import type { PiToolCandidate } from "../runtime/contracts";
+import { result } from "../runtime/result";
+import { candidate } from "./candidate";
+
+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.",
+  }),
+}, { additionalProperties: false });
+
+export function suggestFollowupsPiToolCandidate(): PiToolCandidate {
+  return {
+    ...candidate({
+      name: "suggest_followups",
+      label: "Suggest follow-ups",
+      description:
+        "Offer the user 2-4 optional follow-up directions for a completed substantive task. Call at most once.",
+      parameters: suggestFollowupsParameters,
+      async execute(_toolCallId, input) {
+        return result({ noted: true, count: input.items.length });
+      },
+    }),
+    unattendedExecution: {
+      capability: "runtime-ui",
+      operation: "suggest-followups",
+    },
+    exposureMode: "direct",
+  };
+}

package/src/tools/assistant/index.ts

@@ -0,0 +1,19 @@
+import type { PiToolCandidate } from "../runtime/contracts";
+import { webSearchPiToolCandidate } from "../web/search";
+import type { WebSearch } from "../web/search/api";
+import { askUserPiToolCandidate } from "./ask-user";
+import { suggestFollowupsPiToolCandidate } from "./followups";
+import { updatePlanPiToolCandidate } from "./plan";
+
+export { memoryPiToolCandidate } from "./memory";
+export { normalizeUpdatePlanArguments } from "./plan";
+export * from "./time";
+
+export function basePiToolCandidates(webSearch?: WebSearch): PiToolCandidate[] {
+  return [
+    askUserPiToolCandidate(),
+    suggestFollowupsPiToolCandidate(),
+    updatePlanPiToolCandidate(),
+    ...(webSearch ? [webSearchPiToolCandidate(webSearch)] : []),
+  ];
+}

package/src/tools/assistant/memory.ts

@@ -0,0 +1,73 @@
+import type { AgentTool } from "@earendil-works/pi-agent-core";
+import { StringEnum, Type } from "@earendil-works/pi-ai";
+import { estimateStringTokens } from "../../lib/token-estimate";
+import type { RuntimeMemoryPort } from "../../config/ports";
+import type { RuntimeMemoryProfile } from "../../config/profile";
+import type { PiToolCandidate } from "../runtime/contracts";
+import { result } from "../runtime/result";
+
+const setContextParameters = Type.Object({
+  label: StringEnum(["memory", "preferences"] as const, {
+    description:
+      "Context block to update: memory for durable facts and active context, preferences for tone and workflow choices.",
+  }),
+  content: Type.String({ description: "Text to store in the selected context block." }),
+  action: Type.Optional(StringEnum(["replace", "append"] as const, {
+    description: 'Whether to replace the block or append to it. Defaults to "replace".',
+  })),
+}, { additionalProperties: false });
+
+/** Writable hot-memory Tool restored from Think Session context blocks. */
+export function memoryPiToolCandidate(
+  memory: RuntimeMemoryPort,
+  profile: Pick<
+    RuntimeMemoryProfile,
+    "memoryTokens" | "preferencesTokens"
+  >,
+): PiToolCandidate {
+  const queues = new Map<string, Promise<void>>();
+  const tool: AgentTool<typeof setContextParameters> = {
+    name: "set_context",
+    label: "Set context",
+    description:
+      "Replace or append durable working context. Use memory for facts and active context; use preferences for tone, format, tools, and workflow preferences.",
+    parameters: setContextParameters,
+    async execute(_toolCallId, { label, content, action = "replace" }) {
+      const run = async () => {
+        const existing = action === "append"
+          ? await memory.get(label) ?? ""
+          : "";
+        const separator = existing && !content.startsWith("\n") ? "\n" : "";
+        const updated = `${existing}${separator}${content}`;
+        const maxTokens = label === "memory"
+          ? profile.memoryTokens
+          : profile.preferencesTokens;
+        const tokens = estimateStringTokens(updated);
+        if (tokens > maxTokens) {
+          throw new Error(
+            `Block "${label}" exceeds maxTokens: ${tokens} > ${maxTokens}`,
+          );
+        }
+        await memory.set(label, updated);
+        return result({ label, action, tokens, maxTokens });
+      };
+      const tail = queues.get(label) ?? Promise.resolve();
+      const output = tail.then(run);
+      const next = output.then(
+        () => { },
+        () => { },
+      );
+      queues.set(label, next);
+      void next.then(() => {
+        if (queues.get(label) === next) queues.delete(label);
+      });
+      return output;
+    },
+  };
+  return {
+    owner: "runtime-memory",
+    requiredExecutionLevel: "safe",
+    source: "action",
+    tool,
+  };
+}

package/src/tools/assistant/plan.ts

@@ -0,0 +1,98 @@
+import { StringEnum, Type, type Static } from "@earendil-works/pi-ai";
+import type { PiToolCandidate } from "../runtime/contracts";
+import { result } from "../runtime/result";
+import { candidate } from "./candidate";
+
+const updatePlanParameters = Type.Object({
+  steps: Type.Array(Type.Object({
+    text: Type.String({
+      description: "The step, phrased as a short imperative.",
+    }),
+    status: StringEnum(["pending", "in_progress", "done"] as const, {
+      description:
+        'Current status. Use "done" for a finished step; never use "completed".',
+    }),
+  }, { additionalProperties: false }), {
+    description:
+      "The complete, ordered plan. Overwrites any previously reported plan.",
+  }),
+}, { additionalProperties: false });
+
+type UpdatePlanArguments = Static<typeof updatePlanParameters>;
+
+function normalizeStepStatus(
+  status: unknown,
+): UpdatePlanArguments["steps"][number]["status"] {
+  switch (status) {
+    case "done":
+    case "completed": // Anthropic models sometimes output "completed"
+      return "done";
+    case "in_progress":
+    case "inProgress": // camelCase variant
+      return "in_progress";
+    default: // covers "pending", "todo" (Google), and any other unknown value
+      return "pending";
+  }
+}
+
+export function normalizeUpdatePlanArguments(
+  input: unknown,
+): UpdatePlanArguments {
+  if (input === null || typeof input !== "object") {
+    return input as UpdatePlanArguments;
+  }
+  const value = input as Record<string, unknown>;
+  let steps = value.steps;
+  if (typeof steps === "string") {
+    try {
+      steps = JSON.parse(steps);
+    } catch {
+      return input as UpdatePlanArguments;
+    }
+  }
+  if (!Array.isArray(steps)) return input as UpdatePlanArguments;
+  return {
+    ...value,
+    steps: steps.map((step) => {
+      if (step === null || typeof step !== "object") return step;
+      const s = step as Record<string, unknown>;
+      const { step: stepAlias, title: titleAlias, ...rest } = s;
+      const alias = typeof stepAlias === "string" ? stepAlias : titleAlias;
+      const text = typeof rest.text === "string"
+        ? rest.text
+        : typeof alias === "string"
+          ? alias
+          : undefined;
+      return {
+        ...rest,
+        ...(text === undefined ? {} : { text }),
+        status: normalizeStepStatus(s.status),
+      };
+    }),
+  } as UpdatePlanArguments;
+}
+
+export function updatePlanPiToolCandidate(): PiToolCandidate {
+  return {
+    ...candidate({
+      name: "update_plan",
+      label: "Update plan",
+      description:
+        "Maintain the user-visible plan for the current task. Required input: steps. 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,
+      prepareArguments: normalizeUpdatePlanArguments,
+      async execute(_toolCallId, input) {
+        return result({
+          ok: true,
+          total: input.steps.length,
+          done: input.steps.filter((step) => step.status === "done").length,
+        });
+      },
+    }),
+    unattendedExecution: {
+      capability: "runtime-ui",
+      operation: "update",
+    },
+    exposureMode: "direct",
+  };
+}

package/src/tools/{time.ts → assistant/time.ts}

@@ -1,6 +1,6 @@
 import type { AgentToolResult } from "@earendil-works/pi-agent-core";
 import { Type } from "@earendil-works/pi-ai";
-import type { PiToolCandidate } from "./compiler";
+import type { PiToolCandidate } from "../runtime/contracts";
 
 export const GET_TIME_TOOL_NAME = "get_time";