@agent-compose/sdk 0.6.0 → 0.8.0

package/src/types/api-runs.ts

@@ -0,0 +1,412 @@
+/**
+ * Run-facing wire types for `AgentComposeClient` — invocation, status,
+ * pause/steer control, run detail/listing, lifecycle events, logs,
+ * artifacts, and snapshots.
+ *
+ * These are deliberate contract pins mirrored in `dashboard/src/lib/api.ts`;
+ * when the server changes a response shape, both update in the same change.
+ */
+
+import type { SandboxNetworkPolicy, SandboxSize } from "../sandbox.js";
+import type { SnapshotConfig } from "./workflow-metadata.js";
+import type { RunContext } from "./api-scopes.js";
+
+export type RunState = "running" | "success" | "failed" | "abandoned" | "canceled";
+
+export interface InvokeWorkflowOptions {
+  /** Per-invocation snapshot config override. `snapshots.bootFrom`
+   *  replaces the template's boot source; `snapshots.saveLatest` and
+   *  `snapshots.retainSteps` override capture mode. Anything omitted
+   *  falls back to the template's registered default. */
+  snapshots?: SnapshotConfig;
+  /** Per-invocation network policy override. Replaces the template-level
+   *  policy for this run only — registered metadata is not mutated. */
+  networkPolicy?: SandboxNetworkPolicy;
+  /** Per-invocation placeholder override. Maps secret names referenced in
+   *  `networkPolicy` ($VAR) to the values the runner should see for env
+   *  vars after brokering. Replaces the template-level placeholders for
+   *  this run only — registered metadata is not mutated. */
+  placeholders?: Record<string, string>;
+  /** Per-invocation machine-size override of the template's `resources.size`.
+   *  `small` (default) | `medium` | `large`; omit → the template default,
+   *  else `small`. Honoured on Vercel (→ vCPUs); E2B ignores it. */
+  size?: SandboxSize;
+  /** Explicit parent run id. Pass `null` to suppress ambient RUN_ID auto-detection. */
+  parentRunId?:  string | null;
+  /** Agent loop inside the parent run that caused this invoke, when applicable. */
+  agentId?:      string | null;
+  /** Factory slug. Defaults to `"default"`. */
+  factorySlug?:  string;
+  /** Idempotency key — sent as the `Idempotency-Key` header. A repeat invoke
+   *  with the same key inside the server's dedup window returns the original
+   *  run instead of starting a new one (matches `resumePause`'s pattern). */
+  idempotencyKey?: string;
+}
+
+export interface InvokeAndWaitOptions extends InvokeWorkflowOptions {
+  timeoutMs?:      number;
+  pollIntervalMs?: number;
+}
+
+export interface InvokeResult {
+  id: string;
+}
+
+export interface StreamRunLogsOptions {
+  lastEventId?: number;
+  signal?: AbortSignal;
+}
+
+export interface RunStatus<TOutput = unknown> {
+  id: string;
+  status: RunState;
+  output?: TOutput;
+  /** The run's latest (`saveLatest`) snapshot id, populated once the run has
+   *  succeeded — the boot source to fork this run's evolved filesystem from
+   *  (pass as `snapshots.bootFrom` on a follow-up invoke). `null` while the run
+   *  is still in flight or when it captured no snapshot. Lets an orchestrator
+   *  fork a child straight off the `invokeChild` result without a separate
+   *  `listRunSnapshots` call. */
+  latestSnapshotId?: string | null;
+}
+
+/** ADR-0006 step 10 — actor record returned on a successful resume.
+ *  Shape mirrors the server's `PauseResumeActor` type after the row
+ *  has been stamped. Audit FKs (`userId` / `keyId` / `runId`) may be
+ *  null when the referenced row was deleted between resume and the
+ *  response render — the immutable `label` survives. */
+export interface ResumePauseActor {
+  kind:     "session_user" | "api_key" | "agent";
+  /** Better Auth user id when kind='session_user'. */
+  userId?:  string | null;
+  /** api_keys.id when kind='api_key'. */
+  keyId?:   string | null;
+  /** Caller-run id when kind='agent' (NOT the run being resumed). */
+  runId?:   string | null;
+  /** Agent-instance within `runId` when kind='agent'. */
+  agentId?: string | null;
+  label:    string;
+}
+
+/** Success branch of the resume HTTP response. The pause has reached
+ *  a terminal state — `resolved` (workflow signal arrived), `expired`
+ *  (TTL fired first), or `cancelled` (workflow terminated mid-pause).
+ *  Only `resolved` carries the resume payload the user supplied. */
+export interface ResumePauseSuccess {
+  status:        "resolved" | "expired" | "cancelled";
+  pauseId:       string;
+  resolvedAt:    string | null;
+  resumePayload: unknown;
+  actor:         ResumePauseActor | null;
+}
+
+/** Pending branch — the workflow accepted the signal but the row
+ *  flip didn't observe within the route's 5s wait window. The
+ *  operation is in-flight; retry with the same `Idempotency-Key`
+ *  and the cache collapses the duplicate to a single canonical
+ *  response. */
+export interface ResumePausePending {
+  status:   "pending";
+  pauseId:  string;
+  timedOut: true;
+}
+
+export type ResumePauseResponse = ResumePauseSuccess | ResumePausePending;
+
+export interface ResumePauseOptions {
+  /** Stripe-style retry-dedup key — same syntax as the workflow-invoke
+   *  route: 1..255 chars of `[A-Za-z0-9_\-:.]`, no embedded CR/LF.
+   *  Sent as the `Idempotency-Key` request header. (The server reads the
+   *  header first, falling back to a body field for callers behind a
+   *  header-stripping proxy; this client only sends the header.) */
+  idempotencyKey?: string;
+  /** Abort the HTTP request mid-wait (e.g. from a UI cancel button).
+   *  The server's LISTEN tears down via the request's AbortSignal. */
+  signal?:         AbortSignal;
+}
+
+export interface RequestAgentPauseOptions {
+  /** Human-readable note surfaced to the agent as the pause reason. */
+  reason?:         string;
+  /** Your handle for answering this pause without the minted pauseId:
+   *  pass the same value to `resumePauseByKey`. */
+  correlationKey?: string;
+  /** Abort the HTTP request. */
+  signal?:         AbortSignal;
+}
+
+export interface AnswerSteerOptions extends ResumePauseOptions {
+  /** Who answered — surfaced to the agent as `[human steer from <actor>]`. */
+  actor?: string;
+}
+
+/** 202 envelope from a steer-pause request. The request is best-effort and
+ *  fire-and-forget: it publishes a transient control message and returns
+ *  immediately — the agent parks at its next iteration boundary (if it is
+ *  `mode: "hitl"` and still running). Answer it via `answerSteerByKey`
+ *  (pass the `correlationKey` you set here) or `answerSteer` (by pauseId). */
+export interface RequestAgentPauseResponse {
+  status:  "steer_requested";
+  runId:   string;
+  agentId: string;
+}
+
+export interface SendAgentMessageOptions {
+  /** Transcript attribution. For non-session callers (API key, orchestrator)
+   *  this names the sender; defaults to the caller's identity server-side. */
+  senderName?: string;
+  /** Abort the HTTP request. */
+  signal?:     AbortSignal;
+}
+
+/** 202 envelope from a message-to-running-agent request. The message is queued
+ *  durably and delivered mid-stream as the agent's next user turn — the workflow
+ *  is NOT paused. `seq` is the message's per-run ordinal. */
+export interface SendAgentMessageResponse {
+  status:  "message_enqueued";
+  runId:   string;
+  agentId: string;
+  seq:     number;
+}
+
+export interface RunDetail<TOutput = unknown> {
+  runId: string;
+  title: string;
+  metadata: Record<string, unknown>;
+  outcome: string;
+  startedAt: string;
+  endedAt: string | null;
+  durationMs: number | null;
+  failureReason: string | null;
+  input: unknown;
+  output: TOutput | null;
+  /** Call context (ADR-0045 §3) — both ids null = team-visible ("Team");
+   *  UI labels private runs "Only you" / "#channel-name". */
+  context: RunContext;
+  lifecycleEvents: Array<{ at: string; type: string; payload: unknown }>;
+  children?: RunDetail[];
+}
+
+/** The funding-lane vocabulary: 'platform' (gateway-metered), 'byok'
+ *  (author's own key), 'subscription' (the initiating user's connected
+ *  plan). */
+export type FundingLane = "platform" | "byok" | "subscription";
+
+/** One per-(step, credential) funding-lane stamp (ADR-0048), recorded at
+ *  credential resolution — `GET /workflows/:id/funding`. Attribution only:
+ *  non-platform lanes are the user's own money and are never metered. */
+export interface RunFundingStamp {
+  stepIndex: number;
+  /** Env-var name (or auth-file path) the sandbox read the credential from. */
+  envVar: string;
+  /** Provider family — 'anthropic' | 'openai' | 'openrouter' | … */
+  provider: string;
+  lane: FundingLane;
+  /** Platform lane only — the gateway virtual key's alias. */
+  keyAlias: string | null;
+}
+
+/** One (provider, model) usage group of the run's gateway-attested platform
+ *  cut — the ONLY usage the ledger records. */
+export interface RunFundingUsageRow {
+  provider: string;
+  model: string;
+  promptTokens: number;
+  completionTokens: number;
+  cacheReadTokens: number;
+  cacheCreationTokens: number;
+  calls: number;
+}
+
+/** `GET /workflows/:id/funding` — the run's funding-lane surface: per-step
+ *  lane stamps (recorded at resolution, never re-detected) and the run's
+ *  gateway-attested platform dollars. Empty `stamps` = the run predates
+ *  lane stamping. */
+export interface RunFundingResponse {
+  object: "run.funding";
+  runId: string;
+  stamps: RunFundingStamp[];
+  stampsTruncated: boolean;
+  attested: {
+    totalUsd: number;
+    rows: Array<RunFundingUsageRow & { costUsd: number }>;
+    truncated: boolean;
+  };
+}
+
+/** One row from the factory runs list (`GET /factories/:slug/runs`) — the
+ *  summary shape, a strict subset of what the route returns. */
+export interface RunListEntry {
+  runId: string;
+  title: string;
+  /** System-stamped bag; `_workflow` names the registered workflow. */
+  metadata: Record<string, unknown>;
+  outcome: string;
+  paused: boolean;
+  startedAt: string;
+  endedAt: string | null;
+  durationMs: number | null;
+  failureReason: string | null;
+  /** Call context (ADR-0045 §3) — both ids null = team-visible ("Team"). */
+  context: RunContext;
+}
+
+export interface ListRunsOptions {
+  /** Factory the runs live in. Defaults to "default". */
+  factorySlug?: string;
+  /** Substring match on the registered workflow name (`metadata._workflow`). */
+  workflow?: string;
+  /** Substring match across title / task title / branch / run id. */
+  search?: string;
+  outcome?: string;
+  sort?: "newest" | "oldest" | "fastest" | "slowest";
+  limit?: number;
+}
+
+export interface TimelineEvent {
+  kind: string;
+  at: string;
+  seq: number;
+  type: string;
+  payload: Record<string, unknown>;
+}
+
+export type EventSubjectType = "run" | "agent" | "workflow" | "factory";
+
+export interface EventRow {
+  id: string;
+  teamId: string;
+  subjectType: EventSubjectType | string;
+  subjectId: string;
+  runId: string | null;
+  agentId: string | null;
+  workflowId: string | null;
+  factoryId: string | null;
+  name: string;
+  body: unknown;
+  summary: string | null;
+  confidence: string | null;
+  timestamp: string;
+  attributes: Record<string, unknown>;
+  propagate: boolean;
+  idempotencyKey: string | null;
+  createdAt: string;
+}
+
+// The server emits these rows in snake_case; the client maps them to
+// camelCase at the fetch boundary so the SDK surface stays uniform
+// (`EventRow.createdAt`, `RunStatus.latestSnapshotId`, …).
+export interface RunArtifactRow {
+  path: string;
+  factorySlug: string | null;
+  sizeBytes: number | null;
+  lastWriteAt: string;
+  /** Opening text of the file (≤320 chars) — null for binary/empty. */
+  preview: string | null;
+}
+
+export interface ReportEventInput {
+  name: string;
+  body: unknown;
+  summary?: string;
+  confidence?: number;
+  timestamp?: string | Date;
+  attributes?: Record<string, unknown>;
+  propagate?: boolean;
+  idempotencyKey?: string;
+}
+
+export interface ListEventsOptions {
+  factorySlug?: string;
+  limit?: number;
+  /** Case-insensitive substring match. Server uses `ILIKE %name%`, so
+   *  `"site"` matches `site.created`, `site.failed`, etc. Pass the
+   *  full event name for an effectively-exact filter (any string is a
+   *  substring of itself). */
+  name?: string;
+  /** Date-range lower bound: only include events at or after this
+   *  timestamp. Used by the dashboard's range toggle (1h / 24h / 7d
+   *  / 30d). Same semantics as `from` on the runs list endpoint. */
+  from?: string;
+  /** Timestamp cursor for "load older" pagination. Pass the
+   *  `timestamp` of the last row from the previous page; the server
+   *  returns rows strictly older than that. Distinct from `from`:
+   *  `from` filters a date range, `before` walks the page boundary.
+   *  Both can be supplied together for a paginated range-query. */
+  before?: string;
+}
+
+export interface ListEventsResult {
+  events:   EventRow[];
+  has_more: boolean;
+}
+
+/** One captured stdout or stderr line from a run's sandbox subprocess.
+ *  `id` is per-run monotonically increasing — pass the highest `id`
+ *  you've seen as `afterId` to paginate forward. */
+export interface RunLogLine {
+  id:     number;
+  at:     string;
+  stream: "stdout" | "stderr";
+  line:   string;
+}
+
+export interface ListRunLogsOptions {
+  /** Return only lines with `id > afterId` (forward pagination). */
+  afterId?: number;
+  /** Max lines (server clamps to [1, 1000], defaults to 200). */
+  limit?:   number;
+  /** Stream direction. `"asc"` (default) returns the oldest lines first
+   *  — use with `afterId` to paginate forward. `"desc"` returns the newest
+   *  lines first — use to fetch the last N lines of a finished run. */
+  direction?: "asc" | "desc";
+}
+
+/** Response from `POST /api/v1/workflows/:id/cancel`. The endpoint is
+ *  idempotent: cancelling a run that's already terminal returns its current
+ *  outcome verbatim (rather than throwing or pretending it just canceled),
+ *  so `status` widens to every terminal value the server might surface. */
+export interface CancelRunResponse {
+  runId:       string;
+  status:      "canceled" | "success" | "failed" | "abandoned";
+  canceledAt:  string;
+}
+
+export interface ListSnapshotsOptions {
+  /** Factory slug. Defaults to `"default"`. */
+  factorySlug?: string;
+  workflow?: string;
+  limit?: number;
+  /** Cursor returned as `next_cursor` from `listSnapshotsPage`. */
+  before?: string;
+}
+
+export interface SnapshotListEntry {
+  snapshotId: string;
+  kind: "latest" | "step";
+  stepIndex: number | null;
+  runId: string;
+  workflow: string | null;
+  version: string | null;
+  createdAt: string | null;
+  /** Provider-reported on-disk size, or null when unavailable. */
+  sizeBytes: number | null;
+}
+
+export interface SnapshotListResponse {
+  object: "list";
+  data: SnapshotListEntry[];
+  has_more: boolean;
+  next_cursor: string | null;
+}
+
+export interface RunSnapshotEntry {
+  snapshotId: string;
+  /** `"latest"` = current/last pointer on the run.
+   *  `"step"` = retained per-step snapshot. */
+  kind: "latest" | "step";
+  stepIndex: number | null;
+  createdAt: string | null;
+  /** Provider-reported on-disk size, or null when unavailable. */
+  sizeBytes: number | null;
+}

