@nuxtagentic/prompt 0.0.0-stage → 0.1.0

package/LICENSE.md

@@ -0,0 +1,9 @@
+Proprietary software. All rights reserved.
+
+Use of Nuxt Agentic packages and starter materials is governed by the applicable
+commercial agreement supplied with a purchase. This repository does not grant
+an open-source license or permission to redistribute the packages as a competing
+template or module library.
+
+Third-party dependencies retain their respective licenses. This notice does not
+replace or modify those licenses.

package/README.md

@@ -1,3 +1,92 @@
-# Temporary Holding Version
+# Prompt
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+`@nuxtagentic/prompt` owns decision providers, prompt dispatch, schema-based query
+interpretation, and the plan/review/execute lifecycle. It installs Data and has no
+dependency on a particular collection UI. The root app supplies the prompt and review
+dialog; installed features supply their tools, model views, and resource adapters.
+
+This shared prompt engine serves the workspace input. The separate
+[`@nuxtagentic/agents`](../agents/README.md) package manages saved agent
+definitions and their runs. The `/api/agent` endpoints and `agentOperation`
+confirmation model retain their existing names.
+
+The prompt uses registered feature aliases, tools, and model views. Agents,
+Integrations, and Automations contribute their navigation and planning metadata.
+New domain features can add structured parsing and natural-language actions
+through the same contracts without a separate prompt engine.
+
+## Setup
+
+Include `agentOperationsModels` from `@nuxtagentic/prompt/schema` in the host's
+`cloud.config.ts`, then generate, review, and apply the CloudConfig migration.
+The confirmation store must exist before planning mutations.
+
+Set `NUXT_DECISION_PROVIDER` to `typesafeAI` (default) or `openAI`, and configure
+`NUXT_TYPESAFE_API_KEY` or `NUXT_OPENAI_API_KEY` on the server.
+`NUXT_OPENAI_DECISION_MODEL` overrides the default OpenAI decision model,
+`gpt-6-luna`. Restart or redeploy after changing settings. Provider keys stay out
+of public runtime config.
+
+## Follow a request
+
+| Endpoint                  | Purpose                                                             |
+| ------------------------- | ------------------------------------------------------------------- |
+| `POST /api/agent`         | Route a collection prompt and produce validated tool arguments      |
+| `POST /api/agent/plan`    | Return results, clarification, upload handoff, or a mutation review |
+| `POST /api/agent/execute` | Execute a review key and selected IDs; return a receipt             |
+| `POST /api/agent/cancel`  | Cancel a pending review                                             |
+
+Both providers select typed choices for resources, operations, fields, operators,
+and literal values. Choices come from registered schemas and the request text.
+The application constructs and validates filters and writes; providers do not
+supply arbitrary SQL or execute tools. Missing required fields produce a specific
+clarification. Unsupported values and ambiguous timestamps remain reviewable errors.
+
+Feature metadata enters through `#workspace/client` and `#workspace/server`.
+A feature's `runtime/shared/agent.ts` contributes public views, tools, aliases,
+and exclusions. Its `runtime/server/contribution.ts` can add authenticated
+resource factories for its own data and actions. There is no host-level action or model-view configuration file.
+
+Only models contributed through installed resource aliases or model views enter
+the agent catalog. Keeping a removed feature's schema does not expose its records
+or internal workflows. Custom models retain schema-derived fields and operations;
+register their aliases or views to make them available.
+
+Editor commands live in each feature's `runtime/actions.ts` and execute through
+Workspace's registered handlers. They remain separate from database mutations.
+
+## Mutation guarantees
+
+Every mutation opens a review. Updates and deletes require an ID, current
+selection, or a nonempty filter matching at most 25 accessible records. LIMIT
+cannot silently truncate mutation targets. Singular requests select one record;
+plural requests can select a subset.
+
+Reviews bind the proposed input, candidate IDs, and fingerprints to the account
+and session and expire after ten minutes. Execution accepts the key and reviewed
+IDs, not replacement fields or filters. It checks authorization and freshness,
+claims the review atomically, and stores the receipt for retries.
+
+Batches execute sequentially. A partial failure records completed IDs and prevents
+replay. This is not a cross-model transaction; an uncertain execution stays blocked
+until its outcome is known. CloudConfig still enforces model rules, validation,
+hooks, and storage cleanup for each write.
+
+## Find the code
+
+| Area                                         | Owner                                                                                          |
+| -------------------------------------------- | ---------------------------------------------------------------------------------------------- |
+| Framework-independent planning and execution | [`core/`](core/)                                                                               |
+| CloudConfig resources                        | [`cloudconfig.ts`](cloudconfig.ts)                                                             |
+| Provider selection and HTTP adapters         | [`runtime/server/utils/decision-provider.ts`](runtime/server/utils/decision-provider.ts)       |
+| Collection routing                           | [`runtime/server/utils/jev-dispatch.ts`](runtime/server/utils/jev-dispatch.ts)                 |
+| Mutation arguments                           | [`runtime/server/utils/decision-arguments.ts`](runtime/server/utils/decision-arguments.ts)     |
+| Model query compilation                      | [`runtime/server/utils/model-query.ts`](runtime/server/utils/model-query.ts)                   |
+| Authenticated operation host                 | [`runtime/server/utils/agent-operations.ts`](runtime/server/utils/agent-operations.ts)         |
+| Durable reviews and receipts                 | [`runtime/server/confirmations.ts`](runtime/server/confirmations.ts), [`schema.ts`](schema.ts) |
+| Query limits and inference policy            | [`config.ts`](config.ts)                                                                       |
+| Review dialog                                | Host application: `app/components/AgentOperationDialog.vue`                                    |
+
+[How search works](docs/search.md) covers local parsing, collection registration,
+and provider boundaries. Regression tests live in `tests/`; the host's
+`pnpm test:workspace` includes them. Default verification remains `pnpm typecheck`.

