@adonis-agora/agent 0.1.0

package/dist/src/types.d.ts

@@ -0,0 +1,222 @@
+import type { StandardSchemaV1 } from '@standard-schema/spec';
+/** Who is driving the turn. Roles + tenant come from the host app (nestjs-context/authz). */
+export interface Actor {
+    id: string;
+    /** The caller's roles. Tool authorization is a set intersection against a tool's `roles`. */
+    roles?: string[];
+    tenantRef?: string;
+}
+export type ToolKind = 'read' | 'action' | 'agent';
+/**
+ * Declared shape of a tool.
+ *  - `read`   auto-executes.
+ *  - `action` never auto-executes — requires HITL approval.
+ *  - `agent`  delegates to another named agent (durable: a child workflow; inline: a nested loop),
+ *             handled at the loop level — NOT via a handler. Carries `targetAgent`.
+ */
+export interface ToolSpec {
+    name: string;
+    kind: ToolKind;
+    description: string;
+    /**
+     * Input schema as a [Standard Schema](https://standardschema.dev) — validation-agnostic, so
+     * Zod, Valibot, or ArkType all work. The loop validates input via `~standard.validate` before
+     * running the handler, and providers convert it to the model's tool-parameter JSON schema.
+     */
+    inputSchema: StandardSchemaV1;
+    /** For `kind: 'agent'` — the name of the agent to delegate to. */
+    targetAgent?: string;
+    /** Roles allowed to invoke. Undefined → defaults applied by RolesPolicy (e.g. ADMIN-only). */
+    roles?: string[];
+    /**
+     * An authorization ability name (e.g. 'cache.purge'). Consumed by an ability-aware RolesPolicy
+     * such as the `@dudousxd/nestjs-agent-authz` Gate adapter. Apps that don't use authz ignore it
+     * and rely on `roles` instead — both live on the same SPI, so neither is required.
+     */
+    ability?: string;
+}
+/** What the model is told a tool looks like (no handler, no host types). */
+export interface ToolDefinition {
+    name: string;
+    kind: ToolKind;
+    description: string;
+    inputSchema: StandardSchemaV1;
+}
+/** A tool call the model asked for during a turn. */
+export interface ToolCallRequest {
+    id: string;
+    name: string;
+    input: unknown;
+}
+/** Result of running a tool. */
+export interface ToolResult {
+    id: string;
+    name: string;
+    output: unknown;
+    error?: string;
+}
+export interface MessageUsage {
+    /**
+     * Total input (prompt) tokens for the turn — the whole input side, cached and uncached alike.
+     * `cacheWriteTokens` + `cacheReadTokens` are subsets of this count, not additions to it, so
+     * token totals and quota never change when a breakdown is present.
+     */
+    inputTokens: number;
+    /** Total output (completion) tokens for the turn; `reasoningTokens` is a subset of this. */
+    outputTokens: number;
+    /**
+     * How many of `inputTokens` were written to the prompt cache this turn (billed at a premium,
+     * ~1.25× base input). Undefined when the provider doesn't report caching. Refines the cost
+     * estimate only — priced by the pricing row's cache-write rate (falling back to the input rate).
+     */
+    cacheWriteTokens?: number;
+    /**
+     * How many of `inputTokens` were served from the prompt cache this turn (billed at a discount,
+     * ~0.1× base input). Undefined when the provider doesn't report caching.
+     */
+    cacheReadTokens?: number;
+    /**
+     * How many of `outputTokens` the model spent on reasoning/thinking. Observability only — reasoning
+     * tokens are billed at the output rate, so they don't change the cost estimate. Undefined for
+     * non-reasoning models or providers that don't report it.
+     */
+    reasoningTokens?: number;
+    /**
+     * This turn's USD cost: the provider's own reported figure when it has one (a gateway), else an
+     * estimate from the bound `AgentPricingStore` (cached once per run — see `AgentLoopDeps.pricingStore`),
+     * else `null` when no pricing store is bound or the model has no price row. Never `0` for an unpriced
+     * model — a real $0 turn and "we don't know" must stay distinguishable. Undefined before the loop
+     * folds cost (e.g. a plain usage struct that predates pricing).
+     */
+    costUsd?: number | null;
+}
+export type UsagePurpose = 'chat' | 'title' | 'follow_ups' | 'summary';
+export interface QuotaState {
+    usedTokens: number;
+    limitTokens: number;
+    withinLimit: boolean;
+}
+/** A human decision on a pending action tool call. */
+export interface Decision {
+    approved: boolean;
+    reason?: string;
+}
+export type MessageRole = 'user' | 'assistant' | 'system';
+/**
+ * A file a user attached to a message so a vision-capable model sees it natively (an image, a PDF).
+ * The lib stays provider-agnostic: it passes {@link MessageAttachment.url} straight through as the
+ * model's image/file part data — making that URL reachable by the provider (a presigned URL, a proxy,
+ * or a `data:` URI) is the consumer's job. The lib never fetches bytes or talks to a store; that
+ * upload-time work is the {@link import('./spi/attachment-staging.js').AttachmentStagingStore} seam.
+ */
+export interface MessageAttachment {
+    /** Stable id of the stored media object in the consumer's media store. Provenance + replay key. */
+    mediaId: string;
+    /** A URL the model provider can fetch the bytes from at turn time. */
+    url: string;
+    /** MIME type — routes the part: `image/*` → image part, otherwise → file part. */
+    contentType: string;
+    /** Original filename, for display and the file part's filename. */
+    name: string;
+}
+/** A neutral chat message exchanged with the model. */
+export interface ModelMessage {
+    role: MessageRole;
+    content: string;
+    toolCalls?: ToolCallRequest[];
+    toolResults?: ToolResult[];
+    /** User-message attachments (image/PDF), rendered as native model content parts by the adapter. */
+    attachments?: MessageAttachment[];
+}
+export interface PageContext {
+    kind?: string;
+    [key: string]: unknown;
+}
+/**
+ * Inputs a {@link PromptBuilder} may use to compose the effective system prompt for a turn.
+ * `basePrompt` is the agent's own (already-resolved) base prompt, so a persona builder can wrap
+ * or extend it rather than replace it.
+ */
+export interface PromptContext {
+    actor: Actor;
+    persona?: Persona;
+    pageContext?: PageContext;
+    basePrompt: string;
+}
+/**
+ * A dynamic system prompt. Return a string (optionally async) built from the turn's context —
+ * e.g. injecting the actor, the current page, or a data-shape description. The loop resolves it
+ * once per turn from stable inputs (actor/persona/pageContext), so it stays replay-safe.
+ */
+export type PromptBuilder = (ctx: PromptContext) => string | Promise<string>;
+export interface Persona {
+    id: string;
+    label: string;
+    /** A flat prompt, or a {@link PromptBuilder} composed per request from {@link PromptContext}. */
+    systemPrompt: string | PromptBuilder;
+    /** If set, only these tool names are offered (after role filtering). */
+    allowedTools?: string[];
+}
+/** Everything needed to run one agent turn. */
+export interface AgentRunInput {
+    threadId: string;
+    actor: Actor;
+    /** The latest user message text. */
+    userText: string;
+    /** Files attached to the latest user message (image/PDF). Persisted with it and sent to the model. */
+    attachments?: MessageAttachment[];
+    persona?: Persona;
+    pageContext?: PageContext;
+    isRegenerate?: boolean;
+    /** YYYY-MM-DD stamped by the runner so quota/day stays deterministic under durable replay. */
+    day?: string;
+    /** Which named agent runs this turn. Omitted → the default/single agent. */
+    agentName?: string;
+}
+/**
+ * A named agent: its prompt, the tools it may use, and its personas. Multiple definitions are
+ * registered via `AgentModule.forFeature([...])`; an orchestrator delegates to others through
+ * `ctx.runAgent(name, task)`. Model/store/sink/governance are shared from the module unless
+ * overridden here.
+ */
+export interface AgentDefinition {
+    name: string;
+    /** Base prompt for this agent. A flat string, or a {@link PromptBuilder} resolved per turn. */
+    systemPrompt?: string | PromptBuilder;
+    /** Allow-list of tool names this agent may use (subset of all registered tools). */
+    tools?: string[];
+    /** Names of other agents this agent may delegate to (auto-registered as `agent`-kind tools). */
+    delegatesTo?: string[];
+    personas?: Persona[];
+    defaultPersona?: string;
+    modelId?: string;
+    maxSteps?: number;
+}
+export interface ThreadSummary {
+    id: string;
+    title: string;
+    persona: string;
+    pinnedAt?: string;
+    transient: boolean;
+    createdAt: string;
+    updatedAt: string;
+    lastMessagePreview?: string;
+}
+export interface StoredMessage {
+    id: string;
+    role: MessageRole;
+    content: string;
+    toolCalls?: ToolCallRequest[];
+    toolResults?: ToolResult[];
+    /** Files the user attached to this message (image/PDF). Persisted with the message, replayed as-is. */
+    attachments?: MessageAttachment[];
+    followUps?: string[];
+    usage?: MessageUsage;
+    createdAt: string;
+}
+export interface ThreadDetail extends ThreadSummary {
+    messages: StoredMessage[];
+    activeStreamId?: string;
+}
+export type ToolCallStatus = 'auto_executed' | 'pending_approval' | 'executed' | 'rejected' | 'failed';
+//# sourceMappingURL=types.d.ts.map

