// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.

import { APIResource } from '../core/resource';
import * as CompletionsAPI from './chat/completions';
import { APIPromise } from '../core/api-promise';
import { CursorPage, type CursorPageParams, PagePromise } from '../core/pagination';
import { RequestOptions } from '../internal/request-options';
import { path } from '../internal/utils/path';

export class AgentConfigs extends APIResource {
  /**
   * Create a reusable agent configuration (system prompt, harness, model, allowed
   * tools) under the caller's account.
   *
   * The config is a template that a chat session or a non-chat trigger later turns
   * into task params; creating one does not start any task. `persistent_workspace`
   * opts tasks made from this config into a durable `/workspace` that survives
   * sandbox death (off by default, and fixed once a task starts), and `repos`
   * overrides which repositories provisioning clones into that workspace — omit it
   * (null) to use the deployment default, or pass an empty list to clone nothing. A
   * `repos` override is rejected with a 422 on the model-agnostic (litellm) harness
   * unless `persistent_workspace` is also true, because non-persistent litellm tasks
   * run in a pre-cloned warm-pool sandbox where the override would be ignored.
   * `allowed_tools` may name MCP servers (Slack, Linear, GitHub, ...) alongside
   * harness tools, and granting an MCP server name authorizes every tool it exposes.
   */
  create(body: AgentConfigCreateParams, options?: RequestOptions): APIPromise<AgentConfigCreateResponse> {
    return this._client.post('/v5/agent_configs', { body, ...options });
  }

  /**
   * Fetch a single stored agent configuration by id, including its
   * `persistent_workspace` flag and any `repos` override.
   *
   * This returns the saved record as-is and does not compute task params; use
   * `{agent_config_id}/resolve` when you need the config projected into the params a
   * task would run with. A user caller can only read a config they created unless
   * fine-grained access control grants access, while a service account can read any
   * config under the account; a missing or out-of-scope id returns a 404.
   */
  retrieve(agentConfigID: string, options?: RequestOptions): APIPromise<AgentConfigRetrieveResponse> {
    return this._client.get(path`/v5/agent_configs/${agentConfigID}`, options);
  }

  /**
   * Partially update a stored agent config; only fields present in the request body
   * are changed.
   *
   * `persistent_workspace` and `repos` are both patchable — an explicit null on
   * `repos` clears the override back to the deployment default, while the
   * always-present fields (name, system_prompt, harness, allowed_tools, model, and
   * persistent_workspace) reject an explicit null. Because `persistent_workspace`
   * and `repos` are read when a task is created and are fixed for a task's life,
   * changing them affects only tasks created afterward, not one already running. The
   * optional `task_id` query parameter opts into a live-config side effect: after
   * the row is persisted, the changed pass-through fields (system_prompt, model,
   * harness, and allowed_tools split into harness tools versus MCP servers) are
   * shallow-merged into that running task's params on Agentex in a background task
   * so the worker picks them up on its next turn; `persistent_workspace` and `repos`
   * are intentionally not forwarded to a running task. That side effect runs after
   * the response is sent, is best-effort, and no-ops if the task does not exist or
   * the caller does not own it. A user caller can only update a config they created
   * unless fine-grained access control grants access.
   */
  update(
    agentConfigID: string,
    params: AgentConfigUpdateParams,
    options?: RequestOptions,
  ): APIPromise<AgentConfigUpdateResponse> {
    const { task_id, ...body } = params;
    return this._client.patch(path`/v5/agent_configs/${agentConfigID}`, {
      query: { task_id },
      body,
      ...options,
    });
  }

  /**
   * List agent configurations visible to the caller, with cursor-based pagination.
   *
   * A user caller sees only the configs they created unless fine-grained access
   * control (FGAC) grants them access to others; a service-account caller sees every
   * config under the account. This returns the stored config records as-is — use
   * `{agent_config_id}/resolve` instead when you need a config projected into the
   * params a task would run with. Because deleting a config removes it outright
   * rather than archiving it, there are no archived configs to page through here.
   */
  list(
    query: AgentConfigListParams | null | undefined = {},
    options?: RequestOptions,
  ): PagePromise<AgentConfigListResponsesCursorPage, AgentConfigListResponse> {
    return this._client.getAPIList('/v5/agent_configs', CursorPage<AgentConfigListResponse>, {
      query,
      ...options,
    });
  }

