oomi-ai 0.3.8 → 0.4.0

package/README.md

@@ -1,12 +1,12 @@
 # oomi-ai
 
-Managed Oomi channel, bridge, voice, and persona app API tooling for OpenClaw.
+Connect OpenClaw, Hermes, and other local agents to Oomi through an explicit runtime adapter.
 
-`oomi-ai` connects an OpenClaw machine to Oomi. Persona UI creation and rendering happen inside Oomi-managed systems. The OpenClaw machine uses API actions only.
+`oomi-ai` connects the selected local agent to Oomi. Persona UI creation and rendering happen inside Oomi-managed systems. The OpenClaw machine uses API actions only.
 
 The current model is:
 
-- OpenClaw talks to Oomi through managed channel and bridge APIs.
+- The selected agent talks to Oomi through managed channel and bridge APIs.
 - Oomi clients render persona apps from approved templates, components, data bindings, actions, and permissions.
 - The agent may inspect and update persona app state through approved Oomi API actions.
 - The user adds persona apps from the Oomi client so platform permissions and data hydration happen in the right place.
@@ -44,75 +44,77 @@ Persona UI is an Oomi-managed client capability, not an OpenClaw-machine respons
 
 This package exposes connection, bridge, voice, and persona app state APIs. It does not include a local persona app workspace, local persona runtime manager, queued UI job runner, or app framework bundle.
 
-## Install And Upgrade
+## Connect Your Local Agent
 
-Global install:
+Connect the agent the user is speaking to. Identify your runtime and profile first. Never choose OpenClaw merely because it is installed on the same machine as Hermes.
 
-```bash
-pnpm add -g oomi-ai@latest
-```
+## Standard Connect Flow
 
-Fallback:
+Install or update the local package:
 
 ```bash
 npm install -g oomi-ai@latest
 ```
 
-Install or update the OpenClaw plugin:
+Run ONE command for your runtime:
 
 ```bash
-openclaw plugins install oomi-ai@latest
-```
+# OpenClaw (reuses existing default OpenClaw pairing)
+oomi connect --runtime openclaw --app-url https://www.oomi.ai
 
-After upgrading, refresh the running bridge so stale gateway connections do not keep using the previous package:
+# Hermes (separate connection, no OpenClaw required)
+oomi connect --runtime hermes --name hermes --app-url https://www.oomi.ai
 
-```bash
-oomi openclaw refresh --skip-version-check
-oomi openclaw bridge ps
+# Another local agent, through its own adapter
+oomi connect --runtime command --name my-agent --command '["/absolute/path/to/adapter"]' --app-url https://www.oomi.ai
 ```
 
-If the bridge still looks stale, restart it explicitly:
+Use the user's app URL when provided. Hermes supports `--profile <profile>` and `--resume <exact-session-id>`. Without `--resume`, Oomi starts a persistent conversation with the same configured agent. Do not use `latest` or claim that an existing chat session was transferred unless its exact ID was selected. Hermes uses `chat --quiet --query-file -`, reads the final reply from stdout and the exact `session_id` from stderr, and resumes that ID on subsequent turns.
 
-```bash
-oomi openclaw bridge restart --detach
-oomi openclaw bridge ps
-```
+The command verifies a real local reply, reuses saved credentials or pairs once, starts the bridge, waits for Oomi's subscription, then creates a single-use Auth Link. Failed verification means setup is incomplete: repair the selected runtime, never substitute a different one.
 
-On macOS supervised installs:
+The installer is an alternative to npm plus connect, and requires an explicit runtime:
 
 ```bash
-oomi openclaw bridge service restart
-oomi openclaw bridge service status
+curl -fsSL https://www.oomi.ai/install.sh | bash -s -- --runtime hermes --name hermes
 ```
 
-Healthy update expectation:
+## Required User-Facing Result
 
-- exactly one bridge worker is active
-- the worker reports the newly installed package version
-- bridge status reaches `connected`
+Return the verified runtime/profile and the printed Auth Link. The human opens the link, signs in, and approves ownership. Only after a message receives a reply in Oomi can you claim end-to-end delivery works. Never expose raw tokens, pairing codes, or gateway credentials.
 
-## Standard Connect Flow
+## Repair and Reconnect
 
-Pair the machine:
+Use the SAME connection name from setup. Omit `--name` for default OpenClaw.
 
 ```bash
-oomi openclaw pair --app-url https://www.oomi.ai --no-start
+oomi status --name hermes --json
+oomi verify --name hermes
+oomi bridge restart --name hermes --detach
+oomi invite --name hermes --app-url https://www.oomi.ai
 ```
 
