@red-hat-developer-hub/backstage-plugin-augment-common 0.2.0

package/dist/index.d.ts

@@ -0,0 +1,2095 @@
+import * as _backstage_plugin_permission_common from '@backstage/plugin-permission-common';
+
+/**
+ * Permission to access the Augment plugin.
+ *
+ * Controls access to ALL Augment features. If a user has this
+ * permission, they get full access. If not, they are blocked entirely.
+ *
+ * @public
+ */
+declare const augmentAccessPermission: _backstage_plugin_permission_common.BasicPermission;
+/**
+ * Permission to access admin features of the Augment plugin.
+ *
+ * Controls access to admin-only features such as document management,
+ * swim lane/prompt editing, system prompt configuration, and branding.
+ * Users with this permission see additional admin tabs in the UI.
+ *
+ * @public
+ */
+declare const augmentAdminPermission: _backstage_plugin_permission_common.BasicPermission;
+/**
+ * List of all Augment permissions.
+ *
+ * To restrict access to a Keycloak group, configure RBAC policies in app-config.yaml:
+ *
+ * @example
+ * ```yaml
+ * permission:
+ *   enabled: true
+ *   rbac:
+ *     policies:
+ *       - g, group:default/augment-users, role:default/augment-user
+ *       - p, role:default/augment-user, augment.access, read, allow
+ *       - g, group:default/augment-admins, role:default/augment-admin
+ *       - p, role:default/augment-admin, augment.access, read, allow
+ *       - p, role:default/augment-admin, augment.admin, update, allow
+ * ```
+ *
+ * @public
+ */
+declare const augmentPermissions: _backstage_plugin_permission_common.BasicPermission[];
+
+/**
+ * Token usage reported by the inference server for a single response turn.
+ *
+ * Mirrors the OpenAI Responses API `ResponseUsage` object.
+ * Llama Stack implements the same schema, so this type is
+ * the single source of truth for both frontend and backend.
+ *
+ * @see https://platform.openai.com/docs/api-reference/responses/object
+ * @public
+ */
+interface ResponseUsage {
+    /** Total input tokens (cumulative across all internal agentic calls) */
+    input_tokens: number;
+    /** Total output tokens (cumulative across all internal agentic calls) */
+    output_tokens: number;
+    /** Sum of input_tokens + output_tokens (may include internal overhead) */
+    total_tokens: number;
+    /**
+     * Breakdown of input tokens.
+     * Present when the server supports prompt caching.
+     */
+    input_tokens_details?: InputTokensDetails;
+    /**
+     * Breakdown of output tokens.
+     * Llama Stack may return `null` when the model does not emit reasoning tokens.
+     */
+    output_tokens_details?: OutputTokensDetails | null;
+}
+/**
+ * Detailed breakdown of input tokens.
+ * @public
+ */
+interface InputTokensDetails {
+    /** Tokens retrieved from the KV-cache (no additional compute cost) */
+    cached_tokens?: number;
+}
+/**
+ * Detailed breakdown of output tokens.
+ * @public
+ */
+interface OutputTokensDetails {
+    /** Internal chain-of-thought tokens used by reasoning models (e.g. o3, o4-mini) */
+    reasoning_tokens?: number;
+}
+/**
+ * Chat message in a conversation
+ * @public
+ */
+interface ChatMessage {
+    role: 'system' | 'user' | 'assistant';
+    content: string;
+}
+/**
+ * Tool call information
+ * @public
+ */
+interface ToolCallInfo {
+    id: string;
+    name: string;
+    serverLabel: string;
+    arguments: string;
+    output?: string;
+    error?: string;
+}
+/**
+ * RAG source information from file_search_call.results
+ * This comes directly from Llama Stack Responses API when include: ['file_search_call.results']
+ * @public
+ */
+interface RAGSource {
+    /** Filename or document identifier */
+    filename: string;
+    /** Relevant text snippet from the document */
+    text?: string;
+    /** Relevance score (0-1) if provided by the API */
+    score?: number;
+    /** File ID for reference */
+    fileId?: string;
+    /** Document title from attributes (for display in citations) */
+    title?: string;
+    /** Source URL from attributes (for clickable citations) */
+    sourceUrl?: string;
+    /** Content type from attributes */
+    contentType?: string;
+    /** Raw attributes object from Llama Stack */
+    attributes?: Record<string, unknown>;
+}
+/**
+ * Aggregated evaluation result for a response
+ * @public
+ */
+interface EvaluationResult {
+    /** Overall quality score (0-1) */
+    overallScore: number;
+    /** Individual scores by function */
+    scores: Record<string, number>;
+    /** Whether the response passed quality threshold */
+    passedThreshold: boolean;
+    /** Human-readable quality assessment */
+    qualityLevel: 'excellent' | 'good' | 'fair' | 'poor';
+    /** Timestamp of evaluation */
+    evaluatedAt: string;
+    /** Error message if evaluation failed */
+    error?: string;
+    /** True when evaluation was skipped (e.g. not available) rather than run */
+    skipped?: boolean;
+}
+/**
+ * File format enum
+ * @public
+ */
+declare enum FileFormat {
+    YAML = "yaml",
+    PDF = "pdf",
+    TEXT = "text",
+    MARKDOWN = "markdown",
+    JSON = "json"
+}
+/**
+ * Information about an uploaded document
+ * @public
+ */
+interface DocumentInfo {
+    id: string;
+    fileName: string;
+    format: FileFormat;
+    fileSize: number;
+    uploadedAt: string;
+    status: 'completed' | 'in_progress' | 'failed' | 'cancelled';
+}
+/**
+ * Provider status information
+ * @public
+ */
+interface ProviderStatus {
+    id: string;
+    model: string;
+    baseUrl: string;
+    connected: boolean;
+    error?: string;
+}
+/**
+ * Vector store status information
+ * @public
+ */
+interface VectorStoreStatus {
+    id: string;
+    connected: boolean;
+    totalDocuments?: number;
+    error?: string;
+}
+/**
+ * MCP server status information
+ * @public
+ */
+interface MCPToolInfo {
+    name: string;
+    description?: string;
+}
+/**
+ * @public
+ */
+interface MCPServerStatus {
+    id: string;
+    name: string;
+    url: string;
+    connected: boolean;
+    error?: string;
+    /** Tools available on this MCP server (populated when connected) */
+    tools?: MCPToolInfo[];
+    /** Total number of tools (convenience field) */
+    toolCount?: number;
+    /** Whether this server was defined in YAML (true) or added via admin UI (false) */
+    source?: 'yaml' | 'admin';
+}
+/**
+ * Security mode for Augment
+ * @public
+ */
+type SecurityMode = 'none' | 'plugin-only' | 'full';
+/**
+ * Combined status for Augment
+ * @public
+ */
+interface AugmentStatus {
+    /** Active provider identifier (e.g., 'llamastack', 'googleadk') */
+    providerId: string;
+    provider: ProviderStatus;
+    vectorStore: VectorStoreStatus;
+    mcpServers: MCPServerStatus[];
+    /** Current security mode: 'none' | 'plugin-only' | 'full' */
+    securityMode: SecurityMode;
+    timestamp: string;
+    /** Whether the plugin is ready to handle requests (AI provider connected) */
+    ready: boolean;
+    /** Blocking configuration errors that prevent the plugin from working */
+    configurationErrors: string[];
+    /** Whether the current user has admin privileges */
+    isAdmin?: boolean;
+    /** Optional capability status — these are not required for basic chat */
+    capabilities?: {
+        chat: boolean;
+        rag: {
+            available: boolean;
+            reason?: string;
+        };
+        mcpTools: {
+            available: boolean;
+            reason?: string;
+        };
+        /** Whether this provider supports listing agents for the catalog */
+        agentCatalog?: boolean;
+        /** Whether the user must select an agent before chatting */
+        agentSelection?: boolean;
+        /** Whether agents have rich metadata (cards, skills) */
+        agentCards?: boolean;
+    };
+    /** Summary of configured agents (multi-agent only) */
+    agents?: Array<{
+        key: string;
+        name: string;
+        isDefault: boolean;
+    }>;
+    /** Tool execution mode: 'direct' or 'backend' */
+    toolExecutionMode?: 'direct' | 'backend';
+    /** Error from last agent graph resolution attempt, if any */
+    agentGraphError?: string;
+}
+/**
+ * Information about an available vector store
+ * @public
+ */
+interface VectorStoreInfo {
+    id: string;
+    name: string;
+    status: string;
+    fileCount: number;
+    createdAt: number;
+    embeddingModel?: string;
+    embeddingDimension?: number;
+    providerType?: string;
+    usageBytes?: number;
+    lastActiveAt?: number;
+    fileCounts?: {
+        completed: number;
+        inProgress: number;
+        failed: number;
+        cancelled: number;
+        total: number;
+    };
+}
+/**
+ * Quick prompt configuration
+ * @public
+ */
+interface QuickPrompt {
+    title: string;
+    description: string;
+    prompt: string;
+    category: string;
+}
+/**
+ * A single step within a workflow
+ * @public
+ */
+interface WorkflowStep {
+    /** Step title shown in UI */
+    title: string;
+    /** Prompt to send to chat when this step is executed */
+    prompt: string;
+    /** Optional description for the step */
+    description?: string;
+}
+/**
+ * A workflow template - multi-step guided experience
+ * @public
+ */
+interface Workflow {
+    /** Unique identifier */
+    id: string;
+    /** Display name */
+    name: string;
+    /** Short description */
+    description: string;
+    /** Icon name (material icons) */
+    icon?: string;
+    /** Category for grouping */
+    category?: string;
+    /** Ordered list of steps */
+    steps: WorkflowStep[];
+    /** Whether this workflow is coming soon (disabled, non-clickable) */
+    comingSoon?: boolean;
+    /** Custom coming soon label (defaults to "Coming Soon") */
+    comingSoonLabel?: string;
+}
+/**
+ * Quick action - single click prompt
+ * @public
+ */
+interface QuickAction {
+    /** Display title */
+    title: string;
+    /** Short description */
+    description?: string;
+    /** Prompt to send to chat */
+    prompt: string;
+    /** Icon name */
+    icon?: string;
+    /** Category for grouping */
+    category?: string;
+    /** Whether this action is coming soon (disabled, non-clickable) */
+    comingSoon?: boolean;
+    /** Custom coming soon label (defaults to "Coming Soon") */
+    comingSoonLabel?: string;
+}
+/**
+ * A clickable prompt card within a prompt group on the welcome screen
+ * @public
+ */
+interface PromptCard {
+    /** Display title */
+    title: string;
+    /** Short description */
+    description?: string;
+    /** Prompt to send to chat */
+    prompt: string;
+    /** Icon name */
+    icon?: string;
+    /** Agent to auto-select when this card is clicked (e.g. "namespace/agentName") */
+    agentId?: string;
+    /** Whether this feature is coming soon (disabled, non-clickable) */
+    comingSoon?: boolean;
+    /** Custom coming soon label (defaults to "Coming Soon") */
+    comingSoonLabel?: string;
+}
+/**
+ * Per-agent chat experience configuration set by admins.
+ * Controls which agents are visible to end users and how they appear.
+ * @public
+ */
+interface ChatAgentConfig {
+    /** Agent identifier: "namespace/name" */
+    agentId: string;
+    /** Whether this agent is published to the end-user catalog (derived from lifecycleStage === 'published') */
+    published: boolean;
+    /** Whether this agent appears in end-user chat (only applies when published) */
+    visible: boolean;
+    /** Whether this agent is featured prominently on the welcome screen */
+    featured: boolean;
+    /** Lifecycle stage: draft → pending → published → archived */
+    lifecycleStage?: AgentLifecycleStage;
+    /** Pending action when in 'pending' stage (e.g. publish or unpublish) */
+    pendingAction?: 'publish' | 'unpublish';
+    /** Promotion version — incremented each time the agent is promoted forward */
+    version?: number;
+    /** ISO timestamp of last promotion */
+    promotedAt?: string;
+    /** User ref of who last promoted this agent */
+    promotedBy?: string;
+    /** User ref of who originally created/registered this agent in the lifecycle */
+    createdBy?: string;
+    /** ISO timestamp of when the agent was first registered in the lifecycle */
+    createdAt?: string;
+    /** Reason the agent was rejected (set on review → draft demotion, cleared on re-promote) */
+    rejectionReason?: string;
+    /** User ref of who rejected the agent */
+    rejectedBy?: string;
+    /** ISO timestamp of when the agent was rejected */
+    rejectedAt?: string;
+    /** SonataFlow process instance id while awaiting admin approval */
+    approvalWorkflowInstanceId?: string;
+    /** Display order (lower first) */
+    order?: number;
+    /** Override display name */
+    displayName?: string;
+    /** Override description */
+    description?: string;
+    /** Custom avatar image URL */
+    avatarUrl?: string;
+    /** Per-agent accent color (hex) */
+    accentColor?: string;
+    /** Greeting message shown as first bot message on new conversation */
+    greeting?: string;
+    /** Suggested prompts shown on the agent card and below the input */
+    conversationStarters?: string[];
+    /** Direct chat endpoint URL for skill agents (e.g. http://agent.ns.svc:8000) */
+    chatEndpoint?: string;
+    /** K8s namespace where the skill agent is deployed */
+    namespace?: string;
+}
+/**
+ * Per-tool lifecycle configuration set by admins.
+ * Controls which tools are published to end users, mirroring the agent lifecycle.
+ * @public
+ */
+interface ChatToolConfig {
+    /** Tool identifier: "namespace/name" */
+    toolId: string;
+    /** Whether this tool is published to the end-user catalog (derived from lifecycleStage === 'published') */
+    published: boolean;
+    /** Whether this tool appears in end-user listings (only applies when published) */
+    visible: boolean;
+    /** Lifecycle stage: draft → pending → published → archived */
+    lifecycleStage?: AgentLifecycleStage;
+    /** Promotion version — incremented each time the tool is promoted forward */
+    version?: number;
+    /** ISO timestamp of last promotion */
+    promotedAt?: string;
+    /** User ref of who last promoted this tool */
+    promotedBy?: string;
+    /** User ref of who created this tool */
+    createdBy?: string;
+    /** ISO timestamp of creation */
+    createdAt?: string;
+}
+/**
+ * A group of related prompts displayed on the welcome screen
+ * @public
+ */
+interface PromptGroup {
+    /** Unique identifier */
+    id: string;
+    /** Display title */
+    title: string;
+    /** Description of this prompt group */
+    description?: string;
+    /** Icon name */
+    icon?: string;
+    /** Theme color (hex) */
+    color?: string;
+    /** Display order (lower numbers appear first, defaults to array order if not specified) */
+    order?: number;
+    /** Cards within this prompt group */
+    cards: PromptCard[];
+}
+/**
+ * Lifecycle stage of an agent in the promotion pipeline.
+ *
+ *   draft → review → staging → production → retired
+ *
+ * - **draft**: Under development. Visible only to creator/admin.
+ * - **review**: Submitted for admin review. Appears in the Review Queue.
+ * - **staging**: Approved, available for internal testing. Not visible to end users.
+ * - **published**: Live in the end-user marketplace/catalog.
+ * - **archived**: Removed from production, preserved for audit/history.
+ * @public
+ */
+type AgentLifecycleStage = 'draft' | 'pending' | 'published' | 'archived';
+/** Human-readable action name for a lifecycle transition. @public */
+type AgentLifecycleAction = 'submit' | 'approve' | 'reject' | 'publish' | 'unpublish' | 'archive' | 'reactivate' | 'withdraw' | 'request-unpublish' | 'approve-unpublish' | 'reject-unpublish';
+/** A single allowed lifecycle transition. @public */
+interface AgentLifecycleTransition {
+    from: AgentLifecycleStage;
+    to: AgentLifecycleStage;
+    action: AgentLifecycleAction;
+    label: string;
+}
+/** Ordered list of lifecycle stages for pipeline display. @public */
+declare const LIFECYCLE_STAGE_ORDER: readonly AgentLifecycleStage[];
+/** All valid lifecycle transitions with human-readable labels. @public */
+declare const LIFECYCLE_TRANSITIONS: readonly AgentLifecycleTransition[];
+/**
+ * Maps old stage names to new ones for backward compatibility.
+ * @public
+ */
+declare const LEGACY_STAGE_MAP: Record<string, AgentLifecycleStage>;
+/** Returns the valid forward transitions from a given stage. @public */
+declare function getAvailableTransitions(stage: AgentLifecycleStage): AgentLifecycleTransition[];
+/** Checks whether a transition from one stage to another is valid. @public */
+declare function isValidTransition(from: AgentLifecycleStage, to: AgentLifecycleStage): boolean;
+/** Normalizes a legacy stage name to the current stage name. @public */
+declare function normalizeLifecycleStage(stage: string | undefined): AgentLifecycleStage;
+/**
+ * Provider-agnostic representation of a chat agent.
+ * Used by the agent catalog/gallery to display agents from any provider
+ * (Kagenti, Llama Stack config-driven, or custom).
+ * @public
+ */
+interface ChatAgent {
+    /** Unique agent identifier (e.g. "namespace/name" for Kagenti, agent key for Llama Stack) */
+    id: string;
+    /** Display name */
+    name: string;
+    /** Human-readable description */
+    description?: string;
+    /** Runtime status (e.g. "Ready", "Pending", "config") */
+    status: string;
+    /** Whether this is the default/entry agent */
+    isDefault?: boolean;
+    /** Provider that owns this agent */
+    providerType: string;
+    /** Conversation starters / example prompts */
+    starters?: string[];
+    /** Avatar image URL */
+    avatarUrl?: string;
+    /** Agent creation timestamp */
+    createdAt?: string;
+    /** Agent framework label (e.g. "a2a", "llamastack") */
+    framework?: string;
+    /** Protocol labels (e.g. "A2A", "MCP") */
+    protocols?: string[];
+    /** Whether this agent is published to the end-user catalog (derived: lifecycleStage === 'published') */
+    published?: boolean;
+    /** Origin of this agent: 'kagenti' | 'orchestration' | 'external' */
+    source?: string;
+    /** Namespace the agent belongs to (for Kagenti agents) */
+    namespace?: string;
+    /** Current lifecycle stage in the promotion pipeline */
+    lifecycleStage?: AgentLifecycleStage;
+    /** Pending action when in 'pending' stage (e.g. publish or unpublish) */
+    pendingAction?: 'publish' | 'unpublish';
+    /** Promotion version (increments each time the agent is promoted) */
+    version?: number;
+    /** When this agent was last promoted */
+    promotedAt?: string;
+    /** Who promoted this agent */
+    promotedBy?: string;
+    /** User ref of who originally created/registered this agent in the lifecycle */
+    createdBy?: string;
+    /** Reason the agent was rejected (set on review → draft demotion, cleared on re-promote) */
+    rejectionReason?: string;
+    /** User ref of who rejected the agent */
+    rejectedBy?: string;
+    /** ISO timestamp of when the agent was rejected */
+    rejectedAt?: string;
+    /** Role of this agent in the orchestration topology */
+    agentRole?: AgentRole;
+    /**
+     * True when a chatAgents lifecycle entry exists for this agent.
+     * False for runtime-only agents (Kagenti/orchestration) not yet in governance.
+     */
+    governanceRegistered?: boolean;
+    /** Direct chat endpoint URL for skill agents (e.g. http://agent.ns.svc:8000) */
+    chatEndpoint?: string;
+}
+/**
+ * Possible roles an agent can have in the orchestration topology.
+ * Always auto-derived from connections, never manually set.
+ * @public
+ */
+type AgentRole = 'router' | 'specialist' | 'standalone';
+/**
+ * Minimal agent shape required for topology-based role derivation.
+ * Both frontend form data and backend config objects satisfy this.
+ * @public
+ */
+interface AgentTopologyNode {
+    handoffs?: string[];
+    asTools?: string[];
+}
+/**
+ * Derives an agent's role from the multi-agent topology.
+ * This is the single source of truth for role derivation across
+ * both frontend and backend.
+ *
+ * Rules:
+ * - Has outgoing handoffs or asTools -> 'router'
+ * - Is a target of another agent's handoffs or asTools -> 'specialist'
+ * - Neither -> 'standalone'
+ *
+ * @public
+ */
+declare function deriveRoleFromTopology(agentKey: string, allAgents: Record<string, AgentTopologyNode | null | undefined>): AgentRole;
+/**
+ * Conversation summary for UI display.
+ * Derived from stored responses.
+ * @public
+ */
+interface ConversationSummary {
+    /** Response ID — use to continue this conversation */
+    responseId: string;
+    /** Preview of the conversation (first user message or assistant response) */
+    preview: string;
+    /** When the conversation was created */
+    createdAt: Date;
+    /** Model used */
+    model: string;
+    /** Status */
+    status: 'completed' | 'failed' | 'in_progress';
+    /** Llama Stack conversation ID (present for new-style conversations) */
+    conversationId?: string;
+    /** Previous response ID for chain deduplication */
+    previousResponseId?: string;
+}
+/**
+ * Base response from the chat endpoint, shared between frontend and backend.
+ * Frontend extends this with additional fields (filtered, evaluation, etc.).
+ * @public
+ */
+interface ChatResponse {
+    role: 'assistant';
+    content: string;
+    ragContext?: string[];
+    /** @deprecated Use ragSources instead */
+    filesSearched?: string[];
+    ragSources?: RAGSource[];
+    toolCalls?: ToolCallInfo[];
+    responseId?: string;
+    usage?: ResponseUsage;
+    /** Name of the agent that produced the final response (multi-agent only) */
+    agentName?: string;
+    /** Ordered list of agent keys visited during handoffs, e.g. ["triage", "billing"] */
+    handoffPath?: string[];
+    /** Present when a backend-executed tool requires HITL approval before execution */
+    pendingApproval?: PendingApprovalInfo;
+    /** All pending approvals when multiple backend tools need HITL approval */
+    pendingApprovals?: PendingApprovalInfo[];
+    /** Structured output validation error (G5). Present when the agent's outputSchema validation failed. */
+    outputValidationError?: string;
+    /** Reasoning/thinking summaries from the model's chain-of-thought. */
+    reasoning?: ReasoningSummary[];
+}
+/**
+ * Summary of model reasoning from chain-of-thought output.
+ * @public
+ */
+interface ReasoningSummary {
+    id: string;
+    text: string;
+}
+/**
+ * Information about a single pending HITL approval.
+ * @public
+ */
+interface PendingApprovalInfo {
+    approvalRequestId: string;
+    toolName: string;
+    serverLabel?: string;
+    arguments?: string;
+}
+/**
+ * Result of a document sync operation.
+ * @public
+ */
+interface SyncResult {
+    added: number;
+    removed: number;
+    updated: number;
+    failed: number;
+    unchanged: number;
+    errors: string[];
+}
+/**
+ * Detailed tool information for the capabilities-aware prompt generator.
+ * Used by the frontend capabilities selector to send tool descriptions
+ * to the backend so the meta-prompt can reference what each tool does.
+ * @public
+ */
+interface ToolCapabilityInfo {
+    name: string;
+    description?: string;
+    serverLabel?: string;
+}
+/**
+ * User-selected capabilities to emphasize when generating agent instructions.
+ * Sent to the backend so the meta-prompt includes specific tool descriptions
+ * and contextual detail about the agent's environment.
+ * @public
+ */
+interface PromptCapabilities {
+    tools?: ToolCapabilityInfo[];
+    enableWebSearch?: boolean;
+    enableCodeInterpreter?: boolean;
+    ragEnabled?: boolean;
+    vectorStoreNames?: string[];
+    safetyEnabled?: boolean;
+    safetyShields?: string[];
+}
+
+/** Response has been created, streaming is starting. @public */
+interface StreamStartedEvent {
+    type: 'stream.started';
+    responseId: string;
+    model?: string;
+    /** Server-side creation timestamp (Unix epoch seconds) */
+    createdAt?: number;
+}
+/** A chunk of generated text. @public */
+interface StreamTextDeltaEvent {
+    type: 'stream.text.delta';
+    delta: string;
+}
+/** Text generation is complete for this response. @public */
+interface StreamTextDoneEvent {
+    type: 'stream.text.done';
+    text: string;
+}
+/** A chunk of reasoning/thinking text (models with chain-of-thought). @public */
+interface StreamReasoningDeltaEvent {
+    type: 'stream.reasoning.delta';
+    delta: string;
+}
+/** Reasoning text is complete. @public */
+interface StreamReasoningDoneEvent {
+    type: 'stream.reasoning.done';
+    text: string;
+}
+/** Provider is discovering available tools (e.g., listing MCP server tools). @public */
+interface StreamToolDiscoveryEvent {
+    type: 'stream.tool.discovery';
+    serverLabel?: string;
+    status: 'in_progress' | 'completed';
+    toolCount?: number;
+}
+/** A tool call has started. @public */
+interface StreamToolStartedEvent {
+    type: 'stream.tool.started';
+    callId: string;
+    name: string;
+    serverLabel?: string;
+}
+/** Tool call arguments are streaming in. @public */
+interface StreamToolDeltaEvent {
+    type: 'stream.tool.delta';
+    callId: string;
+    delta: string;
+}
+/** Tool call completed with output. @public */
+interface StreamToolCompletedEvent {
+    type: 'stream.tool.completed';
+    callId: string;
+    name: string;
+    serverLabel?: string;
+    output?: string;
+    error?: string;
+}
+/** Tool call failed. @public */
+interface StreamToolFailedEvent {
+    type: 'stream.tool.failed';
+    callId: string;
+    name: string;
+    serverLabel?: string;
+    error: string;
+}
+/** Tool call requires human approval (HITL). @public */
+interface StreamToolApprovalEvent {
+    type: 'stream.tool.approval';
+    callId: string;
+    name: string;
+    serverLabel?: string;
+    arguments?: string;
+    /** Response ID for this approval request, for reliable approval submission. */
+    responseId?: string;
+}
+/** Backend is executing tool calls on behalf of the LLM. @public */
+interface StreamBackendToolExecutingEvent {
+    type: 'stream.backend_tool.executing';
+    toolCount: number;
+    tools: string[];
+}
+/** RAG search results arrived. @public */
+interface StreamRagResultsEvent {
+    type: 'stream.rag.results';
+    sources: Array<{
+        filename: string;
+        fileId?: string;
+        text?: string;
+        score?: number;
+        title?: string;
+        sourceUrl?: string;
+        contentType?: string;
+        attributes?: Record<string, unknown>;
+    }>;
+    filesSearched?: string[];
+}
+/** The response is fully complete. @public */
+interface StreamCompletedEvent {
+    type: 'stream.completed';
+    responseId?: string;
+    usage?: ResponseUsage;
+    /** Display name of the agent that produced the final response (multi-agent only) */
+    agentName?: string;
+    /** Output validation error when structured output schema validation failed */
+    outputValidationError?: string;
+}
+/** An agent handoff occurred during multi-agent streaming. @public */
+interface StreamAgentHandoffEvent {
+    type: 'stream.agent.handoff';
+    fromAgent?: string;
+    toAgent: string;
+    /** Optional reason provided by the model for the handoff */
+    reason?: string;
+}
+/** A form field descriptor for input-required forms. @public */
+interface StreamFormField {
+    name: string;
+    type?: string;
+    label?: string;
+    description?: string;
+    required?: boolean;
+    defaultValue?: unknown;
+    options?: Array<{
+        label: string;
+        value: string;
+    }>;
+    [key: string]: unknown;
+}
+/** Shape of a form render request from an A2A agent. @public */
+interface StreamFormDescriptor {
+    title?: string;
+    description?: string;
+    fields?: StreamFormField[];
+    [key: string]: unknown;
+}
+/** Agent requests structured form input from the user (A2A INPUT_REQUIRED). @public */
+interface StreamFormRequestEvent {
+    type: 'stream.form.request';
+    taskId?: string;
+    contextId?: string;
+    form: StreamFormDescriptor;
+}
+/** Shape of a secret demand from an A2A agent. @public */
+interface StreamSecretDemand {
+    name: string;
+    description?: string;
+    [key: string]: unknown;
+}
+/** Agent requires authentication (A2A AUTH_REQUIRED -- OAuth or secrets). @public */
+interface StreamAuthRequiredEvent {
+    type: 'stream.auth.required';
+    taskId?: string;
+    authType: 'oauth' | 'secret';
+    url?: string;
+    demands?: {
+        secrets?: StreamSecretDemand[];
+        [key: string]: unknown;
+    };
+}
+/** Agent is streaming an artifact (code, file, document). @public */
+interface StreamArtifactEvent {
+    type: 'stream.artifact';
+    artifactId: string;
+    name?: string;
+    description?: string;
+    content: string;
+    append?: boolean;
+    lastChunk?: boolean;
+}
+/** A single citation reference. @public */
+interface StreamCitationReference {
+    title?: string;
+    url?: string;
+    snippet?: string;
+    [key: string]: unknown;
+}
+/** Agent provides source citations for its response. @public */
+interface StreamCitationEvent {
+    type: 'stream.citation';
+    citations: StreamCitationReference[];
+}
+/** An error occurred during streaming. @public */
+interface StreamErrorEvent {
+    type: 'stream.error';
+    error: string;
+    code?: string;
+    title?: string;
+    context?: Record<string, unknown>;
+}
+/**
+ * Union of all normalized streaming events.
+ *
+ * This is the single source of truth for the streaming contract
+ * between the backend and frontend. Both the backend's EventNormalizer
+ * and the frontend's StreamingMessage reducer use this type.
+ * @public
+ */
+type NormalizedStreamEvent = StreamStartedEvent | StreamTextDeltaEvent | StreamTextDoneEvent | StreamReasoningDeltaEvent | StreamReasoningDoneEvent | StreamToolDiscoveryEvent | StreamToolStartedEvent | StreamToolDeltaEvent | StreamToolCompletedEvent | StreamToolFailedEvent | StreamToolApprovalEvent | StreamBackendToolExecutingEvent | StreamRagResultsEvent | StreamAgentHandoffEvent | StreamFormRequestEvent | StreamAuthRequiredEvent | StreamArtifactEvent | StreamCitationEvent | StreamCompletedEvent | StreamErrorEvent;
+
+/**
+ * Branding configuration loaded from app-config.yaml.
+ * Shared across frontend and backend.
+ * @public
+ */
+interface BrandingConfig {
+    appName: string;
+    tagline: string;
+    inputPlaceholder: string;
+    primaryColor: string;
+    secondaryColor: string;
+    successColor: string;
+    warningColor: string;
+    errorColor: string;
+    infoColor: string;
+    logoUrl?: string;
+    faviconUrl?: string;
+    botAvatarUrl?: string;
+    themePreset?: string;
+}
+/**
+ * Single source of truth for branding defaults.
+ * Used by both frontend hooks and backend API routes.
+ * @public
+ */
+declare const DEFAULT_BRANDING: BrandingConfig;
+
+/**
+ * Allowed keys for admin-managed configuration stored in the database.
+ *
+ * Keys fall into three categories:
+ * - `activeProvider`: which provider is currently active
+ * - Global keys: shared across all providers (branding, promptGroups, etc.)
+ * - Provider-scoped keys: namespaced per provider in storage (model, baseUrl, etc.)
+ *
+ * @public
+ */
+type AdminConfigKey = 'activeProvider' | 'promptGroups' | 'systemPrompt' | 'branding' | 'safetyPatterns' | 'vectorStoreConfig' | 'activeVectorStoreIds' | 'model' | 'baseUrl' | 'kagentiBaseUrl' | 'toolChoice' | 'enableWebSearch' | 'enableCodeInterpreter' | 'mcpServers' | 'disabledMcpServerIds' | 'safetyEnabled' | 'inputShields' | 'outputShields' | 'safetyOnError' | 'evaluationEnabled' | 'scoringFunctions' | 'minScoreThreshold' | 'evaluationOnError' | 'agents' | 'defaultAgent' | 'maxAgentTurns' | 'maxToolCalls' | 'maxOutputTokens' | 'temperature' | 'safetyIdentifier' | 'chatAgents' | 'chatTools' | 'devSpacesApiUrl' | 'devSpacesToken' | 'devSpacesNamespace' | 'workflows' | 'workflowVersions' | 'workflowTestSuites' | 'workflowEvaluations';
+/**
+ * A single admin config entry stored in the database.
+ * @public
+ */
+interface AdminConfigEntry {
+    configKey: AdminConfigKey;
+    configValue: unknown;
+    updatedAt: string;
+    updatedBy: string;
+}
+/**
+ * A single chunk returned from a RAG test query.
+ * @public
+ */
+interface RagTestChunk {
+    text: string;
+    score?: number;
+    fileId?: string;
+    fileName?: string;
+    vectorStoreId?: string;
+}
+/**
+ * Result of a RAG test query against the vector store.
+ * @public
+ */
+interface RagTestResult {
+    query: string;
+    chunks: RagTestChunk[];
+    vectorStoreId: string;
+    totalResults: number;
+}
+/**
+ * Result of an end-to-end RAG generation test: retrieval + LLM answer.
+ * @public
+ */
+interface RagGenerateResult {
+    query: string;
+    answer: string;
+    chunks: RagTestChunk[];
+    model: string;
+    totalResults: number;
+}
+/**
+ * Result of uploading a document to the vector store.
+ * @public
+ */
+interface UploadResult {
+    fileId: string;
+    fileName: string;
+    status: string;
+}
+/**
+ * Vector store configuration editable from the admin panel.
+ * Fields mirror the vector store section of the active provider's app-config.
+ * @public
+ */
+interface VectorStoreConfig {
+    vectorStoreName: string;
+    embeddingModel: string;
+    embeddingDimension: number;
+    searchMode?: 'semantic' | 'keyword' | 'hybrid';
+    bm25Weight?: number;
+    semanticWeight?: number;
+    chunkingStrategy: 'auto' | 'static';
+    maxChunkSizeTokens: number;
+    chunkOverlapTokens: number;
+    fileSearchMaxResults?: number;
+    fileSearchScoreThreshold?: number;
+}
+/**
+ * Result of creating a vector store.
+ * @public
+ */
+interface VectorStoreCreateResult {
+    vectorStoreId: string;
+    vectorStoreName: string;
+    created: boolean;
+    embeddingModel: string;
+    embeddingDimension?: number;
+}
+/**
+ * Current status of the vector store.
+ * @public
+ */
+interface VectorStoreStatusResult {
+    exists: boolean;
+    vectorStoreId?: string;
+    vectorStoreName?: string;
+    documentCount?: number;
+    embeddingModel?: string;
+    ready: boolean;
+}
+
+/** @public */
+interface KagentiSecretKeyRef {
+    name: string;
+    key: string;
+}
+/** @public */
+interface KagentiConfigMapKeyRef {
+    name: string;
+    key: string;
+}
+/** @public */
+interface KagentiEnvVarSource {
+    secretKeyRef?: KagentiSecretKeyRef;
+    configMapKeyRef?: KagentiConfigMapKeyRef;
+}
+/** @public */
+interface KagentiEnvVar {
+    name: string;
+    value?: string;
+    valueFrom?: KagentiEnvVarSource;
+}
+/** @public */
+interface KagentiServicePort {
+    name?: string;
+    port: number;
+    targetPort?: number;
+    protocol?: string;
+}
+/** @public */
+interface KagentiResourceLabels {
+    protocol?: string | string[];
+    framework?: string;
+    type?: string;
+}
+/** @public */
+interface KagentiAgentSummary {
+    name: string;
+    namespace: string;
+    description: string;
+    status: string;
+    labels: KagentiResourceLabels;
+    workloadType?: string;
+    createdAt?: string;
+}
+/** @public */
+interface KagentiAgentDetail {
+    metadata: Record<string, unknown>;
+    spec: Record<string, unknown>;
+    status: Record<string, unknown>;
+    workloadType?: string;
+    readyStatus?: string;
+    service?: Record<string, unknown>;
+}
+/** @public */
+interface KagentiAgentCardSkill {
+    id?: string;
+    name?: string;
+    description?: string;
+    examples?: string[];
+}
+/** @public */
+interface KagentiAgentCard {
+    name: string;
+    description?: string;
+    version: string;
+    url: string;
+    streaming: boolean;
+    defaultInputModes?: string[];
+    skills: KagentiAgentCardSkill[];
+}
+/** @public */
+interface KagentiShipwrightConfig {
+    buildStrategy?: string;
+    dockerfile?: string;
+    buildArgs?: string[];
+    buildTimeout?: string;
+}
+/** @public */
+interface KagentiCreateAgentRequest {
+    name: string;
+    namespace: string;
+    protocol?: string;
+    framework?: string;
+    envVars?: KagentiEnvVar[];
+    workloadType?: 'deployment' | 'statefulset' | 'job';
+    deploymentMethod?: 'source' | 'image';
+    gitUrl?: string;
+    gitPath?: string;
+    gitBranch?: string;
+    imageTag?: string;
+    registryUrl?: string;
+    registrySecret?: string;
+    startCommand?: string;
+    containerImage?: string;
+    imagePullSecret?: string;
+    servicePorts?: KagentiServicePort[];
+    createHttpRoute?: boolean;
+    authBridgeEnabled?: boolean;
+    spireEnabled?: boolean;
+    shipwrightConfig?: KagentiShipwrightConfig;
+}
+/** @public */
+interface KagentiCreateAgentResponse {
+    success: boolean;
+    name: string;
+    namespace: string;
+    message: string;
+}
+/** @public */
+interface KagentiFinalizeAgentBuildRequest {
+    protocol?: string;
+    framework?: string;
+    envVars?: KagentiEnvVar[];
+    servicePorts?: KagentiServicePort[];
+    createHttpRoute?: boolean;
+    authBridgeEnabled?: boolean;
+    imagePullSecret?: string;
+}
+/** @public */
+interface KagentiToolSummary {
+    name: string;
+    namespace: string;
+    description: string;
+    status: string;
+    labels: KagentiResourceLabels;
+    createdAt?: string;
+    workloadType?: string;
+}
+/** @public */
+interface KagentiToolDetail {
+    metadata: Record<string, unknown>;
+    spec: Record<string, unknown>;
+    status: Record<string, unknown>;
+    workloadType?: string;
+    service?: Record<string, unknown>;
+}
+/** @public */
+interface KagentiCreateToolRequest {
+    name: string;
+    namespace: string;
+    protocol?: string;
+    framework?: string;
+    description?: string;
+    envVars?: KagentiEnvVar[];
+    servicePorts?: KagentiServicePort[];
+    workloadType?: 'deployment' | 'statefulset';
+    persistentStorage?: KagentiPersistentStorageConfig;
+    deploymentMethod?: 'image' | 'source';
+    containerImage?: string;
+    imagePullSecret?: string;
+    gitUrl?: string;
+    gitRevision?: string;
+    contextDir?: string;
+    registryUrl?: string;
+    registrySecret?: string;
+    imageTag?: string;
+    shipwrightConfig?: KagentiShipwrightConfig;
+    createHttpRoute?: boolean;
+    authBridgeEnabled?: boolean;
+    spireEnabled?: boolean;
+}
+/** @public */
+interface KagentiCreateToolResponse {
+    success: boolean;
+    name: string;
+    namespace: string;
+    message: string;
+}
+/** @public */
+interface KagentiPersistentStorageConfig {
+    enabled: boolean;
+    size: string;
+}
+/** @public */
+interface KagentiFinalizeToolBuildRequest {
+    protocol?: string;
+    framework?: string;
+    workloadType?: string;
+    persistentStorage?: KagentiPersistentStorageConfig;
+    envVars?: KagentiEnvVar[];
+    servicePorts?: KagentiServicePort[];
+    createHttpRoute?: boolean;
+    authBridgeEnabled?: boolean;
+    spireEnabled?: boolean;
+    imagePullSecret?: string;
+}
+/** @public */
+interface KagentiMcpInvokeResponse {
+    result: unknown;
+}
+/** @public */
+interface KagentiMcpToolSchema {
+    name: string;
+    description?: string;
+    input_schema?: Record<string, unknown>;
+}
+/** @public */
+interface KagentiFeatureFlags {
+    sandbox: boolean;
+    integrations: boolean;
+    triggers: boolean;
+}
+/** @public */
+interface KagentiDashboardConfig {
+    traces?: string;
+    network?: string;
+    mcpInspector?: string;
+    mcpProxy?: string;
+    keycloakConsole?: string;
+    domainName?: string;
+}
+/**
+ * Kagenti server's user-facing SSO / Keycloak configuration.
+ *
+ * **This is NOT the Backstage service credentials** configured in
+ * `augment.kagenti.auth` (which uses OAuth2 client-credentials grant
+ * for backend-to-Kagenti API authentication). This type represents
+ * the Kagenti server's own authentication settings for end users,
+ * as returned by the `GET /api/v1/auth/config` endpoint.
+ *
+ * @public
+ */
+interface KagentiAuthConfig {
+    enabled: boolean;
+    keycloak_url?: string;
+    realm?: string;
+    client_id?: string;
+    redirect_uri?: string;
+}
+/** @public */
+interface KagentiBuildListItem {
+    name: string;
+    namespace: string;
+    resourceType?: string;
+    registered: boolean;
+    strategy?: string;
+    gitUrl?: string;
+    gitRevision?: string;
+    contextDir?: string;
+    outputImage?: string;
+    creationTimestamp?: string;
+}
+/** @public */
+interface KagentiResourceConfigFromBuild {
+    protocol?: string;
+    framework?: string;
+    createHttpRoute?: boolean;
+    registrySecret?: string;
+    envVars?: KagentiEnvVar[];
+    servicePorts?: KagentiServicePort[];
+}
+/** @public */
+interface KagentiBuildInfo {
+    name: string;
+    namespace: string;
+    buildRegistered: boolean;
+    buildReason?: string;
+    buildMessage?: string;
+    outputImage: string;
+    strategy: string;
+    gitUrl: string;
+    gitRevision: string;
+    contextDir: string;
+    hasBuildRun: boolean;
+    buildRunName?: string;
+    buildRunPhase?: string;
+    buildRunStartTime?: string;
+    buildRunCompletionTime?: string;
+    buildRunOutputImage?: string;
+    buildRunOutputDigest?: string;
+    buildRunFailureMessage?: string;
+    agentConfig?: KagentiResourceConfigFromBuild;
+    toolConfig?: KagentiResourceConfigFromBuild;
+}
+/** @public */
+interface KagentiBuildStrategy {
+    name: string;
+    description?: string;
+}
+/** @public */
+interface KagentiRouteStatus {
+    hasRoute: boolean;
+    /** Present when the API exposes a public URL for the route. */
+    url?: string;
+    /** Additional fields returned by the Kagenti API (e.g. ready, status). */
+    [key: string]: unknown;
+}
+/** @public */
+interface KagentiTriggerBuildRunResponse {
+    success: boolean;
+    buildRunName: string;
+    namespace: string;
+    buildName: string;
+    message?: string;
+}
+/** @public */
+interface KagentiMigratableAgent {
+    name: string;
+    namespace: string;
+    status: string;
+    has_deployment: boolean;
+    labels: KagentiResourceLabels;
+    description?: string;
+}
+/** @public */
+interface KagentiMigrateAgentResponse {
+    success: boolean;
+    migrated: boolean;
+    name: string;
+    namespace: string;
+    message: string;
+    deployment_created: boolean;
+    service_created: boolean;
+    agent_crd_deleted: boolean;
+}
+/** @public */
+interface KagentiMigrateAllResponse {
+    namespace: string;
+    dry_run: boolean;
+    delete_old: boolean;
+    total: number;
+    migrated: unknown[];
+    skipped: unknown[];
+    failed: unknown[];
+}
+/** @public */
+interface KagentiSandboxSession {
+    contextId: string;
+    agentName?: string;
+    status: string;
+    title?: string;
+    visibility?: 'private' | 'namespace';
+    createdAt?: string;
+    updatedAt?: string;
+}
+/** @public */
+interface KagentiSandboxAgentInfo {
+    name: string;
+    namespace: string;
+    sessionCount?: number;
+    [key: string]: unknown;
+}
+/** @public */
+interface KagentiSandboxCreateRequest {
+    [key: string]: unknown;
+}
+/** @public */
+interface KagentiSidecar {
+    sidecarType: string;
+    enabled: boolean;
+    config?: Record<string, unknown>;
+}
+/** @public */
+interface KagentiSessionTokenUsage {
+    contextId: string;
+    totalTokens?: number;
+    totalCost?: number;
+    models?: Array<{
+        model: string;
+        tokens: number;
+        cost?: number;
+    }>;
+}
+/** @public */
+interface KagentiIntegration {
+    name: string;
+    namespace: string;
+    conditions?: Array<{
+        type: string;
+        status: string;
+        message?: string;
+    }>;
+    [key: string]: unknown;
+}
+/** @public */
+interface KagentiCreateIntegrationRequest {
+    name: string;
+    namespace: string;
+    [key: string]: unknown;
+}
+/** @public */
+interface KagentiLlmTeam {
+    teamId: string;
+    namespace: string;
+    [key: string]: unknown;
+}
+/** @public */
+interface KagentiLlmKey {
+    alias?: string;
+    agent?: string;
+    namespace?: string;
+    [key: string]: unknown;
+}
+/** @public */
+interface KagentiCreateTeamRequest {
+    namespace: string;
+    [key: string]: unknown;
+}
+/** @public */
+interface KagentiCreateKeyRequest {
+    namespace: string;
+    agentName: string;
+    [key: string]: unknown;
+}
+/** @public */
+interface KagentiTriggerRequest {
+    type: 'cron' | 'webhook' | 'alert';
+    namespace: string;
+    skill?: string;
+    schedule?: string;
+    ttl_hours?: number;
+    [key: string]: unknown;
+}
+/** Request body for creating a Dev Spaces workspace. @public */
+interface DevSpacesCreateWorkspaceRequest {
+    namespace: string;
+    git_repo: string;
+    memory_limit?: string;
+    cpu_limit?: string;
+}
+/** Response from the Dev Spaces workspace creation API. @public */
+interface DevSpacesCreateWorkspaceResponse {
+    name: string;
+    namespace: string;
+    phase: string;
+    message?: string;
+    url?: string;
+    created_at?: string;
+}
+/** Health check response for the Dev Spaces API. @public */
+interface DevSpacesHealthResponse {
+    ok: boolean;
+    configured: boolean;
+    message: string;
+    apiUrl?: string;
+    responseTimeMs?: number;
+}
+/** A single workspace entry returned by list/get operations. @public */
+interface DevSpacesWorkspace {
+    name: string;
+    namespace: string;
+    phase: string;
+    url?: string;
+    created_at?: string;
+    started_at?: string;
+    stopped_at?: string;
+    git_repo?: string;
+    memory_limit?: string;
+    cpu_limit?: string;
+}
+/** Response from the list-workspaces endpoint. @public */
+interface DevSpacesListWorkspacesResponse {
+    workspaces: DevSpacesWorkspace[];
+    namespace: string;
+}
+/** Request to stop a workspace. @public */
+interface DevSpacesStopWorkspaceRequest {
+    namespace: string;
+    name: string;
+}
+/** Request to delete a workspace. @public */
+interface DevSpacesDeleteWorkspaceRequest {
+    namespace: string;
+    name: string;
+}
+
+/**
+ * Status of a workflow in its lifecycle.
+ * @public
+ */
+type WorkflowStatus = 'draft' | 'published' | 'archived';
+/**
+ * Discriminated node types available in the workflow canvas.
+ * @public
+ */
+type WorkflowNodeType = 'start' | 'agent' | 'tool' | 'guardrail' | 'logic' | 'user_interaction' | 'classify' | 'end' | 'note' | 'transform' | 'set_state' | 'file_search' | 'mcp';
+/**
+ * Position on the canvas for visual layout.
+ * @public
+ */
+interface NodePosition {
+    x: number;
+    y: number;
+}
+/**
+ * Data for the Start node -- defines the workflow's input contract.
+ * @public
+ */
+interface StartNodeData {
+    inputDescription?: string;
+    inputSchema?: Record<string, unknown>;
+}
+/**
+ * Data for an Agent node -- carries the full agent configuration.
+ * @public
+ */
+interface AgentNodeData {
+    agentKey: string;
+    name: string;
+    instructions: string;
+    handoffDescription?: string;
+    model?: string;
+    mcpServers?: string[];
+    enableRAG?: boolean;
+    vectorStoreIds?: string[];
+    enableWebSearch?: boolean;
+    enableCodeInterpreter?: boolean;
+    functions?: AgentFunctionDef[];
+    toolChoice?: string;
+    temperature?: number;
+    maxOutputTokens?: number;
+    maxToolCalls?: number;
+    reasoning?: {
+        effort?: string;
+    };
+    guardrails?: string[];
+    outputSchema?: Record<string, unknown>;
+    toolUseBehavior?: string;
+    resetToolChoice?: boolean;
+    handoffInputFilter?: string;
+    handoffInputSchema?: Record<string, unknown>;
+    nestHandoffHistory?: boolean;
+    truncation?: string;
+    promptRef?: {
+        id: string;
+        version?: number;
+        variables?: Record<string, string>;
+    };
+    enabled?: boolean;
+}
+/**
+ * A custom function definition attached to an agent.
+ * @public
+ */
+interface AgentFunctionDef {
+    name: string;
+    description: string;
+    parameters: Record<string, unknown>;
+}
+/**
+ * Tool type discriminator for ToolNodeData.
+ * @public
+ */
+type ToolNodeKind = 'mcp_server' | 'file_search' | 'web_search' | 'code_interpreter' | 'custom_function';
+/**
+ * Data for a Tool node -- references an external capability.
+ * @public
+ */
+interface ToolNodeData {
+    kind: ToolNodeKind;
+    label: string;
+    mcpServerId?: string;
+    mcpToolFilter?: string[];
+    vectorStoreIds?: string[];
+    functionDef?: AgentFunctionDef;
+    requireApproval?: boolean;
+}
+/**
+ * Data for a Guardrail node -- safety checks on input/output.
+ * @public
+ */
+interface GuardrailNodeData {
+    guardType: 'input' | 'output';
+    shieldIds?: string[];
+    customRules?: GuardrailRule[];
+    onFailure: 'block' | 'warn' | 'fallback';
+    fallbackMessage?: string;
+}
+/**
+ * A custom guardrail rule (regex, keyword, or LLM-graded).
+ * @public
+ */
+interface GuardrailRule {
+    id: string;
+    name: string;
+    type: 'regex' | 'keyword_block' | 'llm_grader';
+    pattern?: string;
+    keywords?: string[];
+    graderPrompt?: string;
+}
+/**
+ * Logic node sub-type.
+ * @public
+ */
+type LogicNodeKind = 'if_else' | 'while_loop' | 'switch';
+/**
+ * Data for a Logic node -- conditional routing and loops.
+ * @public
+ */
+interface LogicNodeData {
+    kind: LogicNodeKind;
+    condition: string;
+    cases?: Array<{
+        label: string;
+        condition: string;
+    }>;
+    maxIterations?: number;
+}
+/**
+ * Data for a User Interaction node -- HITL approval gates and forms.
+ * @public
+ */
+interface UserInteractionNodeData {
+    interactionType: 'approval_gate' | 'form_input' | 'confirmation';
+    prompt: string;
+    formFields?: UserInteractionField[];
+    timeoutSeconds?: number;
+    defaultAction?: 'approve' | 'reject' | 'skip';
+}
+/**
+ * A field in a user interaction form.
+ * @public
+ */
+interface UserInteractionField {
+    id: string;
+    label: string;
+    type: 'text' | 'select' | 'boolean' | 'number';
+    required?: boolean;
+    options?: string[];
+    defaultValue?: string;
+}
+/**
+ * Data for a Classify node -- routes to different branches based on LLM classification.
+ * @public
+ */
+interface ClassifyNodeData {
+    classifications: Array<{
+        label: string;
+        description: string;
+    }>;
+    instructions?: string;
+    model?: string;
+}
+/**
+ * Data for an End node -- terminates the workflow execution.
+ * @public
+ */
+interface EndNodeData {
+    outputExpression?: string;
+}
+/**
+ * Data for a Note node -- annotation-only, no execution semantics.
+ * @public
+ */
+interface NoteNodeData {
+    text: string;
+}
+/**
+ * Data for a Transform node -- transforms data between steps using expressions.
+ * @public
+ */
+interface TransformNodeData {
+    expression: string;
+    outputVariable?: string;
+}
+/**
+ * Data for a Set State node -- assigns values to workflow state variables.
+ * @public
+ */
+interface SetStateNodeData {
+    assignments: Record<string, string>;
+}
+/**
+ * Data for a File Search node -- configures vector store search.
+ * @public
+ */
+interface FileSearchNodeData {
+    vectorStoreIds?: string[];
+    maxResults?: number;
+    scoreThreshold?: number;
+}
+/**
+ * Data for an MCP node -- configures a Model Context Protocol server.
+ * @public
+ */
+interface McpNodeData {
+    serverUrl: string;
+    serverLabel: string;
+    requireApproval?: 'always' | 'never' | 'auto';
+    allowedTools?: string[];
+    headers?: Record<string, string>;
+}
+/**
+ * Union of all node data payloads, discriminated by the parent node's `type`.
+ * @public
+ */
+type WorkflowNodeData = StartNodeData | AgentNodeData | ToolNodeData | GuardrailNodeData | LogicNodeData | UserInteractionNodeData | ClassifyNodeData | EndNodeData | NoteNodeData | TransformNodeData | SetStateNodeData | FileSearchNodeData | McpNodeData;
+/**
+ * A single node in the workflow graph.
+ * @public
+ */
+interface WorkflowNode {
+    id: string;
+    type: WorkflowNodeType;
+    position: NodePosition;
+    data: WorkflowNodeData;
+    label?: string;
+}
+/**
+ * Edge type determines the connection semantics.
+ * @public
+ */
+type WorkflowEdgeType = 'handoff' | 'tool_binding' | 'guardrail_binding' | 'sequence' | 'conditional';
+/**
+ * A connection between two nodes in the workflow graph.
+ * @public
+ */
+interface WorkflowEdge {
+    id: string;
+    source: string;
+    target: string;
+    sourceHandle?: string;
+    targetHandle?: string;
+    type?: WorkflowEdgeType;
+    label?: string;
+    condition?: string;
+}
+/**
+ * Global settings that apply to the entire workflow.
+ * @public
+ */
+interface WorkflowSettings {
+    maxTurns?: number;
+    defaultModel?: string;
+    globalGuardrails?: string[];
+    conversationPersistence?: boolean;
+    tracingEnabled?: boolean;
+    timeoutSeconds?: number;
+}
+/**
+ * A published, immutable version snapshot of a workflow.
+ * @public
+ */
+interface WorkflowVersion {
+    version: number;
+    publishedAt: string;
+    publishedBy: string;
+    changelog?: string;
+    definition: WorkflowDefinition;
+}
+/**
+ * The complete workflow definition -- the top-level serializable artifact.
+ *
+ * This is persisted in the admin config store and exchanged between the
+ * frontend canvas editor and the backend hydration engine.
+ * @public
+ */
+interface WorkflowDefinition {
+    id: string;
+    name: string;
+    description: string;
+    version: number;
+    createdAt: string;
+    updatedAt: string;
+    createdBy?: string;
+    updatedBy?: string;
+    status: WorkflowStatus;
+    nodes: WorkflowNode[];
+    edges: WorkflowEdge[];
+    settings: WorkflowSettings;
+    tags?: string[];
+}
+/**
+ * Status of a workflow execution run.
+ * @public
+ */
+type WorkflowRunStatus = 'pending' | 'running' | 'completed' | 'failed' | 'interrupted' | 'cancelled';
+/**
+ * A record of a single node's execution within a run.
+ * @public
+ */
+interface NodeExecutionRecord {
+    nodeId: string;
+    nodeType: WorkflowNodeType;
+    nodeName: string;
+    startedAt: string;
+    completedAt?: string;
+    status: 'running' | 'completed' | 'failed' | 'skipped';
+    input?: unknown;
+    output?: unknown;
+    error?: string;
+    tokenUsage?: {
+        inputTokens: number;
+        outputTokens: number;
+    };
+    durationMs?: number;
+}
+/**
+ * A complete execution trace for a workflow run.
+ * @public
+ */
+interface WorkflowRunTrace {
+    runId: string;
+    workflowId: string;
+    workflowVersion: number;
+    status: WorkflowRunStatus;
+    startedAt: string;
+    completedAt?: string;
+    nodeExecutions: NodeExecutionRecord[];
+    totalTokenUsage?: {
+        inputTokens: number;
+        outputTokens: number;
+    };
+    totalDurationMs?: number;
+    error?: string;
+}
+/**
+ * A single test case for evaluating a workflow.
+ * @public
+ */
+interface WorkflowTestCase {
+    id: string;
+    name: string;
+    input: string;
+    expectedOutput?: string;
+    expectedAgent?: string;
+    criteria?: EvaluationCriterion[];
+    tags?: string[];
+}
+/**
+ * A criterion for grading a workflow run.
+ * @public
+ */
+interface EvaluationCriterion {
+    id: string;
+    name: string;
+    type: 'exact_match' | 'contains' | 'regex' | 'llm_graded' | 'custom';
+    weight: number;
+    pattern?: string;
+    graderPrompt?: string;
+    scoringFunction?: string;
+    threshold?: number;
+}
+/**
+ * Result of evaluating a single test case.
+ * @public
+ */
+interface TestCaseResult {
+    testCaseId: string;
+    passed: boolean;
+    score: number;
+    actualOutput: string;
+    actualAgent?: string;
+    criterionResults: Array<{
+        criterionId: string;
+        passed: boolean;
+        score: number;
+        details?: string;
+    }>;
+    trace: WorkflowRunTrace;
+    durationMs: number;
+}
+/**
+ * Result of an evaluation run across multiple test cases.
+ * @public
+ */
+interface WorkflowEvaluationResult {
+    evaluationId: string;
+    workflowId: string;
+    workflowVersion: number;
+    ranAt: string;
+    ranBy?: string;
+    testCaseResults: TestCaseResult[];
+    overallScore: number;
+    passRate: number;
+    totalDurationMs: number;
+}
+/**
+ * A stored set of test cases for repeatable evaluation.
+ * @public
+ */
+interface WorkflowTestSuite {
+    id: string;
+    name: string;
+    workflowId: string;
+    testCases: WorkflowTestCase[];
+    createdAt: string;
+    updatedAt: string;
+}
+/**
+ * Creates a default empty workflow definition.
+ */
+declare function createDefaultWorkflow(id: string, name: string, createdBy?: string): WorkflowDefinition;
+/**
+ * Type guard for AgentNodeData.
+ */
+declare function isAgentNodeData(data: WorkflowNodeData): data is AgentNodeData;
+/**
+ * Type guard for ToolNodeData.
+ */
+declare function isToolNodeData(data: WorkflowNodeData): data is ToolNodeData;
+/**
+ * Type guard for GuardrailNodeData.
+ */
+declare function isGuardrailNodeData(data: WorkflowNodeData): data is GuardrailNodeData;
+/**
+ * Type guard for LogicNodeData.
+ */
+declare function isLogicNodeData(data: WorkflowNodeData): data is LogicNodeData;
+/**
+ * Type guard for UserInteractionNodeData.
+ */
+declare function isUserInteractionNodeData(data: WorkflowNodeData): data is UserInteractionNodeData;
+
+declare const WORKFLOW_TEMPLATES: WorkflowDefinition[];
+
+/**
+ * Built-in AI provider identifiers shipped with the plugin.
+ * @public
+ */
+type BuiltInProviderType = 'llamastack' | 'googleadk' | 'kagenti';
+/**
+ * All accepted provider identifiers.
+ *
+ * Built-in types (`llamastack`, `googleadk`) are autocompleted,
+ * but arbitrary string IDs from extension-registered providers
+ * are also accepted via the `(string & {})` widening pattern.
+ *
+ * @public
+ */
+type ProviderType = BuiltInProviderType | (string & {});
+/**
+ * Capability categories that a provider may support.
+ *
+ * Used by the admin panel to conditionally render config tabs
+ * and by the backend to gate API endpoints.
+ *
+ * @public
+ */
+interface ProviderCapabilities {
+    readonly chat: boolean;
+    readonly rag: boolean;
+    readonly safety: boolean;
+    readonly evaluation: boolean;
+    readonly conversations: boolean;
+    readonly mcpTools: boolean;
+    readonly tools: boolean;
+    /** Provider manages tool lifecycle (build, deploy, route) */
+    readonly toolLifecycle: boolean;
+    /** Provider manages agent lifecycle (build, deploy, migrate) */
+    readonly agentLifecycle: boolean;
+    /** Provider supports DevSpaces integration */
+    readonly devSpaces: boolean;
+    /** Provider needs context hydrated from DB on non-streaming paths */
+    readonly contextHydration: boolean;
+    /** Provider registers its own sub-routes (e.g. kagenti-specific endpoints) */
+    readonly providerRoutes: boolean;
+}
+/**
+ * Definition of a single provider-specific config field.
+ *
+ * The admin panel uses these to render dynamic forms based
+ * on which provider is active.
+ *
+ * @public
+ */
+interface ProviderConfigField {
+    /** Config key (matches AdminConfigKey) */
+    readonly key: string;
+    /** Human-readable label for the form field */
+    readonly label: string;
+    /** Field type determines the form control rendered */
+    readonly type: 'string' | 'boolean' | 'number' | 'select';
+    /** Whether the field is required for the provider to function */
+    readonly required: boolean;
+    /** Help text shown below the field */
+    readonly description?: string;
+    /** Options for 'select' type fields */
+    readonly options?: readonly string[];
+    /** Placeholder text for text inputs */
+    readonly placeholder?: string;
+    /** Whether the field value is sensitive (passwords, secrets) and should be masked in UI */
+    readonly sensitive?: boolean;
+}
+/**
+ * Describes an AI provider's identity, capabilities, and config shape.
+ *
+ * The provider registry holds one descriptor per known provider,
+ * including placeholders for providers that are not yet implemented.
+ *
+ * @public
+ */
+interface ProviderDescriptor {
+    /** Unique provider identifier */
+    readonly id: ProviderType;
+    /** Human-readable display name (e.g., "Llama Stack") */
+    readonly displayName: string;
+    /** Short description of the provider */
+    readonly description: string;
+    /** Whether this provider has a working implementation */
+    readonly implemented: boolean;
+    /** Which capability categories this provider supports */
+    readonly capabilities: ProviderCapabilities;
+    /** Provider-specific config field definitions for the admin panel */
+    readonly configFields: readonly ProviderConfigField[];
+}
+/**
+ * Config keys that are shared across all providers.
+ *
+ * These are stored without a provider prefix and apply
+ * regardless of which provider is active.
+ *
+ * @public
+ */
+declare const GLOBAL_CONFIG_KEYS: readonly ["systemPrompt", "branding", "promptGroups", "safetyPatterns", "mcpServers", "disabledMcpServerIds", "agents", "defaultAgent", "maxAgentTurns", "devSpacesApiUrl"];
+/**
+ * Config keys that are scoped per provider.
+ *
+ * When stored in the database, these are prefixed with the
+ * provider ID (e.g., `llamastack::model`). This allows each
+ * provider to retain its own settings when switching.
+ *
+ * @public
+ */
+declare const PROVIDER_SCOPED_KEYS: readonly ["model", "baseUrl", "kagentiBaseUrl", "toolChoice", "enableWebSearch", "enableCodeInterpreter", "safetyEnabled", "inputShields", "outputShields", "safetyOnError", "evaluationEnabled", "scoringFunctions", "minScoreThreshold", "evaluationOnError", "vectorStoreConfig", "activeVectorStoreIds", "maxToolCalls", "maxOutputTokens", "temperature", "safetyIdentifier"];
+/**
+ * Type-safe element of {@link GLOBAL_CONFIG_KEYS}.
+ * @public
+ */
+type GlobalConfigKey = (typeof GLOBAL_CONFIG_KEYS)[number];
+/**
+ * Type-safe element of {@link PROVIDER_SCOPED_KEYS}.
+ * @public
+ */
+type ProviderScopedKey = (typeof PROVIDER_SCOPED_KEYS)[number];
+/**
+ * Build a provider-scoped config key for database storage.
+ *
+ * @param provider - The provider ID to scope under
+ * @param key - The base config key
+ * @returns A scoped key in the format `provider::key`
+ * @public
+ */
+declare function scopedConfigKey(provider: ProviderType, key: string): string;
+/**
+ * Check whether a config key is provider-scoped.
+ *
+ * @param key - The config key to check
+ * @returns `true` if the key should be stored per-provider
+ * @public
+ */
+declare function isProviderScopedKey(key: string): key is ProviderScopedKey;
+/**
+ * Check whether a config key is global (shared across providers).
+ *
+ * @param key - The config key to check
+ * @returns `true` if the key is shared across all providers
+ * @public
+ */
+declare function isGlobalConfigKey(key: string): key is GlobalConfigKey;
+
+export { DEFAULT_BRANDING, FileFormat, GLOBAL_CONFIG_KEYS, LEGACY_STAGE_MAP, LIFECYCLE_STAGE_ORDER, LIFECYCLE_TRANSITIONS, PROVIDER_SCOPED_KEYS, WORKFLOW_TEMPLATES, augmentAccessPermission, augmentAdminPermission, augmentPermissions, createDefaultWorkflow, deriveRoleFromTopology, getAvailableTransitions, isAgentNodeData, isGlobalConfigKey, isGuardrailNodeData, isLogicNodeData, isProviderScopedKey, isToolNodeData, isUserInteractionNodeData, isValidTransition, normalizeLifecycleStage, scopedConfigKey };
+export type { AdminConfigEntry, AdminConfigKey, AgentFunctionDef, AgentLifecycleAction, AgentLifecycleStage, AgentLifecycleTransition, AgentNodeData, AgentRole, AgentTopologyNode, AugmentStatus, BrandingConfig, BuiltInProviderType, ChatAgent, ChatAgentConfig, ChatMessage, ChatResponse, ChatToolConfig, ClassifyNodeData, ConversationSummary, DevSpacesCreateWorkspaceRequest, DevSpacesCreateWorkspaceResponse, DevSpacesDeleteWorkspaceRequest, DevSpacesHealthResponse, DevSpacesListWorkspacesResponse, DevSpacesStopWorkspaceRequest, DevSpacesWorkspace, DocumentInfo, EndNodeData, EvaluationCriterion, EvaluationResult, FileSearchNodeData, GlobalConfigKey, GuardrailNodeData, GuardrailRule, InputTokensDetails, KagentiAgentCard, KagentiAgentCardSkill, KagentiAgentDetail, KagentiAgentSummary, KagentiAuthConfig, KagentiBuildInfo, KagentiBuildListItem, KagentiBuildStrategy, KagentiConfigMapKeyRef, KagentiCreateAgentRequest, KagentiCreateAgentResponse, KagentiCreateIntegrationRequest, KagentiCreateKeyRequest, KagentiCreateTeamRequest, KagentiCreateToolRequest, KagentiCreateToolResponse, KagentiDashboardConfig, KagentiEnvVar, KagentiEnvVarSource, KagentiFeatureFlags, KagentiFinalizeAgentBuildRequest, KagentiFinalizeToolBuildRequest, KagentiIntegration, KagentiLlmKey, KagentiLlmTeam, KagentiMcpInvokeResponse, KagentiMcpToolSchema, KagentiMigratableAgent, KagentiMigrateAgentResponse, KagentiMigrateAllResponse, KagentiPersistentStorageConfig, KagentiResourceConfigFromBuild, KagentiResourceLabels, KagentiRouteStatus, KagentiSandboxAgentInfo, KagentiSandboxCreateRequest, KagentiSandboxSession, KagentiSecretKeyRef, KagentiServicePort, KagentiSessionTokenUsage, KagentiShipwrightConfig, KagentiSidecar, KagentiToolDetail, KagentiToolSummary, KagentiTriggerBuildRunResponse, KagentiTriggerRequest, LogicNodeData, LogicNodeKind, MCPServerStatus, MCPToolInfo, McpNodeData, NodeExecutionRecord, NodePosition, NormalizedStreamEvent, NoteNodeData, OutputTokensDetails, PendingApprovalInfo, PromptCapabilities, PromptCard, PromptGroup, ProviderCapabilities, ProviderConfigField, ProviderDescriptor, ProviderScopedKey, ProviderStatus, ProviderType, QuickAction, QuickPrompt, RAGSource, RagGenerateResult, RagTestChunk, RagTestResult, ReasoningSummary, ResponseUsage, SecurityMode, SetStateNodeData, StartNodeData, StreamAgentHandoffEvent, StreamArtifactEvent, StreamAuthRequiredEvent, StreamBackendToolExecutingEvent, StreamCitationEvent, StreamCitationReference, StreamCompletedEvent, StreamErrorEvent, StreamFormDescriptor, StreamFormField, StreamFormRequestEvent, StreamRagResultsEvent, StreamReasoningDeltaEvent, StreamReasoningDoneEvent, StreamSecretDemand, StreamStartedEvent, StreamTextDeltaEvent, StreamTextDoneEvent, StreamToolApprovalEvent, StreamToolCompletedEvent, StreamToolDeltaEvent, StreamToolDiscoveryEvent, StreamToolFailedEvent, StreamToolStartedEvent, SyncResult, TestCaseResult, ToolCallInfo, ToolCapabilityInfo, ToolNodeData, ToolNodeKind, TransformNodeData, UploadResult, UserInteractionField, UserInteractionNodeData, VectorStoreConfig, VectorStoreCreateResult, VectorStoreInfo, VectorStoreStatus, VectorStoreStatusResult, Workflow, WorkflowDefinition, WorkflowEdge, WorkflowEdgeType, WorkflowEvaluationResult, WorkflowNode, WorkflowNodeData, WorkflowNodeType, WorkflowRunStatus, WorkflowRunTrace, WorkflowSettings, WorkflowStatus, WorkflowStep, WorkflowTestCase, WorkflowTestSuite, WorkflowVersion };