@corenel/sidecar 0.1.4 → 0.1.6

package/CHANGELOG.md

@@ -0,0 +1,76 @@
+# Changelog
+
+## 0.1.6
+
+The daemon release. `@corenel/sidecar` could already expose a machine's files and
+shell to a browser session; it can now also **run crew agents on its own** —
+on a schedule, when files change, or when another run finishes — with budgets,
+permissions and per-owner isolation enforced node-side.
+
+Everything below is additive. An existing `pd sidecar` setup behaves as it did in
+0.1.5 unless you pass `--daemon`.
+
+### Daemon core
+- `--daemon` starts an always-on core: an interruptible clock (sleep-until-next-wake,
+  wake signal, max-sleep cap) driving a trigger dispatcher over a shared runner.
+- Node run executor built on `runAgent`, with session recording to disk.
+- Per-agent run queue — one live run per agent, so a slow run cannot stack.
+- Node gateway client (absolute endpoint, node auth); daemon-origin requests are
+  tagged so entitlement metering can tell them from browser traffic.
+- `--default-model` fallback; a crew agent with no model fails fast rather than
+  starting an unrunnable run.
+
+### Triggers
+- Minimal 5-field UTC cron matcher with per-agent trigger state (`lastFired`,
+  `nextWake`), persisted and serialized so concurrent writes cannot clobber it.
+- File-change triggers: a self-contained glob matcher, a bounded change buffer,
+  and an idempotent re-scan.
+- Run-complete triggers: an evaluator carrying owner, stop reason and run
+  generation, with a chain-depth cap (`--max-chain-depth`, validated so a bad
+  value cannot disable the cap) to stop runs triggering each other forever.
+- `schedule_self` tool for self-directed wakes.
+
+### Budgets
+- Run budgets enforced node-side (stop / degrade), failing **closed** on an
+  unpriceable run rather than proceeding unmetered.
+- A continuous trigger cannot become due without a budget cap.
+- Pure usage pricing extracted to the harness; the node side hydrates a price table.
+
+### Permissions and attendance
+- Unattended prompt resolver: deny, park (bounded by the real budget remainder),
+  or allow — an abort resolves to null rather than a silent deny.
+- Attendance registry: asks are broadcast to attached clients, first answer wins,
+  and replay on attach means reconnecting does not lose a pending ask.
+- Pending-ask records with boot reconciliation (audit-only) and permission audit lines.
+- Stall watchdog aborts hung runs while leaving parked ones alone.
+
+### Multi-owner isolation
+- Per-owner run state and owner-qualified dispatch keys; a multi-root schedule
+  enumerates the daemon's own crew plus every `hosts/<dir>/crew`.
+- `call_agent` is confined to the caller's owner, and an attended run resolves its
+  owner from the authenticated identity rather than a client-supplied value.
+
+### Hosts and sync
+- Durable `sidecarId` with friendly-name resolution; the CLI advertises id and name.
+- `hosts.json` manifest: sanitized frozen `dirName`, null-prototype parsing,
+  per-record validation, atomic writes and serialized read-modify-write.
+- `pd sidecar hosts list` / `forget`; boot logs manifest drift.
+- Host-sync service with daemon-derived destinations. Writes to a synced tree go
+  through `syncWrite`/`syncRemove` only — the exposed surface has no `write`/`remove`
+  to bypass, and path confinement is reused from `NodeFileService` rather than
+  reimplemented.
+- A materialized directory is never reclaimed by eviction.
+
+### Also
+- `--help` / `-h` now print usage and exit 0. They were previously rejected as
+  unknown arguments, which printed a bare flag list and exited 1. The help text is
+  generated from the same table the parser validates against, so a flag cannot be
+  added without appearing in `--help`.
+- `fs_delete` tool, wired to `SidecarFileService.remove`.
+- Quieter cloudflared output.
+- A second `hello` is ignored once authenticated.
+
+### Housekeeping
+- The package's own `typecheck` now passes. It shares modules with the browser
+  harness (which guards its browser bits at runtime), so the tsconfig lacked the
+  DOM *types* and reported a dozen phantom errors against correct code.

