;',
+ },
+ {
+ name: 'SessionIdOf',
+ declaration: 'export type SessionIdOf = SessionStandardProps extends {\n sessionId: infer S;\n} ? S : string;',
+ },
+ {
+ name: 'SessionMaybeStandardProps',
+ declaration: 'export interface SessionMaybeStandardProps {\n}',
+ },
+ {
+ name: 'SessionProviderComponent',
+ declaration: 'export type SessionProviderComponent = (props: SessionAreaProps) => ReactNode;',
+ },
+ {
+ name: 'SessionSearchResultItem',
+ declaration: 'export interface SessionSearchResultItem {\n sessionId: SessionId;\n snippet: string;\n}',
+ },
+ {
+ name: 'SessionStandardProps',
+ declaration: 'export interface SessionStandardProps {\n}',
+ },
+ {
+ name: 'SlotComponent',
+ declaration: 'export type SlotComponent = (props: P) => ReactNode;',
+ },
+ {
+ name: 'SlotCore',
+ declaration: 'export class SlotCore {\n constructor();\n register = EntryKeyOf, const D extends ChildrenDecl = Record, H extends StoreDecl | undefined = undefined, M = never, N extends (keyof LocaleNamespaceMap & string) | undefined = undefined, C extends SlotComponent = SlotComponent>(options: BaseOptions & {\n inject?: undefined;\n }, component: C & SlotComponent, keyof NoInfer & keyof SlotMap & string, HandleOf>, object, NoInfer, NoInfer>> & RendersCheck): () => void;\n register = EntryKeyOf, const D extends ChildrenDecl = Record, H extends StoreDecl | undefined = undefined, M = never, N extends (keyof LocaleNamespaceMap & string) | undefined = undefined, C extends SlotComponent = SlotComponent>(options: BaseOptions & {\n inject: (...args: InjectParams) => I;\n }, component: C & SlotComponent, keyof NoInfer & keyof SlotMap & string, HandleOf>, I, NoInfer, NoInfer>> & RendersCheck): () => void;\n register(options: ErasedOptions, component: unknown): () => void;\n isLive(entry: StoredEntry): boolean;\n entries(key: string): readonly StoredEntry[];\n entriesOfSlot(key /* …truncated — full shape in source */',
+ },
+ {
+ name: 'SlotEntryDef',
+ declaration: 'export interface SlotEntryDef {\n kind: SlotKind;\n scope: SlotScope;\n owner?: object;\n keyProps?: Record;\n hookContext?: unknown;\n inject?: object;\n}',
+ },
+ {
+ name: 'SlotInjectFace',
+ declaration: 'export type SlotInjectFace = I extends {\n hooks: infer HS extends object;\n} ? Omit & PropsSlotHooks : I;',
+ },
+ {
+ name: 'SlotInjectOf',
+ declaration: 'export type SlotInjectOf = SlotMap[K] extends {\n inject: infer Injected extends object;\n} ? Injected : object;',
+ },
+ {
+ name: 'SlotKind',
+ declaration: 'export type SlotKind = \'single\' | \'list\' | \'keyed\' | \'chain\';',
+ },
+ {
+ name: 'SlotLabel',
+ declaration: 'export type SlotLabel = string | (() => string);',
+ },
+ {
+ name: 'SlotMap',
+ declaration: 'export interface SlotMap {\n}',
+ },
+ {
+ name: 'SlotScope',
+ declaration: 'export type SlotScope = \'root\' | \'session-maybe\' | \'session\';',
+ },
+ {
+ name: 'SlotSpec',
+ declaration: 'export type SlotSpec = {\n kind: E[\'kind\'];\n scope: E[\'scope\'];\n} & (\'inject\' extends keyof E ? E extends {\n inject: infer Injected extends object;\n} ? {\n inject: Injected;\n} : {\n inject?: object;\n} : {\n inject?: never;\n});',
+ },
+ {
+ name: 'SnapshotSelectorHook',
+ declaration: 'export type SnapshotSelectorHook = (sel: (s: T) => S, eq?: (a: S, b: S) => boolean) => S;',
+ },
+ {
+ name: 'SteeringMessageNode',
+ declaration: 'export interface SteeringMessageNode {\n kind: \'steering\';\n messageId: MessageId;\n seq: number;\n time: number;\n content: readonly ContentBlock[];\n source: unknown;\n}',
+ },
+ {
+ name: 'StepLocation',
+ declaration: 'export interface StepLocation {\n readonly turn: number;\n readonly step: number;\n readonly start: SessionEvent<\'step/start\'> | undefined;\n readonly end: SessionEvent<\'step/end\'> | undefined;\n readonly status: \'open\' | \'closed\' | \'unknown\';\n readonly data: ConversationLocationDataStore;\n}',
+ },
+ {
+ name: 'StoreDecl',
+ declaration: 'export type StoreDecl = StoreHandle | StoreFactory;',
+ },
+ {
+ name: 'StoredEntry',
+ declaration: 'export interface StoredEntry {\n component: unknown;\n options: {\n key?: string;\n id?: string;\n order?: number;\n label?: SlotLabel;\n priority?: number;\n };\n select?: ((owner: never) => unknown) | undefined;\n inject?: ((...args: never[]) => Record) | undefined;\n children?: Readonly>> | undefined;\n store?: StoreDecl | undefined;\n locale?: string | undefined;\n registrant?: string | undefined;\n}',
+ },
+ {
+ name: 'StoreFactory',
+ declaration: 'export type StoreFactory = () => StoreHandle;',
+ },
+ {
+ name: 'StoreHandle',
+ declaration: 'export interface StoreHandle> {\n readonly spec: StoreSpec;\n create(scopeKey?: string): StoreInstance;\n}',
+ },
+ {
+ name: 'StoreInstance',
+ declaration: 'export interface StoreInstance> {\n readonly actions: BakedActions;\n getSnapshot(): T;\n subscribe(fn: () => void): () => void;\n clearPersisted(): void;\n}',
+ },
+ {
+ name: 'StoreSpec',
+ declaration: 'export interface StoreSpec> {\n init: () => T;\n persist?: string;\n actions: A;\n}',
+ },
+ {
+ name: 'ThemeDefinition',
+ declaration: 'export interface ThemeDefinition {\n id: string;\n colorScheme: \'light\' | \'dark\';\n tokens: ThemeTokens;\n}',
+ },
+ {
+ name: 'ThemePreference',
+ declaration: 'export type ThemePreference = typeof THEME_PREFERENCES[number];',
+ },
+ {
+ name: 'ThemeSnapshot',
+ declaration: 'export interface ThemeSnapshot {\n preference: ThemePreference;\n active: ThemeDefinition;\n themes: readonly ThemeDefinition[];\n revision: number;\n}',
+ },
+ {
+ name: 'ThemeTokenModes',
+ declaration: 'export interface ThemeTokenModes {\n light: string;\n dark: string;\n}',
+ },
+ {
+ name: 'ThemeTokenOverrides',
+ declaration: 'export type ThemeTokenOverrides = Record;',
+ },
+ {
+ name: 'ThemeTokens',
+ declaration: 'export type ThemeTokens = Record;',
+ },
+ {
+ name: 'ToolCallBlock',
+ declaration: 'export type ToolCallBlock = RunningToolCall | ToolResultNode;',
+ },
+ {
+ name: 'ToolResultNode',
+ declaration: 'export interface ToolResultNode {\n kind: \'tool-result\';\n seq: number;\n time: number;\n callId: string;\n call: {\n name: string;\n argsRaw: string;\n } | null;\n callTime: number | null;\n content: readonly ContentBlock[];\n isError: boolean;\n error?: {\n name: string;\n code: string;\n };\n meta?: unknown;\n callView: ToolCallView | null;\n resultView: ToolResultView | null;\n subCalls: readonly ToolCallBlock[];\n}',
+ },
+ {
+ name: 'Translate',
+ declaration: 'export type Translate = (key: K, params?: Record) => string;',
+ },
+ {
+ name: 'TranslateNS',
+ declaration: 'export type TranslateNS = Translate>;',
+ },
+ {
+ name: 'TurnErrorNode',
+ declaration: 'export interface TurnErrorNode {\n kind: \'turn-error\';\n seq: number;\n time: number;\n turn: number;\n step: number;\n message: string;\n code?: string;\n}',
+ },
+ {
+ name: 'TurnLocation',
+ declaration: 'export interface TurnLocation {\n readonly turn: number;\n readonly start: SessionEvent<\'turn/start\'> | undefined;\n readonly end: SessionEvent<\'turn/end\'> | undefined;\n readonly status: \'open\' | \'closed\' | \'unknown\';\n readonly steps: readonly StepLocation[];\n readonly data: ConversationLocationDataStore;\n}',
+ },
+ {
+ name: 'UnknownSurfaceNode',
+ declaration: 'export interface UnknownSurfaceNode {\n kind: \'unknown\';\n seq: number;\n time: number;\n type: string;\n data: unknown;\n}',
+ },
+ {
+ name: 'UserMessageNode',
+ declaration: 'export interface UserMessageNode {\n kind: \'user\';\n seq: number;\n time: number;\n content: readonly ContentBlock[];\n source: unknown;\n}',
+ },
+]
+
+/** The inherited `ctx` API (cordis core + loader/hmr/timer), in curated order. */
+export const INHERITED_CTX_API: readonly InheritedApiEntry[] = [
+ { name: 'ctx.on / ctx.once', summary: 'Register an event listener (disposable).' },
+ { name: 'ctx.emit / ctx.parallel / ctx.serial / ctx.bail / ctx.waterfall', summary: 'Dispatch an event (sync / awaited / first-bail / short-circuit chain).' },
+ { name: 'ctx.plugin / ctx.inject', summary: 'Load a plugin / declare required services.' },
+ { name: 'ctx.effect', summary: 'Register a disposable side effect tied to the fiber.' },
+ { name: 'ctx.get / ctx.set / ctx.provide / ctx.accessor / ctx.mixin', summary: 'Low-level service-store access and binding.' },
+ { name: 'ctx.extend / ctx.isolate / ctx.intercept', summary: 'Derive a child context (scoped services / isolation / interception).' },
+ { name: 'ctx.root / ctx.scope / ctx.fiber / ctx.registry / ctx.reflect / ctx.events / ctx.logger', summary: 'Ambient handles onto the running context graph.' },
+ { name: 'ctx.timer (+ interval / timeout / throttle / debounce)', summary: 'Disposable timer helpers. The `timer` key is provided at runtime; the four supported helpers are mixed onto ctx directly (declared via Pick).' },
+ { name: 'ctx.loader', summary: 'The config Loader that booted the app (present under the loader).' },
+ { name: 'ctx.hmr', summary: 'The hot-module-reload watcher (present under the hmr plugin).' },
+]
+
+function referencedTypeClosure(seeds: readonly string[]): TypeApiEntry[] {
+ const included = new Set()
+ let frontier = [...seeds]
+ while (frontier.length > 0) {
+ const next: string[] = []
+ for (const entry of TYPE_API) {
+ if (included.has(entry.name)) continue
+ const pattern = new RegExp(`\b${entry.name}\b`)
+ if (!frontier.some(text => pattern.test(text))) continue
+ included.add(entry.name)
+ next.push(entry.declaration)
+ }
+ frontier = next
+ }
+ return TYPE_API.filter(entry => included.has(entry.name))
+}
+
+function contextProperty(key: string): string {
+ return /^[A-Za-z_$][\w$]*$/.test(key) ? `ctx.${key}` : `ctx[${JSON.stringify(key)}]`
+}
+
+/**
+ * Project the Service Catalog as a compact directory or one exact coding contract.
+ * @param key - exact Service key; omit it to list all Services and method signatures.
+ * @param services - platform-specific visible Service entries.
+ * @returns compact navigation data or one detailed Service with its referenced type closure.
+ */
+export function queryServiceApi(key?: string, services: readonly ServiceApiEntry[] = SERVICE_API): object {
+ if (key === undefined) {
+ return {
+ mode: 'catalog',
+ services: services.map(service => ({
+ key: service.key,
+ description: service.summary,
+ methods: service.methods.map(method => ({ signature: method.signature })),
+ })),
+ }
+ }
+ const service = services.find(candidate => candidate.key === key)
+ if (service === undefined) throw new Error(`no catalogued Service named "${key}"`)
+ return {
+ mode: 'service',
+ service: {
+ key: service.key,
+ description: service.description,
+ access: {
+ optional: { expression: `ctx.get(${JSON.stringify(service.key)})`, requiresUndefinedCheck: true },
+ hardDependency: { inject: [service.key], expression: contextProperty(service.key) },
+ },
+ methods: service.methods,
+ },
+ referencedTypes: referencedTypeClosure(service.methods.map(method => method.signature)),
+ }
+}
+
+/**
+ * Project the Event Catalog as a compact directory or one exact listener contract.
+ * @param name - exact Event name; omit it to list all Events and listener signatures.
+ * @param events - platform-specific visible Event entries.
+ * @returns compact navigation data or one detailed Event with its referenced type closure.
+ */
+export function queryEventApi(name?: string, events: readonly EventApiEntry[] = EVENT_API): object {
+ if (name === undefined) {
+ return {
+ mode: 'catalog',
+ events: events.map(event => ({
+ name: event.name,
+ description: event.summary,
+ mode: event.mode,
+ signature: event.signature,
+ })),
+ }
+ }
+ const event = events.find(candidate => candidate.name === name)
+ if (event === undefined) throw new Error(`no catalogued Event named "${name}"`)
+ return {
+ mode: 'event',
+ event: {
+ name: event.name,
+ description: event.description,
+ mode: event.mode,
+ signature: event.signature,
+ parameters: event.parameters,
+ },
+ referencedTypes: referencedTypeClosure([event.signature]),
+ }
+}
diff --git a/packages/extensions/cordis-client-runner/src/client/evaluator.ts b/packages/extensions/cordis-client-runner/src/client/evaluator.ts
new file mode 100644
index 0000000000..534fe187d9
--- /dev/null
+++ b/packages/extensions/cordis-client-runner/src/client/evaluator.ts
@@ -0,0 +1,222 @@
+/**
+ * Browser-half closure evaluation: the package source runs as the body of an
+ * async function whose parameters ARE the symbol surface. Shadowing parameters
+ * (setTimeout/fetch/require/…) turn the ambient browser globals into teaching
+ * redirects without touching the page. The host syntax-prechecked the source at
+ * define time; SyntaxError handling here is the engine-divergence fallback and
+ * reaches the model through the load report.
+ */
+
+import * as React from 'react'
+import type { CordisDynamicPluginId } from '@deepseek-ai/dsh-api-remotes/client'
+
+/** A mountable plugin as the closure must return it (FUNCTION or OBJECT form). */
+export interface DynamicCordisEvaluatedPlugin {
+ /** Optional plugin name; the runner overwrites it with the module id. */
+ name?: string
+ /** Services the browser half declares; the runner overwrites it from the dispatched row. */
+ inject?: string[]
+ /** Plugin body receiving the guard facade. */
+ apply: (ctx: unknown, config?: unknown) => unknown
+}
+
+/** What the evaluator needs from the runner to build one package's closure. */
+export interface DynamicCordisClosureEnv {
+ /** Route `host.call` to this package's host half over the wire. */
+ invoke(method: string, args: unknown): Promise
+ /** Mirror one runtime error text into the load report (console.error copies). */
+ noteError(message: string): void
+}
+
+const TIMER_REDIRECT
+ = 'browser timer globals are unavailable in dynamic packages. Declare inject: [\'timer\'] on the returned plugin, '
+ + 'query Client Service.listService for the exact API, and close over that plugin ctx. In React, create timers '
+ + 'from an event handler or React.useEffect and return callback-form disposers from the effect cleanup.'
+
+/**
+ * Where each withheld browser global sends the author instead. One home for two
+ * consumers: the closure traps below throw these, and a render crash whose
+ * message names one of them gets the same redirect appended — a package that
+ * reached the global some other way (`window.setInterval`) crashes with the
+ * engine's own bare text, and the author needs the redirect either way.
+ */
+export const DYNAMIC_CLIENT_REDIRECTS: Readonly> = {
+ setTimeout: TIMER_REDIRECT,
+ setInterval: TIMER_REDIRECT,
+ clearTimeout: TIMER_REDIRECT,
+ clearInterval: TIMER_REDIRECT,
+ fetch:
+ 'network belongs to the HOST half: register a handler there with harness.handle(method, fn) and call it here via host.call(method, args).',
+ require:
+ 'modules cannot be imported here. React arrives as the `React` closure symbol; everything else goes through ctx services or host.call.',
+}
+
+/** Callable teaching traps shadowing the ambient globals the closure must not reach. */
+function closureTraps(): Record never> {
+ const traps: Record never> = {}
+ for (const [name, redirect] of Object.entries(DYNAMIC_CLIENT_REDIRECTS)) {
+ traps[name] = (): never => {
+ throw new Error(`${name} is not available in a dynamic client half — ${redirect}`)
+ }
+ }
+ return traps
+}
+
+/** The `harness` seat exists only host-side; any touch teaches the split. */
+function harnessTrap(): unknown {
+ return new Proxy({}, {
+ get(_target, prop) {
+ throw new Error(
+ `harness.${String(prop)} belongs to the HOST half (\`code\`): register handlers there with harness.handle(method, fn); `
+ + 'the browser half calls them via host.call(method, args).',
+ )
+ },
+ })
+}
+
+/** Per-package style-tag bookkeeping behind the `styles.insert` symbol. */
+export class DynamicCordisStyles {
+ private readonly tags = new Set()
+
+ /** @param pluginId - owning Plugin ID, stamped as `data-dyn` on every tag. */
+ constructor(private readonly pluginId: CordisDynamicPluginId) {}
+
+ /**
+ * Inject one stylesheet, removed automatically on package unload.
+ * @param css - raw CSS text.
+ * @returns disposer removing this one tag early.
+ */
+ insert(css: string): () => void {
+ if (typeof css !== 'string') throw new Error('styles.insert(css) needs a CSS string')
+ const tag = document.createElement('style')
+ tag.dataset.dyn = this.pluginId
+ tag.textContent = css
+ document.head.append(tag)
+ this.tags.add(tag)
+ return () => {
+ this.tags.delete(tag)
+ tag.remove()
+ }
+ }
+
+ /** Live tag count (load-report contribution summary). */
+ get count(): number {
+ return this.tags.size
+ }
+
+ /** Remove every tag this package still owns (unload path). */
+ dispose(): void {
+ for (const tag of this.tags) tag.remove()
+ this.tags.clear()
+ }
+}
+
+/** Stringify one console argument for the error mirror. */
+function errorText(arg: unknown): string {
+ if (arg instanceof Error) return arg.message
+ if (typeof arg === 'string') return arg
+ if (arg === undefined) return 'undefined'
+ try {
+ return JSON.stringify(arg)
+ } catch {
+ // A circular or otherwise non-serializable console argument: the mirror
+ // carries the message, and nothing else here can fail.
+ return '[unserializable console argument]'
+ }
+}
+
+/** Tagged write-through console; error lines additionally copy into the load report. */
+function taggedConsole(pluginId: CordisDynamicPluginId, noteError: (message: string) => void): Console {
+ const tag = `[cordis:${pluginId}]`
+ const forward = (level: 'log' | 'info' | 'warn' | 'error' | 'debug') => (...args: unknown[]): void => {
+ console[level](tag, ...args)
+ if (level !== 'error') return
+ noteError(args.map(errorText).join(' ').slice(0, 500))
+ }
+ return {
+ ...console,
+ log: forward('log'),
+ info: forward('info'),
+ warn: forward('warn'),
+ error: forward('error'),
+ debug: forward('debug'),
+ }
+}
+
+/**
+ * Narrow a closure return value to a mountable plugin (host guard mirror).
+ * @param value - whatever the closure returned.
+ * @returns whether the value is mountable.
+ */
+export function isDynamicCordisPlugin(value: unknown): value is DynamicCordisEvaluatedPlugin | ((ctx: unknown) => unknown) {
+ if (typeof value === 'function') return true
+ return typeof value === 'object' && value !== null
+ && typeof (value as { apply?: unknown }).apply === 'function'
+}
+
+/**
+ * Evaluate one package's browser half and return the (un-guarded) plugin.
+ * @param pluginId - stable Plugin ID (console tag and style ownership).
+ * @param clientCode - the browser half's source: an async function body returning a plugin.
+ * @param env - runner wiring for `host.call` and error mirroring.
+ * @param styles - the package's style bookkeeping (owned by the caller so unload can dispose it).
+ * @returns the plugin the closure returned.
+ * @throws teaching errors for syntax failures and non-plugin returns.
+ */
+export async function evaluateClientHalf(
+ pluginId: CordisDynamicPluginId,
+ clientCode: string,
+ env: DynamicCordisClosureEnv,
+ styles: DynamicCordisStyles,
+): Promise unknown)> {
+ const traps = closureTraps()
+ const parameters = ['React', 'console', 'styles', 'host', 'harness', ...Object.keys(traps), 'process', 'Buffer']
+ let closure: (...args: unknown[]) => Promise
+ try {
+ // The wrapper mirrors the host precheck exactly, so line offsets match.
+ // Evaluating a definition's browser half IS this package's product: the
+ // source arrived from a host process that accepted and prechecked it.
+ // oxlint-disable-next-line typescript/no-implied-eval -- see above
+ const factory = new Function(...parameters, `return (async () => {\n${clientCode}\n})()`)
+ closure = factory as (...args: unknown[]) => Promise
+ } catch (error) {
+ if (!(error instanceof SyntaxError)) throw error
+ // Engine-divergence fallback: the host precheck already carried the
+ // line/caret teaching; browsers give only the message.
+ throw new Error(
+ `client half failed to parse in this browser: ${error.message}\n`
+ + 'The browser half is plain JavaScript (no JSX, no TypeScript); build elements with React.createElement.',
+ )
+ }
+ const host = {
+ /**
+ * Call a host-half handler of THIS package (harness.handle pairing). A call
+ * with nothing to pass omits the argument: it arrives at the handler as
+ * `null`, because the wire carries JSON and `undefined` is not JSON —
+ * requiring `host.call('m', {})` would be a ritual, and defaulting to `{}`
+ * would invent an empty argument the caller never wrote.
+ */
+ call: (method: string, args: unknown = null): Promise => env.invoke(method, args),
+ }
+ const returned = await closure(
+ React,
+ taggedConsole(pluginId, (message) => { env.noteError(message) }),
+ styles,
+ host,
+ harnessTrap(),
+ ...Object.values(traps),
+ undefined, // process: undefined keeps `typeof process` probes safe
+ undefined, // Buffer
+ )
+ if (!isDynamicCordisPlugin(returned)) {
+ if (returned === undefined) {
+ throw new Error(
+ 'client half returned `undefined` — did you forget `return`?\n'
+ + ' ✓ return (ctx) => { … }\n'
+ + ' ✓ return { name: \'…\', inject: [\'slots\'], apply(ctx) { … } }',
+ )
+ }
+ throw new Error('client half must `return` a plugin: a function, or an object with an `apply(ctx)` method')
+ }
+ return returned
+}
diff --git a/packages/extensions/cordis-client-runner/src/client/guard.ts b/packages/extensions/cordis-client-runner/src/client/guard.ts
new file mode 100644
index 0000000000..8f71f9ced1
--- /dev/null
+++ b/packages/extensions/cordis-client-runner/src/client/guard.ts
@@ -0,0 +1,239 @@
+/**
+ * The browser twin of the tool-cordis context facade: a whitelist of
+ * lifecycle-safe verbs plus optional `ctx.get()` lookup and declared-service
+ * property access, with
+ * framework internals withheld and Context-valued returns denied. Two seats
+ * carry extra machinery: `slots`, where the register proxy assigns the
+ * shadowing priority and ledgers the registration — invoking the service with
+ * the traced receiver so the effect lands on the CALLING plugin's fiber
+ * (SlotsService.register must stay a prototype method for exactly that
+ * reason) — and `theme`, whose override source is pinned to the package id.
+ *
+ * This is API discipline, not a security boundary: a dynamic package's code is
+ * as trusted as the host process that accepted its definition.
+ */
+
+import { Context } from '@deepseek-ai/cordis'
+import type { DynamicCordisPackage } from '@deepseek-ai/dsh-api-remotes/client'
+import type { SlotsService } from '@deepseek-ai/dsh-client-runtime/client'
+import type { ThemeService } from '@deepseek-ai/dsh-client-ui-theme/client'
+
+/** Facade verbs beyond declared services (host CTX_VERBS twin). */
+const CTX_VERBS = new Set([
+ 'effect', 'on', 'once', 'provide', 'timeout', 'interval', 'setTimeout', 'setInterval', 'throttle', 'debounce',
+])
+const TIMER_VERBS = new Set(['timeout', 'interval', 'setTimeout', 'setInterval', 'throttle', 'debounce'])
+
+/** One package's slot-registration ledger row (contribution projection source). */
+export interface DynamicCordisSlotLedgerRow {
+ /** Target slot name. */
+ slot: string
+ /** The assigned shadowing priority (globally unique — how winners are matched back to packages). */
+ priority: number | undefined
+}
+
+/** What the facade needs beyond the real ctx to govern one package. */
+export interface DynamicCordisGuardEnv {
+ /** The dispatched Package row. */
+ pkg: DynamicCordisPackage
+ /** Ledger sink: every slot registration this package makes. */
+ ledger: DynamicCordisSlotLedgerRow[]
+ /**
+ * Ownership index sink: the component object seated in a slot, so a later
+ * render crash reported against the stored entry can be attributed back to
+ * this package. Identity is the key — the registry stores the component
+ * verbatim — which is why nothing else has to be remembered about the entry.
+ * @param component - whatever the package passed as its component.
+ */
+ claim(component: unknown): void
+ /** Allocate one page-local shadowing rank; later registrations sort first. */
+ allocatePriority(): number
+ /** Report one post-activation guard rejection to the owning Agent. */
+ reportFailure(error: Error): void
+}
+
+/** Reject any service return that is a cordis Context (host guard twin). */
+function denyContext(value: unknown, service: string, env: DynamicCordisGuardEnv): unknown {
+ if (value instanceof Context) {
+ return rejectGuard(env,
+ `service "${service}" returned a cordis Context, which the dynamic facade does not expose. `
+ + 'Operate through your own plugin ctx and the services you declared — never another context.',
+ )
+ }
+ return value
+}
+
+/**
+ * Forward service methods with the traced service as receiver — `this.ctx`
+ * inside prototype methods (slots.register) must stay the CALLER's ctx so
+ * effects land on the calling plugin's fiber — while denying Context returns.
+ */
+function guardedService(service: object, name: string, env: DynamicCordisGuardEnv): unknown {
+ return new Proxy(service, {
+ get(target, prop) {
+ const value = Reflect.get(target, prop, target) as unknown
+ if (typeof value !== 'function') return denyContext(value, name, env)
+ return (...args: unknown[]): unknown => {
+ const result = Reflect.apply(value, target, args) as unknown
+ if (result instanceof Promise) return result.then(resolved => denyContext(resolved, name, env))
+ return denyContext(result, name, env)
+ }
+ },
+ })
+}
+
+/** Erased register options as this facade reads and rewrites them. */
+interface ErasedSlotOptions {
+ name?: string
+ priority?: number
+ [key: string]: unknown
+}
+
+/**
+ * The slots seat: automatic shadowing priority and ledger recording around the
+ * traced service's own register.
+ */
+function guardedSlots(slots: SlotsService, env: DynamicCordisGuardEnv): unknown {
+ return new Proxy(slots, {
+ get(target, prop) {
+ const value = Reflect.get(target, prop, target) as unknown
+ if (prop !== 'register') {
+ if (typeof value !== 'function') return denyContext(value, 'slots', env)
+ return (...args: unknown[]): unknown => denyContext(Reflect.apply(value, target, args), 'slots', env)
+ }
+ return (rawOptions: unknown, component: unknown): unknown => {
+ if (typeof rawOptions !== 'object' || rawOptions === null) {
+ return rejectGuard(env, 'slots.register(options, component) needs an options object with a `name`')
+ }
+ const options = { ...rawOptions as ErasedSlotOptions }
+ const slot = options.name
+ if (typeof slot !== 'string' || slot.length === 0) {
+ return rejectGuard(env, 'slots.register options need a string `name` (the target slot key)')
+ }
+ if (slot === 'tool.view.cordis') {
+ if (options.key !== 'self') {
+ return rejectGuard(env, 'tool.view.cordis only accepts key "self"; the runtime binds it to this Package')
+ }
+ options.key = `${env.pkg.pluginId}.${env.pkg.packageId}`
+ }
+ // Shadowing kinds get a page-local rank. Later registrations sort first;
+ // chain slots keep their own election (select order) untouched.
+ const spec = (slots.spec as (key: string) => { kind?: string } | undefined)(slot)
+ let priority = options.priority
+ if (spec === undefined || spec.kind !== 'chain') {
+ priority = env.allocatePriority()
+ options.priority = priority
+ }
+ const register = Reflect.get(target, 'register', target) as unknown as (opts: object, comp: unknown) => () => void
+ const dispose = register.call(target, options, component)
+ env.ledger.push({ slot, priority })
+ // After the registry accepted it: a rejected registration seats no entry,
+ // so claiming one would index a component no crash can ever name.
+ env.claim(component)
+ return dispose
+ }
+ },
+ })
+}
+
+/**
+ * The theme seat: `overrideTokens`' source is FORCED to the package id — a
+ * dynamic package can never impersonate (or evict) another source's layer, and
+ * its own layers converge under one identity unload can reason about. The
+ * layer's disposer is additionally hung on the calling fiber, because the
+ * documented contract is "unload restores" and model code cannot be trusted to
+ * keep the returned handle (slots parity — register hangs its own cleanup).
+ * Everything else forwards through the generic guard.
+ */
+function guardedTheme(theme: ThemeService, env: DynamicCordisGuardEnv, ctx: Context): unknown {
+ return new Proxy(theme, {
+ get(target, prop) {
+ if (prop !== 'overrideTokens') {
+ const value = Reflect.get(target, prop, target) as unknown
+ if (typeof value !== 'function') return denyContext(value, 'theme', env)
+ return (...args: unknown[]): unknown => {
+ const result = Reflect.apply(value, target, args) as unknown
+ if (result instanceof Promise) return result.then(resolved => denyContext(resolved, 'theme', env))
+ return denyContext(result, 'theme', env)
+ }
+ }
+ return (source: unknown, tokens: unknown): unknown => {
+ // Two-argument shape preserved so the facade matches the documented
+ // service signature; the source VALUE is replaced, never trusted.
+ if (tokens === undefined && typeof source === 'object' && source !== null) {
+ return rejectGuard(env,
+ 'theme.overrideTokens(source, tokens) takes two arguments; source is replaced with your package id, '
+ + 'so pass any string first and the token map second: overrideTokens(\'mine\', { \'--dsw-alias-…\': { light: \'…\', dark: \'…\' } })',
+ )
+ }
+ const method = Reflect.get(target, 'overrideTokens', target)
+ const dispose = Reflect.apply(method, target, [`${env.pkg.pluginId}.${env.pkg.packageId}`, tokens]) as () => void
+ // Fiber-owned lifetime; the returned handle stays valid for early
+ // removal (the service disposer is idempotent per layer identity).
+ ctx.effect(() => dispose, 'cordis-client-runner: dynamic theme override layer')
+ return dispose
+ }
+ },
+ })
+}
+
+/**
+ * Build the facade one dynamic plugin's `apply` receives (host sandboxContext
+ * twin, browser seats). `ctx.get(name)` performs optional lookup; direct
+ * `ctx.serviceName` access is gated by the fiber's `inject` declaration.
+ * @param ctx - the plugin's real fiber ctx (loader-created).
+ * @param env - package row + ledger sink.
+ * @returns the whitelisting proxy standing in for ctx.
+ */
+export function dynamicCordisContext(ctx: Context, env: DynamicCordisGuardEnv): Context {
+ const declared = new Set(Object.keys(ctx.fiber.inject))
+ const denyRead = (prop: string): never => {
+ if (ctx.get(prop) !== undefined) {
+ return rejectGuard(env,
+ `service "${prop}" is not declared by your plugin. Declare it on the plugin you return: `
+ + `{ inject: ['${prop}', …], apply(ctx) { … } } — a plain \`function\` has no declaration site, `
+ + 'so use the object form. The runtime then parks the package if the provider unloads.',
+ )
+ }
+ return rejectGuard(env,
+ `dynamic ctx does not expose "${prop}". Available: ctx.on / ctx.provide / timer helpers after injecting timer, and any service your `
+ + 'returned plugin declared in inject (slots and theme are the usual UI seats). Framework internals are withheld '
+ + 'by design.',
+ )
+ }
+ const readService = (name: string, requireDeclaration: boolean): unknown => {
+ if (requireDeclaration && !declared.has(name)) return denyRead(name)
+ const service = denyContext(ctx.get(name), name, env)
+ if (service === null || (typeof service !== 'object' && typeof service !== 'function')) return service
+ if (name === 'slots') return guardedSlots(service as SlotsService, env)
+ if (name === 'theme') return guardedTheme(service as ThemeService, env, ctx)
+ return guardedService(service, name, env)
+ }
+ return new Proxy({}, {
+ get(_target, prop) {
+ if (prop === 'get') return (name: string): unknown => readService(name, false)
+ if (typeof prop !== 'string') return undefined
+ // Lazy verb forwarder (host twin): resolve ctx[verb] only when called.
+ if (CTX_VERBS.has(prop)) {
+ return (...args: unknown[]): unknown => {
+ if (TIMER_VERBS.has(prop) && !declared.has('timer')) return denyRead('timer')
+ const method = ctx[prop as keyof Context]
+ return Reflect.apply(method as (...a: unknown[]) => unknown, ctx, args)
+ }
+ }
+ return readService(prop, true)
+ },
+ set(_target, prop) {
+ return rejectGuard(env, `dynamic ctx is read-only; cannot assign "${String(prop)}"`)
+ },
+ has: (_target, prop) => prop === 'get'
+ || (typeof prop === 'string'
+ && ((CTX_VERBS.has(prop) && (!TIMER_VERBS.has(prop) || declared.has('timer'))) || declared.has(prop))),
+ }) as unknown as Context
+}
+
+function rejectGuard(env: DynamicCordisGuardEnv, message: string): never {
+ const error = new Error(message)
+ env.reportFailure(error)
+ throw error
+}
diff --git a/packages/extensions/cordis-client-runner/src/client/index.ts b/packages/extensions/cordis-client-runner/src/client/index.ts
new file mode 100644
index 0000000000..244fd5a7f5
--- /dev/null
+++ b/packages/extensions/cordis-client-runner/src/client/index.ts
@@ -0,0 +1,308 @@
+/**
+ * Dynamic-package runner, browser half: the load engine that turns one browser
+ * half's source into a live cordis plugin (closure → guard → module table →
+ * loader entry, ./runtime.ts), plus the retract announcement that unloads it.
+ *
+ * Nothing loads on activation: this page holds no dynamic package until a
+ * dispatch arrives, and a dispatch only follows a model `cordis_run` or a user
+ * pressing a card's start control. A refresh therefore starts clean by design —
+ * host process memory still holds the definition, the page simply does not run
+ * it until asked again.
+ */
+
+import type { Context } from '@deepseek-ai/cordis'
+import type {
+ ApprovalRequestId, CordisDynamicPluginId, DynamicCordisInvokeResult, JsonValue,
+ DynamicCordisInventoryRow,
+} from '@deepseek-ai/dsh-api-remotes/client'
+import type { ClientModuleSystem } from '@deepseek-ai/dsh-client-modules/client'
+import type { SlotsService } from '@deepseek-ai/dsh-client-runtime/client'
+// The Client Remote assembly is the one place the two planes meet: it mounts the
+// `dynamicCordisRunner` namespace and re-exports its payload vocabulary, so this
+// package names what it sends without importing a Host package.
+import type { DynamicCordisLivePackage } from './runtime.ts'
+import { DynamicCordisPackageRunner } from './runtime.ts'
+import { CordisRunOrchestrator } from './orchestrator.ts'
+import { ClientCordisInspectRegistry, provideClientCordisInspect } from './inspect-registry.ts'
+import { clientInspectProviders } from './providers.ts'
+import { provideClientTimer } from './timer.ts'
+import type { CordisRunActivity, CordisRunFailure, CordisUserRunRequest } from './orchestrator.ts'
+import type { CordisObservable, DynamicCordisRenderFailure } from './runtime.ts'
+
+export { CordisRunOrchestrator } from './orchestrator.ts'
+export { ClientCordisInspectRegistry } from './inspect-registry.ts'
+export type {
+ ClientCordisInspectHost, ClientCordisInspectProviderRegistration, ClientCordisInspectQueryContext,
+} from './inspect-registry.ts'
+export type {
+ CordisRunActivity, CordisRunFailure, CordisRunHostSeam,
+ CordisRunOrchestratorEnv, CordisRunRequest, CordisUserRunRequest,
+} from './orchestrator.ts'
+export { DynamicCordisPackageRunner } from './runtime.ts'
+export type {
+ CordisObservable, DynamicCordisClientHalf, DynamicCordisLivePackage, DynamicCordisLoadErrorCause,
+ DynamicCordisLoadResult, DynamicCordisRenderFailure, DynamicCordisRunnerEnv,
+} from './runtime.ts'
+
+export { DynamicCordisStyles, evaluateClientHalf, isDynamicCordisPlugin } from './evaluator.ts'
+export type { DynamicCordisClosureEnv, DynamicCordisEvaluatedPlugin } from './evaluator.ts'
+export { dynamicCordisContext } from './guard.ts'
+export type { DynamicCordisGuardEnv, DynamicCordisSlotLedgerRow } from './guard.ts'
+export { ClientTimerService } from './timer.ts'
+// Re-exported so consumers of the service face and the two events can name
+// their subjects without reaching into the wire contract themselves.
+export type {
+ ApprovalRequestId, CordisDynamicPackageId, CordisDynamicPluginId, CordisDynamicPluginRunId,
+ DynamicCordisPackage,
+} from '@deepseek-ai/dsh-api-remotes/client'
+
+
+/**
+ * What a run surface reads and calls. The activity map is the single home of
+ * "a run is in flight", so an affordance never keeps its own copy — that is what
+ * makes it survive a remount.
+ */
+export interface CordisRunnerFace {
+ /** Each definition's in-flight run activity. */
+ readonly activeRuns: CordisObservable>
+ /** The last failure of this page's own run attempt, per definition. */
+ readonly lastRunError: CordisObservable>
+ /**
+ * This page's last render crash per definition: a browser half that loaded
+ * cleanly and then broke while React rendered it. Page-local and current by
+ * construction — cleared when the package stops, is retracted, or loads again —
+ * which is what makes it safe for a row to render directly. The host keeps its
+ * own last-across-pages copy for the model; the two have different owners and
+ * lifetimes and neither is derived from the other.
+ */
+ readonly renderFailures: CordisObservable>
+ /**
+ * Restore pending approvals after a page reconnect or missed event.
+ * @param rows - current dynamic Plugin inventory.
+ */
+ reconcileApprovals(rows: readonly DynamicCordisInventoryRow[]): void
+ /**
+ * Answer one run request with "run it" and drive both halves.
+ * @param requestId - the request being answered; unknown or settled ids are a no-op.
+ * @param approveFutureVersions - whether this decision covers later Packages of the same Plugin.
+ * @returns after the orchestration settled.
+ */
+ approve(requestId: ApprovalRequestId, approveFutureVersions: boolean): Promise
+ /**
+ * Answer one run request with "do not run it".
+ * @param requestId - the request being answered; unknown or settled ids are a no-op.
+ * @returns after the refusal reached the host.
+ */
+ decline(requestId: ApprovalRequestId): Promise
+ /**
+ * Run a definition here at the user's own request (the gesture authorizes it).
+ * A definition with a browser half also loads onto this page; a host-only one
+ * only comes up in the host process.
+ * @param request - the definition to run, its session, and whether it has a browser half.
+ * @returns after the orchestration settled.
+ */
+ startUserRun(request: CordisUserRunRequest): Promise
+ /**
+ * Observe what this page has loaded.
+ * @param fn - notified after every converged load or unload.
+ * @returns unsubscribe.
+ */
+ subscribe(fn: () => void): () => void
+ /**
+ * Read what this page currently has loaded.
+ * @returns immutable rows for live Client halves.
+ */
+ getSnapshot(): readonly DynamicCordisLivePackage[]
+ /**
+ * Whether this page loaded a definition's browser half — page-local truth,
+ * never the host's "it is running".
+ * @param pluginId - stable Plugin identity.
+ * @returns true while a load is live here.
+ */
+ isLoaded(pluginId: CordisDynamicPluginId): boolean
+}
+
+declare module '@deepseek-ai/cordis' {
+ interface Context {
+ /** Run orchestration and page-local load state: what run surfaces read and call. */
+ dynamicCordisRunner: CordisRunnerFace
+ }
+}
+
+/** Teaching text for a routing failure the infrastructure itself reports. */
+function invokeFailure(pluginId: CordisDynamicPluginId, method: string, result: Extract): string {
+ const where = `host.call("${method}") on ${pluginId}`
+ if (result.code === 'plugin-not-running') {
+ return `${where} found no active Host half — the Plugin is stopped or was removed.`
+ }
+ if (result.code === 'stale-run') {
+ return `${where} belongs to an activation that has already been replaced.`
+ }
+ if (result.code === 'method-not-found') {
+ return `${where} is not registered: the host half must declare it with harness.handle("${method}", fn).`
+ }
+ return `${where} failed inside the host handler: ${result.message}`
+}
+
+/** Preserve a Host handler's stack while adding the Client call site diagnosis. */
+function invokeError(
+ pluginId: CordisDynamicPluginId,
+ method: string,
+ result: Extract,
+): Error {
+ const error = new Error(invokeFailure(pluginId, method, result))
+ if (result.stack !== undefined) error.stack = `${error.stack ?? error.message}\nHost stack:\n${result.stack}`
+ return error
+}
+
+/**
+ * Teaching text for a `host.call` the wire itself refused: the generated codec
+ * rejected the argument before sending, or the result on the way back, or the
+ * transport broke. The infrastructure's message names the field it refused but
+ * not the call it belonged to, and the model authored both halves — so this adds
+ * the call and the contract it has to satisfy.
+ */
+function wireFailure(id: CordisDynamicPluginId, method: string, error: unknown): string {
+ const message = error instanceof Error ? error.message : String(error)
+ return `host.call("${method}") on ${id} did not complete: ${message}\n`
+ + 'Both directions carry JSON only: pass plain JSON data as the argument — or omit it, and the handler receives '
+ + `null — and answer from harness.handle("${method}", fn) with JSON (\`return null\` when there is nothing to report).`
+}
+
+/** Stable Cordis plugin name. */
+export const name = 'cordis-client-runner'
+
+/**
+ * Required services: the loader/module chain for entries, the slot registry for
+ * contributions, and the `dynamicCordisRunner` Remote namespace. Declaring the
+ * namespace parks this plugin until the host side exists, so a page never loads
+ * a browser half whose host half it could not reach.
+ */
+export const inject = ['loader', 'modules', 'slots', 'remote', 'remote.dynamicCordisRunner']
+
+/**
+ * Client plugin body: build the runner and subscribe the dispatch family.
+ * @param ctx - client root context.
+ */
+export function apply(ctx: Context): void {
+ provideClientTimer(ctx)
+ const inspect = new ClientCordisInspectRegistry({
+ sync: async (providers) => {
+ const answered = await ctx.remote.dynamicCordisRunner.syncInspectManifest(providers)
+ if (!answered.ok) throw new Error(`${answered.error.code}: ${answered.error.message}`)
+ },
+ resolve: async (agentId, requestId, resolution) => {
+ const answered = await ctx.remote.dynamicCordisRunner.resolveInspectQuery(agentId, requestId, resolution)
+ if (!answered.ok) throw new Error(`${answered.error.code}: ${answered.error.message}`)
+ },
+ })
+ provideClientCordisInspect(ctx, inspect)
+ for (const provider of clientInspectProviders(ctx)) {
+ ctx.effect(() => inspect.register(provider), `cordis-client-runner: inspect ${provider.manifest.id}`)
+ }
+ ctx.on('connection/reset', () => { inspect.publish() })
+
+ const runner = new DynamicCordisPackageRunner({
+ ctx,
+ loader: ctx.loader,
+ modules: ctx.get('modules') as ClientModuleSystem,
+ slots: ctx.get('slots') as SlotsService,
+ invoke: async (pluginId, pluginRunId, method, args) => {
+ // Model-authored arguments reach this boundary untyped; the namespace's
+ // generated codec is what validates them as JSON, and its rejection is a
+ // bare field name — this is the only place that still knows which call it
+ // belonged to, so the teaching has to be added here.
+ const answered = await ctx.remote.dynamicCordisRunner.invoke(pluginId, pluginRunId, method, args as JsonValue)
+ .catch((error: unknown) => { throw new Error(wireFailure(pluginId, method, error)) })
+ // Two failure layers, and they teach different things: the carrier's error
+ // branch means the call never reached the host half, while the namespace's
+ // own `ok: false` is that half answering with a refusal.
+ if (!answered.ok) throw new Error(wireFailure(pluginId, method, `${answered.error.code}: ${answered.error.message}`))
+ const result = answered.value
+ if (result.ok) return result.value
+ throw invokeError(pluginId, method, result)
+ },
+ // Post-settle diagnosis, deliberately fire-and-forget: the run this package
+ // belongs to was answered before it ever rendered, so nothing waits on this
+ // and a failed report must not turn one crash into two.
+ reportRenderFailure: (agentId, pluginId, pluginRunId, failure) => {
+ void ctx.remote.dynamicCordisRunner.reportRenderFailure(agentId, pluginId, pluginRunId, failure).then((result) => {
+ if (!result.ok) {
+ console.error(`[cordis-client-runner] reporting a render failure of ${pluginId} failed:`, result.error)
+ }
+ }, (error: unknown) => {
+ console.error(`[cordis-client-runner] reporting a render failure of ${pluginId} failed:`, error)
+ })
+ },
+ reportGuardFailure: (agentId, pluginId, pluginRunId, failure) => {
+ void ctx.remote.dynamicCordisRunner.reportClientGuardFailure(agentId, pluginId, pluginRunId, failure).then((result) => {
+ if (!result.ok) {
+ console.error(`[cordis-client-runner] reporting a guard failure of ${pluginId} failed:`, result.error)
+ }
+ }, (error: unknown) => {
+ console.error(`[cordis-client-runner] reporting a guard failure of ${pluginId} failed:`, error)
+ })
+ },
+ })
+ const orchestrator = new CordisRunOrchestrator({
+ runner,
+ host: {
+ // The seam names business payloads only, so a carrier failure is folded
+ // here into whatever each verb already does with one: the short-circuit
+ // message for a start, a throw where the caller has a catch of its own.
+ runHostHalf: async (agentId, pluginId, packageId, mode, requestId, approveFutureVersions) => {
+ const answered = await ctx.remote.dynamicCordisRunner.runHostHalf(
+ agentId, pluginId, packageId, mode, requestId, approveFutureVersions,
+ )
+ return answered.ok ? answered.value : { ok: false, message: `${answered.error.code}: ${answered.error.message}` }
+ },
+ getClientCode: async (agentId, pluginId, pluginRunId) => {
+ const answered = await ctx.remote.dynamicCordisRunner.getClientCode(agentId, pluginId, pluginRunId)
+ if (!answered.ok) throw new Error(`${answered.error.code}: ${answered.error.message}`)
+ return answered.value
+ },
+ resolveRequestRun: async (requestId, resolution) => {
+ const answered = await ctx.remote.dynamicCordisRunner.resolveRequestRun(requestId, resolution)
+ // Thrown rather than returned: `answer` logs and drops a failed answer,
+ // and the host settles the request on its own either way.
+ if (!answered.ok) throw new Error(`${answered.error.code}: ${answered.error.message}`)
+ return answered.value
+ },
+ settleUserRun: async (agentId, pluginId, resolution) => {
+ const answered = await ctx.remote.dynamicCordisRunner.settleUserRun(agentId, pluginId, resolution)
+ if (!answered.ok) throw new Error(`${answered.error.code}: ${answered.error.message}`)
+ return answered.value
+ },
+ },
+ })
+ const face: CordisRunnerFace = {
+ activeRuns: orchestrator.activeRuns,
+ lastRunError: orchestrator.lastRunError,
+ renderFailures: runner.renderFailures,
+ reconcileApprovals: rows => { orchestrator.reconcileApprovals(rows) },
+ approve: (requestId, approveFutureVersions) => orchestrator.approve(requestId, approveFutureVersions),
+ decline: requestId => orchestrator.decline(requestId),
+ startUserRun: request => orchestrator.startUserRun(request),
+ subscribe: fn => runner.subscribe(fn),
+ getSnapshot: () => runner.getSnapshot(),
+ isLoaded: id => runner.isLoaded(id),
+ }
+ ctx.provide('dynamicCordisRunner', face)
+ ctx.effect(() => () => { void runner.dispose() }, 'cordis-client-runner: dynamic package runner')
+
+ // Forwarded Host events: `$on` hands the listener the Host's own argument list,
+ // so these read the request itself rather than a transport envelope.
+ ctx.remote.$on('cordis/request-run', (request) => {
+ orchestrator.open(request)
+ })
+ ctx.remote.$on('cordis/request-run-resolved', (resolved) => { orchestrator.close(resolved.requestId) })
+ ctx.remote.$on('cordis/dynamic-retract', (retracted) => {
+ runner.retract(retracted.pluginId, retracted.pluginRunId)
+ })
+ ctx.remote.$on('cordis/inspect-query', (request) => {
+ void inspect.query(request).catch((error: unknown) => {
+ console.error(`[cordis-client-runner] inspect query ${request.provider}.${request.method} failed:`, error)
+ })
+ })
+ ctx.remote.$on('cordis/inspect-query-resolved', (resolved) => { inspect.close(resolved.requestId) })
+}
diff --git a/packages/extensions/cordis-client-runner/src/client/inspect-registry.ts b/packages/extensions/cordis-client-runner/src/client/inspect-registry.ts
new file mode 100644
index 0000000000..16090cf4ed
--- /dev/null
+++ b/packages/extensions/cordis-client-runner/src/client/inspect-registry.ts
@@ -0,0 +1,146 @@
+/** Browser registry for read-only Cordis capability providers. */
+
+import type { Context } from '@deepseek-ai/cordis'
+import type {
+ CordisInspectProviderManifest, CordisInspectQueryRequest, CordisInspectQueryResolution,
+ CordisInspectRequestId, JsonValue,
+} from '@deepseek-ai/dsh-api-remotes/client'
+import type { SessionId } from '@deepseek-ai/dsh-client-connection/client'
+
+/** Context supplied to a Client inspect provider query. */
+export interface ClientCordisInspectQueryContext {
+ /** Cancellation broadcast by the Host. */
+ signal: AbortSignal
+ /** Session whose model requested the query. */
+ sessionId: SessionId
+}
+
+/** Client provider registration retained beside its serializable manifest. */
+export interface ClientCordisInspectProviderRegistration {
+ /** Provider and explicit query directory. */
+ manifest: CordisInspectProviderManifest
+ /** Execute one declared read-only method. */
+ query(method: string, input: JsonValue | undefined, context: ClientCordisInspectQueryContext): Promise
+}
+
+/** Remote operations needed by the Client registry. */
+export interface ClientCordisInspectHost {
+ /** Replace the Host's mirrored Client manifest. */
+ sync(providers: readonly CordisInspectProviderManifest[]): Promise
+ /** Submit one query result; the first accepted page wins. */
+ resolve(
+ sessionId: SessionId,
+ requestId: CordisInspectRequestId,
+ resolution: CordisInspectQueryResolution,
+ ): Promise
+}
+
+/** Client provider registry, manifest publisher, and live query dispatcher. */
+export class ClientCordisInspectRegistry {
+ private readonly providers = new Map()
+ private readonly active = new Map()
+ private publishQueued = false
+ private syncChain = Promise.resolve()
+
+ /** @param host - folded manifest and query result transport. */
+ constructor(private readonly host: ClientCordisInspectHost) {}
+
+ /**
+ * Register one Client provider and publish a new complete manifest.
+ * @param registration - provider manifest and local handler.
+ * @returns idempotent disposer.
+ */
+ register(registration: ClientCordisInspectProviderRegistration): () => void {
+ const { manifest } = registration
+ if (manifest.id.trim() === '') throw new Error('Client Cordis inspect provider id must not be empty')
+ if (this.providers.has(manifest.id)) throw new Error(`Client Cordis inspect provider "${manifest.id}" is already registered`)
+ const names = new Set()
+ for (const method of manifest.methods) {
+ if (names.has(method.name)) throw new Error(`Client Cordis inspect provider "${manifest.id}" repeats method "${method.name}"`)
+ names.add(method.name)
+ }
+ this.providers.set(manifest.id, registration)
+ this.publish()
+ let disposed = false
+ return () => {
+ if (disposed) return
+ disposed = true
+ if (this.providers.get(manifest.id) === registration) {
+ this.providers.delete(manifest.id)
+ this.publish()
+ }
+ }
+ }
+
+ /** Publish the current complete manifest, including after reconnect. */
+ publish(): void {
+ if (this.publishQueued) return
+ this.publishQueued = true
+ queueMicrotask(() => {
+ this.publishQueued = false
+ const manifests = [...this.providers.values()].map(provider => provider.manifest)
+ this.syncChain = this.syncChain.then(async () => {
+ await this.host.sync(manifests)
+ }).catch((error: unknown) => {
+ console.error('[cordis-client-runner] syncing inspect providers failed:', error)
+ })
+ })
+ }
+
+ /**
+ * Execute and answer one Host-broadcast query.
+ * @param request - exact provider query and Session correlation received from Host.
+ * @returns after the first local result has been sent back to Host.
+ */
+ async query(request: CordisInspectQueryRequest): Promise {
+ if (this.active.has(request.requestId)) return
+ const controller = new AbortController()
+ this.active.set(request.requestId, controller)
+ let resolution: CordisInspectQueryResolution
+ try {
+ const provider = this.providers.get(request.provider)
+ if (provider === undefined) {
+ resolution = { ok: false, reason: 'provider-missing', message: `Client inspect provider "${request.provider}" is unavailable` }
+ } else if (!provider.manifest.methods.some(method => method.name === request.method)) {
+ resolution = { ok: false, reason: 'method-missing', message: `Client inspect provider "${request.provider}" has no method "${request.method}"` }
+ } else {
+ const data = await provider.query(request.method, request.input, {
+ signal: controller.signal,
+ sessionId: request.agentId,
+ })
+ resolution = controller.signal.aborted
+ ? { ok: false, reason: 'cancelled', message: 'Client inspect query was cancelled' }
+ : { ok: true, data }
+ }
+ } catch (error) {
+ resolution = controller.signal.aborted
+ ? { ok: false, reason: 'cancelled', message: 'Client inspect query was cancelled' }
+ : { ok: false, reason: 'provider-error', message: error instanceof Error ? error.message : String(error) }
+ } finally {
+ this.active.delete(request.requestId)
+ }
+ if (controller.signal.aborted) return
+ await this.host.resolve(request.agentId, request.requestId, resolution)
+ }
+
+ /**
+ * Cancel local work after another page answered or the Tool call ended.
+ * @param requestId - query correlation that is no longer answerable.
+ */
+ close(requestId: CordisInspectRequestId): void {
+ this.active.get(requestId)?.abort()
+ this.active.delete(requestId)
+ }
+}
+
+declare module '@deepseek-ai/cordis' {
+ interface Context {
+ /** Browser registry for pre-definition Cordis capability discovery. */
+ cordisInspect: ClientCordisInspectRegistry
+ }
+}
+
+/** Provide the registry as a normal Client service. */
+export function provideClientCordisInspect(ctx: Context, registry: ClientCordisInspectRegistry): void {
+ ctx.provide('cordisInspect', registry)
+}
diff --git a/packages/extensions/cordis-client-runner/src/client/orchestrator.ts b/packages/extensions/cordis-client-runner/src/client/orchestrator.ts
new file mode 100644
index 0000000000..3bbc193b3a
--- /dev/null
+++ b/packages/extensions/cordis-client-runner/src/client/orchestrator.ts
@@ -0,0 +1,442 @@
+/**
+ * Page-side run orchestration for model approvals and direct panel gestures.
+ * Host activation always precedes Client loading. The same Plugin-keyed state
+ * drives every surface, so remounting a panel never loses an open approval or
+ * an in-flight transition.
+ */
+
+import type {
+ ApprovalRequestId,
+ CordisDynamicPackageId,
+ CordisDynamicPluginId,
+ CordisDynamicPluginRunId,
+ CordisDynamicRunMode,
+ DynamicCordisClientSource,
+ DynamicCordisHostHalfResult,
+ DynamicCordisInventoryRow,
+ DynamicCordisResolveAck,
+ DynamicCordisRunResolution,
+ DynamicCordisRunResponse,
+} from '@deepseek-ai/dsh-api-remotes/client'
+import type { SessionId } from '@deepseek-ai/dsh-client-connection/client'
+import { errorDetails } from './runtime.ts'
+import type { CordisErrorDetails, CordisObservable, DynamicCordisPackageRunner } from './runtime.ts'
+
+/** One Plugin's in-flight approval or activation. */
+export type CordisRunActivity =
+ | {
+ phase: 'awaiting-approval'
+ requestId: ApprovalRequestId
+ agentId: SessionId
+ packageId: CordisDynamicPackageId
+ mode: CordisDynamicRunMode
+ name: string
+ purpose: string
+ }
+ | {
+ phase: 'orchestrating'
+ agentId: SessionId
+ packageId: CordisDynamicPackageId
+ mode: CordisDynamicRunMode
+ }
+
+/** Why this page's latest activation attempt failed. */
+export interface CordisRunFailure {
+ /** Package the attempt targeted. */
+ packageId: CordisDynamicPackageId
+ /** Which half or settlement stage failed. */
+ reason: 'host-half-failed' | 'client-half-failed'
+ /** Actionable failure text. */
+ message: string
+ /** Original failure stack when available. */
+ stack?: string
+}
+
+/** Host operations consumed by the orchestrator after transport folding. */
+export interface CordisRunHostSeam {
+ /** Start a new Host activation or attach this page to an existing one. */
+ runHostHalf(
+ agentId: SessionId,
+ pluginId: CordisDynamicPluginId,
+ packageId: CordisDynamicPackageId,
+ mode: CordisDynamicRunMode,
+ requestId: ApprovalRequestId | null,
+ approveFutureVersions: boolean,
+ ): Promise
+ /** Fetch Client source for one exact active run. */
+ getClientCode(
+ agentId: SessionId,
+ pluginId: CordisDynamicPluginId,
+ pluginRunId: CordisDynamicPluginRunId,
+ ): Promise
+ /** Settle a model-driven approval. */
+ resolveRequestRun(
+ requestId: ApprovalRequestId,
+ resolution: DynamicCordisRunResolution,
+ ): Promise
+ /** Settle a direct panel activation after this page handles its Client half. */
+ settleUserRun(
+ agentId: SessionId,
+ pluginId: CordisDynamicPluginId,
+ resolution: DynamicCordisRunResolution,
+ ): Promise
+}
+
+/** Dependencies of one page's orchestrator. */
+export interface CordisRunOrchestratorEnv {
+ /** Page-local Client loader. */
+ runner: DynamicCordisPackageRunner
+ /** Folded Host RPC operations. */
+ host: CordisRunHostSeam
+}
+
+/** Forwarded approval request fields used by this page. */
+export interface CordisRunRequest {
+ requestId: ApprovalRequestId
+ agentId: SessionId
+ pluginId: CordisDynamicPluginId
+ packageId: CordisDynamicPackageId
+ mode: CordisDynamicRunMode
+ name: string
+ purpose: string
+ requiresApproval: boolean
+}
+
+/** Direct panel activation request. */
+export interface CordisUserRunRequest {
+ agentId: SessionId
+ pluginId: CordisDynamicPluginId
+ packageId: CordisDynamicPackageId
+ mode: CordisDynamicRunMode
+ /** Host-only Packages finish without a Client load or settlement call. */
+ hasClientHalf: boolean
+}
+
+interface RunPlan extends CordisUserRunRequest {
+ requestId?: ApprovalRequestId
+ approveFutureVersions?: boolean
+}
+
+/** Drives Host → Client activation and publishes Plugin-keyed activity. */
+export class CordisRunOrchestrator {
+ private readonly requests = new Map()
+ private readonly activity = new Map()
+ private readonly failures = new Map()
+ private readonly inFlight = new Map>()
+ private readonly listeners = new Set<() => void>()
+ private activityCache: ReadonlyMap | undefined
+ private failureCache: ReadonlyMap | undefined
+
+ /** @param env - Client loader and folded Host operations. */
+ constructor(private readonly env: CordisRunOrchestratorEnv) {}
+
+ /** Open approvals and current activation attempts, keyed by stable Plugin ID. */
+ readonly activeRuns: CordisObservable> = {
+ getSnapshot: () => this.activityCache ??= new Map(this.activity),
+ subscribe: fn => this.observe(fn),
+ }
+
+ /** Latest page-side activation failure for each Plugin. */
+ readonly lastRunError: CordisObservable> = {
+ getSnapshot: () => this.failureCache ??= new Map(this.failures),
+ subscribe: fn => this.observe(fn),
+ }
+
+ /** Register a Client activation request, starting it immediately when the Plugin is already authorized. */
+ open(request: CordisRunRequest): void {
+ this.requests.set(request.requestId, request)
+ if (!request.requiresApproval) {
+ void this.orchestrate({
+ agentId: request.agentId,
+ pluginId: request.pluginId,
+ packageId: request.packageId,
+ mode: request.mode,
+ requestId: request.requestId,
+ hasClientHalf: true,
+ }).catch((error: unknown) => {
+ console.error(`[cordis-client-runner] automatic activation ${request.requestId} failed:`, error)
+ })
+ return
+ }
+ if (this.activity.get(request.pluginId)?.phase !== 'orchestrating') {
+ this.activity.set(request.pluginId, {
+ phase: 'awaiting-approval',
+ requestId: request.requestId,
+ agentId: request.agentId,
+ packageId: request.packageId,
+ mode: request.mode,
+ name: request.name,
+ purpose: request.purpose,
+ })
+ }
+ this.commit()
+ }
+
+ /**
+ * Rebuild pending approvals and automatic Client activations from an authoritative Host inventory read.
+ * @param rows - complete process-wide Plugin inventory.
+ */
+ reconcileApprovals(rows: readonly DynamicCordisInventoryRow[]): void {
+ const expected = new Map()
+ for (const row of rows) {
+ const attempt = row.latestRun
+ if (attempt?.approvalRequestId === undefined
+ || (attempt.status !== 'awaiting-approval'
+ && attempt.status !== 'starting-host'
+ && attempt.status !== 'client-pending')) continue
+ const pkg = row.packages.find(candidate => candidate.packageId === attempt.packageId)
+ if (pkg === undefined) continue
+ expected.set(attempt.approvalRequestId, {
+ requestId: attempt.approvalRequestId,
+ agentId: row.agentId,
+ pluginId: row.pluginId,
+ packageId: attempt.packageId,
+ mode: attempt.mode,
+ name: pkg.name,
+ purpose: pkg.purpose,
+ requiresApproval: attempt.requiresApproval ?? attempt.status === 'awaiting-approval',
+ })
+ }
+
+ let changed = false
+ for (const [requestId, request] of [...this.requests]) {
+ if (expected.has(requestId)) continue
+ this.requests.delete(requestId)
+ const current = this.activity.get(request.pluginId)
+ if (current?.phase === 'awaiting-approval' && current.requestId === requestId) {
+ this.activity.delete(request.pluginId)
+ }
+ changed = true
+ }
+ for (const [requestId, request] of expected) {
+ const previous = this.requests.get(requestId)
+ const current = this.activity.get(request.pluginId)
+ if (!request.requiresApproval && current?.phase === 'orchestrating') continue
+ if (request.requiresApproval
+ && sameRequest(previous, request)
+ && current?.phase === 'awaiting-approval'
+ && current.requestId === requestId) continue
+ if (!request.requiresApproval) {
+ this.open(request)
+ changed = true
+ continue
+ }
+ this.requests.set(requestId, request)
+ if (current?.phase !== 'orchestrating') {
+ this.activity.set(request.pluginId, {
+ phase: 'awaiting-approval',
+ requestId,
+ agentId: request.agentId,
+ packageId: request.packageId,
+ mode: request.mode,
+ name: request.name,
+ purpose: request.purpose,
+ })
+ }
+ changed = true
+ }
+ if (changed) this.commit()
+ }
+
+ /** Close an approval settled by another page or by cancellation. */
+ close(requestId: ApprovalRequestId): void {
+ const request = this.requests.get(requestId)
+ if (request === undefined) return
+ this.requests.delete(requestId)
+ const current = this.activity.get(request.pluginId)
+ if (current?.phase === 'awaiting-approval' && current.requestId === requestId) {
+ this.activity.delete(request.pluginId)
+ }
+ this.commit()
+ }
+
+ /** Approve and execute one still-open model request. */
+ approve(requestId: ApprovalRequestId, approveFutureVersions: boolean): Promise {
+ const request = this.requests.get(requestId)
+ if (request === undefined || !request.requiresApproval) return Promise.resolve()
+ return this.orchestrate({
+ agentId: request.agentId,
+ pluginId: request.pluginId,
+ packageId: request.packageId,
+ mode: request.mode,
+ requestId,
+ approveFutureVersions,
+ hasClientHalf: true,
+ })
+ }
+
+ /** Reject one still-open model request without executing either half. */
+ async decline(requestId: ApprovalRequestId): Promise {
+ const request = this.requests.get(requestId)
+ if (request === undefined || !request.requiresApproval) return
+ const current = this.activity.get(request.pluginId)
+ if (current?.phase !== 'awaiting-approval' || current.requestId !== requestId) return
+ this.requests.delete(requestId)
+ this.activity.delete(request.pluginId)
+ this.commit()
+ await this.answer(requestId, { ok: false, reason: 'rejected' })
+ }
+
+ /** Execute a direct panel run; the user gesture itself authorizes it. */
+ startUserRun(request: CordisUserRunRequest): Promise {
+ return this.orchestrate(request)
+ }
+
+ private observe(fn: () => void): () => void {
+ this.listeners.add(fn)
+ return () => { this.listeners.delete(fn) }
+ }
+
+ private commit(): void {
+ this.activityCache = undefined
+ this.failureCache = undefined
+ for (const fn of [...this.listeners]) fn()
+ }
+
+ private orchestrate(plan: RunPlan): Promise {
+ const running = this.inFlight.get(plan.pluginId)
+ if (running !== undefined) return running
+ this.activity.set(plan.pluginId, {
+ phase: 'orchestrating',
+ agentId: plan.agentId,
+ packageId: plan.packageId,
+ mode: plan.mode,
+ })
+ this.failures.delete(plan.pluginId)
+ if (plan.requestId !== undefined) this.requests.delete(plan.requestId)
+ this.commit()
+ const attempt = this.drive(plan).finally(() => {
+ this.inFlight.delete(plan.pluginId)
+ this.activity.delete(plan.pluginId)
+ this.commit()
+ })
+ this.inFlight.set(plan.pluginId, attempt)
+ return attempt
+ }
+
+ private async drive(plan: RunPlan): Promise {
+ const started = await this.startHost(plan)
+ if (!started.ok) {
+ this.fail(plan, 'host-half-failed', started)
+ if (plan.requestId !== undefined) {
+ await this.answer(plan.requestId, { ...started, reason: 'host-half-failed' })
+ }
+ return
+ }
+ if (!plan.hasClientHalf) return
+
+ let source: DynamicCordisClientSource
+ try {
+ source = await this.env.host.getClientCode(plan.agentId, plan.pluginId, started.pluginRunId)
+ } catch (error) {
+ await this.finishClientFailure(plan, started.pluginRunId, started.startedHere, errorDetails(error), error)
+ return
+ }
+ const loaded = await this.env.runner.load({
+ pluginId: source.pluginId,
+ packageId: source.packageId,
+ pluginRunId: source.pluginRunId,
+ agentId: plan.agentId,
+ name: source.name,
+ code: source.code,
+ }).catch((error: unknown) => ({ ok: false, cause: 'evaluate', ...errorDetails(error), error }) as const)
+ if (!loaded.ok) {
+ await this.finishClientFailure(
+ plan,
+ started.pluginRunId,
+ started.startedHere,
+ {
+ message: `${loaded.cause}: ${loaded.message}`,
+ ...loaded.stack === undefined ? {} : { stack: loaded.stack },
+ },
+ loaded.error,
+ )
+ return
+ }
+ const resolution: DynamicCordisRunResolution = {
+ ok: true,
+ pluginRunId: loaded.pluginRunId,
+ ...loaded.waitingFor === undefined ? {} : { waitingFor: loaded.waitingFor },
+ }
+ if (plan.requestId !== undefined) {
+ await this.answer(plan.requestId, resolution)
+ return
+ }
+ await this.settleDirect(plan, resolution)
+ }
+
+ private async startHost(plan: RunPlan): Promise {
+ try {
+ return await this.env.host.runHostHalf(
+ plan.agentId,
+ plan.pluginId,
+ plan.packageId,
+ plan.mode,
+ plan.requestId ?? null,
+ plan.approveFutureVersions ?? false,
+ )
+ } catch (error) {
+ return { ok: false, ...errorDetails(error) }
+ }
+ }
+
+ private async finishClientFailure(
+ plan: RunPlan,
+ pluginRunId: CordisDynamicPluginRunId,
+ startedHere: boolean,
+ failure: CordisErrorDetails,
+ originalError?: unknown,
+ ): Promise {
+ console.error(
+ `[cordis-client-runner] Client activation ${plan.pluginId}/${plan.packageId} (${pluginRunId}) failed:`,
+ originalError ?? failure,
+ )
+ this.fail(plan, 'client-half-failed', failure)
+ const resolution: DynamicCordisRunResolution = {
+ ok: false,
+ reason: 'client-half-failed',
+ pluginRunId,
+ startedHere,
+ ...failure,
+ }
+ if (plan.requestId !== undefined) await this.answer(plan.requestId, resolution)
+ else await this.settleDirect(plan, resolution)
+ }
+
+ private async settleDirect(plan: RunPlan, resolution: DynamicCordisRunResolution): Promise {
+ try {
+ const response = await this.env.host.settleUserRun(plan.agentId, plan.pluginId, resolution)
+ if (!response.ok) this.fail(plan, 'client-half-failed', response)
+ } catch (error) {
+ this.fail(plan, 'client-half-failed', errorDetails(error))
+ }
+ }
+
+ private async answer(requestId: ApprovalRequestId, resolution: DynamicCordisRunResolution): Promise {
+ try {
+ await this.env.host.resolveRequestRun(requestId, resolution)
+ } catch (error) {
+ console.error(`[cordis-client-runner] answering run request ${requestId} failed:`, error)
+ }
+ }
+
+ private fail(
+ plan: Pick,
+ reason: CordisRunFailure['reason'],
+ failure: CordisErrorDetails,
+ ): void {
+ this.failures.set(plan.pluginId, { packageId: plan.packageId, reason, ...failure })
+ this.commit()
+ }
+}
+
+function sameRequest(left: CordisRunRequest | undefined, right: CordisRunRequest): boolean {
+ return left?.requestId === right.requestId
+ && left.agentId === right.agentId
+ && left.pluginId === right.pluginId
+ && left.packageId === right.packageId
+ && left.mode === right.mode
+ && left.name === right.name
+ && left.purpose === right.purpose
+ && left.requiresApproval === right.requiresApproval
+}
diff --git a/packages/extensions/cordis-client-runner/src/client/providers.ts b/packages/extensions/cordis-client-runner/src/client/providers.ts
new file mode 100644
index 0000000000..4d5cbe5672
--- /dev/null
+++ b/packages/extensions/cordis-client-runner/src/client/providers.ts
@@ -0,0 +1,219 @@
+/** Built-in Client inspect providers over live Client-owned services. */
+
+import type { Context } from '@deepseek-ai/cordis'
+import type { JsonValue } from '@deepseek-ai/dsh-api-remotes/client'
+import type { SlotsService } from '@deepseek-ai/dsh-client-runtime/client'
+import type { ThemeService } from '@deepseek-ai/dsh-client-ui-theme/client'
+import { queryEventApi, queryServiceApi } from './api-catalog.ts'
+import type { ClientCordisInspectProviderRegistration } from './inspect-registry.ts'
+import { CLIENT_SLOT_API } from './slot-catalog.ts'
+import type { ClientSlotEntry } from './slot-catalog.ts'
+
+const EMPTY_INPUT = { type: 'object', properties: {}, additionalProperties: false } as const
+const ANY_OUTPUT = { description: 'JSON data owned by this inspect provider.' } as const
+const SERVICE_INPUT = exactInput('service', 'Exact Service key. Omit it for the compact Service and method-signature directory.')
+const EVENT_INPUT = exactInput('event', 'Exact Event name. Omit it for the compact Event and listener-signature directory.')
+const SERVICE_OUTPUT = {
+ description: 'Compact Service directory, or one exact Service contract with only its referenced type declarations.',
+} as const
+const EVENT_OUTPUT = {
+ description: 'Compact Event directory, or one exact Event contract with only its referenced type declarations.',
+} as const
+const SUBTREE_OUTPUT = {
+ description: 'Compact purpose/topology trees. With root, selected also contains that Slot\'s full contract and live occupants.',
+} as const
+const SUBTREE_INPUT = {
+ type: 'object',
+ properties: {
+ root: {
+ type: 'string',
+ description: 'Exact live Slot key. When supplied, selected contains the full contract for this Slot.',
+ },
+ },
+ additionalProperties: false,
+} as const
+
+/** Exact Client closure symbols exposed by the evaluator and guard. */
+export const CLIENT_BUILTIN_INSPECTION: readonly JsonValue[] = [
+ {
+ name: 'ctx',
+ description: 'Restricted Cordis Context. Prefer ctx.get(name) with an undefined check; use inject only for hard dependencies.',
+ signatures: [
+ 'ctx.get(name: string): unknown | undefined',
+ 'ctx.on(name: string, listener: Function): () => void',
+ 'ctx.provide(name: string, value: unknown): () => void',
+ 'ctx.effect(callback: Function, label?: string): () => void',
+ ],
+ },
+ {
+ name: 'React',
+ description: 'React runtime exposed without JSX transformation.',
+ signatures: ['React.createElement(type, props, ...children): ReactElement', 'React.useState(initial)', 'React.useEffect(effect, deps)'],
+ },
+ {
+ name: 'host',
+ description: 'Package-private JSON RPC from Client to this Package\'s Host half.',
+ signatures: ['host.call(method: string, args?: JsonValue): Promise'],
+ },
+ {
+ name: 'styles',
+ description: 'Package-owned stylesheet insertion cleaned up with the Client run.',
+ signatures: ['styles.insert(css: string): () => void'],
+ },
+ {
+ name: 'console',
+ description: 'Package-tagged browser logging.',
+ signatures: ['console.log(...values): void', 'console.error(...values): void'],
+ },
+]
+
+/** Construct the first-party Client provider registrations. */
+export function clientInspectProviders(ctx: Context): ClientCordisInspectProviderRegistration[] {
+ return [
+ registration(
+ 'Service',
+ 'Progressive Client Service discovery: compact capability/signature directory, then one exact coding contract.',
+ 'listService',
+ async input => queryServiceApi(readExact(input, 'service')) as unknown as JsonValue,
+ SERVICE_INPUT,
+ SERVICE_OUTPUT,
+ ),
+ registration(
+ 'Event',
+ 'Progressive Client Event discovery: compact listener directory, then one exact event contract.',
+ 'listEvents',
+ async input => queryEventApi(readExact(input, 'event')) as unknown as JsonValue,
+ EVENT_INPUT,
+ EVENT_OUTPUT,
+ ),
+ registration('Builtin', 'Plain-JavaScript symbols available to a dynamic Client half.', 'listBuiltins', async () => ({
+ builtins: [...CLIENT_BUILTIN_INSPECTION],
+ referencedTypes: [],
+ })),
+ {
+ manifest: {
+ id: 'Slots',
+ description: 'Progressive live Slot inspection: compact purpose/topology trees plus one exact Slot contract.',
+ methods: [{
+ name: 'listSubTree',
+ description: 'Return compact live Slot trees for navigation. With root, also return the selected Slot\'s full contract and occupants.',
+ inputSchema: SUBTREE_INPUT,
+ outputSchema: SUBTREE_OUTPUT,
+ }],
+ },
+ async query(method, input) {
+ if (method !== 'listSubTree') throw new Error(`unknown Slots inspect method "${method}"`)
+ const slots = ctx.get('slots') as SlotsService | undefined
+ if (slots === undefined) throw new Error('Client Slots service is not running')
+ const root = typeof input === 'object' && input !== null && !Array.isArray(input)
+ && typeof input.root === 'string' ? input.root : undefined
+ const trees = slots.snapshot(root)
+ const selected = trees[0]
+ return {
+ ...root === undefined ? {} : { requestedRoot: { name: root, available: trees.length > 0 } },
+ trees: trees.map(compactSlotTree),
+ ...root === undefined || selected === undefined ? {} : { selected: inspectLiveSlot(selected) },
+ referencedTypes: [],
+ } as unknown as JsonValue
+ },
+ },
+ registration('Theme', 'Current theme token names and light/dark override requirements.', 'listTokens', async () => {
+ const theme = ctx.get('theme') as ThemeService | undefined
+ if (theme === undefined) throw new Error('Client Theme service is not running')
+ return { tokens: theme.exportInspectTokens(), referencedTypes: [] } as unknown as JsonValue
+ }),
+ ]
+}
+
+function registration(
+ id: string,
+ description: string,
+ method: string,
+ query: (input: JsonValue | undefined) => Promise,
+ inputSchema: JsonValue = EMPTY_INPUT,
+ outputSchema: JsonValue = ANY_OUTPUT,
+): ClientCordisInspectProviderRegistration {
+ return {
+ manifest: {
+ id,
+ description,
+ methods: [{
+ name: method,
+ description,
+ inputSchema,
+ outputSchema,
+ }],
+ },
+ async query(requested, input) {
+ if (requested !== method) throw new Error(`unknown ${id} inspect method "${requested}"`)
+ return await query(input)
+ },
+ }
+}
+
+function exactInput(field: string, description: string): JsonValue {
+ return { type: 'object', properties: { [field]: { type: 'string', description } }, additionalProperties: false }
+}
+
+function readExact(input: JsonValue | undefined, field: string): string | undefined {
+ if (input === undefined || input === null || Array.isArray(input) || typeof input !== 'object') return undefined
+ const value = input[field]
+ return typeof value === 'string' ? value : undefined
+}
+
+type LiveSlotNode = ReturnType[number]
+
+const SLOT_CATALOG = new Map(CLIENT_SLOT_API.map(entry => [entry.key, entry]))
+
+function compactSlotTree(node: LiveSlotNode): JsonValue {
+ const catalog = SLOT_CATALOG.get(node.name)
+ return {
+ name: node.name,
+ kind: node.kind,
+ scope: node.scope,
+ ...catalog === undefined ? {} : {
+ purpose: catalog.summary,
+ replaceRisk: catalog.replaceRisk,
+ ...catalog.registerOptions.length === 0 ? {} : {
+ registration: catalog.registerOptions.map(option => ({
+ name: option.name,
+ type: option.type,
+ required: option.requirement === 'required',
+ })),
+ },
+ ...catalog.keyDomain === '' ? {} : { keyDomain: catalog.keyDomain },
+ },
+ children: node.children.map(compactSlotTree),
+ } as unknown as JsonValue
+}
+
+function inspectLiveSlot(node: LiveSlotNode): JsonValue {
+ const catalog = SLOT_CATALOG.get(node.name)
+ return {
+ name: node.name,
+ kind: node.kind,
+ scope: node.scope,
+ ...node.declaredBy === undefined ? {} : { declaredBy: node.declaredBy },
+ occupants: node.occupants.map(occupant => ({ ...occupant })),
+ ...catalog === undefined ? {} : { catalog: inspectSlotCatalog(catalog) },
+ } as unknown as JsonValue
+}
+
+function inspectSlotCatalog(entry: ClientSlotEntry): JsonValue {
+ return {
+ description: entry.doc,
+ registration: entry.registerOptions.map(option => ({
+ name: option.name,
+ type: option.type,
+ required: option.requirement === 'required',
+ description: option.doc,
+ })),
+ ownerProps: [...entry.ownerProps],
+ ownerPropsReferences: [...entry.ownerPropsReferences],
+ standardProps: [...entry.standardProps],
+ keyDomain: entry.keyDomain,
+ hookContext: entry.hookContext,
+ slotInject: entry.slotInject,
+ replaceRisk: entry.replaceRisk,
+ } as unknown as JsonValue
+}
diff --git a/packages/extensions/cordis-client-runner/src/client/runtime.ts b/packages/extensions/cordis-client-runner/src/client/runtime.ts
new file mode 100644
index 0000000000..209a3d4d21
--- /dev/null
+++ b/packages/extensions/cordis-client-runner/src/client/runtime.ts
@@ -0,0 +1,506 @@
+/**
+ * Per-package browser lifecycle: evaluate the closure, wrap `apply` in the guard
+ * facade, seat a ready-made factory in the module table, and create a loader
+ * entry — so dynamic packages ride the exact machinery static plugins do
+ * (activation gating on inject, fiber-effect cleanup, status projection). Unload
+ * = loader entry removal (fiber disposal cascades slot entries and facade
+ * effects) + factory invalidation + style removal.
+ *
+ * The engine answers its caller: `load` resolves with what this page ended up
+ * with, which is what the run orchestration reports back to the host. Loads
+ * converge by Plugin Run ID against live state, not history: loading the exact
+ * activation this page already runs is a no-op that still answers, another run
+ * replaces it, and the same Package after a retract loads afresh. Per-Plugin
+ * serialization keeps a second request from interleaving with one in flight.
+ */
+
+import type { Context } from '@deepseek-ai/cordis'
+import type { Loader } from '@deepseek-ai/cordis-plugin-loader'
+import type {
+ CordisDynamicPackageId, CordisDynamicPluginId, CordisDynamicPluginRunId, DynamicCordisPackage,
+} from '@deepseek-ai/dsh-api-remotes/client'
+import type { SessionId } from '@deepseek-ai/dsh-client-connection/client'
+import type { ClientModuleSystem } from '@deepseek-ai/dsh-client-modules/client'
+import type { SlotsService } from '@deepseek-ai/dsh-client-runtime/client'
+import { DynamicCordisStyles, evaluateClientHalf, DYNAMIC_CLIENT_REDIRECTS } from './evaluator.ts'
+import type { DynamicCordisEvaluatedPlugin } from './evaluator.ts'
+import { dynamicCordisContext } from './guard.ts'
+import type { DynamicCordisSlotLedgerRow } from './guard.ts'
+
+/**
+ * Snapshot source a surface can subscribe to (the render seam's observable
+ * shape). Lives here because both this engine and the run orchestration publish
+ * through it, and the orchestration already depends on this module.
+ */
+export interface CordisObservable {
+ /** Current value; the reference is stable between mutations. */
+ getSnapshot(): T
+ /**
+ * Observe mutations.
+ * @param fn - notified after each committed change.
+ * @returns unsubscribe.
+ */
+ subscribe(fn: () => void): () => void
+}
+
+/** Which stage of a load failed, as the page classified it. */
+export type DynamicCordisLoadErrorCause = 'evaluate' | 'module-import' | 'activate'
+
+/** Error fields retained by the page runner and Host transport. */
+export interface CordisErrorDetails {
+ /** Original error message. */
+ message: string
+ /** Original stack when the thrown value supplied one. */
+ stack?: string
+}
+
+/** One package's browser half as the host handed it over. */
+export interface DynamicCordisClientHalf {
+ /** Stable Plugin instance. */
+ pluginId: CordisDynamicPluginId
+ /** Immutable Package source version. */
+ packageId: CordisDynamicPackageId
+ /** Exact activation. */
+ pluginRunId: CordisDynamicPluginRunId
+ /** Session the run is carried out for; a later render failure is reported under it. */
+ agentId: SessionId
+ /** Label from the define call; also the plugin name. */
+ name: string
+ /** Browser-half source: an async function body returning a plugin. */
+ code: string
+}
+
+/**
+ * One render-time crash of a dynamic package's slot entry, as this page reports
+ * it. Post-settle diagnosis only: the run it belongs to was answered long before
+ * (a package that crashes while rendering loaded successfully), so this never
+ * reaches a run resolution.
+ */
+export interface DynamicCordisRenderFailure {
+ /** Slot key the crashed entry rendered under. */
+ slot: string
+ /** What the author has to read to fix it: the crash text, plus a redirect when it names a withheld global. */
+ message: string
+ /** Original render failure stack when available. */
+ stack?: string
+ /** Whether the crash retired the entry from its cell — the package's UI is gone, not merely broken. */
+ abdicated: boolean
+}
+
+/**
+ * What this page ended up with. A parked package is a success — the browser half
+ * settled and waits on declared services this page has not got.
+ */
+export type DynamicCordisLoadResult =
+ | { ok: true; pluginRunId: CordisDynamicPluginRunId; waitingFor?: string[] }
+ | ({ ok: false; cause: DynamicCordisLoadErrorCause; error?: unknown } & CordisErrorDetails)
+
+/** The `window.__ModuleLoader__` registration sink (client-modules contract C6). */
+interface ModuleLoaderSink {
+ __ModuleLoader__?: {
+ load(handoff: { id: string; factory: (require: (spec: string) => unknown) => unknown }): void
+ }
+}
+
+/** One live package's bookkeeping. */
+interface LivePackage {
+ pkg: DynamicCordisPackage
+ entryId: string
+ styles: DynamicCordisStyles
+ ledger: DynamicCordisSlotLedgerRow[]
+ /** Services the browser half declared and this page has not got (parked, still a success). */
+ waitingFor: string[]
+}
+
+/** Runner dependencies, resolved by the plugin entry at activation. */
+export interface DynamicCordisRunnerEnv {
+ /** The client root context (service reads and the guard's fiber owner). */
+ ctx: Context
+ /** Client cordis Loader: dynamic packages become entries under it. */
+ loader: Loader
+ /** Module table, for factory invalidation before every (re-)registration. */
+ modules: ClientModuleSystem
+ /** Slot registry, for the entry-crash supervision seam. */
+ slots: SlotsService
+ /** Route one `host.call` to the package's host half through the Remote namespace. */
+ invoke(
+ pluginId: CordisDynamicPluginId,
+ pluginRunId: CordisDynamicPluginRunId,
+ method: string,
+ args: unknown,
+ ): Promise
+ /**
+ * Send one render-time crash back to the session that authored the package.
+ * Fire-and-forget by contract: the crash already happened, and a failed report
+ * must not become a second failure.
+ * @param agentId - session the crashed package was run for.
+ * @param id - the crashed package.
+ * @param failure - slot, teaching text, and whether the entry was retired.
+ */
+ reportRenderFailure(
+ agentId: SessionId,
+ pluginId: CordisDynamicPluginId,
+ pluginRunId: CordisDynamicPluginRunId,
+ failure: DynamicCordisRenderFailure,
+ ): void
+ /** Send one post-activation Client guard rejection to the owning Agent. */
+ reportGuardFailure(
+ agentId: SessionId,
+ pluginId: CordisDynamicPluginId,
+ pluginRunId: CordisDynamicPluginRunId,
+ failure: CordisErrorDetails,
+ ): void
+}
+
+/** Module-table id of one package (also its loader entry name and fiber name). */
+function moduleIdOf(id: CordisDynamicPluginId): string {
+ return `dyn/${id}`
+}
+
+/** One live package's contribution summary in this page. */
+export interface DynamicCordisLivePackage {
+ /** Stable Plugin instance. */
+ pluginId: CordisDynamicPluginId
+ /** Immutable Package source version. */
+ packageId: CordisDynamicPackageId
+ /** Exact activation loaded in this page. */
+ pluginRunId: CordisDynamicPluginRunId
+ /** Label from the define call. */
+ name: string
+ /** Slot names this package registered into here. */
+ slots: string[]
+ /** Live injected-style tag count. */
+ styleCount: number
+}
+
+/** The browser-side load engine for dynamic packages. */
+export class DynamicCordisPackageRunner {
+ private readonly live = new Map()
+ /** Serializes load/unload per package id (a second request can outrun a slow load). */
+ private readonly queues = new Map>()
+ private readonly changeListeners = new Set<() => void>()
+ /** Page-local shadowing rank. A later registration receives a lower priority. */
+ private nextPriority = 0
+ /**
+ * Which package seated which component, and for whom. Component identity is the
+ * only attribution key that holds:
+ * - the registry stores the component verbatim, so a crashed entry carries its
+ * own way back — no parallel entry ledger to keep in step;
+ * - `entry.registrant` is `options.registrant ?? fiber.name` and the facade does
+ * not strip a package-supplied one, so a package could name itself something
+ * else — attributing by it would let a package impersonate another;
+ * - the assigned shadowing priority is unique but absent on chain entries (their
+ * election is deliberately left alone), so it would miss chain crashes;
+ * - a package torn down between the crash and the report is still attributable,
+ * because this index does not depend on the live record.
+ *
+ * Two packages cannot collide here: each browser half is evaluated in its own
+ * closure, so no component object reaches two of them. A collision is only
+ * possible inside ONE package (the same component seated twice), where both
+ * entries map to the same id and the value is identical.
+ */
+ private readonly owners = new WeakMap()
+ /** This page's last render crash per package: what a run surface shows on the row. */
+ private readonly failures = new Map()
+ private readonly unwatch: () => void
+ private snapshotCache: readonly DynamicCordisLivePackage[] | undefined
+ private failureCache: ReadonlyMap | undefined
+
+ /** @param env - loader/module/slot wiring plus the two host verbs this engine uses. */
+ constructor(private readonly env: DynamicCordisRunnerEnv) {
+ // The supervision seam fires for EVERY entry crash on the page, factory UI
+ // included; only the ones this runner seated are ours to report.
+ this.unwatch = env.slots.onEntryError((slot, entry, error, info) => {
+ const component: unknown = (entry as { component?: unknown }).component
+ const owner = indexable(component) ? this.owners.get(component) : undefined
+ if (owner === undefined) return
+ const details = errorDetails(error)
+ const failure: DynamicCordisRenderFailure = {
+ slot,
+ message: renderFailureMessage(slot, details.message),
+ ...details.stack === undefined ? {} : { stack: details.stack },
+ abdicated: info.abdicated,
+ }
+ // One observation, two outlets with different owners and lifetimes: the host
+ // keeps the last crash ACROSS pages for the model, this map is what THIS page
+ // currently shows. Neither is derived from the other.
+ env.reportRenderFailure(owner.agentId, owner.pluginId, owner.pluginRunId, failure)
+ this.failures.set(owner.pluginId, failure)
+ this.notify()
+ })
+ }
+
+ /**
+ * Observe live-set changes (the run-state surface's re-render seam).
+ * @param fn - notified after every converged mutation.
+ * @returns unsubscribe.
+ */
+ subscribe(fn: () => void): () => void {
+ this.changeListeners.add(fn)
+ return () => { this.changeListeners.delete(fn) }
+ }
+
+ /**
+ * This page's last render crash per package, on the same notification channel as
+ * the live set — a surface that already subscribed learns about a crash without
+ * a second mechanism to wire.
+ */
+ readonly renderFailures: CordisObservable> = {
+ getSnapshot: () => this.failureCache ??= new Map(this.failures),
+ subscribe: fn => this.subscribe(fn),
+ }
+
+ /**
+ * What this page currently has loaded (stable reference between mutations, so
+ * it can back a snapshot selector).
+ * @returns one row per live package.
+ */
+ getSnapshot(): readonly DynamicCordisLivePackage[] {
+ return this.snapshotCache ??= [...this.live.values()].map(({ pkg, ledger, styles }) => ({
+ pluginId: pkg.pluginId,
+ packageId: pkg.packageId,
+ pluginRunId: pkg.pluginRunId,
+ name: pkg.name,
+ slots: [...new Set(ledger.map(row => row.slot))],
+ styleCount: styles.count,
+ }))
+ }
+
+ /**
+ * Whether this page has the browser half loaded — page-local truth, never the
+ * host's "it is running".
+ * @param pluginId - stable Plugin identity.
+ * @returns true while one activation of the Plugin is live here.
+ */
+ isLoaded(pluginId: CordisDynamicPluginId): boolean {
+ return this.live.has(pluginId)
+ }
+
+ /**
+ * Load one browser half into this page and answer what happened.
+ * @param half - source for one exact Host activation.
+ * @returns the outcome the run orchestration reports to the host.
+ */
+ load(half: DynamicCordisClientHalf): Promise {
+ return this.enqueue(half.pluginId, async () => {
+ const current = this.live.get(half.pluginId)
+ if (current !== undefined) {
+ // Already running this activation here: nothing to load, but the caller
+ // still needs an answer (a replayed run must not look unacknowledged).
+ if (current.pkg.pluginRunId === half.pluginRunId) return settled(current)
+ await this.teardown(current.pkg.pluginId, current.entryId, current.styles)
+ }
+ const result = await this.mount(half)
+ this.notify()
+ return result
+ })
+ }
+
+ /**
+ * Unload one package (`cordis/dynamic-retract`: a stop, or an undefine
+ * that stops first).
+ * @param pluginId - stable Plugin identity.
+ * @param pluginRunId - exact activation being retracted; a newer run survives.
+ */
+ retract(pluginId: CordisDynamicPluginId, pluginRunId: CordisDynamicPluginRunId): void {
+ void this.enqueue(pluginId, async () => {
+ const current = this.live.get(pluginId)
+ if (current === undefined || current.pkg.pluginRunId !== pluginRunId) return
+ await this.teardown(pluginId, current.entryId, current.styles)
+ this.notify()
+ })
+ }
+
+ /** Unload everything (plugin disposal path). */
+ async dispose(): Promise {
+ this.unwatch()
+ for (const current of [...this.live.values()]) {
+ await this.teardown(current.pkg.pluginId, current.entryId, current.styles)
+ }
+ this.notify()
+ }
+
+ private notify(): void {
+ this.snapshotCache = undefined
+ this.failureCache = undefined
+ for (const fn of [...this.changeListeners]) fn()
+ }
+
+ /** Queue one package operation behind that package's previous ones. */
+ private enqueue(id: CordisDynamicPluginId, op: () => Promise): Promise {
+ const previous = this.queues.get(id) ?? Promise.resolve()
+ const next = previous.then(op)
+ // The queue tail must survive this operation's failure, or one rejection
+ // would wedge every later operation on the same package.
+ this.queues.set(id, next.then(() => {}, () => {}))
+ return next
+ }
+
+ private async mount(half: DynamicCordisClientHalf): Promise {
+ const styles = new DynamicCordisStyles(half.pluginId)
+ const ledger: DynamicCordisSlotLedgerRow[] = []
+ let plugin: DynamicCordisEvaluatedPlugin | ((ctx: unknown) => unknown)
+ try {
+ plugin = await evaluateClientHalf(half.pluginId, half.code, {
+ invoke: (method, args) => this.env.invoke(half.pluginId, half.pluginRunId, method, args),
+ noteError: (message) => {
+ // A loaded package's own console.error: a page-local diagnostic with
+ // no wire carrier (the run round trip settled long before).
+ console.error(`[cordis-client-runner] ${half.pluginId} logged an error:`, message)
+ },
+ }, styles)
+ } catch (error) {
+ styles.dispose()
+ return { ok: false, cause: 'evaluate', ...errorDetails(error), error }
+ }
+
+ const pkg: DynamicCordisPackage = {
+ pluginId: half.pluginId,
+ packageId: half.packageId,
+ pluginRunId: half.pluginRunId,
+ name: half.name,
+ }
+ const surface = this.guardedSurface(pkg, half.agentId, plugin, ledger)
+ const moduleId = moduleIdOf(half.pluginId)
+ // Invalidate-then-register keeps re-loading legal: the module table throws
+ // loudly on a duplicate factory registration.
+ this.env.modules.invalidate(moduleId)
+ const sink = (globalThis as ModuleLoaderSink).__ModuleLoader__
+ if (sink === undefined) {
+ throw new Error('cordis-client-runner: window.__ModuleLoader__ is missing (booted outside the web shell?)')
+ }
+ sink.load({ id: moduleId, factory: () => surface })
+
+ const entryId = await this.env.loader.create({ name: moduleId })
+ const fiber = this.env.loader.resolve(entryId).fiber
+ if (fiber === undefined) {
+ await this.teardown(half.pluginId, entryId, styles)
+ return { ok: false, cause: 'module-import', message: 'module import failed (see the browser console)' }
+ }
+ try {
+ await fiber.await()
+ } catch (error) {
+ await this.teardown(half.pluginId, entryId, styles)
+ return { ok: false, cause: 'activate', ...errorDetails(error), error }
+ }
+ // Settled but not active = legal pending on an unsatisfied declaration. The
+ // record is seated only now, so an error mirrored during `apply` cannot
+ // claim the package is already live.
+ const waitingFor = Object.keys(fiber.inject).filter(name => this.env.ctx.get(name) === undefined)
+ const record: LivePackage = { pkg, entryId, styles, ledger, waitingFor }
+ this.live.set(half.pluginId, record)
+ // A fresh load answers for itself: whatever this page last showed as crashed
+ // is no longer true of what is mounted now.
+ this.failures.delete(half.pluginId)
+ return settled(record)
+ }
+
+ /**
+ * Wrap the evaluated plugin so `apply` sees the guard facade; the surface
+ * doubles as the module-table module. The plugin's OWN `inject` survives (the
+ * object form's declaration is the facade's service gate, mirroring the host
+ * sandbox reading `ctx.fiber.inject`); the function form has no declaration
+ * site and therefore reaches no service.
+ */
+ private guardedSurface(
+ pkg: DynamicCordisPackage,
+ agentId: SessionId,
+ plugin: DynamicCordisEvaluatedPlugin | ((ctx: unknown) => unknown),
+ ledger: DynamicCordisSlotLedgerRow[],
+ ): DynamicCordisEvaluatedPlugin {
+ const claim = (component: unknown): void => {
+ if (indexable(component)) {
+ this.owners.set(component, { pluginId: pkg.pluginId, pluginRunId: pkg.pluginRunId, agentId })
+ }
+ }
+ const guarded = (ctx: unknown): Context => dynamicCordisContext(ctx as Context, {
+ pkg,
+ ledger,
+ claim,
+ allocatePriority: () => --this.nextPriority,
+ reportFailure: error => this.env.reportGuardFailure(
+ agentId,
+ pkg.pluginId,
+ pkg.pluginRunId,
+ errorDetails(error),
+ ),
+ })
+ if (typeof plugin === 'function') {
+ return { name: moduleIdOf(pkg.pluginId), apply: (ctx: unknown) => plugin(guarded(ctx)) }
+ }
+ return {
+ ...plugin,
+ name: moduleIdOf(pkg.pluginId),
+ apply: (ctx: unknown, config?: unknown) => plugin.apply(guarded(ctx), config),
+ }
+ }
+
+ /**
+ * Unload one package's contributions. Takes the pieces rather than the record
+ * because a load can fail before any record is seated.
+ */
+ private async teardown(
+ id: CordisDynamicPluginId,
+ entryId: string,
+ styles: DynamicCordisStyles,
+ ): Promise {
+ this.live.delete(id)
+ // Nothing of this package renders here any more, so a crash row would outlive
+ // the thing it described.
+ this.failures.delete(id)
+ // Entry removal disposes the fiber (slot entries and facade effects
+ // cascade); the factory invalidation makes a later re-load legal.
+ await this.env.loader.remove(entryId)
+ this.env.modules.invalidate(moduleIdOf(id))
+ styles.dispose()
+ }
+}
+
+/** The success answer for a package that is live here, parked or active. */
+function settled(record: { pkg: DynamicCordisPackage; waitingFor: string[] }): DynamicCordisLoadResult {
+ return {
+ ok: true,
+ pluginRunId: record.pkg.pluginRunId,
+ ...record.waitingFor.length > 0 ? { waitingFor: record.waitingFor } : {},
+ }
+}
+
+/**
+ * Whether a component can key the ownership index. Identity is the key, so only
+ * objects and functions qualify — a package may register anything, and what it
+ * registered is what a crash report carries back.
+ * @param component - whatever a package passed as its component.
+ * @returns true when the value can be indexed by identity.
+ */
+function indexable(component: unknown): component is object {
+ return typeof component === 'object' && component !== null || typeof component === 'function'
+}
+
+/**
+ * Preserve error fields for a load result without fabricating a stack.
+ * @param error - original thrown value.
+ * @returns its message and original string stack, when present.
+ */
+export function errorDetails(error: unknown): CordisErrorDetails {
+ if (typeof error !== 'object' || error === null) return { message: String(error) }
+ const message = 'message' in error && typeof error.message === 'string' ? error.message : String(error)
+ const stack = 'stack' in error && typeof error.stack === 'string' ? error.stack : undefined
+ return { message, ...stack === undefined ? {} : { stack } }
+}
+
+/**
+ * What the authoring session reads about one render crash. The slot says where it
+ * happened, the crash message says what broke, and a withheld global named in that
+ * text pulls in its redirect — a package that reached `window.setInterval` around
+ * the closure trap crashes with the engine's bare message, which teaches nothing.
+ */
+function renderFailureMessage(slot: string, message: string): string {
+ const redirect = Object.entries(DYNAMIC_CLIENT_REDIRECTS)
+ .find(([name, text]) => message.includes(name) && !message.includes(text))?.[1]
+ return `your entry in slot "${slot}" crashed while React rendered it: ${message}`
+ + (redirect === undefined ? '' : `\n${redirect}`)
+}
diff --git a/packages/extensions/cordis-client-runner/src/client/slot-catalog.ts b/packages/extensions/cordis-client-runner/src/client/slot-catalog.ts
new file mode 100644
index 0000000000..f1f205b34c
--- /dev/null
+++ b/packages/extensions/cordis-client-runner/src/client/slot-catalog.ts
@@ -0,0 +1,1571 @@
+/**
+ * Generated by scripts/gen-client-catalog.ts — do not edit by hand; run
+ * `pnpm run gen-client-catalog` to regenerate (freshness-gated by
+ * `pnpm run verify-client-catalog` in doc-sync).
+ *
+ * The compile-time contract of the shipped web bundle's slot surface, as
+ * `cordis_inspect what:"client"` serves it to the model: every SlotMap key a
+ * browser half can register into, what that register call must pass, what the
+ * component receives, who already occupies the seat, and which owner has to be
+ * mounted for the seat to exist. Data only — this module is the one legitimate
+ * meeting point of the two planes, so it carries strings, never client imports.
+ *
+ * @module @deepseek-ai/dsh-cordis-client-runner/client/slot-catalog
+ */
+
+/** One option a register call passes for a given slot cardinality. */
+export interface ClientSlotOption {
+ /** Option name as written in the register options object. */
+ name: string
+ /** Whether the cardinality requires it. */
+ requirement: string
+ /** Accepted type, in source spelling. */
+ type: string
+ /** What it does, from the registrant's side. */
+ doc: string
+}
+
+/** One browser-half slot a dynamic package can contribute UI into. */
+export interface ClientSlotEntry {
+ /** SlotMap key passed as the register call's `name`. */
+ key: string
+ /** Cardinality: `single`, `list`, `keyed`, or `chain`. */
+ kind: string
+ /** Data scope: `root`, `session`, or `session-maybe`. */
+ scope: string
+ /** First sentence of the contract prose. */
+ summary: string
+ /** Full contract prose from the SlotMap declaration. */
+ doc: string
+ /** Options this cardinality accepts (beyond `name`). */
+ registerOptions: readonly ClientSlotOption[]
+ /** Declarations of the props the owner passes down, with their own documentation. */
+ ownerProps: readonly string[]
+ /** Names of the shapes those props reference; deliberately not expanded here. */
+ ownerPropsReferences: readonly string[]
+ /** Framework-supplied component props for this scope. */
+ standardProps: readonly string[]
+ /** For keyed slots: how the key set is constrained and which keys are taken. */
+ keyDomain: string
+ /** Opaque per-render-site context passed to slot-level hooks, when the slot declares one. */
+ hookContext: string
+ /** Slot-level inject face every entry receives, when the slot declares one. */
+ slotInject: string
+ /** Which mounted entry makes this slot exist. */
+ declaredBy: string
+ /** Entries the shipped composition already registered here. */
+ occupants: readonly string[]
+ /** `shadows-shipped-ui` when registering here replaces shipped UI; `none` when additive. */
+ replaceRisk: string
+ /** A minimal browser half that registers into this slot. */
+ example: string
+ /** Source pointer of the contract declaration. */
+ source: string
+}
+
+/** Rules that apply to every browser-half contribution, in reading order. */
+export const CLIENT_NOTES: readonly string[] = [
+ 'Contribute UI only through `ctx.slots.register(options, Component)`; declare `inject: [\'slots\']` in your returned plugin (object form) or the seat is withheld.',
+ 'Wrap every registration in `ctx.slots.inject(key, () => ctx.slots.register(...))`. A slot exists only while the entry that declared it is mounted, and registering into an undeclared slot throws; `inject` runs your registration when the declaration is (or becomes) live and re-runs it if the owner remounts.',
+ 'Do NOT pass `priority`: the browser-half facade assigns one automatically, and it is LOWER than every shipped entry — in a single or keyed cell that means your entry is the one that renders.',
+ 'You cannot `import` anything, so the design-system components are out of reach: build markup with `React.createElement` and ship CSS through `styles.insert(css)`. Use the theme CSS variables (`var(--dsw-alias-bg-layer-1)`, `var(--dsw-alias-label-primary)`, …) instead of literal colors, or your contribution breaks in the other color scheme.',
+ 'Every component receives the framework hook seats listed under `framework props` for its scope; a selector hook is called with a selector, e.g. `useSessions(state => state.current)`.',
+ 'This catalog is the COMPILE-TIME contract of the shipped web bundle, not a snapshot of one page: a key is registrable only where the owner that declares it is mounted. A failed registration surfaces in the browser-half load report — read it back with `cordis_inspect what:"temporary"`.',
+]
+
+/** Every slot the shipped web bundle declares, sorted by key. */
+// Seats of one cardinality repeat their register options and framework props
+// verbatim; that sameness IS the contract a registrant reads, so clone
+// detection is told to skip the data rather than the file.
+/* jscpd:ignore-start */
+export const CLIENT_SLOT_API: readonly ClientSlotEntry[] = [
+ {
+ key: 'conversation',
+ kind: 'single',
+ scope: 'session-maybe',
+ summary: 'The whole center column, across both the no-session hero and a live conversation.',
+ doc: 'The whole center column, across both the no-session hero and a live\nconversation. OCCUPIED by ui-conversation\'s ConversationRoot, which\ndeclares the session body, composer, and input seats inside it —\nregistering here replaces the entire conversation surface (and removes\nevery seat it declares) rather than adding to it.\n\nCurrent-session-optional: the occupant owns both states without\nchanging its React identity, so it keeps its own state across a session\nswitch. It receives no owner props; session facts arrive through the\nframework hooks of the `session-maybe` scope.',
+ registerOptions: [],
+ ownerProps: [
+ '/** Conversation owner share: business state and actions belong to the registrant. */\nexport interface ConvOwnerProps {}',
+ ],
+ ownerPropsReferences: [],
+ standardProps: [
+ 'useSessions: SnapshotSelectorHook',
+ 'useWorkspaces: SnapshotSelectorHook',
+ 'useSession: MaybeSnapshotSelectorHook',
+ 'sessionId: SessionId | undefined',
+ 'useProjection: UseProjection',
+ 'useInput: MaybeSnapshotSelectorHook',
+ 'inputActions: InputActions | undefined',
+ ],
+ keyDomain: '',
+ hookContext: '',
+ slotInject: '',
+ declaredBy: 'an entry in \'root\' (client-ui-layout), so it exists while that entry is mounted',
+ occupants: [
+ 'client-ui-conversation ConversationRoot',
+ ],
+ replaceRisk: 'shadows-shipped-ui',
+ example: 'return {\n inject: [\'slots\'],\n apply(ctx) {\n ctx.slots.inject(\'conversation\', () => ctx.slots.register(\n { name: \'conversation\' },\n () => React.createElement(\'div\', null, \'hello\'),\n ))\n },\n}',
+ source: 'packages/client/ui-layout/src/client/index.ts:62',
+ },
+ {
+ key: 'conversation.chat.commandview',
+ kind: 'keyed',
+ scope: 'session',
+ summary: 'The chat view\'s per-command row hole: keyed dispatch on the command name (`command/run.name`; a run-less cross-window node has none and always lands on the fallback).',
+ doc: 'The chat view\'s per-command row hole: keyed dispatch on the command\nname (`command/run.name`; a run-less cross-window node has none and\nalways lands on the fallback). Declared by the chat view entry; the\nrender site dispatches via `entryKey: name` with GenericCommandCard as\nthe `fallback` — a slash command renders durably with zero\nregistration, and a domain upgrades by registering one row component.',
+ registerOptions: [
+ {
+ name: 'key',
+ requirement: 'required',
+ type: 'string',
+ doc: 'Your cell key: the entry renders where the owner dispatches this exact key. Registering an already-occupied key replaces that occupant.',
+ },
+ ],
+ ownerProps: [
+ '/**\n * Owner share of the per-command row slot: the frozen {@link CommandNode}\n * slice off the snapshot (cache-stable reference — memo premise). The node\n * carries the whole lifecycle (structured name/args, pairing id, and\n * outcome-or-executing). A successful domain command may also carry the\n * explicitly linked projection node needed to fold two log records into one\n * presentation row.\n */\nexport interface CommandRowOwnerProps {\n /** Folded command lifecycle node (run + optional done). */\n node: CommandNode\n /** Explicitly linked compaction checkpoint for the settled `/compact` presentation. */\n compaction?: CompactionSummaryNode\n}',
+ ],
+ ownerPropsReferences: [
+ 'CommandNode',
+ 'CompactionSummaryNode',
+ ],
+ standardProps: [
+ 'useSessions: SnapshotSelectorHook',
+ 'useWorkspaces: SnapshotSelectorHook',
+ 'useSession: SnapshotSelectorHook',
+ 'sessionId: SessionId',
+ 'useProjection: UseProjection',
+ 'useInput: SnapshotSelectorHook',
+ 'inputActions: InputActions',
+ ],
+ keyDomain: 'open: any string the owner dispatches (no compile-time key set), none are taken yet',
+ hookContext: '',
+ slotInject: '',
+ declaredBy: 'an entry in \'conversation.chat.node\' (client-ui-conversation), so it exists while that entry is mounted',
+ occupants: [],
+ replaceRisk: 'none',
+ example: 'return {\n inject: [\'slots\'],\n apply(ctx) {\n ctx.slots.inject(\'conversation.chat.commandview\', () => ctx.slots.register(\n { name: \'conversation.chat.commandview\', key: \'