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

package/src/tools/schedule/index.ts

@@ -0,0 +1,301 @@
+import type { AgentTool, AgentToolResult } from "@earendil-works/pi-agent-core";
+import { Type, fauxToolCall, validateToolArguments, type JsonObject, type TSchema } from "@earendil-works/pi-ai";
+import {
+  toScheduleRuleSpec,
+  validateScheduleRuleSpec,
+} from "../../adapter/cloudflare/scheduling/schedule-rule";
+import { isValidTimeZone } from "../../adapter/cloudflare/scheduling/zoned-cron";
+import type { RuntimeSchedulePort, RuntimeSchedulePreparation } from "../../config/ports";
+import { serializeOutput } from "../../lib/artifacts";
+import type { ScheduleSpec } from "../../submission/contracts";
+import type { PiToolCandidate } from "../runtime/contracts";
+
+const scheduleTriggerParameters = Type.Union([
+  Type.Object({
+    kind: Type.Literal("local", { description: "Interpret the rule in the explicit task timezone." }),
+    rule: Type.Union([
+      Type.Object({ kind: Type.Literal("once", { description: "Run on one local date." }), date: Type.String({ description: "Local date YYYY-MM-DD." }), time: Type.String({ description: "Local clock time HH:mm." }) }, { additionalProperties: false }),
+      Type.Object({ kind: Type.Literal("daily", { description: "Run each local day." }), time: Type.String({ description: "Local clock time HH:mm." }) }, { additionalProperties: false }),
+      Type.Object({ kind: Type.Literal("weekly", { description: "Run on the selected weekdays." }), weekdays: Type.Array(Type.Integer({ minimum: 0, maximum: 6 }), { minItems: 1, description: "Weekdays: Sunday 0 through Saturday 6." }), time: Type.String({ description: "Local clock time HH:mm." }) }, { additionalProperties: false }),
+    ], { description: "Once, daily or weekly local-time rule." }),
+    startDate: Type.Optional(Type.String({ description: "Inclusive first local date YYYY-MM-DD." })),
+    endDate: Type.Optional(Type.String({ description: "Inclusive last local date YYYY-MM-DD." })),
+  }, { additionalProperties: false }),
+  Type.Object({
+    kind: Type.Literal("once-in", { description: "Run once after a delay." }),
+    seconds: Type.Integer({
+      minimum: 1,
+      description: "Fire once, this many seconds from now.",
+    }),
+  }, { additionalProperties: false }),
+  Type.Object({
+    kind: Type.Literal("once-at", { description: "Run once at an absolute UTC time." }),
+    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", { description: "Repeat on a UTC cron schedule." }),
+    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", { description: "Repeat at fixed intervals." }),
+    seconds: Type.Integer({
+      minimum: 1,
+      description: "Repeat every this many seconds.",
+    }),
+  }, { additionalProperties: false }),
+], {
+  description:
+    "When to fire. Discriminate on the `kind` field (never \"type\"). " +
+    'Shapes: {"kind":"local","rule":{"kind":"once","date":"2026-09-17","time":"14:06"}} runs once at 14:06 in `timezone`; ' +
+    '{"kind":"local","rule":{"kind":"daily","time":"09:00"}} runs daily; ' +
+    '{"kind":"local","rule":{"kind":"weekly","weekdays":[1,3],"time":"09:30"}} runs on Mondays and Wednesdays; ' +
+    '{"kind":"once-at","at":"2026-09-17T06:06:00Z"} fires once at an absolute UTC time.',
+});
+
+const scheduleParameters = Type.Object({
+  prompt: Type.String({
+    minLength: 1, maxLength: 1000, pattern: "\\S",
+    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.Optional(Type.String({ maxLength: 50, description: "Optional task name, at most 50 Unicode characters. The Host generates a name when omitted." })),
+  timezone: Type.String({ minLength: 1, description: "Required IANA timezone. Use the user's explicit timezone or reliable Host/browser timezone; ask when unknown." }),
+}, { 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({ minLength: 1, description: "The exact id returned by `list_schedules`." }),
+  prompt: Type.Optional(scheduleParameters.properties.prompt),
+  trigger: Type.Optional(scheduleTriggerParameters),
+  label: scheduleParameters.properties.label,
+  timezone: Type.Optional(scheduleParameters.properties.timezone),
+}, { 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[] {
+  const candidates = [
+    candidate(
+      {
+        name: "schedule",
+        label: "Schedule prompt",
+        description:
+          "Schedule a prompt to run LATER, autonomously. Required inputs: prompt (Requirement, at most 1000 Unicode characters), trigger and timezone. Prefer local once/daily/weekly rules. trigger discriminates on `kind` (never \"type\"); see the trigger parameter schema for detailed shapes. label is optional (at most 50 characters); the Host generates an omitted name. Ask for missing information.  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();
+          throw new Error("Matching user confirmation is required");
+        },
+      },
+      {
+        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. Required input: id. Optional prompt, trigger, label and timezone preserve the saved values when omitted; trigger uses the same `kind`-based shapes as `schedule`. Every edit requires user confirmation; changing Requirement requires a fresh Host authorization check.  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();
+        throw new Error("Matching user confirmation is required");
+      },
+    }),
+    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" },
+    ),
+  ];
+  return candidates.flatMap((toolCandidate): PiToolCandidate[] => {
+    const name = toolCandidate.tool.name;
+    if (name !== "schedule" && name !== "update_schedule") return [toolCandidate];
+    const confirmation = schedule.confirmation;
+    if (!confirmation) return [];
+    return [{
+      ...toolCandidate, alwaysRequiresApproval: true, confirmation: {
+        async prepare(args, { intentId }) {
+          const validated = validateToolArguments(toolCandidate.tool, fauxToolCall(name, args as JsonObject));
+          const input = validated as { id?: string; prompt?: string; trigger?: ScheduleSpec["trigger"]; label?: string; timezone?: string };
+          if (input.timezone !== undefined && !isValidTimeZone(input.timezone)) throw new Error("A valid IANA timezone is required");
+          if (input.trigger?.kind === "local" && input.timezone) {
+            const error = validateScheduleRuleSpec(toScheduleRuleSpec(input.trigger, input.timezone));
+            if (error) throw new Error(error.message);
+          }
+          const prepared = await confirmation.prepare({
+            intentId, ...(name === "update_schedule" ? { id: input.id } : {}),
+            ...(input.prompt !== undefined ? { prompt: input.prompt } : {}),
+            ...(input.trigger !== undefined ? { trigger: input.trigger } : {}),
+            ...(input.label !== undefined ? { label: input.label } : {}),
+            ...(input.timezone !== undefined ? { tz: input.timezone } : {}),
+          });
+          if (prepared.id !== input.id) throw new Error("Host preparation changed the target Task ID");
+          const fullInput = { prompt: prepared.prompt, label: prepared.label, trigger: prepared.trigger, timezone: prepared.timezone };
+          void validateToolArguments({ ...toolCandidate.tool, parameters: scheduleParameters }, fauxToolCall(name, fullInput));
+          if (!prepared.label?.trim() || !isValidTimeZone(prepared.timezone) || !prepared.candidateId?.trim() || !prepared.candidateVersion?.trim() || !prepared.authorization?.version?.trim() || !prepared.authorization.scope?.trim() || !Array.isArray(prepared.authorization.missing)) {
+            throw new Error("Host preparation is incomplete");
+          }
+          if (prepared.trigger.kind === "local") {
+            const error = validateScheduleRuleSpec(toScheduleRuleSpec(prepared.trigger, prepared.timezone));
+            if (error) throw new Error(error.message);
+          }
+          return prepared;
+        },
+        async execute(prepared, context) {
+          const preview = prepared as RuntimeSchedulePreparation;
+          if (preview.authorization.missing.length) throw new Error(`Missing authorization: ${preview.authorization.missing.join("; ")}`);
+          const { id } = await confirmation.commit(preview, context);
+          return result({ [name === "schedule" ? "scheduled" : "updated"]: true, id, task: { label: preview.label, prompt: preview.prompt, trigger: preview.trigger, timezone: preview.timezone } });
+        },
+      }
+    }];
+  });
+}
+
+/** 从 {@link RuntimeSchedulePort} 生成定时任务 Tool 集。 */

package/src/tools/skill/contracts.ts

@@ -0,0 +1,20 @@
+import { type SkillSource } from "agents/skills";
+import type { RuntimeSkillScriptPolicy, WorkspacePort } from "../../config/ports";
+import type { RuntimeSkillBodyTransform } from "../../config/definition";
+import type { PiToolCandidate } from "../runtime/contracts";
+
+/** A configured Skill source and its script capabilities. */
+export interface PiSkillBinding {
+  readonly name: string;
+  readonly description: string;
+  readonly source: SkillSource;
+  readonly script?: RuntimeSkillScriptPolicy;
+}
+
+/** Host capabilities available while creating Skill tools. */
+export interface SkillPiToolOptions {
+  readonly loader?: WorkerLoader;
+  readonly workspace?: WorkspacePort;
+  readonly tools?: readonly PiToolCandidate[];
+  readonly transformSkillBody?: RuntimeSkillBodyTransform;
+}

package/src/tools/skill/index.ts

@@ -0,0 +1,99 @@
+import { SkillRegistry } from "agents/skills";
+import { aiToolToPi } from "../adapters/ai-to-pi";
+import type { PiToolCandidate } from "../runtime/contracts";
+import type { PiSkillBinding, SkillPiToolOptions } from "./contracts";
+import { catalogSkillSource, materializeSkillResourceTool, wrapSkillResourceRead } from "./resources";
+import { scriptRunner, wrapSkillScript } from "./scripts";
+
+export type { PiSkillBinding, SkillPiToolOptions } from "./contracts";
+const SKILL_TOOL_LABELS: Readonly<Record<string, string>> = {
+  activate_skill: "Activate Skill",
+  read_skill_resource: "Read Skill resource",
+  run_skill_script: "Run Skill script",
+  materialize_skill_resource: "Materialize Skill resource",
+};
+
+const SKILL_TOOL_PARAMETER_DESCRIPTIONS: Readonly<Record<string, Readonly<Record<string, string>>>> = {
+  activate_skill: {
+    name: "Exact name of the available Skill to activate.",
+  },
+  read_skill_resource: {
+    name: "Name of the activated Skill. Omit only when path starts with the Skill name.",
+    path: "Bundled resource path listed by activate_skill.",
+  },
+  run_skill_script: {
+    name: "Name of the activated Skill that supplies the script.",
+    path: "Bundled script path listed by activate_skill.",
+    input: "JSON input expected by the Skill script. Defaults to an empty object.",
+  },
+};
+
+/** Create Pi candidates from the official Agents SDK SkillRegistry tools. */
+export async function skillPiToolCandidates(
+  bindings: readonly PiSkillBinding[],
+  options: SkillPiToolOptions = {},
+): Promise<PiToolCandidate[]> {
+  if (bindings.length === 0) return [];
+
+  const availableToolNames = (options.tools ?? []).map(({ tool }) => tool.name);
+
+  const registry = new SkillRegistry(
+    bindings.map((binding) => catalogSkillSource(
+      binding,
+      options.transformSkillBody,
+      availableToolNames,
+    )),
+    scriptRunner(bindings, options),
+  );
+  await registry.load();
+
+  const tools = registry.tools();
+  if (options.workspace) {
+    tools.materialize_skill_resource = materializeSkillResourceTool(
+      bindings,
+      options.workspace,
+    );
+  }
+
+  return Object.entries(tools).map(([name, tool]) => {
+    const adapted = aiToolToPi(name, tool, {
+      label: SKILL_TOOL_LABELS[name] ?? name,
+      ...(name === "read_skill_resource"
+        ? {
+          description:
+            "Read a bundled resource listed by activate_skill. Returns structured resource metadata and content. Do not pass SKILL.md; activate_skill returns the Skill instructions.",
+        }
+        : {}),
+    });
+    const properties = (adapted.parameters as { properties?: unknown }).properties;
+    if (properties && typeof properties === "object" && !Array.isArray(properties)) {
+      for (const [parameter, description] of Object.entries(
+        SKILL_TOOL_PARAMETER_DESCRIPTIONS[name] ?? {},
+      )) {
+        const schema = (properties as Record<string, unknown>)[parameter];
+        if (schema && typeof schema === "object" && !Array.isArray(schema)) {
+          (schema as Record<string, unknown>).description ??= description;
+        }
+      }
+    }
+    if (name === "read_skill_resource") wrapSkillResourceRead(adapted, bindings);
+    if (name === "run_skill_script") wrapSkillScript(adapted, options.workspace);
+    return {
+      owner: "runtime-skill",
+      requiredExecutionLevel: "safe",
+      // activate_skill 返回的是 Skill 指令本身,是模型接下来所有动作的依据。把它外置
+      // 成文件,模型手里就只剩一个路径,必须再取一次才能知道该做什么 —— 而典型
+      // SKILL.md 正好落在会触发外置的区间。指令必须当场到手。
+      ...(name === "activate_skill"
+        ? { outputBudget: { kind: "structure" as const } }
+        : {}),
+      ...(name === "activate_skill"
+        ? { exposureMode: "direct" as const }
+        : { exposureMode: "codemode" as const }),
+      ...(name === "activate_skill" || name === "read_skill_resource"
+        ? { retry: "idempotent" as const }
+        : {}),
+      tool: adapted,
+    };
+  });
+}