@happyvertical/smrt-chat 0.38.19 → 0.38.21

package/AGENTS.md

@@ -25,6 +25,14 @@ Facade: `sendMessage()` (authors as the actor with `role: 'user'`; room-membersh
 
 `allowedTools` is a JSON array controlled by the consuming app. Fail-closed: an empty/unparseable whitelist permits NO tools. The internal `sendAgentReply(service, params)` function enforces the whitelist before emitting any `tool`/`tool_call` message; a caller cannot supply a `senderProfileId`/`role` to post as the agent, and the function is not reachable from the package index.
 
+## Conversational Harness (L3, #1891)
+
+The "chat with your learning agent" surface — the real agentic runtime for `AgentSession` (the only shipping chat runtime before this was a single-shot completion). This is the new **acyclic `chat → personas` / `chat → agents` / `chat → users` edge**; keep it that way (personas/agents/users never depend back on chat).
+
+- **`runToolLoop(options)`** (`tool-loop.ts`) — a bounded `tool_call → observe → respond` loop. Tools are **manifest operations** of installed packages: `buildManifestToolCatalog({ allowedTools })` reads the `PermissionCatalogService` catalog and keeps only the `(collection, action)` entries named in the persona's allow-list (the **offer gate**; absent/empty ⇒ NO tools). The loop runs inside one `executeAsPrincipal` context, and `invokeManifestTool` executes each op **in-process ("side door")** against `run.context.database` (the RLS tx when Postgres RLS is on), after re-asserting the fail-closed allow-list (`run.assertToolAllowed`) AND the catalog permission (`run.assertOperation`) — the **execution gate**. Bounded by a max-steps ceiling (`DEFAULT_MAX_STEPS = 8`): on the ceiling it disables tools for one final completion so the turn always terminates with text.
+- **`runPersonaConversationTurn(options)`** (`persona-conversation.ts`) — binds a conversation to an `AgentPersona`/`ResolvedPersona`: runs as its principal (`runAsUserId`), offers only its `allowedTools`, speaks its instructions (`resolvePersonaInstructions`, layering approved learned directives), and injects its **recalled learning memory** (`personaLearningMemory`, isolated per `memoryScope`) into the system prompt. `bindPersonaToSession()` mirrors the persona's `allowedTools`/instructions onto the `AgentSession` so the chat authoring gate agrees with the loop's offer gate. Authors the reply (and each executed tool) via the internal `sendAgentReply` bridge.
+- **Chat feedback capture** (`chat-feedback.ts`) — `captureChatFeedback()` + `acceptAppliedChange`/`rejectAppliedChange`/`correctResponse`/`rateResponse`/`thumbsUp`/`thumbsDown` write a `Feedback` row (personas) carrying the conversation's **correlation-id**, and (by default) reinforce the persona's learning memory (`reinforceFromFeedback`). So an in-chat reject decays a strategy below the reuse floor and it stops being recalled; a correction supersedes its stored value.
+
 ## Gotchas
 
 - **sessionContext, not context**: `context` is reserved for slug scoping. Use `getSessionContext()`/`updateSessionContext()` for agent memory.

package/dist/chat-feedback.d.ts

@@ -0,0 +1,95 @@
+import { LearningMemoryRecord, LearningSemanticSearch, SmrtClassOptions } from '@happyvertical/smrt-core';
+import { Feedback, FeedbackSignalType } from '@happyvertical/smrt-personas';
+/** The minimal persona shape chat feedback needs to route the signal. */
+export interface ChatFeedbackPersona {
+    /** Persona id — required (a signal always judges a specific persona). */
+    id?: string | null;
+    /** Owning tenant. */
+    tenantId?: string | null;
+    /** Canonical agent class the persona configures (denormalised onto the row). */
+    agentClass?: string;
+    /** Learning memory partition key. */
+    memoryScope?: string;
+}
+/**
+ * Options for {@link captureChatFeedback}.
+ */
+export interface CaptureChatFeedbackOptions {
+    /** Database handle. */
+    db: SmrtClassOptions['db'];
+    /** The persona the signal judges. */
+    persona: ChatFeedbackPersona;
+    /** The kind of signal. */
+    signalType: FeedbackSignalType;
+    /** Correlation-id of the conversation turn this signal judges. */
+    correlationId: string;
+    /** What {@link correlationId} names. Default `'chat_message'`. */
+    correlationType?: string;
+    /** Learning episode scope the signal reinforces (matches recall/capture). */
+    scope: string;
+    /** Learning episode key the signal reinforces. */
+    key: string;
+    /** The user id that authored the signal (null for autonomous). */
+    actorId?: string | null;
+    /** Numeric rating for a `rating` signal. */
+    rating?: number | null;
+    /** Corrected value for a `correction` signal. */
+    correction?: string | null;
+    /** Freeform note. */
+    comment?: string | null;
+    /** Structured metadata persisted on the row. */
+    metadata?: Record<string, unknown>;
+    /** Apply the signal to memory immediately. Default `true`. */
+    reinforce?: boolean;
+    /** Optional embedding search wired into the reinforced memory. */
+    semanticSearch?: LearningSemanticSearch;
+    /** Neutral point of a `rating` scale (see `FeedbackOutcomeOptions`). Default 0. */
+    ratingNeutral?: number;
+}
+/** The outcome of capturing chat feedback. */
+export interface ChatFeedbackResult {
+    /** The persisted feedback row. */
+    feedback: Feedback;
+    /** The memory record the signal reinforced, or `null` when it carried none. */
+    reinforced: LearningMemoryRecord | null;
+}
+/**
+ * Capture one in-chat feedback signal as a {@link Feedback} row and (by default)
+ * reinforce the persona's learning memory from it.
+ *
+ * @throws when the persona has no id (a signal must name a persisted persona).
+ */
+export declare function captureChatFeedback(options: CaptureChatFeedbackOptions): Promise<ChatFeedbackResult>;
+/** Shared options for the signal-typed convenience wrappers. */
+export type ChatFeedbackBase = Omit<CaptureChatFeedbackOptions, 'signalType' | 'rating' | 'correction'>;
+/**
+ * Accept an applied change — reinforces the judged strategy as a success.
+ */
+export declare function acceptAppliedChange(options: ChatFeedbackBase): Promise<ChatFeedbackResult>;
+/**
+ * Reject an applied change — decays the judged strategy toward the failure floor
+ * so it stops being recalled.
+ */
+export declare function rejectAppliedChange(options: ChatFeedbackBase & {
+    comment?: string | null;
+}): Promise<ChatFeedbackResult>;
+/**
+ * Record an inline correction — decays the wrong strategy AND supersedes its
+ * stored value with the corrected one, so the next recall returns the fix.
+ */
+export declare function correctResponse(options: ChatFeedbackBase & {
+    correction: string;
+    comment?: string | null;
+}): Promise<ChatFeedbackResult>;
+/**
+ * Record a numeric rating for a response (scale is caller-defined; pass
+ * `ratingNeutral` for a mid-point).
+ */
+export declare function rateResponse(options: ChatFeedbackBase & {
+    rating: number;
+}): Promise<ChatFeedbackResult>;
+/** Thumbs-up — a `+1` rating (reinforces as a success against neutral 0). */
+export declare function thumbsUp(options: ChatFeedbackBase): Promise<ChatFeedbackResult>;
+/** Thumbs-down — a `-1` rating (decays as a failure against neutral 0). */
+export declare function thumbsDown(options: ChatFeedbackBase): Promise<ChatFeedbackResult>;
+//# sourceMappingURL=chat-feedback.d.ts.map

package/dist/chat-feedback.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chat-feedback.d.ts","sourceRoot":"","sources":["../src/chat-feedback.ts"],"names":[],"mappings":"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"}

package/dist/chunks/{ChatService-hKK-GI17.js → ChatService-BRsE5HmY.js}

@@ -1,6 +1,18 @@
 import { ObjectRegistry, SmrtCollection, SmrtObject, crossPackageRef, field, foreignKey, smrt } from "@happyvertical/smrt-core";
 import { TenantScoped, tenantId } from "@happyvertical/smrt-tenancy";
 import { createHash } from "node:crypto";
+//#region \0rolldown/runtime.js
+var __defProp$6 = Object.defineProperty;
+var __exportAll = (all, no_symbols) => {
+	let target = {};
+	for (var name in all) __defProp$6(target, name, {
+		get: all[name],
+		enumerable: true
+	});
+	if (!no_symbols) __defProp$6(target, Symbol.toStringTag, { value: "Module" });
+	return target;
+};
+//#endregion
 //#region src/models/AgentSession.ts
 var __defProp$5 = Object.defineProperty;
 var __getOwnPropDesc$5 = Object.getOwnPropertyDescriptor;
@@ -1059,6 +1071,10 @@ var ChatThreadCollection = class extends SmrtCollection {
 };
 //#endregion
 //#region src/services/ChatService.ts
+var ChatService_exports = /* @__PURE__ */ __exportAll({
+	ChatService: () => ChatService,
+	sendAgentReply: () => sendAgentReply
+});
 var RUN_AGENT_REPLY = /* @__PURE__ */ Symbol("smrt-chat.runAgentReply");
 var ChatService = class ChatService {
 	#rooms;
@@ -1737,6 +1753,6 @@ function sendAgentReply(service, params) {
 	return ChatService[RUN_AGENT_REPLY](service, params);
 }
 //#endregion
-export { ChatReaction as a, AgentSession as c, ChatRoom as i, sendAgentReply as n, ChatParticipant as o, ChatThread as r, ChatMessage as s, ChatService as t };
+export { ChatRoom as a, ChatMessage as c, ChatThread as i, AgentSession as l, ChatService_exports as n, ChatReaction as o, sendAgentReply as r, ChatParticipant as s, ChatService as t };
 
-//# sourceMappingURL=ChatService-hKK-GI17.js.map
+//# sourceMappingURL=ChatService-BRsE5HmY.js.map