@nuxtagentic/workspace 0.0.0-stage → 0.1.0

package/LICENSE.md

@@ -0,0 +1,9 @@
+Proprietary software. All rights reserved.
+
+Use of Nuxt Agentic packages and starter materials is governed by the applicable
+commercial agreement supplied with a purchase. This repository does not grant
+an open-source license or permission to redistribute the packages as a competing
+template or module library.
+
+Third-party dependencies retain their respective licenses. This notice does not
+replace or modify those licenses.

package/README.md

@@ -1,3 +1,63 @@
-# Temporary Holding Version
+# Workspace contracts
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+`@nuxtagentic/workspace` connects feature packages to the host application.
+It supplies contribution types, context and action registration, feature discovery,
+and account-scoped installation state. Its Nuxt dependencies install Identity,
+Data, and Prompt. It does not install dashboard layouts, pages, components, or styles.
+
+The starter owns its shell in `app/`: dashboard pages and layout,
+prompt and search controllers, navigation, operation review, settings composition,
+UI defaults, and color tokens. Shell regression tests live in
+`tests/workspace/`. Features keep their own UI, server
+code, schemas, and contributions in their packages.
+
+## Connect a feature to the host
+
+Available features implement [the contribution contracts](runtime/types.ts).
+They provide collection components, prompt parsers, search providers, resource
+navigation, actions, settings panels, and layout contributions as needed. Kit
+builds `#workspace/features` and `#workspace/modules` from those registrations.
+The host consumes the generated contributions without importing business features.
+
+The host layout provides `WorkspaceContext` through `provideWorkspaceContext`
+and an action registry through `provideAgentActionHandlers`. Feature pages read
+`useWorkspaceContext` and call `useWorkspaceRoute` to ask the host for navigation
+based on that page's own Nuxt route. Feature components register active commands
+with `useAgentActionHandler`. These APIs keep feature packages independent of
+application files.
+
+See the starter's `app/layouts/dashboard.vue`, `app/composables/useDashboardWorkspace.ts`,
+and `app/composables/useDashboardRoute.ts` for the host implementation. Include the
+starter's editable `app/` shell when installing these packages in another application,
+or supply your own layout and controllers.
+
+Input, selection, project, and view state stay in the URL. Changes to the prompt,
+route, or account scope invalidate stale planning results. Mutations finish on
+the server; late results refresh the current scope without replacing a newer
+prompt or restoring a stale completion message.
+
+## Installation state
+
+`workspaceModels` stores module installation choices; business models stay with
+their features. Compose it into the host's CloudConfig schema. This starter disables
+module management and keeps every registered agentic feature available.
+
+Hosts that enable `workspace: { moduleManagement: true }` use `useWorkspaceModules`
+to manage installation state. Defaults come from the generated catalog, and removal
+retains records. Hosts own the catalog page and route guards; the starter's
+`isModuleManagementEnabled` flag in `nuxt.config.ts` controls both the module option
+and whether `/dashboard/modules` is registered.
+
+Core features omit their catalog entry and remain available regardless of saved
+installation choices. Agents, Integrations, and Automations use this registration.
+Prompt tools and Google connections use the same installation state on the server.
+The host keys its layout by workspace and installation revision to recreate
+controllers after those values change.
+
+## Presentation
+
+Dashboard colors live in the host's `app/assets/css/main.css`
+and component defaults in `app/app.config.ts`. Use Nuxt
+UI's semantic `success` and `error` tokens for status indicators and switches.
+Avatars use `bg-avatar` with `--avatar-hue`; shared lightness and chroma keep them
+softer than status indicators.

package/module.ts