-Print the OpenClaw config:
+Do not pair again to refresh an expired Auth Link. Re-running `connect` reuses the saved pairing and verifies the runtime again. A different command, profile, or working directory requires a new connection name, so one agent cannot silently replace another. Named connections store private state and logs under `~/.oomi/connections/<name>`; default OpenClaw keeps `~/.openclaw`. A detached worker requires the computer to remain awake and does not start automatically after reboot. Configure the host's process supervisor when persistence across reboot is needed.
 
-```bash
-oomi openclaw plugin --show-secrets --backend-url https://api.oomi.ai
-```
+`connected` describes the broker transport. Inspect `runtimeReady`, `verifiedAt`, and `lastReplyAt` separately. A process ID, Auth Link, or broker connection alone does not prove the agent is answering.
 
-Apply the printed `channels.oomi.accounts.default` config and restart OpenClaw.
+## Other Runtime Adapter Contract
 
-Start or repair the bridge:
+`--command` is a JSON argv array, not a shell command. Write an adapter against the selected agent's documented API or noninteractive CLI. The executable reads one JSON object from stdin:
 
-```bash
-oomi openclaw bridge ensure --detach
+```json
+{"sessionKey":"...","message":"...","idempotencyKey":"...","history":[],"runtimeSessionId":"..."}
 ```
 
+It writes `{"text":"final reply","sessionId":"optional-runtime-session"}` to stdout and exits zero on success. Errors must exit nonzero; diagnostics go to stderr. Resume `runtimeSessionId`, or use `history` for stateless runtimes. Never bypass the agent's existing approval rules. The adapter supports text (including voice transcripts); attachments are rejected explicitly. A failed or interrupted action is not silently repeated. Check the agent before sending a new message after a failure.
+
+## OpenClaw Channel Extension
+
+Managed web text and voice connect through the local gateway. The optional OpenClaw `oomi-ai` channel plugin handles agent-initiated channel output. If you need that path, install the plugin, enable its entry in OpenClaw, apply `oomi openclaw plugin --show-secrets --backend-url https://api.oomi.ai` locally, and restart OpenClaw. Never share that secret config with the user. Disabling the plugin does not explain a gateway protocol rejection.
+
+OpenClaw gateway protocols 3 and 4 are negotiated independently of the broker. For an existing install affected by a protocol mismatch, update `oomi-ai`, then run `oomi connect --runtime openclaw --app-url https://www.oomi.ai`.
+
+
 ## Configuration
 
 OpenClaw channel config lives under:
@@ -206,6 +208,15 @@ Use context tools when the user asks a data-backed question that should come fro
 oomi context health --json
 ```
 
+Clients built from the health-history revision also support stored date ranges:
+
+```bash
+oomi context health --window year --date 2025-06-01 --group-by month --json
+oomi context health --window all --shape summary --json
+```
+
+For these queries, follow `healthHistory.agentGuidance` and use `healthHistory.summary` or `series`. Stored history remains usable while the phone is offline; missing days are unknown. See the [health-history guide](../../docs/2026-09-28-health-history-and-agent-parity.md) for custom ranges and pagination.
+
 Rules for agents:
 
 - Answer from `healthContext.summary` and `healthContext.derived`.
@@ -258,7 +269,7 @@ tail -f ~/.openclaw/logs/gateway.err.log
 Bridge status meanings:
 
 - `starting`: bridge booting or waiting for managed subscription
-- `connected`: ready for managed chat and voice traffic
+- `connected`: subscribed to the Oomi broker; inspect `runtimeReady` and verify a real reply separately
 - `reconnecting`: transport dropped and retry is scheduled
 - `degraded`: bridge caught a runtime fault but is still alive
 - `error`: startup or auth failure blocked useful operation

package/agent_instructions.md

@@ -1,174 +1,72 @@
-# Oomi OpenClaw Operator Guide
+# Oomi Local Agent Operator Guide
 
-Use these instructions when you need to connect, repair, or verify an OpenClaw machine that should talk to Oomi.
-
-This package is for managed Oomi connectivity. Persona UI creation and rendering happen inside Oomi-managed systems. The OpenClaw machine uses API actions only.
-
-## Primary Goal
-
-Get OpenClaw into a state where:
-
-- Oomi managed text chat works
-- Oomi device-backed voice can start cleanly
-- the bridge is supervised or restartable
-- component-composed persona apps can be inspected and updated through Oomi API tools
-- approved user context, such as HealthKit data synced by the Oomi mobile app, can be read through Oomi backend context tools
-- the user never has to paste raw pair identifiers or gateway secrets manually when managed connect is available
+Connect the agent the user is speaking to. Identify your runtime and profile first. Never choose OpenClaw merely because it is installed on the same machine as Hermes.
 
 ## Standard Connect Flow
 
-If the user asks to connect OpenClaw to Oomi chat or voice:
-
-1. For a first-time install or missing local pairing state, run the bootstrap exactly once using the requested app URL:
-   - `curl -fsSL https://www.oomi.ai/install.sh | bash`
-   - The bootstrap installs or updates `oomi-ai`, performs the one initial pair, installs the plugin, and starts the saved bridge in detached mode.
-   - Do not pair again after the bootstrap finishes.
-2. Print the config block and secrets:
-   - `oomi openclaw plugin --show-secrets --backend-url https://api.oomi.ai`
-3. Apply the printed `channels.oomi.accounts.default` config.
-4. Restart OpenClaw.
-5. Start or repair the bridge from saved pairing state:
-   - `oomi openclaw bridge ensure --detach`
-   - if stale: `oomi openclaw bridge restart --detach`
-   - on macOS, prefer supervision: `oomi openclaw bridge service install`
-6. If the Auth Link printed by bootstrap is missing or expired, create a replacement without re-pairing:
-   - `oomi openclaw invite --app-url https://www.oomi.ai`
-
-If the machine is already paired, do not rerun bootstrap. Use `invite` for a fresh Auth Link and `bridge ensure` or `bridge restart` for runtime recovery.
-
-If the user provides a specific app URL, substitute it in both the bootstrap URL and the `invite --app-url` command.
-
-## Required User-Facing Result
-
-When pairing completes successfully, return this exact format:
-
-- `Oomi Connect Ready`
-- `Auth Link: ...`
-
-Do not add extra narrative before or after those lines.
-Do not ask the user to enter raw pair codes, gateway passwords, or nonce values manually.
-
-## Update And Stale Bridge Repair
-
-After updating `oomi-ai`, always make sure the running bridge is not still using an old package or dead gateway connection.
-
-Preferred update flow:
+Install or update the local package:
 
 ```bash
-pnpm add -g oomi-ai@latest
-openclaw plugins install oomi-ai@latest
-oomi openclaw refresh --skip-version-check
-oomi openclaw bridge ps
+npm install -g oomi-ai@latest
 ```
 
