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

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.cjs

@@ -1 +1 @@
-Object.defineProperty(exports,Symbol.toStringTag,{value:`Module`});const e=require("./services/define.cjs"),t=require("./services/sessionStore.cjs"),n=require("./services/toolResult.cjs");exports.defineSessionChannel=e.defineSessionChannel,exports.defineSessionStore=t.defineSessionStore,exports.defineSlot=e.defineSlot,exports.defineWebPlugin=e.defineWebPlugin,exports.toolResultText=n.toolResultText,exports.toolResultTextLines=n.toolResultTextLines;
+Object.defineProperty(exports,Symbol.toStringTag,{value:`Module`});const e=require("./services/define.cjs"),t=require("./services/globalStore.cjs"),n=require("./services/sessionStore.cjs"),r=require("./services/toolResult.cjs");exports.defineGlobalStore=t.defineGlobalStore,exports.defineSessionChannel=e.defineSessionChannel,exports.defineSessionStore=n.defineSessionStore,exports.defineSlot=e.defineSlot,exports.defineWebPlugin=e.defineWebPlugin,exports.toolResultText=r.toolResultText,exports.toolResultTextLines=r.toolResultTextLines;

package/dist/index.d.cts

@@ -1,6 +1,7 @@
-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, GlobalStore, LeaderBindingContribution, LeaderKeyContribution, MinorModeContribution, PaletteCommandContext, PaletteCommandContribution, RepositorySettingsPanelContribution, RepositorySettingsPanelProps, RepositorySettingsRepository, 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 { defineGlobalStore } from "./services/globalStore.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 };
+import { ChannelFrame, HubChannelConnection, HubChannelHost, HubChannelSource, HubSessionApiRequest, HubSessionScope, WebHubChannel } from "./types/webHub.cjs";
+export { type ActivityGroupContribution, type ChannelFrame, type GlobalStore, type HubChannelConnection, type HubChannelHost, type HubChannelSource, type HubSessionApiRequest, type HubSessionScope, type LeaderBindingContribution, type LeaderKeyContribution, type MinorModeContribution, type PaletteCommandContext, type PaletteCommandContribution, type RepositorySettingsPanelContribution, type RepositorySettingsPanelProps, type RepositorySettingsRepository, 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, defineGlobalStore, defineSessionChannel, defineSessionStore, defineSlot, defineWebPlugin, toolResultText, toolResultTextLines };

package/dist/index.d.mts

@@ -1,6 +1,7 @@
-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, GlobalStore, LeaderBindingContribution, LeaderKeyContribution, MinorModeContribution, PaletteCommandContext, PaletteCommandContribution, RepositorySettingsPanelContribution, RepositorySettingsPanelProps, RepositorySettingsRepository, 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 { defineGlobalStore } from "./services/globalStore.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 };
+import { ChannelFrame, HubChannelConnection, HubChannelHost, HubChannelSource, HubSessionApiRequest, HubSessionScope, WebHubChannel } from "./types/webHub.mjs";
+export { type ActivityGroupContribution, type ChannelFrame, type GlobalStore, type HubChannelConnection, type HubChannelHost, type HubChannelSource, type HubSessionApiRequest, type HubSessionScope, type LeaderBindingContribution, type LeaderKeyContribution, type MinorModeContribution, type PaletteCommandContext, type PaletteCommandContribution, type RepositorySettingsPanelContribution, type RepositorySettingsPanelProps, type RepositorySettingsRepository, 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, defineGlobalStore, defineSessionChannel, defineSessionStore, defineSlot, defineWebPlugin, toolResultText, toolResultTextLines };

package/dist/index.mjs

@@ -1 +1 @@
-import{defineSessionChannel as e,defineSlot as t,defineWebPlugin as n}from"./services/define.mjs";import{defineSessionStore as r}from"./services/sessionStore.mjs";import{toolResultText as i,toolResultTextLines as a}from"./services/toolResult.mjs";export{e as defineSessionChannel,r as defineSessionStore,t as defineSlot,n as defineWebPlugin,i as toolResultText,a as toolResultTextLines};
+import{defineSessionChannel as e,defineSlot as t,defineWebPlugin as n}from"./services/define.mjs";import{defineGlobalStore as r}from"./services/globalStore.mjs";import{defineSessionStore as i}from"./services/sessionStore.mjs";import{toolResultText as a,toolResultTextLines as o}from"./services/toolResult.mjs";export{r as defineGlobalStore,e as defineSessionChannel,i as defineSessionStore,t as defineSlot,n as defineWebPlugin,a as toolResultText,o as toolResultTextLines};

package/dist/services/globalStore.cjs

@@ -0,0 +1,2 @@
+let e=require("@tanstack/store");function t(t){let n=new e.Store(t);return{store:n,update:e=>{let t=n.state,r=e(t);r!==t&&n.setState(()=>r)},reset:()=>{n.setState(e=>e===t?e:t)}}}exports.defineGlobalStore=t;
+//# sourceMappingURL=globalStore.cjs.map

package/dist/services/globalStore.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"globalStore.cjs","names":["Store"],"sources":["../../src/services/globalStore.ts"],"sourcesContent":["import { Store } from '@tanstack/store';\nimport type { GlobalStore } from '../types/webPlugin.ts';\n\n/** Page-wide plugin state shared by every contribution from the plugin. */\nexport function defineGlobalStore<T>(initial: T): GlobalStore<T> {\n  const store = new Store<T>(initial);\n\n  const update = (updater: (current: T) => T): void => {\n    const current = store.state;\n    const next = updater(current);\n    if (next !== current) store.setState(() => next);\n  };\n\n  const reset = (): void => {\n    store.setState((current) => (current === initial ? current : initial));\n  };\n\n  return { store, update, reset };\n}\n"],"mappings":"iCAIA,SAAgB,EAAqB,EAA4B,CAC/D,IAAM,EAAQ,IAAIA,EAAAA,MAAS,CAAO,EAYlC,MAAO,CAAE,QAAO,OAVA,GAAqC,CACnD,IAAM,EAAU,EAAM,MAChB,EAAO,EAAQ,CAAO,EACxB,IAAS,GAAS,EAAM,aAAe,CAAI,CACjD,EAMwB,UAJE,CACxB,EAAM,SAAU,GAAa,IAAY,EAAU,EAAU,CAAQ,CACvE,CAE8B,CAChC"}

package/dist/services/globalStore.d.cts

@@ -0,0 +1,7 @@
+import { GlobalStore } from "../types/webPlugin.cjs";
+//#region src/services/globalStore.d.ts
+/** Page-wide plugin state shared by every contribution from the plugin. */
+declare function defineGlobalStore<T>(initial: T): GlobalStore<T>;
+//#endregion
+export { defineGlobalStore };
+//# sourceMappingURL=globalStore.d.cts.map

