@aiworker/web 1.22.0 → 1.23.0

package/server/lib/notifications/APNS.md.bak

@@ -1,135 +0,0 @@
-# APNs remote push — signed relay mode
-
-Native iOS background push (notifications even when the app is **suspended or killed**) is
-delivered via APNs through a **central relay**, so no user configures an Apple key. Each server
-signs its relay requests with an auto-generated keypair, and tokens are bound to the server that
-registered them — so a leaked device token alone can't be used to push.
-
-## How it works
-
-1. The app registers its APNs device token with **its own server** (`POST /api/push/apns-token`,
-   `useNativePushRegistration`). PWA/desktop never register — only the native Capacitor app.
-2. The server **binds the token on the relay**: it POSTs `{ token, publicKeyJwk, ts, sig }` to
-   `POST /v1/push/register-token`, signed with its auto-generated ECDSA P-256 key
-   (`getOrCreateRelayKeypair`, persisted in settings like the VAPID keys). The relay records
-   `token → serverId` where `serverId = SHA-256(publicKey)`.
-3. On a trigger (ready/error/question/permission), the server composes **generic, content-free**
-   text — a fixed scenario title ("Agent response is ready" / "Agent needs your input" / "Agent
-   needs permission" / "Agent hit an error") + the **session name** as the body, no model/project/
-   message content — plus a **`badge`** count (see below) — and POSTs `{ tokens, title, body,
-   badge, env, data:{sessionId}, publicKeyJwk, ts, sig }` to `POST /v1/push/send`
-   (`apns-runtime.js` → `sendViaRelay`). It does **not** gate on UI visibility (see below).
-4. The **relay** (`openchamber-website/apps/api`, Cloudflare Worker) verifies the signature +
-   `ts` freshness, derives `serverId`, and only delivers to tokens bound to that server. It holds
-   the single project APNs `.p8` key, signs an ES256 JWT with `crypto.subtle`, and sends each
-   token to APNs over HTTP/2, returning per-token results; the server drops tokens flagged `drop`
-   (410 / BadDeviceToken). The relay stores no secret — only `token → serverId` hashes.
-5. Tapping a push deep-links to its session via the forwarded `sessionId`.
-
-## Foreground suppression
-
-APNs is **not** gated on UI visibility. A backgrounded WKWebView can't reliably report "hidden"
-before iOS suspends it, so a server-side visibility gate dropped background push for short
-responses. Instead the server always sends, and **iOS** suppresses the foreground banner
-(`PushNotifications.presentationOptions: []` in `capacitor.config`) — so there is no notification
-while the app is active, with no race. APNs is the native app's **only** channel; local
-notifications were removed (a WKWebView can't tell foreground from background — `document.hasFocus()`
-is unreliable — so they leaked while the app was open). Cloudflare is touched only when a native
-app with notifications on has a registered token and a trigger fires.
-
-## App-icon badge
-
-Each push carries an **absolute** `aps.badge` = the number of **distinct collapse-ids (`tag`)
-pushed since the app was last foregrounded**. It mirrors the lock-screen banner stack.
-
-The count is a `Set<tag>` (`pendingPushTags`) in the trigger runtime (`runtime.js`):
-`toApnsGenericPayload` adds the push `tag` and returns the set size as the badge. We key by **`tag`,
-not sessionId**, because the tag *is* the banner identity — iOS uses it as `apns-collapse-id`, so
-same-tag pushes replace one banner while different tags are distinct banners. One session can raise
-several banners (`ready-<id>`, `question-<id>`, `permission-<requestKey>` are different tags), so
-counting sessionIds both over- and under-counts the stack; counting tags matches it.
-
-It is deliberately **not** derived from the live attention snapshot (`needsAttention`/`isViewed`):
-that machinery drives in-app indicators on *connected* clients, where a backgrounded client stays
-"viewing" and `needsAttention` is set by a separate `session.status` event that races the push
-trigger. The set self-clears via `clearPendingPushBadge` on any signal that the user is engaging
-with the app: the visibility beacon (`updateUiVisibility` wrapper, `visible:true`), **plus** opening
-a session (`POST /api/sessions/:id/view`) and sending a message (`POST /api/sessions/:id/
-message-sent`). The latter two need no auth and fire reliably on the native app when it foregrounds,
-so they are the dependable reset — the visibility beacon alone proved unreliable in WKWebView. This
-mirrors the device zeroing its icon badge on `sceneDidBecomeActive` (`AppDelegate.swift`), keeping
-server and device in sync.
-
-The value flows `runtime.js` (`toApnsGenericPayload`) → `apns-runtime.js` (`sendViaRelay` body /
-direct-mode `aps.badge`) → relay (`pushSendSchema.badge` → `aps.badge`). It is **not** signed (like
-`body`/`data`); the relay still only delivers to bound tokens. The set is server-global, so every
-device token of a server sees the same badge.
-
-## Modes
-
-- **Relay (default):** server has no Apple key; `AIWORKER_PUSH_RELAY_URL` defaults to
-  `https://api.aiworker.dev/v1/push/send` (register URL is derived as `…/register-token`).
-- **Direct (fallback):** set `AIWORKER_PUSH_RELAY_DISABLED=true` + `AIWORKER_APNS_KEY_ID/
-  TEAM_ID/P8` to sign+send from the server itself (HTTP/2 + ES256 JWT); no relay binding needed.
-
-## Config
-
-Server (`apns-runtime.js`):
-- `AIWORKER_PUSH_RELAY_URL` (default the public relay), `AIWORKER_APNS_ENVIRONMENT`
-  (optional override forcing every send to `sandbox` or `production`; normally unset — each
-  token is delivered to the environment it registered with: the iOS shell reads the
-  `aps-environment` entitlement from the embedded provisioning profile and reports it at
-  registration, so Xcode dev builds go to sandbox and TestFlight/App Store to production).
-  The signing keypair is auto-generated — nothing to set.
-- Direct fallback: `AIWORKER_APNS_KEY_ID`, `AIWORKER_APNS_TEAM_ID`, `AIWORKER_APNS_P8`
-  (or `_P8_PATH`), `AIWORKER_APNS_BUNDLE_ID`, `AIWORKER_PUSH_RELAY_DISABLED=true`.
-
-Relay (Cloudflare Worker secrets via `wrangler secret put` / GitHub Actions): `APNS_P8`,
-`APNS_KEY_ID`, `APNS_TEAM_ID`, optional `APNS_BUNDLE_ID` / `APNS_DEFAULT_ENV`. The `push_tokens`
-binding table is created by `migrations/0002_push_tokens.sql` (applied on deploy).
-
-## Apple setup (one-time)
-
-1. Apple **Keys** (not Certificates) → create an **APNs Auth Key** (`.p8`) → Key ID + Team ID;
-   enable **Push Notifications** on App ID `com.aiworker.app`.
-2. In the **openchamber-website** repo → Actions secrets: `APNS_P8` (PEM), `APNS_KEY_ID`,
-   `APNS_TEAM_ID`. Push to `main` → relay deploys, secrets sync, D1 migrations apply.
-3. Xcode: confirm the Push Notifications capability; Clean Build Folder; run on device.
-
-## Security posture
-
-- The device token is a per-install secret, but no longer the *only* defence: every relay request
-  is signed by the server's private key, and the relay only delivers to a token from its bound
-  `serverId`. A leaked token alone is useless — an attacker has neither the private key nor a
-  matching binding.
-- `serverId` self-certifies (`SHA-256(publicKey)`), so the relay holds no secret; a D1 leak
-  exposes only `token → serverId` hashes. The signed `ts` (±5 min window) blocks replay.
-- Residual: trust-on-first-bind (whoever registers a token first owns it) — acceptable, since
-  registering already requires possessing the token. Cloudflare rate limiting is defence-in-depth.
-
-## Data confidentiality (what the relay / Apple can see)
-
-The push payload is **not** application-encrypted, so there is no decryption step. The text is
-sent in plaintext, protected only by **TLS in transit** (HTTPS to the relay, TLS from the relay
-to APNs). The request **signature is authentication, not encryption** — the relay *verifies* it
-(valid / invalid), it does not hide anything.
-
-Who can read the alert text:
-
-- **Network hops:** nothing (TLS).
-- **The relay (Cloudflare):** the generic title + body (session name), the device token, and
-  `sessionId`. It stores only `token → serverId` hashes (no text, no payload).
-- **Apple APNs:** the alert text too — APNs always reads the alert payload of an `alert` push.
-- **The device:** displays it.
-
-This is acceptable **because the text is deliberately content-free**: a fixed scenario title +
-the session name only — no model, project, or message content (`runtime.js` →
-`toApnsGenericPayload`). The session name is the single semi-personal field that crosses the
-relay/Apple. To hide even that from Apple would require an end-to-end **encrypted payload**
-(`mutable-content` + a Notification Service Extension that decrypts on-device with a key never
-sent to the relay) — not implemented, and unnecessary for generic text.
-
-## Android (FCM) note
-
-The Android equivalent is **FCM** (not implemented): the same relay would forward to FCM with a
-server key, and the client would register an FCM token (same store/routes + signing).

package/server/lib/notifications/DOCUMENTATION.md.bak

@@ -1,138 +0,0 @@
-# Notifications Module Documentation
-
-## Purpose
-This module provides notification message preparation utilities for the web server runtime, including text truncation and plain-text normalization for system notifications.
-
-## Entrypoints and structure
-- `packages/web/server/lib/notifications/index.js`: public entrypoint imported by `packages/web/server/index.js`.
-- `packages/web/server/lib/notifications/routes.js`: route registration for push, visibility, and session status/attention endpoints.
-- `packages/web/server/lib/notifications/push-runtime.js`: push subscription persistence, VAPID initialization, and UI visibility runtime.
-- `packages/web/server/lib/notifications/apns-runtime.js`: native iOS APNs device-token persistence + delivery. Two modes: **relay** (default — sign + POST tokens + generic text to the central Cloudflare relay `https://api.aiworker.dev/v1/push/send`, which holds the single project APNs key) and **direct** (fallback — sign ES256 JWT with Node crypto + HTTP/2, when `AIWORKER_PUSH_RELAY_DISABLED=true`). Each server has an auto-generated ECDSA P-256 keypair (`getOrCreateRelayKeypair`, persisted in settings); it binds tokens on the relay (`/v1/push/register-token`) and signs every relay request, so the relay only delivers to tokens bound to that server. APNs is the native app's sole notification channel (no local notifications) and is NOT gated on UI visibility — iOS suppresses the foreground banner instead. Mobile push carries only generic text (scenario title + session name) — see `APNS.md`.
-- `packages/web/server/lib/notifications/emitter-runtime.js`: desktop/stdout + UI SSE notification emission runtime.
-- `packages/web/server/lib/notifications/runtime.js`: trigger runtime for OpenCode event-driven notification fanout.
-- `packages/web/server/lib/notifications/template-runtime.js`: notification template variables and session text/title enrichment runtime. Zen-model helpers are retained as compatibility stubs only.
-- `packages/web/server/lib/notifications/message.js`: helper implementation module.
-- `packages/web/server/lib/notifications/message.test.js`: unit tests for notification message helpers.
-
-## Public exports
-
-### Notifications API (re-exported from message.js)
-- `truncateNotificationText(text, maxLength)`: Truncates text to specified max length, appending `...` if truncated.
-- `prepareNotificationLastMessage({ message, settings })`: Prepares the last message for notification display by normalizing and truncating text.
-
-### Route registration API (routes.js)
-- `registerNotificationRoutes(app, dependencies)`: Registers notification-owned endpoints:
-  - `GET /api/push/vapid-public-key`
-  - `POST /api/push/subscribe`
-  - `DELETE /api/push/subscribe`
-  - `POST /api/push/apns-token` (native iOS APNs device-token registration)
-  - `DELETE /api/push/apns-token`
-  - `POST /api/push/visibility`
-  - `GET /api/push/visibility`
-  - `GET /api/notifications/stream`
-  - `GET /api/session-activity`
-  - `GET /api/sessions/snapshot`
-  - `GET /api/sessions/status`
-  - `GET /api/sessions/:id/status`
-  - `GET /api/sessions/attention`
-  - `GET /api/sessions/:id/attention`
-  - `POST /api/sessions/:id/view`
-  - `POST /api/sessions/:id/unview`
-  - `POST /api/sessions/:id/message-sent`
-
-### Trigger runtime API (runtime.js)
-- `createNotificationTriggerRuntime(dependencies)`: creates runtime-owned debounced trigger handling for OpenCode events.
-- Returned API:
-  - `maybeSendPushForTrigger(payload)`
-- Owns:
-  - completion/error/question/permission trigger routing; permission suppression consults the authoritative permission-auto-accept runtime
-  - session parent cache for subtask suppression
-  - template resolution and fallback behavior
-  - native notification fanout and web push payload fanout
-  - push suppression while any fresh UI visibility heartbeat reports a focused client
-
-### Push runtime API (push-runtime.js)
-- `createPushRuntime(dependencies)`: creates runtime for web push and UI visibility state.
-- Returned API:
-  - `getOrCreateVapidKeys()`
-  - `ensurePushInitialized()`
-  - `setPushInitialized(value)`
-  - `addOrUpdatePushSubscription(uiSessionToken, subscription, userAgent)`
-  - `removePushSubscription(uiSessionToken, endpoint)`
-  - `sendPushToAllUiSessions(payload, options?)`
-  - `updateUiVisibility(token, visible)`
-  - `isAnyUiVisible()`
-  - `isUiVisible(token)`
-
-### APNs runtime API (apns-runtime.js)
-- `createApnsRuntime(dependencies)`: creates runtime for native iOS APNs push and device-token state. Dependencies: `fsPromises`, `path`, `crypto`, `http2`, `APNS_TOKENS_FILE_PATH`, `readSettingsFromDiskMigrated`, `writeSettingsToDisk` (persists the auto-generated relay signing keypair).
-- Returned API:
-  - `addOrUpdateApnsToken(uiSessionToken, deviceToken, userAgent, platform, environment)` — also binds a newly-seen token on the relay (signed `/v1/push/register-token`). `environment` is the APNs environment the token was minted for (`sandbox` for Xcode/dev-signed installs, `production` otherwise — reported by the client at registration); delivery groups tokens by it.
-  - `removeApnsToken(uiSessionToken, deviceToken)`
-  - `removeApnsTokenFromAllSessions(deviceToken)`
-  - `sendApnsToAllUiSessions(payload)` — signs + sends to all registered tokens (no UI-visibility gate; iOS suppresses the foreground banner). No-ops with a single warning when APNs is unconfigured. Drops tokens on `410` / `BadDeviceToken` / `Unregistered`.
-  - `resolveApnsConfig()`
-- Configuration (env first, then `settings.apnsConfig`): `AIWORKER_APNS_KEY_ID`, `AIWORKER_APNS_TEAM_ID`, `AIWORKER_APNS_P8` (PEM contents; literal `\n` accepted) or `AIWORKER_APNS_P8_PATH`, `AIWORKER_APNS_BUNDLE_ID` (default `com.aiworker.app`), `AIWORKER_APNS_ENVIRONMENT` (optional override forcing every send to `sandbox` or `production`; when unset, each token is delivered to the environment it registered with, defaulting to `production` for tokens without one).
-
-### Emitter runtime API (emitter-runtime.js)
-- `createNotificationEmitterRuntime(dependencies)`: creates runtime for unified notification emission channels.
-- Returned API:
-  - `writeSseEvent(res, payload)`
-  - `emitDesktopNotification(payload)`
-  - `broadcastUiNotification(payload)`
-
-### Template runtime API (template-runtime.js)
-- `createNotificationTemplateRuntime(dependencies)`: creates shared notification/template runtime. Model-backed summarization was retired after the Zen provider became unavailable.
-- Returned API:
-  - `resolveNotificationTemplate(template, variables)`
-  - `shouldApplyResolvedTemplateMessage(template, resolved, variables)`
-  - `fetchFreeZenModels()` compatibility stub returning `[]`
-  - `resolveZenModel(override)` compatibility stub preserving stored values without validation
-  - `validateZenModelAtStartup()` compatibility no-op
-  - `summarizeText(text, targetLength, zenModel)` compatibility stub returning local fallback text
-  - `extractLastMessageText(payload, maxLength?)`
-  - `fetchLastAssistantMessageText(sessionId, messageId, maxLength?)`
-  - `maybeCacheSessionInfoFromEvent(payload)`
-  - `buildTemplateVariables(payload, sessionId)`
-  - `getCachedZenModels()`
-
-## Constants
-
-### Default values
-- `DEFAULT_NOTIFICATION_MESSAGE_MAX_LENGTH`: 250 (default max length for notification text).
-- `NOTIFICATION_SSE_HEARTBEAT_INTERVAL_MS`: 20000 (notification SSE comment heartbeat interval).
-
-## Settings object format
-
-The `settings` parameter for `prepareNotificationLastMessage` supports `maxLastMessageLength` (number), the maximum length for the final notification text (default: 250). Legacy summarization settings may still exist in persisted settings but are ignored.
-
-## Response contracts
-
-### `truncateNotificationText`
-- Returns empty string for non-string input.
-- Returns original text if under max length.
-- Returns `${text.slice(0, maxLength)}...` for truncated text.
-
-### `prepareNotificationLastMessage`
-- Returns empty string for empty/null message.
-- Returns truncated original message. Model-backed notification summarization is retired.
-- Normalizes markdown-like formatting to plain text before truncation.
-- Always applies `maxLastMessageLength` truncation to final result.
-
-## Notes for contributors
-
-### Adding new notification helpers
-1. Add new helper functions to `packages/web/server/lib/notifications/message.js`.
-2. Export functions that are intended for public use.
-3. Follow existing patterns for input validation (e.g., type checking for strings).
-4. Use `resolvePositiveNumber` for numeric parameters with fallbacks to maintain safe defaults.
-5. Add corresponding unit tests in `packages/web/server/lib/notifications/message.test.js`.
-
-### Error handling
-- `prepareNotificationLastMessage` does not call model summarization.
-- Invalid numeric parameters default to safe fallback values.
-- Non-string inputs are handled gracefully (return empty string).
-
-### Testing
-- Run `bun run type-check`, `bun run lint`, and `bun run build` before finalizing changes.
-- Unit tests should cover truncation behavior and edge cases (empty strings, invalid inputs).

package/server/lib/openchamber-control/DOCUMENTATION.md.bak

@@ -1,64 +0,0 @@
-# AiWorker Control Service
-
-## Purpose
-
-This module owns the typed control contract shared by the AiWorker CLI and
-the managed OpenCode `aiworker` tool. Both adapters delegate to
-`createAiWorkerControlService()`; neither adapter may call or spawn the
-other.
-
-## Boundaries
-
-- `service.js` validates and executes the fixed project, model, session, and
-  scheduled-task action allowlist. `actions.js` marks CLI-only actions with
-  `agentExposed: false` (currently `schedule.status`); the agent tool consumes
-  the filtered `AIWORKER_AGENT_TOOL_*` exports. `schedule.toggle` requires
-  the `disabled` boolean and replaces separate enable/disable actions;
-  `schedule.list` also returns scheduler status as `scheduler`.
-- `routes.js` is the authenticated CLI HTTP adapter. It forwards one action,
-  preserves service status and partial-result details, and propagates request
-  cancellation.
-- `../agent-tool/runtime.js` is the managed-tool adapter. It wraps service
-  results in the versioned native-tool envelope and uses a separate ephemeral
-  loopback credential.
-- `../openchamber-sessions/routes.js` and `../scheduled-tasks/service.js` own
-  their domain operations and are composed into this service.
-
-## Invariants
-
-- Session status and messages come from official directory-scoped OpenCode
-  APIs. Message output includes only ordered `text` parts.
-- Wait never treats an initial idle response as completion after dispatch. It
-  requires observed activity or a newly completed assistant message.
-- Timeout and cancellation are failures, never authoritative idle results.
-- Validation that protects side effects runs before session creation or
-  dispatch. An explicitly requested model, agent, or variant is checked against
-  the directory's own OpenCode agent and provider lists before any session,
-  worktree, or goal is created, because `prompt_async` accepts an unusable
-  selection and then fails only on the event stream. A failed or empty lookup
-  never turns a valid selection into a rejection.
-- `promptDispatched` reports an observed dispatch, never an accepted request.
-  After `prompt_async` the service confirms a new user message reached the
-  session; when it does not, the result reports `promptDispatched: false` with
-  `promptError` instead of claiming success.
-- Send and fork dispatches without an explicit model/agent/variant reuse the
-  target session's last user-message selection before falling back to the
-  configured defaults; only session creation resolves defaults directly.
-- Usage errors name the missing or conflicting input so CLI and agent-tool
-  callers can correct an invalid request without an upfront usage manual.
-- Explicit `projectId` or `directory` scope takes precedence over the managed
-  tool's current-session directory fallback; the fallback never creates a
-  conflicting second scope.
-- One failed directory status lookup produces `unknown` for only that
-  directory and does not erase other session results.
-- Destructive session/worktree deletion and project-path registration are not
-  part of the action contract.
-- `browser.capture` writes its image on the server, into
-  `.aiworker/screenshots/` under the scoped project directory, and returns
-  the project-relative path rather than the image bytes. The client that took
-  the picture may be on a different machine than the repository, and a path is
-  what an answer, a commit, or a review can use; base64 in a tool result cannot
-  be any of those. The agent's label is reduced to a filename fragment, never
-  used as a path. The result also states how to present the image, because chat
-  renders the image paths written in a finished answer below that message —
-  saving the file is not what shows it to anyone.