oomi-ai 0.7.1 → 0.8.0

package/README.md

@@ -123,11 +123,17 @@ Use the SAME connection name from setup. Omit `--name` for default OpenClaw.
 ```bash
 oomi status --name hermes --json
 oomi verify --name hermes
-oomi bridge restart --name hermes --detach
+oomi bridge repair --name hermes
 oomi invite --name hermes --app-url https://www.oomi.ai
 ```
 
-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.
+Do not pair again to refresh an expired Auth Link. Re-running `connect` reuses saved pairing and verification; only the first connection or an explicit `oomi verify` sends a model probe. 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`. Since 0.8.0, `connect` installs a separate automatic-start service for each connection: macOS launchd or Linux systemd user. It restarts an exited worker and starts at the next login/user session. Linux servers can start at boot and remain running after logout when the host administrator enables user lingering (`loginctl enable-linger <user>`); `oomi bridge service status --name hermes` reports whether this is enabled. WSL needs systemd and a running WSL instance; native Windows does not yet have an automatic service installer. A sleeping, powered-off, or disconnected computer remains unavailable.
+
+Run `oomi bridge list` to find saved connection names and their startup protection on this computer. To upgrade an existing connection on **each computer**, install `oomi-ai@latest`, then run `oomi bridge repair --name <existing-name>` (omit the name for default OpenClaw). Repair installs/updates its supervisor, preserves pairing and conversations, and waits for the broker connection. It does not send a model probe or switch agents. Do not copy connection credentials between computers.
+
+Use `oomi bridge service status --name hermes --json` to inspect startup protection. `oomi bridge stop --name hermes` disables automatic startup and stops only that connection; `oomi bridge start --name hermes` enables it again. `oomi bridge service uninstall --name hermes` removes startup management without deleting saved state. The legacy `oomi openclaw bridge service` command remains supported.
+
+For containers or an existing external supervisor, use `connect --no-service` explicitly, then configure that supervisor to run `oomi bridge start --name <name> --service-managed` in the foreground. Detached mode alone does not provide crash/login recovery. Setup fails with an actionable error when the service manager is unavailable; never claim automatic startup in that case. The phone's Reconnect button reconnects the client; it cannot wake a computer or start a missing host process.
 
 `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.
 
@@ -328,7 +334,7 @@ STT works but the assistant does not reply:
 Bridge keeps using an old package after update:
 
 - Action: run `oomi openclaw refresh --skip-version-check`.
-- If still stale: run `oomi openclaw bridge restart --detach`.
+- If still stale: run `oomi bridge repair` for default OpenClaw, or add the existing `--name` for a named connection.
 - On macOS service installs: run `oomi openclaw bridge service restart`.
 - Confirm with `oomi openclaw bridge ps`.
 
@@ -353,6 +359,12 @@ Oomi now stores a primary agent and reliable recurring check-ins. Agents can pro
 
 Run `oomi capabilities` for the command map, `oomi instructions` for the installed guide, and `oomi spaces catalog --connection <name>` for supported components and bindings. Agents create and edit persistent Spaces with `spaces create/update --file`, including from other chats, without asking the user to build UI. User edits and agent writes share revisions and idempotency keys. See the packaged Oomi skill for complete examples, source permissions, layout recovery, and routine authority.
 
