@protolabsai/sdk surface changes for workstacean fleet integration

[mabry1985]

Goal

Track SDK-side changes needed as protoCLI joins the workstacean fleet via ProtoSdkExecutor. Driven by workstacean#516; changes here unblock that integration.

This is a tracking issue — the concrete API tweaks will be discovered as the workstacean side lands. Keeping it open as the parking lot for SDK churn until the integration is stable.

What we have today

• @protolabsai/sdk@0.2.0 published from packages/sdk-typescript/.
• Public surface: query(), Query class, AbortError, MCP server helpers, typed messages (SDKMessage variants, ToolUseBlock, etc.), RunConfig, SubagentConfig.
• Already streaming-capable, already typed, already supports cancellation via AbortError.

Likely gap areas

Each of these is a hypothesis until workstacean#516 surfaces the actual need. Don't pre-implement.

1. Progress event shape

Workstacean's ProtoSdkExecutor.onProgress callback wants distinct events for tool calls (started, output, completed) so the dashboard can render "running shell command..." / "reading file...". Verify the SDK emits these as parsable SDKMessage variants, or expose a higher-level progress stream that maps cleanly to workstacean's bus event shape.

2. Token usage rollup

ui.modelPricing lives in proto's settings now (#219). When the SDK is invoked from workstacean, the dispatcher needs final token counts (and ideally per-turn deltas) to compute cost in the workstacean dashboard. Confirm SDKResultMessage.usage is populated for gateway-routed runs and includes prompt/completion/cached tokens consistently.

3. Cancellation cleanliness

AbortError exists and the underlying CLI has bg_stop/task_stop. Verify a mid-run cancel actually drains:

• Active in-flight model request.
• Background shells the run spawned.
• File handles / partial writes.

If anything leaks, the workstacean cancel path will leak it across the bus.

4. Working directory

query() should accept (and respect) a cwd so workstacean can dispatch into a protoMaker-owned worktree without process.chdir() side effects. Verify the option exists or add it.

5. Per-call model override

Workstacean's AgentExecutorConfig allows per-skill model override. Confirm RunConfig.model is honored by the SDK and routes through our gateway with the right auth.

6. Session shape for resume

SDKResultMessage likely surfaces session_id. Workstacean does not currently chain runs, but if it ever does (multi-turn skill), the SDK should support resume: <sessionId> in query() options. Defer until workstacean asks.

7. Error surface

When proto exits abnormally, the SDK's error needs to be rich enough that workstacean can route it to skill.result.{correlationId} with actionable detail (timeout vs. tool-error vs. auth-failure). Today this likely surfaces as a single error string — may need typed error variants.

Process

• Each concrete change → its own PR.
• Cross-reference workstacean#516's progress; close this when that issue closes (or carry over remaining items).
• SDK is on a separate semver from the CLI — bump minor for additive surface, major only if we have to break.

Out of scope

• Background-agent control surface (task_stop, send_message, event_monitor) — separate track, see docs/explanation/background-agents-design.md.
• Headless CLI changes — keep scope to the SDK. CLI binary is consumed by humans, SDK is consumed by workstacean.

[mabry1985]

First concrete deliverable from this issue: PR #231 — typed error variants (CliNotFoundError, CliInitError, TransportError, InputClosedError) + type guards. Pre-empts §7.