agents-relay 1.0.4 → 1.0.5

package/README.md

@@ -103,7 +103,7 @@ npx agents-relay submit --repo OWNER/REPO --pr 5 --id job-1 \
   --input "Research the dashboard UX and return implementation guidance."
 ~~~
 
-The adapter discovers `chatgpt-browser-worker/agents/browser-worker.agent.md` from `AGENTS_RELAY_CHATGPT_BROWSER_WORKER_AGENT` first, then `AGENTS_RELAY_SKILL_ROOTS`, `~/.codex/skills`, `~/.agents/skills`, and the local `skills` directory. It runs the definition and one typed JSON request through the configured local harness (`AGENTS_RELAY_AGENT_HARNESS`, default `codex`). Normal consumers do not need a Neo source checkout.
+The adapter discovers the packaged `chatgpt-browser-worker` skill from `AGENTS_RELAY_CHATGPT_BROWSER_WORKER_AGENT` first, then `AGENTS_RELAY_SKILL_ROOTS`, the package `skills` directory, `~/.codex/skills`, `~/.agents/skills`, and the local `skills` directory. It invokes that skill's Browser Harness drivers directly; it does not launch Codex, MacDeveloperBridge, or a ChatGPT API transport. Normal consumers do not need a Neo source checkout.
 
 GitHub PR state is authoritative for terminal lifecycle: a merged PR reconciles its managed job to `COMPLETED`; a closed, unmerged PR reconciles to `CANCELLED` and cannot launch queued work. The dashboard exposes `/api/jobs` and shows repository-wide managed PR state beside each durable Agents Relay job state so stale markers are visible instead of being mistaken for current truth.
 

package/dist/adapters.js

@@ -1,7 +1,8 @@
 import { spawn } from 'node:child_process';
 import { access, readFile, readdir } from 'node:fs/promises';
 import { homedir } from 'node:os';
-import { join } from 'node:path';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
 import { randomUUID } from 'node:crypto';
 function commandExecution(child, output, signal, id) { const promise = new Promise((resolve, reject) => { child.on('error', reject); child.on('close', code => code === 0 ? resolve({ summary: output().trim() || 'Command completed' }) : reject(new Error(output().trim() || `Command exited ${code}`))); signal.addEventListener('abort', () => child.kill('SIGTERM'), { once: true }); }); return { id, promise, cancel: () => { child.kill('SIGTERM'); } }; }
 export function buildCodexArgs(route, input) {
@@ -151,17 +152,20 @@ export class CodexAdapter {
         return null;
     }
 }
+export class LaunchFailure extends Error {
+}
 function browserWorkerCandidates(explicit) {
     const roots = (process.env.AGENTS_RELAY_SKILL_ROOTS ?? '').split(':').filter(Boolean);
-    return [explicit, ...roots, join(homedir(), '.codex', 'skills'), join(homedir(), '.agents', 'skills'), join(process.cwd(), 'skills')]
+    const packageSkills = join(dirname(fileURLToPath(import.meta.url)), '..', 'skills');
+    return [explicit, ...roots, packageSkills, join(homedir(), '.codex', 'skills'), join(homedir(), '.agents', 'skills'), join(process.cwd(), 'skills')]
         .filter((value) => Boolean(value))
         .map(value => value.endsWith('browser-worker.agent.md') ? value : join(value, 'chatgpt-browser-worker', 'agents', 'browser-worker.agent.md'));
 }