  /**
   * Permanently delete an agent config; this is a hard delete, not an archive, so
   * the row is removed and cannot be restored.
   *
   * Because a config is only a template, deleting it does not stop or alter any task
   * already created from it. A user caller can only delete a config they created
   * unless fine-grained access control grants access. The response echoes the
   * deleted id.
   */
  delete(agentConfigID: string, options?: RequestOptions): APIPromise<AgentConfigDeleteResponse> {
    return this._client.delete(path`/v5/agent_configs/${agentConfigID}`, options);
  }

  /**
   * Return the fixed set of tool names that route to MCP servers rather than
   * harness-provided tools.
   *
   * These are the subset of `allowed_tools` values (Slack, Linear, GitHub, ...) the
   * platform treats as MCP servers; the list is a static enum, not account data, so
   * it is identical for every caller. It is exposed mainly so the generated SDK
   * carries the `McpTool` type and the frontend can assert its own
   * MCP-versus-harness tool classifier against the backend to prevent drift. It does
   * not list configs or the tools actually granted to any particular config.
   */
  listMcpTools(options?: RequestOptions): APIPromise<AgentConfigListMcpToolsResponse> {
    return this._client.get('/v5/agent_configs/mcp_tools', options);
  }
}

export type AgentConfigListResponsesCursorPage = CursorPage<AgentConfigListResponse>;

/**
 * A single repo the agent should clone into its workspace.
 *
 * Mirrors the per-entry shape the golden agent's `_validate_repos` accepts: `url`
 * is required, the rest are optional passthrough hints. Sent verbatim as
 * `task.params.repos` so provisioning clones these instead of the
 * deployment-global default.
 */
export interface RepoSpec {
  url: string;

  depth?: number;

  path?: string;
}

export interface AgentConfigCreateResponse {
  id: string;

  allowed_tools: Array<string>;

  created_at: string;

  harness: string;

  model: string;

  name: string;

  system_prompt: string;

  updated_at: string;

  description?: string;

  object?: 'agent_config';

  persistent_workspace?: boolean;

  repos?: Array<RepoSpec>;
}

export interface AgentConfigRetrieveResponse {
  id: string;

  allowed_tools: Array<string>;

  created_at: string;

  harness: string;

  model: string;

  name: string;

  system_prompt: string;

  updated_at: string;

  description?: string;

  object?: 'agent_config';

  persistent_workspace?: boolean;

  repos?: Array<RepoSpec>;
}

export interface AgentConfigUpdateResponse {
  id: string;

  allowed_tools: Array<string>;

  created_at: string;

  harness: string;

  model: string;

  name: string;

  system_prompt: string;

  updated_at: string;

  description?: string;

  object?: 'agent_config';

  persistent_workspace?: boolean;

  repos?: Array<RepoSpec>;
}

export interface AgentConfigListResponse {
  id: string;

  allowed_tools: Array<string>;

  created_at: string;

  harness: string;

  model: string;

  name: string;

  system_prompt: string;

  updated_at: string;

  description?: string;

  object?: 'agent_config';

  persistent_workspace?: boolean;

  repos?: Array<RepoSpec>;
}

export interface AgentConfigDeleteResponse {
  id: string;

  deleted: boolean;

  object?: 'agent_config';
}

export type AgentConfigListMcpToolsResponse = Array<
  | 'Slack'
  | 'Linear'
  | 'GitHub'
  | 'Confluence'
  | 'Notion'
  | 'Datadog'
  | 'PagerDuty'
  | 'Salesforce'
  | 'Figma'
  | 'Granola'
  | 'Jira'
  | 'Gmail'
  | 'GoogleCalendar'
  | 'GoogleDrive'
  | 'GoogleDocs'
  | 'GoogleSheets'
  | 'GoogleSlides'
  | 'Snowflake'
  | 'Redash'
  | 'Tableau'
  | 'Metabase'
  | 'Gong'
  | 'ZoomInfo'
  | 'Clay'
>;

export interface AgentConfigCreateParams {
  /**
   * Harness strategy. See Harness enum for supported values.
   */
  harness: 'claude-code' | 'codex' | 'litellm';

  model: string;

  name: string;

  system_prompt: string;

