# Local LLM diagnosis bridge

The local bridge sends one selected BugTape occurrence to a model that runs on
your computer. BugTape stores the run and its result. BugTape does not receive
the model URL, model key, source code, shell access, or a GitHub token.

This first release is a staged, diagnosis-only feature. Each project has its
own rollout switch. New projects start with the switch off.

## What one click does

1. A user opens one issue and selects one occurrence.
2. BugTape creates a redacted packet for that occurrence.
3. The local bridge pulls one leased packet over outbound HTTPS.
4. The bridge sends the packet to a loopback Ollama or OpenAI-compatible API.
5. The bridge returns one bounded diagnosis.
6. BugTape shows the result and the durable run timeline on the issue.

The run cannot edit files, run commands, create a branch, open a pull request,
or write to GitHub. It has one attempt. A lost lease, cancellation, expired
key, revoked key, or removed project grant stops the run.

## Pair a project

Open **Settings → Agents**, select the project, and choose **Connect local
LLM**. Enter a name and start pairing. BugTape shows a one-use code and a
pinned `npx` command.

Run the command in a terminal. It reads the code through a hidden terminal
prompt. The code does not enter the command line, URL, browser storage,
or shell history. Compare these four values in the terminal and console:

- bridge fingerprint;
- BugTape origin;
- project ID;
- `diagnose only` capability.

Confirm only when all four values match. The bridge stores its project key in
`~/.config/bugtape-agent/store.json`. The directory mode is `0700`; the file
mode is `0600`.

If the first heartbeat response is lost, the saved key remains in the store.
Run the worker command shown in the console to retry activation. Replace the
pairing only when the CLI says that it could not save the key.

## Start an Ollama worker

Replace the model placeholder with a model that is already installed in
Ollama:

```text
npx --yes --package=https://app.bugtape.ai/sdk/agent-bridge/0.1.0/bugtape-agent-bridge-0.1.0.tgz bugtape-agent bridge start --bridge <bridge-id> --adapter ollama --base-url http://127.0.0.1:11434 --model <installed-model>
```

The bridge accepts only loopback model URLs. It opens no listener. Use
`--bridge <id>` for one saved bridge or `--all` for every saved bridge.

For a local OpenAI-compatible server:

```text
BUGTAPE_PROVIDER_KEY=<local-key-if-required> npx --yes --package=https://app.bugtape.ai/sdk/agent-bridge/0.1.0/bugtape-agent-bridge-0.1.0.tgz bugtape-agent bridge start --bridge <bridge-id> --adapter openai-compatible --base-url http://127.0.0.1:1234 --model <model>
```

The provider key stays inside the local process. The bridge never adds it to a
BugTape request or log.

## Test the connection

The fake adapter proves pairing, pull, lease, callback, and timeline without a
model call:

```text
npx --yes --package=https://app.bugtape.ai/sdk/agent-bridge/0.1.0/bugtape-agent-bridge-0.1.0.tgz bugtape-agent bridge start --bridge <bridge-id> --adapter fake --once
```

Its result starts with `SIMULATED DIAGNOSIS (connection test only)`. It is not
evidence that a model diagnosed the issue.

## Packet limits and privacy

The packet contains the selected report, selected occurrence fields, and up to
120 allowlisted events. It has a 64 KiB limit. Each event has a 16 KiB limit.
BugTape removes URL credentials, query strings, fragments, cookies,
authorization values, session and CSRF values, JWT-like values, opaque secret
forms, and email addresses. Paths become short hash values for correlation.
DOM payloads, custom event payloads, attachments, and file bytes stay in
BugTape unless the packet allowlist includes them.

The issue page shows source-evidence bytes, delivered packet bytes, redacted
value count, and truncation. Every packet field remains untrusted model input.
The adapter uses a separate system message that tells the model to treat packet
text as data.

The result can contain a summary, confidence, references to the exact
occurrence and included event IDs, and a test plan. The server rejects source
changes, commands, another occurrence, a stale lease, a changed replay, or a
result above 64 KiB.

## Key authority

Pairing creates one key with only the `repair_run` action and one project
grant. Normal key management cannot widen its actions, add another project, or
extend its expiry. An admin or manager can shorten its expiry or revoke it.
Revocation stops the next heartbeat or request. The bridge removes its local
copy after a definitive invalid, forbidden, or revoked response.

## Run states

The console keeps these states after reload:

`packet_ready → delivered → acknowledged → diagnosing → diagnosis_ready`

A run can instead end as `canceled` or `failed_terminal`. Lease expiry is
terminal and does not start a second model call. BugTape may retry one uncertain
HTTP command with the same command ID. It never retries the model call.