pi-harness-runtime 0.10.13 → 0.10.15

package/IMPLEMENTATION/RFC-0101/TESTS.md

@@ -1,127 +0,0 @@
-# Test Plan — RFC-0101
-
-## Unit Tests
-
-### Inbox
-
-- `inbox.append` writes one JSON line per call to `tasks.jsonl`.
-- `inbox.list` returns queued tasks in stable order (priority -> createdAt).
-- `inbox.transition` updates status atomically with history append.
-- `inbox.archive` moves completed records after the retention window.
-
-### Lease
-
-- `lease.claim` returns a lease and writes the lease file atomically.
-- Two parallel `claim` calls on the same task — exactly one wins.
-- `lease.heartbeat` extends `expiresAt`; cross-worker heartbeat aborts safely.
-- `lease.reap` releases leases past `expiresAt + grace` and writes a `recovered` history entry.
-- Lease file with corrupt JSON is quarantined, not silently reaped.
-
-### Worker
-
-- `worker.loop` claims the next ready task and runs it through the inner loop.
-- `worker.recoverOnStartup` calls `lease.reap` once before the main loop.
-- `worker.heartbeat` writes to `worker-registry.json` at the configured cadence.
-- Worker `SIGTERM` handler runs graceful shutdown and exits 0.
-
-### Privilege Broker
-
-- `registry.load` reads `config/privileges.yaml` and rejects unknown capabilities.
-- `executor.execve` runs an exact `argv` with no shell.
-- `executor.argvTampering` — passing extra args that do not match the registered `argv` is rejected.
-- `executor.unknownCapability` fails with a structured `BrokerDeniedError`.
-- `audit.append` writes one line per broker call; rotation reads `logrotate` config and works under simulated 24 h clock.
-
-### Policy Engine Integration
-
-- `policy.class(capability)` resolves from `config/privileges.yaml`.
-- Each capability in the initial registry is mapped to the class declared in RFC-0101 §9.
-- `Approval.request` creates an approval request with `expiresAt`.
-- `Approval.timeout` sweeps expired requests and fails the task.
-
-### Scheduler Adapter
-
-- `systemd.compile(task)` produces a `.service` + `.timer` pair matching the template.
-- `launchd.compile(task)` produces a `plist` with `StartCalendarInterval`.
-- `cron.compile(task)` produces a crontab fragment.
-- `internal.compile(task)` registers an in-process timer (and is marked not-for-production).
-- Re-running install does not duplicate units (idempotency test).
-
-## Integration Tests
-
-### Happy Path
-
-- Submit a task while a chat session is open; close the chat; worker still completes the task.
-- Schedule a recurring task; verify it fires every N minutes under `cron` and `systemd` adapters.
-- OKF pattern bundle is produced on a successful task with deliverable.
-- OKF lesson bundle is produced on a classified failure.
-
-### Concurrency
-
-- Spin up two workers on the same host; submit 100 tasks; verify each is executed exactly once.
-- Spin up a reaper script in parallel with the workers; verify no lease is reaped while still heartbeating.
-
-### Recovery
-
-- Kill a worker mid-task with `SIGKILL`; another worker resumes the task from its last checkpoint.
-- Reboot the host (or simulate via `systemctl restart`); worker restarts; in-flight tasks recovered.
-- Fill the disk to 99 %; worker pauses new claims; verify no checkpoint corruption.
-- Block the notification channel for 1 hour; verify events buffer and flush on reconnect.
-
-### Approval Flow
-
-- Submit a `human_approval_required` task; verify the task pauses at `waiting_approval`.
-- Approve the task via operator; verify the task resumes and completes.
-- Deny the task; verify it transitions to `failed` with reason "approval denied".
-- Let an approval expire (24 h); verify it transitions to `failed` with reason "approval timeout".
-
-### Privilege Broker
-
-- Request a registered capability -> succeeds.
-- Request an unknown capability -> fails with `BrokerDeniedError`.
-- Request a registered capability with mismatched args -> fails.
-- Verify audit log contains one entry per call with the correct shape.
-
-## Failure-Mode Tests
-
-| Scenario | Expected Outcome |
-|---|---|
-| Worker killed mid-task | Lease reaper releases; next worker resumes from checkpoint. |
-| Host reboot | Supervisor restarts worker; leases reaped; checkpoints restored. |
-| Filesystem full during checkpoint | Worker pauses new claims; operator notified; no half-written checkpoint. |
-| Quota exhausted | Task transitions to `waiting_quota`; resumes after reset. |
-| Provider returns 5xx for 30 min | Tasks wait in `waiting_quota`; resume on green health probe. |
-| Clock skew between two workers | Atomic rename protects; only one heartbeat wins. |
-| Privilege registry file corrupted | Worker refuses to start; clear error pointing at schema validator. |
-| Approval request lost in transit | Task expires after 24 h; broker logs lost request. |
-| Repeated identical failure | After `maxAttempts` the task moves to `dead_letter`; operator notified. |
-| Recursive task creation (cycle) | DAG cycle detection rejects; task fails. |
-
-## Security Tests
-
-- Capability enumeration refuses unknown names.
-- Argv tampering rejected at broker.
-- Audit log cannot be rewritten by the worker (`chmod 0640`, owner `root`, group `your_app`).
-- No `shell.root`, `sudo.any`, or wildcard capabilities are reachable via the registry.
-- Agent cannot mutate `privileges.yaml` at runtime (no API exposed).
-
-## Performance / Cost
-
-- Worker steady-state CPU < 1 % on idle (verify with `pidstat -u -p <pid> 60`).
-- Heartbeat write rate < 1 KB / 30 s.
-- Inbox append throughput ≥ 1 000 tasks / s on local SSD.
-- Lease claim latency < 5 ms on local filesystem.
-
-## Acceptance Run
-
-- All 25 criteria in RFC-0101 §20 must be demonstrated.
-- Run the integration suite end-to-end against a clean `~/.pi/harness/` directory.
-- Capture the test report under `test/reports/RFC-0101-<date>.md`.
-
-## Required Tooling
-
-- `bun test` (or `node --test`) for unit + integration.
-- `tmux` or `setsid` for parallel-worker chaos.
-- `systemd-run --scope` for supervised-worker tests on Linux.
-- `logrotate --debug` for audit-log rotation tests.
-- `faketime` (or equivalent) for approval-timeout and clock-skew tests.

