@love-moon/app-sdk 0.3.2

package/dist/react/styles.css

@@ -0,0 +1,264 @@
+/* Conductor App SDK — chat widget styles.
+ *
+ * v0.1: hand-written CSS, functional but visually minimal. The eventual
+ * extraction from web/src/features/chat will swap this for the pre-compiled
+ * Tailwind output. Until then, hosts who want polished visuals are free to
+ * override any class — every component renders semantic conductor-* classes.
+ *
+ * Theming: all colors / radii / spacing pull from CSS variables on the
+ * `.conductor-chat-view` root, which `<ChatView theme={...} />` overrides
+ * per instance.
+ */
+
+.conductor-chat-view {
+  --accent: #e4572e;
+  --conductor-paper: #f5f1ea;
+  --conductor-text: #1a1a1a;
+  --conductor-text-muted: rgba(0, 0, 0, 0.55);
+  --conductor-bubble-user: #f1ece2;
+  --conductor-bubble-assistant: #ffffff;
+  --conductor-border: rgba(0, 0, 0, 0.08);
+  --conductor-radius: 12px;
+  --conductor-spacing: 12px;
+  --conductor-font:
+    -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto,
+    "Helvetica Neue", Arial, sans-serif;
+
+  display: grid;
+  grid-template-rows: auto 1fr auto;
+  height: 100%;
+  background: var(--conductor-paper);
+  color: var(--conductor-text);
+  font-family: var(--conductor-font);
+  font-size: 14px;
+  line-height: 1.5;
+  box-sizing: border-box;
+}
+
+.conductor-chat-view *,
+.conductor-chat-view *::before,
+.conductor-chat-view *::after {
+  box-sizing: border-box;
+}
+
+/* ----- Runtime status bar ------------------------------------------------- */
+
+.conductor-runtime-status {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  padding: 8px var(--conductor-spacing);
+  font-size: 12px;
+  color: var(--conductor-text-muted);
+  border-bottom: 1px solid var(--conductor-border);
+  min-height: 32px;
+}
+
+.conductor-runtime-indicator {
+  width: 8px;
+  height: 8px;
+  border-radius: 50%;
+  background: rgba(0, 0, 0, 0.2);
+  flex-shrink: 0;
+}
+
+.conductor-runtime-indicator--active {
+  background: var(--accent);
+  animation: conductor-pulse 1.2s ease-in-out infinite;
+}
+
+@keyframes conductor-pulse {
+  0%,
+  100% {
+    transform: scale(1);
+    opacity: 1;
+  }
+  50% {
+    transform: scale(1.4);
+    opacity: 0.6;
+  }
+}
+
+.conductor-runtime-text {
+  flex: 1;
+  white-space: nowrap;
+  overflow: hidden;
+  text-overflow: ellipsis;
+}
+
+.conductor-runtime-error {
+  color: #b04020;
+  font-weight: 500;
+}
+
+.conductor-runtime-connection {
+  margin-left: auto;
+  font-size: 11px;
+  color: var(--conductor-text-muted);
+}
+
+/* ----- Message list ------------------------------------------------------- */
+
+.conductor-message-list {
+  overflow-y: auto;
+  padding: var(--conductor-spacing);
+  display: flex;
+  flex-direction: column;
+  gap: 8px;
+  min-height: 0; /* lets it shrink inside the grid row */
+}
+
+.conductor-load-earlier {
+  display: flex;
+  justify-content: center;
+  margin-bottom: 4px;
+}
+
+.conductor-load-earlier button {
+  background: transparent;
+  border: 1px solid var(--conductor-border);
+  border-radius: 999px;
+  padding: 4px 12px;
+  font-size: 12px;
+  color: var(--conductor-text-muted);
+  cursor: pointer;
+}
+
+.conductor-load-earlier button:disabled {
+  opacity: 0.5;
+  cursor: progress;
+}
+
+.conductor-message {
+  display: flex;
+}
+
+.conductor-message--user {
+  justify-content: flex-end;
+}
+
+.conductor-message--assistant {
+  justify-content: flex-start;
+}
+
+.conductor-bubble {
+  max-width: 75%;
+  padding: 10px 14px;
+  border-radius: var(--conductor-radius);
+  white-space: pre-wrap;
+  word-break: break-word;
+  border: 1px solid var(--conductor-border);
+}
+
+.conductor-message--user .conductor-bubble {
+  background: var(--conductor-bubble-user);
+  border-bottom-right-radius: 4px;
+}
+
+.conductor-message--assistant .conductor-bubble {
+  background: var(--conductor-bubble-assistant);
+  border-bottom-left-radius: 4px;
+}
+
+.conductor-message--pending .conductor-bubble {
+  opacity: 0.6;
+}
+
+/* ----- Message input ------------------------------------------------------ */
+
+.conductor-message-input {
+  display: flex;
+  align-items: flex-end;
+  gap: 8px;
+  padding: var(--conductor-spacing);
+  border-top: 1px solid var(--conductor-border);
+  background: var(--conductor-paper);
+}
+
+.conductor-message-input__textarea {
+  flex: 1;
+  min-height: 36px;
+  max-height: 136px;
+  resize: none;
+  padding: 8px 12px;
+  border: 1px solid var(--conductor-border);
+  border-radius: var(--conductor-radius);
+  background: #fff;
+  color: var(--conductor-text);
+  font-family: inherit;
+  font-size: 14px;
+  line-height: 1.5;
+  outline: none;
+  overflow-y: auto;
+}
+
+.conductor-message-input__textarea:focus {
+  border-color: var(--accent);
+  box-shadow: 0 0 0 3px rgba(228, 87, 46, 0.15);
+}
+
+.conductor-message-input__actions {
+  display: flex;
+  align-items: center;
+  gap: 6px;
+}
+
+.conductor-button {
+  padding: 8px 14px;
+  border-radius: var(--conductor-radius);
+  border: 1px solid var(--conductor-border);
+  background: #fff;
+  color: var(--conductor-text);
+  font: inherit;
+  cursor: pointer;
+  transition: background-color 120ms ease;
+}
+
+.conductor-button:hover {
+  background: rgba(0, 0, 0, 0.04);
+}
+
+.conductor-button:disabled {
+  opacity: 0.4;
+  cursor: not-allowed;
+}
+
+.conductor-button--send {
+  background: var(--accent);
+  color: #fff;
+  border-color: transparent;
+}
+
+.conductor-button--send:hover {
+  background: var(--accent);
+  filter: brightness(0.92);
+}
+
+.conductor-button--interrupt {
+  background: #b04020;
+  color: #fff;
+  border-color: transparent;
+}
+
+.conductor-button--interrupt:hover {
+  filter: brightness(0.92);
+}
+
+/* ----- Mobile layout ------------------------------------------------------ */
+
+@media (max-width: 600px) {
+  .conductor-chat-view {
+    font-size: 15px;
+  }
+  .conductor-bubble {
+    max-width: 85%;
+  }
+}
+
+.conductor-chat-view[data-layout='mobile'] .conductor-bubble {
+  max-width: 85%;
+}
+
+.conductor-chat-view[data-layout='desktop'] .conductor-bubble {
+  max-width: 60%;
+}

