@nuxtagentic/agents 0.0.0-stage → 0.1.0

package/runtime/server/utils/agent-execution.ts

@@ -0,0 +1,124 @@
+import { createServerClient } from '@cloudconfig/core/server'
+import type { AgentsConfig } from '@cloudconfig/core/agents'
+import type { AgentRunHost, AgentRunRequest } from '@cloudconfig/core/agents/platform'
+import { runSavedAgent } from '@cloudconfig/core/agents/runtime'
+import { toAgentDefinition } from '../../shared/definition'
+import { getAgentProviderKeys } from './agent-provider-keys'
+import type { IntegrationsConfig } from '@nuxtagentic/integrations/schema'
+import {
+  actorOf,
+  backendConfig,
+  getDatabaseProvider,
+  integrationApi,
+  listGrantedTools,
+  performIntegrationAction,
+  type IntegrationServiceContext,
+} from '@nuxtagentic/integrations/runtime/server/utils/integration-context'
+import { createRetryingModelFetch } from './model-fetch'
+import { limitToolResult } from './tool-result'
+
+export async function resolveAgentExecution(
+  request: AgentRunRequest,
+  env?: Record<string, unknown>,
+) {
+  const database = await getDatabaseProvider(env)
+  const context: IntegrationServiceContext = {
+    database,
+    env,
+    request: new Request('https://agent.internal'),
+    ownerId: request.scope.ownerId,
+    workspace: request.scope.workspace,
+  }
+  // Runs act as the agent's owner, and only while they are still a member.
+  await actorOf(context)
+  const api = createServerClient(
+    backendConfig as AgentsConfig & IntegrationsConfig,
+    { request: context.request, env },
+    { db: database, getUser: () => ({ id: context.ownerId }) },
+  )
+  const record = await api.agent.get(request.scope.agentId)
+  const agent = toAgentDefinition(record)
+  const granted = agent.tools.some((tool) => tool.enabled) ? await listGrantedTools(context) : []
+  const tools = agent.tools
+    .filter((tool) => tool.enabled && agent.toolChoice !== 'none')
+    .map((tool) => {
+      const action = granted.find((entry) => entry.name === tool.name)
+      if (!action) {
+        throw new Error(`Tool ${tool.name} has no connected handler or permission.`)
+      }
+      return {
+        name: action.name,
+        description: tool.description || action.description,
+        parameters: action.parameters,
+        provider: action.provider,
+        action: action.action,
+        bindingId: action.bindingId,
+      }
+    })
+  return {
+    agent,
+    tools,
+    keys: getAgentProviderKeys({ ...process.env, ...env }),
+    callTool: async (
+      name: string,
+      input: Record<string, unknown>,
+      call: { idempotencyKey: string },
+    ) => {
+      const tool = tools.find((entry) => entry.name === name)
+      if (!tool) {
+        throw new Error('The agent requested a tool it has not been granted.')
+      }
+      return limitToolResult(
+        await performIntegrationAction(
+          context,
+          { provider: tool.provider, action: tool.action, input, bindingId: tool.bindingId },
+          {
+            idempotencyKey: call.idempotencyKey,
+            continuation: { agentScope: request.scope, agentRunId: request.runId },
+          },
+        ),
+      )
+    },
+    async approval(id: number) {
+      const integrations = await integrationApi(context)
+      const approval = await integrations.integrationApproval.get(id)
+      const connection = await integrations.integrationConnection.get(approval.connectionId)
+      if (connection.workspace !== context.workspace) {
+        throw new Error('Approval belongs to another workspace.')
+      }
+      if (approval.status === 'completed') {
+        return limitToolResult(approval.result)
+      }
+      if (approval.status === 'pending' || approval.status === 'approved') {
+        return { approvalRequired: true, approvalId: id }
+      }
+      throw new Error(
+        approval.status === 'rejected'
+          ? 'The owner rejected the action.'
+          : 'The approved action failed.',
+      )
+    },
+  }
+}
+
+/** How saved agents run on every deployment target; the framework supplies the platform. */
+export const agentRunHost = {
+  resolve: resolveAgentExecution,
+  approval: async (request, approvalId, env) =>
+    (await resolveAgentExecution(request, env)).approval(approvalId),
+  // Local Codex and Claude CLIs run only for runs a localhost request started in development.
+  execute: async (invocation, request) => {
+    if (invocation.fetch) {
+      return runSavedAgent(invocation)
+    }
+    if (
+      import.meta.dev &&
+      request.context?.localCli === true &&
+      invocation.agent.runtime &&
+      invocation.agent.runtime !== 'api'
+    ) {
+      return (await import('./run-local-agent')).runLocalAgent(invocation)
+    }
+    return runSavedAgent({ ...invocation, fetch: createRetryingModelFetch() })
+  },
+} satisfies AgentRunHost<Record<string, unknown> | undefined>

