@forge-sdk/core

import * as api from '@forge-sdk/core';

export class BrewBuilder {
  constructor(id: string, version: string);
  addNode(nodeId: string, kind: BrewNodeKind): this;
  addEdge(from: string, to: string, edgeKind: BrewEdgeKind): this;
  setEntry(nodeId: string): this;
  setExit(nodeId: string): this;
  withTopology(topology: ModelTopology): this;
  withMetadata(nodeId: string, key: string, value: string): this;
  build(): Brew;
}

export function topologicalSort(
  nodes: ReadonlyMap<NodeId, BrewNode>,
  edges: readonly BrewEdge[],
): NodeId[];

export interface BrewEnvironment {
  /** Registered model providers, keyed by their `namespace:model` string. */
  readonly providers: ReadonlyMap<string, string>;
  /** Registered tool names available in this environment. */
  readonly tools: ReadonlySet<string>;
  /** Connected MCP server identifiers (URIs or aliases). */
  readonly mcpServers: ReadonlySet<string>;
  /** Web capabilities available in this environment. */
  readonly webCapabilities: ReadonlySet<string>;
}

export const BrewResolutionErrorKind /* type inferred in source */;

export type BrewResolutionErrorKind =
  (typeof BrewResolutionErrorKind)[keyof typeof BrewResolutionErrorKind];

export interface BrewResolutionError {
  /** The node that failed resolution. */
  readonly nodeId: NodeId;
  /** What went wrong. */
  readonly errorKind: BrewResolutionErrorKind;
}

export interface ResolvedBrewPlan {
  /** Deterministic plan identifier (hash of brew_id + version + env hash). */
  readonly planId: string;
  /** The original brew identifier. */
  readonly brewId: BrewId;
  /** The original brew version. */
  readonly brewVersion: BrewVersion;
  /** ISO 8601 timestamp of when resolution was performed. */
  readonly resolvedAt: string;
  /** The resolved node execution order (topological sort). */
  readonly executionOrder: readonly NodeId[];
  /** The edges from the original brew. */
  readonly edges: readonly BrewEdge[];
  /** The entry nodes. */
  readonly entryNodes: readonly NodeId[];
  /** The exit nodes. */
  readonly exitNodes: readonly NodeId[];
}

export function resolve(
  brew: Brew,
  env: BrewEnvironment,
): ResolvedBrewPlan;

export type BrewId = string;

export type NodeId = string;

export type BrewVersion = string;

export type JoinMode =
  | { readonly type: 'await_all' }
  | { readonly type: 'first_success' }
  | { readonly type: 'first_n'; readonly n: number };

export function joinAwaitAll(): JoinMode;

export function joinFirstSuccess(): JoinMode;

export function joinFirstN(n: number): JoinMode;

export type BrewNodeKind =
  | {
      readonly type: 'agent_step';
      readonly provider: string;
      readonly systemPrompt?: string;
      readonly maxSteps: number;
    }
  | {
      readonly type: 'tool_invocation';
      readonly toolId: string;
      readonly tier: ToolTier;
    }
  | {
      readonly type: 'mcp_call';
      readonly serverId: string;
      readonly toolName: string;
    }
  | {
      readonly type: 'web_operation';
      readonly operation: string;
    }
  | {
      readonly type: 'conditional_branch';
      readonly conditionExpr: string;
      readonly trueTarget: NodeId;
      readonly falseTarget: NodeId;
    }
  | {
      readonly type: 'parallel_fork';
      readonly branches: readonly NodeId[];
      readonly joinMode: JoinMode;
    }
  | {
      readonly type: 'sub_brew_ref';
      readonly brewId: BrewId;
    }
  | {
      readonly type: 'human_checkpoint';
      readonly prompt: string;
      readonly timeoutMs?: number;
    };

export interface BrewNode {
  /** Stable identifier within this brew. */
  readonly id: NodeId;
  /** The node's execution semantics. */
  readonly kind: BrewNodeKind;
  /** Arbitrary key-value metadata for tooling and visualization. */
  readonly metadata: Readonly<Record<string, string>>;
}

export const BrewEdgeKind /* type inferred in source */;

export type BrewEdgeKind = (typeof BrewEdgeKind)[keyof typeof BrewEdgeKind];

export interface BrewEdge {
  /** Source node. */
  readonly from: NodeId;
  /** Target node. */
  readonly to: NodeId;
  /** Edge semantics. */
  readonly kind: BrewEdgeKind;
}

