feat(sdk): publish the Public Thread client as a minimal Agent App integration kit

[Yevanchen]

Area

Developer experience / Public Thread API / MCP delegation

Problem

The GoGym dogfood project had to reimplement more than 100 lines of Mosoo-specific integration code before it could embed an Agent safely:

• Public Thread and Run request/response types
• Bearer authentication and API error handling
• SSE parsing and run completion tracking
• retry/idempotency behavior
• delegation JWT verification inside the MCP server

This is protocol and trust-boundary glue, not GoGym business logic. Every Agent App would otherwise copy it, and small mistakes create data leaks or duplicate side effects.

Mosoo already contains most of the right low-level implementation in pkgs/public-api-client, verified on main@dd06043:

• create/retrieve Thread
• send Message / create Run
• upload Agent file
• list and stream run events
• wait for terminal output
• typed API errors and idempotency headers

However, the package is currently private: true, and its event stream is a one-shot connection. External apps therefore cannot reuse it and still need to implement reconnect, history reconciliation, deduplication, and delegation verification themselves.

Proposal

Publish and minimally extend the existing @mosoo/public-api-client. Do not create a second SDK or a new application framework.

1. Publish the existing client

• make the existing package installable and versioned
• support Node.js and Cloudflare Workers
• keep the current low-level Thread, Run, File, and event methods

2. Add a resumable watchRun()

A high-level helper should:

• tail the live event stream
• reconnect with bounded backoff
• reconcile persisted event history after reconnect
• deduplicate by stable event ID
• check the terminal Thread/Run snapshot
• support AbortSignal and timeout
• surface history truncation or terminal failure explicitly
• never silently replace a missing Thread

The app callback should observe each persisted event at most once within one watcher invocation.

3. Add delegation verification

Provide a runtime-neutral verifyDelegation() helper, implemented with WebCrypto, that validates:

• signature and allowed algorithm
• issuer and audience
• iat, exp, and maximum token lifetime
• required Mosoo execution claims

Return a typed execution context such as:

{
  userId,
  appId,
  agentId,
  threadId,
  runId,
  toolCallId,
}

This helper verifies Mosoo's signed delegation. It does not implement application login, business authorization, RLS, or replay protection.

4. Make retry-safe idempotency the default

High-level mutation helpers and examples must accept a caller-stable requestId / operation ID and map it to Idempotency-Key.

Documentation must not generate a new random key inside a retry attempt.

Acceptance criteria

• An external TypeScript app can install the published package.
• One example backend creates a Thread with trusted userId, watches a Run through a forced disconnect, and never exposes the Mosoo token to the browser.
• The watcher has tests for reconnect, history merge, duplicate events, terminal state reached during disconnect, timeout, and abort.
• The delegation helper has tests for valid claims, bad signature, wrong issuer/audience, expiry, future iat, excessive lifetime, and missing claims.
• Existing low-level client methods remain usable; no parallel client implementation is introduced.
• GoGym can delete its handwritten Mosoo client/SSE parser and JWT verifier after adopting the package.

Non-goals

• Supabase Auth, RLS, storage, or application-user lifecycle
• generating MCP servers, Tool schemas, or business Tools
• browser WebSocket/UI event mapping
• Agent manifests or publish/deploy workflows
• Cloudflare/OpenShip deployment abstraction
• exactly-once external side effects or provider-specific reconciliation

Related issues

• feat(public-api): expose stable toolCallId for business-side idempotency #488 should provide a stable public toolCallId for business-side idempotency.
• fix(runtime): persist uncertainty for external tool effects #412 owns uncertain external Tool effects.
• feat(runtime): reconcile external tool effects for idempotency-capable MCP providers #446 owns provider-specific reconciliation.

This issue is the thin, reusable adoption layer above those runtime contracts—not a replacement for them.

[Yevanchen]

PitchPilot dogfood feedback

The PitchPilot migration independently validates this issue and gives us a concrete deletion target.

At commit ada87d2, the integration added:

• a 597-line handwritten Public Thread client;
• a 662-line deck-scoped proxy route, part of which must remain as the App authorization/BFF boundary;
• custom browser history and EventSource reconciliation in useDeckTimeline.ts.

Failures and workarounds observed