@@ -0,0 +1,24 @@
+import { createResolver, defineNuxtModule } from '@nuxt/kit'
+import { registerWorkspaceModule } from '@nuxtagentic/kit'
+
+export default defineNuxtModule<{ moduleManagement: boolean }>({
+  meta: { name: '@nuxtagentic/workspace', configKey: 'workspace' },
+  defaults: { moduleManagement: false },
+  moduleDependencies: {
+    '@nuxtagentic/identity': {},
+    '@nuxtagentic/data': {},
+    '@nuxtagentic/prompt': {},
+  },
+  setup(options, nuxt) {
+    const resolver = createResolver(import.meta.url)
+    registerWorkspaceModule(
+      {
+        id: 'workspace',
+        runtime: resolver.resolve('./runtime'),
+        metadata: resolver.resolve('./runtime/shared/agent.ts'),
+      },
+      nuxt,
+    )
+    nuxt.options.runtimeConfig.public.workspaceModules = { managed: options.moduleManagement }
+  },
+})

package/package.json

@@ -1,6 +1,49 @@
 {
   "name": "@nuxtagentic/workspace",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0",
+  "type": "module",
+  "files": [
+    "module.ts",
+    "runtime",
+    "schema.ts",
+    "README.md",
+    "LICENSE.md"
+  ],
+  "exports": {
+    ".": "./module.ts",
+    "./package.json": "./package.json",
+    "./schema": "./schema.ts",
+    "./runtime/*.vue": "./runtime/*.vue",
+    "./runtime/*.css": "./runtime/*.css",
+    "./runtime/*.json": "./runtime/*.json",
+    "./runtime/*.svg": "./runtime/*.svg",
+    "./runtime/*": "./runtime/*.ts"
+  },
+  "dependencies": {
+    "@cloudconfig/core": "0.2.0-beta.2",
+    "@nuxt/kit": "4.6.1",
+    "@nuxt/ui": "^4.11.1",
+    "vue-router": "^5.4.0",
+    "h3": "1.15.11",
+    "@nuxtagentic/prompt": "0.1.0",
+    "@nuxtagentic/data": "0.1.0",
+    "@nuxtagentic/kit": "0.1.0",
+    "@nuxtagentic/identity": "0.1.0"
+  },
+  "peerDependencies": {
+    "nuxt": "^4.6.1",
+    "vue": "^3.5.43"
+  },
+  "cloudconfig": {
+    "models": "workspaceModels"
+  },
+  "license": "SEE LICENSE IN LICENSE.md",
+  "description": "Feature contracts and host registration for Nuxt Agentic.",
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "engines": {
+    "node": "^22.22.3 || ^24.15.0 || >=26.0.0"
+  }
 }

package/runtime/composables/useAgentActions.ts

@@ -0,0 +1,39 @@
+import {
+  shallowReactive,
+  provide,
+  inject,
+  watchEffect,
+  toValue,
+  type InjectionKey,
+  type MaybeRefOrGetter,
+} from 'vue'
+
+export type AgentActionHandler = () => unknown | Promise<unknown>
+const handlersKey: InjectionKey<Map<string, AgentActionHandler>> = Symbol('agent-action-handlers')
+
+/** Provide the action registry that feature components populate while active. */
+export function provideAgentActionHandlers() {
+  const handlers = shallowReactive(new Map<string, AgentActionHandler>())
+  provide(handlersKey, handlers)
+  return handlers
+}
+
+/** Register a feature action and remove it when the feature becomes inactive or unmounts. */
+export function useAgentActionHandler(
+  command: string,
+  handler: AgentActionHandler,
+  active: MaybeRefOrGetter<boolean>,
+) {
+  const handlers = inject(handlersKey, undefined)
+  watchEffect((onCleanup) => {
+    if (!handlers || !toValue(active)) {
+      return
+    }
+    handlers.set(command, handler)
+    onCleanup(() => {
+      if (handlers.get(command) === handler) {
+        handlers.delete(command)
+      }
+    })
+  })
+}

package/runtime/composables/useInstalledFeatures.ts

