@agent-compose/sdk 0.7.0 → 0.8.0

package/src/types/api-conversations.ts

@@ -0,0 +1,522 @@
+/**
+ * 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;
+}
+
+// ── Conversations (wire shapes mirror routes/conversations.ts) ──────────────
+
+/** 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;
+  // ── Spawn options (ADR-0055 §2.5b) — the workflow-run call pattern ──────
+  /** 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;
+}
+
+// ── Session branch proposals (ADR-0053) ─────────────────────────────────────
+// Every cloud session works on its own factory-drive branch; the whole branch
+// is the unit of review, like a PR. Wire shapes mirror
+// server/src/routes/session-changes.ts verbatim (camelCase).
+
+/** 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;
+}
+
+// ── Channel-attached sessions (ADR-0057 — sessions VISIT channels) ──────────
+// A session can be brought into a channel for as long as a piece of work
+// lasts: attachment is a link (never a membership copy) granting the
+// channel's members derived access, and the session posts back into the
+// channel attributed as itself. Wire shapes mirror the channel-session
+// routes in server/src/routes/conversations.ts verbatim (camelCase).
+
+/** 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;
+}