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

package/dist/conversations/titles.js

@@ -1,11 +1,30 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
 import { isModelError, } from "@capybara-hq/plugin-sdk";
-import { Queue, Worker } from "bullmq";
+import { getQueueToken } from "@nestjs/bullmq";
+import { Inject, Injectable, Module } from "@nestjs/common";
 import { sql } from "kysely";
+import { ExtensionsModule } from "../extensions/extensions.module.js";
+import { ExtensionHost } from "../extensions/host.js";
 import { audit } from "../identity/audit.js";
-import { PurposeAttemptError } from "../models/purposes.js";
+import { KernelDb } from "../infra/database/kernel-db.js";
+import { TransactionHost } from "../infra/database/transaction-host.js";
+import { Transactional } from "../infra/database/transactional.decorator.js";
+import { QueueModule } from "../infra/queue/queue.module.js";
+import { KERNEL_LOGGER } from "../infra/tokens.js";
+import { ModelsModule } from "../models/models.module.js";
+import { ModelPurposesService, PurposeAttemptError } from "../models/purposes.js";
 import { fireObserve, hookDeniedAudit, hookDeniedEvent, hookRequestOf, } from "../runtime/hook-calls.js";
-import { bullConnection } from "../runtime/run-queue.js";
+import { UsageReporter, UsageReportModule } from "../runtime/usage-report.js";
 import { HIDDEN_FORMAT_RE } from "../text.js";
+import { EventLog, EventLogModule } from "./event-log.js";
 import { typedInvocation } from "./events.js";
 /**
  * Model-generated conversation titles (UI refresh B, spec §5.1 "Titles").
@@ -28,10 +47,17 @@ export const titleJobId = (conversationId, attempt) => `title-${conversationId}-
 export const TITLE_MAX_ATTEMPTS = 3;
 /** Output cap of the title call. */
 export const TITLE_MAX_OUTPUT_TOKENS = 32;
-/** The longest generated title (characters); a rename has the same limit. */
+/** The longest title a person can give by renaming (characters). */
 export const TITLE_MAX_CHARS = 120;
+/** The longest generated title by display width (CJK and emoji count 2: ~24 CJK / 48 Latin). */
+export const TITLE_MAX_WIDTH = 48;
 /** Each side of the excerpt is cut to this many characters. */
 export const TITLE_EXCERPT_CHARS = 1000;
+/**
+ * Parameters of the title call where the target model declares them and the `title` purpose does
+ * not set them: no thinking, so the {@link TITLE_MAX_OUTPUT_TOKENS} budget goes to the title.
+ */
+export const TITLE_PARAM_DEFAULTS = { thinking: "off" };
 /** Time limit of one title call. */
 export const TITLE_TIMEOUT_MS = 60_000;
 /** How far into the log the excerpt is looked for (events). */
@@ -39,8 +65,13 @@ const EXCERPT_SCAN_EVENTS = 2000;
 const PAGE = 500;
 const JOB = "title";
 /** The system prompt of the title call (model-facing, English). */
-export const TITLE_PROMPT = "Write a title of at most 8 words for this conversation, in the language the user writes in. " +
+export const TITLE_PROMPT = "Write a short topic of what the user asked, not the reply, as a title for this conversation, " +
+    "in the language the user writes in. Use a noun phrase of at most 6 words or about 16 CJK " +
+    "characters: no sentence, no list. " +
     "Reply with the title only, no quotes or punctuation at the end.";
