core/docs/archive/DESIGN-0.26.0.md

DESIGN — v0.26.0: Workflow Engine

Status: Shipped (v0.26.0–v0.26.5, 15 changesets) Branch: 0.26.0 Scope: Team-owned staged processes, AI intake, human assignment, visitor experience Depends on: Dynamic surfaces (v0.25.0), multi-participant channels (v0.23.x), anonymous identity (v0.24.3), permissions (v0.24.2)

---

Phasing

Six sub-releases. Each is shippable and testable independently. Deferred tech debt from v0.21–v0.25 absorbed into v0.26.0 (phase 0).

v0.26.0  Foundation: cleanup + context-aware tool system
           │
v0.26.1  Workflow definitions + versioning (schema + CRUD)
           │
v0.26.2  Workflow instances + stage transitions (runtime)
           │
v0.26.3  Visitor experience (surfaces + branded chat)
           │
v0.26.4  AI intake + assignment queue
           │
v0.26.5  Team collaboration + workflow builder UI

---

v0.26.0 — Foundation

Cleanup debt, then build the tool infrastructure that workflows need.

Deferred Cleanup (absorb from v0.21–v0.25)

Session cleanup job

• Background goroutine: delete session_participants older than N days with no associated messages
• Configurable via SESSION_EXPIRY_DAYS env var (default: 30)
• Runs on startup + every 6h
• Closes v0.24.3 deferred item

Stale code TODOs

• surfaces.go:108-109 — surface delete: clean up static assets + templates from SURFACE_ASSET_DIR/{id}/ and SURFACE_TEMPLATE_DIR/{id}/
• completion.go:164 — remove misleading TODO comment (pricing IS populated in recordUsage() at line ~1996)
• intrinsic.go:19 — remove stale "TODO: 0.9.2" comment (shipped in v0.22.0)

Roadmap housekeeping

• Mark shipped items in "Technical Debt + Deferred Items" section:
  • Rate limit tracking (v0.22.4)
  • Auto-disable policy (v0.22.4)
  • Tool health recording (v0.22.4)
  • PDF export via pandoc (v0.22.4)
  • Persona tool grant enforcement (v0.25.0)
• Clean up stale deferred-into version markers

Context-Aware Tool System

Absorbed from v0.25.0 roadmap. Prerequisite for workflow tool scoping.

ToolContext struct (tools/types.go)

• Fields: ChannelType, WorkspaceID, WorkflowID, TeamID, PersonaID, IsVisitor
• Populated from channel record in completion handler before tool execution

Require predicates

• Availability() Require method on Tool interface
• BaseTool embed: defaults to AlwaysAvailable (backward compat)
• Built-in predicates: RequireWorkspace, RequireWorkflow, RequireTeam, DenyVisitor, All()
• tools.AvailableFor(tctx, disabled) replaces AllDefinitionsFiltered()

Self-declaring tools

• Workspace tools: RequireWorkspace + DenyVisitor
• Git tools: RequireWorkspace + DenyVisitor
• workspace_create: available only when no workspace bound
• Memory/notes tools: DenyVisitor
• Eliminates WorkspaceToolNames() / GitToolNames() manual suppression

ExecutionContext extension

• Add WorkflowID, TeamID to existing ExecutionContext
• Populated from channel record in completion handler

Persona tool grant enforcement hardening

• v0.25.0 shipped the second-pass allowlist in completion.go:917
• For workflows: version snapshot must include persona tool grants at snapshot time (frozen for running instances)

Route Namespaces

Two distinct namespaces. No collision.

/s/:slug — Extension Surfaces (application extensions)

• Single-page, self-contained sub-applications
• Examples: custom dashboard, kanban board, form builder
• One template, one JS entry point, scoped CSS
• Registered via surface manifest (v0.25.0 surface_registry)

/w/:scope/:slug — Workflows (business logic automation)

• :scope is team-slug or global — workflows belong to a team or are org-wide. Prevents slug collisions across teams.
• Multi-page: landing, visitor chat, team review, admin tracking — different views depending on who is accessing (visitor vs. team member vs. admin)
• Involves customers and team members, possibly spanning multiple teams
• Purpose-built Go templates per view, not a single-page pattern

Both use Go template rendering. They share base.html but have independent template trees and JS entry points.

Migration

• 023_v0260_foundation.sql: session cleanup additions (if schema changes needed), no new tables in this phase

---

v0.26.1 — Workflow Definitions + Versioning

