@agent-compose/sdk 0.8.2 → 0.8.3

package/dist/client.d.ts

@@ -12,17 +12,17 @@
  */
 import type { RunEvent } from "./types/events.js";
 import type { ConversationStreamEvent } from "./types/conversation-stream.js";
-import type { InvokeWorkflowOptions, InvokeAndWaitOptions, InvokeResult, StreamRunLogsOptions, InlineWorkflowPayload, InvokeInlineOptions, InvokeInlineAndWaitOptions, RunStatus, ResumePauseOptions, ResumePauseResponse, AnswerSteerOptions, RequestAgentPauseOptions, RequestAgentPauseResponse, SendAgentMessageOptions, SendAgentMessageResponse, RunDetail, RunListEntry, ListRunsOptions, TimelineEvent, RunFundingResponse, EventRow, ReportEventInput, ListEventsOptions, ListEventsResult, RunArtifactRow, RunLogLine, ListRunLogsOptions, CancelRunResponse, ListSnapshotsOptions, SnapshotListResponse, SnapshotListEntry, RunSnapshotEntry } from "./types/api-runs.js";
-import type { TeamMember, Mention, CreateMentionsInput, ConversationsPage, SessionsPage, ConversationDetail, ConversationThread, CreateCloudSessionInput, CloudSessionCreated, SessionPreview, PreviewOpened, OpenPreviewInput, SessionForked, BackgroundWorkHeld, SessionChangeSet, SessionMergeGated, SessionMergeReport, SessionDiscardReport, SendConversationMessageInput, SendConversationMessageResult, ChannelSessionRow, SessionChannelMessagePosted, ConversationPresenceSnapshot, StreamConversationOptions, AgentListRow } from "./types/api-conversations.js";
+import type { InvokeWorkflowOptions, InvokeAndWaitOptions, InvokeResult, StreamRunLogsOptions, InlineWorkflowPayload, InvokeInlineOptions, InvokeInlineAndWaitOptions, RunStatus, ResumePauseOptions, ResumePauseResponse, AnswerSteerOptions, RequestAgentPauseOptions, RequestAgentPauseResponse, SendAgentMessageOptions, SendAgentMessageResponse, RunDetail, RunListEntry, ListRunsOptions, TimelineEvent, RunFundingResponse, RunStepUsageResponse, EventRow, ReportEventInput, ListEventsOptions, ListEventsResult, RunArtifactRow, RunLogLine, ListRunLogsOptions, CancelRunResponse, ListSnapshotsOptions, SnapshotListResponse, SnapshotListEntry, RunSnapshotEntry } from "./types/api-runs.js";
+import type { TeamMember, Mention, CreateMentionsInput, ConversationsPage, SessionsPage, ConversationDetail, ConversationThread, CreateCloudSessionInput, CloudSessionCreated, SessionPreview, PreviewOpened, OpenPreviewInput, SessionForked, BackgroundWorkHeld, SessionChangeSet, SessionMergeGated, SessionMergeReport, SessionDiscardReport, SessionChangePreflight, SessionRebaseReport, SessionAutoRebaseState, ReviewSuggestionInput, ReviewNotesPublished, ReviewGitCredential, SendConversationMessageInput, SendConversationMessageResult, ChannelSessionRow, SessionChannelMessagePosted, SessionDirectMessageSent, BranchClaimGranted, BranchClaimsReleased, BranchClaimState, ConversationPresenceSnapshot, StreamConversationOptions, AgentListRow, SessionPerfHistoryPage } from "./types/api-conversations.js";
 import type { ConversationMemberRole, ConversationMember, ArtifactScope, SetScopeGrantsInput, SetTemplateScopeInput } from "./types/api-scopes.js";
 import type { Project, ProjectsPage, ProjectRole, ProjectMember, ProjectObjectsPage, ProjectAddPreview, AddProjectObjectInput, AddProjectObjectResult, RefreshProjectObjectResult } from "./types/api-projects.js";
-import type { RegisterResult, RegisterWorkflowInput, TemplateRow, TemplateDetail, ListTemplatesOptions, SearchFactoryFilesOptions, FactoryFileSearchResult, FactoryFileWriteResult, FactoryRow, CreateFactoryInput, UpdateFactoryInput, ScheduleRow, CreateScheduleInput, SecretOptions, SetSecretResult, SecretListEntry, CreateApiKeyInput, ApiKeyCreated, ListApiKeysOptions, ApiKeyPage, UsageResponse, DriveRepoLink, CreateDriveRepoLinkInput, DriveMountSession, CreateDriveMountSessionInput } from "./types/api-factory.js";
+import type { RegisterResult, RegisterWorkflowInput, TemplateRow, TemplateDetail, ListTemplatesOptions, SearchFactoryFilesOptions, FactoryFileSearchResult, FactoryFileWriteResult, ListFactoryFilesOptions, FactoryFileListPage, FactoryRow, CreateFactoryInput, UpdateFactoryInput, FactoryPerfSummary, ScheduleRow, CreateScheduleInput, SecretOptions, SetSecretResult, SecretListEntry, SessionSecretEntry, SessionSecretInput, SessionSecretRequestCreated, SessionSecretRequestStatus, CreateApiKeyInput, ApiKeyCreated, ListApiKeysOptions, ApiKeyPage, UsageResponse, DriveRepoLink, CreateDriveRepoLinkInput, DriveMountSession, CreateDriveMountSessionInput } from "./types/api-factory.js";
 import type { ComplianceSession, RequestComplianceSessionInput, ListComplianceSessionsOptions, ComplianceSessionsPage, ListComplianceAccessesOptions, ComplianceAccessesPage } from "./types/api-compliance.js";
