@leanandmean/coding-agent 0.74.1-scramjet.6 → 0.74.1-scramjet.60

package/dist/core/extensions/types.d.ts

@@ -8,7 +8,7 @@
  * - Interact with the user via UI primitives
  */
 import type { AgentMessage, AgentToolResult, AgentToolUpdateCallback, ThinkingLevel, ToolExecutionMode } from "@leanandmean/agent";
-import type { Api, AssistantMessageEvent, AssistantMessageEventStream, Context, ImageContent, Model, OAuthCredentials, OAuthLoginCallbacks, SimpleStreamOptions, SystemPromptSection, TextContent, ToolResultMessage } from "@leanandmean/ai";
+import type { Api, AssistantMessageEvent, AssistantMessageEventStream, Context, ImageContent, Model, OAuthCredentials, OAuthLoginCallbacks, ProviderRequestToolInventory, SimpleStreamOptions, SystemPromptSection, TextContent, ToolResultMessage } from "@leanandmean/ai";
 import type { AutocompleteItem, AutocompleteProvider, Component, EditorComponent, EditorTheme, KeyId, OverlayHandle, OverlayOptions, TUI } from "@leanandmean/tui";
 import type { Static, TSchema } from "typebox";
 import type { Theme } from "../../modes/interactive/theme/theme.js";
@@ -112,6 +112,8 @@ export interface ExtensionUIContext {
     }) | undefined): void;
     /** Set the terminal window/tab title. */
     setTitle(title: string): void;
