@happyvertical/smrt-personas 0.38.18

package/dist/smrt-knowledge.json

@@ -0,0 +1,311 @@
+{
+  "schemaVersion": 1,
+  "generatedAt": "2026-07-09T01:22:04.866Z",
+  "packageName": "@happyvertical/smrt-personas",
+  "packageVersion": "0.38.18",
+  "sourceManifestPath": "dist/manifest.json",
+  "agentDocPath": "AGENTS.md",
+  "sourceHashes": {
+    "manifest": "096dbac08a846b0a0c9c3eff123d85bd9b47c9638db3e5ff4354ef0f60642b6b",
+    "packageJson": "b06371e5956e3d28275e5fcf417aa9c32b0ed89ab0cd9691b9e354dd63e70391",
+    "agents": "ef998dbc563d3d2905c694cd77a99576a6fd2d16d10f675014dbbe9aec1cbf5f"
+  },
+  "exports": [
+    ".",
+    "./manifest",
+    "./manifest.json"
+  ],
+  "dependencies": {
+    "@happyvertical/smrt-agents": "workspace:*",
+    "@happyvertical/smrt-core": "workspace:*",
+    "@happyvertical/smrt-tenancy": "workspace:*",
+    "@happyvertical/smrt-vitest": "workspace:*",
+    "@types/node": "24.13.2",
+    "typescript": "^5.9.3",
+    "vite": "^8.1.3",
+    "vitest": "^4.1.9"
+  },
+  "smrtDependencies": [
+    "@happyvertical/smrt-agents",
+    "@happyvertical/smrt-core",
+    "@happyvertical/smrt-tenancy",
+    "@happyvertical/smrt-vitest"
+  ],
+  "sdkDependencies": [],
+  "tags": [],
+  "risks": [],
+  "objects": [
+    {
+      "name": "AgentPersona",
+      "qualifiedName": "@happyvertical/smrt-personas:AgentPersona",
+      "collection": "agentpersonas",
+      "tableName": "agent_personas",
+      "packageName": "@happyvertical/smrt-personas",
+      "extends": "SmrtObject",
+      "fields": [
+        {
+          "name": "tenantId",
+          "type": "text",
+          "required": true,
+          "columnType": "UUID"
+        },
+        {
+          "name": "agentClass",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "name",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "contextType",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "contextId",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "instructions",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "allowedTools",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "runAsUserId",
+          "type": "crossPackageRef",
+          "required": true,
+          "related": "@happyvertical/smrt-users:User",
+          "columnType": "UUID"
+        },
+        {
+          "name": "actsAsProfileId",
+          "type": "crossPackageRef",
+          "required": false,
+          "related": "@happyvertical/smrt-profiles:Profile",
+          "columnType": "UUID"
+        },
+        {
+          "name": "memoryScope",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "priority",
+          "type": "integer",
+          "required": false,
+          "columnType": "INTEGER"
+        },
+        {
+          "name": "enabled",
+          "type": "boolean",
+          "required": false,
+          "columnType": "BOOLEAN"
+        }
+      ],
+      "relationships": [
+        {
+          "name": "runAsUserId",
+          "type": "crossPackageRef",
+          "required": true,
+          "related": "@happyvertical/smrt-users:User",
+          "columnType": "UUID"
+        },
+        {
+          "name": "actsAsProfileId",
+          "type": "crossPackageRef",
+          "required": false,
+          "related": "@happyvertical/smrt-profiles:Profile",
+          "columnType": "UUID"
+        }
+      ],
+      "methods": [
+        "getAllowedTools",
+        "setAllowedTools"
+      ],
+      "surfaces": [
+        {
+          "kind": "api",
+          "name": "agentpersonas.list",
+          "operation": "list",
+          "objectName": "@happyvertical/smrt-personas:AgentPersona",
+          "path": "/agentpersonas",
+          "method": "GET"
+        },
+        {
+          "kind": "api",
+          "name": "agentpersonas.get",
+          "operation": "get",
+          "objectName": "@happyvertical/smrt-personas:AgentPersona",
+          "path": "/agentpersonas/[id]",
+          "method": "GET"
+        },
+        {
+          "kind": "api",
+          "name": "agentpersonas.create",
+          "operation": "create",
+          "objectName": "@happyvertical/smrt-personas:AgentPersona",
+          "path": "/agentpersonas",
+          "method": "POST"
+        },
+        {
+          "kind": "api",
+          "name": "agentpersonas.update",
+          "operation": "update",
+          "objectName": "@happyvertical/smrt-personas:AgentPersona",
+          "path": "/agentpersonas/[id]",
+          "method": "PATCH"
+        },
+        {
+          "kind": "api",
+          "name": "agentpersonas.delete",
+          "operation": "delete",
+          "objectName": "@happyvertical/smrt-personas:AgentPersona",
+          "path": "/agentpersonas/[id]",
+          "method": "DELETE"
+        },
+        {
+          "kind": "cli",
+          "name": "agentpersona_list",
+          "operation": "list",
+          "objectName": "@happyvertical/smrt-personas:AgentPersona"
+        },
+        {
+          "kind": "cli",
+          "name": "agentpersona_get",
+          "operation": "get",
+          "objectName": "@happyvertical/smrt-personas:AgentPersona"
+        },
+        {
+          "kind": "mcp",
+          "name": "agentpersona_list",
+          "operation": "list",
+          "objectName": "@happyvertical/smrt-personas:AgentPersona"
+        },
+        {
+          "kind": "mcp",
+          "name": "agentpersona_get",
+          "operation": "get",
+          "objectName": "@happyvertical/smrt-personas:AgentPersona"
+        }
+      ],
+      "relationshipFeatures": [
+        "crossPackageRef",
+        "uuidColumns"
+      ],
+      "tags": [],
+      "risks": []
+    },
+    {
+      "name": "AgentPersonaCollection",
+      "qualifiedName": "@happyvertical/smrt-personas:AgentPersonaCollection",
+      "collection": "agentpersonas",
+      "tableName": "agent_personas",
+      "packageName": "@happyvertical/smrt-personas",
+      "extends": "SmrtCollection",
+      "fields": [],
+      "relationships": [],
+      "methods": [
+        "byTenantAndClass",
+        "findActive"
+      ],
+      "surfaces": [],
+      "relationshipFeatures": [
+        "uuidColumns"
+      ],
+      "tags": [],
+      "risks": []
+    }
+  ],
+  "surfaces": [
+    {
+      "kind": "api",
+      "name": "agentpersonas.list",
+      "operation": "list",
+      "objectName": "@happyvertical/smrt-personas:AgentPersona",
+      "path": "/agentpersonas",
+      "method": "GET"
+    },
+    {
+      "kind": "api",
+      "name": "agentpersonas.get",
+      "operation": "get",
+      "objectName": "@happyvertical/smrt-personas:AgentPersona",
+      "path": "/agentpersonas/[id]",
+      "method": "GET"
+    },
+    {
+      "kind": "api",
+      "name": "agentpersonas.create",
+      "operation": "create",
+      "objectName": "@happyvertical/smrt-personas:AgentPersona",
+      "path": "/agentpersonas",
+      "method": "POST"
+    },
+    {
+      "kind": "api",
+      "name": "agentpersonas.update",
+      "operation": "update",
+      "objectName": "@happyvertical/smrt-personas:AgentPersona",
+      "path": "/agentpersonas/[id]",
+      "method": "PATCH"
+    },
+    {
+      "kind": "api",
+      "name": "agentpersonas.delete",
+      "operation": "delete",
+      "objectName": "@happyvertical/smrt-personas:AgentPersona",
+      "path": "/agentpersonas/[id]",
+      "method": "DELETE"
+    },
+    {
+      "kind": "cli",
+      "name": "agentpersona_list",
+      "operation": "list",
+      "objectName": "@happyvertical/smrt-personas:AgentPersona"
+    },
+    {
+      "kind": "cli",
+      "name": "agentpersona_get",
+      "operation": "get",
+      "objectName": "@happyvertical/smrt-personas:AgentPersona"
+    },
+    {
+      "kind": "mcp",
+      "name": "agentpersona_list",
+      "operation": "list",
+      "objectName": "@happyvertical/smrt-personas:AgentPersona"
+    },
+    {
+      "kind": "mcp",
+      "name": "agentpersona_get",
+      "operation": "get",
+      "objectName": "@happyvertical/smrt-personas:AgentPersona"
+    }
+  ],
+  "prompts": [],
+  "relationshipsV2": {
+    "foreignKeyFields": 0,
+    "crossPackageRefFields": 2,
+    "junctionCollections": 0,
+    "hierarchicalObjects": 0,
+    "polymorphicAssociations": 0,
+    "uuidColumns": 5
+  },
+  "agentDoc": "# @happyvertical/smrt-personas\n\nTenant-owned, context-scoped agent personas and their resolution. Layers over\n`@happyvertical/smrt-agents`' `TenantAgent` availability/ceiling gate to decide\n*how* an agent behaves for a given tenant and context (its `TenantAgent` binding\ndecides *whether* it runs and caps its capabilities).\n\nThis is the L2 foundation of the \"learning agents\" epic (#1885). Foundation\nonly: `AgentPersona` + `PersonaResolver`. `ExecuteAsPrincipal`, feedback, the\nreflection runner, and multi-instance routing are separate issues\n(#1888/#1889/#1890).\n\n## Models\n\n- **AgentPersona** (`@TenantScoped({ mode: 'required' })`, table `agent_personas`):\n  a behavioral profile for one agent class within one tenant. Many per\n  `(tenant, agentClass)`; unique on `(tenant_id, agent_class, name)` via\n  `conflictColumns`. Fields:\n  - `agentClass` — canonical qualified agent type (e.g.\n    `@happyvertical/smrt-agents:Praeco`); stored canonical so it lines up with\n    `TenantAgent.agentClass`.\n  - `name` — persona name, unique per `(tenant, agentClass)`.\n  - `contextType` / `contextId` — optional scoping. No `contextType` = a\n    tenant-wide default; `contextType` only = type-scoped; both = exact context.\n  - `instructions` — system prompt layered onto the agent.\n  - `allowedTools` — JSON array of tool ids stored as a string; use\n    `getAllowedTools()` / `setAllowedTools()` (tolerant `try/catch` parse).\n  - `runAsUserId` — `@crossPackageRef('@happyvertical/smrt-users:User')`, the\n    principal the persona runs as.\n  - `actsAsProfileId` — optional `@crossPackageRef('@happyvertical/smrt-profiles:Profile')`,\n    a `Bot` identity for audit/attribution.\n  - `memoryScope` — memory/reflection partition key (empty → resolver-derived).\n  - `priority` — integer; higher wins among personas that apply at the same\n    tenant level.\n  - `enabled` — boolean; only enabled personas are resolved.\n\n## Collection\n\n`AgentPersonaCollection`:\n\n- `byTenantAndClass(tenantId, agentClass)` — all personas for the pair\n  (canonicalized), ordered by descending priority then name.\n- `findActive(tenantId, agentClass, context?)` — enabled personas applicable to\n  a context, same ordering.\n\n## PersonaResolver\n\n`resolve(tenantId, agentClass, context, options) → ResolvedPersona` layers,\nbottom to top: **manifest defaults → `TenantAgent` gate/ceiling → AgentPersona**.\n\n- **Hierarchy inheritance** mirrors `TenantAgentCollection.resolveForTenant`:\n  walks the requesting tenant then its ancestors (`options.getAncestorIds`,\n  nearest first). The nearest level with any applicable persona wins (a closer\n  level shadows a farther one).\n- **Selection within a level**: most context-specific first\n  (exact > type-scoped > tenant-wide), then highest `priority`, then name.\n- **Ceiling**: `options.availability` (a `PersonaAvailabilityGate`) gates\n  availability and intersects the resolved `allowedTools`. Build one from a\n  `ResolvedAgentAvailability` with `availabilityFromResolvedAgent()`.\n- **Default fallback**: when no persona applies, returns a defined default\n  (`source: 'default'`, `name: 'default'`) from manifest defaults + the gate.\n\nBecause the walk reads personas across tenants, `resolve()` is intended for a\nsystem/admin path where cross-tenant reads are allowed — not inside a strict\nper-tenant interceptor context (same expectation as `resolveForTenant`).\n\n## Dependencies\n\nLeaf package (acyclic by construction — nothing depends back on it):\n\n- Runtime: `@happyvertical/smrt-core`, `@happyvertical/smrt-tenancy`,\n  `@happyvertical/smrt-agents` (the `TenantAgent` type it bridges).\n- `runAsUserId` / `actsAsProfileId` reference `@happyvertical/smrt-users` and\n  `@happyvertical/smrt-profiles` via `@crossPackageRef` string ids only — no\n  package edge (keeps the DAG minimal). No inter-`smrt-*` `peerDependencies`.\n\n## Gotchas\n\n- **`conflictColumns` replaces the default `(slug, context)` unique index** — the\n  unique key is `(tenant_id, agent_class, name)`, so same-named personas across\n  tenants are allowed and tenant isolation is preserved.\n- **`allowedTools` is text, not `type: 'json'`** — stored as a JSON string and\n  read through the helpers, so it never auto-hydrates to an object.\n- **Resolver runs outside strict tenant context** — it deliberately crosses\n  tenants to walk the hierarchy.\n"
+}

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "@happyvertical/smrt-personas",
+  "version": "0.38.18",
+  "description": "Tenant-owned, context-scoped agent personas and resolution for the SMRT framework",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "CLAUDE.md",
+    "AGENTS.md"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./manifest": "./dist/manifest.json",
+    "./manifest.json": "./dist/manifest.json"
+  },
+  "dependencies": {
+    "@happyvertical/smrt-agents": "0.38.18",
+    "@happyvertical/smrt-tenancy": "0.38.18",
+    "@happyvertical/smrt-core": "0.38.18"
+  },
+  "devDependencies": {
+    "@types/node": "24.13.2",
+    "typescript": "^5.9.3",
+    "vite": "^8.1.3",
+    "vitest": "^4.1.9",
+    "@happyvertical/smrt-vitest": "0.38.18"
+  },
+  "keywords": [
+    "smrt",
+    "agents",
+    "personas",
+    "multi-tenant",
+    "resolution"
+  ],
+  "author": "HappyVertical",
+  "license": "MIT",
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org",
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/happyvertical/smrt.git",
+    "directory": "packages/personas"
+  },
+  "scripts": {
+    "build": "vite build --mode library",
+    "build:watch": "vite build --mode library --watch",
+    "clean": "rm -rf dist",
+    "dev": "vite dev",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit -p tsconfig.json",
+    "verify:pack": "node ../../scripts/verify-package-types-exports.js ."
+  }
+}