package/dist/services/globalStore.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"globalStore.d.cts","names":[],"sources":["../../src/services/globalStore.ts"],"mappings":";;;iBAIgB,kBAAkB,GAAG,SAAS,IAAI,YAAY"}

package/dist/services/globalStore.d.mts

@@ -0,0 +1,7 @@
+import { GlobalStore } from "../types/webPlugin.mjs";
+//#region src/services/globalStore.d.ts
+/** Page-wide plugin state shared by every contribution from the plugin. */
+declare function defineGlobalStore<T>(initial: T): GlobalStore<T>;
+//#endregion
+export { defineGlobalStore };
+//# sourceMappingURL=globalStore.d.mts.map

package/dist/services/globalStore.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"globalStore.d.mts","names":[],"sources":["../../src/services/globalStore.ts"],"mappings":";;;iBAIgB,kBAAkB,GAAG,SAAS,IAAI,YAAY"}

package/dist/services/globalStore.mjs

@@ -0,0 +1,2 @@
+import{Store as e}from"@tanstack/store";function t(t){let n=new e(t);return{store:n,update:e=>{let t=n.state,r=e(t);r!==t&&n.setState(()=>r)},reset:()=>{n.setState(e=>e===t?e:t)}}}export{t as defineGlobalStore};
+//# sourceMappingURL=globalStore.mjs.map

package/dist/services/globalStore.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"globalStore.mjs","names":[],"sources":["../../src/services/globalStore.ts"],"sourcesContent":["import { Store } from '@tanstack/store';\nimport type { GlobalStore } from '../types/webPlugin.ts';\n\n/** Page-wide plugin state shared by every contribution from the plugin. */\nexport function defineGlobalStore<T>(initial: T): GlobalStore<T> {\n  const store = new Store<T>(initial);\n\n  const update = (updater: (current: T) => T): void => {\n    const current = store.state;\n    const next = updater(current);\n    if (next !== current) store.setState(() => next);\n  };\n\n  const reset = (): void => {\n    store.setState((current) => (current === initial ? current : initial));\n  };\n\n  return { store, update, reset };\n}\n"],"mappings":"wCAIA,SAAgB,EAAqB,EAA4B,CAC/D,IAAM,EAAQ,IAAI,EAAS,CAAO,EAYlC,MAAO,CAAE,QAAO,OAVA,GAAqC,CACnD,IAAM,EAAU,EAAM,MAChB,EAAO,EAAQ,CAAO,EACxB,IAAS,GAAS,EAAM,aAAe,CAAI,CACjD,EAMwB,UAJE,CACxB,EAAM,SAAU,GAAa,IAAY,EAAU,EAAU,CAAQ,CACvE,CAE8B,CAChC"}

package/dist/services/testing/channels.cjs

@@ -1,2 +1,2 @@
-function e(e,t,n){let r=e.parse(n);return r===null?{accepted:!1}:(e.apply(t,r),{accepted:!0})}const t={sessionId:`s1`,cwd:`/repo`};function n(e,n={}){let r=[...n.sessions??[t]],i=[],a=[],o=e.start({sessions:()=>r,publish:(t,n)=>{i.push({type:e.frameType,sessionId:t,payload:n})},onNotice:e=>a.push(e)});return{source:o,published:i,notices:a,snapshot(e){let n=r.find(t=>t.sessionId===e)??r[0]??t;return o.payloadFor(n)},addSession(e){r.push(e),o.sessionAdded?.(e)},removeSession(e){let t=r.findIndex(t=>t.sessionId===e);t>=0&&r.splice(t,1),o.sessionRemoved?.(e)},close:()=>o.close()}}exports.driveChannel=e,exports.hubChannelHarness=n;
+function e(e,t,n){let r=e.parse(n);return r===null?{accepted:!1}:(e.apply(t,r),{accepted:!0})}const t={sessionId:`s1`,cwd:`/repo`};function n(e,n={}){let r=[...n.sessions??[t]],i=[],a=[],o=e.start({sessions:()=>r,publish:(t,n)=>{i.push({type:e.frameType,sessionId:t,payload:n})},requestSessionApi:()=>Promise.resolve(Response.json({error:`No session API in the channel harness.`},{status:501})),onNotice:e=>a.push(e)});return{source:o,published:i,notices:a,snapshot(e){let n=r.find(t=>t.sessionId===e)??r[0]??t;return o.payloadFor(n)},addSession(e){r.push(e),o.sessionAdded?.(e)},removeSession(e){let t=r.findIndex(t=>t.sessionId===e);t>=0&&r.splice(t,1),o.sessionRemoved?.(e)},close:()=>o.close()}}exports.driveChannel=e,exports.hubChannelHarness=n;
 //# sourceMappingURL=channels.cjs.map

