@happyvertical/smrt-chat 0.38.20 → 0.38.21

package/dist/tool-loop.d.ts

@@ -0,0 +1,182 @@
+import { AIInterface, AIMessage, AITool, ChatOptions } from '@happyvertical/ai';
+import { PrincipalAuditSink, PrincipalBinding, PrincipalRun } from '@happyvertical/smrt-agents';
+import { SmrtClassOptions } from '@happyvertical/smrt-core';
+import { PermissionDefinition } from '@happyvertical/smrt-users';
+/** Default ceiling on tool-executing rounds before the loop force-terminates. */
+export declare const DEFAULT_MAX_STEPS = 8;
+/**
+ * A single manifest operation the loop can offer and execute. Its {@link slug}
+ * is simultaneously the tool's stable name AND its permission-catalog slug — one
+ * source of truth for both what the model may call and what the principal must
+ * be permitted to do.
+ */
+export interface ManifestTool {
+    /** Catalog slug (`collection.action`) — the tool name and the permission slug. */
+    slug: string;
+    /** Collection (permission resource), e.g. `articles`. */
+    collection: string;
+    /** Registry class name used to resolve the backing collection, e.g. `Article`. */
+    className: string;
+    /** Catalog action: `read` / `create` / `update` / `delete`, or a public custom method name. */
+    action: string;
+    /** Qualified class name, when known. */
+    qualifiedName?: string;
+    /** Human-readable description surfaced to the model. */
+    description?: string;
+}
+/**
+ * The record of one tool invocation attempt in a loop turn.
+ */
+export interface ToolInvocation {
+    /** The tool name the model asked for. */
+    slug: string;
+    /** Parsed arguments (best-effort JSON parse of the model's raw arguments). */
+    args: Record<string, unknown>;
+    /** Whether the operation executed successfully. */
+    ok: boolean;
+    /** The JSON-serializable observation fed back to the model. */
+    observation: unknown;
+    /** True when the call was denied (not on the allow-list / not permitted). */
+    rejected: boolean;
+    /** Error summary when `ok` is false. */
+    error?: string;
+}
+/** Why {@link runToolLoop} returned. */
+export type ToolLoopStopReason = 'stop' | 'max_steps' | 'no_tools';
+/** The outcome of a {@link runToolLoop} turn. */
+export interface ToolLoopResult {
+    /** The model's final assistant text. */
+    content: string;
+    /** Number of tool-executing rounds completed. */
+    steps: number;
+    /** Why the loop stopped. */
+    stoppedReason: ToolLoopStopReason;
+    /** Every tool invocation attempted this turn, in order. */
+    invocations: ToolInvocation[];
+    /** The full working transcript (input messages + assistant/tool turns). */
+    messages: AIMessage[];
+    /** Total tokens reported by the AI boundary, when available. */
+    totalTokens: number;
+}
+/** Context handed to a custom {@link ToolLoopOptions.executeTool} implementation. */
+export interface ToolExecutionContext {
+    /** The principal run whose context bounds this execution. */
+    run: PrincipalRun;
+    /** The manifest operation to execute. */
+    tool: ManifestTool;
+    /** Parsed tool arguments. */
+    args: Record<string, unknown>;
+    /** The database handle to operate against (already the RLS-bound tx when on). */
+    db?: SmrtClassOptions['db'];
+}
+/**
+ * Options for {@link runToolLoop}.
+ */
+export interface ToolLoopOptions {
+    /** The AI boundary (the only thing mocked in tests). */
+    ai: AIInterface;
+    /** The initial conversation messages (system / history / user). */
+    messages: AIMessage[];
+    /** The manifest operations available this turn (already allow-list-filtered). */
+    tools: ManifestTool[];
+    /** The persona principal every tool call runs as. */
+    principal: PrincipalBinding;
+    /** Database handle the side-door operations run against. */
+    db?: SmrtClassOptions['db'];
+    /** Max tool-executing rounds before force-termination. Default {@link DEFAULT_MAX_STEPS}. */
+    maxSteps?: number;
+    /** Model id passed to the AI boundary. */
+    model?: string;
+    /** Sampling temperature. */
+    temperature?: number;
+    /** Max tokens per completion. */
+    maxTokens?: number;
+    /** Tool-choice behaviour while tools are offered. Default `'auto'`. */
+    toolChoice?: ChatOptions['toolChoice'];
+    /**
+     * Override the side-door executor. The default
+     * ({@link invokeManifestTool}) enforces the allow-list + catalog gate and
+     * dispatches through the ObjectRegistry. Tests inject a stub to exercise loop
+     * mechanics without a backing object.
+     */
+    executeTool?: (ctx: ToolExecutionContext) => Promise<unknown>;
+    /** Notified after each tool invocation (for streaming/telemetry). */
+    onInvocation?: (invocation: ToolInvocation) => void | Promise<void>;
+    /** The originating user the turn runs on behalf of (audited). */
+    onBehalfOfUserId?: string | null;
+    /** Canonical agent class, recorded in the audit entry. */
+    agentClass?: string;
+    /** Audit sink forwarded to {@link executeAsPrincipal}. */
+    audit?: PrincipalAuditSink;
+    /** Opt into Postgres RLS transaction wrapping. */
+    postgresRls?: boolean;
+}
+/**
+ * Build the closed catalog of manifest operations available as tools.
+ *
+ * Reads the manifest-derived {@link PermissionCatalog} and keeps only the
+ * entries that name a dispatchable operation (a `(collection, action)` with a
+ * resolvable backing class). Pass `allowedTools` to narrow the catalog to a
+ * persona's least-privilege allow-list — this is the **offer gate**: a slug not
+ * in `allowedTools` is never returned, so it is neither offered to the model nor
+ * executed. A missing, `null`, or empty `allowedTools` yields **no tools**
+ * (fail-closed) — the same whitelist semantics as `AgentSession`/
+ * `PrincipalBinding` (S5 #1392), so forgetting the allow-list can only tighten,
+ * never widen, the offered surface. Pass `all: true` to deliberately enumerate
+ * the full manifest operation surface (e.g. an admin tool picker) — that is the
+ * one explicit escape hatch, never the default.
+ */
+export declare function buildManifestToolCatalog(options?: SmrtClassOptions & {
+    /** Least-privilege allow-list to narrow the catalog by (fail-closed). */
+    allowedTools?: string[] | null;
+    /** Explicitly enumerate the ENTIRE manifest operation surface (no narrowing). */
+    all?: boolean;
+    /** Supply a pre-built catalog (skips the manifest walk). */
+    catalog?: PermissionDefinition[];
+}): ManifestTool[];
+/**
+ * A provider-safe function name for a catalog slug.
+ *
+ * Catalog slugs are `collection.action` and routinely contain a `.`, but many
+ * providers (OpenAI) restrict function names to `[A-Za-z0-9_-]{1,64}`. This maps
+ * the slug into that charset (dots → `-`) for the wire; {@link runToolLoop} maps
+ * the returned name back to the tool, and `tool.slug` remains the internal
+ * permission id. Distinct slugs stay distinct (the only substituted char is the
+ * single `.` separator).
+ */
+export declare function toolFunctionName(slug: string): string;
+/**
+ * Project a manifest operation into an AI function-tool definition. The function
+ * name is the provider-safe rendering of the catalog slug
+ * ({@link toolFunctionName}), so the model can only ever name a real operation.
+ */
+export declare function manifestToolToAITool(tool: ManifestTool): AITool;
+/**
+ * Execute a manifest operation in-process ("side door") under the principal.
+ *
+ * Enforces both authority dimensions before touching data: the fail-closed tool
+ * allow-list ({@link PrincipalRun.assertToolAllowed}) and the catalog permission
+ * for the `(collection, action)` ({@link PrincipalRun.assertOperation}) — the
+ * door-agnostic teeth that hold on RLS-off adapters and are a redundant second
+ * gate under Postgres RLS. Data operations run against the principal context's
+ * database (the RLS-bound transaction when RLS is on), so tenant + per-operation
+ * enforcement apply exactly as they would through REST or MCP.
+ */
+export declare function invokeManifestTool(run: PrincipalRun, tool: ManifestTool, args: Record<string, unknown>, options?: {
+    db?: SmrtClassOptions['db'];
+}): Promise<unknown>;
+/**
+ * Run a bounded `tool_call → observe → respond` loop over the manifest operation
+ * surface, as the persona's bound principal.
+ *
+ * The whole turn runs inside a single {@link executeAsPrincipal} context, so
+ * every tool call shares one published permission snapshot (matching what a
+ * Postgres RLS session enforces) and the turn audits once as on-behalf-of the
+ * originating user.
+ *
+ * @param options - The AI boundary, seed messages, allow-list-filtered tools,
+ *   principal, and ceiling.
+ * @returns The final assistant text plus the invocation log and transcript.
+ */
+export declare function runToolLoop(options: ToolLoopOptions): Promise<ToolLoopResult>;
+//# sourceMappingURL=tool-loop.d.ts.map

