Introduce packages/codev-sdk: client SDK for Tower (server/client dependency isolation)

[amrmelsayed]

Goal

Introduce packages/codev-sdk (@cluesmith/codev-sdk): the single client implementation of "how anything talks to Tower". Restructure the shared-package taxonomy so server and client dependencies are isolated at the package level:

• codev-types: wire contracts. The only package imported by both sides. Unchanged.
• codev-core: server-side implementation only (local-key auth issuance, homedir-derived path constants, and over time Tower internals).
• codev-sdk (new): Tower API client, WS/message-bus client, and the client-side pure helpers. Consumed by the web dashboard, the VS Code extension, the CLI's Tower-facing commands, and the future mobile app.

Invariant: codev-core and codev-sdk never import each other; both import codev-types.

Motivation

codev-core is currently consumed from both server (Tower, CLI) and client (dashboard browser bundle, VS Code extension host) contexts. The boundary between its Node-only modules and its environment-agnostic ones is enforced only by convention (subpath exports plus reviewer vigilance). Two concrete problems observed:

1. constants.ts imports node:path/node:os, so a pure value like DEFAULT_TOWER_PORT is unreachable from any bundler that cannot resolve Node builtins (Metro for the planned mobile app fails loudly on it).
2. Nothing structural prevents a server-side need from adding a runtime dependency that every client then inherits.