package/dist/services/testing/channels.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"channels.cjs","names":[],"sources":["../../../src/services/testing/channels.ts"],"sourcesContent":["import type {\n  ChannelFrame,\n  HubChannelHost,\n  HubChannelSource,\n  HubSessionScope,\n  WebHubChannel,\n} from '../../types/webHub.ts';\nimport type { SessionChannelContribution } from '../../types/webPlugin.ts';\n\n/**\n * The two halves of a plugin's data channel, driven the way the hub drives them.\n *\n * A channel is the one place a plugin parses input it did not produce, so its\n * parse gate is the boundary that matters, and a test that calls `apply`\n * directly steps straight over it. `driveChannel` sends a wire payload the way\n * the page does: through `parse` first, and nothing applied when it is\n * rejected.\n */\n\nexport interface ChannelDelivery {\n  /** Whether the parse gate accepted the payload. */\n  accepted: boolean;\n}\n\n/**\n * Sends one wire payload to a session channel.\n *\n * Returns whether the gate accepted it, so a test can assert a rejection\n * without knowing what the plugin's parsed shape looks like.\n */\nexport function driveChannel(\n  channel: SessionChannelContribution,\n  sessionId: string,\n  payload: unknown,\n): ChannelDelivery {\n  const parsed: unknown = channel.parse(payload);\n  if (parsed === null) return { accepted: false };\n  channel.apply(sessionId, parsed);\n  return { accepted: true };\n}\n\nexport interface HubChannelHarness {\n  /** The running source, as the hub holds it. */\n  source: HubChannelSource;\n  /** Everything the source pushed, in order. */\n  readonly published: readonly ChannelFrame[];\n  /** What the source told the hub. */\n  readonly notices: readonly string[];\n  /** The subscribe-time snapshot one session would receive; undefined means no frame. */\n  snapshot(sessionId?: string): unknown;\n  /** Registers a session with the source, as the hub does when one appears. */\n  addSession(scope: HubSessionScope): void;\n  removeSession(sessionId: string): void;\n  close(): void;\n}\n\nexport interface HubChannelHarnessOptions {\n  /** Sessions the hub already manages when the channel starts. */\n  sessions?: readonly HubSessionScope[];\n}\n\nconst DEFAULT_SESSION: HubSessionScope = { sessionId: 's1', cwd: '/repo' };\n\n/**\n * A plugin's hub channel, started against a real host.\n *\n * The hub calls `payloadFor` once per subscriber and pushes through `publish`\n * afterwards, and a channel that only answers one of those looks correct in a\n * test that exercises the other.\n */\nexport function hubChannelHarness(channel: WebHubChannel, options: HubChannelHarnessOptions = {}): HubChannelHarness {\n  const sessions = [...(options.sessions ?? [DEFAULT_SESSION])];\n  const published: ChannelFrame[] = [];\n  const notices: string[] = [];\n  const host: HubChannelHost = {\n    sessions: () => sessions,\n    publish: (sessionId, payload) => {\n      published.push({ type: channel.frameType, sessionId, payload });\n    },\n    onNotice: (message) => notices.push(message),\n  };\n  const source = channel.start(host);\n\n  return {\n    source,\n    published,\n    notices,\n    snapshot(sessionId) {\n      const scope = sessions.find((candidate) => candidate.sessionId === sessionId) ?? sessions[0] ?? DEFAULT_SESSION;\n      return source.payloadFor(scope);\n    },\n    addSession(scope) {\n      sessions.push(scope);\n      source.sessionAdded?.(scope);\n    },\n    removeSession(sessionId) {\n      const index = sessions.findIndex((candidate) => candidate.sessionId === sessionId);\n      if (index >= 0) sessions.splice(index, 1);\n      source.sessionRemoved?.(sessionId);\n    },\n    close: () => source.close(),\n  };\n}\n"],"mappings":"AA8BA,SAAgB,EACd,EACA,EACA,EACiB,CACjB,IAAM,EAAkB,EAAQ,MAAM,CAAO,EAG7C,OAFI,IAAW,KAAa,CAAE,SAAU,EAAM,GAC9C,EAAQ,MAAM,EAAW,CAAM,EACxB,CAAE,SAAU,EAAK,EAC1B,CAsBA,MAAM,EAAmC,CAAE,UAAW,KAAM,IAAK,OAAQ,EASzE,SAAgB,EAAkB,EAAwB,EAAoC,CAAC,EAAsB,CACnH,IAAM,EAAW,CAAC,GAAI,EAAQ,UAAY,CAAC,CAAe,CAAE,EACtD,EAA4B,CAAC,EAC7B,EAAoB,CAAC,EAQrB,EAAS,EAAQ,MAAM,CAN3B,aAAgB,EAChB,SAAU,EAAW,IAAY,CAC/B,EAAU,KAAK,CAAE,KAAM,EAAQ,UAAW,YAAW,SAAQ,CAAC,CAChE,EACA,SAAW,GAAY,EAAQ,KAAK,CAAO,CAEb,CAAC,EAEjC,MAAO,CACL,SACA,YACA,UACA,SAAS,EAAW,CAClB,IAAM,EAAQ,EAAS,KAAM,GAAc,EAAU,YAAc,CAAS,GAAK,EAAS,IAAM,EAChG,OAAO,EAAO,WAAW,CAAK,CAChC,EACA,WAAW,EAAO,CAChB,EAAS,KAAK,CAAK,EACnB,EAAO,eAAe,CAAK,CAC7B,EACA,cAAc,EAAW,CACvB,IAAM,EAAQ,EAAS,UAAW,GAAc,EAAU,YAAc,CAAS,EAC7E,GAAS,GAAG,EAAS,OAAO,EAAO,CAAC,EACxC,EAAO,iBAAiB,CAAS,CACnC,EACA,UAAa,EAAO,MAAM,CAC5B,CACF"}
+{"version":3,"file":"channels.cjs","names":[],"sources":["../../../src/services/testing/channels.ts"],"sourcesContent":["import type {\n  ChannelFrame,\n  HubChannelHost,\n  HubChannelSource,\n  HubSessionScope,\n  WebHubChannel,\n} from '../../types/webHub.ts';\nimport type { SessionChannelContribution } from '../../types/webPlugin.ts';\n\n/**\n * The two halves of a plugin's data channel, driven the way the hub drives them.\n *\n * A channel is the one place a plugin parses input it did not produce, so its\n * parse gate is the boundary that matters, and a test that calls `apply`\n * directly steps straight over it. `driveChannel` sends a wire payload the way\n * the page does: through `parse` first, and nothing applied when it is\n * rejected.\n */\n\nexport interface ChannelDelivery {\n  /** Whether the parse gate accepted the payload. */\n  accepted: boolean;\n}\n\n/**\n * Sends one wire payload to a session channel.\n *\n * Returns whether the gate accepted it, so a test can assert a rejection\n * without knowing what the plugin's parsed shape looks like.\n */\nexport function driveChannel(\n  channel: SessionChannelContribution,\n  sessionId: string,\n  payload: unknown,\n): ChannelDelivery {\n  const parsed: unknown = channel.parse(payload);\n  if (parsed === null) return { accepted: false };\n  channel.apply(sessionId, parsed);\n  return { accepted: true };\n}\n\nexport interface HubChannelHarness {\n  /** The running source, as the hub holds it. */\n  source: HubChannelSource;\n  /** Everything the source pushed, in order. */\n  readonly published: readonly ChannelFrame[];\n  /** What the source told the hub. */\n  readonly notices: readonly string[];\n  /** The subscribe-time snapshot one session would receive; undefined means no frame. */\n  snapshot(sessionId?: string): unknown;\n  /** Registers a session with the source, as the hub does when one appears. */\n  addSession(scope: HubSessionScope): void;\n  removeSession(sessionId: string): void;\n  close(): void;\n}\n\nexport interface HubChannelHarnessOptions {\n  /** Sessions the hub already manages when the channel starts. */\n  sessions?: readonly HubSessionScope[];\n}\n\nconst DEFAULT_SESSION: HubSessionScope = { sessionId: 's1', cwd: '/repo' };\n\n/**\n * A plugin's hub channel, started against a real host.\n *\n * The hub calls `payloadFor` once per subscriber and pushes through `publish`\n * afterwards, and a channel that only answers one of those looks correct in a\n * test that exercises the other.\n */\nexport function hubChannelHarness(channel: WebHubChannel, options: HubChannelHarnessOptions = {}): HubChannelHarness {\n  const sessions = [...(options.sessions ?? [DEFAULT_SESSION])];\n  const published: ChannelFrame[] = [];\n  const notices: string[] = [];\n  const host: HubChannelHost = {\n    sessions: () => sessions,\n    publish: (sessionId, payload) => {\n      published.push({ type: channel.frameType, sessionId, payload });\n    },\n    requestSessionApi: () =>\n      Promise.resolve(Response.json({ error: 'No session API in the channel harness.' }, { status: 501 })),\n    onNotice: (message) => notices.push(message),\n  };\n  const source = channel.start(host);\n\n  return {\n    source,\n    published,\n    notices,\n    snapshot(sessionId) {\n      const scope = sessions.find((candidate) => candidate.sessionId === sessionId) ?? sessions[0] ?? DEFAULT_SESSION;\n      return source.payloadFor(scope);\n    },\n    addSession(scope) {\n      sessions.push(scope);\n      source.sessionAdded?.(scope);\n    },\n    removeSession(sessionId) {\n      const index = sessions.findIndex((candidate) => candidate.sessionId === sessionId);\n      if (index >= 0) sessions.splice(index, 1);\n      source.sessionRemoved?.(sessionId);\n    },\n    close: () => source.close(),\n  };\n}\n"],"mappings":"AA8BA,SAAgB,EACd,EACA,EACA,EACiB,CACjB,IAAM,EAAkB,EAAQ,MAAM,CAAO,EAG7C,OAFI,IAAW,KAAa,CAAE,SAAU,EAAM,GAC9C,EAAQ,MAAM,EAAW,CAAM,EACxB,CAAE,SAAU,EAAK,EAC1B,CAsBA,MAAM,EAAmC,CAAE,UAAW,KAAM,IAAK,OAAQ,EASzE,SAAgB,EAAkB,EAAwB,EAAoC,CAAC,EAAsB,CACnH,IAAM,EAAW,CAAC,GAAI,EAAQ,UAAY,CAAC,CAAe,CAAE,EACtD,EAA4B,CAAC,EAC7B,EAAoB,CAAC,EAUrB,EAAS,EAAQ,MAAM,CAR3B,aAAgB,EAChB,SAAU,EAAW,IAAY,CAC/B,EAAU,KAAK,CAAE,KAAM,EAAQ,UAAW,YAAW,SAAQ,CAAC,CAChE,EACA,sBACE,QAAQ,QAAQ,SAAS,KAAK,CAAE,MAAO,wCAAyC,EAAG,CAAE,OAAQ,GAAI,CAAC,CAAC,EACrG,SAAW,GAAY,EAAQ,KAAK,CAAO,CAEb,CAAC,EAEjC,MAAO,CACL,SACA,YACA,UACA,SAAS,EAAW,CAClB,IAAM,EAAQ,EAAS,KAAM,GAAc,EAAU,YAAc,CAAS,GAAK,EAAS,IAAM,EAChG,OAAO,EAAO,WAAW,CAAK,CAChC,EACA,WAAW,EAAO,CAChB,EAAS,KAAK,CAAK,EACnB,EAAO,eAAe,CAAK,CAC7B,EACA,cAAc,EAAW,CACvB,IAAM,EAAQ,EAAS,UAAW,GAAc,EAAU,YAAc,CAAS,EAC7E,GAAS,GAAG,EAAS,OAAO,EAAO,CAAC,EACxC,EAAO,iBAAiB,CAAS,CACnC,EACA,UAAa,EAAO,MAAM,CAC5B,CACF"}

