@love-moon/app-sdk 0.3.2

package/CHANGELOG.md

@@ -0,0 +1,135 @@
+# @love-moon/app-sdk
+
+## 0.3.2
+
+### Changed
+
+- `ChatEvent.task_failed.error` and `StreamReplyDelta.error` now include
+  optional `details?: unknown` and `cause?: unknown` fields. Additive,
+  non-breaking — existing consumers ignore the new fields. The default WS
+  → ChatEvent translation forwards both from `ConductorAppError`, so host
+  UIs can surface server payloads / request IDs / underlying causes without
+  depending on the SDK error class directly. The `<ChatView />` React store
+  (`useChat().state.error`) also carries these through.
+- `examples/02_bff` BFF now hardcodes `role: 'user'` and strips
+  `metadata.audit` on `POST /messages`. **Integrators copying the example
+  must follow this pattern.** Without it, a malicious browser could forge
+  `role: 'system'|'assistant'` messages or stamp `audit.actor='app'` —
+  bypassing `streamReply`'s SDK-echo filter and impersonating server-side
+  app messages. The BFF is the only point in the pipeline that knows the
+  browser is untrusted; do not push role/audit choices down to the SDK.
+- `client.tasks.streamReply()` now applies a default **120s idle timeout**
+  between consecutive `text` / status-transition deltas. If no progress is
+  observed in that window the iterator yields a terminal
+  `{ type: 'error', error: { code: 'stream_aborted', message: 'idle timeout' } }`
+  and closes. Long-running backends (e.g. tools that may legitimately go
+  silent for minutes) can opt out by passing `idleTimeoutMs: 0`:
+
+  ```ts
+  for await (const delta of client.tasks.streamReply(taskId, { idleTimeoutMs: 0 })) {
+    // never time out — caller is responsible for cancelling via signal
+  }
+  ```
+- **Locked down the public `.d.ts` surface.** Internal transport types —
+  `Fetcher`, `FetcherOptions`, `RequestOptions`, `AppWebSocket`,
+  `AppWebSocketOptions`, `TasksRestApi` — are now tagged
+  `/** @internal */` and stripped from generated d.ts via tsup's
+  `dts.compilerOptions.stripInternal`. Previously these appeared as
+  `declare class …` in `dist/server/index.d.ts` (even though not
+  re-exported) and TypeScript surfaced them on hover / structural
+  reference. The `AppClient._internals` test-seam getter has been removed
+  (it was unused). The CI `bundle-smoke` script now also asserts none of
+  these symbols leak into any d.ts as a regression net.
+- **`AppClient.close()` now safely terminates in-flight subscribe
+  iterators.** When a `for await` loop on `tasks.subscribe(taskId)` is
+  mid-stream and the caller invokes `client.close()`, the iterator now
+  yields a synthetic
+  `{ type: 'task_failed', taskId, error: { code: 'subscribe_failed', message: 'client closed' } }`
+  and returns instead of hanging silently. Same for `tasks.streamReply()`
+  — it surfaces an `{ type: 'error', error: { code: 'subscribe_failed' } }`
+  delta. `close()` is also idempotent (a second call is a no-op). After
+  close, calls to `tasks.subscribe()` / `tasks.streamReply()` / any
+  `tasks.*` REST method throw a synchronous
+  `ConductorAppError({ code: 'subscribe_failed', message: 'client is closed' })`
+  rather than returning a hanging iterator. Implemented internally by a
+  new `AppWebSocket.onClose(listener)` channel; the public API surface
+  is unchanged.
+
+## 0.1.0
+
+Initial implementation, RFC 0027 milestones M0–M3.
+
+### Added — package layout (M0)
+
+- Single npm package with three subpath entries:
+  - `@love-moon/app-sdk` (root, types-only + `SDK_VERSION`)
+  - `@love-moon/app-sdk/server` (Node)
+  - `@love-moon/app-sdk/react` (browser / React)
+  - `@love-moon/app-sdk/react/styles.css`
+- tsup multi-entry build; per-entry tsconfig conditions.
+- `react` + `react-dom` as optional peer dependencies — server-only consumers
+  don't get warnings.
+- CI bundle smoke test (`npm run test:bundle`) statically asserts no Node
+  symbols leak into `/react` and no DOM symbols leak into `/server`.
+- vitest with per-file `@vitest-environment` directives (node + jsdom).
+
+### Added — `/server` (M1)
+
+- `connect()` + `AppClient` with `projects` and `tasks` sub-APIs.
+- `projects.bind()` — idempotent find-or-create on (daemonHost, workspacePath);
+  stamps `metadata.audit.createdByApp` on creation (zero schema change).
+- `projects.list()` / `projects.get()`.
+- `tasks.create()` / `tasks.get()` / `tasks.list()`.
+- `tasks.sendMessage()` with auto-generated `clientRequestId` (idempotent).
+- `tasks.history()` with cursor-based pagination.
+- `tasks.interrupt()` with `targetReplyTo`.
+- `tasks.subscribe(taskId)` — `AsyncIterable<ChatEvent>` over `/ws/app` with
+  taskId-side filtering, capped backoff reconnect, and a per-iterator abort.
+- `tasks.streamReply(taskId)` — `AsyncIterable<StreamReplyDelta>` built on
+  subscribe; yields `text` deltas from `reply_preview` plus a terminal `done`
+  on the assistant message (or `error` on `task_status_update=failed`).
+- Unified `ConductorAppError` with named error codes mapped from HTTP status
+  + backend error strings.
+- Custom fetch / WebSocket / bearerToken providers for SSR + test injection.
+
+### Added — `/react` (M2)
+
+- `<ChatView />` — composed widget: runtime status bar + message list + input.
+- `<MessageList />`, `<MessageInput />`, `<RuntimeStatusBar />` —
+  building-block components for compose-your-own layouts.
+- `<ChatProvider />` + `useChat()` — React Context + useReducer chat state
+  (no zustand dep; per-instance store so multiple widgets on the same page
+  don't collide).
+- `createRestAdapter()` — default `ChatAdapter` implementation that talks to
+  a host BFF exposing 4 routes (`messages` GET/POST, `interrupt`, `events`
+  SSE).
+- Optimistic send → server confirm flow with pending-message replacement.
+- Pre-compiled CSS at `@love-moon/app-sdk/react/styles.css`; CSS-variable
+  theming via the `theme` prop; mobile/desktop layout via responsive CSS
+  + an explicit `layout` prop override.
+- jsdom integration tests covering hydration, live events, runtime status,
+  interrupt button visibility, and optimistic send.
+
+### Added — examples + docs (M3)
+
+- `examples/01_example/` — minimal Node CLI demo: bind project → create task
+  → stream AI reply to stdout. ~35 lines of business code, no UI / BFF.
+- `examples/02_bff/` — runnable Next.js demo: BFF wraps `/server`,
+  page mounts `<ChatView />`, ~120 lines of business code total.
+  - `lib/conductor.ts` — singleton AppClient.
+  - `app/api/conductor/bind/route.ts` — `projects.bind()` + `tasks.create()`.
+  - `app/api/conductor/[...path]/route.ts` — catch-all BFF translating to
+    the 4 widget-expected routes, including a 30-line SSE bridge over
+    `tasks.subscribe()`.
+- README with quickstart, full integration recipe, and security model.
+
+### Known gaps
+
+- v0.1 chat UI is functional but visually minimal. RFC §4 phase B (physical
+  extraction of `web/src/features/chat` polished components, including
+  Markdown / attachments / 1423-line regression test) is a follow-up PR.
+- Streaming surface yields `text` cumulative previews, not token-level
+  deltas. Real token streaming requires a backend envelope addition; the
+  `StreamReplyDelta` shape is forward-compatible.
+- Attachments not implemented in the default REST adapter or `<ChatView>`;
+  `Attachment` types are defined for forward compat.

package/README.md

@@ -0,0 +1,173 @@
+# @love-moon/app-sdk
+
+Embed Conductor AI tools into third-party apps. One npm package, three
+subpath entries:
+
+| Entry | Environment | Purpose |
+| --- | --- | --- |
+| `@love-moon/app-sdk` | any | Pure types + `SDK_VERSION`. Safe everywhere. |
+| `@love-moon/app-sdk/server` | Node 18+ | SDK for third-party **backends** to talk to Conductor REST + `/ws/app`. |
+| `@love-moon/app-sdk/react` | browser / React 18+ | Chat widget (`<ChatView />`) wired by a `ChatAdapter`. |
+
+See [RFC 0027](../../claw/rfc/0027-feature-conductor-app-sdk.md) for the design.
+
+## Examples
+
+Two runnable examples ship with the package, under [`examples/`](./examples/):
+
+| Example | Lines | What it shows |
+| --- | --- | --- |
+| [`examples/01_example/`](./examples/01_example/) | ~35 LOC | **Smallest possible app.** Pure Node CLI: bind project → create task → stream the AI reply to stdout. Use this to learn the SDK in 60 seconds. |
+| [`examples/02_bff/`](./examples/02_bff/) | ~120 LOC | Full-stack: Next.js BFF + React `<ChatView />` widget + SSE bridge over `/ws/app`. Use this as a template for real browser integrations. |
+
+## Quick start
+
+A complete integration is ~120 lines of business code spread across a Next.js
+BFF and a React page. See [`examples/02_bff/`](./examples/02_bff/) for the
+full runnable demo, or [`examples/01_example/`](./examples/01_example/) for
+a pure-Node CLI.
+
+### Backend (the only place your Conductor token lives)
+
+```ts
+// lib/conductor.ts
+import { connect } from '@love-moon/app-sdk/server';
+
+export const client = await connect({
+  baseUrl: 'https://conductor.example.com',
+  bearerToken: process.env.CONDUCTOR_TOKEN!,
+});
+
+export async function bindProject() {
+  return client.projects.bind({
+    name: 'Acme Dashboard',
+    daemonHost: process.env.CONDUCTOR_DAEMON_HOST!,
+    workspacePath: process.env.CONDUCTOR_WORKSPACE_PATH!,
+  });
+  // Idempotent: matches by (daemonHost, workspacePath); creates only on miss.
+}
+
+// Create a task once you've got the project id. `initialMessage` is the
+// kickoff prompt — the AI reply to that message starts streaming as soon
+// as you subscribe below.
+const task = await client.tasks.create({
+  projectId: project.id,
+  title: 'Investigate billing anomaly',
+  initialMessage: 'Look at the last 24h of charges.',
+});
+
+// Subscribe to receive the AI's reply (and any subsequent events on the
+// task). Use `sendMessage` to add follow-up turns from your code; the demo
+// here shows a single-turn flow, so we just consume events until the task
+// finishes. To send a follow-up turn before exiting, call
+// `client.tasks.sendMessage(task.id, 'drill into the top one')` and keep
+// the loop running.
+for await (const evt of client.tasks.subscribe(task.id)) {
+  if (evt.type === 'message_appended') console.log(evt.message.content);
+  if (evt.type === 'task_finished') break;
+}
+
+// streamReply: stream the AI's reply as it builds up. Defaults to a 120s
+// idle timeout between deltas; pass `idleTimeoutMs: 0` to disable for
+// long-running backends that may legitimately go silent for minutes.
+for await (const delta of client.tasks.streamReply(task.id, { idleTimeoutMs: 0 })) {
+  if (delta.type === 'text') process.stdout.write(delta.text);
+  if (delta.type === 'done') break;
+  if (delta.type === 'error') throw new Error(delta.error.message);
+}
+```
+
+### Frontend (chat widget)
+
+```tsx
+import { ChatView, createRestAdapter } from '@love-moon/app-sdk/react';
+import '@love-moon/app-sdk/react/styles.css';
+
+const adapter = createRestAdapter({
+  baseUrl: '/api/conductor',          // your BFF, not Conductor directly
+});
+
+export default function ChatPage({ taskId }: { taskId: string }) {
+  return <ChatView taskId={taskId} adapter={adapter} />;
+}
+```
+
+### Backend-for-Frontend (the 4 routes the widget speaks)
+
+The widget's default `createRestAdapter` expects:
+
+| Route | Forward to |
+| --- | --- |
+| `GET  /tasks/:id/messages?pagination=1&limit=N&before_id=...` | `client.tasks.history()` |
+| `POST /tasks/:id/messages` | `client.tasks.sendMessage()` |
+| `POST /tasks/:id/interrupt` | `client.tasks.interrupt()` |
+| `GET  /tasks/:id/events` (text/event-stream) | `client.tasks.subscribe()` via SSE bridge |
+
+The SSE bridge over Conductor's `/ws/app` is the only non-trivial piece —
+~30 lines of code. See the
+[example catch-all route](./examples/02_bff/app/api/conductor/[...path]/route.ts)
+for the full pattern.
+
+## Why a single package, three entries
+
+The widget and the BFF must agree on wire format and event shapes; coupling
+them in a single package + shared types makes that contract impossible to
+accidentally split. Subpath exports + `peerDependenciesMeta.optional = true`
+ensure server-only consumers don't pay for React, and browsers never see Node
+code. See [Option F in the RFC](../../claw/rfc/0027-feature-conductor-app-sdk.md#proposed-design).
+
+## Security model
+
+The token used by `@love-moon/app-sdk/server` is equivalent to the user's
+Conductor account. **Never** put it in a browser bundle or expose it to
+untrusted code. The intended deployment is:
+
+```
+[browser widget] ──▶ [your BFF, holds token] ──▶ [Conductor backend] ──▶ [daemon]
+```
+
+The widget never receives the Conductor token — it talks only to your BFF.
+
+## Status
+
+| Milestone | Status |
+| --- | --- |
+| M0 — package skeleton + exports + bundle smoke | ✓ |
+| M1 — `/server` REST + WS subscribe + streamReply + tests | ✓ |
+| M2 — `/react` widget + default REST adapter + integration tests | ✓ |
+| M3 — `examples/01_example` CLI + `examples/02_bff` Next.js demo + this README | ✓ |
+
+The v0.1 widget is intentionally minimal in visuals — the eventual physical
+extraction of the polished UI from `web/src/features/chat` (RFC §4) is a
+future PR. The widget's component API + adapter contract are stable now.
+
+## Development
+
+```bash
+cd modules/app-sdk
+npm install           # via root npm workspaces
+npm run build         # tsup + Tailwind copy
+npm test              # vitest: unit + integration tests across node + jsdom
+npm run typecheck
+npm run test:bundle   # static guard: no Node code in /react, no DOM in /server
+```
+
+### Project layout
+
+```
+src/
+  types/            Pure types — Task / Message / RuntimeStatus / ChatEvent / ChatAdapter / errors
+  index.ts          Root entry (re-exports types)
+  server/           Node-only: connect() / AppClient / projects.bind / tasks.* / ws subscribe / streamReply
+  react/            Browser-only: <ChatView />, components, default REST adapter, styles
+test/
+  server/           node-env tests (fetcher, projects, tasks, subscribe, streamReply)
+  react/            jsdom-env tests (<ChatView /> integration)
+```
+
+### Versioning policy
+
+- 1.x freezes `<ChatView>` props, `AppClient` methods, `ChatAdapter` interface,
+  and root type exports.
+- Adding a new `ChatEvent` variant or a new SDK method is a minor bump.
+- Removing or renaming any of the above is a major bump.

package/dist/index.d.ts

@@ -0,0 +1,299 @@
+/**
+ * Task: a single AI conversation within a project.
+ *
+ * Mirrors the shape returned by Conductor's `/api/tasks/[taskId]` REST endpoint
+ * (camelCase normalized). All fields are present after a successful read; the
+ * `null`-able fields reflect cases where the backend hasn't populated them yet
+ * (e.g. a task created via SDK before its daemon picks it up).
+ */
+interface Task {
+    id: string;
+    projectId: string;
+    title: string;
+    status: TaskStatus;
+    /** Backend execution engine ("claude_code" / "codex" / etc.) or null when not selected yet. */
+    backendType: string | null;
+    /** AI session id assigned by the daemon; null until the daemon attaches. */
+    sessionId: string | null;
+    sessionFilePath: string | null;
+    /** ISO 8601 timestamps. Always present after the task is persisted. */
+    createdAt: string;
+    updatedAt: string;
+}
+type TaskStatus = 'pending' | 'running' | 'finished' | 'failed' | 'cancelled' | string;
+interface CreateTaskInput {
+    projectId: string;
+    title: string;
+    /**
+     * Optional first user message. When provided, the backend persists it as
+     * the task's initial message right after creation.
+     * Maps to the backend's `initialContent` field; the SDK renames it for
+     * symmetry with `sendMessage(taskId, content)`.
+     */
+    initialMessage?: string;
+    /** Backend type override (claude_code / codex / kimi-cli / etc.). */
+    backendType?: string;
+    /** Free-form metadata; merged with SDK audit fields server-side. */
+    metadata?: Record<string, unknown>;
+}
+
+/**
+ * Project: a workspace binding (daemon + filesystem path) inside which tasks
+ * are scoped. Maps to Conductor's Project model.
+ *
+ * `daemonHost` and `workspacePath` are the binding identity. App-SDK's
+ * `projects.bind()` is idempotent on this pair.
+ */
+interface Project {
+    id: string;
+    name: string;
+    daemonHost: string | null;
+    workspacePath: string | null;
+    repoRoot: string | null;
+    worktreeBranch: string | null;
+    lastCommit: string | null;
+    lastCommitAt: string | null;
+    fileCount: number | null;
+    isDefault: boolean;
+    /**
+     * True when this project was created via the App SDK (audit hint, derived
+     * from `metadata.audit.createdByApp`). Read-only flag for UI affordances.
+     */
+    createdByApp: boolean;
+    createdAt: string;
+    updatedAt: string;
+}
+interface BindProjectInput {
+    name: string;
+    daemonHost: string;
+    workspacePath: string;
+    /**
+     * Optional override for the audit `createdByApp.name` field. Defaults to the
+     * `name` argument. Only used when the SDK has to create a new project (no
+     * existing binding found).
+     */
+    appLabel?: string;
+}
+
+/**
+ * Message: one entry in a task's chat transcript.
+ *
+ * Roles:
+ *  - 'user'      — message sent by the user (or the SDK on their behalf).
+ *  - 'sdk'       — message sent by an SDK / CLI / app integration (still
+ *                  appears in the chat as a user-side bubble).
+ *  - 'assistant' — AI reply.
+ *  - 'system'    — system-emitted notice (rare; renders muted).
+ *
+ * `role` is intentionally open-vocabulary; new backend roles render as
+ * a generic bubble.
+ */
+interface Message {
+    id: string;
+    taskId: string;
+    role: MessageRole | string;
+    content: string;
+    metadata: Record<string, unknown> | null;
+    attachments: Attachment[];
+    createdAt: string;
+}
+type MessageRole = 'user' | 'sdk' | 'assistant' | 'system';
+interface Attachment {
+    id: string;
+    filename: string;
+    mimeType: string;
+    sizeBytes: number;
+    /** Resolvable URL or relative path the host must turn into a fetchable URL. */
+    url: string;
+}
+interface SendMessageInput {
+    content: string;
+    /** Idempotency key. When omitted, the SDK auto-generates a UUID. */
+    clientRequestId?: string;
+    metadata?: Record<string, unknown>;
+    /** Optional attachments to include with this message; must be pre-uploaded. */
+    attachmentIds?: string[];
+    /** Role override; defaults to 'sdk'. */
+    role?: MessageRole;
+}
+
+/**
+ * Runtime status pushed by the daemon while a task is in progress.
+ * Mirrors `task_runtime_status` envelope on /ws/app.
+ */
+interface RuntimeStatus {
+    taskId: string;
+    /** High-level phase: 'idle' | 'thinking' | 'tool_call' | 'awaiting_user' | 'done'. */
+    state: RuntimeState;
+    phase?: string | null;
+    source?: string | null;
+    /** Short status line shown next to the AI avatar ("Reading file X..."). */
+    statusLine?: string | null;
+    /** Final status line shown when the reply finishes. */
+    statusDoneLine?: string | null;
+    replyPreview?: string | null;
+    replyTo?: string | null;
+    replyInProgress?: boolean;
+    backend?: string | null;
+    threadId?: string | null;
+    daemon?: string | null;
+    pid?: number | null;
+    sessionId?: string | null;
+    sessionFilePath?: string | null;
+    tokenUsagePercent?: number | null;
+    contextUsagePercent?: number | null;
+    createdAt?: string | null;
+}
+type RuntimeState = 'idle' | 'thinking' | 'tool_call' | 'awaiting_user' | 'done' | string;
+
+/**
+ * ChatEvent: the minimal set of events the chat widget needs to render.
+ *
+ * This is intentionally a small union — the widget should not have to
+ * pattern-match dozens of envelope types. The default REST/WS adapter
+ * funnels raw `/ws/app` envelopes into ChatEvents; custom adapters can do the
+ * same translation against any wire format.
+ */
+/**
+ * Error shape carried inside `task_failed` ChatEvents and `error`
+ * StreamReplyDeltas.
+ *
+ * `details` and `cause` are optional, free-form passthroughs of the original
+ * SDK error's structured fields — useful for surfacing request IDs / server
+ * payloads in host UIs without depending on the SDK error class directly.
+ */
+interface ChatEventError {
+    code: string;
+    message: string;
+    details?: unknown;
+    cause?: unknown;
+}
+type ChatEvent = {
+    type: 'message_appended';
+    message: Message;
+} | {
+    type: 'message_updated';
+    message: Message;
+} | {
+    type: 'runtime_status';
+    status: RuntimeStatus;
+} | {
+    type: 'task_finished';
+    taskId: string;
+} | {
+    type: 'task_failed';
+    taskId: string;
+    error: ChatEventError;
+} | {
+    type: 'connection_state';
+    state: 'connected' | 'reconnecting' | 'offline';
+};
+/**
+ * StreamReplyDelta: a streaming AI reply chunk yielded by
+ * `client.tasks.streamReply(id)`.
+ *
+ * v1 semantics: each `text` delta is a *cumulative* preview-style chunk
+ * (built from `task_runtime_status.reply_preview` rolling state). The final
+ * `done` delta carries the full reply Message. A future RFC may add real
+ * token-level streaming; the shape is forward-compatible.
+ */
+type StreamReplyDelta = {
+    type: 'text';
+    text: string;
+    replyTo: string;
+} | {
+    type: 'status';
+    status: RuntimeStatus;
+} | {
+    type: 'done';
+    message: Message;
+} | {
+    type: 'error';
+    error: ChatEventError;
+};
+
+/**
+ * ChatAdapter: the contract between the React widget and *something* that
+ * can talk to a Conductor-shaped backend. The widget calls these methods;
+ * implementations decide how to translate to HTTP / WS / GraphQL / in-process
+ * calls.
+ *
+ * The default implementation `createRestAdapter` (in `/react`) talks to a
+ * BFF that mirrors Conductor's REST shape. Hosts using a custom wire format
+ * just implement this interface directly.
+ */
+interface ChatAdapter {
+    fetchHistory(taskId: string, opts?: {
+        beforeId?: string;
+        limit?: number;
+        signal?: AbortSignal;
+    }): Promise<{
+        messages: Message[];
+        hasMoreBefore: boolean;
+        oldestMessageId: string | null;
+    }>;
+    subscribe(taskId: string, handler: (event: ChatEvent) => void): {
+        unsubscribe(): void;
+    };
+    sendMessage(taskId: string, input: SendMessageInput): Promise<Message>;
+    interrupt(taskId: string, opts: {
+        targetReplyTo: string;
+    }): Promise<void>;
+    /** Optional. Adapters that don't support attachments may omit. */
+    uploadAttachment?(taskId: string, file: File | Blob, opts?: {
+        signal?: AbortSignal;
+        filename?: string;
+    }): Promise<{
+        id: string;
+        url: string;
+    }>;
+}
+
+/**
+ * ConductorAppError: every error thrown out of the SDK is one of these.
+ * Callers can `if (err instanceof ConductorAppError) switch (err.code)`.
+ *
+ * `code` is open-vocabulary for forward compat; the SDK promises to never
+ * remove existing codes, only add new ones, and to bump the minor version
+ * when a new code is introduced.
+ */
+declare class ConductorAppError extends Error {
+    readonly name = "ConductorAppError";
+    readonly code: ConductorErrorCode | string;
+    readonly status?: number;
+    readonly details?: unknown;
+    readonly requestId?: string;
+    constructor(args: {
+        code: ConductorErrorCode | string;
+        message: string;
+        status?: number;
+        details?: unknown;
+        requestId?: string;
+        cause?: unknown;
+    });
+}
+type ConductorErrorCode = 'unauthorized' | 'forbidden' | 'token_revoked' | 'invalid_input' | 'project_not_found' | 'task_not_found' | 'message_not_found' | 'daemon_offline' | 'workspace_path_conflict' | 'binding_validation_failed' | 'task_not_running' | 'task_type_not_messageable' | 'task_type_not_interruptible' | 'task_fire_owner_offline' | 'network_error' | 'timeout' | 'rate_limited' | 'server_error' | 'subscribe_failed' | 'stream_aborted';
+/** Helper: type-guard for callers that don't want `instanceof`. */
+declare function isConductorAppError(error: unknown): error is ConductorAppError;
+
+/**
+ * @conductor/app-sdk root entry.
+ *
+ * This entry is environment-agnostic: it re-exports pure types plus a few
+ * runtime constants. Safe to import from Node, browsers, Edge runtimes, and
+ * React Server Components.
+ *
+ * Use the subpath entries for runtime code:
+ *   - `@love-moon/app-sdk/server` — Node SDK for talking to Conductor.
+ *   - `@love-moon/app-sdk/react`  — React chat widget.
+ */
+
+declare const SDK_VERSION = "0.3.2";
+declare const SDK_NAME = "@love-moon/app-sdk";
+/**
+ * User-Agent fragment the SDK sets on every outbound HTTP request.
+ * Format: `conductor-app-sdk/<version>`.
+ */
+declare const SDK_USER_AGENT = "conductor-app-sdk/0.3.2";
+
+export { type Attachment, type BindProjectInput, type ChatAdapter, type ChatEvent, ConductorAppError, type ConductorErrorCode, type CreateTaskInput, type Message, type MessageRole, type Project, type RuntimeState, type RuntimeStatus, SDK_NAME, SDK_USER_AGENT, SDK_VERSION, type SendMessageInput, type StreamReplyDelta, type Task, type TaskStatus, isConductorAppError };

package/dist/index.js

@@ -0,0 +1,30 @@
+// src/types/errors.ts
+var ConductorAppError = class extends Error {
+  name = "ConductorAppError";
+  code;
+  status;
+  details;
+  requestId;
+  constructor(args) {
+    super(args.message, args.cause ? { cause: args.cause } : void 0);
+    this.code = args.code;
+    this.status = args.status;
+    this.details = args.details;
+    this.requestId = args.requestId;
+  }
+};
+function isConductorAppError(error) {
+  return typeof error === "object" && error !== null && error.name === "ConductorAppError";
+}
+
+// src/index.ts
+var SDK_VERSION = "0.3.2";
+var SDK_NAME = "@love-moon/app-sdk";
+var SDK_USER_AGENT = `conductor-app-sdk/${SDK_VERSION}`;
+export {
+  ConductorAppError,
+  SDK_NAME,
+  SDK_USER_AGENT,
+  SDK_VERSION,
+  isConductorAppError
+};