package/src/types/api-scopes.ts

@@ -0,0 +1,102 @@
+/**
+ * Membership-scoped authorization wire types (ADR-0045).
+ *
+ * Conversation roles, artifact scopes, and run call-context. Wire shapes are
+ * pinned by docs/specs/membership-authz-contract.md §6 — the server, this
+ * SDK, and dashboard/src/lib/api.ts update together.
+ */
+
+/** Conversation role ladder — `owner > write > read`. `read` sees the
+ *  conversation and everything scoped to it; `write` additionally acts
+ *  (send/react/invite/dispatch); `owner` additionally manages the roster
+ *  and can delete the conversation. */
+export type ConversationMemberRole = "owner" | "write" | "read";
+
+/** One human member of a conversation (channel roster row), with display
+ *  identity merged in server-side. */
+export interface ConversationMember {
+  userId: string;
+  name: string | null;
+  email: string;
+  image: string | null;
+  /** Server-relative uploaded-avatar URL (ADR-0056), when set — takes
+   *  precedence over `image`. Prefix with your API base. */
+  avatarUrl?: string | null;
+  addedBy: string | null;
+  createdAt: string;
+  role: ConversationMemberRole;
+}
+
+/** Document share capabilities. */
+export type DocumentCapability = "read" | "write";
+/** Template share capabilities. Implications are normative server-side:
+ *  `write→read`, `invoke→read`, `see_runs→read`. `see_runs` = may view the
+ *  template's runs (detail, logs, timeline, pauses, artifacts, stream)
+ *  regardless of call context — read-only, never act. */
+export type TemplateCapability = "read" | "write" | "invoke" | "see_runs";
+
+/** One grant on an artifact scope. `team`/`user` are the editable tiers
+ *  carried on a PUT (full-replace); `session`/`project` are DERIVED,
+ *  read-only arms that appear only on READ payloads (the routes that manage
+ *  them own their mutation — a scope PUT rejects them, 400 `invalid_principal`).
+ *
+ *  Session and project grants carry FIXED capabilities `['read','write']`:
+ *  the fs-gateway is concealment-only (no read/write dimension at the mount),
+ *  so any grant that un-conceals a path is read-write for the granted
+ *  session — the API therefore offers no read-only choice for these
+ *  principals and every consent surface says "open and edit". */
+export type ScopeGrant =
+  | { principal: "team"; capabilities: string[] }
+  | { principal: "user"; userId: string; capabilities: string[] }
+  | { principal: "session"; sessionId: string; conversationId: string; capabilities: string[] }
+  | {
+      principal: "project";
+      projectId: string;
+      projectName: string;
+      /** The project_objects row this grant hangs off — the handle the file's
+       *  owner uses to ✕ a "via project" row from the SharePicker without
+       *  being a project member (share implies unshare). Null only for
+       *  transitional/legacy rows. */
+      projectObjectId: string | null;
+      capabilities: string[];
+    };
+
+/** An artifact's share scope (documents and templates — one model).
+ *  On wire payloads `null` = unscoped/grandfathered team tier. A scope row
+ *  with no grants = private to its owner. Platform templates report a fixed
+ *  synthetic `{ grants: [{ principal: 'team', capabilities: ['read','invoke'] }] }`. */
+export interface ArtifactScope {
+  kind: "document" | "template";
+  ownerUserId: string | null;
+  /** Templates only — the owning conversation binding (a grant source:
+   *  members of that conversation reach the template via their role). */
+  conversationId?: string | null;
+  grants: ScopeGrant[];
+}
+
+/** The call context stamped on a run at dispatch (ADR-0045 §3) — the
+ *  anchor of run visibility. Both ids null = the grandfathered
+ *  team-visible tier ("Team"); conversationId set = the channel/session
+ *  the run was dispatched from; otherwise dispatchedByUserId is the
+ *  private floor (the dispatcher, or a key's creator). */
+export interface RunContext {
+  conversationId: string | null;
+  conversationTitle: string | null;
+  dispatchedByUserId: string | null;
+}
+
+/** Share-mutation body — ONE shape for both kinds. `grants` is a
+ *  FULL-REPLACE of the scope's grant list (empty array = private to the
+ *  owner). Capabilities are validated per kind server-side (`read|write`
+ *  for documents; `read|write|invoke|see_runs` for templates; 400 on
+ *  unknown). Mutating a scope requires owner or team admin. */
+export interface SetScopeGrantsInput {
+  grants: ScopeGrant[];
+}
+
+export interface SetTemplateScopeInput extends SetScopeGrantsInput {
+  /** Bind (`uuid`) or unbind (`null`) the owning conversation; omit to
+   *  leave the binding unchanged. Binding requires `owner` role in the
+   *  target conversation. */
+  conversationId?: string | null;
+}