@astrale-os/shell 0.1.0

package/dist/domain/window/lifecycle.js

@@ -0,0 +1,36 @@
+/**
+ * Pure state-machine transition. Used by the lifecycle controller —
+ * no timers, no side effects here.
+ */
+export function transition(state, event) {
+    switch (state) {
+        case 'active':
+            if (event.kind === 'hide')
+                return { ok: true, next: 'hidden' };
+            if (event.kind === 'requestClose')
+                return { ok: true, next: 'closing' };
+            if (event.kind === 'forceClose')
+                return { ok: true, next: 'closed' };
+            break;
+        case 'hidden':
+            if (event.kind === 'restore')
+                return { ok: true, next: 'active' };
+            if (event.kind === 'requestClose')
+                return { ok: true, next: 'closing' };
+            if (event.kind === 'forceClose')
+                return { ok: true, next: 'closed' };
+            break;
+        case 'closing':
+            if (event.kind === 'closeAck')
+                return { ok: true, next: 'closed' };
+            if (event.kind === 'closeRefuse')
+                return { ok: true, next: 'active' };
+            if (event.kind === 'forceClose')
+                return { ok: true, next: 'closed' };
+            break;
+        case 'closed':
+            // Terminal — no transitions out.
+            break;
+    }
+    return { ok: false, reason: `invalid transition ${state}.${event.kind}` };
+}

package/dist/domain/window/window.d.ts

@@ -0,0 +1,12 @@
+import type { WindowCapabilities } from './config';
+export type WindowState = 'active' | 'hidden' | 'closing' | 'closed';
+export interface Window {
+    readonly windowId: string;
+    readonly functionId: string;
+    readonly targetNodeId?: string;
+    readonly isolation: 'sandboxed' | 'shared';
+    readonly state: WindowState;
+    readonly delegationToken: string | null;
+    readonly capabilities: WindowCapabilities;
+}
+//# sourceMappingURL=window.d.ts.map

package/dist/domain/window/window.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"window.d.ts","sourceRoot":"","sources":["../../../src/domain/window/window.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,UAAU,CAAA;AAElD,MAAM,MAAM,WAAW,GAAG,QAAQ,GAAG,QAAQ,GAAG,SAAS,GAAG,QAAQ,CAAA;AAEpE,MAAM,WAAW,MAAM;IACrB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;IAC3B,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAA;IAC9B,QAAQ,CAAC,SAAS,EAAE,WAAW,GAAG,QAAQ,CAAA;IAC1C,QAAQ,CAAC,KAAK,EAAE,WAAW,CAAA;IAC3B,QAAQ,CAAC,eAAe,EAAE,MAAM,GAAG,IAAI,CAAA;IACvC,QAAQ,CAAC,YAAY,EAAE,kBAAkB,CAAA;CAC1C"}

package/dist/domain/window/window.js

@@ -0,0 +1 @@
+export {};

package/dist/index.d.ts