1. Forwarding a multipart File parsed by a Cloudflare Worker into a second outbound multipart request threw Illegal invocation. PitchPilot rebuilt the complete file in the current Worker realm.
2. An injected/bound fetch lost the Cloudflare invocation context, so the client had to fall back to runtime-global fetch.
3. App-owned attachments currently make a double hop: PitchPilot R2 → Worker arrayBuffer() → Mosoo upload. The canonical upload-session/raw-byte flow documented in docs(api): clarify Thread file upload and attach flow #172 should be exposed by the published client so a Worker can stream bytes instead of buffering the complete object.
4. The Web App loads and streams only the latest 400 events and currently ignores truncated. One deployed browser Run produced 2,391 activity records, so reload cannot reconstruct the complete history.
5. A stale application field, clientRequestId, reached the public endpoint and failed with Unsupported thread event field: clientRequestId; PitchPilot now maps it manually to requestId.

Suggested acceptance additions

• Run the installable client in a real Cloudflare Worker fixture, including Thread creation, event streaming, and file upload.
• Expose the upload-session/raw-content flow so Worker/R2 content can be streamed without a full arrayBuffer() copy or multipart-to-multipart File reconstruction.
• Force a disconnect after more than one event-history page and prove watchRun() reconciles all persisted events, surfaces truncation, and emits no duplicate IDs.
• Generate or share the wire request types so requestId / userId contract drift fails before deployment.
• After adoption, PitchPilot can delete its handwritten client and event watcher while retaining only deck authorization and business projection.

Structured Run artifact identity is separated into #505. PitchPilot-specific Preview, Deck revision, and export behavior should remain outside this SDK.

[Yevanchen]

ghfind dogfood feedback

ghfind independently confirms the deletion target in this issue—and adds a Go consumer.

At commit b7eee13, its production project-analysis worker carries a 564-line handwritten Go Public Thread client. The file explicitly says it mirrors a separate 427-line TypeScript implementation, which remains the source of truth for wire shapes, error codes, and activity classification.

Mosoo-specific code ghfind currently owns

• request/response structs and enum validation for Thread, Run, event, file, and error payloads (Go types);
• Bearer auth, timeout handling, API error-envelope parsing, Retry-After, and HTTP-to-product error mapping (transport);
• Thread creation plus caller-stable Idempotency-Key handling (create);
• Run watching by polling the Thread and only the latest 100 events (snapshot), while the worker separately owns retry scheduling and reconciliation;
• artifact discovery by exact filename, followed by three individual downloads (artifact read).

Workarounds / contract pressure

1. History truncation is parsed but ignored. The client models truncated, but GetProjectAnalysisSnapshot() always requests limit=100 and returns activities without surfacing truncation or paging older events. A resumable watcher should own pagination/reconciliation/deduplication, not each app.
2. The app recreates the Run state machine. Its worker persists Mosoo IDs, polls snapshots, applies retry/backoff, and resumes after process/queue redelivery. ghfind should keep its business job durability, but Mosoo client code should expose a tested wait/watch primitive with terminal/error semantics.
3. Artifacts are inferred by filename. ghfind scans the full Thread file list for three names derived from its analysis ID. The naming convention is ghfind business logic, but stable Run → artifact IDs belong to feat(public-api): expose structured Run artifact references for Agent Apps #505 and would remove the list/reconcile ambiguity.
4. Contract drift already produced a compatibility shim. The Go client notes that the live API expects userId and rejects the historical client_external_ref shape (comment). Generated/shared wire types would make this fail before deployment.
5. Agent package updates are not available through this integration path. ghfind carries a large REPORT_CONTRACT in every task because the registered Skill snapshot cannot be updated through the public API (rationale). This is lifecycle/versioning pressure, not necessarily SDK scope; ghfind's rubric and report contract should remain app-owned.

Scope recommendation

For this issue, keep the promised TypeScript package minimal, but treat ghfind as evidence that the reusable contract is language-neutral:

• OpenAPI-derived request/response/error types;
• stable idempotency helpers;
• a resumable, truncation-aware Run watcher;
• explicit terminal/error semantics;
• artifact helpers after feat(public-api): expose structured Run artifact references for Agent Apps #505 exposes Run-linked IDs.

A Go SDK can be a follow-up if demand justifies it. The important near-term constraint is that the published protocol and conformance fixtures make ghfind's handwritten Go client boring to generate or delete. ghfind's RabbitMQ topology, concurrency slots, persistent job state, score schema, artifact size policy, and activity labels should stay in ghfind.