@onkeiki/agents 0.1.0

package/src/Server.ts

@@ -0,0 +1,618 @@
+import { Effect, Schema, JSONSchema } from 'effect'
+import type { AgentKitConfig } from './types/config.js'
+import type { InboundMessage, DeliveryStatus } from './types/index.js'
+import type { ToolDefinition } from './Tool.js'
+import type { AlertStateService, AlertContext, AlertMedia, AlertDefinition } from './Alert.js'
+import type { UserStateService, SecretsService } from './Tool.js'
+import { mergedAlerts, type ResolvedPlugins } from './Kit.js'
+import type { TurnEvent, TurnResult, RouteContext } from './Plugin.js'
+import type { PluginDbService } from './services/PluginDb.js'
+import type { SandboxHandle, SandboxExecResult } from './services/Sandbox.js'
+import { StorageError } from './services/Storage.js'
+
+/**
+ * HTTP server that receives turn requests from the Orchid platform.
+ *
+ * Routes:
+ * - POST /turn        — Platform sends inbound messages for processing
+ * - POST /delivery    — Platform proxies delivery status webhooks
+ * - POST /events/:type — Platform proxies event webhooks
+ * - GET  /health      — Health check
+ * - ...plugin routes  — Contributed by plugins
+ */
+
+export type TurnRequest = {
+  readonly message: InboundMessage
+  readonly context: {
+    readonly memories: ReadonlyArray<{ content: string; category: string }>
+    readonly history: ReadonlyArray<{ content: string; direction: 'inbound' | 'outbound' }>
+  }
+}
+
+export type TurnResponse = {
+  readonly reply: string
+  readonly media?: { url: string; mimeType: string }
+  readonly toolCalls?: ReadonlyArray<{ name: string; input: unknown; output: unknown }>
+  readonly shouldLearn?: boolean
+}
+
+/** One outbound message produced by an alert run, as returned to the platform. */
+export type AlertDelivery = {
+  readonly phone: string
+  readonly text: string
+  readonly media?: AlertMedia
+  /** Recipient-scoped claim key: the platform skips a delivery whose key was already claimed. */
+  readonly dedupKey?: string
+}
+
+export function createServer(config: AgentKitConfig, resolved: ResolvedPlugins) {
+  const routeCtx: RouteContext = { config, request: null as any }
+
+  return {
+    fetch: async (req: Request): Promise<Response> => {
+      // Run plugin onRequest interceptors
+      for (const onReq of resolved.onRequest) {
+        const result = await Effect.runPromise(onReq(req).pipe(Effect.orDie))
+        if (result instanceof Response) return result
+        if (result instanceof Request) req = result
+      }
+
+      // Run plugin middleware
+      for (const mw of resolved.middleware) {
+        const url = new URL(req.url)
+        if (url.pathname.startsWith(mw.path)) {
+          const mwResult = await Effect.runPromise(
+            mw.handler(req, { ...routeCtx, request: req }).pipe(Effect.orDie)
+          )
+          if (mwResult instanceof Response) return mwResult
+        }
+      }
+
+      const url = new URL(req.url)
+
+      // Check plugin routes first
+      const pluginRoute = resolved.routes[url.pathname]
+      if (pluginRoute) {
+        const response = await pluginRoute(req, { ...routeCtx, request: req })
+        return applyOnResponse(response, resolved)
+      }
+
+      let response: Response
+      switch (url.pathname) {
+        case '/health':
+          response = new Response(JSON.stringify({ status: 'ok', version: '0.1.0' }), {
+            headers: { 'Content-Type': 'application/json' },
+          })
+          break
+
+        case '/turn':
+          response = await handleTurn(req, config, resolved)
+          break
+
+        case '/alerts/execute':
+          response = await handleAlertExecute(req, config, resolved)
+          break
+
+        case '/delivery':
+          response = await handleDelivery(req, config)
+          break
+
+        default:
+          if (url.pathname.startsWith('/events/')) {
+            response = await handleEvent(req, config, url.pathname.slice(8))
+          } else {
+            response = new Response('Not found', { status: 404 })
+          }
+      }
+
+      return applyOnResponse(response, resolved)
+    },
+  }
+}
+
+async function applyOnResponse(res: Response, resolved: ResolvedPlugins): Promise<Response> {
+  for (const onRes of resolved.onResponse) {
+    res = await Effect.runPromise(onRes(res).pipe(Effect.orDie))
+  }
+  return res
+}
+
+async function handleTurn(req: Request, config: AgentKitConfig, resolved: ResolvedPlugins): Promise<Response> {
+  const authHeader = req.headers.get('Authorization')
+  const isPlatformForward = req.headers.get('X-Orchid-Platform') === 'true'
+  if (!isPlatformForward && (!authHeader?.startsWith('Bearer ') || authHeader.slice(7) !== config.apiKey)) {
+    return new Response('Unauthorized', { status: 401 })
+  }
+
+  const body = (await req.json()) as TurnRequest
+
+  // Run beforeTurn hooks
+  let turnEvent: TurnEvent = {
+    phone: body.message.phone,
+    messages: [
+      ...body.context.history.map((h) => ({ content: h.content, direction: h.direction })),
+      { content: body.message.text, direction: 'inbound' as const },
+    ],
+    context: {},
+  }
+  for (const hook of resolved.hooks.beforeTurn) {
+    turnEvent = await Effect.runPromise(hook(turnEvent).pipe(Effect.orDie))
+  }
+
+  const startTime = Date.now()
+  const result = await Effect.runPromise(runAgentTurn(config, body, resolved))
+
+  // Run afterTurn hooks
+  const turnResult: TurnResult = {
+    phone: body.message.phone,
+    response: result.reply,
+    toolCalls: result.toolCalls ?? [],
+    tokensUsed: { in: (result as any).tokensIn ?? 0, out: (result as any).tokensOut ?? 0 },
+    durationMs: Date.now() - startTime,
+  }
+  for (const hook of resolved.hooks.afterTurn) {
+    await Effect.runPromise(hook(turnResult).pipe(Effect.orDie))
+  }
+
+  return new Response(JSON.stringify(result), {
+    headers: { 'Content-Type': 'application/json' },
+  })
+}
+
+async function handleAlertExecute(
+  req: Request,
+  config: AgentKitConfig,
+  resolved: ResolvedPlugins
+): Promise<Response> {
+  const isPlatformForward = req.headers.get('X-Orchid-Platform') === 'true'
+  if (!isPlatformForward) return new Response('Unauthorized', { status: 401 })
+
+  const body = await req.json() as AlertExecuteBody
+  const alert = mergedAlerts(config, resolved).find((a) => a.name === body.alertName)
+  if (!alert) return new Response(`Alert not found: ${body.alertName}`, { status: 404 })
+
+  const pluginDb = config.storage && 'pluginDb' in config.storage ? config.storage.pluginDb : undefined
+  const result = await executeAlert(alert, body, pluginDb)
+
+  return new Response(JSON.stringify(result), {
+    headers: { 'Content-Type': 'application/json' },
+  })
+}
+
+export type AlertExecuteBody = {
+  alertName: string
+  subscribers: Array<{ phone: string; preferences?: Record<string, unknown> }>
+  secrets?: Record<string, string>
+}
+
+/**
+ * Run one alert against its subscribers and flatten the results into ordered
+ * {@link AlertDelivery} entries. Shared by the built-in `/alerts/execute`
+ * route and the alerts plugin, so the two paths cannot diverge.
+ */
+export async function executeAlert(
+  alert: AlertDefinition,
+  body: AlertExecuteBody,
+  pluginDb?: PluginDbService
+): Promise<{ sent: number; skipped: number; deliveries: AlertDelivery[] }> {
+  let sent = 0
+  let skipped = 0
+  const deliveries: AlertDelivery[] = []
+
+  for (const subscriber of body.subscribers ?? []) {
+    const ctx: AlertContext = {
+      subscriber: {
+        phone: subscriber.phone,
+        chatId: `sdk-alert:${subscriber.phone}`,
+        preferences: subscriber.preferences ?? {},
+      },
+      now: new Date(),
+      secrets: body.secrets ?? {},
+      state: makeAlertState(pluginDb, body.alertName, subscriber.phone),
+    }
+
+    const ok = alert.shouldSend ? await Effect.runPromise(alert.shouldSend(ctx)) : true
+    if (!ok) {
+      skipped++
+      continue
+    }
+
+    const content = await Effect.runPromise(alert.generate(ctx))
+    if (!content || (!content.text && !content.media && !(content.messages?.length))) {
+      skipped++
+      continue
+    }
+
+    sent++
+    const subscriberDeliveries: AlertDelivery[] = []
+    if (content.text || content.media) {
+      subscriberDeliveries.push({ phone: subscriber.phone, text: content.text, media: content.media })
+    }
+    for (const extra of content.messages ?? []) {
+      if (!extra.text && !(extra.media?.length)) continue
+      subscriberDeliveries.push({ phone: subscriber.phone, text: extra.text, media: extra.media?.[0] })
+      for (const m of extra.media?.slice(1) ?? []) {
+        subscriberDeliveries.push({ phone: subscriber.phone, text: '', media: m })
+      }
+    }
+    // The claim key rides on the first delivery that will actually be sent,
+    // so a content shape with an empty primary message still gets claimed.
+    const dedupKey = alert.dedupKey?.(ctx)
+    if (dedupKey && subscriberDeliveries[0]) {
+      subscriberDeliveries[0] = { ...subscriberDeliveries[0], dedupKey }
+    }
+    deliveries.push(...subscriberDeliveries)
+  }
+
+  return { sent, skipped, deliveries }
+}
+
+async function handleDelivery(req: Request, config: AgentKitConfig): Promise<Response> {
+  const body = (await req.json()) as DeliveryStatus
+  if (config.events?.onDeliveryStatus) {
+    await Effect.runPromise(config.events.onDeliveryStatus(body))
+  }
+  return new Response('ok')
+}
+
+async function handleEvent(req: Request, config: AgentKitConfig, eventType: string): Promise<Response> {
+  const body = await req.json()
+
+  switch (eventType) {
+    case 'new-user':
+      if (config.events?.onNewUser) {
+        await Effect.runPromise(config.events.onNewUser(body))
+      }
+      break
+    case 'opt-out':
+      if (config.events?.onOptOut) {
+        await Effect.runPromise(config.events.onOptOut(body))
+      }
+      break
+  }
+
+  return new Response('ok')
+}
+
+const OPENROUTER_API_KEY = process.env.OPENROUTER_API_KEY ?? ''
+const OPENROUTER_BASE_URL = 'https://openrouter.ai/api/v1'
+
+/** Most reply-review rejections ({@link TurnHooks.reviewReply}) honored per turn. */
+const MAX_REPLY_REVIEW_RETRIES = 2
+
+type LLMMessage = {
+  role: string
+  content?: string | null
+  tool_calls?: Array<{ id: string; type: 'function'; function: { name: string; arguments: string } }>
+  tool_call_id?: string
+}
+
+function runAgentTurn(config: AgentKitConfig, turn: TurnRequest, resolved: ResolvedPlugins): Effect.Effect<TurnResponse> {
+  return Effect.tryPromise({
+    try: async () => {
+      const promptCtx = {
+        user: { phone: turn.message.phone, timezone: null, currency: null, metadata: {}, firstSeenAt: new Date() },
+        now: new Date(),
+        phone: turn.message.phone,
+        context: {
+          memorySummary: turn.context.memories.map((m) => `[${m.category}] ${m.content}`).join('\n') || null,
+          relevantFacts: turn.context.memories.map((m) => ({ fact: m.content, category: m.category })),
+        },
+        isFirstInteraction: turn.context.history.length === 0,
+        history: turn.context.history,
+      }
+      const hooks = config.agent.hooks
+      const finishReply = (reply: string) =>
+        hooks?.transformReply ? hooks.transformReply(reply, promptCtx) : reply
+
+      const systemPrompt = config.agent.systemPrompt(promptCtx)
+
+      // Merge agent tools + plugin tools
+      const allTools = [...config.agent.tools, ...resolved.tools]
+
+      // Convert SDK tools to OpenAI format
+      const openaiTools = allTools.map((t) => ({
+        type: 'function' as const,
+        function: {
+          name: t.name,
+          description: t.description,
+          parameters: JSONSchema.make(t.input),
+        },
+      }))
+
+      // Build LLM messages
+      const llmMessages: LLMMessage[] = [
+        { role: 'system', content: systemPrompt },
+        ...turn.context.history.map((h) => ({
+          role: h.direction === 'inbound' ? 'user' : 'assistant',
+          content: h.content,
+        })),
+        { role: 'user', content: turn.message.text },
+      ]
+
+      const model = config.agent.model.startsWith('openrouter/')
+        ? config.agent.model.slice('openrouter/'.length)
+        : config.agent.model
+
+      // Agentic loop
+      let totalTokensIn = 0
+      let totalTokensOut = 0
+      let lastToolName: string | undefined
+      let lastToolError: string | undefined
+      let lastToolInput: string | undefined
+      let identicalFailureStreak = 0
+      let stoppedByHook = false
+      let reviewAttempts = 0
+      const rejectedReplies = new Set<string>()
+      const toolCallResults: Array<{ name: string; input: unknown; output: unknown }> = []
+
+      for (let step = 0; step < config.agent.maxSteps; step++) {
+        const hookState = { step, toolCalls: toolCallResults.length, lastToolName, lastToolError, lastToolInput, identicalFailureStreak }
+        const prepared = hooks?.prepareStep?.(hookState, promptCtx)
+        const stepMessages = prepared?.appendSystem
+          ? [...llmMessages, { role: 'system', content: prepared.appendSystem }]
+          : llmMessages
+        const body: Record<string, unknown> = {
+          model,
+          messages: stepMessages,
+          reasoning: { effort: 'low', exclude: true },
+        }
+        if (openaiTools.length > 0) body.tools = openaiTools
+
+        const res = await fetch(`${OPENROUTER_BASE_URL}/chat/completions`, {
+          method: 'POST',
+          headers: {
+            'Authorization': `Bearer ${OPENROUTER_API_KEY}`,
+            'Content-Type': 'application/json',
+            'HTTP-Referer': 'https://onkeiki.com',
+            'X-Title': 'Keiki SDK',
+          },
+          body: JSON.stringify(body),
+        })
+
+        if (!res.ok) throw new Error(`OpenRouter ${res.status}: ${await res.text()}`)
+
+        const data = await res.json() as {
+          choices: Array<{ message: { content?: string | null; tool_calls?: Array<{ id: string; type: 'function'; function: { name: string; arguments: string } }> } }>
+          usage?: { prompt_tokens: number; completion_tokens: number }
+        }
+
+        totalTokensIn += data.usage?.prompt_tokens ?? 0
+        totalTokensOut += data.usage?.completion_tokens ?? 0
+
+        const msg = data.choices?.[0]?.message
+        if (!msg) throw new Error('No response from LLM')
+
+        // No tool calls — final response. Review gates the delivered
+        // (post-transformReply) text and fails closed: a rejected candidate is
+        // never delivered, even when retries run out.
+        if (!msg.tool_calls || msg.tool_calls.length === 0) {
+          const candidate = finishReply(msg.content ?? '')
+          const review = hooks?.reviewReply?.(candidate, promptCtx, { toolResults: toolCallResults, attempt: reviewAttempts })
+          if (review?.retryWith) {
+            rejectedReplies.add(msg.content ?? '')
+            if (reviewAttempts < MAX_REPLY_REVIEW_RETRIES) {
+              reviewAttempts++
+              llmMessages.push({ role: 'assistant', content: msg.content ?? '' })
+              llmMessages.push({ role: 'system', content: review.retryWith })
+              continue
+            }
+            return {
+              reply: '',
+              toolCalls: toolCallResults.length > 0 ? toolCallResults : undefined,
+              shouldLearn: config.agent.memory?.enabled ?? false,
+              tokensIn: totalTokensIn,
+              tokensOut: totalTokensOut,
+            } as TurnResponse
+          }
+          return {
+            reply: candidate,
+            toolCalls: toolCallResults.length > 0 ? toolCallResults : undefined,
+            shouldLearn: config.agent.memory?.enabled ?? false,
+            tokensIn: totalTokensIn,
+            tokensOut: totalTokensOut,
+          } as TurnResponse
+        }
+
+        // Add assistant message with tool_calls
+        llmMessages.push({
+          role: 'assistant',
+          content: msg.content || null,
+          tool_calls: msg.tool_calls,
+        })
+
+        // Execute each tool call via Effect
+        for (const toolCall of msg.tool_calls) {
+          const toolDef = allTools.find((t) => t.name === toolCall.function.name)
+          if (!toolDef) {
+            llmMessages.push({ role: 'tool', tool_call_id: toolCall.id, content: `Error: Unknown tool ${toolCall.function.name}` })
+            continue
+          }
+
+          // Run beforeToolCall hooks
+          let toolCallEvent = { phone: turn.message.phone, toolName: toolCall.function.name, input: null as unknown }
+          for (const hook of resolved.hooks.beforeToolCall) {
+            toolCallEvent = await Effect.runPromise(hook(toolCallEvent).pipe(Effect.orDie))
+          }
+
+          const toolStart = Date.now()
+          try {
+            const args = JSON.parse(toolCall.function.arguments)
+            toolCallEvent.input = args
+            const decoded = Schema.decodeUnknownSync(toolDef.input)(args)
+            const result = await Effect.runPromise(
+              (toolDef.execute as (input: any, ctx: any) => Effect.Effect<any>)(decoded, {
+                phone: turn.message.phone,
+                user: promptCtx.user,
+                blackboard: {} as any,
+                platform: {} as any,
+                userState: makeNoopUserState(),
+                secrets: makeNoopSecrets(),
+                db: (config.storage && 'pluginDb' in config.storage ? config.storage.pluginDb : undefined) ?? makeNoopPluginDb(),
+                sandbox: makeNoopSandbox(),
+              })
+            )
+            const resultStr = typeof result === 'string' ? result : JSON.stringify(result)
+            toolCallResults.push({ name: toolCall.function.name, input: args, output: result })
+            lastToolName = toolCall.function.name
+            lastToolError = undefined
+            lastToolInput = toolCall.function.arguments
+            identicalFailureStreak = 0
+            llmMessages.push({ role: 'tool', tool_call_id: toolCall.id, content: resultStr })
+
+            // Run afterToolCall hooks
+            for (const hook of resolved.hooks.afterToolCall) {
+              await Effect.runPromise(hook({
+                phone: turn.message.phone,
+                toolName: toolCall.function.name,
+                input: args,
+                output: result,
+                durationMs: Date.now() - toolStart,
+              }).pipe(Effect.orDie))
+            }
+          } catch (err) {
+            const errStr = `Error: ${err instanceof Error ? err.message : String(err)}`
+            llmMessages.push({ role: 'tool', tool_call_id: toolCall.id, content: errStr })
+            const sameFailure =
+              lastToolName === toolCall.function.name &&
+              lastToolInput === toolCall.function.arguments &&
+              lastToolError === errStr
+            identicalFailureStreak = sameFailure ? identicalFailureStreak + 1 : 1
+            lastToolName = toolCall.function.name
+            lastToolError = errStr
+            lastToolInput = toolCall.function.arguments
+
+            // Run afterToolCall hooks with error
+            for (const hook of resolved.hooks.afterToolCall) {
+              await Effect.runPromise(hook({
+                phone: turn.message.phone,
+                toolName: toolCall.function.name,
+                input: toolCallEvent.input,
+                output: null,
+                durationMs: Date.now() - toolStart,
+                error: errStr,
+              }).pipe(Effect.orDie))
+            }
+          }
+        }
+
+        // Developer stop condition: end the turn with the last assistant text.
+        if (hooks?.stopWhen?.({ step, toolCalls: toolCallResults.length, lastToolName, lastToolError, lastToolInput, identicalFailureStreak }, promptCtx)) {
+          stoppedByHook = true
+          break
+        }
+      }
+
+      // Loop ended without a tool-free reply: use the last assistant text the
+      // model produced. Only real step exhaustion gets the apology — a
+      // developer stop condition is intentional and must not read as a failure.
+      const lastAssistantText = llmMessages
+        .filter((m) => m.role === 'assistant' && typeof m.content === 'string' && m.content && !rejectedReplies.has(m.content))
+        .pop()?.content as string | undefined
+      return {
+        reply: finishReply(lastAssistantText ?? (stoppedByHook ? '' : 'I apologize, I ran out of steps processing your request.')),
+        toolCalls: toolCallResults.length > 0 ? toolCallResults : undefined,
+        shouldLearn: config.agent.memory?.enabled ?? false,
+        tokensIn: totalTokensIn,
+        tokensOut: totalTokensOut,
+      } as TurnResponse
+    },
+    catch: (e) => e as Error,
+  }).pipe(Effect.orDie)
+}
+
+/** Whether the durable alert-state table has been ensured this process. */
+let alertStateTableEnsured = false
+
+/**
+ * Durable per-(alert, subscriber) KV state, persisted through the configured
+ * PluginDb. Falls back to per-run in-memory state when no PluginDb is
+ * configured, so alerts still run (just without cross-run durability).
+ */
+function makeAlertState(pluginDb: PluginDbService | undefined, alertName: string, phone: string): AlertStateService {
+  if (!pluginDb) {
+    const mem = new Map<string, unknown>()
+    return {
+      get: (key) => Effect.succeed(mem.get(key) ?? null),
+      set: (key, value) => Effect.sync(() => { mem.set(key, value) }),
+    }
+  }
+
+  const ensureTable = Effect.suspend(() => {
+    if (alertStateTableEnsured) return Effect.void
+    return pluginDb.execute(
+      `CREATE TABLE IF NOT EXISTS smskit_alert_state (
+        alert_name TEXT NOT NULL,
+        phone TEXT NOT NULL,
+        key TEXT NOT NULL,
+        value JSONB,
+        updated_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+        PRIMARY KEY (alert_name, phone, key)
+      )`
+    ).pipe(
+      Effect.tap(() => Effect.sync(() => { alertStateTableEnsured = true })),
+      // Concurrent CREATE TABLE IF NOT EXISTS can race itself in Postgres
+      // (duplicate-relation error); the table exists either way, so swallow
+      // the DDL failure and let the actual read/write surface real errors.
+      Effect.catchAll(() => Effect.void)
+    )
+  })
+
+  return {
+    get: (key) =>
+      ensureTable.pipe(
+        Effect.andThen(pluginDb.queryOne<{ value: unknown }>(
+          `SELECT value FROM smskit_alert_state WHERE alert_name = $1 AND phone = $2 AND key = $3`,
+          [alertName, phone, key]
+        )),
+        Effect.map((row) => row?.value ?? null),
+        Effect.orDie
+      ),
+    set: (key, value) =>
+      ensureTable.pipe(
+        Effect.andThen(pluginDb.execute(
+          `INSERT INTO smskit_alert_state (alert_name, phone, key, value, updated_at)
+           VALUES ($1, $2, $3, $4, now())
+           ON CONFLICT (alert_name, phone, key) DO UPDATE SET value = EXCLUDED.value, updated_at = now()`,
+          [alertName, phone, key, JSON.stringify(value ?? null)]
+        )),
+        Effect.orDie
+      ),
+  }
+}
+
+function makeNoopUserState(): UserStateService {
+  const store = new Map<string, unknown>()
+  return {
+    get: (key) => Effect.succeed(store.get(key) ?? null),
+    set: (key, value) => Effect.sync(() => { store.set(key, value) }),
+    delete: (key) => Effect.succeed(store.delete(key)),
+    getAll: () => Effect.succeed(Object.fromEntries(store)),
+    setMany: (entries) => Effect.sync(() => { for (const [k, v] of Object.entries(entries)) store.set(k, v) }),
+  }
+}
+
+function makeNoopSecrets(): SecretsService {
+  return {
+    get: () => Effect.succeed(null),
+    getAll: () => Effect.succeed({}),
+  }
+}
+
+function makeNoopPluginDb(): PluginDbService {
+  const err = new StorageError('PluginDb not configured. Use PostgresStorage() instead of PostgresStorageLive().')
+  return {
+    query: () => Effect.fail(err),
+    queryOne: () => Effect.fail(err),
+    execute: () => Effect.fail(err),
+  }
+}
+
+function makeNoopSandbox(): SandboxHandle {
+  const err = () => { throw new Error('SandboxProvider not configured. Enable the Sandbox capability via the sandbox() plugin.') }
+  return {
+    exec: err as () => Promise<SandboxExecResult>,
+    getPublicUrl: err as () => Promise<string>,
+    getHomeDir: err as () => Promise<string>,
+  }
+}