@hearthscale/app 0.0.0-stage → 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,3230 @@
+/**
+ * The platform half of the contract, generated from the Rust types of
+ * the `contract` crate by `npm run contract` in `apps/platform/scripts`.
+ * Do not edit: change the Rust types and run the command again.
+ */
+
+/**
+ * One line of a session log: the body its `type` names, and the envelope
+ * every entry shares. Tree entries carry `parent`; the others are out of
+ * the tree and apply to the whole session.
+ */
+type Entry = {
+    seq: number;
+    id: string;
+    at: string;
+    session: string;
+    by: PrincipalRef;
+    origin: Origin;
+} & ({
+    app: string;
+    appVersion: string;
+    agent: string;
+    authoritySession: string;
+    project?: string;
+    forkedFrom?: ForkPoint;
+    spawnedBy?: SpawnPoint;
+    startedBy?: PrincipalRef;
+    type: 'session.created';
+} | {
+    title: string;
+    type: 'session.title';
+} | {
+    turn: string;
+    result: Structured;
+    type: 'session.result';
+} | {
+    type: 'session.closed';
+} | {
+    project: string | null;
+    pinned: boolean;
+    archived: boolean;
+    rank: number;
+    type: 'session.filing';
+} | {
+    model?: string | null;
+    type: 'session.settings';
+} | {
+    to: string | null;
+    type: 'session.leaf';
+} | {
+    attached: SessionRoot[];
+    type: 'session.roots';
+} | {
+    turn: string;
+    model: string;
+    provider: string;
+    location: ModelLocation;
+    revision: string;
+    type: 'turn.started';
+} | {
+    turn: string;
+    stopReason: StopReason;
+    type: 'turn.finished';
+} | {
+    parent: string | null;
+    parts: UserPart[];
+    type: 'user.message';
+} | {
+    parent: string | null;
+    turn: string;
+    parts: AgentPart[];
+    toolCalls?: ToolCall[];
+    usage?: Usage;
+    stop: AgentStop;
+    model: string;
+    provider: string;
+    error?: string;
+    type: 'agent.message';
+} | {
+    turn: string;
+    partId: string;
+    text: string;
+    type: 'agent.part';
+} | {
+    callId: string;
+    turn: string;
+    /**
+     * The call this one runs under; absent for a call of the turn.
+     */
+    under?: string;
+    name: string;
+    /**
+     * JSON-encoded, as the model emitted them.
+     */
+    arguments: string;
+    context: CallContext;
+    pin?: string;
+    /**
+     * Absent for a core tool, and for a name that named no tool.
+     */
+    label?: CallLabel;
+    type: 'call.prepared';
+} | {
+    callId: string;
+    turn: string;
+    under?: string;
+    executor: Executor;
+    type: 'call.dispatched';
+} | {
+    /**
+     * The tree parent; a call under another call has none and stays
+     * out of the tree.
+     */
+    parent?: string | null;
+    turn: string;
+    callId: string;
+    under?: string;
+    content: Content[];
+    structured?: Structured;
+    /**
+     * Values for the view that renders the result; they never reach a
+     * model.
+     */
+    meta?: {
+        [k: string]: unknown;
+    };
+    isError: boolean;
+    outcome: ToolOutcome;
+    /**
+     * The provider's view that renders the result, as its manifest
+     * declares it for the tool.
+     */
+    view?: ViewRef;
+    /**
+     * The paths the call changed, and the ones it read.
+     */
+    wrote?: string[];
+    read?: string[];
+    /**
+     * The model tokens the body spent through `models.complete`.
+     */
+    usage?: Usage;
+    type: 'tool.result';
+} | {
+    turn: string;
+    callId: string;
+    decision: Decision;
+    decidedBy: DecisionBy;
+    review?: ReviewRecord;
+    ask?: string;
+    grant?: Grant;
+    reason?: string;
+    type: 'consent.decision';
+} | {
+    cell: number;
+    callId: string;
+    turn: string;
+    type: 'cell.started';
+} | {
+    cell: number;
+    callId: string;
+    outcome: CellOutcome;
+    /**
+     * Why a program failed, in words.
+     */
+    error?: string;
+    /**
+     * The tail of the program's output.
+     */
+    output: string;
+    type: 'cell.ended';
+} | {
+    process: number;
+    callId: string;
+    turn: string;
+    command: string;
+    pid: number;
+    startedAt: string;
+    type: 'process.started';
+} | {
+    process: number;
+    callId: string;
+    outcome: ProcessOutcome;
+    /**
+     * The exit code of a command that exited.
+     */
+    code?: number;
+    /**
+     * Why a command was stopped, in words.
+     */
+    reason?: string;
+    /**
+     * The tail of the command's output.
+     */
+    output: string;
+    type: 'process.ended';
+} | {
+    ask: Ask;
+    type: 'ask.opened';
+} | {
+    ask: string;
+    outcome: AskOutcome;
+    answeredBy?: PrincipalRef;
+    option?: string;
+    allow?: boolean;
+    grant?: Grant;
+    /**
+     * The person's own words, answering a question.
+     */
+    text?: string;
+    type: 'ask.closed';
+} | {
+    parent: string | null;
+    app: string;
+    kind: string;
+    data: unknown;
+    /**
+     * Text the model sees for the entry; absent, it is display only.
+     */
+    context?: string;
+    type: 'app.entry';
+} | {
+    asset: string;
+    model: string | null;
+    /**
+     * The name the model that read the picture shows under.
+     */
+    label?: string;
+    text?: string;
+    reason?: DescriptionFailure;
+    usage?: Usage;
+    type: 'asset.described';
+} | {
+    watermark: string;
+    rounds: number;
+    type: 'compaction.cleared';
+} | {
+    tailStart: string;
+    summary: string;
+    sections: {
+        [k: string]: string;
+    };
+    kept: string[];
+    tokensBefore: number;
+    tokensAfter: number;
+    model: string;
+    provider: string;
+    location: ModelLocation;
+    usage?: Usage;
+    type: 'compaction.folded';
+} | {
+    reason: string;
+    model: string;
+    type: 'compaction.failed';
+} | {
+    parent: string | null;
+    turn: string;
+    what: BudgetWhat;
+    type: 'budget.reached';
+} | {
+    parent: string | null;
+    turn: string;
+    calls: string[];
+    type: 'repair.interrupted';
+});
+/**
+ * Who acts. A surface is one attachment of a client; an app is a package;
+ * a view is an app's view hosted by another app; the core is the daemon
+ * itself, which appears only as the author of entries it writes.
+ */
+type PrincipalRef = {
+    id: string;
+    kind: 'surface';
+} | {
+    id: string;
+    kind: 'app';
+} | {
+    id: string;
+    host: string;
+    kind: 'view';
+} | {
+    kind: 'core';
+};
+/**
+ * Where a message or a call came from: the person, the person while a
+ * turn ran, an app's backend, an agent, a view, or a window's own act
+ * outside any conversation.
+ */
+type Origin = 'user' | 'steer' | 'app' | 'agent' | 'view' | 'surface';
+type MountMode = 'read' | 'read-write';
+type RootKind = 'home' | 'workspace' | 'project' | 'memory' | 'skill' | 'folder' | 'file';
+type ModelLocation = 'local' | 'lan' | 'cloud';
+type StopReason = ('end_turn' | 'length' | 'budget' | 'cancelled' | 'error' | 'refused' | 'app_disabled' | 'app_update' | 'interrupted') | 'no_result';
+/**
+ * A part of a user message.
+ */
+type UserPart = {
+    text: string;
+    kind: 'text';
+} | {
+    asset: string;
+    name: string;
+    mediaType: string;
+    kind: 'asset';
+} | {
+    root: string;
+    path: string;
+    kind: 'file';
+} | {
+    name: string;
+    kind: 'skill';
+} | {
+    app: string;
+    item: MentionItem;
+    kind: 'mention';
+} | {
+    app: string;
+    title?: string;
+    content: Content;
+    kind: 'context';
+};
+/**
+ * What a tool result carries: a closed union, never a bare string. A
+ * result's one structured value travels beside its content.
+ */
+type Content = {
+    text: string;
+    kind: 'text';
+} | {
+    asset: string;
+    mediaType: string;
+    name?: string;
+    kind: 'asset';
+} | {
+    uri: string;
+    name?: string;
+    kind: 'resource_link';
+};
+/**
+ * A part of an agent message.
+ */
+type AgentPart = {
+    text: string;
+    kind: 'text';
+} | {
+    text: string;
+    kind: 'reasoning';
+};
+type AgentStop = 'end_turn' | 'tool_calls' | 'length' | 'cancelled' | 'error' | 'refused' | 'interrupted';
+/**
+ * A transcript mark an app's manifest names for a tool.
+ */
+type ChatIconRole = 'back' | 'brain' | 'camera' | 'check' | 'chevron-down' | 'alert' | 'clock' | 'code' | 'eye' | 'globe' | 'hammer' | 'image' | 'keyboard' | 'click' | 'scroll' | 'search' | 'pen' | 'terminal' | 'x' | 'compact' | 'agent' | 'lightbulb' | 'music' | 'speech' | 'transcript' | 'connector' | 'question' | 'view';
+type SourceKind = 'app' | 'connector';
+type ToolOutcome = 'completed' | 'failed' | 'cancelled' | 'skipped' | 'unknown';
+type Decision = 'run' | 'refused';
+/**
+ * Who or what let a call run, or refused it.
+ */
+type DecisionBy = 'level' | 'silent' | 'grant' | 'fence' | 'judge' | 'review' | 'person' | 'floor';
+type Risk = 'low' | 'high' | 'too_destructive';
+type Authorisation = 'explicitly_no' | 'neutral' | 'explicitly_yes';
+/**
+ * The rights a grant may hold; a closed list.
+ */
+type Right = 'fs.read' | 'fs.write' | 'net.host' | 'connector' | 'capability' | 'sessions.create' | 'terminal' | 'reader';
+/**
+ * How a program ended: at its end, with an error or a limit, stopped, or
+ * lost with a daemon that did not stop cleanly.
+ */
+type CellOutcome = 'finished' | 'failed' | 'stopped' | 'lost';
+/**
+ * How a background command ended: it exited, it was stopped, or it was
+ * lost with a daemon that did not stop cleanly.
+ */
+type ProcessOutcome = 'exited' | 'stopped' | 'lost';
+/**
+ * What a card asks about. One `tool` kind covers a core tool, an app's
+ * own tool, a connector tool and another app's capability; an app's own
+ * question is `app:<id>/<kind>`.
+ */
+type AskKind = CoreAskKind | AppAskKind;
+/**
+ * What a card asks about, besides an app's own question.
+ */
+type CoreAskKind = ('tool' | 'root' | 'connector.tools' | 'connector.login' | 'app.login' | 'terminal' | 'app.dev' | 'sandbox.violation') | 'question' | 'elicitation';
+/**
+ * An app's own question kind, `app:<id>/<kind>`.
+ */
+type AppAskKind = `app:${string}`;
+type PathShape = 'folder' | 'file';
+type GrantScope = 'session' | 'always';
+type AskOutcome = 'answered' | 'expired' | 'closed' | 'covered';
+/**
+ * Why an image has no description in place of one.
+ */
+type DescriptionFailure = 'over_budget' | 'vision_model_absent' | 'engine_failed';
+type BudgetWhat = 'tokens' | 'rounds';
+type EnvironmentKind = 'process' | 'vm';
+/**
+ * The tab commands a tool body may send to the session's executor
+ * surface. A command drives the page of the app's first surface, in the
+ * manifest's order, placed in the rail or a tab: a `web` surface's own
+ * page, or the web page of a view's tab. `navigate` loads an address in
+ * the session's tab, opening it when the session has none, hidden for a
+ * view's tab; `evaluate` runs a script and answers its value;
+ * `screenshot` answers the page as an asset; `show` puts the tab in front
+ * of the person; `close` ends it.
+ */
+type SurfaceOp = 'navigate' | 'evaluate' | 'screenshot' | 'show' | 'close';
+/**
+ * One setting's value.
+ */
+type SettingValue = string | number | boolean;
+/**
+ * The kinds a job runs on: every kind but chat.
+ */
+type JobKind = 'embedding' | 'image' | 'music' | 'speech' | 'transcription';
+type JobStatus = 'queued' | 'running' | 'completed' | 'failed' | 'cancelled';
+type SessionStatus = 'idle' | 'running' | 'requires_action' | 'terminated';
+/**
+ * One picture for both colour schemes, or one per scheme.
+ */
+type Schemed = ServedPicture | SchemePair;
+/**
+ * A picture the platform lets out of the package beside its page:
+ * `icon.svg`, `icon.png` or a path under `assets/`.
+ */
+type ServedPicture = string;
+/**
+ * What an app is for: one to three per listing, from this list and no
+ * other.
+ */
+type Category = 'chat' | 'writing' | 'coding' | 'research' | 'notes' | 'productivity' | 'communication' | 'data' | 'finance' | 'design' | 'audio' | 'video' | 'games' | 'education' | 'health' | 'lifestyle' | 'automation' | 'utilities';
+/**
+ * What a listing discloses about money, never a price: nothing is paid,
+ * something behind it is, or the whole of it is.
+ */
+type PaymentKind = 'free' | 'optional' | 'paid';
+/**
+ * An entry of `environment.network`.
+ */
+type NetworkEntry = string;
+type Lifetime = 'service';
+/**
+ * The kinds a model card answers on.
+ */
+type ModelKind = 'chat' | 'embedding' | 'image' | 'music' | 'speech' | 'transcription';
+type Reasoning = 'none' | 'auto' | 'high';
+/**
+ * A relative path inside the package, forward slashes, never leaving it.
+ */
+type PackagePath = string;
+/**
+ * The well-known roots an agent may name; a project adds `project` on its
+ * own.
+ */
+type AgentRoot = 'home' | 'workspace' | 'memory';
+/**
+ * Who may call a tool, as MCP Apps names them: `model`, the agents;
+ * `app`, the app's own views.
+ */
+type ToolVisibility = 'model' | 'app';
+/**
+ * The namespaces `uses` may name: the backend's channel namespaces, the
+ * view extensions, and `files.open`. A backend and a view reach `store`,
+ * `events`, `models`, `jobs` and `peers` alike, each only when its app
+ * names it here. An agent's core tools need no namespace here.
+ */
+type Uses = 'sessions' | 'sessions.create' | 'secrets' | 'notifications' | 'readers' | 'roots' | 'exec' | 'catalogue' | 'oauth' | 'surface' | 'store' | 'events' | 'models' | 'jobs' | 'terminals' | 'files.open' | 'surfaces.open' | 'peers';
+/**
+ * What a surface is: `view`, an MCP Apps document in a sandboxed frame,
+ * which may reserve slots for the chat the shell draws for the app's own
+ * agent; `web`, a web page on the app's own partition.
+ */
+type SurfaceDeclaration = {
+    id: string;
+    title: string;
+    /**
+     * The mark of the surface's tab and launcher row; absent, they show
+     * the app's icon.
+     */
+    icon?: Schemed;
+    /**
+     * @minItems 1
+     */
+    placements: Placement[];
+    /**
+     * @minItems 1
+     */
+    quickActions?: QuickAction[];
+    /**
+     * The view's document: a file in the package, or a `ui://` resource
+     * of one of the app's MCP servers.
+     */
+    entry: string;
+    /**
+     * The tool the host calls when the surface opens, with `{}`, or with
+     * the `FileInput` of the file it opens; its result is the view's first
+     * tool result. Absent, the view receives the tool input alone.
+     */
+    tool?: string;
+    /**
+     * The file extensions the view opens, in a tab, in place of the
+     * system's own app; with `https:` and `http:`, the web addresses of
+     * those schemes, each as the web page of a new tab of the view, which
+     * makes the app one the person may pick as their browser.
+     *
+     * @minItems 1
+     */
+    opens?: Opened[];
+    /**
+     * What the view shows at an address. A file a turn changed opens in
+     * the one usable app whose view shows its change when the working
+     * tree of its repository holds one, and in the one whose view shows
+     * files when it does not; the window first gives that app read
+     * access to the repository or the file's folder.
+     *
+     * @minItems 1
+     */
+    shows?: Shown[];
+    kind: 'view';
+} | {
+    id: string;
+    title: string;
+    /**
+     * The mark of the surface's tab and launcher row; absent, they show
+     * the app's icon.
+     */
+    icon?: Schemed;
+    /**
+     * @minItems 1
+     */
+    placements: Placement[];
+    /**
+     * @minItems 1
+     */
+    quickActions?: QuickAction[];
+    /**
+     * The page the surface opens on: an `https:` address, or `http:` on
+     * this machine, whose host `environment.network` covers.
+     */
+    entry: string;
+    /**
+     * Local storage the page finds at each load: on the origin of
+     * `entry`, each key holds its value before the page's own scripts
+     * run, so a setting the site keeps there, such as its theme, is the
+     * app's.
+     */
+    storage?: {
+        [k: string]: string;
+    };
+    kind: 'web';
+};
+/**
+ * Where a surface appears: `rail` gives the app its rail button, which
+ * opens the surface in the focused tile; `tab` lists it in the launcher as
+ * a tab of a tile; `inline` draws it in a transcript, under the result of
+ * each of the app's tools whose `view` names it; `modal` draws it over a
+ * tile of its app when a view of the app opens it with
+ * `hearthscale/ui/open-modal`.
+ */
+type Placement = 'rail' | 'tab' | 'inline' | 'modal';
+/**
+ * What a view surface opens: a file extension, or a scheme of web
+ * addresses.
+ */
+type Opened = string;
+/**
+ * What a view surface shows at an address the window opens it on,
+ * `/?path=<absolute path>` with the path percent-encoded: `file`, a file
+ * of this machine in its folder; `change`, a file's change in the working
+ * tree of its git repository.
+ */
+type Shown = 'file' | 'change';
+/**
+ * The literal `object`, the type of a settings schema.
+ */
+type ObjectType = 'object';
+/**
+ * One setting as a JSON Schema property.
+ */
+type SettingDeclaration = {
+    /**
+     * The setting's label.
+     */
+    title: string;
+    /**
+     * The tooltip of the setting's row.
+     */
+    description?: string;
+    /**
+     * The value the platform holds until the person changes it.
+     */
+    default: boolean;
+    type: 'boolean';
+} | {
+    /**
+     * The setting's label.
+     */
+    title: string;
+    /**
+     * The tooltip of the setting's row.
+     */
+    description?: string;
+    /**
+     * @minItems 1
+     */
+    enum?: string[];
+    minLength?: number;
+    maxLength?: number;
+    pattern?: string;
+    /**
+     * The value the platform holds until the person changes it.
+     */
+    default: string;
+    type: 'string';
+} | {
+    /**
+     * The setting's label.
+     */
+    title: string;
+    /**
+     * The tooltip of the setting's row.
+     */
+    description?: string;
+    minimum?: number;
+    maximum?: number;
+    multipleOf?: number;
+    /**
+     * The value the platform holds until the person changes it.
+     */
+    default: number;
+    type: 'number';
+} | {
+    /**
+     * The setting's label.
+     */
+    title: string;
+    /**
+     * The tooltip of the setting's row.
+     */
+    description?: string;
+    minimum?: number;
+    maximum?: number;
+    multipleOf?: number;
+    /**
+     * The value the platform holds until the person changes it.
+     */
+    default: number;
+    type: 'integer';
+};
+/**
+ * One row of a settings group: a setting by its name, or a button that
+ * calls one of the app's tools with `{}`. A tool whose result names a view
+ * opens that view in a modal over the settings; any other shows its text
+ * in a tooltip of the button.
+ */
+type SettingsItem = {
+    property: string;
+    kind: 'property';
+} | {
+    tool: string;
+    title: string;
+    kind: 'tool';
+};
+/**
+ * One MCP server the app brings. Its tools, `ui://` views and resources
+ * are the app's.
+ */
+type McpServerDeclaration = RemoteMcpServer | BundledMcpServer;
+/**
+ * The device capabilities a view may ask for, each a consent fact, as the
+ * MCP Apps sandbox permissions name them.
+ */
+type ViewPermission = 'camera' | 'microphone' | 'geolocation' | 'clipboard-write';
+/**
+ * The card a request runs on, or the reason in words that none can.
+ */
+type EffectiveModel = {
+    card: string;
+    source: ModelSource;
+} | {
+    card: null;
+    reason: string;
+};
+/**
+ * Where a chosen card comes from: the session's own model, the card the
+ * person gave the app, the role of its kind, or the daemon's rule.
+ */
+type ModelSource = 'session' | 'app' | 'role' | 'automatic';
+/**
+ * One frame of a streamed completion.
+ */
+type CompletionDelta = {
+    text: string;
+    reasoning?: boolean;
+} | {
+    done: true;
+    toolCalls?: ToolCall[];
+    usage?: Usage;
+    stop: CompletionStop;
+    error?: string;
+};
+type CompletionStop = 'end_turn' | 'tool_calls' | 'length' | 'cancelled' | 'error';
+type ChatRole = 'system' | 'user' | 'assistant' | 'tool';
+type ChatContent = string | ChatContentPart[];
+/**
+ * A part of a message's content: text, or a picture by its asset, which
+ * the model registry turns into its data URL.
+ */
+type ChatContentPart = {
+    text: string;
+    type: 'text';
+} | {
+    asset: string;
+    mediaType: string;
+    type: 'image';
+};
+/**
+ * A frame on `GET /terminals/:id/stream`: the snapshot once, then the
+ * bytes as they come, then the exit.
+ */
+type TerminalFrame = {
+    snapshot: TerminalSnapshot;
+    type: 'snapshot';
+} | {
+    data: string;
+    type: 'output';
+} | {
+    exitCode: number;
+    type: 'exited';
+};
+type TerminalStatus = 'running' | 'exited';
+/**
+ * What a view's `openai/resources/write` of an opened file did: saved
+ * with the new version's ETag; nothing written because the version on
+ * disk is another, which `etag` names; or nothing written because the
+ * bytes exceed `max_bytes`.
+ */
+type ResourceWriteResult = {
+    etag: string;
+    outcome: 'saved';
+} | {
+    etag: string;
+    outcome: 'conflict';
+} | {
+    maxBytes: number;
+    outcome: 'too-large';
+};
+/**
+ * What a patch compares: the working tree with the index, the index with
+ * `HEAD`, or the current branch with a base.
+ */
+type VcsScope = 'working' | 'staged' | 'branch';
+/**
+ * What one job takes.
+ */
+type JobInput = ImageJobInput | MusicJobInput | SpeechJobInput | TranscriptionJobInput | EmbeddingJobInput;
+/**
+ * How a sign-in reaches the person: `loopback` opens their browser and
+ * comes back to this computer; `device` shows a code to enter on any
+ * device.
+ */
+type OAuthGrant = 'loopback' | 'device';
+interface ForkPoint {
+    session: string;
+    leaf: string;
+}
+interface SpawnPoint {
+    session: string;
+    callId: string;
+}
+/**
+ * A tool's structured value: the object its declared output schema
+ * describes.
+ */
+interface Structured {
+    [k: string]: unknown;
+}
+/**
+ * One folder a session's tools reach, by the handle the model names.
+ */
+interface SessionRoot {
+    handle: string;
+    path: string;
+    mode: MountMode;
+    kind: RootKind;
+}
+/**
+ * One item of the composer's `@` list, as an MCP resource link: the
+ * address the app resolves it by, its name, and the words the list shows
+ * in place of the name.
+ */
+interface MentionItem {
+    uri: string;
+    name: string;
+    title?: string;
+    mimeType?: string;
+}
+interface ToolCall {
+    id: string;
+    name: string;
+    /**
+     * JSON-encoded arguments exactly as the model emitted them.
+     */
+    arguments: string;
+}
+/**
+ * Token counts as the runtime reported them, or as the shared estimator
+ * counted them with `estimated: true`.
+ */
+interface Usage {
+    input: number;
+    output: number;
+    estimated?: true;
+}
+/**
+ * What every tool call, session write and job carries: who acts, where
+ * the words came from, and the chain of principals the call crossed,
+ * outermost first.
+ */
+interface CallContext {
+    principal: PrincipalRef;
+    origin: Origin;
+    chain: PrincipalRef[];
+    session?: string;
+    turn?: string;
+    call?: string;
+    authoritySession?: string;
+}
+/**
+ * How the transcript shows a call of a tool an app or a connector
+ * declares, as the tool was when the call was prepared.
+ */
+interface CallLabel {
+    title: string;
+    icon?: ChatIconRole;
+    /**
+     * The app or the connector that declares the tool, and the name the
+     * person knows it by.
+     */
+    source: CallSource;
+}
+interface CallSource {
+    kind: SourceKind;
+    id: string;
+    name: string;
+}
+interface Executor {
+    principal: PrincipalRef;
+    instance: string;
+}
+/**
+ * The provider's view that renders a result: the provider and the view's
+ * id.
+ */
+interface ViewRef {
+    app: string;
+    id: string;
+}
+interface ReviewRecord {
+    risk: Risk;
+    authorisation: Authorisation;
+    reason: string;
+    model: string;
+    /**
+     * The `user` and `steer` entries the reviewer read as authorisation.
+     */
+    authorisedBy: string[];
+}
+/**
+ * One durable allowance. `fs.write` implies `fs.read`. A grant with
+ * `session` belongs to that session and its helpers, and ends with it.
+ * `pin` is the hash of a tool's name, description, schemas and flags.
+ */
+interface Grant {
+    principal: PrincipalRef;
+    right: Right;
+    subject: string;
+    label: string;
+    createdAt: string;
+    pin?: string;
+    session?: string;
+}
+interface Ask {
+    id: string;
+    kind: AskKind;
+    principal: PrincipalRef;
+    /**
+     * The principals the call crossed, outermost first.
+     */
+    chain: PrincipalRef[];
+    session?: string;
+    /**
+     * The root of the session's tree of helpers: where a helper's card is
+     * drawn, and the scope a session answer covers.
+     */
+    authoritySession?: string;
+    turn?: string;
+    callId?: string;
+    facts: AskFacts;
+    options: AskOption[];
+    openedAt: string;
+    /**
+     * Absolute; absent on a parked ask, which waits for a window.
+     */
+    deadline?: string;
+}
+/**
+ * The facts a card draws, as the core established them.
+ */
+interface AskFacts {
+    /**
+     * The tool's name; `source` names where it comes from when it is not
+     * a core tool, and `sourceName` is that app's or connector's name.
+     */
+    tool?: string;
+    source?: string;
+    sourceName?: string;
+    /**
+     * The names of the apps a call made inside other calls went through,
+     * after the conversation's app and before the tool's source.
+     */
+    via?: string[];
+    /**
+     * The words the card names the act by: a tool's manifest title, or an
+     * app question's title from its manifest.
+     */
+    title?: string;
+    /**
+     * The agent's question, on a `question` card; its options are the
+     * choices it offers.
+     */
+    question?: string;
+    /**
+     * The label of the control the person pressed in a view, as the view
+     * reported it.
+     */
+    label?: string;
+    arguments?: string;
+    /**
+     * The absolute path a file call would touch.
+     */
+    path?: string;
+    command?: string;
+    /**
+     * No fence holds the command.
+     */
+    unfenced?: true;
+    /**
+     * A fenced run tripped over these; `stderr` holds the lines that said
+     * so.
+     */
+    paths?: string[];
+    hosts?: string[];
+    stderr?: string;
+    /**
+     * The command still runs, and the fence holds its connection to the
+     * hosts until the answer.
+     */
+    running?: true;
+    /**
+     * What a backend wants a folder for, on a `root` card it raised.
+     */
+    purpose?: string;
+    /**
+     * On a `root` card: whether it is about a folder or one file.
+     */
+    shape?: PathShape;
+    /**
+     * An app's own question, or an elicitation's message: the app's words.
+     */
+    text?: string;
+    /**
+     * On an elicitation card: the form, as the JSON Schema object the
+     * server sent.
+     */
+    schema?: {
+        [k: string]: unknown;
+    };
+    /**
+     * A connector card: the connector, and the tools waiting on a bulk
+     * card, or the sign-in's issuer, or the device code the person types
+     * at the verification address. An app's sign-in card carries the
+     * issuer, the scopes, and the code or the sign-in a window starts
+     * with the authorization endpoint its browser opens.
+     */
+    connector?: string;
+    tools?: ToolSummary[];
+    issuer?: string;
+    userCode?: string;
+    verificationUri?: string;
+    scopes?: string[];
+    login?: string;
+    authorizationEndpoint?: string;
+}
+interface ToolSummary {
+    name: string;
+    description: string;
+}
+/**
+ * One answer a card offers, with the grant the core computed for it.
+ */
+interface AskOption {
+    id: string;
+    label: string;
+    /**
+     * The option is a pick: the person chooses a folder or a file, and the
+     * answer carries its path.
+     */
+    pick?: PathShape;
+    grant?: OptionGrant;
+}
+/**
+ * The grant the core computed for one answer of a card.
+ */
+interface OptionGrant {
+    principal: PrincipalRef;
+    right: Right;
+    subject: string;
+    scope: GrantScope;
+    pin?: string;
+}
+/**
+ * What the chips of a view hold from its last `ui/update-model-context`:
+ * the id the host gave that update, and its blocks.
+ */
+interface ModelContextState {
+    updateId: string;
+    /**
+     * The MCP content blocks of the update.
+     */
+    content?: {
+        [k: string]: unknown;
+    }[];
+    structuredContent?: {
+        [k: string]: unknown;
+    };
+}
+/**
+ * Every setting's value, by its name.
+ */
+interface SettingValues {
+    [k: string]: SettingValue;
+}
+/**
+ * One room an app of this platform is in. A member is a platform in the
+ * room, named by its peer id, which is new for each room and stays the
+ * member's while it keeps its place: through a dropped connection and a
+ * restart of its platform, until it leaves or the room ends.
+ */
+interface Room {
+    /**
+     * The same on every member's platform.
+     */
+    id: string;
+    app: string;
+    /**
+     * What a person passes on to another computer to join the room: a
+     * `hearthscale://join?app=<id>&ticket=<…>` link, which opens the
+     * client's join sheet with the ticket filled in, and which the sheet
+     * also takes pasted.
+     */
+    ticket: string;
+    /**
+     * This platform's peer id in the room.
+     */
+    me: string;
+    /**
+     * The member that opened the room: the room ends when it leaves.
+     */
+    opener: string;
+    /**
+     * The other members this platform is with now, in the order they
+     * came. A member that is with no one is out of reach of the opener
+     * and dials it again.
+     */
+    peers: string[];
+}
+/**
+ * One job as `POST /models/jobs` answers it and `job.progress` frames it.
+ * The result is one asset per output: a picture, a WAV, a text or a JSON
+ * document, owned by the session the job ran for or else by the app.
+ */
+interface Job {
+    id: string;
+    kind: JobKind;
+    app: string;
+    session?: string;
+    /**
+     * The tool call that submitted it, for a job a tool started.
+     */
+    callId?: string;
+    card: string;
+    status: JobStatus;
+    submittedAt: string;
+    /**
+     * Why the job has not started on the machine that runs it, such as
+     * busy models holding the memory it needs.
+     */
+    waiting?: string;
+    progress?: JobProgress;
+    result?: string[];
+    error?: string;
+    finishedAt?: string;
+}
+interface JobProgress {
+    fraction?: number;
+}
+/**
+ * A program of a session that runs now.
+ */
+interface SessionCell {
+    cell: number;
+    callId: string;
+}
+/**
+ * A command of a session that runs in the background now.
+ */
+interface SessionProcess {
+    process: number;
+    callId: string;
+}
+interface Manifest {
+    /**
+     * The address of this schema, for an editor's completion; nothing in
+     * Hearthscale reads it.
+     */
+    $schema?: string;
+    id: string;
+    name: string;
+    /**
+     * Semver, shown and never interpreted.
+     */
+    version: string;
+    api: 6;
+    description: string;
+    icon?: Schemed;
+    license?: string;
+    /**
+     * One to three categories, each once.
+     *
+     * @minItems 1
+     * @maxItems 3
+     */
+    categories?: Category[];
+    payment?: PaymentKind;
+    author?: string;
+    environment?: Environment;
+    agent?: AgentDefinition;
+    agents?: {
+        [k: string]: AgentDefinition;
+    };
+    models?: {
+        chat?: ModelNeed;
+        embedding?: ModelNeed;
+        image?: ModelNeed;
+        music?: ModelNeed;
+        speech?: ModelNeed;
+        transcription?: ModelNeed;
+    };
+    tools?: ToolDeclaration[];
+    capabilities?: Capabilities;
+    /**
+     * The questions the app's backend raises from inside a tool call, by
+     * kind, each with the title its card shows: a sign-in, a handoff.
+     */
+    asks?: AskDeclaration[];
+    /**
+     * The file formats the app's backend turns into text for the read
+     * tool, each an id and the extensions it claims.
+     */
+    formats?: FormatDeclaration[];
+    uses?: Uses[];
+    recommends?: string[];
+    onboarding?: Onboarding;
+    /**
+     * What the app shows in tiles, in the rail and in transcripts.
+     *
+     * @minItems 1
+     */
+    surfaces?: SurfaceDeclaration[];
+    settings?: SettingsDeclaration;
+    /**
+     * The tool that answers the composer's `@` list with the app's items:
+     * it takes `MentionSearch` and answers `MentionResult` as its
+     * structured result. A consent fact: the person's `@` runs it at
+     * every level.
+     */
+    mentions?: Mentions;
+    /**
+     * @minItems 1
+     */
+    mcp?: McpServerDeclaration[];
+    /**
+     * @minItems 1
+     */
+    permissions?: ViewPermission[];
+    /**
+     * Sample prompts the app's Marketplace listing shows.
+     *
+     * @minItems 1
+     */
+    examples?: string[];
+}
+interface SchemePair {
+    light: ServedPicture;
+    dark: ServedPicture;
+}
+interface Environment {
+    kind: EnvironmentKind;
+    /**
+     * The hosts the app reaches: its backend through the relay, its views
+     * and its web surfaces. Each is a consent fact.
+     */
+    network?: NetworkEntry[];
+    lifetime?: Lifetime;
+}
+interface AgentDefinition {
+    name: string;
+    description?: string;
+    model: ModelRequirement;
+    prompt?: PackagePath[];
+    compaction?: Compaction;
+    skills?: PackagePath[];
+    tools?: string[];
+    roots?: AgentRoot[];
+    budget?: Budget;
+    projects?: boolean;
+    /**
+     * The result a session of this agent answers through `finish`, when a
+     * helper's parent or an app started it: an object schema.
+     */
+    result?: {
+        [k: string]: unknown;
+    };
+}
+interface ModelRequirement {
+    kind: ModelKind;
+    tools?: boolean;
+    vision?: boolean;
+    /**
+     * Models the author knows the agent runs well on, as a catalogue
+     * spells them; a preference in the pick, never a requirement.
+     */
+    recommend?: string[];
+    sampling?: Sampling;
+    reasoning?: Reasoning;
+}
+interface Sampling {
+    temperature?: number;
+    topP?: number;
+    maxTokens?: number;
+}
+interface Compaction {
+    focus: string;
+}
+interface Budget {
+    tokens?: number;
+    rounds?: number;
+}
+/**
+ * The kinds of model a package needs, each marked as required or not, in
+ * the order the manifest names them.
+ */
+interface ModelNeed {
+    required: boolean;
+}
+interface ToolDeclaration {
+    name: string;
+    title: string;
+    description: string;
+    input: {
+        [k: string]: unknown;
+    };
+    output?: {
+        [k: string]: unknown;
+    };
+    mutating: boolean;
+    outbound: boolean;
+    timeoutMs?: number;
+    /**
+     * The view that renders the tool's result: a view surface placed
+     * `inline`.
+     */
+    view?: string;
+    icon?: ChatIconRole;
+    /**
+     * Who may call the tool. Absent, both.
+     *
+     * @minItems 1
+     */
+    visibility?: ToolVisibility[];
+}
+interface Capabilities {
+    tools?: string[];
+    skills?: PackagePath[];
+}
+interface AskDeclaration {
+    kind: string;
+    title: string;
+}
+interface FormatDeclaration {
+    id: string;
+    /**
+     * @minItems 1
+     */
+    extensions: string[];
+}
+interface Onboarding {
+    version: number;
+    /**
+     * @minItems 1
+     */
+    cards: OnboardingCard[];
+}
+interface OnboardingCard {
+    title: string;
+    text?: string;
+    image?: ServedPicture;
+    rows?: OnboardingRow[];
+    /**
+     * A model this computer's engine can pull, by the id its device row
+     * gives it.
+     */
+    download?: string;
+}
+interface OnboardingRow {
+    icon: ChatIconRole;
+    title: string;
+    text: string;
+}
+/**
+ * A right-click entry of the app's rail button: a call of one of the
+ * app's tools with these arguments, `{}` when absent. A result that names
+ * a view opens that view as a tab of the focused tile.
+ */
+interface QuickAction {
+    title: string;
+    tool: string;
+    args?: {
+        [k: string]: unknown;
+    };
+}
+/**
+ * The app's settings: a JSON Schema object of booleans, strings and
+ * numbers, which the platform stores and hands to the app's backend and
+ * views, and the groups the settings page draws them in. With `layout`,
+ * every setting sits in exactly one group; without it, the settings show
+ * in the order the schema declares them.
+ */
+interface SettingsDeclaration {
+    schema: SettingsSchema;
+    /**
+     * @minItems 1
+     */
+    layout?: SettingsGroup[];
+}
+interface SettingsSchema {
+    type: ObjectType;
+    properties: {
+        [k: string]: SettingDeclaration;
+    };
+}
+interface SettingsGroup {
+    title: string;
+    /**
+     * @minItems 1
+     */
+    items: SettingsItem[];
+}
+interface Mentions {
+    tool: string;
+}
+/**
+ * A remote MCP server, by its address.
+ */
+interface RemoteMcpServer {
+    url: string;
+}
+/**
+ * A JavaScript file in the package the platform runs in the app's
+ * environment, with the environment variables it reads, each a secret the
+ * person enters.
+ */
+interface BundledMcpServer {
+    entry: string;
+    env?: string[];
+}
+/**
+ * What `net.fetch` takes.
+ */
+interface FetchParams {
+    url: string;
+    method?: string;
+    headers?: {
+        [k: string]: string;
+    };
+    body?: string;
+}
+/**
+ * What `net.fetch` answers.
+ */
+interface FetchAnswer {
+    status: number;
+    headers: {
+        [k: string]: string;
+    };
+    body: string;
+}
+/**
+ * The body of `POST /models/complete` and of one model call of a turn.
+ */
+interface CompletionRequest {
+    messages: ChatMessage[];
+    tools?: ToolDefinition[];
+    /**
+     * JSON against this schema, sent to the runtime as its structured
+     * output request; a runtime without the feature refuses with its own
+     * reason.
+     */
+    format?: CompletionFormat;
+    sampling?: Sampling;
+    reasoning?: Reasoning;
+    /**
+     * Asks for the same answer to the same request as far as the runtime
+     * allows: a fixed seed, and on a Hearthscale Server the whole prompt
+     * read again rather than partly from an earlier request's cache.
+     */
+    repeatable?: true;
+}
+/**
+ * One message of a request, in the OpenAI v1 roles.
+ */
+interface ChatMessage {
+    role: ChatRole;
+    content: ChatContent;
+    toolCalls?: ToolCall[];
+    toolCallId?: string;
+}
+/**
+ * One tool as a model sees it.
+ */
+interface ToolDefinition {
+    name: string;
+    description: string;
+    /**
+     * JSON Schema for the arguments object.
+     */
+    parameters: {
+        [k: string]: unknown;
+    };
+}
+/**
+ * The structured output a request asks for.
+ */
+interface CompletionFormat {
+    name?: string;
+    schema: {
+        [k: string]: unknown;
+    };
+}
+/**
+ * What a conversation's requests have spent, by the log.
+ */
+interface SpentTokens {
+    tokens: number;
+    rounds: number;
+}
+/**
+ * An icon as a data URL per scheme.
+ */
+interface SchemedIcon {
+    light: string;
+    dark: string;
+}
+/**
+ * One folder or file an app's backend reaches, by the handle its channel
+ * names.
+ */
+interface Mount {
+    handle: string;
+    path: string;
+    mode: MountMode;
+}
+/**
+ * A project: one folder under its app's workspace and the instructions
+ * its sessions read.
+ */
+interface ProjectRecord {
+    id: string;
+    app: string;
+    name: string;
+    instructions: string;
+    rank: number;
+    createdAt: string;
+    folder: string;
+}
+/**
+ * A file opened in an app, by an address only the host resolves.
+ */
+interface OpenedFile {
+    name: string;
+    resourceUri: string;
+}
+/**
+ * One folder as `GET /fs/list` answers it.
+ */
+interface FsListing {
+    path: string;
+    /**
+     * The drive or volume the path sits on, where walking up ends.
+     */
+    root: string;
+    dirs: string[];
+    files: string[];
+}
+/**
+ * The head of one file as `GET /fs/read` answers it.
+ */
+interface FsRead {
+    path: string;
+    size: number;
+    binary: boolean;
+    text?: string;
+}
+/**
+ * What one repository answers about itself.
+ */
+interface VcsRepo {
+    root: string;
+    /**
+     * The checked-out branch, empty where HEAD is detached.
+     */
+    branch: string;
+}
+interface VcsRefs {
+    current: string;
+    branches: string[];
+}
+/**
+ * One scope's patch.
+ */
+interface VcsDiff {
+    patch: string;
+    /**
+     * The cap cut the patch; what came back is whole files up to the cut.
+     */
+    truncated: boolean;
+    /**
+     * How many changed files the patch leaves out because they lie in the
+     * deny-read set.
+     */
+    hidden: number;
+}
+/**
+ * One file whole, as a scope's new side holds it.
+ */
+interface VcsFile {
+    text: string;
+}
+/**
+ * One terminal as `POST /terminals` answers it and as its stream's first
+ * frame carries it.
+ */
+interface TerminalSnapshot {
+    id: string;
+    /**
+     * The app whose window the terminal was opened in.
+     */
+    app: string;
+    /**
+     * The folder the shell started in.
+     */
+    cwd: string;
+    /**
+     * The shell's own name: PowerShell, zsh, bash.
+     */
+    shell: string;
+    status: TerminalStatus;
+    /**
+     * The scrollback, capped at the line ring.
+     */
+    history: string;
+    exitCode: number | null;
+}
+/**
+ * One session as `GET /sessions` lists it: its record, its agent's display
+ * name, its own name else the app's, and the card its next turn runs on
+ * by the daemon's rule.
+ */
+interface Session {
+    id: string;
+    app: string;
+    appVersion: string;
+    agent: string;
+    project?: string;
+    startedBy?: PrincipalRef;
+    title: string;
+    preview: string;
+    /**
+     * The card the next turn uses, when a person chose one.
+     */
+    model?: string;
+    createdAt: string;
+    updatedAt: string;
+    status: SessionStatus;
+    stopReason?: StopReason;
+    leaf: string | null;
+    entries: number;
+    bytes: number;
+    pinned: boolean;
+    archived: boolean;
+    rank: number;
+    forkedFrom?: string;
+    spawnedBy?: string;
+    /**
+     * On a helper: the parent's `spawn_agent` call that started it.
+     */
+    spawnedByCall?: string;
+    authoritySession: string;
+    spent: SpentTokens;
+    roots: SessionRoot[];
+    lastTurn?: LastTurn;
+    /**
+     * The programs running now, each with the `exec` call that started
+     * it.
+     */
+    cells: SessionCell[];
+    /**
+     * The commands running in the background now, each with the `bash`
+     * call that started it.
+     */
+    processes: SessionProcess[];
+    agentName: string;
+    effective: EffectiveModel;
+}
+/**
+ * The turn a session ended last, and why.
+ */
+interface LastTurn {
+    id: string;
+    stopReason: StopReason;
+}
+/**
+ * `GET /vcs/diff`: one scope's patch of a repository.
+ */
+interface VcsDiffQuery {
+    root: string;
+    scope: VcsScope;
+    /**
+     * The ref a `branch` scope compares the current branch against.
+     */
+    base?: string;
+    /**
+     * Root-relative pathspecs the patch is narrowed to.
+     */
+    paths?: string[];
+}
+/**
+ * `GET /vcs/file`: one file whole, as a scope's new side holds it, which
+ * the diff panel's unmodified runs are read from: the working tree's copy
+ * for `working`, the index's for `staged` and `HEAD`'s for `branch`.
+ */
+interface VcsFileQuery {
+    root: string;
+    scope: VcsScope;
+    /**
+     * Relative to the repository's top, as the patch names it.
+     */
+    path: string;
+}
+/**
+ * What one job of each kind takes, by kind. Audio and images cross as
+ * assets.
+ */
+interface JobInputs {
+    image: ImageJobInput;
+    music: MusicJobInput;
+    speech: SpeechJobInput;
+    transcription: TranscriptionJobInput;
+    embedding: EmbeddingJobInput;
+}
+interface ImageJobInput {
+    prompt: string;
+    size?: string;
+}
+interface MusicJobInput {
+    prompt: string;
+    seconds: number;
+    lyrics?: string;
+}
+interface SpeechJobInput {
+    text: string;
+    voice?: string;
+}
+/**
+ * `audio` is an asset.
+ */
+interface TranscriptionJobInput {
+    audio: string;
+    language?: string;
+}
+interface EmbeddingJobInput {
+    texts: string[];
+}
+/**
+ * The executor's answer to a command: what the command answers the body,
+ * or the error it met.
+ */
+interface SurfaceResult {
+    id: string;
+    url?: string;
+    title?: string;
+    result?: unknown;
+    asset?: string;
+    shown?: boolean;
+    error?: string;
+}
+/**
+ * A path inside a mount, as the backend names files: the mount's handle
+ * and the path under it.
+ */
+interface MountPath {
+    root: string;
+    path: string;
+}
+/**
+ * What a tool body answers: content for the model and the view that
+ * renders the result.
+ */
+interface ToolAnswer {
+    content: Content[];
+    structured?: Structured;
+    /**
+     * Values for the view that renders the result, as MCP's result
+     * `_meta`; they never reach a model.
+     */
+    meta?: {
+        [k: string]: unknown;
+    };
+    view?: string;
+    /**
+     * The model tokens the body spent through `models.complete`, summed
+     * by the core.
+     */
+    usage?: Usage;
+}
+/**
+ * What a surface command answers a body: the page's address and title
+ * after the command, a script's value, a screenshot's asset, and whether
+ * the tab is in the conversation's panel, where the person sees it, which
+ * every answer but `close`'s carries.
+ */
+interface SurfaceAnswer {
+    url?: string;
+    title?: string;
+    result?: unknown;
+    asset?: string;
+    shown?: boolean;
+}
+/**
+ * One session as `sessions.list` lists it.
+ */
+interface SessionListing {
+    id: string;
+    app: string;
+    title: string;
+    createdAt: string;
+    updatedAt: string;
+}
+/**
+ * One session with its entries, as `sessions.open` answers it.
+ */
+interface OpenedSession {
+    id: string;
+    title: string;
+    entries: Entry[];
+}
+/**
+ * A conversation `sessions.create` starts: in this app, or in another app
+ * under the `sessions.create` grant, for a named agent and in a project.
+ */
+interface SessionCreate {
+    app?: string;
+    agent?: string;
+    project?: string;
+    title?: string;
+    message?: string;
+    /**
+     * A chat card `models.for` lists for the app.
+     */
+    model?: string;
+}
+/**
+ * A session's last turn: how it ended, its last reply, and the result its
+ * agent answered through `finish`.
+ */
+interface TurnOutcome {
+    turn: string;
+    stopReason: StopReason;
+    text: string;
+    result?: Structured;
+}
+/**
+ * One enabled app as `apps.list` lists it.
+ */
+interface AppListing {
+    id: string;
+    name: string;
+    description: string;
+    /**
+     * The icon's file in the app's package per colour scheme, which a page
+     * loads from `/apps/<id>/ui/<file>`; null when it has none.
+     */
+    icon: SchemedIcon | null;
+    agent: boolean;
+    capabilities: string[];
+}
+/**
+ * One chat card an app's sessions may run on, as `models.for` lists it.
+ */
+interface ModelListing {
+    id: string;
+    name: string;
+    provider: string;
+}
+/**
+ * One project as `projects.list` lists it.
+ */
+interface ProjectListing {
+    id: string;
+    name: string;
+    folder: string;
+}
+/**
+ * An app's own question to the person during a tool call: a choice, a
+ * sign-in, a handoff; `kind` is one the manifest's `asks` declares. It
+ * widens nothing.
+ */
+interface AppQuestion {
+    kind: string;
+    text: string;
+}
+/**
+ * The person's answer to an app's question.
+ */
+interface AppAnswer {
+    allow: boolean;
+    option?: string;
+}
+/**
+ * A durable entry in one of the app's own sessions, or a transient event
+ * for the app's views.
+ */
+interface AppEvent {
+    name: string;
+    session?: string;
+    data: unknown;
+    durable: boolean;
+    context?: string;
+}
+/**
+ * An OS notification an app asks for.
+ */
+interface AppNotice {
+    title: string;
+    body: string;
+    session?: string;
+}
+/**
+ * A sign-in to an online service of the app's own, with the app's own
+ * client registered at that service.
+ */
+interface OAuthLogin {
+    /**
+     * The authorization server's identifier, an https address without a
+     * query or a fragment; its metadata names the endpoints unless
+     * `endpoints` does.
+     */
+    issuer: string;
+    /**
+     * Absent when the server registers clients itself (RFC 7591).
+     */
+    clientId?: string;
+    /**
+     * For a server that demands one even from a desktop client.
+     */
+    clientSecret?: string;
+    scopes?: string[];
+    /**
+     * The RFC 8707 resource the token is for.
+     */
+    resource?: string;
+    endpoints?: OAuthEndpoints;
+    grant?: OAuthGrant;
+    /**
+     * The server's own fields on the authorization address, such as
+     * `access_type`.
+     */
+    params?: {
+        [k: string]: string;
+    };
+}
+/**
+ * The endpoints of an authorization server that publishes no metadata.
+ */
+interface OAuthEndpoints {
+    authorization?: string;
+    token: string;
+    device?: string;
+}
+
+/**
+ * The view bridge: what a view, an app's UI in a sandboxed frame, and its
+ * host say to each other beyond the MCP Apps standard the view speaks.
+ * Every method is a JSON-RPC request over the MCP Apps transport, and
+ * every result is an object, as that protocol requires.
+ *
+ * Where OpenAI's MCP extensions name a key or a method, the bridge uses
+ * that name, so a view written for ChatGPT runs unchanged; `hearthscale/*`
+ * names only what those extensions have no name for.
+ *
+ * The host fills the standard capabilities of `ui/initialize` as follows:
+ * `updateModelContext` and `message` take text, image, resource link and
+ * embedded resource blocks, and `updateModelContext` also structured
+ * content; `sampling` is offered when the app names `models` in `uses`,
+ * and answers on the card the app's chat runs on; `downloadFile` saves
+ * through the system's save dialog; `sandbox.permissions` holds the
+ * manifest's `permissions` (`clipboard-write` as `clipboardWrite`), and
+ * `sandbox.csp` the hosts of `environment.network` for connections,
+ * resources and frames alike. Under `experimental`, the keys
+ * `openai/modelContext`, `openai/message` and `openai/resource` each hold
+ * `{}`, `openai/files` holds `{}` when the app names `files.open` in
+ * `uses`, and `hearthscale` holds `HearthscaleHostCapability`. In the host
+ * context, `displayMode` and `availableDisplayModes` follow
+ * `MCP_DISPLAY_MODES` and the surface's placements, and
+ * `containerDimensions` is the size of the view's frame, `width` and
+ * `height` in a tab or a modal and `width` and `maxHeight` under a
+ * result, sent again on each change.
+ *
+ * Every block a view sends with `ui/update-model-context` shows as a
+ * removable chip above the composer of each chat on screen in the same
+ * window, and rides the next message sent there as a `context` part; no
+ * block reaches a model without a chip, whatever its
+ * `annotations.audience` says.
+ */
+
+/** The extensions a view calls as `hearthscale/<extension>/…`, each only
+ *  when its app names it in `uses`: the app's own conversations and
+ *  projects, its store, its backend's events, its folders, its models,
+ *  its jobs, its terminals, opening a surface, and its rooms. Opening a
+ *  file is OpenAI's `openai/files/open`, which `files.open` in `uses`
+ *  gates. */
+declare const VIEW_EXTENSIONS: readonly ["sessions", "store", "events", "roots", "models", "jobs", "terminals", "surfaces.open", "peers"];
+type ViewExtension = (typeof VIEW_EXTENSIONS)[number];
+/** `hostCapabilities.experimental.hearthscale`: the extensions this view
+ *  may call. The `hearthscale/ui/*` methods are offered to every view. */
+interface HearthscaleHostCapability {
+    extensions: ViewExtension[];
+}
+/** The keys the host adds to the MCP Apps host context, set when the view
+ *  starts and changed by `ui/notifications/host-context-changed`. */
+interface ViewHostContext {
+    /** The look the host wears, as one style sheet of `@layer` bodies. */
+    'hearthscale/appearance': string;
+    /** The app's settings; absent for an app that declares none. */
+    'hearthscale/settings'?: SettingValues;
+    /** What the view's chips hold from its last `ui/update-model-context`;
+     *  null once no chip of it is left. */
+    'openai/modelContext': ModelContextState | null;
+    /** The state the view last saved with `hearthscale/ui/set-widget-state`,
+     *  given back when the host loads a discarded view again; null before
+     *  the first save. */
+    'hearthscale/widgetState': unknown;
+    /** The app-relative address, with its query, that a deep link or
+     *  `hearthscale/surfaces/open` opened the surface on; absent for a
+     *  surface opened without one. The link is
+     *  `hearthscale://open?app=<id>&surface=<id>&path=<address>`, the
+     *  address percent-encoded and starting with `/`. */
+    'openai/deepLink'?: {
+        url: string;
+    };
+}
+/** The `_meta` of a text or image block of `ui/update-model-context` or
+ *  `ui/message`. `openai/title` is the label of the block's chip: in a
+ *  message, a titled block becomes a chip and an untitled text block
+ *  becomes the message's text. */
+interface ContentBlockMeta {
+    'openai/title'?: string;
+}
+/** `_meta['openai/modelContext']` on the result of
+ *  `ui/update-model-context`. Each update replaces the view's last. */
+interface ModelContextAnswer {
+    updateId: string;
+}
+/** `_meta['openai/message']` on a `ui/message` request. */
+interface MessageOptions {
+    /** `active`, also when absent: the conversation whose transcript shows
+     *  the view; for a view that fills a tab, the conversation of its app
+     *  that its first `chat` or `composer` slot shows, made there by the
+     *  message when the slot shows a new one. `new`: a new conversation of
+     *  that app, which the slot then shows. A view that fills a tab and
+     *  shows no such slot sends no message, and drafts its words in the
+     *  composer of the conversation on screen. */
+    target?: 'active' | 'new';
+    /** True, also when absent, sends the message; false leaves it in the
+     *  composer for the person to send. */
+    send?: boolean;
+}
+/** The tool input a view gets when its surface opens a file. */
+interface FileInput {
+    file: OpenedFile;
+}
+/** `_meta['openai/resource']` on a `resources/read` of an opened file:
+ *  whether its bytes come as text or as a base64 blob; absent, by the
+ *  file's kind. The host answers the read, the subscription and its
+ *  `notifications/resources/updated` itself. */
+interface ResourceReadOptions {
+    representation: 'text' | 'blob';
+}
+/** `_meta['openai/resource']` on the content a read of an opened file
+ *  answers: the version read, and whether `openai/resources/write` may
+ *  replace it. */
+interface ResourceVersion {
+    etag: string;
+    writable: boolean;
+}
+/** `_meta['openai/resource']` the host adds to a tool call a view showing
+ *  an opened file makes to its app's MCP server: the file's absolute path
+ *  on the platform's machine, which the view never sees. */
+interface ResourcePath {
+    path: string;
+}
+/** Replaces an opened file's bytes, when the version is still `ifMatch`
+ *  or `ifMatch` is absent. */
+type ResourceWrite = {
+    uri: string;
+    ifMatch?: string;
+} & ({
+    text: string;
+}
+/** Base64. */
+ | {
+    blob: string;
+});
+/** What the shell draws in a rectangle a view reserves: `chat`, the
+ *  transcript and the composer; `composer`, the composer alone; `cards`,
+ *  the requests of the view's app alone, for a view that has no composer;
+ *  `terminal`, the person's own live shell, which the window opens with
+ *  its own authority and the view never reads or types into; `web`, the
+ *  tab's web page on the app's own partition, which reaches only the hosts
+ *  the app declares, and which the view drives with `hearthscale/web/*`.
+ *  A view reserves at most one `web` slot. */
+declare const HOST_SLOT_KINDS: readonly ["chat", "composer", "cards", "terminal", "web"];
+type HostSlotKind = (typeof HOST_SLOT_KINDS)[number];
+/** The distances, in the view's CSS pixels, from each edge of the view to
+ *  the same edge of a slot. The shell anchors the slot by them in its own
+ *  layout, so a slot follows a change of its tile's size in the same frame. */
+interface SlotInsets {
+    left: number;
+    top: number;
+    right: number;
+    bottom: number;
+}
+/** One rectangle a view reserves for the shell's trusted parts. */
+interface HostSlot {
+    /** The view's own name for the slot, unique among its slots. */
+    id: string;
+    kind: HostSlotKind;
+    /** On a `chat` or `composer` slot: the conversation of the view's app
+     *  it shows. Null or absent, it shows a new conversation, which the
+     *  first message creates in `project` when one is named, and
+     *  `hearthscale/ui/slot-session` tells the view its id. */
+    session?: string | null;
+    project?: string;
+    /** On a `terminal` slot: the folder its shell starts in, inside a folder
+     *  the person gave the view's app. The slot's id, letters, digits, `-`
+     *  and `_`, names the shell in the view's tab: the same id takes up the
+     *  shell it opened while the platform holds it, and the shell ends with
+     *  the tab. */
+    cwd?: string;
+    insets: SlotInsets;
+}
+/** The notifications the host sends every view that reserved a slot. */
+type HostSlotNotification = 
+/** The height the composer or the cards in the slot take now. They lie
+ *  on the slot's bottom edge and grow upward, past the slot's top edge
+ *  when they need to; the view may make room for them. */
+{
+    method: 'hearthscale/ui/slot-size';
+    params: {
+        id: string;
+        height: number;
+    };
+}
+/** The chat or the composer in the slot shows another conversation of
+ *  the app: the one its first message created, a fork, or a helper. The
+ *  shell shows it at once; the view's next report of the slot names it. */
+ | {
+    method: 'hearthscale/ui/slot-session';
+    params: {
+        id: string;
+        session: string;
+    };
+}
+/** The tab's web page changed: its address, title, icon, load, history
+ *  or zoom. Sent once when the view starts and at each change. */
+ | {
+    method: 'hearthscale/web/page';
+    params: WebPageState;
+}
+/** The matches of the last `hearthscale/web/find`. */
+ | {
+    method: 'hearthscale/web/found';
+    params: {
+        active: number;
+        total: number;
+    };
+}
+/** A download of the app's pages started or moved; each view tab of the
+ *  app hears it, and `mine` is set for the tab whose page started it. */
+ | {
+    method: 'hearthscale/web/download';
+    params: WebDownload & {
+        mine: boolean;
+    };
+}
+/** The tab's page sent a password with a sign-in form, which the host
+ *  holds for ten minutes and keeps in the system's keychain once the
+ *  view asks with `hearthscale/web/password-save`. */
+ | {
+    method: 'hearthscale/web/password';
+    params: {
+        id: string;
+    } & WebLogin;
+};
+/** The web page of a view's tab as the view hears it. The page lives as
+ *  long as the tab, whether or not the view reserves its `web` slot, and
+ *  it lies over the slot unless the view covers it. */
+type WebPageState = {
+    /** The address the page shows; null for a tab that has loaded none. */
+    url: string | null;
+    title: string;
+    /** The page's own icon, an address; absent while it names none. */
+    icon?: string;
+    loading: boolean;
+    canGoBack: boolean;
+    canGoForward: boolean;
+    /** The page's zoom factor, 1 at 100 %. */
+    zoom: number;
+};
+type Empty = Record<never, never>;
+/** The host methods beyond MCP Apps that every view may call. */
+interface ViewHostMethods {
+    /** Reserves rectangles of a view that fills a tab, each for a part the
+     *  shell draws and answers there: the chat, the composer or the cards.
+     *  The list replaces the last one; an empty list gives every rectangle
+     *  back, and a new document of the view starts with none. A slot is cut
+     *  to the view. A slot below `SLOT_MIN_WIDTH` or `SLOT_MIN_HEIGHT`, or
+     *  one that names a conversation of another app, is not drawn. The view
+     *  never receives what the person types there. Requests of the app dock
+     *  on the composer of its slot or in its `cards` slot, and a press on a
+     *  card counts only once the slot has kept its place for a moment. A
+     *  view in a transcript reserves none. */
+    'hearthscale/ui/slots': {
+        params: {
+            slots: HostSlot[];
+        };
+        result: Empty;
+    };
+    /** Gives the keyboard focus to the composer of a `chat` or `composer`
+     *  slot, right after the person's own click or key press in the view. */
+    'hearthscale/ui/focus-slot': {
+        params: {
+            id: string;
+        };
+        result: Empty;
+    };
+    /** Names the tab a view fills, in its lane and its hover card: `title`
+     *  its title, at most `TAB_TITLE_CHARS` characters, and `icon` its mark,
+     *  a picture as a `data:` address of at most `TAB_ICON_CHARS`
+     *  characters. A field left out stays as it is; null gives back the
+     *  tab's own: the surface's title or its conversation's, and the
+     *  surface's mark or its app's. The tab keeps its name through a
+     *  restart. A result's view names the tab it moves into, whenever it
+     *  moves. */
+    'hearthscale/ui/set-tab': {
+        params: {
+            title?: string | null;
+            icon?: string | null;
+        };
+        result: Empty;
+    };
+    /** Shows a view surface of the same app that its manifest places in
+     *  `modal` over the asking view's tile, on a click inside the view. The
+     *  tile dims under the modal, and the modal's view fills the tile on a
+     *  clear plate and draws its own box. It takes `input` as its tool
+     *  input, `{}` when absent, and the tool its surface names is called
+     *  with it. One modal per tile: another replaces it. The app's
+     *  requests draw above the modal. */
+    'hearthscale/ui/open-modal': {
+        params: {
+            surface: string;
+            input?: Record<string, unknown>;
+        };
+        result: Empty;
+    };
+    /** Closes the modal the calling view is in. */
+    'hearthscale/ui/close-modal': {
+        params: Empty;
+        result: Empty;
+    };
+    /** Keeps a JSON value for this view's tab, which the host gives back in
+     *  `hearthscale/widgetState`; it never reaches a model. The value takes
+     *  at most 64 KiB as JSON text. */
+    'hearthscale/ui/set-widget-state': {
+        params: {
+            state: unknown;
+        };
+        result: Empty;
+    };
+    /** Lets the person pick files with the system's dialog, on a click
+     *  inside the view and at every level, filtered by extension (`.png`),
+     *  media type (`image/png`) or a family of types (`image/*`); the files
+     *  read through `resources/read`, as files the app opened. A cancelled
+     *  dialog answers none. */
+    'hearthscale/ui/select-files': {
+        params: {
+            accept?: string[];
+            multiple?: boolean;
+        };
+        result: {
+            files: OpenedFile[];
+        };
+    };
+    /** Stores `blob`, base64 of at most 64 MiB, as an
+     *  asset of the conversation the view belongs to, else of its app; the
+     *  view reads it back as `hearthscale-asset://<asset>` and hands `asset`
+     *  to its tools. */
+    'hearthscale/ui/upload-file': {
+        params: {
+            name: string;
+            mediaType: string;
+            blob: string;
+        };
+        result: {
+            asset: string;
+        };
+    };
+    'openai/resources/write': {
+        params: ResourceWrite;
+        result: ResourceWriteResult;
+    };
+    /** Loads an `https:` or `http:` address in the tab's web page, which
+     *  starts with the first one. A host the app does not declare in
+     *  `environment.network` is refused before it leaves the machine. */
+    'hearthscale/web/navigate': {
+        params: {
+            url: string;
+        };
+        result: Empty;
+    };
+    /** Steps the page back or forward in its history, loads it again, or
+     *  stops its load. */
+    'hearthscale/web/go': {
+        params: {
+            to: 'back' | 'forward' | 'reload' | 'stop';
+        };
+        result: Empty;
+    };
+    /** Finds text in the page, the next match with `next`, backwards
+     *  unless `forward`; empty text ends the find and clears its marks. The
+     *  matches arrive as `hearthscale/web/found`. */
+    'hearthscale/web/find': {
+        params: {
+            text: string;
+            forward?: boolean;
+            next?: boolean;
+        };
+        result: Empty;
+    };
+    /** Sets the page's zoom factor, between 0.25 and 5. */
+    'hearthscale/web/zoom': {
+        params: {
+            factor: number;
+        };
+        result: Empty;
+    };
+    /** Opens the system's print dialog for the page; needs a click. */
+    'hearthscale/web/print': {
+        params: Empty;
+        result: Empty;
+    };
+    /** A picture of the page as it shows, a PNG in base64. */
+    'hearthscale/web/capture': {
+        params: Empty;
+        result: {
+            png: string;
+        };
+    };
+    /** Lays the page under the view while `covered`, so a menu or a mark the
+     *  view draws over the slot shows above it; the page shows through
+     *  where the view is transparent and takes no pointer. Uncovered, the
+     *  page lies over its slot. */
+    'hearthscale/web/cover': {
+        params: {
+            covered: boolean;
+        };
+        result: Empty;
+    };
+    /** Opens a new tab of the calling view's surface in its tile, after its
+     *  tab, with its page on `url` when one is given, and its view starting
+     *  from `state` as the state it saved; needs a click. */
+    'hearthscale/web/open-tab': {
+        params: {
+            url?: string;
+            state?: unknown;
+        };
+        result: Empty;
+    };
+    /** Draws the page as a device's screen draws it, or as the slot's own
+     *  size with null. */
+    'hearthscale/web/device': {
+        params: {
+            device: WebDevice | null;
+        };
+        result: Empty;
+    };
+    /** The element of the page at a point of the slot, in the view's CSS
+     *  pixels from the slot's top left; null where the page shows none. */
+    'hearthscale/web/inspect': {
+        params: {
+            x: number;
+            y: number;
+        };
+        result: {
+            element: WebElement | null;
+        };
+    };
+    /** Clears what the app's pages keep: their cookies and site storage,
+     *  and their cached files; needs a click. */
+    'hearthscale/web/clear': {
+        params: {
+            cookies: boolean;
+            cache: boolean;
+        };
+        result: Empty;
+    };
+    /** Whether a download of the app's pages asks where to save it, with
+     *  the system's dialog, or goes to the system's downloads folder. */
+    'hearthscale/web/downloads': {
+        params: {
+            ask: boolean;
+        };
+        result: Empty;
+    };
+    /** The origins and accounts the system's keychain keeps passwords of
+     *  the app's pages for. No view reads a password: the host fills a
+     *  sign-in form of a page with the password of the page's own origin
+     *  when the person reaches for one of its fields. */
+    'hearthscale/web/passwords': {
+        params: Empty;
+        result: {
+            logins: WebLogin[];
+        };
+    };
+    /** Keeps a password a page sent in the system's keychain; needs a
+     *  click. */
+    'hearthscale/web/password-save': {
+        params: {
+            id: string;
+        };
+        result: Empty;
+    };
+    /** Removes a kept password; needs a click. */
+    'hearthscale/web/password-remove': {
+        params: WebLogin;
+        result: Empty;
+    };
+    /** Keeps the passwords of a passwords export file (a CSV with the
+     *  columns url, username and password, as Chrome writes it) that the
+     *  person picks with the system's dialog; answers how many, or null
+     *  for a cancelled pick. Needs a click. */
+    'hearthscale/web/passwords-import': {
+        params: Empty;
+        result: {
+            count: number | null;
+        };
+    };
+    /** Whether Hearthscale blocks ads in the person's browser's pages; null
+     *  for an app that is not the person's browser. */
+    'hearthscale/web/ad-blocking': {
+        params: Empty;
+        result: {
+            enabled: boolean | null;
+        };
+    };
+    /** Turns ad blocking in the person's browser on or off; needs a click. */
+    'hearthscale/web/set-ad-blocking': {
+        params: {
+            enabled: boolean;
+        };
+        result: Empty;
+    };
+    /** Whether the person's browser draws its pages dark; null for an app
+     *  that is not the person's browser. */
+    'hearthscale/web/dark-pages': {
+        params: Empty;
+        result: {
+            enabled: boolean | null;
+        };
+    };
+    /** Turns dark pages in the person's browser on or off; needs a click. */
+    'hearthscale/web/set-dark-pages': {
+        params: {
+            enabled: boolean;
+        };
+        result: Empty;
+    };
+    /** Opens a finished download in the system's app for its kind, shows it
+     *  in its folder, or cancels one under way; needs a click. */
+    'hearthscale/web/download': {
+        params: {
+            id: string;
+            action: 'open' | 'show' | 'cancel';
+        };
+        result: Empty;
+    };
+}
+/** A screen a page is drawn at: its size in CSS pixels, its device pixel
+ *  ratio, and whether it is a phone's or a tablet's, which draws the page
+ *  with a mobile viewport. */
+type WebDevice = {
+    width: number;
+    height: number;
+    scale: number;
+    mobile: boolean;
+};
+/** An element of a page as the person points at it. */
+type WebElement = {
+    /** The tag, with its id and classes, as a CSS selector names it. */
+    selector: string;
+    /** Its text, its label, or its address, cut to a line. */
+    text: string;
+    /** Its box in the slot, in the view's CSS pixels. */
+    box: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+};
+/** An account a page signs in with: its page's origin and its name. */
+type WebLogin = {
+    origin: string;
+    username: string;
+};
+/** A download of one of the app's pages, as its tab's view hears it. */
+type WebDownload = {
+    id: string;
+    url: string;
+    /** The file's name as it is saved. */
+    name: string;
+    state: 'progressing' | 'completed' | 'cancelled' | 'interrupted';
+    received: number;
+    /** The size in bytes; 0 while it is unknown. */
+    total: number;
+};
+/** The methods gated by `uses`, each with the entry its app must name
+ *  before the host answers it. A view acts as its app: what it reads and
+ *  changes is its app's own, a terminal line it types goes at its app's
+ *  level as one a page types, and the platform's log names the app. An
+ *  act that sends the person's words, deletes what cannot come back,
+ *  opens something on the person's screen or puts the app in a room runs
+ *  only on a click inside the view. */
+interface ViewExtensionMethods {
+    /** The app's own conversations, newest first; archived ones only when
+     *  asked. Without `spawnedBy` the list holds the conversations no helper
+     *  call started; with it, the helpers that conversation started. */
+    'hearthscale/sessions/list': {
+        uses: 'sessions';
+        params: {
+            archived?: boolean;
+            spawnedBy?: string;
+        };
+        result: {
+            sessions: Session[];
+        };
+    };
+    /** A new conversation of the app, with `agent` or the app's own agent;
+     *  `message`, sent as its first message, needs a click. */
+    'hearthscale/sessions/create': {
+        uses: 'sessions';
+        params: {
+            agent?: string;
+            project?: string;
+            title?: string;
+            message?: string;
+        };
+        result: {
+            session: Session;
+        };
+    };
+    /** Renames a conversation, files it in a project or none, pins,
+     *  archives or orders it. */
+    'hearthscale/sessions/update': {
+        uses: 'sessions';
+        params: {
+            id: string;
+            title?: string;
+            project?: string | null;
+            pinned?: boolean;
+            archived?: boolean;
+            rank?: number;
+        };
+        result: {
+            session: Session;
+        };
+    };
+    /** Deletes a conversation and the helpers it started; needs a click. */
+    'hearthscale/sessions/delete': {
+        uses: 'sessions';
+        params: {
+            id: string;
+        };
+        result: Empty;
+    };
+    /** A copy of a conversation from its current leaf, as a new
+     *  conversation of the app. */
+    'hearthscale/sessions/fork': {
+        uses: 'sessions';
+        params: {
+            id: string;
+        };
+        result: {
+            session: Session;
+        };
+    };
+    /** Sends the person's words as the conversation's next message; needs
+     *  a click. */
+    'hearthscale/sessions/send': {
+        uses: 'sessions';
+        params: {
+            id: string;
+            text: string;
+        };
+        result: Empty;
+    };
+    'hearthscale/sessions/entries': {
+        uses: 'sessions';
+        params: {
+            id: string;
+        };
+        result: {
+            entries: Entry[];
+        };
+    };
+    'hearthscale/sessions/projects/list': {
+        uses: 'sessions';
+        params: Empty;
+        result: {
+            projects: ProjectRecord[];
+        };
+    };
+    'hearthscale/sessions/projects/create': {
+        uses: 'sessions';
+        params: {
+            name: string;
+        };
+        result: {
+            project: ProjectRecord;
+        };
+    };
+    'hearthscale/sessions/projects/update': {
+        uses: 'sessions';
+        params: {
+            id: string;
+            name?: string;
+            instructions?: string;
+            rank?: number;
+        };
+        result: {
+            project: ProjectRecord;
+        };
+    };
+    /** Deletes a project; its conversations stay, filed under none. Needs a
+     *  click. */
+    'hearthscale/sessions/projects/delete': {
+        uses: 'sessions';
+        params: {
+            id: string;
+        };
+        result: Empty;
+    };
+    /** The store the app's backend shares; `value` is null for a key that
+     *  holds nothing. */
+    'hearthscale/store/get': {
+        uses: 'store';
+        params: {
+            key: string;
+        };
+        result: {
+            value: unknown;
+        };
+    };
+    'hearthscale/store/set': {
+        uses: 'store';
+        params: {
+            key: string;
+            value: unknown;
+        };
+        result: Empty;
+    };
+    'hearthscale/store/delete': {
+        uses: 'store';
+        params: {
+            key: string;
+        };
+        result: Empty;
+    };
+    'hearthscale/roots/list': {
+        uses: 'roots';
+        params: Empty;
+        result: {
+            mounts: Mount[];
+        };
+    };
+    /** Opens the system's picker right after the person's own click or key
+     *  press; the pick becomes a grant and a mount. */
+    'hearthscale/roots/request': {
+        uses: 'roots';
+        params: {
+            purpose: string;
+            shape: 'folder' | 'file';
+            mode: 'read' | 'read-write';
+        };
+        result: {
+            mount: Mount | null;
+        };
+    };
+    /** A folder's folders and files by name, hidden ones left out. Every
+     *  path of `hearthscale/fs/*` and `hearthscale/vcs/*` is absolute on the
+     *  platform's machine and lies inside a folder or file the person gave
+     *  the app; one outside, or in a folder that holds credentials, is
+     *  refused in words. Each reads and never writes. */
+    'hearthscale/fs/list': {
+        uses: 'roots';
+        params: {
+            path: string;
+        };
+        result: FsListing;
+    };
+    /** A file's size, and its head as text unless it is binary. */
+    'hearthscale/fs/read': {
+        uses: 'roots';
+        params: {
+            path: string;
+        };
+        result: FsRead;
+    };
+    /** A whole file of at most 64 MiB, in base64, with the media type of
+     *  its extension. */
+    'hearthscale/fs/raw': {
+        uses: 'roots';
+        params: {
+            path: string;
+        };
+        result: {
+            data: string;
+            mediaType: string;
+        };
+    };
+    /** The system's icon of a file's kind, or of a folder when `folder` is
+     *  set, as a PNG `data:` address; null where the system draws none. */
+    'hearthscale/fs/icon': {
+        uses: 'roots';
+        params: {
+            path: string;
+            folder?: boolean;
+        };
+        result: {
+            icon: string | null;
+        };
+    };
+    /** The repository a folder belongs to and its branch, or null where it
+     *  belongs to none. A repository that reaches past what the person gave
+     *  the app is refused, because `git` reads all of it. */
+    'hearthscale/vcs/repo': {
+        uses: 'roots';
+        params: {
+            path: string;
+        };
+        result: {
+            repo: VcsRepo | null;
+        };
+    };
+    /** The branches a comparison may use, and the one checked out. */
+    'hearthscale/vcs/refs': {
+        uses: 'roots';
+        params: {
+            root: string;
+        };
+        result: VcsRefs;
+    };
+    /** One scope's patch. */
+    'hearthscale/vcs/diff': {
+        uses: 'roots';
+        params: VcsDiffQuery;
+        result: VcsDiff;
+    };
+    /** One file whole, as the scope's new side holds it. */
+    'hearthscale/vcs/file': {
+        uses: 'roots';
+        params: VcsFileQuery;
+        result: VcsFile;
+    };
+    /** One streaming completion on the app's chat card or the chat role;
+     *  the frames arrive as `hearthscale/models/delta` with `stream`, and
+     *  the call answers once the stream has ended. */
+    'hearthscale/models/complete': {
+        uses: 'models';
+        params: {
+            stream: string;
+            request: CompletionRequest;
+        };
+        result: Empty;
+    };
+    'hearthscale/models/cancel': {
+        uses: 'models';
+        params: {
+            stream: string;
+        };
+        result: Empty;
+    };
+    'hearthscale/jobs/submit': {
+        uses: 'jobs';
+        params: {
+            kind: JobKind;
+            input: JobInput;
+        };
+        result: {
+            job: Job;
+        };
+    };
+    'hearthscale/jobs/get': {
+        uses: 'jobs';
+        params: {
+            id: string;
+        };
+        result: {
+            job: Job;
+        };
+    };
+    'hearthscale/jobs/cancel': {
+        uses: 'jobs';
+        params: {
+            id: string;
+        };
+        result: {
+            job: Job;
+        };
+    };
+    /** Opens the person's own shell in a folder, at the app's level as a
+     *  page opens one, or takes up the one this window holds under the same
+     *  id; its snapshot and output arrive as `hearthscale/terminals/frame`.
+     *  The id is the view's own. Each line the view writes goes at the app's
+     *  level before it reaches the shell. */
+    'hearthscale/terminals/open': {
+        uses: 'terminals';
+        params: {
+            id: string;
+            cwd: string;
+            cols: number;
+            rows: number;
+        };
+        result: {
+            terminal: TerminalSnapshot;
+        };
+    };
+    'hearthscale/terminals/write': {
+        uses: 'terminals';
+        params: {
+            id: string;
+            data: string;
+        };
+        result: Empty;
+    };
+    'hearthscale/terminals/resize': {
+        uses: 'terminals';
+        params: {
+            id: string;
+            cols: number;
+            rows: number;
+        };
+        result: Empty;
+    };
+    'hearthscale/terminals/close': {
+        uses: 'terminals';
+        params: {
+            id: string;
+        };
+        result: Empty;
+    };
+    /** Opens a file by its absolute path on the platform's machine in the
+     *  surface that opens its extension, else in the system's own app when
+     *  the system shows its kind without running it; and shows a folder of
+     *  the app's own, one the person gave it, its data folder or a folder of
+     *  one of its projects, in the system's file manager. Needs a click. */
+    'openai/files/open': {
+        uses: 'files.open';
+        params: {
+            path: string;
+        };
+        result: Empty;
+    };
+    /** Opens a surface of this app, or of `app`, that its manifest places
+     *  in the rail or a tab, beside the view's tile; `session` is a
+     *  conversation of that app a chat opens on, `path` the address a view
+     *  opens on, as a deep link gives it. With `session` and no `surface`,
+     *  the conversation opens in its own app, as a notification's click
+     *  opens it; `app`, when given, must be that app. Needs a click. */
+    'hearthscale/surfaces/open': {
+        uses: 'surfaces.open';
+        params: {
+            app?: string;
+            surface?: string;
+            session?: string;
+            path?: string;
+        };
+        result: Empty;
+    };
+    /** The rooms the app is in. */
+    'hearthscale/peers/rooms': {
+        uses: 'peers';
+        params: Empty;
+        result: {
+            rooms: Room[];
+        };
+    };
+    /** Opens a new room of the app, whose ticket the view shows the person
+     *  to pass on. Needs a click. */
+    'hearthscale/peers/create': {
+        uses: 'peers';
+        params: Empty;
+        result: {
+            room: Room;
+        };
+    };
+    /** Asks the person for the ticket of a room in a sheet the host draws,
+     *  at every level, and joins that room; null when the person cancels.
+     *  The view never names the ticket. Needs a click. */
+    'hearthscale/peers/join': {
+        uses: 'peers';
+        params: Empty;
+        result: {
+            room: Room | null;
+        };
+    };
+    /** Sends `data`, at most 64 KiB as JSON, to every other
+     *  member of a room of the app; each member's app hears it as
+     *  `hearthscale/peers/message`, its views and its backend alike. */
+    'hearthscale/peers/send': {
+        uses: 'peers';
+        params: {
+            room: string;
+            data: unknown;
+        };
+        result: Empty;
+    };
+    /** Takes the app out of a room; a room it opened ends for every member. */
+    'hearthscale/peers/leave': {
+        uses: 'peers';
+        params: {
+            room: string;
+        };
+        result: Empty;
+    };
+}
+type ViewExtensionMethod = keyof ViewExtensionMethods;
+/** The notifications the host sends a view, each only to a view whose app
+ *  names the extension in `uses`: a conversation of the app changed or
+ *  went, a project of any app changed, the app's backend emitted an
+ *  event, a completion or a terminal of the view moved, a job of the app
+ *  moved, a room of the app changed, ended or carried a message. */
+type ViewExtensionNotification = {
+    method: 'hearthscale/sessions/changed';
+    params: {
+        session: string;
+    };
+} | {
+    method: 'hearthscale/sessions/deleted';
+    params: {
+        id: string;
+    };
+} | {
+    method: 'hearthscale/sessions/projects/changed';
+    params: Empty;
+}
+/** A transient event the app's backend emitted. */
+ | {
+    method: 'hearthscale/events/event';
+    params: {
+        name: string;
+        session?: string;
+        data: unknown;
+    };
+} | {
+    method: 'hearthscale/models/delta';
+    params: {
+        stream: string;
+        delta: CompletionDelta;
+    };
+} | {
+    method: 'hearthscale/jobs/progress';
+    params: {
+        job: Job;
+    };
+} | {
+    method: 'hearthscale/terminals/frame';
+    params: {
+        id: string;
+        frame: TerminalFrame;
+    };
+}
+/** The app entered a room, or a member came to it or left it. */
+ | {
+    method: 'hearthscale/peers/changed';
+    params: {
+        room: Room;
+    };
+}
+/** The app is out of a room. */
+ | {
+    method: 'hearthscale/peers/ended';
+    params: {
+        room: string;
+    };
+} | {
+    method: 'hearthscale/peers/message';
+    params: {
+        room: string;
+        from: string;
+        data: unknown;
+    };
+};
+
+/**
+ * The types a view imports: the methods every view may call
+ * (`ViewHostMethods`), the `hearthscale/*` extensions and
+ * `openai/files/open`, which it calls through its MCP Apps `App`, each
+ * answered only when its app names the method's entry in `uses`, the
+ * notifications the host sends it, the keys the host adds to the host
+ * context, the `_meta` of the standard messages, and the tool input of a
+ * view that opens a file (`FileInput`). The host lists what
+ * the view may call in `getHostCapabilities().experimental.hearthscale`.
+ */
+
+/** One extension call, typed by its method: the request's params in, its
+ *  result out. A refusal rejects with the host's words. */
+type ViewExtensionCall = <M extends ViewExtensionMethod>(method: M, params: ViewExtensionMethods[M]['params']) => Promise<ViewExtensionMethods[M]['result']>;
+
+/**
+ * `@hearthscale/app`: the types an app's backend and its views import,
+ * and the type of its manifest, `app.json` (`Manifest`). The
+ * running implementation lives in the app host, which serves this import
+ * from itself, so an app bundles nothing of the platform. Everything here
+ * is wire-shaped: every method is asynchronous, every value is JSON, files
+ * are handles inside mounts, and no callable crosses to the core.
+ */
+
+/** A relayed TCP or TLS stream. Bytes have no message boundaries; the
+ *  protocol on top is the app's. */
+interface Connection {
+    readonly id: string;
+    readonly state: 'plain' | 'tls';
+    write(bytes: Uint8Array | string): Promise<void>;
+    /** Upgrades the same socket to TLS after the app's protocol exchange. */
+    startTls(): Promise<void>;
+    close(): Promise<void>;
+    on(event: 'data', fn: (bytes: Uint8Array) => void): () => void;
+    on(event: 'end' | 'closed', fn: () => void): () => void;
+    on(event: 'error', fn: (error: {
+        code: string;
+        message: string;
+    }) => void): () => void;
+}
+/** A sandboxed run of one program in the app's environment. */
+interface Run {
+    readonly id: string;
+    wait(): Promise<{
+        exitCode: number;
+        output: string;
+    }>;
+    cancel(): Promise<void>;
+    on(event: 'output', fn: (output: string) => void): () => void;
+}
+/** What a backend reaches. A namespace the manifest's `uses` does not
+ *  name is absent from this object. */
+interface AppContext {
+    readonly app: {
+        id: string;
+        version: string;
+    };
+    readonly api: number;
+    /** The folders the host reaches, by handle. */
+    readonly mounts: Mount[];
+    /** Aborts when the host is disposed. */
+    readonly signal: AbortSignal;
+    log(level: 'debug' | 'info' | 'warn' | 'error', message: string): Promise<void>;
+    roots?: {
+        list(): Promise<Mount[]>;
+        /** Raises the folder card; the person's pick becomes a mount, which
+         *  the request answers. The host restarts with it once its calls and
+         *  folder requests in flight have ended, so the mount works from the
+         *  next call; asked outside any call, the answer comes first. */
+        request(purpose: string, shape: 'folder' | 'file'): Promise<Mount | null>;
+    };
+    fs?: {
+        read(path: MountPath, options?: {
+            offset?: number;
+            limit?: number;
+        }): Promise<string>;
+        list(path: MountPath): Promise<{
+            dirs: string[];
+            files: string[];
+        }>;
+        write(path: MountPath, text: string): Promise<void>;
+        edit(path: MountPath, oldText: string, newText: string): Promise<void>;
+        /** Copies an asset's bytes to a path inside a read-write mount. */
+        export(asset: string, path: MountPath): Promise<void>;
+    };
+    assets: {
+        get(id: string, range?: {
+            offset: number;
+            length: number;
+        }): Promise<{
+            bytes: Uint8Array;
+            mediaType: string;
+        }>;
+        put(bytes: Uint8Array | string, mediaType: string, name?: string): Promise<string>;
+        /** Copies a file from a mount into the store, in the core. */
+        import(path: MountPath, mediaType: string): Promise<string>;
+        release(id: string): Promise<void>;
+    };
+    net?: {
+        fetch(params: FetchParams): Promise<FetchAnswer>;
+        connect(host: string, port: number, tls: boolean): Promise<Connection>;
+    };
+    exec?: {
+        run(argv: string[], cwd: MountPath, options?: {
+            wall?: number;
+        }): Promise<Run>;
+    };
+    surface?: {
+        /** A tab command on the session's executor surface, from inside a
+         *  body whose tool is declared outbound: on the page of the app's
+         *  first surface placed in the rail or a tab, a `web` surface's own
+         *  page or the web page of a view's tab; `show` reaches no network and
+         *  runs from any body. Rejects with the error the window met. */
+        command(op: SurfaceOp, args?: Record<string, unknown>): Promise<SurfaceAnswer>;
+    };
+    store?: {
+        get(key: string): Promise<unknown>;
+        set(key: string, value: unknown): Promise<void>;
+        delete(key: string): Promise<void>;
+    };
+    secrets?: {
+        get(name: string): Promise<string | null>;
+        set(name: string, value: string): Promise<void>;
+        delete(name: string): Promise<void>;
+    };
+    oauth?: {
+        /** True once a token for the issuer covers the scopes: at once when
+         *  one is held, else after the person's sign-in card and the grant;
+         *  false when the person or the service said no. Rejects with the
+         *  reason when the request, the manifest's `network` or the service
+         *  does not allow a sign-in. A sign-in replaces the scopes held, so
+         *  each call names every scope the app needs. */
+        login(request: OAuthLogin): Promise<boolean>;
+        /** The access token, refreshed when it is past half its lifetime;
+         *  null when the app must sign in again. A token the service revoked
+         *  early still comes back: after a 401, `logout` and `login` again. */
+        token(issuer: string): Promise<string | null>;
+        /** Forgets the tokens for the issuer, revoked at the service where
+         *  its metadata names a revocation endpoint. Null, or the words when
+         *  the service did not confirm the revocation and may still hold the
+         *  access. */
+        logout(issuer: string): Promise<string | null>;
+    };
+    events?: {
+        emit(event: AppEvent): Promise<void>;
+    };
+    notify?(notice: AppNotice): Promise<void>;
+    /** Drawn in the conversation at every level, from inside a tool body. */
+    ask(question: AppQuestion): Promise<AppAnswer>;
+    sessions?: {
+        /** This app's sessions and the ones it started in other apps. */
+        list(): Promise<SessionListing[]>;
+        open(id: string): Promise<OpenedSession>;
+        create(body: SessionCreate): Promise<{
+            id: string;
+        }>;
+        send(id: string, text: string): Promise<void>;
+        wait(id: string): Promise<TurnOutcome>;
+        on(event: 'deleted', fn: (id: string) => void): () => void;
+        on(event: 'finished', fn: (result: {
+            session: string;
+            turn: string;
+            stopReason: string;
+        }) => void): () => void;
+    };
+    apps: {
+        /** The enabled apps. */
+        list(): Promise<AppListing[]>;
+        /** Called when the set of enabled apps changed. */
+        on(event: 'changed', fn: () => void): () => void;
+    };
+    /** The settings the manifest declares, which the platform keeps. */
+    settings: {
+        /** Every setting, with the value the person set or its default;
+         *  rejects for an app that declares no settings. */
+        get(): Promise<SettingValues>;
+        /** Called with every setting's value when the person changed one. */
+        on(event: 'changed', fn: (values: SettingValues) => void): () => void;
+    };
+    models?: {
+        /** One streaming completion on the card this app runs chat on, or
+         *  the chat role; `format` asks for JSON against a schema. A call
+         *  inside a tool body counts against the budget of the turn that
+         *  made the call. */
+        complete(request: CompletionRequest, signal?: AbortSignal): AsyncIterable<CompletionDelta>;
+        /** The chat cards an app's sessions may run on: this app's, or
+         *  another app's under the `sessions.create` grant. */
+        for(app?: string): Promise<ModelListing[]>;
+        /** The card an app runs a kind on, and where the choice came from, or
+         *  the reason none can: this app's, or another app's under the
+         *  `sessions.create` grant. */
+        effective(kind: ModelKind, app?: string): Promise<EffectiveModel>;
+    };
+    /** With `sessions.create`: the projects of an app this one may start
+     *  conversations in. */
+    projects?: {
+        list(app?: string): Promise<ProjectListing[]>;
+    };
+    /** With `catalogue`: the bus. A search reads the catalogue, never
+     *  asks, and answers the whole definition of each match; a call runs
+     *  another app's offered tool or an attached connector's tool, with this
+     *  app as the caller. A call made inside a tool body runs under that
+     *  call, in its conversation and at its level, and ends with it; the
+     *  signal cancels it earlier. A refused or failed call rejects with the
+     *  words. */
+    capabilities?: {
+        search(queries: string | string[], limit?: number): Promise<string>;
+        call(name: string, input?: Record<string, unknown>, options?: {
+            signal?: AbortSignal;
+        }): Promise<CapabilityAnswer>;
+    };
+    /** With `readers`: a reader for a format the manifest declares under
+     *  `formats`; the read tool hands it the file's bytes. */
+    readers?: {
+        register(format: string, read: (bytes: Uint8Array, name: string) => Promise<string> | string): () => void;
+    };
+    jobs?: {
+        /** One job on the card this app runs that kind on. */
+        submit(kind: JobKind, input: JobInput): Promise<Job>;
+        get(id: string): Promise<Job>;
+        cancel(id: string): Promise<Job>;
+        on(event: 'progress', fn: (job: Job) => void): () => void;
+    };
+    /** With `peers`: the rooms the app is in. The person opens or joins a
+     *  room through a view of the app; a backend sends to the room's other
+     *  members, hears their messages, and may leave. While the app is in a
+     *  room, an event of it starts the backend when it is not up. */
+    peers?: {
+        list(): Promise<Room[]>;
+        /** Sends `data`, at most 64 KiB as JSON, to every other
+         *  member; inside a tool body, the tool is declared outbound. */
+        send(room: string, data: unknown): Promise<void>;
+        leave(room: string): Promise<void>;
+        on(event: 'message', fn: (message: {
+            room: string;
+            from: string;
+            data: unknown;
+        }) => void): () => void;
+        /** The app entered a room, or a member came to it or left it. */
+        on(event: 'changed', fn: (room: Room) => void): () => void;
+        /** The app is out of a room. */
+        on(event: 'ended', fn: (room: string) => void): () => void;
+    };
+}
+/** What a tool body runs with. */
+interface ToolRun {
+    readonly callId: string;
+    readonly context: CallContext;
+    readonly signal: AbortSignal;
+    /** A snapshot of the output so far, drawn under the tool's row. */
+    progress(output: string): void;
+}
+/** What a capability call answers: its text, its structured object when
+ *  the tool answered one, and the files it answered, which this app
+ *  holds until it releases them. */
+interface CapabilityAnswer {
+    text: string;
+    structured?: Structured;
+    assets: {
+        id: string;
+        mediaType: string;
+        name?: string;
+    }[];
+}
+/** A tool body: the input the model sent, checked against the tool's
+ *  input schema before the body runs, and the answer: text, content,
+ *  content with its structured object and a view, or one structured
+ *  object alone. An object whose `content` is an array is read as content
+ *  with its structured object, so a structured result that holds such a
+ *  field answers `{ content: [], structured }`. A tool that declares
+ *  `output` answers a structured object that matches it. */
+type ToolBody = (input: unknown, run: ToolRun) => Promise<string | Content[] | ToolAnswer | Structured> | string | Content[] | ToolAnswer | Structured;
+/** What `backend.js` exports. `activate` has five seconds; a body a
+ *  manifest tool lacks, or a manifest tool with no body, fails activation
+ *  with the name. */
+interface Backend {
+    activate?(ctx: AppContext): Promise<void> | void;
+    deactivate?(): Promise<void> | void;
+    tools?: Record<string, ToolBody>;
+}
+
+export type { AppAnswer, AppContext, AppEvent, AppListing, AppNotice, AppQuestion, Backend, CallContext, CapabilityAnswer, ChatContentPart, ChatMessage, CompletionDelta, CompletionRequest, CompletionStop, Connection, Content, ContentBlockMeta, EffectiveModel, FetchAnswer, FetchParams, FileInput, HearthscaleHostCapability, HostSlot, HostSlotKind, HostSlotNotification, Job, JobInput, JobInputs, JobKind, Manifest, MessageOptions, ModelContextAnswer, ModelKind, ModelListing, ModelSource, Mount, MountPath, OAuthLogin, OpenedSession, Origin, PrincipalRef, ProjectListing, ResourcePath, ResourceReadOptions, ResourceVersion, Room, Run, Sampling, Session, SessionCell, SessionCreate, SessionListing, SessionProcess, SessionRoot, SessionStatus, SettingValues, SlotInsets, StopReason, Structured, SurfaceAnswer, SurfaceOp, SurfaceResult, TerminalFrame, TerminalSnapshot, ToolAnswer, ToolBody, ToolCall, ToolDefinition, ToolRun, TurnOutcome, Usage, ViewExtension, ViewExtensionCall, ViewExtensionMethod, ViewExtensionMethods, ViewExtensionNotification, ViewHostContext, ViewHostMethods, WebPageState };