pi-harness-runtime 0.10.12 → 0.10.13

package/IMPLEMENTATION/RFC-0102/TASKS.md

@@ -0,0 +1,75 @@
+# Tasks — RFC-0102 Context Engineering Pipeline
+
+## Phase 1 — intent-analyzer
+
+- [ ] Create `packages/intent-analyzer/src/types.ts` — Intent, IntentKind (14 kinds), IntentConfidence, IntentSignal, IntentRule
+- [ ] Create `packages/intent-analyzer/src/analyzer.ts` — IntentAnalyzer class with keyword scoring, analyze(text), analyzeBatch(texts)
+- [ ] Create `packages/intent-analyzer/src/index.ts` — public barrel
+- [ ] Create `packages/intent-analyzer/test/analyzer.test.ts` — bun test for all 14 intent kinds
+- [ ] Build and verify: `npx tsc -p packages/intent-analyzer/tsconfig.json --skipLibCheck`
+- [ ] Run tests: `bun test packages/intent-analyzer/test/analyzer.test.ts`
+
+## Phase 2 — workspace-scanner
+
+- [ ] Create `packages/workspace-scanner/src/types.ts` — WorkspaceSnapshot, GitState, ProjectConfig, ScannerOptions
+- [ ] Create `packages/workspace-scanner/src/git.ts` — getGitState(rootPath) via git CLI (rev-parse, status --porcelain, log -1)
+- [ ] Create `packages/workspace-scanner/src/detect.ts` — detectProject(rootPath) from file presence (package.json, go.mod, Cargo.toml, etc.)
+- [ ] Create `packages/workspace-scanner/src/scanner.ts` — WorkspaceScanner class orchestrating git + detect
+- [ ] Create `packages/workspace-scanner/src/index.ts` — public barrel
+- [ ] Create `packages/workspace-scanner/test/scanner.test.ts` — bun test with temp dir
+- [ ] Build and verify
+- [ ] Run tests
+
+## Phase 3 — dependency-analyzer
+
+- [ ] Create `packages/dependency-analyzer/src/types.ts` — DependencyKind enum, DependencyNode, DependencyGraph, DependencyEdge
+- [ ] Create `packages/dependency-analyzer/src/imports.ts` — parseImports(content, filePath) regex for TS/JS/CommonJS/Python
+- [ ] Create `packages/dependency-analyzer/src/analyzer.ts` — DependencyAnalyzer class, analyze(filePath, rootPath): DependencyGraph
+- [ ] Create `packages/dependency-analyzer/src/index.ts` — public barrel
+- [ ] Create `packages/dependency-analyzer/test/analyzer.test.ts` — bun test with sample TypeScript
+- [ ] Build and verify
+- [ ] Run tests
+
+## Phase 4 — context-discovery
+
+- [ ] Create `packages/context-discovery/src/types.ts` — DiscoveredContext, DiscoveryOptions, DiscoveryResult
+- [ ] Create `packages/context-discovery/src/discovery.ts` — ContextDiscovery class orchestrating intent + workspace + dependency + OKF
+- [ ] Create `packages/context-discovery/src/index.ts` — public barrel
+- [ ] Create `packages/context-discovery/test/discovery.test.ts` — bun test with mocked dependencies
+- [ ] Build and verify
+- [ ] Run tests
+
+## Phase 5 — context-engineering (Pipeline Coordinator)
+
+- [ ] Create `packages/context-engineering/src/types.ts` — ContextPackage, PipelineOptions, PipelineStats
+- [ ] Create `packages/context-engineering/src/pipeline.ts` — ContextEngineeringPipeline class wiring all 5 packages
+- [ ] Create `packages/context-engineering/src/cache.ts` — ContextCache wrapping @pi/context-compiler cache
+- [ ] Create `packages/context-engineering/src/index.ts` — public barrel
+- [ ] Create `packages/context-engineering/test/pipeline.test.ts` — bun test
+- [ ] Build and verify
+- [ ] Run tests
+
+## Phase 6 — Integration
+
+- [ ] Import `compileContext` from `@pi/context-compiler` in context-discovery
+- [ ] Import `loadOkfConcepts` from `@pi/context-compiler/src/okf-loader.js` in context-discovery
+- [ ] Wire ContextEngineeringPipeline output to provider router input format
+- [ ] Verify full pipeline builds: `npx tsc` across all 5 packages
+
+## Phase 7 — Tests
+
+- [ ] Unit: intent-analyzer — all 14 intent kinds detected correctly
+- [ ] Unit: workspace-scanner — git state, project type, framework detection
+- [ ] Unit: dependency-analyzer — import parsing for TS/JS/Python, cycle detection
+- [ ] Unit: context-discovery — candidates collected from all sources
+- [ ] Integration: full pipeline on known test workspace
+- [ ] Security: policy filter denies .env files
+
+## Phase 8 — Documentation
+
+- [ ] Write `packages/intent-analyzer/README.md`
+- [ ] Write `packages/workspace-scanner/README.md`
+- [ ] Write `packages/dependency-analyzer/README.md`
+- [ ] Write `packages/context-discovery/README.md`
+- [ ] Write `packages/context-engineering/README.md`
+- [ ] Update root `README.md` with RFC-0102 reference

