@onkeiki/agents 0.1.0

package/src/services/Observability.ts

@@ -0,0 +1,320 @@
+/**
+ * Observability Service
+ *
+ * Allows developers to export turn traces to external providers:
+ * - Braintrust (AI-specific tracing, evals, scoring)
+ * - Axiom (structured log ingestion)
+ * - Generic OTEL (any OpenTelemetry-compatible backend)
+ * - Custom (developer-provided exporter function)
+ *
+ * The platform always records traces internally (14-day retention).
+ * This service ADDITIONALLY exports to the developer's chosen provider.
+ */
+import { Effect, Context } from 'effect'
+
+// --- Types ---
+
+export type SpanKind = 'llm' | 'tool' | 'retrieval' | 'generation' | 'internal'
+export type SpanStatus = 'running' | 'completed' | 'error'
+
+export type TraceEvent = {
+  traceId: string
+  apiKey: string
+  phone: string
+  startedAt: Date
+  endedAt?: Date
+  durationMs?: number
+  status: SpanStatus
+  model?: string
+  tokensIn: number
+  tokensOut: number
+  totalSteps: number
+  error?: string
+  metadata: Record<string, unknown>
+  spans: SpanEvent[]
+}
+
+export type SpanEvent = {
+  spanId: string
+  traceId: string
+  parentSpanId?: string
+  name: string
+  kind: SpanKind
+  startedAt: Date
+  endedAt?: Date
+  durationMs?: number
+  status: SpanStatus
+  input?: unknown
+  output?: unknown
+  error?: string
+  metadata: Record<string, unknown>
+}
+
+// --- Exporter Interface ---
+
+export type TraceExporter = {
+  name: string
+  exportTrace: (trace: TraceEvent) => Effect.Effect<void, ObservabilityError>
+  flush?: () => Effect.Effect<void, ObservabilityError>
+  shutdown?: () => Effect.Effect<void, ObservabilityError>
+}
+
+export class ObservabilityError {
+  readonly _tag = 'ObservabilityError'
+  constructor(readonly provider: string, readonly message: string, readonly cause?: unknown) {}
+}
+
+// --- Service Tag ---
+
+export class Observability extends Context.Tag('Observability')<
+  Observability,
+  { exporters: TraceExporter[] }
+>() {}
+
+// --- Provider Factories ---
+
+/**
+ * Braintrust exporter.
+ * Sends traces as Braintrust spans for AI observability, evals, and scoring.
+ */
+export function braintrustExporter(config: {
+  apiKey: string
+  projectName: string
+  baseUrl?: string
+}): TraceExporter {
+  const baseUrl = config.baseUrl ?? 'https://api.braintrust.dev'
+
+  return {
+    name: 'braintrust',
+    exportTrace: (trace) =>
+      Effect.tryPromise({
+        try: async () => {
+          const spans = trace.spans.map((span) => ({
+            id: span.spanId,
+            span_id: span.spanId,
+            root_span_id: trace.traceId,
+            parent_id: span.parentSpanId,
+            name: span.name,
+            kind: mapSpanKindToBraintrust(span.kind),
+            start_time: span.startedAt.toISOString(),
+            end_time: span.endedAt?.toISOString(),
+            status_code: span.status === 'error' ? 'ERROR' : 'OK',
+            input: span.input,
+            output: span.output,
+            error: span.error,
+            metadata: {
+              ...span.metadata,
+              kind: span.kind,
+              phone: trace.phone,
+            },
+            metrics: span.kind === 'llm' ? {
+              tokens: (trace.tokensIn + trace.tokensOut) || undefined,
+              prompt_tokens: trace.tokensIn || undefined,
+              completion_tokens: trace.tokensOut || undefined,
+            } : undefined,
+          }))
+
+          const res = await fetch(`${baseUrl}/v1/project_logs/${encodeURIComponent(config.projectName)}/insert`, {
+            method: 'POST',
+            headers: {
+              'Authorization': `Bearer ${config.apiKey}`,
+              'Content-Type': 'application/json',
+            },
+            body: JSON.stringify({ events: spans }),
+          })
+
+          if (!res.ok) {
+            throw new Error(`Braintrust export failed: ${res.status} ${await res.text()}`)
+          }
+        },
+        catch: (err) => new ObservabilityError('braintrust', String(err), err),
+      }),
+  }
+}
+
+/**
+ * Axiom exporter.
+ * Sends traces as structured events to an Axiom dataset.
+ */
+export function axiomExporter(config: {
+  apiToken: string
+  dataset: string
+  orgId?: string
+  baseUrl?: string
+}): TraceExporter {
+  const baseUrl = config.baseUrl ?? 'https://api.axiom.co'
+
+  return {
+    name: 'axiom',
+    exportTrace: (trace) =>
+      Effect.tryPromise({
+        try: async () => {
+          // Flatten trace + spans into Axiom events
+          const events = [
+            // Root trace event
+            {
+              _time: trace.startedAt.toISOString(),
+              type: 'trace',
+              traceId: trace.traceId,
+              apiKey: trace.apiKey,
+              phone: trace.phone,
+              model: trace.model,
+              status: trace.status,
+              durationMs: trace.durationMs,
+              tokensIn: trace.tokensIn,
+              tokensOut: trace.tokensOut,
+              totalSteps: trace.totalSteps,
+              error: trace.error,
+              ...trace.metadata,
+            },
+            // Individual span events
+            ...trace.spans.map((span) => ({
+              _time: span.startedAt.toISOString(),
+              type: 'span',
+              traceId: span.traceId,
+              spanId: span.spanId,
+              parentSpanId: span.parentSpanId,
+              name: span.name,
+              kind: span.kind,
+              status: span.status,
+              durationMs: span.durationMs,
+              error: span.error,
+              ...span.metadata,
+            })),
+          ]
+
+          const res = await fetch(`${baseUrl}/v1/datasets/${config.dataset}/ingest`, {
+            method: 'POST',
+            headers: {
+              'Authorization': `Bearer ${config.apiToken}`,
+              'Content-Type': 'application/json',
+              ...(config.orgId ? { 'X-Axiom-Org-Id': config.orgId } : {}),
+            },
+            body: JSON.stringify(events),
+          })
+
+          if (!res.ok) {
+            throw new Error(`Axiom export failed: ${res.status} ${await res.text()}`)
+          }
+        },
+        catch: (err) => new ObservabilityError('axiom', String(err), err),
+      }),
+  }
+}
+
+/**
+ * OpenTelemetry (OTLP) exporter.
+ * Sends traces via OTLP/HTTP (JSON) to any OTEL-compatible backend
+ * (Grafana Tempo, Jaeger, Honeycomb, Datadog, etc.)
+ */
+export function otelExporter(config: {
+  endpoint: string
+  headers?: Record<string, string>
+  serviceName?: string
+}): TraceExporter {
+  const serviceName = config.serviceName ?? 'orchid-sms-agent'
+
+  return {
+    name: 'otel',
+    exportTrace: (trace) =>
+      Effect.tryPromise({
+        try: async () => {
+          const resourceSpans = [{
+            resource: {
+              attributes: [
+                { key: 'service.name', value: { stringValue: serviceName } },
+                { key: 'orchid.api_key', value: { stringValue: trace.apiKey } },
+              ],
+            },
+            scopeSpans: [{
+              scope: { name: 'orchid-agents', version: '0.1.0' },
+              spans: trace.spans.map((span) => ({
+                traceId: hexToBase64(trace.traceId),
+                spanId: hexToBase64(span.spanId.replace(/-/g, '').slice(0, 16)),
+                parentSpanId: span.parentSpanId ? hexToBase64(span.parentSpanId.replace(/-/g, '').slice(0, 16)) : undefined,
+                name: span.name,
+                kind: mapSpanKindToOtel(span.kind),
+                startTimeUnixNano: String(span.startedAt.getTime() * 1_000_000),
+                endTimeUnixNano: span.endedAt ? String(span.endedAt.getTime() * 1_000_000) : undefined,
+                status: {
+                  code: span.status === 'error' ? 2 : 1,
+                  message: span.error,
+                },
+                attributes: [
+                  { key: 'orchid.span.kind', value: { stringValue: span.kind } },
+                  { key: 'orchid.phone', value: { stringValue: trace.phone } },
+                  ...(span.kind === 'llm' ? [
+                    { key: 'gen_ai.system', value: { stringValue: 'orchid' } },
+                    { key: 'gen_ai.request.model', value: { stringValue: trace.model ?? '' } },
+                    { key: 'gen_ai.usage.prompt_tokens', value: { intValue: String(trace.tokensIn) } },
+                    { key: 'gen_ai.usage.completion_tokens', value: { intValue: String(trace.tokensOut) } },
+                  ] : []),
+                ],
+              })),
+            }],
+          }]
+
+          const res = await fetch(`${config.endpoint}/v1/traces`, {
+            method: 'POST',
+            headers: {
+              'Content-Type': 'application/json',
+              ...config.headers,
+            },
+            body: JSON.stringify({ resourceSpans }),
+          })
+
+          if (!res.ok) {
+            throw new Error(`OTEL export failed: ${res.status} ${await res.text()}`)
+          }
+        },
+        catch: (err) => new ObservabilityError('otel', String(err), err),
+      }),
+  }
+}
+
+/**
+ * Custom exporter — developer provides their own export function.
+ */
+export function customExporter(config: {
+  name: string
+  exportFn: (trace: TraceEvent) => Promise<void>
+}): TraceExporter {
+  return {
+    name: config.name,
+    exportTrace: (trace) =>
+      Effect.tryPromise({
+        try: () => config.exportFn(trace),
+        catch: (err) => new ObservabilityError(config.name, String(err), err),
+      }),
+  }
+}
+
+// --- Helpers ---
+
+function mapSpanKindToBraintrust(kind: SpanKind): string {
+  switch (kind) {
+    case 'llm': return 'llm'
+    case 'tool': return 'tool'
+    case 'retrieval': return 'retrieval'
+    case 'generation': return 'generation'
+    default: return 'task'
+  }
+}
+
+function mapSpanKindToOtel(kind: SpanKind): number {
+  switch (kind) {
+    case 'llm': return 3 // CLIENT
+    case 'tool': return 3 // CLIENT
+    case 'retrieval': return 3 // CLIENT
+    case 'internal': return 1 // INTERNAL
+    default: return 0 // UNSPECIFIED
+  }
+}
+
+function hexToBase64(hex: string): string {
+  const bytes = new Uint8Array(hex.length / 2)
+  for (let i = 0; i < hex.length; i += 2) {
+    bytes[i / 2] = parseInt(hex.slice(i, i + 2), 16)
+  }
+  return btoa(String.fromCharCode(...bytes))
+}

