@capybara-hq/kernel 0.1.0-rc.0 → 0.1.0-rc.10

package/dist/log-loki.js

@@ -0,0 +1,145 @@
+const PUSH_PATH = "/loki/api/v1/push";
+const PUSH_TIMEOUT_MS = 10_000;
+/** A batch is pushed right away once it reaches this many records. */
+const BATCH_SIZE = 1_000;
+const ERROR_NOTE_INTERVAL_MS = 60_000;
+function pushUrl(url) {
+    const u = new URL(url);
+    if (!u.pathname.endsWith(PUSH_PATH))
+        u.pathname = `${u.pathname.replace(/\/+$/, "")}${PUSH_PATH}`;
+    return u;
+}
+/**
+ * Batches JSON log lines and POSTs them to Loki's push API (JSON body), one stream per level with
+ * the labels `{ job: "capybara", ...labels, role, level }`. Pushing never blocks or throws into the
+ * caller: a failed push drops its batch and is reported to `onError` at most once per minute; while
+ * Loki is down at most `maxBuffer` records are kept. The interval timer is unref'd.
+ */
+export function createLokiStream(opts) {
+    const url = pushUrl(opts.url);
+    const intervalMs = opts.intervalMs ?? 2_000;
+    const maxBuffer = opts.maxBuffer ?? 10_000;
+    const now = opts.now ?? Date.now;
+    const onError = opts.onError ?? ((m) => void process.stderr.write(`capybara: ${m}\n`));
+    // the marker keeps these pushes out of HTTP client traces (apps/capybara tracing.ts)
+    const headers = {
+        "content-type": "application/json",
+        "x-capybara-log-push": "1",
+    };
+    if (opts.username !== undefined || opts.password !== undefined) {
+        const token = Buffer.from(`${opts.username ?? ""}:${opts.password ?? ""}`).toString("base64");
+        headers.authorization = `Basic ${token}`;
+    }
+    const baseLabels = { job: "capybara", ...opts.labels, role: opts.role };
+    let buffer = [];
+    let dropped = 0;
+    let inFlight;
+    let timer;
+    let lastNote = Number.NEGATIVE_INFINITY;
+    let closed = false;
+    /** Reports at most once a minute; `message` names the Loki origin only (a URL may carry credentials). */
+    const report = (message) => {
+        const t = now();
+        if (t - lastNote < ERROR_NOTE_INTERVAL_MS)
+            return;
+        lastNote = t;
+        onError(`${message}; further Loki errors are not reported for a minute`);
+    };
+    const note = (reason) => report(`cannot push logs to Loki at ${url.origin} (${reason}); records are dropped until it recovers`);
+    const pushBatch = async (batch, lost) => {
+        const streams = new Map();
+        for (const e of batch) {
+            const values = streams.get(e.level) ?? [];
+            values.push([e.ns, e.line]);
+            streams.set(e.level, values);
+        }
+        const body = JSON.stringify({
+            streams: [...streams].map(([level, values]) => ({
+                stream: { ...baseLabels, level },
+                values,
+            })),
+        });
+        try {
+            const res = await fetch(url, {
+                method: "POST",
+                headers,
+                body,
+                signal: AbortSignal.timeout(PUSH_TIMEOUT_MS),
+            });
+            await res.body?.cancel();
+            if (!res.ok)
+                note(`HTTP ${res.status}`);
+            else if (lost > 0) {
+                report(`${lost} log records for Loki at ${url.origin} were dropped: the buffer was full`);
+            }
+        }
+        catch (e) {
+            note(e instanceof Error ? (e.cause instanceof Error ? e.cause.message : e.message) : "error");
+        }
+    };
+    /** Starts a push of the current buffer unless one is in flight. */
+    const kick = () => {
+        if (inFlight || buffer.length === 0)
+            return inFlight ?? Promise.resolve();
+        const batch = buffer;
+        const lost = dropped;
+        buffer = [];
+        dropped = 0;
+        inFlight = pushBatch(batch, lost).finally(() => {
+            inFlight = undefined;
+        });
+        return inFlight;
+    };
+    const ensureTimer = () => {
+        if (timer || closed)
+            return;
+        timer = setInterval(() => void kick(), intervalMs);
+        timer.unref();
+    };
+    return {
+        write(chunk) {
+            for (const line of chunk.split("\n")) {
+                if (line === "")
+                    continue;
+                let level = "info";
+                let ms = Date.now();
+                try {
+                    const rec = JSON.parse(line);
+                    if (typeof rec.level === "string")
+                        level = rec.level;
+                    if (typeof rec.time === "string") {
+                        const t = Date.parse(rec.time);
+                        if (!Number.isNaN(t))
+                            ms = t;
+                    }
+                }
+                catch {
+                    // not JSON: push it as is
+                }
+                buffer.push({ level, ns: `${BigInt(ms) * 1000000n}`, line });
+                if (buffer.length > maxBuffer) {
+                    buffer.shift();
+                    dropped++;
+                }
+            }
+            ensureTimer();
+            if (buffer.length >= BATCH_SIZE)
+                void kick();
+        },
+        async flush() {
+            while (inFlight || buffer.length > 0) {
+                if (inFlight)
+                    await inFlight;
+                else
+                    await kick();
+            }
+        },
+        async close() {
+            closed = true;
+            if (timer)
+                clearInterval(timer);
+            timer = undefined;
+            await this.flush();
+        },
+    };
+}