@@ -0,0 +1,24 @@
+import { WORKSPACE_CONTRIBUTIONS, WORKSPACE_FEATURES } from '#workspace/features'
+import { useWorkspaceModules } from './useWorkspaceModules'
+import type { RouteLocationNormalizedLoaded } from 'vue-router'
+
+export function findWorkspaceRouteContribution(route: RouteLocationNormalizedLoaded) {
+  return (
+    WORKSPACE_CONTRIBUTIONS.find((entry) => entry.matchesRoute?.(route)) ??
+    (route.path === '/dashboard'
+      ? WORKSPACE_FEATURES.find(
+          (entry) => entry.id === route.query.module || !!route.query[entry.selectionKey],
+        )
+      : undefined)
+  )
+}
+
+export function useInstalledContributions() {
+  const modules = useWorkspaceModules()
+  return WORKSPACE_CONTRIBUTIONS.filter((entry) => modules.isInstalled(entry.moduleId ?? entry.id))
+}
+
+export function useInstalledFeatures() {
+  const modules = useWorkspaceModules()
+  return WORKSPACE_FEATURES.filter((entry) => modules.isInstalled(entry.moduleId ?? entry.id))
+}

package/runtime/composables/useWorkspaceContext.ts

@@ -0,0 +1,18 @@
+import { inject, provide, type InjectionKey } from 'vue'
+import type { WorkspaceContext } from '../types'
+
+const workspaceContextKey: InjectionKey<WorkspaceContext> = Symbol('workspace-context')
+
+/** Connect the host shell to the feature pages rendered within it. */
+export function provideWorkspaceContext(context: WorkspaceContext) {
+  provide(workspaceContextKey, context)
+}
+
+/** Read the host context; the enclosing application layout must provide it. */
+export function useWorkspaceContext() {
+  const context = inject(workspaceContextKey)
+  if (!context) {
+    throw new Error('Feature pages require a layout that provides the workspace context.')
+  }
+  return context
+}

package/runtime/composables/useWorkspaceModules.ts

@@ -0,0 +1,126 @@
+import { computed, ref } from 'vue'
+import { useAsyncData, useCloudConfig, useRuntimeConfig, useState } from '#imports'
+import { useWorkspaceScope } from '@nuxtagentic/identity/runtime/composables/useWorkspaceScope'
+import { MODULE_CATALOG } from '#workspace/modules'
+import { isWorkspaceModuleInstalled } from '../shared/modules'
+import type { WorkspaceConfig } from '../../schema'
+
+export function useWorkspaceModules() {
+  const scope = useWorkspaceScope()
+  const managed =
+    (useRuntimeConfig().public.workspaceModules as { managed?: boolean }).managed === true
+  const defaults = MODULE_CATALOG.filter((entry) => entry.defaultInstalled).map((entry) => entry.id)
+  const revision = useState('workspace-modules-revision', () => 0)
+  const api = useCloudConfig<WorkspaceConfig>()
+  const request = useAsyncData(
+    computed(() => `workspace:modules:${scope.value}`),
+    async () => {
+      if (!managed || !scope.value) {
+        return null
+      }
+      const workspace = scope.value.slice(scope.value.indexOf(':') + 1)
+      const result = await api.workspaceInstallation.list({
+        pageSize: 1,
+        filters: {
+          type: 'group',
+          logic: 'and',
+          children: [{ type: 'condition', field: 'workspace', operator: 'eq', value: workspace }],
+        },
+      })
+      return result.data[0] ?? null
+    },
+    { deep: false },
+  )
+  const installed = computed<string[]>(() =>
+    !managed
+      ? MODULE_CATALOG.map((entry) => entry.id)
+      : (Array.isArray(request.data.value?.installed)
+          ? request.data.value.installed
+          : defaults
+        ).filter((id: string) => MODULE_CATALOG.some((entry) => entry.id === id)),
+  )
+  const busy = ref<string | null>(null)
+  const mutationError = ref('')
+
+  function isInstalled(id: string) {
+    return isWorkspaceModuleInstalled(id, installed.value)
+  }
+  function requiredBy(id: string) {
+    return MODULE_CATALOG.filter(
+      (entry) => installed.value.includes(entry.id) && entry.dependencies?.includes(id),
+    )
+  }
+  async function setInstalled(id: string, enabled: boolean) {
+    if (busy.value || !managed) {
+      return false
+    }
+    const module = MODULE_CATALOG.find((entry) => entry.id === id)
+    if (!module) {
+      return false
+    }
+    if (!enabled && requiredBy(id).length) {
+      mutationError.value = `Remove ${requiredBy(id)
+        .map((entry) => entry.label)
+        .join(' and ')} first.`
+      return false
+    }
+    busy.value = id
+    mutationError.value = ''
+    const currentScope = scope.value
+    const next = new Set(installed.value)
+    function include(key: string) {
+      next.add(key)
+      for (const dependency of MODULE_CATALOG.find((entry) => entry.id === key)?.dependencies ??
+        []) {
+        include(dependency)
+      }
+    }
+    if (enabled) {
+      include(id)
+    } else {
+      next.delete(id)
+    }
+    try {
+      if (request.error.value) {
+        throw request.error.value
+      }
+      const fields = { installed: [...next] }
+      if (request.data.value) {
+        await api.workspaceInstallation.update(request.data.value.id, fields)
+      } else {
+        await api.workspaceInstallation.create({
+          ...fields,
+          workspace: currentScope.slice(currentScope.indexOf(':') + 1),
+        })
+      }
+      if (scope.value !== currentScope) {
+        return false
+      }
+      await request.refresh()
+      if (request.error.value) {
+        throw request.error.value
+      }
+      revision.value++
+      return true
+    } catch (error) {
+      mutationError.value =
+        error instanceof Error ? error.message : 'Could not save this module. Try again.'
+      return false
+    } finally {
+      busy.value = null
+    }
+  }
+  return {
+    catalog: MODULE_CATALOG,
+    installed,
+    managed,
+    busy,
+    error: request.error,
+    mutationError,
+    ready: request,
+    refresh: request.refresh,
+    isInstalled,
+    requiredBy,
+    setInstalled,
+  }
+}