package/src/services/Platform.ts

@@ -0,0 +1,125 @@
+import { Context, Effect } from 'effect'
+
+export class PlatformError {
+  readonly _tag = 'PlatformError'
+  constructor(readonly message: string, readonly cause?: unknown) {}
+}
+
+/**
+ * Platform client — communicates with the Orchid platform API
+ * to access managed services (memory, browser, sandbox, etc.)
+ */
+
+export type MemoryFact = {
+  readonly id: string
+  readonly content: string
+  readonly category: string
+  readonly createdAt: Date
+}
+
+export type BrowseResult = {
+  readonly sessionId: string
+  readonly url: string
+  readonly screenshot?: string
+  readonly content?: string
+}
+
+export type SandboxExecResult = {
+  readonly stdout: string
+  readonly stderr: string
+  readonly exitCode: number
+  readonly files?: ReadonlyArray<{ path: string; url: string }>
+}
+
+export type HandoffResult = {
+  readonly handoffUrl: string
+  readonly sessionId: string
+  readonly status: 'waiting' | 'completed' | 'expired'
+}
+
+export type EscalationResult = {
+  readonly escalationId: string
+  readonly routedTo: string
+  readonly status: 'pending' | 'acknowledged' | 'resolved'
+}
+
+export type BackgroundJobResult = {
+  readonly jobId: string
+  readonly status: 'queued' | 'running' | 'completed' | 'failed'
+  readonly result?: unknown
+}
+
+export interface PlatformService {
+  // Memory (Supermemory)
+  readonly memoryRecall: (phone: string, query: string, opts?: {
+    categories?: ReadonlyArray<string>
+    limit?: number
+  }) => Effect.Effect<ReadonlyArray<MemoryFact>, PlatformError>
+
+  readonly memoryLearn: (phone: string, facts: ReadonlyArray<{
+    content: string
+    category: string
+  }>) => Effect.Effect<void, PlatformError>
+
+  // Browser (Browserbase)
+  readonly browse: (instruction: string, opts?: {
+    sessionId?: string
+    screenshot?: boolean
+  }) => Effect.Effect<BrowseResult, PlatformError>
+
+  readonly handoff: (opts: {
+    phone: string
+    instruction: string
+    url?: string
+    timeoutMinutes?: number
+  }) => Effect.Effect<HandoffResult, PlatformError>
+
+  // Sandbox (Code execution)
+  readonly exec: (command: string, opts?: {
+    phone?: string
+    persistent?: boolean
+    timeout?: number
+  }) => Effect.Effect<SandboxExecResult, PlatformError>
+
+  readonly writeFile: (path: string, content: string, opts?: {
+    phone?: string
+  }) => Effect.Effect<void, PlatformError>
+
+  readonly readFile: (path: string, opts?: {
+    phone?: string
+  }) => Effect.Effect<string, PlatformError>
+
+  // Executor (Background jobs)
+  readonly runJob: (opts: {
+    name: string
+    command: string
+    phone?: string
+    timeout?: number
+  }) => Effect.Effect<BackgroundJobResult, PlatformError>
+
+  readonly getJobStatus: (jobId: string) => Effect.Effect<BackgroundJobResult, PlatformError>
+
+  // Escalation
+  readonly escalate: (opts: {
+    phone: string
+    reason: string
+    context?: string
+    routes?: { webhook?: string; slack?: { channel: string }; email?: string }
+  }) => Effect.Effect<EscalationResult, PlatformError>
+
+  // Background learning
+  readonly extractFacts: (phone: string, messages: ReadonlyArray<{
+    content: string
+    direction: 'inbound' | 'outbound'
+  }>) => Effect.Effect<ReadonlyArray<{ content: string; category: string }>, PlatformError>
+
+  // Media processing
+  readonly transcribeAudio: (url: string) => Effect.Effect<string, PlatformError>
+  readonly describeImage: (url: string, prompt?: string) => Effect.Effect<string, PlatformError>
+  readonly extractDocument: (url: string) => Effect.Effect<string, PlatformError>
+}
+
+export class Platform extends Context.Tag('@onkeiki/agents/Platform')<
+  Platform,
+  PlatformService
+>() {}

