@gakim-digital/dexter-bridge 0.5.21 → 0.11.1

package/README.md

@@ -1,35 +1,121 @@
 # Local Agent Bridge
 
 Local bridge CLI for InstaWebAI and Dexter. It connects a user's existing
-Claude Code or Codex login without sending those login credentials to
-InstaWebAI.
+Codex, Claude Code, or OpenCode setup without sending those login credentials
+to InstaWebAI.
 
-The two products share the bridge package but not their pairing state:
-
-- InstaWebAI App Builder uses the `app-builder` connection scope and dedicated
-  `~/.dexter-bridge/app-builder-*` configuration directories.
-- Dexter uses the `framer` connection scope and its standard bridge
-  configuration.
-- The API assigns the product identity during pairing. The CLI does not accept
-  a flag that can change one product's connection into the other.
+The two products share the bridge package but not their pairing state. The API
+assigns the product identity during pairing; the CLI cannot turn one product's
+pairing code into another product's connection.
 
 ## InstaWebAI App Builder
 
-The App Builder Connections page generates a complete command. Run it in a
-terminal and keep it open while building:
+The Connections page offers separate Codex, Claude Code, and OpenCode cards.
+Choose an agent, copy its command, and keep that terminal open while building:
 
 ```bash
 npx --yes @gakim-digital/dexter-bridge@latest connect 123456 \
   --api https://api-insta.instawebai.com/iwm-api/0.0.1 \
-  --agent codex \
-  --model codex:gpt-5.5 \
-  --config-dir ~/.dexter-bridge/app-builder-codex
+  --runtime codex
 ```
 
-Claude Code and Codex use separate App Builder config directories so both
-bridges can remain connected at the same time. A connection is considered
-online only after the command claims its short-lived pairing code and begins
-authenticated polling.
+Use `--runtime claude-code` or `--runtime opencode` for the other cards. The
+CLI automatically stores each connection in an isolated directory under
+`~/.dexter-bridge/app-builder/`, so any combination of the three agents can be
+connected at the same time. The selected runtime must already be installed and
+signed in or configured on the same computer.
+
+The pairing session is scoped to the runtime selected in InstaWebAI. A modified
+command cannot claim the pairing code for a different runtime.
+
+## Dexter for Framer
+
+Dexter Framer runs are harness-first. The API sends one scoped outcome
+assignment to the connected Codex, Claude Code, or OpenCode runtime. That
+harness inspects and edits the selected Framer project directly through the
+official `@framer/agent` connection while the plugin remains the chat,
+progress, cancellation, and result interface.
+
+The Framer harness receives only these project-scoped tools:
+
+- `framer_instructions` and `framer_context`
+- `framer_read_project`, `framer_verify_interactions`, and `framer_apply_changes`
+- restricted `framer_read` and `framer_write`
+- `progress_update`
+
+Native shell, filesystem, web, and unrelated-project access are disabled for
+Framer outcome runs. Publishing is denied unless a future assignment explicitly
+authorizes it.
+
+Bridges advertise `framer-interaction-verification-v1`,
+`framer-behavior-contract-v1`, and `framer-mechanism-verification-v1` only
+when interaction work is declared as observable behavior, checked against the
+selected Framer mechanism before mutation, and verified from live canonical
+Framer nodes afterward. Repeated behavior is verified on one representative
+target before the remaining targets are changed.
+
+Project connection is handled inside Dexter and completes before the model
+starts:
+
+- The plugin reads the exact active project or branch URL directly from Framer.
+- The user adds a Framer project API key once in Dexter. The API verifies it
+  through Framer's documented `connect(projectId, apiKey)` plus
+  `getProjectInfo()` flow, then encrypts and stores it only after that succeeds.
+- The active hosted runtime redeems that verified credential only for the
+  matching run and device, then installs it with Framer’s official
+  `project auth` command against the authoritative 20-character project ID.
+- The runtime opens an official Framer Agent session, reads the active branch
+  back from Framer, and confirms the authoritative project ID again.
+- Rejected credentials are revoked. Replacing a key creates a new credential
+  version, so a cached runtime session cannot reuse the replacement.
+- Hosted worker images bundle the Framer skills and seed them into each
+  runtime's private writable home before processing runs.
+
+The user never runs `@framer/agent setup`, `project auth`, or `session new`.
+The raw project credential is scoped to the matching active run and paired
+device, is excluded from run payloads and logs, and is never sent to the Framer
+plugin after the one-time authenticated submission.
+
+The bridge reports provider token usage on terminal events, including
+interrupted and cancelled runs. Claude-reported
+dollar cost is stored when available; Codex token-only runs are priced by the
+API’s model cost catalog so they no longer appear as zero-cost runs.
+
+On macOS, the bridge holds an idle-sleep assertion only while a claimed run is
+active, then releases it immediately afterward. Closing a laptop lid can still
+suspend local processes; uninterrupted lid-closed execution requires running
+the bridge on an always-on machine or a hosted harness runner.
+
+For App Builder runs, planning remains server-owned. Once the workflow
+contract, data model, dependencies, and design direction are ready, the bridge
+receives one bounded product outcome plus a disposable source snapshot. The
+selected harness implements the complete functional outcome in that isolated
+workspace. The API then validates and applies the changed files and runs its
+own type, authorization, API-contract, browser-workflow, responsive, and visual
+checks. A failed verification is returned as one grouped repair brief, with at
+most three complete attempts before the saved workspace is paused for review.
+
+Every supported coding harness receives the same seven tools:
+
+- `workspace_inspect` and `workspace_sync` for the disposable source tree.
+- `shell_run` for package installation, code generation, tests, builds, and
+  other project commands in the isolated build worker.
+- `preview_control` and `browser_control` for the live application.
+- `data_inspect` for owner-scoped, redacted development data.
+- `verification_run` for deterministic and browser workflow checks.
+
+Codex receives these as native dynamic tools. Claude Code and OpenCode receive
+the same contract through a local, token-protected MCP bridge. Commands never
+run through the bridge machine's shell. The API delegates them to a
+project-confined build worker with an offline default; only script-disabled npm
+dependency commands receive registry access. The API remains the authority for
+project ownership, protected platform files, data access, command execution,
+and final verification.
+
+When a dependency requires a lifecycle build, the harness can run `npm rebuild`
+as a separate offline command after installation. This allows package code to
+prepare itself without combining arbitrary script execution with internet
+access.
 
 ## Claude Code on macOS
 
