@agent-compose/sdk 0.8.5 → 0.8.7

package/src/types/api-conversations.ts

@@ -9,6 +9,7 @@
 
 import type { ConversationAgentPresence } from "./conversation-stream.js";
 import type { ConversationMemberRole } from "./api-scopes.js";
+import type { ProjectRole } from "./api-projects.js";
 import type { SandboxSize } from "../sandbox/sizes.js";
 import type { SandboxNetworkPolicy } from "../sandbox/network-policy.js";
 
@@ -46,6 +47,9 @@ export interface Mention {
   contextUrl: string | null;
   text: string;
   runId: string | null;
+  /** The chat message the ping came from (conversation pings from a send
+   *  or an edit); null otherwise. */
+  messageId: string | null;
   seenAt: string | null;
   resolvedAt: string | null;
   createdAt: string;
@@ -89,10 +93,36 @@ export interface ConversationRow {
    *  `model: "default"` passes through to the agent's own model. */
   agentConfig: { model: string; effort: string; instructions: string };
   createdAt: string;
+  /** The ROW's write time — every write bumps it, invisible background
+   *  rows included. Recency people see is `lastMessageAt`. */
   updatedAt: string;
-  /** Per-viewer unread count — present on the list wire for session
-   *  callers; key callers see 0. */
+  /** Per-viewer unread room messages — present on the list wire for
+   *  session callers; key callers see 0. */
   unreadCount?: number;
+  /** Per-viewer unread replies in the channel threads the viewer follows
+   *  (wrote the root or a reply) — read only by opening the thread.
+   *  List wire; key callers see 0. */
+  threadUnreadCount?: number;
+  /** When the conversation last had something a person can SEE (a
+   *  message that renders, room or thread) — "last active" and the rail's
+   *  order. Null when nothing visible is recent. List wire. */
+  lastMessageAt?: string | null;
+  /** The projects holding this chat that the caller can see — a member
+   *  row, or a team-public project (role `read`) — each with the object
+   *  row that files it. Empty for a chat in no visible project; a private
+   *  project the caller is outside is never named. List wire. */
+  projects?: ConversationProject[];
+}
+
+/** A project a chat is filed in, as the caller may see it: the project,
+ *  the caller's role there (a member row's, or a public project's `read`
+ *  floor) and the object row that files the chat — the id a
+ *  `removeProjectObject` of that filing takes. */
+export interface ConversationProject {
+  id: string;
+  name: string;
+  role: ProjectRole;
+  objectId: string;
 }
 
 /** Agent-author identity decoration (mirrors the server's `agentAuthor`
@@ -108,6 +138,9 @@ export interface ConversationAgentAuthor {
   avatarSeed: string;
   ownerUserId: string | null;
   ownerName: string | null;
+  /** True when this agent IS Ivy (a user's assistant or a shared chat's
+   *  resident): render Ivy's one mark, never `avatarSeed`. */
+  ivy: boolean;
 }
 
 export interface ConversationMessageRow {
@@ -134,6 +167,11 @@ export interface ConversationMessageRow {
    *  (absent on older servers). */
   editedAt?: string | null;
   createdAt: string;
+  /** When the row's words first landed, on a reply row its turn opened
+   *  before it had any; null for a row sent with its words. Read state
+   *  dates a message by the later of this and `createdAt`: a reply that
+   *  lands after a read is new. Absent on older servers. */
+  publishedAt?: string | null;
   /** 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)
@@ -371,6 +409,37 @@ export interface ConversationThread {
   root: ConversationMessageRow;
   /** Oldest→newest; the root is not repeated. */
   messages: ConversationMessageRow[];
+  /** The viewer's thread read cursor before this visit (ISO) — the
+   *  panel's "new replies" divider; null when they never read it. */
+  viewerLastReadAt: string | null;
+}
+
+/** GET /conversations/unread — every chat with something unread for the
+ *  caller (the sidebar, project rollups and space totals read this one
+ *  summary). Session callers only; keys get an empty list. */
+export interface ConversationUnreadSummary {
+  conversations: Array<{ conversationId: string; unreadCount: number; threadUnreadCount: number }>;
+  /** A server bound cut the list. */
+  truncated: boolean;
+}
+
+/** GET /conversations/:id/unread-threads — one channel's threads with
+ *  unread replies for the caller, in transcript order. */
+export interface ConversationUnreadThreads {
+  threads: Array<{ rootId: string; unreadCount: number }>;
+  truncated: boolean;
+}
+
+/** POST /conversations/:id/read — what the caller SAW (`through` the newest
+ *  message they had in view), or the explicit wholesale read (`all`). */
+export type ConversationReadInput = { through: string } | { all: true };
+
+export interface ConversationReadResult {
+  ok: true;
+  /** The thread the read moved; null = the room. */
+  threadRootId: string | null;
+  /** That place's cursor after the read (ISO). */
+  readAt: string;
 }
 
 /** One live dev preview on a cloud session (ADR-0052 §4). The directory row
@@ -396,13 +465,24 @@ export interface SessionPreview {
   url: string | null;
   createdAt: string;
   lastSeenAt: string;
+  /** The hosting session (a chat's list spans the sessions attached to the
+   *  chat; a session's own list names itself) and its liveness: `live` =
+   *  the machine runs now, `parked` = suspended (an open wakes it), `gone`
+   *  = the machine was reclaimed. */
+  sessionId: string;
+  sessionTitle: string | null;
+  sessionState: "live" | "parked" | "gone";
 }
 
 /** 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;
+  /** The member-gated preview URL to open in a browser (never the raw host),
+   *  minted for the PERSON who opened it. `null` when the opener is the
+   *  session's own machine key (`agentc preview open` inside the sandbox):
+   *  a machine gets no link; every person who looks mints their own from
+   *  the live previews list (the card, the chat's Previews chip). */
+  url: string | null;
 }
 
 /** Input for `openPreview`. */
