@capybara-hq/kernel 0.1.0-rc.5 → 0.1.0-rc.7

package/dist/conversations/conversations.service.js

@@ -29,6 +29,7 @@ import { readAgentTree } from "./agent-tree.js";
 import { AttachmentsService } from "./attachments.service.js";
 import { EventLog } from "./event-log.js";
 import { userMessageIdemKey } from "./idem-keys.js";
+import { readMessageContext } from "./message-context.js";
 import { NO_SELECTION, planSelection, readSelection } from "./selection.js";
 import { conversationTree } from "./tree.js";
 /** Escapes `\`, `%` and `_` so user text is matched literally by `LIKE … ESCAPE '\'`. */
@@ -205,7 +206,7 @@ let ConversationsService = class ConversationsService {
         if (prior)
             return prior;
         const environmentId = await this.environments.forNew(orgId, accountId, pick);
-        const next = await this.planSwitch(agent.definition, NO_SELECTION, input);
+        const next = await this.planSwitch(orgId, agent.definition, NO_SELECTION, input);
         const extra = await this.resolveExtra(orgId, accountId, input);
         const invoked = await this.prepareSkill(orgId, agentId, undefined, agent.definition, input);
         const id = randomUUID();
@@ -245,7 +246,7 @@ let ConversationsService = class ConversationsService {
         if (!row)
             return undefined;
         const blocks = await this.bindIn(orgId, id, accountId, input.files ?? []);
-        return this.writeMessage(id, accountId, input, next, extra, blocks, invoked);
+        return this.writeMessage(orgId, id, accountId, input, next, extra, blocks, invoked);
     }
     /**
      * The conversation (and its first event) an earlier first send with this id created. The id used
@@ -701,23 +702,17 @@ let ConversationsService = class ConversationsService {
             : undefined;
         const next = agent === undefined || (input.model === undefined && input.effort === undefined)
             ? null
-            : await this.planSwitch(agent, conv.selection, input);
+            : await this.planSwitch(orgId, agent, conv.selection, input);
         const extra = await this.resolveExtra(orgId, accountId, input);
         const invoked = agent === undefined
             ? undefined
             : await this.prepareSkill(orgId, conv.agentId, conversationId, agent, input);
-        let event;
-        if (files.length > 0 || next !== null) {
-            event = await this.postIn(orgId, conversationId, accountId, input, next, extra, invoked);
-            await this.eventLog.notify(conversationId, event.seq);
-            if (next !== null)
-                await this.eventLog.publishChanged(conversationId, "selection");
-        }
-        else {
-            [event] = await this.eventLog.append(conversationId, [
-                this.userMessage(accountId, input, extra, [], invoked),
-            ]);
-        }
+        // one transaction: the sender, time zone and language are read with the message's write
+        // (run context spec §3.2)
+        const event = await this.postIn(orgId, conversationId, accountId, input, next, extra, invoked);
+        await this.eventLog.notify(conversationId, event.seq);
+        if (next !== null)
+            await this.eventLog.publishChanged(conversationId, "selection");
         // The message is written: it brings an archived conversation back into the default lists
         if (conv.archivedAt !== null) {
             await this.db
@@ -730,27 +725,31 @@ let ConversationsService = class ConversationsService {
         await this.runs.ensureRun(conversationId);
         return event;
     }
-    /** A message with files or a model switch: binds the files and writes it in one transaction. */
+    /**
+     * Writes a message in one transaction: binds its files, reads its sender context and appends it
+     * (after its `model_switched` when it switches).
+     */
     // its own transaction: the caller notifies and publishes after the commit
     async postIn(orgId, conversationId, accountId, input, next, extra, invoked) {
         const blocks = await this.bindIn(orgId, conversationId, accountId, input.files ?? []);
-        const written = await this.writeMessage(conversationId, accountId, input, next, extra, blocks, invoked);
+        const written = await this.writeMessage(orgId, conversationId, accountId, input, next, extra, blocks, invoked);
         return written.at(-1);
     }
     /**
      * The selection a message switches to, or null when it changes nothing. A model equal to the
      * agent's means "back to the agent's model" (null); a model change without `effort` resets the
      * effort. The target model must resolve (`agent.model_unavailable`) and declare the effort
-     * (`validation_failed`). Resolving is the agent editor's check: providers are deployment-scoped
-     * and serve chat models only. If per-org provider enablement is added, this check and the run
-     * worker's `fallBackIfUnavailable` must follow it.
+     * (`validation_failed`). Resolving is the agent editor's check, for the org (its effective
+     * provider config, spec B §5.5) and its disabled lists: a model the platform or the org disabled,
+     * or a non-chat model, is refused (spec B §5.3), as the run worker's `fallBackIfUnavailable` falls
+     * back from it.
      */
-    async planSwitch(agent, current, input) {
+    async planSwitch(orgId, agent, current, input) {
         const next = planSelection(agent.model, current, input);
         if (next === null)
             return null;
         const { model, effort } = next;
-        const { info } = await this.providers.resolve(model ?? agent.model);
+        const { info } = await this.providers.resolve(orgId, model ?? agent.model);
         if (effort !== null) {
             const knob = info.parameters.find((p) => p.key === "effort");
             const values = knob?.schema?.enum ?? [];
@@ -771,14 +770,14 @@ let ConversationsService = class ConversationsService {
         if (pick.model === undefined && pick.effort === undefined)
             return;
         const agent = await this.agents.get(orgId, conv.agentId, accountId);
-        await this.planSwitch(agent.definition, conv.selection, pick);
+        await this.planSwitch(orgId, agent.definition, conv.selection, pick);
     }
     /**
      * Writes the message (preceded by its `model_switched` when it switches) inside `t` and updates
      * `conversations.selection`; returns the events written, in seq order (the `user_message`
      * last). The caller notifies after commit.
      */
-    async writeMessage(conversationId, accountId, input, next, extra, blocks, invoked) {
+    async writeMessage(orgId, conversationId, accountId, input, next, extra, blocks, invoked) {
         const events = [];
         if (next !== null) {
             events.push({
@@ -789,7 +788,13 @@ let ConversationsService = class ConversationsService {
                 payload: { ...next, byAccountId: accountId, reason: "user" },
             });
         }
-        events.push(this.userMessage(accountId, input, extra, blocks, invoked));
+        const context = await readMessageContext(this.db.db, {
+            orgId,
+            accountId,
+            senderName: input.senderName,
+            browser: { timeZone: input.timeZone, locale: input.locale },
+        });
+        events.push(this.userMessage(accountId, input, extra, blocks, invoked, context));
         const written = await this.eventLog.appendIn(conversationId, events);
         if (next !== null) {
             const t = this.db.db;
@@ -846,7 +851,7 @@ let ConversationsService = class ConversationsService {
             return [];
         return this.attachments.bindForMessage(orgId, conversationId, accountId, files);
     }
-    userMessage(accountId, input, extra, fileBlocks, invoked) {
+    userMessage(accountId, input, extra, fileBlocks, invoked, context) {
         // a skill invocation's rendered text replaces the typed arguments as content[0]
         const text = invoked?.text ?? input.text;
         return {
@@ -863,6 +868,7 @@ let ConversationsService = class ConversationsService {
                 ],
                 ...(extra.attachments.length > 0 && { attachments: extra.attachments }),
                 authorAccountId: accountId,
+                ...context,
                 ...(input.clientMessageId !== undefined && { clientMessageId: input.clientMessageId }),
                 ...(input.retryOf !== undefined && { retryOf: input.retryOf }),
                 ...(invoked !== undefined && { skill: invoked.skill }),

package/dist/conversations/events.d.ts

@@ -145,6 +145,39 @@ export declare const SubagentFinishStatusSchema: z.ZodEnum<{
     max_steps: "max_steps";
     timed_out: "timed_out";
 }>;
+/** The languages a run context names (the org `locale` values). */
+export declare const RUN_CONTEXT_LOCALES: readonly ["zh", "en"];
+/** `user_message.sender` (run context spec §3.2). */
+export declare const MessageSenderSchema: z.ZodObject<{
+    name: z.ZodString;
+    role: z.ZodOptional<z.ZodEnum<{
+        admin: "admin";
+        guest: "guest";
+        member: "member";
+        owner: "owner";
+    }>>;
+    anonymous: z.ZodOptional<z.ZodLiteral<true>>;
+}, z.core.$strip>;
+/** `run_context` (run context spec §3.1): every field optional, a later event holds changes only. */
+export declare const RunContextSchema: z.ZodObject<{
+    agent: z.ZodOptional<z.ZodObject<{
+        name: z.ZodString;
+        description: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    org: z.ZodOptional<z.ZodObject<{
+        name: z.ZodString;
+    }, z.core.$strip>>;
+    date: z.ZodOptional<z.ZodString>;
+    timeZone: z.ZodOptional<z.ZodString>;
+    locale: z.ZodOptional<z.ZodEnum<{
+        en: "en";
+        zh: "zh";
+    }>>;
+    dispatchedBy: z.ZodOptional<z.ZodObject<{
+        agent: z.ZodString;
+        person: z.ZodString;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
 /**
  * 会话事件（`type` + `payload`）的判别联合。事件日志只追加，写入前用它校验 payload；
  * 读出时按写入时的形状原样返回。
@@ -217,6 +250,21 @@ export declare const ConversationEventSchema: z.ZodDiscriminatedUnion<[z.ZodObje
             name: z.ZodString;
         }, z.core.$strip>>>;
         authorAccountId: z.ZodString;
+        sender: z.ZodOptional<z.ZodObject<{
+            name: z.ZodString;
+            role: z.ZodOptional<z.ZodEnum<{
+                admin: "admin";
+                guest: "guest";
+                member: "member";
+                owner: "owner";
+            }>>;
+            anonymous: z.ZodOptional<z.ZodLiteral<true>>;
+        }, z.core.$strip>>;
+        timeZone: z.ZodOptional<z.ZodString>;
+        locale: z.ZodOptional<z.ZodEnum<{
+            en: "en";
+            zh: "zh";
+        }>>;
         clientMessageId: z.ZodOptional<z.ZodString>;
         retryOf: z.ZodOptional<z.ZodNumber>;
         skill: z.ZodOptional<z.ZodObject<{
@@ -241,18 +289,18 @@ export declare const ConversationEventSchema: z.ZodDiscriminatedUnion<[z.ZodObje
                 task: "task";
             }>>;
             narrowed: z.ZodOptional<z.ZodObject<{
-                tools: z.ZodArray<z.ZodPreprocess<z.ZodDiscriminatedUnion<[z.ZodObject<{
+                disabledTools: z.ZodOptional<z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
                     kind: z.ZodLiteral<"builtin">;
                     name: z.ZodString;
                 }, z.core.$strict>, z.ZodObject<{
                     kind: z.ZodLiteral<"plugin">;
                     plugin: z.ZodString;
-                    name: z.ZodString;
+                    tools: z.ZodUnion<readonly [z.ZodLiteral<"all">, z.ZodArray<z.ZodString>]>;
                 }, z.core.$strict>, z.ZodObject<{
                     kind: z.ZodLiteral<"connector">;
                     connectorId: z.ZodString;
                     tools: z.ZodUnion<readonly [z.ZodLiteral<"all">, z.ZodArray<z.ZodString>]>;
-                }, z.core.$strict>], "kind">, unknown>>;
+                }, z.core.$strict>], "kind">>>;
                 skills: z.ZodOptional<z.ZodObject<{
                     orgSkills: z.ZodArray<z.ZodString>;
                     pinned: z.ZodOptional<z.ZodArray<z.ZodString>>;
@@ -439,6 +487,27 @@ export declare const ConversationEventSchema: z.ZodDiscriminatedUnion<[z.ZodObje
         step: z.ZodNumber;
         text: z.ZodString;
     }, z.core.$strip>;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"run_context">;
+    payload: z.ZodObject<{
+        agent: z.ZodOptional<z.ZodObject<{
+            name: z.ZodString;
+            description: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>;
+        org: z.ZodOptional<z.ZodObject<{
+            name: z.ZodString;
+        }, z.core.$strip>>;
+        date: z.ZodOptional<z.ZodString>;
+        timeZone: z.ZodOptional<z.ZodString>;
+        locale: z.ZodOptional<z.ZodEnum<{
+            en: "en";
+            zh: "zh";
+        }>>;
+        dispatchedBy: z.ZodOptional<z.ZodObject<{
+            agent: z.ZodString;
+            person: z.ZodString;
+        }, z.core.$strip>>;
+    }, z.core.$strip>;
 }, z.core.$strip>, z.ZodObject<{
     type: z.ZodLiteral<"tools_changed">;
     payload: z.ZodObject<{
@@ -697,6 +766,7 @@ export declare const ConversationEventSchema: z.ZodDiscriminatedUnion<[z.ZodObje
         }, z.core.$strip>;
         definition: z.ZodObject<{
             name: z.ZodString;
+            description: z.ZodOptional<z.ZodString>;
             avatarUrl: z.ZodDefault<z.ZodNullable<z.ZodURL>>;
             instructions: z.ZodDefault<z.ZodString>;
             instructionFiles: z.ZodOptional<z.ZodArray<z.ZodObject<{
@@ -713,18 +783,22 @@ export declare const ConversationEventSchema: z.ZodDiscriminatedUnion<[z.ZodObje
             }, z.core.$strip>>>;
             modelParams: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>>;
             fallbackParams: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>>;
-            tools: z.ZodDefault<z.ZodArray<z.ZodPreprocess<z.ZodDiscriminatedUnion<[z.ZodObject<{
+            disabledTools: z.ZodDefault<z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
                 kind: z.ZodLiteral<"builtin">;
                 name: z.ZodString;
             }, z.core.$strict>, z.ZodObject<{
                 kind: z.ZodLiteral<"plugin">;
                 plugin: z.ZodString;
-                name: z.ZodString;
+                tools: z.ZodUnion<readonly [z.ZodLiteral<"all">, z.ZodArray<z.ZodString>]>;
             }, z.core.$strict>, z.ZodObject<{
                 kind: z.ZodLiteral<"connector">;
                 connectorId: z.ZodString;
                 tools: z.ZodUnion<readonly [z.ZodLiteral<"all">, z.ZodArray<z.ZodString>]>;
-            }, z.core.$strict>], "kind">, unknown>>>;
+            }, z.core.$strict>], "kind">>>;
+            subagentTools: z.ZodOptional<z.ZodObject<{
+                allow: z.ZodOptional<z.ZodArray<z.ZodString>>;
+                deny: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            }, z.core.$strict>>;
             toolPolicies: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodEnum<{
                 ask: "ask";
                 deny: "deny";

package/dist/conversations/events.js

@@ -1,6 +1,6 @@
 import { DOCUMENT_MEDIA_TYPES, hasControlChars, IMAGE_MEDIA_TYPES, isAttachmentId, isSkillName, MEDIA_NAME_MAX_CHARS, } from "@capybara-hq/plugin-sdk";
 import { z } from "zod";
-import { AgentDefinitionSchema, AgentToolRef, ModelRef } from "../agents/definition.js";
+import { AgentDefinitionSchema, DisabledToolRef, ModelRef } from "../agents/definition.js";
 import { ORG_ROLES } from "../orgs/roles.js";
 import { TOOL_VIEW_DIFF_MAX_LINES, TOOL_VIEW_LINE_MAX_CHARS, TOOL_VIEW_PATH_MAX_CHARS, } from "../tools/view.js";
 /** 供应商私有数据（`ProviderOpaque`）：原样保存、只回放给同一供应商。 */
@@ -176,6 +176,37 @@ const InputFormSchema = z.object({
 });
 /** 表单答案（plugin-sdk 的 `FormAnswer`）。 */
 const FormAnswerSchema = z.record(z.string(), z.union([z.string(), z.number(), z.boolean(), z.array(z.string())]));
+/** The languages a run context names (the org `locale` values). */
+export const RUN_CONTEXT_LOCALES = ["zh", "en"];
+/** `user_message.sender` (run context spec §3.2). */
+export const MessageSenderSchema = z.object({
+    name: z.string().min(1).max(80),
+    /** Absent = no membership. */
+    role: z.enum(ORG_ROLES).optional(),
+    /** An IM sender served as the org's anonymous guest; `name` is the IM profile name. */
+    anonymous: z.literal(true).optional(),
+});
+/** `run_context` (run context spec §3.1): every field optional, a later event holds changes only. */
+export const RunContextSchema = z.object({
+    /** The agent itself: its name and its versioned description collapsed to one line. */
+    agent: z
+        .object({ name: z.string().min(1).max(130), description: z.string().max(200).optional() })
+        .optional(),
+    org: z.object({ name: z.string().min(1).max(200) }).optional(),
+    /** Today in `timeZone`, `YYYY-MM-DD`. */
+    date: z
+        .string()
+        .regex(/^\d{4}-\d{2}-\d{2}$/)
+        .optional(),
+    /** IANA name. */
+    timeZone: z.string().min(1).max(64).optional(),
+    /** The language of the person whose message started the run. */
+    locale: z.enum(RUN_CONTEXT_LOCALES).optional(),
+    /** Sub-agents only: who dispatched this conversation. */
+    dispatchedBy: z
+        .object({ agent: z.string().min(1).max(130), person: z.string().min(1).max(80) })
+        .optional(),
+});
 const ev = (type, payload) => z.object({ type: z.literal(type), payload });
 /**
  * 会话事件（`type` + `payload`）的判别联合。事件日志只追加，写入前用它校验 payload；
@@ -193,6 +224,20 @@ export const ConversationEventSchema = z.discriminatedUnion("type", [
             .array(z.object({ appId: z.string(), appName: z.string(), uri: z.string(), name: z.string() }))
             .optional(),
         authorAccountId: z.string(),
+        /**
+         * Who wrote the message, at send time (run context spec §3.2): display name and org role
+         * only (never email or ids). Absent in older logs, on a sub-agent's task or `SendMessage`
+         * message. Model-visible only through the sender line, written when the sender changes
+         * (`senderLines`, runtime/context/run-context.ts).
+         */
+        sender: MessageSenderSchema.optional(),
+        /**
+         * The sender's time zone (IANA) and language at send time (run context spec §3.4): the
+         * account setting, else the browser's, else the org defaults. Not model-visible: the next
+         * run's `run_context` is derived from them.
+         */
+        timeZone: z.string().min(1).max(64).optional(),
+        locale: z.enum(RUN_CONTEXT_LOCALES).optional(),
         clientMessageId: z.string().optional(),
         /**
          * A retry after a failed run (UI refresh B): the seq of the message it repeats. Display only
@@ -232,13 +277,16 @@ export const ConversationEventSchema = z.discriminatedUnion("type", [
              */
             kind: z.enum(["task", "message"]).optional(),
             /**
-             * A follow-up (`resume`, final review I1): the frozen tools and org skills intersected
-             * with the current version (`narrowFollowUp`); the child's run uses these instead of
-             * the frozen ones. Absent on a first dispatch and in older logs.
+             * A follow-up (`resume`, final review I1): the frozen and the current version's
+             * turned-off tools together, and the frozen org skills intersected with the current
+             * ones (`narrowFollowUp`); the child's run uses these instead of the frozen ones.
+             * Absent on a first dispatch and in older logs; logs from before tools were on by
+             * default carry an enabled `tools` list instead of `disabledTools` (read as no tool
+             * narrowing).
              */
             narrowed: z
                 .object({
-                tools: z.array(AgentToolRef),
+                disabledTools: z.array(DisabledToolRef).optional(),
                 skills: z
                     .object({ orgSkills: z.array(z.string()), pinned: z.array(z.string()).optional() })
                     .optional(),
@@ -380,6 +428,13 @@ export const ConversationEventSchema = z.discriminatedUnion("type", [
         callId: z.string().optional(),
     })),
     ev("reminder", z.object({ step: count, text: z.string() })),
+    /**
+     * Who the agent is and the facts of the day (run context spec §3.1), written at run start
+     * (`RunContextService.record`): the conversation's first one holds every field that applies, a
+     * later one only the fields that changed. **Model-visible**: rendered at its position as a
+     * system message (`runContextText`); a summary covering it restores the current values.
+     */
+    ev("run_context", RunContextSchema),
     /**
      * The step's resolved tool set differs from the one the conversation's previous model request
      * offered (`toolSetChange`): tool names as the model sees them, sorted. Written before that

package/dist/conversations/message-context.d.ts

@@ -0,0 +1,28 @@
+import type { KernelSchemaDb } from "../db/kernel-schema.js";
+import type { EventPayload } from "./events.js";
+/** The name of an anonymous IM guest whose IM profile gives none. */
+export declare const ANONYMOUS_SENDER_NAME = "Anonymous guest";
+/** What the browser sent with a message (run context spec §3.4); both optional. */
+export interface BrowserContext {
+    timeZone?: string | undefined;
+    locale?: "zh" | "en" | undefined;
+}
+/** The `user_message` fields {@link readMessageContext} fills. */
+export type MessageContext = Pick<EventPayload<"user_message">, "sender" | "timeZone" | "locale">;
+/**
+ * Who wrote a message and in which time zone and language (run context spec §3.2, §3.4), read in
+ * the message's transaction (`t`):
+ * - `sender`: the account's display name and org role at send time; the org's anonymous guest
+ *   account (`org_anonymous_accounts`) is `{ name: <senderName, else "Anonymous guest">, role:
+ *   "guest", anonymous: true }`. Names are sanitised; an empty one leaves `sender` out.
+ * - `timeZone`: the account's setting, else the browser's (when valid), else the org default, else
+ *   UTC. The anonymous guest account has no setting of its own, so it gets the org default.
+ * - `locale`: the browser's UI language, else the org's `locale`.
+ */
+export declare function readMessageContext(t: KernelSchemaDb, input: {
+    orgId: string;
+    accountId: string;
+    /** An anonymous IM guest's IM profile name. */
+    senderName?: string | undefined;
+    browser?: BrowserContext | undefined;
+}): Promise<MessageContext>;

package/dist/conversations/message-context.js

@@ -0,0 +1,56 @@
+import { readOrgSettings } from "../orgs/settings.service.js";
+import { sanitizeSenderName } from "../runtime/context/run-context.js";
+import { isTimeZone } from "../time-zone.js";
+/** The name of an anonymous IM guest whose IM profile gives none. */
+export const ANONYMOUS_SENDER_NAME = "Anonymous guest";
+/**
+ * Who wrote a message and in which time zone and language (run context spec §3.2, §3.4), read in
+ * the message's transaction (`t`):
+ * - `sender`: the account's display name and org role at send time; the org's anonymous guest
+ *   account (`org_anonymous_accounts`) is `{ name: <senderName, else "Anonymous guest">, role:
+ *   "guest", anonymous: true }`. Names are sanitised; an empty one leaves `sender` out.
+ * - `timeZone`: the account's setting, else the browser's (when valid), else the org default, else
+ *   UTC. The anonymous guest account has no setting of its own, so it gets the org default.
+ * - `locale`: the browser's UI language, else the org's `locale`.
+ */
+export async function readMessageContext(t, input) {
+    const row = await t
+        .selectFrom("accounts")
+        .leftJoin("memberships", (j) => j
+        .onRef("memberships.account_id", "=", "accounts.id")
+        .on("memberships.org_id", "=", input.orgId))
+        .leftJoin("org_anonymous_accounts as anon", (j) => j.onRef("anon.account_id", "=", "accounts.id").on("anon.org_id", "=", input.orgId))
+        .select([
+        "accounts.display_name",
+        "accounts.time_zone",
+        "memberships.role",
+        "anon.account_id as anonymous",
+    ])
+        .where("accounts.id", "=", input.accountId)
+        .executeTakeFirst();
+    const org = await readOrgSettings(t, input.orgId);
+    const anonymous = row?.anonymous !== null && row?.anonymous !== undefined;
+    let sender;
+    if (row !== undefined) {
+        const name = anonymous
+            ? sanitizeSenderName(input.senderName ?? "") || ANONYMOUS_SENDER_NAME
+            : sanitizeSenderName(row.display_name);
+        if (name !== "") {
+            sender = anonymous
+                ? { name, role: "guest", anonymous: true }
+                : { name, ...(row.role !== null && { role: row.role }) };
+        }
+    }
+    const own = row?.time_zone ?? null;
+    const browser = input.browser?.timeZone;
+    const timeZone = own !== null && isTimeZone(own)
+        ? own
+        : browser !== undefined && isTimeZone(browser)
+            ? browser
+            : (org.timeZone ?? "UTC");
+    return {
+        ...(sender !== undefined && { sender }),
+        timeZone,
+        locale: input.browser?.locale ?? org.locale,
+    };
+}

package/dist/conversations/queue.d.ts

@@ -5,6 +5,7 @@ import { type InvocationRecord, type RenderedInvocation } from "../skills/invoke
 import type { AttachmentRef } from "./conversations.service.js";
 import { type AppendEvent, type EventLog } from "./event-log.js";
 import type { ConversationEvent, LogContentBlock } from "./events.js";
+import { type MessageContext } from "./message-context.js";
 /**
  * Queued messages (UI refresh B, spec §5.7): messages a person queued while a run was going. They
  * are conversation state in PG, not events: the model has not seen them, so they enter the log only
@@ -113,7 +114,7 @@ export declare function storedSkill(invokedAs: string, invoked: RenderedInvocati
     first: LogContentBlock;
 };
 /** The `user_message` a queued item becomes, as `postUserMessage` would have written it. */
-export declare function queuedUserMessage(r: QueueRow): AppendEvent;
+export declare function queuedUserMessage(r: QueueRow, context?: MessageContext): AppendEvent;
 /**
  * Appends a queued item inside `t` (the caller holds the conversation row lock): its pick, re-planned
  * against the selection in effect now, becomes a `model_switched` before the `user_message`, as a

package/dist/conversations/queue.js

@@ -4,6 +4,7 @@ import { ApiError } from "../errors.js";
 import { recordedSkillBlocked, } from "../skills/invoke.js";
 import { payloadJson } from "./event-log.js";
 import { userMessageIdemKey } from "./idem-keys.js";
+import { readMessageContext } from "./message-context.js";
 import { planSelection, readSelection } from "./selection.js";
 /**
  * Queued messages (UI refresh B, spec §5.7): messages a person queued while a run was going. They
@@ -77,7 +78,7 @@ export function storedSkill(invokedAs, invoked) {
     return { skill: payloadJson(skill), first: { type: "text", text: invoked.text } };
 }
 /** The `user_message` a queued item becomes, as `postUserMessage` would have written it. */
-export function queuedUserMessage(r) {
+export function queuedUserMessage(r, context = {}) {
     const attachments = r.attachments;
     const skill = r.skill;
     return {
@@ -91,6 +92,7 @@ export function queuedUserMessage(r) {
             ],
             ...(attachments.length > 0 && { attachments }),
             authorAccountId: r.account_id,
+            ...context,
             clientMessageId: r.client_message_id,
             ...(skill !== null && { skill: skill.record }),
         },
@@ -120,7 +122,14 @@ export async function appendQueuedIn(t, eventLog, conversationId, r) {
             payload: { ...next, byAccountId: r.account_id, reason: "user" },
         });
     }
-    events.push(queuedUserMessage(r));
+    // run context spec §3.4: no browser values were stored with a leftover row
+    const org = await t
+        .selectFrom("conversations")
+        .select("org_id")
+        .where("id", "=", conversationId)
+        .executeTakeFirstOrThrow();
+    const context = await readMessageContext(t, { orgId: org.org_id, accountId: r.account_id });
+    events.push(queuedUserMessage(r, context));
     const written = await eventLog.appendIn(conversationId, events);
     if (next !== null) {
         await t

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

@@ -4,6 +4,8 @@ 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";
@@ -22,6 +24,17 @@ export interface KernelDeps {
     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 & {
@@ -102,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

@@ -164,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
@@ -218,6 +219,24 @@ export function createExtensionContext(deps, manifest, deploymentConfig, extensi
             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 ?? []);
@@ -561,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 });
@@ -575,6 +595,7 @@ export function createExtensionContext(deps, manifest, deploymentConfig, extensi
     };
     gated("secrets", secretsApi);
     gated("storage", storageApi);
+    gated("models", modelsApi);
     return ctx;
 }
 /**