Define an app

defineApp() checks the portable contract and fills safe defaults before build.

import {defineApp, ref, resources} from '@twl-tool/app-sdk';

export default defineApp({
  key: 'research-assistant',
  name: 'Research Assistant',
  version: '1.0.0',
  description: 'Collect sources and turn them into structured reports.',
  catalog: {
    category: 'automation',
    runtime: 'server',
    tags: ['research', 'documents'],
  },
  permissions: [
    'data-workspace.read',
    'documents.write',
    'workflows.execute',
    'ai-chat.use',
  ],
  ui: {
    defaultSurface: 'research',
    surfaces: [
      {
        key: 'research',
        label: 'Research',
        type: 'chat',
        preset: {
          workflow: ref('workflowDefinitions', 'createReport'),
          outputDocumentFolder: ref('documentFolders', 'reports'),
          allowedTools: ['workflow.launch'],
          expectedOutput: 'document',
        },
      },
    ],
  },
  resources: {
    documentFolders: {
      reports: {name: 'Research Reports'},
    },
    workflowDefinitions: {
      createReport: resources.workflow({
        title: 'Create Research Report',
        desiredState: 'active',
        definition: {
          version: 1,
          default_runner: 'builtin',
          steps: [],
        },
      }),
    },
  },
});

Identity rules

• key must be a lowercase slug such as research-assistant.
• name and version must be non-empty.
• format is added automatically as twl-tool.app.v1.
• app versions should change whenever the installable contract changes.

Catalog metadata

Catalog categories are chrome-tools, browser-agents, automation, data, forms, and other. Runtime may be chrome-extension, browser-agent, or server.