@oh-my-pi/pi-coding-agent 10.6.1 → 11.0.0

package/docs/session.md

@@ -5,10 +5,12 @@ Sessions are stored as JSONL (JSON Lines) files. Each line is a JSON object with
 ## File Location
 
 ```
-~/.omp/agent/sessions/--<path>--/<timestamp>_<uuid>.jsonl
+~/.omp/agent/sessions/--<cwd>--/<timestamp>_<sessionId>.jsonl
 ```
 
-Where `<path>` is the working directory with `/` replaced by `-`.
+Default base directory comes from `getAgentDir()` (overridable via `PI_CODING_AGENT_DIR`).
+`<cwd>` is the working directory with the leading slash removed and `/`, `\`, `:` replaced by `-`.
+`<timestamp>` is ISO-8601 with `:`/`.` replaced by `-`. `sessionId` is a snowflake hex string.
 
 ## Session Version
 
@@ -16,14 +18,16 @@ Sessions have a version field in the header:
 
 - **Version 1**: Linear entry sequence (legacy, auto-migrated on load)
 - **Version 2**: Tree structure with `id`/`parentId` linking
+- **Version 3**: Renamed legacy `hookMessage` role to `custom`
 
-Existing v1 sessions are automatically migrated to v2 when loaded.
+Existing sessions are automatically migrated to the latest version when loaded.
 
 ## Type Definitions
 
-- [`src/core/session-manager.ts`](../src/core/session-manager.ts) - Session entry types
-- [`packages/agent/src/types.ts`](../../agent/src/types.ts) - `AgentMessage`, `Attachment`, `ThinkingLevel`
-- [`packages/ai/src/types.ts`](../../ai/src/types.ts) - `UserMessage`, `AssistantMessage`, `ToolResultMessage`, `Usage`, `ToolCall`
+- [`src/session/session-manager.ts`](../src/session/session-manager.ts) - Session entry types and `SessionManager`
+- [`src/session/messages.ts`](../src/session/messages.ts) - Custom message roles and LLM conversion
+- [`packages/agent/src/types.ts`](../../agent/src/types.ts) - `AgentMessage`, `ThinkingLevel`
+- [`packages/ai/src/types.ts`](../../ai/src/types.ts) - `Message`, content blocks, `Usage`, `ToolCall`
 
 ## Entry Base
 
@@ -32,7 +36,7 @@ All entries (except `SessionHeader`) extend `SessionEntryBase`:
 ```typescript
 interface SessionEntryBase {
 	type: string;
-	id: string; // 8-char hex ID
+	id: string; // Short snowflake suffix (8 hex chars)
 	parentId: string | null; // Parent entry ID (null for first entry)
 	timestamp: string; // ISO timestamp
 }
