charness 3.1.0 → 3.3.0

package/dist/stt/sttInstallReporter.js

@@ -0,0 +1,57 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createSttInstallMessageReporter = createSttInstallMessageReporter;
+exports.createSttInstallLogReporter = createSttInstallLogReporter;
+exports.createSttInstallMessagePorts = createSttInstallMessagePorts;
+const sessionKey_1 = require("../sessionKey");
+const sttScreenPlan_1 = require("./sttScreenPlan");
+/**
+ * @description Keep ONE message up to date with a running install. It edits `existing` (a message the caller
+ * already posted — the `/stt` confirm screen), else the one `state.json` remembers for THIS topic, else posts one
+ * on the first report, and remembers its id together with the "enable on done" flag. The END of the job is not
+ * reported here: the finisher turns the message into the outcome (with its buttons) and forgets it, so a job that
+ * outlives the bot is finished the same way by whoever re-attaches.
+ */
+function createSttInstallMessageReporter(ports, key, existing) {
+    const threadKey = (0, sessionKey_1.keyToString)(key);
+    const startedAtMs = ports.nowMs();
+    const remembered = ports.getState().getSttInstallProgressMessage();
+    const rememberedHere = remembered?.threadKey === threadKey ? remembered : null;
+    const shouldEnableOnDone = (existing ?? rememberedHere)?.shouldEnableOnDone === true;
+    let messageId = existing?.messageId ?? rememberedHere?.messageId ?? null;
+    let persistedId = rememberedHere?.messageId ?? null;
+    const report = async (progress) => {
+        if (progress.phase === 'done' || progress.phase === 'failed')
+            return;
+        const text = (0, sttScreenPlan_1.buildSttInstallProgressText)(progress, (ports.nowMs() - startedAtMs) / 1000, ports.translateFor(key));
+        const isEdited = messageId !== null && (await ports.editThreadMessage(key, messageId, text));
+        if (!isEdited)
+            messageId = await ports.replyToThread(key, text);
+        if (messageId !== null && messageId !== persistedId) {
+            await ports.getState().setSttInstallProgressMessage({ threadKey, messageId, ...(shouldEnableOnDone ? { shouldEnableOnDone } : {}) });
+            persistedId = messageId;
+        }
+    };
+    return { report, getMessageId: () => messageId };
+}
+/** @description The reporter for an install nobody is watching in a chat: one `[STT] install: …` line per phase change. */
+function createSttInstallLogReporter(log) {
+    let lastPhase = '';
+    return (progress) => {
+        if (progress.phase === lastPhase)
+            return;
+        lastPhase = progress.phase;
+        log((0, sttScreenPlan_1.formatSttInstallLogLine)(progress));
+    };
+}
+/** @description The ports of {@link createSttInstallMessageReporter} over the bot's topic helpers; `translate` is `t(…)`. */
+function createSttInstallMessagePorts(core, translate) {
+    return {
+        getState: core.getState,
+        replyToThread: (key, text) => core.replyToThread(key, text),
+        editThreadMessage: (key, messageId, text) => core.editThreadMessage(key, messageId, text),
+        translateFor: (key) => (code, vars) => core.withThreadLocale(key, () => translate(code, vars)),
+        nowMs: () => Date.now(),
+    };
+}
+//# sourceMappingURL=sttInstallReporter.js.map

package/dist/stt/sttInstallReporter.js.map

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

package/dist/stt/sttRuntime.d.ts

