docs: design C — the family's own app tools over the shared server (approved draft, reviewed) #6

Merged

claude merged 5 commits from oss-oo/family-tools-design into main 2026-10-28 00:54:27 +00:00

Conversation 0 Commits 5 Files changed 1 +130

claude agent commented 2026-10-27 23:41:12 +00:00

Member

• Copy link
• Copy Markdown

Design C — the family's own app tools over the shared server

docs/FAMILY-TOOLS-DESIGN.md: the design paper for the family-own MCP tool server that offers the thread tools of the bundled Codex app plugin (send_message_to_thread, read_thread, create_thread, fork_thread, handoff_thread, wait_threads) over the shared app-server's own door — so they work with AND without the running ChatGPT app (the parity rule). Z said yes to building after the measurement points (steer 40, 2026-10-28 01:01) on the first version; the reworked decisions (registration, transport, write path, receipt kinds, not-servable list) are marked [Z], the approval mode [owner], until he has read them.

What the paper fixes: registration options (codex_app with the bundled plugin off, or family_tools beside the bridge — Z decides after measurement 3), one short-lived connection per call and no heal from inside the shared server, writes through oo-appserver send --json --wait 0 --min-interval 0 --no-heal --from <caller> with the sender tag prepended by the tool server, receipt kinds per tool, the approval mode as an owner decision, the bundle's zod schemas as the contract (read_thread, send_message_to_thread, create_thread, fork_thread, wait_threads — read from the installed bundle) and what the shared server cannot serve (cloud target, remote hostId, worktree, projectId, model/thinking on a send), six measurements before the build, the stages (building block 1 oo-appserver read = v0.4.0, PR #7, merged).

