@gakim-digital/dexter-bridge 0.5.20 → 0.11.0

package/README.md

@@ -1,6 +1,108 @@
-# Dexter Bridge
+# Local Agent Bridge
 
-Local Companion CLI for Dexter's Framer plugin.
+Local bridge CLI for InstaWebAI and Dexter. It connects a user's existing
+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. 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 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 \
+  --runtime codex
+```
+
+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` 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.
+
+Project connection is automatic and completes before the model starts:
+
+- The run carries the project ID that Dexter read from the open Framer project.
+- The bridge first reuses an active Framer Agent session or locally authorized
+  project.
+- If needed, the active paired device redeems the matching encrypted
+  per-project credential from the API and installs it through Framer’s official
+  CLI.
+- If no credential exists, or Framer rejects a stale one, Dexter opens Framer’s
+  browser authorization and resumes the same run automatically after approval.
+
+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.
+
+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
 
@@ -78,11 +180,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`.
 
@@ -95,11 +202,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 system prompt that requires Dexter
-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
@@ -135,9 +244,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
 
@@ -181,10 +291,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.0
 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.0-mac-arm64.dmg
+NEXT_PUBLIC_DEXTER_BRIDGE_MAC_X64_URL=https://instawebai.com/downloads/dexter-bridge/Dexter-Bridge-0.11.0-mac-x64.dmg
+NEXT_PUBLIC_DEXTER_BRIDGE_MAC_ZIP_URL=https://instawebai.com/downloads/dexter-bridge/Dexter-Bridge-0.11.0-mac-universal.zip
+NEXT_PUBLIC_DEXTER_BRIDGE_WIN_X64_URL=https://instawebai.com/downloads/dexter-bridge/Dexter-Bridge-0.11.0-win-x64.exe
 ```

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@gakim-digital/dexter-bridge",
-  "version": "0.5.20",
-  "description": "Local Companion bridge for the Dexter Framer plugin — runs Codex or Claude Code on your machine.",
+  "version": "0.11.0",
+  "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"
   }
 }