@kelpie/server 0.5.2 → 0.6.0

package/src/lib/kelpieConfigFile.ts

@@ -0,0 +1,283 @@
+import type { KelpieModule } from '../runtime/module.ts'
+import { ConfigurationError, type Environment, type KelpieConfig, type LogLevel, type RuntimeMode } from './config.ts'
+import type { EmailConfig } from './email.ts'
+import { type ConfigValue, resolveMarkers } from './fromEnv.ts'
+import type { LoggingDestination } from './logger.ts'
+import type { RateLimitConfig } from './rateLimit.ts'
+import type { SecretEncryptionConfig } from './secrets.ts'
+
+/**
+ * The shape a `kelpie.config.ts` file declares.
+ *
+ * Every leaf is either a literal value the assembly commits to git, or a
+ * `fromEnv(...)` marker the deployment fills in. The resolver walks this
+ * object, replaces markers with parsed values, and returns a fully-populated
+ * `KelpieConfig`.
+ *
+ * The file is the map. `fromEnv(...)` marks the leaves a deployment overrides.
+ * Nothing in the app reads `process.env` for these fields after boot.
+ */
+
+export interface KelpieConfigInput {
+  readonly runtimeMode: ConfigValue<RuntimeMode>
+  readonly port: ConfigValue<number>
+  readonly databaseUrl: ConfigValue<string>
+  readonly logging: LoggingInput
+  /** Optional; unset in development, set to the built web bundle in a deployment. */
+  readonly webBundleDirectory?: ConfigValue<string | undefined>
+  /** Optional; unset in development, set to the deploy-time module override file. */
+  readonly moduleConfigPath?: ConfigValue<string | undefined>
+  /** Optional; defaults to 0 (no proxy in front). */
+  readonly trustedProxyHopCount?: ConfigValue<number>
+  /**
+   * The deployment's base URL. Every emailed link (password reset, email
+   * verification, invite) is built from it. Required by the workspace and auth
+   * modules. Optional here so an older assembly can omit it and let those
+   * modules fall back to the `context.config(appUrlConfigSchema)` path.
+   */
+  readonly appBaseUrl?: ConfigValue<string>
+  /**
+   * Keys that seal stored secrets (webhook signing secrets, agent-task auth
+   * headers). Required by the webhooks and agent-tasks modules. Optional here
+   * for the same reason `appBaseUrl` is.
+   */
+  readonly secretEncryption?: SecretEncryptionInput
+  readonly email: EmailInput
+  /** Optional; each unset field falls back to the same defaults `loadConfig` used. */
+  readonly rateLimit?: RateLimitInput
+  /**
+   * Env-keyed values the assembly can lock in code, or defer to the
+   * environment. Modules read this through `context.config(schema)`; each
+   * module's own Zod schema still names the keys and validates them.
+   *
+   * A key present here overrides the same key in `process.env`. A key absent
+   * here falls through to `process.env` unchanged, so the section is a
+   * progressive migration: lock what you want to lock, leave the rest.
+   *
+   * Literal: `SECRET_ENCRYPTION_KEY: 'a-committed-key'` (don't do this for
+   * secrets — the point is you can, if the value is not a secret).
+   * Marker: `SECRET_ENCRYPTION_KEY: fromEnv('SECRET_ENCRYPTION_KEY', z.string())`
+   * defers to the environment, same as today.
+   */
+  readonly env?: Readonly<Record<string, ConfigValue<string | undefined>>>
+  /** The module list the assembly composes. Same shape it had before. */
+  readonly modules: readonly KelpieModule[]
+}
+
+/**
+ * The `logging` sub-tree of the assembly config.
+ *
+ * `level` is the minimum severity to emit. `destinations` is the ordered list
+ * of destinations each line writes to; stdout is the default entry in the
+ * template assembly, and a self-hoster adds another by extending
+ * `LoggingDestination` in `@kelpie/server` and putting a matching entry here.
+ */
+export interface LoggingInput {
+  readonly level: ConfigValue<LogLevel>
+  readonly destinations: readonly LoggingDestination[]
+}
+
+/**
+ * The `email` sub-tree of the assembly config.
+ *
+ * `provider` names one entry in the runtime's provider registry. `'log'` is a
+ * built-in the runtime always registers; `'smtp'` is registered by the
+ * built-in `smtp-email` core module; third-party provider modules register
+ * their own names (an API-based provider might register `'resend'` or
+ * `'postmark'`, and so on). Free-string so a self-hoster can install a
+ * module core has never heard of.
+ *
+ * `from` is the address on every outgoing message. Provider-specific config
+ * (SMTP host and credentials, an API key) belongs to the provider module,
+ * which reads it through `context.config(...)`; putting it here would tie the
+ * assembly config to a single transport.
+ */
+export interface EmailInput {
+  readonly provider: ConfigValue<string>
+  readonly from: ConfigValue<string>
+}
+
+export interface SecretEncryptionInput {
+  readonly key: ConfigValue<string>
+  /** Absent (or blank) is normal; only set while rotating away from an older key. */
+  readonly previousKey?: ConfigValue<string | undefined>
+}
+
+export interface RateLimitBudgetInput {
+  readonly limit?: ConfigValue<number>
+  readonly windowSeconds?: ConfigValue<number>
+}
+
+export interface RateLimitInput {
+  readonly forms?: RateLimitBudgetInput
+  readonly auth?: RateLimitBudgetInput
+  readonly loginAccount?: RateLimitBudgetInput
+  readonly api?: RateLimitBudgetInput
+}
+
+/**
+ * The defaults for each rate-limit budget, from `lib/rateLimit.ts`. Kept in
+ * this file so the assembly can leave `rateLimit` unset and still get the same
+ * numbers `loadConfig` produced.
+ */
+const RATE_LIMIT_DEFAULTS = {
+  forms: { limit: 20, windowSeconds: 60 },
+  auth: { limit: 10, windowSeconds: 60 },
+  loginAccount: { limit: 10, windowSeconds: 900 },
+  api: { limit: 600, windowSeconds: 60 },
+} as const
+
+/**
+ * Identity helper for the assembly's config file. It exists for the type-check
+ * only: `defineKelpieConfig({...})` makes TypeScript check the object against
+ * `KelpieConfigInput` at the call site, so a wrong-shape field is caught in
+ * the assembly rather than at boot.
+ */
+export function defineKelpieConfig(input: KelpieConfigInput): KelpieConfigInput {
+  return input
+}
+
+/**
+ * Resolves an assembly's config against an environment.
+ *
+ * Every `fromEnv` marker is resolved. Missing required variables and parse
+ * failures are collected together, so a self-hoster fixes them in one pass.
+ *
+ * @throws ConfigurationError listing every problem.
+ */
+export function resolveKelpieConfig(input: KelpieConfigInput, environment: Environment): KelpieConfig {
+  const walked = resolveMarkers(input, environment)
+  const problems = [...walked.problems.map((problem) => (problem.path.length > 0 ? `${problem.path}: ${problem.message}` : problem.message))]
+
+  // Even when problems exist, the walk still produced a partial object. Reshape
+  // it now: any field a problem covered will be undefined, which is fine, since
+  // we throw before returning.
+  const resolved = walked.value as ResolvedInput
+
+  const email = buildEmailConfig(resolved.email)
+  const rateLimit = buildRateLimitConfig(resolved.rateLimit)
+  const env = mergeEnv(environment, resolved.env)
+  const secretEncryption = buildSecretEncryptionConfig(resolved.secretEncryption)
+
+  if (problems.length > 0) {
+    throw new ConfigurationError(problems)
+  }
+
+  return {
+    runtimeMode: resolved.runtimeMode,
+    port: resolved.port,
+    databaseUrl: resolved.databaseUrl,
+    logging: {
+      level: resolved.logging.level,
+      destinations: resolved.logging.destinations,
+    },
+    email,
+    moduleConfigPath: resolved.moduleConfigPath,
+    webBundleDirectory: resolved.webBundleDirectory,
+    rateLimit,
+    trustedProxyHopCount: resolved.trustedProxyHopCount ?? 0,
+    env,
+    appBaseUrl: resolved.appBaseUrl,
+    secretEncryption,
+  }
+}
+
+/**
+ * `kelpie.config.ts` env wins per-key; unset keys pass through from `environment`.
+ * Absent env section returns `environment` unchanged, so a self-hoster who has
+ * not opted in gets the same behaviour they had before pass 2.
+ */
+function mergeEnv(
+  environment: Environment,
+  resolvedEnv: Readonly<Record<string, string | undefined>> | undefined,
+): Environment {
+  if (resolvedEnv === undefined) {
+    return environment
+  }
+
+  return { ...environment, ...resolvedEnv }
+}
+
+interface ResolvedInput {
+  readonly runtimeMode: RuntimeMode
+  readonly port: number
+  readonly databaseUrl: string
+  readonly logging: {
+    readonly level: LogLevel
+    readonly destinations: readonly LoggingDestination[]
+  }
+  readonly webBundleDirectory?: string | undefined
+  readonly moduleConfigPath?: string | undefined
+  readonly trustedProxyHopCount?: number
+  readonly appBaseUrl?: string
+  readonly secretEncryption?: ResolvedSecretEncryption
+  readonly email: ResolvedEmail
+  readonly rateLimit?: ResolvedRateLimit
+  readonly env?: Readonly<Record<string, string | undefined>>
+  readonly modules: readonly KelpieModule[]
+}
+
+interface ResolvedSecretEncryption {
+  readonly key: string
+  readonly previousKey?: string
+}
+
+interface ResolvedEmail {
+  readonly provider: string
+  readonly from: string
+}
+
+interface ResolvedRateLimit {
+  readonly forms?: { readonly limit?: number; readonly windowSeconds?: number }
+  readonly auth?: { readonly limit?: number; readonly windowSeconds?: number }
+  readonly loginAccount?: { readonly limit?: number; readonly windowSeconds?: number }
+  readonly api?: { readonly limit?: number; readonly windowSeconds?: number }
+}
+
+function buildEmailConfig(resolved: ResolvedEmail | undefined): EmailConfig {
+  // Missing `email.provider` or `email.from` is already recorded by the
+  // walker; return a placeholder so `resolveKelpieConfig` reaches its throw
+  // below.
+  return {
+    EMAIL_PROVIDER: resolved?.provider ?? '',
+    EMAIL_FROM: resolved?.from ?? '',
+  }
+}
+
+/**
+ * Reshape the resolved leaves into the `SecretEncryptionConfig` shape modules
+ * already consume. Returns undefined when the config file omits the field, in
+ * which case a module falls back to reading `context.config(...)`.
+ */
+function buildSecretEncryptionConfig(
+  resolved: ResolvedSecretEncryption | undefined,
+): SecretEncryptionConfig | undefined {
+  if (resolved === undefined) {
+    return undefined
+  }
+
+  return resolved.previousKey === undefined
+    ? { SECRET_ENCRYPTION_KEY: resolved.key }
+    : { SECRET_ENCRYPTION_KEY: resolved.key, SECRET_ENCRYPTION_KEY_PREVIOUS: resolved.previousKey }
+}
+
+function buildRateLimitConfig(resolved: ResolvedRateLimit | undefined): RateLimitConfig {
+  return {
+    forms: budget('forms', resolved?.forms),
+    auth: budget('auth', resolved?.auth),
+    loginAccount: budget('loginAccount', resolved?.loginAccount),
+    api: budget('api', resolved?.api),
+  }
+}
+
+function budget(
+  key: keyof typeof RATE_LIMIT_DEFAULTS,
+  input: { readonly limit?: number; readonly windowSeconds?: number } | undefined,
+): { readonly limit: number; readonly windowMs: number } {
+  const defaults = RATE_LIMIT_DEFAULTS[key]
+
+  return {
+    limit: input?.limit ?? defaults.limit,
+    windowMs: (input?.windowSeconds ?? defaults.windowSeconds) * 1000,
+  }
+}

