@onkeiki/agents 0.1.0

package/src/Kit.ts

@@ -0,0 +1,705 @@
+import { Effect, Layer, Queue, Ref, pipe, JSONSchema } from 'effect'
+import type { AgentKitConfig, AgentConfig, StorageBundle } from './types/config.js'
+import type { PluginDbService } from './services/PluginDb.js'
+import { StorageError, type StorageService } from './services/Storage.js'
+import type { AlertDefinition } from './Alert.js'
+import type { AgentKitPlugin, PluginContext, SyncPayload } from './Plugin.js'
+import type { PluginMigration } from './services/PluginDb.js'
+import { Storage } from './services/Storage.js'
+import { Platform, PlatformError } from './services/Platform.js'
+import { Steering, type SteeringDecision } from './services/Steering.js'
+import { Blackboard } from './services/Blackboard.js'
+import { bundleTool } from './bundle.js'
+import type { InboundMessage } from './types/index.js'
+import type { ToolDefinition } from './Tool.js'
+
+export type AgentKitInstance = {
+  /**
+   * Sync local agent config + tools to the platform (infra-as-code).
+   * Pushes model, systemPrompt, tools, and execution mode to the platform DB.
+   */
+  readonly sync: () => Promise<void>
+
+  /**
+   * Start the HTTP server that receives turn requests from the platform.
+   * Also calls sync() to push config to platform.
+   */
+  readonly serve: (opts?: { port?: number; host?: string }) => Promise<void>
+
+  /**
+   * Process a single inbound message programmatically (useful for testing).
+   */
+  readonly handleInbound: (msg: InboundMessage) => Promise<{ response: string; messageId: string }>
+
+  /**
+   * Graceful shutdown.
+   */
+  readonly shutdown: () => Promise<void>
+}
+
+/**
+ * @deprecated Use {@link AgentKitInstance} instead. Kept for backwards compatibility.
+ */
+export type SmsKitInstance = AgentKitInstance
+
+/**
+ * Resolved plugin state — the merged result of all plugins.
+ * Used internally by Kit, Server, and sync.
+ */
+export type ResolvedPlugins = {
+  /** Agent config with plugin `init` contributions applied (explicit config wins). */
+  readonly agentConfig: AgentConfig
+  /** Merged `PluginInitResult.extra` values, seeded into the sync payload's `extra`. */
+  readonly initExtra: Record<string, unknown>
+  readonly tools: ReadonlyArray<ToolDefinition<any, any>>
+  /** Alert definitions contributed by plugins, additive to `agent.alerts`. */
+  readonly alerts: ReadonlyArray<AlertDefinition>
+  readonly routes: Readonly<Record<string, (req: Request, ctx: any) => Promise<Response>>>
+  readonly hooks: {
+    readonly beforeTurn: ReadonlyArray<NonNullable<NonNullable<AgentKitPlugin['hooks']>['beforeTurn']>>
+    readonly afterTurn: ReadonlyArray<NonNullable<NonNullable<AgentKitPlugin['hooks']>['afterTurn']>>
+    readonly beforeToolCall: ReadonlyArray<NonNullable<NonNullable<AgentKitPlugin['hooks']>['beforeToolCall']>>
+    readonly afterToolCall: ReadonlyArray<NonNullable<NonNullable<AgentKitPlugin['hooks']>['afterToolCall']>>
+  }
+  readonly layers: ReadonlyArray<Layer.Layer<any>>
+  readonly onSync: ReadonlyArray<NonNullable<AgentKitPlugin['onSync']>>
+  readonly onRequest: ReadonlyArray<NonNullable<AgentKitPlugin['onRequest']>>
+  readonly onResponse: ReadonlyArray<NonNullable<AgentKitPlugin['onResponse']>>
+  readonly middleware: ReadonlyArray<NonNullable<AgentKitPlugin['middleware']>[number]>
+  readonly migrations: ReadonlyArray<{ readonly pluginId: string; readonly migrations: ReadonlyArray<PluginMigration> }>
+}
+
+/**
+ * Merge a plugin's `init` config contribution into the agent config.
+ * Explicitly-set agent config keys always win over plugin defaults.
+ */
+export function applyPluginConfig(agent: AgentConfig, overrides: Partial<AgentConfig>): AgentConfig {
+  const explicit = Object.fromEntries(
+    Object.entries(agent).filter(([, value]) => value !== undefined)
+  ) as Partial<AgentConfig>
+  return { ...agent, ...overrides, ...explicit }
+}
+
+/**
+ * Resolve all plugins into a single merged structure.
+ */
+export function resolvePlugins(config: AgentKitConfig): ResolvedPlugins {
+  const plugins = config.plugins ?? []
+  let agentConfig: AgentConfig = config.agent
+  const initExtra: Record<string, unknown> = {}
+
+  const tools: ToolDefinition<any, any>[] = []
+  const routes: Record<string, (req: Request, ctx: any) => Promise<Response>> = {}
+  const beforeTurn: ResolvedPlugins['hooks']['beforeTurn'][number][] = []
+  const afterTurn: ResolvedPlugins['hooks']['afterTurn'][number][] = []
+  const beforeToolCall: ResolvedPlugins['hooks']['beforeToolCall'][number][] = []
+  const afterToolCall: ResolvedPlugins['hooks']['afterToolCall'][number][] = []
+  const layers: Layer.Layer<any>[] = []
+  const onSync: NonNullable<AgentKitPlugin['onSync']>[] = []
+  const onRequest: NonNullable<AgentKitPlugin['onRequest']>[] = []
+  const onResponse: NonNullable<AgentKitPlugin['onResponse']>[] = []
+  const middleware: NonNullable<AgentKitPlugin['middleware']>[number][] = []
+  const migrations: ResolvedPlugins['migrations'][number][] = []
+  const alerts: AlertDefinition[] = []
+
+  for (const plugin of plugins) {
+    // Run init — may contribute config overrides (not mutating original).
+    // Later plugins see earlier plugins' contributions.
+    const ctx: PluginContext = { config, agentConfig }
+    const initResult = plugin.init?.(ctx)
+    if (initResult?.config) {
+      agentConfig = applyPluginConfig(agentConfig, initResult.config)
+    }
+    if (initResult?.extra) {
+      Object.assign(initExtra, initResult.extra)
+    }
+
+    // Collect static migrations declared on the plugin
+    if (plugin.migrations && plugin.migrations.length > 0) {
+      migrations.push({ pluginId: plugin.id, migrations: plugin.migrations })
+    }
+
+    if (plugin.tools) tools.push(...plugin.tools)
+    if (plugin.alerts) alerts.push(...plugin.alerts)
+    if (plugin.routes) Object.assign(routes, plugin.routes)
+    if (plugin.hooks?.beforeTurn) beforeTurn.push(plugin.hooks.beforeTurn)
+    if (plugin.hooks?.afterTurn) afterTurn.push(plugin.hooks.afterTurn)
+    if (plugin.hooks?.beforeToolCall) beforeToolCall.push(plugin.hooks.beforeToolCall)
+    if (plugin.hooks?.afterToolCall) afterToolCall.push(plugin.hooks.afterToolCall)
+    if (plugin.layers) layers.push(...plugin.layers)
+    if (plugin.onSync) onSync.push(plugin.onSync)
+    if (plugin.onRequest) onRequest.push(plugin.onRequest)
+    if (plugin.onResponse) onResponse.push(plugin.onResponse)
+    if (plugin.middleware) middleware.push(...plugin.middleware)
+  }
+
+  return {
+    agentConfig,
+    initExtra,
+    tools,
+    alerts,
+    routes,
+    hooks: { beforeTurn, afterTurn, beforeToolCall, afterToolCall },
+    layers,
+    onSync,
+    onRequest,
+    onResponse,
+    middleware,
+    migrations,
+  }
+}
+
+/**
+ * The agent's own alerts plus plugin-contributed ones, deduped by name
+ * (first definition wins, so agent config beats plugins). Used by both
+ * alert registration in `sync` and the `/alerts/execute` handler so the
+ * two cannot diverge.
+ */
+export function mergedAlerts(config: AgentKitConfig, resolved: ResolvedPlugins): AlertDefinition[] {
+  const seen = new Set<string>()
+  return [...(config.agent.alerts ?? []), ...resolved.alerts].filter((a) => {
+    if (seen.has(a.name)) return false
+    seen.add(a.name)
+    return true
+  })
+}
+
+/**
+ * Run all plugin `onSync` hooks over the initial sync payload.
+ */
+export function applySyncHooks(
+  initial: SyncPayload,
+  hooks: ReadonlyArray<NonNullable<AgentKitPlugin['onSync']>>
+): SyncPayload {
+  let payload = initial
+  for (const onSync of hooks) {
+    payload = onSync(payload)
+  }
+  return payload
+}
+
+function isStorageBundle(s: Layer.Layer<Storage, StorageError> | StorageBundle): s is StorageBundle {
+  return 'layer' in s && 'pluginDb' in s
+}
+
+/** Cloud agents keep history and users on the platform; every local storage call fails loudly. */
+const NoStorage: Layer.Layer<Storage, StorageError> = Layer.succeed(
+  Storage,
+  new Proxy({} as StorageService, {
+    get: (_, method) => () =>
+      Effect.fail(new StorageError(`Storage.${String(method)} called but no \`storage\` was passed to AgentKit.create`)),
+  })
+)
+
+function unwrapStorage(config: AgentKitConfig): {
+  layer: Layer.Layer<Storage, StorageError>
+  pluginDb: PluginDbService | undefined
+} {
+  if (!config.storage) return { layer: NoStorage, pluginDb: undefined }
+  if (isStorageBundle(config.storage)) {
+    return { layer: config.storage.layer, pluginDb: config.storage.pluginDb }
+  }
+  return { layer: config.storage, pluginDb: undefined }
+}
+
+/**
+ * Run plugin-owned migrations using the configured PluginDb.
+ * Each plugin's migrations are tracked in `smskit_plugin_migrations`.
+ * Migrations are additive only — tables are NEVER dropped when a plugin is disabled.
+ */
+async function runPluginMigrations(
+  pluginDb: PluginDbService | undefined,
+  migrations: ResolvedPlugins['migrations']
+): Promise<void> {
+  if (migrations.length === 0 || !pluginDb) return
+
+  const db = pluginDb
+
+  await Effect.runPromise(
+    db.execute(`
+      CREATE TABLE IF NOT EXISTS smskit_plugin_migrations (
+        plugin_id  TEXT NOT NULL,
+        version    INT NOT NULL,
+        name       TEXT NOT NULL,
+        applied_at TIMESTAMPTZ DEFAULT now(),
+        PRIMARY KEY (plugin_id, version)
+      )
+    `)
+  )
+
+  for (const { pluginId, pluginMigrations } of migrations.map((m) => ({ pluginId: m.pluginId, pluginMigrations: m.migrations }))) {
+    const applied = await Effect.runPromise(
+      db.query<{ version: number }>(
+        `SELECT version FROM smskit_plugin_migrations WHERE plugin_id = $1 ORDER BY version`,
+        [pluginId]
+      )
+    )
+    const appliedSet = new Set(applied.map((r) => r.version))
+
+    for (const migration of [...pluginMigrations].sort((a, b) => a.version - b.version)) {
+      if (appliedSet.has(migration.version)) continue
+
+      await Effect.runPromise(db.execute(migration.up))
+      await Effect.runPromise(
+        db.execute(
+          `INSERT INTO smskit_plugin_migrations (plugin_id, version, name) VALUES ($1, $2, $3)`,
+          [pluginId, migration.version, migration.name]
+        )
+      )
+    }
+  }
+}
+
+/**
+ * Create an AgentKit instance from config.
+ *
+ * @example
+ * ```ts
+ * import { AgentKit } from '@onkeiki/agents'
+ * import { PostgresStorageLive } from '@onkeiki/agents-storage-postgres'
+ * import { memory, browser, steering } from '@onkeiki/agents-plugins'
+ *
+ * const kit = AgentKit.create({
+ *   apiKey: process.env.KEIKI_API_KEY!,
+ *   name: 'My Agent',
+ *   resolveNumber: (ctx) => Effect.succeed('+14155551234'),
+ *   storage: PostgresStorageLive({ connectionString: process.env.DATABASE_URL! }),
+ *   plugins: [
+ *     memory({ provider: 'supermemory', autoRetrieve: true }),
+ *     browser({ handoff: true }),
+ *     steering({ debounceWindow: '2 seconds', midTurnStrategy: 'interrupt' }),
+ *   ],
+ *   agent: {
+ *     model: 'google/gemini-3.5-flash',
+ *     maxSteps: 10,
+ *     historyLimit: 40,
+ *     systemPrompt: ({ user }) => `You are an assistant for ${user.phone}`,
+ *     tools: [],
+ *   },
+ * })
+ *
+ * kit.serve({ port: 8789 })
+ * ```
+ */
+export const AgentKit = {
+  create(config: AgentKitConfig): AgentKitInstance {
+    const resolved = resolvePlugins(config)
+    const effectiveConfig: AgentKitConfig = { ...config, agent: resolved.agentConfig }
+    const { layer: storageLayer, pluginDb } = unwrapStorage(effectiveConfig)
+    const platformLayer = makePlatformLayer(effectiveConfig)
+    const steeringLayer = makeSteeringLayer(effectiveConfig.agent)
+    const blackboardLayer = makeBlackboardLayer()
+
+    const fullLayer = pipe(
+      storageLayer,
+      Layer.merge(platformLayer),
+      Layer.merge(steeringLayer),
+      Layer.merge(blackboardLayer),
+    )
+
+    return {
+      sync: async () => {
+        await runPluginMigrations(pluginDb, resolved.migrations)
+        await syncToPlatform(effectiveConfig, resolved)
+      },
+
+      serve: async (opts) => {
+        const port = opts?.port ?? 8789
+        const host = opts?.host ?? '0.0.0.0'
+
+        // Start server first so it's ready to receive turns
+        const { createServer } = await import('./Server.js')
+        const server = createServer(effectiveConfig, resolved)
+
+        Bun.serve({
+          port,
+          hostname: host,
+          fetch: server.fetch,
+        })
+
+        console.log(`@onkeiki/agents serving on ${host}:${port}`)
+
+        // Run plugin migrations and sync config
+        await runPluginMigrations(pluginDb, resolved.migrations)
+        await syncToPlatform(effectiveConfig, resolved, port)
+      },
+
+      handleInbound: async (msg) => {
+        return Effect.runPromise(
+          Effect.gen(function* () {
+            const steering = yield* Steering
+            yield* steering.enqueue(msg)
+            return { response: '', messageId: '' }
+          }).pipe(Effect.provide(fullLayer))
+        )
+      },
+
+      shutdown: async () => {
+        console.log('@onkeiki/agents shutting down')
+      },
+    }
+  },
+}
+
+/**
+ * @deprecated Use {@link AgentKit} instead. Kept for backwards compatibility.
+ */
+export const SmsKit = AgentKit
+
+/**
+ * Channel-neutral alias of `AgentKit.create()`.
+ *
+ * @example
+ * ```ts
+ * import { create } from '@onkeiki/agents'
+ *
+ * const kit = create({ ... })
+ * ```
+ */
+export const create = (config: AgentKitConfig): AgentKitInstance => AgentKit.create(config)
+
+// --- Internal helpers ---
+
+function platformFetch(config: AgentKitConfig, path: string, body?: unknown) {
+  return Effect.tryPromise({
+    try: async () => {
+      const res = await fetch(`${getPlatformUrl()}${path}`, {
+        method: body ? 'POST' : 'GET',
+        headers: {
+          'Authorization': `Bearer ${config.apiKey}`,
+          'Content-Type': 'application/json',
+        },
+        ...(body ? { body: JSON.stringify(body) } : {}),
+      })
+      if (!res.ok) {
+        throw new Error(`Platform API error ${res.status}: ${await res.text()}`)
+      }
+      return await res.json()
+    },
+    catch: (e) => new PlatformError(String(e), e),
+  })
+}
+
+function makePlatformLayer(config: AgentKitConfig): Layer.Layer<Platform> {
+  return Layer.succeed(Platform, {
+    memoryRecall: (phone, query, opts) =>
+      platformFetch(config, '/v1/memory/recall', { phone, query, ...opts }).pipe(
+        Effect.map((r: any) => r.facts ?? [])
+      ),
+
+    memoryLearn: (phone, facts) =>
+      platformFetch(config, '/v1/memory/learn', { phone, facts }).pipe(Effect.asVoid),
+
+    browse: (instruction, opts) =>
+      platformFetch(config, '/v1/browser/browse', { instruction, ...opts }),
+
+    handoff: (opts) =>
+      platformFetch(config, '/v1/browser/handoff', opts),
+
+    exec: (command, opts) =>
+      platformFetch(config, '/v1/sandbox/exec', { command, ...opts }),
+
+    writeFile: (path, content, opts) =>
+      platformFetch(config, '/v1/sandbox/write', { path, content, ...opts }).pipe(Effect.asVoid),
+
+    readFile: (path, opts) =>
+      platformFetch(config, '/v1/sandbox/read', { path, ...opts }).pipe(
+        Effect.map((r: any) => r.content as string)
+      ),
+
+    runJob: (opts) =>
+      platformFetch(config, '/v1/executor/run', opts),
+
+    getJobStatus: (jobId) =>
+      platformFetch(config, `/v1/executor/status/${jobId}`),
+
+    escalate: (opts) =>
+      platformFetch(config, '/v1/escalation/create', opts),
+
+    extractFacts: (phone, messages) =>
+      platformFetch(config, '/v1/learning/extract', { phone, messages }).pipe(
+        Effect.map((r: any) => r.facts ?? [])
+      ),
+
+    transcribeAudio: (url) =>
+      platformFetch(config, '/v1/media/transcribe', { url }).pipe(
+        Effect.map((r: any) => r.text as string)
+      ),
+
+    describeImage: (url, prompt) =>
+      platformFetch(config, '/v1/media/describe', { url, prompt }).pipe(
+        Effect.map((r: any) => r.description as string)
+      ),
+
+    extractDocument: (url) =>
+      platformFetch(config, '/v1/media/extract-document', { url }).pipe(
+        Effect.map((r: any) => r.content as string)
+      ),
+  })
+}
+
+function makeSteeringLayer(agent: AgentConfig): Layer.Layer<Steering> {
+  return Layer.effect(
+    Steering,
+    Effect.gen(function* () {
+      const decisionQueue = yield* Queue.unbounded<SteeringDecision>()
+      const states = yield* Ref.make(new Map<string, { phone: string; status: 'idle' | 'debouncing' | 'processing'; pending: InboundMessage[] }>())
+
+      return {
+        enqueue: (msg: InboundMessage) =>
+          Effect.gen(function* () {
+            const stateMap = yield* Ref.get(states)
+            const existing = stateMap.get(msg.phone)
+
+            if (!existing || existing.status === 'idle') {
+              yield* Ref.update(states, (m) => {
+                const updated = new Map(m)
+                updated.set(msg.phone, { phone: msg.phone, status: 'debouncing', pending: [msg] })
+                return updated
+              })
+            } else if (existing.status === 'debouncing') {
+              yield* Ref.update(states, (m) => {
+                const updated = new Map(m)
+                updated.set(msg.phone, { ...existing, pending: [...existing.pending, msg] })
+                return updated
+              })
+            } else if (existing.status === 'processing') {
+              const strategy = agent.steering?.midTurnStrategy ?? 'append'
+              if (strategy === 'interrupt') {
+                yield* Queue.offer(decisionQueue, { type: 'interrupt', messages: [msg] })
+              } else {
+                yield* Queue.offer(decisionQueue, { type: 'append', message: msg })
+              }
+            }
+          }),
+
+        decisions: Effect.succeed(decisionQueue),
+
+        turnCompleted: (phone: string) =>
+          Ref.update(states, (m) => {
+            const updated = new Map(m)
+            updated.set(phone, { phone, status: 'idle', pending: [] })
+            return updated
+          }),
+
+        getState: (phone: string) =>
+          Ref.get(states).pipe(
+            Effect.map((m) => m.get(phone) ?? { phone, status: 'idle' as const, pending: [] })
+          ),
+      }
+    })
+  )
+}
+
+function makeBlackboardLayer(): Layer.Layer<Blackboard> {
+  return Layer.effect(
+    Blackboard,
+    Effect.gen(function* () {
+      const store = yield* Ref.make(new Map<string, unknown>())
+
+      return {
+        read: (key: string) => Ref.get(store).pipe(Effect.map((m) => m.get(key) ?? null)),
+        write: (key: string, value: unknown) =>
+          Ref.update(store, (m) => { const n = new Map(m); n.set(key, value); return n }),
+        delete: (key: string) =>
+          Ref.update(store, (m) => { const n = new Map(m); n.delete(key); return n }),
+        entries: () => Ref.get(store).pipe(Effect.map((m) => [...m.entries()])),
+        clear: () => Ref.set(store, new Map()),
+      }
+    })
+  )
+}
+
+/**
+ * Sync local agent config + tools + alerts + secrets to the platform (infra-as-code).
+ */
+async function syncToPlatform(config: AgentKitConfig, resolved: ResolvedPlugins, port?: number) {
+  const platformUrl = getPlatformUrl()
+  console.log(`[agents] Syncing to platform at ${platformUrl}`)
+
+  const headers = {
+    'Authorization': `Bearer ${config.apiKey}`,
+    'Content-Type': 'application/json',
+  }
+
+  // Build a static system prompt for platform storage
+  const staticPrompt = config.agent.systemPrompt({
+    user: { phone: '', timezone: null, currency: null, metadata: {}, firstSeenAt: new Date() },
+    now: new Date(),
+    phone: '',
+    context: { memorySummary: null, relevantFacts: [] },
+    isFirstInteraction: false,
+    history: [],
+    staticSync: true,
+  })
+
+  // Merge agent tools + plugin tools
+  const allTools = [...config.agent.tools, ...resolved.tools]
+
+  // Build tool definitions for the sync payload
+  const isSdkMode = port !== undefined
+  const toolDefs = await Promise.all(
+    allTools.map(async (tool) => ({
+      name: tool.name,
+      description: tool.description,
+      inputSchema: JSONSchema.make(tool.input),
+      executionType: 'code' as const,
+      code: isSdkMode ? null : await bundleTool(tool),
+    }))
+  )
+
+  // Derive features flags from agent config
+  const features = {
+    memory: !!config.agent.memory?.enabled,
+    browser: !!config.agent.browser?.enabled,
+    sandbox: !!config.agent.sandbox?.enabled,
+    executor: !!config.agent.executor?.enabled,
+    mcp: !!config.agent.mcp?.enabled,
+    blackboard: !!config.agent.blackboard,
+    promptCache: !!config.agent.promptCache,
+    escalation: !!config.agent.escalation?.enabled,
+    steering: !!config.agent.steering,
+    media: !!config.agent.media,
+    loops: !!config.agent.loops?.enabled,
+  }
+
+  const loopPresets = (config.agent.loops?.presets ?? []).map((p) => ({
+    name: p.name,
+    description: p.description,
+    prompt: p.prompt,
+    schedule_type: p.scheduleType,
+    schedule_expression: p.scheduleExpression,
+    timezone: p.timezone ?? null,
+    quiet: p.quiet ?? false,
+  }))
+
+  const userConnections = (config.agent.mcp?.userConnections ?? []).map((c) => ({
+    name: c.name,
+    description: c.description ?? null,
+    aliases: c.aliases ?? [],
+    vendor: c.vendor ?? null,
+    capabilities: c.capabilities ?? [],
+    spec: c.spec,
+    base_url: c.baseUrl ?? null,
+    oauth: {
+      authorization_url: c.oauth.authorizationUrl,
+      token_url: c.oauth.tokenUrl,
+      client_id_secret: c.oauth.clientIdSecret,
+      client_secret_secret: c.oauth.clientSecretSecret,
+    },
+    health_check: c.healthCheck
+      ? {
+          operation: c.healthCheck.operation,
+          args: c.healthCheck.args ?? null,
+          identity_field: c.healthCheck.identityField ?? null,
+        }
+      : null,
+  }))
+
+  // Single atomic sync call
+  const syncBody = {
+    name: config.name,
+    model: config.agent.model,
+    max_steps: config.agent.maxSteps,
+    history_limit: config.agent.historyLimit,
+    system_prompt: staticPrompt,
+    execution_mode: port ? 'sdk' : 'platform',
+    webhook_url: port ? `http://localhost:${port}` : undefined,
+    harness: config.harness?.type ?? 'flue',
+    harness_config: config.harness ? {
+      mode: config.harness.connectivity,
+      dispatchUrl: config.harness.dispatchUrl,
+      timeoutMs: config.harness.timeoutMs === undefined
+        ? undefined
+        : durationInputToMs(config.harness.timeoutMs),
+    } : undefined,
+    features,
+    loop_presets: loopPresets,
+    user_connections: userConnections,
+    capabilities: config.agent.capabilities ?? undefined,
+    tools: toolDefs,
+  }
+
+  // Let plugins augment the sync payload
+  const payload = applySyncHooks(
+    {
+      name: syncBody.name,
+      model: syncBody.model,
+      tools: toolDefs.map((t) => ({ name: t.name, description: t.description, inputSchema: t.inputSchema })),
+      features,
+      extra: { ...resolved.initExtra },
+    },
+    resolved.onSync
+  )
+
+  const syncRes = await fetch(`${platformUrl}/api/v1/developer/sync`, {
+    method: 'POST',
+    headers,
+    body: JSON.stringify({
+      ...syncBody,
+      name: payload.name,
+      model: payload.model,
+      features: payload.features,
+      extra: payload.extra,
+    }),
+  })
+
+  let devAgentId: string | undefined
+  if (!syncRes.ok) {
+    console.warn(`[agents] Sync failed: ${syncRes.status} ${await syncRes.text()}`)
+  } else {
+    const result = await syncRes.json() as { devAgentId?: string }
+    devAgentId = result.devAgentId
+    console.log(`[agents] Sync complete: agent="${config.name}" id=${devAgentId} tools=${allTools.length}`)
+  }
+
+  // Sync alerts (if any defined) — the agent's own plus plugin-contributed.
+  const alerts = mergedAlerts(config, resolved)
+  if (alerts.length > 0) {
+    const alertDefs = alerts.map((alert) => ({
+      name: alert.name,
+      description: alert.description,
+      schedule: alert.schedule,
+    }))
+
+    const alertsRes = await fetch(`${platformUrl}/api/v1/developer/alerts/sync`, {
+      method: 'POST',
+      headers,
+      body: JSON.stringify({ devAgentId, alerts: alertDefs }),
+    })
+
+    if (!alertsRes.ok) {
+      console.warn(`[agents] Alerts sync failed: ${alertsRes.status} ${await alertsRes.text()}`)
+    } else {
+      console.log(`[agents] Alerts synced: ${alerts.length} alert(s)`)
+    }
+  }
+
+  // Sync secrets (if any defined)
+  if (config.secrets && Object.keys(config.secrets).length > 0) {
+    const secretsRes = await fetch(`${platformUrl}/api/v1/developer/secrets/sync`, {
+      method: 'POST',
+      headers,
+      body: JSON.stringify({ secrets: config.secrets }),
+    })
+
+    if (!secretsRes.ok) {
+      console.warn(`[agents] Secrets sync failed: ${secretsRes.status} ${await secretsRes.text()}`)
+    } else {
+      console.log(`[agents] Secrets synced: ${Object.keys(config.secrets).length} secret(s)`)
+    }
+  }
+}
+
+function durationInputToMs(value: number | `${number} ${'seconds' | 'minutes' | 'hours'}`): number {
+  if (typeof value === 'number') return value
+  const [amountText, unit] = value.split(' ')
+  const amount = Number(amountText)
+  if (unit === 'hours') return amount * 3_600_000
+  if (unit === 'minutes') return amount * 60_000
+  return amount * 1_000
+}
+
+function getPlatformUrl(): string {
+  return process.env.KEIKI_PLATFORM_URL ?? 'https://smskit-production.up.railway.app'
+}