@kindgi/agents 0.0.0-bootstrap.0 → 0.1.0

package/migrations/meta/0002_snapshot.json

@@ -0,0 +1,287 @@
+{
+  "id": "2769ef0e-69b4-4a4d-ab47-044e2f11945e",
+  "prevId": "02977280-a54a-47a9-90e9-db22e06166f2",
+  "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
+        },
+        "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_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
+        },
+        "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

@@ -0,0 +1,27 @@
+{
+  "version": "7",
+  "dialect": "postgresql",
+  "entries": [
+    {
+      "idx": 0,
+      "version": "7",
+      "when": 1789708941765,
+      "tag": "0000_sparkling_talkback",
+      "breakpoints": true
+    },
+    {
+      "idx": 1,
+      "version": "7",
+      "when": 1790270079710,
+      "tag": "0001_tired_warhawk",
+      "breakpoints": true
+    },
+    {
+      "idx": 2,
+      "version": "7",
+      "when": 1790813765675,
+      "tag": "0002_violet_ezekiel",
+      "breakpoints": true
+    }
+  ]
+}

package/package.json

@@ -1,7 +1,79 @@
 {
   "name": "@kindgi/agents",
-  "version": "0.0.0-bootstrap.0",
-  "description": "Placeholder so a trusted publisher can be attached. Releases are published from https://github.com/kindgi/kindgi-sdk with provenance; use 0.1.0 or later.",
+  "version": "0.1.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": { "type": "git", "url": "git+https://github.com/kindgi/kindgi-sdk.git" }
-}
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kindgi/kindgi-sdk.git",
+    "directory": "packages/agents"
+  },
+  "homepage": "https://github.com/kindgi/kindgi-sdk/tree/main/packages/agents#readme",
+  "bugs": {
+    "url": "https://github.com/kindgi/kindgi-sdk/issues"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "migrations",
+    "README.md",
+    "SPEC.md",
+    "type-manifest.json"
+  ],
+  "dependencies": {
+    "@kindgi/authz": "0.1.0",
+    "@kindgi/capabilities": "0.1.0",
+    "@kindgi/compliance": "0.1.0",
+    "@kindgi/embedding": "0.1.0",
+    "@kindgi/flow": "0.1.0",
+    "@kindgi/handler": "0.1.0",
+    "@kindgi/guardrails": "0.1.0",
+    "@kindgi/memory": "0.1.0",
+    "@kindgi/policy-contract": "0.1.0",
+    "@kindgi/provenance": "0.1.0",
+    "@kindgi/runtime": "0.1.0",
+    "@kindgi/schema": "0.1.0",
+    "@kindgi/tools": "0.1.0",
+    "@kindgi/types": "0.1.0",
+    "drizzle-orm": "^0.36.4",
+    "liquidjs": "^10.29.0"
+  },
+  "peerDependencies": {
+    "zod": "^4.0.0"
+  },
+  "peerDependenciesMeta": {
+    "zod": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.5",
+    "drizzle-kit": "^0.30.1",
+    "typescript": "^5.7.3",
+    "vitest": "^2.1.8",
+    "zod": "^4.6.5"
+  },
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "clean": "rm -rf dist *.tsbuildinfo",
+    "db:generate": "drizzle-kit generate"
+  }
+}

package/src/agent-turn-flow.ts

