-
setStep(i, { title: e.currentTarget.value })}
- />
-
setStep(i, { status: normStatus(e.currentTarget.value) })}
- >
-
- {(opt) => {language.t(STATUS_LABEL_KEY[opt] as never)} }
-
-
-
removeStep(i)}
- aria-label={language.t("composer.goal.editPlan.removeStep")}
- >
-
+
)}
@@ -156,7 +245,7 @@ export function GoalPlanEditDialog(props: {
{language.t("composer.goal.editPlan.cancel")}
- {language.t("composer.goal.editPlan.save")}
+ {language.t(challenge() ? "composer.goal.editPlan.confirm" : "composer.goal.editPlan.save")}
diff --git a/packages/app/src/components/deepagent/panel-goal-contract.test.ts b/packages/app/src/components/deepagent/panel-goal-contract.test.ts
index 0a95d393..276650c5 100644
--- a/packages/app/src/components/deepagent/panel-goal-contract.test.ts
+++ b/packages/app/src/components/deepagent/panel-goal-contract.test.ts
@@ -8,6 +8,7 @@ import {
resumeGoal,
stopGoal,
goalStatus,
+ buildGoalPlanWrite,
editPlanGoal,
fetchCapabilities,
} from "./panel-goal.api"
@@ -54,7 +55,12 @@ describe("Expert Panel route contract (§C)", () => {
test("armPanel POSTs /deepagent/panel/arm with rounds and returns the effective armed state + depth", async () => {
const calls: Recorded[] = []
- const result = await armPanel(client(calls, { sessionID: "ses_1", armed: true, rounds: "multi" }), "ses_1", true, "multi")
+ const result = await armPanel(
+ client(calls, { sessionID: "ses_1", armed: true, rounds: "multi" }),
+ "ses_1",
+ true,
+ "multi",
+ )
expect(calls).toEqual([
{
method: "POST",
@@ -75,7 +81,11 @@ describe("Expert Panel route contract (§C)", () => {
test("fetchPanelStatus tolerates a missing body (disarmed, not explicit, single-round default)", async () => {
const calls: Recorded[] = []
- expect(await fetchPanelStatus(client(calls, {}), "ses_1")).toEqual({ armed: false, explicit: false, rounds: "single" })
+ expect(await fetchPanelStatus(client(calls, {}), "ses_1")).toEqual({
+ armed: false,
+ explicit: false,
+ rounds: "single",
+ })
})
})
@@ -118,27 +128,166 @@ describe("Goal Loop route contract (§D)", () => {
expect(await goalStatus(client(calls, { goal: null }), "ses_1")).toBeNull()
})
- test("editPlanGoal POSTs /deepagent/goal/edit-plan with { sessionID, plan } and returns ok", async () => {
+ test("editPlanGoal POSTs the strict durable admission envelope and returns its receipt", async () => {
const calls: Recorded[] = []
- const plan = {
+ const planWrite = {
+ operation: "advance" as const,
+ expected_plan_id: "plan_1",
+ expected_version: 7,
goal: "ship it",
- steps: [
- { step_id: "step_1", title: "revised", status: "pending" },
- { title: "new step" },
- ],
+ assumptions: ["CI is available"],
+ steps: [{ step_id: "step_1", title: "verify", status: "active" as const }],
+ active_step_id: "step_1",
+ }
+ const receipt = {
+ state: "queued" as const,
+ activity_id: "activity_1",
+ request_id: "request_1",
+ candidate_hash: `sha256:${"a".repeat(64)}`,
}
- const ok = await editPlanGoal(client(calls, { ok: true }), "ses_1", plan)
+ const result = await editPlanGoal(client(calls, receipt), {
+ sessionID: "ses_1",
+ requestID: "request_1",
+ planWrite,
+ qualityChallengeID: "challenge_1",
+ })
expect(calls).toEqual([
- { method: "POST", url: "/deepagent/goal/edit-plan", body: { sessionID: "ses_1", plan }, headers: JSON_HEADERS },
+ {
+ method: "POST",
+ url: "/deepagent/goal/edit-plan",
+ body: {
+ sessionID: "ses_1",
+ request_id: "request_1",
+ plan_write: planWrite,
+ quality_challenge_id: "challenge_1",
+ },
+ headers: JSON_HEADERS,
+ },
])
- expect(ok).toBe(true)
+ expect(result).toEqual(receipt)
})
- test("editPlanGoal returns false when the server refuses (no goal / terminal)", async () => {
+ test("editPlanGoal leaves a missing response body explicit", async () => {
const calls: Recorded[] = []
- expect(await editPlanGoal(client(calls, { ok: false }), "ses_1", { goal: "g", steps: [] })).toBe(false)
- // ...and tolerates a missing body (older server) as false.
- expect(await editPlanGoal(client(calls, {}), "ses_1", { goal: "g", steps: [] })).toBe(false)
+ expect(
+ await editPlanGoal(client(calls, undefined), {
+ sessionID: "ses_1",
+ requestID: "request_1",
+ planWrite: {
+ operation: "advance",
+ expected_plan_id: "plan_1",
+ expected_version: 1,
+ goal: "g",
+ assumptions: [],
+ steps: [{ step_id: "step_1", title: "step", status: "active" }],
+ active_step_id: "step_1",
+ },
+ }),
+ ).toBeUndefined()
+ })
+
+ test("buildGoalPlanWrite emits advance for status and blocker-note changes", () => {
+ const result = buildGoalPlanWrite(
+ {
+ plan_id: "plan_1",
+ plan_version: 4,
+ goal: "ship",
+ assumptions: ["CI"],
+ steps: [
+ { step_id: "step_a", title: "Implement", acceptance: "tests pass", assigned_agent: "build" },
+ { step_id: "step_b", title: "Review", acceptance: "approved", assigned_agent: "review" },
+ ],
+ },
+ {
+ goal: "ship",
+ assumptions: ["CI"],
+ steps: [
+ {
+ step_id: "step_a",
+ title: "Implement",
+ acceptance: "tests pass",
+ assigned_agent: "build",
+ status: "done",
+ },
+ {
+ step_id: "step_b",
+ title: "Review",
+ acceptance: "approved",
+ assigned_agent: "review",
+ status: "blocked",
+ note: "waiting for owner",
+ },
+ ],
+ },
+ )
+
+ expect(result.operation).toBe("advance")
+ expect(result.expected_plan_id).toBe("plan_1")
+ expect(result.expected_version).toBe(4)
+ expect(result.steps.map((step) => step.step_id)).toEqual(["step_a", "step_b"])
+ expect(result.active_step_id).toBeNull()
+ expect(result.steps[0]).toMatchObject({ acceptance: "tests pass", assigned_agent: "build", note: null })
+ expect(result.steps[1]).toMatchObject({
+ acceptance: "approved",
+ assigned_agent: "review",
+ note: "waiting for owner",
+ })
+ })
+
+ test("buildGoalPlanWrite keeps absent optional fields as explicit wire nulls", () => {
+ const result = buildGoalPlanWrite(
+ {
+ plan_id: "plan_1",
+ plan_version: 1,
+ goal: "ship",
+ assumptions: [],
+ steps: [{ step_id: "step_a", title: "Implement" }],
+ },
+ {
+ goal: "ship",
+ assumptions: [],
+ steps: [{ step_id: "step_a", title: "Implement", status: "active" }],
+ },
+ )
+
+ expect(result.steps[0]).toEqual({
+ step_id: "step_a",
+ title: "Implement",
+ status: "active",
+ acceptance: null,
+ assigned_agent: null,
+ note: null,
+ })
+ })
+
+ test("buildGoalPlanWrite replans structural edits without rebinding a renamed step identity", () => {
+ const ids = ["step_fresh"]
+ const result = buildGoalPlanWrite(
+ {
+ plan_id: "plan_1",
+ plan_version: 9,
+ goal: "ship",
+ assumptions: [],
+ steps: [
+ { step_id: "step_a", title: "Implement", acceptance: "tests pass" },
+ { step_id: "step_b", title: "Review", acceptance: "approved" },
+ ],
+ },
+ {
+ goal: "ship",
+ assumptions: [],
+ steps: [
+ { step_id: "step_b", title: "Review", acceptance: "approved", status: "pending" },
+ { step_id: "step_a", title: "Implement and deploy", acceptance: "tests pass", status: "active" },
+ ],
+ },
+ () => ids.shift() ?? "unexpected",
+ )
+
+ expect(result.operation).toBe("replan")
+ expect(result.replan_reason).toBe("human_goal_edit")
+ expect(result.steps.map((step) => step.step_id)).toEqual(["step_b", "step_fresh"])
+ expect(result.active_step_id).toBe("step_fresh")
})
})
diff --git a/packages/app/src/components/deepagent/panel-goal.api.ts b/packages/app/src/components/deepagent/panel-goal.api.ts
index c5cdb8c6..ea06dd57 100644
--- a/packages/app/src/components/deepagent/panel-goal.api.ts
+++ b/packages/app/src/components/deepagent/panel-goal.api.ts
@@ -183,38 +183,169 @@ export const stopGoal = (client: PanelGoalClient, sessionID: string) => goalMuta
/** A plan step as the edit-plan payload carries it (loose input: step_id/status optional, mirroring the
* backend PlanInput — evidence is runtime-owned and never sent from the client). */
+export type GoalPlanStatus = "pending" | "active" | "done" | "cancelled" | "blocked"
+
export type GoalPlanStepInput = {
step_id?: string
title: string
- status?: string
+ status: GoalPlanStatus
acceptance?: string | null
assigned_agent?: string | null
note?: string | null
}
-export type GoalPlanInput = {
+export type GoalPlanWriteInput = {
+ operation: "create" | "advance" | "replan"
+ expected_plan_id: string | null
+ expected_version: number | null
+ replan_reason?: string
goal: string
steps: GoalPlanStepInput[]
- assumptions?: string[]
- active_step_id?: string | null
+ assumptions: string[]
+ active_step_id: string | null
+}
+
+export type GoalPlanEditChallenge = {
+ challenge_id: string
+ candidate_hash: string
+ expected_plan_id: string
+ expected_version: number
+ issued_at: string
+ expires_at: string
+}
+
+export type GoalPlanEditFailure =
+ | {
+ kind: "validation"
+ code: string
+ offending_step_ids: string[]
+ previous_plan_id: string | null
+ previous_plan_version: number | null
+ }
+ | {
+ kind: "conflict"
+ expected_plan_id: string | null
+ expected_version: number | null
+ actual_plan_id: string | null
+ actual_version: number | null
+ }
+ | { kind: "target_unavailable" | "runtime_error"; message: string }
+
+export type GoalPlanEditReceipt = {
+ state: "challenged" | "queued" | "applied" | "rejected" | "conflict" | "runtime_error"
+ activity_id: string
+ request_id: string
+ candidate_hash: string
+ challenge?: GoalPlanEditChallenge
+ result?: { plan_id: string; doc_id: string; version: number; changed: boolean }
+ failure?: GoalPlanEditFailure
+}
+
+export type GoalPlanEditDraft = {
+ goal: string
+ assumptions: string[]
+ steps: GoalPlanStepInput[]
}
/**
- * V4.1 §S2 — hot-edit the plan of a RUNNING or PAUSED goal. POSTs the revised plan on the goal control
- * channel; the driver applies it between ticks (durable-doc upsert + stall re-baseline). Returns false
- * when no goal is running or it reached a terminal phase (the server's orphan guard).
+ * Build a versioned write against the exact live-plan snapshot the user edited. Structural changes
+ * are replans; a status/note-only update over the same ordered identities is an advance.
*/
+export const buildGoalPlanWrite = (
+ current: {
+ plan_id: string
+ plan_version: number
+ goal: string
+ assumptions: string[]
+ steps: Array<{
+ step_id: string
+ title: string
+ acceptance?: string | null
+ assigned_agent?: string | null
+ }>
+ },
+ draft: GoalPlanEditDraft,
+ createStepID: () => string = () => `step_${globalThis.crypto.randomUUID()}`,
+): GoalPlanWriteInput => {
+ const goal = draft.goal.trim()
+ const assumptions = draft.assumptions.map((value) => value.trim())
+ if (!goal || !Number.isSafeInteger(current.plan_version) || current.plan_version < 0) {
+ throw new Error("Plan edit requires a valid authority snapshot")
+ }
+ if (draft.steps.length === 0) throw new Error("Plan edit requires at least one step")
+
+ const originalByID = new Map(current.steps.map((step) => [step.step_id, step] as const))
+ const text = (value: string | null | undefined) => (value ?? "").trim()
+ const sameIdentity = (left: GoalPlanStepInput, right: (typeof current.steps)[number]) =>
+ text(left.title) === text(right.title) &&
+ text(left.acceptance) === text(right.acceptance) &&
+ text(left.assigned_agent) === text(right.assigned_agent)
+ const structuralChange =
+ goal !== current.goal.trim() ||
+ JSON.stringify(assumptions) !== JSON.stringify(current.assumptions.map((value) => value.trim())) ||
+ draft.steps.length !== current.steps.length ||
+ draft.steps.some((step, index) => step.step_id !== current.steps[index]?.step_id || !sameIdentity(step, current.steps[index]))
+
+ const used = new Set
()
+ const freshStepID = () => {
+ const id = createStepID().trim()
+ if (!id || used.has(id) || originalByID.has(id)) throw new Error("Plan edit generated a duplicate step identity")
+ return id
+ }
+ const steps = draft.steps.map((step) => {
+ const original = step.step_id ? originalByID.get(step.step_id) : undefined
+ const stepID = original && sameIdentity(step, original) ? original.step_id : freshStepID()
+ if (used.has(stepID)) throw new Error("Plan edit contains a duplicate step identity")
+ used.add(stepID)
+ const title = step.title.trim()
+ const note = text(step.note) || null
+ if (!title) throw new Error("Plan edit step title cannot be empty")
+ if (step.status === "blocked" && !note) throw new Error("Blocked plan steps require a note")
+ return {
+ step_id: stepID,
+ title,
+ status: step.status,
+ acceptance: text(step.acceptance) || null,
+ assigned_agent: text(step.assigned_agent) || null,
+ note,
+ }
+ })
+ const active = steps.filter((step) => step.status === "active")
+ if (active.length > 1) throw new Error("Plan edit cannot contain multiple active steps")
+
+ return {
+ operation: structuralChange ? "replan" : "advance",
+ expected_plan_id: current.plan_id,
+ expected_version: current.plan_version,
+ ...(structuralChange ? { replan_reason: "human_goal_edit" } : {}),
+ goal,
+ assumptions,
+ steps,
+ active_step_id: active[0]?.step_id ?? null,
+ }
+}
+
+/** Admit a durable human plan-edit activity. Exact network retries reuse request_id. */
export const editPlanGoal = async (
client: PanelGoalClient,
- sessionID: string,
- plan: GoalPlanInput,
-): Promise => {
- const response = await client.client.request<{ ok: boolean }>({
+ input: {
+ sessionID: string
+ requestID: string
+ planWrite: GoalPlanWriteInput
+ qualityChallengeID?: string
+ },
+): Promise => {
+ const response = await client.client.request({
method: "POST",
url: "/deepagent/goal/edit-plan",
- body: { sessionID, plan },
+ body: {
+ sessionID: input.sessionID,
+ request_id: input.requestID,
+ plan_write: input.planWrite,
+ ...(input.qualityChallengeID ? { quality_challenge_id: input.qualityChallengeID } : {}),
+ },
headers: JSON_HEADERS,
})
- return response.data?.ok ?? false
+ return response.data
}
export const goalStatus = async (
diff --git a/packages/app/src/components/prompt-input.tsx b/packages/app/src/components/prompt-input.tsx
index 9aee1c96..ee9cbf34 100644
--- a/packages/app/src/components/prompt-input.tsx
+++ b/packages/app/src/components/prompt-input.tsx
@@ -87,6 +87,10 @@ import { pathKey } from "@/utils/path-key"
import { base64Encode } from "@deepagent-code/core/util/encode"
import { displayName } from "@/pages/layout/helpers"
+export type PromptInputControl = {
+ cancelPending: () => Promise
+}
+
interface PromptInputProps {
class?: string
variant?: "dock" | "new-session"
@@ -99,6 +103,8 @@ interface PromptInputProps {
onQueue?: (draft: FollowupDraft) => void
onAbort?: () => void
onSubmit?: () => void
+ disabled?: boolean
+ controlRef?: (control: PromptInputControl | undefined) => void
}
const EXAMPLES = [
@@ -220,7 +226,7 @@ export const PromptInput: Component = (props) => {
const makeTextPrompt = (text: string): Prompt => [{ type: "text", content: text, start: 0, end: text.length }]
- const finishDraftReview = (result: { editedGoal: string } | false) => {
+ const finishDraftReview = (result: { editedGoal: string } | false, restore = true) => {
const current = draftReview()
if (!current) return
setDraftReview(undefined)
@@ -228,6 +234,7 @@ export const PromptInput: Component = (props) => {
draftReviewResolve = undefined
resolve?.(result)
if (result !== false) return
+ if (!restore) return
prompt.set(current.originalPrompt, current.originalCursor)
requestAnimationFrame(() => {
@@ -281,6 +288,13 @@ export const PromptInput: Component = (props) => {
if (!draftReview() && !draftPreparing()) draftPreparePrompt = undefined
}
+ const discardDraftPrepare = () => {
+ if (draftReview()) finishDraftReview(false, false)
+ setDraftPreparing(false)
+ setDraftPreview("")
+ draftPreparePrompt = undefined
+ }
+
// Copy the preserved partial draft into the editor so the user can edit and resubmit it. A canceled
// stream has no server-persisted draft id, so it can't be submitted as an intelligence draft directly.
const useDraftPreview = () => {
@@ -1295,7 +1309,7 @@ export const PromptInput: Component = (props) => {
})
})
- const { abort, handleSubmit } = createPromptSubmit({
+ const { abort, cancelPending, handleSubmit } = createPromptSubmit({
info,
imageAttachments,
commentCount,
@@ -1320,10 +1334,24 @@ export const PromptInput: Component = (props) => {
onPromptPrepareStart: startDraftPrepare,
onPromptPrepareProgress: updateDraftPrepare,
onPromptPrepareEnd: stopDraftPrepare,
+ onPromptPrepareDiscard: discardDraftPrepare,
confirmPromptDraft,
})
+ const submitControl = {
+ cancelPending: async () => {
+ discardDraftPrepare()
+ await cancelPending()
+ },
+ }
+ props.controlRef?.(submitControl)
+ onCleanup(() => props.controlRef?.(undefined))
+
const handlePromptSubmit = (event: Event) => {
+ if (props.disabled) {
+ event.preventDefault()
+ return
+ }
// Read-only finished subagent: swallow the submit so no new turn is started.
if (subagentFinished()) {
event.preventDefault()
@@ -1349,6 +1377,11 @@ export const PromptInput: Component = (props) => {
}
const handleKeyDown = (event: KeyboardEvent) => {
+ if (props.disabled) {
+ event.preventDefault()
+ event.stopPropagation()
+ return
+ }
if (draftPreparing()) {
if (event.key === "Escape" || (event.ctrlKey && event.code === "KeyG")) void abort()
event.preventDefault()
@@ -1808,7 +1841,7 @@ export const PromptInput: Component = (props) => {
{
- if (draftPreparing()) return
+ if (draftPreparing() || props.disabled) return
const target = e.target
if (!(target instanceof HTMLElement)) return
if (
@@ -1835,8 +1868,8 @@ export const PromptInput: Component
= (props) => {
role="textbox"
aria-multiline="true"
aria-label={placeholder()}
- aria-disabled={draftPreparing()}
- contenteditable={draftPreparing() ? "false" : "true"}
+ aria-disabled={draftPreparing() || props.disabled}
+ contenteditable={draftPreparing() || props.disabled ? "false" : "true"}
autocapitalize={store.mode === "normal" ? "sentences" : "off"}
autocorrect={store.mode === "normal" ? "on" : "off"}
spellcheck={store.mode === "normal"}
@@ -1857,7 +1890,7 @@ export const PromptInput: Component = (props) => {
"font-mono!": store.mode === "shell",
// Editor keeps the raw user input during preparation (the streamed draft shows in the
// panel below), so it reads normally — locked to edits, not greyed as a placeholder.
- "cursor-wait": draftPreparing(),
+ "cursor-wait": draftPreparing() || props.disabled,
}}
style={{ "padding-bottom": space }}
/>
@@ -1900,7 +1933,7 @@ export const PromptInput: Component = (props) => {
= []
-const sentPromptAsync: Array<{ directory: string; metadata?: unknown; text?: string }> = []
+const preparedIntents: Array<{ intentID?: string; source?: string }> = []
+const sentPromptAsync: Array<{
+ directory: string
+ metadata?: unknown
+ text?: string
+ intentID?: string
+ intentSource?: string
+ intentVariant?: string
+}> = []
const promptPrepareEvents: string[] = []
const promptPrepareProgress: string[] = []
@@ -38,6 +46,7 @@ let variant: string | undefined
// normalizer maps to "intelligence"); either way submit sends "intelligence" on the wire.
let promptMode: "direct" | "intelligence" | "wish" = "direct"
let appLocale = "en"
+let releaseDelayedPrompt: (() => void) | undefined
const promptValue: Prompt = [{ type: "text", content: "ls", start: 0, end: 2 }]
const flushAsyncSubmit = () => new Promise((resolve) => setTimeout(resolve, 0))
@@ -60,12 +69,27 @@ const clientFor = (directory: string) => {
return { data: undefined }
},
prompt: async () => ({ data: undefined }),
- promptAsync: async (payload?: { metadata?: unknown; parts?: Array<{ type: string; text?: string }> }) => {
- sentPromptAsync.push({
+ promptAsync: async (payload?: {
+ metadata?: unknown
+ parts?: Array<{ type: string; text?: string }>
+ intentID?: string
+ intentSource?: string
+ intentVariant?: string
+ }) => {
+ const sent = {
directory,
metadata: payload?.metadata,
text: payload?.parts?.find((part) => part.type === "text")?.text,
- })
+ intentID: payload?.intentID,
+ intentSource: payload?.intentSource,
+ intentVariant: payload?.intentVariant,
+ }
+ sentPromptAsync.push(sent)
+ if (sent.text === "prompt waits after admission") {
+ await new Promise((resolve) => {
+ releaseDelayedPrompt = resolve
+ })
+ }
return { data: undefined }
},
command: async () => ({ data: undefined }),
@@ -75,7 +99,13 @@ const clientFor = (directory: string) => {
request: async (payload: {
url?: string
path?: { sessionID?: string }
- body?: { mode?: string; output_language?: string; parts?: Array<{ type: string; text?: string }> }
+ body?: {
+ mode?: string
+ output_language?: string
+ intent_id?: string
+ intent_source?: string
+ parts?: Array<{ type: string; text?: string }>
+ }
signal?: AbortSignal
}) => {
const text = payload.body?.parts?.find((part) => part.type === "text")?.text
@@ -86,6 +116,7 @@ const clientFor = (directory: string) => {
outputLanguage: payload.body?.output_language,
text,
})
+ preparedIntents.push({ intentID: payload.body?.intent_id, source: payload.body?.intent_source })
if (text === "prepare fails") {
throw new Error("POST /session/ses_1/prompt_prepare returned 400", {
cause: {
@@ -115,6 +146,7 @@ const clientFor = (directory: string) => {
route: text === "hello" ? "general" : "code",
goal: "Prepared goal",
preview: "# Prepared prompt",
+ intent_id: payload.body?.intent_id,
}
return {
data: new ReadableStream({
@@ -311,6 +343,7 @@ beforeEach(() => {
sentShell.length = 0
syncedDirectories.length = 0
preparedDrafts.length = 0
+ preparedIntents.length = 0
sentPromptAsync.length = 0
promptPrepareEvents.length = 0
promptPrepareProgress.length = 0
@@ -319,6 +352,8 @@ beforeEach(() => {
variant = undefined
promptMode = "direct"
appLocale = "en"
+ releaseDelayedPrompt?.()
+ releaseDelayedPrompt = undefined
for (const key of Object.keys(storedSessions)) delete storedSessions[key]
})
@@ -487,6 +522,10 @@ describe("prompt submit worktree selection", () => {
{ directory: "/repo/main", sessionID: "session-1", mode: "intelligence", outputLanguage: "english", text: "ls" },
])
expect(sentPromptAsync[0]?.text).toBe("Edited prepared goal")
+ expect(preparedIntents[0]?.intentID).toBe(sentPromptAsync[0]?.intentID)
+ expect(preparedIntents[0]?.source).toBe("intelligence")
+ expect(sentPromptAsync[0]?.intentSource).toBe("intelligence")
+ expect(sentPromptAsync[0]?.intentVariant).toBe("rewritten")
expect(sentPromptAsync[0]?.metadata).toEqual({
deepagent: {
prompt_pipeline: {
@@ -535,6 +574,7 @@ describe("prompt submit worktree selection", () => {
params = { id: "session-1" }
promptMode = "intelligence"
const confirms: string[] = []
+ const discards: string[] = []
promptValue[0] = { type: "text", content: "hello", start: 0, end: 5 }
const submit = createPromptSubmit({
@@ -555,6 +595,7 @@ describe("prompt submit worktree selection", () => {
confirms.push("called")
return { editedGoal: "should not submit" }
},
+ onPromptPrepareDiscard: () => discards.push("discard"),
onSubmit: () => undefined,
})
@@ -564,6 +605,7 @@ describe("prompt submit worktree selection", () => {
await flushAsyncSubmit()
expect(confirms).toEqual([])
+ expect(discards).toEqual(["discard"])
expect(preparedDrafts).toEqual([
{
directory: "/repo/main",
@@ -574,6 +616,8 @@ describe("prompt submit worktree selection", () => {
},
])
expect(sentPromptAsync[0]?.text).toBe("hello")
+ expect(preparedIntents[0]?.intentID).toBe(sentPromptAsync[0]?.intentID)
+ expect(sentPromptAsync[0]?.intentVariant).toBe("original")
expect(sentPromptAsync[0]?.metadata).toEqual({
deepagent: {
agent_mode_override: "general",
@@ -658,4 +702,86 @@ describe("prompt submit worktree selection", () => {
expect(sentPromptAsync).toEqual([])
promptValue[0] = { type: "text", content: "ls", start: 0, end: 2 }
})
+
+ test("supersedes an in-flight intelligence preparation without admitting or restoring it", async () => {
+ params = { id: "session-1" }
+ promptMode = "intelligence"
+ promptValue[0] = { type: "text", content: "prepare waits", start: 0, end: 13 }
+ const discards: string[] = []
+
+ const submit = createPromptSubmit({
+ info: () => ({ id: "session-1" }),
+ imageAttachments: () => [],
+ commentCount: () => 0,
+ autoAccept: () => false,
+ mode: () => "normal",
+ working: () => false,
+ editor: () => undefined,
+ queueScroll: () => undefined,
+ promptLength: (value) => value.reduce((sum, part) => sum + ("content" in part ? part.content.length : 0), 0),
+ addToHistory: () => undefined,
+ resetHistoryNavigation: () => undefined,
+ setMode: () => undefined,
+ setPopover: () => undefined,
+ onPromptPrepareDiscard: () => discards.push("discard"),
+ onSubmit: () => undefined,
+ })
+
+ await submit.handleSubmit({ preventDefault: () => undefined } as unknown as Event)
+ await flushAsyncSubmit()
+ await submit.cancelPending()
+ await flushAsyncSubmit()
+
+ expect(discards).toEqual(["discard"])
+ expect(sentPromptAsync).toEqual([])
+ promptValue[0] = { type: "text", content: "ls", start: 0, end: 2 }
+ })
+
+ test("joins an admission already in flight and rejects a duplicate local submit", async () => {
+ params = { id: "session-1" }
+ promptValue[0] = {
+ type: "text",
+ content: "prompt waits after admission",
+ start: 0,
+ end: 28,
+ }
+
+ const submit = createPromptSubmit({
+ info: () => ({ id: "session-1" }),
+ imageAttachments: () => [],
+ commentCount: () => 0,
+ autoAccept: () => false,
+ mode: () => "normal",
+ working: () => false,
+ editor: () => undefined,
+ queueScroll: () => undefined,
+ promptLength: (value) => value.reduce((sum, part) => sum + ("content" in part ? part.content.length : 0), 0),
+ addToHistory: () => undefined,
+ resetHistoryNavigation: () => undefined,
+ setMode: () => undefined,
+ setPopover: () => undefined,
+ onSubmit: () => undefined,
+ })
+
+ const event = { preventDefault: () => undefined } as unknown as Event
+ await submit.handleSubmit(event)
+ await flushAsyncSubmit()
+ expect(sentPromptAsync).toHaveLength(1)
+
+ await submit.handleSubmit(event)
+ expect(sentPromptAsync).toHaveLength(1)
+
+ let canceled = false
+ const cancel = submit.cancelPending().then(() => {
+ canceled = true
+ })
+ await flushAsyncSubmit()
+ expect(canceled).toBe(false)
+
+ releaseDelayedPrompt?.()
+ await cancel
+ expect(canceled).toBe(true)
+ expect(sentPromptAsync).toHaveLength(1)
+ promptValue[0] = { type: "text", content: "ls", start: 0, end: 2 }
+ })
})
diff --git a/packages/app/src/components/prompt-input/submit.ts b/packages/app/src/components/prompt-input/submit.ts
index 7e98fdf9..814be647 100644
--- a/packages/app/src/components/prompt-input/submit.ts
+++ b/packages/app/src/components/prompt-input/submit.ts
@@ -57,6 +57,7 @@ export type DeepAgentPromptPrepareResult = {
route: "code" | "general"
goal: string
preview: string
+ intent_id?: string
}
export type DeepAgentPromptConfirmResult = { editedGoal: string }
@@ -94,12 +95,15 @@ type FollowupSendInput = {
sync: ReturnType
draft: FollowupDraft
messageID?: string
+ intentID?: string
+ intentSource?: "composer" | "intelligence" | "followup" | "rewrite"
optimisticBusy?: boolean
before?: () => Promise | boolean
onBeforeSubmit?: () => void
onPromptPrepareStart?: () => void
onPromptPrepareProgress?: (preview: string) => void
onPromptPrepareEnd?: () => void
+ onPromptPrepareDiscard?: () => void
promptPrepareSignal?: AbortSignal
promptOutputLanguage?: DeepAgentPromptOutputLanguage
confirmPromptDraft?: (draft: DeepAgentPromptPrepareResult) => Promise
@@ -120,6 +124,8 @@ async function prepareDeepAgentPromptDraft(input: {
mode: DeepAgentPromptModeForConfirmation
outputLanguage: DeepAgentPromptOutputLanguage
parts: SessionPromptAsyncInput["parts"]
+ intentID: string
+ intentSource: "composer" | "intelligence" | "followup" | "rewrite"
signal?: AbortSignal
onProgress?: (preview: string) => void
}) {
@@ -131,6 +137,8 @@ async function prepareDeepAgentPromptDraft(input: {
body: {
mode: input.mode,
output_language: input.outputLanguage,
+ intent_id: input.intentID,
+ intent_source: input.intentSource,
parts: input.parts,
},
headers: {
@@ -212,8 +220,9 @@ export async function sendFollowupDraft(input: FollowupSendInput) {
}
const wait = async () => {
+ if (input.promptPrepareSignal?.aborted) return false
const ok = await input.before?.()
- if (ok === false) return false
+ if (ok === false || input.promptPrepareSignal?.aborted) return false
return true
}
@@ -251,6 +260,7 @@ export async function sendFollowupDraft(input: FollowupSendInput) {
}
const messageID = input.messageID ?? Identifier.ascending("message")
+ const intentID = input.intentID ?? Identifier.ascending("message")
const buildParts = (promptText: string) =>
buildRequestParts({
prompt: input.draft.prompt,
@@ -285,9 +295,14 @@ export async function sendFollowupDraft(input: FollowupSendInput) {
mode,
outputLanguage: input.promptOutputLanguage ?? "english",
parts: preparedParts.requestParts,
+ intentID,
+ intentSource: input.intentSource ?? "intelligence",
signal: input.promptPrepareSignal,
onProgress: input.onPromptPrepareProgress,
})
+ if (prepared.intent_id && prepared.intent_id !== intentID) {
+ throw new Error("Prompt draft prepare returned a different intent")
+ }
} catch (err) {
setIdle()
input.onPromptPrepareEnd?.()
@@ -296,6 +311,7 @@ export async function sendFollowupDraft(input: FollowupSendInput) {
}
input.onPromptPrepareEnd?.()
if (prepared.route === "general") {
+ input.onPromptPrepareDiscard?.()
metadata = {
deepagent: {
agent_mode_override: "general",
@@ -306,7 +322,7 @@ export async function sendFollowupDraft(input: FollowupSendInput) {
}
} else {
const confirmed = await input.confirmPromptDraft?.(prepared)
- if (!confirmed) {
+ if (!confirmed || input.promptPrepareSignal?.aborted) {
setIdle()
return false
}
@@ -354,6 +370,7 @@ export async function sendFollowupDraft(input: FollowupSendInput) {
if (!waited && !(await wait())) {
return false
}
+ if (input.promptPrepareSignal?.aborted) return false
input.onBeforeSubmit?.()
batch(() => {
@@ -366,6 +383,9 @@ export async function sendFollowupDraft(input: FollowupSendInput) {
agent: input.draft.agent,
model: input.draft.model,
messageID,
+ intentID,
+ intentSource: input.intentSource ?? (mode ? "intelligence" : "composer"),
+ intentVariant: confirmedDraft ? "rewritten" : "original",
parts: submittedParts.requestParts,
variant: input.draft.variant,
metadata,
@@ -404,6 +424,7 @@ type PromptSubmitInput = {
onPromptPrepareStart?: () => void
onPromptPrepareProgress?: (preview: string) => void
onPromptPrepareEnd?: () => void
+ onPromptPrepareDiscard?: () => void
confirmPromptDraft?: (draft: DeepAgentPromptPrepareResult) => Promise
}
@@ -430,7 +451,17 @@ export function createPromptSubmit(input: PromptSubmitInput) {
const language = useLanguage()
const params = useParams()
const pendingKey = (sessionID: string) => ScopedKey.from(sdk.scope, sessionID)
- let activePreparation: { sessionID: string; controller: AbortController } | undefined
+ let submissionSequence = 0
+ let activeSubmission:
+ | {
+ id: number
+ sessionID: string
+ controller: AbortController
+ preparing: boolean
+ admissionStarted: boolean
+ promise: Promise
+ }
+ | undefined
const errorMessage = (err: unknown) => {
if (err && typeof err === "object" && "data" in err) {
@@ -441,8 +472,20 @@ export function createPromptSubmit(input: PromptSubmitInput) {
return language.t("common.requestFailed")
}
+ const cancelPending = async (options?: { preserveDraft?: boolean }) => {
+ const submission = activeSubmission
+ if (!submission) return
+ submission.controller.abort()
+ if (submission.preparing) {
+ if (options?.preserveDraft) input.onPromptPrepareEnd?.()
+ else input.onPromptPrepareDiscard?.()
+ }
+ await submission.promise
+ return submission
+ }
+
const abort = async () => {
- const sessionID = activePreparation?.sessionID ?? params.id
+ const sessionID = activeSubmission?.sessionID ?? params.id
if (!sessionID) return Promise.resolve()
// D3: any stop resets the scenario to `direct` and pauses scenario automation for this
@@ -452,10 +495,12 @@ export function createPromptSubmit(input: PromptSubmitInput) {
input.onAbort?.()
- if (activePreparation) {
- activePreparation.controller.abort()
- activePreparation = undefined
- return Promise.resolve()
+ const submission = await cancelPending({ preserveDraft: true })
+ if (submission) {
+ if (submission.admissionStarted) {
+ await sdk.client.session.abort({ sessionID }).catch(() => {})
+ }
+ return
}
const key = pendingKey(sessionID)
@@ -515,6 +560,7 @@ export function createPromptSubmit(input: PromptSubmitInput) {
const handleSubmit = async (event: Event) => {
event.preventDefault()
+ if (activeSubmission) return
const currentPrompt = prompt.current()
const text = currentPrompt.map((part) => ("content" in part ? part.content : "")).join("")
@@ -733,8 +779,9 @@ export function createPromptSubmit(input: PromptSubmitInput) {
const commentItems = context.filter((item) => item.type === "file" && !!item.comment?.trim())
const messageID = Identifier.ascending("message")
+ const intentID = Identifier.ascending("message")
const preparesPromptDraft = promptPipelineMode(draft.metadata) === "intelligence"
- const preparationAbort = preparesPromptDraft ? new AbortController() : undefined
+ const controller = new AbortController()
const removeOptimisticMessage = () => {
sync.session.optimistic.remove({
@@ -757,7 +804,6 @@ export function createPromptSubmit(input: PromptSubmitInput) {
sync.set("session_status", session.id, { type: "busy" })
}
- const controller = preparationAbort ?? new AbortController()
const cleanup = () => {
if (sessionDirectory === projectDirectory) {
sync.set("session_status", session.id, { type: "idle" })
@@ -806,31 +852,51 @@ export function createPromptSubmit(input: PromptSubmitInput) {
return true
}
- if (preparationAbort) activePreparation = { sessionID: session.id, controller: preparationAbort }
- const clearActivePreparation = () => {
- if (activePreparation?.controller !== preparationAbort) return
- activePreparation = undefined
+ const operation = {
+ id: ++submissionSequence,
+ sessionID: session.id,
+ controller,
+ preparing: preparesPromptDraft,
+ admissionStarted: false,
+ promise: Promise.resolve(),
}
-
- void sendFollowupDraft({
+ const ownsOperation = () => activeSubmission?.id === operation.id && !controller.signal.aborted
+ activeSubmission = operation
+ operation.promise = sendFollowupDraft({
client,
sync,
serverSync,
draft,
messageID,
+ intentID,
+ intentSource: preparesPromptDraft ? "intelligence" : "composer",
optimisticBusy: sessionDirectory === projectDirectory,
before: waitForWorktree,
- onBeforeSubmit: input.onSubmit,
- onPromptPrepareStart: input.onPromptPrepareStart,
- onPromptPrepareProgress: input.onPromptPrepareProgress,
- onPromptPrepareEnd: input.onPromptPrepareEnd,
- promptPrepareSignal: preparationAbort?.signal,
+ onBeforeSubmit: () => {
+ operation.admissionStarted = true
+ input.onSubmit?.()
+ },
+ onPromptPrepareStart: () => {
+ if (ownsOperation()) input.onPromptPrepareStart?.()
+ },
+ onPromptPrepareProgress: (preview) => {
+ if (ownsOperation()) input.onPromptPrepareProgress?.(preview)
+ },
+ onPromptPrepareEnd: () => {
+ if (ownsOperation()) input.onPromptPrepareEnd?.()
+ },
+ onPromptPrepareDiscard: () => {
+ if (ownsOperation()) input.onPromptPrepareDiscard?.()
+ },
+ promptPrepareSignal: controller.signal,
promptOutputLanguage: promptOutputLanguage(language.locale()),
confirmPromptDraft: input.confirmPromptDraft,
})
.then((sent) => {
- clearActivePreparation()
+ if (activeSubmission?.id !== operation.id) return
+ activeSubmission = undefined
pending.delete(pendingKey(session.id))
+ if (controller.signal.aborted) return
if (sent) {
if (preparesPromptDraft) {
clearContext()
@@ -846,8 +912,10 @@ export function createPromptSubmit(input: PromptSubmitInput) {
restoreInput()
})
.catch((err) => {
- clearActivePreparation()
+ if (activeSubmission?.id !== operation.id) return
+ activeSubmission = undefined
pending.delete(pendingKey(session.id))
+ if (controller.signal.aborted) return
if (sessionDirectory === projectDirectory) {
sync.set("session_status", session.id, { type: "idle" })
}
@@ -859,10 +927,12 @@ export function createPromptSubmit(input: PromptSubmitInput) {
if (!preparesPromptDraft) restoreCommentItems(commentItems)
restoreInput()
})
+ void operation.promise
}
return {
abort,
+ cancelPending,
handleSubmit,
}
}
diff --git a/packages/app/src/context/directory-sync.ts b/packages/app/src/context/directory-sync.ts
index 417e2f8b..d0994a93 100644
--- a/packages/app/src/context/directory-sync.ts
+++ b/packages/app/src/context/directory-sync.ts
@@ -370,6 +370,8 @@ export const createDirSyncContext = (
})
}
+ const loadPlan = (sessionID: string) => serverSync.plan.sync(directory, sessionID)
+
return {
get data() {
return current()[0]
@@ -434,6 +436,7 @@ export const createDirSyncContext = (
const key = keyFor(directory, sessionID)
touch(directory, setStore, sessionID)
+ const planReq = loadPlan(sessionID)
const seeded = getSessionPrefetch(serverSDK.scope, directory, sessionID)
if (seeded && store.message[sessionID] !== undefined && meta.limit[key] === undefined) {
@@ -463,7 +466,10 @@ export const createDirSyncContext = (
const hasSession = Binary.search(store.session, sessionID, (s) => s.id).found
const cachedMessages = store.message[sessionID]
const cached = cachedMessages !== undefined && meta.limit[key] !== undefined
- if (cached && hasSession && !opts?.force && cachedMessages.length > 0) return
+ if (cached && hasSession && !opts?.force && cachedMessages.length > 0) {
+ await planReq
+ return
+ }
const limit = meta.limit[key] ?? initialMessagePageSize
const sessionReq =
@@ -502,7 +508,7 @@ export const createDirSyncContext = (
limit,
})
- await Promise.all([sessionReq, messagesReq])
+ await Promise.all([sessionReq, messagesReq, planReq])
})
},
async diff(sessionID: string, opts?: { force?: boolean }) {
diff --git a/packages/app/src/context/global-sync/event-reducer.test.ts b/packages/app/src/context/global-sync/event-reducer.test.ts
index 160ace11..bbc88ca9 100644
--- a/packages/app/src/context/global-sync/event-reducer.test.ts
+++ b/packages/app/src/context/global-sync/event-reducer.test.ts
@@ -653,7 +653,9 @@ describe("plan.updated reconcile (session_plan)", () => {
properties: {
sessionID,
plan_id: "plan_1",
+ plan_version: 1,
goal: "ship it",
+ assumptions: ["CI"],
active_step_id: activeStepID,
steps: steps.map(([step_id, status]) => ({ step_id, title: step_id.toUpperCase(), status })),
done: steps.filter(([, status]) => status === "done").length,
@@ -693,6 +695,8 @@ describe("plan.updated reconcile (session_plan)", () => {
// First plan.updated: step "a" is active, the rest pending.
dispatch(setStore, store, setSessionPlan, planEvent("ses_1", [["a", "active"], ["b", "pending"], ["c", "pending"]], "a"))
expect(planStore.sp.ses_1.steps.map((s) => s.status)).toEqual(["active", "pending", "pending"])
+ expect(planStore.sp.ses_1.plan_version).toBe(1)
+ expect(planStore.sp.ses_1.assumptions).toEqual(["CI"])
// Second plan.updated: same plan_id, "a" done and "b" now active. This is the event the old
// code effectively dropped from the panel's point of view.
@@ -719,7 +723,9 @@ describe("plan.updated reconcile (session_plan)", () => {
test.skipIf(isServer)("keying by step_id preserves per-step identity across reorder", () => {
const mk = (rows: Array<[string, string]>): SessionPlan => ({
plan_id: "plan_1",
+ plan_version: 1,
goal: "g",
+ assumptions: [],
active_step_id: rows[0]?.[0] ?? null,
steps: rows.map(([step_id, status]) => ({ step_id, title: step_id.toUpperCase(), status })),
done: rows.filter(([, s]) => s === "done").length,
diff --git a/packages/app/src/context/global-sync/event-reducer.ts b/packages/app/src/context/global-sync/event-reducer.ts
index a41e9c2b..8ef6fec8 100644
--- a/packages/app/src/context/global-sync/event-reducer.ts
+++ b/packages/app/src/context/global-sync/event-reducer.ts
@@ -10,7 +10,7 @@ import type {
SessionStatus,
SnapshotFileDiff,
} from "@deepagent-code/sdk/v2/client"
-import type { State, VcsCache, SessionPlan, SessionGoal } from "./types"
+import type { State, VcsCache, SessionPlan, SessionGoal, SessionPlanUpdateOptions } from "./types"
import { trimSessions } from "./session-trim"
import { dropSessionCaches } from "./session-cache"
import { diffs as list, message as clean } from "@/utils/diffs"
@@ -84,7 +84,11 @@ export function applyDirectoryEvent(input: {
directory: string
loadLsp: () => void
vcsCache?: VcsCache
- setSessionPlan?: (sessionID: string, plan: SessionPlan | undefined) => void
+ setSessionPlan?: (
+ sessionID: string,
+ plan: SessionPlan | undefined,
+ options?: SessionPlanUpdateOptions,
+ ) => void
setSessionGoal?: (sessionID: string, goal: SessionGoal | undefined) => void
retainedLimit?: number
}) {
@@ -172,7 +176,9 @@ export function applyDirectoryEvent(input: {
const props = event.properties as {
sessionID: string
plan_id: string
+ plan_version: number
goal: string
+ assumptions: string[]
active_step_id: string | null
steps: SessionPlan["steps"]
done: number
@@ -180,12 +186,14 @@ export function applyDirectoryEvent(input: {
}
input.setSessionPlan?.(props.sessionID, {
plan_id: props.plan_id,
+ plan_version: props.plan_version,
goal: props.goal,
+ assumptions: props.assumptions,
active_step_id: props.active_step_id,
steps: props.steps,
done: props.done,
total: props.total,
- })
+ }, { source: "event" })
break
}
case "goal.updated": {
diff --git a/packages/app/src/context/global-sync/types.ts b/packages/app/src/context/global-sync/types.ts
index 0260548c..08760184 100644
--- a/packages/app/src/context/global-sync/types.ts
+++ b/packages/app/src/context/global-sync/types.ts
@@ -38,17 +38,54 @@ export type SessionPlanStep = {
status: string // pending | active | done | cancelled | blocked
acceptance?: string | null
assigned_agent?: string | null
+ evidence?: string[]
note?: string | null // U10: blocker explanation when status is "blocked"
}
export type SessionPlan = {
plan_id: string
+ plan_version: number
goal: string
+ assumptions: string[]
active_step_id: string | null
steps: SessionPlanStep[]
done: number
total: number
}
+export type SessionPlanUpdateSource = "event" | "snapshot"
+export type SessionPlanCursor = Pick | undefined
+
+export type SessionPlanUpdateOptions = {
+ source?: SessionPlanUpdateSource
+ snapshotBaseline?: SessionPlanCursor
+}
+
+export const sessionPlanCursor = (plan: SessionPlan | undefined): SessionPlanCursor =>
+ plan ? { plan_id: plan.plan_id, plan_version: plan.plan_version } : undefined
+
+export const hasSessionPlanIdentityConflict = (
+ current: SessionPlan | undefined,
+ incoming: SessionPlan | undefined,
+): boolean => !!current && !!incoming && current.plan_id !== incoming.plan_id
+
+const sameSessionPlanCursor = (left: SessionPlanCursor, right: SessionPlanCursor): boolean =>
+ left?.plan_id === right?.plan_id && left?.plan_version === right?.plan_version
+
+/** Cursor and identity gate shared by live events and reconnect snapshots. */
+export const acceptsSessionPlanUpdate = (
+ current: SessionPlan | undefined,
+ incoming: SessionPlan | undefined,
+ options: SessionPlanUpdateOptions = {},
+): boolean => {
+ const source = options.source ?? "event"
+ const snapshotCanRecalibrate =
+ source === "snapshot" && sameSessionPlanCursor(sessionPlanCursor(current), options.snapshotBaseline)
+ if (!incoming) return snapshotCanRecalibrate || current === undefined
+ if (!current) return true
+ if (current.plan_id !== incoming.plan_id) return snapshotCanRecalibrate
+ return incoming.plan_version >= current.plan_version
+}
+
// V3.9 §D: live Goal Loop status mirrored from the backend goal.updated event. Declared here (not in
// server-sync) so both the reducer and the sync context import it without a cycle. Mirrors the
// GoalManager snapshot + budget ledger the status bar renders.
diff --git a/packages/app/src/context/server-sync.test.ts b/packages/app/src/context/server-sync.test.ts
index 93e9c417..672172bc 100644
--- a/packages/app/src/context/server-sync.test.ts
+++ b/packages/app/src/context/server-sync.test.ts
@@ -1,6 +1,125 @@
import { describe, expect, test } from "bun:test"
import { canDisposeDirectory, pickDirectoriesToEvict } from "./global-sync/eviction"
import { estimateRootSessionTotal, loadRootSessionsWithFallback } from "./global-sync/session-load"
+import {
+ acceptsSessionPlanUpdate,
+ hasSessionPlanIdentityConflict,
+ sessionPlanCursor,
+ type SessionPlan,
+} from "./global-sync/types"
+import { syncRetainedSessionPlanSnapshots } from "./server-sync"
+
+const sessionPlan = (overrides: Partial = {}): SessionPlan => ({
+ plan_id: "plan-1",
+ plan_version: 3,
+ goal: "ship",
+ assumptions: [],
+ active_step_id: "a",
+ steps: [],
+ done: 0,
+ total: 0,
+ ...overrides,
+})
+
+describe("session plan cursor and identity admission", () => {
+ test("rejects a lower live version and a different live plan identity", () => {
+ const current = sessionPlan()
+ expect(acceptsSessionPlanUpdate(current, sessionPlan({ plan_version: 2 }), { source: "event" })).toBe(false)
+ expect(
+ acceptsSessionPlanUpdate(current, sessionPlan({ plan_id: "plan-2", plan_version: 1 }), { source: "event" }),
+ ).toBe(false)
+ })
+
+ test("allows a reconnect snapshot to calibrate a new plan identity", () => {
+ const current = sessionPlan()
+ const options = { source: "snapshot" as const, snapshotBaseline: sessionPlanCursor(current) }
+ expect(acceptsSessionPlanUpdate(current, sessionPlan({ plan_id: "plan-2", plan_version: 1 }), options)).toBe(true)
+ expect(acceptsSessionPlanUpdate(current, undefined, options)).toBe(true)
+ })
+
+ test("does not let an older same-identity snapshot roll back a live event", () => {
+ const baseline = sessionPlan({ plan_version: 3 })
+ const current = sessionPlan({ plan_version: 12 })
+ const options = { source: "snapshot" as const, snapshotBaseline: sessionPlanCursor(baseline) }
+ expect(acceptsSessionPlanUpdate(current, sessionPlan({ plan_version: 11 }), options)).toBe(false)
+ expect(acceptsSessionPlanUpdate(current, sessionPlan({ plan_version: 12 }), options)).toBe(true)
+ })
+
+ test("does not let a stale snapshot clear or replace a live cursor that changed after request start", () => {
+ const baseline = sessionPlan({ plan_version: 3 })
+ const current = sessionPlan({ plan_id: "plan-2", plan_version: 1 })
+ const options = { source: "snapshot" as const, snapshotBaseline: sessionPlanCursor(baseline) }
+ expect(acceptsSessionPlanUpdate(current, undefined, options)).toBe(false)
+ expect(acceptsSessionPlanUpdate(current, baseline, options)).toBe(false)
+ })
+
+ test("accepts the first live event and same-identity forward cursor", () => {
+ expect(acceptsSessionPlanUpdate(undefined, sessionPlan({ plan_version: 0 }), { source: "event" })).toBe(true)
+ expect(acceptsSessionPlanUpdate(sessionPlan(), sessionPlan({ plan_version: 4 }), { source: "event" })).toBe(true)
+ })
+})
+
+// Fix-C §7.7: A live event with a different plan_id is an identity conflict. The admission gate
+// must detect it so the caller (server-sync.tsx) can trigger a snapshot recalibration.
+describe("session plan identity conflict detection", () => {
+ test("detects identity conflict when live event has a different plan_id", () => {
+ const current = sessionPlan({ plan_id: "plan-1" })
+ const incoming = sessionPlan({ plan_id: "plan-2", plan_version: 1 })
+ expect(hasSessionPlanIdentityConflict(current, incoming)).toBe(true)
+ })
+
+ test("no conflict when plan_id is the same (even with a higher version)", () => {
+ const current = sessionPlan({ plan_id: "plan-1", plan_version: 3 })
+ const incoming = sessionPlan({ plan_id: "plan-1", plan_version: 4 })
+ expect(hasSessionPlanIdentityConflict(current, incoming)).toBe(false)
+ })
+
+ test("no conflict when current is undefined (first event)", () => {
+ expect(hasSessionPlanIdentityConflict(undefined, sessionPlan())).toBe(false)
+ })
+
+ test("no conflict when incoming is undefined", () => {
+ expect(hasSessionPlanIdentityConflict(sessionPlan(), undefined)).toBe(false)
+ })
+
+ // This test documents the recalibration contract: a different-identity live event is REJECTED
+ // by acceptsSessionPlanUpdate (snapshotCanRecalibrate is false for event source), but the
+ // caller (server-sync.tsx) must trigger recalibrateSessionPlan when hasSessionPlanIdentityConflict
+ // returns true. The snapshot recalibration is what authorises the identity transition.
+ test("different-identity live event is rejected by admission but triggers recalibration via conflict flag", () => {
+ const current = sessionPlan({ plan_id: "plan-1" })
+ const incoming = sessionPlan({ plan_id: "plan-2", plan_version: 1 })
+ // Admission rejects the different-identity live event (no snapshot baseline provided)
+ expect(acceptsSessionPlanUpdate(current, incoming, { source: "event" })).toBe(false)
+ // But the conflict flag is set so the caller knows to fetch a fresh snapshot
+ expect(hasSessionPlanIdentityConflict(current, incoming)).toBe(true)
+ })
+})
+
+describe("session plan reconnect snapshots", () => {
+ test("requests authority snapshots for retained sessions that already have plans", async () => {
+ const calls: Array<{ directory: string; sessionID: string }> = []
+
+ await syncRetainedSessionPlanSnapshots({
+ stores: {
+ "/workspace/a": { session: [{ id: "session-a" }, { id: "session-without-plan" }] },
+ "/workspace/b": { session: [{ id: "session-b" }] },
+ },
+ plans: {
+ "session-a": sessionPlan({ plan_id: "plan-a" }),
+ "session-b": sessionPlan({ plan_id: "plan-b" }),
+ },
+ sync: async (directory, sessionID) => {
+ calls.push({ directory, sessionID })
+ },
+ })
+
+ expect(calls).toEqual([
+ { directory: "/workspace/a", sessionID: "session-a" },
+ { directory: "/workspace/b", sessionID: "session-b" },
+ ])
+ })
+})
describe("pickDirectoriesToEvict", () => {
test("keeps pinned stores and evicts idle stores", () => {
diff --git a/packages/app/src/context/server-sync.tsx b/packages/app/src/context/server-sync.tsx
index dfd38d15..59952d9e 100644
--- a/packages/app/src/context/server-sync.tsx
+++ b/packages/app/src/context/server-sync.tsx
@@ -46,10 +46,32 @@ import type { ServerScope } from "@/utils/server-scope"
import { persisted } from "@/utils/persist"
import { isFilesystemRootDir } from "@/utils/filesystem-root"
import { toggleMcp } from "./global-sync/mcp"
-import type { SessionPlan, SessionPlanStep, SessionGoal } from "./global-sync/types"
+import {
+ acceptsSessionPlanUpdate,
+ hasSessionPlanIdentityConflict,
+ sessionPlanCursor,
+ type SessionPlan,
+ type SessionPlanStep,
+ type SessionGoal,
+ type SessionPlanUpdateOptions,
+} from "./global-sync/types"
export type { SessionPlan, SessionPlanStep, SessionGoal }
+export async function syncRetainedSessionPlanSnapshots(input: {
+ stores: Readonly>
+ plans: Readonly>
+ sync: (directory: string, sessionID: string) => Promise
+}) {
+ await Promise.all(
+ Object.entries(input.stores).flatMap(([directory, store]) =>
+ store.session
+ .filter((session) => input.plans[session.id] !== undefined)
+ .map((session) => input.sync(directory, session.id)),
+ ),
+ )
+}
+
const PROVIDER_MODEL_REFRESH_INTERVAL_MS = 24 * 60 * 60 * 1000
type GlobalStore = {
@@ -115,6 +137,8 @@ export function createServerSyncContextInner(_serverSDK?: ServerSDK) {
const sdkCache = new Map()
const booting = new Map>()
const sessionLoads = new Map>()
+ const planLoads = new Map>()
+ const planReloads = new Set()
const sessionMeta = new Map()
const sdkFor = (directory: string) => {
@@ -244,9 +268,16 @@ export function createServerSyncContextInner(_serverSDK?: ServerSDK) {
}) as typeof setGlobalStore
// Set/clear the live plan for a session.
- const setSessionPlan = (sessionID: string, plan: SessionPlan | undefined) => {
+ const setSessionPlan = (sessionID: string, plan: SessionPlan | undefined, options: SessionPlanUpdateOptions = {}) => {
if (!sessionID) return
+ const source = options.source ?? "event"
+ const current = globalStore.session_plan[sessionID]
+ if (!acceptsSessionPlanUpdate(current, plan, options)) return
if (!plan) {
+ // A reconnect snapshot is authoritative, but an event-only clear must not erase a newer
+ // snapshot/event that arrived out of order. The backend does not emit plan deletion events,
+ // so only an explicit snapshot may clear an existing cache.
+ if (source !== "snapshot" && current) return
setGlobalStore(
"session_plan",
produce((draft) => {
@@ -283,6 +314,69 @@ export function createServerSyncContextInner(_serverSDK?: ServerSDK) {
setGlobalStore("session_goal", sessionID, reconcile(goal))
}
+ const syncSessionPlan = (directory: string, sessionID: string): Promise => {
+ const key = `${directoryKey(directory)}\n${sessionID}`
+ const pending = planLoads.get(key)
+ if (pending) return pending
+
+ const snapshotBaseline = sessionPlanCursor(globalStore.session_plan[sessionID])
+ const promise = retry(() => sdkFor(directory).session.plan({ sessionID }))
+ .then((response) => {
+ if (!children.children[directoryKey(directory)]) return
+ const snapshot = response.data
+ if (!snapshot?.plan) {
+ setSessionPlan(sessionID, undefined, { source: "snapshot", snapshotBaseline })
+ return
+ }
+ if (typeof snapshot.plan_version !== "number") {
+ throw new Error(`plan snapshot is missing its authority version for ${sessionID}`)
+ }
+ const plan = snapshot.plan
+ setSessionPlan(
+ sessionID,
+ {
+ plan_id: plan.plan_id,
+ plan_version: snapshot.plan_version,
+ goal: plan.goal,
+ assumptions: [...plan.assumptions],
+ active_step_id: plan.active_step_id,
+ steps: plan.steps.map((step) => ({
+ step_id: step.step_id,
+ title: step.title,
+ status: step.status,
+ acceptance: step.acceptance,
+ assigned_agent: step.assigned_agent,
+ evidence: step.evidence,
+ note: step.note,
+ })),
+ done: plan.steps.filter((step) => step.status === "done").length,
+ total: plan.steps.length,
+ },
+ { source: "snapshot", snapshotBaseline },
+ )
+ })
+ .finally(() => {
+ planLoads.delete(key)
+ if (!planReloads.delete(key)) return
+ void syncSessionPlan(directory, sessionID).catch((error) => {
+ console.error("Failed to reload session plan after an identity race", error)
+ })
+ })
+ planLoads.set(key, promise)
+ return promise
+ }
+
+ const recalibrateSessionPlan = (directory: string, sessionID: string) => {
+ const key = `${directoryKey(directory)}\n${sessionID}`
+ if (planLoads.has(key)) {
+ planReloads.add(key)
+ return
+ }
+ void syncSessionPlan(directory, sessionID).catch((error) => {
+ console.error("Failed to recalibrate session plan after an identity conflict", error)
+ })
+ }
+
const paused = () => untrack(() => globalStore.reload) !== undefined
const queue = createRefreshQueue({
@@ -445,6 +539,11 @@ export function createServerSyncContextInner(_serverSDK?: ServerSDK) {
translate: language.t,
queryClient,
})
+ await syncRetainedSessionPlanSnapshots({
+ stores: { [key]: child[0] },
+ plans: globalStore.session_plan,
+ sync: syncSessionPlan,
+ })
})
booting.set(key, promise)
@@ -490,7 +589,13 @@ export function createServerSyncContextInner(_serverSDK?: ServerSDK) {
store,
setStore,
push: queue.push,
- setSessionPlan,
+ setSessionPlan: (sessionID, plan, options) => {
+ const conflict = hasSessionPlanIdentityConflict(globalStore.session_plan[sessionID], plan)
+ setSessionPlan(sessionID, plan, options)
+ if (conflict && (options?.source ?? "event") === "event") {
+ recalibrateSessionPlan(directory, sessionID)
+ }
+ },
setSessionGoal,
retainedLimit: sessionMeta.get(key)?.limit,
vcsCache: children.vcsCache.get(key),
@@ -644,6 +749,7 @@ export function createServerSyncContextInner(_serverSDK?: ServerSDK) {
project: projectApi,
plan: {
set: setSessionPlan,
+ sync: syncSessionPlan,
},
goal: {
set: setSessionGoal,
diff --git a/packages/app/src/i18n/en.ts b/packages/app/src/i18n/en.ts
index 43bc114d..0bfd2260 100644
--- a/packages/app/src/i18n/en.ts
+++ b/packages/app/src/i18n/en.ts
@@ -389,8 +389,11 @@ export const dict = {
"composer.goal.editPlan.addStep": "Add step",
"composer.goal.editPlan.removeStep": "Remove step",
"composer.goal.editPlan.stepPlaceholder": "Step description",
+ "composer.goal.editPlan.blockedNotePlaceholder": "Why this step is blocked",
"composer.goal.editPlan.save": "Apply changes",
+ "composer.goal.editPlan.confirm": "Confirm replacement",
"composer.goal.editPlan.cancel": "Cancel",
+ "composer.goal.editPlan.challenge": "This revision removes substantial plan detail. Confirm that the current plan should be replaced.",
"composer.goal.editPlan.saved": "Plan updated — takes effect next tick",
"composer.goal.editPlan.failed": "Couldn't update the plan (goal not running?)",
"composer.goal.editPlan.status.pending": "Pending",
diff --git a/packages/app/src/i18n/zh.ts b/packages/app/src/i18n/zh.ts
index cc86fe00..6c01349b 100644
--- a/packages/app/src/i18n/zh.ts
+++ b/packages/app/src/i18n/zh.ts
@@ -397,8 +397,11 @@ export const dict = {
"composer.goal.editPlan.addStep": "添加步骤",
"composer.goal.editPlan.removeStep": "删除步骤",
"composer.goal.editPlan.stepPlaceholder": "步骤描述",
+ "composer.goal.editPlan.blockedNotePlaceholder": "说明该步骤受阻的原因",
"composer.goal.editPlan.save": "应用更改",
+ "composer.goal.editPlan.confirm": "确认替换",
"composer.goal.editPlan.cancel": "取消",
+ "composer.goal.editPlan.challenge": "这次修改移除了大量计划细节。请确认要替换当前计划。",
"composer.goal.editPlan.saved": "计划已更新——下一个 tick 生效",
"composer.goal.editPlan.failed": "无法更新计划（目标未在运行？）",
"composer.goal.editPlan.status.pending": "待处理",
diff --git a/packages/app/src/i18n/zht.ts b/packages/app/src/i18n/zht.ts
index 83ba1dd0..745deeb7 100644
--- a/packages/app/src/i18n/zht.ts
+++ b/packages/app/src/i18n/zht.ts
@@ -337,8 +337,11 @@ export const dict = {
"composer.goal.editPlan.addStep": "新增步驟",
"composer.goal.editPlan.removeStep": "刪除步驟",
"composer.goal.editPlan.stepPlaceholder": "步驟描述",
+ "composer.goal.editPlan.blockedNotePlaceholder": "說明該步驟受阻的原因",
"composer.goal.editPlan.save": "套用變更",
+ "composer.goal.editPlan.confirm": "確認替換",
"composer.goal.editPlan.cancel": "取消",
+ "composer.goal.editPlan.challenge": "這次修改移除了大量計劃細節。請確認要替換目前計劃。",
"composer.goal.editPlan.saved": "計劃已更新——下一個 tick 生效",
"composer.goal.editPlan.failed": "無法更新計劃（目標未在執行？）",
"composer.goal.editPlan.status.pending": "待處理",
diff --git a/packages/app/src/pages/session.tsx b/packages/app/src/pages/session.tsx
index c01b51eb..72b4804c 100644
--- a/packages/app/src/pages/session.tsx
+++ b/packages/app/src/pages/session.tsx
@@ -45,6 +45,7 @@ import { useSettings } from "@/context/settings"
import { useSync } from "@/context/sync"
import { useTerminalHosts } from "@/context/terminal"
import { DialogDeepAgentPromptConfirm } from "@/components/dialog-deepagent-prompt-confirm"
+import type { PromptInputControl } from "@/components/prompt-input"
import {
type DeepAgentPromptPrepareResult,
type FollowupDraft,
@@ -52,6 +53,7 @@ import {
sendFollowupDraft,
} from "@/components/prompt-input/submit"
import { createSessionComposerState, SessionComposerRegion } from "@/pages/session/composer"
+import { createFollowupSubmissionRegistry } from "@/pages/session/followup-submission"
import {
createForkAction,
createOpenReviewFile,
@@ -654,6 +656,7 @@ export default function Page() {
}
let inputRef!: HTMLDivElement
+ let promptInputControl: PromptInputControl | undefined
let promptDock: HTMLDivElement | undefined
let dockHeight = 0
let scroller: HTMLDivElement | undefined
@@ -708,9 +711,9 @@ export default function Page() {
},
)
- // NOTE: the per-turn todo prefetch effect was removed when task tracking unified onto the plan
- // system. The task dock is now driven exclusively by the persistent plan (session_plan), which
- // arrives via the plan.updated SSE stream — there is no REST todo endpoint to prime on activation.
+ // Plan state is restored by session sync from the authoritative snapshot endpoint, then advanced
+ // by advisory plan.updated events. The event stream remains live-only; snapshot fetch is what makes
+ // reload, reconnect, and a missed event recoverable.
createEffect(
on(
@@ -1443,6 +1446,8 @@ export default function Page() {
return followup.edit[id]
})
+ const followupSubmissions = createFollowupSubmissionRegistry()
+
const followupMutation = useMutation(() => ({
mutationFn: async (input: { sessionID: string; id: string }) => {
const item = (followup.items[input.sessionID] ?? []).find((entry) => entry.id === input.id)
@@ -1450,18 +1455,28 @@ export default function Page() {
setFollowup("failed", input.sessionID, undefined)
- const ok = await sendFollowupDraft({
+ const controller = new AbortController()
+ const promise = sendFollowupDraft({
client: sdk.client,
sync,
serverSync,
draft: item,
+ intentID: item.id,
+ intentSource: "followup",
optimisticBusy: item.sessionDirectory === sdk.directory,
confirmPromptDraft,
- }).catch((err) => {
- setFollowup("failed", input.sessionID, input.id)
- fail(err)
- return false
+ promptPrepareSignal: controller.signal,
})
+ followupSubmissions.register({ ...input, controller, promise })
+ const ok = await promise
+ .catch((err) => {
+ setFollowup("failed", input.sessionID, input.id)
+ fail(err)
+ return false
+ })
+ .finally(() => {
+ followupSubmissions.clear(input.sessionID, input.id)
+ })
if (!ok) return
setFollowup("items", input.sessionID, (items) => (items ?? []).filter((entry) => entry.id !== input.id))
@@ -1505,6 +1520,7 @@ export default function Page() {
}
const queueFollowup = (draft: FollowupDraft) => {
+ if (reverting()) return
setFollowup("items", draft.sessionID, (items) => [
...(items ?? []),
{ id: Identifier.ascending("message"), ...draft },
@@ -1516,6 +1532,7 @@ export default function Page() {
const followupDock = createMemo(() => queuedFollowups().map((item) => ({ id: item.id, text: followupText(item) })))
const sendFollowup = (sessionID: string, id: string) => {
+ if (reverting()) return Promise.resolve()
if (sync.session.get(sessionID)?.parentID) return Promise.resolve()
const item = (followup.items[sessionID] ?? []).find((entry) => entry.id === id)
if (!item) return Promise.resolve()
@@ -1527,7 +1544,7 @@ export default function Page() {
const editFollowup = (id: string) => {
const sessionID = params.id
if (!sessionID) return
- if (followupBusy(sessionID)) return
+ if (reverting() || followupBusy(sessionID)) return
const item = queuedFollowups().find((entry) => entry.id === id)
if (!item) return
@@ -1544,7 +1561,7 @@ export default function Page() {
const deleteFollowup = (id: string) => {
const sessionID = params.id
if (!sessionID) return
- if (followupBusy(sessionID)) return
+ if (reverting() || followupBusy(sessionID)) return
setFollowup("items", sessionID, (items) => (items ?? []).filter((entry) => entry.id !== id))
setFollowup("failed", sessionID, (value) => (value === id ? undefined : value))
@@ -1559,27 +1576,25 @@ export default function Page() {
const halt = (sessionID: string) =>
busy(sessionID) ? sdk.client.session.abort({ sessionID }).catch(() => {}) : Promise.resolve()
+ const cancelFollowup = async (sessionID: string) => {
+ await followupSubmissions.cancel(sessionID)
+ }
+
const revertMutation = useMutation(() => ({
mutationFn: async (input: { sessionID: string; messageID: string }) => {
- const prev = prompt.current().slice()
- const last = info()?.revert
const value = draft(input.messageID)
- batch(() => {
- roll(input.sessionID, { messageID: input.messageID })
- prompt.set(value)
- })
- await halt(input.sessionID)
+ await cancelFollowup(input.sessionID)
+ .then(() => promptInputControl?.cancelPending() ?? Promise.resolve())
+ .then(() => halt(input.sessionID))
.then(() => sdk.client.session.revert(input))
.then((result) => {
- if (result.data) merge(result.data)
- })
- .catch((err) => {
batch(() => {
- roll(input.sessionID, last)
- prompt.set(prev)
+ roll(input.sessionID, { messageID: input.messageID })
+ prompt.set(value)
+ if (result.data) merge(result.data)
})
- fail(err)
})
+ .catch(fail)
},
}))
@@ -1589,38 +1604,28 @@ export default function Page() {
if (!sessionID) return
const next = userMessages().find((item) => item.id > id)
- const prev = prompt.current().slice()
- const last = info()?.revert
-
- batch(() => {
- roll(sessionID, next ? { messageID: next.id } : undefined)
- if (next) {
- prompt.set(draft(next.id))
- return
- }
- prompt.reset()
- })
- const task = !next
- ? halt(sessionID).then(() => sdk.client.session.unrevert({ sessionID }))
- : halt(sessionID).then(() =>
- sdk.client.session.revert({
+ const request = () =>
+ !next
+ ? sdk.client.session.unrevert({ sessionID })
+ : sdk.client.session.revert({
sessionID,
messageID: next.id,
- }),
- )
+ })
- await task
+ await cancelFollowup(sessionID)
+ .then(() => promptInputControl?.cancelPending() ?? Promise.resolve())
+ .then(() => halt(sessionID))
+ .then(request)
.then((result) => {
- if (result.data) merge(result.data)
- })
- .catch((err) => {
batch(() => {
- roll(sessionID, last)
- prompt.set(prev)
+ roll(sessionID, next ? { messageID: next.id } : undefined)
+ if (next) prompt.set(draft(next.id))
+ else prompt.reset()
+ if (result.data) merge(result.data)
})
- fail(err)
})
+ .catch(fail)
},
}))
@@ -1752,12 +1757,17 @@ export default function Page() {
resumeScroll()
}}
onResponseSubmit={resumeScroll}
+ inputDisabled={reverting()}
+ inputControlRef={(control) => {
+ promptInputControl = control
+ }}
followup={
params.id && !isChildSession()
? {
queue: queueEnabled,
items: followupDock(),
sending: sendingFollowup(),
+ disabled: reverting(),
edit: editingFollowup(),
onQueue: queueFollowup,
onAbort: () => {
diff --git a/packages/app/src/pages/session/composer/session-composer-region.tsx b/packages/app/src/pages/session/composer/session-composer-region.tsx
index 5083db31..65e13f52 100644
--- a/packages/app/src/pages/session/composer/session-composer-region.tsx
+++ b/packages/app/src/pages/session/composer/session-composer-region.tsx
@@ -4,7 +4,7 @@ import { useNavigate } from "@solidjs/router"
import { useSpring } from "@deepagent-code/ui/motion-spring"
import { Icon } from "@deepagent-code/ui/icon"
import { useLayout } from "@/context/layout"
-import { PromptInput } from "@/components/prompt-input"
+import { PromptInput, type PromptInputControl } from "@/components/prompt-input"
import { useLanguage } from "@/context/language"
import { usePrompt } from "@/context/prompt"
import { useSync } from "@/context/sync"
@@ -31,10 +31,13 @@ export function SessionComposerRegion(props: {
onNewSessionWorktreeReset: () => void
onSubmit: () => void
onResponseSubmit: () => void
+ inputDisabled?: boolean
+ inputControlRef?: (control: PromptInputControl | undefined) => void
followup?: {
queue: () => boolean
items: { id: string; text: string }[]
sending?: string
+ disabled?: boolean
edit?: { id: string; prompt: FollowupDraft["prompt"]; context: FollowupDraft["context"] }
onQueue: (draft: FollowupDraft) => void
onAbort: () => void
@@ -278,6 +281,7 @@ export function SessionComposerRegion(props: {
((done) => {
+ resolve = done
+ })
+ return { promise, resolve }
+}
+
+describe("follow-up submission registry", () => {
+ test("cancel aborts and joins only the targeted session", async () => {
+ const registry = createFollowupSubmissionRegistry()
+ const first = deferred()
+ const second = deferred()
+ const firstController = new AbortController()
+ const secondController = new AbortController()
+ registry.register({ sessionID: "session-a", id: "a", controller: firstController, promise: first.promise })
+ registry.register({ sessionID: "session-b", id: "b", controller: secondController, promise: second.promise })
+
+ let joined = false
+ const cancel = registry.cancel("session-a").then(() => {
+ joined = true
+ })
+ await Promise.resolve()
+ expect(firstController.signal.aborted).toBe(true)
+ expect(secondController.signal.aborted).toBe(false)
+ expect(joined).toBe(false)
+ first.resolve(false)
+ await cancel
+ expect(joined).toBe(true)
+ second.resolve(true)
+ })
+
+ test("an old completion cannot clear a replacement submission", async () => {
+ const registry = createFollowupSubmissionRegistry()
+ const current = deferred()
+ const controller = new AbortController()
+ registry.register({
+ sessionID: "session-a",
+ id: "replacement",
+ controller,
+ promise: current.promise,
+ })
+ registry.clear("session-a", "old")
+
+ const cancel = registry.cancel("session-a")
+ expect(controller.signal.aborted).toBe(true)
+ current.resolve(false)
+ await cancel
+ })
+})
diff --git a/packages/app/src/pages/session/followup-submission.ts b/packages/app/src/pages/session/followup-submission.ts
new file mode 100644
index 00000000..6615ecb7
--- /dev/null
+++ b/packages/app/src/pages/session/followup-submission.ts
@@ -0,0 +1,39 @@
+export type FollowupSubmission = {
+ readonly sessionID: string
+ readonly id: string
+ readonly controller: AbortController
+ readonly promise: Promise
+}
+
+export function createFollowupSubmissionRegistry() {
+ // Keyed by sessionID → Map so multiple concurrent followups per session
+ // are all tracked and cancelled on revert (fixes single-entry overwrite gap).
+ const submissions = new Map>>()
+
+ return {
+ register(input: FollowupSubmission) {
+ let slot = submissions.get(input.sessionID)
+ if (!slot) {
+ slot = new Map()
+ submissions.set(input.sessionID, slot)
+ }
+ slot.set(input.id, {
+ id: input.id,
+ controller: input.controller,
+ promise: input.promise,
+ })
+ },
+ clear(sessionID: string, id: string) {
+ const slot = submissions.get(sessionID)
+ if (!slot) return
+ slot.delete(id)
+ if (slot.size === 0) submissions.delete(sessionID)
+ },
+ async cancel(sessionID: string) {
+ const slot = submissions.get(sessionID)
+ if (!slot) return
+ for (const sub of slot.values()) sub.controller.abort()
+ await Promise.all([...slot.values()].map((sub) => sub.promise.catch(() => false)))
+ },
+ }
+}
diff --git a/packages/core/package.json b/packages/core/package.json
index 0e4b80a4..c91b2975 100644
--- a/packages/core/package.json
+++ b/packages/core/package.json
@@ -1,6 +1,6 @@
{
"$schema": "https://json.schemastore.org/package.json",
- "version": "4.0.5",
+ "version": "4.0.6",
"name": "@deepagent-code/core",
"type": "module",
"license": "AGPL-3.0-or-later",
diff --git a/packages/core/script/live-llm/runtime.ts b/packages/core/script/live-llm/runtime.ts
index a575d92e..6457f985 100644
--- a/packages/core/script/live-llm/runtime.ts
+++ b/packages/core/script/live-llm/runtime.ts
@@ -80,7 +80,11 @@ export async function runV2LiveCases(input: {
const events = EventV2.defaultLayer
const store = SessionStore.defaultLayer
const locations = LocationServiceMap.layer
- const execution = sessionExecutionLocal.layer.pipe(Layer.provide(store), Layer.provide(locations))
+ const execution = sessionExecutionLocal.layer.pipe(
+ Layer.provide(store),
+ Layer.provide(events),
+ Layer.provide(locations),
+ )
const sessions = SessionV2.layer.pipe(
Layer.provide(events),
Layer.provide(database),
diff --git a/packages/core/script/live-llm/v2-provider-loop.ts b/packages/core/script/live-llm/v2-provider-loop.ts
index 62af66df..eed3dbb7 100644
--- a/packages/core/script/live-llm/v2-provider-loop.ts
+++ b/packages/core/script/live-llm/v2-provider-loop.ts
@@ -139,7 +139,11 @@ const markerTool = Layer.effectDiscard(
).pipe(Layer.provide(applicationTools))
const locations = LocationServiceMap.layer
-const execution = sessionExecutionLocal.layer.pipe(Layer.provide(store), Layer.provide(locations))
+const execution = sessionExecutionLocal.layer.pipe(
+ Layer.provide(store),
+ Layer.provide(events),
+ Layer.provide(locations),
+)
const sessions = SessionV2.layer.pipe(
Layer.provide(events),
Layer.provide(database),
diff --git a/packages/core/src/agent-gateway.ts b/packages/core/src/agent-gateway.ts
index 9bc5c791..f7266ec5 100644
--- a/packages/core/src/agent-gateway.ts
+++ b/packages/core/src/agent-gateway.ts
@@ -407,6 +407,7 @@ const isManagedDeepAgentRuntimeWith = (config: CurrentConfig) =>
import {
buildSystemPrompt,
+ buildVolatileContinuationContext,
buildVolatileRoundContext,
type KnowledgeRefProjection,
type PromptContext,
@@ -488,6 +489,9 @@ export const systemPrompt = (_providerID: string, context?: PromptContext) =>
export const volatileRoundContext = (context: PromptContext): string =>
isActiveDeepAgentRuntime() ? buildVolatileRoundContext(context) : ""
+export const volatileContinuationContext = (): string =>
+ isActiveDeepAgentRuntime() ? buildVolatileContinuationContext() : ""
+
export const preflight = (input: RunInput): Effect.Effect => preflightWith(input, current)
const preflightWith = (input: RunInput, config: CurrentConfig): Effect.Effect =>
diff --git a/packages/core/src/context-federation/rollout.ts b/packages/core/src/context-federation/rollout.ts
index 339e1cb4..f418e9c1 100644
--- a/packages/core/src/context-federation/rollout.ts
+++ b/packages/core/src/context-federation/rollout.ts
@@ -10,6 +10,38 @@ export type Requested = {
readonly coreV2ExecutionOwner: boolean
}
+// BUG-008: derived readiness snapshot — always derived from existing identity/index/adapter/storage
+// authorities; never writable independently. Consumers call readinessFromAuthorities() to build it.
+export type ReadinessState = "uninitialized" | "building" | "ready" | "degraded" | "blocked"
+
+export type DerivedContextDataReadiness = {
+ /** Overall data-plane state for the owning security namespace / project / location. */
+ readonly state: ReadinessState
+ /** True when a canonical Project/Location identity row has been registered. */
+ readonly identityBound: boolean
+ /** True when at least one index incarnation is available for the location. */
+ readonly indexAvailable: boolean
+ /** True when durable selection/artifact/attempt storage probe succeeded. */
+ readonly storageHealthy: boolean
+ /** Unix ms when this snapshot was derived. */
+ readonly observedAt: number
+ /** Unix ms after which this snapshot must be re-derived. */
+ readonly expiresAt: number
+}
+
+/**
+ * Minimal safe readiness snapshot — all capabilities available, no TTL.
+ * Use only in tests; production code must derive from real authorities.
+ */
+export const READINESS_READY_STUB: DerivedContextDataReadiness = {
+ state: "ready",
+ identityBound: true,
+ indexAvailable: true,
+ storageHealthy: true,
+ observedAt: 0,
+ expiresAt: Number.MAX_SAFE_INTEGER,
+}
+
export type Evidence = {
readonly coreV2ParityVerified: boolean
}
@@ -22,6 +54,9 @@ export type BlockReason =
| "core_v2_parity_required"
| "project_rollout_not_selected"
| "context_federation_kill_switch"
+ | "data_readiness_identity_missing"
+ | "data_readiness_expired"
+ | "data_readiness_blocked"
export type Decision = {
readonly requested: Requested
@@ -97,6 +132,73 @@ export function resolve(requested: Requested, evidence: Evidence): Decision {
}
}
+/**
+ * BUG-008: combine eligibility + readiness into a final activation decision.
+ *
+ * Eligibility (flags, cohort, kill-switch) is the existing `resolve()` result.
+ * Readiness is derived from real identity/index/adapter/storage authorities.
+ *
+ * Safety policy (§6.4):
+ * - expired, identity-missing, or blocked readiness → model-facing owners fail closed
+ * - degraded readiness → shadow continues (logs degraded), projection/tools blocked
+ * - ready → use the eligibility decision unchanged
+ *
+ * NOTE: core V2 execution owner has its own independent parity gate and is never
+ * activated by readiness alone — it must also pass `evidence.coreV2ParityVerified`.
+ */
+export function activate(eligibility: Decision, readiness: DerivedContextDataReadiness): Decision {
+ const now = Date.now()
+ const expired = now > readiness.expiresAt
+ const identityMissing = !readiness.identityBound
+
+ // Hard safety gates: fail closed for model-facing owners.
+ if (expired || identityMissing || readiness.state === "blocked") {
+ const reasons: BlockReason[] = expired
+ ? ["data_readiness_expired"]
+ : identityMissing
+ ? ["data_readiness_identity_missing"]
+ : ["data_readiness_blocked"]
+ const modelFacingOwners = ["contextProjectionV2", "contextQueryToolsV2", "coreV2ExecutionOwner"] as const
+ return {
+ ...eligibility,
+ enabled: {
+ ...eligibility.enabled,
+ contextProjectionV2: false,
+ contextQueryToolsV2: false,
+ coreV2ExecutionOwner: false,
+ },
+ blocked: modelFacingOwners.reduce(
+ (acc, stage) =>
+ eligibility.enabled[stage] ? { ...acc, [stage]: [...(eligibility.blocked[stage] ?? []), ...reasons] } : acc,
+ eligibility.blocked,
+ ),
+ }
+ }
+
+ // Degraded readiness: shadow can continue (availability/timeout), projection/tools blocked.
+ if (readiness.state === "degraded" || !readiness.indexAvailable || !readiness.storageHealthy) {
+ return {
+ ...eligibility,
+ enabled: {
+ ...eligibility.enabled,
+ contextProjectionV2: false,
+ contextQueryToolsV2: false,
+ // coreV2ExecutionOwner governed by its own parity gate — leave unchanged
+ },
+ blocked: (["contextProjectionV2", "contextQueryToolsV2"] as const).reduce(
+ (acc, stage) =>
+ eligibility.enabled[stage]
+ ? { ...acc, [stage]: [...(eligibility.blocked[stage] ?? []), "data_readiness_blocked"] }
+ : acc,
+ eligibility.blocked,
+ ),
+ }
+ }
+
+ // Ready: use eligibility as-is.
+ return eligibility
+}
+
export function projectBucket(projectScopeKey: string): number {
return Number.parseInt(Hash.sha256(`context-federation-rollout/v1:${projectScopeKey}`).slice(0, 8), 16) % 100
}
@@ -104,19 +206,17 @@ export function projectBucket(projectScopeKey: string): number {
export function resolveProject(decision: Decision, projectScopeKey: string, policy: ProjectPolicy): ProjectDecision {
const percentage = Number.isFinite(policy.percentage) ? Math.max(0, Math.min(100, policy.percentage)) : 0
const bucket = projectBucket(projectScopeKey)
- const selected = policy.stage === "all" ||
+ const selected =
+ policy.stage === "all" ||
(policy.stage === "internal" && policy.internalProjectScopeKeys.includes(projectScopeKey)) ||
(policy.stage === "percentage" &&
(policy.internalProjectScopeKeys.includes(projectScopeKey) || bucket < percentage))
const disableModelOwners = policy.killSwitch || !selected
- const reason: BlockReason = policy.killSwitch
- ? "context_federation_kill_switch"
- : "project_rollout_not_selected"
+ const reason: BlockReason = policy.killSwitch ? "context_federation_kill_switch" : "project_rollout_not_selected"
const blocked = disableModelOwners
? (["contextProjectionV2", "contextQueryToolsV2", "coreV2ExecutionOwner"] as const).reduce(
- (result, stage) => decision.enabled[stage]
- ? { ...result, [stage]: [...(decision.blocked[stage] ?? []), reason] }
- : result,
+ (result, stage) =>
+ decision.enabled[stage] ? { ...result, [stage]: [...(decision.blocked[stage] ?? []), reason] } : result,
decision.blocked,
)
: decision.blocked
diff --git a/packages/core/src/database/migration.gen.ts b/packages/core/src/database/migration.gen.ts
index 45784f83..1ba6a640 100644
--- a/packages/core/src/database/migration.gen.ts
+++ b/packages/core/src/database/migration.gen.ts
@@ -60,5 +60,14 @@ export const migrations = (
import("./migration/20260726073000_context_links"),
import("./migration/20260726080000_location_change_journal"),
import("./migration/20260731000000_agent_execution"),
+ import("./migration/20260803000000_time_suspended"),
+ import("./migration/20260803000001_subagent_control_plane_l1"),
+ import("./migration/20260805000000_repair_task_admission"),
+ import("./migration/20260806051000_session_prompt_intent"),
+ import("./migration/20260806060000_session_mutation_epoch"),
+ import("./migration/20260806070000_compaction_lifecycle"),
+ import("./migration/20260806080000_session_tool_request_receipt"),
+ import("./migration/20260807090000_session_tool_argument_receipt"),
+ import("./migration/20260807123000_session_tool_argument_validation_outcome"),
])
).map((module) => module.default) satisfies DatabaseMigration.Migration[]
diff --git a/packages/core/src/database/migration/20260803000000_time_suspended.ts b/packages/core/src/database/migration/20260803000000_time_suspended.ts
new file mode 100644
index 00000000..f2c8e83a
--- /dev/null
+++ b/packages/core/src/database/migration/20260803000000_time_suspended.ts
@@ -0,0 +1,13 @@
+import { Effect } from "effect"
+import type { DatabaseMigration } from "../migration"
+
+export default {
+ id: "20260803000000_time_suspended",
+ up: (tx) =>
+ Effect.gen(function* () {
+ yield* tx.run(`ALTER TABLE \`session\` ADD \`time_suspended\` integer;`)
+ yield* tx.run(
+ `CREATE INDEX \`session_time_suspended_idx\` ON \`session\` (\`time_suspended\`) WHERE "session"."time_suspended" is not null;`,
+ )
+ }),
+} satisfies DatabaseMigration.Migration
diff --git a/packages/core/src/database/migration/20260803000001_subagent_control_plane_l1.ts b/packages/core/src/database/migration/20260803000001_subagent_control_plane_l1.ts
new file mode 100644
index 00000000..c3b6e6fb
--- /dev/null
+++ b/packages/core/src/database/migration/20260803000001_subagent_control_plane_l1.ts
@@ -0,0 +1,381 @@
+/**
+ * L1 Migration: Subagent Control Plane Schema
+ *
+ * Design: subagent-control-plane-design.zh-CN.md §13.1
+ *
+ * Strategy: shadow table rebuild for task_run, task_notification_outbox, and task_admission.
+ *
+ * The previous migration (20260724134000_task_run_delivery) used strict CHECK constraints
+ * that only allow legacy state/phase/status values. Since ALTER TABLE ADD COLUMN cannot
+ * modify existing CHECK constraints in SQLite, a shadow table approach is required:
+ * 1. Create *_new tables with all columns (existing + new) and correct CHECKs
+ * 2. Backfill: copy rows with vocabulary renames (error→failed, researching→running, etc.)
+ * 3. Validate: check no constraint violations before committing
+ * 4. Drop old table + rename new table
+ * 5. Recreate indexes and FK-dependent structures
+ *
+ * IMPORTANT: This migration must run in a single SQLite transaction to ensure the rename
+ * is atomic. If any step fails the entire migration rolls back leaving the old schema intact.
+ *
+ * Legacy writers (claimTaskProvisioning / startTaskRun / recoverExpiredTaskRuns / settleTaskRun
+ * in task-run.ts) are updated in the same commit to write new vocabulary. Both old and new
+ * vocabularies are accepted by the new CHECKs to allow zero-downtime deploys.
+ */
+
+import { Effect } from "effect"
+import type { DatabaseMigration } from "../migration"
+
+export default {
+ id: "20260803000001_subagent_control_plane_l1",
+ up(tx) {
+ return Effect.gen(function* () {
+ // SQLite ignores PRAGMA foreign_keys changes made after a transaction begins. Keep a
+ // transaction-local copy before dropping task_run so ON DELETE CASCADE cannot erase the
+ // historical admission rows that must be rebuilt against the replacement table.
+ yield* tx.run(`
+ CREATE TEMP TABLE task_admission_l1_backup AS
+ SELECT
+ admission_key, request_hash, run_id, parent_session_id,
+ parent_message_id, tool_call_id, delivery_mode, time_created
+ FROM task_admission
+ `)
+
+ // ── Disable FK enforcement during rebuild (re-enabled at end) ─────────
+ yield* tx.run(`PRAGMA foreign_keys = OFF`)
+
+ // ── Step 1: Rebuild task_run with correct state/phase CHECKs ──────────
+ // New CHECK accepts both legacy vocabulary (researching, error) for backward-compat
+ // reads of any rows that pre-date this migration, and new vocabulary (running, failed,
+ // queued, closed, recovery_required) required by the durable control plane.
+ yield* tx.run(`
+ CREATE TABLE task_run_new (
+ run_id TEXT PRIMARY KEY,
+ root_run_id TEXT,
+ request_hash TEXT NOT NULL,
+ parent_session_id TEXT NOT NULL REFERENCES session(id) ON DELETE CASCADE,
+ parent_message_id TEXT NOT NULL,
+ tool_call_id TEXT NOT NULL,
+ child_session_id TEXT NOT NULL,
+ generation INTEGER NOT NULL,
+ delivery_mode TEXT NOT NULL CHECK (delivery_mode IN ('foreground', 'background')),
+ phase TEXT NOT NULL CHECK (phase IN (
+ 'admission', 'research', 'finalize', 'settled',
+ 'queue', 'provision'
+ )),
+ state TEXT NOT NULL CHECK (state IN (
+ 'admitted', 'queued', 'provisioning', 'running', 'researching',
+ 'finalizing', 'completed', 'failed', 'error',
+ 'cancelled', 'interrupted', 'closed', 'recovery_required'
+ )),
+ reason TEXT,
+ attempts INTEGER NOT NULL DEFAULT 0,
+ execution_owner TEXT,
+ lease_expires_at INTEGER,
+ raw_result_message_id TEXT,
+ structured_result_message_id TEXT,
+ output TEXT,
+ error TEXT,
+ time_created INTEGER NOT NULL,
+ time_updated INTEGER NOT NULL,
+ time_settled INTEGER,
+
+ -- L1: run graph / lineage
+ parent_run_id TEXT REFERENCES task_run_new(run_id) ON DELETE CASCADE,
+ continuation_of_run_id TEXT REFERENCES task_run_new(run_id) ON DELETE CASCADE,
+ depth INTEGER NOT NULL DEFAULT 1,
+
+ -- L1: origin identity
+ origin_kind TEXT NOT NULL DEFAULT 'task_tool' CHECK (origin_kind IN ('task_tool','goal_role')),
+ origin_key TEXT,
+
+ -- L1: modes (immutable at admission)
+ effective_delivery_mode TEXT NOT NULL DEFAULT 'foreground',
+ promoted_at INTEGER,
+ session_mode TEXT NOT NULL DEFAULT 'new',
+ context_mode TEXT NOT NULL DEFAULT 'fresh',
+ context_cutoff_message_id TEXT,
+
+ -- L1: capability / workspace policy (frozen at admission)
+ mutation_capability TEXT NOT NULL DEFAULT 'write',
+ tool_capability_hash TEXT NOT NULL DEFAULT 'legacy-unknown',
+ workspace_mode TEXT NOT NULL DEFAULT 'shared',
+ workspace_owner TEXT NOT NULL DEFAULT 'parent',
+ workspace_visibility TEXT NOT NULL DEFAULT 'live',
+ parent_dirty_policy TEXT NOT NULL DEFAULT 'allow_live',
+ workspace_operation_key TEXT,
+ workspace_revision INTEGER,
+ execution_spec TEXT,
+
+ -- L1: lifecycle / CAS
+ version INTEGER NOT NULL DEFAULT 0,
+ control_state TEXT NOT NULL DEFAULT 'open',
+ input_state TEXT NOT NULL DEFAULT 'legacy',
+ child_message_id TEXT,
+ input_admission_started_at INTEGER,
+ child_input_materialized_hash TEXT,
+ child_input_part_count INTEGER,
+ execution_started_at INTEGER,
+ finalizer_started_at INTEGER,
+ interrupt_requested_at INTEGER,
+ interrupt_reason TEXT,
+ close_requested_at INTEGER,
+ close_reason TEXT,
+ claim_generation INTEGER NOT NULL DEFAULT 0,
+ start_attempts INTEGER NOT NULL DEFAULT 0,
+ available_at INTEGER NOT NULL DEFAULT 0,
+ priority INTEGER NOT NULL DEFAULT 0,
+ queue_reason TEXT,
+
+ -- L1: workspace provisioning receipts
+ workspace_preflight_state TEXT NOT NULL DEFAULT 'legacy',
+ workspace_preflight_at INTEGER,
+ workspace_repository_root TEXT,
+ workspace_base_commit TEXT,
+ workspace_parent_branch TEXT,
+ workspace_target_branch TEXT,
+ workspace_status_hash TEXT,
+ workspace_preflight_error_code TEXT,
+ workspace_branch_state TEXT NOT NULL DEFAULT 'none',
+ workspace_branch_started_at INTEGER,
+ worktree_directory TEXT,
+ worktree_branch TEXT,
+ worktree_state TEXT NOT NULL DEFAULT 'none',
+ worktree_started_at INTEGER,
+ pr_operation_key TEXT,
+ pr_started_at INTEGER,
+ pr_id TEXT,
+
+ -- L1: goal-specific identity
+ goal_id TEXT,
+ goal_tick_seq INTEGER,
+ goal_role TEXT,
+ goal_ordinal INTEGER,
+
+ -- L1: result enrichment
+ result_hash TEXT,
+ usage TEXT,
+ progress_seq INTEGER NOT NULL DEFAULT 0,
+ last_progress_at INTEGER,
+ finalizer_input_message_id TEXT
+ )
+ `)
+
+ // ── Step 2: Copy task_run rows with vocabulary renames ────────────────
+ // state: error → failed, researching → running
+ // phase: research stays 'research' (still valid), others unchanged
+ // control_state: backfill 'closed' for all terminal rows
+ yield* tx.run(`
+ INSERT INTO task_run_new
+ SELECT
+ run_id, root_run_id, request_hash, parent_session_id, parent_message_id,
+ tool_call_id, child_session_id, generation, delivery_mode,
+ phase,
+ CASE state
+ WHEN 'error' THEN 'failed'
+ WHEN 'researching' THEN 'running'
+ ELSE state
+ END,
+ reason, attempts, execution_owner, lease_expires_at,
+ raw_result_message_id, structured_result_message_id,
+ output, error, time_created, time_updated, time_settled,
+ NULL, NULL, 1,
+ 'task_tool', NULL,
+ delivery_mode,
+ NULL, 'new', 'fresh', NULL,
+ 'write', 'legacy-unknown',
+ 'shared', 'parent', 'live', 'allow_live',
+ NULL, NULL, NULL,
+ 0,
+ CASE
+ WHEN state IN ('completed','error','failed','cancelled','interrupted','closed')
+ THEN 'closed'
+ ELSE 'open'
+ END,
+ 'legacy',
+ NULL, NULL, NULL, NULL,
+ NULL, NULL,
+ NULL, NULL, NULL, NULL,
+ 0, 0,
+ time_created,
+ 0, NULL,
+ 'legacy', NULL, NULL, NULL, NULL, NULL, NULL, NULL,
+ 'none', NULL,
+ NULL, NULL, 'none', NULL,
+ NULL, NULL, NULL,
+ NULL, NULL, NULL, NULL,
+ NULL, NULL, 0, NULL, NULL
+ FROM task_run
+ `)
+
+ // ── Step 3: Backfill origin_key from task_admission ───────────────────
+ yield* tx.run(`
+ UPDATE task_run_new SET origin_key = (
+ SELECT admission_key FROM task_admission WHERE task_admission.run_id = task_run_new.run_id
+ ) WHERE origin_key IS NULL
+ `)
+
+ // ── Step 4: Backfill start_attempts from attempts for historical rows ─
+ yield* tx.run(`
+ UPDATE task_run_new
+ SET start_attempts = attempts
+ WHERE start_attempts = 0 AND attempts > 0
+ `)
+
+ // ── Step 5: Validate — no orphan state after rename ───────────────────
+ // Note: the INSERT above would already fail with a CHECK constraint violation if any row
+ // had an invalid state. No additional validation step is needed.
+
+ // ── Step 6: Rebuild task_notification_outbox with new status values ───
+ yield* tx.run(`
+ CREATE TABLE task_notification_outbox_new (
+ id TEXT PRIMARY KEY,
+ run_id TEXT NOT NULL UNIQUE REFERENCES task_run_new(run_id) ON DELETE CASCADE,
+ message_id TEXT NOT NULL UNIQUE,
+ parent_session_id TEXT NOT NULL REFERENCES session(id) ON DELETE CASCADE,
+ directory TEXT NOT NULL,
+ payload TEXT NOT NULL,
+ status TEXT NOT NULL CHECK (status IN (
+ 'pending', 'admitting', 'admitted', 'processing', 'delivering', 'delivered', 'dead',
+ 'response_recovery_required'
+ )),
+ attempts INTEGER NOT NULL DEFAULT 0,
+ available_at INTEGER NOT NULL,
+ lease_owner TEXT,
+ lease_expires_at INTEGER,
+ last_error TEXT,
+ time_created INTEGER NOT NULL,
+ time_updated INTEGER NOT NULL,
+ time_delivered INTEGER,
+ -- L1 new columns
+ event_kind TEXT NOT NULL DEFAULT 'terminal',
+ correlation_id TEXT,
+ payload_hash TEXT,
+ parent_input_message_id TEXT,
+ response_message_id TEXT,
+ response_started_at INTEGER,
+ time_admitted INTEGER
+ )
+ `)
+
+ yield* tx.run(`
+ INSERT INTO task_notification_outbox_new
+ SELECT
+ id, run_id, message_id, parent_session_id, directory, payload,
+ -- status: map old values that still apply; 'delivering' → 'processing' for in-flight
+ CASE status
+ WHEN 'delivering' THEN 'processing'
+ ELSE status
+ END AS status,
+ attempts, available_at, lease_owner, lease_expires_at,
+ last_error, time_created, time_updated, time_delivered,
+ 'terminal', NULL, NULL, NULL, NULL, NULL, NULL
+ FROM task_notification_outbox
+ `)
+
+ // ── Step 7: Drop old tables and rename new ones ───────────────────────
+ // Drop indexes that reference the old tables first
+ yield* tx.run(`DROP INDEX IF EXISTS task_run_child_generation_idx`)
+ yield* tx.run(`DROP INDEX IF EXISTS task_run_child_active_idx`)
+ yield* tx.run(`DROP INDEX IF EXISTS task_run_parent_state_idx`)
+ yield* tx.run(`DROP INDEX IF EXISTS task_run_root_idx`)
+ yield* tx.run(`DROP INDEX IF EXISTS task_notification_outbox_due_idx`)
+ yield* tx.run(`DROP TABLE task_notification_outbox`)
+ yield* tx.run(`DROP TABLE task_run`)
+ yield* tx.run(`ALTER TABLE task_run_new RENAME TO task_run`)
+ yield* tx.run(`ALTER TABLE task_notification_outbox_new RENAME TO task_notification_outbox`)
+
+ // ── Step 8: Recreate indexes ──────────────────────────────────────────
+ yield* tx.run(`
+ CREATE UNIQUE INDEX task_run_child_generation_idx
+ ON task_run (child_session_id, generation)
+ `)
+ yield* tx.run(`
+ CREATE UNIQUE INDEX task_run_child_active_idx
+ ON task_run (child_session_id)
+ WHERE state IN ('admitted', 'provisioning', 'running', 'researching', 'finalizing')
+ `)
+ yield* tx.run(`
+ CREATE INDEX task_run_parent_state_idx
+ ON task_run (parent_session_id, state, time_updated)
+ `)
+ yield* tx.run(`
+ CREATE INDEX task_run_root_idx
+ ON task_run (root_run_id)
+ `)
+ yield* tx.run(`
+ CREATE INDEX task_notification_outbox_due_idx
+ ON task_notification_outbox (status, available_at, lease_expires_at)
+ `)
+ yield* tx.run(`
+ CREATE INDEX task_run_queue_idx
+ ON task_run(state, available_at, priority DESC, time_created, generation)
+ `)
+ yield* tx.run(`
+ CREATE INDEX task_run_goal_idx
+ ON task_run(goal_id, goal_tick_seq, goal_role, goal_ordinal)
+ `)
+
+ // ── Step 9: task_run_event (new table, no existing data) ─────────────
+ yield* tx.run(`
+ CREATE TABLE IF NOT EXISTS task_run_event (
+ event_id TEXT PRIMARY KEY,
+ run_id TEXT NOT NULL REFERENCES task_run(run_id) ON DELETE CASCADE,
+ version INTEGER NOT NULL,
+ type TEXT NOT NULL,
+ from_state TEXT,
+ to_state TEXT,
+ reason TEXT,
+ data TEXT,
+ time_created INTEGER NOT NULL,
+ UNIQUE(run_id, version)
+ )
+ `)
+ yield* tx.run(`
+ CREATE INDEX IF NOT EXISTS task_run_event_time_idx
+ ON task_run_event(time_created, event_id)
+ `)
+
+ // ── Step 10: Unique index on outbox per-parent processing ─────────────
+ yield* tx.run(`
+ CREATE UNIQUE INDEX IF NOT EXISTS task_notification_outbox_parent_processing_idx
+ ON task_notification_outbox(parent_session_id)
+ WHERE status = 'processing'
+ `)
+
+ // ── task_admission: shadow table rebuild (add origin fields) ──────────
+ yield* tx.run(`
+ CREATE TABLE task_admission_new (
+ admission_key TEXT PRIMARY KEY,
+ request_hash TEXT NOT NULL,
+ run_id TEXT NOT NULL REFERENCES task_run(run_id) ON DELETE CASCADE,
+ parent_session_id TEXT NOT NULL REFERENCES session(id) ON DELETE CASCADE,
+ parent_message_id TEXT NOT NULL,
+ tool_call_id TEXT NOT NULL,
+ delivery_mode TEXT NOT NULL CHECK (delivery_mode IN ('foreground', 'background')),
+ time_created INTEGER NOT NULL,
+ -- L1: origin identity fields
+ origin_kind TEXT NOT NULL DEFAULT 'task_tool' CHECK (origin_kind IN ('task_tool','goal_role')),
+ origin_key TEXT
+ )
+ `)
+ yield* tx.run(`
+ INSERT INTO task_admission_new
+ SELECT
+ admission_key, request_hash, run_id, parent_session_id,
+ parent_message_id, tool_call_id, delivery_mode, time_created,
+ 'task_tool', admission_key
+ FROM task_admission_l1_backup
+ `)
+ yield* tx.run(`DROP INDEX IF EXISTS task_admission_run_idx`)
+ yield* tx.run(`DROP TABLE task_admission`)
+ yield* tx.run(`ALTER TABLE task_admission_new RENAME TO task_admission`)
+ yield* tx.run(`
+ CREATE INDEX task_admission_run_idx ON task_admission (run_id)
+ `)
+ yield* tx.run(`DROP TABLE task_admission_l1_backup`)
+
+ // ── Step 11: Re-enable FK enforcement ────────────────────────────────
+ yield* tx.run(`PRAGMA foreign_keys = ON`)
+ })
+ },
+} satisfies DatabaseMigration.Migration
diff --git a/packages/core/src/database/migration/20260805000000_repair_task_admission.ts b/packages/core/src/database/migration/20260805000000_repair_task_admission.ts
new file mode 100644
index 00000000..378bb427
--- /dev/null
+++ b/packages/core/src/database/migration/20260805000000_repair_task_admission.ts
@@ -0,0 +1,30 @@
+import { Effect } from "effect"
+import type { DatabaseMigration } from "../migration"
+
+export default {
+ id: "20260805000000_repair_task_admission",
+ up(tx) {
+ return Effect.gen(function* () {
+ // Early L1 builds could cascade-delete task_admission while rebuilding task_run with
+ // foreign_keys still enabled. L1 persisted the canonical admission key on the run before
+ // that drop, so restore the exact-retry authority when the row is otherwise missing.
+ yield* tx.run(`
+ INSERT INTO task_admission (
+ admission_key, request_hash, run_id, parent_session_id, parent_message_id,
+ tool_call_id, delivery_mode, time_created, origin_kind, origin_key
+ )
+ SELECT
+ run.origin_key, run.request_hash, run.run_id, run.parent_session_id,
+ run.parent_message_id, run.tool_call_id, run.delivery_mode, run.time_created,
+ 'task_tool', run.origin_key
+ FROM task_run AS run
+ WHERE run.origin_kind = 'task_tool'
+ AND run.origin_key IS NOT NULL
+ AND NOT EXISTS (
+ SELECT 1 FROM task_admission AS admission WHERE admission.run_id = run.run_id
+ )
+ ON CONFLICT DO NOTHING
+ `)
+ })
+ },
+} satisfies DatabaseMigration.Migration
diff --git a/packages/core/src/database/migration/20260806051000_session_prompt_intent.ts b/packages/core/src/database/migration/20260806051000_session_prompt_intent.ts
new file mode 100644
index 00000000..9219f0f8
--- /dev/null
+++ b/packages/core/src/database/migration/20260806051000_session_prompt_intent.ts
@@ -0,0 +1,35 @@
+import { Effect } from "effect"
+import type { DatabaseMigration } from "../migration"
+
+export default {
+ id: "20260806051000_session_prompt_intent",
+ up(tx) {
+ return Effect.gen(function* () {
+ yield* tx.run(`
+ CREATE TABLE session_intent (
+ intent_id TEXT PRIMARY KEY,
+ session_id TEXT NOT NULL REFERENCES session(id) ON DELETE CASCADE,
+ source TEXT NOT NULL CHECK (source IN ('composer', 'intelligence', 'followup', 'rewrite')),
+ state TEXT NOT NULL CHECK (state IN ('preparing', 'admitting', 'admitted', 'canceled', 'superseded', 'failed')),
+ selected_variant TEXT CHECK (selected_variant IN ('original', 'rewritten')),
+ selected_payload_hash TEXT,
+ delivery TEXT CHECK (delivery IN ('turn', 'steer', 'queue', 'goal_steer')),
+ admitted_message_id TEXT,
+ correlation_id TEXT,
+ owner_token TEXT,
+ lease_expires_at INTEGER,
+ version INTEGER NOT NULL DEFAULT 0,
+ time_created INTEGER NOT NULL,
+ time_selected INTEGER,
+ time_admitted INTEGER,
+ time_updated INTEGER NOT NULL,
+ UNIQUE (session_id, intent_id)
+ )
+ `)
+ yield* tx.run(`
+ CREATE INDEX session_intent_session_state_idx
+ ON session_intent (session_id, state, time_created)
+ `)
+ })
+ },
+} satisfies DatabaseMigration.Migration
diff --git a/packages/core/src/database/migration/20260806060000_session_mutation_epoch.ts b/packages/core/src/database/migration/20260806060000_session_mutation_epoch.ts
new file mode 100644
index 00000000..fb8486a4
--- /dev/null
+++ b/packages/core/src/database/migration/20260806060000_session_mutation_epoch.ts
@@ -0,0 +1,18 @@
+import { Effect } from "effect"
+import type { DatabaseMigration } from "../migration"
+
+export default {
+ id: "20260806060000_session_mutation_epoch",
+ up(tx) {
+ return Effect.gen(function* () {
+ yield* tx.run("ALTER TABLE session ADD COLUMN mutation_epoch INTEGER NOT NULL DEFAULT 0")
+ yield* tx.run("ALTER TABLE session_intent ADD COLUMN mutation_epoch INTEGER NOT NULL DEFAULT 0")
+ yield* tx.run("ALTER TABLE session_steer ADD COLUMN mutation_epoch INTEGER NOT NULL DEFAULT 0")
+ yield* tx.run("ALTER TABLE session_steer ADD COLUMN superseded_at INTEGER")
+ yield* tx.run(`
+ CREATE INDEX session_steer_session_epoch_pending_idx
+ ON session_steer (session_id, mutation_epoch, delivery, consumed_seq, superseded_at, seq)
+ `)
+ })
+ },
+} satisfies DatabaseMigration.Migration
diff --git a/packages/core/src/database/migration/20260806070000_compaction_lifecycle.ts b/packages/core/src/database/migration/20260806070000_compaction_lifecycle.ts
new file mode 100644
index 00000000..6ba778c9
--- /dev/null
+++ b/packages/core/src/database/migration/20260806070000_compaction_lifecycle.ts
@@ -0,0 +1,102 @@
+import { Effect } from "effect"
+import type { DatabaseMigration } from "../migration"
+
+// BUG-005: introduce the durable compaction lifecycle tables and the PromptEpoch table.
+//
+// compaction_run tracks logical compaction attempts (one per hard decision).
+// compaction_summary_attempt tracks physical Provider dispatches within a run (max 2 per run).
+// session_prompt_epoch is the unique history boundary authority (replaces summary-scan heuristic).
+//
+// These three tables share the existing shared SQLite database alongside the core session tables.
+// Migrations are additive; no existing data is touched.
+export default {
+ id: "20260806070000_compaction_lifecycle",
+ up(tx) {
+ return Effect.gen(function* () {
+ // ── compaction_run ──────────────────────────────────────────────────
+ // One row per logical compaction decision. A session may have many runs
+ // (one per hard overflow event) but at most one "active" (requested/summarizing) run.
+ yield* tx.run(`
+ CREATE TABLE compaction_run (
+ run_id TEXT NOT NULL PRIMARY KEY,
+ session_id TEXT NOT NULL,
+ from_prompt_epoch INTEGER NOT NULL,
+ target_prompt_epoch INTEGER,
+ trigger TEXT NOT NULL CHECK (trigger IN ('turn_start', 'provider_overflow', 'manual')),
+ marker_message_id TEXT,
+ marker_part_id TEXT,
+ committed_summary_message_id TEXT,
+ checkpoint_ref TEXT,
+ checkpoint_hash TEXT,
+ state TEXT NOT NULL CHECK (state IN
+ ('requested', 'summarizing', 'committed', 'failed', 'indeterminate')),
+ terminal_failure_kind TEXT,
+ created_at INTEGER NOT NULL,
+ committed_at INTEGER
+ )
+ `)
+ // At most one active run per session (state in requested|summarizing|indeterminate).
+ yield* tx.run(`
+ CREATE UNIQUE INDEX compaction_run_session_active_idx
+ ON compaction_run (session_id)
+ WHERE state IN ('requested', 'summarizing', 'indeterminate')
+ `)
+ yield* tx.run(`CREATE INDEX compaction_run_session_idx ON compaction_run (session_id, created_at)`)
+
+ // ── compaction_summary_attempt ──────────────────────────────────────
+ // One row per physical Provider dispatch within a compaction_run.
+ // ordinal is 1-based; max 2 dispatches per run (BUG-006 hard upper bound).
+ yield* tx.run(`
+ CREATE TABLE compaction_summary_attempt (
+ summary_attempt_id TEXT NOT NULL PRIMARY KEY,
+ run_id TEXT NOT NULL REFERENCES compaction_run(run_id) ON DELETE CASCADE,
+ ordinal INTEGER NOT NULL CHECK (ordinal >= 1),
+ parent_attempt_id TEXT,
+ provider_id TEXT NOT NULL,
+ model_id TEXT NOT NULL,
+ protocol TEXT NOT NULL,
+ request_hash TEXT,
+ idempotency_key TEXT,
+ state TEXT NOT NULL CHECK (state IN
+ ('prepared', 'dispatching', 'streaming', 'settled', 'failed',
+ 'indeterminate_after_crash')),
+ retry_reason TEXT,
+ failure_kind TEXT,
+ prepared_at INTEGER NOT NULL,
+ dispatched_at INTEGER,
+ completed_at INTEGER,
+ UNIQUE (run_id, ordinal)
+ )
+ `)
+
+ // ── session_prompt_epoch ────────────────────────────────────────────
+ // The ONLY history boundary authority for a session. Exactly one row has
+ // state='active' per session at any time (enforced by the partial unique index).
+ // checkpoint refs are null for Epoch 0 (bootstrap / no compaction yet).
+ yield* tx.run(`
+ CREATE TABLE session_prompt_epoch (
+ session_id TEXT NOT NULL,
+ epoch INTEGER NOT NULL CHECK (epoch >= 0),
+ state TEXT NOT NULL CHECK (state IN ('active', 'retired')),
+ checkpoint_user_id TEXT,
+ checkpoint_assistant_id TEXT,
+ retained_tail_start_id TEXT,
+ source_end_message_id TEXT,
+ checkpoint_hash TEXT,
+ reason TEXT NOT NULL CHECK (reason IN
+ ('bootstrap', 'compaction', 'model', 'agent', 'directory',
+ 'workspace', 'tools', 'permission', 'renderer')),
+ created_at INTEGER NOT NULL,
+ retired_at INTEGER,
+ PRIMARY KEY (session_id, epoch)
+ )
+ `)
+ // At most one active epoch per session.
+ yield* tx.run(`
+ CREATE UNIQUE INDEX session_prompt_epoch_active_idx
+ ON session_prompt_epoch (session_id)
+ WHERE state = 'active'
+ `)
+ })
+ },
+} satisfies DatabaseMigration.Migration
diff --git a/packages/core/src/database/migration/20260806080000_session_tool_request_receipt.ts b/packages/core/src/database/migration/20260806080000_session_tool_request_receipt.ts
new file mode 100644
index 00000000..082c411a
--- /dev/null
+++ b/packages/core/src/database/migration/20260806080000_session_tool_request_receipt.ts
@@ -0,0 +1,54 @@
+import { Effect } from "effect"
+import type { DatabaseMigration } from "../migration"
+
+// BUG-009: per-turn final-request receipt.
+// One row per physical Provider dispatch, recording the tool candidate/filter/offer pipeline
+// so failures can be attributed to a specific stage (registry, permission, adapter).
+// This table intentionally does NOT duplicate Tool.Called/Success/Failed events; it relates
+// to those events via (assistant_message_id, call_id).
+export default {
+ id: "20260806080000_session_tool_request_receipt",
+ up(tx) {
+ return Effect.gen(function* () {
+ yield* tx.run(`
+ CREATE TABLE session_tool_request_receipt (
+ receipt_id TEXT NOT NULL PRIMARY KEY,
+ request_ordinal INTEGER NOT NULL CHECK (request_ordinal >= 1),
+ session_id TEXT NOT NULL,
+ user_message_id TEXT NOT NULL,
+ assistant_message_id TEXT,
+ provider_attempt_id TEXT,
+ provider_id TEXT NOT NULL,
+ model_id TEXT NOT NULL,
+ protocol TEXT,
+ registry_tool_ids TEXT NOT NULL, -- JSON array of all registered tool IDs
+ permission_filtered_tool_ids TEXT NOT NULL, -- JSON array after permission check
+ final_offered_tool_ids TEXT NOT NULL, -- JSON array in final wire request
+ call_ids TEXT NOT NULL DEFAULT '[]', -- JSON array of provider tool call IDs observed in this turn
+ tool_definition_hash TEXT, -- stable hash of offered schema bytes
+ tool_choice_mode TEXT, -- "auto"|"required"|"none"|null
+ adapter_tool_capability TEXT, -- "supported"|"unsupported"|"unknown"
+ adapter_lowering_outcome TEXT, -- "ok"|"schema_rejected"|"omitted_no_support"
+ estimated_input_tokens INTEGER,
+ physical_input_budget INTEGER,
+ reserved_output_tokens INTEGER,
+ safety_margin_tokens INTEGER,
+ context_limit_provenance TEXT, -- "model_limit"|"host_guard"
+ request_state TEXT NOT NULL CHECK (request_state IN ('prepared','dispatched','rejected')),
+ request_error_code TEXT,
+ created_at INTEGER NOT NULL
+ )
+ `)
+ yield* tx.run(
+ `CREATE UNIQUE INDEX session_tool_request_receipt_session_ordinal_idx
+ ON session_tool_request_receipt(session_id, request_ordinal)`,
+ )
+ yield* tx.run(
+ `CREATE INDEX session_tool_request_receipt_session_idx ON session_tool_request_receipt(session_id, created_at)`,
+ )
+ yield* tx.run(
+ `CREATE INDEX session_tool_request_receipt_msg_idx ON session_tool_request_receipt(assistant_message_id)`,
+ )
+ })
+ },
+} satisfies DatabaseMigration.Migration
diff --git a/packages/core/src/database/migration/20260807090000_session_tool_argument_receipt.ts b/packages/core/src/database/migration/20260807090000_session_tool_argument_receipt.ts
new file mode 100644
index 00000000..bc73a969
--- /dev/null
+++ b/packages/core/src/database/migration/20260807090000_session_tool_argument_receipt.ts
@@ -0,0 +1,45 @@
+import { Effect } from "effect"
+import type { DatabaseMigration } from "../migration"
+
+// BUG-010: bounded evidence for each layer of the Provider argument pipeline.
+// The table deliberately excludes raw payloads; payload_hash/length/keys are enough
+// to correlate a damaged argument without persisting prompts, files, or secrets.
+export default {
+ id: "20260807090000_session_tool_argument_receipt",
+ up(tx) {
+ return Effect.gen(function* () {
+ yield* tx.run(`
+ CREATE TABLE session_tool_argument_receipt (
+ receipt_id TEXT NOT NULL,
+ layer TEXT NOT NULL CHECK (layer IN ('raw_frame','ai_sdk_input','adapter_assembly','processor_decoded')),
+ ordinal INTEGER NOT NULL CHECK (ordinal >= 0),
+ call_id TEXT,
+ tool_name TEXT,
+ event_type TEXT NOT NULL,
+ payload_hash TEXT,
+ payload_length INTEGER CHECK (payload_length IS NULL OR payload_length >= 0),
+ payload_keys TEXT NOT NULL,
+ unavailable_reason TEXT,
+ created_at INTEGER NOT NULL,
+ PRIMARY KEY (receipt_id, layer, ordinal),
+ FOREIGN KEY (receipt_id) REFERENCES session_tool_request_receipt(receipt_id) ON DELETE CASCADE,
+ CHECK (call_id IS NULL OR length(trim(call_id)) > 0),
+ CHECK (tool_name IS NULL OR length(trim(tool_name)) > 0),
+ CHECK (
+ (payload_hash IS NOT NULL AND length(payload_hash) = 64 AND payload_length IS NOT NULL AND unavailable_reason IS NULL)
+ OR
+ (payload_hash IS NULL AND payload_length IS NULL AND unavailable_reason IS NOT NULL AND length(trim(unavailable_reason)) > 0)
+ )
+ )
+ `)
+ yield* tx.run(
+ `CREATE INDEX session_tool_argument_receipt_call_idx
+ ON session_tool_argument_receipt(receipt_id, call_id, layer, ordinal)`,
+ )
+ yield* tx.run(
+ `CREATE INDEX session_tool_argument_receipt_created_idx
+ ON session_tool_argument_receipt(created_at)`,
+ )
+ })
+ },
+} satisfies DatabaseMigration.Migration
diff --git a/packages/core/src/database/migration/20260807123000_session_tool_argument_validation_outcome.ts b/packages/core/src/database/migration/20260807123000_session_tool_argument_validation_outcome.ts
new file mode 100644
index 00000000..1e9a2ea3
--- /dev/null
+++ b/packages/core/src/database/migration/20260807123000_session_tool_argument_validation_outcome.ts
@@ -0,0 +1,25 @@
+import { Effect } from "effect"
+import type { DatabaseMigration } from "../migration"
+
+// Argument receipts are diagnostic evidence, so the stored row must distinguish raw visibility,
+// schema admission, and the plan tool's semantic admission result without retaining the payload.
+export default {
+ id: "20260807123000_session_tool_argument_validation_outcome",
+ up(tx) {
+ return Effect.gen(function* () {
+ yield* tx.run(`
+ ALTER TABLE session_tool_argument_receipt
+ ADD COLUMN validation_outcome TEXT NOT NULL DEFAULT 'not_evaluated'
+ CHECK (validation_outcome IN (
+ 'not_evaluated',
+ 'schema_valid',
+ 'schema_invalid',
+ 'semantic_valid',
+ 'semantic_invalid',
+ 'conflict',
+ 'no_progress'
+ ))
+ `)
+ })
+ },
+} satisfies DatabaseMigration.Migration
diff --git a/packages/core/src/deepagent/failure-triage.ts b/packages/core/src/deepagent/failure-triage.ts
index af9e3c34..9d642443 100644
--- a/packages/core/src/deepagent/failure-triage.ts
+++ b/packages/core/src/deepagent/failure-triage.ts
@@ -1,5 +1,5 @@
import { analyzeErrors, type ErrorPattern } from "./diagnosis"
-import type { ValidationResult } from "./round-state"
+import type { ValidationFailureKind, ValidationResult } from "./round-state"
/**
* T2 (S1-v3.4): failure triage — the "fixability × progress" three-light classifier.
@@ -38,12 +38,14 @@ export type TriageResult = {
readonly reason: string // human-readable; flows into needs_human body / fold label
}
-// Exit codes that indicate the command/environment, not the code, failed.
-// 127 = command not found, 126 = not executable, 124 = timeout (GNU coreutils convention).
-const ENV_EXIT_CODES = new Set([124, 126, 127])
-// 128 + signal: 137 = SIGKILL (OOM), 139 = SIGSEGV, 134 = SIGABRT — when these come from the
-// toolchain itself they are environment crashes, not user-code assertions.
-const SIGNAL_EXIT_CODES = new Set([134, 137, 139])
+const ENV_FAILURE_KINDS = new Set([
+ "shell_bootstrap_failed",
+ "unsupported_platform",
+ "unsupported_dialect",
+ "timeout",
+ "signal",
+ "output_unavailable",
+])
// Output signatures of environment / dependency / network / resource problems (not fixable by editing code).
const ENV_OUTPUT =
@@ -66,8 +68,8 @@ const dominantCategory = (patterns: ErrorPattern[]): string | null => {
return [...patterns].sort((a, b) => b.count - a.count || a.category.localeCompare(b.category))[0]!.category
}
-const hasEnvExitCode = (failed: readonly ValidationResult[]): number | undefined =>
- failed.find((f) => ENV_EXIT_CODES.has(f.exit_code) || SIGNAL_EXIT_CODES.has(f.exit_code))?.exit_code
+const environmentFailure = (failed: readonly ValidationResult[]): ValidationResult | undefined =>
+ failed.find((result) => ENV_FAILURE_KINDS.has(result.kind))
/**
* Classify a failing round into a tier (+ yellow substate). Pure function; all signals are passed in.
@@ -80,12 +82,12 @@ export const classifyFailure = (input: TriageInput): TriageResult => {
const combined = [...input.failed.map((f) => f.output), input.errorOutput ?? ""].join("\n")
// ── 🔴 RED: not auto-fixable (any one hit → immediate exit, no budget burn) ──
- const envExit = hasEnvExitCode(input.failed)
- if (envExit !== undefined) {
+ const transportFailure = environmentFailure(input.failed)
+ if (transportFailure) {
return {
tier: "not_auto_fixable",
category,
- reason: `command/environment failure (exit ${envExit}) — not auto-fixable`,
+ reason: `validation runner failure (${transportFailure.kind}, exit ${transportFailure.exit_code}) — not auto-fixable`,
}
}
if (ENV_OUTPUT.test(combined)) {
diff --git a/packages/core/src/deepagent/goal-loop.ts b/packages/core/src/deepagent/goal-loop.ts
index b542560d..714670a5 100644
--- a/packages/core/src/deepagent/goal-loop.ts
+++ b/packages/core/src/deepagent/goal-loop.ts
@@ -1,15 +1,18 @@
import { Effect, Schema } from "effect"
+import type { ValidationResult } from "./round-state"
import { randomUUID } from "node:crypto"
import type { DocumentStore } from "./document-store"
import {
type PlanDoc,
- type PlanInput,
type PlanStep,
buildCompletionReport,
- buildPlanFromInput,
+ buildPlanFromWriteInput,
hasBlockedSteps,
+ planProgressFingerprint,
planScope,
} from "./plan-controller"
+import { type PlanEditCommand, PlanEditTargetUnavailableError } from "./plan-edit-protocol"
+import { compareAndCommitPlanDocument, decodePlanDoc } from "./plan-store"
// V3.9 §D — Goal Loop（自主长跑原语）. A supervised, cross-tick control loop: given an OBJECTIVELY
// decidable completion criterion, the loop drives 计划→执行→验证→迭代 until the criteria are met or a
@@ -153,7 +156,9 @@ export class InvalidGoalError extends Schema.TaggedErrorClass(
*/
export type GraderPorts = {
/** Run the given validation commands; `pass` iff ALL succeeded. */
- readonly runTests: (commands: readonly string[]) => Effect.Effect<{ readonly pass: boolean }>
+ readonly runTests: (
+ commands: readonly string[],
+ ) => Effect.Effect<{ readonly pass: boolean; readonly results?: readonly ValidationResult[] }>
/**
* Highest diagnostic severity currently present, or null when there are none. `checked` MUST be false
* when the port could not actually compute diagnostics (LSP crashed/timed out, no client covered the
@@ -197,7 +202,10 @@ const evaluateOne = (
Effect.gen(function* () {
switch (criterion.kind) {
case "tests_pass": {
- const { pass } = yield* ports.runTests(criterion.commands)
+ const { pass, results } = yield* ports.runTests(criterion.commands)
+ const runnerFailure = results?.find((result) => result.kind !== "command_exit")
+ if (runnerFailure)
+ return `tests_pass: validation runner failed (${runnerFailure.kind}) for [${runnerFailure.command}]`
return pass ? null : `tests_pass: one or more of [${criterion.commands.join(", ")}] failed`
}
case "no_diagnostics": {
@@ -442,14 +450,10 @@ const stateSlug = (goalId: string): string => `goal-state-${goalId}`
// The plan doc body is the JSON-serialized PlanDoc (the goal carrier). Parse defensively — a malformed
// / absent body yields null so plan_complete reports a gap rather than crashing the loop.
-const readPlan = (store: DocumentStore, planDocId: string): { plan: PlanDoc | null; version: number } => {
- const doc = store.get(planDocId)
+const readPlan = (store: DocumentStore, planDocId: string, version?: number): { plan: PlanDoc | null; version: number } => {
+ const doc = store.get(planDocId, version)
if (!doc) return { plan: null, version: 0 }
- try {
- return { plan: JSON.parse(doc.body) as PlanDoc, version: doc.version }
- } catch {
- return { plan: null, version: doc.version }
- }
+ return { plan: decodePlanDoc(doc.body), version: doc.version }
}
// Step-status fingerprint drives no-progress / stall detection (independent of the doc version used
@@ -519,50 +523,6 @@ const loadState = (deps: ControllerDeps, handle: GoalHandle): GoalRuntimeState |
return null
}
-// V4.1 cross-process cold recovery — a durable home for a PENDING USER PLAN EDIT so the event-driven
-// GoalTickConsumer (which may run on a cold fiber with no in-memory control map) can pick it up. The
-// in-process driver historically kept the pending PlanInput ONLY in the goal-manager `controls` map;
-// that is invisible to a cold consumer. We persist it as a `run_context` doc under the SAME store, but
-// DELIBERATELY WITHOUT the `goal_id` extension (which `loadState` matches on at line ~434) — instead we
-// mark it with `pending_edit_goal_id`, so `loadState` skips it (its goal_id is undefined ≠ the handle's)
-// and never tries to parse a PlanInput as GoalRuntimeState. An empty body is the "no pending edit"
-// sentinel (there is no doc delete API). The consumer reads it via its own fresh store handle; the
-// content-equality clear in markPlanEditConsumed preserves a newer edit written between read and clear.
-const pendingEditSlug = (goalId: string): string => `goal-pending-edit-${goalId}`
-
-export const persistPendingPlanEdit = (
- store: DocumentStore,
- sessionId: string,
- goalId: string,
- plan: PlanInput | null,
-): void => {
- store.upsert({
- type: "run_context",
- scope: planScope(sessionId),
- description: `goal pending plan edit ${goalId}`,
- idSlug: pendingEditSlug(goalId),
- body: plan == null ? "" : JSON.stringify(plan),
- provenance: { source: "runner", run_ref: planScope(sessionId) },
- // NOTE: pending_edit_goal_id, NOT goal_id — keeps loadState() from ever matching this doc.
- extensions: { pending_edit_goal_id: goalId },
- })
-}
-
-export const readPendingPlanEdit = (store: DocumentStore, sessionId: string, goalId: string): PlanInput | null => {
- for (const ref of store.list({ type: "run_context", scope: planScope(sessionId) })) {
- const doc = store.get(ref.id)
- if (!doc) continue
- if (doc.extensions?.pending_edit_goal_id !== goalId) continue
- if (!doc.body.trim()) return null // sentinel: consumed / never set
- try {
- return JSON.parse(doc.body) as PlanInput
- } catch {
- return null
- }
- }
- return null
-}
-
// V4.1 §N — durable command cursor. Weight ticks by one more than the maximum continuing stall count so
// resetting stallCount after progress cannot repeat or decrease the cursor. A replay advances stallCount;
// an executed tick advances ledger.ticks; every continuing transition therefore produces a fresh key.
@@ -758,7 +718,10 @@ export interface GoalLoop {
* re-baseline gives the revision a fresh runway.
* No-op when no persisted state exists for the handle (goal not started / already gone).
*/
- readonly applyPlanEdit: (handle: GoalHandle, edit: PlanInput) => Effect.Effect
+ readonly applyPlanEdit: (
+ handle: GoalHandle,
+ command: PlanEditCommand,
+ ) => Effect.Effect<{ readonly plan_id: string; readonly doc_id: string; readonly version: number; readonly changed: boolean }, unknown>
}
// §D.4 start validation — HARD, no defaults that bypass. criteria empty → not objectively decidable;
@@ -1060,48 +1023,78 @@ export const makeGoalLoop = (deps: ControllerDeps): GoalLoop => {
persistState(deps, { ...state, phase: "stopped", lastOutcome: state.lastOutcome })
})
- const applyPlanEdit: GoalLoop["applyPlanEdit"] = (handle, edit) =>
- Effect.sync(() => {
+ const applyPlanEdit: GoalLoop["applyPlanEdit"] = (handle, command) =>
+ Effect.try({
+ try: () => {
const state = loadState(deps, handle)
- // No persisted state (goal not started / gone), or already terminal → nothing to edit/re-baseline.
- if (state == null || isTerminalPhase(state.phase)) return
- // Reconcile the user's revision against the CURRENT durable plan (via this driver's own store
- // handle) so step ids + accumulated evidence are PRESERVED across the rewrite (buildPlanFromInput
- // matches revised steps to prior steps by id). Reading `previous` here — not in the HTTP fiber —
- // is why evidence isn't lost: the driver's handle holds the up-to-date doc incl. the last tick's
- // mirrored-back progress.
+ if (state == null) throw new PlanEditTargetUnavailableError("goal state not found")
+ if (isTerminalPhase(state.phase)) throw new PlanEditTargetUnavailableError(`goal is ${state.phase}`)
+ if (command.session_id !== handle.sessionId || command.goal_id !== handle.goalId) {
+ throw new PlanEditTargetUnavailableError("command identity does not match the goal handle")
+ }
+
+ const expectedVersion = command.plan_write.expected_version
+ if (expectedVersion != null) {
+ const recovered = readPlan(deps.store, state.planDocId, expectedVersion + 1)
+ if (recovered.plan?.last_write_activity_id === command.activity_id) {
+ const current = readPlan(deps.store, state.planDocId)
+ if (current.plan == null) throw new PlanEditTargetUnavailableError("authoritative plan is malformed")
+ persistPlanEditBaseline(deps, state, current.plan)
+ return {
+ plan_id: recovered.plan.plan_id,
+ doc_id: state.planDocId,
+ version: recovered.version,
+ changed: true,
+ }
+ }
+ }
+
const existing = deps.store.get(state.planDocId)
- // The goal's plan doc must already exist (start materialized it). If it is somehow gone, do NOT
- // fabricate an orphan under a fresh id — a re-baseline against a doc the tick can't read would be
- // silent data loss. Bail (no-op) so the caller's ok:true never lies about a lost edit.
- if (existing == null) return
+ if (existing == null) throw new PlanEditTargetUnavailableError("authoritative plan document not found")
const previous = readPlan(deps.store, state.planDocId).plan
- const editedPlan = buildPlanFromInput(state.sessionId, edit, previous)
- // 1) Write the edited plan back to THE SAME durable doc by id (version+1), so the next tick's
- // readPlan(state.planDocId) sees the revision. Writing by id — not upsert-by-logical-key —
- // avoids the description/idSlug matching that would otherwise mint an orphan doc (upsert's
- // findLogical keys on description, which need not equal the doc materialize() wrote). A
- // fingerprint-identical edit is a no-op (updateWithProvenance returns cur unchanged, INV-4).
- // provenance.source="human" records the human-authored revision (vs the model's plan-tool edits).
- deps.store.updateWithProvenance(state.planDocId, JSON.stringify(editedPlan), {
- source: "human",
- run_ref: planScope(state.sessionId),
- })
- // 2) Re-baseline: reset stall + set the progress baselines to the EDITED plan, and null the
- // processed-version so the next tick runs against the revision (not deduped, not a false stall).
- persistState(deps, {
- ...state,
- stallCount: 0,
- lastFingerprint: planFingerprint(editedPlan),
- lastDoneCount: doneStepCount(editedPlan),
- lastEvidenceCount: evidenceCount(editedPlan),
- // metCount is criteria-derived (independent of plan structure); leave it — a plan edit does not
- // retroactively un-meet a satisfied criterion, and the next tick re-grades regardless.
- lastProcessedVersion: null,
+ if (previous == null) throw new PlanEditTargetUnavailableError("authoritative plan is malformed")
+ const editedPlan = buildPlanFromWriteInput(
+ state.sessionId,
+ command.plan_write,
+ previous,
+ { plan_id: previous.plan_id, doc_id: existing.id, version: existing.version },
+ { allowQualityRegression: command.confirmed_challenge_id != null },
+ )
+ if (
+ planProgressFingerprint({ ...editedPlan, last_write_activity_id: null }) ===
+ planProgressFingerprint({ ...previous, last_write_activity_id: null })
+ ) {
+ persistPlanEditBaseline(deps, state, previous)
+ return { plan_id: previous.plan_id, doc_id: existing.id, version: existing.version, changed: false }
+ }
+ const committed = compareAndCommitPlanDocument(deps.store, {
+ sessionId: state.sessionId,
+ expected: {
+ plan_id: command.plan_write.expected_plan_id ?? previous.plan_id,
+ doc_id: existing.id,
+ version: command.plan_write.expected_version ?? existing.version,
+ },
+ candidate: { ...editedPlan, last_write_activity_id: command.activity_id },
+ origin: "human_goal_edit",
})
+ persistPlanEditBaseline(deps, state, committed.plan)
+ return { plan_id: committed.plan.plan_id, doc_id: committed.doc_id, version: committed.version, changed: true }
+ },
+ catch: (error) => error,
})
return { start, tick, status, stop, applyPlanEdit }
}
+const persistPlanEditBaseline = (deps: ControllerDeps, state: GoalRuntimeState, plan: PlanDoc): void => {
+ persistState(deps, {
+ ...state,
+ stallCount: 0,
+ lastFingerprint: planFingerprint(plan),
+ lastDoneCount: doneStepCount(plan),
+ lastEvidenceCount: evidenceCount(plan),
+ lastProcessedVersion: null,
+ })
+}
+
export * as GoalLoop from "./goal-loop"
diff --git a/packages/core/src/deepagent/plan-controller.ts b/packages/core/src/deepagent/plan-controller.ts
index fa393706..c6d7edf1 100644
--- a/packages/core/src/deepagent/plan-controller.ts
+++ b/packages/core/src/deepagent/plan-controller.ts
@@ -9,7 +9,7 @@
// (new user message, tool failure, validation failure, no-progress fingerprint, pack change) — it
// does NOT trust the model to report that it deviated. That is what makes the gate robust on MoE
// models whose self-reporting is unreliable.
-import { randomUUID } from "node:crypto"
+import { createHash, randomUUID } from "node:crypto"
import type { AgentMode } from "./mode"
import { classifyCommand } from "./command-intent"
@@ -56,6 +56,10 @@ export type PlanDoc = {
readonly steps: readonly PlanStep[]
// null in P0 (coarse-grained latch only); U9 makes it authoritative for high+ per-step binding.
readonly active_step_id: string | null
+ /** The reason for the most recent explicit replan, retained for progress identity. */
+ readonly replan_reason?: string | null
+ /** Server-generated human plan-edit activity that produced this exact version, if any. */
+ readonly last_write_activity_id?: string | null
readonly created_at: string
}
@@ -198,6 +202,399 @@ const STATUS_ALIASES: Record = {
skipped: "cancelled",
stuck: "blocked",
}
+
+export type PlanWriteOperation = "create" | "advance" | "replan"
+export type PlanWriteOrigin = "model_tool" | "human_goal_edit" | "runtime_goal_bridge" | "legacy_migration"
+export type PlanWriteStatus = PlanStepStatus | keyof typeof STATUS_ALIASES
+
+export type PlanWriteInput = {
+ readonly operation: PlanWriteOperation
+ readonly expected_plan_id: string | null
+ readonly expected_version: number | null
+ readonly replan_reason?: string
+ readonly goal: string
+ readonly assumptions?: readonly string[]
+ readonly steps: readonly {
+ readonly step_id?: string
+ readonly title: string
+ readonly status: PlanWriteStatus
+ readonly acceptance?: string | null
+ readonly assigned_agent?: string | null
+ readonly note?: string | null
+ }[]
+ readonly active_step_id: string | null
+}
+
+const isRecord = (value: unknown): value is Record =>
+ typeof value === "object" && value !== null && !Array.isArray(value)
+
+/** Decode a persisted or otherwise untrusted strict plan-write envelope. */
+export const decodePlanWriteInput = (value: unknown): PlanWriteInput | null => {
+ if (!isRecord(value)) return null
+ if (!(value.operation === "create" || value.operation === "advance" || value.operation === "replan")) return null
+ if (!(value.expected_plan_id === null || typeof value.expected_plan_id === "string")) return null
+ if (
+ !(
+ value.expected_version === null ||
+ (typeof value.expected_version === "number" &&
+ Number.isSafeInteger(value.expected_version) &&
+ value.expected_version >= 0)
+ )
+ )
+ return null
+ if (typeof value.goal !== "string" || !Array.isArray(value.steps)) return null
+ if (!(value.active_step_id === null || typeof value.active_step_id === "string")) return null
+ if (value.replan_reason !== undefined && typeof value.replan_reason !== "string") return null
+ if (
+ value.assumptions !== undefined &&
+ (!Array.isArray(value.assumptions) || value.assumptions.some((item) => typeof item !== "string"))
+ ) {
+ return null
+ }
+ const steps = value.steps.map((step) => {
+ if (!isRecord(step) || typeof step.title !== "string" || typeof step.status !== "string") return null
+ if (step.step_id !== undefined && typeof step.step_id !== "string") return null
+ if (step.acceptance !== undefined && step.acceptance !== null && typeof step.acceptance !== "string") return null
+ if (step.assigned_agent !== undefined && step.assigned_agent !== null && typeof step.assigned_agent !== "string")
+ return null
+ if (step.note !== undefined && step.note !== null && typeof step.note !== "string") return null
+ return {
+ ...(typeof step.step_id === "string" ? { step_id: step.step_id } : {}),
+ title: step.title,
+ status: step.status as PlanWriteStatus,
+ ...(step.acceptance !== undefined ? { acceptance: step.acceptance as string | null } : {}),
+ ...(step.assigned_agent !== undefined ? { assigned_agent: step.assigned_agent as string | null } : {}),
+ ...(step.note !== undefined ? { note: step.note as string | null } : {}),
+ }
+ })
+ if (steps.some((step) => step == null)) return null
+ return {
+ operation: value.operation,
+ expected_plan_id: value.expected_plan_id,
+ expected_version: value.expected_version,
+ ...(typeof value.replan_reason === "string" ? { replan_reason: value.replan_reason } : {}),
+ goal: value.goal,
+ ...(Array.isArray(value.assumptions) ? { assumptions: value.assumptions as string[] } : {}),
+ steps: steps.filter((step): step is NonNullable => step != null),
+ active_step_id: value.active_step_id,
+ }
+}
+
+export type PlanValidationCode =
+ | "invalid_operation"
+ | "invalid_precondition"
+ | "plan_already_exists"
+ | "plan_missing"
+ | "replan_reason_required"
+ | "invalid_replan_reason"
+ | "empty_goal"
+ | "empty_steps"
+ | "empty_title"
+ | "invalid_status"
+ | "duplicate_step_id"
+ | "invalid_active_step"
+ | "multiple_active_steps"
+ | "blocked_without_note"
+ | "unsafe_step_identity"
+ | "suspicious_quality_regression"
+
+export class PlanValidationError extends Error {
+ readonly _tag = "PlanValidationError"
+ override readonly name = "PlanValidationError"
+
+ constructor(
+ readonly code: PlanValidationCode,
+ readonly offending_step_ids: readonly string[] = [],
+ readonly previous_plan_id: string | null = null,
+ readonly previous_plan_version: number | null = null,
+ readonly attempt_ordinal = 0,
+ readonly candidate_hash?: string,
+ readonly challenge_id?: string,
+ ) {
+ super(`Plan validation failed: ${code}`)
+ }
+}
+
+export type PlanExpected = { readonly plan_id: string; readonly doc_id: string; readonly version: number }
+export type PlanActual = { readonly plan_id: string; readonly doc_id: string; readonly version: number } | null
+
+export class PlanConflictError extends Error {
+ readonly _tag = "PlanConflictError"
+ override readonly name = "PlanConflictError"
+
+ constructor(
+ readonly expected: PlanExpected | null,
+ readonly actual: PlanActual,
+ ) {
+ super("Plan compare-and-commit precondition did not match the authoritative version")
+ }
+}
+
+const normalizeStatus = (status: string): PlanStepStatus | undefined => {
+ const normalized = status.trim().toLowerCase()
+ if (STEP_STATUSES.has(normalized as PlanStepStatus)) return normalized as PlanStepStatus
+ return STATUS_ALIASES[normalized]
+}
+
+const normalizedText = (value: string | null | undefined): string => (value ?? "").trim()
+
+const planTextSize = (plan: PlanDoc): number =>
+ plan.steps.reduce(
+ (total, step) => total + [...normalizedText(step.title)].length + [...normalizedText(step.acceptance)].length,
+ 0,
+ )
+
+const unresolved = (step: PlanStep): boolean => step.status === "pending" || step.status === "active"
+
+const hasSameIdentity = (left: PlanStep, right: PlanStep): boolean =>
+ normalizedText(left.title) === normalizedText(right.title) &&
+ normalizedText(left.acceptance) === normalizedText(right.acceptance)
+
+export const planWriteCandidateHash = (input: PlanWriteInput): string =>
+ `sha256:${createHash("sha256")
+ .update(
+ JSON.stringify({
+ operation: input.operation,
+ expected_plan_id: input.expected_plan_id,
+ expected_version: input.expected_version,
+ replan_reason: normalizedText(input.replan_reason),
+ goal: normalizedText(input.goal),
+ assumptions: (input.assumptions ?? []).map(normalizedText),
+ active_step_id: input.active_step_id,
+ steps: input.steps.map((step) => ({
+ step_id: normalizedText(step.step_id) || null,
+ title: normalizedText(step.title),
+ status: normalizedText(step.status).toLowerCase(),
+ acceptance: normalizedText(step.acceptance) || null,
+ assigned_agent: normalizedText(step.assigned_agent) || null,
+ note: normalizedText(step.note) || null,
+ })),
+ }),
+ )
+ .digest("hex")}`
+
+const qualityRegression = (previous: PlanDoc, candidate: PlanDoc): boolean => {
+ const previousUnresolved = previous.steps.filter(unresolved)
+ const candidateUnresolved = candidate.steps.filter(unresolved)
+ const previousChars = planTextSize(previous)
+ const candidateChars = planTextSize(candidate)
+ const previousAcceptanceSteps = previousUnresolved.filter((step) => normalizedText(step.acceptance) !== "")
+ const candidateAcceptanceSteps = candidateUnresolved.filter((step) => normalizedText(step.acceptance) !== "")
+ const candidateById = new Map(candidateUnresolved.map((step) => [step.step_id, step] as const))
+ const preservesAcceptanceIdentity = previousAcceptanceSteps.some((step) => {
+ const next = candidateById.get(step.step_id)
+ return next != null && hasSameIdentity(step, next)
+ })
+
+ if (previous.steps.length >= 2 && candidate.steps.length <= Math.floor(previous.steps.length / 2)) {
+ if (candidateChars * 2 < previousChars) return true
+ }
+ if (previousAcceptanceSteps.length >= 2 && candidateAcceptanceSteps.length === 0 && !preservesAcceptanceIdentity)
+ return true
+ if (
+ previousUnresolved.length >= 2 &&
+ candidateUnresolved.every((step) => !previous.steps.some((prior) => prior.step_id === step.step_id))
+ ) {
+ if (candidate.steps.reduce((total, step) => total + [...normalizedText(step.title)].length, 0) < 16) return true
+ }
+ return false
+}
+
+export const planProgressFingerprint = (plan: PlanDoc): string =>
+ JSON.stringify({
+ plan_id: plan.plan_id,
+ goal: normalizedText(plan.goal),
+ assumptions: plan.assumptions.map(normalizedText),
+ replan_reason: normalizedText(plan.replan_reason),
+ last_write_activity_id: plan.last_write_activity_id ?? null,
+ active_step_id: plan.active_step_id,
+ steps: plan.steps.map((step) => ({
+ step_id: step.step_id,
+ title: normalizedText(step.title),
+ acceptance: normalizedText(step.acceptance),
+ assigned_agent: normalizedText(step.assigned_agent),
+ status: step.status,
+ note: normalizedText(step.note),
+ evidence: [...(step.evidence ?? [])],
+ })),
+ })
+
+const requireExpected = (input: PlanWriteInput, previous: PlanDoc | null, ref: PlanExpected | null): void => {
+ if (input.operation === "create") {
+ if (input.expected_plan_id !== null || input.expected_version !== null) {
+ throw new PlanValidationError("invalid_precondition", [], previous?.plan_id ?? null, ref?.version ?? null)
+ }
+ if (previous != null)
+ throw new PlanValidationError("plan_already_exists", [], previous.plan_id, ref?.version ?? null)
+ return
+ }
+ if (previous == null || ref == null) {
+ throw new PlanValidationError("plan_missing")
+ }
+ if (
+ input.expected_plan_id !== previous.plan_id ||
+ input.expected_version !== ref.version ||
+ input.expected_plan_id == null ||
+ input.expected_version == null
+ ) {
+ throw new PlanConflictError(
+ input.expected_plan_id != null && input.expected_version != null
+ ? { plan_id: input.expected_plan_id, doc_id: ref.doc_id, version: input.expected_version }
+ : null,
+ { plan_id: previous.plan_id, doc_id: ref.doc_id, version: ref.version },
+ )
+ }
+}
+
+export const buildPlanFromWriteInput = (
+ sessionId: string,
+ input: PlanWriteInput,
+ previous: PlanDoc | null,
+ ref: PlanExpected | null,
+ options: { readonly allowQualityRegression?: boolean } = {},
+): PlanDoc => {
+ if (!("create" === input.operation || "advance" === input.operation || "replan" === input.operation)) {
+ throw new PlanValidationError("invalid_operation")
+ }
+ requireExpected(input, previous, ref)
+ if (normalizedText(input.goal) === "")
+ throw new PlanValidationError("empty_goal", [], previous?.plan_id ?? null, ref?.version ?? null)
+ if (input.steps.length === 0)
+ throw new PlanValidationError("empty_steps", [], previous?.plan_id ?? null, ref?.version ?? null)
+ if (input.operation === "replan") {
+ const reason = normalizedText(input.replan_reason)
+ if (reason === "")
+ throw new PlanValidationError("replan_reason_required", [], previous?.plan_id ?? null, ref?.version ?? null)
+ if ([...reason].length > 512)
+ throw new PlanValidationError("invalid_replan_reason", [], previous?.plan_id ?? null, ref?.version ?? null)
+ }
+
+ const priorById = new Map((previous?.steps ?? []).map((step) => [step.step_id, step] as const))
+ if (input.operation === "advance" && previous != null) {
+ const previousIds = previous.steps.map((step) => step.step_id)
+ const suppliedIds = input.steps.map((step) => normalizedText(step.step_id))
+ const suppliedAssumptions = (input.assumptions ?? previous.assumptions).map((value) => value.trim())
+ if (
+ suppliedIds.length !== previousIds.length ||
+ suppliedIds.some((stepID, index) => stepID === "" || stepID !== previousIds[index]) ||
+ normalizedText(input.goal) !== normalizedText(previous.goal) ||
+ JSON.stringify(suppliedAssumptions) !== JSON.stringify(previous.assumptions.map((value) => value.trim()))
+ ) {
+ throw new PlanValidationError(
+ "unsafe_step_identity",
+ suppliedIds.filter(Boolean),
+ previous.plan_id,
+ ref?.version ?? null,
+ )
+ }
+ }
+ const used = new Set()
+ const steps = input.steps.map((step) => {
+ if (normalizedText(step.title) === "") {
+ throw new PlanValidationError("empty_title", [], previous?.plan_id ?? null, ref?.version ?? null)
+ }
+ const status = normalizeStatus(step.status)
+ if (!status) throw new PlanValidationError("invalid_status", [], previous?.plan_id ?? null, ref?.version ?? null)
+ const suppliedID = normalizedText(step.step_id)
+ if (input.operation === "advance" && suppliedID === "") {
+ throw new PlanValidationError("unsafe_step_identity", [], previous?.plan_id ?? null, ref?.version ?? null)
+ }
+ const stepID = suppliedID || `step_${randomUUID()}`
+ if (used.has(stepID))
+ throw new PlanValidationError("duplicate_step_id", [stepID], previous?.plan_id ?? null, ref?.version ?? null)
+ used.add(stepID)
+ const prior = priorById.get(stepID)
+ if (input.operation === "advance" && prior == null) {
+ throw new PlanValidationError("unsafe_step_identity", [stepID], previous?.plan_id ?? null, ref?.version ?? null)
+ }
+ if (input.operation === "advance" && prior != null) {
+ if (
+ normalizedText(prior.title) !== normalizedText(step.title) ||
+ normalizedText(prior.acceptance) !== normalizedText(step.acceptance) ||
+ normalizedText(prior.assigned_agent) !== normalizedText(step.assigned_agent)
+ ) {
+ throw new PlanValidationError("unsafe_step_identity", [stepID], previous?.plan_id ?? null, ref?.version ?? null)
+ }
+ }
+ if (
+ input.operation === "replan" &&
+ prior != null &&
+ suppliedID !== "" &&
+ (normalizedText(prior.title) !== normalizedText(step.title) ||
+ normalizedText(prior.acceptance) !== normalizedText(step.acceptance) ||
+ normalizedText(prior.assigned_agent) !== normalizedText(step.assigned_agent))
+ ) {
+ throw new PlanValidationError("unsafe_step_identity", [stepID], previous?.plan_id ?? null, ref?.version ?? null)
+ }
+ const sameIdentity = prior != null && hasSameIdentity(prior, { ...step, step_id: stepID, status })
+ return {
+ step_id: stepID,
+ title: normalizedText(step.title),
+ status,
+ acceptance: normalizedText(step.acceptance) || null,
+ assigned_agent: normalizedText(step.assigned_agent) || null,
+ evidence: sameIdentity ? [...(prior.evidence ?? [])] : [],
+ note: normalizedText(step.note) || null,
+ }
+ })
+ const active = steps.filter((step) => step.status === "active")
+ if (active.length > 1)
+ throw new PlanValidationError(
+ "multiple_active_steps",
+ active.map((step) => step.step_id),
+ )
+ if (input.active_step_id !== null && !used.has(input.active_step_id)) {
+ throw new PlanValidationError("invalid_active_step", [input.active_step_id])
+ }
+ if (
+ (input.active_step_id === null && active.length > 0) ||
+ (input.active_step_id !== null && active[0]?.step_id !== input.active_step_id)
+ ) {
+ throw new PlanValidationError(
+ "invalid_active_step",
+ input.active_step_id ? [input.active_step_id] : active.map((step) => step.step_id),
+ )
+ }
+ const blocked = steps.filter((step) => step.status === "blocked" && normalizedText(step.note) === "")
+ if (blocked.length > 0)
+ throw new PlanValidationError(
+ "blocked_without_note",
+ blocked.map((step) => step.step_id),
+ )
+
+ const candidate: PlanDoc = {
+ plan_id: previous?.plan_id ?? `plan_${randomUUID()}`,
+ session_id: sessionId,
+ goal: normalizedText(input.goal),
+ assumptions: (input.assumptions ?? (input.operation === "advance" ? previous?.assumptions : []) ?? []).map(
+ (value) => value.trim(),
+ ),
+ steps,
+ active_step_id: input.active_step_id,
+ replan_reason:
+ input.operation === "replan" ? normalizedText(input.replan_reason) : (previous?.replan_reason ?? null),
+ last_write_activity_id: null,
+ created_at: previous?.created_at ?? new Date().toISOString(),
+ }
+ if (
+ input.operation === "replan" &&
+ previous != null &&
+ !options.allowQualityRegression &&
+ qualityRegression(previous, candidate)
+ ) {
+ throw new PlanValidationError(
+ "suspicious_quality_regression",
+ candidate.steps.map((step) => step.step_id),
+ previous.plan_id,
+ ref?.version ?? null,
+ 0,
+ planWriteCandidateHash(input),
+ randomUUID(),
+ )
+ }
+ return candidate
+}
+
const normStatus = (s: string | undefined): PlanStepStatus => {
const status = s?.trim().toLowerCase()
if (!status) return "pending"
@@ -365,14 +762,17 @@ export const formatStepChange = (c: StepStatusChange): string =>
c.from === null ? `${c.title}: →${c.to}` : `${c.title}: ${c.from}→${c.to}`
// Compact, constant-size plan snapshot re-injected into context each turn (high+ only) so the model
-// can SEE its own checklist and report against it. One line per step; goal + progress header. We
-// deliberately omit acceptance/assumptions/evidence to keep this small (it is re-injected every
-// turn, so it must not grow with history).
-export const renderPlanSnapshot = (plan: PlanDoc): string => {
+// can SEE its own checklist and report against it. One line per step; the full form includes goal +
+// progress, while tool continuations omit the already-adjacent goal. We deliberately omit
+// acceptance/assumptions/evidence so it cannot grow with history.
+export const renderPlanSnapshot = (plan: PlanDoc, detail: "full" | "continuation" = "full"): string => {
const { done, total } = planProgress(plan)
const active = plan.steps.find((s) => s.step_id === plan.active_step_id) ?? null
const lines = plan.steps.map((s) => `[${STATUS_MARK[s.status]}] ${s.title}`)
- const header = `Current plan (${done}/${total} done) — goal: ${plan.goal}`
+ const header =
+ detail === "continuation"
+ ? `Current plan (${done}/${total} done)`
+ : `Current plan (${done}/${total} done) — goal: ${plan.goal}`
const activeLine = active ? `Active step: ${active.title}` : "No step is marked active."
return `${header}\n${lines.join("\n")}\n${activeLine}`
}
@@ -460,5 +860,3 @@ export const attachEvidenceToNewlyDone = (
})
return changed ? { ...next, steps } : next
}
-
-
diff --git a/packages/core/src/deepagent/plan-edit-protocol.ts b/packages/core/src/deepagent/plan-edit-protocol.ts
new file mode 100644
index 00000000..d9260656
--- /dev/null
+++ b/packages/core/src/deepagent/plan-edit-protocol.ts
@@ -0,0 +1,515 @@
+import { randomUUID } from "node:crypto"
+import { DocumentConflictError, type DocumentStore } from "./document-store"
+import {
+ type PlanConflictError,
+ type PlanValidationCode,
+ type PlanValidationError,
+ type PlanWriteInput,
+ decodePlanWriteInput,
+ planScope,
+ planWriteCandidateHash,
+} from "./plan-controller"
+
+export const PLAN_EDIT_PROTOCOL_VERSION = 1 as const
+export const PLAN_EDIT_CHALLENGE_TTL_MS = 15 * 60 * 1000
+
+export type PlanEditCommand = {
+ readonly protocol_version: typeof PLAN_EDIT_PROTOCOL_VERSION
+ readonly activity_id: string
+ readonly request_id: string
+ readonly session_id: string
+ readonly goal_id: string
+ readonly admitted_at: string
+ readonly candidate_hash: string
+ readonly plan_write: PlanWriteInput
+ readonly confirmed_challenge_id?: string
+}
+
+export type PlanEditChallenge = {
+ readonly challenge_id: string
+ readonly candidate_hash: string
+ readonly expected_plan_id: string
+ readonly expected_version: number
+ readonly issued_at: string
+ readonly expires_at: string
+}
+
+export type PlanEditFailure =
+ | {
+ readonly kind: "validation"
+ readonly code: PlanValidationCode
+ readonly offending_step_ids: readonly string[]
+ readonly previous_plan_id: string | null
+ readonly previous_plan_version: number | null
+ }
+ | {
+ readonly kind: "conflict"
+ readonly expected_plan_id: string | null
+ readonly expected_version: number | null
+ readonly actual_plan_id: string | null
+ readonly actual_version: number | null
+ }
+ | { readonly kind: "target_unavailable"; readonly message: string }
+ | { readonly kind: "runtime_error"; readonly message: string }
+
+export type PlanEditReceipt = {
+ readonly protocol_version: typeof PLAN_EDIT_PROTOCOL_VERSION
+ readonly state: "challenged" | "queued" | "applied" | "rejected" | "conflict" | "runtime_error"
+ readonly command: PlanEditCommand
+ readonly updated_at: string
+ readonly challenge?: PlanEditChallenge
+ readonly result?: {
+ readonly plan_id: string
+ readonly doc_id: string
+ readonly version: number
+ readonly changed: boolean
+ }
+ readonly failure?: PlanEditFailure
+}
+
+export type PlanEditSettlement =
+ | {
+ readonly state: "applied"
+ readonly result: NonNullable
+ }
+ | { readonly state: "rejected" | "conflict" | "runtime_error"; readonly failure: PlanEditFailure }
+
+export class PlanEditBusyError extends Error {
+ readonly _tag = "PlanEditBusyError"
+ override readonly name = "PlanEditBusyError"
+
+ constructor(readonly activity_id: string) {
+ super(`A plan edit is already queued: ${activity_id}`)
+ }
+}
+
+export class PlanEditChallengeError extends Error {
+ readonly _tag = "PlanEditChallengeError"
+ override readonly name = "PlanEditChallengeError"
+
+ constructor(readonly reason: "missing" | "mismatch" | "expired" | "consumed") {
+ super(`Plan edit quality challenge is ${reason}`)
+ }
+}
+
+export class PlanEditMailboxConflictError extends Error {
+ readonly _tag = "PlanEditMailboxConflictError"
+ override readonly name = "PlanEditMailboxConflictError"
+
+ constructor() {
+ super("Plan edit mailbox changed concurrently; reload the plan and retry")
+ }
+}
+
+export class PlanEditRequestConflictError extends Error {
+ readonly _tag = "PlanEditRequestConflictError"
+ override readonly name = "PlanEditRequestConflictError"
+
+ constructor(readonly request_id: string) {
+ super(`Plan edit request id was already used with different content: ${request_id}`)
+ }
+}
+
+export class PlanEditProtocolCorruptionError extends Error {
+ readonly _tag = "PlanEditProtocolCorruptionError"
+ override readonly name = "PlanEditProtocolCorruptionError"
+
+ constructor(readonly doc_id: string) {
+ super(`Plan edit mailbox is malformed: ${doc_id}`)
+ }
+}
+
+export class PlanEditTargetUnavailableError extends Error {
+ readonly _tag = "PlanEditTargetUnavailableError"
+ override readonly name = "PlanEditTargetUnavailableError"
+
+ constructor(readonly reason: string) {
+ super(`Plan edit target is unavailable: ${reason}`)
+ }
+}
+
+const isRecord = (value: unknown): value is Record =>
+ typeof value === "object" && value !== null && !Array.isArray(value)
+
+const isNonEmptyString = (value: unknown): value is string => typeof value === "string" && value.trim() !== ""
+
+const isTimestamp = (value: unknown): value is string => isNonEmptyString(value) && Number.isFinite(Date.parse(value))
+
+const PLAN_EDIT_STATES = new Set([
+ "challenged",
+ "queued",
+ "applied",
+ "rejected",
+ "conflict",
+ "runtime_error",
+])
+
+const PLAN_VALIDATION_CODES = new Set([
+ "invalid_operation",
+ "invalid_precondition",
+ "plan_already_exists",
+ "plan_missing",
+ "replan_reason_required",
+ "invalid_replan_reason",
+ "empty_goal",
+ "empty_steps",
+ "empty_title",
+ "invalid_status",
+ "duplicate_step_id",
+ "invalid_active_step",
+ "multiple_active_steps",
+ "blocked_without_note",
+ "unsafe_step_identity",
+ "suspicious_quality_regression",
+])
+
+const isPlanEditState = (value: unknown): value is PlanEditReceipt["state"] =>
+ typeof value === "string" && PLAN_EDIT_STATES.has(value as PlanEditReceipt["state"])
+
+const isPlanValidationCode = (value: unknown): value is PlanValidationCode =>
+ typeof value === "string" && PLAN_VALIDATION_CODES.has(value as PlanValidationCode)
+
+const isNullableString = (value: unknown): value is string | null => value === null || typeof value === "string"
+
+const isNullableVersion = (value: unknown): value is number | null =>
+ value === null || (typeof value === "number" && Number.isSafeInteger(value) && value >= 0)
+
+const decodeCommand = (value: unknown): PlanEditCommand | null => {
+ if (!isRecord(value) || value.protocol_version !== PLAN_EDIT_PROTOCOL_VERSION) return null
+ if (!isNonEmptyString(value.activity_id) || !isNonEmptyString(value.request_id)) return null
+ if (!isNonEmptyString(value.session_id) || !isNonEmptyString(value.goal_id) || !isTimestamp(value.admitted_at)) return null
+ if (typeof value.candidate_hash !== "string" || !/^sha256:[a-f0-9]{64}$/.test(value.candidate_hash)) return null
+ if (value.confirmed_challenge_id !== undefined && !isNonEmptyString(value.confirmed_challenge_id)) return null
+ const planWrite = decodePlanWriteInput(value.plan_write)
+ if (!planWrite || planWriteCandidateHash(planWrite) !== value.candidate_hash) return null
+ return {
+ protocol_version: PLAN_EDIT_PROTOCOL_VERSION,
+ activity_id: value.activity_id,
+ request_id: value.request_id,
+ session_id: value.session_id,
+ goal_id: value.goal_id,
+ admitted_at: value.admitted_at,
+ candidate_hash: value.candidate_hash,
+ plan_write: planWrite,
+ ...(typeof value.confirmed_challenge_id === "string"
+ ? { confirmed_challenge_id: value.confirmed_challenge_id }
+ : {}),
+ }
+}
+
+const decodeChallenge = (value: unknown): PlanEditChallenge | null => {
+ if (!isRecord(value)) return null
+ if (!isNonEmptyString(value.challenge_id) || !isNonEmptyString(value.candidate_hash)) return null
+ if (!/^sha256:[a-f0-9]{64}$/.test(value.candidate_hash)) return null
+ if (!isNonEmptyString(value.expected_plan_id)) return null
+ if (typeof value.expected_version !== "number" || !Number.isSafeInteger(value.expected_version) || value.expected_version < 0) {
+ return null
+ }
+ if (!isTimestamp(value.issued_at) || !isTimestamp(value.expires_at)) return null
+ if (Date.parse(value.expires_at) <= Date.parse(value.issued_at)) return null
+ return {
+ challenge_id: value.challenge_id,
+ candidate_hash: value.candidate_hash,
+ expected_plan_id: value.expected_plan_id,
+ expected_version: value.expected_version,
+ issued_at: value.issued_at,
+ expires_at: value.expires_at,
+ }
+}
+
+const decodeFailure = (value: unknown): PlanEditFailure | null => {
+ if (!isRecord(value) || typeof value.kind !== "string") return null
+ if (value.kind === "validation") {
+ if (!isPlanValidationCode(value.code) || !Array.isArray(value.offending_step_ids)) return null
+ if (!value.offending_step_ids.every((item) => typeof item === "string")) return null
+ if (!isNullableString(value.previous_plan_id) || !isNullableVersion(value.previous_plan_version)) return null
+ return {
+ kind: "validation",
+ code: value.code,
+ offending_step_ids: value.offending_step_ids,
+ previous_plan_id: value.previous_plan_id,
+ previous_plan_version: value.previous_plan_version,
+ }
+ }
+ if (value.kind === "conflict") {
+ if (!isNullableString(value.expected_plan_id) || !isNullableString(value.actual_plan_id)) return null
+ if (!isNullableVersion(value.expected_version) || !isNullableVersion(value.actual_version)) return null
+ return {
+ kind: "conflict",
+ expected_plan_id: value.expected_plan_id,
+ expected_version: value.expected_version,
+ actual_plan_id: value.actual_plan_id,
+ actual_version: value.actual_version,
+ }
+ }
+ if (value.kind === "target_unavailable" || value.kind === "runtime_error") {
+ if (!isNonEmptyString(value.message)) return null
+ return { kind: value.kind, message: value.message }
+ }
+ return null
+}
+
+export const decodePlanEditReceipt = (value: unknown): PlanEditReceipt | null => {
+ if (!isRecord(value) || value.protocol_version !== PLAN_EDIT_PROTOCOL_VERSION) return null
+ if (!isPlanEditState(value.state)) return null
+ const command = decodeCommand(value.command)
+ if (!command || !isTimestamp(value.updated_at)) return null
+ const challenge = value.challenge === undefined ? undefined : decodeChallenge(value.challenge)
+ if (value.state === "challenged" && !challenge) return null
+ if (value.state !== "challenged" && value.challenge !== undefined) return null
+ const result = isRecord(value.result)
+ ? typeof value.result.plan_id === "string" &&
+ typeof value.result.doc_id === "string" &&
+ typeof value.result.version === "number" &&
+ typeof value.result.changed === "boolean"
+ ? {
+ plan_id: value.result.plan_id,
+ doc_id: value.result.doc_id,
+ version: value.result.version,
+ changed: value.result.changed,
+ }
+ : null
+ : undefined
+ const failure = value.failure === undefined ? undefined : decodeFailure(value.failure)
+ if (value.state === "applied" && !result) return null
+ if (value.state !== "applied" && value.result !== undefined) return null
+ if (value.state === "rejected" && !(failure?.kind === "validation" || failure?.kind === "target_unavailable")) return null
+ if (value.state === "conflict" && failure?.kind !== "conflict") return null
+ if (value.state === "runtime_error" && failure?.kind !== "runtime_error") return null
+ if ((value.state === "challenged" || value.state === "queued" || value.state === "applied") && value.failure !== undefined) return null
+ return {
+ protocol_version: PLAN_EDIT_PROTOCOL_VERSION,
+ state: value.state,
+ command,
+ updated_at: value.updated_at,
+ ...(challenge ? { challenge } : {}),
+ ...(result ? { result } : {}),
+ ...(failure ? { failure } : {}),
+ }
+}
+
+const mailboxSlug = (goalID: string): string => `goal-plan-edit-mailbox-${goalID}`
+
+const resolveMailbox = (store: DocumentStore, sessionID: string, goalID: string) => {
+ const refs = store
+ .list({ type: "run_context", scope: planScope(sessionID) })
+ .filter((candidate) => store.get(candidate.id)?.extensions?.plan_edit_goal_id === goalID)
+ if (refs.length > 1) throw new PlanEditProtocolCorruptionError(refs.map((ref) => ref.id).join(","))
+ const doc = refs[0] ? store.get(refs[0].id) : null
+ if (!doc) return null
+ let value: unknown
+ try {
+ value = JSON.parse(doc.body)
+ } catch {
+ throw new PlanEditProtocolCorruptionError(doc.id)
+ }
+ const receipt = decodePlanEditReceipt(value)
+ if (!receipt || receipt.command.session_id !== sessionID || receipt.command.goal_id !== goalID) {
+ throw new PlanEditProtocolCorruptionError(doc.id)
+ }
+ return { doc, receipt }
+}
+
+export const readPlanEditReceipt = (store: DocumentStore, sessionID: string, goalID: string): PlanEditReceipt | null =>
+ resolveMailbox(store, sessionID, goalID)?.receipt ?? null
+
+export const readPlanEditReceiptByRequest = (
+ store: DocumentStore,
+ sessionID: string,
+ goalID: string,
+ requestID: string,
+): PlanEditReceipt | null => {
+ const mailbox = resolveMailbox(store, sessionID, goalID)
+ if (!mailbox) return null
+ for (let version = mailbox.doc.version; version > 0; version--) {
+ const doc = store.get(mailbox.doc.id, version)
+ if (!doc) throw new PlanEditProtocolCorruptionError(`${mailbox.doc.id}@v${version}`)
+ let value: unknown
+ try {
+ value = JSON.parse(doc.body)
+ } catch {
+ throw new PlanEditProtocolCorruptionError(`${mailbox.doc.id}@v${version}`)
+ }
+ const receipt = decodePlanEditReceipt(value)
+ if (!receipt || receipt.command.session_id !== sessionID || receipt.command.goal_id !== goalID) {
+ throw new PlanEditProtocolCorruptionError(`${mailbox.doc.id}@v${version}`)
+ }
+ if (receipt.command.request_id === requestID) return receipt
+ }
+ return null
+}
+
+export const readPendingPlanEditCommand = (
+ store: DocumentStore,
+ sessionID: string,
+ goalID: string,
+): PlanEditCommand | null => {
+ const receipt = readPlanEditReceipt(store, sessionID, goalID)
+ return receipt?.state === "queued" ? receipt.command : null
+}
+
+const writeReceipt = (store: DocumentStore, receipt: PlanEditReceipt): PlanEditReceipt => {
+ const current = resolveMailbox(store, receipt.command.session_id, receipt.command.goal_id)
+ try {
+ store.upsert({
+ type: "run_context",
+ scope: planScope(receipt.command.session_id),
+ description: current?.doc.description ?? `goal plan edit mailbox ${receipt.command.goal_id}`,
+ idSlug: mailboxSlug(receipt.command.goal_id),
+ body: JSON.stringify(receipt),
+ provenance: { source: "human", run_ref: planScope(receipt.command.session_id) },
+ extensions: {
+ plan_edit_goal_id: receipt.command.goal_id,
+ plan_edit_protocol_version: PLAN_EDIT_PROTOCOL_VERSION,
+ },
+ })
+ return receipt
+ } catch (error) {
+ if (!(error instanceof DocumentConflictError)) throw error
+ store.rebuildIndex()
+ throw new PlanEditMailboxConflictError()
+ }
+}
+
+export const createPlanEditCommand = (input: {
+ readonly requestID: string
+ readonly sessionID: string
+ readonly goalID: string
+ readonly planWrite: PlanWriteInput
+ readonly now?: Date
+ readonly confirmedChallengeID?: string
+}): PlanEditCommand => ({
+ protocol_version: PLAN_EDIT_PROTOCOL_VERSION,
+ activity_id: randomUUID(),
+ request_id: input.requestID,
+ session_id: input.sessionID,
+ goal_id: input.goalID,
+ admitted_at: (input.now ?? new Date()).toISOString(),
+ candidate_hash: planWriteCandidateHash(input.planWrite),
+ plan_write: input.planWrite,
+ ...(input.confirmedChallengeID ? { confirmed_challenge_id: input.confirmedChallengeID } : {}),
+})
+
+const reconcileRequestRetry = (store: DocumentStore, command: PlanEditCommand): PlanEditReceipt | null => {
+ const receipt = readPlanEditReceiptByRequest(store, command.session_id, command.goal_id, command.request_id)
+ if (!receipt) return null
+ if (receipt.command.candidate_hash === command.candidate_hash) return receipt
+ throw new PlanEditRequestConflictError(command.request_id)
+}
+
+export const admitPlanEditCommand = (
+ store: DocumentStore,
+ command: PlanEditCommand,
+ now = new Date(),
+): PlanEditReceipt => {
+ const retry = reconcileRequestRetry(store, command)
+ if (retry) return retry
+ const current = readPlanEditReceipt(store, command.session_id, command.goal_id)
+ if (current?.state === "queued") throw new PlanEditBusyError(current.command.activity_id)
+ if (command.confirmed_challenge_id) {
+ if (!current || current.state !== "challenged" || !current.challenge) throw new PlanEditChallengeError("missing")
+ if (current.challenge.challenge_id !== command.confirmed_challenge_id) throw new PlanEditChallengeError("mismatch")
+ if (
+ current.challenge.candidate_hash !== command.candidate_hash ||
+ current.challenge.expected_plan_id !== command.plan_write.expected_plan_id ||
+ current.challenge.expected_version !== command.plan_write.expected_version
+ ) {
+ throw new PlanEditChallengeError("mismatch")
+ }
+ if (Date.parse(current.challenge.expires_at) <= now.getTime()) throw new PlanEditChallengeError("expired")
+ }
+ return writeReceipt(store, {
+ protocol_version: PLAN_EDIT_PROTOCOL_VERSION,
+ state: "queued",
+ command,
+ updated_at: now.toISOString(),
+ })
+}
+
+export const issuePlanEditChallenge = (
+ store: DocumentStore,
+ command: PlanEditCommand,
+ challengeID: string,
+ now = new Date(),
+): PlanEditReceipt => {
+ const retry = reconcileRequestRetry(store, command)
+ if (retry) return retry
+ const current = readPlanEditReceipt(store, command.session_id, command.goal_id)
+ if (current?.state === "queued") throw new PlanEditBusyError(current.command.activity_id)
+ if (command.plan_write.expected_plan_id == null || command.plan_write.expected_version == null) {
+ throw new PlanEditChallengeError("mismatch")
+ }
+ return writeReceipt(store, {
+ protocol_version: PLAN_EDIT_PROTOCOL_VERSION,
+ state: "challenged",
+ command,
+ updated_at: now.toISOString(),
+ challenge: {
+ challenge_id: challengeID,
+ candidate_hash: command.candidate_hash,
+ expected_plan_id: command.plan_write.expected_plan_id,
+ expected_version: command.plan_write.expected_version,
+ issued_at: now.toISOString(),
+ expires_at: new Date(now.getTime() + PLAN_EDIT_CHALLENGE_TTL_MS).toISOString(),
+ },
+ })
+}
+
+export const settlePlanEditCommand = (
+ store: DocumentStore,
+ command: PlanEditCommand,
+ settlement: PlanEditSettlement,
+ now = new Date(),
+): PlanEditReceipt => {
+ const current = readPlanEditReceipt(store, command.session_id, command.goal_id)
+ if (current && current.command.activity_id === command.activity_id && current.state !== "queued") return current
+ if (!current || current.state !== "queued" || current.command.activity_id !== command.activity_id) {
+ throw new PlanEditMailboxConflictError()
+ }
+ if (settlement.state === "rejected" && !(settlement.failure.kind === "validation" || settlement.failure.kind === "target_unavailable")) {
+ throw new PlanEditProtocolCorruptionError(current.command.activity_id)
+ }
+ if (settlement.state === "conflict" && settlement.failure.kind !== "conflict") {
+ throw new PlanEditProtocolCorruptionError(current.command.activity_id)
+ }
+ if (settlement.state === "runtime_error" && settlement.failure.kind !== "runtime_error") {
+ throw new PlanEditProtocolCorruptionError(current.command.activity_id)
+ }
+ return writeReceipt(store, {
+ protocol_version: PLAN_EDIT_PROTOCOL_VERSION,
+ state: settlement.state,
+ command,
+ updated_at: now.toISOString(),
+ ...(settlement.state === "applied" ? { result: settlement.result } : { failure: settlement.failure }),
+ })
+}
+
+export const planEditFailure = (error: unknown): PlanEditFailure => {
+ const validation = error as Partial
+ if (validation._tag === "PlanValidationError" && validation.code) {
+ return {
+ kind: "validation",
+ code: validation.code,
+ offending_step_ids: validation.offending_step_ids ?? [],
+ previous_plan_id: validation.previous_plan_id ?? null,
+ previous_plan_version: validation.previous_plan_version ?? null,
+ }
+ }
+ const conflict = error as Partial
+ if (conflict._tag === "PlanConflictError") {
+ return {
+ kind: "conflict",
+ expected_plan_id: conflict.expected?.plan_id ?? null,
+ expected_version: conflict.expected?.version ?? null,
+ actual_plan_id: conflict.actual?.plan_id ?? null,
+ actual_version: conflict.actual?.version ?? null,
+ }
+ }
+ if (error instanceof PlanEditTargetUnavailableError) {
+ return { kind: "target_unavailable", message: error.message }
+ }
+ return {
+ kind: "runtime_error",
+ message: error instanceof Error ? error.message : "Unknown plan edit runtime failure",
+ }
+}
diff --git a/packages/core/src/deepagent/plan-store.ts b/packages/core/src/deepagent/plan-store.ts
index 50543a8c..6fc1152c 100644
--- a/packages/core/src/deepagent/plan-store.ts
+++ b/packages/core/src/deepagent/plan-store.ts
@@ -14,8 +14,16 @@
// visible to the goal driver and vice versa, with no second cache to drift. The shared index IS the
// hot cache: getPlanDoc is an in-memory Map lookup + a JSON.parse, not a disk read.
import path from "node:path"
-import { DocumentStore } from "./document-store"
-import type { PlanDoc } from "./plan-controller"
+import { DocumentConflictError, DocumentStore, type Provenance } from "./document-store"
+import {
+ PlanConflictError,
+ PlanValidationError,
+ type PlanDoc,
+ type PlanExpected,
+ type PlanStepStatus,
+ type PlanWriteOrigin,
+ planProgressFingerprint,
+} from "./plan-controller"
// The stable identity of a session's plan doc: type "plan", scope "run:", slug "plan-",
// description planDescription(sid). ALL FOUR must match between the `plan` tool path (setPlanDoc) and
@@ -49,6 +57,75 @@ export const planStoreRoot = (sessionId: string): string => {
// tool path, the goal driver, and the UI/archive readers all see one coherent in-memory index.
const store = (sessionId: string): DocumentStore => DocumentStore.shared(planStoreRoot(sessionId))
+const planStatuses = new Set(["pending", "active", "done", "cancelled", "blocked"])
+
+export const decodePlanDoc = (body: string): PlanDoc | null => {
+ let value: unknown
+ try {
+ value = JSON.parse(body)
+ } catch {
+ return null
+ }
+ if (!value || typeof value !== "object" || Array.isArray(value)) return null
+ const plan = value as Record
+ if (typeof plan.plan_id !== "string" || plan.plan_id.trim() === "") return null
+ if (typeof plan.session_id !== "string" || plan.session_id.trim() === "") return null
+ if (typeof plan.goal !== "string" || plan.goal.trim() === "") return null
+ if (!Array.isArray(plan.assumptions) || !plan.assumptions.every((item) => typeof item === "string")) return null
+ if (typeof plan.created_at !== "string" || plan.created_at.trim() === "") return null
+ if (
+ plan.replan_reason !== undefined &&
+ plan.replan_reason !== null &&
+ (typeof plan.replan_reason !== "string" ||
+ plan.replan_reason.trim() === "" ||
+ [...plan.replan_reason.trim()].length > 512)
+ ) {
+ return null
+ }
+ if (
+ plan.last_write_activity_id !== undefined &&
+ plan.last_write_activity_id !== null &&
+ (typeof plan.last_write_activity_id !== "string" || plan.last_write_activity_id.trim() === "")
+ ) {
+ return null
+ }
+ if (!Array.isArray(plan.steps) || plan.steps.length === 0) return null
+
+ const stepIDs = new Set()
+ const validSteps = plan.steps.every((value) => {
+ if (!value || typeof value !== "object" || Array.isArray(value)) return false
+ const step = value as Record
+ if (typeof step.step_id !== "string" || step.step_id.trim() === "" || stepIDs.has(step.step_id)) return false
+ stepIDs.add(step.step_id)
+ if (typeof step.title !== "string" || step.title.trim() === "") return false
+ if (typeof step.status !== "string" || !planStatuses.has(step.status as PlanStepStatus)) return false
+ if (step.acceptance !== undefined && step.acceptance !== null && typeof step.acceptance !== "string") return false
+ if (step.assigned_agent !== undefined && step.assigned_agent !== null && typeof step.assigned_agent !== "string")
+ return false
+ if (step.note !== undefined && step.note !== null && typeof step.note !== "string") return false
+ if (
+ step.evidence !== undefined &&
+ (!Array.isArray(step.evidence) || !step.evidence.every((item) => typeof item === "string"))
+ ) {
+ return false
+ }
+ if (step.status === "blocked" && (typeof step.note !== "string" || step.note.trim() === "")) return false
+ return true
+ })
+ if (!validSteps) return null
+
+ const active = plan.steps.filter((value) => (value as Record).status === "active") as Record<
+ string,
+ unknown
+ >[]
+ if (active.length > 1) return null
+ if (plan.active_step_id !== null && typeof plan.active_step_id !== "string") return null
+ if (typeof plan.active_step_id === "string" && !stepIDs.has(plan.active_step_id)) return null
+ if (plan.active_step_id === null && active.length > 0) return null
+ if (typeof plan.active_step_id === "string" && active[0]?.step_id !== plan.active_step_id) return null
+ return plan as PlanDoc
+}
+
// Resolve a session's plan doc ref. The doc id is NOT reconstructable from the slug — allocateId runs
// idSlug through slugify() (lowercase, `_`→`-`, truncate 48), so a raw `doc:plan:plan-` guess
// misses for realistic session ids. Instead resolve by (type "plan", scope "run:"): the plan-store
@@ -66,11 +143,7 @@ export const getPlanDoc = (sessionId: string): PlanDoc | null => {
if (!ref) return null
const doc = store(sessionId).get(ref.id)
if (!doc) return null
- try {
- return JSON.parse(doc.body) as PlanDoc
- } catch {
- return null
- }
+ return decodePlanDoc(doc.body)
}
// The doc id + current version for a session's plan (for the SessionRunState latch pointer), or null.
@@ -81,18 +154,112 @@ export const planDocRef = (sessionId: string): { id: string; version: number } |
return doc ? { id: doc.id, version: doc.version } : null
}
-// Write (create or new-version) the structural plan. Idempotent per session via upsert keyed on the
-// stable slug: an unchanged body is an INV-4 no-op (no version bump), a changed body appends a new
-// version (CAS-protected). Returns the resulting doc id + version so the caller can update the latch
-// pointer. This is the ONE write seam — the `plan` tool AND the goal path both call it.
+export type PlanCompareAndCommitInput = {
+ readonly sessionId: string
+ readonly expected: PlanExpected | null
+ readonly candidate: PlanDoc
+ readonly origin: PlanWriteOrigin
+}
+
+export type PlanCompareAndCommitResult = {
+ readonly plan: PlanDoc
+ readonly doc_id: string
+ readonly version: number
+ readonly changed: boolean
+}
+
+const provenanceFor = (origin: PlanWriteOrigin, sessionId: string): Provenance => ({
+ source: origin === "human_goal_edit" ? "human" : origin === "model_tool" ? "model" : "runner",
+ run_ref: planScope(sessionId),
+})
+
+const currentPlanFromStore = (
+ documentStore: DocumentStore,
+ sessionId: string,
+): { plan: PlanDoc; ref: { id: string; version: number } } | null => {
+ const refs = documentStore.list({ type: "plan", scope: planScope(sessionId) })
+ const ref = refs.length > 0 ? refs[0] : null
+ if (!ref) return null
+ const doc = documentStore.get(ref.id)
+ if (!doc) return null
+ const plan = decodePlanDoc(doc.body)
+ if (!plan) return null
+ return { plan, ref: { id: doc.id, version: doc.version } }
+}
+
+const actualExpected = (current: { plan: PlanDoc; ref: { id: string; version: number } } | null) =>
+ current ? { plan_id: current.plan.plan_id, doc_id: current.ref.id, version: current.ref.version } : null
+
+export const compareAndCommitPlanDocument = (
+ documentStore: DocumentStore,
+ input: PlanCompareAndCommitInput,
+): PlanCompareAndCommitResult => {
+ if (input.candidate.session_id !== input.sessionId || !decodePlanDoc(JSON.stringify(input.candidate))) {
+ throw new PlanValidationError("invalid_precondition")
+ }
+ const current = currentPlanFromStore(documentStore, input.sessionId)
+ const refs = documentStore.list({ type: "plan", scope: planScope(input.sessionId) })
+ if (refs.length > 0 && current == null) {
+ throw new PlanValidationError("invalid_precondition")
+ }
+ const actual = actualExpected(current)
+ if (input.expected == null) {
+ if (actual != null) throw new PlanConflictError(null, actual)
+ } else if (
+ actual == null ||
+ actual.plan_id !== input.expected.plan_id ||
+ actual.doc_id !== input.expected.doc_id ||
+ actual.version !== input.expected.version
+ ) {
+ throw new PlanConflictError(input.expected, actual)
+ }
+
+ if (current && planProgressFingerprint(current.plan) === planProgressFingerprint(input.candidate)) {
+ return { plan: current.plan, doc_id: current.ref.id, version: current.ref.version, changed: false }
+ }
+
+ try {
+ // Existing plan documents may have been created by the pre-I33-1 goal path with a different
+ // human-readable description. Preserve that document's logical identity while appending the
+ // next version; otherwise DocumentStore.upsert() would allocate a second plan doc instead of
+ // advancing the CAS-protected authority.
+ const currentDoc = current ? documentStore.get(current.ref.id) : null
+ const doc = documentStore.upsert({
+ type: "plan",
+ scope: planScope(input.sessionId),
+ description: currentDoc?.description ?? planDescription(input.sessionId),
+ idSlug: planSlug(input.sessionId),
+ body: JSON.stringify(input.candidate),
+ provenance: provenanceFor(input.origin, input.sessionId),
+ })
+ return { plan: input.candidate, doc_id: doc.id, version: doc.version, changed: true }
+ } catch (error) {
+ if (!(error instanceof DocumentConflictError)) throw error
+ documentStore.rebuildIndex()
+ const raced = currentPlanFromStore(documentStore, input.sessionId)
+ throw new PlanConflictError(input.expected, actualExpected(raced))
+ }
+}
+
+export const compareAndCommitPlan = (input: PlanCompareAndCommitInput): PlanCompareAndCommitResult =>
+ compareAndCommitPlanDocument(store(input.sessionId), input)
+
+// Write (create or new-version) the structural plan for legacy callers. It retains the historical API
+// shape, but still goes through strict structural decode, session binding, and a synchronous CAS. The
+// semantic admission layer remains the responsibility of production writers before they call this
+// compatibility seam; malformed or cross-session candidates are rejected at this final boundary.
export const setPlanDoc = (sessionId: string, plan: PlanDoc): { id: string; version: number } => {
- const doc = store(sessionId).upsert({
- type: "plan",
- scope: planScope(sessionId),
- description: planDescription(sessionId),
- idSlug: planSlug(sessionId),
- body: JSON.stringify(plan),
- provenance: { source: "model", run_ref: planScope(sessionId) },
+ if (plan.session_id !== sessionId || !decodePlanDoc(JSON.stringify(plan))) {
+ throw new PlanValidationError("invalid_precondition")
+ }
+ const current = getPlanDoc(sessionId)
+ const currentRef = planDocRef(sessionId)
+ const committed = compareAndCommitPlanDocument(store(sessionId), {
+ sessionId,
+ expected:
+ current && currentRef ? { plan_id: current.plan_id, doc_id: currentRef.id, version: currentRef.version } : null,
+ candidate: plan,
+ origin: "legacy_migration",
})
- return { id: doc.id, version: doc.version }
+ return { id: committed.doc_id, version: committed.version }
}
diff --git a/packages/core/src/deepagent/prompt-policy.ts b/packages/core/src/deepagent/prompt-policy.ts
index cff80ffe..c4c19a41 100644
--- a/packages/core/src/deepagent/prompt-policy.ts
+++ b/packages/core/src/deepagent/prompt-policy.ts
@@ -215,6 +215,21 @@ export const buildVolatileRoundContext = (ctx: PromptContext): string => {
return ["", body, " "].join("\n")
}
+// Tool continuations already have the current user request, assistant decision, tool call, and tool
+// result in adjacent durable history. Repeating the full activation/task/previous-results block after
+// every tool result makes that control block look like a fresh user request and can induce semantic
+// restatement loops. Keep only an explicit, constant-size continuation directive in the volatile tail;
+// live plan state is appended separately by the request layer.
+export const buildVolatileContinuationContext = (): string =>
+ [
+ "",
+ "# Tool continuation",
+ "",
+ "Continue directly from the immediately preceding tool result.",
+ "Apply runtime and plan control state silently. Do not restate or re-summarize the user request, the current phase, or conclusions already established unless the tool result materially changes them.",
+ " ",
+ ].join("\n")
+
const identitySection = (mode: AgentMode): string => {
// P2-1: ultra must not fall through to the High label. Each strength has its own label.
// NOTE (prompt-cache): mode is session-stable, but the round number is NOT — it now lives in
diff --git a/packages/core/src/deepagent/round-state.ts b/packages/core/src/deepagent/round-state.ts
index f3e05ba4..19d288db 100644
--- a/packages/core/src/deepagent/round-state.ts
+++ b/packages/core/src/deepagent/round-state.ts
@@ -1,12 +1,21 @@
import type { ActivationStage, AgentMode, RoundDecision, RunPhase } from "./mode"
+export type ValidationFailureKind =
+ | "command_exit"
+ | "shell_bootstrap_failed"
+ | "unsupported_platform"
+ | "unsupported_dialect"
+ | "timeout"
+ | "signal"
+ | "output_unavailable"
+
export type ValidationResult = {
readonly command: string
readonly passed: boolean
- // T1 (S1-v3.4): the raw process exit code, carried through for failure triage.
- // 127 = command not found, 126 = not executable, 124 = timeout, 137 = OOM/SIGKILL, etc.
- // These are the green/red dividing signals classifyFailure() needs; `passed` is still
- // exactly `exit_code === 0`, so existing assertions are unaffected.
+ // `kind` is authoritative. `exit_code` is the process code for command_exit and a diagnostic
+ // compatibility value for runner failures; classifiers must never infer transport failures from
+ // an exit code alone because user commands are allowed to return 124/126/127.
+ readonly kind: ValidationFailureKind
readonly exit_code: number
readonly output: string
readonly duration_ms: number
@@ -92,7 +101,10 @@ const stageForDecision = (decision: RoundDecision, current: ActivationStage): Ac
// on exit_code (not output text) for the same reason validationFingerprint is — output carries volatile
// noise (durations/timestamps) that must not make identical evidence look distinct.
const candidateEvidenceKey = (c: CandidateRef): string =>
- `${c.round}|${c.status}|${[...c.validations].map((v) => `${v.command}=${v.exit_code}`).sort().join(",")}`
+ `${c.round}|${c.status}|${[...c.validations]
+ .map((v) => `${v.command}=${v.kind}:${v.exit_code}`)
+ .sort()
+ .join(",")}`
export const addCandidate = (state: RoundState, candidate: CandidateRef): RoundState => {
// STALE-REHARVEST DEDUPE (single append site; covers BOTH the request-prep path and the micro-round
diff --git a/packages/core/src/deepagent/session-state.ts b/packages/core/src/deepagent/session-state.ts
index a807d4af..6d619a37 100644
--- a/packages/core/src/deepagent/session-state.ts
+++ b/packages/core/src/deepagent/session-state.ts
@@ -3,6 +3,7 @@ import { randomUUID } from "node:crypto"
import path from "node:path"
import { writeFileAtomic } from "./atomic-write"
import * as PlanStore from "./plan-store"
+import { DocumentStore } from "./document-store"
import type { AgentMode } from "./mode"
import {
createInitialRoundState,
@@ -25,6 +26,9 @@ import {
recordGateBlock,
resetGateBlocks,
planStatusesChanged,
+ planProgressFingerprint,
+ buildPlanFromWriteInput,
+ PlanValidationError,
type PlanLatchState,
type StaleReason,
type PlanDoc,
@@ -236,26 +240,52 @@ export const advanceToNextRound = (sessionId: string, decision: import("./mode")
// plan is exactly the "I updated the plan" event that clears a stale latch (and bumps replan_count
// via clearStale for the escape hatch). Binds the plan id to the latch.
export const setPlan = (sessionId: string, plan: PlanDoc): void => {
+ // Compatibility entry point for legacy callers and migration tests. Production writers must use
+ // PlanStore.compareAndCommitPlan followed by bindPlan; this fallback retains the historical API
+ // without allowing the new model-tool path to bypass admission.
+ const previous = getPlan(sessionId)
+ PlanStore.setPlanDoc(sessionId, plan)
+ bindPlan(sessionId, plan, previous, previous == null || planProgressFingerprint(previous) !== planProgressFingerprint(plan))
+}
+
+/** Bind a plan that has already passed PlanStore admission to the hot session latch. */
+export const bindPlan = (
+ sessionId: string,
+ plan: PlanDoc,
+ previousPlan: PlanDoc | null = getPlan(sessionId),
+ changed = true,
+): void => {
const state = sessions.get(sessionId)
if (!state) return
+ // A semantic no-op may still be the first time a pre-existing authority is adopted into the hot
+ // latch. Bind only the pointer in that case; it is not plan progress and must not clear a stale
+ // latch, bump replan_count, or reset reporting counters.
+ if (!changed) {
+ if (state.planLatch.plan_id === plan.plan_id) return
+ state.planLatch = { ...state.planLatch, plan_id: plan.plan_id }
+ saveToDisk()
+ return
+ }
// U10: reset the progress-nudge state ONLY when the model actually moved a step's status (or
// added a step). A no-op re-write leaves the counter/flag running so the nudge is not silenced by
- // an empty update ("report theater"). Compare against the CURRENT structural plan in the store.
- const previous = PlanStore.getPlanDoc(sessionId)
- if (planStatusesChanged(previous, plan)) {
+ // an empty update ("report theater"). The caller passes the pre-commit snapshot because the
+ // authoritative store already contains `plan` by the time this hot-state binding runs.
+ if (planStatusesChanged(previousPlan, plan)) {
state.mutationsSinceReport = 0
state.validationPassedSinceReport = false
}
- // I33-1: the plan body is written to the single DocumentStore authority (plan-store); session state
- // keeps only the latch pointer (plan_id). The store upsert is content-addressed + CAS-protected.
- PlanStore.setPlanDoc(sessionId, plan)
state.planLatch = clearStale({ ...state.planLatch, plan_id: plan.plan_id })
saveToDisk()
}
// I33-1: read the structural plan from the single DocumentStore authority (plan-store). This is an
// in-memory shared-index lookup + JSON.parse (F30-1 Part 2), safe on the hot path (every tool call).
-export const getPlan = (sessionId: string): PlanDoc | null => PlanStore.getPlanDoc(sessionId)
+export const getPlan = (sessionId: string): PlanDoc | null => {
+ const planId = sessions.get(sessionId)?.planLatch.plan_id
+ if (!planId) return null
+ const plan = PlanStore.getPlanDoc(sessionId)
+ return plan?.plan_id === planId ? plan : null
+}
// V3.9 §C — Expert Panel per-session arming.
// The raw per-session toggle (null = never explicitly toggled). setPanelArmed writes an explicit
@@ -421,7 +451,7 @@ export const markPlanStale = (sessionId: string, reason: StaleReason): void => {
saveToDisk()
}
-export type UserMessageObservation = "initial" | "same" | "new"
+export type UserMessageObservation = "initial" | "same" | "new" | "reopened"
/**
* Observes a user admission message and returns whether it is the first,
@@ -432,7 +462,9 @@ export type UserMessageObservation = "initial" | "same" | "new"
* "initial": first time this session is seen; records the baseline ID, does NOT
* mark stale. Old state without lastAdmissionUserMessageId migrates here.
* "same": same ID as last recorded; this is a tool continuation, skip.
- * "new": different ID; this is a genuine new user message, caller should mark stale.
+ * "new": different ID while the activity is live; caller should mark its plan stale.
+ * "reopened": different ID after completion/failure; starts a fresh activity while retaining
+ * session-scoped preferences and the versioned plan history.
*/
export const observeUserAdmission = (
sessionId: string,
@@ -447,6 +479,21 @@ export const observeUserAdmission = (
}
if (state.lastAdmissionUserMessageId === admissionMessageId) return "same"
state.lastAdmissionUserMessageId = admissionMessageId
+ if (state.completedAt) {
+ state.roundState = createInitialRoundState(state.mode)
+ state.lastValidationResults = []
+ state.lastValidationOutput = null
+ state.knowledgeSynthesis = null
+ state.runId = `run_${randomUUID()}`
+ state.planLatch = initialPlanLatch()
+ state.mutationsSinceReport = 0
+ state.validationPassedSinceReport = false
+ state.suppressedValidations = []
+ state.completedAt = null
+ state.lastPlanGateNudgeFingerprint = null
+ saveToDisk()
+ return "reopened"
+ }
saveToDisk()
return "new"
}
@@ -593,7 +640,7 @@ function normalizeState(state: SessionRunState): SessionRunState {
// `>= limit` false forever, silently disabling the grace release for older sessions).
planLatch: state.planLatch
? { ...state.planLatch, consecutive_blocks: state.planLatch.consecutive_blocks ?? 0 }
- : initialPlanLatch(),
+ : initialPlanLatch(PlanStore.getPlanDoc(state.sessionId)?.plan_id ?? null),
// Backfill: sessions persisted before U10 have no counter on disk.
mutationsSinceReport: state.mutationsSinceReport ?? 0,
validationPassedSinceReport: state.validationPassedSinceReport ?? false,
@@ -652,12 +699,73 @@ function loadFromDisk() {
// a newer store doc (e.g. a goal edit) is never overwritten by a stale inline body.
if (state.plan && !PlanStore.getPlanDoc(id)) {
try {
- PlanStore.setPlanDoc(id, state.plan)
- } catch {
- /* best-effort migration: a store hiccup must not block loading session state */
+ const admitted = buildPlanFromWriteInput(
+ id,
+ {
+ operation: "create",
+ expected_plan_id: null,
+ expected_version: null,
+ goal: state.plan.goal,
+ assumptions: state.plan.assumptions ?? [],
+ steps: state.plan.steps.map((step) => ({
+ step_id: step.step_id,
+ title: step.title,
+ status: step.status,
+ acceptance: step.acceptance ?? undefined,
+ assigned_agent: step.assigned_agent ?? undefined,
+ note: step.note ?? undefined,
+ })),
+ active_step_id: state.plan.active_step_id,
+ },
+ null,
+ null,
+ )
+ PlanStore.compareAndCommitPlan({
+ sessionId: id,
+ expected: null,
+ candidate: {
+ ...admitted,
+ plan_id: state.plan.plan_id,
+ created_at: state.plan.created_at,
+ replan_reason: state.plan.replan_reason ?? null,
+ steps: admitted.steps.map((step) => ({
+ ...step,
+ evidence: [...(state.plan!.steps.find((source) => source.step_id === step.step_id)?.evidence ?? [])],
+ })),
+ },
+ origin: "legacy_migration",
+ })
+ } catch (error) {
+ writeLegacyPlanMigrationDiagnostic(id, state.plan, error)
}
}
sessions.set(id, normalizeState(state))
}
} catch {}
}
+
+const writeLegacyPlanMigrationDiagnostic = (sessionId: string, plan: PlanDoc | null | undefined, error: unknown): void => {
+ const code = error instanceof PlanValidationError ? error.code : "legacy_plan_migration_failed"
+ const message = error instanceof Error ? error.message : String(error)
+ const store = DocumentStore.shared(PlanStore.planStoreRoot(sessionId))
+ const description = `DeepAgent legacy plan migration diagnostic ${sessionId}`
+ const doc = store.upsert({
+ type: "diagnosis",
+ scope: PlanStore.planScope(sessionId),
+ description,
+ idSlug: `plan-migration-${sessionId}`,
+ body: JSON.stringify({
+ schema_version: 1,
+ kind: "legacy_plan_migration",
+ status: "quarantined",
+ session_id: sessionId,
+ plan_id: plan?.plan_id ?? null,
+ code,
+ message,
+ observed_at: new Date().toISOString(),
+ }),
+ provenance: { source: "runner", run_ref: PlanStore.planScope(sessionId) },
+ tags: ["bug-010", "plan-migration", "quarantined"],
+ })
+ store.setStatus(doc.id, "quarantined")
+}
diff --git a/packages/core/src/deepagent/validation.ts b/packages/core/src/deepagent/validation.ts
index 8653a214..01e86dbc 100644
--- a/packages/core/src/deepagent/validation.ts
+++ b/packages/core/src/deepagent/validation.ts
@@ -1,18 +1,40 @@
-import type { ValidationResult } from "./round-state"
+import type { ValidationFailureKind, ValidationResult } from "./round-state"
+
+export type ValidationCommandSource = "package_script" | "builtin" | "agents_md" | "user"
+export type ValidationScriptDialect = "posix"
+
+export type ValidationCommand =
+ | {
+ readonly id: string
+ readonly source: ValidationCommandSource
+ readonly transport: "argv"
+ readonly executable: string
+ readonly args: readonly string[]
+ readonly display: string
+ }
+ | {
+ readonly id: string
+ readonly source: ValidationCommandSource
+ readonly transport: ValidationScriptDialect
+ readonly script: string
+ readonly display: string
+ }
+
+export type ValidationCommandInput = string | ValidationCommand
export type ValidationPlan = {
- readonly commands: readonly string[]
+ readonly commands: readonly ValidationCommand[]
readonly timeout_ms: number
readonly failFast: boolean
}
export type ValidationConfig = {
readonly cwd: string
- readonly commands: readonly string[]
+ readonly commands: readonly ValidationCommandInput[]
readonly timeout_ms?: number
}
-export const inferValidationCommands = (context: {
+export const inferValidationPlan = (context: {
readonly cwd: string
readonly packageJson?: { scripts?: Record }
readonly agentsMd?: string
@@ -21,40 +43,105 @@ export const inferValidationCommands = (context: {
// The package-script runner for this workspace (e.g. "npm run", "bun run"). Defaults to npm.
// P2-7: single inference impl; the deepagent-code production path passes "bun run".
readonly runner?: string
-}): string[] => {
- const commands: string[] = []
+}): ValidationCommand[] => {
+ const commands: ValidationCommand[] = []
const run = context.runner ?? "npm run"
- const runnerBin = run.split(/\s+/)[0] ?? "npm" // "bun"/"npm" for the bare typecheck fallback
+ const runner = run.trim().split(/\s+/).filter(Boolean)
+ const runnerBin = runner[0] ?? "npm"
+ const packageScript = (name: string): ValidationCommand => ({
+ id: `package:${name}`,
+ source: "package_script",
+ transport: "argv",
+ executable: runnerBin,
+ args: [...runner.slice(1), name],
+ display: `${run} ${name}`,
+ })
if (context.packageJson?.scripts) {
const scripts = context.packageJson.scripts
- if (scripts.typecheck) commands.push(`${run} typecheck`)
- else if (scripts["type-check"]) commands.push(`${run} type-check`)
- else if (context.hasTypeScript) commands.push(runnerBin === "bun" ? "bun typecheck" : "npx tsc --noEmit")
+ if (scripts.typecheck) commands.push(packageScript("typecheck"))
+ else if (scripts["type-check"]) commands.push(packageScript("type-check"))
+ else if (context.hasTypeScript)
+ commands.push(
+ runnerBin === "bun"
+ ? {
+ id: "builtin:typecheck",
+ source: "builtin",
+ transport: "argv",
+ executable: "bun",
+ args: ["typecheck"],
+ display: "bun typecheck",
+ }
+ : {
+ id: "builtin:typecheck",
+ source: "builtin",
+ transport: "argv",
+ executable: "npx",
+ args: ["tsc", "--noEmit"],
+ display: "npx tsc --noEmit",
+ },
+ )
- if (scripts.lint) commands.push(`${run} lint`)
+ if (scripts.lint) commands.push(packageScript("lint"))
// P1-3: the test command is part of the micro-round validation gate — a failing test means
// "not done". Only added when a test script actually exists (no blind test runs).
- if (scripts.test) commands.push(`${run} test`)
- if (scripts.build && !scripts.test) commands.push(`${run} build`)
+ if (scripts.test) commands.push(packageScript("test"))
+ if (scripts.build && !scripts.test) commands.push(packageScript("build"))
} else if (context.hasTypeScript) {
- commands.push("npx tsc --noEmit")
+ commands.push({
+ id: "builtin:typecheck",
+ source: "builtin",
+ transport: "argv",
+ executable: "npx",
+ args: ["tsc", "--noEmit"],
+ display: "npx tsc --noEmit",
+ })
}
if (context.hasPython) {
- commands.push("python -m py_compile *.py")
+ commands.push({
+ id: "builtin:python-compile",
+ source: "builtin",
+ transport: "argv",
+ executable: "python",
+ args: ["-m", "compileall", "-q", "."],
+ display: "python -m compileall -q .",
+ })
}
if (context.agentsMd) {
const inferredFromAgents = extractCommandsFromAgentsMd(context.agentsMd)
- for (const cmd of inferredFromAgents) {
- if (!commands.includes(cmd)) commands.push(cmd)
- }
+ for (const cmd of inferredFromAgents)
+ if (!commands.some((item) => item.display === cmd))
+ commands.push({
+ id: `agents:${commands.length}`,
+ source: "agents_md",
+ transport: "posix",
+ script: cmd,
+ display: cmd,
+ })
}
return commands
}
+export const inferValidationCommands = (context: Parameters[0]): string[] =>
+ inferValidationPlan(context).map((command) => command.display)
+
+export const normalizeValidationCommand = (command: ValidationCommandInput): ValidationCommand =>
+ typeof command === "string"
+ ? {
+ id: `user:${command}`,
+ source: "user",
+ transport: "posix",
+ script: command,
+ display: command,
+ }
+ : command
+
+export const validationCommandDisplay = (command: ValidationCommandInput): string =>
+ normalizeValidationCommand(command).display
+
// P2-7: the single AGENTS.md command extractor (was duplicated in workspace-context with a
// drifting regex). Matches both "`cmd` - typecheck" list items and "run `cmd` to typecheck" prose.
export const extractCommandsFromAgentsMd = (content: string): string[] => {
@@ -70,7 +157,10 @@ export const extractCommandsFromAgentsMd = (content: string): string[] => {
}
export const buildValidationPlan = (config: ValidationConfig): ValidationPlan => ({
- commands: config.commands.length > 0 ? config.commands : ["echo 'no validation commands configured'"],
+ commands:
+ config.commands.length > 0
+ ? config.commands.map(normalizeValidationCommand)
+ : [normalizeValidationCommand("echo 'no validation commands configured'")],
timeout_ms: config.timeout_ms ?? 60_000,
failFast: true,
})
@@ -80,9 +170,11 @@ export const parseValidationOutput = (
exitCode: number,
output: string,
duration_ms: number,
+ kind: ValidationFailureKind = "command_exit",
): ValidationResult => ({
command,
- passed: exitCode === 0,
+ passed: kind === "command_exit" && exitCode === 0,
+ kind,
exit_code: exitCode,
output: output.slice(-4000),
duration_ms,
diff --git a/packages/core/src/flag/flag.ts b/packages/core/src/flag/flag.ts
index e243ea4a..adaac291 100644
--- a/packages/core/src/flag/flag.ts
+++ b/packages/core/src/flag/flag.ts
@@ -1,4 +1,5 @@
import { Config } from "effect"
+import { InstallationCommit } from "../installation/version"
export function truthy(key: string) {
const value = process.env[key]?.toLowerCase()
@@ -32,7 +33,7 @@ export const Flag = {
DEEPAGENT_CODE_SERVER_USERNAME: process.env["DEEPAGENT_CODE_SERVER_USERNAME"],
// Server Edition: CI injects the deepagent-code commit into workspace images so
// the gateway can report/version-check the data plane (server-v1 §13.3).
- DEEPAGENT_CODE_COMMIT: process.env["DEEPAGENT_CODE_COMMIT"],
+ DEEPAGENT_CODE_COMMIT: InstallationCommit ?? process.env["DEEPAGENT_CODE_COMMIT"],
// Server Edition: when running inside a gateway-managed workspace container,
// provider keys are injected via env and must not persist to the volume (§20.4).
// Getter so tests can toggle it per-case (matches the experimental-flag pattern).
diff --git a/packages/core/src/installation/version.ts b/packages/core/src/installation/version.ts
index 48519a09..0d79c1af 100644
--- a/packages/core/src/installation/version.ts
+++ b/packages/core/src/installation/version.ts
@@ -1,8 +1,10 @@
declare global {
const DEEPAGENT_CODE_VERSION: string
const DEEPAGENT_CODE_CHANNEL: string
+ const DEEPAGENT_CODE_COMMIT: string
}
export const InstallationVersion = typeof DEEPAGENT_CODE_VERSION === "string" ? DEEPAGENT_CODE_VERSION : "local"
export const InstallationChannel = typeof DEEPAGENT_CODE_CHANNEL === "string" ? DEEPAGENT_CODE_CHANNEL : "local"
export const InstallationLocal = InstallationChannel === "local"
+export const InstallationCommit = typeof DEEPAGENT_CODE_COMMIT === "string" ? DEEPAGENT_CODE_COMMIT : undefined
diff --git a/packages/core/src/session/event.ts b/packages/core/src/session/event.ts
index f6d51fb6..501e7bc5 100644
--- a/packages/core/src/session/event.ts
+++ b/packages/core/src/session/event.ts
@@ -130,6 +130,42 @@ export const InterruptRequested = EventV2.define({
})
export type InterruptRequested = typeof InterruptRequested.Type
+export namespace Execution {
+ export const Started = EventV2.define({
+ type: "session.execution.started",
+ ...options,
+ schema: Base,
+ })
+ export type Started = typeof Started.Type
+
+ export const Succeeded = EventV2.define({
+ type: "session.execution.succeeded",
+ ...options,
+ schema: Base,
+ })
+ export type Succeeded = typeof Succeeded.Type
+
+ export const Failed = EventV2.define({
+ type: "session.execution.failed",
+ ...options,
+ schema: {
+ ...Base,
+ error: UnknownError,
+ },
+ })
+ export type Failed = typeof Failed.Type
+
+ export const Interrupted = EventV2.define({
+ type: "session.execution.interrupted",
+ ...options,
+ schema: {
+ ...Base,
+ reason: Schema.Literals(["user", "shutdown", "superseded"]),
+ },
+ })
+ export type Interrupted = typeof Interrupted.Type
+}
+
export const ContextUpdated = EventV2.define({
type: "session.next.context.updated",
...options,
@@ -481,6 +517,10 @@ const DurableDefinitions = [
PromptLifecycle.Admitted,
PromptLifecycle.Promoted,
InterruptRequested,
+ Execution.Started,
+ Execution.Succeeded,
+ Execution.Failed,
+ Execution.Interrupted,
ContextUpdated,
Synthetic,
Shell.Started,
diff --git a/packages/core/src/session/execution.ts b/packages/core/src/session/execution.ts
index eb06090b..465fea4f 100644
--- a/packages/core/src/session/execution.ts
+++ b/packages/core/src/session/execution.ts
@@ -1,23 +1,48 @@
export * as SessionExecution from "./execution"
-import { Context, Effect, Layer } from "effect"
+import { Cause, Context, Effect, Exit, Layer } from "effect"
import { SessionRunner } from "./runner/index"
import { SessionSchema } from "./schema"
export interface Interface {
+ /** Snapshots active execution owned by this process. */
+ readonly active: Effect.Effect>
/** Explicitly drain one Session, making at least one provider attempt. */
readonly resume: (sessionID: SessionSchema.ID) => Effect.Effect
/** Schedule a drain after durable work is recorded. Repeated wakeups may coalesce. */
readonly wake: (sessionID: SessionSchema.ID, seq?: number) => Effect.Effect
/** Interrupt active work owned by this process. Idle interruption is a no-op. */
readonly interrupt: (sessionID: SessionSchema.ID, seq?: number) => Effect.Effect
+ /** Resolves once this process owns no active execution for the Session. */
+ readonly awaitIdle: (sessionID: SessionSchema.ID) => Effect.Effect
}
/** Routes execution from a Session ID to the runner owned by that Session's Location. */
export class Service extends Context.Service()("@deepagent-code/v2/SessionExecution") {}
+export type InterruptReason = "user" | "shutdown" | "superseded"
+
+export function terminal(exit: Exit.Exit, reason?: InterruptReason) {
+ if (Exit.isSuccess(exit)) return { type: "succeeded" as const }
+ if (Cause.hasInterrupts(exit.cause)) return { type: "interrupted" as const, reason: reason ?? "shutdown" }
+ const failure = Cause.squash(exit.cause)
+ return {
+ type: "failed" as const,
+ error: {
+ type: "unknown" as const,
+ message: failure instanceof Error ? failure.message : String(failure),
+ },
+ }
+}
+
/** Low-level compatibility layer for callers that only need durable Session recording. */
export const noopLayer = Layer.succeed(
Service,
- Service.of({ resume: () => Effect.void, wake: () => Effect.void, interrupt: () => Effect.void }),
+ Service.of({
+ active: Effect.succeed(new Set()),
+ resume: () => Effect.void,
+ wake: () => Effect.void,
+ interrupt: () => Effect.void,
+ awaitIdle: () => Effect.void,
+ }),
)
diff --git a/packages/core/src/session/execution/local.ts b/packages/core/src/session/execution/local.ts
index 8f1b1763..be6ff784 100644
--- a/packages/core/src/session/execution/local.ts
+++ b/packages/core/src/session/execution/local.ts
@@ -1,5 +1,9 @@
-import { Effect, Layer } from "effect"
+export * as SessionExecutionLocal from "./local"
+
+import { Cause, DateTime, Effect, Layer } from "effect"
+import { EventV2 } from "../../event"
import { LocationServiceMap } from "../../location-layer"
+import { SessionEvent } from "../event"
import { SessionRunCoordinator } from "../run-coordinator"
import { SessionRunner } from "../runner"
import { SessionSchema } from "../schema"
@@ -13,7 +17,38 @@ export const layer = Layer.effect(
Effect.gen(function* () {
const store = yield* SessionStore.Service
const locations = yield* LocationServiceMap
- const coordinator = yield* SessionRunCoordinator.make({
+ const events = yield* EventV2.Service
+ const reportLifecycle = (sessionID: SessionSchema.ID, effect: Effect.Effect) =>
+ effect.pipe(
+ Effect.tapCause((cause) =>
+ Cause.hasInterruptsOnly(cause)
+ ? Effect.void
+ : Effect.logError("Failed to publish Session execution lifecycle", cause).pipe(
+ Effect.annotateLogs("sessionID", sessionID),
+ ),
+ ),
+ Effect.ignore,
+ )
+ const clearSuspensionOnCommit = (sessionID: SessionSchema.ID) => ({
+ commit: () => store.consumeSuspended(sessionID).pipe(Effect.asVoid),
+ })
+ const coordinator = yield* SessionRunCoordinator.make<
+ SessionSchema.ID,
+ void,
+ SessionRunner.RunError,
+ SessionExecution.InterruptReason
+ >({
+ started: (sessionID) =>
+ reportLifecycle(
+ sessionID,
+ Effect.gen(function* () {
+ yield* events.publish(
+ SessionEvent.Execution.Started,
+ { sessionID, timestamp: yield* DateTime.now },
+ clearSuspensionOnCommit(sessionID),
+ )
+ }),
+ ),
drain: Effect.fnUntraced(function* (sessionID: SessionSchema.ID, mode) {
const session = yield* store.get(sessionID)
if (!session) return yield* Effect.die(`Session not found: ${sessionID}`)
@@ -22,14 +57,47 @@ export const layer = Layer.effect(
)
}),
onFailure: (sessionID, cause) => logFailure("Failed to drain Session", sessionID, cause),
+ settled: (sessionID, exit, reason) =>
+ reportLifecycle(
+ sessionID,
+ Effect.gen(function* () {
+ const outcome = SessionExecution.terminal(exit, reason)
+ const timestamp = yield* DateTime.now
+ if (outcome.type === "succeeded") {
+ yield* events.publish(
+ SessionEvent.Execution.Succeeded,
+ { sessionID, timestamp },
+ clearSuspensionOnCommit(sessionID),
+ )
+ return
+ }
+ if (outcome.type === "interrupted") {
+ yield* events.publish(SessionEvent.Execution.Interrupted, {
+ sessionID,
+ timestamp,
+ reason: outcome.reason,
+ })
+ return
+ }
+ yield* events.publish(
+ SessionEvent.Execution.Failed,
+ { sessionID, timestamp, error: outcome.error },
+ clearSuspensionOnCommit(sessionID),
+ )
+ }),
+ ),
})
return SessionExecution.Service.of({
- interrupt: coordinator.interrupt,
+ active: coordinator.active,
+ interrupt: (sessionID, seq) => coordinator.interrupt(sessionID, seq, "user"),
resume: coordinator.run,
wake: coordinator.wake,
+ awaitIdle: coordinator.awaitIdle,
})
}),
)
-export const defaultLayer = layer.pipe(Layer.provide(SessionStore.defaultLayer))
+export const defaultLayer = layer.pipe(Layer.provide(SessionStore.defaultLayer), Layer.provide(EventV2.defaultLayer))
+
+export const liveLayer = Layer.suspend(() => defaultLayer.pipe(Layer.provide(LocationServiceMap.layer)))
diff --git a/packages/core/src/session/execution/restart.ts b/packages/core/src/session/execution/restart.ts
new file mode 100644
index 00000000..9f89cef9
--- /dev/null
+++ b/packages/core/src/session/execution/restart.ts
@@ -0,0 +1,39 @@
+export * as SessionRestart from "./restart"
+
+import { Context, Effect, Layer } from "effect"
+import { SessionExecution } from "../execution"
+import { SessionStore } from "../store"
+
+export interface Interface {
+ /** Marks execution active in this process for one resume attempt by the next managed process. */
+ readonly suspendActiveSessions: Effect.Effect
+ /** Atomically consumes and resumes every suspended Session at most once. */
+ readonly resumeSuspendedSessions: Effect.Effect
+}
+
+/** Restart continuity actions. The host must invoke them explicitly. */
+export class Service extends Context.Service()("@deepagent-code/v2/SessionRestart") {}
+
+export const layer = Layer.effect(
+ Service,
+ Effect.gen(function* () {
+ const store = yield* SessionStore.Service
+ const execution = yield* SessionExecution.Service
+ return Service.of({
+ suspendActiveSessions: Effect.gen(function* () {
+ yield* store.suspend(yield* execution.active)
+ }),
+ resumeSuspendedSessions: Effect.gen(function* () {
+ yield* Effect.forEach(
+ yield* store.listSuspended(),
+ (sessionID) =>
+ Effect.gen(function* () {
+ if (!(yield* store.consumeSuspended(sessionID))) return
+ yield* execution.resume(sessionID).pipe(Effect.ignore)
+ }),
+ { concurrency: "unbounded", discard: true },
+ )
+ }),
+ })
+ }),
+)
diff --git a/packages/core/src/session/message-updater.ts b/packages/core/src/session/message-updater.ts
index bbe1ce75..db804272 100644
--- a/packages/core/src/session/message-updater.ts
+++ b/packages/core/src/session/message-updater.ts
@@ -100,6 +100,10 @@ export function update(adapter: Adapter, event: SessionEvent.Event) {
return Effect.gen(function* () {
yield* SessionEvent.All.match(event, {
+ "session.execution.started": () => Effect.void,
+ "session.execution.succeeded": () => Effect.void,
+ "session.execution.failed": () => Effect.void,
+ "session.execution.interrupted": () => Effect.void,
"session.next.agent.switched": (event) => {
return adapter.appendMessage(
new SessionMessage.AgentSwitched({
diff --git a/packages/core/src/session/projector.ts b/packages/core/src/session/projector.ts
index d021201d..663be8b4 100644
--- a/packages/core/src/session/projector.ts
+++ b/packages/core/src/session/projector.ts
@@ -413,6 +413,10 @@ export const layer = Layer.effectDiscard(
}),
)
yield* events.project(SessionEvent.InterruptRequested, () => Effect.void)
+ yield* events.project(SessionEvent.Execution.Started, () => Effect.void)
+ yield* events.project(SessionEvent.Execution.Succeeded, () => Effect.void)
+ yield* events.project(SessionEvent.Execution.Failed, () => Effect.void)
+ yield* events.project(SessionEvent.Execution.Interrupted, () => Effect.void)
yield* events.project(SessionEvent.ContextUpdated, (event) => {
if (!event.replay || event.seq === undefined) return run(db, event)
return run(db, event).pipe(
diff --git a/packages/core/src/session/run-coordinator.ts b/packages/core/src/session/run-coordinator.ts
index 681ab81b..17f13cbd 100644
--- a/packages/core/src/session/run-coordinator.ts
+++ b/packages/core/src/session/run-coordinator.ts
@@ -26,7 +26,9 @@ type Demand = { readonly _tag: "run" } | { readonly _tag: "wake"; readonly seq?:
* `interrupt` stops the current ownership chain. Advisory wakes from before the interrupt
* boundary are suppressed; advisory wakes after the boundary run after cleanup.
*/
-export interface Coordinator {
+export interface Coordinator {
+ /** Snapshots keys with an ownership chain active in this process. */
+ readonly active: Effect.Effect>
/** Starts or joins one explicit drain generation. */
readonly run: (key: Key) => Effect.Effect
/** Coalesces one wake-up after durable work is recorded. */
@@ -34,11 +36,11 @@ export interface Coordinator {
/** Waits until the current ownership chain settles. */
readonly awaitIdle: (key: Key) => Effect.Effect
/** Interrupts the active ownership chain without automatically draining pending wakes. */
- readonly interrupt: (key: Key, seq?: number) => Effect.Effect
+ readonly interrupt: (key: Key, seq?: number, reason?: Reason) => Effect.Effect
}
/** One Session's process-local execution lane: one active demand and at most one coalesced follow-up. */
-type Entry = {
+type Entry = {
readonly done: Deferred.Deferred
readonly settled: Deferred.Deferred>
current: Demand
@@ -47,6 +49,9 @@ type Entry = {
interruptSeq?: number
owner?: Fiber.Fiber
stopping: boolean
+ started: boolean
+ terminalizing: boolean
+ interruptionReason?: Reason
}
/** Combines follow-up demand: runs dominate, while wakes retain the newest durable admission sequence. */
@@ -62,12 +67,16 @@ const maxSeq = (left: number | undefined, right: number | undefined) => {
}
/** Constructs a scoped coordinator. Every in-memory transition is synchronous. */
-export const make = (options: {
+export const make = (options: {
readonly drain: (key: Key, mode: Mode) => Effect.Effect
readonly onFailure?: (key: Key, cause: Cause.Cause) => Effect.Effect
-}): Effect.Effect, never, Scope.Scope> =>
+ /** Runs once before the first drain in one process-local ownership chain. */
+ readonly started?: (key: Key) => Effect.Effect
+ /** Runs once after the final drain in one process-local ownership chain. */
+ readonly settled?: (key: Key, exit: Exit.Exit, reason?: Reason) => Effect.Effect
+}): Effect.Effect, never, Scope.Scope> =>
Effect.gen(function* () {
- const active = new Map>()
+ const active = new Map>()
const interruptSeq = new Map()
const report = yield* FiberSet.makeRuntime()
const fork = yield* FiberSet.makeRuntime()
@@ -82,25 +91,39 @@ export const make = (options: {
}),
)
- const makeEntry = (current: Demand, explicitWaiter?: Deferred.Deferred): Entry => ({
+ const makeEntry = (current: Demand, explicitWaiter?: Deferred.Deferred): Entry => ({
done: Deferred.makeUnsafe(),
settled: Deferred.makeUnsafe>(),
current,
explicitWaiter,
stopping: false,
+ started: false,
+ terminalizing: false,
})
- const start = (key: Key, entry: Entry, demand: Demand, successor = false) => {
+ const start = (key: Key, entry: Entry, demand: Demand, successor = false) => {
const ready = Deferred.makeUnsafe()
const drain = Effect.suspend(() => options.drain(key, demand._tag))
+ const started = Effect.suspend(() => {
+ if (entry.started) return Effect.void
+ entry.started = true
+ return options.started?.(key) ?? Effect.void
+ })
// Initial work retains immediate-start behavior but cannot run before ownership is published.
// Observer-started successors yield once so synchronous drains cannot recurse on the JS stack.
const owner = fork(
- (successor
- ? Effect.yieldNow.pipe(Effect.andThen(drain))
- : Deferred.await(ready).pipe(Effect.andThen(drain))
- ).pipe(
- Effect.onExit((exit) => Effect.sync(() => settle(key, entry, demand, exit))),
+ started.pipe(
+ Effect.andThen(
+ successor ? Effect.yieldNow.pipe(Effect.andThen(drain)) : Deferred.await(ready).pipe(Effect.andThen(drain)),
+ ),
+ Effect.onExit((exit) => {
+ if (exit._tag === "Success" && !entry.stopping && entry.pending !== undefined)
+ return Effect.sync(() => settle(key, entry, demand, exit))
+ entry.terminalizing = true
+ return (options.settled?.(key, exit, entry.interruptionReason) ?? Effect.void).pipe(
+ Effect.ensuring(Effect.sync(() => settle(key, entry, demand, exit))),
+ )
+ }),
Effect.exit,
Effect.asVoid,
),
@@ -109,7 +132,7 @@ export const make = (options: {
if (!successor) Deferred.doneUnsafe(ready, Effect.void)
}
- const settle = (key: Key, entry: Entry, demand: Demand, exit: Exit.Exit) => {
+ const settle = (key: Key, entry: Entry, demand: Demand, exit: Exit.Exit) => {
if (closed) {
Deferred.doneUnsafe(entry.done, exit)
Deferred.doneUnsafe(entry.settled, Effect.succeed(exit))
@@ -128,7 +151,7 @@ export const make = (options: {
Deferred.doneUnsafe(entry.settled, Effect.succeed(exit))
return
}
- if (exit._tag === "Success" && !entry.stopping) {
+ if (exit._tag === "Success" && !entry.stopping && !entry.terminalizing) {
if (entry.pending !== undefined) {
const pending = entry.pending
entry.pending = undefined
@@ -190,7 +213,7 @@ export const make = (options: {
if (firstFailure !== undefined) return yield* Effect.failCause(firstFailure)
})
- const interrupt = (key: Key, seq?: number): Effect.Effect =>
+ const interrupt = (key: Key, seq?: number, reason?: Reason): Effect.Effect =>
Effect.suspend(() => {
const entry = active.get(key)
const latest = interruptSeq.get(key)
@@ -206,17 +229,25 @@ export const make = (options: {
)
return Effect.void
if (entry.stopping) {
+ if (reason !== undefined) entry.interruptionReason = reason
entry.interruptSeq = maxSeq(entry.interruptSeq, seq)
suppressPendingAtOrBefore(entry, seq)
return Fiber.interrupt(entry.owner)
}
entry.stopping = true
+ entry.interruptionReason = reason
entry.interruptSeq = seq
suppressPendingAtOrBefore(entry, seq)
return Fiber.interrupt(entry.owner)
})
- return { run, wake, awaitIdle, interrupt }
+ return {
+ active: Effect.sync(() => new Set(active.keys())),
+ run,
+ wake,
+ awaitIdle,
+ interrupt,
+ }
function run(key: Key): Effect.Effect {
return Effect.uninterruptibleMask((restore) => {
@@ -245,7 +276,7 @@ export const make = (options: {
return Effect.raceFirst(Deferred.await(done), Deferred.await(shutdown).pipe(Effect.andThen(Effect.interrupt)))
}
- function acceptsWake(entry: Entry, seq: number | undefined) {
+ function acceptsWake(entry: Entry, seq: number | undefined) {
return !entry.stopping || (entry.interruptSeq !== undefined && seq !== undefined && seq > entry.interruptSeq)
}
@@ -254,7 +285,7 @@ export const make = (options: {
return latest === undefined || (seq !== undefined && seq > latest)
}
- function suppressPendingAtOrBefore(entry: Entry, seq: number | undefined) {
+ function suppressPendingAtOrBefore(entry: Entry, seq: number | undefined) {
if (
entry.pending?._tag === "wake" &&
seq !== undefined &&
diff --git a/packages/core/src/session/sql.ts b/packages/core/src/session/sql.ts
index 1bdd4971..260ed7b2 100644
--- a/packages/core/src/session/sql.ts
+++ b/packages/core/src/session/sql.ts
@@ -1,4 +1,14 @@
-import { sqliteTable, text, integer, index, primaryKey, real, uniqueIndex } from "drizzle-orm/sqlite-core"
+import {
+ sqliteTable,
+ text,
+ integer,
+ index,
+ primaryKey,
+ real,
+ uniqueIndex,
+ type AnySQLiteColumn,
+} from "drizzle-orm/sqlite-core"
+import { sql } from "drizzle-orm"
import * as DatabasePath from "../database/path"
import { ProjectTable } from "../project/sql"
import type { SessionMessage } from "./message"
@@ -13,7 +23,6 @@ import { WorkspaceV2 } from "../workspace"
import { Timestamps } from "../database/schema.sql"
import type { SystemContext } from "../system-context/index"
import { AgentV2 } from "../agent"
-import { sql } from "drizzle-orm"
type SessionMessageData = Omit<(typeof SessionMessage.Message)["Encoded"], "type" | "id">
type V1MessageData = Omit
@@ -46,6 +55,7 @@ export const SessionTable = sqliteTable(
tokens_reasoning: integer().notNull().default(0),
tokens_cache_read: integer().notNull().default(0),
tokens_cache_write: integer().notNull().default(0),
+ mutation_epoch: integer().notNull().default(0),
revert: text({ mode: "json" }).$type<{ messageID: MessageID; partID?: PartID; snapshot?: string; diff?: string }>(),
permission: text({ mode: "json" }).$type(),
agent: text(),
@@ -57,6 +67,7 @@ export const SessionTable = sqliteTable(
...Timestamps,
time_compacting: integer(),
time_archived: integer(),
+ time_suspended: integer(),
// Snapshot of the session's first user message (truncated, single-lined). Lets an archived-sessions
// list render a content preview per row without loading the full conversation. Set once, never
// overwritten. Mirrors Codex's `threads.preview`.
@@ -66,6 +77,9 @@ export const SessionTable = sqliteTable(
index("session_project_idx").on(table.project_id),
index("session_workspace_idx").on(table.workspace_id),
index("session_parent_idx").on(table.parent_id),
+ index("session_time_suspended_idx")
+ .on(table.time_suspended)
+ .where(sql`${table.time_suspended} is not null`),
],
)
@@ -178,10 +192,9 @@ export const SessionInputTable = sqliteTable(
// loop (SessionPrompt.runLoop), where it is persisted as an ordinary tail user message. This is a
// PLAIN durable buffer (direct row writes, NOT event-sourced) — deliberately distinct from
// SessionInputTable, which is projected only by the dormant experimentalEventSystem V2 runner and
-// feeds a different (V2) history store. Consume-once is enforced by `consumed_seq`: `drainSteer`
-// atomically stamps every pending row it returns in one transaction, so a second drain (or a
-// concurrent one) sees no pending rows. `seq` is a per-session monotonic admission order (autoincrement
-// PK) so a drain returns steers in the exact order the user sent them.
+// feeds a different (V2) history store. Chat materialization writes the V1 message and consume stamp in
+// one transaction. `mutation_epoch` and `superseded_at` fence every pending row against revert/rewrite.
+// `seq` is a per-session monotonic admission order so a drain preserves exact send order.
export const SessionSteerTable = sqliteTable(
"session_steer",
{
@@ -197,7 +210,9 @@ export const SessionSteerTable = sqliteTable(
correlation_id: text(),
prompt: text({ mode: "json" }).notNull().$type(),
delivery: text().$type().notNull(),
+ mutation_epoch: integer().notNull().default(0),
consumed_seq: integer(),
+ superseded_at: integer(),
time_created: integer()
.notNull()
.$default(() => Date.now()),
@@ -208,6 +223,36 @@ export const SessionSteerTable = sqliteTable(
],
)
+export const SessionIntentTable = sqliteTable(
+ "session_intent",
+ {
+ intent_id: text().primaryKey(),
+ session_id: text()
+ .$type()
+ .notNull()
+ .references(() => SessionTable.id, { onDelete: "cascade" }),
+ source: text().$type<"composer" | "intelligence" | "followup" | "rewrite">().notNull(),
+ state: text().$type<"preparing" | "admitting" | "admitted" | "canceled" | "superseded" | "failed">().notNull(),
+ selected_variant: text().$type<"original" | "rewritten">(),
+ selected_payload_hash: text(),
+ delivery: text().$type<"turn" | SessionInput.Delivery>(),
+ admitted_message_id: text(),
+ correlation_id: text(),
+ owner_token: text(),
+ lease_expires_at: integer(),
+ mutation_epoch: integer().notNull().default(0),
+ version: integer().notNull().default(0),
+ time_created: integer().notNull(),
+ time_selected: integer(),
+ time_admitted: integer(),
+ time_updated: integer().notNull(),
+ },
+ (table) => [
+ uniqueIndex("session_intent_session_intent_idx").on(table.session_id, table.intent_id),
+ index("session_intent_session_state_idx").on(table.session_id, table.state, table.time_created),
+ ],
+)
+
export const SessionContextEpochTable = sqliteTable("session_context_epoch", {
session_id: text()
.$type()
@@ -224,6 +269,7 @@ export const SessionContextEpochTable = sqliteTable("session_context_epoch", {
export const TaskRunTable = sqliteTable(
"task_run",
{
+ // ── Core identity ──────────────────────────────────────────────────────
run_id: text().primaryKey(),
root_run_id: text(),
request_hash: text().notNull(),
@@ -236,10 +282,22 @@ export const TaskRunTable = sqliteTable(
child_session_id: text().$type().notNull(),
generation: integer().notNull(),
delivery_mode: text().$type<"foreground" | "background">().notNull(),
- phase: text().$type<"admission" | "research" | "finalize" | "settled">().notNull(),
+ phase: text().$type<"admission" | "research" | "finalize" | "settled" | "queue" | "provision">().notNull(),
state: text()
.$type<
- "admitted" | "provisioning" | "researching" | "finalizing" | "completed" | "error" | "cancelled" | "interrupted"
+ | "admitted"
+ | "provisioning"
+ | "researching"
+ | "finalizing"
+ | "completed"
+ | "error"
+ | "cancelled"
+ | "interrupted"
+ | "queued"
+ | "running"
+ | "failed"
+ | "closed"
+ | "recovery_required"
>()
.notNull(),
reason: text(),
@@ -253,14 +311,99 @@ export const TaskRunTable = sqliteTable(
time_created: integer().notNull(),
time_updated: integer().notNull(),
time_settled: integer(),
+ // ── Run graph / lineage (L2) ───────────────────────────────────────────
+ parent_run_id: text().references((): AnySQLiteColumn => TaskRunTable.run_id, { onDelete: "cascade" }),
+ continuation_of_run_id: text().references((): AnySQLiteColumn => TaskRunTable.run_id, { onDelete: "cascade" }),
+ depth: integer().notNull().default(1),
+ // ── Origin identity ────────────────────────────────────────────────────
+ origin_kind: text().$type<"task_tool" | "goal_role">().notNull().default("task_tool"),
+ origin_key: text(),
+ // ── Modes (immutable at admission) ─────────────────────────────────────
+ effective_delivery_mode: text().$type<"foreground" | "background">().notNull().default("foreground"),
+ promoted_at: integer(),
+ session_mode: text().$type<"new" | "resume">().notNull().default("new"),
+ context_mode: text().$type<"fresh" | "fork">().notNull().default("fresh"),
+ context_cutoff_message_id: text().$type(),
+ // ── Capability / workspace policy (frozen at admission) ────────────────
+ mutation_capability: text().$type<"read_only" | "write">().notNull().default("write"),
+ tool_capability_hash: text().notNull().default("legacy-unknown"),
+ workspace_mode: text().$type<"shared" | "worktree">().notNull().default("shared"),
+ workspace_owner: text().$type<"parent" | "run" | "caller" | "goal">().notNull().default("parent"),
+ workspace_visibility: text().$type<"live" | "base_commit">().notNull().default("live"),
+ parent_dirty_policy: text().$type<"allow_live" | "exclude" | "reject">().notNull().default("allow_live"),
+ workspace_operation_key: text(),
+ workspace_revision: integer(),
+ execution_spec: text({ mode: "json" }).$type>(),
+ // ── Lifecycle / CAS ────────────────────────────────────────────────────
+ version: integer().notNull().default(0),
+ control_state: text().$type<"open" | "close_requested" | "closed">().notNull().default("open"),
+ input_state: text()
+ .$type<"pending" | "admitting" | "ready" | "conflict" | "outcome_unknown" | "legacy">()
+ .notNull()
+ .default("legacy"),
+ child_message_id: text().$type(),
+ input_admission_started_at: integer(),
+ child_input_materialized_hash: text(),
+ child_input_part_count: integer(),
+ execution_started_at: integer(),
+ finalizer_started_at: integer(),
+ interrupt_requested_at: integer(),
+ interrupt_reason: text(),
+ close_requested_at: integer(),
+ close_reason: text(),
+ claim_generation: integer().notNull().default(0),
+ start_attempts: integer().notNull().default(0),
+ available_at: integer().notNull().default(0),
+ priority: integer().notNull().default(0),
+ queue_reason: text(),
+ // ── Workspace provisioning receipts ────────────────────────────────────
+ workspace_preflight_state: text().$type<"legacy" | "pending" | "ready" | "failed">().notNull().default("legacy"),
+ workspace_preflight_at: integer(),
+ workspace_repository_root: text(),
+ workspace_base_commit: text(),
+ workspace_parent_branch: text(),
+ workspace_target_branch: text(),
+ workspace_status_hash: text(),
+ workspace_preflight_error_code: text(),
+ workspace_branch_state: text().$type<"none" | "admitting" | "ready" | "conflict">().notNull().default("none"),
+ workspace_branch_started_at: integer(),
+ worktree_directory: text(),
+ worktree_branch: text(),
+ worktree_state: text()
+ .$type<"none" | "admitting" | "ready" | "conflict" | "retained" | "submitted" | "removed">()
+ .notNull()
+ .default("none"),
+ worktree_started_at: integer(),
+ pr_operation_key: text(),
+ pr_started_at: integer(),
+ pr_id: text(),
+ // ── Goal-specific identity columns ─────────────────────────────────────
+ goal_id: text(),
+ goal_tick_seq: integer(),
+ goal_role: text(),
+ goal_ordinal: integer(),
+ // ── Result enrichment ──────────────────────────────────────────────────
+ result_hash: text(),
+ usage: text({ mode: "json" }).$type>(),
+ progress_seq: integer().notNull().default(0),
+ last_progress_at: integer(),
+ finalizer_input_message_id: text().$type(),
},
(table) => [
uniqueIndex("task_run_child_generation_idx").on(table.child_session_id, table.generation),
uniqueIndex("task_run_child_active_idx")
.on(table.child_session_id)
- .where(sql`${table.state} IN ('admitted', 'provisioning', 'researching', 'finalizing')`),
+ .where(sql`${table.state} IN ('admitted', 'provisioning', 'running', 'researching', 'finalizing')`),
index("task_run_parent_state_idx").on(table.parent_session_id, table.state, table.time_updated),
index("task_run_root_idx").on(table.root_run_id),
+ index("task_run_queue_idx").on(
+ table.state,
+ table.available_at,
+ table.priority,
+ table.time_created,
+ table.generation,
+ ),
+ index("task_run_goal_idx").on(table.goal_id, table.goal_tick_seq, table.goal_role, table.goal_ordinal),
],
)
@@ -305,7 +448,18 @@ export const TaskNotificationOutboxTable = sqliteTable(
text: string
}>()
.notNull(),
- status: text().$type<"pending" | "delivering" | "delivered" | "dead">().notNull(),
+ status: text()
+ .$type<
+ | "pending"
+ | "delivering"
+ | "delivered"
+ | "dead"
+ | "admitting"
+ | "admitted"
+ | "processing"
+ | "response_recovery_required"
+ >()
+ .notNull(),
attempts: integer().notNull().default(0),
available_at: integer().notNull(),
lease_owner: text(),
@@ -314,6 +468,40 @@ export const TaskNotificationOutboxTable = sqliteTable(
time_created: integer().notNull(),
time_updated: integer().notNull(),
time_delivered: integer(),
+ // ── New columns (L1) ───────────────────────────────────────────────────
+ event_kind: text().$type<"terminal" | "progress" | "notification">().notNull().default("terminal"),
+ correlation_id: text(),
+ payload_hash: text(),
+ parent_input_message_id: text().$type(),
+ response_message_id: text().$type(),
+ response_started_at: integer(),
+ time_admitted: integer(),
+ },
+ (table) => [
+ index("task_notification_outbox_due_idx").on(table.status, table.available_at, table.lease_expires_at),
+ uniqueIndex("task_notification_outbox_parent_processing_idx")
+ .on(table.parent_session_id)
+ .where(sql`${table.status} = 'processing'`),
+ ],
+)
+
+export const TaskRunEventTable = sqliteTable(
+ "task_run_event",
+ {
+ event_id: text().primaryKey(),
+ run_id: text()
+ .notNull()
+ .references(() => TaskRunTable.run_id, { onDelete: "cascade" }),
+ version: integer().notNull(),
+ type: text().notNull(),
+ from_state: text(),
+ to_state: text(),
+ reason: text(),
+ data: text({ mode: "json" }).$type(),
+ time_created: integer().notNull(),
},
- (table) => [index("task_notification_outbox_due_idx").on(table.status, table.available_at, table.lease_expires_at)],
+ (table) => [
+ uniqueIndex("task_run_event_run_version_idx").on(table.run_id, table.version),
+ index("task_run_event_time_idx").on(table.time_created, table.event_id),
+ ],
)
diff --git a/packages/core/src/session/store.ts b/packages/core/src/session/store.ts
index fcb7586e..3d6f19c9 100644
--- a/packages/core/src/session/store.ts
+++ b/packages/core/src/session/store.ts
@@ -1,6 +1,6 @@
export * as SessionStore from "./store"
-import { eq } from "drizzle-orm"
+import { and, eq, inArray, isNotNull, isNull } from "drizzle-orm"
import { Context, Effect, Layer, Schema } from "effect"
import { Database } from "../database/database"
import { makeGlobalNode } from "../effect/app-node"
@@ -21,6 +21,10 @@ export interface Interface {
readonly message: (
messageID: SessionMessage.ID,
) => Effect.Effect<{ readonly sessionID: SessionSchema.ID; readonly message: SessionMessage.Message } | undefined>
+ readonly listSuspended: () => Effect.Effect>
+ /** Clears suspension, reporting whether this caller consumed it. At most one concurrent caller receives true. */
+ readonly consumeSuspended: (sessionID: SessionSchema.ID) => Effect.Effect
+ readonly suspend: (sessionIDs: Iterable) => Effect.Effect
}
export class Service extends Context.Service()("@deepagent-code/v2/SessionStore") {}
@@ -56,6 +60,38 @@ export const layer = Layer.effect(
}
: undefined
}),
+ listSuspended: Effect.fn("SessionStore.listSuspended")(function* () {
+ return yield* db
+ .select({ sessionID: SessionTable.id })
+ .from(SessionTable)
+ .where(isNotNull(SessionTable.time_suspended))
+ .all()
+ .pipe(
+ Effect.orDie,
+ Effect.map((rows) => rows.map((row) => row.sessionID)),
+ )
+ }),
+ consumeSuspended: Effect.fn("SessionStore.consumeSuspended")(function* (sessionID) {
+ return (
+ (yield* db
+ .update(SessionTable)
+ .set({ time_suspended: null })
+ .where(and(eq(SessionTable.id, sessionID), isNotNull(SessionTable.time_suspended)))
+ .returning({ sessionID: SessionTable.id })
+ .get()
+ .pipe(Effect.orDie)) !== undefined
+ )
+ }),
+ suspend: Effect.fn("SessionStore.suspend")(function* (sessionIDs) {
+ const ids = Array.from(sessionIDs)
+ if (ids.length === 0) return
+ yield* db
+ .update(SessionTable)
+ .set({ time_suspended: Date.now() })
+ .where(and(inArray(SessionTable.id, ids), isNull(SessionTable.time_suspended)))
+ .run()
+ .pipe(Effect.orDie)
+ }),
})
}),
)
diff --git a/packages/core/src/v1/session.ts b/packages/core/src/v1/session.ts
index 2a16677a..111dee0f 100644
--- a/packages/core/src/v1/session.ts
+++ b/packages/core/src/v1/session.ts
@@ -70,6 +70,12 @@ export const OutputDegenerationError = NamedError.create("OutputDegenerationErro
ratio: Schema.Number,
detectorVersion: Schema.String,
})
+export const PlanProtocolViolationError = NamedError.create("PlanProtocolViolation", {
+ message: Schema.String,
+ sessionID: Schema.optional(SessionSchema.ID),
+ attemptOrdinal: NonNegativeInt,
+ code: Schema.optional(Schema.String),
+})
export class OutputFormatText extends Schema.Class("OutputFormatText")({
type: Schema.Literal("text"),
@@ -411,6 +417,7 @@ const AssistantErrorSchema = Schema.Union([
ContextOverflowError.EffectSchema,
APIError.EffectSchema,
OutputDegenerationError.EffectSchema,
+ PlanProtocolViolationError.EffectSchema,
]).annotate({ discriminator: "name" })
type AssistantError = Schema.Schema.Type
diff --git a/packages/core/test/context-federation/contract.test.ts b/packages/core/test/context-federation/contract.test.ts
index 9d8d0966..8819e13b 100644
--- a/packages/core/test/context-federation/contract.test.ts
+++ b/packages/core/test/context-federation/contract.test.ts
@@ -177,6 +177,52 @@ describe("context federation rollout dependencies", () => {
expect(decision.blocked.contextProjectionV2).toContain("context_federation_kill_switch")
})
+ test("requires derived readiness after Project eligibility", () => {
+ const eligible = ContextFederationRollout.resolveProject(
+ ContextFederationRollout.resolve(allRequested, { coreV2ParityVerified: true }),
+ "project_scope_ready",
+ { stage: "all", percentage: 100, internalProjectScopeKeys: [], killSwitch: false },
+ )
+ const now = Date.now()
+ const missingIdentity = ContextFederationRollout.activate(eligible, {
+ state: "uninitialized",
+ identityBound: false,
+ indexAvailable: false,
+ storageHealthy: true,
+ observedAt: now,
+ expiresAt: now + 1_000,
+ })
+ expect(missingIdentity.enabled.contextProjectionV2).toBe(false)
+ expect(missingIdentity.blocked.contextProjectionV2).toContain("data_readiness_identity_missing")
+
+ const expired = ContextFederationRollout.activate(eligible, {
+ ...ContextFederationRollout.READINESS_READY_STUB,
+ observedAt: now - 2_000,
+ expiresAt: now - 1_000,
+ })
+ expect(expired.enabled.contextQueryToolsV2).toBe(false)
+ expect(expired.blocked.contextQueryToolsV2).toContain("data_readiness_expired")
+
+ const degraded = ContextFederationRollout.activate(eligible, {
+ state: "degraded",
+ identityBound: true,
+ indexAvailable: false,
+ storageHealthy: true,
+ observedAt: now,
+ expiresAt: now + 1_000,
+ })
+ expect(degraded.enabled.contextProjectionV2).toBe(false)
+ expect(degraded.enabled.contextQueryToolsV2).toBe(false)
+ expect(degraded.enabled.contextFederationShadow).toBe(true)
+
+ expect(
+ ContextFederationRollout.activate(eligible, {
+ ...ContextFederationRollout.READINESS_READY_STUB,
+ observedAt: now,
+ }).enabled,
+ ).toEqual(allRequested)
+ })
+
test("rollback rehearsal fails on durable loss or indeterminate requeue", () => {
const before = {
admissionIds: ["input_1"],
diff --git a/packages/core/test/database-migration.test.ts b/packages/core/test/database-migration.test.ts
index b0d82bdb..6a1c8416 100644
--- a/packages/core/test/database-migration.test.ts
+++ b/packages/core/test/database-migration.test.ts
@@ -4,7 +4,7 @@ import { fileURLToPath } from "url"
import path from "path"
import { SqliteClient } from "@effect/sql-sqlite-bun"
import { EffectDrizzleSqlite } from "@deepagent-code/effect-drizzle-sqlite"
-import { Effect, Layer } from "effect"
+import { Effect, Exit, Layer } from "effect"
import { eq, inArray, sql } from "drizzle-orm"
import { DatabaseMigration } from "@deepagent-code/core/database/migration"
import { migrations } from "@deepagent-code/core/database/migration.gen"
@@ -14,6 +14,10 @@ import sessionMessageProjectionOrderMigration from "@deepagent-code/core/databas
import eventSourcedSessionInputMigration from "@deepagent-code/core/database/migration/20260604172448_event_sourced_session_input"
import contextEpochAgentMigration from "@deepagent-code/core/database/migration/20260605042240_add_context_epoch_agent"
import eventDropDistinctMigration from "@deepagent-code/core/database/migration/20260712040000_deepagent_event_drop_distinct"
+import timeSuspendedMigration from "@deepagent-code/core/database/migration/20260803000000_time_suspended"
+import taskRunDeliveryMigration from "@deepagent-code/core/database/migration/20260724134000_task_run_delivery"
+import subagentControlPlaneMigration from "@deepagent-code/core/database/migration/20260803000001_subagent_control_plane_l1"
+import taskAdmissionRepairMigration from "@deepagent-code/core/database/migration/20260805000000_repair_task_admission"
import { ProjectV2 } from "@deepagent-code/core/project"
import { ProjectTable } from "@deepagent-code/core/project/sql"
import { AbsolutePath } from "@deepagent-code/core/schema"
@@ -89,6 +93,71 @@ describe("DatabaseMigration", () => {
{ name: "task_run_child_generation_idx" },
])
expect(yield* db.get(sql`SELECT count(*) as count FROM migration`)).toEqual({ count: migrations.length })
+ expect(yield* db.get(sql`SELECT name FROM pragma_table_info('session') WHERE name = 'time_suspended'`)).toEqual(
+ { name: "time_suspended" },
+ )
+ expect(
+ yield* db.get(
+ sql`SELECT name FROM sqlite_master WHERE type = 'index' AND name = 'session_time_suspended_idx'`,
+ ),
+ ).toEqual({ name: "session_time_suspended_idx" })
+ expect(
+ yield* db.get(
+ sql`SELECT name FROM sqlite_master WHERE type = 'table' AND name = 'session_tool_argument_receipt'`,
+ ),
+ ).toEqual({ name: "session_tool_argument_receipt" })
+ expect(
+ yield* db.all(
+ sql`SELECT name FROM sqlite_master WHERE type = 'index' AND name IN ('session_tool_argument_receipt_call_idx', 'session_tool_argument_receipt_created_idx') ORDER BY name`,
+ ),
+ ).toEqual([
+ { name: "session_tool_argument_receipt_call_idx" },
+ { name: "session_tool_argument_receipt_created_idx" },
+ ])
+ expect(
+ yield* db.get(
+ sql`SELECT name, dflt_value FROM pragma_table_info('session_tool_argument_receipt') WHERE name = 'validation_outcome'`,
+ ),
+ ).toEqual({ name: "validation_outcome", dflt_value: "'not_evaluated'" })
+ yield* db.run(sql`
+ INSERT INTO session_tool_request_receipt (
+ receipt_id, request_ordinal, session_id, user_message_id, provider_id, model_id,
+ registry_tool_ids, permission_filtered_tool_ids, final_offered_tool_ids, call_ids,
+ request_state, created_at
+ ) VALUES (
+ 'receipt-constraint-test', 1, 'session-constraint-test', 'message-constraint-test',
+ 'provider-test', 'model-test', '[]', '[]', '[]', '[]', 'dispatched', 1
+ )
+ `)
+ yield* db.run(sql`
+ INSERT INTO session_tool_argument_receipt (
+ receipt_id, layer, ordinal, event_type, payload_keys, unavailable_reason, created_at
+ ) VALUES (
+ 'receipt-constraint-test', 'raw_frame', 0, 'raw', '[]', 'raw_receipt_gate_disabled', 1
+ )
+ `)
+ const emptyEvidence = yield* db
+ .run(
+ sql`
+ INSERT INTO session_tool_argument_receipt (
+ receipt_id, layer, ordinal, event_type, payload_keys, created_at
+ ) VALUES (
+ 'receipt-constraint-test', 'ai_sdk_input', 0, 'tool-call', '[]', 1
+ )
+ `,
+ )
+ .pipe(Effect.exit)
+ expect(Exit.isFailure(emptyEvidence)).toBe(true)
+ const invalidOutcome = yield* db
+ .run(
+ sql`
+ UPDATE session_tool_argument_receipt
+ SET validation_outcome = 'untrusted'
+ WHERE receipt_id = 'receipt-constraint-test'
+ `,
+ )
+ .pipe(Effect.exit)
+ expect(Exit.isFailure(invalidOutcome)).toBe(true)
expect(
yield* db.all(
sql`SELECT name FROM sqlite_master WHERE type = 'index' AND name IN ('event_aggregate_seq_idx', 'event_aggregate_type_seq_idx', 'session_input_session_pending_seq_idx', 'session_input_session_pending_delivery_seq_idx', 'session_input_session_admitted_seq_idx', 'session_input_session_promoted_seq_idx', 'session_message_session_idx', 'session_message_session_type_idx', 'session_message_session_seq_idx', 'session_message_session_type_seq_idx', 'session_message_session_time_created_id_idx') ORDER BY name`,
@@ -107,6 +176,150 @@ describe("DatabaseMigration", () => {
)
})
+ test("adds nullable Session suspension without inferring historical recovery", async () => {
+ await run(
+ Effect.gen(function* () {
+ const db = yield* makeDb
+ yield* db.run(sql`CREATE TABLE session (id text PRIMARY KEY)`)
+ yield* db.run(sql`INSERT INTO session (id) VALUES ('historical')`)
+
+ yield* DatabaseMigration.applyOnly(db, [timeSuspendedMigration])
+
+ expect(yield* db.get(sql`SELECT time_suspended FROM session WHERE id = 'historical'`)).toEqual({
+ time_suspended: null,
+ })
+ expect(
+ yield* db.get(
+ sql`SELECT name FROM sqlite_master WHERE type = 'index' AND name = 'session_time_suspended_idx'`,
+ ),
+ ).toEqual({ name: "session_time_suspended_idx" })
+ }),
+ )
+ })
+
+ test("preserves historical task admission and outbox rows across the L1 rebuild", async () => {
+ await run(
+ Effect.gen(function* () {
+ const db = yield* makeDb
+ yield* db.run(sql`PRAGMA foreign_keys = ON`)
+ yield* db.run(sql`CREATE TABLE session (id TEXT PRIMARY KEY)`)
+ yield* db.run(sql`INSERT INTO session (id) VALUES ('ses_parent')`)
+ yield* DatabaseMigration.applyOnly(db, [taskRunDeliveryMigration])
+ yield* db.run(sql`
+ INSERT INTO task_run (
+ run_id, root_run_id, request_hash, parent_session_id, parent_message_id,
+ tool_call_id, child_session_id, generation, delivery_mode, phase, state,
+ attempts, time_created, time_updated
+ ) VALUES (
+ 'run_historical', 'run_historical', 'request', 'ses_parent', 'msg_parent',
+ 'call_historical', 'ses_child', 1, 'background', 'research', 'researching',
+ 2, 100, 200
+ )
+ `)
+ yield* db.run(sql`
+ INSERT INTO task_admission (
+ admission_key, request_hash, run_id, parent_session_id, parent_message_id,
+ tool_call_id, delivery_mode, time_created
+ ) VALUES (
+ 'admission_historical', 'request', 'run_historical', 'ses_parent', 'msg_parent',
+ 'call_historical', 'background', 100
+ )
+ `)
+ yield* db.run(sql`
+ INSERT INTO task_notification_outbox (
+ id, run_id, message_id, parent_session_id, directory, payload, status,
+ attempts, available_at, time_created, time_updated
+ ) VALUES (
+ 'outbox_historical', 'run_historical', 'msg_outbox', 'ses_parent', '/repo', '{}',
+ 'delivering', 1, 150, 100, 200
+ )
+ `)
+
+ yield* DatabaseMigration.applyOnly(db, [subagentControlPlaneMigration])
+
+ expect(
+ yield* db.get(
+ sql`SELECT state, phase, control_state, input_state, workspace_preflight_state, start_attempts FROM task_run WHERE run_id = 'run_historical'`,
+ ),
+ ).toEqual({
+ state: "running",
+ phase: "research",
+ control_state: "open",
+ input_state: "legacy",
+ workspace_preflight_state: "legacy",
+ start_attempts: 2,
+ })
+ expect(
+ yield* db.get(
+ sql`SELECT admission_key, origin_kind, origin_key FROM task_admission WHERE run_id = 'run_historical'`,
+ ),
+ ).toEqual({
+ admission_key: "admission_historical",
+ origin_kind: "task_tool",
+ origin_key: "admission_historical",
+ })
+ expect(
+ yield* db.get(
+ sql`SELECT status, event_kind, time_admitted FROM task_notification_outbox WHERE run_id = 'run_historical'`,
+ ),
+ ).toEqual({ status: "processing", event_kind: "terminal", time_admitted: null })
+ const activeIndex = yield* db.get<{ sql: string }>(
+ sql`SELECT sql FROM sqlite_master WHERE type = 'index' AND name = 'task_run_child_active_idx'`,
+ )
+ expect(activeIndex?.sql).toContain(
+ "WHERE state IN ('admitted', 'provisioning', 'running', 'researching', 'finalizing')",
+ )
+ expect(activeIndex?.sql).not.toContain("'queued'")
+ }),
+ )
+ })
+
+ test("repairs the canonical admission on databases already affected by the L1 cascade", async () => {
+ await run(
+ Effect.gen(function* () {
+ const db = yield* makeDb
+ yield* db.run(sql`CREATE TABLE session (id TEXT PRIMARY KEY)`)
+ yield* db.run(sql`INSERT INTO session (id) VALUES ('ses_parent')`)
+ yield* DatabaseMigration.applyOnly(db, [taskRunDeliveryMigration])
+ yield* db.run(sql`
+ INSERT INTO task_run (
+ run_id, root_run_id, request_hash, parent_session_id, parent_message_id,
+ tool_call_id, child_session_id, generation, delivery_mode, phase, state,
+ attempts, time_created, time_updated
+ ) VALUES (
+ 'run_repair', 'run_repair', 'request_repair', 'ses_parent', 'msg_repair',
+ 'call_repair', 'ses_child_repair', 1, 'foreground', 'research', 'completed',
+ 1, 100, 200
+ )
+ `)
+ yield* db.run(sql`
+ INSERT INTO task_admission (
+ admission_key, request_hash, run_id, parent_session_id, parent_message_id,
+ tool_call_id, delivery_mode, time_created
+ ) VALUES (
+ 'admission_repair', 'request_repair', 'run_repair', 'ses_parent', 'msg_repair',
+ 'call_repair', 'foreground', 100
+ )
+ `)
+ yield* DatabaseMigration.applyOnly(db, [subagentControlPlaneMigration])
+ yield* db.run(sql`DELETE FROM task_admission WHERE run_id = 'run_repair'`)
+
+ yield* DatabaseMigration.applyOnly(db, [taskAdmissionRepairMigration])
+
+ expect(
+ yield* db.get(
+ sql`SELECT admission_key, request_hash, tool_call_id, origin_key FROM task_admission WHERE run_id = 'run_repair'`,
+ ),
+ ).toEqual({
+ admission_key: "admission_repair",
+ request_hash: "request_repair",
+ tool_call_id: "call_repair",
+ origin_key: "admission_repair",
+ })
+ }),
+ )
+ })
+
test("backfills existing Context Epoch rows to the build agent", async () => {
await run(
Effect.gen(function* () {
diff --git a/packages/core/test/deepagent/failure-triage.test.ts b/packages/core/test/deepagent/failure-triage.test.ts
index 0c2b5e2e..6096b723 100644
--- a/packages/core/test/deepagent/failure-triage.test.ts
+++ b/packages/core/test/deepagent/failure-triage.test.ts
@@ -5,12 +5,12 @@ import type { ValidationResult } from "../../src/deepagent/round-state"
// T2 (S1-v3.4): classifyFailure — fixability × progress, priority RED > YELLOW > GREEN.
const vr = (over: Partial = {}): ValidationResult => ({
- command: "tsc",
- passed: false,
- exit_code: 1,
- output: "",
- duration_ms: 1,
- ...over,
+ command: over.command ?? "tsc",
+ passed: over.passed ?? false,
+ kind: over.kind ?? "command_exit",
+ exit_code: over.exit_code ?? 1,
+ output: over.output ?? "",
+ duration_ms: over.duration_ms ?? 1,
})
const base = {
@@ -25,16 +25,25 @@ const base = {
describe("failure-triage.classifyFailure", () => {
describe("🔴 not_auto_fixable (environment)", () => {
- it("exit 127 (command not found) → red", () => {
- const r = FailureTriage.classifyFailure({ ...base, failed: [vr({ exit_code: 127 })] })
+ it("typed shell bootstrap failure → red", () => {
+ const r = FailureTriage.classifyFailure({
+ ...base,
+ failed: [vr({ kind: "shell_bootstrap_failed", exit_code: -1 })],
+ })
expect(r.tier).toBe("not_auto_fixable")
- expect(r.reason).toMatch(/exit 127/)
+ expect(r.reason).toMatch(/shell_bootstrap_failed/)
})
- for (const code of [126, 124, 137, 139, 134]) {
- it(`exit ${code} → red`, () => {
- expect(FailureTriage.classifyFailure({ ...base, failed: [vr({ exit_code: code })] }).tier).toBe(
- "not_auto_fixable",
- )
+ it("a command that deliberately exits 127 is not red because of the number alone", () => {
+ const r = FailureTriage.classifyFailure({
+ ...base,
+ failed: [vr({ kind: "command_exit", exit_code: 127, output: "application-specific status" })],
+ })
+ expect(r.tier).not.toBe("not_auto_fixable")
+ expect(r.reason).not.toMatch(/exit 127/)
+ })
+ for (const kind of ["unsupported_platform", "unsupported_dialect", "timeout", "signal"] as const) {
+ it(`${kind} → red`, () => {
+ expect(FailureTriage.classifyFailure({ ...base, failed: [vr({ kind })] }).tier).toBe("not_auto_fixable")
})
}
for (const sig of [
@@ -150,13 +159,14 @@ describe("failure-triage.classifyFailure", () => {
})
describe("priority", () => {
- it("red beats yellow: env exit code wins even when stagnant", () => {
+ it("a command exit 127 does not beat yellow merely because it is 127", () => {
const r = FailureTriage.classifyFailure({
...base,
stagnant: true,
failed: [vr({ exit_code: 127, output: "error TS2322: Type X is not assignable" })],
})
- expect(r.tier).toBe("not_auto_fixable")
+ expect(r.tier).toBe("needs_narrowing")
+ expect(r.substate).toBe("stall")
})
it("yellow beats green: stall on a fixable category is not green", () => {
const r = FailureTriage.classifyFailure({
diff --git a/packages/core/test/deepagent/goal-loop.test.ts b/packages/core/test/deepagent/goal-loop.test.ts
index 87735a68..b1905721 100644
--- a/packages/core/test/deepagent/goal-loop.test.ts
+++ b/packages/core/test/deepagent/goal-loop.test.ts
@@ -10,13 +10,11 @@ import {
buildPlanFromInput,
type PlanDoc,
type PlanStep,
- type PlanInput,
} from "../../src/deepagent/plan-controller"
+import { createPlanEditCommand } from "../../src/deepagent/plan-edit-protocol"
import {
makeGoalLoop,
readGoalTickCursor,
- persistPendingPlanEdit,
- readPendingPlanEdit,
evaluateForController,
budgetNotice,
InvalidGoalError,
@@ -172,6 +170,29 @@ describe("V3.9 §D — Grader per-criterion evaluation (§D.3)", () => {
expect(res.result.gaps[0]).toMatch(/tests_pass/)
})
+ test("tests_pass preserves a typed validation runner failure in the grader gap", async () => {
+ const ports: GraderPorts = {
+ ...passingPorts(),
+ runTests: () =>
+ Effect.succeed({
+ pass: false,
+ results: [
+ {
+ command: "bun run test",
+ passed: false,
+ kind: "unsupported_platform",
+ exit_code: -1,
+ output: "run in WSL2",
+ duration_ms: 1,
+ },
+ ],
+ }),
+ }
+ const res = await Effect.runPromise(evaluateForController([criteria.tests_pass], ports, donePlan()))
+ expect(res.result.met).toBe(false)
+ expect(res.result.gaps[0]).toContain("unsupported_platform")
+ })
+
test("no_diagnostics: any diagnostic is a gap when unbounded; within bound is met", async () => {
const withDiag: GraderPorts = { ...passingPorts(), diagnostics: () => Effect.succeed({ maxSeverity: "warning" }) }
const strict = await Effect.runPromise(evaluateForController([{ kind: "no_diagnostics" }], withDiag, donePlan()))
@@ -793,7 +814,7 @@ describe("V3.9 §D — confirmed-bug regressions (2026-07-14)", () => {
const clock = new FakeClock()
// step a is done, step b is blocked → buildCompletionReport.complete is true (blocked counts as
// resolved), which previously made plan_complete report DONE and silently swallowed the blocker.
- const planDocId = putPlan([step("a", "done"), step("b", "blocked")])
+ const planDocId = putPlan([step("a", "done"), { ...step("b", "blocked"), note: "dependency unavailable" }])
const loop = makeGoalLoop(deps({}, clock))
const handle = await Effect.runPromise(loop.start(spec(planDocId)))
const outcome = await Effect.runPromise(loop.tick(handle))
@@ -805,7 +826,10 @@ describe("V3.9 §D — confirmed-bug regressions (2026-07-14)", () => {
})
test("BUG#6: evaluateForController surfaces a blocked plan as an unmet, escalating gap", async () => {
- const blockedPlan = createPlanDoc(SESSION, "g", [step("a", "done"), step("b", "blocked")])
+ const blockedPlan = createPlanDoc(SESSION, "g", [
+ step("a", "done"),
+ { ...step("b", "blocked"), note: "dependency unavailable" },
+ ])
const res = await Effect.runPromise(
evaluateForController([{ kind: "plan_complete" }], passingPorts(), blockedPlan),
)
@@ -894,11 +918,31 @@ describe("V3.9 §D — process restart recovery (§D.6 可恢复)", () => {
})
describe("V4.1 §S2 — goal plan hot-edit (applyPlanEdit)", () => {
- // A user plan edit expressed as the loose PlanInput the route/handler forwards.
- const edit = (steps: { title: string; step_id?: string; status?: string }[], goal = "reach the goal"): PlanInput => ({
- goal,
- steps,
- })
+ const edit = (
+ planDocId: string,
+ goalId: string,
+ steps: { title: string; step_id?: string; status?: string }[],
+ goal = "reach the goal",
+ operation: "advance" | "replan" = "replan",
+ ) => {
+ const doc = store.get(planDocId)!
+ const plan = JSON.parse(doc.body) as PlanDoc
+ return createPlanEditCommand({
+ requestID: `request-${crypto.randomUUID()}`,
+ sessionID: SESSION,
+ goalID: goalId,
+ planWrite: {
+ operation,
+ expected_plan_id: plan.plan_id,
+ expected_version: doc.version,
+ ...(operation === "replan" ? { replan_reason: "human goal edit" } : {}),
+ goal,
+ assumptions: plan.assumptions,
+ steps: steps.map((step) => ({ ...step, status: step.status ?? "pending" })),
+ active_step_id: steps.find((step) => step.status === "active")?.step_id ?? null,
+ },
+ })
+ }
test("upserts the edited plan to the durable doc (version+1) so the next tick sees the revision", async () => {
const clock = new FakeClock()
@@ -907,7 +951,7 @@ describe("V4.1 §S2 — goal plan hot-edit (applyPlanEdit)", () => {
const loop = makeGoalLoop(deps({}, clock))
const handle = await Effect.runPromise(loop.start(spec(planDocId)))
- await Effect.runPromise(loop.applyPlanEdit(handle, edit([{ title: "revised step", status: "pending" }])))
+ await Effect.runPromise(loop.applyPlanEdit(handle, edit(planDocId, handle.goalId, [{ title: "revised step", status: "pending" }])))
const doc = store.get(planDocId)!
expect(doc.version).toBeGreaterThan(v0)
@@ -917,7 +961,7 @@ describe("V4.1 §S2 — goal plan hot-edit (applyPlanEdit)", () => {
expect(doc.provenance.source).toBe("human")
})
- test("preserves step ids + accumulated evidence across the rewrite (buildPlanFromInput reconciliation)", async () => {
+ test("rejects retitling an existing step so evidence cannot be rebound to new work", async () => {
const clock = new FakeClock()
// Seed a plan whose step "a" already carries evidence (as the executor's mirror-back would leave it).
const seeded = createPlanDoc(SESSION, "reach the goal", [{ ...step("a", "active"), evidence: ["tests pass"] }])
@@ -932,13 +976,17 @@ describe("V4.1 §S2 — goal plan hot-edit (applyPlanEdit)", () => {
const loop = makeGoalLoop(deps({}, clock))
const handle = await Effect.runPromise(loop.start(spec(planDocId)))
- // The user re-titles the SAME step (same id) — evidence must survive (it is runtime-owned, never
- // taken from the loose input).
- await Effect.runPromise(loop.applyPlanEdit(handle, edit([{ step_id: "a", title: "renamed", status: "active" }])))
+ // Reusing the same id for a different title is ambiguous: a human edit must assign a new id before
+ // any evidence can move to the new work item.
+ await expect(
+ Effect.runPromise(
+ loop.applyPlanEdit(handle, edit(planDocId, handle.goalId, [{ step_id: "a", title: "renamed", status: "active" }])),
+ ),
+ ).rejects.toThrow("unsafe_step_identity")
const revised = JSON.parse(store.get(planDocId)!.body) as PlanDoc
expect(revised.steps[0].step_id).toBe("a")
- expect(revised.steps[0].title).toBe("renamed")
+ expect(revised.steps[0].title).toBe("a")
expect(revised.steps[0].evidence).toEqual(["tests pass"])
})
@@ -964,7 +1012,10 @@ describe("V4.1 §S2 — goal plan hot-edit (applyPlanEdit)", () => {
// User re-opens the step (done→pending) + adds a new one. The re-baseline resets stallCount to 0.
await Effect.runPromise(
- loop.applyPlanEdit(handle, edit([{ step_id: "a", title: "a", status: "pending" }, { title: "b", status: "pending" }])),
+ loop.applyPlanEdit(
+ handle,
+ edit(planDocId, handle.goalId, [{ step_id: "a", title: "a", status: "pending" }, { title: "b", status: "pending" }]),
+ ),
)
const afterEdit = await Effect.runPromise(loop.status(handle))
expect(afterEdit.stallCount).toBe(0)
@@ -975,11 +1026,24 @@ describe("V4.1 §S2 — goal plan hot-edit (applyPlanEdit)", () => {
expect(outcome).toBe("continue")
})
- test("no-op on an unknown/unstarted goal (never throws, never creates a doc)", async () => {
+ test("rejects an unknown/unstarted goal and never creates a doc", async () => {
const clock = new FakeClock()
const loop = makeGoalLoop(deps({}, clock))
const handle = { goalId: "nope", planDocId: "no-doc", sessionId: SESSION }
- await Effect.runPromise(loop.applyPlanEdit(handle, edit([{ title: "x" }])))
+ const command = createPlanEditCommand({
+ requestID: "request-unknown",
+ sessionID: SESSION,
+ goalID: "nope",
+ planWrite: {
+ operation: "create",
+ expected_plan_id: null,
+ expected_version: null,
+ goal: "reach the goal",
+ steps: [{ title: "x", status: "pending" }],
+ active_step_id: null,
+ },
+ })
+ await expect(Effect.runPromise(loop.applyPlanEdit(handle, command))).rejects.toThrow("goal state not found")
expect(store.get("no-doc")).toBeNull()
})
@@ -991,7 +1055,11 @@ describe("V4.1 §S2 — goal plan hot-edit (applyPlanEdit)", () => {
await Effect.runPromise(loop.stop(handle))
const vAfterStop = store.get(planDocId)!.version
- await Effect.runPromise(loop.applyPlanEdit(handle, edit([{ title: "revised" }])))
+ await expect(
+ Effect.runPromise(loop.applyPlanEdit(handle, edit(planDocId, handle.goalId, [{ title: "revised" }]))),
+ ).rejects.toThrow(
+ "goal is stopped",
+ )
// Terminal → the edit is ignored; the durable doc is untouched.
expect(store.get(planDocId)!.version).toBe(vAfterStop)
@@ -1018,9 +1086,15 @@ describe("V4.1 §S2 — goal plan hot-edit (applyPlanEdit)", () => {
const v0 = store.get(planDocId)!.version
// An edit that reconciles to the exact same body + same (human) provenance ⇒ INV-4 no-op.
- await Effect.runPromise(loop.applyPlanEdit(handle, edit([{ step_id: "a", title: "a", status: "pending" }])))
+ const result = await Effect.runPromise(
+ loop.applyPlanEdit(
+ handle,
+ edit(planDocId, handle.goalId, [{ step_id: "a", title: "a", status: "pending" }], "reach the goal", "advance"),
+ ),
+ )
expect(store.get(planDocId)!.version).toBe(v0)
+ expect(result.changed).toBe(false)
})
})
@@ -1268,57 +1342,3 @@ describe("V4.0.1 P2 — net-generation token accounting (§4.4/§4.5, budgetToke
expect(status.ledger.tokens).toBe(2_100) // 2 × 1050 gross — stays gross despite the flag flip
})
})
-
-// V4.0.1 P3(a) — tick idempotency / crash recovery. The infrastructure already exists (durable command
-// cursor + plan-version dedup on the event path; shared run_context doc for both drivers); these tests
-// pin the DURABILITY guarantees that the exactly-once story rests on. `persistPendingPlanEdit` /
-// `readPendingPlanEdit` are pure functions over a DocumentStore, so "cold recovery" is modeled by opening
-// a FRESH DocumentStore handle over the same on-disk root — the exact "second process" reconstruction the
-// event-driven cold-recovery test uses (goal-tick-cold-recovery.test.ts).
-describe("V4.0.1 P3(a) — pendingPlanEdit durability + cold recovery", () => {
- const GOAL = "g-pending-1"
- const editInput: PlanInput = { goal: "reach the goal", steps: [{ title: "revised", status: "pending" }] }
-
- test("a persisted pending edit survives a process restart (fresh store over the same root)", () => {
- persistPendingPlanEdit(store, SESSION, GOAL, editInput)
-
- // Simulate a process restart: NOTHING in memory, only the run_context doc on disk. A brand-new store
- // handle over the same root must reconstruct the pending edit byte-for-byte.
- const recovered = readPendingPlanEdit(new DocumentStore(root), SESSION, GOAL)
- expect(recovered).toEqual(editInput)
- })
-
- test("consume-once: writing the null sentinel clears the edit, and a re-read after restart stays cleared", () => {
- persistPendingPlanEdit(store, SESSION, GOAL, editInput)
- expect(readPendingPlanEdit(store, SESSION, GOAL)).toEqual(editInput)
-
- // markPlanEditConsumed persists the empty-body sentinel (plan == null). Once consumed it must never
- // re-materialize — not on this handle, and not after a cold restart.
- persistPendingPlanEdit(store, SESSION, GOAL, null)
- expect(readPendingPlanEdit(store, SESSION, GOAL)).toBeNull()
- expect(readPendingPlanEdit(new DocumentStore(root), SESSION, GOAL)).toBeNull()
- })
-
- test("a pending edit is keyed per goal — reading a different goalId never returns another goal's edit", () => {
- persistPendingPlanEdit(store, SESSION, GOAL, editInput)
- // pending_edit_goal_id scopes the doc: a sibling goal in the same session sees nothing.
- expect(readPendingPlanEdit(new DocumentStore(root), SESSION, "g-other")).toBeNull()
- expect(readPendingPlanEdit(new DocumentStore(root), SESSION, GOAL)).toEqual(editInput)
- })
-
- test("the latest write wins across a restart (a newer edit persisted after read is preserved)", () => {
- persistPendingPlanEdit(store, SESSION, GOAL, editInput)
- const newer: PlanInput = { goal: "reach the goal", steps: [{ title: "newer step", status: "active" }] }
- // A second edit lands (e.g. the user revised again before the first was consumed) — the durable doc
- // reflects the newest content, and a cold reader sees it.
- persistPendingPlanEdit(store, SESSION, GOAL, newer)
- expect(readPendingPlanEdit(new DocumentStore(root), SESSION, GOAL)).toEqual(newer)
- })
-
- test("the pending-edit doc is invisible to the goal-tick cursor (kept off loadState's run_context match)", () => {
- // The pending-edit doc uses `pending_edit_goal_id`, NOT `goal_id`, so it must never be mistaken for the
- // goal's run-state doc — otherwise readGoalTickCursor could parse the edit body as GoalRuntimeState.
- persistPendingPlanEdit(store, SESSION, GOAL, editInput)
- expect(readGoalTickCursor(new DocumentStore(root), SESSION, GOAL)).toBeNull()
- })
-})
diff --git a/packages/core/test/deepagent/plan-controller.test.ts b/packages/core/test/deepagent/plan-controller.test.ts
index b993dcc8..db00d248 100644
--- a/packages/core/test/deepagent/plan-controller.test.ts
+++ b/packages/core/test/deepagent/plan-controller.test.ts
@@ -8,6 +8,11 @@ import {
isMutatingTool,
createPlanDoc,
buildPlanFromInput,
+ buildPlanFromWriteInput,
+ decodePlanWriteInput,
+ PlanConflictError,
+ PlanValidationError,
+ planWriteCandidateHash,
planProgress,
planScope,
DEFAULT_REPLAN_LIMIT,
@@ -252,6 +257,343 @@ describe("plan doc scaffold", () => {
})
})
+describe("strict plan write admission", () => {
+ const input = (overrides: Partial[1]> = {}) => ({
+ operation: "create" as const,
+ expected_plan_id: null,
+ expected_version: null,
+ goal: "ship a reliable change",
+ steps: [
+ { step_id: "s1", title: "implement", status: "active" as const, acceptance: "tests pass" },
+ { step_id: "s2", title: "verify", status: "pending" as const, acceptance: "review complete" },
+ ],
+ active_step_id: "s1",
+ ...overrides,
+ })
+
+ test("admits create and normalizes the explicit status vocabulary", () => {
+ const plan = buildPlanFromWriteInput("s1", input(), null, null)
+ expect(plan.steps.map((step) => step.status)).toEqual(["active", "pending"])
+ expect(plan.active_step_id).toBe("s1")
+ })
+
+ test("decodes untrusted plan writes and hashes normalized semantics without leaking content", () => {
+ const value = input({
+ goal: " ship a reliable change ",
+ steps: [
+ { title: " implement ", status: "ACTIVE", acceptance: " tests pass " },
+ { title: "verify", status: "pending" },
+ ],
+ active_step_id: null,
+ })
+ const decoded = decodePlanWriteInput(value)
+ expect(decoded).not.toBeNull()
+ expect(decodePlanWriteInput({ ...value, expected_version: 1.5 })).toBeNull()
+ expect(decodePlanWriteInput({ ...value, steps: [{ title: "x", status: 4 }] })).toBeNull()
+ const hash = planWriteCandidateHash(decoded!)
+ expect(hash).toMatch(/^sha256:[a-f0-9]{64}$/)
+ expect(hash).not.toContain("ship a reliable change")
+ expect(hash).toBe(planWriteCandidateHash({ ...decoded!, goal: "ship a reliable change" }))
+ })
+
+ test("quality challenge uses a stable candidate hash and a fresh challenge id", () => {
+ const previous = buildPlanFromWriteInput("s1", input(), null, null)
+ const candidate = input({
+ operation: "replan",
+ expected_plan_id: previous.plan_id,
+ expected_version: 1,
+ replan_reason: "replace unresolved work",
+ steps: [{ title: "do it", status: "pending" }],
+ active_step_id: null,
+ })
+ const capture = () => {
+ try {
+ buildPlanFromWriteInput(
+ "s1",
+ candidate,
+ previous,
+ { plan_id: previous.plan_id, doc_id: "doc:plan:s1", version: 1 },
+ )
+ throw new Error("candidate unexpectedly admitted")
+ } catch (error) {
+ expect(error).toBeInstanceOf(PlanValidationError)
+ return error as PlanValidationError
+ }
+ }
+ const first = capture()
+ const second = capture()
+ expect(first.candidate_hash).toBe(planWriteCandidateHash(candidate))
+ expect(second.candidate_hash).toBe(first.candidate_hash)
+ expect(second.challenge_id).not.toBe(first.challenge_id)
+ })
+
+ test("rejects malformed steps before any store write", () => {
+ expect(() =>
+ buildPlanFromWriteInput(
+ "s1",
+ input({ steps: [{ step_id: "s1", title: "", status: "active" }], active_step_id: "s1" }),
+ null,
+ null,
+ ),
+ ).toThrow("empty_title")
+ expect(() =>
+ buildPlanFromWriteInput(
+ "s1",
+ input({ steps: [{ step_id: "s1", title: "implement", status: "sideways" as never }], active_step_id: "s1" }),
+ null,
+ null,
+ ),
+ ).toThrow("invalid_status")
+ })
+
+ test("requires exact identity and version for advance", () => {
+ const previous = buildPlanFromWriteInput("s1", input(), null, null)
+ const ref = { plan_id: previous.plan_id, doc_id: "doc:plan:s1", version: 1 }
+ expect(() =>
+ buildPlanFromWriteInput(
+ "s1",
+ input({ operation: "advance", expected_plan_id: previous.plan_id, expected_version: 0 }),
+ previous,
+ ref,
+ ),
+ ).toThrow(PlanConflictError)
+ expect(() =>
+ buildPlanFromWriteInput(
+ "s1",
+ input({ operation: "advance", expected_plan_id: previous.plan_id, expected_version: 1, steps: [{ title: "implement", status: "done" }] }),
+ previous,
+ ref,
+ ),
+ ).toThrow(PlanValidationError)
+ })
+
+ test("advance preserves ordered step identity and immutable goal contracts", () => {
+ const previous = buildPlanFromWriteInput("s1", input(), null, null)
+ const ref = { plan_id: previous.plan_id, doc_id: "doc:plan:s1", version: 1 }
+ expect(() =>
+ buildPlanFromWriteInput(
+ "s1",
+ input({
+ operation: "advance",
+ expected_plan_id: previous.plan_id,
+ expected_version: 1,
+ goal: "a different goal",
+ steps: [
+ { step_id: "s2", title: "verify", status: "active", acceptance: "review complete" },
+ { step_id: "s1", title: "implement", status: "done", acceptance: "tests pass" },
+ ],
+ active_step_id: "s2",
+ }),
+ previous,
+ ref,
+ ),
+ ).toThrow("unsafe_step_identity")
+ })
+
+ test("quality challenge rejects a replan that drops unresolved work", () => {
+ const previous = buildPlanFromWriteInput("s1", input(), null, null)
+ const ref = { plan_id: previous.plan_id, doc_id: "doc:plan:s1", version: 1 }
+ expect(() =>
+ buildPlanFromWriteInput(
+ "s1",
+ input({
+ operation: "replan",
+ expected_plan_id: previous.plan_id,
+ expected_version: 1,
+ replan_reason: "provider correction",
+ steps: [{ step_id: "new", title: "do it", status: "active" }],
+ active_step_id: "new",
+ }),
+ previous,
+ ref,
+ ),
+ ).toThrow("suspicious_quality_regression")
+ })
+
+ test("quality oracle covers A/B/C, equality boundaries, and Unicode code points", () => {
+ const write = (
+ previous: PlanDoc,
+ steps: Parameters[1]["steps"],
+ activeStepId: string | null,
+ ) =>
+ buildPlanFromWriteInput(
+ "s1",
+ {
+ operation: "replan",
+ expected_plan_id: previous.plan_id,
+ expected_version: 1,
+ replan_reason: "intentional test replan",
+ goal: previous.goal,
+ assumptions: previous.assumptions,
+ steps,
+ active_step_id: activeStepId,
+ },
+ previous,
+ { plan_id: previous.plan_id, doc_id: "doc:plan:s1", version: 1 },
+ )
+
+ const aPrevious = buildPlanFromWriteInput(
+ "s1",
+ input({
+ steps: [
+ { step_id: "a1", title: "abcdefghij", status: "active" },
+ { step_id: "a2", title: "abcdefghij", status: "pending" },
+ { step_id: "a3", title: "abcdefghij", status: "pending" },
+ { step_id: "a4", title: "abcdefghij", status: "pending" },
+ ],
+ active_step_id: "a1",
+ }),
+ null,
+ null,
+ )
+ expect(() =>
+ write(
+ aPrevious,
+ [
+ { step_id: "a1", title: "abcdefghij", status: "active" },
+ { step_id: "a2", title: "abcdefghij", status: "pending" },
+ ],
+ "a1",
+ ),
+ ).not.toThrow()
+ expect(() =>
+ write(
+ aPrevious,
+ [
+ { step_id: "new-a1", title: "abcdefghij", status: "active" },
+ { step_id: "new-a2", title: "abcdefghi", status: "pending" },
+ ],
+ "new-a1",
+ ),
+ ).toThrow("suspicious_quality_regression")
+
+ const bPrevious = buildPlanFromWriteInput(
+ "s1",
+ input({
+ steps: [
+ { step_id: "b1", title: "first accepted work item", status: "active", acceptance: "first proof" },
+ { step_id: "b2", title: "second accepted work item", status: "pending", acceptance: "second proof" },
+ ],
+ active_step_id: "b1",
+ }),
+ null,
+ null,
+ )
+ expect(() =>
+ write(
+ bPrevious,
+ [
+ { step_id: "new-b1", title: "replacement work item one", status: "active" },
+ { step_id: "new-b2", title: "replacement work item two", status: "pending" },
+ ],
+ "new-b1",
+ ),
+ ).toThrow("suspicious_quality_regression")
+ expect(() =>
+ write(
+ bPrevious,
+ [
+ { step_id: "new-b1", title: "replacement work item one", status: "active", acceptance: "new proof one" },
+ { step_id: "new-b2", title: "replacement work item two", status: "pending", acceptance: "new proof two" },
+ ],
+ "new-b1",
+ ),
+ ).not.toThrow()
+
+ const cPrevious = buildPlanFromWriteInput(
+ "s1",
+ input({
+ steps: [
+ { step_id: "c1", title: "first unresolved work", status: "active" },
+ { step_id: "c2", title: "second unresolved work", status: "pending" },
+ ],
+ active_step_id: "c1",
+ }),
+ null,
+ null,
+ )
+ expect(() =>
+ write(
+ cPrevious,
+ [
+ { step_id: "new-c1", title: "one", status: "active" },
+ { step_id: "new-c2", title: "two", status: "pending" },
+ ],
+ "new-c1",
+ ),
+ ).toThrow("suspicious_quality_regression")
+
+ const unicodePrevious = buildPlanFromWriteInput(
+ "s1",
+ input({
+ steps: [
+ { step_id: "u1", title: "😀😀", status: "active" },
+ { step_id: "u2", title: "😀😀", status: "pending" },
+ ],
+ active_step_id: "u1",
+ }),
+ null,
+ null,
+ )
+ expect(() => write(unicodePrevious, [{ step_id: "u1", title: "😀😀", status: "active" }], "u1")).not.toThrow()
+ })
+
+ test("deterministic incident fixture rejects all 11 malformed forward-compatible replans", () => {
+ const previous = buildPlanFromWriteInput(
+ "s1",
+ input({
+ steps: [
+ { step_id: "s1", title: "inspect the repository", status: "done", acceptance: "repository is understood" },
+ { step_id: "s2", title: "implement the guarded write path", status: "active", acceptance: "write path is validated" },
+ { step_id: "s3", title: "exercise the regression fixture", status: "pending", acceptance: "fixture is deterministic" },
+ { step_id: "s4", title: "verify persistence and recovery", status: "pending", acceptance: "recovery is covered" },
+ { step_id: "s5", title: "review the final diff", status: "pending", acceptance: "review is complete" },
+ ],
+ active_step_id: "s2",
+ }),
+ null,
+ null,
+ )
+ const ref = { plan_id: previous.plan_id, doc_id: "doc:plan:s1", version: 1 }
+ const malformed = [
+ ["ayContext", "active"],
+ ["Context", "pending"],
+ ["Context", "active"],
+ ["Context", "active"],
+ ["", ""],
+ ["Context", "active"],
+ ["", "active"],
+ ["Context", "pending"],
+ ["", "active"],
+ ["Context", "active"],
+ ["Context", "active"],
+ ] as const
+
+ for (const [title, status] of malformed) {
+ const candidate = {
+ operation: "replan" as const,
+ expected_plan_id: previous.plan_id,
+ expected_version: 1,
+ replan_reason: "provider returned a malformed plan payload",
+ goal: previous.goal,
+ assumptions: previous.assumptions,
+ steps: [{ step_id: "s2", title, status: status as "pending" | "active" }],
+ active_step_id: status === "active" ? "s2" : null,
+ }
+ expect(() => buildPlanFromWriteInput("s1", candidate, previous, ref)).toThrow(PlanValidationError)
+ try {
+ buildPlanFromWriteInput("s1", candidate, previous, ref)
+ throw new Error("fixture candidate unexpectedly admitted")
+ } catch (error) {
+ expect(error).toBeInstanceOf(PlanValidationError)
+ expect(["empty_title", "invalid_status", "unsafe_step_identity", "suspicious_quality_regression"]).toContain(
+ (error as PlanValidationError).code,
+ )
+ }
+ }
+ })
+})
+
// U10 step-reporting -----------------------------------------------------------------------------
const mkPlan = (steps: PlanDoc["steps"], activeId: string | null = null): PlanDoc => ({
plan_id: "p1",
@@ -347,6 +689,8 @@ describe("plan snapshot render", () => {
expect(out).toContain("[!] deploy")
expect(out).toContain("[ ] docs")
expect(out).toContain("Active step: test")
+ expect(out).toContain("goal:")
+ expect(renderPlanSnapshot(plan, "continuation")).not.toContain("goal:")
})
})
diff --git a/packages/core/test/deepagent/plan-edit-protocol.test.ts b/packages/core/test/deepagent/plan-edit-protocol.test.ts
new file mode 100644
index 00000000..5fbd08ab
--- /dev/null
+++ b/packages/core/test/deepagent/plan-edit-protocol.test.ts
@@ -0,0 +1,248 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test"
+import { mkdtempSync, rmSync } from "node:fs"
+import { tmpdir } from "node:os"
+import path from "node:path"
+import { DocumentStore } from "../../src/deepagent/document-store"
+import {
+ PlanEditBusyError,
+ PlanEditChallengeError,
+ PlanEditMailboxConflictError,
+ PlanEditProtocolCorruptionError,
+ PlanEditRequestConflictError,
+ admitPlanEditCommand,
+ createPlanEditCommand,
+ decodePlanEditReceipt,
+ issuePlanEditChallenge,
+ readPendingPlanEditCommand,
+ readPlanEditReceipt,
+ readPlanEditReceiptByRequest,
+ settlePlanEditCommand,
+} from "../../src/deepagent/plan-edit-protocol"
+import type { PlanWriteInput } from "../../src/deepagent/plan-controller"
+
+let root: string
+let store: DocumentStore
+
+const write: PlanWriteInput = {
+ operation: "advance",
+ expected_plan_id: "plan_1",
+ expected_version: 3,
+ goal: "ship safely",
+ assumptions: ["authority exists"],
+ steps: [
+ { step_id: "s1", title: "implement", status: "done", acceptance: "tests pass" },
+ { step_id: "s2", title: "verify", status: "active", acceptance: "review complete" },
+ ],
+ active_step_id: "s2",
+}
+
+beforeEach(() => {
+ root = mkdtempSync(path.join(tmpdir(), "deepagent-plan-edit-"))
+ store = new DocumentStore(root)
+})
+
+afterEach(() => {
+ DocumentStore.__resetSharedRegistryForTests()
+ rmSync(root, { recursive: true, force: true })
+})
+
+describe("durable plan edit protocol", () => {
+ test("queues durably, survives a reopened store, and clears pending work after settlement", () => {
+ const command = createPlanEditCommand({
+ requestID: "request-1",
+ sessionID: "session-1",
+ goalID: "goal-1",
+ planWrite: write,
+ })
+ expect(admitPlanEditCommand(store, command).state).toBe("queued")
+ expect(readPendingPlanEditCommand(new DocumentStore(root), "session-1", "goal-1")).toEqual(command)
+
+ settlePlanEditCommand(store, command, {
+ state: "rejected",
+ failure: {
+ kind: "validation",
+ code: "unsafe_step_identity",
+ offending_step_ids: ["s2"],
+ previous_plan_id: "plan_1",
+ previous_plan_version: 3,
+ },
+ })
+ expect(readPendingPlanEditCommand(store, "session-1", "goal-1")).toBeNull()
+ expect(readPlanEditReceipt(new DocumentStore(root), "session-1", "goal-1")?.state).toBe("rejected")
+ })
+
+ test("preserves nullable HTTP plan fields across a mailbox reopen", () => {
+ const nullableWrite: PlanWriteInput = {
+ ...write,
+ steps: [
+ { step_id: "s1", title: "implement", status: "done", acceptance: null, assigned_agent: null, note: null },
+ { step_id: "s2", title: "verify", status: "active", acceptance: "review complete", note: null },
+ ],
+ }
+ const command = createPlanEditCommand({
+ requestID: "request-nullable",
+ sessionID: "session-1",
+ goalID: "goal-1",
+ planWrite: nullableWrite,
+ })
+
+ admitPlanEditCommand(store, command)
+
+ expect(readPendingPlanEditCommand(new DocumentStore(root), "session-1", "goal-1")).toEqual(command)
+ })
+
+ test("reconciles exact request retries and rejects last-write-wins overwrite", () => {
+ const command = createPlanEditCommand({
+ requestID: "request-1",
+ sessionID: "session-1",
+ goalID: "goal-1",
+ planWrite: write,
+ })
+ const first = admitPlanEditCommand(store, command)
+ expect(admitPlanEditCommand(store, command)).toEqual(first)
+ expect(() =>
+ admitPlanEditCommand(
+ store,
+ createPlanEditCommand({ requestID: "request-2", sessionID: "session-1", goalID: "goal-1", planWrite: write }),
+ ),
+ ).toThrow(PlanEditBusyError)
+ })
+
+ test("reconciles a historical request after newer activities and rejects conflicting reuse", () => {
+ const first = createPlanEditCommand({
+ requestID: "request-1",
+ sessionID: "session-1",
+ goalID: "goal-1",
+ planWrite: write,
+ })
+ admitPlanEditCommand(store, first)
+ const firstReceipt = settlePlanEditCommand(store, first, {
+ state: "applied",
+ result: { plan_id: "plan_1", doc_id: "doc:plan:1", version: 4, changed: true },
+ })
+ const secondWrite = { ...write, expected_version: 4, steps: write.steps.map((step) => ({ ...step })) }
+ const second = createPlanEditCommand({
+ requestID: "request-2",
+ sessionID: "session-1",
+ goalID: "goal-1",
+ planWrite: secondWrite,
+ })
+ admitPlanEditCommand(store, second)
+ settlePlanEditCommand(store, second, {
+ state: "applied",
+ result: { plan_id: "plan_1", doc_id: "doc:plan:1", version: 4, changed: false },
+ })
+
+ expect(admitPlanEditCommand(store, first)).toEqual(firstReceipt)
+ expect(readPlanEditReceiptByRequest(store, "session-1", "goal-1", "request-1")).toEqual(firstReceipt)
+ expect(() =>
+ admitPlanEditCommand(
+ store,
+ createPlanEditCommand({
+ requestID: "request-1",
+ sessionID: "session-1",
+ goalID: "goal-1",
+ planWrite: { ...write, goal: "different content" },
+ }),
+ ),
+ ).toThrow(PlanEditRequestConflictError)
+ })
+
+ test("binds quality confirmation to challenge, candidate, version, and expiry", () => {
+ const now = new Date("2026-08-07T00:00:00.000Z")
+ const candidate = createPlanEditCommand({
+ requestID: "request-challenge",
+ sessionID: "session-1",
+ goalID: "goal-1",
+ planWrite: { ...write, operation: "replan", replan_reason: "intentional replacement" },
+ now,
+ })
+ const challenged = issuePlanEditChallenge(store, candidate, "challenge-1", now)
+ expect(challenged.state).toBe("challenged")
+
+ const mismatched = createPlanEditCommand({
+ requestID: "request-confirm-mismatch",
+ sessionID: "session-1",
+ goalID: "goal-1",
+ planWrite: { ...candidate.plan_write, expected_version: 4 },
+ confirmedChallengeID: "challenge-1",
+ now,
+ })
+ expect(() => admitPlanEditCommand(store, mismatched, now)).toThrow(PlanEditChallengeError)
+
+ const confirmed = createPlanEditCommand({
+ requestID: "request-confirm",
+ sessionID: "session-1",
+ goalID: "goal-1",
+ planWrite: candidate.plan_write,
+ confirmedChallengeID: "challenge-1",
+ now,
+ })
+ expect(admitPlanEditCommand(store, confirmed, new Date("2026-08-07T00:14:59.000Z")).state).toBe("queued")
+
+ const expiredCandidate = createPlanEditCommand({
+ requestID: "request-expired",
+ sessionID: "session-2",
+ goalID: "goal-2",
+ planWrite: candidate.plan_write,
+ now,
+ })
+ issuePlanEditChallenge(store, expiredCandidate, "challenge-expired", now)
+ const expiredConfirmation = createPlanEditCommand({
+ requestID: "request-expired-confirm",
+ sessionID: "session-2",
+ goalID: "goal-2",
+ planWrite: candidate.plan_write,
+ confirmedChallengeID: "challenge-expired",
+ now,
+ })
+ expect(() => admitPlanEditCommand(store, expiredConfirmation, new Date("2026-08-07T00:15:00.000Z"))).toThrow(
+ PlanEditChallengeError,
+ )
+ })
+
+ test("detects cross-handle CAS races instead of overwriting a mailbox", () => {
+ const first = new DocumentStore(root)
+ const stale = new DocumentStore(root)
+ admitPlanEditCommand(
+ first,
+ createPlanEditCommand({ requestID: "request-1", sessionID: "session-1", goalID: "goal-1", planWrite: write }),
+ )
+ expect(() =>
+ admitPlanEditCommand(
+ stale,
+ createPlanEditCommand({ requestID: "request-2", sessionID: "session-1", goalID: "goal-1", planWrite: write }),
+ ),
+ ).toThrow(PlanEditMailboxConflictError)
+ })
+
+ test("fails closed on malformed or internally inconsistent receipts", () => {
+ const command = createPlanEditCommand({
+ requestID: "request-1",
+ sessionID: "session-1",
+ goalID: "goal-1",
+ planWrite: write,
+ })
+ expect(
+ decodePlanEditReceipt({
+ protocol_version: 1,
+ state: "applied",
+ command,
+ updated_at: new Date().toISOString(),
+ result: { plan_id: "plan_1", doc_id: "doc:plan:1", version: 4, changed: true },
+ failure: { kind: "runtime_error", message: "must not coexist" },
+ }),
+ ).toBeNull()
+
+ store.upsert({
+ type: "run_context",
+ scope: "run:session-1",
+ description: "corrupt mailbox",
+ idSlug: "corrupt-mailbox",
+ body: "{not-json",
+ provenance: { source: "human" },
+ extensions: { plan_edit_goal_id: "goal-1" },
+ })
+ expect(() => readPlanEditReceipt(store, "session-1", "goal-1")).toThrow(PlanEditProtocolCorruptionError)
+ })
+})
diff --git a/packages/core/test/deepagent/plan-gate-loop.test.ts b/packages/core/test/deepagent/plan-gate-loop.test.ts
index ec3b5155..4f808ae2 100644
--- a/packages/core/test/deepagent/plan-gate-loop.test.ts
+++ b/packages/core/test/deepagent/plan-gate-loop.test.ts
@@ -43,7 +43,7 @@ describe("U1 soft-gate loop (chokepoint contract)", () => {
// a failing validation flips the latch from runtime truth
SessionState.recordValidation(
"gate-s1",
- [{ command: "tsc", passed: false, exit_code: 1, output: "e", duration_ms: 1 }],
+ [{ command: "tsc", passed: false, kind: "command_exit", exit_code: 1, output: "e", duration_ms: 1 }],
"e",
)
diff --git a/packages/core/test/deepagent/plan-store.test.ts b/packages/core/test/deepagent/plan-store.test.ts
index 6120646e..e0658392 100644
--- a/packages/core/test/deepagent/plan-store.test.ts
+++ b/packages/core/test/deepagent/plan-store.test.ts
@@ -5,7 +5,13 @@ import path from "node:path"
import * as PlanStore from "../../src/deepagent/plan-store"
import * as SessionState from "../../src/deepagent/session-state"
import { DocumentStore } from "../../src/deepagent/document-store"
-import { createPlanDoc, type PlanDoc, type PlanStep } from "../../src/deepagent/plan-controller"
+import {
+ createPlanDoc,
+ PlanConflictError,
+ PlanValidationError,
+ type PlanDoc,
+ type PlanStep,
+} from "../../src/deepagent/plan-controller"
// I33-1 (deepagentcore-v4.0.3): the DocumentStore `type:"plan"` doc is the SINGLE structural authority
// for a session's plan. session-state.setPlan/getPlan delegate to plan-store; the goal path writes the
@@ -65,6 +71,106 @@ describe("I33-1 plan-store single authority", () => {
expect(PlanStore.getPlanDoc("s2")?.steps[0].status).toBe("done")
})
+ test("compareAndCommitPlan enforces a logical version precondition", () => {
+ const sid = "s_cas"
+ const first = plan(sid, [step("step_1")])
+ const created = PlanStore.compareAndCommitPlan({ sessionId: sid, expected: null, candidate: first, origin: "model_tool" })
+ expect(created.version).toBe(1)
+ const expected = { plan_id: first.plan_id, doc_id: created.doc_id, version: created.version }
+ const second = { ...first, steps: [{ ...first.steps[0], status: "done" as const }] }
+ const committed = PlanStore.compareAndCommitPlan({ sessionId: sid, expected, candidate: second, origin: "model_tool" })
+ expect(committed.version).toBe(2)
+ expect(() =>
+ PlanStore.compareAndCommitPlan({
+ sessionId: sid,
+ expected,
+ candidate: { ...second, goal: "stale writer" },
+ origin: "model_tool",
+ }),
+ ).toThrow(PlanConflictError)
+ expect(PlanStore.planDocRef(sid)?.version).toBe(2)
+ })
+
+ test("compareAndCommitPlan refuses to overwrite an existing malformed authority", () => {
+ const sid = "s_malformed"
+ const authority = DocumentStore.shared(PlanStore.planStoreRoot(sid))
+ authority.upsert({
+ type: "plan",
+ scope: PlanStore.planScope(sid),
+ description: PlanStore.planDescription(sid),
+ idSlug: `plan-${sid}`,
+ body: "{not-json",
+ provenance: { source: "model", run_ref: PlanStore.planScope(sid) },
+ })
+ expect(() =>
+ PlanStore.compareAndCommitPlan({
+ sessionId: sid,
+ expected: null,
+ candidate: plan(sid, [step("step_1")]),
+ origin: "legacy_migration",
+ }),
+ ).toThrow(PlanValidationError)
+ expect(authority.list({ type: "plan", scope: PlanStore.planScope(sid) })).toHaveLength(1)
+ })
+
+ test("compareAndCommitPlan refuses parseable authorities that violate PlanDoc invariants", () => {
+ const fixtures = [
+ (value: PlanDoc): unknown => ({ ...value, steps: [] }),
+ (value: PlanDoc): unknown => ({ ...value, steps: [{ ...value.steps[0], status: "unknown" }] }),
+ (value: PlanDoc): unknown => ({ ...value, active_step_id: value.steps[0]!.step_id }),
+ ]
+
+ fixtures.forEach((malform, index) => {
+ const sid = `s_malformed_shape_${index}`
+ const authority = DocumentStore.shared(PlanStore.planStoreRoot(sid))
+ const malformed = malform(plan(sid, [step("step_1")]))
+ const stored = authority.upsert({
+ type: "plan",
+ scope: PlanStore.planScope(sid),
+ description: PlanStore.planDescription(sid),
+ idSlug: `plan-${sid}`,
+ body: JSON.stringify(malformed),
+ provenance: { source: "model", run_ref: PlanStore.planScope(sid) },
+ })
+
+ expect(PlanStore.getPlanDoc(sid)).toBeNull()
+ expect(() =>
+ PlanStore.compareAndCommitPlan({
+ sessionId: sid,
+ expected: null,
+ candidate: plan(sid, [step("replacement")]),
+ origin: "legacy_migration",
+ }),
+ ).toThrow(PlanValidationError)
+ expect(authority.get(stored.id)?.body).toBe(JSON.stringify(malformed))
+ expect(authority.get(stored.id)?.version).toBe(1)
+ })
+ })
+
+ test("compareAndCommitPlan validates the candidate at the CAS boundary", () => {
+ const sid = "s_invalid_candidate"
+ const malformed = { ...plan(sid, [step("step_1")]), steps: [] } as PlanDoc
+ expect(() =>
+ PlanStore.compareAndCommitPlan({
+ sessionId: sid,
+ expected: null,
+ candidate: malformed,
+ origin: "runtime_goal_bridge",
+ }),
+ ).toThrow(PlanValidationError)
+ expect(DocumentStore.shared(PlanStore.planStoreRoot(sid)).list({ type: "plan" })).toHaveLength(0)
+
+ expect(() =>
+ PlanStore.compareAndCommitPlan({
+ sessionId: sid,
+ expected: null,
+ candidate: { ...plan(sid, [step("step_1")]), session_id: "another-session" },
+ origin: "runtime_goal_bridge",
+ }),
+ ).toThrow(PlanValidationError)
+ expect(DocumentStore.shared(PlanStore.planStoreRoot(sid)).list({ type: "plan" })).toHaveLength(0)
+ })
+
test("session-state.setPlan/getPlan delegate to the store (body NOT on session state)", async () => {
SessionState.getOrCreate("s3", "high")
const p = plan("s3", [step("step_1")])
@@ -160,4 +266,43 @@ describe("I33-1 plan-store single authority", () => {
SessionState.configure(stateDir) // load; migration sees the store already has a plan -> skips
expect(PlanStore.getPlanDoc("s7")?.steps[0].status).toBe("done") // newer store doc preserved
})
+
+ test("legacy migration rejects a malformed inline plan instead of making it authoritative", () => {
+ const malformed = { ...plan("s8", [step("step_1")]), steps: [] }
+ mkdirSync(stateDir, { recursive: true })
+ writeFileSync(
+ path.join(stateDir, "sessions.json"),
+ JSON.stringify({
+ s8: {
+ sessionId: "s8",
+ mode: "high",
+ completedAt: null,
+ planLatch: {
+ plan_id: malformed.plan_id,
+ latch: "fresh",
+ stale_reason: null,
+ replan_count: 0,
+ consecutive_blocks: 0,
+ },
+ plan: malformed,
+ },
+ }),
+ )
+ DocumentStore.__resetSharedRegistryForTests()
+ SessionState.configure(stateDir)
+ expect(PlanStore.getPlanDoc("s8")).toBeNull()
+ expect(SessionState.getPlan("s8")).toBeNull()
+ const diagnostics = DocumentStore.shared(PlanStore.planStoreRoot("s8")).list({
+ type: "diagnosis",
+ scope: PlanStore.planScope("s8"),
+ status: "quarantined",
+ })
+ expect(diagnostics).toHaveLength(1)
+ expect(JSON.parse(DocumentStore.shared(PlanStore.planStoreRoot("s8")).get(diagnostics[0]!.id)!.body)).toMatchObject({
+ kind: "legacy_plan_migration",
+ session_id: "s8",
+ plan_id: malformed.plan_id,
+ code: "empty_steps",
+ })
+ })
})
diff --git a/packages/core/test/deepagent/prompt-policy.test.ts b/packages/core/test/deepagent/prompt-policy.test.ts
index 166e2c31..0c5248ce 100644
--- a/packages/core/test/deepagent/prompt-policy.test.ts
+++ b/packages/core/test/deepagent/prompt-policy.test.ts
@@ -1,5 +1,10 @@
import { describe, expect, test } from "bun:test"
-import { buildSystemPrompt, buildVolatileRoundContext, type PromptContext } from "../../src/deepagent/prompt-policy"
+import {
+ buildSystemPrompt,
+ buildVolatileContinuationContext,
+ buildVolatileRoundContext,
+ type PromptContext,
+} from "../../src/deepagent/prompt-policy"
import type { ActivationDecision } from "../../src/deepagent/activation-policy"
import type { RoundState } from "../../src/deepagent/round-state"
@@ -204,4 +209,15 @@ describe("buildVolatileRoundContext", () => {
expect(vol).not.toContain("本体直接完成")
expect(vol).not.toContain("level=0")
})
+
+ test("tool continuation omits task, activation, results, and budget restatements", () => {
+ const vol = buildVolatileContinuationContext()
+ expect(vol).toContain("")
+ expect(vol).toContain("Continue directly from the immediately preceding tool result")
+ expect(vol).toContain("Do not restate or re-summarize")
+ expect(vol).not.toContain("# Task Context")
+ expect(vol).not.toContain("# Activation")
+ expect(vol).not.toContain("# Previous Round Results")
+ expect(vol).not.toContain("Token budget remaining")
+ })
})
diff --git a/packages/core/test/deepagent/round-report.test.ts b/packages/core/test/deepagent/round-report.test.ts
index c5be8c12..51ac4776 100644
--- a/packages/core/test/deepagent/round-report.test.ts
+++ b/packages/core/test/deepagent/round-report.test.ts
@@ -9,8 +9,22 @@ import {
type RunnerGroundTruth,
} from "../../src/deepagent/round-report"
-const pass = (command: string) => ({ command, passed: true, exit_code: 0, output: "ok", duration_ms: 1 })
-const fail = (command: string) => ({ command, passed: false, exit_code: 1, output: "boom", duration_ms: 1 })
+const pass = (command: string) => ({
+ command,
+ passed: true,
+ kind: "command_exit" as const,
+ exit_code: 0,
+ output: "ok",
+ duration_ms: 1,
+})
+const fail = (command: string) => ({
+ command,
+ passed: false,
+ kind: "command_exit" as const,
+ exit_code: 1,
+ output: "boom",
+ duration_ms: 1,
+})
const declarations = (over: Partial = {}): ModelDeclarations => ({
completion_claim: "complete",
diff --git a/packages/core/test/deepagent/round-state-dedupe.test.ts b/packages/core/test/deepagent/round-state-dedupe.test.ts
index 85146274..c818cd6b 100644
--- a/packages/core/test/deepagent/round-state-dedupe.test.ts
+++ b/packages/core/test/deepagent/round-state-dedupe.test.ts
@@ -11,6 +11,7 @@ describe("addCandidate stale-reharvest dedupe", () => {
const vr = (command: string, exit_code: number, output = "x"): ValidationResult => ({
command,
passed: exit_code === 0,
+ kind: "command_exit",
exit_code,
output,
duration_ms: 0,
diff --git a/packages/core/test/deepagent/session-state-activity.test.ts b/packages/core/test/deepagent/session-state-activity.test.ts
new file mode 100644
index 00000000..8afbbd24
--- /dev/null
+++ b/packages/core/test/deepagent/session-state-activity.test.ts
@@ -0,0 +1,81 @@
+import { beforeEach, describe, expect, test } from "bun:test"
+import { mkdtempSync } from "node:fs"
+import { tmpdir } from "node:os"
+import path from "node:path"
+import { DeepAgentPlanStore, DeepAgentSessionState } from "../../src/deepagent"
+
+const plan = (sessionId: string, planId: string, goal: string) => ({
+ plan_id: planId,
+ session_id: sessionId,
+ goal,
+ assumptions: [],
+ steps: [{ step_id: "step_1", title: goal, status: "active" as const }],
+ active_step_id: "step_1",
+ created_at: new Date().toISOString(),
+})
+
+describe("DeepAgent activity lifecycle", () => {
+ beforeEach(() => {
+ DeepAgentSessionState.configure(mkdtempSync(path.join(tmpdir(), "deepagent-activity-")))
+ })
+
+ test("a new admission reopens completed activity state without deleting plan history", () => {
+ const sessionId = "activity-reopen"
+ const state = DeepAgentSessionState.getOrCreate(sessionId, "high")
+ expect(DeepAgentSessionState.observeUserAdmission(sessionId, "msg_a")).toBe("initial")
+ DeepAgentSessionState.setPlan(sessionId, plan(sessionId, "plan_old", "old task"))
+ DeepAgentSessionState.advanceToNextRound(sessionId, "continue")
+ DeepAgentSessionState.recordValidation(
+ sessionId,
+ [
+ {
+ command: "bun test",
+ passed: false,
+ kind: "command_exit",
+ exit_code: 1,
+ output: "failed",
+ duration_ms: 1,
+ },
+ ],
+ "failed",
+ )
+ DeepAgentSessionState.suppressValidation(sessionId, "bun test", 1, "old activity")
+ DeepAgentSessionState.complete(sessionId)
+ const oldRunId = state.runId
+
+ expect(DeepAgentSessionState.observeUserAdmission(sessionId, "msg_b")).toBe("reopened")
+ const reopened = DeepAgentSessionState.get(sessionId)!
+ expect(reopened.roundState).toMatchObject({ round: 1, phase: "planning", stage: "first_fast_design" })
+ expect(reopened.lastValidationResults).toEqual([])
+ expect(reopened.lastValidationOutput).toBeNull()
+ expect(reopened.suppressedValidations).toEqual([])
+ expect(reopened.completedAt).toBeNull()
+ expect(reopened.runId).not.toBe(oldRunId)
+ expect(reopened.planLatch).toMatchObject({ plan_id: null, latch: "fresh", stale_reason: null })
+ expect(DeepAgentSessionState.getPlan(sessionId)).toBeNull()
+ expect(DeepAgentPlanStore.getPlanDoc(sessionId)?.plan_id).toBe("plan_old")
+
+ DeepAgentSessionState.setPlan(sessionId, plan(sessionId, "plan_new", "new task"))
+ expect(DeepAgentSessionState.getPlan(sessionId)?.goal).toBe("new task")
+ })
+
+ test("the same admission never reopens a just-completed activity", () => {
+ const sessionId = "activity-same-admission"
+ DeepAgentSessionState.getOrCreate(sessionId, "high")
+ expect(DeepAgentSessionState.observeUserAdmission(sessionId, "msg_a")).toBe("initial")
+ DeepAgentSessionState.complete(sessionId)
+
+ expect(DeepAgentSessionState.observeUserAdmission(sessionId, "msg_a")).toBe("same")
+ expect(DeepAgentSessionState.get(sessionId)?.roundState.phase).toBe("completed")
+ })
+
+ test("a new admission during a live activity remains a steer signal", () => {
+ const sessionId = "activity-steer"
+ DeepAgentSessionState.getOrCreate(sessionId, "high")
+ DeepAgentSessionState.observeUserAdmission(sessionId, "msg_a")
+ DeepAgentSessionState.advanceToNextRound(sessionId, "continue")
+
+ expect(DeepAgentSessionState.observeUserAdmission(sessionId, "msg_b")).toBe("new")
+ expect(DeepAgentSessionState.get(sessionId)?.roundState.round).toBe(2)
+ })
+})
diff --git a/packages/core/test/deepagent/session-state-plan-latch.test.ts b/packages/core/test/deepagent/session-state-plan-latch.test.ts
index 0cf40403..05bead02 100644
--- a/packages/core/test/deepagent/session-state-plan-latch.test.ts
+++ b/packages/core/test/deepagent/session-state-plan-latch.test.ts
@@ -22,7 +22,7 @@ describe("session-state plan latch", () => {
SessionState.getOrCreate("latch-s2", "high")
SessionState.recordValidation(
"latch-s2",
- [{ command: "tsc", passed: false, exit_code: 1, output: "err", duration_ms: 1 }],
+ [{ command: "tsc", passed: false, kind: "command_exit", exit_code: 1, output: "err", duration_ms: 1 }],
"err",
)
const latch = SessionState.planLatch("latch-s2")
@@ -34,7 +34,7 @@ describe("session-state plan latch", () => {
SessionState.getOrCreate("latch-s3", "high")
SessionState.recordValidation(
"latch-s3",
- [{ command: "tsc", passed: true, exit_code: 0, output: "ok", duration_ms: 1 }],
+ [{ command: "tsc", passed: true, kind: "command_exit", exit_code: 0, output: "ok", duration_ms: 1 }],
"ok",
)
expect(SessionState.planLatch("latch-s3")?.latch).toBe("fresh")
@@ -67,6 +67,30 @@ describe("session-state plan latch", () => {
expect(SessionState.getPlan("latch-s5")?.goal).toBe("ship it")
})
+ test("a semantic no-op does not clear a stale latch or bump replan_count", () => {
+ const plan = {
+ plan_id: "plan_noop",
+ session_id: "latch-noop",
+ goal: "ship it",
+ assumptions: [],
+ steps: [{ step_id: "step_1", title: "build", status: "active" as const }],
+ active_step_id: "step_1",
+ created_at: new Date().toISOString(),
+ }
+ SessionState.getOrCreate("latch-noop", "high")
+ SessionState.setPlan("latch-noop", plan)
+ SessionState.markPlanStale("latch-noop", "no_progress")
+
+ SessionState.setPlan("latch-noop", plan)
+
+ expect(SessionState.planLatch("latch-noop")).toMatchObject({
+ plan_id: "plan_noop",
+ latch: "stale",
+ stale_reason: "no_progress",
+ replan_count: 0,
+ })
+ })
+
test("latch survives a save/load round-trip via getOrCreate normalize", () => {
SessionState.getOrCreate("latch-s6", "high")
SessionState.markPlanStale("latch-s6", "no_progress")
@@ -90,9 +114,9 @@ describe("session-state progress-nudge counter", () => {
SessionState.configure(mkdtempSync(path.join(tmpdir(), "plan-nudge-")))
})
- const plan = (steps: Array<{ id: string; status: string }>, activeId: string | null = null) => ({
+ const plan = (sessionID: string, steps: Array<{ id: string; status: string }>, activeId: string | null = null) => ({
plan_id: "plan_x",
- session_id: "sess",
+ session_id: sessionID,
goal: "g",
assumptions: [] as string[],
steps: steps.map((s) => ({ step_id: s.id, title: s.id, status: s.status as never })),
@@ -108,7 +132,7 @@ describe("session-state progress-nudge counter", () => {
test("recordMutation counts once a plan exists", () => {
SessionState.getOrCreate("nudge-s2", "high")
- SessionState.setPlan("nudge-s2", plan([{ id: "s1", status: "active" }], "s1"))
+ SessionState.setPlan("nudge-s2", plan("nudge-s2", [{ id: "s1", status: "active" }], "s1"))
SessionState.recordMutation("nudge-s2")
SessionState.recordMutation("nudge-s2")
expect(SessionState.mutationsSinceReport("nudge-s2")).toBe(2)
@@ -116,29 +140,33 @@ describe("session-state progress-nudge counter", () => {
test("a real status change resets the counter; a no-op re-write does not", () => {
SessionState.getOrCreate("nudge-s3", "high")
- SessionState.setPlan("nudge-s3", plan([{ id: "s1", status: "active" }], "s1"))
+ SessionState.setPlan("nudge-s3", plan("nudge-s3", [{ id: "s1", status: "active" }], "s1"))
SessionState.recordMutation("nudge-s3")
SessionState.recordMutation("nudge-s3")
// no-op re-write (same statuses) -> counter keeps running (no report theater)
- SessionState.setPlan("nudge-s3", plan([{ id: "s1", status: "active" }], "s1"))
+ SessionState.setPlan("nudge-s3", plan("nudge-s3", [{ id: "s1", status: "active" }], "s1"))
expect(SessionState.mutationsSinceReport("nudge-s3")).toBe(2)
// real status change -> reset
- SessionState.setPlan("nudge-s3", plan([{ id: "s1", status: "done" }]))
+ SessionState.setPlan("nudge-s3", plan("nudge-s3", [{ id: "s1", status: "done" }]))
expect(SessionState.mutationsSinceReport("nudge-s3")).toBe(0)
})
test("setPlan preserves evidence across a re-write (evidence is runtime-owned)", () => {
SessionState.getOrCreate("nudge-s4", "high")
SessionState.setPlan("nudge-s4", {
- ...plan([{ id: "s1", status: "done" }]),
+ ...plan("nudge-s4", [{ id: "s1", status: "done" }]),
steps: [{ step_id: "s1", title: "build", status: "done", evidence: ["run:1"] }],
})
// model re-writes the plan (adds a step) without repeating evidence
SessionState.setPlan("nudge-s4", {
- ...plan([
- { id: "s1", status: "done" },
- { id: "s2", status: "active" },
- ]),
+ ...plan(
+ "nudge-s4",
+ [
+ { id: "s1", status: "done" },
+ { id: "s2", status: "active" },
+ ],
+ "s2",
+ ),
steps: [
{ step_id: "s1", title: "build", status: "done" },
{ step_id: "s2", title: "test", status: "active" },
@@ -155,8 +183,8 @@ describe("session-state progress-nudge counter", () => {
SessionState.recordValidation(
"nudge-s5",
[
- { command: "tsc", passed: true, exit_code: 0, output: "ok", duration_ms: 1 },
- { command: "test", passed: false, exit_code: 1, output: "err", duration_ms: 1 },
+ { command: "tsc", passed: true, kind: "command_exit", exit_code: 0, output: "ok", duration_ms: 1 },
+ { command: "test", passed: false, kind: "command_exit", exit_code: 1, output: "err", duration_ms: 1 },
],
"mixed",
)
@@ -168,36 +196,84 @@ describe("session-state progress-nudge counter", () => {
test("validationPassedSinceReport: set by an all-pass run, reset on a real status change", () => {
SessionState.getOrCreate("nudge-s6", "high")
- SessionState.setPlan("nudge-s6", plan([{ id: "s1", status: "active" }], "s1"))
+ SessionState.setPlan("nudge-s6", plan("nudge-s6", [{ id: "s1", status: "active" }], "s1"))
expect(SessionState.validationPassedSinceReport("nudge-s6")).toBe(false)
// a failing run does NOT set the semantic flag (it marks the latch stale instead)
SessionState.recordValidation(
"nudge-s6",
- [{ command: "tsc", passed: false, exit_code: 1, output: "err", duration_ms: 1 }],
+ [{ command: "tsc", passed: false, kind: "command_exit", exit_code: 1, output: "err", duration_ms: 1 }],
"err",
)
expect(SessionState.validationPassedSinceReport("nudge-s6")).toBe(false)
// an all-passing run sets it
SessionState.recordValidation(
"nudge-s6",
- [{ command: "tsc", passed: true, exit_code: 0, output: "ok", duration_ms: 1 }],
+ [{ command: "tsc", passed: true, kind: "command_exit", exit_code: 0, output: "ok", duration_ms: 1 }],
"ok",
)
expect(SessionState.validationPassedSinceReport("nudge-s6")).toBe(true)
// a real status change clears it (fresh reporting window)
- SessionState.setPlan("nudge-s6", plan([{ id: "s1", status: "done" }]))
+ SessionState.setPlan("nudge-s6", plan("nudge-s6", [{ id: "s1", status: "done" }]))
expect(SessionState.validationPassedSinceReport("nudge-s6")).toBe(false)
})
test("validationPassedSinceReport: a no-op plan re-write does NOT clear the flag", () => {
SessionState.getOrCreate("nudge-s7", "high")
- SessionState.setPlan("nudge-s7", plan([{ id: "s1", status: "active" }], "s1"))
+ SessionState.setPlan("nudge-s7", plan("nudge-s7", [{ id: "s1", status: "active" }], "s1"))
SessionState.recordValidation(
"nudge-s7",
- [{ command: "tsc", passed: true, exit_code: 0, output: "ok", duration_ms: 1 }],
+ [{ command: "tsc", passed: true, kind: "command_exit", exit_code: 0, output: "ok", duration_ms: 1 }],
"ok",
)
- SessionState.setPlan("nudge-s7", plan([{ id: "s1", status: "active" }], "s1")) // no status change
+ SessionState.setPlan("nudge-s7", plan("nudge-s7", [{ id: "s1", status: "active" }], "s1")) // no status change
expect(SessionState.validationPassedSinceReport("nudge-s7")).toBe(true)
})
})
+
+// BUG-010 Fix-A §7.3: document that SessionState.setPlan() is a legacy compatibility seam.
+// It writes directly to PlanStore without going through the strict admission/CAS gate.
+// All NEW plan writers (model_tool, human_goal_edit, runtime_goal_bridge) must use
+// compareAndCommitPlan instead. This test pins the legacy behavior so changes to it are visible.
+describe("session-state setPlan compat seam (BUG-010 Fix-A)", () => {
+ beforeEach(() => {
+ SessionState.configure(mkdtempSync(path.join(tmpdir(), "plan-bypass-")))
+ })
+
+ test("setPlan writes a plan without operation/version preconditions (compat seam, not an admission gate)", () => {
+ const sessionID = "bypass-s1"
+ SessionState.getOrCreate(sessionID, "high")
+ // setPlan does NOT require operation/expected_plan_id/expected_version —
+ // this is intentionally a backwards-compat path used only by legacy callers.
+ const legacyPlan = {
+ plan_id: "plan_legacy",
+ session_id: sessionID,
+ goal: "legacy plan",
+ assumptions: [],
+ steps: [{ step_id: "s1", title: "step one", status: "active" as const }],
+ active_step_id: "s1",
+ created_at: new Date().toISOString(),
+ }
+ SessionState.setPlan(sessionID, legacyPlan)
+ // The call succeeds (no error thrown) — that's the definition of "bypass":
+ // it skips the semantic oracle and CAS precondition.
+ expect(SessionState.getPlan(sessionID)).not.toBeNull()
+ })
+
+ // This test is a regression guard: if setPlan is removed or made to throw, update the
+ // legacy callers listed in §7.3 (migration/tests) before removing it from the codebase.
+ test("setPlan is still callable — existing legacy/test callers depend on it", () => {
+ const sessionID = "bypass-s2"
+ SessionState.getOrCreate(sessionID, "high")
+ expect(() =>
+ SessionState.setPlan(sessionID, {
+ plan_id: "plan_compat",
+ session_id: sessionID,
+ goal: "compat",
+ assumptions: [],
+ steps: [{ step_id: "s1", title: "step", status: "pending" as const }],
+ active_step_id: null,
+ created_at: new Date().toISOString(),
+ }),
+ ).not.toThrow()
+ })
+})
diff --git a/packages/core/test/location-layer.test.ts b/packages/core/test/location-layer.test.ts
index faf6186f..99ed456f 100644
--- a/packages/core/test/location-layer.test.ts
+++ b/packages/core/test/location-layer.test.ts
@@ -1,6 +1,6 @@
import fs from "fs/promises"
import path from "path"
-import { describe, expect } from "bun:test"
+import { afterAll, beforeAll, describe, expect } from "bun:test"
import { Effect, Layer, Schema } from "effect"
import { Tool } from "@deepagent-code/core/public"
import { Catalog } from "@deepagent-code/core/catalog"
@@ -22,6 +22,7 @@ import { ProjectReference } from "../src/project-reference"
import { LocationSearch } from "../src/location-search"
import { ToolRegistry } from "../src/tool/registry"
import { ApplicationTools } from "../src/tool/application-tools"
+import { Flag } from "../src/flag/flag"
const applicationTools = ApplicationTools.layer
const it = testEffect(
@@ -44,6 +45,19 @@ const it = testEffect(
)
describe("LocationServiceMap", () => {
+ // ModelsDevPlugin.refresh() calls modelsDev.get() which acquires a cross-process
+ // Flock on models.json. On a developer machine where the main app holds that lock,
+ // PluginBoot.wait() never returns. Disable the models fetch for this test file so
+ // boot completes instantly without any network or file-locking. Same pattern as
+ // packages/core/test/models.test.ts.
+ const ORIGINAL_DISABLE_FETCH = Flag.DEEPAGENT_CODE_DISABLE_MODELS_FETCH
+ beforeAll(() => {
+ Flag.DEEPAGENT_CODE_DISABLE_MODELS_FETCH = true
+ })
+ afterAll(() => {
+ Flag.DEEPAGENT_CODE_DISABLE_MODELS_FETCH = ORIGINAL_DISABLE_FETCH
+ })
+
it.live("isolates location state while sharing location policy with catalog", () =>
Effect.acquireRelease(
Effect.promise(() => Promise.all([tmpdir(), tmpdir()])),
diff --git a/packages/core/test/session-execution.test.ts b/packages/core/test/session-execution.test.ts
new file mode 100644
index 00000000..108deaef
--- /dev/null
+++ b/packages/core/test/session-execution.test.ts
@@ -0,0 +1,238 @@
+import { describe, expect, test } from "bun:test"
+import { asc, eq } from "drizzle-orm"
+import { Context, Deferred, Effect, Exit, Layer, LayerMap, Scope } from "effect"
+import { Database } from "@deepagent-code/core/database/database"
+import { EventV2 } from "@deepagent-code/core/event"
+import { EventTable } from "@deepagent-code/core/event/sql"
+import { LocationServiceMap } from "@deepagent-code/core/location-layer"
+import { Project } from "@deepagent-code/core/project"
+import { ProjectTable } from "@deepagent-code/core/project/sql"
+import { AbsolutePath } from "@deepagent-code/core/schema"
+import { SessionEvent } from "@deepagent-code/core/session/event"
+import { SessionExecution } from "@deepagent-code/core/session/execution"
+import { SessionExecutionLocal } from "@deepagent-code/core/session/execution/local"
+import { SessionRestart } from "@deepagent-code/core/session/execution/restart"
+import { SessionRunner } from "@deepagent-code/core/session/runner"
+import { SessionSchema } from "@deepagent-code/core/session/schema"
+import { SessionTable } from "@deepagent-code/core/session/sql"
+import { SessionStore } from "@deepagent-code/core/session/store"
+import { testEffect } from "./lib/effect"
+
+const database = Database.layerFromPath(":memory:")
+const events = EventV2.layer.pipe(Layer.provide(database))
+const store = SessionStore.layer.pipe(Layer.provide(database))
+const it = testEffect(Layer.mergeAll(database, events, store))
+
+describe("SessionExecution lifecycle", () => {
+ test("classifies success, failure, and interruption terminals", () => {
+ expect(SessionExecution.terminal(Exit.succeed(undefined))).toEqual({ type: "succeeded" })
+ expect(SessionExecution.terminal(Exit.die(new Error("failed")))).toEqual({
+ type: "failed",
+ error: { type: "unknown", message: "failed" },
+ })
+ const interrupted = Effect.runSyncExit(Effect.interrupt)
+ expect(SessionExecution.terminal(interrupted)).toEqual({ type: "interrupted", reason: "shutdown" })
+ expect(SessionExecution.terminal(interrupted, "user")).toEqual({ type: "interrupted", reason: "user" })
+ })
+
+ it.effect("atomically consumes each suspension at most once", () =>
+ Effect.gen(function* () {
+ const database = yield* Database.Service
+ const store = yield* SessionStore.Service
+ const first = SessionSchema.ID.make("ses_recover_first")
+ const second = SessionSchema.ID.make("ses_recover_second")
+ yield* seedSessions(database, [first, second], { time_suspended: Date.now() })
+
+ expect(yield* store.consumeSuspended(first)).toBe(true)
+ expect(yield* store.consumeSuspended(first)).toBe(false)
+ expect(yield* store.consumeSuspended(second)).toBe(true)
+ expect(yield* suspensions(database)).toEqual({ [first]: false, [second]: false })
+ }),
+ )
+
+ it.effect("clears suspension and records one lifecycle when execution succeeds", () =>
+ Effect.gen(function* () {
+ const database = yield* Database.Service
+ const sessionID = SessionSchema.ID.make("ses_suspend_completed")
+ yield* seedSessions(database, [sessionID], { time_suspended: Date.now() })
+
+ const scope = yield* Scope.make()
+ yield* Effect.addFinalizer(() => Scope.close(scope, Exit.void))
+ const context = yield* buildExecution(scope, () => Effect.void)
+ const execution = Context.get(context, SessionExecution.Service)
+
+ yield* execution.resume(sessionID)
+ yield* execution.awaitIdle(sessionID)
+
+ expect(yield* suspensions(database)).toEqual({ [sessionID]: false })
+ expect(yield* eventTypes(database, sessionID)).toEqual([
+ EventV2.versionedType(SessionEvent.Execution.Started.type, 1),
+ EventV2.versionedType(SessionEvent.Execution.Succeeded.type, 1),
+ ])
+ }),
+ )
+
+ it.effect("preserves suspension when orderly teardown interrupts execution", () =>
+ Effect.gen(function* () {
+ const database = yield* Database.Service
+ const sessionID = SessionSchema.ID.make("ses_suspend_interrupted")
+ yield* seedSessions(database, [sessionID])
+
+ const started = yield* Deferred.make()
+ const scope = yield* Scope.make()
+ yield* Effect.addFinalizer(() => Scope.close(scope, Exit.void))
+ const context = yield* buildExecution(scope, () =>
+ Deferred.succeed(started, undefined).pipe(Effect.andThen(Effect.never)),
+ )
+ const execution = Context.get(context, SessionExecution.Service)
+ const restart = Context.get(context, SessionRestart.Service)
+ yield* execution.resume(sessionID).pipe(Effect.forkIn(scope))
+ yield* Deferred.await(started)
+
+ yield* restart.suspendActiveSessions
+ expect(yield* suspensions(database)).toEqual({ [sessionID]: true })
+ yield* Scope.close(scope, Exit.void)
+
+ expect(yield* suspensions(database)).toEqual({ [sessionID]: true })
+ expect(yield* eventTypes(database, sessionID)).toEqual([
+ EventV2.versionedType(SessionEvent.Execution.Started.type, 1),
+ EventV2.versionedType(SessionEvent.Execution.Interrupted.type, 1),
+ ])
+ }),
+ )
+
+ it.effect("resumes each suspended Session at most once", () =>
+ Effect.gen(function* () {
+ const database = yield* Database.Service
+ const first = SessionSchema.ID.make("ses_resume_first")
+ const second = SessionSchema.ID.make("ses_resume_second")
+ yield* seedSessions(database, [first, second], { time_suspended: Date.now() })
+
+ const resumed: SessionSchema.ID[] = []
+ const scope = yield* Scope.make()
+ yield* Effect.addFinalizer(() => Scope.close(scope, Exit.void))
+ const context = yield* buildExecution(scope, ({ sessionID }) =>
+ Effect.sync(() => {
+ resumed.push(sessionID)
+ }),
+ )
+ const execution = Context.get(context, SessionExecution.Service)
+ const restart = Context.get(context, SessionRestart.Service)
+
+ yield* restart.resumeSuspendedSessions
+ yield* Effect.forEach([first, second], execution.awaitIdle, { discard: true })
+ yield* restart.resumeSuspendedSessions
+
+ expect(resumed.toSorted()).toEqual([first, second])
+ expect(yield* suspensions(database)).toEqual({ [first]: false, [second]: false })
+ }),
+ )
+
+ it.effect("starts suspended Sessions concurrently", () =>
+ Effect.gen(function* () {
+ const database = yield* Database.Service
+ const sessionIDs = Array.from({ length: 5 }, (_, index) =>
+ SessionSchema.ID.make(`ses_resume_concurrent_${index}`),
+ )
+ yield* seedSessions(database, sessionIDs, { time_suspended: Date.now() })
+
+ const allStarted = yield* Deferred.make()
+ const resumed: SessionSchema.ID[] = []
+ const scope = yield* Scope.make()
+ yield* Effect.addFinalizer(() => Scope.close(scope, Exit.void))
+ const context = yield* buildExecution(scope, ({ sessionID }) =>
+ Effect.sync(() => {
+ resumed.push(sessionID)
+ if (resumed.length === sessionIDs.length) Deferred.doneUnsafe(allStarted, Effect.void)
+ }).pipe(Effect.andThen(Effect.never)),
+ )
+ const execution = Context.get(context, SessionExecution.Service)
+ const restart = Context.get(context, SessionRestart.Service)
+
+ yield* restart.resumeSuspendedSessions.pipe(Effect.forkIn(scope))
+ yield* Deferred.await(allStarted)
+
+ expect(resumed.toSorted()).toEqual(sessionIDs.toSorted())
+ expect(Array.from(yield* execution.active).toSorted()).toEqual(sessionIDs.toSorted())
+ }),
+ )
+})
+
+function seedSessions(
+ database: Database.Interface,
+ sessionIDs: ReadonlyArray,
+ values: { time_suspended?: number } = {},
+) {
+ return Effect.gen(function* () {
+ yield* database.db
+ .insert(ProjectTable)
+ .values({ id: Project.ID.global, worktree: AbsolutePath.make("/project"), sandboxes: [] })
+ .onConflictDoNothing()
+ .run()
+ .pipe(Effect.orDie)
+ yield* database.db
+ .insert(SessionTable)
+ .values(
+ sessionIDs.map((id) => ({
+ id,
+ project_id: Project.ID.global,
+ slug: id,
+ directory: "/project",
+ title: id,
+ version: "test",
+ ...values,
+ })),
+ )
+ .run()
+ .pipe(Effect.orDie)
+ })
+}
+
+function suspensions(database: Database.Interface) {
+ return database.db
+ .select({ id: SessionTable.id, suspended: SessionTable.time_suspended })
+ .from(SessionTable)
+ .all()
+ .pipe(
+ Effect.orDie,
+ Effect.map((rows) => Object.fromEntries(rows.map((row) => [row.id, row.suspended !== null]))),
+ )
+}
+
+function eventTypes(database: Database.Interface, sessionID: SessionSchema.ID) {
+ return database.db
+ .select({ type: EventTable.type })
+ .from(EventTable)
+ .where(eq(EventTable.aggregate_id, sessionID))
+ .orderBy(asc(EventTable.seq))
+ .all()
+ .pipe(
+ Effect.orDie,
+ Effect.map((rows) => rows.map((row) => row.type)),
+ )
+}
+
+function buildExecution(scope: Scope.Closeable, run: SessionRunner.Interface["run"]) {
+ return Effect.gen(function* () {
+ const events = yield* EventV2.Service
+ const store = yield* SessionStore.Service
+ const runner = Layer.succeed(SessionRunner.Service, SessionRunner.Service.of({ run }))
+ const locations = Layer.effect(
+ LocationServiceMap,
+ LayerMap.make(() => runner).pipe(
+ // The lifecycle harness only needs the runner from the full Location graph.
+ // oxlint-disable-next-line typescript-eslint/no-unsafe-type-assertion
+ Effect.map((service) => service as unknown as LocationServiceMap["Service"]),
+ ),
+ )
+ return yield* Layer.buildWithScope(
+ SessionRestart.layer.pipe(
+ Layer.provideMerge(SessionExecutionLocal.layer),
+ Layer.provide(Layer.succeed(EventV2.Service, events)),
+ Layer.provide(Layer.succeed(SessionStore.Service, store)),
+ Layer.provide(locations),
+ ),
+ scope,
+ )
+ })
+}
diff --git a/packages/core/test/session-prompt.test.ts b/packages/core/test/session-prompt.test.ts
index 4b8a0fc4..0c81b8de 100644
--- a/packages/core/test/session-prompt.test.ts
+++ b/packages/core/test/session-prompt.test.ts
@@ -30,6 +30,8 @@ const wakeSeqs: Array = []
const execution = Layer.succeed(
SessionExecution.Service,
SessionExecution.Service.of({
+ active: Effect.succeed(new Set()),
+ awaitIdle: () => Effect.void,
resume: (sessionID) =>
Effect.sync(() => {
executionCalls.push(sessionID)
diff --git a/packages/core/test/session-run-coordinator.test.ts b/packages/core/test/session-run-coordinator.test.ts
index 1dc95c7f..83803049 100644
--- a/packages/core/test/session-run-coordinator.test.ts
+++ b/packages/core/test/session-run-coordinator.test.ts
@@ -41,6 +41,95 @@ describe("SessionRunCoordinator", () => {
),
)
+ it.effect("snapshots only active ownership chains", () =>
+ Effect.scoped(
+ Effect.gen(function* () {
+ const firstStarted = yield* Deferred.make()
+ const secondStarted = yield* Deferred.make()
+ const firstGate = yield* Deferred.make()
+ const secondGate = yield* Deferred.make()
+ const coordinator = yield* SessionRunCoordinator.make({
+ drain: (key: string) =>
+ Deferred.succeed(key === "first" ? firstStarted : secondStarted, undefined).pipe(
+ Effect.andThen(Deferred.await(key === "first" ? firstGate : secondGate)),
+ ),
+ })
+
+ expect(Array.from(yield* coordinator.active)).toEqual([])
+ const first = yield* coordinator.run("first").pipe(Effect.forkChild)
+ yield* Deferred.await(firstStarted)
+ expect(Array.from(yield* coordinator.active)).toEqual(["first"])
+
+ const second = yield* coordinator.run("second").pipe(Effect.forkChild)
+ yield* Deferred.await(secondStarted)
+ expect(Array.from(yield* coordinator.active)).toEqual(["first", "second"])
+
+ yield* Deferred.succeed(firstGate, undefined)
+ yield* Fiber.join(first)
+ expect(Array.from(yield* coordinator.active)).toEqual(["second"])
+ yield* Deferred.succeed(secondGate, undefined)
+ yield* Fiber.join(second)
+ expect(Array.from(yield* coordinator.active)).toEqual([])
+ }),
+ ),
+ )
+
+ it.effect("reports one lifecycle for a coalesced ownership chain", () =>
+ Effect.scoped(
+ Effect.gen(function* () {
+ const firstStarted = yield* Deferred.make()
+ const firstGate = yield* Deferred.make()
+ const secondStarted = yield* Deferred.make()
+ const lifecycle: string[] = []
+ let runs = 0
+ const coordinator = yield* SessionRunCoordinator.make({
+ started: (key: string) => Effect.sync(() => lifecycle.push(`started:${key}`)),
+ drain: () =>
+ Effect.sync(() => ++runs).pipe(
+ Effect.flatMap((run) =>
+ run === 1
+ ? Deferred.succeed(firstStarted, undefined).pipe(Effect.andThen(Deferred.await(firstGate)))
+ : Deferred.succeed(secondStarted, undefined),
+ ),
+ ),
+ settled: (key, exit) =>
+ Effect.sync(() => lifecycle.push(`settled:${key}:${Exit.isSuccess(exit) ? "success" : "failure"}`)),
+ })
+
+ const run = yield* coordinator.run("session").pipe(Effect.forkChild)
+ yield* Deferred.await(firstStarted)
+ yield* coordinator.wake("session")
+ yield* Deferred.succeed(firstGate, undefined)
+ yield* Deferred.await(secondStarted)
+ yield* Fiber.join(run)
+
+ expect(runs).toBe(2)
+ expect(lifecycle).toEqual(["started:session", "settled:session:success"])
+ }),
+ ),
+ )
+
+ it.effect("passes the interruption reason to lifecycle settlement", () =>
+ Effect.scoped(
+ Effect.gen(function* () {
+ const started = yield* Deferred.make()
+ const reasons: Array = []
+ const coordinator = yield* SessionRunCoordinator.make({
+ drain: () => Deferred.succeed(started, undefined).pipe(Effect.andThen(Effect.never)),
+ settled: (_key, _exit, reason) => Effect.sync(() => reasons.push(reason)),
+ })
+
+ const run = yield* coordinator.run("session").pipe(Effect.exit, Effect.forkChild)
+ yield* Deferred.await(started)
+ yield* coordinator.interrupt("session", undefined, "shutdown")
+ yield* Fiber.join(run)
+
+ expect(reasons).toEqual(["shutdown"])
+ expect(Array.from(yield* coordinator.active)).toEqual([])
+ }),
+ ),
+ )
+
it.effect("does nothing when interrupted while idle", () =>
Effect.scoped(
Effect.gen(function* () {
diff --git a/packages/core/test/session-runner-recorded.test.ts b/packages/core/test/session-runner-recorded.test.ts
index aa8a0ac6..85e8272c 100644
--- a/packages/core/test/session-runner-recorded.test.ts
+++ b/packages/core/test/session-runner-recorded.test.ts
@@ -91,6 +91,8 @@ const execution = Layer.effect(
SessionRunCoordinator.Service.pipe(
Effect.map((coordinator) =>
SessionExecution.Service.of({
+ active: coordinator.active,
+ awaitIdle: coordinator.awaitIdle,
resume: coordinator.run,
wake: coordinator.wake,
interrupt: coordinator.interrupt,
diff --git a/packages/core/test/session-runner.test.ts b/packages/core/test/session-runner.test.ts
index c71b4d8c..95699891 100644
--- a/packages/core/test/session-runner.test.ts
+++ b/packages/core/test/session-runner.test.ts
@@ -252,6 +252,8 @@ const execution = Layer.effect(
SessionRunCoordinator.Service.pipe(
Effect.map((coordinator) =>
SessionExecution.Service.of({
+ active: coordinator.active,
+ awaitIdle: coordinator.awaitIdle,
resume: coordinator.run,
wake: coordinator.wake,
interrupt: coordinator.interrupt,
diff --git a/packages/core/test/subagent-control-plane-migration.test.ts b/packages/core/test/subagent-control-plane-migration.test.ts
new file mode 100644
index 00000000..b17d7f48
--- /dev/null
+++ b/packages/core/test/subagent-control-plane-migration.test.ts
@@ -0,0 +1,175 @@
+/**
+ * DET-MIG-01: L1 migration — schema upgrade correctness
+ *
+ * Tests: §13.1 backfill rules, CHECK constraint enforcement, duplicate-apply idempotence.
+ */
+import { describe, expect } from "bun:test"
+import { Effect, Layer } from "effect"
+import { eq } from "drizzle-orm"
+import { Database } from "@deepagent-code/core/database/database"
+import { TaskRunTable } from "@deepagent-code/core/session/sql"
+import { Project } from "@deepagent-code/core/project"
+import { ProjectTable } from "@deepagent-code/core/project/sql"
+import { AbsolutePath } from "@deepagent-code/core/schema"
+import { SessionSchema } from "@deepagent-code/core/session/schema"
+import { SessionTable } from "@deepagent-code/core/session/sql"
+import { testEffect } from "./lib/effect"
+
+const database = Database.layerFromPath(":memory:")
+const it = testEffect(Layer.mergeAll(database))
+
+const projectID = Project.ID.make("git-remote:example.com/cp-migration-test")
+const parentSessionID = SessionSchema.ID.descending()
+
+const setup = Effect.gen(function* () {
+ const { db } = yield* Database.Service
+ yield* db
+ .insert(ProjectTable)
+ .values({ id: projectID, worktree: AbsolutePath.make("/project"), sandboxes: [] })
+ .onConflictDoNothing()
+ .run()
+ .pipe(Effect.orDie)
+ yield* db
+ .insert(SessionTable)
+ .values({
+ id: parentSessionID,
+ project_id: projectID,
+ slug: "cp-migration-test-parent",
+ directory: "/project",
+ title: "parent",
+ version: "test",
+ })
+ .onConflictDoNothing()
+ .run()
+ .pipe(Effect.orDie)
+})
+
+describe("DET-MIG-01: L1 migration", () => {
+ it.effect("applies cleanly to a fresh database — task_run table exists", () =>
+ Effect.gen(function* () {
+ const { db } = yield* Database.Service
+ // If the layer initialised without error all migrations applied.
+ // Verify key columns exist by selecting from the table (errors if schema mismatch).
+ const rows = yield* db.select({ run_id: TaskRunTable.run_id }).from(TaskRunTable).all().pipe(Effect.orDie)
+ expect(Array.isArray(rows)).toBe(true)
+ }),
+ )
+
+ it.effect("L1 state values admitted/queued/running/failed/closed are accepted", () =>
+ Effect.gen(function* () {
+ yield* setup
+ const { db } = yield* Database.Service
+ const now = Date.now()
+
+ const childSessionIDs: string[] = []
+ for (const state of ["admitted", "queued", "running", "failed", "closed", "recovery_required"] as const) {
+ const childID = SessionSchema.ID.descending()
+ childSessionIDs.push(childID as string)
+ // First insert a child session row (FK dependency)
+ yield* db
+ .insert(SessionTable)
+ .values({
+ id: childID,
+ project_id: projectID,
+ slug: `cp-mig-child-${state}`,
+ directory: "/project",
+ title: `child-${state}`,
+ version: "test",
+ })
+ .onConflictDoNothing()
+ .run()
+ .pipe(Effect.orDie)
+ // Insert task_run with the new L1 state values
+ yield* db
+ .insert(TaskRunTable)
+ .values({
+ run_id: `run_mig_${state}_${now}`,
+ request_hash: "hash",
+ parent_session_id: parentSessionID,
+ parent_message_id: `msg_mig_${state}` as any,
+ tool_call_id: `tc_${state}`,
+ child_session_id: childID,
+ generation: 1,
+ delivery_mode: "foreground",
+ phase: "admission",
+ state,
+ attempts: 0,
+ time_created: now,
+ time_updated: now,
+ })
+ .run()
+ .pipe(Effect.orDie)
+ }
+
+ const inserted = yield* db
+ .select({ state: TaskRunTable.state })
+ .from(TaskRunTable)
+ .where(eq(TaskRunTable.parent_session_id, parentSessionID as any))
+ .all()
+ .pipe(Effect.orDie)
+
+ const states = new Set(inserted.map((r) => r.state))
+ expect(states.has("admitted")).toBe(true)
+ expect(states.has("queued")).toBe(true)
+ expect(states.has("running")).toBe(true)
+ expect(states.has("failed")).toBe(true)
+ expect(states.has("closed")).toBe(true)
+ expect(states.has("recovery_required")).toBe(true)
+ }),
+ )
+
+ it.effect("execution_spec column exists and round-trips JSON", () =>
+ Effect.gen(function* () {
+ yield* setup
+ const { db } = yield* Database.Service
+ const now = Date.now()
+ const childID = SessionSchema.ID.descending()
+
+ yield* db
+ .insert(SessionTable)
+ .values({
+ id: childID,
+ project_id: projectID,
+ slug: "cp-mig-spec-child",
+ directory: "/project",
+ title: "spec-child",
+ version: "test",
+ })
+ .onConflictDoNothing()
+ .run()
+ .pipe(Effect.orDie)
+
+ const spec = { prompt: { text: "hello world" } }
+ yield* db
+ .insert(TaskRunTable)
+ .values({
+ run_id: `run_mig_spec_${now}`,
+ request_hash: "hash_spec",
+ parent_session_id: parentSessionID,
+ parent_message_id: `msg_spec_${now}` as any,
+ tool_call_id: "tc_spec",
+ child_session_id: childID,
+ generation: 1,
+ delivery_mode: "foreground",
+ phase: "admission",
+ state: "admitted",
+ attempts: 0,
+ execution_spec: spec as any,
+ time_created: now,
+ time_updated: now,
+ })
+ .run()
+ .pipe(Effect.orDie)
+
+ const row = yield* db
+ .select({ execution_spec: TaskRunTable.execution_spec })
+ .from(TaskRunTable)
+ .where(eq(TaskRunTable.run_id, `run_mig_spec_${now}`))
+ .get()
+ .pipe(Effect.orDie)
+
+ expect(row).toBeDefined()
+ expect((row!.execution_spec as any)?.prompt?.text).toBe("hello world")
+ }),
+ )
+})
diff --git a/packages/deepagent-code/README.md b/packages/deepagent-code/README.md
index d1cc670c..4c74998f 100644
--- a/packages/deepagent-code/README.md
+++ b/packages/deepagent-code/README.md
@@ -2,8 +2,6 @@
DeepAgent Code is a document-centered AI coding agent. This package contains the CLI/server runtime used by the terminal and desktop applications.
-The current product release is Desktop 1.4.4 with DeepAgent Core V4.0.5.
-
DeepAgent Code keeps the opencode runtime foundation and adds the DeepAgent control plane:
- typed-document memory for run state, durable knowledge, worklogs, decisions, diagnosis, and context snapshots.
diff --git a/packages/deepagent-code/package.json b/packages/deepagent-code/package.json
index e6fe2d6d..a7aaa824 100644
--- a/packages/deepagent-code/package.json
+++ b/packages/deepagent-code/package.json
@@ -25,6 +25,7 @@
"test:llm-live:subagent-foreground": "bun run script/live-llm/subagents.ts",
"test:llm-live:shell-exit-contract": "bun run script/live-llm/shell-exit-contract.ts",
"test:llm-live:stale-validation": "bun run script/live-llm/stale-validation.ts",
+ "test:llm-live:continuation-repetition": "bun run script/live-llm/continuation-repetition.ts",
"test:llm-live:degeneration": "bun run script/live-llm/degeneration.ts",
"test:llm-ext:finalizer-isolation": "bun run script/live-llm/finalizer-isolation.ts",
"test:llm-live:steer-boundary": "bun run script/live-llm/steer-boundary.ts",
@@ -44,6 +45,8 @@
"test:llm-ext:compaction-retention": "bun run script/live-llm/compaction-retention.ts",
"test:llm-ext:expert-panel": "bun run script/live-llm/expert-panel.ts",
"test:llm-ext:intelligence-draft": "bun run script/live-llm/cli-intelligence.ts",
+ "test:llm-ext:prompt-intent-fencing": "bun run script/live-llm/prompt-intent-fencing.ts",
+ "test:llm-live:subagent-control-plane": "bun run script/live-llm/subagent-control-plane.ts",
"test:llm-eval:autonomous": "bun run script/live-llm/autonomous-eval.ts",
"test:httpapi": "bun run script/httpapi-exercise.ts --mode coverage --fail-on-missing --fail-on-skip && bun run script/httpapi-exercise.ts --mode auth --fail-on-missing --fail-on-skip && bun run script/httpapi-exercise.ts --mode effect --fail-on-missing --fail-on-skip",
"bench:test": "bun run script/bench-test-suite.ts",
diff --git a/packages/deepagent-code/script/build.ts b/packages/deepagent-code/script/build.ts
index 1d8298f0..25dbb935 100755
--- a/packages/deepagent-code/script/build.ts
+++ b/packages/deepagent-code/script/build.ts
@@ -9,6 +9,18 @@ import { createSolidTransformPlugin } from "@opentui/solid/bun-plugin"
const __filename = fileURLToPath(import.meta.url)
const __dirname = path.dirname(__filename)
const dir = path.resolve(__dirname, "..")
+const repository = path.resolve(dir, "../..")
+
+const gitOutput = (args: string[]) => {
+ const result = Bun.spawnSync(["git", ...args], { cwd: repository, stdout: "pipe", stderr: "ignore" })
+ if (result.exitCode !== 0) return
+ return result.stdout.toString().trim()
+}
+
+const sourceCommit = process.env.DEEPAGENT_CODE_COMMIT ?? gitOutput(["rev-parse", "HEAD"])
+const sourceDirty = sourceCommit
+ ? (gitOutput(["status", "--porcelain", "--untracked-files=all"])?.length ?? 0) > 0
+ : undefined
process.chdir(dir)
@@ -196,6 +208,7 @@ for (const item of targets) {
OTUI_TREE_SITTER_WORKER_PATH: bunfsRoot + workerRelativePath,
DEEPAGENT_CODE_WORKER_PATH: workerPath,
DEEPAGENT_CODE_CHANNEL: `'${Script.channel}'`,
+ ...(sourceCommit ? { DEEPAGENT_CODE_COMMIT: JSON.stringify(sourceCommit) } : {}),
DEEPAGENT_CODE_LIBC: item.os === "linux" ? `'${item.abi ?? "glibc"}'` : "",
...(item.os === "linux" ? { "process.env.OPENTUI_LIBC": JSON.stringify(item.abi ?? "glibc") } : {}),
},
@@ -215,6 +228,9 @@ for (const item of targets) {
}
await $`rm -rf ./dist/${name}/bin/tui`
+ const binarySha256 = new Bun.CryptoHasher("sha256")
+ .update(await Bun.file(`dist/${name}/bin/deepagent-code`).bytes())
+ .digest("hex")
await Bun.file(`dist/${name}/package.json`).write(
JSON.stringify(
{
@@ -224,6 +240,11 @@ for (const item of targets) {
os: [item.os],
cpu: [item.arch],
...(item.abi ? { libc: [item.abi] } : {}),
+ deepagentCodeBuild: {
+ ...(sourceCommit ? { sourceCommit } : {}),
+ ...(sourceDirty !== undefined ? { sourceDirty } : {}),
+ binarySha256,
+ },
},
null,
2,
diff --git a/packages/deepagent-code/script/generate.ts b/packages/deepagent-code/script/generate.ts
index fe89e8a4..6df05026 100644
--- a/packages/deepagent-code/script/generate.ts
+++ b/packages/deepagent-code/script/generate.ts
@@ -1,14 +1,8 @@
-import path from "path"
-import { fileURLToPath } from "url"
+import path from "node:path"
+import { loadModelsData } from "./models-data"
-const __filename = fileURLToPath(import.meta.url)
-const __dirname = path.dirname(__filename)
-const dir = path.resolve(__dirname, "..")
+process.chdir(path.resolve(import.meta.dir, ".."))
-process.chdir(dir)
-
-const modelsUrl = process.env.DEEPAGENT_CODE_MODELS_URL || "https://models.dev"
-export const modelsData = process.env.MODELS_DEV_API_JSON
- ? await Bun.file(process.env.MODELS_DEV_API_JSON).text()
- : await fetch(`${modelsUrl}/api.json`).then((x) => x.text())
-console.log("Loaded models.dev snapshot")
+const models = await loadModelsData()
+export const modelsData = models.data
+console.log(`Loaded models.dev snapshot from ${models.source}`)
diff --git a/packages/deepagent-code/script/live-llm/compaction-retention.ts b/packages/deepagent-code/script/live-llm/compaction-retention.ts
index a23d8101..77c29e19 100644
--- a/packages/deepagent-code/script/live-llm/compaction-retention.ts
+++ b/packages/deepagent-code/script/live-llm/compaction-retention.ts
@@ -30,6 +30,7 @@ const artifact = await runLegacyLiveCases({
},
],
sharedSession: true,
+ inspectDurability: true,
beforeCase: async ({ caseName, directory }) => {
if (caseName === "fill-context-window") {
await Promise.all(
@@ -87,6 +88,30 @@ if (fill.compactionCount !== 1 || recovery.compactionCount !== 1 || recovery.new
if (fill.summaryTexts.length !== 1 || fill.summaryTexts.some((text) => markers.some((marker) => text.includes(marker)))) {
throw new Error("C1 marker leaked into or was missing from the automatic compaction summary boundary")
}
+if (!fill.durability) throw new Error("C1 did not capture compaction durability evidence")
+const committedRuns = fill.durability.compactionRuns.filter((run) => run.state === "committed")
+if (committedRuns.length !== 1) {
+ throw new Error(`Expected exactly one committed compaction run, received ${committedRuns.length}`)
+}
+const committedRun = committedRuns[0]
+const summaryAttempts = fill.durability.summaryAttempts.filter(
+ (attempt) => attempt.run_id === committedRun.run_id,
+)
+if (summaryAttempts.length < 1 || summaryAttempts.length > 2) {
+ throw new Error(`Expected one or two durable summary attempts, received ${summaryAttempts.length}`)
+}
+if (summaryAttempts.filter((attempt) => attempt.state === "settled").length !== 1) {
+ throw new Error(`Expected one settled summary attempt: ${JSON.stringify(summaryAttempts)}`)
+}
+const activeEpochs = fill.durability.promptEpochs.filter((epoch) => epoch.state === "active")
+if (
+ activeEpochs.length !== 1 ||
+ activeEpochs[0].epoch <= 0 ||
+ activeEpochs[0].epoch !== committedRun.target_prompt_epoch ||
+ activeEpochs[0].checkpoint_assistant_id !== committedRun.committed_summary_message_id
+) {
+ throw new Error(`C1 PromptEpoch did not bind the committed summary: ${JSON.stringify(activeEpochs)}`)
+}
const worldState = fill.users.map((user) => user.syntheticText).find((text) => text.includes(""))
if (!worldState || markers.some((marker) => !worldState.includes(marker))) {
@@ -104,6 +129,23 @@ if (completedTools.length !== 1 || completedTools[0]?.name !== "write") {
if (recovery.newTools.some((tool) => tool.status !== "completed")) {
throw new Error("C1 produced a failed or non-terminal tool call")
}
+if (!recovery.durability) throw new Error("C1 did not capture request receipt evidence")
+const completedWrite = completedTools[0]
+const writeReceipt = recovery.durability.requestReceipts.find(
+ (receipt) =>
+ receipt.assistant_message_id === completedWrite.messageID && receipt.call_ids.includes(completedWrite.id),
+)
+if (
+ !writeReceipt ||
+ writeReceipt.request_state !== "dispatched" ||
+ writeReceipt.adapter_lowering_outcome !== "ok" ||
+ !writeReceipt.registry_tool_ids.includes("write") ||
+ !writeReceipt.permission_filtered_tool_ids.includes("write") ||
+ !writeReceipt.final_offered_tool_ids.includes("write") ||
+ !writeReceipt.tool_definition_hash
+) {
+ throw new Error(`C1 write request receipt was incomplete: ${JSON.stringify(writeReceipt)}`)
+}
const writeInput = record(completedTools[0]?.input, "write input")
if (typeof writeInput.filePath !== "string" || path.basename(writeInput.filePath) !== "output.txt") {
throw new Error("C1 write did not target output.txt")
@@ -126,6 +168,10 @@ const result = {
evidence: {
markerHashes: markers.map((marker) => Bun.hash(marker).toString(16)),
automaticCompactions: automatic.length,
+ committedCompactionRuns: committedRuns.length,
+ summaryAttempts: summaryAttempts.length,
+ activePromptEpoch: activeEpochs[0].epoch,
+ writeReceiptID: writeReceipt.receipt_id,
summaryExcludedMarkers: true,
worldStateSuppliedMarkers: true,
changedPaths: evaluation.changedPaths,
diff --git a/packages/deepagent-code/script/live-llm/continuation-repetition.ts b/packages/deepagent-code/script/live-llm/continuation-repetition.ts
new file mode 100644
index 00000000..ff58e275
--- /dev/null
+++ b/packages/deepagent-code/script/live-llm/continuation-repetition.ts
@@ -0,0 +1,180 @@
+import path from "node:path"
+import { writeLiveArtifact } from "../../../llm/script/live-llm/config"
+import { finishLiveScript } from "./lifecycle"
+import { runLegacyLiveCases } from "./runtime"
+
+// Regression for session-scoped DeepAgent state and full round-context re-injection. The first case
+// deliberately completes validation. The second admission must start with no stale round/results/plan
+// context, then execute one expected failing validation followed by four serial reads. Every request
+// after a tool result must carry the compact continuation tail, never the full task/activation block.
+const passMarker = `continuation-pass-${crypto.randomUUID()}`
+const failMarker = `continuation-fail-${crypto.randomUUID()}`
+const objectiveMarker = `continuation-objective-${crypto.randomUUID()}`
+const facts = Array.from({ length: 4 }, (_, index) => ({
+ path: `facts/${index + 1}.txt`,
+ marker: `fact-${index + 1}-${crypto.randomUUID()}`,
+}))
+const verifier = [
+ "#!/bin/sh",
+ 'if [ "$1" = "pass" ]; then',
+ ` printf '%s\\n' '${passMarker}'`,
+ " exit 0",
+ "fi",
+ `printf '%s\\n' '${failMarker}' >&2`,
+ "exit 17",
+ "",
+].join("\n")
+const prompts = {
+ complete: `Run ./verify pass exactly once and reply with its exact marker.`,
+ continuation: [
+ `Objective label: ${objectiveMarker}.`,
+ "Run ./verify fail exactly once. This failure is an expected fixture result, not work to repair.",
+ `Then read ${facts.map((fact) => fact.path).join(", ")} in that exact order.`,
+ "Issue exactly one tool call per assistant turn and wait for each result before calling the next tool.",
+ "Do not re-explain the objective, phase, or expected failure between tools.",
+ "In the final answer, print the objective label exactly once followed by the four fact markers in order.",
+ ].join("\n"),
+}
+const redactions = [
+ { value: passMarker, replacement: "" },
+ { value: failMarker, replacement: "" },
+ { value: objectiveMarker, replacement: "" },
+ ...facts.map((fact, index) => ({ value: fact.marker, replacement: `` })),
+]
+const artifact = await runLegacyLiveCases({
+ suite: "continuation-repetition-legacy",
+ permission: {
+ "*": "deny",
+ bash: { "*": "deny", "./verify pass": "allow", "./verify fail": "allow" },
+ read: { "*": "deny", ...Object.fromEntries(facts.map((fact) => [fact.path, "allow" as const])) },
+ },
+ cases: [
+ { name: "complete", prompt: prompts.complete },
+ { name: "continuation", prompt: prompts.continuation },
+ ],
+ files: {
+ ...Object.fromEntries(facts.map((fact) => [fact.path, `${fact.marker}\n`])),
+ "AGENTS.md":
+ "- `./verify pass` - passing fixture validation\n- `./verify fail` - expected failing fixture validation\n",
+ },
+ toolSandbox: { verifierScript: verifier },
+ sharedSession: true,
+ observeAssembledRequestFingerprints: true,
+ environment: { DEEPAGENT_MODE: "high" },
+ primaryPrompt:
+ "This is a serial tool-continuation contract test. Use only the tools named by the current user, " +
+ "exactly one per assistant turn. An explicitly expected verifier failure is evidence to record, not a repair task.",
+ modelMaxTokens: 1024,
+ maxProviderTurns: 10,
+})
+await writeLiveArtifact(
+ { artifactDirectory: path.resolve(import.meta.dir, "../../.artifacts/live-llm") },
+ `${artifact.suite}-observed`,
+ artifact,
+ { redactions },
+)
+
+const completed = artifact.cases.find((testCase) => testCase.name === "complete")
+const continuation = artifact.cases.find((testCase) => testCase.name === "continuation")
+if (!completed || !continuation) throw new Error("Missing continuation-repetition observation")
+const completedTools = completed.newTools.filter((tool) => tool.status === "completed")
+if (
+ completedTools.length !== 1 ||
+ completedTools[0]?.name !== "bash" ||
+ !completedTools[0].output?.includes(passMarker)
+) {
+ throw new Error("Setup activity did not complete through the passing verifier")
+}
+
+const tools = continuation.newTools.filter((tool) => tool.status === "completed")
+const expectedTools = ["bash", ...facts.map(() => "read")]
+if (
+ tools.length !== expectedTools.length ||
+ tools.some((tool, index) => tool.name !== expectedTools[index]) ||
+ continuation.newTools.some((tool) => tool.status !== "completed")
+) {
+ throw new Error(
+ `Continuation tool sequence mismatch: ${continuation.newTools.map((tool) => `${tool.name}:${tool.status}`).join(", ")}`,
+ )
+}
+if (!tools[0]?.output?.includes(failMarker)) {
+ throw new Error("Continuation activity did not observe the expected failing validation")
+}
+for (const [index, fact] of facts.entries()) {
+ if (!tools[index + 1]?.output?.includes(fact.marker) || !continuation.finalText.includes(fact.marker)) {
+ throw new Error(`Continuation activity did not preserve fact ${index + 1}`)
+ }
+}
+const finalMarkers = [objectiveMarker, ...facts.map((fact) => fact.marker)].map((marker) =>
+ continuation.finalText.indexOf(marker),
+)
+if (finalMarkers.some((index) => index < 0) || finalMarkers.some((index, offset) => offset > 0 && index <= finalMarkers[offset - 1]!)) {
+ throw new Error(`Continuation final markers are missing or out of order: ${finalMarkers.join(", ")}`)
+}
+
+const contextKinds = continuation.assembledRequestFingerprints.map((fingerprint) =>
+ typeof fingerprint.volatileContextKind === "string" ? fingerprint.volatileContextKind : "missing",
+)
+if (contextKinds[0] !== "none") {
+ throw new Error(`New activity inherited stale runtime context: ${contextKinds.join(" -> ")}`)
+}
+if (contextKinds.length < expectedTools.length + 1 || contextKinds.slice(1).some((kind) => kind !== "continuation")) {
+ throw new Error(`Tool turns did not use compact continuation context: ${contextKinds.join(" -> ")}`)
+}
+const objectiveOccurrences = (continuation.allText.match(new RegExp(objectiveMarker, "g")) ?? []).length
+if (objectiveOccurrences !== 1) {
+ throw new Error(`The objective label appeared ${objectiveOccurrences} times instead of exactly once`)
+}
+
+const narrations = continuation.assistantTexts.map(normalize).filter((text) => text.length >= 24)
+const repeatedPairs = narrations.flatMap((left, index) =>
+ narrations.slice(index + 1).flatMap((right) => (dice(left, right) >= 0.68 ? [[left, right] as const] : [])),
+)
+if (repeatedPairs.length > 1) {
+ throw new Error(`Assistant repeated semantically equivalent narration across ${repeatedPairs.length} turn pairs`)
+}
+if (artifact.workspace.status.trim()) {
+ throw new Error(`Read-only continuation suite mutated the workspace: ${artifact.workspace.status}`)
+}
+
+const result = {
+ ...artifact,
+ evidence: {
+ contextKinds,
+ assistantTurns: continuation.assistantTurns,
+ completedTools: tools.map((tool) => tool.name),
+ repeatedNarrationPairs: repeatedPairs.length,
+ maxNarrationSimilarity: Math.max(
+ 0,
+ ...narrations.flatMap((left, index) => narrations.slice(index + 1).map((right) => dice(left, right))),
+ ),
+ objectiveMarkerHash: Bun.hash(objectiveMarker).toString(16),
+ factMarkerHashes: facts.map((fact) => Bun.hash(fact.marker).toString(16)),
+ },
+}
+await writeLiveArtifact(
+ { artifactDirectory: path.resolve(import.meta.dir, "../../.artifacts/live-llm") },
+ result.suite,
+ result,
+ { redactions },
+)
+console.log(
+ `${result.suite}: passed (${result.fingerprint.providerID}/${result.fingerprint.modelID}, ` +
+ `${continuation.assistantTurns} assistant turns, ${contextKinds.length} requests)`,
+)
+
+function normalize(value: string) {
+ return value.toLowerCase().replace(/[\p{P}\p{S}\s\d_]+/gu, "")
+}
+
+function dice(left: string, right: string) {
+ const grams = (value: string) =>
+ new Set(Array.from({ length: Math.max(0, value.length - 1) }, (_, index) => value.slice(index, index + 2)))
+ const a = grams(left)
+ const b = grams(right)
+ if (a.size === 0 || b.size === 0) return 0
+ const overlap = [...a].filter((gram) => b.has(gram)).length
+ return (2 * overlap) / (a.size + b.size)
+}
+
+finishLiveScript()
diff --git a/packages/deepagent-code/script/live-llm/dispatcher.ts b/packages/deepagent-code/script/live-llm/dispatcher.ts
index e70db0de..62e7e974 100644
--- a/packages/deepagent-code/script/live-llm/dispatcher.ts
+++ b/packages/deepagent-code/script/live-llm/dispatcher.ts
@@ -112,6 +112,25 @@ const checkCommands: Record = {
"test/agent/subagent-plan-permission.test.ts",
),
],
+ "prompt-intent": [
+ command(
+ "packages/deepagent-code",
+ "bun",
+ "test",
+ "test/session/prompt-intent.test.ts",
+ "test/session/revert-compact.test.ts",
+ "test/session/steer.test.ts",
+ ),
+ command(
+ "packages/app",
+ "bun",
+ "test",
+ "--preload",
+ "./happydom.ts",
+ "src/components/prompt-input/submit.test.ts",
+ "src/pages/session/followup-submission.test.ts",
+ ),
+ ],
mcp: [
command("packages/deepagent-code", "bun", "typecheck"),
command("packages/deepagent-code", "bun", "test", "test/mcp", "test/deepagent/mcp-provenance.test.ts"),
@@ -171,6 +190,10 @@ const modelCommands = new Map([
"live:legacy-session:stale-validation",
command("packages/deepagent-code", "bun", "run", "test:llm-live:stale-validation"),
],
+ [
+ "live:legacy-session:continuation-repetition",
+ command("packages/deepagent-code", "bun", "run", "test:llm-live:continuation-repetition"),
+ ],
["live:legacy-session:degeneration", command("packages/deepagent-code", "bun", "run", "test:llm-live:degeneration")],
[
"ext:legacy-session:subagent-finalizer-isolation",
@@ -243,6 +266,14 @@ const modelCommands = new Map([
"ext:legacy-session:intelligence-draft-confirmation",
command("packages/deepagent-code", "bun", "run", "test:llm-ext:intelligence-draft"),
],
+ [
+ "ext:legacy-session:prompt-intent-fencing",
+ command("packages/deepagent-code", "bun", "run", "test:llm-ext:prompt-intent-fencing"),
+ ],
+ [
+ "live:legacy-session:subagent-control-plane",
+ command("packages/deepagent-code", "bun", "run", "test:llm-live:subagent-control-plane"),
+ ],
])
// Registration is not qualification. A LIVE suite enters this set only after its committed harness,
diff --git a/packages/deepagent-code/script/live-llm/multi-agent-pr-collaboration.ts b/packages/deepagent-code/script/live-llm/multi-agent-pr-collaboration.ts
index c6a6e0a2..8cb12604 100644
--- a/packages/deepagent-code/script/live-llm/multi-agent-pr-collaboration.ts
+++ b/packages/deepagent-code/script/live-llm/multi-agent-pr-collaboration.ts
@@ -24,9 +24,9 @@ const prompt = [
"Both calls must use subagent_type worker, background false, omit isolation entirely, and use the exact raw output_schema below.",
`Use this exact output_schema for both calls: ${JSON.stringify(outputSchema)}.`,
"LEFT description: implement left PR fixture.",
- "LEFT prompt: Read only fixtures/left.txt exactly once. Then use write exactly once to write those exact bytes to output/left.txt. Do not use bash or edit. Return result set to the exact bytes written.",
+ "LEFT prompt: Read only fixtures/left.txt exactly once. Then use write exactly once to write those exact bytes to output/left.txt. Do not use bash or edit. Return result set to the exact bytes written, including the trailing newline, without Markdown or backticks.",
"RIGHT description: implement right PR fixture.",
- "RIGHT prompt: Read only fixtures/right.txt exactly once. Then use write exactly once to write those exact bytes to output/right.txt. Do not use bash or edit. Return result set to the exact bytes written.",
+ "RIGHT prompt: Read only fixtures/right.txt exactly once. Then use write exactly once to write those exact bytes to output/right.txt. Do not use bash or edit. Return result set to the exact bytes written, including the trailing newline, without Markdown or backticks.",
"After both task results return, your NEXT assistant response must contain exactly one pr_finalize tool call and no text. Omit pr_ids so the complete batch is finalized.",
"Do not call read, write, edit, bash, task_status, or task_read in the parent.",
"After pr_finalize returns, report that the two PRs and stage review completed.",
@@ -82,7 +82,7 @@ const artifact = await runLegacyLiveCases({
await writeLiveArtifact(
{ artifactDirectory: path.resolve(import.meta.dir, "../../.artifacts/live-llm") },
`${artifact.suite}-observed`,
- artifact,
+ { ...artifact, status: "observed" },
)
if ([leftMarker, rightMarker, verifierSuccess].some((marker) => prompt.includes(marker))) {
diff --git a/packages/deepagent-code/script/live-llm/prompt-intent-fencing.ts b/packages/deepagent-code/script/live-llm/prompt-intent-fencing.ts
new file mode 100644
index 00000000..101efccc
--- /dev/null
+++ b/packages/deepagent-code/script/live-llm/prompt-intent-fencing.ts
@@ -0,0 +1,183 @@
+import path from "node:path"
+import { writeLiveArtifact } from "../../../llm/script/live-llm/config"
+import { finishLiveScript } from "./lifecycle"
+import { runLegacyLiveCases } from "./runtime"
+
+const directMarker = `direct-intent-${crypto.randomUUID()}`
+const rewriteMarker = `rewrite-intent-${crypto.randomUUID()}`
+const directIntentID = `intent-direct-${crypto.randomUUID()}`
+const rewriteIntentID = `intent-rewrite-${crypto.randomUUID()}`
+// Keep classifier input natural; response markers belong to the agent prompt, not the user request.
+const directPrompt = "你好"
+const conflictingPrompt = "你好！"
+const rewritePrompt = "谢谢"
+
+const artifact = await runLegacyLiveCases({
+ suite: "prompt-intent-fencing-legacy",
+ permission: { "*": "deny" },
+ cases: [
+ {
+ name: "intelligence-direct",
+ prompt: directPrompt,
+ intelligence: { outputLanguage: "english", expectedRoute: "general" },
+ admission: {
+ intentID: directIntentID,
+ source: "intelligence",
+ variant: "original",
+ exactRetry: true,
+ conflictingRetry: { prompt: conflictingPrompt, variant: "rewritten" },
+ },
+ },
+ {
+ name: "revert-rewrite",
+ prompt: rewritePrompt,
+ admission: {
+ intentID: rewriteIntentID,
+ source: "rewrite",
+ variant: "rewritten",
+ exactRetry: true,
+ },
+ revertBefore: { targetCase: "intelligence-direct", retryTargetIntent: true },
+ },
+ ],
+ sharedSession: true,
+ primaryPrompt:
+ `When the user says "${directPrompt}", reply with exactly ${directMarker}. ` +
+ `When the user says "${rewritePrompt}", reply with exactly ${rewriteMarker}. ` +
+ "Do not call tools or add any other text.",
+ modelMaxTokens: 128,
+ maxProviderTurns: 2,
+})
+
+const direct = requireCase("intelligence-direct")
+const rewrite = requireCase("revert-rewrite")
+
+if (direct.sessionID !== rewrite.sessionID) throw new Error("Prompt intent fencing did not use one durable Session")
+if (direct.intelligenceDraft?.route !== "general" || direct.intelligenceDraft.preview !== directPrompt) {
+ throw new Error("Intelligence preparation did not select the direct route with the original prompt")
+}
+if (
+ direct.admission?.state !== "admitted" ||
+ direct.admission.source !== "intelligence" ||
+ direct.admission.variant !== "original" ||
+ direct.admission.delivery !== "turn"
+) {
+ throw new Error(`Direct intent receipt was invalid: ${JSON.stringify(direct.admission)}`)
+}
+const directRetry = direct.admission.retry
+if (
+ directRetry?.exact?.accepted !== true ||
+ !directRetry.activeBeforeRetry ||
+ directRetry.exact.userCountBefore !== directRetry.exact.userCountAfter
+) {
+ throw new Error("Exact direct-intent retry was not an active-turn admission no-op")
+}
+if (
+ directRetry.conflict?.accepted !== false ||
+ directRetry.conflict.error !== "SessionPromptIntent.Conflict"
+) {
+ throw new Error(`Late rewritten draft was not rejected: ${JSON.stringify(directRetry.conflict)}`)
+}
+if (direct.users.length !== 1 || direct.users[0]?.text !== directPrompt) {
+ throw new Error(`Direct route materialized ${direct.users.length} user messages instead of the original input once`)
+}
+if (direct.users[0].metadata?.deepagent?.prompt_pipeline?.mode !== "direct_override") {
+ throw new Error("Direct-route user message did not preserve direct_override metadata")
+}
+if (
+ direct.assistantTurns !== 1 ||
+ direct.newTools.length !== 0 ||
+ direct.providerErrors.length !== 0 ||
+ !direct.finalText.includes(directMarker)
+) {
+ throw new Error("Direct-route execution did not complete exactly once through the real provider")
+}
+
+if (
+ rewrite.revert?.targetCase !== "intelligence-direct" ||
+ rewrite.revert.epochAfter !== rewrite.revert.epochBefore + 1 ||
+ rewrite.revert.retry?.accepted !== false ||
+ rewrite.revert.retry.error !== "SessionMutationEpoch.Stale"
+) {
+ throw new Error(`Revert did not fence the old prompt intent: ${JSON.stringify(rewrite.revert)}`)
+}
+if (
+ rewrite.admission?.state !== "admitted" ||
+ rewrite.admission.source !== "rewrite" ||
+ rewrite.admission.variant !== "rewritten" ||
+ rewrite.admission.mutationEpoch !== rewrite.revert.epochAfter
+) {
+ throw new Error(`Rewrite intent receipt was invalid: ${JSON.stringify(rewrite.admission)}`)
+}
+const rewriteRetry = rewrite.admission.retry
+if (
+ rewriteRetry?.exact?.accepted !== true ||
+ !rewriteRetry.activeBeforeRetry ||
+ rewriteRetry.exact.userCountBefore !== rewriteRetry.exact.userCountAfter
+) {
+ throw new Error("Exact rewrite retry was not an active-turn admission no-op")
+}
+if (rewrite.users.length !== 1 || rewrite.users[0]?.text !== rewritePrompt) {
+ throw new Error(`Revert/rewrite materialized ${rewrite.users.length} current user messages instead of one`)
+}
+if (
+ rewrite.assistantTurns !== 1 ||
+ rewrite.newTools.length !== 0 ||
+ rewrite.providerErrors.length !== 0 ||
+ !rewrite.finalText.includes(rewriteMarker)
+) {
+ throw new Error("Rewritten prompt did not execute exactly once through the real provider")
+}
+if (rewrite.allText.includes(directMarker) || artifact.workspace.status.trim()) {
+ throw new Error("Revert left stale output in the active transcript or mutated the workspace")
+}
+if (
+ artifact.cases.some(
+ (testCase) => testCase.permissionRequests.length !== 0 || testCase.questionRequests.length !== 0,
+ )
+) {
+ throw new Error("Prompt intent fencing requested undeclared permission or question input")
+}
+
+const result = {
+ ...artifact,
+ mode: "ext" as const,
+ evidence: {
+ directIntentHash: Bun.hash(directIntentID).toString(16),
+ rewriteIntentHash: Bun.hash(rewriteIntentID).toString(16),
+ directMarkerHash: Bun.hash(directMarker).toString(16),
+ rewriteMarkerHash: Bun.hash(rewriteMarker).toString(16),
+ exactRetries: 2,
+ conflictingDraftRejected: true,
+ staleEpochRetryRejected: true,
+ mutationEpochAdvance: rewrite.revert.epochAfter - rewrite.revert.epochBefore,
+ userMessagesAfterRewrite: rewrite.users.length,
+ providerTurns: direct.assistantTurns + rewrite.assistantTurns,
+ },
+}
+
+await writeLiveArtifact(
+ { artifactDirectory: path.resolve(import.meta.dir, "../../.artifacts/live-llm") },
+ result.suite,
+ result,
+ {
+ redactions: [
+ { value: directMarker, replacement: `` },
+ { value: rewriteMarker, replacement: `` },
+ { value: directIntentID, replacement: `` },
+ { value: rewriteIntentID, replacement: `` },
+ ],
+ },
+)
+console.log(
+ `${result.suite}: passed (${result.fingerprint.providerID}/${result.fingerprint.modelID}, ` +
+ `${result.evidence.providerTurns} provider turns, epoch +${result.evidence.mutationEpochAdvance})`,
+)
+
+finishLiveScript()
+
+function requireCase(name: string) {
+ const testCase = artifact.cases.find((item) => item.name === name)
+ if (!testCase) throw new Error(`Missing prompt-intent case ${name}`)
+ return testCase
+}
diff --git a/packages/deepagent-code/script/live-llm/recovery.ts b/packages/deepagent-code/script/live-llm/recovery.ts
index e99c81c0..998d60fa 100644
--- a/packages/deepagent-code/script/live-llm/recovery.ts
+++ b/packages/deepagent-code/script/live-llm/recovery.ts
@@ -56,6 +56,11 @@ const artifact = await runLegacyLiveCases({
primaryPrompt:
"This suite verifies recovery from real tool errors. Follow every requested attempt in order, inspect actual error results, and never skip an intentionally failing first attempt.",
})
+await writeLiveArtifact(
+ { artifactDirectory: path.resolve(import.meta.dir, "../../.artifacts/live-llm") },
+ `${artifact.suite}-observed`,
+ { ...artifact, status: "observed" },
+)
const stale = requireCase("stale-edit")
if (
diff --git a/packages/deepagent-code/script/live-llm/routes.ts b/packages/deepagent-code/script/live-llm/routes.ts
index 2fc2990d..4c48e5e6 100644
--- a/packages/deepagent-code/script/live-llm/routes.ts
+++ b/packages/deepagent-code/script/live-llm/routes.ts
@@ -29,6 +29,7 @@ export const modelSuites = [
"desktop-subagents",
"shell-exit-contract",
"stale-validation",
+ "continuation-repetition",
"degeneration",
"subagent-finalizer-isolation",
"steer-boundary",
@@ -44,6 +45,8 @@ export const modelSuites = [
"expert-panel",
"goal-grader-cli-entry",
"intelligence-draft-confirmation",
+ "prompt-intent-fencing",
+ "subagent-control-plane",
] as const
export type ExecutionStack = (typeof executionStacks)[number]
@@ -63,6 +66,7 @@ export type DeterministicCheck =
| "llm-adapter"
| "mcp"
| "permission"
+ | "prompt-intent"
| "session-continuation"
| "session-v2"
| "tool-bash-sandbox"
@@ -97,6 +101,7 @@ const interruptedSubagent = modelRun("ext", "legacy-session", "subagent-interrup
const backgroundSubagent = modelRun("ext", "legacy-session", "subagent-background")
const shellExitContract = modelRun("live", "legacy-session", "shell-exit-contract")
const staleValidation = modelRun("live", "legacy-session", "stale-validation")
+const continuationRepetition = modelRun("live", "legacy-session", "continuation-repetition")
const degeneration = modelRun("live", "legacy-session", "degeneration")
const finalizerIsolation = modelRun("ext", "legacy-session", "subagent-finalizer-isolation")
const steerBoundary = modelRun("live", "legacy-session", "steer-boundary")
@@ -112,6 +117,8 @@ const compactionRetention = modelRun("ext", "legacy-session", "compaction-retent
const expertPanel = modelRun("ext", "legacy-session", "expert-panel")
const goalGraderCliEntry = modelRun("ext", "cli-subprocess", "goal-grader-cli-entry")
const intelligenceDraft = modelRun("ext", "legacy-session", "intelligence-draft-confirmation")
+const promptIntentFencing = modelRun("ext", "legacy-session", "prompt-intent-fencing")
+const subagentControlPlane = modelRun("live", "legacy-session", "subagent-control-plane")
const allHarnessRuns = [
adapterProvider,
cliHeadless,
@@ -127,6 +134,7 @@ const allHarnessRuns = [
v2BashRepair,
shellExitContract,
staleValidation,
+ continuationRepetition,
degeneration,
finalizerIsolation,
steerBoundary,
@@ -146,6 +154,8 @@ const allHarnessRuns = [
expertPanel,
goalGraderCliEntry,
intelligenceDraft,
+ promptIntentFencing,
+ subagentControlPlane,
]
export const routeManifest = [
@@ -253,6 +263,12 @@ export const routeManifest = [
checks: ["session-continuation", "tool-bash-sandbox"],
runs: [staleValidation],
},
+ {
+ id: "live-llm-continuation-repetition-harness",
+ paths: ["packages/deepagent-code/script/live-llm/continuation-repetition.ts"],
+ checks: ["session-continuation"],
+ runs: [continuationRepetition],
+ },
{
id: "live-llm-degeneration-harness",
paths: ["packages/deepagent-code/script/live-llm/degeneration.ts"],
@@ -538,17 +554,33 @@ export const routeManifest = [
legacyFileMutations,
legacyBashRepair,
legacySubagent,
+ continuationRepetition,
+ compactionRetention,
worktreeRouting,
multiAgentParallelWorktrees,
subagentIntensity,
expertPanel,
],
},
+ {
+ id: "deepagent-continuation-context",
+ paths: [
+ "packages/core/src/agent-gateway.ts",
+ "packages/core/src/deepagent/plan-controller.ts",
+ "packages/core/src/deepagent/prompt-policy.ts",
+ "packages/core/src/deepagent/session-state.ts",
+ "packages/deepagent-code/src/session/llm/request.ts",
+ "packages/deepagent-code/src/session/reminders.ts",
+ ],
+ checks: ["live-llm-routes", "session-continuation"],
+ runs: [continuationRepetition],
+ },
{
id: "legacy-session-prompt",
paths: [
"packages/deepagent-code/src/session/prompt.ts",
"packages/deepagent-code/src/session/processor.ts",
+ "packages/deepagent-code/src/session/tool-argument-receipt.sql.ts",
"packages/deepagent-code/src/session/tools.ts",
],
checks: ["llm-adapter", "session-continuation", "tool-files", "tool-bash-sandbox", "worktree-routing"],
@@ -571,6 +603,12 @@ export const routeManifest = [
paths: [
"packages/deepagent-code/src/session/steer.ts",
"packages/deepagent-code/src/session/compaction.ts",
+ "packages/deepagent-code/src/session/compaction-sql.ts",
+ "packages/deepagent-code/src/session/prompt-epoch.ts",
+ "packages/deepagent-code/src/session/prompt-epoch.sql.ts",
+ "packages/deepagent-code/src/session/tool-argument-receipt.sql.ts",
+ "packages/deepagent-code/src/session/tool-request-receipt.sql.ts",
+ "packages/deepagent-code/src/session/message-v2.ts",
"packages/deepagent-code/src/session/context-ledger.ts",
"packages/deepagent-code/src/session/system.ts",
"packages/core/src/system-context/**",
@@ -620,6 +658,7 @@ export const routeManifest = [
id: "legacy-tool-registry",
paths: [
"packages/deepagent-code/src/tool/registry.ts",
+ "packages/deepagent-code/src/context-federation/readiness.ts",
"packages/deepagent-code/src/tool/tool.ts",
"packages/deepagent-code/src/tool/schema.ts",
"packages/deepagent-code/src/tool/define.ts",
@@ -689,6 +728,37 @@ export const routeManifest = [
goalGraderCliEntry,
],
},
+ {
+ // L0–L10 durable control plane session layer
+ // Covers all new TaskDispatcher / TaskExecutor / TaskDelivery / provisioner / fork / input / capability files
+ id: "durable-control-plane-session",
+ paths: [
+ "packages/deepagent-code/src/session/task-dispatcher.ts",
+ "packages/deepagent-code/src/session/task-executor.ts",
+ "packages/deepagent-code/src/session/task-delivery.ts",
+ "packages/deepagent-code/src/session/task-fork.ts",
+ "packages/deepagent-code/src/session/task-input.ts",
+ "packages/deepagent-code/src/session/tool-capability.ts",
+ "packages/deepagent-code/src/session/branch-provisioner.ts",
+ "packages/deepagent-code/src/session/durable-executor-lock.ts",
+ "packages/deepagent-code/src/session/goal-receipt-store.ts",
+ "packages/deepagent-code/src/session/goal-workspace-adapter.ts",
+ "packages/deepagent-code/src/session/task-pr-submission.ts",
+ "packages/deepagent-code/src/session/task-worktree.ts",
+ "packages/deepagent-code/src/session/workspace-preflight.ts",
+ "packages/deepagent-code/src/tool/git_read.ts",
+ ],
+ checks: ["permission", "worktree-routing"],
+ runs: [
+ legacySubagent,
+ worktreeRouting,
+ multiAgentParallelWorktrees,
+ subagentResume,
+ interruptedSubagent,
+ backgroundSubagent,
+ subagentControlPlane,
+ ],
+ },
{
id: "legacy-subagent-worktree-runtime",
paths: ["packages/deepagent-code/src/project/instance-*.ts", "packages/deepagent-code/src/worktree/**"],
@@ -865,6 +935,11 @@ export const routeManifest = [
paths: [
"packages/deepagent-code/script/live-llm/compaction-retention.ts",
"packages/deepagent-code/src/session/compaction.ts",
+ "packages/deepagent-code/src/session/compaction-sql.ts",
+ "packages/deepagent-code/src/session/prompt-epoch.ts",
+ "packages/deepagent-code/src/session/prompt-epoch.sql.ts",
+ "packages/deepagent-code/src/session/tool-request-receipt.sql.ts",
+ "packages/deepagent-code/src/session/message-v2.ts",
"packages/deepagent-code/src/session/overflow.ts",
],
checks: ["session-continuation"],
@@ -897,6 +972,26 @@ export const routeManifest = [
checks: ["llm-adapter"],
runs: [intelligenceDraft],
},
+ {
+ id: "prompt-intent-fencing-suite",
+ paths: [
+ "packages/app/src/components/prompt-input/**",
+ "packages/app/src/pages/session.tsx",
+ "packages/app/src/pages/session/followup-submission.ts",
+ "packages/core/src/database/migration/20260806051000_session_prompt_intent.ts",
+ "packages/core/src/database/migration/20260806060000_session_mutation_epoch.ts",
+ "packages/core/src/session/sql.ts",
+ "packages/deepagent-code/script/live-llm/prompt-intent-fencing.ts",
+ "packages/deepagent-code/src/server/routes/instance/httpapi/handlers/session.ts",
+ "packages/deepagent-code/src/session/mutation-epoch.ts",
+ "packages/deepagent-code/src/session/prompt-intent.ts",
+ "packages/deepagent-code/src/session/prompt.ts",
+ "packages/deepagent-code/src/session/revert.ts",
+ "packages/deepagent-code/src/session/session.ts",
+ ],
+ checks: ["prompt-intent"],
+ runs: [promptIntentFencing],
+ },
] satisfies Route[]
export const owningPaths = [
@@ -904,6 +999,8 @@ export const owningPaths = [
"packages/core/src/session/**",
"packages/core/src/session.ts",
"packages/core/src/agent-gateway.ts",
+ "packages/core/src/deepagent/prompt-policy.ts",
+ "packages/core/src/deepagent/session-state.ts",
"packages/core/src/tool/**",
"packages/core/src/deepagent/goal-*.ts",
"packages/core/src/deepagent/plan-controller.ts",
diff --git a/packages/deepagent-code/script/live-llm/runtime.ts b/packages/deepagent-code/script/live-llm/runtime.ts
index a91cdca7..8a521353 100644
--- a/packages/deepagent-code/script/live-llm/runtime.ts
+++ b/packages/deepagent-code/script/live-llm/runtime.ts
@@ -97,6 +97,21 @@ export type LegacyLiveCase = {
agent?: string
intelligence?: {
outputLanguage?: "english" | "chinese"
+ expectedRoute?: "code" | "general"
+ }
+ admission?: {
+ intentID: string
+ source: "composer" | "intelligence" | "followup" | "rewrite"
+ variant: "original" | "rewritten"
+ exactRetry?: boolean
+ conflictingRetry?: {
+ prompt: string
+ variant: "original" | "rewritten"
+ }
+ }
+ revertBefore?: {
+ targetCase: string
+ retryTargetIntent?: boolean
}
}
@@ -149,6 +164,7 @@ export async function runLegacyLiveCases(input: {
// durable admission evidence before awaiting that prompt to completion.
steerDuringCases?: ReadonlyArray<{ duringCaseName: string; text: string }>
observeAssembledRequestFingerprints?: boolean
+ inspectDurability?: boolean
subagentIntensity?: "inherit" | "downgrade"
environment?: Readonly>
panel?: LegacyPanelCase
@@ -164,6 +180,9 @@ export async function runLegacyLiveCases(input: {
if (input.verifyChildWorktrees && !input.toolSandbox?.verifierScript) {
throw new Error("verifyChildWorktrees requires a toolSandbox verifierScript")
}
+ if (!input.sharedSession && input.cases.some((testCase) => testCase.revertBefore)) {
+ throw new Error("revertBefore requires sharedSession so the target and rewrite use one durable Session")
+ }
const preflight = await preflightLiveLLM(config)
const testRoot = await mkdtemp(path.join(os.tmpdir(), `deepagent-code-${input.suite}-`))
const isolatedHome = path.join(testRoot, "home")
@@ -178,7 +197,9 @@ export async function runLegacyLiveCases(input: {
const { ModelV2 } = await import("@deepagent-code/core/model")
const { ProviderV2 } = await import("@deepagent-code/core/provider")
const { CrossSpawnSpawner } = await import("@deepagent-code/core/cross-spawn-spawner")
+ const { EffectFlock } = await import("@deepagent-code/core/util/effect-flock")
const { Context, Deferred, Effect, Fiber, Layer, Schedule } = await import("effect")
+ const { eq } = await import("drizzle-orm")
const { AgentExecution } = await import("@deepagent-code/core/deepagent/agent-execution")
const { ApprovalQueue } = await import("@deepagent-code/core/deepagent/approval-queue")
const { DeepAgentEventBus } = await import("@deepagent-code/core/deepagent/deepagent-event-bus")
@@ -195,11 +216,17 @@ export async function runLegacyLiveCases(input: {
const { Permission } = await import("../../src/permission")
const { Question } = await import("../../src/question")
const { SessionCompaction } = await import("../../src/session/compaction")
+ const { CompactionRunTable, CompactionSummaryAttemptTable } = await import("../../src/session/compaction-sql")
+ const { SessionPromptEpochTable } = await import("../../src/session/prompt-epoch.sql")
+ const { SessionPromptIntent } = await import("../../src/session/prompt-intent")
const { SessionPrompt } = await import("../../src/session/prompt")
+ const { SessionRevert } = await import("../../src/session/revert")
const { SessionRunState } = await import("../../src/session/run-state")
const { MessageID } = await import("../../src/session/schema")
const { SessionSteer } = await import("../../src/session/steer")
const { Session } = await import("../../src/session/session")
+ const { SessionToolRequestReceiptTable } = await import("../../src/session/tool-request-receipt.sql")
+ const { SessionIntentTable } = await import("@deepagent-code/core/session/sql")
const { EventDispatcher } = await import("../../src/session/event-dispatcher")
const { MultiAgentRuntime } = await import("../../src/session/multi-agent-runtime")
const { makeEventTurnRunner } = await import("../../src/session/v4-event-runtime")
@@ -225,9 +252,11 @@ export async function runLegacyLiveCases(input: {
| undefined
const program = Effect.gen(function* () {
const prompts = yield* SessionPrompt.Service
+ const database = yield* Database.Service
const runState = yield* SessionRunState.Service
const steers = yield* SessionSteer.Service
const compaction = yield* SessionCompaction.Service
+ const revert = yield* SessionRevert.Service
const sessions = yield* Session.Service
const instance = yield* TestInstance
const parentInstance = yield* InstanceRef
@@ -537,6 +566,13 @@ export async function runLegacyLiveCases(input: {
permission: Permission.fromConfig(input.primaryPermission ?? input.permission ?? {}),
})
: undefined
+ const admittedCases = new Map<
+ string,
+ Parameters[0] & {
+ readonly intentID: string
+ readonly messageID: ReturnType
+ }
+ >()
const observations = yield* Effect.forEach(input.cases, (testCase) =>
Effect.gen(function* () {
const session = sharedSession ?? (yield* sessions.create({ title: `Live ${input.suite}: ${testCase.name}` }))
@@ -545,6 +581,40 @@ export async function runLegacyLiveCases(input: {
input.beforeCase!({ caseName: testCase.name, directory: instance.directory, sandbox }),
)
}
+ const revertEvidence = testCase.revertBefore
+ ? yield* Effect.gen(function* () {
+ const target = admittedCases.get(testCase.revertBefore!.targetCase)
+ if (!target || target.sessionID !== session.id) {
+ return yield* Effect.die(
+ new Error(`Missing same-Session revert target ${testCase.revertBefore!.targetCase}`),
+ )
+ }
+ const epochBefore = yield* sessions.mutationEpoch(session.id).pipe(Effect.orDie)
+ yield* revert.revert({ sessionID: session.id, messageID: target.messageID })
+ const epochAfter = yield* sessions.mutationEpoch(session.id).pipe(Effect.orDie)
+ const retry = testCase.revertBefore!.retryTargetIntent
+ ? yield* prompts
+ .promptAsync({ ...target, messageID: MessageID.ascending() })
+ .pipe(
+ Effect.as({ accepted: true as const }),
+ Effect.catch((error) =>
+ Effect.succeed({ accepted: false as const, error: liveErrorName(error) }),
+ ),
+ )
+ : undefined
+ if (retry?.accepted) {
+ return yield* Effect.die(new Error("A pre-revert prompt intent was admitted in a newer mutation epoch"))
+ }
+ yield* revert.cleanup(yield* sessions.get(session.id).pipe(Effect.orDie), epochAfter)
+ return {
+ targetCase: testCase.revertBefore!.targetCase,
+ targetMessageID: target.messageID,
+ epochBefore,
+ epochAfter,
+ retry,
+ }
+ })
+ : undefined
const messagesBefore = yield* sessions.messages({ sessionID: session.id })
const toolCountBefore = messagesBefore.reduce(
(count, message) => count + message.parts.filter((part) => part.type === "tool").length,
@@ -568,6 +638,13 @@ export async function runLegacyLiveCases(input: {
pendingAfterAdmission: boolean
consumedAfterAdmission: boolean
}> = []
+ if (testCase.admission) {
+ yield* SessionPromptIntent.prepare({
+ intentID: testCase.admission.intentID,
+ sessionID: session.id,
+ source: testCase.admission.source,
+ }).pipe(Effect.provideService(Database.Service, database))
+ }
const intelligenceDraft = testCase.intelligence
? yield* prompts.refineIntelligenceDraft({
sessionID: session.id,
@@ -575,25 +652,131 @@ export async function runLegacyLiveCases(input: {
outputLanguage: testCase.intelligence.outputLanguage,
})
: undefined
- if (intelligenceDraft && (intelligenceDraft.route !== "code" || !intelligenceDraft.prompt_draft_id)) {
+ const expectedIntelligenceRoute = testCase.intelligence?.expectedRoute ?? "code"
+ if (intelligenceDraft && intelligenceDraft.route !== expectedIntelligenceRoute) {
+ return yield* Effect.die(
+ new Error(
+ `Intelligence live case expected ${expectedIntelligenceRoute} but received ${intelligenceDraft.route}`,
+ ),
+ )
+ }
+ if (intelligenceDraft?.route === "code" && !intelligenceDraft.prompt_draft_id) {
return yield* Effect.die(new Error("Intelligence live case did not produce a confirmable code draft"))
}
- const turn = prompts.prompt({
- sessionID: session.id,
- model: { providerID, modelID },
- agent: testCase.agent ?? "live-test",
- parts: [{ type: "text", text: testCase.prompt }],
- metadata: intelligenceDraft
+ const metadata = intelligenceDraft
+ ? intelligenceDraft.route === "code"
? {
deepagent: {
prompt_pipeline: {
- mode: "intelligence",
+ mode: "intelligence" as const,
confirmed_draft_id: intelligenceDraft.prompt_draft_id,
},
},
}
- : undefined,
- })
+ : {
+ deepagent: {
+ agent_mode_override: "general" as const,
+ prompt_pipeline: { mode: "direct_override" as const },
+ },
+ }
+ : undefined
+ const promptInput = {
+ sessionID: session.id,
+ model: { providerID, modelID },
+ agent: testCase.agent ?? "live-test",
+ parts: [{ type: "text", text: testCase.prompt }],
+ metadata,
+ ...(testCase.admission
+ ? {
+ messageID: MessageID.ascending(),
+ intentID: testCase.admission.intentID,
+ intentSource: testCase.admission.source,
+ intentVariant: testCase.admission.variant,
+ }
+ : {}),
+ } satisfies Parameters[0]
+ const admissionRetryEvidence: Array<{
+ activeBeforeRetry: boolean
+ exact?: { accepted: true; userCountBefore: number; userCountAfter: number }
+ conflict?: { accepted: boolean; error?: string }
+ }> = []
+ const turn = testCase.admission
+ ? Effect.gen(function* () {
+ yield* prompts.promptAsync(promptInput)
+ if (!promptInput.messageID) {
+ return yield* Effect.die(new Error("Durable admission did not reserve a message ID"))
+ }
+ admittedCases.set(testCase.name, {
+ ...promptInput,
+ intentID: testCase.admission!.intentID,
+ messageID: promptInput.messageID,
+ })
+ const hasRetry = testCase.admission!.exactRetry || testCase.admission!.conflictingRetry
+ const activeBeforeRetry = hasRetry
+ ? yield* runState
+ .isBusy(session.id)
+ .pipe(
+ Effect.repeat({ while: (busy) => !busy, schedule: Schedule.spaced("10 millis") }),
+ Effect.timeout(config.timeoutMs),
+ )
+ : false
+ if (hasRetry && !activeBeforeRetry) {
+ return yield* Effect.die(new Error("Admitted prompt did not enter an active turn before retry"))
+ }
+ const exact = testCase.admission!.exactRetry
+ ? yield* Effect.gen(function* () {
+ const before = (yield* sessions.messages({ sessionID: session.id })).filter(
+ (message) => message.info.role === "user",
+ ).length
+ yield* prompts.promptAsync({ ...promptInput, messageID: MessageID.ascending() })
+ const after = (yield* sessions.messages({ sessionID: session.id })).filter(
+ (message) => message.info.role === "user",
+ ).length
+ if (after !== before) {
+ return yield* Effect.die(new Error("An exact prompt intent retry created another user message"))
+ }
+ return { accepted: true as const, userCountBefore: before, userCountAfter: after }
+ })
+ : undefined
+ const conflict = testCase.admission!.conflictingRetry
+ ? yield* prompts
+ .promptAsync({
+ ...promptInput,
+ messageID: MessageID.ascending(),
+ intentVariant: testCase.admission!.conflictingRetry.variant,
+ parts: [{ type: "text", text: testCase.admission!.conflictingRetry.prompt }],
+ })
+ .pipe(
+ Effect.as({ accepted: true as const }),
+ Effect.catch((error) =>
+ Effect.succeed({ accepted: false as const, error: liveErrorName(error) }),
+ ),
+ )
+ : undefined
+ if (conflict?.accepted) {
+ return yield* Effect.die(new Error("A conflicting prompt intent retry was admitted"))
+ }
+ admissionRetryEvidence.push({ activeBeforeRetry, exact, conflict })
+ return yield* Effect.gen(function* () {
+ const busy = yield* runState.isBusy(session.id)
+ const messages = yield* sessions.messages({ sessionID: session.id })
+ const assistant = messages
+ .filter(
+ (message): message is SessionV1.WithParts & { info: SessionV1.Assistant } =>
+ message.info.role === "assistant",
+ )
+ .slice(assistantCountBefore)
+ .findLast((message) => message.info.time.completed !== undefined || message.info.error !== undefined)
+ return !busy && assistant ? assistant : undefined
+ }).pipe(
+ Effect.repeat({ while: (result) => result === undefined, schedule: Schedule.spaced("50 millis") }),
+ Effect.timeout(config.timeoutMs),
+ Effect.flatMap((result) =>
+ result ? Effect.succeed(result) : Effect.die(new Error("Admitted prompt produced no terminal assistant")),
+ ),
+ )
+ })
+ : prompts.prompt(promptInput)
const result =
concurrentSteers.length === 0
? yield* turn
@@ -854,6 +1037,41 @@ export async function runLegacyLiveCases(input: {
),
)
const info = yield* sessions.get(session.id)
+ const intent = testCase.admission
+ ? yield* database.db
+ .select()
+ .from(SessionIntentTable)
+ .where(eq(SessionIntentTable.intent_id, testCase.admission.intentID))
+ .get()
+ .pipe(Effect.orDie)
+ : undefined
+ const durability = input.inspectDurability
+ ? {
+ promptEpochs: yield* database.db
+ .select()
+ .from(SessionPromptEpochTable)
+ .where(eq(SessionPromptEpochTable.session_id, session.id))
+ .all()
+ .pipe(Effect.orDie),
+ compactionRuns: yield* database.db
+ .select()
+ .from(CompactionRunTable)
+ .where(eq(CompactionRunTable.session_id, session.id))
+ .all()
+ .pipe(Effect.orDie),
+ summaryAttempts: yield* database.db
+ .select()
+ .from(CompactionSummaryAttemptTable)
+ .all()
+ .pipe(Effect.orDie),
+ requestReceipts: yield* database.db
+ .select()
+ .from(SessionToolRequestReceiptTable)
+ .where(eq(SessionToolRequestReceiptTable.session_id, session.id))
+ .all()
+ .pipe(Effect.orDie),
+ }
+ : undefined
return {
name: testCase.name,
sessionID: session.id,
@@ -864,6 +1082,21 @@ export async function runLegacyLiveCases(input: {
steering: steeringEvidence,
messageCount: messages.length,
intelligenceDraft,
+ durability,
+ admission: intent
+ ? {
+ intentID: intent.intent_id,
+ state: intent.state,
+ source: intent.source,
+ variant: intent.selected_variant,
+ delivery: intent.delivery,
+ admittedMessageID: intent.admitted_message_id,
+ mutationEpoch: intent.mutation_epoch,
+ version: intent.version,
+ retry: admissionRetryEvidence[0],
+ }
+ : undefined,
+ revert: revertEvidence,
users: currentUsers.map((message) => ({
metadata: message.info.metadata,
text: message.parts
@@ -874,6 +1107,11 @@ export async function runLegacyLiveCases(input: {
.join(""),
})),
assistantTurns: currentAssistants.length,
+ assistantTexts: currentAssistants.map((message) =>
+ message.parts
+ .flatMap((part) => (part.type === "text" && !part.synthetic && !part.ignored ? [part.text] : []))
+ .join(""),
+ ),
summaryTexts: currentAssistants
.filter((message) => message.info.summary === true)
.map((message) =>
@@ -1085,12 +1323,14 @@ export async function runLegacyLiveCases(input: {
SessionRunState.defaultLayer,
SessionSteer.defaultLayer,
SessionCompaction.defaultLayer,
+ SessionRevert.defaultLayer,
Session.defaultLayer,
Permission.defaultLayer,
Question.defaultLayer,
EventV2Bridge.defaultLayer,
Worktree.appLayer,
Git.defaultLayer,
+ EffectFlock.defaultLayer,
PRQueue.layer.pipe(Layer.orDie),
CrossSpawnSpawner.defaultLayer,
Database.defaultLayer,
@@ -1174,6 +1414,13 @@ function restoreEnvironment(environment: Record) {
})
}
+function liveErrorName(error: unknown) {
+ if (typeof error !== "object" || error === null) return String(error)
+ if ("_tag" in error && typeof error._tag === "string") return error._tag
+ if (error instanceof Error) return error.name
+ return "UnknownError"
+}
+
async function prepareIsolation(
testRoot: string,
isolatedHome: string,
diff --git a/packages/deepagent-code/script/live-llm/subagent-control-plane.ts b/packages/deepagent-code/script/live-llm/subagent-control-plane.ts
new file mode 100644
index 00000000..bfb347bd
--- /dev/null
+++ b/packages/deepagent-code/script/live-llm/subagent-control-plane.ts
@@ -0,0 +1,255 @@
+import path from "node:path"
+import { writeLiveArtifact } from "../../../llm/script/live-llm/config"
+import { finishLiveScript } from "./lifecycle"
+import { runLegacyLiveCases } from "./runtime"
+
+// ─── REAL-CP-01: dirty-workspace read-only subagent ───────────────────────────
+//
+// Oracle: task_run.mutation_capability DB row (read_only enforced by L3a admission),
+// observed via:
+// 1. task_run.state = "completed" surfaced through task_status (L10 durable overlay)
+// 2. child session's tool set — no write/edit/bash completed calls (read_only fence)
+// 3. dirty parent workspace did NOT block admission (L3b only blocks writers)
+
+const marker01 = `cp01-${crypto.randomUUID()}`
+const evidence01 = `Control plane fixture key: ${marker01}`
+
+const prompt01 = [
+ "Call task exactly once in foreground mode with subagent_type researcher and description cp01 dirty-workspace read-only research.",
+ "The child prompt must be exactly: Read fixtures/cp01.txt exactly once. Return a valid ResearchResult with mechanism set to the file content exactly, without quotes or explanation. Do not call task.",
+ "Do not read the fixture in the parent.",
+ "After the task completes, call task_status exactly once.",
+ "Report the child session id and the completion state shown by task_status.",
+].join("\n")
+
+const artifact01 = await runLegacyLiveCases({
+ suite: "subagent-cp-dirty-readonly",
+ permission: { "*": "deny", read: "allow" },
+ primaryPermission: { "*": "deny", task: "allow", task_status: "allow" },
+ environment: { DEEPAGENT_CODE_SUBAGENT_CONTROL_PLANE: "durable" },
+ cases: [{ name: "subagent-dirty-readonly", prompt: prompt01 }],
+ files: { "fixtures/cp01.txt": `${evidence01}\n` },
+ beforeCase: async ({ directory }) => {
+ // Write an uncommitted file so the parent workspace is dirty.
+ // A researcher (mutation_capability=read_only) must still be admitted — only
+ // automatic writers are blocked by L3b preflight (design §3.2 + §15.3.3).
+ await Bun.write(path.join(directory, "dirty-marker.txt"), `dirty-${marker01}\n`)
+ },
+})
+
+await writeLiveArtifact(
+ { artifactDirectory: path.resolve(import.meta.dir, "../../.artifacts/live-llm") },
+ `${artifact01.suite}-observed`,
+ { ...artifact01, status: "observed" },
+)
+
+// ─── Oracle: REAL-CP-01 ───────────────────────────────────────────────────────
+
+const cp01 = artifact01.cases[0]
+if (!cp01) throw new Error("REAL-CP-01: Missing observation")
+
+const cp01Done = cp01.tools.filter((t) => t.status === "completed")
+if (!cp01Done.some((t) => t.name === "task")) {
+ throw new Error(
+ `REAL-CP-01: Parent did not complete a task call; tools: ${cp01.tools.map((t) => `${t.name}:${t.status}`).join(", ")}`,
+ )
+}
+if (!cp01Done.some((t) => t.name === "task_status")) {
+ throw new Error("REAL-CP-01: Parent did not call task_status")
+}
+
+// DB-oracle: task_status reads from task_run.state (L10 durable overlay in task_status.ts).
+// D-2 (P1-10): production outputs English "completed" state, not French "[terminé]".
+// Accept either so this harness works after the string alignment fix.
+const statusOut01 = cp01Done.find((t) => t.name === "task_status")?.output ?? ""
+if (!statusOut01.includes("completed") && !statusOut01.includes("[terminé]")) {
+ throw new Error(
+ `REAL-CP-01: task_status DB-oracle did not report completed state. Output: ${statusOut01.slice(0, 300)}`,
+ )
+}
+
+if (cp01.children.length !== 1) {
+ throw new Error(`REAL-CP-01: Expected one child session, received ${cp01.children.length}`)
+}
+const child01 = cp01.children[0]!
+if (child01.parentID !== cp01.sessionID || child01.agent !== "researcher") {
+ throw new Error("REAL-CP-01: Child lineage or agent type incorrect")
+}
+
+// DB-oracle: child session metadata — set by settleSubagentRun in task.ts
+const subagent01 = nestedRecord(child01.metadata, ["deepagent", "subagent"])
+if (subagent01.finished !== true || subagent01.state !== "completed") {
+ throw new Error(
+ `REAL-CP-01: Child durable metadata state incorrect: ${JSON.stringify(subagent01)}`,
+ )
+}
+if (typeof subagent01.run_id !== "string" || subagent01.run_id.length === 0) {
+ throw new Error("REAL-CP-01: Child durable metadata missing run_id — legacy path was used, not durable")
+}
+
+// mutation_capability=read_only fence: child must NOT have successfully called mutating tools
+const childTools01 = child01.assistants.flatMap((a) => a.tools)
+const mutating01 = childTools01.filter(
+ (t) => t.status === "completed" && ["write", "edit", "bash"].includes(t.name),
+)
+if (mutating01.length > 0) {
+ throw new Error(
+ `REAL-CP-01: Read-only subagent completed mutating tool calls: ${mutating01.map((t) => t.name).join(", ")}`,
+ )
+}
+
+// L3b admission gate must NOT have blocked the researcher despite the dirty workspace
+const taskOut01 = cp01Done.find((t) => t.name === "task")?.output ?? ""
+if (taskOut01.includes("workspace_dirty") || taskOut01.includes("uncommitted changes")) {
+ throw new Error("REAL-CP-01: L3b dirty-workspace gate incorrectly rejected read-only researcher")
+}
+
+// Child must have read the fixture through a completed read tool
+if (!childTools01.some((t) => t.name === "read" && t.status === "completed" && t.output?.includes(marker01))) {
+ throw new Error("REAL-CP-01: Child did not obtain the marker through a completed read tool")
+}
+
+const result01 = {
+ ...artifact01,
+ evidence: {
+ markerHash: Bun.hash(marker01).toString(16),
+ childSessionIDLength: child01.id.length,
+ dirtyWorkspaceAllowed: true,
+ mutatingToolsUsed: mutating01.length,
+ durableState: subagent01.state,
+ runID: (subagent01.run_id as string).slice(0, 8),
+ taskStatusDbOracle: statusOut01.includes("[terminé]"),
+ },
+}
+await writeLiveArtifact(
+ { artifactDirectory: path.resolve(import.meta.dir, "../../.artifacts/live-llm") },
+ result01.suite,
+ result01,
+)
+console.log(`${result01.suite}: passed (${result01.fingerprint.providerID}/${result01.fingerprint.modelID})`)
+
+// ─── REAL-CP-02: durable event audit trail ────────────────────────────────────
+//
+// Oracle: task_run_event table (run_queued → run_claimed → execution_started → run_settled).
+// These four events must all have been written for task_run.state to reach "completed".
+// Direct table access is not available from the live-test harness, so we verify the
+// implied invariant: task_run.state = "completed" (surfaced by task_status L10 overlay)
+// + child.metadata.deepagent.subagent.{finished, state, run_id, generation} set by
+// settleSubagentRun — which is only reached after run_settled is written.
+
+const marker02 = `cp02-${crypto.randomUUID()}`
+const evidence02 = `Audit fixture key: ${marker02}`
+
+const prompt02 = [
+ "Call task exactly once in foreground mode with subagent_type researcher and description cp02 durable-events audit.",
+ "The child prompt must be exactly: Read fixtures/cp02.txt exactly once. Return a valid ResearchResult with mechanism set to the file content exactly, without quotes or explanation. Do not call task.",
+ "Do not read the fixture in the parent.",
+ "After the task completes, call task_status exactly once.",
+ "Report the child session id and the state shown by task_status.",
+].join("\n")
+
+const artifact02 = await runLegacyLiveCases({
+ suite: "subagent-cp-durable-events",
+ permission: { "*": "deny", read: "allow" },
+ primaryPermission: { "*": "deny", task: "allow", task_status: "allow" },
+ environment: { DEEPAGENT_CODE_SUBAGENT_CONTROL_PLANE: "durable" },
+ cases: [{ name: "subagent-durable-events", prompt: prompt02 }],
+ files: { "fixtures/cp02.txt": `${evidence02}\n` },
+})
+
+await writeLiveArtifact(
+ { artifactDirectory: path.resolve(import.meta.dir, "../../.artifacts/live-llm") },
+ `${artifact02.suite}-observed`,
+ { ...artifact02, status: "observed" },
+)
+
+// ─── Oracle: REAL-CP-02 ───────────────────────────────────────────────────────
+
+const cp02 = artifact02.cases[0]
+if (!cp02) throw new Error("REAL-CP-02: Missing observation")
+
+const cp02Done = cp02.tools.filter((t) => t.status === "completed")
+if (!cp02Done.some((t) => t.name === "task")) {
+ throw new Error(
+ `REAL-CP-02: Parent did not complete a task call; tools: ${cp02.tools.map((t) => `${t.name}:${t.status}`).join(", ")}`,
+ )
+}
+if (!cp02Done.some((t) => t.name === "task_status")) {
+ throw new Error("REAL-CP-02: Parent did not call task_status")
+}
+
+// DB-oracle: task_run.state sourced via task_status L10 durable overlay.
+// "completed" in task_status means the run_settled event was committed to task_run_event,
+// which is only written after execution_started, which follows run_claimed, run_queued.
+// D-2 (P1-10): accept both "completed" and "[terminé]" for forward/backward compat.
+const statusOut02 = cp02Done.find((t) => t.name === "task_status")?.output ?? ""
+if (!statusOut02.includes("completed") && !statusOut02.includes("[terminé]")) {
+ throw new Error(
+ `REAL-CP-02: task_status DB-oracle did not report completed state. Output: ${statusOut02.slice(0, 300)}`,
+ )
+}
+
+if (cp02.children.length !== 1) {
+ throw new Error(`REAL-CP-02: Expected one child session, received ${cp02.children.length}`)
+}
+const child02 = cp02.children[0]!
+if (child02.parentID !== cp02.sessionID || child02.agent !== "researcher") {
+ throw new Error("REAL-CP-02: Child lineage or agent type incorrect")
+}
+
+// DB-oracle: metadata set by settleSubagentRun → implies run_settled event was written
+const subagent02 = nestedRecord(child02.metadata, ["deepagent", "subagent"])
+if (subagent02.finished !== true || subagent02.state !== "completed") {
+ throw new Error(
+ `REAL-CP-02: Durable event audit incomplete — child has state=${subagent02.state} finished=${subagent02.finished}`,
+ )
+}
+
+// Presence of run_id and generation proves the durable code path was taken (not legacy)
+if (typeof subagent02.run_id !== "string" || subagent02.run_id.length === 0) {
+ throw new Error("REAL-CP-02: Child durable metadata missing run_id — durable path was not activated")
+}
+if (typeof subagent02.generation !== "number") {
+ throw new Error("REAL-CP-02: Child durable metadata missing generation — durable path was not activated")
+}
+
+// Child must have read the fixture through a completed read tool
+const childTools02 = child02.assistants.flatMap((a) => a.tools)
+if (!childTools02.some((t) => t.name === "read" && t.status === "completed" && t.output?.includes(marker02))) {
+ throw new Error("REAL-CP-02: Child did not obtain the marker through a completed read tool")
+}
+
+const result02 = {
+ ...artifact02,
+ evidence: {
+ markerHash: Bun.hash(marker02).toString(16),
+ childSessionIDLength: child02.id.length,
+ durableState: subagent02.state,
+ runID: (subagent02.run_id as string).slice(0, 8),
+ generation: subagent02.generation,
+ taskStatusDbOracle: statusOut02.includes("[terminé]"),
+ // All four events must have been written in task_run_event for state="completed":
+ impliedEventTrail: ["run_queued", "run_claimed", "execution_started", "run_settled"],
+ },
+}
+await writeLiveArtifact(
+ { artifactDirectory: path.resolve(import.meta.dir, "../../.artifacts/live-llm") },
+ result02.suite,
+ result02,
+)
+console.log(`${result02.suite}: passed (${result02.fingerprint.providerID}/${result02.fingerprint.modelID})`)
+
+// ─── Helpers ─────────────────────────────────────────────────────────────────
+
+function nestedRecord(value: unknown, keys: string[]) {
+ const result = keys.reduce | undefined>((current, key) => {
+ if (!current) return undefined
+ const next = current[key]
+ if (typeof next !== "object" || next === null || Array.isArray(next)) return undefined
+ return next as Record
+ }, typeof value === "object" && value !== null && !Array.isArray(value) ? (value as Record) : undefined)
+ if (!result) throw new Error(`Missing object path ${keys.join(".")}`)
+ return result
+}
+
+finishLiveScript()
diff --git a/packages/deepagent-code/script/live-llm/subagent-takeover.ts b/packages/deepagent-code/script/live-llm/subagent-takeover.ts
index 4e261515..8cc26a69 100644
--- a/packages/deepagent-code/script/live-llm/subagent-takeover.ts
+++ b/packages/deepagent-code/script/live-llm/subagent-takeover.ts
@@ -5,112 +5,104 @@ import { runLegacyLiveCases } from "./runtime"
const prompt = [
"Your first assistant response must contain exactly one task tool call and no text.",
- "Call task in foreground mode with subagent_type researcher and description verify bounded takeover.",
+ "Call task in foreground mode with subagent_type researcher and description verify explicit timeout recovery.",
"The child prompt must be exactly: Call question immediately and exactly once to ask whether to continue, with one Continue option. Wait for the answer. Do not call any other tool and do not return before the answer.",
"The test operator will deliberately leave the question unanswered.",
- "After the task reports that bounded takeover was exhausted, do not call any more tools. Report that the child timed out and takeover stopped at its configured limit.",
+ "After task returns an attempt_timeout error, call task_read exactly once with the child session id from that error.",
+ "After task_read returns, do not call any more tools. Report that automatic retry was disabled, no replacement child was created, and the interrupted transcript was recovered.",
].join(" ")
const artifact = await runLegacyLiveCases({
suite: "subagent-takeover-legacy",
permission: { "*": "deny", question: "allow" },
- primaryPermission: { "*": "deny", task: "allow" },
+ primaryPermission: { "*": "deny", task: "allow", task_read: "allow" },
questionAction: { type: "hold" },
- cases: [{ name: "bounded-takeover", prompt }],
+ cases: [{ name: "explicit-timeout-recovery", prompt }],
environment: {
DEEPAGENT_ENABLED: "false",
DEEPAGENT_CODE_SUBAGENT_TIMEOUT_MS: "15000",
- DEEPAGENT_CODE_SUBAGENT_TAKEOVER_LIMIT: "1",
},
modelMaxTokens: 512,
- maxProviderTurns: 6,
+ maxProviderTurns: 8,
timeoutMs: 120_000,
})
await writeLiveArtifact(
{ artifactDirectory: path.resolve(import.meta.dir, "../../.artifacts/live-llm") },
`${artifact.suite}-observed`,
- artifact,
+ { ...artifact, status: "observed" },
)
const observation = artifact.cases[0]
if (!observation || observation.providerErrors.length > 0) {
- throw new Error(`Bounded takeover provider turn failed: ${JSON.stringify(observation?.providerErrors)}`)
+ throw new Error(`Explicit timeout recovery provider turn failed: ${JSON.stringify(observation?.providerErrors)}`)
}
-if (
- observation.tools.length !== 1 ||
- observation.tools[0]?.name !== "task" ||
- observation.tools[0].status !== "error"
-) {
+const task = observation.tools.find((tool) => tool.name === "task")
+const transcript = observation.tools.find((tool) => tool.name === "task_read")
+if (observation.tools.length !== 2 || task?.status !== "error" || transcript?.status !== "completed") {
throw new Error(
- `Parent did not execute exactly one failing task: ${observation.tools.map((tool) => `${tool.name}:${tool.status}`).join(", ")}`,
+ `Parent did not execute one failing task followed by task_read: ${observation.tools.map((tool) => `${tool.name}:${tool.status}`).join(", ")}`,
)
}
if (
- !observation.tools[0].error?.includes("bounded takeover") ||
- !observation.tools[0].error.includes("[timeout]") ||
- !observation.tools[0].error.includes("task_read")
+ !task.error?.includes("[attempt_timeout]") ||
+ !task.error.includes("Automatic retry is disabled") ||
+ !task.error.includes("task_read")
) {
- throw new Error(`Task did not surface the bounded timeout recovery contract: ${observation.tools[0].error}`)
+ throw new Error(`Task did not surface the explicit timeout recovery contract: ${task.error}`)
}
-if (observation.children.length !== 2) {
- throw new Error(`Expected the original child and one takeover child, received ${observation.children.length}`)
+if (observation.children.length !== 1) {
+ throw new Error(`Expected one interrupted child without automatic replay, received ${observation.children.length}`)
}
-if (observation.questionRequests.length !== 2 || observation.pendingQuestionIDs.length !== 0) {
+if (observation.questionRequests.length !== 1 || observation.pendingQuestionIDs.length !== 0) {
throw new Error(
- `Question lifecycle did not settle after takeover: ${JSON.stringify({
+ `Question lifecycle did not settle after timeout: ${JSON.stringify({
requests: observation.questionRequests,
pending: observation.pendingQuestionIDs,
})}`,
)
}
-const terminal = observation.children.map((child) => {
- if (
- child.parentID !== observation.sessionID ||
- child.agent !== "researcher" ||
- child.model?.providerID !== "live-deepseek" ||
- child.model.id !== artifact.fingerprint.modelID ||
- child.assistants.length === 0 ||
- child.assistants.some(
- (assistant) =>
- assistant.providerID !== "live-deepseek" ||
- assistant.modelID !== artifact.fingerprint.modelID ||
- record(assistant.error, "expected timeout assistant error").name !== "MessageAbortedError",
- )
- ) {
- throw new Error(`Takeover child ${child.id} has invalid lineage or provider/model identity`)
- }
- const questions = child.assistants.flatMap((assistant) => assistant.tools).filter((tool) => tool.name === "question")
- if (
- questions.length !== 1 ||
- questions[0]?.status !== "error" ||
- !questions[0].error?.includes("aborted") ||
- observation.questionRequests.filter((request) => request.sessionID === child.id).length !== 1
- ) {
- throw new Error(`Takeover child ${child.id} did not reach exactly one held production question`)
- }
- return nestedRecord(child.metadata, ["deepagent", "subagent"])
-})
-
+const child = observation.children[0]!
if (
- terminal[0]?.state !== "cancelled" ||
- terminal[0].reason !== "takeover" ||
- terminal[0].finished !== true ||
- terminal[1]?.state !== "error" ||
- terminal[1].reason !== "timeout" ||
- terminal[1].finished !== true
+ child.parentID !== observation.sessionID ||
+ child.agent !== "researcher" ||
+ child.model?.providerID !== "live-deepseek" ||
+ child.model.id !== artifact.fingerprint.modelID ||
+ child.assistants.length === 0 ||
+ child.assistants.some(
+ (assistant) =>
+ assistant.providerID !== "live-deepseek" ||
+ assistant.modelID !== artifact.fingerprint.modelID ||
+ record(assistant.error, "expected timeout assistant error").name !== "MessageAbortedError",
+ )
) {
- throw new Error(`Takeover attempts have invalid durable terminal states: ${JSON.stringify(terminal)}`)
+ throw new Error(`Interrupted child ${child.id} has invalid lineage or provider/model identity`)
}
+const questions = child.assistants.flatMap((assistant) => assistant.tools).filter((tool) => tool.name === "question")
if (
- !observation.finalText.toLowerCase().includes("timeout") &&
- !observation.finalText.toLowerCase().includes("timed out") &&
- !observation.finalText.includes("超时")
+ questions.length !== 1 ||
+ questions[0]?.status !== "error" ||
+ !questions[0].error?.includes("aborted") ||
+ observation.questionRequests.filter((request) => request.sessionID === child.id).length !== 1
) {
- throw new Error("Parent did not report the bounded timeout outcome")
+ throw new Error(`Interrupted child ${child.id} did not reach exactly one held production question`)
+}
+const terminal = nestedRecord(child.metadata, ["deepagent", "subagent"])
+if (
+ terminal.state !== "interrupted" ||
+ terminal.reason !== "attempt_timeout" ||
+ terminal.finished !== true ||
+ terminal.attempts !== 0
+) {
+ throw new Error(`Timed out child has invalid durable terminal state: ${JSON.stringify(terminal)}`)
+}
+if (!transcript.output?.includes(`id="${child.id}"`) || !transcript.output.includes('state="interrupted"')) {
+ throw new Error("task_read did not recover the original interrupted child transcript")
}
if (observation.pendingPermissionIDs.length !== 0) {
- throw new Error(`Bounded takeover leaked permission requests: ${observation.pendingPermissionIDs.join(", ")}`)
+ throw new Error(
+ `Explicit timeout recovery leaked permission requests: ${observation.pendingPermissionIDs.join(", ")}`,
+ )
}
const result = {
@@ -120,7 +112,8 @@ const result = {
childCount: observation.children.length,
questionCount: observation.questionRequests.length,
pendingQuestionCount: observation.pendingQuestionIDs.length,
- terminalStates: terminal.map((item) => `${String(item.state)}:${String(item.reason)}`),
+ terminalState: `${String(terminal.state)}:${String(terminal.reason)}`,
+ recoveredTranscript: true,
parentTools: observation.tools.map((tool) => `${tool.name}:${tool.status}`),
},
}
diff --git a/packages/deepagent-code/script/models-data.ts b/packages/deepagent-code/script/models-data.ts
new file mode 100644
index 00000000..a4cb245d
--- /dev/null
+++ b/packages/deepagent-code/script/models-data.ts
@@ -0,0 +1,87 @@
+import { mkdir, rename, rm } from "node:fs/promises"
+import os from "node:os"
+import path from "node:path"
+import { resolveDataPath } from "@deepagent-code/core/global-path"
+
+const repositorySnapshotFile = path.resolve(import.meta.dir, "../test/tool/fixtures/models-api.json")
+
+export async function loadModelsData(
+ options: {
+ environment?: Readonly>
+ cacheFile?: string
+ fallbackFiles?: readonly string[]
+ requestTimeoutMs?: number
+ } = {},
+) {
+ const environment = options.environment ?? process.env
+ const configuredFile = environment.MODELS_DEV_API_JSON?.trim()
+ if (configuredFile) {
+ const configured = await readCatalog(configuredFile)
+ if (!configured) throw new Error(`Configured models.dev snapshot is invalid: ${configuredFile}`)
+ return { data: JSON.stringify(configured), source: configuredFile }
+ }
+
+ const modelsURL = (environment.DEEPAGENT_CODE_MODELS_URL?.trim() || "https://models.dev").replace(/\/$/, "")
+ const remote = await fetch(`${modelsURL}/api.json`, {
+ signal: AbortSignal.timeout(options.requestTimeoutMs ?? 10_000),
+ })
+ .then(async (response) => (response.ok ? catalog(await response.json()) : undefined))
+ .catch(() => undefined)
+ const cacheFile = options.cacheFile ?? path.join(resolveDataPath(), "cache", "models.json")
+ if (remote) {
+ await persistCatalog(cacheFile, remote).catch((error) =>
+ console.warn(
+ `Unable to update models.dev build cache: ${error instanceof Error ? error.message : String(error)}`,
+ ),
+ )
+ return { data: JSON.stringify(remote), source: `${modelsURL}/api.json` }
+ }
+
+ const fallbacks = options.fallbackFiles ?? [
+ cacheFile,
+ path.join(os.homedir(), ".cache", "opencode", "models.json"),
+ repositorySnapshotFile,
+ ]
+ const cached = (await Promise.all(fallbacks.map(async (file) => ({ file, data: await readCatalog(file) })))).find(
+ (item): item is { file: string; data: Record } => item.data !== undefined,
+ )
+ if (!cached) throw new Error(`Unable to load a valid models.dev catalog from ${modelsURL} or local snapshots`)
+ return { data: JSON.stringify(cached.data), source: cached.file }
+}
+
+function catalog(value: unknown): Record | undefined {
+ if (typeof value !== "object" || value === null || Array.isArray(value)) return
+ const providers = Object.values(value)
+ if (providers.length === 0) return
+ if (
+ providers.some(
+ (provider) =>
+ typeof provider !== "object" ||
+ provider === null ||
+ Array.isArray(provider) ||
+ typeof (provider as Record).models !== "object" ||
+ (provider as Record).models === null ||
+ Array.isArray((provider as Record).models),
+ )
+ )
+ return
+ return value as Record
+}
+
+async function readCatalog(file: string) {
+ return catalog(
+ await Bun.file(file)
+ .json()
+ .catch(() => undefined),
+ )
+}
+
+async function persistCatalog(file: string, data: Record) {
+ const temporary = `${file}.${process.pid}.${Date.now()}.tmp`
+ await mkdir(path.dirname(file), { recursive: true })
+ await Bun.write(temporary, `${JSON.stringify(data)}\n`)
+ await rename(temporary, file).catch(async (error) => {
+ await rm(temporary, { force: true })
+ throw error
+ })
+}
diff --git a/packages/deepagent-code/src/agent/__tests__/subagent-permissions.test.ts b/packages/deepagent-code/src/agent/__tests__/subagent-permissions.test.ts
index 8c3d9eaa..a025516d 100644
--- a/packages/deepagent-code/src/agent/__tests__/subagent-permissions.test.ts
+++ b/packages/deepagent-code/src/agent/__tests__/subagent-permissions.test.ts
@@ -387,4 +387,38 @@ describe("subagentIsWriteType", () => {
const a = makeAgent("a", [makeRule("*", "deny"), makeRule("write", "allow", "output/**")])
expect(subagentIsWriteType(a)).toBe(true)
})
+
+ // BUG-001-405 Fix-A regression: researcher profile must be read-only
+ it("researcher profile (star-deny + read/grep/glob/list/webfetch/websearch/code_intel, NO bash) is read-only", () => {
+ const researcherPermissions: PermissionV1.Rule[] = [
+ makeRule("*", "deny"),
+ makeRule("grep", "allow"),
+ makeRule("glob", "allow"),
+ makeRule("list", "allow"),
+ // bash intentionally absent — matches the Fix-A change in agent.ts
+ makeRule("git_read", "allow"),
+ makeRule("webfetch", "allow"),
+ makeRule("websearch", "allow"),
+ makeRule("read", "allow"),
+ makeRule("code_intel", "allow"),
+ makeRule("context_query", "allow"),
+ makeRule("task", "deny"),
+ ]
+ const researcher = makeAgent("researcher", researcherPermissions)
+ expect(subagentIsWriteType(researcher)).toBe(false)
+ })
+
+ // Verify that adding bash back would flip the result (documents why bash must stay absent)
+ it("researcher profile WITH bash:allow is write-type (confirms Fix-A necessity)", () => {
+ const withBash: PermissionV1.Rule[] = [
+ makeRule("*", "deny"),
+ makeRule("grep", "allow"),
+ makeRule("glob", "allow"),
+ makeRule("list", "allow"),
+ makeRule("bash", "allow"), // ← the bug: this made researcher a writer
+ makeRule("read", "allow"),
+ makeRule("task", "deny"),
+ ]
+ expect(subagentIsWriteType(makeAgent("researcher-buggy", withBash))).toBe(true)
+ })
})
diff --git a/packages/deepagent-code/src/agent/agent.ts b/packages/deepagent-code/src/agent/agent.ts
index 88e347bd..115e5fed 100644
--- a/packages/deepagent-code/src/agent/agent.ts
+++ b/packages/deepagent-code/src/agent/agent.ts
@@ -300,6 +300,14 @@ export const layer = Layer.effect(
// `task: "deny"` and edit/write staying denied prevents recursive fan-out and mutation —
// they read and report, they do not delegate or change files. (deriveSubagentSessionPermission
// already denies `task` by default; the explicit deny here is belt-and-suspenders.)
+ //
+ // BUG-001-405 Fix-A: `bash` is intentionally absent here. subagentIsWriteType() treats
+ // any `bash: allow` as write-capable (unrestricted shell can write files), so including
+ // it caused researcher to be classified as a writer → clean-workspace gate blocked every
+ // researcher task in a dirty repo. researcher/reviewer are read-only roles and must not
+ // carry generic bash. Structured read tools (grep/glob/list/read/code_intel) are
+ // sufficient for all research use cases. git_read covers git-history queries
+ // (git log/diff/blame/show/etc.) without triggering write-type detection.
researcher: {
name: "researcher",
permission: Permission.merge(
@@ -309,7 +317,8 @@ export const layer = Layer.effect(
grep: "allow",
glob: "allow",
list: "allow",
- bash: "allow",
+ // bash intentionally omitted — see BUG-001-405 Fix-A comment above
+ git_read: "allow",
webfetch: "allow",
websearch: "allow",
read: "allow",
diff --git a/packages/deepagent-code/src/agent/pr-collaboration.ts b/packages/deepagent-code/src/agent/pr-collaboration.ts
index 1d2e3155..7f29a8b7 100644
--- a/packages/deepagent-code/src/agent/pr-collaboration.ts
+++ b/packages/deepagent-code/src/agent/pr-collaboration.ts
@@ -108,9 +108,17 @@ export const ensureSessionBranch = Effect.fn("PRCollaboration.ensureSessionBranc
if (!repository) return false
const status = yield* input.git.porcelainStatus(input.directory)
if (!status?.clean) {
+ // BUG-001-405 Fix-C: truncate the path list to avoid flooding the parent model context.
+ // Dumping all dirty/untracked paths produced 86 k-char errors in observed sessions.
+ const MAX_SHOWN = 10
+ const allPaths = status?.paths ?? []
+ const shown = allPaths.slice(0, MAX_SHOWN).join(", ")
+ const overflow = allPaths.length > MAX_SHOWN ? ` … and ${allPaths.length - MAX_SHOWN} more` : ""
return yield* Effect.fail(
new Error(
- `Write-subagent collaboration requires a clean parent checkout; preserve or commit these paths first: ${status?.paths.join(", ") || "unknown"}`,
+ `Write-subagent collaboration requires a clean parent checkout. ` +
+ `${allPaths.length} path(s) are modified/untracked — commit or stash them first. ` +
+ `Examples: ${shown}${overflow}`,
),
)
}
diff --git a/packages/deepagent-code/src/cli/cmd/github.handler.ts b/packages/deepagent-code/src/cli/cmd/github.handler.ts
index 7ce61b82..e326f404 100644
--- a/packages/deepagent-code/src/cli/cmd/github.handler.ts
+++ b/packages/deepagent-code/src/cli/cmd/github.handler.ts
@@ -364,7 +364,7 @@ jobs:
persist-credentials: false
- name: Run deepagent-code
- uses: deepagent-ltd/deepagent-code/github@github-v1.4.4${envStr}
+ uses: deepagent-ltd/deepagent-code/github@github-v1.4.5${envStr}
with:
model: ${provider}/${model}`,
)
diff --git a/packages/deepagent-code/src/cli/cmd/run.ts b/packages/deepagent-code/src/cli/cmd/run.ts
index 5622af32..c3522eed 100644
--- a/packages/deepagent-code/src/cli/cmd/run.ts
+++ b/packages/deepagent-code/src/cli/cmd/run.ts
@@ -918,10 +918,11 @@ export const RunCommand = effectCmd({
}
if (args.goal) {
+ const objective = initialInput?.trim()
const result = await client.deepagent.goal
.start({
sessionID,
- ...(message.trim() ? { objective: message.trim() } : {}),
+ ...(objective ? { objective } : {}),
})
.catch((error) => ({ data: undefined, error }))
if (result.error || !result.data) {
diff --git a/packages/deepagent-code/src/context-federation/readiness.ts b/packages/deepagent-code/src/context-federation/readiness.ts
new file mode 100644
index 00000000..88dd52a8
--- /dev/null
+++ b/packages/deepagent-code/src/context-federation/readiness.ts
@@ -0,0 +1,78 @@
+export * as ContextFederationReadiness from "./readiness"
+
+import { ContextFederationRollout } from "@deepagent-code/core/context-federation/rollout"
+import { Database } from "@deepagent-code/core/database/database"
+import { Context, Effect, Exit, Layer } from "effect"
+import { LocationIndexRuntime } from "../location-index/runtime"
+
+const SnapshotLifetimeMs = 15_000
+
+export function unavailableSnapshot(observedAt = Date.now()): ContextFederationRollout.DerivedContextDataReadiness {
+ return {
+ state: "blocked",
+ identityBound: false,
+ indexAvailable: false,
+ storageHealthy: false,
+ observedAt,
+ expiresAt: observedAt,
+ }
+}
+
+export interface Interface {
+ readonly snapshot: () => Effect.Effect
+}
+
+export class Service extends Context.Service()("@deepagent-code/ContextFederationReadiness") {}
+
+export const layer = Layer.effect(
+ Service,
+ Effect.gen(function* () {
+ const database = yield* Database.Service
+ const runtime = yield* LocationIndexRuntime.Service
+
+ const snapshot: Interface["snapshot"] = Effect.fn("ContextFederationReadiness.snapshot")(function* () {
+ const observedAt = Date.now()
+ const current = yield* runtime.current()
+ if (!current) {
+ return {
+ state: "uninitialized",
+ identityBound: false,
+ indexAvailable: false,
+ storageHealthy: false,
+ observedAt,
+ expiresAt: observedAt + SnapshotLifetimeMs,
+ }
+ }
+
+ const [index, storage] = yield* Effect.all([
+ current.coordinator.codeStatus().pipe(Effect.exit),
+ database.db.run("SELECT 1").pipe(Effect.exit),
+ ])
+ const indexAvailable = Exit.isSuccess(index) && ["ready", "degraded"].includes(index.value.state)
+ const storageHealthy = Exit.isSuccess(storage)
+ const state = !storageHealthy
+ ? ("blocked" as const)
+ : Exit.isFailure(index) || index.value.state === "unavailable"
+ ? ("degraded" as const)
+ : index.value.state === "cold" || index.value.state === "indexing"
+ ? ("building" as const)
+ : index.value.state
+
+ return {
+ state,
+ identityBound: true,
+ indexAvailable,
+ storageHealthy,
+ observedAt,
+ expiresAt: observedAt + SnapshotLifetimeMs,
+ }
+ })
+
+ return Service.of({ snapshot })
+ }),
+)
+
+export const defaultLayer = layer.pipe(
+ Layer.provide(LocationIndexRuntime.defaultLayer),
+ Layer.provide(Database.defaultLayer),
+)
diff --git a/packages/deepagent-code/src/deepagent/validation-exec.ts b/packages/deepagent-code/src/deepagent/validation-exec.ts
index a3ef0915..7c7b0a6d 100644
--- a/packages/deepagent-code/src/deepagent/validation-exec.ts
+++ b/packages/deepagent-code/src/deepagent/validation-exec.ts
@@ -1,34 +1,81 @@
import { AgentGateway } from "@deepagent-code/core/agent-gateway"
+import type { ValidationCommandInput } from "@deepagent-code/core/deepagent/validation"
+import type { ValidationFailureKind } from "@deepagent-code/core/deepagent/round-state"
import { buffer } from "node:stream/consumers"
+import { release } from "node:os"
import { Process } from "@/util/process"
-
-// V3 A3: real validation executor. Runs the workspace validation commands (typecheck / lint /
-// test, inferred by workspace-context) and maps each to the universal ValidationResult the
-// orchestrator consumes. Used by the multi-round loop to get ground-truth pass/fail evidence.
+import { Shell } from "@/shell/shell"
export type ValidationResult = ReturnType
+type Invocation =
+ | { readonly argv: readonly string[] }
+ | { readonly kind: "unsupported_platform" | "unsupported_dialect"; readonly detail: string }
+
+type ValidationOptions = {
+ readonly shell?: string
+ readonly platform?: NodeJS.Platform
+ readonly release?: string
+ readonly env?: NodeJS.ProcessEnv
+}
+
+export function validationInvocation(
+ input: ValidationCommandInput,
+ cwd: string,
+ options?: ValidationOptions,
+): Invocation {
+ const command = AgentGateway.DeepAgentValidation.normalizeValidationCommand(input)
+ const platform = options?.platform ?? process.platform
+ const platformFailure = unsupportedPlatform(platform, options?.release ?? release(), options?.env ?? process.env)
+ if (platformFailure) return { kind: "unsupported_platform", detail: platformFailure }
+ if (command.transport === "argv") return { argv: [command.executable, ...command.args] }
+
+ const shell = options?.shell ?? validationShell()
+ if (!shell)
+ return {
+ kind: "unsupported_dialect",
+ detail: `No ${command.transport} interpreter is available for validation command "${command.display}"`,
+ }
+ return { argv: [shell, ...Shell.args(shell, command.script, cwd)] }
+}
+
export const runValidationCommands = async (
- commands: readonly string[],
+ commands: readonly ValidationCommandInput[],
cwd: string,
timeoutMs = 120_000,
+ options?: ValidationOptions,
): Promise => {
const results: ValidationResult[] = []
- for (const command of commands) {
+ for (const input of commands) {
+ const command = AgentGateway.DeepAgentValidation.normalizeValidationCommand(input)
const started = Date.now()
+ const invocation = validationInvocation(command, cwd, options)
+ if ("kind" in invocation) {
+ results.push(result(command.display, -1, invocation.detail, started, invocation.kind))
+ continue
+ }
+
try {
- const proc = Process.spawn(["sh", "-c", command], {
+ const proc = Process.spawn([...invocation.argv], {
cwd,
stdout: "pipe",
stderr: "pipe",
env: { ...process.env },
})
- const stdout = proc.stdout
- const stderr = proc.stderr
- if (!stdout || !stderr) throw new Error("Validation process output is unavailable")
- // P2-5: race the full read+exit against a timeout sentinel. On timeout we kill the process
- // AND resolve immediately to a failed result, instead of awaiting stdout that may never close
- // after kill (the previous code could hang on `Response(proc.stdout).text()`).
+ if (!proc.stdout || !proc.stderr) {
+ proc.kill()
+ results.push(
+ result(
+ command.display,
+ -1,
+ `Validation process output is unavailable for ${invocation.argv[0]}`,
+ started,
+ "output_unavailable",
+ ),
+ )
+ continue
+ }
+
let timer: ReturnType | undefined
const timeout = new Promise<"timeout">((resolve) => {
timer = setTimeout(() => {
@@ -38,34 +85,72 @@ export const runValidationCommands = async (
resolve("timeout")
}, timeoutMs)
})
- const completed = (async () => {
- const [output, error, exitCode] = await Promise.all([buffer(stdout), buffer(stderr), proc.exited])
- return { stdout: output.toString(), stderr: error.toString(), exitCode } as const
- })()
-
+ const completed = Promise.all([buffer(proc.stdout), buffer(proc.stderr), proc.exited]).then(
+ ([stdout, stderr, exitCode]) => ({
+ stdout: stdout.toString(),
+ stderr: stderr.toString(),
+ exitCode,
+ }),
+ )
const outcome = await Promise.race([completed, timeout])
if (timer) clearTimeout(timer)
if (outcome === "timeout") {
results.push(
- AgentGateway.DeepAgentValidation.parseValidationOutput(
- command,
- 124, // conventional timeout exit code
+ result(
+ command.display,
+ 124,
`validation command timed out after ${timeoutMs}ms`,
- Date.now() - started,
+ started,
+ "timeout",
),
)
continue
}
- const output = `${outcome.stdout}\n${outcome.stderr}`.trim()
results.push(
- AgentGateway.DeepAgentValidation.parseValidationOutput(command, outcome.exitCode, output, Date.now() - started),
+ result(
+ command.display,
+ outcome.exitCode,
+ `${outcome.stdout}\n${outcome.stderr}`.trim(),
+ started,
+ proc.signalCode ? "signal" : "command_exit",
+ ),
)
- } catch (err) {
- // a command that cannot even launch counts as a failed validation (non-zero "exit")
+ } catch (error) {
results.push(
- AgentGateway.DeepAgentValidation.parseValidationOutput(command, 127, String(err), Date.now() - started),
+ result(
+ command.display,
+ -1,
+ `validation process bootstrap failed (${invocation.argv[0]}): ${String(error)}`,
+ started,
+ "shell_bootstrap_failed",
+ ),
)
}
}
return results
}
+
+function validationShell() {
+ const shell = Shell.acceptable()
+ return Shell.posix(shell) ? shell : "/bin/sh"
+}
+
+function unsupportedPlatform(platform: NodeJS.Platform, kernelRelease: string, env: NodeJS.ProcessEnv) {
+ if (platform === "win32")
+ return "Native Windows validation is unsupported. Connect the desktop app to a DeepAgent Code server running in WSL2."
+ if (platform !== "linux") return
+ const version = kernelRelease.toLowerCase()
+ const wsl = Boolean(env.WSL_DISTRO_NAME || env.WSL_INTEROP || version.includes("microsoft"))
+ if (wsl && !version.includes("microsoft-standard") && !version.includes("wsl2"))
+ return "WSL1 validation is unsupported. Upgrade the distribution to WSL2 and reconnect the WSL server."
+}
+
+function result(
+ command: string,
+ exitCode: number,
+ output: string,
+ started: number,
+ kind: ValidationFailureKind,
+) {
+ return AgentGateway.DeepAgentValidation.parseValidationOutput(command, exitCode, output, Date.now() - started, kind)
+}
diff --git a/packages/deepagent-code/src/deepagent/workspace-context.ts b/packages/deepagent-code/src/deepagent/workspace-context.ts
index 168ff530..e3f3ab0e 100644
--- a/packages/deepagent-code/src/deepagent/workspace-context.ts
+++ b/packages/deepagent-code/src/deepagent/workspace-context.ts
@@ -3,9 +3,11 @@ export * as DeepAgentWorkspace from "./workspace-context"
import { readFile, stat } from "node:fs/promises"
import path from "node:path"
import { AgentGateway } from "@deepagent-code/core/agent-gateway"
+import type { ValidationCommand } from "@deepagent-code/core/deepagent/validation"
export type WorkspaceInfo = {
validationCommands: string[]
+ validationPlan: ValidationCommand[]
hasTypeScript: boolean
hasPython: boolean
packageJson: { scripts?: Record } | null
@@ -39,6 +41,7 @@ export async function detect(cwd: string): Promise {
async function detectImpl(cwd: string): Promise {
const info: WorkspaceInfo = {
validationCommands: [],
+ validationPlan: [],
hasTypeScript: false,
hasPython: false,
packageJson: null,
@@ -57,7 +60,8 @@ async function detectImpl(cwd: string): Promise {
info.hasTypeScript = (await exists(path.join(cwd, "tsconfig.json"))) || Boolean(info.packageJson?.scripts?.typecheck)
info.hasPython = await exists(path.join(cwd, "requirements.txt"))
info.agentsMdContent = await readFileSafe(path.join(cwd, "AGENTS.md"))
- info.validationCommands = inferCommands(info)
+ info.validationPlan = inferCommands(info)
+ info.validationCommands = info.validationPlan.map((command) => command.display)
return info
}
@@ -79,11 +83,12 @@ async function exists(filePath: string): Promise {
}
}
-function inferCommands(info: WorkspaceInfo): string[] {
+function inferCommands(info: WorkspaceInfo): ValidationCommand[] {
// P2-7 / P1-3: single source of validation-command inference lives in core's validation.ts
// (includes test/build/python + the AGENTS.md extractor). This bun-based workspace passes the
- // "bun run" runner so emitted commands are runnable via `sh -c` in validation-exec.
- return AgentGateway.DeepAgentValidation.inferValidationCommands({
+ // "bun run" runner so emitted commands use the workspace package manager. The validation
+ // executor runs them through the host's accepted shell (PowerShell/cmd on Windows, POSIX elsewhere).
+ return AgentGateway.DeepAgentValidation.inferValidationPlan({
cwd: "",
packageJson: info.packageJson ?? undefined,
agentsMd: info.agentsMdContent ?? undefined,
diff --git a/packages/deepagent-code/src/effect/runner.ts b/packages/deepagent-code/src/effect/runner.ts
index f21a61c9..363c6eb7 100644
--- a/packages/deepagent-code/src/effect/runner.ts
+++ b/packages/deepagent-code/src/effect/runner.ts
@@ -3,7 +3,7 @@ import { Cause, Deferred, Effect, Exit, Fiber, Latch, Schema, Scope, Synchronize
export interface Runner {
readonly state: State
readonly busy: boolean
- readonly ensureRunning: (work: Effect.Effect) => Effect.Effect
+ readonly ensureRunning: (work: Effect.Effect, onRunning?: Effect.Effect) => Effect.Effect
readonly startShell: (work: Effect.Effect, ready?: Latch.Latch) => Effect.Effect
readonly cancel: Effect.Effect
}
@@ -112,26 +112,28 @@ export const make = (
yield* Fiber.interrupt(shell.fiber)
})
- const ensureRunning = (work: Effect.Effect) =>
+ const ensureRunning = (work: Effect.Effect, onRunning?: Effect.Effect) =>
SynchronizedRef.modifyEffect(
ref,
Effect.fnUntraced(function* (st) {
+ const awaitRunning = (done: Deferred.Deferred) =>
+ onRunning ? onRunning.pipe(Effect.andThen(awaitDone(done))) : awaitDone(done)
switch (st._tag) {
case "Running":
case "ShellThenRun":
- return [awaitDone(st.run.done), st] as const
+ return [awaitRunning(st.run.done), st] as const
case "Shell": {
const run = {
id: next(),
done: yield* Deferred.make(),
work,
} satisfies PendingHandle
- return [awaitDone(run.done), { _tag: "ShellThenRun", shell: st.shell, run }] as const
+ return [awaitRunning(run.done), { _tag: "ShellThenRun", shell: st.shell, run }] as const
}
case "Idle": {
const done = yield* Deferred.make()
const run = yield* startRun(work, done)
- return [awaitDone(done), { _tag: "Running", run }] as const
+ return [awaitRunning(done), { _tag: "Running", run }] as const
}
}
}),
diff --git a/packages/deepagent-code/src/effect/runtime-flags.ts b/packages/deepagent-code/src/effect/runtime-flags.ts
index c37584a2..6805f5bf 100644
--- a/packages/deepagent-code/src/effect/runtime-flags.ts
+++ b/packages/deepagent-code/src/effect/runtime-flags.ts
@@ -54,13 +54,31 @@ export class Service extends ConfigService.Service()("@deepagent-code/R
// by default. NOTE: this is local, non-durable (process restart loses live jobs); cross-restart
// recovery + remote/cloud agents are deferred to V3.4 (S1 §10). Disable with =false.
experimentalBackgroundSubagents: stableOn("DEEPAGENT_CODE_EXPERIMENTAL_BACKGROUND_SUBAGENTS"),
- // Attempt wall limit. A provider/tool that never returns cannot leave the parent blocked forever:
- // expiry cancels the old fiber and starts a bounded takeover from the same fork point. Missing,
- // malformed, zero, and negative values all fail closed to the production default.
+ // Attempt wall limit. Expiry interrupts the same child and preserves partial work for explicit
+ // recovery. It never starts a replacement child or replays provider/tool work automatically.
subagentTimeoutMs: positiveIntegerWithDefault("DEEPAGENT_CODE_SUBAGENT_TIMEOUT_MS", DEFAULT_SUBAGENT_TIMEOUT_MS),
- // v4.0.4 块1: 单个子 Agent 任务被 takeover(超时/崩溃后重生)的最大次数。达上限仍失败则上报主 Agent。
- // 默认 undefined ⇒ 代码内回退到 2。防无限接管。
- subagentTakeoverLimit: positiveInteger("DEEPAGENT_CODE_SUBAGENT_TAKEOVER_LIMIT"),
+ // Subagent control plane rollout gate (L0 design, subagent-control-plane-design.zh-CN.md §13.3).
+ //
+ // "legacy" — keep the current SessionPrompt execution path without automatic takeover.
+ // "shadow" — RESERVED for future use. Legacy lifecycle authority remains; durable coordinator
+ // records non-authoritative comparison artifacts only. Currently routes identically
+ // to "legacy". DO NOT use in production until §4 cutover protocol is implemented.
+ // "durable" — all lifecycle owned by the durable TaskCoordinator (L4+); takeover permanently
+ // removed; SessionPrompt driven through LegacySubagentExecutor.
+ // REQUIRES: L1 migration applied, L3 provisioner wired, start/settle fences complete.
+ //
+ // Unknown values fail closed to "legacy". Once set to "durable" it MUST NOT be rolled back to
+ // re-enable takeover (design §13.4). Mode is per-SQLite/Location — mixing modes across processes
+ // sharing the same database is prohibited (design §4.4).
+ subagentControlPlane: Config.string("DEEPAGENT_CODE_SUBAGENT_CONTROL_PLANE").pipe(
+ Config.withDefault("legacy"),
+ Config.map((value): "legacy" | "shadow" | "durable" => {
+ if (value === "legacy" || value === "shadow" || value === "durable") return value
+ throw new Error(
+ `Invalid DEEPAGENT_CODE_SUBAGENT_CONTROL_PLANE="${value}". Must be one of: legacy, shadow, durable. Refusing to start with unknown mode.`
+ )
+ }),
+ ),
// Parent injection is bounded by default. The complete result remains durable in the child Session
// and the truncated envelope carries the task_read recovery pointer.
subagentOutputMaxChars: positiveIntegerWithDefault(
@@ -68,7 +86,6 @@ export class Service extends ConfigService.Service()("@deepagent-code/R
DEFAULT_SUBAGENT_OUTPUT_MAX_CHARS,
),
subagentResearchStepLimit: positiveInteger("DEEPAGENT_CODE_SUBAGENT_RESEARCH_STEP_LIMIT"),
- subagentResearchTokenLimit: positiveInteger("DEEPAGENT_CODE_SUBAGENT_RESEARCH_TOKEN_LIMIT"),
subagentResearchWallMs: positiveInteger("DEEPAGENT_CODE_SUBAGENT_RESEARCH_WALL_MS"),
subagentNoProgressLimit: positiveInteger("DEEPAGENT_CODE_SUBAGENT_NO_PROGRESS_LIMIT"),
subagentPermissionTimeoutMs: positiveInteger("DEEPAGENT_CODE_SUBAGENT_PERMISSION_TIMEOUT_MS"),
@@ -216,6 +233,9 @@ export class Service extends ConfigService.Service()("@deepagent-code/R
// Process-local HMAC fingerprints, aggregate counts, and existing request/session identifiers only —
// never raw prompt, message, tool, header, metadata, or credential values.
assembledRequestFingerprint: bool("DEEPAGENT_CODE_ASSEMBLED_REQUEST_FINGERPRINT"),
+ // BUG-010 diagnostic gate. Normal receipts persist decoded argument hashes only. Raw provider
+ // chunks are provider-specific and potentially numerous, so inspect them only for an explicit gate.
+ toolArgumentRawReceipt: bool("DEEPAGENT_CODE_TOOL_ARGUMENT_RAW_RECEIPT"),
experimentalWebSockets: bool("DEEPAGENT_CODE_EXPERIMENTAL_WEBSOCKETS"),
// ── V4.0 event-driven Agent-OS — DEFAULT OFF (production-safe, operator opt-in) ──────────────────
// Per §H3 (Feature Flags: all six ship OFF) and §H1 (staged rollout: shadow → low-risk → push
diff --git a/packages/deepagent-code/src/lsp/resolve.ts b/packages/deepagent-code/src/lsp/resolve.ts
index 4df56054..f7d6240b 100644
--- a/packages/deepagent-code/src/lsp/resolve.ts
+++ b/packages/deepagent-code/src/lsp/resolve.ts
@@ -84,14 +84,18 @@ export namespace LSPResolve {
symbol: string
file?: string
kind?: string
+ /** Bounded text-search candidates used to warm cold LSP indexes, never as semantic results. */
+ fallbackFiles?: readonly string[]
}) {
const wantedKind = input.kind ? LABEL_TO_KIND[input.kind] : undefined
const candidates: Candidate[] = []
- if (input.file) {
- // File-scoped: documentSymbol returns a tree (DocumentSymbol) or flat (Symbol) list.
- const uri = fileToUri(input.file)
- const symbols = yield* input.lsp.documentSymbol(uri).pipe(Effect.catch(() => Effect.succeed([])))
+ const collectDocumentCandidates = Effect.fn("LSPResolve.collectDocumentCandidates")(function* (
+ file: string,
+ warm: boolean,
+ ) {
+ if (warm) yield* input.lsp.touchFile(file).pipe(Effect.catch(() => Effect.void))
+ const symbols = yield* input.lsp.documentSymbol(fileToUri(file)).pipe(Effect.catch(() => Effect.succeed([])))
const visit = (items: (LSP.DocumentSymbol | LSP.Symbol)[], file: string) => {
for (const sym of items) {
// DocumentSymbol has selectionRange; Symbol has location.range.
@@ -104,7 +108,12 @@ export namespace LSPResolve {
if (children?.length) visit(children, file)
}
}
- visit(symbols, input.file)
+ visit(symbols, file)
+ })
+
+ if (input.file) {
+ // File-scoped: documentSymbol returns a tree (DocumentSymbol) or flat (Symbol) list.
+ yield* collectDocumentCandidates(input.file, false)
} else {
// Global: workspaceSymbol. Widen the kind filter so resolution isn't blocked by the
// default narrow whitelist; we apply the caller's kind filter ourselves.
@@ -117,6 +126,14 @@ export namespace LSPResolve {
const file = uriToFile(sym.location.uri)
candidates.push(toCandidate(sym.name, sym.kind, file, sym.location.range))
}
+
+ // workspace/symbol is frequently empty before a language server has indexed any files.
+ // Text search only seeds a bounded set of documents; documentSymbol remains the semantic oracle.
+ if (candidates.length === 0) {
+ for (const file of input.fallbackFiles?.slice(0, 20) ?? []) {
+ yield* collectDocumentCandidates(file, true)
+ }
+ }
}
if (candidates.length === 0) return { type: "not_found" } as Result
diff --git a/packages/deepagent-code/src/provider/provider.ts b/packages/deepagent-code/src/provider/provider.ts
index 05e01bd3..50adfca7 100644
--- a/packages/deepagent-code/src/provider/provider.ts
+++ b/packages/deepagent-code/src/provider/provider.ts
@@ -1710,6 +1710,8 @@ export const layer = Layer.effect(
},
options: mergeDeep(existingModel?.options ?? {}, model.options ?? {}),
limit: {
+ // BUG-007: unknown context stays 0 for the wire type (overflow.ts recognises 0 as
+ // "context_limit_unknown" and returns phase:"unavailable" instead of phase:"ok").
context: model.limit?.context ?? existingModel?.limit?.context ?? catalogModel?.limit.context ?? 0,
input: model.limit?.input ?? existingModel?.limit?.input ?? catalogModel?.limit.input,
output: model.limit?.output ?? existingModel?.limit?.output ?? catalogModel?.limit.output ?? 0,
diff --git a/packages/deepagent-code/src/server/routes/instance/httpapi/groups/deepagent.ts b/packages/deepagent-code/src/server/routes/instance/httpapi/groups/deepagent.ts
index b074359e..5bcdd746 100644
--- a/packages/deepagent-code/src/server/routes/instance/httpapi/groups/deepagent.ts
+++ b/packages/deepagent-code/src/server/routes/instance/httpapi/groups/deepagent.ts
@@ -8,6 +8,7 @@ import {
WorkspaceRoutingQueryFields,
} from "../middleware/workspace-routing"
import { described } from "./metadata"
+import { NonNegativeInt } from "@deepagent-code/core/schema"
const root = "/deepagent"
@@ -18,6 +19,52 @@ export class DeepAgentPromotionError extends Schema.ErrorClass(
+ "DeepAgentGoalPlanValidationError",
+)(
+ {
+ message: Schema.String,
+ code: Schema.String,
+ offending_step_ids: Schema.Array(Schema.String),
+ previous_plan_id: Schema.NullOr(Schema.String),
+ previous_plan_version: Schema.NullOr(Schema.Number),
+ },
+ { httpApiStatus: 422 },
+) {}
+
+export class DeepAgentGoalPlanConflictError extends Schema.ErrorClass(
+ "DeepAgentGoalPlanConflictError",
+)(
+ {
+ message: Schema.String,
+ expected_plan_id: Schema.NullOr(Schema.String),
+ expected_version: Schema.NullOr(Schema.Number),
+ actual_plan_id: Schema.NullOr(Schema.String),
+ actual_version: Schema.NullOr(Schema.Number),
+ },
+ { httpApiStatus: 409 },
+) {}
+
+export class DeepAgentGoalPlanBusyError extends Schema.ErrorClass(
+ "DeepAgentGoalPlanBusyError",
+)({ message: Schema.String, activity_id: Schema.String }, { httpApiStatus: 409 }) {}
+
+export class DeepAgentGoalPlanChallengeError extends Schema.ErrorClass(
+ "DeepAgentGoalPlanChallengeError",
+)({ message: Schema.String, reason: Schema.String }, { httpApiStatus: 409 }) {}
+
+export class DeepAgentGoalPlanUnavailableError extends Schema.ErrorClass(
+ "DeepAgentGoalPlanUnavailableError",
+)({ message: Schema.String }, { httpApiStatus: 503 }) {}
+
+export const DeepAgentGoalPlanError = [
+ DeepAgentGoalPlanValidationError,
+ DeepAgentGoalPlanConflictError,
+ DeepAgentGoalPlanBusyError,
+ DeepAgentGoalPlanChallengeError,
+ DeepAgentGoalPlanUnavailableError,
+] as const
+
// V3 reviewer (F4): expose recent run reviews so the reviewer UI is no longer a dead link.
export const DeepAgentCandidateNode = Schema.Struct({
round: Schema.Number,
@@ -330,30 +377,79 @@ export const DeepAgentGoalStartInput = Schema.Struct({
/** Goal lifecycle mutations that only need the session id. */
export const DeepAgentGoalSessionInput = Schema.Struct({ sessionID: Schema.String })
-/**
- * POST /deepagent/goal/edit-plan — V4.1 §S2 GOAL PLAN HOT-EDIT. A user revises the plan of a RUNNING or
- * PAUSED goal; the driver applies it BETWEEN ticks (durable-doc upsert + stall re-baseline). The step
- * shape mirrors plan-controller PlanInput (loose input: step_id/status/acceptance optional; evidence is
- * runtime-owned and never taken from input). `ok:false` when no goal is running or it reached a terminal
- * phase (no orphan edit).
- */
+/** POST /deepagent/goal/edit-plan — strict durable plan-edit admission envelope. */
export const DeepAgentGoalPlanStepInput = Schema.Struct({
step_id: Schema.optional(Schema.String),
title: Schema.String,
- status: Schema.optional(Schema.String),
+ status: Schema.Literals([
+ "pending",
+ "active",
+ "done",
+ "cancelled",
+ "blocked",
+ "completed",
+ "in_progress",
+ "in_review",
+ "skipped",
+ "stuck",
+ ]),
acceptance: Schema.optional(Schema.NullOr(Schema.String)),
assigned_agent: Schema.optional(Schema.NullOr(Schema.String)),
note: Schema.optional(Schema.NullOr(Schema.String)),
})
-export const DeepAgentGoalPlanInput = Schema.Struct({
+export const DeepAgentGoalPlanWriteInput = Schema.Struct({
+ operation: Schema.Literals(["create", "advance", "replan"]),
+ expected_plan_id: Schema.NullOr(Schema.String),
+ expected_version: Schema.NullOr(NonNegativeInt),
goal: Schema.String,
steps: Schema.Array(DeepAgentGoalPlanStepInput),
- assumptions: Schema.optional(Schema.Array(Schema.String)),
- active_step_id: Schema.optional(Schema.NullOr(Schema.String)),
+ assumptions: Schema.Array(Schema.String),
+ active_step_id: Schema.NullOr(Schema.String),
+ replan_reason: Schema.optional(Schema.String),
})
export const DeepAgentGoalEditPlanInput = Schema.Struct({
sessionID: Schema.String,
- plan: DeepAgentGoalPlanInput,
+ request_id: Schema.String,
+ plan_write: DeepAgentGoalPlanWriteInput,
+ quality_challenge_id: Schema.optional(Schema.String),
+})
+
+const DeepAgentGoalPlanChallenge = Schema.Struct({
+ challenge_id: Schema.String,
+ candidate_hash: Schema.String,
+ expected_plan_id: Schema.String,
+ expected_version: Schema.Number,
+ issued_at: Schema.String,
+ expires_at: Schema.String,
+})
+const DeepAgentGoalPlanFailure = Schema.Union([
+ Schema.Struct({
+ kind: Schema.Literal("validation"),
+ code: Schema.String,
+ offending_step_ids: Schema.Array(Schema.String),
+ previous_plan_id: Schema.NullOr(Schema.String),
+ previous_plan_version: Schema.NullOr(Schema.Number),
+ }),
+ Schema.Struct({
+ kind: Schema.Literal("conflict"),
+ expected_plan_id: Schema.NullOr(Schema.String),
+ expected_version: Schema.NullOr(Schema.Number),
+ actual_plan_id: Schema.NullOr(Schema.String),
+ actual_version: Schema.NullOr(Schema.Number),
+ }),
+ Schema.Struct({ kind: Schema.Literal("target_unavailable"), message: Schema.String }),
+ Schema.Struct({ kind: Schema.Literal("runtime_error"), message: Schema.String }),
+])
+export const DeepAgentGoalPlanEditResult = Schema.Struct({
+ state: Schema.Literals(["challenged", "queued", "applied", "rejected", "conflict", "runtime_error"]),
+ activity_id: Schema.String,
+ request_id: Schema.String,
+ candidate_hash: Schema.String,
+ challenge: Schema.optional(DeepAgentGoalPlanChallenge),
+ result: Schema.optional(
+ Schema.Struct({ plan_id: Schema.String, doc_id: Schema.String, version: Schema.Number, changed: Schema.Boolean }),
+ ),
+ failure: Schema.optional(DeepAgentGoalPlanFailure),
})
export const DeepAgentGoalSnapshot = Schema.Struct({
@@ -728,14 +824,14 @@ export const DeepAgentApi = HttpApi.make("deepagent").add(
HttpApiEndpoint.post("goalEditPlan", `${root}/goal/edit-plan`, {
query: WorkspaceRoutingQuery,
payload: DeepAgentGoalEditPlanInput,
- success: described(DeepAgentGoalMutateResult, "Whether the plan edit was enqueued for the goal"),
- error: DeepAgentPromotionError,
+ success: described(DeepAgentGoalPlanEditResult, "The durable plan-edit activity receipt"),
+ error: DeepAgentGoalPlanError,
}).annotateMerge(
OpenApi.annotations({
identifier: "deepagent.goal.editPlan",
summary: "Hot-edit the plan of a running/paused Goal Loop",
description:
- "V4.1 §S2: enqueue a user plan revision on the goal control channel. The driver applies it between ticks (durable-doc upsert + stall re-baseline). ok:false when no goal is running or it reached a terminal phase.",
+ "V4.1 §S2: admit a strict plan-write command into the durable activity mailbox. The driver settles the receipt after CAS and re-baseline.",
}),
),
)
diff --git a/packages/deepagent-code/src/server/routes/instance/httpapi/groups/session.ts b/packages/deepagent-code/src/server/routes/instance/httpapi/groups/session.ts
index 1698e5d1..ff35600c 100644
--- a/packages/deepagent-code/src/server/routes/instance/httpapi/groups/session.ts
+++ b/packages/deepagent-code/src/server/routes/instance/httpapi/groups/session.ts
@@ -20,7 +20,13 @@ import {
WorkspaceRoutingQuery,
WorkspaceRoutingQueryFields,
} from "../middleware/workspace-routing"
-import { ApiNotFoundError, InvalidRequestError, PermissionNotFoundError, SessionBusyError } from "../errors"
+import {
+ ApiNotFoundError,
+ ConflictError,
+ InvalidRequestError,
+ PermissionNotFoundError,
+ SessionBusyError,
+} from "../errors"
import { described } from "./metadata"
import { QueryBoolean } from "./query"
import { ProviderV2 } from "@deepagent-code/core/provider"
@@ -77,6 +83,8 @@ export const PromptPreparePayload = Schema.Struct({
// normalizes internally. Do NOT drop "wish" from this union.
mode: Schema.Literals(["wish", "intelligence"]),
output_language: Schema.optional(Schema.Literals(["chinese", "english"])),
+ intent_id: Schema.optional(Schema.String),
+ intent_source: Schema.optional(Schema.Literals(["composer", "intelligence", "followup", "rewrite"])),
parts: SessionPrompt.PromptInput.fields.parts,
})
export const PromptPrepareResult = Schema.Struct({
@@ -88,6 +96,7 @@ export const PromptPrepareResult = Schema.Struct({
route: Schema.Union([Schema.Literal("code"), Schema.Literal("general")]),
goal: Schema.String,
preview: Schema.String,
+ intent_id: Schema.optional(Schema.String),
})
// A3 macro-round: the latest persisted next-round suggestion for human approval. `null` body when
// no suggestion exists yet.
@@ -95,6 +104,30 @@ export const PromptSuggestionResult = Schema.Struct({
status: Schema.NullOr(Schema.String),
body: Schema.NullOr(Schema.String),
})
+const PlanSnapshotStep = Schema.Struct({
+ step_id: Schema.String,
+ title: Schema.String,
+ status: Schema.String,
+ acceptance: Schema.NullOr(Schema.String),
+ assigned_agent: Schema.NullOr(Schema.String),
+ evidence: Schema.Array(Schema.String),
+ note: Schema.NullOr(Schema.String),
+})
+const PlanSnapshot = Schema.Struct({
+ plan_id: Schema.String,
+ session_id: Schema.String,
+ goal: Schema.String,
+ assumptions: Schema.Array(Schema.String),
+ steps: Schema.Array(PlanSnapshotStep),
+ active_step_id: Schema.NullOr(Schema.String),
+ replan_reason: Schema.optional(Schema.NullOr(Schema.String)),
+ created_at: Schema.String,
+})
+export const PlanSnapshotResult = Schema.Struct({
+ plan: Schema.NullOr(PlanSnapshot),
+ doc_id: Schema.NullOr(Schema.String),
+ plan_version: Schema.NullOr(Schema.Number),
+})
export const CommandPayload = Schema.Struct(Struct.omit(SessionPrompt.CommandInput.fields, ["sessionID"]))
export const ShellPayload = Schema.Struct(Struct.omit(SessionPrompt.ShellInput.fields, ["sessionID"]))
export const RevertPayload = Schema.Struct(Struct.omit(SessionRevert.RevertInput.fields, ["sessionID"]))
@@ -239,6 +272,7 @@ export const SessionPaths = {
get: `${root}/:sessionID`,
children: `${root}/:sessionID/children`,
todo: `${root}/:sessionID/todo`,
+ plan: `${root}/:sessionID/plan`,
diff: `${root}/:sessionID/diff`,
messages: `${root}/:sessionID/message`,
message: `${root}/:sessionID/message/:messageID`,
@@ -328,6 +362,18 @@ export const SessionApi = HttpApi.make("session")
description: "Retrieve the todo list associated with a specific session, showing tasks and action items.",
}),
),
+ HttpApiEndpoint.get("plan", SessionPaths.plan, {
+ params: { sessionID: SessionID },
+ query: WorkspaceRoutingQuery,
+ success: described(PlanSnapshotResult, "Current durable session plan"),
+ error: [HttpApiError.BadRequest, ApiNotFoundError],
+ }).annotateMerge(
+ OpenApi.annotations({
+ identifier: "session.plan",
+ summary: "Get session plan",
+ description: "Retrieve the versioned durable plan snapshot for a session.",
+ }),
+ ),
HttpApiEndpoint.get("diff", SessionPaths.diff, {
params: { sessionID: SessionID },
query: DiffQuery,
@@ -482,7 +528,7 @@ export const SessionApi = HttpApi.make("session")
query: WorkspaceRoutingQuery,
payload: PromptPayload,
success: described(SessionV1.WithParts, "Created message"),
- error: [HttpApiError.BadRequest, ApiNotFoundError],
+ error: [HttpApiError.BadRequest, ConflictError, ApiNotFoundError],
}).annotateMerge(
OpenApi.annotations({
identifier: "session.prompt",
@@ -495,7 +541,7 @@ export const SessionApi = HttpApi.make("session")
query: WorkspaceRoutingQuery,
payload: PromptPreparePayload,
success: described(PromptPrepareResult, "Prepared prompt draft"),
- error: [HttpApiError.BadRequest, InvalidRequestError, ApiNotFoundError],
+ error: [HttpApiError.BadRequest, ConflictError, InvalidRequestError, ApiNotFoundError],
}).annotateMerge(
OpenApi.annotations({
identifier: "session.prompt_prepare",
@@ -508,7 +554,7 @@ export const SessionApi = HttpApi.make("session")
query: WorkspaceRoutingQuery,
payload: PromptPreparePayload,
success: Schema.String,
- error: [HttpApiError.BadRequest, InvalidRequestError, ApiNotFoundError],
+ error: [HttpApiError.BadRequest, ConflictError, InvalidRequestError, ApiNotFoundError],
}).annotateMerge(
OpenApi.annotations({
identifier: "session.prompt_prepare_stream",
@@ -535,13 +581,13 @@ export const SessionApi = HttpApi.make("session")
query: WorkspaceRoutingQuery,
payload: PromptPayload,
success: described(HttpApiSchema.NoContent, "Prompt accepted"),
- error: [HttpApiError.BadRequest, ApiNotFoundError],
+ error: [HttpApiError.BadRequest, ConflictError, ApiNotFoundError],
}).annotateMerge(
OpenApi.annotations({
identifier: "session.prompt_async",
summary: "Send async message",
description:
- "Create and send a new message to a session asynchronously, starting the session if needed and returning immediately.",
+ "Durably admit a new message or steer, start session execution if needed, and return without waiting for model completion.",
}),
),
HttpApiEndpoint.post("command", SessionPaths.command, {
diff --git a/packages/deepagent-code/src/server/routes/instance/httpapi/handlers/deepagent.ts b/packages/deepagent-code/src/server/routes/instance/httpapi/handlers/deepagent.ts
index caebfe05..119f84a1 100644
--- a/packages/deepagent-code/src/server/routes/instance/httpapi/handlers/deepagent.ts
+++ b/packages/deepagent-code/src/server/routes/instance/httpapi/handlers/deepagent.ts
@@ -9,7 +9,14 @@ import { Effect } from "effect"
import { buildRunReview, listRunIds } from "@/deepagent/run-review"
import { AgentGateway } from "@deepagent-code/core/agent-gateway"
import { InstanceHttpApi } from "../api"
-import { DeepAgentPromotionError } from "../groups/deepagent"
+import {
+ DeepAgentGoalPlanBusyError,
+ DeepAgentGoalPlanChallengeError,
+ DeepAgentGoalPlanConflictError,
+ DeepAgentGoalPlanUnavailableError,
+ DeepAgentGoalPlanValidationError,
+ DeepAgentPromotionError,
+} from "../groups/deepagent"
import { WorkspaceRouteContext } from "../middleware/workspace-routing"
import { RuntimeFlags } from "@/effect/runtime-flags"
import { SettingsStore } from "@/settings/store"
@@ -26,7 +33,70 @@ import { WIKI_EDITABLE_TYPES, type WikiPage } from "@/wiki/wiki-service"
import type { PanelTurnRunner } from "@/panel/panelist-runner"
import type { PanelVerdict } from "@/agent/schema/panel"
import type { CompletionCriterion } from "@deepagent-code/core/deepagent/goal-loop"
-import type { PlanInput } from "@deepagent-code/core/deepagent/plan-controller"
+import { PlanConflictError, PlanValidationError } from "@deepagent-code/core/deepagent/plan-controller"
+import {
+ PlanEditBusyError,
+ PlanEditChallengeError,
+ PlanEditMailboxConflictError,
+ PlanEditProtocolCorruptionError,
+ PlanEditRequestConflictError,
+ PlanEditTargetUnavailableError,
+ type PlanEditReceipt,
+} from "@deepagent-code/core/deepagent/plan-edit-protocol"
+
+export const mapGoalPlanError = (error: GoalManager.GoalPlanEditAdmissionError) => {
+ if (error instanceof PlanValidationError) {
+ return new DeepAgentGoalPlanValidationError({
+ message: error.message,
+ code: error.code,
+ offending_step_ids: [...error.offending_step_ids],
+ previous_plan_id: error.previous_plan_id,
+ previous_plan_version: error.previous_plan_version,
+ })
+ }
+ if (error instanceof PlanConflictError) {
+ return new DeepAgentGoalPlanConflictError({
+ message: error.message,
+ expected_plan_id: error.expected?.plan_id ?? null,
+ expected_version: error.expected?.version ?? null,
+ actual_plan_id: error.actual?.plan_id ?? null,
+ actual_version: error.actual?.version ?? null,
+ })
+ }
+ if (error instanceof PlanEditBusyError) {
+ return new DeepAgentGoalPlanBusyError({ message: error.message, activity_id: error.activity_id })
+ }
+ if (error instanceof PlanEditChallengeError) {
+ return new DeepAgentGoalPlanChallengeError({ message: error.message, reason: error.reason })
+ }
+ if (error instanceof PlanEditRequestConflictError || error instanceof PlanEditMailboxConflictError) {
+ return new DeepAgentGoalPlanConflictError({
+ message: error.message,
+ expected_plan_id: null,
+ expected_version: null,
+ actual_plan_id: null,
+ actual_version: null,
+ })
+ }
+ if (
+ error instanceof PlanEditTargetUnavailableError ||
+ error instanceof PlanEditProtocolCorruptionError ||
+ error instanceof GoalManager.GoalPlanEditUnavailableError
+ ) {
+ return new DeepAgentGoalPlanUnavailableError({ message: error.message })
+ }
+ return new DeepAgentGoalPlanUnavailableError({ message: "unknown plan edit failure" })
+}
+
+const projectPlanReceipt = (receipt: PlanEditReceipt) => ({
+ state: receipt.state,
+ activity_id: receipt.command.activity_id,
+ request_id: receipt.command.request_id,
+ candidate_hash: receipt.command.candidate_hash,
+ ...(receipt.challenge ? { challenge: receipt.challenge } : {}),
+ ...(receipt.result ? { result: receipt.result } : {}),
+ ...(receipt.failure ? { failure: receipt.failure } : {}),
+})
const dbgLog = Log.create({ service: "deepagent.packs.debug" })
@@ -598,27 +668,32 @@ export const deepagentHandlers = HttpApiBuilder.group(InstanceHttpApi, "deepagen
if (!flags.experimentalGoalLoop) return { ok: false }
return { ok: yield* goals.stop(ctx.payload.sessionID) }
})
- // V4.1 §S2 — hot-edit the plan of a running/paused goal. Normalize the wire payload (readonly step
- // structs → the loose PlanInput the backend reconciles via buildPlanFromInput, preserving ids +
- // runtime-owned evidence). GoalManager.editPlan enqueues it on the control channel (ok:false when no
- // goal is running or the goal is terminal); the driver applies it between ticks.
const goalEditPlan = Effect.fn("DeepAgentHttpApi.goalEditPlan")(function* (ctx) {
- if (!flags.experimentalGoalLoop) return { ok: false }
- const p = ctx.payload.plan
- const plan: PlanInput = {
- goal: p.goal,
- steps: p.steps.map((s: (typeof p.steps)[number]) => ({
- ...(s.step_id != null ? { step_id: s.step_id } : {}),
- title: s.title,
- ...(s.status != null ? { status: s.status } : {}),
- ...(s.acceptance !== undefined ? { acceptance: s.acceptance } : {}),
- ...(s.assigned_agent !== undefined ? { assigned_agent: s.assigned_agent } : {}),
- ...(s.note !== undefined ? { note: s.note } : {}),
- })),
- ...(p.assumptions ? { assumptions: [...p.assumptions] } : {}),
- ...(p.active_step_id !== undefined ? { active_step_id: p.active_step_id } : {}),
+ if (!flags.experimentalGoalLoop) {
+ return yield* Effect.fail(new DeepAgentGoalPlanUnavailableError({ message: "goal loop is disabled" }))
}
- return { ok: yield* goals.editPlan({ sessionID: ctx.payload.sessionID, plan }) }
+ const receipt = yield* goals
+ .editPlan({
+ sessionID: ctx.payload.sessionID,
+ requestID: ctx.payload.request_id,
+ planWrite: {
+ operation: ctx.payload.plan_write.operation,
+ expected_plan_id: ctx.payload.plan_write.expected_plan_id,
+ expected_version: ctx.payload.plan_write.expected_version,
+ goal: ctx.payload.plan_write.goal,
+ assumptions: ctx.payload.plan_write.assumptions,
+ steps: ctx.payload.plan_write.steps,
+ active_step_id: ctx.payload.plan_write.active_step_id,
+ ...(ctx.payload.plan_write.replan_reason !== undefined
+ ? { replan_reason: ctx.payload.plan_write.replan_reason }
+ : {}),
+ },
+ ...(ctx.payload.quality_challenge_id !== undefined
+ ? { qualityChallengeID: ctx.payload.quality_challenge_id }
+ : {}),
+ })
+ .pipe(Effect.mapError(mapGoalPlanError))
+ return projectPlanReceipt(receipt)
})
const goalStatus = Effect.fn("DeepAgentHttpApi.goalStatus")(function* (ctx) {
return { goal: yield* goals.status(ctx.query.sessionID) }
diff --git a/packages/deepagent-code/src/server/routes/instance/httpapi/handlers/session.ts b/packages/deepagent-code/src/server/routes/instance/httpapi/handlers/session.ts
index 320b3e03..9ff25965 100644
--- a/packages/deepagent-code/src/server/routes/instance/httpapi/handlers/session.ts
+++ b/packages/deepagent-code/src/server/routes/instance/httpapi/handlers/session.ts
@@ -1,5 +1,7 @@
import { PermissionV1 } from "@deepagent-code/core/v1/permission"
+import { Database } from "@deepagent-code/core/database/database"
import { Agent } from "@/agent/agent"
+import { AgentGateway } from "@deepagent-code/core/agent-gateway"
import { SessionV1 } from "@deepagent-code/core/v1/session"
import { EventV2Bridge } from "@/event-v2-bridge"
import { ContextFederationDiagnostics } from "@/context-federation/diagnostics"
@@ -10,6 +12,8 @@ import { Session } from "@/session/session"
import { SessionCompaction } from "@/session/compaction"
import { MessageV2 } from "@/session/message-v2"
import { SessionPrompt } from "@/session/prompt"
+import { SessionPromptIntent } from "@/session/prompt-intent"
+import { SessionMutationEpoch } from "@/session/mutation-epoch"
import { SessionRevert } from "@/session/revert"
import { SessionRunState } from "@/session/run-state"
import { SessionStatus } from "@/session/status"
@@ -39,7 +43,7 @@ import {
SummarizePayload,
UpdatePayload,
} from "../groups/session"
-import { PermissionNotFoundError } from "../errors"
+import { ConflictError, PermissionNotFoundError } from "../errors"
import * as SessionError from "./session-errors"
const tryParseJson = (text: string) =>
@@ -68,6 +72,7 @@ export const sessionHandlers = HttpApiBuilder.group(InstanceHttpApi, "session",
const session = yield* Session.Service
const shareSvc = yield* SessionShare.Service
const promptSvc = yield* SessionPrompt.Service
+ const database = yield* Database.Service
const revertSvc = yield* SessionRevert.Service
const compactSvc = yield* SessionCompaction.Service
const runState = yield* SessionRunState.Service
@@ -114,6 +119,28 @@ export const sessionHandlers = HttpApiBuilder.group(InstanceHttpApi, "session",
return yield* todoSvc.get(ctx.params.sessionID)
})
+ const plan = Effect.fn("SessionHttpApi.plan")(function* (ctx: { params: { sessionID: SessionID } }) {
+ yield* requireSession(ctx.params.sessionID)
+ const current = AgentGateway.DeepAgentPlanStore.getPlanDoc(ctx.params.sessionID)
+ const ref = AgentGateway.DeepAgentPlanStore.planDocRef(ctx.params.sessionID)
+ return {
+ plan: current
+ ? {
+ ...current,
+ steps: current.steps.map((step) => ({
+ ...step,
+ acceptance: step.acceptance ?? null,
+ assigned_agent: step.assigned_agent ?? null,
+ evidence: [...(step.evidence ?? [])],
+ note: step.note ?? null,
+ })),
+ }
+ : null,
+ doc_id: ref?.id ?? null,
+ plan_version: ref?.version ?? null,
+ }
+ })
+
const diff = Effect.fn("SessionHttpApi.diff")(function* (ctx: {
params: { sessionID: SessionID }
query: typeof DiffQuery.Type
@@ -328,7 +355,23 @@ export const sessionHandlers = HttpApiBuilder.group(InstanceHttpApi, "session",
...ctx.payload,
sessionID: ctx.params.sessionID,
})
- .pipe(Effect.mapError(() => new HttpApiError.BadRequest({})))
+ .pipe(
+ Effect.mapError((error) =>
+ error instanceof SessionMutationEpoch.Stale
+ ? new ConflictError({
+ message: "prompt intent was superseded by a session revert",
+ resource: `session:${error.sessionID}`,
+ })
+ : error instanceof SessionPromptIntent.Conflict
+ ? new ConflictError({ message: error.reason, resource: `session_intent:${error.intentID}` })
+ : error instanceof SessionPromptIntent.InProgress
+ ? new ConflictError({
+ message: "prompt intent admission is already in progress",
+ resource: `session_intent:${error.intentID}`,
+ })
+ : new HttpApiError.BadRequest({}),
+ ),
+ )
const body =
result.kind === "turn"
? JSON.stringify(result.message)
@@ -345,7 +388,24 @@ export const sessionHandlers = HttpApiBuilder.group(InstanceHttpApi, "session",
yield* requireSession(input.ctx.params.sessionID)
const rawInput = promptText(input.ctx.payload.parts)
if (!rawInput.trim()) return yield* new HttpApiError.BadRequest({})
- return yield* promptSvc
+ if (input.ctx.payload.intent_id) {
+ yield* SessionPromptIntent.prepare({
+ intentID: input.ctx.payload.intent_id,
+ sessionID: input.ctx.params.sessionID,
+ source: input.ctx.payload.intent_source ?? "intelligence",
+ }).pipe(
+ Effect.provideService(Database.Service, database),
+ Effect.mapError((error) =>
+ error instanceof SessionMutationEpoch.Stale
+ ? new ConflictError({
+ message: "prompt intent was superseded by a session revert",
+ resource: `session:${error.sessionID}`,
+ })
+ : new ConflictError({ message: error.reason, resource: `session_intent:${error.intentID}` }),
+ ),
+ )
+ }
+ const result = yield* promptSvc
.refineIntelligenceDraft({
sessionID: input.ctx.params.sessionID,
rawInput,
@@ -380,6 +440,10 @@ export const sessionHandlers = HttpApiBuilder.group(InstanceHttpApi, "session",
),
),
)
+ return {
+ ...result,
+ ...(input.ctx.payload.intent_id ? { intent_id: input.ctx.payload.intent_id } : {}),
+ }
})
const promptPrepare = Effect.fn("SessionHttpApi.promptPrepare")(function* (ctx: {
@@ -436,24 +500,24 @@ export const sessionHandlers = HttpApiBuilder.group(InstanceHttpApi, "session",
payload: typeof PromptPayload.Type
}) {
yield* requireSession(ctx.params.sessionID)
- // V4.1 §S1.2: mirror the synchronous `prompt` handler — route through promptOrSteer so a message
- // sent while the session is mid-turn is admitted as a steer (absorbed at the next model-request
- // boundary) instead of queuing as a new turn that starts only after the current one finishes.
- // The turn result / steer ack is ignored here (we return 204 regardless); errors are published
- // as session error events just like the old prompt() path.
- yield* promptSvc.promptOrSteer({ ...ctx.payload, sessionID: ctx.params.sessionID }).pipe(
- Effect.catchCause((cause) =>
- Effect.gen(function* () {
- yield* Effect.logError("prompt_async failed").pipe(
- Effect.annotateLogs({ sessionID: ctx.params.sessionID, cause }),
- )
- yield* events.publish(Session.Event.Error, {
- sessionID: ctx.params.sessionID,
- error: new NamedError.Unknown({ message: Cause.pretty(cause) }).toObject(),
- })
- }),
+ // Return only after the input has crossed its durable admission boundary. Model execution stays
+ // asynchronous, but callers may safely serialize destructive actions after this acknowledgement.
+ yield* promptSvc.promptAsync({ ...ctx.payload, sessionID: ctx.params.sessionID }).pipe(
+ Effect.mapError((error) =>
+ error instanceof SessionPromptIntent.Conflict
+ ? new ConflictError({ message: error.reason, resource: `session_intent:${error.intentID}` })
+ : error instanceof SessionPromptIntent.InProgress
+ ? new ConflictError({
+ message: "prompt intent admission is already in progress",
+ resource: `session_intent:${error.intentID}`,
+ })
+ : error instanceof SessionMutationEpoch.Stale
+ ? new ConflictError({
+ message: "prompt intent was superseded by a session revert",
+ resource: `session:${error.sessionID}`,
+ })
+ : new HttpApiError.BadRequest({}),
),
- Effect.forkIn(scope, { startImmediately: true }),
)
return HttpApiSchema.NoContent.make()
})
@@ -587,6 +651,7 @@ export const sessionHandlers = HttpApiBuilder.group(InstanceHttpApi, "session",
.handle("get", get)
.handle("children", children)
.handle("todo", todo)
+ .handle("plan", plan)
.handle("diff", diff)
.handle("messages", messages)
.handle("message", message)
diff --git a/packages/deepagent-code/src/session/branch-provisioner.ts b/packages/deepagent-code/src/session/branch-provisioner.ts
new file mode 100644
index 00000000..ceecf876
--- /dev/null
+++ b/packages/deepagent-code/src/session/branch-provisioner.ts
@@ -0,0 +1,415 @@
+/**
+ * SessionBranchProvisioner — durable session target-branch provisioning.
+ *
+ * Design: subagent-control-plane-design.zh-CN.md §3.2.1
+ *
+ * Wraps the existing ensureSessionBranch helper from pr-collaboration.ts with:
+ * - durable receipt written to task_run.workspace_branch_state
+ * - cross-process lock via EffectFlock on the repository root
+ * - crash recovery: if branch_state="admitting" on restart, query Git and adopt or conflict
+ *
+ * Invariants (design §1.3):
+ * #31 automatic writer session target branch must be durable provisioned
+ * #34 workspace_target_branch != worktree_branch (enforced by callers)
+ * #36 single legacy executor per SQLite/Location (EffectFlock guards provisioning)
+ */
+
+import { Data, Effect } from "effect"
+import { Database } from "@deepagent-code/core/database/database"
+import { TaskRunEventTable, TaskRunTable } from "@deepagent-code/core/session/sql"
+import { EffectFlock } from "@deepagent-code/core/util/effect-flock"
+import { and, eq } from "drizzle-orm"
+import { Git } from "@/git"
+import { Identifier } from "@/id/id"
+
+// ---------------------------------------------------------------------------
+// Errors
+// ---------------------------------------------------------------------------
+
+export class SessionBranchConflict extends Data.TaggedError("SessionBranchProvisioner.Conflict")<{
+ readonly runID: string
+ readonly desiredBranch: string
+ readonly reason: string
+}> {}
+
+export class SessionBranchUnavailable extends Data.TaggedError("SessionBranchProvisioner.Unavailable")<{
+ readonly runID: string
+ readonly reason: string
+}> {}
+
+// ---------------------------------------------------------------------------
+// Core: ensureExact
+// Design §3.2.1
+// ---------------------------------------------------------------------------
+
+export type BranchProvisionResult = {
+ readonly targetBranch: string
+ readonly baseCommit: string
+}
+
+/**
+ * Provision the session target branch for an automatic writer run, durably.
+ *
+ * Flow:
+ * 1. If workspace_branch_state = "ready" with matching branch/base → adopt
+ * 2. CAS workspace_branch_state = "admitting" + record desired target/base
+ * 3. Under EffectFlock(repositoryRoot): verify clean + attached + HEAD == base_commit
+ * 4. Query or create refs/heads/
+ * 5. CAS workspace_branch_state = "ready"
+ *
+ * Crash recovery: if state = "admitting" on restart, query Git state and:
+ * - branch exists and HEAD == base_commit → adopt (state=ready)
+ * - branch exists but HEAD differs → provisioning_conflict
+ * - branch absent → safe to re-attempt (re-run from step 3)
+ */
+export function ensureExact(input: {
+ readonly runID: string
+ readonly runVersion: number
+ readonly parentSessionID: string
+ readonly repositoryRoot: string
+ readonly baseCommit: string
+ readonly parentDirectory: string
+ readonly now?: number
+}) {
+ return Effect.gen(function* () {
+ const { db } = yield* Database.Service
+ const flock = yield* EffectFlock.Service
+ const git = yield* Git.Service
+ const now = input.now ?? Date.now()
+ const desiredBranch = `deepagent-code/session-${input.parentSessionID}`
+
+ // Step 1: check if already provisioned
+ const existingRun = yield* db
+ .select({
+ version: TaskRunTable.version,
+ branchState: TaskRunTable.workspace_branch_state,
+ targetBranch: TaskRunTable.workspace_target_branch,
+ baseCommit: TaskRunTable.workspace_base_commit,
+ })
+ .from(TaskRunTable)
+ .where(eq(TaskRunTable.run_id, input.runID))
+ .get()
+ .pipe(Effect.orDie)
+
+ if (!existingRun) return yield* Effect.die(new Error(`ensureExact: run ${input.runID} not found`))
+ if (existingRun.version !== input.runVersion) {
+ return yield* Effect.die(
+ new Error(
+ `ensureExact: run version changed before branch provisioning (expected ${input.runVersion}, got ${existingRun.version})`,
+ ),
+ )
+ }
+
+ if (existingRun.branchState === "ready" && existingRun.targetBranch && existingRun.baseCommit) {
+ // Already provisioned — verify it still matches what we expect
+ if (existingRun.targetBranch !== desiredBranch || existingRun.baseCommit !== input.baseCommit) {
+ return yield* Effect.fail(
+ new SessionBranchConflict({
+ runID: input.runID,
+ desiredBranch,
+ reason: `existing receipt has branch=${existingRun.targetBranch}, base=${existingRun.baseCommit}`,
+ }),
+ )
+ }
+ const adopted = yield* flock.withLock(
+ Effect.gen(function* () {
+ const branch = yield* git.branch(input.parentDirectory)
+ const head = yield* git.resolveRef(input.parentDirectory)
+ if (branch !== desiredBranch || head !== input.baseCommit) {
+ return yield* Effect.fail(
+ new SessionBranchConflict({
+ runID: input.runID,
+ desiredBranch,
+ reason: `ready receipt no longer matches Git branch/head (${branch ?? "detached"}/${head ?? "missing"})`,
+ }),
+ )
+ }
+ return { targetBranch: desiredBranch, baseCommit: input.baseCommit } satisfies BranchProvisionResult
+ }),
+ `task-workspace:${input.repositoryRoot}`,
+ )
+ return adopted
+ }
+
+ if (existingRun.branchState === "conflict") {
+ return yield* Effect.fail(
+ new SessionBranchConflict({
+ runID: input.runID,
+ desiredBranch,
+ reason: "workspace_branch_state is already 'conflict'",
+ }),
+ )
+ }
+
+ // Step 2: CAS to "admitting" if not already in that state
+ if (existingRun.branchState !== "admitting") {
+ yield* db.transaction(
+ (tx) =>
+ Effect.gen(function* () {
+ const casResult = yield* tx
+ .update(TaskRunTable)
+ .set({
+ workspace_branch_state: "admitting",
+ workspace_branch_started_at: now,
+ workspace_target_branch: desiredBranch,
+ workspace_base_commit: input.baseCommit,
+ version: existingRun.version + 1,
+ time_updated: now,
+ })
+ .where(
+ and(
+ eq(TaskRunTable.run_id, input.runID),
+ eq(TaskRunTable.version, existingRun.version),
+ eq(TaskRunTable.workspace_branch_state, existingRun.branchState ?? "none"),
+ ),
+ )
+ .returning({ version: TaskRunTable.version })
+ .get()
+ .pipe(Effect.orDie)
+ if (!casResult) {
+ return yield* Effect.die(
+ new Error(`ensureExact: CAS to admitting lost for run ${input.runID} — concurrent provisioner`),
+ )
+ }
+ yield* tx
+ .insert(TaskRunEventTable)
+ .values({
+ event_id: Identifier.ascending("event"),
+ run_id: input.runID,
+ version: casResult.version,
+ type: "session_branch_started",
+ from_state: "admitted",
+ to_state: "admitted",
+ reason: desiredBranch,
+ time_created: now,
+ })
+ .run()
+ .pipe(Effect.orDie)
+ }),
+ { behavior: "immediate" },
+ )
+ }
+
+ // Step 3+4: under cross-process lock, perform Git operations and CAS to "ready"
+ const gitBody = Effect.gen(function* () {
+ // Re-read current branch and status under lock
+ const currentBranch = yield* git.branch(input.parentDirectory)
+ if (!currentBranch) {
+ return yield* Effect.fail(
+ new SessionBranchUnavailable({
+ runID: input.runID,
+ reason: "parent checkout has detached HEAD; cannot create session branch",
+ }),
+ )
+ }
+
+ // If already on a non-protected branch that matches desired, adopt it
+ const defaultBranchInfo = yield* git.defaultBranch(input.parentDirectory)
+ const protectedBranches = new Set(["main", "master", "dev", defaultBranchInfo?.name].filter(Boolean))
+
+ if (!protectedBranches.has(currentBranch)) {
+ if (currentBranch !== desiredBranch) {
+ return yield* Effect.fail(
+ new SessionBranchConflict({
+ runID: input.runID,
+ desiredBranch,
+ reason: `parent is on non-protected branch '${currentBranch}' which is not the desired '${desiredBranch}'`,
+ }),
+ )
+ }
+ // Already on the desired branch — verify HEAD matches base_commit
+ const headResult = yield* git.run(["rev-parse", "HEAD"], { cwd: input.parentDirectory })
+ const head = headResult.text().trim()
+ if (head !== input.baseCommit) {
+ return yield* Effect.fail(
+ new SessionBranchConflict({
+ runID: input.runID,
+ desiredBranch,
+ reason: `HEAD ${head} does not match expected base_commit ${input.baseCommit}`,
+ }),
+ )
+ }
+ return { targetBranch: desiredBranch, baseCommit: input.baseCommit } satisfies BranchProvisionResult
+ }
+
+ // Parent is on a protected branch — must create/switch to desired branch
+ // Verify clean status first (design §3.2, workspace preflight should already have done this)
+ const gitStatus = yield* git.status(input.parentDirectory)
+ const isDirty = gitStatus.length > 0
+ if (isDirty) {
+ const paths = gitStatus.map((s) => s.file).join(", ")
+ return yield* Effect.fail(
+ new SessionBranchUnavailable({
+ runID: input.runID,
+ reason: `parent checkout is dirty; cannot create session branch (paths: ${paths})`,
+ }),
+ )
+ }
+
+ // Check if the desired branch already exists
+ const showRefResult = yield* git
+ .run(["show-ref", "--verify", "--quiet", `refs/heads/${desiredBranch}`], {
+ cwd: input.parentDirectory,
+ })
+ .pipe(Effect.orElseSucceed(() => ({ exitCode: 1, text: () => "", truncated: false }) as const))
+
+ if (showRefResult.exitCode === 0) {
+ // Branch exists — verify it points to base_commit
+ const refHashResult = yield* git.run(["rev-parse", `refs/heads/${desiredBranch}`], {
+ cwd: input.parentDirectory,
+ })
+ const refHash = refHashResult.text().trim()
+ if (refHash !== input.baseCommit) {
+ return yield* Effect.fail(
+ new SessionBranchConflict({
+ runID: input.runID,
+ desiredBranch,
+ reason: `branch ${desiredBranch} already exists but points to ${refHash} not ${input.baseCommit}`,
+ }),
+ )
+ }
+ // Switch to existing branch
+ const switched = yield* git.run(["switch", desiredBranch], { cwd: input.parentDirectory })
+ if (switched.exitCode !== 0) {
+ return yield* Effect.fail(
+ new SessionBranchUnavailable({
+ runID: input.runID,
+ reason: `git switch ${desiredBranch} failed: ${switched.text().trim()}`,
+ }),
+ )
+ }
+ } else {
+ // Create new branch at base_commit
+ const created = yield* git.run(["switch", "-c", desiredBranch, input.baseCommit], {
+ cwd: input.parentDirectory,
+ })
+ if (created.exitCode !== 0) {
+ return yield* Effect.fail(
+ new SessionBranchUnavailable({
+ runID: input.runID,
+ reason: `git switch -c ${desiredBranch} ${input.baseCommit} failed: ${created.text().trim()}`,
+ }),
+ )
+ }
+ }
+
+ return { targetBranch: desiredBranch, baseCommit: input.baseCommit } satisfies BranchProvisionResult
+ })
+ const result = yield* flock.withLock(gitBody, `task-workspace:${input.repositoryRoot}`)
+
+ // Step 5: CAS workspace_branch_state to "ready" (or "conflict" on failure)
+ yield* db.transaction(
+ (tx) =>
+ Effect.gen(function* () {
+ const current = yield* tx
+ .select({ version: TaskRunTable.version })
+ .from(TaskRunTable)
+ .where(eq(TaskRunTable.run_id, input.runID))
+ .get()
+ .pipe(Effect.orDie)
+ if (!current) return yield* Effect.die(new Error(`ensureExact: run ${input.runID} disappeared`))
+ const updated = yield* tx
+ .update(TaskRunTable)
+ .set({
+ workspace_branch_state: "ready",
+ workspace_target_branch: result.targetBranch,
+ workspace_base_commit: result.baseCommit,
+ version: current.version + 1,
+ time_updated: now,
+ })
+ .where(
+ and(
+ eq(TaskRunTable.run_id, input.runID),
+ eq(TaskRunTable.version, current.version),
+ eq(TaskRunTable.workspace_branch_state, "admitting"),
+ ),
+ )
+ .returning({ version: TaskRunTable.version })
+ .get()
+ .pipe(Effect.orDie)
+ if (!updated) return yield* Effect.die(new Error(`ensureExact: ready receipt lost for ${input.runID}`))
+ yield* tx
+ .insert(TaskRunEventTable)
+ .values({
+ event_id: Identifier.ascending("event"),
+ run_id: input.runID,
+ version: updated.version,
+ type: "session_branch_ready",
+ from_state: "admitted",
+ to_state: "admitted",
+ reason: result.targetBranch,
+ time_created: now,
+ })
+ .run()
+ .pipe(Effect.orDie)
+ }),
+ { behavior: "immediate" },
+ )
+
+ return result
+ }).pipe(
+ // On any typed error, persist "conflict" state before propagating
+ Effect.tapError((err) => {
+ if (err instanceof SessionBranchConflict || err instanceof SessionBranchUnavailable) {
+ return markConflict({ runID: input.runID, reason: err.reason, now: input.now ?? Date.now() }).pipe(
+ Effect.ignore,
+ )
+ }
+ return Effect.void
+ }),
+ )
+}
+
+function markConflict(input: { readonly runID: string; readonly reason: string; readonly now: number }) {
+ return Effect.gen(function* () {
+ const { db } = yield* Database.Service
+ return yield* db.transaction(
+ (tx) =>
+ Effect.gen(function* () {
+ const current = yield* tx
+ .select({ version: TaskRunTable.version })
+ .from(TaskRunTable)
+ .where(eq(TaskRunTable.run_id, input.runID))
+ .get()
+ .pipe(Effect.orDie)
+ if (!current) return false
+ const updated = yield* tx
+ .update(TaskRunTable)
+ .set({
+ workspace_branch_state: "conflict",
+ version: current.version + 1,
+ time_updated: input.now,
+ })
+ .where(
+ and(
+ eq(TaskRunTable.run_id, input.runID),
+ eq(TaskRunTable.version, current.version),
+ eq(TaskRunTable.workspace_branch_state, "admitting"),
+ ),
+ )
+ .returning({ version: TaskRunTable.version })
+ .get()
+ .pipe(Effect.orDie)
+ if (!updated) return false
+ yield* tx
+ .insert(TaskRunEventTable)
+ .values({
+ event_id: Identifier.ascending("event"),
+ run_id: input.runID,
+ version: updated.version,
+ type: "session_branch_conflict",
+ from_state: "admitted",
+ to_state: "admitted",
+ reason: input.reason,
+ time_created: input.now,
+ })
+ .run()
+ .pipe(Effect.orDie)
+ return true
+ }),
+ { behavior: "immediate" },
+ )
+ })
+}
+
+export * as SessionBranchProvisioner from "./branch-provisioner"
diff --git a/packages/deepagent-code/src/session/compaction-sql.ts b/packages/deepagent-code/src/session/compaction-sql.ts
new file mode 100644
index 00000000..21dc93f2
--- /dev/null
+++ b/packages/deepagent-code/src/session/compaction-sql.ts
@@ -0,0 +1,49 @@
+// BUG-005: drizzle-orm type bindings for compaction_run and compaction_summary_attempt.
+import { integer, sqliteTable, text } from "drizzle-orm/sqlite-core"
+
+export type CompactionRunState = "requested" | "summarizing" | "committed" | "failed" | "indeterminate"
+export type CompactionRunTrigger = "turn_start" | "provider_overflow" | "manual"
+export type SummaryAttemptState =
+ | "prepared"
+ | "dispatching"
+ | "streaming"
+ | "settled"
+ | "failed"
+ | "indeterminate_after_crash"
+
+export const CompactionRunTable = sqliteTable("compaction_run", {
+ run_id: text().primaryKey().notNull(),
+ session_id: text().notNull(),
+ from_prompt_epoch: integer().notNull(),
+ target_prompt_epoch: integer(),
+ trigger: text().$type().notNull(),
+ marker_message_id: text(),
+ marker_part_id: text(),
+ committed_summary_message_id: text(),
+ checkpoint_ref: text(),
+ checkpoint_hash: text(),
+ state: text().$type().notNull(),
+ terminal_failure_kind: text(),
+ created_at: integer().notNull(),
+ committed_at: integer(),
+})
+
+export const CompactionSummaryAttemptTable = sqliteTable("compaction_summary_attempt", {
+ summary_attempt_id: text().primaryKey().notNull(),
+ run_id: text()
+ .notNull()
+ .references(() => CompactionRunTable.run_id, { onDelete: "cascade" }),
+ ordinal: integer().notNull(),
+ parent_attempt_id: text(),
+ provider_id: text().notNull(),
+ model_id: text().notNull(),
+ protocol: text().notNull(),
+ request_hash: text(),
+ idempotency_key: text(),
+ state: text().$type().notNull(),
+ retry_reason: text(),
+ failure_kind: text(),
+ prepared_at: integer().notNull(),
+ dispatched_at: integer(),
+ completed_at: integer(),
+})
diff --git a/packages/deepagent-code/src/session/compaction.ts b/packages/deepagent-code/src/session/compaction.ts
index 0bab9b37..64f2c2bf 100644
--- a/packages/deepagent-code/src/session/compaction.ts
+++ b/packages/deepagent-code/src/session/compaction.ts
@@ -6,13 +6,18 @@ import { Provider } from "@/provider/provider"
import { MessageV2 } from "./message-v2"
import { Token } from "@/util/token"
import { Log } from "@deepagent-code/core/util/log"
-import { SessionProcessor } from "./processor"
+import { SessionProcessor, SummaryProtocolViolation } from "./processor"
import { Agent } from "@/agent/agent"
import { Plugin } from "@/plugin"
import { Config } from "@/config/config"
import { NotFoundError } from "@/storage/storage"
+import { Database } from "@deepagent-code/core/database/database"
+import { MessageTable, PartTable } from "@deepagent-code/core/session/sql"
+import { PromptEpoch } from "./prompt-epoch"
+import { CompactionRunTable, CompactionSummaryAttemptTable, type SummaryAttemptState } from "./compaction-sql"
+import { eq, and, inArray } from "drizzle-orm"
-import { Effect, Layer, Context } from "effect"
+import { Cause, Effect, Exit, Layer, Context, Option } from "effect"
import * as DateTime from "effect/DateTime"
import { InstanceState } from "@/effect/instance-state"
import { isOverflow as overflow, usable } from "./overflow"
@@ -26,6 +31,8 @@ import { ModelV2 } from "@deepagent-code/core/model"
import { EventV2 } from "@deepagent-code/core/event"
import { buildPrompt } from "@deepagent-code/core/session/compaction"
import { updateLedgerFromSummary, carryOverToBridge } from "./context-ledger"
+import { Hash } from "@deepagent-code/core/util/hash"
+import { LLM } from "./llm"
const log = Log.create({ service: "session.compaction" })
@@ -177,6 +184,284 @@ export const layer = Layer.effect(
const provider = yield* Provider.Service
const events = yield* EventV2Bridge.Service
const flags = yield* RuntimeFlags.Service
+ const { db } = yield* Database.Service
+ const promptEpoch = yield* PromptEpoch.Service
+
+ const recover = Effect.fn("SessionCompaction.recover")(function* (sessionID: SessionID) {
+ const requested = yield* db
+ .select({
+ run_id: CompactionRunTable.run_id,
+ marker_message_id: CompactionRunTable.marker_message_id,
+ marker_part_id: CompactionRunTable.marker_part_id,
+ })
+ .from(CompactionRunTable)
+ .where(and(eq(CompactionRunTable.session_id, sessionID), eq(CompactionRunTable.state, "requested")))
+ .all()
+ .pipe(Effect.orDie)
+ yield* Effect.forEach(requested, (run) =>
+ Effect.gen(function* () {
+ const markerMessage = run.marker_message_id
+ ? yield* db
+ .select({ id: MessageTable.id })
+ .from(MessageTable)
+ .where(
+ and(
+ eq(MessageTable.id, MessageID.make(run.marker_message_id)),
+ eq(MessageTable.session_id, sessionID),
+ ),
+ )
+ .get()
+ .pipe(Effect.orDie)
+ : undefined
+ const markerPart =
+ markerMessage && run.marker_part_id
+ ? yield* db
+ .select({ data: PartTable.data })
+ .from(PartTable)
+ .where(
+ and(
+ eq(PartTable.id, PartID.make(run.marker_part_id)),
+ eq(PartTable.message_id, markerMessage.id),
+ eq(PartTable.session_id, sessionID),
+ ),
+ )
+ .get()
+ .pipe(Effect.orDie)
+ : undefined
+ if (markerPart?.data.type === "compaction") return
+ yield* db
+ .update(CompactionRunTable)
+ .set({ state: "failed", terminal_failure_kind: "marker_write_incomplete" })
+ .where(and(eq(CompactionRunTable.run_id, run.run_id), eq(CompactionRunTable.state, "requested")))
+ .run()
+ .pipe(Effect.orDie)
+ }),
+ )
+ yield* db
+ .update(CompactionSummaryAttemptTable)
+ .set({ state: "indeterminate_after_crash", failure_kind: "process_restart", completed_at: Date.now() })
+ .where(
+ and(
+ inArray(
+ CompactionSummaryAttemptTable.run_id,
+ db
+ .select({ run_id: CompactionRunTable.run_id })
+ .from(CompactionRunTable)
+ .where(eq(CompactionRunTable.session_id, sessionID)),
+ ),
+ inArray(CompactionSummaryAttemptTable.state, ["dispatching", "streaming"] as const),
+ ),
+ )
+ .run()
+ .pipe(Effect.orDie)
+ yield* db
+ .update(CompactionRunTable)
+ .set({ state: "indeterminate", terminal_failure_kind: "process_restart" })
+ .where(and(eq(CompactionRunTable.session_id, sessionID), eq(CompactionRunTable.state, "summarizing")))
+ .run()
+ .pipe(Effect.orDie)
+ })
+
+ const ensureRun = Effect.fn("SessionCompaction.ensureRun")(function* (input: {
+ sessionID: SessionID
+ markerMessageID: MessageID
+ markerPartID?: PartID
+ fromEpoch: number
+ trigger: "turn_start" | "provider_overflow" | "manual"
+ }) {
+ const existing = yield* db
+ .select()
+ .from(CompactionRunTable)
+ .where(
+ and(
+ eq(CompactionRunTable.session_id, input.sessionID),
+ inArray(CompactionRunTable.state, ["requested", "summarizing", "indeterminate"] as const),
+ ),
+ )
+ .get()
+ .pipe(Effect.orDie)
+ if (existing) {
+ if (existing.marker_message_id !== input.markerMessageID) return undefined
+ return existing
+ }
+ const row = {
+ run_id: Hash.sha256(`compaction-run:${input.sessionID}:${input.markerMessageID}`),
+ session_id: input.sessionID,
+ from_prompt_epoch: input.fromEpoch,
+ trigger: input.trigger,
+ marker_message_id: input.markerMessageID,
+ marker_part_id: input.markerPartID,
+ state: "requested" as const,
+ created_at: Date.now(),
+ }
+ yield* db.insert(CompactionRunTable).values(row).onConflictDoNothing().run().pipe(Effect.orDie)
+ return yield* db
+ .select()
+ .from(CompactionRunTable)
+ .where(eq(CompactionRunTable.run_id, row.run_id))
+ .get()
+ .pipe(Effect.orDie)
+ })
+
+ const updateAttempt = (input: {
+ attemptID: string
+ from: SummaryAttemptState[]
+ to: SummaryAttemptState
+ error?: unknown
+ }) =>
+ db
+ .update(CompactionSummaryAttemptTable)
+ .set({
+ state: input.to,
+ ...(input.error
+ ? {
+ failure_kind:
+ input.error instanceof SummaryProtocolViolation
+ ? `summary_protocol_${input.error.kind}`
+ : "provider_error",
+ }
+ : {}),
+ ...(input.to === "dispatching" ? { dispatched_at: Date.now() } : {}),
+ ...(input.to === "settled" || input.to === "failed" || input.to === "indeterminate_after_crash"
+ ? { completed_at: Date.now() }
+ : {}),
+ })
+ .where(
+ and(
+ eq(CompactionSummaryAttemptTable.summary_attempt_id, input.attemptID),
+ inArray(CompactionSummaryAttemptTable.state, input.from),
+ ),
+ )
+ .run()
+ .pipe(Effect.orDie)
+
+ const prepareAttempt = Effect.fn("SessionCompaction.prepareAttempt")(function* (input: {
+ runID: string
+ model: Provider.Model
+ requestHash: string
+ parentAttemptID?: string
+ }) {
+ return yield* db
+ .transaction(
+ (tx) =>
+ Effect.gen(function* () {
+ const run = yield* tx
+ .select()
+ .from(CompactionRunTable)
+ .where(eq(CompactionRunTable.run_id, input.runID))
+ .get()
+ if (!run || (run.state !== "requested" && run.state !== "summarizing")) return undefined
+ const count = yield* tx
+ .select({ id: CompactionSummaryAttemptTable.summary_attempt_id })
+ .from(CompactionSummaryAttemptTable)
+ .where(eq(CompactionSummaryAttemptTable.run_id, input.runID))
+ .all()
+ if (count.length >= 2) return undefined
+ const ordinal = count.length + 1
+ const attemptID = Hash.sha256(`${input.runID}:summary-attempt:${ordinal}`)
+ yield* tx
+ .insert(CompactionSummaryAttemptTable)
+ .values({
+ summary_attempt_id: attemptID,
+ run_id: input.runID,
+ ordinal,
+ parent_attempt_id: input.parentAttemptID,
+ provider_id: input.model.providerID,
+ model_id: input.model.id,
+ protocol: LLM.toolChoiceProtocol(input.model),
+ request_hash: input.requestHash,
+ idempotency_key: Hash.sha256(`${input.runID}:summary:${ordinal}`),
+ state: "prepared",
+ prepared_at: Date.now(),
+ })
+ .run()
+ if (run.state === "requested") {
+ const transitioned = yield* tx
+ .update(CompactionRunTable)
+ .set({ state: "summarizing" })
+ .where(and(eq(CompactionRunTable.run_id, input.runID), eq(CompactionRunTable.state, "requested")))
+ .returning({ run_id: CompactionRunTable.run_id })
+ .get()
+ if (!transitioned) return yield* Effect.die(new Error(`compaction run transition lost: ${input.runID}`))
+ }
+ return {
+ attemptId: attemptID,
+ dispatching: updateAttempt({ attemptID, from: ["prepared"], to: "dispatching" }),
+ streaming: updateAttempt({ attemptID, from: ["dispatching"], to: "streaming" }),
+ settled: updateAttempt({ attemptID, from: ["dispatching", "streaming"], to: "settled" }),
+ failed: (error: unknown) =>
+ updateAttempt({
+ attemptID,
+ from: ["prepared", "dispatching", "streaming"],
+ to: "failed",
+ error,
+ }),
+ }
+ }),
+ { behavior: "immediate" },
+ )
+ .pipe(Effect.orDie)
+ })
+
+ const failRun = (runID: string, kind: string) =>
+ db
+ .update(CompactionRunTable)
+ .set({ state: "failed", terminal_failure_kind: kind })
+ .where(
+ and(
+ eq(CompactionRunTable.run_id, runID),
+ inArray(CompactionRunTable.state, ["requested", "summarizing"] as const),
+ ),
+ )
+ .run()
+ .pipe(Effect.orDie)
+
+ const commitRun = Effect.fn("SessionCompaction.commitRun")(function* (input: {
+ runID: string
+ sessionID: SessionID
+ fromEpoch: number
+ checkpointUserID: MessageID
+ checkpointAssistantID: MessageID
+ retainedTailStartID?: MessageID
+ sourceEndMessageID?: MessageID
+ checkpointHash: string
+ }) {
+ return yield* db
+ .transaction(
+ (tx) =>
+ Effect.gen(function* () {
+ const settled = yield* tx
+ .select({ id: CompactionSummaryAttemptTable.summary_attempt_id })
+ .from(CompactionSummaryAttemptTable)
+ .where(
+ and(
+ eq(CompactionSummaryAttemptTable.run_id, input.runID),
+ eq(CompactionSummaryAttemptTable.state, "settled"),
+ ),
+ )
+ .get()
+ if (!settled) return false
+ const epoch = yield* PromptEpoch.activateInTransaction(tx, input)
+ if (!epoch) return false
+ const committed = yield* tx
+ .update(CompactionRunTable)
+ .set({
+ state: "committed",
+ committed_summary_message_id: input.checkpointAssistantID,
+ checkpoint_hash: input.checkpointHash,
+ target_prompt_epoch: epoch.epoch,
+ committed_at: Date.now(),
+ })
+ .where(and(eq(CompactionRunTable.run_id, input.runID), eq(CompactionRunTable.state, "summarizing")))
+ .returning({ run_id: CompactionRunTable.run_id })
+ .get()
+ if (!committed) return yield* Effect.die(new Error(`compaction commit CAS lost: ${input.runID}`))
+ return true
+ }),
+ { behavior: "immediate" },
+ )
+ .pipe(Effect.orDie)
+ })
const isOverflow = Effect.fn("SessionCompaction.isOverflow")(function* (input: {
tokens: SessionV1.Assistant["tokens"]
@@ -309,7 +594,30 @@ export const layer = Layer.effect(
throw new Error(`Compaction parent must be a user message: ${input.parentID}`)
}
const userMessage = parent.info
- const compactionPart = parent.parts.find((part): part is SessionV1.CompactionPart => part.type === "compaction")
+ const existingCompactionPart = parent.parts.find(
+ (part): part is SessionV1.CompactionPart => part.type === "compaction",
+ )
+ const compactionPart =
+ existingCompactionPart ??
+ ({
+ id: PartID.ascending(),
+ messageID: parent.info.id,
+ sessionID: input.sessionID,
+ type: "compaction",
+ auto: input.auto,
+ overflow: input.overflow,
+ } satisfies SessionV1.CompactionPart)
+ if (!existingCompactionPart) yield* session.updatePart(compactionPart)
+ yield* recover(input.sessionID)
+ const activeEpoch = yield* promptEpoch.bootstrap(input.sessionID)
+ const run = yield* ensureRun({
+ sessionID: input.sessionID,
+ markerMessageID: input.parentID,
+ markerPartID: compactionPart.id,
+ fromEpoch: activeEpoch.epoch,
+ trigger: input.overflow ? "provider_overflow" : input.auto ? "turn_start" : "manual",
+ })
+ if (!run || run.state === "indeterminate") return "stop"
let messages = input.messages
let replay:
@@ -408,35 +716,81 @@ export const layer = Layer.effect(
},
}
yield* session.updateMessage(msg)
- const processor = yield* processors.create({
- assistantMessage: msg,
- sessionID: input.sessionID,
- model,
- })
- const result = yield* processor.process({
+
+ // BUG-006 §5.1: establish the explicit summary request contract.
+ // toolChoice:"none" tells the adapter the model must produce text only.
+ const summaryStreamInput = {
user: userMessage,
agent,
sessionID: input.sessionID,
tools: {},
+ toolChoice: "none" as const,
system: [],
messages: [
...modelMessages,
{
- role: "user",
- content: [{ type: "text", text: nextPrompt }],
+ role: "user" as const,
+ content: [{ type: "text" as const, text: nextPrompt }],
},
],
model,
- })
+ }
+
+ let dispatchCount = 0
+ let previousAttemptID: string | undefined
+ let currentProcessor = yield* processors.create({ assistantMessage: msg, sessionID: input.sessionID, model })
+ let result: "continue" | "compact" | "stop" = "stop"
+
+ while (true) {
+ dispatchCount++
+ const attempt = yield* prepareAttempt({
+ runID: run.run_id,
+ model,
+ requestHash: Hash.sha256(JSON.stringify(summaryStreamInput.messages)),
+ parentAttemptID: previousAttemptID,
+ })
+ if (!attempt) {
+ yield* failRun(run.run_id, "summary_attempt_budget_exhausted")
+ return "stop"
+ }
+ const dispatchResult = yield* Effect.exit(currentProcessor.processSummary(summaryStreamInput, attempt))
+ if (Exit.isSuccess(dispatchResult)) {
+ result = dispatchResult.value
+ if (result === "stop") {
+ yield* failRun(run.run_id, "summary_provider_error")
+ return "stop"
+ }
+ previousAttemptID = attempt.attemptId
+ break
+ }
+ const failure = Option.getOrUndefined(Cause.findErrorOption(dispatchResult.cause))
+ if (!(failure instanceof SummaryProtocolViolation)) {
+ yield* failRun(run.run_id, "summary_provider_error")
+ return "stop"
+ }
+ yield* session.updateMessage({
+ ...currentProcessor.message,
+ error: MessageV2.fromError(failure, { providerID: model.providerID }),
+ finish: "error",
+ })
+ if (dispatchCount >= 2) {
+ yield* failRun(run.run_id, `summary_protocol_${failure.kind}`)
+ return "stop"
+ }
+ const retryMsg: SessionV1.Assistant = { ...msg, id: MessageID.ascending(), error: undefined, finish: undefined }
+ yield* session.updateMessage(retryMsg)
+ currentProcessor = yield* processors.create({ assistantMessage: retryMsg, sessionID: input.sessionID, model })
+ }
if (result === "compact") {
- processor.message.error = new SessionV1.ContextOverflowError({
+ currentProcessor.message.error = new SessionV1.ContextOverflowError({
message: replay
? "Conversation history too large to compact - exceeds model context limit"
: "Session too large to compact - context exceeds model limit even after stripping media",
}).toObject()
- processor.message.finish = "error"
- yield* session.updateMessage(processor.message)
+ currentProcessor.message.finish = "error"
+ yield* session.updateMessage(currentProcessor.message)
+ yield* failRun(run.run_id, "summary_context_overflow")
return "stop"
}
@@ -531,11 +885,14 @@ export const layer = Layer.effect(
}
}
- if (processor.message.error) return "stop"
+ if (currentProcessor.message.error) {
+ yield* failRun(run.run_id, "summary_provider_error")
+ return "stop"
+ }
if (result === "continue") {
const summary = summaryText(
(yield* session.messages({ sessionID: input.sessionID }).pipe(Effect.orDie)).find(
- (item) => item.info.id === msg.id,
+ (item) => item.info.id === currentProcessor.message.id,
) ?? {
info: msg,
parts: [],
@@ -552,6 +909,24 @@ export const layer = Layer.effect(
recent,
})
}
+
+ if (summary) {
+ const committed = yield* commitRun({
+ runID: run.run_id,
+ sessionID: input.sessionID,
+ fromEpoch: run.from_prompt_epoch,
+ checkpointUserID: input.parentID,
+ checkpointAssistantID: currentProcessor.message.id,
+ checkpointHash: Hash.sha256(`${run.run_id}:${msg.id}:${summary.slice(0, 256)}`),
+ retainedTailStartID: selected.tail_start_id as MessageID | undefined,
+ sourceEndMessageID: selected.head.at(-1)?.info.id,
+ })
+ if (!committed) {
+ yield* failRun(run.run_id, "compaction_commit_conflict")
+ return "stop"
+ }
+ }
+
// V3.8 App-A Stage 1 (coexist, gated, default-safe): mirror the compaction summary into the
// structured Session Ledger. This does NOT change compaction behavior — it maintains the
// ledger as a structured-summary candidate for the Stage 2 Curator. updateLedgerFromSummary
@@ -577,23 +952,50 @@ export const layer = Layer.effect(
model: { providerID: ProviderV2.ID; modelID: ModelV2.ID }
auto: boolean
overflow?: boolean
+ trigger?: "turn_start" | "provider_overflow" | "manual"
}) {
- const msg = yield* session.updateMessage({
- id: MessageID.ascending(),
- role: "user",
- model: input.model,
+ yield* recover(input.sessionID)
+ // BUG-005: ensure Epoch 0 exists before the first compaction so PromptEpoch is always
+ // the history authority even for sessions that were created before this migration.
+ const activeEpoch = yield* promptEpoch.bootstrap(input.sessionID)
+
+ const markerMessageID = MessageID.ascending()
+ const markerPartID = PartID.ascending()
+ const run = yield* ensureRun({
sessionID: input.sessionID,
- agent: input.agent,
- time: { created: Date.now() },
- })
- yield* session.updatePart({
- id: PartID.ascending(),
- messageID: msg.id,
- sessionID: msg.sessionID,
- type: "compaction",
- auto: input.auto,
- overflow: input.overflow,
+ markerMessageID,
+ markerPartID,
+ fromEpoch: activeEpoch.epoch,
+ trigger: input.trigger ?? (input.overflow ? "provider_overflow" : input.auto ? "turn_start" : "manual"),
})
+ if (!run || run.state === "indeterminate") return
+
+ const marker = yield* Effect.exit(
+ Effect.gen(function* () {
+ const msg = yield* session.updateMessage({
+ id: markerMessageID,
+ role: "user",
+ model: input.model,
+ sessionID: input.sessionID,
+ agent: input.agent,
+ time: { created: Date.now() },
+ })
+ yield* session.updatePart({
+ id: markerPartID,
+ messageID: msg.id,
+ sessionID: msg.sessionID,
+ type: "compaction",
+ auto: input.auto,
+ overflow: input.overflow,
+ })
+ return msg
+ }),
+ )
+ if (Exit.isFailure(marker)) {
+ yield* failRun(run.run_id, "marker_write_incomplete")
+ return yield* Effect.failCause(marker.cause)
+ }
+ const msg = marker.value
if (flags.experimentalEventSystem) {
yield* events.publish(SessionEvent.Compaction.Started, {
sessionID: input.sessionID,
@@ -623,6 +1025,8 @@ export const defaultLayer = Layer.suspend(() =>
Layer.provide(Config.defaultLayer),
Layer.provide(RuntimeFlags.defaultLayer),
Layer.provide(EventV2Bridge.defaultLayer),
+ Layer.provide(Database.defaultLayer),
+ Layer.provide(PromptEpoch.defaultLayer),
),
)
diff --git a/packages/deepagent-code/src/session/deepagent-multiround.ts b/packages/deepagent-code/src/session/deepagent-multiround.ts
index e356360a..bf89e83c 100644
--- a/packages/deepagent-code/src/session/deepagent-multiround.ts
+++ b/packages/deepagent-code/src/session/deepagent-multiround.ts
@@ -1,5 +1,6 @@
import { Effect } from "effect"
import { AgentGateway } from "@deepagent-code/core/agent-gateway"
+import type { ValidationCommandInput } from "@deepagent-code/core/deepagent/validation"
import type { ValidationResult } from "../deepagent/validation-exec"
import type { GitGroundTruth } from "../deepagent/git-groundtruth"
@@ -44,7 +45,7 @@ const StopHook = new AgentGateway.DeepAgentHooks.HookPolicy().on("stop", AgentGa
// rounds with the same signature failed in the same way (no progress on the validation axis).
const validationSignature = (results: readonly ValidationResult[]): string =>
results
- .map((r) => `${r.command}=${r.passed ? "1" : "0"}`)
+ .map((r) => `${r.command}=${r.kind}:${r.exit_code}`)
.sort()
.join(",")
@@ -60,11 +61,11 @@ export type MultiRoundOps = {
readonly autonomous?: boolean
readonly maxRounds: number | null
readonly first: T
- readonly validationCommands: readonly string[]
+ readonly validationCommands: readonly ValidationCommandInput[]
// Re-establish the orchestrator session (the gateway prunes it on turn completion, so the
// driver must ensure it exists before running rounds — F3 fix).
readonly ensureSession: () => void
- readonly runValidation: (commands: readonly string[]) => Effect.Effect
+ readonly runValidation: (commands: readonly ValidationCommandInput[]) => Effect.Effect