@rome-os/app-runtime 0.2.2 → 0.3.0

package/dist/index.d.ts

@@ -1,16 +1,9 @@
 import type { BetterSQLite3Database } from "drizzle-orm/better-sqlite3";
 import { z } from "zod";
+import type { JSONSchema } from "zod/v4/core";
 export { z };
+export type { JSONSchema };
 export * from "./browser.js";
-export { getWorkerRpc, isWorkerRpcResponse, WorkerRpcTimeoutError, WorkerRpcDisconnectError, setWorkerRpcInProcessDispatcher, type WorkerRpcInProcessDispatcher, type RpcResponseMessage, } from "./worker-rpc.js";
-export { RoutineEngineProxy, EventBusProxy, EventCatalogProxy, AppManagerProxy, } from "./proxies.js";
-export { IpcRpc, IpcRpcTimeoutError, IpcRpcDisconnectError, IpcStreamError, isIpcMessage, createWorkerProcessTransport, createChildProcessTransport, type IpcMessage, type IpcTransport, type IpcCallContext, type IpcInboundStream, type IpcOutboundStream, } from "./ipc.js";
-import { IpcRpc } from "./ipc.js";
-/**
- * Lazy worker-side IpcRpc bound to the parent process IPC channel. Returns
- * the same instance for the lifetime of the worker.
- */
-export declare function getWorkerIpc(): IpcRpc;
 export type SpanAttributes = Record<string, unknown>;
 export interface TelemetryBridge {
     withRomeSpan<T>(name: string, attrs: SpanAttributes, fn: () => Promise<T>): Promise<T>;
@@ -87,41 +80,182 @@ export type PreviewPayload = {
         value: string;
     }[];
 };
