@datalayer/agent-runtimes 1.0.4 → 1.0.6

package/lib/tools/adapters/copilotkit/lexicalHooks.js

@@ -10,7 +10,7 @@
  */
 import { useMemo } from 'react';
 import { useLexicalStore, DefaultExecutor as LexicalDefaultExecutor, lexicalToolDefinitions, lexicalToolOperations, } from '@datalayer/jupyter-lexical';
-import { createAllCopilotKitActions, ActionRegistrar, } from './CopilotKitToolAdapter';
+import { createAllCopilotKitActions } from './CopilotKitToolAdapter';
 /**
  * Hook that creates CopilotKit actions for lexical tools.
  * Returns stable actions array that won't cause re-renders.
@@ -55,5 +55,3 @@ export function useLexicalToolActions(documentId, contextOverrides) {
     const actions = useMemo(() => createAllCopilotKitActions(lexicalToolDefinitions, lexicalToolOperations, context), [context]);
     return actions;
 }
-// Re-export shared types and components for convenience
-export { ActionRegistrar };

package/lib/tools/adapters/copilotkit/notebookHooks.d.ts

@@ -1,5 +1,5 @@
 import type { ToolExecutionContext } from '@datalayer/jupyter-react';
-import { createAllCopilotKitActions, ActionRegistrar, type UseFrontendToolFn } from './CopilotKitToolAdapter';
+import { createAllCopilotKitActions } from './CopilotKitToolAdapter';
 /**
  * Hook that creates CopilotKit actions for notebook tools.
  * Returns stable actions array that won't cause re-renders.
@@ -24,4 +24,3 @@ import { createAllCopilotKitActions, ActionRegistrar, type UseFrontendToolFn } f
  * ```
  */
 export declare function useNotebookToolActions(documentId: string, contextOverrides?: Partial<Omit<ToolExecutionContext, 'executor' | 'documentId'>>): ReturnType<typeof createAllCopilotKitActions>;
-export { ActionRegistrar, type UseFrontendToolFn };

package/lib/tools/adapters/copilotkit/notebookHooks.js

@@ -10,7 +10,7 @@
  */
 import { useMemo } from 'react';
 import { notebookStore, DefaultExecutor, notebookToolDefinitions, notebookToolOperations, } from '@datalayer/jupyter-react';
-import { createAllCopilotKitActions, ActionRegistrar, } from './CopilotKitToolAdapter';
+import { createAllCopilotKitActions } from './CopilotKitToolAdapter';
 // Hook wrapper to get notebook store state
 const useNotebookStore = () => notebookStore.getState();
 /**
@@ -55,5 +55,3 @@ export function useNotebookToolActions(documentId, contextOverrides) {
     // Create and return CopilotKit actions (stable reference)
     return useMemo(() => createAllCopilotKitActions(notebookToolDefinitions, notebookToolOperations, context), [context]);
 }
-// Re-export shared types and components for convenience
-export { ActionRegistrar };

package/lib/tools/index.d.ts

@@ -5,5 +5,3 @@
  */
 export * from './adapters/copilotkit';
 export { ToolExecutor, createToolExecutor, type ToolExecutionContext, } from './ToolExecutor';
-export type { ToolDefinition, FrontendToolDefinition, BackendToolDefinition, ToolLocation, ToolParameter, ToolRenderStatus, ToolRenderProps, ToolRenderAndWaitProps, ToolCallRequest, ToolExecutionResult, ToolRegistryEntry, } from '../types/tools';
-export { isFrontendTool, isBackendTool, hasHitlRender } from '../types/tools';

package/lib/tools/index.js

@@ -11,4 +11,3 @@
 export * from './adapters/copilotkit';
 // Tool executor
 export { ToolExecutor, createToolExecutor, } from './ToolExecutor';
-export { isFrontendTool, isBackendTool, hasHitlRender } from '../types/tools';

package/lib/types/agents-lifecycle.d.ts