-If the bridge is stale, disconnected, duplicated, or reporting the wrong version:
+Run ONE command for your runtime:
 
 ```bash
-oomi openclaw bridge restart --detach
-oomi openclaw bridge ps
-```
+# OpenClaw (reuses existing default OpenClaw pairing)
+oomi connect --runtime openclaw --app-url https://www.oomi.ai
 
-On macOS supervised installs:
+# Hermes (separate connection, no OpenClaw required)
+oomi connect --runtime hermes --name hermes --app-url https://www.oomi.ai
 
-```bash
-oomi openclaw bridge service restart
-oomi openclaw bridge service status
+# Another local agent, through its own adapter
+oomi connect --runtime command --name my-agent --command '["/absolute/path/to/adapter"]' --app-url https://www.oomi.ai
 ```
 
-Healthy result:
+Use the user's app URL when provided. Hermes supports `--profile <profile>` and `--resume <exact-session-id>`. Without `--resume`, Oomi starts a persistent conversation with the same configured agent. Do not use `latest` or claim that an existing chat session was transferred unless its exact ID was selected. Hermes uses `chat --quiet --query-file -`, reads the final reply from stdout and the exact `session_id` from stderr, and resumes that ID on subsequent turns.
 
-- one bridge worker is active
-- bridge status reaches `connected`
-- the bridge version matches the newly installed package
+The command verifies a real local reply, reuses saved credentials or pairs once, starts the bridge, waits for Oomi's subscription, then creates a single-use Auth Link. Failed verification means setup is incomplete: repair the selected runtime, never substitute a different one.
 
-## Runtime Checks
-
-Use these commands to inspect the installed machine:
+The installer is an alternative to npm plus connect, and requires an explicit runtime:
 
 ```bash
-oomi openclaw bridge ps
-oomi openclaw bridge service status
-oomi openclaw status
-tail -f ~/.openclaw/logs/oomi-bridge-live.log
-tail -f ~/.openclaw/logs/gateway.log
-tail -f ~/.openclaw/logs/gateway.err.log
+curl -fsSL https://www.oomi.ai/install.sh | bash -s -- --runtime hermes --name hermes
 ```
 
