@agent-compose/sdk 0.8.5 → 0.8.7

package/src/agent/perf-sampler.ts

@@ -47,8 +47,32 @@ export const PERF_PROBE_WINDOW_SECONDS = 2;
 /** The standalone probe's output line leads with this prefix. */
 export const PERF_PROBE_LINE_PREFIX = "perf ";
 
-/** Longest token the parsers accept — anything bigger is garbage. */
-export const PERF_TOKEN_MAX_CHARS = 200;
+/** Longest token the parsers accept — anything bigger is garbage. The
+ *  `top` field (three process names of up to 20 chars with their RSS) is
+ *  what moved this up from 200. */
+export const PERF_TOKEN_MAX_CHARS = 320;
+
+/** THE TOP PROCESSES BY RESIDENT MEMORY ("why was it at 99%?", the
+ *  2026-10-03 flight incident: a 4 vCPU / 8 GB machine sat at 99% memory
+ *  for twelve minutes and nothing recorded what held it): at most this many
+ *  entries ride the token, name and resident MB each. A machine fact, read
+ *  by the same /proc burst; never a judgment. */
+export const PERF_TOP_PROCESSES = 3;
+/** A process name as the token carries it: `comm`, sanitized on the guest
+ *  to this alphabet and length, so it can ride a comma-separated token. */
+export const PERF_TOP_NAME_MAX = 20;
+const TOP_NAME_RE = /^[A-Za-z0-9._-]{1,20}$/;
+/** A process resident set the clamp believes, in MB (a 64 GB machine is
+ *  past every sandbox we run). */
+const TOP_RSS_MAX_MB = 65_536;
+
+/** One process by resident memory. */
+export interface GuestTopProcess {
+  /** Its `comm` (the executable's short name), sanitized. */
+  name: string;
+  /** Resident set in MB, whole. */
+  rssMb: number;
+}
 
 /** One clamped guest perf sample. Null fields = unreadable/absent on the
  *  guest — never zero-filled (a zero is a claim; null is honesty). */
@@ -67,6 +91,9 @@ export interface GuestPerfSample {
   ramMb: number | null;
   /** Guest clock at sample time, epoch seconds. Dedupe only. */
   sampledAtS: number | null;
+  /** The processes holding the most memory, biggest first (`top`); null
+   *  when the guest did not report them (an older image, no `ps`). */
+  topProcesses: GuestTopProcess[] | null;
 }
 
 export interface PerfSamplerPaths {
@@ -113,7 +140,13 @@ function perfReadFunctionFragment(procRoot: string, diskPath: string): string {
     + `if [ "\${ac_pmt:-0}" -gt 0 ] && [ -n "\${ac_pma:-}" ]; then ac_pmem=$(( 100 * (ac_pmt - ac_pma) / ac_pmt )); fi; `
     + `[ "$ac_pmem" -gt 100 ] && ac_pmem=100; [ "$ac_pmem" -lt -1 ] && ac_pmem=-1; `
     + `ac_pdsk=$(df -kP ${disk} 2>/dev/null | awk 'NR==2 && $2>0 {print int(100*$3/$2)}'); `
-    + `ac_tok="v=1,cpu=$ac_pcpu,l1=\${ac_pl1:--1},mem=$ac_pmem,dsk=\${ac_pdsk:--1},vc=\${ac_pvc:-0},ram=$(( \${ac_pmt:-0} / 1024 )),ts=$(date +%s)"; `
+    // The top processes by resident memory (the "why 99%?" fact): three
+    // `comm` names with their RSS in MB, each name sanitized to the token's
+    // alphabet, `;`-joined so the field stays one comma-free word. A guest
+    // whose `ps` lacks `--sort` (not procps) prints nothing and the field is
+    // absent — the parser reads that as "not reported", never as zero.
+    + `ac_ptop=$(ps -eo rss=,comm= --sort=-rss 2>/dev/null | head -${PERF_TOP_PROCESSES} | awk '{ n=$2; gsub(/[^A-Za-z0-9._-]/, "_", n); if (length(n) > ${PERF_TOP_NAME_MAX}) n=substr(n, 1, ${PERF_TOP_NAME_MAX}); if (n == "") n="_"; printf "%s%s:%d", (NR > 1 ? ";" : ""), n, int($1 / 1024) }' 2>/dev/null); `
+    + `ac_tok="v=1,cpu=$ac_pcpu,l1=\${ac_pl1:--1},mem=$ac_pmem,dsk=\${ac_pdsk:--1},vc=\${ac_pvc:-0},ram=$(( \${ac_pmt:-0} / 1024 )),ts=$(date +%s)\${ac_ptop:+,top=$ac_ptop}"; `
     + `}; `;
 }
 
@@ -184,12 +217,30 @@ export function parsePerfToken(token: string): GuestPerfSample | null {
     ramMb: bounded("ram", 1, 16 * 1024 * 1024),
     // Bounded to [2020, 2100) in epoch seconds — dedupe-grade only.
     sampledAtS: bounded("ts", 1_577_836_800, 4_102_444_800),
+    topProcesses: parseTopProcesses(kv.get("top")),
   };
   if (sample.cpuBusyPct === null && sample.load1 === null
     && sample.memUsedPct === null && sample.diskUsedPct === null) return null;
   return sample;
 }
 
