@kelpie/server 0.1.0

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

@@ -0,0 +1,188 @@
+import type { Database } from '../../lib/database.ts'
+import { describeThrown } from '../../lib/errors.ts'
+import type { Logger } from '../../lib/logger.ts'
+import { SecretDecryptionError } from '../../lib/secrets.ts'
+import type { SecretCipher } from '../../lib/secrets.ts'
+import * as repository from './repository.ts'
+import type { AgentRecord, RunRecord } from './repository.ts'
+import { dispatchPayload } from './wire.ts'
+import type { ResolvedTaskView } from './wire.ts'
+
+/**
+ * The dispatch engine: one run, one POST to the registered agent's endpoint.
+ *
+ * It runs detached from the request that created the run, so a slow or
+ * unreachable agent slows nobody down; the caller polls the run instead.
+ *
+ * One attempt, deliberately, where webhook delivery retries three times. A
+ * webhook receiver dedupes on the delivery id and a repeated event is cheap;
+ * an agent that accepted a task and then timed out on the response would run
+ * the whole task twice if Kelpie re-POSTed it. A failed run keeps its reason
+ * and the human re-runs it from the page.
+ */
+
+/** How long the agent has to accept the dispatch before it counts as failed. */
+export const DISPATCH_TIMEOUT_MS = 10_000
+
+export interface DispatchRequest {
+  readonly url: string
+  readonly body: string
+  readonly headers: Readonly<Record<string, string>>
+}
+
+export interface DispatchOutcome {
+  readonly delivered: boolean
+  /** The response status, or null when no response arrived at all. */
+  readonly status: number | null
+  /** Why it failed, for the run log. Null on success. */
+  readonly reason: string | null
+}
+
+/** The outbound port. Injected so no test makes a network call. */
+export type SendDispatch = (request: DispatchRequest) => Promise<DispatchOutcome>
+
+/**
+ * The real sender. Redirects are not followed, the webhook rule: an endpoint
+ * that moved should be seen and corrected rather than have a workspace's
+ * prompt posted wherever the old address now points.
+ *
+ * The catch is broad because this is the process boundary: `fetch` rejects
+ * with anything from a DNS failure to an abort, and turning all of it into one
+ * outcome is the port's whole job. Nothing is swallowed — the reason lands on
+ * the run.
+ */
+export function createHttpSender(fetchImplementation: typeof fetch = fetch): SendDispatch {
+  return async (request) => {
+    try {
+      const response = await fetchImplementation(request.url, {
+        method: 'POST',
+        body: request.body,
+        headers: request.headers,
+        redirect: 'manual',
+        signal: AbortSignal.timeout(DISPATCH_TIMEOUT_MS),
+      })
+
+      return response.ok
+        ? { delivered: true, status: response.status, reason: null }
+        : {
+            delivered: false,
+            status: response.status,
+            reason: `agent endpoint answered ${String(response.status)}`,
+          }
+    } catch (error: unknown) {
+      return { delivered: false, status: null, reason: describeThrown(error) }
+    }
+  }
+}
+
+export interface DispatchDependencies {
+  readonly db: Database
+  readonly now: () => Date
+  readonly cipher: SecretCipher
+  readonly send: SendDispatch
+  readonly log: Logger
+}
+
+export interface DispatchEngine {
+  /**
+   * Moves the run `queued → running → succeeded | failed`. Total: every
+   * failure path settles the run rather than rejecting, so a caller may fire
+   * it without awaiting.
+   */
+  dispatch(run: RunRecord, agent: AgentRecord, resolved: ResolvedTaskView): Promise<void>
+}
+
+export function createDispatchEngine(dependencies: DispatchDependencies): DispatchEngine {
+  async function settle(runId: string, outcome: DispatchOutcome): Promise<void> {
+    await repository.updateRun(dependencies.db, runId, {
+      status: outcome.delivered ? 'succeeded' : 'failed',
+      failureReason: outcome.reason,
+      updatedAt: dependencies.now(),
+    })
+  }
+
+  return {
+    async dispatch(run, agent, resolved) {
+      try {
+        await repository.updateRun(dependencies.db, run.id, {
+          status: 'running',
+          updatedAt: dependencies.now(),
+        })
+
+        let authHeader: string | undefined
+
+        if (agent.authHeaderEncrypted !== null) {
+          try {
+            authHeader = dependencies.cipher.open(agent.authHeaderEncrypted)
+          } catch (error: unknown) {
+            if (!(error instanceof SecretDecryptionError)) {
+              throw error
+            }
+
+            // The fault is Kelpie's key, not the agent's endpoint. The run
+            // still fails — the dispatch cannot happen — but the reason points
+            // at the key so nobody debugs a healthy agent.
+            dependencies.log.error('agent auth header could not be decrypted', {
+              agentId: agent.id,
+              runId: run.id,
+              error: describeThrown(error),
+            })
+            await settle(run.id, {
+              delivered: false,
+              status: null,
+              reason:
+                'The stored auth header could not be decrypted; check SECRET_ENCRYPTION_KEY, then save the header again',
+            })
+
+            return
+          }
+        }
+
+        const outcome = await dependencies.send({
+          url: agent.endpoint,
+          body: JSON.stringify(dispatchPayload(run, resolved)),
+          headers: {
+            'content-type': 'application/json',
+            ...(authHeader === undefined ? {} : { authorization: authHeader }),
+          },
+        })
+
+        if (!outcome.delivered) {
+          dependencies.log.warn('agent dispatch failed', {
+            agentId: agent.id,
+            runId: run.id,
+            taskId: run.taskId,
+            status: outcome.status,
+            reason: outcome.reason,
+          })
+        }
+
+        await settle(run.id, outcome)
+      } catch (error: unknown) {
+        // The engine's own boundary: `dispatch` promises to settle rather than
+        // reject, because nothing awaits it. Whatever slipped past the paths
+        // above still lands on the run.
+        dependencies.log.error('agent dispatch could not be attempted', {
+          agentId: agent.id,
+          runId: run.id,
+          error: describeThrown(error),
+        })
+
+        try {
+          await settle(run.id, {
+            delivered: false,
+            status: null,
+            reason: describeThrown(error),
+          })
+        } catch (settleError: unknown) {
+          // The settle write itself failed — likely the database. The run is
+          // left `running` and there is nothing sound to write anywhere.
+          dependencies.log.error('agent run could not be settled', {
+            runId: run.id,
+            error: describeThrown(settleError),
+          })
+        }
+      }
+    },
+  }
+}

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