package/cloudconfig.ts

@@ -0,0 +1,165 @@
+import type { AnyConfig, CloudConfigUser, FilterNode } from '@cloudconfig/core'
+import { compileConfig, publicModels, toInputSchema } from '@cloudconfig/core/server'
+import {
+  OPERATIONS,
+  OperationError,
+  type Field,
+  type Query,
+  type Resource,
+  type Row,
+} from './core/types'
+import { isRecord } from './core/validation'
+
+/** Type erasure is confined to the registry boundary; hosts instantiate the generated typed clients. */
+export interface ModelSource {
+  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>
+}
+interface AdapterOptions {
+  user: CloudConfigUser
+  request: Request
+  source: (name: string) => ModelSource
+  /** Used only for permission preflight predicates that refer to private ownership fields. */
+  privateSource: (name: string) => Pick<ModelSource, 'list'>
+  include?: readonly string[]
+  exclude?: readonly string[]
+  aliases?: Record<string, readonly string[]>
+  lockedFields?: readonly string[]
+}
+
+/** Derive capabilities and public write schemas from the SAME config as the generated REST API. */
+export function createCloudConfigResources(config: AnyConfig, options: AdapterOptions): Resource[] {
+  const base = compileConfig(config)
+  const locked = new Set(options.lockedFields ?? ['ownerId', 'editorIds', 'viewerIds'])
+  return publicModels(base)
+    .filter(
+      (model) =>
+        (!options.include || options.include.includes(model.name)) &&
+        !options.exclude?.includes(model.name),
+    )
+    .map((model) => {
+      const source = options.source(model.name)
+      const fields: Field[] = [
+        { key: 'id', label: 'ID', kind: 'number', required: false, writable: false },
+        ...Object.values(model.fieldSpecs)
+          .filter(({ spec }) => !spec.serverOnly)
+          .map(({ columnKey, spec }) => ({
+            key: columnKey,
+            label: spec.label ?? columnKey,
+            kind: spec.kind,
+            required: spec.required && !spec.hasDefault && !locked.has(columnKey),
+            options: spec.options,
+            writable: !locked.has(columnKey),
+          })),
+        ...(model.timestamps
+          ? ['createdAt', 'updatedAt'].map((key) => ({
+              key,
+              label: key,
+              kind: 'datetime',
+              required: false,
+              writable: false,
+            }))
+          : []),
+      ]
+      const schemaKeys = (schema: typeof model.create) =>
+        Object.keys((toInputSchema(schema).properties ?? {}) as Record<string, unknown>).filter(
+          (key) => !locked.has(key),
+        )
+      const createFields = schemaKeys(model.create)
+      const updateFields = schemaKeys(model.update)
+      for (const field of fields) {
+        field.writable = createFields.includes(field.key) || updateFields.includes(field.key)
+      }
+      const operations = OPERATIONS.filter(
+        (action) => model.model.options.access?.[action] || base.accessDefault === 'allow',
+      )
+      const resource: Resource = {
+        id: model.name,
+        label: model.label,
+        aliases: [model.name, model.namePlural, ...(options.aliases?.[model.name] ?? [])],
+        fields,
+        operations,
+        createFields,
+        updateFields,
+        displayFields: fields
+          .filter(
+            (field) =>
+              !['json', 'multiselect', 'relation'].includes(field.kind) && !locked.has(field.key),
+          )
+          .map((field) => field.key),
+        ...(model.model.options.storage ? { createHandoff: `upload:${model.name}` } : {}),
+        list: (query) => source.list(query),
+        get: (id) => source.get(id),
+        create: (input) => source.create(input),
+        update: (id, input) => source.update(id, input),
+        delete: (id) => source.delete(id),
+        validateInput(action, input) {
+          const allowed = action === 'create' ? createFields : updateFields
+          if (!isRecord(input) || Object.keys(input).some((key) => !allowed.includes(key))) {
+            throw new OperationError(
+              422,
+              'The action contains a server-managed or unavailable field.',
+            )
+          }
+          // A public ownership column is assigned from the authenticated session, never from AI input.
+          const supplied = { ...input }
+          if (
+            action === 'create' &&
+            model.fieldSpecs.ownerId &&
+            !model.fieldSpecs.ownerId.spec.serverOnly
+          ) {
+            supplied.ownerId = options.user.id
+          }
+          const parsed = (action === 'create' ? model.create : model.update).safeParse(supplied)
+          if (!parsed.success) {
+            const first = parsed.error.issues[0]
+            throw new OperationError(
+              422,
+              first ? `${first.path.join('.')}: ${first.message}` : 'Invalid record fields.',
+            )
+          }
+          if (!isRecord(parsed.data)) {
+            throw new OperationError(422, 'Invalid record fields.')
+          }
+          return parsed.data
+        },
+        async authorize(action, id, input) {
+          const rule = model.model.options.access?.[action]
+          const result = rule
+            ? await rule({
+                user: options.user,
+                request: options.request,
+                action,
+                ...(id !== undefined ? { id } : {}),
+                ...(input !== undefined ? { input } : {}),
+                where: (field, operator, value) => ({ type: 'condition', field, operator, value }),
+              })
+            : base.accessDefault === 'allow'
+          if (result === false) {
+            throw new OperationError(403, `You cannot ${action} ${model.label.toLowerCase()}.`)
+          }
+          if (typeof result !== 'boolean' && id !== undefined) {
+            const filters = {
+              type: 'group' as const,
+              logic: 'and' as const,
+              children: [
+                { type: 'condition' as const, field: 'id', operator: 'eq' as const, value: id },
+                result as FilterNode,
+              ],
+            }
+            // CloudConfig evaluates the list rule and this write predicate together. Private rows stay here.
+            const found = await options
+              .privateSource(model.name)
+              .list({ page: 1, pageSize: 1, filters })
+            if (!found.data.length) {
+              throw new OperationError(403, `You cannot ${action} this record.`)
+            }
+          }
+        },
+      }
+      return resource
+    })
+}