package/src/services/PluginDb.ts

@@ -0,0 +1,48 @@
+import { Context, Effect } from 'effect'
+import { StorageError } from './Storage.js'
+
+/**
+ * Generic query interface for plugins that need their own persistence.
+ *
+ * Provided by the active storage adapter (Postgres, MongoDB, etc.) so
+ * plugins can create and query their own tables/collections without
+ * extending the core `StorageService` interface.
+ *
+ * The storage adapter is responsible for:
+ * - Running plugin migrations at boot (see `PluginMigration`)
+ * - Providing a `PluginDb` backed by the same connection pool / client
+ *
+ * Plugins access this via `PluginDb` in their tools and hooks.
+ */
+export interface PluginDbService {
+  /** Run a query that returns rows. */
+  readonly query: <T = Record<string, unknown>>(sql: string, params?: readonly unknown[]) => Effect.Effect<T[], StorageError>
+
+  /** Run a query that returns a single row or null. */
+  readonly queryOne: <T = Record<string, unknown>>(sql: string, params?: readonly unknown[]) => Effect.Effect<T | null, StorageError>
+
+  /** Run a statement that doesn't return rows (INSERT, UPDATE, DELETE). */
+  readonly execute: (sql: string, params?: readonly unknown[]) => Effect.Effect<void, StorageError>
+}
+
+export class PluginDb extends Context.Tag('@onkeiki/agents/PluginDb')<
+  PluginDb,
+  PluginDbService
+>() {}
+
+/**
+ * A single migration contributed by a plugin. Migrations are tracked in
+ * a `smskit_plugin_migrations` table and only run once per (pluginId, version).
+ *
+ * Migrations are NEVER rolled back when a plugin is disabled — disabling
+ * a plugin simply stops running its code, but the tables and data remain
+ * intact. This prevents accidental data loss.
+ */
+export type PluginMigration = {
+  /** Monotonically increasing version number (1, 2, 3, ...). */
+  readonly version: number
+  /** Human-readable name for logging. */
+  readonly name: string
+  /** SQL statement(s) to execute. May contain multiple statements separated by semicolons. */
+  readonly up: string
+}