package/dist/src/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/types.ts"],"names":[],"mappings":"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"}

package/dist/src/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/src/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/types.ts"],"names":[],"mappings":""}

package/dist/stubs/config/agent.stub

@@ -0,0 +1,55 @@
+{{{
+  exports({ to: app.configPath('agent.ts') })
+}}}
+import { defineConfig, stores, AuthActorResolver } from '@adonis-agora/agent'
+// import { attachmentStores } from '@adonis-agora/agent'
+// import { aiSdkModel } from '@adonis-agora/agent/ai-sdk'
+// import { openai } from '@ai-sdk/openai'
+
+/**
+ * Configuration for @adonis-agora/agent. Only `model` is required. Pick a `store` by name from the
+ * `stores` map (each driver's peer is imported lazily, only when selected); omit `store` for the
+ * in-memory store. The runner is in-process by default (`durable` is deferred). The actor resolver
+ * defaults to one that THROWS — the agent never fabricates a caller — so wire a real one.
+ *
+ * Publish the tables with `node ace migration:run` after configuring.
+ */
+export default defineConfig({
+  /**
+   * The LLM provider. Wrap the Vercel AI SDK via `aiSdkModel(...)` (from `@adonis-agora/agent/ai-sdk`)
+   * or supply any `ModelProvider`. A lazy thunk keeps the provider SDK peer imported only at boot:
+   *
+   *   model: () => aiSdkModel({ model: openai('gpt-4o-mini') }),
+   */
+  model: () => {
+    throw new Error('Configure a model in config/agent.ts (e.g. aiSdkModel({ model: ... }))')
+  },
+
+  store: 'lucid',
+  stores: {
+    memory: stores.memory(),
+    lucid: stores.lucid(),
+  },
+
+  // Identity seam — reads ctx.auth.user (fail-closed: throws when unauthenticated). Swap for your own
+  // resolver, or HeaderActorResolver behind a trusted gateway.
+  actorResolver: new AuthActorResolver(),
+
+  // path: 'agent',            // → /agent/chat, /agent/threads, ...
+  // defaultRoles: ['ADMIN'],  // roles a tool requires when it declares none (fail-closed)
+  // maxSteps: 8,              // cap on model↔tool iterations per turn
+
+  // Multimodal uploads — mounts POST /agent/attachments, which stages a file into a model-fetchable
+  // MessageAttachment the client sends back with its next chat message. Bind your own store (presign
+  // S3/GCS or wrap your media pipeline); `attachmentStores.memory()` inlines bytes as a data: URL.
+  // attachmentStaging: attachmentStores.memory(),
+  // attachmentMaxBytes: 20 * 1024 * 1024,
+  // attachmentAllowedContentTypes: ['image/png', 'image/jpeg', 'application/pdf'],
+
+  // The implicit default agent (base prompt, personas, tool allow-list). Omit for a bare assistant.
+  // defaultAgent: {
+  //   systemPrompt: 'You are a helpful assistant.',
+  //   personas: [{ id: 'default', label: 'Default', systemPrompt: 'You are a helpful assistant.' }],
+  //   defaultPersona: 'default',
+  // },
+})

