@onkeiki/agents 0.1.0

package/src/Tool.ts

@@ -0,0 +1,110 @@
+import { Effect, Schema } from 'effect'
+import { fileURLToPath } from 'node:url'
+import type { UserProfile } from './types/index.js'
+import type { BlackboardService } from './services/Blackboard.js'
+import type { PlatformService } from './services/Platform.js'
+import type { PluginDbService } from './services/PluginDb.js'
+import type { SandboxHandle } from './services/Sandbox.js'
+import type { EntityStore } from './Entity.js'
+
+/**
+ * Per-user KV state backed by a Rivet UserState actor.
+ * One instance per (apiKey, phone) pair.
+ */
+export interface UserStateService {
+  readonly get: (key: string) => Effect.Effect<unknown>
+  readonly set: (key: string, value: unknown) => Effect.Effect<void>
+  readonly delete: (key: string) => Effect.Effect<boolean>
+  readonly getAll: () => Effect.Effect<Record<string, unknown>>
+  readonly setMany: (entries: Record<string, unknown>) => Effect.Effect<void>
+}
+
+/**
+ * Developer secrets — encrypted KV stored on the platform.
+ * Synced via kit.sync() and accessible at runtime.
+ */
+export interface SecretsService {
+  readonly get: (name: string) => Effect.Effect<string | null>
+  readonly getAll: () => Effect.Effect<Record<string, string>>
+}
+
+/**
+ * Where the turn calling a tool came from: the channel plus the provider ids
+ * naming the sender and the thread. Flat so it reads the same on a trace and in
+ * a tool. `userId` is the sender in the channel's own terms — a Slack user id,
+ * an email address, a phone number, a Telegram chat id.
+ */
+export type ChannelEnvelope = {
+  readonly channel: 'sms' | 'telegram' | 'whatsapp' | 'xchat' | 'slack' | 'agentmail' | 'api' | 'agent' | 'synthetic'
+  /** Text of the messages a person sent this turn, joined; platform notices excluded. */
+  readonly inboundText: string
+  /** Provider id of the last inbound message (Slack `ts`, email `message_id`, …). */
+  readonly messageId?: string
+  readonly userId?: string
+  readonly teamId?: string
+  readonly channelId?: string
+  readonly threadTs?: string
+  readonly threadId?: string
+  readonly inboxId?: string
+  /** WhatsApp: Meta's phone number id the conversation runs on. */
+  readonly phoneNumberId?: string
+  /** X Chat: the canonical conversation id. */
+  readonly chatConversationId?: string
+  /** `ask_agent`: the agent asking. */
+  readonly fromAgentId?: string
+}
+
+export type ToolContext = {
+  readonly phone: string
+  readonly user: UserProfile
+  /** Set when the tool runs on the platform for a turn; absent in a local runtime. */
+  readonly channel?: ChannelEnvelope
+  readonly blackboard: BlackboardService
+  readonly platform: PlatformService
+  readonly userState: UserStateService
+  readonly secrets: SecretsService
+  readonly db: PluginDbService
+  /**
+   * Entity persistence bridge for cloud (actor) execution, where `db` is not
+   * reachable. Entity helpers use `contextEntityStore(ctx)`, which prefers
+   * this and falls back to SQL over `db`.
+   */
+  readonly entityStore?: EntityStore
+  readonly sandbox: SandboxHandle
+}
+
+export type ToolDefinition<I = unknown, O = unknown> = {
+  readonly name: string
+  readonly description: string
+  readonly input: Schema.Schema<I>
+  readonly execute: (input: I, ctx: ToolContext) => Effect.Effect<O>
+  /**
+   * Absolute path to the module that defined this tool. Captured automatically
+   * by {@link defineTool} so `kit.sync()` can bundle the tool into a standalone
+   * actor artifact. Not set by hand.
+   */
+  readonly sourceFile?: string
+}
+
+/**
+ * Define a type-safe tool for your agent.
+ */
+export function defineTool<I, O>(def: ToolDefinition<I, O>): ToolDefinition<I, O> {
+  return { ...def, sourceFile: def.sourceFile ?? captureSourceFile() }
+}
+
+const THIS_FILE = import.meta.url
+
+function captureSourceFile(): string | undefined {
+  const stack = new Error().stack
+  if (!stack) return undefined
+  for (const line of stack.split('\n').slice(1)) {
+    const match = line.match(/(?:\(|@|\s)((?:file:\/\/)?\/[^\s()]+?\.[cm]?[jt]sx?):\d+:\d+/)
+    if (!match) continue
+    let file = match[1]!
+    if (file.startsWith('file://')) file = fileURLToPath(file)
+    if (file === fileURLToPath(THIS_FILE)) continue
+    return file
+  }
+  return undefined
+}

package/src/bundle.ts

@@ -0,0 +1,114 @@
+import { writeFile, rm } from 'node:fs/promises'
+import { dirname, join } from 'node:path'
+import { randomUUID } from 'node:crypto'
+import type { ToolDefinition } from './Tool.js'
+
+/**
+ * Bundle a single tool into a standalone, dependency-free ESM artifact that the
+ * platform deploys and runs as a per-tool actor.
+ *
+ * The artifact exports `__run(input, host)`:
+ *   - `input`  — raw tool arguments (validated against the tool's Schema here)
+ *   - `host`   — actor-provided bridge: `{ phone, user, channel, userState, secrets, entities }`
+ *                with async methods backed by the platform's Rivet UserState
+ *                actor, developer secrets, and entity storage.
+ *
+ * Bundling requires Bun (developers run `kit.sync()` under Bun) and the tool's
+ * captured `sourceFile`, since `execute` is a live closure that imports helpers
+ * and cannot be serialized from the tool object alone.
+ */
+export async function bundleTool(tool: ToolDefinition): Promise<string> {
+  const bun = (globalThis as { Bun?: { build: (opts: unknown) => Promise<BunBuildOutput> } }).Bun
+  if (!bun) {
+    throw new Error(
+      `kit.sync() must run under Bun to bundle tool "${tool.name}" into an actor artifact.`
+    )
+  }
+  if (!tool.sourceFile) {
+    throw new Error(
+      `Cannot bundle tool "${tool.name}": its source file was not captured. ` +
+        `Define it with defineTool() from '@onkeiki/agents'.`
+    )
+  }
+
+  const entryDir = dirname(tool.sourceFile)
+  const entryPath = join(entryDir, `.smskit-actor-${sanitize(tool.name)}-${randomUUID()}.mjs`)
+
+  await writeFile(entryPath, buildEntrySource(tool.name, tool.sourceFile), 'utf8')
+  try {
+    const built = await bun.build({
+      entrypoints: [entryPath],
+      target: 'node',
+      format: 'esm',
+      minify: true,
+    })
+    if (!built.success) {
+      const detail = built.logs.map((l) => String(l)).join('\n')
+      throw new Error(`Failed to bundle tool "${tool.name}":\n${detail}`)
+    }
+    const output = built.outputs[0]
+    if (!output) throw new Error(`Bundling tool "${tool.name}" produced no output`)
+    return await output.text()
+  } finally {
+    await rm(entryPath, { force: true })
+  }
+}
+
+function buildEntrySource(toolName: string, sourceFile: string): string {
+  const name = JSON.stringify(toolName)
+  const source = JSON.stringify(sourceFile)
+  return `import { Effect, Schema } from 'effect'
+import * as __mod from ${source}
+
+const __toolName = ${name}
+const __isTool = (t) => t && typeof t === 'object' && typeof t.execute === 'function' && t.name === __toolName
+const __exports = Object.values(__mod)
+const __tool =
+  __exports.find(__isTool)
+  ?? __exports.flatMap((e) => (e && typeof e === 'object' && Array.isArray(e.tools) ? e.tools : [])).find(__isTool)
+if (!__tool) throw new Error('Tool ' + __toolName + ' not found in ' + ${source})
+
+const fromPromise = (run) => Effect.tryPromise({ try: run, catch: (e) => e })
+
+function buildContext(host) {
+  const unavailable = (what) => {
+    throw new Error(what + ' is not available in actor tool execution')
+  }
+  return {
+    phone: host.phone,
+    user: host.user,
+    channel: host.channel,
+    get blackboard() { return unavailable('ctx.blackboard') },
+    get platform() { return unavailable('ctx.platform') },
+    userState: {
+      get: (k) => fromPromise(() => host.userState.get(k)),
+      set: (k, v) => fromPromise(() => host.userState.set(k, v)),
+      delete: (k) => fromPromise(() => host.userState.delete(k)),
+      getAll: () => fromPromise(() => host.userState.getAll()),
+      setMany: (e) => fromPromise(() => host.userState.setMany(e)),
+    },
+    secrets: {
+      get: (n) => fromPromise(() => host.secrets.get(n)),
+      getAll: () => fromPromise(() => host.secrets.getAll()),
+    },
+    get db() { return unavailable('ctx.db (use entity helpers, which route through ctx.entityStore)') },
+    entityStore: host.entities,
+  }
+}
+
+export async function __run(input, host) {
+  const decoded = Schema.decodeUnknownSync(__tool.input)(input)
+  return await Effect.runPromise(__tool.execute(decoded, buildContext(host)))
+}
+`
+}
+
+function sanitize(name: string): string {
+  return name.replace(/[^a-zA-Z0-9_-]/g, '_')
+}
+
+type BunBuildOutput = {
+  success: boolean
+  logs: unknown[]
+  outputs: Array<{ text: () => Promise<string> }>
+}

package/src/index.ts

@@ -0,0 +1,209 @@
+// Main entry point for @onkeiki/agents
+export {
+  AgentKit,
+  SmsKit,
+  create,
+  type ResolvedPlugins,
+  type AgentKitInstance,
+  type SmsKitInstance,
+} from './Kit.js'
+export {
+  defineTool,
+  type ToolDefinition,
+  type ToolContext,
+  type ChannelEnvelope,
+  type UserStateService,
+  type SecretsService,
+} from './Tool.js'
+export {
+  defineAlert,
+  type AlertDefinition,
+  type AlertSchedule,
+  type AlertContent,
+  type AlertContext,
+  type AlertMedia,
+  type AlertMessage,
+  type AlertStateService,
+} from './Alert.js'
+export {
+  defineEntity,
+  entityMigrations,
+  entityTools,
+  createEntityDb,
+  contextEntityStore,
+  sqlEntityStore,
+  EntityError,
+  type EntityStore,
+  type EntityStoreRow,
+  type EntityDefinition,
+  type EntityRow,
+  type EntityAccessor,
+  type EntityDb,
+} from './Entity.js'
+export {
+  definePlugin,
+  type AgentKitPlugin,
+  type SmsKitPlugin,
+  type Plugin,
+  type TurnEvent,
+  type TurnResult,
+  type ToolCallEvent,
+  type ToolCallResult,
+  type RouteContext,
+  type PluginContext,
+  type SyncPayload,
+  type PluginInitResult,
+} from './Plugin.js'
+export {
+  oauthOpenApiSpec,
+  googleOpenApiSpec,
+  microsoftOpenApiSpec,
+  OpenApiSpecError,
+  GOOGLE_AUTHORIZATION_URL,
+  GOOGLE_TOKEN_URL,
+  MICROSOFT_AUTHORIZATION_URL,
+  MICROSOFT_TOKEN_URL,
+  type OpenApiMethod,
+  type OpenApiOperation,
+  type OpenApiParameter,
+  type OpenApiParameterRef,
+  type OAuthOpenApiSpec,
+  type OAuthOpenApiSpecInput,
+} from './OpenApi.js'
+export {
+  createServer,
+  executeAlert,
+  type TurnRequest,
+  type TurnResponse,
+  type AlertDelivery,
+  type AlertExecuteBody,
+} from './Server.js'
+
+// Services (for advanced use / custom adapters)
+export {
+  Storage,
+  StorageError,
+  type StorageService,
+  type NewMessage,
+  type DeliveryClaim,
+  type UsageEvent,
+  type BillingPeriod,
+  type UsageSummary,
+} from './services/Storage.js'
+
+export {
+  Transport,
+  type TransportService,
+} from './services/Transport.js'
+
+export {
+  Platform,
+  PlatformError,
+  type PlatformService,
+  type MemoryFact,
+  type BrowseResult,
+  type SandboxExecResult,
+  type HandoffResult,
+  type EscalationResult,
+  type BackgroundJobResult,
+} from './services/Platform.js'
+
+export {
+  Steering,
+  type SteeringService,
+  type SteeringDecision,
+  type TurnState,
+} from './services/Steering.js'
+
+export {
+  Blackboard,
+  type BlackboardService,
+} from './services/Blackboard.js'
+
+export {
+  Observability,
+  ObservabilityError,
+  braintrustExporter,
+  axiomExporter,
+  otelExporter,
+  customExporter,
+  type TraceExporter,
+  type TraceEvent,
+  type SpanEvent,
+  type SpanKind,
+  type SpanStatus,
+} from './services/Observability.js'
+
+export {
+  SandboxProvider,
+  type SandboxProviderService,
+  type SandboxHandle,
+} from './services/Sandbox.js'
+
+export {
+  PluginDb,
+  type PluginDbService,
+  type PluginMigration,
+} from './services/PluginDb.js'
+
+// Types
+export type {
+  AgentKitConfig,
+  SmsKitConfig,
+  AgentConfig,
+  MemoryConfig,
+  BrowserConfig,
+  SandboxConfig,
+  ExecutorConfig,
+  SteeringConfig,
+  MediaConfig,
+  MediaActionConfig,
+  EscalationConfig,
+  EscalationRoute,
+  EventHandlers,
+  ObservabilityConfig,
+  PromptContext,
+  TurnHooks,
+  TurnHookState,
+  TurnReviewState,
+  RetrievedContext,
+  ResolveNumberContext,
+  AcquireLineOpts,
+  PhoneLine,
+  DurationInput,
+  HarnessConfig,
+  StorageBundle,
+  ChannelType,
+  ChannelConfig,
+  SmsChannelConfig,
+  TelegramChannelConfig,
+  CapabilityRef,
+  CapabilityManifest,
+  CapabilityRuntime,
+  CapabilityNamespace,
+  CapabilitySecret,
+  CapabilityField,
+  CapabilityTool,
+  CapabilityToolRun,
+  CapabilityTemplate,
+  CapabilityEntity,
+  CapabilityLoop,
+  CapabilityLoopProbe,
+  CapabilityLoopTrigger,
+  CapabilityInput,
+} from './types/config.js'
+
+export type {
+  InboundMessage,
+  OutboundMessage,
+  StoredMessage,
+  MediaPayload,
+  SendResult,
+  DeliveryStatus,
+  Direction,
+} from './types/message.js'
+
+export type {
+  UserProfile,
+  Subscriber,
+} from './types/user.js'

package/src/services/Blackboard.ts

@@ -0,0 +1,19 @@
+import { Context, Effect } from 'effect'
+
+/**
+ * Cross-step key-value scratchpad within a single turn.
+ * Tools can read/write state that persists across tool steps
+ * but is cleared when the turn ends.
+ */
+export interface BlackboardService {
+  readonly read: (key: string) => Effect.Effect<unknown | null>
+  readonly write: (key: string, value: unknown) => Effect.Effect<void>
+  readonly delete: (key: string) => Effect.Effect<void>
+  readonly entries: () => Effect.Effect<ReadonlyArray<[string, unknown]>>
+  readonly clear: () => Effect.Effect<void>
+}
+
+export class Blackboard extends Context.Tag('@onkeiki/agents/Blackboard')<
+  Blackboard,
+  BlackboardService
+>() {}