The Open Framework for Building Agents
test(eve): cover schedule approval policies (#292)
Ruia230d29e9a15
diff --git a/docs/tools/human-in-the-loop.md b/docs/tools/human-in-the-loop.mdindex 51743574e..534fdb6ed 100644--- a/docs/tools/human-in-the-loop.md+++ b/docs/tools/human-in-the-loop.md@@ -56,6 +56,33 @@ Policies can also return `"approved"` or `"denied"` to decide automatically. UseGating a side effect on approval is also how you make non-idempotent work safe across replays: a charge or email that sits behind `always()` can't fire from a re-run step without a fresh human decision.+### Skipping approval for schedule-dispatched turns++`session.auth.current` identifies the caller of this turn. Markdown schedules use the app principal (`authenticator: "app"`, `principalId: "eve:app"`, `principalType: "runtime"`) automatically. A `run` schedule must pass its `appAuth` to `receive(...)` for the child session to use that principal. Match all three fields to skip approval for automated turns while still prompting when a person calls the same tool:++```ts title="agent/tools/refund_charge.ts"+import { defineTool } from "eve/tools";+import { z } from "zod";++export default defineTool({+ description: "Refund a charge.",+ inputSchema: z.object({ chargeId: z.string(), amount: z.number() }),+ approval: ({ session }) => {+ const auth = session.auth.current;+ return auth?.authenticator === "app" &&+ auth.principalId === "eve:app" &&+ auth.principalType === "runtime"+ ? "not-applicable"+ : "user-approval";+ },+ async execute(input) {+ return refund(input);+ },+});+```++`session` in `approval` has the same shape as `ctx.session` in `execute`: `id`, `auth`, `turn`, and an optional `parent`. If a person later resumes a schedule-started session, `session.auth.current` becomes that person while `session.auth.initiator` remains the app principal. Inspect `initiator` only when the policy should apply to the whole session. Skipping approval on scheduled turns means any non-idempotent side effect will re-fire if a step replays, so pair this pattern with idempotency keys or `once()` where needed.+## QuestionsThe built-in `ask_question` tool lets the model pause and ask the user, rather than guessing. It has no `execute` — the model calls it with `{ prompt, options?, allowFreeform? }`:diff --git a/e2e/fixtures/agent-schedules/agent/tools/record-heartbeat.ts b/e2e/fixtures/agent-schedules/agent/tools/record-heartbeat.tsindex 0d6fb9ced..4f988c5d1 100644--- a/e2e/fixtures/agent-schedules/agent/tools/record-heartbeat.ts+++ b/e2e/fixtures/agent-schedules/agent/tools/record-heartbeat.ts@@ -13,6 +13,14 @@ export default defineTool({inputSchema: z.object({note: z.string().min(1).describe("Any short note describing the heartbeat."),}),+ approval: ({ session }) => {+ const auth = session.auth.current;+ return auth?.authenticator === "app" &&+ auth.principalId === "eve:app" &&+ auth.principalType === "runtime"+ ? "not-applicable"+ : "user-approval";+ },async execute({ note }) {return { ok: true, note, token: "schedule-heartbeat-ok-P2N" };},diff --git a/packages/eve/src/harness/tools.test.ts b/packages/eve/src/harness/tools.test.tsindex 2c8b50a1e..db86d8710 100644--- a/packages/eve/src/harness/tools.test.ts+++ b/packages/eve/src/harness/tools.test.ts@@ -3,6 +3,7 @@ import { describe, expect, it } from "vitest";import { ContextContainer, contextStorage } from "#context/container.js";import { SessionKey, type Session } from "#context/keys.js";+import { SCHEDULE_APP_AUTH } from "#channel/schedule-auth.js";import { always, never, once } from "#public/tools/approval/approval-helpers.js";import type { RuntimeModelReference } from "#runtime/agent/bootstrap.js";import {@@ -766,6 +767,52 @@ describe("buildToolSet", () => {expect(capturedCtx?.getSkill).toBeTypeOf("function");});+ it("uses the active principal for schedule approval", async () => {+ const human: NonNullable<Session["auth"]["current"]> = {+ attributes: {},+ authenticator: "test",+ principalId: "eve:app",+ principalType: "user",+ };+ const tools: HarnessToolMap = new Map<string, HarnessToolDefinition>([+ [+ "refund",+ {+ approval: ({ session }) => {+ const auth = session.auth.current;+ return auth?.authenticator === SCHEDULE_APP_AUTH.authenticator &&+ auth.principalId === SCHEDULE_APP_AUTH.principalId &&+ auth.principalType === SCHEDULE_APP_AUTH.principalType+ ? "not-applicable"+ : "user-approval";+ },+ description: "Refund a charge.",+ execute: async () => "ok",+ inputSchema: jsonSchema({ type: "object" }),+ name: "refund",+ },+ ],+ ]);+ const scheduleSession: Session = {+ auth: { current: SCHEDULE_APP_AUTH, initiator: SCHEDULE_APP_AUTH },+ sessionId: "schedule-session",+ turn: { id: "schedule-turn", sequence: 0 },+ };+ const humanResumedSession: Session = {+ auth: { current: human, initiator: SCHEDULE_APP_AUTH },+ sessionId: "schedule-session",+ turn: { id: "human-turn", sequence: 1 },+ };+ const result = buildToolSet({ tools });++ await expect(resolveApproval(result, "refund", {}, scheduleSession)).resolves.toBe(+ "not-applicable",+ );+ await expect(resolveApproval(result, "refund", {}, humanResumedSession)).resolves.toBe(+ "user-approval",+ );+ });+it("input-aware approval skips when compound key is in approvedTools", async () => {const tools: HarnessToolMap = new Map<string, HarnessToolDefinition>([[