@agent-compose/sdk 0.6.0 → 0.8.0

package/dist/types/api-factory.d.ts

@@ -0,0 +1,309 @@
+/**
+ * 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;
+}
+/** 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;
+}
+/** 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/dist/types/api-projects.d.ts

@@ -0,0 +1,131 @@
+/**
+ * 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[];
+}