@agent-compose/sdk 0.6.0 → 0.8.0

package/src/types/api-factory.ts

@@ -0,0 +1,336 @@
+/**
+ * Factory-facing wire types for `AgentComposeClient` — template
+ * registration, factories, drive files, schedules, secrets, API keys,
+ * and usage.
+ *
+ * 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 { SnapshotConfig, IOSchema, ConnectorRequirements, ConnectorOperationTag, InvokePolicy, SandboxResources, DriveMergePolicy } from "./workflow-metadata.js";
+import type { WorkflowPlan } from "./workflow-plan.js";
+import type { WorkflowManifest } from "../utils/bundler.js";
+import type { ArtifactScope } from "./api-scopes.js";
+
+export interface RegisterResult {
+  id: string;
+  name: string;
+  version: string;
+  runtimes?: RegisteredRuntime[];
+}
+
+export interface RegisteredRuntime {
+  id: string;
+  name: string;
+  version: string;
+}
+
+export interface RuntimeSourceInput {
+  name: string;
+  source: string;
+}
+
+/** GitHub provenance for a registered template's source file — stored as
+ *  `metadata.source` on the registration. `cloud-build` stamps the built
+ *  commit's sha; the dashboard's manual link path writes `sha: "manual"`. */
+export interface TemplateSourceRef {
+  owner:  string;
+  repo:   string;
+  branch: string;
+  /** Repo-relative file path, e.g. `.agentc/workflows/workflow-deploy.ts`. */
+  path:   string;
+  /** Commit sha the version was built from, or `"manual"` for hand-links. */
+  sha:    string;
+}
+
+export interface RegisterWorkflowInput {
+  name: string;
+  source: string;
+  /** Structured attestation produced by `bundleWorkflow`. The server
+   *  requires this on every registration; it proves the source was
+   *  bundled by a `defineWorkflow`-aware toolchain. The server validates
+   *  the manifest's shape and verifies `manifest.sourceHash` matches
+   *  sha256(source) — the source bytes themselves are never parsed or
+   *  executed on the server. */
+  manifest: WorkflowManifest;
+  version?: string;
+  /** Where the source file lives on GitHub — stored as `metadata.source`.
+   *  Named `sourceRef` because `source` is the bundled code itself. */
+  sourceRef?: TemplateSourceRef;
+  schedule?: string;
+  runtimes?: RuntimeSourceInput[];
+  /** Human-readable description declared via
+   *  `defineWorkflow({ description })`. Stored in template metadata and
+   *  surfaced on the dashboard template card. */
+  description?: string;
+  networkPolicy?: unknown;
+  placeholders?: Record<string, string>;
+  /** All snapshot config — `bootFrom` (where to restore at run start),
+   *  `save`, `retain`. See `WorkflowMetadata.snapshots`. */
+  snapshots?: SnapshotConfig;
+  /** Sandbox machine resources — size + provider (template defaults).
+   *  See `WorkflowMetadata.resources`. */
+  resources?: SandboxResources;
+  /** Run-branch merge policy declared via `defineWorkflow({ mergePolicy })`.
+   *  Omitted ⇒ `"auto"` on the server (today's behaviour) — see
+   *  `WorkflowMetadata.mergePolicy`. */
+  mergePolicy?: DriveMergePolicy;
+  /** Provider-neutral execution plan detected by the CLI bundler. */
+  workflowPlan?: WorkflowPlan;
+  /** Connector requirements declared via `defineWorkflow({ connectors })`
+   *  (ADR-0007). Validated against the server's provider registry at
+   *  registration; tokens are injected at the network layer at dispatch. */
+  connectors?: ConnectorRequirements;
+  /** Connector-catalogue operation tag — see `ConnectorOperationTag`. */
+  connectorOperation?: ConnectorOperationTag;
+  /** Tier-1 invoke ACL declared via `defineWorkflow({ invokePolicy })`.
+   *  Only meaningful when the workflow also declares `connectors` — the
+   *  server gates dispatch on it before binding any grant. */
+  invokePolicy?: InvokePolicy;
+  /** Input schema extracted from the workflow's `input` zod schema. */
+  inputSchema?: IOSchema;
+  /** Output schema extracted from the workflow's `output` zod schema. */
+  outputSchema?: IOSchema;
+  /** Set by `defineSandboxEnvironment` — marks an environment build so the
+   *  server skips the /factory mount for its runs (#13). See
+   *  `WorkflowMetadata.environmentBuild`. */
+  environmentBuild?: boolean;
+  /** Factory slug. Defaults to `"default"`. */
+  factorySlug?: string;
+}
+
+export interface TemplateRow {
+  name: string;
+  version: string;
+  factorySlug: string;
+  /** Share scope (ADR-0045) — `null` = unscoped/grandfathered team tier. */
+  scope: ArtifactScope | null;
+}
+
+/** Template detail (`GET /factories/:slug/templates/:name`) — the typed
+ *  subset the SDK pins; the route returns additional registration fields
+ *  (contentHash, metadata timestamps) that flow through untyped. */
+export interface TemplateDetail {
+  id: string;
+  name: string;
+  version: string;
+  factorySlug: string;
+  metadata: Record<string, unknown>;
+  /** `factory` = registered in this factory; `published` = platform
+   *  template (fixed team-wide read+invoke, never write). */
+  origin: "factory" | "published";
+  /** Share scope (ADR-0045) — `null` = unscoped/grandfathered team tier. */
+  scope: ArtifactScope | null;
+}
+
+export interface ListTemplatesOptions {
+  factorySlug?: string;
+}
+
+// ── Factory-file search (wire shape mirrors routes/factory-files.ts) ────────
+
+/** Public "anyone with the link" state — the additive `public` field on file
+ *  rows (list/ls/search). The token is the whole capability, so an enabled
+ *  row carries it ONLY for viewers holding the document's share authority
+ *  (scope owner / internal); everyone else — read-only grantees, session
+ *  toolbelt keys — gets the token-less badge. The PUT /files/public-link
+ *  response (share-gated) always carries it. Files/docs only — sessions
+ *  never go public (ADR-0052). */
+export type PublicFileLinkState = { enabled: true; token?: string } | { enabled: false };
+
+export interface FactoryFileSearchRow {
+  id: string;
+  path: string;
+  sizeBytes: number;
+  contentType: string | null;
+  contentHash: string;
+  deletedAt: string | null;
+  createdAt: string;
+  updatedAt: string;
+  /** Opening slice (≤320 chars) of the extracted text; null for binary. */
+  preview: string | null;
+  /** Share scope (ADR-0045) — `null` = unscoped/team tier. Optional: file
+   *  list payloads gain it as the server's document surfaces land. */
+  scope?: ArtifactScope | null;
+  /** Public link state — additive beside `scope` (a link exists on scoped
+   *  and unscoped files alike). Absent on payloads that predate the field. */
+  public?: PublicFileLinkState;
+}
+
+export interface SearchFactoryFilesOptions {
+  factorySlug?: string;
+  limit?: number;
+  /** Path cursor from a prior page's `next_cursor`. */
+  cursor?: string;
+}
+
+/** One DIRECTORY hit on `/files/search` — a distinct dir prefix (any depth)
+ *  whose leaf segment matches the query, derived server-side from paths the
+ *  viewer can see. Mirrors the `/files/ls` folders shape. */
+export interface FactoryFolderSearchRow {
+  name: string;
+  path: string;
+  file_count: number;
+  total_size: number;
+  last_updated: string;
+}
+
+export interface FactoryFileSearchResult {
+  object: "list";
+  data: FactoryFileSearchRow[];
+  has_more: boolean;
+  next_cursor: string | null;
+  /** Directory hits (first page only — a `cursor` call pages FILES and
+   *  answers `[]`). Optional: absent on payloads that predate the field. */
+  folders?: FactoryFolderSearchRow[];
+  /** True when more directories matched than the server's folder bound. */
+  folders_truncated?: boolean;
+}
+
+export interface FactoryFileWriteResult {
+  path: string;
+  contentHash: string;
+  sizeBytes: number;
+  created: boolean;
+}
+
+/** A factory: a project-level grouping of workflows inside a team. */
+export interface FactoryRow {
+  id:          string;
+  teamId:      string;
+  slug:        string;
+  name:        string;
+  description: string | null;
+  createdAt:   string;
+  updatedAt:   string;
+}
+
+export interface CreateFactoryInput {
+  slug: string;
+  name: string;
+  description?: string;
+}
+
+export interface UpdateFactoryInput {
+  name?: string;
+  description?: string;
+}
+
+export interface ScheduleRow {
+  id:           string;
+  name:         string;
+  workflowName: string;
+  cron:         string;
+  createdAt:    string;
+  updatedAt:    string;
+  nextFireAt:   string | null;
+  lastFireAt:   string | null;
+}
+
+export interface CreateScheduleInput {
+  /** Human-friendly schedule name. Unique within the factory. */
+  name:         string;
+  /** The workflow this schedule should fire. Must already be registered
+   *  in the same factory. */
+  workflow:     string;
+  /** Cron expression (UTC). */
+  cron:         string;
+  /** Factory to attach the schedule to. Defaults to `"default"`. */
+  factorySlug?: string;
+}
+
+export interface SecretOptions {
+  factorySlug?: string;
+}
+
+export interface SetSecretResult {
+  key: string;
+}
+
+export interface SecretListEntry {
+  key: string;
+  createdAt: string;
+  updatedAt: string;
+}
+
+export interface CreateApiKeyInput {
+  name?:        string;
+  scopes?:      string[];
+  expiresAt?:   string;
+  factorySlug?: string;
+}
+
+/** Row shape returned by `GET /api-keys`. */
+export interface ApiKey {
+  object:           "api_key";
+  id:               string;
+  name:             string | null;
+  last4:            string | null;
+  scopes:           string[];
+  teamId:           string;
+  createdByUserId:  string | null;
+  /** Non-null when the key is restricted to a single factory. */
+  factoryId:        string | null;
+  createdAt:        string;
+  expiresAt:        string | null;
+  lastUsedAt:       string | null;
+  revokedAt:        string | null;
+}
+
+/** Response from `POST /api-keys`. The `key` field is the plaintext token —
+ *  shown once at creation, never retrievable again. */
+export interface ApiKeyCreated extends ApiKey { key: string }
+
+/** Single rollup row from `GET /api/v1/usage`. */
+export interface UsageRollupRow {
+  eventType: string;
+  unit:      string;
+  total:     number;
+  tags:      Record<string, unknown>;
+}
+
+/** Response from `GET /api/v1/usage`. */
+export interface UsageResponse {
+  object:   "list";
+  data:     UsageRollupRow[];
+  has_more: boolean;
+  from:     string | null;
+  to:       string | null;
+}
+
+// ── GitHub-linked drive directories (ADR-0030 P1) ───────────────────────────
+
+/** One drive-directory ⇄ GitHub-repo link (`/factories/:slug/repo-links`).
+ *  The webhook secret ref is operator plumbing and never on the wire. */
+export interface DriveRepoLink {
+  id:            string;
+  factoryId:     string;
+  /** Linked directory prefix under the drive root (relative, no slashes
+   *  at either end). Unique per factory; overlaps are rejected. */
+  dirPrefix:     string;
+  provider:      string;
+  /** "org/repo". */
+  repoFullName:  string;
+  /** The GitHub branch drive `main` syncs with. */
+  trackedBranch: string;
+  connectorGrantId: string | null;
+  /** v1 links are always 'write' (the round trip is the feature). */
+  access:        "read" | "write";
+  lastSyncedGitSha:    string | null;
+  lastSyncedAcgCommit: string | null;
+  syncState:     "idle" | "syncing" | "diverged" | "reauth_required";
+  visibility:    "team" | "restricted";
+  createdBy:     string | null;
+  lastSyncedAt:  string | null;
+  createdAt:     string;
+}
+
+/** Input for `POST /factories/:slug/repo-links`. Requires the drive to be
+ *  graph-authoritative (ADR-0058 Phase 4 promoted) — 409 otherwise. */
+export interface CreateDriveRepoLinkInput {
+  dirPrefix:     string;
+  repoFullName:  string;
+  trackedBranch: string;
+  connectorGrantId: string;
+  visibility?:   "team" | "restricted";
+}