Schema and CRUD for defining workflows. No runtime yet.

Tables

workflows

• id, team_id (nullable — NULL = global), name, slug (unique within scope: UNIQUE(team_id, slug) with partial index for global), description
• branding (JSONB: accent color, logo URL, tagline)
• entry_mode (enum: public_link, team_only)
• is_active, version (auto-increment on edit)
• on_complete (JSONB, nullable — v0.27.0 chaining hook, NULL for now. Future schema: {"action": "start_workflow", "target_slug": "...", "data_map": {...}}. Column exists early so the table doesn't need migration when chaining lands.)
• retention (JSONB — {"mode": "archive"|"delete", "delete_after_days": N}. Default: {"mode": "archive"})
• created_by, created_at, updated_at

workflow_stages

• id, workflow_id, ordinal, name
• persona_id (FK — persona drives this stage)
• assignment_team_id (FK — which team handles human review)
• form_template (JSONB — fields the persona should collect)
• history_mode (enum: full, summary, fresh — default full)
• auto_transition (bool — advance automatically when form complete)
• transition_rules (JSONB — conditions, round-robin config)

workflow_versions

• id, workflow_id, version_number
• snapshot (JSONB — full serialized definition + stages + tool grants)
• created_at

API

• Team-admin CRUD: create/edit/delete workflows and stages
• Reorder stages (PATCH ordinal)
• workflow.create permission required
• Publish action: snapshot current definition → workflow_versions
• Slug validation: lowercase, alphanumeric + hyphens, unique within scope (same slug can exist under different teams). URL resolves as /w/team-slug/workflow-slug or /w/global/workflow-slug.

Design Decisions (to flesh out)

• Branding schema: minimal (accent + logo + tagline) or extensible JSONB?
• Stage persona: must be team-scoped persona? Or any accessible persona?

Migration

• 023_v0261_workflows.sql: workflows, workflow_stages, workflow_versions

---

v0.26.2 — Workflow Instances + Stage Transitions

Channels become workflow runtime containers.

Channel Extensions

• workflow_id, workflow_version columns on channels (populated on workflow channel creation)
• current_stage (ordinal), stage_data (JSONB)
• workflow_status enum: active, completed, stale, cancelled
• last_activity_at tracking

Entry Point

• Public link: /w/:scope/:slug → creates workflow channel, adds anonymous session participant (v0.24.3), binds stage 1 persona, auto-creates workspace. :scope is team slug or global.
• Team-only: same flow but requires authenticated user

Stage Transitions

• AI-triggered: workflow_advance tool (see v0.26.4)
• Human-triggered: button in channel header
• Rejection: return to previous stage with reason text
• On transition: swap active persona, notify assignment team, update channel metadata, create channel-scoped note with collected data

History mode (per-stage, configurable in workflow_stages):

• full — new persona sees complete conversation history with a system boundary message (same pattern as @mention context boundaries, v0.23.0). Simplest to implement, best for continuity-sensitive workflows.
• summary — utility-role summarization of prior stages injected as a system message. New persona starts with context but not raw history.
• fresh — new persona sees nothing from prior stages. Clean slate. Simplest for independent review stages.

Default: full. Stored as history_mode enum on workflow_stages.

Staleness Sweep

• Background goroutine (like health accumulator pattern)
• Marks idle instances as stale after configurable threshold
• Stale UX: visitor sees "Continue or Start Over" (start over = new instance on latest version)

Migration

• Adds columns to channels, or separate workflow_instances table (TBD — inline columns simpler, separate table cleaner)

---

v0.26.3 — Visitor Experience

Purpose-built surfaces for anonymous workflow participants.

Landing Page

• GET /w/:scope/:slug — branded page with persona avatar, description, "Start"
• Go template: workflow-landing.html
• Reads workflow.branding JSONB for accent color, logo, tagline
• System dark/light mode (no theme toggle — visitors don't have prefs)

Visitor Chat

• GET /w/:scope/:slug/c/:channelId — bubble chat (NOT full ChatPane)
• workflow-chat.js: lightweight WebSocket client
  • Message send/receive
  • Markdown rendering (marked.js + DOMPurify, already available)
  • Typing indicator
  • Stage transition animation (visual feedback on advance)
• Scoped: no sidebar, no settings, no navigation
• Session auth via AuthOrSession middleware (v0.24.3)

Tool Scoping

• DenyVisitor predicates prevent visitors from accessing workspace, git, memory, notes tools
• Persona tool grants further restrict per-stage

Design Decisions (to flesh out)

• Visitor can upload files? (attachments to workflow channel)
• Visitor can see previous stage history? (probably not — each stage is a clean persona conversation)
• Mobile-first layout for visitor surfaces

---

v0.26.4 — AI Intake + Assignment Queue

The AI does the data collection. Humans review and act.

workflow_advance Tool

• RequireWorkflow availability predicate
• Input: collected form data (JSONB matching form_template)
• Validates all required fields present
• Triggers stage transition (same path as human-triggered)
• Creates channel-scoped note with structured form response

Form Template → System Prompt

• Stage form_template JSONB injected into persona system prompt: "Collect the following information from the visitor: [field list]"
• Persona conducts conversational intake
• When all fields gathered → calls workflow_advance with data
• Rejection: persona sees rejection reason in conversation, re-collects

Assignment Queue

workflow_assignments table

• id, channel_id, stage (ordinal), team_id
• assigned_to (nullable user_id), status (unassigned/claimed/completed)
• created_at, claimed_at, completed_at

Claim model

• Unassigned workflow channels visible to all team members
• Optimistic lock: UPDATE ... WHERE status = 'unassigned'
• Round-robin auto-assignment (optional, per-stage transition_rules)

Notifications

• New workflow assignment → notification to team (existing infra)
• WebSocket push to online team members
• Claim confirmation notification to claimer

Migration

• workflow_assignments table

---

v0.26.5 — Team Collaboration + Workflow Builder UI

Frontend surfaces for building and managing workflows.

Team Member View

• Assigned member sees full history (AI intake + artifacts + notes)
• Persona remains active — assists both visitor and team member
• Member can: advance stage, reject (with reason), add notes, invoke tools, reassign, escalate

Workflow Builder

• Team admin panel section
• Stage list editor: add/remove/reorder stages
• Per-stage config: persona picker, assignment team, form template editor
• Branding editor: accent color, logo upload, tagline
• Publish button (creates version snapshot)
• Read-only tool grants display per stage persona

Channel Header (Workflow Mode)

• Workflow stage indicator (step N of M, stage name)
• Advance / Reject buttons (permission-gated)
• Assignment info (who claimed, when)
• History mode indicator (full/summary/fresh)

Queue UI

Prototype both approaches in v0.26.5, decide based on usage:

Option A: Sidebar section for team members — shows unassigned workflow channels for user's teams, count badge, click opens in main pane. Low friction, always visible.

Option B: Dedicated surface (/workflows or team-admin view) for tracking and management — full table with filters, assignment history, metrics. Better for high-volume operations.

Likely outcome: both. Sidebar for team members (day-to-day claims), dedicated surface for team admins (tracking, reporting, bulk ops).

---

Resolved Decisions

1. Workflow channel lifecycle. Configurable per-workflow retention policy. Default: archive (read-only, ai_mode='off', no new messages). Optional: auto-delete after N days. Stored as retention JSONB on workflows table.

2. Multi-stage persona conversations. Three modes, configurable per-stage via history_mode enum on workflow_stages:

   • full — complete history + boundary message (default, simplest)
   • summary — utility-role summarization injected as system message
   • fresh — clean slate, no prior context First and third are simplest to implement; ship those first, summary can land as a follow-up.

3. Visitor re-entry. Resume if session cookie matches and instance is active. Otherwise start new on latest version.

4. Workflow-to-workflow chaining. Deferred to v0.27.0 (tasks/agents). on_complete JSONB column on workflows table ships as nullable in v0.26.1 migration so the schema is pre-wired. v0.27.0 populates it and adds the trigger logic. No migration needed when chaining lands.

5. Route namespaces. /s/:slug for extension surfaces (single-page sub-apps). /w/:scope/:slug for workflows (multi-page, role-dependent views). No collision. See "Route Namespaces" in v0.26.0.

---

Cross-Cutting Concerns

Testing strategy: Integration tests per phase. v0.26.0 tool context tests. v0.26.1 workflow CRUD + versioning tests. v0.26.2 stage transition tests. v0.26.4 assignment claim concurrency test.

Migration numbering: Single migration per phase (023, 024, ...) or consolidated? Leaning toward: one per phase, squash at tag time if needed.

Backward compat: Non-workflow channels unaffected. ToolContext with BaseTool defaults means existing tools work without changes. Workflow columns on channels are nullable.