package/IMPLEMENTATION/RFC-0102/TESTS.md

@@ -0,0 +1,78 @@
+# Tests — RFC-0102 Context Engineering Pipeline
+
+## intent-analyzer
+
+### Unit Tests
+
+| Test | Input | Expected |
+|---|---|---|
+| bug_fix detection | "fix the login bug" | kind = "bug_fix" |
+| feature detection | "add dark mode support" | kind = "feature" |
+| refactor detection | "refactor the auth module" | kind = "refactor" |
+| code_review detection | "review the pull request" | kind = "code_review" |
+| testing detection | "write tests for payment" | kind = "testing" |
+| deployment detection | "deploy to production" | kind = "deployment" |
+| security detection | "fix auth vulnerability" | kind = "security" |
+| performance detection | "optimize database query" | kind = "performance" |
+| architecture detection | "review architecture design" | kind = "architecture" |
+| migration detection | "migrate to TypeScript" | kind = "migration" |
+| research detection | "investigate memory leak" | kind = "research" |
+| learning detection | "explain how X works" | kind = "learning" |
+| documentation detection | "add README for API" | kind = "documentation" |
+| general fallback | "hello world" | kind = "general" |
+| multiple keywords | "fix the security bug" | kind = "bug_fix" (both signals) |
+| analyzeBatch | ["fix bug", "add feat"] | [bug_fix, feature] |
+
+## workspace-scanner
+
+### Unit Tests
+
+| Test | Setup | Expected |
+|---|---|---|
+| detects package.json | package.json in dir | hasNode = true |
+| detects pyproject.toml | pyproject.toml in dir | hasPython = true |
+| detects git repo | .git in dir | hasGit = true |
+| detects dirty git | git with modified files | isDirty = true |
+| detects branch | git on branch "feature-x" | branch = "feature-x" |
+| detects vite | vite.config.ts in dir | framework = "vite" |
+| detects next | next.config.js in dir | framework = "next" |
+| skips git | skipGit = true | git = null |
+| skips config | skipConfig = true | project = {} |
+
+## dependency-analyzer
+
+### Unit Tests
+
+| Test | Input | Expected |
+|---|---|---|
+| ESM default import | `import x from './y'` | ['./y'] |
+| ESM named import | `import { a, b } from './x'` | ['./x'] |
+| ESM package import | `import pkg from 'lodash'` | ['lodash'] |
+| ESM namespace | `import * as x from './y'` | ['./y'] |
+| CommonJS require | `const x = require('./y')` | ['./y'] |
+| Python from-import | `from os import path` | ['os'] |
+| Python direct import | `import numpy` | ['numpy'] |
+| cycle detection | a->b->c->a | cycle = ['a','b','c'] |
+| empty file | '' | [] |
+
+## context-discovery
+
+### Unit Tests
+
+| Test | Setup | Expected |
+|---|---|---|
+| discovers package.json | npm workspace | candidates has package.json |
+| discovers git diff | modified files | candidates has modified files |
+| filters .env | workspace has .env | .env not in candidates |
+| filters node_modules | workspace has node_modules | node_modules not in candidates |
+
+## context-engineering
+
+### Integration Tests
+
+| Test | Setup | Expected |
+|---|---|---|
+| full pipeline | known workspace + task | ContextPackage with intent + files |
+| cache hit | same task twice | second call faster |
+| cache miss | git branch changed | rebuild triggered |
+| policy deny | AGENTS.md denies *.pem | pem files omitted |