package/src/services/Sandbox.ts

@@ -0,0 +1,74 @@
+import { Context } from 'effect'
+
+/**
+ * Result of executing a command in a sandbox.
+ */
+export type SandboxExecResult = {
+  readonly stdout: string
+  readonly stderr: string
+  readonly exitCode: number
+}
+
+/**
+ * A handle to a running sandbox instance. Provides shell execution and
+ * network access needed by plugins that run daemons inside sandboxes
+ * (e.g. Executor.sh for custom MCP servers).
+ */
+export interface SandboxHandle {
+  /** Execute a shell command inside the sandbox. */
+  readonly exec: (
+    command: string,
+    opts?: { readonly timeoutSeconds?: number; readonly cwd?: string }
+  ) => Promise<SandboxExecResult>
+
+  /** Get a publicly-reachable URL for a port exposed inside the sandbox. */
+  readonly getPublicUrl: (port: number, expiresInSeconds?: number) => Promise<string>
+
+  /** Absolute home directory of the sandbox user. */
+  readonly getHomeDir: () => Promise<string>
+
+  /**
+   * Absolute path of a durable data directory backed by persistent storage
+   * (e.g. a Daytona volume) that survives sandbox stop/delete, or `null` when
+   * no durable storage is attached. Daemons that keep state (SQLite, OAuth
+   * credentials) use it as a backup/restore target across sandbox recreation.
+   */
+  readonly getPersistentExecutorDataDir?: () => Promise<string | null>
+}
+
+/**
+ * Abstract sandbox provider — any sandbox company (Daytona, E2B, Runloop,
+ * Modal, etc.) can implement this interface and plug into AgentKit.
+ *
+ * The provider is responsible for lifecycle management (create, start, stop,
+ * reuse) of sandboxes. Each `scope` string identifies an isolation boundary
+ * (e.g. `"apiKey:phone"` for per-user sandboxes).
+ *
+ * @example
+ * ```ts
+ * // Community adapter: @onkeiki/agents-sandbox-daytona
+ * import { Daytona } from '@daytona/sdk'
+ *
+ * export function daytona(opts: { apiKey: string; snapshot?: string }): SandboxProvider {
+ *   return {
+ *     resolve: async (scope) => {
+ *       const sandbox = await getOrCreate(scope)
+ *       return {
+ *         exec: (cmd, o) => sandbox.process.executeCommand(cmd, o?.cwd, {}, o?.timeoutSeconds),
+ *         getPublicUrl: (port, exp) => sandbox.getSignedPreviewUrl(port, exp).then(r => r.url),
+ *         getHomeDir: () => sandbox.getUserHomeDir().then(h => h ?? '/root'),
+ *       }
+ *     },
+ *   }
+ * }
+ * ```
+ */
+export interface SandboxProviderService {
+  /** Get or create a sandbox for the given scope. */
+  readonly resolve: (scope: string) => Promise<SandboxHandle>
+}
+
+export class SandboxProvider extends Context.Tag('@onkeiki/agents/SandboxProvider')<
+  SandboxProvider,
+  SandboxProviderService
+>() {}

