@x-otto/runtime 0.0.1-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 +108 -0
- package/dist/index.d.ts +2973 -0
- package/dist/index.d.ts.map +1 -0
- package/dist/index.js +24 -0
- package/dist/index.js.map +1 -0
- package/package.json +40 -0
package/README.md
ADDED
|
@@ -0,0 +1,108 @@
|
|
|
1
|
+
# @x-otto/runtime
|
|
2
|
+
|
|
3
|
+
> Host-neutral engine assembly layer — wraps `@x-otto/agent` into session-ready form.
|
|
4
|
+
|
|
5
|
+
`@x-otto/runtime` takes the bare `@x-otto/agent` execution engine and assembles it into a form hosts can directly derive sessions from. Host-neutral, zero coding domain strategy dependency — any structurally different second host can reuse the engine in 3 lines of assembly.
|
|
6
|
+
|
|
7
|
+
Beyond session management, runtime provides process lifecycle governance (`ProcessRuntime`, `MemoryGovernor`, `FleetMonitor`), observability (`AgentObservabilityRegistry`, `AgentJobRegistry`), time travel (checkpoint/rollback/fork/replay/traceback), persistence sync, context source injection, and HITL interaction gates.
|
|
8
|
+
|
|
9
|
+
## Installation
|
|
10
|
+
|
|
11
|
+
```bash
|
|
12
|
+
pnpm add @x-otto/runtime
|
|
13
|
+
```
|
|
14
|
+
|
|
15
|
+
## Usage
|
|
16
|
+
|
|
17
|
+
### Minimal host — 3 lines
|
|
18
|
+
|
|
19
|
+
```ts
|
|
20
|
+
import { createAgentRuntime } from '@x-otto/runtime'
|
|
21
|
+
|
|
22
|
+
const runtime = createAgentRuntime({ workspaceDir: process.cwd() })
|
|
23
|
+
|
|
24
|
+
const session = await runtime.createSession({
|
|
25
|
+
model: myModel,
|
|
26
|
+
systemPrompt: 'You are a coding assistant.',
|
|
27
|
+
tools: myTools,
|
|
28
|
+
})
|
|
29
|
+
|
|
30
|
+
await session.prompt('Hello')
|
|
31
|
+
await runtime.dispose()
|
|
32
|
+
```
|
|
33
|
+
|
|
34
|
+
### Subscribe to session events
|
|
35
|
+
|
|
36
|
+
```ts
|
|
37
|
+
session.subscribe((event) => {
|
|
38
|
+
switch (event.type) {
|
|
39
|
+
case 'stream.event':
|
|
40
|
+
case 'tool.callStart':
|
|
41
|
+
case 'tool.callEnd':
|
|
42
|
+
case 'prompt.end':
|
|
43
|
+
}
|
|
44
|
+
})
|
|
45
|
+
```
|
|
46
|
+
|
|
47
|
+
### Register a permission hook
|
|
48
|
+
|
|
49
|
+
```ts
|
|
50
|
+
runtime.hookRegistry.register(defineHook({
|
|
51
|
+
name: 'my-permission-guard',
|
|
52
|
+
timing: 'tool.execute.before',
|
|
53
|
+
handle: (input, output) => {
|
|
54
|
+
if (input.toolName === 'dangerous_op') output.decision = 'deny'
|
|
55
|
+
},
|
|
56
|
+
}))
|
|
57
|
+
```
|
|
58
|
+
|
|
59
|
+
## API
|
|
60
|
+
|
|
61
|
+
### `createAgentRuntime(options?)`
|
|
62
|
+
|
|
63
|
+
| Field | Default | Description |
|
|
64
|
+
|-------|---------|-------------|
|
|
65
|
+
| `workspaceDir` | `process.cwd()` | Workspace root |
|
|
66
|
+
| `providerRegistry` | `createDefaultProviderRegistry()` | LLM provider registry |
|
|
67
|
+
| `hookRegistry` | `createHookRegistry({preset:'default'})` | Hook container |
|
|
68
|
+
| `clock` | system clock | Deterministic clock (replay feed) |
|
|
69
|
+
| `traceStore` | `MemoryAppendLog` | Trace storage backend |
|
|
70
|
+
| `checkpointStore` | `MemoryAppendLog` | Checkpoint storage backend |
|
|
71
|
+
| `memory` | `undefined` | Auto memory compression port |
|
|
72
|
+
| `maxSessions` | env `SESSION_MAX`(50) | Session pool capacity |
|
|
73
|
+
| `storage` | `{kind:'in-memory'}` | Persistence backend (disk/remote/custom) |
|
|
74
|
+
|
|
75
|
+
### `AgentRuntime`
|
|
76
|
+
|
|
77
|
+
| Member | Description |
|
|
78
|
+
|--------|-------------|
|
|
79
|
+
| `createSession(config)` | Unified session derivation entry |
|
|
80
|
+
| `sessions` | `SessionManager` — pool, time travel, persistence |
|
|
81
|
+
| `hookRegistry` | Global hook registry |
|
|
82
|
+
| `contextSources` | Ordered context source registry (D33) |
|
|
83
|
+
| `traceStore` / `checkpointStore` | Event store backends |
|
|
84
|
+
| `clock` | Deterministic clock |
|
|
85
|
+
| `dispose()` | Release all sessions |
|
|
86
|
+
|
|
87
|
+
### `RUNTIME_DEFAULTS`
|
|
88
|
+
|
|
89
|
+
Single source of truth for cross-layer defaults: `{ maxToolTurns: 25 }` (references `ENGINE_DEFAULTS`).
|
|
90
|
+
|
|
91
|
+
### Process & Fleet Governance
|
|
92
|
+
|
|
93
|
+
- `ProcessRuntime` — managed subprocess lifecycle (spawn/kill/kill-grace/reap by category)
|
|
94
|
+
- `MemoryGovernor` — V8 heap self-monitoring with warning/critical levels
|
|
95
|
+
- `FleetMonitor` — machine-level otto process budget awareness (RSS, orphans, generations)
|
|
96
|
+
- `AgentObservabilityRegistry` — sub-agent transparent observability (turn/tool/token/stall)
|
|
97
|
+
- `AgentJobRegistry` — background agent session job tracking (running→ready→applied lifecycle)
|
|
98
|
+
|
|
99
|
+
## Dependencies
|
|
100
|
+
|
|
101
|
+
- Internal: `@x-otto/agent`, `@x-otto/ai`, `@x-otto/devtools`, `@x-otto/env`, `@x-otto/hooks`, `@x-otto/persistence`, `@x-otto/prompt`, `@x-otto/session`, `@x-otto/session-contract`, `@x-otto/shared`
|
|
102
|
+
- External: `node:crypto`, `node:fs/promises`, `node:path`, `node:child_process`
|
|
103
|
+
|
|
104
|
+
## Related
|
|
105
|
+
|
|
106
|
+
- [Architecture](./ARCHITECTURE.md)
|
|
107
|
+
- `@x-otto/agent` — bare engine this package assembles
|
|
108
|
+
- `@x-otto/coding` — coding strategy layer (consumes runtime)
|