package/dist/tool-loop.d.ts.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@happyvertical/smrt-chat",
-  "version": "0.38.20",
+  "version": "0.38.21",
   "description": "Chat rooms, DMs, threads, and agent conversations for the SMRT framework",
   "type": "module",
   "smrtRawPrimitives": "strict",
@@ -56,10 +56,15 @@
     "access": "public"
   },
   "dependencies": {
-    "@happyvertical/smrt-core": "0.38.20",
-    "@happyvertical/smrt-types": "0.38.20",
-    "@happyvertical/smrt-ui": "0.38.20",
-    "@happyvertical/smrt-tenancy": "0.38.20"
+    "@happyvertical/ai": "^0.77.0",
+    "@happyvertical/sql": "^0.77.0",
+    "@happyvertical/smrt-agents": "0.38.21",
+    "@happyvertical/smrt-core": "0.38.21",
+    "@happyvertical/smrt-personas": "0.38.21",
+    "@happyvertical/smrt-tenancy": "0.38.21",
+    "@happyvertical/smrt-types": "0.38.21",
+    "@happyvertical/smrt-ui": "0.38.21",
+    "@happyvertical/smrt-users": "0.38.21"
   },
   "peerDependencies": {
     "svelte": "^5.56.4"
@@ -79,9 +84,8 @@
     "typescript": "^5.9.3",
     "vite": "^8.1.3",
     "vitest": "^4.1.9",
-    "@happyvertical/smrt-agents": "0.38.20",
-    "@happyvertical/smrt-profiles": "0.38.20",
-    "@happyvertical/smrt-vitest": "0.38.20"
+    "@happyvertical/smrt-profiles": "0.38.21",
+    "@happyvertical/smrt-vitest": "0.38.21"
   },
   "scripts": {
     "build": "vite build --mode library && svelte-package -i src/svelte -o dist/svelte --tsconfig tsconfig.svelte.json",