From ad32c6b2cd8d71a083cb7c0d96525d9c1e91d35f Mon Sep 17 00:00:00 2001 From: Henry Date: Wed, 9 Sep 2026 02:57:45 +0800 Subject: [PATCH] fix(backend): stop discarding step_complete's handoff before the next step reads it (#3446) Co-authored-by: nova28 <17953305+nova28@users.noreply.github.com> Co-authored-by: Carlos Florencio --- .../backend/internal/mcp/handlers/handlers.go | 22 +- .../mcp/handlers/step_complete_bounds.go | 29 + .../mcp/handlers/step_complete_bounds_test.go | 60 ++ .../mcp/handlers/step_complete_test.go | 47 ++ .../handlers/step_complete_truncation_test.go | 170 ++++ apps/backend/internal/mcp/server/server.go | 6 +- .../server/step_complete_description_test.go | 61 ++ .../coordinator_stop_edges_test.go | 4 + .../orchestrator/event_handlers_agent.go | 14 +- ...event_handlers_duplicate_autostart_test.go | 4 +- ...vent_handlers_initial_prompt_dedup_test.go | 6 +- .../event_handlers_step_completion.go | 28 +- .../orchestrator/event_handlers_workflow.go | 282 +++++-- .../event_handlers_workflow_moved_test.go | 2 +- .../event_handlers_workflow_profile_test.go | 6 +- ...ent_handlers_workflow_prompt_claim_test.go | 10 +- ...handlers_workflow_reset_quiescence_test.go | 2 +- .../fallback_fresh_launch_handoff_test.go | 72 ++ .../orchestrator/messagequeue/send_now.go | 12 + .../messagequeue/send_now_test.go | 46 ++ .../orchestrator/messagequeue/types.go | 7 + .../prompt_dispatch_failure_handoff_test.go | 96 +++ .../queue_auto_run_review_test.go | 1 + .../internal/orchestrator/queue_send_now.go | 1 + apps/backend/internal/orchestrator/service.go | 5 +- .../orchestrator/step_handoff_carry.go | 252 ++++++ .../step_handoff_carry_dispatch_test.go | 751 ++++++++++++++++++ .../step_handoff_carry_write_test.go | 385 +++++++++ .../step_history_handoff_blockers_test.go | 169 ++++ .../internal/orchestrator/task_operations.go | 53 +- .../task_pull_request_target_prompt_test.go | 2 +- .../internal/orchestrator/workflow_store.go | 17 + apps/backend/internal/task/models/models.go | 16 + .../internal/task/models/public_metadata.go | 5 +- .../task/models/public_metadata_test.go | 25 + .../step_handoff_carry_claim_postgres_test.go | 125 +++ .../sqlite/step_handoff_carry_claim_test.go | 156 ++++ .../internal/task/repository/sqlite/task.go | 64 ++ apps/backend/internal/task/service/service.go | 2 +- .../service_step_handoff_metadata_test.go | 49 ++ .../task/service/service_task_metadata.go | 11 +- .../internal/task/service/service_workflow.go | 19 +- .../repository/session_step_history_test.go | 48 ++ .../internal/workflow/service/service.go | 20 +- .../tests/kanban/wip-overflow-queue.spec.ts | 1 + ...icit-completion-signal-for-auto-advance.md | 13 +- docs/decisions/INDEX.md | 2 +- docs/specs/tasks/README.md | 2 + ...flow-completion-signal-payload-delivery.md | 318 ++++++++ ...flow-completion-signal-payload-delivery.md | 566 +++++++++++++ 50 files changed, 3921 insertions(+), 143 deletions(-) create mode 100644 apps/backend/internal/mcp/handlers/step_complete_bounds.go create mode 100644 apps/backend/internal/mcp/handlers/step_complete_bounds_test.go create mode 100644 apps/backend/internal/mcp/handlers/step_complete_truncation_test.go create mode 100644 apps/backend/internal/mcp/server/step_complete_description_test.go create mode 100644 apps/backend/internal/orchestrator/fallback_fresh_launch_handoff_test.go create mode 100644 apps/backend/internal/orchestrator/prompt_dispatch_failure_handoff_test.go create mode 100644 apps/backend/internal/orchestrator/step_handoff_carry.go create mode 100644 apps/backend/internal/orchestrator/step_handoff_carry_dispatch_test.go create mode 100644 apps/backend/internal/orchestrator/step_handoff_carry_write_test.go create mode 100644 apps/backend/internal/orchestrator/step_history_handoff_blockers_test.go create mode 100644 apps/backend/internal/task/models/public_metadata_test.go create mode 100644 apps/backend/internal/task/repository/sqlite/step_handoff_carry_claim_postgres_test.go create mode 100644 apps/backend/internal/task/repository/sqlite/step_handoff_carry_claim_test.go create mode 100644 apps/backend/internal/task/service/service_step_handoff_metadata_test.go create mode 100644 docs/specs/tasks/requirements/workflow-completion-signal-payload-delivery.md create mode 100644 docs/specs/tasks/system-design/workflow-completion-signal-payload-delivery.md diff --git a/apps/backend/internal/mcp/handlers/handlers.go b/apps/backend/internal/mcp/handlers/handlers.go index 3cab84d432..c12bb1bc74 100644 --- a/apps/backend/internal/mcp/handlers/handlers.go +++ b/apps/backend/internal/mcp/handlers/handlers.go @@ -2316,12 +2316,14 @@ func (h *Handlers) handleStepComplete(ctx context.Context, msg *ws.Message) (*ws return ws.NewError(msg.ID, msg.Action, ws.ErrorCodeValidation, "workflow step changed before signal was recorded", nil) } + boundedHandoff, handoffTruncated := boundStepCompletionSignalField(strings.TrimSpace(req.Handoff)) + boundedBlockers, blockersTruncated := boundStepCompletionSignalField(strings.TrimSpace(req.Blockers)) signal := models.PendingStepCompletionSignal{ StepID: launchStepID, Source: models.StepCompletionSourceAgent, Summary: strings.TrimSpace(req.Summary), - Handoff: strings.TrimSpace(req.Handoff), - Blockers: strings.TrimSpace(req.Blockers), + Handoff: boundedHandoff, + Blockers: boundedBlockers, SignaledAt: time.Now().UTC(), } stored, err := h.claimStepCompletionSignal(ctx, req.TaskID, req.SessionID, launchStepID, signal) @@ -2353,11 +2355,23 @@ func (h *Handlers) handleStepComplete(ctx context.Context, msg *ws.Message) (*ws return errMsg, err } - return ws.NewResponse(msg.ID, msg.Action, map[string]interface{}{ + response := map[string]interface{}{ "accepted": true, "step_id": task.WorkflowStepID, "signaled_at": signal.SignaledAt, - }) + } + var truncatedFields []string + if handoffTruncated { + truncatedFields = append(truncatedFields, "handoff") + } + if blockersTruncated { + truncatedFields = append(truncatedFields, "blockers") + } + if len(truncatedFields) > 0 { + response["truncated"] = truncatedFields + response["truncation_limit_bytes"] = stepCompletionSignalFieldLimitBytes + } + return ws.NewResponse(msg.ID, msg.Action, response) } func (h *Handlers) stepCompletionLaunchStep(ctx context.Context, sessionID, fallback string) (string, error) { diff --git a/apps/backend/internal/mcp/handlers/step_complete_bounds.go b/apps/backend/internal/mcp/handlers/step_complete_bounds.go new file mode 100644 index 0000000000..53164e733b --- /dev/null +++ b/apps/backend/internal/mcp/handlers/step_complete_bounds.go @@ -0,0 +1,29 @@ +package handlers + +import ( + "github.com/kandev/kandev/internal/common/truncate" +) + +// stepCompletionSignalFieldLimitBytes is the fixed, compiled-in ceiling for +// the step_complete_kandev handoff and blockers arguments. It is inclusive of +// stepCompletionSignalTruncationMarker and applies to each field +// independently, so it is never configurable at runtime or per deployment. +const stepCompletionSignalFieldLimitBytes = 8192 + +// stepCompletionSignalTruncationMarker is appended to a truncated handoff or +// blockers value so a later reader cannot mistake a cut value for a complete +// one. Its byte length (33) is subtracted from the ceiling before cutting. +const stepCompletionSignalTruncationMarker = "[truncated: over 8192-byte limit]" + +// boundStepCompletionSignalField bounds an already-trimmed handoff or +// blockers value to stepCompletionSignalFieldLimitBytes, measured as UTF-8 +// byte length. A value at or under the ceiling is stored byte-for-byte; a +// larger value is cut on a UTF-8 character boundary and the fixed marker is +// appended, so the stored result is never larger than the ceiling. +func boundStepCompletionSignalField(trimmed string) (bounded string, wasTruncated bool) { + if len(trimmed) <= stepCompletionSignalFieldLimitBytes { + return trimmed, false + } + prefixLimit := stepCompletionSignalFieldLimitBytes - len(stepCompletionSignalTruncationMarker) + return truncate.UTF8(trimmed, prefixLimit) + stepCompletionSignalTruncationMarker, true +} diff --git a/apps/backend/internal/mcp/handlers/step_complete_bounds_test.go b/apps/backend/internal/mcp/handlers/step_complete_bounds_test.go new file mode 100644 index 0000000000..99e15cb698 --- /dev/null +++ b/apps/backend/internal/mcp/handlers/step_complete_bounds_test.go @@ -0,0 +1,60 @@ +package handlers + +import ( + "strings" + "testing" + + "github.com/stretchr/testify/assert" + "github.com/stretchr/testify/require" +) + +// TestBoundStepCompletionSignalField_Boundary covers AC-003.2's exact +// boundary pair: 8,192 bytes stores whole, 8,193 truncates. +func TestBoundStepCompletionSignalField_Boundary(t *testing.T) { + atLimit := strings.Repeat("a", stepCompletionSignalFieldLimitBytes) + bounded, truncated := boundStepCompletionSignalField(atLimit) + assert.False(t, truncated) + assert.Equal(t, atLimit, bounded) + assert.Len(t, bounded, stepCompletionSignalFieldLimitBytes) + + overLimit := strings.Repeat("a", stepCompletionSignalFieldLimitBytes+1) + bounded, truncated = boundStepCompletionSignalField(overLimit) + assert.True(t, truncated) + assert.LessOrEqual(t, len(bounded), stepCompletionSignalFieldLimitBytes) + assert.True(t, strings.HasSuffix(bounded, stepCompletionSignalTruncationMarker)) +} + +// TestBoundStepCompletionSignalField_MultiByteBoundary ensures a cut landing +// mid-rune is avoided: the retained prefix must be valid UTF-8 and the total +// length (marker included) must stay within the ceiling (AC-003.3). +func TestBoundStepCompletionSignalField_MultiByteBoundary(t *testing.T) { + // Each rune is 3 bytes (e.g. "世"), chosen so a naive byte-count cut would + // very likely split a character. + rune3 := "世" + require.Len(t, rune3, 3) + overLimit := strings.Repeat(rune3, (stepCompletionSignalFieldLimitBytes/3)+50) + + bounded, truncated := boundStepCompletionSignalField(overLimit) + require.True(t, truncated) + assert.LessOrEqual(t, len(bounded), stepCompletionSignalFieldLimitBytes) + assert.True(t, strings.HasSuffix(bounded, stepCompletionSignalTruncationMarker)) + prefix := strings.TrimSuffix(bounded, stepCompletionSignalTruncationMarker) + assert.True(t, utf8ValidString(prefix), "retained prefix must not split a multi-byte character") +} + +func utf8ValidString(s string) bool { + for _, r := range s { + if r == '�' { + return false + } + } + return true +} + +// TestBoundStepCompletionSignalField_WellUnderLimit is the trivial pass- +// through case: a short value is stored unchanged with no marker. +func TestBoundStepCompletionSignalField_WellUnderLimit(t *testing.T) { + bounded, truncated := boundStepCompletionSignalField("short handoff") + assert.False(t, truncated) + assert.Equal(t, "short handoff", bounded) +} diff --git a/apps/backend/internal/mcp/handlers/step_complete_test.go b/apps/backend/internal/mcp/handlers/step_complete_test.go index b08bc70f93..5f2f157e8d 100644 --- a/apps/backend/internal/mcp/handlers/step_complete_test.go +++ b/apps/backend/internal/mcp/handlers/step_complete_test.go @@ -378,6 +378,53 @@ func TestHandleStepComplete_DedupRunningNoRepublish(t *testing.T) { assert.Equal(t, before, after, "already_signaled dedup must not increment workflow_step_completion_signal_received_total") } +// TestHandleStepComplete_DuplicateCallDoesNotOverwriteHandoffOrBlockers covers +// AC-001.13: a rejected duplicate call must not mutate the already-persisted +// bag, even when the second call's handoff/blockers differ from the first's. +// Only the first accepted call's content may ever reach the single-slot carry +// token or the audit metadata — a duplicate silently replacing it would let a +// second, unvetted call clobber content already committed to the transition. +func TestHandleStepComplete_DuplicateCallDoesNotOverwriteHandoffOrBlockers(t *testing.T) { + ctx := context.Background() + svc, repo := newTestTaskService(t) + seedStepCompleteTarget(t, repo, "task-dup-overwrite", "session-dup-overwrite", "step-1", models.TaskSessionStateRunning) + require.NoError(t, repo.SetSessionMetadataKey(ctx, "session-dup-overwrite", models.SessionMetaKeyPendingStepCompletion, models.PendingStepCompletionSignal{ + StepID: "step-1", + Source: models.StepCompletionSourceAgent, + Summary: "first call", + Handoff: "first handoff", + Blockers: "first blockers", + SignaledAt: time.Now().UTC(), + })) + seedAgentProfileSnapshot(t, repo, "session-dup-overwrite", "claude-dup-overwrite") + bus := &mcpRecordingEventBus{} + h := newStepCompleteHandler(t, svc, repo, bus) + + msg := makeWSMessage(t, ws.ActionMCPStepComplete, map[string]interface{}{ + "task_id": "task-dup-overwrite", + "session_id": "session-dup-overwrite", + "summary": "second call (same step)", + "handoff": "second handoff should not land", + "blockers": "second blockers should not land", + }) + resp, err := h.handleStepComplete(ctx, msg) + require.NoError(t, err) + require.NotNil(t, resp) + + var payload map[string]interface{} + require.NoError(t, json.Unmarshal(resp.Payload, &payload)) + assert.Equal(t, false, payload["accepted"]) + assert.Equal(t, "already_signaled", payload["reason"]) + + session, err := repo.GetTaskSession(ctx, "session-dup-overwrite") + require.NoError(t, err) + bag, ok := models.LoadPendingStepSignal(session.Metadata) + require.True(t, ok, "expected the original bag entry to still be present") + assert.Equal(t, "first call", bag.Summary, "duplicate call must not overwrite the persisted summary") + assert.Equal(t, "first handoff", bag.Handoff, "duplicate call must not overwrite the persisted handoff") + assert.Equal(t, "first blockers", bag.Blockers, "duplicate call must not overwrite the persisted blockers") +} + // TestHandleStepComplete_DedupWaitingRepublishes covers the retry-after- // publish-failure path. When the session is WAITING_FOR_INPUT, the bag is // already persisted but the orchestrator subscriber may have never fired diff --git a/apps/backend/internal/mcp/handlers/step_complete_truncation_test.go b/apps/backend/internal/mcp/handlers/step_complete_truncation_test.go new file mode 100644 index 0000000000..1130d4d654 --- /dev/null +++ b/apps/backend/internal/mcp/handlers/step_complete_truncation_test.go @@ -0,0 +1,170 @@ +package handlers + +import ( + "context" + "encoding/json" + "strings" + "testing" + "time" + + "github.com/stretchr/testify/assert" + "github.com/stretchr/testify/require" + + "github.com/kandev/kandev/internal/task/models" + ws "github.com/kandev/kandev/pkg/websocket" +) + +// TestHandleStepComplete_TruncatesOversizedHandoff covers AC-003.1/003.2/003.4: +// an oversized handoff never strands the step (the call is still accepted and +// stored bounded), and the result reports which argument was truncated. +func TestHandleStepComplete_TruncatesOversizedHandoff(t *testing.T) { + svc, repo := newTestTaskService(t) + seedStepCompleteTarget(t, repo, "task-trunc", "session-trunc", "step-1", models.TaskSessionStateRunning) + bus := &mcpRecordingEventBus{} + h := newStepCompleteHandler(t, svc, repo, bus) + + oversized := strings.Repeat("h", stepCompletionSignalFieldLimitBytes+500) + msg := makeWSMessage(t, ws.ActionMCPStepComplete, map[string]interface{}{ + "task_id": "task-trunc", + "session_id": "session-trunc", + "summary": "done", + "handoff": oversized, + }) + resp, err := h.handleStepComplete(context.Background(), msg) + require.NoError(t, err) + + var payload map[string]interface{} + require.NoError(t, json.Unmarshal(resp.Payload, &payload)) + assert.Equal(t, true, payload["accepted"], "an oversized value must never strand the step") + truncatedRaw, ok := payload["truncated"].([]interface{}) + require.True(t, ok, "expected truncated array in response") + assert.Equal(t, []interface{}{"handoff"}, truncatedRaw) + assert.Equal(t, float64(stepCompletionSignalFieldLimitBytes), payload["truncation_limit_bytes"]) + + session, err := repo.GetTaskSession(context.Background(), "session-trunc") + require.NoError(t, err) + bag, ok := models.LoadPendingStepSignal(session.Metadata) + require.True(t, ok) + assert.LessOrEqual(t, len(bag.Handoff), stepCompletionSignalFieldLimitBytes) + assert.True(t, strings.HasSuffix(bag.Handoff, stepCompletionSignalTruncationMarker)) +} + +// TestHandleStepComplete_WhitespacePaddedHandoffTrimsBeforeMeasuring covers +// AC-003.2's trim-first ordering: a handoff that is oversized BEFORE +// trimming but at or under the ceiling AFTER trimming must be stored whole, +// with no truncation reported. +func TestHandleStepComplete_WhitespacePaddedHandoffTrimsBeforeMeasuring(t *testing.T) { + svc, repo := newTestTaskService(t) + seedStepCompleteTarget(t, repo, "task-trim-first", "session-trim-first", "step-1", models.TaskSessionStateRunning) + bus := &mcpRecordingEventBus{} + h := newStepCompleteHandler(t, svc, repo, bus) + + atLimit := strings.Repeat("h", stepCompletionSignalFieldLimitBytes) + padded := strings.Repeat(" ", 500) + atLimit + strings.Repeat("\n", 500) + msg := makeWSMessage(t, ws.ActionMCPStepComplete, map[string]interface{}{ + "task_id": "task-trim-first", + "session_id": "session-trim-first", + "summary": "done", + "handoff": padded, + }) + resp, err := h.handleStepComplete(context.Background(), msg) + require.NoError(t, err) + + var payload map[string]interface{} + require.NoError(t, json.Unmarshal(resp.Payload, &payload)) + assert.Equal(t, true, payload["accepted"]) + _, hasTruncated := payload["truncated"] + assert.False(t, hasTruncated, "trimmed value is exactly at the ceiling and must not report truncation") + + session, err := repo.GetTaskSession(context.Background(), "session-trim-first") + require.NoError(t, err) + bag, ok := models.LoadPendingStepSignal(session.Metadata) + require.True(t, ok) + assert.Equal(t, atLimit, bag.Handoff, "stored value must equal the trimmed input exactly, whole and unmarked") +} + +// TestHandleStepComplete_TruncatesBothFieldsInOrder covers AC-003.5: when +// both handoff and blockers truncate, the array lists "handoff" before +// "blockers". +func TestHandleStepComplete_TruncatesBothFieldsInOrder(t *testing.T) { + svc, repo := newTestTaskService(t) + seedStepCompleteTarget(t, repo, "task-trunc2", "session-trunc2", "step-1", models.TaskSessionStateRunning) + bus := &mcpRecordingEventBus{} + h := newStepCompleteHandler(t, svc, repo, bus) + + oversized := strings.Repeat("x", stepCompletionSignalFieldLimitBytes+1) + msg := makeWSMessage(t, ws.ActionMCPStepComplete, map[string]interface{}{ + "task_id": "task-trunc2", + "session_id": "session-trunc2", + "summary": "done", + "handoff": oversized, + "blockers": oversized, + }) + resp, err := h.handleStepComplete(context.Background(), msg) + require.NoError(t, err) + + var payload map[string]interface{} + require.NoError(t, json.Unmarshal(resp.Payload, &payload)) + assert.Equal(t, []interface{}{"handoff", "blockers"}, payload["truncated"]) +} + +// TestHandleStepComplete_NoTruncationOmitsFields covers AC-003.5's converse: +// when nothing was truncated, both fields are entirely absent from the +// response rather than present with empty/zero values. +func TestHandleStepComplete_NoTruncationOmitsFields(t *testing.T) { + svc, repo := newTestTaskService(t) + seedStepCompleteTarget(t, repo, "task-notrunc", "session-notrunc", "step-1", models.TaskSessionStateRunning) + bus := &mcpRecordingEventBus{} + h := newStepCompleteHandler(t, svc, repo, bus) + + msg := makeWSMessage(t, ws.ActionMCPStepComplete, map[string]interface{}{ + "task_id": "task-notrunc", + "session_id": "session-notrunc", + "summary": "done", + "handoff": "short", + }) + resp, err := h.handleStepComplete(context.Background(), msg) + require.NoError(t, err) + + var payload map[string]interface{} + require.NoError(t, json.Unmarshal(resp.Payload, &payload)) + _, hasTruncated := payload["truncated"] + _, hasLimit := payload["truncation_limit_bytes"] + assert.False(t, hasTruncated) + assert.False(t, hasLimit) +} + +// TestHandleStepComplete_DuplicateReportsNoTruncation covers AC-003.5a: a +// call rejected as a duplicate keeps its existing rejection shape and never +// reports truncation, even though its (discarded) values would have +// truncated. +func TestHandleStepComplete_DuplicateReportsNoTruncation(t *testing.T) { + ctx := context.Background() + svc, repo := newTestTaskService(t) + seedStepCompleteTarget(t, repo, "task-dup-trunc", "session-dup-trunc", "step-1", models.TaskSessionStateRunning) + require.NoError(t, repo.SetSessionMetadataKey(ctx, "session-dup-trunc", models.SessionMetaKeyPendingStepCompletion, models.PendingStepCompletionSignal{ + StepID: "step-1", + Source: models.StepCompletionSourceAgent, + Summary: "first call", + SignaledAt: time.Now().UTC(), + })) + bus := &mcpRecordingEventBus{} + h := newStepCompleteHandler(t, svc, repo, bus) + + oversized := strings.Repeat("y", stepCompletionSignalFieldLimitBytes+1) + msg := makeWSMessage(t, ws.ActionMCPStepComplete, map[string]interface{}{ + "task_id": "task-dup-trunc", + "session_id": "session-dup-trunc", + "summary": "second call", + "handoff": oversized, + }) + resp, err := h.handleStepComplete(ctx, msg) + require.NoError(t, err) + + var payload map[string]interface{} + require.NoError(t, json.Unmarshal(resp.Payload, &payload)) + assert.Equal(t, false, payload["accepted"]) + assert.Equal(t, "already_signaled", payload["reason"]) + _, hasTruncated := payload["truncated"] + assert.False(t, hasTruncated, "a rejected duplicate must report no truncation") +} diff --git a/apps/backend/internal/mcp/server/server.go b/apps/backend/internal/mcp/server/server.go index 89a0279d01..e601353f77 100644 --- a/apps/backend/internal/mcp/server/server.go +++ b/apps/backend/internal/mcp/server/server.go @@ -1706,10 +1706,10 @@ func (s *Server) updateRepositoryBaseBranchHandler() server.ToolHandlerFunc { func (s *Server) registerStepCompleteTool() { s.mcpServer.AddTool( mcp.NewTool("step_complete_kandev", - mcp.WithDescription(`Signal that every requirement for the current workflow step is complete. Call this as the step's final action; do not call before asking the user, during partial work, or with an unresolved blocker. The signal is idempotent within a step, and any configured transition runs asynchronously at turn end. A new user message cancels a pending signal. The summary is shown to the user and may be forwarded to the next step.`), + mcp.WithDescription(`Signal that every requirement for the current workflow step is complete. Call this as the step's final action; do not call before asking the user or during partial work. If you cannot make further progress without input, describe the issue in blockers. The signal is idempotent within a step, and any configured transition runs asynchronously at turn end. A new user message cancels a pending signal. The summary is shown to the user and is recorded on the step-transition history.`), mcp.WithString("summary", mcp.Required(), mcp.Description("One-paragraph plain-text summary of what was done in this step. Shown to the user.")), - mcp.WithString("handoff", mcp.Description("Optional context the next step's agent will need to pick up where you left off (decisions, open files, follow-ups).")), - mcp.WithString("blockers", mcp.Description("Optional list of known unresolved issues. Use sparingly — only when the step is complete in the sense that you cannot make further progress without input, not for normal partial work.")), + mcp.WithString("handoff", mcp.Description("Optional context for the immediately-following step's agent, delivered once in that step's first prompt and not carried beyond it. Up to 8,192 bytes; longer values are truncated.")), + mcp.WithString("blockers", mcp.Description("Optional list of known unresolved issues. Recorded on this step's transition history, not delivered to the next step's agent — do not use it to pass context forward. Use sparingly, only when you cannot make further progress without input. Up to 8,192 bytes; longer values are truncated.")), ), s.wrapHandler("step_complete_kandev", s.stepCompleteHandler()), ) diff --git a/apps/backend/internal/mcp/server/step_complete_description_test.go b/apps/backend/internal/mcp/server/step_complete_description_test.go new file mode 100644 index 0000000000..d15a44cdfe --- /dev/null +++ b/apps/backend/internal/mcp/server/step_complete_description_test.go @@ -0,0 +1,61 @@ +package mcp + +import ( + "strings" + "testing" + + "github.com/stretchr/testify/assert" + "github.com/stretchr/testify/require" +) + +// TestStepCompleteToolDescription_DeliveryExtent covers REQ-004: the +// registered descriptions must state the actual delivered behavior (handoff +// is delivered once, to the immediately-next step, and not carried further; +// blockers is recorded on the transition record and never delivered to the +// next step's agent), state the byte ceiling, and must not claim a +// forwarding behavior the mechanism does not provide. +func TestStepCompleteToolDescription_DeliveryExtent(t *testing.T) { + s := newTaskModeServer(t, &testBackend{}, "task-current") + tool, ok := s.mcpServer.ListTools()["step_complete_kandev"] + require.True(t, ok) + + var handoffDesc, blockersDesc string + raw, ok := tool.Tool.InputSchema.Properties["handoff"].(map[string]interface{}) + require.True(t, ok, "expected handoff property schema") + handoffDesc, _ = raw["description"].(string) + raw, ok = tool.Tool.InputSchema.Properties["blockers"].(map[string]interface{}) + require.True(t, ok, "expected blockers property schema") + blockersDesc, _ = raw["description"].(string) + + // AC-004.1: handoff's description states one-time, immediately-next-step + // delivery and that it is not carried beyond that step. + assert.Contains(t, handoffDesc, "once") + assert.Contains(t, handoffDesc, "not carried beyond") + + // AC-004.2: blockers' description states it is recorded on the transition + // record and NOT delivered to the next step's agent. + assert.Contains(t, blockersDesc, "not delivered to the next step") + + // AC-004.3: both descriptions state the byte ceiling. + assert.Contains(t, handoffDesc, "8,192") + assert.Contains(t, blockersDesc, "8,192") + + // AC-004.4: the top-level description must not claim handoff/blockers are + // forwarded to the next step (the mechanism does not deliver blockers at + // all, and handoff only survives one hop). + assert.NotContains(t, strings.ToLower(tool.Tool.Description), "forwarded to the next step") + + // AC-004.5: both arguments remain registered, optional, and string-typed. + _, handoffRequired := requiredSet(tool.Tool.InputSchema.Required)["handoff"] + _, blockersRequired := requiredSet(tool.Tool.InputSchema.Required)["blockers"] + assert.False(t, handoffRequired) + assert.False(t, blockersRequired) +} + +func requiredSet(required []string) map[string]struct{} { + set := make(map[string]struct{}, len(required)) + for _, name := range required { + set[name] = struct{}{} + } + return set +} diff --git a/apps/backend/internal/orchestrator/coordinator_stop_edges_test.go b/apps/backend/internal/orchestrator/coordinator_stop_edges_test.go index d809ea97a1..5390dbe6bb 100644 --- a/apps/backend/internal/orchestrator/coordinator_stop_edges_test.go +++ b/apps/backend/internal/orchestrator/coordinator_stop_edges_test.go @@ -210,6 +210,8 @@ func TestFallbackFreshLaunch_CoordinatorCancellationWinsBeforeResetWrite(t *test "session-fallback-stop-race", "replacement prompt", false, + "", + false, nil, nil, nil, @@ -263,6 +265,8 @@ func TestFallbackFreshLaunch_DoesNotResetCancellationObservedBeforeGuard(t *test "session-fallback-already-stopped", "replacement prompt", false, + "", + false, nil, nil, nil, diff --git a/apps/backend/internal/orchestrator/event_handlers_agent.go b/apps/backend/internal/orchestrator/event_handlers_agent.go index 8656ab150b..2085e72dea 100644 --- a/apps/backend/internal/orchestrator/event_handlers_agent.go +++ b/apps/backend/internal/orchestrator/event_handlers_agent.go @@ -789,11 +789,12 @@ func (s *Service) recordQueuedUserMessage(ctx context.Context, queuedMsg *messag } references := entityrefs.NormalizePersisted(queuedMsg.Metadata[messagequeue.MetadataEntityReferences]) promptContent := AppendEntityReferenceContext(queuedMsg.Content, references) + promptContent = appendStepHandoffToPrompt(promptContent, stepHandoffFromQueuedMetadata(queuedMsg.Metadata)) meta := NewUserMessageMeta(). WithPlanMode(queuedMsg.PlanMode). WithAttachments(attachments). WithEntityReferences(references) - metaMap := mergeMetadata(meta.ToMap(), metadataWithoutEntityReferences(queuedMsg.Metadata)) + metaMap := mergeMetadata(meta.ToMap(), metadataWithoutQueueOnlyKeys(queuedMsg.Metadata)) if err := s.messageCreator.CreateUserMessage(ctx, queuedMsg.TaskID, promptContent, queuedMsg.SessionID, turnID, metaMap); err != nil { s.logger.Error("failed to create user message for queued message", zap.String("session_id", queuedMsg.SessionID), zap.Error(err)) return err @@ -865,6 +866,7 @@ func (s *Service) executeQueuedMessageWithReservation( } references := entityrefs.NormalizePersisted(queuedMsg.Metadata[messagequeue.MetadataEntityReferences]) promptContent := AppendEntityReferenceContext(queuedMsg.Content, references) + promptContent = appendStepHandoffToPrompt(promptContent, stepHandoffFromQueuedMetadata(queuedMsg.Metadata)) // Create user messages for ordinary queue entries now. Lifecycle entries // persist their visible message only after the final active-task claim. @@ -1153,13 +1155,19 @@ func markQueuedUserMessageRecorded(queuedMsg *messagequeue.QueuedMessage) { queuedMsg.Metadata[metaKeyUserMessageRecorded] = true } -func metadataWithoutEntityReferences(metadata map[string]interface{}) map[string]interface{} { +// metadataWithoutQueueOnlyKeys strips queue-transport-only keys before a +// queued message's metadata is persisted onto a chat message row: +// entity references are re-added via WithEntityReferences, and a carried +// completion handoff (messagequeue.MetadataStepHandoff) is already folded +// into the recorded content by the caller, so neither belongs in the row's +// own stored metadata. +func metadataWithoutQueueOnlyKeys(metadata map[string]interface{}) map[string]interface{} { if len(metadata) == 0 { return nil } copy := make(map[string]interface{}, len(metadata)) for key, value := range metadata { - if key != messagequeue.MetadataEntityReferences { + if key != messagequeue.MetadataEntityReferences && key != messagequeue.MetadataStepHandoff { copy[key] = value } } diff --git a/apps/backend/internal/orchestrator/event_handlers_duplicate_autostart_test.go b/apps/backend/internal/orchestrator/event_handlers_duplicate_autostart_test.go index 155774efe8..8c26f7335c 100644 --- a/apps/backend/internal/orchestrator/event_handlers_duplicate_autostart_test.go +++ b/apps/backend/internal/orchestrator/event_handlers_duplicate_autostart_test.go @@ -586,7 +586,7 @@ func TestAutoStartCreatedLaunch_QueuesPromptWhenAgentAlreadyRunning(t *testing.T t.Fatalf("set session profile: %v", err) } - err = svc.autoStartStepPrompt(ctx, taskID, session, step, "Do the work", false, true) + err = svc.autoStartStepPrompt(ctx, taskID, session, step, "Do the work", false, true, nil) if err == nil { t.Fatal("expected autoStartStepPrompt to return the launch error") } @@ -664,7 +664,7 @@ func TestAutoStartCreatedLaunch_DoesNotRestoreHandoffAfterQueueingMergedPrompt(t t.Fatalf("seed handoff message: %v", err) } - err = svc.autoStartStepPrompt(ctx, taskID, session, step, autoStart, false, true) + err = svc.autoStartStepPrompt(ctx, taskID, session, step, autoStart, false, true, nil) if err == nil { t.Fatal("expected autoStartStepPrompt to return the launch error") } diff --git a/apps/backend/internal/orchestrator/event_handlers_initial_prompt_dedup_test.go b/apps/backend/internal/orchestrator/event_handlers_initial_prompt_dedup_test.go index 142e426124..f7b6c29665 100644 --- a/apps/backend/internal/orchestrator/event_handlers_initial_prompt_dedup_test.go +++ b/apps/backend/internal/orchestrator/event_handlers_initial_prompt_dedup_test.go @@ -158,7 +158,7 @@ func TestWorkflowAutoStartCreatedNonEmptyPromptPreservesQueuedHandoff(t *testing if err := fixture.svc.autoStartStepPrompt( context.Background(), fixture.taskID, fixture.session, fixture.step, - fixture.step.Prompt, false, true, + fixture.step.Prompt, false, true, nil, ); err != nil { t.Fatalf("autoStartStepPrompt returned error: %v", err) } @@ -228,7 +228,7 @@ func TestWorkflowAutoStartPlanModeOnlyPromptForCreatedSession(t *testing.T) { } if err := fixture.svc.autoStartStepPrompt( - context.Background(), fixture.taskID, fixture.session, fixture.step, "", true, true, + context.Background(), fixture.taskID, fixture.session, fixture.step, "", true, true, nil, ); err != nil { t.Fatalf("autoStartStepPrompt returned error: %v", err) } @@ -298,7 +298,7 @@ func TestWorkflowAutoStartAttachmentOnlyHandoffIsRecorded(t *testing.T) { if err := fixture.svc.autoStartStepPrompt( context.Background(), fixture.taskID, fixture.session, fixture.step, - "", false, true, + "", false, true, nil, ); err != nil { t.Fatalf("autoStartStepPrompt returned error: %v", err) } diff --git a/apps/backend/internal/orchestrator/event_handlers_step_completion.go b/apps/backend/internal/orchestrator/event_handlers_step_completion.go index 4511f907bb..bb728ca4d4 100644 --- a/apps/backend/internal/orchestrator/event_handlers_step_completion.go +++ b/apps/backend/internal/orchestrator/event_handlers_step_completion.go @@ -2,6 +2,7 @@ package orchestrator import ( "context" + "strings" "go.uber.org/zap" @@ -82,17 +83,26 @@ func (s *Service) recordAutoStepTransition(ctx context.Context, sessionID, fromS "signal_source": signal.Source, "signal_summary": signal.Summary, } + if handoff := strings.TrimSpace(signal.Handoff); handoff != "" { + metadata["signal_handoff"] = handoff + } + if blockers := strings.TrimSpace(signal.Blockers); blockers != "" { + metadata["signal_blockers"] = blockers + } } trigger := wfmodels.StepTransitionTriggerAutoComplete if len(triggers) > 0 && triggers[0] != "" { trigger = triggers[0] } if asyncRecorder, ok := s.stepHistoryRecorder.(asyncStepHistoryRecorder); ok { - asyncRecorder.EnqueueStepTransition(sessionID, fromStepID, toStepID, trigger, nil, metadata) - return + if asyncRecorder.EnqueueStepTransition(sessionID, fromStepID, toStepID, trigger, nil, metadata) { + return + } + // A full or closed worker must not discard a consumed signal's audit + // payload. Fall through to the bounded synchronous write below. } - // Test doubles can remain synchronous. Production workflow service uses the - // queue branch above. + // Test doubles remain synchronous, and production falls back here when its + // bounded worker cannot accept the row. writeCtx, cancel := context.WithTimeout(context.WithoutCancel(ctx), constants.StepHistoryWriteTimeout) defer cancel() if err := s.stepHistoryRecorder.CreateStepTransition( @@ -119,12 +129,14 @@ func (s *Service) recordManualStepTransition(ctx context.Context, sessionID, fro } // Test doubles can remain synchronous. Production workflow service uses the // queue branch below. + if asyncRecorder, ok := s.stepHistoryRecorder.(asyncStepHistoryRecorder); ok { + if asyncRecorder.EnqueueStepTransition(sessionID, fromStepID, toStepID, wfmodels.StepTransitionTriggerManual, nil, nil) { + return + } + // Fall through when the bounded worker is full or closed. + } writeCtx, cancel := context.WithTimeout(context.WithoutCancel(ctx), constants.StepHistoryWriteTimeout) defer cancel() - if asyncRecorder, ok := s.stepHistoryRecorder.(asyncStepHistoryRecorder); ok { - asyncRecorder.EnqueueStepTransition(sessionID, fromStepID, toStepID, wfmodels.StepTransitionTriggerManual, nil, nil) - return - } if err := s.stepHistoryRecorder.CreateStepTransition( writeCtx, sessionID, fromStepID, toStepID, wfmodels.StepTransitionTriggerManual, nil, nil, ); err != nil { diff --git a/apps/backend/internal/orchestrator/event_handlers_workflow.go b/apps/backend/internal/orchestrator/event_handlers_workflow.go index 8f8e038f19..06bf71ec9e 100644 --- a/apps/backend/internal/orchestrator/event_handlers_workflow.go +++ b/apps/backend/internal/orchestrator/event_handlers_workflow.go @@ -81,6 +81,15 @@ type taskMetadataKeySetterIfNoActiveSession interface { SetTaskMetadataKeyIfNoActiveSession(context.Context, string, string, interface{}) (bool, error) } +// taskMetadataCarryTaker is the compare-and-swap claim behind the +// completion-handoff carry token. A repository that lacks it degrades to +// today's behavior (no handoff delivered) rather than erroring. +type taskMetadataCarryTaker interface { + TakeTaskMetadataKeyIfDestinationStep( + ctx context.Context, taskID, key, expectedStepID, expectedStamp string, + ) (json.RawMessage, bool, error) +} + type lifecycleTaskMetadataLister interface { ListTasksWithMetadataKey(context.Context, string) ([]*models.Task, error) } @@ -402,6 +411,21 @@ func (s *Service) executeStepTransition(ctx context.Context, taskID, sessionID s // transition. task.WorkflowStepID = toStepID task.UpdatedAt = time.Now().UTC() + // Capture the completion signal before admission and carry its handoff on + // the same task snapshot. A queued destination can be promoted immediately + // after this write, so a post-commit metadata write would leave a race where + // the first prompt starts without its handoff. + var consumedSignal *models.PendingStepCompletionSignal + signalSession, signalErr := s.repo.GetTaskSession(ctx, sessionID) + if signalErr != nil { + s.logger.Warn("failed to load session for step handoff carry", + zap.String("session_id", sessionID), zap.Error(signalErr)) + } else if triggerOnEnter && signalSession != nil { + if signal, has := models.LoadPendingStepSignal(signalSession.Metadata); has && signal.StepID == fromStep.ID { + consumedSignal = &signal + } + setStepHandoffCarryMetadata(task, toStepID, consumedSignal) + } // executeStepTransition's two callers are always a genuine session turn: // on_turn_complete (triggerOnEnter=true) or on_turn_start (false). legacyTrigger := engine.TriggerOnTurnStart @@ -420,13 +444,14 @@ func (s *Service) executeStepTransition(ctx context.Context, taskID, sessionID s } queued := task.QueuedForStepID != "" - // Process on_exit only after the transition is durably admitted. Freshly - // load the session since the caller may not have it (legacy path). + // Process on_exit only after the transition is durably admitted. Reload the + // session so side effects use the same fresh snapshot as the old path; the + // earlier signal snapshot was needed only to make carry part of admission. exitSession, exitErr := s.repo.GetTaskSession(ctx, sessionID) if exitErr != nil { s.logger.Warn("failed to load session for on_exit", zap.String("session_id", sessionID), zap.Error(exitErr)) - } else { + } else if exitSession != nil { s.processOnExit(ctx, taskID, exitSession, fromStep) } @@ -447,26 +472,28 @@ func (s *Service) executeStepTransition(ctx context.Context, taskID, sessionID s if s.workflowStore != nil { s.workflowStore.pullNextTaskOnVacate(ctx, fromStep.ID, taskID) } - if queued { - s.setSessionWaitingForInput(ctx, taskID, sessionID) - return - } - // ADR 0015 — record the audit row before the pending signal (if any) - // is cleared below. Only the triggerOnEnter=true (legacy - // on_turn_complete) branch could have consumed a signal; the - // on_turn_start branch records with no signal metadata. - var consumedSignal *models.PendingStepCompletionSignal - if triggerOnEnter && exitSession != nil { - if signal, has := models.LoadPendingStepSignal(exitSession.Metadata); has && signal.StepID == fromStep.ID { - consumedSignal = &signal - } - } + // A queued transition still commits: the task's step already changed + // above, only entry into it is deferred until a queue promotion admits + // the task. So the audit row and any handoff carry token are captured + // here, before the queued check below returns — a later promotion + // dispatches through StartSessionForWorkflowStep, which claims the token + // itself and has no other way to learn one was ever written. Only the + // triggerOnEnter=true (legacy on_turn_complete) branch could have + // consumed a signal; the on_turn_start branch records with no signal + // metadata and never touches the token. trigger := wfmodels.StepTransitionTriggerTurnStart if triggerOnEnter { trigger = wfmodels.StepTransitionTriggerAutoComplete } s.recordAutoStepTransition(ctx, sessionID, fromStep.ID, toStepID, consumedSignal, trigger) + if queued { + if triggerOnEnter { + s.clearPendingStepSignalByID(ctx, sessionID) + } + s.setSessionWaitingForInput(ctx, taskID, sessionID) + return + } if triggerOnEnter { // ADR 0015 — clear any pending completion-signal bag for the @@ -3000,7 +3027,10 @@ func (s *Service) processOnEnter(ctx context.Context, taskID string, session *mo } s.setSessionWaitingForInput(ctx, taskID, sessionID, session) s.publishSessionWaitingEvent(ctx, taskID, sessionID, step.ID, session) - s.drainQueuedMessageForPromptableSession(ctx, sessionID) + // This step entry never reaches buildWorkflowEntryPrompt or + // launchAfterOnEnterDispatch (no on_enter actions, no profile switch), + // so a single-use claim helper covers it. + s.drainQueuedMessageForPromptableSessionWithHandoff(ctx, taskID, sessionID, step.ID, newStepHandoffOnce()) return } @@ -3041,6 +3071,10 @@ func (s *Service) launchAfterOnEnterDispatch( ) { sessionID := session.ID isPassthrough := s.agentManager.IsPassthroughSession(ctx, sessionID) + // One claim for this whole step entry: every branch and replacement + // launch below shares it, so a successful claim's text is reused rather + // than silently lost to a second, always-empty DB attempt. + handoffOnce := newStepHandoffOnce() var effectivePrompt string if hasAutoStart || (sessionSwitched && step.Prompt != "") { var err error @@ -3062,10 +3096,16 @@ func (s *Service) launchAfterOnEnterDispatch( // The empty workflow prompt is suppressed for an already-prompted // session, but a queued handoff may still be the next user input. // Drain it through the normal executor path so passthrough attachments - // are materialized and the handoff is not stranded in the queue. - s.drainQueuedMessageForPromptableSession(ctx, sessionID) + // are materialized and the handoff is not stranded in the queue. This + // branch still DISPATCHES, so it carries the completion handoff too. + s.drainQueuedMessageForPromptableSessionWithHandoff(ctx, taskID, sessionID, step.ID, handoffOnce) return } + // Claimed after the actionability decision above (effectivePrompt was + // non-blank), over content that excludes the handoff text. + effectivePrompt = appendStepHandoffToPrompt( + effectivePrompt, s.resolveStepHandoffText(ctx, handoffOnce, taskID, step.ID, true), + ) if err := s.autoStartPassthroughPrompt(ctx, taskID, session, step.Name, effectivePrompt); err != nil { s.logger.Error("failed to auto-start passthrough agent for step", zap.String("task_id", taskID), @@ -3081,38 +3121,11 @@ func (s *Service) launchAfterOnEnterDispatch( // When called from applyEngineTransition (on_turn_complete), processOnEnter // runs in a goroutine and the session is already WAITING_FOR_INPUT, so // autoStartStepPrompt sends the prompt directly via PromptTask. - if err := s.autoStartStepPrompt(ctx, taskID, session, step, effectivePrompt, hasPlanMode, true); err != nil { + if err := s.autoStartStepPrompt(ctx, taskID, session, step, effectivePrompt, hasPlanMode, true, handoffOnce); err != nil { if errors.Is(err, errWorkflowAutoStartSessionTerminalized) { - if workflowAutoStartWasCancelled(err) { - s.logger.Info("workflow auto-start cancelled before dispatch; not creating replacement", - zap.String("task_id", taskID), zap.String("session_id", sessionID)) - return - } - s.logger.Info("creating fresh workflow session after reused session terminalized", - zap.String("task_id", taskID), zap.String("session_id", sessionID)) - replacement, replacementErr := s.createNewSessionForStep( - ctx, taskID, session, session.AgentProfileID, + s.replaceTerminalizedAutoStartSession( + ctx, taskID, taskDescription, session, step, isPassthrough, hasPlanMode, handoffOnce, err, ) - if replacementErr != nil { - s.logger.Error("failed to create replacement after reused session terminalized", - zap.String("task_id", taskID), zap.String("session_id", sessionID), zap.Error(replacementErr)) - return - } - replacementPrompt, promptErr := s.buildWorkflowEntryPrompt( - ctx, taskDescription, step, taskID, replacement.ID, isPassthrough, - ) - if promptErr != nil { - s.handleWorkflowEntryPromptError(ctx, taskID, replacement, step, promptErr) - return - } - if replacementErr = s.autoStartStepPrompt( - ctx, taskID, replacement, step, replacementPrompt, hasPlanMode, true, - ); replacementErr != nil { - s.logger.Error("failed to auto-start replacement after reused session terminalized", - zap.String("task_id", taskID), zap.String("session_id", replacement.ID), zap.Error(replacementErr)) - s.setSessionWaitingForInput(ctx, taskID, replacement.ID, replacement) - s.publishSessionWaitingEvent(ctx, taskID, replacement.ID, step.ID, replacement) - } return } s.logger.Error("failed to auto-start agent for step", @@ -3179,7 +3192,7 @@ func (s *Service) launchAfterOnEnterDispatch( return } if replacementErr = s.autoStartStepPrompt( - asyncCtx, taskID, replacement, step, replacementPrompt, planMode, true, + asyncCtx, taskID, replacement, step, replacementPrompt, planMode, true, handoffOnce, ); replacementErr != nil { s.logger.Error("failed to auto-start replacement after terminalized profile switch", zap.String("task_id", taskID), zap.String("session_id", replacement.ID), zap.Error(replacementErr)) @@ -3191,7 +3204,7 @@ func (s *Service) launchAfterOnEnterDispatch( lock.Unlock() release() - err := s.autoStartStepPrompt(asyncCtx, taskID, fresh, step, effectivePrompt, planMode, true) + err := s.autoStartStepPrompt(asyncCtx, taskID, fresh, step, effectivePrompt, planMode, true, handoffOnce) if err != nil { if errors.Is(err, errWorkflowAutoStartSessionTerminalized) { if workflowAutoStartWasCancelled(err) { @@ -3217,7 +3230,7 @@ func (s *Service) launchAfterOnEnterDispatch( return } if replacementErr = s.autoStartStepPrompt( - asyncCtx, taskID, replacement, step, replacementPrompt, planMode, true, + asyncCtx, taskID, replacement, step, replacementPrompt, planMode, true, handoffOnce, ); replacementErr != nil { s.logger.Error("failed to auto-start replacement after terminalized dispatch", zap.String("task_id", taskID), zap.String("session_id", replacement.ID), zap.Error(replacementErr)) @@ -3232,7 +3245,7 @@ func (s *Service) launchAfterOnEnterDispatch( zap.Error(err)) s.setSessionWaitingForInput(asyncCtx, taskID, sessionID, fresh) s.publishSessionWaitingEvent(asyncCtx, taskID, sessionID, stepID, fresh) - s.drainQueuedMessageForPromptableSession(asyncCtx, sessionID) + s.drainQueuedMessageForPromptableSessionWithHandoff(asyncCtx, taskID, sessionID, stepID, handoffOnce) } }() return @@ -3246,12 +3259,55 @@ func (s *Service) launchAfterOnEnterDispatch( // so user-queued messages would otherwise stick forever on transitions to // steps without auto_start_agent (e.g. Review). Drain here to match the // pre-#677 behavior where handleAgentReady always drained after returning - // from inline processOnEnter. - s.drainQueuedMessageForPromptableSession(ctx, sessionID) + // from inline processOnEnter. This is the ordinary no-on_enter-actions + // step shape, so it carries the completion handoff too. + s.drainQueuedMessageForPromptableSessionWithHandoff(ctx, taskID, sessionID, step.ID, handoffOnce) } } +// replaceTerminalizedAutoStartSession handles the ACP auto-start path's +// errWorkflowAutoStartSessionTerminalized outcome: an explicit cancellation +// stays terminal, otherwise a fresh replacement session is created and +// launched with the same shared handoffOnce so the completion handoff (if any +// was already claimed) is not silently dropped. +func (s *Service) replaceTerminalizedAutoStartSession( + ctx context.Context, taskID, taskDescription string, session *models.TaskSession, step *wfmodels.WorkflowStep, + isPassthrough, hasPlanMode bool, handoffOnce *stepHandoffOnce, err error, +) { + sessionID := session.ID + if workflowAutoStartWasCancelled(err) { + s.logger.Info("workflow auto-start cancelled before dispatch; not creating replacement", + zap.String("task_id", taskID), zap.String("session_id", sessionID)) + return + } + s.logger.Info("creating fresh workflow session after reused session terminalized", + zap.String("task_id", taskID), zap.String("session_id", sessionID)) + replacement, replacementErr := s.createNewSessionForStep( + ctx, taskID, session, session.AgentProfileID, + ) + if replacementErr != nil { + s.logger.Error("failed to create replacement after reused session terminalized", + zap.String("task_id", taskID), zap.String("session_id", sessionID), zap.Error(replacementErr)) + return + } + replacementPrompt, promptErr := s.buildWorkflowEntryPrompt( + ctx, taskDescription, step, taskID, replacement.ID, isPassthrough, + ) + if promptErr != nil { + s.handleWorkflowEntryPromptError(ctx, taskID, replacement, step, promptErr) + return + } + if replacementErr = s.autoStartStepPrompt( + ctx, taskID, replacement, step, replacementPrompt, hasPlanMode, true, handoffOnce, + ); replacementErr != nil { + s.logger.Error("failed to auto-start replacement after reused session terminalized", + zap.String("task_id", taskID), zap.String("session_id", replacement.ID), zap.Error(replacementErr)) + s.setSessionWaitingForInput(ctx, taskID, replacement.ID, replacement) + s.publishSessionWaitingEvent(ctx, taskID, replacement.ID, step.ID, replacement) + } +} + func (s *Service) handleWorkflowEntryPromptError( ctx context.Context, taskID string, @@ -4000,13 +4056,14 @@ func (s *Service) handleCreatedAutoStartLaunchFailure( origin workflowMessageOrigin, references []v1.EntityReference, takenMsg *messagequeue.QueuedMessage, + handoffText string, ) { promptQueued := false if shouldQueueIfBusy && (isAgentAlreadyRunningError(launchErr) || isSessionBusyError(launchErr) || isTransientPromptError(launchErr)) { if queueErr := s.queueAutoStartPrompt( ctx, taskID, sessionID, prompt, planMode, - attachments, origin, userMessageRecorded, references, + attachments, origin, userMessageRecorded, references, handoffText, ); queueErr != nil { s.logger.Warn("failed to queue auto-start prompt after launch failure", zap.String("task_id", taskID), @@ -4022,11 +4079,18 @@ func (s *Service) handleCreatedAutoStartLaunchFailure( } } +// handoffOnce claims the completion-handoff carry token addressed to step, +// through the caller's shared per-step-entry stepHandoffOnce, so a +// replacement launch after this attempt reuses the same handoff text. Pass +// nil when the caller is not part of a step-entry dispatch (e.g. tests +// exercising this function directly) — resolveStepHandoffText treats a nil +// once as "never claim". func (s *Service) autoStartStepPrompt( ctx context.Context, taskID string, session *models.TaskSession, step *wfmodels.WorkflowStep, prompt string, planMode bool, shouldQueueIfBusy bool, + handoffOnce *stepHandoffOnce, ) error { sessionID := session.ID origin := workflowOriginFromStep(step) @@ -4037,17 +4101,30 @@ func (s *Service) autoStartStepPrompt( // content first, hand-off after — and forward attachments verbatim. // Track the original message so terminal failure paths can restore it // instead of dropping the user's prompt or attachments on the floor. - takenMsg, mergedPrompt, attachments, references := s.takeAndMergeHandoffMessage(ctx, sessionID, prompt) + takenMsg, mergedPrompt, attachments, references, queuedHandoff := s.takeAndMergeHandoffMessage(ctx, sessionID, prompt) prompt = mergedPrompt agentPrompt := AppendEntityReferenceContext(prompt, references) effectiveAgentPrompt := s.effectivePromptForSession(sessionID, agentPrompt, planMode, session) - if strings.TrimSpace(effectiveAgentPrompt) == "" && len(attachments) == 0 { + if strings.TrimSpace(effectiveAgentPrompt) == "" && len(attachments) == 0 && queuedHandoff == "" { // The session is already running after ensureSessionRunning; no prompt // means we leave it waiting for the first user message rather than // auto-starting. Attachment-only handoffs are admitted below. return nil } + // The completion-handoff carry token is claimed only after the + // actionability decision above, and over content that excludes the + // handoff text, then appended last, after the queued hand-off already + // merged into agentPrompt/effectiveAgentPrompt above. + handoffText := s.resolveStepHandoffText(ctx, handoffOnce, taskID, step.ID, true) + if queuedHandoff != "" { + agentPrompt = appendStepHandoffToPrompt(agentPrompt, queuedHandoff) + effectiveAgentPrompt = appendStepHandoffToPrompt(effectiveAgentPrompt, queuedHandoff) + } + agentPrompt = appendStepHandoffToPrompt(agentPrompt, handoffText) + effectiveAgentPrompt = appendStepHandoffToPrompt(effectiveAgentPrompt, handoffText) + handoffForQueue := joinStepHandoffText(queuedHandoff, handoffText) + // requeueTaken puts the original queued message back so a manual retry can // pick it up. Skip when shouldQueueIfBusy successfully re-queued the // concatenated prompt (the content is already preserved there). @@ -4062,7 +4139,7 @@ func (s *Service) autoStartStepPrompt( // userMessageRecorded=false: recordAutoStartMessage has not run yet — // the drain side (executeQueuedMessage) is responsible for inserting // the chat-history row. - queued, err := s.queueAutoStartPromptIfRunning(ctx, taskID, session, prompt, planMode, attachments, origin, false, references) + queued, err := s.queueAutoStartPromptIfRunning(ctx, taskID, session, prompt, planMode, attachments, origin, false, references, handoffForQueue) if err != nil { requeueTaken() return err @@ -4195,7 +4272,7 @@ func (s *Service) autoStartStepPrompt( s.handleCreatedAutoStartLaunchFailure( ctx, taskID, sessionID, stepName, prompt, err, planMode, shouldQueueIfBusy, userMsgRecorded, - attachments, origin, references, takenMsg, + attachments, origin, references, takenMsg, handoffForQueue, ) } return err @@ -4205,6 +4282,15 @@ func (s *Service) autoStartStepPrompt( for attempt := 1; attempt <= maxRetryAttempts; attempt++ { _, err := s.promptTask(ctx, taskID, sessionID, dispatchPrompt, "", planMode, attachments, false, promptTaskOptions{ requireNonterminalSession: true, + // dispatchPrompt is already fully composed for this step entry + // (handoff included, see the ErrExecutionNotFound branch below): + // if promptTask's own internal ErrExecutionNotFound recovery fires + // first (ordinary lazy-resume race), it must use the same + // composed-prompt seam rather than recomposing from the + // destination step's own template and discarding the handoff. + promptAlreadyComposed: true, + fallbackLaunchPrompt: recordedPrompt, + fallbackRetryPrompt: dispatchPrompt, }) if err == nil { return nil @@ -4218,15 +4304,17 @@ func (s *Service) autoStartStepPrompt( // the lifecycle manager no longer has (e.g. the post-resume agent // process failed to start and runAgentProcessAsync removed it). The // session's stored AgentExecutionID is now stale. Recover by clearing - // it and routing through StartCreatedSession for a fresh launch — the - // prompt is baked into LaunchPreparedSession so we don't lose it. + // it and relaunching fresh through the composed-prompt seam — recordedPrompt + // and dispatchPrompt are already fully composed for this step entry + // (handoff included), so the fallback must not let StartCreatedSession + // recompose them from the destination step's own template. if errors.Is(err, executor.ErrExecutionNotFound) { s.logger.Warn("auto-start: PromptTask hit missing execution; falling back to fresh launch", zap.String("task_id", taskID), zap.String("session_id", sessionID), zap.String("step_name", stepName)) return s.fallbackFreshLaunchOnMissingExecution( - ctx, taskID, sessionID, recordedPrompt, planMode, takenMsg, attachments, references, + ctx, taskID, sessionID, recordedPrompt, true, dispatchPrompt, planMode, takenMsg, attachments, references, ) } @@ -4237,7 +4325,7 @@ func (s *Service) autoStartStepPrompt( // chat row was successfully inserted above; a failed write passes false, // letting the drain re-attempt insertion. if isAgentAlreadyRunningError(err) && shouldQueueIfBusy { - if queueErr := s.queueAutoStartPrompt(ctx, taskID, sessionID, prompt, planMode, attachments, origin, userMsgRecorded, references); queueErr != nil { + if queueErr := s.queueAutoStartPrompt(ctx, taskID, sessionID, prompt, planMode, attachments, origin, userMsgRecorded, references, handoffForQueue); queueErr != nil { requeueTaken() return queueErr } @@ -4252,7 +4340,7 @@ func (s *Service) autoStartStepPrompt( if shouldQueueIfBusy { // Pass userMsgRecorded so the drain skips CreateUserMessage only when // the chat row was successfully inserted above by recordAutoStartMessage. - if queueErr := s.queueAutoStartPrompt(ctx, taskID, sessionID, prompt, planMode, attachments, origin, userMsgRecorded, references); queueErr != nil { + if queueErr := s.queueAutoStartPrompt(ctx, taskID, sessionID, prompt, planMode, attachments, origin, userMsgRecorded, references, handoffForQueue); queueErr != nil { requeueTaken() return queueErr } @@ -4279,12 +4367,21 @@ func (s *Service) autoStartStepPrompt( // fallbackFreshLaunchOnMissingExecution recovers from a PromptTask that returned // ErrExecutionNotFound — the session's stored AgentExecutionID points at an // execution the lifecycle manager doesn't have, so the resume path is dead. -// Clear the stale ID, flip state to CREATED, and route through StartCreatedSession -// (which uses LaunchPreparedSession with the prompt baked in — bypassing resume). -// On further failure, the queued message is restored so a manual retry recovers it. +// Clear the stale ID, flip state to CREATED, and relaunch with prompt. +// promptAlreadyComposed routes the relaunch through the composed-prompt seam +// (startCreatedSessionWithComposedPrompt, with retryPrompt as its raw dispatch +// value) instead of the public StartCreatedSession, so a caller that already +// composed prompt itself (e.g. appending a claimed step handoff) is not +// recomposed from the destination step's own template — which discards +// everything it was passed when that template lacks {{task_prompt}}. Callers +// that have not composed the prompt pass promptAlreadyComposed=false and an +// empty retryPrompt. On further failure, the queued message is restored so a +// manual retry recovers it. func (s *Service) fallbackFreshLaunchOnMissingExecution( ctx context.Context, taskID, sessionID, prompt string, + promptAlreadyComposed bool, + retryPrompt string, planMode bool, takenMsg *messagequeue.QueuedMessage, attachments []v1.MessageAttachment, @@ -4316,14 +4413,23 @@ func (s *Service) fallbackFreshLaunchOnMissingExecution( return err } - if _, err := s.StartCreatedSession( - ctx, taskID, sessionID, fresh.AgentProfileID, - prompt, true, planMode, true, attachments, references, - ); err != nil { + var launchErr error + if promptAlreadyComposed { + _, launchErr = s.startCreatedSessionWithComposedPrompt( + ctx, taskID, sessionID, fresh.AgentProfileID, + prompt, retryPrompt, true, planMode, true, attachments, references, + ) + } else { + _, launchErr = s.StartCreatedSession( + ctx, taskID, sessionID, fresh.AgentProfileID, + prompt, true, planMode, true, attachments, references, + ) + } + if launchErr != nil { s.logger.Error("auto-start fallback: fresh launch failed", - zap.String("session_id", sessionID), zap.Error(err)) + zap.String("session_id", sessionID), zap.Error(launchErr)) requeue() - return err + return launchErr } return nil } @@ -4378,13 +4484,17 @@ func (s *Service) resetSessionForFreshFallback( // the original queued message (so terminal failure paths can re-queue it via // requeueMessage), merged prompt, converted attachments, and structurally // normalized references. -func (s *Service) takeAndMergeHandoffMessage(ctx context.Context, sessionID, basePrompt string) (*messagequeue.QueuedMessage, string, []v1.MessageAttachment, []v1.EntityReference) { +func (s *Service) takeAndMergeHandoffMessage(ctx context.Context, sessionID, basePrompt string) (*messagequeue.QueuedMessage, string, []v1.MessageAttachment, []v1.EntityReference, string) { if s.messageQueue == nil { - return nil, basePrompt, nil, nil + return nil, basePrompt, nil, nil, "" } msg, ok := s.messageQueue.TakeQueuedIfAutoRun(ctx, sessionID) - if !ok || msg == nil || (msg.Content == "" && len(msg.Attachments) == 0) { - return nil, basePrompt, nil, nil + queuedHandoff := "" + if msg != nil { + queuedHandoff = stepHandoffFromQueuedMetadata(msg.Metadata) + } + if !ok || msg == nil || (msg.Content == "" && len(msg.Attachments) == 0 && queuedHandoff == "") { + return nil, basePrompt, nil, nil, "" } prompt := basePrompt if msg.Content != "" { @@ -4407,7 +4517,7 @@ func (s *Service) takeAndMergeHandoffMessage(ctx context.Context, sessionID, bas } s.publishQueueStatusEvent(ctx, sessionID) references := entityrefs.NormalizePersisted(msg.Metadata[messagequeue.MetadataEntityReferences]) - return msg, prompt, attachments, references + return msg, prompt, attachments, references, queuedHandoff } // recordAutoStartMessage creates a user message for a workflow auto-start prompt @@ -4469,11 +4579,12 @@ func (s *Service) queueAutoStartPromptIfRunning( origin workflowMessageOrigin, userMessageRecorded bool, references []v1.EntityReference, + handoffText string, ) (bool, error) { if session.State != models.TaskSessionStateRunning && session.State != models.TaskSessionStateStarting { return false, nil } - if err := s.queueAutoStartPrompt(ctx, taskID, session.ID, prompt, planMode, attachments, origin, userMessageRecorded, references); err != nil { + if err := s.queueAutoStartPrompt(ctx, taskID, session.ID, prompt, planMode, attachments, origin, userMessageRecorded, references, handoffText); err != nil { return false, err } return true, nil @@ -4508,7 +4619,10 @@ func toQueuedAttachments(attachments []v1.MessageAttachment) []messagequeue.Mess // Callers that queue BEFORE recordAutoStartMessage runs (e.g. // queueAutoStartPromptIfRunning's early-busy path) must pass false. Prompt // content stays raw here; references remain metadata until drain-time context -// is built, preventing duplicate system blocks across retries. +// is built, preventing duplicate system blocks across retries. handoffText, if +// non-empty, is a completion handoff already claimed for this step entry; it +// rides the same way, so a dispatch deferred through this queue still appends +// it last, after entity-reference expansion, at actual dispatch time. func (s *Service) queueAutoStartPrompt( ctx context.Context, taskID, sessionID, prompt string, @@ -4517,6 +4631,7 @@ func (s *Service) queueAutoStartPrompt( origin workflowMessageOrigin, userMessageRecorded bool, references []v1.EntityReference, + handoffText string, ) error { if s.messageQueue == nil { return fmt.Errorf("message queue is not configured") @@ -4525,6 +4640,9 @@ func (s *Service) queueAutoStartPrompt( if userMessageRecorded { meta[metaKeyUserMessageRecorded] = true } + if handoffText != "" { + meta[messagequeue.MetadataStepHandoff] = handoffText + } _, err := s.messageQueue.QueueMessageWithMetadata( ctx, sessionID, diff --git a/apps/backend/internal/orchestrator/event_handlers_workflow_moved_test.go b/apps/backend/internal/orchestrator/event_handlers_workflow_moved_test.go index 3804a8f9ca..282d943724 100644 --- a/apps/backend/internal/orchestrator/event_handlers_workflow_moved_test.go +++ b/apps/backend/internal/orchestrator/event_handlers_workflow_moved_test.go @@ -720,7 +720,7 @@ func TestHandleTaskMovedWithSession(t *testing.T) { _ = repo.UpdateTaskSession(ctx, session) svc := createTestService(repo, newMockStepGetter(), newMockTaskRepo()) - queued, err := svc.queueAutoStartPromptIfRunning(ctx, "t1", session, "prompt", false, nil, workflowMessageOrigin{}, false, nil) + queued, err := svc.queueAutoStartPromptIfRunning(ctx, "t1", session, "prompt", false, nil, workflowMessageOrigin{}, false, nil, "") if err != nil { t.Fatalf("unexpected error: %v", err) } diff --git a/apps/backend/internal/orchestrator/event_handlers_workflow_profile_test.go b/apps/backend/internal/orchestrator/event_handlers_workflow_profile_test.go index cbe8d20e96..1781246cbd 100644 --- a/apps/backend/internal/orchestrator/event_handlers_workflow_profile_test.go +++ b/apps/backend/internal/orchestrator/event_handlers_workflow_profile_test.go @@ -223,7 +223,7 @@ func TestAutoStartStepPrompt_OfficeWithoutRuntimeEnvFailsClosed(t *testing.T) { ) prompt := spoofedReference + "\n\n" + sysprompt.InjectOfficeContext("wrong-task", "wrong-session", "Do the work") - err = svc.autoStartStepPrompt(ctx, "task-office", session, step, prompt, false, false) + err = svc.autoStartStepPrompt(ctx, "task-office", session, step, prompt, false, false, nil) if err == nil || !strings.Contains(err.Error(), "office tasks must be started through Office") { t.Fatalf("autoStartStepPrompt error = %v, want Office scheduler guard", err) } @@ -278,7 +278,7 @@ func TestAutoStartStepPrompt_ResetContextInjectsCompletionContractForReusedSessi messages := &mockMessageCreator{} svc := createTestServiceWithScheduler(repo, stepGetter, newMockTaskRepo(), agentMgr) svc.messageCreator = messages - err = svc.autoStartStepPrompt(ctx, "task-reused", session, step, "Review the change", false, false) + err = svc.autoStartStepPrompt(ctx, "task-reused", session, step, "Review the change", false, false, nil) if err != nil { t.Fatalf("autoStartStepPrompt returned error: %v", err) } @@ -321,7 +321,7 @@ func TestAutoStartStepPrompt_ResetContextPreservesOfficeModeForReusedSession(t * messages := &mockMessageCreator{} svc := createTestServiceWithScheduler(repo, stepGetter, newMockTaskRepo(), agentMgr) svc.messageCreator = messages - if err := svc.autoStartStepPrompt(ctx, task.ID, session, step, "Run the Office task", false, false); err != nil { + if err := svc.autoStartStepPrompt(ctx, task.ID, session, step, "Run the Office task", false, false, nil); err != nil { t.Fatalf("autoStartStepPrompt returned error: %v", err) } if len(messages.userMessages) != 1 { diff --git a/apps/backend/internal/orchestrator/event_handlers_workflow_prompt_claim_test.go b/apps/backend/internal/orchestrator/event_handlers_workflow_prompt_claim_test.go index e873354c5a..2daeb46e53 100644 --- a/apps/backend/internal/orchestrator/event_handlers_workflow_prompt_claim_test.go +++ b/apps/backend/internal/orchestrator/event_handlers_workflow_prompt_claim_test.go @@ -240,7 +240,7 @@ func TestWorkflowAutoStartRejectsSessionTerminalizedBeforeResume(t *testing.T) { } errCh := make(chan error, 1) go func() { - errCh <- svc.autoStartStepPrompt(ctx, session.TaskID, session, &wfmodels.WorkflowStep{}, "review the task", false, false) + errCh <- svc.autoStartStepPrompt(ctx, session.TaskID, session, &wfmodels.WorkflowStep{}, "review the task", false, false, nil) }() <-barrierRepo.claimReached @@ -290,7 +290,7 @@ func TestWorkflowAutoStartRollsBackPromptClaimWhenPostClaimReloadFails(t *testin repo: failingRepo, } - err = svc.autoStartStepPrompt(ctx, session.TaskID, session, &wfmodels.WorkflowStep{}, "review the task", false, false) + err = svc.autoStartStepPrompt(ctx, session.TaskID, session, &wfmodels.WorkflowStep{}, "review the task", false, false, nil) if !errors.Is(err, reloadErr) { t.Fatalf("auto-start error = %v, want post-claim reload error", err) } @@ -348,7 +348,7 @@ func TestWorkflowAutoStartRollsBackPromptClaimWhenTerminalizedAfterClaim(t *test errCh := make(chan error, 1) go func() { - errCh <- svc.autoStartStepPrompt(ctx, session.TaskID, session, &wfmodels.WorkflowStep{}, "review the task", false, false) + errCh <- svc.autoStartStepPrompt(ctx, session.TaskID, session, &wfmodels.WorkflowStep{}, "review the task", false, false, nil) }() <-barrierRepo.claimReached @@ -528,7 +528,7 @@ func TestWorkflowAutoStartReleasesTerminalGuardAfterPromptAdmission(t *testing.T svc.executor = executor.NewExecutor(agentMgr, repo, testLogger(), executor.ExecutorConfig{}) errCh := make(chan error, 1) go func() { - errCh <- svc.autoStartStepPrompt(ctx, session.TaskID, session, &wfmodels.WorkflowStep{}, "review the task", false, false) + errCh <- svc.autoStartStepPrompt(ctx, session.TaskID, session, &wfmodels.WorkflowStep{}, "review the task", false, false, nil) }() <-agentMgr.dispatched @@ -618,7 +618,7 @@ func TestWorkflowAutoStartCreatedTerminalizedGuard(t *testing.T) { errCh := make(chan error, 1) go func() { - errCh <- svc.autoStartStepPrompt(ctx, session.TaskID, session, step, "review the task", false, false) + errCh <- svc.autoStartStepPrompt(ctx, session.TaskID, session, step, "review the task", false, false, nil) }() <-barrierRepo.lockAcquired diff --git a/apps/backend/internal/orchestrator/event_handlers_workflow_reset_quiescence_test.go b/apps/backend/internal/orchestrator/event_handlers_workflow_reset_quiescence_test.go index 80f6541e2d..89b724e740 100644 --- a/apps/backend/internal/orchestrator/event_handlers_workflow_reset_quiescence_test.go +++ b/apps/backend/internal/orchestrator/event_handlers_workflow_reset_quiescence_test.go @@ -199,7 +199,7 @@ func TestResetAgentContext_ActiveTurnAllowsSuccessorPrompt(t *testing.T) { }}, } if err := svc.autoStartStepPrompt( - context.Background(), "task1", resetSession, step, "successor prompt", false, false, + context.Background(), "task1", resetSession, step, "successor prompt", false, false, nil, ); err != nil { t.Fatalf("auto-start successor prompt: %v", err) } diff --git a/apps/backend/internal/orchestrator/fallback_fresh_launch_handoff_test.go b/apps/backend/internal/orchestrator/fallback_fresh_launch_handoff_test.go new file mode 100644 index 0000000000..145e56322f --- /dev/null +++ b/apps/backend/internal/orchestrator/fallback_fresh_launch_handoff_test.go @@ -0,0 +1,72 @@ +package orchestrator + +import ( + "context" + "strings" + "testing" + + "github.com/kandev/kandev/internal/orchestrator/executor" + "github.com/kandev/kandev/internal/task/models" + wfmodels "github.com/kandev/kandev/internal/workflow/models" + v1 "github.com/kandev/kandev/pkg/api/v1" + "github.com/stretchr/testify/require" +) + +// TestFallbackFreshLaunch_ComposedPromptSurvivesStepRecomposition covers the +// ErrExecutionNotFound recovery path from autoStartStepPrompt: when the +// caller has already composed the dispatch prompt (appending a claimed step +// handoff), the fresh launch must not let StartCreatedSession's own workflow +// step recomposition discard it. A destination step Prompt template with no +// {{task_prompt}} placeholder replaces any base prompt during recomposition +// (see TestApplyWorkflowAndPlanMode_KeepsWorkflowPromptVisibleWhenStepEnablesPlanMode +// in workflow_prompt_test.go), so promptAlreadyComposed must route around +// that seam entirely instead of losing the handoff. +func TestFallbackFreshLaunch_ComposedPromptSurvivesStepRecomposition(t *testing.T) { + ctx := context.Background() + const ( + taskID = "task-fallback-handoff" + sessionID = "session-fallback-handoff" + stepID = "step-next" + handoff = "watch out for the flaky test" + ) + repo := setupTestRepo(t) + seedTaskAndSession(t, repo, taskID, sessionID, models.TaskSessionStateWaitingForInput) + dbTask, err := repo.GetTask(ctx, taskID) + require.NoError(t, err) + dbTask.WorkflowStepID = stepID + require.NoError(t, repo.UpdateTask(ctx, dbTask)) + session, err := repo.GetTaskSession(ctx, sessionID) + require.NoError(t, err) + session.AgentProfileID = "profile-fallback" + require.NoError(t, repo.UpdateTaskSession(ctx, session)) + + stepGetter := newMockStepGetter() + stepGetter.steps[stepID] = &wfmodels.WorkflowStep{ + ID: stepID, WorkflowID: "wf1", Name: "Next", + Prompt: "Recomposed step instructions.", + } + taskRepo := newMockTaskRepo() + taskRepo.tasks[taskID] = &v1.Task{ID: taskID, Title: "Test Task", State: v1.TaskStateInProgress} + + var launchedDescription string + agentMgr := &mockAgentManager{ + repoForExecutionLookup: repo, + launchAgentFunc: func(_ context.Context, req *executor.LaunchAgentRequest) (*executor.LaunchAgentResponse, error) { + launchedDescription = req.TaskDescription + return &executor.LaunchAgentResponse{AgentExecutionID: "exec-fresh"}, nil + }, + } + svc := createTestServiceWithScheduler(repo, stepGetter, taskRepo, agentMgr) + svc.messageCreator = &mockMessageCreator{} + + composedPrompt := "Run the next workflow step.\n\n" + stepHandoffPromptHeading + "\n\n" + handoff + + err = svc.fallbackFreshLaunchOnMissingExecution( + ctx, taskID, sessionID, composedPrompt, true, composedPrompt, false, nil, nil, nil, + ) + require.NoError(t, err) + require.Contains(t, launchedDescription, handoff, + "the already-composed prompt (with the claimed handoff) must survive the fresh launch") + require.NotEqual(t, "Recomposed step instructions.", strings.TrimSpace(launchedDescription), + "promptAlreadyComposed must skip StartCreatedSession's own step-template recomposition") +} diff --git a/apps/backend/internal/orchestrator/messagequeue/send_now.go b/apps/backend/internal/orchestrator/messagequeue/send_now.go index e36aa0762a..b1b070b71d 100644 --- a/apps/backend/internal/orchestrator/messagequeue/send_now.go +++ b/apps/backend/internal/orchestrator/messagequeue/send_now.go @@ -140,6 +140,7 @@ func BuildSendNowEnvelope(entries []QueuedMessage) (*QueuedMessage, error) { seenReferences := make(map[string]struct{}) references := make([]apiv1.EntityReference, 0) sources := make([]map[string]interface{}, 0, len(entries)) + var handoffText string for _, entry := range entries { if entry.Content != "" { @@ -155,6 +156,12 @@ func BuildSendNowEnvelope(entries []QueuedMessage) (*QueuedMessage, error) { references = append(references, reference) } + if handoffText == "" { + if text, ok := entry.Metadata[MetadataStepHandoff].(string); ok && text != "" { + handoffText = text + } + } + sources = append(sources, map[string]interface{}{ "id": entry.ID, "task_id": entry.TaskID, @@ -172,6 +179,11 @@ func BuildSendNowEnvelope(entries []QueuedMessage) (*QueuedMessage, error) { } else { metadata[MetadataEntityReferences] = references } + if handoffText == "" { + delete(metadata, MetadataStepHandoff) + } else { + metadata[MetadataStepHandoff] = handoffText + } metadata[MetadataSendNowSources] = sources return &QueuedMessage{ diff --git a/apps/backend/internal/orchestrator/messagequeue/send_now_test.go b/apps/backend/internal/orchestrator/messagequeue/send_now_test.go index 1cf8bca525..f098ef79ed 100644 --- a/apps/backend/internal/orchestrator/messagequeue/send_now_test.go +++ b/apps/backend/internal/orchestrator/messagequeue/send_now_test.go @@ -64,6 +64,52 @@ func TestBuildSendNowEnvelopeAggregatesInFIFOOrder(t *testing.T) { } } +func TestBuildSendNowEnvelopeCarriesHandoffFromNonHeadEntry(t *testing.T) { + queuedAt := time.Date(2026, time.January, 1, 12, 0, 0, 0, time.UTC) + entries := []QueuedMessage{ + { + ID: "first", SessionID: "session-1", TaskID: "task-1", Position: 10, + Content: "user message", QueuedAt: queuedAt, QueuedBy: QueuedByUser, + Metadata: map[string]interface{}{"origin": "user-input"}, + }, + { + ID: "second", SessionID: "session-1", TaskID: "task-1", Position: 20, + Content: "workflow auto-start", QueuedAt: queuedAt.Add(time.Minute), QueuedBy: QueuedByWorkflow, + Metadata: map[string]interface{}{MetadataStepHandoff: "claimed handoff text"}, + }, + } + + envelope, err := BuildSendNowEnvelope(entries) + if err != nil { + t.Fatalf("BuildSendNowEnvelope() error = %v", err) + } + if got, ok := envelope.Metadata[MetadataStepHandoff].(string); !ok || got != "claimed handoff text" { + t.Fatalf("envelope handoff = %#v, want the second entry's claimed handoff text", envelope.Metadata[MetadataStepHandoff]) + } +} + +func TestBuildSendNowEnvelopeOmitsHandoffWhenNoEntryCarriesOne(t *testing.T) { + queuedAt := time.Date(2026, time.January, 1, 12, 0, 0, 0, time.UTC) + entries := []QueuedMessage{ + { + ID: "first", SessionID: "session-1", TaskID: "task-1", Position: 10, + Content: "user message", QueuedAt: queuedAt, QueuedBy: QueuedByUser, + }, + { + ID: "second", SessionID: "session-1", TaskID: "task-1", Position: 20, + Content: "another message", QueuedAt: queuedAt.Add(time.Minute), QueuedBy: QueuedByUser, + }, + } + + envelope, err := BuildSendNowEnvelope(entries) + if err != nil { + t.Fatalf("BuildSendNowEnvelope() error = %v", err) + } + if _, ok := envelope.Metadata[MetadataStepHandoff]; ok { + t.Fatalf("envelope handoff = %#v, want absent", envelope.Metadata[MetadataStepHandoff]) + } +} + func TestBuildSendNowEnvelopeAllowsAttachmentOnlyEntries(t *testing.T) { entries := []QueuedMessage{ {ID: "first", SessionID: "session-1", Position: 1, Attachments: []MessageAttachment{{Data: "aA==", SizeBytes: 1}}}, diff --git a/apps/backend/internal/orchestrator/messagequeue/types.go b/apps/backend/internal/orchestrator/messagequeue/types.go index 6a4c8a576c..aff4206abb 100644 --- a/apps/backend/internal/orchestrator/messagequeue/types.go +++ b/apps/backend/internal/orchestrator/messagequeue/types.go @@ -46,6 +46,13 @@ const MetadataCoalesceKey = "coalesce_key" // queued message. const MetadataEntityReferences = "entity_references" +// MetadataStepHandoff carries a completion-handoff carry token's claimed text +// for a queued workflow auto-start prompt, so a dispatch path that defers +// delivery through the queue (rather than sending it directly) still appends +// the handoff at actual dispatch time, after entity-reference context, rather +// than losing it at claim time or appending it out of order. +const MetadataStepHandoff = "step_handoff" + // MetadataContextFiles carries path/name references and optional directory // identity for queued user messages. const MetadataContextFiles = "context_files" diff --git a/apps/backend/internal/orchestrator/prompt_dispatch_failure_handoff_test.go b/apps/backend/internal/orchestrator/prompt_dispatch_failure_handoff_test.go new file mode 100644 index 0000000000..9f6ee3f843 --- /dev/null +++ b/apps/backend/internal/orchestrator/prompt_dispatch_failure_handoff_test.go @@ -0,0 +1,96 @@ +package orchestrator + +import ( + "context" + "strings" + "testing" + + "github.com/kandev/kandev/internal/orchestrator/executor" + "github.com/kandev/kandev/internal/sysprompt" + "github.com/kandev/kandev/internal/task/models" + wfmodels "github.com/kandev/kandev/internal/workflow/models" + v1 "github.com/kandev/kandev/pkg/api/v1" + "github.com/stretchr/testify/require" +) + +// TestHandlePromptDispatchFailure_ComposedPromptSurvivesInternalFallback +// covers promptTask's OWN internal ErrExecutionNotFound recovery +// (handlePromptDispatchFailure), a second, independent trigger for +// fallbackFreshLaunchOnMissingExecution beyond autoStartStepPrompt's own +// explicit branch (covered by +// TestFallbackFreshLaunch_ComposedPromptSurvivesStepRecomposition). This +// internal recovery fires on the ordinary "lazy resume after a backend +// restart" race (promptTask's resumedForPrompt) and used to always call +// fallbackFreshLaunchOnMissingExecution with promptAlreadyComposed=false, +// silently discarding an already-claimed step handoff whenever the caller +// had already composed the dispatch prompt (e.g. autoStartStepPrompt, +// appending a claimed handoff before calling promptTask) — the same failure +// mode Build round 4 fixed at the sibling call site only. +// +// Exercises handlePromptDispatchFailure directly rather than through +// promptTask/PromptTask: promptTask's requireNonterminalSession branch +// already holds the per-session cancelInFlightGuard for the rest of the +// call, and fallbackFreshLaunchOnMissingExecution re-acquires that same +// guard — a pre-existing, unrelated locking shape (present at merge-base, +// unrelated to this capability) that this test must not exercise. +func TestHandlePromptDispatchFailure_ComposedPromptSurvivesInternalFallback(t *testing.T) { + ctx := context.Background() + const ( + taskID = "task-dispatch-failure-handoff" + sessionID = "session-dispatch-failure-handoff" + stepID = "step-next-dispatch-failure" + handoff = "watch out for the flaky test" + ) + repo := setupTestRepo(t) + seedTaskAndSession(t, repo, taskID, sessionID, models.TaskSessionStateWaitingForInput) + dbTask, err := repo.GetTask(ctx, taskID) + require.NoError(t, err) + dbTask.WorkflowStepID = stepID + require.NoError(t, repo.UpdateTask(ctx, dbTask)) + session, err := repo.GetTaskSession(ctx, sessionID) + require.NoError(t, err) + session.AgentProfileID = "profile-dispatch-failure" + require.NoError(t, repo.UpdateTaskSession(ctx, session)) + + stepGetter := newMockStepGetter() + stepGetter.steps[stepID] = &wfmodels.WorkflowStep{ + ID: stepID, WorkflowID: "wf1", Name: "Next", + Prompt: "Recomposed step instructions.", + } + taskRepo := newMockTaskRepo() + taskRepo.tasks[taskID] = &v1.Task{ID: taskID, Title: "Test Task", State: v1.TaskStateInProgress} + + var launchedDescription string + agentMgr := &mockAgentManager{ + repoForExecutionLookup: repo, + launchAgentFunc: func(_ context.Context, req *executor.LaunchAgentRequest) (*executor.LaunchAgentResponse, error) { + launchedDescription = req.TaskDescription + return &executor.LaunchAgentResponse{AgentExecutionID: "exec-fresh"}, nil + }, + } + svc := createTestServiceWithScheduler(repo, stepGetter, taskRepo, agentMgr) + svc.messageCreator = &mockMessageCreator{} + + composedPrompt := "Run the next workflow step.\n\n" + stepHandoffPromptHeading + "\n\n" + handoff + + // Mirrors the guard handlePromptDispatchFailure checks before recovering + // internally: resumedForPrompt=true, nothing accepted or reserved yet, + // and the specific ErrExecutionNotFound this recovery targets. + result, err := svc.handlePromptDispatchFailure( + ctx, taskID, sessionID, composedPrompt, + true, true, + nil, + promptClaimRollback{}, + false, false, + executor.ErrExecutionNotFound, + true, sysprompt.InjectPlanMode(composedPrompt), composedPrompt, + ) + require.NoError(t, err) + require.NotNil(t, result) + require.Contains(t, launchedDescription, handoff, + "the already-composed prompt (with the claimed handoff) must survive promptTask's own internal fallback") + require.Contains(t, launchedDescription, sysprompt.PlanMode(), + "the fallback must retain the plan-mode transform") + require.NotEqual(t, "Recomposed step instructions.", strings.TrimSpace(launchedDescription), + "promptAlreadyComposed must skip StartCreatedSession's own step-template recomposition") +} diff --git a/apps/backend/internal/orchestrator/queue_auto_run_review_test.go b/apps/backend/internal/orchestrator/queue_auto_run_review_test.go index 3edc572e38..234ee81df0 100644 --- a/apps/backend/internal/orchestrator/queue_auto_run_review_test.go +++ b/apps/backend/internal/orchestrator/queue_auto_run_review_test.go @@ -76,6 +76,7 @@ func TestAutoStartStepPrompt_LeavesHandoffQueuedWhenAutoRunPaused(t *testing.T) autoStart, false, false, + nil, ) require.NoError(t, err) diff --git a/apps/backend/internal/orchestrator/queue_send_now.go b/apps/backend/internal/orchestrator/queue_send_now.go index d9aed45da6..3fbc5c1fa0 100644 --- a/apps/backend/internal/orchestrator/queue_send_now.go +++ b/apps/backend/internal/orchestrator/queue_send_now.go @@ -462,6 +462,7 @@ func (s *Service) promptSendNowClaim(ctx context.Context, claim *messagequeue.Se } references := entityrefs.NormalizePersisted(claim.Dispatch.Metadata[messagequeue.MetadataEntityReferences]) promptContent := AppendEntityReferenceContext(claim.Dispatch.Content, references) + promptContent = appendStepHandoffToPrompt(promptContent, stepHandoffFromQueuedMetadata(claim.Dispatch.Metadata)) if err := s.recordQueuedUserMessage(ctx, &claim.Dispatch, attachments); err != nil { s.logger.Warn("failed to record send-now user message before prompt", zap.String("session_id", sessionID), zap.Error(err)) diff --git a/apps/backend/internal/orchestrator/service.go b/apps/backend/internal/orchestrator/service.go index fd65c47824..a47e6787cd 100644 --- a/apps/backend/internal/orchestrator/service.go +++ b/apps/backend/internal/orchestrator/service.go @@ -222,7 +222,10 @@ type StepHistoryRecorder interface { } type asyncStepHistoryRecorder interface { - EnqueueStepTransition(sessionID, fromStepID, toStepID string, trigger wfmodels.StepTransitionTrigger, actorID *string, metadata map[string]interface{}) + // EnqueueStepTransition returns false when the bounded worker cannot accept + // the row. Signal-bearing callers can then use their bounded synchronous + // fallback instead of silently losing the audit payload. + EnqueueStepTransition(sessionID, fromStepID, toStepID string, trigger wfmodels.StepTransitionTrigger, actorID *string, metadata map[string]interface{}) bool } // AgentFamilyResolver maps a hand-written agent family reference onto the diff --git a/apps/backend/internal/orchestrator/step_handoff_carry.go b/apps/backend/internal/orchestrator/step_handoff_carry.go new file mode 100644 index 0000000000..6627776392 --- /dev/null +++ b/apps/backend/internal/orchestrator/step_handoff_carry.go @@ -0,0 +1,252 @@ +package orchestrator + +import ( + "context" + "encoding/json" + "strings" + "sync" + + "github.com/google/uuid" + "go.uber.org/zap" + + "github.com/kandev/kandev/internal/orchestrator/messagequeue" + "github.com/kandev/kandev/internal/task/models" +) + +// drainQueuedMessageForPromptableSessionWithHandoff is a sibling of +// drainQueuedMessageForPromptableSessionOutcome for the step-entry dispatch +// branches whose only activity is draining a queued message. It duplicates +// that function's guard/reserve tail instead of adding a splice parameter to +// the shared drain chain, which has 12 production call sites that are not +// step entries at all and must keep their existing behavior unchanged. The +// handoff is claimed only once a message is confirmed about to be +// dispatched, and is carried on a LOCAL COPY of that message's metadata — +// never onto the stored queue entry — so a skipped or paused reservation +// cannot lose or double-append it on a later drain. It rides as metadata +// rather than being spliced onto Content directly because the actual +// dispatch still runs entity-reference expansion over Content; appending the +// handoff here would let that expansion land after it, violating the +// "handoff last" rule whenever the queued message itself carries references. +func (s *Service) drainQueuedMessageForPromptableSessionWithHandoff( + ctx context.Context, taskID, sessionID, stepID string, once *stepHandoffOnce, +) bool { + lock, release := s.acquireCancelInFlightGuard(sessionID) + defer release() + lock.Lock() + defer lock.Unlock() + if s.isCancelInFlight(sessionID) { + return false + } + session, err := s.repo.GetTaskSession(ctx, sessionID) + if err != nil { + s.logger.Warn("failed to reload session before handoff-aware drain", + zap.String("session_id", sessionID), zap.Error(err)) + return false + } + if err := s.checkSessionPromptable(session.TaskID, sessionID, session.State); err != nil { + return false + } + if s.messageQueue == nil || s.isQueuedDispatchInFlight(sessionID) || s.isSteerInFlight(sessionID) { + return false + } + queuedMsg, ok, autoRun := s.messageQueue.ReserveQueuedWithAutoRun(ctx, sessionID) + if !autoRun || !ok || queuedMsg == nil { + return false + } + if queuedMsg.Content != "" || len(queuedMsg.Attachments) > 0 { + if handoffText := s.resolveStepHandoffText(ctx, once, taskID, stepID, true); handoffText != "" { + queuedMsg = withStepHandoffMetadata(queuedMsg, handoffText) + } + } + return s.dispatchTakenQueuedMessage(ctx, sessionID, queuedMsg, ok) +} + +// withStepHandoffMetadata returns a shallow copy of msg carrying handoffText +// under messagequeue.MetadataStepHandoff, leaving the original message (and +// its metadata map) untouched so a later drain of the same stored entry never +// observes a handoff it was not itself claimed for. +func withStepHandoffMetadata(msg *messagequeue.QueuedMessage, handoffText string) *messagequeue.QueuedMessage { + spliced := *msg + metadata := make(map[string]interface{}, len(msg.Metadata)+1) + for k, v := range msg.Metadata { + metadata[k] = v + } + metadata[messagequeue.MetadataStepHandoff] = handoffText + spliced.Metadata = metadata + return &spliced +} + +// stepHandoffFromQueuedMetadata extracts a claimed handoff carried through a +// queued message's metadata (see withStepHandoffMetadata / queueAutoStartPrompt), +// so a deferred dispatch path can append it last, after entity-reference +// expansion, instead of losing it or racing that expansion. +func stepHandoffFromQueuedMetadata(metadata map[string]interface{}) string { + handoff, _ := metadata[messagequeue.MetadataStepHandoff].(string) + return handoff +} + +// stepHandoffPromptHeading is the fixed heading the claimed handoff text is +// appended under, last in the composed prompt. Not localized: the same class +// as workflowInstructionsHeading, sent to the model rather than rendered to a +// user. +const stepHandoffPromptHeading = "## Context from the previous workflow step" + +// setStepHandoffCarryMetadata applies the same single-slot carry semantics to +// a task snapshot before a workflow transition is persisted. Keeping the token +// on that snapshot makes admission and carry publication one database write, +// so a queued task cannot be promoted in the gap between the transition and a +// later metadata update. +func setStepHandoffCarryMetadata(task *models.Task, nextStepID string, signal *models.PendingStepCompletionSignal) { + if task == nil || nextStepID == "" { + return + } + if task.Metadata == nil { + task.Metadata = make(map[string]interface{}) + } + handoff := "" + if signal != nil { + handoff = strings.TrimSpace(signal.Handoff) + } + if handoff == "" { + delete(task.Metadata, models.MetaKeyStepHandoffCarry) + return + } + task.Metadata[models.MetaKeyStepHandoffCarry] = models.StepHandoffCarryToken{ + Handoff: handoff, + StepID: nextStepID, + Stamp: uuid.NewString(), + } +} + +// claimStepHandoffCarryText performs the advisory-read-then-claim for the +// step being entered, returning the claimed handoff text and whether a token +// was actually claimed. A repository lacking the capability, a missing or +// mismatched token, or a claim error all report claimed=false with no text, +// so a failed attempt never spends the step entry's one-claim budget. +func (s *Service) claimStepHandoffCarryText(ctx context.Context, taskID, stepID string) (string, bool) { + if taskID == "" || stepID == "" || s.repo == nil { + return "", false + } + taker, ok := s.repo.(taskMetadataCarryTaker) + if !ok { + return "", false + } + token, ok := s.advisoryStepHandoffCarryToken(ctx, taskID, stepID) + if !ok { + return "", false + } + claimedRaw, claimed, err := taker.TakeTaskMetadataKeyIfDestinationStep( + ctx, taskID, models.MetaKeyStepHandoffCarry, stepID, token.Stamp, + ) + if err != nil { + s.logger.Debug("failed to claim step handoff carry token", + zap.String("task_id", taskID), zap.String("step_id", stepID), zap.Error(err)) + return "", false + } + if !claimed { + return "", false + } + var claimedToken models.StepHandoffCarryToken + if err := json.Unmarshal(claimedRaw, &claimedToken); err != nil { + return "", false + } + return strings.TrimSpace(claimedToken.Handoff), true +} + +// advisoryStepHandoffCarryToken performs the non-claiming read used to decide +// whether a claim attempt targeting stepID is worth making. This read is not +// synchronized with a concurrent claim, so the caller still must perform the +// compare-and-swap via TakeTaskMetadataKeyIfDestinationStep rather than acting +// on this result directly. +func (s *Service) advisoryStepHandoffCarryToken(ctx context.Context, taskID, stepID string) (models.StepHandoffCarryToken, bool) { + task, err := s.repo.GetTask(ctx, taskID) + if err != nil || task == nil || task.Metadata == nil { + return models.StepHandoffCarryToken{}, false + } + rawValue, present := task.Metadata[models.MetaKeyStepHandoffCarry] + if !present { + return models.StepHandoffCarryToken{}, false + } + tokenBytes, err := json.Marshal(rawValue) + if err != nil { + return models.StepHandoffCarryToken{}, false + } + var token models.StepHandoffCarryToken + if err := json.Unmarshal(tokenBytes, &token); err != nil { + return models.StepHandoffCarryToken{}, false + } + if token.StepID != stepID || strings.TrimSpace(token.Stamp) == "" { + return models.StepHandoffCarryToken{}, false + } + return token, true +} + +// appendStepHandoffToPrompt appends the claimed handoff text under the fixed +// heading, last in the composed prompt. Called after reference expansion has +// already run over the rest of the prompt, so the handoff text is never +// itself expanded. +func appendStepHandoffToPrompt(prompt, handoffText string) string { + if handoffText == "" { + return prompt + } + section := stepHandoffPromptHeading + "\n\n" + handoffText + if strings.TrimSpace(prompt) == "" { + return section + } + return prompt + "\n\n" + section +} + +// joinStepHandoffText combines raw handoff payloads for a queue entry. The +// queue adds one heading when it dispatches, so the payload stays free of +// formatting and remains safe to append after reference expansion. +func joinStepHandoffText(previous, current string) string { + previous = strings.TrimSpace(previous) + current = strings.TrimSpace(current) + switch { + case previous == "": + return current + case current == "": + return previous + default: + return previous + "\n\n" + current + } +} + +// stepHandoffOnce memoizes one step entry's handoff claim so a replacement +// launch (after a failed or terminalized first attempt within the same step +// entry) reuses the same text instead of re-claiming: the underlying DB claim +// only ever succeeds once, so a second raw attempt would silently find +// nothing. Only a SUCCESSFUL claim is memoized — a failure (no repository +// capability, no matching token, or a claim error) is not, so a later +// replacement launch in the same entry retries it. +type stepHandoffOnce struct { + mu sync.Mutex + claimed bool + text string +} + +func newStepHandoffOnce() *stepHandoffOnce { + return &stepHandoffOnce{} +} + +// resolveStepHandoffText returns the handoff text to append for this step +// entry, claiming it at most once. wouldSend reports whether the caller's own +// dispatch branch has already decided it will send the agent something over +// content that excludes the handoff text; when false, nothing is claimed, so +// a dispatch that never happens can never consume a handoff. +func (s *Service) resolveStepHandoffText(ctx context.Context, once *stepHandoffOnce, taskID, stepID string, wouldSend bool) string { + if once == nil || !wouldSend { + return "" + } + once.mu.Lock() + defer once.mu.Unlock() + if once.claimed { + return once.text + } + text, claimed := s.claimStepHandoffCarryText(ctx, taskID, stepID) + if claimed { + once.claimed = true + once.text = text + } + return text +} diff --git a/apps/backend/internal/orchestrator/step_handoff_carry_dispatch_test.go b/apps/backend/internal/orchestrator/step_handoff_carry_dispatch_test.go new file mode 100644 index 0000000000..aded7253e9 --- /dev/null +++ b/apps/backend/internal/orchestrator/step_handoff_carry_dispatch_test.go @@ -0,0 +1,751 @@ +package orchestrator + +import ( + "context" + "encoding/json" + "errors" + "fmt" + "strings" + "sync/atomic" + "testing" + "time" + + "github.com/kandev/kandev/internal/orchestrator/executor" + "github.com/kandev/kandev/internal/orchestrator/messagequeue" + "github.com/kandev/kandev/internal/orchestrator/queue" + "github.com/kandev/kandev/internal/orchestrator/scheduler" + "github.com/kandev/kandev/internal/sysprompt" + "github.com/kandev/kandev/internal/task/models" + wfmodels "github.com/kandev/kandev/internal/workflow/models" + v1 "github.com/kandev/kandev/pkg/api/v1" + "github.com/stretchr/testify/require" +) + +func seedHandoffCarryToken(t *testing.T, repo interface { + SetTaskMetadataKey(ctx context.Context, taskID, key string, value interface{}) error +}, taskID, stepID, handoff, stamp string) { + t.Helper() + err := repo.SetTaskMetadataKey(context.Background(), taskID, models.MetaKeyStepHandoffCarry, models.StepHandoffCarryToken{ + Handoff: handoff, StepID: stepID, Stamp: stamp, + }) + if err != nil { + t.Fatalf("seed carry token: %v", err) + } +} + +// TestAutoStartStepPrompt_DeliversHandoffLastAfterQueuedHandoff covers +// AC-001.6 and AC-001.6a on the ACP dispatch branch: an AutoRun-enabled +// queued hand-off message merges first, then the completion handoff carry +// token is claimed and appended last, under the fixed heading. +func TestAutoStartStepPrompt_DeliversHandoffLastAfterQueuedHandoff(t *testing.T) { + ctx := context.Background() + const ( + taskID = "task-handoff-order" + sessionID = "session-handoff-order" + stepID = "step-next" + queued = "please also check the migration" + autoStart = "Run the next workflow step" + carried = "watch out for the flaky test" + ) + repo := setupTestRepo(t) + seedTaskAndSession(t, repo, taskID, sessionID, models.TaskSessionStateWaitingForInput) + seedHandoffCarryToken(t, repo, taskID, stepID, carried, "stamp-order") + agentMgr := &mockAgentManager{isAgentRunning: true, repoForExecutionLookup: repo} + svc := createTestServiceWithAgent(repo, newMockStepGetter(), newMockTaskRepo(), agentMgr) + svc.executor = executor.NewExecutor(agentMgr, repo, testLogger(), executor.ExecutorConfig{}) + seedExecutorRunning(t, repo, sessionID, taskID, "exec-handoff-order") + + _, err := svc.messageQueue.QueueMessage(ctx, sessionID, taskID, queued, "", "user", false, nil) + require.NoError(t, err) + session, err := repo.GetTaskSession(ctx, sessionID) + require.NoError(t, err) + + err = svc.autoStartStepPrompt( + ctx, taskID, session, &wfmodels.WorkflowStep{ID: stepID, WorkflowID: "wf1", Name: "Next"}, + autoStart, false, false, newStepHandoffOnce(), + ) + require.NoError(t, err) + require.Len(t, agentMgr.capturedPrompts, 1) + prompt := agentMgr.capturedPrompts[0] + + autoStartIdx := strings.Index(prompt, autoStart) + queuedIdx := strings.Index(prompt, queued) + headingIdx := strings.Index(prompt, stepHandoffPromptHeading) + carriedIdx := strings.Index(prompt, carried) + require.NotEqual(t, -1, autoStartIdx, "prompt = %q", prompt) + require.NotEqual(t, -1, queuedIdx, "prompt = %q", prompt) + require.NotEqual(t, -1, headingIdx, "prompt = %q", prompt) + require.NotEqual(t, -1, carriedIdx, "prompt = %q", prompt) + require.True(t, autoStartIdx < queuedIdx, "auto-start content must precede the queued hand-off") + require.True(t, queuedIdx < headingIdx, "the completion handoff must land after the queued hand-off") + require.True(t, headingIdx < carriedIdx) + + if _, present := carryToken(t, repo, taskID); present { + t.Fatal("the claimed carry token must be removed") + } +} + +// TestAutoStartStepPrompt_NoTokenNoHeading covers the plain case: with no +// carry token, the prompt is unchanged and no heading is injected. +func TestAutoStartStepPrompt_NoTokenNoHeading(t *testing.T) { + ctx := context.Background() + const ( + taskID = "task-no-handoff" + sessionID = "session-no-handoff" + autoStart = "Run the next workflow step" + ) + repo := setupTestRepo(t) + seedTaskAndSession(t, repo, taskID, sessionID, models.TaskSessionStateWaitingForInput) + agentMgr := &mockAgentManager{isAgentRunning: true, repoForExecutionLookup: repo} + svc := createTestServiceWithAgent(repo, newMockStepGetter(), newMockTaskRepo(), agentMgr) + svc.executor = executor.NewExecutor(agentMgr, repo, testLogger(), executor.ExecutorConfig{}) + seedExecutorRunning(t, repo, sessionID, taskID, "exec-no-handoff") + session, err := repo.GetTaskSession(ctx, sessionID) + require.NoError(t, err) + + err = svc.autoStartStepPrompt( + ctx, taskID, session, &wfmodels.WorkflowStep{ID: "step-next", WorkflowID: "wf1", Name: "Next"}, + autoStart, false, false, newStepHandoffOnce(), + ) + require.NoError(t, err) + require.Len(t, agentMgr.capturedPrompts, 1) + require.False(t, strings.Contains(agentMgr.capturedPrompts[0], stepHandoffPromptHeading)) +} + +// TestAutoStartStepPrompt_ReplacementLaunchReusesClaimedHandoff covers +// AC-001.8: a replacement launch within the same step entry, sharing the same +// stepHandoffOnce, receives the same handoff text even though the DB-level +// claim can only succeed once. +func TestAutoStartStepPrompt_ReplacementLaunchReusesClaimedHandoff(t *testing.T) { + ctx := context.Background() + const ( + taskID = "task-replacement-handoff" + sessionID = "session-replacement-handoff" + stepID = "step-next" + autoStart = "Run the next workflow step" + carried = "carried across the replacement" + ) + repo := setupTestRepo(t) + seedTaskAndSession(t, repo, taskID, sessionID, models.TaskSessionStateWaitingForInput) + seedHandoffCarryToken(t, repo, taskID, stepID, carried, "stamp-replacement") + agentMgr := &mockAgentManager{isAgentRunning: true, repoForExecutionLookup: repo} + svc := createTestServiceWithAgent(repo, newMockStepGetter(), newMockTaskRepo(), agentMgr) + svc.executor = executor.NewExecutor(agentMgr, repo, testLogger(), executor.ExecutorConfig{}) + seedExecutorRunning(t, repo, sessionID, taskID, "exec-replacement-handoff") + session, err := repo.GetTaskSession(ctx, sessionID) + require.NoError(t, err) + step := &wfmodels.WorkflowStep{ID: stepID, WorkflowID: "wf1", Name: "Next"} + once := newStepHandoffOnce() + + // First attempt: claims and delivers the token, removing it from the DB. + err = svc.autoStartStepPrompt(ctx, taskID, session, step, autoStart, false, false, once) + require.NoError(t, err) + require.Len(t, agentMgr.capturedPrompts, 1) + require.Contains(t, agentMgr.capturedPrompts[0], carried) + if _, present := carryToken(t, repo, taskID); present { + t.Fatal("the token must be removed after the first claim") + } + + // A replacement launch in the SAME step entry reuses the shared once — the + // DB has nothing left to claim, but the memoized text must still appear. + // Reset the session back to promptable, standing in for a real replacement + // launch (created after the first session terminalized). + require.NoError(t, repo.UpdateTaskSessionState(ctx, sessionID, models.TaskSessionStateWaitingForInput, "")) + seedExecutorRunning(t, repo, sessionID, taskID, "exec-replacement-handoff-2") + session, err = repo.GetTaskSession(ctx, sessionID) + require.NoError(t, err) + err = svc.autoStartStepPrompt(ctx, taskID, session, step, autoStart, false, false, once) + require.NoError(t, err) + require.Len(t, agentMgr.capturedPrompts, 2) + require.Contains(t, agentMgr.capturedPrompts[1], carried, "the replacement launch must reuse the already-claimed handoff text") +} + +// TestLaunchAfterOnEnterDispatch_PassthroughEmptyPromptDeliversViaDrain covers +// AC-001.6c: the passthrough branch that finds its composed prompt empty +// still dispatches a drained queued message, and that dispatch carries the +// completion handoff. +func TestLaunchAfterOnEnterDispatch_PassthroughEmptyPromptDeliversViaDrain(t *testing.T) { + ctx := context.Background() + const ( + taskID = "task-passthrough-drain" + sessionID = "session-passthrough-drain" + stepID = "step1" + queued = "drain me please" + carried = "passthrough carried text" + ) + repo := setupTestRepo(t) + seedTaskAndSession(t, repo, taskID, sessionID, models.TaskSessionStateWaitingForInput) + seedHandoffCarryToken(t, repo, taskID, stepID, carried, "stamp-passthrough") + agentMgr := &mockAgentManager{isAgentRunning: true, repoForExecutionLookup: repo, isPassthrough: true} + svc := createTestServiceWithAgent(repo, newMockStepGetter(), newMockTaskRepo(), agentMgr) + svc.executor = executor.NewExecutor(agentMgr, repo, testLogger(), executor.ExecutorConfig{}) + seedExecutorRunning(t, repo, sessionID, taskID, "exec-passthrough-drain") + + _, err := svc.messageQueue.QueueMessage(ctx, sessionID, taskID, queued, "", "user", false, nil) + require.NoError(t, err) + session, err := repo.GetTaskSession(ctx, sessionID) + require.NoError(t, err) + // Pre-consume the one-time initial-prompt fallback claim so buildWorkflowEntryPrompt + // treats taskDescription as ineligible and composes an empty prompt below — the + // actual case this test targets. Without this, the first claim on a fresh session + // wins and taskDescription becomes the composed prompt, silently exercising the + // unrelated autoStartPassthroughPrompt branch instead of the drain-only one. + _, err = repo.ClaimInitialPromptFallback(ctx, sessionID) + require.NoError(t, err) + + done := make(chan struct{}, 1) + agentMgr.passthroughStdinFunc = func(context.Context, string, string) error { + done <- struct{}{} + return nil + } + + step := &wfmodels.WorkflowStep{ID: stepID, WorkflowID: "wf1", Name: "Step 1", Prompt: ""} + svc.launchAfterOnEnterDispatch(ctx, taskID, session, step, "task description", false, true, false) + + select { + case <-done: + case <-time.After(5 * time.Second): + t.Fatal("timed out waiting for the drained queue message to dispatch") + } + + // The claim happens synchronously inside the guarded reserve, before the + // dispatch's async execution. + if _, present := carryToken(t, repo, taskID); present { + t.Fatal("the drain-only passthrough branch must claim the token when it dispatches") + } + require.Len(t, agentMgr.passthroughStdinCalls, 1) + written := agentMgr.passthroughStdinCalls[0].Data + require.Contains(t, written, queued) + require.Contains(t, written, carried, "the passthrough drain must deliver the claimed handoff text") +} + +// TestProcessOnEnter_NoOnEnterActionsDrainDeliversHandoff covers F22's first +// gap: processOnEnter's own early return (no on_enter actions, no profile +// switch) never reaches launchAfterOnEnterDispatch, yet still drains a queued +// message and must still carry the handoff. +func TestProcessOnEnter_NoOnEnterActionsDrainDeliversHandoff(t *testing.T) { + ctx := context.Background() + const ( + taskID = "task-no-onenter-drain" + sessionID = "session-no-onenter-drain" + stepID = "step1" + queued = "drain me too" + carried = "no on_enter carried text" + ) + repo := setupTestRepo(t) + seedTaskAndSession(t, repo, taskID, sessionID, models.TaskSessionStateWaitingForInput) + seedHandoffCarryToken(t, repo, taskID, stepID, carried, "stamp-no-onenter") + agentMgr := &mockAgentManager{isAgentRunning: true, repoForExecutionLookup: repo} + svc := createTestServiceWithAgent(repo, newMockStepGetter(), newMockTaskRepo(), agentMgr) + svc.executor = executor.NewExecutor(agentMgr, repo, testLogger(), executor.ExecutorConfig{}) + seedExecutorRunning(t, repo, sessionID, taskID, "exec-no-onenter-drain") + + _, err := svc.messageQueue.QueueMessage(ctx, sessionID, taskID, queued, "", "user", false, nil) + require.NoError(t, err) + session, err := repo.GetTaskSession(ctx, sessionID) + require.NoError(t, err) + + done := make(chan struct{}) + svc.onQueuedMessageExecutionComplete = func() { close(done) } + + step := &wfmodels.WorkflowStep{ID: stepID, WorkflowID: "wf1", Name: "Step 1"} + svc.processOnEnter(ctx, taskID, session, step, "task description", 0, nil) + + select { + case <-done: + case <-time.After(5 * time.Second): + t.Fatal("timed out waiting for the drained queue message to dispatch") + } + + if _, present := carryToken(t, repo, taskID); present { + t.Fatal("processOnEnter's own drain-only early return must claim the token when it dispatches") + } + require.Len(t, agentMgr.capturedPrompts, 1) + prompt := agentMgr.capturedPrompts[0] + require.Contains(t, prompt, queued) + require.Contains(t, prompt, carried, "processOnEnter's drain-only early return must deliver the claimed handoff text") +} + +// TestLaunchAfterOnEnterDispatch_EmptyEntrySendsNothingClaimsNothing covers +// AC-001.6a: when a step entry decides — over content excluding the handoff +// text — that it will send the agent nothing, the handoff must never be +// claimed. Modeled on TestWorkflowAutoStartEmptyPrompt's "prompted session +// suppresses task description" case, which reaches autoStartStepPrompt's own +// early return with no queued hand-off to fall back to. +func TestLaunchAfterOnEnterDispatch_EmptyEntrySendsNothingClaimsNothing(t *testing.T) { + fixture := newInitialPromptDedupFixture(t, true, false) + seedHandoffCarryToken(t, fixture.repo, fixture.taskID, fixture.step.ID, "must not be claimed", "stamp-unsent") + + fixture.svc.launchAfterOnEnterDispatch( + context.Background(), fixture.taskID, fixture.session, fixture.step, + fixture.taskDescription, false, true, false, + ) + + if len(fixture.agent.capturedPrompts) != 0 { + t.Fatalf("captured prompts = %#v, want none", fixture.agent.capturedPrompts) + } + token, present := carryToken(t, fixture.repo, fixture.taskID) + if !present || token.Handoff != "must not be claimed" { + t.Fatalf("a dispatch that sends nothing must not claim the token, got present=%v token=%+v", present, token) + } +} + +// TestAutoStartPassthroughPrompt_ClaimedTokenNotRestoredOnDispatchFailure +// covers AC-001.9: a claimed token is never restored, even when the entry +// that claimed it then fails to dispatch — and a later entry into that same +// step gets no handoff either, since REQ-005 accepts the handoff as lost +// rather than risk a double-delivery on retry. +func TestAutoStartPassthroughPrompt_ClaimedTokenNotRestoredOnDispatchFailure(t *testing.T) { + ctx := context.Background() + const ( + taskID = "task-unrestored-handoff" + sessionID = "session-unrestored-handoff" + stepID = "step-next" + carried = "lost on dispatch failure" + ) + repo := setupTestRepo(t) + seedTaskAndSession(t, repo, taskID, sessionID, models.TaskSessionStateWaitingForInput) + seedHandoffCarryToken(t, repo, taskID, stepID, carried, "stamp-unrestored") + agentMgr := &mockAgentManager{ + isAgentRunning: true, repoForExecutionLookup: repo, isPassthrough: true, + passthroughStdinErr: errors.New("simulated stdin write failure"), + } + svc := createTestServiceWithAgent(repo, newMockStepGetter(), newMockTaskRepo(), agentMgr) + svc.executor = executor.NewExecutor(agentMgr, repo, testLogger(), executor.ExecutorConfig{}) + seedExecutorRunning(t, repo, sessionID, taskID, "exec-unrestored-handoff") + session, err := repo.GetTaskSession(ctx, sessionID) + require.NoError(t, err) + + step := &wfmodels.WorkflowStep{ID: stepID, WorkflowID: "wf1", Name: "Next", Prompt: "go"} + svc.launchAfterOnEnterDispatch(ctx, taskID, session, step, "task description", false, true, false) + + if _, present := carryToken(t, repo, taskID); present { + t.Fatal("the token must be claimed (removed) even though dispatch failed") + } + text, claimed := svc.claimStepHandoffCarryText(ctx, taskID, stepID) + if claimed || text != "" { + t.Fatalf("a later entry into the same step must get nothing back, got claimed=%v text=%q", claimed, text) + } +} + +// TestStartSessionForWorkflowStep_DeliversHandoff covers AC-001.11: the queue +// promotion / manual auto-start dispatch path also claims and appends the +// completion handoff. +func TestStartSessionForWorkflowStep_DeliversHandoff(t *testing.T) { + fixture := newInitialPromptDedupFixture(t, true, false) + fixture.step.Prompt = "Continue with validation." + seedHandoffCarryToken(t, fixture.repo, fixture.taskID, fixture.step.ID, "queue promotion carried text", "stamp-queue-promo") + + if err := fixture.svc.StartSessionForWorkflowStep( + context.Background(), fixture.taskID, fixture.sessionID, fixture.step.ID, + ); err != nil { + t.Fatalf("StartSessionForWorkflowStep returned error: %v", err) + } + + got := fixture.agent.capturedPrompts + if len(got) != 1 || !strings.Contains(got[0], fixture.step.Prompt) || !strings.Contains(got[0], "queue promotion carried text") { + t.Fatalf("captured prompts = %#v, want step prompt plus carried handoff", got) + } + if _, present := carryToken(t, fixture.repo, fixture.taskID); present { + t.Fatal("the claimed token must be removed") + } +} + +// TestStartSessionForWorkflowStep_ComposedHandoffSurvivesLazyResumeFallback +// covers the same ErrExecutionNotFound-after-lazy-resume race +// autoStartStepPrompt and promptTask's own internal recovery were already +// fixed for, at the one remaining composed-prompt caller: StartSessionForWorkflowStep +// appends a claimed handoff to effectivePrompt before dispatch, but used to +// call the public PromptTask (promptAlreadyComposed defaults to false), so a +// missing-execution race hitting promptTask's internal recovery would +// recompose the prompt from the destination step's own template and silently +// drop the handoff. +func TestStartSessionForWorkflowStep_ComposedHandoffSurvivesLazyResumeFallback(t *testing.T) { + ctx := context.Background() + const ( + taskID = "task-workflow-step-lazy-resume" + sessionID = "session-workflow-step-lazy-resume" + stepID = "step-workflow-step-lazy-resume" + handoff = "watch out for the flaky test" + ) + repo := setupTestRepo(t) + seedTaskAndSession(t, repo, taskID, sessionID, models.TaskSessionStateWaitingForInput) + session, err := repo.GetTaskSession(ctx, sessionID) + require.NoError(t, err) + session.AgentExecutionID = "exec-before-restart" + session.AgentProfileID = "profile-lazy-resume" + require.NoError(t, repo.UpdateTaskSession(ctx, session)) + seedExecutorRunning(t, repo, sessionID, taskID, "exec-before-restart") + seedHandoffCarryToken(t, repo, taskID, stepID, handoff, "stamp-lazy-resume") + + stepGetter := newMockStepGetter() + stepGetter.steps[stepID] = &wfmodels.WorkflowStep{ + ID: stepID, WorkflowID: "wf1", Name: "Next", + Prompt: "Recomposed step instructions.", + Events: wfmodels.StepEvents{OnEnter: []wfmodels.OnEnterAction{{Type: wfmodels.OnEnterEnablePlanMode}}}, + } + taskRepo := newMockTaskRepo() + taskRepo.tasks[taskID] = &v1.Task{ID: taskID, Title: "Test Task", State: v1.TaskStateInProgress} + + // IsAgentRunningForSession reports "running" for every call except the + // second: StartSessionForWorkflowStep's own ensureSessionRunning (call 1) + // sees the session as already running and skips resuming it, then + // promptTask's internal hadExecutionBeforeEnsure check (call 2) hits a + // momentary "not running" blip — the exact lazy-resume race + // promptTask's own internal ErrExecutionNotFound recovery exists for — + // before promptTask's own ensureSessionRunning call (call 3) sees it + // running again and does not attempt a second resume. No cold-resume + // launch is needed to reach this state; the only launch in this test is + // the fresh-launch fallback after PromptAgent reports ErrExecutionNotFound. + var runningChecks atomic.Int32 + var launchCalls atomic.Int32 + launchPrompts := make(chan string, 1) + agentMgr := &mockAgentManager{ + repoForExecutionLookup: repo, + promptErr: executor.ErrExecutionNotFound, + isAgentRunningFn: func(_ context.Context, _ string) bool { + return runningChecks.Add(1) != 2 + }, + isAgentReadyFn: func(_ context.Context, _ string) bool { return true }, + launchAgentFunc: func(_ context.Context, req *executor.LaunchAgentRequest) (*executor.LaunchAgentResponse, error) { + call := launchCalls.Add(1) + launchPrompts <- req.TaskDescription + return &executor.LaunchAgentResponse{AgentExecutionID: fmt.Sprintf("exec-fresh-%d", call)}, nil + }, + } + svc := createTestServiceWithAgent(repo, stepGetter, taskRepo, agentMgr) + exec := executor.NewExecutor(agentMgr, repo, testLogger(), executor.ExecutorConfig{}) + svc.executor = exec + svc.scheduler = scheduler.NewScheduler(queue.NewTaskQueue(100), exec, taskRepo, testLogger(), scheduler.DefaultSchedulerConfig()) + svc.messageCreator = &mockMessageCreator{} + + err = svc.StartSessionForWorkflowStep(ctx, taskID, sessionID, stepID) + require.NoError(t, err) + + require.Equal(t, int32(1), launchCalls.Load(), "expected exactly the fresh-launch fallback, no cold-resume launch") + freshPrompt := <-launchPrompts + require.Contains(t, freshPrompt, handoff, + "the already-composed prompt (with the claimed handoff) must survive the fresh-launch fallback") + require.Contains(t, freshPrompt, sysprompt.PlanMode(), + "the fresh-launch fallback must retain the destination step's plan-mode instructions") + require.NotEqual(t, "Recomposed step instructions.", strings.TrimSpace(freshPrompt), + "promptAlreadyComposed must skip StartCreatedSession's own step-template recomposition") +} + +// TestAutoStartStepPrompt_QueueFallbackWhenRunningCarriesHandoffMetadata covers +// AC-001.6/AC-001.8's queue-fallback half: when autoStartStepPrompt's +// shouldQueueIfBusy branch queues instead of dispatching directly (the +// session is already RUNNING), the handoff already claimed for this step +// entry must ride along as queue metadata — not the raw pre-handoff prompt — +// so a later drain (through the ordinary, non-handoff-aware drain path every +// other queued message uses) still appends it, last, after entity-reference +// expansion. +func TestAutoStartStepPrompt_QueueFallbackWhenRunningCarriesHandoffMetadata(t *testing.T) { + ctx := context.Background() + const ( + taskID = "task-queue-fallback-running" + sessionID = "session-queue-fallback-running" + stepID = "step-next" + autoStart = "Run the next workflow step" + carried = "carried through queue fallback" + ) + repo := setupTestRepo(t) + seedTaskAndSession(t, repo, taskID, sessionID, models.TaskSessionStateRunning) + seedHandoffCarryToken(t, repo, taskID, stepID, carried, "stamp-queue-fallback") + agentMgr := &mockAgentManager{isAgentRunning: true, repoForExecutionLookup: repo} + svc := createTestServiceWithAgent(repo, newMockStepGetter(), newMockTaskRepo(), agentMgr) + svc.executor = executor.NewExecutor(agentMgr, repo, testLogger(), executor.ExecutorConfig{}) + seedExecutorRunning(t, repo, sessionID, taskID, "exec-queue-fallback-running") + session, err := repo.GetTaskSession(ctx, sessionID) + require.NoError(t, err) + + step := &wfmodels.WorkflowStep{ID: stepID, WorkflowID: "wf1", Name: "Next"} + err = svc.autoStartStepPrompt(ctx, taskID, session, step, autoStart, false, true, newStepHandoffOnce()) + require.NoError(t, err) + require.Empty(t, agentMgr.capturedPrompts, "a queued-because-running fallback must not dispatch directly") + + if _, present := carryToken(t, repo, taskID); present { + t.Fatal("the queue-fallback path must still claim the token up front, before deciding to queue") + } + + entries, _, err := svc.messageQueue.SnapshotSession(ctx, sessionID) + require.NoError(t, err) + require.Len(t, entries, 1) + require.Equal(t, carried, stepHandoffFromQueuedMetadata(entries[0].Metadata), + "the queued message metadata must carry the already-claimed handoff, not silently drop it") + + // Drain through the ordinary, non-handoff-aware path every other queued + // message goes through in production. If the fix instead spliced the + // handoff onto raw Content at queue time, this would double as an + // ordering bug; carrying it as metadata means the generic drain path + // (which knows nothing about step handoffs) still appends it correctly. + require.NoError(t, repo.UpdateTaskSessionState(ctx, sessionID, models.TaskSessionStateWaitingForInput, "")) + done := make(chan struct{}) + svc.onQueuedMessageExecutionComplete = func() { close(done) } + require.True(t, svc.drainQueuedMessageForPromptableSessionLocked(ctx, sessionID)) + select { + case <-done: + case <-time.After(5 * time.Second): + t.Fatal("timed out waiting for the drained queue message to dispatch") + } + + require.Len(t, agentMgr.capturedPrompts, 1) + prompt := agentMgr.capturedPrompts[0] + autoStartIdx := strings.Index(prompt, autoStart) + headingIdx := strings.Index(prompt, stepHandoffPromptHeading) + carriedIdx := strings.Index(prompt, carried) + require.NotEqual(t, -1, autoStartIdx, "prompt = %q", prompt) + require.NotEqual(t, -1, headingIdx, "prompt = %q", prompt) + require.NotEqual(t, -1, carriedIdx, "prompt = %q", prompt) + require.True(t, autoStartIdx < headingIdx && headingIdx < carriedIdx, + "the handoff must land last in the drained prompt") +} + +// TestAutoStartStepPrompt_QueueFallbackPreservesEntityReferenceOrderingBeforeHandoff +// covers the MAJOR ordering finding directly: a queue-fallback re-queues a +// message carrying entity references (taken from an existing queued hand-off) +// alongside the claimed step handoff. AppendEntityReferenceContext only runs +// at actual dispatch/drain time, so the drained prompt must still show the +// reference block before the handoff heading — proving the fix appends the +// handoff after reference expansion rather than baking it into raw Content at +// queue time, which would let expansion land after it. +func TestAutoStartStepPrompt_QueueFallbackPreservesEntityReferenceOrderingBeforeHandoff(t *testing.T) { + ctx := context.Background() + const ( + taskID = "task-queue-fallback-refs" + sessionID = "session-queue-fallback-refs" + stepID = "step-next" + autoStart = "Run the next workflow step" + queued = "please also check the migration" + carried = "watch out for the flaky test" + ) + repo := setupTestRepo(t) + seedTaskAndSession(t, repo, taskID, sessionID, models.TaskSessionStateRunning) + seedHandoffCarryToken(t, repo, taskID, stepID, carried, "stamp-queue-fallback-refs") + agentMgr := &mockAgentManager{isAgentRunning: true, repoForExecutionLookup: repo} + svc := createTestServiceWithAgent(repo, newMockStepGetter(), newMockTaskRepo(), agentMgr) + svc.executor = executor.NewExecutor(agentMgr, repo, testLogger(), executor.ExecutorConfig{}) + seedExecutorRunning(t, repo, sessionID, taskID, "exec-queue-fallback-refs") + + reference := queuedReferenceFixture() + _, err := svc.messageQueue.QueueMessageWithMetadata( + ctx, sessionID, taskID, queued, "", messagequeue.QueuedByUser, false, nil, + map[string]interface{}{messagequeue.MetadataEntityReferences: []v1.EntityReference{reference}}, + ) + require.NoError(t, err) + session, err := repo.GetTaskSession(ctx, sessionID) + require.NoError(t, err) + + step := &wfmodels.WorkflowStep{ID: stepID, WorkflowID: "wf1", Name: "Next"} + err = svc.autoStartStepPrompt(ctx, taskID, session, step, autoStart, false, true, newStepHandoffOnce()) + require.NoError(t, err) + require.Empty(t, agentMgr.capturedPrompts) + + require.NoError(t, repo.UpdateTaskSessionState(ctx, sessionID, models.TaskSessionStateWaitingForInput, "")) + done := make(chan struct{}) + svc.onQueuedMessageExecutionComplete = func() { close(done) } + require.True(t, svc.drainQueuedMessageForPromptableSessionLocked(ctx, sessionID)) + select { + case <-done: + case <-time.After(5 * time.Second): + t.Fatal("timed out waiting for the drained queue message to dispatch") + } + + require.Len(t, agentMgr.capturedPrompts, 1) + prompt := agentMgr.capturedPrompts[0] + queuedIdx := strings.Index(prompt, queued) + referenceIdx := strings.Index(prompt, "Validated work-item reference snapshots") + headingIdx := strings.Index(prompt, stepHandoffPromptHeading) + carriedIdx := strings.Index(prompt, carried) + require.NotEqual(t, -1, queuedIdx, "prompt = %q", prompt) + require.NotEqual(t, -1, referenceIdx, "prompt = %q", prompt) + require.NotEqual(t, -1, headingIdx, "prompt = %q", prompt) + require.NotEqual(t, -1, carriedIdx, "prompt = %q", prompt) + require.True(t, queuedIdx < referenceIdx && referenceIdx < headingIdx && headingIdx < carriedIdx, + "entity-reference expansion must land before the handoff, which must land last; prompt = %q", prompt) +} + +func TestAutoStartStepPrompt_MergesQueuedStepHandoff(t *testing.T) { + ctx := context.Background() + fixture := newInitialPromptDedupFixture(t, true, false) + const queuedHandoff = "handoff already claimed by the queued entry" + + _, err := fixture.svc.messageQueue.QueueMessageWithMetadata( + ctx, + fixture.sessionID, + fixture.taskID, + "queued workflow message", + "", + messagequeue.QueuedByWorkflow, + false, + nil, + map[string]interface{}{messagequeue.MetadataStepHandoff: queuedHandoff}, + ) + require.NoError(t, err) + + err = fixture.svc.autoStartStepPrompt( + ctx, fixture.taskID, fixture.session, fixture.step, + "start the next step", false, true, newStepHandoffOnce(), + ) + require.NoError(t, err) + require.Len(t, fixture.agent.capturedPrompts, 1) + require.Contains(t, fixture.agent.capturedPrompts[0], queuedHandoff, + "a queued entry's previously claimed handoff must survive auto-start merging") +} + +// failOnceHandoffClaimRepo wraps a real repo's TakeTaskMetadataKeyIfDestinationStep +// so its first invocation fails, standing in for a transient claim error. Per +// AC-005.2, a failed claim must not spend the step entry's one-claim budget, so +// a later attempt within the same entry (e.g. a replacement launch) must retry +// and succeed against the still-present token. +type failOnceHandoffClaimRepo struct { + sessionExecutorStore + failed bool +} + +func (r *failOnceHandoffClaimRepo) TakeTaskMetadataKeyIfDestinationStep( + ctx context.Context, taskID, key, expectedStepID, expectedStamp string, +) (json.RawMessage, bool, error) { + if !r.failed { + r.failed = true + return nil, false, errors.New("simulated transient claim failure") + } + taker, ok := r.sessionExecutorStore.(taskMetadataCarryTaker) + if !ok { + return nil, false, errors.New("handoff claim capability is unavailable") + } + return taker.TakeTaskMetadataKeyIfDestinationStep(ctx, taskID, key, expectedStepID, expectedStamp) +} + +// TestClaimStepHandoffCarryText_FailedClaimDoesNotSpendBudget covers AC-005.2: +// a failed claim attempt must not memoize an empty result, so a later attempt +// in the same step entry (sharing the same stepHandoffOnce) retries and can +// still succeed. +func TestClaimStepHandoffCarryText_FailedClaimDoesNotSpendBudget(t *testing.T) { + ctx := context.Background() + const ( + taskID = "task-failed-claim-retry" + stepID = "step2" + carried = "carried after retry" + ) + repo := setupTestRepo(t) + seedSession(t, repo, taskID, "session-failed-claim-retry", "step1") + seedHandoffCarryToken(t, repo, taskID, stepID, carried, "stamp-retry") + svc := createTestService(repo, twoStepGetter(), newMockTaskRepo()) + wrapped := &failOnceHandoffClaimRepo{sessionExecutorStore: svc.repo} + svc.repo = wrapped + + once := newStepHandoffOnce() + text := svc.resolveStepHandoffText(ctx, once, taskID, stepID, true) + require.Empty(t, text, "the first, failing attempt must not deliver a handoff") + require.True(t, wrapped.failed, "expected the wrapped claim to have been invoked") + + text = svc.resolveStepHandoffText(ctx, once, taskID, stepID, true) + require.Equal(t, carried, text, "a retried attempt must claim the still-present token") +} + +// TestLaunchAfterOnEnterDispatch_FallbackDrainDeliversHandoff covers F22's +// fourth gap: the final fallback drain for a step with no auto_start_agent and +// no profile switch (e.g. a Review-shaped step) still carries the handoff. +func TestLaunchAfterOnEnterDispatch_FallbackDrainDeliversHandoff(t *testing.T) { + ctx := context.Background() + const ( + taskID = "task-fallback-drain" + sessionID = "session-fallback-drain" + stepID = "step-review" + queued = "drain via fallback" + carried = "fallback carried text" + ) + repo := setupTestRepo(t) + seedTaskAndSession(t, repo, taskID, sessionID, models.TaskSessionStateWaitingForInput) + seedHandoffCarryToken(t, repo, taskID, stepID, carried, "stamp-fallback") + agentMgr := &mockAgentManager{isAgentRunning: true, repoForExecutionLookup: repo} + svc := createTestServiceWithAgent(repo, newMockStepGetter(), newMockTaskRepo(), agentMgr) + svc.executor = executor.NewExecutor(agentMgr, repo, testLogger(), executor.ExecutorConfig{}) + seedExecutorRunning(t, repo, sessionID, taskID, "exec-fallback-drain") + + _, err := svc.messageQueue.QueueMessage(ctx, sessionID, taskID, queued, "", "user", false, nil) + require.NoError(t, err) + session, err := repo.GetTaskSession(ctx, sessionID) + require.NoError(t, err) + + // hasAutoStart=false, sessionSwitched=false: neither the ACP branch nor the + // implicit profile-switch branch applies, landing on the final fallback + // drain — the shape a step without auto_start_agent (e.g. Review) takes. + done := make(chan struct{}) + svc.onQueuedMessageExecutionComplete = func() { close(done) } + + step := &wfmodels.WorkflowStep{ID: stepID, WorkflowID: "wf1", Name: "Review"} + svc.launchAfterOnEnterDispatch(ctx, taskID, session, step, "task description", false, false, false) + + select { + case <-done: + case <-time.After(5 * time.Second): + t.Fatal("timed out waiting for the drained queue message to dispatch") + } + + if _, present := carryToken(t, repo, taskID); present { + t.Fatal("the final fallback drain must claim the token when it dispatches") + } + require.Len(t, agentMgr.capturedPrompts, 1) + prompt := agentMgr.capturedPrompts[0] + require.Contains(t, prompt, queued) + require.Contains(t, prompt, carried, "the final fallback drain must deliver the claimed handoff text") +} + +// TestLaunchAfterOnEnterDispatch_AsyncProfileSwitchFailureDrainDeliversHandoff +// covers F22's third gap: when the implicit profile-switch async launch fails +// to dispatch, the failure drain reuses the already-claimed handoff text (the +// shared stepHandoffOnce, not a fresh claim) and delivers it via the drained +// queued message. +func TestLaunchAfterOnEnterDispatch_AsyncProfileSwitchFailureDrainDeliversHandoff(t *testing.T) { + ctx := context.Background() + const ( + taskID = "task-profile-switch-drain" + sessionID = "session-profile-switch-drain" + stepID = "step-next" + queued = "queued after failed switch" + carried = "profile switch carried text" + ) + repo := setupTestRepo(t) + seedTaskAndSession(t, repo, taskID, sessionID, models.TaskSessionStateWaitingForInput) + seedHandoffCarryToken(t, repo, taskID, stepID, carried, "stamp-profile-switch") + agentMgr := &mockAgentManager{ + isAgentRunning: true, repoForExecutionLookup: repo, + promptErr: errors.New("simulated fatal profile switch prompt error"), + } + svc := createTestServiceWithAgent(repo, newMockStepGetter(), newMockTaskRepo(), agentMgr) + svc.executor = executor.NewExecutor(agentMgr, repo, testLogger(), executor.ExecutorConfig{}) + seedExecutorRunning(t, repo, sessionID, taskID, "exec-profile-switch-drain") + + _, err := svc.messageQueue.QueueMessage(ctx, sessionID, taskID, queued, "", "user", false, nil) + require.NoError(t, err) + session, err := repo.GetTaskSession(ctx, sessionID) + require.NoError(t, err) + + done := make(chan struct{}) + svc.onQueuedMessageExecutionComplete = func() { close(done) } + + // sessionSwitched=true with a non-empty step.Prompt and hasAutoStart=false + // selects the implicit profile-switch async goroutine (the design's + // AC-005-adjacent "profile switch failure" branch): the launch fails, then + // the failure drain must deliver the queued message with the handoff the + // launch attempt already claimed. + step := &wfmodels.WorkflowStep{ID: stepID, WorkflowID: "wf1", Name: "Next", Prompt: "please continue"} + svc.launchAfterOnEnterDispatch(ctx, taskID, session, step, "task description", false, false, true) + + select { + case <-done: + case <-time.After(5 * time.Second): + t.Fatal("timed out waiting for the queued message to execute after the failed profile-switch dispatch") + } + + require.GreaterOrEqual(t, len(agentMgr.capturedPrompts), 2, + "expected the failed profile-switch attempt plus the drained queued dispatch") + last := agentMgr.capturedPrompts[len(agentMgr.capturedPrompts)-1] + require.Contains(t, last, queued) + require.Contains(t, last, carried, "the drain must reuse the already-claimed handoff text") + if _, present := carryToken(t, repo, taskID); present { + t.Fatal("the token must have been claimed by the failed attempt") + } +} diff --git a/apps/backend/internal/orchestrator/step_handoff_carry_write_test.go b/apps/backend/internal/orchestrator/step_handoff_carry_write_test.go new file mode 100644 index 0000000000..72656a7fba --- /dev/null +++ b/apps/backend/internal/orchestrator/step_handoff_carry_write_test.go @@ -0,0 +1,385 @@ +package orchestrator + +import ( + "context" + "encoding/json" + "testing" + + "github.com/kandev/kandev/internal/task/models" + "github.com/kandev/kandev/internal/workflow/engine" + wfmodels "github.com/kandev/kandev/internal/workflow/models" +) + +func carryToken(t *testing.T, repo interface { + GetTask(ctx context.Context, id string) (*models.Task, error) +}, taskID string) (models.StepHandoffCarryToken, bool) { + t.Helper() + task, err := repo.GetTask(context.Background(), taskID) + if err != nil { + t.Fatalf("GetTask: %v", err) + } + raw, present := task.Metadata[models.MetaKeyStepHandoffCarry] + if !present { + return models.StepHandoffCarryToken{}, false + } + bytes, err := json.Marshal(raw) + if err != nil { + t.Fatalf("marshal carry token: %v", err) + } + var token models.StepHandoffCarryToken + if err := json.Unmarshal(bytes, &token); err != nil { + t.Fatalf("unmarshal carry token: %v", err) + } + return token, true +} + +// TestExecuteStepTransition_WritesHandoffCarryToken covers AC-001.2 on the +// legacy funnel: a consumed signal carrying a non-blank handoff is written as +// a carry token addressed to the destination step. +func TestExecuteStepTransition_WritesHandoffCarryToken(t *testing.T) { + ctx := context.Background() + repo := setupTestRepo(t) + seedSession(t, repo, "t1", "s1", "step1") + sg := twoStepGetter() + svc := createTestService(repo, sg, newMockTaskRepo()) + svc.stepHistoryRecorder = &fakeStepHistoryRecorder{} + + signal := models.PendingStepCompletionSignal{ + StepID: "step1", + Source: models.StepCompletionSourceAgent, + Summary: "did the work", + Handoff: "watch out for X", + } + if err := repo.SetSessionMetadataKey(ctx, "s1", models.SessionMetaKeyPendingStepCompletion, signal); err != nil { + t.Fatalf("seed pending signal: %v", err) + } + + svc.executeStepTransition(ctx, "t1", "s1", sg.steps["step1"], "step2", true) + + token, present := carryToken(t, repo, "t1") + if !present { + t.Fatal("expected a carry token to be written") + } + if token.Handoff != "watch out for X" || token.StepID != "step2" || token.Stamp == "" { + t.Fatalf("token = %+v, want handoff for step2 with a stamp", token) + } +} + +// TestExecuteStepTransition_BlankHandoffRemovesToken covers AC-001.2's other +// half: a consumed signal with no handoff text removes any existing token +// rather than writing a blank one. +func TestExecuteStepTransition_BlankHandoffRemovesToken(t *testing.T) { + ctx := context.Background() + repo := setupTestRepo(t) + seedSession(t, repo, "t1", "s1", "step1") + if err := repo.SetTaskMetadataKey(ctx, "t1", models.MetaKeyStepHandoffCarry, models.StepHandoffCarryToken{ + Handoff: "stale", StepID: "step2", Stamp: "stale-stamp", + }); err != nil { + t.Fatalf("seed stale token: %v", err) + } + sg := twoStepGetter() + svc := createTestService(repo, sg, newMockTaskRepo()) + svc.stepHistoryRecorder = &fakeStepHistoryRecorder{} + + signal := models.PendingStepCompletionSignal{StepID: "step1", Source: models.StepCompletionSourceAgent, Summary: "done"} + if err := repo.SetSessionMetadataKey(ctx, "s1", models.SessionMetaKeyPendingStepCompletion, signal); err != nil { + t.Fatalf("seed pending signal: %v", err) + } + + svc.executeStepTransition(ctx, "t1", "s1", sg.steps["step1"], "step2", true) + + if _, present := carryToken(t, repo, "t1"); present { + t.Fatal("expected the stale token to be removed when the consumed signal has no handoff") + } +} + +// TestExecuteStepTransition_OnTurnStartDoesNotTouchToken covers AC-001.2a: a +// non-consuming (on_turn_start) transition must not write or remove the +// token, since only the consuming transition may act on it. +func TestExecuteStepTransition_OnTurnStartDoesNotTouchToken(t *testing.T) { + ctx := context.Background() + repo := setupTestRepo(t) + seedSession(t, repo, "t1", "s1", "step1") + if err := repo.SetTaskMetadataKey(ctx, "t1", models.MetaKeyStepHandoffCarry, models.StepHandoffCarryToken{ + Handoff: "keep me", StepID: "step3", Stamp: "kept-stamp", + }); err != nil { + t.Fatalf("seed existing token: %v", err) + } + sg := twoStepGetter() + svc := createTestService(repo, sg, newMockTaskRepo()) + svc.stepHistoryRecorder = &fakeStepHistoryRecorder{} + + signal := models.PendingStepCompletionSignal{StepID: "step1", Source: models.StepCompletionSourceAgent, Summary: "premature"} + if err := repo.SetSessionMetadataKey(ctx, "s1", models.SessionMetaKeyPendingStepCompletion, signal); err != nil { + t.Fatalf("seed pending signal: %v", err) + } + + svc.executeStepTransition(ctx, "t1", "s1", sg.steps["step1"], "step2", false) + + token, present := carryToken(t, repo, "t1") + if !present || token.StepID != "step3" || token.Handoff != "keep me" { + t.Fatalf("on_turn_start transition must leave the existing token untouched, got present=%v token=%+v", present, token) + } +} + +// TestExecuteStepTransition_QueuedTransitionStillWritesHandoffCarryToken +// covers AC-001.11's legacy-funnel half: a transition that lands the task in +// a WIP-full queued state still commits — the task's step already changed, +// only dispatch is deferred until a queue promotion admits it. The carry +// token (and the audit metadata) must be captured at commit time, because +// StartSessionForWorkflowStep claims the token at promotion and has no other +// way to learn one was ever written. +func TestExecuteStepTransition_QueuedTransitionStillWritesHandoffCarryToken(t *testing.T) { + ctx := context.Background() + repo := setupTestRepo(t) + seedSession(t, repo, "t1", "s1", "step1") + if err := repo.CreateTask(ctx, &models.Task{ + ID: "occupant", + WorkspaceID: "ws1", + WorkflowID: "wf1", + WorkflowStepID: "step2", + Title: "Occupant", + State: "TODO", + Priority: "medium", + }); err != nil { + t.Fatalf("create occupant: %v", err) + } + + steps := newMockStepGetter() + fromStep := &wfmodels.WorkflowStep{ID: "step1", WorkflowID: "wf1", Name: "Source"} + steps.steps["step2"] = &wfmodels.WorkflowStep{ + ID: "step2", WorkflowID: "wf1", Name: "Limited", WIPLimit: 1, + } + svc := createTestService(repo, steps, newMockTaskRepo()) + recorder := &fakeStepHistoryRecorder{} + svc.stepHistoryRecorder = recorder + + signal := models.PendingStepCompletionSignal{ + StepID: "step1", + Source: models.StepCompletionSourceAgent, + Summary: "did the work", + Handoff: "watch out for X", + } + if err := repo.SetSessionMetadataKey(ctx, "s1", models.SessionMetaKeyPendingStepCompletion, signal); err != nil { + t.Fatalf("seed pending signal: %v", err) + } + + svc.executeStepTransition(ctx, "t1", "s1", fromStep, "step2", true) + + task, err := repo.GetTask(ctx, "t1") + if err != nil { + t.Fatalf("load task: %v", err) + } + if task.WorkflowStepID != "step2" || task.WIPAdmitted || task.QueuedForStepID != "step2" { + t.Fatalf("queued task placement: step=%q admitted=%t queue=%q", task.WorkflowStepID, task.WIPAdmitted, task.QueuedForStepID) + } + + token, present := carryToken(t, repo, "t1") + if !present { + t.Fatal("a queued transition must still write the carry token so a later queue promotion can claim it") + } + if token.Handoff != "watch out for X" || token.StepID != "step2" { + t.Fatalf("token = %+v, want handoff for step2", token) + } + + calls := recorder.Calls() + if len(calls) != 1 { + t.Fatalf("expected 1 recorded transition even though dispatch is deferred, got %d", len(calls)) + } + if calls[0].metadata["signal_handoff"] != "watch out for X" { + t.Errorf("metadata[signal_handoff] = %v, want 'watch out for X'", calls[0].metadata["signal_handoff"]) + } + + session, err := repo.GetTaskSession(ctx, "s1") + if err != nil { + t.Fatalf("load session: %v", err) + } + if _, has := models.LoadPendingStepSignal(session.Metadata); has { + t.Fatal("the consumed signal bag must be cleared even when the transition's dispatch is deferred by the queue") + } +} + +// TestApplyEngineTransition_WritesHandoffCarryToken covers AC-001.2 on the +// engine funnel, proving both consuming-transition sites carry the token. +func TestApplyEngineTransition_WritesHandoffCarryToken(t *testing.T) { + ctx := context.Background() + repo := setupTestRepo(t) + seedSession(t, repo, "t1", "s1", "step1") + sg := twoStepGetter() + svc := createTestService(repo, sg, newMockTaskRepo()) + svc.SetWorkflowStepGetter(sg) + svc.stepHistoryRecorder = &fakeStepHistoryRecorder{} + onEnterDone := make(chan struct{}) + svc.onProcessOnEnterComplete = func() { close(onEnterDone) } + + signal := models.PendingStepCompletionSignal{ + StepID: "step1", + Source: models.StepCompletionSourceAgent, + Summary: "engine path done", + Handoff: "engine handoff text", + } + if err := repo.SetSessionMetadataKey(ctx, "s1", models.SessionMetaKeyPendingStepCompletion, signal); err != nil { + t.Fatalf("seed pending signal: %v", err) + } + session, err := repo.GetTaskSession(ctx, "s1") + if err != nil { + t.Fatalf("GetTaskSession: %v", err) + } + + result := engine.HandleResult{Transitioned: true, FromStepID: "step1", ToStepID: "step2"} + transitioned := svc.applyEngineTransition(ctx, "t1", session, result, engine.TriggerOnTurnComplete, "desc", true) + if !transitioned { + t.Fatalf("expected transition to apply") + } + <-onEnterDone + + token, present := carryToken(t, repo, "t1") + if !present { + t.Fatal("expected a carry token to be written by the engine funnel") + } + if token.StepID != "step2" { + // The dispatch side may have already claimed it as part of on_enter + // processing once wired; either the token is still addressed to + // step2 or it has already been claimed (removed). Both are + // acceptable outcomes here — what must NOT happen is a token + // addressed to any other step. + t.Fatalf("token = %+v, want step2", token) + } +} + +// TestApplyEngineTransition_QueuedTransitionWritesHandoffCarryTokenAtAdmission +// covers the engine funnel's queue boundary: the carry token must be part of +// the same admission write as the queued destination, so promotion cannot +// start before the token exists. +func TestApplyEngineTransition_QueuedTransitionWritesHandoffCarryTokenAtAdmission(t *testing.T) { + ctx := context.Background() + repo := setupTestRepo(t) + seedSession(t, repo, "t1", "s1", "step1") + if err := repo.CreateTask(ctx, &models.Task{ + ID: "occupant-engine", + WorkspaceID: "ws1", + WorkflowID: "wf1", + WorkflowStepID: "step2", + Title: "Occupant", + State: "TODO", + Priority: "medium", + }); err != nil { + t.Fatalf("create occupant: %v", err) + } + + steps := newMockStepGetter() + steps.steps["step1"] = &wfmodels.WorkflowStep{ID: "step1", WorkflowID: "wf1", Name: "Source", Position: 0} + steps.steps["step2"] = &wfmodels.WorkflowStep{ID: "step2", WorkflowID: "wf1", Name: "Limited", Position: 1, WIPLimit: 1} + svc := createTestService(repo, steps, newMockTaskRepo()) + svc.SetWorkflowStepGetter(steps) + svc.stepHistoryRecorder = &fakeStepHistoryRecorder{} + + signal := models.PendingStepCompletionSignal{ + StepID: "step1", + Source: models.StepCompletionSourceAgent, + Summary: "engine queued work", + Handoff: "carry before promotion", + } + if err := repo.SetSessionMetadataKey(ctx, "s1", models.SessionMetaKeyPendingStepCompletion, signal); err != nil { + t.Fatalf("seed pending signal: %v", err) + } + session, err := repo.GetTaskSession(ctx, "s1") + if err != nil { + t.Fatalf("GetTaskSession: %v", err) + } + + result := engine.HandleResult{Transitioned: true, FromStepID: "step1", ToStepID: "step2"} + if !svc.applyEngineTransition(ctx, "t1", session, result, engine.TriggerOnTurnComplete, "desc", true) { + t.Fatal("expected queued transition to apply") + } + + task, err := repo.GetTask(ctx, "t1") + if err != nil { + t.Fatalf("load queued task: %v", err) + } + if task.WIPAdmitted || task.QueuedForStepID != "step2" { + t.Fatalf("expected task queued for step2, got admitted=%t queue=%q", task.WIPAdmitted, task.QueuedForStepID) + } + token, present := carryToken(t, repo, "t1") + if !present || token.Handoff != signal.Handoff || token.StepID != "step2" { + t.Fatalf("queued engine token = present=%v token=%+v, want step2 handoff", present, token) + } +} + +// TestApplyEngineTransition_OnTurnStartDoesNotTouchToken covers AC-001.2a on +// the engine funnel: a non-consuming trigger must not touch the token. +func TestApplyEngineTransition_OnTurnStartDoesNotTouchToken(t *testing.T) { + ctx := context.Background() + repo := setupTestRepo(t) + seedSession(t, repo, "t1", "s1", "step1") + if err := repo.SetTaskMetadataKey(ctx, "t1", models.MetaKeyStepHandoffCarry, models.StepHandoffCarryToken{ + Handoff: "keep me", StepID: "step3", Stamp: "kept-stamp", + }); err != nil { + t.Fatalf("seed existing token: %v", err) + } + sg := twoStepGetter() + svc := createTestService(repo, sg, newMockTaskRepo()) + svc.SetWorkflowStepGetter(sg) + svc.stepHistoryRecorder = &fakeStepHistoryRecorder{} + + signal := models.PendingStepCompletionSignal{StepID: "step1", Source: models.StepCompletionSourceAgent, Summary: "premature"} + if err := repo.SetSessionMetadataKey(ctx, "s1", models.SessionMetaKeyPendingStepCompletion, signal); err != nil { + t.Fatalf("seed pending signal: %v", err) + } + session, err := repo.GetTaskSession(ctx, "s1") + if err != nil { + t.Fatalf("GetTaskSession: %v", err) + } + + result := engine.HandleResult{Transitioned: true, FromStepID: "step1", ToStepID: "step2"} + transitioned := svc.applyEngineTransition(ctx, "t1", session, result, engine.TriggerOnTurnStart, "desc", false) + if !transitioned { + t.Fatalf("expected transition to apply") + } + + token, present := carryToken(t, repo, "t1") + if !present || token.StepID != "step3" || token.Handoff != "keep me" { + t.Fatalf("on_turn_start transition must leave the existing token untouched, got present=%v token=%+v", present, token) + } +} + +// TestApplyEngineTransition_GuardedDecisionDoesNotTouchToken is the F15 +// guarded-decision carve-out: a quorum/approval decision carries +// TriggerOnTurnComplete too, with no turn having ended, so a trigger-only +// gate would wipe an unclaimed token the instant a reviewer approves. Only +// the compound `sessionLifecycle && trigger == TriggerOnTurnComplete` gate +// must apply. +func TestApplyEngineTransition_GuardedDecisionDoesNotTouchToken(t *testing.T) { + ctx := context.Background() + repo := setupTestRepo(t) + seedSession(t, repo, "t1", "s1", "step1") + if err := repo.SetTaskMetadataKey(ctx, "t1", models.MetaKeyStepHandoffCarry, models.StepHandoffCarryToken{ + Handoff: "unclaimed", StepID: "step3", Stamp: "unclaimed-stamp", + }); err != nil { + t.Fatalf("seed existing token: %v", err) + } + sg := twoStepGetter() + svc := createTestService(repo, sg, newMockTaskRepo()) + svc.SetWorkflowStepGetter(sg) + svc.stepHistoryRecorder = &fakeStepHistoryRecorder{} + + session, err := repo.GetTaskSession(ctx, "s1") + if err != nil { + t.Fatalf("GetTaskSession: %v", err) + } + + result := engine.HandleResult{Transitioned: true, FromStepID: "step1", ToStepID: "step2"} + applied := svc.applyEngineTransitionWithCommitMode( + ctx, "t1", session, result, engine.TriggerOnTurnComplete, "desc", + transitionLifecycleGuardedDecision, + func(commitCtx context.Context) (bool, error) { return true, nil }, + ) + if !applied { + t.Fatalf("expected guarded decision transition to apply") + } + + token, present := carryToken(t, repo, "t1") + if !present || token.StepID != "step3" || token.Handoff != "unclaimed" { + t.Fatalf("guarded decision must leave the unclaimed token untouched, got present=%v token=%+v", present, token) + } +} diff --git a/apps/backend/internal/orchestrator/step_history_handoff_blockers_test.go b/apps/backend/internal/orchestrator/step_history_handoff_blockers_test.go new file mode 100644 index 0000000000..79e784f836 --- /dev/null +++ b/apps/backend/internal/orchestrator/step_history_handoff_blockers_test.go @@ -0,0 +1,169 @@ +package orchestrator + +import ( + "context" + "testing" + + "github.com/kandev/kandev/internal/task/models" + "github.com/kandev/kandev/internal/workflow/engine" + wfmodels "github.com/kandev/kandev/internal/workflow/models" +) + +type rejectingAsyncStepHistoryRecorder struct { + fakeStepHistoryRecorder +} + +func (*rejectingAsyncStepHistoryRecorder) EnqueueStepTransition( + string, string, string, wfmodels.StepTransitionTrigger, *string, map[string]interface{}, +) bool { + return false +} + +// TestRecordAutoStepTransition_FallsBackWhenHistoryQueueIsFull covers the +// signal-audit durability boundary: a bounded asynchronous writer may reject +// an enqueue, but the consumed signal's blockers and handoff must still be +// written through the bounded synchronous path. +func TestRecordAutoStepTransition_FallsBackWhenHistoryQueueIsFull(t *testing.T) { + svc := &Service{logger: testLogger()} + recorder := &rejectingAsyncStepHistoryRecorder{} + svc.stepHistoryRecorder = recorder + + svc.recordAutoStepTransition(context.Background(), "session-1", "step-a", "step-b", &models.PendingStepCompletionSignal{ + Source: models.StepCompletionSourceAgent, + Summary: "completed", + Handoff: "carry this", + Blockers: "needs review", + }, wfmodels.StepTransitionTriggerAutoComplete) + + calls := recorder.Calls() + if len(calls) != 1 { + t.Fatalf("expected synchronous fallback to record one transition, got %d", len(calls)) + } + if calls[0].metadata["signal_handoff"] != "carry this" || calls[0].metadata["signal_blockers"] != "needs review" { + t.Fatalf("fallback metadata = %#v, want signal handoff and blockers", calls[0].metadata) + } +} + +// TestExecuteStepTransition_RecordsHandoffAndBlockersMetadata covers +// AC-002.1: the legacy funnel's audit metadata gains signal_blockers and +// signal_handoff alongside signal_source/signal_summary. +func TestExecuteStepTransition_RecordsHandoffAndBlockersMetadata(t *testing.T) { + ctx := context.Background() + repo := setupTestRepo(t) + seedSession(t, repo, "t1", "s1", "step1") + sg := twoStepGetter() + svc := createTestService(repo, sg, newMockTaskRepo()) + recorder := &fakeStepHistoryRecorder{} + svc.stepHistoryRecorder = recorder + + signal := models.PendingStepCompletionSignal{ + StepID: "step1", + Source: models.StepCompletionSourceAgent, + Summary: "did the work", + Handoff: "watch out for X", + Blockers: "needs a design decision", + } + if err := repo.SetSessionMetadataKey(ctx, "s1", models.SessionMetaKeyPendingStepCompletion, signal); err != nil { + t.Fatalf("seed pending signal: %v", err) + } + + svc.executeStepTransition(ctx, "t1", "s1", sg.steps["step1"], "step2", true) + + calls := recorder.Calls() + if len(calls) != 1 { + t.Fatalf("expected 1 recorded transition, got %d", len(calls)) + } + got := calls[0] + if got.metadata["signal_handoff"] != "watch out for X" { + t.Errorf("metadata[signal_handoff] = %v, want 'watch out for X'", got.metadata["signal_handoff"]) + } + if got.metadata["signal_blockers"] != "needs a design decision" { + t.Errorf("metadata[signal_blockers] = %v, want 'needs a design decision'", got.metadata["signal_blockers"]) + } +} + +// TestExecuteStepTransition_OmitsBlankHandoffAndBlockers covers AC-002.2: an +// empty or whitespace-only handoff/blockers is omitted from the audit +// metadata entirely rather than written as an empty entry. +func TestExecuteStepTransition_OmitsBlankHandoffAndBlockers(t *testing.T) { + ctx := context.Background() + repo := setupTestRepo(t) + seedSession(t, repo, "t1", "s1", "step1") + sg := twoStepGetter() + svc := createTestService(repo, sg, newMockTaskRepo()) + recorder := &fakeStepHistoryRecorder{} + svc.stepHistoryRecorder = recorder + + signal := models.PendingStepCompletionSignal{ + StepID: "step1", + Source: models.StepCompletionSourceAgent, + Summary: "did the work", + } + if err := repo.SetSessionMetadataKey(ctx, "s1", models.SessionMetaKeyPendingStepCompletion, signal); err != nil { + t.Fatalf("seed pending signal: %v", err) + } + + svc.executeStepTransition(ctx, "t1", "s1", sg.steps["step1"], "step2", true) + + calls := recorder.Calls() + if len(calls) != 1 { + t.Fatalf("expected 1 recorded transition, got %d", len(calls)) + } + got := calls[0] + if _, ok := got.metadata["signal_handoff"]; ok { + t.Errorf("metadata must omit signal_handoff when blank, got %v", got.metadata["signal_handoff"]) + } + if _, ok := got.metadata["signal_blockers"]; ok { + t.Errorf("metadata must omit signal_blockers when blank, got %v", got.metadata["signal_blockers"]) + } +} + +// TestApplyEngineTransition_RecordsHandoffAndBlockersMetadata covers the +// engine funnel's half of AC-002.1, proving both consuming-transition sites +// were updated (the design's named drift risk). +func TestApplyEngineTransition_RecordsHandoffAndBlockersMetadata(t *testing.T) { + ctx := context.Background() + repo := setupTestRepo(t) + seedSession(t, repo, "t1", "s1", "step1") + sg := twoStepGetter() + svc := createTestService(repo, sg, newMockTaskRepo()) + svc.SetWorkflowStepGetter(sg) + recorder := &fakeStepHistoryRecorder{} + svc.stepHistoryRecorder = recorder + onEnterDone := make(chan struct{}) + svc.onProcessOnEnterComplete = func() { close(onEnterDone) } + + signal := models.PendingStepCompletionSignal{ + StepID: "step1", + Source: models.StepCompletionSourceAgent, + Summary: "engine path done", + Handoff: "engine handoff text", + Blockers: "engine blocker text", + } + if err := repo.SetSessionMetadataKey(ctx, "s1", models.SessionMetaKeyPendingStepCompletion, signal); err != nil { + t.Fatalf("seed pending signal: %v", err) + } + session, err := repo.GetTaskSession(ctx, "s1") + if err != nil { + t.Fatalf("GetTaskSession: %v", err) + } + + result := engine.HandleResult{Transitioned: true, FromStepID: "step1", ToStepID: "step2"} + transitioned := svc.applyEngineTransition(ctx, "t1", session, result, engine.TriggerOnTurnComplete, "desc", true) + if !transitioned { + t.Fatalf("expected transition to apply") + } + <-onEnterDone + + calls := recorder.Calls() + if len(calls) != 1 { + t.Fatalf("expected 1 recorded transition, got %d", len(calls)) + } + got := calls[0] + if got.metadata["signal_handoff"] != "engine handoff text" { + t.Errorf("metadata[signal_handoff] = %v, want 'engine handoff text'", got.metadata["signal_handoff"]) + } + if got.metadata["signal_blockers"] != "engine blocker text" { + t.Errorf("metadata[signal_blockers] = %v, want 'engine blocker text'", got.metadata["signal_blockers"]) + } +} diff --git a/apps/backend/internal/orchestrator/task_operations.go b/apps/backend/internal/orchestrator/task_operations.go index 85a08fc292..53759ac878 100644 --- a/apps/backend/internal/orchestrator/task_operations.go +++ b/apps/backend/internal/orchestrator/task_operations.go @@ -2509,7 +2509,23 @@ func (s *Service) StartSessionForWorkflowStep(ctx context.Context, taskID, sessi return nil } - _, err = s.PromptTask(ctx, taskID, sessionID, effectivePrompt, "", stepPlanMode, nil, false) + // Claimed after the actionability decision above, over content that + // excludes the handoff text, then appended last. Queue promotion and + // manual auto-start dispatch once with no replacement launch, so no + // shared stepHandoffOnce is needed here. + handoffText, _ := s.claimStepHandoffCarryText(ctx, taskID, workflowStepID) + effectivePrompt = appendStepHandoffToPrompt(effectivePrompt, handoffText) + composedLaunchPrompt := appendStepHandoffToPrompt(promptForEmptinessCheck, handoffText) + + // effectivePrompt is already fully composed for this step entry (handoff + // included): if promptTask's own internal ErrExecutionNotFound recovery + // fires, it must reuse this composed prompt rather than recomposing from + // the destination step's own template and discarding the handoff. + _, err = s.promptTask(ctx, taskID, sessionID, effectivePrompt, "", stepPlanMode, nil, false, promptTaskOptions{ + promptAlreadyComposed: true, + fallbackLaunchPrompt: composedLaunchPrompt, + fallbackRetryPrompt: effectivePrompt, + }) if err != nil { return fmt.Errorf("failed to prompt session: %w", err) } @@ -4221,6 +4237,21 @@ type promptTaskOptions struct { // waits for the turn to finish. Automation callers use it to bind durable // attempt identity to the exact turn. onAccepted func(turnID string) + // promptAlreadyComposed and fallbackRetryPrompt mirror the composed-prompt + // seam autoStartStepPrompt's own ErrExecutionNotFound branch uses (see + // fallbackFreshLaunchOnMissingExecution). When promptAlreadyComposed is + // true, handlePromptDispatchFailure's own internal ErrExecutionNotFound + // recovery relaunches via startCreatedSessionWithComposedPrompt + // (fallbackRetryPrompt as its dispatch value) instead of the public + // StartCreatedSession, so a caller that already composed the prompt itself + // (e.g. appending a claimed step handoff) is not silently recomposed from + // the destination step's own template. + promptAlreadyComposed bool + // fallbackLaunchPrompt is the fully composed prompt for fresh-launch + // recovery. The normal dispatch still receives the raw prompt so it can + // apply session transforms exactly once. + fallbackLaunchPrompt string + fallbackRetryPrompt string } type promptDispatchOutcome struct { @@ -4477,6 +4508,11 @@ func (s *Service) promptTask(ctx context.Context, taskID, sessionID string, prom ) dispatchAccepted, publicationErr := dispatchOutcome.snapshot() if err != nil { + // Missing-execution recovery reacquires the cancel guard while it resets + // the session. Release dispatch admission before entering that path. + if releaseDispatchGuard != nil { + releaseDispatchGuard() + } return s.finishPromptDispatchFailure( ctx, taskID, sessionID, prompt, planMode, resumedForPrompt, attachments, rollback, options, err, foregroundDispatch, dispatchAccepted, publicationErr, @@ -4511,6 +4547,7 @@ func (s *Service) finishPromptDispatchFailure( failureResult, failureErr := s.handlePromptDispatchFailure( failureCtx, taskID, sessionID, prompt, planMode, resumedForPrompt, attachments, rollback, options.lifecyclePrompt, dispatchAccepted, promptErr, + options.promptAlreadyComposed, options.fallbackLaunchPrompt, options.fallbackRetryPrompt, ) return failureResult, wrapAcceptedPromptDispatchFailure( dispatchAccepted, @@ -4980,6 +5017,11 @@ func (s *Service) restoreLifecycleTaskState( // it falls back to a fresh launch instead of surfacing the error to the // caller. Otherwise — or if that fallback launch itself fails — it // delegates to handlePromptError for the caller-facing result. +// promptAlreadyComposed/fallbackRetryPrompt are the caller's promptTaskOptions +// values, forwarded to fallbackFreshLaunchOnMissingExecution so a caller that +// already composed the dispatch prompt (e.g. autoStartStepPrompt, which +// appends a claimed step handoff) is not silently recomposed from the +// destination step's own template by this internal recovery. func (s *Service) handlePromptDispatchFailure( ctx context.Context, taskID, sessionID, prompt string, @@ -4989,14 +5031,21 @@ func (s *Service) handlePromptDispatchFailure( lifecyclePrompt bool, dispatchAccepted bool, promptErr error, + promptAlreadyComposed bool, + fallbackLaunchPrompt string, + fallbackRetryPrompt string, ) (*PromptResult, error) { if resumedForPrompt && !dispatchAccepted && !rollback.reservedTurnAccepted && rollback.reservedTurn == nil && errors.Is(promptErr, executor.ErrExecutionNotFound) { s.logger.Warn("prompt after lazy resume hit missing execution; falling back to fresh launch", zap.String("task_id", taskID), zap.String("session_id", sessionID)) + fallbackPrompt := prompt + if fallbackLaunchPrompt != "" { + fallbackPrompt = fallbackLaunchPrompt + } if freshErr := s.fallbackFreshLaunchOnMissingExecution( - ctx, taskID, sessionID, prompt, planMode, nil, attachments, nil, + ctx, taskID, sessionID, fallbackPrompt, promptAlreadyComposed, fallbackRetryPrompt, planMode, nil, attachments, nil, ); freshErr == nil { return &PromptResult{}, nil } else { diff --git a/apps/backend/internal/orchestrator/task_pull_request_target_prompt_test.go b/apps/backend/internal/orchestrator/task_pull_request_target_prompt_test.go index a3ba25e36c..eb4da106da 100644 --- a/apps/backend/internal/orchestrator/task_pull_request_target_prompt_test.go +++ b/apps/backend/internal/orchestrator/task_pull_request_target_prompt_test.go @@ -105,7 +105,7 @@ func TestAutoStartStepPrompt_ResetContextReinjectsSnapshottedPullRequestTarget(t svc.messageCreator = messages require.NoError(t, svc.autoStartStepPrompt( - ctx, "task1", session, step, "Review the release", false, false, + ctx, "task1", session, step, "Review the release", false, false, nil, )) require.Len(t, messages.userMessages, 1) require.Contains(t, messages.userMessages[0].content, `gh pr create --base "main"`) diff --git a/apps/backend/internal/orchestrator/workflow_store.go b/apps/backend/internal/orchestrator/workflow_store.go index a7ec6039ce..bf5fe95009 100644 --- a/apps/backend/internal/orchestrator/workflow_store.go +++ b/apps/backend/internal/orchestrator/workflow_store.go @@ -328,6 +328,23 @@ func (s *workflowStore) applyTransition(ctx context.Context, taskID, sessionID, delete(task.Metadata, models.MetaKeyQueuedMoveExitCompleted) delete(task.Metadata, models.MetaKeyQueuePromotionPending) } + // The on_turn_complete transition consumes the source session's signal. + // Put its carry token on this task snapshot before admission so a queued + // destination cannot be promoted between the transition commit and a later + // metadata write. + if trigger == engine.TriggerOnTurnComplete { + var consumedSignal *models.PendingStepCompletionSignal + session, sessionErr := s.repo.GetTaskSession(ctx, sessionID) + if sessionErr != nil { + s.logger.Debug("failed to load session for step handoff carry", + zap.String("session_id", sessionID), zap.Error(sessionErr)) + } else if session != nil { + if signal, has := models.LoadPendingStepSignal(session.Metadata); has && signal.StepID == fromStepID { + consumedSignal = &signal + } + setStepHandoffCarryMetadata(task, toStepID, consumedSignal) + } + } task.UpdatedAt = time.Now().UTC() // engine_transition applies only when no outer caller already declared a // trigger — applyPendingMove sets mcp_deferred_move before reaching this diff --git a/apps/backend/internal/task/models/models.go b/apps/backend/internal/task/models/models.go index dd7960dced..2583a6a215 100644 --- a/apps/backend/internal/task/models/models.go +++ b/apps/backend/internal/task/models/models.go @@ -215,8 +215,24 @@ const ( // whose Routine workflow start step has no other transition to carry it // into an auto_start_agent evaluation. MetaKeyAutoStartOnCreate = "auto_start_on_create" + // MetaKeyStepHandoffCarry is a single-slot, task-scoped token carrying one + // consuming transition's completion handoff exactly one hop, to the next + // step's first dispatched prompt. Its value is a StepHandoffCarryToken. + // Recording it replaces any existing token (single-slot by construction); + // claiming it removes it. See REQ-TASKS-SIGNAL-PAYLOAD-DELIVERY-001. + MetaKeyStepHandoffCarry = "step_handoff_carry" ) +// StepHandoffCarryToken is the JSON shape stored under +// tasks.metadata[MetaKeyStepHandoffCarry]. Stamp is a fresh unique value +// (uuid.NewString()) minted on every write, compared by the claim's +// compare-and-swap alongside StepID; it must never be content-derived. +type StepHandoffCarryToken struct { + Handoff string `json:"handoff"` + StepID string `json:"step_id"` + Stamp string `json:"stamp"` +} + // IsAgentTitlePending reports whether task metadata contains the durable // pending title marker. JSON rehydration produces bool values, while a // few in-process callers may provide typed metadata, so only an explicit true diff --git a/apps/backend/internal/task/models/public_metadata.go b/apps/backend/internal/task/models/public_metadata.go index ffc451207b..05e5f2d73d 100644 --- a/apps/backend/internal/task/models/public_metadata.go +++ b/apps/backend/internal/task/models/public_metadata.go @@ -3,13 +3,14 @@ package models import "maps" // PublicTaskMetadata returns a detached task metadata projection for API -// responses. Deferred launch attribution is server-owned and must never expose -// the creator's raw user ID or the internal recency marker. +// responses. Deferred-launch attribution and step-handoff carry are +// server-owned and must not expose their internal state to clients. func PublicTaskMetadata(metadata map[string]interface{}) map[string]interface{} { if metadata == nil { return nil } public := maps.Clone(metadata) + delete(public, MetaKeyStepHandoffCarry) deferred, ok := public[MetaKeyDeferredLaunch].(map[string]interface{}) if !ok { return public diff --git a/apps/backend/internal/task/models/public_metadata_test.go b/apps/backend/internal/task/models/public_metadata_test.go new file mode 100644 index 0000000000..4e02b7a2bf --- /dev/null +++ b/apps/backend/internal/task/models/public_metadata_test.go @@ -0,0 +1,25 @@ +package models + +import "testing" + +func TestPublicTaskMetadataRedactsStepHandoffCarry(t *testing.T) { + metadata := map[string]interface{}{ + "ordinary": "visible", + MetaKeyStepHandoffCarry: StepHandoffCarryToken{ + Handoff: "private handoff", + StepID: "step-next", + Stamp: "private-stamp", + }, + } + + public := PublicTaskMetadata(metadata) + if _, ok := public[MetaKeyStepHandoffCarry]; ok { + t.Fatalf("public metadata must not expose %q", MetaKeyStepHandoffCarry) + } + if got := public["ordinary"]; got != "visible" { + t.Fatalf("ordinary metadata = %v, want visible", got) + } + if _, ok := metadata[MetaKeyStepHandoffCarry]; !ok { + t.Fatal("redaction must not mutate stored metadata") + } +} diff --git a/apps/backend/internal/task/repository/sqlite/step_handoff_carry_claim_postgres_test.go b/apps/backend/internal/task/repository/sqlite/step_handoff_carry_claim_postgres_test.go new file mode 100644 index 0000000000..16598fc685 --- /dev/null +++ b/apps/backend/internal/task/repository/sqlite/step_handoff_carry_claim_postgres_test.go @@ -0,0 +1,125 @@ +package sqlite + +import ( + "context" + "encoding/json" + "testing" + "time" + + "github.com/kandev/kandev/internal/task/models" + "github.com/kandev/kandev/internal/testutil" +) + +// TestPostgresTakeTaskMetadataKeyIfDestinationStepUsesJSONB proves +// TakeTaskMetadataKeyIfDestinationStep's dialect.IsPostgres branch +// (jsonb_extract_path_text / #-) behaves the same as the SQLite json_extract +// path already covered in step_handoff_carry_claim_test.go: a matching +// step_id and stamp claims and returns the token, a token naming another +// step is left in place, and a stale stamp on the same step leaves a +// same-step replacement token in place. +func TestPostgresTakeTaskMetadataKeyIfDestinationStepUsesJSONB(t *testing.T) { + db := testutil.OpenIsolatedPostgres(t, testutil.PostgresDSNFromEnv(t)) + repo, err := NewWithDB(db, db, nil) + if err != nil { + t.Fatalf("init postgres schema: %v", err) + } + ctx := context.Background() + now := time.Now().UTC() + + seed := func(taskID string, metadata string) { + if _, err := db.Exec(db.Rebind(` + INSERT INTO tasks (id, title, metadata, created_at, updated_at) + VALUES (?, ?, ?, ?, ?) + `), taskID, "Postgres CAS task", metadata, now, now); err != nil { + t.Fatalf("seed task %s: %v", taskID, err) + } + } + + t.Run("match claims and returns", func(t *testing.T) { + const taskID = "task-pg-handoff-carry-match" + seed(taskID, `{"step_handoff_carry":{"handoff":"watch the migration","step_id":"step-b","stamp":"stamp-1"}}`) + + raw, ok, err := repo.TakeTaskMetadataKeyIfDestinationStep( + ctx, taskID, models.MetaKeyStepHandoffCarry, "step-b", "stamp-1", + ) + if err != nil { + t.Fatalf("TakeTaskMetadataKeyIfDestinationStep: %v", err) + } + if !ok { + t.Fatal("expected the matching token to be claimed") + } + var token models.StepHandoffCarryToken + if err := json.Unmarshal(raw, &token); err != nil { + t.Fatalf("unmarshal claimed token: %v", err) + } + if token.Handoff != "watch the migration" || token.StepID != "step-b" || token.Stamp != "stamp-1" { + t.Fatalf("claimed token = %#v, want the seeded token", token) + } + + task, err := repo.GetTask(ctx, taskID) + if err != nil { + t.Fatalf("reload task: %v", err) + } + if _, present := task.Metadata[models.MetaKeyStepHandoffCarry]; present { + t.Fatal("claimed token must be removed from task metadata") + } + }) + + t.Run("wrong step leaves token in place", func(t *testing.T) { + const taskID = "task-pg-handoff-carry-wrong-step" + seed(taskID, `{"step_handoff_carry":{"handoff":"for step C","step_id":"step-c","stamp":"stamp-2"}}`) + + raw, ok, err := repo.TakeTaskMetadataKeyIfDestinationStep( + ctx, taskID, models.MetaKeyStepHandoffCarry, "step-b", "stamp-2", + ) + if err != nil { + t.Fatalf("TakeTaskMetadataKeyIfDestinationStep: %v", err) + } + if ok || raw != nil { + t.Fatalf("expected no claim for a token naming another step, got ok=%v raw=%s", ok, raw) + } + + task, err := repo.GetTask(ctx, taskID) + if err != nil { + t.Fatalf("reload task: %v", err) + } + stored, _ := task.Metadata[models.MetaKeyStepHandoffCarry].(map[string]interface{}) + if stored["step_id"] != "step-c" { + t.Fatalf("stored token = %#v, want step-c untouched", stored) + } + }) + + t.Run("stale stamp leaves replacement in place", func(t *testing.T) { + const taskID = "task-pg-handoff-carry-stale-stamp" + seed(taskID, `{"step_handoff_carry":{"handoff":"stale text","step_id":"step-b","stamp":"stamp-old"}}`) + + // Simulate a replacement landing between the caller's advisory read + // and its claim attempt: same step, new stamp, new text. + if err := repo.SetTaskMetadataKey(ctx, taskID, models.MetaKeyStepHandoffCarry, models.StepHandoffCarryToken{ + Handoff: "fresh text", + StepID: "step-b", + Stamp: "stamp-new", + }); err != nil { + t.Fatalf("simulate replacement: %v", err) + } + + raw, ok, err := repo.TakeTaskMetadataKeyIfDestinationStep( + ctx, taskID, models.MetaKeyStepHandoffCarry, "step-b", "stamp-old", + ) + if err != nil { + t.Fatalf("TakeTaskMetadataKeyIfDestinationStep: %v", err) + } + if ok || raw != nil { + t.Fatalf("expected no claim against a stale stamp, got ok=%v raw=%s", ok, raw) + } + + task, err := repo.GetTask(ctx, taskID) + if err != nil { + t.Fatalf("reload task: %v", err) + } + stored, _ := task.Metadata[models.MetaKeyStepHandoffCarry].(map[string]interface{}) + if stored["stamp"] != "stamp-new" { + t.Fatalf("stored token = %#v, want the replacement (stamp-new) untouched", stored) + } + }) +} diff --git a/apps/backend/internal/task/repository/sqlite/step_handoff_carry_claim_test.go b/apps/backend/internal/task/repository/sqlite/step_handoff_carry_claim_test.go new file mode 100644 index 0000000000..8bd020c4ed --- /dev/null +++ b/apps/backend/internal/task/repository/sqlite/step_handoff_carry_claim_test.go @@ -0,0 +1,156 @@ +package sqlite + +import ( + "context" + "encoding/json" + "testing" + + "github.com/kandev/kandev/internal/task/models" +) + +// TestTakeTaskMetadataKeyIfDestinationStep_MatchClaimsAndReturns covers the +// happy path: a token naming the step being entered, with the stamp read +// alongside it, is removed and its content returned. +func TestTakeTaskMetadataKeyIfDestinationStep_MatchClaimsAndReturns(t *testing.T) { + repo := newRepoForMetadataCASTests(t) + seedMetadataCASTask(t, repo, map[string]interface{}{ + models.MetaKeyStepHandoffCarry: models.StepHandoffCarryToken{ + Handoff: "watch the migration", + StepID: "step-b", + Stamp: "stamp-1", + }, + }) + ctx := context.Background() + + raw, ok, err := repo.TakeTaskMetadataKeyIfDestinationStep( + ctx, casTaskID, models.MetaKeyStepHandoffCarry, "step-b", "stamp-1", + ) + if err != nil { + t.Fatalf("TakeTaskMetadataKeyIfDestinationStep: %v", err) + } + if !ok { + t.Fatal("expected the matching token to be claimed") + } + var token models.StepHandoffCarryToken + if err := json.Unmarshal(raw, &token); err != nil { + t.Fatalf("unmarshal claimed token: %v", err) + } + if token.Handoff != "watch the migration" || token.StepID != "step-b" || token.Stamp != "stamp-1" { + t.Fatalf("claimed token = %#v, want the seeded token", token) + } + + if _, found := metadataValue(t, repo, models.MetaKeyStepHandoffCarry); found { + t.Fatal("claimed token must be removed from task metadata") + } +} + +// TestTakeTaskMetadataKeyIfDestinationStep_WrongStepLeavesTokenInPlace +// covers AC-001.5 against the race it actually guards: a caller can only ever +// hold a stamp read alongside a stepID before the claim attempt runs, so the +// regression case is a token that was REPLACED, naming a different +// destination, between that read and the claim — not merely "no token for +// this step ever existed". Seed a token for step-b, overwrite it with a fresh +// one for step-c (simulating a transition that landed in between), then claim +// with the original step-b/stamp-1 pair: the mismatch must leave the step-c +// replacement untouched so a later entry into step-c can still receive it. +func TestTakeTaskMetadataKeyIfDestinationStep_WrongStepLeavesTokenInPlace(t *testing.T) { + repo := newRepoForMetadataCASTests(t) + seedMetadataCASTask(t, repo, map[string]interface{}{ + models.MetaKeyStepHandoffCarry: models.StepHandoffCarryToken{ + Handoff: "for step B", + StepID: "step-b", + Stamp: "stamp-1", + }, + }) + ctx := context.Background() + + if err := repo.SetTaskMetadataKey(ctx, casTaskID, models.MetaKeyStepHandoffCarry, models.StepHandoffCarryToken{ + Handoff: "for step C", + StepID: "step-c", + Stamp: "stamp-2", + }); err != nil { + t.Fatalf("simulate replacement to a different destination step: %v", err) + } + + raw, ok, err := repo.TakeTaskMetadataKeyIfDestinationStep( + ctx, casTaskID, models.MetaKeyStepHandoffCarry, "step-b", "stamp-1", + ) + if err != nil { + t.Fatalf("TakeTaskMetadataKeyIfDestinationStep: %v", err) + } + if ok || raw != nil { + t.Fatalf("expected no claim for a token naming another step, got ok=%v raw=%s", ok, raw) + } + + stored, found := metadataValue(t, repo, models.MetaKeyStepHandoffCarry) + if !found { + t.Fatal("the step-c replacement must remain in place") + } + storedMap, _ := stored.(map[string]interface{}) + if storedMap["step_id"] != "step-c" || storedMap["stamp"] != "stamp-2" { + t.Fatalf("stored token = %#v, want the step-c replacement untouched", stored) + } +} + +// TestTakeTaskMetadataKeyIfDestinationStep_StaleStampLeavesReplacementInPlace +// covers the same-step race the stamp compare exists for: a caller holding a +// stale stamp for the CORRECT step must not remove a token that was replaced +// in between, and must not deliver the stale (already-superseded) text. +func TestTakeTaskMetadataKeyIfDestinationStep_StaleStampLeavesReplacementInPlace(t *testing.T) { + repo := newRepoForMetadataCASTests(t) + seedMetadataCASTask(t, repo, map[string]interface{}{ + models.MetaKeyStepHandoffCarry: models.StepHandoffCarryToken{ + Handoff: "stale text", + StepID: "step-b", + Stamp: "stamp-old", + }, + }) + ctx := context.Background() + + // Simulate a replacement landing between the caller's advisory read and + // its claim attempt: same step, new stamp, new text. + if err := repo.SetTaskMetadataKey(ctx, casTaskID, models.MetaKeyStepHandoffCarry, models.StepHandoffCarryToken{ + Handoff: "fresh text", + StepID: "step-b", + Stamp: "stamp-new", + }); err != nil { + t.Fatalf("simulate replacement: %v", err) + } + + raw, ok, err := repo.TakeTaskMetadataKeyIfDestinationStep( + ctx, casTaskID, models.MetaKeyStepHandoffCarry, "step-b", "stamp-old", + ) + if err != nil { + t.Fatalf("TakeTaskMetadataKeyIfDestinationStep: %v", err) + } + if ok || raw != nil { + t.Fatalf("expected no claim against a stale stamp, got ok=%v raw=%s", ok, raw) + } + + stored, found := metadataValue(t, repo, models.MetaKeyStepHandoffCarry) + if !found { + t.Fatal("the replacement token must survive a stale-stamp claim attempt") + } + storedMap, _ := stored.(map[string]interface{}) + if storedMap["stamp"] != "stamp-new" { + t.Fatalf("stored token = %#v, want the replacement (stamp-new) untouched", stored) + } +} + +// TestTakeTaskMetadataKeyIfDestinationStep_NoTokenIsANoOp covers the empty +// case: nothing is stored, nothing is claimed, no error. +func TestTakeTaskMetadataKeyIfDestinationStep_NoTokenIsANoOp(t *testing.T) { + repo := newRepoForMetadataCASTests(t) + seedMetadataCASTask(t, repo, map[string]interface{}{}) + ctx := context.Background() + + raw, ok, err := repo.TakeTaskMetadataKeyIfDestinationStep( + ctx, casTaskID, models.MetaKeyStepHandoffCarry, "step-b", "stamp-1", + ) + if err != nil { + t.Fatalf("TakeTaskMetadataKeyIfDestinationStep: %v", err) + } + if ok || raw != nil { + t.Fatalf("expected no claim when no token exists, got ok=%v raw=%s", ok, raw) + } +} diff --git a/apps/backend/internal/task/repository/sqlite/task.go b/apps/backend/internal/task/repository/sqlite/task.go index c634c0dacc..f2df8ea415 100644 --- a/apps/backend/internal/task/repository/sqlite/task.go +++ b/apps/backend/internal/task/repository/sqlite/task.go @@ -1045,6 +1045,70 @@ func (r *Repository) RemoveTaskMetadataKeyIfStamp( return rows > 0, err } +// TakeTaskMetadataKeyIfDestinationStep removes one metadata object only when +// its nested step_id and stamp both equal the caller's expectations, and +// returns the object's raw JSON on a successful claim. The advisory read +// happens before the conditional removal; since stamp is a fresh unique value +// minted on every write (never content-derived), a removal that matches both +// step_id and stamp can only have removed the exact object just read. +func (r *Repository) TakeTaskMetadataKeyIfDestinationStep( + ctx context.Context, + taskID, key, expectedStepID, expectedStamp string, +) (json.RawMessage, bool, error) { + if strings.TrimSpace(expectedStepID) == "" || strings.TrimSpace(expectedStamp) == "" { + return nil, false, nil + } + task, err := r.GetTask(ctx, taskID) + if err != nil { + return nil, false, err + } + value, present := task.Metadata[key] + if !present { + return nil, false, nil + } + raw, err := json.Marshal(value) + if err != nil { + return nil, false, err + } + + var query string + var args []interface{} + if dialect.IsPostgres(r.db.DriverName()) { + query = ` + UPDATE tasks + SET metadata = (CASE WHEN metadata IS NULL OR metadata = 'null' OR metadata = '' THEN '{}'::jsonb ELSE metadata::jsonb END #- ARRAY[?]::text[])::text, updated_at = ? + WHERE id = ? + AND jsonb_extract_path_text(CASE WHEN metadata IS NULL OR metadata = 'null' OR metadata = '' THEN '{}'::jsonb ELSE metadata::jsonb END, ?, 'step_id') = ? + AND jsonb_extract_path_text(CASE WHEN metadata IS NULL OR metadata = 'null' OR metadata = '' THEN '{}'::jsonb ELSE metadata::jsonb END, ?, 'stamp') = ? + ` + args = []interface{}{key, time.Now().UTC(), taskID, key, expectedStepID, key, expectedStamp} + } else { + path := jsonPath(key) + stepIDPath := path + ".step_id" + stampPath := path + ".stamp" + query = ` + UPDATE tasks + SET metadata = json_remove(CASE WHEN metadata IS NULL OR metadata = 'null' OR metadata = '' THEN '{}' ELSE metadata END, ?), updated_at = ? + WHERE id = ? + AND json_extract(CASE WHEN metadata IS NULL OR metadata = 'null' OR metadata = '' THEN '{}' ELSE metadata END, ?) = ? + AND json_extract(CASE WHEN metadata IS NULL OR metadata = 'null' OR metadata = '' THEN '{}' ELSE metadata END, ?) = ? + ` + args = []interface{}{path, time.Now().UTC(), taskID, stepIDPath, expectedStepID, stampPath, expectedStamp} + } + result, err := r.db.ExecContext(ctx, r.db.Rebind(query), args...) + if err != nil { + return nil, false, err + } + rows, err := result.RowsAffected() + if err != nil { + return nil, false, err + } + if rows == 0 { + return nil, false, nil + } + return raw, true, nil +} + func (r *Repository) removeTaskMetadataKeyWithExecutor( ctx context.Context, exec taskSessionExecutor, diff --git a/apps/backend/internal/task/service/service.go b/apps/backend/internal/task/service/service.go index 343702a637..cf1d49d4fd 100644 --- a/apps/backend/internal/task/service/service.go +++ b/apps/backend/internal/task/service/service.go @@ -287,7 +287,7 @@ type StepHistoryRecorder interface { } type asyncStepHistoryRecorder interface { - EnqueueStepTransition(sessionID, fromStepID, toStepID string, trigger wfmodels.StepTransitionTrigger, actorID *string, metadata map[string]interface{}) + EnqueueStepTransition(sessionID, fromStepID, toStepID string, trigger wfmodels.StepTransitionTrigger, actorID *string, metadata map[string]interface{}) bool } // ContributionDestinationPreparer is an internal creation-time hook for a diff --git a/apps/backend/internal/task/service/service_step_handoff_metadata_test.go b/apps/backend/internal/task/service/service_step_handoff_metadata_test.go new file mode 100644 index 0000000000..6754d67aa0 --- /dev/null +++ b/apps/backend/internal/task/service/service_step_handoff_metadata_test.go @@ -0,0 +1,49 @@ +package service + +import ( + "testing" + + "github.com/kandev/kandev/internal/task/models" +) + +func TestProtectedTaskMetadataUpdatePreservesStepHandoffCarry(t *testing.T) { + existing := map[string]interface{}{ + "ordinary": "old", + models.MetaKeyStepHandoffCarry: models.StepHandoffCarryToken{ + Handoff: "trusted handoff", + StepID: "step-next", + Stamp: "trusted-stamp", + }, + } + requested := map[string]interface{}{ + "ordinary": "new", + models.MetaKeyStepHandoffCarry: models.StepHandoffCarryToken{ + Handoff: "forged handoff", + StepID: "step-next", + Stamp: "forged-stamp", + }, + } + + updated := protectedTaskMetadataUpdate(existing, requested) + if got := updated["ordinary"]; got != "new" { + t.Fatalf("ordinary metadata = %v, want new", got) + } + if got := updated[models.MetaKeyStepHandoffCarry]; got != existing[models.MetaKeyStepHandoffCarry] { + t.Fatalf("carry token = %#v, want existing token", got) + } +} + +func TestProtectedTaskMetadataUpdateRejectsNewStepHandoffCarry(t *testing.T) { + requested := map[string]interface{}{ + models.MetaKeyStepHandoffCarry: models.StepHandoffCarryToken{ + Handoff: "forged handoff", + StepID: "step-next", + Stamp: "forged-stamp", + }, + } + + updated := protectedTaskMetadataUpdate(nil, requested) + if _, ok := updated[models.MetaKeyStepHandoffCarry]; ok { + t.Fatalf("new carry token must not be accepted from client metadata") + } +} diff --git a/apps/backend/internal/task/service/service_task_metadata.go b/apps/backend/internal/task/service/service_task_metadata.go index c162409da3..2a0a93e492 100644 --- a/apps/backend/internal/task/service/service_task_metadata.go +++ b/apps/backend/internal/task/service/service_task_metadata.go @@ -18,9 +18,9 @@ func cloneTaskMetadata(metadata map[string]interface{}) map[string]interface{} { } // protectedTaskMetadataUpdate applies a generic metadata replacement while -// keeping the deferred launch intent owned by the server. The HTTP PATCH -// surface may replace ordinary metadata, but it cannot create, replace, or -// remove the launch record that carries deferred-start ownership. +// keeping server-managed deferred-launch and step-handoff records owned by the +// server. The HTTP PATCH surface may replace ordinary metadata, but it cannot +// create, replace, or remove either record. func protectedTaskMetadataUpdate(existing, requested map[string]interface{}) map[string]interface{} { updated := cloneTaskMetadata(requested) if updated == nil { @@ -31,5 +31,10 @@ func protectedTaskMetadataUpdate(existing, requested map[string]interface{}) map } else { delete(updated, models.MetaKeyDeferredLaunch) } + if carry, ok := existing[models.MetaKeyStepHandoffCarry]; ok { + updated[models.MetaKeyStepHandoffCarry] = carry + } else { + delete(updated, models.MetaKeyStepHandoffCarry) + } return updated } diff --git a/apps/backend/internal/task/service/service_workflow.go b/apps/backend/internal/task/service/service_workflow.go index fe2879f558..a077caa7ad 100644 --- a/apps/backend/internal/task/service/service_workflow.go +++ b/apps/backend/internal/task/service/service_workflow.go @@ -357,7 +357,8 @@ func (s *Service) updateTaskStateIfSessionState( return true, nil } -// UpdateTaskMetadata updates only the metadata of a task (merges with existing) +// UpdateTaskMetadata updates ordinary task metadata while preserving +// server-managed deferred-launch and step-handoff records. func (s *Service) UpdateTaskMetadata(ctx context.Context, id string, metadata map[string]interface{}) (*models.Task, error) { if err := s.authorizeTaskScope(ctx, id, authz.ScopeTaskWrite); err != nil { return nil, err @@ -374,7 +375,7 @@ func (s *Service) UpdateTaskMetadata(ctx context.Context, id string, metadata ma for k, v := range metadata { // Deferred launch ownership is server-managed. Preserve it even if a // future metadata endpoint forwards the whole request map here. - if k == models.MetaKeyDeferredLaunch { + if k == models.MetaKeyDeferredLaunch || k == models.MetaKeyStepHandoffCarry { continue } task.Metadata[k] = v @@ -1024,10 +1025,13 @@ func (s *Service) recordQueuedPromotion(ctx context.Context, taskID, fromStepID, return } if asyncRecorder, ok := s.stepHistoryRecorder.(asyncStepHistoryRecorder); ok { - asyncRecorder.EnqueueStepTransition(session.ID, fromStepID, toStepID, wfmodels.StepTransitionTriggerQueuePromotion, nil, nil) - return + if asyncRecorder.EnqueueStepTransition(session.ID, fromStepID, toStepID, wfmodels.StepTransitionTriggerQueuePromotion, nil, nil) { + return + } } - if err := s.stepHistoryRecorder.CreateStepTransition(ctx, session.ID, fromStepID, toStepID, wfmodels.StepTransitionTriggerQueuePromotion, nil, nil); err != nil { + writeCtx, cancel := context.WithTimeout(context.WithoutCancel(ctx), constants.StepHistoryWriteTimeout) + defer cancel() + if err := s.stepHistoryRecorder.CreateStepTransition(writeCtx, session.ID, fromStepID, toStepID, wfmodels.StepTransitionTriggerQueuePromotion, nil, nil); err != nil { s.logger.Warn("failed to record queued task promotion", zap.String("task_id", taskID), zap.Error(err)) } } @@ -1372,8 +1376,9 @@ func (s *Service) recordManualStepTransition(ctx context.Context, sessionID, fro } } if asyncRecorder, ok := s.stepHistoryRecorder.(asyncStepHistoryRecorder); ok { - asyncRecorder.EnqueueStepTransition(sessionID, fromStepID, toStepID, trigger, actorID, nil) - return + if asyncRecorder.EnqueueStepTransition(sessionID, fromStepID, toStepID, trigger, actorID, nil) { + return + } } // The step change is already durably persisted by the time this runs. // Use a detached, bounded context so a cancelled request context (client diff --git a/apps/backend/internal/workflow/repository/session_step_history_test.go b/apps/backend/internal/workflow/repository/session_step_history_test.go index 27cf735bca..80b2a80156 100644 --- a/apps/backend/internal/workflow/repository/session_step_history_test.go +++ b/apps/backend/internal/workflow/repository/session_step_history_test.go @@ -108,6 +108,54 @@ func TestCreateHistory_NullableFromStepAndActor(t *testing.T) { } } +// TestListHistoryBySession_PreMigrationRowOmitsHandoffAndBlockersKeys covers +// AC-002.7: a row written before this capability shipped (metadata carrying +// only signal_source/signal_summary, the pre-existing shape) round-trips +// through the JSON metadata column unchanged — signal_handoff and +// signal_blockers must stay absent keys, not materialize as empty-string or +// null entries, so a consumer's "absent-by-default" read is correct without +// needing a migration to backfill them. +func TestListHistoryBySession_PreMigrationRowOmitsHandoffAndBlockersKeys(t *testing.T) { + repo, sqlxDB := setupTestRepoWithDB(t) + ctx := context.Background() + + if _, err := sqlxDB.Exec(`INSERT INTO task_sessions (id) VALUES ('sess-pre-migration')`); err != nil { + t.Fatalf("failed to insert test session: %v", err) + } + + history := &models.SessionStepHistory{ + SessionID: "sess-pre-migration", + ToStepID: "step-old", + Trigger: models.StepTransitionTriggerManual, + Metadata: map[string]interface{}{ + "signal_source": "agent", + "signal_summary": "old-shaped row from before handoff/blockers existed", + }, + } + if err := repo.CreateHistory(ctx, history); err != nil { + t.Fatalf("CreateHistory failed: %v", err) + } + + result, err := repo.ListHistoryBySession(ctx, "sess-pre-migration") + if err != nil { + t.Fatalf("ListHistoryBySession failed: %v", err) + } + if len(result) != 1 { + t.Fatalf("expected 1 history row, got %d", len(result)) + } + + got := result[0] + if got.Metadata["signal_summary"] != "old-shaped row from before handoff/blockers existed" { + t.Errorf("Metadata[signal_summary] = %v, want the seeded pre-migration summary", got.Metadata["signal_summary"]) + } + if _, ok := got.Metadata["signal_handoff"]; ok { + t.Errorf("Metadata[signal_handoff] = %v, want the key absent for a pre-migration row", got.Metadata["signal_handoff"]) + } + if _, ok := got.Metadata["signal_blockers"]; ok { + t.Errorf("Metadata[signal_blockers] = %v, want the key absent for a pre-migration row", got.Metadata["signal_blockers"]) + } +} + func TestListHistoryBySession_OrderedByCreatedAt(t *testing.T) { repo, sqlxDB := setupTestRepoWithDB(t) ctx := context.Background() diff --git a/apps/backend/internal/workflow/service/service.go b/apps/backend/internal/workflow/service/service.go index 8ae75eb914..7ca3826a2a 100644 --- a/apps/backend/internal/workflow/service/service.go +++ b/apps/backend/internal/workflow/service/service.go @@ -142,23 +142,26 @@ func (s *Service) drainHistoryQueue() { } // EnqueueStepTransition records transition history outside the caller's -// event-reader path. The queue is bounded. A full queue, or an enqueue after -// Close has begun, is logged as a dropped best-effort telemetry row while the -// workflow mutation itself succeeds. -func (s *Service) EnqueueStepTransition(sessionID, fromStepID, toStepID string, trigger models.StepTransitionTrigger, actorID *string, metadata map[string]interface{}) { +// event-reader path. The queue is bounded. It returns false when a full queue, +// an empty session ID, or shutdown prevents enqueueing, so callers carrying +// signal data can use a bounded synchronous fallback instead of silently +// losing that payload. +func (s *Service) EnqueueStepTransition(sessionID, fromStepID, toStepID string, trigger models.StepTransitionTrigger, actorID *string, metadata map[string]interface{}) bool { if sessionID == "" { - return + return false } s.historyMu.RLock() defer s.historyMu.RUnlock() if s.historyClosed { s.logger.Warn("dropped step transition enqueued after shutdown", zap.String("session_id", sessionID)) - return + return false } select { case s.historyQueue <- historyWrite{sessionID: sessionID, fromStepID: fromStepID, toStepID: toStepID, trigger: trigger, actorID: actorID, metadata: metadata}: + return true default: s.logger.Warn("step transition history queue is full", zap.String("session_id", sessionID)) + return false } } @@ -601,8 +604,9 @@ func (s *Service) ReorderSteps(ctx context.Context, workflowID string, stepIDs [ // CreateStepTransition creates a new step transition history entry. metadata // is optional (nil for a plain move) and carries the ADR 0015 consumed-signal -// shape ({"signal_source", "signal_summary"}) when a completion signal drove -// the transition. +// shape ({"signal_source", "signal_summary"}, plus "signal_handoff" and +// "signal_blockers" when the signal carried a non-blank value for either) +// when a completion signal drove the transition. func (s *Service) CreateStepTransition(ctx context.Context, sessionID string, fromStepID, toStepID string, trigger models.StepTransitionTrigger, actorID *string, metadata map[string]interface{}) error { history := &models.SessionStepHistory{ SessionID: sessionID, diff --git a/apps/web/e2e/tests/kanban/wip-overflow-queue.spec.ts b/apps/web/e2e/tests/kanban/wip-overflow-queue.spec.ts index fce37a2bbc..9e4d4c3f7d 100644 --- a/apps/web/e2e/tests/kanban/wip-overflow-queue.spec.ts +++ b/apps/web/e2e/tests/kanban/wip-overflow-queue.spec.ts @@ -9,6 +9,7 @@ test("dragging into a feeder wakes an open pull target without reload", async ({ apiClient, seedData, }) => { + await testPage.setViewportSize({ width: 1440, height: 900 }); const workflow = await apiClient.createWorkflow(seedData.workspaceId, "Feeder Move Workflow"); const sourceStep = await apiClient.createWorkflowStep(workflow.id, "C", 0, { is_start_step: true, diff --git a/docs/decisions/0015-explicit-completion-signal-for-auto-advance.md b/docs/decisions/0015-explicit-completion-signal-for-auto-advance.md index dd3780ba06..3a426523ef 100644 --- a/docs/decisions/0015-explicit-completion-signal-for-auto-advance.md +++ b/docs/decisions/0015-explicit-completion-signal-for-auto-advance.md @@ -1,6 +1,6 @@ # 0015: Explicit completion signal for auto-advance -**Status:** proposed (amended 2026-08-14) +**Status:** proposed (amended 2026-08-14, 2026-09-05) **Date:** 2026-06-04 **Area:** backend, frontend @@ -8,6 +8,15 @@ > [ADR-2026-08-14-current-turn-clarification-ownership](2026-08-14-current-turn-clarification-ownership.md): > a detached clarification remains a hard-pause barrier only while its turn remains current. > That ownership rule stands independently of this proposal's future status. +> +> Amended 2026-09-05: `handoff` now carries one hop beyond the bag into the next step's +> dispatched prompt, and `blockers` (with `handoff`) now rides the existing step-transition +> audit metadata alongside `signal_source`/`signal_summary`, retrievable through +> `GET /sessions/:id/workflow/history`. The "persisted in the bag only, not on the wire" claim +> below (Mechanism, step 1) describes the signal-publish event only and no longer describes the +> full lifecycle of either field. See +> `docs/specs/tasks/requirements/workflow-completion-signal-payload-delivery.md` and its +> system design for the carry/claim mechanism and the audit-metadata addition. ## Context @@ -61,7 +70,7 @@ Today, a workflow step's `on_turn_complete` actions (most commonly `move_to_next - **Idempotent.** Repeated calls within the same step are no-ops: if `existing != nil && existing.StepID == currentStepID`, the MCP tool returns `{accepted: false, reason: "already_signaled"}` without overwriting. - **Audit (implemented for the trigger-enum call sites).** Consumed-signal context is persisted on the transition row (`SessionStepHistory.Metadata["signal_source"]` ∈ {`"agent"`, `"manual_fallback"`} plus `Metadata["signal_summary"]`), written by `orchestrator.Service.recordAutoStepTransition` immediately before the bag is cleared, for both the workflow-engine (`applyEngineTransition`) and legacy (`executeStepTransition`) transition paths. The three `StepTransitionTrigger` funnels are wired: manual moves (`StepTransitionTriggerManual`, from `task/service.MoveTaskWithOptions`, including the deferred `move_task_kandev` path via `orchestrator.applyPendingMove`), approval-gated moves (`StepTransitionTriggerApproval`, from `applyApprovalStepTransition`), and orchestrator-driven moves (`StepTransitionTriggerAutoComplete`, covering on_turn_complete, on_turn_start, and on_children_completed via `applyEngineTransition`/`executeStepTransition`) — but only an on_turn_complete transition that actually consumed a matching pending signal carries the metadata above; other automated transitions record with no metadata. Cancelled signals (overwritten by user reply) are still not retained — the bag is cleared, not archived. - Transition ownership is now explicit at the mutation boundaries. Generic `task/service.UpdateTask` changes use `task_update`; queue-promotion paths use `queue_promotion`; engine and legacy orchestrator paths preserve their event trigger; and human or agent move paths carry explicit actor provenance. The workflow service owns the history writer. Runtime callers enqueue rows on its bounded worker, which drains during service shutdown. This is best-effort telemetry: a full queue or database failure is logged and does not roll back an already-committed task mutation. A durable audit ledger would require an outbox transaction in a future change. + Transition ownership is now explicit at the mutation boundaries. Generic `task/service.UpdateTask` changes use `task_update`; queue-promotion paths use `queue_promotion`; engine and legacy orchestrator paths preserve their event trigger; and human or agent move paths carry explicit actor provenance. The workflow service owns the history writer. Runtime callers enqueue rows on its bounded worker, which drains during service shutdown; a full or closed worker falls back to a bounded synchronous write. Database failure or a shutdown deadline remains best-effort telemetry and does not roll back an already-committed task mutation. A durable audit ledger would require an outbox transaction in a future change. - **Chat visibility (deferred).** Surfacing a `step_complete_signaled` system message in the existing message stream is planned but not yet emitted. Today the only user-visible cue is the next-step transition itself; the bag remains the only truth source. 3. **System-prompt injection.** When `auto_advance_requires_signal` is true on the current workflow step, `internal/sysprompt/` prepends a short instruction block to the agent's system prompt at launch / resume time, in the same path that already injects MCP tool descriptions. The text is fixed, terse, and points at the tool by name: diff --git a/docs/decisions/INDEX.md b/docs/decisions/INDEX.md index 3b0026f56f..f617cc580e 100644 --- a/docs/decisions/INDEX.md +++ b/docs/decisions/INDEX.md @@ -20,7 +20,7 @@ Read individual ADRs for full context. Create new ones via `/record decision` or | 0012 | [Service-only UI self-update](0012-service-only-self-update.md) | accepted | backend, frontend, cli | 2026-05-29 | | 0013 | [Multi-branch task support — N (repo, branch) pairs per task](0013-multi-branch-tasks.md) | accepted | backend, frontend | 2026-06-01 | | 0014 | [Per-CLI MCP server injection for passthrough mode](0014-passthrough-mcp-injection-strategies.md) | accepted | backend | 2026-05-29 | -| 0015 | [Explicit completion signal for auto-advance](0015-explicit-completion-signal-for-auto-advance.md) | proposed (amended 2026-08-14) | backend, frontend | 2026-06-04 | +| 0015 | [Explicit completion signal for auto-advance](0015-explicit-completion-signal-for-auto-advance.md) | proposed (amended 2026-08-14, 2026-09-05) | backend, frontend | 2026-06-04 | | 0016 | [Read-only absolute file paths](0016-observed-external-file-reads.md) | accepted | backend | 2026-06-14 | | 0017 | [Resource metrics sampling](0017-resource-metrics-sampling.md) | accepted | backend, frontend, protocol | 2026-06-14 | | 0018 | [Runtime settings overrides](0018-runtime-settings-overrides.md) | accepted (amended 2026-08-11) | backend, frontend, cli | 2026-06-14 | diff --git a/docs/specs/tasks/README.md b/docs/specs/tasks/README.md index 35902de881..67bc03883b 100644 --- a/docs/specs/tasks/README.md +++ b/docs/specs/tasks/README.md @@ -102,6 +102,7 @@ signals, and task-scoped scheduling contracts. - [User Question Turn Boundary](requirements/user-question-turn-boundary.md) - [WIP Limits and Visible Overflow Queues](requirements/wip-limit-pull-system.md) - [Tasks Without Repositories](requirements/without-repositories.md) +- [Workflow completion-signal payload delivery](requirements/workflow-completion-signal-payload-delivery.md) - [Cancelled Turn Completion](requirements/workflow-cancelled-turn-completion.md) - [Workflow Cycle Guardrails](requirements/workflow-cycle-guardrails.md) - [Workflow Duplication](requirements/workflow-duplication.md) @@ -161,6 +162,7 @@ signals, and task-scoped scheduling contracts. - [Task Create Launch Preview](system-design/task-create-launch-preview.md) - [Task priority visibility](system-design/task-priority-visibility.md) - [WIP Limits and Visible Overflow Queues](system-design/wip-limit-pull-system.md) +- [Workflow completion-signal payload delivery](system-design/workflow-completion-signal-payload-delivery.md) - [Workflow quorum decision recording](system-design/workflow-quorum-decision-recording.md) - [Workflow Step Agent Start Ownership](system-design/workflow-step-agent-start-ownership.md) - [Workflow Step Fixed-Profile Routing](system-design/workflow-step-fixed-profile-routing.md) diff --git a/docs/specs/tasks/requirements/workflow-completion-signal-payload-delivery.md b/docs/specs/tasks/requirements/workflow-completion-signal-payload-delivery.md new file mode 100644 index 0000000000..7bd2cefabd --- /dev/null +++ b/docs/specs/tasks/requirements/workflow-completion-signal-payload-delivery.md @@ -0,0 +1,318 @@ +--- +status: draft +system: tasks +created: 2026-09-04 +owners: + - kandev +--- + +# Workflow completion-signal payload delivery Requirements + +## Overview + +`step_complete_kandev` accepts `summary`, `handoff` and `blockers`; only `summary` +survives the transition it triggers, the orchestrator having lifted it onto the +audit row before deleting the signal bag. `tasks` owns the contract: the durable +artifacts are the session signal bag and the step-transition audit row. +Measured evidence, ADR citations, provenance, per-requirement framing, and the +code shapes behind every criterion are in the paired system design, +`docs/specs/tasks/system-design/workflow-completion-signal-payload-delivery.md`. + +## Terminology + +- **Completion signal:** the `PendingStepCompletionSignal` written to + `TaskSession.Metadata` by `step_complete_kandev` or the manual fallback. +- **Completion handoff:** the `handoff` argument of a completion signal, and the + value this capability delivers. Not the queued hand-off message. +- **Queued hand-off message:** a pre-existing, unrelated message-queue entry a + `move_task_kandev` call can attach, already merged into a step entry prompt + after the step's own content. Different provenance and lifetime; unchanged here. +- **Consuming transition:** an orchestrator-driven step transition that both runs + on the turn-completion trigger AND carries the session lifecycle of a turn + actually ending. The trigger value alone is not the test: guarded quorum-decision + re-evaluation reuses the same turn-completion trigger without a turn having + completed, and is excluded by the session-lifecycle half. Transitions on other + triggers, including turn start and children completed, manual moves, approvals, + and guarded quorum decisions, are not consuming transitions. +- **Consumed signal:** the completion signal a consuming transition finds for the + step it is leaving, when it commits. A consuming transition may find none. +- **Transition audit record:** the `session_step_history` row a transition writes, + whose `metadata` already carries `signal_source` and `signal_summary`. +- **Handoff carry token:** a single-slot, task-scoped record holding one consumed + signal's completion handoff and the step it addresses. It is the `tasks.metadata` + key `step_handoff_carry`, an object with `handoff` (the bounded text), `step_id` + (the next step's identifier) and `stamp` (a fresh unique value per token write, + which the claim compares). +- **Step entry:** one attempt to put a task to work on a step it has entered, + from a dispatch path's start to a dispatched prompt or a decision not to + dispatch. It may compose more than one prompt when a launch is replaced after + a failure. +- **Step entry prompt:** the prompt composed for a step entry. +- **Next step:** a consuming transition's destination step. + +## Prior art + +The wiki leg ran and returned nothing useful; the vendor leg did not run, its +tool being unreachable. Neither informed this document; receipts and the +precedents followed are in the paired system design. + +## Requirements + +### REQ-TASKS-SIGNAL-PAYLOAD-DELIVERY-001: A completed step's completion handoff reaches the next step's agent exactly once + +#### Acceptance criteria + +- **AC-TASKS-SIGNAL-PAYLOAD-DELIVERY-001.1:** When a consuming transition + commits and its consumed signal carries a non-empty completion handoff, the + system shall record a handoff carry token holding that handoff text and the + next step's identifier. +- **AC-TASKS-SIGNAL-PAYLOAD-DELIVERY-001.2:** When a consuming transition + commits and its consumed signal carries an empty or whitespace-only completion + handoff, or the transition found no signal, the system shall remove any + existing handoff carry token for that task, so a handoff never survives a + later consuming transition that wrote none. +- **AC-TASKS-SIGNAL-PAYLOAD-DELIVERY-001.2a:** A transition that is not a + consuming transition shall neither record nor remove a handoff carry token, so + an unclaimed token survives any turn-start transition, children-completed + transition, manual move, approval move, or guarded quorum decision occurring + before the step is entered. +- **AC-TASKS-SIGNAL-PAYLOAD-DELIVERY-001.3:** The system shall keep at most one + handoff carry token per task. Recording a token shall replace any existing + token rather than append to it, so no accumulation across steps is possible. +- **AC-TASKS-SIGNAL-PAYLOAD-DELIVERY-001.4:** When a branch will send the agent + something per -001.6c, the system shall claim the task's handoff carry + token in a single atomic operation that removes and returns it ONLY IF the + stored token names the step being entered, and otherwise removes nothing and + returns nothing. The destination-step comparison shall be evaluated inside that + one operation, against the stored value; any earlier read is advisory only, so a + token replaced between that read and the claim is neither delivered nor + destroyed. When two step entries race for one token, exactly one shall receive + it and the other none. +- **AC-TASKS-SIGNAL-PAYLOAD-DELIVERY-001.5:** The system shall deliver a handoff + carry token only to an entry into the step it names. When the task's token names + the step being entered, the system shall claim it per -001.4 and include its + handoff text in the step entry prompt. When it names any other step, the system + shall leave it in place unclaimed and compose the prompt with no handoff text, + so a later entry into the step it does name can still receive it. The text + delivered shall be the text the -001.4 claim returned, never a copy read before it. +- **AC-TASKS-SIGNAL-PAYLOAD-DELIVERY-001.6:** The system shall append the + completion handoff text LAST in the dispatched prompt: after the step entry + prompt's own composed content and after any queued hand-off message merged into + it. The text shall be introduced by the fixed heading line + `## Context from the previous workflow step`, alone on its line, with one blank + line before it and one after. The system shall not reorder, suppress, or + otherwise change how a queued hand-off message is merged, and shall not change + the prompt of an entry claiming no token. +- **AC-TASKS-SIGNAL-PAYLOAD-DELIVERY-001.6a:** Every decision a dispatch branch + makes about WHETHER to send the agent anything shall be evaluated on content + that excludes the completion handoff text, using the rule that branch already + applies today, so a completion handoff can never on its own cause a dispatch + that would not otherwise happen. That decision shall precede the claim; claiming + first and deciding afterwards violates this criterion even when the discarded + prompt would have sent nothing. +- **AC-TASKS-SIGNAL-PAYLOAD-DELIVERY-001.6b:** The system shall not apply + saved-prompt reference expansion to the completion handoff text, and shall apply + it to the entry prompt's own composed content exactly as today, so a completing + agent cannot pull unrelated saved-prompt content into the next agent's prompt. +- **AC-TASKS-SIGNAL-PAYLOAD-DELIVERY-001.6c:** When a branch decides to send the + agent something, the system shall claim the token per -001.4 and append the + handoff per -001.6. This includes a branch that finds its composed step prompt + empty and dispatches only a drained queued message: that dispatch is a step + entry and shall carry the handoff. When a branch sends the agent nothing at all, + the system shall claim nothing and shall leave the token in place for a later + entry into the step it names. Branches of one dispatch path may apply different + rules; each shall follow its own rather than a unified one. +- **AC-TASKS-SIGNAL-PAYLOAD-DELIVERY-001.7:** Every branch of every step-entry + dispatch path that sends the agent anything shall evaluate the handoff carry + token, so no branch can dispatch without the token having been considered, and + shall do so through one shared claim-and-place implementation rather than logic + duplicated per branch. Coverage is judged per branch, not per path: a path whose + ACP branch claims and whose passthrough branch does not is a violation. +- **AC-TASKS-SIGNAL-PAYLOAD-DELIVERY-001.8:** When one step entry composes more + than one prompt because a launch was replaced after a failure, the system shall + claim the token at most once per step entry — only a claim that returned text + counts as that one claim — and shall include that text in every prompt composed + from that claim onward, rather than re-claiming it per prompt. A prompt composed + before any claim returned text carries none and does not violate this criterion. +- **AC-TASKS-SIGNAL-PAYLOAD-DELIVERY-001.9:** After a step entry has claimed a + token, a later entry into the same step shall receive no handoff text. The + system shall not restore or re-record a claimed token, including when the entry + that claimed it subsequently fails to dispatch. +- **AC-TASKS-SIGNAL-PAYLOAD-DELIVERY-001.10:** When the next step's agent + profile differs from the completing step's, so the destination step runs on a + different session, the completion handoff shall still reach the prompt composed + for that session. +- **AC-TASKS-SIGNAL-PAYLOAD-DELIVERY-001.11:** When a consuming transition + commits but the destination step's entry is deferred until a queue promotion + admits the task, the handoff shall reach the prompt composed at that promotion. +- **AC-TASKS-SIGNAL-PAYLOAD-DELIVERY-001.12:** When a manual move takes a task + away from a step whose token was never claimed and later returns it to that + same step, the system shall deliver that token on the return and shall add no + time-based expiry to suppress it. Any consuming transition in between removes + or replaces the token per -001.2 and -001.3. +- **AC-TASKS-SIGNAL-PAYLOAD-DELIVERY-001.13:** The completion handoff and + blockers a transition carries shall be those of the first completion signal + accepted for that step. When a second `step_complete_kandev` call is rejected + as a duplicate, its handoff and blockers shall not be recorded, delivered, + merged, or allowed to overwrite the accepted signal's. + +### REQ-TASKS-SIGNAL-PAYLOAD-DELIVERY-002: A signal's blockers are retrievable after the transition + +#### Acceptance criteria + +- **AC-TASKS-SIGNAL-PAYLOAD-DELIVERY-002.1:** When a consuming transition writes + its transition audit record, the system shall include the consumed signal's + blockers under the key `signal_blockers` and its completion handoff under the + key `signal_handoff`, alongside the `signal_source` and `signal_summary` it + already writes. +- **AC-TASKS-SIGNAL-PAYLOAD-DELIVERY-002.2:** The system shall omit an empty or + whitespace-only blockers value, and an empty or whitespace-only completion + handoff value, from the audit record rather than writing an empty entry. +- **AC-TASKS-SIGNAL-PAYLOAD-DELIVERY-002.3:** The system shall capture the + blockers and completion handoff into the audit record before the pending signal + bag is cleared and before the carry token is recorded, so no ordering can lose + them. Where a queued worker writes the row asynchronously, capture at enqueue + satisfies this: the row may land later but shall carry the values the consuming + transition read. +- **AC-TASKS-SIGNAL-PAYLOAD-DELIVERY-002.4:** The system shall expose these + values through the existing session step-history read path, adding no endpoint + and changing its response shape only by the added metadata keys. +- **AC-TASKS-SIGNAL-PAYLOAD-DELIVERY-002.5:** The system shall record blockers + and completion handoff only for a transition that consumed a signal; one that + consumed none shall continue to write no signal metadata. +- **AC-TASKS-SIGNAL-PAYLOAD-DELIVERY-002.6:** The system shall store these + values in the existing audit record metadata, adding no table and no column. +- **AC-TASKS-SIGNAL-PAYLOAD-DELIVERY-002.7:** An audit record written before + this capability shall remain readable and shall not be rewritten or migrated. + A consumer shall treat `signal_blockers` and `signal_handoff` as + absent-by-default. +- **AC-TASKS-SIGNAL-PAYLOAD-DELIVERY-002.8:** The values recorded shall be those + of the first signal accepted for the step, per -001.13. A duplicate signal + shall neither append a second audit record nor amend the existing one. + +### REQ-TASKS-SIGNAL-PAYLOAD-DELIVERY-003: Neither argument can grow without bound + +#### Acceptance criteria + +- **AC-TASKS-SIGNAL-PAYLOAD-DELIVERY-003.1:** The system shall bound the stored + completion handoff text and the stored blockers text to 8,192 bytes each, + measured as UTF-8 byte length and inclusive of any truncation marker appended, + and shall apply the bound where the completion signal is first recorded, so the + signal bag, the audit record, and the carry token hold the same bounded value. +- **AC-TASKS-SIGNAL-PAYLOAD-DELIVERY-003.2:** Bounding shall be measured and + applied AFTER the handler's existing leading/trailing whitespace trim, on the + trimmed value. When that trimmed value is at most 8,192 bytes the system shall + store it byte-for-byte and append no marker. At 8,193 bytes or more it shall + store a truncated value whose total length, marker included, is at most 8,192 + bytes. +- **AC-TASKS-SIGNAL-PAYLOAD-DELIVERY-003.3:** When the system truncates a value + it shall cut on a UTF-8 character boundary, never storing a partial character, + and shall append the fixed marker `[truncated: over 8192-byte limit]` so a + later reader cannot mistake a cut value for a complete one. The retained content + shall be the longest whole-character prefix leaving room for that marker. +- **AC-TASKS-SIGNAL-PAYLOAD-DELIVERY-003.4:** When the system bounds a value, it + shall still accept the completion signal and shall drive the step transition + exactly as it would for an unbounded value. An oversized completion handoff or + blockers value shall never strand a step. +- **AC-TASKS-SIGNAL-PAYLOAD-DELIVERY-003.5:** When the system truncates one or + more values on a call it accepts, that call's `step_complete_kandev` result + shall carry `truncated`, a JSON array of the lowercase argument names that were + truncated, and `truncation_limit_bytes`, a JSON number holding the ceiling. The + array shall list `"handoff"` before `"blockers"` when both were truncated, + contain exactly one entry when one was, and never repeat a name. When nothing + was truncated the system shall omit both fields, so a result omitting them means + every submitted value was stored whole. +- **AC-TASKS-SIGNAL-PAYLOAD-DELIVERY-003.5a:** When a call is rejected as a + duplicate for the step, its result shall keep its existing rejection shape and + report no truncation, none of that call's values having been stored. Bounding + shall never convert a rejected duplicate into an accepted signal. +- **AC-TASKS-SIGNAL-PAYLOAD-DELIVERY-003.6:** The ceiling shall be a fixed value + compiled into the backend, identical across deployments, and readable or + writable from no configuration, environment, or runtime feature toggle. +- **AC-TASKS-SIGNAL-PAYLOAD-DELIVERY-003.7:** The system shall bound each value + independently per signal; the ceiling shall not accumulate across signals, + steps, or a task's transition history. + +### REQ-TASKS-SIGNAL-PAYLOAD-DELIVERY-004: The tool describes what it actually does + +#### Acceptance criteria + +- **AC-TASKS-SIGNAL-PAYLOAD-DELIVERY-004.1:** The registered description of the + `handoff` argument shall state that it is delivered once to the + immediately-following step's agent and is not carried beyond that step. +- **AC-TASKS-SIGNAL-PAYLOAD-DELIVERY-004.2:** The registered description of the + `blockers` argument shall state that it is recorded on the step-transition + record and not delivered to the next step's agent, so it is not used to pass + context forward. +- **AC-TASKS-SIGNAL-PAYLOAD-DELIVERY-004.3:** The registered descriptions of + both arguments shall state the byte ceiling from + REQ-TASKS-SIGNAL-PAYLOAD-DELIVERY-003. +- **AC-TASKS-SIGNAL-PAYLOAD-DELIVERY-004.4:** The tool's top-level description + shall claim no forwarding behavior the delivered mechanism does not provide. +- **AC-TASKS-SIGNAL-PAYLOAD-DELIVERY-004.5:** The system shall keep both + arguments registered and optional, with their existing names and types. + +### REQ-TASKS-SIGNAL-PAYLOAD-DELIVERY-005: Delivery never costs a transition + +#### Acceptance criteria + +- **AC-TASKS-SIGNAL-PAYLOAD-DELIVERY-005.1:** When recording or removing a carry + token fails, the system shall log it and complete the transition unchanged, + without retrying, rolling back, or deferring it. +- **AC-TASKS-SIGNAL-PAYLOAD-DELIVERY-005.2:** When claiming a carry token fails, + the system shall compose the step entry prompt exactly as today, with no + handoff text, and shall not fail the step entry. A failed claim removed and + returned nothing, so it shall not count as the step entry's one claim under + -001.8: a replacement launch in the same step entry, and any later entry into + the same step, shall attempt the claim again. The system shall not retry within + one composed prompt. +- **AC-TASKS-SIGNAL-PAYLOAD-DELIVERY-005.3:** When the configured repository + provides no atomic task-metadata write or claim operation, the system shall + behave as today: no token recorded, none claimed, no handoff text, and no error + surfaced to the transition or the step entry. +- **AC-TASKS-SIGNAL-PAYLOAD-DELIVERY-005.4:** When two consuming transitions for + the same task resolve concurrently, the last token write shall win — the + single-row overwrite's own commit order decides which is last, and no version or + sequence column is added — and neither outcome shall deliver a handoff to a step + the winning token does not name, because -001.4 compares the destination step + inside the same atomic operation that removes it. +- **AC-TASKS-SIGNAL-PAYLOAD-DELIVERY-005.5:** When a duplicate delivery re-runs + a consuming transition that already recorded its token, re-recording the same + handoff and destination step shall be indistinguishable from recording them + once in what is DELIVERED: at most one entry into that step receives that + handoff. The stamp is minted fresh per write, so the stored tokens differ at + that field; that is expected, and the stamp shall never be made stable or + content-derived to satisfy this criterion. +- **AC-TASKS-SIGNAL-PAYLOAD-DELIVERY-005.6:** A task with no handoff carry token + shall compose step entry prompts byte-identically to today. + +## Out of scope + +- **Attention routing for blockers.** Making them retrievable is this capability. + Surfacing them on a board, in chat, or in a notification is excluded: no + endpoint, no event, no frontend change, no copy, and therefore no localization. +- **Rendering or collapsing the handoff block in chat.** It is agent-facing + English composed into the prompt, not localized, the same class as the + workflow-instructions heading. No frontend affordance. +- **Changing the queued hand-off message.** Its provenance, merge position, and + requeue-on-failure behavior are untouched. AC-001.6 states only where the + completion handoff sits. +- **Unifying the actionability rules.** Dispatch branches apply different rules + today; the design records which. AC-001.6a defers to a branch's own rule rather + than reconciling them. +- **Ordering of the audit read path.** `ListHistoryBySession` orders by + `created_at` with no tiebreak column, and this capability changes neither; two + rows sharing a `created_at` stay in the order the driver returns them. +- **Putting handoff or blockers on the bus-event wire.** ADR 0015 kept both off + the `workflow.step_completion_signaled` payload. Delivery happens at transition + time from the persisted bag, not through the event. +- **Multi-hop retention.** Nothing accumulates handoffs across steps. Multi-hop + receipts remain the task plan's job; its three tools are unchanged. +- **Restructuring the completion payload into typed evidence fields.** The three + arguments keep their names, types, and optionality; a structured evidence bundle + is a separate item. +- **The manual completion fallback button.** Its source value is covered by every + rule above, but the button remains unimplemented and out of scope here, per + `REQ-TASKS-WORKFLOW-EXPLICIT-COMPLETION-SIGNAL-001`. +- **Amending ADR 0015.** Updating its text is a documentation change, not a + contract change owned here. diff --git a/docs/specs/tasks/system-design/workflow-completion-signal-payload-delivery.md b/docs/specs/tasks/system-design/workflow-completion-signal-payload-delivery.md new file mode 100644 index 0000000000..cf4870ca56 --- /dev/null +++ b/docs/specs/tasks/system-design/workflow-completion-signal-payload-delivery.md @@ -0,0 +1,566 @@ +--- +status: draft +system: tasks +requirements: + - REQ-TASKS-SIGNAL-PAYLOAD-DELIVERY-001 + - REQ-TASKS-SIGNAL-PAYLOAD-DELIVERY-002 + - REQ-TASKS-SIGNAL-PAYLOAD-DELIVERY-003 + - REQ-TASKS-SIGNAL-PAYLOAD-DELIVERY-004 + - REQ-TASKS-SIGNAL-PAYLOAD-DELIVERY-005 +created: 2026-09-05 +owners: + - kandev +--- + +# Workflow completion-signal payload delivery System Design + +## Purpose and boundaries + +The paired requirement is the contract. This document records the measured +current-tree shapes those criteria were written against, the mechanism chosen for +each, and the prior art followed rather than re-derived. Where the two disagree, +the requirement wins and this document is wrong. + +Line numbers are omitted: they drifted between sessions of this card. Every element +below is named by symbol, so a builder greps for it. + +## Provenance + +**Why this exists.** ADR 0015 records the mechanism accurately at its line 42 +("`handoff` and `blockers` are persisted in the bag only, not on the wire") but +justifies it at line 114 on the opposite outcome ("the summary is cheap, the +next-step agent benefits from a handoff blurb"). The mechanism never delivered +the rationale. This capability closes that gap; it does not reverse the ADR. +Amending the ADR's text is a documentation change, out of scope for the contract. + +**Measured cost of the defect.** Both shipped boards tell every agent to fill +`handoff` on every step while also declaring the task plan IS the handoff, a +workaround that exists because the argument does not work. One card made 26 step +transitions on 2026-09-03/04; every handoff it wrote was discarded. + +**Prior-art leg receipts.** The wiki leg RAN and returned nothing useful: the +configured Obsidian vault and QMD collection were unreachable in this +environment (all three transports unavailable — the wiki CLI not installed, +the query tool not on `PATH`, and the vault path denied by local filesystem +permissions). The vendor leg DID NOT RUN: `saas-kb` / `search_fsm_docs` are not +registered in this session, so `ai_sdlc` was not queried. Neither informed the +requirement. + +## Measured input + +Re-sampled against the working tree on 2026-09-05, and re-verified during spec +review. Every claim here was read from the code, not inferred. + +### The lifecycle today + +1. `step_complete_kandev` is registered in `internal/mcp/server`'s + `registerStepCompleteTool`, with `summary` required and `handoff` and + `blockers` optional. +2. `internal/mcp/handlers`'s `handleStepComplete` trims all three and builds a + `models.PendingStepCompletionSignal`, then calls `claimStepCompletionSignal`. +3. That claim is `SetSessionMetadataKeyIfAbsentOrDifferentStep[IfTaskAtStep]`, + so a second call at the same step returns `stored=false` and the first signal + stands. This is the mechanism behind AC-001.13 and AC-003.5a: the duplicate + path runs `handleDuplicateStepComplete`, which re-publishes the event and + returns `{accepted:false, reason:"already_signaled"}`. The second call's + `handoff` and `blockers` are already discarded today, and stay discarded. +4. Two consuming-transition sites exist in `internal/orchestrator`, both in + `event_handlers_workflow.go`: `executeStepTransition` (legacy + on_turn_complete) and **`applyEngineTransitionWithCommitMode`** (engine path). + Grep for that full name: `applyEngineTransition`, + `applyEngineTransitionWithCommit` and `applyEngineTransitionWithMode` are thin + wrappers that contain none of the consuming logic. Each site builds + `consumedSignal` by `models.LoadPendingStepSignal`, calls + `recordAutoStepTransition`, then clears the bag. Both must be changed, or the + two funnels drift. +5. `recordAutoStepTransition` in `event_handlers_step_completion.go` builds + `map[string]interface{}{"signal_source", "signal_summary"}`. This is the + single place the payload is narrowed, and the single place REQ-002 widens. It + leaves `metadata` nil when the signal is nil, which is what makes AC-002.5 + hold with no added branch. +6. `clearPendingStepSignal` / `clearPendingStepSignalByID` delete the bag entry. + This is where `handoff` and `blockers` die today. + +### Trigger gating: the asymmetry AC-001.2a exists for + +`recordAutoStepTransition` is called **unconditionally on every trigger** at both +sites, with `consumedSignal` nil for anything that is not turn completion. +The bag clear, by contrast, **is** trigger-gated: `if triggerOnEnter` in +`executeStepTransition`, and `if sessionLifecycle && trigger == +engine.TriggerOnTurnComplete` in `applyEngineTransitionWithCommitMode`. + +Placing the carry-token write beside `recordAutoStepTransition` without adopting +that gate would let a turn-start or children-completed transition satisfy +AC-001.2's "found no signal" clause and erase a token written moments earlier by +the consuming transition that delivered the task into the step. The token write +and removal therefore take the **bag clear's gate**, not the audit row's. + +**The trigger value alone is not the gate, and this is the trap.** +`applyFirstSatisfiedGuardedTransition` in `internal/workflow/engine/quorum.go` +drives a guarded quorum/approval decision through +`ApplyTransitionIfAtStep(..., TriggerOnTurnComplete)` — the SAME trigger constant a +real turn completion uses. (`TriggerOnApprovalResolved` exists in `engine/types.go` +but is not what this path passes.) So a reviewer clicking approve arrives carrying +`TriggerOnTurnComplete` with no turn having ended, on the DECIDER's session rather +than the assignee's. What excludes it is the other half of the condition: +`sessionLifecycle := mode != transitionLifecycleGuardedDecision` in +`applyEngineTransitionWithCommitMode`, which is why the gate is the compound +`sessionLifecycle && trigger == engine.TriggerOnTurnComplete` and not the trigger +test alone. A builder implementing AC-001.2 from a trigger check alone fires the +token write/remove on every quorum-gated approval, and AC-001.2's "found no +signal, so remove" branch then wipes a pending, unclaimed token the instant a +reviewer approves. Copy the compound condition; do not paraphrase it. + +### The step-entry surface + +- **`buildWorkflowEntryPrompt`** (`internal/orchestrator/task_operations.go`) is + the single prompt-**composition** seam, at five call sites: four in + `event_handlers_workflow.go` (the `launchAfterOnEnterDispatch` branches, + including three replacement launches after a failed or terminalized launch) and + one in `task_operations.go` inside `StartSessionForWorkflowStep` (queue + promotion and manual auto-start). +- **Composition is not dispatch.** There are **two step-entry dispatch paths**: + `launchAfterOnEnterDispatch` and `StartSessionForWorkflowStep`. The five seam + call sites sit inside those two. But the path is NOT the unit of coverage: + `launchAfterOnEnterDispatch` forks into an ACP branch (`autoStartStepPrompt`) and + a passthrough branch, and those two decide differently on identical input. AC-001.7 + therefore judges coverage per branch, which is why "I changed both paths" is not + evidence that every dispatch was covered. +- **Actionability is decided after the seam returns, by three different rules.** + `promptForEmptinessCheck` covers one call site, not all three. + - `StartSessionForWorkflowStep`: `promptForEmptinessCheck := + s.effectivePromptForSession(...)`, then `strings.TrimSpace(...) == ""` returns + without dispatching. + - `autoStartStepPrompt`: its own `effectiveAgentPrompt` check, which returns + early only when the prompt is blank **and** `len(attachments) == 0`, so an + attachment-only entry is actionable there and nowhere else. + - the passthrough branch of `launchAfterOnEnterDispatch`: a bare + `strings.TrimSpace(effectivePrompt) == ""`, which then calls + `drainQueuedMessageForPromptableSession` and returns. **That branch still + DISPATCHES** — it sends the drained queued message to the agent. It is not a + "nothing happened" path, which is why AC-001.6c names it explicitly and treats + it as a step entry that carries the handoff. + Note these are rules of BRANCHES, not paths: `autoStartStepPrompt` and the + passthrough branch both sit inside `launchAfterOnEnterDispatch` and disagree on + the same input (empty composed prompt plus a non-empty queued message). AC-001.6a + defers to the branch's own rule; unification is a named exclusion. +- **A queued hand-off message already merges into this prompt.** + `autoStartStepPrompt` calls `takeAndMergeHandoffMessage`, which drains an + Auto-run-enabled queued message (typically a `move_task_kandev` hand-off + prompt) and merges it with documented ordering "auto-start content first, + hand-off after", forwarding attachments and restoring the message on terminal + failure via `requeueTaken`. This is a different concept from the completion + handoff, with different provenance and lifetime, and the requirement names both + so a builder cannot conflate them. **This is also why AC-001.6 places the + completion handoff LAST, after the queued hand-off.** + `takeAndMergeHandoffMessage` runs BEFORE `autoStartStepPrompt`'s actionability + test and concatenates in one shot (`basePrompt + "\n\n" + msg.Content`) with no + splice point. Placing the completion handoff between the composed content and the + queued hand-off would force the claim before the actionability decision, violating + AC-001.6a, or restructure how the queued hand-off merges, which AC-001.6 forbids. + Appending last satisfies both and is reachable on every branch: after the + actionability test, before dispatch. +- **Saved-prompt reference expansion runs over the joined composition.** + `buildWorkflowPromptWithTrustedContext` ends in + `expandPromptReferencesWithContext(ctx, joined, isPassthrough)`. Appending the + completion handoff before that call would expand `@name` references inside + agent-authored text; AC-001.6b forbids it for that reason. + +### Shapes the mechanism relies on + +- **`session_step_history.metadata`** is a nullable `TEXT` column + (`internal/workflow/repository/sqlite.go`) holding free-form JSON. Adding keys + needs no migration, satisfying AC-002.6. +- **The read path already ships.** `GET /sessions/:id/workflow/history` + (`internal/workflow/handlers`) plus a WS action reach + `Controller.ListHistoryBySession`, whose `models.SessionStepHistory` carries + `Metadata map[string]interface{}` with `json:"metadata,omitempty"`. Added map + keys appear automatically, satisfying AC-002.4 with no endpoint and no shape + change, and `omitempty` gives AC-002.7's absent-by-default for free. + `ListHistoryBySession` is `ORDER BY created_at` with no tiebreak column; the + requirement names that as an exclusion rather than changing it. +- **Recording is asynchronous in production.** `recordAutoStepTransition` prefers + `asyncStepHistoryRecorder.EnqueueStepTransition`; when the bounded worker is + full or closed, it falls back to a bounded synchronous `CreateStepTransition` + write. The metadata map is built from the signal's fields before enqueue, so + values are captured at enqueue time even though the normal row lands later. + Database failure or a shutdown deadline can still drop telemetry; neither + rolls back an already-committed task mutation. Hence AC-002.3 says *capture* + before the clear, not *write* before it. +- **`tasks.metadata`** is an existing JSON bag with concurrent-key-safe patch + helpers on the SQLite repository: `SetTaskMetadataKey` (a plain overwrite, no + CAS, which is what makes AC-005.4's last-write-wins the primitive's actual + semantics) and `RemoveTaskMetadataKey`. +- **`RemoveTaskMetadataKey` cannot serve as the claim on its own.** Its signature + is `(ctx, taskID, key string) (bool, error)`: the boolean reports *presence*, + and the removed **value is not returned**. AC-001.4 requires one atomic + operation that both returns the content and removes it, so this capability adds + one. See "The claim primitive" below. +- **`internal/common/truncate`** already exposes `UTF8(s string, maxBytes int)`, + which cuts on a rune boundary. It appends no marker, so REQ-003's marker + handling wraps it rather than replacing it. + +## Mechanism + +### The claim primitive (new) + +A new repository method beside `RemoveTaskMetadataKey` in +`internal/task/repository/sqlite/task.go`, returning the removed value as well as +whether it was present, so read-and-remove is one claim: + + TakeTaskMetadataKeyIfDestinationStep( + ctx, taskID, key, expectedStepID, expectedStamp string, + ) (json.RawMessage, bool, error) + +**Why a plain take plus a pre-check is not equivalent.** `SetTaskMetadataKey` is an +unconditional overwrite, so a concurrent consuming transition can replace the token +between a check and an unconditional take, after which the take returns a token +addressed to a different step. Delivering that breaks AC-001.5; discarding it destroys +a token AC-001.5 requires be left in place, and AC-001.9 forbids putting it back. + +**`RemoveTaskMetadataKeyIfStamp` supplies the conditional-compare half only, NOT the +return value.** It reports presence through `RowsAffected` and does not return what it +removed, and no single statement can: neither SQLite's nor this repository's Postgres +`RETURNING` can read a pre-`UPDATE` value. Every `UPDATE ... RETURNING` over a JSON +`metadata` column in this tree — for example the compaction-count increment in +`internal/task/repository/sqlite/session.go` — returns the POST-update value, which +after a removal is null. "Return the removed value" is therefore NOT a one-line +extension of that precedent, and a builder must not plan for it as one. + +**The mechanism: compare-and-swap on the token's stamp.** The write side mints a fresh +`stamp` into every token (see "Handoff carriage"). The claim is an advisory read +followed by ONE conditional `UPDATE` whose `WHERE` compares BOTH nested fields +(paths built from `key`, as the precedent builds its own; shown here concrete): + + UPDATE tasks SET metadata = json_remove(metadata, '$.step_handoff_carry') + WHERE id = ? + AND json_extract(metadata, '$.step_handoff_carry.step_id') = ? + AND json_extract(metadata, '$.step_handoff_carry.stamp') = ? + +`RowsAffected == 1` means the row removed WAS the row read, because the stamp it is +keyed on is unique per token write. The method returns the handoff text from the +advisory read, and that text is provably the removed one — which is exactly what +AC-001.5's "never a copy read before it" protects against, and what AC-001.4 means by +an earlier read being advisory only. `RowsAffected == 0` means the token was replaced +or names another step: remove nothing, return nothing, compose with no handoff text, +and leave whatever is there for a later entry into the step it names. + +The destination-step comparison sits in the `WHERE` clause rather than in Go, so +AC-001.4's "evaluated inside that one operation" holds literally. The stamp is what +makes the claim safe with NO isolation-level or transaction assumption: no `BeginTxx`, +no `SELECT ... FOR UPDATE`, no `BEGIN IMMEDIATE`, and no dependence on SQLite's +deferred-transaction upgrade behavior. Mirror `RemoveTaskMetadataKeyIfStamp`'s +dual-dialect body — it already carries the Postgres `jsonb_extract_path_text` / `#-` +form beside the SQLite `json_extract` / `json_remove` form — rather than adding a +SQLite-only method to a file whose every neighbour handles both. + +The new method ships behind a narrow optional interface in +`internal/orchestrator/event_handlers_workflow.go`; it is deliberately not part +of the broad `sessionExecutorStore` contract in `internal/orchestrator/service.go`. +AC-005.3's degrade-to-today branch mirrors the existing +`asyncStepHistoryRecorder` and `stepCompletionSignalClaimer` optional-interface +assertions: a repository that lacks the method takes today's behavior rather than +erroring. + +### Handoff carriage (REQ-001) + +A **handoff carry token** on `tasks.metadata` under the key `step_handoff_carry`, +declared as a `MetaKey...` constant beside `MetaKeyQueuePromotionPending` and its ~25 +neighbours in `internal/task/models/models.go`. Naming it there is not cosmetic: +`Task.Metadata` is `map[string]interface{}` with `json:"metadata,omitempty"`, so the +key ships to the frontend in every task payload, and an unregistered name can silently +collide with another feature's one-shot token. Its value is a JSON object with exactly +three fields: + +- `handoff` — the bounded completion handoff text (REQ-003 bounds it, so a token + holds at most 8,192 bytes and the task payload grows by that much until claimed); +- `step_id` — the next step's identifier, which the claim compares; +- `stamp` — a fresh unique value minted on EVERY token write (`uuid.NewString()`; + `workflow_profile_session_lifecycle.go` already sets a `Stamp` that way). It must NOT + be content-derived: `models.StableLaunchErrorStamp` is a SHA-256 of its inputs, so two + successive tokens carrying the same handoff would share a stamp and the claim's + compare-and-swap would stop telling them apart. See "The claim primitive". + +Single-slot by construction, since `SetTaskMetadataKey` overwrites, which is how +AC-001.3 forbids accumulation without a length check. + +**Written** at both consuming-transition sites, under the same trigger gate the +bag clear uses (see "Trigger gating" above), next to `recordAutoStepTransition` +and before the bag clear, so AC-002.3's ordering falls out of placement rather +than a lock. A consumed signal with a blank handoff, or a consuming transition +that found no signal, removes the key instead of writing it (AC-001.2). A +non-consuming transition touches neither (AC-001.2a). + +**Claimed** once per step entry, through one shared helper rather than logic +duplicated per branch (AC-001.7). The order is fixed by AC-001.6a, AC-001.6c and +AC-001.4: + +1. compose the step entry prompt through `buildWorkflowEntryPrompt`, with no + handoff text, and let the branch merge any queued hand-off message exactly as + it does today; +2. apply that branch's existing rule for whether it will send the agent anything, + over content that excludes the handoff text (AC-001.6a); +3. if it will send nothing at all, stop: claim nothing, leave the token in place + (AC-001.6c). If it will send something — INCLUDING the passthrough branch that + found its composed prompt empty and is dispatching only a drained queued + message — continue; +4. read the token (advisory); if one is there, call + `TakeTaskMetadataKeyIfDestinationStep` with the step being entered AND the stamp + just read. If the read finds nothing, claim nothing. A token naming another step + is left untouched: AC-001.12 requires it still be deliverable when a manual move + later returns the task to that step. See "The claim primitive" for why this + settles both races (AC-001.4, AC-001.5, AC-005.4); +5. append the returned text LAST in the prompt, under the fixed heading + `## Context from the previous workflow step` (AC-001.6), without running + reference expansion over it (AC-001.6b). Appending after the composition seam + is what gives AC-001.6b for free: `expandPromptReferencesWithContext` runs + inside `buildWorkflowPromptWithTrustedContext`, which is upstream of here; +6. dispatch. + +Steps 2 and 3 are per BRANCH, not per path: `launchAfterOnEnterDispatch` contains +two branches whose rules disagree (see "Actionability"). The shared helper takes the +branch's own send-or-not answer as an argument rather than re-deriving it. + +A token addressed to a step that is never re-entered is not leaked: it is +single-slot, and the next consuming transition replaces it (AC-001.3) or removes +it (AC-001.2). + +Composing first and claiming second is what makes AC-001.6a satisfiable: the +send-or-not rules live downstream of the composition seam, so a claim inside the +seam would necessarily precede the decision. Hence AC-001.7 is a coverage guarantee +over branches plus one shared implementation, not "claim inside +`buildWorkflowEntryPrompt`". + +The claimed text is held by the dispatch path for the remainder of that step entry, +which lets a replacement launch reuse it (AC-001.8) even though the replacement +re-enters the composition seam with a fresh session. The seam's own +`ClaimInitialPromptFallback` treats a replacement as a fresh prompt boundary; the +carry token deliberately does not, so that precedent is noted to stop a builder +copying it. + +Task-keyed, not session-keyed, because a transition may switch the task onto a +different session for the destination step's profile; a session-keyed token would +be written on the source session and read by nobody. That is what makes AC-001.10 +and AC-001.11 hold rather than being separate code paths. + +### Blockers retrievability (REQ-002) + +Two more keys on the map `recordAutoStepTransition` already builds, named +`signal_blockers` and `signal_handoff` to match the `signal_source` / +`signal_summary` literals there, omitted when blank (AC-002.2). No table, no +column, no endpoint. The handoff is recorded here too, so the audit row states what +was carried as well as what was blocked. + +These two names are a wire contract, not an internal detail: they surface +verbatim in the `metadata` map of `GET /sessions/:id/workflow/history`. Update the +doc comment on `CreateStepTransition` in `internal/workflow/service/service.go`, +which currently documents the shape as `{"signal_source", "signal_summary"}`, so +the documented shape and the written shape stay in step. + +### Bounding (REQ-003) + +Applied in `handleStepComplete`, where the signal is first constructed and +already `strings.TrimSpace`-normalised, upstream of the bag, the audit row and +the carry token, so all three hold the same bounded value from one enforcement +point. A fixed compiled-in constant, following +`REQ-TASKS-PLAN-CONTENT-SIZE-LIMIT-001`'s pattern. + +Order matters and AC-003.2 pins it: TRIM FIRST, then measure. So "stored +byte-for-byte" in AC-003.2 means byte-for-byte against the TRIMMED value, not the +raw argument. + +The ceiling is inclusive of the marker (AC-003.1), so the algorithm is: if the +trimmed value is at most 8,192 bytes, store it as-is; otherwise `truncate.UTF8` the +content to `8192 - len(marker)` bytes, which already cuts on a rune boundary, then +append the marker, giving a stored value of at most 8,192 bytes. The marker +`[truncated: over 8192-byte limit]` is 33 bytes, so the retained prefix is at most +8,159 bytes. + +Bounding never rejects (AC-003.4): unlike the plan-size limit, refusing here +would strand a task on a step whose work is finished. The truncation report rides +the accepted result only: `truncated` is a JSON array of lowercase argument names +in the fixed order `["handoff", "blockers"]`, never a bare string and never a map, +alongside `truncation_limit_bytes` as a JSON number (AC-003.5). Both are omitted +entirely when nothing was truncated, so their absence is the signal that every +value was stored whole. `handleStepComplete` already returns a +`map[string]interface{}` that the MCP layer's `stepCompleteHandler` marshals +straight through, so the two fields reach the agent with no extra plumbing. The +duplicate path's rejection shape is untouched (AC-003.5a) because none of that +call's values were stored — note that bounding happens at signal construction, +which is upstream of the duplicate check, so a rejected duplicate must report no +truncation even though it computed one. + +### Tool description (REQ-004) + +Text-only change at the registration site. Non-localized: the string is sent to +the model, the same class as `workflowInstructionsHeading`, which the codebase +already documents as deliberately not i18n'd. No locale catalogs are touched, so +the i18n gate does not apply. Same for the fixed handoff heading in the prompt. + +### Failure posture (REQ-005) + +Every added write is best-effort, matching the contract the audit row already +has: `recordAutoStepTransition` logs and swallows, and this capability's writes +sit beside it under the same rule. + +**A failed claim is not a spent claim, and that asymmetry with AC-005.1 is deliberate.** +AC-005.1 forbids retrying a failed token WRITE, because the transition it belongs to has +already committed and a retry would race the next one. The claim is the opposite case: a +claim that errors removed nothing and returned nothing, so the token is still there, +still addressed to this step, and a later attempt is free. AC-005.2 therefore does not +spend AC-001.8's one-claim-per-step-entry budget on a failure — a replacement launch in +the same step entry attempts the claim again, and so does a later entry into the same +step. What AC-005.2 does forbid is a retry loop INSIDE one composed prompt: one attempt +per composed prompt, and a failure composes with no handoff text. The claim's +compare-and-swap is what makes re-attempting safe rather than double-delivering. + +**AC-005.5's re-run is not a delivery hazard.** `reconcileStepCompletionSignalLocked` +returns early on `task.WorkflowStepID != stepID`, so a replayed signal cannot re-run a +transition that already committed: the task is at the destination step by then and the +replay names the source. A re-record therefore lands only before any entry into that +step could have claimed, so AC-005.5 needs no double-delivery guard. + +## Requirement framing +Each requirement's intent and user story, held here so the paired requirements +document stays inside its ceiling. These frame the contract; they are not +themselves acceptance criteria. + +### REQ-TASKS-SIGNAL-PAYLOAD-DELIVERY-001 + +*A completed step's completion handoff reaches the next step's agent exactly once* + +**Intent:** Deliver what `handoff` already promises, on every path a step entry can +take, and stop there. Per-step context that is never dropped becomes a document +every later step pays to read. + +**User story:** As an agent starting a workflow step, I want the previous step's +closing context in my first prompt, so I do not reconstruct it from a record that +grows on every hop. + +### REQ-TASKS-SIGNAL-PAYLOAD-DELIVERY-002 + +*A signal's blockers are retrievable after the transition* + +**Intent:** Stop destroying the field. Its cheapest durable home is the audit +record already carrying the signal's summary and source, on an endpoint that +already ships. + +**User story:** As someone reconstructing why a task moved, I want the blockers +the completing agent reported, so a stated unresolved issue survives the step +advancing. + +### REQ-TASKS-SIGNAL-PAYLOAD-DELIVERY-003 + +*Neither argument can grow without bound* + +**Intent:** One hop of context is the deliverable. An oversized signal must still +advance the step: refusing it would strand a task on a step whose work is done. + +**User story:** As an operator, I want a fixed ceiling on what one signal carries +forward, so delivering a handoff cannot reproduce the growth that made the running +record expensive to read. + +### REQ-TASKS-SIGNAL-PAYLOAD-DELIVERY-004 + +*The tool describes what it actually does* + +**Intent:** The description must state delivery's exact extent: an agent believing +`handoff` persists across steps will use it as a running record. + +**User story:** As an agent choosing what to put in each argument, I want the tool +to state where each lands and how long it lives, so I do not put multi-step +bookkeeping into a one-hop field. + +### REQ-TASKS-SIGNAL-PAYLOAD-DELIVERY-005 + +*Delivery never costs a transition* + +**Intent:** Every added write is best-effort work on an already-committed +transition, matching the audit row's contract. A failed carry is a lost blurb; one +that rolls back or blocks a transition is a stuck card. + +**User story:** As a user whose card is mid-transition, I want a carriage failure +to cost me the handoff and nothing else, so a step never stops advancing because a +context blurb could not be stored. + +## Prior art followed + +- **ADR 0015** widened `session_step_history.metadata` rather than adding a + table, explicitly rejecting a dedicated signal table as overkill. REQ-002 adds + keys to that same map for the same data, applying the decision rather than + reopening it. +- **`MetaKeyQueuePromotionPending` / `MetaKeyAutoStartOnCreate`** establish the + one-shot task-metadata token claimed by whichever delivery wins the atomic + remove. The carry token is that shape plus the step and stamp fields. + **Copy the claim, NOT the restore.** `restoreTaskLifecycleToken` puts a + queue-promotion token BACK at six failure/recovery sites and is generic over + `key`, so aiming it at `step_handoff_carry` is a one-line change made by + symmetry. AC-001.9 forbids it: a claimed token is never restored, even when the + entry that claimed it then fails to dispatch. That handoff is lost; REQ-005 + accepts that. +- **`REQ-TASKS-PLAN-CONTENT-SIZE-LIMIT-001`** supplies the bounding pattern: one + fixed ceiling, compiled in, not configurable, enforced at a shared seam. + +**What differs.** Those precedents claim a value that already had a reader, and +their claim needs only "was it there". This capability adds the reader, which is the +whole defect, and needs the VALUE back — which is why it adds a new primitive rather +than reusing `RemoveTaskMetadataKey`, and why that primitive is a compare-and-swap +rather than the plain conditional remove `RemoveTaskMetadataKeyIfStamp` performs. + +## Testing notes + +The two consuming-transition sites are the drift risk: a change applied to only +one leaves the other silently discarding handoffs. Cover both +`executeStepTransition` and `applyEngineTransitionWithCommitMode`, and cover a +non-consuming trigger at each to prove AC-001.2a's gate. + +**Cover the guarded-decision carve-out explicitly.** A test that only varies the +trigger cannot catch F15's failure mode, because the guarded path carries +`TriggerOnTurnComplete` too. Drive a guarded quorum decision +(`transitionLifecycleGuardedDecision`) against a task holding an unclaimed carry +token and assert the token is STILL THERE afterwards. Without this test, an +implementation gated on the trigger alone passes every other test in this list. + +The dispatch BRANCHES are the second drift risk, and there are more of them than +there are paths. Cover `launchAfterOnEnterDispatch` twice — the ACP branch via +`autoStartStepPrompt` (including a replacement launch, for AC-001.8) and the +passthrough branch that dispatches only a drained queued message (AC-001.6c) — plus +`StartSessionForWorkflowStep` (for AC-001.11's queue promotion). Assert the handoff +lands LAST, after any queued hand-off content, on the branch where both are present. + +**The claim race needs a test that fails against a pre-check implementation.** +Between reading a token for step A and claiming it, overwrite the key with a token +for step B, then run the claim. Assert the entry into A receives no handoff AND the +step-B token is still present. An unconditional take plus a pre-check passes a naive +single-threaded test and fails this one, which is the whole point. + +Add the same-step variant, which the step comparison alone cannot catch: replace the +token with a DIFFERENT token also naming step A, then claim. Assert the entry receives +nothing and the replacement is still present. An implementation that compares only +`step_id` removes the replacement and delivers the stale text, passing the step-B test +above; only the stamp compare-and-swap fails it. + +Cover a failed claim followed by a replacement launch in the same step entry: assert the +second attempt runs and delivers, per the failure-posture rule that a failed claim does +not spend the entry's one claim. + +Also assert an entry that sends the agent nothing claims nothing (AC-001.6a), so a +handoff can never be consumed by a dispatch that did not happen. + +Assert a claimed token is NOT restored when the claiming entry then fails to dispatch +(AC-001.9): claim, fail the launch terminally, then assert `tasks.metadata` has no +`step_handoff_carry` and a later entry into that step gets no handoff. Without it the +`restoreTaskLifecycleToken` symmetry ships silently. + +The async recorder means an assertion on a durable row can race. Assert on the +metadata map handed to the recorder (the test double takes the synchronous +branch), which is also the value AC-002.3 pins, and assert the exact key names +`signal_blockers` / `signal_handoff` rather than just presence. + +AC-003.2's boundary pair (8,192 stored whole, 8,193 truncated) is measured AFTER +the trim, so include a case padded with whitespace that is oversized before +trimming and in-bounds after: it must store whole and report no truncation. +AC-003.3's marker-inside-the-ceiling rule needs a multi-byte-character case so a +cut landing mid-rune is caught. Assert `truncated` is an array in the order +`["handoff", "blockers"]` when both truncate, and that both fields are absent when +neither does.