@nuxtagentic/prompt 0.0.0-stage → 0.1.0

package/core/engine.ts

@@ -0,0 +1,317 @@
+import {
+  OperationError,
+  type Context,
+  type ConfirmationStore,
+  type Planner,
+  type PlanResult,
+  type PreparedMutation,
+  type Resource,
+  type Receipt,
+  type Row,
+} from './types'
+import { toDisplayRow, computeFingerprint, isValidId, validateFilters } from './validation'
+
+const MAX_RECORDS = 25
+
+function writableInput(plan: PreparedMutation, resource: Resource) {
+  const fields = plan.operation === 'create' ? resource.createFields : resource.updateFields
+  return Object.fromEntries(Object.entries(plan.input).filter(([key]) => fields.includes(key)))
+}
+
+export function createOperationEngine(
+  resources: readonly Resource[],
+  planner: Planner,
+  store: ConfirmationStore,
+) {
+  const registry = new Map(resources.map((resource) => [resource.id, resource]))
+  const resourceFor = (id: string) => {
+    const resource = registry.get(id)
+    if (!resource) {
+      throw new OperationError(403, 'This resource is not available to the agent.')
+    }
+    return resource
+  }
+  const supports = (resource: Resource, operation: string) => {
+    if (!resource.operations.some((action) => action === operation)) {
+      throw new OperationError(403, `You cannot ${operation} ${resource.label.toLowerCase()}.`)
+    }
+  }
+
+  async function plan(prompt: string, context: Context): Promise<PlanResult> {
+    const route = await planner.route(prompt, resources, context)
+    if (!route.resource || !route.operation) {
+      return { kind: 'fallback' }
+    }
+    if (!Number.isFinite(route.confidence) || route.confidence < 0.8) {
+      return {
+        kind: 'clarification',
+        message: 'Name the resource and the action you want to perform.',
+      }
+    }
+    const resource = resourceFor(route.resource)
+    const operation = route.operation
+    supports(resource, operation)
+    // Input-dependent create rules run after extraction, never with guessed placeholder data.
+    if (operation === 'list') {
+      await resource.authorize(operation)
+    }
+    if (operation === 'create' && resource.createHandoff) {
+      return { kind: 'handoff', resource: resource.id, action: resource.createHandoff }
+    }
+    const proposal = await planner.extract(prompt, resource, operation, context)
+    if (!proposal.supported) {
+      return {
+        kind: 'clarification',
+        message:
+          proposal.clarification || 'Be more specific about the fields and records to change.',
+      }
+    }
+    const filters = validateFilters(proposal.filters, resource)
+    let id = proposal.id
+    if (id !== null && !isValidId(id)) {
+      throw new OperationError(422, 'Choose a valid record ID.')
+    }
+    if (proposal.useSelection) {
+      if (
+        id !== null ||
+        context.resource !== resource.id ||
+        !isValidId(context.selection) ||
+        filters.children.length
+      ) {
+        throw new OperationError(422, 'Select a record or provide an explicit filter.')
+      }
+      id = context.selection
+    }
+    if (id !== null && filters.children.length) {
+      throw new OperationError(422, 'Use a record ID or a filter, not both.')
+    }
+    if (
+      proposal.sortBy &&
+      !resource.fields.some(
+        (field) =>
+          field.key === proposal.sortBy &&
+          !['json', 'multiselect', 'relation'].includes(field.kind),
+      )
+    ) {
+      throw new OperationError(422, 'This sort field is unavailable.')
+    }
+    if (
+      proposal.limit !== null &&
+      (!Number.isSafeInteger(proposal.limit) || proposal.limit < 1 || proposal.limit > MAX_RECORDS)
+    ) {
+      throw new OperationError(422, `Request between 1 and ${MAX_RECORDS} records.`)
+    }
+    if (operation === 'create') {
+      const missing = resource.fields.filter((field) => {
+        const value = proposal.input[field.key]
+        return (
+          field.required &&
+          resource.createFields.includes(field.key) &&
+          (value === undefined || value === null || (typeof value === 'string' && !value.trim()))
+        )
+      })
+      if (missing.length) {
+        return {
+          kind: 'clarification',
+          message: `Provide ${missing.map((field) => field.label).join(' and ')} to create ${resource.label.toLowerCase()}.`,
+        }
+      }
+    }
+    const input =
+      operation === 'create' || operation === 'update'
+        ? resource.validateInput(operation, proposal.input)
+        : {}
+    if (operation === 'update' && !Object.keys(proposal.input).length) {
+      throw new OperationError(422, 'Specify the fields to update.')
+    }
+    if (operation === 'create') {
+      if (id !== null || filters.children.length || proposal.useSelection) {
+        throw new OperationError(422, 'A new record cannot have a target filter.')
+      }
+      await resource.authorize(operation, undefined, input)
+      return prepare(
+        { resource: resource.id, operation, input, targets: [], many: false },
+        [],
+        resource,
+        context,
+      )
+    }
+    const mutating = operation === 'update' || operation === 'delete'
+    if ((mutating || operation === 'read') && id === null && !filters.children.length) {
+      return {
+        kind: 'clarification',
+        message:
+          'Select a record or add a filter, for example “delete user with email containing adriaansen”.',
+      }
+    }
+    // Mutations resolve the complete bounded match set. A user-supplied LIMIT must never hide targets.
+    const result =
+      id !== null
+        ? { data: [await resource.get(id)], totalCount: 1 }
+        : await resource.list({
+            page: 1,
+            pageSize: mutating ? MAX_RECORDS : (proposal.limit ?? MAX_RECORDS),
+            sortBy: proposal.sortBy ?? 'id',
+            sortDir: proposal.sortDir,
+            ...(filters.children.length ? { filters } : {}),
+          })
+    if (!mutating) {
+      // A filter resolves IDs through list access; read access can be narrower than list access.
+      const rows =
+        operation === 'read' && id === null
+          ? await Promise.all(result.data.map((row) => resource.get(row.id)))
+          : result.data
+      return {
+        kind: 'result',
+        resource: resource.id,
+        label: resource.label,
+        fields: resource.fields.filter((field) => resource.displayFields.includes(field.key)),
+        records: rows.map((row) => toDisplayRow(row, resource)),
+        totalCount: result.totalCount,
+      }
+    }
+    if (!result.totalCount) {
+      return { kind: 'clarification', message: 'No accessible records match that request.' }
+    }
+    if (result.totalCount > MAX_RECORDS || result.data.length !== result.totalCount) {
+      throw new OperationError(
+        422,
+        `More than ${MAX_RECORDS} records match. Add a narrower filter before changing them.`,
+      )
+    }
+    if (proposal.limit !== null && proposal.limit < result.totalCount) {
+      throw new OperationError(422, 'Use a narrower filter instead of LIMIT for a mutation.')
+    }
+    for (const row of result.data) {
+      await resource.authorize(operation, row.id, input)
+    }
+    const targets = await Promise.all(
+      result.data.map(async (row) => ({ id: row.id, fingerprint: await computeFingerprint(row) })),
+    )
+    return prepare(
+      { resource: resource.id, operation, input, targets, many: proposal.many },
+      result.data,
+      resource,
+      context,
+    )
+  }
+
+  async function prepare(
+    prepared: PreparedMutation,
+    rows: Row[],
+    resource: Resource,
+    context: Context,
+  ): Promise<PlanResult> {
+    const confirmation = await store.create(prepared, context)
+    return {
+      kind: 'confirmation',
+      key: confirmation.key,
+      resource: resource.id,
+      label: resource.label,
+      operation: prepared.operation,
+      input: writableInput(prepared, resource),
+      records: rows.map((row) => toDisplayRow(row, resource)),
+      many: prepared.many,
+      expiresAt: confirmation.expiresAt,
+      fields: resource.fields.filter((field) => resource.displayFields.includes(field.key)),
+    }
+  }
+
+  async function execute(key: string, selectedIds: number[], context: Context): Promise<Receipt> {
+    const confirmation = await store.get(key, context)
+    if (confirmation.actorId !== context.actorId || confirmation.sessionId !== context.sessionId) {
+      throw new OperationError(403, 'This confirmation belongs to another session.')
+    }
+    // Retrying a lost response returns the saved receipt; it never repeats a mutation.
+    if (confirmation.result && ['completed', 'failed'].includes(confirmation.state)) {
+      return confirmation.result
+    }
+    if (confirmation.expiresAt <= Date.now()) {
+      throw new OperationError(409, 'This confirmation expired. Submit the request again.')
+    }
+    if (confirmation.state !== 'pending') {
+      throw new OperationError(
+        409,
+        'This action is already running or was cancelled. Submit a new request after checking the results.',
+      )
+    }
+    const prepared = confirmation.plan
+    const resource = resourceFor(prepared.resource)
+    const targets = new Map(prepared.targets.map((target) => [target.id, target]))
+    supports(resource, prepared.operation)
+    if (
+      selectedIds.some((id) => !isValidId(id)) ||
+      new Set(selectedIds).size !== selectedIds.length ||
+      selectedIds.some((id) => !targets.has(id)) ||
+      (prepared.operation === 'create' ? selectedIds.length !== 0 : !selectedIds.length) ||
+      (!prepared.many && prepared.operation !== 'create' && selectedIds.length !== 1)
+    ) {
+      throw new OperationError(
+        422,
+        'Confirm only the reviewed records. Choose one record for a singular request.',
+      )
+    }
+    const input =
+      prepared.operation === 'delete'
+        ? {}
+        : resource.validateInput(prepared.operation, writableInput(prepared, resource))
+    async function recheck(id: number) {
+      const target = targets.get(id)!
+      const current = await resource.get(id)
+      if ((await computeFingerprint(current)) !== target.fingerprint) {
+        throw new OperationError(
+          409,
+          'A reviewed record changed. Submit the request again to review its current values.',
+        )
+      }
+      await resource.authorize(prepared.operation, id, input)
+    }
+    // Check every target before the first write, then check each again immediately before its write.
+    if (prepared.operation === 'create') {
+      await resource.authorize('create', undefined, input)
+    } else {
+      for (const id of selectedIds) {
+        await recheck(id)
+      }
+    }
+    await store.claim(confirmation, context)
+    const result: Receipt = {
+      resource: resource.id,
+      operation: prepared.operation,
+      completedIds: [],
+      success: true,
+    }
+    try {
+      if (prepared.operation === 'create') {
+        result.completedIds.push((await resource.create(input)).id)
+      } else {
+        for (const id of selectedIds) {
+          await recheck(id)
+          if (prepared.operation === 'delete') {
+            await resource.delete(id)
+          } else {
+            await resource.update(id, input)
+          }
+          result.completedIds.push(id)
+        }
+      }
+    } catch (cause) {
+      result.success = false
+      result.error = cause instanceof Error ? cause.message : 'The action could not be completed.'
+    }
+    // An unrecorded result must stay "executing" and cannot be retried as another mutation.
+    await store.finish(confirmation, result, context)
+    return result
+  }
+
+  async function cancel(key: string, context: Context) {
+    const confirmation = await store.get(key, context)
+    if (confirmation.actorId !== context.actorId || confirmation.sessionId !== context.sessionId) {
+      throw new OperationError(403, 'This confirmation belongs to another session.')
+    }
+    if (confirmation.state === 'pending') {
+      await store.cancel(confirmation, context)
+    }
+  }
+  return { plan, execute, cancel }
+}