  /**
   * Tools enabled for this config. See AllowedTool enum for the catalogue.
   */
  allowed_tools?: Array<
    | 'Read'
    | 'Write'
    | 'Edit'
    | 'Bash'
    | 'Glob'
    | 'Grep'
    | 'List'
    | 'WebFetch'
    | 'WebSearch'
    | 'Task'
    | 'TodoWrite'
    | 'NotebookEdit'
    | 'ExitPlanMode'
    | 'Slack'
    | 'Linear'
    | 'GitHub'
    | 'Confluence'
    | 'Notion'
    | 'Datadog'
    | 'PagerDuty'
    | 'Salesforce'
    | 'Figma'
    | 'Granola'
    | 'Jira'
    | 'Gmail'
    | 'GoogleCalendar'
    | 'GoogleDrive'
    | 'GoogleDocs'
    | 'GoogleSheets'
    | 'GoogleSlides'
    | 'Snowflake'
    | 'Redash'
    | 'Tableau'
    | 'Metabase'
    | 'Gong'
    | 'ZoomInfo'
    | 'Clay'
  >;

  description?: string;

  /**
   * Give tasks a persistent /workspace that survives sandbox death. Fixed for a
   * task's life; defaults off.
   */
  persistent_workspace?: boolean;

  /**
   * Per-config repo override. None uses the deployment default; an empty list clones
   * nothing.
   */
  repos?: Array<RepoSpec>;
}

export interface AgentConfigUpdateParams {
  /**
   * Query param: If set, after persisting the patch we shallow-merge the changed
   * fields into this task's params column on Agentex so the worker picks up the new
   * values on its next turn. Caller-provided context — Agentex enforces task
   * ownership via its own auth, so the side-effect no-ops if the caller doesn't own
   * the task.
   */
  task_id?: string;

  /**
   * Body param
   */
  allowed_tools?: Array<
    | 'Read'
    | 'Write'
    | 'Edit'
    | 'Bash'
    | 'Glob'
    | 'Grep'
    | 'List'
    | 'WebFetch'
    | 'WebSearch'
    | 'Task'
    | 'TodoWrite'
    | 'NotebookEdit'
    | 'ExitPlanMode'
    | 'Slack'
    | 'Linear'
    | 'GitHub'
    | 'Confluence'
    | 'Notion'
    | 'Datadog'
    | 'PagerDuty'
    | 'Salesforce'
    | 'Figma'
    | 'Granola'
    | 'Jira'
    | 'Gmail'
    | 'GoogleCalendar'
    | 'GoogleDrive'
    | 'GoogleDocs'
    | 'GoogleSheets'
    | 'GoogleSlides'
    | 'Snowflake'
    | 'Redash'
    | 'Tableau'
    | 'Metabase'
    | 'Gong'
    | 'ZoomInfo'
    | 'Clay'
  >;

  /**
   * Body param
   */
  description?: string;

  /**
   * Body param: Supported agent harness strategies.
   *
   * Mirrors `PROVIDERS` in golden-agent's `project/harness/activity.py`.
   */
  harness?: 'claude-code' | 'codex' | 'litellm';

  /**
   * Body param
   */
  model?: string;

  /**
   * Body param
   */
  name?: string;

  /**
   * Body param
   */
  persistent_workspace?: boolean;

  /**
   * Body param
   */
  repos?: Array<RepoSpec>;

  /**
   * Body param
   */
  system_prompt?: string;
}

export interface AgentConfigListParams extends CursorPageParams {
  sort_by?: string;

  sort_order?: CompletionsAPI.SortOrder;
}

export declare namespace AgentConfigs {
  export {
    type RepoSpec as RepoSpec,
    type AgentConfigCreateResponse as AgentConfigCreateResponse,
    type AgentConfigRetrieveResponse as AgentConfigRetrieveResponse,
    type AgentConfigUpdateResponse as AgentConfigUpdateResponse,
    type AgentConfigListResponse as AgentConfigListResponse,
    type AgentConfigDeleteResponse as AgentConfigDeleteResponse,
    type AgentConfigListMcpToolsResponse as AgentConfigListMcpToolsResponse,
    type AgentConfigListResponsesCursorPage as AgentConfigListResponsesCursorPage,
    type AgentConfigCreateParams as AgentConfigCreateParams,
    type AgentConfigUpdateParams as AgentConfigUpdateParams,
    type AgentConfigListParams as AgentConfigListParams,
  };
}