@@ -42,28 +46,39 @@ interface SessionEntryBase {
 
 ### SessionHeader
 
-First line of the file. Metadata only, not part of the tree (no `id`/`parentId`).
+First line of the file. Metadata only, not part of the tree (no `id`/`parentId`). `version` is absent in v1 sessions.
 
 ```json
-{ "type": "session", "version": 2, "id": "uuid", "timestamp": "2024-12-03T14:00:00.000Z", "cwd": "/path/to/project" }
+{
+	"type": "session",
+	"version": 3,
+	"id": "a1b2c3d4e5f60001",
+	"timestamp": "2024-12-03T14:00:00.000Z",
+	"cwd": "/path/to/project",
+	"title": "Optional title"
+}
 ```
 
-For sessions with a parent (created via `/branch` or `newSession({ parentSession })`):
+For sessions with a parent (created via `/branch`, `newSession({ parentSession })`, or fork operations):
 
 ```json
 {
 	"type": "session",
-	"version": 2,
-	"id": "uuid",
+	"version": 3,
+	"id": "a1b2c3d4e5f60001",
 	"timestamp": "2024-12-03T14:00:00.000Z",
 	"cwd": "/path/to/project",
 	"parentSession": "/path/to/original/session.jsonl"
 }
 ```
 
+`parentSession` is an opaque string used for lineage tracking (typically a session file path).
+
 ### SessionMessageEntry
 
-A message in the conversation. The `message` field contains an `AgentMessage`.
+A message in the conversation. The `message` field contains an `AgentMessage`,
+including base LLM messages plus coding-agent custom roles (bash/python execution,
+custom/legacy `hookMessage` messages from v2 sessions, file mentions, etc.).
 
 ```json
 {"type":"message","id":"a1b2c3d4","parentId":"prev1234","timestamp":"2024-12-03T14:00:01.000Z","message":{"role":"user","content":"Hello"}}
@@ -73,7 +88,7 @@ A message in the conversation. The `message` field contains an `AgentMessage`.
 
 ### ModelChangeEntry
 
-Emitted when the user switches models mid-session.
+Emitted when the user switches models mid-session. `model` is stored as `provider/modelId`.
 
 ```json
 {
@@ -81,8 +96,8 @@ Emitted when the user switches models mid-session.
 	"id": "d4e5f6g7",
 	"parentId": "c3d4e5f6",
 	"timestamp": "2024-12-03T14:05:00.000Z",
-	"provider": "openai",
-	"modelId": "gpt-4o"
+	"model": "openai/gpt-4o",
+	"role": "default"
 }
 ```
 
@@ -100,6 +115,8 @@ Emitted when the user changes the thinking/reasoning level.
 }
 ```
 
+`thinkingLevel` matches `ThinkingLevel` from `packages/agent` (e.g., `off`, `minimal`, `low`, `medium`, `high`, `xhigh`).
+
 ### CompactionEntry
 
 Created when context is compacted. Stores a summary of earlier messages.
@@ -111,19 +128,23 @@ Created when context is compacted. Stores a summary of earlier messages.
 	"parentId": "e5f6g7h8",
 	"timestamp": "2024-12-03T14:10:00.000Z",
 	"summary": "User discussed X, Y, Z...",
+	"shortSummary": "Quick recap...",
 	"firstKeptEntryId": "c3d4e5f6",
-	"tokensBefore": 50000
+	"tokensBefore": 50000,
+	"fromExtension": false
 }
 ```
 
 Optional fields:
 
-- `details`: Compaction-implementation specific data (e.g., file operations for default implementation, or custom data for custom hook implementations)
-- `fromHook`: `true` if generated by a hook, `false`/`undefined` if omp-generated
+- `details`: Compaction-implementation specific data (extension data, version markers, etc.)
+- `shortSummary`: Short-form summary for UI contexts
+- `preserveData`: Hook/extension data to persist across compaction
+- `fromExtension`: `true` if generated by an extension, `false`/`undefined` if pi-generated
 
 ### BranchSummaryEntry
 
-Created when switching branches via `/tree` with an LLM generated summary of the left branch up to the common ancestor. Captures context from the abandoned path.
+Created when switching branches with an LLM-generated summary of the abandoned path. Captures context from the previous branch.
 
 ```json
 {
@@ -136,14 +157,16 @@ Created when switching branches via `/tree` with an LLM generated summary of the
 }
 ```
 
+`fromId` is the branch point entry id; when branching from the root it is `"root"`.
+
 Optional fields:
 
-- `details`: File tracking data (`{ readFiles: string[], modifiedFiles: string[] }`) for default implementation, arbitrary for custom implementation
-- `fromHook`: `true` if generated by a hook
+- `details`: Extension-specific data (not sent to LLM)
+- `fromExtension`: `true` if generated by an extension
 
 ### CustomEntry
 
-Hook state persistence. Does NOT participate in LLM context.
+Extension state persistence. Does NOT participate in LLM context.
 
 ```json
 {
@@ -151,16 +174,16 @@ Hook state persistence. Does NOT participate in LLM context.
 	"id": "h8i9j0k1",
 	"parentId": "g7h8i9j0",
 	"timestamp": "2024-12-03T14:20:00.000Z",
-	"customType": "my-hook",
+	"customType": "my-extension",
 	"data": { "count": 42 }
 }
 ```
 
-Use `customType` to identify your hook's entries on reload.
+Use `customType` to identify your extension's entries on reload.
 
 ### CustomMessageEntry
 
-Hook-injected messages that DO participate in LLM context.
+Extension-injected messages that DO participate in LLM context.
 
 ```json
 {
@@ -168,7 +191,7 @@ Hook-injected messages that DO participate in LLM context.
 	"id": "i9j0k1l2",
 	"parentId": "h8i9j0k1",
 	"timestamp": "2024-12-03T14:25:00.000Z",
-	"customType": "my-hook",
+	"customType": "my-extension",
 	"content": "Injected context...",
 	"display": true
 }