@@ -0,0 +1,42 @@
+export type { ErrorCode } from './domain/message/errors';
+export type { IntentRegistry, CtrlRegistry, ViewRef } from './domain/message/registries';
+export type { ShellMessage, IntentMessage, IntentEnvelope, CtrlMessage, ErrorMessage, } from './domain/message/types';
+export type { WindowConfig, WindowCapabilities, SandboxProfile } from './domain/window/config';
+export type { Window, WindowState } from './domain/window/window';
+export { transition as lifecycleTransition } from './domain/window/lifecycle';
+export type { LifecycleEvent, TransitionResult } from './domain/window/lifecycle';
+export type { IntentMiddleware } from './domain/intent/pipeline';
+export type { IntentRouter } from './domain/intent/router';
+export { loggingMiddleware } from './domain/intent/middleware/logging';
+export type { LoggingConfig, LoggingEntry, LoggingSink } from './domain/intent/middleware/logging';
+export { capabilitiesMiddleware } from './domain/intent/middleware/capabilities';
+export type { CapabilitiesConfig, CapabilityLookup, CapabilityViolation, } from './domain/intent/middleware/capabilities';
+export { rateLimitMiddleware } from './domain/intent/middleware/rate-limit';
+export type { RateLimitConfig, RateLimitViolation } from './domain/intent/middleware/rate-limit';
+export type { DelegationScope, DelegationToken, TokenState } from './domain/identity/delegation';
+export { stateOf, isExpired } from './domain/identity/delegation';
+export type { Transport } from './ports/transport';
+export type { ShellAdapter, WindowHandle } from './ports/shell-adapter';
+export type { KernelClient } from './ports/kernel-client';
+export { createKernelClientAdapter } from './adapters/kernel-client.adapter';
+export type { KernelClientAdapter, CreateKernelClientAdapterOpts, } from './adapters/kernel-client.adapter';
+export { createMessagePortTransport } from './adapters/message-port.transport';
+export type { MessagePortTransportConfig } from './adapters/message-port.transport';
+export { createIframeShellAdapter } from './adapters/iframe.shell-adapter';
+export type { IframeShellAdapterConfig } from './adapters/iframe.shell-adapter';
+export type { Shell, ShellConfig, StandaloneConfig, SandboxedConfig, MountParams, MountedWindow, CloseResult, ParentChannel, ChildrenChannel, MessageDirection, MessageHandler, ObserverHandler, } from './application/shell';
+export { createShell } from './application/shell';
+export { runParentHandshake } from './application/windowing/handshake';
+export type { HandshakeParams, HandshakeError, HandshakeResult, } from './application/windowing/handshake';
+export { performChildInit } from './application/windowing/child-init';
+export type { ChildInitParams, ChildInitResult } from './application/windowing/child-init';
+export { createTokenRefresher } from './application/windowing/token-refresh';
+export type { TokenRefreshConfig, TokenRefresher } from './application/windowing/token-refresh';
+export { createIntentPipeline } from './application/intent/pipeline-runner';
+export type { IntentPipeline } from './application/intent/pipeline-runner';
+export { createIntentRouter } from './application/intent/router';
+export type { IntentRouterController, IntentRouterConfig, IntentDecision, IntentOrigin, IntentPolicy, IntentContext, LocalIntentHandler, } from './application/intent/router';
+export { requestIntent, replyToIntent, requestAccess } from './application/intent/request';
+export { INIT_REQUEST_TYPE, INIT_RESPONSE_TYPE, isInitRequest, isInitResponse, } from './application/windowing/protocol';
+export type { InitRequestMessage, InitResponseMessage } from './application/windowing/protocol';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/index.js

@@ -0,0 +1,20 @@
+export { transition as lifecycleTransition } from './domain/window/lifecycle';
+export { loggingMiddleware } from './domain/intent/middleware/logging';
+export { capabilitiesMiddleware } from './domain/intent/middleware/capabilities';
+export { rateLimitMiddleware } from './domain/intent/middleware/rate-limit';
+export { stateOf, isExpired } from './domain/identity/delegation';
+// ─── adapters ───────────────────────────────────────────────────────────────
+export { createKernelClientAdapter } from './adapters/kernel-client.adapter';
+export { createMessagePortTransport } from './adapters/message-port.transport';
+export { createIframeShellAdapter } from './adapters/iframe.shell-adapter';
+export { createShell } from './application/shell';
+// ─── application/windowing (advanced / testing) ─────────────────────────────
+export { runParentHandshake } from './application/windowing/handshake';
+export { performChildInit } from './application/windowing/child-init';
+export { createTokenRefresher } from './application/windowing/token-refresh';
+// ─── application/intent (advanced / testing) ────────────────────────────────
+export { createIntentPipeline } from './application/intent/pipeline-runner';
+export { createIntentRouter } from './application/intent/router';
+export { requestIntent, replyToIntent, requestAccess } from './application/intent/request';
+// ─── Init-request protocol (shared with host pages) ─────────────────────────
+export { INIT_REQUEST_TYPE, INIT_RESPONSE_TYPE, isInitRequest, isInitResponse, } from './application/windowing/protocol';

