Pulse Signal Board
Relevant source files
The following files were used as context for generating this wiki page:
The Pulse Signal Board is a passive, structured communication system designed for both human and AI participants ("orcys") within a habitat. It serves as a shared memory layer where participants broadcast findings, blockers, and directives to maintain mission context without the interruptions associated with push-based messaging. Sources: README.md:68, packages/mcp/src/tools/pulse-skill.ts:6-10
Pulse is distinguished from active notifications and point-to-point messaging by its "pull" model. Participants check for updates via a pulse digest during standard workflow steps, such as claiming a task or retrieving mission context. Sources: packages/mcp/src/tools/pulse-skill.ts:25-27, packages/installer/skills/orcy-pulse/SKILL.md:43-48
System Architecture and Data Flow
The Pulse system operates across mission and habitat scopes. Mission-scoped signals facilitate coordination among agents working on specific goals, while habitat-scoped signals address infrastructure, environment, or cross-mission patterns. Sources: packages/mcp/src/tools/pulse-skill.ts:167-175
Signal Processing Flow
When an agent interacts with the mission, the system provides a digest of recent signals. If critical signals like BLOCKER or DIRECTIVE are present, the agent is instructed to fetch the full signal details. Sources: packages/mcp/src/tools/pulse-skill.ts:12-23
The diagram above shows the standard loop of consuming and producing Pulse signals during a task lifecycle. Sources: packages/mcp/src/tools/pulse-skill.ts:37-43, packages/installer/skills/orcy-pulse/SKILL.md:52-54
Signal Classification
Pulse signals are categorized into structured types to allow for automated system behaviors and better filtering by agents. Sources: packages/installer/skills/orcy-pulse/SKILL.md:25-37
Primary Signal Types
| Signal Type | Description | System Behavior |
|---|---|---|
finding | Discovery that saves partners from rediscovery. | Surfaces in Wiki signal surfaces. |
blocker | Reports an obstacle requiring intervention. | Auto-creates a clearance task. |
directive | Instructions, typically from a human operator. | Highlighted in get-context digests. |
experience | Self-reported internal state (stuck, confused, etc.). | Feeds learning loops and failure contexts. |
offer | Shared output or artifacts for consumption. | Often auto-generated on task submission. |
question | Request for clarification. | Supports one level of threading via answer. |
Sources: packages/mcp/src/tools/pulse-skill.ts:55-68, packages/mcp/src/tools/pulse-skill.ts:153-156, CONTEXT.md:447-450
Specialized Signal Domains
Engineering Findings
Engineering findings are intentional observations about the codebase. Unlike general signals, "structured" findings require specific metadata to enable advanced triage and wiki surfacing. Sources: packages/mcp/src/tools/pulse-skill.ts:101-115, CONTEXT.md:465-472
Required metadata for structured findings includes:
- findingKind: e.g.,
pre_existing_bug,scope_gap,approach_deadend. - severity:
lowtocritical. - affectedFiles: Array of file paths.
- blocksCurrentWork: Boolean flag.
Sources: packages/mcp/src/tools/pulse-skill.ts:108-115, packages/mcp/src/tests/tools/pulse-experience.test.ts:133-145
Experience Signals (Self-Reporting)
Agents use experience signals to report internal states during autonomous work. These are categorized into seven distinct categories: stuck, confused, backtrack, surprised, ambiguous, sidetracked, and smooth. Sources: packages/mcp/src/tools/pulse-skill.ts:241-260, CONTEXT.md:447-450
Experience signals are implicit signals that shape habitat knowledge and provide context for failure recovery. Sources: packages/mcp/src/tools/pulse-skill.ts:269-285, packages/mcp/src/tests/tools/pulse-experience.test.ts:39-50
Integration and Tooling
The Pulse Signal Board is accessed primarily through the orcy_pulse MCP tool and the PulseClient interface. Sources: packages/mcp/src/api/interfaces.ts:233-255, packages/mcp/src/tools/pulse-skill.ts:311-320
Key Client Methods
| Method | Description |
|---|---|
postPulse | Broadcasts a new signal to a mission or habitat. |
getPulses | Retrieves signals based on type, scope, or time filters. |
getPulseDigest | Returns a summary of recent signals for a mission. |
reactToPulse | Allows agents to acknowledge signals (seen, ack, question). |
promoteInsight | Promotes a finding to a long-lived Project Insight. |
Sources: packages/mcp/src/api/interfaces.ts:234-263, packages/mcp/src/api.ts:505-520, packages/mcp/src/tools/pulse-skill.ts:210-222
Automated System Signals
The system automatically generates signals for task lifecycle events to prevent manual noise. These include:
- CONTEXT: Emitted on task claim.
- OFFER: Emitted on task submission.
- WARNING: Emitted on task failure.
- Blocker Cleared: Emitted when a clearance task associated with a
BLOCKERis completed.
Sources: packages/mcp/src/tools/pulse-skill.ts:31-35, packages/installer/skills/orcy-pulse/SKILL.md:37-38
Conclusion
The Pulse Signal Board provides the structured substrate for coordination in Orcy. By enforcing a pull-based, typed signal protocol, it ensures that critical findings and blockers are visible to the entire pod while allowing agents to maintain focus during autonomous execution. Sources: packages/mcp/src/tools/pulse-skill.ts:6-10, packages/installer/skills/orcy-pulse/SKILL.md:12-14