@@ -177,8 +200,8 @@ Hook-injected messages that DO participate in LLM context.
 Fields:
 
 - `content`: String or `(TextContent | ImageContent)[]` (same as UserMessage)
-- `display`: `true` = show in TUI with purple styling, `false` = hidden
-- `details`: Optional hook-specific metadata (not sent to LLM)
+- `display`: `true` = show in TUI with distinct styling, `false` = hidden
+- `details`: Optional extension-specific metadata (not sent to LLM)
 
 ### LabelEntry
 
@@ -197,6 +220,37 @@ User-defined bookmark/marker on an entry.
 
 Set `label` to `undefined` to clear a label.
 
+### TtsrInjectionEntry
+
+Tracks which time-traveling stream rules were injected during the session.
+
+```json
+{
+	"type": "ttsr_injection",
+	"id": "k1l2m3n4",
+	"parentId": "j0k1l2m3",
+	"timestamp": "2024-12-03T14:31:00.000Z",
+	"injectedRules": ["rule-a", "rule-b"]
+}
+```
+
+### SessionInitEntry
+
+Captures initial context for subagent sessions (debugging/replay). Not used in LLM context building.
+
+```json
+{
+	"type": "session_init",
+	"id": "l2m3n4o5",
+	"parentId": "k1l2m3n4",
+	"timestamp": "2024-12-03T14:32:00.000Z",
+	"systemPrompt": "...",
+	"task": "Initial task...",
+	"tools": ["bash", "read"],
+	"outputSchema": { "type": "object" }
+}
+```
+
 ## Tree Structure
 
 Entries form a tree:
@@ -217,13 +271,15 @@ Entries form a tree:
 `buildSessionContext()` walks from the current leaf to the root, producing the message list for the LLM:
 
 1. Collects all entries on the path
-2. Extracts current model and thinking level settings
+2. Extracts current model map, thinking level, and injected TTSR rules
 3. If a `CompactionEntry` is on the path:
    - Emits the summary first
    - Then messages from `firstKeptEntryId` to compaction
    - Then messages after compaction
 4. Converts `BranchSummaryEntry` and `CustomMessageEntry` to appropriate message formats
 
