@kelpie/server 0.1.0

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

@@ -0,0 +1,260 @@
+import { AGENT_RUN_STATUSES, AGENT_TASK_TARGET_TYPES } from '@kelpie/schemas'
+import type { AgentRunStatus, AgentTaskDefinition, AgentTaskTargetType } from '@kelpie/schemas'
+import type { Context, Hono } from 'hono'
+import { z } from 'zod'
+
+import { AppError } from '../../lib/errors.ts'
+import { pageBody, readJsonBody, readListParameters } from '../../lib/http.ts'
+import { endpointUrlProblem } from '../../lib/url.ts'
+import type { Actor } from '../auth/actor.ts'
+import { resolveActorFrom } from '../auth/credentials.ts'
+import type { CredentialDependencies } from '../auth/credentials.ts'
+import type { AgentTasksService, AgentView, RunView } from './service.ts'
+import { resolvedTaskResponse } from './wire.ts'
+
+/**
+ * Wire shapes for `/v1/agent-tasks`, `/v1/agent-runs` and `/v1/agents`.
+ *
+ * Bodies are strict: `api.md` makes an unknown field a 422 rather than
+ * something dropped in silence. Everything is `snake_case` on the wire —
+ * `agent-tasks.md`'s examples predate that convention and `api.md` wins.
+ */
+
+const CREDENTIALS_MESSAGE = 'Remove the credentials from the URL; use auth_header instead'
+
+const endpointField = z
+  .string()
+  .refine((value) => endpointUrlProblem(value, CREDENTIALS_MESSAGE) === undefined, {
+    error: (issue) =>
+      endpointUrlProblem(String(issue.input), CREDENTIALS_MESSAGE)?.message ?? 'Invalid URL',
+  })
+
+const targetTypeField = z.enum(AGENT_TASK_TARGET_TYPES)
+
+export const resolveBody = z.strictObject({
+  target_type: targetTypeField,
+  target_id: z.string().min(1),
+})
+
+export const runBody = z.strictObject({
+  target_type: targetTypeField,
+  target_id: z.string().min(1),
+  agent_id: z.string().min(1),
+})
+
+export const createAgentBody = z.strictObject({
+  name: z.string().min(1),
+  endpoint: endpointField,
+  auth_header: z.string().min(1).optional(),
+})
+
+/** `auth_header: null` clears the stored header; a string replaces it. */
+export const updateAgentBody = z
+  .strictObject({
+    name: z.string().min(1),
+    endpoint: endpointField,
+    auth_header: z.string().min(1).nullable(),
+  })
+  .partial()
+
+export function taskDefinitionResponse(definition: AgentTaskDefinition): Record<string, unknown> {
+  return {
+    id: definition.id,
+    label: definition.label,
+    description: definition.description,
+    target_types: definition.targetTypes,
+    placement: definition.placement,
+    handbook_slugs: definition.handbookSlugs,
+    instructions: definition.instructions,
+    write_policy: definition.writePolicy,
+  }
+}
+
+export function agentResponse(agent: AgentView): Record<string, unknown> {
+  return {
+    id: agent.id,
+    name: agent.name,
+    endpoint: agent.endpoint,
+    has_auth_header: agent.hasAuthHeader,
+    last_run_at: agent.lastRunAt === null ? null : agent.lastRunAt.toISOString(),
+    created_at: agent.createdAt.toISOString(),
+    updated_at: agent.updatedAt.toISOString(),
+  }
+}
+
+export function runResponse(run: RunView): Record<string, unknown> {
+  return {
+    id: run.id,
+    agent_id: run.agentId,
+    task_id: run.taskId,
+    target_type: run.targetType,
+    target_id: run.targetId,
+    status: run.status,
+    prompt: run.prompt,
+    failure_reason: run.failureReason,
+    created_at: run.createdAt.toISOString(),
+    updated_at: run.updatedAt.toISOString(),
+  }
+}
+
+/**
+ * Reads an optional query value against a fixed list.
+ *
+ * @throws AppError 422 for a value outside the list. Answering it with an empty
+ *   result would read as "none of those" rather than "no such value".
+ */
+function readEnumFilter<Value extends string>(
+  context: Context,
+  name: string,
+  values: readonly [Value, ...Value[]],
+): Value | undefined {
+  const raw = context.req.query(name)
+
+  if (raw === undefined) {
+    return undefined
+  }
+
+  const parsed = z.enum(values).safeParse(raw)
+
+  if (!parsed.success) {
+    throw AppError.validationFailed(`That is not a ${name.replace('_', ' ')}`, [
+      { field: name, message: `Use one of: ${values.join(', ')}` },
+    ])
+  }
+
+  return parsed.data
+}
+
+/** A blank id filter asks a different question than the one intended, per `api.md`. */
+function readIdQuery(context: Context, name: string): string | undefined {
+  const raw = context.req.query(name)
+
+  if (raw === undefined) {
+    return undefined
+  }
+
+  if (raw.length === 0) {
+    throw AppError.validationFailed(`${name} must not be blank`, [
+      { field: name, message: 'Provide an id or omit the parameter' },
+    ])
+  }
+
+  return raw
+}
+
+export interface AgentTasksRoutesDependencies extends CredentialDependencies {
+  readonly service: AgentTasksService
+}
+
+export function mountAgentTasksRoutes(
+  router: Hono,
+  dependencies: AgentTasksRoutesDependencies,
+): void {
+  const requireActor = (context: Context): Promise<Actor> => resolveActorFrom(dependencies, context)
+
+  /**
+   * The catalog, optionally narrowed to one target type. Code, not rows: the
+   * whole list rides in one response with no cursor, the `/v1/mcp/tools` shape.
+   */
+  router.get('/agent-tasks', async (context) => {
+    const targetType = readEnumFilter<AgentTaskTargetType>(
+      context,
+      'target_type',
+      AGENT_TASK_TARGET_TYPES,
+    )
+    const tasks = await dependencies.service.listTasks(await requireActor(context), targetType)
+
+    return context.json({ data: tasks.map(taskDefinitionResponse), next_cursor: null })
+  })
+
+  router.post('/agent-tasks/:taskId/resolve', async (context) => {
+    const body = await readJsonBody(context, resolveBody)
+    const resolved = await dependencies.service.resolve(
+      await requireActor(context),
+      context.req.param('taskId'),
+      { targetType: body.target_type, targetId: body.target_id },
+    )
+
+    return context.json(resolvedTaskResponse(resolved))
+  })
+
+  /** Creates the run and answers `queued`; the dispatch happens after. */
+  router.post('/agent-tasks/:taskId/run', async (context) => {
+    const body = await readJsonBody(context, runBody)
+    const run = await dependencies.service.run(
+      await requireActor(context),
+      context.req.param('taskId'),
+      { targetType: body.target_type, targetId: body.target_id, agentId: body.agent_id },
+    )
+
+    return context.json(runResponse(run), 201)
+  })
+
+  router.get('/agent-runs', async (context) => {
+    const page = await dependencies.service.listRuns(
+      await requireActor(context),
+      {
+        agentId: readIdQuery(context, 'agent_id'),
+        status: readEnumFilter<AgentRunStatus>(context, 'status', AGENT_RUN_STATUSES),
+      },
+      readListParameters(context),
+    )
+
+    return context.json(pageBody(page, runResponse))
+  })
+
+  router.get('/agent-runs/:id', async (context) => {
+    const run = await dependencies.service.getRun(
+      await requireActor(context),
+      context.req.param('id'),
+    )
+
+    return context.json(runResponse(run))
+  })
+
+  router.get('/agents', async (context) => {
+    const page = await dependencies.service.listAgents(
+      await requireActor(context),
+      readListParameters(context),
+    )
+
+    return context.json(pageBody(page, agentResponse))
+  })
+
+  router.post('/agents', async (context) => {
+    const body = await readJsonBody(context, createAgentBody)
+    const agent = await dependencies.service.createAgent(await requireActor(context), {
+      name: body.name,
+      endpoint: body.endpoint,
+      authHeader: body.auth_header,
+    })
+
+    return context.json(agentResponse(agent), 201)
+  })
+
+  router.get('/agents/:id', async (context) => {
+    const agent = await dependencies.service.getAgent(
+      await requireActor(context),
+      context.req.param('id'),
+    )
+
+    return context.json(agentResponse(agent))
+  })
+
+  router.patch('/agents/:id', async (context) => {
+    const body = await readJsonBody(context, updateAgentBody)
+    const agent = await dependencies.service.updateAgent(
+      await requireActor(context),
+      context.req.param('id'),
+      { name: body.name, endpoint: body.endpoint, authHeader: body.auth_header },
+    )
+
+    return context.json(agentResponse(agent))
+  })
+
+  router.delete('/agents/:id', async (context) => {
+    await dependencies.service.removeAgent(await requireActor(context), context.req.param('id'))
+
+    return context.body(null, 204)
+  })
+}

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