export interface Brew {
  /** Unique identifier for this brew definition. */
  readonly id: BrewId;
  /** Semantic version of this brew definition. */
  readonly version: BrewVersion;
  /** The graph's nodes, keyed by stable node ID. */
  readonly nodes: ReadonlyMap<NodeId, BrewNode>;
  /** The graph's edges, sorted by (from, to, kind) for determinism. */
  readonly edges: readonly BrewEdge[];
  /** Designated entry nodes. Execution begins at these nodes. */
  readonly entryNodes: readonly NodeId[];
  /** Designated exit nodes. Execution terminates when all exit nodes complete. */
  readonly exitNodes: readonly NodeId[];
  /** Optional model topology for this brew. */
  readonly topology?: ModelTopology;
}

export interface GenerateOptions {
  /** Sampling temperature (0.0 = deterministic, 2.0 = maximum randomness). */
  readonly temperature?: number;
  /** Maximum tokens to generate. */
  readonly maxTokens?: number;
  /** Top-p (nucleus) sampling threshold. */
  readonly topP?: number;
  /** Stop sequences -- generation stops when any of these are produced. */
  readonly stopSequences?: readonly string[];
  /** Frequency penalty (-2.0 to 2.0). */
  readonly frequencyPenalty?: number;
  /** Presence penalty (-2.0 to 2.0). */
  readonly presencePenalty?: number;
  /** Seed for deterministic generation (if supported by provider). */
  readonly seed?: number;
  /** JSON schema for structured output enforcement. */
  readonly outputSchema?: JsonSchema;
}

export function defaultGenerateOptions(): GenerateOptions;

export interface EmbedOptions {
  /** The embedding model to use (if different from default). */
  readonly model?: string;
  /** Dimensionality of the output embeddings (if configurable). */
  readonly dimensions?: number;
}

export const ForgeErrorCode /* type inferred in source */;

export type ForgeErrorCode = (typeof ForgeErrorCode)[keyof typeof ForgeErrorCode];

export class ForgeError extends Error {
  public readonly code: ForgeErrorCode;
  constructor(code: ForgeErrorCode, message: string);
  static providerNotFound(providerRef: string): ForgeError;
  static invalidProviderRef(input: string): ForgeError;
  static schemaValidation(path: string, reason: string): ForgeError;
  static invalidLifecycleTransition(from: string, to: string, reason: string): ForgeError;
  static toolInvocationDenied(
    toolName: string,
    agentDid: string,
    requiredCapability: string,
    actId: string
  ): ForgeError;
  static toolExecutionFailed(toolName: string, reason: string): ForgeError;
  static missingConfig(field: string, hint: string): ForgeError;
  static stopConditionReached(reason: string, steps: number, tokens: number): ForgeError;
  static unsupportedOperation(model: string, operation: string): ForgeError;
  static providerUnavailable(providerRef: string, reason: string): ForgeError;
  static providerAuthenticationFailed(providerRef: string, reason: string): ForgeError;
  static capabilityUnsupported(providerRef: string, capability: string): ForgeError;
  static providerNegotiationFailed(providerRef: string, reason: string): ForgeError;
  static providerSessionExpired(providerRef: string, sessionId: string): ForgeError;
  static providerInterruptUnsupported(providerRef: string): ForgeError;
  static providerResumeUnsupported(providerRef: string): ForgeError;
  static internal(message: string): ForgeError;
}

export {
  Role,
  type TextPart,
  type ImagePart,
  type ToolCallPart,
  type ToolResultPart,
  type MessagePart,
  type ModelMessage,
  textPart,
  imagePart,
  toolCallPart,
  toolResultPart,
  isToolCall,
  isToolResult,
  createMessage,
  createTextMessage,
  getToolCalls,
  getTextContent,
} from './message.js';

export { type LanguageModel } from './model.js';

export {
  FinishReason,
  type Usage,
  type GenerateResult,
  type TextDeltaChunk,
  type ToolCallDeltaChunk,
  type DoneChunk,
  type StreamChunk,
  zeroUsage,
  addUsage,
  isComplete,
  isToolCallFinish,
  textDeltaChunk,
  doneChunk,
  isTextDelta,
  isDone,
  chunkText,
} from './output.js';

export {
  ToolTier,
  type ToolDefinition,
  type ToolCall,
  type ToolResult,
  type ToolApproval,
  ToolApprovalDecision,
  ToolDefinitionBuilder,
  buildToolDefinition,
  requiresAuthorization,
  approve,
  deny,
  modify,
} from './tool.js';

export {
  type GenerateOptions,
  type EmbedOptions,
  defaultGenerateOptions,
} from './config.js';

export { JsonSchema, SchemaType } from './schema.js';

export { ForgeError, ForgeErrorCode } from './error.js';

