@passioncode-ai/fabric-agent-adapter 0.3.1 → 0.4.2

package/plugins/fabric-agent-adapter/skills/building-fabric-services/references/dashboard.md

@@ -0,0 +1,32 @@
+# Dashboard principles
+
+The dashboard is where the operator decides; it must stay truthful when parts of the
+service are not.
+
+1. **Same origin, static assets.** HTML shell plus hashed `app.js`/`app.css` from a
+   whitelist; no inline script; a strict CSP. Nothing from a CDN — the page must work
+   offline on a plane.
+2. **State first, then detail.** The top of every page answers "is it working, and
+   does it need me?" — the same `status`, `degraded` and attention tiles the
+   well-known document publishes, so the page and Fabric Dashboards never disagree.
+3. **Calm refresh.** Poll the page's own API every 5 s while visible, back off when
+   hidden, and pause while a field is focused, a form has unsaved input or a dialog is
+   open. Replace a region only when its data changed; keep focus, scroll and open
+   sections.
+4. **Partial failure stays partial.** Load panels independently (`Promise.allSettled`);
+   a failed panel shows its own one-sentence error and a retry, and the rest render.
+5. **Every error is a sentence and an action.** "Store listing push failed: App Store
+   Connect rejected the key. Settings → Keys" — never a status code, a stack trace or a
+   blank area. Show when data was last fresh.
+6. **Server down is a state, not a crash.** When the API stops answering, keep the
+   last data greyed with "Service not answering since 17:02", and recover by itself
+   when it returns.
+7. **Approvals show the diff and its hash.** Any write the operator approves shows
+   before → after and the hash the service will verify at apply time.
+8. **Theme.** Follow the operator's product design system (PassionCode.ai tokens for
+   Fabric-family services); respect `prefers-color-scheme` unless the product fixes a
+   theme; never encode meaning by colour alone.
+9. **Links into the page are stable.** Event `link`s point at hash routes that survive
+   a reload (`/dashboard#/approvals/77`) so a notification opens the exact item.
+10. **No second browser tab required.** With Fabric Dashboards installed, the page is
+    shown inside it; do not open windows or tabs on your own — use in-page dialogs.

package/plugins/fabric-agent-adapter/skills/building-fabric-services/references/events-and-notifications.md

@@ -0,0 +1,44 @@
+# Events and notifications
+
+## Map the log you already keep
+
+| Existing log | View |
+|---|---|
+| a SQL `events`/`jobs` table with an autoincrement id | `SELECT … WHERE id > ? ORDER BY id LIMIT ?`; `id` as string |
+| per-job JSONL files | keep one append-only `activity.jsonl` index written beside them, or merge by `(ts, job, seq)` into a composite id `"<ts>-<job>-<seq>"` that still sorts |
+| a journal with no id | add a monotonic counter when appending; backfill ids once on migration |
+| nothing | `JsonlEventLog` from the kit |
+
+The feed is a view: never copy rows into a second store that can drift from the first.
+
+## Writing an event
+
+- `kind`: dotted, stable, past tense or state (`job.failed`, `job.awaiting_choice`,
+  `service.started`, `collector.stale`). Hosts filter on it.
+- `level`: `info` (routine), `notice` (the operator may want to look), `warning`
+  (something is degrading), `error` (something failed and needs action).
+- `text`: one sentence, in the operator's language, with the object named and the
+  number stated — "The Q3 report draft is ready for your approval (12 sections, 3
+  languages)." Never a machine id, never a stack trace.
+- `subject`: what it is about (`{type: "report", id: "q3", label: "Q3 report"}`), so a host
+  can group.
+- `link`: the page that resolves it.
+
+## When to set `notify: true`
+
+Notify when the operator must act (an approval is waiting, a key expired, a job failed
+after retries) or asked to be told (a long job finished). Do not notify for routine
+progress, retries that will succeed, or anything that fires more than a few times an
+hour. The host decides whether to show it — quiet hours, per-service settings — and
+debounces; the service decides only what is notification-worthy.
+
+## Lifecycle events every service emits
+
+`service.started` (with the build), `service.stopping`, `service.degraded` and
+`service.recovered` when a degraded source appears or clears, `update.available` when
+the service learns of a newer release.
+
+## Retention
+
+At least seven days or 1000 events, whichever is more; trim oldest first; a cursor
+older than retention returns the oldest retained page, not an error.

package/plugins/fabric-agent-adapter/skills/building-fabric-services/references/lifecycle.md

