Architecture and Entry Points

Architecture #

┌─────────────────────────────────────────────┐
│                  Dispatch                   │
│       85 registered tools, 1 registry       │
│             runtime/dispatch.js             │
├──────────────────┬──────────────────────────┤
│   CLI (argv)     │      MCP (JSON-RPC)      │
│   cli.js         │      mcp/index.js        │
│   thin proxy     │      thin proxy          │
├──────────────────┴──────────────────────────┤
│  runtime/tools/*       handlers/*           │
│  constructor/*         catalog/*            │
│  schema/*              validation/*         │
│  loader/*              plugins/*            │
│  sharing/*             server/*    ssr/*    │
└─────────────────────────────────────────────┘

CLI and MCP share the same dispatch layer: every registry tool is available through MCP and through the kebab-case CLI command generated from the tool name. No business logic lives in cli.js or mcp/index.js.

Entry Points #

Host Contracts and Construction Protocol

Portable Relaunch And Host Contract #

Use strict export for configs that must be saved, shared, and relaunched by a different host:

import {
  createHostIntegrationContract,
  exportConfig,
  importConfig,
} from 'symbiote-workspace';

let exported = exportConfig(config, { strict: true });
if (!exported.json) {
  throw new Error(exported.errors.map((error) => error.message).join('; '));
}

let imported = importConfig(exported.json);
let contract = createHostIntegrationContract(imported.config);

Default export mode strips host/local and user identity fields from the exported JSON. Strict mode rejects host-only state before sanitizing, so release and relaunch flows cannot hide local paths, sessions, endpoints, user identity, or host payloads.

createHostIntegrationContract(config) returns host-readable metadata for a portable config:

• construction and config tools: construction_classify, construction_questions_build, construction_question_answer, construction_plan, construction_construct, config_patch_validate, config_patch_apply, config_export, and config_import;
• standalone browser requirements: import-map entries for symbiote-workspace/browser, symbiote-ui/ui, symbiote-engine, and symbiote-engine/contracts, plus mountWorkspace() and symbiote-ui/ui.applyCascadeTheme;
• persistence requirements from requires.hostServices;
• module, runtime-slot, and package requirements from modules[] and requires{}.

The contract is metadata only: it lists service IDs and import specifiers, never credentials, user identity, URLs, local paths, or product code.

MCP #

Start as MCP server:

node cli.js mcp

The MCP transport exposes the same 85 tools as the CLI. Both are thin proxies to dispatch(toolName, args, session).

Tools Reference #

Mutating tools require baseRevision; dispatch rejects mutations that omit it or race the current session revision.

Target Workspace Config #

The target schema version is 1.0.0. The structural surface is a root stack of views[], named layouts{}, panels{}, modules[], requires{}, wires[], state, routes, behavior, and optional server declarations.

{
  "version": "1.0.0",
  "name": "Records",
  "requires": {
    "packages": [{ "id": "symbiote-ui", "version": "^4" }],
    "hostServices": {
      "required": ["storage.project"],
      "optional": []
    }
  },
  "modules": [
    {
      "id": "symbiote-ui:data-table",
      "source": { "kind": "package", "package": "symbiote-ui", "export": "DataTable" },
      "tagName": "sn-data-table",
      "title": "Records",
      "capabilities": ["data.table"],
      "actions": [
        { "id": "refresh", "label": "Refresh", "does": { "kind": "emit", "event": "refresh" } }
      ],
      "hostServices": {
        "required": ["storage.project"],
        "optional": []
      }
    }
  ],
  "panels": {
    "records": {
      "module": "symbiote-ui:data-table",
      "title": "Records",
      "menu": [{ "ref": "action:refresh" }]
    }
  },
  "layouts": {
    "records-main": {
      "kind": "bsp",
      "root": { "type": "panel", "id": "records-leaf", "panel": "records" }
    }
  },
  "views": [
    {
      "id": "records",
      "title": "Records",
      "layout": { "$layout": "records-main" },
      "lifecycle": "durable"
    }
  ],
  "state": {
    "fields": [
      { "id": "records.selection", "type": "object", "persistence": "ephemeral" }
    ]
  },
  "wires": [
    {
      "id": "select-record",
      "from": "panel:records:records-leaf#event:row-select",
      "to": "state:records.selection"
    }
  ],
  "validation": { "reports": [] }
}

Deleted top-level structure keys are rejected by validation. Module source dependencies are declared in requires.packages, requires.plugins, and requires.packs; aggregate host services are declared in requires.hostServices.

Construction Protocol #

The constructor protocol is designed for agents that build workspaces from declared modules instead of editing application code directly.

construction_classify returns the matched template, normalized intent, initial questionnaire, and nextAction. construction_questions_build and construction_question_answer expose the questionnaire step without creating a plan or mutating session state.

construction_plan returns construction diagnostics, questionnaire state, readiness, a normalized plan, verification reports, and a proposed config. It does not mutate session state. construction_construct generates the same plan and stores the executable config in the active session.

import {
  buildConstructionQuestions,
  answerConstructionQuestion,
  planWorkspaceConstruction,
  extractConstructionPlan,
} from 'symbiote-workspace/constructor';

let questions = buildConstructionQuestions({
  brief: 'build an agent review workspace',
  requiredCapabilities: ['data.table', 'admin.bulk-actions'],
});
questions = answerConstructionQuestion(questions, 'theme-mode', 'dark');

let { config } = planWorkspaceConstruction({
  brief: 'build an agent review workspace',
  requiredCapabilities: ['data.table', 'admin.bulk-actions'],
}, {
  moduleCapabilities: [
    {
      tagName: 'sn-data-table',
      provider: 'symbiote-ui',
      capabilities: ['data.table', 'admin.bulk-actions'],
      actions: [
        { id: 'refresh', label: 'Refresh', does: { kind: 'emit', event: 'refresh' } }
      ],
      hostServices: { required: ['storage.project'], optional: [] },
      placement: {
        panel: 'records',
        title: 'Records',
        icon: 'table',
        behavior: { importance: 90, minInlineSize: 320 }
      }
    }
  ],
  answers: {
    'workspace-name': 'Review Desk',
    'target-register': 'agent-workspace'
  }
});

console.log(extractConstructionPlan(config));

The planner records normalized intent, questionnaire answers, module capability coverage, selected modules, package context, execution model, host-service requirements, and verification reports under config.construction. The executable schema surface remains views[], layouts{}, panels{}, modules[], requires{}, and wires[].

Catalog Protocol #

symbiote-workspace/catalog provides module-id catalog entries and three dispatch tools:

• catalog_search filters and ranks entries by text, capability, kind, mode, and fingerprint.
• catalog_describe returns summary, contract, or full-depth data for module ids.
• catalog_proof records a performed gap search before inline free creation.

Catalog entries are addressed by module id in namespace:local-name form. Search, proof, and references do not expose activation tag names. Registry and engine sources participate in search and proof through the same entry shape. Entries marked installed:false route to installation before placement. Development-only entries are visible in scratch mode and excluded from production proof.

Fingerprints are deterministic. A caller can pass knownFingerprint to catalog_search; unchanged fingerprints short-circuit the response. A catalogProof must match the current production fingerprint, and stale proofs fail.

Package And Server Surfaces #

Workspace package tools are the dispatch-facing equivalents of the sharing helpers:

• pack_export, pack_import, pack_validate, and pack_inspect wrap strict portable configs with manifest metadata, host contracts, dependency lists, and readiness diagnostics.
• pack_context_create, pack_contexts_create, and pack_handoff_create project package data into construction-ready handoffs.
• pack_plugin_modules_collect and pack_plugin_templates_collect read plugin manifests without activating them.

symbiote-workspace/server exports createWorkspaceServer(), plugin loading, ingress routing, trigger reconciliation, job runtime helpers, and data-change broadcast helpers. Server mode is optional and Node-only.

Browser Theme Mounting #

symbiote-workspace/browser exports browser-safe schema, loader, constructor, sharing, validation, and plugin APIs plus DOM mounting helpers. Node-only runtime dispatch remains in symbiote-workspace/runtime.

import { mountWorkspace } from 'symbiote-workspace/browser';
import { applyCascadeGeometryRegister, applyCascadeTheme } from 'symbiote-ui/ui';

let mounted = mountWorkspace(config, document.querySelector('#workspace'), {
  themeAdapter: { applyCascadeTheme, applyCascadeGeometryRegister },
  onThemeChange({ config }) {
    saveConfig(config);
  }
});

theme.params and theme.relations are passed to the cascade adapter. A theme.params.register value is applied through applyCascadeGeometryRegister instead of being forwarded as a color parameter. theme.overrides are applied as CSS custom properties on the workspace root, and theme.subtrees apply scoped params, relations, overrides, and geometry registers to matching descendants. If params, relations, or registers are present without the matching theme adapter, mounting throws instead of silently skipping the cascade.

Discrete cascade params such as themeVariant (modern or classic), tabShape (frame, ear, or classic-ear), tabRadius, and cellRadius stay in theme.params and are forwarded through applyCascadeTheme; workspace does not model them as recipes, overrides, or geometry registers. tabRadius is separate from the general radius control so hosts can round project tabs independently from controls, cards, tables, graph chrome, chat surfaces, and layout panels. cellRadius is also independent so animated cell-bg dot sizes can remain stable when the UI chrome uses sharp corners.

cascade-theme-change events from cascade-theme-widget or cascade-theme-editor write normalized params back into config.theme.params. Events with detail.targetSelector update the matching theme.subtrees[] entry so manual theme edits survive export/import as portable config. cascade-geometry-register-change events write detail.register into the same portable params object for the root or matching subtree.

For agent-facing presentation or guidance, the browser entrypoint also exports collectWorkspaceInterfaceContext(config, root, options). A mounted workspace exposes the same data through mounted.getInterfaceContext(). The returned map combines the active runtime view with the full portable config: all views, stack tabs, panels, current visibility, rendered status, declared module actions, declared WebMCP tools, and the view.select / stack.select reveal actions needed to show hidden interface areas before an agent authors a narration or tour timeline.

Hosts can pass targetCollector (or collectComponentTargets) to merge live component targets discovered by symbiote-ui/webmcp.js or an equivalent host collector. DOM references are stripped from the returned context, duplicate target addresses are de-duplicated, and targetEnrichment can attach product/domain metadata as portable data. dataContext adds selected records, document presentation sidecars, retrieved context, mock/demo data, or other presentation-safe state; route params/query/data are read from the mounted router automatically.

Generated presentation artifacts live in narration.timelines[]. A semantic timeline can carry segments[] with narration text, locale, stable WAS focus targets, highlight/annotation cues, safe webmcp / host / workspace actions, data references, timing hints, and required host services. Validation rejects DOM selectors as targets, unsupported action/data sources, and timelines built against an older provenance.revision unless they are explicitly marked freshness: "stale".

Presentation audio selection lives in narration.audio. The live slot can use browser TTS for interactive playback, while render must use an artifact-producing TTS provider and alignment must use a transcription provider. Each slot carries portable ids such as kind, profile, providerId, modelClass, voiceRef, and hostService; the referenced host service must be declared in requires.hostServices. Portable configs never store provider endpoints, credentials, local paths, or voice sample paths.

createWorkspacePresentationTimeline(context, request) turns the collected interface context into a portable timeline draft. request.prompt, request.profile, or request.depth select the prompt profile: brief keeps a compact visible-target tour, full expands target coverage across hidden and visible panels, and data-grounded prioritizes data-bearing targets and attaches dataRefs from route data, selected records, retrieved context, mock/demo data, live data, or document presentation sidecars. Mounted workspaces expose this as mounted.createPresentationTimeline(request, contextOptions), so a host can construct the workspace first, read the live WebMCP/interface context, generate a prompt-specific timeline, and then play or export that same artifact.

playWorkspacePresentationTimeline(timeline, mounted, options) executes that artifact against a mounted workspace. It reads mounted.getInterfaceContext(), runs declared reveal actions before focus/cue/action/narration callbacks, uses the mounted router for view.select, and requires the host to provide executeAction for timeline actions so WebMCP/host/workspace actions stay in the declared safe-action layer. Mounted workspaces expose the same helper as mounted.playPresentationTimeline(...).

Render-time lesson generation uses the presentation-timeline-v2 contract. Every turn has an explicit id and persona and can carry dialogueAct, replyTo, and sourceRefs; grounding.sources[] records compact source identity, content hashes, and sanitized summaries. The structural review rejects unknown or target-mismatched sources, unregistered tools, DOM or metadata tokens in spoken text, and disconnected two-person dialogue. A rejected review produces no TTS items.

createPresentationContextSnapshot() separates stable interface identity from volatile live data. identityHash includes viewport, visible/rendered targets, and declared safe actions, while dataHash tracks source content. Source URLs are stripped of credentials, query strings, and fragments. Horizontal and vertical snapshots therefore have different identities without invalidating an identity solely because live values changed.

prepareWorkspacePresentation(options) owns the browser-side preflight loop. The host rehydrates the requested viewport, waits for layout/fonts/WebMCP to settle, collects a target snapshot, and calls its injected planner. The planner may request at most one deepening round with at most three actions; the host must execute only allowlisted safe actions, settle and recollect, then replan. Hosts may set reviewRepairAttempts: 1 to permit one review-guided planner correction on the same target snapshot. That correction cannot request another deepening round; a missing, non-ready, stale, or still-rejected result fails the preflight. The finalizer rejects stale generations or snapshot hashes and returns one atomic timeline/cache identity. Rendering and TTS must consume that finalized packet rather than constructing a fallback timeline server-side.

Plugins, Portability, and Templates

Plugin System #

Plugins are namespaced manifests that contribute modules, panel/view fragments, hooks, theme profiles, engine packs, narration metadata, and whole-config templates. Current manifests use the contributes.* surface. Flat top-level manifest keys (handlers, components, workspace, and category) are rejected by validatePluginDefinition().

Plugin Format #

// acme-video.plugin.js
export default {
  name: 'acme.video',
  version: '1.0.0',
  description: 'Video review workspace contributions.',

  contributes: {
    modules: [
      {
        id: 'acme.video:preview',
        tagName: 'acme-video-preview',
        title: 'Preview',
        provider: 'acme.video',
        capabilities: ['media.preview'],
        actions: [
          {
            id: 'play',
            label: 'Play',
            does: { kind: 'emit', event: 'play' }
          }
        ],
        hostServices: {
          required: ['storage.project'],
          optional: []
        },
        lifecycle: { readiness: 'auto' }
      }
    ],

    packs: [
      {
        id: 'acme.video:media',
        handlers: [
          {
            type: 'video/webhook',
            trigger: { kind: 'ingress' },
            ui: { autoForm: true },
            credentialType: 'api-key',
            hostServices: { required: ['network.fetch'], optional: [] }
          }
        ]
      }
    ],

    templates: [
      {
        name: 'video-review',
        description: 'Video review desk.',
        config: {
          version: '1.0.0',
          name: 'Video Review'
        }
      }
    ]
  },

  hostServices: {
    required: ['storage.project'],
    optional: []
  },

  idLifecycle: {
    renames: {
      'acme.video:timeline': 'acme.video:preview'
    }
  }
};

Contribution ids are namespaced under the manifest name, for example acme.video:preview. Rename targets in idLifecycle.renames must point to current contribution ids; renamed-away ids must not still exist.

Plugin API #

import {
  MODULE_CAPABILITY_DESCRIPTOR_SCHEMA,
  MODULE_CAPABILITY_SCHEMA_VERSION,
  PLUGIN_SCHEMA,
  validatePluginDefinition,
  validatePluginWorkspaceTemplate,
  validateModuleCapabilityDescriptor,
  validatePortableStringArray,
  registerPlugin,
  activatePlugin,
  unregisterPlugin,
  listPlugins,
  validatePlugin,
} from 'symbiote-workspace/plugins';

let validation = validatePluginDefinition(plugin);
if (!validation.valid) {
  throw new Error(JSON.stringify(validation.errors));
}

let module = plugin.contributes.modules[0];
let descriptorErrors = [];
validateModuleCapabilityDescriptor(module, 'contributes.modules[0]', descriptorErrors, {
  moduleId: module.id
});

validatePortableStringArray(['analysis.sentiment'], 'capabilities', []);
validatePluginWorkspaceTemplate(plugin.contributes.templates[0], 'contributes.templates[0]', []);

registerPlugin(plugin);
await activatePlugin('acme.video', { server, graph });
console.log(listPlugins());
console.log(MODULE_CAPABILITY_SCHEMA_VERSION);
console.log(PLUGIN_SCHEMA.properties.contributes);
console.log(MODULE_CAPABILITY_DESCRIPTOR_SCHEMA.required);

unregisterPlugin('acme.video');

The same module capability schema helpers are exported from symbiote-workspace/schema, the root entrypoint, the browser entrypoint, and symbiote-workspace/plugins.

Portability Rules #

Workspace configs are portable JSON:

• No auth tokens, API keys, or secrets
• No server URLs or endpoints
• No user identity or session data
• Theme params, layout trees, module references, and wires are portable
• Any compliant host assembles from config plus explicit host contracts

Provider references must be portable package or registry identifiers such as symbiote-ui or @acme/workspace-pack; URLs, file references, home-directory paths, and temporary paths are rejected before descriptor data reaches construction or package handoff surfaces.

Templates #

Built-in workspace templates are available through constructor APIs and dispatch:

node cli.js construction-template-list

import { listTemplates, getTemplate } from 'symbiote-workspace/constructor';

listTemplates();

let template = getTemplate('chat');
console.log(template.config);

External templates are plain data. A plugin template is a { name, description?, config } entry under contributes.templates, and the config is validated by the same workspace config validator.

import { planWorkspaceConstruction } from 'symbiote-workspace/constructor';

let { config } = planWorkspaceConstruction({
  brief: 'build a team room',
  template: 'team-ai-room'
}, {
  workspaceTemplates: [
    {
      name: 'team-ai-room',
      description: 'Team command room.',
      config: { version: '1.0.0', name: 'Team AI Room' }
    }
  ]
});

CLI construction commands accept the same input with --workspace-templates <json-array>.

Workspace Package #

The workspace package format wraps a portable workspace config with manifest metadata, a host integration contract, dependency lists, and asset references for distribution and discovery.

import {
  exportWorkspacePackage,
  importWorkspacePackage,
  createWorkspaceConstructionHandoff,
  createWorkspacePackageConstructionContext,
  createWorkspacePackagesConstructionContext,
  inspectWorkspacePackage,
  prepareConstructionIntentWithPackageContext,
  validateWorkspacePackage,
  WORKSPACE_PACKAGE_KIND,
  WORKSPACE_PACKAGE_SCHEMA_VERSION,
} from 'symbiote-workspace';

exportWorkspacePackage(config, manifest) exports the workspace config in strict mode, collects host contract requirements, normalizes the manifest (id, version, tags, permissions, dependencies, assets), and returns a validated package object with JSON output.

importWorkspacePackage(json) parses a workspace package JSON string, validates it against the package schema, and returns both the parsed package and its workspace config.

validateWorkspacePackage(packageObject) validates a workspace package object in isolation, checking package kind, schema version, workspace config validity, manifest portability, and host contract integrity.

inspectWorkspacePackage(input, options) inspects a workspace package object or JSON string without requiring a full host. Pass an optional options.available host-neutral inventory (components, plugins, packages, hostServices, runtimeSlots) to detect missing capabilities.

createWorkspacePackageConstructionContext(input, options) projects a valid workspace package into constructor-ready data without installing or activating anything. It returns external workspaceTemplates, package moduleCapabilities, explicit requiredCapabilities, package requirements, readiness gaps, and source metadata.

createWorkspacePackagesConstructionContext({ packages, available }) aggregates multiple package entries ({ package, templateName } or { json, templateName }) into one constructor-ready context.

prepareConstructionIntentWithPackageContext(intent, context) returns a cloned constructor intent with package-required capabilities merged and sorted into requiredCapabilities.

createWorkspaceConstructionHandoff(context, intent) converts a package construction context into a handoff envelope with _type: "workspace-construction-handoff" plus the { intent, options } shape consumed by planWorkspaceConstruction(handoff.intent, handoff.options).

let context = createWorkspacePackageConstructionContext(packageJson, {
  templateName: 'review-package'
});

let handoff = createWorkspaceConstructionHandoff(context, {
  brief: 'Build a review queue workspace',
  template: 'dashboard'
});

let { config, plan } = planWorkspaceConstruction(handoff.intent, handoff.options);

The dispatch/MCP tools accept the same handoff object directly:

let planned = await dispatch('construction_plan', handoff, session);
let constructed = await dispatch('construction_construct', {
  ...handoff,
  baseRevision: session.revision
}, session);

The CLI accepts the same handoff object as a single positional JSON argument, or constructor options with --options <json-object> when agents pass only the handoff options through shell arguments:

node cli.js construction-plan '{"_type":"workspace-construction-handoff","valid":true,"ready":true,"intent":{"brief":"Build a review queue workspace","template":"dashboard"},"options":{"workspaceTemplates":[],"moduleCapabilities":[]}}'

Package dispatch tools use the pack_* family:

• pack_export
• pack_import
• pack_validate
• pack_inspect
• pack_context_create
• pack_contexts_create
• pack_handoff_create
• pack_plugin_modules_collect
• pack_plugin_templates_collect

Catalog And Inline Creation #

Catalog entries are module-id references with deterministic ranking and fingerprinting. catalog_search and catalog_describe inspect installed, registry, engine, and scratch sources. catalog_proof creates a proof for a performed gap search before inline free creation.

The manifest and package surfaces keep catalog data host-neutral. Registry listings can expose summaries for search, contracts for placement review, and full records for inspection. Placement of an installed:false entry routes to installation first.

Manifest Rejections #

The manifest and package validators reject host, identity, marketplace, and non-portable state:

• host/identity keys: token, secret, session, user, credential, endpoint, password, profile, organization, tenant, billing, subscription
• marketplace keys: price, seller, marketplace, licenseKey, licenseServer, purchase, rating, payout, listing
• non-portable values: local file URIs, home-directory or temporary absolute paths, HTTP/WS URLs in dependency and asset fields