package/dist/server/index.d.ts

@@ -0,0 +1,376 @@
+/**
+ * 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>;
+}
+
+/**
+ * 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;
+};
+
+/**
+ * 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;
+}
+
+declare class ProjectsApi {
+    private readonly fetcher;
+    /**
+     * Idempotent find-or-create on (daemonHost, workspacePath).
+     *
+     * Flow:
+     *   1. POST `/api/projects/match-path` with `{ daemonHost, path: workspacePath }`.
+     *      If a project matches (or is a parent of) the path, return it.
+     *   2. Otherwise POST `/api/projects` with binding fields. The server
+     *      validates the binding with the user's daemon. Success returns the
+     *      new project; daemon-offline returns 409 → mapped to `daemon_offline`.
+     *
+     * The created project carries `metadata.audit.createdByApp` so it can be
+     * distinguished in the main Conductor UI later. No new schema is required.
+     */
+    bind(input: BindProjectInput, opts?: {
+        signal?: AbortSignal;
+    }): Promise<Project>;
+    list(opts?: {
+        signal?: AbortSignal;
+    }): Promise<Project[]>;
+    get(projectId: string, opts?: {
+        signal?: AbortSignal;
+    }): Promise<Project>;
+}
+
+interface ConnectOptions {
+    /** Conductor backend URL, e.g. `https://conductor.example.com`. */
+    baseUrl: string;
+    /**
+     * Bearer token issued from Conductor Settings → API Tokens.
+     * Accepts a string or an async provider (for token rotation / vault lookup).
+     */
+    bearerToken: string | (() => Promise<string>);
+    /** Custom fetch (SSR, testing). Defaults to `globalThis.fetch`. */
+    fetch?: typeof globalThis.fetch;
+    /** Per-request timeout in ms. Default 30_000. */
+    timeoutMs?: number;
+    /** Called once when any request returns 401. */
+    onUnauthorized?: () => void;
+    /**
+     * Lazy: do not open the /ws/app connection until the first subscribe/stream
+     * call. Default `true`. Set to `false` to eagerly connect at `connect()`.
+     */
+    lazyWebSocket?: boolean;
+    /**
+     * Inject a custom WebSocket constructor (used by tests).
+     * Type widened to `unknown` to avoid forcing consumers to depend on the
+     * specific `ws` types.
+     */
+    webSocketImpl?: unknown;
+}
+type AppClientOptions = ConnectOptions;
+declare class AppClient {
+    readonly projects: ProjectsApi;
+    readonly tasks: TasksApi;
+    private readonly _fetcher;
+    private _socket;
+    private _closed;
+    private readonly options;
+    constructor(options: AppClientOptions);
+    /**
+     * Release the WS connection and mark the client closed. Idempotent —
+     * calling twice is a no-op rather than a NPE. After close, any new
+     * `tasks.subscribe()` / `tasks.streamReply()` / `tasks.*` REST call
+     * throws synchronously instead of returning a hanging iterator.
+     */
+    close(): Promise<void>;
+    private getOrCreateSocket;
+}
+/**
+ * `connect()`: thin async wrapper around the constructor. In v0.1 it's
+ * synchronous-ish (no remote probe); kept async for forward compatibility
+ * (v0.2 may probe `/api/auth/me` for early-failure semantics).
+ */
+declare function connect(options: ConnectOptions): Promise<AppClient>;
+declare class TasksApi {
+    private readonly rest;
+    private readonly getSocket;
+    private readonly isClosed;
+    private assertOpen;
+    create(input: CreateTaskInput, opts?: {
+        signal?: AbortSignal;
+    }): Promise<Task>;
+    get(taskId: string, opts?: {
+        signal?: AbortSignal;
+    }): Promise<Task>;
+    list(filter?: {
+        projectId?: string;
+        status?: string;
+    }, opts?: {
+        signal?: AbortSignal;
+    }): Promise<Task[]>;
+    sendMessage(taskId: string, input: string | SendMessageInput, opts?: {
+        signal?: AbortSignal;
+    }): Promise<Message>;
+    history(taskId: string, paging?: {
+        beforeId?: string;
+        limit?: number;
+    }, opts?: {
+        signal?: AbortSignal;
+    }): Promise<{
+        messages: Message[];
+        hasMoreBefore: boolean;
+        oldestMessageId: string | null;
+    }>;
+    interrupt(taskId: string, opts: {
+        targetReplyTo: string;
+        signal?: AbortSignal;
+    }): Promise<void>;
+    /**
+     * Subscribe to a task's event stream. Yields ChatEvents until the caller
+     * breaks out of the `for await` loop, calls `signal.abort()`, or the
+     * client is closed.
+     *
+     * The first call lazily opens a /ws/app connection; subsequent calls share
+     * the same connection.
+     */
+    subscribe(taskId: string, opts?: {
+        signal?: AbortSignal;
+        bufferCap?: number;
+    }): AsyncIterable<ChatEvent>;
+    /**
+     * Higher-level convenience: yield only AI reply deltas. Internally consumes
+     * `subscribe()` and selects runtime_status preview chunks + the final
+     * assistant message.
+     */
+    streamReply(taskId: string, opts?: {
+        signal?: AbortSignal;
+        emitInitialPreview?: boolean;
+        idleTimeoutMs?: number;
+    }): AsyncIterable<StreamReplyDelta>;
+}
+
+/**
+ * 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;
+
+export { AppClient, type AppClientOptions, type Attachment, type BindProjectInput, type ChatEvent, ConductorAppError, type ConnectOptions, type CreateTaskInput, type Message, type MessageRole, type Project, type RuntimeState, type RuntimeStatus, type SendMessageInput, type StreamReplyDelta, type Task, type TaskStatus, connect, isConductorAppError };