mirror of
https://github.com/getcompanion-ai/co-mono.git
synced 2026-04-15 14:03:49 +00:00
docs(coding-agent): improve README structure and update session/compaction docs
- README-NEW.md: add Quick Start, Interactive Mode, Sessions sections - session.md: add Message Types section, complete SessionManager API, fix source links to GitHub URLs - compaction.md: rename hooks to extensions, fix source links to GitHub URLs - keybindings.md: new file documenting all keyboard shortcuts
This commit is contained in:
Mario Zechner
parent
859a4e05b6
commit
28ab25b07e
4 changed files with 412 additions and 64 deletions
|
|
@ -26,11 +26,147 @@ Sessions have a version field in the header:
|
|||
|
||||
Existing sessions are automatically migrated to the current version (v3) when loaded.
|
||||
|
||||
## Type Definitions
|
||||
## Source Files
|
||||
|
||||
- [`src/core/session-manager.ts`](../src/core/session-manager.ts) - Session entry types
|
||||
- [`packages/agent-core/src/types.ts`](../../agent-core/src/types.ts) - `AgentMessage`
|
||||
- [`packages/ai/src/types.ts`](../../ai/src/types.ts) - `UserMessage`, `AssistantMessage`, `ToolResultMessage`, `Usage`, `ToolCall`, `ImageContent`, `TextContent`
|
||||
Source on GitHub ([pi-mono](https://github.com/badlogic/pi-mono)):
|
||||
- [`packages/coding-agent/src/core/session-manager.ts`](https://github.com/badlogic/pi-mono/blob/main/packages/coding-agent/src/core/session-manager.ts) - Session entry types and SessionManager
|
||||
- [`packages/coding-agent/src/core/messages.ts`](https://github.com/badlogic/pi-mono/blob/main/packages/coding-agent/src/core/messages.ts) - Extended message types (BashExecutionMessage, CustomMessage, etc.)
|
||||
- [`packages/ai/src/types.ts`](https://github.com/badlogic/pi-mono/blob/main/packages/ai/src/types.ts) - Base message types (UserMessage, AssistantMessage, ToolResultMessage)
|
||||
- [`packages/agent/src/types.ts`](https://github.com/badlogic/pi-mono/blob/main/packages/agent/src/types.ts) - AgentMessage union type
|
||||
|
||||
For TypeScript definitions in your project, inspect `node_modules/@mariozechner/pi-coding-agent/dist/` and `node_modules/@mariozechner/pi-ai/dist/`.
|
||||
|
||||
## Message Types
|
||||
|
||||
Session entries contain `AgentMessage` objects. Understanding these types is essential for parsing sessions and writing extensions.
|
||||
|
||||
### Content Blocks
|
||||
|
||||
Messages contain arrays of typed content blocks:
|
||||
|
||||
```typescript
|
||||
interface TextContent {
|
||||
type: "text";
|
||||
text: string;
|
||||
}
|
||||
|
||||
interface ImageContent {
|
||||
type: "image";
|
||||
data: string; // base64 encoded
|
||||
mimeType: string; // e.g., "image/jpeg", "image/png"
|
||||
}
|
||||
|
||||
interface ThinkingContent {
|
||||
type: "thinking";
|
||||
thinking: string;
|
||||
}
|
||||
|
||||
interface ToolCall {
|
||||
type: "toolCall";
|
||||
id: string;
|
||||
name: string;
|
||||
arguments: Record<string, any>;
|
||||
}
|
||||
```
|
||||
|
||||
### Base Message Types (from pi-ai)
|
||||
|
||||
```typescript
|
||||
interface UserMessage {
|
||||
role: "user";
|
||||
content: string | (TextContent | ImageContent)[];
|
||||
timestamp: number; // Unix ms
|
||||
}
|
||||
|
||||
interface AssistantMessage {
|
||||
role: "assistant";
|
||||
content: (TextContent | ThinkingContent | ToolCall)[];
|
||||
api: string;
|
||||
provider: string;
|
||||
model: string;
|
||||
usage: Usage;
|
||||
stopReason: "stop" | "length" | "toolUse" | "error" | "aborted";
|
||||
errorMessage?: string;
|
||||
timestamp: number;
|
||||
}
|
||||
|
||||
interface ToolResultMessage {
|
||||
role: "toolResult";
|
||||
toolCallId: string;
|
||||
toolName: string;
|
||||
content: (TextContent | ImageContent)[];
|
||||
details?: any; // Tool-specific metadata
|
||||
isError: boolean;
|
||||
timestamp: number;
|
||||
}
|
||||
|
||||
interface Usage {
|
||||
input: number;
|
||||
output: number;
|
||||
cacheRead: number;
|
||||
cacheWrite: number;
|
||||
totalTokens: number;
|
||||
cost: {
|
||||
input: number;
|
||||
output: number;
|
||||
cacheRead: number;
|
||||
cacheWrite: number;
|
||||
total: number;
|
||||
};
|
||||
}
|
||||
```
|
||||
|
||||
### Extended Message Types (from pi-coding-agent)
|
||||
|
||||
```typescript
|
||||
interface BashExecutionMessage {
|
||||
role: "bashExecution";
|
||||
command: string;
|
||||
output: string;
|
||||
exitCode: number | undefined;
|
||||
cancelled: boolean;
|
||||
truncated: boolean;
|
||||
fullOutputPath?: string;
|
||||
excludeFromContext?: boolean; // true for !! prefix commands
|
||||
timestamp: number;
|
||||
}
|
||||
|
||||
interface CustomMessage {
|
||||
role: "custom";
|
||||
customType: string; // Extension identifier
|
||||
content: string | (TextContent | ImageContent)[];
|
||||
display: boolean; // Show in TUI
|
||||
details?: any; // Extension-specific metadata
|
||||
timestamp: number;
|
||||
}
|
||||
|
||||
interface BranchSummaryMessage {
|
||||
role: "branchSummary";
|
||||
summary: string;
|
||||
fromId: string; // Entry we branched from
|
||||
timestamp: number;
|
||||
}
|
||||
|
||||
interface CompactionSummaryMessage {
|
||||
role: "compactionSummary";
|
||||
summary: string;
|
||||
tokensBefore: number;
|
||||
timestamp: number;
|
||||
}
|
||||
```
|
||||
|
||||
### AgentMessage Union
|
||||
|
||||
```typescript
|
||||
type AgentMessage =
|
||||
| UserMessage
|
||||
| AssistantMessage
|
||||
| ToolResultMessage
|
||||
| BashExecutionMessage
|
||||
| CustomMessage
|
||||
| BranchSummaryMessage
|
||||
| CompactionSummaryMessage;
|
||||
```
|
||||
|
||||
## Entry Base
|
||||
|
||||
|
|
@ -96,8 +232,8 @@ Created when context is compacted. Stores a summary of earlier messages.
|
|||
```
|
||||
|
||||
Optional fields:
|
||||
- `details`: Compaction-implementation specific data (e.g., file operations for default implementation, or custom data for extension implementations)
|
||||
- `fromHook`: `true` if generated by an extension, `false`/`undefined` if pi-generated
|
||||
- `details`: Implementation-specific data (e.g., `{ readFiles: string[], modifiedFiles: string[] }` for default, or custom data for extensions)
|
||||
- `fromHook`: `true` if generated by an extension, `false`/`undefined` if pi-generated (legacy field name)
|
||||
|
||||
### BranchSummaryEntry
|
||||
|
||||
|
|
@ -108,8 +244,8 @@ Created when switching branches via `/tree` with an LLM generated summary of the
|
|||
```
|
||||
|
||||
Optional fields:
|
||||
- `details`: File tracking data (`{ readFiles: string[], modifiedFiles: string[] }`) for default implementation, arbitrary for custom implementation
|
||||
- `fromHook`: `true` if generated by an extension
|
||||
- `details`: File tracking data (`{ readFiles: string[], modifiedFiles: string[] }`) for default, or custom data for extensions
|
||||
- `fromHook`: `true` if generated by an extension, `false`/`undefined` if pi-generated (legacy field name)
|
||||
|
||||
### CustomEntry
|
||||
|
||||
|
|
@ -224,15 +360,25 @@ for (const line of lines) {
|
|||
|
||||
## SessionManager API
|
||||
|
||||
Key methods for working with sessions programmatically:
|
||||
Key methods for working with sessions programmatically.
|
||||
|
||||
### Creation
|
||||
### Static Creation Methods
|
||||
- `SessionManager.create(cwd, sessionDir?)` - New session
|
||||
- `SessionManager.open(path, sessionDir?)` - Open existing
|
||||
- `SessionManager.open(path, sessionDir?)` - Open existing session file
|
||||
- `SessionManager.continueRecent(cwd, sessionDir?)` - Continue most recent or create new
|
||||
- `SessionManager.inMemory(cwd?)` - No file persistence
|
||||
- `SessionManager.forkFrom(sourcePath, targetCwd, sessionDir?)` - Fork session from another project
|
||||
|
||||
### Appending (all return entry ID)
|
||||
### Static Listing Methods
|
||||
- `SessionManager.list(cwd, sessionDir?, onProgress?)` - List sessions for a directory
|
||||
- `SessionManager.listAll(onProgress?)` - List all sessions across all projects
|
||||
|
||||
### Instance Methods - Session Management
|
||||
- `newSession(options?)` - Start a new session (options: `{ parentSession?: string }`)
|
||||
- `setSessionFile(path)` - Switch to a different session file
|
||||
- `createBranchedSession(leafId)` - Extract branch to new session file
|
||||
|
||||
### Instance Methods - Appending (all return entry ID)
|
||||
- `appendMessage(message)` - Add message
|
||||
- `appendThinkingLevelChange(level)` - Record thinking change
|
||||
- `appendModelChange(provider, modelId)` - Record model change
|
||||
|
|
@ -242,7 +388,7 @@ Key methods for working with sessions programmatically:
|
|||
- `appendCustomMessageEntry(customType, content, display, details?)` - Extension message (in context)
|
||||
- `appendLabelChange(targetId, label)` - Set/clear label
|
||||
|
||||
### Tree Navigation
|
||||
### Instance Methods - Tree Navigation
|
||||
- `getLeafId()` - Current position
|
||||
- `getLeafEntry()` - Get current leaf entry
|
||||
- `getEntry(id)` - Get entry by ID
|
||||
|
|
@ -254,8 +400,13 @@ Key methods for working with sessions programmatically:
|
|||
- `resetLeaf()` - Reset leaf to null (before any entries)
|
||||
- `branchWithSummary(entryId, summary, details?, fromHook?)` - Branch with context summary
|
||||
|
||||
### Context
|
||||
- `buildSessionContext()` - Get messages for LLM
|
||||
### Instance Methods - Context & Info
|
||||
- `buildSessionContext()` - Get messages, thinkingLevel, and model for LLM
|
||||
- `getEntries()` - All entries (excluding header)
|
||||
- `getHeader()` - Session metadata
|
||||
- `getHeader()` - Session header metadata
|
||||
- `getSessionName()` - Get display name from latest session_info entry
|
||||
- `getCwd()` - Working directory
|
||||
- `getSessionDir()` - Session storage directory
|
||||
- `getSessionId()` - Session UUID
|
||||
- `getSessionFile()` - Session file path (undefined for in-memory)
|
||||
- `isPersisted()` - Whether session is saved to disk
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue