@agent-compose/sdk 0.8.5 → 0.8.7

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

@@ -30,6 +30,22 @@ export interface Project {
     role: ProjectRole;
     memberCount: number;
     objectCount: number;
+    /** The overview's words and dates (owner 2026-10-05): a short
+     *  description, and the start and target dates as calendar days
+     *  (`YYYY-MM-DD`); null until someone sets them. */
+    description: string | null;
+    startDate: string | null;
+    targetDate: string | null;
+}
+/** What `updateProject` may set: each field absent = untouched, null =
+ *  cleared. `name` and the details need `write`; `visibility` needs a
+ *  project owner or a team admin. */
+export interface ProjectUpdate {
+    name?: string;
+    visibility?: "public" | "private";
+    description?: string | null;
+    startDate?: string | null;
+    targetDate?: string | null;
 }
 /** A page of projects, newest-activity first. Cursor-paginated: pass the
  *  previous page's `next_cursor` (null when exhausted). */
@@ -84,6 +100,15 @@ export interface ProjectObjectsPage {
     objects: ProjectObject[];
     next_cursor: string | null;
 }
+/** How many objects of each kind a project holds for the caller — the
+ *  whole project's counts under the list's own visibility, never a
+ *  page's. `GET /projects/:id/objects/counts`. */
+export interface ProjectObjectCounts {
+    file: number;
+    conversation: number;
+    session: number;
+    folder: number;
+}
 /** One file the caller could NOT contribute to a project when adding a
  *  session — only files the caller OWNS are materialized. `path` is present
  *  only when visible to the caller; paths concealed from the caller are
@@ -129,3 +154,499 @@ export interface RefreshProjectObjectResult {
     objects: ProjectObject[];
     skipped: ProjectSkippedFile[];
 }
+/** A person on a project status row, identity merged server-side. `email`
+ *  rides only while they share the workspace with the viewer: the
+ *  dashboard's label rule (name, else email, else "Teammate") picks. */
+export interface ProjectStatusPerson {
+    id: string;
+    name: string | null;
+    email: string | null;
+    image: string | null;
+    avatarUrl: string | null;
+}
+/** Whom a thread waits on (owner 2026-10-01: status "is multiplayer, could
+ *  be needs Chris or Westan"; it names people). A plan task that waits on a
+ *  person, as the thread agent wrote it (a teammate, or someone outside by
+ *  name), or a worker's question owed an answer, which waits on the person
+ *  who asked for the work (the thread's opening message), else the last
+ *  person to speak on the thread. */
+export interface ProjectStatusWaitingOn {
+    /** The teammate, when known. */
+    person: ProjectStatusPerson | null;
+    /** How the thread names them: the teammate's name, "Dana's IT team", or
+     *  "an answer" when a worker's question has nobody to wait on yet. */
+    who: string;
+    /** What they will do or answer, in the people's terms. */
+    what: string | null;
+    /** `task`: a plan task waiting on a person; `question`: a worker's
+     *  question owed an answer; `answer`: the thread's own question to a
+     *  person (its raise declared whom it waits on), open until one of them
+     *  answers where Ivy spoke. */
+    kind: "task" | "question" | "answer";
+    /** The chat message where the person said it, when the thread agent
+     *  recorded one, or Ivy's message carrying the thread's question: the way
+     *  to the ask. Null otherwise. */
+    messageId: string | null;
+    /** An answer wait's place: the chat thread Ivy spoke in (null for the
+     *  room's top level). Absent on the other kinds. */
+    threadRootId?: string | null;
+    /** When the thread asked (ISO). Absent on the other kinds. */
+    at?: string | null;
+}
+/** Whom a TASK waits on (owner 2026-10-05: a todo may wait on more than one
+ *  person's answer or sign-off): every teammate it names, as people, and
+ *  the words the thread agent (or the person who set it) wrote for whoever
+ *  they are. */
+export interface ThreadStatusWaitingOn {
+    /** The teammates, the one whose act comes first first; empty for a wait
+     *  on someone the workspace cannot name ("Dana's IT team"). */
+    people: ProjectStatusPerson[];
+    /** How the thread names them. */
+    who: string;
+    /** What they will do or answer, in the people's terms; null when a person
+     *  set the wait without saying for what. */
+    what: string | null;
+    /** The chat message where the person said it, when one was recorded. */
+    messageId: string | null;
+}
+/** Who a todo is assigned to (owner 2026-10-05, like an issue's assignee):
+ *  Ivy, or one person. Null on the todo = nobody, after a person took the
+ *  assignee off. */
+export type ThreadStatusAssignee = {
+    kind: "ivy";
+} | ({
+    kind: "person";
+} & ProjectStatusPerson);
+/** One plan task of a thread, as the thread agent's plan view reads it. */
+export interface ProjectStatusTask {
+    id: string;
+    objective: string;
+    status: "open" | "done";
+    dueAt: string | null;
+    overdue: boolean;
+    /** Open and waiting on a task that is not done. */
+    blocked: boolean;
+    criteria: {
+        met: number;
+        total: number;
+    };
+    /** Open and waiting on a person. */
+    waitingOn: ThreadStatusWaitingOn | null;
+    assignee: ThreadStatusAssignee | null;
+}
+/** What a thread's workers are doing, from platform rows: `waiting` a
+ *  worker's question is owed an answer; `working` a worker has a live turn;
+ *  `idle` workers exist and none is running; `done` the thread is closed;
+ *  `none` no worker was started. */
+export type ProjectStatusWorker = "working" | "waiting" | "idle" | "done" | "none";
+/** One outcome thread born in one of the project's chats. */
+export interface ProjectStatusThread {
+    id: string;
+    title: string;
+    state: "open" | "waiting" | "snoozed" | "closed";
+    note: string | null;
+    /** The chat the thread was born in, and whether it is public or private. */
+    conversation: {
+        id: string;
+        title: string | null;
+        access: "public" | "private";
+    };
+    /** The chat message the thread opened on, for a deep link; null if none. */
+    openingMessageId: string | null;
+    /** Who holds the next move: a person while the thread waits on people,
+     *  else Ivy. */
+    owner: {
+        kind: "ivy";
+    } | ({
+        kind: "person";
+    } & ProjectStatusPerson);
+    /** The people who spoke on the thread, most recent first. */
+    people: ProjectStatusPerson[];
+    /** The now line: what its running worker is doing (`worker`), else the
+     *  thread agent's note, its own reading of where things stand (`note`);
+     *  null when there is neither. `at` is when the text was set (ISO). */
+    now: {
+        kind: "worker" | "note";
+        text: string;
+        at: string | null;
+    } | null;
+    /** `running`: how many of its workers have a live turn. `line`: while
+     *  `status` is working, the one-line status its running worker set most
+     *  recently ("Reading the Fly logs") and when (ISO); null otherwise. */
+    worker: {
+        status: ProjectStatusWorker;
+        sessions: number;
+        running: number;
+        line: {
+            text: string;
+            at: string;
+        } | null;
+    };
+    /** Whom the thread waits on, named; empty when it waits on nobody. */
+    waitingOn: ProjectStatusWaitingOn[];
+    /** The next open task deadline, else the thread agent's check-in. */
+    next: {
+        at: string;
+        what: string;
+        kind: "deadline" | "check_in";
+    } | null;
+    progress: {
+        done: number;
+        total: number;
+    };
+    tasks: ProjectStatusTask[];
+    overdue: number;
+    blocked: number;
+    unmetCriteria: number;
+    lastMovementAt: string;
+    closedAt: string | null;
+}
+/** What moved: a task done, a thread opened or closed, a result or decision
+ *  the thread agent raised to the people, a worker's declared result, or a
+ *  person's answer (`by` names them). */
+export type ProjectStatusActivityKind = "task_done" | "thread_closed" | "thread_opened" | "result" | "decision" | "answer";
+export interface ProjectStatusActivity {
+    at: string;
+    kind: ProjectStatusActivityKind;
+    threadId: string;
+    threadTitle: string;
+    text: string;
+    by: ProjectStatusPerson | null;
+}
+/** How many live threads wait on one person (or one named outsider). */
+export interface ProjectStatusWaitingCount {
+    person: ProjectStatusPerson | null;
+    who: string;
+    threads: number;
+}
+/** The header's counts: "3 in progress, waiting on Chris (2) and Westan (1),
+ *  4 done this week". */
+export interface ProjectStatusCounts {
+    /** Live threads (open, waiting or snoozed). */
+    inProgress: number;
+    /** Threads closed in the last seven days. */
+    doneThisWeek: number;
+    waitingOn: ProjectStatusWaitingCount[];
+}
+/** GET /projects/:id/status. `threads` (the live ones) is cursor-paginated
+ *  by last movement; `recentlyClosed` rides the first page only (empty on
+ *  later pages). The project facts (`sources`, `progress`, `dueAt`,
+ *  `nextCheckIn`, `activity`) span every thread the viewer may read, on
+ *  every page. */
+export interface ProjectStatus {
+    project: {
+        id: string;
+        name: string;
+        visibility: "public" | "private";
+        role: ProjectRole;
+    };
+    /** The chats in the project, where its threads are born. */
+    sources: number;
+    progress: {
+        done: number;
+        total: number;
+    };
+    /** The latest deadline of an open task: the project's finish line. */
+    dueAt: string | null;
+    nextCheckIn: {
+        at: string;
+        threadId: string;
+        threadTitle: string;
+        conversationId: string;
+        with: ProjectStatusPerson | null;
+    } | null;
+    counts: ProjectStatusCounts;
+    threads: ProjectStatusThread[];
+    /** Closed in the last seven days. */
+    recentlyClosed: ProjectStatusThread[];
+    activity: ProjectStatusActivity[];
+    generatedAt: string;
+    next_cursor: string | null;
+}
+/** A worker's state as the chat's chips say it: working (a live turn, or
+ *  parked on a question), starting (nothing produced yet), done, failed,
+ *  stopped. */
+export type ThreadStatusWorkerState = "starting" | "working" | "done" | "failed" | "stopped";
+/** The effort a worker was started with; null = the harness's own default. */
+export type ThreadStatusWorkerEffort = "low" | "medium" | "high" | "xhigh" | "max";
+/** What pays for a worker's inference, as its hover card says it (owner
+ *  2026-10-05: a findable detail, never a mark on rows): a person's connected
+ *  plan (the person by id and name only, when the turn named them), platform
+ *  credits, or a connected provider key by its provider family. */
+export type WorkerFunding = {
+    lane: "subscription";
+    owner: {
+        id: string;
+        name: string | null;
+    } | null;
+} | {
+    lane: "platform";
+} | {
+    lane: "byok";
+    provider: string;
+};
+export interface ThreadStatusWorker {
+    /** The worker's session (its page is /conversations/:id). */
+    conversationId: string;
+    title: string | null;
+    state: ThreadStatusWorkerState;
+    /** Its one-line status while working; null otherwise. */
+    line: {
+        text: string;
+        at: string;
+    } | null;
+    startedAt: string;
+    /** When a settled worker last spoke, or its session ended. */
+    finishedAt: string | null;
+    /** The result it declared, when it did. */
+    result: string | null;
+    /** The question it is parked on, while one is owed. */
+    asking: string | null;
+    /** The model stamped at birth (what it was CONFIGURED to run); null =
+     *  the runtime's own default. */
+    model: string | null;
+    /** The models its turns ACTUALLY ran (owner 2026-10-06: "what model
+     *  actually did the work"), each once in first-seen order — a mid-turn
+     *  switch lists both: the harness's own report (its stream; codex's
+     *  rollout file read at the turn's end), then the metering gateway's
+     *  attested record of the model each platform-funded call went to. Never
+     *  derived from `model`: empty when nothing is on record, and the
+     *  surfaces then say the model isn't known. Absent on older servers. */
+    ranModels?: string[];
+    effort: ThreadStatusWorkerEffort | null;
+    /** The harness it runs ("claude-code", "codex", ...); null when unknown. */
+    runtime: string | null;
+    /** Where it runs: a cloud sandbox or the person's machine; null when
+     *  unknown. */
+    executor: "local" | "cloud" | null;
+    /** When its running turn started (ISO); null while no turn runs. */
+    workingSince: string | null;
+    /** When its newest turn ended (ISO): the moment it stopped, while no turn
+     *  runs. Null while a turn runs, and for a worker that has not run one. */
+    lastTurnEndedAt: string | null;
+    /** Its machine has a live desktop to show (the Desktop pill's own
+     *  verdict, for the session's current machine): the chat draws a door to
+     *  it on the step the worker is on. False for a local session, a machine
+     *  with no GUI, or a session no longer on a machine. */
+    desktopCapable: boolean;
+    /** What pays for it, when the record says (see WorkerFunding); null when
+     *  nothing is on record. Absent on older servers. */
+    funding?: WorkerFunding | null;
+}
+/** A message that directed a step: who wrote it and the opening of what
+ *  they said, where it sits (its chat and, for a reply, the root of its
+ *  chat thread; null for the chat's top level) and when. */
+export interface ThreadStatusDirector {
+    messageId: string;
+    conversationId: string;
+    threadRootId: string | null;
+    /** The person who wrote it, as the status wire names people; null for a
+     *  message Ivy wrote. */
+    author: ProjectStatusPerson | null;
+    /** The opening of what they said, in plain words (links read as their
+     *  labels), capped; null when the message shows no words. */
+    excerpt: string | null;
+    /** When it was said (ISO). */
+    at: string;
+}
+/** Something a worker produced, filed under the step it was on: a desktop
+ *  screenshot or a capture pushed with a need (`path`, a drive file), or
+ *  its declared result (`text`, its words). */
+export interface ThreadStatusOutput {
+    id: string;
+    kind: "screenshot" | "capture" | "result";
+    /** When it landed (ISO). */
+    at: string;
+    /** The drive path of a picture; null for words. */
+    path: string | null;
+    /** The words: a result's own, a picture's summary. */
+    text: string;
+}
+/** What a person did on a todo in the chat's todo view (owner 2026-10-05):
+ *  a comment, or an edit of its assignee, details, status or whom it waits
+ *  on. The todo's Activity, with the platform's own history. */
+export interface ThreadStatusTodoActivity {
+    id: string;
+    /** When (ISO). */
+    at: string;
+    kind: "comment" | "assignee" | "description" | "status" | "waiting_on";
+    /** Who did it; null for a person the workspace cannot name. */
+    by: ProjectStatusPerson | null;
+    /** A comment's words, or the details written; null otherwise. */
+    text: string | null;
+    /** The assignee set (`kind` assignee); null for nobody. */
+    assignee: ThreadStatusAssignee | null;
+    /** The status set (`kind` status). */
+    status: "open" | "in_progress" | "waiting" | "done" | null;
+    /** The people set (`kind` waiting_on). */
+    waitingOn: ProjectStatusPerson[];
+}
+/** One step of the thread's plan. */
+export interface ThreadStatusTodo {
+    id: string;
+    objective: string;
+    status: "open" | "done";
+    dueAt: string | null;
+    overdue: boolean;
+    /** Open and waiting on a step that is not done. */
+    blocked: boolean;
+    /** The steps it waits on, by their objective. */
+    blockedOn: string[];
+    /** Open and waiting on people. */
+    waitingOn: ThreadStatusWaitingOn | null;
+    /** Who it is assigned to: Ivy, one person, or nobody (owner 2026-10-05).
+     *  Stored on the server; the plan's default is the first person it waits
+     *  on, else Ivy, and a person's choice stands over the plan's. */
+    assignee: ThreadStatusAssignee | null;
+    /** The details a person wrote on it, plain text with line breaks; null
+     *  when none. */
+    description: string | null;
+    /** What people did on it (edits and comments), oldest first, bounded. */
+    activity: ThreadStatusTodoActivity[];
+    /** Its done criteria, as counts. */
+    criteria: {
+        met: number;
+        total: number;
+    };
+    /** The thread's worker on this step (the thread agent's stamp), or null. */
+    workerConversationId: string | null;
+    /** Done, and completed with this note: what it produced, in one line. */
+    result: string | null;
+    /** When a worker was first put on the step (ISO): its own clock in the
+     *  chat, never a worker's turn. Null until then. */
+    startedAt: string | null;
+    /** Done at this moment (ISO): when its check-off lands in the chat. Null
+     *  while open. */
+    completedAt: string | null;
+    /** The messages that directed the step (the request or follow-up that
+     *  added it, then every steer, from another chat thread too), oldest
+     *  first. Empty = the job's request alone. The step's status shows in the
+     *  chat thread of each. */
+    directedBy: ThreadStatusDirector[];
+    /** What the worker produced for the step, newest first (bounded): its
+     *  screenshots and captures, and its declared result. */
+    outputs: ThreadStatusOutput[];
+}
+/** One of the last things that happened on the thread: a worker's stream
+ *  event (its type), or the thread's record ("said" for a person's words,
+ *  "raised" for what the agent put to the people, "worker_result", ...). */
+export interface ThreadStatusEvent {
+    at: string;
+    kind: string;
+    text: string;
+    by: ProjectStatusPerson | null;
+}
+/** One thread's work, as the card under the message that started it reads
+ *  it: the thread, the root it opened on, the note, its workers and its
+ *  steps. */
+export interface ChatWorkThread {
+    thread: ProjectStatusThread;
+    /** The message the thread opened on, in this chat: the job's request —
+     *  who asked for it, their words, where it sits (the job's started mark
+     *  shows there) and when. Null when the thread opened on no message here
+     *  (the chat shows no card for it, but its workers still count in the
+     *  chat's working status), or the viewer cannot see it. */
+    request: ThreadStatusDirector | null;
+    /** The job's latest place: the newest agent-authored message after the
+     *  request in the request's own chat thread (the thread under a room
+     *  request, or the reply thread the request sits in), else the room's
+     *  newest after it for a room request answered inline. "Jump to latest"
+     *  lands here. Null while nothing has answered; the request is then its
+     *  place. */
+    latestMessageId: string | null;
+    /** The chat thread that latest message sits in (null for the room's top
+     *  level); null with no latest message. */
+    latestThreadRootId: string | null;
+    /** The thread agent's rolling note: where things stand, in its words. */
+    summary: string | null;
+    /** When the thread was opened (ISO): the job's start, the beginning of
+     *  its total time. */
+    openedAt: string;
+    /** Working first, then starting, then what settled (newest first). */
+    workers: ThreadStatusWorker[];
+    /** The plan's steps, in plan order (oldest first). */
+    todos: ThreadStatusTodo[];
+}
+export interface ThreadStatus extends ChatWorkThread {
+    events: ThreadStatusEvent[];
+    generatedAt: string;
+}
+/** GET /conversations/:id/work: the chat's threads, most recently moved
+ *  first and bounded (the server's CHAT_WORK_THREADS), each with its work.
+ *  404 for a chat the viewer cannot read. */
+export interface ChatWork {
+    threads: ChatWorkThread[];
+    /** The project the chat is filed in, as the viewer may see it; null for
+     *  a chat in none. A todo's Properties name it. */
+    project: {
+        id: string;
+        name: string;
+    } | null;
+    generatedAt: string;
+}
+/** PATCH /conversations/:id/todos/:todoId (owner 2026-10-05: "change the
+ *  assignee", "write details in here myself"): what a person who can read
+ *  the chat may change on a todo. Each field is optional; one call may
+ *  carry several. Answers the chat's whole work read (ChatWork), so the
+ *  surfaces redraw from one truth. */
+export interface ChatTodoPatch {
+    /** The one assignee: Ivy, a person who can read the chat, or null for
+     *  nobody. */
+    assignee?: {
+        kind: "ivy";
+    } | {
+        kind: "person";
+        userId: string;
+    } | null;
+    /** The details, plain text with line breaks; null or "" clears. */
+    description?: string | null;
+    /** Where it stands, in the plan's own states: open (not started), in
+     *  progress, waiting (on the people given, or the ones it already waits
+     *  on), done. A done todo stays done. */
+    status?: "open" | "in_progress" | "waiting" | "done";
+    /** Whom it waits on: people who can read the chat (several allowed), and
+     *  for what; [] or null clears the wait. */
+    waitingOn?: {
+        userIds: string[];
+        what?: string | null;
+    } | null;
+}
+/** POST /conversations/:id/todos/:todoId/comments: a comment on the todo,
+ *  which lands in its Activity and reaches the thread's agent. Answers the
+ *  chat's whole work read. */
+export interface ChatTodoComment {
+    text: string;
+}
+export interface MeStatusCounts {
+    waitingOnYou: number;
+    inProgress: number;
+    /** The viewer's projects with a relevant live thread. */
+    projects: number;
+    doneThisWeek: number;
+}
+/** GET /me/status, for the current workspace: the threads relevant to the
+ *  viewer (they posted, were mentioned, asked, have a to-do, or are in the
+ *  chat), never the whole workspace. `threads` is cursor-paginated by last
+ *  movement; `waitingOnYou`, `recentlyClosed` and `activity` ride the first
+ *  page. The client groups by `chatProjects` (the viewer's project for each
+ *  chat; a chat absent there is in none of theirs). */
+export interface MeStatus {
+    counts: MeStatusCounts;
+    /** Live threads a task of which waits on the viewer, or whose worker's
+     *  question is owed and the viewer asked for the work (else spoke last). */
+    waitingOnYou: ProjectStatusThread[];
+    threads: ProjectStatusThread[];
+    recentlyClosed: ProjectStatusThread[];
+    chatProjects: Array<{
+        conversationId: string;
+        project: {
+            id: string;
+            name: string;
+        };
+    }>;
+    activity: Array<ProjectStatusActivity & {
+        conversationId: string | null;
+    }>;
+    generatedAt: string;
+    next_cursor: string | null;
+}

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

@@ -90,6 +90,14 @@ export interface InvokeInlineAndWaitOptions extends InvokeInlineOptions {
 }
 export interface InvokeResult {
     id: string;
+    /** The run is PARKED for its funding plan's reset: the person whose plan
+     *  pays for it has every plan out, so nothing runs until `until`, when it
+     *  starts by itself; `text` is the one line to pass on. Absent for a run
+     *  that boots now. */
+    hold?: {
+        until: string;
+        text: string;
+    };
 }
 export interface StreamRunLogsOptions {
     lastEventId?: number;
@@ -311,6 +319,81 @@ export interface ListRunsOptions {
     sort?: "newest" | "oldest" | "fastest" | "slowest";
     limit?: number;
 }
+/** What started a run (`GET /factories/:slug/workflow-activity*`), read off
+ *  the dispatch stamps: a schedule's tick, a thread's scripted check, the
+ *  chat an agent's turn dispatched it from, the person who invoked it from
+ *  the dashboard, or the API key (the CLI, a script). */
+export type RunStartedBy = {
+    kind: "schedule";
+    name: string | null;
+} | {
+    kind: "check";
+} | {
+    kind: "chat";
+    conversationId: string;
+    title: string | null;
+} | {
+    kind: "person";
+    userId: string;
+    name: string;
+    image: string | null;
+    avatarUrl: string | null;
+} | {
+    kind: "key";
+    name: string;
+} | {
+    kind: "unknown";
+};
+/** One run in a space's workflow activity: the runs list's summary plus
+ *  what started it. */
+export interface WorkflowActivityRun extends RunListEntry {
+    finalSummary: string | null;
+    /** Structured return value from the workflow, when it completed. */
+    output: unknown;
+    startedBy: RunStartedBy;
+}
+/** One stack in a space's workflow activity: a workflow that has run there
+ *  and its latest run. */
+export interface WorkflowActivityHead {
+    workflow: string;
+    latestRun: WorkflowActivityRun;
+}
+export interface ListWorkflowActivityOptions {
+    /** Factory the runs live in. Defaults to "default". */
+    factorySlug?: string;
+    /** Stacks per page (1–50, server default 20). */
+    limit?: number;
+    /** The previous page's `nextCursor`. */
+    cursor?: string;
+    /** A search (at most 100 characters): every run whose workflow name,
+     *  title, failure or summary contains it, without case — reaching past
+     *  the last 90 days the listing shows without one. */
+    q?: string;
+}
+export interface ListWorkflowRunsOptions {
+    /** Factory the runs live in. Defaults to "default". */
+    factorySlug?: string;
+    /** The registered workflow name, exactly. */
+    workflow: string;
+    /** Runs per page (1–50, server default 10). */
+    limit?: number;
+    /** The previous page's `nextCursor`. */
+    cursor?: string;
+    /** A search (at most 100 characters): the workflow's runs whose title,
+     *  failure or summary contains it, without case — reaching past the last
+     *  90 days the listing shows without one. */
+    q?: string;
+}
+export interface WorkflowActivityPage {
+    workflows: WorkflowActivityHead[];
+    hasMore: boolean;
+    nextCursor: string | null;
+}
+export interface WorkflowRunsPage {
+    runs: WorkflowActivityRun[];
+    hasMore: boolean;
+    nextCursor: string | null;
+}
 export interface TimelineEvent {
     kind: string;
     at: string;

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

@@ -32,9 +32,10 @@ export type DocumentCapability = "read" | "write";
  *  regardless of call context — read-only, never act. */
 export type TemplateCapability = "read" | "write" | "invoke" | "see_runs";
 /** One grant on an artifact scope. `team`/`user` are the editable tiers
- *  carried on a PUT (full-replace); `session`/`project` are DERIVED,
- *  read-only arms that appear only on READ payloads (the routes that manage
- *  them own their mutation — a scope PUT rejects them, 400 `invalid_principal`).
+ *  carried on a PUT (full-replace); `session`/`project`/`conversation`/
+ *  `worker` are DERIVED, read-only arms that appear only on READ payloads
+ *  (the routes that manage them own their mutation — a scope PUT rejects
+ *  them, 400 `invalid_principal`).
  *
  *  Session and project grants carry FIXED capabilities `['read','write']`:
  *  the fs-gateway is concealment-only (no read/write dimension at the mount),
@@ -62,6 +63,30 @@ export type ScopeGrant = {
      *  being a project member (share implies unshare). Null only for
      *  transitional/legacy rows. */
     projectObjectId: string | null;
+    /** The people in the project: the row's reach. */
+    memberCount: number;
+    capabilities: string[];
+}
+/** A chat's grant (scope-at-birth, documents): reach derives LIVE from the
+ *  chat's tier and member rows. `memberCount` is null for a public channel,
+ *  whose audience is the whole team rather than its member rows. */
+ | {
+    principal: "conversation";
+    conversationId: string;
+    conversationTitle: string | null;
+    memberCount: number | null;
+    capabilities: string[];
+}
+/** The grant a chat's WORKER session holds on what it wrote: not a group
+ *  of people. The readers of the chat it works for (`chatId`) reach the
+ *  file through it while the worker's project boundary holds. `title` is
+ *  the work's (the session's) title. */
+ | {
+    principal: "worker";
+    conversationId: string;
+    title: string | null;
+    chatId: string;
+    chatTitle: string | null;
     capabilities: string[];
 };
 /** An artifact's share scope (documents and templates — one model).
@@ -74,6 +99,10 @@ export interface ArtifactScope {
     /** Templates only — the owning conversation binding (a grant source:
      *  members of that conversation reach the template via their role). */
     conversationId?: string | null;
+    /** Documents only — born of a shared chat's work (Ivy's publish, a
+     *  worker's output for a chat). Such a document is shared by the people
+     *  who can edit it, whoever its owner is; so is one with no owner. */
+    bornOfChatWork?: boolean;
     grants: ScopeGrant[];
 }
 /** The call context stamped on a run at dispatch (ADR-0045 §3) — the