package/dist/ports/kernel-client.d.ts

@@ -0,0 +1,33 @@
+export interface KernelClient {
+    call(path: string, params: unknown): Promise<unknown>;
+    /**
+     * Produce a credential usable by a child shell.
+     *
+     * v1: returns a fresh identity credential scoped to the current principal.
+     * Future (SDK v2): will accept `{ functionId }` to scope the delegation
+     * to a specific Function — tracked in `.dev/todo/shell-sdk-v2-delegation.md`.
+     */
+    mintDelegation(): Promise<string>;
+    /**
+     * Return the JWT this shell currently uses to authenticate `call`. Iframes
+     * use it to make their own authenticated HTTP requests to the kernel —
+     * e.g. when a third-party SDK like Vercel AI's `useChat` issues a raw
+     * `fetch()` that can't run through `call()`. Callers form the Authorization
+     * header themselves: `Authorization: \`Bearer ${shell.kernel.authToken()}\``.
+     *
+     * The value is the *current* token; the parent shell auto-refreshes it
+     * before expiry, so always read fresh on each request rather than caching.
+     */
+    authToken(): string;
+    /**
+     * URL of the kernel this shell talks to. Pair with `authToken()` when an
+     * iframe needs to make a raw `fetch()` from a third-party SDK (e.g.
+     * Vercel AI's `useChat`): the kernel-issued JWT's `aud` matches the
+     * kernel's own issuer, so requests must target the kernel directly. If
+     * a sandboxed iframe POSTs to its own `window.location.origin` (the
+     * worker hosting the iframe), the worker's audience check rejects the
+     * cred with "Credential audience mismatch".
+     */
+    readonly url: string;
+}
+//# sourceMappingURL=kernel-client.d.ts.map

package/dist/ports/kernel-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"kernel-client.d.ts","sourceRoot":"","sources":["../../src/ports/kernel-client.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,YAAY;IAC3B,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAA;IACrD;;;;;;OAMG;IACH,cAAc,IAAI,OAAO,CAAC,MAAM,CAAC,CAAA;IACjC;;;;;;;;;OASG;IACH,SAAS,IAAI,MAAM,CAAA;IACnB;;;;;;;;OAQG;IACH,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;CACrB"}

package/dist/ports/kernel-client.js

@@ -0,0 +1 @@
+export {};

package/dist/ports/shell-adapter.d.ts

@@ -0,0 +1,13 @@
+import type { WindowConfig } from '../domain/window/config';
+export interface WindowHandle {
+    readonly element: HTMLIFrameElement | HTMLElement;
+    readonly port: MessagePort | null;
+    readonly origin: string;
+}
+export interface ShellAdapter {
+    mount(config: WindowConfig): {
+        handle: WindowHandle;
+        dispose: () => void;
+    };
+}
+//# sourceMappingURL=shell-adapter.d.ts.map

package/dist/ports/shell-adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shell-adapter.d.ts","sourceRoot":"","sources":["../../src/ports/shell-adapter.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAA;AAE3D,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,OAAO,EAAE,iBAAiB,GAAG,WAAW,CAAA;IACjD,QAAQ,CAAC,IAAI,EAAE,WAAW,GAAG,IAAI,CAAA;IACjC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CACxB;AAED,MAAM,WAAW,YAAY;IAC3B,KAAK,CAAC,MAAM,EAAE,YAAY,GAAG;QAAE,MAAM,EAAE,YAAY,CAAC;QAAC,OAAO,EAAE,MAAM,IAAI,CAAA;KAAE,CAAA;CAC3E"}

package/dist/ports/shell-adapter.js

@@ -0,0 +1 @@
+export {};

package/dist/ports/transport.d.ts