package/src/types/api-projects.ts

@@ -0,0 +1,140 @@
+/**
+ * Projects wire types (ADR-0045 projects extension).
+ *
+ * A project is a member-gated group (roles `owner > write > read`, mirroring
+ * conversation rosters) that also holds a collection of objects — factory
+ * files, conversations, and sessions (kind='session' conversations). Membership ⊆
+ * visibility: every project member sees every project object. Access is
+ * DERIVED (grant rows keyed `principal='project'`), never promoted into a
+ * personal scope — it exists only while `(member ∈ project) ∧ (object ∈
+ * project)`.
+ *
+ * Wire shapes are pinned tri-party: the server routes, this SDK, and the
+ * dashboard's own thin client update together. The dashboard NEVER imports
+ * the SDK — it mirrors these shapes over its own fetch wrapper.
+ */
+
+/** Project role ladder — `owner > write > read`. `read` sees the project and
+ *  every object in it; `write` additionally administers (rename, invite as
+ *  write/read, add/remove objects); `owner` additionally re-roles members and
+ *  deletes the project. Roles gate ADMINISTRATION only — never visibility. */
+export type ProjectRole = "owner" | "write" | "read";
+
+/** One project, as the caller sees it. `role` is the caller's own role;
+ *  `createdBy` is provenance/display only (there is NO implicit creator
+ *  authority — authority is the member row exclusively). */
+export interface Project {
+  id: string;
+  name: string;
+  createdBy: string | null;
+  createdAt: string;
+  updatedAt: string;
+  role: ProjectRole;
+  memberCount: number;
+  objectCount: number;
+}
+
+/** A page of projects, newest-activity first. Cursor-paginated: pass the
+ *  previous page's `next_cursor` (null when exhausted). */
+export interface ProjectsPage {
+  projects: Project[];
+  next_cursor: string | null;
+}
+
+/** One human member of a project (roster row), with display identity merged
+ *  in server-side. */
+export interface ProjectMember {
+  userId: string;
+  role: ProjectRole;
+  name: string | null;
+  email: string | null;
+  addedBy: string | null;
+  createdAt: string;
+}
+
+/** One object referenced by a project — a LIVE link (grant row), never a
+ *  copy/snapshot. Files are id-keyed (renames ride along); conversations and
+ *  sessions are both keyed by `conversationId` (sessions ARE conversations
+ *  with `kind='session'`). */
+export type ProjectObject =
+  | {
+      id: string;
+      type: "file";
+      fileId: string;
+      path: string;
+      factorySlug: string;
+      /** True once the file carries an artifact scope; unscoped files are
+       *  ref-only (grandfathered team-visible) until scoped. */
+      scoped: boolean;
+      addedBy: string | null;
+      /** Non-null when this file row was MATERIALIZED as part of a session
+       *  add (it points at the session object row); null = directly added. */
+      addedViaObjectId: string | null;
+      createdAt: string;
+    }
+  | {
+      id: string;
+      type: "conversation" | "session";
+      conversationId: string;
+      title: string | null;
+      kind: "chat" | "session";
+      executor: "local" | "cloud" | null;
+      /** Resolved session model (per-session override, else the hosting
+       *  agent's default) — lets clients render a provider mark from the
+       *  object row itself. Null for chat conversations. */
+      model: string | null;
+      addedBy: string | null;
+      createdAt: string;
+    };
+
+/** A page of project objects. Cursor-paginated (created_at DESC, id ASC). */
+export interface ProjectObjectsPage {
+  objects: ProjectObject[];
+  next_cursor: string | null;
+}
+
+/** One file the caller could NOT contribute to a project when adding a
+ *  session — only files the caller OWNS are materialized. `path` is present
+ *  only when visible to the caller; paths concealed from the caller are
+ *  silently omitted (never disclosed, not even counted). */
+export interface ProjectSkippedFile {
+  path: string;
+  reason: "not_owner";
+}
+
+/** One file that WOULD be materialized (shared into the project) by adding a
+ *  session. */
+export interface ProjectPreviewFile {
+  fileId: string;
+  path: string;
+  factorySlug: string;
+}
+
+/** The dry-run result of a session add — powers the consent dialog's
+ *  expandable file list + skipped line. No mutation, no audit, no push. */
+export interface ProjectAddPreview {
+  files: ProjectPreviewFile[];
+  skipped: ProjectSkippedFile[];
+}
+
+/** Body for adding one object to a project. Conversations/sessions carry a
+ *  `conversationId`; files carry a drive `path` (+ optional factory). The
+ *  server derives the true object type from `conversations.kind` and rejects
+ *  a mismatched declared `type` (400 `object_kind_mismatch`). */
+export type AddProjectObjectInput =
+  | { type: "conversation" | "session"; conversationId: string }
+  | { type: "file"; path: string; factorySlug?: string };
+
+/** Result of adding an object. A session add returns the session object plus
+ *  the file objects materialized from the caller's owned scopes, and reports
+ *  any owned-but-skipped entries. */
+export interface AddProjectObjectResult {
+  objects: ProjectObject[];
+  skipped?: ProjectSkippedFile[];
+}
+
+/** Result of re-materializing a session object's file context (add-only). */
+export interface RefreshProjectObjectResult {
+  objects: ProjectObject[];
+  skipped: ProjectSkippedFile[];
+}