relavium 0.1.0 → 0.1.1
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/CHANGELOG.md +76 -0
- package/README.md +109 -27
- package/dist/index.js +82 -39
- package/package.json +15 -4
package/CHANGELOG.md
ADDED
|
@@ -0,0 +1,76 @@
|
|
|
1
|
+
# Changelog
|
|
2
|
+
|
|
3
|
+
All notable changes to the `relavium` CLI are documented here. The format follows
|
|
4
|
+
[Keep a Changelog](https://keepachangelog.com/en/1.1.0/); this project is pre-1.0, so
|
|
5
|
+
minor and patch bumps both land additively under a `0.1.x` line. The publish flow is
|
|
6
|
+
[release-a-surface.md](../../docs/runbooks/release-a-surface.md) (tag `v<version>` →
|
|
7
|
+
the `Release CLI` workflow: pack → cross-OS smoke → publish).
|
|
8
|
+
|
|
9
|
+
## [0.1.1] — 2026-06-28
|
|
10
|
+
|
|
11
|
+
Everything merged since the `v0.1.0` spine — the three additive lanes and the authoring
|
|
12
|
+
lifecycle — with the in-phase CLI now feature-complete (Phase 2 workstreams 2.A–2.S).
|
|
13
|
+
|
|
14
|
+
### Added
|
|
15
|
+
|
|
16
|
+
- **Authoring lifecycle (`create` / `import` / `export`)** (2.J, PR #58). `relavium create`
|
|
17
|
+
is a `@clack/prompts` wizard that scaffolds either an **agent** (`.agent.yaml`) or a
|
|
18
|
+
**minimal single-agent workflow** (`input → agent → output`, `.relavium.yaml`), validated
|
|
19
|
+
against the kind-appropriate `@relavium/shared` schema before write. `relavium import <path>`
|
|
20
|
+
copies an external workflow/agent into the project after schema validation; `relavium
|
|
21
|
+
export <id>` writes a portable, share-safe copy **re-serialized from the validated AST**
|
|
22
|
+
(canonical, comment-free; no provider key by construction). Ids are unique **project-globally**
|
|
23
|
+
across both catalogs (a same-kind clash needs `--force`; a cross-kind clash is always
|
|
24
|
+
rejected), so a bare `<id>` stays unambiguous for `export` / `run`.
|
|
25
|
+
- **Agent-first chat family** (2.M–2.Q, PR #54/#55). `relavium chat` — an interactive
|
|
26
|
+
multi-turn REPL over `AgentSession` with streaming tokens, tool-call annotations, and the
|
|
27
|
+
FS-scope tier + command allowlist honored (`/exit` returns exit code `4`); `relavium
|
|
28
|
+
chat-resume <sessionId>`, `relavium chat-list`, and `relavium chat-export` (+ the in-REPL
|
|
29
|
+
`/export`) to ship a session to a `.relavium.yaml` scaffold; a headless `relavium chat --json`
|
|
30
|
+
`SessionEvent` stream; and a one-shot `relavium agent run <agent>` with a `--fixture` cassette
|
|
31
|
+
for deterministic offline replay.
|
|
32
|
+
- **Inbound MCP client** (2.R, PR #56/#57). Agents consume external MCP servers' tools across
|
|
33
|
+
`chat`, `run`, and `agent run` via the SDK-fenced `@relavium/mcp` package — `stdio` plus the
|
|
34
|
+
`http` / `sse` / `websocket` network transports behind an SSRF pre-connect floor + a per-server
|
|
35
|
+
`allow_local_endpoint` opt-in, with server credentials resolved from an isolated `mcp-secret:*`
|
|
36
|
+
keychain namespace and injected only into the spawn-time `env`. Discovered tools surface under
|
|
37
|
+
the `mcp_{server}_{tool}` namespace; a real-spawn end-to-end test proves the round-trip.
|
|
38
|
+
- **Media host-wiring** (2.S, PR #52). A generative media-output fixture runs end-to-end on the
|
|
39
|
+
CLI — host `resolveMediaSurface` routing, content-addressed `MediaStore` de-inline to a
|
|
40
|
+
`media://` handle, the SSRF-validated `EgressCapability.fetch` egress, a containment-checked
|
|
41
|
+
`save_to` write port, and the produced-media render surface in both the TUI and `--json` paths.
|
|
42
|
+
|
|
43
|
+
### Changed
|
|
44
|
+
|
|
45
|
+
- `relavium export` / `import` re-serialize from the validated AST: the canonical form drops
|
|
46
|
+
authored comments and emits cwd-relative paths in both human and `--json` output (no absolute
|
|
47
|
+
filesystem path in any message or record).
|
|
48
|
+
- The `create` wizard requires an interactive terminal on **both** ends (TTY stdout + TTY stdin);
|
|
49
|
+
it fails loud (exit `2`) under `--json` or a piped stream rather than hanging.
|
|
50
|
+
|
|
51
|
+
## [0.1.0] — 2026-06-24
|
|
52
|
+
|
|
53
|
+
The first published CLI — the engine-proving spine and the run/read surface.
|
|
54
|
+
|
|
55
|
+
### Added
|
|
56
|
+
|
|
57
|
+
- The `commander.js` CLI skeleton + process contract (output-mode detection, the deterministic
|
|
58
|
+
exit-code map, global flags) (2.A) and two-level config resolution (`~/.relavium/` → project
|
|
59
|
+
`.relavium/`) (2.B).
|
|
60
|
+
- `relavium run` wired to `@relavium/core` — workflow resolution, typed `--input` coercion, the
|
|
61
|
+
live event stream, SIGINT→cancel, and the terminal-event→exit-code mapping (2.D).
|
|
62
|
+
- The `--json` CI machine-output contract: one `RunEvent` per line (NDJSON), pure stdout,
|
|
63
|
+
diagnostics on stderr, deterministic exit codes (2.F).
|
|
64
|
+
- The `ink` streaming TUI — live per-node status, the active node's token stream, and a running
|
|
65
|
+
cost/duration footer over the same event bus as `--json` (2.E).
|
|
66
|
+
- The interactive human-gate prompt + the out-of-band `relavium gate <runId>` cross-process
|
|
67
|
+
resume (2.G).
|
|
68
|
+
- Durable local run history via `@relavium/db`, powering the read commands `list` / `logs` /
|
|
69
|
+
`status` / `gate list` (2.H, 2.I).
|
|
70
|
+
- `relavium provider` commands storing API keys in the OS keychain via `@napi-rs/keyring`, with a
|
|
71
|
+
`RELAVIUM_<PROVIDER>_API_KEY` env-var fallback for headless/CI hosts (2.C).
|
|
72
|
+
- The engine regression harness adopted as the CI gate (2.K), and packaging + cross-OS install
|
|
73
|
+
verification — the `tsup` engine-inlined ESM bundle published as `npm i -g relavium` (2.L).
|
|
74
|
+
|
|
75
|
+
[0.1.1]: https://github.com/HodeTech/Relavium/releases/tag/v0.1.1
|
|
76
|
+
[0.1.0]: https://github.com/HodeTech/Relavium/releases/tag/v0.1.0
|
package/README.md
CHANGED
|
@@ -1,11 +1,17 @@
|
|
|
1
1
|
# relavium
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
|
|
4
|
+
|
|
5
|
+
|
|
4
6
|
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
|
|
7
|
+
> **Start as an agent. Ship the workflow. Own every run.**
|
|
8
|
+
|
|
9
|
+
`relavium` is the command-line surface of **[Relavium](https://github.com/HodeTech/Relavium)** — a
|
|
10
|
+
local-first, multi-model AI agent platform from **[HodeTech](https://github.com/HodeTech)**. Begin in a
|
|
11
|
+
conversational **agent session** in your terminal, graduate it into a git-committable, multi-agent
|
|
12
|
+
`.relavium.yaml` **workflow**, and run it anywhere — all on the same pure-TypeScript engine that powers
|
|
13
|
+
the Relavium desktop and VS Code surfaces. Every step is debuggable, every token and dollar tracked, and
|
|
14
|
+
nothing leaves your machine unless you choose it.
|
|
9
15
|
|
|
10
16
|
## Install
|
|
11
17
|
|
|
@@ -13,42 +19,118 @@ dollar tracked, nothing leaving your machine unless you choose it.
|
|
|
13
19
|
npm install -g relavium
|
|
14
20
|
```
|
|
15
21
|
|
|
16
|
-
Requires **Node.js ≥ 20.12**. The package
|
|
17
|
-
binaries
|
|
22
|
+
Requires **Node.js ≥ 20.12**. The package is an engine-inlined bundle that installs prebuilt native
|
|
23
|
+
binaries — no C/C++ toolchain, no Python sidecar.
|
|
18
24
|
|
|
19
25
|
## Quick start
|
|
20
26
|
|
|
21
27
|
```bash
|
|
22
|
-
#
|
|
23
|
-
relavium
|
|
28
|
+
# 1 · Point Relavium at a provider — your key goes to the OS keychain, never a file or argv
|
|
29
|
+
relavium provider add anthropic
|
|
30
|
+
echo "$ANTHROPIC_API_KEY" | relavium provider set-key anthropic
|
|
24
31
|
|
|
25
|
-
#
|
|
26
|
-
relavium
|
|
32
|
+
# 2 · Start as an agent — a streaming, multi-turn session in your terminal
|
|
33
|
+
relavium chat
|
|
34
|
+
# …converse until a flow proves itself, then run /export inside the REPL
|
|
35
|
+
# to ship the session to a git-committable .relavium.yaml
|
|
27
36
|
|
|
28
|
-
#
|
|
29
|
-
|
|
37
|
+
# 3 · Own every run — execute the workflow, streaming live (or --json for CI)
|
|
38
|
+
relavium run ./my-workflow.relavium.yaml --input file=./src/index.ts
|
|
39
|
+
relavium run ./my-workflow.relavium.yaml --json
|
|
30
40
|
```
|
|
31
41
|
|
|
42
|
+
Prefer authoring directly? `relavium create` scaffolds an agent or a minimal single-agent workflow from
|
|
43
|
+
an interactive wizard.
|
|
44
|
+
|
|
45
|
+
## Why relavium
|
|
46
|
+
|
|
47
|
+
- **One engine, every surface.** The terminal, desktop, and VS Code run the _identical_ engine — a
|
|
48
|
+
workflow behaves the same on your laptop and in CI.
|
|
49
|
+
- **A chat-to-workflow continuum.** Sessions are persistent and resumable; one command — `/export` —
|
|
50
|
+
turns a proven conversation into a reviewed, committed workflow.
|
|
51
|
+
- **Multi-model with fallback chains.** Route across Anthropic, OpenAI / DeepSeek, and Gemini behind one
|
|
52
|
+
seam; a run survives a provider outage by failing over (`[claude → gpt-4o → gemini]`).
|
|
53
|
+
- **Local-first, keys in your OS keychain.** BYOK, no account, no telemetry — keys never touch a file, a
|
|
54
|
+
log, an argv, or `--json` output.
|
|
55
|
+
- **Live _and_ scriptable.** A rich streaming TUI on a TTY; a stable NDJSON `RunEvent` stream with
|
|
56
|
+
deterministic exit codes under `--json` for CI.
|
|
57
|
+
- **Extensible and multimodal.** Agents consume external **MCP** tools (stdio + `http` / `sse` /
|
|
58
|
+
`websocket`, behind an SSRF floor), and workflows generate image / audio / video **output** through the
|
|
59
|
+
same engine (media input via `read_media` is a tracked follow-up).
|
|
60
|
+
|
|
32
61
|
## Commands
|
|
33
62
|
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
|
37
|
-
|
|
|
38
|
-
| `relavium
|
|
39
|
-
| `relavium
|
|
40
|
-
| `relavium
|
|
41
|
-
| `relavium
|
|
42
|
-
| `relavium
|
|
63
|
+
### Agent sessions
|
|
64
|
+
|
|
65
|
+
| Command | Purpose |
|
|
66
|
+
| --------------------------------------------- | ----------------------------------------------------------- |
|
|
67
|
+
| `relavium chat [--agent <ref>]` | Start an interactive multi-turn agent session (the REPL). |
|
|
68
|
+
| `relavium chat-resume <sessionId>` | Reload and continue a persisted session. |
|
|
69
|
+
| `relavium chat-list` | List past sessions (id, agent, last activity). |
|
|
70
|
+
| `relavium chat-export <sessionId>` | Export a session to a `.relavium.yaml` workflow scaffold. |
|
|
71
|
+
| `relavium agent run <agent> [--fixture <p>]` | Run a single agent one-shot (prompt on **stdin**); `--fixture` replays a cassette (offline, CI-ready). |
|
|
72
|
+
|
|
73
|
+
### Workflows & authoring
|
|
74
|
+
|
|
75
|
+
| Command | Purpose |
|
|
76
|
+
| ------------------------------------ | ----------------------------------------------------------------- |
|
|
77
|
+
| `relavium run <workflow> [--input k=v]` | Execute a workflow — live TUI, or `--json` NDJSON for CI. |
|
|
78
|
+
| `relavium create` | Scaffold a new agent or a minimal workflow from a wizard. |
|
|
79
|
+
| `relavium import <path>` | Import an external `.relavium.yaml` / `.agent.yaml` into the project. |
|
|
80
|
+
| `relavium export <id>` | Write a portable, share-safe copy (no secret material). |
|
|
81
|
+
|
|
82
|
+
### History & human gates
|
|
83
|
+
|
|
84
|
+
| Command | Purpose |
|
|
85
|
+
| ---------------------------------------------------- | ---------------------------------------------------- |
|
|
86
|
+
| `relavium list [--agents]` | List discovered workflows (or agents) + last-run status. |
|
|
87
|
+
| `relavium logs <runId>` | Replay a past run's event stream (raw under `--json`). |
|
|
88
|
+
| `relavium status` | Show active / paused runs and their per-node status. |
|
|
89
|
+
| `relavium gate <runId> --approve\|--reject\|--input …` | Resolve a pending human gate. |
|
|
90
|
+
| `relavium gate list [<runId>]` | List pending human gates across runs. |
|
|
91
|
+
|
|
92
|
+
### Providers & keys
|
|
93
|
+
|
|
94
|
+
| Command | Purpose |
|
|
95
|
+
| -------------------------------- | ---------------------------------------------------------- |
|
|
96
|
+
| `relavium provider list` | Registered providers and whether a key is set. |
|
|
97
|
+
| `relavium provider add <id>` | Register a provider. |
|
|
98
|
+
| `relavium provider set-key <id>` | Store a key in the OS keychain (read from **stdin**). |
|
|
99
|
+
| `relavium provider remove-key <id>` | Delete a key from the keychain. |
|
|
100
|
+
| `relavium provider test <id>` | Verify a key with a minimal live request. |
|
|
101
|
+
|
|
102
|
+
The global flags `--json`, `--cwd`, `--config`, `--no-color`, `--verbose` (`-v`), and `--quiet` (`-q`)
|
|
103
|
+
apply throughout. Run `relavium --help` or `relavium <command> --help` for the full surface.
|
|
104
|
+
|
|
105
|
+
## Exit codes
|
|
106
|
+
|
|
107
|
+
Deterministic, for CI:
|
|
108
|
+
|
|
109
|
+
| Code | Meaning |
|
|
110
|
+
| ---- | --------------------------------------------------------------------- |
|
|
111
|
+
| `0` | Completed successfully |
|
|
112
|
+
| `1` | Workflow failed (a node errored and exhausted retries / fallbacks) |
|
|
113
|
+
| `2` | Invalid invocation (bad arguments, not found, schema error) |
|
|
114
|
+
| `3` | Run paused at a human gate (non-interactive) — resume with `relavium gate` |
|
|
115
|
+
| `4` | A `relavium chat` / `chat-resume` session ended (`/exit`, `/cancel`, or input EOF) |
|
|
116
|
+
|
|
117
|
+
For a workflow run or agent session, `--json` makes stdout a pure NDJSON stream — `RunEvent`s for `run` /
|
|
118
|
+
`gate`, `SessionEvent`s for `chat` / `agent run` — with all diagnostics on stderr. (`--help`, `--version`,
|
|
119
|
+
and a bare invocation stay human-readable on stdout.)
|
|
120
|
+
|
|
121
|
+
## Keys & configuration
|
|
43
122
|
|
|
44
|
-
|
|
45
|
-
|
|
123
|
+
Provider keys resolve **OS keychain → `RELAVIUM_<PROVIDER>_API_KEY` env var → error** — no plaintext
|
|
124
|
+
fallback, and only a 4-character hint is ever displayed. Configuration layers from `~/.relavium/`
|
|
125
|
+
(global) and a project `.relavium/`, with CLI flags and env vars overriding. Run history persists locally
|
|
126
|
+
to `~/.relavium/history.db`.
|
|
46
127
|
|
|
47
128
|
## Documentation
|
|
48
129
|
|
|
49
|
-
The full command reference, the `--json` machine contract, and the CI guide live in the
|
|
50
|
-
[
|
|
130
|
+
The full command reference, the `--json` machine-output contract, and the CI guide live in the Relavium
|
|
131
|
+
docs: **[docs/reference/cli/commands.md](https://github.com/HodeTech/Relavium/blob/main/docs/reference/cli/commands.md)**.
|
|
51
132
|
|
|
52
133
|
## License
|
|
53
134
|
|
|
54
|
-
Proprietary — © HodeTech, all rights reserved.
|
|
135
|
+
Proprietary — © HodeTech, all rights reserved. Not open source; no rights are granted except as expressly
|
|
136
|
+
stated. See **[LICENSE](https://github.com/HodeTech/Relavium/blob/main/LICENSE)**.
|