@nuxtagentic/prompt 0.0.0-stage → 0.1.0

package/core/validation.ts

@@ -0,0 +1,187 @@
+import {
+  OperationError,
+  type Condition,
+  type Field,
+  type Filters,
+  type ResourceInfo,
+  type Row,
+} from './types'
+
+export function isRecord(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === 'object' && !Array.isArray(value)
+}
+
+export function isValidId(value: unknown): value is number {
+  return typeof value === 'number' && Number.isSafeInteger(value) && value > 0
+}
+
+const textKinds = new Set(['text', 'textarea', 'email', 'url', 'select', 'date', 'datetime'])
+const numericKinds = new Set(['number', 'float', 'relation'])
+const textOperators = ['like', 'not_contains', 'starts_with', 'ends_with']
+const rangeOperators = ['gt', 'gte', 'lt', 'lte']
+const emptyOperators = ['is_empty', 'is_not_empty']
+const setOperators = ['is_any_of', 'is_none_of']
+const operators = new Set([
+  'eq',
+  'neq',
+  ...textOperators,
+  ...rangeOperators,
+  ...emptyOperators,
+  ...setOperators,
+])
+
+function matchesField(value: unknown, kind: string) {
+  if (value === null) {
+    return true
+  }
+  if (kind === 'boolean') {
+    return typeof value === 'boolean'
+  }
+  if (numericKinds.has(kind)) {
+    return typeof value === 'number' && Number.isFinite(value)
+  }
+  return textKinds.has(kind) && typeof value === 'string' && value.length <= 2000
+}
+
+function validDate(value: unknown, kind: string) {
+  if (value === null) {
+    return true
+  }
+  if (typeof value !== 'string' || !Number.isFinite(Date.parse(value))) {
+    return false
+  }
+  const canonical = new Date(value).toISOString()
+  return kind === 'datetime'
+    ? canonical === value
+    : /^\d{4}-\d{2}-\d{2}$/.test(value) && canonical.slice(0, 10) === value
+}
+
+function validateCondition(raw: Record<string, unknown>, field: Field | undefined): Condition {
+  if (
+    raw.type !== 'condition' ||
+    !field ||
+    typeof raw.operator !== 'string' ||
+    !operators.has(raw.operator) ||
+    ['json', 'multiselect'].includes(field.kind) ||
+    Object.keys(raw).some((key) => !['type', 'field', 'operator', 'value'].includes(key))
+  ) {
+    throw new OperationError(422, 'The filter contains an unavailable field or operator.')
+  }
+  const operator = raw.operator as Condition['operator']
+  const value = raw.value
+  const values = Array.isArray(value) ? value : [value]
+  if (setOperators.includes(operator)) {
+    if (
+      !Array.isArray(value) ||
+      !value.length ||
+      value.length > 25 ||
+      value.some(
+        (item) => item === null || typeof item === 'boolean' || !matchesField(item, field.kind),
+      )
+    ) {
+      throw new OperationError(422, 'Invalid filter alternatives.')
+    }
+  } else if (!matchesField(value, field.kind)) {
+    throw new OperationError(422, 'Invalid filter value.')
+  }
+  if (emptyOperators.includes(operator) && value !== null) {
+    throw new OperationError(422, 'Empty-value filters must use null.')
+  }
+  if (
+    ['date', 'datetime'].includes(field.kind) &&
+    values.some((item) => !validDate(item, field.kind))
+  ) {
+    throw new OperationError(422, 'Use a valid date or canonical UTC timestamp in filters.')
+  }
+  if (
+    textOperators.includes(operator) &&
+    (!textKinds.has(field.kind) ||
+      typeof value !== 'string' ||
+      !value.trim() ||
+      /[%_\\]/.test(value))
+  ) {
+    throw new OperationError(422, 'Use literal, non-empty text to match records.')
+  }
+  if (
+    rangeOperators.includes(operator) &&
+    ((!numericKinds.has(field.kind) && !['date', 'datetime'].includes(field.kind)) ||
+      value === null)
+  ) {
+    throw new OperationError(422, 'This field cannot use a range comparison.')
+  }
+  if (
+    field.options?.length &&
+    !emptyOperators.includes(operator) &&
+    values.some((item) => !field.options!.includes(String(item)))
+  ) {
+    throw new OperationError(422, 'Unknown field option.')
+  }
+  return { type: 'condition', field: field.key, operator, value: value as Condition['value'] }
+}
+
+/** Never drop an invalid constraint: doing so could broaden a mutation. */
+export function validateFilters(value: unknown, resource: ResourceInfo): Filters {
+  const fields = new Map(resource.fields.map((field) => [field.key, field]))
+  let count = 0
+  function inspect(raw: unknown, depth: number): Condition | Filters {
+    if (++count > 60 || depth > 6 || !isRecord(raw)) {
+      throw new OperationError(422, 'The filter is too complex.')
+    }
+    if (raw.type !== 'group') {
+      return validateCondition(
+        raw,
+        typeof raw.field === 'string' ? fields.get(raw.field) : undefined,
+      )
+    }
+    if (
+      (raw.logic !== 'and' && raw.logic !== 'or') ||
+      !Array.isArray(raw.children) ||
+      Object.keys(raw).some((key) => !['type', 'logic', 'children'].includes(key))
+    ) {
+      throw new OperationError(422, 'Invalid filter group.')
+    }
+    if (depth && !raw.children.length) {
+      throw new OperationError(422, 'An empty nested filter is not supported.')
+    }
+    return {
+      type: 'group',
+      logic: raw.logic,
+      children: raw.children.map((node) => inspect(node, depth + 1)),
+    }
+  }
+  const filters = inspect(value, 0)
+  if (filters.type !== 'group') {
+    throw new OperationError(422, 'Expected a filter group.')
+  }
+  return filters
+}
+
+export function toDisplayRow(row: Row, resource: ResourceInfo) {
+  const result: Row = { id: row.id }
+  for (const key of resource.displayFields) {
+    const value = row[key]
+    // Public scalar evidence only. No private rows or large document payloads in confirmations.
+    if (value === null || ['string', 'number', 'boolean'].includes(typeof value)) {
+      result[key] = value
+    }
+  }
+  return result
+}
+
+function canonical(value: unknown): string {
+  if (Array.isArray(value)) {
+    return `[${value.map(canonical).join(',')}]`
+  }
+  if (isRecord(value)) {
+    return `{${Object.keys(value)
+      .sort()
+      .map((key) => `${JSON.stringify(key)}:${canonical(value[key])}`)
+      .join(',')}}`
+  }
+  return JSON.stringify(value) ?? 'null'
+}
+export async function computeFingerprint(row: Row): Promise<string> {
+  const bytes = new TextEncoder().encode(canonical(row))
+  const digest = await globalThis.crypto.subtle.digest('SHA-256', bytes)
+  return Array.from(new Uint8Array(digest), (byte) => byte.toString(16).padStart(2, '0')).join('')
+}

