biz-a-cli 2.3.80-15385 → 2.3.80-15390

package/bin/hub.js

@@ -130,6 +130,11 @@ const argv = yargs(process.argv.slice(2))
 		   show its rules behave. */
 		default: "observe",
 	})
+	.options("aiGateway", {
+		describe:
+			"Doc 1 0b.6b: base URL of the central AI gateway (biz-a-server /ai) that ccai calls. Defaults to this hub's server (serverMode).",
+		type: "string",
+	})
 	.options("services", {
 		describe:
 			"Comma-separated list of engine jobs this agent handles (e.g., 'BPM,EMAIL')",

package/bin/hubEvent.js

@@ -28,6 +28,9 @@ import { authorizeRequest, principalForCliScript } from "../security/internalPri
 import { whoami } from "../security/whoami.js";
 import { runDraftAction } from "../engine/cc/draftStore.js";
 import { createPgDraftRepo } from "../engine/cc/pgRepo.js";
+import { runAiAction } from "../engine/cc/aiTurns.js";
+import { createTurnRepo } from "../engine/cc/turnRepo.js";
+import { createAiGatewayClient } from "../security/aiGatewayClient.js";
 import {
 	readUserPreferences,
 	writeUserPreferences,
@@ -47,7 +50,7 @@ import {
 	execPostgresTransaction,
 	isPostgresIndex,
 } from "../engine/domain/dialect.js";
-import { resolveTunnelTarget } from "./tunnelTarget.js";
+import { pipeTunnel } from "./tunnelTarget.js";
 /*
  * Doc 4 §8 — ⚠️ `runAsPrincipal` VALIDATES SYNCHRONOUSLY, so a browser-supplied active tenant outside
  * the signed claim throws out of the CALL, not out of the promise it would have returned. On this
@@ -232,59 +235,34 @@ export const streamEvent = async (socket, argv) =>
 				},
 			});
 
-			// let client = net.connect(argv['port'], argv['hostname']);
-			/* Where this pipe ends. A tenant this CLI serves on PostgreSQL is looped back to the
-			   hub's own FINA-compatible endpoint; every other tenant goes to FINA unchanged.
-			   Without this, biz-a's login — which only ever travels this tunnel — could not be
-			   answered at all on a tenant with no FINA running. */
-			const target = resolveTunnelTarget(argv, isPostgresIndex);
-			let client = target.secure
-				? tls.connect({
-						port: target.port,
-						host: target.host,
-						// Looping back to ourselves, the certificate is our own.
-						rejectUnauthorized: !target.local,
-					})
-				: net.connect(target.port, target.host);
-			client.on("connect", () => {
-				// logger.info(`client connected to ${argv['hostname']}:${argv['port']}`)
-				let s = ss.createStream();
-
-				// s.pipe(client).pipe(s);
-				s.pipe(client).pipe(addCLIAddressAsResponseHeader).pipe(s);
-
-				// use pipeline for better performance, back pressure, memory management, error handling and clean up
-				// pipeline(s, client, addCLIAddressAsResponseHeader, s, (err)=>{if (err) {logger.error(err)}}) // Not work well with heroku
-
-				s.on("end", () => {
-					client.destroy();
-				});
-
-				socket.once(clientId, () => {
-					// hub server shall notify us to end pipeline as soon as possible
-					client.end();
-				});
-
-				ss(socket).emit(clientId, s);
-			});
-
-			client.setTimeout(IDLE_SOCKET_TIMEOUT_MILLISECONDS);
-			client.on("timeout", () => {
-				// in case client not notify to end pipeline, then inactivity timeout will end it
-				client.end();
-			});
-
-			client.on("error", (err) => {
-				// handle connection refusal (create a stream and immediately close it)
-				logger.error(
-					`API Error : tunnel could not reach ${target.local ? "this CLI's own endpoint" : "the API"} at ` +
-						`${target.host}:${target.port} — `,
-					err,
-				);
-				let s = ss.createStream();
-				ss(socket).emit(clientId, s);
-				s.end();
+			/*
+			 * Where this pipe ends is decided by the request's FIRST BYTES (bin/tunnelTarget.js): a tenant
+			 * this CLI serves on PostgreSQL, and — since 2026-10-01 — a Firebird tenant's LOGIN, are looped
+			 * back to the hub's own FINA-compatible endpoint; every other request goes to FINA unchanged.
+			 * Without the loop-back a Firebird login never passed through the CLI, so it never received
+			 * the signed principal (Doc 6 on Firebird).
+			 */
+			const s = ss.createStream();
+			pipeTunnel({
+				stream: s,
+				argv,
+				isPostgresIndex,
+				connect: (target) =>
+					target.secure
+						? tls.connect({
+								port: target.port,
+								host: target.host,
+								// Looping back to ourselves, the certificate is our own.
+								rejectUnauthorized: !target.local,
+							})
+						: net.connect(target.port, target.host),
+				transform: () => addCLIAddressAsResponseHeader,
+				idleMs: IDLE_SOCKET_TIMEOUT_MILLISECONDS,
+				// hub server shall notify us to end pipeline as soon as possible
+				onClient: (client) => socket.once(clientId, () => client.end()),
+				logger,
 			});
+			ss(socket).emit(clientId, s);
 		};
 
 		// const cliReqCb = async (data, callback) => {
@@ -673,6 +651,31 @@ const handleCliCommand = async (data, cb, argv) => {
 			 * publish may). A refusal the user can act on is returned as `problems`, as companytheme
 			 * does; `code` carries CC_DRAFT_STALE for a save made from an old revision.
 			 */
+			/*
+			 * Doc 1 0b.6b — an AI turn from Control Center, through the central gateway
+			 * (engine/cc/aiTurns.js). `send` answers at once; the turn finishes in the background, is
+			 * recorded in SYS$CC_TURN with its cost, and the VERIFIED user is told {turnId, outcome}.
+			 * The CLI holds no AI key: the gateway client signs with this company's biza.ai key.
+			 */
+			case "ccai": {
+				const aiResult = await runAiAction({
+					repo: createTurnRepo({ exec: (sql) => execPostgres(sql, argv["dbindex"]) }),
+					gateway: createAiGatewayClient({ baseUrl: argv["aiGateway"] || argv["server"], subdomain: argv["subdomain"] }),
+					principal: principalForCliScript(data.headers, { mode: argv["principalMode"] || "observe" }),
+					isPostgres: isPostgresIndex(argv["dbindex"]),
+					action: data.action,
+					args: data.args,
+					notify: (userId, eventName, payload) => ClientEmitter.emitUsers([userId], eventName, payload),
+					logger,
+				});
+				cb(null, {
+					success: aiResult.ok,
+					...(aiResult.code ? { code: aiResult.code } : {}),
+					problems: aiResult.problems ?? [],
+					data: aiResult.data ?? null,
+				});
+				break;
+			}
 			case "ccdraft": {
 				const ccResult = await runDraftAction({
 					repo: createPgDraftRepo({

package/bin/tunnelTarget.js

@@ -11,8 +11,35 @@
  * database index, as it is everywhere else in this port.
  */
 
+/*
+ * ⚠️ Doc 6 on Firebird (found live 2026-10-01): the LOGIN of a Firebird tenant went straight to FINA
+ * through this tunnel, so the CLI never saw FINA's answer and never added the signed principal — and
+ * every principal-guarded command (company theme, logo, user preferences) refused on Firebird. The login
+ * is now looped back to the CLI's own endpoint too (finaEndpoint.js forwards it to FINA and appends the
+ * principal); every other Firebird request still goes straight to FINA, byte for byte.
+ *
+ * Recognised by its REQUEST LINE only (method + path), never by anything in a body.
+ */
+const LOGIN_PATH = /%22get_valid_user_id%22|"get_valid_user_id"/i;
+
+export const isLoginRequest = (firstChunk) => {
+	if (!firstChunk || firstChunk.length === 0) return false;
+	const head = Buffer.from(firstChunk).subarray(0, 2048).toString("latin1");
+	const lineEnd = head.indexOf("\r\n");
+	const requestLine = lineEnd === -1 ? head : head.slice(0, lineEnd);
+	const [method, path] = requestLine.split(" ");
+	return method === "POST" && typeof path === "string" && LOGIN_PATH.test(path);
+};
+
+const ownEndpoint = (argv) => ({
+	host: "127.0.0.1", // ourselves — never the public interface
+	port: argv.serverport,
+	secure: argv.isHttps === true, // how WE listen; argv.secure describes FINA
+	local: true,
+});
+
 /* Kept separate from hubEvent.js so it can be exercised without importing the socket machinery. */
-export const resolveTunnelTarget = (argv, isPostgresIndex) => {
+export const resolveTunnelTarget = (argv, isPostgresIndex, firstChunk) => {
 	const fina = {
 		host: argv.hostname,
 		port: argv.port,
@@ -20,6 +47,7 @@ export const resolveTunnelTarget = (argv, isPostgresIndex) => {
 		local: false,
 	};
 
+	if (isLoginRequest(firstChunk)) return ownEndpoint(argv);
 	if (!argv.dbindex) return fina;
 
 	let servedHere = false;
@@ -32,10 +60,35 @@ export const resolveTunnelTarget = (argv, isPostgresIndex) => {
 	}
 	if (!servedHere) return fina;
 
-	return {
-		host: "127.0.0.1", // ourselves — never the public interface
-		port: argv.serverport,
-		secure: argv.isHttps === true, // how WE listen; argv.secure describes FINA
-		local: true,
-	};
+	return ownEndpoint(argv);
+};
+
+/*
+ * One tunnelled request: biz-a's bytes arrive on `stream`; the connection is opened only once the first
+ * bytes say where it must go (resolveTunnelTarget), that first chunk is written first so nothing is
+ * lost, and the rest is piped. The answer flows back through `transform()` (the response-header
+ * injection). A connection that fails ends the stream, so biz-a is not left waiting.
+ */
+export const pipeTunnel = ({ stream, argv, isPostgresIndex, connect, transform, idleMs, onClient, logger = console }) => {
+	stream.once("data", (first) => {
+		stream.pause();
+		const target = resolveTunnelTarget(argv, isPostgresIndex, first);
+		const client = connect(target);
+		onClient?.(client);
+		if (idleMs) client.setTimeout(idleMs);
+		client.on("timeout", () => client.end());
+		client.on("connect", () => {
+			client.write(first);
+			stream.pipe(client).pipe(transform()).pipe(stream);
+			stream.resume();
+		});
+		client.on("error", (err) => {
+			logger.error?.(
+				`API Error : tunnel could not reach ${target.local ? "this CLI's own endpoint" : "the API"} at ${target.host}:${target.port} — `,
+				err,
+			);
+			stream.end();
+		});
+		stream.on("end", () => client.destroy());
+	});
 };

package/engine/cc/aiTurns.js

@@ -0,0 +1,167 @@
+/*
+ * Doc 1 step 0b.6b — `ccai`: an AI turn from Control Center, through the central AI gateway.
+ *
+ * CC → this CLI → the gateway (biz-a-server /ai; the only holder of the OpenRouter key, the company's
+ * limit and the usage ledger — 0b.6a) → OpenRouter. The CLI holds NO AI key: it signs with the
+ * company's own `biza.ai.<subdomain>` key (security/aiGatewayClient.js), which proves to the gateway
+ * which company is spending.
+ *
+ *   send    answers AT ONCE with {turnId, jobId} — a model call can take minutes, CC's command times out
+ *           at 15 s and the hub relay at 28 s. The turn then finishes in the background: recorded in
+ *           SYS$CC_TURN with its cost (Doc 1 §10), and the VERIFIED user is told {turnId, outcome} and
+ *           nothing more — socket rooms come from unverified handshake values, so the answer itself is
+ *           fetched with `get`, which checks the principal.
+ *   get     the caller's own turn. One still RUNNING long after it started belonged to a CLI that
+ *           restarted mid-turn: it is reported, and stored, as lost.
+ *   usage   this company's month — limit and spend — from the gateway.
+ *   settle  the AI Assist panel reports what it did with a turn's tool calls (COMMITTED / ROLLED_BACK).
+ *
+ * Administrators only (ruling 2026-10-01): every call spends the company's AI budget.
+ */
+import { requirePrincipal } from "../orm/principalGuards.js";
+
+/* The gateway gives a job 5 minutes before calling it lost; a turn gets a little longer. */
+export const AI_TURN_LOST_AFTER_MS = 6 * 60 * 1000;
+const MAX_TOKENS_CAP = 32000;
+
+const refuse = (message, code, data) => ({ ok: false, code, problems: [message], ...(data !== undefined ? { data } : {}) });
+const done = (data) => ({ ok: true, data });
+
+const isPlainObject = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
+
+/* What the user asked this turn: the last user message (the audit's PROMPT column). */
+const promptOf = (messages) => {
+	const last = [...messages].reverse().find((m) => m.role === "user");
+	if (!last) return null;
+	return typeof last.content === "string" ? last.content : JSON.stringify(last.content);
+};
+
+const badRequest = (args) => {
+	const { sessionId, phase, messages, tools, maxTokens } = args;
+	if (typeof sessionId !== "string" || !/^[A-Za-z0-9_.:-]{1,100}$/.test(sessionId)) return "sessionId is required (letters, digits, . _ : -, at most 100).";
+	if (phase !== "A" && phase !== "B") return 'phase must be "A" (story → map) or "B" (map → config).';
+	if (!Array.isArray(messages) || messages.length === 0) return "messages must be a non-empty list.";
+	if (!messages.every((m) => isPlainObject(m) && typeof m.role === "string")) return "every message needs a role.";
+	if (tools !== undefined && !Array.isArray(tools)) return "tools must be a list.";
+	if (maxTokens !== undefined && !(Number.isInteger(maxTokens) && maxTokens > 0 && maxTokens <= MAX_TOKENS_CAP)) {
+		return `maxTokens must be a whole number from 1 to ${MAX_TOKENS_CAP}.`;
+	}
+	return null;
+};
+
+/* The gateway's refusal, in words an implementor can act on. */
+const describeGatewayRefusal = (error) => {
+	const d = error.details ?? {};
+	if (error.code === "AI_LIMIT_REACHED") {
+		return `This company has used its AI limit for ${d.period} ($${d.spentUsd} of $${d.limitUsd}). Ask Imamatek to raise it.`;
+	}
+	if (error.code === "UNAUTHORIZED") return "The AI gateway did not accept this CLI's key. Ask Imamatek to provision it again.";
+	return `The AI gateway refused the request (${error.code}).`;
+};
+
+const actions = {
+	send: async ({ repo, gateway, userId, args, notify, schedule, logger }) => {
+		const problem = badRequest(args);
+		if (problem) return refuse(problem, "AI_BAD_REQUEST");
+
+		const { sessionId, phase, functionId = null, messages, tools, tool_choice, maxTokens } = args;
+		const turn = await repo.insertTurn({
+			sessionId,
+			phase,
+			functionId,
+			userId,
+			prompt: promptOf(messages),
+			context: { messages, ...(tools ? { tools } : {}) },
+		});
+
+		const body = {
+			messages,
+			...(tools ? { tools } : {}),
+			...(tool_choice !== undefined ? { tool_choice } : {}),
+			...(maxTokens !== undefined ? { max_tokens: maxTokens } : {}),
+			meta: { sessionId, phase, turnId: turn.id },
+		};
+
+		let job;
+		try {
+			/* ⚠️ The request id is the TURN: a resubmission of this turn is the same gateway job and
+			   one charge, never a second call. */
+			job = await gateway.submit(body, { requestId: `cc-turn-${turn.id}` });
+		} catch (error) {
+			const code = error?.code && error?.status ? error.code : "AI_UNAVAILABLE";
+			await repo.failTurn(turn.id, code === "AI_UNAVAILABLE" ? String(error?.message ?? error) : code);
+			return code === "AI_UNAVAILABLE"
+				? refuse(String(error?.message ?? error), code, {})
+				: refuse(describeGatewayRefusal(error), code, error.details ?? {});
+		}
+
+		/* ⚠️ After the answer. Never throws: a failure is recorded on the turn and the user is told. */
+		schedule(async () => {
+			let outcome = "FAILED";
+			try {
+				const result = await gateway.wait(job.jobId);
+				if (result?.status === "DONE") {
+					const toolCalls = result.message?.tool_calls?.length ? result.message.tool_calls : null;
+					/* A turn that ended with tool calls stays RUNNING until the panel settles it. */
+					outcome = toolCalls ? "RUNNING" : "TEXT_ONLY";
+					await repo.completeTurn(turn.id, {
+						modelText: result.message?.content ?? null,
+						toolCalls,
+						outcome,
+						model: result.model ?? null,
+						tokensIn: result.tokensIn ?? null,
+						tokensOut: result.tokensOut ?? null,
+						costUsd: result.costUsd ?? null,
+						gatewayRef: result.generationId ?? null,
+					});
+				} else {
+					await repo.failTurn(turn.id, result?.error ?? `the gateway ended the job as ${result?.status}`);
+				}
+			} catch (error) {
+				logger?.error?.(`[ccai] turn ${turn.id} failed: ${error?.message ?? error}`);
+				await repo.failTurn(turn.id, String(error?.message ?? error)).catch(() => {});
+			}
+			try {
+				await notify(userId, `CC_AI_TURN_${turn.id}`, { turnId: turn.id, outcome });
+			} catch (error) {
+				logger?.error?.(`[ccai] could not tell user ${userId} turn ${turn.id} ended: ${error?.message ?? error}`);
+			}
+		});
+
+		return done({ turnId: turn.id, jobId: job.jobId });
+	},
+
+	get: async ({ repo, userId, args, now }) => {
+		const turn = await repo.getTurn(Number(args.turnId));
+		/* Another user's turn is indistinguishable from no turn. */
+		if (!turn || turn.userId !== userId) return refuse("There is no such AI turn.", "AI_TURN_NOT_FOUND");
+		const startedAt = turn.startedAt ? new Date(turn.startedAt).getTime() : now();
+		if (turn.outcome === "RUNNING" && !turn.toolCalls && now() - startedAt > AI_TURN_LOST_AFTER_MS) {
+			return done((await repo.failTurn(turn.id, "AI_TURN_LOST")) ?? (await repo.getTurn(turn.id)));
+		}
+		return done(turn);
+	},
+
+	usage: async ({ gateway }) => done(await gateway.usage()),
+
+	settle: async ({ repo, userId, args }) => {
+		const settled = await repo.settleTurn(Number(args.turnId), userId, args.outcome);
+		return settled ? done(settled) : refuse("Only your own turn that is waiting on its tool calls can be settled.", "AI_TURN_NOT_SETTLEABLE");
+	},
+};
+
+export const AI_ACTIONS = Object.freeze(Object.keys(actions));
+
+export const runAiAction = async ({ repo, gateway, principal, isPostgres, action, args = {}, notify, schedule = (fn) => setImmediate(fn), now = Date.now, logger }) => {
+	if (!isPostgres) {
+		throw new Error("Control Center AI needs a PostgreSQL tenant; this database index is not one.");
+	}
+	const userId = requirePrincipal(principal, "Control Center AI requires a verified principal. Sign in again.");
+	/* ⚠️ Authority first, before anything is read or spent. */
+	if (!(await repo.isAdministrator(userId))) {
+		throw new Error(`user ${userId} is not an administrator; only administrators may use Control Center AI.`);
+	}
+	const handler = actions[action];
+	if (!handler) throw new Error(`Unknown ccai action "${action}". Use one of ${AI_ACTIONS.join(", ")}.`);
+	return handler({ repo, gateway, userId, args: args ?? {}, notify, schedule, now, logger });
+};

package/engine/cc/turnRepo.js

@@ -0,0 +1,109 @@
+/*
+ * Doc 1 step 0b.6b — the PostgreSQL repository behind SYS$CC_TURN, the AI turn audit (Doc 1 §10).
+ *
+ * A turn is inserted RUNNING when it starts and completed ONCE when it ends: every completion is
+ * conditional on OUTCOME = 'RUNNING', so a late, repeated or racing completion cannot rewrite the
+ * record. There is no method that deletes — the table has no DELETE grant either
+ * (migrations/postgres/1790100000000__cc_doc1_revoke.sql).
+ */
+import { quoteLiteral } from "../orm/dialect.js";
+import { buildFindAdminForUserSql } from "../orm/userAdmin.js";
+
+export const TURN_TABLE = "sys$cc_turn";
+export const TURN_OUTCOMES = Object.freeze(["RUNNING", "COMMITTED", "ROLLED_BACK", "TEXT_ONLY", "FAILED"]);
+const LIST_LIMIT = 100;
+
+/* json, not jsonb: what was sent and what came back are kept as written. */
+const jsonText = (value) => (value === null || value === undefined ? "NULL" : `${quoteLiteral(JSON.stringify(value))}::json`);
+const text = (value) => (value === null || value === undefined ? "NULL" : quoteLiteral(String(value)));
+const int = (value) => (Number.isFinite(Number(value)) && value !== null && value !== undefined ? String(Math.trunc(Number(value))) : "NULL");
+const numeric = (value) => (Number.isFinite(Number(value)) && value !== null && value !== undefined ? String(Number(value)) : "NULL");
+const num = (value) => (value === null || value === undefined ? null : Number(value));
+const jsonValue = (value) => (typeof value === "string" ? JSON.parse(value) : (value ?? null));
+
+const checkOutcome = (outcome) => {
+	if (!TURN_OUTCOMES.includes(outcome)) throw new Error(`outcome must be one of ${TURN_OUTCOMES.join(", ")}`);
+	return outcome;
+};
+
+/* pg lower-cases column names and hands bigint / numeric back as STRINGS. */
+const toTurn = (row) =>
+	row
+		? {
+				id: num(row.id),
+				sessionId: row.session_id,
+				phase: row.phase,
+				functionId: row.function_id ?? null,
+				userId: num(row.user_id),
+				prompt: row.prompt ?? null,
+				context: jsonValue(row.context),
+				modelText: row.model_text ?? null,
+				toolCalls: jsonValue(row.tool_calls),
+				outcome: row.outcome,
+				error: row.error ?? null,
+				model: row.model ?? null,
+				tokensIn: num(row.tokens_in),
+				tokensOut: num(row.tokens_out),
+				costUsd: num(row.cost_usd),
+				gatewayRef: row.gateway_ref ?? null,
+				startedAt: row.started_at ?? null,
+				finishedAt: row.finished_at ?? null,
+			}
+		: null;
+
+const COLUMNS =
+	"id, session_id, phase, function_id, user_id, prompt, context, model_text, tool_calls, outcome, error, model, tokens_in, tokens_out, cost_usd, gateway_ref, started_at, finished_at";
+
+export const createTurnRepo = ({ exec }) => {
+	const first = async (sql) => toTurn((await exec(sql))?.[0] ?? null);
+
+	return {
+		/* The same administrator check the draft store uses (SYS$ADMINISTRATOR). Read-only. */
+		isAdministrator: async (userId) => ((await exec(buildFindAdminForUserSql(userId))) ?? []).length > 0,
+
+		insertTurn: ({ sessionId, phase, functionId = null, userId, prompt, context }) =>
+			first(
+				`INSERT INTO ${TURN_TABLE} (session_id, phase, function_id, user_id, prompt, context) VALUES ` +
+					`(${text(sessionId)}, ${text(phase)}, ${text(functionId)}, ${int(userId)}, ${text(prompt)}, ${jsonText(context)}) ` +
+					`RETURNING ${COLUMNS}`,
+			),
+
+		completeTurn: (id, { modelText = null, toolCalls = null, outcome, model = null, tokensIn = null, tokensOut = null, costUsd = null, gatewayRef = null }) =>
+			first(
+				`UPDATE ${TURN_TABLE} SET model_text = ${text(modelText)}, tool_calls = ${jsonText(toolCalls)}, ` +
+					`outcome = ${quoteLiteral(checkOutcome(outcome))}, model = ${text(model)}, tokens_in = ${int(tokensIn)}, ` +
+					`tokens_out = ${int(tokensOut)}, cost_usd = ${numeric(costUsd)}, gateway_ref = ${text(gatewayRef)}` +
+					// A turn that ended with tool calls stays open for `settle`; any other is finished now.
+					(outcome === "RUNNING" ? "" : ", finished_at = now()") +
+					` WHERE id = ${int(id)} AND outcome = 'RUNNING' RETURNING ${COLUMNS}`,
+			),
+
+		failTurn: (id, error) =>
+			first(
+				`UPDATE ${TURN_TABLE} SET outcome = 'FAILED', error = ${text(String(error ?? "").slice(0, 2000))}, finished_at = now() ` +
+					`WHERE id = ${int(id)} AND outcome = 'RUNNING' RETURNING ${COLUMNS}`,
+			),
+
+		/* The AI Assist panel reports what it did with the tool calls: applied (COMMITTED) or not. */
+		settleTurn: async (id, userId, outcome) => {
+			if (!["COMMITTED", "ROLLED_BACK"].includes(outcome)) throw new Error("outcome must be COMMITTED or ROLLED_BACK");
+			return first(
+				`UPDATE ${TURN_TABLE} SET outcome = ${quoteLiteral(outcome)}, finished_at = now() ` +
+					`WHERE id = ${int(id)} AND user_id = ${int(userId)} AND outcome = 'RUNNING' AND tool_calls IS NOT NULL ` +
+					`RETURNING ${COLUMNS}`,
+			);
+		},
+
+		getTurn: (id) => first(`SELECT ${COLUMNS} FROM ${TURN_TABLE} WHERE id = ${int(id)}`),
+
+		listTurns: async ({ userId, sessionId = null, limit = 20 }) => {
+			const bounded = Math.max(1, Math.min(LIST_LIMIT, Number(limit) || 20));
+			const rows = await exec(
+				`SELECT ${COLUMNS} FROM ${TURN_TABLE} WHERE user_id = ${int(userId)}` +
+					(sessionId ? ` AND session_id = ${text(sessionId)}` : "") +
+					` ORDER BY id DESC LIMIT ${bounded}`,
+			);
+			return (rows ?? []).map(toTurn);
+		},
+	};
+};

package/engine/orm/registryClient.js

@@ -1,8 +1,10 @@
 /*
- * The authenticated call to biz-a for this tenant's database coordinates.
+ * The authenticated call to biz-a for this tenant's configuration.
  *
  * The CLI must never read Mongo directly — biz-a owns the `configuration` registry and serves it
- * over HTTPS. This is the transport half; registry.js holds the caching policy.
+ * over HTTPS. This is the transport half; registry.js holds the caching policy, and
+ * scheduler/configController.js makes the same call with `scope: "scheduler"` to fetch what the
+ * timers need (it used to open MongoClient against the Atlas cluster itself).
  *
  * Authentication reuses the scheme biz-a already accepts from the CLI (see
  * biz-a/src/api/encryptController.js): a base64 JSON payload plus an RSA-PSS signature over it,
@@ -27,9 +29,17 @@ export const REGISTRY_PATH = "/config/resolveBySubdomain";
    or the `biza` command was launched from. */
 const CLI_PRIVATE_KEY = path.join(__dirname, "..", "..", "key", "cliPrivate.pem");
 
-export const buildSignedPayload = ({ subdomain, now }) =>
+/* `scope` is OMITTED when absent rather than sent as undefined, so the default payload stays
+   byte-identical to what every deployed CLI already signs. biz-a reads the scope from this signed
+   payload, never from the request body, so a scope that never got signed would be ignored. */
+export const buildSignedPayload = ({ subdomain, now, scope }) =>
 	Buffer.from(
-		JSON.stringify({ issuer: "CLI", subdomain: String(subdomain ?? ""), ts: now }),
+		JSON.stringify({
+			issuer: "CLI",
+			subdomain: String(subdomain ?? ""),
+			...(scope ? { scope } : {}),
+			ts: now,
+		}),
 	).toString("base64");
 
 /* The default signer. Injected in tests so they need no key material. */
@@ -46,8 +56,10 @@ export const makeRegistryClient = ({
 	signPayload = signWithCliKey,
 	now = Date.now,
 }) => ({
-	async resolve(subdomain) {
-		const data = buildSignedPayload({ subdomain, now: now() });
+	/* `scope` is per call: the same client serves both the plain coordinate read (dialect.js's
+	   primeRegistry) and the scheduler's wider read, which also needs methodClass and smtp. */
+	async resolve(subdomain, { scope } = {}) {
+		const data = buildSignedPayload({ subdomain, now: now(), scope });
 		const res = await http.post(
 			`${serverLink}${REGISTRY_PATH}`,
 			{ data, signature: signPayload(data) },

package/envs/env.dev.js

@@ -1,12 +1,11 @@
+/*
+ * PUBLIC values only — this file ships in the published npm package. See envs/env.js for why the Atlas
+ * connection strings that used to live here are gone.
+ */
 import { DEV_SERVER_URL, DEV_HUB_URL } from './hosts.js';
 
 export const envDev = {
   production: false,
-  BIZA_MONGO_LINK: 'mongodb+srv://imm_biza:' +
-    encodeURIComponent('imm@2023') + '@cluster0.z2yr8kp.mongodb.net/?retryWrites=true&w=majority',
-  CDM_MONGO_LINK: 'mongodb+srv://imm_cdm:' +
-    encodeURIComponent('imm@2019') + '@imm-cdm-dev.rf6wr.mongodb.net/?retryWrites=true&w=majority',
-  COMPANY_REGISTER: 'companyregister-dev',
   BIZA_SERVER_LINK: DEV_SERVER_URL,
   BIZA_HUB_SERVER_LINK: DEV_HUB_URL
   // Retired values, kept in case biz-a.id (or the old heroku dyno) is used again:

package/envs/env.js

@@ -1,12 +1,16 @@
+/*
+ * PUBLIC values only. This file ships inside the published npm package (package.json `files` includes
+ * `envs/`), so nothing secret may live here.
+ *
+ * BIZA_MONGO_LINK, CDM_MONGO_LINK and COMPANY_REGISTER used to sit in this object with their Atlas
+ * passwords in plaintext. The CLI no longer talks to Mongo at all: biz-a serves each tenant's
+ * configuration over HTTPS and performs both database reads itself — see
+ * scheduler/configController.js and engine/orm/registryClient.js.
+ */
 import { SERVER_URL, HUB_URL } from './hosts.js';
 
 export const env = {
   production: true,
-  BIZA_MONGO_LINK: 'mongodb+srv://imm_biza:' +
-    encodeURIComponent('imm@2023') + '@cluster0.lezywmk.mongodb.net/?retryWrites=true&w=majority',
-  CDM_MONGO_LINK: 'mongodb+srv://imm_cdm:' +
-    encodeURIComponent('imm@2019') + '@imm-cdm.ohcqt.mongodb.net/?retryWrites=true&w=majority',
-  COMPANY_REGISTER: 'companyregister',
   BIZA_SERVER_LINK: SERVER_URL,
   BIZA_HUB_SERVER_LINK: HUB_URL
   // Retired values, kept in case biz-a.id (or the old heroku dyno) is used again:

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "biz-a-cli",
-	"version": "2.3.80-15385",
+	"version": "2.3.80-15390",
 	"description": "",
 	"main": "bin/index.js",
 	"type": "module",
@@ -10,7 +10,7 @@
 	},
 	"files": [
 		"bin/**/*",
-		"config/**/*",
+		"config/databases.example.json",
 		"db/**/*",
 		"engine/**/*",
 		"envs/**/*",
@@ -50,7 +50,6 @@
 		"cors": "^2.8.5",
 		"dayjs": "^1.11.10",
 		"express": "^4.18.3",
-		"mongodb": "^6.5.0",
 		"net": "^1.0.2",
 		"nodemailer": "^6.9.12",
 		"pg": "^8.23.0",

package/readme.md

@@ -107,4 +107,20 @@
 		hub --mode agent --dispatcherUrl http://localhost:3000 --services BPM,EMAIL --sp 3002
 
 > [!TIP]
->    When running multiple Agents on the same server, always define unique ports using --sp to avoid collisions.
+>    When running multiple Agents on the same server, always define unique ports using --sp to avoid collisions.
+
+
+## V. Watcher (scheduler)
+
+	watcher -c [company] -p [port, default: 3001]
+
+	Example :
+		watcher -c imamatek
+
+`-c` / `--company` is the company name, exactly as before — nothing about the command line changed.
+
+> [!NOTE]
+> The CLI holds **no database credentials**. It asks the Biz-A server for this company's configuration
+> over HTTPS, and the server performs the database reads — the company lookup and the configuration
+> itself — so nothing secret needs to be installed alongside the package. An unknown company fails with
+> `ENOENT`.

package/scheduler/configController.js

@@ -1,60 +1,32 @@
-import { MongoClient, ObjectId } from 'mongodb';
-import { envDev } from '../envs/env.dev.js';
-import { env } from '../envs/env.js';
-import { logger } from "../logger.js";
+/*
+ * The scheduler's configuration read.
+ *
+ * This module used to open MongoClient TWICE at `watcher` startup — once against the CDM cluster to
+ * turn a company name into an ObjectId, once against the biz-a cluster for the configuration document
+ * and its SMTP row — using connection strings hardcoded in envs/env.js. That file ships inside the
+ * published npm package, so both Atlas passwords were public and one leak was every tenant's database.
+ *
+ * biz-a owns the `configuration` collection and already serves it over HTTPS to the rest of the CLI
+ * (engine/orm/registryClient.js), so both reads moved there and the scheduler asks for the finished
+ * config in ONE request. The CLI now holds no database credential at all, and `mongodb` is no longer
+ * even a dependency.
+ *
+ * WHAT DID NOT CHANGE: the returned `config` keeps exactly the shape the Mongo aggregate produced, so
+ * datalib.js, watcherController.js and mailController.js are untouched. Everything after this point —
+ * SYS$WATCHER, SYS$TIMER, SYS$HISTORY, the CLI scripts and their mail — was never in Mongo; it lives
+ * in the tenant's own database, reached over the FINA REST API or Postgres using the coordinates this
+ * read returns.
+ */
+import { makeRegistryClient } from "../engine/orm/registryClient.js";
+import { env } from "../envs/env.js";
 
-let BIZA_MONGO_LINK;
-let CDM_MONGO_LINK;
-let COMPANY_REGISTER;
-
-// if ((process.env.NODE_ENV == undefined) || (process.env.NODE_ENV == 'development')) {
-// BIZA_MONGO_LINK = envDev.BIZA_MONGO_LINK;
-// CDM_MONGO_LINK = envDev.CDM_MONGO_LINK;
-// COMPANY_REGISTER = envDev.COMPANY_REGISTER;
-
-// logger.info('BIZA_MONGO_LINK =>', BIZA_MONGO_LINK);
-// logger.info('CDM_MONGO_LINK =>', CDM_MONGO_LINK);
-// logger.info('COMPANY_REGISTER =>', COMPANY_REGISTER);
-// } else {
-BIZA_MONGO_LINK = env.BIZA_MONGO_LINK;
-CDM_MONGO_LINK = env.CDM_MONGO_LINK;
-COMPANY_REGISTER = env.COMPANY_REGISTER;
-// }
-
-async function fetchSelectedConfig(aggregateField) {
-    const client = new MongoClient(BIZA_MONGO_LINK);
-    try {
-        await client.connect();
-        const db = client.db('biz-a');
-        const config = db.collection('configuration');
-
-        return await config.aggregate(aggregateField).toArray();
-    } catch (error) {
-        logger.error(error);
-        throw new Error(error);
-    } finally {
-        client.close()
-    }
-}
-
-function getSelectedConfigAggregateField(companyObjectId) {
-    let configAggregate = [];
-    if (companyObjectId) {
-        configAggregate.push({ "$match": { companyObjectId: new ObjectId(companyObjectId) } });
-    };
-    configAggregate.push({
-        $lookup: {
-            from: 'smtp',
-            localField: '_id',
-            foreignField: 'configObjectId',
-            as: 'smtp'
-        }
-    });
-    configAggregate.push({ $unwind: { path: "$smtp" } });
-
-    return configAggregate;
-}
+/* biz-a serves `methodClass` and `smtp` only under this scope, so the plain coordinate read that
+   `biza publish` and `migrate` perform never starts carrying an SMTP password it has no use for. It
+   travels inside the SIGNED payload, so it cannot be widened by a caller. */
+export const SCHEDULER_SCOPE = "scheduler";
 
+/* The scheduler reads `config.url`; biz-a stores it as API_URL. Unchanged from the Mongo-backed
+   version, array in and array out, because that is the shape its tests pin. */
 function addUrlValue(config) {
     if (!config[0].url) {
         config[0].url = config[0].API_URL
@@ -62,56 +34,43 @@ function addUrlValue(config) {
     return config;
 }
 
-async function getSelectedConfig(companyObjectId) {
-    let config = await fetchSelectedConfig(getSelectedConfigAggregateField(companyObjectId));
-    config = addUrlValue(config);
-    return config[0];
-}
+/* `client` is injected in tests so they need neither a network nor key material. `tenant` is passed
+   to biz-a verbatim: the server resolves a subdomain OR a CDM company name, so whatever
+   `watcher -c` was given keeps working. */
+export const createConfigReader = ({ client, serverLink = env.BIZA_SERVER_LINK } = {}) => {
+	const registry = client ?? makeRegistryClient({ serverLink });
 
-function getCompanyObjectIdFindOneField(companyName) {
-    return [
-        { companyID: { $regex: new RegExp(`^${companyName}$`, 'i') } },
-        {
-            projection: {
-                _id: 1,
-                companyID: 1
-            }
-        }
-    ]
-}
+	return {
+		async getSelectedConfig(tenant) {
+			if (!tenant) {
+				throw new Error("the scheduler needs a tenant (subdomain or company name)");
+			}
 
-async function fetchCompanyObjectId(findOneField) {
-    const client = new MongoClient(CDM_MONGO_LINK);
-    try {
-        await client.connect();
-        const db = client.db(COMPANY_REGISTER);
-        const company = db.collection('companies');
+			const doc = await registry.resolve(tenant, { scope: SCHEDULER_SCOPE });
 
-        return await company.findOne(findOneField[0], findOneField[1]);
-    } catch (error) {
-        logger.error(error);
-        throw new Error(error);
-    } finally {
-        client.close()
-    }
-}
+			/* biz-a answers an unknown tenant with 404, which resolve() deliberately reports as null
+			   rather than throwing. Keep the ENOENT signal callers already branch on, and keep it
+			   distinct from a transport failure — which propagates, so an outage is never mistaken
+			   for "this tenant does not exist". */
+			if (!doc) {
+				throw { code: "ENOENT" };
+			}
 
-function validateCompanyObjectId(companyObjectId) {
-    if (companyObjectId?._id) {
-        return companyObjectId;
-    } else {
-        throw { code: 'ENOENT' };
-    }
+			return addUrlValue([doc])[0];
+		},
+	};
 };
 
-async function getCompanyObjectId(companyName) {
-    const companyObjectId = await fetchCompanyObjectId(getCompanyObjectIdFindOneField(companyName));
-    return validateCompanyObjectId(companyObjectId);
-};
+let defaultReader = null;
+
+/* Built lazily, so importing this module stays side-effect-free — tests/config.test.js imports it for
+   addUrlValue alone. */
+async function getSelectedConfig(tenant) {
+	defaultReader = defaultReader ?? createConfigReader();
+	return defaultReader.getSelectedConfig(tenant);
+}
 
 export {
-    BIZA_MONGO_LINK,
     getSelectedConfig,
-    getCompanyObjectId,
     addUrlValue
-};
+};

package/scheduler/timer.js

@@ -1,7 +1,7 @@
 import { checkSchedule } from "./datalib.js"
 import { getWatchers, getHistories } from "./watcherController.js";
 import { isItTime, loopTimer } from "./watcherlib.js"
-import { getCompanyObjectId, getSelectedConfig } from "../scheduler/configController.js";
+import { getSelectedConfig } from "../scheduler/configController.js";
 import { historyRecordToJson, watcherRecordToJson, setUtcDate } from "./converter.js";
 import { logger } from "../logger.js";
 
@@ -66,9 +66,10 @@ export async function* setConstantInterval(interval, start) {  //SCY BZ 4169
     }
 }
 
+/* `companyName` reaches biz-a untouched: it resolves a subdomain or a CDM company name, so the
+   separate getCompanyObjectId round trip the CLI used to make against the CDM Atlas cluster is gone. */
 export const runScheduler = async (companyName) => {
-    const company = await getCompanyObjectId(companyName);
-    const config = await getSelectedConfig(company._id);
+    const config = await getSelectedConfig(companyName);
 
     Promise.all([getHistories(config), getWatchers(config)]).then(([historyResult, watcherResult]) => {
         const histories = historyRecordToJson(historyResult);

package/security/aiGatewayClient.js

@@ -85,7 +85,15 @@ export const createAiGatewayClient = ({
 			init.body = JSON.stringify(body);
 			headers["content-type"] = "application/json";
 		}
-		const res = await fetchImpl(`${base}${path}`, init);
+		let res;
+		try {
+			res = await fetchImpl(`${base}${path}`, init);
+		} catch (error) {
+			/* Node's fetch says only "fetch failed"; the reason is in error.cause. Name both. */
+			const cause = error?.cause;
+			const why = cause ? `${cause.code ?? ""} ${cause.message ?? ""}`.trim() : String(error?.message ?? error);
+			throw Object.assign(new Error(`the AI gateway at ${base} could not be reached: ${why}`), { code: "AI_GATEWAY_UNREACHABLE" });
+		}
 		const json = await res.json().catch(() => ({}));
 		if (!res.ok) {
 			const { error, ...details } = json ?? {};

package/config/databases.json

@@ -1,20 +0,0 @@
-{
-	"3": {
-		"host": "127.0.0.1",
-		"port": 5432,
-		"database": "studioa",
-		"user": "postgres",
-		"password": "M45t3rK3y",
-		"poolMax": 10,
-		"ssl": false
-	},
-	"4": {
-		"host": "127.0.0.1",
-		"port": 5432,
-		"database": "studiob",
-		"user": "postgres",
-		"password": "M45t3rK3y",
-		"poolMax": 10,
-		"ssl": false
-	}
-}

package/config/ext-oidc.json

@@ -1,7 +0,0 @@
-{
-  "google": {
-    "clientId": "19528327527-cda778568pel4uc7019bhee117p8t2ad.apps.googleusercontent.com",
-    "clientSecret": "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",
-    "redirectUri": "https://test.biz-a.id/auth/google/callback"
-  }
-}

package/config/secrets.json

@@ -1,27 +0,0 @@
-{
-  "supertail.ledger": {
-    "currentKeyId": "st_ledger_v1",
-    "keys": {
-      "st_ledger_v1": "CdgBjUShgx7t9Wo/dfSOOJAHjHOD5KwAlRi6xwDMEfs="
-    }
-  },
-  "supertail.session": "3jepiFkSV6HxlbCSWiGqYWpmfapYxLHeHY/YgxyFQ8Q=",
-  "ext.capability": {
-    "currentKeyId": "ext_v1",
-    "keys": {
-      "ext_v1": "f4PLkG2QLn6OFyv0IlqWhq3tlSGs2VAyaYDM4kDKLZ8="
-    }
-  },
-  "internal.principal": {
-    "currentKeyId": "ip_v1",
-    "keys": {
-      "ip_v1": "GsoRIpPG0D7c0q+AtmMNrtKpZ104Uv4/tfmLHtAtbIM="
-    }
-  },
-  "biza.ai.studiob": {
-    "currentKeyId": "ai_v1",
-    "keys": {
-      "ai_v1": "QxE6YiZdcjVRK1UbWGRMLuEgBKM3zFUte9euFldduZc="
-    }
-  }
-}