package/config.ts

@@ -0,0 +1,33 @@
+import type { PromptConfig } from './runtime/shared/prompt-config'
+
+export const MODEL_QUERY_CONFIG = {
+  model: 'jev-latest',
+  maxConstraintsPerField: 4,
+  candidates: { span: 24, text: 200, maxWords: 8 },
+  routing: { maxInlineModels: 2, maxInlineQuestions: 120, maxInlineBytes: 64000 },
+  inference: { deadlineMs: 10000, timeoutMs: 5000, maxRetries: 1 },
+  rerank: {
+    maxFiles: 12,
+    excerptChars: 500,
+    queryChars: 300,
+    nameChars: 255,
+    folderChars: 80,
+    mimeTypeChars: 100,
+    deadlineMs: 5000,
+    timeoutMs: 3000,
+    maxRetries: 0,
+  },
+  logMetrics: false,
+  instructions: [
+    'Interpret the intended read-only query, whether written as SQL, shorthand, or natural language.',
+    'Accept omitted WHERE, missing operators, singular/plural names, reordered words, synonyms, and obvious spelling mistakes when the allowed schema makes the intent clear.',
+    'For boolean fields, true/yes/on/1 mean true and false/no/off/0 mean false. Respect negation and the meaning of the field.',
+    'A boolean adjective alone is a filter. A field followed by a value implies equality unless a different comparison is requested.',
+    'Use field keys, labels, and optional field hints to match concepts. Never invent a field, value, or constraint, and never discard an unsupported part of the request.',
+    'Treat text values as data: preserve their spelling, punctuation, and full wording. Correct spelling only when matching schema vocabulary.',
+    'Expand IN/one-of alternatives into equality constraints joined with OR; NOT IN/excluding alternatives into inequality constraints joined with AND. A range has two comparisons.',
+    'Number distinct constraints on each field by their appearance in the request. A named date period is one constraint. Do not repeat a constraint in another slot.',
+    'A range uses two constraints, each IN/NOT IN value uses one. Generic search is separate from explicit field filters. Not mentioned and mentioned with an unavailable value are different outcomes.',
+    'Month names without a year use the current UTC year from referenceDate. Compare named date periods as a whole: = means during, != means outside, > means after the period ends, >= means from its start, < means before its start, and <= means through its end.',
+  ].join(' '),
+} satisfies PromptConfig