package/docs/search.md

@@ -0,0 +1,69 @@
+# How search works
+
+The workspace combines local query parsing, authorized retrieval, and optional
+provider decisions. Each feature owns its query syntax and data source. Agent
+routes natural-language requests using metadata from the installed modules.
+
+## Follow a query
+
+1. Workspace recognizes a short keyword search or asks registered feature parsers
+   to interpret structured input.
+2. A local match opens its collection and passes a validated query to that
+   feature's data source. No provider call is needed.
+3. Submitted natural language goes to Agent. The selected provider chooses a tool
+   and schema-derived arguments; the application validates and compiles them.
+4. The feature retrieves authorized records through its own data source.
+5. Selecting a result changes URL state. Proposed mutations go through a separate
+   server-stored review before execution.
+
+Short keyword searches cover the installed searchable collections. Fully quoting
+an input forces literal keyword interpretation. Inputs with intent words or
+structured-query punctuation stay available to feature parsers and Agent.
+[`getDashboardSearchText`](../../workspace/runtime/shared/dashboard-search.ts) owns
+that distinction; [`useWorkspacePrompt`](../../../app/composables/useWorkspacePrompt.ts)
+coordinates parsing, provider requests, cancellation, and retries.
+
+## Register a model collection
+
+Define the model in its owning package's `schema.ts` and include it in the host's
+`cloud.config.ts`. Create a view with
+[`defineModelView`](../../data/runtime/shared/model-views.ts) and publish it through
+that module's `runtime/shared/agent.ts` metadata.
+
+| View option                      | Controls                                      |
+| -------------------------------- | --------------------------------------------- |
+| `id`, `label`, `icon`, `aliases` | Source identity and recognized names          |
+| `columns`                        | Visible and selectable columns                |
+| `search`, `filter`, `sort`       | Allowed fields for those operations           |
+| `actions`                        | Available create, update, and delete controls |
+| `prompt.fields`, `prompt.values` | Domain vocabulary for schema-based decisions  |
+
+Field types, defaults, and select options come from the schema. Server-only fields
+remain excluded from public forms and assignment. The owning feature supplies
+its collection UI and registers it with the workspace.
+
+Kit generates metadata from installed modules. There is no central
+`model-ui.config.ts` or handwritten list of every query sentence.
+
+## What the provider decides
+
+[`createDispatcher`](../runtime/server/utils/jev-dispatch.ts) builds closed choices
+from registered tools and model views. Explicit resource context can skip routing.
+When request limits permit, routing and argument decisions share a call; larger
+requests first select a resource, then ask only about its schema.
+
+[`prepareCandidates`](../runtime/server/utils/prompt-candidates.ts) preserves
+literal values from the input. Schema-based decisions select fields, comparisons,
+values, and AND/OR structure. The query compiler validates the result before
+building CloudConfig filters. Required mutation fields are checked by the planner.
+Neither provider generates executable SQL or arbitrary JSON arguments.
+
+TypeSafe AI and OpenAI use the same decision contract through
+[`useDecisionProvider`](../runtime/server/utils/decision-provider.ts). Resource
+routing needs a configured provider key; deterministic local queries continue
+without one. The [Agent guide](../README.md) describes configuration and writes.
+
+[`config.ts`](../config.ts) contains interpretation instructions, candidate limits,
+request budgets, deadlines, retries, and reranking policy. Optional metrics record
+request timing and size without logging prompt or answer text. Literal names keep
+their spelling; schema vocabulary can accept known aliases and spelling variants.