@@ -0,0 +1,79 @@
+import { createSecretCipher, secretEncryptionConfigSchema } from '../../lib/secrets.ts'
+import type { KelpieModule } from '../../runtime/module.ts'
+import { createDispatchEngine, createHttpSender } from './dispatch.ts'
+import type { SendDispatch } from './dispatch.ts'
+import { mountAgentTasksRoutes } from './routes.ts'
+import * as schema from './schema.ts'
+import { createAgentTasksService } from './service.ts'
+
+/**
+ * Agent tasks (`agent-tasks.md`): the task catalog, resolve, run dispatch, and
+ * registered agents.
+ *
+ * `requires` names every module whose tables resolve reads — the dashboard
+ * rule. Nothing here depends on registration order; the list is about a build
+ * that omits one of them, which should fail at boot rather than answer resolve
+ * with a query against an unmigrated table.
+ */
+export interface AgentTasksModuleOptions {
+  /** Injected by tests so no suite makes a network call. */
+  readonly send?: SendDispatch
+}
+
+export function createAgentTasksModule(
+  migrationsDirectory: string,
+  options: AgentTasksModuleOptions = {},
+): KelpieModule {
+  return {
+    id: 'agent-tasks',
+    requires: [
+      'workspace',
+      'people',
+      'companies',
+      'positions',
+      'pipelines',
+      'deals',
+      'opportunities',
+      'partnerships',
+      'raises',
+      'hiring',
+      'plans',
+      'decisions',
+      'notes',
+      'handbook',
+    ],
+
+    register(context) {
+      // 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))
+
+      const engine = createDispatchEngine({
+        db: context.db,
+        now: context.now,
+        cipher,
+        send: options.send ?? createHttpSender(),
+        log: context.log,
+      })
+
+      const service = createAgentTasksService({
+        db: context.db,
+        transaction: context.transaction,
+        createId: context.createId,
+        now: context.now,
+        cipher,
+        engine,
+        log: context.log,
+      })
+
+      context.schema(schema, migrationsDirectory)
+
+      context.routes((router) => {
+        mountAgentTasksRoutes(router, { db: context.db, now: context.now, service })
+      })
+
+      return Promise.resolve()
+    },
+  }
+}

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