package/IMPLEMENTATION/RFC-0102/ACCEPTANCE_CRITERIA.md

@@ -1,33 +0,0 @@
-# Acceptance Criteria — RFC-0102 Context Engineering Pipeline
-
-## Functional
-
-- [ ] IntentAnalyzer classifies "fix the login bug" as `bug_fix`
-- [ ] IntentAnalyzer classifies "add dark mode support" as `feature`
-- [ ] IntentAnalyzer classifies "deploy to production" as `deployment`
-- [ ] IntentAnalyzer falls back to `general` for unknown input
-- [ ] WorkspaceScanner detects git branch, dirty state, modified files
-- [ ] WorkspaceScanner detects project type from package.json, go.mod, Cargo.toml
-- [ ] WorkspaceScanner detects framework from vite.config.ts, next.config.js, nuxt.config.ts
-- [ ] DependencyAnalyzer parses ESM imports: `import X from './y'`, `import { a } from 'pkg'`
-- [ ] DependencyAnalyzer parses CommonJS: `const X = require('./y')`
-- [ ] DependencyAnalyzer parses Python: `from module import x`
-- [ ] ContextDiscovery collects candidates from workspace + git diff + OKF
-- [ ] ContextEngineeringPipeline returns a valid ContextPackage
-- [ ] Policy filter denies `**/.env`, `**/*.pem`, `**/credentials/**`
-- [ ] Cache key invalidates when git branch changes
-- [ ] Cache key invalidates when AGENTS.md changes
-
-## Non-Functional
-
-- [ ] Each package compiles with `npx tsc --skipLibCheck` zero errors
-- [ ] All tests pass: `bun test packages/*/test/*.test.ts`
-- [ ] No hardcoded paths — uses configurable root
-- [ ] No secret leakage — .env files never included
-- [ ] Pipeline processes known workspace in < 2 seconds
-
-## Integration
-
-- [ ] Pipeline integrates with `@pi/context-compiler` (compileContext, loadOkfConcepts)
-- [ ] Pipeline integrates with `@pi/session-api` for historical context
-- [ ] Pipeline output compatible with provider router input format

package/IMPLEMENTATION/RFC-0102/AI_BRIEF.md

