@agent-compose/sdk 0.8.5 → 0.8.7

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

@@ -8,6 +8,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";
 /** A human member of your team — the people an agent (or you) can @-flag. */
@@ -43,6 +44,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;
@@ -87,10 +91,35 @@ export interface ConversationRow {
         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`
  *  on message rows and stream payloads): rows authored by a user's agent
@@ -105,6 +134,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 {
     id: string;
@@ -130,6 +162,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;
@@ -379,6 +416,44 @@ 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
  *  the UI lists; the security boundary is the member-gated proxy + the
@@ -403,12 +478,23 @@ 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`. */
 export interface OpenPreviewInput {
@@ -443,6 +529,139 @@ export interface BackgroundWorkChildDecl {
     journalPath?: string;
     label?: string;
 }
+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;
+} | {
+    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
@@ -576,6 +795,38 @@ export interface SessionChangeSet {
      *  pages serve an empty array. */
     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. */
@@ -889,6 +1140,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
  *  snapshot + the roster TTL. The attach roster itself is NOT returned —
@@ -909,10 +1163,37 @@ 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 {
@@ -930,22 +1211,14 @@ 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;
 }
 /** 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;
-}
 /** 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
@@ -1029,9 +1302,12 @@ export interface StreamConversationOptions {
     lastEventId?: number;
     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[];
@@ -1046,26 +1322,163 @@ export interface ChannelIvyState {
     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;
-    }>;
 }
-export interface ProjectIvyConnection {
+/** 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;
-    projectId: 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;
+}
+/** 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;
+}