diff --git a/apps/agent/agent/hooks/builder-delegation.ts b/apps/agent/agent/hooks/builder-delegation.ts new file mode 100644 index 00000000..036060bc --- /dev/null +++ b/apps/agent/agent/hooks/builder-delegation.ts @@ -0,0 +1,26 @@ +import { defineHook } from "eve/hooks"; +import { + builderDelegationState, + recordBuilderDelegation, +} from "../lib/builder-delegation"; +import { attribute, purposeOf } from "../lib/session-purpose"; + +export default defineHook({ + events: { + "actions.requested"(event, ctx) { + if ( + purposeOf(ctx) !== "builder" || + attribute(ctx, "commandType") !== "CREATE_AGENT" + ) { + return; + } + + const next = recordBuilderDelegation( + builderDelegationState.get(), + event.data.turnId, + event.data.actions, + ); + builderDelegationState.update(() => next); + }, + }, +}); diff --git a/apps/agent/agent/instructions/task.ts b/apps/agent/agent/instructions/task.ts index a22b7afd..3cf99d13 100644 --- a/apps/agent/agent/instructions/task.ts +++ b/apps/agent/agent/instructions/task.ts @@ -64,7 +64,7 @@ export function builderTaskMarkdown( ): string { const task = commandType === "CREATE_AGENT" - ? `This private CRM chat turn is authorized to create or revise an agent. Call agent_builder exactly once. Pass the complete request, the conversation's relevant decisions, every tagged resource, and your understanding of any attachment. Do not call research tools or mutate CRM records yourself. If the specialist returns needs_input, call ask_question with exactly its question, options, and freeform policy instead of replying with a plain-text question. Ask exactly one decision at a time and never bundle several missing details into one prompt. After the answer, ask another question only if the build remains materially blocked. Ask only when the answer materially changes the trigger, records, integrations, schedule, outcome, or side effect. Do not interrupt a sufficiently specific request or ask about optional polish. If the specialist returns draft_ready, relay its concise summary and explain that the draft is ready for human review and is not deployed yet.` + ? `This private CRM chat turn is authorized to create or revise an agent. Call agent_builder exactly once. Pass the complete request, the conversation's relevant decisions, every tagged resource, and your understanding of any attachment. Do not call research tools or mutate CRM records yourself. The specialist asks any essential clarification directly through ask_question and returns only when the draft is ready. Never retry agent_builder in the same turn. If the specialist fails, explain that the build could not finish and ask the user to try again instead of delegating again. If the specialist returns draft_ready, relay its concise summary and explain that the draft is ready for human review and is not deployed yet.` : `This is a private CRM assistant chat. Answer the user's question directly. Use tagged records as scope and use available read-only CRM and research tools when evidence is needed. Use list_deals for pipeline-wide, open-deal, or inactivity questions and follow its pagination until the requested scope is complete. The chat renders list_deals output as a structured deal list. Do not restate or enumerate individual deal rows in prose, bullets, or tables; the structured list is the sole row-level presentation. Give only a concise synthesis, caveats, and useful next actions after the tool results. If one materially necessary decision is missing, call ask_question with one focused follow-up instead of guessing; do not interrupt for optional detail. Do not call agent_builder, create an agent draft, or mutate CRM records on this turn. Agent creation begins only from an explicit request to create or build one. Be concise, distinguish CRM evidence from inference, and say when the CRM does not contain the answer.`; return needsTitle diff --git a/apps/agent/agent/lib/builder-delegation.ts b/apps/agent/agent/lib/builder-delegation.ts new file mode 100644 index 00000000..30695531 --- /dev/null +++ b/apps/agent/agent/lib/builder-delegation.ts @@ -0,0 +1,45 @@ +import { defineState } from "eve/context"; + +type BuilderDelegationAction = { + callId: string; + kind: string; + subagentName?: string; +}; + +type BuilderDelegationState = { + turnId: string | null; + callIds: string[]; +}; + +export const builderDelegationState = defineState( + "crm.builder-delegation", + () => ({ turnId: null, callIds: [] }), +); + +export function recordBuilderDelegation( + state: BuilderDelegationState, + turnId: string, + actions: readonly BuilderDelegationAction[], +): BuilderDelegationState { + const current = + state.turnId === turnId ? state : { turnId, callIds: [] as string[] }; + const callIds = new Set(current.callIds); + + for (const action of actions) { + if ( + action.kind !== "subagent-call" || + action.subagentName !== "agent_builder" || + callIds.has(action.callId) + ) { + continue; + } + if (callIds.size > 0) { + throw new Error( + "The agent builder can be delegated only once per creation turn.", + ); + } + callIds.add(action.callId); + } + + return { turnId, callIds: [...callIds] }; +} diff --git a/apps/agent/agent/lib/builder-runtime.ts b/apps/agent/agent/lib/builder-runtime.ts index 2a30b816..434e59ff 100644 --- a/apps/agent/agent/lib/builder-runtime.ts +++ b/apps/agent/agent/lib/builder-runtime.ts @@ -460,9 +460,21 @@ async function validateDraft( .filter((resource) => resource.kind !== "integration") .map((resource) => `${resource.kind}:${resource.id}`), ); + const taggedRecordLabels = new Map( + taggedResources + .filter((resource) => resource.kind !== "integration") + .map((resource) => [`${resource.kind}:${resource.id}`, resource.label]), + ); for (const resource of recordResources) { - if (!taggedRecordKeys.has(`${resource.kind}:${resource.id}`)) { + const key = `${resource.kind}:${resource.id}`; + if (!taggedRecordKeys.has(key)) { issues.push(`${resource.label} was not tagged in this builder chat.`); + continue; + } + if (taggedRecordLabels.get(key) !== resource.label) { + issues.push( + `${resource.kind} ${resource.id} must use its exact tagged label.`, + ); } } diff --git a/apps/agent/agent/subagents/agent_builder/agent.ts b/apps/agent/agent/subagents/agent_builder/agent.ts index 19b75699..4318264f 100644 --- a/apps/agent/agent/subagents/agent_builder/agent.ts +++ b/apps/agent/agent/subagents/agent_builder/agent.ts @@ -10,30 +10,15 @@ export default defineAgent({ fallback: DEFAULT_AGENT_MODEL.id, events: { "session.started": () => selectedModel() }, }), - outputSchema: z.discriminatedUnion("status", [ - z.object({ - status: z.literal("needs_input"), - question: z.string().min(1).max(500), - options: z - .array( - z.object({ - id: z.string().min(1).max(80), - label: z.string().min(1).max(120), - }), - ) - .max(4), - allowFreeform: z.boolean(), - }), - z.object({ - status: z.literal("draft_ready"), - summary: z.string().min(1).max(1000), - agentId: z.string().min(1), - versionId: z.string().min(1), - }), - ]), + outputSchema: z.object({ + status: z.literal("draft_ready"), + summary: z.string().min(1).max(1000), + agentId: z.string().min(1), + versionId: z.string().min(1), + }), limits: { - maxInputTokensPerSession: 250_000, - maxOutputTokensPerSession: 20_000, + maxInputTokensPerSession: 100_000, + maxOutputTokensPerSession: 10_000, sessionTimeoutMs: 24 * 60 * 60 * 1000, }, }); diff --git a/apps/agent/agent/subagents/agent_builder/hooks/execution-guard.ts b/apps/agent/agent/subagents/agent_builder/hooks/execution-guard.ts new file mode 100644 index 00000000..754d6fc9 --- /dev/null +++ b/apps/agent/agent/subagents/agent_builder/hooks/execution-guard.ts @@ -0,0 +1,29 @@ +import { defineHook } from "eve/hooks"; +import { + builderExecutionState, + markBuilderDraftSaveFinished, + recordBuilderActions, +} from "../lib/execution-state"; + +export default defineHook({ + events: { + "actions.requested"(event) { + const next = recordBuilderActions( + builderExecutionState.get(), + event.data.turnId, + event.data.stepIndex, + event.data.actions, + ); + builderExecutionState.update(() => next); + }, + "action.result"(event) { + if ( + event.data.status !== "completed" && + event.data.result.kind === "tool-result" && + event.data.result.toolName === "save_agent_draft" + ) { + markBuilderDraftSaveFinished(false); + } + }, + }, +}); diff --git a/apps/agent/agent/subagents/agent_builder/instructions.md b/apps/agent/agent/subagents/agent_builder/instructions.md index 6506c68e..1742462f 100644 --- a/apps/agent/agent/subagents/agent_builder/instructions.md +++ b/apps/agent/agent/subagents/agent_builder/instructions.md @@ -31,23 +31,29 @@ not report. If no safe and useful draft is possible because an essential target, explicitly requested connection, schedule, outcome, or side effect remains ambiguous, do -not call `save_agent_draft`. Return `needs_input` with one focused question for -the parent to ask the user. Include two to four mutually exclusive options when -they clarify a real choice, and set `allowFreeform` when a custom answer is -valid. Ask only when the answer materially changes the bounded behavior and the -least-privilege defaults above do not resolve it. Return exactly one decision -per pause; never bundle several missing details into one question. After the -answer, ask the next question only if the build is still materially blocked. Do -not interrupt for a name, wording, optional polish, or another choice that can -be safely represented in the reviewable draft. For a schedule, calculate a -future `nextRunAt` from the supplied current time and provide its recurrence in -minutes. +not call `save_agent_draft`. Call `ask_question` directly with one focused +question. Include two to four mutually exclusive options when they clarify a +real choice, and allow freeform input when a custom answer is valid. Ask only +when the answer materially changes the bounded behavior and the least-privilege +defaults above do not resolve it. Ask exactly one decision per pause; never +bundle several missing details into one question. After the answer, ask the next +question only if the build is still materially blocked. Do not interrupt for a +name, wording, optional polish, or another choice that can be safely represented +in the reviewable draft. For a schedule, calculate a future `nextRunAt` from the +supplied current time and provide its recurrence in minutes. Choose the record scope explicitly. Use `SELECTED` only for the exact tagged CRM records reported by `inspect_context`. Use `WORKSPACE` only when the user clearly asks for workspace-wide CRM access. Never treat an empty selected scope as workspace access. +The `save_agent_draft` resource contract is exact. Copy only tagged companies, +contacts, and deals from `inspect_context` into `resources`, preserving each +kind, id, and label byte for byte. Put read-only sources in `integrations` using +only `gmail` or `calendar`, and only when `availableConnections` reports that +source. Never put CRM, Gmail, Google Calendar, or another integration in +`resources`. The runtime derives the human-readable access list. + For `crm.activity.create`, list the exact allowed activity types. Authorize `NOTE`, `TASK`, or both only when the request calls for them. A prose summary never grants an activity type by itself. @@ -60,5 +66,6 @@ call when necessary. Never put credentials, tokens, or secret values in a file. After the three files agree, call `save_agent_draft` once with the exact same behavior. A successful save creates exact final file snapshots and an immutable version in READY state for human review. It does not deploy it. -Return `draft_ready` with the saved agent and version ids plus a plain-language -summary of the trigger, data scope, action, and access. +After a successful save, call no tool except `final_output`. Return +`draft_ready` immediately with the saved agent and version ids plus a +plain-language summary of the trigger, data scope, action, and access. diff --git a/apps/agent/agent/subagents/agent_builder/lib/draft-input.ts b/apps/agent/agent/subagents/agent_builder/lib/draft-input.ts new file mode 100644 index 00000000..a25f2c43 --- /dev/null +++ b/apps/agent/agent/subagents/agent_builder/lib/draft-input.ts @@ -0,0 +1,81 @@ +import { z } from "zod"; +import type { DraftAgentInput } from "../../../lib/builder-runtime"; + +const recordResource = z.object({ + kind: z.enum(["company", "contact", "deal"]), + id: z.string().min(1), + label: z.string().min(1).max(120), +}); + +const trigger = z.object({ + type: z.enum(["MANUAL", "SCHEDULE"]), + name: z.string().trim().min(1).max(120), + summary: z.string().trim().min(1).max(240), + nextRunAt: z.string().nullish(), + intervalMinutes: z.number().int().min(1).max(525_600).nullish(), +}); + +const action = z.discriminatedUnion("type", [ + z.object({ + type: z.literal("crm.activity.create"), + provider: z.literal("crm"), + summary: z.string().trim().min(1).max(240), + activityTypes: z + .array(z.enum(["NOTE", "TASK"])) + .min(1) + .max(2), + }), + z.object({ + type: z.literal("run.summary"), + provider: z.literal("crm"), + summary: z.string().trim().min(1).max(240), + }), +]); + +export const builderDraftToolInput = z.object({ + name: z.string().trim().min(1).max(100), + description: z.string().trim().min(1).max(320), + instructions: z.string().trim().min(40).max(20_000), + trigger, + recordScope: z.enum(["SELECTED", "WORKSPACE"]), + resources: z.array(recordResource).max(30), + integrations: z.array(z.enum(["gmail", "calendar"])).max(2), + actions: z.array(action).min(1).max(10), +}); + +type BuilderDraftToolInput = z.infer; + +const INTEGRATIONS = { + gmail: { kind: "integration", id: "google:gmail", label: "Gmail" }, + calendar: { + kind: "integration", + id: "google:calendar", + label: "Google Calendar", + }, +} as const; + +export function draftInputFromTool( + input: BuilderDraftToolInput, +): DraftAgentInput { + const { integrations: requestedIntegrations, ...draft } = input; + const integrations = [...new Set(requestedIntegrations)]; + const access = [ + input.recordScope === "WORKSPACE" + ? "Read workspace CRM records" + : "Read selected CRM records", + ...integrations.map((integration) => + integration === "gmail" + ? "Read connected Gmail messages" + : "Read connected Google Calendar events", + ), + ]; + + return { + ...draft, + resources: [ + ...input.resources, + ...integrations.map((integration) => INTEGRATIONS[integration]), + ], + access, + }; +} diff --git a/apps/agent/agent/subagents/agent_builder/lib/execution-state.ts b/apps/agent/agent/subagents/agent_builder/lib/execution-state.ts new file mode 100644 index 00000000..bfa845ad --- /dev/null +++ b/apps/agent/agent/subagents/agent_builder/lib/execution-state.ts @@ -0,0 +1,117 @@ +import { defineState } from "eve/context"; + +type BuilderAction = { + callId: string; + kind: string; + toolName?: string; +}; + +type BuilderExecutionState = { + turnId: string | null; + stepIndex: number | null; + callIds: string[]; + stepCallIds: string[]; + saveCallIds: string[]; + savePending: boolean; + saved: boolean; +}; + +export const builderExecutionState = defineState( + "crm.agent-builder.execution", + () => ({ + turnId: null, + stepIndex: null, + callIds: [], + stepCallIds: [], + saveCallIds: [], + savePending: false, + saved: false, + }), +); + +export function recordBuilderActions( + state: BuilderExecutionState, + turnId: string, + stepIndex: number, + actions: readonly BuilderAction[], +): BuilderExecutionState { + const current = + state.turnId === turnId + ? state + : { + turnId, + stepIndex: null, + callIds: [], + stepCallIds: [], + saveCallIds: [], + savePending: false, + saved: state.saved, + }; + const callIds = new Set(current.callIds); + const stepCallIds = new Set( + current.stepIndex === stepIndex ? current.stepCallIds : [], + ); + const saveCallIds = new Set(current.saveCallIds); + let savePending = current.savePending; + + for (const action of actions) { + if (callIds.has(action.callId)) continue; + if (current.saved && action.toolName !== "final_output") { + throw new Error( + "The draft is already saved. Return the saved draft now without calling another tool.", + ); + } + if (!current.saved && action.toolName === "final_output") { + throw new Error("Save the draft before returning draft_ready."); + } + if (savePending) { + throw new Error( + "Wait for save_agent_draft to finish before calling another tool.", + ); + } + if (callIds.size >= 12) { + throw new Error("The agent builder exceeded its tool-call budget."); + } + if (action.toolName === "save_agent_draft") { + if (stepCallIds.size > 0) { + throw new Error("Call save_agent_draft by itself in a model step."); + } + if (saveCallIds.size >= 2) { + throw new Error("The agent builder exceeded its draft-save budget."); + } + saveCallIds.add(action.callId); + savePending = true; + } + callIds.add(action.callId); + stepCallIds.add(action.callId); + } + + return { + turnId, + stepIndex, + callIds: [...callIds], + stepCallIds: [...stepCallIds], + saveCallIds: [...saveCallIds], + savePending, + saved: current.saved, + }; +} + +export function finishBuilderDraftSave( + state: BuilderExecutionState, + saved: boolean, +): BuilderExecutionState { + return { ...state, savePending: false, saved: state.saved || saved }; +} + +export function markBuilderDraftSaveFinished(saved: boolean): void { + builderExecutionState.update((state) => finishBuilderDraftSave(state, saved)); +} + +export function assertBuilderDraftOpen(): void { + if (builderExecutionState.get().saved) { + throw new Error( + "The draft is already saved. Return the saved draft now without changing files.", + ); + } +} diff --git a/apps/agent/agent/subagents/agent_builder/tools/ask_question.ts b/apps/agent/agent/subagents/agent_builder/tools/ask_question.ts deleted file mode 100644 index 04bd0544..00000000 --- a/apps/agent/agent/subagents/agent_builder/tools/ask_question.ts +++ /dev/null @@ -1,3 +0,0 @@ -import { disableTool } from "eve/tools"; - -export default disableTool(); diff --git a/apps/agent/agent/subagents/agent_builder/tools/save_agent_draft.ts b/apps/agent/agent/subagents/agent_builder/tools/save_agent_draft.ts index 3528a620..8ed3c0aa 100644 --- a/apps/agent/agent/subagents/agent_builder/tools/save_agent_draft.ts +++ b/apps/agent/agent/subagents/agent_builder/tools/save_agent_draft.ts @@ -1,57 +1,24 @@ import { defineTool } from "eve/tools"; -import { z } from "zod"; import { saveBuilderDraft } from "../../../lib/builder-runtime"; import { requireBuilderAttribute } from "../../../lib/session-purpose"; - -const resource = z.object({ - kind: z.enum(["integration", "company", "contact", "deal"]), - id: z.string().min(1), - label: z.string().min(1).max(120), -}); - -const trigger = z.object({ - type: z.enum(["MANUAL", "SCHEDULE"]), - name: z.string().min(1).max(120), - summary: z.string().min(1).max(240), - nextRunAt: z.string().nullish(), - intervalMinutes: z.number().int().min(1).max(525_600).nullish(), -}); - -const action = z.discriminatedUnion("type", [ - z.object({ - type: z.literal("crm.activity.create"), - provider: z.literal("crm"), - summary: z.string().min(1).max(240), - activityTypes: z - .array(z.enum(["NOTE", "TASK"])) - .min(1) - .max(2), - }), - z.object({ - type: z.literal("run.summary"), - provider: z.literal("crm"), - summary: z.string().min(1).max(240), - }), -]); +import { builderDraftToolInput, draftInputFromTool } from "../lib/draft-input"; +import { + assertBuilderDraftOpen, + markBuilderDraftSaveFinished, +} from "../lib/execution-state"; export default defineTool({ description: - "Validate and save one immutable agent version for human review. This never deploys the agent.", - inputSchema: z.object({ - name: z.string().trim().min(1).max(100), - description: z.string().trim().min(1).max(320), - instructions: z.string().trim().min(40).max(20_000), - trigger, - recordScope: z.enum(["SELECTED", "WORKSPACE"]), - resources: z.array(resource).max(30), - actions: z.array(action).min(1).max(10), - access: z.array(z.string().trim().min(1).max(120)).max(20), - }), + "Validate and save one immutable agent version for human review. Copy selected CRM records exactly into resources. Put connected read sources only in integrations. This never deploys the agent.", + inputSchema: builderDraftToolInput, async execute(input, ctx) { - return saveBuilderDraft( + assertBuilderDraftOpen(); + const result = await saveBuilderDraft( requireBuilderAttribute(ctx, "conversationId"), requireBuilderAttribute(ctx, "userId"), - input, + draftInputFromTool(input), ); + markBuilderDraftSaveFinished(result.saved); + return result; }, }); diff --git a/apps/agent/agent/subagents/agent_builder/tools/write_agent_file.ts b/apps/agent/agent/subagents/agent_builder/tools/write_agent_file.ts index 8e46d38a..9d938012 100644 --- a/apps/agent/agent/subagents/agent_builder/tools/write_agent_file.ts +++ b/apps/agent/agent/subagents/agent_builder/tools/write_agent_file.ts @@ -5,6 +5,7 @@ import { writeBuilderArtifact, } from "../../../lib/builder-runtime"; import { requireBuilderAttribute } from "../../../lib/session-purpose"; +import { assertBuilderDraftOpen } from "../lib/execution-state"; export default defineTool({ description: @@ -14,6 +15,7 @@ export default defineTool({ content: z.string().min(1).max(40_000), }), async execute(input, ctx) { + assertBuilderDraftOpen(); return writeBuilderArtifact( requireBuilderAttribute(ctx, "conversationId"), requireBuilderAttribute(ctx, "userId"), diff --git a/apps/agent/test/custom-agent-runtime.spec.ts b/apps/agent/test/custom-agent-runtime.spec.ts index 963136fa..fde444e8 100644 --- a/apps/agent/test/custom-agent-runtime.spec.ts +++ b/apps/agent/test/custom-agent-runtime.spec.ts @@ -1,5 +1,6 @@ import { describe, expect, it } from "bun:test"; import { builderTaskMarkdown } from "../agent/instructions/task"; +import { recordBuilderDelegation } from "../agent/lib/builder-delegation"; import { builderCommandType, builderDeliveryMessage, @@ -16,6 +17,14 @@ import { requireBuilderAttribute, requireTeamAgentAttribute, } from "../agent/lib/session-purpose"; +import { + builderDraftToolInput, + draftInputFromTool, +} from "../agent/subagents/agent_builder/lib/draft-input"; +import { + finishBuilderDraftSave, + recordBuilderActions, +} from "../agent/subagents/agent_builder/lib/execution-state"; const context = (purpose?: string, commandType?: string) => ({ session: { @@ -149,11 +158,8 @@ describe("builder command routing", () => { it("delegates only the explicit creation command to the agent builder", () => { const creation = builderTaskMarkdown("CREATE_AGENT"); expect(creation).toContain("Call agent_builder exactly once"); - expect(creation).toContain("call ask_question"); - expect(creation).toContain("exactly one decision at a time"); - expect(creation).toContain( - "Do not interrupt a sufficiently specific request", - ); + expect(creation).toContain("Never retry agent_builder in the same turn"); + expect(creation).toContain("asks any essential clarification directly"); const chat = builderTaskMarkdown("CHAT"); expect(chat).toContain("Do not call agent_builder"); expect(chat).toContain("call ask_question"); @@ -171,3 +177,285 @@ describe("builder command routing", () => { expect(builderTaskMarkdown("CHAT", false)).not.toContain("set_chat_title"); }); }); + +describe("builder delegation guard", () => { + it("allows one idempotent builder delegation per turn", () => { + const first = recordBuilderDelegation( + { turnId: null, callIds: [] }, + "turn-1", + [ + { + kind: "subagent-call", + callId: "call-1", + subagentName: "agent_builder", + }, + ], + ); + + expect( + recordBuilderDelegation(first, "turn-1", [ + { + kind: "subagent-call", + callId: "call-1", + subagentName: "agent_builder", + }, + ]), + ).toEqual(first); + expect(() => + recordBuilderDelegation(first, "turn-1", [ + { + kind: "subagent-call", + callId: "call-2", + subagentName: "agent_builder", + }, + ]), + ).toThrow("only once"); + expect( + recordBuilderDelegation(first, "turn-2", [ + { + kind: "subagent-call", + callId: "call-2", + subagentName: "agent_builder", + }, + ]), + ).toEqual({ turnId: "turn-2", callIds: ["call-2"] }); + }); +}); + +describe("agent builder execution guard", () => { + it("bounds save attempts and permits only final output after saving", () => { + const initial = { + turnId: null, + stepIndex: null, + callIds: [], + stepCallIds: [], + saveCallIds: [], + savePending: false, + saved: false, + }; + const first = recordBuilderActions(initial, "turn-1", 0, [ + { + kind: "tool-call", + callId: "save-1", + toolName: "save_agent_draft", + }, + ]); + const second = recordBuilderActions( + finishBuilderDraftSave(first, false), + "turn-1", + 1, + [ + { + kind: "tool-call", + callId: "save-2", + toolName: "save_agent_draft", + }, + ], + ); + + expect(() => + recordBuilderActions(finishBuilderDraftSave(second, false), "turn-1", 2, [ + { + kind: "tool-call", + callId: "save-3", + toolName: "save_agent_draft", + }, + ]), + ).toThrow("draft-save budget"); + + const saved = finishBuilderDraftSave(first, true); + expect(() => + recordBuilderActions(saved, "turn-2", 0, [ + { + kind: "tool-call", + callId: "write-1", + toolName: "write_agent_file", + }, + ]), + ).toThrow("already saved"); + expect(() => + recordBuilderActions(saved, "turn-2", 0, [ + { + kind: "tool-call", + callId: "final-1", + toolName: "final_output", + }, + ]), + ).not.toThrow(); + }); + + it("requires draft saving to run by itself", () => { + const initial = { + turnId: null, + stepIndex: null, + callIds: [], + stepCallIds: [], + saveCallIds: [], + savePending: false, + saved: false, + }; + + expect(() => + recordBuilderActions(initial, "turn-1", 0, [ + { + kind: "tool-call", + callId: "save-1", + toolName: "save_agent_draft", + }, + { + kind: "tool-call", + callId: "write-1", + toolName: "write_agent_file", + }, + ]), + ).toThrow("Wait for save_agent_draft"); + expect(() => + recordBuilderActions(initial, "turn-1", 0, [ + { + kind: "tool-call", + callId: "write-1", + toolName: "write_agent_file", + }, + { + kind: "tool-call", + callId: "save-1", + toolName: "save_agent_draft", + }, + ]), + ).toThrow("by itself"); + }); +}); + +describe("agent builder draft input", () => { + it("separates canonical integrations from exact CRM resources", () => { + const parsed = builderDraftToolInput.parse({ + name: "Renewal prep", + description: "Prepare a renewal call brief.", + instructions: + "Run manually. Read the selected deal and summarize renewal risks for review.", + trigger: { + type: "MANUAL", + name: "Prepare renewal brief", + summary: "Run before a renewal call", + }, + recordScope: "SELECTED", + resources: [{ kind: "deal", id: "deal-1", label: "Acme renewal" }], + integrations: ["gmail", "calendar"], + actions: [ + { + type: "run.summary", + provider: "crm", + summary: "Write a reviewable renewal brief", + }, + ], + }); + + expect(draftInputFromTool(parsed)).toMatchObject({ + resources: [ + { kind: "deal", id: "deal-1", label: "Acme renewal" }, + { kind: "integration", id: "google:gmail", label: "Gmail" }, + { + kind: "integration", + id: "google:calendar", + label: "Google Calendar", + }, + ], + access: [ + "Read selected CRM records", + "Read connected Gmail messages", + "Read connected Google Calendar events", + ], + }); + }); + + it("rejects guessed integration resource objects", () => { + const result = builderDraftToolInput.safeParse({ + name: "Renewal prep", + description: "Prepare a renewal call brief.", + instructions: + "Run manually. Read the selected deal and summarize renewal risks for review.", + trigger: { + type: "MANUAL", + name: "Prepare renewal brief", + summary: "Run before a renewal call", + }, + recordScope: "SELECTED", + resources: [{ kind: "integration", id: "gmail", label: "gmail" }], + integrations: [], + actions: [ + { + type: "run.summary", + provider: "crm", + summary: "Write a reviewable renewal brief", + }, + ], + }); + + expect(result.success).toBe(false); + expect( + builderDraftToolInput.safeParse({ + name: "Renewal prep", + description: "Prepare a renewal call brief.", + instructions: + "Run manually. Read workspace deals and summarize renewal risks for review.", + trigger: { + type: "MANUAL", + name: "Prepare renewal brief", + summary: "Run before a renewal call", + }, + recordScope: "WORKSPACE", + resources: [], + integrations: ["crm"], + actions: [ + { + type: "run.summary", + provider: "crm", + summary: "Write a reviewable renewal brief", + }, + ], + }).success, + ).toBe(false); + }); + + it("trims trigger metadata and rejects blank text", () => { + const base = { + name: "Renewal prep", + description: "Prepare a renewal call brief.", + instructions: + "Run manually. Read workspace deals and summarize renewal risks for review.", + recordScope: "WORKSPACE" as const, + resources: [], + integrations: [], + actions: [ + { + type: "run.summary" as const, + provider: "crm" as const, + summary: " Write a reviewable renewal brief ", + }, + ], + }; + + expect( + builderDraftToolInput.safeParse({ + ...base, + trigger: { + type: "MANUAL", + name: " ", + summary: "Run before a renewal call", + }, + }).success, + ).toBe(false); + + const parsed = builderDraftToolInput.parse({ + ...base, + trigger: { + type: "MANUAL", + name: " Prepare renewal brief ", + summary: " Run before a renewal call ", + }, + }); + expect(parsed.trigger.name).toBe("Prepare renewal brief"); + expect(parsed.trigger.summary).toBe("Run before a renewal call"); + expect(parsed.actions[0]?.summary).toBe("Write a reviewable renewal brief"); + }); +}); diff --git a/apps/app/components/agent-builder/agent-builder-chat.tsx b/apps/app/components/agent-builder/agent-builder-chat.tsx index 6bca17f7..a4eaea97 100644 --- a/apps/app/components/agent-builder/agent-builder-chat.tsx +++ b/apps/app/components/agent-builder/agent-builder-chat.tsx @@ -22,6 +22,14 @@ import { import { Button } from "@crm/ui/components/button"; import { Icon } from "@crm/ui/components/icon"; import { Markdown } from "@crm/ui/components/markdown"; +import { + MessageScroller, + MessageScrollerButton, + MessageScrollerContent, + MessageScrollerItem, + MessageScrollerProvider, + MessageScrollerViewport, +} from "@crm/ui/components/message-scroller"; import { Reasoning } from "@crm/ui/components/reasoning"; import { useMountEffect } from "@crm/ui/hooks/use-mount-effect"; import { cn } from "@crm/ui/lib/utils"; @@ -282,84 +290,125 @@ export function AgentBuilderChat({ creatingAgent={creatingAgent} /> -
-
- {timeline.map((item) => - item.kind === "submission" ? ( - - ) : ( - - ), - )} - - {working && creatingAgent ? ( - - ) : null} - - {creatingAgent && data.builderArtifacts.length > 0 ? ( - - ) : null} - - {!working && - failure && - creatingAgent && - !reviewVersion && - data.agent?.status !== "LIVE" ? ( - send(retryPrompt) : null} - /> - ) : null} - - {!working && failure && !creatingAgent ? ( - send(retryPrompt) : null} - /> - ) : null} - - {creatingAgent && !working && reviewVersion ? ( - - ) : null} + + + + + {timeline.map((item) => ( + + {item.kind === "submission" ? ( + + ) : ( + + )} + + ))} - {creatingAgent && data.agent?.status === "LIVE" && !reviewVersion ? ( - - send({ - commandType: "CHAT", - message, - resources: [], - attachments: [], - }) - } - /> - ) : null} -
-
+ {working && creatingAgent ? ( + + + + ) : null} + + {creatingAgent && data.builderArtifacts.length > 0 ? ( + + + + ) : null} + + {!working && + failure && + creatingAgent && + !reviewVersion && + data.agent?.status !== "LIVE" ? ( + + send(retryPrompt) : null} + /> + + ) : null} + + {!working && failure && !creatingAgent ? ( + + send(retryPrompt) : null} + /> + + ) : null} + + {creatingAgent && !working && reviewVersion ? ( + + + + ) : null} + + {creatingAgent && + data.agent?.status === "LIVE" && + !reviewVersion ? ( + + + send({ + commandType: "CHAT", + message, + resources: [], + attachments: [], + }) + } + /> + + ) : null} + + + + +
@@ -463,43 +512,63 @@ function SharedAgentChat({ Read-only -
-
-
-

Shared by {conversation.ownerName}

-

- You can read this builder chat, but only its owner can continue or - change it. -

-
+ + + + + +
+

+ Shared by {conversation.ownerName} +

+

+ You can read this builder chat, but only its owner can + continue or change it. +

+
+ - {timeline.map((item) => - item.kind === "submission" ? ( - - ) : ( - - ), - )} + {timeline.map((item) => ( + + {item.kind === "submission" ? ( + + ) : ( + + )} + + ))} - {conversation.builderArtifacts.length > 0 ? ( - - ) : null} -
-
+ {conversation.builderArtifacts.length > 0 ? ( + + + + ) : null} + + + + + ); } diff --git a/docs/agent.md b/docs/agent.md index 358faacb..6003b621 100644 --- a/docs/agent.md +++ b/docs/agent.md @@ -220,9 +220,11 @@ delegation paths for custom agents. - **Creation requires the current `CREATE_AGENT` turn.** Every builder tool checks the purpose and command type in session auth. A normal builder chat cannot create a draft by prompt alone. -- **Builder output is typed.** `needs_input` carries one question and its choices for - the parent to surface through eve HITL. `draft_ready` carries the immutable version - ids. The specialist cannot ask directly because its `ask_question` is disabled. +- **Builder clarification is durable HITL.** The specialist calls eve's built-in + `ask_question` directly; descendant input requests are proxied to the root channel, + and the same child turn resumes when the user answers. The authored + `tools/ask_question.ts` disable override must stay absent. Builder task output is + typed as `draft_ready` and carries the immutable version ids only after save. - **Empty never means all.** A version chooses `SELECTED` or `WORKSPACE` record scope. Selected scope requires at least one record tagged in that private conversation; workspace scope is an explicit grant and cannot also list selected records. @@ -244,9 +246,10 @@ delegation paths for custom agents. and current run state. Every runner tool also checks the `team-agent` purpose and revalidates scope and action permission. - **No generic execution surface.** Both specialists disable shell, file, arbitrary - web, todo and direct-question built-ins. CRM access exists only through their small - authored tool sets. Tool code runs in the trusted app runtime; the sandbox remains - isolated and deny-all. + web and todo built-ins. The runner also disables direct questions; the builder keeps + only `ask_question` for durable clarification. CRM access exists only through their + small authored tool sets. Tool code runs in the trusted app runtime; the sandbox + remains isolated and deny-all. Runner manifests fail closed when either the explicit record-scope mode or an activity type grant is missing. Versions created before these typed permissions were