package/core/index.ts

@@ -0,0 +1,3 @@
+export * from './types'
+export { createOperationEngine } from './engine'
+export { createDecisionPlanner } from './planner'

package/core/planner.ts

@@ -0,0 +1,67 @@
+import { choice, noul } from '@typesafe-ai/sdk'
+import { OperationError, OPERATIONS, type Operation, type Planner } from './types'
+import type { DecisionInference } from './decisions'
+
+export function createDecisionPlanner(
+  infer: DecisionInference,
+  extract: Planner['extract'],
+): Planner {
+  return {
+    async route(prompt, resources, context) {
+      const result = await infer({
+        state: {
+          request: prompt,
+          currentResource: context.resource ?? null,
+          selectedId: context.selection ?? null,
+        },
+        questions: {
+          resource: choice(
+            'Which resource does the requested operation concern? Explicit resource names override the current page. Use the current resource only for implicit requests such as delete this or rename it. Accept synonyms and obvious spelling mistakes. Choose none for editor commands, navigation, questions, or unsupported resources.',
+            {
+              ...Object.fromEntries(
+                resources.map((resource) => [
+                  resource.id,
+                  `${resource.label}; ${resource.aliases.join(', ')}`,
+                ]),
+              ),
+              none: 'No available CRUD resource fits.',
+            },
+          ),
+          operation: choice(
+            'Which one database operation is explicitly requested? A request to delete, remove or erase is delete even with typos. Updating existing fields is update. List/search/filter records is list. Read/open one identified record is read. Creating a record is create. Never interpret an edit or delete as a read-only query. Editor commands, file export, navigation and general questions are none.',
+            {
+              list: 'Find, filter, search, or list records.',
+              read: 'Read a single existing record.',
+              create: 'Create a new database record or upload a file.',
+              update: 'Change fields on existing records.',
+              delete: 'Delete existing database records.',
+              none: 'No CRUD operation is requested.',
+            },
+          ),
+          single_action: noul(
+            'Does the request describe at most ONE operation on ONE resource? Updating several fields or operating on several records of one resource is one operation. A conditional workflow, a sequence of different actions, or multiple resources is not supported.',
+          ),
+        },
+      })
+      const { resource, operation, single_action: single } = result.answers
+      if (
+        resource?.type !== 'choice' ||
+        operation?.type !== 'choice' ||
+        single?.type !== 'noul' ||
+        (!resources.some((entry) => entry.id === resource.choice) && resource.choice !== 'none') ||
+        (!OPERATIONS.some((entry) => entry === operation.choice) && operation.choice !== 'none')
+      ) {
+        throw new OperationError(502, 'The provider returned an unavailable action or resource.')
+      }
+      if (single.noul < 0.8) {
+        throw new OperationError(422, 'Request one action on one resource at a time.')
+      }
+      return {
+        resource: resource.choice === 'none' ? null : resource.choice,
+        operation: operation.choice === 'none' ? null : (operation.choice as Operation),
+        confidence: Math.min(resource.confidence, operation.confidence, single.noul),
+      }
+    },
+    extract,
+  }
+}