+Return value is a `SessionContext` containing `messages`, `models`, `thinkingLevel`, and `injectedTtsrRules`.
+
 ## Parsing Example
 
 ```typescript
@@ -231,7 +287,6 @@ const text = await Bun.file("session.jsonl").text();
 const entries = Bun.JSONL.parse(text);
 
 for (const entry of entries) {
-
 	switch (entry.type) {
 		case "session":
 			console.log(`Session v${entry.version ?? 1}: ${entry.id}`);
@@ -249,13 +304,19 @@ for (const entry of entries) {
 			console.log(`[${entry.id}] Custom (${entry.customType}): ${JSON.stringify(entry.data)}`);
 			break;
 		case "custom_message":
-			console.log(`[${entry.id}] Hook message (${entry.customType}): ${entry.content}`);
+			console.log(`[${entry.id}] Custom message (${entry.customType}): ${entry.content}`);
+			break;
+		case "ttsr_injection":
+			console.log(`[${entry.id}] TTSR rules: ${entry.injectedRules.join(", ")}`);
+			break;
+		case "session_init":
+			console.log(`[${entry.id}] Init: ${entry.tools.join(", ")}`);
 			break;
 		case "label":
 			console.log(`[${entry.id}] Label "${entry.label}" on ${entry.targetId}`);
 			break;
 		case "model_change":
-			console.log(`[${entry.id}] Model: ${entry.provider}/${entry.modelId}`);
+			console.log(`[${entry.id}] Model: ${entry.model} (${entry.role ?? "default"})`);
 			break;
 		case "thinking_level_change":
 			console.log(`[${entry.id}] Thinking: ${entry.thinkingLevel}`);
@@ -279,22 +340,26 @@ Key methods for working with sessions programmatically:
 
 - `appendMessage(message)` - Add message
 - `appendThinkingLevelChange(level)` - Record thinking change
-- `appendModelChange(provider, modelId)` - Record model change
-- `appendCompaction(summary, firstKeptEntryId, tokensBefore, details?, fromHook?)` - Add compaction
-- `appendCustomEntry(customType, data?)` - Hook state (not in context)
-- `appendCustomMessageEntry(customType, content, display, details?)` - Hook message (in context)
+- `appendModelChange(model, role?)` - Record model change (`model` = `provider/modelId`)
+- `appendSessionInit(init)` - Record initial subagent context
+- `appendCompaction(summary, shortSummary, firstKeptEntryId, tokensBefore, details?, fromExtension?, preserveData?)`
+- `appendCustomEntry(customType, data?)` - Extension state (not in context)
+- `appendCustomMessageEntry(customType, content, display, details?)` - Extension message (in context)
+- `appendTtsrInjection(ruleNames)` - Record injected TTSR rules
 - `appendLabelChange(targetId, label)` - Set/clear label
 
 ### Tree Navigation
 
 - `getLeafId()` - Current position
+- `getLeafEntry()` - Current leaf entry
 - `getEntry(id)` - Get entry by ID
-- `getPath(fromId?)` - Walk from entry to root
+- `getBranch(fromId?)` - Walk from entry to root
 - `getTree()` - Get full tree structure
 - `getChildren(parentId)` - Get direct children
 - `getLabel(id)` - Get label for entry
 - `branch(entryId)` - Move leaf to earlier entry
-- `branchWithSummary(entryId, summary, details?, fromHook?)` - Branch with context summary
+- `branchWithSummary(entryId | null, summary, details?, fromExtension?)` - Branch with context summary
+- `resetLeaf()` - Move leaf to before first entry
 
 ### Context
 

package/docs/skills.md

@@ -4,7 +4,7 @@
 
 Skills are self-contained capability packages that the agent loads on-demand. A skill provides specialized workflows, setup instructions, helper scripts, and reference documentation for specific tasks.
 
-OMP implements the [Agent Skills standard](https://agentskills.io/specification).
+OMP follows the [Agent Skills](https://agentskills.io/specification) SKILL.md format (YAML frontmatter + markdown body) and exposes skills via `skill://` URLs.
 
 **Example use cases:**
 - Web search and content extraction (Brave Search API)
@@ -87,99 +87,78 @@ cd /path/to/skill && npm install
 
 ### Frontmatter Fields
 