@@ -0,0 +1,140 @@
+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.
+ *
+ * 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.
+ */
+
+/** A handbook page the task requires, resolved to this workspace's own copy. */
+export interface HandbookPageReference {
+  readonly slug: string
+  readonly title: string
+  readonly deepLink: string
+}
+
+/** One id list under "Related ids". `truncated` keeps a capped list honest. */
+export interface RelatedIdList {
+  readonly ids: readonly string[]
+  readonly truncated: boolean
+}
+
+/** One sweep bucket under "Workspace signals". `total` is exact; `ids` are capped. */
+export interface WorkspaceSignal {
+  readonly label: string
+  readonly total: number
+  readonly ids: readonly string[]
+}
+
+export interface PromptInputs {
+  readonly workspaceName: string
+  readonly targetLabel: string
+  readonly deepLink: string
+  readonly handbookPages: readonly HandbookPageReference[]
+  readonly pinnedNoteIds: readonly string[]
+  readonly openPlanIds: readonly string[]
+  readonly openDecisionIds: readonly string[]
+  readonly related: Readonly<Record<string, RelatedIdList>>
+  readonly signals: readonly WorkspaceSignal[]
+}
+
+function codeList(ids: readonly string[], empty: string): string {
+  return ids.length > 0 ? ids.map((id) => `\`${id}\``).join(', ') : empty
+}
+
+function handbookLines(pages: readonly HandbookPageReference[]): string {
+  if (pages.length === 0) {
+    return '- (none)'
+  }
+
+  return pages.map((page) => `- \`${page.slug}\` — ${page.title} (\`${page.deepLink}\`)`).join('\n')
+}
+
+function relatedSection(related: Readonly<Record<string, RelatedIdList>>): string {
+  const lines = Object.entries(related)
+    .filter(([, list]) => list.ids.length > 0)
+    .map(([key, list]) => {
+      const suffix = list.truncated ? ` (first ${String(list.ids.length)}; more exist)` : ''
+
+      return `- ${key}${suffix}: ${list.ids.join(', ')}`
+    })
+
+  return lines.length > 0 ? `\n## Related ids\n${lines.join('\n')}\n` : ''
+}
+
+function signalsSection(signals: readonly WorkspaceSignal[]): string {
+  if (signals.length === 0) {
+    return ''
+  }
+
+  const lines = signals.map((signal) => {
+    if (signal.total === 0) {
+      return `- ${signal.label}: none`
+    }
+
+    const shown = signal.ids.join(', ')
+    const suffix = signal.total > signal.ids.length ? ` (first ${String(signal.ids.length)})` : ''
+
+    return `- ${signal.label}: ${String(signal.total)} total — ${shown}${suffix}`
+  })
+
+  return `\n## Workspace signals\n${lines.join('\n')}\n`
+}
+
+/**
+ * The first required read. A workspace task has no single record to load; the
+ * dashboard is the workspace's own context pack, and pointing the agent at the
+ * endpoint keeps the signals live rather than frozen at resolve time.
+ */
+function firstRead(targetType: AgentTaskTargetType): string {
+  if (targetType === 'workspace') {
+    return 'Load the workspace dashboard: `GET /v1/dashboard` (MCP: `dashboard_get`). It carries open pipeline counts, overdue and due-soon Plan items, upcoming partnership touchpoints, stale contacts, and recent activity.'
+  }
+
+  return 'Load the target record and agent fields.'
+}
+
+export function renderPrompt(
+  definition: AgentTaskDefinition,
+  targetType: AgentTaskTargetType,
+  targetId: string,
+  inputs: PromptInputs,
+): 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}
+
+## Target
+- **Type:** \`${targetType}\`
+- **Id:** \`${targetId}\`
+- **Label:** ${inputs.targetLabel}
+- **UI:** ${inputs.deepLink}
+
+## Required reads
+1. ${firstRead(targetType)}
+2. Prefer pinned notes: ${codeList(inputs.pinnedNoteIds, '(none pinned)')}.
+3. Open Plan items: ${codeList(inputs.openPlanIds, '(none)')}.
+4. Open Decisions: ${codeList(inputs.openDecisionIds, '(none)')}.
+5. Handbook pages:
+${handbookLines(inputs.handbookPages)}
+${relatedSection(inputs.related)}${signalsSection(inputs.signals)}
+## Instructions
+${definition.instructions}
+
+## Write policy
+${definition.writePolicy}
+
+## Done when
+You have applied allowed updates via MCP/API (or asked the human when blocked), and summarised what changed.
+`
+}

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