package/dist/services/testing/channels.mjs

@@ -1,2 +1,2 @@
-function e(e,t,n){let r=e.parse(n);return r===null?{accepted:!1}:(e.apply(t,r),{accepted:!0})}const t={sessionId:`s1`,cwd:`/repo`};function n(e,n={}){let r=[...n.sessions??[t]],i=[],a=[],o=e.start({sessions:()=>r,publish:(t,n)=>{i.push({type:e.frameType,sessionId:t,payload:n})},onNotice:e=>a.push(e)});return{source:o,published:i,notices:a,snapshot(e){let n=r.find(t=>t.sessionId===e)??r[0]??t;return o.payloadFor(n)},addSession(e){r.push(e),o.sessionAdded?.(e)},removeSession(e){let t=r.findIndex(t=>t.sessionId===e);t>=0&&r.splice(t,1),o.sessionRemoved?.(e)},close:()=>o.close()}}export{e as driveChannel,n as hubChannelHarness};
+function e(e,t,n){let r=e.parse(n);return r===null?{accepted:!1}:(e.apply(t,r),{accepted:!0})}const t={sessionId:`s1`,cwd:`/repo`};function n(e,n={}){let r=[...n.sessions??[t]],i=[],a=[],o=e.start({sessions:()=>r,publish:(t,n)=>{i.push({type:e.frameType,sessionId:t,payload:n})},requestSessionApi:()=>Promise.resolve(Response.json({error:`No session API in the channel harness.`},{status:501})),onNotice:e=>a.push(e)});return{source:o,published:i,notices:a,snapshot(e){let n=r.find(t=>t.sessionId===e)??r[0]??t;return o.payloadFor(n)},addSession(e){r.push(e),o.sessionAdded?.(e)},removeSession(e){let t=r.findIndex(t=>t.sessionId===e);t>=0&&r.splice(t,1),o.sessionRemoved?.(e)},close:()=>o.close()}}export{e as driveChannel,n as hubChannelHarness};
 //# sourceMappingURL=channels.mjs.map