package/README.md

@@ -29,6 +29,128 @@ match the site you're connecting from (the app fills it in for you).
 | `--host <addr>` | `127.0.0.1` | Bind address. Non-loopback is reachable off-box; keep the token secret. |
 | `--tls-cert <f>` `--tls-key <f>` | _(none)_ | Serve `wss://` (needed for a remote sidecar from an https page). |
 
+## Daemon (preview)
+
+`--daemon` also runs crew agents in-process, so the app can command a manual run on
+your machine instead of only serving tools. It also runs an always-on clock: agents
+with a `schedule` or `continuous` trigger fire on their own, with no client
+connected, over the same shared runner (and its per-agent queue) a client-commanded
+run uses. Global-scope agents only.
+
+New flag: `--default-model <id>` — a fallback model id used for a crew agent whose
+`settings.model` is unset. With neither set, the daemon fails that agent's run
+fast, before any network call, instead of sending an empty model id to the gateway.
+
+**Budget enforcement.** The daemon enforces the agent's `budget` on every run,
+headless or client-commanded:
+
+- `maxTokens` and `maxMs` are always enforceable — no pricing needed.
+- `maxUsd` additionally requires the daemon to be able to *price* the run's model.
+  The daemon hydrates a price table from the backend (`GET <endpoint>/llm-providers/available`)
+  once at startup using the daemon's login token (see "Log in" below). If a `maxUsd`
+  cap is set on a model the daemon cannot price, the run **refuses to start** rather
+  than let the cap silently never trip.
+- With no attendance relay yet, a breach's `ask`/`warn` action collapses to `stop`
+  for an unattended run (there is nobody to ask).
+- **A breach always results in `stop` for a daemon run in this release.** Saved crew
+  agents get `onBreach: 'ask'` (which collapses to `stop`) and the daemon supplies no
+  cheaper-model resolver, so `degrade` is unreachable in production — it is
+  implemented and tested as a seam only, pending a real `CrewBudget.onBreach` field.
+
+**`continuous` triggers require a budget.** A `continuous` trigger with neither
+`budget.maxUsd` nor `budget.maxTokens` set is refused — otherwise it would fire on
+every clock pass, forever. `continuous` also has a 60-second minimum interval
+(`trigger.config.minIntervalMs`, floored at 60000) regardless of what's configured.
+
+**`schedule` triggers use UTC cron.** The 5-field cron expression
+(`minute hour day-of-month month day-of-week`) is matched against the machine's UTC
+clock. There is no local-time or DST handling — write the expression in UTC.
+
+**Permission governance (`ask`-tier tools, unattended runs).** A crew agent's
+`POLICY.yaml` may declare `unattended: deny | park | allow` for what a daemon run
+does with an `ask`-tier permission gate when nobody is watching (default `deny`):
+
+- `deny` — the ask resolves to deny immediately. The run continues degraded (a
+  denial is not a run failure); this is the only outcome that never waits.
+- `allow` — the ask resolves to allow immediately, unattended.
+- `park` — the run WAITS for someone to attend and answer, bounded by
+  `min(remaining budget.maxMs, parkTimeoutMs ?? 30 minutes)` (`PARK_TIMEOUT_MS`,
+  overridable per agent via `POLICY.parkTimeoutMs`). If the bound expires with
+  nobody answering, the ask resolves to deny and the run continues degraded — the
+  same outcome as `deny`, just delayed. A parked run **holds its agent's queue
+  slot** for the whole window: another run for the same agent cannot start until
+  the park ends (answered, expired, or the run is otherwise stopped).
+- If a client IS attending when the ask fires (any non-`park` mode too), it is
+  offered the chance to answer directly before the unattended mode applies; an
+  attended ask that goes unanswered (e.g. every client detaches) falls through to
+  the unattended mode above.
+
+Approvals are answered from the app's **pending-approvals surface** — a
+connected browser (or CLI) client attached to the daemon's shared attendance
+registry sees every outstanding ask (including ones that started before it
+connected) and can answer any of them.
+
+**A daemon restart destroys parked runs.** Parked state lives only in the
+daemon's process memory (the in-flight `await`, not a durable record) — a
+restart drops it. The run's pending record is marked dead on the next boot;
+there is no resume. Re-issue the run after restarting if it still needs to
+happen.
+
+**The stall watchdog never aborts a parked run.** A run idle for 10 minutes
+(no event delivered to any caller) is aborted with `stopReason: 'stalled'` —
+except a run that is currently parked, which is legitimately silent while it
+waits for a human and is explicitly excluded from the watchdog's scan.
+
+Manual smoke (schedule trigger, no browser open):
+
+1. Create a crew agent with a schedule trigger and a token budget, e.g. in its
+   `AGENT.md` frontmatter:
+
+   ```yaml
+   triggers:
+     - type: schedule
+       config: { cron: "*/5 * * * *" }
+   budget:
+     maxTokens: 2000
+   ```
+
+2. Start the daemon: `npx @corenel/sidecar --daemon --root <project>`.
+3. Wait for the next 5-minute UTC boundary and confirm a new session appears
+   under `~/.prompd/crew/<name>/sessions/` — with no browser open and no client
+   connected, proving the clock (not a client command) drove the run.
+
+Manual smoke (manual/client-commanded trigger):
+
+1. **Log in** with the node CLI so the daemon has a gateway token:
+
+   ```bash
+   corenel login
+   ```
+
+   This writes the token to `<state dir>/token` (default `~/.corenel/token`, or
+   `~/.prompd/token` in a `.prompd`-branded install).
+
+2. **Create a crew agent** in the app (global scope) so it lands on disk at
+   `<state dir>/crew/<name>/`.
+
+3. **Start the sidecar with `--daemon`:**
+
+   ```bash
+   npx @corenel/sidecar --daemon --allow-origin https://prompd.app
+   ```
+
+   Add `--endpoint <url>` to point at a non-default gateway, `--state-dir <dir>`
+   to use a state dir other than the default, or `--default-model <id>` to give
+   agents with no `settings.model` a fallback.
+
+4. **Pair from the app** with the printed token, then command a manual run of the
+   agent you created. Confirm the reply streams back in the app as it's generated,
+   and that a new session appears under `<state dir>/crew/<name>/sessions/<runId>/`.
+
+Entitlement for daemon runs is enforced at the gateway, not locally — a 401/403 on
+the run means the login token from step 1 doesn't carry daemon access, not a bug in
+the sidecar itself.
+
 ## Security
 
 - Loopback by default; a browser connection requires both the pairing token **and** an
@@ -36,5 +158,18 @@ match the site you're connecting from (the app fills it in for you).
 - The HTTP proxy (for local LLMs) only reaches **loopback** hosts — it can't be used as
   an SSRF pivot to internal services.
 - `sidecar_shell_exec` is off unless you pass `--allow-shell`.
+- **Pairing a device grants its agents real reach on this machine.** With
+  `--daemon` and host config sync, a paired client can sync its own crew
+  agents to the daemon and have them run here — on the daemon's machine,
+  against the daemon's own `--root` workspace, not a workspace of the
+  client's own. Each synced agent runs under the POLICY the client itself
+  authored for it, including `unattended: allow`, on a schedule the client
+  itself sets. If you also pass `--allow-shell`, that shell access extends
+  to a paired client's agents too, exactly as it does to a client-commanded
+  run. There is no separate approval step per agent or per run beyond the
+  pairing handshake — treat pairing a device the same way you'd treat
+  handing it an SSH key to this machine: only pair devices you trust with
+  that level of access, and un-pair (revoke) a device the moment you stop
+  trusting it.
 
 Licensed under Elastic-2.0.