package/IMPLEMENTATION/RFC-0103/ACCEPTANCE_CRITERIA.md

@@ -0,0 +1,45 @@
+# Acceptance Criteria — RFC-0103 Session Event Runtime
+
+## Functional
+
+- [ ] EventStore.append() generates id + timestamp, appends JSONL line
+- [ ] EventStore.read() returns events filtered by sessionId, since, types, limit
+- [ ] EventStore.search() returns events matching text query
+- [ ] EventStore.stats() returns totalEvents, sizeBytes, lastEventAt
+- [ ] EventStore.list() returns all session IDs from ~/.pi/sessions/
+- [ ] EventBus.publish() returns eventId, notifies all matching subscribers
+- [ ] EventBus.subscribe() returns subscriptionId, sorted by priority (higher first)
+- [ ] EventBus.subscribe() with filter only notifies when filter(data) returns true
+- [ ] EventBus.unsubscribe() removes subscription, no further notifications
+- [ ] EventBus.replay() delivers historical events to new subscriber
+- [ ] ProjectionEngine.addEvent() updates all projections
+- [ ] ProjectionEngine.getDecisions() returns detected architecture decisions
+- [ ] ProjectionEngine.getSummary() returns messageCount, toolCount, decisionCount, topics
+- [ ] SemanticEventBuilder.buildFromSessionEvents() converts SessionEvents to SemanticEvents
+- [ ] WorkflowStateMachine.transition() advances state based on semantic event
+- [ ] SubscriptionEngine.subscribe() creates subscription with predicate
+- [ ] SubscriptionEngine.match() returns all subscriptions whose predicate matches
+- [ ] SessionService.getLatestDecision() returns most recent decision
+- [ ] SessionService.search() returns matching events from event-store
+- [ ] SessionExporter.toMarkdown() generates readable markdown with timeline
+- [ ] SessionExporter.toJson() generates structured JSON export
+- [ ] Clipboard.copy() writes text to system clipboard
+- [ ] Clipboard.read() reads from system clipboard
+- [ ] /copy last — copies latest assistant message via clipboard
+- [ ] /export last — exports latest response via session-export
+
+## Non-Functional
+
+- [ ] All 8 packages compile with zero TypeScript errors
+- [ ] All tests pass: `bun test packages/*/test/*.test.ts`
+- [ ] event-store handles corrupted JSONL lines gracefully (skip + warn)
+- [ ] event-bus handles subscriber crash gracefully (remove dead subscriber)
+- [ ] projection-engine handles empty events array gracefully
+- [ ] clipboard gracefully handles unavailable clipboard (fallback message)
+- [ ] SessionService never reads JSONL directly — always through event-store
+
+## Integration
+
+- [ ] autonomous-runtime (RFC-0101) publishes WorkerStarted, TaskAssigned, TaskCompleted via EventBus
+- [ ] context-engineering (RFC-0102) reads session via SessionService.getRecentFailures()
+- [ ] JSONL format preserved — same format as existing pi session files

package/IMPLEMENTATION/RFC-0103/AI_BRIEF.md