@@ -0,0 +1,35 @@
+import { type ResolvedSttSettings } from './sttSettings';
+import { type SttOwnerContext, type SttSidecarOwner } from './sttSidecarOwner';
+/**
+ * @description The voice settings as the running bot sees them: `stt.json` re-read when it changes, resolved
+ * against what the local engine's lifecycle says RIGHT NOW (installed? installing? marked unhealthy? has an
+ * owner?), with a change in what is wrong logged once as `[STT] …`. Built over injected dependencies so `bot.ts`
+ * (which a test cannot import) only wires it.
+ */
+export interface SttRuntimeDeps {
+    getDataDir: () => string;
+    getConfigPath: () => string;
+    owner: Pick<SttSidecarOwner, 'ensure' | 'checkIsUnhealthy'>;
+    getOwnerContext: () => SttOwnerContext | null;
+    /** The sinks for the `[STT]` lines: info (the migration) and problems (what is wrong with the settings). */
+    logInfo: (line: string) => void;
+    logProblem: (line: string) => void;
+    /**
+     * Called when `stt.json` CHANGED (a hand edit or a `/stt` save) and now names an enabled local engine that is
+     * not installed — the bot installs it by itself. Not called at boot (the boot step starts that install, with
+     * its progress message) and never per voice note, so a failed install is not retried by every voice.
+     */
+    onNeedsAutoInstall?: () => void;
+    /** Seams for tests; default to the real install checks. */
+    checkIsConfigOnContainerDisk?: (configPath: string) => boolean;
+    checkIsInstalled?: (dataDir: string) => boolean;
+    checkIsInstalling?: (dataDir: string) => boolean;
+}
+export interface SttRuntime {
+    /** The chain in effect now (re-reads the file when its stamp changed). */
+    getResolved: () => ResolvedSttSettings;
+    /** Boot: move the old env keys into `stt.json` once, then report the first state. */
+    init: () => void;
+}
+export declare function createSttRuntime(deps: SttRuntimeDeps): SttRuntime;
+//# sourceMappingURL=sttRuntime.d.ts.map

package/dist/stt/sttRuntime.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sttRuntime.d.ts","sourceRoot":"","sources":["../../src/stt/sttRuntime.ts"],"names":[],"mappings":"AACA,OAAO,EAML,KAAK,mBAAmB,EAGzB,MAAM,eAAe,CAAC;AAEvB,OAAO,EAEL,KAAK,eAAe,EACpB,KAAK,eAAe,EACrB,MAAM,mBAAmB,CAAC;AAE3B;;;;;GAKG;AAEH,MAAM,WAAW,cAAc;IAC7B,UAAU,EAAE,MAAM,MAAM,CAAC;IACzB,aAAa,EAAE,MAAM,MAAM,CAAC;IAC5B,KAAK,EAAE,IAAI,CAAC,eAAe,EAAE,QAAQ,GAAG,kBAAkB,CAAC,CAAC;IAC5D,eAAe,EAAE,MAAM,eAAe,GAAG,IAAI,CAAC;IAC9C,4GAA4G;IAC5G,OAAO,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAChC,UAAU,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IACnC;;;;OAIG;IACH,kBAAkB,CAAC,EAAE,MAAM,IAAI,CAAC;IAChC,2DAA2D;IAC3D,4BAA4B,CAAC,EAAE,CAAC,UAAU,EAAE,MAAM,KAAK,OAAO,CAAC;IAC/D,gBAAgB,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC;IAChD,iBAAiB,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC;CAClD;AAED,MAAM,WAAW,UAAU;IACzB,0EAA0E;IAC1E,WAAW,EAAE,MAAM,mBAAmB,CAAC;IACvC,qFAAqF;IACrF,IAAI,EAAE,MAAM,IAAI,CAAC;CAClB;AAED,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,cAAc,GAAG,UAAU,CA8DjE"}

package/dist/stt/sttRuntime.js

