@pcircle/footprint 1.3.0 → 1.6.0

package/SKILL.md

@@ -1,18 +1,20 @@
 # Footprint Agent Skill
 
-> MCP server for capturing and encrypting AI conversations as verifiable records with Git timestamps.
+> MCP server for AI work history, context memory, and encrypted evidence capture.
 
 **Package:** `@pcircle/footprint` (v1.1.1)  
 **Protocol:** Model Context Protocol (MCP)  
 **License:** MIT
 
+This skill is specifically about the encrypted evidence workflow. Footprint also has separate session-history and context-memory surfaces for ongoing work continuity.
+
 ## Decision Tree: Should I Capture This?
 
 ```
 Should I capture this conversation?
 ├─ User explicitly asked → YES
 │   ├─ "save this conversation"
-│   ├─ "record this for evidence"  
+│   ├─ "record this for evidence"
 │   ├─ "capture this as evidence"
 │   └─ "I need this for legal/audit purposes"
 ├─ High-value content mentioned → SUGGEST to user
@@ -32,19 +34,22 @@ Should I capture this conversation?
 ## Specific Trigger Patterns
 
 **Immediate capture (don't ask, just do it):**
+
 - "save this conversation"
-- "record this for evidence" 
+- "record this for evidence"
 - "capture this as evidence"
 - "I need this documented"
 - "save this for legal purposes"
 
 **Suggest capture (ask user first):**
+
 - After discussing: patents, contracts, algorithms, research hypotheses, business decisions
 - When mentioned: "IP", "copyright", "legal", "audit", "proof", "compliance"
 - Milestone completions: "finished", "completed", "approved", "signed off"
 - Key decisions: "we decided", "the plan is", "going with option"
 
 **Never capture without explicit request:**
+
 - Casual conversations, personal chat, jokes
 - Debugging sessions, draft work, brainstorming
 - Test conversations, API experiments
@@ -53,13 +58,15 @@ Should I capture this conversation?
 ## Available Tools
 
 ### 1. `capture-footprint`
+
 Save a conversation as encrypted evidence.
 
 **Input Parameters:**
+
 ```json
 {
   "conversationId": "api-auth-decision-2026-01-28",
-  "llmProvider": "Claude Sonnet 4.5", 
+  "llmProvider": "Claude Sonnet 4.5",
   "content": "Human: We need to decide on the OAuth implementation...\nAssistant: I recommend using PKCE flow...\nHuman: Approved, let's go with that approach.",
   "messageCount": 15,
   "tags": "api,oauth,security,decision,approved"
@@ -67,11 +74,12 @@ Save a conversation as encrypted evidence.
 ```
 
 **Expected Output (text):**
+
 ```
 ✅ Evidence captured successfully
 - Evidence ID: `550e8400-e29b-41d4-a716-446655440000`
 - Conversation ID: `api-auth-decision-2026-01-28`
-- Messages: 15 
+- Messages: 15
 - Tags: api,oauth,security,decision,approved
 - Git hash: `a1b2c3d4e5f6789...`
 - Created: 2026-01-28T14:30:45Z
@@ -80,11 +88,12 @@ Keep this Evidence ID safe for future reference.
 ```
 
 **Expected Output (structuredContent):**
+
 ```json
 {
   "type": "evidence_created",
   "evidenceId": "550e8400-e29b-41d4-a716-446655440000",
-  "conversationId": "api-auth-decision-2026-01-28", 
+  "conversationId": "api-auth-decision-2026-01-28",
   "messageCount": 15,
   "tags": ["api", "oauth", "security", "decision", "approved"],
   "gitHash": "a1b2c3d4e5f6789...",
@@ -94,9 +103,11 @@ Keep this Evidence ID safe for future reference.
 ```
 
 ### 2. `list-footprints`
+
 List all captured evidence (metadata only).
 
 **Input Parameters:**
+
 ```json
 {
   "limit": 10,
@@ -105,15 +116,17 @@ List all captured evidence (metadata only).
 ```
 
 **Expected Output (text):**
+
 ```
 📋 Evidence Archive (10 most recent)
 1. api-auth-decision-2026-01-28 | 15 msgs | api,oauth,security
-2. patent-algorithm-2026-01-27 | 32 msgs | ip,patent,algorithm  
+2. patent-algorithm-2026-01-27 | 32 msgs | ip,patent,algorithm
 3. contract-review-2026-01-26 | 8 msgs | legal,contract
 ...
 ```
 
 **Expected Output (structuredContent):**
+
 ```json
 {
   "type": "evidence_list",
@@ -131,9 +144,11 @@ List all captured evidence (metadata only).
 ```
 
 ### 3. `get-footprint`
+
 Retrieve and decrypt specific evidence.
 
 **Input Parameters:**
+
 ```json
 {
   "id": "550e8400-e29b-41d4-a716-446655440000"
@@ -141,6 +156,7 @@ Retrieve and decrypt specific evidence.
 ```
 
 **Expected Output (text):**
+
 ```
 📄 Evidence Retrieved
 - ID: 550e8400-e29b-41d4-a716-446655440000
@@ -154,9 +170,11 @@ Assistant: I recommend using PKCE flow...
 ```
 
 ### 4. `search-footprints`
+
 Find evidence by content or tags.
 
 **Input Parameters:**
+
 ```json
 {
   "query": "OAuth OR PKCE OR authentication",
@@ -166,9 +184,11 @@ Find evidence by content or tags.
 ```
 
 ### 5. `export-footprints`
+
 Export evidence as encrypted archive.
 
 **Input Parameters:**
+
 ```json
 {
   "id": "550e8400-e29b-41d4-a716-446655440000",
@@ -177,6 +197,7 @@ Export evidence as encrypted archive.
 ```
 
 **Expected Output (structuredContent):**
+
 ```json
 {
   "type": "evidence_export",
@@ -188,9 +209,11 @@ Export evidence as encrypted archive.
 ```
 
 ### 6. `verify-footprint`
+
 Verify evidence integrity (checksum + Git timestamp).
 
 **Input Parameters:**
+
 ```json
 {
   "id": "550e8400-e29b-41d4-a716-446655440000"
@@ -198,6 +221,7 @@ Verify evidence integrity (checksum + Git timestamp).
 ```
 
 **Expected Output (text):**
+
 ```
 🔐 Evidence Verification Report
 - ID: 550e8400-e29b-41d4-a716-446655440000
@@ -208,6 +232,7 @@ Verify evidence integrity (checksum + Git timestamp).
 ```
 
 **Expected Output (structuredContent):**
+
 ```json
 {
   "type": "verification_result",
@@ -223,21 +248,26 @@ Verify evidence integrity (checksum + Git timestamp).
 ## Best Practices
 
 ### Naming conversationId
+
 **Format:** `{topic-type}-{descriptive-name}-{YYYY-MM-DD}`
 
 **Good examples:**
+
 - `api-auth-decision-2026-01-28`
 - `patent-ml-algorithm-2026-01-27`
 - `contract-vendor-negotiation-2026-01-26`
 - `milestone-mvp-completion-2026-01-25`
 
 **Avoid:**
+
 - `conversation-1` (not descriptive)
-- `important-chat` (too vague)  
+- `important-chat` (too vague)
 - `chat-2026-01-28` (missing context)
 
 ### Choosing Tags
+
 **Common patterns:**
+
 - **Type**: `decision`, `milestone`, `research`, `review`, `approval`
 - **Domain**: `api`, `ui`, `database`, `security`, `legal`, `business`
 - **Status**: `draft`, `finalized`, `approved`, `rejected`
@@ -245,12 +275,14 @@ Verify evidence integrity (checksum + Git timestamp).
 - **Legal**: `contract`, `agreement`, `compliance`, `audit`
 
 **Tag Guidelines:**
+
 - Use 3-6 tags maximum
 - Prefer specific over general (`oauth` not just `auth`)
 - Include project/product names if relevant
 - Always include content type (`decision`, `research`, etc.)
 
 ### When to Use Each Tool
+
 - **capture-footprint**: Primary tool for saving conversations
 - **list-footprints**: Browse/overview existing evidence
 - **search-footprints**: Find specific content across evidence
@@ -261,23 +293,27 @@ Verify evidence integrity (checksum + Git timestamp).
 ## Token-Efficient Agent Responses
 
 **After capturing evidence (keep it brief):**
+
 ```
-✅ Evidence saved as `{conversationId}` 
+✅ Evidence saved as `{conversationId}`
 ID: `{first-8-chars-of-id}`...
 Tags: {tags}
 ```
 
 **When suggesting capture:**
+
 ```
 💡 This looks like valuable evidence (contains {trigger}). Save it?
 ```
 
 **When declining to capture:**
+
 ```
 ℹ️ Skipping evidence capture (casual conversation)
 ```
 
 **For retrieval:**
+
 ```
 📄 Found: {conversationId} ({messageCount} messages)
 [Show relevant excerpt or summary]
@@ -285,25 +321,27 @@ Tags: {tags}
 
 ## Error Handling with Recovery Actions
 
-| Error | Likely Cause | Recovery Action |
-|-------|--------------|-----------------|
-| "Password required" | FOOTPRINT_PASSWORD not set | 1. Check env config<br>2. Restart MCP server<br>3. Verify password in env |
-| "Evidence not found" | Invalid/wrong ID | 1. Use `list-footprints` to find correct ID<br>2. Search by conversationId<br>3. Check if user meant different evidence |
-| "Decryption failed" | Password changed/wrong | 1. Verify current password matches<br>2. Check if evidence pre-dates password change<br>3. Try with backup password if available |
-| "Database error" | DB path/permissions issues | 1. Check FOOTPRINT_DB_PATH exists<br>2. Verify file permissions<br>3. Create directory if missing |
-| "Git repository error" | Git not initialized | 1. Initialize git in evidence directory<br>2. Set git user.name/user.email<br>3. Make initial commit |
-| "Capture timeout" | Large conversation size | 1. Split into smaller chunks<br>2. Reduce messageCount<br>3. Compress content before capture |
+| Error                  | Likely Cause                 | Recovery Action                                                                                                                  |
+| ---------------------- | ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
+| "Password required"    | FOOTPRINT_PASSPHRASE not set | 1. Check env config<br>2. Restart MCP server<br>3. Verify passphrase in env                                                      |
+| "Evidence not found"   | Invalid/wrong ID             | 1. Use `list-footprints` to find correct ID<br>2. Search by conversationId<br>3. Check if user meant different evidence          |
+| "Decryption failed"    | Password changed/wrong       | 1. Verify current password matches<br>2. Check if evidence pre-dates password change<br>3. Try with backup password if available |
+| "Database error"       | DB path/permissions issues   | 1. Check FOOTPRINT_DATA_DIR exists<br>2. Verify file permissions<br>3. Create directory if missing                               |
+| "Git repository error" | Git not initialized          | 1. Initialize git in evidence directory<br>2. Set git user.name/user.email<br>3. Make initial commit                             |
+| "Capture timeout"      | Large conversation size      | 1. Split into smaller chunks<br>2. Reduce messageCount<br>3. Compress content before capture                                     |
 
 **Agent Recovery Protocol:**
+
 1. **Detect error** from tool response
 2. **Identify cause** from error message
-3. **Apply recovery action** from table above  
+3. **Apply recovery action** from table above
 4. **Retry operation** if recovery successful
 5. **Escalate to user** only if recovery fails
 
 ## Workflow Examples
 
 ### 1. User Explicit Request
+
 ```
 User: "Save this conversation about the API design"
 
@@ -314,7 +352,8 @@ Agent:
 4. Report success with Evidence ID
 ```
 
-### 2. High-Value Content Detection  
+### 2. High-Value Content Detection
+
 ```
 User: "We've decided to patent this algorithm approach."
 
@@ -325,6 +364,7 @@ Agent:
 ```
 
 ### 3. Evidence Retrieval
+
 ```
 User: "Find the conversation about OAuth implementation"
 
@@ -335,10 +375,11 @@ Agent:
 ```
 
 ### 4. Legal Export
+
 ```
 User: "Export the patent evidence for filing"
 
-Agent: 
+Agent:
 1. 🔍 Help identify relevant evidence (search by "patent" tag)
 2. 📦 Export each evidence as encrypted ZIP
 3. ✅ Provide files with verification instructions
@@ -347,15 +388,16 @@ Agent:
 
 ## Security & Verification
 
-- **Password**: Set via `FOOTPRINT_PASSWORD` env var (never ask user in chat)
-- **Encryption**: XChaCha20-Poly1305 (256-bit) with Argon2id key derivation  
+- **Password**: Set via `FOOTPRINT_PASSPHRASE` env var (never ask user in chat)
+- **Encryption**: XChaCha20-Poly1305 (256-bit) with Argon2id key derivation
 - **Git Timestamps**: Cryptographic proof of creation time
 - **SHA-256 Checksums**: Detect any content tampering
 - **Evidence Chain**: Each capture creates immutable Git commit
 - **Storage**: Local SQLite with encrypted BLOBs (no cloud, no tracking)
 
 **For legal proceedings:**
-1. Export evidence with `export-evidence` 
+
+1. Export evidence with `export-evidence`
 2. Verify Git hash against repository
 3. Check SHA-256 checksum matches
 4. Git log shows creation timestamp
@@ -375,13 +417,14 @@ npx @pcircle/footprint
 
 **Claude Desktop config location:**
 
-| Platform | Config Path |
-|----------|-------------|
-| macOS | `~/Library/Application Support/Claude/claude_desktop_config.json` |
-| Linux | `~/.config/Claude/claude_desktop_config.json` |
-| Windows | `%APPDATA%\Claude\claude_desktop_config.json` |
+| Platform | Config Path                                                       |
+| -------- | ----------------------------------------------------------------- |
+| macOS    | `~/Library/Application Support/Claude/claude_desktop_config.json` |
+| Linux    | `~/.config/Claude/claude_desktop_config.json`                     |
+| Windows  | `%APPDATA%\Claude\claude_desktop_config.json`                     |
 
 **Config content:**
+
 ```json
 {
   "mcpServers": {
@@ -389,8 +432,8 @@ npx @pcircle/footprint
       "command": "npx",
       "args": ["@pcircle/footprint"],
       "env": {
-        "FOOTPRINT_DB_PATH": "/path/to/evidence.db",
-        "FOOTPRINT_PASSWORD": "your-secure-password-here"
+        "FOOTPRINT_DATA_DIR": "/path/to/data",
+        "FOOTPRINT_PASSPHRASE": "your-secure-password-here"
       }
     }
   }
@@ -398,8 +441,9 @@ npx @pcircle/footprint
 ```
 
 **Environment Variables:**
-- `FOOTPRINT_PASSWORD` (required): Encryption passphrase
-- `FOOTPRINT_DB_PATH` (optional): Path to SQLite database (default: `./evidence.db` in current directory)
+
+- `FOOTPRINT_PASSPHRASE` (required): Encryption passphrase
+- `FOOTPRINT_DATA_DIR` (optional): Directory for data storage (default: `~/.footprint`)
 
 ## Performance Notes
 
@@ -409,4 +453,4 @@ npx @pcircle/footprint
 - **Search speed**: Sub-second for <1000 evidence records
 - **Export time**: ~5-15 seconds depending on content size
 
-Large conversations (>100 messages) may take longer to encrypt and commit.
+Large conversations (>100 messages) may take longer to encrypt and commit.

package/bin/footprint.js

@@ -0,0 +1,16 @@
+#!/usr/bin/env node
+import { existsSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+const currentDir = path.dirname(fileURLToPath(import.meta.url));
+const distEntry = path.resolve(currentDir, "../dist/src/cli/index.js");
+
+if (!existsSync(distEntry)) {
+  process.stderr.write(
+    'Footprint CLI is not built yet. Run "pnpm --dir packages/mcp-server build" first.\n',
+  );
+  process.exit(1);
+}
+
+await import(pathToFileURL(distEntry).href);

package/dist/src/adapters/claude.d.ts

@@ -0,0 +1,2 @@
+export declare const claudeAdapter: import("./types.js").HostAdapter;
+//# sourceMappingURL=claude.d.ts.map

package/dist/src/adapters/claude.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"claude.d.ts","sourceRoot":"","sources":["../../../src/adapters/claude.ts"],"names":[],"mappings":"AAEA,eAAO,MAAM,aAAa,kCAIxB,CAAC"}

package/dist/src/adapters/claude.js

@@ -0,0 +1,7 @@
+import { createStructuredPrefixAdapter } from "./structured-prefix.js";
+export const claudeAdapter = createStructuredPrefixAdapter({
+    host: "claude",
+    name: "claude-adapter",
+    prefix: "FOOTPRINT_CLAUDE_EVENT ",
+});
+//# sourceMappingURL=claude.js.map

package/dist/src/adapters/claude.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"claude.js","sourceRoot":"","sources":["../../../src/adapters/claude.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,6BAA6B,EAAE,MAAM,wBAAwB,CAAC;AAEvE,MAAM,CAAC,MAAM,aAAa,GAAG,6BAA6B,CAAC;IACzD,IAAI,EAAE,QAAQ;IACd,IAAI,EAAE,gBAAgB;IACtB,MAAM,EAAE,yBAAyB;CAClC,CAAC,CAAC"}

package/dist/src/adapters/codex.d.ts

@@ -0,0 +1,2 @@
+export declare const codexAdapter: import("./types.js").HostAdapter;
+//# sourceMappingURL=codex.d.ts.map

package/dist/src/adapters/codex.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"codex.d.ts","sourceRoot":"","sources":["../../../src/adapters/codex.ts"],"names":[],"mappings":"AAEA,eAAO,MAAM,YAAY,kCAIvB,CAAC"}

package/dist/src/adapters/codex.js

@@ -0,0 +1,7 @@
+import { createStructuredPrefixAdapter } from "./structured-prefix.js";
+export const codexAdapter = createStructuredPrefixAdapter({
+    host: "codex",
+    name: "codex-adapter",
+    prefix: "FOOTPRINT_CODEX_EVENT ",
+});
+//# sourceMappingURL=codex.js.map

package/dist/src/adapters/codex.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"codex.js","sourceRoot":"","sources":["../../../src/adapters/codex.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,6BAA6B,EAAE,MAAM,wBAAwB,CAAC;AAEvE,MAAM,CAAC,MAAM,YAAY,GAAG,6BAA6B,CAAC;IACxD,IAAI,EAAE,OAAO;IACb,IAAI,EAAE,eAAe;IACrB,MAAM,EAAE,wBAAwB;CACjC,CAAC,CAAC"}

package/dist/src/adapters/gemini.d.ts

@@ -0,0 +1,2 @@
+export declare const geminiAdapter: import("./types.js").HostAdapter;
+//# sourceMappingURL=gemini.d.ts.map

package/dist/src/adapters/gemini.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gemini.d.ts","sourceRoot":"","sources":["../../../src/adapters/gemini.ts"],"names":[],"mappings":"AAEA,eAAO,MAAM,aAAa,kCAIxB,CAAC"}

package/dist/src/adapters/gemini.js

@@ -0,0 +1,7 @@
+import { createStructuredPrefixAdapter } from "./structured-prefix.js";
+export const geminiAdapter = createStructuredPrefixAdapter({
+    host: "gemini",
+    name: "gemini-adapter",
+    prefix: "FOOTPRINT_GEMINI_EVENT ",
+});
+//# sourceMappingURL=gemini.js.map

package/dist/src/adapters/gemini.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"gemini.js","sourceRoot":"","sources":["../../../src/adapters/gemini.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,6BAA6B,EAAE,MAAM,wBAAwB,CAAC;AAEvE,MAAM,CAAC,MAAM,aAAa,GAAG,6BAA6B,CAAC;IACzD,IAAI,EAAE,QAAQ;IACd,IAAI,EAAE,gBAAgB;IACtB,MAAM,EAAE,yBAAyB;CAClC,CAAC,CAAC"}

package/dist/src/adapters/index.d.ts

@@ -0,0 +1,5 @@
+import type { HostAdapter } from "./types.js";
+import type { SessionHost } from "../lib/storage/index.js";
+export type { AdapterContext, AdapterEventEnvelope, AdapterParseResult, HostAdapter, } from "./types.js";
+export declare function getHostAdapter(host: SessionHost): HostAdapter | null;
+//# sourceMappingURL=index.d.ts.map

package/dist/src/adapters/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/adapters/index.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAC9C,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AAQ3D,YAAY,EACV,cAAc,EACd,oBAAoB,EACpB,kBAAkB,EAClB,WAAW,GACZ,MAAM,YAAY,CAAC;AAEpB,wBAAgB,cAAc,CAAC,IAAI,EAAE,WAAW,GAAG,WAAW,GAAG,IAAI,CAEpE"}

package/dist/src/adapters/index.js

@@ -0,0 +1,12 @@
+import { claudeAdapter } from "./claude.js";
+import { codexAdapter } from "./codex.js";
+import { geminiAdapter } from "./gemini.js";
+const adapters = new Map([
+    ["claude", claudeAdapter],
+    ["gemini", geminiAdapter],
+    ["codex", codexAdapter],
+]);
+export function getHostAdapter(host) {
+    return adapters.get(host) ?? null;
+}
+//# sourceMappingURL=index.js.map

package/dist/src/adapters/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/adapters/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAC1C,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAI5C,MAAM,QAAQ,GAAG,IAAI,GAAG,CAA2B;IACjD,CAAC,QAAQ,EAAE,aAAa,CAAC;IACzB,CAAC,QAAQ,EAAE,aAAa,CAAC;IACzB,CAAC,OAAO,EAAE,YAAY,CAAC;CACxB,CAAC,CAAC;AASH,MAAM,UAAU,cAAc,CAAC,IAAiB;IAC9C,OAAO,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,IAAI,CAAC;AACpC,CAAC"}

package/dist/src/adapters/structured-prefix.d.ts

@@ -0,0 +1,10 @@
+import type { HostAdapter } from "./types.js";
+import type { SessionHost } from "../lib/storage/index.js";
+interface StructuredPrefixAdapterConfig {
+    host: SessionHost;
+    name: string;
+    prefix: string;
+}
+export declare function createStructuredPrefixAdapter(config: StructuredPrefixAdapterConfig): HostAdapter;
+export {};
+//# sourceMappingURL=structured-prefix.d.ts.map

package/dist/src/adapters/structured-prefix.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"structured-prefix.d.ts","sourceRoot":"","sources":["../../../src/adapters/structured-prefix.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAGV,WAAW,EACZ,MAAM,YAAY,CAAC;AACpB,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AAE3D,UAAU,6BAA6B;IACrC,IAAI,EAAE,WAAW,CAAC;IAClB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;CAChB;AAuBD,wBAAgB,6BAA6B,CAC3C,MAAM,EAAE,6BAA6B,GACpC,WAAW,CA2Cb"}

package/dist/src/adapters/structured-prefix.js

@@ -0,0 +1,59 @@
+function parseEnvelope(line, prefix) {
+    if (!line.startsWith(prefix)) {
+        return null;
+    }
+    const json = line.slice(prefix.length).trim();
+    if (!json) {
+        return null;
+    }
+    const parsed = JSON.parse(json);
+    if (!parsed.eventType) {
+        return null;
+    }
+    return parsed;
+}
+export function createStructuredPrefixAdapter(config) {
+    return {
+        host: config.host,
+        name: config.name,
+        parseLine(line, stream, _context) {
+            try {
+                const envelope = parseEnvelope(line, config.prefix);
+                if (!envelope) {
+                    return null;
+                }
+                return {
+                    handled: true,
+                    suppressTranscript: true,
+                    events: [
+                        {
+                            ...envelope,
+                            payload: {
+                                ...(envelope.payload ?? {}),
+                                stream,
+                            },
+                        },
+                    ],
+                };
+            }
+            catch {
+                return {
+                    handled: true,
+                    suppressTranscript: false,
+                    events: [
+                        {
+                            eventType: "error.observed",
+                            summary: `${config.name} failed to parse host event`,
+                            payload: {
+                                line,
+                                stream,
+                            },
+                            status: "parse-error",
+                        },
+                    ],
+                };
+            }
+        },
+    };
+}
+//# sourceMappingURL=structured-prefix.js.map

package/dist/src/adapters/structured-prefix.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"structured-prefix.js","sourceRoot":"","sources":["../../../src/adapters/structured-prefix.ts"],"names":[],"mappings":"AAaA,SAAS,aAAa,CACpB,IAAY,EACZ,MAAc;IAEd,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,MAAM,CAAC,EAAE,CAAC;QAC7B,OAAO,IAAI,CAAC;IACd,CAAC;IAED,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,CAAC;IAC9C,IAAI,CAAC,IAAI,EAAE,CAAC;QACV,OAAO,IAAI,CAAC;IACd,CAAC;IAED,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAyB,CAAC;IACxD,IAAI,CAAC,MAAM,CAAC,SAAS,EAAE,CAAC;QACtB,OAAO,IAAI,CAAC;IACd,CAAC;IAED,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,MAAM,UAAU,6BAA6B,CAC3C,MAAqC;IAErC,OAAO;QACL,IAAI,EAAE,MAAM,CAAC,IAAI;QACjB,IAAI,EAAE,MAAM,CAAC,IAAI;QACjB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ;YAC9B,IAAI,CAAC;gBACH,MAAM,QAAQ,GAAG,aAAa,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC;gBACpD,IAAI,CAAC,QAAQ,EAAE,CAAC;oBACd,OAAO,IAAI,CAAC;gBACd,CAAC;gBAED,OAAO;oBACL,OAAO,EAAE,IAAI;oBACb,kBAAkB,EAAE,IAAI;oBACxB,MAAM,EAAE;wBACN;4BACE,GAAG,QAAQ;4BACX,OAAO,EAAE;gCACP,GAAG,CAAC,QAAQ,CAAC,OAAO,IAAI,EAAE,CAAC;gCAC3B,MAAM;6BACP;yBACF;qBACF;iBACF,CAAC;YACJ,CAAC;YAAC,MAAM,CAAC;gBACP,OAAO;oBACL,OAAO,EAAE,IAAI;oBACb,kBAAkB,EAAE,KAAK;oBACzB,MAAM,EAAE;wBACN;4BACE,SAAS,EAAE,gBAAgB;4BAC3B,OAAO,EAAE,GAAG,MAAM,CAAC,IAAI,6BAA6B;4BACpD,OAAO,EAAE;gCACP,IAAI;gCACJ,MAAM;6BACP;4BACD,MAAM,EAAE,aAAa;yBACtB;qBACF;iBACF,CAAC;YACJ,CAAC;QACH,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/src/adapters/types.d.ts

@@ -0,0 +1,32 @@
+import type { SessionHost, SessionStatus } from "../lib/storage/index.js";
+export interface AdapterContext {
+    host: SessionHost;
+    cwd: string;
+    args: string[];
+}
+export interface AdapterEventEnvelope {
+    eventType: string;
+    eventSubType?: string | null;
+    summary?: string | null;
+    payload?: Record<string, unknown> | null;
+    status?: string | null;
+    startedAt?: string | null;
+    endedAt?: string | null;
+    relatedMessageRole?: "user" | "assistant" | "system" | null;
+}
+export interface AdapterParseResult {
+    handled: boolean;
+    suppressTranscript?: boolean;
+    events?: AdapterEventEnvelope[];
+}
+export interface HostAdapter {
+    host: SessionHost;
+    name: string;
+    parseLine(line: string, stream: "stdout" | "stderr", context: AdapterContext): AdapterParseResult | null;
+    onSessionStart?(context: AdapterContext): AdapterEventEnvelope[];
+    onSessionEnd?(context: AdapterContext, result: {
+        exitCode: number;
+        status: SessionStatus;
+    }): AdapterEventEnvelope[];
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/src/adapters/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/adapters/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAC;AAE1E,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,WAAW,CAAC;IAClB,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,EAAE,CAAC;CAChB;AAED,MAAM,WAAW,oBAAoB;IACnC,SAAS,EAAE,MAAM,CAAC;IAClB,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IACzC,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,kBAAkB,CAAC,EAAE,MAAM,GAAG,WAAW,GAAG,QAAQ,GAAG,IAAI,CAAC;CAC7D;AAED,MAAM,WAAW,kBAAkB;IACjC,OAAO,EAAE,OAAO,CAAC;IACjB,kBAAkB,CAAC,EAAE,OAAO,CAAC;IAC7B,MAAM,CAAC,EAAE,oBAAoB,EAAE,CAAC;CACjC;AAED,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,WAAW,CAAC;IAClB,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,CACP,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,QAAQ,GAAG,QAAQ,EAC3B,OAAO,EAAE,cAAc,GACtB,kBAAkB,GAAG,IAAI,CAAC;IAC7B,cAAc,CAAC,CAAC,OAAO,EAAE,cAAc,GAAG,oBAAoB,EAAE,CAAC;IACjE,YAAY,CAAC,CACX,OAAO,EAAE,cAAc,EACvB,MAAM,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,aAAa,CAAA;KAAE,GAClD,oBAAoB,EAAE,CAAC;CAC3B"}

package/dist/src/adapters/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/src/adapters/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/adapters/types.ts"],"names":[],"mappings":""}

package/dist/src/analyzers/content-analyzer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"content-analyzer.d.ts","sourceRoot":"","sources":["../../../src/analyzers/content-analyzer.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,MAAM,WAAW,cAAc;IAC7B,aAAa,EAAE,OAAO,CAAC;IACvB,MAAM,EAAE,MAAM,CAAC;IACf,aAAa,EAAE,MAAM,EAAE,CAAC;IACxB,uBAAuB,EAAE,MAAM,CAAC;IAChC,UAAU,EAAE,MAAM,CAAC;IACnB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAkLD;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,cAAc,CAuB9D"}
+{"version":3,"file":"content-analyzer.d.ts","sourceRoot":"","sources":["../../../src/analyzers/content-analyzer.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,MAAM,WAAW,cAAc;IAC7B,aAAa,EAAE,OAAO,CAAC;IACvB,MAAM,EAAE,MAAM,CAAC;IACf,aAAa,EAAE,MAAM,EAAE,CAAC;IACxB,uBAAuB,EAAE,MAAM,CAAC;IAChC,UAAU,EAAE,MAAM,CAAC;IACnB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAsMD;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,cAAc,CAwB9D"}