package/src/lib/logger.ts

@@ -1,8 +1,18 @@
+import winston from 'winston'
+import Transport from 'winston-transport'
+
 import type { LogLevel } from './config.ts'
 
 /**
- * Structured logging as JSON lines. The sink is injected so tests capture output
- * instead of writing to stdout, and so a deployment can redirect it.
+ * Structured logging as JSON lines. Every line goes through one or more
+ * transports, each of which is a named destination (`createStdoutTransport`,
+ * `createCaptureTransport`, and whatever a deployment adds). Nothing defaults:
+ * an empty transport list means the logger writes nowhere, which the assembly
+ * must notice.
+ *
+ * Winston handles level filtering and fan-out to transports. The JSON line
+ * itself is built in this file and passed through as the message, so the
+ * envelope order (`time`, `level`, `message` last) is preserved exactly.
  */
 
 export type LogFields = Readonly<Record<string, unknown>>
@@ -16,48 +26,96 @@ export interface Logger {
   child(fields: LogFields): Logger
 }
 
-export type LogSink = (line: string) => void
+/**
+ * A destination declared in `kelpie.config.ts`. Extend the union to add a new
+ * kind; the switch in `createTransportForDestination` fails to compile until it
+ * covers every new variant, so a destination cannot be added in config without
+ * a matching transport factory.
+ */
+export type LoggingDestination = { readonly kind: 'stdout' }
+
+const LEVELS: Readonly<Record<LogLevel, number>> = {
+  error: 0,
+  warn: 1,
+  info: 2,
+  debug: 3,
+}
+
+class LineTransport extends Transport {
+  private readonly writeLine: (line: string) => void
+
+  constructor(writeLine: (line: string) => void) {
+    super()
+    this.writeLine = writeLine
+  }
+
+  override log(info: { readonly message: string }, next: () => void): void {
+    this.writeLine(info.message)
+    // Winston expects the transport to emit 'logged' after handling.
+    setImmediate(() => this.emit('logged', info))
+    next()
+  }
+}
+
+/** Writes each line plus a trailing newline directly to stdout. */
+export function createStdoutTransport(): Transport {
+  return new LineTransport((line) => {
+    process.stdout.write(`${line}\n`)
+  })
+}
 