@@ -0,0 +1,46 @@
+# AI Brief — RFC-0103 Session Event Runtime & Agent Communication Layer
+
+## What is being built
+
+An 8-package system that transforms pi's JSONL session files into a real-time event bus for autonomous agents:
+
+1. **event-store** — immutable JSONL wrapper: append, read, search, stats
+2. **event-bus** — typed pub/sub with priority, filtering, replay
+3. **projection-engine** — semantic views from raw events (decisions, tasks, summary, timeline)
+4. **workflow-events** — semantic event vocabulary + state machine
+5. **subscription-engine** — predicate-based agent subscriptions
+6. **session-api** — safe read-only API (never parse JSONL directly)
+7. **session-export** — markdown/JSON/text/HTML export
+8. **clipboard** — /copy and /export commands
+
+## Key interfaces
+
+- `SessionEvent` — { id, sessionId, timestamp, type, role?, content?, tool?, metadata? }
+- `EventPayload<T>` — { topic, data, timestamp, eventId, source }
+- `SemanticEvent` — discriminated union: TaskAssigned/Started/Completed, ReviewRequested, ArchitectureDecision, etc.
+- `EventBus` — publish(topic, data), subscribe(topic, fn, filter?, priority?)
+- `SessionService` — getLatestDecision(), getRecentFailures(), search(), getSummary()
+
+## Integration
+
+- event-store reads/writes JSONL at `~/.pi/sessions/`
+- event-bus uses Node.js EventEmitter internally
+- projection-engine consumes SessionEvents, emits typed views
+- subscription-engine wraps event-bus for predicate filtering
+- session-api uses projection-engine + event-store for read operations
+- autonomous-runtime (RFC-0101) publishes lifecycle events via event-bus
+- context-engineering (RFC-0102) uses session-api for historical context
+
+## Testing strategy
+
+- event-store: mock temp JSONL file, test append/read/search
+- event-bus: test pub/sub, priority ordering, filter, unsubscribe, replay
+- projection-engine: test decision detection, task state, summary counts
+- workflow-events: test state machine transitions
+- Mock JSONL fixtures for CI
+
+## Security
+
+- No direct JSONL access from agents — must use SessionService
+- Replay attack prevention via eventId deduplication
+- Capability enforcement via SubscriptionEngine

package/IMPLEMENTATION/RFC-0103/FILES.md