package/runtime/composables/useWorkspaceRoute.ts

@@ -0,0 +1,7 @@
+import { useRoute } from '#imports'
+import { useWorkspaceContext } from './useWorkspaceContext'
+
+/** Ask the host to create navigation using this feature page's own Nuxt route. */
+export function useWorkspaceRoute() {
+  return useWorkspaceContext().createNavigation(useRoute())
+}

package/runtime/server/middleware/modules.ts

@@ -0,0 +1,41 @@
+import { defineEventHandler, getRequestURL } from 'h3'
+import { useRuntimeConfig } from '#imports'
+import { useCloudConfigServer } from '#cloudconfig/server'
+import { MODULE_CATALOG } from '#workspace/modules'
+import type { WorkspaceConfig } from '../../../schema'
+import { useAgentSession } from '@nuxtagentic/prompt/runtime/server/utils/agent-session'
+
+export default defineEventHandler(async (event) => {
+  const path = getRequestURL(event).pathname
+  if (!/^\/api\/agent(?:\/|$)/.test(path)) {
+    return
+  }
+  const runtime = useRuntimeConfig(event)
+  if (!(runtime.public.workspaceModules as { managed?: boolean }).managed) {
+    return
+  }
+  const session = await useAgentSession(event)
+  if (!session?.user) {
+    return
+  }
+  const api = await useCloudConfigServer<WorkspaceConfig>(event)
+  const result = await api.workspaceInstallation.list({
+    pageSize: 1,
+    filters: {
+      type: 'group',
+      logic: 'and',
+      children: [
+        {
+          type: 'condition',
+          field: 'workspace',
+          operator: 'eq',
+          value: String(session.session.activeOrganizationId ?? 'personal'),
+        },
+      ],
+    },
+  })
+  const installed = result.data[0]?.installed
+  event.context.workspaceModules = Array.isArray(installed)
+    ? installed.filter((id) => MODULE_CATALOG.some((entry) => entry.id === id))
+    : MODULE_CATALOG.filter((entry) => entry.defaultInstalled).map((entry) => entry.id)
+})

