@agent-compose/sdk 0.8.1 → 0.8.3

package/src/display.ts

@@ -70,7 +70,11 @@ export type DisplayMarker =
   | { kind: "image"; path: string; factorySlug?: string }
   | { kind: "table"; columns: DisplayTableColumn[]; rows: Array<Record<string, DisplayTableCell>>; truncated: boolean }
   | { kind: "chart"; chartKind: DisplayChartKind; series: DisplayChartSeries[]; xLabel?: string; yLabel?: string }
-  | { kind: "ask"; askId: string; prompt: string; options?: DisplayAskOption[]; freeText: boolean };
+  | { kind: "ask"; askId: string; 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 };
 
 const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
 
@@ -273,6 +277,9 @@ export function clampAskOptions(raw: unknown): DisplayAskOption[] {
   return options;
 }
 
+/** Desktop-snapshot note bound — one caption line on the card. */
+export const DESKTOP_NOTE_MAX_CHARS = 200;
+
 /** One-line JSON marker — exactly what `agentc display` prints. */
 export function serializeDisplayMarker(marker: DisplayMarker): string {
   return JSON.stringify({ [DISPLAY_MARKER_KEY]: DISPLAY_MARKER_VERSION, ...marker });
@@ -350,6 +357,21 @@ export function parseDisplayMarker(line: string): DisplayMarker | null {
         ...(yLabel !== undefined ? { yLabel } : {}),
       };
     }
