/**
 * @fileoverview Application composition root. Constructs all services in
 * dependency order, initializes telemetry/logger, starts transport, and
 * registers shutdown/signal handlers. Returns a ServerHandle for lifecycle
 * management.
 * @module src/core/app
 */
import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
import type { Implementation } from '@modelcontextprotocol/sdk/types.js';
import type { SupabaseClient } from '@supabase/supabase-js';
import { config } from '../config/index.js';
import { type LandingConfig, type ServerManifest } from '../core/serverManifest.js';
import type { AnyPromptDefinition } from '../mcp-server/prompts/utils/promptDefinition.js';
import type { AnyResourceDefinition } from '../mcp-server/resources/utils/resourceDefinition.js';
import { TaskManager } from '../mcp-server/tasks/core/taskManager.js';
import type { AnyToolDef } from '../mcp-server/tools/tool-registration.js';
import type { DataCanvas } from '../services/canvas/core/DataCanvas.js';
import type { ILlmProvider } from '../services/llm/core/ILlmProvider.js';
import { SpeechService } from '../services/speech/core/SpeechService.js';
import { StorageService } from '../storage/core/StorageService.js';
import type { Database } from '../storage/providers/supabase/supabase.types.js';
import { logger } from '../utils/internal/logger.js';
import { RateLimiter } from '../utils/security/rateLimiter.js';
/**
 * Options affecting the `Context` object passed to every handler.
 * Surfaced via {@link CreateAppOptions.context}.
 */