package/dist/services/testing/channels.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"channels.mjs","names":[],"sources":["../../../src/services/testing/channels.ts"],"sourcesContent":["import type {\n  ChannelFrame,\n  HubChannelHost,\n  HubChannelSource,\n  HubSessionScope,\n  WebHubChannel,\n} from '../../types/webHub.ts';\nimport type { SessionChannelContribution } from '../../types/webPlugin.ts';\n\n/**\n * The two halves of a plugin's data channel, driven the way the hub drives them.\n *\n * A channel is the one place a plugin parses input it did not produce, so its\n * parse gate is the boundary that matters, and a test that calls `apply`\n * directly steps straight over it. `driveChannel` sends a wire payload the way\n * the page does: through `parse` first, and nothing applied when it is\n * rejected.\n */\n\nexport interface ChannelDelivery {\n  /** Whether the parse gate accepted the payload. */\n  accepted: boolean;\n}\n\n/**\n * Sends one wire payload to a session channel.\n *\n * Returns whether the gate accepted it, so a test can assert a rejection\n * without knowing what the plugin's parsed shape looks like.\n */\nexport function driveChannel(\n  channel: SessionChannelContribution,\n  sessionId: string,\n  payload: unknown,\n): ChannelDelivery {\n  const parsed: unknown = channel.parse(payload);\n  if (parsed === null) return { accepted: false };\n  channel.apply(sessionId, parsed);\n  return { accepted: true };\n}\n\nexport interface HubChannelHarness {\n  /** The running source, as the hub holds it. */\n  source: HubChannelSource;\n  /** Everything the source pushed, in order. */\n  readonly published: readonly ChannelFrame[];\n  /** What the source told the hub. */\n  readonly notices: readonly string[];\n  /** The subscribe-time snapshot one session would receive; undefined means no frame. */\n  snapshot(sessionId?: string): unknown;\n  /** Registers a session with the source, as the hub does when one appears. */\n  addSession(scope: HubSessionScope): void;\n  removeSession(sessionId: string): void;\n  close(): void;\n}\n\nexport interface HubChannelHarnessOptions {\n  /** Sessions the hub already manages when the channel starts. */\n  sessions?: readonly HubSessionScope[];\n}\n\nconst DEFAULT_SESSION: HubSessionScope = { sessionId: 's1', cwd: '/repo' };\n\n/**\n * A plugin's hub channel, started against a real host.\n *\n * The hub calls `payloadFor` once per subscriber and pushes through `publish`\n * afterwards, and a channel that only answers one of those looks correct in a\n * test that exercises the other.\n */\nexport function hubChannelHarness(channel: WebHubChannel, options: HubChannelHarnessOptions = {}): HubChannelHarness {\n  const sessions = [...(options.sessions ?? [DEFAULT_SESSION])];\n  const published: ChannelFrame[] = [];\n  const notices: string[] = [];\n  const host: HubChannelHost = {\n    sessions: () => sessions,\n    publish: (sessionId, payload) => {\n      published.push({ type: channel.frameType, sessionId, payload });\n    },\n    onNotice: (message) => notices.push(message),\n  };\n  const source = channel.start(host);\n\n  return {\n    source,\n    published,\n    notices,\n    snapshot(sessionId) {\n      const scope = sessions.find((candidate) => candidate.sessionId === sessionId) ?? sessions[0] ?? DEFAULT_SESSION;\n      return source.payloadFor(scope);\n    },\n    addSession(scope) {\n      sessions.push(scope);\n      source.sessionAdded?.(scope);\n    },\n    removeSession(sessionId) {\n      const index = sessions.findIndex((candidate) => candidate.sessionId === sessionId);\n      if (index >= 0) sessions.splice(index, 1);\n      source.sessionRemoved?.(sessionId);\n    },\n    close: () => source.close(),\n  };\n}\n"],"mappings":"AA8BA,SAAgB,EACd,EACA,EACA,EACiB,CACjB,IAAM,EAAkB,EAAQ,MAAM,CAAO,EAG7C,OAFI,IAAW,KAAa,CAAE,SAAU,EAAM,GAC9C,EAAQ,MAAM,EAAW,CAAM,EACxB,CAAE,SAAU,EAAK,EAC1B,CAsBA,MAAM,EAAmC,CAAE,UAAW,KAAM,IAAK,OAAQ,EASzE,SAAgB,EAAkB,EAAwB,EAAoC,CAAC,EAAsB,CACnH,IAAM,EAAW,CAAC,GAAI,EAAQ,UAAY,CAAC,CAAe,CAAE,EACtD,EAA4B,CAAC,EAC7B,EAAoB,CAAC,EAQrB,EAAS,EAAQ,MAAM,CAN3B,aAAgB,EAChB,SAAU,EAAW,IAAY,CAC/B,EAAU,KAAK,CAAE,KAAM,EAAQ,UAAW,YAAW,SAAQ,CAAC,CAChE,EACA,SAAW,GAAY,EAAQ,KAAK,CAAO,CAEb,CAAC,EAEjC,MAAO,CACL,SACA,YACA,UACA,SAAS,EAAW,CAClB,IAAM,EAAQ,EAAS,KAAM,GAAc,EAAU,YAAc,CAAS,GAAK,EAAS,IAAM,EAChG,OAAO,EAAO,WAAW,CAAK,CAChC,EACA,WAAW,EAAO,CAChB,EAAS,KAAK,CAAK,EACnB,EAAO,eAAe,CAAK,CAC7B,EACA,cAAc,EAAW,CACvB,IAAM,EAAQ,EAAS,UAAW,GAAc,EAAU,YAAc,CAAS,EAC7E,GAAS,GAAG,EAAS,OAAO,EAAO,CAAC,EACxC,EAAO,iBAAiB,CAAS,CACnC,EACA,UAAa,EAAO,MAAM,CAC5B,CACF"}
+{"version":3,"file":"channels.mjs","names":[],"sources":["../../../src/services/testing/channels.ts"],"sourcesContent":["import type {\n  ChannelFrame,\n  HubChannelHost,\n  HubChannelSource,\n  HubSessionScope,\n  WebHubChannel,\n} from '../../types/webHub.ts';\nimport type { SessionChannelContribution } from '../../types/webPlugin.ts';\n\n/**\n * The two halves of a plugin's data channel, driven the way the hub drives them.\n *\n * A channel is the one place a plugin parses input it did not produce, so its\n * parse gate is the boundary that matters, and a test that calls `apply`\n * directly steps straight over it. `driveChannel` sends a wire payload the way\n * the page does: through `parse` first, and nothing applied when it is\n * rejected.\n */\n\nexport interface ChannelDelivery {\n  /** Whether the parse gate accepted the payload. */\n  accepted: boolean;\n}\n\n/**\n * Sends one wire payload to a session channel.\n *\n * Returns whether the gate accepted it, so a test can assert a rejection\n * without knowing what the plugin's parsed shape looks like.\n */\nexport function driveChannel(\n  channel: SessionChannelContribution,\n  sessionId: string,\n  payload: unknown,\n): ChannelDelivery {\n  const parsed: unknown = channel.parse(payload);\n  if (parsed === null) return { accepted: false };\n  channel.apply(sessionId, parsed);\n  return { accepted: true };\n}\n\nexport interface HubChannelHarness {\n  /** The running source, as the hub holds it. */\n  source: HubChannelSource;\n  /** Everything the source pushed, in order. */\n  readonly published: readonly ChannelFrame[];\n  /** What the source told the hub. */\n  readonly notices: readonly string[];\n  /** The subscribe-time snapshot one session would receive; undefined means no frame. */\n  snapshot(sessionId?: string): unknown;\n  /** Registers a session with the source, as the hub does when one appears. */\n  addSession(scope: HubSessionScope): void;\n  removeSession(sessionId: string): void;\n  close(): void;\n}\n\nexport interface HubChannelHarnessOptions {\n  /** Sessions the hub already manages when the channel starts. */\n  sessions?: readonly HubSessionScope[];\n}\n\nconst DEFAULT_SESSION: HubSessionScope = { sessionId: 's1', cwd: '/repo' };\n\n/**\n * A plugin's hub channel, started against a real host.\n *\n * The hub calls `payloadFor` once per subscriber and pushes through `publish`\n * afterwards, and a channel that only answers one of those looks correct in a\n * test that exercises the other.\n */\nexport function hubChannelHarness(channel: WebHubChannel, options: HubChannelHarnessOptions = {}): HubChannelHarness {\n  const sessions = [...(options.sessions ?? [DEFAULT_SESSION])];\n  const published: ChannelFrame[] = [];\n  const notices: string[] = [];\n  const host: HubChannelHost = {\n    sessions: () => sessions,\n    publish: (sessionId, payload) => {\n      published.push({ type: channel.frameType, sessionId, payload });\n    },\n    requestSessionApi: () =>\n      Promise.resolve(Response.json({ error: 'No session API in the channel harness.' }, { status: 501 })),\n    onNotice: (message) => notices.push(message),\n  };\n  const source = channel.start(host);\n\n  return {\n    source,\n    published,\n    notices,\n    snapshot(sessionId) {\n      const scope = sessions.find((candidate) => candidate.sessionId === sessionId) ?? sessions[0] ?? DEFAULT_SESSION;\n      return source.payloadFor(scope);\n    },\n    addSession(scope) {\n      sessions.push(scope);\n      source.sessionAdded?.(scope);\n    },\n    removeSession(sessionId) {\n      const index = sessions.findIndex((candidate) => candidate.sessionId === sessionId);\n      if (index >= 0) sessions.splice(index, 1);\n      source.sessionRemoved?.(sessionId);\n    },\n    close: () => source.close(),\n  };\n}\n"],"mappings":"AA8BA,SAAgB,EACd,EACA,EACA,EACiB,CACjB,IAAM,EAAkB,EAAQ,MAAM,CAAO,EAG7C,OAFI,IAAW,KAAa,CAAE,SAAU,EAAM,GAC9C,EAAQ,MAAM,EAAW,CAAM,EACxB,CAAE,SAAU,EAAK,EAC1B,CAsBA,MAAM,EAAmC,CAAE,UAAW,KAAM,IAAK,OAAQ,EASzE,SAAgB,EAAkB,EAAwB,EAAoC,CAAC,EAAsB,CACnH,IAAM,EAAW,CAAC,GAAI,EAAQ,UAAY,CAAC,CAAe,CAAE,EACtD,EAA4B,CAAC,EAC7B,EAAoB,CAAC,EAUrB,EAAS,EAAQ,MAAM,CAR3B,aAAgB,EAChB,SAAU,EAAW,IAAY,CAC/B,EAAU,KAAK,CAAE,KAAM,EAAQ,UAAW,YAAW,SAAQ,CAAC,CAChE,EACA,sBACE,QAAQ,QAAQ,SAAS,KAAK,CAAE,MAAO,wCAAyC,EAAG,CAAE,OAAQ,GAAI,CAAC,CAAC,EACrG,SAAW,GAAY,EAAQ,KAAK,CAAO,CAEb,CAAC,EAEjC,MAAO,CACL,SACA,YACA,UACA,SAAS,EAAW,CAClB,IAAM,EAAQ,EAAS,KAAM,GAAc,EAAU,YAAc,CAAS,GAAK,EAAS,IAAM,EAChG,OAAO,EAAO,WAAW,CAAK,CAChC,EACA,WAAW,EAAO,CAChB,EAAS,KAAK,CAAK,EACnB,EAAO,eAAe,CAAK,CAC7B,EACA,cAAc,EAAW,CACvB,IAAM,EAAQ,EAAS,UAAW,GAAc,EAAU,YAAc,CAAS,EAC7E,GAAS,GAAG,EAAS,OAAO,EAAO,CAAC,EACxC,EAAO,iBAAiB,CAAS,CACnC,EACA,UAAa,EAAO,MAAM,CAC5B,CACF"}

