@gotcos/glasses-server 6.3.1 → 6.6.0

package/.env.example

@@ -19,18 +19,34 @@ BIND_HOST=0.0.0.0
 # here for a stable token across restarts.
 # COS_API_TOKEN=pick-any-long-random-string
 
+# Optional durable image-store location. Defaults to
+# ~/.cos-glasses/data/media alongside the standalone conversation/archive data.
+# COS_MEDIA_ROOT=/path/on-a-local-volume/media
+
+# Optional logical server identity location. Most installs should keep the
+# default (~/.cos-glasses/server-instance-id) so reconnects can verify the same
+# server after Wi-Fi/Tailscale changes and process restarts.
+# COS_SERVER_INSTANCE_ID_PATH=/path/to/server-instance-id
+
 # ── THE LLM (chat) ──────────────────────────────────────────────────────
 # Chat runs through your LOCAL agent CLI — NOT an API key:
-#   Opus / Sonnet / Haiku  ->  Claude Code CLI  (https://claude.ai/download, then `claude login`)
-#   Codex High             ->  Codex CLI        (https://developers.openai.com/codex/, then `codex login`)
+#   Opus / Fable / Sonnet  ->  Claude Code CLI  (https://claude.ai/download, then `claude login`)
+#   GPT Frontier/Balanced  ->  Codex CLI        (https://developers.openai.com/codex/, then `codex login`)
 # Install at least one. Pick the default model the glasses use:
-# COS_G2_DEFAULT_MODEL=sonnet     # opus | sonnet | haiku | codex-high
+# COS_G2_DEFAULT_MODEL=sonnet     # opus | fable | sonnet | codex-frontier | codex-balanced
 #
-# Codex options (only used for the codex-high model):
-#   COS_CODEX_MODEL pins a specific codex model id; blank = use your codex CLI default.
-#   COS_CODEX_REASONING_EFFORT is low | medium | high (default high).
+# GPT slots refresh from the Codex model catalog every 15 minutes and retain
+# their last-known-good resolution if discovery is temporarily unavailable.
+# COS_CODEX_MODEL_REFRESH_TTL_MS=900000
+# COS_CODEX_MODEL_REFRESH_TIMEOUT_MS=7000
+#
+# Legacy explicit overrides remain supported for migrated codex-high/frontier
+# installs. Leave blank for auto-latest; Balanced always stays auto-catalog.
 # COS_CODEX_MODEL=
-# COS_CODEX_REASONING_EFFORT=high
+# COS_CODEX_REASONING_EFFORT=high   # low | medium | high | xhigh | max | ultra
+#
+# Codex remains read-only by default. This is the only broader trust opt-in:
+# COS_CODEX_SANDBOX=workspace-write
 
 # ── VOICE (optional) ────────────────────────────────────────────────────
 # Local transcription is FREE via whisper.cpp (brew install whisper-cpp; the

package/CHANGELOG.md

@@ -1,5 +1,113 @@
 # Changelog
 