export {
  ForgeSpan,
  ForgeEvent,
  SpanStatus,
  type SpanStatusType,
  type SpanAttribute,
  type TelemetryEmitter,
  NoopEmitter,
  RecordingEmitter,
} from './telemetry.js';

export {
  type AgentDid,
  Timestamp,
  createAgentDid,
  trustedAgentDid,
} from './types.js';

export {
  ProviderRef,
  ProviderRegistry,
  type ProviderMetadata,
  RuntimeCapability,
  ProviderRuntimeCapabilities,
  type ProviderNegotiationRequest,
  type ProviderNegotiationResult,
  ProviderSessionState,
  type ProviderUsageSummary,
  type ProviderSessionEvent,
} from './provider.js';

export {
  ProviderFamily,
  AuthStrategy,
  type ProviderPreset,
  type ProviderEnvironment,
  type ProviderExecutionRequest,
  type ProviderInstallOptions,
  approvedCodingProviderPresets,
  approvedDirectProviderPresets,
  approvedGatewayProviderPresets,
  registerOfficialCodingProviders,
  registerDefaultCoreDirectProviders,
  registerOpenAiModel,
  registerAnthropicModel,
  registerGoogleModel,
  registerXaiModel,
  registerDeepSeekModel,
  registerMistralModel,
  registerCohereModel,
  registerGroqModel,
  registerMoonshotModel,
  registerZaiModel,
  registerMiniMaxModel,
  registerOpenRouterModel,
  registerBedrockModel,
  registerVertexAiModel,
  registerMicrosoftFoundryModel,
  registerFoundryModel,
  unavailableProviderResult,
} from './provider-families.js';

export {
  DEFAULT_ROLE,
  CostPreference,
  LatencyPreference,
  type ModelSlot,
  ModelTopology,
  TopologyBuilder,
} from './topology.js';

export {
  TaskMode,
  taskModeAsRoleName,
  ExecutionTopology,
  type RoutingContext,
  defaultRoutingContext,
  type ModelCapabilities,
  defaultModelCapabilities,
  type ResolvedRoute,
  type ModelRouter,
  DefaultModelRouter,
} from './routing.js';

export {
  type BrewId,
  type NodeId,
  type BrewVersion,
  type JoinMode,
  joinAwaitAll,
  joinFirstSuccess,
  joinFirstN,
  type BrewNodeKind,
  type BrewNode,
  BrewEdgeKind,
  type BrewEdge,
  type Brew,
} from './brew.js';

export { BrewBuilder, topologicalSort } from './brew-builder.js';

export {
  type BrewEnvironment,
  BrewResolutionErrorKind,
  type BrewResolutionError,
  type ResolvedBrewPlan,
  resolve,
} from './brew-resolver.js';

export const Role /* type inferred in source */;

export type Role = (typeof Role)[keyof typeof Role];

export interface TextPart {
  readonly type: 'text';
  /** The text content. */
  readonly text: string;
}

export interface ImagePart {
  readonly type: 'image';
  /** Base64-encoded image data, or a URL. */
  readonly data: string;
  /** MIME type (e.g., "image/png"). */
  readonly mediaType: string;
}

export interface ToolCallPart {
  readonly type: 'tool_call';
  /** Unique identifier for this tool call. */
  readonly id: string;
  /** The tool name. */
  readonly name: string;
  /** JSON arguments for the tool. */
  readonly arguments: unknown;
}

export interface ToolResultPart {
  readonly type: 'tool_result';
  /** The tool call ID this result corresponds to. */
  readonly toolCallId: string;
  /** The tool name. */
  readonly name: string;
  /** The result content (typically stringified). */
  readonly content: string;
  /** Whether the tool execution resulted in an error. */
  readonly isError: boolean;
}

export type MessagePart = TextPart | ImagePart | ToolCallPart | ToolResultPart;

export function textPart(text: string): TextPart;

export function imagePart(data: string, mediaType: string): ImagePart;

export function toolCallPart(id: string, name: string, args: unknown): ToolCallPart;

export function toolResultPart(
  toolCallId: string,
  name: string,
  content: string,
  isError: boolean
): ToolResultPart;

export function isToolCall(part: MessagePart): part is ToolCallPart;

export function isToolResult(part: MessagePart): part is ToolResultPart;

export interface ModelMessage {
  /** The message participant role. */
  readonly role: Role;
  /** One or more content parts. */
  readonly parts: readonly MessagePart[];
}

export function createMessage(role: Role, parts: MessagePart[]): ModelMessage;

export function createTextMessage(role: Role, text: string): ModelMessage;