package/dist/stubs/database/migrations/create_agent_rag_chunks.stub

@@ -0,0 +1,41 @@
+{{{
+  exports({ to: app.migrationsPath(`${new Date().getTime()}_create_agent_rag_chunks.ts`) })
+}}}
+import { BaseSchema } from '@adonisjs/lucid/schema'
+
+/**
+ * The pgvector chunk table for the @adonis-agora/agent `retrievers.pgvector({...})` store: one row per
+ * embedded chunk (id `${documentId}#<n>`), the chunk text, an optional citation source, a `jsonb`
+ * metadata column filtered with `@>`, and the `vector(N)` embedding ranked with the `<=>`/`<->`/`<#>`
+ * operators. Requires the pgvector extension (`CREATE EXTENSION vector`) — Postgres only.
+ *
+ * Set `DIMENSION` to your embedding model's width (e.g. 1536 for text-embedding-3-small) and `OPCLASS`
+ * to the index operator class matching the store's metric: `vector_cosine_ops` (default),
+ * `vector_l2_ops`, or `vector_ip_ops`.
+ */
+const TABLE = 'agent_rag_chunks'
+const DIMENSION = 1536
+const OPCLASS = 'vector_cosine_ops'
+
+export default class extends BaseSchema {
+  async up() {
+    this.schema.raw('CREATE EXTENSION IF NOT EXISTS vector')
+
+    this.schema.createTable(TABLE, (table) => {
+      table.text('id').primary()
+      table.text('text').notNullable()
+      table.text('source')
+      table.jsonb('metadata')
+      table.specificType('embedding', `vector(${DIMENSION})`).notNullable()
+    })
+
+    // Approximate-nearest-neighbour index for the configured metric. Drop it to fall back to an exact scan.
+    this.schema.raw(
+      `CREATE INDEX IF NOT EXISTS ${TABLE}_embedding_idx ON ${TABLE} USING hnsw (embedding ${OPCLASS})`
+    )
+  }
+
+  async down() {
+    this.schema.dropTableIfExists(TABLE)
+  }
+}

