Skip to content

armgit / eve

Public Imported from GitHub
0

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.md
index 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. Use
Gating 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.
+
## Questions
The 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.ts
index 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.ts
index 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>([
[