package/module.ts

@@ -0,0 +1,26 @@
+import { createResolver, defineNuxtModule } from '@nuxt/kit'
+import { registerWorkspaceModule } from '@nuxtagentic/kit'
+import { defu } from 'defu'
+
+export default defineNuxtModule({
+  meta: { name: '@nuxtagentic/prompt' },
+  moduleDependencies: {
+    '@nuxtagentic/data': {},
+  },
+  setup(_options, nuxt) {
+    const resolver = createResolver(import.meta.url)
+    registerWorkspaceModule(
+      {
+        id: 'prompt',
+        runtime: resolver.resolve('./runtime'),
+        metadata: resolver.resolve('./runtime/shared/agent.ts'),
+      },
+      nuxt,
+    )
+    nuxt.options.runtimeConfig = defu(nuxt.options.runtimeConfig, {
+      decisionProvider: 'typesafeAI',
+      typesafe: { apiKey: '' },
+      openai: { apiKey: '', decisionModel: 'gpt-6-luna' },
+    })
+  },
+})

package/package.json

@@ -1,6 +1,59 @@
 {
   "name": "@nuxtagentic/prompt",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0",
+  "type": "module",
+  "files": [
+    "module.ts",
+    "runtime",
+    "schema.ts",
+    "core",
+    "cloudconfig.ts",
+    "config.ts",
+    "server-contributions.ts",
+    "docs",
+    "README.md",
+    "LICENSE.md"
+  ],
+  "exports": {
+    ".": "./module.ts",
+    "./package.json": "./package.json",
+    "./schema": "./schema.ts",
+    "./cloudconfig": "./cloudconfig.ts",
+    "./config": "./config.ts",
+    "./server-contributions": "./server-contributions.ts",
+    "./core": "./core/index.ts",
+    "./core/*": "./core/*.ts",
+    "./runtime/*.vue": "./runtime/*.vue",
+    "./runtime/*.css": "./runtime/*.css",
+    "./runtime/*.json": "./runtime/*.json",
+    "./runtime/*.svg": "./runtime/*.svg",
+    "./runtime/*": "./runtime/*.ts"
+  },
+  "dependencies": {
+    "@cloudconfig/core": "0.2.0-beta.2",
+    "@nuxt/kit": "4.6.1",
+    "@typesafe-ai/sdk": "^0.6.0",
+    "h3": "1.15.11",
+    "defu": "6.1.7",
+    "@nuxtagentic/kit": "0.1.0",
+    "@nuxtagentic/data": "0.1.0"
+  },
+  "peerDependencies": {
+    "nuxt": "^4.6.1"
+  },
+  "devDependencies": {
+    "tsx": "^4.23.15"
+  },
+  "cloudconfig": {
+    "models": "agentOperationsModels"
+  },
+  "license": "SEE LICENSE IN LICENSE.md",
+  "description": "Prompt planning, query decisions and reviewed mutations for Nuxt Agentic.",
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "engines": {
+    "node": "^22.22.3 || ^24.15.0 || >=26.0.0"
+  }
 }

package/runtime/server/api/agent/cancel.post.ts