package/dist/log.d.ts

@@ -1,4 +1,5 @@
 import type { Logger } from "@capybara-hq/plugin-sdk";
+import { type LokiOptions } from "./log-loki.js";
 /** 日志级别，按严重程度递增。 */
 export declare const LOG_LEVELS: readonly ["debug", "info", "warn", "error"];
 /** 日志级别。 */
@@ -11,7 +12,7 @@ export interface KernelLogger extends Logger {
     setLevel(level: string): void;
     /**
      * 登记部署方（运维）给的密钥值：内核配置与插件部署级配置里的 secret 字段。此后日志消息与字段里出现这些值都替换为
-     * `[REDACTED]`（顶层的 `ts` / `level` 不打码）。字符串与数字（转成字符串）登记，布尔不登记；
+     * `[REDACTED]`（顶层的 `time` / `level` 不打码）。字符串与数字（转成字符串）登记，布尔不登记；
      * 数组与对象递归展开其中的标量；短于 4 个字符的值不登记（会误伤普通文本）。
      * 数值字段的字符串形式等于已登记值时同样打码。
      */
@@ -27,6 +28,13 @@ export interface KernelLogger extends Logger {
      * 报错说明）之前用。
      */
     redact(text: string): string;
+    /** Waits until buffered records reached every output (Loki); never rejects. Call before exit. */
+    flush(): Promise<void>;
+    /**
+     * A logger that adds `fields` to every record (e.g. `{ context: "RunWorker" }`); call fields cannot
+     * overwrite them. It shares everything else with this logger: level, secrets, outputs.
+     */
+    child(fields: Record<string, string>): KernelLogger;
 }
 /**
  * 用与 logger 相同的匹配器打码任意文本（工具结果等不经过日志的内容用）：展开规则同 `addOrgSecrets`
@@ -34,15 +42,50 @@ export interface KernelLogger extends Logger {
  * 不得小于匹配器的分桶前缀长度 4）。没有可用的值时原样返回。
  */
 export declare function createRedactor(values: readonly unknown[], minLength?: number): (s: string) => string;
-/**
- * 创建结构化 JSON logger：每条日志写一行 `{ ts, level, msg, ...fields }`。
- * 字段不能覆盖 ts / level / msg；Error 序列化为 name / message / stack；
- * 经 `addSecrets` 登记的部署方密钥在消息与字段的任何字符串里都被打码；经 `addOrgSecrets` 登记的组织来源密钥
- * 只在字段里打码，不动顶层 msg；顶层 ts / level 从不打码。
- * `opts.orgSecretCapacity` 为组织来源密钥集合的容量（测试用）；`opts.onMatcherBuild` 在每次重建匹配器时调用（测试用）。
- */
-export declare function createLogger(level?: string, opts?: {
+/** Console format: `pretty` (pino-pretty), `json`, or `auto` (pretty on a TTY). */
+export declare const LOG_FORMATS: readonly ["auto", "pretty", "json"];
+/** Console format. */
+export type LogFormat = (typeof LOG_FORMATS)[number];
+/** A minimal writable the console output goes to (`process.stdout` by default). */
+export interface LogOutput {
+    write(chunk: string): unknown;
+    /** A stream's `error` event (EPIPE when its reader is gone). */
+    on?(event: "error", listener: (err: unknown) => void): unknown;
+}
+/** Options of {@link createLogger}. */
+export interface LoggerOptions {
+    /**
+     * Receives every record as one JSON line (no trailing newline) instead of the console; the
+     * console format is ignored. Used by tests and embedders that collect records themselves.
+     */
     write?: (line: string) => void;
+    /** Console format; default `auto`. */
+    format?: LogFormat;
+    /** Console stream; default `process.stdout`. */
+    out?: LogOutput;
+    /** Whether the console is a terminal (picks `auto` and colors); default `process.stdout.isTTY`. */
+    isTTY?: boolean;
+    /**
+     * Pretty output in colors; default: `FORCE_COLOR` (set and not `0`) turns them on, `NO_COLOR` off,
+     * else a TTY. `pnpm dev:kernel` forces them, since its output goes through `tee`.
+     */
+    colors?: boolean;
+    /** Also push every record to Loki. */
+    loki?: LokiOptions;
+    /** Fields on every record (e.g. `role`); log calls cannot overwrite them. */
+    base?: Record<string, string>;
+    /** Capacity of the org secret set (tests). */
     orgSecretCapacity?: number;
+    /** Called on every matcher rebuild (tests). */
     onMatcherBuild?: () => void;
-}): KernelLogger;
+}
+/**
+ * Creates the kernel logger on pino. Each record is `{ time, level, msg, ...base, ...fields }` with
+ * `level` the label and `time` ISO 8601; fields cannot overwrite time / level / msg or the base
+ * fields; an Error becomes name / message / stack (and cause). Redaction happens before pino, so
+ * every output sees the same redacted record: deployment secrets (`addSecrets`) in msg and every
+ * field string, org secrets (`addOrgSecrets`) in fields only; level and time are never redacted.
+ * The console gets pino-pretty or JSON lines per `opts.format`; `opts.write` replaces the console
+ * with a JSON line sink.
+ */
+export declare function createLogger(level?: string, opts?: LoggerOptions): KernelLogger;

package/dist/log.js

@@ -1,9 +1,13 @@
+import { pino } from "pino";
+import { prettyFactory } from "pino-pretty";
 import { secretScalars } from "./config/fields.js";
+import { logContext } from "./log-context.js";
+import { createLokiStream } from "./log-loki.js";
 /** 日志级别，按严重程度递增。 */
 export const LOG_LEVELS = ["debug", "info", "warn", "error"];
 const LEVELS = LOG_LEVELS;
 const REDACTED = "[REDACTED]";
-const RESERVED = new Set(["ts", "level", "msg"]);
+const RESERVED = new Set(["time", "level", "msg"]);
 /** 部署方密钥的最短登记长度：过短的值打码会误伤普通文本。 */
 const MIN_SECRET_LEN = 4;
 /** 组织来源密钥的最短登记长度。 */
@@ -101,16 +105,110 @@ function expandSecret(value) {
     }
     return out;
 }
