Files

Lukas May 2877484012 Add userDismissedAt field to agents schema

2026-02-07 00:33:12 +01:00

9.1 KiB

Raw Blame History

Session State

Session state tracks position, decisions, and blockers across agent restarts. Unlike the Domain Layer (which tracks codebase state), session state tracks execution state.

STATE.md

Every active initiative maintains a STATE.md file tracking execution progress:

# STATE.md
initiative: init-abc123
title: User Authentication

# Current Position
position:
  phase: 2
  phase_name: "JWT Implementation"
  plan: 3
  plan_name: "Refresh Token Rotation"
  task: "Implement token rotation endpoint"
  wave: 1
  status: in_progress

# Progress Tracking
progress:
  phases_total: 4
  phases_completed: 1
  current_phase_tasks: 8
  current_phase_completed: 5
  bar: "████████░░░░░░░░ 50%"

# Decisions Made
decisions:
  - date: 2024-01-14
    context: "Token storage strategy"
    decision: "httpOnly cookie, not localStorage"
    reason: "XSS protection, automatic inclusion in requests"

  - date: 2024-01-14
    context: "JWT library"
    decision: "jose over jsonwebtoken"
    reason: "Better TypeScript support, Web Crypto API"

  - date: 2024-01-15
    context: "Refresh token lifetime"
    decision: "7 days"
    reason: "Balance between security and UX"

# Active Blockers
blockers:
  - id: block-001
    description: "Waiting for OAuth credentials from client"
    blocked_since: 2024-01-15
    affects: ["Phase 3: OAuth Integration"]
    workaround: "Proceeding with email/password auth first"

# Session History
sessions:
  - id: session-001
    started: 2024-01-14T09:00:00Z
    ended: 2024-01-14T17:00:00Z
    completed: ["Phase 1: Database Schema", "Phase 2 Tasks 1-3"]

  - id: session-002
    started: 2024-01-15T09:00:00Z
    status: active
    working_on: "Phase 2, Task 4: Refresh token rotation"

# Next Action
next_action: |
  Continue implementing refresh token rotation endpoint.
  After completion, run verification for Phase 2.
  If Phase 2 passes, move to Phase 3 (blocked pending OAuth creds).

# Context for Resume
resume_context:
  files_modified_this_session:
    - src/api/auth/refresh.ts
    - src/middleware/auth.ts
    - db/migrations/002_refresh_tokens.sql

  key_implementations:
    - "Refresh tokens stored in SQLite with expiry"
    - "Rotation creates new token, invalidates old"
    - "Token family tracking for reuse detection"

  open_questions: []

State Updates

When to Update STATE.md

Event	Update
Task started	`position.task`, `position.status`
Task completed	`progress.*`, `position` to next task
Decision made	Add to `decisions`
Blocker encountered	Add to `blockers`
Blocker resolved	Remove from `blockers`
Session start	Add to `sessions`
Session end	Update session `ended`, `completed`
Phase completed	`progress.phases_completed`, reset task counters

Atomic Updates

// Update position atomically
await updateState({
  position: {
    phase: 2,
    plan: 3,
    task: "Implement token rotation",
    wave: 1,
    status: "in_progress"
  }
});

// Add decision
await addDecision({
  context: "Token storage",
  decision: "httpOnly cookie",
  reason: "XSS protection"
});

// Record blocker
await addBlocker({
  description: "Waiting for OAuth creds",
  affects: ["Phase 3"]
});

Resume Protocol

When resuming work:

1. Load STATE.md

Read STATE.md for initiative
Extract: position, decisions, blockers, resume_context

2. Load Relevant Context

If position.plan exists:
  Load {phase}-{plan}-PLAN.md
  Load prior SUMMARY.md files for this phase

If position.task exists:
  Find task in current plan
  Resume from that task

3. Verify State

Check files_modified_this_session still exist
Check implementations match key_implementations
If mismatch: flag for review before proceeding

4. Continue Execution

Display: "Resuming from Phase {N}, Plan {M}, Task: {name}"
Display: decisions made (for context)
Display: active blockers (for awareness)
Continue with task execution

Decision Tracking

Decisions are first-class citizens, not comments.

What to Track

Type	Example	Why Track
Technology choice	"Using jose for JWT"	Prevents second-guessing
Architecture decision	"Separate auth service"	Documents reasoning
Trade-off resolution	"Speed over features"	Explains constraints
User preference	"Dark mode default"	Preserves intent
Constraint discovered	"API rate limited to 100/min"	Prevents repeated discovery

Decision Format

decisions:
  - date: 2024-01-15
    context: "Where the decision was needed"
    decision: "What was decided"
    reason: "Why this choice"
    alternatives_considered:
      - "Alternative A: rejected because..."
      - "Alternative B: rejected because..."
    reversible: true|false

