@x-otto/agent 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 +73 -0
- package/dist/index.d.ts +1625 -0
- package/dist/index.d.ts.map +1 -0
- package/dist/index.js +8 -0
- package/dist/index.js.map +1 -0
- package/package.json +35 -0
package/README.md
ADDED
|
@@ -0,0 +1,73 @@
|
|
|
1
|
+
# @x-otto/agent
|
|
2
|
+
|
|
3
|
+
> Single agent execution engine — state machine, work loop, tool pipeline, and deterministic trace substrate.
|
|
4
|
+
|
|
5
|
+
Encapsulates the single-agent execution loop: model streaming, tool orchestration (readonly parallel + mutation serial + steering), turn control, and full lifecycle observability. Provides the **agent core** that `@x-otto/runtime` assemblies into sessions.
|
|
6
|
+
|
|
7
|
+
## Installation
|
|
8
|
+
|
|
9
|
+
```bash
|
|
10
|
+
pnpm add @x-otto/agent
|
|
11
|
+
```
|
|
12
|
+
|
|
13
|
+
## Usage
|
|
14
|
+
|
|
15
|
+
```ts
|
|
16
|
+
import { createAgent } from '@x-otto/agent'
|
|
17
|
+
|
|
18
|
+
const agent = createAgent({
|
|
19
|
+
model: myModel,
|
|
20
|
+
provider: myProvider,
|
|
21
|
+
systemPrompt: 'You are a helpful assistant.',
|
|
22
|
+
tools: [readTool, writeTool, bashTool],
|
|
23
|
+
maxToolTurns: 25,
|
|
24
|
+
})
|
|
25
|
+
|
|
26
|
+
agent.on('turn.end', (ev) => console.log('Turn complete, tokens:', ev.message.usage))
|
|
27
|
+
agent.on('error', (ev) => console.error('Agent error:', ev.error))
|
|
28
|
+
|
|
29
|
+
await agent.prompt('Find and fix the type error in src/app.ts')
|
|
30
|
+
```
|
|
31
|
+
|
|
32
|
+
## API
|
|
33
|
+
|
|
34
|
+
### `createAgent(config)` / `Agent`
|
|
35
|
+
|
|
36
|
+
State machine with 7 states (`idle → streaming → tool_executing → completed/error/aborted/archived`) and 11+ lifecycle events. Key methods:
|
|
37
|
+
- `run(context)` — main execution entry (mutates messages in-place)
|
|
38
|
+
- `steer(message)` — inject steering mid-execution
|
|
39
|
+
- `followUp(message)` — inject follow-up question
|
|
40
|
+
- `abort()` — graceful abort
|
|
41
|
+
- `getState()` — immutable state snapshot
|
|
42
|
+
- `reset()` — hard reset (only legal bypass of `VALID_TRANSITIONS`)
|
|
43
|
+
|
|
44
|
+
### Agent Events
|
|
45
|
+
|
|
46
|
+
`status.change` / `turn.start` / `turn.end` / `stream.event` / `tool.callStart` / `tool.callEnd` / `steering.injected` / `followUp.start` / `max.turns` / `prompt.budget` / `progress.stall` / `tool.call.mismatch` / `compaction.reactive` / `image.degradation` / `image.vision-delegate` / `stream.retry` / `stream.retry.accelerated` / `error` / `abort`
|
|
47
|
+
|
|
48
|
+
### Deterministic Ports
|
|
49
|
+
|
|
50
|
+
`ClockPort` / `RandomPort` / `IdPort` — injectable ports replacing `Date.now()` / `Math.random()` / `randomUUID()`. Recording ports wrap real implementations and log nondet draws for replay; replay ports feed back recorded values for byte-identical determinism.
|
|
51
|
+
|
|
52
|
+
### Engine Nodes & Defaults
|
|
53
|
+
|
|
54
|
+
`ENGINE_NODES` canonical node table — 21 pausable, 23 observable, 30 traceable, 9 hook timing nodes, all views derived via capability projection. `ENGINE_DEFAULTS` cross-layer constants (`maxToolTurns`, `streamEventSampleInterval`, `traceResultMaxChars`, `maxToolResultChars`, `maxToolConcurrency`).
|
|
55
|
+
|
|
56
|
+
### Trace System
|
|
57
|
+
|
|
58
|
+
Five-capability (observe / debug / traceback / rollback / replay) unified source of truth. `TraceEvent` with 5 kinds (`lifecycle` / `stream` / `tool` / `nondet` / `checkpoint`). `TraceRecorder` / `TraceSink` ports. Causal DAG views via `trace-views.ts`.
|
|
59
|
+
|
|
60
|
+
### Tool Executor
|
|
61
|
+
|
|
62
|
+
`beforeHooks → Zod validate → execute → afterHooks` pipeline. Supports `direct` / `deferred` / `hidden` exposure levels, `readonly` parallel optimization, approval gates, and error classification.
|
|
63
|
+
|
|
64
|
+
## Dependencies
|
|
65
|
+
|
|
66
|
+
- Internal: `@x-otto/hook-contracts`, `@x-otto/interchange`, `@x-otto/provider`, `@x-otto/shared`
|
|
67
|
+
- External: none
|
|
68
|
+
|
|
69
|
+
## Related
|
|
70
|
+
|
|
71
|
+
- [Architecture](./ARCHITECTURE.md)
|
|
72
|
+
- `@x-otto/runtime` — assembly layer that wraps Agent into host-neutral sessions
|
|
73
|
+
- `@x-otto/hook-contracts` — lifecycle hook timing contracts
|