-Useful local files:
-
-- `~/.openclaw/oomi-bridge-status.json`
-- `~/.openclaw/logs/oomi-bridge-live.log`
-- `~/.openclaw/logs/gateway.log`
-- `~/.openclaw/logs/gateway.err.log`
-- `~/.openclaw/agents/main/sessions/*.jsonl`
-
-## Healthy State
-
-Treat the machine as healthy when all of the following are true:
-
-- OpenClaw loads the `oomi-ai` plugin without duplicate-id conflicts
-- `channels.oomi.accounts.default` is populated with a valid `backendUrl` and `deviceToken`
-- the bridge shows `connected` after managed subscription is confirmed
-- text chat reaches the Oomi assistant
-- voice STT can produce `asr.final`
-- assistant replies can come back without the bridge dropping into `stopped`
-
-Bridge status meanings:
-
-- `starting`: bridge booting or waiting for managed subscription
-- `connected`: ready for managed chat and voice traffic
-- `reconnecting`: transport dropped and retry is scheduled
-- `degraded`: bridge caught a runtime fault but is still alive
-- `error`: startup or auth failure blocked useful operation
-- `stopped`: not running or intentionally stopped
-
-## Troubleshooting
-
-### Duplicate plugin id warning
-
-Symptom:
-
-- OpenClaw reports `duplicate plugin id detected`
-
-Action:
-
-- ensure only one active `oomi-ai` plugin install is discoverable
-- remove stale extension copies before reinstalling
-
-### `invalid handshake: first request must be connect`
-
-Meaning:
+## Required User-Facing Result
 
-- a gateway request was sent before `connect` had been accepted
+Return the verified runtime/profile and the printed Auth Link. The human opens the link, signs in, and approves ownership. Only after a message receives a reply in Oomi can you claim end-to-end delivery works. Never expose raw tokens, pairing codes, or gateway credentials.
 
-Action:
+## Repair and Reconnect
 
-- update `oomi-ai`
-- restart the bridge
-- confirm only one bridge worker is running
+Use the SAME connection name from setup. Omit `--name` for default OpenClaw.
 
-### Device is linked but voice start still fails
+```bash
+oomi status --name hermes --json
+oomi verify --name hermes
+oomi bridge restart --name hermes --detach
+oomi invite --name hermes --app-url https://www.oomi.ai
+```
 
-Meaning:
+Do not pair again to refresh an expired Auth Link. Re-running `connect` reuses the saved pairing and verifies the runtime again. A different command, profile, or working directory requires a new connection name, so one agent cannot silently replace another. Named connections store private state and logs under `~/.oomi/connections/<name>`; default OpenClaw keeps `~/.openclaw`. A detached worker requires the computer to remain awake and does not start automatically after reboot. Configure the host's process supervisor when persistence across reboot is needed.
 
-- linked ownership is not enough; the device side still needs to be live
+`connected` describes the broker transport. Inspect `runtimeReady`, `verifiedAt`, and `lastReplyAt` separately. A process ID, Auth Link, or broker connection alone does not prove the agent is answering.
 
-Action:
+## Other Runtime Adapter Contract
 
-- confirm the device websocket is actually online
-- confirm the bridge is `connected`
-- restart the bridge if it is stuck in `reconnecting` or `degraded`
+`--command` is a JSON argv array, not a shell command. Write an adapter against the selected agent's documented API or noninteractive CLI. The executable reads one JSON object from stdin:
 
-### STT works but the assistant does not reply
+```json
+{"sessionKey":"...","message":"...","idempotencyKey":"...","history":[],"runtimeSessionId":"..."}
+```
 
-Meaning:
+It writes `{"text":"final reply","sessionId":"optional-runtime-session"}` to stdout and exits zero on success. Errors must exit nonzero; diagnostics go to stderr. Resume `runtimeSessionId`, or use `history` for stateless runtimes. Never bypass the agent's existing approval rules. The adapter supports text (including voice transcripts); attachments are rejected explicitly. A failed or interrupted action is not silently repeated. Check the agent before sending a new message after a failure.
 
-- the voice turn likely reached Oomi, but the managed gateway or OpenClaw run failed later
+## OpenClaw Channel Extension
 
-Action:
+Managed web text and voice connect through the local gateway. The optional OpenClaw `oomi-ai` channel plugin handles agent-initiated channel output. If you need that path, install the plugin, enable its entry in OpenClaw, apply `oomi openclaw plugin --show-secrets --backend-url https://api.oomi.ai` locally, and restart OpenClaw. Never share that secret config with the user. Disabling the plugin does not explain a gateway protocol rejection.
 
-- inspect `gateway.log`, `gateway.err.log`, and the session JSONL
-- check for `network_error`, auth failures, repeated bridge restarts, or stale package versions
+OpenClaw gateway protocols 3 and 4 are negotiated independently of the broker. For an existing install affected by a protocol mismatch, update `oomi-ai`, then run `oomi connect --runtime openclaw --app-url https://www.oomi.ai`.
 
 ## Voice Notes