@happyvertical/smrt-personas 0.38.18

package/AGENTS.md

@@ -0,0 +1,85 @@
+# @happyvertical/smrt-personas
+
+Tenant-owned, context-scoped agent personas and their resolution. Layers over
+`@happyvertical/smrt-agents`' `TenantAgent` availability/ceiling gate to decide
+*how* an agent behaves for a given tenant and context (its `TenantAgent` binding
+decides *whether* it runs and caps its capabilities).
+
+This is the L2 foundation of the "learning agents" epic (#1885). Foundation
+only: `AgentPersona` + `PersonaResolver`. `ExecuteAsPrincipal`, feedback, the
+reflection runner, and multi-instance routing are separate issues
+(#1888/#1889/#1890).
+
+## Models
+
+- **AgentPersona** (`@TenantScoped({ mode: 'required' })`, table `agent_personas`):
+  a behavioral profile for one agent class within one tenant. Many per
+  `(tenant, agentClass)`; unique on `(tenant_id, agent_class, name)` via
+  `conflictColumns`. Fields:
+  - `agentClass` — canonical qualified agent type (e.g.
+    `@happyvertical/smrt-agents:Praeco`); stored canonical so it lines up with
+    `TenantAgent.agentClass`.
+  - `name` — persona name, unique per `(tenant, agentClass)`.
+  - `contextType` / `contextId` — optional scoping. No `contextType` = a
+    tenant-wide default; `contextType` only = type-scoped; both = exact context.
+  - `instructions` — system prompt layered onto the agent.
+  - `allowedTools` — JSON array of tool ids stored as a string; use
+    `getAllowedTools()` / `setAllowedTools()` (tolerant `try/catch` parse).
+  - `runAsUserId` — `@crossPackageRef('@happyvertical/smrt-users:User')`, the
+    principal the persona runs as.
+  - `actsAsProfileId` — optional `@crossPackageRef('@happyvertical/smrt-profiles:Profile')`,
+    a `Bot` identity for audit/attribution.
+  - `memoryScope` — memory/reflection partition key (empty → resolver-derived).
+  - `priority` — integer; higher wins among personas that apply at the same
+    tenant level.
+  - `enabled` — boolean; only enabled personas are resolved.
+
+## Collection
+
+`AgentPersonaCollection`:
+
+- `byTenantAndClass(tenantId, agentClass)` — all personas for the pair
+  (canonicalized), ordered by descending priority then name.
+- `findActive(tenantId, agentClass, context?)` — enabled personas applicable to
+  a context, same ordering.
+
+## PersonaResolver
+
+`resolve(tenantId, agentClass, context, options) → ResolvedPersona` layers,
+bottom to top: **manifest defaults → `TenantAgent` gate/ceiling → AgentPersona**.
+
+- **Hierarchy inheritance** mirrors `TenantAgentCollection.resolveForTenant`:
+  walks the requesting tenant then its ancestors (`options.getAncestorIds`,
+  nearest first). The nearest level with any applicable persona wins (a closer
+  level shadows a farther one).
+- **Selection within a level**: most context-specific first
+  (exact > type-scoped > tenant-wide), then highest `priority`, then name.
+- **Ceiling**: `options.availability` (a `PersonaAvailabilityGate`) gates
+  availability and intersects the resolved `allowedTools`. Build one from a
+  `ResolvedAgentAvailability` with `availabilityFromResolvedAgent()`.
+- **Default fallback**: when no persona applies, returns a defined default
+  (`source: 'default'`, `name: 'default'`) from manifest defaults + the gate.
+
+Because the walk reads personas across tenants, `resolve()` is intended for a
+system/admin path where cross-tenant reads are allowed — not inside a strict
+per-tenant interceptor context (same expectation as `resolveForTenant`).
+
+## Dependencies
+
+Leaf package (acyclic by construction — nothing depends back on it):
+
+- Runtime: `@happyvertical/smrt-core`, `@happyvertical/smrt-tenancy`,
+  `@happyvertical/smrt-agents` (the `TenantAgent` type it bridges).
+- `runAsUserId` / `actsAsProfileId` reference `@happyvertical/smrt-users` and
+  `@happyvertical/smrt-profiles` via `@crossPackageRef` string ids only — no
+  package edge (keeps the DAG minimal). No inter-`smrt-*` `peerDependencies`.
+
+## Gotchas
+
+- **`conflictColumns` replaces the default `(slug, context)` unique index** — the
+  unique key is `(tenant_id, agent_class, name)`, so same-named personas across
+  tenants are allowed and tenant isolation is preserved.
+- **`allowedTools` is text, not `type: 'json'`** — stored as a JSON string and
+  read through the helpers, so it never auto-hydrates to an object.
+- **Resolver runs outside strict tenant context** — it deliberately crosses
+  tenants to walk the hierarchy.

package/CLAUDE.md

@@ -0,0 +1 @@
+@AGENTS.md

package/LICENSE

@@ -0,0 +1,7 @@
+Copyright <2025> <Happy Vertical Corporation>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/dist/index.d.ts

@@ -0,0 +1,294 @@
+import { ResolvedAgentAvailability } from '@happyvertical/smrt-agents';
+import { SmrtCollection } from '@happyvertical/smrt-core';
+import { SmrtObject } from '@happyvertical/smrt-core';
+
+/**
+ * AgentPersona SmrtObject — a tenant/context-scoped behavioral profile for an
+ * agent class.
+ */
+export declare class AgentPersona extends SmrtObject {
+    /** Owning tenant (required — personas are never global). */
+    tenantId: string;
+    /**
+     * Canonical qualified agent type this persona configures
+     * (e.g. `@happyvertical/smrt-agents:Praeco`). Stored in canonical form so it
+     * lines up with `TenantAgent.agentClass`.
+     */
+    agentClass: string;
+    /**
+     * Human-readable persona name, unique per `(tenant, agentClass)`
+     * (see `conflictColumns`). Inherited `name` from {@link SmrtObject} is the
+     * conflict column; declared here for documentation and typing clarity.
+     */
+    name: string;
+    /**
+     * Optional context dimension type this persona is scoped to
+     * (e.g. `'site'`, `'property'`, `'chatRoom'`). `null` means the persona is a
+     * tenant-wide default that applies to every context for its agent class.
+     */
+    contextType: string | null;
+    /**
+     * Optional context dimension id. Only meaningful alongside `contextType`:
+     * when set, the persona targets one specific context row; when `null` (with
+     * a `contextType` set) it applies to every context of that type.
+     */
+    contextId: string | null;
+    /** System prompt / behavioral instructions layered onto the agent. */
+    instructions: string;
+    /**
+     * Allowed tool identifiers, stored as a JSON array string. Use
+     * {@link getAllowedTools} / {@link setAllowedTools} rather than reading this
+     * field directly. Empty array (`'[]'`) means "no persona-specific tools"
+     * (the resolver then falls back to manifest defaults, capped by the
+     * `TenantAgent` ceiling).
+     */
+    allowedTools: string;
+    /**
+     * The user whose principal this persona runs as (cross-package reference to
+     * `@happyvertical/smrt-users:User`). Required — a persona always runs as a
+     * concrete principal. Stored as a plain id column; no DDL FK constraint is
+     * emitted (cross-package).
+     */
+    runAsUserId: string;
+    /**
+     * Optional `Bot` profile the persona acts as for identity/audit
+     * (cross-package reference to `@happyvertical/smrt-profiles:Profile`).
+     * `null` when the persona has no distinct acting identity.
+     */
+    actsAsProfileId: string | null;
+    /**
+     * Memory scope key controlling how the agent's memory/reflection is
+     * partitioned for this persona. Empty string means "use a resolver-derived
+     * default".
+     */
+    memoryScope: string;
+    /**
+     * Resolution priority — higher wins when several personas apply to the same
+     * context at the same tenant level. Integer.
+     */
+    priority: number;
+    /** Whether this persona is active and eligible for resolution. */
+    enabled: boolean;
+    /**
+     * Allowed tool identifiers as an array.
+     *
+     * Tolerates malformed stored JSON by returning an empty array.
+     */
+    getAllowedTools(): string[];
+    /**
+     * Replace the allowed tool identifiers.
+     */
+    setAllowedTools(tools: string[]): void;
+}
+
+/**
+ * Collection for managing {@link AgentPersona} records.
+ */
+export declare class AgentPersonaCollection extends SmrtCollection<AgentPersona> {
+    static readonly _itemClass: typeof AgentPersona;
+    /**
+     * List personas for a tenant + agent class, matching either the canonical
+     * qualified name or the simple class name (see {@link agentClassAliases}).
+     *
+     * Ordered by descending priority then name.
+     *
+     * @param extraWhere - Additional equality filters merged into the query
+     *   (e.g. `{ enabled: true }`).
+     */
+    private listForClass;
+    /**
+     * List every persona bound to a tenant + agent class.
+     *
+     * Ordered by descending priority then name so callers that don't need the
+     * full resolver still get a deterministic, priority-first ordering.
+     */
+    byTenantAndClass(tenantId: string, agentClass: string): Promise<AgentPersona[]>;
+    /**
+     * List the enabled personas for a tenant + agent class, filtered to those
+     * applicable to a context.
+     *
+     * `enabled` is filtered in the query; the context predicate (tenant-wide vs
+     * type-scoped vs exact) is applied in memory since it is an OR over several
+     * columns. A persona is applicable when it is a tenant-wide default (no
+     * `contextType`) or its context matches the requested one. Ordered by
+     * descending priority then name.
+     *
+     * @param context - Optional `{ contextType, contextId }` to filter by.
+     */
+    findActive(tenantId: string, agentClass: string, context?: {
+        contextType?: string | null;
+        contextId?: string | null;
+    }): Promise<AgentPersona[]>;
+}
+
+/**
+ * Project a `TenantAgent` resolution into a {@link PersonaAvailabilityGate}.
+ *
+ * This is the concrete bridge between the `@happyvertical/smrt-agents`
+ * availability layer and the persona layer. Pass `toolPermissionPrefix` to
+ * derive a tool ceiling from granted permission ids (permissions whose id
+ * starts with the prefix become the ceiling, with the prefix stripped); omit it
+ * to leave the ceiling open.
+ *
+ * @param resolved - A `ResolvedAgentAvailability` (or `null`/`undefined`).
+ * @param options.toolPermissionPrefix - Permission-id prefix that marks
+ *   tool grants (e.g. `'tool:'`).
+ * @returns A gate, or `null` when `resolved` is nullish.
+ */
+export declare function availabilityFromResolvedAgent(resolved: ResolvedAgentAvailability | null | undefined, options?: {
+    toolPermissionPrefix?: string;
+}): PersonaAvailabilityGate | null;
+
+/**
+ * Return the canonical agent type identifier for storage and lookup.
+ *
+ * Uses the registry's qualified name when the class is registered and falls
+ * back to the raw input for dynamically defined or unregistered classes. This
+ * mirrors `getAgentTypeName()` in `@happyvertical/smrt-agents` without reaching
+ * into that package's internal module — personas store the same canonical form
+ * that `TenantAgent` does so the two layers line up.
+ */
+export declare function canonicalAgentClass(name: string): string;
+
+/**
+ * Bottom-layer defaults for an agent class, typically derived from its build
+ * manifest.
+ */
+export declare interface ManifestPersonaDefaults {
+    /** Default system instructions when no persona overrides them. */
+    instructions?: string;
+    /** Default tool identifiers, capped by the availability ceiling. */
+    allowedTools?: string[];
+    /** Default memory scope. */
+    memoryScope?: string;
+}
+
+/**
+ * Whether a persona applies to a requested context.
+ *
+ * - No `contextType` on the persona → tenant-wide default, applies to all.
+ * - `contextType` set, `contextId` null → type-scoped, applies when the
+ *   requested `contextType` matches.
+ * - Both set → exact, applies when both match.
+ */
+export declare function personaAppliesToContext(persona: Pick<AgentPersona, 'contextType' | 'contextId'>, context: {
+    contextType?: string | null;
+    contextId?: string | null;
+}): boolean;
+
+/**
+ * Middle-layer availability + capability ceiling, projected from a
+ * `TenantAgent` resolution.
+ */
+export declare interface PersonaAvailabilityGate {
+    /** Resolved `TenantAgent` status. `'disabled'` marks the persona unavailable. */
+    status: 'active' | 'disabled';
+    /**
+     * Tool identifiers the tenant is permitted to grant. When set, resolved
+     * `allowedTools` are intersected with this ceiling. `undefined` means no
+     * ceiling (tools pass through unchanged).
+     */
+    toolCeiling?: string[];
+    /** Tenant the binding was resolved from (provenance only). */
+    sourceTenantId?: string;
+}
+
+/**
+ * The context a persona is being resolved for.
+ */
+export declare interface PersonaContext {
+    /** Context dimension type (e.g. `'site'`). */
+    contextType?: string | null;
+    /** Context dimension id within `contextType`. */
+    contextId?: string | null;
+}
+
+/**
+ * Context-specificity rank used for resolution ordering.
+ *
+ * - `2` exact `(contextType, contextId)` match
+ * - `1` type-scoped match (`contextType` matches, persona `contextId` null)
+ * - `0` tenant-wide default (persona has no `contextType`)
+ */
+export declare function personaContextRank(persona: Pick<AgentPersona, 'contextType' | 'contextId'>): number;
+
+/**
+ * Resolves the active persona for a `(tenant, agentClass, context)` request.
+ */
+export declare class PersonaResolver {
+    private readonly personas;
+    constructor(personas: AgentPersonaCollection);
+    /**
+     * Resolve the active persona.
+     *
+     * @param tenantId - Requesting tenant.
+     * @param agentClass - Agent class (canonicalized internally).
+     * @param context - Context dimension being resolved for.
+     * @param options - Hierarchy walk, manifest defaults, and availability gate.
+     * @returns The layered {@link ResolvedPersona} — either a matched persona or
+     *   the defined default fallback.
+     */
+    resolve(tenantId: string, agentClass: string, context?: PersonaContext, options?: ResolvePersonaOptions): Promise<ResolvedPersona>;
+    private layerPersona;
+    private defaultResolution;
+}
+
+/**
+ * A fully resolved persona: the layered, ready-to-use configuration plus
+ * provenance describing how it was resolved.
+ */
+export declare interface ResolvedPersona {
+    /** Canonical qualified agent type the resolution was for. */
+    agentClass: string;
+    /** Tenant the resolution was requested for. */
+    tenantId: string;
+    /** Id of the selected persona, or `undefined` for the default fallback. */
+    personaId?: string;
+    /** Selected persona name, or `'default'` for the fallback. */
+    name: string;
+    /** Layered instructions (persona → manifest default). */
+    instructions: string;
+    /** Layered tool ids (persona/manifest tools, capped by the ceiling). */
+    allowedTools: string[];
+    /** Run-as user principal, if the selected persona sets one. */
+    runAsUserId?: string;
+    /** Acting `Bot` profile id, if the selected persona sets one. */
+    actsAsProfileId?: string | null;
+    /** Resolved memory scope (persona → manifest default → derived default). */
+    memoryScope: string;
+    /** Selected persona priority (`0` for the default fallback). */
+    priority: number;
+    /** Context type the resolution was requested for. */
+    contextType?: string | null;
+    /** Context id the resolution was requested for. */
+    contextId?: string | null;
+    /** Whether a persona matched (`'persona'`) or the default was used (`'default'`). */
+    source: 'persona' | 'default';
+    /** For a matched persona, whether it was the tenant's own or inherited. */
+    personaSource?: 'explicit' | 'inherited';
+    /** Tenant the matched persona came from (own tenant or an ancestor). */
+    sourceTenantId?: string;
+    /** Whether the `TenantAgent` gate reports the agent as available. */
+    available: boolean;
+}
+
+/**
+ * Options for {@link PersonaResolver.resolve}.
+ */
+export declare interface ResolvePersonaOptions {
+    /**
+     * Return ancestor tenant ids for a tenant, nearest parent first through to
+     * the root — mirrors `TenantAgentCollection.resolveForTenant`. Omit for a
+     * single-tenant resolution with no inheritance.
+     */
+    getAncestorIds?: (tenantId: string) => Promise<string[]>;
+    /** Bottom-layer manifest defaults for the agent class. */
+    manifestDefaults?: ManifestPersonaDefaults;
+    /**
+     * Middle-layer `TenantAgent` availability + ceiling. Omit to skip gating
+     * (the result is always `available: true` with no tool ceiling).
+     */
+    availability?: PersonaAvailabilityGate | null;
+}
+
+export { }