@@ -0,0 +1,73 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createSttRuntime = createSttRuntime;
+const configDirFile_1 = require("../configDirFile");
+const sttSettings_1 = require("./sttSettings");
+const sttInstall_1 = require("./sttInstall");
+const sttSidecarOwner_1 = require("./sttSidecarOwner");
+function createSttRuntime(deps) {
+    const checkIsInstalled = deps.checkIsInstalled ?? sttInstall_1.isGigaamInstalled;
+    const checkIsInstalling = deps.checkIsInstalling ?? sttInstall_1.isGigaamInstalling;
+    const checkIsConfigOnContainerDisk = deps.checkIsConfigOnContainerDisk ?? configDirFile_1.checkIsConfigFileOnContainerDisk;
+    /** The `[STT]` lines last logged, so an unchanged state is reported once, not per voice note. */
+    let lastReport = '';
+    /** The load the last resolve saw: the cache hands back the SAME object until the file changes. */
+    let lastLoad = null;
+    function resolveNow(isInit) {
+        const load = (0, sttSettings_1.loadSttConfig)(deps.getConfigPath());
+        const dataDir = deps.getDataDir();
+        const facts = {
+            isGigaamInstalled: checkIsInstalled(dataDir),
+            isGigaamInstalling: checkIsInstalling(dataDir),
+            isGigaamUnhealthy: deps.owner.checkIsUnhealthy(),
+            hasOwnerContext: deps.getOwnerContext() !== null,
+        };
+        // The process settings of THIS resolve: a start (or an adoption) is judged against them.
+        const localEngineSettings = (load.config ?? (0, sttSettings_1.createEmptySttConfig)()).gigaam;
+        const resolved = (0, sttSettings_1.resolveSttSettings)(load, facts, {
+            getGigaamEndpoint: async () => (0, sttSidecarOwner_1.getSttSidecarTranscriptionEndpoint)(await deps.owner.ensure(localEngineSettings)),
+        });
+        const report = (0, sttSettings_1.getSttReportLines)(resolved).join('\n');
+        if (report !== lastReport) {
+            lastReport = report;
+            if (report)
+                deps.logProblem(report);
+        }
+        const isChanged = load !== lastLoad;
+        lastLoad = load;
+        if (isChanged && !isInit && resolved.needsAutoInstall)
+            deps.onNeedsAutoInstall?.();
+        return resolved;
+    }
+    /**
+     * Said once, at boot: a settings file that cannot be kept loses every /stt edit — a read-only or missing mount
+     * (the write check), or a container's own disk (writable, so the write check is quiet, but a new container starts
+     * empty and would migrate the old env keys again).
+     */
+    function reportStorageProblem(configPath) {
+        const writeBlock = (0, configDirFile_1.getConfigFileWriteBlock)(configPath);
+        if (writeBlock !== null) {
+            deps.logProblem(`[STT] ${configPath} cannot be written (${writeBlock}): changes made in /stt will not be kept — make its directory writable`);
+        }
+        else if (checkIsConfigOnContainerDisk(configPath)) {
+            deps.logProblem(`[STT] ${configPath} is on this container's own disk, not on a mount: changes made in /stt are lost when the container is re-created — mount its directory (SETUP.md, Run with Docker)`);
+        }
+    }
+    return {
+        getResolved: () => resolveNow(false),
+        init() {
+            const configPath = deps.getConfigPath();
+            const migration = (0, sttSettings_1.migrateLegacySttKeys)(configPath);
+            if (migration.status === 'migrated') {
+                deps.logInfo(`[STT] moved ${migration.engineNames.join(' + ')} from the environment into ${configPath}`);
+            }
+            else if (migration.status === 'writeFailed') {
+                deps.logProblem(`[STT] could not write ${configPath} (${migration.error}): voice input stays off until it can be written`);
+            }
+            if (migration.status !== 'writeFailed')
+                reportStorageProblem(configPath);
+            resolveNow(true);
+        },
+    };
+}
+//# sourceMappingURL=sttRuntime.js.map

package/dist/stt/sttRuntime.js.map

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

package/dist/stt/sttScreenPlan.d.ts