package/core/decisions.ts

@@ -0,0 +1,155 @@
+import type { EntryType, Questions, SystemOneRequest, SystemOneResult } from '@typesafe-ai/sdk'
+import { OperationError } from './types'
+import { isRecord } from './validation'
+
+export type DecisionResult = SystemOneResult<Questions>
+export type DecisionInference = (request: SystemOneRequest) => Promise<DecisionResult>
+export type DecisionInput = {
+  role: 'user'
+  content: ({ type: 'input_text'; text: string } | { type: 'input_image'; image_url: string })[]
+}[]
+
+const text = (value: EntryType | undefined) =>
+  typeof value === 'string' ? value : JSON.stringify(value ?? '')
+const probability = (value: unknown): value is number =>
+  typeof value === 'number' && Number.isFinite(value) && value >= 0 && value <= 1
+
+export function openAIDecisionBody(
+  request: SystemOneRequest,
+  model: string,
+  input?: DecisionInput,
+) {
+  return {
+    model,
+    input: input ?? text(request.state),
+    questions: Object.entries(request.questions).map(([name, question]) => {
+      const base = { name, instructions: text(question.instructions) }
+      switch (question.type) {
+        case 'choice':
+          return {
+            ...base,
+            type: 'choice',
+            choices: Object.entries(question.criteria).map(([value, description]) => ({
+              value,
+              description: text(description),
+            })),
+          }
+        case 'noul':
+          return {
+            ...base,
+            type: 'predicate',
+            instructions: question.criteria
+              ? `${base.instructions} Outcome criteria: ${text(question.criteria)}`
+              : base.instructions,
+          }
+        case 'score':
+          return {
+            ...base,
+            type: 'score',
+            levels: question.criteria.map((description, index) => ({
+              label: String(index),
+              description: text(description),
+            })),
+          }
+      }
+    }),
+  }
+}
+
+export function readOpenAIDecisions(
+  value: unknown,
+  request: SystemOneRequest,
+  model: string,
+): DecisionResult {
+  if (!isRecord(value) || !Array.isArray(value.answers)) {
+    throw new OperationError(502, 'OpenAI returned an invalid decision.')
+  }
+  const answers: Record<string, DecisionResult['answers'][string]> = {}
+  for (const answer of value.answers) {
+    if (
+      !isRecord(answer) ||
+      typeof answer.name !== 'string' ||
+      Object.hasOwn(answers, answer.name)
+    ) {
+      throw new OperationError(502, 'OpenAI returned an invalid decision.')
+    }
+    const {
+      name,
+      type,
+      probability: answerProbability,
+      confidence,
+      probabilities: answerProbabilities,
+      choice,
+      score,
+    } = answer
+    if (type === 'refusal') {
+      throw new OperationError(
+        422,
+        'The request could not be interpreted. Rephrase the action and resource.',
+      )
+    }
+    const question = request.questions[name]
+    if (!question) {
+      throw new OperationError(502, 'OpenAI returned an unavailable decision.')
+    }
+    if (type === 'predicate' && question.type === 'noul') {
+      if (!probability(answerProbability)) {
+        throw new OperationError(502, 'OpenAI returned an invalid probability.')
+      }
+      answers[name] = { type: 'noul', noul: answerProbability }
+      continue
+    }
+    if (!probability(confidence)) {
+      throw new OperationError(502, 'OpenAI returned an invalid confidence.')
+    }
+    const probabilities = Object.fromEntries(
+      (Array.isArray(answerProbabilities) ? answerProbabilities : []).map((item) => {
+        if (!isRecord(item) || !probability(item.probability)) {
+          throw new OperationError(502, 'OpenAI returned invalid probabilities.')
+        }
+        return [String(item.value), item.probability]
+      }),
+    )
+    if (type === 'choice' && question.type === 'choice') {
+      if (typeof choice !== 'string' || !Object.hasOwn(question.criteria, choice)) {
+        throw new OperationError(502, 'OpenAI returned an unavailable choice.')
+      }
+      answers[name] = {
+        type: 'choice',
+        choice,
+        confidence,
+        probabilities,
+      }
+    } else if (type === 'score' && question.type === 'score') {
+      if (
+        typeof score !== 'number' ||
+        !Number.isFinite(score) ||
+        score < 0 ||
+        score > question.criteria.length - 1
+      ) {
+        throw new OperationError(502, 'OpenAI returned an invalid score.')
+      }
+      answers[name] = {
+        type: 'score',
+        score,
+        confidence,
+        probabilities,
+        legend: Object.fromEntries(question.criteria.map((level, index) => [index, level])),
+      }
+    } else {
+      throw new OperationError(502, 'OpenAI returned an invalid decision type.')
+    }
+  }
+  if (Object.keys(request.questions).some((name) => !Object.hasOwn(answers, name))) {
+    throw new OperationError(502, 'OpenAI omitted a decision.')
+  }
+  const usage = isRecord(value.usage) ? value.usage : {}
+  return {
+    model: typeof value.model === 'string' ? value.model : model,
+    answers,
+    usage: {
+      input_tokens: Number(usage.input_tokens ?? 0),
+      output_tokens: Number(usage.output_tokens ?? 0),
+    },
+  }
+}