+const WIDE_RE = /[\u1100-\u115F\u2E80-\u303E\u3041-\u33FF\u3400-\u4DBF\u4E00-\u9FFF\uA000-\uA4CF\uAC00-\uD7A3\uF900-\uFAFF\uFE30-\uFE6F\uFF00-\uFF60\uFFE0-\uFFE6]|\p{Extended_Pictographic}|[\u{20000}-\u{3FFFD}]/u;
+/** Display width of a character: 2 for CJK, fullwidth forms and emoji, else 1. */
+const widthOf = (ch) => (WIDE_RE.test(ch) ? 2 : 1);
 const cut = (s) => {
     const cps = Array.from(s);
     return cps.length <= TITLE_EXCERPT_CHARS ? s : `${cps.slice(0, TITLE_EXCERPT_CHARS).join("")}…`;
@@ -51,8 +82,8 @@ export function titleExcerpt(firstUser, firstReply) {
 }
 /**
  * The title from a model reply: the first non-empty line, without control or format characters,
- * wrapping quotes or trailing punctuation, at most {@link TITLE_MAX_CHARS} characters; null when
- * nothing is left.
+ * wrapping quotes or trailing punctuation, at most {@link TITLE_MAX_WIDTH} display width (cut on a
+ * character boundary, no ellipsis); null when nothing is left.
  */
 export function cleanTitle(reply) {
     const line = reply
@@ -67,10 +98,16 @@ export function cleanTitle(reply) {
         .replace(/^["'“”‘’「」《》`*]+|["'“”‘’「」《》`*]+$/gu, "")
         .replace(/[.。!！?？,，;；:：]+$/u, "")
         .trim();
-    // counted in code points, so a cut never splits a surrogate pair
-    const cps = Array.from(t);
-    if (cps.length > TITLE_MAX_CHARS)
-        t = cps.slice(0, TITLE_MAX_CHARS).join("").trimEnd();
+    // cut by display width over code points, so a cut never splits a surrogate pair
+    let width = 0;
+    let out = "";
+    for (const ch of t) {
+        width += widthOf(ch);
+        if (width > TITLE_MAX_WIDTH)
+            break;
+        out += ch;
+    }
+    t = out.trimEnd();
     return t === "" ? null : t;
 }
 const textOf = (content) => content.flatMap((b) => (b.type === "text" ? [b.text] : [])).join("");
@@ -185,6 +222,8 @@ export async function runTitleJob(d, conversationId, attempt) {
             maxOutputTokens: TITLE_MAX_OUTPUT_TOKENS,
         }, signal, {
             ...(fallback && { fallback: { model: fallback, params: {} } }),
+            // a thinking model spends the small output budget on thinking and returns no text
+            paramDefaults: TITLE_PARAM_DEFAULTS,
             beforeSend: async (target, request) => {
                 await checkTitleHooks(d, scope, target, request, signal);
                 sent = { ...target, at: Date.now() };
@@ -227,23 +266,15 @@ export async function runTitleJob(d, conversationId, attempt) {
     if (sent && d.hooks)
         observeTitle(d, scope, sent, out, null, signal);
     const title = cleanTitle(textOf(out.content));
-    const { written, usage } = await d.db.transaction().execute(async (t) => {
-        // Append first: it locks the conversation row FOR UPDATE before this transaction touches it.
-        // Updating the title first held the row FOR NO KEY UPDATE, which lets in another
-        // transaction's foreign key check (FOR KEY SHARE, e.g. inserting an approval); the append's
-        // FOR UPDATE then waited for that one while it waited for the title row: 40P01
-        const [ev] = await d.eventLog.append(conversationId, [usageEvent(attempt, out)], t);
-        const row = title === null
-            ? undefined
-            : await t
-                .updateTable("conversations")
-                .set({ title, title_source: "generated" })
-                .where("id", "=", conversationId)
-                .where("title_source", "is", null)
-                .returning("id")
-                .executeTakeFirst();
-        return { written: row !== undefined, usage: ev };
-    });
+    if (title === null) {
+        d.log.warn("conversation title call returned no title", {
+            conversationId,
+            attempt,
+            stopReason: out.stopReason,
+            outputTokens: out.usage.outputTokens,
+        });
+    }
+    const { written, usage } = await d.writes.writeResult(conversationId, attempt, out, title);
     if (usage) {
         await d.eventLog.notify(conversationId, usage.seq);
         void d.usageReport?.enqueue(conversationId, usage.seq);
@@ -312,7 +343,7 @@ async function checkTitleHooks(d, scope, target, request, signal) {
     };
     const entry = hookDeniedAudit(site, hookDeniedEvent(site, "model.request", verdict, { step: 0, attempt: 1 }).payload, verdict);
     entry.detail = { ...entry.detail, purpose: "title" };
-    await d.db.transaction().execute((t) => audit(t, entry));
+    await d.writes.auditDenied(entry);
     d.log.warn("conversation title blocked by a policy hook", {
         conversationId: scope.conversationId,
         plugin: verdict.plugin,
@@ -343,31 +374,118 @@ function observeTitle(d, scope, sent, out, err, signal) {
         ...(out === null && { errorCode: errorCodeOf(err) }),
     }, signal, d.log);
 }
+/**
+ * One title attempt's work ({@link runTitleJob}) over the injected services, with its writes in
+ * transactions of their own: the title with the call's usage event, and a policy denial's audit row.
+ */
+let TitleGenerator = class TitleGenerator {
+    kdb;
+    eventLog;
+    purposes;
+    host;
+    usageReport;
+    log;
+    txHost;
+    constructor(kdb, eventLog, purposes, 
+    /** The title call fires the plugin hooks (`model.request`, `model.response`). */
+    host, usageReport, log, txHost) {
+        this.kdb = kdb;
+        this.eventLog = eventLog;
+        this.purposes = purposes;
+        this.host = host;
+        this.usageReport = usageReport;
+        this.log = log;
+        this.txHost = txHost;
+    }
+    /** One attempt ({@link runTitleJob}); `signal` aborts the call (the worker stopping). */
+    run(conversationId, attempt, signal) {
+        const kdb = this.kdb;
+        const hooks = this.host?.hooks;
+        return runTitleJob({
+            get db() {
+                return kdb.db;
+            },
+            eventLog: this.eventLog,
+            purposes: this.purposes,
+            log: this.log,
+            ...(hooks !== undefined && { hooks }),
+            ...(this.usageReport !== undefined && { usageReport: this.usageReport }),
+            ...(signal !== undefined && { signal }),
+            writes: this,
+        }, conversationId, attempt);
+    }
+    /**
+     * Appends the call's `usage` event and writes the title while `title_source IS NULL` (a rename
+     * wins), in one transaction.
+     */
+    async writeResult(conversationId, attempt, out, title) {
+        // Append first: it locks the conversation row FOR UPDATE before this transaction touches it.
+        // Updating the title first held the row FOR NO KEY UPDATE, which lets in another
+        // transaction's foreign key check (FOR KEY SHARE, e.g. inserting an approval); the append's
+        // FOR UPDATE then waited for that one while it waited for the title row: 40P01
+        const [ev] = await this.eventLog.appendIn(conversationId, [usageEvent(attempt, out)]);
+        const row = title === null
+            ? undefined
+            : await this.kdb.db
+                .updateTable("conversations")
+                .set({ title, title_source: "generated" })
+                .where("id", "=", conversationId)
+                .where("title_source", "is", null)
+                .returning("id")
+                .executeTakeFirst();
+        return { written: row !== undefined, usage: ev };
+    }
+    /** The `hook.denied` audit row of a denied title call. */
+    async auditDenied(entry) {
+        await audit(this.kdb.db, entry);
+    }
+};
+__decorate([
+    Transactional({ propagation: "requires_new" })
+], TitleGenerator.prototype, "writeResult", null);
+__decorate([
+    Transactional({ propagation: "requires_new" })
+], TitleGenerator.prototype, "auditDenied", null);
+TitleGenerator = __decorate([
+    Injectable(),
+    __param(0, Inject(KernelDb)),
+    __param(1, Inject(EventLog)),
+    __param(2, Inject(ModelPurposesService)),
+    __param(3, Inject(ExtensionHost)),
+    __param(4, Inject(UsageReporter)),
+    __param(5, Inject(KERNEL_LOGGER)),
+    __param(6, Inject(TransactionHost))
+], TitleGenerator);
+export { TitleGenerator };
 /**
  * The title queue: `maybeEnqueue` on any role (called by the run worker after a completed run),
- * the worker on the `worker` role. One attempt per job, no BullMQ retries: the next completed run
- * enqueues the next attempt.
+ * consumed on the `worker` role by its `@Processor`. One attempt per job, no BullMQ retries: the
+ * next completed run enqueues the next attempt.
  */
-export class TitleQueue {
-    d;
+let TitleQueue = class TitleQueue {
+    kdb;
     queue;
-    queueConn;
+    generator;
+    log;
     worker;
-    workerConn;
     closed = false;
     stopping = new AbortController();
-    constructor(d) {
-        this.d = d;
+    constructor(kdb, queue, generator, log) {
+        this.kdb = kdb;
+        this.queue = queue;
+        this.generator = generator;
+        this.log = log;
+        queue.on("error", (err) => this.log.error("title queue error", { err }));
     }
     /** Enqueues the next title attempt when one is due. Never throws (logs instead). */
     async maybeEnqueue(conversationId) {
         if (this.closed)
             return;
         try {
-            const attempt = await titleAttemptDue(this.d.db, conversationId);
+            const attempt = await titleAttemptDue(this.kdb.db, conversationId);
             if (attempt === null)
                 return;
-            await this.getQueue().add(JOB, { conversationId, attempt }, {
+            await this.queue.add(JOB, { conversationId, attempt }, {
                 jobId: titleJobId(conversationId, attempt),
                 attempts: 1,
                 removeOnComplete: true,
@@ -375,48 +493,55 @@ export class TitleQueue {
             });
         }
         catch (err) {
-            this.d.log.warn("cannot enqueue conversation title", { conversationId, err });
+            this.log.warn("cannot enqueue conversation title", { conversationId, err });
         }
     }
-    startWorker() {
+    /** Starts consuming (worker role only): `worker` is the `@Processor` worker of {@link TITLE_QUEUE}. */
+    startWorker(worker) {
         if (this.worker || this.closed)
             return;
-        const { jobLockMs, stalledIntervalMs } = this.d.config().runtime;
-        this.workerConn = bullConnection(this.d.redisUrl, this.d.log);
-        this.worker = new Worker(TITLE_QUEUE, (j) => this.process(j), {
-            connection: this.workerConn,
-            concurrency: 4,
-            lockDuration: jobLockMs,
-            stalledInterval: stalledIntervalMs,
-            maxStalledCount: 1,
-        });
-        this.worker.on("error", (err) => this.d.log.error("title worker error", { err }));
+        this.worker = worker;
+        void worker.run().catch((err) => this.log.error("title worker error", { err }));
+    }
+    /** The worker's `error` event. */
+    onError(err) {
+        this.log.error("title worker error", { err });
     }
+    /** One title job (the `@Processor` calls it). */
     async process(j) {
-        await runTitleJob({ ...this.d, signal: this.stopping.signal }, j.data.conversationId, j.data.attempt);
+        await this.generator.run(j.data.conversationId, j.data.attempt, this.stopping.signal);
     }
+    /** Stops: no more enqueues, the call in flight is aborted, the worker closes. */
     async stop() {
         this.closed = true;
         this.stopping.abort();
         const w = this.worker;
         this.worker = undefined;
         await w?.close().catch(() => { });
-        const q = this.queue;
-        this.queue = undefined;
-        await q?.close().catch(() => { });
-        for (const c of [this.workerConn, this.queueConn]) {
-            if (c)
-                await c.quit().catch(() => c.disconnect());
-        }
-        this.workerConn = undefined;
-        this.queueConn = undefined;
-    }
-    getQueue() {
-        if (!this.queue) {
-            this.queueConn = bullConnection(this.d.redisUrl, this.d.log);
-            this.queue = new Queue(TITLE_QUEUE, { connection: this.queueConn });
-            this.queue.on("error", (err) => this.d.log.error("title queue error", { err }));
-        }
-        return this.queue;
     }
-}
+};
+TitleQueue = __decorate([
+    Injectable(),
+    __param(0, Inject(KernelDb)),
+    __param(1, Inject(getQueueToken(TITLE_QUEUE))),
+    __param(2, Inject(TitleGenerator)),
+    __param(3, Inject(KERNEL_LOGGER))
+], TitleQueue);
+export { TitleQueue };
+/** Conversation titles: the queue and the job (consumed on the worker role). */
+let TitlesModule = class TitlesModule {
+};
+TitlesModule = __decorate([
+    Module({
+        imports: [
+            EventLogModule,
+            ModelsModule,
+            ExtensionsModule,
+            UsageReportModule,
+            QueueModule.registerQueue(TITLE_QUEUE),
+        ],
+        providers: [TitleGenerator, TitleQueue],
+        exports: [TitleQueue],
+    })
+], TitlesModule);
+export { TitlesModule };

package/dist/conversations/tree.d.ts

@@ -0,0 +1,17 @@
+import type { KernelSchemaDb } from "../db/kernel-schema.js";
+/**
+ * A conversation and every sub-agent conversation below it (agent map spec §6: its children,
+ * grandchildren and so on, through `conversations.parent_conversation_id`), each with its level
+ * below `conversationId` (0 for the conversation itself), shallowest first. Deleted conversations
+ * are included (a deleted root's tree is still stopped); an unknown id yields nothing.
+ */
+export declare function conversationTree(db: KernelSchemaDb, conversationId: string): Promise<{
+    id: string;
+    level: number;
+}[]>;
+/**
+ * The ancestors of a conversation (agent map spec §8: live progress reaches every level above a
+ * sub-agent), nearest first: its parent, the parent's parent and so on up to the root, through
+ * `conversations.parent_conversation_id`. Empty for a root or an unknown id.
+ */
+export declare function conversationAncestors(db: KernelSchemaDb, conversationId: string): Promise<string[]>;

package/dist/conversations/tree.js

@@ -0,0 +1,42 @@
+import { sql } from "kysely";
+/**
+ * How many levels below a conversation the tree reads walk at most: far above
+ * `subagents.maxDepth`'s bound of 5, so a corrupt parent chain cannot loop forever.
+ */
+const TREE_MAX_LEVELS = 16;
+/**
+ * A conversation and every sub-agent conversation below it (agent map spec §6: its children,
+ * grandchildren and so on, through `conversations.parent_conversation_id`), each with its level
+ * below `conversationId` (0 for the conversation itself), shallowest first. Deleted conversations
+ * are included (a deleted root's tree is still stopped); an unknown id yields nothing.
+ */
+export async function conversationTree(db, conversationId) {
+    const r = await sql `
+    WITH RECURSIVE tree(id, level) AS (
+      SELECT c.id, 0 FROM capybara.conversations c WHERE c.id = ${conversationId}
+      UNION ALL
+      SELECT c.id, t.level + 1
+      FROM capybara.conversations c JOIN tree t ON c.parent_conversation_id = t.id
+      WHERE c.kind = 'subagent' AND t.level < ${TREE_MAX_LEVELS}
+    )
+    SELECT id, level FROM tree ORDER BY level, id`.execute(db);
+    return r.rows;
+}
+/**
+ * The ancestors of a conversation (agent map spec §8: live progress reaches every level above a
+ * sub-agent), nearest first: its parent, the parent's parent and so on up to the root, through
+ * `conversations.parent_conversation_id`. Empty for a root or an unknown id.
+ */
+export async function conversationAncestors(db, conversationId) {
+    const r = await sql `
+    WITH RECURSIVE up(id, parent, level) AS (
+      SELECT c.id, c.parent_conversation_id, 0 FROM capybara.conversations c
+      WHERE c.id = ${conversationId}
+      UNION ALL
+      SELECT c.id, c.parent_conversation_id, up.level + 1
+      FROM capybara.conversations c JOIN up ON c.id = up.parent
+      WHERE up.level < ${TREE_MAX_LEVELS}
+    )
+    SELECT id FROM up WHERE level > 0 ORDER BY level`.execute(db);
+    return r.rows.map((row) => row.id);
+}

package/dist/ctx/bus.js

@@ -1,3 +1,5 @@
+import { runOutsideTransaction } from "../infra/database/transaction-host.js";
+import { withoutLogContext } from "../log-context.js";
 import { assertNamespace } from "./namespace.js";
 /** 未注入 logger 时的兜底：输出到 stderr。 */
 const consoleLog = {
@@ -19,9 +21,13 @@ export function createBusSubscriber(subFactory, log = consoleLog) {
             return conn;
         const c = subFactory();
         c.on("message", (channel, message) => {
-            for (const h of [...(channels.get(channel)?.handlers ?? [])]) {
-                invokeIsolated(log, channel, () => h(message));
-            }
+            // the connection's callbacks carry the async context of the first subscribe (a request's
+            // log fields, possibly an open transaction): every handler starts from an empty one
+            runOutsideTransaction(() => withoutLogContext(() => {
+                for (const h of [...(channels.get(channel)?.handlers ?? [])]) {
+                    invokeIsolated(log, channel, () => h(message));
+                }
+            }));
         });
         c.on("error", (err) => log.error("bus subscriber connection error", { err }));
         conn = c;

package/dist/ctx/create-ctx.d.ts

@@ -3,6 +3,10 @@ import type { Redis } from "ioredis";
 import { Kysely } from "kysely";
 import { type RegisteredHook } from "../extensions/hooks.js";
 import { RegistrationLedger } from "../extensions/ledger.js";
+import type { LockService } from "../infra/lock/lock.service.js";
+import type { ModelEmbeddings } from "../models/embeddings.js";
+import type { HookRunner } from "../runtime/hook-calls.js";
+import type { EmbedTokens } from "../ui/embed-token.js";
 import { type UiActionHandler, type UiRender } from "../ui/registry.js";
 import { type BusSubscriber } from "./bus.js";
 import { type Keyring } from "./secrets.js";
@@ -13,9 +17,24 @@ export interface KernelDeps {
     /** PG 建立连接的超时（迁移器的独立连接使用）。 */
     connectTimeoutMs?: number;
     redis: Redis;
+    /** The kernel's lock primitives (`ctx.lock`, the dedupe markers). */
+    locks: Pick<LockService, "lease" | "renew" | "releaseIf">;
     busSubscriber: BusSubscriber;
     redisUrl: string;
     keyring: Keyring;
+    /** Verifies embed tokens (`ctx.ui` embed requests; the one `EmbedTokens` provider). */
+    embedTokens: Pick<EmbedTokens, "verify">;
+    /**
+     * The `ctx.models` broker (the one `ModelEmbeddings` provider). Absent (a ctx built alone in a
+     * test): `ctx.models` calls reject.
+     */
+    models?: Pick<ModelEmbeddings, "embed" | "describe">;
+    /**
+     * The host's hook registry: `ctx.models.embed` fires `model.request` through it (spec B §5.4).
+     * A required key, so no builder leaves policy hooks out by omission (fail closed by
+     * construction); only a ctx built alone in a test passes `undefined` (no hooks fire).
+     */
+    hooks: HookRunner | undefined;
     runWorkers: boolean;
     /** 内核 logger（`debug` 可选：插件 Logger 没有它，测试可不给）。 */
     log: Logger & {
@@ -42,6 +61,11 @@ export interface ExtensionPointAccess {
     }[];
     /** Names of the extensions enabled in the organization (`extension_org_configs.enabled` plus required bootstrap plugins, `enabled.ts`); queried every time, not cached. */
     enabledPlugins(orgId: string): Promise<Set<string>>;
+    /**
+     * Whether the extension's effective config is valid in the organization (layering spec A §6):
+     * a provider that is not is excluded from point resolution for that org.
+     */
+    configOk(orgId: string, plugin: string): Promise<boolean>;
 }
 /**
  * Queries the names of the extensions enabled in the organization (org config rows plus the
@@ -91,7 +115,8 @@ export declare class LiveConfig {
  * `deploymentConfig` may be a {@link LiveConfig} (shared by the instance, replaceable in place);
  * otherwise a fixed value is wrapped.
  * - Granted automatically: `kv`, `lock`, `bus`, `queue`, `log`, `db`, `config`, `provide`;
- * - `secrets` only with `permissions.secrets`, `storage` only with `permissions.storage`; `http.route`
+ * - `secrets` only with `permissions.secrets`, `storage` only with `permissions.storage`, `models`
+ *   only with `permissions.models` (and only its `embedding` purposes, through `deps.models`); `http.route`
  *   only the method + path declared in `permissions.http`; `tools.register` only names declared in
  *   `permissions.tools`; `ui.view` / `ui.action` only ids declared in `permissions.ui.views` (during
  *   setup only); `ui.invalidate` sends a refresh over the kernel bus (namespace `kernel`), across

package/dist/ctx/create-ctx.js

@@ -6,8 +6,7 @@ import { enabledExtensionsQuery, isExtensionEnabled } from "../extensions/enable
 import { checkHookRegistration } from "../extensions/hooks.js";
 import { RegistrationLedger } from "../extensions/ledger.js";
 import { audit } from "../identity/audit.js";
-import { StorageService } from "../storage/storage.service.js";
-import { EmbedTokens } from "../ui/embed-token.js";
+import { PrefixedStorage } from "../storage/storage.service.js";
 import { canUsePlace, orgUiTopic, PluginUiRegistration, } from "../ui/registry.js";
 import { createBus } from "./bus.js";
 import { createKv } from "./kv.js";
@@ -58,16 +57,15 @@ async function invalidateTargetOk(db, plugin, orgId, conversationId) {
 /** 越权审计去重键的 TTL：同一插件同一项在此期间只记一次。 */
 const DENIAL_DEDUPE_TTL_SECONDS = 30 * 24 * 3600;
 /**
- * Records one `extension.permission_denied` audit, deduplicated per (extension, item) through Redis
- * `SET NX EX` (once across replicas). When the audit write fails, the dedup key is removed (the next
+ * Records one `extension.permission_denied` audit, deduplicated per (extension, item) through a
+ * Redis marker set unless present (`LockService.lease`; once across replicas). When the audit write fails, the dedup key is removed (the next
  * violation tries again) and a warning is logged; nothing is thrown to the extension (it already got
  * an ExtensionPermissionError).
  */
 async function recordDenial(deps, plugin, item) {
     const key = `capk:plugin-permission-denied:${plugin}:${item}`;
     try {
-        const first = await deps.redis.set(key, "1", "EX", DENIAL_DEDUPE_TTL_SECONDS, "NX");
-        if (first !== "OK")
+        if (!(await deps.locks.lease(key, "1", DENIAL_DEDUPE_TTL_SECONDS * 1000)))
             return;
         try {
             await audit(kernelDb(deps.db), {
@@ -148,6 +146,7 @@ function guardBuilder(builder, plugin) {
 const noProviders = (deps) => ({
     providers: () => [],
     enabledPlugins: (orgId) => queryEnabledPlugins(deps.db, orgId),
+    configOk: async () => true,
 });
 /**
  * 插件实例的部署配置（已校验）：`ctx.config` 是读它的 getter。hot 字段改动时宿主替换 `value`（C10），
@@ -165,7 +164,8 @@ export class LiveConfig {
  * `deploymentConfig` may be a {@link LiveConfig} (shared by the instance, replaceable in place);
  * otherwise a fixed value is wrapped.
  * - Granted automatically: `kv`, `lock`, `bus`, `queue`, `log`, `db`, `config`, `provide`;
- * - `secrets` only with `permissions.secrets`, `storage` only with `permissions.storage`; `http.route`
+ * - `secrets` only with `permissions.secrets`, `storage` only with `permissions.storage`, `models`
+ *   only with `permissions.models` (and only its `embedding` purposes, through `deps.models`); `http.route`
  *   only the method + path declared in `permissions.http`; `tools.register` only names declared in
  *   `permissions.tools`; `ui.view` / `ui.action` only ids declared in `permissions.ui.views` (during
  *   setup only); `ui.invalidate` sends a refresh over the kernel bus (namespace `kernel`), across
@@ -195,7 +195,7 @@ export function createExtensionContext(deps, manifest, deploymentConfig, extensi
     const lifecycle = new AbortController();
     /** 撤销时队列 worker 排空的截止时刻（epoch 毫秒）；undefined = 一直等（停机路径）。 */
     let drainDeadline;
-    const lock = createLock(deps.redis, name);
+    const lock = createLock(deps.locks, name);
     const tag = (fields) => ({ ...fields, plugin: name });
     let closing;
     const perms = manifest.permissions ?? {};
@@ -214,11 +214,29 @@ export function createExtensionContext(deps, manifest, deploymentConfig, extensi
     // 键加前缀 plugins/<name>/<orgId>/。没有提供方时各方法 reject storage.unavailable
     // （宿主不会加载这样的插件，见 approvals.ts；单独构造 ctx 的测试会走到这里）
     const storageApi = perms.storage
-        ? new StorageService({
+        ? new PrefixedStorage({
             provider: () => extensionPointAccess.providers(OBJECT_STORE_EXTENSION_POINT)[0]?.impl,
             plugins: async () => [name],
         }).forPlugin(name)
         : undefined;
+    // ctx.models: only with permissions.models; the broker accepts only the purposes declared there
+    // with kind embedding (spec B §5.4), aborted by this instance's signal
+    // a frozen copy: the approved manifest, not an object the extension could change later
+    const declaredModels = Object.freeze(structuredClone(perms.models ?? []).map((m) => Object.freeze(m)));
+    const modelsApi = declaredModels.length > 0
+        ? {
+            embed: async (req) => {
+                if (!deps.models)
+                    throw new Error(`plugin ${name}: ctx.models is not available`);
+                return deps.models.embed(name, declaredModels, req, lifecycle.signal, deps.hooks);
+            },
+            describe: async (req) => {
+                if (!deps.models)
+                    throw new Error(`plugin ${name}: ctx.models is not available`);
+                return deps.models.describe(name, declaredModels, req);
+            },
+        }
+        : undefined;
     const declaredRoutes = new Set((perms.http ?? []).map((r) => `${r.method} ${r.path}`));
     const declaredTools = new Set(perms.tools ?? []);
     const declaredHooks = new Set(perms.hooks ?? []);
@@ -229,7 +247,7 @@ export function createExtensionContext(deps, manifest, deploymentConfig, extensi
         ...(manifest.optional ?? []),
     ]);
     const uiReg = new PluginUiRegistration(manifest, deny);
-    const embedTokens = new EmbedTokens(deps.keyring);
+    const embedTokens = deps.embedTokens;
     const uiPlaces = new Map((manifest.ui ?? []).map((c) => [c.id, c.place]));
     /** 校验能力可取用（非 brokered、已在清单声明），返回其登记信息。 */
     const checkExtensionPoint = (ref) => {
@@ -262,12 +280,21 @@ export function createExtensionContext(deps, manifest, deploymentConfig, extensi
             throw new ExtensionPointUnavailableError(`extension point ${ref} has no provider`);
         return { info, chosen };
     };
-    /** 组织视角过滤提供方：orgScoped 能力只留该组织已启用的（每次查询，不缓存）。 */
+    /**
+     * The org's view of the providers: an orgScoped point keeps only those the org enabled (queried
+     * every time, not cached), and every point drops those whose effective config is not valid in
+     * the org (layering spec A §6: a call on behalf of an org never reaches such a provider).
+     */
     const forOrg = async (orgScoped, orgId, entries) => {
-        if (!orgScoped || entries.length === 0)
+        if (entries.length === 0)
             return entries;
-        const enabled = await extensionPointAccess.enabledPlugins(orgId);
-        return entries.filter((e) => enabled.has(e.plugin));
+        let out = entries;
+        if (orgScoped) {
+            const enabled = await extensionPointAccess.enabledPlugins(orgId);
+            out = out.filter((e) => enabled.has(e.plugin));
+        }
+        const ok = await Promise.all(out.map((e) => extensionPointAccess.configOk(orgId, e.plugin)));
+        return out.filter((_, i) => ok[i]);
     };
     const listAll = (ref) => {
         const info = checkExtensionPoint(ref);
@@ -282,7 +309,7 @@ export function createExtensionContext(deps, manifest, deploymentConfig, extensi
             return (async () => {
                 const { info, chosen } = pick(ref, provider);
                 if ((await forOrg(info.orgScoped, orgId, [chosen])).length === 0) {
-                    throw new ExtensionPointUnavailableError(`extension point ${ref} provider ${chosen.plugin} is not enabled in organization ${orgId}`);
+                    throw new ExtensionPointUnavailableError(`extension point ${ref} provider ${chosen.plugin} is not available in organization ${orgId} (not enabled there, or its configuration is not valid there)`);
                 }
                 return chosen.impl;
             })();
@@ -553,7 +580,8 @@ export function createExtensionContext(deps, manifest, deploymentConfig, extensi
             return closing;
         },
     };
-    // 声明了 secrets / storage 时是普通属性；未声明时是不可枚举的抛错 getter——展开 / 打印 ctx 不会触发越权与审计
+    // secrets / storage / models: a plain property when declared; otherwise a non-enumerable getter
+    // that throws, so spreading or printing ctx triggers no denial and no audit
     const gated = (key, api) => {
         if (api) {
             Object.assign(ctx, { [key]: api });
@@ -567,6 +595,7 @@ export function createExtensionContext(deps, manifest, deploymentConfig, extensi
     };
     gated("secrets", secretsApi);
     gated("storage", storageApi);
+    gated("models", modelsApi);
     return ctx;
 }
 /**