# DSH ⇄ ChatGPT Fusion Gateway

A minimal MCP bridge that keeps [DeepSeek Harness](https://www.deepseek.com) (DSH) as the
**single agent and runtime**, and uses **ChatGPT Web** only as a stateless, single-turn
*reasoning provider*.

DSH owns agents, tools, permissions, sessions, compaction, subagents, workflows, goals,
and real file/shell execution. The gateway simply relays one immutable DSH context
snapshot to a ChatGPT "Brain" conversation, and relays back exactly one decision — a final
answer, one action proposal, or a bounded read-only batch. The Gateway never executes the
proposed action itself.

```
User
 ↓
DSH UI
 ↓
DSH Native Agent Loop  →  Context / Compaction
 ↓
ChatGPT Fusion LLM Adapter
 ↓
Fusion Reasoning Gateway          ← this repository
 ↓
ChatGPT Brain Worker              (a dedicated ChatGPT Web conversation + optional wake extension)
 ↓
final | action_proposal | readonly_batch
 ↓
Gateway validation
 ↓
DSH Permissions / ToolRuntime  →  DSH Native Tool  →  Next DSH Tick
```

## Features

- **Strict one-result reasoning contract** — every request carries one complete, immutable
  snapshot; the Brain returns exactly one terminal result (`final`, `action_proposal`, or a
  bounded `readonly_batch` of read/glob/grep).
- **Recoverable delivery** — requests are journaled to disk; a crashed Gateway restores
  in-flight claims instead of losing them. Retries are idempotent via snapshot + nonce.
- **Multi-worker failover** — several Brain conversations can back the same model route;
  a stalled claim is released and re-delivered to a healthy standby with a rotated nonce.
- **OAuth 2.0 (loopback)** — optional authorization for the public ChatGPT connector
  (`/brain-mcp`), with rotating access/refresh tokens.
- **Cross-platform** — the gateway and Node daemon run on Linux, macOS, and Windows.
- **Optional browser wake** — a Chrome extension (`browser-autowake/`) polls loopback
  queue metadata and wakes a route-bound Brain tab when work is waiting.

## Requirements

- [Node.js](https://nodejs.org) **18+** (uses the global `fetch`).
- `git` (and, on Linux, your configured command user) for the workspace tools.

DSH itself must be available for the DSH-native agent loop and tool runtime; the gateway
detects the DSH-bundled `node_modules` automatically, or you can point it there with the
`DSH_NODE_MODULES` environment variable.

## Quick start

```bash
git clone <your-repo-url>
cd dsh-chatgpt-mcp
npm install
```

Put real credentials into `config.json` and `model-bindings.json` (all values ship as
`REDACTED_*` placeholders), then start:

```bash
npm run daemon:start     # background, supervised with auto-restart
npm run daemon:status
```

…or run in the foreground:

```bash
npm start                # node server.strict.cjs
```

The gateway binds `http://127.0.0.1:7688`. Detailed architecture and invariants live in
[`ARCHITECTURE.md`](ARCHITECTURE.md).

## Configuration

### `config.json`

| Key | Meaning |
| --- | --- |
| `host` / `port` | Loopback bind address (default `127.0.0.1:7688`). |
| `workspaceRoot` | Project workspace the tools may access. `.` = the project root. |
| `ownerPassword` | Owner password for OAuth authorization (≥ 16 chars). |
| `staticToken` | Static bearer token for the loopback Brain MCP (≥ 32 chars). |
| `allowedPrograms` | Executables the workspace `run_command` tool may launch. |
| `commandUser` | Linux-only: user the sandboxed commands drop to via `setpriv`. |

`ownerPassword`, `staticToken`, and the binding keys are **required** and must be filled in
before use. On macOS/Windows there is no portable setuid helper, so sandboxed commands run
as the current user and `commandUser` is ignored.

### `model-bindings.json`

Maps each `modelId` + `reasoningEffort` route to a `bindingKey`. The `bindingKey` is the
secret shared with the matching `brain-worker-*.txt`; keep both in sync.

## Service control

Works identically on Linux, macOS, and Windows:

```bash
node scripts/daemon.mjs start      # start detached supervisor + server
node scripts/daemon.mjs stop
node scripts/daemon.mjs restart
node scripts/daemon.mjs status
```

These are also exposed as `npm run daemon:start|stop|restart|status`. Linux-only
`screen`-based scripts remain in `scripts/` (`control.sh`, `public_quick.sh`, …) for
Cloudflare quick-tunnel and the headless Chrome worker pools.

## Reasoning protocol (v4)

The gateways speaks a strict protocol to the ChatGPT "Brain":

```
fusion_wait_for_reasoning_request  →  one immutable snapshot + data-only action catalog
fusion_submit_reasoning_result     →  exactly one {final} | {action_proposal} | {readonly_batch}
fusion_fail_reasoning_request      →  terminal failure for the assigned snapshot
```

`actionCatalog` is *data only* — a description of the DSH native tools, never installed as
ChatGPT/MCP tools. An `action_proposal` is a recommendation that DSH later executes under
its own permission/sandbox policy; the Gateway does not run it.

The public endpoint is `GET|POST /brain-mcp`. The former `/mcp` and `/fusion/tasks…`
routes return `HTTP 410` (disabled).

## Permissions

Uses the native three-level DSH model — `read-only`, `workspace-write`,
`danger-full-access` — with `workspace-write` as the default.

## Repository layout

```
server.strict.cjs        active gateway (strict v4; no legacy /mcp)
server.cjs               full gateway incl. workspace file/shell tools
config.json              runtime configuration (secrets are placeholders)
model-bindings.json      modelId → bindingKey map
scripts/daemon.mjs       cross-platform daemon (start/stop/restart/status)
scripts/*.sh             Linux deployment helpers (screen, cloudflared, Chrome workers)
brain-worker-*.txt       per-route prompts for dedicated Brain conversations
browser-autowake/        optional Chrome extension that wakes Brain tabs
tests/                   selftests and headless integration workers
state/  logs/            runtime artifacts (gitignored)
```

## Testing

```bash
npm install
node tests/reasoning-contract-v4-selftest.mjs   # primary protocol test
# …plus oauth, worker-recovery, failover, context-overflow, payload-limit selftests
```

See the `## Verification` section of the implementation notes for the full matrix.

## Security notes

- Bind to `127.0.0.1` by default; only the quick-tunnel script exposes a public URL.
- Do **not** commit `config.json` or `model-bindings.json` with real secrets — this
  repository ships placeholders for that reason.
- `/bin/setpriv` is used on Linux to drop sandboxed commands to `commandUser`; on other
  platforms commands run as the current user.

---

*DSH ⇄ ChatGPT Fusion is a community bridge and is not affiliated with or endorsed by
OpenAI or DeepSeek. Use of ChatGPT is subject to OpenAI's terms of service.*