+When the live catalog advertises `space.v2`, named `sources` and component `sourceRef` fields connect shared readings, recorded workouts, and separate Fitness completions. Include `schemaVersion:"space.v2"` on every write to such a Space (or `--schema-version space.v2` for flag-only commands). These dependencies update data quietly without changing layout revisions, granting provider permissions, or scheduling reminders. Display periods are independent of goal recurrence.
+
+When the catalog advertises `space.v3`, `oomi objectives list/show/history/create/update/respond` manages reusable daily, selected-day, weekly, monthly and one-time goals. Space `objective` components reference those IDs; optional `streak` components reference matching calendars and count full history. Both clients support creation, manual corrections, older progress, and prospective target/pause changes. Use `schemaVersion:"space.v3"` for these Spaces. The [operator guide](agent_instructions.md#recurring-goals-and-optional-streaks-spacev3) describes authority, calendars, source rules, reminders and retries. This source change has not been published to npm.
+
 For short health answers, use `oomi context health --window week --metric steps --json`; use an explicit date range for calendar weeks. `--output <new-file>` saves full private JSON rather than risking terminal truncation.
 
 Ordinary state events sync quietly and are available through `oomi updates`. Phone reminders work without model turns. Explicit routine `agentWakeEnabled:true` enables a bounded wake path (six attempts/hour, no automatic retry after an uncertain model dispatch). Older bridges receive no wake events. Owner identity edits receive one notice per revision; agent-originated edits do not wake the agent again. Initial setup and explicit `oomi verify` send a test message; unchanged reconnects reuse successful verification, including after a failed pairing attempt. Install/update and restart the selected bridge to use the new workers.
+
+`spaces upgrade ID --file upgrade.json` applies explicit checklist-to-goal, streak and named-source mappings in one revision-checked transaction. It preserves unrelated plan data and never turns undated legacy ticks into dated completions. Goal rules may also use an either/or set of presence sources, for example a recorded workout or a Fitness check-in, counting the period once. Read the live catalog before using new capabilities; source code in this branch does not imply an npm release.

package/agent_instructions.md

@@ -32,14 +32,61 @@ Supported types and binding fields:
 - profile: heightCm, birthDate (YYYY-MM-DD), sex, activityLevel, athleteMode. Ask incrementally only when necessary; do not invent profile facts.
 - routine/streak: routineId returned by the existing routines API. The source remains that routine's real schedule and check-ins. Rendering a component does not activate a routine.
 
-Live source example: `{"id":"steps","type":"chart","title":"Steps this week","dataKey":"steps","source":{"kind":"health","metric":"activity.steps","window":"week","unit":"count"}}`. Health sources use canonical metric names from the catalog and resolve permissioned observations when opened. Body-weight unit may be kg or lb. For the user's shared scale use `source:{kind:"scale",metric:"weight",unit:"lb"}`. The scale shows received capture values; packet stability and measurement time remain unverified. No body-composition values can be inferred from weight alone. Don't present estimates as measurements.
+Live source example: `{"id":"steps","type":"chart","title":"Steps this week","dataKey":"steps","source":{"kind":"health","metric":"activity.steps","window":"week","unit":"count"}}`. Health sources use canonical metric names from the catalog and resolve permissioned observations when opened. Body-weight unit may be kg or lb. For the user's shared scale use `source:{kind:"scale",metric:"weight",unit:"lb"}`. The scale prefers accepted stable weigh-ins; older manually shared captures remain labelled separately. The timestamp is phone receipt time, not a verified scale measurement time. No body-composition values can be inferred from weight alone. Don't present estimates as measurements.
 
 Removing a component keeps its binding data and revision history. Use `oomi spaces revisions ID` and `oomi spaces restore ID --file restore.json` with `{expectedRevision,restoreRevision,idempotencyKey}` to restore layout without rolling back saved values. Archive/unarchive is reversible. Spaces never execute scripts, HTML, or agent-provided code; unsupported components require an Oomi renderer update.
 
 Creating a Space does not authorize health access, identity-file backup, push messages, or schedules. For a requested routine, use the existing routine proposal/commit commands and authenticated sourceMessageId or previously granted externalInstruction permission. When the user says to revise and set it, commit all changes together; the resolved review card disappears. Don't make them repeat the instruction in the UI. The primary agent normally coordinates; specialists keep their own assigned Spaces.
 
+### Recurring goals and optional streaks (space.v3)
+
+Use the live catalog to confirm support, then `oomi objectives list` and `oomi objectives show ID` before adding another goal. Goals belong to the account and may be reused across Spaces. Keep the existing `goal` card for numeric milestones; use an `objective` component for a recurring rule. A plain checklist does not reset or create completion history.
+
+Create with `oomi objectives create --file goal.json`. Example shape only; choose dates, calendar, target and source from the user's request rather than creating this example:
+```json
+{
+  "title": "Reading practice",
+  "idempotencyKey": "unique-goal-create-request",
+  "calendar": {"period":"daily","timezone":"America/Chicago","startsOn":"YYYY-MM-DD","weekdays":[1,2,3,4,5]},
+  "definition": {"source":{"kind":"manual","unit":"chapters"},"comparison":"gte","target":1}
+}
+```
+
+Calendars support daily (optionally selected weekdays, 1=Monday), weekly (weekStartsOn defaults to Monday), monthly, and once (endsOn required). Time zone and calendar stay fixed through travel. A different calendar requires a new goal. Targets/rules/pause changes take effect next period, leaving past and current progress intact. A future one-time goal may change before starting; once started, correct its progress or create another goal.
+
+Sources may be manual, an existing routine (`{kind:"routine",routineId:"returned ID",operation:"count"}`), or a supported observation/workouts/fitness configuration without window/timezone. The calendar supplies its evaluation window. Daily weigh-in uses observation/body.mass_kg/presence/target 1; weekly recorded workouts uses workouts/workout/count and the requested target. Fitness is user-reported and remains separate from sensor workouts. Daily activity totals imported in a different time zone are unknown for this goal, not rebinned or invented. Sources need existing permission; creating goals never grants it.
+
+For either/or completion use `{kind:"any",sources:[{kind:"workouts",metric:"workout",operation:"presence"},{kind:"fitness",metric:"completion",operation:"presence"}]}` with comparison `gte` and target `1`. Use 2–5 presence sources (observation, workouts, Fitness, or an existing routine). One period counts once even if several sources match; this does not add workout counts across providers. Nested combinations and manual sources inside this rule are unsupported.
+
+Add components using the returned goal ID, preserving all other components and bindings:
+```json
+{"schemaVersion":"space.v3","expectedRevision":1,"idempotencyKey":"unique-space-update-request","components":[{"id":"practice","type":"objective","title":"Reading practice","dataKey":"practice","objectiveId":"RETURNED_OBJECTIVE_ID"},{"id":"practiceStreak","type":"streak","title":"Practice streak","dataKey":"practiceStreak","objectiveIds":["RETURNED_OBJECTIVE_ID"],"match":"all"}]}
+```
+
+Send space.v3 on every write/restore/archive of a Space containing these references. The CLI supplies the space.v3 read header; older clients show an update message and cannot discard newer definitions. Removing a card preserves the objective and history. Never save resolvedBindings back into bindings.
+
+For requested changes use `oomi objectives update ID --file change.json` with expectedRevision, stable idempotencyKey, and only the changed title/definition/reminderRoutineId. A definition is replaced as a whole: preserve the source/comparison/target/status not being changed. Set definition.status to active/paused. An optional reminderRoutineId links an existing authorized routine, creates no schedule, and automatically suppresses its reminder once the goal is complete. One routine can follow one goal. A routine-backed goal may link that same routine as its reminder, but not a different routine. Automatic reminder completion is excluded from source evidence so it cannot complete its own goal indefinitely. Create/activate any new reminder through the established routine authority flow.
+
+For a person's progress correction use `oomi objectives respond ID --file response.json` with expectedRevision, expectedPeriodRevision, periodKey (all from the latest read), action record/incomplete/skip/reset, and a stable idempotencyKey. Record also requires numeric value; optional note is at most 500 characters. Agent-recorded progress requires sourceMessageId from the authenticated Oomi owner message. The external routine permission does not authorize generic goal responses. Existing routine and Fitness actions still use their own action APIs; goals consume that evidence. Never fabricate completed actions. Corrections persist until reset (return to source data, or clear a manual entry). On uncertain failure retry the identical key/body; after a definite revision conflict read current state and make a new request.
+
+`show` contains the last 31 periods; `oomi objectives history ID [--before YYYY-MM-DD]` pages 100 older periods using nextCursor. Full stored history drives current/best streaks, not the seven visible dots. A streak can use 1–10 goals with identical recurring calendars, matching all or any. Rest, skip and pause add no success and do not break an individual streak; an open period is not missed. Skipping one grouped goal does not hide another missed goal. Missing evidence is unknown; unavailable access hides progress. Late source changes/corrections reconcile earlier periods. Existing routine-only streak cards remain compatible and retain their older history limit; migrate explicitly when requested.
+
+### Upgrade an existing Space without losing its plan
+
+Read the Space and its existing routines first. If the catalog advertises `upgrade`, use `oomi spaces upgrade ID --file upgrade.json` to apply explicit source and goal mappings atomically. Supply `expectedRevision`, a stable `idempotencyKey`, optional named `sources`, optional `sourceBindings:{"EXISTING_COMPONENT_ID":"SOURCE_NAME"}`, and an `objectives` array. Each entry requires a distinct stable `key`, `title`, `calendar`, and `definition` in the usual goal format. Optional fields:
+- `checklistItem:{componentId,itemId}` removes exactly that legacy checklist item.
+- `componentId` chooses the new goal card ID; `replaceComponent:true` explicitly replaces an existing section.
+- `reminderRoutineId` links an existing authorized reminder.
+- `streakComponentIds:["EXISTING_STREAK_ID"]` converts selected streaks to the new goal.
+
+All mappings must succeed or nothing changes. Retry the identical body/key after an uncertain response. A conflict requires a fresh read and new request key. Preserve user targets, notes, profiles, unrelated bindings and source permissions. Existing undated checklist ticks are retained in revision history, never invented as dated completions. Use this only for a requested upgrade; do not infer recurrence or health targets from vague prose. Restore an earlier layout with the existing revision API; created account goals and their history remain available.
+
 ### Health questions without oversized output
 
+The iPhone synchronizes available Apple Health history in durable pages keyed by sample UUID, then tracks additions and explicit deletions. A cursor advances only after Oomi saves the page and its affected daily totals. Interrupted imports resume on foreground or a later health update. Apple does not reveal read denials: an empty query is unknown, not zero or proof of deletion. Provider permissions and Oomi's sharing switch still apply. Physical HealthKit/background-delivery acceptance is separate from simulator and synthetic checks.
+
+Scale readings belong to the account even without a Space. Query them with `oomi context health --window week --provider smart_scale --json`; use `--provider apple_health` to restrict Apple Health or `all` (the history default) for permitted providers. Follow `healthHistory.agentGuidance` for these queries independently of Apple Health current-context availability. A missing source is unknown, never zero. Automatic scale sync must be enabled on the phone; agents cannot grant it.
+
 For a rolling seven days: `oomi context health --window week --metric steps --json`.
 For a previous calendar week: determine dates in the user's time zone, then `oomi context health --window range --from YYYY-MM-DD --to YYYY-MM-DD --metric steps --json`.
 Use `--metric weight`, `--metric sleep`, or a canonical metric as needed. Preserve coverage, dates, units, missing days, and today's partial count. Don't label a rolling window as a calendar week. For large/raw responses use `--output /absolute/path/new-health.json`; the CLI writes private, complete JSON to a new file and prints a small receipt. Never try to parse a terminal-truncated response as if it were the original JSON. Read existing permitted history before asking the user to sync. Request a phone sync only when current data is needed; don't repeatedly poll an offline phone.
@@ -129,11 +176,17 @@ Use the SAME connection name from setup. Omit `--name` for default OpenClaw.
 ```bash
 oomi status --name hermes --json
 oomi verify --name hermes
-oomi bridge restart --name hermes --detach
+oomi bridge repair --name hermes
 oomi invite --name hermes --app-url https://www.oomi.ai
 ```
 
-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.
+Do not pair again to refresh an expired Auth Link. Re-running `connect` reuses saved pairing and verification; only the first connection or an explicit `oomi verify` sends a model probe. 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`. Since 0.8.0, `connect` installs a separate automatic-start service for each connection: macOS launchd or Linux systemd user. It restarts an exited worker and starts at the next login/user session. Linux servers can start at boot and remain running after logout when the host administrator enables user lingering (`loginctl enable-linger <user>`); `oomi bridge service status --name hermes` reports whether this is enabled. WSL needs systemd and a running WSL instance; native Windows does not yet have an automatic service installer. A sleeping, powered-off, or disconnected computer remains unavailable.
+
+Run `oomi bridge list` to find saved connection names and their startup protection on this computer. To upgrade an existing connection on **each computer**, install `oomi-ai@latest`, then run `oomi bridge repair --name <existing-name>` (omit the name for default OpenClaw). Repair installs/updates its supervisor, preserves pairing and conversations, and waits for the broker connection. It does not send a model probe or switch agents. Do not copy connection credentials between computers.
+
+Use `oomi bridge service status --name hermes --json` to inspect startup protection. `oomi bridge stop --name hermes` disables automatic startup and stops only that connection; `oomi bridge start --name hermes` enables it again. `oomi bridge service uninstall --name hermes` removes startup management without deleting saved state. The legacy `oomi openclaw bridge service` command remains supported.
+
+For containers or an existing external supervisor, use `connect --no-service` explicitly, then configure that supervisor to run `oomi bridge start --name <name> --service-managed` in the foreground. Detached mode alone does not provide crash/login recovery. Setup fails with an actionable error when the service manager is unavailable; never claim automatic startup in that case. The phone's Reconnect button reconnects the client; it cannot wake a computer or start a missing host process.
 
 `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.
 
@@ -254,7 +307,7 @@ oomi context health --json
 
 Rules:
 
-- Answer only from `healthContext.summary` and `healthContext.derived`.
+- Answer current Apple Health questions from `healthContext.summary` and `healthContext.derived`. Answer historical or scale queries from `healthHistory.summary` and `healthHistory.series`, respecting their provider permissions and coverage.
 - Respect `healthContext.agentGuidance.canAnswerFromContext`.
 - If `healthContext.agentGuidance.recommendedCommand` is present, run it before answering current/latest health questions.
 - If `healthContext.status` is `stale` or `needs_sync`, run `oomi context health sync --wait --json`; answer only after fresh context is uploaded, or tell the user the phone sync is still pending if it times out.
@@ -271,12 +324,15 @@ To reach the user on their phone when they are not in the conversation, send a p
 oomi notify "Your 7-day plan is ready. Want to look now?" --title "Fitness" --json
 ```
 
+Add `--connection NAME` when you run it outside an Oomi conversation (for example from a scheduled job). Turns Oomi starts already set `OOMI_CONNECTION`. Omit it for the default OpenClaw connection.
+
 Rules:
 
 - Notify only for things worth interrupting the user for: a reminder they asked for, a finished task, or something time-sensitive. Say everything else in chat.
 - Keep the message short and specific. The title defaults to your agent name.
 - Tapping the notification opens the Oomi app to the conversation, where the message also appears.
-- Messages you send the user on the Oomi channel already notify their phone. Do not also run `oomi notify` for the same message.
+- Replies to the user's own Oomi messages, and OpenClaw sends on the Oomi channel, already notify their phone. Do not also run `oomi notify` for the same message.
+- Anything you start on your own, such as a reminder or finished background work, needs `oomi notify`. Hermes agents have no other way to reach the phone.
 - If `notification.status` is `skipped`, tell the user `notification.guidance` instead of retrying.
 - If the request is rate limited, do not retry until `retryAfterSeconds` has passed.