How the Status System Enables Workflow Customization in Craft Agents

The status system in Craft Agents treats each session as a work item that moves through configurable states, triggering automations and UI updates via the SessionStatus type and workspace-level statuses/config.json configuration.

The status system for workflow customization in Craft Agents (lukilabs/craft-agents-oss) provides a declarative mechanism for defining how conversations progress through business workflows. By mapping session states to automation triggers, developers can build complex approval processes, notification pipelines, and agent handoffs without modifying core application logic.

Core Concepts of the Status System

SessionStatus Type Definition

The foundation of the status system resides in packages/core/src/types/session.ts, which defines the SessionStatus enum and extends the Session interface with an optional status field. This type-safe definition ensures that all workspace states conform to a consistent schema across the application.

Workspace Configuration Storage

Status configurations are stored in the workspace file statuses/config.json. This file acts as the source of truth for which statuses are valid within a specific workspace, allowing different teams to define custom workflows such as "Backlog," "In Review," and "Deployed" without code changes.

Validation and Error Handling

The packages/shared/src/statuses/validation.ts module provides runtime validation against the workspace configuration. When a status change is requested, the system checks packages/shared/src/statuses/types.ts to verify that the target status exists in statuses/config.json, throwing a descriptive error if an undeclared status is used.

Programmatic Status Changes

The set_session_status Tool

Agents interact with the status system through the set_session_status tool defined in packages/session-tools-core/src/tool-defs.ts. This tool accepts a sessionId (optional, defaults to current session) and a status parameter, allowing agents to advance workflows based on conversation outcomes.

Handler Implementation

The tool handler in packages/session-tools-core/src/handlers/set-session-status.ts processes agent requests by invoking ctx.setSessionStatus. This abstraction layer ensures that agents cannot directly manipulate workspace files, maintaining security boundaries while enabling workflow automation.

Server-Side Persistence

The SessionManager class in packages/server-core/src/sessions/SessionManager.ts implements the actual status mutation. When setSessionStatus is called, the method persists the change to statuses/config.json and emits a SessionStatusChange event through the automation system, triggering any configured downstream actions.

Workflow Automation Integration

Event Emission and Listening

The packages/shared/src/automations/event-bus.ts module defines the SessionStatusChangePayload interface, which carries the sessionId, newState, and optional metadata such as previous state and timestamp. This event bus decouples status changes from automation execution, enabling asynchronous workflow processing.

Automation Configuration Examples

Automations are configured in workspace files (typically under .craft/automations) and listen for SessionStatusChange events. For example, when a session transitions to done, an automation might invoke the close_session tool and send an email notification:

{
  "SessionStatusChange": [
    {
      "if": {
        "newState": "done"
      },
      "then": [
        { "tool": "close_session", "args": {} },
        { "tool": "send_email", "args": { "to": "[email protected]", "subject": "Session completed" } }
      ]
    }
  ]
}

Legacy Event Mapping

The packages/shared/src/automations/schemas.ts file maintains backward compatibility by mapping legacy TodoStateChange events to the modern SessionStatusChange type. This ensures that existing automations continue functioning while migrating to the current status system.

UI and Prompt Integration

Rendering Status Activities

The UI layer in packages/ui/src/components/chat/turn-utils.ts handles status visualization by checking activity objects with type: 'status'. The component renders a spinner emoji (⏳) while status equals running, a checkmark (✅) when completed, and an error icon (❌) for failures, providing immediate visual feedback on workflow state.

System Prompt Documentation

System prompts defined in packages/shared/src/prompts/system.ts explicitly document the set_session_status tool, instructing agents that status changes can trigger automations via SessionStatusChange events. This documentation ensures that AI agents understand the workflow implications of status updates without requiring hardcoded logic.

Summary

• The status system in Craft Agents uses SessionStatus (defined in packages/core/src/types/session.ts) and workspace-specific statuses/config.json to create configurable workflows.
• Programmatic control flows through the set_session_status tool → handler → SessionManager.setSessionStatus, which persists changes and emits events.
• Automation integration occurs via SessionStatusChange events (defined in packages/shared/src/automations/event-bus.ts), allowing user-defined automations to trigger on status transitions.
• Legacy compatibility is maintained through schema mappings in packages/shared/src/automations/schemas.ts.
• UI reflection and agent prompts ensure that status changes are visible to users and understood by AI agents as workflow triggers.

Frequently Asked Questions

How do I define custom statuses for my workspace?

Create or edit the statuses/config.json file in your workspace root. This JSON file declares the valid status strings (e.g., ["backlog", "in_progress", "needs_review", "done"]) that the validation logic in packages/shared/src/statuses/validation.ts will enforce. Any status not listed in this configuration will be rejected when an agent or script attempts to apply it.

What happens when an agent calls set_session_status?

When an agent invokes the set_session_status tool, the request flows through the handler in packages/session-tools-core/src/handlers/set-session-status.ts to SessionManager.setSessionStatus in packages/server-core/src/sessions/SessionManager.ts. The manager validates the status against the workspace configuration, persists the change to statuses/config.json, and emits a SessionStatusChange event via the automation event bus, potentially triggering user-defined automations before returning success to the agent.

Can I trigger external integrations when a status changes?

Yes, by configuring automations that listen for SessionStatusChange events in your workspace automation files (typically under .craft/automations). According to the schema in packages/shared/src/automations/schemas.ts, you can define conditional logic that invokes tool calls such as send_email, slack_notification, or custom webhooks when a session enters specific states like done or needs_review, enabling seamless integration with external CI/CD pipelines or notification systems.

How does the UI reflect status changes in real-time?

The UI components in packages/ui/src/components/chat/turn-utils.ts monitor activity objects with type: 'status'. When a status activity is running, the interface displays a spinner (⏳); when completed, it shows a checkmark (✅); and when error, it displays a failure icon (❌). Because the SessionManager emits events immediately upon persistence, the UI receives real-time updates through the application's event stream, providing immediate visual feedback on workflow progression without requiring page refreshes.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}