export interface ContextOptions {
    /**
     * When `true`, `ctx.sessionId` is populated in stateless HTTP mode using
     * the per-request token the SDK generates. Default `false` — `ctx.sessionId`
     * is only defined when there is a durable session (HTTP `stateful` / `auto`
     * mode). Stdio handlers always see `undefined`.
     *
     * Opt in only when downstream code is structured around `ctx.sessionId`
     * and accepts that the value changes per-request under stateless mode. For
     * generic per-request correlation, use `ctx.requestId` (always present).
     */
    exposeStatelessSessionId?: boolean;
}
/** Options for {@link createApp}. All arrays default to empty. */
export interface CreateAppOptions {
    /** Options affecting the `Context` object passed to handlers. */
    context?: ContextOptions;
    /**
     * One-line description shown in client listings and the server card.
     * When set, this takes priority over the `MCP_SERVER_DESCRIPTION` env var
     * and `package.json` `description`. Forwarded to the `McpServer` constructor
     * and to `buildServerManifest` so `initialize` and `/.well-known/mcp.json`
     * stay consistent.
     */
    description?: string;
    /**
     * SEP-2133 extensions to advertise in server capabilities.
     * Keys are extension identifiers (`vendor-prefix/extension-name`).
     */
    extensions?: Record<string, object>;
    /**
     * Server icon(s) rendered in client listings. Typed against the SDK's
     * `Implementation['icons']` — each entry carries `src` (URL), optional
     * `mimeType`, `sizes?: string[]`, and `theme?: 'light' | 'dark'`.
     *
     * @example
     * ```ts
     * icons: [{ src: 'https://example.com/icon.png', sizes: ['48x48'], mimeType: 'image/png' }]
     * ```
     */
    icons?: Implementation['icons'];
    /**
     * Server-level orientation text included on every `initialize` response.
     * Spec-compliant clients SHOULD forward this to the model as session-level
     * system context. Use for deployment-specific guidance (configured connection
     * aliases, regional notes, scope hints, available shortcuts) instead of
     * leaking that text into every tool description.
     *
     * Client adoption is uneven — clients that ignore `instructions` are no
     * worse off than they are today, so this is a strict improvement when set.
     */
    instructions?: string;
    /**
     * Landing page configuration. Applies to the HTTP transport only.
     * See {@link LandingConfig} for the full shape — all fields optional,
     * sane defaults for everything.
     */
    landing?: LandingConfig;
    /**
     * Server name — overrides `package.json` `name` and the `MCP_SERVER_NAME`
     * env var. Also seeds `OTEL_SERVICE_NAME` when that var is unset (`??=`), so
     * telemetry's `service.name` defaults to this value; an explicit
     * `OTEL_SERVICE_NAME` in the environment still wins.
     */
    name?: string;
    /** Prompt definitions. */
    prompts?: AnyPromptDefinition[];
    /** Resource definitions. */
    resources?: AnyResourceDefinition[];
    /** Runs after core services are constructed, before transport starts. */
    setup?: (core: CoreServices) => void | Promise<void>;
    /**
     * Human-readable display name shown in client listings and consent UIs.
     * Supplements `name` (which is the machine identifier). Forwarded to the
     * `McpServer` constructor's `serverInfo` and to the server manifest.
     *
     * @example `'My Server'`
     */
    title?: string;
    /** Tool definitions (legacy, new-style, or task). */
    tools?: AnyToolDef[];
    /** Server version — overrides package.json and MCP_SERVER_VERSION env var. */
    version?: string;
    /**
     * Canonical URL for the server's homepage or repository. Forwarded to the
     * `McpServer` constructor's `serverInfo` and to the server manifest so
     * `initialize` and `/.well-known/mcp.json` stay consistent.
     *
     * @example `'https://github.com/owner/my-mcp-server'`
     */
    websiteUrl?: string;
}
/** Services available in the `setup()` callback and on ServerHandle. */
export interface CoreServices {
    /**
     * Optional DataCanvas primitive (issue #97). Present when
     * `CANVAS_PROVIDER_TYPE` is set to a supported engine (`duckdb`).
     * `undefined` when canvas is disabled (`'none'`, the default) or when
     * running on Cloudflare Workers (DuckDB has no V8-isolate build).
     */
    canvas?: DataCanvas;
    config: typeof config;
    llmProvider?: ILlmProvider;
    logger: typeof logger;
    rateLimiter: RateLimiter;
    speechService?: SpeechService;
    storage: StorageService;
    supabase?: SupabaseClient<Database>;
}
/** Handle returned by {@link createApp} for controlling the server lifecycle. */
export interface ServerHandle {
    /** Read-only access to core services for integration testing or embedding. */
    readonly services: CoreServices;
    /** Initiates graceful shutdown (stops transport, flushes OTEL, closes logger). */
    shutdown(signal?: string): Promise<void>;
}
/** @internal Result of composeServices — used by createApp and createWorkerHandler. */
export interface ComposedApp {
    coreServices: CoreServices;
    createServer: () => Promise<McpServer>;
    /**
     * Server manifest — the single source of truth for the `/mcp` status JSON,
     * the SEP-1649 Server Card at `/.well-known/mcp.json`, and the HTML landing
     * page at `/`.
     */
    manifest: ServerManifest;
    taskManager: TaskManager;
}
/**
 * Constructs core services, registries, and server factory.
 * Shared by createApp() (Node) and createWorkerHandler() (Workers).
 * Does NOT start transport, register signal handlers, or init OTEL/logger.
 * @internal
 */
export declare function composeServices(options?: CreateAppOptions): Promise<ComposedApp>;
/**
 * Composes the application, initializes all services, starts transport,
 * and registers signal/error handlers. This is the complete entry point
 * for a Node.js MCP server process.
 *
 * @param options - Definition arrays, name/version overrides, and setup callback.
 *                  All arrays default to empty.
 * @returns A {@link ServerHandle} with `shutdown()` and `services`.
 * @throws {McpError} If config parsing or service construction fails.
 */
export declare function createApp(options?: CreateAppOptions): Promise<ServerHandle>;
export { z } from 'zod';
export type { Context, ContextLogger, ContextProgress, ContextState } from '../core/context.js';
export type { PromptDefinition } from '../mcp-server/prompts/utils/promptDefinition.js';
export { prompt } from '../mcp-server/prompts/utils/promptDefinition.js';
export type { AnyResourceDefinition, ResourceDefinition, } from '../mcp-server/resources/utils/resourceDefinition.js';
export { resource } from '../mcp-server/resources/utils/resourceDefinition.js';
export type { AnyToolDefinition, DisabledMetadata, ToolAnnotations, ToolDefinition, } from '../mcp-server/tools/utils/toolDefinition.js';
export { disabledTool, tool, } from '../mcp-server/tools/utils/toolDefinition.js';
//# sourceMappingURL=app.d.ts.map