Package-level separation makes the package manager enforce the boundary instead of review discipline. The mobile workstream (issue #1147, research in codev/research/mobile/) makes a third client environment (React Native / Metro) concrete, but the split stands on its own for the two existing clients.

Import census (verified 2026-07-16)

Who imports each codev-core leaf today:

Leaf	codev (CLI/server)	dashboard	vscode	Disposition
tower-client	CLI commands	-	yes	sdk (auth/transport injected)
auth	(via tower-client)	-	yes	issuance stays core; sdk takes injected getToken
workspace	yes	-	yes	sdk (URL grammar is contract-adjacent)
constants	yes	-	yes	split: pure values to sdk, homedir paths stay core
escape-buffer	-	yes	yes	sdk
reconnect-policy	Tower (tunnel-client, tower-websocket)	yes	yes	sdk owns it; core keeps a private copy (see exception)
agent-names	yes	-	yes	sdk
architect-name	yes	-	yes	sdk
builder-helpers	-	yes	yes	sdk
area-grouping	-	-	yes	sdk
phase-grouping	-	-	yes	sdk
review-markers	-	-	yes	sdk

Note on packages/codev: the server/client line runs through this package, not around it. It hosts Tower (server) and also the afx/porch/consult CLI commands, which are Tower API clients. The CLI's Tower-facing slice consumes the sdk like every other client; the rest of the CLI (worktree surgery, porch state machine, scaffolding) stays where it is.

The one exception: reconnect-policy

Genuinely dual-use: Tower itself uses it in tunnel-client.ts (Tower acting as a WS client of the cloud) and tower-websocket.ts. Resolution: the sdk owns the module; codev-core keeps a private copy of the backoff math (~40 lines of pure code) for the tunnel. Accepted duplication, recorded here deliberately; the alternatives (core importing the client sdk, or algorithm code in codev-types) each break a rule worth more than 40 lines.

SDK constraints (the guardrails)

Its consumers span browser (dashboard), React Native / Metro (mobile), and Node (VS Code extension host, CLI). Therefore:

• Zero runtime dependencies. dependencies: {} is a reviewable contract.
• Environment-agnostic: no DOM, no node:*, no fetch assumptions. Transport, storage, and auth arrive as injected adapters (the VS Code extension injects a local-key reader; the browser injects its stored key; mobile injects secure-store).
• CI-enforced boundary: an import-boundary test in the style of packages/artifact-canvas/src/__tests__/import-boundary.test.ts, failing the suite if any shipped module imports Node builtins, vscode, or uses fetch directly.
• Framework-free: no React in v1. The extension host and CLI cannot use hooks. An optional /react subpath entry (React as optional peer) can be added later if web and mobile demonstrably duplicate hook logic; that addition requires its own proposal.

Explicitly deferred: apps/cli

Considered and rejected for now: moving the CLI to apps/cli on top of the sdk. The CLI is not a Tower client; it is local runtime sharing a machine and filesystem with Tower (launches the daemon, performs git worktree operations, runs porch over local state, scaffolds from the bundled skeleton). It would still need codev-core and most of packages/codev, and npm install -g @cluesmith/codev deliberately ships CLI and Tower as one artifact. Revisit only if Tower ships as a standalone daemon/service with its own release cadence, or a genuinely thin remote-only CLI is wanted. (Same defer-until-trigger pattern as #1029.)

Sequencing and operational touchpoints

• Land after Monorepo layout: introduce apps/ for end-user surfaces #855 merges: Monorepo layout: introduce apps/ for end-user surfaces #855 relocates packages/dashboard to apps/web, and this refactor touches the same import lines; doing them serially avoids double churn.
• scripts/local-install.sh packs codev-core and codev into one global install; codev-sdk must join the pack set or global installs break on the unresolvable workspace dep.
• Publish with pnpm publish (workspace:* resolution).
• Release protocol version-bump set grows by one package.
• Mobile is not blocked on this: spike work talks raw fetch/WS to Tower; the PoC implementation builds on the sdk.

Origin

Mobile workstream architecture discussion (2026-07-16), evolving the retired packages/tower-sdk concept from codev/research/mobile/interaction-model.md section 7.2 into a dependency-isolation split with existing consumers. A docs amendment to the mobile research (replacing the tower-sdk section with this design) follows separately.

[amrmelsayed]

Consumer-census update: the integrations packages (Stream Deck) join this refactor — absorption + monorepo move (decided with Amr, 2026-08-05)

Assessment of codev-integrations (@cluesmith/codev-client 0.1.0 + @cluesmith/codev-streamdeck) against this refactor concluded the client is a near-perfect early embodiment of this issue's design rules — injectable auth (read-only local-key as a de-facto injected getToken), codev-types as its only shared import, fetch/transport seams throughout. Decisions:

1. codev-sdk absorbs @cluesmith/codev-client (deprecate, don't facade)

The client's npm package is 0.1.0 with one consumer — the cheapest moment to consolidate is when the SDK lands. A facade would be a second name for the same implementation (a diluted duplicate-canonical-home). Absorption specifics, adding rows to this issue's census:

From codev-client	Disposition
SSE subscribe w/ backoff + pure parseSseText parser	lift into sdk (best current implementation of Tower SSE consumption; becomes/joins the sdk's event-stream client)
sendCommand + COMMAND_ROUTE (the /api/command verb relay)	lift into sdk; resolves the existing mild duplication (CommandRequest defined client-side AND mirrored in codev-types)
Read-only local-key reader (~/.agent-farm/local-key → codev-web-key header)	lift into sdk as the default getToken profile for local outside-in controllers (issuance stays core, per this issue's auth disposition)
Outside-in posture (allowlisted verbs, no Tower state)	preserved as a curated subpath export (e.g. @cluesmith/codev-sdk/controller) rather than a separate package

2. The Stream Deck plugin moves into the monorepo as apps/streamdeck

Rationale (supersedes the earlier keep-repos-separate lean): (a) post-#1189, isolation is package-manager-enforced — a package declaring only codev-sdk + @elgato/streamdeck can't reach internals regardless of repo; (b) apps/vscode already proves the monorepo ships non-npm marketplace artifacts (toolchain + packaging + separate channel); (c) with codev-client dissolved, the migration delta is exactly one package, fitting #855's apps/ = end-user-surfaces taxonomy. The plugin becomes the SDK's first and simplest consumer — a plain Node 20 process whose needs (overview + workspaces + SSE + command verbs) are a strict subset of the mobile app's, i.e. a cheap validation target before mobile bets on the SDK.

3. What's lost + mitigation

In-repo, the plugin consumes workspace:* HEAD and stops dogfooding the published npm contract (a signal already dying — the mobile app will also be an in-repo workspace:* consumer). Mitigation: a small scheduled CI job building apps/streamdeck against the latest published @cluesmith/codev-sdk, keeping one external-fidelity canary alive for third-party integrators.

4. Sequencing

All of this rides THIS issue's delivery: SDK lands → client absorbed + npm package deprecated with a pointer → plugin moves in-repo and migrates as first consumer → codev-integrations retires (or remains an archive/community-examples shell). No pre-emptive moves; the current codev-client stays correct until then.

[amrmelsayed]

Ownership clarification (Amr, 2026-08-05)

This issue's execution belongs to the main architect's lane — it is a cross-cutting core refactor (area/core, package-taxonomy surgery across codev-core/codev-types/new codev-sdk) serving every client, not a mobile-workstream deliverable. The mobile architect authored the design because mobile's spike research motivated it (PR #1190's Metro/node-builtins finding); that authorship had informally hardened into implied ownership, corrected here.

Going forward:

• Execution/scheduling: main architect. Spawned from the main queue when prioritized.
• Mobile architect: consumer-stakeholder. Reviews the SDK contract at the plan gate against React Native / Metro constraints (the environment that motivated the split).
• Streamdeck architect (launching soon): consumer-stakeholder. Reviews the controller subpath-export surface; then OWNS the follow-on migration — apps/streamdeck monorepo move, first-consumer migration to the published SDK, @cluesmith/codev-client deprecation, and codev-integrations repo retirement (per the plan in the previous comment).
• Mobile architect owns mobile-app consumption when that workstream resumes.

Consumer-stakeholder review at the plan gate replaces neither CMAP nor the human gates — it is additive domain review by the two architects whose clients this SDK must serve.

[amrmelsayed]

On it! Working on this with the PIR protocol (plan + dev-approval gates before PR).