-export interface ActionResult {
-    success: boolean;
-    data?: unknown;
-    error?: string;
-    pendingApproval?: {
-        approvalId: string;
-        actionName: string;
-        description: string;
-    };
+/** Execution was suspended pending guardian approval; the action body has NOT
+ * run. When the guardian approves, core re-runs the action for real and the
+ * outcome arrives out-of-band (a new agent turn / webhook poll update). */
+export interface PendingApproval {
+    approvalId: string;
+    actionName: string;
+    description: string;
+}
+/**
+ * Park the calling agent on a self-contained guardian input. When an
+ * agent-callable action returns this, the calling agent is told to wait (it
+ * does not receive data); the chat host mounts this app's own component as a
+ * first-class assistant block in the transcript (declared in app.yaml under
+ * `components:` and registered via the web SDK's `defineComponent`). Best for
+ * a structured question card (see the `ask-user` app). The thread is not
+ * locked; several inline components can be open at once.
+ *
+ * Resolves by posting an `interaction_result` (the produced artifact, or
+ * `{ dismissed: true }`) on the session, which re-drives the calling agent
+ * with a server-built outcome prompt. Control never leaves the calling agent —
+ * for a transfer of the floor to another agent, see {@link Handoff}.
+ */
+export interface PendingInteraction {
+    /** This app's id (owns the component to render). */
+    appId: string;
     /**
-     * Suspend the calling agent and hand control to an app surface. When an
-     * agent-callable action returns this, the calling agent is told to wait (it
-     * does not receive `data`); the chat host mounts the named app surface so the
-     * guardian can produce an artifact collaboratively. The surface posts the
-     * artifact back as an `interaction_result` on the parent session, which
-     * re-drives the calling agent with the outcome — the action body does NOT
-     * re-run. Generalizes `ask_user_question` so any app can extend it into an
-     * arbitrarily rich interactive flow.
+     * Human-readable rendering of what the component asks for. Only webchat can
+     * mount the component; on a messaging channel (or inside a subagent) the
+     * calling agent relays this text as prose and the guardian's reply arrives
+     * as the next turn.
      */
-    pendingInteraction?: {
-        /** App that owns the surface to mount (this app's id, e.g. "workflow-studio"). */
-        appId: string;
-        /** Surface route within the app the host opens (app-defined, e.g. "design"). */
-        surface: string;
-        /**
-         * Agent that borrows this session's turns while the interaction is open. The
-         * guardian keeps using the same chat thread; their turns route to this agent
-         * (on the same webchat session) until the surface resolves, then route back
-         * to the calling agent. Omit for a surface that needs no conversation.
-         */
-        agentName?: string;
-        /** Optional seed context passed through to the surface. */
-        payload?: Record<string, unknown>;
+    promptText: string;
+    render: {
+        kind: "inline";
+        /** Component id declared in app.yaml and registered via defineComponent. */
+        componentId: string;
+        /** Optional seed props handed to the component renderer. */
+        props?: Record<string, unknown>;
     };
 }
+/**
+ * Result contract of a handoff's child conversation — what the specialist
+ * agent must hand back before control returns to the caller.
+ */
+export interface HandbackSpec {
+    /**
+     * JSON Schema the handback artifact must satisfy. The specialist agent gets
+     * a `submit_output` tool AJV-validated against it; invalid submissions
+     * bounce back as tool errors until they conform.
+     */
+    schema: Record<string, unknown>;
+    /**
+     * Optional action the host runs on each submission AFTER the schema passes,
+     * for app-specific semantic checks the schema can't express. It receives the
+     * candidate payload as its input and must return `{ valid: boolean,
+     * errors?: string[] }` in `data`. Invalid (or any validator failure —
+     * fail-closed) bounces the submission back to the agent with the errors.
+     * Must be read-only: it can run once per submission attempt.
+     */
+    validate?: string;
+}
+/**
+ * Transfer the floor to another agent. When an agent-callable action returns
+ * this, the calling agent suspends and the host opens a dedicated child session
+ * the guardian collaborates in with `agentName` (see Workflow Studio's
+ * `design_workflow`). The parent thread is locked until control returns.
+ *
+ * The handoff itself mounts no app surface — the summoned agent brings one up on
+ * demand by calling the `show_app` action (e.g. Workflow Studio's author shows
+ * its live storyboard once there is a plan to preview). `appId` only names the
+ * app that owns the handoff (the host install-checks it).
+ *
+ * The handback: when `handback` is set, a schema-valid (and, if declared,
+ * app-validated) `submit_output` submission renders an approval card in the
+ * child session; guardian approval ends the handoff and posts the payload as
+ * an `interaction_result` on the parent session, re-driving the caller with a
+ * server-built outcome prompt (plus `handbackHint`). Dismissal hands control
+ * back with `{ dismissed: true }` and no artifact.
+ */
+export interface Handoff {
+    /** The app that owns this handoff (the host install-checks it). */
+    appId: string;
+    /**
+     * Off-webchat fallback. Only webchat can run a handoff; on a messaging
+     * channel (or inside a subagent) the calling agent relays this text as prose
+     * and the guardian's reply arrives as the next turn.
+     */
+    promptText: string;
+    /**
+     * Agent the guardian collaborates with in the child session. Omit for a
+     * handoff that needs no conversation.
+     */
+    agentName?: string;
+    /** Optional seed context (e.g. the opening summary). */
+    payload?: Record<string, unknown>;
+    /** Result contract the specialist must satisfy to hand control back. */
+    handback?: HandbackSpec;
+    /**
+     * Appended to the resolution prompt the resumed caller receives, so the
+     * caller learns its exact next step. The literal token `<childSessionId>` is
+     * substituted with the handoff's child session id by the host.
+     */
+    handbackHint?: string;
+}
+/**
+ * Place one of this app's web widgets onto the guardian's workspace (the
+ * freegrid), WITHOUT parking the calling agent. Unlike {@link PendingInteraction}
+ * — which suspends the turn and waits for the guardian to resolve a surface —
+ * this is fire-and-forget: the widget is mounted as a side effect and the agent
+ * is told it succeeded and keeps going on the same turn. Use it to surface a
+ * read-only view the guardian can glance at (e.g. Workflow Studio's storyboard),
+ * not to collect input.
+ *
+ * Only takes effect on a webchat turn (the placement rides the turn's event
+ * stream to the browser). On a messaging channel or inside a subagent there is
+ * no workspace, so the calling agent is told the widget could not be shown.
+ */
+export interface PlaceWidget {
+    /** This app's id — the app whose web widget is mounted onto the freegrid. */
+    appId: string;
+    /**
+     * `true` scopes the placement to the current chat session: the widget is added
+     * to this session's layout and mounted with `?session=<id>`, so a session-keyed
+     * surface shows this conversation's state. `false` is a standing placement that
+     * persists across sessions (as on app install).
+     */
+    sessionScoped: boolean;
+    /**
+     * Optional route within the app, e.g. `"orders/123"`. It rides the widget src
+     * as the path after the app id (`/full/apps/<appId>/orders/123`), which the
+     * host forwards to the app as `bootstrap.routePath` so the app's own router
+     * resolves it. An unknown route is the app's to handle (typically a not-found
+     * screen). This is *addressing*, not data: payloads belong in the app's own
+     * session storage, which the route reads on mount (keyed by `session` + `params`).
+     */
+    route?: string;
+    /**
+     * Optional flat scalar parameters carried as query params on the widget src
+     * (`?orderId=123`). The app reads them off `window.location.search`. Values must
+     * be primitives so they serialize into the persisted placement and survive
+     * remount. Host-owned query keys (`session`, `interaction`) always win.
+     */
+    params?: Record<string, string | number | boolean>;
+}
+/**
+ * The envelope every action returns, discriminated on `status`. This one type
+ * crosses every invocation boundary — agent↔action tool results, app↔app
+ * `runAction`, webhook invocation records — so the states are modeled as a union
+ * rather than independent flags: a result is exactly one of completed (`ok`),
+ * domain-rejected (`error`), suspended on approval, suspended on an inline
+ * guardian input (`pending_interaction`), suspended on a handoff to another agent
+ * (`handoff`), or completed-with-a-widget-placed (`place_widget`, which does NOT
+ * suspend). Infrastructure failures (handler throw, serialization, worker crash)
+ * are NOT `error` results — they surface as a thrown {@link ActionInvocationError}.
+ * The `error` variant is for domain rejections the caller can act on ("routine
+ * name already taken").
+ */
+export type ActionResult<T = unknown> = {
+    status: "ok";
+    data?: T;
+} | {
+    status: "error";
+    error: string;
+} | {
+    status: "pending_approval";
+    approval: PendingApproval;
+} | {
+    status: "pending_interaction";
+    interaction: PendingInteraction;
+} | {
+    status: "handoff";
+    handoff: Handoff;
+} | {
+    status: "place_widget";
+    placement: PlaceWidget;
+};
 /**
  * Build an {@link Action} from a Zod input schema. The schema is the single
  * source of truth: it generates the model-facing JSON Schema (`inputSchema`),
@@ -246,42 +380,77 @@ export interface AgentLifecycleHookDeps {
     appContext?: RomeAppContext;
     agentRunner?: AgentRunnerInterface;
 }
-export type AgentMessage = {
+/** Turn bracketing: the first event of a turn's stream. */
+export interface TurnStartMessage {
+    type: "turn_start";
+    turnId: string;
+    /** Session the turn runs on — stable across turns of a conversation. */
+    sessionId: string;
+    userPrompt: string;
+}
+/** Turn bracketing: the last event of a turn's stream, emitted after the
+ *  terminal `result`/`error` block. */
+export interface TurnEndMessage {
+    type: "turn_end";
+    turnId: string;
+    /** Turn outcome. `interrupted` means the user stopped the turn mid-flight;
+     *  it takes precedence over `error` (an abort surfaced as an error block is
+     *  still an interruption, not a failure). */
+    status: "completed" | "interrupted" | "error";
+    /** Turn wall-clock measured by the AgentSession. Distinct from
+     *  `accounting.durationMs` on the terminal block, which is the
+     *  provider's self-reported per-call duration. */
+    durationMs: number;
+}
+export interface TextMessage {
     type: "text";
     content: string;
-} | {
+}
+/**
+ * Incremental preview of an in-flight `text` block (provider streaming).
+ * Transient: the complete `text` block still follows, so consumers that
+ * only care about whole blocks (trace, persistence, accounting) must
+ * ignore this variant. Emitted only by providers that support partial
+ * output; absence degrades to whole-block delivery.
+ */
+export interface TextDeltaMessage {
+    type: "text_delta";
+    content: string;
+}
+export interface ThinkingMessage {
     type: "thinking";
     content: string;
-} | {
+}
+export interface ToolUseMessage {
     type: "tool_use";
     id: string;
     tool: string;
     input: unknown;
     startedAt?: string;
-} | {
+}
+export interface ToolResultMessage {
     type: "tool_result";
     toolUseId: string;
     tool: string;
     output: unknown;
     endedAt?: string;
-} | {
+}
+/** Terminal content block: the agent's final answer for its turn.
+ *  The turn boundary itself is the `turn_end` event that follows. */
+export interface ResultMessage {
     type: "result";
     content: string;
+    /** Provider-reported usage for the agent that produced this block.
+     *  Sub-agent terminals carry their own accounting. */
     accounting?: AgentAccounting;
-    /** True on the single block that ends the turn (the outermost
-     *  AgentSession's terminal). Sub-agent terminals carry false. */
-    turnTerminal?: boolean;
-    /** Turn wall-clock; set only when `turnTerminal === true`. Separate
-     *  from `accounting.durationMs`, which is the provider's per-call
-     *  duration. */
-    turnDurationMs?: number;
-} | {
+}
+/** Terminal content block: the turn failed. `turn_end` still follows. */
+export interface ErrorMessage {
     type: "error";
     error: string;
     accounting?: AgentAccounting;
-    turnTerminal?: boolean;
-    turnDurationMs?: number;
-} | {
+}
+export interface SessionInitMessage {
     type: "session_init";
     sessionId: string;
     systemPrompt?: string;
@@ -289,17 +458,19 @@ export type AgentMessage = {
     projectPath?: string;
     /** RFC 013: per-turn id allocated by AgentSession.sendTurn. */
     turnId?: string;
-} | {
-    /**
-     * Structured payload an agent submitted via its `outputSchema` (RFC 016
-     * §submit_output). Emitted by AgentSession only AFTER the payload has
-     * been schema-validated and accepted, so consumers can treat it as
-     * authoritative — distinct from the raw `tool_use` event for the
-     * underlying `submit_output` tool which represents the model's proposal.
-     */
+}
+/**
+ * Structured payload an agent submitted via its `outputSchema` (RFC 016
+ * §submit_output). Emitted by AgentSession only AFTER the payload has
+ * been schema-validated and accepted, so consumers can treat it as
+ * authoritative — distinct from the raw `tool_use` event for the
+ * underlying `submit_output` tool which represents the model's proposal.
+ */
+export interface StructuredOutputMessage {
     type: "structured_output";
     payload: unknown;
-};
+}
+export type AgentMessage = TurnStartMessage | TurnEndMessage | TextMessage | TextDeltaMessage | ThinkingMessage | ToolUseMessage | ToolResultMessage | ResultMessage | ErrorMessage | SessionInitMessage | StructuredOutputMessage;
 export type StreamAgentMessage = AgentMessage & {
     agent?: string;
 };
@@ -312,6 +483,12 @@ export interface ThreadContext {
     threadType?: "private" | "group";
     projectName?: string;
     projectPath?: string;
+    /**
+     * Bond level of the message sender, when known. Lets turn-level logic tell the
+     * guardian apart from other trusted senders (inner-circle, acquaintance) who
+     * reach the same `<channel>:<thread>` trusted path.
+     */
+    senderBondLevel?: string;
 }
 export interface RunParams {
     agentName: string;
@@ -334,6 +511,27 @@ export interface ForkRunParams {
 export interface AgentRunnerInterface {
     run(params: RunParams): AsyncIterable<AgentMessage>;
     runForked?(params: ForkRunParams): AsyncIterable<AgentMessage>;
+    /**
+     * Returns true when the agent with the given name is loaded in the catalog
+     * and can be invoked via `run`. Used by callers (e.g. the inbox message
+     * handler) to fall back gracefully when a channel is configured to route to
+     * an agent that has been uninstalled. Optional for backwards compatibility;
+     * implementations that don't provide it are treated as always-true by
+     * callers. May be async — the worker-side runner resolves the catalog over
+     * RPC, so callers must `await` the result.
+     */
+    hasAgent?(name: string): boolean | Promise<boolean>;
+    /**
+     * Returns true when the named agent is allowed to call the named action —
+     * i.e. the action resolves through the agent's allow-list (or `*`, or a
+     * globally-granted action), the same resolution the agent session uses to
+     * gate tool calls. Lets callers (e.g. the inbox message handler) tailor
+     * guidance to what the routed agent can actually do, instead of assuming.
+     * Optional for backwards compatibility; implementations that don't provide
+     * it are treated as "cannot" by callers. May be async — the worker-side
+     * runner resolves the catalog over RPC, so callers must `await` the result.
+     */
+    hasAction?(agentName: string, actionName: string): boolean | Promise<boolean>;
 }
 export interface Attachment {
     type: "image" | "video" | "audio" | "document" | "sticker" | "location" | "contact";
@@ -385,26 +583,6 @@ export type MessagePart = {
     actionName: string;
     preview: PreviewPayload;
     status: ApprovalCardStatus;
-} | {
-    /**
-     * The model called the built-in `ask_user_question` MCP tool. The host
-     * channel (web chat today) snapshots the tool's input into this part so
-     * the question card renders as a first-class assistant message, not a
-     * detail buried inside the trace drawer.
-     */
-    type: "ask_user_question_card";
-    toolUseId: string;
-    questions: AskUserQuestionDefinition[];
-} | {
-    /**
-     * A user's reply to a previously rendered ask_user_question card. Lives
-     * inside a user-role webchat message so the UI can derive "this question
-     * was answered" by scanning subsequent messages for a matching
-     * toolUseId, instead of mutating any tool_use block in place.
-     */
-    type: "user_answer";
-    toolUseId: string;
-    answers: UserAnswerEntry[];
 } | {
     /**
      * An interactive "routine draft" the agent proposes mid-conversation.
@@ -417,6 +595,62 @@ export type MessagePart = {
     type: "routine_draft_card";
     toolUseId: string;
     draft: RoutineDraftSpec;
+} | {
+    /**
+     * A parked inline guardian input the agent is waiting on. The action that
+     * called for it returned a `pending_interaction` result; the webchat drain
+     * loop snapshots this part keyed by the tool call's id, and the host
+     * mounts the app's component in the transcript. The component lives in
+     * the app, not core.
+     */
+    type: "pending_interaction";
+    toolUseId: string;
+    appId: string;
+    render: {
+        kind: "inline";
+        componentId: string;
+        props?: Record<string, unknown>;
+    };
+} | {
+    /**
+     * A handoff in progress: the calling agent suspended and `agentName`
+     * holds the floor in `childSessionId` (the spawned design conversation),
+     * with the app's `surface` mounted as a side-by-side widget. The webchat
+     * drain loop snapshots this part keyed by the tool call's id.
+     */
+    type: "handoff";
+    toolUseId: string;
+    appId: string;
+    surface: string;
+    agentName?: string;
+    payload?: Record<string, unknown>;
+    childSessionId?: string;
+    /** Mirrors {@link Handoff.handbackHint}; appended to the resolution
+     * prompt when the handoff resolves with an artifact. */
+    handbackHint?: string;
+} | {
+    /**
+     * A schema-valid payload the specialist agent submitted via
+     * `submit_output` in a handoff child session that carries a handback
+     * contract. The host renders it as an approval card: Approve ends the
+     * handoff with `payload` as the output; "keep editing" feedback continues
+     * the conversation and a later submission supersedes this card.
+     */
+    type: "submission_card";
+    payload: Record<string, unknown>;
+} | {
+    /**
+     * Resolution of an inline interaction or a handoff — the single
+     * resolution part both suspension kinds share. Lives in a user-role
+     * webchat message so the UI derives "this resolved" by scanning for a
+     * matching toolUseId, and the server re-drives the calling agent with a
+     * server-built outcome prompt. `output` is the produced artifact (a
+     * handoff's approved handback payload, or an inline component's result),
+     * or `{ dismissed: true }`.
+     */
+    type: "interaction_result";
+    toolUseId: string;
+    output: Record<string, unknown>;
 };
 /** The proposed routine, as snapshotted from the agent's `propose_routine`
  * tool call. `name`/`trigger`/`actionName`/`args` are the create payload;
@@ -441,45 +675,20 @@ export interface RoutineDraftSpec {
     /** Single argument object for the action. */
     args: Record<string, unknown>;
 }
-export type AskUserQuestionDefinition = {
-    id: string;
-    question: string;
-    type: "single" | "multi";
-    options: AskUserQuestionOption[];
-    /** When true (default), the user may add a free-text note alongside their selection. */
-    allowFreeText?: boolean;
-} | {
-    id: string;
-    question: string;
-    type: "text";
-};
-export interface AskUserQuestionOption {
-    id: string;
-    text: string;
-    preview?: AskUserQuestionOptionPreview;
-}
-export interface AskUserQuestionOptionPreview {
-    url: string;
-    kind?: "image" | "video" | "html" | "csv";
-    alt?: string;
-}
-export type UserAnswerEntry = {
-    type: "single";
-    questionId: string;
-    selected: string;
-    selectedText?: string;
-    freeText?: string;
-} | {
-    type: "multi";
-    questionId: string;
-    selected: string[];
-    selectedText?: string[];
-    freeText?: string;
-} | {
-    type: "text";
-    questionId: string;
-    text: string;
-};
+/**
+ * Optional per-message routing overrides resolved by the channel adapter from
+ * its channel-level configuration. When present, the downstream message handler
+ * uses these to override the default trusted-path target agent. Untrusted
+ * messages still go through sentinel regardless.
+ */
+export interface MessageRouting {
+    /**
+     * Name of the agent to route this message to on the trusted path. Falls back
+     * to the default ("main") when undefined or when the named agent is not
+     * present in the catalog.
+     */
+    agentName?: string;
+}
 export interface NormalizedMessage {
     id: string;
     channel: "telegram" | "telegram_user" | "whatsapp" | "wechat" | "webchat" | "discord";
@@ -492,6 +701,7 @@ export interface NormalizedMessage {
     text: string;
     attachments: Attachment[];
     replyToMessageId?: string;
+    routing?: MessageRouting;
     rawEvent: unknown;
 }
 export interface ChannelAdapter {
@@ -600,6 +810,20 @@ export interface RomeAppContext {
     runAction(name: string, args: Record<string, unknown>): Promise<ActionResult>;
     listRoutines(): Promise<Routine[]>;
 }
+export type ActionInvocationErrorCode = "not_found" | "unserializable" | "handler_error" | "worker_failure";
+/**
+ * The single failure shape of `RomeAppContext.runAction`, RFC 030. Every
+ * invocation failure — unknown action, args/result that can't cross a process
+ * boundary, a throwing handler, a dead worker — surfaces as this type with the
+ * same fields regardless of which process the caller or callee ran in, so app
+ * code never branches on transport. Cancellation is the one pass-through: it
+ * is a control signal for the runtime, not a failure the app handles.
+ */
+export declare class ActionInvocationError extends Error {
+    readonly actionName: string;
+    readonly code: ActionInvocationErrorCode;
+    constructor(actionName: string, code: ActionInvocationErrorCode, message: string);
+}
 export type AppActionRuntimeDeps<TShared = Record<string, unknown>> = TShared & {
     appContext: RomeAppContext;
 };
@@ -741,6 +965,20 @@ export interface EventBusTrigger {
 export interface EventCatalogEntry {
     eventType: string;
     appId: string;
+    /** JSON Schema for the event's payload — the same vocabulary action input
+     * schemas use. With `schemaOrigin: "observed"` it is inferred from the most
+     * recent non-empty emission, so it is a discovery aid for a consumer writing
+     * a routine `trigger.filter` (whose dot-paths read payload fields), **not** a
+     * contract: it reflects one observed payload, may omit optional keys, and
+     * deliberately carries no `required` (one sample can't establish
+     * requiredness). Absent until the type has been emitted with a non-empty
+     * payload. */
+    payloadSchema?: JSONSchema.ObjectSchema;
+    /** Where `payloadSchema` came from. `"observed"` = inferred from a real
+     * emission. `"declared"` is reserved for producer-authored schemas
+     * (pre-registration); a declared schema is authoritative and is never
+     * overwritten by an observed one. */
+    schemaOrigin?: "observed" | "declared";
 }
 export interface PollTrigger {
     type: "poll";
@@ -812,9 +1050,28 @@ export interface EventCatalogReader {
         total: number;
     }>;
 }
+/** A Discord guild channel as enumerated by the running bot. */
+export interface DiscordGuildChannel {
+    id: string;
+    name: string;
+    guildId: string;
+    guildName: string;
+    type: string;
+    parentId?: string;
+}
+/** Control surface of the live Discord adapter (which runs in the main
+ * process). Both operations tolerate the adapter not running: `reloadConfig`
+ * is a no-op and `listChannels` returns `[]`, so callers can render a clean
+ * "Discord not configured" outcome instead of handling transport errors. */
+export interface DiscordChannelControl {
+    reloadConfig(): Promise<void>;
+    listChannels(): Promise<DiscordGuildChannel[]>;
+}
 /** App lifecycle authority (create / install / uninstall / enable). Results are
  * app-local shapes the caller knows, so they cross this surface as `unknown` and
- * the caller narrows — the SDK stays free of the concrete result types. */
+ * the caller narrows — the SDK stays free of the concrete result types.
+ * `install` takes no appId: the daemon derives it from the source (manifest id
+ * for local sources, listing slug for appstore) and returns it in the result. */
 export interface AppLifecycle {
     create(params: {
         appId: string;
@@ -822,7 +1079,6 @@ export interface AppLifecycle {
         template?: "default" | "workflow";
     }): Promise<unknown>;
     install(params: {
-        appId: string;
         source: unknown;
         enabled?: boolean;
     }): Promise<unknown>;