@webskill/console

An embeddable operations console for the browser, built on @webskill/sdk. It provides a two-level IA across 22 pages — Skills library/editor/transfer/integrity, Runs (activity/inspector/sessions), Governance (review queue, audit chain, versions, evaluation, insights), Connections (model providers, MCP, page skills), and Settings (agent runtime, sandbox, generative UI, appearance, diagnostics) — backed by the SDK's fs-driven ConsoleBackend and governance facade.

@webskill/console is an upper-layer product, not part of @webskill/sdk. It consumes the SDK as a peer dependency, so your application carries exactly one SDK instance shared between the console, the chatbot, and your own code.

0.0.x phase — the public API may change between patch releases. Not recommended for production-critical paths until 0.1.0. See the versioning plan in the repository docs (0.0.1 → 0.0.2 → 0.1.0, strict semver from 0.1.0).

Install

npm install @webskill/console @webskill/sdk react react-dom

Optional peers

| Package | Install it to… | Without it | | ---------------------------------------- | --------------------------------------------------------------- | -------------------------------------------- | | @monaco-editor/react + monaco-editor | use the Monaco skill-file editor | the editor falls back to a plain textarea | | @a2ui/lit + @a2ui/web_core | preview the A2UI renderer track in Settings › Generative UI | the track is greyed out with an install hint | | @openuidev/react-lang | preview the OpenUI renderer track | the track is greyed out with an install hint |

Vite integration

The optional peers above are loaded through dynamic import() (Monaco via React.lazy, the renderer tracks via availability probes in Settings › Generative UI) so that a host without them still builds. Vite's dev server pre-bundles dependencies lazily, so the first dynamic import of an un-optimized package triggers a full re-optimization and a page reload. Declare the ones you installed up front:

// vite.config.ts
import { defineConfig } from 'vite';

export default defineConfig({
  optimizeDeps: {
    // Only list packages you actually installed; an entry for a missing package
    // makes the dev server fail to start.
    include: ['@monaco-editor/react', '@a2ui/lit/v0_9', '@openuidev/react-lang']
  }
});

This matters only for the dev server; production builds resolve the same imports statically. If you also embed @webskill/chatbot, use the fuller list in its README — the chat surface imports more of the A2UI graph.

Minimal example

The snippet below is compiled as-is by this repository's consumer typecheck probe (pnpm test:install-smoke), against the published .d.ts.

import { Console, createFsConsoleBackend, createFsTraceSource } from '@webskill/console';
import { OpfsProvider } from '@webskill/sdk/browser';
import '@webskill/console/console.css';

// ConsoleBackend: wire a FileSystemProvider (browser OPFS / custom), skill
// roots, and a trace source. A Node host implements ConsoleBackend over
// @webskill/sdk/node instead.
const fs = new OpfsProvider({ rootName: 'my-app' });
const traces = createFsTraceSource(fs, '/chat');
const backend = createFsConsoleBackend({ fs, roots: ['/skills'], traces });

export function ConsoleApp() {
  return (
    // Layout contract: the host gives the console its height; the console owns
    // the single main scroll region (h-full min-h-0 on the theme wrapper).
    <div className="h-full min-h-0">
      <Console backend={backend} />
    </div>
  );
}

See examples/chatbot-playground for a complete wiring (OPFS storage, skills, trace source, governance facade, chatbot embedding).

Embedding models

• As a component inside an existing web app — mount <Console> with your own backend; use initialPage to deep-link a page.
• As a full-page foundation — let the console own navigation across its two-level IA; pair with @webskill/chatbot for the conversational surface.

Stability

Every public export carries a @stable or @experimental JSDoc tag. The tag is part of the checked-in API snapshot (api-snapshots/console/index.d.ts.snap), so a symbol cannot be quietly downgraded — the change shows up in the diff.

• @stable — covered by the semver contract from 0.1.0: bug fixes ship in a patch, backwards-compatible capabilities in a minor, breaking changes only in a major with release notes. This covers Console, ConsoleProps, the ConsoleBackend family of source interfaces, createFsConsoleBackend, createFsTraceSource, createGovernanceFacade, GovernanceFacade and the governance/runs/sessions data types those ports exchange.
• @experimental — may change in a minor or patch release. Only three kinds of symbol qualify, and each one is here for a stated reason:
  • The Connect surface — ConnectFacade, ConnectEndpointConfig, ConnectEndpointStatus, ConnectEndpointView, ConnectTemporarySkill, ConnectTestResult, ConnectToolView. MCP endpoint management is still settling, and these view types gained fields in this release.
  • RuntimeConfig / RuntimeConfigStore — every new setting adds a required field, which breaks hosts that build the object as a literal. Consume it through mergeRuntimeConfigDefaults rather than hand-assembling it; this pair leaves @experimental once the settings surface converges.
  • Transitional exports — SkillTarExporter (the archive format is not versioned yet).

Anything a README example or the published-.d.ts consumer probe imports is @stable by rule: once we teach a call site, we stop calling it experimental. pnpm lint enforces that rule against this file.

License

MIT