Task-level SDK facade over @codeoid/core — script a session without driving the event loop

[saucam]

Problem

@codeoid/core and @codeoid/protocol are already on npm (both 0.2.0, MIT). But they are transport-level and first-party-shaped: CodeoidClient (WS handshake, reconnect, heartbeat), MessageStore (upsert-by-messageId, delta merge, replay routing), ResumeCursors. They exist so the web UI and the mobile client can share plumbing — the README describes them as "everything a frontend needs except the pixels."

That is the right library for building a renderer. It is the wrong library for someone who wants to script codeoid: run a prompt in a session, wait for the turn, read the result, check what it cost.

So the packages are published but effectively undiscoverable as a public API — nothing in the README or docs positions them as an SDK, and the ergonomics assume you're implementing a UI.

Proposed scope

A thin task-oriented facade over the existing packages — resource-shaped, the way Superset's @superset_sh/sdk uses resources/*:

const codeoid = new Codeoid({ url, token });
const session = await codeoid.sessions.create({ name, workdir, provider: "claude" });
const turn = await session.send("run the tests and fix what fails");  // resolves on turn_done
console.log(turn.usage.totalCostUsd, turn.text);

• sessions — create / list / get / send / interrupt / destroy
• session.send() that awaits turn_done instead of making the caller drive an event loop, with an onEvent escape hatch for streaming
• Typed turn results off the existing NormalizedTurnResult (usage, cost, model, stopReason)
• Approval handling as a callback, not a message-pump the caller reassembles
• Transcript paging that reuses ResumeCursors rather than reimplementing cursor logic

Where this lands is an open question: a new packages/sdk on top of @codeoid/core, or an added export surface (@codeoid/core/sdk). Prefer the latter if it doesn't drag UI concerns into the dependency.

Plus the non-code half, which is most of the current gap:

• A documented public API surface (what's stable vs internal — right now everything looks internal)
• Runnable examples
• A docs page, and a README line saying codeoid has an SDK

Sequencing

Do this after the control-plane MCP server. The MCP server is the better distribution lever (agents pull codeoid in; the SDK only helps people who already chose codeoid), and both will want the same authorization decisions — scope mapping, audit attribution — so settling those once in the MCP work makes this one mostly DX.

Non-goals

• Not a new wire protocol. This is ergonomics over @codeoid/protocol; if the facade needs a new message type, that's a protocol change reviewed on its own merits.
• No Python/Go clients yet.
• Not a reason to destabilize @codeoid/core's existing consumers (web UI, mobile) — additive only.

[saucam]

Sequenced after #251 (control-plane MCP server), which settles the scope-mapping and audit-attribution questions this shares.