@agimon-ai/doompi-web-contracts 0.0.1-alpha.2 → 0.0.1-alpha.3

package/README.md

@@ -1,27 +1,46 @@
 # @agimon-ai/doompi-web-contracts
 
-Web cockpit plugin contracts for DoomPi.
+Typed plugin, slot, session-channel, and hub-channel contracts for the DoomPi web cockpit.
 
-Part of the [DoomPi distribution](https://www.npmjs.com/package/@agimon-ai/doompi).
+This is a library, not a Pi extension. It starts no process and does not belong in `.doom/modes.yaml`.
 
-A DoomPi web plugin has two halves that share these types:
+> **Alpha:** web plugin contracts may change between releases.
 
-- A client entry exporting `webPlugin: WebPluginDefinition`, compiled into the cockpit bundle by
-  the host package's build. It can contribute tabs with panels and badges, session data channels,
-  overlays, Leader Space key bindings, command palette commands, rail, selection bar, and
-  activity dock sections, and tool renderers: one `message` component per claimed tool (by name,
-  or by a `matches` predicate for tools named at runtime) that owns the tool call's whole timeline
-  item, composed from the shared components package's `MessageItem` so it looks like every other
-  item; `toolResultText` and `toolResultTextLines` read a result's text blocks the same way.
-- An optional hub entry exporting `webHubChannels: readonly WebHubChannel[]`, loaded by the cockpit
-  server at startup. A channel watches some data source and answers per-session payloads that reach
-  the page as `ChannelFrame` messages whose frame type is the channel name.
+## Install
 
-Plugin packages declare both entries in a `doompiWeb` block in their package.json; the cockpit's
-build scans the workspace and generates its registration modules from those blocks.
+```bash
+npm install @agimon-ai/doompi-web-contracts
+```
 
-Use `defineWebPlugin` and `defineSessionChannel` for checked literals. Server code should import
-these contracts type-only.
+Web plugin clients also require the package's React, React DOM, and TanStack Store peers when they use
+those surfaces.
+
+## Plugin shape
+
+A web plugin can have two entries:
+
+- A client entry exports `webPlugin: WebPluginDefinition`. It can contribute tabs, slots, Leader
+  bindings, commands, session channels, activity surfaces, and tool renderers.
+- An optional hub entry exports `webHubChannels: readonly WebHubChannel[]`. Each channel watches a
+  data source and emits per-session `ChannelFrame` payloads to the page.
+
+Declare both entries in the plugin package's `doompiWeb` manifest block. The DoomPi cockpit bundler
+reads those declarations and generates the registration modules.
+
+Use the definition helpers for checked literals:
+
+```ts
+import {
+  defineSessionChannel,
+  defineSessionStore,
+  defineSlot,
+  defineWebPlugin,
+  toolResultText,
+} from '@agimon-ai/doompi-web-contracts';
+```
+
+Import contracts type-only from server code. The `/testing` subpath provides channel, render, slot,
+and tool-message fixtures for plugin tests.
 
 ## License
 

package/dist/index.d.cts

@@ -1,6 +1,6 @@
-import { ActivityGroupContribution, LeaderBindingContribution, LeaderKeyContribution, MinorModeContribution, PaletteCommandContext, PaletteCommandContribution, SelectionAxisContribution, SessionChannelContribution, SessionFrameSender, SessionRecords, SessionStore, SessionStoreChannel, SlotDataFill, SlotDeclaration, SlotFillContribution, SurfaceContribution, TabContribution, ToolMessageRenderProps, ToolRendererContribution, ToolResultView, TransientTab, WebPluginDefinition, WebPluginRuntime, WebPluginSlotProps } from "./types/webPlugin.cjs";
+import { ActivityGroupContribution, LeaderBindingContribution, LeaderKeyContribution, MinorModeContribution, PaletteCommandContext, PaletteCommandContribution, SelectionAxisContribution, SessionChannelContribution, SessionFrameSender, SessionRecords, SessionStore, SessionStoreChannel, SettingsFieldContribution, SettingsFieldOption, SettingsSectionContribution, SlotDataFill, SlotDeclaration, SlotFillContribution, SurfaceContribution, TabContribution, ToolMessageRenderProps, ToolPromptContribution, ToolPromptDialog, ToolPromptRenderProps, ToolRendererContribution, ToolResultView, TransientTab, WebPluginDefinition, WebPluginRuntime, WebPluginSlotProps } from "./types/webPlugin.cjs";
 import { defineSessionChannel, defineSlot, defineWebPlugin } from "./services/define.cjs";
 import { defineSessionStore } from "./services/sessionStore.cjs";
 import { toolResultText, toolResultTextLines } from "./services/toolResult.cjs";
 import { ChannelFrame, HubChannelHost, HubChannelSource, HubSessionScope, WebHubChannel } from "./types/webHub.cjs";
-export { type ActivityGroupContribution, type ChannelFrame, type HubChannelHost, type HubChannelSource, type HubSessionScope, type LeaderBindingContribution, type LeaderKeyContribution, type MinorModeContribution, type PaletteCommandContext, type PaletteCommandContribution, type SelectionAxisContribution, type SessionChannelContribution, type SessionFrameSender, type SessionRecords, type SessionStore, type SessionStoreChannel, type SlotDataFill, type SlotDeclaration, type SlotFillContribution, type SurfaceContribution, type TabContribution, type ToolMessageRenderProps, type ToolRendererContribution, type ToolResultView, type TransientTab, type WebHubChannel, type WebPluginDefinition, type WebPluginRuntime, type WebPluginSlotProps, defineSessionChannel, defineSessionStore, defineSlot, defineWebPlugin, toolResultText, toolResultTextLines };
+export { type ActivityGroupContribution, type ChannelFrame, type HubChannelHost, type HubChannelSource, type HubSessionScope, type LeaderBindingContribution, type LeaderKeyContribution, type MinorModeContribution, type PaletteCommandContext, type PaletteCommandContribution, type SelectionAxisContribution, type SessionChannelContribution, type SessionFrameSender, type SessionRecords, type SessionStore, type SessionStoreChannel, type SettingsFieldContribution, type SettingsFieldOption, type SettingsSectionContribution, type SlotDataFill, type SlotDeclaration, type SlotFillContribution, type SurfaceContribution, type TabContribution, type ToolMessageRenderProps, type ToolPromptContribution, type ToolPromptDialog, type ToolPromptRenderProps, type ToolRendererContribution, type ToolResultView, type TransientTab, type WebHubChannel, type WebPluginDefinition, type WebPluginRuntime, type WebPluginSlotProps, defineSessionChannel, defineSessionStore, defineSlot, defineWebPlugin, toolResultText, toolResultTextLines };

package/dist/index.d.mts

@@ -1,6 +1,6 @@
-import { ActivityGroupContribution, LeaderBindingContribution, LeaderKeyContribution, MinorModeContribution, PaletteCommandContext, PaletteCommandContribution, SelectionAxisContribution, SessionChannelContribution, SessionFrameSender, SessionRecords, SessionStore, SessionStoreChannel, SlotDataFill, SlotDeclaration, SlotFillContribution, SurfaceContribution, TabContribution, ToolMessageRenderProps, ToolRendererContribution, ToolResultView, TransientTab, WebPluginDefinition, WebPluginRuntime, WebPluginSlotProps } from "./types/webPlugin.mjs";
+import { ActivityGroupContribution, LeaderBindingContribution, LeaderKeyContribution, MinorModeContribution, PaletteCommandContext, PaletteCommandContribution, SelectionAxisContribution, SessionChannelContribution, SessionFrameSender, SessionRecords, SessionStore, SessionStoreChannel, SettingsFieldContribution, SettingsFieldOption, SettingsSectionContribution, SlotDataFill, SlotDeclaration, SlotFillContribution, SurfaceContribution, TabContribution, ToolMessageRenderProps, ToolPromptContribution, ToolPromptDialog, ToolPromptRenderProps, ToolRendererContribution, ToolResultView, TransientTab, WebPluginDefinition, WebPluginRuntime, WebPluginSlotProps } from "./types/webPlugin.mjs";
 import { defineSessionChannel, defineSlot, defineWebPlugin } from "./services/define.mjs";
 import { defineSessionStore } from "./services/sessionStore.mjs";
 import { toolResultText, toolResultTextLines } from "./services/toolResult.mjs";
 import { ChannelFrame, HubChannelHost, HubChannelSource, HubSessionScope, WebHubChannel } from "./types/webHub.mjs";
-export { type ActivityGroupContribution, type ChannelFrame, type HubChannelHost, type HubChannelSource, type HubSessionScope, type LeaderBindingContribution, type LeaderKeyContribution, type MinorModeContribution, type PaletteCommandContext, type PaletteCommandContribution, type SelectionAxisContribution, type SessionChannelContribution, type SessionFrameSender, type SessionRecords, type SessionStore, type SessionStoreChannel, type SlotDataFill, type SlotDeclaration, type SlotFillContribution, type SurfaceContribution, type TabContribution, type ToolMessageRenderProps, type ToolRendererContribution, type ToolResultView, type TransientTab, type WebHubChannel, type WebPluginDefinition, type WebPluginRuntime, type WebPluginSlotProps, defineSessionChannel, defineSessionStore, defineSlot, defineWebPlugin, toolResultText, toolResultTextLines };
+export { type ActivityGroupContribution, type ChannelFrame, type HubChannelHost, type HubChannelSource, type HubSessionScope, type LeaderBindingContribution, type LeaderKeyContribution, type MinorModeContribution, type PaletteCommandContext, type PaletteCommandContribution, type SelectionAxisContribution, type SessionChannelContribution, type SessionFrameSender, type SessionRecords, type SessionStore, type SessionStoreChannel, type SettingsFieldContribution, type SettingsFieldOption, type SettingsSectionContribution, type SlotDataFill, type SlotDeclaration, type SlotFillContribution, type SurfaceContribution, type TabContribution, type ToolMessageRenderProps, type ToolPromptContribution, type ToolPromptDialog, type ToolPromptRenderProps, type ToolRendererContribution, type ToolResultView, type TransientTab, type WebHubChannel, type WebPluginDefinition, type WebPluginRuntime, type WebPluginSlotProps, defineSessionChannel, defineSessionStore, defineSlot, defineWebPlugin, toolResultText, toolResultTextLines };

package/dist/types/webPlugin.d.cts

@@ -105,6 +105,54 @@ interface TabContribution {
   /** A React hook, fully typed inside the plugin; 0 hides the badge. */
   useBadge?: (sessionId: string | null) => number;
 }
+/**
+ * One field on a settings page, declared as data.
+ *
+ * Settings are data rather than a component because the host owns what a
+ * plugin cannot: which file an edit lands in. A page has one scope switch and
+ * one repository, and every field on it reports where its value came from and
+ * whether the selected scope may hold it. A plugin drawing its own form would
+ * have to reproduce all of that, and each would get it slightly different.
+ */
+interface SettingsFieldContribution {
+  /** Unique within the section; also the testid suffix. */
+  id: string;
+  label: string;
+  kind: 'text' | 'select' | 'toggle' | 'info';
+  /** The config key this reads and writes, e.g. ['modes','planning','main','model']. */
+  keyPath: readonly string[];
+  /** One line of help under the field. */
+  detail?: string;
+  /** Shown while the field is unset, in place of a value. */
+  placeholder?: string;
+  /** The closed set a 'select' offers, when the plugin knows it. */
+  options?: readonly SettingsFieldOption[];
+  /**
+   * An option set the host supplies instead. A model picker needs the machine's
+   * authenticated models, which no plugin can enumerate from the browser; a
+   * host that cannot answer leaves the field as free text.
+   */
+  optionsFrom?: 'models';
+}
+interface SettingsFieldOption {
+  value: string;
+  label: string;
+  /** Groups entries under a heading, as providers group their models. */
+  group?: string;
+}
+/**
+ * A page in cockpit settings, contributed by the package that owns the
+ * settings on it. The id is the URL segment (/settings/:id), so it is unique
+ * across plugins; a collision is an install diagnostic and the first wins.
+ */
+interface SettingsSectionContribution {
+  id: string;
+  label: string;
+  detail: string;
+  /** Sort position in the settings menu; lower first, id breaks ties. */
+  order?: number;
+  fields: readonly SettingsFieldContribution[];
+}
 interface SurfaceContribution {
   id: string;
   component: ComponentType<WebPluginSlotProps>;
@@ -214,6 +262,19 @@ interface ActivityGroupContribution {
   widgetKeys?: string[];
   /** The plugin tab the group's key chip opens; without one the chip is a plain label. */
   tab?: string;
+  /**
+   * Drop the group entirely while its status key is present but empty, rather
+   * than showing a header over "idle".
+   *
+   * A session publishes a status key once and clears it by publishing nothing,
+   * which reaches the page as an empty string, so a group that has reported at
+   * all can never stop reporting. For a group whose whole content is the thing
+   * the session is doing (a goal, a recording, the files it changed), the
+   * header alone is a row that says nothing, and a dock of those buries the
+   * groups that do. A group that is also a way in, with a launcher or a tab,
+   * leaves this off: its frame is worth keeping when it is idle.
+   */
+  hideWhenEmpty?: boolean;
   /** Sort position in the dock; lower first, name breaks ties. */
   order?: number;
 }
@@ -289,6 +350,51 @@ interface ToolMessageRenderProps extends WebPluginSlotProps {
   running: boolean;
   isError: boolean;
 }
+/** The extension UI request a running tool is blocked on, as its prompt sees it. */
+interface ToolPromptDialog {
+  id: string;
+  method: 'select' | 'confirm' | 'input' | 'editor';
+  title: string;
+  message: string;
+  options: readonly string[];
+  placeholder: string;
+  prefill: string;
+}
+/**
+ * Everything a tool's composer prompt receives: the timeline item's props,
+ * plus the request the tool is waiting on and the two ways to settle it.
+ *
+ * The dialog frame is deliberately thin, because Pi's own is: a select
+ * carries a title and a list of labels and nothing else. A prompt that needs
+ * more renders it from `args`, which is the whole call the tool was made
+ * with, and answers with whatever its session half agreed to read back.
+ */
+interface ToolPromptRenderProps extends ToolMessageRenderProps {
+  dialog: ToolPromptDialog;
+  /** Answers the request and unblocks the tool. Bound, so a prompt may destructure it. */
+  answer: (value: string) => void;
+  /** The reader declined; the tool sees a cancellation. */
+  cancel: () => void;
+}
+/**
+ * A tool's stand-in for the composer input, shown while the tool is running
+ * and holding an extension UI request.
+ *
+ * A question the agent is blocked on belongs where the reader is already
+ * looking and typing, not behind a modal covering the conversation they need
+ * in order to answer. While a prompt is up the host's own dialog stands down,
+ * so exactly one surface owns the request.
+ */
+interface ToolPromptContribution {
+  /**
+   * True when this tool owns the open request. Without it the tool claims any
+   * request open while it runs, which is wrong the moment a second extension
+   * asks something during the same turn; a request it refuses falls back to
+   * the host's dialog.
+   */
+  claims?(dialog: ToolPromptDialog, args: Record<string, unknown>): boolean;
+  component: ComponentType<ToolPromptRenderProps>;
+}
 /**
  * The timeline item for the tools a package registers, the web half of the
  * TUI's renderCall/renderResult with Pi's renderShell 'self': one `message`
@@ -306,6 +412,8 @@ interface ToolRendererContribution {
    */
   matches?(toolName: string, statuses: Readonly<Record<string, string>>): boolean;
   message: ComponentType<ToolMessageRenderProps>;
+  /** Stands in for the composer input while this tool runs and holds a request. */
+  prompt?: ToolPromptContribution;
 }
 /** What a plugin's optional runtime may do; both send on the page's hub socket. */
 interface WebPluginRuntime {
@@ -324,6 +432,8 @@ interface WebPluginDefinition {
   leaderBindings?: LeaderBindingContribution[];
   railSections?: SurfaceContribution[];
   selectionBarItems?: SurfaceContribution[];
+  /** Compact controls placed in the mobile composer's action row, immediately before queue. */
+  composerActions?: SurfaceContribution[];
   toolRenderers?: ToolRendererContribution[];
   /**
    * A section whose id names an activity group any plugin declares renders
@@ -331,6 +441,11 @@ interface WebPluginDefinition {
    * one-line summary; any other section renders after the groups.
    */
   activitySections?: SurfaceContribution[];
+  /**
+   * Pages this plugin adds to cockpit settings. The host renders the fields and
+   * owns the scope switch, the repository picker, and every write.
+   */
+  settingsSections?: SettingsSectionContribution[];
   /** The slots this plugin opens for others, each named '<this plugin id>.<name>'. */
   slots?: SlotDeclaration[];
   /** This plugin's contributions into slots other plugins (or the host) declare. */
@@ -339,5 +454,5 @@ interface WebPluginDefinition {
   start?(runtime: WebPluginRuntime): (() => void) | void;
 }
 //#endregion
-export { ActivityGroupContribution, LeaderBindingBase, LeaderBindingContribution, LeaderKeyContribution, MinorModeContribution, PaletteCommandContext, PaletteCommandContribution, SelectionAxisContribution, SessionChannelContribution, SessionFrameSender, SessionRecords, SessionStore, SessionStoreChannel, SlotDataFill, SlotDeclaration, SlotFillContribution, SurfaceContribution, TabContribution, ToolMessageRenderProps, ToolRendererContribution, ToolResultView, TransientTab, WebPluginDefinition, WebPluginRuntime, WebPluginSlotProps };
+export { ActivityGroupContribution, LeaderBindingBase, LeaderBindingContribution, LeaderKeyContribution, MinorModeContribution, PaletteCommandContext, PaletteCommandContribution, SelectionAxisContribution, SessionChannelContribution, SessionFrameSender, SessionRecords, SessionStore, SessionStoreChannel, SettingsFieldContribution, SettingsFieldOption, SettingsSectionContribution, SlotDataFill, SlotDeclaration, SlotFillContribution, SurfaceContribution, TabContribution, ToolMessageRenderProps, ToolPromptContribution, ToolPromptDialog, ToolPromptRenderProps, ToolRendererContribution, ToolResultView, TransientTab, WebPluginDefinition, WebPluginRuntime, WebPluginSlotProps };
 //# sourceMappingURL=webPlugin.d.cts.map

package/dist/types/webPlugin.d.cts.map

@@ -1 +1 @@
-{"version":3,"file":"webPlugin.d.cts","names":[],"sources":["../../src/types/webPlugin.ts"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;KAwBY,sBAAsB,mBAAmB,OAAO;;;;;;;;;;UAU3C,gBAAgB;EAC/B;;EAEA,OAAO,iBAAiB;;;UAGT,aAAa;EAC5B;EACA;EACA;EACA,MAAM;;;;;;;;UAQS;;EAEf;EACA;EACA,OAAO,cAAc;;;UAGN;EACf;;EAEA,UAAU;;EAEV,mBAAmB,KAAK;EACxB,oBAAoB;;;;;;EAMpB,eAAe,qBAAqB;;EAEpC,kBAAkB;;EAElB,aAAa,iBAAiB;;EAE9B,WAAW,MAAM,MAAM,gBAAgB,mBAAmB,aAAa;;;;;;;EAOvE,UAAU,SAAS;;;;;;;UAOJ;EACf;EACA;;EAEA;EACA;EACA,YAAY,cAAc;;UAEX;;EAEf;EACA;EACA,OAAO,cAAc;;EAErB,YAAY;;UAEG;EACf;EACA,WAAW,cAAc;;UAEV;EACf;;EAEA,QAAQ;EACR,kBAAkB;;UAEH;EACf;EACA;EACA;EACA,IAAI,SAAS;;;;;;;UAOE;EACf;EACA;EACA;;UAEe;EACf;;EAEA,MAAM;;;;;;;;;;;;;KAaI,6BACP;EACC;MAED;EACC,IAAI,SAAS;;;;;;;;UAQF;EACf;;;;;;;EAOA;;EAEA;;EAEA;;EAEA;;EAEA;;;;;;;;UAQe;;EAEf;;EAEA;;EAEA;;EAEA;;EAEA;;EAEA;;;;;;;;;;UAUe;EACf;;EAEA;;EAEA;;EAEA;;EAEA;;EAEA;;;;;;;UAOe,2BAA2B;EAC1C;EACA,MAAM,iBAAiB;EACvB,MAAM,mBAAmB,SAAS;EAClC,KAAK;;;KAGK,eAAe,KAAK,QAAQ,eAAe;;UAEtC,oBAAoB,GAAG;EACtC;EACA,MAAM,iBAAiB;;EAEvB,OAAO,SAAS,GAAG,SAAS,UAAU;;;;;;;UAOvB,aAAa;WACnB,OAAO,MAAM,eAAe;;;;;;EAMrC,OAAO,OAAO,eAAe,IAAI,2BAA2B;;EAE5D,OAAO,mBAAmB,UAAU,SAAS,MAAM;EACnD,KAAK;EACL;;EAEA,QAAQ,SAAS,SAAS,oBAAoB,GAAG,WAAW;;;;;;;UAO7C;EACf;EACA;;;;;;;;;;UAUe,+BAA+B;EAC9C;;EAEA;EACA,MAAM;;EAEN,UAAU,SAAS;;EAEnB,QAAQ;;EAER;;EAEA;EACA;;;;;;;;UAQe;;EAEf;;;;;;;EAOA,SAAS,kBAAkB,UAAU,SAAS;EAC9C,SAAS,cAAc;;;UAGR;EACf,kBAAkB;EAClB,aAAa,OAAO;;UAEL;EACf;EACA,OAAO;EACP,WAAW;EACX,gBAAgB;EAChB,aAAa;EACb,iBAAiB;EACjB,WAAW;EACX,kBAAkB;EAClB,iBAAiB;EACjB,eAAe;EACf,oBAAoB;EACpB,gBAAgB;;;;;;EAMhB,mBAAmB;;EAEnB,QAAQ;;EAER,QAAQ;;EAER,OAAO,SAAS"}
+{"version":3,"file":"webPlugin.d.cts","names":[],"sources":["../../src/types/webPlugin.ts"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;KAwBY,sBAAsB,mBAAmB,OAAO;;;;;;;;;;UAU3C,gBAAgB;EAC/B;;EAEA,OAAO,iBAAiB;;;UAGT,aAAa;EAC5B;EACA;EACA;EACA,MAAM;;;;;;;;UAQS;;EAEf;EACA;EACA,OAAO,cAAc;;;UAGN;EACf;;EAEA,UAAU;;EAEV,mBAAmB,KAAK;EACxB,oBAAoB;;;;;;EAMpB,eAAe,qBAAqB;;EAEpC,kBAAkB;;EAElB,aAAa,iBAAiB;;EAE9B,WAAW,MAAM,MAAM,gBAAgB,mBAAmB,aAAa;;;;;;;EAOvE,UAAU,SAAS;;;;;;;UAOJ;EACf;EACA;;EAEA;EACA;EACA,YAAY,cAAc;;UAEX;;EAEf;EACA;EACA,OAAO,cAAc;;EAErB,YAAY;;;;;;;;;;;UAWG;;EAEf;EACA;EACA;;EAEA;;EAEA;;EAEA;;EAEA,mBAAmB;;;;;;EAMnB;;UAEe;EACf;EACA;;EAEA;;;;;;;UAOe;EACf;EACA;EACA;;EAEA;EACA,iBAAiB;;UAEF;EACf;EACA,WAAW,cAAc;;UAEV;EACf;;EAEA,QAAQ;EACR,kBAAkB;;UAEH;EACf;EACA;EACA;EACA,IAAI,SAAS;;;;;;;UAOE;EACf;EACA;EACA;;UAEe;EACf;;EAEA,MAAM;;;;;;;;;;;;;KAaI,6BACP;EACC;MAED;EACC,IAAI,SAAS;;;;;;;;UAQF;EACf;;;;;;;EAOA;;EAEA;;EAEA;;EAEA;;EAEA;;;;;;;;UAQe;;EAEf;;EAEA;;EAEA;;EAEA;;EAEA;;EAEA;;;;;;;;;;UAUe;EACf;;EAEA;;EAEA;;EAEA;;EAEA;;;;;;;;;;;;;EAaA;;EAEA;;;;;;;UAOe,2BAA2B;EAC1C;EACA,MAAM,iBAAiB;EACvB,MAAM,mBAAmB,SAAS;EAClC,KAAK;;;KAGK,eAAe,KAAK,QAAQ,eAAe;;UAEtC,oBAAoB,GAAG;EACtC;EACA,MAAM,iBAAiB;;EAEvB,OAAO,SAAS,GAAG,SAAS,UAAU;;;;;;;UAOvB,aAAa;WACnB,OAAO,MAAM,eAAe;;;;;;EAMrC,OAAO,OAAO,eAAe,IAAI,2BAA2B;;EAE5D,OAAO,mBAAmB,UAAU,SAAS,MAAM;EACnD,KAAK;EACL;;EAEA,QAAQ,SAAS,SAAS,oBAAoB,GAAG,WAAW;;;;;;;UAO7C;EACf;EACA;;;;;;;;;;UAUe,+BAA+B;EAC9C;;EAEA;EACA,MAAM;;EAEN,UAAU,SAAS;;EAEnB,QAAQ;;EAER;;EAEA;EACA;;;UAGe;EACf;EACA;EACA;EACA;EACA;EACA;EACA;;;;;;;;;;;UAWe,8BAA8B;EAC7C,QAAQ;;EAER,SAAS;;EAET;;;;;;;;;;;UAWe;;;;;;;EAOf,QAAQ,QAAQ,kBAAkB,MAAM;EACxC,WAAW,cAAc;;;;;;;;UAQV;;EAEf;;;;;;;EAOA,SAAS,kBAAkB,UAAU,SAAS;EAC9C,SAAS,cAAc;;EAEvB,SAAS;;;UAGM;EACf,kBAAkB;EAClB,aAAa,OAAO;;UAEL;EACf;EACA,OAAO;EACP,WAAW;EACX,gBAAgB;EAChB,aAAa;EACb,iBAAiB;EACjB,WAAW;EACX,kBAAkB;EAClB,iBAAiB;EACjB,eAAe;EACf,oBAAoB;;EAEpB,kBAAkB;EAClB,gBAAgB;;;;;;EAMhB,mBAAmB;;;;;EAKnB,mBAAmB;;EAEnB,QAAQ;;EAER,QAAQ;;EAER,OAAO,SAAS"}

package/dist/types/webPlugin.d.mts

@@ -105,6 +105,54 @@ interface TabContribution {
   /** A React hook, fully typed inside the plugin; 0 hides the badge. */
   useBadge?: (sessionId: string | null) => number;
 }
+/**
+ * One field on a settings page, declared as data.
+ *
+ * Settings are data rather than a component because the host owns what a
+ * plugin cannot: which file an edit lands in. A page has one scope switch and
+ * one repository, and every field on it reports where its value came from and
+ * whether the selected scope may hold it. A plugin drawing its own form would
+ * have to reproduce all of that, and each would get it slightly different.
+ */
+interface SettingsFieldContribution {
+  /** Unique within the section; also the testid suffix. */
+  id: string;
+  label: string;
+  kind: 'text' | 'select' | 'toggle' | 'info';
+  /** The config key this reads and writes, e.g. ['modes','planning','main','model']. */
+  keyPath: readonly string[];
+  /** One line of help under the field. */
+  detail?: string;
+  /** Shown while the field is unset, in place of a value. */
+  placeholder?: string;
+  /** The closed set a 'select' offers, when the plugin knows it. */
+  options?: readonly SettingsFieldOption[];
+  /**
+   * An option set the host supplies instead. A model picker needs the machine's
+   * authenticated models, which no plugin can enumerate from the browser; a
+   * host that cannot answer leaves the field as free text.
+   */
+  optionsFrom?: 'models';
+}
+interface SettingsFieldOption {
+  value: string;
+  label: string;
+  /** Groups entries under a heading, as providers group their models. */
+  group?: string;
+}
+/**
+ * A page in cockpit settings, contributed by the package that owns the
+ * settings on it. The id is the URL segment (/settings/:id), so it is unique
+ * across plugins; a collision is an install diagnostic and the first wins.
+ */
+interface SettingsSectionContribution {
+  id: string;
+  label: string;
+  detail: string;
+  /** Sort position in the settings menu; lower first, id breaks ties. */
+  order?: number;
+  fields: readonly SettingsFieldContribution[];
+}
 interface SurfaceContribution {
   id: string;
   component: ComponentType<WebPluginSlotProps>;
@@ -214,6 +262,19 @@ interface ActivityGroupContribution {
   widgetKeys?: string[];
   /** The plugin tab the group's key chip opens; without one the chip is a plain label. */
   tab?: string;
+  /**
+   * Drop the group entirely while its status key is present but empty, rather
+   * than showing a header over "idle".
+   *
+   * A session publishes a status key once and clears it by publishing nothing,
+   * which reaches the page as an empty string, so a group that has reported at
+   * all can never stop reporting. For a group whose whole content is the thing
+   * the session is doing (a goal, a recording, the files it changed), the
+   * header alone is a row that says nothing, and a dock of those buries the
+   * groups that do. A group that is also a way in, with a launcher or a tab,
+   * leaves this off: its frame is worth keeping when it is idle.
+   */
+  hideWhenEmpty?: boolean;
   /** Sort position in the dock; lower first, name breaks ties. */
   order?: number;
 }
@@ -289,6 +350,51 @@ interface ToolMessageRenderProps extends WebPluginSlotProps {
   running: boolean;
   isError: boolean;
 }
+/** The extension UI request a running tool is blocked on, as its prompt sees it. */
+interface ToolPromptDialog {
+  id: string;
+  method: 'select' | 'confirm' | 'input' | 'editor';
+  title: string;
+  message: string;
+  options: readonly string[];
+  placeholder: string;
+  prefill: string;
+}
+/**
+ * Everything a tool's composer prompt receives: the timeline item's props,
+ * plus the request the tool is waiting on and the two ways to settle it.
+ *
+ * The dialog frame is deliberately thin, because Pi's own is: a select
+ * carries a title and a list of labels and nothing else. A prompt that needs
+ * more renders it from `args`, which is the whole call the tool was made
+ * with, and answers with whatever its session half agreed to read back.
+ */
+interface ToolPromptRenderProps extends ToolMessageRenderProps {
+  dialog: ToolPromptDialog;
+  /** Answers the request and unblocks the tool. Bound, so a prompt may destructure it. */
+  answer: (value: string) => void;
+  /** The reader declined; the tool sees a cancellation. */
+  cancel: () => void;
+}
+/**
+ * A tool's stand-in for the composer input, shown while the tool is running
+ * and holding an extension UI request.
+ *
+ * A question the agent is blocked on belongs where the reader is already
+ * looking and typing, not behind a modal covering the conversation they need
+ * in order to answer. While a prompt is up the host's own dialog stands down,
+ * so exactly one surface owns the request.
+ */
+interface ToolPromptContribution {
+  /**
+   * True when this tool owns the open request. Without it the tool claims any
+   * request open while it runs, which is wrong the moment a second extension
+   * asks something during the same turn; a request it refuses falls back to
+   * the host's dialog.
+   */
+  claims?(dialog: ToolPromptDialog, args: Record<string, unknown>): boolean;
+  component: ComponentType<ToolPromptRenderProps>;
+}
 /**
  * The timeline item for the tools a package registers, the web half of the
  * TUI's renderCall/renderResult with Pi's renderShell 'self': one `message`
@@ -306,6 +412,8 @@ interface ToolRendererContribution {
    */
   matches?(toolName: string, statuses: Readonly<Record<string, string>>): boolean;
   message: ComponentType<ToolMessageRenderProps>;
+  /** Stands in for the composer input while this tool runs and holds a request. */
+  prompt?: ToolPromptContribution;
 }
 /** What a plugin's optional runtime may do; both send on the page's hub socket. */
 interface WebPluginRuntime {
@@ -324,6 +432,8 @@ interface WebPluginDefinition {
   leaderBindings?: LeaderBindingContribution[];
   railSections?: SurfaceContribution[];
   selectionBarItems?: SurfaceContribution[];
+  /** Compact controls placed in the mobile composer's action row, immediately before queue. */
+  composerActions?: SurfaceContribution[];
   toolRenderers?: ToolRendererContribution[];
   /**
    * A section whose id names an activity group any plugin declares renders
@@ -331,6 +441,11 @@ interface WebPluginDefinition {
    * one-line summary; any other section renders after the groups.
    */
   activitySections?: SurfaceContribution[];
+  /**
+   * Pages this plugin adds to cockpit settings. The host renders the fields and
+   * owns the scope switch, the repository picker, and every write.
+   */
+  settingsSections?: SettingsSectionContribution[];
   /** The slots this plugin opens for others, each named '<this plugin id>.<name>'. */
   slots?: SlotDeclaration[];
   /** This plugin's contributions into slots other plugins (or the host) declare. */
@@ -339,5 +454,5 @@ interface WebPluginDefinition {
   start?(runtime: WebPluginRuntime): (() => void) | void;
 }
 //#endregion
-export { ActivityGroupContribution, LeaderBindingBase, LeaderBindingContribution, LeaderKeyContribution, MinorModeContribution, PaletteCommandContext, PaletteCommandContribution, SelectionAxisContribution, SessionChannelContribution, SessionFrameSender, SessionRecords, SessionStore, SessionStoreChannel, SlotDataFill, SlotDeclaration, SlotFillContribution, SurfaceContribution, TabContribution, ToolMessageRenderProps, ToolRendererContribution, ToolResultView, TransientTab, WebPluginDefinition, WebPluginRuntime, WebPluginSlotProps };
+export { ActivityGroupContribution, LeaderBindingBase, LeaderBindingContribution, LeaderKeyContribution, MinorModeContribution, PaletteCommandContext, PaletteCommandContribution, SelectionAxisContribution, SessionChannelContribution, SessionFrameSender, SessionRecords, SessionStore, SessionStoreChannel, SettingsFieldContribution, SettingsFieldOption, SettingsSectionContribution, SlotDataFill, SlotDeclaration, SlotFillContribution, SurfaceContribution, TabContribution, ToolMessageRenderProps, ToolPromptContribution, ToolPromptDialog, ToolPromptRenderProps, ToolRendererContribution, ToolResultView, TransientTab, WebPluginDefinition, WebPluginRuntime, WebPluginSlotProps };
 //# sourceMappingURL=webPlugin.d.mts.map

package/dist/types/webPlugin.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"webPlugin.d.mts","names":[],"sources":["../../src/types/webPlugin.ts"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;KAwBY,sBAAsB,mBAAmB,OAAO;;;;;;;;;;UAU3C,gBAAgB;EAC/B;;EAEA,OAAO,iBAAiB;;;UAGT,aAAa;EAC5B;EACA;EACA;EACA,MAAM;;;;;;;;UAQS;;EAEf;EACA;EACA,OAAO,cAAc;;;UAGN;EACf;;EAEA,UAAU;;EAEV,mBAAmB,KAAK;EACxB,oBAAoB;;;;;;EAMpB,eAAe,qBAAqB;;EAEpC,kBAAkB;;EAElB,aAAa,iBAAiB;;EAE9B,WAAW,MAAM,MAAM,gBAAgB,mBAAmB,aAAa;;;;;;;EAOvE,UAAU,SAAS;;;;;;;UAOJ;EACf;EACA;;EAEA;EACA;EACA,YAAY,cAAc;;UAEX;;EAEf;EACA;EACA,OAAO,cAAc;;EAErB,YAAY;;UAEG;EACf;EACA,WAAW,cAAc;;UAEV;EACf;;EAEA,QAAQ;EACR,kBAAkB;;UAEH;EACf;EACA;EACA;EACA,IAAI,SAAS;;;;;;;UAOE;EACf;EACA;EACA;;UAEe;EACf;;EAEA,MAAM;;;;;;;;;;;;;KAaI,6BACP;EACC;MAED;EACC,IAAI,SAAS;;;;;;;;UAQF;EACf;;;;;;;EAOA;;EAEA;;EAEA;;EAEA;;EAEA;;;;;;;;UAQe;;EAEf;;EAEA;;EAEA;;EAEA;;EAEA;;EAEA;;;;;;;;;;UAUe;EACf;;EAEA;;EAEA;;EAEA;;EAEA;;EAEA;;;;;;;UAOe,2BAA2B;EAC1C;EACA,MAAM,iBAAiB;EACvB,MAAM,mBAAmB,SAAS;EAClC,KAAK;;;KAGK,eAAe,KAAK,QAAQ,eAAe;;UAEtC,oBAAoB,GAAG;EACtC;EACA,MAAM,iBAAiB;;EAEvB,OAAO,SAAS,GAAG,SAAS,UAAU;;;;;;;UAOvB,aAAa;WACnB,OAAO,MAAM,eAAe;;;;;;EAMrC,OAAO,OAAO,eAAe,IAAI,2BAA2B;;EAE5D,OAAO,mBAAmB,UAAU,SAAS,MAAM;EACnD,KAAK;EACL;;EAEA,QAAQ,SAAS,SAAS,oBAAoB,GAAG,WAAW;;;;;;;UAO7C;EACf;EACA;;;;;;;;;;UAUe,+BAA+B;EAC9C;;EAEA;EACA,MAAM;;EAEN,UAAU,SAAS;;EAEnB,QAAQ;;EAER;;EAEA;EACA;;;;;;;;UAQe;;EAEf;;;;;;;EAOA,SAAS,kBAAkB,UAAU,SAAS;EAC9C,SAAS,cAAc;;;UAGR;EACf,kBAAkB;EAClB,aAAa,OAAO;;UAEL;EACf;EACA,OAAO;EACP,WAAW;EACX,gBAAgB;EAChB,aAAa;EACb,iBAAiB;EACjB,WAAW;EACX,kBAAkB;EAClB,iBAAiB;EACjB,eAAe;EACf,oBAAoB;EACpB,gBAAgB;;;;;;EAMhB,mBAAmB;;EAEnB,QAAQ;;EAER,QAAQ;;EAER,OAAO,SAAS"}
+{"version":3,"file":"webPlugin.d.mts","names":[],"sources":["../../src/types/webPlugin.ts"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;KAwBY,sBAAsB,mBAAmB,OAAO;;;;;;;;;;UAU3C,gBAAgB;EAC/B;;EAEA,OAAO,iBAAiB;;;UAGT,aAAa;EAC5B;EACA;EACA;EACA,MAAM;;;;;;;;UAQS;;EAEf;EACA;EACA,OAAO,cAAc;;;UAGN;EACf;;EAEA,UAAU;;EAEV,mBAAmB,KAAK;EACxB,oBAAoB;;;;;;EAMpB,eAAe,qBAAqB;;EAEpC,kBAAkB;;EAElB,aAAa,iBAAiB;;EAE9B,WAAW,MAAM,MAAM,gBAAgB,mBAAmB,aAAa;;;;;;;EAOvE,UAAU,SAAS;;;;;;;UAOJ;EACf;EACA;;EAEA;EACA;EACA,YAAY,cAAc;;UAEX;;EAEf;EACA;EACA,OAAO,cAAc;;EAErB,YAAY;;;;;;;;;;;UAWG;;EAEf;EACA;EACA;;EAEA;;EAEA;;EAEA;;EAEA,mBAAmB;;;;;;EAMnB;;UAEe;EACf;EACA;;EAEA;;;;;;;UAOe;EACf;EACA;EACA;;EAEA;EACA,iBAAiB;;UAEF;EACf;EACA,WAAW,cAAc;;UAEV;EACf;;EAEA,QAAQ;EACR,kBAAkB;;UAEH;EACf;EACA;EACA;EACA,IAAI,SAAS;;;;;;;UAOE;EACf;EACA;EACA;;UAEe;EACf;;EAEA,MAAM;;;;;;;;;;;;;KAaI,6BACP;EACC;MAED;EACC,IAAI,SAAS;;;;;;;;UAQF;EACf;;;;;;;EAOA;;EAEA;;EAEA;;EAEA;;EAEA;;;;;;;;UAQe;;EAEf;;EAEA;;EAEA;;EAEA;;EAEA;;EAEA;;;;;;;;;;UAUe;EACf;;EAEA;;EAEA;;EAEA;;EAEA;;;;;;;;;;;;;EAaA;;EAEA;;;;;;;UAOe,2BAA2B;EAC1C;EACA,MAAM,iBAAiB;EACvB,MAAM,mBAAmB,SAAS;EAClC,KAAK;;;KAGK,eAAe,KAAK,QAAQ,eAAe;;UAEtC,oBAAoB,GAAG;EACtC;EACA,MAAM,iBAAiB;;EAEvB,OAAO,SAAS,GAAG,SAAS,UAAU;;;;;;;UAOvB,aAAa;WACnB,OAAO,MAAM,eAAe;;;;;;EAMrC,OAAO,OAAO,eAAe,IAAI,2BAA2B;;EAE5D,OAAO,mBAAmB,UAAU,SAAS,MAAM;EACnD,KAAK;EACL;;EAEA,QAAQ,SAAS,SAAS,oBAAoB,GAAG,WAAW;;;;;;;UAO7C;EACf;EACA;;;;;;;;;;UAUe,+BAA+B;EAC9C;;EAEA;EACA,MAAM;;EAEN,UAAU,SAAS;;EAEnB,QAAQ;;EAER;;EAEA;EACA;;;UAGe;EACf;EACA;EACA;EACA;EACA;EACA;EACA;;;;;;;;;;;UAWe,8BAA8B;EAC7C,QAAQ;;EAER,SAAS;;EAET;;;;;;;;;;;UAWe;;;;;;;EAOf,QAAQ,QAAQ,kBAAkB,MAAM;EACxC,WAAW,cAAc;;;;;;;;UAQV;;EAEf;;;;;;;EAOA,SAAS,kBAAkB,UAAU,SAAS;EAC9C,SAAS,cAAc;;EAEvB,SAAS;;;UAGM;EACf,kBAAkB;EAClB,aAAa,OAAO;;UAEL;EACf;EACA,OAAO;EACP,WAAW;EACX,gBAAgB;EAChB,aAAa;EACb,iBAAiB;EACjB,WAAW;EACX,kBAAkB;EAClB,iBAAiB;EACjB,eAAe;EACf,oBAAoB;;EAEpB,kBAAkB;EAClB,gBAAgB;;;;;;EAMhB,mBAAmB;;;;;EAKnB,mBAAmB;;EAEnB,QAAQ;;EAER,QAAQ;;EAER,OAAO,SAAS"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agimon-ai/doompi-web-contracts",
-  "version": "0.0.1-alpha.2",
+  "version": "0.0.1-alpha.3",
   "description": "Web cockpit plugin contracts for DoomPi: plugin definitions, slot contributions, session data channels, and hub channel sources.",
   "keywords": [
     "ai",