package/runtime/shared/agent-actions.ts

@@ -0,0 +1,40 @@
+import type { LocationQueryRaw } from 'vue-router'
+
+export interface AgentActionContext {
+  /** Current page/resource, URL values, and selected record are available to handlers. */
+  page: string
+  resource: string | null
+  selection: string | null
+  read: (key: string) => string
+  navigate: (path: string, query?: LocationQueryRaw) => Promise<unknown>
+  prompt: (input: string) => Promise<void>
+  /** Invoke a handler registered by the active editor or resource component. */
+  run: (command: string) => Promise<unknown>
+  canRun: (command: string) => boolean
+}
+
+export interface AgentAction {
+  id: string
+  name: string
+  description: string
+  icon: string
+  /** Alternative phrases accepted on submit and included in typing suggestions. */
+  aliases?: readonly string[]
+  available?: (context: AgentActionContext) => boolean
+  run: (context: AgentActionContext) => unknown | Promise<unknown>
+}
+
+export interface AgentActionSuggestion {
+  id: string
+  name: string
+  description: string
+  icon: string
+}
+
+export function normalizeActionName(input: string) {
+  return input
+    .trim()
+    .toLowerCase()
+    .replace(/\s+/g, ' ')
+    .replace(/[.!?]+$/, '')
+}

package/runtime/shared/agent.ts

@@ -0,0 +1 @@
+export default { excludedModels: ['workspaceInstallation'] }

package/runtime/shared/dashboard-search.ts

@@ -0,0 +1,50 @@
+/** Feature IDs come from the app registry; shared search records are extensible. */
+export type SearchModule = string
+export interface SearchLink {
+  path: string
+  query: Record<string, string>
+}
+export interface SearchResultItem {
+  id: number | string
+  label: string
+  description: string
+  icon: string
+  to: SearchLink
+}
+export interface SearchResultGroup {
+  id: SearchModule
+  label: string
+  icon: string
+  count: number
+  items: SearchResultItem[]
+  to: SearchLink
+  loading?: boolean
+  error?: string
+}
+
+const INTENT_WORDS = new Set(
+  (
+    'show find search list count filter sort order select users user people team accounts files file ' +
+    'please can could would me my all only for from by in on to and or not ' +
+    'calendar agenda schedule meeting event create add book today tomorrow week month emails email mail inbox boards board kanban tasks task ' +
+    'active banned verified unverified disabled joined before after newest oldest latest ' +
+    'role roles admin user who whose where with'
+  ).split(' '),
+)
+
+/** Short keyword searches need no AI call; structured queries keep their existing routes. */
+export function getDashboardSearchText(input: string): string {
+  const text = input.trim()
+  const quoted = /^(?:"([^"]+)"|'([^']+)')$/.exec(text)
+  if (quoted) {
+    return (quoted[1] ?? quoted[2]!).trim()
+  }
+  if (!text || /[:<>=?;\n]/.test(text)) {
+    return ''
+  }
+  const words = text.toLowerCase().split(/\s+/)
+  if (words.length > 4 || words.some((word) => INTENT_WORDS.has(word))) {
+    return ''
+  }
+  return text
+}

package/runtime/shared/modules.ts

@@ -0,0 +1,6 @@
+import { MODULE_CATALOG } from '#workspace/modules'
+
+export function isWorkspaceModuleInstalled(id: string, installed?: readonly string[]) {
+  const module = MODULE_CATALOG.find((entry) => entry.id === id)
+  return !module || (installed ? installed.includes(id) : !!module.defaultInstalled)
+}

package/runtime/types.ts