export function getToolCalls(message: ModelMessage): readonly ToolCallPart[];

export function getTextContent(message: ModelMessage): string;

export interface LanguageModel {
  /** The model identifier (e.g., "gpt-4o", "claude-sonnet-4-5-20250929"). */
  readonly modelId: string;

  /** The provider namespace (e.g., "openai", "anthropic"). */
  readonly provider: string;

  /** Whether this model supports tool calling. */
  readonly supportsToolCalling: boolean;

  /** Whether this model supports structured output (JSON mode). */
  readonly supportsStructuredOutput: boolean;

  /** Whether this model supports image input. */
  readonly supportsImageInput: boolean;

  /** Whether this model supports streaming. */
  readonly supportsStreaming: boolean;

  /**
   * Generates a complete response from the model.
   *
   * @param messages - The conversation history.
   * @param tools - Available tool definitions for this inference call.
   * @param options - Generation options (temperature, max_tokens, etc.).
   * @returns A GenerateResult containing the model's response, usage statistics,
   *   and finish reason.
   * @throws {ForgeError} If the provider call fails, times out, or returns
   *   an invalid response.
   */
  generate(
    messages: readonly ModelMessage[],
    tools: readonly ToolDefinition[],
    options: GenerateOptions
  ): Promise<GenerateResult>;

  /**
   * Streams a response from the model as chunks.
   *
   * @param messages - The conversation history.
   * @param tools - Available tool definitions for this inference call.
   * @param options - Generation options.
   * @returns An async generator of StreamChunk values. Callers should process
   *   chunks as they arrive for real-time output.
   * @throws {ForgeError} If the provider call fails.
   */
  stream(
    messages: readonly ModelMessage[],
    tools: readonly ToolDefinition[],
    options: GenerateOptions
  ): AsyncGenerator<StreamChunk>;
}

export enum ProviderFamily {
  CodingProduct = 'coding_product',
  DirectModel = 'direct_model',
  Gateway = 'gateway',
}

export enum AuthStrategy {
  ApiKey = 'api_key',
  AccessToken = 'access_token',
  BrowserAccountLogin = 'browser_account_login',
  CloudCredentials = 'cloud_credentials',
}

export interface ProviderPreset {
  readonly namespace: string;
  readonly family: ProviderFamily;
  readonly authStrategy: AuthStrategy;
}

export function approvedCodingProviderPresets(): readonly ProviderPreset[];

export function approvedDirectProviderPresets(): readonly ProviderPreset[];

export function approvedGatewayProviderPresets(): readonly ProviderPreset[];

export function registerOfficialCodingProviders(registry: ProviderRegistry): void;

export function registerDefaultCoreDirectProviders(registry: ProviderRegistry): readonly string[];

export function registerOpenAiModel(registry: ProviderRegistry, modelId: string): string;

export function registerAnthropicModel(registry: ProviderRegistry, modelId: string): string;

export function registerGoogleModel(registry: ProviderRegistry, modelId: string): string;

export function registerXAiModel(registry: ProviderRegistry, modelId: string): string;

export function registerDeepseekModel(registry: ProviderRegistry, modelId: string): string;

export function registerMistralModel(registry: ProviderRegistry, modelId: string): string;

export function registerCohereModel(registry: ProviderRegistry, modelId: string): string;

export function registerGroqModel(registry: ProviderRegistry, modelId: string): string;

export function registerMoonshotModel(registry: ProviderRegistry, modelId: string): string;

export function registerZaiModel(registry: ProviderRegistry, modelId: string): string;

export function registerMiniMaxModel(registry: ProviderRegistry, modelId: string): string;

export function registerOpenRouterModel(registry: ProviderRegistry, modelId: string): string;

export function registerBedrockModel(registry: ProviderRegistry, modelId: string): string;

export function registerVertexAiModel(registry: ProviderRegistry, modelId: string): string;

export function registerMicrosoftFoundryModel(
  registry: ProviderRegistry,
  modelId: string
): string;

export function registerFoundryModel(registry: ProviderRegistry, modelId: string): string;

export const FinishReason /* type inferred in source */;

export type FinishReason = (typeof FinishReason)[keyof typeof FinishReason];

export function isComplete(reason: FinishReason): boolean;

export function isToolCallFinish(reason: FinishReason): boolean;

export interface Usage {
  /** Tokens consumed by the input prompt. */
  readonly promptTokens: number;
  /** Tokens generated in the response. */
  readonly completionTokens: number;
  /** Total tokens (prompt + completion). */
  readonly totalTokens: number;
}

export function zeroUsage(): Usage;

