@happyvertical/smrt-personas 0.38.19 → 0.38.21

package/AGENTS.md

@@ -5,10 +5,13 @@ Tenant-owned, context-scoped agent personas and their resolution. Layers over
 *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).
+This is the L2 layer of the "learning agents" epic (#1885): the persona foundation
+(`AgentPersona` + `PersonaResolver`), the **persona learning & adaptation loop**
+(#1889) — feedback → confidence-scored reinforcement → a scheduled reflection
+runner that emits pending directive proposals → a permission-gated approval
+surface that activates an approved rewrite as a tenant/persona-scoped prompt
+override — and the persona-as-durable-instance / multi-instance helpers (#1890,
+below). `ExecuteAsPrincipal` remains a separate issue (#1888).
 
 ## Models
 
@@ -34,6 +37,67 @@ reflection runner, and multi-instance routing are separate issues
     tenant level.
   - `enabled` — boolean; only enabled personas are resolved.
 
+- **Feedback** (`@TenantScoped({ mode: 'optional' })`, table `agent_feedback`):
+  one reinforcement signal against a persona and the learning episode it judges.
+  Human signals (`accept` / `reject` / `correction` / `rating`) and autonomous
+  signals (`outcome` / `metric`) each carry a required **`correlationId`** (+
+  optional `correlationType`) back to the AI call / dispatch / job. `scope` /
+  `key` name the `LearningMemory` episode; `toLearningOutcome()` maps the signal
+  onto a `LearningOutcome` (feeds reinforcement, #1886). `FeedbackCollection`:
+  `forPersona`, `forScope`, `byCorrelation`.
+
+- **DirectiveProposal** (`@TenantScoped({ mode: 'required' })`, table
+  `directive_proposals`): a pending, human-reviewable proposed edit to a
+  persona's `instructions`. Read-only generated surface (`api`/`cli`/`mcp` =
+  `list`/`get`) — writes go through the gated approval service, not CRUD. Key
+  fields: `promptKey`, `proposedInstructions`, `currentInstructions` (diff),
+  `rationale`, `evidence` (JSON: episode + feedback ids), `status`
+  (`pending`/`approved`/`rejected`/`superseded`), `fingerprint` (dedup so a
+  rejected rewrite is never re-surfaced), `proposedBy`, `reviewedBy` /
+  `reviewedAt` / `activatedOverrideId`. `DirectiveProposalCollection`:
+  `pending(...)` (the review queue), `findByFingerprint(...)`.
+
+## Learning loop (#1889)
+
+- **Persona instructions via prompt overrides** (`persona-prompt.ts`): a
+  persona's instructions apply through a per-persona registered prompt key
+  (`persona.<id>.instructions`, neutral empty base template) plus a
+  tenant-scoped `prompt_override`. Two personas of the same tenant/class resolve
+  different instructions without colliding on the override `(key, context)`
+  identity. `ensurePersonaInstructionsPrompt` (idempotent registration,
+  `editable` configurable), `applyPersonaInstructions` /
+  `upsertPromptTemplateOverride` (write the override — flows through
+  `PromptOverride.save()` → `validatePromptOverride`, so a non-editable template
+  is refused), `resolvePersonaInstructions`.
+- **Memory scoping** (`persona-memory.ts`): `personaLearningMemory` routes a
+  `LearningMemory` by the persona's `memoryScope` (used as `owner_id`), so
+  personas learn independently. `reinforceFromFeedback` applies a `Feedback`
+  signal to memory as automatic, confidence-only reinforcement (ungated).
+- **ReflectionRunner** (`reflection-runner.ts`): a schedulable pass that, under
+  the autonomous reflection principal (which **lacks**
+  `personas.activate-directive`), reinforces recent feedback, consolidates
+  episodes + feedback via an injected `reflect` boundary (the AI call, mocked in
+  tests), and records a **pending** `DirectiveProposal` (deduped by fingerprint).
+  It cannot activate anything.
+- **The gate = a permission split** (`directive-principal.ts`,
+  `directive-approval.ts`): activating a directive is the permissioned operation
+  `personas.activate-directive` (contributed to the manifest permission catalog
+  via `registerPermissionDefinitions`). `DirectiveApprovalService.approve` /
+  `reject` first `assertCanActivate(principal)`; approval writes the
+  persona-scoped override and records an `accept` signal, rejection records a
+  `reject` signal and closes the proposal. A `DirectivePrincipal` is built from
+  granted slugs (`principalFromPermissions`) or a `PermissionResolver`
+  (`resolveDirectivePrincipal`).
+
+## Svelte UI
+
+`@happyvertical/smrt-personas/svelte` ships a minimal, presentational
+`DirectiveReviewQueue` component (Svelte 5): it lists pending proposals with a
+current-vs-proposed diff and Approve/Reject actions, delegating to `onApprove`
+(optionally with reviewer-edited text) / `onReject` callbacks a host wires to
+the gated `DirectiveApprovalService`. Built with `svelte-package`; Svelte tests
+run in CI only.
+
 ## Collection
 
 `AgentPersonaCollection`:
@@ -64,15 +128,51 @@ 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`).
 
+## Persona as Durable Instance (#1890)
+
+A persona is a **durable instance** of an agent class — N per tenant, each
+independently scheduled, memory-scoped, and permission-scoped. `persona-instance.ts`
+wires that to the `@happyvertical/smrt-agents` multi-instance primitives (which are
+per-package opt-in via `static multiInstance`, singleton by default):
+
+- **Identity** — `personaInstanceKey(persona)` returns the persona id, or `null`
+  for the `default` persona (`DEFAULT_PERSONA_NAME`). A `null` key reuses the
+  **singleton** runtime identity (class-keyed dispatch subscriber + un-suffixed
+  memory scope). `agentOptionsForPersona(persona)` projects `{ instanceKey,
+  tenantId }` to spread into the agent constructor.
+- **Scheduling** — `schedulePersonaInstance(schedules, persona, { cron, … })`
+  creates an `AgentSchedule` for the instance. The instance key rides in
+  `agentConfig` (which the scheduler spreads into the agent constructor →
+  `AgentOptions.instanceKey`); `agentId` is left **null** on purpose, because the
+  scheduler copies `agentId`→`SmrtJob.objectId` and the `TaskRunner`
+  `loadFromId()`s it against the agent's STI table — a persona id is not a row
+  there. The default persona carries no key → runs the singleton.
+- **Admin** — `buildPersonaInstanceAdmin(personas, { tenantId, agentClass,
+  manifest })` renders the class's `uiSlots`/`adminRoutes` **once per instance**
+  (with the per-instance dispatch subscriber); `addPersonaInstance()` /
+  `removePersonaInstance(personaId)` are the add/remove affordances.
+- **Non-destructive upgrade** — `upgradeSingletonToDefaultPersona(personas, {
+  tenantId, agentClass, runAsUserId, … })` maps an existing singleton to a single
+  `default` persona. It's null-keyed, so the running agent's dispatch subscriber,
+  memory, and config are untouched; idempotent (a second call returns the
+  existing default with `created: false` and never overwrites it).
+
 ## 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).
+  `@happyvertical/smrt-agents` (the `TenantAgent` type it bridges, plus the
+  `AgentSchedule`/multi-instance surface `persona-instance.ts` builds on),
+  `@happyvertical/smrt-prompts` (persona instructions via `PromptOverride` +
+  `resolvePrompt`), `@happyvertical/smrt-users` (the permission catalog slug +
+  `PermissionResolver` principal), and `@happyvertical/sql` (`DatabaseInterface`
+  type). These edges are all acyclic (none of those packages depend on personas).
+- Svelte peer + `@happyvertical/smrt-ui` for the optional `./svelte` review-queue
+  component.
 - `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`.
+  `@happyvertical/smrt-profiles` via `@crossPackageRef` string ids only. No
+  inter-`smrt-*` `peerDependencies`.
 
 ## Gotchas
 
@@ -83,3 +183,15 @@ Leaf package (acyclic by construction — nothing depends back on it):
   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.
+- **The gate is the permission split, not a bespoke check** — the reflection
+  principal simply lacks `personas.activate-directive`, so it can only propose;
+  everything privileged in `DirectiveApprovalService` calls `assertCanActivate`
+  first. Instruction rewrites are gated; confidence-only reinforcement is not.
+- **Persona instructions live in the override layer, not the base prompt** — the
+  per-persona prompt key registers a neutral empty template, so re-registration
+  stays idempotent as instructions change; the tenant-scoped override carries the
+  actual text. Activation still honours `validatePromptOverride` editability.
+- **Directive dedup is by fingerprint across all statuses** — the runner skips a
+  proposal whose `(personaId, promptKey, proposedInstructions)` fingerprint
+  already exists (pending, approved, or rejected), so a rejected rewrite is never
+  re-surfaced.

package/dist/__smrt-register__.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=__smrt-register__.d.ts.map

package/dist/__smrt-register__.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"__smrt-register__.d.ts","sourceRoot":"","sources":["../src/__smrt-register__.ts"],"names":[],"mappings":""}

package/dist/agent-persona.d.ts

@@ -0,0 +1,161 @@
+import { SmrtCollection, SmrtObject } from '@happyvertical/smrt-core';
+/**
+ * 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;
+/**
+ * Return the meaningful aliases for an agent class — the canonical qualified
+ * name plus the simple class name — deduplicated.
+ *
+ * Lookups match against both so a persona persisted under a simple name (e.g.
+ * `Praeco`, when written through the generated create API without
+ * normalization) is still found when resolving under the canonical qualified
+ * name, and vice versa. Mirrors `getAgentTypeAliases()` in
+ * `@happyvertical/smrt-agents`.
+ */
+export declare function agentClassAliases(name: string): string[];
+/**
+ * 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[]>;
+}
+/**
+ * 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;
+/**
+ * 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;
+export default AgentPersona;
+//# sourceMappingURL=agent-persona.d.ts.map

package/dist/agent-persona.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-persona.d.ts","sourceRoot":"","sources":["../src/agent-persona.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,EAKL,cAAc,EACd,UAAU,EAEX,MAAM,0BAA0B,CAAC;AAGlC;;;;;;;;GAQG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAGxD;AAED;;;;;;;;;GASG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,CAKxD;AAmBD;;;GAGG;AACH,qBAQa,YAAa,SAAQ,UAAU;IAC1C,4DAA4D;IAE5D,QAAQ,EAAE,MAAM,CAAM;IAEtB;;;;OAIG;IAEH,UAAU,EAAE,MAAM,CAAM;IAExB;;;;OAIG;IACH,IAAI,EAAE,MAAM,CAAM;IAElB;;;;OAIG;IAEH,WAAW,EAAE,MAAM,GAAG,IAAI,CAAQ;IAElC;;;;OAIG;IAEH,SAAS,EAAE,MAAM,GAAG,IAAI,CAAQ;IAEhC,sEAAsE;IAEtE,YAAY,EAAE,MAAM,CAAM;IAE1B;;;;;;OAMG;IAEH,YAAY,EAAE,MAAM,CAAQ;IAE5B;;;;;OAKG;IAEH,WAAW,EAAE,MAAM,CAAM;IAEzB;;;;OAIG;IAEH,eAAe,EAAE,MAAM,GAAG,IAAI,CAAQ;IAEtC;;;;OAIG;IAEH,WAAW,EAAE,MAAM,CAAM;IAEzB;;;OAGG;IACH,QAAQ,EAAE,MAAM,CAAK;IAErB,kEAAkE;IAElE,OAAO,EAAE,OAAO,CAAQ;IAExB;;;;OAIG;IACH,eAAe,IAAI,MAAM,EAAE;IAI3B;;OAEG;IACH,eAAe,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,IAAI;CAGvC;AAED;;GAEG;AACH,qBAAa,sBAAuB,SAAQ,cAAc,CAAC,YAAY,CAAC;IACtE,MAAM,CAAC,QAAQ,CAAC,UAAU,sBAAgB;IAE1C;;;;;;;;OAQG;YACW,YAAY;IAc1B;;;;;OAKG;IACG,gBAAgB,CACpB,QAAQ,EAAE,MAAM,EAChB,UAAU,EAAE,MAAM,GACjB,OAAO,CAAC,YAAY,EAAE,CAAC;IAI1B;;;;;;;;;;;OAWG;IACG,UAAU,CACd,QAAQ,EAAE,MAAM,EAChB,UAAU,EAAE,MAAM,EAClB,OAAO,GAAE;QAAE,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;QAAC,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;KAAO,GACvE,OAAO,CAAC,YAAY,EAAE,CAAC;CAQ3B;AAED;;;;;;;GAOG;AACH,wBAAgB,uBAAuB,CACrC,OAAO,EAAE,IAAI,CAAC,YAAY,EAAE,aAAa,GAAG,WAAW,CAAC,EACxD,OAAO,EAAE;IAAE,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAAC,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,GAClE,OAAO,CAWT;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAChC,OAAO,EAAE,IAAI,CAAC,YAAY,EAAE,aAAa,GAAG,WAAW,CAAC,GACvD,MAAM,CAKR;AAWD,eAAe,YAAY,CAAC"}

package/dist/directive-approval.d.ts

@@ -0,0 +1,94 @@
+import { PromptOverride } from '@happyvertical/smrt-prompts';
+import { DatabaseInterface } from '@happyvertical/sql';
+import { AgentPersonaCollection } from './agent-persona.js';
+import { DirectivePrincipal } from './directive-principal.js';
+import { DirectiveProposal, DirectiveProposalCollection } from './directive-proposal.js';
+import { Feedback, FeedbackCollection } from './feedback.js';
+/** Raised when a principal without the activation permission attempts to review. */
+export declare class DirectiveActivationDeniedError extends Error {
+    constructor(message?: string);
+}
+/** Raised when a review is attempted on a proposal that is not pending. */
+export declare class DirectiveNotPendingError extends Error {
+    constructor(status: string);
+}
+/** Options for {@link DirectiveApprovalService}. */
+export interface DirectiveApprovalServiceOptions {
+    db: DatabaseInterface;
+    proposals?: DirectiveProposalCollection;
+    feedback?: FeedbackCollection;
+    personas?: AgentPersonaCollection;
+}
+/** Result of approving a proposal. */
+export interface DirectiveApprovalResult {
+    proposal: DirectiveProposal;
+    /** The activated persona-scoped override. */
+    override: PromptOverride;
+    /** The recorded `accept` signal. */
+    signal: Feedback;
+}
+/** Result of rejecting a proposal. */
+export interface DirectiveRejectionResult {
+    proposal: DirectiveProposal;
+    /** The recorded `reject` signal. */
+    signal: Feedback;
+}
+/** A proposal reference: the row, or its id. */
+export type ProposalRef = DirectiveProposal | string;
+/**
+ * The permission-gated review surface for persona directives.
+ */
+export declare class DirectiveApprovalService {
+    private readonly db;
+    private proposals?;
+    private feedback?;
+    private personas?;
+    constructor(options: DirectiveApprovalServiceOptions);
+    /**
+     * Assert a principal is authorised to review directives. The single gate:
+     * everything privileged in this service calls it first.
+     *
+     * @throws {DirectiveActivationDeniedError} when the principal lacks the slug.
+     */
+    assertCanActivate(principal: DirectivePrincipal): void;
+    /**
+     * Assert a principal may review a specific proposal: its resolved tenant, when
+     * bound, must match the proposal's tenant. Permissions are resolved per
+     * tenant, so holding the slug in one tenant must not authorise activating
+     * another tenant's directive.
+     *
+     * @throws {DirectiveActivationDeniedError} on a cross-tenant attempt.
+     */
+    private assertTenantMatch;
+    /**
+     * Approve a pending proposal: activate the persona-scoped override and record
+     * an `accept` signal. Pass `editedInstructions` to activate a revised text
+     * (the proposal keeps the model's original as its audit record; the override
+     * holds what was activated).
+     *
+     * @throws {DirectiveActivationDeniedError} when the principal lacks the slug.
+     * @throws {DirectiveNotPendingError} when the proposal is already reviewed.
+     */
+    approve(ref: ProposalRef, principal: DirectivePrincipal, options?: {
+        note?: string;
+        editedInstructions?: string;
+    }): Promise<DirectiveApprovalResult>;
+    /**
+     * Reject a pending proposal: record a `reject` signal and close it so it is
+     * never re-surfaced.
+     *
+     * @throws {DirectiveActivationDeniedError} when the principal lacks the slug.
+     * @throws {DirectiveNotPendingError} when the proposal is already reviewed.
+     */
+    reject(ref: ProposalRef, principal: DirectivePrincipal, options?: {
+        note?: string;
+    }): Promise<DirectiveRejectionResult>;
+    private loadPending;
+    private getProposal;
+    private recordSignal;
+    private syncPersonaInstructions;
+    private personasCollection;
+    private proposalsCollection;
+    private feedbackCollection;
+}
+//# sourceMappingURL=directive-approval.d.ts.map

package/dist/directive-approval.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"directive-approval.d.ts","sourceRoot":"","sources":["../src/directive-approval.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,6BAA6B,CAAC;AAClE,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AAC5D,OAAO,EAAE,sBAAsB,EAAE,MAAM,oBAAoB,CAAC;AAC5D,OAAO,EAEL,KAAK,kBAAkB,EACxB,MAAM,0BAA0B,CAAC;AAClC,OAAO,EACL,iBAAiB,EACjB,2BAA2B,EAC5B,MAAM,yBAAyB,CAAC;AACjC,OAAO,EAAE,KAAK,QAAQ,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAC;AAGlE,oFAAoF;AACpF,qBAAa,8BAA+B,SAAQ,KAAK;gBAErD,OAAO,SAA4G;CAKtH;AAED,2EAA2E;AAC3E,qBAAa,wBAAyB,SAAQ,KAAK;gBACrC,MAAM,EAAE,MAAM;CAI3B;AAED,oDAAoD;AACpD,MAAM,WAAW,+BAA+B;IAC9C,EAAE,EAAE,iBAAiB,CAAC;IACtB,SAAS,CAAC,EAAE,2BAA2B,CAAC;IACxC,QAAQ,CAAC,EAAE,kBAAkB,CAAC;IAC9B,QAAQ,CAAC,EAAE,sBAAsB,CAAC;CACnC;AAED,sCAAsC;AACtC,MAAM,WAAW,uBAAuB;IACtC,QAAQ,EAAE,iBAAiB,CAAC;IAC5B,6CAA6C;IAC7C,QAAQ,EAAE,cAAc,CAAC;IACzB,oCAAoC;IACpC,MAAM,EAAE,QAAQ,CAAC;CAClB;AAED,sCAAsC;AACtC,MAAM,WAAW,wBAAwB;IACvC,QAAQ,EAAE,iBAAiB,CAAC;IAC5B,oCAAoC;IACpC,MAAM,EAAE,QAAQ,CAAC;CAClB;AAED,gDAAgD;AAChD,MAAM,MAAM,WAAW,GAAG,iBAAiB,GAAG,MAAM,CAAC;AAErD;;GAEG;AACH,qBAAa,wBAAwB;IACnC,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAoB;IACvC,OAAO,CAAC,SAAS,CAAC,CAA8B;IAChD,OAAO,CAAC,QAAQ,CAAC,CAAqB;IACtC,OAAO,CAAC,QAAQ,CAAC,CAAyB;gBAE9B,OAAO,EAAE,+BAA+B;IAOpD;;;;;OAKG;IACH,iBAAiB,CAAC,SAAS,EAAE,kBAAkB,GAAG,IAAI;IAMtD;;;;;;;OAOG;IACH,OAAO,CAAC,iBAAiB;IAczB;;;;;;;;OAQG;IACG,OAAO,CACX,GAAG,EAAE,WAAW,EAChB,SAAS,EAAE,kBAAkB,EAC7B,OAAO,GAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,kBAAkB,CAAC,EAAE,MAAM,CAAA;KAAO,GAC3D,OAAO,CAAC,uBAAuB,CAAC;IAwCnC;;;;;;OAMG;IACG,MAAM,CACV,GAAG,EAAE,WAAW,EAChB,SAAS,EAAE,kBAAkB,EAC7B,OAAO,GAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAA;KAAO,GAC9B,OAAO,CAAC,wBAAwB,CAAC;YAkBtB,WAAW;YAYX,WAAW;YAKX,YAAY;YAyBZ,uBAAuB;YAavB,kBAAkB;YAOlB,mBAAmB;YASnB,kBAAkB;CAMjC"}

package/dist/directive-principal.d.ts

@@ -0,0 +1,56 @@
+import { PermissionDefinition, PermissionResolver } from '@happyvertical/smrt-users';
+/** The permission slug that authorises activating a persona directive. */
+export declare const ACTIVATE_DIRECTIVE_PERMISSION = "personas.activate-directive";
+/** Catalog definition contributed for {@link ACTIVATE_DIRECTIVE_PERMISSION}. */
+export declare const DIRECTIVE_ACTIVATION_PERMISSION_DEF: PermissionDefinition;
+/**
+ * An actor whose authority is expressed as a set of held permission slugs.
+ *
+ * Deliberately minimal so the gate depends only on the permission model, not on
+ * any particular resolver or session machinery.
+ */
+export interface DirectivePrincipal {
+    /** Optional stable id (recorded as the reviewer on approve/reject). */
+    readonly id?: string;
+    /**
+     * The tenant this principal's authority was resolved for. Permissions are
+     * resolved per tenant (`PermissionResolver.resolvePermissions(userId, tenantId)`),
+     * so a principal authorised in one tenant must not activate another tenant's
+     * directive. When set, the approval service enforces
+     * `principal.tenantId === proposal.tenantId`. `undefined` skips the check
+     * (e.g. a system/global actor or a hand-built principal).
+     */
+    readonly tenantId?: string;
+    /** Whether this actor holds the given permission slug. */
+    can(slug: string): boolean;
+}
+/**
+ * Build a {@link DirectivePrincipal} from an explicit set of granted slugs.
+ */
+export declare function principalFromPermissions(permissions: Iterable<string>, options?: {
+    id?: string;
+    tenantId?: string;
+}): DirectivePrincipal;
+/**
+ * Build a {@link DirectivePrincipal} for a user in a tenant by resolving their
+ * effective permissions through the RBAC {@link PermissionResolver} — the
+ * production wiring that makes the gate concretely the permission system.
+ */
+export declare function resolveDirectivePrincipal(options: {
+    resolver: PermissionResolver;
+    userId: string;
+    tenantId: string;
+}): Promise<DirectivePrincipal>;
+/**
+ * Register the persona directive-activation permission into the runtime catalog.
+ *
+ * @returns An unregister function (primarily for tests).
+ */
+export declare function registerPersonaPermissions(): () => void;
+/**
+ * Register the persona permissions once per process. Called as a side effect
+ * from the package entry so the slug is present in the permission catalog for
+ * any consumer that imports `@happyvertical/smrt-personas`.
+ */
+export declare function ensurePersonaPermissionsRegistered(): void;
+//# sourceMappingURL=directive-principal.d.ts.map

package/dist/directive-principal.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"directive-principal.d.ts","sourceRoot":"","sources":["../src/directive-principal.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,EACL,KAAK,oBAAoB,EACzB,KAAK,kBAAkB,EAExB,MAAM,2BAA2B,CAAC;AAEnC,0EAA0E;AAC1E,eAAO,MAAM,6BAA6B,gCAAgC,CAAC;AAE3E,gFAAgF;AAChF,eAAO,MAAM,mCAAmC,EAAE,oBAMjD,CAAC;AAEF;;;;;GAKG;AACH,MAAM,WAAW,kBAAkB;IACjC,uEAAuE;IACvE,QAAQ,CAAC,EAAE,CAAC,EAAE,MAAM,CAAC;IACrB;;;;;;;OAOG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,0DAA0D;IAC1D,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC;CAC5B;AAED;;GAEG;AACH,wBAAgB,wBAAwB,CACtC,WAAW,EAAE,QAAQ,CAAC,MAAM,CAAC,EAC7B,OAAO,GAAE;IAAE,EAAE,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAO,GAC/C,kBAAkB,CAOpB;AAED;;;;GAIG;AACH,wBAAsB,yBAAyB,CAAC,OAAO,EAAE;IACvD,QAAQ,EAAE,kBAAkB,CAAC;IAC7B,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;CAClB,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAW9B;AAID;;;;GAIG;AACH,wBAAgB,0BAA0B,IAAI,MAAM,IAAI,CAEvD;AAED;;;;GAIG;AACH,wBAAgB,kCAAkC,IAAI,IAAI,CAMzD"}

package/dist/directive-proposal.d.ts

@@ -0,0 +1,103 @@
+import { SmrtCollection, SmrtObject } from '@happyvertical/smrt-core';
+/**
+ * Lifecycle status of a proposal:
+ *
+ * - `pending` — awaiting review; surfaced in the queue.
+ * - `approved` — a reviewer activated it; the override was written.
+ * - `rejected` — a reviewer declined it; recorded as a signal and never
+ *   re-surfaced (the runner dedups against it by fingerprint).
+ * - `superseded` — a newer proposal replaced it before review.
+ */
+export type DirectiveProposalStatus = 'pending' | 'approved' | 'rejected' | 'superseded';
+/**
+ * Structured evidence backing a proposal — the ids of the learning episodes and
+ * feedback signals the reflection consolidated. Pure references so the proposal
+ * stays auditable without duplicating payloads.
+ */
+export interface DirectiveEvidence {
+    /** `_smrt_contexts` row ids of the episodes considered. */
+    episodeIds?: string[];
+    /** {@link Feedback} row ids considered. */
+    feedbackIds?: string[];
+    /** Free-form supporting notes (e.g. counts, aggregate metrics). */
+    notes?: string[];
+    [key: string]: unknown;
+}
+/**
+ * A stable content fingerprint for `(personaId, promptKey, proposedInstructions)`.
+ *
+ * Used to dedup proposals so an already-reviewed rewrite — in particular a
+ * rejected one — is never re-surfaced. Pure FNV-1a so it needs no crypto import
+ * and stays identical across Node and browser bundles.
+ */
+export declare function computeDirectiveFingerprint(personaId: string, promptKey: string, proposedInstructions: string): string;
+/**
+ * A pending, human-reviewable proposed edit to a persona's instructions.
+ */
+export declare class DirectiveProposal extends SmrtObject {
+    /** Owning tenant (required — proposals always target a tenant's persona). */
+    tenantId: string;
+    /** The persona whose instructions this proposal would rewrite. */
+    personaId: string;
+    /** Canonical agent class the persona configures (denormalised for queries). */
+    agentClass: string;
+    /**
+     * The registered prompt key whose template the persona's instructions map to.
+     * Activation writes/updates the tenant-scoped override for this key.
+     */
+    promptKey: string;
+    /** The proposed replacement instructions (the new prompt template). */
+    proposedInstructions: string;
+    /** Snapshot of the instructions at proposal time (for a review diff). */
+    currentInstructions: string;
+    /** Model-authored explanation for the proposed change. */
+    rationale: string;
+    /** Structured evidence, stored as a JSON string (see {@link getEvidence}). */
+    evidence: string;
+    /** Lifecycle status. */
+    status: DirectiveProposalStatus;
+    /**
+     * Content fingerprint for dedup / not-re-surfacing. Set from
+     * {@link computeDirectiveFingerprint} at creation time.
+     */
+    fingerprint: string;
+    /** Aggregate confidence in the proposal, in `[0, 1]`. */
+    confidence: number;
+    /** Id of the principal (autonomous reflection actor) that proposed it. */
+    proposedBy: string;
+    /** The reviewer (user id) that approved/rejected it, once reviewed. */
+    reviewedBy: string | null;
+    /** When the proposal was reviewed. */
+    reviewedAt: Date | null;
+    /** Reviewer note attached on approve/reject. */
+    reviewNote: string | null;
+    /** The `prompt_override` id written on activation (`null` until approved). */
+    activatedOverrideId: string | null;
+    /** Parse {@link evidence}, tolerating malformed JSON. */
+    getEvidence(): DirectiveEvidence;
+    /** Replace {@link evidence}. */
+    setEvidence(value: DirectiveEvidence): void;
+    /** Whether the proposal is still awaiting review. */
+    isPending(): boolean;
+}
+/**
+ * Collection for {@link DirectiveProposal} rows — the review queue.
+ */
+export declare class DirectiveProposalCollection extends SmrtCollection<DirectiveProposal> {
+    static readonly _itemClass: typeof DirectiveProposal;
+    /**
+     * The review queue: pending proposals, oldest first. Optionally scoped to a
+     * persona.
+     */
+    pending(options?: {
+        personaId?: string;
+        limit?: number;
+    }): Promise<DirectiveProposal[]>;
+    /**
+     * Existing proposals for a persona carrying a given fingerprint, in any
+     * status — used to avoid re-surfacing an already-seen (e.g. rejected) rewrite.
+     */
+    findByFingerprint(personaId: string, fingerprint: string): Promise<DirectiveProposal[]>;
+}
+export default DirectiveProposal;
+//# sourceMappingURL=directive-proposal.d.ts.map

package/dist/directive-proposal.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"directive-proposal.d.ts","sourceRoot":"","sources":["../src/directive-proposal.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EAGL,cAAc,EACd,UAAU,EAEX,MAAM,0BAA0B,CAAC;AAGlC;;;;;;;;GAQG;AACH,MAAM,MAAM,uBAAuB,GAC/B,SAAS,GACT,UAAU,GACV,UAAU,GACV,YAAY,CAAC;AAEjB;;;;GAIG;AACH,MAAM,WAAW,iBAAiB;IAChC,2DAA2D;IAC3D,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;IACtB,2CAA2C;IAC3C,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;IACvB,mEAAmE;IACnE,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IACjB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED;;;;;;GAMG;AACH,wBAAgB,2BAA2B,CACzC,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,MAAM,EACjB,oBAAoB,EAAE,MAAM,GAC3B,MAAM,CASR;AAgBD;;GAEG;AACH,qBASa,iBAAkB,SAAQ,UAAU;IAC/C,6EAA6E;IAE7E,QAAQ,EAAE,MAAM,CAAM;IAEtB,kEAAkE;IAElE,SAAS,EAAE,MAAM,CAAM;IAEvB,+EAA+E;IAE/E,UAAU,EAAE,MAAM,CAAM;IAExB;;;OAGG;IAEH,SAAS,EAAE,MAAM,CAAM;IAEvB,uEAAuE;IAEvE,oBAAoB,EAAE,MAAM,CAAM;IAElC,yEAAyE;IAEzE,mBAAmB,EAAE,MAAM,CAAM;IAEjC,0DAA0D;IAE1D,SAAS,EAAE,MAAM,CAAM;IAEvB,8EAA8E;IAE9E,QAAQ,EAAE,MAAM,CAAQ;IAExB,wBAAwB;IAExB,MAAM,EAAE,uBAAuB,CAAa;IAE5C;;;OAGG;IAEH,WAAW,EAAE,MAAM,CAAM;IAEzB,yDAAyD;IACzD,UAAU,EAAE,MAAM,CAAO;IAEzB,0EAA0E;IAE1E,UAAU,EAAE,MAAM,CAAM;IAExB,uEAAuE;IAEvE,UAAU,EAAE,MAAM,GAAG,IAAI,CAAQ;IAEjC,sCAAsC;IAEtC,UAAU,EAAE,IAAI,GAAG,IAAI,CAAQ;IAE/B,gDAAgD;IAEhD,UAAU,EAAE,MAAM,GAAG,IAAI,CAAQ;IAEjC,8EAA8E;IAE9E,mBAAmB,EAAE,MAAM,GAAG,IAAI,CAAQ;IAE1C,yDAAyD;IACzD,WAAW,IAAI,iBAAiB;IAIhC,gCAAgC;IAChC,WAAW,CAAC,KAAK,EAAE,iBAAiB,GAAG,IAAI;IAI3C,qDAAqD;IACrD,SAAS,IAAI,OAAO;CAGrB;AAED;;GAEG;AACH,qBAAa,2BAA4B,SAAQ,cAAc,CAAC,iBAAiB,CAAC;IAChF,MAAM,CAAC,QAAQ,CAAC,UAAU,2BAAqB;IAE/C;;;OAGG;IACG,OAAO,CACX,OAAO,GAAE;QAAE,SAAS,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAO,GACnD,OAAO,CAAC,iBAAiB,EAAE,CAAC;IAY/B;;;OAGG;IACG,iBAAiB,CACrB,SAAS,EAAE,MAAM,EACjB,WAAW,EAAE,MAAM,GAClB,OAAO,CAAC,iBAAiB,EAAE,CAAC;CAGhC;AAED,eAAe,iBAAiB,CAAC"}