@nuxtagentic/prompt 0.0.0-stage → 0.1.1

package/runtime/server/utils/prompt-candidates.ts

@@ -0,0 +1,165 @@
+import type { Scalar } from '@nuxtagentic/data/runtime/shared/resource-query'
+import type { PromptConfig } from '../../shared/prompt-config'
+import { findDateCandidates } from './prompt-dates'
+
+export interface ValueCandidate {
+  value: Scalar
+  label: string
+  end?: string
+}
+
+interface NumberCandidate extends ValueCandidate {
+  value: number
+  unit?: string
+}
+
+export interface PromptCandidates {
+  now: Date
+  text: string[]
+  spans: string[]
+  numbers: NumberCandidate[]
+  dates: ValueCandidate[]
+  limits: string[]
+}
+
+// Rank phrase boundaries; never remove these words from a literal value.
+const STOPWORDS = new Set(
+  'a an the and or of in on at to for from by with without is are was were be been has have had do does did me my we our us you your i it its all any every some only just please can could would show list find get give see display filter search sort order named called titled where what when how'.split(
+    ' ',
+  ),
+)
+
+function textCandidates(prompt: string, maxWords: number, limit: number): string[] {
+  const quoted = [...prompt.matchAll(/"([^"]+)"|(?<![\p{L}\p{N}])'([^']+)'|“([^”]+)”/gu)].map(
+    (match) => (match[1] ?? match[2] ?? match[3])!.trim(),
+  )
+  const emails = prompt.match(/[\w.+-]+@[\w-]+(?:\.[\w-]+)+/g) ?? []
+  const named = [
+    ...prompt.matchAll(
+      /\b(?:named|called|titled)\s+(.+?)(?=\s+(?:on|at|from|for|where|with)\b|[.!?]?$)/gi,
+    ),
+  ].map((match) => match[1]!.trim())
+  const words = [...prompt.matchAll(/[\p{L}\p{N}@._+-]+(?:['’][\p{L}\p{N}]+)*/gu)]
+  const groups = Array.from({ length: Math.min(maxWords, words.length) }, (_, index) => {
+    const length = index + 1
+    const spans = []
+    for (let i = 0; i + length <= words.length; i++) {
+      const first = words[i]!
+      const last = words[i + length - 1]!
+      spans.push({
+        text: prompt.slice(first.index!, last.index! + last[0].length),
+        rank:
+          Number(!STOPWORDS.has(first[0].toLowerCase())) +
+          Number(!STOPWORDS.has(last[0].toLowerCase())),
+      })
+    }
+    return spans.sort((a, b) => b.rank - a.rank)
+  })
+  const result = new Set([...quoted, ...emails, ...named].filter(Boolean))
+  for (let offset = 0; result.size < limit; offset++) {
+    let found = false
+    for (const group of groups) {
+      const span = group[offset]
+      if (!span) {
+        continue
+      }
+      found = true
+      result.add(span.text)
+      if (result.size >= limit) {
+        break
+      }
+    }
+    if (!found) {
+      break
+    }
+  }
+  return [...result].slice(0, limit)
+}
+
+export function prepareCandidates(
+  prompt: string,
+  config: PromptConfig,
+  now = new Date(),
+): PromptCandidates {
+  const text = textCandidates(
+    prompt,
+    config.candidates.maxWords,
+    Math.min(253, Math.max(config.candidates.text, config.candidates.span)),
+  )
+  const numbers = [...prompt.matchAll(/-?\d+(?:\.\d+)?(?:\s*(?:KB|MB|GB))?/gi)].map((match) => {
+    const [, amount, unit] = /(-?\d+(?:\.\d+)?)\s*(KB|MB|GB)?/i.exec(match[0])!
+    return { value: Number(amount), label: match[0], unit: unit?.toUpperCase() }
+  })
+  return {
+    now,
+    text: text.slice(0, config.candidates.text),
+    spans: text.slice(0, config.candidates.span),
+    numbers,
+    dates: findDateCandidates(prompt, now),
+    limits: [...new Set(prompt.match(/\b\d+\b/g) ?? [])].slice(0, 253),
+  }
+}
+
+export function findFieldCandidates(
+  context: PromptCandidates,
+  field: { kind: string; options?: readonly string[] },
+  vocabulary: Record<string, string> = {},
+  unit?: 'bytes',
+): ValueCandidate[] {
+  let values: ValueCandidate[]
+  switch (field.kind) {
+    case 'boolean':
+      values = [
+        { value: true, label: 'true / yes / on / 1' },
+        { value: false, label: 'false / no / off / 0' },
+      ]
+      break
+    case 'select':
+      values = (field.options ?? []).map((value) => ({
+        value,
+        label: vocabulary[value] ? `${value}: ${vocabulary[value]}` : value,
+      }))
+      break
+    case 'number':
+    case 'float':
+    case 'relation':
+      values = context.numbers.map((candidate) => ({
+        value:
+          candidate.value *
+          (unit === 'bytes' && candidate.unit
+            ? { KB: 1024, MB: 1024 ** 2, GB: 1024 ** 3 }[candidate.unit as 'KB' | 'MB' | 'GB']
+            : 1),
+        label: candidate.label,
+      }))
+      break
+    case 'date':
+    case 'datetime':
+      values = context.dates.map((candidate) =>
+        field.kind === 'date'
+          ? {
+              ...candidate,
+              value: String(candidate.value).slice(0, 10),
+              end: candidate.end?.slice(0, 10),
+            }
+          : candidate,
+      )
+      break
+    default:
+      values = [
+        ...Object.entries(vocabulary).map(([value, meaning]) => ({
+          value,
+          label: `${value}: ${meaning}`,
+        })),
+        ...context.text.map((value) => ({ value, label: value })),
+      ]
+  }
+  const unique = new Map<string, ValueCandidate>()
+  for (const candidate of values) {
+    const key = JSON.stringify([candidate.value, candidate.end])
+    if (!unique.has(key)) {
+      unique.set(key, candidate)
+    }
+  }
+  // Reserve three of Choice's 255 options: actual null, absent and unavailable.
+  return [...[...unique.values()].slice(0, 252), { value: null, label: 'missing / null' }]
+}

package/runtime/server/utils/prompt-dates.ts

@@ -0,0 +1,83 @@
+import { findNamedMonthPeriods } from '@nuxtagentic/data/runtime/shared/date-periods'
+import type { ValueCandidate } from './prompt-candidates'
+
+const millisecondsPerDay = 86_400_000
+const millisecondsPerUnit: Record<string, number> = {
+  hour: 3_600_000,
+  day: millisecondsPerDay,
+  week: 7 * millisecondsPerDay,
+}
+
+export function findDateCandidates(prompt: string, now: Date): ValueCandidate[] {
+  const values: ValueCandidate[] = []
+  const day = (year: number, month: number, date: number) =>
+    new Date(Date.UTC(year, month, date)).toISOString()
+  const year = now.getUTCFullYear()
+  const month = now.getUTCMonth()
+  const date = now.getUTCDate()
+  const weekday = (now.getUTCDay() + 6) % 7
+  const periods: Record<string, [string, string]> = {
+    today: [day(year, month, date), day(year, month, date + 1)],
+    yesterday: [day(year, month, date - 1), day(year, month, date)],
+    tomorrow: [day(year, month, date + 1), day(year, month, date + 2)],
+    'this week': [day(year, month, date - weekday), day(year, month, date - weekday + 7)],
+    'last week': [day(year, month, date - weekday - 7), day(year, month, date - weekday)],
+    'next week': [day(year, month, date - weekday + 7), day(year, month, date - weekday + 14)],
+    'this month': [day(year, month, 1), day(year, month + 1, 1)],
+    'last month': [day(year, month - 1, 1), day(year, month, 1)],
+    'next month': [day(year, month + 1, 1), day(year, month + 2, 1)],
+    'this year': [day(year, 0, 1), day(year + 1, 0, 1)],
+    'last year': [day(year - 1, 0, 1), day(year, 0, 1)],
+    'next year': [day(year + 1, 0, 1), day(year + 2, 0, 1)],
+  }
+  for (const [label, [value, end]] of Object.entries(periods)) {
+    if (new RegExp(`\\b${label}\\b`, 'i').test(prompt)) {
+      values.push({ label: `${label} (${value} until ${end}, exclusive)`, value, end })
+    }
+  }
+  for (const { label, start, end } of findNamedMonthPeriods(prompt, now)) {
+    values.push({ label: `${label} (${start} until ${end}, exclusive)`, value: start, end })
+  }
+  for (const match of prompt.matchAll(
+    /\b(?:last|past|previous)\s+(\d+)\s+(hours?|days?|weeks?|months?|years?)\b/gi,
+  )) {
+    const amount = Number(match[1])
+    const unit = match[2]!.toLowerCase().replace(/s$/, '')
+    const start = new Date(now)
+    if (unit === 'year' || unit === 'month') {
+      const targetYear = unit === 'year' ? year - amount : year
+      const targetMonth = unit === 'month' ? month - amount : month
+      const lastDay = new Date(Date.UTC(targetYear, targetMonth + 1, 0)).getUTCDate()
+      start.setUTCDate(Math.min(date, lastDay))
+      start.setUTCFullYear(targetYear, targetMonth)
+    } else {
+      const duration = millisecondsPerUnit[unit] ?? millisecondsPerDay
+      start.setTime(now.getTime() - amount * duration)
+    }
+    if (Number.isFinite(start.getTime())) {
+      values.push({ label: match[0], value: start.toISOString(), end: now.toISOString() })
+    }
+  }
+  for (const match of prompt.matchAll(
+    /\b\d{4}-\d{2}-\d{2}(?:T\d{2}:\d{2}(?::\d{2}(?:\.\d+)?)?(?:Z|[+-]\d{2}:\d{2})?)?\b/g,
+  )) {
+    const parsed = new Date(match[0])
+    if (Number.isFinite(parsed.getTime())) {
+      values.push({
+        label: match[0],
+        value: parsed.toISOString(),
+        ...(match[0].length === 10
+          ? { end: new Date(parsed.getTime() + 86400000).toISOString() }
+          : {}),
+      })
+    }
+  }
+  for (const match of prompt.matchAll(/\b(?:19|20)\d{2}\b/g)) {
+    if (prompt.slice(match.index! + 4, match.index! + 5) === '-') {
+      continue
+    }
+    const y = Number(match[0])
+    values.push({ label: `year ${y}`, value: day(y, 0, 1), end: day(y + 1, 0, 1) })
+  }
+  return values
+}

package/runtime/shared/agent-tools.ts

@@ -0,0 +1,50 @@
+/** Closed choices, boolean flags, or literal spans copied from the prompt. */
+export type ArgSpec =
+  | {
+      kind: 'choice'
+      question: string
+      stated?: string
+      options: Record<string, string>
+    }
+  | { kind: 'flag'; question: string }
+  | { kind: 'span'; question: string; stated: string }
+
+export interface ToolSpec {
+  /** What the tool does, in the words a user might use. Jev routes on this. */
+  description: string
+  args: Record<string, ArgSpec>
+}
+
+export type AgentToolName = string
+
+export type ArgValue = string | string[] | boolean
+
+export interface ToolCallArgument {
+  /** Left out because the prompt did not mention it. */
+  omitted: boolean
+  value?: ArgValue
+  /** Normalized decision confidence, from 0 to 1. */
+  confidence: number
+}
+
+/** What the server answers for a prompt. `tool: null` means no tool fits. */
+export interface AgentToolCall {
+  tool: AgentToolName | null
+  args: Record<string, ArgValue>
+  arguments: Record<string, ToolCallArgument>
+  /** The least certain judgement behind the call. */
+  confidence: number
+  weakest: string | null
+  model: string
+  /** Validated, read-only model query assembled from schema-derived Jev decisions. */
+  resource?: {
+    id: string
+    query: import('@nuxtagentic/data/runtime/shared/resource-query').ResourceQuery
+  }
+}
+
+export const JEV_MODELS = [
+  { id: 'jev-latest', name: 'Jev latest', description: 'Stable release' },
+  { id: 'jev-preview', name: 'Jev preview', description: 'Newest build' },
+  { id: 'jev-1.13.0', name: 'Jev 1.13', description: 'Pinned version' },
+] as const

package/runtime/shared/agent.ts

@@ -0,0 +1,5 @@
+import type { WorkspaceMetadata } from '@nuxtagentic/prompt/server-contributions'
+
+export default {
+  excludedModels: ['agentOperation'],
+} satisfies WorkspaceMetadata

package/runtime/shared/decision-provider.ts

@@ -0,0 +1 @@
+export type DecisionProvider = 'openAI' | 'typesafeAI'

package/runtime/shared/prompt-config.ts

@@ -0,0 +1,27 @@
+export interface InferencePolicy {
+  /** Total time across all stages and SDK retries. */
+  deadlineMs: number
+  /** Timeout of an individual SDK attempt. */
+  timeoutMs: number
+  maxRetries: number
+}
+
+export interface PromptConfig {
+  model: string
+  instructions: string
+  maxConstraintsPerField: number
+  candidates: { span: number; text: number; maxWords: number }
+  /** Bound speculative model extraction on global requests. */
+  routing: { maxInlineModels: number; maxInlineQuestions: number; maxInlineBytes: number }
+  inference: InferencePolicy
+  rerank: InferencePolicy & {
+    maxFiles: number
+    excerptChars: number
+    queryChars: number
+    nameChars: number
+    folderChars: number
+    mimeTypeChars: number
+  }
+  /** Log timing and usage, without prompts, candidates or answers. */
+  logMetrics: boolean
+}

package/schema.ts

@@ -0,0 +1,69 @@
+import { model, t } from '@cloudconfig/core'
+
+export const agentOperationsModels = {
+  // Durable, session-bound reviews. Public CRUD cannot write any of these private fields.
+  agentOperation: model(
+    {
+      key: t.text().required().unique().serverOnly(),
+      ownerId: t.number().required().serverOnly(),
+      sessionId: t.text().required().serverOnly(),
+      expiresAt: t.datetime().required().serverOnly(),
+      state: t
+        .select(['pending', 'executing', 'completed', 'failed', 'cancelled'])
+        .default('pending')
+        .serverOnly(),
+      plan: t.json().required().serverOnly(),
+      result: t.json().serverOnly(),
+      version: t.number().default(0).serverOnly(),
+      expectedVersion: t.number().default(-1).serverOnly(),
+    },
+    {
+      access: {
+        list: ({ user, where }) => (user ? where('ownerId', 'eq', user.id) : false),
+        read: ({ user, where }) => (user ? where('ownerId', 'eq', user.id) : false),
+        create: ({ user, input }) =>
+          !!user && input?.ownerId === user.id && !!input?.plan && input?.state === 'pending',
+        update: ({ user, input, where }) =>
+          user && Number.isSafeInteger(input?.expectedVersion)
+            ? where('ownerId', 'eq', user.id)
+            : false,
+      },
+      validate: (input, existing) => {
+        const issues = []
+        if (
+          !/^[0-9a-f-]{36}$/.test(String(input.key)) ||
+          !String(input.sessionId) ||
+          !Number.isFinite(Date.parse(String(input.expiresAt))) ||
+          JSON.stringify(input.plan).length > 100_000
+        ) {
+          issues.push({ path: 'plan', message: 'Invalid action confirmation.' })
+        }
+        if (
+          existing &&
+          (input.expectedVersion !== existing.version ||
+            input.version !== Number(existing.version) + 1)
+        ) {
+          issues.push({ path: 'version', message: 'This action was already claimed or changed.' })
+        }
+        if (existing) {
+          const transitions: Record<string, string[]> = {
+            pending: ['executing', 'cancelled'],
+            executing: ['completed', 'failed'],
+          }
+          if (
+            !(transitions[String(existing.state)] ?? []).includes(String(input.state)) ||
+            ['key', 'ownerId', 'sessionId', 'expiresAt'].some(
+              (key) => input[key] !== existing[key],
+            ) ||
+            JSON.stringify(input.plan) !== JSON.stringify(existing.plan)
+          ) {
+            issues.push({ path: 'state', message: 'Invalid action confirmation transition.' })
+          }
+        }
+        return issues
+      },
+    },
+  ),
+}
+
+export type AgentOperationsConfig = { models: typeof agentOperationsModels }

package/server-contributions.ts

@@ -0,0 +1,53 @@
+import type { ClientOptions } from '@cloudconfig/core/client'
+import type { H3Event } from 'h3'
+import type { ModelView } from '@nuxtagentic/data/runtime/shared/model-views'
+import type { ToolSpec } from './runtime/shared/agent-tools'
+import type { Resource } from '@nuxtagentic/prompt/core/index'
+
+export interface WorkspaceMetadata {
+  views?: readonly ModelView[]
+  tools?: Record<string, ToolSpec>
+  resourceAliases?: Record<string, readonly string[]>
+  excludedModels?: readonly string[]
+  googleServices?: Record<
+    string,
+    {
+      label: string
+      scopes: readonly string[]
+      disconnect?: {
+        dataPrefixes?: readonly string[]
+        userStatePrefixes?: readonly string[]
+      }
+    }
+  >
+}
+
+export interface AgentSession {
+  user: { id: string | number; [key: string]: unknown }
+  session: { id: string | number; activeOrganizationId?: string | number | null }
+}
+
+export type AgentResourceFactory = (context: {
+  event: H3Event
+  authBase: string
+  session: AgentSession
+  clientOptions: ClientOptions
+}) => Resource | Promise<Resource>
+
+export type GoogleDisconnectHook = (input: {
+  event: H3Event
+  service: string
+  user: { id: number }
+}) => void | Promise<void>
+
+export type GoogleAvailabilityHook = (input: {
+  event: H3Event
+  service: string
+  user: { id: number; email: string }
+}) => string | undefined | Promise<string | undefined>
+
+export interface ServerContribution extends WorkspaceMetadata {
+  resourceFactories?: readonly AgentResourceFactory[]
+  googleDisconnectHooks?: readonly GoogleDisconnectHook[]
+  googleAvailabilityHooks?: readonly GoogleAvailabilityHook[]
+}