+## 6.6.0
+
+Reconnect compatibility for COS Glasses build 188, without importing private
+COS day-context or Mac service-control behavior into the public package.
+
+- **Stable logical server identity.** The server creates one atomic UUID under
+  `~/.cos-glasses/server-instance-id`, preserves it across process and network
+  restarts, and returns it from authenticated `/api/models` probes. Files are
+  mode `0600`; identity is minted only after every required listener binds.
+- **Boot-scoped display cursors.** Display events receive one publish-owned ID
+  before fan-out, so multiple subscribers see the same cursor and cannot
+  duplicate replay records. Each process boot has a distinct UUID.
+- **Deterministic reconnect handshake.** `/api/display-stream` emits `ready`
+  before application events, accepts boot/event cursors, replays the last 200
+  publish-owned events, and reports typed `boot_changed`, `cursor_ahead`, or
+  `buffer_overflow` gaps so clients reconcile durable history instead of
+  guessing or silently dropping replies.
+- **Privacy boundary preserved.** Authenticated query activity remains off the
+  unauthenticated global display bus. The npm server does not include private
+  daily evidence exports, personal COS paths, launchd ownership, or remote
+  machine-restart controls.
+- **Backward compatible.** Older clients can continue opening the same SSE
+  endpoint and ignoring the additive `ready`, cursor metadata, and replay-gap
+  events.
+
+## 6.5.0
+
+Durable phone photos and assistant-selected output images for COS Glasses
+build 179, while preserving the public server's sandbox and privacy boundary.
+
+- **One media contract.** Authenticated phone uploads become opaque attachment
+  refs, survive queues/restarts/archives/numbered-message recall, and resolve to
+  normalized server-owned files for Claude/Codex. Bytes and storage paths never
+  enter SSE, run ledgers, or archives.
+- **Answer images.** Claude or Codex can publish an already-local generated,
+  researched, or explicitly used email image through a private run-scoped
+  capability. The server accepts JPEG/PNG/WebP/HEIC/HEIF/AVIF up to 16 MiB and
+  16 megapixels, strips metadata, re-encodes through the existing media store,
+  and appends refs to the completed answer.
+- **No mailbox or URL crawler.** The publisher rejects URLs, data URIs, base64,
+  unrelated discovery, symlinks, directory replacement, content-id tampering,
+  over-capacity output, and manifest fields that could carry private paths.
+- **Codex remains read-only.** Output publishing adds only the random private
+  run directory via `codex exec --add-dir`; global sandbox flags precede
+  `resume`. Older CLIs without `--add-dir` keep chat working and simply disable
+  Codex output-image publishing. There is no full-access fallback.
+- **Durable finalization.** Assistant text is persisted before image
+  normalization, request media associates even if SSE disconnects, partial
+  image failures do not discard successful refs, and completion emits one
+  canonical `attachments` list with safe aggregate stats.
+- **Lens contract.** `/api/health` advertises `mediaProcessingReady` and
+  `g2LensVariant=png-288x144-v1`; the media endpoint serves the validated phone,
+  thumbnail, and exact 288×144 G2 variants expected by build 179.
+- **Fresh-install diagnostics.** The npm launcher now reports whether ffmpeg is
+  ready for phone/output/lens images, gives a non-blocking install command when
+  absent, and sends setup questions directly to `gotcos.com/wizard/`.
+- **One server owner.** The public runner now claims the same atomic
+  machine-wide lock as the installed LaunchAgent before mutable modules load.
+  A duplicate exits with code 75, and HTTP/HTTPS listeners bind as one required
+  set: if either port is occupied, any earlier listener closes and the process
+  exits instead of surviving half-bound with separate SSE and media state.
+
+Release evidence: TypeScript, 130/130 tests across 23 files, package dry-run
+including the executable publisher and startup hardening, and a live duplicate
+start against the installed LaunchAgent rejected before server initialization.
+
+## 6.4.0
+
+Fresh-install parity for COS Glasses builds 170–173, without weakening the
+public server's sandbox defaults.
+
+- **Auto-updating GPT Frontier + Balanced.** Stable client slots resolve to the
+  top two capable models in the newest visible GPT generation through Codex's
+  official `model/list` catalog. The server refreshes at boot and every 15
+  minutes, and each Codex run awaits the same TTL-cached/coalesced refresh
+  before resolving its slot. It preserves the last-known-good catalog on
+  failures and falls back to the CLI default only before any discovery succeeds.
+- **Fable + effort controls.** Fable joins Opus and Sonnet as a first-class
+  Claude tier alias, and High / Extra High / Max / Ultracode now propagate from
+  `/api/query` to both Claude and Codex. Claude aliases remain versionless and
+  1M-context capable; Codex effort is clamped to each live model's advertised
+  support. Per-run ledgers record the concrete resolved model and effort.
+- **Safe live job activity.** `activityToolMode` supports off, status-only, or
+  bounded observable tool input/output previews. ANSI/control data, credential
+  assignments, auth headers, provider tokens, JWTs, URL credentials, and opaque
+  blobs are redacted, including 40–72-character PEM/private-key body chunks.
+  Hidden reasoning is never surfaced.
+- **Same-session run safety.** Turns for one conversation now serialize until
+  the active bridge sends a terminal callback, while different sessions remain
+  concurrent. Failed or cancelled Claude/Codex runs remove the exact pending
+  user exchange by object identity, preventing phantom prompts, duplicate-text
+  deletion, and resume-history contamination.
+- **Authenticated transport boundary.** Activity lines are returned only on the
+  authenticated `/api/query` SSE stream. They are deliberately excluded from
+  the unauthenticated global display bus and its replay buffer.
+- **Public trust model retained.** Codex remains read-only by default with only
+  the existing `workspace-write` opt-in. Existing archive traversal, local-day,
+  malformed-file, starter-kit launch-directory, and conversation behavior are
+  unchanged. Legacy `codex-high` state migrates to the frontier slot without
+  changing saved thread trust mode.
+- **Diagnostics and compatibility.** `/api/models`, health data, and `/v1/models`
+  expose stable slots plus concrete live models. `cos-codex-high` remains an
+  accepted alias for older clients. Existing `COS_CODEX_MODEL` and
+  `COS_CODEX_REASONING_EFFORT` overrides continue to apply to the migrated
+  legacy/frontier slot; leave them unset for auto-latest. A new regression suite covers catalog
+  selection/fallback/refresh, sandbox arguments, migrations, effort mappings,
+  activity redaction, and the display-bus security boundary.
+
 ## 6.3.1
 
 Security + robustness hardening on the 6.3.0 archive routes, from a 3-agent QA pass. (6.3.0 was never published; 6.3.1 is the first release of the expanded route set.)

