@monkey-mini-app/host 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,782 @@
+import { Hono } from 'hono';
+
+type AgentCwdType = "app" | "process" | "temp" | "custom";
+type AgentCwdInput = {
+    cwdType?: AgentCwdType;
+    /** Absolute path; only for custom (or alone ⇒ implied custom). */
+    cwd?: string;
+};
+/** Subset of AppRuntime needed to resolve cwdType "app". */
+type AgentCwdContext = {
+    appDir?: string;
+};
+declare function isAgentCwdType(value: unknown): value is AgentCwdType;
+/**
+ * Resolve an absolute enterable cwd for the agent session.
+ * When cwdType is "temp", creates a new directory under os.tmpdir().
+ */
+declare function resolveAgentCwd(input: AgentCwdInput, ctx?: AgentCwdContext): string;
+
+/**
+ * Shared / extensible options for ctx.llm and ctx.agent.
+ * Minimum known field set is explicit; hosts may intersect extra fields at the edges.
+ */
+/** JSON Schema document passed as `opts.schema` (soft-instruct + coerce). */
+type JsonSchema = object;
+/**
+ * Minimum shared options for model-backed calls (llm + agent).
+ * Open for declaration merging / intersection by host packages.
+ */
+interface ModelCallOptions {
+    provider?: string;
+    model?: string;
+    /** Extra system instruction (combined with schema instruction when both set). */
+    system?: string;
+    /** When set, host soft-instructs JSON-only output and coerces fences/preamble. */
+    schema?: JsonSchema;
+    maxTokens?: number;
+    signal?: AbortSignal;
+}
+/** Options for HostCapabilities.llm / ctx.llm. */
+interface LlmRunOptions extends ModelCallOptions {
+}
+/** Subset used by JSON instruct / coerce helpers. */
+type JsonInstructOptions = Pick<ModelCallOptions, "schema" | "system">;
+/** Subset used by provider/model routing. */
+type ModelRouteOptions = Pick<ModelCallOptions, "provider" | "model">;
+
+/**
+ * Process events for ctx.agent — optional observation surface.
+ * Final answer remains Promise<string>; apps opt in via opts.onEvent.
+ */
+
+/**
+ * Why a turn ended (from dsh session `turn/end.reason`).
+ * Kept loose so hosts can pass through new kinds without breaking apps.
+ */
+type AgentTurnEndReason = {
+    kind: string;
+    /** Nested details when kind is error / aborted / etc. */
+    error?: unknown;
+    reason?: unknown;
+};
+type AgentEvent = {
+    type: "status";
+    status: "running" | "idle";
+} | {
+    type: "text-delta";
+    text: string;
+} | {
+    type: "tool";
+    phase: "start" | "end";
+    name: string;
+    args?: unknown;
+    result?: unknown;
+} | {
+    type: "turn";
+    phase: "start";
+    turn: number;
+} | {
+    type: "turn";
+    phase: "end";
+    turn: number;
+    reason?: AgentTurnEndReason;
+} | {
+    type: "error";
+    message: string;
+} | {
+    type: "done";
+    text: string;
+};
+type AgentEventHandler = (event: AgentEvent) => void;
+/** Options for HostCapabilities.agent / ctx.agent (extends shared model-call fields). */
+interface AgentRunOptions extends ModelCallOptions {
+    /**
+     * Soft cap on agent turns (host cancels after this many `turn` end events).
+     * dsh AgentOptions has no native maxIterations — enforced by the one-shot runner.
+     */
+    maxIterations?: number;
+    /** Optional live projection of the agent run (does not change the string return). */
+    onEvent?: AgentEventHandler;
+    /**
+     * Working-directory mode for the agent session (default `"process"`).
+     * - app: current mini-app directory (from AppRuntime.appDir)
+     * - process: dsh process.cwd()
+     * - temp: fresh directory under os.tmpdir()
+     * - custom: requires `cwd` absolute path
+     *
+     * If `cwd` is set without cwdType, treated as custom.
+     * If `cwd` is set with cwdType other than custom → error.
+     */
+    cwdType?: AgentCwdType;
+    /** Absolute path; only with cwdType "custom", or alone (implies custom). */
+    cwd?: string;
+}
+
+/**
+ * Call-level facts for a mini-app API invocation (no capability methods).
+ * Passed as the first argument to HostCapabilities.* — never merged into user opts.
+ */
+type AppCallContext = {
+    /** Reverse-DNS app id (e.g. com.example.todo). */
+    appId: string;
+    /** Absolute runtime/apps/<appId> directory (derived from appId). */
+    appDir: string;
+    /** Cancel signal for the current dashboard API call. */
+    signal?: AbortSignal;
+    /**
+     * Optional host.json llm route defaults — routing only, never written into opts.
+     */
+    hostLlm?: {
+        provider?: string;
+        model?: string;
+    };
+};
+/** Effective abort signal: user opts win when set, else call context signal. */
+declare function effectiveSignal(optsSignal: AbortSignal | undefined, call: AppCallContext | undefined): AbortSignal | undefined;
+
+type AppTheme = {
+    theme: string;
+    palette: string;
+};
+declare function readAppTheme(dir: string): AppTheme | null;
+declare function writeAppTheme(dir: string, val: AppTheme | null): AppTheme | null;
+
+declare const appIdBrand: unique symbol;
+declare const absolutePathBrand: unique symbol;
+type AppId = string & {
+    readonly [appIdBrand]: "AppId";
+};
+type AbsolutePath = string & {
+    readonly [absolutePathBrand]: "AbsolutePath";
+};
+declare function isAppId(value: string): value is AppId;
+declare function asAppId(value: string): AppId;
+declare function isAbsolutePath(value: string): value is AbsolutePath;
+declare function asAbsolutePath(value: string): AbsolutePath;
+declare function assertNever(value: never, message?: string): never;
+
+/**
+ * Stateless host capabilities. First argument is always the call context;
+ * user opts (2nd/3rd) stay pristine — do not mutate them.
+ */
+interface HostCapabilities {
+    bash?(ctx: AppCallContext, command: string): Promise<{
+        stdout: string;
+        stderr: string;
+        exitCode: number;
+    }>;
+    llm?(ctx: AppCallContext, prompt: string, opts?: LlmRunOptions): Promise<string>;
+    /** Final answer is always a string; pass `opts.onEvent` for live process events. */
+    agent?(ctx: AppCallContext, goal: string, opts?: AgentRunOptions): Promise<string>;
+    tool?(ctx: AppCallContext, name: string, args?: Record<string, unknown>): Promise<unknown>;
+    mcp?(ctx: AppCallContext, name: string, args?: Record<string, unknown>): Promise<unknown>;
+    /** May later scope by app/call; pass ctx even if unused today. */
+    credentials?(ctx: AppCallContext): Record<string, string>;
+    /** May later scope by app/call; pass ctx even if unused today. */
+    config?(ctx: AppCallContext): Record<string, unknown>;
+    listTools?(ctx: AppCallContext): unknown[];
+}
+/**
+ * Author-facing methods (no leading ctx — bound by bindCapsToContext).
+ * `credentials` / `config` are methods here; AppsManager exposes them as `ctx.*` properties.
+ */
+type BoundHostCapabilities = {
+    bash(command: string): Promise<{
+        stdout: string;
+        stderr: string;
+        exitCode: number;
+    }>;
+    llm(prompt: string, opts?: LlmRunOptions): Promise<string>;
+    agent(goal: string, opts?: AgentRunOptions): Promise<string>;
+    tool(name: string, args?: Record<string, unknown>): Promise<unknown>;
+    mcp(name: string, args?: Record<string, unknown>): Promise<unknown>;
+    credentials(): Record<string, string>;
+    config(): Record<string, unknown>;
+    listTools(): unknown[];
+};
+/**
+ * Bind caps.*(ctx, …) onto author-facing methods.
+ * Keep this list next to HostCapabilities so new tools are not forgotten.
+ */
+declare function bindCapsToContext(ctx: AppCallContext, caps: HostCapabilities): BoundHostCapabilities;
+
+/** Owns all path composition under a validated absolute runtime root. */
+declare class WorkspacePaths {
+    static readonly Rel: {
+        readonly apps: "apps";
+        readonly hostConfig: "host.json";
+        readonly ui: "ui.tsx";
+        readonly api: "main.api.ts";
+        readonly manifest: "manifest.json";
+        readonly storage: "storage";
+        readonly uiCache: ".ui-cache";
+    };
+    readonly root: AbsolutePath;
+    constructor(root: AbsolutePath);
+    appsDir(): AbsolutePath;
+    appDir(id: AppId): AbsolutePath;
+    hostConfigFile(): AbsolutePath;
+    uiCacheDir(): AbsolutePath;
+    appFile(id: AppId, rel: string): AbsolutePath;
+}
+
+declare const THEME_IDS: readonly ["light", "dark"];
+type ThemeId = (typeof THEME_IDS)[number];
+declare const PALETTE_IDS: readonly ["default", "tokyo", "forest", "matcha", "yellow", "zoro", "hokage", "slate"];
+type PaletteId = (typeof PALETTE_IDS)[number];
+declare const LOCALE_IDS: readonly ["zh-CN", "en"];
+type LocaleId = (typeof LOCALE_IDS)[number];
+type LlmConfig = {
+    provider: string;
+    model: string;
+};
+type HostConfig = {
+    runtimeRoot: AbsolutePath;
+    hostPort: number;
+    theme: ThemeId;
+    /** Builtin {@link PaletteId} or a custom theme id from runtime themes/. */
+    palette: string;
+    locale: LocaleId;
+    chatLanguage: LocaleId;
+    llm: LlmConfig | null;
+};
+type HostConfigSeed = {
+    runtimeRoot: string;
+    hostPort: number;
+    theme: ThemeId;
+    palette: string;
+    locale: LocaleId;
+    chatLanguage: LocaleId;
+    llm: LlmConfig | null;
+};
+type HostConfigInitInput = {
+    runtimeRoot?: string;
+    hostPort?: number;
+    theme?: string;
+    palette?: string;
+    locale?: string;
+    chatLanguage?: string;
+    llm?: {
+        provider?: string;
+        model?: string;
+    } | null;
+};
+
+type UiBuildFile = {
+    name: string;
+    contents: Uint8Array;
+};
+type UiCompileOptions = {
+    locale: LocaleId;
+};
+/**
+ * Locate @monkey-mini-app/ui dist.
+ * When host is bundled into dsh/lib, `import.meta.url` is the plugin bundle —
+ * resolve from several bases + monorepo-relative fallbacks.
+ */
+declare function resolveUiDistDir(): string;
+/** Bundles a mini-app ui.tsx into self-contained ESM (entry.js + chunks). */
+declare class UiCompiler {
+    private readonly paths;
+    private readonly buildCache;
+    constructor(paths: WorkspacePaths);
+    invalidate(appDir: string): void;
+    cacheSize(): number;
+    compile(appDir: string, options: UiCompileOptions): Promise<UiBuildFile[]>;
+    private cacheKey;
+    private cacheSig;
+}
+
+type GitAuthor = {
+    name: string;
+    email: string;
+};
+type Commit = {
+    id: string;
+    time: string;
+    message: string;
+};
+type FileStat = {
+    path: string;
+    add: number;
+    del: number;
+};
+type CommitNode = {
+    id: string;
+    parentIds: string[];
+    message: string;
+    time: string;
+};
+type CommitTree = {
+    head: string;
+    nodes: CommitNode[];
+    tips: {
+        name: string;
+        commitId: string;
+    }[];
+};
+/** isomorphic-git only. Read + write history for an app directory. */
+declare class GitHistory {
+    private readonly commitCountCache;
+    private invalidateCount;
+    init(dir: string): Promise<void>;
+    commit(dir: string, message: string, opts?: {
+        author?: GitAuthor;
+    }): Promise<{
+        commitId: string;
+    }>;
+    /**
+     * True when worktree or index differs from HEAD.
+     * Content-hashes tracked files that statusMatrix marks clean — isomorphic-git
+     * can miss same-size / same-mtime edits (see stageAll comment).
+     */
+    isDirty(dir: string): Promise<boolean>;
+    listCommits(dir: string, opts?: {
+        limit?: number;
+    }): Promise<CommitTree>;
+    revert(dir: string, commitId: string, opts?: {
+        message?: string;
+    }): Promise<{
+        commitId: string;
+    }>;
+    resetTo(dir: string, commitId: string, opts?: {
+        createBackupRef?: boolean;
+    }): Promise<{
+        backupRef?: string;
+    }>;
+    commitCount(dir: string): Promise<number>;
+    log(dir: string, limit: number): Promise<Commit[]>;
+    fileStats(dir: string, id: string): Promise<FileStat[]>;
+    filePreview(dir: string, id: string, filepath: string, maxLines?: number): Promise<string>;
+}
+
+interface FuzzyMatchResult {
+    /** Whether a match was found */
+    found: boolean;
+    /** The index where the match starts (in the content that should be used for replacement) */
+    index: number;
+    /** Length of the matched text */
+    matchLength: number;
+    /** Whether fuzzy matching was used (false = exact match) */
+    usedFuzzyMatch: boolean;
+    /**
+     * The content to use for replacement operations.
+     * When exact match: original content. When fuzzy match: normalized content.
+     */
+    contentForReplacement: string;
+}
+interface Edit {
+    oldText: string;
+    newText: string;
+}
+interface AppliedEditsResult {
+    baseContent: string;
+    newContent: string;
+}
+/**
+ * Find oldText in content, trying exact match first, then fuzzy match.
+ * When fuzzy matching is used, the returned contentForReplacement is the
+ * fuzzy-normalized version of the content (trailing whitespace stripped,
+ * Unicode quotes/dashes normalized to ASCII).
+ */
+declare function fuzzyFindText(content: string, oldText: string): FuzzyMatchResult;
+/**
+ * Apply one or more exact-text replacements to LF-normalized content.
+ *
+ * All edits are matched against the same original content. Replacements are
+ * then applied in reverse order so offsets remain stable. If any edit needs
+ * fuzzy matching, the operation runs in fuzzy-normalized content space and then
+ * overlays those line-level changes onto the original content so unchanged line
+ * blocks keep their original bytes.
+ */
+declare function applyEditsToNormalizedContent(normalizedContent: string, edits: Edit[], path: string): AppliedEditsResult;
+
+/**
+ * Mini-app source file CUD helpers (list/read/write/edit/delete).
+ * Edit semantics come from ./edit-diff.ts (Pi MIT port).
+ */
+
+type ListedFile = {
+    path: string;
+    size: number;
+};
+/** 1-indexed inclusive line window. Omit both → whole file. */
+type ReadFileRange = {
+    startLine?: number;
+    endLine?: number;
+    /**
+     * Prefix each returned line with `N|` (1-indexed absolute line numbers).
+     * Default false — raw text is better for copying into mini_app_edit oldText.
+     */
+    numbered?: boolean;
+};
+type ReadFileResult = {
+    path: string;
+    /** Sliced file text (raw, or numbered when numbered:true). */
+    content: string;
+    bytes: number;
+    totalLines: number;
+    /** Actual 1-indexed inclusive window returned. */
+    startLine: number;
+    endLine: number;
+    /** True when a safety cap truncated the response (caller should page with startLine). */
+    truncated?: boolean;
+};
+type MutateFileResult = {
+    path: string;
+    bytes: number;
+    diff?: string;
+    created?: boolean;
+};
+
+type HttpRequest = {
+    url: string;
+    method?: string;
+    headers?: Record<string, string>;
+    query?: Record<string, string | number | boolean | null | undefined>;
+    body?: unknown;
+    timeout?: number;
+    signal?: AbortSignal;
+};
+type HttpResponse = {
+    ok: boolean;
+    status: number;
+    headers: Record<string, string>;
+    text: string;
+    json: unknown | null;
+};
+
+type AppItem = {
+    id: AppId;
+    name: string;
+    description: string;
+    version: string;
+    acronym: string;
+    commits: number;
+};
+type AppStorage = {
+    get(key: string): Promise<unknown>;
+    set(key: string, value: unknown): Promise<void>;
+    delete(key: string): Promise<void>;
+    clear(): Promise<void>;
+    table(name: string): AppStorage;
+};
+type AppContext = {
+    /** Reverse-DNS id of the running mini-app. */
+    appId: string;
+    /** Absolute runtime/apps/<appId> directory (derived from appId). */
+    appDir: string;
+    storage: AppStorage;
+    state: Record<string, unknown>;
+    credentials: Record<string, string>;
+    log(...a: unknown[]): void;
+    push(method: string, params?: unknown): void;
+    mcp(name: string, args?: Record<string, unknown>): Promise<unknown>;
+    tool(name: string, args?: Record<string, unknown>): Promise<unknown>;
+    listTools(): unknown[];
+    llm(prompt: string, opts?: LlmRunOptions): Promise<string>;
+    agent(goal: string, opts?: AgentRunOptions): Promise<string>;
+    bash(command: string): Promise<{
+        stdout: string;
+        stderr: string;
+        exitCode: number;
+    }>;
+    http(url: string | HttpRequest, opts?: Omit<HttpRequest, "url">): Promise<HttpResponse>;
+    system: {
+        metrics(): Promise<Record<string, unknown>>;
+    };
+    config: Record<string, unknown>;
+    /** Cancel signal for the current dashboard API call. */
+    signal?: AbortSignal;
+};
+type DashboardMethod = (ctx: AppContext, args: unknown) => unknown | Promise<unknown>;
+type DashboardDef = {
+    name: string;
+    description: string;
+    api: Record<string, DashboardMethod>;
+    state?: Record<string, unknown>;
+};
+type AfterMutateOptions = {
+    commitMessage: string;
+    /** Default true. Pass false to skip auto-commit. */
+    commit?: boolean;
+};
+type AfterMutateResult = {
+    committed: {
+        commitId: string;
+        message: string;
+    } | null;
+};
+type ReloadResult = {
+    ok: boolean;
+    errors: string[];
+    path: string;
+    compiled?: {
+        api: boolean;
+        ui: boolean;
+    };
+    committed?: {
+        commitId: string;
+        message: string;
+    } | null;
+};
+/** Loads, registers, and executes mini-apps under WorkspacePaths.appsDir(). */
+declare class AppsManager {
+    private readonly paths;
+    private readonly capabilities;
+    private readonly git;
+    private readonly config;
+    private readonly dashboardCache;
+    private uiCompiler;
+    constructor(paths: WorkspacePaths, capabilities: HostCapabilities, git: GitHistory, config: HostConfig);
+    /** Wire UI compiler for invalidate + reload (createHost calls this). */
+    setUiCompiler(compiler: UiCompiler): void;
+    dirOf(appId: string): AbsolutePath;
+    list(): Promise<AppItem[]>;
+    get(appId: string): Promise<AppItem | null>;
+    register(appId: string, files: Record<string, string>): Promise<AppItem>;
+    listFiles(appId: string): Promise<ListedFile[]>;
+    readFile(appId: string, relPath: string, range?: ReadFileRange): Promise<ReadFileResult>;
+    writeFile(appId: string, relPath: string, content: string, opts?: {
+        commit?: boolean;
+    }): Promise<MutateFileResult & AfterMutateResult>;
+    editFile(appId: string, relPath: string, edits: Edit[], opts?: {
+        commit?: boolean;
+    }): Promise<MutateFileResult & AfterMutateResult>;
+    deleteFile(appId: string, relPath: string, opts?: {
+        commit?: boolean;
+    }): Promise<{
+        path: string;
+    } & AfterMutateResult>;
+    /**
+     * Validate + sync-compile api/ui. On success, auto-commit if the worktree is dirty.
+     * Replaces the old lightweight mini_app_validate tool.
+     */
+    reload(appId: string): Promise<ReloadResult>;
+    afterMutate(appDir: string, opts: AfterMutateOptions): Promise<AfterMutateResult>;
+    remove(appId: string): Promise<void>;
+    load(appId: string): {
+        def: DashboardDef;
+        ctx: AppContext;
+    };
+    call(appId: string, method: string, args?: unknown, signal?: AbortSignal): Promise<unknown>;
+    invalidate(appDir: string): void;
+    private readAppItem;
+    private dashboardMtime;
+    private loadMainApi;
+    private loadAppFile;
+    private buildCtx;
+}
+
+type AppManifest = {
+    id: AppId;
+    name: string;
+    version: string;
+    entry: string;
+    description?: string;
+    permissions: string[];
+    acronym?: string;
+    theme?: {
+        followsHost?: boolean;
+    };
+};
+/** Parse and validate a mini-app manifest.json. */
+declare function parseManifest(raw: string): AppManifest;
+/** Two-letter badge: manifest acronym wins, else first two alphanumeric of name. */
+declare function acronymOf(name: string, manifestAcronym?: string): string;
+
+type StorageTableInfo = {
+    name: string;
+    size: number;
+    updatedAt: string;
+};
+/** Enumerate `*.json` tables under an app storage dir (newest first). */
+declare function listStorageTables(dir: string): StorageTableInfo[];
+/** Basename-only join + `.json` — blocks path traversal. */
+declare function storageTablePath(dir: string, table: string): string;
+declare function readJsonFile(fp: string, fallback?: unknown): unknown;
+
+/** Install/init: apply DEFAULT_HOST_CONFIG_SEED, then parse. */
+declare function bootstrapHostConfig(input: HostConfigInitInput): HostConfig;
+
+/** Bootstrap-only defaults. Runtime load/parse must not read this module. */
+declare const DEFAULT_HOST_CONFIG_SEED: HostConfigSeed;
+
+/** Read host.json from WorkspacePaths. Fail loud; no defaults. */
+declare function loadHostConfig(paths: WorkspacePaths): HostConfig;
+
+/** Validate a complete host config. Does not apply defaults. */
+declare function parseHostConfig(raw: unknown): HostConfig;
+
+/** Persist a complete HostConfig to host.json (pretty-printed). */
+declare function writeHostConfig(paths: WorkspacePaths, config: HostConfig): void;
+
+/** Host → browser events (SSE). Agent-agnostic; tools emit, HttpGateway fans out. */
+type HostEvent = {
+    type: "app:open";
+    appId: string;
+    title?: string;
+};
+type HostEventListener = (event: HostEvent) => void;
+declare class HostEventBus {
+    private readonly listeners;
+    private seq;
+    subscribe(listener: HostEventListener): () => void;
+    emit(event: HostEvent): void;
+    /** Monotonic id for SSE `id:` fields. */
+    nextId(): number;
+}
+declare function formatSse(event: HostEvent, id: number): string;
+
+/** Custom palette row for GET /api/palettes (builtins stay in panel). */
+type CustomThemePalette = {
+    id: string;
+    label: string;
+    swatch: string;
+    custom: true;
+    /** Opaque token bags; panel maps them when applying. */
+    tokens?: {
+        light: Record<string, string>;
+        dark: Record<string, string>;
+    };
+};
+/**
+ * ThemeResource — host consumes; the shell (dsh) implements.
+ * Parallel to HostCapabilities / HostLifecycle (not a bare CSS string callback).
+ */
+interface ThemeResource {
+    /** Full CSS injected into the iframe runner `<style>` (builtin + custom blocks). */
+    runnerCss(): string;
+    /** Optional custom themes for `/api/palettes`. Default empty. */
+    listCustomPalettes?(): CustomThemePalette[] | Promise<CustomThemePalette[]>;
+}
+/** Empty resource used when the shell does not supply themes. */
+declare const EMPTY_THEME_RESOURCE: ThemeResource;
+
+/** Localhost HTTP surface. Calls AppsManager / UiCompiler — never ToolFacade. */
+declare class HttpGateway {
+    private readonly apps;
+    private readonly config;
+    private readonly paths;
+    private readonly compiler;
+    private readonly git;
+    private readonly themes;
+    private readonly events?;
+    private readonly onHostPortChanged?;
+    readonly app: Hono;
+    private server;
+    private boundPort;
+    constructor(apps: AppsManager, config: HostConfig, paths: WorkspacePaths, compiler: UiCompiler, git: GitHistory, themes?: ThemeResource, events?: HostEventBus | undefined, onHostPortChanged?: ((port: number) => void) | undefined);
+    get port(): number;
+    listen(port: number): Promise<number>;
+    close(): Promise<void>;
+    private buildApp;
+}
+
+type ToolDefinition = {
+    name: string;
+    description: string;
+    inputSchema: Record<string, unknown>;
+    execute: (args: Record<string, unknown>, signal?: AbortSignal) => Promise<unknown>;
+};
+/** Host chat tools: `mini_app_list`, `mini_app_read`, … and `mini_app_list_ctx_tools`. */
+declare function isMiniAppToolName(name: string): boolean;
+/** Agent-facing mini_app_* tools. Execute calls AppsManager / GitHistory — never HTTP. */
+declare class ToolFacade {
+    private readonly apps;
+    private readonly git;
+    private readonly paths;
+    private readonly events?;
+    constructor(apps: AppsManager, git: GitHistory, paths: WorkspacePaths, events?: HostEventBus | undefined);
+    definitions(): ToolDefinition[];
+    invoke(name: string, args?: Record<string, unknown>, signal?: AbortSignal): Promise<unknown>;
+    private handleGet;
+    private handleReload;
+    private handleRegister;
+    private handleListFiles;
+    private handleRead;
+    private handleEdit;
+    private handleWrite;
+    private handleDelete;
+    private handleOpen;
+    private handleCall;
+    private handleHistoryCommit;
+    private handleHistoryList;
+    private handleHistoryReset;
+    private handleHistoryRevert;
+}
+
+type LogLevel = "debug" | "info" | "warn" | "error";
+/** Domain managers passed to `attach`. HTTP and tools both call these. */
+type HostServices = {
+    apps: AppsManager;
+    git: GitHistory;
+    tools: ToolFacade;
+    paths: WorkspacePaths;
+    config: HostConfig;
+};
+/** Host calls these; the agent plugin implements. */
+interface HostLifecycle {
+    attach(ctx: unknown, services: HostServices): void | Promise<void>;
+    detach?(): void | Promise<void>;
+    onHostPortChanged?(port: number): void;
+    log?(level: LogLevel, message: string, meta?: unknown): void;
+}
+
+/** Agent-agnostic host. `apply` = attach + listen on the Hono HttpGateway. */
+declare class Host {
+    private readonly capabilities;
+    private readonly lifecycle;
+    private readonly paths;
+    private readonly config;
+    private readonly services;
+    private readonly http;
+    private boundPort;
+    private attached;
+    private active;
+    constructor(capabilities: HostCapabilities, lifecycle: HostLifecycle, paths: WorkspacePaths, config: HostConfig, services: HostServices, http: HttpGateway);
+    get port(): number;
+    apply(ctx?: unknown): Promise<{
+        port: number;
+    }>;
+    start(): Promise<{
+        port: number;
+    }>;
+    stop(): Promise<void>;
+}
+
+/** Assemble a Host. `options.config` must already be parsed (`parseHostConfig` / bootstrap). */
+declare function createHost(capabilities: HostCapabilities, lifecycle: HostLifecycle, options: {
+    config: HostConfig;
+    /** Theme resource port — shell implements; host only consumes the interface. */
+    themes?: ThemeResource;
+}): Host;
+
+declare class HostError extends Error {
+    readonly code: string;
+    constructor(code: string, message: string, options?: {
+        cause?: unknown;
+    });
+}
+declare class HostConfigError extends HostError {
+    constructor(message: string, options?: {
+        code?: string;
+        cause?: unknown;
+    });
+}
+
+/** Iframe entry HTML for a compiled mini-app UI bundle. */
+declare function appRunnerHtml(appId: string, themeCss?: string): string;
+
+type I18nParams = Record<string, string | number>;
+type HostI18n = {
+    readonly locale: LocaleId;
+    t(key: string, params?: I18nParams): string;
+};
+/** i18next helper bound to `locale`. Missing keys throw outside production. */
+declare function createHostI18n(locale: LocaleId): HostI18n;
+
+declare const packageName = "@monkey-mini-app/host";
+
+export { type AbsolutePath, type AfterMutateOptions, type AfterMutateResult, type AgentCwdContext, type AgentCwdInput, type AgentCwdType, type AgentEvent, type AgentEventHandler, type AgentRunOptions, type AgentTurnEndReason, type AppCallContext, type AppContext, type AppId, type AppItem, type AppManifest, type AppStorage, type AppTheme, AppsManager, type BoundHostCapabilities, type Commit, type CommitNode, type CommitTree, type CustomThemePalette, DEFAULT_HOST_CONFIG_SEED, type DashboardDef, type DashboardMethod, EMPTY_THEME_RESOURCE, type Edit, type FileStat, type GitAuthor, GitHistory, Host, type HostCapabilities, type HostConfig, HostConfigError, type HostConfigInitInput, type HostConfigSeed, HostError, type HostEvent, HostEventBus, type HostEventListener, type HostI18n, type HostLifecycle, type HostServices, HttpGateway, type I18nParams, type JsonInstructOptions, type JsonSchema, LOCALE_IDS, type LlmConfig, type LlmRunOptions, type LocaleId, type LogLevel, type ModelCallOptions, type ModelRouteOptions, PALETTE_IDS, type PaletteId, type ReloadResult, type StorageTableInfo, THEME_IDS, type ThemeId, type ThemeResource, type ToolDefinition, ToolFacade, type UiBuildFile, type UiCompileOptions, UiCompiler, WorkspacePaths, acronymOf, appRunnerHtml, applyEditsToNormalizedContent, asAbsolutePath, asAppId, assertNever, bindCapsToContext, bootstrapHostConfig, createHost, createHostI18n, effectiveSignal, formatSse, fuzzyFindText, isAbsolutePath, isAgentCwdType, isAppId, isMiniAppToolName, listStorageTables, loadHostConfig, packageName, parseHostConfig, parseManifest, readAppTheme, readJsonFile, resolveAgentCwd, resolveUiDistDir, storageTablePath, writeAppTheme, writeHostConfig };