package/src/services/Steering.ts

@@ -0,0 +1,45 @@
+import { Context, Effect, Queue, Fiber, Ref } from 'effect'
+import type { InboundMessage } from '../types/index.js'
+import type { SteeringConfig } from '../types/config.js'
+
+export type SteeringDecision =
+  | { readonly type: 'batch'; readonly messages: ReadonlyArray<InboundMessage> }
+  | { readonly type: 'interrupt'; readonly messages: ReadonlyArray<InboundMessage> }
+  | { readonly type: 'append'; readonly message: InboundMessage }
+  | { readonly type: 'queue'; readonly message: InboundMessage }
+
+export type TurnState = {
+  readonly phone: string
+  readonly status: 'idle' | 'debouncing' | 'processing'
+  readonly pending: ReadonlyArray<InboundMessage>
+  readonly currentTurnStartedAt?: Date
+}
+
+export interface SteeringService {
+  /**
+   * Enqueue an inbound message. Steering decides when to
+   * release it as a turn (after debounce window) or interrupt
+   * an in-progress turn.
+   */
+  readonly enqueue: (msg: InboundMessage) => Effect.Effect<void>
+
+  /**
+   * Subscribe to turn decisions. The agent runtime consumes these.
+   */
+  readonly decisions: Effect.Effect<Queue.Dequeue<SteeringDecision>>
+
+  /**
+   * Signal that the current turn for a phone has completed.
+   */
+  readonly turnCompleted: (phone: string) => Effect.Effect<void>
+
+  /**
+   * Get current state for a phone number.
+   */
+  readonly getState: (phone: string) => Effect.Effect<TurnState>
+}
+
+export class Steering extends Context.Tag('@onkeiki/agents/Steering')<
+  Steering,
+  SteeringService
+>() {}

