@cogenta/agents 0.2.1 → 0.5.0

package/dist/providers/store.js

@@ -0,0 +1,308 @@
+import { createCipheriv, createDecipheriv, randomBytes, scryptSync } from 'node:crypto';
+import { mkdir, readdir, readFile, rm, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { CogentaError } from '@cogenta/core';
+import { findProviderCatalogEntry } from './catalog.js';
+/**
+ * L22 task 1bis's "Providers" screen: which LLM providers this site has
+ * configured, each one's API key, and its default model — persisted so an
+ * operator can turn a provider on from the admin instead of only via
+ * `COGENTA_LLM_API_KEY`/`cogenta.config.mjs`'s single `llm` section
+ * (`@cogenta/core`'s `llmSchema`, unchanged and still the install-time
+ * default — `agents/orchestrator.ts` imports it as the first configured
+ * provider the first time this store is read, so an existing site loses
+ * nothing by upgrading).
+ *
+ * Fiche 56 widened `provider` from the closed 3-literal union to a free
+ * string (`registry.ts`'s `ProviderName`) so a catalog id (OpenRouter,
+ * DeepSeek, Qwen, GLM, …) or an operator-chosen custom id both fit. `upsert`
+ * is the write boundary that keeps this safe: `assertValidProviderId` rejects
+ * anything that is not a plain slug (this store builds a filename directly
+ * from `provider` — see `fileFor` — so a malformed id is a path-traversal
+ * risk, not merely an aesthetic one), and a name absent from the catalog
+ * must carry its own `baseUrl` or it could never resolve to a working client
+ * (`registry.ts`'s `buildClient` throws `PROVIDER_CUSTOM_BASE_URL_REQUIRED`
+ * for exactly that case — this store refuses the same shape earlier, at the
+ * point an operator can still fix it, rather than at first agent run).
+ *
+ * "Jamais affichée en clair une fois enregistrée" (the lot's own words, same
+ * discipline as `create-cogenta`'s masked key prompt) rules out storing the
+ * key as recoverable plaintext an API response could echo back — but an LLM
+ * call still needs the real key at request time, which rules out a one-way
+ * hash (`@cogenta/auth`'s `ApiKeyStore` model: fine for a bearer token this
+ * site itself verifies, useless for a key a *vendor* must see). This store
+ * therefore encrypts at rest (AES-256-GCM, `node:crypto`, zero new
+ * dependency — R9/R10) with a key derived from `COGENTA_AUTH_SIGNING_KEY`
+ * (the secret every real deployment already has, R7 — no second secret to
+ * generate, rotate or lose) via `scryptSync` with a purpose-specific salt,
+ * so the derived key is never the literal signing key reused across
+ * purposes. `list()`/`get()` return only a masked preview; the plaintext key
+ * is decrypted solely inside `resolveProviderRegistryConfig`, which the
+ * runtime hands straight to `createProviderRegistry` and never logs or
+ * returns over the wire (R7).
+ */
+/**
+ * A safe filename component and a reasonable admin-typed identifier: lower-
+ * case slug, 2-64 characters, no leading/trailing/doubled hyphen. Every
+ * catalog id in `catalog.ts` matches this by construction; the check exists
+ * for an operator-typed custom provider id.
+ */
+const PROVIDER_ID_PATTERN = /^[a-z0-9]+(?:-[a-z0-9]+){0,10}$/u;
+function assertValidProviderId(provider) {
+    if (PROVIDER_ID_PATTERN.test(provider) && provider.length <= 64)
+        return;
+    throw new CogentaError({
+        code: 'PROVIDER_ID_INVALID',
+        message: `"${provider}" is not a valid provider id.`,
+        hint: 'Use lowercase letters, digits and single hyphens only (e.g. "openrouter", "my-vllm-server").',
+    });
+}
+/** A provider id the catalog does not know needs its own `baseUrl` — otherwise it could never resolve to a working client (see `registry.ts`'s `buildClient`). */
+function assertResolvable(provider, baseUrl) {
+    if (findProviderCatalogEntry(provider) !== undefined)
+        return;
+    if (baseUrl !== undefined && baseUrl.trim().length > 0)
+        return;
+    throw new CogentaError({
+        code: 'PROVIDER_CUSTOM_BASE_URL_REQUIRED',
+        message: `"${provider}" is not a built-in provider — a custom provider needs a non-empty "baseUrl".`,
+        hint: 'Add a baseUrl pointing at an OpenAI-compatible chat completions endpoint, or use a catalog provider id.',
+    });
+}
+/** Bounds wide enough for any real model/deployment, narrow enough to catch a typo (a negative, a zero, or a value nobody would deliberately set) before it reaches an HTTP request. */
+const TUNING_BOUNDS = {
+    maxOutputTokens: { min: 1, max: 200_000 },
+    requestTimeoutMs: { min: 1000, max: 600_000 },
+    maxCorrectionAttempts: { min: 1, max: 10 },
+};
+function assertValidTuning(input) {
+    for (const [field, bounds] of Object.entries(TUNING_BOUNDS)) {
+        const value = input[field];
+        if (value === undefined)
+            continue;
+        if (!Number.isInteger(value) || value < bounds.min || value > bounds.max) {
+            throw new CogentaError({
+                code: 'PROVIDER_TUNING_INVALID',
+                message: `"${field}" must be a whole number between ${bounds.min} and ${bounds.max}.`,
+                hint: 'Leave it empty to use the built-in default for this field.',
+            });
+        }
+    }
+}
+const KEY_DERIVATION_SALT = 'cogenta-provider-secrets-v1';
+const ALGORITHM = 'aes-256-gcm';
+function deriveKey(signingKey) {
+    return scryptSync(signingKey, KEY_DERIVATION_SALT, 32);
+}
+function mask(apiKey) {
+    const tail = apiKey.slice(-4);
+    return tail.length === 0 ? '••••' : `••••${tail}`;
+}
+function providerNotConfigured(provider) {
+    return new CogentaError({
+        code: 'PROVIDER_NOT_CONFIGURED',
+        message: `No API key is saved for "${provider}".`,
+        hint: 'Configure it from the admin\'s "Providers" screen first.',
+    });
+}
+function toSummary(record) {
+    return {
+        provider: record.provider,
+        enabled: record.enabled,
+        model: record.model,
+        ...(record.baseUrl === undefined ? {} : { baseUrl: record.baseUrl }),
+        maskedKey: record.maskedKey,
+        updatedAt: record.updatedAt,
+        ...(record.maxOutputTokens === undefined ? {} : { maxOutputTokens: record.maxOutputTokens }),
+        ...(record.requestTimeoutMs === undefined ? {} : { requestTimeoutMs: record.requestTimeoutMs }),
+        ...(record.maxCorrectionAttempts === undefined
+            ? {}
+            : { maxCorrectionAttempts: record.maxCorrectionAttempts }),
+    };
+}
+/** One `<provider>.json` record per configured provider, under `options.dir` — the same one-file-per-record shape every other file store in this package uses (R1: no external service). */
+export function createFileProviderConfigStore(options) {
+    const now = options.now ?? (() => new Date());
+    const key = deriveKey(options.signingKey);
+    const ready = mkdir(options.dir, { recursive: true });
+    /**
+     * The one place every method that touches disk builds a path from
+     * `provider` — validating here, rather than only in `upsert`, is what
+     * closes the path-traversal gap `PATCH`/`DELETE /api/providers/:provider`
+     * would otherwise reopen: the router no longer allowlists `provider`
+     * against a fixed name list before calling `setEnabled`/`updateSettings`/
+     * `remove` (fiche 56 removed that gate to admit catalog and custom ids),
+     * so this store is the only remaining checkpoint before an attacker-
+     * controlled string like `../../agents/some-agent` reaches `readFile`/
+     * `writeFile`/`rm`. A caller of `get`/`decryptKey` on a malformed id gets
+     * the same `PROVIDER_ID_INVALID` an `upsert` would — never a silent
+     * "not found" that would let the check be bypassed by relying on ENOENT.
+     */
+    function fileFor(provider) {
+        assertValidProviderId(provider);
+        return join(options.dir, `${provider}.json`);
+    }
+    function encrypt(plaintext) {
+        const iv = randomBytes(12);
+        const cipher = createCipheriv(ALGORITHM, key, iv);
+        const ciphertext = Buffer.concat([cipher.update(plaintext, 'utf8'), cipher.final()]);
+        return {
+            iv: iv.toString('base64'),
+            authTag: cipher.getAuthTag().toString('base64'),
+            ciphertext: ciphertext.toString('base64'),
+        };
+    }
+    function decrypt(record) {
+        const decipher = createDecipheriv(ALGORITHM, key, Buffer.from(record.iv, 'base64'));
+        decipher.setAuthTag(Buffer.from(record.authTag, 'base64'));
+        const plaintext = Buffer.concat([
+            decipher.update(Buffer.from(record.ciphertext, 'base64')),
+            decipher.final(),
+        ]);
+        return plaintext.toString('utf8');
+    }
+    async function readRecord(provider) {
+        // `fileFor` (which validates `provider`) is called outside the try
+        // block on purpose: a `PROVIDER_ID_INVALID` it throws must propagate as
+        // itself, never be caught below and rewritten into a misleading
+        // "the file may be corrupted" `INTERNAL` error.
+        const path = fileFor(provider);
+        try {
+            const raw = await readFile(path, 'utf8');
+            return JSON.parse(raw);
+        }
+        catch (error) {
+            if (error.code === 'ENOENT')
+                return null;
+            throw new CogentaError({
+                code: 'INTERNAL',
+                message: `Could not read the saved configuration for provider "${provider}".`,
+                hint: 'The file may be corrupted; consider removing it and reconfiguring the provider.',
+                cause: error,
+            });
+        }
+    }
+    return {
+        async list() {
+            await ready;
+            const filenames = await readdir(options.dir).catch(() => []);
+            const records = [];
+            for (const filename of filenames) {
+                if (!filename.endsWith('.json'))
+                    continue;
+                const provider = filename.replace(/\.json$/u, '');
+                if (!PROVIDER_ID_PATTERN.test(provider))
+                    continue;
+                const record = await readRecord(provider);
+                if (record !== null)
+                    records.push(toSummary(record));
+            }
+            return records.sort((a, b) => a.provider.localeCompare(b.provider));
+        },
+        async get(provider) {
+            await ready;
+            const record = await readRecord(provider);
+            return record === null ? undefined : toSummary(record);
+        },
+        async upsert(input) {
+            await ready;
+            assertValidProviderId(input.provider);
+            assertResolvable(input.provider, input.baseUrl);
+            assertValidTuning(input);
+            const { iv, authTag, ciphertext } = encrypt(input.apiKey);
+            const record = {
+                provider: input.provider,
+                enabled: input.enabled ?? true,
+                model: input.model,
+                ...(input.baseUrl === undefined ? {} : { baseUrl: input.baseUrl }),
+                maskedKey: mask(input.apiKey),
+                iv,
+                authTag,
+                ciphertext,
+                updatedAt: now().toISOString(),
+                ...(input.maxOutputTokens === undefined ? {} : { maxOutputTokens: input.maxOutputTokens }),
+                ...(input.requestTimeoutMs === undefined
+                    ? {}
+                    : { requestTimeoutMs: input.requestTimeoutMs }),
+                ...(input.maxCorrectionAttempts === undefined
+                    ? {}
+                    : { maxCorrectionAttempts: input.maxCorrectionAttempts }),
+            };
+            await writeFile(fileFor(input.provider), JSON.stringify(record, null, 2), 'utf8');
+            return toSummary(record);
+        },
+        async setEnabled(provider, enabled) {
+            await ready;
+            const existing = await readRecord(provider);
+            if (existing === null)
+                throw providerNotConfigured(provider);
+            const updated = { ...existing, enabled, updatedAt: now().toISOString() };
+            await writeFile(fileFor(provider), JSON.stringify(updated, null, 2), 'utf8');
+            return toSummary(updated);
+        },
+        async remove(provider) {
+            await ready;
+            await rm(fileFor(provider), { force: true });
+        },
+        async updateSettings(provider, patch) {
+            await ready;
+            const existing = await readRecord(provider);
+            if (existing === null)
+                throw providerNotConfigured(provider);
+            const nextBaseUrl = patch.baseUrl !== undefined
+                ? patch.baseUrl
+                : existing.baseUrl === undefined
+                    ? undefined
+                    : existing.baseUrl;
+            assertResolvable(provider, nextBaseUrl);
+            assertValidTuning({
+                ...(patch.maxOutputTokens === undefined || patch.maxOutputTokens === null
+                    ? {}
+                    : { maxOutputTokens: patch.maxOutputTokens }),
+                ...(patch.requestTimeoutMs === undefined || patch.requestTimeoutMs === null
+                    ? {}
+                    : { requestTimeoutMs: patch.requestTimeoutMs }),
+                ...(patch.maxCorrectionAttempts === undefined || patch.maxCorrectionAttempts === null
+                    ? {}
+                    : { maxCorrectionAttempts: patch.maxCorrectionAttempts }),
+            });
+            // `null` clears a tuning field back to "use the built-in default";
+            // `undefined` leaves it exactly as saved — the reason this can't just
+            // be `patch.x ?? existing.x` the way `model` above is. Starting from
+            // `existing` stripped of all three (rather than the full record) and
+            // re-adding only what survives is what lets a `null` actually delete
+            // the key instead of merely being overwritten back to its old value.
+            const { maxOutputTokens: _existingMaxOutputTokens, requestTimeoutMs: _existingRequestTimeoutMs, maxCorrectionAttempts: _existingMaxCorrectionAttempts, ...existingWithoutTuning } = existing;
+            const nextMaxOutputTokens = patch.maxOutputTokens === undefined
+                ? existing.maxOutputTokens
+                : (patch.maxOutputTokens ?? undefined);
+            const nextRequestTimeoutMs = patch.requestTimeoutMs === undefined
+                ? existing.requestTimeoutMs
+                : (patch.requestTimeoutMs ?? undefined);
+            const nextMaxCorrectionAttempts = patch.maxCorrectionAttempts === undefined
+                ? existing.maxCorrectionAttempts
+                : (patch.maxCorrectionAttempts ?? undefined);
+            const updated = {
+                ...existingWithoutTuning,
+                model: patch.model ?? existing.model,
+                ...(nextBaseUrl === undefined ? {} : { baseUrl: nextBaseUrl }),
+                updatedAt: now().toISOString(),
+                ...(nextMaxOutputTokens === undefined ? {} : { maxOutputTokens: nextMaxOutputTokens }),
+                ...(nextRequestTimeoutMs === undefined ? {} : { requestTimeoutMs: nextRequestTimeoutMs }),
+                ...(nextMaxCorrectionAttempts === undefined
+                    ? {}
+                    : { maxCorrectionAttempts: nextMaxCorrectionAttempts }),
+            };
+            await writeFile(fileFor(provider), JSON.stringify(updated, null, 2), 'utf8');
+            return toSummary(updated);
+        },
+        async decryptKey(provider) {
+            await ready;
+            const record = await readRecord(provider);
+            if (record === null)
+                throw providerNotConfigured(provider);
+            return decrypt(record);
+        },
+    };
+}
+//# sourceMappingURL=store.js.map

package/dist/providers/store.js.map

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

package/dist/providers/tool-names.d.ts

@@ -0,0 +1,9 @@
+import type { ChatRequest } from './types.js';
+export declare function encodeToolName(name: string): string;
+/**
+ * The decoder for one request. Throws when two distinct tool names would
+ * collide on the wire (`a.b` next to `a__b`) — a misconfiguration worth a
+ * loud error, never a silently wrong tool.
+ */
+export declare function createToolNameDecoder(request: ChatRequest): (wire: string) => string;
+//# sourceMappingURL=tool-names.d.ts.map

package/dist/providers/tool-names.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-names.d.ts","sourceRoot":"","sources":["../../src/providers/tool-names.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAA;AA4B7C,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAEnD;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,WAAW,GAAG,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,CAmBpF"}

package/dist/providers/tool-names.js

@@ -0,0 +1,56 @@
+import { CogentaError } from '@cogenta/core';
+/**
+ * Contract C names its tools with a dot (`content.read`, `redirects.create`,
+ * `code.propose_patch`); every vendor wire format refuses that character in
+ * a function name — OpenAI-compatible endpoints (OpenAI, DeepSeek, Qwen,
+ * OpenRouter…) and Anthropic both enforce `^[a-zA-Z0-9_-]+$`, and Gemini
+ * has its own narrower rules. Found live: DeepSeek answered every agent run
+ * with `400 Invalid 'tools[0].function.name': string does not match
+ * pattern` before the request ever reached a model, and nothing in the
+ * catalog could have worked with a single tool declared.
+ *
+ * The fix lives here rather than in the tool names themselves: contract C
+ * is frozen, and a dot is the right separator for humans, the audit log
+ * and the permission taxonomy. Each adapter encodes on the way out and
+ * decodes on the way back, so no other layer ever sees a wire name.
+ *
+ * Encoding is deterministic (`.` and anything else outside the safe set →
+ * `__`), which is what lets an assistant message from earlier in the
+ * conversation — one that echoes a previous tool call by name — be encoded
+ * without any state. Decoding needs the reverse map, built from the request
+ * itself; a wire name the map does not know (a model inventing a tool) is
+ * returned unchanged, and the runtime's own registry refuses it downstream
+ * exactly as it would have before.
+ */
+const UNSAFE = /[^a-zA-Z0-9_-]/gu;
+export function encodeToolName(name) {
+    return name.replace(UNSAFE, '__');
+}
+/**
+ * The decoder for one request. Throws when two distinct tool names would
+ * collide on the wire (`a.b` next to `a__b`) — a misconfiguration worth a
+ * loud error, never a silently wrong tool.
+ */
+export function createToolNameDecoder(request) {
+    const byWire = new Map();
+    const register = (name) => {
+        const wire = encodeToolName(name);
+        const existing = byWire.get(wire);
+        if (existing !== undefined && existing !== name) {
+            throw new CogentaError({
+                code: 'PROVIDER_REQUEST_FAILED',
+                message: `Tool names "${existing}" and "${name}" are indistinguishable once encoded for the provider ("${wire}").`,
+                hint: 'Rename one of the two tools so they differ by more than characters the wire format refuses.',
+            });
+        }
+        byWire.set(wire, name);
+    };
+    for (const tool of request.tools ?? [])
+        register(tool.name);
+    for (const message of request.messages) {
+        for (const call of message.toolCalls ?? [])
+            register(call.name);
+    }
+    return (wire) => byWire.get(wire) ?? wire;
+}
+//# sourceMappingURL=tool-names.js.map

package/dist/providers/tool-names.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-names.js","sourceRoot":"","sources":["../../src/providers/tool-names.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,eAAe,CAAA;AAG5C;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,MAAM,MAAM,GAAG,kBAAkB,CAAA;AAEjC,MAAM,UAAU,cAAc,CAAC,IAAY;IACzC,OAAO,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,IAAI,CAAC,CAAA;AACnC,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,qBAAqB,CAAC,OAAoB;IACxD,MAAM,MAAM,GAAG,IAAI,GAAG,EAAkB,CAAA;IACxC,MAAM,QAAQ,GAAG,CAAC,IAAY,EAAQ,EAAE;QACtC,MAAM,IAAI,GAAG,cAAc,CAAC,IAAI,CAAC,CAAA;QACjC,MAAM,QAAQ,GAAG,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,CAAA;QACjC,IAAI,QAAQ,KAAK,SAAS,IAAI,QAAQ,KAAK,IAAI,EAAE,CAAC;YAChD,MAAM,IAAI,YAAY,CAAC;gBACrB,IAAI,EAAE,yBAAyB;gBAC/B,OAAO,EAAE,eAAe,QAAQ,UAAU,IAAI,2DAA2D,IAAI,KAAK;gBAClH,IAAI,EAAE,6FAA6F;aACpG,CAAC,CAAA;QACJ,CAAC;QACD,MAAM,CAAC,GAAG,CAAC,IAAI,EAAE,IAAI,CAAC,CAAA;IACxB,CAAC,CAAA;IACD,KAAK,MAAM,IAAI,IAAI,OAAO,CAAC,KAAK,IAAI,EAAE;QAAE,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;IAC3D,KAAK,MAAM,OAAO,IAAI,OAAO,CAAC,QAAQ,EAAE,CAAC;QACvC,KAAK,MAAM,IAAI,IAAI,OAAO,CAAC,SAAS,IAAI,EAAE;YAAE,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;IACjE,CAAC;IACD,OAAO,CAAC,IAAI,EAAE,EAAE,CAAC,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,IAAI,CAAA;AAC3C,CAAC"}

package/dist/providers/types.d.ts

@@ -13,10 +13,33 @@ export interface ProviderToolCall {
     readonly name: string;
     readonly input: Readonly<Record<string, unknown>>;
 }
+/** A plain-text segment of a multimodal message. */
+export interface ChatTextPart {
+    readonly type: 'text';
+    readonly text: string;
+}
+/**
+ * An inline image segment of a multimodal message. `data` is raw base64 —
+ * no `data:` URI prefix — so each adapter can format it however its own
+ * wire protocol wants it (a data URL for OpenAI, a bare base64 field for
+ * Anthropic and Google).
+ */
+export interface ChatImagePart {
+    readonly type: 'image';
+    readonly mediaType: string;
+    readonly data: string;
+}
+export type ChatContentPart = ChatTextPart | ChatImagePart;
 export interface ChatMessage {
     readonly role: ChatRole;
-    /** Absent (not empty-string) when a turn is tool calls with no accompanying text. */
-    readonly content?: string;
+    /**
+     * Absent (not empty-string) when a turn is tool calls with no accompanying
+     * text. A plain `string` is the common case and every existing caller
+     * keeps compiling and behaving identically; an array of `ChatContentPart`
+     * lets a caller attach images alongside text (e.g. the Theme Creator
+     * agent handing a model a screenshot a user uploaded).
+     */
+    readonly content?: string | readonly ChatContentPart[];
     /** Set on an `assistant` message that requested tool calls. */
     readonly toolCalls?: readonly ProviderToolCall[];
     /** Set on a `tool` message: which call this is the result of. */
@@ -35,7 +58,14 @@ export interface ChatRequest {
     readonly system?: string;
     readonly messages: readonly ChatMessage[];
     readonly tools?: readonly ProviderToolSpec[];
-    readonly maxTokens: number;
+    /**
+     * Absent lets the client fall back to its own configured
+     * `maxOutputTokens` (an admin-set property of the provider/model, not a
+     * literal a caller should be picking) — see `ProviderClient.maxOutputTokens`.
+     * A caller only sets this for a genuine, call-specific reason to differ
+     * from that default.
+     */
+    readonly maxTokens?: number;
     readonly temperature?: number;
 }
 export type StopReason = 'end_turn' | 'tool_use' | 'max_tokens' | 'stop_sequence';
@@ -58,6 +88,60 @@ export interface ChatOptions {
 export interface ProviderClient {
     readonly name: string;
     readonly model: string;
+    /**
+     * Whether this client can accept a `ChatImagePart` in a message's content.
+     * Absent means "unknown, assume no" — a caller building a multimodal
+     * message should check this before attaching an image, and degrade
+     * (text-only, with an explicit note) when it is not `true`.
+     */
+    readonly supportsVision?: boolean;
+    /**
+     * The completion budget every call through this client defaults to when
+     * a request does not set its own `maxTokens` — a property of *which
+     * model this is*, not of any one call site. A reasoning-tier model can
+     * spend thousands of tokens "thinking" before it ever writes a visible
+     * answer, and that reasoning counts against this same budget; a plain
+     * instruct model needs far less. This is why it lives on the provider
+     * (admin-configurable from `/admin/providers`, `resolve.ts` resolves it
+     * from `ProviderConfigStore`), not as a constant scattered across every
+     * caller — a real, reproduced bug (`docs`/changeset history: DeepSeek's
+     * `deepseek-v4-flash` hitting `finish_reason: "length"` with empty
+     * content at a too-low hardcoded ceiling) is exactly what a per-call
+     * hardcoded number cannot adapt to.
+     *
+     * **Always a concrete number, never `undefined`** — fiche feedback: this
+     * used to be optional, with the site-wide floor a resolved adapter falls
+     * back to (when an admin never set a per-provider override) living as a
+     * TypeScript constant (`FALLBACK_MAX_OUTPUT_TOKENS`), invisible and
+     * unreachable from the admin. That floor is now itself a real site
+     * setting (`assistant.defaultMaxOutputTokens`, `SITE_SETTINGS_REGISTRY`
+     * in `@cogenta/schema`) a resolved adapter
+     * (`createAnthropicClient`/`createOpenAiClient`/`createGoogleClient`)
+     * always merges in before ever returning a client — so a caller never
+     * needs its own `?? literal`, and the type now says so.
+     */
+    readonly maxOutputTokens: number;
+    /**
+     * How many times a generate-validate-correct loop (skin generation, brief
+     * analysis, content-model/demo-content proposals, the base-theme choice)
+     * retries this client before giving up. Same reasoning as
+     * `maxOutputTokens`, site-wide floor included:
+     * `assistant.defaultMaxCorrectionAttempts` — always a concrete number.
+     */
+    readonly maxCorrectionAttempts: number;
+    /**
+     * How long a single HTTP call to this provider is allowed to run before
+     * being aborted — both the raw request timeout each adapter applies via
+     * `requestSignalWithTimeout`, and the per-model-call timeout the LangGraph
+     * agent loop (`runtime/loop.ts`) enforces around `chat()`. A slower
+     * (often reasoning-tier) model genuinely needs more wall-clock time, not
+     * just more tokens; a fixed timeout picked without knowing which model an
+     * admin configured is the same class of mistake as a fixed token budget.
+     * Site-wide floor: `assistant.defaultRequestTimeoutSeconds` — always a
+     * concrete number, in milliseconds here (the setting itself is seconds,
+     * matching what the admin form shows).
+     */
+    readonly requestTimeoutMs: number;
     chat(request: ChatRequest, options?: ChatOptions): Promise<ChatResponse>;
 }
 //# sourceMappingURL=types.d.ts.map

package/dist/providers/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/providers/types.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,MAAM,MAAM,QAAQ,GAAG,MAAM,GAAG,WAAW,GAAG,MAAM,CAAA;AAEpD,qFAAqF;AACrF,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;IACnB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,KAAK,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAA;CAClD;AAED,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAA;IACvB,qFAAqF;IACrF,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAA;IACzB,+DAA+D;IAC/D,QAAQ,CAAC,SAAS,CAAC,EAAE,SAAS,gBAAgB,EAAE,CAAA;IAChD,iEAAiE;IACjE,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAA;IAC5B,0FAA0F;IAC1F,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;CAC3B;AAED,oJAAoJ;AACpJ,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;IAC5B,QAAQ,CAAC,WAAW,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAA;CACxD;AAED,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,QAAQ,EAAE,SAAS,WAAW,EAAE,CAAA;IACzC,QAAQ,CAAC,KAAK,CAAC,EAAE,SAAS,gBAAgB,EAAE,CAAA;IAC5C,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAA;CAC9B;AAED,MAAM,MAAM,UAAU,GAAG,UAAU,GAAG,UAAU,GAAG,YAAY,GAAG,eAAe,CAAA;AAEjF,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;IAC5B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAA;CAC9B;AAED,MAAM,WAAW,YAAY;IAC3B,0EAA0E;IAC1E,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAA;IAC/B,QAAQ,CAAC,SAAS,EAAE,SAAS,gBAAgB,EAAE,CAAA;IAC/C,QAAQ,CAAC,UAAU,EAAE,UAAU,CAAA;IAC/B,QAAQ,CAAC,KAAK,EAAE,UAAU,CAAA;CAC3B;AAED,MAAM,WAAW,WAAW;IAC1B,yHAAyH;IACzH,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAA;CAC9B;AAED,wHAAwH;AACxH,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,IAAI,CAAC,OAAO,EAAE,WAAW,EAAE,OAAO,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,YAAY,CAAC,CAAA;CACzE"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/providers/types.ts"],"names":[],"mappings":"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"}

package/dist/rag/reference-documents/ingest.d.ts

@@ -0,0 +1,22 @@
+import type { ExtractedDocument } from '../../documents/extract-text.js';
+import type { EmbeddingProvider } from '../embeddings/types.js';
+import type { VectorStore } from '../vector/types.js';
+export interface ReferenceDocumentIngestOptions {
+    readonly store: VectorStore;
+    readonly embeddings: EmbeddingProvider;
+    readonly siteId: string;
+}
+/**
+ * Chunks, embeds and stores one uploaded reference document under the
+ * reserved pseudo-collection (`types.ts`). `documentId` is the
+ * `ReferenceDocumentStore` row's own id — reusing it as the vector
+ * `entryId` is what lets `removeReferenceDocument` and a re-upload address
+ * exactly the chunks this document produced, the same way a content entry's
+ * id already does for `withVectorIndexing`.
+ */
+export declare function ingestReferenceDocument(document: Pick<ExtractedDocument, 'filename' | 'text'>, documentId: string, options: ReferenceDocumentIngestOptions): Promise<{
+    readonly chunkCount: number;
+}>;
+/** Removes every chunk a document produced — an upload's own undo, and what a delete from the admin screen calls. */
+export declare function removeReferenceDocumentVectors(store: VectorStore, siteId: string, documentId: string): Promise<void>;
+//# sourceMappingURL=ingest.d.ts.map

package/dist/rag/reference-documents/ingest.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ingest.d.ts","sourceRoot":"","sources":["../../../src/rag/reference-documents/ingest.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,iCAAiC,CAAA;AAGxE,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAA;AAC/D,OAAO,KAAK,EAAgB,WAAW,EAAE,MAAM,oBAAoB,CAAA;AA4BnE,MAAM,WAAW,8BAA8B;IAC7C,QAAQ,CAAC,KAAK,EAAE,WAAW,CAAA;IAC3B,QAAQ,CAAC,UAAU,EAAE,iBAAiB,CAAA;IACtC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CACxB;AAED;;;;;;;GAOG;AACH,wBAAsB,uBAAuB,CAC3C,QAAQ,EAAE,IAAI,CAAC,iBAAiB,EAAE,UAAU,GAAG,MAAM,CAAC,EACtD,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,8BAA8B,GACtC,OAAO,CAAC;IAAE,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;CAAE,CAAC,CA8B1C;AAED,qHAAqH;AACrH,wBAAsB,8BAA8B,CAClD,KAAK,EAAE,WAAW,EAClB,MAAM,EAAE,MAAM,EACd,UAAU,EAAE,MAAM,GACjB,OAAO,CAAC,IAAI,CAAC,CAMf"}

package/dist/rag/reference-documents/ingest.js

@@ -0,0 +1,69 @@
+import { chunkDocument } from '../chunking/chunk-document.js';
+import { REFERENCE_DOCUMENT_COLLECTION, REFERENCE_DOCUMENT_LOCALE, REFERENCE_DOCUMENT_STATUS, } from './types.js';
+/**
+ * The one real user of `chunkDocument` (L18 task 15) against an actual
+ * multi-chunk document — `withVectorIndexing`'s own `recordFor` deliberately
+ * uses one chunk per entry instead (see that file's comment: real chunking
+ * "is a piece of work of its own"). A reference document has no blocks to
+ * read, only the flat string `extractDocumentText` already produced, so this
+ * is that piece of work, scoped to exactly what an uploaded document needs:
+ * paragraphs standing in for blocks, a blank line standing in for the
+ * boundary between them, and nothing claiming to be a heading (a plain-text
+ * or a PDF extraction has no reliable way to tell one from a paragraph, so
+ * claiming otherwise would just fabricate section boundaries `chunkDocument`
+ * would then treat as if a human had marked them).
+ */
+function paragraphsOf(text) {
+    return text
+        .split(/\n{2,}/u)
+        .map((paragraph) => paragraph.trim())
+        .filter((paragraph) => paragraph.length > 0)
+        .map((paragraph, index) => ({ id: String(index), text: paragraph }));
+}
+/**
+ * Chunks, embeds and stores one uploaded reference document under the
+ * reserved pseudo-collection (`types.ts`). `documentId` is the
+ * `ReferenceDocumentStore` row's own id — reusing it as the vector
+ * `entryId` is what lets `removeReferenceDocument` and a re-upload address
+ * exactly the chunks this document produced, the same way a content entry's
+ * id already does for `withVectorIndexing`.
+ */
+export async function ingestReferenceDocument(document, documentId, options) {
+    const blocks = paragraphsOf(document.text);
+    if (blocks.length === 0)
+        return { chunkCount: 0 };
+    const chunks = chunkDocument({
+        documentId,
+        title: document.filename,
+        blocks,
+    });
+    if (chunks.length === 0)
+        return { chunkCount: 0 };
+    const vectors = await options.embeddings.embed(chunks.map((chunk) => chunk.text));
+    const records = [];
+    chunks.forEach((chunk, index) => {
+        const vector = vectors[index];
+        if (vector === undefined)
+            return;
+        records.push({
+            siteId: options.siteId,
+            collection: REFERENCE_DOCUMENT_COLLECTION,
+            entryId: documentId,
+            locale: REFERENCE_DOCUMENT_LOCALE,
+            status: REFERENCE_DOCUMENT_STATUS,
+            chunk,
+            vector,
+        });
+    });
+    await options.store.upsert(records);
+    return { chunkCount: records.length };
+}
+/** Removes every chunk a document produced — an upload's own undo, and what a delete from the admin screen calls. */
+export async function removeReferenceDocumentVectors(store, siteId, documentId) {
+    await store.removeEntries({
+        siteId,
+        collection: REFERENCE_DOCUMENT_COLLECTION,
+        entryIds: [documentId],
+    });
+}
+//# sourceMappingURL=ingest.js.map

package/dist/rag/reference-documents/ingest.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ingest.js","sourceRoot":"","sources":["../../../src/rag/reference-documents/ingest.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,aAAa,EAAE,MAAM,+BAA+B,CAAA;AAI7D,OAAO,EACL,6BAA6B,EAC7B,yBAAyB,EACzB,yBAAyB,GAC1B,MAAM,YAAY,CAAA;AAEnB;;;;;;;;;;;;GAYG;AACH,SAAS,YAAY,CAAC,IAAY;IAChC,OAAO,IAAI;SACR,KAAK,CAAC,SAAS,CAAC;SAChB,GAAG,CAAC,CAAC,SAAS,EAAE,EAAE,CAAC,SAAS,CAAC,IAAI,EAAE,CAAC;SACpC,MAAM,CAAC,CAAC,SAAS,EAAE,EAAE,CAAC,SAAS,CAAC,MAAM,GAAG,CAAC,CAAC;SAC3C,GAAG,CAAC,CAAC,SAAS,EAAE,KAAK,EAAE,EAAE,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,CAAC,KAAK,CAAC,EAAE,IAAI,EAAE,SAAS,EAAE,CAAC,CAAC,CAAA;AACxE,CAAC;AAQD;;;;;;;GAOG;AACH,MAAM,CAAC,KAAK,UAAU,uBAAuB,CAC3C,QAAsD,EACtD,UAAkB,EAClB,OAAuC;IAEvC,MAAM,MAAM,GAAG,YAAY,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAA;IAC1C,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,EAAE,UAAU,EAAE,CAAC,EAAE,CAAA;IAEjD,MAAM,MAAM,GAAG,aAAa,CAAC;QAC3B,UAAU;QACV,KAAK,EAAE,QAAQ,CAAC,QAAQ;QACxB,MAAM;KACP,CAAC,CAAA;IACF,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,EAAE,UAAU,EAAE,CAAC,EAAE,CAAA;IAEjD,MAAM,OAAO,GAAG,MAAM,OAAO,CAAC,UAAU,CAAC,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAA;IAEjF,MAAM,OAAO,GAAmB,EAAE,CAAA;IAClC,MAAM,CAAC,OAAO,CAAC,CAAC,KAAK,EAAE,KAAK,EAAE,EAAE;QAC9B,MAAM,MAAM,GAAG,OAAO,CAAC,KAAK,CAAC,CAAA;QAC7B,IAAI,MAAM,KAAK,SAAS;YAAE,OAAM;QAChC,OAAO,CAAC,IAAI,CAAC;YACX,MAAM,EAAE,OAAO,CAAC,MAAM;YACtB,UAAU,EAAE,6BAA6B;YACzC,OAAO,EAAE,UAAU;YACnB,MAAM,EAAE,yBAAyB;YACjC,MAAM,EAAE,yBAAyB;YACjC,KAAK;YACL,MAAM;SACP,CAAC,CAAA;IACJ,CAAC,CAAC,CAAA;IAEF,MAAM,OAAO,CAAC,KAAK,CAAC,MAAM,CAAC,OAAO,CAAC,CAAA;IACnC,OAAO,EAAE,UAAU,EAAE,OAAO,CAAC,MAAM,EAAE,CAAA;AACvC,CAAC;AAED,qHAAqH;AACrH,MAAM,CAAC,KAAK,UAAU,8BAA8B,CAClD,KAAkB,EAClB,MAAc,EACd,UAAkB;IAElB,MAAM,KAAK,CAAC,aAAa,CAAC;QACxB,MAAM;QACN,UAAU,EAAE,6BAA6B;QACzC,QAAQ,EAAE,CAAC,UAAU,CAAC;KACvB,CAAC,CAAA;AACJ,CAAC"}