@@ -0,0 +1,171 @@
+import type { Component, Ref } from 'vue'
+import type { DropdownMenuItem, NavigationMenuItem } from '@nuxt/ui'
+import type {
+  LocationQueryRaw,
+  NavigationFailure,
+  RouteLocationNormalizedLoaded,
+  RouteLocationRaw,
+} from 'vue-router'
+import type { AgentToolCall, AgentToolName } from '@nuxtagentic/prompt/runtime/shared/agent-tools'
+import type { AgentAction } from './shared/agent-actions'
+import type { SearchLink, SearchResultGroup } from './shared/dashboard-search'
+
+export type WorkspaceNavigationResult =
+  Promise<void | NavigationFailure | false> | false | void | RouteLocationRaw
+
+export interface WorkspaceNavigation {
+  route: RouteLocationNormalizedLoaded
+  read: (key: string) => string
+  prompt: Ref<string>
+  module: Ref<WorkspaceFeature | null>
+  selection: Ref<WorkspaceFeature | null>
+  hasSelection: Ref<boolean>
+  navigate: (patch: LocationQueryRaw, replace?: boolean) => WorkspaceNavigationResult
+  back: (query: LocationQueryRaw, overview?: boolean) => WorkspaceNavigationResult
+  closeDetail: () => WorkspaceNavigationResult
+  goBack: () => WorkspaceNavigationResult
+  resolveFeature: (intent: WorkspacePromptIntent | null) => WorkspaceFeature | null
+}
+
+export interface WorkspaceEntryContext {
+  input: Ref<string>
+  intent: Ref<WorkspacePromptIntent | null>
+  keyword: Ref<string>
+  navigation: WorkspaceNavigation
+}
+
+/** Host state that feature pages consume without importing the application's shell. */
+export interface WorkspaceContext {
+  entryContext: WorkspaceEntryContext
+  activeFeature: Ref<WorkspaceFeature | null>
+  createNavigation: (route: RouteLocationNormalizedLoaded) => WorkspaceNavigation
+}
+
+export interface WorkspaceSearchContext {
+  text: Ref<string>
+  link: (extra?: Record<string, string>) => SearchLink
+}
+
+export interface WorkspaceSearchProvider {
+  featureId: string
+  group: Ref<Omit<SearchResultGroup, 'id' | 'label' | 'icon'>>
+  meta: Ref<string>
+  refresh?: () => void | Promise<void>
+}
+
+export interface WorkspacePromptIntent {
+  featureId: string
+  action: 'query' | 'create'
+  source: 'sql' | 'explicit' | 'jev'
+  call?: AgentToolCall
+}
+
+export interface WorkspacePromptMatch<
+  Intent extends WorkspacePromptIntent = WorkspacePromptIntent,
+> {
+  intent: Intent | null
+  local: boolean
+  /** An explicit model prefix survives local parsing failure and can skip routing. */
+  resource?: string
+  error?: string
+}
+
+export interface WorkspacePromptParser<
+  Intent extends WorkspacePromptIntent = WorkspacePromptIntent,
+> {
+  parse: (input: string) => WorkspacePromptMatch<Intent> | null
+  tools?: Partial<Record<AgentToolName, (input: string, call: AgentToolCall) => Intent | null>>
+  reset?: () => void
+}
+
+export interface WorkspaceWorkProvider {
+  section: Ref<string | null>
+  location: (project: number | null) => RouteLocationRaw
+  navigation?: Ref<RouteLocationRaw>
+  navigationItems?: Ref<readonly NavigationMenuItem[]>
+}
+
+export interface WorkspacePromptPresentation {
+  hidden?: boolean
+  class?: string | string[]
+  key?: string
+  placeholder?: string
+}
+
+export interface WorkspaceLayout {
+  navbar?: boolean
+  expand?: boolean | 'wide'
+  edgeToEdge?: boolean
+  flat?: boolean
+  ownsDetailAside?: boolean
+  workspaceClass?: string
+  navbarClass?: string
+  navbarRightClass?: string
+  hideTitle?: boolean
+  hideExpand?: boolean
+  hideSeparator?: boolean
+  immersive?: boolean
+}
+
+export interface WorkspaceContribution {
+  id: string
+  moduleId?: string
+  label: string
+  icon: string
+  resource?: string
+  preservePrompt?: boolean
+  preparePrompt?: (input: string) => string
+  selectionKey?: string
+  selectionParam?: string
+  matchesRoute?: (route: RouteLocationNormalizedLoaded) => boolean
+  recordLocation?: (id: number, query: LocationQueryRaw) => RouteLocationRaw
+  collectionLocation?: (query: LocationQueryRaw) => RouteLocationRaw
+  handoff?: (action: string, route: RouteLocationNormalizedLoaded) => RouteLocationRaw | undefined
+  useRefresh?: () => () => Promise<unknown>
+  actions?: Record<string, readonly AgentAction[]>
+  useActionPage?: () => Ref<string>
+  additionalActionScopes?: readonly string[]
+  navigation?: {
+    order: number
+    label?: string
+    icon?: string
+    group?: 'workspace' | 'create' | 'footer'
+  }
+  navigationShortcuts?: readonly NavigationMenuItem[]
+  projectHome?: boolean
+  useWork?: () => WorkspaceWorkProvider
+  settingsPanels?: readonly Component[]
+  generalPanels?: readonly Component[]
+  appearancePanels?: readonly Component[]
+  useAppearanceMenu?: () => Ref<DropdownMenuItem[]>
+  promptDropComponent?: Component
+  promptLeadingComponent?: Component
+  usePromptPresentation?: () => Ref<WorkspacePromptPresentation>
+  layout?: WorkspaceLayout
+  useLayout?: () => Ref<WorkspaceLayout>
+  headerComponent?: Component
+  sidebarComponent?: Component
+  workspaceSwitcherComponent?: Component
+}
+
+/** Collection features connect the prompt shell to records and workflows. */
+export interface WorkspaceFeature extends WorkspaceContribution {
+  prompt: {
+    query: string
+    useMeta: () => Ref<string>
+  }
+  urlKeys: readonly string[]
+  selectionKey: string
+  component: Component
+  entryProps?: (
+    expanded: boolean,
+    prompt: (input: string) => Promise<void>,
+  ) => Record<string, unknown>
+  statusComponent?: Component
+  detailAside?: boolean
+  draftKeys?: readonly string[]
+  backKeys?: readonly string[]
+  reviewIntent?: (intent: WorkspacePromptIntent) => LocationQueryRaw
+  createPromptParser?: (referenceDay: Date) => WorkspacePromptParser
+  useSearch?: (context: WorkspaceSearchContext) => WorkspaceSearchProvider
+}

