> For the complete documentation index, see [llms.txt](https://faction-os.gitbook.io/faction-os-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://faction-os.gitbook.io/faction-os-docs/.spec_system/archive/phases/phase_19/session_01_protocol_and_events.md).

# Session 01: Protocol And Events

**Session ID**: `phase19-session01-protocol-and-events` **Package**: packages/protocol **Status**: Complete **Completed**: 2026-06-26 **Estimated Tasks**: \~12-25 **Estimated Duration**: 2-4 hours

***

## Objective

Define the shared orchestration contracts that every later Phase 19 server, store, and panel slice will depend on.

***

## Scope

### In Scope (MVP)

* Plan campaign and plan task DTOs with state, dependency, revision, owner, verification, and assignment fields
* Attention item, executor capability, hero lifecycle command, execution run, permission request, file intent, workpad, evidence, verification attempt, review gate, handoff, diagnostic, channel command, and usage metric DTOs
* WebSocket event schemas for plan, task, attention, executor, hero, execution, permission, file intent, workpad, evidence, verification, handoff, diagnostic, channel command, and usage updates
* Fixture round trips for current guarded action, queue, template, and lineage payload compatibility
* Protocol README updates for new contracts and compatibility boundaries

### Out of Scope

* Server managers, persistence, REST routes, or web store wiring
* Family-specific executor implementation

***

## Prerequisites

* [x] Phase 19 PRD reviewed
* [x] Current guarded action, queue, lineage, template, and event contract files inspected

***

## Deliverables

1. Protocol modules exporting the new DTO, validator, and event schemas
2. Valid and invalid fixtures covering all new event families
3. Protocol tests for parsing, rejection, and compatibility behavior
4. README notes documenting the contracts and unavailable-state semantics

***

## Source Coverage And Evidence

Source coverage:

* Session Split Plan Session 01: Protocol And Events
* Implementation targets that introduce shared plan, attention, executor, permission, file intent, workpad, evidence, verification, handoff, diagnostic, channel, usage, and WebSocket shapes
* Balls-To-The-Wall Track A: Protocol And Events
* Appendix A Reference Index for architecture, route, event, hook, prompt, and package evidence

Key EXAMPLES links:

* [Architecture executors](https://github.com/AI-with-Apex-VIP/factionos/tree/main/.spec_system/EXAMPLES/findings/architecture.md#L140-L195)
* [Historical REST inventory](https://github.com/AI-with-Apex-VIP/factionos/tree/main/.spec_system/EXAMPLES/findings/api-routes.txt#L1-L210)
* [Historical WebSocket inventory](https://github.com/AI-with-Apex-VIP/factionos/tree/main/.spec_system/EXAMPLES/findings/websocket-events.txt#L1-L172)
* [Claude hook contract](https://github.com/AI-with-Apex-VIP/factionos/tree/main/.spec_system/EXAMPLES/findings/claude-hook-contract.md#L1-L236)
* [Plan decomposer prompt](https://github.com/AI-with-Apex-VIP/factionos/tree/main/.spec_system/EXAMPLES/findings/llm-prompts/plan-decomposer.md#L1-L76)

***

## Success Criteria

* [x] Protocol tests pass for every added DTO and event family
* [x] Existing guarded action, queue, template, and lineage consumers compile
* [x] Documentation names each new DTO/event and its owning surface
* [x] Unsupported or future families have explicit capability states rather than ambiguous placeholders


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://faction-os.gitbook.io/faction-os-docs/.spec_system/archive/phases/phase_19/session_01_protocol_and_events.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.