@@ -0,0 +1,7 @@
+import type { ShellMessage } from '../domain/message/types';
+export interface Transport {
+    send(message: ShellMessage): void;
+    onMessage(handler: (message: ShellMessage) => void): void;
+    close(): void;
+}
+//# sourceMappingURL=transport.d.ts.map

package/dist/ports/transport.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transport.d.ts","sourceRoot":"","sources":["../../src/ports/transport.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAA;AAE3D,MAAM,WAAW,SAAS;IACxB,IAAI,CAAC,OAAO,EAAE,YAAY,GAAG,IAAI,CAAA;IACjC,SAAS,CAAC,OAAO,EAAE,CAAC,OAAO,EAAE,YAAY,KAAK,IAAI,GAAG,IAAI,CAAA;IACzD,KAAK,IAAI,IAAI,CAAA;CACd"}

package/dist/ports/transport.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@astrale-os/shell",
+  "version": "0.1.0",
+  "description": "Astrale Shell SDK — parent/child/kernel communication",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/astrale-os/shell.git",
+    "directory": "packages/shell"
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "publishConfig": {
+    "access": "restricted",
+    "registry": "https://npm.pkg.github.com"
+  },
+  "dependencies": {
+    "@astrale-os/kernel-client": ">=0.1.0 <1.0.0",
+    "@astrale-os/kernel-core": ">=0.4.1 <1.0.0"
+  },
+  "devDependencies": {
+    "@typescript/native-preview": "latest",
+    "typescript": "~6.0.1-rc"
+  },
+  "scripts": {
+    "build": "tsgo",
+    "clean": "rm -rf dist *.tsbuildinfo",
+    "typecheck": "tsgo --noEmit",
+    "preinstall": "node .check-workspace.cjs"
+  }
+}

package/src/adapters/iframe.shell-adapter.ts

@@ -0,0 +1,68 @@
+import type { SandboxProfile } from '../domain/window/config'
+import type { ShellAdapter, WindowHandle } from '../ports/shell-adapter'
+
+export type IframeShellAdapterConfig = {
+  /**
+   * Optional class list applied to every iframe created by this adapter.
+   * Useful for consistent styling without leaking styling into the SDK.
+   */
+  readonly className?: string
+}
+
+const DEFAULT_SANDBOX: SandboxProfile = {
+  allowScripts: true,
+  allowForms: false,
+  allowPopups: false,
+  allowSameOrigin: false,
+  allowModals: false,
+}
+
+export function createIframeShellAdapter(config: IframeShellAdapterConfig = {}): ShellAdapter {
+  return {
+    mount(windowConfig) {
+      if (windowConfig.isolation !== 'sandboxed') {
+        throw new Error(
+          `iframe adapter only supports sandboxed windows, got '${windowConfig.isolation}'`,
+        )
+      }
+
+      const element = document.createElement('iframe')
+      element.dataset.astraleFunctionId = windowConfig.functionId
+      if (config.className) element.className = config.className
+
+      // `sandbox: null` is an explicit opt-out — leave the iframe without a
+      // `sandbox` attribute (only cross-origin isolation applies). Used by
+      // the GUI for first-party trusted views (see trusted-view-origins).
+      if (windowConfig.sandbox !== null) {
+        const profile = windowConfig.sandbox ?? DEFAULT_SANDBOX
+        element.setAttribute('sandbox', sandboxAttrFor(profile))
+      }
+      element.setAttribute('allow', 'clipboard-read; clipboard-write')
+      element.setAttribute('loading', 'eager')
+      element.setAttribute('referrerpolicy', 'no-referrer')
+
+      const handle: WindowHandle = {
+        element,
+        port: null,
+        origin: '',
+      }
+
+      return {
+        handle,
+        dispose: () => {
+          element.remove()
+        },
+      }
+    },
+  }
+}
+
+function sandboxAttrFor(profile: SandboxProfile): string {
+  const tokens: string[] = []
+  if (profile.allowScripts) tokens.push('allow-scripts')
+  if (profile.allowForms) tokens.push('allow-forms')
+  if (profile.allowPopups) tokens.push('allow-popups')
+  if (profile.allowSameOrigin) tokens.push('allow-same-origin')
+  if (profile.allowModals) tokens.push('allow-modals')
+  return tokens.join(' ')
+}

