sidebud 0.2.0 → 0.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sidebud",
-  "version": "0.2.0",
+  "version": "0.5.0",
   "description": "Sidebud companion: talk to the agents on your computer from your phone.",
   "keywords": [
     "sidebud",
@@ -33,9 +33,11 @@
     "@modelcontextprotocol/sdk": "^1.30.0",
     "@noble/curves": "^2.0.1",
     "@noble/hashes": "^2.0.1",
+    "@sentry/node": "10.75.3",
     "diff": "^8.0.4",
     "qrcode": "^1.5.4",
     "ws": "^8.18.3",
+    "yaml": "^2.9.1",
     "zod": "^4.5.4"
   }
 }

package/skills/widget-packs/SKILL.md

@@ -20,7 +20,7 @@ A pack folder holds:
 
 1. **Find the server.** Prefer an MCP server that already exists: the app's own (`hermes mcp serve`, `openclaw mcp serve`), the vendor's hosted endpoint, or a maintained community server. Note its transport (a stdio command, or an HTTP URL) and credentials: an API key is a pack **secret**; OAuth is an `auth` block; files on disk are a **setting** holding the path.
 2. **If none exists, write one** in `server/` (see [Writing a pack server](#writing-a-pack-server)). Wrap a CLI or a local API; keep it small and read-mostly.
-3. **Draft in a working folder** the user owns (for example `~/sidebud-packs/<name>/`): `pack.json` with identity and `mcp` only, then `packs__probe` to list the server's tools with their read-only hints and input schemas.
+3. **Draft in a working folder** the user owns (for example `~/sidebud-packs/<name>/`): `pack.json` with identity and `mcp` only, then `packs__probe` to list the server's tools with their read-only hints and input schemas. Declare **every** tool it lists in `permissions.tools`, not only the ones the widget uses: the owner sees everything the pack can do, and the fast path and the execution agent can then use any of it. `packs__preview` and the connection check report tools the pack leaves out.
 4. **Look at real results.** `packs__try` calls one read-only tool and returns the result, so you map the shape you actually get.
 5. **Map results onto the UI library**: up to two glance stats (or one line), detail blocks, an optional tapped-row detail, spoken updates, and controls. Templates are lookups (below).
 6. **See it as the phone will.** `packs__preview` validates the draft, runs its data queries against its server, and renders the widget exactly as the phone receives it. It returns a text rendering of the tile and every block, any query errors, and `previewUrl`: the companion's **Phone preview** page showing the draft first on the phone's home screen, beside the draft opened. Open `previewUrl` with your browser tools and look at it (a screenshot shows both phones at once). Or give the link to the user when they want to see it. Fix what looks wrong (empty lists, raw ids, cut-off titles, statuses on every row, the wrong tile size) and preview again after each change, until it reads well at a glance.
@@ -43,26 +43,26 @@ A pack folder holds:
 | `name`, `description`, `version`, `author`, `license` | Shown before install. `version` is semver. |
 | `logo` | `{ "kind": "icon", "name": "tools" }` (agents, mail, calendar, chat, code, github, files, chart, bell, bolt, globe, home, music, note, star, tools), `{ "kind": "emoji", "value": "💾" }`, or `{ "kind": "file", "path": "logo.png", "source": "https://…" }`. For a pack that wraps an app, use the app's own logo: download it from its official site or repository (its app icon or favicon), save it in the pack, and set `source` to where it came from. The file is what is shown; the phone never loads the link. |
 | `tile.size` | `small` (1×1), `medium` (2×1), or `large` (2×2); users can resize. |
-| `mcp` | `{ "transport": "stdio", "command", "args", "env" }` or `{ "transport": "http", "url", "headers" }`. Commands run in the pack folder, so a pack server is `"command": "node", "args": ["server/index.mjs"]`. `args`, `env`, and `headers` may use `{{setting.x}}`, `{{secret.NAME}}`, `{{env.NAME}}`, and `{{oauth.accessToken}}`. |
+| `mcp` | `{ "transport": "stdio", "command", "args", "env" }` or `{ "transport": "http", "url", "headers" }`. Commands run in the pack folder, so a pack server is `"command": "node", "args": ["server/index.mjs"]`. `args`, `env`, and `headers` may use `{{setting.x}}`, `{{secret.NAME}}`, `{{env.NAME}}`, and `{{oauth.accessToken}}`. An http `url` may be a setting plus a path, `"{{setting.baseUrl}}/api/mcp"`, for a server on the user's own network. |
 | `platforms` | A different launch per OS: `{ "win32": { …launch… }, "darwin": …, "linux": … }`. Use it when an app installs to different places, e.g. `{{env.LOCALAPPDATA}}\\Programs\\…` on Windows. |
 | `auth` | OAuth 2.0: `authorizationUrl`, `tokenUrl`, `scopes`, `clientIdSecret`, optional `clientSecretSecret` (both declared in `secrets`), `authorizationParams`. The companion runs consent on this computer, keeps tokens in the keychain, and refreshes them. An http server gets `Authorization: Bearer`; a stdio server must read `{{oauth.accessToken}}` from its `env` and is restarted when the token refreshes. |
 | `secrets` | `[{ "name": "API_KEY", "description": "…" }]`: names only; values live in the keychain. |
-| `permissions.tools` | **Every** tool the pack may call, with `access: read \| write`, optional `description`, and optional `argumentSettings` (`{ "repo": "repo" }` pins that argument to a required setting on every call). Nothing else is ever called. `permissions.network` lists hosts, for review. |
-| `settings` | `text`, `boolean`, or `select` fields with defaults; `required` and `format` (`directory`, `http-url`) for text. |
+| `permissions.tools` | **Every** tool the server offers (nothing undeclared is ever called, and a pack that leaves some out fails its connection check), with `access: read \| write`, optional `description`, and optional `argumentSettings` (`{ "repo": "repo" }` pins that argument to a required setting on every call), and `optional: true` for a tool the server offers only in some setups (for example only when the user has that kind of device), so checking the connection does not require it. A server whose tool list depends on the user's setup (one tool per device kind or user script) sets `permissions.toolsVary: true` and declares the tools every setup has; the ones it adds are never called. Nothing else is ever called. `permissions.network` lists hosts, for review. `permissions.reach` declares what the pack reaches beyond its tools, shown first when someone adds or turns it on: `computer` when its tools start agents, run commands, or otherwise act anywhere on the computer (an agents app, a shell, computer control); `files` for the user's files; `messages` for messages it reads or sends as the user; `devices` for home devices. Declare every one that applies; understating it gets a pack rejected in library review. |
+| `settings` | `text`, `boolean`, or `select` fields with defaults; `required` and `format` (`directory`, `http-url`) for text. An `http-url` must use HTTPS unless it points at this computer or the local network (private addresses, Tailscale, `.local`). |
 | `setup` | `steps` (what you or the user do to set it up), `prerequisites` (`[{ "name": "Node.js", "command": "node" }]`), and `detect.anyPath` (paths that exist when the app is installed; `~` and `{{env.NAME}}` allowed), which lets setup suggest the pack. |
 | `skill` | `{ "path": "SKILL.md" }`. |
 | `listing` | For the widget library: `category` (agents, communication, developer, notes, productivity, system), `account` (what the user signs in with or selects), `connectsTo`, optional `homepage`. Packs without one are not listed. |
 | `preview` | Made-up sample data the widget library shows before anyone installs it: `data` is one sample result per query id (the shape its tool returns, after `extract`), optional `settings` for the templates that read them, and `at`, the time the sample was written; times in the sample move forward so "3m ago" stays true. Never real accounts, names, or messages. ≤32 KB. A listed pack without one shows no phone preview in the library. |
-| `data` | `{ "id", "tool", "arguments", "extract", "refreshSeconds" }` (≤10). Only `read` tools; they run automatically, never if the server marks the tool as writing. `extract`: `json` (default; structured content, else JSON text), `text-json`, `text`, or `records` ("Key: value" blocks). |
+| `data` | `{ "id", "tool", "arguments", "extract", "refreshSeconds" }` (≤10). Only `read` tools; they run automatically, never if the server marks the tool as writing. `extract`: `json` (default; structured content, else JSON text), `text-json`, `text`, `records` ("Key: value" blocks), or `yaml` (a heading line or two before the YAML is skipped). `document`: a JSON pointer, for a server whose JSON text wraps the payload in a string field (`{"success": true, "result": "<yaml>"}` → `"document": "/result"`); `extract` then applies to that field, and a result without it fails with the server's `error` text. |
 | `glance` | `{ "stats": [≤2 × { "label", "value", "tone" }] }` or `{ "line", "tone" }`. Tones: neutral, info, success, warning, danger. |
 | `badge` | `{ "text", "tone" }`; hidden when it renders empty or `0`. |
-| `blocks` | ≤8: `stats` (≤4 items; three read best), `list` (`items` resolves to an array; `item.title/subtitle/status` use `{{item/…}}`; `item.statusTones` colors rows by status text, and an empty status shows none, so emit a status only when it is news, e.g. "running"; `item.time` is an ISO date-time shown relative, "3m ago" or "in 12m"; `item.key` makes rows tappable when the pack has a `detail`; `limit` ≤20; `title` is the list's heading, needed when there are several lists), `board` (columns of items, a kanban board: `items`, `column` renders each item's column value, `columns` ≤6 of `{ id, title, tone, values }` where `values` lists the column values it collects (default its id), `item.title/subtitle/key/time`, `limit` ≤10 per column; each column shows its count), `text`. A `large` tile previews its first list's top four rows or, with two lists or boards, each one's title and top row (a board shows its column counts); choose `large` when two are worth seeing at a glance. |
+| `blocks` | ≤8: `stats` (≤4 items; three read best), `list` (`items` resolves to an array; `item.title/subtitle/status` use `{{item/…}}`; `item.statusTones` colors rows by status text, and an empty status shows none, so emit a status only when it is news, e.g. "running"; `item.time` is an ISO date-time shown relative, "3m ago" or "in 12m"; `item.key` makes rows tappable when the pack has a `detail`; `item.buttons` (needs `item.key`) puts a small button at the row's end that calls one declared tool for that row's item straight from a tap, with no agent: `{ "id", "label", "tool", "arguments" (with `{{item/…}}`), "when" (the `where` filter's syntax, e.g. `domain=light,state=on`), optional "confirm" }`; a row shows its first button whose `when` matches, and the companion checks `when` again against fresh data before calling, so a stale button does nothing; `limit` ≤20; `title` is the list's heading, needed when there are several lists), `board` (columns of items, a kanban board: `items`, `column` renders each item's column value, `columns` ≤6 of `{ id, title, tone, values }` where `values` lists the column values it collects (default its id), `item.title/subtitle/key/time`, `limit` ≤10 per column; each column shows its count), `text`. A `large` tile previews its first list's top four rows or, with two lists or boards, each one's title and top row (a board shows its column counts); choose `large` when two are worth seeing at a glance. |
 | `subtitle` | Optional live line under the title when the widget is open, e.g. `"{{agents/count}} agents · {{sessions/active}} running"`; the description is shown when absent. |
-| `detail` | What a tapped row opens: a read `tool` with `arguments` (`{{item/…}}` is the row), `messages` (`{{detail/…}}`, the result's message array), and `message.role/text/at`. |
+| `detail` | What a tapped row opens: a read `tool` with `arguments` (`{{item/…}}` is the row; an argument that is exactly one template and finds no value is left out, so one detail can serve rows of different shapes), `extract`/`document` as for `data`, `messages` (`{{detail/…}}`, the result's message array), and `message.role/text/at`. |
 | `notify` | Spoken updates during calls (≤6): `items`, `key`, optional `state`, `category` (agents, messages, mail, calendar, updates), and `rules` (`{ "state": "failed" }` or `{ "new": true }`, `priority` needs_you/failed/finished/update, `text`, optional `withLatest`). The first read is a baseline. |
 | `controls` | ≤12. `prompt` controls send their `prompt` as the user's own words. `tool` controls call one declared tool with fixed `arguments` (optional `forEach` + `maxCalls`), `effect` read or consequential, and `confirm` text for consequential ones. Mark two or three `default: true`. |
 
-**Templates** are lookups, never code: `{{setting.path}}`, `{{disks}}` (a query's data), `{{disks/drives/0/free}}` (JSON pointer), `{{item/name}}` (inside lists and `forEach`), with filters `|count`, `|pluck:id`, `|first`, `|join:", "`, `|default:none`, `|truncate:40`, and `|sort:-updatedAt` (comma-separated keys, `-` descending, `field=value` first). A string that is exactly one template yields the raw value, so `"ids": "{{unread/threads|pluck:id}}"` passes an array.
+**Templates** are lookups, never code: `{{setting.path}}`, `{{disks}}` (a query's data), `{{disks/drives/0/free}}` (JSON pointer), `{{item/name}}` (inside lists and `forEach`), with filters `|count`, `|pluck:id`, `|first`, `|join:", "`, `|default:none`, `|truncate:40`, `|sort:-updatedAt` (comma-separated keys, `-` descending, `field=value` first), `|where:domain=light,state=on` (items where every `field=value` holds; `!=` negates, `;` separates alternatives: `where:domain=lock,state!=locked;domain=cover,state=open`), `|group:area` (`[{ key, count, items }]` per distinct value; items without it are left out), and `|split:", "` (text into a list). A string that is exactly one template yields the raw value, so `"ids": "{{unread/threads|pluck:id}}"` passes an array.
 
 ## Writing a pack server
 
@@ -192,6 +192,7 @@ Every pack gets a `SKILL.md` with frontmatter (`name`, `description`) and these
 - Every consequential control needs `confirm` text that states the exact effect and count ("Archive {{newsletters/threads|count}} threads?").
 - Controls take fixed arguments (plus settings and query data); no free-form inputs.
 - Keep `forEach` bounded with `maxCalls`; prefer a batch tool when there is one.
+- Give row buttons a `when` that admits only items the button is safe for, and a `confirm` for anything hard to undo. Never put a button on something that lets people in (unlocking, opening a garage door or gate, disarming an alarm).
 - Ask for the narrowest scopes and tokens that make the pack work.
 - Secrets and tokens appear only in `mcp` (`env`, `headers`, `args`); validation rejects them anywhere else.
 - A pack that launches a program or ships a server runs code on the user's computer. Say what it runs before the user enables it, and never enable a pack from a bundle or the library that you have not read.

package/src/manage/guide.md

@@ -19,6 +19,10 @@ A widget comes from a **widget pack**: a folder on this computer that says which
 
 A library pack that has a newer version shows **Update to …**. Updating keeps your settings and keys. If what the pack runs changed, it stays off until setup turns it on again. A pack installed before a format change shows **Reinstall**, which also keeps your settings and keys.
 
+Sidebud installs a library pack only when the library's signature checks out and its files match what was signed. If an update lets a pack do more (a new tool, a tool that now changes things, a new address, key, or account access, or new server code), the page lists those changes and asks you first; your agent can never approve that for you. An update never replaces a pack you edited on this computer: customize a copy to keep your changes. After an update, **Roll back** returns to the version it replaced.
+
+If Sidebud pulls a release from the library (for example, it turned out to be unsafe), a computer with that version turns the pack off, says why on this page and in your phone's conversation, and keeps it off until you update or roll back.
+
 ## Ask your agent to build one
 
 You can ask for a new widget, or a change to one, by voice or typed chat. For example:
@@ -136,4 +140,5 @@ Besides packs, your agent can put a simple widget of its own on the phone ("add
 - **Needs setup** on a tile: open the pack's page and choose **Set up with my agent**, or fill in what it lists.
 - **An error in the widget**: the pack's server or account had a problem, and the widget shows its last good data with the error. **Check connection** on the pack's page tests it. Turning off a tool the widget reads also shows an error there.
 - **The library is empty**: this computer cannot reach the widget library. Packs you already installed keep working.
+- **Sidebud did not install a pack**: its download failed the signature or file check. Try again later; if it keeps failing, update the companion.
 - **A widget looks different on the phone than here**: update the Sidebud app on the phone. An older app skips widget parts it does not know yet.

package/src/manage/index.html

@@ -35,6 +35,10 @@
             ><svg viewBox="0 0 24 24" aria-hidden="true"><path d="m5 8 4 4-4 4M12 17h7" /></svg
             >Execution</a
           >
+          <a href="#decisions"
+            ><svg viewBox="0 0 24 24" aria-hidden="true"><path d="M13 2.5 4.5 13.5H12L11 21.5l8.5-11H12l1-8Z" /></svg
+            >Fast decisions<span class="tag-beta">Beta</span></a
+          >
           <a href="#mcp"
             ><svg viewBox="0 0 24 24" aria-hidden="true"><rect x="3.5" y="3.5" width="7" height="7" rx="1.5" /><rect x="13.5" y="3.5" width="7" height="7" rx="1.5" /><rect x="3.5" y="13.5" width="7" height="7" rx="1.5" /><path d="M17 14v6M14 17h6" /></svg
             >MCP &amp; widgets</a

package/src/manage/manage.css

@@ -406,6 +406,47 @@ button.theme-toggle {
   background: var(--amber-soft);
   color: var(--amber-text);
 }
+.label-text {
+  display: inline-flex;
+  flex-wrap: wrap;
+  align-items: center;
+  gap: 8px;
+}
+/* A setting's source (ADR 0014): Account, This computer, or Default, and its pin toggle. */
+.badge.source {
+  font-size: 11px;
+  padding: 4px 8px;
+}
+.badge.source.account {
+  background: var(--amber-soft);
+  color: var(--amber-text);
+}
+.badge.source.override {
+  background: var(--green-soft);
+  color: var(--green);
+}
+button.link.pin-toggle {
+  font-size: 12px;
+  font-weight: 500;
+  color: var(--muted);
+}
+button.link.pin-toggle:hover {
+  color: var(--text);
+}
+.tag-beta {
+  display: inline-block;
+  margin-left: 8px;
+  padding: 2px 7px;
+  border-radius: 999px;
+  border: 1px solid var(--amber-text);
+  color: var(--amber-text);
+  font-size: 10px;
+  font-weight: 700;
+  letter-spacing: 0.06em;
+  line-height: 1.4;
+  text-transform: uppercase;
+  vertical-align: middle;
+}
 .badge.bad {
   background: var(--red-soft);
   color: var(--red);
@@ -1033,6 +1074,16 @@ a.button {
 a.button:hover {
   background: var(--amber-hover);
 }
+/* A link that leads to a review step rather than acting (a full-control or community pack): not the page's call to action. */
+a.button.quiet {
+  background: var(--raised);
+  border: 1px solid var(--border);
+  color: var(--text);
+  text-align: center;
+}
+a.button.quiet:hover {
+  background: var(--hover);
+}
 
 /* Setup */
 .setup-steps {
@@ -1226,6 +1277,24 @@ ol.steps {
   margin: 0;
   padding-left: 20px;
 }
+/* Account settings sync */
+.sync-block {
+  border-top: 1px solid var(--border-soft);
+  padding-top: 14px;
+}
+.sync-list {
+  margin: 4px 0 8px;
+  padding-left: 20px;
+}
+.sync-conflict {
+  border-top: 1px solid var(--border-soft);
+  padding-top: 12px;
+}
+.sync-conflict .hint {
+  margin: 0;
+  overflow-wrap: anywhere;
+}
+
 .segmented {
   display: inline-flex;
   gap: 4px;
@@ -1406,6 +1475,24 @@ details.menu .menu-list a.button:hover {
   overflow: hidden;
   white-space: nowrap;
 }
+.phone-row-button {
+  flex: 0 0 auto;
+  align-self: center;
+  border-radius: 10px;
+  padding: 4px 10px;
+  font-size: 12px;
+  font-weight: 600;
+  line-height: 1.4;
+  background: var(--phone-raised);
+}
+/* A row with a button: the text takes the room, the status and button sit at the end. */
+.phone-list > div:has(> .phone-row-button) > div:first-child {
+  flex: 1 1 auto;
+  min-width: 0;
+}
+.phone-list > div:has(> .phone-row-button) {
+  align-items: center;
+}
 .phone-row-end {
   flex: 0 0 auto;
   white-space: nowrap;
@@ -1988,3 +2075,45 @@ pre.skill {
   gap: 8px;
   font-weight: 500;
 }
+
+/* How much a pack can control (packAccessOverview): shown first before it is added or turned on. */
+.access-overview {
+  margin: 16px 0;
+}
+.access-overview.level-computer {
+  border-color: var(--red);
+  background: var(--red-soft);
+}
+.access-overview.level-computer h3 {
+  color: var(--red);
+}
+.access-points {
+  display: grid;
+  gap: 8px;
+  margin: 0;
+  padding-left: 20px;
+  font-size: 14px;
+  line-height: 1.5;
+}
+.access-points li.danger {
+  color: var(--text);
+  font-weight: 600;
+}
+.access-points li.danger::marker {
+  color: var(--red);
+}
+.access-points li.caution::marker {
+  color: var(--amber-text);
+}
+.access-points li.info {
+  color: var(--muted);
+}
+.access-line {
+  display: grid;
+  justify-items: start;
+  gap: 6px;
+  margin-top: 6px;
+}
+.access-line:empty {
+  display: none;
+}