@opengeni/contracts 5.4.0 → 5.5.0-canary.36927100590001

package/dist/agent-config.d.ts

@@ -0,0 +1,872 @@
+/**
+ * Agent configuration: one `agent` object that describes what an OpenGeni
+ * agent is (identity), how it answers (renderer, instructions alias) and what
+ * it can do (capabilities). Capabilities are product words; this module owns
+ * the single registry that maps every first-party tool to exactly one of them
+ * and the pure resolution shared by every session creator (API, MCP child,
+ * Slack, scheduled tasks, automations) and the mid-session update.
+ *
+ * Invariants:
+ * - `"all"` reproduces the creator's legacy tool values exactly: capability
+ *   filtering only removes tools of capabilities that are OFF, and every
+ *   capability is ON under `"all"` (deployment-disabled capabilities are
+ *   reported but never rewrite the stored selection; the runtime enforces them).
+ * - A session with no configuration (`null`) keeps byte-identical legacy
+ *   behavior; nothing here runs for it.
+ * - Children and agent callers may only narrow.
+ *
+ * This module must not import runtime values from `./index` (the index
+ * re-exports it); only types cross that edge.
+ */
+import { z } from "zod";
+import type { FirstPartyMcpToolName, SessionToolPolicy, ToolRef } from "./index.js";
+export declare const AGENT_CAPABILITY_IDS: readonly ["webSearch", "humanInput", "skills", "goals", "subagents", "knowledge", "schedules", "artifacts", "browser", "media", "workspaceFiles", "workspaceConnectors", "workspaceAdmin"];
+export declare const AgentCapabilityId: z.ZodEnum<{
+    artifacts: "artifacts";
+    browser: "browser";
+    goals: "goals";
+    humanInput: "humanInput";
+    knowledge: "knowledge";
+    media: "media";
+    schedules: "schedules";
+    skills: "skills";
+    subagents: "subagents";
+    webSearch: "webSearch";
+    workspaceAdmin: "workspaceAdmin";
+    workspaceConnectors: "workspaceConnectors";
+    workspaceFiles: "workspaceFiles";
+}>;
+export type AgentCapabilityId = z.infer<typeof AgentCapabilityId>;
+/** Boolean capabilities: every capability except the three-state `skills`. */
+export type AgentBooleanCapabilityId = Exclude<AgentCapabilityId, "skills">;
+export declare const AGENT_BOOLEAN_CAPABILITY_IDS: AgentBooleanCapabilityId[];
+/** `read` reads installed Skills; `manage` also saves/installs/publishes/removes. */
+export declare const AgentSkillsCapability: z.ZodUnion<readonly [z.ZodLiteral<"read">, z.ZodLiteral<"manage">, z.ZodLiteral<false>]>;
+export type AgentSkillsCapability = z.infer<typeof AgentSkillsCapability>;
+export declare const AgentCapabilityStartingPoint: z.ZodEnum<{
+    all: "all";
+    none: "none";
+}>;
+export type AgentCapabilityStartingPoint = z.infer<typeof AgentCapabilityStartingPoint>;
+export declare const AgentCapabilityToggles: z.ZodObject<{
+    webSearch: z.ZodOptional<z.ZodBoolean>;
+    humanInput: z.ZodOptional<z.ZodBoolean>;
+    skills: z.ZodOptional<z.ZodUnion<readonly [z.ZodLiteral<"read">, z.ZodLiteral<"manage">, z.ZodLiteral<false>]>>;
+    goals: z.ZodOptional<z.ZodBoolean>;
+    subagents: z.ZodOptional<z.ZodBoolean>;
+    knowledge: z.ZodOptional<z.ZodBoolean>;
+    schedules: z.ZodOptional<z.ZodBoolean>;
+    artifacts: z.ZodOptional<z.ZodBoolean>;
+    browser: z.ZodOptional<z.ZodBoolean>;
+    media: z.ZodOptional<z.ZodBoolean>;
+    workspaceFiles: z.ZodOptional<z.ZodBoolean>;
+    workspaceConnectors: z.ZodOptional<z.ZodBoolean>;
+    workspaceAdmin: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strict>;
+export type AgentCapabilityToggles = z.infer<typeof AgentCapabilityToggles>;
+/**
+ * `"all"`: everything this workspace offers (today's behavior). `"none"`: the
+ * session's own tools plus essentials (human input and reading Skills). An
+ * object starts from one of them and switches individual capabilities.
+ */
+export declare const AgentCapabilities: z.ZodUnion<readonly [z.ZodLiteral<"all">, z.ZodLiteral<"none">, z.ZodObject<{
+    webSearch: z.ZodOptional<z.ZodBoolean>;
+    humanInput: z.ZodOptional<z.ZodBoolean>;
+    skills: z.ZodOptional<z.ZodUnion<readonly [z.ZodLiteral<"read">, z.ZodLiteral<"manage">, z.ZodLiteral<false>]>>;
+    goals: z.ZodOptional<z.ZodBoolean>;
+    subagents: z.ZodOptional<z.ZodBoolean>;
+    knowledge: z.ZodOptional<z.ZodBoolean>;
+    schedules: z.ZodOptional<z.ZodBoolean>;
+    artifacts: z.ZodOptional<z.ZodBoolean>;
+    browser: z.ZodOptional<z.ZodBoolean>;
+    media: z.ZodOptional<z.ZodBoolean>;
+    workspaceFiles: z.ZodOptional<z.ZodBoolean>;
+    workspaceConnectors: z.ZodOptional<z.ZodBoolean>;
+    workspaceAdmin: z.ZodOptional<z.ZodBoolean>;
+    from: z.ZodEnum<{
+        all: "all";
+        none: "none";
+    }>;
+}, z.core.$strict>]>;
+export type AgentCapabilities = z.infer<typeof AgentCapabilities>;
+/** `opengeni` emits `sandbox:`/`artifact:` links and inline visuals; `markdown` does not. */
+export declare const AgentRenderer: z.ZodEnum<{
+    markdown: "markdown";
+    opengeni: "opengeni";
+}>;
+export type AgentRenderer = z.infer<typeof AgentRenderer>;
+export declare const AGENT_IDENTITY_MAX_CHARACTERS = 8000;
+/** Same bound as `SESSION_INSTRUCTIONS_MAX_CHARACTERS` (asserted by test). */
+export declare const AGENT_INSTRUCTIONS_MAX_CHARACTERS = 65536;
+export declare const AgentIdentity: z.ZodString;
+/** The request-side agent object. Every field is optional. */
+export declare const AgentConfigRequest: z.ZodObject<{
+    capabilities: z.ZodOptional<z.ZodUnion<readonly [z.ZodLiteral<"all">, z.ZodLiteral<"none">, z.ZodObject<{
+        webSearch: z.ZodOptional<z.ZodBoolean>;
+        humanInput: z.ZodOptional<z.ZodBoolean>;
+        skills: z.ZodOptional<z.ZodUnion<readonly [z.ZodLiteral<"read">, z.ZodLiteral<"manage">, z.ZodLiteral<false>]>>;
+        goals: z.ZodOptional<z.ZodBoolean>;
+        subagents: z.ZodOptional<z.ZodBoolean>;
+        knowledge: z.ZodOptional<z.ZodBoolean>;
+        schedules: z.ZodOptional<z.ZodBoolean>;
+        artifacts: z.ZodOptional<z.ZodBoolean>;
+        browser: z.ZodOptional<z.ZodBoolean>;
+        media: z.ZodOptional<z.ZodBoolean>;
+        workspaceFiles: z.ZodOptional<z.ZodBoolean>;
+        workspaceConnectors: z.ZodOptional<z.ZodBoolean>;
+        workspaceAdmin: z.ZodOptional<z.ZodBoolean>;
+        from: z.ZodEnum<{
+            all: "all";
+            none: "none";
+        }>;
+    }, z.core.$strict>]>>;
+    identity: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    instructions: z.ZodOptional<z.ZodString>;
+    renderer: z.ZodOptional<z.ZodEnum<{
+        markdown: "markdown";
+        opengeni: "opengeni";
+    }>>;
+}, z.core.$strict>;
+export type AgentConfigRequest = z.infer<typeof AgentConfigRequest>;
+/** Workspace "Defaults for new sessions" agent part (no instructions alias). */
+export declare const WorkspaceAgentDefaults: z.ZodObject<{
+    capabilities: z.ZodOptional<z.ZodUnion<readonly [z.ZodLiteral<"all">, z.ZodLiteral<"none">, z.ZodObject<{
+        webSearch: z.ZodOptional<z.ZodBoolean>;
+        humanInput: z.ZodOptional<z.ZodBoolean>;
+        skills: z.ZodOptional<z.ZodUnion<readonly [z.ZodLiteral<"read">, z.ZodLiteral<"manage">, z.ZodLiteral<false>]>>;
+        goals: z.ZodOptional<z.ZodBoolean>;
+        subagents: z.ZodOptional<z.ZodBoolean>;
+        knowledge: z.ZodOptional<z.ZodBoolean>;
+        schedules: z.ZodOptional<z.ZodBoolean>;
+        artifacts: z.ZodOptional<z.ZodBoolean>;
+        browser: z.ZodOptional<z.ZodBoolean>;
+        media: z.ZodOptional<z.ZodBoolean>;
+        workspaceFiles: z.ZodOptional<z.ZodBoolean>;
+        workspaceConnectors: z.ZodOptional<z.ZodBoolean>;
+        workspaceAdmin: z.ZodOptional<z.ZodBoolean>;
+        from: z.ZodEnum<{
+            all: "all";
+            none: "none";
+        }>;
+    }, z.core.$strict>]>>;
+    identity: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    renderer: z.ZodOptional<z.ZodEnum<{
+        markdown: "markdown";
+        opengeni: "opengeni";
+    }>>;
+}, z.core.$strict>;
+export type WorkspaceAgentDefaults = z.infer<typeof WorkspaceAgentDefaults>;
+export declare const ResolvedAgentCapabilities: z.ZodObject<{
+    webSearch: z.ZodBoolean;
+    humanInput: z.ZodBoolean;
+    skills: z.ZodUnion<readonly [z.ZodLiteral<"read">, z.ZodLiteral<"manage">, z.ZodLiteral<false>]>;
+    goals: z.ZodBoolean;
+    subagents: z.ZodBoolean;
+    knowledge: z.ZodBoolean;
+    schedules: z.ZodBoolean;
+    artifacts: z.ZodBoolean;
+    browser: z.ZodBoolean;
+    media: z.ZodBoolean;
+    workspaceFiles: z.ZodBoolean;
+    workspaceConnectors: z.ZodBoolean;
+    workspaceAdmin: z.ZodBoolean;
+}, z.core.$strict>;
+export type ResolvedAgentCapabilities = z.infer<typeof ResolvedAgentCapabilities>;
+export declare const ResolvedAgentConfigSource: z.ZodEnum<{
+    deployment_default: "deployment_default";
+    inherited: "inherited";
+    legacy_conversion: "legacy_conversion";
+    request: "request";
+    workspace_default: "workspace_default";
+}>;
+export type ResolvedAgentConfigSource = z.infer<typeof ResolvedAgentConfigSource>;
+/**
+ * The frozen per-session configuration (`sessions.agent_config`). `capabilities`
+ * is the effective map; `unavailable` names capabilities the configuration
+ * wanted on but this deployment does not offer (reported off, never widened
+ * later without a new resolution).
+ */
+export declare const ResolvedAgentConfig: z.ZodObject<{
+    version: z.ZodLiteral<1>;
+    from: z.ZodEnum<{
+        all: "all";
+        none: "none";
+    }>;
+    capabilities: z.ZodObject<{
+        webSearch: z.ZodBoolean;
+        humanInput: z.ZodBoolean;
+        skills: z.ZodUnion<readonly [z.ZodLiteral<"read">, z.ZodLiteral<"manage">, z.ZodLiteral<false>]>;
+        goals: z.ZodBoolean;
+        subagents: z.ZodBoolean;
+        knowledge: z.ZodBoolean;
+        schedules: z.ZodBoolean;
+        artifacts: z.ZodBoolean;
+        browser: z.ZodBoolean;
+        media: z.ZodBoolean;
+        workspaceFiles: z.ZodBoolean;
+        workspaceConnectors: z.ZodBoolean;
+        workspaceAdmin: z.ZodBoolean;
+    }, z.core.$strict>;
+    unavailable: z.ZodDefault<z.ZodArray<z.ZodEnum<{
+        artifacts: "artifacts";
+        browser: "browser";
+        goals: "goals";
+        humanInput: "humanInput";
+        knowledge: "knowledge";
+        media: "media";
+        schedules: "schedules";
+        skills: "skills";
+        subagents: "subagents";
+        webSearch: "webSearch";
+        workspaceAdmin: "workspaceAdmin";
+        workspaceConnectors: "workspaceConnectors";
+        workspaceFiles: "workspaceFiles";
+    }>>>;
+    identity: z.ZodNullable<z.ZodString>;
+    renderer: z.ZodEnum<{
+        markdown: "markdown";
+        opengeni: "opengeni";
+    }>;
+    source: z.ZodEnum<{
+        deployment_default: "deployment_default";
+        inherited: "inherited";
+        legacy_conversion: "legacy_conversion";
+        request: "request";
+        workspace_default: "workspace_default";
+    }>;
+}, z.core.$strict>;
+export type ResolvedAgentConfig = z.infer<typeof ResolvedAgentConfig>;
+/** `PUT /v1/workspaces/:workspaceId/sessions/:sessionId/agent`. Omitted fields keep current values. */
+export declare const UpdateSessionAgentRequest: z.ZodObject<{
+    agent: z.ZodObject<{
+        capabilities: z.ZodOptional<z.ZodUnion<readonly [z.ZodLiteral<"all">, z.ZodLiteral<"none">, z.ZodObject<{
+            webSearch: z.ZodOptional<z.ZodBoolean>;
+            humanInput: z.ZodOptional<z.ZodBoolean>;
+            skills: z.ZodOptional<z.ZodUnion<readonly [z.ZodLiteral<"read">, z.ZodLiteral<"manage">, z.ZodLiteral<false>]>>;
+            goals: z.ZodOptional<z.ZodBoolean>;
+            subagents: z.ZodOptional<z.ZodBoolean>;
+            knowledge: z.ZodOptional<z.ZodBoolean>;
+            schedules: z.ZodOptional<z.ZodBoolean>;
+            artifacts: z.ZodOptional<z.ZodBoolean>;
+            browser: z.ZodOptional<z.ZodBoolean>;
+            media: z.ZodOptional<z.ZodBoolean>;
+            workspaceFiles: z.ZodOptional<z.ZodBoolean>;
+            workspaceConnectors: z.ZodOptional<z.ZodBoolean>;
+            workspaceAdmin: z.ZodOptional<z.ZodBoolean>;
+            from: z.ZodEnum<{
+                all: "all";
+                none: "none";
+            }>;
+        }, z.core.$strict>]>>;
+        identity: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        instructions: z.ZodOptional<z.ZodString>;
+        renderer: z.ZodOptional<z.ZodEnum<{
+            markdown: "markdown";
+            opengeni: "opengeni";
+        }>>;
+    }, z.core.$strict>;
+    expectedVersion: z.ZodNumber;
+}, z.core.$strict>;
+export type UpdateSessionAgentRequest = z.infer<typeof UpdateSessionAgentRequest>;
+/** Client-safe rollout projection. */
+export declare const ClientAgentConfig: z.ZodObject<{
+    enabled: z.ZodBoolean;
+    defaultForNewSessions: z.ZodBoolean;
+    capabilities: z.ZodArray<z.ZodObject<{
+        id: z.ZodEnum<{
+            artifacts: "artifacts";
+            browser: "browser";
+            goals: "goals";
+            humanInput: "humanInput";
+            knowledge: "knowledge";
+            media: "media";
+            schedules: "schedules";
+            skills: "skills";
+            subagents: "subagents";
+            webSearch: "webSearch";
+            workspaceAdmin: "workspaceAdmin";
+            workspaceConnectors: "workspaceConnectors";
+            workspaceFiles: "workspaceFiles";
+        }>;
+        available: z.ZodBoolean;
+        reason: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export type ClientAgentConfig = z.infer<typeof ClientAgentConfig>;
+/** A first-party tool's owner: a capability, or pure runtime mechanics. */
+export type AgentToolCapability = AgentCapabilityId | "runtime";
+/**
+ * Exhaustive map from every `FIRST_PARTY_MCP_TOOL_NAMES` entry to exactly one
+ * owner. The `Record` type makes an unmapped new name a compile error, and
+ * `agent-config-registry.test.ts` asserts it at runtime too.
+ *
+ * `runtime` tools are mechanics every agent needs regardless of what it may do:
+ * - `wait_for_input`: ends the turn and waits for the next input.
+ * - `command_read` / `command_wait`: read/await the session's own background
+ *   sandbox commands (the shell already exists whenever a sandbox is attached).
+ * - `set_session_title`: session titling.
+ */
+export declare const FIRST_PARTY_MCP_TOOL_CAPABILITIES: {
+    readonly set_session_title: "runtime";
+    readonly wait_for_input: "runtime";
+    readonly command_wait: "runtime";
+    readonly command_read: "runtime";
+    readonly goal_set: "goals";
+    readonly goal_update: "goals";
+    readonly goal_progress: "goals";
+    readonly goal_complete: "goals";
+    readonly goal_pause: "goals";
+    readonly goal_resume: "goals";
+    readonly knowledge_search: "knowledge";
+    readonly knowledge_prepare_save: "knowledge";
+    readonly knowledge_get: "knowledge";
+    readonly knowledge_browse: "knowledge";
+    readonly knowledge_save: "knowledge";
+    readonly knowledge_retain_file: "knowledge";
+    readonly knowledge_retain_message: "knowledge";
+    readonly knowledge_archive: "knowledge";
+    readonly instruction_policy_save: "knowledge";
+    readonly instruction_policy_get: "knowledge";
+    readonly memory_search: "knowledge";
+    readonly memory_save: "knowledge";
+    readonly memory_correct: "knowledge";
+    readonly preference_registry_summary: "knowledge";
+    readonly preference_registry_get: "knowledge";
+    readonly task_notes_list: "knowledge";
+    readonly task_note_save: "knowledge";
+    readonly task_note_archive: "knowledge";
+    readonly task_note_replace: "knowledge";
+    readonly work_claim_upsert: "knowledge";
+    readonly work_claim_release: "knowledge";
+    readonly knowledge_propose: "knowledge";
+    readonly knowledge_correct: "knowledge";
+    readonly task_note_promote_knowledge: "knowledge";
+    readonly task_note_promote_instruction_policy: "knowledge";
+    readonly task_note_promote_preference: "knowledge";
+    readonly instruction_policy_propose: "knowledge";
+    readonly preference_propose: "knowledge";
+    readonly remember: "knowledge";
+    readonly remember_confirm: "knowledge";
+    readonly company_profile_propose: "knowledge";
+    readonly company_profile_confirm: "knowledge";
+    readonly sandboxes_list: "workspaceAdmin";
+    readonly sandbox_attach: "workspaceAdmin";
+    readonly sandbox_swap: "workspaceAdmin";
+    readonly run_on: "workspaceAdmin";
+    readonly sandbox_provision: "workspaceAdmin";
+    readonly connected_machine_remove: "workspaceAdmin";
+    readonly connected_machine_enroll_token: "workspaceAdmin";
+    readonly project_list: "workspaceAdmin";
+    readonly project_get: "workspaceAdmin";
+    readonly project_create: "workspaceAdmin";
+    readonly project_update: "workspaceAdmin";
+    readonly project_reorder: "workspaceAdmin";
+    readonly project_delete: "workspaceAdmin";
+    readonly session_set_project: "workspaceAdmin";
+    readonly rig_list: "workspaceAdmin";
+    readonly rig_get: "workspaceAdmin";
+    readonly rig_propose_change: "workspaceAdmin";
+    readonly rig_verify: "workspaceAdmin";
+    readonly rig_promote: "workspaceAdmin";
+    readonly variable_set_list: "workspaceAdmin";
+    readonly environment_list: "workspaceAdmin";
+    readonly variable_set_get_variable: "workspaceAdmin";
+    readonly variable_set_set_variable: "workspaceAdmin";
+    readonly environment_set_variable: "workspaceAdmin";
+    readonly capability_catalog_search: "workspaceAdmin";
+    readonly capability_authorization_request: "workspaceAdmin";
+    readonly custom_mcp_setup_request: "workspaceAdmin";
+    readonly sessions_list: "subagents";
+    readonly session_get: "subagents";
+    readonly session_events: "subagents";
+    readonly session_wait: "subagents";
+    readonly session_create: "subagents";
+    readonly session_send_message: "subagents";
+    readonly session_pause: "subagents";
+    readonly session_resume: "subagents";
+    readonly session_steer: "subagents";
+    readonly session_human_input_respond: "subagents";
+    readonly set_other_session_title: "subagents";
+    readonly session_set_model: "subagents";
+    readonly interaction_discover: "browser";
+    readonly browser_open: "browser";
+    readonly browser_tabs: "browser";
+    readonly browser_observe: "browser";
+    readonly browser_read: "browser";
+    readonly browser_screenshot: "browser";
+    readonly browser_act: "browser";
+    readonly browser_clipboard: "browser";
+    readonly browser_debug: "browser";
+    readonly browser_auth: "browser";
+    readonly interaction_request_human: "browser";
+    readonly browser_identity: "browser";
+    readonly browser_publish: "browser";
+    readonly browser_lifecycle: "browser";
+    readonly computer_open: "browser";
+    readonly computer_targets: "browser";
+    readonly computer_observe: "browser";
+    readonly computer_clipboard: "browser";
+    readonly computer_act: "browser";
+    readonly computer_lifecycle: "browser";
+    readonly github_connect_link: "workspaceConnectors";
+    readonly github_repositories_list: "workspaceConnectors";
+    readonly social_connections_list: "workspaceConnectors";
+    readonly social_posts_recent: "workspaceConnectors";
+    readonly social_daily_analysis_context: "workspaceConnectors";
+    readonly social_search_live: "workspaceConnectors";
+    readonly social_mentions_live: "workspaceConnectors";
+    readonly social_thread_fetch: "workspaceConnectors";
+    readonly social_posts_sync: "workspaceConnectors";
+    readonly social_post_reply: "workspaceConnectors";
+    readonly x_accounts_list: "workspaceConnectors";
+    readonly x_search_live: "workspaceConnectors";
+    readonly x_mentions_live: "workspaceConnectors";
+    readonly x_thread_fetch: "workspaceConnectors";
+    readonly x_posts_sync: "workspaceConnectors";
+    readonly x_post_reply: "workspaceConnectors";
+    readonly reddit_accounts_list: "workspaceConnectors";
+    readonly reddit_search_live: "workspaceConnectors";
+    readonly reddit_mentions_live: "workspaceConnectors";
+    readonly reddit_thread_fetch: "workspaceConnectors";
+    readonly reddit_posts_sync: "workspaceConnectors";
+    readonly reddit_post_reply: "workspaceConnectors";
+    readonly slack_bot_list_channels: "workspaceConnectors";
+    readonly slack_bot_search: "workspaceConnectors";
+    readonly slack_bot_channel_history: "workspaceConnectors";
+    readonly slack_bot_thread_replies: "workspaceConnectors";
+    readonly slack_bot_list_users: "workspaceConnectors";
+    readonly slack_bot_list_files: "workspaceConnectors";
+    readonly slack_bot_file_info: "workspaceConnectors";
+    readonly slack_bot_file_content: "workspaceConnectors";
+    readonly slack_bot_upload_file: "workspaceConnectors";
+    readonly slack_bot_post_message: "workspaceConnectors";
+    readonly slack_bot_delete_message: "workspaceConnectors";
+    readonly slack_bot_prepare_message: "workspaceConnectors";
+    readonly slack_bot_send_prepared_message: "workspaceConnectors";
+    readonly fiken_companies_list: "workspaceConnectors";
+    readonly fiken_contacts_list: "workspaceConnectors";
+    readonly fiken_contact_create: "workspaceConnectors";
+    readonly fiken_products_list: "workspaceConnectors";
+    readonly fiken_invoices_list: "workspaceConnectors";
+    readonly fiken_invoice_get: "workspaceConnectors";
+    readonly fiken_invoice_draft_create: "workspaceConnectors";
+    readonly fiken_bank_accounts_list: "workspaceConnectors";
+    readonly fiken_purchases_list: "workspaceConnectors";
+    readonly fiken_sales_list: "workspaceConnectors";
+    readonly atlassian_sources_list: "workspaceConnectors";
+    readonly atlassian_search: "workspaceConnectors";
+    readonly atlassian_get: "workspaceConnectors";
+    readonly scheduled_tasks_list: "schedules";
+    readonly scheduled_tasks_get: "schedules";
+    readonly scheduled_tasks_create: "schedules";
+    readonly scheduled_tasks_update: "schedules";
+    readonly scheduled_tasks_pause: "schedules";
+    readonly scheduled_tasks_resume: "schedules";
+    readonly scheduled_tasks_trigger: "schedules";
+    readonly scheduled_tasks_delete: "schedules";
+    readonly scheduled_task_runs_list: "schedules";
+    readonly artifacts_list: "artifacts";
+    readonly artifacts_get_source: "artifacts";
+    readonly artifacts_prepare_upload: "artifacts";
+    readonly artifacts_create: "artifacts";
+    readonly artifacts_publish: "artifacts";
+    readonly artifacts_rollback: "artifacts";
+    readonly artifacts_archive: "artifacts";
+    readonly artifacts_restore: "artifacts";
+    readonly sandbox_file_publish: "artifacts";
+    readonly editable_artifact_list: "artifacts";
+    readonly editable_artifact_create: "artifacts";
+    readonly editable_artifact_import: "artifacts";
+    readonly editable_artifact_get: "artifacts";
+    readonly editable_artifact_inspect: "artifacts";
+    readonly editable_artifact_apply: "artifacts";
+    readonly editable_artifact_export: "artifacts";
+    readonly editable_artifact_export_status: "artifacts";
+};
+/** Owner of a non-MCP tool: a capability, runtime mechanics, or the sandbox. */
+export type AgentFunctionToolClass = AgentCapabilityId | "runtime" | "sandbox";
+/** Tools served outside the first-party MCP catalog, by the name the model sees. */
+export declare const AGENT_FUNCTION_TOOL_CAPABILITIES: {
+    readonly web_search: "webSearch";
+    readonly x_search: "webSearch";
+    readonly image_generation: "media";
+    readonly request_human_input: "humanInput";
+    readonly list_models: "subagents";
+    readonly generate_image: "media";
+    readonly generate_video: "media";
+    readonly get_video_generation_capabilities: "media";
+    readonly skill_read: "skills";
+    readonly skill_search: "skills";
+    readonly skill_checkout: "skills";
+    readonly skill_save: "skills";
+    readonly skill_install: "skills";
+    readonly skill_publish: "skills";
+    readonly skill_remove: "skills";
+    readonly exec_command: "sandbox";
+    readonly write_stdin: "sandbox";
+    readonly apply_patch: "sandbox";
+    readonly view_image: "sandbox";
+    readonly repository_skill_read: "sandbox";
+    readonly code_search: "sandbox";
+    readonly tool_search: "runtime";
+    readonly tool_list: "runtime";
+    readonly tool_invoke: "runtime";
+    readonly operation_read: "runtime";
+    readonly refresh_credentials: "runtime";
+    readonly knowledge_source_fetch: "runtime";
+    readonly knowledge_source_read: "runtime";
+};
+export type AgentFunctionToolName = keyof typeof AGENT_FUNCTION_TOOL_CAPABILITIES;
+/**
+ * Value-free snapshot of the adapters actually selected for one runtime build.
+ * Undefined means attachment has not been resolved, not that media is absent.
+ * Subscription pool readiness is not evidence for either adapter.
+ */
+export type AgentMediaAttachment = {
+    image: "native_hosted" | "provider_adapter" | null;
+    video: boolean;
+};
+export declare function resolveAgentMediaToolSurface(config: ResolvedAgentConfig | null | undefined, attachment?: AgentMediaAttachment): {
+    toolsKnown: boolean;
+    hosted: AgentFunctionToolName[];
+    runtime: AgentFunctionToolName[];
+};
+/** Skill tools that only read installed Skills (`skills: "read"`). */
+export declare const AGENT_SKILL_READ_TOOL_NAMES: readonly ["skill_read"];
+/** Skill tools that change Skills (`skills: "manage"` only). */
+export declare const AGENT_SKILL_MANAGE_TOOL_NAMES: readonly ["skill_search", "skill_checkout", "skill_save", "skill_install", "skill_publish", "skill_remove"];
+/** Built-in MCP servers that belong to a capability rather than the product. */
+export declare const AGENT_BUILTIN_MCP_SERVER_CAPABILITIES: {
+    readonly opengeni: "runtime";
+    readonly files: "workspaceFiles";
+    readonly docs: "knowledge";
+    readonly "google-drive-publishing": "workspaceConnectors";
+};
+export declare function firstPartyMcpToolCapability(tool: FirstPartyMcpToolName): AgentToolCapability;
+/** Availability narrows configuration; it never grants a disabled capability. */
+export type AgentToolEnvironment = {
+    /** Explicit product MCPs are independent of ambient workspace connectors. */
+    productServerIds?: ReadonlySet<string>;
+    unavailable?: readonly AgentCapabilityId[];
+    hasSkills?: boolean;
+    webSearch?: boolean;
+    humanInput?: boolean;
+    media?: boolean | undefined;
+    hasDeferredTools?: boolean;
+    routerInHistory?: boolean;
+};
+export declare const AGENT_RUNTIME_MECHANIC_TOOL_NAMES: readonly ["wait_for_input", "command_read", "command_wait"];
+/**
+ * The one turn-time capability gate. Null means the historical attachment
+ * rules, including unconditional Skill tools and router. Resource-derived
+ * sandbox tools, product MCPs and runtime mechanics are never toggled.
+ */
+export declare function resolveAgentToolFamilies(config: ResolvedAgentConfig | null | undefined, environment?: AgentToolEnvironment): {
+    webSearch: boolean;
+    humanInput: boolean;
+    media: boolean;
+    subagents: boolean;
+    skills: "manage" | "read" | false;
+    router: boolean;
+    allowsFirstPartyTool: (name: FirstPartyMcpToolName) => boolean;
+    firstPartyTools(names: readonly FirstPartyMcpToolName[]): FirstPartyMcpToolName[];
+    allowsFunctionTool(name: string): boolean;
+    allowsMcpServer(id: string): boolean;
+};
+export declare function firstPartyMcpToolsForCapability(capability: AgentCapabilityId): FirstPartyMcpToolName[];
+/** Product words for UI and docs. Meaning is fixed by the ids. */
+export declare const AGENT_CAPABILITY_DESCRIPTIONS: Readonly<Record<AgentCapabilityId, {
+    label: string;
+    description: string;
+}>>;
+/**
+ * Sections of the modular operational contract (sessions with an agent
+ * configuration). The order is the composition order. `base_behavior` and
+ * `runtime_mechanics` are always present; every other module is included only
+ * when its capability or resource is present. The model-context inspector
+ * reports them as metadata on the `operational_contract` layer.
+ */
+export declare const AGENT_PROMPT_MODULE_IDS: readonly ["base_behavior", "runtime_mechanics", "renderer_markdown", "sandbox", "connected_machine", "repositories", "workspace_environment", "rig", "artifacts", "goals", "subagents", "knowledge", "skills", "admin", "attachments"];
+export declare const AgentPromptModuleId: z.ZodEnum<{
+    admin: "admin";
+    artifacts: "artifacts";
+    attachments: "attachments";
+    base_behavior: "base_behavior";
+    connected_machine: "connected_machine";
+    goals: "goals";
+    knowledge: "knowledge";
+    renderer_markdown: "renderer_markdown";
+    repositories: "repositories";
+    rig: "rig";
+    runtime_mechanics: "runtime_mechanics";
+    sandbox: "sandbox";
+    skills: "skills";
+    subagents: "subagents";
+    workspace_environment: "workspace_environment";
+}>;
+export type AgentPromptModuleId = z.infer<typeof AgentPromptModuleId>;
+export declare const AGENT_PROMPT_MODULE_TITLES: Readonly<Record<AgentPromptModuleId, string>>;
+/** The prompt module each capability owns; capabilities absent here own none. */
+export declare const AGENT_CAPABILITY_PROMPT_MODULES: Readonly<Partial<Record<AgentCapabilityId, readonly AgentPromptModuleId[]>>>;
+export declare const AgentConfigErrorCode: z.ZodEnum<{
+    agent_capability_unavailable: "agent_capability_unavailable";
+    agent_config_conflict: "agent_config_conflict";
+    agent_config_not_enabled: "agent_config_not_enabled";
+    agent_config_widening: "agent_config_widening";
+}>;
+export type AgentConfigErrorCode = z.infer<typeof AgentConfigErrorCode>;
+/** Typed resolution failure. Transports render it as 422 with `details.code`. */
+export declare class AgentConfigError extends Error {
+    readonly code: AgentConfigErrorCode;
+    readonly capability: AgentCapabilityId | undefined;
+    constructor(code: AgentConfigErrorCode, message: string, capability?: AgentCapabilityId);
+}
+export declare function isAgentConfigError(error: unknown): error is AgentConfigError;
+export declare function allAgentCapabilities(): ResolvedAgentCapabilities;
+/** `"none"`: the session's own tools plus the essentials. */
+export declare function noneAgentCapabilities(): ResolvedAgentCapabilities;
+export declare function agentCapabilityEnabled(capabilities: ResolvedAgentCapabilities, id: AgentCapabilityId): boolean;
+/** Clamp `value` to `ceiling` (children and agent callers never widen). */
+export declare function intersectAgentCapabilities(value: ResolvedAgentCapabilities, ceiling: ResolvedAgentCapabilities): ResolvedAgentCapabilities;
+/** First capability `value` enables beyond `ceiling`, or null. */
+export declare function agentCapabilityWidening(value: ResolvedAgentCapabilities, ceiling: ResolvedAgentCapabilities): AgentCapabilityId | null;
+/** Hard limits: capabilities this deployment does not offer, with a reason. */
+export type AgentConfigDeploymentLimits = {
+    unavailable: Partial<Record<AgentCapabilityId, string>>;
+};
+export type AgentConfigCreator = "api" | "slack" | "scheduled" | "automation" | "site_auth_maintenance";
+/** What the workspace offers when a configuration is being created. */
+export type AgentConfigWorkspaceContext = {
+    /** Explicit `settings.sessionAgentDefaults`, honored only with admission enabled. */
+    defaults: WorkspaceAgentDefaults | null;
+    /** Legacy `settings.agentHumanInputEnabled`; false maps to `humanInput: false`. */
+    humanInputEnabled: boolean;
+};
+export type AgentConfigParent = {
+    kind: "configured";
+    config: ResolvedAgentConfig;
+}
+/** A null-config parent: its current effective capabilities are the ceiling. */
+ | {
+    kind: "legacy";
+    ceiling: ResolvedAgentCapabilities;
+};
+export type ResolveAgentConfigInput = {
+    creator: AgentConfigCreator;
+    /** The request `agent` object; undefined when omitted. */
+    request?: AgentConfigRequest | undefined;
+    /** The legacy session `instructions` field (alias target). */
+    instructions?: string | undefined;
+    workspace: AgentConfigWorkspaceContext;
+    deployment: AgentConfigDeploymentLimits & {
+        admissionEnabled: boolean;
+        defaultForNewSessions: boolean;
+    };
+    /** Undefined for a top-level session. */
+    parent?: AgentConfigParent | undefined;
+    /** Whether the new session carries a goal. */
+    goal: boolean;
+};
+export type ResolveAgentConfigResult = {
+    config: ResolvedAgentConfig | null;
+    /** The effective session instructions after the alias rule. */
+    instructions: string | undefined;
+};
+/**
+ * Resolve the frozen agent configuration for a new session.
+ *
+ * Order: deployment limits, then the workspace default, then the request, then
+ * the parent (children only narrow). Returns `config: null` (exact legacy)
+ * when nothing asks for a configuration: no request `agent`, no configured
+ * parent, no honored workspace default, and the default-for-new-sessions
+ * switch off (or a legacy parent, which keeps its tree legacy).
+ */
+export declare function resolveAgentConfig(input: ResolveAgentConfigInput): ResolveAgentConfigResult;
+/**
+ * Resolve a mid-session update. Omitted fields keep the current values; a
+ * legacy (null) session converts from `legacyCeiling` (its current effective
+ * state). Agent callers may only narrow.
+ */
+export declare function resolveAgentConfigUpdate(input: {
+    current: ResolvedAgentConfig | null;
+    legacyCeiling: ResolvedAgentCapabilities;
+    request: AgentConfigRequest;
+    deployment: AgentConfigDeploymentLimits & {
+        admissionEnabled: boolean;
+    };
+    onlyNarrow: boolean;
+    /** A parent's configuration or legacy ceiling; children never widen past it. */
+    parentCeiling?: ResolvedAgentCapabilities | undefined;
+    goal: boolean;
+}): ResolvedAgentConfig;
+/**
+ * Narrow a creator's first-party selection (its exact legacy value) to the
+ * enabled capabilities. `"all"` returns `baseline` unchanged. `explicit`, when
+ * the request listed `firstPartyMcpTools` itself, must not name a tool of a
+ * capability the configuration turns off.
+ */
+export declare function agentConfigFirstPartyMcpTools(config: ResolvedAgentConfig, baseline: readonly FirstPartyMcpToolName[], explicit?: readonly FirstPartyMcpToolName[]): FirstPartyMcpToolName[];
+/**
+ * First-party tools a capability change adds on top of the current selection:
+ * the default-selection tools of every capability that `next` enables and
+ * `previous` did not. Unchanged capabilities keep their exact current tools.
+ */
+export declare function agentConfigAddedFirstPartyMcpTools(previous: ResolvedAgentCapabilities, next: ResolvedAgentConfig, defaults: readonly FirstPartyMcpToolName[]): FirstPartyMcpToolName[];
+export type AgentConfigToolRefsInput = {
+    config: ResolvedAgentConfig;
+    tools: readonly ToolRef[];
+    toolPolicy: SessionToolPolicy;
+    /** Product servers: attached to this session or named explicitly by the request. */
+    productServerIds: ReadonlySet<string>;
+    /** Server ids the request's explicit `tools` named (strict conflict check). */
+    explicitServerIds?: ReadonlySet<string>;
+};
+/**
+ * Apply `workspaceFiles`, `knowledge` (the `docs` server) and
+ * `workspaceConnectors` to the stored tool refs and policy. A workspace-default
+ * policy keeps tracking defaults with `files`/`docs` excluded when their
+ * capability is off; with connectors off it becomes an explicit policy holding
+ * only product refs (plus enabled built-ins), so no workspace default connector
+ * ever reaches the session. `"all"` returns the input unchanged.
+ */
+export declare function agentConfigToolRefs(input: AgentConfigToolRefsInput): {
+    tools: ToolRef[];
+    toolPolicy: SessionToolPolicy;
+};
+/**
+ * The effective capabilities of a null-config (legacy) session, used as the
+ * ceiling when a child asks for an explicit configuration and when a legacy
+ * session converts on its first update. Legacy sessions always carry web
+ * search, media, list_models and every Skill tool, so those are on.
+ */
+export declare function legacyEffectiveAgentCapabilities(input: {
+    firstPartyMcpTools: readonly FirstPartyMcpToolName[];
+    tools: readonly ToolRef[];
+    toolPolicy: SessionToolPolicy;
+    humanInputEnabled: boolean;
+    /**
+     * The workspace's current omitted-tools default server ids, when known. A
+     * workspace-default session only has `files`/`docs`/connectors that are
+     * actually defaults; without this the ceiling assumes they are.
+     */
+    defaultServerIds?: Iterable<string> | undefined;
+}): ResolvedAgentCapabilities;
+/**
+ * Deployment limits derivable from the deployment's first-party ceiling: a
+ * capability whose every first-party tool is outside the allowlist is not
+ * offered. Callers add feature flags (for example hosted web search).
+ */
+export declare function agentConfigDeploymentLimitsFromAllowlist(allowed: readonly FirstPartyMcpToolName[], extra?: Partial<Record<AgentCapabilityId, string>>): AgentConfigDeploymentLimits;
+export type AgentEffectiveToolEntry = {
+    name: string;
+    capability: AgentCapabilityId | "runtime" | "sandbox" | "product";
+    source: "first_party" | "runtime" | "hosted" | "sandbox" | "mcp";
+    visibility?: "upfront" | "search";
+};
+export type AgentEffectiveMcpServerEntry = {
+    id: string;
+    capability: AgentCapabilityId | "runtime" | "product";
+    toolsKnown: boolean;
+};
+export declare const AgentEffectiveTools: z.ZodObject<{
+    capabilities: z.ZodObject<{
+        webSearch: z.ZodBoolean;
+        humanInput: z.ZodBoolean;
+        skills: z.ZodUnion<readonly [z.ZodLiteral<"read">, z.ZodLiteral<"manage">, z.ZodLiteral<false>]>;
+        goals: z.ZodBoolean;
+        subagents: z.ZodBoolean;
+        knowledge: z.ZodBoolean;
+        schedules: z.ZodBoolean;
+        artifacts: z.ZodBoolean;
+        browser: z.ZodBoolean;
+        media: z.ZodBoolean;
+        workspaceFiles: z.ZodBoolean;
+        workspaceConnectors: z.ZodBoolean;
+        workspaceAdmin: z.ZodBoolean;
+    }, z.core.$strict>;
+    unavailable: z.ZodArray<z.ZodEnum<{
+        artifacts: "artifacts";
+        browser: "browser";
+        goals: "goals";
+        humanInput: "humanInput";
+        knowledge: "knowledge";
+        media: "media";
+        schedules: "schedules";
+        skills: "skills";
+        subagents: "subagents";
+        webSearch: "webSearch";
+        workspaceAdmin: "workspaceAdmin";
+        workspaceConnectors: "workspaceConnectors";
+        workspaceFiles: "workspaceFiles";
+    }>>;
+    mediaToolsKnown: z.ZodOptional<z.ZodBoolean>;
+    tools: z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        capability: z.ZodUnion<readonly [z.ZodEnum<{
+            artifacts: "artifacts";
+            browser: "browser";
+            goals: "goals";
+            humanInput: "humanInput";
+            knowledge: "knowledge";
+            media: "media";
+            schedules: "schedules";
+            skills: "skills";
+            subagents: "subagents";
+            webSearch: "webSearch";
+            workspaceAdmin: "workspaceAdmin";
+            workspaceConnectors: "workspaceConnectors";
+            workspaceFiles: "workspaceFiles";
+        }>, z.ZodLiteral<"runtime">, z.ZodLiteral<"sandbox">, z.ZodLiteral<"product">]>;
+        source: z.ZodEnum<{
+            first_party: "first_party";
+            hosted: "hosted";
+            mcp: "mcp";
+            runtime: "runtime";
+            sandbox: "sandbox";
+        }>;
+        visibility: z.ZodOptional<z.ZodEnum<{
+            search: "search";
+            upfront: "upfront";
+        }>>;
+    }, z.core.$strict>>;
+    mcpServers: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        capability: z.ZodUnion<readonly [z.ZodEnum<{
+            artifacts: "artifacts";
+            browser: "browser";
+            goals: "goals";
+            humanInput: "humanInput";
+            knowledge: "knowledge";
+            media: "media";
+            schedules: "schedules";
+            skills: "skills";
+            subagents: "subagents";
+            webSearch: "webSearch";
+            workspaceAdmin: "workspaceAdmin";
+            workspaceConnectors: "workspaceConnectors";
+            workspaceFiles: "workspaceFiles";
+        }>, z.ZodLiteral<"runtime">, z.ZodLiteral<"product">]>;
+        toolsKnown: z.ZodBoolean;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export type AgentEffectiveTools = z.infer<typeof AgentEffectiveTools>;
+/**
+ * Project known model tools through the same turn-time gates. External MCP
+ * schemas are never guessed: their server stays toolsKnown:false until listed.
+ */
+export declare function projectAgentEffectiveTools(input: {
+    config: ResolvedAgentConfig;
+    firstPartyMcpTools: readonly FirstPartyMcpToolName[];
+    mcpServerIds: readonly string[];
+    /** Servers attached to the session itself; other non-built-in ids are workspace connectors. */
+    productServerIds: ReadonlySet<string>;
+    environment?: AgentToolEnvironment;
+    runtimeToolNames?: readonly AgentFunctionToolName[];
+    hostedToolNames?: readonly AgentFunctionToolName[];
+    sandboxToolNames?: readonly AgentFunctionToolName[];
+    routerToolNames?: readonly AgentFunctionToolName[];
+    /** Raw first-party names; other entries use model-facing names. */
+    upfrontToolNames?: ReadonlySet<string>;
+    firstPartyModelNames?: ReadonlyMap<FirstPartyMcpToolName, string>;
+    mediaAttachment?: AgentMediaAttachment | undefined;
+}): AgentEffectiveTools;