package/README.md

@@ -1,7 +1,7 @@
 # COS Glasses Server
 
 Self-hosted AI heads-up display for **Even G2 smart glasses**. Runs on your Mac,
-talks to your local **Claude Code** CLI, and pushes answers, voice
+talks to your local **Claude Code or Codex** CLI, and pushes answers, voice
 transcription, and notes to the lens. Your data never leaves your machine, and no
 API key is pasted into the phone for chat.
 
@@ -11,22 +11,34 @@ API key is pasted into the phone for chat.
 npx @gotcos/glasses-server
 ```
 
-The launcher checks Node, finds your CLI, downloads the local voice model, writes
-`~/.cos-glasses/.env`, and starts the server on `0.0.0.0:3141`. On boot it prints
-an **API token** — paste that into the COS Glasses app.
+The launcher checks Node, finds your CLI, checks voice and image processing,
+downloads the local voice model when needed, writes `~/.cos-glasses/.env`, and
+starts the server on `0.0.0.0:3141`. On boot it prints
+an **API token** — paste that into the COS Glasses app. Only one COS Glasses
+server may run on a Mac at a time; a second `npx` or source runner exits before
+opening ports or touching shared conversation/media state. Version 6.6.0 also
+gives that server a durable identity and boot-scoped display replay, allowing
+build 188+ to reconnect after a Tailscale, Wi-Fi, or process interruption
+without silently losing completed replies.
 
 ## Requirements
 
 - **Node.js 20.11+** — https://nodejs.org
-- **Claude Code CLI** (Opus/Sonnet/Haiku) — https://claude.ai/download, then `claude login`
-  _or_ **Codex CLI** (Codex High) — https://developers.openai.com/codex/, then `codex login`
+- **Claude Code CLI** (Opus/Fable/Sonnet) — https://claude.ai/download, then `claude login`
+  _or_ **Codex CLI** (GPT Frontier/Balanced) — https://developers.openai.com/codex/, then `codex login`
 - **Even G2 glasses** + the **COS Glasses** app from the Even Hub
 - _Optional:_ `brew install whisper-cpp` for free local voice (otherwise OpenAI API)
+- _Optional:_ `brew install ffmpeg` for phone/output image attachments (text chat remains available without it)
 - _Optional:_ **Tailscale** so your phone reaches your Mac from anywhere
 
 > No `ANTHROPIC_API_KEY` is needed — chat runs through your installed CLI, billed
 > to your existing Claude or Codex subscription. Pick either per query, or set a
-> default with `COS_G2_DEFAULT_MODEL` (`opus`|`sonnet`|`haiku`|`codex-high`).
+> default with `COS_G2_DEFAULT_MODEL` (`opus`|`fable`|`sonnet`|`codex-frontier`|`codex-balanced`).
+> Claude tier aliases and the two GPT slots resolve dynamically, so new model
+> releases do not require a new glasses package. GPT discovery refreshes every
+> 15 minutes and retains its last-known-good catalog through transient failures.
+> Existing `COS_CODEX_MODEL` / `COS_CODEX_REASONING_EFFORT` settings remain
+> supported on the migrated Frontier slot; leave them blank for auto-latest.
 > Codex runs **sandboxed read-only** by default (`COS_CODEX_SANDBOX` to adjust).
 
 ## Connect your phone (the one gotcha)
@@ -44,8 +56,13 @@ The built-in IP allowlist blocks public-internet traffic regardless.
 ## What it does
 
 - Ask anything, get a streamed answer on the lens (`/api/query`, `/v1/chat/completions`)
+- Choose Opus, Fable, Sonnet, GPT Frontier, or GPT Balanced plus High, Extra
+  High, Max, or Ultracode effort; optional redacted tool activity streams only
+  to the authenticated query that requested it
 - Message History + cross-day "reference message N" — your chats are archived by day
   and every message keeps a permanent number you can recall (`/api/archive`, `/api/message/:num`)
+- Send phone photos with queued prompts, and review assistant-selected generated,
+  research, or explicitly used email images in Messages and on the G2 lens
 - Live voice capture + transcription during meetings
 - Local whisper.cpp transcription (free) with OpenAI fallback (optional)
 - Tasks / calendar / people context **if** you run the
@@ -57,7 +74,8 @@ The built-in IP allowlist blocks public-internet traffic regardless.
 Config lives at `~/.cos-glasses/.env` (created on first run). Every key is
 optional except an installed CLI. Highlights: `BIND_HOST`, `PORT`,
 `COS_API_TOKEN` (auto if unset), `OPENAI_API_KEY` (cloud voice fallback),
-`COS_SCRIPTS_DIR` (full pipeline). Your name + transcription vocabulary live in
+`COS_SCRIPTS_DIR` (full pipeline), and `COS_MEDIA_ROOT` (optional image-store
+location; default `~/.cos-glasses/data/media`). Your name + transcription vocabulary live in
 `~/.cos-glasses/.cos-profile.json` (see `.cos-profile.example.json`).
 
 ## Run from source
@@ -72,8 +90,10 @@ BIND_HOST=0.0.0.0 npm run start:server
 ## Troubleshooting
 
 - *Phone can't connect* — check `BIND_HOST=0.0.0.0`, the same Tailscale account on both devices, and the correct `100.x` IP + token.
+- *Safari connects but the app does not* — confirm `npx @gotcos/glasses-server@latest` is 6.6.0+, then use the app's server reconnect/edit control to verify the current URL and token. Do not run a second source or `npx` server alongside it.
 - *AI queries fail* — run `claude --version` / `codex --version`, then `claude login` / `codex login`.
 - *Voice getting billed?* — install `whisper-cpp` for free local transcription.
+- *Photos unavailable?* — install `ffmpeg`, restart the server, and confirm `/api/health` reports `features.mediaProcessingReady: true`.
 
 ## License
 

package/bin/cli.cjs

@@ -34,13 +34,13 @@ if (process.argv.includes('--help') || process.argv.includes('-h')) {
   console.log('')
   console.log('  Requirements:')
   console.log('    - Node.js 20.11+')
-  console.log('    - Claude Code CLI (Opus / Sonnet / Haiku) or Codex CLI (Codex High)')
+  console.log('    - Claude Code CLI (Opus / Fable / Sonnet) or Codex CLI (GPT Frontier / Balanced)')
   console.log('    - Even G2 smart glasses + the COS Glasses app (Even Hub)')
   console.log('')
   console.log('  No API key is needed for chat — it runs through your installed CLI.')
   console.log('  Config persists at ~/.cos-glasses/.env')
   console.log('')
-  console.log('  Setup guide: https://www.gotcos.com')
+  console.log('  Setup guide: https://www.gotcos.com/wizard/')
   console.log('')
   process.exit(0)
 }
@@ -60,9 +60,9 @@ if (nodeMajor < 20 || (nodeMajor === 20 && nodeMinor < 11)) {
 console.log(green('  ✓') + ` Node.js ${process.versions.node}`)
 
 // Step 2: agent CLI detection — at least one of Claude Code / Codex is required
-function getCliVersion(command) {
+function getCliVersion(command, versionArg = '--version') {
   try {
-    return execSync(`${command} --version 2>&1`, { shell: '/bin/sh', stdio: 'pipe', timeout: 5000 }).toString().trim()
+    return execSync(`${command} ${versionArg} 2>&1`, { shell: '/bin/sh', stdio: 'pipe', timeout: 5000 }).toString().trim()
   } catch {
     return null
   }
@@ -75,15 +75,15 @@ function normalizeCodexVersion(raw) {
 const claudeVersion = getCliVersion('claude')
 const codexVersion = getCliVersion('codex')
 if (claudeVersion) {
-  console.log(green('  ✓') + ` Claude Code ${claudeVersion} ` + dim('(Opus / Sonnet / Haiku)'))
+  console.log(green('  ✓') + ` Claude Code ${claudeVersion} ` + dim('(Opus / Fable / Sonnet)'))
 } else {
-  console.log(yellow('  ⚠') + ' Claude Code CLI not found ' + dim('— Opus/Sonnet/Haiku unavailable'))
+  console.log(yellow('  ⚠') + ' Claude Code CLI not found ' + dim('— Opus/Fable/Sonnet unavailable'))
   console.log('    Install: ' + bold('https://claude.ai/download'))
 }
 if (codexVersion) {
-  console.log(green('  ✓') + ` Codex CLI ${normalizeCodexVersion(codexVersion)} ` + dim('(Codex High)'))
+  console.log(green('  ✓') + ` Codex CLI ${normalizeCodexVersion(codexVersion)} ` + dim('(GPT Frontier / Balanced)'))
 } else {
-  console.log(yellow('  ⚠') + ' Codex CLI not found ' + dim('— Codex High unavailable'))
+  console.log(yellow('  ⚠') + ' Codex CLI not found ' + dim('— GPT Frontier/Balanced unavailable'))
 }
 if (!claudeVersion && !codexVersion) {
   console.log('')
@@ -184,13 +184,25 @@ if (whisperCliPath && hasValidModel) {
   console.log('    Free local voice: ' + bold('brew install whisper-cpp') + dim('  (no Homebrew? https://brew.sh)'))
 }
 
-// Step 6: phone reachability — the glasses' phone app must reach this server.
+// Step 6: image capability — ffmpeg validates, strips metadata, normalizes,
+// and builds the exact 288x144 G2 variant. It is optional so text/voice remain
+// useful on a minimal install, but the launcher should make the gap visible.
+const ffmpegVersion = getCliVersion('ffmpeg', '-version')
+if (ffmpegVersion) {
+  const firstLine = ffmpegVersion.split('\n')[0].trim()
+  console.log(green('  ✓') + ` ${firstLine} ` + dim('— phone + lens images ready'))
+} else {
+  console.log(yellow('  ⚠') + ' ffmpeg not installed ' + dim('— phone and answer images disabled'))
+  console.log('    Enable photos: ' + bold('brew install ffmpeg') + dim('  (text + voice still work)'))
+}
+
+// Step 7: phone reachability — the glasses' phone app must reach this server.
 if (!process.env.BIND_HOST) {
   process.env.BIND_HOST = '0.0.0.0'
   console.log(yellow('  ⚠') + ' BIND_HOST not set — defaulting to 0.0.0.0 so your phone can reach the server')
 }
 
-// Step 7: start the bundled server
+// Step 8: start the bundled server
 try {
   const ld = process.env.COS_LAUNCH_DIR
   if (ld && (existsSync(join(ld, '.cos', 'manifest.json')) || existsSync(join(ld, 'AGENTS.md')) || existsSync(join(ld, 'CLAUDE.md')))) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gotcos/glasses-server",
-  "version": "6.3.1",
+  "version": "6.6.0",
   "description": "COS Glasses — self-hosted AI heads-up-display server for Even G2 smart glasses, powered by your local Claude Code or Codex CLI",
   "type": "module",
   "bin": {
@@ -9,14 +9,25 @@
   "scripts": {
     "start": "node bin/cli.cjs",
     "start:server": "node --import tsx/esm server/index.ts",
+    "test": "vitest run",
     "typecheck": "tsc --noEmit"
   },
-  "keywords": ["even-g2", "smart-glasses", "claude-code", "codex", "ai", "cos", "heads-up-display", "whisper"],
+  "keywords": [
+    "even-g2",
+    "smart-glasses",
+    "claude-code",
+    "codex",
+    "ai",
+    "cos",
+    "heads-up-display",
+    "whisper"
+  ],
   "files": [
     "bin/cli.cjs",
-    "server/**/*.ts",
-    "server/**/*.js",
-    "shared/**/*.ts",
+    "server",
+    "shared",
+    "!server/**/*.test.ts",
+    "!shared/**/*.test.ts",
     ".env.example",
     ".cos-profile.example.json",
     "README.md",
@@ -48,6 +59,7 @@
     "@types/cors": "^2.8.19",
     "@types/express": "^5.0.6",
     "@types/node": "^22.10.0",
-    "typescript": "^5.9.3"
+    "typescript": "^5.9.3",
+    "vitest": "^3.2.7"
   }
 }