Blocker Management

Blocker States

[new] ──identify──▶ [active] ──resolve──▶ [resolved]
                       │
                       │ workaround
                       ▼
                   [bypassed]

Blocker Format

blockers:
  - id: block-001
    status: active
    description: "Need production API keys"
    identified_at: 2024-01-15T10:00:00Z
    affects:
      - "Phase 4: Production deployment"
      - "Phase 5: Monitoring setup"
    blocked_tasks:
      - task-xyz: "Configure production environment"
    workaround: null
    resolution: null

  - id: block-002
    status: bypassed
    description: "Design mockups not ready"
    identified_at: 2024-01-14T09:00:00Z
    affects: ["UI implementation"]
    workaround: "Using placeholder styles, will refine later"
    workaround_tasks:
      - task-abc: "Apply final styles when mockups ready"

Blocker Impact on Execution

Task Blocking: Task marked blocked in tasks table
Phase Blocking: If all remaining tasks blocked, phase paused
Initiative Blocking: If all phases blocked, escalate to user

Session History

Track work sessions for debugging and handoffs:

sessions:
  - id: session-001
    agent: worker-abc
    started: 2024-01-14T09:00:00Z
    ended: 2024-01-14T12:30:00Z
    context_usage: "45%"
    completed:
      - "Phase 1, Plan 1: Database setup"
      - "Phase 1, Plan 2: User model"
    notes: "Clean execution, no issues"

  - id: session-002
    agent: worker-def
    started: 2024-01-14T13:00:00Z
    ended: 2024-01-14T17:00:00Z
    context_usage: "62%"
    completed:
      - "Phase 1, Plan 3: Auth endpoints"
    issues:
      - "Context exceeded 50%, quality may have degraded"
      - "Encountered blocker: missing env vars"
    handoff_reason: "Context limit reached"

Storage Options

SQLite (Recommended for Codewalk)

CREATE TABLE initiative_state (
  initiative_id TEXT PRIMARY KEY REFERENCES initiatives(id),
  current_phase INTEGER,
  current_plan INTEGER,
  current_task TEXT,
  current_wave INTEGER,
  status TEXT,
  progress_json TEXT,
  updated_at INTEGER
);

CREATE TABLE initiative_decisions (
  id TEXT PRIMARY KEY,
  initiative_id TEXT REFERENCES initiatives(id),
  date INTEGER,
  context TEXT,
  decision TEXT,
  reason TEXT,
  alternatives_json TEXT,
  reversible BOOLEAN
);

CREATE TABLE initiative_blockers (
  id TEXT PRIMARY KEY,
  initiative_id TEXT REFERENCES initiatives(id),
  status TEXT CHECK (status IN ('active', 'bypassed', 'resolved')),
  description TEXT,
  identified_at INTEGER,
  affects_json TEXT,
  workaround TEXT,
  resolution TEXT,
  resolved_at INTEGER
);

CREATE TABLE session_history (
  id TEXT PRIMARY KEY,
  initiative_id TEXT REFERENCES initiatives(id),
  agent_id TEXT,
  started_at INTEGER,
  ended_at INTEGER,
  context_usage REAL,
  completed_json TEXT,
  issues_json TEXT,
  handoff_reason TEXT
);

File-Based (Alternative)

.planning/
├── STATE.md                    # Current state
├── decisions/
│   └── 2024-01-15-jwt-library.md
├── blockers/
│   └── block-001-oauth-creds.md
└── sessions/
    ├── session-001.md
    └── session-002.md

Integration with Agents

Worker

Reads STATE.md at start
Updates position on task transitions
Adds deviations to session notes
Updates progress counters

Architect

Creates initial STATE.md when planning
Sets up phase/plan structure
Documents initial decisions

Orchestrator

Monitors blocker status
Triggers resume when blockers resolve
Coordinates session handoffs

Verifier

Reads decisions for verification context
Updates state with verification results
Flags issues for resolution

Example: Resume After Crash

1. Agent crashes mid-task

2. Supervisor detects stale assignment
   - Task assigned_at > 30min ago
   - No progress updates

3. Supervisor resets task
   - Status back to 'open'
   - Clear assigned_to

4. New agent picks up task
   - Reads STATE.md
   - Sees: "Last working on: Refresh token rotation"
   - Loads relevant PLAN.md
   - Resumes execution

5. STATE.md shows continuity
   sessions:
     - id: session-003
       status: crashed
       notes: "Agent unresponsive, task reset"
     - id: session-004
       status: active
       notes: "Resuming from session-003 crash"

9.1 KiB Raw Blame History