Skip to content

armgit / eve

Public Imported from GitHub
0

The Open Framework for Building Agents

feat(eve): state machine for HITL authorization (#1370)

Ben Pankowed74b7cbb47b
diff --git a/e2e/fixtures/agent-cancellation/evals/cancellation/clear-channel-session.eval.ts b/e2e/fixtures/agent-cancellation/evals/cancellation/clear-channel-session.eval.ts
index a052daeb3..70c0861aa 100644
--- a/e2e/fixtures/agent-cancellation/evals/cancellation/clear-channel-session.eval.ts
+++ b/e2e/fixtures/agent-cancellation/evals/cancellation/clear-channel-session.eval.ts
@@ -61,6 +61,7 @@ export default defineEval({
initial.notEvent("session.failed");
const liveClear = t.target.watchTurn(sessionId, { startIndex: initial.events.length });
+ await new Promise((resolve) => setTimeout(resolve, 250));
const clearedResponse = await postJson<ClearResponse>(
t.target,
`/threads/${threadId}/clear`,
@@ -81,6 +82,10 @@ export default defineEval({
cleared.notEvent("turn.failed");
cleared.notEvent("session.failed");
+ const followUpTurn = t.target.watchTurn(sessionId, {
+ startIndex: initial.events.length + cleared.events.length,
+ });
+ await new Promise((resolve) => setTimeout(resolve, 250));
const resumed = await postJson<MessageResponse>(t.target, `/threads/${threadId}/messages`, {
message: "Reply with exactly CLEAR-FOLLOW-UP-OK.",
});
@@ -92,11 +97,7 @@ export default defineEval({
),
);
- const followUp = await t.target
- .watchTurn(sessionId, {
- startIndex: initial.events.length + cleared.events.length,
- })
- .result();
+ const followUp = await followUpTurn.result();
followUp.notEvent("turn.failed");
followUp.notEvent("session.failed");
followUp.messageIncludes(/CLEAR-FOLLOW-UP-OK/i);
diff --git a/e2e/fixtures/agent-cancellation/evals/cancellation/compact-channel-session.eval.ts b/e2e/fixtures/agent-cancellation/evals/cancellation/compact-channel-session.eval.ts
index a31cf72ad..06a18bf22 100644
--- a/e2e/fixtures/agent-cancellation/evals/cancellation/compact-channel-session.eval.ts
+++ b/e2e/fixtures/agent-cancellation/evals/cancellation/compact-channel-session.eval.ts
@@ -69,6 +69,7 @@ export default defineEval({
const liveCompaction = t.target.watchTurn(sessionId, {
startIndex: initial.events.length,
});
+ await new Promise((resolve) => setTimeout(resolve, 250));
const compactedResponse = await postJson<CompactResponse>(
t.target,
`/threads/${threadId}/compact`,
@@ -94,6 +95,10 @@ export default defineEval({
compacted.notEvent("turn.failed");
compacted.notEvent("session.failed");
+ const followUpTurn = t.target.watchTurn(sessionId, {
+ startIndex: initial.events.length + compacted.events.length,
+ });
+ await new Promise((resolve) => setTimeout(resolve, 250));
const resumed = await postJson<MessageResponse>(t.target, `/threads/${threadId}/messages`, {
message: "Reply with exactly COMPACT-FOLLOW-UP-OK.",
});
@@ -105,11 +110,7 @@ export default defineEval({
),
);
- const followUp = await t.target
- .watchTurn(sessionId, {
- startIndex: initial.events.length + compacted.events.length,
- })
- .result();
+ const followUp = await followUpTurn.result();
followUp.notEvent("turn.failed");
followUp.notEvent("session.failed");
followUp.messageIncludes(/COMPACT-FOLLOW-UP-OK/i);
diff --git a/e2e/fixtures/agent-tools-hitl/evals/auth/authorization-nonblocking.eval.ts b/e2e/fixtures/agent-tools-hitl/evals/auth/authorization-nonblocking.eval.ts
index fce4a7686..664e339c4 100644
--- a/e2e/fixtures/agent-tools-hitl/evals/auth/authorization-nonblocking.eval.ts
+++ b/e2e/fixtures/agent-tools-hitl/evals/auth/authorization-nonblocking.eval.ts
@@ -1,11 +1,10 @@
import { defineEval } from "eve/evals";
-import type { EveEvalContext, EveEvalSession, EveEvalTurn } from "eve/evals";
/**
* An open authorization challenge must not wedge the session: an ordinary
- * message runs as a normal turn while the challenge waits, and the callback
- * still completes it afterwards. Tool re-execution after the callback is
- * covered deterministically by `workflow-entry.integration.test.ts`.
+ * message runs as a normal turn while the challenge waits. Callback completion
+ * and tool re-execution are covered deterministically by
+ * `workflow-entry.integration.test.ts`.
*/
export default defineEval({
description: "An ordinary message runs while an authorization challenge stays open.",
@@ -17,8 +16,6 @@ export default defineEval({
parked.notEvent("authorization.completed");
parked.event("session.waiting", { count: 1 });
- // The wedge case: a message while the challenge is open runs as a
- // normal turn instead of queueing behind the callback.
const message = await t.send("Do not call any tools. Reply with exactly AUTH-OPEN-MESSAGE-OK.");
message.expectOk();
if (message.sessionId !== parked.sessionId) {
@@ -30,48 +27,5 @@ export default defineEval({
message.event("session.waiting", { count: 1 });
message.messageIncludes("AUTH-OPEN-MESSAGE-OK");
message.usedNoTools();
-
- // The callback still lands and closes the challenge exactly once.
- const resumed = await invokeCallback(t, parked);
- resumed.turn.event("authorization.completed", {
- count: 1,
- data: { outcome: "authorized" },
- });
- resumed.turn.notEvent("session.failed");
-
- // The session stays conversational after the whole sequence.
- const followUp = await resumed.session.send(
- "Do not call tools. Reply with exactly AUTH-OPEN-FOLLOW-UP-OK.",
- );
- followUp.expectOk();
- if (followUp.sessionId !== parked.sessionId) {
- throw new Error("Follow-up after the callback changed session identity.");
- }
- followUp.event("message.completed", { count: 1 });
- followUp.event("session.waiting", { count: 1 });
- followUp.messageIncludes("AUTH-OPEN-FOLLOW-UP-OK");
- followUp.usedNoTools();
},
});
-
-function authorizationUrl(turn: EveEvalTurn): URL {
- for (const event of turn.events) {
- if (event.type !== "authorization.required") continue;
- const url = event.data.authorization?.url;
- if (url !== undefined) return new URL(url);
- }
- throw new Error("authorization.required did not expose a callback URL.");
-}
-
-async function invokeCallback(
- t: EveEvalContext,
- turn: EveEvalTurn,
-): Promise<{ readonly session: EveEvalSession; readonly turn: EveEvalTurn }> {
- const state = t.state as { readonly streamIndex?: unknown } | undefined;
- if (typeof state?.streamIndex !== "number") throw new Error("Missing auth callback cursor.");
- const url = authorizationUrl(turn);
- const response = await t.target.fetch(`${url.pathname}${url.search}`);
- if (!response.ok) throw new Error(`Authorization callback failed (${String(response.status)}).`);
- const live = t.target.watchTurn(turn.sessionId, { startIndex: state.streamIndex });
- return { session: live.session, turn: await live.result() };
-}
diff --git a/e2e/fixtures/agent-tools-hitl/evals/hitl/button-cancel.eval.ts b/e2e/fixtures/agent-tools-hitl/evals/hitl/button-cancel.eval.ts
new file mode 100644
index 000000000..71cac2cd7
--- /dev/null
+++ b/e2e/fixtures/agent-tools-hitl/evals/hitl/button-cancel.eval.ts
@@ -0,0 +1,17 @@
+import { defineEval } from "eve/evals";
+
+export default defineEval({
+ tags: ["real-model"],
+ description: "HITL smoke: approvals use structured controls, not text replies.",
+ async test(t) {
+ const parked = await t.send('Call the guarded-echo tool with note "text-approve".');
+ parked.calledTool("guarded-echo", { status: "pending", count: 1 });
+ const approval = t.requireInputRequest({
+ display: "confirmation",
+ toolName: "guarded-echo",
+ });
+ const cancelled = await t.respond([{ optionId: "cancel", requestId: approval.requestId }]);
+ cancelled.expectOk();
+ t.succeeded();
+ },
+});
diff --git a/e2e/fixtures/agent-tools-hitl/evals/hitl/text-approve.eval.ts b/e2e/fixtures/agent-tools-hitl/evals/hitl/text-approve.eval.ts
index ad8bc008d..0fb2f025c 100644
--- a/e2e/fixtures/agent-tools-hitl/evals/hitl/text-approve.eval.ts
+++ b/e2e/fixtures/agent-tools-hitl/evals/hitl/text-approve.eval.ts
@@ -1,38 +1,14 @@
import { defineEval } from "eve/evals";
-import { GUARDED_ECHO_TOKEN } from "./shared";
-
-/**
- * HITL flow: a plain follow-up message whose text matches an approval option
- * resolves the pending approval the same way as structured inputResponses.
- */
export default defineEval({
tags: ["real-model"],
- description: "HITL smoke: text approve resolves a pending tool approval.",
+ description: "HITL smoke: approval decisions use structured controls.",
async test(t) {
- const parked = await t.send('Call the guarded-echo tool with note "text-approve".');
+ const parked = await t.send('Call the guarded-echo tool with note "button-only".');
parked.calledTool("guarded-echo", { status: "pending", count: 1 });
- t.requireInputRequest({ display: "confirmation", toolName: "guarded-echo" });
-
- const approved = await t.send("approve");
- approved.expectOk();
- approved.event("action.result", {
- data: {
- result: {
- kind: "tool-result",
- output: new RegExp(GUARDED_ECHO_TOKEN),
- toolName: "guarded-echo",
- },
- status: "completed",
- },
- count: 1,
- });
-
+ const request = t.requireInputRequest({ display: "confirmation", toolName: "guarded-echo" });
+ const cancelled = await t.respond([{ optionId: "cancel", requestId: request.requestId }]);
+ cancelled.expectOk();
t.succeeded();
- t.calledTool("guarded-echo", {
- output: new RegExp(GUARDED_ECHO_TOKEN),
- status: "completed",
- count: 1,
- });
},
});
diff --git a/packages/eve/src/context/build-dynamic-tools.ts b/packages/eve/src/context/build-dynamic-tools.ts
index a94ef004f..220454c7c 100644
--- a/packages/eve/src/context/build-dynamic-tools.ts
+++ b/packages/eve/src/context/build-dynamic-tools.ts
@@ -1,4 +1,5 @@
import type { HarnessToolDefinition } from "#harness/execute-tool.js";
+import type { HarnessToolMap } from "#harness/types.js";
import type { ContextKey } from "#context/key.js";
import {
SessionDynamicToolMetadataKey,
@@ -118,6 +119,20 @@ function buildReplayedApproval(
* `LiveStepToolsKey`). Session/turn tools are replayed from durable
* metadata via the bundler's registered step functions.
*/
+export function buildResponseAuthorizationTools(input: {
+ readonly authoredTools: HarnessToolMap;
+ readonly context?: { get<T>(key: ContextKey<T>): T | undefined };
+}): HarnessToolMap {
+ const tools = new Map<string, HarnessToolDefinition>();
+ for (const tool of input.context === undefined ? [] : buildDynamicTools(input.context)) {
+ if (!tools.has(tool.name)) tools.set(tool.name, tool);
+ }
+ for (const [name, tool] of input.authoredTools) {
+ if (!tools.has(name)) tools.set(name, tool);
+ }
+ return tools;
+}
+
export function buildDynamicTools(ctx: {
get<T>(key: ContextKey<T>): T | undefined;
}): readonly HarnessToolDefinition[] {
diff --git a/packages/eve/src/context/dynamic-tool-lifecycle.test.ts b/packages/eve/src/context/dynamic-tool-lifecycle.test.ts
index 1ffec4dbe..8b2593953 100644
--- a/packages/eve/src/context/dynamic-tool-lifecycle.test.ts
+++ b/packages/eve/src/context/dynamic-tool-lifecycle.test.ts
@@ -1,4 +1,4 @@
-import { asSchema } from "ai";
+import { asSchema, jsonSchema } from "ai";
import { describe, expect, it, vi } from "vitest";
import type { DynamicToolEntry } from "#shared/dynamic-tool-definition.js";
@@ -20,10 +20,12 @@ const {
dispatchDynamicToolEvent,
refreshDynamicSessionToolsForRuntimeRevision,
} = await import("#context/dynamic-tool-lifecycle.js");
-const { buildDynamicTools } = await import("#context/build-dynamic-tools.js");
+const { buildDynamicTools, buildResponseAuthorizationTools } =
+ await import("#context/build-dynamic-tools.js");
import { ContextContainer } from "#context/container.js";
import {
+ LiveStepToolsKey,
SessionIdKey,
SessionDynamicToolMetadataKey,
SessionDynamicToolRuntimeRevisionKey,
@@ -728,6 +730,24 @@ describe("dispatchDynamicToolEvent", () => {
expect(getToken).toHaveBeenCalledOnce();
});
+ it("restores cached step tools after virtual context is cleared", async () => {
+ const ctx = createCtx();
+ const resolver = createResolver("api", ["step.started"], () => ({
+ query: createReplayableTool("cached"),
+ }));
+ const event = {
+ type: "step.started",
+ data: { stepIndex: 1, turnId: "turn-1" },
+ } as UnstampedMessageStreamEvent;
+
+ await dispatchDynamicToolEvent({ ctx, event, messages: [], resolvers: [resolver] });
+ ctx.clearVirtualContext();
+ expect(buildDynamicTools(ctx)).toEqual([]);
+
+ await dispatchDynamicToolEvent({ ctx, event, messages: [], resolvers: [resolver] });
+ expect(buildDynamicTools(ctx)[0]?.description).toBe("cached");
+ });
+
it("replaces tools from the same resolver slug (last write wins)", async () => {
const ctx = createCtx();
let callCount = 0;
@@ -1231,6 +1251,41 @@ describe("framework dynamic tools (no bundler transform)", () => {
).resolves.toBe("user-approval");
});
+ it("uses the first dynamic definition for response authorization", () => {
+ const ctx = createCtx();
+ ctx.set(LiveStepToolsKey, [
+ {
+ approval: {
+ request: () => "user-approval",
+ response: async () => ({ status: "allowed" }) as const,
+ },
+ description: "step",
+ execute: () => null,
+ inputSchema: jsonSchema({ type: "object" }),
+ name: "guarded",
+ },
+ ]);
+ ctx.set(SessionDynamicToolMetadataKey, [
+ {
+ approvalResponseStepFnName: "session-authorizer",
+ approvalStepFnName: "session-policy",
+ description: "session",
+ entryKey: "session:guarded",
+ executeStepFnName: "session-execute",
+ inputSchema: { type: "object" },
+ name: "guarded",
+ resolverSlug: "session",
+ },
+ ]);
+
+ const tools = buildResponseAuthorizationTools({
+ authoredTools: new Map(),
+ context: ctx,
+ });
+
+ expect(tools.get("guarded")?.description).toBe("step");
+ });
+
it("replays response authorization from session-scoped dynamic tools", async () => {
const ctx = createCtx();
const response = vi.fn(async () => ({ status: "allowed" }) as const);
diff --git a/packages/eve/src/context/dynamic-tool-lifecycle.ts b/packages/eve/src/context/dynamic-tool-lifecycle.ts
index eb53c2466..e41e69ac4 100644
--- a/packages/eve/src/context/dynamic-tool-lifecycle.ts
+++ b/packages/eve/src/context/dynamic-tool-lifecycle.ts
@@ -355,12 +355,50 @@ async function resolveToolsFromEvent(
// Dispatch: route to the scope-appropriate durable key
// ---------------------------------------------------------------------------
+const resolvedStepTools = new WeakMap<
+ ContextContainer,
+ { readonly coordinate: string; readonly tools: readonly HarnessToolDefinition[] }
+>();
+
/**
* Dispatches a stream event to dynamic tool resolvers. Each
* resolver's metadata replaces its slot (by slug) in the
* scope-appropriate durable key. The tool-loop calls
* {@link buildDynamicTools} to assemble the effective toolset.
*/
+/** Resolves step-scoped tools once for one internal policy/model pass. */
+export async function resolveStepDynamicTools(input: {
+ readonly ctx: ContextContainer;
+ readonly resolvers: readonly ResolvedDynamicToolResolver[];
+ readonly event: UnstampedMessageStreamEvent;
+ readonly messages: readonly ModelMessage[];
+}): Promise<void> {
+ const data = ("data" in input.event ? input.event.data : undefined) as
+ | { readonly stepIndex?: unknown; readonly turnId?: unknown }
+ | undefined;
+ const coordinate =
+ typeof data?.turnId === "string" && typeof data.stepIndex === "number"
+ ? `${data.turnId}:${String(data.stepIndex)}`
+ : undefined;
+ const cached = resolvedStepTools.get(input.ctx);
+ if (coordinate !== undefined && cached?.coordinate === coordinate) {
+ input.ctx.setVirtualContext(LiveStepToolsKey, cached.tools);
+ return;
+ }
+
+ const matching = input.resolvers.filter((resolver) =>
+ resolver.eventNames.includes("step.started"),
+ );
+ const { liveTools } =
+ matching.length === 0
+ ? { liveTools: [] }
+ : await resolveToolsFromEvent(input.ctx, matching, input.event, input.messages);
+ input.ctx.setVirtualContext(LiveStepToolsKey, liveTools);
+ if (coordinate !== undefined) {
+ resolvedStepTools.set(input.ctx, { coordinate, tools: liveTools });
+ }
+}
+
export async function dispatchDynamicToolEvent(input: {
readonly ctx: ContextContainer;
readonly resolvers: readonly ResolvedDynamicToolResolver[];
@@ -371,6 +409,11 @@ export async function dispatchDynamicToolEvent(input: {
if (!ALLOWED_DYNAMIC_TOOL_EVENTS.has(event.type)) return;
+ if (event.type === "step.started") {
+ await resolveStepDynamicTools(input);
+ return;
+ }
+
const matching = resolvers.filter((r) => r.eventNames.includes(event.type));
if (matching.length === 0) {
if (event.type === "session.started") {
@@ -379,15 +422,7 @@ export async function dispatchDynamicToolEvent(input: {
return;
}
- const { metadata, liveTools } = await resolveToolsFromEvent(ctx, matching, event, messages);
-
- // Step-scoped tools store live definitions (with original execute
- // closures) since they re-resolve every step and don't need
- // cross-step replay from durable metadata.
- if (event.type === "step.started") {
- ctx.setVirtualContext(LiveStepToolsKey, liveTools);
- return;
- }
+ const { metadata } = await resolveToolsFromEvent(ctx, matching, event, messages);
// Session/turn: store durable metadata for cross-step replay via
// the bundler's registered step functions.
diff --git a/packages/eve/src/harness/approval-candidates.test.ts b/packages/eve/src/harness/approval-candidates.test.ts
new file mode 100644
index 000000000..6edb8d782
--- /dev/null
+++ b/packages/eve/src/harness/approval-candidates.test.ts
@@ -0,0 +1,279 @@
+import { describe, expect, it } from "vitest";
+
+import type { SessionAuthContext } from "#channel/types.js";
+import {
+ createApprovalCandidate,
+ expireApprovalCandidates,
+ finishApprovalCandidate,
+ getApprovalAuditState,
+ markApprovalCandidateAuthorizationRequired,
+ settleAllowedCandidate,
+ settleDirectApprovalResponse,
+} from "#harness/approval-candidates.js";
+import type { SessionStateMap } from "#harness/types.js";
+
+function responder(principalId: string): SessionAuthContext {
+ return {
+ attributes: { workspace: "T1" },
+ authenticator: "slack-webhook",
+ issuer: "slack:T1",
+ principalId,
+ principalType: "user",
+ };
+}
+
+function create(input: {
+ readonly candidateId: string;
+ readonly principalId: string;
+ readonly requestId?: string;
+ readonly state?: SessionStateMap;
+}) {
+ return createApprovalCandidate({
+ candidateIdPrefix: input.candidateId,
+ createdAt: 100,
+ expiresAt: 700,
+ requestId: input.requestId ?? "request-1",
+ responder: responder(input.principalId),
+ state: input.state,
+ });
+}
+
+describe("approval candidate state", () => {
+ it("persists the complete responder while a candidate is active", () => {
+ const transition = create({ candidateId: "candidate-1", principalId: "U1" });
+
+ expect(transition.changed).toBe(true);
+ expect(getApprovalAuditState(transition.state).activeCandidates).toEqual([
+ {
+ candidateId: "candidate-1",
+ createdAt: 100,
+ expiresAt: 700,
+ requestId: "request-1",
+ responder: {
+ attributes: { workspace: "T1" },
+ authenticator: "slack-webhook",
+ issuer: "slack:T1",
+ principalId: "U1",
+ principalType: "user",
+ },
+ status: "pending",
+ },
+ ]);
+ });
+
+ it("silently deduplicates one responder's active candidate", () => {
+ const first = create({ candidateId: "candidate-1", principalId: "U1" });
+ const duplicate = create({
+ candidateId: "candidate-1",
+ principalId: "U1",
+ state: first.state,
+ });
+
+ expect(duplicate.changed).toBe(false);
+ expect(duplicate.state).toBe(first.state);
+ });
+
+ it("defensively deduplicates the same responder under another id", () => {
+ const first = create({ candidateId: "candidate-1", principalId: "U1" });
+ const duplicate = create({
+ candidateId: "candidate-2",
+ principalId: "U1",
+ state: first.state,
+ });
+
+ expect(duplicate.changed).toBe(false);
+ });
+
+ it("allows different responders to validate concurrently", () => {
+ const first = create({ candidateId: "candidate-1", principalId: "U1" });
+ const second = create({
+ candidateId: "candidate-2",
+ principalId: "U2",
+ state: first.state,
+ });
+
+ expect(second.changed).toBe(true);
+ expect(getApprovalAuditState(second.state).activeCandidates).toHaveLength(2);
+ });
+
+ it("tracks authorization-required state and provider expiry", () => {
+ const first = create({ candidateId: "candidate-1", principalId: "U1" });
+ const state = markApprovalCandidateAuthorizationRequired({
+ authorizationChallenges: [],
+ candidateId: "candidate-1",
+ expiresAt: 500,
+ state: first.state,
+ });
+
+ expect(getApprovalAuditState(state).activeCandidates[0]).toMatchObject({
+ expiresAt: 500,
+ status: "authorization-required",
+ });
+ });
+
+ it("projects the responder to narrow identity in terminal history", () => {
+ const first = create({ candidateId: "candidate-1", principalId: "U1" });
+ const state = finishApprovalCandidate({
+ candidateId: "candidate-1",
+ completedAt: 200,
+ state: first.state,
+ status: "rejected",
+ });
+
+ expect(getApprovalAuditState(state).candidateHistory[0]?.responder).toEqual({
+ authenticator: "slack-webhook",
+ issuer: "slack:T1",
+ principalId: "U1",
+ principalType: "user",
+ });
+ });
+
+ it("persists safe rejection feedback and permits a later retry", () => {
+ const first = create({ candidateId: "candidate-1", principalId: "U1" });
+ const rejected = finishApprovalCandidate({
+ candidateId: "candidate-1",
+ completedAt: 200,
+ reason: "GitHub write permission is required.",
+ state: first.state,
+ status: "rejected",
+ });
+ const retry = create({
+ candidateId: "candidate-1",
+ principalId: "U1",
+ state: rejected,
+ });
+
+ expect(getApprovalAuditState(retry.state).candidateHistory).toEqual([
+ expect.objectContaining({
+ candidateId: "candidate-1",
+ reason: "GitHub write permission is required.",
+ status: "rejected",
+ }),
+ ]);
+ expect(retry.changed).toBe(true);
+ });
+
+ it("expires stale candidates intrinsically before creating another candidate", () => {
+ const first = create({ candidateId: "candidate-1", principalId: "U1" });
+ const next = createApprovalCandidate({
+ candidateIdPrefix: "candidate-2",
+ createdAt: 800,
+ expiresAt: 1_400,
+ requestId: "request-1",
+ responder: responder("U2"),
+ state: first.state,
+ });
+
+ expect(getApprovalAuditState(next.state)).toMatchObject({
+ activeCandidates: [expect.objectContaining({ candidateId: "candidate-2" })],
+ candidateHistory: [
+ expect.objectContaining({ candidateId: "candidate-1", status: "timed-out" }),
+ ],
+ });
+ });
+
+ it("expires only candidates whose deadline has passed", () => {
+ const first = create({ candidateId: "candidate-1", principalId: "U1" });
+ const second = createApprovalCandidate({
+ candidateIdPrefix: "candidate-2",
+ createdAt: 100,
+ expiresAt: 900,
+ requestId: "request-1",
+ responder: responder("U2"),
+ state: first.state,
+ });
+ const state = expireApprovalCandidates({ now: 800, state: second.state });
+ const audit = getApprovalAuditState(state);
+
+ expect(audit.activeCandidates.map((candidate) => candidate.candidateId)).toEqual([
+ "candidate-2",
+ ]);
+ expect(audit.candidateHistory).toEqual([
+ expect.objectContaining({ candidateId: "candidate-1", status: "timed-out" }),
+ ]);
+ });
+
+ it("atomically settles the first allowed candidate and stales competitors", () => {
+ const first = create({ candidateId: "candidate-1", principalId: "U1" });
+ const second = create({
+ candidateId: "candidate-2",
+ principalId: "U2",
+ state: first.state,
+ });
+ const winner = settleAllowedCandidate({
+ candidateId: "candidate-2",
+ settledAt: 300,
+ state: second.state,
+ });
+ const late = settleAllowedCandidate({
+ candidateId: "candidate-1",
+ settledAt: 400,
+ state: winner.state,
+ });
+ const audit = getApprovalAuditState(late.state);
+
+ expect(winner.changed).toBe(true);
+ expect(late.changed).toBe(false);
+ expect(audit.activeCandidates).toEqual([]);
+ expect(audit.candidateHistory).toEqual(
+ expect.arrayContaining([
+ expect.objectContaining({ candidateId: "candidate-1", status: "stale" }),
+ expect.objectContaining({ candidateId: "candidate-2", status: "allowed" }),
+ ]),
+ );
+ });
+
+ it("lets Cancel win atomically and stales every Allow candidate", () => {
+ const first = create({ candidateId: "candidate-1", principalId: "U1" });
+ const cancelled = settleDirectApprovalResponse({
+ actor: responder("U2"),
+ outcome: "cancelled",
+ requestId: "request-1",
+ settledAt: 250,
+ state: first.state,
+ });
+ const late = settleAllowedCandidate({
+ candidateId: "candidate-1",
+ settledAt: 300,
+ state: cancelled.state,
+ });
+
+ expect(cancelled.changed).toBe(true);
+ expect(late.changed).toBe(false);
+ });
+
+ it("does not let a candidate start after terminal settlement", () => {
+ const first = create({ candidateId: "candidate-1", principalId: "U1" });
+ const settled = settleAllowedCandidate({
+ candidateId: "candidate-1",
+ settledAt: 300,
+ state: first.state,
+ });
+ const late = create({
+ candidateId: "candidate-2",
+ principalId: "U2",
+ state: settled.state,
+ });
+
+ expect(late.changed).toBe(false);
+ });
+
+ it("keeps unrelated requests active when another request settles", () => {
+ const first = create({ candidateId: "candidate-1", principalId: "U1" });
+ const unrelated = create({
+ candidateId: "candidate-2",
+ principalId: "U2",
+ requestId: "request-2",
+ state: first.state,
+ });
+ const settled = settleAllowedCandidate({
+ candidateId: "candidate-1",
+ settledAt: 300,
+ state: unrelated.state,
+ });
+
+ expect(getApprovalAuditState(settled.state).activeCandidates).toEqual([
+ expect.objectContaining({ candidateId: "candidate-2", requestId: "request-2" }),
+ ]);
+ });
+});
diff --git a/packages/eve/src/harness/approval-candidates.ts b/packages/eve/src/harness/approval-candidates.ts
new file mode 100644
index 000000000..2c641e2db
--- /dev/null
+++ b/packages/eve/src/harness/approval-candidates.ts
@@ -0,0 +1,386 @@
+import type { SessionAuthContext } from "#channel/types.js";
+import type { AuthorizationChallenge } from "#harness/authorization.js";
+import type { SessionStateMap } from "#harness/types.js";
+
+const APPROVAL_STATE_KEY = "eve.runtime.hitl.approvalState";
+
+export type ApprovalCandidateStatus =
+ | "pending"
+ | "authorization-required"
+ | "allowed"
+ | "rejected"
+ | "failed"
+ | "timed-out"
+ | "stale";
+
+export interface ApprovalCandidateAuditRecord {
+ readonly candidateId: string;
+ readonly requestId: string;
+ readonly responder: ApprovalResponderIdentity;
+ readonly status: ApprovalCandidateStatus;
+ readonly createdAt: number;
+ readonly completedAt?: number;
+ readonly expiresAt?: number;
+ readonly reason?: string;
+}
+
+export interface ApprovalResponderIdentity {
+ readonly authenticator: string;
+ readonly issuer?: string;
+ readonly principalId: string;
+ readonly principalType: string;
+}
+
+export interface ApprovalSettlementAuditRecord {
+ readonly actor: ApprovalResponderIdentity;
+ readonly outcome: "allowed" | "cancelled";
+ readonly requestId: string;
+ readonly settledAt: number;
+ readonly candidateId?: string;
+}
+
+export interface ActiveApprovalCandidate {
+ readonly candidateId: string;
+ readonly requestId: string;
+ readonly responder: SessionAuthContext;
+ readonly status: "pending" | "authorization-required";
+ readonly createdAt: number;
+ readonly expiresAt: number;
+ readonly authorizationChallenges?: readonly AuthorizationChallenge[];
+}
+
+interface DurableApprovalState {
+ readonly activeCandidates: Readonly<Record<string, ActiveApprovalCandidate>>;
+ readonly nextCandidateSequence: number;
+ readonly candidateHistory: readonly ApprovalCandidateAuditRecord[];
+ readonly settlements: Readonly<Record<string, ApprovalSettlementAuditRecord>>;
+}
+
+export interface ApprovalStateTransition {
+ readonly changed: boolean;
+ readonly state: SessionStateMap | undefined;
+}
+
+/** Creates or deduplicates one responder's Allow candidate for a pending request. */
+export function createApprovalCandidate(input: {
+ readonly candidateIdPrefix: string;
+ readonly createdAt: number;
+ readonly expiresAt: number;
+ readonly requestId: string;
+ readonly responder: SessionAuthContext;
+ readonly state: SessionStateMap | undefined;
+}): ApprovalStateTransition {
+ const expiredState = expireApprovalCandidates({ now: input.createdAt, state: input.state });
+ const approvalState = readApprovalState(expiredState);
+ const settlement = approvalState.settlements[input.requestId];
+ if (settlement !== undefined) {
+ return { changed: false, state: expiredState };
+ }
+
+ const responder = input.responder;
+ const duplicate = Object.values(approvalState.activeCandidates).find(
+ (candidate) =>
+ candidate.requestId === input.requestId && sameResponder(candidate.responder, responder),
+ );
+ if (duplicate !== undefined) {
+ return { changed: false, state: expiredState };
+ }
+
+ const prefixWasUsed =
+ approvalState.activeCandidates[input.candidateIdPrefix] !== undefined ||
+ approvalState.candidateHistory.some(
+ (candidate) => candidate.candidateId === input.candidateIdPrefix,
+ );
+ const candidateId = prefixWasUsed
+ ? `${input.candidateIdPrefix}.${approvalState.nextCandidateSequence.toString(36)}`
+ : input.candidateIdPrefix;
+ if (
+ approvalState.activeCandidates[candidateId] !== undefined ||
+ approvalState.candidateHistory.some((candidate) => candidate.candidateId === candidateId)
+ ) {
+ throw new Error(`Approval candidate id collision: "${candidateId}".`);
+ }
+
+ const candidate: ActiveApprovalCandidate = {
+ candidateId,
+ createdAt: input.createdAt,
+ expiresAt: input.expiresAt,
+ requestId: input.requestId,
+ responder,
+ status: "pending",
+ };
+ const next: DurableApprovalState = {
+ ...approvalState,
+ activeCandidates: { ...approvalState.activeCandidates, [candidate.candidateId]: candidate },
+ nextCandidateSequence: approvalState.nextCandidateSequence + 1,
+ };
+ return { changed: true, state: writeApprovalState(expiredState, next) };
+}
+
+/** Marks a candidate as waiting on a private authorization challenge. */
+export function markApprovalCandidateAuthorizationRequired(input: {
+ readonly authorizationChallenges: readonly AuthorizationChallenge[];
+ readonly candidateId: string;
+ readonly expiresAt?: number;
+ readonly state: SessionStateMap | undefined;
+}): SessionStateMap | undefined {
+ const approvalState = readApprovalState(input.state);
+ const candidate = approvalState.activeCandidates[input.candidateId];
+ if (candidate === undefined) return input.state;
+ const nextCandidate: ActiveApprovalCandidate = {
+ ...candidate,
+ authorizationChallenges: input.authorizationChallenges,
+ expiresAt: input.expiresAt ?? candidate.expiresAt,
+ status: "authorization-required",
+ };
+ return writeApprovalState(input.state, {
+ ...approvalState,
+ activeCandidates: { ...approvalState.activeCandidates, [input.candidateId]: nextCandidate },
+ });
+}
+
+/** Finishes one candidate without settling the shared request. */
+export function finishApprovalCandidate(input: {
+ readonly candidateId: string;
+ readonly completedAt: number;
+ readonly reason?: string;
+ readonly state: SessionStateMap | undefined;
+ readonly status: Exclude<ApprovalCandidateStatus, "pending" | "authorization-required">;
+}): SessionStateMap | undefined {
+ const approvalState = readApprovalState(input.state);
+ const candidate = approvalState.activeCandidates[input.candidateId];
+ if (candidate === undefined) return input.state;
+ const activeCandidates = { ...approvalState.activeCandidates };
+ delete activeCandidates[input.candidateId];
+ return writeApprovalState(input.state, {
+ ...approvalState,
+ activeCandidates,
+ candidateHistory: [
+ ...approvalState.candidateHistory,
+ toCandidateAuditRecord({
+ candidate,
+ completedAt: input.completedAt,
+ reason: input.reason,
+ status: input.status,
+ }),
+ ],
+ });
+}
+
+/** Expires active candidates whose deterministic deadline has passed. */
+export function expireApprovalCandidates(input: {
+ readonly now: number;
+ readonly state: SessionStateMap | undefined;
+}): SessionStateMap | undefined {
+ let state = input.state;
+ const candidates = Object.values(readApprovalState(state).activeCandidates);
+ for (const candidate of candidates) {
+ if (candidate.expiresAt > input.now) continue;
+ state = finishApprovalCandidate({
+ candidateId: candidate.candidateId,
+ completedAt: input.now,
+ state,
+ status: "timed-out",
+ });
+ }
+ return state;
+}
+
+/** Atomically settles an allowed candidate; every losing candidate becomes stale. */
+export function settleAllowedCandidate(input: {
+ readonly candidateId: string;
+ readonly settledAt: number;
+ readonly state: SessionStateMap | undefined;
+}): ApprovalStateTransition {
+ const expiredState = expireApprovalCandidates({ now: input.settledAt, state: input.state });
+ const approvalState = readApprovalState(expiredState);
+ const candidate = approvalState.activeCandidates[input.candidateId];
+ if (candidate === undefined) {
+ const historical = approvalState.candidateHistory.find(
+ (entry) => entry.candidateId === input.candidateId,
+ );
+ const settlement = historical && approvalState.settlements[historical.requestId];
+ if (settlement !== undefined) {
+ return { changed: false, state: expiredState };
+ }
+ throw new Error(`Unknown approval candidate "${input.candidateId}".`);
+ }
+ return settleRequest({
+ actor: projectResponder(candidate.responder),
+ candidateId: candidate.candidateId,
+ outcome: "allowed",
+ requestId: candidate.requestId,
+ settledAt: input.settledAt,
+ state: expiredState,
+ });
+}
+
+/** Atomically settles a direct authenticated approval response. */
+export function settleDirectApprovalResponse(input: {
+ readonly actor: SessionAuthContext;
+ readonly outcome: "allowed" | "cancelled";
+ readonly requestId: string;
+ readonly settledAt: number;
+ readonly state: SessionStateMap | undefined;
+}): ApprovalStateTransition {
+ const state = expireApprovalCandidates({ now: input.settledAt, state: input.state });
+ return settleRequest({
+ actor: projectResponder(input.actor),
+ outcome: input.outcome,
+ requestId: input.requestId,
+ settledAt: input.settledAt,
+ state,
+ });
+}
+
+/** Returns one active candidate by id. */
+export function getActiveApprovalCandidate(
+ state: SessionStateMap | undefined,
+ candidateId: string,
+): ActiveApprovalCandidate | undefined {
+ return readApprovalState(state).activeCandidates[candidateId];
+}
+
+/** Returns a copy of the durable candidate/audit state for inspection and replay. */
+export function getApprovalAuditState(state: SessionStateMap | undefined): {
+ readonly activeCandidates: readonly ActiveApprovalCandidate[];
+ readonly candidateHistory: readonly ApprovalCandidateAuditRecord[];
+ readonly settlements: readonly ApprovalSettlementAuditRecord[];
+} {
+ const approvalState = readApprovalState(state);
+ return {
+ activeCandidates: Object.values(approvalState.activeCandidates),
+ candidateHistory: approvalState.candidateHistory,
+ settlements: Object.values(approvalState.settlements),
+ };
+}
+
+function settleRequest(input: {
+ readonly actor: ApprovalResponderIdentity;
+ readonly candidateId?: string;
+ readonly outcome: ApprovalSettlementAuditRecord["outcome"];
+ readonly requestId: string;
+ readonly settledAt: number;
+ readonly state: SessionStateMap | undefined;
+}): ApprovalStateTransition {
+ const approvalState = readApprovalState(input.state);
+ const existing = approvalState.settlements[input.requestId];
+ if (existing !== undefined) {
+ return { changed: false, state: input.state };
+ }
+
+ const settlement: ApprovalSettlementAuditRecord = {
+ actor: input.actor,
+ candidateId: input.candidateId,
+ outcome: input.outcome,
+ requestId: input.requestId,
+ settledAt: input.settledAt,
+ };
+ const activeCandidates: Record<string, ActiveApprovalCandidate> = {};
+ const candidateHistory = [...approvalState.candidateHistory];
+ for (const candidate of Object.values(approvalState.activeCandidates)) {
+ if (candidate.requestId !== input.requestId) {
+ activeCandidates[candidate.candidateId] = candidate;
+ continue;
+ }
+ candidateHistory.push(
+ toCandidateAuditRecord({
+ candidate,
+ completedAt: input.settledAt,
+ status: candidate.candidateId === input.candidateId ? "allowed" : "stale",
+ }),
+ );
+ }
+ const next: DurableApprovalState = {
+ activeCandidates,
+ candidateHistory,
+ nextCandidateSequence: approvalState.nextCandidateSequence,
+ settlements: { ...approvalState.settlements, [input.requestId]: settlement },
+ };
+ return { changed: true, state: writeApprovalState(input.state, next) };
+}
+
+function toCandidateAuditRecord(input: {
+ readonly candidate: ActiveApprovalCandidate;
+ readonly completedAt: number;
+ readonly reason?: string;
+ readonly status: Exclude<ApprovalCandidateStatus, "pending" | "authorization-required">;
+}): ApprovalCandidateAuditRecord {
+ const {
+ authorizationChallenges: _authorizationChallenges,
+ responder,
+ ...candidate
+ } = input.candidate;
+ return {
+ ...candidate,
+ completedAt: input.completedAt,
+ responder: projectResponder(responder),
+ reason: input.reason,
+ status: input.status,
+ };
+}
+
+function projectResponder(responder: SessionAuthContext): ApprovalResponderIdentity {
+ return {
+ authenticator: responder.authenticator,
+ issuer: responder.issuer,
+ principalId: responder.principalId,
+ principalType: responder.principalType,
+ };
+}
+
+function sameResponder(
+ a: Pick<SessionAuthContext, "authenticator" | "issuer" | "principalId" | "principalType">,
+ b: Pick<SessionAuthContext, "authenticator" | "issuer" | "principalId" | "principalType">,
+): boolean {
+ return (
+ a.authenticator === b.authenticator &&
+ a.issuer === b.issuer &&
+ a.principalId === b.principalId &&
+ a.principalType === b.principalType
+ );
+}
+
+function readApprovalState(state: SessionStateMap | undefined): DurableApprovalState {
+ const value = state?.[APPROVAL_STATE_KEY];
+ if (typeof value !== "object" || value === null) {
+ return {
+ activeCandidates: {},
+ candidateHistory: [],
+ nextCandidateSequence: 0,
+ settlements: {},
+ };
+ }
+ const candidate = value as Partial<DurableApprovalState>;
+ return {
+ activeCandidates:
+ typeof candidate.activeCandidates === "object" && candidate.activeCandidates !== null
+ ? candidate.activeCandidates
+ : {},
+ candidateHistory: Array.isArray(candidate.candidateHistory) ? candidate.candidateHistory : [],
+ nextCandidateSequence:
+ typeof candidate.nextCandidateSequence === "number" &&
+ Number.isSafeInteger(candidate.nextCandidateSequence) &&
+ candidate.nextCandidateSequence >= 0
+ ? candidate.nextCandidateSequence
+ : deriveNextCandidateSequence(candidate),
+ settlements:
+ typeof candidate.settlements === "object" && candidate.settlements !== null
+ ? candidate.settlements
+ : {},
+ };
+}
+
+function deriveNextCandidateSequence(state: Partial<DurableApprovalState>): number {
+ return (
+ Object.keys(state.activeCandidates ?? {}).length +
+ (Array.isArray(state.candidateHistory) ? state.candidateHistory.length : 0)
+ );
+}
+
+function writeApprovalState(
+ state: SessionStateMap | undefined,
+ approvalState: DurableApprovalState,
+): SessionStateMap {
+ return { ...state, [APPROVAL_STATE_KEY]: approvalState };
+}
diff --git a/packages/eve/src/harness/approval-delivery-coordinator.test.ts b/packages/eve/src/harness/approval-delivery-coordinator.test.ts
new file mode 100644
index 000000000..f6ba09389
--- /dev/null
+++ b/packages/eve/src/harness/approval-delivery-coordinator.test.ts
@@ -0,0 +1,65 @@
+import { describe, expect, it } from "vitest";
+
+import type { SessionAuthContext } from "#channel/types.js";
+import { settleDirectApprovalResponse } from "#harness/approval-candidates.js";
+import { coordinateApprovalDelivery } from "#harness/approval-delivery-coordinator.js";
+import { appendPendingInputBatch } from "#harness/pending-input-batches.js";
+import type { HarnessSession } from "#harness/types.js";
+import type { InputRequest } from "#runtime/input/types.js";
+
+const request: InputRequest = {
+ action: { callId: "call-1", input: { marker: "durable" }, kind: "tool-call", toolName: "gate" },
+ allowFreeform: false,
+ display: "confirmation",
+ kind: "tool-approval",
+ options: [
+ { id: "approve", label: "Approve" },
+ { id: "cancel", label: "Cancel" },
+ ],
+ prompt: "Approve tool call: gate",
+ requestId: "approval-1",
+};
+const responder: SessionAuthContext = {
+ attributes: {},
+ authenticator: "test",
+ issuer: "test",
+ principalId: "user-1",
+ principalType: "user",
+};
+
+function parkedSession(): HarnessSession {
+ return appendPendingInputBatch({
+ requests: [request],
+ responseAuthRequiredRequestIds: [request.requestId],
+ responseMessages: [],
+ session: {
+ agent: { modelReference: { id: "test" }, system: "", tools: [] },
+ compaction: { recentWindowSize: 10, threshold: 0.8 },
+ continuationToken: "test",
+ history: [],
+ sessionId: "session-1",
+ },
+ });
+}
+
+describe("coordinateApprovalDelivery", () => {
+ it("recovers an allowed settlement before its synthetic response is consumed", async () => {
+ const parked = parkedSession();
+ const settled = settleDirectApprovalResponse({
+ actor: responder,
+ outcome: "allowed",
+ requestId: request.requestId,
+ settledAt: 100,
+ state: parked.state,
+ });
+ const result = await coordinateApprovalDelivery({
+ now: 101,
+ session: { ...parked, state: settled.state },
+ tools: new Map(),
+ });
+ expect(result.kind).toBe("continue");
+ expect(result.stepInput?.inputResponses).toEqual([
+ { optionId: "approve", requestId: request.requestId },
+ ]);
+ });
+});
diff --git a/packages/eve/src/harness/approval-delivery-coordinator.ts b/packages/eve/src/harness/approval-delivery-coordinator.ts
new file mode 100644
index 000000000..ae988e69c
--- /dev/null
+++ b/packages/eve/src/harness/approval-delivery-coordinator.ts
@@ -0,0 +1,553 @@
+import type { SessionAuthContext } from "#channel/types.js";
+import { buildCallbackContext } from "#context/build-callback-context.js";
+import { contextStorage } from "#context/container.js";
+import { AuthKey, SessionKey } from "#context/keys.js";
+import {
+ buildApprovalResponseAuth,
+ handleApprovalResponsePolicyError,
+} from "#execution/tool-auth.js";
+import {
+ createApprovalCandidate,
+ expireApprovalCandidates,
+ finishApprovalCandidate,
+ getActiveApprovalCandidate,
+ getApprovalAuditState,
+ markApprovalCandidateAuthorizationRequired,
+ settleAllowedCandidate,
+ settleDirectApprovalResponse,
+ type ActiveApprovalCandidate,
+} from "#harness/approval-candidates.js";
+import {
+ clearPendingAuthorization,
+ getAuthorizationResult,
+ getPendingAuthorization,
+ isAuthorizationSignal,
+ type AuthorizationChallenge,
+} from "#harness/authorization.js";
+import { isApprovalRequest } from "#harness/input-request-class.js";
+import { getPendingInputBatches } from "#harness/pending-input-batches.js";
+import type { HarnessSession, HarnessToolMap, StepInput } from "#harness/types.js";
+import type { InputRequest } from "#runtime/input/types.js";
+
+const UNAUTHENTICATED_APPROVAL_FEEDBACK = "Authentication is required to respond to this approval.";
+const TEXT_APPROVAL_FEEDBACK =
+ "Please use the Approve or Cancel buttons to respond to this approval.";
+const APPROVAL_AUTHORIZER_TIMEOUT_MS = 10_000;
+const APPROVAL_CANDIDATE_TTL_MS = 10 * 60_000;
+
+export interface ApprovalDeliveryResult {
+ readonly challenges: readonly AuthorizationChallenge[];
+ readonly feedback: readonly string[];
+ readonly kind: "continue" | "continue-coordination" | "authorization-required" | "park";
+ readonly session: HarnessSession;
+ readonly stepInput?: StepInput;
+}
+
+/**
+ * Advances approval state by one durable phase.
+ *
+ * | State | Input | Transition |
+ * | --- | --- | --- |
+ * | pending request | Approve | create responder-bound candidate |
+ * | pending request | Cancel | settle cancelled and stale candidates |
+ * | pending candidate | coordinator pass | run current authorizer |
+ * | pending candidate | allowed | settle approved and stale competitors |
+ * | pending candidate | rejected/error/expiry | append terminal history |
+ * | pending candidate | authorization required | persist private challenge |
+ * | authorization required | matching callback | re-run current authorizer |
+ * | settled request | any later response | no state change |
+ *
+ * Delivery ingestion returns before authorizer work so Cancel and candidate
+ * creation commit before long-running policy execution. Candidate results also
+ * commit before lifecycle events are projected by the next stack layer.
+ */
+/** Returns whether this invocation should prepare tools for persisted policy work. */
+export function shouldPrepareApprovalPolicyTools(input: {
+ readonly now?: number;
+ readonly session: HarnessSession;
+ readonly stepInput?: StepInput;
+}): boolean {
+ const batches = getPendingInputBatches(input.session.state);
+ const responses = [
+ ...(input.stepInput?.attributedInputResponses ?? []).map(({ response }) => response),
+ ...(input.stepInput?.inputResponses ?? []),
+ ];
+ if (
+ batches.some((batch) =>
+ batch.requests.some(
+ (request) =>
+ isApprovalRequest(request) &&
+ responses.some((response) => response.requestId === request.requestId),
+ ),
+ )
+ ) {
+ return false;
+ }
+
+ const now = input.now ?? Date.now();
+ return getApprovalAuditState(input.session.state).activeCandidates.some(
+ (candidate) =>
+ candidate.expiresAt > now &&
+ (candidate.status === "pending" ||
+ (candidate.authorizationChallenges?.some(
+ (challenge) => getAuthorizationResult(challenge.name) !== undefined,
+ ) ??
+ false)),
+ );
+}
+
+export async function coordinateApprovalDelivery(input: {
+ readonly now?: number;
+ readonly session: HarnessSession;
+ readonly stepInput?: StepInput;
+ readonly tools: HarnessToolMap;
+}): Promise<ApprovalDeliveryResult> {
+ const now = input.now ?? Date.now();
+ const expiredChallengeNames = getApprovalAuditState(input.session.state)
+ .activeCandidates.filter((candidate) => candidate.expiresAt <= now)
+ .flatMap(
+ (candidate) => candidate.authorizationChallenges?.map((challenge) => challenge.name) ?? [],
+ );
+ const expiredState = expireApprovalCandidates({ now, state: input.session.state });
+ let session: HarnessSession = {
+ ...input.session,
+ state: clearPendingAuthorization(expiredState, expiredChallengeNames),
+ };
+ const audit = getApprovalAuditState(session.state);
+ const batches = getPendingInputBatches(session.state);
+ const pendingRequestIds = new Set(
+ batches.flatMap((batch) => batch.requests.map((request) => request.requestId)),
+ );
+ const allowedRequestIds = new Set(
+ audit.settlements
+ .filter(
+ (settlement) =>
+ settlement.outcome === "allowed" && pendingRequestIds.has(settlement.requestId),
+ )
+ .map((settlement) => settlement.requestId),
+ );
+ const settledRequestIds = new Set(audit.settlements.map((settlement) => settlement.requestId));
+ const discardedDuplicate = hasResponseForRequest(input.stepInput, settledRequestIds);
+ const deduplicatedInput = discardedDuplicate
+ ? removeConsumedResponses(input.stepInput, settledRequestIds)
+ : input.stepInput;
+ if (
+ discardedDuplicate &&
+ allowedRequestIds.size === 0 &&
+ !hasMeaningfulInput(deduplicatedInput)
+ ) {
+ return deliveryResult(session, deduplicatedInput, "park");
+ }
+ if (batches.length === 0) return deliveryResult(session, deduplicatedInput);
+
+ const stepInput = deduplicatedInput;
+ const authorizationRequiredRequestIds = new Set(
+ batches.flatMap((batch) => batch.responseAuthRequiredRequestIds ?? []),
+ );
+ const allRequests = batches.flatMap((batch) => batch.requests);
+ const requests = new Map(allRequests.map((request) => [request.requestId, request]));
+ if (
+ stepInput?.message !== undefined &&
+ (stepInput.attributedInputResponses?.length ?? 0) === 0 &&
+ (stepInput.inputResponses?.length ?? 0) === 0 &&
+ audit.activeCandidates.length === 0 &&
+ authorizationRequiredRequestIds.size > 0
+ ) {
+ return deliveryResult(
+ session,
+ { ...stepInput, message: undefined, messageAuth: undefined },
+ "park",
+ [],
+ [TEXT_APPROVAL_FEEDBACK],
+ );
+ }
+ const challenges: AuthorizationChallenge[] = [];
+ const feedback: string[] = [];
+ const consumed = new Set<string>();
+ let didCommit = false;
+ const candidatesAtStart = getApprovalAuditState(session.state).activeCandidates;
+
+ const deliveredResponses = [
+ ...(stepInput?.attributedInputResponses ?? []),
+ ...(stepInput?.inputResponses ?? []).map((response) => ({ auth: undefined, response })),
+ ];
+ for (const { auth: attributedResponder, response } of deliveredResponses) {
+ const request = requests.get(response.requestId);
+ if (request === undefined || !isApprovalRequest(request)) continue;
+
+ const requiresAuthorization = authorizationRequiredRequestIds.has(response.requestId);
+ if (!requiresAuthorization) {
+ const context = contextStorage.getStore();
+ const responder =
+ attributedResponder !== undefined
+ ? attributedResponder
+ : (context?.get(AuthKey) ?? context?.get(SessionKey)?.auth.current ?? null);
+ if (
+ responder !== null &&
+ (response.optionId === "approve" || response.optionId === "cancel")
+ ) {
+ const settled = settleDirectApprovalResponse({
+ actor: responder,
+ outcome: response.optionId === "approve" ? "allowed" : "cancelled",
+ requestId: response.requestId,
+ settledAt: now,
+ state: session.state,
+ });
+ session = { ...session, state: settled.state };
+ didCommit ||= settled.changed;
+ }
+ continue;
+ }
+ consumed.add(response.requestId);
+
+ if (response.optionId === "cancel") {
+ const responder =
+ attributedResponder !== undefined
+ ? attributedResponder
+ : buildCallbackContext().session.auth.current;
+ if (responder === null) {
+ feedback.push(UNAUTHENTICATED_APPROVAL_FEEDBACK);
+ continue;
+ }
+ const settled = settleDirectApprovalResponse({
+ actor: responder,
+ outcome: "cancelled",
+ requestId: response.requestId,
+ settledAt: now,
+ state: session.state,
+ });
+ session = { ...session, state: settled.state };
+ didCommit ||= settled.changed;
+ continue;
+ }
+
+ if (response.optionId !== "approve") continue;
+ const responder =
+ attributedResponder !== undefined
+ ? attributedResponder
+ : buildCallbackContext().session.auth.current;
+ if (responder === null) {
+ feedback.push(UNAUTHENTICATED_APPROVAL_FEEDBACK);
+ continue;
+ }
+
+ const created = createApprovalCandidate({
+ candidateIdPrefix: approvalCandidateIdPrefix(request.requestId, responder),
+ createdAt: now,
+ expiresAt: now + APPROVAL_CANDIDATE_TTL_MS,
+ requestId: request.requestId,
+ responder,
+ state: session.state,
+ });
+ session = { ...session, state: created.state };
+ didCommit ||= created.changed;
+ }
+
+ const remainingStepInput = removeConsumedResponses(stepInput, consumed);
+ if (consumed.size > 0) {
+ return deliveryResult(
+ session,
+ remainingStepInput,
+ didCommit ? "continue-coordination" : "continue",
+ [],
+ feedback,
+ );
+ }
+ if (didCommit) {
+ return deliveryResult(session, remainingStepInput, "continue", [], feedback);
+ }
+
+ // Candidates are persisted in an earlier pass. Run pending candidates and
+ // resume only authorization-required candidates whose callback arrived.
+ const parkedChallengeNames = new Set(
+ getPendingAuthorization(session.state)?.challenges.map((challenge) => challenge.name) ?? [],
+ );
+ for (const candidate of candidatesAtStart) {
+ if (candidate.status === "authorization-required") {
+ const candidateChallenges = candidate.authorizationChallenges ?? [];
+ const hasCallback = candidateChallenges.some(
+ (challenge) => getAuthorizationResult(challenge.name) !== undefined,
+ );
+ if (!hasCallback) {
+ challenges.push(
+ ...candidateChallenges.filter((challenge) => !parkedChallengeNames.has(challenge.name)),
+ );
+ continue;
+ }
+ }
+
+ const request = requests.get(candidate.requestId);
+ if (
+ request === undefined ||
+ getActiveApprovalCandidate(session.state, candidate.candidateId) === undefined
+ ) {
+ continue;
+ }
+ const processed = await authorizeCandidate({
+ candidateId: candidate.candidateId,
+ now,
+ request,
+ responder: candidate.responder,
+ session,
+ tools: input.tools,
+ });
+ session = processed.session;
+ didCommit ||= processed.didCommit;
+ challenges.push(...processed.challenges);
+ const settlement = getApprovalAuditState(session.state).settlements.find(
+ (entry) => entry.requestId === candidate.requestId,
+ );
+ if (settlement?.outcome === "allowed") allowedRequestIds.add(candidate.requestId);
+ }
+
+ const resumedStepInput = appendAllowedResponses(remainingStepInput, allowedRequestIds);
+ if (allowedRequestIds.size > 0) {
+ return deliveryResult(session, resumedStepInput, "continue");
+ }
+ return didCommit
+ ? deliveryResult(session, resumedStepInput, "continue-coordination")
+ : deliveryResult(
+ session,
+ resumedStepInput,
+ challenges.length > 0 ? "authorization-required" : "continue",
+ challenges,
+ );
+}
+
+async function authorizeCandidate(input: {
+ readonly candidateId: string;
+ readonly now: number;
+ readonly request: InputRequest;
+ readonly responder: ActiveApprovalCandidate["responder"];
+ readonly session: HarnessSession;
+ readonly tools: HarnessToolMap;
+}): Promise<{
+ readonly challenges: readonly AuthorizationChallenge[];
+ readonly didCommit: boolean;
+ readonly session: HarnessSession;
+}> {
+ // Expiry is checked again immediately before callback/policy execution.
+ let session = {
+ ...input.session,
+ state: expireApprovalCandidates({ now: input.now, state: input.session.state }),
+ };
+ if (getActiveApprovalCandidate(session.state, input.candidateId) === undefined) {
+ return { challenges: [], didCommit: false, session };
+ }
+
+ const approval = input.tools.get(input.request.action.toolName)?.approval;
+ const responsePolicy =
+ approval !== undefined && typeof approval !== "function" ? approval.response : undefined;
+ if (responsePolicy === undefined) {
+ return failCandidate({
+ ...input,
+ reason: "Approval authorization is temporarily unavailable. Please try again.",
+ session,
+ });
+ }
+
+ try {
+ const context = buildCallbackContext();
+ const outcome = await withAuthorizerTimeout(
+ responsePolicy({
+ auth: buildApprovalResponseAuth({
+ responder: input.responder,
+ scope: input.candidateId,
+ }),
+ request: {
+ callId: input.request.action.callId,
+ requestId: input.request.requestId,
+ toolInput: input.request.action.input,
+ toolName: input.request.action.toolName,
+ },
+ response: { decision: "approve" },
+ responder: input.responder,
+ session: {
+ id: context.session.id,
+ initiator: context.session.auth.initiator,
+ parent: context.session.parent,
+ turn: context.session.turn,
+ },
+ }),
+ );
+ if (outcome.status === "rejected") {
+ session = {
+ ...session,
+ state: finishApprovalCandidate({
+ candidateId: input.candidateId,
+ completedAt: input.now,
+ reason: outcome.reason,
+ state: session.state,
+ status: "rejected",
+ }),
+ };
+ return { challenges: [], didCommit: true, session };
+ }
+ if (outcome.status !== "allowed") {
+ return failCandidate({ ...input, session });
+ }
+
+ const settled = settleAllowedCandidate({
+ candidateId: input.candidateId,
+ settledAt: input.now,
+ state: session.state,
+ });
+ return {
+ challenges: [],
+ didCommit: settled.changed,
+ session: { ...session, state: settled.state },
+ };
+ } catch (error) {
+ const authorization = await handleApprovalResponsePolicyError(error).catch(() => undefined);
+ if (isAuthorizationSignal(authorization)) {
+ const providerExpiresAt = authorization.challenges
+ .map((entry) => Date.parse(entry.challenge.expiresAt ?? ""))
+ .filter(Number.isFinite)
+ .sort((a, b) => a - b)[0];
+ session = {
+ ...session,
+ state: markApprovalCandidateAuthorizationRequired({
+ authorizationChallenges: authorization.challenges.map((challenge) => ({
+ ...challenge,
+ candidateId: input.candidateId,
+ })),
+ candidateId: input.candidateId,
+ expiresAt: providerExpiresAt,
+ state: session.state,
+ }),
+ };
+ return {
+ challenges: authorization.challenges.map((challenge) => ({
+ ...challenge,
+ candidateId: input.candidateId,
+ })),
+ didCommit: true,
+ session,
+ };
+ }
+ return failCandidate({ ...input, session });
+ }
+}
+
+function failCandidate(input: {
+ readonly candidateId: string;
+ readonly now: number;
+ readonly request: InputRequest;
+ readonly reason?: string;
+ readonly session: HarnessSession;
+}): {
+ readonly challenges: readonly AuthorizationChallenge[];
+ readonly didCommit: true;
+ readonly session: HarnessSession;
+} {
+ const reason = input.reason ?? "We couldn’t verify your approval. Please try again.";
+ return {
+ challenges: [],
+ didCommit: true,
+ session: {
+ ...input.session,
+ state: finishApprovalCandidate({
+ candidateId: input.candidateId,
+ completedAt: input.now,
+ reason,
+ state: input.session.state,
+ status: "failed",
+ }),
+ },
+ };
+}
+
+function hasResponseForRequest(
+ stepInput: StepInput | undefined,
+ requestIds: ReadonlySet<string>,
+): boolean {
+ return (
+ stepInput?.attributedInputResponses?.some(({ response }) =>
+ requestIds.has(response.requestId),
+ ) === true ||
+ stepInput?.inputResponses?.some((response) => requestIds.has(response.requestId)) === true
+ );
+}
+
+function hasMeaningfulInput(stepInput: StepInput | undefined): boolean {
+ return (
+ stepInput?.message !== undefined ||
+ (stepInput?.attributedInputResponses?.length ?? 0) > 0 ||
+ (stepInput?.inputResponses?.length ?? 0) > 0 ||
+ (stepInput?.runtimeActionResults?.length ?? 0) > 0
+ );
+}
+
+function appendAllowedResponses(
+ stepInput: StepInput | undefined,
+ requestIds: ReadonlySet<string>,
+): StepInput | undefined {
+ if (requestIds.size === 0) return stepInput;
+ return {
+ ...stepInput,
+ inputResponses: [
+ ...(stepInput?.inputResponses ?? []),
+ ...[...requestIds].map((requestId) => ({ optionId: "approve", requestId })),
+ ],
+ };
+}
+
+function removeConsumedResponses(
+ stepInput: StepInput | undefined,
+ consumed: ReadonlySet<string>,
+): StepInput | undefined {
+ if (stepInput === undefined) return undefined;
+ const attributed = (stepInput.attributedInputResponses ?? []).filter(
+ ({ response }) => !consumed.has(response.requestId),
+ );
+ const plain = (stepInput.inputResponses ?? []).filter(
+ (response) => !consumed.has(response.requestId),
+ );
+ const inputResponses = [...plain, ...attributed.map(({ response }) => response)];
+ return {
+ ...stepInput,
+ attributedInputResponses: undefined,
+ inputResponses,
+ };
+}
+
+function deliveryResult(
+ session: HarnessSession,
+ stepInput: StepInput | undefined,
+ kind: ApprovalDeliveryResult["kind"] = "continue",
+ challenges: readonly AuthorizationChallenge[] = [],
+ feedback: readonly string[] = [],
+): ApprovalDeliveryResult {
+ return { challenges, feedback, kind, session, stepInput };
+}
+
+function approvalCandidateIdPrefix(requestId: string, responder: SessionAuthContext): string {
+ const principal = [
+ responder.authenticator,
+ responder.issuer ?? "",
+ responder.principalType,
+ responder.principalId,
+ ].join(":");
+ return `${encodeCandidateIdPart(requestId)}.${encodeCandidateIdPart(principal)}`;
+}
+
+function encodeCandidateIdPart(value: string): string {
+ return Array.from(value, (character) => character.codePointAt(0)!.toString(36)).join("-");
+}
+
+async function withAuthorizerTimeout<T>(promise: Promise<T> | T): Promise<T> {
+ let timer: ReturnType<typeof setTimeout> | undefined;
+ try {
+ return await Promise.race([
+ Promise.resolve(promise),
+ new Promise<never>((_resolve, reject) => {
+ timer = setTimeout(
+ () => reject(new Error("Approval response authorizer timed out.")),
+ APPROVAL_AUTHORIZER_TIMEOUT_MS,
+ );
+ }),
+ ]);
+ } finally {
+ if (timer !== undefined) clearTimeout(timer);
+ }
+}
diff --git a/packages/eve/src/harness/input-extraction.ts b/packages/eve/src/harness/input-extraction.ts
index 2bdc48a6a..bf70abcaa 100644
--- a/packages/eve/src/harness/input-extraction.ts
+++ b/packages/eve/src/harness/input-extraction.ts
@@ -3,7 +3,7 @@ import { z } from "zod";
import { ASK_QUESTION_TOOL_NAME } from "#runtime/framework-tools/ask-question.js";
import type { InputRequest } from "#runtime/input/types.js";
-import { createRuntimeToolCallActionFromToolCall } from "#harness/input-requests.js";
+import { createRuntimeToolCallActionFromToolCall } from "#harness/tool-call-action.js";
// Persisted history parts lose AI SDK typing on the storage round trip. The
// schemas are the single source for the runtime narrowing and the static
diff --git a/packages/eve/src/harness/input-requests.ts b/packages/eve/src/harness/input-requests.ts
index 352795b04..d63b5760a 100644
--- a/packages/eve/src/harness/input-requests.ts
+++ b/packages/eve/src/harness/input-requests.ts
@@ -198,7 +198,11 @@ function resolveTextMessageInput(
return stepInput;
}
- const responses = resolveTextToResponses(stepInput.message, pendingBatch.requests);
+ const responseAuthRequired = new Set(pendingBatch.responseAuthRequiredRequestIds ?? []);
+ const textRequests = pendingBatch.requests.filter(
+ (request) => !responseAuthRequired.has(request.requestId),
+ );
+ const responses = resolveTextToResponses(stepInput.message, textRequests);
if (responses.length === 0) return stepInput;
return compactStepInput({
diff --git a/packages/eve/src/harness/pending-input-batches.ts b/packages/eve/src/harness/pending-input-batches.ts
index b0c74fffc..c252d7125 100644
--- a/packages/eve/src/harness/pending-input-batches.ts
+++ b/packages/eve/src/harness/pending-input-batches.ts
@@ -28,6 +28,7 @@ export interface PendingInputBatchEvent {
export interface PendingInputBatch {
readonly event?: PendingInputBatchEvent;
readonly requests: readonly InputRequest[];
+ readonly responseAuthRequiredRequestIds?: readonly string[];
readonly responseMessages: readonly ModelMessage[];
}
@@ -132,6 +133,7 @@ function setPendingInputBatches(
} else {
state[PENDING_INPUT_BATCHES_KEY] = batches.map((batch) => ({
event: batch.event,
+ responseAuthRequiredRequestIds: batch.responseAuthRequiredRequestIds,
requests: [...batch.requests],
responseMessages: [...batch.responseMessages],
}));
@@ -147,6 +149,7 @@ function setPendingInputBatches(
export function appendPendingInputBatch(input: {
readonly event?: PendingInputBatchEvent;
readonly requests: readonly InputRequest[];
+ readonly responseAuthRequiredRequestIds?: readonly string[];
readonly responseMessages: readonly ModelMessage[];
readonly session: HarnessSession;
}): HarnessSession {
@@ -154,6 +157,7 @@ export function appendPendingInputBatch(input: {
...getPendingInputBatches(input.session.state),
{
event: input.event,
+ responseAuthRequiredRequestIds: input.responseAuthRequiredRequestIds,
requests: input.requests,
responseMessages: input.responseMessages,
},
diff --git a/packages/eve/src/harness/stale-input-responses.test.ts b/packages/eve/src/harness/stale-input-responses.test.ts
index c51829025..0f1b333e3 100644
--- a/packages/eve/src/harness/stale-input-responses.test.ts
+++ b/packages/eve/src/harness/stale-input-responses.test.ts
@@ -70,12 +70,22 @@ it("converts a stale approval into a non-authorizing user message", () => {
);
});
-it("converts a stale question selection using its option label", () => {
+it("converts an attributed stale question selection using its option label", () => {
const result = convertStaleResponsesToUserMessage({
history: questionHistory,
pendingRequestIds: new Set(),
stepInput: {
- inputResponses: [{ optionId: "candidate", requestId: "question-1" }],
+ attributedInputResponses: [
+ {
+ auth: {
+ attributes: {},
+ authenticator: "test",
+ principalId: "user-1",
+ principalType: "user",
+ },
+ response: { optionId: "candidate", requestId: "question-1" },
+ },
+ ],
},
});
diff --git a/packages/eve/src/harness/stale-input-responses.ts b/packages/eve/src/harness/stale-input-responses.ts
index 8700703b6..3d9e8b44d 100644
--- a/packages/eve/src/harness/stale-input-responses.ts
+++ b/packages/eve/src/harness/stale-input-responses.ts
@@ -33,25 +33,26 @@ export function dropStaleSessionLimitContinuationResponses(input: {
readonly pendingRequestIds: ReadonlySet<string>;
readonly stepInput?: StepInput;
}): StepInput | undefined {
- const responses = input.stepInput?.inputResponses;
- if (input.stepInput === undefined || responses === undefined || responses.length === 0) {
+ if (input.stepInput === undefined) return undefined;
+ const responses = input.stepInput.inputResponses ?? [];
+ const attributed = input.stepInput.attributedInputResponses ?? [];
+ const keep = (requestId: string) =>
+ input.pendingRequestIds.has(requestId) || !isSessionLimitContinuationRequestId(requestId);
+ const retained = responses.filter((response) => keep(response.requestId));
+ const retainedAttributed = attributed.filter(({ response }) => keep(response.requestId));
+ if (retained.length === responses.length && retainedAttributed.length === attributed.length) {
return input.stepInput;
}
- const retained = responses.filter(
- (response) =>
- input.pendingRequestIds.has(response.requestId) ||
- !isSessionLimitContinuationRequestId(response.requestId),
- );
- if (retained.length === responses.length) {
- return input.stepInput;
- }
-
- const { inputResponses: _dropped, ...remainingInput } = input.stepInput;
- if (retained.length === 0) {
- return remainingInput;
- }
- return { ...remainingInput, inputResponses: retained };
+ const {
+ attributedInputResponses: _attributed,
+ inputResponses: _responses,
+ ...remainingInput
+ } = input.stepInput;
+ const result: { -readonly [K in keyof StepInput]: StepInput[K] } = remainingInput;
+ if (retained.length > 0) result.inputResponses = retained;
+ if (retainedAttributed.length > 0) result.attributedInputResponses = retainedAttributed;
+ return result;
}
/**
@@ -72,18 +73,26 @@ export function convertStaleResponsesToUserMessage(input: {
readonly pendingRequestIds: ReadonlySet<string>;
readonly stepInput?: StepInput;
}): StaleResponseConversion {
- const responses = input.stepInput?.inputResponses;
- if (input.stepInput === undefined || responses === undefined || responses.length === 0) {
+ if (input.stepInput === undefined) return { kind: "unchanged" };
+ const responses = input.stepInput.inputResponses ?? [];
+ const attributed = input.stepInput.attributedInputResponses ?? [];
+ if (responses.length === 0 && attributed.length === 0) {
return { kind: "unchanged", stepInput: input.stepInput };
}
const currentResponses: InputResponse[] = [];
+ const currentAttributed: NonNullable<StepInput["attributedInputResponses"]>[number][] = [];
const staleResponses: InputResponse[] = [];
for (const response of responses) {
- if (input.pendingRequestIds.has(response.requestId)) {
- currentResponses.push(response);
+ (input.pendingRequestIds.has(response.requestId) ? currentResponses : staleResponses).push(
+ response,
+ );
+ }
+ for (const entry of attributed) {
+ if (input.pendingRequestIds.has(entry.response.requestId)) {
+ currentAttributed.push(entry);
} else {
- staleResponses.push(response);
+ staleResponses.push(entry.response);
}
}
@@ -103,14 +112,17 @@ export function convertStaleResponsesToUserMessage(input: {
input.stepInput.message,
formatDisplayMessage(staleResponses, requests),
);
- const { inputResponses: _responses, ...remainingInput } = input.stepInput;
+ const {
+ attributedInputResponses: _attributed,
+ inputResponses: _responses,
+ ...remainingInput
+ } = input.stepInput;
const stepInput: { -readonly [K in keyof StepInput]: StepInput[K] } = {
...remainingInput,
message: modelMessage,
};
- if (currentResponses.length > 0) {
- stepInput.inputResponses = currentResponses;
- }
+ if (currentResponses.length > 0) stepInput.inputResponses = currentResponses;
+ if (currentAttributed.length > 0) stepInput.attributedInputResponses = currentAttributed;
return { displayMessage, kind: "converted", stepInput };
}
diff --git a/packages/eve/src/harness/tool-call-action.ts b/packages/eve/src/harness/tool-call-action.ts
new file mode 100644
index 000000000..75dd41023
--- /dev/null
+++ b/packages/eve/src/harness/tool-call-action.ts
@@ -0,0 +1,21 @@
+import type { RuntimeToolCallActionRequest } from "#runtime/actions/types.js";
+import { resolveToolCallInputObject } from "#harness/runtime-actions.js";
+
+/** Creates a runtime tool-call action shape from an AI SDK tool call. */
+export function createRuntimeToolCallActionFromToolCall(input: {
+ readonly toolCall: {
+ readonly input: unknown;
+ readonly toolCallId: string;
+ readonly toolName: string;
+ };
+}): RuntimeToolCallActionRequest {
+ return {
+ callId: input.toolCall.toolCallId,
+ input: resolveToolCallInputObject(input.toolCall.input, {
+ callId: input.toolCall.toolCallId,
+ toolName: input.toolCall.toolName,
+ }),
+ kind: "tool-call",
+ toolName: input.toolCall.toolName,
+ };
+}
diff --git a/packages/eve/src/harness/tool-loop.ts b/packages/eve/src/harness/tool-loop.ts
index 5f1f3c603..12a60ce74 100644
--- a/packages/eve/src/harness/tool-loop.ts
+++ b/packages/eve/src/harness/tool-loop.ts
@@ -41,7 +41,10 @@ import {
getActiveDynamicModelSelection,
isDynamicModelSelectionError,
} from "#context/dynamic-model-lifecycle.js";
-import { buildDynamicTools } from "#context/build-dynamic-tools.js";
+import {
+ buildDynamicTools,
+ buildResponseAuthorizationTools,
+} from "#context/build-dynamic-tools.js";
import { buildDynamicSubagentTools } from "#context/dynamic-subagent-lifecycle.js";
import { PendingSkillAnnouncementKey } from "#context/dynamic-skill-lifecycle.js";
import { toErrorMessage } from "#shared/errors.js";
@@ -132,6 +135,11 @@ import {
resolvePendingInput,
appendPendingInputBatch,
} from "#harness/input-requests.js";
+import { queueDeferredStepInput } from "#harness/pending-input-batches.js";
+import {
+ coordinateApprovalDelivery,
+ shouldPrepareApprovalPolicyTools,
+} from "#harness/approval-delivery-coordinator.js";
import {
convertStaleResponsesToUserMessage,
dropStaleSessionLimitContinuationResponses,
@@ -149,6 +157,8 @@ import { readToolInterrupt } from "#harness/tool-interrupts.js";
import {
createAuthorizationCompletedEvent,
createAuthorizationRequiredEvent,
+ createMessageCompletedEvent,
+ createStepStartedEvent,
} from "#protocol/message.js";
import {
classifyModelCallError,
@@ -736,12 +746,90 @@ export function createToolLoopHarness(config: ToolLoopHarnessConfig): StepFn {
? { ...effectiveStepInput, message: staleConversion.displayMessage }
: effectiveStepInput;
+ const approvalContext = contextStorage.getStore();
+ if (
+ approvalContext !== undefined &&
+ config.resolveStepDynamicTools !== undefined &&
+ shouldPrepareApprovalPolicyTools({ session, stepInput: effectiveStepInput })
+ ) {
+ await config.resolveStepDynamicTools({
+ ctx: approvalContext,
+ event: createStepStartedEvent({
+ modelId: session.agent.modelReference?.id ?? "dynamic",
+ sequence: emissionState.sequence,
+ stepIndex: emissionState.stepIndex,
+ turnId: emissionState.turnId,
+ }),
+ messages: resolvedRuntimeActions.messages,
+ });
+ }
+ const coordinated = await coordinateApprovalDelivery({
+ session,
+ stepInput: effectiveStepInput,
+ tools: buildResponseAuthorizationTools({
+ authoredTools: config.tools,
+ context: approvalContext,
+ }),
+ });
+ session = coordinated.session;
+ if (emit !== undefined) {
+ for (const message of coordinated.feedback) {
+ await emit(
+ createMessageCompletedEvent({
+ message,
+ sequence: emissionState.sequence,
+ stepIndex: emissionState.stepIndex,
+ turnId: emissionState.turnId,
+ }),
+ );
+ }
+ }
+ if (coordinated.kind === "park") return { next: null, session };
+ if (coordinated.kind === "continue-coordination") {
+ const continuedSession =
+ coordinated.stepInput === undefined
+ ? session
+ : queueDeferredStepInput(session, coordinated.stepInput);
+ return { next: runStep, session: continuedSession };
+ }
+ if (coordinated.challenges.length > 0) {
+ if (emit) {
+ for (const challenge of coordinated.challenges) {
+ await emit(
+ createAuthorizationRequiredEvent({
+ authorization: challenge.challenge,
+ description:
+ challenge.challenge.instructions ?? `Authorization required for ${challenge.name}`,
+ name: challenge.name,
+ sequence: emissionState.sequence,
+ stepIndex: emissionState.stepIndex,
+ turnId: emissionState.turnId,
+ webhookUrl: challenge.hookUrl,
+ }),
+ );
+ }
+ }
+ const parkedSession =
+ coordinated.stepInput === undefined
+ ? session
+ : queueDeferredStepInput(session, coordinated.stepInput);
+ return {
+ next: null,
+ session: {
+ ...parkedSession,
+ state: setPendingAuthorization(parkedSession.state, {
+ challenges: coordinated.challenges,
+ }),
+ },
+ };
+ }
+
const pending = resolvePendingInput({
deferMessagesWhileApprovalsPending: config.mode !== "conversation",
history: resolvedRuntimeActions.messages,
resolveApprovalKey: resolveApprovalKeyFromTools(config.tools),
session,
- stepInput: effectiveStepInput,
+ stepInput: coordinated.stepInput,
});
if (pending.outcome === "unresolved") {
if (
@@ -2229,6 +2317,10 @@ async function handleStepResult(input: {
// --- Park on input requests -----------------------------------------------
if (inputRequests.length > 0) {
+ const responseAuthorizationTools = buildResponseAuthorizationTools({
+ authoredTools: config.tools,
+ context: contextStorage.getStore(),
+ });
let parkedSession = appendPendingInputBatch({
event: {
sequence: emissionState.sequence,
@@ -2236,6 +2328,16 @@ async function handleStepResult(input: {
turnId: emissionState.turnId,
},
requests: inputRequests,
+ responseAuthRequiredRequestIds: approvalRequests
+ .filter((request) => {
+ const approval = responseAuthorizationTools.get(request.action.toolName)?.approval;
+ return (
+ approval !== undefined &&
+ typeof approval !== "function" &&
+ approval.response !== undefined
+ );
+ })
+ .map((request) => request.requestId),
responseMessages,
session: { ...baseSession, history: [...promptMessages] },
});
diff --git a/packages/eve/src/harness/types.ts b/packages/eve/src/harness/types.ts
index 27b0391a7..53c01daa6 100644
--- a/packages/eve/src/harness/types.ts
+++ b/packages/eve/src/harness/types.ts
@@ -1,6 +1,6 @@
import type { LanguageModel, ModelMessage, UserContent } from "ai";
-import type { SessionCapabilities } from "#channel/types.js";
+import type { SessionAuthContext, SessionCapabilities } from "#channel/types.js";
import type { AlsContext } from "#context/container.js";
import type { UnstampedMessageStreamEvent, RuntimeIdentity } from "#protocol/message.js";
import type { RunMode } from "#shared/run-mode.js";
@@ -140,9 +140,18 @@ export interface SessionLimits {
* channels. The harness resolves any pending input batch at the start of
* `runStep` before the model call.
*/
+export interface AttributedInputResponse {
+ readonly auth: SessionAuthContext | null;
+ readonly response: InputResponse;
+}
+
export interface StepInput {
+ /** Internal responder-bound input produced at the delivery boundary. */
+ readonly attributedInputResponses?: readonly AttributedInputResponse[];
readonly inputResponses?: readonly InputResponse[];
readonly message?: string | UserContent;
+ /** Internal actor attribution for `message`. */
+ readonly messageAuth?: SessionAuthContext | null;
/**
* Context strings from the channel delivery. Each entry is appended
* as a `role: "user"` message to `session.history` before the
@@ -310,6 +319,12 @@ export interface ToolLoopHarnessConfig {
* listing appended after runtime-action batches resolve.
*/
readonly persistentSubagentSessions?: boolean;
+ /** Resolves step-scoped dynamic tools once for approval policy and model work. */
+ readonly resolveStepDynamicTools?: (input: {
+ readonly ctx: AlsContext;
+ readonly event: UnstampedMessageStreamEvent;
+ readonly messages: readonly ModelMessage[];
+ }) => Promise<void>;
readonly dispatchDynamicModelEvent?: (input: {
readonly ctx: AlsContext;
readonly event: UnstampedMessageStreamEvent;