@@ -0,0 +1,63 @@
+# Lifecycle — supervisor, install, release layout, state
+
+## launchd plist (generate it with `launchd_plist`)
+
+| Key | Value | Why |
+|---|---|---|
+| `Label` | reverse-DNS, stable (`com.example.example-agent`) | the host controls the job by label |
+| `ProgramArguments` | absolute interpreter + module/script inside a **release** directory | a worktree or checkout path breaks the day it moves |
+| `RunAtLoad` | `true` | back at every login |
+| `KeepAlive` | `true` | `{SuccessfulExit:false}` leaves a cleanly exited service down |
+| `ThrottleInterval` | `10` | bounds a crash loop |
+| `ExitTimeOut` | drain time + margin (40 s default) | SIGKILL arrives after it |
+| `ProcessType` | `Background` | scheduler hint |
+| `EnvironmentVariables` | `PATH` set explicitly; `*_FILE` paths to secrets | never a secret value — the plist is world-readable in backups |
+| `StandardOutPath`/`StandardErrorPath` | `~/Library/Logs/<id>/service.log` | one place the host tails |
+
+## Install, upgrade, uninstall
+
+1. Build or unpack the release into `~/.local/share/<id>/releases/<version>-<sha12>/`
+   (a venv or `node_modules` inside it). Never edit a release after it is written.
+2. `write_descriptor` (port and id claims are checked here).
+3. `launchd_install`: write + `plutil -lint`, `enable`, `bootout` and wait until
+   `launchctl print gui/<uid>/<label>` fails, `bootstrap` with up to five retries,
+   then poll the well-known document until it answers with this `id.instance`.
+4. Upgrade = new release, rewrite the plist with the new path, `launchd_install`
+   again. Keep the previous release for rollback; prune older ones by count.
+5. Uninstall = `launchd_uninstall` + `remove_descriptor`. Data stays.
+
+A host stops a service with `bootout` **and** `disable` (off survives a login) and
+starts it with `enable` + `bootstrap`; restart is `kickstart -k`. The service never
+implements these verbs itself — its CLI calls launchctl the same way.
+
+## Directories
+
+| What | macOS | Linux |
+|---|---|---|
+| data + config | `~/Library/Application Support/<id>/` | `${XDG_DATA_HOME:-~/.local/share}/<id>/` |
+| logs | `~/Library/Logs/<id>/` | `${XDG_STATE_HOME:-~/.local/state}/<id>/logs/` |
+| cache (deletable any time) | `~/Library/Caches/<id>/` | `${XDG_CACHE_HOME:-~/.cache}/<id>/` |
+| code | `~/.local/share/<id>/releases/…` | same |
+
+A repository that versions the data itself (a registry, a plan) may hold the data; the
+service's own code checkout and its releases may not. Directories 0700, secret files 0600. A store carries a schema version and the service
+refuses to open a store newer than its code. The cache holds only what can be rebuilt;
+anything the operator would miss belongs in data.
+
+## Logs
+
+One structured log (JSON lines) rotated by size (5 × 5 MB is a sane default) plus the
+launchd stdout file, truncated at start. Configure logging once, in the entry point.
+Never log a token, a cookie, a login code or a request body that may carry one.
+
+## Shutdown
+
+On `SIGTERM`: stop accepting new work, append a `service.stopping` event, drain
+in-flight work until `ExitTimeOut` minus a margin, persist what was interrupted so the
+next start resumes it, release the lock, exit 0.
+
+## Linux
+
+Until a systemd adapter exists, declare `lifecycle.manager: "none"`. A `systemd --user`
+unit with `Restart=always` gives the same guarantees; the host will control it once the
+adapter ships. Everything else in this skill applies unchanged.

package/plugins/fabric-agent-adapter/skills/building-fabric-services/references/migrating-a-service.md