package/schema.ts

@@ -0,0 +1,43 @@
+import { model, t } from '@cloudconfig/core'
+
+export const workspaceModels = {
+  workspaceInstallation: model(
+    {
+      key: t.text().required().unique().serverOnly(),
+      ownerId: t.number().required().serverOnly(),
+      workspace: t.text().required(),
+      installed: t.json().required(),
+    },
+    {
+      access: {
+        list: ({ user, where }) => (user ? where('ownerId', 'eq', user.id) : false),
+        read: ({ user, where }) => (user ? where('ownerId', 'eq', user.id) : false),
+        create: ({ user }) => !!user,
+        update: ({ user, where }) => (user ? where('ownerId', 'eq', user.id) : false),
+      },
+      hooks: {
+        beforeCreate: ({ user }, input) => ({
+          ...input,
+          ownerId: user!.id,
+          key: `${user!.id}:${input.workspace}`,
+        }),
+      },
+      validate: (input, existing) => {
+        if (existing && (input.workspace !== existing.workspace || input.key !== existing.key)) {
+          return [
+            { path: 'workspace', message: 'Module settings cannot be moved to another workspace.' },
+          ]
+        }
+        return typeof input.workspace !== 'string' ||
+          !input.workspace ||
+          !Array.isArray(input.installed) ||
+          input.installed.length > 50 ||
+          input.installed.some((id) => typeof id !== 'string' || !/^[a-z][a-z0-9-]*$/.test(id))
+          ? [{ path: 'installed', message: 'Choose valid modules for this workspace.' }]
+          : []
+      },
+    },
+  ),
+}
+
+export type WorkspaceConfig = { models: typeof workspaceModels }