package/dist/stubs/database/migrations/create_agent_run_tracking.stub

@@ -0,0 +1,80 @@
+{{{
+  exports({ to: app.migrationsPath(`${new Date().getTime()}_create_agent_run_tracking.ts`) })
+}}}
+import { BaseSchema } from '@adonisjs/lucid/schema'
+
+/**
+ * Additive migration for @adonis-agora/agent RUN tracking. Adds the `agent_run` table (one row per
+ * run/turn lifecycle) plus a nullable `run_id` correlation column on `agent_message`,
+ * `agent_tool_call` and `agent_token_usage`. `run_id` is deliberately NOT a DB foreign key (like the
+ * reference): it can be `ALTER TABLE ADD COLUMN`-ed portably (SQLite can't add a column WITH a FK
+ * constraint) and a row written before this shipped keeps a `null` run_id.
+ *
+ * Timestamps are epoch-ms integers, booleans INTEGER (0/1) and cost a DOUBLE, matching
+ * `create_agent_tables` so the schema stays portable across SQLite / Postgres / MySQL. Safe to run on
+ * an existing deployment: it only creates a new table and adds nullable columns.
+ */
+export default class extends BaseSchema {
+  async up() {
+    this.schema.createTable('agent_run', (table) => {
+      table.string('id').primary()
+      table
+        .string('thread_id')
+        .notNullable()
+        .references('id')
+        .inTable('agent_thread')
+        .onDelete('CASCADE')
+      table.string('agent_name')
+      table.string('actor_ref').notNullable()
+      table.string('tenant_ref')
+      table.string('status').notNullable()
+      table.bigInteger('started_at').notNullable()
+      table.bigInteger('finished_at')
+      table.integer('step_count').notNullable().defaultTo(0)
+      table.integer('input_tokens').notNullable().defaultTo(0)
+      table.integer('output_tokens').notNullable().defaultTo(0)
+      table.double('cost_usd')
+      table.text('error')
+      table.integer('durable').notNullable().defaultTo(0)
+      table.index(['started_at'], 'agent_run_started_idx')
+      table.index(['actor_ref', 'started_at'], 'agent_run_actor_started_idx')
+      table.index(['status', 'started_at'], 'agent_run_status_started_idx')
+    })
+
+    this.schema.alterTable('agent_message', (table) => {
+      table.string('run_id')
+      table.index(['run_id'], 'agent_message_run_idx')
+    })
+
+    this.schema.alterTable('agent_tool_call', (table) => {
+      table.string('run_id')
+      table.index(['run_id'], 'agent_tool_call_run_idx')
+      table.index(['status', 'created_at'], 'agent_tool_call_status_created_idx')
+    })
+
+    this.schema.alterTable('agent_token_usage', (table) => {
+      table.string('run_id')
+      table.index(['run_id'], 'agent_token_usage_run_idx')
+    })
+  }
+
+  async down() {
+    this.schema.alterTable('agent_token_usage', (table) => {
+      table.dropIndex(['run_id'], 'agent_token_usage_run_idx')
+      table.dropColumn('run_id')
+    })
+
+    this.schema.alterTable('agent_tool_call', (table) => {
+      table.dropIndex(['status', 'created_at'], 'agent_tool_call_status_created_idx')
+      table.dropIndex(['run_id'], 'agent_tool_call_run_idx')
+      table.dropColumn('run_id')
+    })
+
+    this.schema.alterTable('agent_message', (table) => {
+      table.dropIndex(['run_id'], 'agent_message_run_idx')
+      table.dropColumn('run_id')
+    })
+
+    this.schema.dropTableIfExists('agent_run')
+  }
+}