package/dist/types/webHub.d.cts

@@ -20,12 +20,27 @@ interface HubSessionScope {
   /** The session's working directory, for repo-scoped data sources. */
   cwd: string;
 }
+interface HubSessionApiRequest {
+  basePath: string;
+  path: string;
+  method: string;
+  body?: string | Uint8Array<ArrayBuffer> | null;
+  signal?: AbortSignal;
+}
+interface HubChannelConnection {
+  /** Opaque for one page socket lifetime. */
+  connectionId: string;
+}
 /** What the hub hands a channel when it starts. */
 interface HubChannelHost {
   /** Every session the hub currently manages. */
   sessions(): readonly HubSessionScope[];
   /** Live fan-out to the session's page subscribers. */
   publish(sessionId: string, payload: unknown): void;
+  /** Delivers only to the authenticated page socket named by connectionId. */
+  publishToConnection?(connectionId: string, sessionId: string, payload: unknown): boolean;
+  /** Authenticated machine-local transport to a session package API. */
+  requestSessionApi(scope: HubSessionScope, request: HubSessionApiRequest): Promise<Response>;
   onNotice(message: string): void;
 }
 /**
@@ -50,7 +65,13 @@ interface WebHubChannel {
   /** Wire frame type; globally unique across every loaded plugin. */
   frameType: string;
   start(host: HubChannelHost): HubChannelSource;
+  /** Allows an authenticated connection to acknowledge targeted frames after its session subscription changes. */
+  receiveWithoutSubscription?: boolean;
+  /** Receives only frames matching frameType and a live session scope. */
+  receive?(scope: HubSessionScope, payload: unknown, connection: HubChannelConnection): void;
+  /** The authenticated page socket has closed. */
+  disconnected?(connection: HubChannelConnection): void;
 }
 //#endregion
-export { ChannelFrame, HubChannelHost, HubChannelSource, HubSessionScope, WebHubChannel };
+export { ChannelFrame, HubChannelConnection, HubChannelHost, HubChannelSource, HubSessionApiRequest, HubSessionScope, WebHubChannel };
 //# sourceMappingURL=webHub.d.cts.map

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