-export type { RunState, InvokeWorkflowOptions, InvokeAndWaitOptions, InvokeResult, FundingChoice, StreamRunLogsOptions, InlineWorkflowPayload, InvokeInlineOptions, InvokeInlineAndWaitOptions, RunStatus, ResumePauseActor, ResumePauseSuccess, ResumePausePending, ResumePauseResponse, ResumePauseOptions, RequestAgentPauseOptions, AnswerSteerOptions, RequestAgentPauseResponse, SendAgentMessageOptions, SendAgentMessageResponse, RunDetail, RunListEntry, ListRunsOptions, TimelineEvent, FundingLane, RunFundingStamp, RunFundingUsageRow, RunFundingResponse, EventSubjectType, EventRow, RunArtifactRow, ReportEventInput, ListEventsOptions, ListEventsResult, RunLogLine, ListRunLogsOptions, CancelRunResponse, ListSnapshotsOptions, SnapshotListEntry, SnapshotListResponse, RunSnapshotEntry, } from "./types/api-runs.js";
-export type { TeamMember, Mention, CreateMentionsInput, ConversationMessagePart, ConversationRow, ConversationMessageRow, ConversationsPage, SessionsPage, ConversationDetail, CreateCloudSessionInput, CloudSessionCreated, ConversationThread, SessionPreview, PreviewOpened, OpenPreviewInput, SessionForked, BackgroundWorkHeld, SessionFileChange, SessionChangeSet, SessionChangeStats, SessionDiffReviewBound, ReviewSuggestion, ReviewSuggestionDecision, ReviewSuggestionDecisions, SessionMergeReportDetail, SessionMergeReport, SessionMergeGated, SessionDiscardReport, ConversationPageContext, SendConversationMessageInput, ConversationTurnState, SendConversationMessageResult, UnnotifiedMention, ConversationPresenceSnapshot, AgentListRow, StreamConversationOptions, ChannelSessionStatus, ChannelSessionRow, ChannelSessionsResponse, SessionChannelMessagePosted, } from "./types/api-conversations.js";
+export type { RunState, InvokeWorkflowOptions, InvokeAndWaitOptions, InvokeResult, FundingChoice, StreamRunLogsOptions, InlineWorkflowPayload, InvokeInlineOptions, InvokeInlineAndWaitOptions, RunStatus, ResumePauseActor, ResumePauseSuccess, ResumePausePending, ResumePauseResponse, ResumePauseOptions, RequestAgentPauseOptions, AnswerSteerOptions, RequestAgentPauseResponse, SendAgentMessageOptions, SendAgentMessageResponse, RunDetail, RunListEntry, ListRunsOptions, TimelineEvent, FundingLane, RunFundingStamp, RunFundingUsageRow, RunFundingResponse, RunStepUsage, RunStepUsageResponse, EventSubjectType, EventRow, RunArtifactRow, ReportEventInput, ListEventsOptions, ListEventsResult, RunLogLine, ListRunLogsOptions, CancelRunResponse, ListSnapshotsOptions, SnapshotListEntry, SnapshotListResponse, RunSnapshotEntry, } from "./types/api-runs.js";
+export type { TeamMember, Mention, CreateMentionsInput, ConversationMessagePart, ConversationRow, ConversationMessageRow, ConversationsPage, SessionsPage, ConversationDetail, CreateCloudSessionInput, CloudSessionCreated, ConversationThread, SessionPreview, PreviewOpened, OpenPreviewInput, SessionForked, BackgroundWorkHeld, SessionFileChange, SessionChangeSet, SessionChangeStats, SessionDiffReviewBound, ReviewSuggestion, ReviewSuggestionInput, ReviewNotesPublished, ReviewGitCredential, SessionReviewDocument, ReviewSuggestionDecision, ReviewSuggestionDecisions, SessionMergeReportDetail, SessionMergeReport, SessionMergeGated, SessionDiscardReport, SessionPreflightFileRow, SessionChangePreflight, SessionRebaseReport, SessionAutoRebaseState, ConversationPageContext, SendConversationMessageInput, ConversationTurnState, SendConversationMessageResult, UnnotifiedMention, ConversationPresenceSnapshot, AgentListRow, StreamConversationOptions, ChannelSessionStatus, ChannelSessionRow, ChannelSessionsResponse, SessionChannelMessagePosted, SessionDirectMessageSent, BranchClaimInfo, BranchClaimGranted, BranchClaimsReleased, BranchClaimState, SessionPerfBucket, SessionPerfHistoryPage, } from "./types/api-conversations.js";
 export type { ConversationMemberRole, ConversationMember, DocumentCapability, TemplateCapability, ScopeGrant, ArtifactScope, RunContext, SetScopeGrantsInput, SetTemplateScopeInput, } from "./types/api-scopes.js";
 export type { Project, ProjectsPage, ProjectRole, ProjectMember, ProjectObject, ProjectObjectsPage, ProjectSkippedFile, ProjectPreviewFile, ProjectAddPreview, AddProjectObjectInput, AddProjectObjectResult, RefreshProjectObjectResult, } from "./types/api-projects.js";