package/dist/stubs/database/migrations/create_agent_tables.stub

@@ -0,0 +1,113 @@
+{{{
+  exports({ to: app.migrationsPath(`${new Date().getTime()}_create_agent_tables.ts`) })
+}}}
+import { BaseSchema } from '@adonisjs/lucid/schema'
+
+/**
+ * The five tables for the @adonis-agora/agent `lucid` store: threads, messages, tool calls, token
+ * usage and model pricing. JSON payloads (tool calls/results, follow-ups, usage, tool input/output)
+ * are stored as TEXT — the store (de)serializes them — booleans as INTEGER (0/1), and timestamps as
+ * epoch-ms integers, so the schema is portable across SQLite / Postgres / MySQL. The `agent_tool_call`
+ * primary key is the model-supplied `toolCallId`, not a generated id.
+ */
+export default class extends BaseSchema {
+  async up() {
+    this.schema.createTable('agent_thread', (table) => {
+      table.string('id').primary()
+      table.string('actor_ref').notNullable()
+      table.string('tenant_ref')
+      table.text('title').notNullable()
+      table.string('persona').notNullable().defaultTo('default')
+      table.integer('transient').notNullable().defaultTo(0)
+      table.bigInteger('pinned_at')
+      table.text('summary')
+      table.integer('summary_message_count').notNullable().defaultTo(0)
+      table.string('active_stream_id')
+      table.bigInteger('created_at').notNullable()
+      table.bigInteger('updated_at').notNullable()
+      table.bigInteger('deleted_at')
+      table.index(['actor_ref', 'updated_at'], 'agent_thread_actor_updated_idx')
+    })
+
+    this.schema.createTable('agent_message', (table) => {
+      table.string('id').primary()
+      table
+        .string('thread_id')
+        .notNullable()
+        .references('id')
+        .inTable('agent_thread')
+        .onDelete('CASCADE')
+      table.string('role').notNullable()
+      table.text('content').notNullable()
+      table.text('tool_calls')
+      table.text('tool_results')
+      table.text('attachments')
+      table.text('follow_ups')
+      table.text('usage')
+      table.string('persona')
+      table.bigInteger('created_at').notNullable()
+      table.index(['thread_id', 'created_at'], 'agent_message_thread_created_idx')
+    })
+
+    this.schema.createTable('agent_tool_call', (table) => {
+      // PK = the model-supplied toolCallId, not a generated id.
+      table.string('id').primary()
+      table
+        .string('message_id')
+        .notNullable()
+        .references('id')
+        .inTable('agent_message')
+        .onDelete('CASCADE')
+      table.string('tool_name').notNullable()
+      table.string('tool_type').notNullable()
+      table.text('input')
+      table.text('output')
+      table.string('status').notNullable()
+      table.string('executed_by_ref')
+      table.integer('execution_ms')
+      table.text('error')
+      table.bigInteger('created_at').notNullable()
+      table.bigInteger('executed_at')
+    })
+
+    this.schema.createTable('agent_token_usage', (table) => {
+      table.string('id').primary()
+      table
+        .string('thread_id')
+        .notNullable()
+        .references('id')
+        .inTable('agent_thread')
+        .onDelete('CASCADE')
+      table.string('actor_ref').notNullable()
+      table.string('message_id')
+      table.string('model_id').notNullable()
+      table.string('purpose').notNullable()
+      table.integer('input_tokens').notNullable()
+      table.integer('output_tokens').notNullable()
+      table.integer('cache_write_tokens')
+      table.integer('cache_read_tokens')
+      table.double('cost_usd')
+      table.bigInteger('created_at').notNullable()
+      table.index(['actor_ref', 'created_at'], 'agent_token_usage_actor_created_idx')
+    })
+
+    this.schema.createTable('agent_model_pricing', (table) => {
+      table.string('id').primary()
+      table.string('model_id').notNullable()
+      table.double('input_price_per_1m').notNullable()
+      table.double('output_price_per_1m').notNullable()
+      table.double('cache_write_price_per_1m')
+      table.double('cache_read_price_per_1m')
+      table.bigInteger('effective_from').notNullable()
+      table.integer('is_current').notNullable()
+    })
+  }
+
+  async down() {
+    this.schema.dropTableIfExists('agent_model_pricing')
+    this.schema.dropTableIfExists('agent_token_usage')
+    this.schema.dropTableIfExists('agent_tool_call')
+    this.schema.dropTableIfExists('agent_message')
+    this.schema.dropTableIfExists('agent_thread')
+  }
+}