+    case "desktop": {
+      const path = str("path");
+      if (!path || !isPlausibleDrivePath(path)) return null;
+      // capturedAt must parse as a real instant — a garbage stamp is
+      // dropped rather than rendered as "Invalid Date" on the card.
+      const capturedAt = str("capturedAt");
+      const capturedOk = capturedAt !== undefined && Number.isFinite(Date.parse(capturedAt));
+      const note = str("note");
+      return {
+        kind: "desktop", path,
+        ...(str("factorySlug") ? { factorySlug: str("factorySlug") } : {}),
+        ...(capturedOk ? { capturedAt } : {}),
+        ...(note !== undefined ? { note: note.slice(0, DESKTOP_NOTE_MAX_CHARS) } : {}),
+      };
+    }
     case "ask": {
       const askId = str("askId");
       const rawPrompt = str("prompt");
@@ -384,6 +406,9 @@ export type AgentcInvocation =
   | { verb: "display-document"; path: string; factorySlug?: string }
   | { verb: "display-plan" }
   | { verb: "display-image"; 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. */
@@ -432,6 +457,7 @@ const VALUE_FLAGS = new Set([
   "--factory", "--input", "--entries", "--url", "--api-key", "--limit",
   "--thread", "--content-type", "--file", "--out", "--revision", "--ended-at",
   "--data", "--kind", "--from", "--to", "--prompt", "--options", "--approver",
+  "--note",
 ]);
 
 /** Detect a known agentc invocation inside a shell command string. Returns
@@ -514,6 +540,8 @@ export function detectAgentcInvocation(command: string): AgentcInvocation | null
         const path = drivePath(args[2]);
         return path ? { verb: "display-image", path, ...withSlug } : null;
       }
+      case "desktop":
+        return { verb: "display-desktop" };
       case "preview": {
         const path = drivePath(args[2]);
         return path ? { verb: "display-preview", path } : null;
@@ -700,6 +728,8 @@ export function createDisplayPromoter(ctx: DisplayPromoterContext = {}): Display
           return call("display_plan", {});
         case "display-image":
           return call("display_image", { path: invocation.path, ...factoryRef(invocation.factorySlug) });
+        case "display-desktop":
+          return call("display_desktop", {});
         case "display-preview":
           return call("display_preview", { path: invocation.path, ...factoryRef(undefined) });
         case "display-table":
@@ -789,6 +819,19 @@ export function createDisplayPromoter(ctx: DisplayPromoterContext = {}): Display
             ...factoryRef(m?.factorySlug ?? inv.factorySlug),
           })];
         }
+        case "display-desktop": {
+          // No marker → the capture failed before it could name a file —
+          // keep the raw output (the CLI's own error is the feedback);
+          // a desktop card without a snapshot would lie.
+          const marker = findDisplayMarker(text);
+          if (marker?.kind !== "desktop") return [result(msg.output)];
+          return [result({
+            path: marker.path,
+            ...factoryRef(marker.factorySlug),
+            capturedAt: marker.capturedAt ?? null,
+            note: marker.note ?? null,
+          })];
+        }
         case "display-table": {
           // File-sourced tables are a DIRECTIVE: keep the raw output so the
           // marker inside it reaches the cloud executor (the real card pair).

package/src/index.ts

@@ -24,8 +24,10 @@ export type {
   AgentRuntime,
   McpServerConfig,
   ModelExecutionContract,
+  RunnerLivenessVerdict,
   ToolCallGateResult,
   RuntimeOptions,
+  TurnExitNotify,
 } from "./types/runtime.js";
 
 // Workflow types and runtime utilities
@@ -98,6 +100,7 @@ export type {
   AgentMessageDone,
   AgentMessageError,
   AgentMessageUsage,
+  AgentMessageTaskNotification,
   AgentStatus,
 } from "./types/protocol.js";
 
@@ -117,15 +120,16 @@ export type {
   InlineWorkflowPayload, InvokeInlineOptions, InvokeInlineAndWaitOptions,
   ListSnapshotsOptions, TemplateRow, ListTemplatesOptions,
   CreateFactoryInput, UpdateFactoryInput,
-  SecretOptions, SetSecretResult, SecretListEntry,
+  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,
+  ApiKey, ApiKeyCreated, ListApiKeysOptions, ApiKeyPage,
   UsageRollupRow, UsageResponse,
   CancelRunResponse,
   RequestAgentPauseOptions, RequestAgentPauseResponse,
@@ -135,18 +139,28 @@ export type {
   ConversationMessagePart, ConversationRow, ConversationMessageRow,
   ConversationsPage, ConversationDetail, ConversationThread,
   ConversationPageContext, SendConversationMessageInput, SendConversationMessageResult,
+  UnnotifiedMention,
   ConversationTurnState, ConversationPresenceSnapshot, StreamConversationOptions, AgentListRow,
   CreateCloudSessionInput, CloudSessionCreated,
   // Cloud-session developer surface (ADR-0052)
-  SessionPreview, PreviewOpened, OpenPreviewInput, SessionForked,
+  SessionPreview, PreviewOpened, OpenPreviewInput, SessionForked, BackgroundWorkHeld,
   // Session branch proposals (ADR-0053)
-  SessionFileChange, SessionChangeSet,
-  SessionMergeReportDetail, SessionMergeReport, SessionDiscardReport,
+  SessionFileChange, SessionChangeSet, SessionChangeStats, SessionDiffReviewBound, ReviewSuggestion,
+  ReviewSuggestionInput, ReviewNotesPublished, ReviewGitCredential, SessionReviewDocument,
+  ReviewSuggestionDecision, ReviewSuggestionDecisions,
+  SessionMergeReportDetail, SessionMergeReport, SessionMergeGated, SessionDiscardReport,
+  SessionPreflightFileRow, SessionChangePreflight, SessionRebaseReport,
   // User drive mounts (`agentc files mount` on a human's own machine)
   DriveMountSession, CreateDriveMountSessionInput,
   // Channel-attached sessions (ADR-0057)
   ChannelSessionStatus, ChannelSessionRow, ChannelSessionsResponse, SessionChannelMessagePosted,
+  // Session→session messaging + branch claims
+  SessionDirectMessageSent, BranchClaimInfo, BranchClaimGranted, BranchClaimsReleased, BranchClaimState,
+  // Sandbox perf history (session_perf_rollups)
+  SessionPerfBucket, SessionPerfHistoryPage, FactoryPerfSummary,
   FactoryFileSearchRow, FactoryFolderSearchRow, SearchFactoryFilesOptions, FactoryFileSearchResult, PublicFileLinkState,
+  // Drive file listing (live + browse-at-head)
+  FactoryFileListRow, ListFactoryFilesOptions, FactoryFileListPage,
   // Membership-scoped authorization (ADR-0045)
   ConversationMemberRole, ConversationMember,
   DocumentCapability, TemplateCapability, ScopeGrant, ArtifactScope,
@@ -243,6 +257,33 @@ export type { CodexRuntimeConfig, CodexReasoningEffort } from "./runtimes/codex.
 export { default as codexRuntime } from "./runtimes/codex.js";
 // Reasoning-effort level a CLI runtime turn may carry (claude-code / codex).
 export type { CliReasoningEffort } from "./runtimes/_cli-agent.js";
+// Guest durable-plane helpers (ADR-0068): the server-side CloudTurnWorkflow
+// activities launch/probe/tail the SAME durable trio the CLI-agent transport
+// writes, so the shell fragments and probe parsers are shared — one source
+// of truth for the guest file contract. Server-side consumers only (these
+// modules read process.env at load; never import them into a workflow VM).
+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";
+// Guest perf sampling (the `.perf` token contract riding the durable trio).
+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";
@@ -278,8 +319,11 @@ export { createSandbox, reconnectSandbox, killAllSandboxes, killSandboxById,
   getSandboxQuotas, listOwnedSandboxes, deleteSandboxSnapshot, snapshotResolves,
   makeSandboxProvider, makeDesktopSandboxProvider,
   parseSseExecStream, AGENT_COMPOSE_TAG,
-  SANDBOX_VCPUS, DEFAULT_SANDBOX_SIZE, E2B_TEMPLATE_SIZES,
-  isE2bSupportedSize, e2bMachineSpec, e2bBaseTemplate, e2bAgentEnvTemplate,
+  SANDBOX_SIZES, SANDBOX_MACHINES, SANDBOX_VCPUS, DEFAULT_SANDBOX_SIZE, SESSION_DEFAULT_SANDBOX_SIZE,
+  E2B_TEMPLATE_SIZES, E2B_MAX_VCPUS, E2B_MAX_MEMORY_MB,
+  VERCEL_MEMORY_MB_PER_VCPU,
+  isE2bSupportedSize, isVercelSupportedSize, sandboxSizeLabel,
+  e2bMachineSpec, e2bBaseTemplate, e2bAgentEnvTemplate,
   isPlatformE2bTemplateAlias,
   // ADR-0038 "Computer" — the per-member persistent desktop machine template.
   E2B_DEVBOX_TEMPLATE, E2B_DEVBOX_SPEC, E2B_DEVBOX_RECIPE_VERSION,
@@ -382,6 +426,28 @@ 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";
+// Durable services manifest (.ac/services.yml) — the machine is cattle, the
+// manifest is the pet. Shared by the server's fresh-boot auto-restore, the
+// resize pre-kill dump hook, and `agentc services`.
+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";
 
@@ -393,6 +459,7 @@ export {
   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,