@@ -0,0 +1,17 @@
+import { defineEventHandler, readBody, createError } from 'h3'
+import { throwAgentOperationError, useAgentOperationHost } from '../../utils/agent-operations'
+import { isRecord } from '../../../../core/validation'
+
+export default defineEventHandler(async (event) => {
+  const host = await useAgentOperationHost(event)
+  const body = await readBody<unknown>(event)
+  if (!isRecord(body) || typeof body.key !== 'string' || !/^[0-9a-f-]{36}$/.test(body.key)) {
+    throw createError({ statusCode: 400, statusMessage: 'Choose a valid confirmation.' })
+  }
+  try {
+    await host.engine.cancel(body.key, host.context)
+    return { cancelled: true }
+  } catch (cause) {
+    throwAgentOperationError(cause)
+  }
+})

package/runtime/server/api/agent/execute.post.ts

@@ -0,0 +1,26 @@
+import { defineEventHandler, readBody, createError } from 'h3'
+import { throwAgentOperationError, useAgentOperationHost } from '../../utils/agent-operations'
+import { isRecord, isValidId } from '../../../../core/validation'
+
+export default defineEventHandler(async (event) => {
+  const host = await useAgentOperationHost(event)
+  const body = await readBody<unknown>(event)
+  // No operation, resource, predicate or write payload is accepted from the browser.
+  if (
+    !isRecord(body) ||
+    Object.keys(body).some((key) => !['key', 'selectedIds'].includes(key)) ||
+    typeof body.key !== 'string' ||
+    !/^[0-9a-f-]{36}$/.test(body.key) ||
+    !Array.isArray(body.selectedIds) ||
+    body.selectedIds.length > 25 ||
+    !body.selectedIds.every(isValidId)
+  ) {
+    throw createError({ statusCode: 400, statusMessage: 'Confirm the exact reviewed records.' })
+  }
+  const { key, selectedIds } = body
+  try {
+    return await host.engine.execute(key, selectedIds, host.context)
+  } catch (cause) {
+    throwAgentOperationError(cause)
+  }
+})

package/runtime/server/api/agent/plan.post.ts

@@ -0,0 +1,37 @@
+import { defineEventHandler, readBody, createError } from 'h3'
+import { throwAgentOperationError, useAgentOperationHost } from '../../utils/agent-operations'
+import { isRecord, isValidId } from '../../../../core/validation'
+
+export default defineEventHandler(async (event) => {
+  const host = await useAgentOperationHost(event)
+  const body = await readBody<unknown>(event)
+  if (
+    !isRecord(body) ||
+    typeof body.prompt !== 'string' ||
+    !body.prompt.trim() ||
+    body.prompt.length > 2000 ||
+    (body.resource !== undefined && typeof body.resource !== 'string') ||
+    (body.selection !== undefined && !isValidId(body.selection))
+  ) {
+    throw createError({
+      statusCode: 400,
+      statusMessage: 'Provide an action, resource and valid optional selection.',
+    })
+  }
+  const { prompt, resource: resourceId, selection } = body
+  const resource = host.resources.find(
+    (resource) => resource.id === resourceId || resource.aliases.includes(String(resourceId)),
+  )
+  if (resourceId && !resource) {
+    throw createError({ statusCode: 422, statusMessage: 'This resource is unavailable.' })
+  }
+  try {
+    return await host.engine.plan(prompt.trim(), {
+      ...host.context,
+      ...(resource ? { resource: resource.id } : {}),
+      ...(selection !== undefined ? { selection } : {}),
+    })
+  } catch (cause) {
+    throwAgentOperationError(cause)
+  }
+})

package/runtime/server/api/agent.post.ts

@@ -0,0 +1,60 @@
+import { createError, defineEventHandler, readValidatedBody } from 'h3'
+import { getWorkspaceMetadata } from '#workspace/server'
+import { JEV_MODELS } from '../../shared/agent-tools'
+import { MODEL_QUERY_CONFIG } from '../../../config'
+import { createDispatcher } from '../utils/jev-dispatch'
+import { useJevInference } from '../utils/jev-inference'
+import { useAgentSession } from '../utils/agent-session'
+
+const MAX_PROMPT_LENGTH = 2000
+interface PromptBody {
+  prompt: string
+  model?: string
+  resource?: string
+}
+
+/**
+ * POST /api/agent — turns a natural-language prompt into a local tool call.
+ *
+ * The active provider only decides; the browser runs the tool. The API key stays on the server,
+ * and only signed-in users can spend it.
+ */
+export default defineEventHandler(async (event) => {
+  const body = await readValidatedBody<PromptBody, typeof event>(
+    event,
+    (body: unknown): body is PromptBody =>
+      typeof body === 'object' &&
+      body !== null &&
+      'prompt' in body &&
+      typeof body.prompt === 'string' &&
+      body.prompt.trim().length > 0 &&
+      body.prompt.length <= MAX_PROMPT_LENGTH &&
+      (!('resource' in body) || body.resource === undefined || typeof body.resource === 'string'),
+  )
+  const prompt = body.prompt.trim()
+  const model =
+    JEV_MODELS.find((candidate) => candidate.id === body.model)?.id ?? MODEL_QUERY_CONFIG.model
+
+  const session = await useAgentSession(event)
+  if (!session?.user) {
+    throw createError({ statusCode: 401, statusMessage: 'Sign in to use the agent.' })
+  }
+
+  const metadata = getWorkspaceMetadata(event.context.workspaceModules as string[] | undefined)
+  const dispatchPrompt = createDispatcher({
+    tools: metadata.AGENT_TOOLS,
+    views: metadata.MODEL_VIEWS,
+    query: MODEL_QUERY_CONFIG,
+  })
+
+  const inference = useJevInference(
+    event,
+    MODEL_QUERY_CONFIG.inference,
+    MODEL_QUERY_CONFIG.logMetrics,
+  )
+  try {
+    return await dispatchPrompt(prompt, inference.infer, { model, resource: body.resource })
+  } finally {
+    inference.close()
+  }
+})

