@kindgi/agents 0.1.3 → 0.1.4-rc.0

package/migrations/meta/0004_snapshot.json

@@ -0,0 +1,327 @@
+{
+  "id": "cfefefb3-52e4-4b8b-b5ec-18d54c0263a0",
+  "prevId": "39c9de18-7608-4826-84f7-af1dda0ba078",
+  "version": "7",
+  "dialect": "postgresql",
+  "tables": {
+    "public.agent_conversations": {
+      "name": "agent_conversations",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "uuid",
+          "primaryKey": true,
+          "notNull": true,
+          "default": "gen_random_uuid()"
+        },
+        "tenant_id": {
+          "name": "tenant_id",
+          "type": "uuid",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "agent_id": {
+          "name": "agent_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "agent_version": {
+          "name": "agent_version",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "title": {
+          "name": "title",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "participant_id": {
+          "name": "participant_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "project_id": {
+          "name": "project_id",
+          "type": "uuid",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "scope": {
+          "name": "scope",
+          "type": "jsonb",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "opened_at": {
+          "name": "opened_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        },
+        "closed_at": {
+          "name": "closed_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "turn_count": {
+          "name": "turn_count",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "default": 0
+        },
+        "last_message_at": {
+          "name": "last_message_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "metadata": {
+          "name": "metadata",
+          "type": "jsonb",
+          "primaryKey": false,
+          "notNull": false
+        }
+      },
+      "indexes": {
+        "agent_conversations_tenant_agent_idx": {
+          "name": "agent_conversations_tenant_agent_idx",
+          "columns": [
+            {
+              "expression": "tenant_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "agent_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "agent_conversations_tenant_participant_idx": {
+          "name": "agent_conversations_tenant_participant_idx",
+          "columns": [
+            {
+              "expression": "tenant_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "participant_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "agent_conversations_tenant_project_opened_idx": {
+          "name": "agent_conversations_tenant_project_opened_idx",
+          "columns": [
+            {
+              "expression": "tenant_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "project_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "opened_at",
+              "isExpression": false,
+              "asc": false,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "where": "\"agent_conversations\".\"project_id\" IS NOT NULL",
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "agent_conversations_open_recent_idx": {
+          "name": "agent_conversations_open_recent_idx",
+          "columns": [
+            {
+              "expression": "tenant_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "last_message_at",
+              "isExpression": false,
+              "asc": false,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "where": "\"agent_conversations\".\"closed_at\" IS NULL",
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.agent_run_snapshots": {
+      "name": "agent_run_snapshots",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "uuid",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "tenant_id": {
+          "name": "tenant_id",
+          "type": "uuid",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "project_id": {
+          "name": "project_id",
+          "type": "uuid",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "agent_id": {
+          "name": "agent_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "agent_version": {
+          "name": "agent_version",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "conversation_id": {
+          "name": "conversation_id",
+          "type": "uuid",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "user_message": {
+          "name": "user_message",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "parameters": {
+          "name": "parameters",
+          "type": "jsonb",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "input": {
+          "name": "input",
+          "type": "jsonb",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "participant_id": {
+          "name": "participant_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "dry_run": {
+          "name": "dry_run",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "default": 0
+        },
+        "principal": {
+          "name": "principal",
+          "type": "jsonb",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "authz": {
+          "name": "authz",
+          "type": "jsonb",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "replay": {
+          "name": "replay",
+          "type": "jsonb",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "agent_run_snapshots_tenant_idx": {
+          "name": "agent_run_snapshots_tenant_idx",
+          "columns": [
+            {
+              "expression": "tenant_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    }
+  },
+  "enums": {},
+  "schemas": {},
+  "sequences": {},
+  "roles": {},
+  "policies": {},
+  "views": {},
+  "_meta": {
+    "columns": {},
+    "schemas": {},
+    "tables": {}
+  }
+}

package/migrations/meta/_journal.json

@@ -29,6 +29,13 @@
       "when": 1791208016784,
       "tag": "0003_hesitant_captain_cross",
       "breakpoints": true
+    },
+    {
+      "idx": 4,
+      "version": "7",
+      "when": 1791247643606,
+      "tag": "0004_stormy_moondragon",
+      "breakpoints": true
     }
   ]
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kindgi/agents",
-  "version": "0.1.3",
+  "version": "0.1.4-rc.0",
   "description": "Agent primitive for Kindgi. Composes capabilities (model routing), tools (execution), memory (facts + retrieval), guardrails (declarative guardrails), and provenance into a single declarative unit. Agents are data-as-code — a defineAgent() call produces a durable definition that runs on the kernel, with first-class multi-turn conversations, streaming output, and a provenance record per turn.",
   "license": "Apache-2.0",
   "repository": {
@@ -31,20 +31,20 @@
     "type-manifest.json"
   ],
   "dependencies": {
-    "@kindgi/authz": "0.1.3",
-    "@kindgi/capabilities": "0.1.3",
-    "@kindgi/compliance": "0.1.3",
-    "@kindgi/embedding": "0.1.3",
-    "@kindgi/flow": "0.1.3",
-    "@kindgi/handler": "0.1.3",
-    "@kindgi/guardrails": "0.1.3",
-    "@kindgi/memory": "0.1.3",
-    "@kindgi/policy-contract": "0.1.3",
-    "@kindgi/provenance": "0.1.3",
-    "@kindgi/runtime": "0.1.3",
-    "@kindgi/schema": "0.1.3",
-    "@kindgi/tools": "0.1.3",
-    "@kindgi/types": "0.1.3",
+    "@kindgi/authz": "0.1.4-rc.0",
+    "@kindgi/capabilities": "0.1.4-rc.0",
+    "@kindgi/compliance": "0.1.4-rc.0",
+    "@kindgi/embedding": "0.1.4-rc.0",
+    "@kindgi/flow": "0.1.4-rc.0",
+    "@kindgi/handler": "0.1.4-rc.0",
+    "@kindgi/guardrails": "0.1.4-rc.0",
+    "@kindgi/memory": "0.1.4-rc.0",
+    "@kindgi/policy-contract": "0.1.4-rc.0",
+    "@kindgi/provenance": "0.1.4-rc.0",
+    "@kindgi/runtime": "0.1.4-rc.0",
+    "@kindgi/schema": "0.1.4-rc.0",
+    "@kindgi/tools": "0.1.4-rc.0",
+    "@kindgi/types": "0.1.4-rc.0",
     "drizzle-orm": "^0.45.3",
     "liquidjs": "^10.29.0"
   },

package/src/blocks.ts

@@ -0,0 +1,231 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+
+import { Liquid } from 'liquidjs';
+
+import { compileInlineSchema } from '@kindgi/schema';
+import type { Result, TenantId } from '@kindgi/types';
+
+import { validatePromptParameters } from './define.js';
+import type { PromptParameter } from './types.js';
+
+/**
+ * Data blocks: versioned content an agent version pins and an expert
+ * can edit without code: a prompt, or settings.
+ *
+ * A block is published like a tool (head plus immutable versions,
+ * unregister and reinstate), into a project. An agent references one by
+ * range, and the version it runs is pinned when the agent version is
+ * published, so an edit reaches an agent only through a new agent
+ * version, which is what gets compared, tested and promoted.
+ */
+export const BLOCK_KINDS = ['prompt', 'settings'] as const;
+export type BlockKind = (typeof BLOCK_KINDS)[number];
+
+/**
+ * A prompt: a Liquid template rendered as an agent's instructions are,
+ * with the same declared parameters and auto-injected variables.
+ */
+export interface PromptBlockContent {
+  readonly template: string;
+  readonly parameters?: readonly PromptParameter[];
+}
+
+/**
+ * Settings: a JSON object a tool reads (`ToolContext.settings`) and a
+ * prompt template reads (`settings.<block id>.<key>`). With `schema`,
+ * `values` must satisfy it, and so must a later version's.
+ */
+export interface SettingsBlockContent {
+  readonly values: Readonly<Record<string, unknown>>;
+  /** JSON Schema (draft 2020-12) the values must satisfy. */
+  readonly schema?: Readonly<Record<string, unknown>>;
+}
+
+interface BlockBase {
+  /** Dotted id, like an agent's (`acme.intake-prompt`). */
+  readonly id: string;
+  /** Plain `major.minor.patch`. */
+  readonly version: string;
+  readonly description?: string;
+}
+
+/** A block version as it's published. */
+export type BlockDefinition =
+  | (BlockBase & { readonly kind: 'prompt'; readonly content: PromptBlockContent })
+  | (BlockBase & { readonly kind: 'settings'; readonly content: SettingsBlockContent });
+
+export interface BlockIssue {
+  readonly path: string;
+  readonly message: string;
+}
+
+export interface InvalidBlock {
+  readonly code: 'invalid-block';
+  readonly message: string;
+  readonly issues: readonly BlockIssue[];
+}
+
+const ID = /^[a-z0-9][a-z0-9-]*(?:\.[a-z0-9][a-z0-9-]*)+$/;
+const VERSION = /^\d+\.\d+\.\d+$/;
+
+/**
+ * Validate a block version's definition: its id, plain semver version,
+ * kind, and content for that kind. A prompt's template must parse as
+ * Liquid and its parameters follow an agent's rules. Settings values
+ * must be an object, satisfying `schema` when it's set (and `schema`
+ * must compile).
+ */
+export function validateBlock(input: unknown): Result<BlockDefinition, InvalidBlock> {
+  const issues: BlockIssue[] = [];
+  if (input === null || typeof input !== 'object' || Array.isArray(input)) {
+    return invalid([{ path: '', message: 'a block must be an object' }]);
+  }
+  const b = input as Record<string, unknown>;
+  if (typeof b.id !== 'string' || !ID.test(b.id)) {
+    issues.push({
+      path: '/id',
+      message: 'id must be a dotted lowercase id, e.g. "acme.intake-prompt"',
+    });
+  }
+  if (typeof b.version !== 'string' || !VERSION.test(b.version)) {
+    issues.push({ path: '/version', message: 'version must be major.minor.patch, e.g. "1.0.0"' });
+  }
+  if (b.description !== undefined && typeof b.description !== 'string') {
+    issues.push({ path: '/description', message: 'description must be a string' });
+  }
+  if (b.kind === 'prompt') issues.push(...promptIssues(b.content));
+  else if (b.kind === 'settings') issues.push(...settingsIssues(b.content));
+  else issues.push({ path: '/kind', message: `kind must be one of: ${BLOCK_KINDS.join(', ')}` });
+  if (issues.length > 0) return invalid(issues);
+
+  const { id, version, kind, content, description } = b as unknown as BlockDefinition;
+  return {
+    kind: 'ok',
+    value: {
+      id,
+      version,
+      kind,
+      content,
+      ...(description !== undefined && { description }),
+    } as BlockDefinition,
+  };
+}
+
+/**
+ * Whether settings `values` satisfy a JSON `schema`: the problems, none
+ * when they do. A later version's values are checked against the
+ * latest version's schema too, so a tool reading them sees a stable
+ * shape.
+ */
+export function settingsSchemaIssues(
+  values: unknown,
+  schema: Readonly<Record<string, unknown>>,
+  path = '/content/values',
+): BlockIssue[] {
+  const compiled = compileInlineSchema(schema);
+  if (compiled.kind === 'err') {
+    return [{ path: '/content/schema', message: compiled.error.message }];
+  }
+  const checked = compiled.value.validate(values);
+  if (checked.kind === 'ok') return [];
+  return checked.error.errors.map((e) => {
+    const err = e as { readonly instancePath?: string; readonly message?: string };
+    return { path: `${path}${err.instancePath ?? ''}`, message: err.message ?? 'invalid' };
+  });
+}
+
+function promptIssues(content: unknown): BlockIssue[] {
+  if (content === null || typeof content !== 'object') {
+    return [
+      { path: '/content', message: 'a prompt block needs content: { template, parameters? }' },
+    ];
+  }
+  const c = content as Record<string, unknown>;
+  if (typeof c.template !== 'string' || c.template.trim().length === 0) {
+    return [{ path: '/content/template', message: 'template must be a non-empty string' }];
+  }
+  const issues: BlockIssue[] = [];
+  try {
+    new Liquid().parse(c.template);
+  } catch (cause) {
+    issues.push({
+      path: '/content/template',
+      message: `template isn't valid Liquid: ${cause instanceof Error ? cause.message : String(cause)}`,
+    });
+  }
+  if (c.parameters !== undefined && !Array.isArray(c.parameters)) {
+    issues.push({ path: '/content/parameters', message: 'parameters must be an array' });
+  } else {
+    issues.push(
+      ...validatePromptParameters(c.parameters as readonly PromptParameter[] | undefined).map(
+        (i) => ({ path: `/content${i.path}`, message: i.message }),
+      ),
+    );
+  }
+  return issues;
+}
+
+function settingsIssues(content: unknown): BlockIssue[] {
+  if (content === null || typeof content !== 'object') {
+    return [{ path: '/content', message: 'a settings block needs content: { values, schema? }' }];
+  }
+  const c = content as Record<string, unknown>;
+  if (c.values === null || typeof c.values !== 'object' || Array.isArray(c.values)) {
+    return [{ path: '/content/values', message: 'values must be a JSON object' }];
+  }
+  if (c.schema === undefined) return [];
+  if (c.schema === null || typeof c.schema !== 'object' || Array.isArray(c.schema)) {
+    return [{ path: '/content/schema', message: 'schema must be a JSON Schema object' }];
+  }
+  return settingsSchemaIssues(c.values, c.schema as Readonly<Record<string, unknown>>);
+}
+
+function invalid(issues: readonly BlockIssue[]): Result<never, InvalidBlock> {
+  return {
+    kind: 'err',
+    error: {
+      code: 'invalid-block',
+      message: `The block is invalid (${issues.length} issue${issues.length === 1 ? '' : 's'})`,
+      issues,
+    },
+  };
+}
+
+/**
+ * What a model-settings block's values may set: the model-call knobs a
+ * turn passes on. Checked when an agent version that references the
+ * block (`Agent.modelSettings`) is published.
+ */
+export const MODEL_SETTINGS_SCHEMA: Readonly<Record<string, unknown>> = {
+  type: 'object',
+  additionalProperties: false,
+  properties: {
+    temperature: { type: 'number', minimum: 0, maximum: 2 },
+    maxOutputTokens: { type: 'integer', minimum: 1 },
+  },
+};
+
+/** The model-call knobs of a model-settings block. */
+export interface ModelSettings {
+  readonly temperature?: number;
+  readonly maxOutputTokens?: number;
+}
+
+/**
+ * Reads data blocks for an agent turn: an exact version (an unregistered
+ * one included, for the agent versions that pin it), and a block's
+ * active versions (to resolve a range for an agent version with no
+ * pins). The runtime supplies it over its block registry.
+ */
+export interface BlockReader {
+  getVersion(input: {
+    readonly tenantId: TenantId;
+    readonly blockId: string;
+    readonly version: string;
+  }): Promise<BlockDefinition | null>;
+  activeVersions(input: {
+    readonly tenantId: TenantId;
+    readonly blockId: string;
+  }): Promise<readonly string[]>;
+}