export function addUsage(a: Usage, b: Usage): Usage;

export interface GenerateResult {
  /** The model's response message. */
  readonly message: ModelMessage;
  /** Why generation stopped. */
  readonly finishReason: FinishReason;
  /** Token usage statistics. */
  readonly usage: Usage;
}

export interface TextDeltaChunk {
  readonly type: 'text_delta';
  /** The text fragment. */
  readonly text: string;
}

export interface ToolCallDeltaChunk {
  readonly type: 'tool_call_delta';
  /** The tool call index (for parallel tool calls). */
  readonly index: number;
  /** The tool call ID (may be empty until fully received). */
  readonly id: string;
  /** The tool name (may be empty until fully received). */
  readonly name: string;
  /** Partial JSON arguments. */
  readonly argumentsDelta: string;
}

export interface DoneChunk {
  readonly type: 'done';
  /** Why generation stopped. */
  readonly finishReason: FinishReason;
  /** Final usage statistics. */
  readonly usage: Usage;
}

export type StreamChunk = TextDeltaChunk | ToolCallDeltaChunk | DoneChunk;

export function textDeltaChunk(text: string): TextDeltaChunk;

export function doneChunk(finishReason: FinishReason, usage: Usage): DoneChunk;

export function isTextDelta(chunk: StreamChunk): chunk is TextDeltaChunk;

export function isDone(chunk: StreamChunk): chunk is DoneChunk;

export function chunkText(chunk: StreamChunk): string | undefined;

export const ProviderFamily /* type inferred in source */;

export type ProviderFamily = (typeof ProviderFamily)[keyof typeof ProviderFamily];

export const AuthStrategy /* type inferred in source */;

export type AuthStrategy = (typeof AuthStrategy)[keyof typeof AuthStrategy];

export interface ProviderPreset {
  readonly namespace: string;
  readonly family: ProviderFamily;
  readonly authStrategy: AuthStrategy;
}

export type ProviderEnvironment = Readonly<Record<string, string | undefined>>;

export interface ProviderExecutionRequest {
  readonly providerRef: string;
  readonly namespace: string;
  readonly modelId: string;
  readonly family: ProviderFamily;
  readonly authStrategy: AuthStrategy;
  readonly credential: string;
  readonly baseUrl?: string;
  readonly messages: readonly ModelMessage[];
  readonly tools: readonly ToolDefinition[];
  readonly options: GenerateOptions;
}

export interface ProviderInstallOptions {
  readonly env?: ProviderEnvironment;
  readonly generate?: (
    request: ProviderExecutionRequest
  ) => Promise<GenerateResult>;
  readonly stream?: (
    request: ProviderExecutionRequest
  ) => AsyncGenerator<StreamChunk>;
}

export function approvedCodingProviderPresets(): ProviderPreset[];

export function approvedDirectProviderPresets(): ProviderPreset[];

export function approvedGatewayProviderPresets(): ProviderPreset[];

export function registerOfficialCodingProviders(
  registry: ProviderRegistry,
  options: ProviderInstallOptions = {}
): void;

export function registerDefaultCoreDirectProviders(
  registry: ProviderRegistry,
  options: ProviderInstallOptions = {}
): string[];

export function registerOpenAiModel(
  registry: ProviderRegistry,
  modelId: string,
  options: ProviderInstallOptions = {}
): string;

export function registerAnthropicModel(
  registry: ProviderRegistry,
  modelId: string,
  options: ProviderInstallOptions = {}
): string;

export function registerGoogleModel(
  registry: ProviderRegistry,
  modelId: string,
  options: ProviderInstallOptions = {}
): string;

export function registerXaiModel(
  registry: ProviderRegistry,
  modelId: string,
  options: ProviderInstallOptions = {}
): string;

export function registerDeepSeekModel(
  registry: ProviderRegistry,
  modelId: string,
  options: ProviderInstallOptions = {}
): string;

export function registerMistralModel(
  registry: ProviderRegistry,
  modelId: string,
  options: ProviderInstallOptions = {}
): string;

export function registerCohereModel(
  registry: ProviderRegistry,
  modelId: string,
  options: ProviderInstallOptions = {}
): string;

export function registerGroqModel(
  registry: ProviderRegistry,
  modelId: string,
  options: ProviderInstallOptions = {}
): string;

export function registerMoonshotModel(
  registry: ProviderRegistry,
  modelId: string,
  options: ProviderInstallOptions = {}
): string;

export function registerZaiModel(
  registry: ProviderRegistry,
  modelId: string,
  options: ProviderInstallOptions = {}
): string;