package/runtime/server/confirmations.ts

@@ -0,0 +1,104 @@
+import { CloudConfigClientError } from '@cloudconfig/core/client'
+import type { ServerClient } from '@cloudconfig/core/server'
+import type { AgentOperationsConfig } from '../../schema'
+import {
+  OperationError,
+  type Confirmation,
+  type ConfirmationStore,
+  type Context,
+  type PreparedMutation,
+  type Receipt,
+} from '../../core/index'
+
+export function createConfirmationStore(
+  api: ServerClient<AgentOperationsConfig>,
+  owner: Context,
+): ConfirmationStore {
+  type Stored = Awaited<ReturnType<typeof api.agentOperation.get>>
+  const recordIds = new Map<string, number>()
+  function view(row: Stored): Confirmation {
+    const { key, ownerId, sessionId, expiresAt, state, plan, result, version } = row
+    return {
+      key,
+      actorId: String(ownerId),
+      sessionId,
+      expiresAt: Date.parse(expiresAt),
+      state,
+      plan: plan as PreparedMutation,
+      ...(result ? { result: result as Receipt } : {}),
+      revision: version,
+    }
+  }
+  async function transition(
+    confirmation: Confirmation,
+    state: 'executing' | 'completed' | 'failed' | 'cancelled',
+    revision: number,
+    result?: Receipt,
+  ) {
+    const id = recordIds.get(confirmation.key)
+    if (id === undefined) {
+      throw new OperationError(404, 'This confirmation is unavailable.')
+    }
+    try {
+      await api.agentOperation.update(id, {
+        state,
+        version: revision + 1,
+        expectedVersion: revision,
+        ...(result ? { result } : {}),
+      })
+    } catch (cause) {
+      if (cause instanceof CloudConfigClientError && [400, 409].includes(cause.status)) {
+        throw new OperationError(
+          409,
+          'This action was already claimed or changed. Check the results before trying again.',
+        )
+      }
+      throw cause
+    }
+  }
+  return {
+    async create(plan, context) {
+      const row = await api.agentOperation.create({
+        key: crypto.randomUUID(),
+        ownerId: Number(owner.actorId),
+        sessionId: context.sessionId,
+        expiresAt: new Date(Date.now() + 10 * 60 * 1000).toISOString(),
+        state: 'pending',
+        plan,
+        version: 0,
+        expectedVersion: -1,
+      })
+      recordIds.set(row.key, row.id)
+      return view(row)
+    },
+    async get(key, context) {
+      const result = await api.agentOperation.list({
+        page: 1,
+        pageSize: 1,
+        filters: {
+          type: 'group',
+          logic: 'and',
+          children: [
+            { type: 'condition', field: 'key', operator: 'eq', value: key },
+            { type: 'condition', field: 'sessionId', operator: 'eq', value: context.sessionId },
+          ],
+        },
+      })
+      const row = result.data[0]
+      if (!row) {
+        throw new OperationError(404, 'This confirmation is unavailable.')
+      }
+      recordIds.set(row.key, row.id)
+      return view(row)
+    },
+    claim: (confirmation) => transition(confirmation, 'executing', confirmation.revision),
+    finish: (confirmation, result) =>
+      transition(
+        confirmation,
+        result.success ? 'completed' : 'failed',
+        confirmation.revision + 1,
+        result,
+      ),
+    cancel: (confirmation) => transition(confirmation, 'cancelled', confirmation.revision),
+  }
+}