@@ -0,0 +1,152 @@
+import type { AgentRunStatus } from '@kelpie/schemas'
+import { and, eq } from 'drizzle-orm'
+
+import { keysetCondition, orderByWindow, timestampSort } from '../../lib/pagination.ts'
+import type { ListWindow, SortableFields } from '../../lib/pagination.ts'
+import type { Queryable } from '../../runtime/transaction.ts'
+import { agentRegistrations, agentRuns } from './schema.ts'
+
+export type AgentRecord = typeof agentRegistrations.$inferSelect
+export type AgentColumns = typeof agentRegistrations.$inferInsert
+export type RunRecord = typeof agentRuns.$inferSelect
+export type RunColumns = typeof agentRuns.$inferInsert
+
+export const AGENT_SORTS: SortableFields<AgentRecord> = {
+  created_at: timestampSort(agentRegistrations.createdAt, (agent) => agent.createdAt),
+  updated_at: timestampSort(agentRegistrations.updatedAt, (agent) => agent.updatedAt),
+}
+
+export const DEFAULT_AGENT_SORT = '-created_at'
+
+export const RUN_SORTS: SortableFields<RunRecord> = {
+  created_at: timestampSort(agentRuns.createdAt, (run) => run.createdAt),
+}
+
+/** Newest first: a run log is read to find out what just happened. */
+export const DEFAULT_RUN_SORT = '-created_at'
+
+export interface RunFilters {
+  readonly agentId?: string | undefined
+  readonly status?: AgentRunStatus | undefined
+}
+
+export function listAgents(
+  db: Queryable,
+  workspaceId: string,
+  window: ListWindow<AgentRecord>,
+): Promise<AgentRecord[]> {
+  return db
+    .select()
+    .from(agentRegistrations)
+    .where(
+      and(eq(agentRegistrations.workspaceId, workspaceId), keysetCondition(window, agentRegistrations.id)),
+    )
+    .orderBy(...orderByWindow(window, agentRegistrations.id))
+    .limit(window.fetchLimit)
+}
+
+export async function findAgent(
+  db: Queryable,
+  workspaceId: string,
+  id: string,
+): Promise<AgentRecord | undefined> {
+  const [found] = await db
+    .select()
+    .from(agentRegistrations)
+    .where(and(eq(agentRegistrations.workspaceId, workspaceId), eq(agentRegistrations.id, id)))
+    .limit(1)
+
+  return found
+}
+
+export async function insertAgent(db: Queryable, values: AgentColumns): Promise<AgentRecord> {
+  const [created] = await db.insert(agentRegistrations).values(values).returning()
+
+  if (created === undefined) {
+    throw new Error(`Inserting agent registration ${values.id} returned no row`)
+  }
+
+  return created
+}
+
+export async function updateAgent(
+  db: Queryable,
+  workspaceId: string,
+  id: string,
+  changes: Partial<AgentColumns>,
+): Promise<AgentRecord | undefined> {
+  const [updated] = await db
+    .update(agentRegistrations)
+    .set(changes)
+    .where(and(eq(agentRegistrations.workspaceId, workspaceId), eq(agentRegistrations.id, id)))
+    .returning()
+
+  return updated
+}
+
+export async function deleteAgent(db: Queryable, workspaceId: string, id: string): Promise<number> {
+  const deleted = await db
+    .delete(agentRegistrations)
+    .where(and(eq(agentRegistrations.workspaceId, workspaceId), eq(agentRegistrations.id, id)))
+    .returning({ id: agentRegistrations.id })
+
+  return deleted.length
+}
+
+export function listRuns(
+  db: Queryable,
+  workspaceId: string,
+  filters: RunFilters,
+  window: ListWindow<RunRecord>,
+): Promise<RunRecord[]> {
+  return db
+    .select()
+    .from(agentRuns)
+    .where(
+      and(
+        eq(agentRuns.workspaceId, workspaceId),
+        filters.agentId === undefined ? undefined : eq(agentRuns.agentId, filters.agentId),
+        filters.status === undefined ? undefined : eq(agentRuns.status, filters.status),
+        keysetCondition(window, agentRuns.id),
+      ),
+    )
+    .orderBy(...orderByWindow(window, agentRuns.id))
+    .limit(window.fetchLimit)
+}
+
+export async function findRun(
+  db: Queryable,
+  workspaceId: string,
+  id: string,
+): Promise<RunRecord | undefined> {
+  const [found] = await db
+    .select()
+    .from(agentRuns)
+    .where(and(eq(agentRuns.workspaceId, workspaceId), eq(agentRuns.id, id)))
+    .limit(1)
+
+  return found
+}
+
+export async function insertRun(db: Queryable, values: RunColumns): Promise<RunRecord> {
+  const [created] = await db.insert(agentRuns).values(values).returning()
+
+  if (created === undefined) {
+    throw new Error(`Inserting agent run ${values.id} returned no row`)
+  }
+
+  return created
+}
+
+/**
+ * Moves a run through its dispatch lifecycle. By id alone, like the delivery
+ * engine's status write: only the dispatcher calls this, and it holds the row
+ * it just inserted.
+ */
+export async function updateRun(
+  db: Queryable,
+  id: string,
+  changes: Partial<RunColumns>,
+): Promise<void> {
+  await db.update(agentRuns).set(changes).where(eq(agentRuns.id, id))
+}