@@ -0,0 +1,32 @@
+# Migrating an existing service
+
+Order matters: each step leaves the service answering.
+
+1. **Measure first.** Run `check_service.py --descriptor <draft>` against a descriptor
+   written by hand into a temporary `--services-dir`; keep the `FAIL` list as the
+   migration's checklist.
+2. **Add the well-known route and the build identity.** Read-only, no risk.
+3. **Add the events view** over the existing log, then the login-code routes. Keep the
+   service's old login path until the operator has switched.
+4. **Move the lock to the top of startup** — before the startup hook that resumes jobs.
+   Test: a second copy exits 75 and the first copy's running jobs are untouched.
+5. **Move state out of the code tree** if it lives there: copy to the OS data
+   directory, switch the paths, keep the old tree read-only for one release, then
+   delete it with the operator's consent.
+6. **Regenerate the plist** from `launchd_plist`, pointing at a release; delete stray
+   `.plist.bak` files from `~/Library/LaunchAgents` after moving them elsewhere.
+7. **Write the descriptor** from the installer; resolve any port claim it refuses by
+   moving the newcomer, never the established service.
+8. **Re-run the probe** until nothing `FAIL`s; record the table in the service's
+   verification document.
+
+## Gaps that existing services usually have
+
+| Gap | What fixes it |
+|---|---|
+| A health route that answers `{"ok": true}` with no identity | the well-known document with `service.id`, `instance`, build and pid |
+| The port bind treated as the single-instance guarantee, with a startup hook that runs first | the lock at the top of startup; a second copy exits 75 |
+| Data, logs or caches inside the repository | the OS data, log and cache directories; the old tree read-only for one release |
+| `KeepAlive {SuccessfulExit:false}`, a plist pointing at a checkout or a worktree | a plist generated by `launchd_plist`, pointing at a release |
+| A port another service already uses by default | the port claim at install; move the newcomer |
+| An event log in a private shape | the events view over it, with one sentence per event |

package/plugins/fabric-agent-adapter/skills/building-fabric-services/references/protocol.md

@@ -0,0 +1,83 @@
+# fabric-service/0.1 — wire reference
+
+Pinned to `fabric-agent-contract` commit `a5a27092ba0dcc5facfbeae8b359146dfb403e9a`
+(`docs/specification/service.md`, DEC-0015). The contract's schemas are normative;
+this page is the working summary. Extension key:
+`https://fabric.passioncode.ai/agent-contract/extensions/service/0.1`.
+
+## Descriptor — written by the installer
+
+Directory: macOS `~/Library/Application Support/ai.passioncode.fabric/services/`,
+Linux `${XDG_DATA_HOME:-~/.local/share}/passioncode-fabric/services/`, or
+`FABRIC_SERVICES_DIR`. File `<id>.<instance>.json`, mode 0600, atomic.
+
+| Field | Rule |
+|---|---|
+| `protocol` | `"fabric-service/0.1"` |
+| `id`, `instance` | `^[a-z][a-z0-9-]{1,62}$`, `^[a-z][a-z0-9-]{0,31}$` (default `default`); the pair is unique per machine |
+| `name`, `summary` | ≤ 80 and ≤ 200 characters |
+| `origin` | `http://127.0.0.1:<port>`; the port is a machine-wide claim |
+| `auth` | `tokenFile` (0600); `header` default `Authorization` with `scheme` `Bearer`; any other header carries the raw token with `scheme: "none"` |
+| `lifecycle` | `manager` `launchd` (then `label` and `plist`) or `none` |
+| `paths` | `data` (required), `logs[]`, optional `config`, `cache` |
+| `commands` | only `doctor` and `update`, argument arrays whose first item is an absolute or `~/` path |
+| `source.repository`, `fabricManifest` | optional |
+| `installedAt`, `installedBy` | when and by which installer version |
+
+## Well-known document — `GET /.well-known/fabric-service`
+
+No auth; the Host/Origin guard applies; answered from memory in under 100 ms.
+
+```json
+{
+  "protocol": "fabric-service/0.1",
+  "service": { "id": "example-agent", "instance": "default", "name": "Example Agent",
+               "version": "0.2.0", "build": { "commit": "8b80be9", "dirty": false, "builtAt": "2026-09-28T17:40:00Z" } },
+  "process": { "pid": 58090, "startedAt": "2026-09-28T17:41:02Z" },
+  "status": "degraded",
+  "degraded": [{ "source": "llm", "reason": "No model key: drafting is paused." }],
+  "summary": [{ "label": "Jobs running", "value": 2 }, { "label": "Awaiting you", "value": 1, "attention": true }],
+  "surfaces": { "dashboard": { "path": "/dashboard", "login": true },
+                "mcp": { "path": "/mcp", "transport": "streamable-http" },
+                "events": { "path": "/fabric/v1/events" } },
+  "update": { "available": null }
+}
+```
+
+- `status`: `starting | ready | degraded | stopping`. No answer means `down`.
+- `build` needs `commit` or `digest` (`sha256:<64 hex>`).
+- `summary`: at most six tiles; `attention: true` counts toward the host's badge.
+- `surfaces.events` is required; `dashboard` and `mcp` when the service has them.
+
+## Events page — `GET /fabric/v1/events?after=<cursor>&limit=<n>`
+
+Token required. `limit` default 50, maximum 200. Without `after`: the newest `limit`,
+ascending. `cursor` is the last id returned, or the `after` you sent when the page is
+empty, or `null` for an empty log. Retain at least seven days or 1000 events.
+
+```json
+{ "events": [ { "id": "4213", "at": "2026-09-28T17:55:10Z", "kind": "job.awaiting_choice",
+                "level": "notice", "text": "The Q3 report draft is ready for your approval.",
+                "subject": { "type": "report", "id": "q3", "label": "Q3 report" },
+                "link": "/dashboard#/approvals/77", "notify": true } ],
+  "cursor": "4213" }
+```
+
+`kind` is dotted lowercase; `level` is `info | notice | warning | error`; `link` is a
+path on the service origin, never an absolute URL. Optional SSE stream at
+`surfaces.events.stream` carrying the same objects.
+
+## Login code — `POST /fabric/v1/login-code`
+
+Token required → `{ "url": "/fabric/v1/login?code=<16–256 url-safe chars>", "expiresAt": "…" }`,
+single use, at most 120 s, recorded as used before it is honoured. `GET` that URL →
+`Set-Cookie` `HttpOnly; SameSite=Strict`, `302` to `surfaces.dashboard.path`.
+
+## Semantic rules a host applies
+
+| Code | Rule |
+|---|---|
+| `FAC-SEM-009` | well-known `service.id.instance` equals the descriptor's, else the port holder is `foreign` |
+| `FAC-SEM-010` | no two descriptors claim one port or one `id.instance` |
+| `FAC-SEM-011` | `ready` carries no degraded source |
+| `FAC-SEM-012` | commands start with an absolute or `~/` executable |

