manifest 5.9.7 → 5.9.8

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.
Files changed (3) hide show
  1. package/README.md +96 -51
  2. package/dist/index.js +3 -3
  3. package/package.json +1 -1
package/README.md CHANGED
@@ -1,108 +1,153 @@
1
1
  # Manifest
2
2
 
3
- Observability plugin for [OpenClaw](https://github.com/open-claw/open-claw). Collects traces, metrics, and cost data from your AI agent and displays them in a local dashboard — zero configuration required.
3
+ Cut your AI agent costs by up to 70%. Manifest is an open-source [OpenClaw](https://github.com/open-claw/open-claw) plugin that combines **intelligent LLM routing** with **real-time cost observability** — one install, zero configuration.
4
4
 
5
- ## Install
5
+ Instead of sending every request to the most expensive model, Manifest scores each query in under 2ms and routes it to the most cost-effective model that can handle it. Simple lookups go to fast, cheap models. Complex reasoning goes to frontier models. You see exactly where every dollar goes in a local dashboard.
6
+
7
+ ## Quick start
6
8
 
7
9
  ```bash
8
10
  openclaw plugins install manifest
9
11
  openclaw gateway restart
10
12
  ```
11
13
 
12
- That's it. The plugin starts an embedded server with SQLite at `http://127.0.0.1:2099`. Open that URL to see your dashboard.
14
+ Open `http://127.0.0.1:2099` — your dashboard is live with SQLite storage, no accounts or external services needed.
13
15
 
14
- ### Cloud mode
16
+ ## How the LLM router works
15
17
 
16
- To send telemetry to the hosted platform at [app.manifest.build](https://app.manifest.build) instead:
18
+ Manifest registers as an OpenAI-compatible provider in OpenClaw under the model name `auto`. When a request comes in:
17
19
 
18
- ```bash
19
- openclaw config set plugins.entries.manifest.config.mode cloud
20
- openclaw config set plugins.entries.manifest.config.apiKey "mnfst_YOUR_KEY"
21
- openclaw gateway restart
20
+ 1. **Score** — The plugin analyzes the conversation locally (last 10 user/assistant messages, excluding system prompts) and assigns a complexity tier.
21
+ 2. **Route** — The tier maps to the cheapest model that meets the quality bar: simple tasks go to small models, complex tasks go to frontier models.
22
+ 3. **Momentum** — Recent tier history (last 5 turns, 30-min window) is factored in so mid-conversation complexity shifts are handled smoothly.
23
+ 4. **Observe** — Every routed request is traced with the resolved model, provider, tier, token counts, and cost — visible in your dashboard.
24
+
25
+ The entire scoring step adds < 2ms of latency. If the resolve call fails, the request falls through to the default model with no interruption.
26
+
27
+ ### Enable routing
28
+
29
+ Routing activates automatically in local mode. Point your OpenClaw config to use the `manifest` provider with model `auto`:
30
+
31
+ ```yaml
32
+ # openclaw.config.yaml
33
+ models:
34
+ - provider: manifest
35
+ model: auto
22
36
  ```
23
37
 
24
- Or with environment variables:
38
+ ## Cost observability
39
+
40
+ The dashboard tracks every LLM call in real time:
41
+
42
+ - **Token usage** — input, output, and cache-read tokens broken down by model and provider
43
+ - **Cost breakdown** — per-model spend in USD with trend indicators
44
+ - **Message log** — paginated history with latency, tokens, and tool calls per request
45
+ - **Agent overview** — aggregated metrics across all your agents
46
+
47
+ ### Agent self-query tools
48
+
49
+ The plugin registers three tools your agent can call to query its own telemetry:
50
+
51
+ | Tool | Returns |
52
+ |------|---------|
53
+ | `manifest_usage` | Token consumption (input, output, cache, trend %) |
54
+ | `manifest_costs` | Cost breakdown by model in USD |
55
+ | `manifest_health` | Connectivity check |
25
56
 
26
- ```bash
27
- export MANIFEST_API_KEY=mnfst_YOUR_KEY
28
57
  ```
58
+ User: "How much have I spent today?"
59
+ → manifest_costs({ period: "today" })
60
+ → { total_usd: 0.42, by_model: { "gpt-4o": 0.38, "gpt-4o-mini": 0.04 } }
61
+ ```
62
+
63
+ ## Data privacy
64
+
65
+ - **Local mode**: Everything stays on your machine. SQLite database, no network calls.
66
+ - **Cloud mode**: Only OpenTelemetry metadata (model, tokens, latency) is sent. Your message content is never collected unless you explicitly enable `captureContent`.
29
67
 
30
68
  ## Configuration
31
69
 
70
+ ### Local mode (default)
71
+
72
+ Works out of the box. No API key needed.
73
+
32
74
  | Option | Type | Default | Description |
33
75
  |--------|------|---------|-------------|
34
- | `mode` | string | `local` | `local` for embedded server + SQLite, `cloud` for app.manifest.build |
35
- | `apiKey` | string | env `MANIFEST_API_KEY` | Agent API key (`mnfst_*`). Required for cloud mode only. |
36
- | `endpoint` | string | `https://app.manifest.build/otlp` | OTLP endpoint URL (cloud mode) |
76
+ | `port` | number | `2099` | Dashboard port |
77
+ | `host` | string | `127.0.0.1` | Bind address |
37
78
  | `serviceName` | string | `openclaw-gateway` | OpenTelemetry service name |
38
- | `captureContent` | boolean | `false` | Include message content in spans. Always enabled in local mode. |
39
- | `metricsIntervalMs` | number | `30000` | Metrics export interval (min 5000ms). 10s in local mode. |
40
- | `port` | number | `2099` | Local server port (local mode only) |
41
- | `host` | string | `127.0.0.1` | Local server bind address (local mode only) |
79
+ | `captureContent` | boolean | `true` | Include message content in spans (always on in local mode) |
80
+ | `metricsIntervalMs` | number | `10000` | Metrics export interval |
42
81
 
43
- Point to a self-hosted instance:
82
+ ### Cloud mode
83
+
84
+ Send telemetry to the hosted platform at [app.manifest.build](https://app.manifest.build):
85
+
86
+ ```bash
87
+ openclaw config set plugins.entries.manifest.config.mode cloud
88
+ openclaw config set plugins.entries.manifest.config.apiKey "mnfst_YOUR_KEY"
89
+ openclaw gateway restart
90
+ ```
91
+
92
+ | Option | Type | Default | Description |
93
+ |--------|------|---------|-------------|
94
+ | `mode` | string | `local` | `local` or `cloud` |
95
+ | `apiKey` | string | env `MANIFEST_API_KEY` | Agent API key (`mnfst_*`). Required for cloud mode. |
96
+ | `endpoint` | string | `https://app.manifest.build/otlp` | OTLP endpoint URL |
97
+ | `serviceName` | string | `openclaw-gateway` | OpenTelemetry service name |
98
+ | `captureContent` | boolean | `false` | Include message content in spans |
99
+ | `metricsIntervalMs` | number | `30000` | Metrics export interval (min 5000ms) |
100
+
101
+ ### Self-hosted
102
+
103
+ Point to your own Manifest instance:
44
104
 
45
105
  ```bash
46
106
  openclaw config set plugins.entries.manifest.config.endpoint "http://localhost:3001/otlp/v1"
47
107
  ```
48
108
 
49
- ## What it does
109
+ ## OpenTelemetry trace structure
50
110
 
51
- The plugin hooks into four OpenClaw lifecycle events and produces OpenTelemetry traces and metrics:
111
+ The plugin hooks into four OpenClaw lifecycle events and produces standard OpenTelemetry traces:
52
112
 
53
113
  | Event | What happens |
54
114
  |-------|-------------|
55
115
  | `message_received` | Root span created, message counter incremented |
56
116
  | `before_agent_start` | Child span for the agent turn |
57
117
  | `tool_result_persist` | Tool span with duration, success/error tracking |
58
- | `agent_end` | Spans closed, token and LLM metrics recorded |
59
-
60
- Resulting trace:
118
+ | `agent_end` | Spans closed, token/cost metrics recorded, routing resolved |
61
119
 
62
120
  ```
63
121
  openclaw.request (SERVER)
64
- └── openclaw.agent.turn (INTERNAL)
65
- ├── tool.web_search
66
- └── tool.summarize
67
- ```
68
-
69
- ## Agent tools
70
-
71
- The plugin registers three tools the agent can call to query its own telemetry:
72
-
73
- - **`manifest_usage`** — token consumption (input, output, cache, trend)
74
- - **`manifest_costs`** — cost breakdown by model in USD
75
- - **`manifest_health`** — connectivity check
76
-
77
- ```
78
- User: "How many tokens today?"
79
- → manifest_usage({ period: "today" })
80
- → { total_tokens: 45230, input_tokens: 34500, output_tokens: 10730, trend_pct: -20 }
122
+ └── openclaw.agent.turn (INTERNAL) model=gpt-4o-mini, tier=simple
123
+ ├── tool.web_search duration=320ms
124
+ └── tool.summarize duration=45ms
81
125
  ```
82
126
 
83
127
  ## Architecture
84
128
 
85
- The plugin bundles all OpenTelemetry dependencies into a single file via esbuild. This avoids the dual-registry problem that occurs when OpenClaw's own `@opentelemetry/api` and the plugin's copy coexist as separate instances. Zero runtime dependencies.
129
+ The plugin bundles all OpenTelemetry dependencies into a single file via esbuild. This avoids the dual-registry problem when OpenClaw's own `@opentelemetry/api` and the plugin's copy coexist. Zero runtime dependencies.
86
130
 
87
131
  ```
88
132
  Published package:
89
- dist/index.js Single-file bundle (~1.4MB)
133
+ dist/index.js Single-file bundle (~1.4 MB)
134
+ dist/server.js Embedded NestJS server (local mode)
135
+ dist/backend/ Backend compiled output
136
+ public/ Frontend dashboard assets
90
137
  openclaw.plugin.json Plugin manifest + config schema
91
138
  skills/ Bundled agent skills
92
- README.md
93
- LICENSE.md
94
139
  ```
95
140
 
96
141
  ## Development
97
142
 
98
143
  ```bash
99
- npm run build # Build the bundle
100
- npm run dev # Watch mode
101
- npm test # Run tests
102
- npm run typecheck # Type check
144
+ npm run build # Build the bundle
145
+ npm run dev # Watch mode
146
+ npm test # Run tests
147
+ npm run typecheck # Type-check
103
148
  ```
104
149
 
105
- Local testing:
150
+ Local testing against OpenClaw:
106
151
 
107
152
  ```bash
108
153
  openclaw plugins install -l ./packages/openclaw-plugin