+/** Console format: `pretty` (pino-pretty), `json`, or `auto` (pretty on a TTY). */
+export const LOG_FORMATS = ["auto", "pretty", "json"];
+/** Fields shown in the pretty prefix instead of the lines below, in this order. */
+const PREFIX_FIELDS = ["traceId", "reqId", "queue", "jobId", "runId", "context", "plugin"];
 /**
- * 创建结构化 JSON logger：每条日志写一行 `{ ts, level, msg, ...fields }`。
- * 字段不能覆盖 ts / level / msg；Error 序列化为 name / message / stack；
- * 经 `addSecrets` 登记的部署方密钥在消息与字段的任何字符串里都被打码；经 `addOrgSecrets` 登记的组织来源密钥
- * 只在字段里打码，不动顶层 msg；顶层 ts / level 从不打码。
- * `opts.orgSecretCapacity` 为组织来源密钥集合的容量（测试用）；`opts.onMatcherBuild` 在每次重建匹配器时调用（测试用）。
+ * pino-pretty's message format, the octok layout:
+ * `[pid=…] - [traceId=…] [reqId=…] [context=…] msg`, each bracket only when present.
+ */
+function prettyMessage(log, messageKey) {
+    const parts = [`[pid=${process.pid}] -`];
+    for (const k of PREFIX_FIELDS) {
+        const v = log[k];
+        if (typeof v === "string" || typeof v === "number")
+            parts.push(`[${k}=${v}]`);
+    }
+    parts.push(String(log[messageKey] ?? ""));
+    return parts.join(" ");
+}
+/** The HTTP access record (`http/app.ts`) as one sentence: method, path, status and duration. */
+function foldAccessLine(log) {
+    if (log.msg !== "request" || typeof log.method !== "string" || typeof log.url !== "string") {
+        return log;
+    }
+    const { method, url, status, ms, ...rest } = log;
+    return { ...rest, msg: `${method} ${url} ${status} ${ms}ms` };
+}
+function colorsOn(opts, isTTY) {
+    if (opts.colors !== undefined)
+        return opts.colors;
+    const force = process.env.FORCE_COLOR;
+    if (force !== undefined && force !== "0")
+        return true;
+    if (process.env.NO_COLOR)
+        return false;
+    return isTTY;
+}
+function consoleStream(opts) {
+    if (opts.write) {
+        const write = opts.write;
+        // pino hands each record as one string ending in "\n"
+        return { write: (s) => write(s.endsWith("\n") ? s.slice(0, -1) : s) };
+    }
+    const format = opts.format ?? "auto";
+    if (!LOG_FORMATS.includes(format)) {
+        throw new Error(`invalid log.format "${format}" (expected ${LOG_FORMATS.join(", ")})`);
+    }
+    const target = opts.out ?? process.stdout;
+    // A console whose reader is gone (the `tee` of `pnpm dev:kernel` stopped by Ctrl-C, a closed
+    // pipe) fails every write with EPIPE. Unhandled, each failure is an uncaught exception the
+    // process guard logs, which writes again: an endless chain that starves the event loop. So the
+    // first stream error ends console output for good (Loki, when configured, still gets records).
+    let broken = false;
+    target.on?.("error", () => {
+        broken = true;
+    });
+    const out = {
+        write: (s) => {
+            if (!broken)
+                target.write(s);
+        },
+    };
+    const isTTY = opts.isTTY ?? process.stdout.isTTY === true;
+    const pretty = format === "pretty" || (format === "auto" && isTTY);
+    if (!pretty)
+        return { write: (s) => out.write(s) };
+    const colors = colorsOn(opts, isTTY);
+    // In process (no worker thread): pino-pretty formats each record synchronously. The layout follows
+    // octok's buildPinoPrettyOptions: full local time, colored level, the bracket prefix, and
+    // the remaining fields as indented `key: value` lines below the message (errors with their stack).
+    const format_ = prettyFactory({
+        colorize: colors,
+        colorizeObjects: colors,
+        singleLine: false,
+        translateTime: "SYS:standard",
+        ignore: ["pid", "hostname", "role", "spanId", ...PREFIX_FIELDS].join(","),
+        messageFormat: (log, messageKey) => prettyMessage(log, messageKey),
+    });
+    return {
+        write: (s) => {
+            let record;
+            try {
+                record = JSON.parse(s);
+            }
+            catch {
+                out.write(s);
+                return;
+            }
+            out.write(format_(foldAccessLine(record)));
+        },
+    };
+}
+/**
+ * Creates the kernel logger on pino. Each record is `{ time, level, msg, ...base, ...fields }` with
+ * `level` the label and `time` ISO 8601; fields cannot overwrite time / level / msg or the base
+ * fields; an Error becomes name / message / stack (and cause). Redaction happens before pino, so
+ * every output sees the same redacted record: deployment secrets (`addSecrets`) in msg and every
+ * field string, org secrets (`addOrgSecrets`) in fields only; level and time are never redacted.
+ * The console gets pino-pretty or JSON lines per `opts.format`; `opts.write` replaces the console
+ * with a JSON line sink.
  */
 export function createLogger(level = "info", opts = {}) {
     let current = parseLevel(level);
-    const write = opts.write ?? ((line) => process.stdout.write(`${line}\n`));
+    const base = opts.base ?? {};
+    const reserved = new Set([...RESERVED, ...Object.keys(base)]);
     const orgCapacity = opts.orgSecretCapacity ?? ORG_SECRET_CAPACITY;
     /** 部署方密钥（数量由配置决定，不淘汰）。 */
     const secrets = new Set();
@@ -136,12 +234,10 @@ export function createLogger(level = "info", opts = {}) {
         return deployMatcher(s);
     };
     const isSecret = (v) => secrets.has(v) || orgSecrets.has(v);
+    /** Redacts and serializes the fields to JSON (errors expanded, cycles cut). */
     const serialize = (entry) => {
         const seen = new WeakSet();
-        return JSON.stringify(entry, function (key, value) {
-            if (this === entry && RESERVED.has(key)) {
-                return key === "msg" && typeof value === "string" ? redactMsg(value) : value;
-            }
+        return JSON.stringify(entry, (_key, value) => {
             if (typeof value === "string")
                 return redact(value);
             if ((typeof value === "number" || typeof value === "bigint") && isSecret(String(value))) {
@@ -167,23 +263,44 @@ export function createLogger(level = "info", opts = {}) {
             return value;
         });
     };
+    const loki = opts.loki ? createLokiStream(opts.loki) : undefined;
+    const sink = pino({
+        level: "debug",
+        base,
+        messageKey: "msg",
+        timestamp: pino.stdTimeFunctions.isoTime,
+        formatters: { level: (label) => ({ level: label }) },
+        // request / job / trace fields of the current async context (log-context.ts)
+        mixin: () => ({ ...logContext() }),
+        // fields arrive already serialized: no pino serializers, no depth or size limits
+        serializers: { err: (e) => e },
+        depthLimit: Number.MAX_SAFE_INTEGER,
+        edgeLimit: Number.MAX_SAFE_INTEGER,
+    }, 
+    // level filtering is ours (setLevel); every stream takes everything that got this far
+    loki
+        ? pino.multistream([
+            { level: "debug", stream: consoleStream(opts) },
+            { level: "debug", stream: loki },
+        ])
+        : consoleStream(opts));
     const emit = (lvl, msg, fields) => {
         if (LEVELS.indexOf(lvl) < LEVELS.indexOf(current))
             return;
-        const entry = { ts: new Date().toISOString(), level: lvl, msg };
+        const entry = {};
         for (const [k, v] of Object.entries(fields ?? {}))
-            if (!RESERVED.has(k))
+            if (!reserved.has(k))
                 entry[k] = v;
-        let line;
+        let obj;
         try {
-            line = serialize(entry);
+            obj = JSON.parse(serialize(entry));
         }
         catch {
-            line = serialize({ ts: entry.ts, level: lvl, msg, logError: "unserializable fields" });
+            obj = { logError: "unserializable fields" };
         }
-        write(line);
+        sink[lvl](obj, redactMsg(msg));
     };
-    return {
+    const root = {
         debug: (msg, fields) => emit("debug", msg, fields),
         info: (msg, fields) => emit("info", msg, fields),
         warn: (msg, fields) => emit("warn", msg, fields),
@@ -192,6 +309,9 @@ export function createLogger(level = "info", opts = {}) {
             return current;
         },
         redact: (text) => redact(text),
+        flush: async () => {
+            await loki?.flush();
+        },
         setLevel(l) {
             current = parseLevel(l);
         },
@@ -225,5 +345,35 @@ export function createLogger(level = "info", opts = {}) {
                 }
             }
         },
+        // a method, so a wrapper of this logger (a test proxy) is the parent its children forward to
+        child(fields) {
+            return childLogger(this, fields);
+        },
+    };
+    return root;
+}
+/**
+ * A logger that adds `bound` to every record and forwards it to `parent`'s public methods (so a spy
+ * on the parent sees its children's records); call fields cannot overwrite the bound ones.
+ */
+function childLogger(parent, bound) {
+    const merged = (fields) => ({ ...fields, ...bound });
+    const child = {
+        debug: (msg, fields) => parent.debug(msg, merged(fields)),
+        info: (msg, fields) => parent.info(msg, merged(fields)),
+        warn: (msg, fields) => parent.warn(msg, merged(fields)),
+        error: (msg, fields) => parent.error(msg, merged(fields)),
+        get level() {
+            return parent.level;
+        },
+        setLevel: (level) => parent.setLevel(level),
+        addSecrets: (values) => parent.addSecrets(values),
+        addOrgSecrets: (values) => parent.addOrgSecrets(values),
+        redact: (text) => parent.redact(text),
+        flush: () => parent.flush(),
+        child(fields) {
+            return childLogger(this, fields);
+        },
     };
+    return child;
 }

package/dist/models/embeddings.d.ts

@@ -0,0 +1,82 @@
+import { type ExtensionEmbedRequest, type ExtensionEmbedResult, type ExtensionModelTarget, type ExtensionPermissions, type Logger } from "@capybara-hq/plugin-sdk";
+import { KernelConfigService } from "../infra/config/kernel-config.service.js";
+import { KernelDb } from "../infra/database/kernel-db.js";
+import { TransactionHost } from "../infra/database/transaction-host.js";
+import { KernelEvents } from "../infra/events/kernel-events.js";
+import { type HookRunner } from "../runtime/hook-calls.js";
+import { ProviderRegistry } from "../runtime/providers.js";
+import { ModelPurposesService } from "./purposes.js";
+/** An extension's `permissions.models` (what it declared, as approved in its manifest). */
+export type DeclaredModelPurposes = readonly NonNullable<ExtensionPermissions["models"]>[number][];
+/** Most texts one `ctx.models.embed` call may carry (the kernel splits them by `maxBatch`). */
+export declare const EMBED_MAX_INPUTS = 2048;
+/**
+ * The `ctx.models` broker for embeddings (model platform spec B §5.4). Every call:
+ * - accepts only a purpose the calling extension declared in `permissions.models` with
+ *   `kind: "embedding"` (`model.purpose_unknown` otherwise: the manifest is what was approved), for
+ *   an org that enabled the extension (`extension.not_enabled`);
+ * - resolves the org's effective target ({@link ModelPurposesService.resolve}: unmapped, or mapped
+ *   to a model the org cannot use, is `model.unconfigured`) and the model in the org's view, enabled
+ *   and of kind `embedding` ({@link ProviderRegistry.resolve}, bound to the org's effective config);
+ * - fires `model.request` once (`purpose: "embedding"`, every text of the call, no conversation
+ *   fields) through the host's hook registry before anything is sent; a policy denial (a deny, a
+ *   hook error or timeout, a policy extension not loaded here or without a valid config in the org)
+ *   writes one `hook.denied` audit row and rejects with `ApiError("model.hook_denied")` (403) whose
+ *   message is the one a denied run step fails with: no provider call, no usage row. A call with no input sends nothing
+ *   and fires nothing;
+ * - splits the input into batches of the model's `maxBatch`, calls the provider's `embed` once per
+ *   batch in order with the extension's signal (plus the request's own `signal`), each batch
+ *   limited by `models.embedTimeoutMs` (`ModelError("timeout")`), checks each result ({@link validateEmbedResult}: a
+ *   wrong count, dimension or a non-finite number is a `ModelError` of kind `server`), and
+ *   concatenates the vectors; no retries (an extension retries itself if it wants to);
+ * - writes one `model_usage` row (the sum of the batches' input tokens) and announces it after the
+ *   commit (`model_usage.recorded`: the usage reporter's `ModelUsageJobs` enqueues its
+ *   `usage.report` delivery; the usage sweep catches up a lost one). A call that fails after the
+ *   provider answered some batches (an invalid result, a later batch failing) still records their
+ *   input tokens before the error reaches the extension; one that fails before any answer records
+ *   nothing.
+ * Purpose params are not sent: an `embed` request carries none (`EmbedRequest`).
+ */
+export declare class ModelEmbeddings {
+    private readonly kdb;
+    readonly txHost: TransactionHost;
+    private readonly purposes;
+    private readonly providers;
+    /** `model_usage.recorded`: the usage reporter enqueues the row's delivery. */
+    private readonly events;
+    private readonly log;
+    /** `models.embedTimeoutMs` (hot). */
+    private readonly config;
+    constructor(kdb: KernelDb, txHost: TransactionHost, purposes: Pick<ModelPurposesService, "resolve">, providers: Pick<ProviderRegistry, "resolve">, 
+    /** `model_usage.recorded`: the usage reporter enqueues the row's delivery. */
+    events: Pick<KernelEvents, "emit">, log: Pick<Logger, "warn">, 
+    /** `models.embedTimeoutMs` (hot). */
+    config: Pick<KernelConfigService, "get">);
+    /** Refuses a purpose `plugin` did not declare with kind `embedding`, or an org it is off in. */
+    private admit;
+    /** The org's target for the purpose and the model bound to the org's config. */
+    private target;
+    /**
+     * One batch to the provider, limited by `models.embedTimeoutMs` (hot, read per call): at the limit
+     * the call's signal aborts and the batch fails with `ModelError("timeout")`, even when the
+     * provider ignores the signal (its late answer is dropped).
+     */
+    private callWithTimeout;
+    /**
+     * `ctx.models.embed` for `plugin` (its declared purposes), aborted by `signal`; `hooks` is the
+     * host's hook registry (`model.request`), absent only for a ctx built without a host (tests).
+     */
+    embed(plugin: string, declared: DeclaredModelPurposes, request: ExtensionEmbedRequest, signal: AbortSignal, hooks: HookRunner | undefined): Promise<ExtensionEmbedResult>;
+    /**
+     * `model.request` for an embed call (policy hooks may deny it). Rejects with the caller's abort
+     * reason when `signal` aborts while the hooks run (an abort is never a deny).
+     */
+    private checkHooks;
+    /** `ctx.models.describe` for `plugin`: null when the purpose maps to no model the org can use. */
+    describe(plugin: string, declared: DeclaredModelPurposes, req: {
+        orgId: string;
+        purpose: string;
+    }): Promise<ExtensionModelTarget | null>;
+    /** One `model_usage` row; its `usage.report` delivery is enqueued after the commit. */
+    private record;
+}