package/src/services/Storage.ts

@@ -0,0 +1,76 @@
+import { Context, Effect } from 'effect'
+import type { StoredMessage, UserProfile, Subscriber } from '../types/index.js'
+
+export class StorageError {
+  readonly _tag = 'StorageError'
+  constructor(readonly message: string, readonly cause?: unknown) {}
+}
+
+export type NewMessage = {
+  readonly phone: string
+  readonly chatId: string
+  readonly direction: 'inbound' | 'outbound'
+  readonly content: string
+  readonly mediaUrl?: string
+  readonly mediaMimeType?: string
+  readonly externalMessageId?: string
+}
+
+export type DeliveryClaim = {
+  readonly phone: string
+  readonly alertKey: string
+  readonly alertText: string
+}
+
+export type UsageEvent = {
+  readonly turns?: number
+  readonly messages?: number
+  readonly tokensIn?: number
+  readonly tokensOut?: number
+}
+
+export type BillingPeriod = {
+  readonly start: Date
+  readonly end: Date
+}
+
+export type UsageSummary = {
+  readonly turns: number
+  readonly messages: number
+  readonly tokensIn: number
+  readonly tokensOut: number
+}
+
+export interface StorageService {
+  // Messages
+  readonly insertMessage: (msg: NewMessage) => Effect.Effect<{ id: string; created: boolean }, StorageError>
+  readonly getHistory: (phone: string, limit: number) => Effect.Effect<StoredMessage[], StorageError>
+  readonly updateMessageContent: (externalId: string, content: string) => Effect.Effect<void, StorageError>
+
+  // User profiles
+  readonly getUser: (phone: string) => Effect.Effect<UserProfile | null, StorageError>
+  readonly upsertUser: (phone: string, patch: Partial<UserProfile>) => Effect.Effect<void, StorageError>
+  readonly getUserMeta: (phone: string, key: string) => Effect.Effect<string | null, StorageError>
+  readonly setUserMeta: (phone: string, key: string, value: string) => Effect.Effect<void, StorageError>
+
+  // Alert subscriptions
+  readonly listSubscribers: () => Effect.Effect<Subscriber[], StorageError>
+  readonly setOptOut: (phone: string, optedOut: boolean) => Effect.Effect<void, StorageError>
+
+  // Alert delivery dedup
+  readonly claimDelivery: (claim: DeliveryClaim) => Effect.Effect<boolean, StorageError>
+  readonly markDelivered: (phone: string, alertKey: string, externalId: string) => Effect.Effect<void, StorageError>
+
+  // Phone line assignments
+  readonly getLineAssignment: (phone: string) => Effect.Effect<string | null, StorageError>
+  readonly setLineAssignment: (phone: string, line: string) => Effect.Effect<void, StorageError>
+
+  // Usage metering
+  readonly incrementUsage: (keyId: string, event: UsageEvent) => Effect.Effect<void, StorageError>
+  readonly getUsage: (keyId: string, period: BillingPeriod) => Effect.Effect<UsageSummary, StorageError>
+}
+
+export class Storage extends Context.Tag('@onkeiki/agents/Storage')<
+  Storage,
+  StorageService
+>() {}