+/** The `top` field, clamped entry by entry: a name outside the alphabet or
+ *  an RSS outside [0, 64 GB] drops THAT entry; more than the cap is cut;
+ *  an absent or empty field is null (not reported). */
+export function parseTopProcesses(raw: string | undefined): GuestTopProcess[] | null {
+  if (raw === undefined || raw.length === 0) return null;
+  const out: GuestTopProcess[] = [];
+  for (const entry of raw.split(";").slice(0, PERF_TOP_PROCESSES)) {
+    const i = entry.lastIndexOf(":");
+    if (i <= 0) continue;
+    const name = entry.slice(0, i);
+    const rssMb = Number(entry.slice(i + 1));
+    if (!TOP_NAME_RE.test(name) || !Number.isInteger(rssMb) || rssMb < 0 || rssMb > TOP_RSS_MAX_MB) continue;
+    out.push({ name, rssMb });
+  }
+  return out.length > 0 ? out : null;
+}
+
 /** Parse the standalone probe's stdout (the LAST `perf ` line wins — envd
  *  occasionally prepends shell noise). */
 export function parsePerfProbeOutput(stdout: string): GuestPerfSample | null {

package/src/agent/run-agent.ts

@@ -1,6 +1,6 @@
 /**
  * agent — canonical entry point for embedding an LLM agent inside a
- * workflow. The workflow's `run()` body calls it; the loop executes
+ * workflow. A step's `run()` body calls it; the loop executes
  * against the runner's own VM.
  *
  * Glue packaged so workflows don't duplicate it:

package/src/client.ts

@@ -1,4 +1,4 @@
-import type { ConversationRow, CreateChatInput, ChannelIvyState, ProjectIvyConnection } from "./types/api-conversations.js";
+import type { ConversationRow, CreateChatInput, ChannelIvyState, DriveSharesView, IvyConnectionsView, ListingPage } from "./types/api-conversations.js";
 /**
  * AgentComposeClient — HTTP client for the agent-compose server API.
  *
@@ -25,6 +25,7 @@ import type {
   RequestAgentPauseOptions, RequestAgentPauseResponse,
   SendAgentMessageOptions, SendAgentMessageResponse,
   RunDetail, RunListEntry, ListRunsOptions, TimelineEvent, RunFundingResponse, RunStepUsageResponse, EventRow, ReportEventInput,
+  ListWorkflowActivityOptions, ListWorkflowRunsOptions, WorkflowActivityPage, WorkflowRunsPage, WorkflowActivityHead, WorkflowActivityRun,
   ListEventsOptions, ListEventsResult, RunArtifactRow, RunLogLine, ListRunLogsOptions,
   CancelRunResponse, ListSnapshotsOptions, SnapshotListResponse, SnapshotListEntry, RunSnapshotEntry,
 } from "./types/api-runs.js";
@@ -34,11 +35,12 @@ import type {
   CreateCloudSessionInput, CloudSessionCreated,
   SessionPreview, PreviewOpened, OpenPreviewInput, SessionForked, BackgroundWorkHeld,
   BackgroundWorkChildDecl, BackgroundWorkStatus, MachineUpsizeOutcome,
-  SessionChangeSet, SessionMergeGated, SessionMergeReport, SessionDiscardReport,
+  CreateSessionWaitInput, SessionWait, SessionWaitCreated, SessionWaitList,
+  SessionChangeSet, SessionFilePlane, SessionMergeGated, SessionMergeReport, SessionDiscardReport,
   SessionChangePreflight, SessionRebaseReport,
   ReviewSuggestionInput, ReviewNotesPublished, ReviewGitCredential,
   SendConversationMessageInput, SendConversationMessageResult,
-  ChannelSessionRow, ChannelSessionsResponse, SessionChannelMessagePosted,
+  ChannelSessionRow, ChannelSessionsResponse,
   SessionDirectMessageSent, BranchClaimGranted, BranchClaimsReleased, BranchClaimState,
   ConversationPresenceSnapshot, StreamConversationOptions, AgentListRow,
   SessionPerfHistoryPage,
@@ -48,9 +50,9 @@ import type {
   SetScopeGrantsInput, SetTemplateScopeInput,
 } from "./types/api-scopes.js";
 import type {
-  Project, ProjectsPage, ProjectRole, ProjectMember,
-  ProjectObjectsPage, ProjectAddPreview,
-  AddProjectObjectInput, AddProjectObjectResult, RefreshProjectObjectResult,
+  Project, ProjectUpdate, ProjectsPage, ProjectRole, ProjectMember,
+  ProjectObject, ProjectObjectsPage, ProjectObjectCounts, ProjectAddPreview,
+  AddProjectObjectInput, AddProjectObjectResult, RefreshProjectObjectResult, ProjectStatus, ThreadStatus, MeStatus,
 } from "./types/api-projects.js";
 import type {
   RegisterResult, RegisterWorkflowInput, TemplateRow, TemplateDetail, ListTemplatesOptions,
@@ -58,7 +60,7 @@ import type {
   FactoryFileListRow, ListFactoryFilesOptions, FactoryFileListPage, FactoryFileConflict, FactoryFileConflictList, ProjectSecretMeta, ProjectSecretList,
   FactoryRow, CreateFactoryInput, UpdateFactoryInput, FactoryPerfSummary,
   ScheduleRow, CreateScheduleInput,
-  SecretOptions, SetSecretResult, SecretListEntry, SessionSecretEntry, SessionSecretInput, SessionSecretRequestCreated, SessionSecretRequestStatus, SessionSecretRequestSummary, VaultRequestKind, VaultCatalogEntry,
+  SecretOptions, SetSecretResult, SecretListEntry, SessionSecretEntry, SessionSecretInput, SessionSecretRequestCreated, SessionSecretRequestStatus, SessionSecretRequestSummary, VaultRequestKind, VaultKeyShape, VaultCatalogEntry, RequestedVaultEntry, VaultCardHint,
   CreateApiKeyInput, ApiKey, ApiKeyCreated, ListApiKeysOptions, ApiKeyPage, UsageResponse,
   DriveRepoLink, CreateDriveRepoLinkInput, CreateNativeRepoInput, CreateNativeRepoResult,
   DriveMountSession, CreateDriveMountSessionInput,
@@ -80,6 +82,8 @@ export type {
   ResumePauseOptions, RequestAgentPauseOptions, AnswerSteerOptions, RequestAgentPauseResponse,
   SendAgentMessageOptions, SendAgentMessageResponse,
   RunDetail, RunListEntry, ListRunsOptions, TimelineEvent,
+  RunStartedBy, WorkflowActivityRun, WorkflowActivityHead, ListWorkflowActivityOptions, ListWorkflowRunsOptions,
+  WorkflowActivityPage, WorkflowRunsPage,
   FundingLane, RunFundingStamp, RunFundingUsageRow, RunFundingResponse,
   RunStepUsage, RunStepUsageResponse,
   EventSubjectType, EventRow, RunArtifactRow, ReportEventInput, ListEventsOptions, ListEventsResult,
@@ -88,20 +92,25 @@ export type {
 } from "./types/api-runs.js";
 export type {
   TeamMember, Mention, CreateMentionsInput,
-  CreateChatInput, ChannelIvyState, ProjectIvyConnection,
-  ConversationMessagePart, ConversationRow, ConversationMessageRow,
+  CreateChatInput, ChannelIvyState, IvyConnection, HiddenIvyConnection, IvyConnectionsView, IvyConnectionScope, ListingPage,
+  DriveShareItem, DriveShare, HiddenDriveShare, DriveSharesView,
+  WorkspaceConnection, WorkspaceConnectionAudienceEntry, WorkspaceConnectionsScopeView,
+  ConversationMessagePart, ConversationRow, ConversationProject, ConversationMessageRow,
   ConversationsPage, SessionsPage, ConversationDetail,
   CreateCloudSessionInput, CloudSessionCreated, ConversationThread,
+  ConversationUnreadSummary, ConversationUnreadThreads, ConversationReadInput, ConversationReadResult,
   SessionPreview, PreviewOpened, OpenPreviewInput, SessionForked, BackgroundWorkHeld,
   BackgroundWorkChildDecl, BackgroundWorkStatus, MachineUpsizeOutcome,
+  SessionWaitKind, SessionWaitState, CreateSessionWaitInput, SessionWait, SessionWaitCheck, SessionWaitCheckResult, SessionWaitCheckReview, SessionWaitCreated, SessionWaitList,
   SessionFileChange, SessionChangeSet, SessionChangeStats, SessionDiffReviewBound, ReviewSuggestion,
+  SessionFileHold, SessionFilePlane,
   ReviewSuggestionInput, ReviewNotesPublished, ReviewGitCredential, SessionReviewDocument,
   ReviewSuggestionDecision, ReviewSuggestionDecisions,
   SessionMergeReportDetail, SessionMergeReport, SessionMergeGated, SessionDiscardReport,
   SessionPreflightFileRow, SessionChangePreflight, SessionRebaseReport,
   ConversationPageContext, SendConversationMessageInput, ConversationTurnState,
   SendConversationMessageResult, UnnotifiedMention, ConversationPresenceSnapshot, AgentListRow, StreamConversationOptions,
-  ChannelSessionStatus, ChannelSessionRow, ChannelSessionsResponse, SessionChannelMessagePosted,
+  ChannelSessionStatus, ChannelSessionRow, ChannelWorkerFacts, ChannelSessionsResponse,
   SessionDirectMessageSent, BranchClaimInfo, BranchClaimGranted, BranchClaimsReleased, BranchClaimState,
   SessionPerfBucket, SessionPerfHistoryPage,
 } from "./types/api-conversations.js";
@@ -111,10 +120,15 @@ export type {
   RunContext, SetScopeGrantsInput, SetTemplateScopeInput,
 } from "./types/api-scopes.js";
 export type {
-  Project, ProjectsPage, ProjectRole, ProjectMember,
-  ProjectObject, ProjectObjectsPage, ProjectSkippedFile, ProjectPreviewFile,
+  Project, ProjectUpdate, ProjectsPage, ProjectRole, ProjectMember,
+  ProjectObject, ProjectObjectsPage, ProjectObjectCounts, ProjectSkippedFile, ProjectPreviewFile,
   ProjectAddPreview, AddProjectObjectInput, AddProjectObjectResult,
   RefreshProjectObjectResult,
+  ProjectStatus, ProjectStatusThread, ProjectStatusTask, ProjectStatusPerson, ProjectStatusWorker, ProjectStatusActivity,
+  ProjectStatusActivityKind, ProjectStatusWaitingOn, ProjectStatusWaitingCount, ProjectStatusCounts,
+  ThreadStatus, ThreadStatusWorker, ThreadStatusWorkerState, ThreadStatusWorkerEffort, WorkerFunding, ThreadStatusTodo, ThreadStatusDirector, ThreadStatusOutput, ThreadStatusEvent, ChatWork, ChatWorkThread,
+  ThreadStatusWaitingOn, ThreadStatusAssignee, ThreadStatusTodoActivity, ChatTodoPatch, ChatTodoComment,
+  MeStatus, MeStatusCounts,
 } from "./types/api-projects.js";
 export type {
   RegisterResult, RegisteredRuntime, RuntimeSourceInput, TemplateSourceRef, RegisterWorkflowInput,
@@ -124,7 +138,7 @@ export type {
   PublicFileLinkState,
   FactoryRow, CreateFactoryInput, UpdateFactoryInput, FactoryPerfSummary,
   ScheduleRow, CreateScheduleInput,
-  SecretOptions, SetSecretResult, SecretListEntry, SessionSecretEntry, SessionSecretInput, SessionSecretRequestCreated, SessionSecretRequestStatus, SessionSecretRequestSummary, VaultRequestKind, VaultCatalogEntry,
+  SecretOptions, SetSecretResult, SecretListEntry, SessionSecretEntry, SessionSecretInput, SessionSecretRequestCreated, SessionSecretRequestStatus, SessionSecretRequestSummary, VaultRequestKind, VaultKeyShape, VaultCatalogEntry, RequestedVaultEntry, VaultCardHint,
   CreateApiKeyInput, ApiKey, ApiKeyCreated, ListApiKeysOptions, ApiKeyPage,
   UsageRollupRow, UsageResponse,
   DriveRepoLink, CreateDriveRepoLinkInput, CreateNativeRepoInput, CreateNativeRepoResult,
@@ -157,6 +171,16 @@ function detectAmbientParentRunId(): string | null {
  *  URL-encoded as defense-in-depth: today's server-side patterns
  *  (`^[a-z][a-z0-9-]*$`) can't produce reserved characters, but a future
  *  relaxation would otherwise quietly become an injection vector. */
+/** The query string of one page of a scope listing (`cursor`: the previous
+ *  page's `nextCursor`; `limit`: 1..200). Empty for the first page at the
+ *  server's size. */
+function listingPageQuery(page: ListingPage = {}): string {
+  const q = new URLSearchParams();
+  if (page.cursor) q.set("cursor", page.cursor);
+  if (page.limit !== undefined) q.set("limit", String(page.limit));
+  return q.toString() ? `?${q}` : "";
+}
+
 function templatePath(factorySlug: string, ...rest: string[]): string {
   const tail = rest.length > 0
     ? "/" + rest.map(encodeURIComponent).join("/")
@@ -660,6 +684,38 @@ export class AgentComposeClient {
     return body.workflows;
   }
 
+  /** A space's workflow activity: one stack per workflow of the space's own
+   *  that has run there in the last 90 days — or, with `q`, that has a run
+   *  matching the search, however old — the most recently run first, each
+   *  with its latest (matching) run and what started it. The platform's
+   *  default workflows (dynamic-task, repo-ingest, …) are left out, the
+   *  search included. Paged by `cursor`. */
+  async listWorkflowActivity(opts: ListWorkflowActivityOptions = {}): Promise<WorkflowActivityPage> {
+    const q = new URLSearchParams();
+    if (opts.limit !== undefined) q.set("limit", String(opts.limit));
+    if (opts.cursor) q.set("cursor", opts.cursor);
+    if (opts.q) q.set("q", opts.q);
+    const slug = encodeURIComponent(opts.factorySlug ?? "default");
+    const body = await this.fetch<{ workflows: WorkflowActivityHead[]; has_more: boolean; next_cursor: string | null }>(
+      `/api/v1/factories/${slug}/workflow-activity${q.toString() ? `?${q}` : ""}`);
+    return { workflows: body.workflows, hasMore: body.has_more, nextCursor: body.next_cursor };
+  }
+
+  /** One workflow's runs in a space, newest first, by its exact registered
+   *  name (`listRuns`' `workflow` is a substring match): the last 90 days,
+   *  or with `q` every run matching the search; a platform default's name
+   *  answers with no runs. Paged by `cursor`. */
+  async listWorkflowRuns(opts: ListWorkflowRunsOptions): Promise<WorkflowRunsPage> {
+    const q = new URLSearchParams({ workflow: opts.workflow });
+    if (opts.limit !== undefined) q.set("limit", String(opts.limit));
+    if (opts.cursor) q.set("cursor", opts.cursor);
+    if (opts.q) q.set("q", opts.q);
+    const slug = encodeURIComponent(opts.factorySlug ?? "default");
+    const body = await this.fetch<{ runs: WorkflowActivityRun[]; has_more: boolean; next_cursor: string | null }>(
+      `/api/v1/factories/${slug}/workflow-activity/runs?${q}`);
+    return { runs: body.runs, hasMore: body.has_more, nextCursor: body.next_cursor };
+  }
+
   /** Ordered lifecycle timeline for one run. */
   async getRunTimeline(runId: string, opts?: { limit?: number; offset?: number }): Promise<TimelineEvent[]> {
     const q = new URLSearchParams();
@@ -867,7 +923,7 @@ export class AgentComposeClient {
   // ── User drive mounts ──────────────────────────────────────────────────────
   // `agentc files mount` on a human's own machine: the server forks a user
   // branch, backs it with a mount session (the review surface), and mints a
-  // user-principal gateway token. Human-held credentials only (sign-in
+  // user-principal gateway token. Own-device credentials only (sign-in
   // cookie or a device-flow bridge key) — sandbox session keys are refused.
 
   /** Create a local drive mount (or re-mint an existing one's token by
@@ -922,8 +978,18 @@ export class AgentComposeClient {
   getChannelIvy(id: string): Promise<ChannelIvyState> {
     return this.fetch(`/api/v1/conversations/${encodeURIComponent(id)}/ivy`);
   }
-  listProjectIvyConnections(id: string): Promise<{ connections: ProjectIvyConnection[]; canManage: boolean }> {
-    return this.fetch(`/api/v1/projects/${encodeURIComponent(id)}/ivy-connections`);
+  /** A project's GitHub grants: its own, and the workspace's it inherits,
+   *  one page at a time (pass the previous page's `nextCursor`). A
+   *  project's access is its members' (and the workspace admins'): a
+   *  member of the workspace who can see a public project without being in
+   *  it gets a 403 `project_member_required`. */
+  listProjectIvyConnections(id: string, page?: ListingPage): Promise<IvyConnectionsView> {
+    return this.fetch(`/api/v1/projects/${encodeURIComponent(id)}/ivy-connections${listingPageQuery(page)}`);
+  }
+  /** A project's Drive shares: its own, and the workspace's it inherits,
+   *  one page at a time. Members only, as listProjectIvyConnections. */
+  listProjectDriveShares(id: string, page?: ListingPage): Promise<DriveSharesView> {
+    return this.fetch(`/api/v1/projects/${encodeURIComponent(id)}/drive-shares${listingPageQuery(page)}`);
   }
 
   /** List conversations the caller can access, newest-activity first.
@@ -1053,25 +1119,6 @@ export class AgentComposeClient {
     );
   }
 
-  /** Post one message into a channel AS the calling session (ADR-0057 Seam
-   *  4) — progress, results, questions, attributed to the session (title +
-   *  runtime mark). Session toolbelt credential ONLY (the calling session
-   *  resolves from the key server-side — 403 `session_credential_required`
-   *  otherwise); the session must be attached (409 `not_attached`). By
-   *  default the post lands in the thread of the message that last
-   *  addressed the session from that channel (the room when none);
-   *  `threadRootId` overrides it — must be a root message in the channel
-   *  (400 `invalid_thread_root`). The post never triggers any turn. */
-  postSessionChannelMessage(
-    channelId: string,
-    input: { text: string; threadRootId?: string },
-  ): Promise<SessionChannelMessagePosted> {
-    return this.fetch<SessionChannelMessagePosted>(
-      `/api/v1/conversations/${encodeURIComponent(channelId)}/session-messages`,
-      { method: "POST", body: { text: input.text, ...(input.threadRootId ? { threadRootId: input.threadRootId } : {}) } },
-    );
-  }
-
   /** Message ANOTHER session's conversation AS the calling session
    *  (`agentc session message @alias`). Session toolbelt credential ONLY —
    *  the sender resolves from the key. `target` is an @alias (team-scoped)
@@ -1178,6 +1225,32 @@ export class AgentComposeClient {
     );
   }
 
+  // ── Session waits (owner ruling 2026-09-23: no watch runs inside a session
+  // sandbox). The session declares what it waits for and ends its turn; the
+  // platform senses the arrival and wakes it. Own-session key posture. ─────
+
+  /** Declare one wait (`agentc wait`): `POST /sessions/:id/waits`. */
+  createSessionWait(conversationId: string, input: CreateSessionWaitInput): Promise<SessionWaitCreated> {
+    return this.fetch<SessionWaitCreated>(
+      `/api/v1/sessions/${encodeURIComponent(conversationId)}/waits`,
+      { method: "POST", body: input },
+    );
+  }
+
+  /** This session's waits, newest first; open only unless `all`. */
+  listSessionWaits(conversationId: string, opts: { all?: boolean } = {}): Promise<SessionWaitList> {
+    const q = opts.all ? "?all=1" : "";
+    return this.fetch<SessionWaitList>(`/api/v1/sessions/${encodeURIComponent(conversationId)}/waits${q}`);
+  }
+
+  /** Cancel an open wait (`agentc wait cancel`): open -> cancelled. */
+  cancelSessionWait(conversationId: string, waitId: string): Promise<SessionWait> {
+    return this.fetch<SessionWait>(
+      `/api/v1/sessions/${encodeURIComponent(conversationId)}/waits/${encodeURIComponent(waitId)}`,
+      { method: "DELETE" },
+    );
+  }
+
   /** Request ONE machine size up for a cloud session (task #110 — the
    *  auto-resize policy's agent door). The platform arbitrates: within the
    *  team's daily cap the upsize is auto-granted (and executes the moment
@@ -1277,17 +1350,30 @@ export class AgentComposeClient {
     return new Uint8Array(buf);
   }
 
+  /** Where ONE path's current version lives for a session
+   *  (`GET /conversations/:id/changes/file`): `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. The
+   *  answer a `file:<path>?session=<id>` link resolves when it is opened.
+   *  404 = missing path or no access (uniform, no existence oracle). */
+  getSessionFilePlane(conversationId: string, path: string): Promise<SessionFilePlane> {
+    const q = new URLSearchParams({ path });
+    return this.fetch<SessionFilePlane>(
+      `/api/v1/conversations/${encodeURIComponent(conversationId)}/changes/file?${q}`,
+    );
+  }
+
   /** Publish a diff review's WHOLE document — prose notes plus structured
    *  suggestions, FULL REPLACE on every call (`POST
    *  /conversations/:id/review-notes`; `agentc review publish`). Callable
-   *  ONLY with the bound review session's own toolbelt credential — any
-   *  other key (another session, a human cookie, a plain API key) refuses
-   *  403. `conversationId` is the REVIEWED session's conversation (in a
-   *  review sandbox: `AGENT_COMPOSE_REVIEW_OF_CONVERSATION_ID`).
+   *  ONLY with the toolbelt credential of a review session spawned for this
+   *  diff, which replaces its own document — any other key (another
+   *  session, a human cookie, a plain API key) refuses 403.
+   *  `conversationId` is the REVIEWED session's conversation (in a review
+   *  sandbox: `AGENT_COMPOSE_REVIEW_OF_CONVERSATION_ID`).
    *
-   *  Failures: 403 `session_credential_required` | `not_review_session` |
-   *  `review_superseded` (a newer review replaced this one); 400
-   *  `suggestion_path_not_in_change_set` (naming the offenders); 409
+   *  Failures: 403 `session_credential_required` | `not_review_session`;
+   *  400 `suggestion_path_not_in_change_set` (naming the offenders); 409
    *  `review_disabled`. */
   publishReviewNotes(
     conversationId: string,
@@ -1323,22 +1409,6 @@ export class AgentComposeClient {
     );
   }
 
-  /** Mint ONE fresh short-lived WIP-push credential for the CALLING
-   *  session's git namespace (`POST /sessions/self/wip-git-credential`,
-   *  git-door slice 2) — the server half of `agentc repos clone` and its
-   *  git credential helper. The token's Push grant is exactly
-   *  `refs/sessions/<sessionId>/`; the door refuses everything else.
-   *  Callable only with a session's own toolbelt credential.
-   *
-   *  Failures: 403 `session_credential_required` | `not_a_session`;
-   *  409 `git_remote_unavailable` (unbranched / legacy plane / fsgw off). */
-  getSessionWipGitCredential(): Promise<ReviewGitCredential & { pushNamespace: string }> {
-    return this.fetch<ReviewGitCredential & { pushNamespace: string }>(
-      "/api/v1/sessions/self/wip-git-credential",
-      { method: "POST" },
-    );
-  }
-
   /** Mint a short-lived native-git credential for a linked repo's MIRROR
    *  namespace (`POST /:slug/repo-links/:id/git-credential`, git-door
    *  slice 4). mode "fetch" (default) reads the mirror — gated on link
@@ -1485,8 +1555,10 @@ export class AgentComposeClient {
     return body.members;
   }
 
-  /** Remove a member (conversation `owner` or team admin only).
-   *  Throws 400 `last_owner` when the target is the roster's last owner. */
+  /** Remove a member (conversation `owner` or team admin), or leave the
+   *  chat yourself: `userId` "me" (or your own id) is the self-leave door.
+   *  Throws 400 `last_owner` when the target is the roster's last owner and
+   *  400 `creator_cannot_leave` when the chat's creator tries to leave it. */
   async removeConversationMember(conversationId: string, userId: string): Promise<ConversationMember[]> {
     const body = await this.fetch<{ members: ConversationMember[] }>(
       `/api/v1/conversations/${encodeURIComponent(conversationId)}/members/${encodeURIComponent(userId)}`,
@@ -1838,9 +1910,16 @@ export class AgentComposeClient {
 
   /** Rename a project (requires `write` role). */
   async renameProject(id: string, name: string): Promise<Project> {
+    return this.updateProject(id, { name });
+  }
+
+  /** Change a project's name, tier, description or dates (one PATCH; see
+   *  ProjectUpdate for who may set what). 400 `date_order` when the target
+   *  date would come before the start date. */
+  async updateProject(id: string, patch: ProjectUpdate): Promise<Project> {
     const body = await this.fetch<{ project: Project }>(
       `/api/v1/projects/${encodeURIComponent(id)}`,
-      { method: "PATCH", body: { name } },
+      { method: "PATCH", body: patch },
     );
     return body.project;
   }
@@ -1874,7 +1953,11 @@ export class AgentComposeClient {
     return body.members;
   }
 
-  /** Remove a member — project owner/team admin, or self-leave. Throws 400
+  /** Remove a member — project owner/team admin, or self-leave (`me`).
+   *  Leaving a project takes its chats with it: the person loses their row
+   *  in every chat filed in the project, public and private, except a chat
+   *  they reach through another project they remain in, the home room, a
+   *  chat they created, and a chat they are the last owner of. Throws 400
    *  `last_owner` when the target is the roster's last owner. */
   async removeProjectMember(id: string, userId: string): Promise<ProjectMember[]> {
     const body = await this.fetch<{ members: ProjectMember[] }>(
@@ -1884,6 +1967,14 @@ export class AgentComposeClient {
     return body.members;
   }
 
+  /** What leaving the project would take from the caller: the chats they
+   *  lose with it, and the project's shared files and folders. */
+  async leaveProjectPreview(id: string): Promise<{ chats: number; files: number }> {
+    return this.fetch<{ chats: number; files: number }>(
+      `/api/v1/projects/${encodeURIComponent(id)}/leave-preview`,
+    );
+  }
+
   /** Change a member's role (project owner or team admin). Throws 400
    *  `last_owner` when demoting the roster's last owner. */
   async setProjectMemberRole(
@@ -1898,15 +1989,56 @@ export class AgentComposeClient {
     return body.members;
   }
 
-  /** List a project's objects (member only), newest first. Cursor-paginated. */
-  listProjectObjects(id: string, opts?: { cursor?: string }): Promise<ProjectObjectsPage> {
+  /** List a project's objects (member only), newest first. Cursor-paginated.
+   *  `type` narrows to one object kind at the server, under the same
+   *  cursor — `"conversation"` is a project's chats alone, however many
+   *  files it holds. */
+  listProjectObjects(id: string, opts?: { cursor?: string; type?: ProjectObject["type"] }): Promise<ProjectObjectsPage> {
     const q = new URLSearchParams();
     if (opts?.cursor) q.set("cursor", opts.cursor);
+    if (opts?.type) q.set("type", opts.type);
     return this.fetch<ProjectObjectsPage>(
       `/api/v1/projects/${encodeURIComponent(id)}/objects${q.toString() ? `?${q}` : ""}`,
     );
   }
 
+  /** How many objects of each kind the project holds for the caller
+   *  (member only): the whole project's counts, where a page of
+   *  `listProjectObjects` holds at most fifty. */
+  getProjectObjectCounts(id: string): Promise<ProjectObjectCounts> {
+    return this.fetch<ProjectObjectCounts>(`/api/v1/projects/${encodeURIComponent(id)}/objects/counts`);
+  }
+
+  /** The project status view (member only): its outcome threads with their
+   *  plans, workers, people and next dates, the project's progress, finish
+   *  line and next check-in, and what moved lately. `threads` is
+   *  cursor-paginated; `recentlyClosed` rides the first page. */
+  getProjectStatus(id: string, opts?: { cursor?: string; limit?: number }): Promise<ProjectStatus> {
+    const q = new URLSearchParams();
+    if (opts?.cursor) q.set("cursor", opts.cursor);
+    if (opts?.limit) q.set("limit", String(opts.limit));
+    return this.fetch<ProjectStatus>(
+      `/api/v1/projects/${encodeURIComponent(id)}/status${q.toString() ? `?${q}` : ""}`,
+    );
+  }
+
+  /** One thread's status for the inline expansion of a status row: its
+   *  summary, workers by state, to-dos and last events. 404 for a thread
+   *  the caller cannot read. */
+  getThreadStatus(threadId: string): Promise<ThreadStatus> {
+    return this.fetch<ThreadStatus>(`/api/v1/threads/${encodeURIComponent(threadId)}/status`);
+  }
+
+  /** The caller's personal status in the current workspace: the threads
+   *  relevant to them (posted, mentioned, asked, a to-do, or in the chat),
+   *  grouped client-side by project. `threads` is cursor-paginated. */
+  getMeStatus(opts?: { cursor?: string; limit?: number }): Promise<MeStatus> {
+    const q = new URLSearchParams();
+    if (opts?.cursor) q.set("cursor", opts.cursor);
+    if (opts?.limit) q.set("limit", String(opts.limit));
+    return this.fetch<MeStatus>(`/api/v1/me/status${q.toString() ? `?${q}` : ""}`);
+  }
+
   /** DRY-RUN preview of a session add: the files that WOULD be shared (from
    *  the caller's owned scopes) + any owned-but-skipped entries (paths
    *  concealed from the caller are omitted). Powers the consent dialog. Same
@@ -2083,9 +2215,10 @@ export class AgentComposeClient {
       { method: "POST", body: input });
   }
 
-  /** The team's connector grants (metadata only — never tokens). Used by
-   *  `agentc repos link` to default `--grant` when the team holds exactly
-   *  one active GitHub grant. */
+  /** The caller's own connector grants and the workspace's GitHub
+   *  installations (metadata only — never tokens; a teammate's other
+   *  accounts never come back). Used by `agentc repos link` to default
+   *  `--grant` when the team holds exactly one active GitHub grant. */
   async listConnectorGrants(): Promise<ConnectorGrantSummary[]> {
     const body = await this.fetch<{ data: ConnectorGrantSummary[] }>("/api/v1/connectors");
     return body.data;
@@ -2164,7 +2297,16 @@ export class AgentComposeClient {
    *  writer. */
   requestSessionSecrets(
     conversationId: string, keys: string[],
-    opts?: { reason?: string; setLabel?: string; kind?: VaultRequestKind },
+    opts?: {
+      reason?: string; setLabel?: string; kind?: VaultRequestKind; shapes?: Record<string, VaultKeyShape>;
+      savedEntry?: RequestedVaultEntry;
+      /** A REPLACEMENT: the keys are held already and did not work; the card
+       *  asks for a new value of the same key. */
+      replace?: boolean;
+      /** A different credential of a kind the work already holds under
+       *  another name (the server refuses such an ask without it). */
+      distinct?: boolean;
+    },
   ): Promise<SessionSecretRequestCreated> {
     return this.fetch(
       `/api/v1/conversations/${encodeURIComponent(conversationId)}/secret-requests`,
@@ -2176,6 +2318,14 @@ export class AgentComposeClient {
         // WHAT KIND of credential — the vault page leads with the user's
         // matching STANDING entries (personal-vault reuse, 2026-08-31).
         ...(opts?.kind ? { kind: opts.kind } : {}),
+        // WHICH standing entry — by label and/or a card's last four — so the
+        // card and the vault page lead with that exact one.
+        ...(opts?.savedEntry ? { savedEntry: opts.savedEntry } : {}),
+        // Per-key DELIVERY (brokered onto a host, or injected) — required
+        // for every key of an api_key ask.
+        ...(opts?.shapes ? { shapes: opts.shapes } : {}),
+        ...(opts?.replace ? { replace: true } : {}),
+        ...(opts?.distinct ? { distinct: true } : {}),
       } });
   }
 
@@ -2183,8 +2333,11 @@ export class AgentComposeClient {
    *  could grant to this session — labels, kinds, field NAMES, last-used.
    *  Values are write-only and never on this wire. Query it BEFORE asking
    *  the human for a credential: a matching entry means the ask is a GRANT
-   *  ask naming it, never a blank re-entry form. */
-  getSessionVaultCatalog(conversationId: string): Promise<{ entries: VaultCatalogEntry[]; note?: string }> {
+   *  ask naming it, never a blank re-entry form. For the session's own key
+   *  it also carries `reaches`: what the session already reaches with no
+   *  credential asked for (`agentc access`), so a need met there is never
+   *  a vault ask. */
+  getSessionVaultCatalog(conversationId: string): Promise<{ entries: VaultCatalogEntry[]; note?: string; reaches?: string }> {
     return this.fetch(
       `/api/v1/conversations/${encodeURIComponent(conversationId)}/vault-catalog`);
   }
@@ -2192,7 +2345,7 @@ export class AgentComposeClient {
   /** Poll a vault link's status (`pending` → `fulfilled`; `expired` when the
    *  clock ran out; `cancelled` when the human denied it or the requester
    *  withdrew it — attribution rides the answer). The in-sandbox
-   *  `agentc secrets request --wait` loop. */
+   *  `agentc secrets session request --wait` loop. */
   getSessionSecretRequest(conversationId: string, requestId: string): Promise<SessionSecretRequestStatus> {
     return this.fetch(
       `/api/v1/conversations/${encodeURIComponent(conversationId)}/secret-requests/${encodeURIComponent(requestId)}`);
@@ -2224,6 +2377,8 @@ export class AgentComposeClient {
   /** Create a new API key on the caller's team. The plaintext `key` is
    *  returned once — it cannot be retrieved later.
    *
+   *  `scopes` omitted mints `read` alone; every scope asked for must be one
+   *  the caller holds (a key carries no more than whoever mints it).
    *  When `factorySlug` is set, the new key is restricted to that factory.
    *  Factory-scoped keys can only mint other keys bound to the same factory. */
   createApiKey(input: CreateApiKeyInput): Promise<ApiKeyCreated> {

package/src/directives.ts

@@ -62,9 +62,9 @@ export type CloudDirective =
    *  the mentions ping are server-authoritative (`display_ask` shape). The
    *  one write-bearing directive (see the module header). */
   | { kind: "ask"; prompt: string; approver: string; options?: Array<{ id: string; label: string }> }
-  /** Offer the human the desktop takeover door (`request_desktop_takeover`
-   *  shape): the server captures the current screen and posts a card with a
-   *  signed takeover link — "You can take over from here." Grants nothing
+  /** Offer the human the desktop takeover door (`show_computer` handing the
+   *  screen over): the server captures the current screen and posts a card
+   *  with a signed takeover link — "You can take over from here." Grants nothing
    *  by itself: the link's viewer must still be a signed-in member with
    *  write access to THIS session (the server re-checks on every resolve).
    *  ONLY for structurally-human walls (a CAPTCHA, human-only verification)

package/src/display.ts

@@ -681,6 +681,18 @@ function runIdIn(text: string): { runId: string; parsed: Record<string, unknown>
   return m ? { runId: m[1], parsed: null } : null;
 }
 
+/** Every platform tool name `createDisplayPromoter` can put on a promoted
+ *  `tool_call` — the closed set a local bridge daemon may legitimately post
+ *  under a platform-owned name. The server's part-POST door
+ *  (routes/bridge.ts) refuses every other platform tool name from a daemon,
+ *  so a local agent cannot forge an approval, vault or takeover card. Kept
+ *  beside the promoter so the two cannot drift. */
+export const DISPLAY_PROMOTED_TOOL_NAMES: ReadonlySet<string> = new Set([
+  "display_run", "display_changes", "display_document", "display_plan", "display_image",
+  "display_desktop", "display_preview", "display_table", "display_chart", "display_diff",
+  "display_ask", "dispatch_workflow",
+]);
+
 export function createDisplayPromoter(ctx: DisplayPromoterContext = {}): DisplayPromoter {
   const pending = new Map<string, PendingPromotion>();