@@ -107,11 +193,16 @@ DEXTER_BRIDGE_AGENT=claude-code npx @gakim-digital/dexter-bridge start
 DEXTER_BRIDGE_AGENT=codex npx @gakim-digital/dexter-bridge start
 ```
 
-Codex App Server runs as a model-only engine in a dedicated empty temporary
-workspace. Shell, app, hook, memory, multi-agent, MCP, plugin, image, and web
-tools are disabled; only a minimal non-secret environment is inherited. The
-CLI and desktop bridge keep one isolated app-server process alive across model
-turns.
+Codex App Server runs planning turns as a model-only engine in a dedicated
+empty temporary workspace. For an App Builder outcome, it receives a disposable
+snapshot and workspace-write access only inside that snapshot; network, app,
+hook, memory, multi-agent, MCP, plugin, image, and web access remain disabled.
+The bridge reads the effective Codex provider configuration and forwards only
+environment variables explicitly referenced by that provider, such as an
+`env_key`; unrelated process secrets remain excluded. The configured provider
+is preferred, with a cached OpenAI/ChatGPT account used as a fallback when its
+required provider credentials are unavailable. Planning sessions may be reused;
+each coding outcome uses a fresh isolated workspace.
 The bridge retains at most 32 recent Codex threads by default; override this
 with `DEXTER_BRIDGE_CODEX_MAX_THREADS`.
 
@@ -124,11 +215,13 @@ for visibility.
 Production API endpoints must use HTTPS. Plain HTTP is accepted only for exact
 localhost loopback addresses during local development.
 
-Claude Code is launched as a model-only engine: local tools, slash commands,
-MCP integrations, browser access, and project-agent context are disabled. The
-bridge supplies a strict JSON schema and a product-specific system prompt
-tool requests to be returned as structured output instead of being executed
-inside Claude Code.
+Claude Code planning turns run as a model-only engine. App Builder outcome runs
+enable local read/write/edit/search tools inside the disposable snapshot plus
+the strict InstaWebAI MCP tool set. Shell checks, previews, browser actions,
+redacted data inspection, and verification execute through the server-owned
+workspace boundary; local shell, network, and external-directory access
+stay disabled. The bridge supplies a strict JSON schema and a product-specific
+system prompt.
 
 Claude Code runs use streaming JSON and Codex runs use JSONL so the bridge can
 report input, output, cache, and reasoning tokens even when a turn is
@@ -164,9 +257,10 @@ desktop window to open that folder.
 Useful events in a stuck run:
 
 - `model_turn` / `agent_process_spawn` — Claude Code or Codex was invoked.
+- `outcome` — a harness is implementing the complete bounded product outcome.
 - `agent_process_timeout` — the local agent did not return before the timeout.
 - `event_post_done` — the bridge returned a model completion to the shared server loop.
-- `run_done` — the local model turn completed.
+- `run_done` — the local model turn or outcome completed.
 
 ## Desktop release
 
@@ -210,10 +304,10 @@ Recommended release env:
 
 ```bash
 FRAMER_COMPANION_DOWNLOAD_URL=https://instawebai.com/dexter-bridge
