@dharta/cli 0.6.77 → 0.6.78

package/node_modules/@dharta/sdk/src/types.ts

@@ -12,17 +12,23 @@ export const API_KEY_SCOPES = [
   "directories:read",
   "embed_keys:read",
   "env:read",
+  "instance_env:read",
+  "kartas:read",
   "keys:read",
   "members:read",
-  "model_keys:read",
+  "model_connections:read",
   "releases:read",
   "schedules:read",
   "sessions:read",
   "source_repos:read",
   "webhooks:read",
+  "fleet:read",
   "agents:write",
   "appearance:write",
   "env:write",
+  "fleet:write",
+  "instance_env:write",
+  "kartas:write",
   "releases:write",
   "schedules:write",
   "webhooks:write",
@@ -32,34 +38,53 @@ export const API_KEY_SCOPES = [
   "env:secrets:read",
   "source_archives:read",
   "workspace_tokens:create",
+  "workspace:read",
   "audit_log:export",
+  "fleet:subjects:read",
   "members:invite",
   "members:write",
   "members:owner_role:write",
   "agents:delete",
   "keys:write",
-  "model_keys:write",
+  "model_connections:write",
+  "fleet:subjects:write",
+  "fleet:operations:write",
   "billing:read",
+  "organization:write",
+  "organization:support_access:write",
 ] as const;
 
 export type ApiKeyScope = (typeof API_KEY_SCOPES)[number];
 
-export type ModelKeyProvider =
+export type ModelConnectionProvider =
   | "anthropic"
   | "openai"
-  | "bedrock"
-  | "vertex"
   | "openrouter"
   | "xai"
   | "google";
 
-export type ModelApiFormat =
+export type ModelConnectionApiFormat =
   | "anthropic_messages"
   | "openai_chat_completions"
-  | "openai_responses"
+  | "openai_responses";
+
+export type ModelApiFormat =
+  | ModelConnectionApiFormat
   | "bedrock_converse"
   | "vertex_generate_content";
 
+export type ResolvedModelProvider = ModelConnectionProvider | "bedrock" | "vertex";
+export type ResolvedModelCredentialKind = "api_key" | "workload_identity";
+
+// The commercial and protocol access path of a stored connector, derived by
+// the server from `provider` + `credential_kind`. Read-only: you never send it.
+export type ModelAdapterKind =
+  | "anthropic_api"
+  | "openai_api"
+  | "openrouter_api"
+  | "xai_api"
+  | "google_gemini_api";
+
 export type ModelReasoningEffort = "low" | "medium" | "high";
 
 export interface ModelParameters {
@@ -94,13 +119,194 @@ export const WEBHOOK_EVENT_TYPES = [
 
 export type WebhookEventType = (typeof WEBHOOK_EVENT_TYPES)[number];
 
+// The one agent shape every agent mutation returns
+// (Api::Serializers::Agent server-side).
+export interface Agent {
+  id: number;
+  slug: string;
+  name: string;
+  deploy_enabled: boolean;
+  serving_status: string;
+  dashboard_edits_enabled: boolean;
+  workspace_inspectable?: boolean;
+  workspace_access?: Record<string, Record<string, boolean>>;
+  // Whether this agent's kartas write to the durable store. A cost setting.
+  durable_workspace_enabled?: boolean;
+  deploy_branch?: string;
+  archived_at?: string | null;
+  // The agent's STORED model policy, never the resolved one. Read the
+  // resolved route from GET /api/agents/{slug}.
+  model?: {
+    // Which policy `connector_order` expresses. `inherit` is an empty order,
+    // `platform` selects the Dharta platform connector, `connection` selects
+    // one of this organization's own model connections.
+    source: "inherit" | "platform" | "connection";
+    // Non-null exactly when `source` is `connection`.
+    model_connection_id: number | null;
+    parameters: ModelParameters;
+    connector_order: string[];
+    model_reference: string;
+  };
+}
+
+export interface AgentChangeResponse {
+  agent: Agent;
+  // False when the request asked for the value the agent already had.
+  changed: boolean;
+}
+
+export interface Release {
+  // bigint primary key server-side, returned as a JSON number.
+  id: number;
+  version: number;
+  label?: string;
+  status: string;
+  kind?: string;
+  current?: boolean;
+  activatable?: boolean;
+  commit_sha?: string | null;
+  error_message?: string | null;
+  build_kind?: string | null;
+  pushed_via?: string | null;
+  harness_slug?: string | null;
+  harness_version?: string | null;
+  created_at?: string;
+  built_at?: string | null;
+}
+
+export interface AgentCreateParams {
+  // Display name. The slug is derived from it when `slug` is absent. IGNORED
+  // with `githubRepositoryId`: that fork creates a source repo, not an agent,
+  // and the agent names itself from the dharta.toml the sync finds.
+  name?: string;
+  slug?: string;
+  // Link this installed GitHub repository instead of creating an empty hosted
+  // repo. `githubRepositories.list()` returns the ids you may send.
+  githubRepositoryId?: number | string;
+  // Only read with `githubRepositoryId`. The repository's default branch when
+  // absent.
+  deployBranch?: string;
+}
+
+export interface AgentCreateResponse {
+  agent: {
+    id: number;
+    slug: string;
+    name: string;
+    deploy_branch: string;
+  };
+  clone_url: string;
+  created: boolean;
+}
+
+// What the GitHub fork of `POST /api/agents` answers. It links a source repo,
+// so there is no agent yet: one appears when the sync finds a single enabled
+// dharta.toml on the deploy branch.
+export interface AgentLinkGithubResponse {
+  source_repo: {
+    slug: string;
+    deploy_branch: string;
+    github_repository: string;
+    clone_url?: string;
+  };
+  created: boolean;
+}
+
+// One entry of `githubRepositories.list()`: an installed repository, and the
+// `id` to send as `githubRepositoryId`.
+export interface GithubRepository {
+  id: number;
+  full_name: string;
+  default_branch: string;
+  // Always sent: the listing joins the installation, and `linked` is computed
+  // for every row.
+  linked: boolean;
+  installation: { account_login: string; account_type: string | null };
+}
+
+export function isAgentLinkGithubResponse(
+  value: AgentCreateResponse | AgentLinkGithubResponse,
+): value is AgentLinkGithubResponse {
+  return "source_repo" in value;
+}
+
+export interface AgentFromTemplateParams {
+  // Template key from `GET /agent_templates`.
+  template: string;
+  name: string;
+  // Derived from `name` when absent.
+  slug?: string;
+  description?: string;
+  // Harness slug, e.g. "claude-code". Dharta's default when absent.
+  harness?: string;
+  // Requires `harness`. The harness default when absent.
+  harnessVersion?: string;
+}
+
+export interface AgentFromTemplateResponse {
+  agent: Agent;
+  clone_url: string;
+  created: boolean;
+  release: Release | null;
+  accepted?: boolean;
+  // Present while release v1 is still building.
+  phase?: string;
+  state?: string;
+  retryable?: boolean;
+}
+
+export interface AgentDeployResponse {
+  agent: Agent;
+  queued: boolean;
+  source_repo: {
+    slug: string;
+    deploy_branch: string;
+    github_repository: string | null;
+  };
+  sync_generation?: number | null;
+  sync_attempt?: number | null;
+}
+
+export interface ReleaseRetryResponse {
+  agent: { id: number; slug: string; name: string };
+  release: Release;
+  retried_release: Release;
+  message?: string;
+  accepted?: boolean;
+  phase?: string;
+  state?: string;
+  retryable?: boolean;
+}
+
+export interface AgentCodeUpdateParams {
+  // Edited files as { path => content }. Only the paths you send change.
+  files: Record<string, string>;
+  // The release version the edits were made against, from
+  // `GET /api/agents/{slug}/releases`. Required: optimistic concurrency is
+  // always on, and a save against any other version is a 409, never a clobber.
+  baseVersion: number;
+}
+
+export interface AgentCodeUpdateResponse {
+  version: number;
+  status: string;
+  // All three are always sent; `changed` is `[]` on a no-op save.
+  changed: string[];
+  no_change: boolean;
+  pending: boolean;
+}
+
 export interface ApiKey {
-  id: string;
+  // Numeric: api_keys has a bigint primary key and the API answers the integer.
+  id: number;
   name: string;
   prefix: string;
   scopes: ApiKeyScope[];
-  mode?: "live" | "test";
-  expires_at?: string | null;
+  // Always answered, on every key and in the rotate response. `expires_at` is
+  // null for a key that never expires; a rotation copies the original's
+  // deadline rather than granting a fresh one.
+  mode: "live" | "test";
+  expires_at: string | null;
   created_at: string;
   last_used_at: string | null;
   revoked_at: string | null;
@@ -112,38 +318,204 @@ export interface ApiKeyCreateResponse {
   secret: string;
 }
 
-export interface ModelKey {
+export const API_KEY_BULK_ACTIONS = ["disable", "enable", "revoke"] as const;
+
+export type ApiKeyBulkAction = (typeof API_KEY_BULK_ACTIONS)[number];
+
+export const API_KEY_ROTATION_GRACE_PERIODS = ["now", "24h", "7d"] as const;
+
+export type ApiKeyRotationGracePeriod = (typeof API_KEY_ROTATION_GRACE_PERIODS)[number];
+
+export interface ApiKeyRotateResponse {
+  api_key: ApiKey;
+  // Plaintext secret for the replacement - shown exactly once. Store it now.
+  secret: string;
+  previous_key: ApiKey;
+  // When the rotated key stops working. Already past for `grace_period: "now"`.
+  grace_ends_at: string;
+}
+
+export interface ApiKeyStateResponse {
+  api_key: ApiKey;
+  // False when the key was already in that state, which is a no-op, not an error.
+  changed: boolean;
+}
+
+export interface ApiKeyBulkUpdateResponse {
+  action: ApiKeyBulkAction;
+  updated: ApiKey[];
+  // Keys the action does not apply to, left unchanged.
+  skipped: ApiKey[];
+}
+
+export interface ModelConnection {
   id: number;
-  provider: ModelKeyProvider;
+  // Organization-unique connector slug. Address a connector by this or by
+  // `id` on every /model_connections path, and by slug in a model reference.
+  slug: string;
+  provider: ModelConnectionProvider;
   name: string;
   tail: string;
-  auth_type: "api_key" | "oauth_subscription";
+  credential_kind: "api_key";
+  funding_source: "api_usage";
+  owner_kind: "organization";
+  storage_kind: "control_plane_encrypted";
+  adapter_kind: ModelAdapterKind;
+  connector_access_path_revision: number;
+  connector_access_path_digest: string;
   endpoint_url: string | null;
-  api_format: ModelApiFormat | null;
+  api_format: ModelConnectionApiFormat | null;
   created_at: string;
   last_verified_at: string | null;
   verification_error: string | null;
   revoked_at: string | null;
 }
 
-export interface ModelKeyCreateParams {
-  provider: ModelKeyProvider;
+export interface ModelConnectionCreateParams {
+  provider: ModelConnectionProvider;
   plaintext: string;
   name?: string;
-  auth_type?: "api_key" | "oauth_subscription";
+  // Omit to let the server derive the slug from `name`.
+  slug?: string;
   endpoint_url?: string;
-  api_format?: ModelApiFormat;
+  api_format?: ModelConnectionApiFormat;
 }
 
+export interface ModelConnectionRotateParams {
+  plaintext: string;
+  name?: string;
+}
+
+// One model a connection can serve. Only explicitly stored offers can be
+// enabled or selected as the connection default.
+export interface ModelConnectionOffer {
+  model_id: string;
+  enabled: boolean;
+  default: boolean;
+}
+
+export interface ModelConnectionOffers {
+  connector: {
+    id: number;
+    slug: string;
+    provider: ModelConnectionProvider;
+  };
+  models: ModelConnectionOffer[];
+}
+
+export interface ModelConnectionOffersUpdateParams {
+  // Replaces the whole enabled set.
+  enabled: string[];
+  // Must be one of `enabled`. Null clears the connector default.
+  default?: string | null;
+}
+
+// What the organization's model settings resolve to for an inheriting agent,
+// reduced to non-secret fields. Either it resolved, or it carries a stable
+// RFC 0070 error code and nothing else. Narrow on `error` before reading the
+// rest:
+//
+//   const r = settings.resolved;
+//   if (r.error) console.log(r.error); else console.log(r.connector, r.model_id);
+export type ResolvedOrganizationModel =
+  | {
+      // The connector slug, or `karta` for the platform connector.
+      connector: string;
+      model_id: string;
+      provider: ResolvedModelProvider;
+      credential_kind: ResolvedModelCredentialKind;
+      error?: never;
+    }
+  | {
+      error: string;
+      connector?: never;
+      model_id?: never;
+      provider?: never;
+      credential_kind?: never;
+    };
+
+// A model reference on the wire: the shorthand string, or the typed mapping.
+// The mapping's fields are exact per kind, matching the server's parser.
+export type ModelReferenceInput =
+  | string
+  | { kind: "default" }
+  | { kind: "model"; model: string }
+  | { kind: "target"; connector: string; model: string }
+  | { kind: "route"; route: string };
+
+// A patch over the portable model parameters. A null clears one parameter and
+// leaves the rest inherited; an absent key leaves it unchanged.
+export interface ModelParametersPatch {
+  temperature?: number | null;
+  top_p?: number | null;
+  max_output_tokens?: number | null;
+  reasoning_effort?: ModelReasoningEffort | null;
+  provider_options?: ModelParameters["provider_options"] | null;
+}
+
+export interface OrganizationModelSettings {
+  // Ordered connector slugs, including the synthetic platform slug `karta`.
+  // Empty means unset, which resolves as `["karta"]`.
+  connector_order: string[];
+  // The stored model reference shorthand: "", "<model>",
+  // "connector:<slug>/<model>", or "route:<name>".
+  model_reference: string;
+  model_parameters: ModelParameters;
+  // Optional endpoint override: the public HTTPS endpoint the organization
+  // default calls instead of the provider's standard API. Null when unset.
+  provider_endpoint_url: string | null;
+  // Wire protocol for that endpoint. Stored NOT NULL, so it always has a value
+  // and is read only when an endpoint URL is set.
+  provider_endpoint_kind: ModelSettingsEndpointKind;
+  resolved: ResolvedOrganizationModel;
+}
+
+// Mirrors OrganizationSettings::ENDPOINT_KINDS server-side. The first three are
+// the historical spellings; the rest name a provider API format directly.
+export const MODEL_SETTINGS_ENDPOINT_KINDS = [
+  "anthropic",
+  "openai",
+  "openai-compatible",
+  "anthropic_messages",
+  "openai_chat_completions",
+  "openai_responses",
+  "bedrock_converse",
+  "vertex_generate_content",
+] as const;
+
+export type ModelSettingsEndpointKind = (typeof MODEL_SETTINGS_ENDPOINT_KINDS)[number];
+
+// Only the keys you send change. A null inside `model_parameters` clears that
+// one parameter.
+export interface OrganizationModelSettingsUpdateParams {
+  // An array of connector slugs, or one string with whitespace or comma
+  // separators. Empty means the platform connector serves turns.
+  connector_order?: string[] | string;
+  model_reference?: ModelReferenceInput;
+  model_parameters?: ModelParametersPatch;
+  // Send "" or null to clear the override; both mean the same thing. The kind
+  // is switched, never cleared: clearing an override means clearing the URL.
+  provider_endpoint_url?: string | null;
+  provider_endpoint_kind?: ModelSettingsEndpointKind;
+}
+
+// `Api::WebhookEndpointsController#serialize`, field for field.
+//
+// `id` is the integer primary key. It read `string` here and `uuid` in the
+// OpenAPI document, so a caller comparing an id to one it stored got false.
+//
+// `consecutive_failures` used to be required and the serializer has never
+// returned it, so `endpoint.consecutive_failures` was `undefined` typed as
+// `number` - the failure the type system exists to prevent.
 export interface WebhookEndpoint {
-  id: string;
+  id: number;
   name: string;
   url: string;
   event_types: WebhookEventType[];
   enabled: boolean;
-  consecutive_failures: number;
   disabled_at: string | null;
   created_at: string;
+  updated_at: string;
 }
 
 export interface WebhookEndpointCreateResponse {
@@ -151,6 +523,35 @@ export interface WebhookEndpointCreateResponse {
   secret: string;
 }
 
+export interface WebhookDelivery {
+  id: number;
+  webhook_endpoint_id: number;
+  event_id: string;
+  event_type: string;
+  attempt: number;
+  next_attempt_at: string | null;
+  created_at: string;
+}
+
+export interface KartaShare {
+  id: number;
+  prefix: string;
+  name: string;
+  agent_instance_id: string;
+  agent: { id: number; slug: string; name: string } | null;
+  allowed_origins: string[];
+  created_at: string;
+  revoked_at: string | null;
+}
+
+export interface KartaShareCreateResponse {
+  share: KartaShare;
+  // Publishable key - shown exactly once. Store it now.
+  secret: string;
+  // The link to hand out, secret included.
+  url: string;
+}
+
 export interface UsageSummary {
   totals: {
     input_tokens?: number;
@@ -172,8 +573,216 @@ export interface BillingStatus {
   current_period_end: string | null;
 }
 
+// A pending organization invitation, as `GET /api/members` lists them and
+// `POST /api/members/invitations/{id}/resend` returns one. `id` is an integer
+// primary key rather than a uuid: invitations predate that convention.
+export interface MemberInvitation {
+  id: number;
+  email: string;
+  role: string;
+  expires_at: string | null;
+  created_at: string;
+}
+
 export interface ErrorBody {
   error: string;
   message?: string;
   details?: Record<string, unknown>;
 }
+
+// --- Fleet (RFC 0048 PR7) -------------------------------------------------
+
+export type FleetEntityType = "agents" | "kartas" | "users" | "sessions";
+
+export type FleetSnoozeDuration = "1h" | "1d" | "1w";
+
+export interface FleetOperation {
+  id: string;
+  entity_type: string;
+  action: string;
+  status: string;
+  parameters: Record<string, unknown>;
+  selection: {
+    mode: string;
+    // Set when the selection freezes, and nothing requires an operation's
+    // selection to be frozen. Every path that creates one today freezes first,
+    // but that is a property of the callers, not of the model.
+    manifest_digest: string | null;
+  };
+  targets: {
+    total: number;
+    pending: number;
+    running: number;
+    succeeded: number;
+    failed: number;
+    skipped: number;
+    cancelled: number;
+  };
+  // A NOT NULL jsonb column with a `{}` default, so it is an empty object
+  // rather than null when a preview produced no summary.
+  dry_run_summary: Record<string, unknown>;
+  warnings: string[];
+  requires_step_up: boolean;
+  // Present only while the operation is a draft: it is what `confirm` takes.
+  confirmation_phrase?: string | null;
+  last_error_code: string | null;
+  last_error_message: string | null;
+  approved_at: string | null;
+  started_at: string | null;
+  finished_at: string | null;
+  cancel_requested_at: string | null;
+  created_at: string;
+}
+
+export interface FleetOperationParams {
+  action_key: string;
+  entity_type?: FleetEntityType;
+  // "explicit" names rows by id. "snapshot" and "all_matching" freeze whatever
+  // the filter or saved view matched at preview time. The server defaults to
+  // "all_matching", which is every row the filter selects - and every row of
+  // the entity type when there is no filter.
+  selection_mode?: "explicit" | "snapshot" | "all_matching";
+  explicit_ids?: string[];
+  saved_view_id?: string;
+  filter?: string;
+  // The server permits exactly these keys and drops anything else without
+  // saying so: team_slug, environment, lifecycle, label_assignment, label_key,
+  // rollout_ring, release_version, model_id, harness_version, cap_cents.
+  // `action_key` decides which of them apply.
+  parameters?: Record<string, unknown>;
+}
+
+export interface FleetRolloutPartition {
+  position: number;
+  name: string;
+  percentage: number;
+  target_count: number;
+  status: string;
+  status_reason: string | null;
+  observation_window_minutes: number;
+  unhealthy_windows: number;
+  started_at: string | null;
+  observing_at: string | null;
+  next_evaluation_at: string | null;
+  last_evaluated_at: string | null;
+  finished_at: string | null;
+}
+
+export interface FleetRollout {
+  id: string;
+  name: string;
+  status: string;
+  status_reason: string | null;
+  // Release versions are integers, and the rollout always has a target. Only
+  // the rollback version is nullable: a rollout that has never been rolled back
+  // has nothing to go back to.
+  target_release_version: number;
+  rollback_release_version: number | null;
+  current_partition_position: number;
+  consecutive_unhealthy_windows: number;
+  automatic_pause_enabled: boolean;
+  automatic_rollback_enabled: boolean;
+  anomaly_gate_enabled: boolean;
+  shadow_mode: boolean;
+  started_at: string | null;
+  paused_at: string | null;
+  finished_at: string | null;
+  created_at: string;
+  partitions: FleetRolloutPartition[];
+}
+
+// The detector's own evidence sample is not part of this shape. It holds
+// session and end-user references, which stay behind the console and the
+// expiring `fleet:subjects:read` scope.
+export interface FleetAnomalyFinding {
+  id: string;
+  metric: string;
+  detector: string;
+  status: string;
+  // Never null: an untriaged finding reads "unclassified".
+  classification: string;
+  severity: string;
+  title: string;
+  detail: string;
+  assigned_membership_id: number | null;
+  runbook_url: string | null;
+  scope_definition: Record<string, unknown>;
+  filter_digest: string;
+  // The detector always produces a full measurement, so these are NOT NULL
+  // columns and the serializer emits every one. `relative_deviation` is the
+  // exception: its column is nullable.
+  observed_value: number;
+  expected_low: number;
+  expected_high: number;
+  absolute_deviation: number;
+  relative_deviation: number | null;
+  sample_count: number;
+  occurrence_count: number;
+  confidence: number;
+  materiality: number;
+  complete: boolean;
+  // The four detection timestamps are NOT NULL. The lifecycle ones below are
+  // not: a finding that was never resolved has no resolved_at.
+  started_at: string;
+  peak_at: string;
+  detected_at: string;
+  last_seen_at: string;
+  recovery_at: string | null;
+  resolved_at: string | null;
+  snoozed_until: string | null;
+  promoted_at: string | null;
+}
+
+export interface FleetSavedView {
+  id: string;
+  url: string;
+  entity_type: string;
+  name: string;
+  description: string | null;
+  visibility: string;
+  team_id: number | null;
+  owner_membership_id: number | null;
+  organization_default: boolean;
+  definition_version: number;
+  definition: Record<string, unknown>;
+  favorite: boolean;
+  updated_at: string;
+}
+
+export interface FleetSavedViewParams {
+  entity_type: string;
+  name: string;
+  definition: Record<string, unknown>;
+  // null clears a description that was set; omitting the key leaves it alone.
+  description?: string | null;
+  visibility?: "private" | "team" | "organization";
+  // null clears the owning team, which is how a team view becomes an
+  // organization or private one.
+  organization_team_id?: number | null;
+  organization_default?: boolean;
+}
+
+export interface FleetAnalyticsSaveParams {
+  name: string;
+  // Optional: the explorer defaults to `turns` when no metric is given.
+  metric?: string;
+  description?: string;
+  range?: string;
+  starts_at?: string;
+  ends_at?: string;
+  scope_kind?: string;
+  scope_ids?: string;
+  bucket?: string;
+  aggregation?: string;
+  comparison?: string;
+  comparison_saved_view?: string;
+  breakdown?: string[];
+  events?: string[];
+  filters?: Record<string, unknown>;
+}
+
+export interface FleetExportParams {
+  entity_type: FleetEntityType;
+  // Row identifiers, as the catalog returns them.
+  explicit_ids: string[];
+}