feat: Navigation-based workflow engine for deterministic traversal#35
Closed
feat: Navigation-based workflow engine for deterministic traversal#35
Conversation
Implement opaque state token encoding/decoding using gzip compression
and base64 encoding. The token format (v1.gzB64.{payload}) is designed
to be non-human-readable to prevent agents from interpreting state.
- Add encodeState/decodeState with gzip+base64
- Add validation helpers (isValidTokenFormat, getTokenVersion)
- Add compression ratio diagnostic
- Add StateCodecError for structured error handling
- Add navigation types for API responses
- Add comprehensive test coverage (20 tests)
Part of #34
Implement core affordance computation logic that determines available actions from workflow definition and current state. - computePosition: Get current position (activity, step, loop) - computeAvailableActions: Core affordance computation - getActiveCheckpoint: Detect blocking checkpoints - isCheckpointBlocking: Check if progress is blocked - isActivityComplete: Check if activity can transition - generateSituationMessage: Human-readable status Checkpoints block step completion until responded, ensuring agents cannot skip required user decisions. Part of #34
Implement pure functions that produce new state from workflow actions, following XState pattern of Machine.transition(state, event) → newState. - completeStep: Mark step complete, advance to next - respondToCheckpoint: Record checkpoint response - transitionToActivity: Move to new activity (validates completion) - advanceLoop: Start/advance/complete loop iterations - tryDefaultTransition: Convenience for default transitions All functions return TransitionResult with success/error, ensuring agents receive clear feedback on invalid actions. State immutability verified in tests. Part of #34
Implement the 4 core navigation tools that provide the "navigation landscape" for agents: - nav_start: Initialize workflow, return initial situation - nav_situation: Get current situation from state token - nav_action: Execute action (complete_step, respond_to_checkpoint, transition, advance_loop) with validation - nav_checkpoint: Get active checkpoint details Each response includes position, available actions, active checkpoint (if any), and opaque state token. Agents cannot interpret state, only pass it through, ensuring engine authority over transitions. History events added automatically for all state changes. Part of #34
Enable navigation tools in MCP server startup. Tools now available: - nav_start, nav_situation, nav_action, nav_checkpoint Part of #34
Comprehensive E2E tests covering: - Simple workflow completion without checkpoints - Checkpoint blocking until response - Full activity traversal with transition - State resumption from saved token - Multi-activity workflow traversal - Error handling for invalid inputs Tests validate the complete navigation flow from start through multiple activities, ensuring agents cannot skip checkpoints or complete steps out of order. Part of #34
Document the new navigation API including: - Tool descriptions and parameters - Response format with position, actions, checkpoint - State token opacity and purpose - Action types and required parameters - Checkpoint blocking behavior Part of #34
25 tasks
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Implements a navigation-based workflow engine that provides server-side authority over workflow state and transitions. This addresses the issue of AI agents bypassing workflow fidelity by making the engine the sole interpreter of state.
Key Changes
nav_start,nav_situation,nav_action,nav_checkpoint)Architecture
Key Design Principles
Test Plan
Closes #34