@@ -0,0 +1,193 @@
+import type { SttInstallProgress } from './sttInstall';
+import { type ResolvedSttSettings, type SttConfigFile, type SttEngineSetting } from './sttSettings';
+import type { SttSidecarStatus } from './sttSidecarOwner';
+/**
+ * @description What the voice-settings messages say, as pure functions over data — the Telegram side
+ * (`connectors/telegram/commands/stt.ts`) only renders and sends them. `translate` is the topic's `t(...)`, so
+ * tests pass a stand-in that echoes the key and variables.
+ */
+export type SttTranslate = (code: string, vars?: Record<string, string | number>) => string;
+/** @description `1:05` — minutes and zero-padded seconds. */
+export declare function formatSttElapsed(elapsedSeconds: number): string;
+/** @description The phase line of a RUNNING install (`downloading the model 120/216 MB…`). */
+export declare function getSttInstallPhaseLine(progress: SttInstallProgress, translate: SttTranslate): string;
+/**
+ * @description The text of the install message for one progress report: while it runs, a header with the elapsed
+ * time over the phase line (`downloading the model 120/216 MB…`); at the end only the outcome — ready, or the
+ * error with the last log lines.
+ */
+export declare function buildSttInstallProgressText(progress: SttInstallProgress, elapsedSeconds: number, translate: SttTranslate): string;
+/** @description One log line per phase change of an install nobody watches in a chat (`[STT] install: …`). */
+export declare function formatSttInstallLogLine(progress: SttInstallProgress): string;
+/** @name SttScreenInput @description Everything a `/stt` screen shows, gathered by the command module. */
+export interface SttScreenInput {
+    resolved: ResolvedSttSettings;
+    configPath: string;
+    isLocalInstalled: boolean;
+    /** The install job's last report while one runs (or null when not installing). */
+    installing: SttInstallProgress | null;
+    sidecar: SttSidecarStatus;
+    hasOwnerContext: boolean;
+}
+export type SttLocalStatus = {
+    state: 'notInstalled';
+} | {
+    state: 'installing';
+    progress: SttInstallProgress;
+} | {
+    state: 'noOwner';
+} | {
+    state: 'unhealthy';
+    until: number;
+}
+/** `busyRequests` unknown: the process is alive but was too busy to answer /health. */
+ | {
+    state: 'running';
+    busyRequests?: number;
+} | {
+    state: 'ready';
+};
+/** @description The one line the local engine's state boils down to; installing and not installed outrank the process state. */
+export declare function getSttLocalStatus(input: SttScreenInput): SttLocalStatus;
+/** @description The content hash `/stt` bakes into every callback: a hand edit of the file makes old keyboards stale. */
+export declare function computeSttRevision(config: SttConfigFile): string;
+export declare const sttCallbackMaxBytes = 64;
+/** Every `/stt` button; registered once with `bot.action`. */
+export declare const sttCallbackRe: RegExp;
+export type SttAction = 'oe' | 'up' | 'dn' | 'us' | 'tm' | 'tb' | 'tp' | 'ky' | 'ra' | 'rd' | 'ad' | 'an' | 'lg' | 'ls' | 'im' | 'is' | 'wm' | 'ws' | 'rt' | 'ec' | 'ei' | 'er' | 'ip' | 'fa' | 'fd' | 'ku' | 'bk' | 'cl' | 'cn';
+export interface ParsedSttCallback {
+    action: SttAction;
+    args: string[];
+    revision: string;
+}
+export declare function buildSttCallback(action: SttAction, args: ReadonlyArray<string | number>, revision: string): string;
+/** @description The parts of a `/stt` callback, or `null` for anything that is not one. */
+export declare function parseSttCallback(data: string): ParsedSttCallback | null;
+export interface SttButton {
+    text: string;
+    data: string;
+}
+export interface SttScreen {
+    text: string;
+    rows: SttButton[][];
+}
+export type SttScreenId = {
+    id: 'main';
+} | {
+    id: 'card';
+    engineId: string;
+} | {
+    id: 'timeout';
+    engineId: string;
+} | {
+    id: 'add';
+} | {
+    id: 'language';
+} | {
+    id: 'idle';
+    engineId: string;
+} | {
+    id: 'workers';
+    engineId: string;
+}
+/** `engineId`: the local engine's card the confirmation was reached from (Cancel returns there); absent: from the add menu. */
+ | {
+    id: 'enableConfirm';
+    engineId?: string;
+} | {
+    id: 'removeEngineConfirm';
+    engineId: string;
+} | {
+    id: 'removeFilesConfirm';
+    engineId: string;
+} | {
+    id: 'keyChoice';
+};
+/** @description An engine's name as the screens say it: translated for the local one, the host for a custom server. */
+export declare function getSttEngineName(engine: SttEngineSetting, translate: SttTranslate): string;
+/**
+ * @description The screen for `screen`, or `null` when it names something that is gone (an engine removed by a
+ * hand edit): the caller falls back to the main screen. `notice` is a one-line result of the tap that led here.
+ */
+export declare function buildSttScreen(screen: SttScreenId, input: SttScreenInput, translate: SttTranslate, notice?: string): SttScreen | null;
+/** @description The one-button keyboard under a pasted-input prompt. */
+export declare function buildSttCancelRow(translate: SttTranslate, revision: string): SttButton[][];
+export type SttInputStep = 'url' | 'key';
+export type SttInputDecision = {
+    outcome: 'accept';
+    value: string;
+} | {
+    outcome: 'retry';
+    hint: 'invalidUrl' | 'invalidKey';
+}
+/** The message may carry a secret (a login inside the address): it is deleted, then the step re-arms. */
+ | {
+    outcome: 'retryAndDelete';
+    hint: 'urlHasCredentials';
+};
+/**
+ * @description What to do with the text typed at an armed `/stt` step. A key that cannot be one (spaces,
+ * non-Latin-1, too short or long) stays VISIBLE — it is not a secret — and the step re-arms; a plausible key is
+ * accepted and the caller deletes the message at once.
+ */
+export declare function decideSttInput(step: SttInputStep, text: string): SttInputDecision;
+/** A one-line result shown on the screen the tap leads to (or as the callback toast). */
+export interface SttNotice {
+    code: string;
+    vars?: Record<string, string | number>;
+}
+/** Which kind of key paste a tap arms. */
+export type SttKeyTarget = {
+    kind: 'engine';
+    engineId: string;
+} | {
+    kind: 'newKeyed';
+    engineKind: 'groq' | 'openai';
+} | {
+    kind: 'newUrl';
+    url: string;
+};
+export type SttEffect = 'install' | 'attachInstall' | 'removeFiles' | 'resetGuard' | 'close';
+export type SttActionOutcome = 
+/** The keyboard is out of date (the file changed, or the engine is gone): say so and re-render the main screen. */
+{
+    kind: 'stale';
+} | {
+    kind: 'show';
+    screen: SttScreenId;
+} | {
+    kind: 'save';
+    config: SttConfigFile;
+    screen: SttScreenId;
+    notice?: SttNotice;
+} | {
+    kind: 'armKey';
+    target: SttKeyTarget;
+} | {
+    kind: 'armUrl';
+} | {
+    kind: 'cancelInput';
+}
+/**
+ * `screen`: where the tap leaves the user when the effect does not take them elsewhere — the card a «try again» stays
+ * on, the card a refused file removal shows again (default: the main screen).
+ */
+ | {
+    kind: 'effect';
+    effect: SttEffect;
+    screen?: SttScreenId;
+};
+export interface SttReducerContext {
+    config: SttConfigFile;
+    isLocalInstalled: boolean;
+    isLocalInstalling: boolean;
+    /** The address typed at the custom-URL step, waiting for "does it need a key?". */
+    pendingUrl: string | null;
+}
+/**
+ * @description What a `/stt` tap does, decided from the callback and the current settings alone — no Telegram, no
+ * disk: a screen to show, a config to save, an input to arm, or an effect to run. A revision that is not the
+ * file's current one is `stale` for every tap that could change something.
+ */
+export declare function reduceSttAction(parsed: ParsedSttCallback, context: SttReducerContext): SttActionOutcome;
+//# sourceMappingURL=sttScreenPlan.d.ts.map

package/dist/stt/sttScreenPlan.d.ts.map

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