@@ -1 +1 @@
-{"version":3,"file":"webHub.d.cts","names":[],"sources":["../../src/types/webHub.ts"],"mappings":";;;;;;;;;;;;UAYiB;EACf;EACA;EACA;;UAGe;EACf;;EAEA;;;UAIe;;EAEf,qBAAqB;;EAErB,QAAQ,mBAAmB;EAC3B,SAAS;;;;;;;UAQM;;EAEf,WAAW,OAAO;EAClB,cAAc,OAAO;EACrB,gBAAgB;;;;;;EAMhB,eAAe,OAAO,iBAAiB;EACvC;;UAGe;;EAEf;EACA,MAAM,MAAM,iBAAiB"}
+{"version":3,"file":"webHub.d.cts","names":[],"sources":["../../src/types/webHub.ts"],"mappings":";;;;;;;;;;;;UAYiB;EACf;EACA;EACA;;UAGe;EACf;;EAEA;;UAGe;EACf;EACA;EACA;EACA,gBAAgB,WAAW;EAC3B,SAAS;;UAGM;;EAEf;;;UAIe;;EAEf,qBAAqB;;EAErB,QAAQ,mBAAmB;;EAE3B,qBAAqB,sBAAsB,mBAAmB;;EAE9D,kBAAkB,OAAO,iBAAiB,SAAS,uBAAuB,QAAQ;EAClF,SAAS;;;;;;;UAQM;;EAEf,WAAW,OAAO;EAClB,cAAc,OAAO;EACrB,gBAAgB;;;;;;EAMhB,eAAe,OAAO,iBAAiB;EACvC;;UAGe;;EAEf;EACA,MAAM,MAAM,iBAAiB;;EAE7B;;EAEA,SAAS,OAAO,iBAAiB,kBAAkB,YAAY;;EAE/D,cAAc,YAAY"}

package/dist/types/webHub.d.mts

@@ -20,12 +20,27 @@ interface HubSessionScope {
   /** The session's working directory, for repo-scoped data sources. */
   cwd: string;
 }
+interface HubSessionApiRequest {
+  basePath: string;
+  path: string;
+  method: string;
+  body?: string | Uint8Array<ArrayBuffer> | null;
+  signal?: AbortSignal;
+}
+interface HubChannelConnection {
+  /** Opaque for one page socket lifetime. */
+  connectionId: string;
+}
 /** What the hub hands a channel when it starts. */
 interface HubChannelHost {
   /** Every session the hub currently manages. */
   sessions(): readonly HubSessionScope[];
   /** Live fan-out to the session's page subscribers. */
   publish(sessionId: string, payload: unknown): void;
+  /** Delivers only to the authenticated page socket named by connectionId. */
+  publishToConnection?(connectionId: string, sessionId: string, payload: unknown): boolean;
+  /** Authenticated machine-local transport to a session package API. */
+  requestSessionApi(scope: HubSessionScope, request: HubSessionApiRequest): Promise<Response>;
   onNotice(message: string): void;
 }
 /**
@@ -50,7 +65,13 @@ interface WebHubChannel {
   /** Wire frame type; globally unique across every loaded plugin. */
   frameType: string;
   start(host: HubChannelHost): HubChannelSource;
+  /** Allows an authenticated connection to acknowledge targeted frames after its session subscription changes. */
+  receiveWithoutSubscription?: boolean;
+  /** Receives only frames matching frameType and a live session scope. */
+  receive?(scope: HubSessionScope, payload: unknown, connection: HubChannelConnection): void;
+  /** The authenticated page socket has closed. */
+  disconnected?(connection: HubChannelConnection): void;
 }
 //#endregion
-export { ChannelFrame, HubChannelHost, HubChannelSource, HubSessionScope, WebHubChannel };
+export { ChannelFrame, HubChannelConnection, HubChannelHost, HubChannelSource, HubSessionApiRequest, HubSessionScope, WebHubChannel };
 //# sourceMappingURL=webHub.d.mts.map

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

@@ -1 +1 @@
-{"version":3,"file":"webHub.d.mts","names":[],"sources":["../../src/types/webHub.ts"],"mappings":";;;;;;;;;;;;UAYiB;EACf;EACA;EACA;;UAGe;EACf;;EAEA;;;UAIe;;EAEf,qBAAqB;;EAErB,QAAQ,mBAAmB;EAC3B,SAAS;;;;;;;UAQM;;EAEf,WAAW,OAAO;EAClB,cAAc,OAAO;EACrB,gBAAgB;;;;;;EAMhB,eAAe,OAAO,iBAAiB;EACvC;;UAGe;;EAEf;EACA,MAAM,MAAM,iBAAiB"}
+{"version":3,"file":"webHub.d.mts","names":[],"sources":["../../src/types/webHub.ts"],"mappings":";;;;;;;;;;;;UAYiB;EACf;EACA;EACA;;UAGe;EACf;;EAEA;;UAGe;EACf;EACA;EACA;EACA,gBAAgB,WAAW;EAC3B,SAAS;;UAGM;;EAEf;;;UAIe;;EAEf,qBAAqB;;EAErB,QAAQ,mBAAmB;;EAE3B,qBAAqB,sBAAsB,mBAAmB;;EAE9D,kBAAkB,OAAO,iBAAiB,SAAS,uBAAuB,QAAQ;EAClF,SAAS;;;;;;;UAQM;;EAEf,WAAW,OAAO;EAClB,cAAc,OAAO;EACrB,gBAAgB;;;;;;EAMhB,eAAe,OAAO,iBAAiB;EACvC;;UAGe;;EAEf;EACA,MAAM,MAAM,iBAAiB;;EAE7B;;EAEA,SAAS,OAAO,iBAAiB,kBAAkB,YAAY;;EAE/D,cAAc,YAAY"}

package/dist/types/webPlugin.d.cts

@@ -10,9 +10,11 @@ import { ComponentType, ReactNode } from "react";
  * @tanstack/store, @tanstack/react-store, this contract,
  * @agimon-ai/doompi-web-components, and the package's own web/ and src/types
  * modules; never another plugin, a node builtin, or a server framework, which
