@agent-compose/sdk 0.7.0 → 0.8.0

package/dist/types/api-conversations.d.ts

@@ -0,0 +1,492 @@
+/**
+ * Conversation-facing wire types for `AgentComposeClient` — channels, solo
+ * chats, sessions, threads, presence, team agents, and the
+ * teammate-mention surface.
+ *
+ * These are deliberate contract pins mirrored in `dashboard/src/lib/api.ts`;
+ * when the server changes a response shape, both update in the same change.
+ */
+import type { ConversationAgentPresence } from "./conversation-stream.js";
+import type { ConversationMemberRole } from "./api-scopes.js";
+import type { SandboxSize } from "../sandbox/sizes.js";
+import type { SandboxNetworkPolicy } from "../sandbox/network-policy.js";
+/** A human member of your team — the people an agent (or you) can @-flag. */
+export interface TeamMember {
+    /** Membership row id. */
+    id: string;
+    /** The user id — what you pass to `createMentions({ mentionedUserIds })`. */
+    userId: string;
+    role: string;
+    email: string;
+    name: string;
+    /** OAuth provider image URL, when present. */
+    image?: string | null;
+    /** Server-relative uploaded-avatar URL (ADR-0056), when set — takes
+     *  precedence over `image`. Prefix with your API base. */
+    avatarUrl?: string | null;
+    joinedAt: string;
+}
+/** A "you were flagged" ping, persisted server-side so it reaches the
+ *  mentioned teammate in their Workbench. */
+export interface Mention {
+    id: string;
+    factoryId: string;
+    mentionedUserId: string;
+    /** Who flagged: 'user' | 'api_key' | 'run' | 'system'. */
+    actorKind: string;
+    actorId: string | null;
+    actorLabel: string | null;
+    /** Where it lives: 'doc' | 'comment' | 'plan' | 'run'. */
+    contextKind: string;
+    contextPath: string | null;
+    /** Ready-made relative dashboard URL the Workbench card links to. */
+    contextUrl: string | null;
+    text: string;
+    runId: string | null;
+    seenAt: string | null;
+    resolvedAt: string | null;
+    createdAt: string;
+}
+export interface CreateMentionsInput {
+    /** Team-member user ids to flag (1–20). Discover them via `listMembers()`.
+     *  Non-members are dropped server-side. */
+    mentionedUserIds: string[];
+    /** The flag message shown in the teammate's Workbench. */
+    text: string;
+    contextKind: "doc" | "comment" | "plan" | "run";
+    /** Factory-relative file path or comment thread id, when applicable. */
+    contextPath?: string;
+    /** Ready-made relative dashboard URL the Workbench card links to (e.g.
+     *  `/factories/<slug>/files/view?path=<plan>`). */
+    contextUrl?: string;
+    runId?: string;
+    factorySlug?: string;
+}
+/** One part of a conversation message. Text/tool/error parts as persisted by
+ *  the server; unknown future part types flow through untyped. */
+export type ConversationMessagePart = {
+    type: string;
+} & Record<string, unknown>;
+export interface ConversationRow {
+    id: string;
+    /** null ⇔ visibility "dm" (human pair, no agent). */
+    agentId: string | null;
+    title: string | null;
+    visibility: "solo" | "shared" | "dm";
+    access: "public" | "private";
+    kind: "chat" | "session";
+    /** The dm pair's user ids (sorted); null for solo/shared. */
+    dmParticipantIds: string[] | null;
+    createdBy: string | null;
+    /** Per-conversation agent overrides. The wire always carries the
+     *  normalized full object (the server defaults every field);
+     *  `model: "default"` passes through to the agent's own model. */
+    agentConfig: {
+        model: string;
+        effort: string;
+        instructions: string;
+    };
+    createdAt: string;
+    updatedAt: string;
+    /** Per-viewer unread count — present on the list wire for session
+     *  callers; key callers see 0. */
+    unreadCount?: number;
+}
+export interface ConversationMessageRow {
+    id: string;
+    authorKind: string;
+    authorId: string | null;
+    parts: ConversationMessagePart[];
+    threadRootId: string | null;
+    reactions: Record<string, string[]>;
+    replyCount: number;
+    lastReplyAt: string | null;
+    createdAt: string;
+    /** Thread-root facepile (≤3) — present only on roots with replies. */
+    replyAuthors?: Array<{
+        kind: string;
+        id: string | null;
+    }>;
+    /** Set on a channel message an ATTACHED SESSION posted (ADR-0057 Seam 4)
+     *  — the session conversation it speaks as. Renderers attribute these
+     *  rows to the session (title + runtime mark), never a resident agent.
+     *  Null once the session is deleted; absent on older servers. */
+    sourceSessionId?: string | null;
+    /** Set on a session-transcript row RELAYED from a channel mention
+     *  (ADR-0057 Seam 3) — the channel it arrived from. Null once the
+     *  channel is deleted; absent on older servers. */
+    sourceChannelId?: string | null;
+    /** Set on relay rows alongside sourceChannelId — the ORIGIN channel
+     *  message the mention rode in on (the session's default post-back
+     *  threads under it). Null once deleted; absent on older servers. */
+    sourceMessageId?: string | null;
+}
+export interface ConversationsPage {
+    conversations: ConversationRow[];
+    next_cursor: string | null;
+}
+/** Sessions page — each row additionally carries its resident
+ *  executor substrate (ADR-0037 §8): `"cloud"` = persistent server-side
+ *  sandbox (pickers render the ☁ marker), `"local"` = bridge daemon,
+ *  null = no durable session record yet. */
+export interface SessionsPage {
+    conversations: Array<ConversationRow & {
+        sessionExecutor: "local" | "cloud" | null;
+    }>;
+    next_cursor: string | null;
+}
+export interface ConversationDetail {
+    conversation: ConversationRow;
+    /** Resident executor substrate (ADR-0037 §8): `"local"` = a developer's
+     *  bridge daemon; `"cloud"` = a persistent server-side sandbox on the
+     *  factory drive; null = no durable session record (platform agents, or
+     *  a bridge conversation before its first turn). Surfaces use this for
+     *  presence labels only — attaching/driving is identical either way. */
+    sessionExecutor?: "local" | "cloud" | null;
+    /** The session's type (ADR-0055 §9) — the ONE surface decision, fixed at
+     *  creation: `chat` = transcript + composer (no terminal, ever);
+     *  `terminal`/`custom` = the PTY (`agentc session terminal`, no chat
+     *  pane). Null = no durable session record; absent on older servers
+     *  (read loosely). */
+    sessionType?: "chat" | "terminal" | "custom" | null;
+    /** The resident agent's slash-command palette, as reported by the
+     *  executor (ACP `available_commands_update`) — drives "/" autocomplete
+     *  in drivers. Null/absent when never reported (platform agents, older
+     *  daemons/servers). */
+    sessionCommands?: Array<{
+        name: string;
+        description: string;
+    }> | null;
+    viewerLastReadAt: string | null;
+    /** The caller's role in this conversation (ADR-0045) — drives client
+     *  affordances only; the server remains the authority on every action.
+     *  Public channels report implicit `write` for non-member teammates. */
+    viewerRole: ConversationMemberRole;
+    /** SSE replay watermark: the conversation's highest durable stream-event
+     *  id at hydrate time — everything at or below it is already folded into
+     *  `messages`. Seed the stream's first `Last-Event-ID` from it instead of
+     *  0 (0 replays the entire history). Absent on older servers. */
+    streamCursor?: number;
+    messages: ConversationMessageRow[];
+}
+/** Input for `createCloudSession` (ADR-0037 Phase 3b / ADR-0055 §9). The
+ *  session runs against a CLOUD CHECKOUT on the factory's drive — never the
+ *  caller's local files. Its TYPE is fixed at creation, never switched. */
+export interface CreateCloudSessionInput {
+    /** Session type (ADR-0055 §9): `chat` = the wrapped agent experience (a
+     *  coding runtime driven via ACP — no terminal, ever); `terminal` = a raw
+     *  machine surface (the PTY is the surface — no chat pane); `custom` = a
+     *  terminal born with a pre-start recipe (`presetId`/`preStart`). Omitted
+     *  = derived server-side (runtime `terminal` → terminal, else chat) — the
+     *  wire-level grandfather for older callers; send it explicitly. */
+    type?: "chat" | "terminal" | "custom";
+    /** In-sandbox coding runtime hosting a CHAT session. Required for chat;
+     *  omitted (or `"terminal"`) for terminal/custom sessions — those have no
+     *  harness, the shell is the surface. */
+    runtime?: "codex" | "cursor" | "droid" | "opencode" | "claude-code" | "terminal";
+    /** Custom sessions: a saved launch preset, resolved server-side and
+     *  FROZEN into the session's pre-start at create (a later preset edit
+     *  never changes an existing session). Exactly one of `presetId` /
+     *  `preStart` is required for custom; both are 400s on other types. */
+    presetId?: string;
+    /** Custom sessions: an inline pre-start recipe — the bootstrap exec'd
+     *  into the session's first pty (e.g. boot the claude-code TUI), with
+     *  `preLaunch` an invisible shell fragment run before it. */
+    preStart?: {
+        command: string;
+        args?: string[];
+        env?: Record<string, string>;
+        preLaunch?: string | null;
+    };
+    /** Factory whose durable drive backs the session's working tree. */
+    factoryId: string;
+    title?: string;
+    /** Optional repo bootstrap: an https git URL cloned onto the drive on
+     *  first turn (idempotent — survives sandbox eviction). */
+    repoUrl?: string;
+    repoBranch?: string;
+    /** Spawn-in-channel (ADR-0057 Seam 1): attach the new session to this
+     *  channel in the same transaction — born attached, every channel member
+     *  has derived access from birth. Requires channel role ≥ write. */
+    channelId?: string;
+    /** Boot from a saved session template (its provider snapshot resolves
+     *  server-side — snapshot refs never cross the wire). Mutually exclusive
+     *  with `sandboxSize`: a snapshot captures its machine spec (400). */
+    templateId?: string;
+    /** Machine size in the run `sandboxSize` vocabulary. Sessions are E2B,
+     *  so only the E2B-buildable sizes are accepted (400 otherwise).
+     *  Omitted = the platform default. */
+    sandboxSize?: SandboxSize;
+    /** Egress policy — the same `SandboxNetworkPolicy` allow-map runs carry
+     *  ("deny-all" = connectors-only: the platform re-widens it with the
+     *  drive gateway + attached connector hosts at every acquire). Omitted =
+     *  open egress. */
+    networkPolicy?: SandboxNetworkPolicy;
+    /** Birth connector attachment (ADR-0044): one of the owner's connector
+     *  profile ids, or "none" for a bare session. Omitted = the owner's
+     *  default profile. */
+    connectorProfileId?: string;
+}
+export interface CloudSessionCreated {
+    conversation: ConversationRow;
+    session: {
+        executor: "cloud";
+        /** The session's type (ADR-0055 §9) — decides its ONE surface: chat
+         *  opens the transcript TUI; terminal/custom open with
+         *  `agentc session terminal <id>` (the PTY, no chat pane). */
+        type: "chat" | "terminal" | "custom";
+        runtime: string;
+        sandboxProvider: string;
+        /** Drive-backed working directory inside the session sandbox. */
+        cwd: string;
+        repoUrl: string | null;
+        repoBranch: string | null;
+    };
+    /** Present when the session was spawned in a channel (`channelId` input)
+     *  — the channel it was born attached to. */
+    attachedChannelId?: string;
+}
+export interface ConversationThread {
+    root: ConversationMessageRow;
+    /** Oldest→newest; the root is not repeated. */
+    messages: ConversationMessageRow[];
+}
+/** One live dev preview on a cloud session (ADR-0052 §4). The directory row
+ *  the UI lists; the security boundary is the member-gated proxy + the
+ *  short-lived token, never this row. */
+export interface SessionPreview {
+    id: string;
+    /** Port bound inside the session sandbox. */
+    port: number;
+    name: string | null;
+    /** The preview's stable SUBDOMAIN label — it serves fully navigable at
+     *  `<label>.<preview wildcard host>` when the deployment configures
+     *  `PREVIEW_WILDCARD_ORIGIN`. Null on rows opened before labels existed
+     *  (they stay on the path-prefixed proxy URL). */
+    label: string | null;
+    /** The app's announced landing path (e.g. `/dashboard`); null = `/`. */
+    path: string | null;
+    status: "active" | "closed";
+    /** The member-gated preview URL, bound to the requesting viewer — the
+     *  subdomain bootstrap URL when the deployment supports it, else the
+     *  path-prefixed proxy URL on the isolated preview origin (ADR-0052 §2.3).
+     *  `null` when previews are disabled or the caller is not a user. */
+    url: string | null;
+    createdAt: string;
+    lastSeenAt: string;
+}
+/** Result of opening a dev preview (`POST /conversations/:id/preview`). */
+export interface PreviewOpened {
+    preview: SessionPreview;
+    /** The member-gated proxy URL to open in a browser (never the raw host). */
+    url: string;
+}
+/** Input for `openPreview`. */
+export interface OpenPreviewInput {
+    /** Port a dev server is LISTENING on inside the session sandbox (1–65535). */
+    port: number;
+    name?: string;
+    /** The app's landing path (e.g. `/dashboard`) — where the preview card and
+     *  chips land the human. Root-relative (`/…`, never `//…`). */
+    path?: string;
+}
+/** Result of forking a cloud session (`POST /conversations/:id/fork`). */
+export interface SessionForked {
+    /** The new child conversation to switch to. */
+    conversationId: string;
+}
+/** One changed file on a session's drive branch relative to `main`. */
+export interface SessionFileChange {
+    /** Factory-relative path. */
+    path: string;
+    kind: "add" | "modify" | "delete";
+    /** Size of the proposed object; null for deletes. */
+    sizeBytes: number | null;
+    /** The proposed object's etag; null for deletes. */
+    etag: string | null;
+}
+/** The session's proposed change set (`GET /conversations/:id/changes`).
+ *  `state: "unbranched"` = the session predates branching and still writes
+ *  `main` directly (it transitions at its next fresh sandbox acquire);
+ *  `branch`/`changes` are null/empty then. The `label` states the freshness
+ *  contract: the list reflects the branch's last flush and is advisory —
+ *  the merge re-verifies against fresh state. */
+export interface SessionChangeSet {
+    object: "session_change_set";
+    conversationId: string;
+    branch: string | null;
+    state: "unbranched" | "clean" | "dirty";
+    label: string;
+    /** False = the branch can only be discarded: a FORKED session's branch
+     *  carries its parent's unmerged work with no main-derived merge base, so
+     *  `mergeSessionChanges` 409s `fork_branch_unmergeable`. */
+    mergeable: boolean;
+    changes: SessionFileChange[];
+    /** True when the listing was capped — more files changed than shown. */
+    truncated: boolean;
+    /** Open `factory_file_conflicts` rows from this session's prior merges. */
+    openConflicts: number;
+}
+/** Per-file accounting of one session branch merge — the merge core's
+ *  honest report, returned verbatim. */
+export interface SessionMergeReportDetail {
+    branch: string | null;
+    merged: number;
+    fastForwarded: number;
+    autoMerged: number;
+    created: number;
+    deleted: number;
+    skipped: number;
+    untouched: number;
+    skippedLossy: number;
+    droppedPaths: string[];
+    conflicts: number;
+}
+/** Result of approving a session's changes
+ *  (`POST /conversations/:id/changes/merge`): the old branch was 3-way
+ *  merged into `main` and the session continues on `newBranch`, freshly
+ *  forked off post-merge `main`. `merged_with_conflicts` means some paths
+ *  landed as `factory_file_conflicts` rows for human resolution. */
+export interface SessionMergeReport {
+    object: "session_merge_report";
+    conversationId: string;
+    /** The branch that was merged. */
+    branch: string;
+    /** The session's fresh branch off post-merge `main`. */
+    newBranch: string;
+    status: "merged" | "merged_with_conflicts";
+    report: SessionMergeReportDetail;
+}
+/** Result of rejecting a session's changes
+ *  (`POST /conversations/:id/changes/discard`): the old branch is abandoned
+ *  (retained dormant, recoverable by an admin re-merge — never deleted) and
+ *  the session continues on `newBranch`, freshly forked off `main`. */
+export interface SessionDiscardReport {
+    object: "session_discard_report";
+    conversationId: string;
+    /** The abandoned branch. */
+    branch: string;
+    /** The session's fresh branch off `main`. */
+    newBranch: string;
+    discarded: true;
+}
+/** The sender's page stamp (HUD bar sends) — persisted server-side, never
+ *  echoed back on the wire. Mirrors the server's `PageContext` schema. */
+export interface ConversationPageContext {
+    kind: string;
+    path: string;
+    entity?: {
+        type: string;
+        id: string;
+        label?: string;
+    };
+}
+export interface SendConversationMessageInput {
+    text: string;
+    /** Land the message in this ROOT message's thread (channels only; the
+     *  triggered turn streams into the same thread). */
+    threadRootId?: string;
+    pageContext?: ConversationPageContext;
+}
+/** The server's authoritative turn verdict on a send (ADR-0037 §4):
+ *  `none` = no turn owed (dm, or a channel message that doesn't @-tag the
+ *  agent); `started` = this send won the turn claim and the reply is
+ *  streaming; `queued` = a turn is already in flight — the message is owed
+ *  work and a coalesced follow-up turn will answer it. NOT an error. */
+export type ConversationTurnState = "none" | "started" | "queued";
+export interface SendConversationMessageResult {
+    /** The persisted user message's id. */
+    messageId: string;
+    /** Whether an agent turn was kicked — the "replying" indicator keys off
+     *  this, never a client-side re-parse. */
+    turnTriggered: boolean;
+    turnState: ConversationTurnState;
+    /** Channel sends only (ADR-0057 Seam 3): the attached sessions this
+     *  message was relayed into via `[@Title](session:<id>)` mentions —
+     *  each runs its own turn in its own conversation. Absent on older
+     *  servers and non-channel sends. */
+    relayedSessionIds?: string[];
+}
+/** Response of the presence heartbeat (ADR-0037 §6): a fresh agent-liveness
+ *  snapshot + the roster TTL. The attach roster itself is NOT returned —
+ *  there is no server-side roster; subscribers assemble it from the
+ *  live-only `presence` beats on the conversation stream. */
+export interface ConversationPresenceSnapshot {
+    agent: ConversationAgentPresence | null;
+    /** A roster entry whose last beat is older than this has detached. */
+    ttlMs: number;
+}
+/** Durable rail status for one attached session (ADR-0057 Seam 5) — all
+ *  derived from existing signals server-side; no background polling. */
+export interface ChannelSessionStatus {
+    /** `running` = a turn is executing (turn claim fresh); else `idle`. */
+    state: "running" | "idle";
+    /** Viewer-scoped unread count (conversation_reads — works for derived
+     *  viewers). 0 for key callers. */
+    unreadCount: number;
+    /** An agent ask is awaiting a human answer (bounded transcript scan). */
+    awaiting: boolean;
+    /** The most recent agent-authored message contains an error part. */
+    lastTurnFailed: boolean;
+    lastAgentMessageAt: string | null;
+}
+/** One session attached to a channel, as listed by
+ *  `GET /conversations/:channelId/sessions` (newest attach first). */
+export interface ChannelSessionRow {
+    conversationId: string;
+    title: string | null;
+    /** The hosting in-sandbox runtime (agent_sessions.agent_kind); null for
+     *  platform-loop sessions. */
+    runtime: string | null;
+    /** The session's type (ADR-0055 §9); null for platform-loop sessions,
+     *  absent on older servers (read loosely). */
+    sessionType?: "chat" | "terminal" | "custom" | null;
+    /** Executor substrate; null = platform-loop session (no durable
+     *  agent_sessions row). */
+    executor: "local" | "cloud" | null;
+    attachedAt: string;
+    /** Who attached it (provenance only); null when the user is gone. */
+    addedBy: string | null;
+    status: ChannelSessionStatus;
+}
+/** Response of `GET /conversations/:channelId/sessions`, verbatim. */
+export interface ChannelSessionsResponse {
+    sessions: ChannelSessionRow[];
+}
+/** Result of posting into a channel AS a session
+ *  (`POST /conversations/:channelId/session-messages`, ADR-0057 Seam 4).
+ *  The post never triggers any turn — it is a report, not an address. */
+export interface SessionChannelMessagePosted {
+    messageId: string;
+    /** Where the post landed: the thread root it replied under (by default,
+     *  the message that last addressed the session from that channel), or
+     *  null for a room post. Absent on older servers. */
+    threadRootId?: string | null;
+}
+/** One agent on the team, as listed by `GET /api/v1/agents`. Bridge-runtime
+ *  rows additionally carry live presence (`online`, from the daemon's
+ *  heartbeat within the server's TTL) and the hosting machine's label. */
+export interface AgentListRow {
+    id: string;
+    name: string;
+    runtime: string;
+    avatarSeed: string;
+    model: string;
+    systemPrompt: string | null;
+    factoryIds: string[];
+    /** Verbatim jsonb from the server — tool-policy shape is runtime-defined. */
+    toolPolicy: Record<string, unknown>;
+    createdAt: string;
+    online?: boolean;
+    machineName?: string;
+    /** Stamped `"cloud"` on rows whose sessions are hosted server-side —
+     *  session pickers filter on this rather than presence. */
+    sessionHost?: "cloud";
+}
+export interface StreamConversationOptions {
+    /** Highest durable stream-event id already processed — the server replays
+     *  only rows with id greater than this. Never advance it from live-only
+     *  events (`part_partial` / `turn_state` / `presence` / `session_status`). */
+    lastEventId?: number;
+    signal?: AbortSignal;
+}