@@ -0,0 +1,121 @@
+# Files — RFC-0103 Session Event Runtime & Agent Communication Layer
+
+## New Packages
+
+```
+packages/
++-- event-store/
+|   +-- src/
+|   |   +-- types.ts         # SessionEvent, SessionEventType, EventMetadata,
+|   |   |                      # StoreOptions, StoreStats, WriteResult,
+|   |   |                      # ReadOptions, SearchOptions
+|   |   +-- store.ts          # EventStore class — append/read/search/stats/list
+|   |   +-- index.ts          # Public barrel
+|   +-- test/
+|   |   +-- store.test.ts    # bun test — temp JSONL file
+|   +-- package.json
+|   +-- tsconfig.json
+|
++-- event-bus/
+|   +-- src/
+|   |   +-- types.ts          # Topic, EventPayload, Subscriber, Subscription,
+|   |   |                      # BusOptions, EventBusError
+|   |   +-- bus.ts            # EventBus class — Map-based pub/sub + EventEmitter
+|   |   +-- index.ts          # Public barrel
+|   +-- test/
+|   |   +-- bus.test.ts       # bun test — pub/sub, priority, filter, replay
+|   +-- package.json
+|   +-- tsconfig.json
+|
++-- projection-engine/
+|   +-- src/
+|   |   +-- types.ts          # Projection, Decision, TaskState,
+|   |   |                      # KnowledgeExtraction, AgentTimeline,
+|   |   |                      # SessionSummary
+|   |   +-- engine.ts          # ProjectionEngine class — addEvent, projections
+|   |   +-- projections/
+|   |   |   +-- decision-projector.ts   # detectArchitectureDecision()
+|   |   |   +-- task-projector.ts      # detectTaskState()
+|   |   |   +-- summary-projector.ts   # buildSummary()
+|   |   |   +-- timeline-projector.ts # buildTimeline()
+|   |   +-- index.ts          # Public barrel
+|   +-- test/
+|   |   +-- engine.test.ts    # bun test — projections
+|   +-- package.json
+|   +-- tsconfig.json
+|
++-- workflow-events/
+|   +-- src/
+|   |   +-- types.ts          # SemanticEvent discriminated union (12 variants),
+|   |   |                      # WorkflowState, WorkflowTransition
+|   |   +-- builder.ts        # SemanticEventBuilder — buildFromSessionEvents()
+|   |   +-- workflow.ts       # WorkflowStateMachine — transition(), getState()
+|   |   +-- index.ts          # Public barrel
+|   +-- test/
+|   |   +-- workflow.test.ts # bun test — transitions
+|   +-- package.json
+|   +-- tsconfig.json
+|
++-- subscription-engine/
+|   +-- src/
+|   |   +-- types.ts          # Predicate<T>, TopicSubscription<T>,
+|   |   |                      # SubscriptionResult, SubscriberInfo
+|   |   +-- engine.ts          # SubscriptionEngine — subscribe/unsubscribe/match
+|   |   +-- index.ts          # Public barrel
+|   +-- test/
+|   |   +-- engine.test.ts    # bun test — predicate filtering
+|   +-- package.json
+|   +-- tsconfig.json
+|
++-- session-api/
+|   +-- src/
+|   |   +-- types.ts          # SessionService interface, SessionQuery
+|   |   +-- api.ts            # SessionServiceImpl — getLatestDecision(),
+|   |   |                      # getRecentFailures(), search(), getSummary()
+|   |   +-- index.ts          # Public barrel
+|   +-- test/
+|   |   +-- api.test.ts       # bun test — mock event store
+|   +-- package.json
+|   +-- tsconfig.json
+|
++-- session-export/
+|   +-- src/
+|   |   +-- types.ts          # ExportFormat, ExportRequest, ExportResult
+|   |   +-- exporter.ts        # SessionExporter — toMarkdown(), toJson(),
+|   |   |                      # toText(), toHtml()
+|   |   +-- index.ts          # Public barrel
+|   +-- test/
+|   |   +-- export.test.ts    # bun test — formats
+|   +-- package.json
+|   +-- tsconfig.json
+|
++-- clipboard/
+    +-- src/
+    |   +-- types.ts          # ClipboardContent, ClipboardOptions
+    |   +-- clipboard.ts       # copy(), read(), copyLastResponse()
+    |   +-- index.ts          # Public barrel
+    +-- test/
+    |   +-- clipboard.test.ts # bun test — mock
+    +-- package.json
+    +-- tsconfig.json
+```
+
+## Integration
+
+| Source | Import from |
+|---|---|
+| Session JSONL path | `~/.pi/sessions/` — convention |
+| SessionService | `session-api` — used by `context-engineering` |
+| Event Bus | `event-bus` — used by `workflow-events`, `subscription-engine` |
+| Semantic Events | `workflow-events` — used by `autonomous-runtime` (RFC-0101) |
+
+## Dependencies
+
+- `event-store` — standalone, no dependencies
+- `event-bus` — uses `crypto.randomUUID()`, no dependencies
+- `projection-engine` — uses `event-store` (or mock)
+- `workflow-events` — uses `event-store` (or mock)
+- `subscription-engine` — uses `event-bus` (or mock)
+- `session-api` — uses `event-store` + `projection-engine`
+- `session-export` — uses `session-api`
+- `clipboard` — uses `session-api`; fallback: `/dev/clipboard` on Linux

package/IMPLEMENTATION/RFC-0103/TASKS.md

