@teamscala/service-boot 0.23.523 → 0.23.525

package/src/resource-chat-inject.ts

@@ -1,374 +0,0 @@
-/**
- * @system service-boot
- * @status handwritten
- * @edit edit directly
- *
- * Injects the generic ResourceChatLauncher block into an AUTHORISED resource
- * page (proposal, agreement, or any gated document) — called from a gate's
- * onAuthorized, so the floating GPT bubble lives strictly behind the email gate
- * and every resource of that type gets it with no per-page Puck edit. It builds
- * the resource's page content into a runtime-context string and passes it to the
- * launcher, which forwards it to the chat as <runtime_context> — so ONE shared
- * assistant agent answers about whichever resource is being viewed.
- *
- * RESOURCE-AGNOSTIC by design (one-ai-chat-system / chat-ui-is-one-canonical-block):
- * the launcher, the chat engine, and this injector are generic; only the
- * per-resource CONFIG differs (which agent, the copy, which resolved key holds
- * the record). The agent id is config, not code (registries-are-source-of-truth):
- * each resource type names a `config / <slug>-assistant-agent` row carrying
- * { agentId }. No row (or no agent) → no injection, page renders unchanged
- * (fail-soft).
- */
-
-/**
- * THE ASSISTANT'S WORDS BELONG TO THE AGENT ROW, NOT TO THIS FILE.
- *
- * `ai_agents` already carries a column for every one of them -- name,
- * welcome_message, conversation_starters, primary_color -- and on 2026-08-19
- * both live agents had welcome_message NULL and conversation_starters empty
- * while the copy sat spelled in TypeScript here and in proposal-chat-inject.
- * The intended home existed, sat blank, and the hardcoded copy won, so nobody
- * could change a word the assistant says without a code change and a deploy.
- * Two copies of one fact with the stale one winning silently is exactly
- * `information-exists-in-one-location`.
- *
- * `launchLabel` and `placeholder` remain caller arguments only because no
- * column holds them yet.
- */
-
-/**
- * The rendered content tree to append the launcher to.
- *
- * WHICH KEYS EXIST IS A ROW FACT, SO IT IS NOT SPELLED HERE. A page's resolved
- * sources and its region slots are declared on the `resource_loader` row, and
- * the caller has already read that row — so it passes `regionSlots` in. An
- * earlier draft of this function named "page", "body", "header" and "footer" as
- * literals, which is a loader row copied into TypeScript, free to drift from it
- * the moment a loader is edited (`identity-is-imported-never-spelled`).
- *
- * A FLAT PAGE KEEPS ITS CONTENT UNDER `page`; A REGION-SLOT PAGE DOES NOT.
- * Proposals and agreements resolve one `page` source, so the original injector
- * read `resolved.page.puck_data.content` and returned early when it was absent.
- * A generated report resolves region slots instead, so that early return fired
- * and the assistant was silently missing — the same failure shape as the dead
- * block name, since fail-soft injection logs nothing and the page looks fine.
- *
- * ANY RENDERED REGION WILL DO, SO THE FIRST DECLARED ONE IS TAKEN. The launcher
- * renders `position: fixed` at `zIndex: 50`, anchored to the viewport and not
- * to its container, so it appears identically whichever region carries it. That
- * is what makes "first declared region holding a content tree" a derivation
- * rather than a guess dressed up as one: there is no better region to prefer.
- *
- * `PAGE_SOURCE_KEY` is the platform's existing name for a flat page's body
- * source — the same convention `decideContentPageFloor` already keys on in the
- * caller. One shared convention, not a per-resource list.
- */
-
-/**
- * Serialise EVERYTHING THIS VIEWER MAY SEE as text for the assistant.
- *
- * BOTH THE RESULT AND THE RENDERED DOCUMENT, BECAUSE NEITHER IS SUFFICIENT.
- * The original serialiser sent the resource record plus the page's content
- * tree, which is exactly right for a proposal — the proposal's substance IS in
- * its blocks. It is wrong for anything the platform GENERATES a document from.
- * A report's body page is a shared template (one `builda_pages` row serves
- * every respondent) so the content tree holds headings and layout and not one
- * personal fact, while the substance — the answers, the category scores, the
- * computed narrative and bands — sits in sibling resolved keys the serialiser
- * never looked at. Sending only the page would give the assistant a form with
- * no answers; sending only the record would leave it unable to discuss what the
- * reader is actually looking at. An assessment result GENERATES a report, so
- * the assistant needs both halves of that.
- *
- * NO KEY IS NAMED, INCLUDED OR EXCLUDED. The loader row decides what a page
- * resolves; this walks whatever that produced. A draft carried a `CHROME_KEYS`
- * exclusion list dropping brand, website, header and footer — every one of them
- * a loader source key, which is to say database facts hardcoded here to save a
- * few hundred tokens of colours and navigation markup. Not a trade worth a
- * literal that goes stale in silence. A loader resolving a new source reaches
- * the assistant with no edit here (`offered-is-derived`).
- *
- * IT CANNOT OUTRUN THE GATE, BY CONSTRUCTION. This runs AFTER every content
- * gate, and a gate withholds by REMOVING content from this same graph. So
- * "everything in the graph" and "everything this viewer may see" are the same
- * set, and they cannot drift — which is what makes serialising the whole graph
- * safe rather than reckless.
- */
-
-import { getAppLogger } from "@teamscala/logger/app-loggers";
-import { loadRegistryConfig } from "@teamscala/db/registry/load-config";
-import { getServerClient } from "./page-server-orpc/server-client.ts";
-import * as v from "valibot";
-import type { BlockSchemaKey } from "@teamscala/db/registry/generated/block-schema";
-import type { ConfigKey } from "@teamscala/db/registry/generated/config";
-
-const AgentConfigSchema = v.object({ agentId: v.string() });
-
-// THE PUSHED BLOCK NAME IS AN IMPORTED IDENTITY, NEVER A SPELLED STRING.
-// discover-blocks keys the Puck registry off block_schema.slug alone
-// (`components[row.slug] = …`), so a type that is not a live slug resolves to
-// nothing — and because injection is fail-soft, the page renders unchanged with
-// no error. That is exactly how the bubble went missing from every gated
-// proposal and agreement: the block was consolidated to ResourceLauncher and
-// these injectors kept pushing their pre-consolidation names. BlockSchemaKey is
-// the generated union of live slugs, so annotating it here makes a stale name a
-// COMPILE error instead of a silent absence (identity-is-imported-never-spelled).
-const LAUNCHER_BLOCK: BlockSchemaKey = "ResourceLauncher";
-
-/** Per-resource-type injection config — the only thing that varies. */
-export interface ResourceChatOptions {
-	/** Key in `resolved` holding the record (e.g. "proposal", "agreement"). */
-	resourceKey: string;
-	/** `config` row slug carrying { agentId } (e.g. "agreement-assistant-agent"). */
-	agentConfigSlug: ConfigKey;
-	/** Org id to scope the chat. If omitted, read from resolved[resourceKey].organisation_id
-	 *  (proposals); agreements pass it explicitly (org isn't on the resolved record). */
-	organisationId?: string;
-	/** Floating button label / speech bubble (e.g. "Ask about this agreement"). */
-	launchLabel: string;
-	/** Input placeholder. */
-	placeholder?: string;
-	/**
-	 * The loader row's `region_slots`, when this page has them — passed in rather
-	 * than guessed, so which keys hold rendered content stays a database fact.
-	 * Absent means a flat page whose content is under the `page` source.
-	 */
-	regionSlots?: readonly string[];
-}
-
-export interface AgentPresentation {
-	title?: string;
-	welcomeMessage?: string;
-	conversationStarters?: string[];
-	primaryColor?: string;
-}
-
-export async function loadAgentPresentation(agentId: string): Promise<AgentPresentation> {
-	// THROUGH ORPC, NEVER PRISMA DIRECTLY (`no-direct-prisma-outside-orpc`).
-	// This is the same service-scoped client the ProductTiers read above uses;
-	// `ai_agents` is already in the declared models of both services that mount
-	// a launcher, so no schema change is needed to read it here.
-	const client = getServerClient() as {
-		ai_agents?: {
-			findFirst: (args: {
-				where: { id: string };
-				select: {
-					name: true;
-					welcome_message: true;
-					conversation_starters: true;
-					primary_color: true;
-				};
-			}) => Promise<{
-				name: string | null;
-				welcome_message: string | null;
-				conversation_starters: unknown;
-				primary_color: string | null;
-			} | null>;
-		};
-	};
-	try {
-		const agent = await client.ai_agents?.findFirst({
-			where: { id: agentId },
-			select: {
-				name: true,
-				welcome_message: true,
-				conversation_starters: true,
-				primary_color: true,
-			},
-		});
-		if (!agent) return {};
-		const starters = Array.isArray(agent.conversation_starters)
-			? (agent.conversation_starters as unknown[]).filter(
-					(entry): entry is string => typeof entry === "string" && entry.trim().length > 0,
-				)
-			: [];
-		return {
-			title: agent.name ?? undefined,
-			welcomeMessage: agent.welcome_message ?? undefined,
-			conversationStarters: starters.length > 0 ? starters : undefined,
-			primaryColor: agent.primary_color ?? undefined,
-		};
-	} catch (err) {
-		// FAIL SOFT, LIKE THE REST OF THE INJECTION. A presentation read that
-		// fails must not remove the bubble: the launcher carries its own
-		// default for every one of these fields, so an unreadable row costs
-		// wording, never the assistant itself.
-		getAppLogger().error(
-			`[resource-chat] agent presentation read failed (${agentId}): ${err instanceof Error ? err.message : String(err)}`,
-		);
-		return {};
-	}
-}
-
-/** A resolved source that carries a Puck content tree. */
-function puckContentOf(value: unknown): unknown[] | null {
-	const content = (value as { puck_data?: { content?: unknown } } | null | undefined)
-		?.puck_data?.content;
-	return Array.isArray(content) ? content : null;
-}
-
-const PAGE_SOURCE_KEY = "page";
-
-function findContentHost(
-	resolved: Record<string, unknown>,
-	regionSlots?: readonly string[],
-): unknown[] | null {
-	if (regionSlots?.length) {
-		for (const slot of regionSlots) {
-			const content = puckContentOf(resolved[slot]);
-			if (content) return content;
-		}
-		return null;
-	}
-	return puckContentOf(resolved[PAGE_SOURCE_KEY]);
-}
-
-async function buildResourceContext(
-	resolved: Record<string, unknown>,
-	resourceKey: string,
-	regionSlots?: readonly string[],
-): Promise<string> {
-	const record = resolved[resourceKey] as Record<string, unknown> | undefined;
-	const parts: string[] = [];
-
-	if (typeof record?.name === "string" && record.name) {
-		parts.push(`Title: ${record.name}`);
-	}
-	if (typeof record?.client_name === "string" && record.client_name) {
-		parts.push(`For: ${record.client_name}`);
-	}
-	if (typeof record?.description === "string" && record.description) {
-		parts.push(`Description: ${record.description}`);
-	}
-
-	for (const [key, value] of Object.entries(resolved)) {
-		if (value == null || typeof value === "function") continue;
-		const content = puckContentOf(value);
-		if (content) {
-			// A rendered document: every block, every prop, verbatim.
-			parts.push(`\n--- Document content (${key}) ---`);
-			parts.push(JSON.stringify(content, null, 2));
-			continue;
-		}
-		parts.push(`\n--- ${key} ---`);
-		parts.push(JSON.stringify(value, null, 2));
-	}
-
-	// Resolve DB-backed product tiers when present (proposals) so the GPT sees
-	// real pricing. Harmless for resources with no ProductTiers blocks.
-	const client = getServerClient() as {
-		products?: {
-			findFirst: (args: {
-				where: { id: string };
-				select: { id: true; billing_type: true; tiers: true; components: true };
-			}) => Promise<{ id: string; billing_type: string; tiers: unknown; components: unknown } | null>;
-		};
-	};
-	for (const block of (findContentHost(resolved, regionSlots) ?? []) as Array<
-		Record<string, unknown>
-	>) {
-		if (block?.type !== "ProductTiers") continue;
-		const props = block.props as Record<string, unknown> | undefined;
-		if (!props) continue;
-		const productIds = [props.productId, props.productId2, props.productId3].filter(
-			(id): id is string => typeof id === "string" && id.trim().length > 0,
-		);
-		for (const pid of productIds) {
-			try {
-				const product = await client.products?.findFirst({
-					where: { id: pid },
-					select: { id: true, billing_type: true, tiers: true, components: true },
-				});
-				if (product) {
-					parts.push(`\n--- Product tiers (productId: ${pid}) ---`);
-					parts.push(JSON.stringify(product, null, 2));
-				}
-			} catch {
-				// best-effort
-			}
-		}
-	}
-
-	return parts.join("\n");
-}
-
-function brandPrimaryColor(resolved: Record<string, unknown>): string {
-	const brand = resolved.brand as { primaryColor?: unknown } | undefined;
-	return typeof brand?.primaryColor === "string" ? brand.primaryColor : "";
-}
-
-/**
- * Inject the generic ResourceChatLauncher behind the gate. `opts` is the only
- * per-resource-type variation; everything else is shared.
- */
-export async function injectResourceChatLauncher(
-	resolved: Record<string, unknown>,
-	viewerEmail: string,
-	opts: ResourceChatOptions,
-): Promise<void> {
-	// Whichever region actually renders — `page` on a flat document, `body` on a
-	// region-slot one. No rendered content at all → nothing to attach to.
-	const hostContent = findContentHost(resolved, opts.regionSlots);
-	if (!hostContent) return;
-
-	const record = resolved[opts.resourceKey] as Record<string, unknown> | undefined;
-	const organisationId =
-		opts.organisationId ||
-		(typeof record?.organisation_id === "string" ? record.organisation_id : "");
-	if (!organisationId) {
-		// THIS BAIL USED TO BE SILENT, AND A SILENT DROP IS THE WORST FAILURE
-		// SHAPE A BLOCK CAN HAVE (measured 2026-09-08 on the quiz report): the
-		// page returns 200 and looks complete while the assistant is simply
-		// absent — resource_key named a resolved key that is null on some link
-		// shapes (a research-anchor link has no raw response match), and the
-		// page rendered a full report with no bubble and no error anywhere.
-		// The page must stay usable (fail-soft for the RENDER is the contract),
-		// but a declared assistant that did not inject is never "fine": name
-		// the key and the reason so the absence is observable.
-		getAppLogger().error(
-			`[resource-chat] assistant declared but NOT injected: resolved["${opts.resourceKey}"] is ${record === undefined ? "absent" : "null"} or carries no organisation_id — the launcher is silently missing from this page`,
-		);
-		return;
-	}
-
-	let agentId = "";
-	try {
-		agentId = (
-			await loadRegistryConfig("config", opts.agentConfigSlug, AgentConfigSchema)
-		).agentId;
-	} catch {
-		return; // no agent configured → no bubble (fail-soft, page unchanged)
-	}
-	if (!agentId) return;
-
-	try {
-		const runtimeContext = await buildResourceContext(
-			resolved,
-			opts.resourceKey,
-			opts.regionSlots,
-		);
-		const presentation = await loadAgentPresentation(agentId);
-		(hostContent as Array<Record<string, unknown>>).push({
-			type: LAUNCHER_BLOCK,
-			props: {
-				id: `${opts.resourceKey}-chat-launcher`,
-				agentId,
-				organisationId,
-				viewerEmail,
-				runtimeContext,
-				// The page's own brand still wins over the agent's stored colour:
-				// the bubble sits ON this document and must match it.
-				primaryColor: brandPrimaryColor(resolved) || presentation.primaryColor,
-				title: presentation.title,
-				welcomeMessage: presentation.welcomeMessage,
-				launchLabel: opts.launchLabel,
-				placeholder: opts.placeholder,
-				conversationStarters: presentation.conversationStarters,
-			},
-		});
-	} catch (err) {
-		getAppLogger().error(
-			`[resource-chat] launcher injection failed (${opts.resourceKey}): ${err instanceof Error ? err.message : String(err)}`,
-		);
-	}
-}