@@ -1,34 +0,0 @@
-# AI Brief — RFC-0102 Context Engineering Pipeline
-
-## What is being built
-
-An 5-package pipeline that transforms user intent into an optimal LLM input:
-
-1. **intent-analyzer** — keyword-based intent classification
-2. **workspace-scanner** — git state + project type detection
-3. **dependency-analyzer** — import/export graph builder
-4. **context-discovery** — orchestrates all stages to collect relevant files
-5. **context-engineering** — wires pipeline, builds ContextPackage, manages cache
-
-Existing `packages/context-compiler/` covers: ranking, compression, compilation, OKF loading.
-
-## Key interfaces
-
-- `Intent` — kind (bug_fix/feature/etc.), confidence, signals, originalText
-- `WorkspaceSnapshot` — root, git state, project config, env files, config files
-- `DependencyGraph` — Map<filePath, DependencyNode> + edges[]
-- `DiscoveredContext` — intent + workspace + dependencies + knowledge + files
-- `ContextPackage` — structured output sent to LLM
-
-## Integration
-
-- Pipeline reads from: filesystem, git, OKF
-- Output feeds: `compileContext()` from `@pi/context-compiler`, then to provider router
-- No new schema — uses existing context-compiler types for candidates
-- Session API (RFC-0103) provides historical context
-
-## Testing strategy
-
-- Unit: intent detection keywords, workspace detection patterns, import parsing
-- Integration: full pipeline on known workspaces
-- Mock workspace fixture for CI

package/IMPLEMENTATION/RFC-0102/FILES.md

@@ -1,73 +0,0 @@
-# Files — RFC-0102 Context Engineering Pipeline
-
-## New Packages
-
-```
-packages/
-+-- intent-analyzer/
-|   +-- src/
-|   |   +-- types.ts          # Intent, IntentKind, IntentConfidence, IntentSignal, IntentRule
-|   |   +-- analyzer.ts       # IntentAnalyzer class — keyword scoring, analyze(text): Intent
-|   |   +-- index.ts         # Public barrel
-|   +-- test/
-|   |   +-- analyzer.test.ts  # bun test — all intent kinds
-|   +-- package.json
-|   +-- tsconfig.json
-|
-+-- workspace-scanner/
-|   +-- src/
-|   |   +-- types.ts         # WorkspaceSnapshot, GitState, ProjectConfig, ScannerOptions
-|   |   +-- git.ts           # getGitState(rootPath): GitState | null via git CLI
-|   |   +-- detect.ts        # detectProject(rootPath): ProjectConfig — file-based detection
-|   |   +-- scanner.ts       # WorkspaceScanner class — orchestrates git + detect
-|   |   +-- index.ts         # Public barrel
-|   +-- test/
-|   |   +-- scanner.test.ts  # bun test — mock workspace
-|   +-- package.json
-|   +-- tsconfig.json
-|
-+-- dependency-analyzer/
-|   +-- src/
-|   |   +-- types.ts         # DependencyNode, DependencyGraph, DependencyEdge, DependencyKind
-|   |   +-- analyzer.ts       # DependencyAnalyzer class — scan + graph build
-|   |   +-- imports.ts       # parseImports(content, filePath): string[] — regex for TS/JS/Python
-|   |   +-- index.ts         # Public barrel
-|   +-- test/
-|   |   +-- analyzer.test.ts # bun test — import patterns
-|   +-- package.json
-|   +-- tsconfig.json
-|
-+-- context-discovery/
-|   +-- src/
-|   |   +-- types.ts         # DiscoveredContext, DiscoveryOptions, DiscoveryResult
-|   |   +-- discovery.ts     # ContextDiscovery class — orchestrates all stages
-|   |   +-- index.ts         # Public barrel
-|   +-- test/
-|   |   +-- discovery.test.ts # bun test — mock dependencies
-|   +-- package.json
-|   +-- tsconfig.json
-|
-+-- context-engineering/
-    +-- src/
-    |   +-- types.ts         # ContextPackage, PipelineOptions, PipelineStats
-    |   +-- pipeline.ts       # ContextEngineeringPipeline — orchestrates all 5 packages
-    |   +-- cache.ts          # ContextCache — wraps @pi/context-compiler cache
-    |   +-- index.ts          # Public barrel
-    +-- test/
-    |   +-- pipeline.test.ts  # bun test — full pipeline
-    +-- package.json
-    +-- tsconfig.json
-```
-
-## Integration (do not create new files)
-
-| Source | Import from |
-|---|---|
-| Context Compiler | `@pi/context-compiler` — compileContext, ContextCandidate, ContextPolicy |
-| OKF Loader | `@pi/context-compiler/src/okf-loader.js` — loadOkfConcepts |
-| Session API | `@pi/session-api` — getRecentFailures, getArchitectureHistory |
-
-## Files NOT Created
-
-- `packages/context-compiler/` — already exists, do not modify
-- `packages/okf-kb/` — already exists, do not modify

package/IMPLEMENTATION/RFC-0102/TASKS.md

@@ -1,75 +0,0 @@
-# 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

@@ -1,78 +0,0 @@
-# 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

@@ -1,45 +0,0 @@
-# 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

@@ -1,46 +0,0 @@
-# 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

@@ -1,121 +0,0 @@
-# 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