package/core/types.ts

@@ -0,0 +1,188 @@
+export const OPERATIONS = ['list', 'read', 'create', 'update', 'delete'] as const
+export type Operation = (typeof OPERATIONS)[number]
+export type Mutation = Extract<Operation, 'create' | 'update' | 'delete'>
+export type Row = { id: number; [key: string]: unknown }
+
+export type Scalar = string | number | boolean | null
+export interface Condition {
+  type: 'condition'
+  field: string
+  operator:
+    | 'eq'
+    | 'neq'
+    | 'like'
+    | 'not_contains'
+    | 'starts_with'
+    | 'ends_with'
+    | 'gt'
+    | 'gte'
+    | 'lt'
+    | 'lte'
+    | 'is_empty'
+    | 'is_not_empty'
+    | 'is_any_of'
+    | 'is_none_of'
+  value: Scalar | (string | number)[]
+}
+
+export interface Filters {
+  type: 'group'
+  logic: 'and' | 'or'
+  children: (Condition | Filters)[]
+}
+
+export interface Query {
+  page?: number
+  pageSize?: number
+  sortBy?: string
+  sortDir?: 'asc' | 'desc'
+  filters?: Filters
+}
+
+export interface Field {
+  key: string
+  label: string
+  kind: string
+  required: boolean
+  options?: readonly string[]
+  writable: boolean
+}
+
+export interface ResourceInfo {
+  id: string
+  label: string
+  aliases: readonly string[]
+  fields: readonly Field[]
+  operations: readonly Operation[]
+  /** Public fields shown in results. Large document bodies are deliberately omitted. */
+  displayFields: readonly string[]
+  createFields: readonly string[]
+  updateFields: readonly string[]
+  /** Storage creation must collect bytes through the host's existing upload flow. */
+  createHandoff?: string
+}
+
+export interface Resource extends ResourceInfo {
+  list(query: Query): Promise<{ data: Row[]; totalCount: number }>
+  get(id: number): Promise<Row>
+  create(input: Record<string, unknown>): Promise<Row>
+  update(id: number, input: Record<string, unknown>): Promise<Row>
+  delete(id: number): Promise<void>
+  /** Must use the host's actual access rules, including row and input-dependent rules. */
+  authorize(operation: Operation, id?: number, input?: Record<string, unknown>): Promise<void>
+  validateInput(
+    operation: 'create' | 'update',
+    input: Record<string, unknown>,
+  ): Record<string, unknown>
+}
+
+export interface Context {
+  actorId: string
+  sessionId: string
+  resource?: string
+  selection?: number
+}
+
+export interface Proposal {
+  supported: boolean
+  clarification: string
+  input: Record<string, unknown>
+  id: number | null
+  useSelection: boolean
+  many: boolean
+  filters: Filters
+  sortBy: string | null
+  sortDir: 'asc' | 'desc'
+  limit: number | null
+}
+
+export interface Route {
+  resource: string | null
+  operation: Operation | null
+  confidence: number
+}
+
+export interface Planner {
+  route(prompt: string, resources: readonly ResourceInfo[], context: Context): Promise<Route>
+  extract(
+    prompt: string,
+    resource: ResourceInfo,
+    operation: Operation,
+    context: Context,
+  ): Promise<Proposal>
+}
+
+export interface Target {
+  id: number
+  fingerprint: string
+}
+
+export interface PreparedMutation {
+  resource: string
+  operation: Mutation
+  input: Record<string, unknown>
+  targets: Target[]
+  many: boolean
+}
+
+export interface Receipt {
+  resource: string
+  operation: Mutation
+  completedIds: number[]
+  success: boolean
+  error?: string
+}
+
+export interface Confirmation {
+  key: string
+  actorId: string
+  sessionId: string
+  expiresAt: number
+  state: 'pending' | 'executing' | 'completed' | 'failed' | 'cancelled'
+  plan: PreparedMutation
+  result?: Receipt
+  revision: number
+}
+
+export interface ConfirmationStore {
+  create(plan: PreparedMutation, context: Context): Promise<Confirmation>
+  get(key: string, context: Context): Promise<Confirmation>
+  /** Atomic compare-and-swap. A competing claimant MUST fail before performing a write. */
+  claim(confirmation: Confirmation, context: Context): Promise<void>
+  finish(confirmation: Confirmation, result: Receipt, context: Context): Promise<void>
+  cancel(confirmation: Confirmation, context: Context): Promise<void>
+}
+
+export type PlanResult =
+  | { kind: 'fallback' }
+  | { kind: 'clarification'; message: string }
+  | { kind: 'handoff'; resource: string; action: string }
+  | {
+      kind: 'result'
+      resource: string
+      label: string
+      fields: readonly Field[]
+      records: Row[]
+      totalCount: number
+    }
+  | {
+      kind: 'confirmation'
+      key: string
+      resource: string
+      label: string
+      operation: Mutation
+      fields: readonly Field[]
+      records: Row[]
+      input: Record<string, unknown>
+      many: boolean
+      expiresAt: number
+    }
+
+export class OperationError extends Error {
+  constructor(
+    public readonly status: number,
+    message: string,
+  ) {
+    super(message)
+  }
+}