-export type { RegisterResult, RegisteredRuntime, RuntimeSourceInput, TemplateSourceRef, RegisterWorkflowInput, TemplateRow, TemplateDetail, ListTemplatesOptions, FactoryFileSearchRow, FactoryFolderSearchRow, SearchFactoryFilesOptions, FactoryFileSearchResult, FactoryFileWriteResult, PublicFileLinkState, FactoryRow, CreateFactoryInput, UpdateFactoryInput, ScheduleRow, CreateScheduleInput, SecretOptions, SetSecretResult, SecretListEntry, CreateApiKeyInput, ApiKey, ApiKeyCreated, ListApiKeysOptions, ApiKeyPage, UsageRollupRow, UsageResponse, DriveRepoLink, CreateDriveRepoLinkInput, DriveMountSession, CreateDriveMountSessionInput, } from "./types/api-factory.js";
+export type { RegisterResult, RegisteredRuntime, RuntimeSourceInput, TemplateSourceRef, RegisterWorkflowInput, TemplateRow, TemplateDetail, ListTemplatesOptions, FactoryFileSearchRow, FactoryFolderSearchRow, SearchFactoryFilesOptions, FactoryFileSearchResult, FactoryFileWriteResult, FactoryFileListRow, ListFactoryFilesOptions, FactoryFileListPage, PublicFileLinkState, FactoryRow, CreateFactoryInput, UpdateFactoryInput, FactoryPerfSummary, ScheduleRow, CreateScheduleInput, SecretOptions, SetSecretResult, SecretListEntry, SessionSecretEntry, SessionSecretInput, SessionSecretRequestCreated, SessionSecretRequestStatus, CreateApiKeyInput, ApiKey, ApiKeyCreated, ListApiKeysOptions, ApiKeyPage, UsageRollupRow, UsageResponse, DriveRepoLink, CreateDriveRepoLinkInput, DriveMountSession, CreateDriveMountSessionInput, } from "./types/api-factory.js";
 export type { ComplianceScopeKind, ComplianceStatus, ComplianceSession, ComplianceAccess, RequestComplianceSessionInput, ListComplianceSessionsOptions, ComplianceSessionsPage, ListComplianceAccessesOptions, ComplianceAccessesPage, } from "./types/api-compliance.js";
 export interface AgentComposeClientOptions {
     /** Your team's API key — minted from the dashboard or `agentc keys create`.
@@ -194,6 +194,11 @@ export declare class AgentComposeClient {
      * the only usage the ledger records (non-platform lanes are attribution,
      * never metered). */
     getRunFunding(runId: string): Promise<RunFundingResponse>;
+    /** Attested platform tokens attributed to each of a run's steps, derived
+     * server-side from the spend ledger by step time window. Empty `steps` is
+     * an honest answer (legacy run, or funded outside the platform lane —
+     * that money is never metered). */
+    getRunStepUsage(runId: string): Promise<RunStepUsageResponse>;
     /** Report a durable event against a run. Events are late-binding facts
      * like quality.accepted, defect.regression, or intervention.override. */
     reportEvent(runId: string, input: ReportEventInput): Promise<EventRow>;
@@ -222,6 +227,7 @@ export declare class AgentComposeClient {
         factorySlug?: string;
         revision?: number;
         branch?: string;
+        at?: string;
     }): Promise<Uint8Array>;
     /** Read one file's current content (or a specific revision) as text
      *  (UTF-8). For binary files use `getFactoryFileBytes` — decoding them to
@@ -230,6 +236,7 @@ export declare class AgentComposeClient {
         factorySlug?: string;
         revision?: number;
         branch?: string;
+        at?: string;
     }): Promise<string>;
     /** Create a local drive mount (or re-mint an existing one's token by
      *  passing its `conversationId`). */
@@ -255,6 +262,19 @@ export declare class AgentComposeClient {
     listSessions(factoryId: string, opts?: {
         cursor?: string;
     }): Promise<SessionsPage>;
+    /** A session's sandbox perf HISTORY — 15-minute rollup buckets
+     *  (CPU/mem/disk percentiles, load, saturation seconds), newest first.
+     *  Member-gated like the session itself. Cursor-paginated. */
+    getSessionPerfHistory(conversationId: string, opts?: {
+        limit?: number;
+        cursor?: string;
+    }): Promise<SessionPerfHistoryPage>;
+    /** Team-level sandbox perf aggregates over a window (default trailing
+     *  24h, max 30 days). Aggregate-only — no per-session identifiers. */
+    getFactoryPerfSummary(factorySlug: string, opts?: {
+        from?: string;
+        to?: string;
+    }): Promise<FactoryPerfSummary>;
     /** One conversation with its latest page of messages. `limit` bounds the
      *  page (newest N) — metadata-only consumers (e.g. resolving the
      *  session's drive branch) pass 1 instead of pulling the full hydrate. */
@@ -300,6 +320,40 @@ export declare class AgentComposeClient {
         text: string;
         threadRootId?: string;
     }): Promise<SessionChannelMessagePosted>;
+    /** 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)
+     *  or a conversation uuid. Unlike a channel post this WAKES the target's
+     *  turn machinery; the response's `turn` verdict says whether it started,
+     *  queued behind a live turn, or was parked by the agent-to-agent
+     *  exchange damper. Unknown alias → 404 with `candidates`. */
+    sendSessionMessage(input: {
+        target: string;
+        text: string;
+    }): Promise<SessionDirectMessageSent>;
+    /** Claim ANOTHER session's drive branch for the calling session
+     *  (`agentc branch claim @alias`) — transfers the branch's one-writer
+     *  authority: the target's own writes refuse honestly until release, and
+     *  the response carries the mount token the CLI uses to FUSE-mount the
+     *  branch in-guest. Session toolbelt credential only; same-owner sessions
+     *  only (cross-user claims refuse with the gap stated); refuses while the
+     *  target is mid-turn (409 `mid_turn`) or already claimed
+     *  (409 `already_claimed`). */
+    claimSessionBranch(input: {
+        target: string;
+        reason?: string;
+    }): Promise<BranchClaimGranted>;
+    /** Release branch claims HELD by the calling session (`agentc branch
+     *  release [@alias]`). `target` narrows to one claim; omitted releases
+     *  them all. Idempotent — an empty `released` list means nothing was
+     *  held. */
+    releaseSessionBranchClaims(input?: {
+        target?: string;
+    }): Promise<BranchClaimsReleased>;
+    /** One session's branch-claim state: the live claim ON its branch (null =
+     *  writable there) and the claims it HOLDS (`agentc branch status`, the
+     *  dashboard's Changes-panel badge). Any viewer with access. */
+    getSessionBranchClaimState(conversationId: string): Promise<BranchClaimState>;
     /** Open a dev preview on a cloud session: expose a port a dev server is
      *  LISTENING on inside the session sandbox at a member-gated proxy URL, and
      *  post an "Open preview" card to the transcript. Resumes a suspended VM
@@ -335,7 +389,47 @@ export declare class AgentComposeClient {
      *  writes `main` directly. The list reflects the branch's last flush and
      *  is advisory; a merge re-verifies against fresh state. 404 = not found
      *  or not a member (uniform). */