@@ -0,0 +1,97 @@
+# Tasks — RFC-0103 Session Event Runtime & Agent Communication Layer
+
+## Phase 1 — event-store
+
+- [ ] Create `packages/event-store/src/types.ts` — SessionEvent, SessionEventType, EventMetadata, StoreOptions, StoreStats, WriteResult, ReadOptions, SearchOptions
+- [ ] Create `packages/event-store/src/store.ts` — EventStore class: append(), read(), search(), stats(), list(), getPath()
+- [ ] Create `packages/event-store/src/index.ts` — public barrel
+- [ ] Create `packages/event-store/test/store.test.ts` — bun test with temp dir JSONL
+- [ ] Build and verify: `npx tsc -p packages/event-store/tsconfig.json --skipLibCheck`
+- [ ] Run tests: `bun test packages/event-store/test/store.test.ts`
+
+## Phase 2 — event-bus
+
+- [ ] Create `packages/event-bus/src/types.ts` — Topic union, EventPayload, Subscriber, Subscription, BusOptions, EventBusError
+- [ ] Create `packages/event-bus/src/bus.ts` — EventBus class: publish(), subscribe(), unsubscribe(), unsubscribeAll(), replay(), getSubscribers()
+- [ ] Create `packages/event-bus/src/index.ts` — public barrel
+- [ ] Create `packages/event-bus/test/bus.test.ts` — bun test: pub/sub, priority ordering, filter, unsubscribe, replay
+- [ ] Build and verify
+- [ ] Run tests
+
+## Phase 3 — projection-engine
+
+- [ ] Create `packages/projection-engine/src/types.ts` — Projection<T>, Decision, TaskState, KnowledgeExtraction, AgentTimeline, SessionSummary
+- [ ] Create `packages/projection-engine/src/projections/decision-projector.ts` — detectArchitectureDecision(events): Decision[]
+- [ ] Create `packages/projection-engine/src/projections/task-projector.ts` — detectTaskState(events): TaskState[]
+- [ ] Create `packages/projection-engine/src/projections/summary-projector.ts` — buildSummary(events): SessionSummary
+- [ ] Create `packages/projection-engine/src/projections/timeline-projector.ts` — buildTimeline(events): AgentTimeline[]
+- [ ] Create `packages/projection-engine/src/engine.ts` — ProjectionEngine class: addEvent(), getDecision(), getDecisions(), getTaskState(), getTaskStates(), getSummary(), getTimeline(), reset()
+- [ ] Create `packages/projection-engine/src/index.ts` — public barrel
+- [ ] Create `packages/projection-engine/test/engine.test.ts` — bun test
+- [ ] Build and verify
+- [ ] Run tests
+
+## Phase 4 — workflow-events
+
+- [ ] Create `packages/workflow-events/src/types.ts` — SemanticEvent discriminated union (12 variants), WorkflowState, WorkflowTransition
+- [ ] Create `packages/workflow-events/src/builder.ts` — SemanticEventBuilder: buildFromSessionEvents(), detectTaskAssigned(), detectTaskCompleted(), detectReviewRequested(), detectArchitectureDecision(), detectHumanApproval()
+- [ ] Create `packages/workflow-events/src/workflow.ts` — WorkflowStateMachine: transition(), getState(), getHistory()
+- [ ] Create `packages/workflow-events/src/index.ts` — public barrel
+- [ ] Create `packages/workflow-events/test/workflow.test.ts` — bun test
+- [ ] Build and verify
+- [ ] Run tests
+
+## Phase 5 — subscription-engine
+
+- [ ] Create `packages/subscription-engine/src/types.ts` — Predicate<T>, TopicSubscription<T>, SubscriptionResult, SubscriberInfo
+- [ ] Create `packages/subscription-engine/src/engine.ts` — SubscriptionEngine: subscribe(), unsubscribe(), unsubscribeAgent(), getSubscriptions(), getAgents(), match<T>()
+- [ ] Create `packages/subscription-engine/src/index.ts` — public barrel
+- [ ] Create `packages/subscription-engine/test/engine.test.ts` — bun test: predicate filtering
+- [ ] Build and verify
+- [ ] Run tests
+
+## Phase 6 — session-api
+
+- [ ] Create `packages/session-api/src/types.ts` — SessionService interface, SessionQuery
+- [ ] Create `packages/session-api/src/api.ts` — SessionServiceImpl: getLatestDecision(), getLatestTask(), getRecentFailures(), getArchitectureHistory(), getWorkflowState(), getLatestSummary(), search(), getAgentTimeline(), getSessionTimeline()
+- [ ] Create `packages/session-api/src/index.ts` — public barrel
+- [ ] Create `packages/session-api/test/api.test.ts` — bun test with mock event store + projection engine
+- [ ] Build and verify
+- [ ] Run tests
+
+## Phase 7 — session-export
+
+- [ ] Create `packages/session-export/src/types.ts` — ExportFormat enum, ExportRequest, ExportResult
+- [ ] Create `packages/session-export/src/exporter.ts` — SessionExporter: export(), toMarkdown(), toJson(), toText(), toHtml()
+- [ ] Create `packages/session-export/src/index.ts` — public barrel
+- [ ] Create `packages/session-export/test/export.test.ts` — bun test
+- [ ] Build and verify
+- [ ] Run tests
+
+## Phase 8 — clipboard
+
+- [ ] Create `packages/clipboard/src/types.ts` — ClipboardContent, ClipboardOptions
+- [ ] Create `packages/clipboard/src/clipboard.ts` — copy(), read(), copyLastResponse() with /dev/clipboard fallback
+- [ ] Create `packages/clipboard/src/index.ts` — public barrel
+- [ ] Create `packages/clipboard/test/clipboard.test.ts` — bun test (mock)
+- [ ] Build and verify
+- [ ] Run tests
+
+## Phase 9 — Integration
+
+- [ ] Wire autonomous-runtime (RFC-0101) to publish events via event-bus
+- [ ] Wire context-engineering (RFC-0102) to read session via session-api
+- [ ] Verify all 8 packages build: `npx tsc` across all
+- [ ] Verify all tests pass: `bun test packages/*/test/*.test.ts`
+
+## Phase 10 — Documentation
+
+- [ ] Write `packages/event-store/README.md`
+- [ ] Write `packages/event-bus/README.md`
+- [ ] Write `packages/projection-engine/README.md`
+- [ ] Write `packages/workflow-events/README.md`
+- [ ] Write `packages/subscription-engine/README.md`
+- [ ] Write `packages/session-api/README.md`
+- [ ] Write `packages/session-export/README.md`
+- [ ] Write `packages/clipboard/README.md`
+- [ ] Update root `README.md` with RFC-0103 reference