+    /** Register a callback that supplies the terminal title. When set, updateTerminalTitle() delegates to this provider; if the provider returns undefined, the default title is used. Pass undefined to clear. */
+    setTitleProvider(provider: (() => string | undefined) | undefined): void;
     /** Show a custom component with keyboard focus. */
     custom<T>(factory: (tui: TUI, theme: Theme, keybindings: KeybindingsManager, done: (result: T) => void) => (Component & {
         dispose?(): void;
@@ -119,10 +121,17 @@ export interface ExtensionUIContext {
         dispose?(): void;
     }>, options?: {
         overlay?: boolean;
+        /** Install visual context at a pending tool row and flush before focusing; retained mode also guards visibility. Not persisted. */
+        toolAttachedContext?: {
+            toolCallId: string;
+            render: (tui: TUI, theme: Theme) => Component;
+        };
         /** Overlay positioning/sizing options. Can be static or a function for dynamic updates. */
         overlayOptions?: OverlayOptions | (() => OverlayOptions);
         /** Called with the overlay handle after the overlay is shown. Use to control visibility. */
         onHandle?: (handle: OverlayHandle) => void;
+        /** Ordinary input-slot allocation before rendering; undefined on initialization/release. Not a visibility guarantee. */
+        onAvailableHeight?: (rows: number | undefined) => void;
     }): Promise<T>;
     /** Paste text into the editor, triggering paste handling (collapse for large content). */
     pasteToEditor(text: string): void;
@@ -192,8 +201,9 @@ export interface ExtensionUIContext {
 export interface ContextUsage {
     /** Estimated context tokens, or null if unknown (e.g. right after compaction, before next LLM response). */
     tokens: number | null;
+    /** Maximum supported total context in tokens. */
     contextWindow: number;
-    /** Context usage as percentage of context window, or null if tokens is unknown. */
+    /** Context usage as percentage of total context, or null if tokens is unknown. */
     percent: number | null;
 }
 export interface CompactOptions {
@@ -221,7 +231,7 @@ export interface DispatchUserInputOptions {
 export interface ExtensionContext {
     /** UI methods for user interaction */
     ui: ExtensionUIContext;
-    /** Whether UI is available (false in print/RPC mode) */
+    /** Whether some UI transport is available; individual methods may still be unsupported (for example custom() in RPC). */
     hasUI: boolean;
     /** Current working directory */
     cwd: string;
@@ -231,6 +241,11 @@ export interface ExtensionContext {
     modelRegistry: ModelRegistry;
     /** Current model (may be undefined) */
     model: Model<any> | undefined;
+    /** Scoped models when a model scope is active (via --models or /scoped-models), empty when no scope is configured */
+    scopedModels: ReadonlyArray<{
+        model: Model<any>;
+        thinkingLevel?: ThinkingLevel;
+    }>;
     /** Whether the agent is idle (not streaming) */
     isIdle(): boolean;
     /** The current abort signal, or undefined when the agent is not streaming. */
@@ -328,7 +343,7 @@ export interface ToolRenderContext<TState = any, TArgs = any> {
     args: TArgs;
     /** Unique id for this tool execution. Stable across call/result renders for the same tool call. */
     toolCallId: string;
-    /** Invalidate just this tool execution component for redraw. */
+    /** Invalidate this tool execution component. Stale lifecycle callbacks are ignored. */
     invalidate: () => void;
     /** Previously returned component for this render slot, if any. */
     lastComponent: Component | undefined;
@@ -367,6 +382,17 @@ export interface ToolDefinition<TParams extends TSchema = TSchema, TDetails = un
     parameters: TParams;
     /** Controls whether ToolExecutionComponent renders the standard colored shell or the tool renders its own framing. */
     renderShell?: "default" | "self";
+    /**
+     * Controls whether the tool can be auto-activated into the LLM-visible tool set.
+     *
+     * - `"default"` (or omitted): the tool participates in normal activation and can be sent to the
+     *   provider and called by the model.
+     * - `"harness-only"`: the tool is never placed in `agent.state.tools` and is therefore never
+     *   provider-visible or model-callable. It stays registered and resolvable (via the full tool
+     *   registry) so the harness can execute it through `pi.invokeHarnessTool`. This is the
+     *   structural guarantee that a system-generated tool cannot masquerade as a model-callable one.
+     */
+    activation?: "default" | "harness-only";
     /** Optional compatibility shim to prepare raw tool call arguments before schema validation. Must return an object conforming to TParams. */
     prepareArguments?: (args: unknown) => Static<TParams>;
     /**
@@ -480,11 +506,34 @@ export interface ContextEvent {
     type: "context";
     messages: AgentMessage[];
 }
+export type DeepReadonly<T> = T extends (...args: any[]) => any ? T : T extends object ? {
+    readonly [K in keyof T]: DeepReadonly<T[K]>;
+} : T;
+export type RoutedModelSnapshot = DeepReadonly<Model<any>>;
+export interface RoutedModelIdentitySnapshot {
+    readonly provider: Model<any>["provider"];
+    readonly id: Model<any>["id"];
+    readonly api: Api;
+}
+/** Fired after context transformation and before provider serialization. Can replace the request-local system prompt. */
+export interface BeforeProviderCallEvent {
+    type: "before_provider_call";
+    model: RoutedModelSnapshot;
+    systemPrompt: Context["systemPrompt"];
+}
 /** Fired before a provider request is sent. Can replace the payload. */
 export interface BeforeProviderRequestEvent {
     type: "before_provider_request";
+    model: RoutedModelSnapshot;
     payload: unknown;
 }
+/** Fired after all provider payload rewrites and before transport. Observation only. */
+export interface ProviderRequestToolInventoryEvent {
+    type: "provider_request_tool_inventory";
+    readonly model: RoutedModelIdentitySnapshot;
+    readonly requestContextToolNames: readonly string[];
+    readonly inventory: DeepReadonly<ProviderRequestToolInventory>;
+}
 /** Fired after a provider response is received and before the response stream is consumed. */
 export interface AfterProviderResponseEvent {
     type: "after_provider_response";
@@ -602,6 +651,16 @@ export interface InputEvent {
     /** Where the input came from */
     source: InputSource;
 }
+export interface InputSessionEntry {
+    customType: string;
+    /**
+     * Extension-defined payload. Must be JSON-serializable: it is persisted with
+     * JSON.stringify and restored with JSON.parse, so non-JSON values (Date, Map,
+     * class instances) round-trip lossily and `undefined` properties are dropped.
+     * The requirement is enforced only at persist time, not by this type.
+     */
+    data?: unknown;
+}
 /** Result from input event handler */
 export type InputEventResult = {
     action: "continue";
@@ -609,6 +668,8 @@ export type InputEventResult = {
     action: "transform";
     text: string;
     images?: ImageContent[];
+    sessionEntries?: InputSessionEntry[];
+    onAccepted?: () => void;
 } | {
     action: "handled";
 };
@@ -735,10 +796,13 @@ export declare function isToolCallEventType<TName extends string, TInput extends
     input: TInput;
 };
 /** Union of all event types */
-export type ExtensionEvent = ResourcesDiscoverEvent | SessionEvent | ContextEvent | BeforeProviderRequestEvent | AfterProviderResponseEvent | BeforeAgentStartEvent | AgentStartEvent | AgentEndEvent | TurnStartEvent | TurnEndEvent | MessageStartEvent | MessageUpdateEvent | MessageEndEvent | ToolExecutionStartEvent | ToolExecutionUpdateEvent | ToolExecutionEndEvent | ModelSelectEvent | ThinkingLevelSelectEvent | UserBashEvent | InputEvent | ToolCallEvent | ToolResultEvent;
+export type ExtensionEvent = ResourcesDiscoverEvent | SessionEvent | ContextEvent | BeforeProviderCallEvent | BeforeProviderRequestEvent | ProviderRequestToolInventoryEvent | AfterProviderResponseEvent | BeforeAgentStartEvent | AgentStartEvent | AgentEndEvent | TurnStartEvent | TurnEndEvent | MessageStartEvent | MessageUpdateEvent | MessageEndEvent | ToolExecutionStartEvent | ToolExecutionUpdateEvent | ToolExecutionEndEvent | ModelSelectEvent | ThinkingLevelSelectEvent | UserBashEvent | InputEvent | ToolCallEvent | ToolResultEvent;
 export interface ContextEventResult {
     messages?: AgentMessage[];
 }
+export interface BeforeProviderCallEventResult {
+    systemPrompt?: Context["systemPrompt"];
+}
 export type BeforeProviderRequestEventResult = unknown;
 export interface ToolCallEventResult {
     /** Block tool execution. To modify arguments, mutate `event.input` in place instead. */
@@ -822,7 +886,9 @@ export interface ExtensionAPI {
     on(event: "session_before_tree", handler: ExtensionHandler<SessionBeforeTreeEvent, SessionBeforeTreeResult>): void;
     on(event: "session_tree", handler: ExtensionHandler<SessionTreeEvent>): void;
     on(event: "context", handler: ExtensionHandler<ContextEvent, ContextEventResult>): void;
+    on(event: "before_provider_call", handler: ExtensionHandler<BeforeProviderCallEvent, BeforeProviderCallEventResult>): void;
     on(event: "before_provider_request", handler: ExtensionHandler<BeforeProviderRequestEvent, BeforeProviderRequestEventResult>): void;
+    on(event: "provider_request_tool_inventory", handler: ExtensionHandler<ProviderRequestToolInventoryEvent>): void;
     on(event: "after_provider_response", handler: ExtensionHandler<AfterProviderResponseEvent>): void;
     on(event: "before_agent_start", handler: ExtensionHandler<BeforeAgentStartEvent, BeforeAgentStartEventResult>): void;
     on(event: "agent_start", handler: ExtensionHandler<AgentStartEvent>): void;
@@ -888,6 +954,28 @@ export interface ExtensionAPI {
     getAllTools(): ToolInfo[];
     /** Set the active tools by name. */
     setActiveTools(toolNames: string[]): void;
+    /**
+     * Execute a registered tool as a harness-originated call, without the model requesting it.
+     *
+     * The tool is resolved from the full tool registry (so `"harness-only"` tools that are never
+     * provider-visible can still be executed) and run through the real execution pipeline: it
+     * produces the same live `tool_execution_*`/message events, persisted session entries, and
+     * `tool_call`/`tool_result` extension hooks as a normal tool call, but emits no run/turn
+     * framing. When idle the call executes immediately; when a run is active it is queued and
+     * drained before the next intra-run LLM call.
+     *
+     * The returned promise resolves only after the resulting tool-result message has been persisted
+     * to the session (#341) — a strictly stronger guarantee than Agent-core execution alone — so a
+     * consumer that must not replace or tear down the session until the record row exists can safely
+     * `await` it. It rejects if no tool with `name` is registered, if a matching event fails to
+     * process/persist, if the session is disposed before it settles or is called after disposal, or if
+     * an explicit {@link InvokeHarnessToolOptions.toolCallId} is malformed or already pending.
+     * **Rejection means the pipeline
+     * did not complete — it does not prove the artifact is absent** (state and persistence may have
+     * partially completed), so do not blindly retry. A tool's own `execute()` error resolves normally
+     * as an `isError` result.
+     */
+    invokeHarnessTool(name: string, args: unknown, options?: InvokeHarnessToolOptions): Promise<void>;
     /** Get available slash commands in the current session. */
     getCommands(): SlashCommandInfo[];
     /** Set the current model. Returns false if no API key available. */
@@ -1028,8 +1116,10 @@ export interface ProviderModelConfig {
         cacheRead: number;
         cacheWrite: number;
     };
-    /** Maximum context window size in tokens. */
+    /** Maximum supported total context in tokens. */
     contextWindow: number;
+    maxInputTokens?: number;
+    requestLimits?: Model<Api>["requestLimits"];
     /** Maximum output tokens. */
     maxTokens: number;
     /** Custom headers for this model. */
@@ -1078,6 +1168,15 @@ export type GetCommandsHandler = () => SlashCommandInfo[];
 export type SetActiveToolsHandler = (toolNames: string[]) => void;
 export type RefreshToolsHandler = () => void;
 export type SetModelHandler = (model: Model<any>) => Promise<boolean>;
+/** Options for {@link ExtensionAPI.invokeHarnessTool}. */
+export interface InvokeHarnessToolOptions {
+    /**
+     * Explicit tool-call id — must be provider-safe (1-64 characters of `[a-zA-Z0-9_-]`); an invalid
+     * id is rejected. Defaults to a provider-safe generated id when omitted.
+     */
+    toolCallId?: string;
+}
+export type InvokeHarnessToolHandler = (name: string, args: unknown, options?: InvokeHarnessToolOptions) => Promise<void>;
 export type GetThinkingLevelHandler = () => ThinkingLevel;
 export type SetThinkingLevelHandler = (level: ThinkingLevel) => void;
 export type SetLabelHandler = (entryId: string, label: string | undefined) => void;
@@ -1120,6 +1219,7 @@ export interface ExtensionActions {
     getActiveTools: GetActiveToolsHandler;
     getAllTools: GetAllToolsHandler;
     setActiveTools: SetActiveToolsHandler;
+    invokeHarnessTool: InvokeHarnessToolHandler;
     refreshTools: RefreshToolsHandler;
     getCommands: GetCommandsHandler;
     setModel: SetModelHandler;
@@ -1132,6 +1232,10 @@ export interface ExtensionActions {
  */
 export interface ExtensionContextActions {
     getModel: () => Model<any> | undefined;
+    getScopedModels: () => ReadonlyArray<{
+        model: Model<any>;
+        thinkingLevel?: ThinkingLevel;
+    }>;
     isIdle: () => boolean;
     getSignal: () => AbortSignal | undefined;
     abort: () => void;