@fonoster/common 0.27.0 → 0.30.0

package/dist/assistants/sessionAssistantSchema.js

@@ -0,0 +1,112 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.sessionAssistantSchema = exports.sessionConversationSettingsSchema = exports.sessionLanguageModelSchema = void 0;
+/**
+ * Copyright (C) 2025 by Fonoster Inc (https://fonoster.com)
+ * http://github.com/fonoster/fonoster
+ *
+ * This file is part of Fonoster
+ *
+ * Licensed under the MIT License (the "License");
+ * you may not use this file except in compliance with
+ * the License. You may obtain a copy of the License at
+ *
+ *    https://opensource.org/licenses/MIT
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+const zod_1 = require("zod");
+const tools_1 = require("./tools");
+// The assistant config for the rebuilt Autopilot (rework-autopilot A8, A11, A12; tasks 5.1, 5.2,
+// 5.4). Strict: vendor credentials, vendor enums, VAD settings and the assistant webhook are
+// rejected with messages pointing to where they moved. It is the only assistant schema: the legacy
+// one was deleted after the cutover job converts stored assistants (rework-autopilot 8.2).
+const removed = (key, message) => zod_1.z
+    .any()
+    .optional()
+    .superRefine((value, ctx) => {
+    if (value !== undefined)
+        ctx.addIssue({
+            code: zod_1.z.ZodIssueCode.custom,
+            message: `${key}: ${message}`
+        });
+});
+exports.sessionLanguageModelSchema = zod_1.z
+    .object({
+    /** A catalog id such as "openai/gpt-4o-mini". */
+    model: zod_1.z
+        .string()
+        .regex(/^[a-z0-9-]+\/.+/, "model must be a catalog id like openai/gpt-4o-mini"),
+    temperature: zod_1.z.number().min(0).max(2).default(0.4),
+    maxTokens: zod_1.z.number().int().positive().default(400),
+    tools: zod_1.z.array(tools_1.toolSchema).default([]),
+    /** Documents for the knowledge port (same shape as before; wired by the operator). */
+    knowledgeBase: zod_1.z
+        .array(zod_1.z.object({
+        type: zod_1.z.enum(["s3"]),
+        title: zod_1.z.string(),
+        document: zod_1.z.string()
+    }))
+        .default([]),
+    provider: removed("provider", "use a catalog id in model (for example openai/gpt-4o-mini)"),
+    apiKey: removed("apiKey", "credentials come from the provider registry or workspace secrets"),
+    baseUrl: removed("baseUrl", "endpoints come from the provider registry")
+})
+    .strict();
+exports.sessionConversationSettingsSchema = zod_1.z
+    .object({
+    firstMessage: zod_1.z.string().optional(),
+    systemPrompt: zod_1.z.string(),
+    goodbyeMessage: zod_1.z.string(),
+    systemErrorMessage: zod_1.z.string(),
+    initialDtmf: zod_1.z
+        .string()
+        .regex(/^[0-9*#]+$/)
+        .optional(),
+    maxSessionDuration: zod_1.z
+        .number()
+        .int()
+        .positive()
+        .default(30 * 60 * 1000),
+    transferOptions: zod_1.z
+        .object({ phoneNumber: zod_1.z.string(), message: zod_1.z.string() })
+        .optional(),
+    idleOptions: zod_1.z
+        .object({
+        message: zod_1.z.string(),
+        timeout: zod_1.z.number().int().positive().default(30000),
+        maxTimeoutCount: zod_1.z.number().int().positive().default(2)
+    })
+        .optional(),
+    allowUserBargeIn: zod_1.z.boolean().default(true),
+    /**
+     * The turn-taking patience knob (TT-B5): sent to the gateway with listen.update so its Pacing
+     * policy waits less (low) or more (high) before turn.ended. Autopilot prepares a reply on
+     * turn.likely_ended at low and normal, and only on turn.ended at high.
+     */
+    patience: zod_1.z.enum(["low", "normal", "high"]).default("normal"),
+    /** Words to bias speech recognition toward (names, brands), sent with listen.update. */
+    hints: zod_1.z.array(zod_1.z.string().min(1)).max(100).optional(),
+    /** Played with play() while thinking; the reply preempts it (A9). */
+    filler: zod_1.z.object({ url: zod_1.z.string().url() }).optional(),
+    /** Catalog ids overriding the app's speech defaults on every speak. */
+    voice: zod_1.z.string().optional(),
+    language: zod_1.z.string().optional(),
+    vad: removed("vad", "turn detection moved to the gateway (turn-taking configuration)"),
+    maxSpeechWaitTimeout: removed("maxSpeechWaitTimeout", "turn detection moved to the gateway")
+})
+    .strict();
+exports.sessionAssistantSchema = zod_1.z
+    .object({
+    conversationSettings: exports.sessionConversationSettingsSchema,
+    languageModel: exports.sessionLanguageModelSchema,
+    /** Conversation eval cases, kept as they were (evaluated outside calls). */
+    testCases: zod_1.z.any().optional(),
+    eventsHook: removed("eventsHook", "assistant webhooks were retired; use workspace webhooks (conversation.ended → call.ended or call_record.sealed)"),
+    audioFilters: removed("audioFilters", "audio filters are part of the app's configuration")
+})
+    .strict();

package/dist/assistants/testCasesSchema.d.ts

@@ -24,13 +24,13 @@ declare const testCasesSchema: z.ZodObject<{
         model: z.ZodString;
         apiKey: z.ZodOptional<z.ZodString>;
     }, "strip", z.ZodTypeAny, {
+        model?: string;
         provider?: "openai";
         apiKey?: string;
-        model?: string;
     }, {
+        model?: string;
         provider?: "openai";
         apiKey?: string;
-        model?: string;
     }>;
     evalsSystemPrompt: z.ZodOptional<z.ZodString>;
     scenarios: z.ZodArray<z.ZodObject<{
@@ -166,9 +166,9 @@ declare const testCasesSchema: z.ZodObject<{
     }>, "many">;
 }, "strip", z.ZodTypeAny, {
     evalsLanguageModel?: {
+        model?: string;
         provider?: "openai";
         apiKey?: string;
-        model?: string;
     };
     evalsSystemPrompt?: string;
     scenarios?: {
@@ -196,9 +196,9 @@ declare const testCasesSchema: z.ZodObject<{
     }[];
 }, {
     evalsLanguageModel?: {
+        model?: string;
         provider?: "openai";
         apiKey?: string;
-        model?: string;
     };
     evalsSystemPrompt?: string;
     scenarios?: {

package/dist/{voice/Dial.d.ts → calls/index.d.ts}

@@ -16,12 +16,7 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-import { VerbRequest } from "./Verb";
-declare enum DialRecordDirection {
-    IN = "IN",
-    OUT = "OUT",
-    BOTH = "BOTH"
-}
+/** Progress of a dialed call, as the Calls API's trackCall reports it. */
 declare enum DialStatus {
     TRYING = "TRYING",
     CANCEL = "CANCEL",
@@ -31,11 +26,19 @@ declare enum DialStatus {
     NOANSWER = "NOANSWER",
     FAILED = "FAILED"
 }
-type DialOptions = {
-    timeout?: number;
-    recordDirection?: DialRecordDirection;
-};
-type DialRequest = VerbRequest & DialOptions & {
-    destination: string;
+/** Answering machine detection verdict (the amd classifier). */
+declare enum AmdStatus {
+    UNSPECIFIED = "AMD_STATUS_UNSPECIFIED",
+    HUMAN = "HUMAN",
+    MACHINE = "MACHINE",
+    VOICEMAIL = "VOICEMAIL",
+    IVR = "IVR",
+    UNKNOWN = "UNKNOWN"
+}
+type Amd = {
+    status: AmdStatus;
+    confidence: number;
+    detector: string;
+    latencyMs: number;
 };
-export { DialOptions, DialRecordDirection, DialRequest, DialStatus };
+export { Amd, AmdStatus, DialStatus };

package/dist/calls/index.js

@@ -0,0 +1,44 @@
+"use strict";
+/**
+ * Copyright (C) 2025 by Fonoster Inc (https://fonoster.com)
+ * http://github.com/fonoster/fonoster
+ *
+ * This file is part of Fonoster
+ *
+ * Licensed under the MIT License (the "License");
+ * you may not use this file except in compliance with
+ * the License. You may obtain a copy of the License at
+ *
+ *    https://opensource.org/licenses/MIT
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+// Call statuses shared by the Calls API, the SDK and the CLI. The verb and stream types of the
+// retired voice.proto are gone (cleanbreak CB-B1).
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DialStatus = exports.AmdStatus = void 0;
+/** Progress of a dialed call, as the Calls API's trackCall reports it. */
+var DialStatus;
+(function (DialStatus) {
+    DialStatus["TRYING"] = "TRYING";
+    DialStatus["CANCEL"] = "CANCEL";
+    DialStatus["ANSWER"] = "ANSWER";
+    DialStatus["BUSY"] = "BUSY";
+    DialStatus["PROGRESS"] = "PROGRESS";
+    DialStatus["NOANSWER"] = "NOANSWER";
+    DialStatus["FAILED"] = "FAILED";
+})(DialStatus || (exports.DialStatus = DialStatus = {}));
+/** Answering machine detection verdict (the amd classifier). */
+var AmdStatus;
+(function (AmdStatus) {
+    AmdStatus["UNSPECIFIED"] = "AMD_STATUS_UNSPECIFIED";
+    AmdStatus["HUMAN"] = "HUMAN";
+    AmdStatus["MACHINE"] = "MACHINE";
+    AmdStatus["VOICEMAIL"] = "VOICEMAIL";
+    AmdStatus["IVR"] = "IVR";
+    AmdStatus["UNKNOWN"] = "UNKNOWN";
+})(AmdStatus || (exports.AmdStatus = AmdStatus = {}));

package/dist/cellsecrets/index.d.ts

@@ -0,0 +1,91 @@
+/** Secret names: provider ids and credential refs (`deepgram`, `groq`, `openai`, `s3.secret`). */
+export declare const SECRET_NAME: RegExp;
+export type CellSecretsConfig = {
+    /** The encrypted file. */
+    file?: string;
+    /** A directory with one file per secret (a mounted Kubernetes Secret). */
+    dir?: string;
+    /** Environment variable with the file's passphrase (default FONOSTER_REGION_SECRETS_KEY). */
+    keyEnv?: string;
+    /** The passphrase itself (tests); prefer keyEnv. */
+    key?: string;
+};
+export declare const DEFAULT_SECRETS_KEY_ENV = "FONOSTER_REGION_SECRETS_KEY";
+export interface CellSecretStore {
+    get(name: string): string | undefined;
+    /** The names that are set, sorted. */
+    names(): string[];
+    set(name: string, value: string): void;
+    /** Returns whether the secret existed. */
+    delete(name: string): boolean;
+}
+export declare function assertSecretName(name: string): void;
+/** Writes a file atomically with mode 0600. */
+export declare function writePrivateFile(file: string, data: string | Buffer): void;
+/** One AES-256-GCM sealed JSON object `{name: value}` in a file. */
+export declare class EncryptedFileSecretStore implements CellSecretStore {
+    private readonly file;
+    private readonly passphrase;
+    private cache?;
+    private keys;
+    constructor(file: string, passphrase: string);
+    private key;
+    private read;
+    private write;
+    get(name: string): string;
+    names(): string[];
+    set(name: string, value: string): void;
+    delete(name: string): boolean;
+}
+/**
+ * One file per secret: a mounted Kubernetes Secret (keys are file names; `..data` and other
+ * dot-entries are Kubernetes' own). Trailing newlines are trimmed.
+ */
+export declare class DirectorySecretStore implements CellSecretStore {
+    private readonly dir;
+    constructor(dir: string);
+    get(name: string): string;
+    names(): string[];
+    set(name: string, value: string): void;
+    delete(name: string): boolean;
+}
+/** The store a config names (dir wins over file). */
+export declare function openCellSecrets(config: CellSecretsConfig, env?: Record<string, string | undefined>): CellSecretStore;
+/**
+ * The cell's secrets as a workspace key source (gateway Catalog, Autopilot): a private region
+ * serves one workspace, so the provider name alone picks the key. Read errors count as unset.
+ */
+export declare class CellSecretKeys {
+    private readonly store;
+    constructor(store: CellSecretStore);
+    get(_workspaceRef: string, providerId: string): Promise<string>;
+    /** By credentialRef first, then by the providers that use that ref. */
+    forCredentialRef(credentialRef: string, providers?: {
+        id: string;
+        credentialRef: string;
+    }[]): string | undefined;
+}
+/** What `NatsWorkspaceKeys` needs of a NATS connection (nats.js connections fit). */
+export interface KeyRequester {
+    request(subject: string, data: Uint8Array, options: {
+        timeout: number;
+    }): Promise<{
+        data: Uint8Array;
+    }>;
+}
+/** The cell-local subject the region agent answers (contract 6); it never crosses the link. */
+export declare const CELL_WORKSPACE_KEYS_SUBJECT = "cell.workspacekeys.get";
+/**
+ * A workspace's bring-your-own key in a public region (add-private-regions PR-20): asked of the
+ * region agent on the cell's NATS for each call, which asks the control plane over the region
+ * link. Never cached and never logged; undefined (the region's own key applies) when the
+ * workspace has none or the answer does not come within the timeout.
+ */
+export declare class NatsWorkspaceKeys {
+    private readonly requester;
+    private readonly timeoutMs;
+    /** Never cached: the gateway keeps no adapter built with these keys past the call's lookup. */
+    readonly cacheable = false;
+    constructor(requester: () => Promise<KeyRequester>, timeoutMs?: number);
+    get(workspaceRef: string, providerId: string): Promise<string | undefined>;
+}

package/dist/cellsecrets/index.js

@@ -0,0 +1,299 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NatsWorkspaceKeys = exports.CELL_WORKSPACE_KEYS_SUBJECT = exports.CellSecretKeys = exports.DirectorySecretStore = exports.EncryptedFileSecretStore = exports.DEFAULT_SECRETS_KEY_ENV = exports.SECRET_NAME = void 0;
+exports.assertSecretName = assertSecretName;
+exports.writePrivateFile = writePrivateFile;
+exports.openCellSecrets = openCellSecrets;
+/**
+ * Copyright (C) 2025 by Fonoster Inc (https://fonoster.com)
+ * http://github.com/fonoster/fonoster
+ *
+ * This file is part of Fonoster
+ *
+ * Licensed under the MIT License (the "License");
+ * you may not use this file except in compliance with
+ * the License. You may obtain a copy of the License at
+ *
+ *    https://opensource.org/licenses/MIT
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+const crypto_1 = require("crypto");
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+// The secret store of a private region's cell (add-private-regions PR-4): provider keys and other
+// secrets that never leave the cell. Two backends:
+//   - an encrypted file (Compose, bare metal): AES-256-GCM, key derived with scrypt from a
+//     passphrase in the environment (default FONOSTER_REGION_SECRETS_KEY);
+//   - a directory with one file per secret: a mounted Kubernetes Secret.
+// The gateway and the hosted Autopilot read it; `fonoster-region secrets` writes it. Values are
+// never logged; `names()` is what the region agent reports in heartbeats.
+/** Secret names: provider ids and credential refs (`deepgram`, `groq`, `openai`, `s3.secret`). */
+exports.SECRET_NAME = /^[a-z0-9][a-z0-9._-]{0,63}$/;
+exports.DEFAULT_SECRETS_KEY_ENV = "FONOSTER_REGION_SECRETS_KEY";
+function assertSecretName(name) {
+    if (!exports.SECRET_NAME.test(name))
+        throw new Error(`invalid secret name "${name}" (lowercase letters, digits, ".", "_" and "-"; up to 64)`);
+}
+/** Writes a file atomically with mode 0600. */
+function writePrivateFile(file, data) {
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    const tmp = `${file}.${process.pid}.${(0, crypto_1.randomBytes)(4).toString("hex")}.tmp`;
+    fs.writeFileSync(tmp, data, { mode: 0o600 });
+    fs.renameSync(tmp, file);
+}
+/** One AES-256-GCM sealed JSON object `{name: value}` in a file. */
+class EncryptedFileSecretStore {
+    constructor(file, passphrase) {
+        this.file = file;
+        this.passphrase = passphrase;
+        this.keys = new Map();
+        if (!passphrase)
+            throw new Error("the region secret store needs a key (passphrase)");
+    }
+    key(salt) {
+        const id = salt.toString("base64");
+        let k = this.keys.get(id);
+        if (!k) {
+            k = (0, crypto_1.scryptSync)(this.passphrase, salt, 32);
+            this.keys.set(id, k);
+        }
+        return k;
+    }
+    read() {
+        if (!fs.existsSync(this.file))
+            return {};
+        const mtimeMs = fs.statSync(this.file).mtimeMs;
+        if (this.cache && this.cache.mtimeMs === mtimeMs)
+            return this.cache.values;
+        const sealed = JSON.parse(fs.readFileSync(this.file, "utf8"));
+        const decipher = (0, crypto_1.createDecipheriv)("aes-256-gcm", this.key(Buffer.from(sealed.salt, "base64")), Buffer.from(sealed.iv, "base64"));
+        decipher.setAuthTag(Buffer.from(sealed.tag, "base64"));
+        let plain;
+        try {
+            plain = Buffer.concat([
+                decipher.update(Buffer.from(sealed.data, "base64")),
+                decipher.final()
+            ]);
+        }
+        catch (_a) {
+            throw new Error(`cannot decrypt ${this.file}: wrong key (check ${exports.DEFAULT_SECRETS_KEY_ENV})`);
+        }
+        const values = JSON.parse(plain.toString("utf8"));
+        this.cache = { mtimeMs, values };
+        return values;
+    }
+    write(values) {
+        const salt = (0, crypto_1.randomBytes)(16);
+        const iv = (0, crypto_1.randomBytes)(12);
+        const cipher = (0, crypto_1.createCipheriv)("aes-256-gcm", this.key(salt), iv);
+        const data = Buffer.concat([
+            cipher.update(Buffer.from(JSON.stringify(values), "utf8")),
+            cipher.final()
+        ]);
+        const sealed = {
+            v: 1,
+            salt: salt.toString("base64"),
+            iv: iv.toString("base64"),
+            tag: cipher.getAuthTag().toString("base64"),
+            data: data.toString("base64")
+        };
+        writePrivateFile(this.file, JSON.stringify(sealed));
+        this.cache = undefined;
+    }
+    get(name) {
+        return this.read()[name] || undefined;
+    }
+    names() {
+        return Object.keys(this.read()).sort();
+    }
+    set(name, value) {
+        assertSecretName(name);
+        if (!value)
+            throw new Error("empty secret value");
+        this.write(Object.assign(Object.assign({}, this.read()), { [name]: value }));
+    }
+    delete(name) {
+        const values = Object.assign({}, this.read());
+        if (!(name in values))
+            return false;
+        delete values[name];
+        this.write(values);
+        return true;
+    }
+}
+exports.EncryptedFileSecretStore = EncryptedFileSecretStore;
+/**
+ * One file per secret: a mounted Kubernetes Secret (keys are file names; `..data` and other
+ * dot-entries are Kubernetes' own). Trailing newlines are trimmed.
+ */
+class DirectorySecretStore {
+    constructor(dir) {
+        this.dir = dir;
+    }
+    get(name) {
+        if (!exports.SECRET_NAME.test(name))
+            return undefined;
+        const file = path.join(this.dir, name);
+        if (!fs.existsSync(file))
+            return undefined;
+        return fs.readFileSync(file, "utf8").replace(/\r?\n$/, "") || undefined;
+    }
+    names() {
+        if (!fs.existsSync(this.dir))
+            return [];
+        return fs
+            .readdirSync(this.dir)
+            .filter((n) => exports.SECRET_NAME.test(n))
+            .filter((n) => fs.statSync(path.join(this.dir, n)).isFile())
+            .sort();
+    }
+    set(name, value) {
+        assertSecretName(name);
+        if (!value)
+            throw new Error("empty secret value");
+        writePrivateFile(path.join(this.dir, name), value);
+    }
+    delete(name) {
+        if (!exports.SECRET_NAME.test(name))
+            return false;
+        const file = path.join(this.dir, name);
+        if (!fs.existsSync(file))
+            return false;
+        fs.rmSync(file);
+        return true;
+    }
+}
+exports.DirectorySecretStore = DirectorySecretStore;
+/** The store a config names (dir wins over file). */
+function openCellSecrets(config, env = process.env) {
+    var _a, _b, _c;
+    if (config.dir)
+        return new DirectorySecretStore(config.dir);
+    if (!config.file)
+        throw new Error("cellSecrets: set file or dir");
+    const key = (_a = config.key) !== null && _a !== void 0 ? _a : env[(_b = config.keyEnv) !== null && _b !== void 0 ? _b : exports.DEFAULT_SECRETS_KEY_ENV];
+    if (!key)
+        throw new Error(`cellSecrets: ${(_c = config.keyEnv) !== null && _c !== void 0 ? _c : exports.DEFAULT_SECRETS_KEY_ENV} is not set`);
+    return new EncryptedFileSecretStore(config.file, key);
+}
+/**
+ * The cell's secrets as a workspace key source (gateway Catalog, Autopilot): a private region
+ * serves one workspace, so the provider name alone picks the key. Read errors count as unset.
+ */
+class CellSecretKeys {
+    constructor(store) {
+        this.store = store;
+    }
+    get(_workspaceRef, providerId) {
+        return __awaiter(this, void 0, void 0, function* () {
+            try {
+                return this.store.get(providerId);
+            }
+            catch (_a) {
+                return undefined;
+            }
+        });
+    }
+    /** By credentialRef first, then by the providers that use that ref. */
+    forCredentialRef(credentialRef, providers = []) {
+        try {
+            const direct = exports.SECRET_NAME.test(credentialRef)
+                ? this.store.get(credentialRef)
+                : undefined;
+            if (direct)
+                return direct;
+            for (const p of providers.filter((x) => x.credentialRef === credentialRef))
+                if (exports.SECRET_NAME.test(p.id)) {
+                    const v = this.store.get(p.id);
+                    if (v)
+                        return v;
+                }
+        }
+        catch (_a) {
+            return undefined;
+        }
+        return undefined;
+    }
+}
+exports.CellSecretKeys = CellSecretKeys;
+/** The cell-local subject the region agent answers (contract 6); it never crosses the link. */
+exports.CELL_WORKSPACE_KEYS_SUBJECT = "cell.workspacekeys.get";
+/**
+ * A workspace's bring-your-own key in a public region (add-private-regions PR-20): asked of the
+ * region agent on the cell's NATS for each call, which asks the control plane over the region
+ * link. Never cached and never logged; undefined (the region's own key applies) when the
+ * workspace has none or the answer does not come within the timeout.
+ */
+class NatsWorkspaceKeys {
+    constructor(requester, timeoutMs = 2000) {
+        this.requester = requester;
+        this.timeoutMs = timeoutMs;
+        /** Never cached: the gateway keeps no adapter built with these keys past the call's lookup. */
+        this.cacheable = false;
+    }
+    get(workspaceRef, providerId) {
+        return __awaiter(this, void 0, void 0, function* () {
+            if (!workspaceRef || !providerId)
+                return undefined;
+            try {
+                const nc = yield this.requester();
+                const reply = yield nc.request(exports.CELL_WORKSPACE_KEYS_SUBJECT, Buffer.from(JSON.stringify({ workspaceRef, provider: providerId })), { timeout: this.timeoutMs });
+                const body = JSON.parse(Buffer.from(reply.data).toString("utf8"));
+                return typeof body.value === "string" && body.value
+                    ? body.value
+                    : undefined;
+            }
+            catch (_a) {
+                return undefined;
+            }
+        });
+    }
+}
+exports.NatsWorkspaceKeys = NatsWorkspaceKeys;

package/dist/config/cli/check.d.ts

@@ -0,0 +1,6 @@
+import { Io } from "./types";
+export type CheckOptions = {
+    dir: string;
+};
+/** Validates config/*.yaml, placeholders resolved from .env, against config/schemas/*.json (D5). */
+export declare function runCheck(options: CheckOptions, io: Io): number;