@kindgi/agents 0.1.4 → 0.1.5-rc.0

package/migrations/meta/0005_snapshot.json

@@ -0,0 +1,333 @@
+{
+  "id": "e25b83b3-c87b-4e04-98fe-d8af651080e5",
+  "prevId": "cfefefb3-52e4-4b8b-b5ec-18d54c0263a0",
+  "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
+        },
+        "unregistered_at": {
+          "name": "unregistered_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

@@ -36,6 +36,13 @@
       "when": 1791247643606,
       "tag": "0004_stormy_moondragon",
       "breakpoints": true
+    },
+    {
+      "idx": 5,
+      "version": "7",
+      "when": 1791379726212,
+      "tag": "0005_condemned_hellcat",
+      "breakpoints": true
     }
   ]
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kindgi/agents",
-  "version": "0.1.4",
+  "version": "0.1.5-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.4",
-    "@kindgi/capabilities": "0.1.4",
-    "@kindgi/compliance": "0.1.4",
-    "@kindgi/embedding": "0.1.4",
-    "@kindgi/flow": "0.1.4",
-    "@kindgi/handler": "0.1.4",
-    "@kindgi/guardrails": "0.1.4",
-    "@kindgi/memory": "0.1.4",
-    "@kindgi/policy-contract": "0.1.4",
-    "@kindgi/provenance": "0.1.4",
-    "@kindgi/runtime": "0.1.4",
-    "@kindgi/schema": "0.1.4",
-    "@kindgi/tools": "0.1.4",
-    "@kindgi/types": "0.1.4",
+    "@kindgi/authz": "0.1.5-rc.0",
+    "@kindgi/capabilities": "0.1.5-rc.0",
+    "@kindgi/compliance": "0.1.5-rc.0",
+    "@kindgi/embedding": "0.1.5-rc.0",
+    "@kindgi/flow": "0.1.5-rc.0",
+    "@kindgi/handler": "0.1.5-rc.0",
+    "@kindgi/guardrails": "0.1.5-rc.0",
+    "@kindgi/memory": "0.1.5-rc.0",
+    "@kindgi/policy-contract": "0.1.5-rc.0",
+    "@kindgi/provenance": "0.1.5-rc.0",
+    "@kindgi/runtime": "0.1.5-rc.0",
+    "@kindgi/schema": "0.1.5-rc.0",
+    "@kindgi/tools": "0.1.5-rc.0",
+    "@kindgi/types": "0.1.5-rc.0",
     "drizzle-orm": "^0.45.3",
     "liquidjs": "^10.29.0"
   },

package/src/blocks.ts

@@ -180,7 +180,8 @@ function settingsIssues(content: unknown): BlockIssue[] {
   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>>);
+  const schema = c.schema as Readonly<Record<string, unknown>>;
+  return [...tunableIssues(schema), ...settingsSchemaIssues(c.values, schema)];
 }
 
 function invalid(issues: readonly BlockIssue[]): Result<never, InvalidBlock> {
@@ -231,3 +232,76 @@ export interface BlockReader {
     readonly blockId: string;
   }): Promise<readonly string[]>;
 }
+
+/** The schema marker that lets an improvement pass search a settings key's values. */
+export const TUNABLE_MARKER = 'x-kindgi-tunable';
+
+/** A settings key an improvement pass may search: a bounded number, or one of a list. */
+export type TunableKey =
+  | {
+      readonly key: string;
+      readonly kind: 'number' | 'integer';
+      readonly minimum: number;
+      readonly maximum: number;
+    }
+  | { readonly key: string; readonly kind: 'enum'; readonly values: readonly unknown[] };
+
+function schemaProperties(
+  schema: Readonly<Record<string, unknown>>,
+): readonly [string, Readonly<Record<string, unknown>>][] {
+  const props = schema.properties;
+  if (props === null || typeof props !== 'object' || Array.isArray(props)) return [];
+  return Object.entries(props).flatMap(([key, value]) =>
+    value !== null && typeof value === 'object' && !Array.isArray(value)
+      ? [[key, value as Readonly<Record<string, unknown>>] as const]
+      : [],
+  );
+}
+
+function tunableOf(key: string, prop: Readonly<Record<string, unknown>>): TunableKey | undefined {
+  if (Array.isArray(prop.enum) && prop.enum.length > 1) {
+    return { key, kind: 'enum', values: prop.enum };
+  }
+  const { type, minimum, maximum } = prop;
+  if (
+    (type === 'number' || type === 'integer') &&
+    typeof minimum === 'number' &&
+    typeof maximum === 'number' &&
+    minimum < maximum
+  ) {
+    return { key, kind: type, minimum, maximum };
+  }
+  return undefined;
+}
+
+/**
+ * The settings keys a schema marks tunable (`"x-kindgi-tunable": true` on
+ * a top-level property): what an improvement pass may search, within the
+ * bounds the schema gives. Nothing is tunable unless its author says so.
+ */
+export function tunableKeys(schema: Readonly<Record<string, unknown>> | undefined): TunableKey[] {
+  if (schema === undefined) return [];
+  return schemaProperties(schema).flatMap(([key, prop]) => {
+    if (prop[TUNABLE_MARKER] !== true) return [];
+    const tunable = tunableOf(key, prop);
+    return tunable === undefined ? [] : [tunable];
+  });
+}
+
+/** A tunable mark on a key it can't apply to: a number without both bounds, say. */
+function tunableIssues(schema: Readonly<Record<string, unknown>>): BlockIssue[] {
+  return schemaProperties(schema).flatMap(([key, prop]) => {
+    const mark = prop[TUNABLE_MARKER];
+    if (mark === undefined) return [];
+    const path = `/content/schema/properties/${key.replaceAll('~', '~0').replaceAll('/', '~1')}/${TUNABLE_MARKER}`;
+    if (mark !== true) return [{ path, message: `${TUNABLE_MARKER} must be true when given` }];
+    return tunableOf(key, prop) === undefined
+      ? [
+          {
+            path,
+            message: `"${key}" can be tunable only as a number or integer with a minimum below its maximum, or with an enum of two or more values`,
+          },
+        ]
+      : [];
+  });
+}