package/plugins/fabric-agent-adapter/skills/building-fabric-services/references/surfaces-and-auth.md

@@ -0,0 +1,58 @@
+# Surfaces and auth
+
+## MCP for agents
+
+- One server inside the service process, `streamable-http`, at `/mcp` on the service
+  origin, stateless JSON responses unless the tools stream.
+- Authenticate with the service token in the declared header. OAuth is for remote
+  multi-user servers, not for a loopback service.
+- Register it into a client config with the service's own command
+  (`<tool> mcp-register`), which writes `{"type":"http","url":"http://127.0.0.1:<port>/mcp","headers":{...}}`
+  atomically, aborts if the file changed meanwhile, and keeps one 0600 backup. The token
+  goes in `headers`, never in the URL — every log that records a URL prints its query
+  string.
+- Ship server `instructions` that tell a caller where to start and that every answer
+  carries `degraded`.
+
+## CLI for people and scripts
+
+`<tool> service status|start|stop|restart` (launchctl on the label, then the
+well-known document), `<tool> dashboard` (asks for a login code and opens it; with
+Fabric Dashboards installed it opens the service there instead), `<tool> doctor --json`
+(the same checks the probe runs, plus provider keys), `--json` on every command. Print
+a sign-in link only when stdout is a terminal.
+
+## A2A for remote agents
+
+Remote reach goes through A2A `1.0` over HTTPS or an authenticated gateway in front of
+MCP — never by binding a LAN address. A tunnel (Tailscale Serve and the like) is an
+outward surface with its own token lifetime; watch it like a service, because nothing
+else will notice it expire.
+
+## Token
+
+- Created once with `ensure_token` at first start, after the instance lock.
+- Stored at the descriptor's `auth.tokenFile`, 0600, owner-checked, never a symlink.
+- Compared in constant time (`token_matches`).
+- Rotation is an operator act: write a new file, restart, re-run `mcp-register`.
+- Same-user processes can read it. The protocol defends against web pages and
+  mistakes, not against hostile code running as the operator — say so in SECURITY.md.
+
+## Dashboard session
+
+- `POST /fabric/v1/login-code` (token) → single-use code, at most 120 s, persisted as
+  used before it is honoured, burned even when expired.
+- `GET /fabric/v1/login?code=` → `HttpOnly; SameSite=Strict` cookie, 302 to the
+  dashboard. Sessions are HMAC-signed; `revoke_all` rotates the key and ends every
+  session at once.
+- Browser writes need the cookie **and** a custom header such as `X-<Tool>-Request: 1`,
+  which forces a preflight the service never answers.
+- A dashboard that is deliberately read-open to local pages declares
+  `"login": false`; its writes still need the header.
+
+## Headers every response carries
+
+`Cache-Control: no-store`, `X-Content-Type-Options: nosniff`, a CSP with no inline
+script, and `frame-ancestors 'self'` unless the page must never be embedded. Fabric
+Dashboards shows pages in a native view, not a frame, so `X-Frame-Options: DENY` does
+not stop it.