-async function loadBrowserWorkerDefinition(explicit) {
+async function loadBrowserWorkerRuntime(explicit) {
     for (const candidate of browserWorkerCandidates(explicit)) {
         try {
             await access(candidate);
-            return readFile(candidate, 'utf8');
+            return { definition: await readFile(candidate, 'utf8'), root: dirname(dirname(candidate)) };
         }
         catch { /* try the next installed skill root */ }
     }
@@ -190,19 +194,71 @@ function parseBrowserWorkerResponse(output) {
         throw new Error('browser-worker response omitted operation or status');
     return response;
 }
-function agentPrompt(definition, request) {
-    return `${definition}\n\nReturn only the machine-readable JSON response required by the agent contract.\nREQUEST_JSON:\n${JSON.stringify(request)}`;
+function parseDriverJson(output) {
+    const lines = output.trim().split(/\r?\n/).filter(Boolean);
+    for (let index = lines.length - 1; index >= 0; index -= 1) {
+        try {
+            const value = JSON.parse(lines[index]);
+            if (value && typeof value === 'object' && !Array.isArray(value))
+                return value;
+        }
+        catch { /* browser-harness diagnostics may precede the final JSON observation */ }
+    }
+    throw new Error('browser-worker driver returned no JSON observation');
 }
-function defaultChatGptAgentRunner(harness) {
-    return (definition, request, route, signal) => {
-        const child = spawn(harness, buildCodexArgs(route, agentPrompt(definition, request)), { shell: false, cwd: route.cwd, stdio: ['ignore', 'pipe', 'pipe'] });
+function directBrowserWorkerRunner(root) {
+    return (_definition, request, _route, signal) => {
+        const scripts = join(root, 'scripts');
+        const project = request.project.name;
+        const args = request.operation === 'create'
+            ? [join(scripts, 'create_bh.py'), '--project', project, '--prompt', request.prompt ?? '', '--thinking-level', request.thinking_level ?? 'default']
+            : [join(scripts, 'operate_bh.py'), request.operation, '--thread-id', request.thread_id ?? '', '--project', project,
+                ...(request.operation === 'continue' ? ['--prompt', request.prompt ?? ''] : [])];
+        const child = spawn('python3', args, { shell: false, stdio: ['ignore', 'pipe', 'pipe'] });
         let stdout = '';
         let stderr = '';
         child.stdout?.on('data', (chunk) => { stdout += chunk.toString(); });
         child.stderr?.on('data', (chunk) => { stderr = appendTail(stderr, chunk.toString()); });
         const promise = new Promise((resolve, reject) => {
             child.on('error', reject);
-            child.on('close', code => code === 0 ? resolve(parseCodexAgentMessage(stdout) ?? stdout.trim()) : reject(new Error(stderr.trim() || `browser-worker harness exited ${code}`)));
+            child.on('close', code => {
+                if (code !== 0) {
+                    reject(new Error(stderr.trim() || stdout.trim() || `browser-worker driver exited ${code}`));
+                    return;
+                }
+                try {
+                    const observed = parseDriverJson(stdout);
+                    const threadId = typeof observed.thread_id === 'string' ? observed.thread_id : request.thread_id;
+                    const response = { operation: request.operation, status: 'running', thread_id: threadId ?? null };
+                    if (request.operation === 'create')
+                        response.status = 'running';
+                    else if (request.operation === 'continue')
+                        response.status = 'running';
+                    else if (request.operation === 'resume')
+                        response.status = typeof observed.status === 'string' ? observed.status : 'awaiting_result';
+                    else if (request.operation === 'status')
+                        response.status = typeof observed.status === 'string' ? observed.status : 'awaiting_result';
+                    else if (request.operation === 'result') {
+                        response.status = typeof observed.status === 'string' ? observed.status : 'completed';
+                        response.result = {
+                            message_id: typeof observed.message_id === 'string' ? observed.message_id : undefined,
+                            text: typeof observed.text === 'string' ? observed.text : undefined,
+                            verified: Boolean(observed.message_id && observed.text),
+                            observed_at: new Date().toISOString()
+                        };
+                    }
+                    else if (request.operation === 'delete') {
+                        const outcome = typeof observed.outcome === 'string' ? observed.outcome : '';
+                        response.status = outcome === 'deleted' || outcome === 'not_found' ? outcome : 'failed';
+                        if (response.status === 'failed')
+                            response.error = { code: 'cleanup_not_verified', message: 'browser-worker did not verify thread cleanup', retryable: true };
+                    }
+                    resolve(JSON.stringify(response));
+                }
+                catch (error) {
+                    reject(error);
+                }
+            });
             if (signal.aborted)
                 child.kill('SIGTERM');
             else
@@ -211,22 +267,6 @@ function defaultChatGptAgentRunner(harness) {
         return { promise, cancel: () => { child.kill('SIGTERM'); } };
     };
 }
-function parseCodexAgentMessage(output) {
-    let final;
-    for (const line of output.split(/\r?\n/)) {
-        try {
-            const value = JSON.parse(line);
-            const payload = value.payload;
-            const item = value.item;
-            if (value.type === 'event_msg' && payload?.type === 'task_complete' && typeof payload.last_agent_message === 'string')
-                final = payload.last_agent_message;
-            if (value.type === 'item.completed' && item?.type === 'agent_message' && typeof item.text === 'string')
-                final = item.text;
-        }
-        catch { /* harness diagnostics are not the agent response */ }
-    }
-    return final;
-}
 function browserWorkerError(response) {
     const detail = response.error?.message || `browser-worker ${response.status}`;
     return new Error(response.error?.code ? `${response.error.code}: ${detail}` : detail);
@@ -236,16 +276,15 @@ export class ChatGptAdapter {
     id = 'chatgpt/browser-worker';
     capabilities = ['model', 'chatgpt', 'browser-harness'];
     agentPath;
-    harness;
     runner;
     deleted = new Set();
     routes = new Map();
-    constructor(options = {}) { this.agentPath = options.agentPath ?? process.env.AGENTS_RELAY_CHATGPT_BROWSER_WORKER_AGENT; this.harness = options.harness ?? process.env.AGENTS_RELAY_AGENT_HARNESS ?? 'codex'; this.runner = options.agentRunner; }
+    constructor(options = {}) { this.agentPath = options.agentPath ?? process.env.AGENTS_RELAY_CHATGPT_BROWSER_WORKER_AGENT; this.runner = options.agentRunner; }
     async run(request, route, signal) {
-        const definition = await loadBrowserWorkerDefinition(this.agentPath);
+        const runtime = await loadBrowserWorkerRuntime(this.agentPath);
         if (signal.aborted)
             throw new Error('browser-worker execution aborted');
-        const run = (this.runner ?? defaultChatGptAgentRunner(this.harness))(definition, request, route, signal);
+        const run = (this.runner ?? directBrowserWorkerRunner(runtime.root))(runtime.definition, request, route, signal);
         const output = await new Promise((resolve, reject) => {
             const abort = () => { run.cancel(); reject(new Error('browser-worker execution aborted')); };
             if (signal.aborted) {
@@ -312,7 +351,17 @@ export class ChatGptAdapter {
                     operation, thread_id: expectedThreadId, project: this.project(task, route), prompt: hasPrompt ? task.input : undefined,
                     thinking_level: thinkingLevel(route.reasoning), state: null,
                 };
-                const response = await this.run(request, route, controller.signal);
+                let response;
+                try {
+                    response = await this.run(request, route, controller.signal);
+                }
+                catch (error) {
+                    if (controller.signal.aborted)
+                        throw error;
+                    if (operation === 'create')
+                        throw new LaunchFailure(error instanceof Error ? error.message : String(error));
+                    throw error;
+                }
                 const threadId = this.exposeThread(execution, expectedThreadId, response);
                 this.routes.set(threadId, route);
                 this.validateOperation(response, operation);

package/dist/reconciler.js

@@ -1,5 +1,6 @@
 import { randomUUID } from 'node:crypto';
 import { schedule, transitionTask } from './scheduler.js';
+import { LaunchFailure } from './adapters.js';
 import { eventFor } from './events.js';
 import { parsePlannerResult, plannerInput } from './planner.js';
 const PRIORITY_RANK = { P0: 0, P1: 1, P2: 2, P3: 3 };
@@ -206,7 +207,7 @@ export class Reconciler {
             execution = adapter.launch(workerTask, controller.signal);
         }
         catch (error) {
-            await this.finish(job.id, task.id, task.executionId, null, error instanceof Error ? error.message : String(error));
+            await this.finish(job.id, task.id, task.executionId, null, error instanceof Error ? error.message : String(error), { retryable: false });
             return;
         }
         // A worker may reject before durable execution metadata finishes saving. Attach a guard immediately so Node never treats that race as an unhandled rejection; the durable completion handler below still records the outcome.
@@ -222,7 +223,7 @@ export class Reconciler {
             persistThread(execution.threadId);
         const timer = setTimeout(() => { controller.abort(); execution.cancel(); }, task.timeoutMs);
         this.live.set(task.id, { taskId: task.id, execution, controller, timer });
-        this.detach(execution.promise.then(async (result) => { await threadPersistence; await this.finish(job.id, task.id, execution.id, result, null); }, async (error) => { await threadPersistence; await this.finish(job.id, task.id, execution.id, null, error instanceof Error ? error.message : String(error)); }), job.id, task.id, 'worker completion');
+        this.detach(execution.promise.then(async (result) => { await threadPersistence; await this.finish(job.id, task.id, execution.id, result, null); }, async (error) => { await threadPersistence; await this.finish(job.id, task.id, execution.id, null, error instanceof Error ? error.message : String(error), { retryable: !(error instanceof LaunchFailure) }); }), job.id, task.id, 'worker completion');
     }
     async launchPlanner(job, task) {
         const planner = this.options.planner;
@@ -319,7 +320,7 @@ export class Reconciler {
         await this.store.saveTask(task);
         await this.emit(eventFor(jobId, taskId, task.parentTaskId, 'thread.started', 'running', `Worker thread ${threadId} started`, 'orchestrator', { threadId }));
     } }
-    async finish(jobId, taskId, executionId, result, error) {
+    async finish(jobId, taskId, executionId, result, error, options = {}) {
         const live = this.live.get(taskId);
         if (live?.execution.id === executionId) {
             clearTimeout(live.timer);
@@ -344,10 +345,11 @@ export class Reconciler {
             await this.deliverContinuation(job, task);
         }
         else {
+            const retryable = options.retryable !== false && task.attempt < task.maxAttempts;
             task.error = error;
             task.leaseOwner = null;
             task.leaseExpiresAt = null;
-            transitionTask(task, task.attempt < task.maxAttempts ? 'READY' : 'FAILED');
+            transitionTask(task, retryable ? 'READY' : 'FAILED');
             await this.store.saveTask(task);
             await this.emit(eventFor(job.id, task.id, task.parentTaskId, task.state === 'FAILED' ? 'task.failed' : 'task.retry', task.state === 'FAILED' ? 'failed' : 'queued', `Task ${task.id}: ${error}`, task.state === 'FAILED' ? 'user' : 'orchestrator'));
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agents-relay",
-  "version": "1.0.4",
+  "version": "1.0.5",
   "description": "Durable async agent jobs coordinated through GitHub pull requests",
   "type": "module",
   "bin": {

package/skills/chatgpt-browser-worker/SKILL.md

@@ -0,0 +1,102 @@
+---
+name: chatgpt-browser-worker
+description: Manage ChatGPT work threads through the authenticated browser-harness session, including Project selection, thinking-level requests, durable thread identity, resume/status/result retrieval, and cleanup.
+---
+
+# ChatGPT browser worker
+
+This skill is the browser-backed ChatGPT worker contract for Neo. It uses the
+existing `browser-harness` command as its only browser interaction layer. It
+does not use the MacBridge ChatGPT runtime, ChatGPT APIs, copied cookies, or a
+second browser automation stack.
+
+## Capability contract
+
+The worker boundary exposes these lifecycle operations:
+
+```text
+create(project, prompt, thinking_level) -> ThreadState
+resume(thread_id, project)             -> ThreadState
+status(thread_id)                      -> StatusObservation
+result(thread_id)                      -> ThreadResult
+delete(thread_id)                      -> DeletedThreadState
+```
+
+`project.name` is required when creating or resuming a thread. `project.id` is
+optional because the UI may not expose it at every boundary. The adapter must
+select and verify that Project before sending the first prompt. A resumed
+thread keeps its recorded Project identity; callers cannot silently move it to
+another Project.
+
+Thinking levels are split into `requested_thinking_level` and
+`effective_thinking_level`. Requested values are `default`, `low`, `medium`,
+and `high`; effective values may additionally be `unknown`. `default` leaves
+the account's current/default setting unchanged. The adapter must preserve
+`unknown` rather than guessing from a label or silently downgrading a request.
+
+## Durable identity and state
+
+Persist the returned state after every successful lifecycle transition. The
+durable key is the ChatGPT `thread_id`; a URL, title, or browser tab index is
+not an identity. Records retain a deleted thread as a tombstone so a stale
+caller cannot recreate or accidentally reuse it. The complete JSON schema and
+valid transition table are in [references/contract.md](references/contract.md).
+
+Pure validation and transition helpers live in `scripts/contract.py`, with
+focused tests in `tests/test_contract.py`. The browser-harness driver is
+intentionally injected through the semantic port described in the reference;
+the contract layer does not import or launch `browser-harness`.
+Run `python3 -m pytest skills/chatgpt-browser-worker/tests` from the repository
+root.
+
+For the Neo/Leo and Agents Relay handoff—task IDs, run-local state, event
+ownership, and the create/resume/result/delete invocation sequence—see
+[references/orchestration.md](references/orchestration.md). The outer
+orchestrator may use MacBridge as a transport, but this worker never treats
+MacBridge as the ChatGPT runtime.
+
+The runtime entry point is the
+[browser-worker agent](agents/browser-worker.agent.md). Callers launch that
+agent with a typed lifecycle intent; they must not directly call
+`create_bh.py` or `operate_bh.py`. Those scripts are helper implementations
+that the agent may use, repair, or bypass while preserving this skill's
+browser-harness and verification contract.
+
+The browser-worker agent's `create` intent starts a new ChatGPT chat when the
+attached tab is already a conversation and emits JSON with the observed
+`thread_id`, conversation URL, selected Project, and thinking observation.
+`scripts/create_bh.py` is only a helper for that agent, not a caller-facing
+runtime contract.
+
+For implementation/debugging, the agent may use the helper equivalent for an
+existing thread with the durable identity from persisted state:
+
+```text
+python3 scripts/operate_bh.py resume --thread-id ID --project NAME
+python3 scripts/operate_bh.py continue --thread-id ID --project NAME --prompt TEXT
+python3 scripts/operate_bh.py status --thread-id ID --project NAME
+python3 scripts/operate_bh.py result --thread-id ID --project NAME
+python3 scripts/operate_bh.py delete --thread-id ID --project NAME
+```
+
+Each command performs one serial browser-harness operation. The injected
+semantic adapter in `scripts/operations.py` is the testable boundary; it does
+not import MacBridge or a ChatGPT runtime API.
+
+## Verification boundary
+
+The worker may report `completed` only from an observed assistant message and
+normalized result. A process exit, click, URL change, or tab title alone is not
+proof that a thread was created, resumed, completed, or deleted. Authentication
+walls, MFA, consent, ambiguous account/project selection, and unverified
+thinking levels are `blocked` or `failed` conditions and must not be
+self-healed.
+
+Delete targets the exact durable conversation URL, requires an observed action
+and confirmation, and verifies that the requested thread is no longer visible.
+Repeated cleanup is idempotent (`not_found` is accepted); archive/undo UI
+controls are evidence only and never revive a deleted tombstone.
+
+Keep credentials, prompts containing private data, and browser runtime state
+out of durable state and events. Runtime artifacts belong under the caller's
+ignored `runs/` directory.

package/skills/chatgpt-browser-worker/agents/browser-worker.agent.md

@@ -0,0 +1,113 @@
+---
+name: browser-worker
+description: Execute the ChatGPT browser-worker lifecycle through browser-harness while preserving verified thread and Project identity.
+type: worker
+---
+
+# Browser Worker Agent
+
+You are the runtime owner for the `chatgpt-browser-worker` skill. Before doing
+any work, load and follow both this skill and the `browser-harness` skill. The
+outer adapter launches you with one typed lifecycle request; Agents Relay
+owns task correlation, retries, events, and run-local persistence, but does
+not own browser execution.
+
+## Runtime rules
+
+- Use `browser-harness` for every browser interaction. Do not use another
+  browser stack, ChatGPT API, MacBridge ChatGPT runtime, copied cookies, or
+  direct HTTP calls to ChatGPT.
+- Preserve the exact observed ChatGPT `thread_id` and Project identity. A URL,
+  title, tab index, or inferred conversation is not an identity. A resumed
+  thread must remain in its recorded Project; reject a mismatch.
+- Treat the scripts in `scripts/` as helpers only. You may use, repair, or
+  bypass `create_bh.py` and `operate_bh.py` when they are brittle, but preserve
+  the skill contract and its evidence requirements.
+- When a selector, layout, label, or ordinary UI flow changes, re-observe the
+  current page through `browser-harness`, identify the semantic control, and
+  adapt the operation. Do not guess from stale selectors or coordinates.
+- Stop with `blocked` for authentication, MFA, consent, ambiguous account or
+  Project selection, or any human decision. Do not bypass these gates.
+- Stop with `blocked` or `failed` when the result cannot be verified. A process
+  exit, URL change, tab title, prior assistant bubble, or synthetic message ID
+  is not completion evidence.
+- Return only observations from the current browser state and persist the last
+  known `thread_id` when an operation fails after creation.
+
+## Typed adapter contract
+
+The input is one JSON object. `operation` must be one of `create`, `resume`,
+`continue`, `status`, `result`, or `delete`.
+
+```json
+{
+  "operation": "create",
+  "thread_id": null,
+  "project": {"name": "neo", "id": "project-optional"},
+  "prompt": "Run the assigned task.",
+  "thinking_level": "high",
+  "state": null
+}
+```
+
+Input requirements:
+
+- `create`: requires `project.name`, `prompt`, and `thinking_level`.
+- `resume`: requires `thread_id` and `project.name`; verify the recorded
+  Project before any other thread action.
+- `continue`: requires `thread_id`, `project.name`, and `prompt`; open and
+  verify the exact thread before sending the follow-up.
+- `status`, `result`, and `delete`: require the durable `thread_id`; use the
+  persisted `state` when supplied and never recreate a missing identity.
+- `thinking_level` is `default`, `low`, `medium`, or `high`; preserve an
+  observed effective value of `unknown` instead of guessing.
+
+The output is one JSON object suitable for an outer adapter:
+
+```json
+{
+  "operation": "result",
+  "status": "completed",
+  "thread_id": "chatgpt-conversation-id",
+  "project": {"name": "neo", "id": "project-id"},
+  "result": {
+    "message_id": "observed-assistant-message-id",
+    "text": "The normalized assistant answer.",
+    "verified": true,
+    "observed_at": "2026-09-19T12:02:00Z"
+  },
+  "state": {
+    "schema_version": 1,
+    "thread_id": "chatgpt-conversation-id",
+    "status": "completed",
+    "project": {"name": "neo", "id": "project-id"}
+  },
+  "error": null
+}
+```
+
+Every response must include `operation`, `status`, and the exact
+`thread_id` when one is known. A successful `result` response must include an
+observed assistant `message_id`, non-empty normalized `text`, and
+`result.verified: true`. `status` is not a result and must not claim
+completion. For `delete`, return a verified `deleted` or idempotent verified
+`not_found` observation and retain a terminal `deleted` tombstone.
+
+For blocked or failed operations, return the last known identity and a typed
+error without credentials or private prompts:
+
+```json
+{
+  "operation": "resume",
+  "status": "blocked",
+  "thread_id": "chatgpt-conversation-id",
+  "error": {
+    "code": "authentication_required",
+    "message": "Sign-in or MFA requires user action.",
+    "retryable": false
+  }
+}
+```
+
+Do not report success until the relevant browser observation has been
+validated against [../references/contract.md](../references/contract.md).

package/skills/chatgpt-browser-worker/references/contract.md

@@ -0,0 +1,132 @@
+# ChatGPT browser-worker contract
+
+This document is the stable boundary between Neo orchestration and a
+`browser-harness` adapter. It is intentionally independent of ChatGPT's DOM,
+URL layout, or internal network calls.
+
+## Requests
+
+All requests contain an operation and no credentials:
+
+```json
+{
+  "operation": "create",
+  "project": {"name": "neo", "id": "project-optional"},
+  "prompt": "Run the assigned task.",
+  "thinking_level": "high"
+}
+```
+
+`create` requires `project.name`, `prompt`, and `thinking_level`.
+`resume` requires `thread_id` and `project`; its thinking level is optional and
+defaults to the persisted request. `status`, `result`, and `delete` require
+only `thread_id`.
+
+Allowed requested thinking levels are `default`, `low`, `medium`, and `high`.
+The adapter may expose a current UI label in an observation, but it must map it
+to one of these values or `unknown` rather than guessing.
+
+## Durable thread state
+
+The state file is the only persisted worker identity. It may look like:
+
+```json
+{
+  "schema_version": 1,
+  "thread_id": "chatgpt-conversation-id",
+  "conversation_url": "https://chatgpt.com/c/chatgpt-conversation-id",
+  "project": {"id": "project-id", "name": "neo"},
+  "status": "awaiting_result",
+  "requested_thinking_level": "high",
+  "effective_thinking_level": "high",
+  "created_at": "2026-09-19T12:00:00Z",
+  "updated_at": "2026-09-19T12:01:00Z",
+  "last_error": null
+}
+```
+
+Required fields are `schema_version`, `thread_id`, `project.name`, `status`,
+`requested_thinking_level`, and `effective_thinking_level`. `project.id` and
+`conversation_url` are optional because the UI may not expose them at every
+boundary, but the adapter must preserve them when observed.
+
+The only valid statuses are:
+
+| Status | Meaning |
+| --- | --- |
+| `created` | identity exists; no prompt has been sent yet |
+| `running` | a prompt was sent and work is in progress |
+| `awaiting_result` | the UI indicates a response may be read |
+| `completed` | an assistant result was observed and normalized |
+| `failed` | the operation failed; recovery may resume this identity |
+| `blocked` | human/authentication/ambiguity decision is required |
+| `deleted` | cleanup was verified; identity must not be reused |
+
+Valid transitions are:
+
+```text
+create -> created -> running -> awaiting_result -> completed
+                                      |              |
+                                      +-> failed     +-> running (follow-up)
+any live state -> blocked
+any live state -> deleted  (only after verified cleanup)
+failed/blocked -> running  (only after an explicit recovery operation)
+```
+
+`deleted` is terminal. A new conversation gets a new `thread_id`.
+
+## Results
+
+```json
+{
+  "thread_id": "chatgpt-conversation-id",
+  "status": "completed",
+  "text": "The assistant's normalized final answer.",
+  "message_id": "observed-message-id",
+  "observed_at": "2026-09-19T12:02:00Z"
+}
+```
+
+`text` is required only for `completed`. Partial or streaming text is not a
+completed result. A result with no observed assistant message is an error, not
+success.
+
+## Browser adapter port
+
+The adapter is tested through a fake port with these semantic calls:
+
+```text
+select_project(project) -> observed_project
+open_thread(thread_id) -> observed_thread
+set_thinking_level(level) -> observation
+send_prompt(prompt) -> observation
+read_status() -> status_observation
+read_result() -> result_observation
+delete_thread() -> cleanup_observation
+```
+
+`cleanup_observation` must contain the requested `thread_id` (or omit it only
+when the browser has verified the thread is absent), `outcome` equal to
+`deleted` or `not_found`, and `verified: true`. `not_found` is a successful
+idempotent retry. Archive/undo controls may be reported as observational
+metadata, but they do not turn a delete into a recoverable state: a deleted
+tombstone remains terminal and must never be reused.
+
+These names describe the boundary, not a required Python class or browser
+selector implementation. Each call must return observed values or a typed
+failure. The contract layer must remain usable with a fake port and must not
+import or launch `browser-harness` itself.
+
+## Testable safety boundaries
+
+- no request can omit the Project on `create` or `resume`;
+- Project IDs are compared when both browser boundaries expose them; a
+  name-only observation remains valid because the UI may hide opaque IDs;
+- no state can omit a non-empty `thread_id` or valid status;
+- `resume` rejects an observed Project mismatch;
+- requested and effective thinking levels are distinct fields;
+- unknown effective level stays `unknown`;
+- only an observed assistant message yields `completed`;
+- delete is terminal and cannot be followed by resume;
+- browser, login, and ambiguity failures preserve the thread identity and are
+  classified as `failed` or `blocked`.