export function registerMiniMaxModel(
  registry: ProviderRegistry,
  modelId: string,
  options: ProviderInstallOptions = {}
): string;

export function registerOpenRouterModel(
  registry: ProviderRegistry,
  modelId: string,
  options: ProviderInstallOptions = {}
): string;

export function registerBedrockModel(
  registry: ProviderRegistry,
  modelId: string,
  options: ProviderInstallOptions = {}
): string;

export function registerVertexAiModel(
  registry: ProviderRegistry,
  modelId: string,
  options: ProviderInstallOptions = {}
): string;

export function registerMicrosoftFoundryModel(
  registry: ProviderRegistry,
  modelId: string,
  options: ProviderInstallOptions = {}
): string;

export function registerFoundryModel(
  registry: ProviderRegistry,
  modelId: string,
  options: ProviderInstallOptions = {}
): string;

export function unavailableProviderResult(providerRef: string): GenerateResult;

export class ProviderRef {
  readonly namespace: string;
  readonly model: string;
  readonly full: string;
  static parse(input: string): ProviderRef;
  toString(): string;
  toJSON(): { namespace: string; model: string; full: string };
}

export interface ProviderMetadata {
  /** Human-readable name. */
  readonly name: string;
  /** Provider namespace (e.g., "openai"). */
  readonly namespace: string;
  /** Whether the provider supports tool calling. */
  readonly supportsToolCalling: boolean;
  /** Whether the provider supports structured output. */
  readonly supportsStructuredOutput: boolean;
  /** Whether the provider supports streaming. */
  readonly supportsStreaming: boolean;
  /** Whether the provider supports image input. */
  readonly supportsImageInput: boolean;
  /** Provider-session runtime capabilities for coding-style integrations. */
  readonly runtimeCapabilities: ProviderRuntimeCapabilities;
}

export enum RuntimeCapability {
  ToolCalls = 'tool_calls',
  DelegatedAgents = 'delegated_agents',
  TerminalSession = 'terminal_session',
  StructuredPatch = 'structured_patch',
  Attachments = 'attachments',
  Interrupts = 'interrupts',
  ResumeSession = 'resume_session',
  ApprovalCheckpoints = 'approval_checkpoints',
  UsageStreaming = 'usage_streaming',
  TranscriptExport = 'transcript_export',
}

export class ProviderRuntimeCapabilities {
  readonly baselineContract: boolean;
  readonly capabilities: readonly RuntimeCapability[];
  constructor(
    baselineContract = false,
    capabilities: readonly RuntimeCapability[] = []
  );
  static baseline(): ProviderRuntimeCapabilities;
  withCapability(capability: RuntimeCapability): ProviderRuntimeCapabilities;
  supports(capability: RuntimeCapability): boolean;
}

export interface ProviderNegotiationRequest {
  readonly providerRef: string;
  readonly requireBaselineContract: boolean;
  readonly requiredCapabilities: readonly RuntimeCapability[];
}

export interface ProviderNegotiationResult {
  readonly providerRef: string;
  readonly baselineContract: boolean;
  readonly negotiatedCapabilities: readonly RuntimeCapability[];
}

export enum ProviderSessionState {
  Created = 'created',
  Ready = 'ready',
  Running = 'running',
  Interrupted = 'interrupted',
  Completed = 'completed',
  Cancelled = 'cancelled',
  Failed = 'failed',
  Expired = 'expired',
  Closed = 'closed',
}

export interface ProviderUsageSummary {
  readonly inputTokens: number;
  readonly outputTokens: number;
  readonly totalTokens: number;
}

export interface ProviderSessionEvent {
  readonly sessionId: string;
  readonly state: ProviderSessionState;
  readonly message?: string;
  readonly usage?: ProviderUsageSummary;
}

export class ProviderRegistry {
  register(providerRef: string, model: LanguageModel): void;
  registerWithRuntime(
    providerRef: string,
    model: LanguageModel,
    runtimeCapabilities: ProviderRuntimeCapabilities
  ): void;
  get(providerRef: string): LanguageModel | undefined;
  require(providerRef: string): LanguageModel;
  metadata(providerRef: string): ProviderMetadata | undefined;
  negotiate(request: ProviderNegotiationRequest): ProviderNegotiationResult;
  list(): string[];
  get size(): number;
  get isEmpty(): boolean;
}

export const TaskMode /* type inferred in source */;

export type TaskMode = (typeof TaskMode)[keyof typeof TaskMode];

export function taskModeAsRoleName(mode: TaskMode): string;

export const ExecutionTopology /* type inferred in source */;

export type ExecutionTopology = (typeof ExecutionTopology)[keyof typeof ExecutionTopology];