package/src/adapters/kernel-client.adapter.ts

@@ -0,0 +1,138 @@
+import {
+  type CallOptions,
+  type CredentialInput,
+  type FnMap,
+  type FunctionSchema,
+} from '@astrale-os/kernel-client'
+import { ClientSession, type ClientSessionConfig } from '@astrale-os/kernel-client/session'
+
+import { identityMethod } from '../domain/identity/path'
+import { createSelfResolver, WHOAMI_PATH } from '../domain/identity/resolve-self'
+
+// Untyped FnMap — the shell uses string paths, not typed method keys.
+type AnyFnMap = FnMap
+
+/**
+ * Low-level kernel adapter — wraps a `ClientSession` (the post-v2 orchestration
+ * layer above `KernelClient`).
+ *
+ * Methods take an explicit credential. The application-layer facade
+ * manages which credential to use.
+ *
+ * Remote-domain redirects are followed transparently: when the kernel
+ * responds with a `redirect` result (pointing at an external worker URL),
+ * the ClientSession mints a worker-scoped delegation credential — for the
+ * audience the kernel carries on the redirect (`CallRedirection.iss`, the
+ * target's own identity) — and re-dials the target URL with it. So
+ * `shell.kernel.call(...)` "just works" for methods whose Function has a
+ * `binding.remoteUrl`.
+ */
+export type KernelClientAdapter = {
+  call(
+    method: string,
+    params: unknown,
+    credential: CredentialInput,
+    opts?: CallOptions,
+  ): Promise<unknown>
+  load(schemas: FunctionSchema[]): void
+  disconnect(): void
+  readonly url: string
+}
+
+export type CreateKernelClientAdapterOpts = {
+  url: string
+  schema?: FunctionSchema[]
+  requestTimeout?: number
+  /**
+   * Returns the current base credential. When provided, the adapter wires a
+   * `delegation: { mint }` on the ClientSession so cross-origin redirects
+   * (kernel → worker) are followed with a fresh worker-scoped delegation
+   * minted from the active identity. Without it,
+   * ClientSession falls back to the base credential and workers reject
+   * with `Credential audience mismatch`.
+   */
+  getCredential?: () => CredentialInput
+  /**
+   * Explicit identity node/path to use as the delegation mint subject. When
+   * omitted, the authenticated caller is resolved via `whoami` (so a cookie-fronted
+   * SPA mints as the logged-in user). Set this only to pin a subject; if set it
+   * MUST match the principal `getCredential()` authenticates as, or
+   * `mintDelegationCredential`'s self-invariant rejects the mint.
+   */
+  mintIdentity?: string
+  /**
+   * Wire-layer `fetch` shim, forwarded to the underlying `KernelClient`s.
+   * Lets a same-origin SPA inject `credentials:'include'` + refresh-on-401 so
+   * a router can unseal a cookie into a Bearer (the parent holds no token).
+   * Default: global fetch — sandboxed child views never set it.
+   */
+  fetch?: typeof fetch
+}
+
+export function createKernelClientAdapter(
+  opts: CreateKernelClientAdapterOpts,
+): KernelClientAdapter {
+  let session: ClientSession<AnyFnMap> | null = null
+  const config: ClientSessionConfig<AnyFnMap> = {
+    default: opts.url,
+    // Identity is supplied per-call via `opts.credential`; no picker bound.
+    // No `delegationPolicy` → ClientSession's default `allowAllDelegations`
+    // mints for the audience the kernel carries on the redirect
+    // (`CallRedirection.iss`), which is exactly what the target worker verifies.
+    identity: undefined,
+  }
+  if (opts.schema) config.schema = opts.schema
+  if (opts.fetch) config.fetch = opts.fetch
+  if (opts.getCredential) {
+    const getCred = opts.getCredential
+    const explicitMintIdentity = opts.mintIdentity
+    const resolveSelf = createSelfResolver()
+    config.delegation = {
+      mint: async (audience, delegation) => {
+        if (!session) throw new Error('ClientSession not initialised')
+        const s = session
+        const subject =
+          explicitMintIdentity ??
+          (await resolveSelf(() =>
+            s.call(WHOAMI_PATH, {}, { credential: getCred(), skipDelegation: true }),
+          ))
+        const result = await s.call(
+          identityMethod(subject, 'mintDelegationCredential'),
+          { audience, delegation, ttl: 3600 },
+          { credential: getCred(), skipDelegation: true },
+        )
+        if (typeof result !== 'string') {
+          throw new Error(`mintDelegationCredential returned non-string: ${typeof result}`)
+        }
+        return { credential: result, ttl: 3600 }
+      },
+    }
+  }
+  session = new ClientSession<AnyFnMap>(config)
+  const ready = session
+
+  return {
+    url: opts.url,
+
+    call(method, params, credential, callOpts) {
+      const sessionOpts: Parameters<typeof ready.call>[2] = { credential }
+      if (callOpts?.timeout !== undefined) sessionOpts.timeout = callOpts.timeout
+      if (callOpts?.signal !== undefined) sessionOpts.signal = callOpts.signal
+      if (callOpts?.class !== undefined) sessionOpts.class = callOpts.class
+      if (callOpts?.transport !== undefined) sessionOpts.transport = callOpts.transport
+      if (callOpts?.protocol !== undefined) sessionOpts.protocol = callOpts.protocol
+      if (callOpts?.correlationId !== undefined) sessionOpts.correlationId = callOpts.correlationId
+      if (callOpts?.self !== undefined) sessionOpts.self = callOpts.self
+      if (callOpts?.url !== undefined) sessionOpts.url = callOpts.url
+      return ready.call(method, params, sessionOpts)
+    },
+
+    load(schemas) {
+      ready.registry.load(schemas)
+    },
+
+    disconnect() {
+      ready.disconnect()
+    },
+  }
+}

