@happyvertical/smrt-personas 0.38.19 → 0.38.21

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (39) hide show
  1. package/AGENTS.md +119 -7
  2. package/dist/__smrt-register__.d.ts +2 -0
  3. package/dist/__smrt-register__.d.ts.map +1 -0
  4. package/dist/agent-persona.d.ts +161 -0
  5. package/dist/agent-persona.d.ts.map +1 -0
  6. package/dist/directive-approval.d.ts +94 -0
  7. package/dist/directive-approval.d.ts.map +1 -0
  8. package/dist/directive-principal.d.ts +56 -0
  9. package/dist/directive-principal.d.ts.map +1 -0
  10. package/dist/directive-proposal.d.ts +103 -0
  11. package/dist/directive-proposal.d.ts.map +1 -0
  12. package/dist/feedback.d.ts +127 -0
  13. package/dist/feedback.d.ts.map +1 -0
  14. package/dist/index.d.ts +11 -294
  15. package/dist/index.d.ts.map +1 -0
  16. package/dist/index.js +829 -19
  17. package/dist/index.js.map +1 -1
  18. package/dist/manifest.json +919 -3
  19. package/dist/persona-instance.d.ts +249 -0
  20. package/dist/persona-instance.d.ts.map +1 -0
  21. package/dist/persona-memory.d.ts +45 -0
  22. package/dist/persona-memory.d.ts.map +1 -0
  23. package/dist/persona-prompt.d.ts +77 -0
  24. package/dist/persona-prompt.d.ts.map +1 -0
  25. package/dist/persona-resolver.d.ts +134 -0
  26. package/dist/persona-resolver.d.ts.map +1 -0
  27. package/dist/reflection-runner.d.ts +113 -0
  28. package/dist/reflection-runner.d.ts.map +1 -0
  29. package/dist/smrt-knowledge.json +519 -11
  30. package/dist/svelte/components/DirectiveReviewQueue.svelte +185 -0
  31. package/dist/svelte/components/DirectiveReviewQueue.svelte.d.ts +15 -0
  32. package/dist/svelte/components/DirectiveReviewQueue.svelte.d.ts.map +1 -0
  33. package/dist/svelte/index.d.ts +16 -0
  34. package/dist/svelte/index.d.ts.map +1 -0
  35. package/dist/svelte/index.js +13 -0
  36. package/dist/svelte/types.d.ts +46 -0
  37. package/dist/svelte/types.d.ts.map +1 -0
  38. package/dist/svelte/types.js +39 -0
  39. package/package.json +23 -7