export interface RoutingContext {
  /** The domain classification for this call (e.g., "code", "math"). */
  readonly domain?: string;
  /** The task mode for this call. */
  readonly taskMode?: TaskMode;
  /** The execution topology for this call. */
  readonly executionTopology?: ExecutionTopology;
  /** Tool capabilities required for the model selected by this route. */
  readonly toolRequirements?: readonly string[];
  /** Explicit role override. When set, the router returns that slot directly. */
  readonly roleOverride?: string;
}

export function defaultRoutingContext(): RoutingContext;

export interface ModelCapabilities {
  readonly textGeneration: boolean;
  readonly toolCalling: boolean;
}

export function defaultModelCapabilities(): ModelCapabilities;

export interface ResolvedRoute {
  /** The role name of the selected slot. */
  readonly slotRole: string;
  /** The specific `ProviderRef` to use (primary or one of the fallbacks). */
  readonly provider: ProviderRef;
  /** The model capabilities of the selected provider. */
  readonly modelCapabilities: ModelCapabilities;
  /** Whether a fallback model was selected instead of the primary. */
  readonly fallbackUsed: boolean;
}

export interface ModelRouter {
  /** Returns the name of this routing strategy (for telemetry and debugging). */
  name(): string;

  /**
   * Selects a slot from the topology.
   *
   * @param context - The routing context describing the current task.
   * @param topology - The model topology to select from.
   * @returns A `ResolvedRoute` identifying the selected slot and provider.
   * @throws {ForgeError} If routing fails.
   */
  route(context: RoutingContext, topology: ModelTopology): ResolvedRoute;
}

export class DefaultModelRouter implements ModelRouter {
  name(): string;
  route(context: RoutingContext, topology: ModelTopology): ResolvedRoute;
}

export const SchemaType /* type inferred in source */;

export type SchemaType = (typeof SchemaType)[keyof typeof SchemaType];

export class JsonSchema {
  readonly type: SchemaType;
  descriptionText?: string;
  propertiesMap?: Map<string, JsonSchema>;
  requiredFields?: string[];
  additionalPropertiesAllowed?: boolean;
  itemsSchema?: JsonSchema;
  enumValuesList?: unknown[];
  minimumValue?: number;
  maximumValue?: number;
  minLengthValue?: number;
  maxLengthValue?: number;
  static string(): JsonSchema;
  static number(): JsonSchema;
  static integer(): JsonSchema;
  static boolean(): JsonSchema;
  static array(): JsonSchema;
  static object(): JsonSchema;
  static null(): JsonSchema;
  description(desc: string): this;
  property(name: string, schema: JsonSchema): this;
  required(name: string): this;
  items(schema: JsonSchema): this;
  enumValues(values: unknown[]): this;
  minimum(min: number): this;
  maximum(max: number): this;
  minLength(len: number): this;
  maxLength(len: number): this;
  additionalProperties(allowed: boolean): this;
  validate(value: unknown): void;
  toJSON(): Record<string, unknown>;
}

export const SpanStatus /* type inferred in source */;

export type SpanStatusType = (typeof SpanStatus)[keyof typeof SpanStatus];

export type SpanAttribute = string | number | boolean;

export class ForgeSpan {
  readonly name: string;
  readonly startTime: Timestamp;
  endTime: Timestamp | null;
  readonly attributes: Map<string, SpanAttribute>;
  status: SpanStatusType;
  statusMessage: string | null;
  parentId: string | null;
  readonly spanId: string;
  constructor(name: string);
  setAttribute(key: string, value: SpanAttribute): void;
  end(): void;
  endWithError(message: string): void;
  withParent(parentId: string): this;
}

export class ForgeEvent {
  readonly name: string;
  readonly timestamp: Timestamp;
  readonly attributes: Map<string, SpanAttribute>;
  constructor(name: string);
  setAttribute(key: string, value: SpanAttribute): void;
}

export interface TelemetryEmitter {
  /** Emits a completed span. */
  emitSpan(span: ForgeSpan): void;
  /** Emits an event. */
  emitEvent(event: ForgeEvent): void;
}

export class NoopEmitter implements TelemetryEmitter {
  emitSpan(_span: ForgeSpan): void;
  emitEvent(_event: ForgeEvent): void;
}

export class RecordingEmitter implements TelemetryEmitter {
  readonly spans: ForgeSpan[];
  readonly events: ForgeEvent[];
  emitSpan(span: ForgeSpan): void;
  emitEvent(event: ForgeEvent): void;
}

export const ToolTier /* type inferred in source */;