-    getSessionChanges(conversationId: string): Promise<SessionChangeSet>;
+    getSessionChanges(conversationId: string, opts?: {
+        after?: string;
+        limit?: number;
+    }): Promise<SessionChangeSet>;
+    /** One proposed file's RAW BYTES from a session's change set
+     *  (`GET /conversations/:id/changes/content`) — the review surface's
+     *  per-file read, also the in-sandbox `agentc review file` door.
+     *  `side: "base"` serves the PRE-change side (graph plane; the legacy
+     *  plane ignores it and always serves the proposed side). 404 = missing
+     *  path or no access (uniform, no existence oracle). */
+    getSessionChangeContent(conversationId: string, path: string, opts?: {
+        side?: "base";
+    }): Promise<Uint8Array>;
+    /** 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`).
+     *
+     *  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
+     *  `review_disabled`. */
+    publishReviewNotes(conversationId: string, input: {
+        notes: string;
+        suggestions?: ReviewSuggestionInput[];
+    }): Promise<ReviewNotesPublished>;
+    /** Mint ONE fresh short-lived credential for the review git remote
+     *  (`POST /conversations/:id/review-git-credential`) — the server half
+     *  of the review sandbox's git credential helper (`agentc review
+     *  git-credential`), which calls this per git operation so the remote's
+     *  credential can never expire mid-review. Callable only with a review
+     *  session's own toolbelt credential; `conversationId` is the REVIEWED
+     *  session's conversation (`AGENT_COMPOSE_REVIEW_OF_CONVERSATION_ID`).
+     *
+     *  Failures: 403 `session_credential_required` | `not_review_session`;
+     *  409 `review_disabled` | `git_remote_unavailable` (legacy plane — read
+     *  the proposal through `getSessionChanges` instead). */
+    getReviewGitCredential(conversationId: string): Promise<ReviewGitCredential>;
     /** Approve the session's proposed changes: 3-way merge its branch into
      *  `main`, then continue the session on a fresh branch off post-merge
      *  `main`. Write-tier + human caller. Pass `opts.branch` (the branch you
@@ -363,6 +457,39 @@ export declare class AgentComposeClient {
     discardSessionChanges(conversationId: string, opts?: {
         branch?: string;
     }): Promise<SessionDiscardReport>;
+    /** The conflict PREFLIGHT: which of the session's changed files would
+     *  conflict with main if merged right now — the real merge's own per-file
+     *  classification, report-only (no writes, no locks). Read-tier.
+     *  Discriminate on `state`: `pending` means a cold compute is still
+     *  running — poll again to collect it; `unavailable` = no cheap anchors
+     *  (legacy plane / unbranched) — degrade honestly. */
+    getSessionChangePreflight(conversationId: string): Promise<SessionChangePreflight>;
+    /** Rebase the session's branch ON main — fold main's current state
+     *  into the session's workspace (the reverse merge; main is never
+     *  touched). Conflicting files KEEP the session's version: each is
+     *  recorded as a conflict row and the session is told in-conversation to
+     *  reconcile. Write-tier — a session's own toolbelt key may rebase its
+     *  OWN branch (unlike merge/discard, which need a human). Pass
+     *  `opts.branch` to fail 409 `branch_changed` if it rotated since review.
+     *
+     *  Failures: 409 `plane_unsupported` (legacy drive plane) |
+     *  `review_session_scratch` | `branch_moved` (the branch advanced
+     *  mid-rebase — retry) | `turn_active` | `decision_in_progress` |
+     *  `freshen_failed` / `merge_retry` (mount mid-handoff — retry); 400
+     *  `no_branch`; 502 `rebase_failed` (nothing changed — retry-safe). */
+    rebaseSessionChanges(conversationId: string, opts?: {
+        branch?: string;
+    }): Promise<SessionRebaseReport>;
+    /** Arm/disarm the OPT-IN main-advance auto-rebase reflex for a session
+     *  (default OFF): when armed and the drive's main moves, the platform
+     *  preflights and — only on a provably clean fold (zero conflicts) —
+     *  rebases the session's branch from main headlessly, posting a quiet
+     *  receipt. Trade-off (why default OFF): the agent's view of files it
+     *  did not touch can change mid-task. Human, write-tier act.
+     *
+     *  Failures: 409 `review_session_scratch` | `plane_unsupported`; 403
+     *  (needs a user-bound human caller with write access). */
+    setSessionAutoRebase(conversationId: string, enabled: boolean): Promise<SessionAutoRebaseState>;
     /** The conversation's member roster with roles. Solo conversations
      *  return an empty roster; a dm returns the pair. */
     getConversationMembers(conversationId: string): Promise<ConversationMember[]>;