package/IMPLEMENTATION/RFC-0103/TESTS.md

@@ -0,0 +1,118 @@
+# Tests — RFC-0103 Session Event Runtime
+
+## event-store
+
+### Unit Tests
+
+| Test | Setup | Expected |
+|---|---|---|
+| append generates id | empty temp dir | event.id is valid UUID |
+| append generates timestamp | empty temp dir | event.timestamp is ISO string |
+| append writes JSONL line | empty temp dir | file contains one JSON line |
+| read by sessionId | 2 sessions in dir | returns only matching session |
+| read with since filter | events before/after timestamp | returns only after |
+| read with type filter | message + tool events | returns only matching types |
+| read with limit | 10 events | returns at most 10 |
+| search by content | events with "error" | returns matching events |
+| search query case-insensitive | events with "Error" | returns matching |
+| stats returns count | 5 events | totalEvents = 5 |
+| list sessions | 2 session files | returns 2 IDs |
+| handles corrupt line | JSONL with invalid JSON | skips line, warns |
+
+## event-bus
+
+### Unit Tests
+
+| Test | Setup | Expected |
+|---|---|---|
+| publish returns eventId | subscribe then publish | returns UUID string |
+| subscriber receives event | subscribe + publish | subscriber called with payload |
+| multiple subscribers | 3 subscribers, one topic | all 3 called |
+| unsubscribe removes subscriber | subscribe, unsubscribe, publish | subscriber not called |
+| unsubscribeAll removes all | subscribe to 2 topics, unsubscribeAll | no subscribers |
+| priority ordering | 2 subscribers, priority 1 and 2 | priority 2 called first |
+| filter predicates | subscribe with filter, matching event | subscriber called |
+| filter predicates | subscribe with filter, non-matching event | subscriber NOT called |
+| replay delivers history | subscribe, replay([events]) | subscriber called for each |
+| topic wildcard | subscribe("*") | receives all events |
+| duplicate topic subscribe | subscribe same topic twice | 2 subscriptions, 2 calls |
+| subscriber crash | subscriber throws | other subscribers still called |
+
+## projection-engine
+
+### Unit Tests
+
+| Test | Input | Expected |
+|---|---|---|
+| decision detection | assistant message with "RFC" | Decision.kind = "ArchitectureDecision" |
+| decision detection | assistant message with "decision: use X" | Decision detected |
+| task state detection | tool event with "task-id" | TaskState with correct id |
+| summary counts messages | 5 message events | messageCount = 5 |
+| summary counts tools | 3 tool events | toolCount = 3 |
+| summary infers topics | messages with "deploy" keyword | topics includes "deployment" |
+| timeline groups by agent | events from 2 agents | 2 AgentTimeline entries |
+| reset clears all | add events, reset() | all projections empty |
+| empty events array | [] | graceful, empty results |
+
+## workflow-events
+
+### Unit Tests
+
+| Test | Input | Expected |
+|---|---|---|
+| build TaskAssigned | SessionEvent type="task_assigned" | SemanticEvent.kind = "TaskAssigned" |
+| build TaskCompleted | SessionEvent type="task_completed" | SemanticEvent.kind = "TaskCompleted" |
+| build ReviewRequested | SessionEvent with "review" content | SemanticEvent.kind = "ReviewRequested" |
+| state machine idle->running | TaskStarted event | state.status = "running" |
+| state machine running->finished | WorkflowFinished event | state.status = "finished" |
+| history records transitions | 3 transitions | history.length = 3 |
+
+## subscription-engine
+
+### Unit Tests
+
+| Test | Setup | Expected |
+|---|---|---|
+| subscribe returns id | subscribe agent to topic | returns UUID string |
+| unsubscribe by id | subscribe, unsubscribe | subscription removed |
+| unsubscribeAgent removes all | agent subscribed to 2 topics | all removed |
+| getSubscriptions by agent | 2 agents subscribed | returns only that agent's |
+| match returns predicates | predicate returns true | subscription in match results |
+| match filters | predicate returns false | subscription NOT in match results |
+| priority passed through | subscribe with priority 5 | stored with priority 5 |
+
+## session-api
+
+### Unit Tests
+
+| Test | Setup | Expected |
+|---|---|---|
+| getLatestDecision | 2 decisions in store | returns most recent |
+| getRecentFailures | 3 failure events | returns 3 |
+| search | query "login" | returns matching events |
+| getSummary | mixed events | returns SessionSummary |
+| getAgentTimeline | events from agent-1 | returns AgentTimeline for agent-1 |
+
+## session-export
+
+### Unit Tests
+
+| Test | Input | Expected |
+|---|---|---|
+| toMarkdown has header | events | starts with "# Session" |
+| toMarkdown has timeline | events | contains timestamps |
+| toJson is valid JSON | events | JSON.parse succeeds |
+| toText is plain text | events | no markdown formatting |
+| export with format=markdown | events | content starts with # |
+| export with format=json | events | content is JSON |
+| eventCount in result | 5 events | eventCount = 5 |
+
+## clipboard
+
+### Unit Tests
+
+| Test | Setup | Expected |
+|---|---|---|
+| copy writes text | text "hello" | no error thrown |
+| read returns string | clipboard has text | returns string |
+| copyLastResponse gets latest | sessionApi with messages | latest assistant message copied |