package/src/conversation-binding.ts

@@ -2,7 +2,7 @@
 // Copyright (C) 2026 Kindgi Inc.
 
 import type { RunBinding } from '@kindgi/runtime';
-import type { ListScope, ProjectId, Result, Semver, TenantId } from '@kindgi/types';
+import type { ListScope, ProjectId, Result, ScopeSegment, Semver, TenantId } from '@kindgi/types';
 
 import type { AgentError } from './errors.js';
 import type {
@@ -51,12 +51,31 @@ export interface AppendMessageInput {
    * assistant response for a turn omits this flag (counts as a turn).
    */
   readonly isIntermediate?: boolean;
+  /**
+   * What the conversation-recall index keeps with the message, from the
+   * turn (the conversation row has neither): the user the turn acts for,
+   * and the run's segment path. A user's message and an agent's final
+   * answer are indexed; tool messages and tool-call turns are not.
+   * Absent: indexed without them.
+   */
+  readonly recall?: {
+    readonly userId?: string;
+    readonly segments?: readonly ScopeSegment[];
+  };
 }
 
 export interface ReadMessagesInput {
   readonly tenantId: TenantId;
   readonly conversationId: ConversationId;
   readonly sinceSequence?: number;
+  /** Only messages before this sequence. */
+  readonly beforeSequence?: number;
+  /**
+   * Only the newest `last` messages (after the other bounds), oldest
+   * first: a turn's history window. A binding that ignores it returns
+   * them all, and the caller keeps the newest.
+   */
+  readonly last?: number;
   readonly limit?: number;
 }
 
@@ -67,7 +86,14 @@ export interface ReadMessagesInput {
  * opaque wire cursor.
  */
 export interface ConversationPageCursor {
-  /** ISO 8601 `openedAt` timestamp of the last row from the previous page. */
+  /**
+   * `openedAt` of the last row from the previous page. As a binding's
+   * `ConversationPage.next` gives it, the stored value exactly (Postgres
+   * keeps microseconds: `opened_at::text`); a cursor from before carries
+   * the row's ISO 8601 `openedAt`. A binding compares it as given, never
+   * through a JS `Date`, which keeps milliseconds and would skip the rows
+   * opened earlier in the same millisecond.
+   */
   readonly openedAt: string;
   readonly id: ConversationId;
 }
@@ -102,6 +128,13 @@ export interface ListConversationsPageInput {
 export interface ConversationPage {
   readonly data: readonly Conversation[];
   readonly hasMore: boolean;
+  /**
+   * Where the next page starts: the last row's position as stored
+   * (`openedAt` to the microsecond, and `id`). Set when `hasMore`. Absent
+   * from a binding that doesn't give it: the caller then uses the last
+   * row's `openedAt` and `id`.
+   */
+  readonly next?: ConversationPageCursor;
 }
 
 /**
@@ -152,7 +185,24 @@ export interface ConversationBinding {
     runBinding?: RunBinding,
   ): Promise<Result<Conversation, AgentError>>;
 
-  deleteConversation(tenantId: TenantId, id: ConversationId): Promise<Result<void, AgentError>>;
+  /**
+   * Unregister a conversation: a tombstone (`unregisteredAt`). From then
+   * on no read, list or recall returns it, and no message can be added;
+   * the retention sweep removes it after the tenant's grace. Optional: a
+   * binding without it can't unregister (the route answers 501).
+   */
+  unregisterConversation?(
+    tenantId: TenantId,
+    id: ConversationId,
+  ): Promise<Result<Conversation, AgentError>>;
+
+  /**
+   * @deprecated Removed with the conversation-recall index: deleting a
+   * row left its messages behind. Unregister instead
+   * (`unregisterConversation`). Optional only so a runtime built before
+   * it still compiles; the next release drops it.
+   */
+  deleteConversation?(tenantId: TenantId, id: ConversationId): Promise<Result<void, AgentError>>;
 
   appendMessage(input: AppendMessageInput): Promise<Result<ConversationMessage, AgentError>>;