@@ -442,6 +522,121 @@ export interface BackgroundWorkChildDecl {
   label?: string;
 }
 
+// ── Session waits (owner ruling 2026-09-23: no watch runs inside a session
+// sandbox; the worker declares what it waits for and the platform senses it,
+// `POST/GET/DELETE /sessions/:id/waits`) ──────────────────────────────────────
+
+export type SessionWaitKind = "mail" | "time" | "need" | "github" | "webhook" | "schedule";
+export type SessionWaitState = "open" | "satisfied" | "expired" | "cancelled";
+
+/** What a session asks to be woken for. A mail wait names a sender (a full
+ *  address or "@domain") with an optional subject regex and ONE deadline
+ *  form (`forMs` from now, or an ISO `until`; default a day); a time wait
+ *  names its instant, which is also its deadline. */
+export type CreateSessionWaitInput =
+  | { kind: "mail"; from: string; subject?: string; forMs?: number; until?: string; label?: string }
+  | { kind: "time"; at: string; label?: string }
+  // STANDING waits (owner 2026-09-27): open across fires; every fire tells
+  // the session's thread agent and wakes the session while it is alive.
+  | { kind: "github"; repo: string; events?: Array<"workflow_run" | "check_run" | "check_suite" | "status" | "release" | "tag">; branches?: string[]; conclusions?: string[]; label: string; cooldownMinutes?: number; forDays?: number; forHours?: number }
+  | { kind: "webhook"; label: string; cooldownMinutes?: number; forDays?: number; forHours?: number }
+  | {
+    kind: "schedule"; cron?: string; everyMinutes?: number; timezone: string; label: string;
+    /** The wait's lifetime (one of the two). A plain schedule more often
+     *  than hourly is armed with one, or with `noEndReason`. */
+    forDays?: number; forHours?: number; noEndReason?: string;
+    /** A SCRIPTED CHECK: the workspace's own registered workflow each tick
+     *  runs instead of waking anyone, the input every run gets, the vault
+     *  keys it reads (from the grants of the chat it is armed from, or of
+     *  that chat's project), the person's message it answers, and a per-run
+     *  model allowance when it must call a small model. Its first run is
+     *  reviewed by the thread's agent before its schedule starts; then only
+     *  what a run reports as needing attention (`attention: { summary,
+     *  evidence }`), a run that measured nothing (no `measured`), or once a
+     *  failure reaches the thread's agent. */
+    workflow?: string; input?: Record<string, unknown>; credentials?: string[]; askedIn?: string; modelBudgetUsd?: number;
+  };
+
+/** How one scripted check run came out, as its wait records it. `breach`:
+ *  it reported no attention and measured nothing (missing data is
+ *  attention, never all clear). */
+export interface SessionWaitCheckResult {
+  runId: string | null;
+  at: string;
+  result: "clear" | "attention" | "breach" | "failed" | "not_run";
+  summary: string;
+  /** What the run reported it measured (`measured` in its output). */
+  measured?: unknown;
+  digest?: string;
+  inARow?: number;
+  /** Whether it reached the thread's agent. */
+  woke: boolean;
+}
+
+/** One review the thread agent recorded of a scripted check. */
+export interface SessionWaitCheckReview {
+  at: string;
+  findings: string;
+  /** The registered version it reviewed (a content hash). */
+  version: string | null;
+  confirmed?: boolean;
+}
+
+/** A scripted check as its wait carries it. */
+export interface SessionWaitCheck {
+  /** proving: its first run awaits the thread agent's review; live: it runs
+   *  on its schedule. */
+  state: "proving" | "live" | null;
+  version: string | null;
+  /** The run going now. */
+  runId: string | null;
+  lastResult: SessionWaitCheckResult | null;
+  /** The agent's reviews of it, newest first (the last 20). */
+  reviews: SessionWaitCheckReview[];
+  nextReviewAt: string | null;
+}
+
+/** One declared wait as the server renders it. */
+export interface SessionWait {
+  object: "session_wait";
+  id: string;
+  kind: SessionWaitKind;
+  /** mail: { from, subject? }; time: { instant }. */
+  spec: Record<string, unknown>;
+  label: string | null;
+  /** ISO deadline (a time wait's instant); a standing wait's lifetime, or
+   *  null when it lives until cancelled. */
+  until: string | null;
+  state: SessionWaitState;
+  /** What settled it: the mail's from, subject and Gmail message id; the
+   *  instant; or the deadline that passed. Null while open or cancelled. */
+  satisfiedBy: Record<string, unknown> | null;
+  createdAt: string;
+  updatedAt: string;
+  /** Standing waits only: how often it fired, when last, and a schedule's
+   *  next instant. */
+  fireCount?: number;
+  lastFiredAt?: string | null;
+  nextFireAt?: string | null;
+  /** A webhook wait: the URL a monitoring tool POSTs to, and how to use it. */
+  webhookUrl?: string | null;
+  instructions?: string;
+  /** A scripted check: where it stands, its run going now, how the latest
+   *  one came out, and the agent's reviews of it. */
+  check?: SessionWaitCheck;
+}
+
+/** The 201 of a declared wait: the row plus the one sentence the worker
+ *  acts on ("the platform wakes this session when it arrives"). */
+export interface SessionWaitCreated extends SessionWait {
+  message: string;
+}
+
+export interface SessionWaitList {
+  object: "list";
+  waits: SessionWait[];
+}
+
 /** Outcome of requesting one machine size up
  *  (`POST /conversations/:id/machine/request-upsize` — task #110, the
  *  auto-resize policy's agent door). The platform arbitrates: within the
@@ -579,6 +774,36 @@ export interface SessionChangeSet {
   reviewDocuments?: SessionReviewDocument[];
 }
 
+/** The one fact keeping a session branch's version of a file off main
+ *  (`SessionFilePlane.why`): an open conflict on the session's branch (one
+ *  conflicting path holds every file on it), an open merge card, the
+ *  session's merge gate, a linked repository's folder — or none of those,
+ *  the session simply has not landed it yet. */
+export type SessionFileHold = "in_progress" | "conflict" | "awaiting_approval" | "merge_gated" | "linked_repo";
+
+/** Where ONE path's current version lives (`GET /conversations/:id/changes/file`),
+ *  decided when a link to it is opened: `main` when the main drive holds the
+ *  session branch's version (landed, or never changed on the branch), else
+ *  `branch` with `why` naming what keeps it off main. `change`, `why` and
+ *  `approvalId` are null and `conflictPaths` empty on the main plane. */
+export interface SessionFilePlane {
+  object: "session_file_plane";
+  conversationId: string;
+  path: string;
+  plane: "main" | "branch";
+  branch: string | null;
+  change: "add" | "modify" | null;
+  why: SessionFileHold | null;
+  /** The open merge card waiting on this session's branch, if any. */
+  approvalId: string | null;
+  /** `why: "conflict"`: the session's open conflicts, oldest first, capped
+   *  — the path itself when it is one of them, else what holds it. */
+  conflictPaths: string[];
+  /** The session the link named: its title, its status, and whether the
+   *  platform lands its drive work on main as it goes (a thread's worker). */
+  session: { title: string | null; status: string; worker: boolean };
+}
+
 /** One reviewer's published review document
  *  (`SessionChangeSet.reviewDocuments`). `stale` compares the head this
  *  document was published against with the served diff. */