@@ -0,0 +1,57 @@
+import { AGENT_RUN_STATUSES } from '@kelpie/schemas'
+import { index, pgTable, text } from 'drizzle-orm/pg-core'
+
+import { checkOneOf, createdAt, moment, primaryId, updatedAt } from '../../lib/columns.ts'
+import { workspaces } from '../workspace/schema.ts'
+
+/**
+ * Agents the workspace has registered to receive task dispatches. Kelpie bundles
+ * no AI; these are the customer's own agents.
+ */
+export const agentRegistrations = pgTable(
+  'agent_registrations',
+  {
+    id: primaryId(),
+    workspaceId: text('workspace_id')
+      .notNull()
+      .references(() => workspaces.id, { onDelete: 'cascade' }),
+    name: text('name').notNull(),
+    endpoint: text('endpoint').notNull(),
+    authHeaderEncrypted: text('auth_header_encrypted'),
+    lastRunAt: moment('last_run_at'),
+    createdAt: createdAt(),
+    updatedAt: updatedAt(),
+  },
+  (table) => [index('agent_registrations_workspace_idx').on(table.workspaceId)],
+)
+
+/**
+ * `task_id` is a catalog string, not a foreign key: the task catalog ships in
+ * code, so a run outlives any catalog edit.
+ */
+export const agentRuns = pgTable(
+  'agent_runs',
+  {
+    id: primaryId(),
+    workspaceId: text('workspace_id')
+      .notNull()
+      .references(() => workspaces.id, { onDelete: 'cascade' }),
+    agentId: text('agent_id')
+      .notNull()
+      .references(() => agentRegistrations.id, { onDelete: 'cascade' }),
+    taskId: text('task_id').notNull(),
+    targetType: text('target_type').notNull(),
+    targetId: text('target_id').notNull(),
+    status: text('status').notNull().default('queued'),
+    prompt: text('prompt').notNull(),
+    /** Set only on `failed`: what the dispatch hit, for the run log. */
+    failureReason: text('failure_reason'),
+    createdAt: createdAt(),
+    updatedAt: updatedAt(),
+  },
+  (table) => [
+    index('agent_runs_workspace_idx').on(table.workspaceId),
+    index('agent_runs_agent_idx').on(table.agentId),
+    checkOneOf('agent_runs_status_check', table.status, AGENT_RUN_STATUSES),
+  ],
+)

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