@@ -18,6 +18,24 @@ export type CreateAgentRuntimeRequest = {
     agentSpecId?: string;
     /** Full agent spec payload to propagate to backend services */
     agentSpec?: Record<string, any>;
+    /** Account UID (user or organization) charged for runtime costs */
+    billableAccountUid?: string;
+    /** User account handle used for user home mount path. */
+    userAccountHandle?: string;
+    /** Account kind charged for runtime costs. */
+    billableAccountType?: 'user' | 'organization' | 'team';
+    /** Account handle charged for runtime costs. */
+    billableAccountHandle?: string;
+    /** Source organization UID for team-billed runtimes. */
+    billableSourceOrganizationUid?: string;
+    /** Source organization handle for team-billed runtimes. */
+    billableSourceOrganizationHandle?: string;
+    /** Mount account home folder into runtime. */
+    mountHomeFolder?: boolean;
+    /** Optional volume UID to mount into runtime. */
+    volumeUid?: string;
+    /** Optional volume UIDs to mount into runtime. */
+    volumeUids?: string[];
 };
 export type CreateRuntimeApiResponse = {
     success?: boolean;

package/lib/types/agents.d.ts

@@ -53,6 +53,12 @@ export type AgentRuntimeData = {
     token?: string;
     agentSpec?: AgentSpec;
     agent_spec_id?: string;
+    billable_account_uid?: string;
+    billable_account_type?: 'user' | 'organization' | 'team';
+    billable_account_handle?: string;
+    mount_home_folder?: boolean;
+    volume_uid?: string;
+    volume_uids?: string[];
 };
 export interface RunningAgent {
     /** Unique agent ID within the runtime */

package/lib/types/agentspecs.d.ts

@@ -33,6 +33,8 @@ export interface AgentSpec {
     enabled: boolean;
     /** AI model identifier to use for this agent */
     model?: string;
+    /** Inference provider routing strategy */
+    inferenceProvider?: 'local' | 'datalayer';
     /** MCP servers used by this agent */
     mcpServers: MCPServer[];
     /** Skills available to this agent */
@@ -57,7 +59,7 @@ export interface AgentSpec {
     welcomeNotebook?: string;
     /** Path to Lexical document to show on agent creation */
     welcomeDocument?: string;
-    /** Sandbox variant to use for this agent ('local-eval', 'jupyter', 'local-jupyter') */
+    /** Sandbox variant to use for this agent ('eval', 'jupyter') */
     sandboxVariant?: string;
     /** User-facing objective for the agent */
     goal?: string;
@@ -87,4 +89,55 @@ export interface AgentSpec {
     notifications?: AgentNotificationConfig;
     /** Memory backend identifier (e.g., 'ephemeral', 'mem0', 'memu', 'simplemem') */
     memory?: string;
+    /** Pre-launch hooks (package installs and sandbox code). */
+    preHooks?: {
+        packages?: string[];
+        sandbox?: string | string[];
+    };
+    /** Post-stop hooks (sandbox cleanup code). */
+    postHooks?: {
+        sandbox?: string | string[];
+    };
+    /** Per-tool-call hooks (authorization/audit integration). */
+    toolHooks?: Record<string, any>;
+    /** JSON schema for launch-time parameter values. */
+    parameters?: Record<string, any>;
+    /** Subagent delegation configuration. */
+    subagents?: SubAgentsConfig;
+}
+/**
+ * Configuration for a subagent within an agent specification.
+ */
+export interface SubAgentSpecConfig {
+    /** Unique identifier for the subagent */
+    name: string;
+    /** Brief description shown to the parent agent */
+    description: string;
+    /** System prompt for the subagent */
+    instructions: string;
+    /** LLM model to use (defaults to parent agent's model) */
+    model?: string;
+    /** Whether the subagent can ask the parent for clarification */
+    canAskQuestions?: boolean;
+    /** Maximum questions the subagent may ask per task */
+    maxQuestions?: number;
+    /** Default execution mode preference */
+    preferredMode?: 'sync' | 'async' | 'auto';
+    /** Typical task complexity hint for auto-mode selection */
+    typicalComplexity?: 'simple' | 'moderate' | 'complex';
+    /** Whether this subagent typically needs user context */
+    typicallyNeedsContext?: boolean;
+}
+/**
+ * Top-level subagents configuration for an agent specification.
+ */
+export interface SubAgentsConfig {
+    /** List of subagent configurations */
+    subagents: SubAgentSpecConfig[];
+    /** Default model for subagents that don't specify one */
+    defaultModel?: string;
+    /** Include a general-purpose fallback subagent */
+    includeGeneralPurpose?: boolean;
+    /** Maximum depth for nested subagent delegation (0 = no nesting) */
+    maxNestingDepth?: number;
 }

package/lib/types/benchmarks.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Evaluation benchmark specification.
+ */
+export interface BenchmarkSpec {
+    /** Unique benchmark identifier */
+    id: string;
+    /** Version */
+    version?: string;
+    /** Display name */
+    name: string;
+    /** Description of the benchmark */
+    description: string;
+    /** Category: Coding, Knowledge, Reasoning, Agentic, or Safety */
+    category: 'Coding' | 'Knowledge' | 'Reasoning' | 'Agentic' | 'Safety';
+    /** Number of tasks in the benchmark */
+    task_count: number;
+    /** Primary metric (e.g., 'pass@1', 'accuracy', 'success_rate') */
+    metric: string;
+    /** Source URL or repository */
+    source: string;
+    /** Difficulty level */
+    difficulty: 'easy' | 'medium' | 'hard' | 'expert';
+    /** Relevant languages */
+    languages: string[];
+    /** Dataset source mode used by this benchmark */
+    dataset_source?: 'hosted' | 'local' | 'hybrid';
+    /** Whether this benchmark can be tracked in live monitoring */
+    supports_live_monitoring?: boolean;
+    /** Whether this benchmark supports side-by-side run comparison */
+    supports_experiment_comparison?: boolean;
+    /** Shapes emitted by evaluators (pass_rate, numeric, categorical, error_only) */
+    evaluator_shapes?: Array<'pass_rate' | 'numeric' | 'categorical' | 'error_only'>;
+    /** Evaluator IDs (optionally versioned) used to score this benchmark */
+    evaluators: string[];
+    /** Suggested time windows for monitoring UIs */
+    recommended_windows?: string[];
+    /** Whether traces include links from results to execution spans */
+    trace_integration?: boolean;
+    /** Whether cases are editable in hosted UI */
+    dataset_editability?: 'read-only' | 'editable';
+    /** SDK maturity level for this benchmark */
+    sdk_support?: 'none' | 'experimental' | 'stable';
+}

package/lib/types/benchmarks.js

@@ -0,0 +1,5 @@
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+export {};

package/lib/types/chat.d.ts

@@ -9,8 +9,39 @@ import type { Protocol, ProtocolConfig } from './protocol';
 import type { McpServerSelection } from './inference';
 import type { MCPServerTool } from './mcp';
 import type { AgentRuntimeConfig } from './config';
+import type { SandboxWsStatus } from './sandbox';
 import type { FrontendToolDefinition } from './tools';
 import type { PoweredByTagProps } from '../chat/display/PoweredByTag';
+/**
+ * Context passed to tool-call pre-hooks.
+ * Fires when a tool call starts executing (backend or frontend).
+ */
+export interface ToolCallStartContext {
+    /** The tool name as declared by the agent */
+    toolName: string;
+    /** Unique identifier for this tool invocation */
+    toolCallId: string;
+    /** Arguments passed to the tool */
+    args: Record<string, unknown>;
+}
+/**
+ * Context passed to tool-call post-hooks.
+ * Fires when a tool result is received.
+ */
+export interface ToolCallCompleteContext {
+    /** The tool name as declared by the agent */
+    toolName: string;
+    /** Unique identifier for this tool invocation */
+    toolCallId: string;
+    /** Arguments that were passed to the tool */
+    args: Record<string, unknown>;
+    /** The tool result (may be a string, object, or undefined on error) */
+    result: unknown;
+    /** Final status of the tool invocation */
+    status: DisplayToolCallStatus;
+    /** Error message, if the tool call failed */
+    error?: string;
+}
 /**
  * View mode for the chat component.
  * - 'floating': Full-height floating panel (pinned to the right edge with offset)
@@ -167,12 +198,197 @@ export interface MCPServerConfig {
     isConfig?: boolean;
     isRunning?: boolean;
 }
+/**
+ * Common props shared by all Chat wrapper components
+ * (Chat, ChatFloating, ChatSidebar, ChatStandalone, ChatPopupStandalone).
+ *
+ * These props represent the public API surface that consumers interact with.
+ * Wrapper components forward most of them to ChatBase and translate others
+ * (e.g. `showNewChatButton` → `headerButtons.showNewChat`).
+ *
+ * Each wrapper extends this interface with component-specific props
+ * (e.g. `position`, `defaultOpen`, `width` for floating variants).
+ *
+ * Use `panelProps` as an escape hatch to pass any ChatBase prop not
+ * directly surfaced in this interface.
+ */
+export interface ChatCommonProps {
+    /**
+     * Protocol type or full configuration.
+     *
+     * When a `Protocol` string is provided (e.g. `'vercel-ai'`), it is forwarded
+     * to ChatBase. When a full `ProtocolConfig` object is provided, it is used
+     * directly.
+     *
+     * @default 'vercel-ai'
+     */
+    protocol?: Protocol | ProtocolConfig;
+    /**
+     * Use Zustand store for state management instead of protocol endpoint.
+     * @default true
+     */
+    useStore?: boolean;
+    /** Chat title */
+    title?: string;
+    /** Chat subtitle (rendered under the title in the header) */
+    subtitle?: string;
+    /** Description shown in empty state */
+    description?: string;
+    /** Show header */
+    showHeader?: boolean;
+    /** Show input area */
+    showInput?: boolean;
+    /** Keep input visible but disabled */
+    disableInputPrompt?: boolean;
+    /** Custom class name */
+    className?: string;
+    /** Children to render in the messages area */
+    children?: ReactNode;
+    /** Custom brand icon for header / empty state */
+    brandIcon?: ReactNode;
+    /** Input placeholder */
+    placeholder?: string;
+    /** Show new chat button in header */
+    showNewChatButton?: boolean;
+    /** Show clear button in header */
+    showClearButton?: boolean;
+    /** Show settings button in header */
+    showSettingsButton?: boolean;
+    /** Show powered by tag */
+    showPoweredBy?: boolean;
+    /** Powered by tag props */
+    poweredByProps?: Partial<PoweredByTagProps>;
+    /** Callback when settings is clicked */
+    onSettingsClick?: () => void;
+    /** Callback when new chat is triggered */
+    onNewChat?: () => void;
+    /** Callback when the component opens */
+    onOpen?: () => void;
+    /** Callback when the component closes */
+    onClose?: () => void;
+    /**
+     * Custom message handler.
+     * When provided, uses this handler instead of protocol mode.
+     */
+    onSendMessage?: MessageHandler;
+    /**
+     * Enable streaming mode for custom message handler.
+     * @default false
+     */
+    enableStreaming?: boolean;
+    /** Show model selector */
+    showModelSelector?: boolean;
+    /** Show tools menu */
+    showToolsMenu?: boolean;
+    /** Show skills menu */
+    showSkillsMenu?: boolean;
+    /**
+     * Show token usage bar.
+     * @default true
+     */
+    showTokenUsage?: boolean;
+    /** Indicate tools are accessed via Codemode meta-tools */
+    codemodeEnabled?: boolean;
+    /**
+     * Callback fired when the user toggles codemode from the Tools menu.
+     * When omitted, the toggle renders in read-only mode.
+     */
+    onToggleCodemode?: (enabled: boolean) => void | Promise<void>;
+    /** Initial model ID to select (e.g., 'openai:gpt-4o-mini') */
+    initialModel?: string;
+    /**
+     * Override the list of available models.
+     * When provided, replaces models returned by the config endpoint.
+     */
+    availableModels?: ModelConfig[];
+    /** MCP server selections to enable (others disabled) */
+    mcpServers?: McpServerSelection[];
+    /** Initial skill IDs to enable */
+    initialSkills?: string[];
+    /** Custom render function for tool results */
+    renderToolResult?: RenderToolResult;
+    /** Frontend tool definitions to register with the chat */
+    frontendTools?: FrontendToolDefinition[];
+    /** Pre-hook: fires when a tool call starts executing */
+    onToolCallStart?: (context: ToolCallStartContext) => void;
+    /** Post-hook: fires when a tool result is received */
+    onToolCallComplete?: (context: ToolCallCompleteContext) => void;
+    /** Suggestions to show in empty state */
+    suggestions?: Suggestion[];
+    /**
+     * Whether to auto-submit when a suggestion is clicked.
+     * @default true
+     */
+    submitOnSuggestionClick?: boolean;
+    /**
+     * Hide assistant messages that follow a rendered tool call UI.
+     * @default false
+     */
+    hideMessagesAfterToolUI?: boolean;
+    /** Runtime ID for conversation persistence */
+    runtimeId?: string;
+    /** Optional legacy endpoint URL for fetching conversation history */
+    historyEndpoint?: string;
+    /** Auth token for the agent runtime */
+    authToken?: string;
+    /** Optional auth token for the legacy history endpoint */
+    historyAuthToken?: string;
+    /**
+     * A prompt to send after conversation history is loaded (sent once).
+     */
+    pendingPrompt?: string;
+    /**
+     * Show the information icon in the header.
+     * @default false
+     */
+    showInformation?: boolean;
+    /** Callback when the information icon is clicked */
+    onInformationClick?: () => void;
+    /** Current chat view mode for header segmented toggle */
+    chatViewMode?: ChatViewMode;
+    /** Callback when user switches chat view mode */
+    onChatViewModeChange?: (mode: ChatViewMode) => void;
+    /** External context snapshot data for the token usage bar */
+    contextSnapshot?: import('./context').ContextSnapshotData;
+    /** External MCP toolsets status data */
+    mcpStatusData?: import('./mcp').McpToolsetsStatusResponse | null;
+    /** External codemode status data (e.g. from WebSocket stream). */
+    codemodeStatusData?: import('./stream').CodemodeStatusData | null;
+    /** Optional sandbox status override for immediate UI updates. */
+    sandboxStatusData?: SandboxWsStatus | null;
+    /**
+     * Whether to render the top-of-chat tool approval banner when there are
+     * pending approvals. @default true
+     */
+    showToolApprovalBanner?: boolean;
+    /** Pending tool approval requests to render in the top banner. */
+    pendingApprovals?: import('../chat/tools').PendingApproval[];
+    /** Called when the user approves a pending request. */
+    onApproveApproval?: (approvalId: string, note?: string) => void | Promise<boolean | void>;
+    /** Called when the user rejects a pending request. */
+    onRejectApproval?: (approvalId: string, note?: string) => void | Promise<boolean | void>;
+    /** Custom header content (rendered below title row) */
+    headerContent?: ReactNode;
+    /** Custom header actions (rendered in title row, right side) */
+    headerActions?: ReactNode;
+    /** Auto-focus the input on mount */
+    autoFocus?: boolean;
+    /** Callback for state updates */
+    onStateUpdate?: (state: unknown) => void;
+    /**
+     * Additional ChatBase props (escape hatch).
+     * Props set here are spread onto ChatBase as overrides.
+     */
+    panelProps?: Partial<ChatBaseProps>;
+}
 /**
  * ChatBase props
  */
 export interface ChatBaseProps {
     /** Chat title */
     title?: string;
+    /** Chat subtitle (rendered under the title in the header) */
+    subtitle?: string;
     /** Show header */
     showHeader?: boolean;
     /**
@@ -182,12 +398,39 @@ export interface ChatBaseProps {
      * @default true
      */
     showTokenUsage?: boolean;
+    /**
+     * External context snapshot data for the token usage bar.
+     * When provided, this overrides the built-in useContextSnapshot hook
+     * (which is a no-op since the REST endpoint was removed).
+     * Pass live data received from the monitoring WebSocket.
+     */
+    contextSnapshot?: import('./context').ContextSnapshotData;
+    /**
+     * External MCP toolsets status data for the MCP indicator.
+     * When provided, the data is forwarded to the McpStatusIndicator
+     * so it shows live status instead of "No MCP Server defined".
+     */
+    mcpStatusData?: import('./mcp').McpToolsetsStatusResponse | null;
+    /**
+     * External codemode status data. When provided, it is forwarded to
+     * AgentDetails so the info panel can render a live codemode status
+     * without waiting for the global WebSocket stream.
+     */
+    codemodeStatusData?: import('./stream').CodemodeStatusData | null;
+    /**
+     * External sandbox status data for the sandbox indicator.
+     * When provided, this data is preferred over the indicator's local
+     * WebSocket state, which allows optimistic variant updates.
+     */
+    sandboxStatusData?: SandboxWsStatus | null;
     /** Show loading indicator */
     showLoadingIndicator?: boolean;
     /** Show error messages */
     showErrors?: boolean;
     /** Show input area */
     showInput?: boolean;
+    /** Keep input visible but disabled */
+    disableInputPrompt?: boolean;
     /** Show model selector (for protocols that support it) */
     showModelSelector?: boolean;
     /** Show tools menu (for protocols that support it) */
@@ -196,6 +439,11 @@ export interface ChatBaseProps {
     showSkillsMenu?: boolean;
     /** Indicate tools are accessed via Codemode meta-tools */
     codemodeEnabled?: boolean;
+    /**
+     * Callback fired when the user toggles codemode from the Tools menu.
+     * When omitted, the toggle renders in read-only mode.
+     */
+    onToggleCodemode?: (enabled: boolean) => void | Promise<void>;
     /** Initial model ID to select (e.g., 'openai:gpt-4o-mini') */
     initialModel?: string;
     /**
@@ -214,6 +462,22 @@ export interface ChatBaseProps {
     loadingState?: React.ReactNode;
     /** Header actions */
     headerActions?: React.ReactNode;
+    /** Notebook kernel indicator state override for the chat header. */
+    kernelIndicatorState?: import('@datalayer/jupyter-react').ExecutionState;
+    /**
+     * Live notebook kernel connection. When provided, the chat header
+     * renders the same `<KernelIndicator>` as the notebook toolbar so
+     * the colour and tooltip remain in sync with the notebook runtime.
+     */
+    kernel?: import('@jupyterlab/services/lib/kernel/kernel').IKernelConnection | null;
+    /** Optional environment name displayed in kernel indicator details. */
+    kernelEnvironmentName?: string;
+    /** Optional CPU info displayed in kernel indicator details. */
+    kernelCpu?: string;
+    /** Optional memory info displayed in kernel indicator details. */
+    kernelMemory?: string;
+    /** Optional GPU info displayed in kernel indicator details. */
+    kernelGpu?: string;
     /**
      * Current chat view mode.
      * When provided, a segmented view-mode toggle is rendered in the header
@@ -392,20 +656,18 @@ export interface ChatBaseProps {
     }>;
     /**
      * Runtime ID for conversation persistence.
-     * When provided, messages are fetched from the server API on page reload
-     * and prevents message mixing between different agent runtimes.
+     * When provided, messages are restored from websocket snapshot data on
+     * reload and prevents message mixing between different agent runtimes.
      */
     runtimeId?: string;
     /**
-     * Endpoint URL for fetching conversation history.
-     * When runtimeId is provided, this endpoint is called to fetch
-     * the conversation history on mount.
-     * If not provided, defaults to `{protocol.endpoint}/api/v1/history`.
+     * Optional legacy endpoint URL for history backfill.
+     * History loading is websocket-first; this field is kept for
+     * compatibility with custom integrations.
      */
     historyEndpoint?: string;
     /**
-     * Auth token for the history endpoint.
-     * If not provided, uses the protocol's authToken.
+     * Optional auth token for the legacy history endpoint.
      */
     historyAuthToken?: string;
     /**
@@ -413,4 +675,59 @@ export interface ChatBaseProps {
      * The message is shown in the chat and sent to the agent exactly once.
      */
     pendingPrompt?: string;
+    /**
+     * Pre-hook: fires when a tool call starts executing.
+     * Called for both backend and frontend tools.
+     *
+     * @example
+     * ```tsx
+     * <Chat
+     *   onToolCallStart={({ toolName, args }) => {
+     *     console.log(`Tool ${toolName} started`, args);
+     *   }}
+     * />
+     * ```
+     */
+    onToolCallStart?: (context: ToolCallStartContext) => void;
+    /**
+     * Post-hook: fires when a tool result is received.
+     * Called for both backend and frontend tools.
+     * Use this to react to specific tool outcomes (e.g. update UI state
+     * when a `load_skill` tool completes).
+     *
+     * @example
+     * ```tsx
+     * <Chat
+     *   onToolCallComplete={({ toolName, result, status }) => {
+     *     if (toolName === 'load_skill' && status === 'complete') {
+     *       // Update skills sidebar from load_skill result
+     *       updateSkillsFromResult(result);
+     *     }
+     *   }}
+     * />
+     * ```
+     */
+    onToolCallComplete?: (context: ToolCallCompleteContext) => void;
+    /**
+     * Whether to render the top-of-chat tool approval banner (and its review
+     * dialog) when `pendingApprovals` is non-empty. The banner/dialog render
+     * only when approvals are actually pending; this flag lets integrators opt
+     * out entirely.
+     * @default true
+     */
+    showToolApprovalBanner?: boolean;
+    /**
+     * Pending tool approval requests to render in the built-in banner.
+     * Typically sourced from the approvals websocket in the hosting app.
+     */
+    pendingApprovals?: import('../chat/tools').PendingApproval[];
+    /**
+     * Called when the user approves a pending request (from banner "Approve All"
+     * or from the review dialog).
+     */
+    onApproveApproval?: (approvalId: string, note?: string) => void | Promise<boolean | void>;
+    /**
+     * Called when the user rejects a pending request from the review dialog.
+     */
+    onRejectApproval?: (approvalId: string, note?: string) => void | Promise<boolean | void>;
 }

package/lib/types/context.d.ts

@@ -54,6 +54,33 @@ export interface ContextSnapshotData {
         turns: number;
         durationSeconds: number;
     } | null;
+    costUsage?: {
+        lastTurnCostUsd: number;
+        cumulativeCostUsd: number;
+        perRunBudgetUsd: number | null;
+        cumulativeBudgetUsd: number | null;
+        requestCount: number;
+        totalTokensUsed: number;
+        modelBreakdown: Array<{
+            model: string;
+            inputTokens: number;
+            outputTokens: number;
+            costUsd: number;
+            requests: number;
+        }>;
+        runs: Array<{
+            timestamp: string;
+            model: string;
+            inputTokens: number;
+            outputTokens: number;
+            runCostUsd: number;
+            cumulativeCostUsd: number;
+            pricePerInputToken: number | null;
+            pricePerOutputToken: number | null;
+            pricingResolved: boolean;
+        }>;
+        lastUpdated: string | null;
+    };
     error?: string;
 }
 /**

package/lib/types/cost.d.ts

@@ -15,8 +15,8 @@ export interface ContextUsage {
     summarizationCount: number;
 }
 export interface CostUsage {
-    /** Current run cost in USD */
-    currentRunCostUsd: number;
+    /** Last turn cost in USD */
+    lastTurnCostUsd: number;
     /** Cumulative cost in USD */
     cumulativeCostUsd: number;
     /** Budget limit per run (from agentspec) */