@@ -882,6 +1107,9 @@ export interface SendConversationMessageResult {
    *  private channel pings members only; a DM pings only the pair) —
    *  present only when non-empty. Absent on older servers. */
   unnotifiedMentions?: UnnotifiedMention[];
+  /** This send made the sender a member of the public chat (posting
+   *  joins). Present only when it happened; absent on older servers. */
+  joined?: true;
 }
 
 /** Response of the presence heartbeat (ADR-0037 §6): a fresh agent-liveness
@@ -911,11 +1139,35 @@ export interface ChannelSessionStatus {
   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. */
+  /** The most recent agent-authored message contains an error part and the
+   *  newest turn was not stopped (a stop is not a failure). */
   lastTurnFailed: boolean;
+  /** The newest turn ended by a stop: someone stopped it on purpose (a
+   *  person, Ivy, the session's thread agent, the platform enforcing one of
+   *  those). */
+  lastTurnStopped: boolean;
   lastAgentMessageAt: string | null;
 }
 
+/** A chat worker's chip facts (owner 2026-09-28) — set only when the
+ *  session is one of this chat's workers. Never viewer-scoped. */
+export interface ChannelWorkerFacts {
+  /** The chat message the worker was started under; null = no anchor. */
+  originMessageId: string | null;
+  /** The model stamped at birth; null = the runtime's own default. */
+  model: string | null;
+  /** The worker's session has ended. */
+  ended: boolean;
+  /** Parked on an open question to its thread agent (work unfinished). */
+  parked: boolean;
+  /** Its one-line status ("Reading the Fly logs"), when that text was set
+   *  (ISO) and how old it was when read (`ageSec`: a live turn whose words
+   *  are old has produced nothing since), while the turn the line describes
+   *  is running; null otherwise. Live updates ride the channel's
+   *  `session_status` frames. */
+  statusLine: { text: string; at: string; ageSec: number } | null;
+}
+
 /** One session attached to a channel, as listed by
  *  `GET /conversations/:channelId/sessions` (newest attach first). */
 export interface ChannelSessionRow {
@@ -933,6 +1185,8 @@ export interface ChannelSessionRow {
   attachedAt: string;
   /** Who attached it (provenance only); null when the user is gone. */
   addedBy: string | null;
+  /** Set ⇔ the session is one of this chat's workers. */
+  worker: ChannelWorkerFacts | null;
   status: ChannelSessionStatus;
 }
 
@@ -941,17 +1195,6 @@ 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;
-}
-
 /** Result of `POST /session-messages` — one session's agent messaging
  *  ANOTHER session's conversation (`agentc session message @alias`). Unlike
  *  a channel post, this DOES wake the target's turn machinery: `turn` is
@@ -1038,9 +1281,12 @@ export interface StreamConversationOptions {
   signal?: AbortSignal;
 }
 
-/** Shared chat creation includes its own Ivy unless explicitly disabled. */
+/** Shared chat creation includes its own Ivy unless explicitly disabled.
+ *  A chat is named for its topic: `title` is required (the server refuses
+ *  a shared chat without one — a conversation with people and no name is
+ *  a direct message, which people start themselves in the dashboard). */
 export interface CreateChatInput {
-  title?: string;
+  title: string;
   visibility: "shared";
   access?: "public" | "private";
   memberIds?: string[];
@@ -1049,10 +1295,107 @@ export interface CreateChatInput {
 export interface ChannelIvyState {
   projects: Array<{ id: string; name: string }>;
   agent: AgentListRow | null;
-  enabled: boolean; agentId: string | null; canManage: boolean; nextReviewAt: string | null;
-  work: Array<{ id: string; title: string; status: string; evidence: string; nextAction: string; waitingOn: string | null; reviewAt: string | null }>;
+  enabled: boolean; agentId: string | null; canManage: boolean;
+}
+/** Where a GitHub grant lives: the whole workspace, one project, or one
+ *  private chat. */
+export type IvyConnectionScope = "workspace" | "project" | "chat";
+/** A GitHub App installation's repositories granted to one scope. `scope`
+ *  says where it lives, `projectId` or `chatId` which one, and `scopeName`
+ *  that project's name or chat's title (null for the workspace). */
+export interface IvyConnection {
+  id: string; teamId: string; scope: IvyConnectionScope; projectId: string | null; chatId: string | null; scopeName: string | null;
+  provider: "github"; installationId: string;
+  accountLogin: string; repositories: string[];
+  /** ADR-0065 capabilities on the connection: allowWrites = issues
+   *  (create, update, comment), allowCodeWrites = code (push branches, open
+   *  pull requests). Every connection reads its repositories. */
+  allowWrites: boolean; allowCodeWrites: boolean; configuredBy: string | null;
+  /** The name of the person who granted it (last shared or changed); null
+   *  when they are gone or unnamed. */
+  configuredByName: string | null;
+  updatedAt: string;
+}
+/** An inherited grant of a project the caller does not read: the fact that
+ *  a project they are not in grants something here, nothing more. */
+export interface HiddenIvyConnection { id: string; provider: "github"; scope: "project"; hidden: true }
+/** One scope's listing: its own grants, the ones it inherits (a project
+ *  the workspace's; a chat the workspace's and each project it is in),
+ *  whether the caller may remove and add here (canManage), whether the
+ *  scope takes a new grant now at all (addable: a chat's only while it is
+ *  private), and who can grant here when the caller cannot. */
+export interface IvyConnectionsView {
+  own: IvyConnection[];
+  inherited: Array<IvyConnection | HiddenIvyConnection>;
+  canManage: boolean;
+  addable: boolean;
+  granters: string[];
+  /** The TEAM CONNECTIONS of this scope (owner 2026-10-01): the
+   *  workspace's own, and what a project or chat inherits from the
+   *  workspace. Absent on an older server. */
+  workspaceConnections?: WorkspaceConnectionsScopeView;
+  /** The listing is a PAGE (`limit`, `cursor` on the request): its rows are
+   *  one bounded read in scope order, and `nextCursor` opens the next page;
+   *  null at the end. */
+  nextCursor: string | null;
+}
+/** One page of a scope listing: `cursor` is the previous page's
+ *  `nextCursor`; `limit` (1..200, 50 by default) its size. */
+export interface ListingPage { cursor?: string; limit?: number }
+/** Where a team connection is shared, as the caller may read it: a
+ *  project they are not in and a chat they do not read keep their ids and
+ *  lose their names. */
+export type WorkspaceConnectionAudienceEntry =
+  | { scope: "workspace" }
+  | { scope: "project"; projectId: string; name: string | null }
+  | { scope: "chat"; chatId: string; title: string | null };
+/** A TEAM-OWNED connection of a tool (Linear first): a dedicated account's
+ *  pasted key or the provider's app installed as itself, with the admin's
+ *  label, the provider's capability keys it enables, and who it is shared
+ *  with. Never a credential. */
+export interface WorkspaceConnection {
+  id: string; provider: string; providerName: string; kind: "api_key" | "oauth_app";
+  label: string; accountLabel: string | null;
+  capabilities: string[]; capabilityLabels: string[];
+  status: "active" | "revoked" | "reauth_required";
+  projectShareable: boolean; addedByName: string | null;
+  audience: WorkspaceConnectionAudienceEntry[]; apiHosts: string[]; updatedAt: string;
+}
+export interface WorkspaceConnectionsScopeView {
+  own: WorkspaceConnection[];
+  inherited: WorkspaceConnection[];
+  shareable: WorkspaceConnection[];
+  canShare: boolean;
+}
+/** One picked Google Drive item of a share: a file, or a folder with
+ *  everything inside it. */
+export interface DriveShareItem { id: string; kind: "file" | "folder"; name: string; mimeType: string | null }
+/** A person's own Drive folders and files shared read-only into one scope
+ *  (owner 2026-10-01), read by Ivy there through the sharer's own account.
+ *  `account` is that Google address on the caller's OWN shares only; every
+ *  other row carries null and reads as "<Name>'s Drive". `sharedBy.email`
+ *  (the sharer's sign-in address, not their Google one) rides only while
+ *  the sharer shares the workspace with the viewer, for the label rule's
+ *  fail-safe when they have no name. `standing` says whether it still
+ *  reaches the scope today (the sharer is still in it and their Google
+ *  account still works). */
+export interface DriveShare {
+  id: string; scope: IvyConnectionScope; projectId: string | null; chatId: string | null; scopeName: string | null;
+  provider: string; sharedBy: { id: string; name: string | null; email: string | null }; account: string | null;
+  items: DriveShareItem[];
+  standing: boolean; standingReason: "sharer_left_scope" | "google_disconnected" | null;
+  createdAt: string; canRemove: boolean;
 }
-export interface ProjectIvyConnection {
-  id: string; teamId: string; projectId: string; provider: "github"; installationId: string;
-  accountLogin: string; repositories: string[]; allowWrites: boolean; configuredBy: string | null; updatedAt: string;
+/** An inherited share of a project the caller does not read: the fact that
+ *  a project they are not in shares something here, nothing more. */
+export interface HiddenDriveShare { id: string; provider: string; scope: "project"; hidden: true }
+/** One scope's Drive shares: its own, the ones it inherits, whether the
+ *  caller may share here, and the Google account they would share from. */
+export interface DriveSharesView {
+  own: DriveShare[];
+  inherited: Array<DriveShare | HiddenDriveShare>;
+  mayShare: boolean;
+  google: { grantId: string; account: string | null } | null;
+  /** A page, as IvyConnectionsView: `nextCursor` opens the next one. */
+  nextCursor: string | null;
 }