-const severityByLevel: Readonly<Record<LogLevel, number>> = {
-  debug: 10,
-  info: 20,
-  warn: 30,
-  error: 40,
+/** Hands each line to a callback. Tests use it to capture output. */
+export function createCaptureTransport(onLine: (line: string) => void): Transport {
+  return new LineTransport(onLine)
+}
+
+/**
+ * Builds the transport for one declared destination. The switch is exhaustive
+ * so adding a new `LoggingDestination` kind without a factory clause fails to
+ * compile.
+ */
+export function createTransportForDestination(destination: LoggingDestination): Transport {
+  switch (destination.kind) {
+    case 'stdout':
+      return createStdoutTransport()
+  }
 }
 
-function writeToStdout(line: string): void {
-  process.stdout.write(`${line}\n`)
+export interface CreateLoggerOptions {
+  readonly level: LogLevel
+  readonly transports: readonly Transport[]
+  /** Injected so tests get deterministic timestamps. Defaults to the wall clock. */
+  readonly now?: () => Date
 }
 
 /**
- * @param level Minimum level to emit. Lines below it are dropped.
- * @param sink Receives one complete JSON line per log call.
- * @param now Injected so tests get deterministic timestamps.
+ * Builds a logger. `transports` is required: an empty list writes nowhere and
+ * that is the assembly's decision to make, not a silent default.
  */
-export function createLogger(
-  level: LogLevel,
-  sink: LogSink = writeToStdout,
-  now: () => Date = () => new Date(),
-): Logger {
-  const threshold = severityByLevel[level]
+export function createLogger(options: CreateLoggerOptions): Logger {
+  const now = options.now ?? ((): Date => new Date())
+  const winstonLogger = winston.createLogger({
+    levels: LEVELS,
+    level: options.level,
+    transports: [...options.transports],
+  })
 
   function build(boundFields: LogFields): Logger {
     function emit(lineLevel: LogLevel, message: string, fields?: LogFields): void {
-      if (severityByLevel[lineLevel] < threshold) {
-        return
-      }
-      // The envelope is written last so a field called `message`, `level`, or
-      // `time` cannot overwrite it. A colliding field is dropped; a corrupted
-      // envelope would make the whole line untrustworthy.
-      sink(
-        JSON.stringify({
-          ...boundFields,
-          ...fields,
-          time: now().toISOString(),
-          level: lineLevel,
-          message,
-        }),
-      )
+      // The envelope is written last so a bound or per-call field called
+      // `message`, `level`, or `time` cannot overwrite it. A colliding field
+      // is dropped; a corrupted envelope would make the whole line untrustworthy.
+      const line = JSON.stringify({
+        ...boundFields,
+        ...fields,
+        time: now().toISOString(),
+        level: lineLevel,
+        message,
+      })
+      // The full JSON line is passed as `message` and each transport writes it
+      // verbatim. Winston still filters by level and fans out to transports;
+      // it does not re-format the line.
+      winstonLogger.log({ level: lineLevel, message: line })
     }
 
     return {

package/src/modules/agent-tasks/index.ts

@@ -48,7 +48,10 @@ export function createAgentTasksModule(
       // Validated at boot rather than on the first run: a missing or malformed
       // key means no stored auth header can ever be read back, and finding that
       // out when a dispatch quietly fails is far too late.
-      const cipher = createSecretCipher(context.config(secretEncryptionConfigSchema))
+      //
+      // Prefer the top-level `secretEncryption` from the assembly's
+      // kelpie.config.ts; fall back to the schema read for older assemblies.
+      const cipher = createSecretCipher(context.secretEncryption ?? context.config(secretEncryptionConfigSchema))
       const egress = createEgressGuard(context.config(egressConfigSchema))
 
       const engine = createDispatchEngine({

package/src/modules/agent-tasks/prompt.ts

@@ -3,12 +3,22 @@ import type { AgentTaskDefinition, AgentTaskTargetType } from '@kelpie/schemas'
 /**
  * Renders the markdown prompt a ResolvedTask carries. Pure: every fact arrives
  * as an argument, so the template is unit-testable and Copy and Run cannot
- * drift — both read the one string this produces.
+ * drift — both read the strings this file produces.
  *
- * The shape is the mockup's (`mockups/src/data/agentTasks.ts`), with two
- * server-era changes: workspace-scoped tasks are pointed at `GET /v1/dashboard`
- * instead of a single record, and the sweep tasks carry a "Workspace signals"
- * section computed at resolve time.
+ * Two renderers, one shared body.
+ *
+ *   - {@link renderBasePrompt} returns the general request: the task title,
+ *     the target, the required reads, the handbook pages, related ids,
+ *     workspace signals, the task instructions, and the write policy. It
+ *     says nothing about *how* the receiver should apply the changes.
+ *   - {@link renderExternalAgentPrompt} wraps the base with framing for an
+ *     agent that calls the CRM itself — the opening line about MCP / the
+ *     public API and the closing "Done when… applied allowed updates" tail.
+ *
+ * The resolved-task and dispatch payloads carry both. The copy-prompt UI
+ * flow serves the external-agent version by default; the hosted AI in the
+ * cloud reads the base and adds its own structured-output framing. Two
+ * consumers, two wrappers, one body.
  */
 
 /** A handbook page the task requires, resolved to this workspace's own copy. */
@@ -99,7 +109,13 @@ function firstRead(targetType: AgentTaskTargetType): string {
   return 'Load the target record and agent fields.'
 }
 
-export function renderPrompt(
+/**
+ * The shared body. Renders everything a receiver needs to *understand* the
+ * task, without telling it how to apply results. Callers wrap this with an
+ * opening and closing that matches how the receiver will execute (call the
+ * CRM, or return structured data for a caller to apply).
+ */
+export function renderBasePrompt(
   definition: AgentTaskDefinition,
   targetType: AgentTaskTargetType,
   targetId: string,
@@ -107,9 +123,6 @@ export function renderPrompt(
 ): string {
   return `# Agent task: ${definition.label}
 
-You are operating on the Kelpie workspace **${inputs.workspaceName}** via MCP / the public API.
-Bring your own model. Kelpie does not bundle AI.
-
 ## Task
 - **Id:** \`${definition.id}\`
 - **Intent:** ${definition.description}
@@ -133,8 +146,43 @@ ${definition.instructions}
 
 ## Write policy
 ${definition.writePolicy}
+`
+}
 
+/**
+ * The external-agent-framed prompt. Adds the opening line about MCP / the
+ * public API and the closing "Done when" tail to the base. This is what the
+ * Copy button hands to the user and what dispatch sends by default; an
+ * agent that runs its own tool loop against the CRM reads this and works
+ * from it directly.
+ */
+export function renderExternalAgentPrompt(
+  definition: AgentTaskDefinition,
+  targetType: AgentTaskTargetType,
+  targetId: string,
+  inputs: PromptInputs,
+): string {
+  const opening = `# Agent task: ${definition.label}
+
+You are operating on the Kelpie workspace **${inputs.workspaceName}** via MCP / the public API.
+Bring your own model. Kelpie does not bundle AI.
+`
+
+  // The base opens with its own `# Agent task:` header; strip it so the
+  // combined prompt has one heading rather than two.
+  const base = renderBasePrompt(definition, targetType, targetId, inputs)
+  const bodyWithoutHeading = base.replace(/^# Agent task:[^\n]*\n\n?/u, '')
+
+  return `${opening}
+${bodyWithoutHeading}
 ## Done when
 You have applied allowed updates via MCP/API (or asked the human when blocked), and summarised what changed.
 `
 }
+
+/**
+ * Backwards-compatible alias for the pre-split renderer. Existing callers
+ * that produced the "wrapped" prompt keep working. New callers pick
+ * {@link renderBasePrompt} or {@link renderExternalAgentPrompt} directly.
+ */
+export const renderPrompt = renderExternalAgentPrompt

package/src/modules/agent-tasks/service.ts

@@ -14,7 +14,7 @@ import { requireWorkspaceId } from '../auth/actor.ts'
 import { roleAllows } from '../workspace/roles.ts'
 import { AGENT_TASK_DEFINITIONS, findTask, tasksFor } from './catalog.ts'
 import type { DispatchEngine } from './dispatch.ts'
-import { renderPrompt } from './prompt.ts'
+import { renderBasePrompt, renderExternalAgentPrompt } from './prompt.ts'
 import * as repository from './repository.ts'
 import { AGENT_SORTS, DEFAULT_AGENT_SORT, DEFAULT_RUN_SORT, RUN_SORTS } from './repository.ts'
 import type { AgentRecord, RunFilters, RunRecord } from './repository.ts'
@@ -184,7 +184,8 @@ export function createAgentTasksService(dependencies: AgentTasksDependencies): A
       taskId: definition.id,
       targetType: target.targetType,
       targetId: target.targetId,
-      prompt: renderPrompt(definition, target.targetType, target.targetId, inputs),
+      prompt: renderExternalAgentPrompt(definition, target.targetType, target.targetId, inputs),
+      basePrompt: renderBasePrompt(definition, target.targetType, target.targetId, inputs),
       context: {
         targetLabel: inputs.targetLabel,
         deepLink: inputs.deepLink,

package/src/modules/agent-tasks/wire.ts

@@ -21,7 +21,18 @@ export interface ResolvedTaskView {
   readonly taskId: string
   readonly targetType: AgentTaskTargetType
   readonly targetId: string
+  /**
+   * The external-agent-framed prompt: opens with "operating via MCP / the
+   * public API", ends with "Done when… applied allowed updates". This is
+   * what Copy hands to a user and what a customer agent reads.
+   */
   readonly prompt: string
+  /**
+   * The shared body without the framing. What an agent that returns
+   * structured data (the hosted AI is the one that ships) reads before
+   * adding its own instructions.
+   */
+  readonly basePrompt: string
   readonly context: ContextPackView
 }
 
@@ -31,6 +42,7 @@ export function resolvedTaskResponse(resolved: ResolvedTaskView): Record<string,
     target_type: resolved.targetType,
     target_id: resolved.targetId,
     prompt: resolved.prompt,
+    base_prompt: resolved.basePrompt,
     context: {
       target_label: resolved.context.targetLabel,
       deep_link: resolved.context.deepLink,

package/src/modules/auth/index.ts

@@ -13,12 +13,10 @@ import { createAuthService } from './service.ts'
  * `users`.
  */
 
-const authConfigSchema = z
-  .object({
-    /** Cookies go out `Secure` everywhere except development. */
-    NODE_ENV: z.enum(['development', 'test', 'production']),
-  })
-  .merge(appUrlConfigSchema)
+const nodeEnvSchema = z.object({
+  /** Cookies go out `Secure` everywhere except development. */
+  NODE_ENV: z.enum(['development', 'test', 'production']),
+})
 
 export function createAuthModule(migrationsDirectory: string): KelpieModule {
   return {
@@ -26,14 +24,18 @@ export function createAuthModule(migrationsDirectory: string): KelpieModule {
     structural: true,
 
     register(context) {
-      const config = context.config(authConfigSchema)
+      const { NODE_ENV } = context.config(nodeEnvSchema)
+      // Prefer the top-level `appBaseUrl` from the assembly's kelpie.config.ts;
+      // fall back to the schema read for older assemblies that don't declare it.
+      const appBaseUrl = context.appBaseUrl ?? context.config(appUrlConfigSchema).APP_BASE_URL
+
       const service = createAuthService({
         db: context.db,
         transaction: context.transaction,
         email: context.email,
         createId: context.createId,
         now: context.now,
-        appBaseUrl: config.APP_BASE_URL,
+        appBaseUrl,
       })
 
       context.schema(schema, migrationsDirectory)
@@ -46,7 +48,7 @@ export function createAuthModule(migrationsDirectory: string): KelpieModule {
           // `Secure` everywhere except development. A test host reaches the API
           // over http through a test client, which stores the cookie regardless
           // of the flag, so test is not excluded.
-          cookie: { secure: config.NODE_ENV !== 'development' },
+          cookie: { secure: NODE_ENV !== 'development' },
         })
       })
 

package/src/modules/companies/events.ts

@@ -0,0 +1,25 @@
+import { z } from 'zod'
+
+import type { ModuleEventCatalog } from '../../runtime/module.ts'
+
+/** Domain events published by the companies module. */
+
+export const companiesEvents = {
+  'companies.company.created': z.object({}).strict(),
+  'companies.company.updated': z.object({ changed: z.array(z.string()).readonly() }),
+  'companies.company.deleted': z.object({}).strict(),
+} satisfies ModuleEventCatalog
+
+export type CompanyCreatedData = Record<string, never>
+export interface CompanyUpdatedData {
+  readonly changed: readonly string[]
+}
+export type CompanyDeletedData = Record<string, never>
+
+declare module '../../runtime/events.ts' {
+  interface KelpieEventMap {
+    'companies.company.created': CompanyCreatedData
+    'companies.company.updated': CompanyUpdatedData
+    'companies.company.deleted': CompanyDeletedData
+  }
+}

package/src/modules/companies/index.ts

@@ -1,5 +1,6 @@
 import type { KelpieModule } from '../../runtime/module.ts'
 import { createActivityRecorder } from '../activities/index.ts'
+import { companiesEvents } from './events.ts'
 import { mountCompaniesRoutes } from './routes.ts'
 import * as schema from './schema.ts'
 import { createCompaniesService } from './service.ts'
@@ -16,6 +17,7 @@ export function createCompaniesModule(migrationsDirectory: string): KelpieModule
     id: 'companies',
     requires: ['workspace', 'activities'],
     structural: true,
+    events: companiesEvents,
 
     register(context) {
       const service = createCompaniesService({