@@ -0,0 +1,183 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+
+import type { Flow } from '@kindgi/flow';
+import { loadFlow } from '@kindgi/flow';
+
+/**
+ * The versioned agent-turn flow. Every agent turn — regardless of which
+ * concrete `Agent` is being invoked — executes as a run of this flow
+ * against handlers that close over the specific agent + bindings + input.
+ *
+ * Shape (uses the kernel loop primitive for the model↔tool cycle):
+ *
+ * ```
+ * $start → setup → render-prompt → persist-user-message → run-retrievals
+ *        → build-initial-messages → agent-loop (kernel loop node)
+ *        → evaluate-guardrails → persist-final-message → persist-provenance
+ *        → compose-result → $end
+ * ```
+ *
+ * Guardrails run on the final response before it is stored: a response
+ * a blocking guardrail rejects never reaches the conversation.
+ *
+ * `agent-loop` is a `while+after` (do-while) loop; its body is
+ * `$loop-start → model-call → dispatch-tools → budget-check → $loop-end`.
+ * Exit condition: `iterationOutput.finishedTurn === true`.
+ * `collectAllIterations: true` so post-loop nodes can aggregate every
+ * iteration's per-iteration usage + appended messages.
+ *
+ * Version-locked so historical runs pin to this shape; any
+ * change to the node set or body sub-flow bumps the version and
+ * `resumeRun` refuses to resume old runs against a new flow.
+ */
+export const AGENT_TURN_FLOW_ID = 'agent.turn';
+export const AGENT_TURN_FLOW_VERSION = '1.1.0';
+
+/**
+ * Safety cap for iterations. Per-agent `maxSteps` is enforced by the
+ * `budget-check` body node — this constant only bounds catastrophic
+ * runaway (model always requests a tool call, no budget-check, no
+ * agent config). Set high enough that no real agent will hit it.
+ */
+export const AGENT_TURN_LOOP_MAX_ITERATIONS = 32;
+
+// Outer node ids.
+export const SETUP_NODE = 'setup';
+export const RENDER_PROMPT_NODE = 'render-prompt';
+export const PERSIST_USER_MESSAGE_NODE = 'persist-user-message';
+export const RUN_RETRIEVALS_NODE = 'run-retrievals';
+export const BUILD_INITIAL_MESSAGES_NODE = 'build-initial-messages';
+export const AGENT_LOOP_NODE = 'agent-loop';
+export const PERSIST_FINAL_MESSAGE_NODE = 'persist-final-message';
+export const EVALUATE_GUARDRAILS_NODE = 'evaluate-guardrails';
+export const PERSIST_PROVENANCE_NODE = 'persist-provenance';
+export const COMPOSE_RESULT_NODE = 'compose-result';
+
+// Loop body node ids.
+export const MODEL_CALL_NODE = 'model-call';
+export const DISPATCH_TOOLS_NODE = 'dispatch-tools';
+export const BUDGET_CHECK_NODE = 'budget-check';
+
+/**
+ * JSON Schema (draft 2020-12) for each iteration's `$loop-end` output.
+ * See `AgentTurnIterationOutput` in the handlers module for the TS
+ * mirror.
+ */
+const iterationOutputSchema = {
+  type: 'object',
+  additionalProperties: false,
+  required: [
+    'finishReason',
+    'message',
+    'iterationAppended',
+    'iterationUsage',
+    'provider',
+    'finishedTurn',
+    'nextMessages',
+  ],
+  properties: {
+    finishReason: {
+      type: 'string',
+      enum: ['stop', 'length', 'tool-use', 'content-filter', 'error'],
+    },
+    message: { type: 'object' },
+    iterationAppended: { type: 'array' },
+    iterationUsage: {
+      type: 'object',
+      additionalProperties: false,
+      required: ['promptTokens', 'completionTokens', 'costUsd'],
+      properties: {
+        promptTokens: { type: 'integer', minimum: 0 },
+        completionTokens: { type: 'integer', minimum: 0 },
+        costUsd: { type: 'number', minimum: 0 },
+      },
+    },
+    provider: {
+      type: 'object',
+      additionalProperties: false,
+      required: ['id', 'model'],
+      properties: {
+        id: { type: 'string' },
+        model: { type: 'string' },
+      },
+    },
+    finishedTurn: { type: 'boolean' },
+    nextMessages: { type: 'array' },
+    /** Populated when finishReason='error' from budget-check or dispatch failure. */
+    errorPayload: { type: 'object' },
+  },
+} as const;
+
+const rawGraph = {
+  id: AGENT_TURN_FLOW_ID,
+  version: AGENT_TURN_FLOW_VERSION,
+  name: 'Agent turn',
+  description:
+    'Framework-grade agent turn execution. One run per turn. Model↔tool cycle uses the kernel loop primitive.',
+  nodes: [
+    { id: SETUP_NODE, kind: 'tool', ref: 'inline' },
+    { id: RENDER_PROMPT_NODE, kind: 'tool', ref: 'inline' },
+    { id: PERSIST_USER_MESSAGE_NODE, kind: 'tool', ref: 'inline' },
+    { id: RUN_RETRIEVALS_NODE, kind: 'tool', ref: 'inline' },
+    { id: BUILD_INITIAL_MESSAGES_NODE, kind: 'tool', ref: 'inline' },
+    {
+      id: AGENT_LOOP_NODE,
+      kind: 'loop',
+      loopKind: 'while',
+      evaluationTiming: 'after',
+      maxIterations: AGENT_TURN_LOOP_MAX_ITERATIONS,
+      exitCondition: {
+        op: 'truthy',
+        value: { path: 'iterationOutput.finishedTurn' },
+      },
+      outputSchema: iterationOutputSchema,
+      collectAllIterations: true,
+      body: {
+        nodes: [
+          { id: MODEL_CALL_NODE, kind: 'tool', ref: 'inline' },
+          { id: DISPATCH_TOOLS_NODE, kind: 'tool', ref: 'inline' },
+          { id: BUDGET_CHECK_NODE, kind: 'tool', ref: 'inline' },
+        ],
+        edges: [
+          { id: 'body-e1', from: '$loop-start', to: MODEL_CALL_NODE },
+          { id: 'body-e2', from: MODEL_CALL_NODE, to: DISPATCH_TOOLS_NODE },
+          { id: 'body-e3', from: DISPATCH_TOOLS_NODE, to: BUDGET_CHECK_NODE },
+          { id: 'body-e4', from: BUDGET_CHECK_NODE, to: '$loop-end' },
+        ],
+      },
+    },
+    { id: EVALUATE_GUARDRAILS_NODE, kind: 'tool', ref: 'inline' },
+    { id: PERSIST_FINAL_MESSAGE_NODE, kind: 'tool', ref: 'inline' },
+    { id: PERSIST_PROVENANCE_NODE, kind: 'tool', ref: 'inline' },
+    { id: COMPOSE_RESULT_NODE, kind: 'tool', ref: 'inline' },
+  ],
+  edges: [
+    { id: 'e0', from: '$start', to: SETUP_NODE },
+    { id: 'e1', from: SETUP_NODE, to: RENDER_PROMPT_NODE },
+    { id: 'e2', from: RENDER_PROMPT_NODE, to: PERSIST_USER_MESSAGE_NODE },
+    { id: 'e3', from: PERSIST_USER_MESSAGE_NODE, to: RUN_RETRIEVALS_NODE },
+    { id: 'e4', from: RUN_RETRIEVALS_NODE, to: BUILD_INITIAL_MESSAGES_NODE },
+    { id: 'e5', from: BUILD_INITIAL_MESSAGES_NODE, to: AGENT_LOOP_NODE },
+    { id: 'e6', from: AGENT_LOOP_NODE, to: EVALUATE_GUARDRAILS_NODE },
+    { id: 'e7', from: EVALUATE_GUARDRAILS_NODE, to: PERSIST_FINAL_MESSAGE_NODE },
+    { id: 'e8', from: PERSIST_FINAL_MESSAGE_NODE, to: PERSIST_PROVENANCE_NODE },
+    { id: 'e9', from: PERSIST_PROVENANCE_NODE, to: COMPOSE_RESULT_NODE },
+    { id: 'e10', from: COMPOSE_RESULT_NODE, to: '$end' },
+  ],
+} as const;
+
+/**
+ * The compiled + validated flow. Cached — the loader is called once
+ * at module load. Throws on module load if the constant is malformed
+ * (should be caught by tests immediately).
+ */
+export const AGENT_TURN_FLOW: Flow = (() => {
+  const r = loadFlow(rawGraph);
+  if (r.kind === 'err') {
+    throw new Error(
+      `AGENT_TURN_FLOW failed to load — this is a bug in agent-turn-flow.ts: ${JSON.stringify(r.error)}`,
+    );
+  }
+  return r.value;
+})();