package/IMPLEMENTATION/RFC-0104/ACCEPTANCE_CRITERIA.md

@@ -0,0 +1,29 @@
+# RFC-0104 Acceptance Criteria
+
+## Functional Requirements
+
+- [ ] A2A Adapter sends tasks to remote agents
+- [ ] Agent Card correctly advertises capabilities
+- [ ] Task lifecycle (create, status, cancel) works
+- [ ] Integration with RFC-0103 event bus
+- [ ] Streaming responses via SSE
+- [ ] Push notification support
+
+## Non-Functional Requirements
+
+- [ ] Latency < 500ms for task dispatch
+- [ ] Graceful timeout handling
+- [ ] Retry on transient failures
+- [ ] Authentication on A2A endpoints
+
+## Integration Tests
+
+- [ ] Local task → Remote agent → Response back to local
+- [ ] Task cancellation propagates
+- [ ] Error handling on network failure
+
+## Documentation
+
+- [ ] README with setup instructions
+- [ ] Protocol specification
+- [ ] Example usage

package/IMPLEMENTATION/RFC-0104/FILES.md

@@ -0,0 +1,33 @@
+# RFC-0104 Files
+
+## Source Files
+
+```
+packages/
+  a2a-adapter/
+    src/
+      index.ts           # Main exports
+      agent-card.ts      # AgentCard schema
+      client.ts         # A2A client
+      server.ts         # A2A server
+      types.ts          # Shared types
+```
+
+## Configuration
+
+```
+configs/
+  a2a/
+    agent-card.json      # Local agent manifest
+    server.json         # Server config
+```
+
+## Documentation
+
+```
+docs/
+  a2a/
+    README.md
+    PROTOCOL.md
+    EXAMPLES.md
+```