@@ -399,10 +526,14 @@ export declare class AgentComposeClient {
      *  scoped, not surface-scoped: any member can cancel, whichever surface
      *  started the turn. The canceled turn closes with a terminal error part
      *  (it is never re-run); a message sent after it stays queued and is
-     *  answered next. `canceled: false` = nothing was in flight. Requires
+     *  answered next. `canceled: false` = nothing was in flight. `owed`
+     *  reports the queued-backlog kick: 'dispatched' = a turn answering the
+     *  queue was started by this call; 'held' = a live release loop owns the
+     *  backlog; 'none' = nothing queued (absent on older servers). Requires
      *  the `invoke` scope. */
     cancelConversationTurn(conversationId: string): Promise<{
         canceled: boolean;
+        owed?: "dispatched" | "held" | "none";
     }>;
     /** Announce this client as ATTACHED to a conversation (ADR-0037 §6) —
      *  beat every ~30s while a surface shows the transcript. Each beat fans
@@ -433,6 +564,12 @@ export declare class AgentComposeClient {
     /** Search a factory drive's live files — path substring OR full-text match
      *  on extracted content. Cursor-paginated by path. */
     searchFactoryFiles(query: string, opts?: SearchFactoryFilesOptions): Promise<FactoryFileSearchResult>;
+    /** List a factory drive's files — a flat recursive listing, cursor-
+     *  paginated by path. The live index by default; pass `at` (a retained
+     *  64-hex commit) to browse the MAIN drive as of that head — read-only
+     *  time travel, with `branch` + `at` pinning a graph branch instead. A
+     *  garbage-collected/unknown head throws 410 `at_unavailable`. */
+    listFactoryFiles(opts?: ListFactoryFilesOptions): Promise<FactoryFileListPage>;
     /** List the human members of your team — the people you (or an agent) can
      *  @-flag with `createMentions`. Each row's `userId` is what
      *  `mentionedUserIds` expects. */
@@ -608,6 +745,25 @@ export declare class AgentComposeClient {
     listFactorySecrets(opts?: SecretOptions): Promise<SecretListEntry[]>;
     /** Delete a factory-level secret. */
     deleteFactorySecret(key: string, opts?: SecretOptions): Promise<void>;
+    /** List a session's secrets (names + metadata only — values are never returned). */
+    listSessionSecrets(conversationId: string): Promise<SessionSecretEntry[]>;
+    /** Set session secrets (bulk-friendly): value entries and/or `source:
+     *  "factory"` attachments-by-name. Returns the keys that were set. */
+    setSessionSecrets(conversationId: string, secrets: SessionSecretInput[]): Promise<string[]>;
+    /** Delete one session secret (owner or team admin). */
+    deleteSessionSecret(conversationId: string, key: string): Promise<void>;
+    /** Mint a VAULT LINK for this session — a short-lived, single-use page
+     *  where a session writer types the named credentials straight into the
+     *  session's secret store (they never transit the chat). Posts a card
+     *  into the session conversation; callable with the session's own
+     *  toolbelt credential (the in-sandbox agent's door) or by a session
+     *  writer. */
+    requestSessionSecrets(conversationId: string, keys: string[], opts?: {
+        reason?: string;
+    }): Promise<SessionSecretRequestCreated>;
+    /** Poll a vault link's status (`pending` → `fulfilled`; `expired` when the
+     *  clock ran out). The in-sandbox `agentc secrets request --wait` loop. */
+    getSessionSecretRequest(conversationId: string, requestId: string): Promise<SessionSecretRequestStatus>;
     /** Create a new API key on the caller's team. The plaintext `key` is
      *  returned once — it cannot be retrieved later.
      *

package/dist/display.d.ts

@@ -100,6 +100,16 @@ export type DisplayMarker = {
     prompt: string;
     options?: DisplayAskOption[];
     freeText: boolean;
+}
+/** A desktop snapshot (`agentc display desktop`): the CLI captured the
+ *  session VM's screen to `path` on the session's drive branch. The card
+ *  renders the snapshot + an "Open desktop" door to the live surface. */
+ | {
+    kind: "desktop";
+    path: string;
+    factorySlug?: string;
+    capturedAt?: string;
+    note?: string;
 };
 /** Clamp raw plan entries to the marker/part bounds; invalid rows drop. */
 export declare function clampPlanEntries(raw: unknown): DisplayPlanEntry[];
@@ -150,6 +160,8 @@ export declare const ASK_OPTION_LABEL_MAX_CHARS = 200;
 /** Normalize + clamp ask options. Accepts `["a","b"]` (id = label) or
  *  `[{ id, label }]`; invalid entries drop, duplicate ids drop. */
 export declare function clampAskOptions(raw: unknown): DisplayAskOption[];
+/** Desktop-snapshot note bound — one caption line on the card. */
+export declare const DESKTOP_NOTE_MAX_CHARS = 200;
 /** One-line JSON marker — exactly what `agentc display` prints. */
 export declare function serializeDisplayMarker(marker: DisplayMarker): string;
 /** Parse one line as a display marker; null when it isn't one (or fails
@@ -176,6 +188,11 @@ export type AgentcInvocation = {
     path: string;
     factorySlug?: string;
 }
+/** `agentc display desktop` — the CLI captures the screen itself, so the
+ *  call has no positional path; the marker in the result names the file. */
+ | {
+    verb: "display-desktop";
+}
 /** Directive verb — detection only arms the tool_call promotion; the
  *  result keeps its raw output so the directive marker reaches the cloud
  *  executor. Same for table `source:"file"`, diff, and ask-with-approver. */

package/dist/index.d.ts

@@ -14,7 +14,7 @@ export { defineRuntime } from "./types/runtime.js";
 export { defineWorkflow } from "./types/workflow.js";
 export { defineSandboxEnvironment } from "./types/sandbox-environment.js";
 export type { SandboxEnvironmentDefinition } from "./types/sandbox-environment.js";
-export type { AgentRuntime, McpServerConfig, ModelExecutionContract, ToolCallGateResult, RuntimeOptions, } from "./types/runtime.js";
+export type { AgentRuntime, McpServerConfig, ModelExecutionContract, RunnerLivenessVerdict, ToolCallGateResult, RuntimeOptions, TurnExitNotify, } from "./types/runtime.js";
 export type { WorkflowRun, AgentBudget, WorkflowHooks, SnapshotConfig, BootSnapshot, ReuseSnapshot, IOSchema, OutputSchema, } from "./types/workflow.js";
 export type { ConnectorRequestRules } from "./types/workflow-metadata.js";
 export type { RunSnapshotEntry } from "./client.js";
@@ -24,10 +24,10 @@ export { RequestContext, ReservedKeyError, NonSerialisableValueError, AC_RESERVE
 export type { RequestContextReserved, RequestContextWire, } from "./request-context/index.js";
 export { Verdict, runProcessorChain, denyTools, humanApproval, requireScope, redactPattern, createGatePauseProcessor, createAskHumanProcessor, ASK_USER_QUESTION_TOOL, } from "./processors/index.js";
 export type { Processor, ProcessorContext, ProcessorVerdict, ToolCall, GatePausePolicy, GatePauseApproval, GatePauseConnection, } from "./processors/index.js";
-export type { AgentMessage, AgentMessageInit, AgentMessageText, AgentMessageThinking, AgentMessageToolUse, AgentMessageToolResult, AgentMessageDone, AgentMessageError, AgentMessageUsage, AgentStatus, } from "./types/protocol.js";
+export type { AgentMessage, AgentMessageInit, AgentMessageText, AgentMessageThinking, AgentMessageToolUse, AgentMessageToolResult, AgentMessageDone, AgentMessageError, AgentMessageUsage, AgentMessageTaskNotification, AgentStatus, } from "./types/protocol.js";
 export type { SandboxProvider, DesktopSandboxProvider, SandboxPtyOpts, SandboxPtyHandle, } from "./types/sandbox.js";
 export { AgentComposeClient } from "./client.js";
-export type { RegisterResult, RegisterWorkflowInput, RuntimeSourceInput, TemplateSourceRef, InvokeWorkflowOptions, InvokeAndWaitOptions, InvokeResult, FundingChoice, InlineWorkflowPayload, InvokeInlineOptions, InvokeInlineAndWaitOptions, ListSnapshotsOptions, TemplateRow, ListTemplatesOptions, CreateFactoryInput, UpdateFactoryInput, SecretOptions, SetSecretResult, SecretListEntry, CreateApiKeyInput, StreamRunLogsOptions, TeamMember, Mention, CreateMentionsInput, EventSubjectType, EventRow, ReportEventInput, ListEventsOptions, ListEventsResult, RunLogLine, ListRunLogsOptions, RunListEntry, ListRunsOptions, RunDetail, FundingLane, RunFundingStamp, RunFundingUsageRow, RunFundingResponse, RegisteredRuntime, RunState, RunStatus, FactoryRow, SnapshotListEntry, SnapshotListResponse, ApiKey, ApiKeyCreated, ListApiKeysOptions, ApiKeyPage, UsageRollupRow, UsageResponse, CancelRunResponse, RequestAgentPauseOptions, RequestAgentPauseResponse, SendAgentMessageOptions, SendAgentMessageResponse, AnswerSteerOptions, ResumePauseOptions, ResumePauseResponse, ResumePauseSuccess, ResumePausePending, ResumePauseActor, ConversationMessagePart, ConversationRow, ConversationMessageRow, ConversationsPage, ConversationDetail, ConversationThread, ConversationPageContext, SendConversationMessageInput, SendConversationMessageResult, UnnotifiedMention, ConversationTurnState, ConversationPresenceSnapshot, StreamConversationOptions, AgentListRow, CreateCloudSessionInput, CloudSessionCreated, SessionPreview, PreviewOpened, OpenPreviewInput, SessionForked, BackgroundWorkHeld, SessionFileChange, SessionChangeSet, SessionChangeStats, SessionDiffReviewBound, ReviewSuggestion, ReviewSuggestionDecision, ReviewSuggestionDecisions, SessionMergeReportDetail, SessionMergeReport, SessionMergeGated, SessionDiscardReport, DriveMountSession, CreateDriveMountSessionInput, ChannelSessionStatus, ChannelSessionRow, ChannelSessionsResponse, SessionChannelMessagePosted, FactoryFileSearchRow, FactoryFolderSearchRow, SearchFactoryFilesOptions, FactoryFileSearchResult, PublicFileLinkState, ConversationMemberRole, ConversationMember, DocumentCapability, TemplateCapability, ScopeGrant, ArtifactScope, RunContext, SetScopeGrantsInput, SetTemplateScopeInput, TemplateDetail, Project, ProjectsPage, ProjectRole, ProjectMember, ProjectObject, ProjectObjectsPage, ProjectSkippedFile, ProjectPreviewFile, ProjectAddPreview, AddProjectObjectInput, AddProjectObjectResult, RefreshProjectObjectResult, ComplianceScopeKind, ComplianceStatus, ComplianceSession, ComplianceAccess, RequestComplianceSessionInput, ListComplianceSessionsOptions, ComplianceSessionsPage, ListComplianceAccessesOptions, ComplianceAccessesPage, } from "./client.js";
+export type { RegisterResult, RegisterWorkflowInput, RuntimeSourceInput, TemplateSourceRef, InvokeWorkflowOptions, InvokeAndWaitOptions, InvokeResult, FundingChoice, InlineWorkflowPayload, InvokeInlineOptions, InvokeInlineAndWaitOptions, ListSnapshotsOptions, TemplateRow, ListTemplatesOptions, CreateFactoryInput, UpdateFactoryInput, SecretOptions, SetSecretResult, SecretListEntry, SessionSecretEntry, SessionSecretInput, SessionSecretRequestCreated, SessionSecretRequestStatus, CreateApiKeyInput, StreamRunLogsOptions, TeamMember, Mention, CreateMentionsInput, EventSubjectType, EventRow, ReportEventInput, ListEventsOptions, ListEventsResult, RunLogLine, ListRunLogsOptions, RunListEntry, ListRunsOptions, RunDetail, FundingLane, RunFundingStamp, RunFundingUsageRow, RunFundingResponse, RunStepUsage, RunStepUsageResponse, RegisteredRuntime, RunState, RunStatus, FactoryRow, SnapshotListEntry, SnapshotListResponse, ApiKey, ApiKeyCreated, ListApiKeysOptions, ApiKeyPage, UsageRollupRow, UsageResponse, CancelRunResponse, RequestAgentPauseOptions, RequestAgentPauseResponse, SendAgentMessageOptions, SendAgentMessageResponse, AnswerSteerOptions, ResumePauseOptions, ResumePauseResponse, ResumePauseSuccess, ResumePausePending, ResumePauseActor, ConversationMessagePart, ConversationRow, ConversationMessageRow, ConversationsPage, ConversationDetail, ConversationThread, ConversationPageContext, SendConversationMessageInput, SendConversationMessageResult, UnnotifiedMention, ConversationTurnState, ConversationPresenceSnapshot, StreamConversationOptions, AgentListRow, CreateCloudSessionInput, CloudSessionCreated, SessionPreview, PreviewOpened, OpenPreviewInput, SessionForked, BackgroundWorkHeld, SessionFileChange, SessionChangeSet, SessionChangeStats, SessionDiffReviewBound, ReviewSuggestion, ReviewSuggestionInput, ReviewNotesPublished, ReviewGitCredential, SessionReviewDocument, ReviewSuggestionDecision, ReviewSuggestionDecisions, SessionMergeReportDetail, SessionMergeReport, SessionMergeGated, SessionDiscardReport, SessionPreflightFileRow, SessionChangePreflight, SessionRebaseReport, DriveMountSession, CreateDriveMountSessionInput, ChannelSessionStatus, ChannelSessionRow, ChannelSessionsResponse, SessionChannelMessagePosted, SessionDirectMessageSent, BranchClaimInfo, BranchClaimGranted, BranchClaimsReleased, BranchClaimState, SessionPerfBucket, SessionPerfHistoryPage, FactoryPerfSummary, FactoryFileSearchRow, FactoryFolderSearchRow, SearchFactoryFilesOptions, FactoryFileSearchResult, PublicFileLinkState, FactoryFileListRow, ListFactoryFilesOptions, FactoryFileListPage, ConversationMemberRole, ConversationMember, DocumentCapability, TemplateCapability, ScopeGrant, ArtifactScope, RunContext, SetScopeGrantsInput, SetTemplateScopeInput, TemplateDetail, Project, ProjectsPage, ProjectRole, ProjectMember, ProjectObject, ProjectObjectsPage, ProjectSkippedFile, ProjectPreviewFile, ProjectAddPreview, AddProjectObjectInput, AddProjectObjectResult, RefreshProjectObjectResult, ComplianceScopeKind, ComplianceStatus, ComplianceSession, ComplianceAccess, RequestComplianceSessionInput, ListComplianceSessionsOptions, ComplianceSessionsPage, ListComplianceAccessesOptions, ComplianceAccessesPage, } from "./client.js";
 export { parseSseStream } from "./sse.js";
 export { renderDirectiveMarker, parseDirectiveMarkers, DIRECTIVE_MARKER_PREFIX, DIRECTIVE_MARKER_SUFFIX, MAX_DIRECTIVES_PER_OUTPUT, REVISION_SELECTOR_RE, ASK_DIRECTIVE_PROMPT_MAX, ASK_DIRECTIVE_MAX_OPTIONS, ASK_DIRECTIVE_OPTION_ID_MAX, ASK_DIRECTIVE_OPTION_LABEL_MAX, ASK_APPROVER_MIN, ASK_APPROVER_MAX, } from "./directives.js";
 export type { CloudDirective } from "./directives.js";
@@ -51,6 +51,10 @@ export { createCodexRuntime, codexSpec } from "./runtimes/codex.js";
 export type { CodexRuntimeConfig, CodexReasoningEffort } from "./runtimes/codex.js";
 export { default as codexRuntime } from "./runtimes/codex.js";
 export type { CliReasoningEffort } from "./runtimes/_cli-agent.js";
+export { shellQuote, uniquePromptPath, turnLivenessProbeCommand, parseTurnProbeOutput, livenessVerdictFromReading, runnerBusySentinelFragment, exitEventPushCommand, injectAppendAndAckCommand, INJECT_ACK_EXEC_TIMEOUT_MS, streamInputFeederFragment, sessionEnvSourceFragment, credEnvSourceFragment, residentFeederFragment, residentIdleCheckFragment, residentIdleWatchdogFragment, residentResultCountCommand, deferredExitEventPushCommand, RESIDENT_IDLE_TTL_S, RESIDENT_WATCHDOG_POLL_S, RESIDENT_RESULT_LINE_PREFIX, SESSION_ENV_FILE_RELPATH, LAUNCH_EXEC_TIMEOUT_MS, TURN_PROBE_TIMEOUT_MS, INSTALL_PROBE_TIMEOUT_MS, CLI_INSTALL_TIMEOUT_MS, RUNNER_HEARTBEAT_INTERVAL_SECONDS, RUNNER_HEARTBEAT_STALE_MS, } from "./runtimes/_cli-agent.js";
+export type { TurnProbeReading, CliAgentSpec } from "./runtimes/_cli-agent.js";
+export { perfSamplerFunctionFragment, standalonePerfProbeCommand, parsePerfToken, parsePerfProbeOutput, PERF_SAMPLE_EVERY_BEATS, PERF_PROBE_WINDOW_SECONDS, PERF_TOKEN_MAX_CHARS, } from "./agent/perf-sampler.js";
+export type { GuestPerfSample } from "./agent/perf-sampler.js";
 export { createAmpRuntime } from "./runtimes/amp.js";
 export type { AmpRuntimeConfig } from "./runtimes/amp.js";
 export { default as ampRuntime } from "./runtimes/amp.js";
@@ -92,7 +96,12 @@ export { agent } from "./agent/run-agent.js";
 export type { AgentOpts } from "./agent/run-agent.js";
 export { AGENT_COMPOSE_MANUAL, buildAgentContextDoc, writeAgentContext, buildAddedSessionBrief } from "./agent/agent-context.js";
 export type { AgentConnectorInfo, AddedSessionBriefParams } from "./agent/agent-context.js";
+export { AC_OPEN_PATH, AC_OPEN_STATE_DIR, AC_OPEN_SHIM_PATHS, AC_OPEN_SCRIPT, AC_OPEN_SHIM, installDesktopOpenCmd, BROWSER_BACKFILL_PIDFILE, BROWSER_BACKFILL_LOG, BROWSER_BACKFILL_FAILED, BROWSER_INSTALL_IN_PROGRESS_MSG, browserBackfillCmd, browserBackfillStatusCmd, CHROMIUM_DEFAULTS, CHROMIUM_DEFAULTS_PATH, installChromiumDefaultsCmd, } from "./agent/desktop-open.js";
+export { SERVICES_MANIFEST_RELPATH, SERVICES_MAX, SERVICE_NAME_RE, parseServicesManifest, renderServicesManifest, } from "./agent/services-manifest.js";
+export type { ServiceEntry, ServiceHealth, ServiceDataHooks, ServicesManifest, ParseServicesManifestResult, } from "./agent/services-manifest.js";
+export { SERVICES_STATE_DIR, SERVICE_STATUS_PREFIX, SERVICE_HEALTH_TIMEOUT_S, servicesRestoreScript, servicesDumpScript, parseServicesRestoreOutput, formatServicesRestoreSummary, } from "./agent/services-restore.js";
+export type { ServiceRestoreOutcome, ServiceRestoreStatus } from "./agent/services-restore.js";
 export { AgentMessageSchema, parseAgentResponse } from "./agent/protocol.js";
 export { importSourceModule, TMP_DIR, LATEST_VERSION } from "./utils/source-loader.js";
-export { DISPLAY_MARKER_KEY, DISPLAY_MARKER_VERSION, PLAN_MAX_ENTRIES, PLAN_ENTRY_MAX_CHARS, TABLE_MAX_COLUMNS, TABLE_MAX_ROWS, TABLE_CELL_MAX_CHARS, CHART_MAX_SERIES, CHART_MAX_POINTS_PER_SERIES, CHART_LABEL_MAX_CHARS, ASK_PROMPT_MAX_CHARS, ASK_MAX_OPTIONS, ASK_OPTION_ID_MAX_CHARS, ASK_OPTION_LABEL_MAX_CHARS, DRIVE_PATH_MAX_CHARS, isPlausibleDrivePath, serializeDisplayMarker, parseDisplayMarker, findDisplayMarker, clampPlanEntries, clampTableData, clampChartSeries, clampChartAxisLabel, clampAskOptions, detectAgentcInvocation, shellWords, createDisplayPromoter, } from "./display.js";
+export { DISPLAY_MARKER_KEY, DISPLAY_MARKER_VERSION, PLAN_MAX_ENTRIES, PLAN_ENTRY_MAX_CHARS, TABLE_MAX_COLUMNS, TABLE_MAX_ROWS, TABLE_CELL_MAX_CHARS, CHART_MAX_SERIES, CHART_MAX_POINTS_PER_SERIES, CHART_LABEL_MAX_CHARS, ASK_PROMPT_MAX_CHARS, ASK_MAX_OPTIONS, ASK_OPTION_ID_MAX_CHARS, ASK_OPTION_LABEL_MAX_CHARS, DESKTOP_NOTE_MAX_CHARS, DRIVE_PATH_MAX_CHARS, isPlausibleDrivePath, serializeDisplayMarker, parseDisplayMarker, findDisplayMarker, clampPlanEntries, clampTableData, clampChartSeries, clampChartAxisLabel, clampAskOptions, detectAgentcInvocation, shellWords, createDisplayPromoter, } from "./display.js";
 export type { DisplayMarker, DisplayPlanEntry, DisplayPlanStatus, DisplayTableCell, DisplayTableColumn, DisplayTableData, DisplayChartKind, DisplayChartPoint, DisplayChartSeries, DisplayAskOption, AgentcInvocation, PromotedPart, DisplayPromoter, DisplayPromoterContext, } from "./display.js";