@x-otto/interchange 0.1.0-alpha.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +109 -0
- package/dist/index.d.ts +1373 -0
- package/dist/index.js +2 -0
- package/package.json +28 -0
package/README.md
ADDED
|
@@ -0,0 +1,109 @@
|
|
|
1
|
+
# @otto/interchange
|
|
2
|
+
|
|
3
|
+
> Provider-neutral protocol type single source of truth. Message, StreamEvent, Model, Tool, Session Event types — zero dependencies.
|
|
4
|
+
|
|
5
|
+
`@otto/interchange` (formerly `@otto/protocol`, renamed/merged) is the zero-dependency pure type leaf package that defines the canonical protocol types shared across the entire monorepo: `Message`, `StreamEvent`, `Model`, `Usage`, `ToolCall`, `AgentSessionEvent`, `GrillQuestion`, sigil input types, and more. Every package that deals with LLM provider communication, session events, or user input contracts imports from here.
|
|
6
|
+
|
|
7
|
+
## Installation
|
|
8
|
+
|
|
9
|
+
```bash
|
|
10
|
+
pnpm add @otto/interchange
|
|
11
|
+
```
|
|
12
|
+
|
|
13
|
+
## Usage
|
|
14
|
+
|
|
15
|
+
```ts
|
|
16
|
+
import type {
|
|
17
|
+
Message,
|
|
18
|
+
UserMessage,
|
|
19
|
+
AssistantMessage,
|
|
20
|
+
StreamEvent,
|
|
21
|
+
Model,
|
|
22
|
+
Usage,
|
|
23
|
+
ToolCall,
|
|
24
|
+
AgentSessionEvent,
|
|
25
|
+
GrillQuestion,
|
|
26
|
+
NormalizedImage,
|
|
27
|
+
SigilEntry,
|
|
28
|
+
SigilKind,
|
|
29
|
+
} from '@otto/interchange'
|
|
30
|
+
import { hasToolCalls, normalizeImageData, sigilOf } from '@otto/interchange'
|
|
31
|
+
|
|
32
|
+
// Inspect a message for tool calls
|
|
33
|
+
const msg: AssistantMessage = { role: 'assistant', content: [...] }
|
|
34
|
+
if (hasToolCalls(msg)) {
|
|
35
|
+
const calls = getToolCallsByAssistantMessage(msg)
|
|
36
|
+
}
|
|
37
|
+
|
|
38
|
+
// Normalize image data
|
|
39
|
+
const normalized = normalizeImageData({ data: 'base64...', mediaType: 'image/png' })
|
|
40
|
+
|
|
41
|
+
// Work with sigils
|
|
42
|
+
const entry: SigilEntry = { label: 'File', value: '/path/to/file', kind: 'file', source: 'builtin' }
|
|
43
|
+
```
|
|
44
|
+
|
|
45
|
+
## API
|
|
46
|
+
|
|
47
|
+
### Message Types (message.ts)
|
|
48
|
+
- `Message` — `UserMessage | AssistantMessage | ToolResultMessage | SystemNotificationMessage`
|
|
49
|
+
- `UserMessage` — `{ role: 'user'; content: ContentPart[] }`
|
|
50
|
+
- `AssistantMessage` — `{ role: 'assistant'; content: ContentPart[]; tool_calls?: ToolCall[] }`
|
|
51
|
+
- `ToolResultMessage` — `{ role: 'tool'; tool_call_id: string; content: ContentPart[] }`
|
|
52
|
+
- `ContentPart` — `TextContent | ImageContent | ThinkingContent | ToolCall | A2uiContent`
|
|
53
|
+
- `Usage` — `{ inputTokens, outputTokens, cacheReadTokens, cacheWriteTokens }`
|
|
54
|
+
- `StopReason` — `'end_turn' | 'max_tokens' | 'tool_use' | 'stop_sequence' | 'refusal'`
|
|
55
|
+
- `Api` / `Provider` / `KnownApi` / `KnownProvider` — provider and API identifiers
|
|
56
|
+
- `hasToolCalls(msg)` / `getToolCallsByAssistantMessage(msg)` — utility predicates
|
|
57
|
+
|
|
58
|
+
### Model Types (model.ts)
|
|
59
|
+
- `Model<T>` — full model descriptor (id, name, api, provider, baseUrl, cost, contextWindow, strengths, thinkingLevels, imageConstraints, supportsTools, etc.)
|
|
60
|
+
- `ModelSpec` — `string | { provider, name, api? } | Model`
|
|
61
|
+
- `Cost` — `{ input, output, cacheRead, cacheWrite }`
|
|
62
|
+
- `ThinkingLevel` — `'low' | 'medium' | 'high' | 'xhigh' | 'max'`
|
|
63
|
+
- `ModelStrength` — capability label for subagent selection
|
|
64
|
+
- `modelSupportsImages(model)` — image capability check
|
|
65
|
+
|
|
66
|
+
### Stream Types (stream.ts)
|
|
67
|
+
- `StreamEvent` — discriminated union of stream events (text/thinking/image start/delta/end, tool calls, error)
|
|
68
|
+
- `ProviderUsageSnapshot` — rate limit and quota snapshot
|
|
69
|
+
|
|
70
|
+
### Tool Types (tool.ts)
|
|
71
|
+
- `ToolCall` — `{ type: 'tool_call'; id, name, arguments, parseError? }`
|
|
72
|
+
- `ToolResult` — `{ content, isError?, errorKind?, details?, pluginSource? }`
|
|
73
|
+
- `ToolCallContext<Params>` — execution context (id, params, signal, sessionId, depth)
|
|
74
|
+
- `AgentTool<Params>` — tool definition (name, description, parameters, execute)
|
|
75
|
+
- `ToolErrorKind` — `'validation' | 'permission' | 'timeout' | 'network' | ...`
|
|
76
|
+
- `extractToolResultText(result)` — concatenate text blocks from tool result
|
|
77
|
+
|
|
78
|
+
### Session Event Types (session-event.ts)
|
|
79
|
+
- `AgentSessionEvent` — full discriminant union of engine events (session lifecycle, prompt, streaming, tool calls, compaction, HITL, errors, etc.)
|
|
80
|
+
- `GrillQuestion` / `GrillAnswer` / `GrillOption` / `GrillRequest` — HITL question types
|
|
81
|
+
- `AskUserQuestion` — legacy question type
|
|
82
|
+
|
|
83
|
+
### Input Types (input.ts)
|
|
84
|
+
- `SigilKind` / `SigilPrefix` — `'#'` and `'@'` trigger types
|
|
85
|
+
- `SigilEntry` / `SigilSource` / `SigilProvider` — input enrichment entries
|
|
86
|
+
- `SigilResolver` — resolve function for runtime chip expansion (RFC-210 D2)
|
|
87
|
+
- `SigilTrigger` / `DismissedSigil` — trigger detection state machine
|
|
88
|
+
- `evaluateSigilTrigger` / `extractSigilPrefix` / `applySigilCompletion` — pure sigil logic functions
|
|
89
|
+
|
|
90
|
+
### Image Types (image.ts)
|
|
91
|
+
- `NormalizedImage` — normalized image representation
|
|
92
|
+
- `normalizeImageData(data, mediaType)` — image normalization pure function
|
|
93
|
+
- `CommonImageMime` / `AnthropicImageMime` — MIME type annotations
|
|
94
|
+
|
|
95
|
+
### Other Types
|
|
96
|
+
- `EngineCommand` — engine-level command type
|
|
97
|
+
- `TodoStatus` / `TodoItem` — todo list types
|
|
98
|
+
- `ChildProcessConfig` / `ProcessTracker` — child process management
|
|
99
|
+
- `PluginPerfMetricResult` — plugin performance metric contract
|
|
100
|
+
- `A2uiComponent` / `A2uiContent` — rich component types
|
|
101
|
+
|
|
102
|
+
## Dependencies
|
|
103
|
+
|
|
104
|
+
- Internal: none
|
|
105
|
+
- External: none
|
|
106
|
+
|
|
107
|
+
## Related
|
|
108
|
+
|
|
109
|
+
- [Architecture](./ARCHITECTURE.md)
|