package/src/adapters/message-port.transport.ts

@@ -0,0 +1,50 @@
+import type { ShellMessage } from '../domain/message/types'
+import type { Transport } from '../ports/transport'
+
+export type MessagePortTransportConfig = {
+  port: MessagePort
+  onClose?: () => void
+}
+
+export function createMessagePortTransport(config: MessagePortTransportConfig): Transport {
+  const { port, onClose } = config
+
+  let closed = false
+  const handlers = new Set<(message: ShellMessage) => void>()
+
+  port.onmessage = (event: MessageEvent) => {
+    if (closed) return
+    const message = event.data as ShellMessage
+    for (const handler of handlers) handler(message)
+  }
+
+  port.onmessageerror = () => {
+    if (closed) return
+    close()
+  }
+
+  port.start()
+
+  function close() {
+    if (closed) return
+    closed = true
+    handlers.clear()
+    try {
+      port.close()
+    } catch {
+      // port may already be closed
+    }
+    onClose?.()
+  }
+
+  return {
+    send(message: ShellMessage) {
+      if (closed) return
+      port.postMessage(message)
+    },
+    onMessage(handler) {
+      handlers.add(handler)
+    },
+    close,
+  }
+}

package/src/application/channels/children-channel.ts

@@ -0,0 +1,112 @@
+import type { ShellMessage } from '../../domain/message/types'
+import type { Transport } from '../../ports/transport'
+import type { MessageObserver } from './observer'
+import type { MessageOf, MessageType } from './types'
+
+export interface ChildrenChannel {
+  send(windowId: string, message: ShellMessage): void
+  on<T extends MessageType>(
+    type: T,
+    handler: (windowId: string, message: MessageOf<T>) => void,
+  ): () => void
+  has(windowId: string): boolean
+  onClose(handler: (windowId: string) => void): () => void
+}
+
+export interface ChildrenChannelController extends ChildrenChannel {
+  attach(windowId: string, transport: Transport): void
+  detach(windowId: string): void
+  dispose(): void
+}
+
+export type ChildrenChannelConfig = {
+  observer: MessageObserver
+  onDeliveryFailed?: (windowId: string, message: ShellMessage) => void
+}
+
+type ChildListener = (windowId: string, message: ShellMessage) => void
+
+export function createChildrenChannel(config: ChildrenChannelConfig): ChildrenChannelController {
+  const { observer, onDeliveryFailed } = config
+  const entries = new Map<string, Transport>()
+  const byType = new Map<MessageType, Set<ChildListener>>()
+  const closeListeners = new Set<(windowId: string) => void>()
+
+  function notifyListeners(windowId: string, message: ShellMessage) {
+    const bucket = byType.get(message.type)
+    if (!bucket || bucket.size === 0) return
+    for (const listener of bucket) {
+      try {
+        listener(windowId, message)
+      } catch {
+        // one rogue listener must not break siblings
+      }
+    }
+  }
+
+  return {
+    attach(windowId, transport) {
+      const existing = entries.get(windowId)
+      if (existing) throw new Error(`Child '${windowId}' already attached`)
+      entries.set(windowId, transport)
+      transport.onMessage((message) => {
+        observer.notify('inbound', message)
+        notifyListeners(windowId, message)
+      })
+    },
+
+    detach(windowId) {
+      const transport = entries.get(windowId)
+      if (!transport) return
+      entries.delete(windowId)
+      transport.close()
+      // `entries.delete` ran first, so `has(windowId)` is already false here —
+      // a listener replying to the gone child is a best-effort no-op.
+      for (const listener of closeListeners) {
+        try {
+          listener(windowId)
+        } catch {
+          // one rogue listener must not break siblings
+        }
+      }
+    },
+
+    dispose() {
+      for (const transport of entries.values()) transport.close()
+      entries.clear()
+    },
+
+    send(windowId, message) {
+      const transport = entries.get(windowId)
+      if (!transport) {
+        onDeliveryFailed?.(windowId, message)
+        return
+      }
+      observer.notify('outbound', message)
+      transport.send(message)
+    },
+
+    on(type, handler) {
+      let bucket = byType.get(type)
+      if (!bucket) {
+        bucket = new Set()
+        byType.set(type, bucket)
+      }
+      bucket.add(handler as ChildListener)
+      return () => {
+        bucket.delete(handler as ChildListener)
+      }
+    },
+
+    has(windowId) {
+      return entries.has(windowId)
+    },
+
+    onClose(handler) {
+      closeListeners.add(handler)
+      return () => {
+        closeListeners.delete(handler)
+      }
+    },
+  }
+}

package/src/application/channels/observer.ts

@@ -0,0 +1,33 @@
+import type { ShellMessage } from '../../domain/message/types'
+
+export type MessageDirection = 'inbound' | 'outbound'
+
+export type ObserverHandler = (message: ShellMessage, direction: MessageDirection) => void
+
+export interface MessageObserver {
+  notify(direction: MessageDirection, message: ShellMessage): void
+  subscribe(handler: ObserverHandler): () => void
+}
+
+export function createMessageObserver(): MessageObserver {
+  const handlers = new Set<ObserverHandler>()
+
+  return {
+    notify(direction, message) {
+      if (handlers.size === 0) return
+      for (const handler of handlers) {
+        try {
+          handler(message, direction)
+        } catch {
+          // one rogue observer must not break siblings
+        }
+      }
+    },
+    subscribe(handler) {
+      handlers.add(handler)
+      return () => {
+        handlers.delete(handler)
+      }
+    },
+  }
+}