Measured facts of 2026-10-28 that the paper rests on (evidence folder read-measure-20261028-0105/, v030-proof/): thread/read, thread/turns/list, thread/items/list do not load a thread (no writer lock for reads; thread/read on the 719 MB thread 4 ms); the bundled tools' catalogue AND calls travel over the per-launch pipe (bridge) and need the running app; the first real calls in the shared server succeeded on the owner's app (read_thread from Luna's chat, Ping-Pong Luna 1 ↔ Luna 2 via send_message_to_thread in both directions, wait_threads incl. the literal rejection of a 150000 ms timeout); ephemeral threads answer neither resume nor turns/list.

Review

Fresh read-only subagent, three readings: on e698ed6 15 points (stale branch; five vs six tools; naming contradiction; app-only tools scoped wrong; FYI/throttle rule unclear; static approval mode; decide+deliver is not what send runs; a persistent connection would block every heal; resume is not read-only; the bundle's schemas differ; overclaims; nits) — folded in 38ab35e; on 38ab35e 3 should-fix (the bundle's real zod schemas; "used by the helper today" before PR #7 landed; attribution and --wait 0 on the send path) + 5 nits — folded in 857a300; on 857a300 2 should-fix (--tag is skipped on a bracketed line → the tool server prepends the tag itself; mark every new decision [Z]) + nits — folded in the final commit, branch rebased onto main after PR #7 (v0.4.0). Review texts: v030-review/review-design-paper-pr6-*.md in the evidence folder.

🤖 Generated with Claude Code

## Design C — the family's own app tools over the shared server `docs/FAMILY-TOOLS-DESIGN.md`: the design paper for the family-own MCP tool server that offers the thread tools of the bundled Codex app plugin (`send_message_to_thread`, `read_thread`, `create_thread`, `fork_thread`, `handoff_thread`, `wait_threads`) over the shared app-server's own door — so they work with AND without the running ChatGPT app (the parity rule). **Z said yes to building after the measurement points (steer 40, 2026-10-28 01:01) on the first version**; the reworked decisions (registration, transport, write path, receipt kinds, not-servable list) are marked **[Z]**, the approval mode **[owner]**, until he has read them. What the paper fixes: registration options (`codex_app` with the bundled plugin off, or `family_tools` beside the bridge — Z decides after measurement 3), one short-lived connection per call and no heal from inside the shared server, writes through `oo-appserver send --json --wait 0 --min-interval 0 --no-heal --from <caller>` with the sender tag prepended by the tool server, receipt kinds per tool, the approval mode as an owner decision, **the bundle's zod schemas as the contract** (read_thread, send_message_to_thread, create_thread, fork_thread, wait_threads — read from the installed bundle) and what the shared server cannot serve (cloud target, remote hostId, worktree, projectId, model/thinking on a send), six measurements before the build, the stages (building block 1 `oo-appserver read` = v0.4.0, PR #7, merged). Measured facts of 2026-10-28 that the paper rests on (evidence folder `read-measure-20261028-0105/`, `v030-proof/`): `thread/read`, `thread/turns/list`, `thread/items/list` do not load a thread (no writer lock for reads; `thread/read` on the 719 MB thread 4 ms); the bundled tools' catalogue AND calls travel over the per-launch pipe (bridge) and need the running app; the first real calls in the shared server succeeded on the owner's app (`read_thread` from Luna's chat, Ping-Pong Luna 1 ↔ Luna 2 via `send_message_to_thread` in both directions, `wait_threads` incl. the literal rejection of a 150000 ms timeout); ephemeral threads answer neither resume nor turns/list. ### Review Fresh read-only subagent, three readings: on `e698ed6` 15 points (stale branch; five vs six tools; naming contradiction; app-only tools scoped wrong; FYI/throttle rule unclear; static approval mode; `decide`+`deliver` is not what `send` runs; a persistent connection would block every heal; resume is not read-only; the bundle's schemas differ; overclaims; nits) — folded in `38ab35e`; on `38ab35e` 3 should-fix (the bundle's real zod schemas; "used by the helper today" before PR #7 landed; attribution and `--wait 0` on the send path) + 5 nits — folded in `857a300`; on `857a300` 2 should-fix (`--tag` is skipped on a bracketed line → the tool server prepends the tag itself; mark every new decision [Z]) + nits — folded in the final commit, branch rebased onto main after PR #7 (v0.4.0). Review texts: `v030-review/review-design-paper-pr6-*.md` in the evidence folder. 🤖 Generated with [Claude Code](https://claude.com/claude-code)

claude agent added 1 commit 2026-10-27 23:41:12 +00:00

docs: design C — the family's own app tools over the shared server (draft for Z) ... 50ad676d57

The paper for Z's target after the bridge: one small MCP server of our own serving the bundled
thread tools' names (send_message_to_thread, read_thread, create_thread, fork_thread,
handoff_thread, wait_threads) over the shared server's WebSocket door — with and without the
running app — reusing the sender's station decision and receipt classes; tool-by-tool mapping to
the v2 protocol, the naming question (register as `codex_app` vs. beside the bridged plugin), the
approval-mode question for headless calls, the measurements to run on a rig first, and the stages.
Stage: idea.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

claude agent referenced this pull request 2026-10-27 23:54:11 +00:00

v0.3.0: the app tools bridge — the bundled Codex app tools work in the shared server #5

claude agent added 1 commit 2026-10-28 00:02:26 +00:00

docs: design C carries Z's word — approved for building after the measurement points, read first (steer 40) ... e698ed6ad8

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

claude agent referenced this pull request 2026-10-28 00:13:26 +00:00

v0.4.0: oo-appserver read — the last turns of a thread, read without loading it; the release gate learns ephemeral threads #7

claude agent force-pushed oss-oo/family-tools-design from e698ed6ad8 to 38ab35e570 2026-10-28 00:26:50 +00:00 Compare

claude agent changed title from docs: design C — the family's own app tools over the shared server (draft for Z) to docs: design C — the family's own app tools over the shared server (approved draft, reviewed) 2026-10-28 00:27:30 +00:00

claude agent added 1 commit 2026-10-28 00:41:41 +00:00

docs: design C after the second read — the bundle's zod schemas as the contract (read_thread, send, create, fork), attribution and --wait 0 on the send path, what the shared server cannot serve, Z's yes scoped to the first version, measurements 3 and 6 widened, evidence paths named ... 857a300d80

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

claude agent added 1 commit 2026-10-28 00:45:31 +00:00

docs: design C — the tool server prepends the sender tag itself (send skips --tag on a bracketed line), every new decision marked [Z], the literal rejection text, the recipient turn's approvals ... c978cfeaf1

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

claude agent force-pushed oss-oo/family-tools-design from c978cfeaf1 to de8a749b3f 2026-10-28 00:47:39 +00:00 Compare

claude agent merged commit e7f2e5e901 into main 2026-10-28 00:54:27 +00:00

claude agent deleted branch oss-oo/family-tools-design 2026-10-28 00:54:27 +00:00

claude agent referenced this pull request from a commit 2026-10-28 00:54:29 +00:00

docs: design C — the family's own app tools over the shared server (approved draft, reviewed) (#6)

Sign in to join this conversation.

Reviewers

No reviewers

Labels

Clear labels

No items

No labels

Milestone

Clear milestone

No items

No milestone

Projects

Clear projects

No items

No project

Assignees

Clear assignees

No assignees

1 participant

Notifications

Subscribe

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference

OSS-OO/oo-appserver!6

No description provided.