@@ -0,0 +1,249 @@
1
+ import { AgentAdminRoute, AgentManifestInfo, AgentSchedule, AgentScheduleCollection, AgentUISlots } from '@happyvertical/smrt-agents';
2
+ import { AgentPersona, AgentPersonaCollection } from './agent-persona.js';
3
+ /**
4
+ * The reserved persona name for the singleton/default instance.
5
+ *
6
+ * Matches the `PersonaResolver` default-fallback name so the concept is
7
+ * consistent across the package. A persona with this name is the tenant's
8
+ * singleton identity: it maps to a `null` instance key (see
9
+ * {@link personaInstanceKey}), reusing the class-keyed dispatch subscriber and
10
+ * un-suffixed memory scope an un-upgraded agent already uses.
11
+ */
12
+ export declare const DEFAULT_PERSONA_NAME = "default";
13
+ /**
14
+ * The durable per-instance key for a persona, or `null` for the singleton.
15
+ *
16
+ * - The `default` persona → `null`: it *is* the singleton identity, so an agent
17
+ * run as it keeps the class-keyed dispatch subscriber and un-suffixed memory
18
+ * scope. This is why upgrading a singleton to a default persona changes no
19
+ * runtime identity (non-destructive).
20
+ * - Any other persona → its `id`: a distinct, stable instance key the framework
21
+ * folds into a per-instance subscriber/memory/interest scope.
22
+ *
23
+ * @throws Error if a non-default persona has no `id` (it must be saved first —
24
+ * an unsaved non-default persona would masquerade as the singleton).
25
+ */
26
+ export declare function personaInstanceKey(persona: Pick<AgentPersona, 'name' | 'id'>): string | null;
27
+ /**
28
+ * Whether a persona is the singleton/default instance.
29
+ */
30
+ export declare function isDefaultPersona(persona: Pick<AgentPersona, 'name'>): boolean;
31
+ /**
32
+ * The subset of `AgentOptions` a runtime spreads to construct an agent as this
33
+ * persona instance. Kept structural (no agents runtime import needed by the
34
+ * caller) — spread into `new AgentClass({ ...agentOptionsForPersona(p), db })`.
35
+ */
36
+ export interface PersonaAgentOptions {
37
+ /** Per-instance key — `null` for the default (singleton) persona. */
38
+ instanceKey: string | null;
39
+ /** The tenant the persona belongs to. */
40
+ tenantId: string;
41
+ }
42
+ /**
43
+ * Project a persona into the agent construction options that give the agent its
44
+ * per-instance identity.
45
+ */
46
+ export declare function agentOptionsForPersona(persona: AgentPersona): PersonaAgentOptions;
47
+ /**
48
+ * Options for {@link schedulePersonaInstance}.
49
+ */
50
+ export interface SchedulePersonaInstanceOptions {
51
+ /** Cron expression (5-field). */
52
+ cron: string;
53
+ /** Timezone label (default `'UTC'`). */
54
+ timezone?: string;
55
+ /** Agent method to invoke (default `'run'`). */
56
+ method?: string;
57
+ /** Config passed to the agent on each run. */
58
+ agentConfig?: Record<string, unknown>;
59
+ /** Arguments passed to the method. */
60
+ methodArgs?: Record<string, unknown>;
61
+ /** Whether the schedule starts enabled (default `true`). */
62
+ enabled?: boolean;
63
+ }
64
+ /**
65
+ * Create an `AgentSchedule` bound to a persona **instance**.
66
+ *
67
+ * The schedule's `agentType` is the persona's agent class. The persona instance
68
+ * key ({@link personaInstanceKey}) must reach the constructed agent as
69
+ * `AgentOptions.instanceKey`, so it is carried in `agentConfig` — which the
70
+ * scheduler (`smrt-jobs`) spreads into the agent constructor options — and
71
+ * `agentId` is left **null**.
72
+ *
73
+ * This is deliberate: the scheduler copies `AgentSchedule.agentId` to
74
+ * `SmrtJob.objectId`, and the `TaskRunner` `loadFromId()`s a non-null
75
+ * `objectId` against the agent's STI table. A persona id lives in
76
+ * `agent_personas`, not that table, so putting it in `agentId` would fail to
77
+ * load (or load the wrong row). Leaving `agentId` null makes the runner
78
+ * construct a fresh instance and pick up `instanceKey` from `agentConfig`. The
79
+ * default persona (null key) carries no key → runs the singleton.
80
+ *
81
+ * @param schedules - The `AgentScheduleCollection` to create into.
82
+ * @param persona - The persona instance to schedule (must be saved).
83
+ * @param options - Cron and run settings.
84
+ */
85
+ export declare function schedulePersonaInstance(schedules: AgentScheduleCollection, persona: AgentPersona, options: SchedulePersonaInstanceOptions): Promise<AgentSchedule>;
86
+ /**
87
+ * One instance's row in the instance-aware admin surface.
88
+ *
89
+ * Carries the agent class's admin surface (`slots` / `adminRoutes`) rendered for
90
+ * THIS instance, plus the resolved per-instance dispatch subscriber so the admin
91
+ * can show how the instance is routed.
92
+ */
93
+ export interface PersonaInstanceView {
94
+ /** The persona id backing this instance. */
95
+ personaId: string;
96
+ /** Persona (instance) name. */
97
+ name: string;
98
+ /** Per-instance key — `null` for the default (singleton). */
99
+ instanceKey: string | null;
100
+ /** Whether this is the default (singleton) instance. */
101
+ isDefault: boolean;
102
+ /** Whether the instance is enabled. */
103
+ enabled: boolean;
104
+ /** Resolution priority. */
105
+ priority: number;
106
+ /** Context scoping (if any). */
107
+ contextType: string | null;
108
+ contextId: string | null;
109
+ /** The principal the instance runs as. */
110
+ runAsUserId: string;
111
+ /** Optional acting bot identity. */
112
+ actsAsProfileId: string | null;
113
+ /** The per-instance dispatch subscriber identity. */
114
+ dispatchSubscriber: string;
115
+ /** The agent class's UI slots, rendered for this instance. */
116
+ slots: AgentUISlots;
117
+ /** The agent class's admin routes, rendered for this instance. */
118
+ adminRoutes: AgentAdminRoute[];
119
+ }
120
+ /**
121
+ * The instance-aware admin surface for one `(tenant, agentClass)` pair.
122
+ */
123
+ export interface PersonaInstanceAdminView {
124
+ /** Canonical agent class the surface is for. */
125
+ agentClass: string;
126
+ /** Tenant the surface is for. */
127
+ tenantId: string;
128
+ /** One entry per configured instance (persona), priority-ordered. */
129
+ instances: PersonaInstanceView[];
130
+ /** Whether new instances may be added (always true for the persona model). */
131
+ canAddInstance: boolean;
132
+ }
133
+ /**
134
+ * Options for {@link buildPersonaInstanceAdmin}.
135
+ */
136
+ export interface BuildPersonaInstanceAdminOptions {
137
+ /** Tenant to render the surface for. */
138
+ tenantId: string;
139
+ /** Agent class (canonicalized internally). */
140
+ agentClass: string;
141
+ /**
142
+ * The agent class's manifest surface. Its `uiSlots` / `adminRoutes` are
143
+ * rendered once per instance. Optional — omit to render instances with empty
144
+ * panels (e.g. a class that declares none).
145
+ */
146
+ manifest?: Pick<AgentManifestInfo, 'uiSlots' | 'adminRoutes'>;
147
+ }
148
+ /**
149
+ * Build the instance-aware admin surface: one panel set per configured instance.
150
+ *
151
+ * Lists the tenant's persona instances for the class and renders the class's
152
+ * `uiSlots`/`adminRoutes` for each, so an admin sees N instances (not one class
153
+ * panel) with add/remove affordances. The default (singleton) instance appears
154
+ * with `instanceKey: null` and the class-keyed subscriber.
155
+ *
156
+ * @param personas - Persona collection to read instances from.
157
+ * @param options - Tenant, class, and the class manifest to render per instance.
158
+ */
159
+ export declare function buildPersonaInstanceAdmin(personas: AgentPersonaCollection, options: BuildPersonaInstanceAdminOptions): Promise<PersonaInstanceAdminView>;
160
+ /**
161
+ * Options for {@link addPersonaInstance}.
162
+ */
163
+ export interface AddPersonaInstanceOptions {
164
+ tenantId: string;
165
+ agentClass: string;
166
+ /** Instance name (unique per `(tenant, agentClass)`). */
167
+ name: string;
168
+ /** The principal the instance runs as (required by `AgentPersona`). */
169
+ runAsUserId: string;
170
+ instructions?: string;
171
+ allowedTools?: string[];
172
+ contextType?: string | null;
173
+ contextId?: string | null;
174
+ priority?: number;
175
+ memoryScope?: string;
176
+ actsAsProfileId?: string | null;
177
+ enabled?: boolean;
178
+ }
179
+ /**
180
+ * Add a new instance (persona) — the "add" admin affordance.
181
+ *
182
+ * Creates and saves an `AgentPersona`, canonicalizing the agent class so it
183
+ * lines up with `TenantAgent`. The `(tenant_id, agent_class, name)` unique
184
+ * constraint rejects a duplicate name.
185
+ */
186
+ export declare function addPersonaInstance(personas: AgentPersonaCollection, options: AddPersonaInstanceOptions): Promise<AgentPersona>;
187
+ /**
188
+ * Remove an instance (persona) by id — the "remove" admin affordance.
189
+ *
190
+ * Deletes only the named instance; other instances of the class are untouched.
191
+ * A no-op (returns `false`) when the persona does not exist.
192
+ *
193
+ * @returns `true` if a persona was removed, `false` if none matched the id.
194
+ */
195
+ export declare function removePersonaInstance(personas: AgentPersonaCollection, personaId: string): Promise<boolean>;
196
+ /**
197
+ * Options for {@link upgradeSingletonToDefaultPersona}.
198
+ */
199
+ export interface UpgradeSingletonOptions {
200
+ tenantId: string;
201
+ agentClass: string;
202
+ /** The principal the default persona runs as (required by `AgentPersona`). */
203
+ runAsUserId: string;
204
+ /** Instructions to seed the default persona with (from existing config). */
205
+ instructions?: string;
206
+ /** Tools to seed (from existing config). */
207
+ allowedTools?: string[];
208
+ /**
209
+ * Memory scope for the default persona. Leave empty (default) to let the
210
+ * resolver derive it — for the default (null-keyed) instance the derived
211
+ * scope equals the singleton's existing `agent/<type>` scope, so existing
212
+ * learned memory is preserved untouched.
213
+ */
214
+ memoryScope?: string;
215
+ actsAsProfileId?: string | null;
216
+ }
217
+ /**
218
+ * The result of a singleton→multi upgrade.
219
+ */
220
+ export interface UpgradeSingletonResult {
221
+ /** The default persona representing the existing singleton instance. */
222
+ persona: AgentPersona;
223
+ /** `true` if it was created now, `false` if a default persona already existed. */
224
+ created: boolean;
225
+ /**
226
+ * The instance key for the default persona — always `null`, i.e. it maps to
227
+ * the existing singleton runtime identity (same dispatch subscriber + memory
228
+ * scope), which is what makes the upgrade non-destructive.
229
+ */
230
+ instanceKey: null;
231
+ }
232
+ /**
233
+ * Non-destructively upgrade a singleton agent to the multi-instance model by
234
+ * mapping the existing instance to a single `default` persona.
235
+ *
236
+ * The default persona is null-keyed, so it *reuses the singleton's exact runtime
237
+ * identity* — the class-keyed dispatch subscriber and the un-suffixed
238
+ * `agent/<type>` memory scope. Nothing about the running agent, its config, its
239
+ * dispatch subscriptions, or its learned memory changes; a persona row is simply
240
+ * added so further instances can now be created alongside it.
241
+ *
242
+ * Idempotent: if a `default` persona already exists for the pair it is returned
243
+ * with `created: false` and nothing is duplicated.
244
+ *
245
+ * @param personas - Persona collection to read/create into.
246
+ * @param options - Tenant, class, and the principal + config to seed.
247
+ */
248
+ export declare function upgradeSingletonToDefaultPersona(personas: AgentPersonaCollection, options: UpgradeSingletonOptions): Promise<UpgradeSingletonResult>;
249
+ //# sourceMappingURL=persona-instance.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"persona-instance.d.ts","sourceRoot":"","sources":["../src/persona-instance.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,45 @@
1
+ import { LearningMemory, LearningMemoryConfig, LearningMemoryRecord, LearningSemanticSearch } from '@happyvertical/smrt-core';
2
+ import { DatabaseInterface } from '@happyvertical/sql';
3
+ import { Feedback, FeedbackOutcomeOptions } from './feedback.js';
4
+ /** The minimal persona shape the memory router needs. */
5
+ export interface PersonaMemoryLike {
6
+ id?: string | null;
7
+ memoryScope?: string;
8
+ agentClass?: string;
9
+ tenantId?: string | null;
10
+ }
11
+ /**
12
+ * The effective memory partition key for a persona: its explicit `memoryScope`,
13
+ * or a stable `persona:<id>` fallback when none is set.
14
+ *
15
+ * @throws if neither a `memoryScope` nor an id is available.
16
+ */
17
+ export declare function personaMemoryScope(persona: PersonaMemoryLike): string;
18
+ /**
19
+ * Build a {@link LearningMemory} partitioned to a persona's memory scope.
20
+ *
21
+ * The persona's `memoryScope` is used as the memory `owner_id`, so recall and
22
+ * capture are isolated per persona. `owner_class` defaults to the persona's
23
+ * agent class (falling back to `'AgentPersona'`).
24
+ */
25
+ export declare function personaLearningMemory(options: {
26
+ db: DatabaseInterface;
27
+ persona: PersonaMemoryLike;
28
+ ownerClass?: string;
29
+ tenantId?: string | null;
30
+ semanticSearch?: LearningSemanticSearch;
31
+ config?: Partial<LearningMemoryConfig>;
32
+ }): LearningMemory;
33
+ /**
34
+ * Apply a single {@link Feedback} signal to a persona's memory as
35
+ * confidence-only reinforcement.
36
+ *
37
+ * Maps the signal onto a `LearningOutcome` and captures it against the episode
38
+ * the signal names (`feedback.scope` / `feedback.key`). A `correction` signal
39
+ * additionally supersedes the stored strategy with the corrected value.
40
+ *
41
+ * @returns The updated/seeded memory record, or `null` when the signal carries
42
+ * no reinforcement value (or there was nothing to reinforce).
43
+ */
44
+ export declare function reinforceFromFeedback(memory: LearningMemory, feedback: Feedback, options?: FeedbackOutcomeOptions): Promise<LearningMemoryRecord | null>;
45
+ //# sourceMappingURL=persona-memory.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"persona-memory.d.ts","sourceRoot":"","sources":["../src/persona-memory.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EACL,cAAc,EACd,KAAK,oBAAoB,EACzB,KAAK,oBAAoB,EACzB,KAAK,sBAAsB,EAC5B,MAAM,0BAA0B,CAAC;AAClC,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AAC5D,OAAO,KAAK,EAAE,QAAQ,EAAE,sBAAsB,EAAE,MAAM,eAAe,CAAC;AAEtE,yDAAyD;AACzD,MAAM,WAAW,iBAAiB;IAChC,EAAE,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACnB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC1B;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,iBAAiB,GAAG,MAAM,CAWrE;AAED;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE;IAC7C,EAAE,EAAE,iBAAiB,CAAC;IACtB,OAAO,EAAE,iBAAiB,CAAC;IAC3B,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,cAAc,CAAC,EAAE,sBAAsB,CAAC;IACxC,MAAM,CAAC,EAAE,OAAO,CAAC,oBAAoB,CAAC,CAAC;CACxC,GAAG,cAAc,CAYjB;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,qBAAqB,CACzC,MAAM,EAAE,cAAc,EACtB,QAAQ,EAAE,QAAQ,EAClB,OAAO,GAAE,sBAA2B,GACnC,OAAO,CAAC,oBAAoB,GAAG,IAAI,CAAC,CActC"}
@@ -0,0 +1,77 @@
1
+ import { PromptDefinition, PromptEditableConfig, PromptOverride } from '@happyvertical/smrt-prompts';
2
+ import { DatabaseInterface } from '@happyvertical/sql';
3
+ /** The minimal persona shape these helpers need. */
4
+ export interface PersonaLike {
5
+ id?: string | null;
6
+ tenantId?: string | null;
7
+ instructions?: string;
8
+ }
9
+ /**
10
+ * The registered prompt key a persona's instructions map to.
11
+ *
12
+ * @throws if the persona has no id (an unsaved persona has no stable key).
13
+ */
14
+ export declare function personaInstructionsPromptKey(persona: PersonaLike): string;
15
+ /**
16
+ * Idempotently register the per-persona instructions prompt.
17
+ *
18
+ * The base template is always the empty string and the editability is fixed, so
19
+ * repeated calls register an identical definition (the registry is idempotent
20
+ * for matching definitions). The persona's real instructions are supplied by
21
+ * the override layer, never by the base template — that keeps re-registration
22
+ * stable even as instructions change.
23
+ *
24
+ * Pass `editable` to model a prompt whose template is locked; activation of a
25
+ * proposal against such a key is then rejected by `validatePromptOverride`.
26
+ */
27
+ export declare function ensurePersonaInstructionsPrompt(persona: PersonaLike, options?: {
28
+ editable?: Partial<PromptEditableConfig>;
29
+ }): PromptDefinition;
30
+ /**
31
+ * Upsert a scoped `prompt_override` template for a registered prompt key.
32
+ *
33
+ * Loads the existing app/tenant override (by `tenantId`), updates its template,
34
+ * or creates a new one. Always flows through `PromptOverride.save()`, so
35
+ * `validatePromptOverride` still forbids overriding a non-editable template.
36
+ *
37
+ * The prompt key must already be registered (via
38
+ * {@link ensurePersonaInstructionsPrompt} or `definePrompt`); this helper does
39
+ * not register it, so it never silently relaxes a locked prompt's editability.
40
+ *
41
+ * @returns The persisted override.
42
+ */
43
+ export declare function upsertPromptTemplateOverride(options: {
44
+ db: DatabaseInterface;
45
+ key: string;
46
+ tenantId: string | null;
47
+ template: string;
48
+ }): Promise<PromptOverride>;
49
+ /**
50
+ * Write (or update) the tenant-scoped `prompt_override` that carries a persona's
51
+ * instructions.
52
+ *
53
+ * Ensures the per-persona prompt key is registered, then upserts the override
54
+ * template to `instructions ?? persona.instructions`. Flows through
55
+ * `PromptOverride.save()`, so a non-editable template throws.
56
+ *
57
+ * @returns The persisted override.
58
+ */
59
+ export declare function applyPersonaInstructions(options: {
60
+ persona: PersonaLike;
61
+ db: DatabaseInterface;
62
+ instructions?: string;
63
+ editable?: Partial<PromptEditableConfig>;
64
+ }): Promise<PromptOverride>;
65
+ /**
66
+ * Resolve a persona's effective instructions through the prompt system —
67
+ * layering code default → config → app override → tenant (persona) override.
68
+ *
69
+ * @returns The rendered instructions text (empty string when nothing overrides
70
+ * the neutral base template).
71
+ */
72
+ export declare function resolvePersonaInstructions(options: {
73
+ persona: PersonaLike;
74
+ db: DatabaseInterface;
75
+ variables?: Record<string, unknown>;
76
+ }): Promise<string>;
77
+ //# sourceMappingURL=persona-prompt.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"persona-prompt.d.ts","sourceRoot":"","sources":["../src/persona-prompt.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,EAEL,KAAK,gBAAgB,EACrB,KAAK,oBAAoB,EACzB,KAAK,cAAc,EAIpB,MAAM,6BAA6B,CAAC;AACrC,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AAE5D,oDAAoD;AACpD,MAAM,WAAW,WAAW;IAC1B,EAAE,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED;;;;GAIG;AACH,wBAAgB,4BAA4B,CAAC,OAAO,EAAE,WAAW,GAAG,MAAM,CAQzE;AAUD;;;;;;;;;;;GAWG;AACH,wBAAgB,+BAA+B,CAC7C,OAAO,EAAE,WAAW,EACpB,OAAO,GAAE;IAAE,QAAQ,CAAC,EAAE,OAAO,CAAC,oBAAoB,CAAC,CAAA;CAAO,GACzD,gBAAgB,CAelB;AAED;;;;;;;;;;;;GAYG;AACH,wBAAsB,4BAA4B,CAAC,OAAO,EAAE;IAC1D,EAAE,EAAE,iBAAiB,CAAC;IACtB,GAAG,EAAE,MAAM,CAAC;IACZ,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,QAAQ,EAAE,MAAM,CAAC;CAClB,GAAG,OAAO,CAAC,cAAc,CAAC,CAe1B;AAED;;;;;;;;;GASG;AACH,wBAAsB,wBAAwB,CAAC,OAAO,EAAE;IACtD,OAAO,EAAE,WAAW,CAAC;IACrB,EAAE,EAAE,iBAAiB,CAAC;IACtB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,EAAE,OAAO,CAAC,oBAAoB,CAAC,CAAC;CAC1C,GAAG,OAAO,CAAC,cAAc,CAAC,CAS1B;AAED;;;;;;GAMG;AACH,wBAAsB,0BAA0B,CAAC,OAAO,EAAE;IACxD,OAAO,EAAE,WAAW,CAAC;IACrB,EAAE,EAAE,iBAAiB,CAAC;IACtB,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACrC,GAAG,OAAO,CAAC,MAAM,CAAC,CAUlB"}
@@ -0,0 +1,134 @@
1
+ import { ResolvedAgentAvailability } from '@happyvertical/smrt-agents';
2
+ import { AgentPersonaCollection, personaAppliesToContext } from './agent-persona.js';
3
+ /**
4
+ * The context a persona is being resolved for.
5
+ */
6
+ export interface PersonaContext {
7
+ /** Context dimension type (e.g. `'site'`). */
8
+ contextType?: string | null;
9
+ /** Context dimension id within `contextType`. */
10
+ contextId?: string | null;
11
+ }
12
+ /**
13
+ * Bottom-layer defaults for an agent class, typically derived from its build
14
+ * manifest.
15
+ */
16
+ export interface ManifestPersonaDefaults {
17
+ /** Default system instructions when no persona overrides them. */
18
+ instructions?: string;
19
+ /** Default tool identifiers, capped by the availability ceiling. */
20
+ allowedTools?: string[];
21
+ /** Default memory scope. */
22
+ memoryScope?: string;
23
+ }
24
+ /**
25
+ * Middle-layer availability + capability ceiling, projected from a
26
+ * `TenantAgent` resolution.
27
+ */
28
+ export interface PersonaAvailabilityGate {
29
+ /** Resolved `TenantAgent` status. `'disabled'` marks the persona unavailable. */
30
+ status: 'active' | 'disabled';
31
+ /**
32
+ * Tool identifiers the tenant is permitted to grant. When set, resolved
33
+ * `allowedTools` are intersected with this ceiling. `undefined` means no
34
+ * ceiling (tools pass through unchanged).
35
+ */
36
+ toolCeiling?: string[];
37
+ /** Tenant the binding was resolved from (provenance only). */
38
+ sourceTenantId?: string;
39
+ }
40
+ /**
41
+ * Options for {@link PersonaResolver.resolve}.
42
+ */
43
+ export interface ResolvePersonaOptions {
44
+ /**
45
+ * Return ancestor tenant ids for a tenant, nearest parent first through to
46
+ * the root — mirrors `TenantAgentCollection.resolveForTenant`. Omit for a
47
+ * single-tenant resolution with no inheritance.
48
+ */
49
+ getAncestorIds?: (tenantId: string) => Promise<string[]>;
50
+ /** Bottom-layer manifest defaults for the agent class. */
51
+ manifestDefaults?: ManifestPersonaDefaults;
52
+ /**
53
+ * Middle-layer `TenantAgent` availability + ceiling. Omit to skip gating
54
+ * (the result is always `available: true` with no tool ceiling).
55
+ */
56
+ availability?: PersonaAvailabilityGate | null;
57
+ }
58
+ /**
59
+ * A fully resolved persona: the layered, ready-to-use configuration plus
60
+ * provenance describing how it was resolved.
61
+ */
62
+ export interface ResolvedPersona {
63
+ /** Canonical qualified agent type the resolution was for. */
64
+ agentClass: string;
65
+ /** Tenant the resolution was requested for. */
66
+ tenantId: string;
67
+ /** Id of the selected persona, or `undefined` for the default fallback. */
68
+ personaId?: string;
69
+ /** Selected persona name, or `'default'` for the fallback. */
70
+ name: string;
71
+ /** Layered instructions (persona → manifest default). */
72
+ instructions: string;
73
+ /** Layered tool ids (persona/manifest tools, capped by the ceiling). */
74
+ allowedTools: string[];
75
+ /** Run-as user principal, if the selected persona sets one. */
76
+ runAsUserId?: string;
77
+ /** Acting `Bot` profile id, if the selected persona sets one. */
78
+ actsAsProfileId?: string | null;
79
+ /** Resolved memory scope (persona → manifest default → derived default). */
80
+ memoryScope: string;
81
+ /** Selected persona priority (`0` for the default fallback). */
82
+ priority: number;
83
+ /** Context type the resolution was requested for. */
84
+ contextType?: string | null;
85
+ /** Context id the resolution was requested for. */
86
+ contextId?: string | null;
87
+ /** Whether a persona matched (`'persona'`) or the default was used (`'default'`). */
88
+ source: 'persona' | 'default';
89
+ /** For a matched persona, whether it was the tenant's own or inherited. */
90
+ personaSource?: 'explicit' | 'inherited';
91
+ /** Tenant the matched persona came from (own tenant or an ancestor). */
92
+ sourceTenantId?: string;
93
+ /** Whether the `TenantAgent` gate reports the agent as available. */
94
+ available: boolean;
95
+ }
96
+ /**
97
+ * Project a `TenantAgent` resolution into a {@link PersonaAvailabilityGate}.
98
+ *
99
+ * This is the concrete bridge between the `@happyvertical/smrt-agents`
100
+ * availability layer and the persona layer. Pass `toolPermissionPrefix` to
101
+ * derive a tool ceiling from granted permission ids (permissions whose id
102
+ * starts with the prefix become the ceiling, with the prefix stripped); omit it
103
+ * to leave the ceiling open.
104
+ *
105
+ * @param resolved - A `ResolvedAgentAvailability` (or `null`/`undefined`).
106
+ * @param options.toolPermissionPrefix - Permission-id prefix that marks
107
+ * tool grants (e.g. `'tool:'`).
108
+ * @returns A gate, or `null` when `resolved` is nullish.
109
+ */
110
+ export declare function availabilityFromResolvedAgent(resolved: ResolvedAgentAvailability | null | undefined, options?: {
111
+ toolPermissionPrefix?: string;
112
+ }): PersonaAvailabilityGate | null;
113
+ /**
114
+ * Resolves the active persona for a `(tenant, agentClass, context)` request.
115
+ */
116
+ export declare class PersonaResolver {
117
+ private readonly personas;
118
+ constructor(personas: AgentPersonaCollection);
119
+ /**
120
+ * Resolve the active persona.
121
+ *
122
+ * @param tenantId - Requesting tenant.
123
+ * @param agentClass - Agent class (canonicalized internally).
124
+ * @param context - Context dimension being resolved for.
125
+ * @param options - Hierarchy walk, manifest defaults, and availability gate.
126
+ * @returns The layered {@link ResolvedPersona} — either a matched persona or
127
+ * the defined default fallback.
128
+ */
129
+ resolve(tenantId: string, agentClass: string, context?: PersonaContext, options?: ResolvePersonaOptions): Promise<ResolvedPersona>;
130
+ private layerPersona;
131
+ private defaultResolution;
132
+ }
133
+ export { personaAppliesToContext };
134
+ //# sourceMappingURL=persona-resolver.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"persona-resolver.d.ts","sourceRoot":"","sources":["../src/persona-resolver.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,113 @@
1
+ import { LearningMemory, LearningMemoryRecord } from '@happyvertical/smrt-core';
2
+ import { DatabaseInterface } from '@happyvertical/sql';
3
+ import { DirectivePrincipal } from './directive-principal.js';
4
+ import { DirectiveProposal, DirectiveProposalCollection } from './directive-proposal.js';
5
+ import { Feedback, FeedbackCollection } from './feedback.js';
6
+ /** The (normalised) persona shape handed to the reflector. */
7
+ export interface ReflectionPersona {
8
+ id: string;
9
+ tenantId: string;
10
+ agentClass?: string;
11
+ name?: string;
12
+ instructions?: string;
13
+ memoryScope?: string;
14
+ }
15
+ /**
16
+ * The persona a run consolidates over — accepts a persisted `AgentPersona`
17
+ * directly (its `id` / `tenantId` are validated at run time).
18
+ */
19
+ export interface ReflectionPersonaInput {
20
+ id?: string | null;
21
+ tenantId?: string | null;
22
+ agentClass?: string;
23
+ name?: string;
24
+ instructions?: string;
25
+ memoryScope?: string;
26
+ }
27
+ /** The consolidated input handed to the reflector (the AI boundary). */
28
+ export interface ReflectionInput {
29
+ persona: ReflectionPersona;
30
+ /** The persona's current effective instructions (resolved via prompts). */
31
+ currentInstructions: string;
32
+ /** Recent episodes for the persona's memory scope. */
33
+ episodes: LearningMemoryRecord[];
34
+ /** Recent feedback signals for the persona. */
35
+ feedback: Feedback[];
36
+ }
37
+ /** A candidate rewrite returned by the reflector. */
38
+ export interface DirectiveDraft {
39
+ /** Proposed replacement instructions. */
40
+ instructions: string;
41
+ /** Model-authored explanation. */
42
+ rationale: string;
43
+ /** Optional aggregate confidence in `[0, 1]`. */
44
+ confidence?: number;
45
+ }
46
+ /**
47
+ * The reflection boundary: consolidate episodes + feedback into a proposed
48
+ * instruction rewrite, or `null` to propose nothing. Injected so the AI call is
49
+ * the only thing mocked in tests.
50
+ */
51
+ export type DirectiveReflector = (input: ReflectionInput) => Promise<DirectiveDraft | null> | DirectiveDraft | null;
52
+ /** Options for {@link ReflectionRunner}. */
53
+ export interface ReflectionRunnerOptions {
54
+ db: DatabaseInterface;
55
+ /** The autonomous principal — must NOT hold `personas.activate-directive`. */
56
+ principal: DirectivePrincipal;
57
+ /** The reflection boundary (AI call), injected. */
58
+ reflect: DirectiveReflector;
59
+ proposals?: DirectiveProposalCollection;
60
+ feedback?: FeedbackCollection;
61
+ /** Clock, injectable for deterministic lookback in tests. */
62
+ now?: () => Date;
63
+ }
64
+ /** Options for a single {@link ReflectionRunner.run} pass over one persona. */
65
+ export interface ReflectionRunOptions {
66
+ persona: ReflectionPersonaInput;
67
+ /** The persona-scoped learning memory (see `personaLearningMemory`). */
68
+ memory: LearningMemory;
69
+ /** Episode scope to recall for evidence. Omit to skip episode gathering. */
70
+ episodeScope?: string;
71
+ /** Only consider feedback newer than this many ms ago. */
72
+ lookbackMs?: number;
73
+ /** Cap on feedback rows considered. Default 50. */
74
+ feedbackLimit?: number;
75
+ /** Neutral point for `rating` signals during reinforcement. Default 0. */
76
+ ratingNeutral?: number;
77
+ /** Override the target prompt key (default the persona instructions key). */
78
+ promptKey?: string;
79
+ }
80
+ /** Result of a {@link ReflectionRunner.run} pass. */
81
+ export interface ReflectionRunResult {
82
+ /** Newly created pending proposals (0 or 1). */
83
+ proposals: DirectiveProposal[];
84
+ /** Number of feedback signals that adjusted memory reinforcement. */
85
+ reinforced: number;
86
+ /** Number of candidate rewrites suppressed (deduped / no-op). */
87
+ skipped: number;
88
+ }
89
+ /**
90
+ * Consolidates feedback + episodes into pending directive proposals under a
91
+ * principal that cannot activate them.
92
+ */
93
+ export declare class ReflectionRunner {
94
+ private readonly db;
95
+ private readonly reflect;
96
+ private readonly now;
97
+ private readonly _principal;
98
+ private proposalsCol?;
99
+ private feedbackCol?;
100
+ constructor(options: ReflectionRunnerOptions);
101
+ /**
102
+ * The autonomous principal this runner acts as. Exposed so callers can prove
103
+ * it cannot activate a proposal (it lacks `personas.activate-directive`).
104
+ */
105
+ get principal(): DirectivePrincipal;
106
+ /**
107
+ * Run one reflection pass for a persona.
108
+ */
109
+ run(options: ReflectionRunOptions): Promise<ReflectionRunResult>;
110
+ private proposalsCollection;
111
+ private feedbackCollection;
112
+ }
113
+ //# sourceMappingURL=reflection-runner.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"reflection-runner.d.ts","sourceRoot":"","sources":["../src/reflection-runner.ts"],"names":[],"mappings":"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"}