package/runtime/server/utils/agent-gateway.ts

@@ -0,0 +1,13 @@
+import type { H3Event } from 'h3'
+import { useCloudConfigAgents } from '#cloudconfig/agents'
+import { getIntegrationContext } from '@nuxtagentic/integrations/runtime/server/utils/integration-context'
+
+/** Open the caller's runs of one saved agent. The scope comes from the session, never the body. */
+export async function connectAgentGateway(event: H3Event, agentId: number, sessionId = 'test') {
+  if (!Number.isSafeInteger(agentId) || agentId < 1) {
+    throw new Error('Choose an agent.')
+  }
+  const context = await getIntegrationContext(event)
+  const scope = { ownerId: context.ownerId, workspace: context.workspace, agentId, sessionId }
+  return { scope, runtime: await useCloudConfigAgents(event).runs(scope) }
+}

package/runtime/server/utils/agent-model-catalog.ts

@@ -0,0 +1,93 @@
+import type { AgentProvider } from '@cloudconfig/core/agents'
+import type { AgentModelOption } from '../../shared/runtime'
+
+const FRESH_FOR = 60 * 60_000
+const RETRY_AFTER = 60_000
+const cache = new Map<
+  AgentProvider,
+  { key: string; until: number; models: Promise<AgentModelOption[]> }
+>()
+
+/** Serves the last good list immediately and refreshes it in the background. */
+export function listApiAgentModels(provider: AgentProvider, key: string) {
+  if (!key) {
+    return Promise.resolve([])
+  }
+  const cached = cache.get(provider)
+  if (cached?.key === key) {
+    if (cached.until <= Date.now()) {
+      cached.until = Date.now() + RETRY_AFTER
+      void discover(provider, key).then(
+        (models) => {
+          if (!models.length) {
+            return
+          }
+          cached.models = Promise.resolve(models)
+          cached.until = Date.now() + FRESH_FOR
+        },
+        () => {},
+      )
+    }
+    return cached.models
+  }
+  const entry = {
+    key,
+    until: Date.now() + RETRY_AFTER,
+    models: Promise.resolve<AgentModelOption[]>([]),
+  }
+  entry.models = discover(provider, key).then(
+    (models) => {
+      if (models.length) {
+        entry.until = Date.now() + FRESH_FOR
+      }
+      return models
+    },
+    () => [],
+  )
+  cache.set(provider, entry)
+  return entry.models
+}
+
+async function discover(provider: AgentProvider, key: string): Promise<AgentModelOption[]> {
+  const urls = {
+    openai: 'https://api.openai.com/v1/models',
+    anthropic: 'https://api.anthropic.com/v1/models?limit=100',
+    google: 'https://generativelanguage.googleapis.com/v1beta/models?pageSize=1000',
+  }
+  const headers: Record<AgentProvider, Record<string, string>> = {
+    openai: { Authorization: `Bearer ${key}` },
+    anthropic: { 'x-api-key': key, 'anthropic-version': '2023-06-01' },
+    google: { 'x-goog-api-key': key },
+  }
+  const response = await fetch(urls[provider], {
+    headers: headers[provider],
+    signal: AbortSignal.timeout(5000),
+    redirect: 'error',
+  })
+  if (!response.ok) {
+    return []
+  }
+  const body = (await response.json()) as {
+    data?: { id: string; display_name?: string; created?: number }[]
+    models?: { name: string; displayName?: string; supportedGenerationMethods?: string[] }[]
+  }
+  if (provider === 'google') {
+    return (body.models ?? [])
+      .filter((model) => model.supportedGenerationMethods?.includes('generateContent'))
+      .map((model) => ({
+        value: model.name.replace(/^models\//, ''),
+        label: model.displayName || model.name,
+      }))
+  }
+  // Anthropic lists newest first; OpenAI needs its creation time to match.
+  return (body.data ?? [])
+    .filter(
+      (model) =>
+        provider !== 'openai' ||
+        (/^(gpt-|o\d|chatgpt-)/.test(model.id) &&
+          !/(audio|realtime|transcribe|tts|image|search|instruct|embedding)/.test(model.id) &&
+          !/-\d{4}-\d{2}-\d{2}$/.test(model.id)),
+    )
+    .sort((a, b) => (b.created ?? 0) - (a.created ?? 0))
+    .map((model) => ({ value: model.id, label: model.display_name || model.id }))
+}

package/runtime/server/utils/agent-provider-keys.ts

@@ -0,0 +1,46 @@
+import type { AgentProviderKeys } from '../../shared/runtime'
+import { useRuntimeConfig } from '#imports'
+import type { H3Event } from 'h3'
+
+export function getAgentProviderKeysForEvent(event: H3Event) {
+  const config = useRuntimeConfig(event)
+  type Settings = { openaiApiKey?: string; anthropicApiKey?: string; googleAiApiKey?: string }
+  const agents = config.agents as Settings | undefined
+  const automations = config.automations as Settings | undefined
+  return getAgentProviderKeys({
+    NUXT_AGENTS_OPENAI_API_KEY: agents?.openaiApiKey,
+    NUXT_AGENTS_ANTHROPIC_API_KEY: agents?.anthropicApiKey,
+    NUXT_AGENTS_GOOGLE_AI_API_KEY: agents?.googleAiApiKey,
+    NUXT_AUTOMATIONS_OPENAI_API_KEY: automations?.openaiApiKey,
+    NUXT_AUTOMATIONS_ANTHROPIC_API_KEY: automations?.anthropicApiKey,
+    NUXT_AUTOMATIONS_GOOGLE_AI_API_KEY: automations?.googleAiApiKey,
+    ...process.env,
+    ...event.context.cloudflare?.env,
+  })
+}
+
+export function getAgentProviderKeys(values: Record<string, unknown>): AgentProviderKeys {
+  return {
+    openai: String(
+      values.NUXT_AGENTS_OPENAI_API_KEY ||
+        values.NUXT_AUTOMATIONS_OPENAI_API_KEY ||
+        values.NUXT_OPENAI_API_KEY ||
+        values.OPENAI_API_KEY ||
+        '',
+    ),
+    anthropic: String(
+      values.NUXT_AGENTS_ANTHROPIC_API_KEY ||
+        values.NUXT_AUTOMATIONS_ANTHROPIC_API_KEY ||
+        values.NUXT_ANTHROPIC_API_KEY ||
+        values.ANTHROPIC_API_KEY ||
+        '',
+    ),
+    google: String(
+      values.NUXT_AGENTS_GOOGLE_AI_API_KEY ||
+        values.NUXT_AUTOMATIONS_GOOGLE_AI_API_KEY ||
+        values.NUXT_GOOGLE_AI_API_KEY ||
+        values.GEMINI_API_KEY ||
+        '',
+    ),
+  }
+}

package/runtime/server/utils/local-agent-catalog.ts

@@ -0,0 +1,151 @@
+import { access, readFile, realpath, stat } from 'node:fs/promises'
+import { constants, createReadStream } from 'node:fs'
+import { homedir } from 'node:os'
+import { delimiter, join } from 'node:path'
+import {
+  LOCAL_RUNTIMES,
+  type AgentModelOption,
+  type AgentRuntimeOption,
+  type LocalAgentRuntime,
+} from '../../shared/runtime'
+
+export async function findLocalAgentBinary(runtime: LocalAgentRuntime) {
+  const directories = [...(process.env.PATH ?? '').split(delimiter), join(homedir(), '.local/bin')]
+  for (const directory of directories.filter(Boolean)) {
+    const path = join(directory, runtime)
+    try {
+      await access(path, constants.X_OK)
+      return await realpath(path)
+    } catch {
+      /* Try the next PATH directory. */
+    }
+  }
+  return null
+}
+
+const RUNTIME_DEFAULT: AgentModelOption = { value: '', label: 'Runtime default' }
+// Claude Code resolves these aliases itself, so they never go stale.
+const FALLBACK: Record<LocalAgentRuntime, AgentModelOption[]> = {
+  claude: ['opus', 'sonnet', 'haiku'].map((value) => ({
+    value,
+    label: `${value[0]!.toUpperCase()}${value.slice(1)} (latest)`,
+  })),
+  codex: [],
+}
+
+// Discovery reads the CLI's 250MB bundle, so repeat it only when the install changes.
+const discovered = new Map<
+  LocalAgentRuntime,
+  { fingerprint: string; models: Promise<AgentModelOption[]> }
+>()
+
+async function computeFingerprint(path: string) {
+  try {
+    const file = await stat(path)
+    return `${path}:${file.size}:${Math.floor(file.mtimeMs)}`
+  } catch {
+    return ''
+  }
+}
+
+async function discoverModels(runtime: LocalAgentRuntime, binary: string) {
+  // Codex refreshes its account's models into a cache file without changing the binary.
+  const source = runtime === 'codex' ? codexModelsCachePath() : binary
+  const key = await computeFingerprint(source)
+  const cached = discovered.get(runtime)
+  if (cached?.fingerprint === key) {
+    return cached.models
+  }
+  const models = (runtime === 'codex' ? codexModels(source) : claudeModels(binary)).catch(() => [])
+  discovered.set(runtime, { fingerprint: key, models })
+  return models
+}
+
+export function getLocalAgentCatalog(): Promise<AgentRuntimeOption[]> {
+  return Promise.all(
+    (Object.keys(LOCAL_RUNTIMES) as LocalAgentRuntime[]).map(async (value) => {
+      const binary = await findLocalAgentBinary(value)
+      const models = binary ? await discoverModels(value, binary) : []
+      return {
+        value,
+        label: LOCAL_RUNTIMES[value].label,
+        provider: LOCAL_RUNTIMES[value].provider,
+        available: !!binary,
+        hint: binary
+          ? 'Uses your local CLI login.'
+          : `Install ${value} and sign in to use it locally.`,
+        models: [RUNTIME_DEFAULT, ...(models.length ? models : FALLBACK[value])],
+      }
+    }),
+  )
+}
+
+function codexModelsCachePath() {
+  return join(process.env.CODEX_HOME || join(homedir(), '.codex'), 'models_cache.json')
+}
+
+async function codexModels(path: string): Promise<AgentModelOption[]> {
+  const cache = JSON.parse(await readFile(path, 'utf8')) as {
+    models?: { slug: string; display_name?: string; visibility?: string; priority?: number }[]
+  }
+  return (cache.models ?? [])
+    .filter((model) => model.slug && (!model.visibility || model.visibility === 'list'))
+    .sort((a, b) => (a.priority ?? 0) - (b.priority ?? 0))
+    .map((model) => ({ value: model.slug, label: model.display_name || model.slug }))
+}
+
+const CHUNK = 4 * 1024 * 1024
+const OVERLAP = 8 * 1024
+
+async function claudeModels(binary: string): Promise<AgentModelOption[]> {
+  // Like Open Run, inspect the installed bundle without starting an inference session.
+  const models = new Map<string, AgentModelOption & { rank: number; effort: boolean }>()
+  const stream = createReadStream(binary, { encoding: 'latin1', highWaterMark: CHUNK })
+  let carry = ''
+  try {
+    for await (const chunk of stream) {
+      const text = carry + chunk
+      carry = text.slice(-OVERLAP)
+      if (!text.includes('display_name:"')) {
+        continue
+      }
+      const entries = [
+        ...text.matchAll(/\{id:"(claude-[a-z0-9.-]+)",family:"[a-z0-9]+",display_name:"([^"]+)"/g),
+      ]
+      for (const [index, entry] of entries.entries()) {
+        const end = entries[index + 1]?.index ?? text.indexOf('],aliases:', entry.index)
+        const metadata = text.slice(entry.index, end >= 0 ? end : entry.index + 2400)
+        models.set(entry[1]!, {
+          value: entry[1]!,
+          label: entry[2]!,
+          rank: Number(/advisor_rank:(\d+)/.exec(metadata)?.[1] ?? 0),
+          effort: (/capabilities:\[([^\]]*)\]/.exec(metadata)?.[1] ?? '').includes('"effort"'),
+        })
+      }
+      const latest = text.match(/latest_per_family:\{([^}]*)\}/)?.[1]
+      if (!latest) {
+        continue
+      }
+      const ids = new Set([...latest.matchAll(/"(claude-[a-z0-9.-]+)"/g)].map((entry) => entry[1]))
+      // `claude` without --model resolves the opus alias; lead with what a run gets today.
+      const preferred = /aliases:\{opus:\{default:"([a-z0-9-]+)"/.exec(text)?.[1]
+      // Match Open Run: keep selectable effort models as well as each family's latest.
+      const current = [...models.values()].filter((model) => model.effort || ids.has(model.value))
+      if (current.length) {
+        return current
+          .sort(
+            (a, b) =>
+              Number(b.value === preferred) - Number(a.value === preferred) ||
+              b.rank - a.rank ||
+              b.value.localeCompare(a.value, undefined, { numeric: true }),
+          )
+          .map(({ value, label }) => ({ value, label, preferred: value === preferred }))
+      }
+    }
+  } finally {
+    stream.destroy()
+  }
+  return [...models.values()]
+    .sort((a, b) => b.rank - a.rank || b.value.localeCompare(a.value, undefined, { numeric: true }))
+    .map(({ value, label }) => ({ value, label }))
+}

package/runtime/server/utils/local-agent-runtime.ts

@@ -0,0 +1,8 @@
+import { getRequestURL, type H3Event } from 'h3'
+
+export function isLocalAgentRuntimeEnabled(event: H3Event) {
+  // Cloudflare's development proxy supplies a context even on the local Node server.
+  return (
+    import.meta.dev && ['localhost', '127.0.0.1', '[::1]'].includes(getRequestURL(event).hostname)
+  )
+}

package/runtime/server/utils/model-fetch.ts

@@ -0,0 +1,66 @@
+/** Rate limits, provider overload and gateway failures that clear on their own. */
+const TRANSIENT_STATUSES = new Set([408, 425, 429, 500, 502, 503, 504, 529])
+const MAX_RETRIES = 3
+const BASE_DELAY_MS = 500
+const MAX_DELAY_MS = 8_000
+
+/**
+ * Model transport that retries rate limits, overloads and dropped connections.
+ * Model requests have no side effects, so a retry only costs time; the call's
+ * own deadline still bounds every attempt and every wait.
+ */
+export function createRetryingModelFetch(base: typeof fetch = fetch): typeof fetch {
+  return async (input, init) => {
+    for (let attempt = 0; ; attempt++) {
+      let response: Response | undefined
+      try {
+        response = await base(input, init)
+      } catch (cause) {
+        if (init?.signal?.aborted || attempt >= MAX_RETRIES) {
+          throw cause
+        }
+      }
+      if (response && (!TRANSIENT_STATUSES.has(response.status) || attempt >= MAX_RETRIES)) {
+        return response
+      }
+      const delay = retryDelay(response, attempt)
+      // A provider asking for a longer pause is out of quota, not briefly busy.
+      if (response && delay > MAX_DELAY_MS) {
+        return response
+      }
+      await response?.body?.cancel()
+      await wait(Math.min(delay, MAX_DELAY_MS), init?.signal)
+    }
+  }
+}
+
+function retryDelay(response: Response | undefined, attempt: number) {
+  const header = response?.headers.get('retry-after')
+  if (header) {
+    const seconds = Number(header)
+    const delay = Number.isFinite(seconds) ? seconds * 1000 : Date.parse(header) - Date.now()
+    if (Number.isFinite(delay)) {
+      return Math.max(delay, 0)
+    }
+  }
+  // Full jitter keeps parallel runs from retrying in lockstep.
+  return BASE_DELAY_MS * 2 ** attempt * (0.5 + Math.random() / 2)
+}
+
+function wait(milliseconds: number, signal?: AbortSignal | null) {
+  return new Promise<void>((resolve, reject) => {
+    if (signal?.aborted) {
+      reject(signal.reason)
+      return
+    }
+    const abort = () => {
+      clearTimeout(timer)
+      reject(signal?.reason)
+    }
+    const timer = setTimeout(() => {
+      signal?.removeEventListener('abort', abort)
+      resolve()
+    }, milliseconds)
+    signal?.addEventListener('abort', abort, { once: true })
+  })
+}