- * the host bundle would swallow. Per-session state takes the shape
- * defineSessionStore gives it. Tailwind utility classes must appear as
- * complete literal strings so the host's class scanner can see them.
+ * modules; never another plugin, a node builtin, or a server framework, which
+ * the host bundle would swallow. Page-wide state takes the shape
+ * defineGlobalStore gives it; per-session state takes the shape defineSessionStore
+ * gives it. Tailwind utility classes must appear as complete literal strings so
+ * the host's class scanner can see them.
  *
  * Plugins are independent: none depends on another, any of them may be added
  * or removed at the next sync, and every relation between two plugins (a fill
@@ -105,6 +107,81 @@ 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;
+}
+/** One repository the host has admitted into repository-scoped settings. */
+interface RepositorySettingsRepository {
+  /** Opaque hub-issued identity. Package APIs resolve this through DoomApiContext. */
+  id: string;
+  /** Last path segment, for compact pickers and headings. */
+  name: string;
+  /** Display-only absolute path. APIs must use id rather than trusting this value. */
+  path: string;
+  /** True while at least one session is open inside this repository. */
+  active: boolean;
+}
+/** Props for a package panel placed inside the host's repository control plane. */
+interface RepositorySettingsPanelProps {
+  repository: RepositorySettingsRepository | null;
+  /** Same-origin request routed through the host's sealed transport when remote. */
+  request: (input: string, init?: RequestInit) => Promise<Response>;
+  /** The same transport, retrying once after the host's fresh passkey gesture. */
+  requestWithStepUp: (input: string, init?: RequestInit) => Promise<Response>;
+}
+/** One package-owned panel below the host's repository selection controls. */
+interface RepositorySettingsPanelContribution {
+  label: string;
+  detail: string;
+  /** Sort position below the host controls; lower first, then plugin id. */
+  order?: number;
+  component: ComponentType<RepositorySettingsPanelProps>;
+}
+/**
+ * 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,9 +291,31 @@ 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;
+  /** Keeps the group visible below the dock's scrolling ordinary groups. */
+  placement?: 'bottom';
   /** Sort position in the dock; lower first, name breaks ties. */
   order?: number;
 }
+/** Page-wide plugin state shared by its runtime, channels, and every rendered contribution. */
+interface GlobalStore<T> {
+  readonly store: Store<T>;
+  /** Replaces the value; an updater returning the current value publishes nothing. */
+  update(updater: (current: T) => T): void;
+  reset(): void;
+}
 /**
  * One session-scoped data channel: the hub pushes ChannelFrame payloads whose
  * frame type equals `channel`; parse is the validation gate at the boundary
@@ -289,6 +388,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,11 +450,14 @@ 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. */
+/** What a plugin's optional runtime may do through the page's hub socket. */
 interface WebPluginRuntime {
   sendSessionFrame: SessionFrameSender;
   sendHubFrame(frame: Record<string, unknown>): void;
+  onHubConnected(listener: () => void): () => void;
 }
 interface WebPluginDefinition {
   id: string;
@@ -324,6 +471,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 +480,16 @@ 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[];
+  /**
+   * A package-owned management panel inside the host's repository page. The
+   * host owns repository identity and passes only repositories it admitted.
+   */
+  repositorySettingsPanel?: RepositorySettingsPanelContribution;
   /** 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 +498,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, GlobalStore, LeaderBindingBase, LeaderBindingContribution, LeaderKeyContribution, MinorModeContribution, PaletteCommandContext, PaletteCommandContribution, RepositorySettingsPanelContribution, RepositorySettingsPanelProps, RepositorySettingsRepository, 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":"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"}

package/dist/types/webPlugin.d.mts

@@ -10,9 +10,11 @@ import { ComponentType, ReactNode } from "react";
  * @tanstack/store, @tanstack/react-store, this contract,
  * @agimon-ai/doompi-web-components, and the package's own web/ and src/types
  * modules; never another plugin, a node builtin, or a server framework, which
- * the host bundle would swallow. Per-session state takes the shape
- * defineSessionStore gives it. Tailwind utility classes must appear as
- * complete literal strings so the host's class scanner can see them.
+ * modules; never another plugin, a node builtin, or a server framework, which
+ * the host bundle would swallow. Page-wide state takes the shape
+ * defineGlobalStore gives it; per-session state takes the shape defineSessionStore
+ * gives it. Tailwind utility classes must appear as complete literal strings so
+ * the host's class scanner can see them.
  *
  * Plugins are independent: none depends on another, any of them may be added
  * or removed at the next sync, and every relation between two plugins (a fill
@@ -105,6 +107,81 @@ 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;
+}
+/** One repository the host has admitted into repository-scoped settings. */
+interface RepositorySettingsRepository {
+  /** Opaque hub-issued identity. Package APIs resolve this through DoomApiContext. */
+  id: string;
+  /** Last path segment, for compact pickers and headings. */
+  name: string;
+  /** Display-only absolute path. APIs must use id rather than trusting this value. */
+  path: string;
+  /** True while at least one session is open inside this repository. */
+  active: boolean;
+}
+/** Props for a package panel placed inside the host's repository control plane. */
+interface RepositorySettingsPanelProps {
+  repository: RepositorySettingsRepository | null;
+  /** Same-origin request routed through the host's sealed transport when remote. */
+  request: (input: string, init?: RequestInit) => Promise<Response>;
+  /** The same transport, retrying once after the host's fresh passkey gesture. */
+  requestWithStepUp: (input: string, init?: RequestInit) => Promise<Response>;
+}
+/** One package-owned panel below the host's repository selection controls. */
+interface RepositorySettingsPanelContribution {
+  label: string;
+  detail: string;
+  /** Sort position below the host controls; lower first, then plugin id. */
+  order?: number;
+  component: ComponentType<RepositorySettingsPanelProps>;
+}
+/**
+ * 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,9 +291,31 @@ 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;
+  /** Keeps the group visible below the dock's scrolling ordinary groups. */
+  placement?: 'bottom';
   /** Sort position in the dock; lower first, name breaks ties. */
   order?: number;
 }
+/** Page-wide plugin state shared by its runtime, channels, and every rendered contribution. */
+interface GlobalStore<T> {
+  readonly store: Store<T>;
+  /** Replaces the value; an updater returning the current value publishes nothing. */
+  update(updater: (current: T) => T): void;
+  reset(): void;
+}
 /**
  * One session-scoped data channel: the hub pushes ChannelFrame payloads whose
  * frame type equals `channel`; parse is the validation gate at the boundary
@@ -289,6 +388,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,11 +450,14 @@ 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. */
+/** What a plugin's optional runtime may do through the page's hub socket. */
 interface WebPluginRuntime {
   sendSessionFrame: SessionFrameSender;
   sendHubFrame(frame: Record<string, unknown>): void;
+  onHubConnected(listener: () => void): () => void;
 }
 interface WebPluginDefinition {
   id: string;
@@ -324,6 +471,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 +480,16 @@ 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[];
+  /**
+   * A package-owned management panel inside the host's repository page. The
+   * host owns repository identity and passes only repositories it admitted.
+   */
+  repositorySettingsPanel?: RepositorySettingsPanelContribution;
   /** 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 +498,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, GlobalStore, LeaderBindingBase, LeaderBindingContribution, LeaderKeyContribution, MinorModeContribution, PaletteCommandContext, PaletteCommandContribution, RepositorySettingsPanelContribution, RepositorySettingsPanelProps, RepositorySettingsRepository, 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":"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"}

package/package.json

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