@@ -0,0 +1,370 @@
+import type { AgentRunStatus, AgentTaskDefinition, AgentTaskTargetType } from '@kelpie/schemas'
+
+import { changedKeys } from '../../lib/changes.ts'
+import type { Database } from '../../lib/database.ts'
+import { AppError, describeThrown } from '../../lib/errors.ts'
+import type { IdFactory } from '../../lib/ids.ts'
+import type { Logger } from '../../lib/logger.ts'
+import { mapPage, readListWindow, toPage } from '../../lib/pagination.ts'
+import type { ListQueryParameters, Page } from '../../lib/pagination.ts'
+import type { SecretCipher } from '../../lib/secrets.ts'
+import type { TransactionScope } from '../../runtime/transaction.ts'
+import type { Actor } from '../auth/actor.ts'
+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 * 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'
+import { assemblePromptInputs } from './resolve.ts'
+import type { ResolvedTaskView } from './wire.ts'
+
+/**
+ * Agent tasks: the catalog, resolve, run dispatch, and registered agents.
+ *
+ * Roles split by verb, deliberately not the webhooks all-verbs-admin rule.
+ * Managing a registration is admin work — its endpoint is where workspace data
+ * gets POSTed. But *reading* the list is what the Run dialog on every record
+ * page does, and running a task is the product's core loop, so members read
+ * agents, resolve tasks, run them, and read the run log. The auth header is the
+ * one secret in the module and it is sealed and never returned, so a member
+ * reading the list learns an endpoint name, not a credential.
+ */
+
+export interface AgentTasksDependencies {
+  readonly db: Database
+  readonly transaction: TransactionScope
+  readonly createId: IdFactory
+  readonly now: () => Date
+  readonly cipher: SecretCipher
+  readonly engine: DispatchEngine
+  readonly log: Logger
+}
+
+/** An agent as the API returns one: never the header, never the tenancy column. */
+export interface AgentView {
+  readonly id: string
+  readonly name: string
+  readonly endpoint: string
+  readonly hasAuthHeader: boolean
+  readonly lastRunAt: Date | null
+  readonly createdAt: Date
+  readonly updatedAt: Date
+}
+
+export type RunView = Omit<RunRecord, 'workspaceId'>
+
+export interface ResolveTargetInput {
+  readonly targetType: AgentTaskTargetType
+  readonly targetId: string
+}
+
+export interface RunTaskInput extends ResolveTargetInput {
+  readonly agentId: string
+}
+
+export interface CreateAgentInput {
+  readonly name: string
+  readonly endpoint: string
+  readonly authHeader?: string | undefined
+}
+
+export interface UpdateAgentInput {
+  readonly name?: string | undefined
+  readonly endpoint?: string | undefined
+  /** A string replaces the stored header; `null` clears it. */
+  readonly authHeader?: string | null | undefined
+}
+
+export interface RunListFilters {
+  readonly agentId?: string | undefined
+  readonly status?: AgentRunStatus | undefined
+}
+
+export interface AgentTasksService {
+  listTasks(actor: Actor, targetType?: AgentTaskTargetType): Promise<readonly AgentTaskDefinition[]>
+  resolve(actor: Actor, taskId: string, target: ResolveTargetInput): Promise<ResolvedTaskView>
+  /** Creates the run, answers `queued`, and dispatches after the transaction commits. */
+  run(actor: Actor, taskId: string, input: RunTaskInput): Promise<RunView>
+  getRun(actor: Actor, id: string): Promise<RunView>
+  listRuns(actor: Actor, filters: RunListFilters, query: ListQueryParameters): Promise<Page<RunView>>
+  listAgents(actor: Actor, query: ListQueryParameters): Promise<Page<AgentView>>
+  getAgent(actor: Actor, id: string): Promise<AgentView>
+  createAgent(actor: Actor, input: CreateAgentInput): Promise<AgentView>
+  updateAgent(actor: Actor, id: string, changes: UpdateAgentInput): Promise<AgentView>
+  removeAgent(actor: Actor, id: string): Promise<void>
+}
+
+function toAgentView(record: AgentRecord): AgentView {
+  return {
+    id: record.id,
+    name: record.name,
+    endpoint: record.endpoint,
+    hasAuthHeader: record.authHeaderEncrypted !== null,
+    lastRunAt: record.lastRunAt,
+    createdAt: record.createdAt,
+    updatedAt: record.updatedAt,
+  }
+}
+
+function toRunView(record: RunRecord): RunView {
+  const { workspaceId: _workspaceId, ...view } = record
+
+  return view
+}
+
+export function createAgentTasksService(dependencies: AgentTasksDependencies): AgentTasksService {
+  function requireAdminWorkspace(actor: Actor): string {
+    const workspaceId = requireWorkspaceId(actor)
+
+    if (actor.role === null || !roleAllows(actor.role, 'admin')) {
+      throw new AppError('forbidden', 'This action needs the admin role')
+    }
+
+    return workspaceId
+  }
+
+  function requireTask(taskId: string): AgentTaskDefinition {
+    const definition = findTask(taskId)
+
+    if (definition === undefined) {
+      throw AppError.notFound('Agent task not found')
+    }
+
+    return definition
+  }
+
+  /**
+   * A task that exists but does not apply to the named target type is a `422`,
+   * not a `404`: the caller found the task, they aimed it wrong.
+   */
+  function requireTargetType(definition: AgentTaskDefinition, targetType: AgentTaskTargetType): void {
+    if (!definition.targetTypes.includes(targetType)) {
+      throw AppError.validationFailed('This task does not apply to that target type', [
+        {
+          field: 'target_type',
+          message: `Task ${definition.id} applies to: ${definition.targetTypes.join(', ')}`,
+        },
+      ])
+    }
+  }
+
+  async function requireAgent(workspaceId: string, id: string): Promise<AgentRecord> {
+    const agent = await repository.findAgent(dependencies.db, workspaceId, id)
+
+    // An agent in another workspace is indistinguishable from one that never
+    // existed, per `api.md`.
+    if (agent === undefined) {
+      throw AppError.notFound('Agent not found')
+    }
+
+    return agent
+  }
+
+  async function resolveView(
+    workspaceId: string,
+    definition: AgentTaskDefinition,
+    target: ResolveTargetInput,
+  ): Promise<ResolvedTaskView> {
+    const inputs = await assemblePromptInputs(
+      dependencies.db,
+      workspaceId,
+      definition,
+      target.targetType,
+      target.targetId,
+    )
+
+    if (inputs === undefined) {
+      throw AppError.notFound('Target record not found')
+    }
+
+    return {
+      taskId: definition.id,
+      targetType: target.targetType,
+      targetId: target.targetId,
+      prompt: renderPrompt(definition, target.targetType, target.targetId, inputs),
+      context: {
+        targetLabel: inputs.targetLabel,
+        deepLink: inputs.deepLink,
+        handbookSlugs: inputs.handbookPages.map((page) => page.slug),
+        pinnedNoteIds: inputs.pinnedNoteIds,
+        openPlanIds: inputs.openPlanIds,
+        openDecisionIds: inputs.openDecisionIds,
+        related: Object.fromEntries(
+          Object.entries(inputs.related)
+            .filter(([, list]) => list.ids.length > 0)
+            .map(([key, list]) => [key, list.ids]),
+        ),
+      },
+    }
+  }
+
+  return {
+    listTasks(actor, targetType) {
+      requireWorkspaceId(actor)
+
+      // The catalog ships in code and is the same for every workspace; the
+      // credential check is about who may ask, not whose answer differs.
+      return Promise.resolve(
+        targetType === undefined ? AGENT_TASK_DEFINITIONS : tasksFor(targetType),
+      )
+    },
+
+    async resolve(actor, taskId, target) {
+      const workspaceId = requireWorkspaceId(actor)
+      const definition = requireTask(taskId)
+
+      requireTargetType(definition, target.targetType)
+
+      return resolveView(workspaceId, definition, target)
+    },
+
+    async run(actor, taskId, input) {
+      const workspaceId = requireWorkspaceId(actor)
+      const definition = requireTask(taskId)
+
+      requireTargetType(definition, input.targetType)
+
+      const agent = await requireAgent(workspaceId, input.agentId)
+      const resolved = await resolveView(workspaceId, definition, input)
+      const now = dependencies.now()
+
+      const created = await dependencies.transaction(async ({ tx }) => {
+        const run = await repository.insertRun(tx, {
+          id: dependencies.createId('agentRun'),
+          workspaceId,
+          agentId: agent.id,
+          taskId: definition.id,
+          targetType: input.targetType,
+          targetId: input.targetId,
+          status: 'queued',
+          prompt: resolved.prompt,
+        })
+
+        // `last_run_at` moves; `updated_at` does not. The latter answers "when
+        // did somebody last change this registration", the webhook rule.
+        await repository.updateAgent(tx, workspaceId, agent.id, { lastRunAt: now })
+
+        return run
+      })
+
+      // After the commit, never awaited: the caller polls the run instead.
+      // `dispatch` settles every failure into the run row; this catch guards
+      // the promise chain itself so nothing leaks an unhandled rejection.
+      dependencies.engine.dispatch(created, agent, resolved).catch((error: unknown) => {
+        dependencies.log.error('agent dispatch rejected outside its own boundary', {
+          runId: created.id,
+          error: describeThrown(error),
+        })
+      })
+
+      return toRunView(created)
+    },
+
+    async getRun(actor, id) {
+      const workspaceId = requireWorkspaceId(actor)
+      const run = await repository.findRun(dependencies.db, workspaceId, id)
+
+      if (run === undefined) {
+        throw AppError.notFound('Agent run not found')
+      }
+
+      return toRunView(run)
+    },
+
+    async listRuns(actor, filters, query) {
+      const workspaceId = requireWorkspaceId(actor)
+      const window = readListWindow(query, RUN_SORTS, DEFAULT_RUN_SORT)
+      const runFilters: RunFilters = { agentId: filters.agentId, status: filters.status }
+      const rows = await repository.listRuns(dependencies.db, workspaceId, runFilters, window)
+
+      return mapPage(
+        toPage(rows, window, (run) => run.id),
+        toRunView,
+      )
+    },
+
+    async listAgents(actor, query) {
+      const workspaceId = requireWorkspaceId(actor)
+      const window = readListWindow(query, AGENT_SORTS, DEFAULT_AGENT_SORT)
+      const rows = await repository.listAgents(dependencies.db, workspaceId, window)
+
+      return mapPage(
+        toPage(rows, window, (agent) => agent.id),
+        toAgentView,
+      )
+    },
+
+    async getAgent(actor, id) {
+      return toAgentView(await requireAgent(requireWorkspaceId(actor), id))
+    },
+
+    async createAgent(actor, input) {
+      const workspaceId = requireAdminWorkspace(actor)
+
+      const created = await dependencies.transaction(({ tx }) =>
+        repository.insertAgent(tx, {
+          id: dependencies.createId('agentRegistration'),
+          workspaceId,
+          name: input.name,
+          endpoint: input.endpoint,
+          authHeaderEncrypted:
+            input.authHeader === undefined ? null : dependencies.cipher.seal(input.authHeader),
+        }),
+      )
+
+      return toAgentView(created)
+    },
+
+    async updateAgent(actor, id, changes) {
+      const workspaceId = requireAdminWorkspace(actor)
+      const existing = await requireAgent(workspaceId, id)
+
+      const columns: Partial<repository.AgentColumns> = {
+        ...(changes.name === undefined ? {} : { name: changes.name }),
+        ...(changes.endpoint === undefined ? {} : { endpoint: changes.endpoint }),
+      }
+
+      // A re-sent header always writes: sealed values cannot be compared (each
+      // seal spends a fresh IV), and re-saving a header is how a customer fixes
+      // one sealed under a lost key.
+      if (changes.authHeader !== undefined) {
+        columns.authHeaderEncrypted =
+          changes.authHeader === null ? null : dependencies.cipher.seal(changes.authHeader)
+      }
+
+      // A PATCH that changes nothing is not a write, the webhook rule.
+      if (changes.authHeader === undefined && changedKeys(existing, columns).length === 0) {
+        return toAgentView(existing)
+      }
+
+      const updated = await dependencies.transaction(async ({ tx }) => {
+        const row = await repository.updateAgent(tx, workspaceId, id, {
+          ...columns,
+          updatedAt: dependencies.now(),
+        })
+
+        if (row === undefined) {
+          throw AppError.notFound('Agent not found')
+        }
+
+        return row
+      })
+
+      return toAgentView(updated)
+    },
+
+    async removeAgent(actor, id) {
+      const workspaceId = requireAdminWorkspace(actor)
+
+      // The run log cascades with the registration, like a webhook's
+      // deliveries: a run only means anything against the agent it went to.
+      await dependencies.transaction(async ({ tx }) => {
+        await requireAgent(workspaceId, id)
+        await repository.deleteAgent(tx, workspaceId, id)
+      })
+    },
+  }
+}