export type ToolTier = (typeof ToolTier)[keyof typeof ToolTier];

export function requiresAuthorization(tier: ToolTier): boolean;

export interface ToolDefinition {
  /** Unique tool name. */
  readonly name: string;
  /** Human-readable description shown to the model. */
  readonly description: string;
  /** JSON Schema defining the tool's parameters. */
  readonly parameters: JsonSchema;
  /** Tier classification (Platform/External/Embedded). */
  readonly tier: ToolTier;
}

export function buildToolDefinition(name: string): ToolDefinitionBuilder;

export class ToolDefinitionBuilder {
  constructor(name: string);
  description(desc: string): this;
  parameters(schema: JsonSchema): this;
  tier(tier: ToolTier): this;
  build(): ToolDefinition;
}

export interface ToolCall {
  /** Unique identifier for this call (used to match with results). */
  readonly id: string;
  /** The tool name being invoked. */
  readonly name: string;
  /** JSON arguments for the tool. */
  readonly arguments: unknown;
}

export interface ToolResult {
  /** The tool call ID this result corresponds to. */
  readonly toolCallId: string;
  /** The tool name. */
  readonly name: string;
  /** The result content (stringified). */
  readonly content: string;
  /** Whether the tool execution resulted in an error. */
  readonly isError: boolean;
}

export const ToolApprovalDecision /* type inferred in source */;

export type ToolApprovalDecision =
  (typeof ToolApprovalDecision)[keyof typeof ToolApprovalDecision];

export type ToolApproval =
  | { readonly decision: 'approve' }
  | { readonly decision: 'deny'; readonly reason: string }
  | { readonly decision: 'modify'; readonly arguments: unknown };

export function approve(): ToolApproval;

export function deny(reason: string): ToolApproval;

export function modify(args: unknown): ToolApproval;

export const DEFAULT_ROLE /* type inferred in source */;

export const CostPreference /* type inferred in source */;

export type CostPreference = (typeof CostPreference)[keyof typeof CostPreference];

export const LatencyPreference /* type inferred in source */;

export type LatencyPreference = (typeof LatencyPreference)[keyof typeof LatencyPreference];

export interface ModelSlot {
  /** The role name for this slot (e.g., "planner", "coder", "default"). */
  readonly role: string;
  /** Primary model for this slot. */
  readonly primary: ProviderRef;
  /** Ordered fallback models. Tried in sequence when the primary is unavailable. */
  readonly fallbacks: readonly ProviderRef[];
  /** Runtime capabilities required for this slot. */
  readonly requiredCapabilities: readonly RuntimeCapability[];
  /** Optional cost preference for the router. */
  readonly costPreference?: CostPreference;
  /** Optional latency preference for the router. */
  readonly latencyPreference?: LatencyPreference;
  /**
   * Optional Arsenal scope narrowing applied when this slot is selected.
   * If set, the agent's ACT is intersected with these scopes before
   * the model call. The intersection can only narrow, never widen.
   */
  readonly arsenalScopeNarrowing?: readonly string[];
}

export class ModelTopology {
  constructor(
    name: string,
    slots: Map<string, ModelSlot>,
    defaultRole: string,
  );
  static single(providerRef: ProviderRef): ModelTopology;
  static builder(): TopologyBuilder;
  name(): string;
  defaultRole(): string;
  defaultSlot(): ModelSlot;
  slotForRole(role: string): ModelSlot;
  slots(): ReadonlyMap<string, ModelSlot>;
  allProviderRefs(): readonly ProviderRef[];
  hasRole(role: string): boolean;
  slotCount(): number;
  toJSON(): Record<string, unknown>;
}

export class TopologyBuilder {
  name(name: string): this;
  slot(role: string, primary: ProviderRef): this;
  withFallback(role: string, fallback: ProviderRef): this;
  withRequiredCapability(role: string, cap: RuntimeCapability): this;
  withCostPreference(role: string, pref: CostPreference): this;
  withLatencyPreference(role: string, pref: LatencyPreference): this;
  withScopeNarrowing(role: string, scopes: string[]): this;
  build(): ModelTopology;
}

export type AgentDid = string & { readonly __brand: 'AgentDid' };

export function createAgentDid(did: string): AgentDid | null;

export function trustedAgentDid(did: string): AgentDid;

export class Timestamp {
  static now(): Timestamp;
  static fromISO(s: string): Timestamp | null;
  static fromDate(date: Date): Timestamp;
  toISO(): string;
  toDate(): Date;
  toEpochMs(): number;
  toString(): string;
  toJSON(): string;
  isAtOrAfter(other: Timestamp): boolean;
}