-Per the [Agent Skills specification](https://agentskills.io/specification#frontmatter-required):
+| Field | Required | Notes |
+|-------|----------|-------|
+| `name` | No | Defaults to the skill directory name. Use lowercase + hyphens for compatibility. |
+| `description` | Yes (OMP/custom), recommended everywhere | Used for skill matching and shown in the system prompt. |
 
-| Field | Required | Constraints |
-|-------|----------|-------------|
-| `name` | Yes | Max 64 chars. Lowercase a-z, 0-9, hyphens only. Must match parent directory name. |
-| `description` | Yes | Max 1024 chars. What the skill does and when to use it. |
-| `license` | No | License name or reference to bundled license file. |
-| `compatibility` | No | Max 500 chars. Environment requirements (system packages, network access, etc.). |
-| `metadata` | No | Arbitrary key-value mapping for additional metadata. |
-| `allowed-tools` | No | Space-delimited list of pre-approved tools (experimental). |
+OMP ignores additional frontmatter fields, but other tooling may use them.
 
-#### Name Validation
+#### Naming Guidance
 
-The `name` field must:
-- Be 1-64 characters
-- Contain only lowercase letters (a-z), numbers (0-9), and hyphens
-- Not start or end with a hyphen
-- Not contain consecutive hyphens (--)
-- Match the parent directory name exactly
-
-Valid: `pdf-processing`, `data-analysis`, `code-review`
-Invalid: `PDF-Processing`, `-pdf`, `pdf--processing`
-
-#### Description Best Practices
-
-The `description` is critical. It determines when the agent loads the skill. Be specific about both what it does and when to use it.
-
-Good:
-```yaml
-description: Extracts text and tables from PDF files, fills PDF forms, and merges multiple PDFs. Use when working with PDF documents or when the user mentions PDFs, forms, or document extraction.
-```
-
-Poor:
-```yaml
-description: Helps with PDFs.
-```
+OMP does not enforce naming rules, but skill names must match exactly for `skill://<name>` and `/skill:<name>` lookups. For cross-tool compatibility, keep names lowercase, hyphenated, and aligned with the directory name.
 
 ### File References
 
-Use relative paths from the skill directory:
+Use `skill://` URLs to reference files inside a skill directory:
 
 ```markdown
-See [the reference guide](references/REFERENCE.md) for details.
+Read the full skill:
+\`\`\`
+skill://my-skill
+\`\`\`
 
-Run the extraction script:
-\`\`\`bash
-./scripts/extract.py input.pdf
+Read a reference file:
+\`\`\`
+skill://my-skill/references/api-reference.md
 \`\`\`
 ```
 
 ## Skill Locations
 
-Skills are discovered from these locations (later wins on name collision):
+Skills are discovered from these sources (first match wins on name collisions):
+
+- OMP user: `~/.omp/agent/skills/<skill>/SKILL.md` (legacy alias: `~/.pi/agent/skills/...`)
+- OMP project: `<cwd>/.omp/skills/<skill>/SKILL.md` (legacy alias: `<cwd>/.pi/skills/...`)
+- Claude Code: `~/.claude/skills/<skill>/SKILL.md` and `<cwd>/.claude/skills/<skill>/SKILL.md`
+- Agents standard: `~/.agents/skills/<skill>/SKILL.md`
+- Codex CLI: `~/.codex/skills/<skill>/SKILL.md` and `<cwd>/.codex/skills/<skill>/SKILL.md`
+- Custom directories from `skills.customDirectories` (scanned recursively)
 
-1. `~/.codex/skills/**/SKILL.md` (Codex CLI, recursive)
-2. `~/.claude/skills/*/SKILL.md` (Claude Code user, one level)
-3. `<cwd>/.claude/skills/*/SKILL.md` (Claude Code project, one level)
-4. `~/.omp/agent/skills/**/SKILL.md` (OMP user, recursive)
-5. `<cwd>/.omp/skills/**/SKILL.md` (OMP project, recursive)
+Discovery skips hidden directories and `node_modules`, and respects `.gitignore`, `.ignore`, and `.fdignore` rules.
 
 ## Configuration
 
-Configure skill loading in `~/.omp/agent/settings.json`:
-
-```json
-{
-  "skills": {
-    "enabled": true,
-    "enableCodexUser": true,
-    "enableClaudeUser": true,
-    "enableClaudeProject": true,
-    "enablePiUser": true,
-    "enablePiProject": true,
-    "customDirectories": ["~/my-skills-repo"],
-    "ignoredSkills": ["deprecated-skill"],
-    "includeSkills": ["git-*", "docker"]
-  }
-}
+Global settings live in `~/.omp/agent/config.yml` (migrated from legacy `settings.json`). Project overrides live in `<cwd>/.omp/settings.json` or `<cwd>/.pi/settings.json`.
+
+```yaml
+skills:
+  enabled: true
+  enableSkillCommands: true
+  enableCodexUser: true
+  enableClaudeUser: true
+  enableClaudeProject: true
+  enablePiUser: true
+  enablePiProject: true
+  customDirectories: []
+  ignoredSkills: []
+  includeSkills: []
 ```
 
 | Setting | Default | Description |
 |---------|---------|-------------|
 | `enabled` | `true` | Master toggle for all skills |
+| `enableSkillCommands` | `true` | Register `/skill:<name>` commands in interactive mode |
 | `enableCodexUser` | `true` | Load from `~/.codex/skills/` |
 | `enableClaudeUser` | `true` | Load from `~/.claude/skills/` |
 | `enableClaudeProject` | `true` | Load from `<cwd>/.claude/skills/` |
-| `enableOmpUser` | `true` | Load from `~/.omp/agent/skills/` |
-| `enableOmpProject` | `true` | Load from `<cwd>/.omp/skills/` |
-| `customDirectories` | `[]` | Additional directories to scan (supports `~` expansion) |
-| `ignoredSkills` | `[]` | Glob patterns to exclude (e.g., `["deprecated-*", "test-skill"]`) |
-| `includeSkills` | `[]` | Glob patterns to include (empty = all; e.g., `["git-*", "docker"]`) |
+| `enablePiUser` | `true` | Load from `~/.omp/agent/skills/` (or `~/.pi/agent/skills/`) |
+| `enablePiProject` | `true` | Load from `<cwd>/.omp/skills/` (or `<cwd>/.pi/skills/`) |
+| `customDirectories` | `[]` | Additional directories to scan recursively (use absolute paths) |
+| `ignoredSkills` | `[]` | Glob patterns to exclude (e.g., `"deprecated-*"`) |
+| `includeSkills` | `[]` | Glob patterns to include (empty = all) |
 
-**Note:** `ignoredSkills` takes precedence over both `includeSkills` in settings and the `--skills` CLI flag. A skill matching any ignore pattern will be excluded regardless of include patterns.
+**Note:** `ignoredSkills` takes precedence over both `includeSkills` and the `--skills` CLI flag.
 
 ### CLI Filtering
 
@@ -200,25 +179,19 @@ This overrides the `includeSkills` setting for the current session.
 
 ## How Skills Work
 
-1. At startup, omp scans skill locations and extracts names + descriptions
-2. The system prompt includes available skills in XML format
-3. When a task matches, the agent uses `read` to load the full SKILL.md
-4. The agent follows the instructions, using relative paths to reference scripts/assets
+1. At startup, omp scans enabled skill locations and filters them by settings and CLI flags.
+2. If the `read` tool is available, skill names + descriptions are injected into the system prompt as XML.
+3. When a task matches a skill, the agent loads it with `read skill://<name>` or `skill://<name>/<path>`.
+4. When skills are preloaded (e.g., Task tool with explicit skills), their full contents are inlined under `<preloaded_skills>` and no `read` call is needed.
 
-This is progressive disclosure: only descriptions are always in context, full instructions load on-demand.
+This is progressive disclosure: only descriptions are always in context, full instructions load on-demand unless explicitly preloaded.
 
-## Validation Warnings
+## Warnings
 
-OMP validates skills against the Agent Skills standard and warns (but still loads) non-compliant skills:
+OMP emits warnings when:
 
-- Name doesn't match parent directory
-- Name exceeds 64 characters
-- Name contains invalid characters
-- Name starts/ends with hyphen or has consecutive hyphens
-- Description missing or exceeds 1024 characters
-- Unknown frontmatter fields
-
-Name collisions (same name from different locations) warn and keep the first skill found.
+- A skill directory or file cannot be read
+- Two skills share the same name (the first loaded wins; later ones are skipped)
 
 ## Example: Web Search Skill
 
@@ -258,12 +231,6 @@ cd /path/to/brave-search && npm install
 \`\`\`
 ```
 
-## Compatibility
-
-**Claude Code**: OMP reads skills from `~/.claude/skills/*/SKILL.md`. The `allowed-tools` and `model` frontmatter fields are ignored.
-
-**Codex CLI**: OMP reads skills from `~/.codex/skills/` recursively. Hidden files/directories and symlinks are skipped.
-
 ## Skill Repositories
 
 For inspiration and ready-to-use skills:
@@ -278,13 +245,10 @@ CLI:
 omp --no-skills
 ```
 
-Settings (`~/.omp/agent/settings.json`):
-```json
-{
-  "skills": {
-    "enabled": false
-  }
-}
+Settings:
+```yaml
+skills:
+  enabled: false
 ```
 
 Use the granular `enable*` flags to disable individual sources (e.g., `enableClaudeUser: false` to skip `~/.claude/skills`).