-NEXT_PUBLIC_DEXTER_BRIDGE_VERSION=0.2.0
+NEXT_PUBLIC_DEXTER_BRIDGE_VERSION=0.11.1
 NEXT_PUBLIC_DEXTER_BRIDGE_DOWNLOAD_BASE_URL=https://instawebai.com/downloads/dexter-bridge
-NEXT_PUBLIC_DEXTER_BRIDGE_MAC_ARM64_URL=https://instawebai.com/downloads/dexter-bridge/Dexter-Bridge-0.2.0-mac-arm64.dmg
-NEXT_PUBLIC_DEXTER_BRIDGE_MAC_X64_URL=https://instawebai.com/downloads/dexter-bridge/Dexter-Bridge-0.2.0-mac-x64.dmg
-NEXT_PUBLIC_DEXTER_BRIDGE_MAC_ZIP_URL=https://instawebai.com/downloads/dexter-bridge/Dexter-Bridge-0.2.0-mac-universal.zip
-NEXT_PUBLIC_DEXTER_BRIDGE_WIN_X64_URL=https://instawebai.com/downloads/dexter-bridge/Dexter-Bridge-0.2.0-win-x64.exe
+NEXT_PUBLIC_DEXTER_BRIDGE_MAC_ARM64_URL=https://instawebai.com/downloads/dexter-bridge/Dexter-Bridge-0.11.1-mac-arm64.dmg
+NEXT_PUBLIC_DEXTER_BRIDGE_MAC_X64_URL=https://instawebai.com/downloads/dexter-bridge/Dexter-Bridge-0.11.1-mac-x64.dmg
+NEXT_PUBLIC_DEXTER_BRIDGE_MAC_ZIP_URL=https://instawebai.com/downloads/dexter-bridge/Dexter-Bridge-0.11.1-mac-universal.zip
+NEXT_PUBLIC_DEXTER_BRIDGE_WIN_X64_URL=https://instawebai.com/downloads/dexter-bridge/Dexter-Bridge-0.11.1-win-x64.exe
 ```

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@gakim-digital/dexter-bridge",
-  "version": "0.5.21",
-  "description": "Local bridge for InstaWebAI and Dexter — runs Codex or Claude Code on your machine.",
+  "version": "0.11.1",
+  "description": "Local bridge for InstaWebAI and Dexter — runs Codex, Claude Code, or OpenCode on your machine.",
   "type": "module",
   "bin": {
     "dexter-bridge": "bin/dexter-bridge.js"
@@ -16,14 +16,15 @@
     "test": "node --test"
   },
   "engines": {
-    "node": ">=18.17"
+    "node": ">=22"
   },
   "keywords": [
     "dexter",
     "framer",
     "instawebai",
     "codex",
-    "claude-code"
+    "claude-code",
+    "opencode"
   ],
   "homepage": "https://instawebai.com/dexter-bridge",
   "publishConfig": {
@@ -31,6 +32,19 @@
   },
   "license": "SEE LICENSE IN LICENSE",
   "dependencies": {
-    "cross-spawn": "^7.0.6"
+    "@framer/agent": "0.0.44",
+    "@ai-sdk/anthropic": "^4.0.46",
+    "@ai-sdk/deepseek": "^3.0.37",
+    "@ai-sdk/google": "^4.0.58",
+    "@ai-sdk/openai": "^4.0.52",
+    "@ai-sdk/openai-compatible": "^3.0.41",
+    "@ai-sdk/xai": "^4.0.50",
+    "@modelcontextprotocol/sdk": "^1.30.0",
+    "@opencode-ai/sdk": "^1.18.25",
+    "@openrouter/ai-sdk-provider": "^3.0.0",
+    "ai": "^7.0.85",
+    "cross-spawn": "^7.0.6",
+    "jsonrepair": "^3.15.0",
+    "zod": "^4.5.4"
   }
 }