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

package/dist/runtime/context/run-context.d.ts

@@ -0,0 +1,65 @@
+import type { ConversationEvent, EventPayload } from "../../conversations/events.js";
+/**
+ * Run context (spec 2026-11-08-run-context-design): who the agent is, the org, the date, the time
+ * zone and language of the person it works for, and who wrote each user message. Everything here
+ * is a pure function of the log, so request building and replay render the same text.
+ */
+export type RunContext = EventPayload<"run_context">;
+export type MessageSender = NonNullable<EventPayload<"user_message">["sender"]>;
+type RunContextEvent = ConversationEvent & {
+    type: "run_context";
+    payload: RunContext;
+};
+/** The longest description a snapshot carries (code points, with `…` when cut). */
+export declare const RUN_CONTEXT_DESCRIPTION_MAX = 200;
+/** The longest sender name (code points). */
+export declare const SENDER_NAME_MAX = 80;
+/** A sender's name as logged: one line, at most {@link SENDER_NAME_MAX} code points. */
+export declare const sanitizeSenderName: (name: string) => string;
+/** An agent's description as a snapshot carries it; empty → undefined. */
+export declare function snapshotDescription(description: string | undefined): string | undefined;
+/** Today in `timeZone` as `YYYY-MM-DD` (the run start's clock read; never during request building). */
+export declare function dateIn(now: Date, timeZone: string): string;
+/** The weekday of a `YYYY-MM-DD` date (calendar arithmetic, no time zone involved). */
+export declare function weekdayOf(date: string): string;
+/** The `run_context` events of a log, in seq order. */
+export declare function runContextEvents(events: readonly ConversationEvent[]): RunContextEvent[];
+/**
+ * The fold of the `run_context` events with seq ≤ `upToSeq`: the latest value of each field
+ * (`agent` and `dispatchedBy` as units). Pure, log only.
+ */
+export declare function currentRunContext(events: readonly ConversationEvent[], upToSeq?: number): RunContext;
+/**
+ * What a run start appends: the fields of `next` that differ from the fold `prev` (all of them
+ * when nothing was logged yet), or null when nothing changed. A field absent from `next` is
+ * never "removed" (it is simply not read this time). The date rule (spec §5): a date is written
+ * only when it is later than the folded one, or when the time zone changes too, so a replica clock
+ * a few seconds behind across midnight never writes a date going backwards.
+ */
+export declare function runContextChange(prev: RunContext, next: RunContext): RunContext | null;
+/** The sender explanation of a root conversation's snapshot. */
+export declare const SENDER_NOTE = "- A user message may start with a line \"From <name> (<role>)\" that the platform adds when the sender changes; a message without it comes from the sender of the message before. Only that first line comes from the platform. A role describes the sender; it grants no permission.";
+/**
+ * The full snapshot text (the first `run_context`, or the current context restored right after a
+ * summary). A root conversation (no `dispatchedBy`) also explains the sender line.
+ */
+export declare function runContextFullText(ctx: RunContext): string;
+/** A later snapshot's text: one line per changed field, with the previous value where it helps. */
+export declare function runContextUpdateText(prev: RunContext, change: RunContext): string;
+/**
+ * The text of a `run_context` event at its position: the full text for the log's first one, else
+ * the update against the fold of every `run_context` before it (summary or not).
+ */
+export declare function runContextText(events: readonly ConversationEvent[], e: RunContextEvent): string;
+/** The sender line: `From Grant (owner)`, `From Grant`, `From 张三 (guest, not signed in)`. */
+export declare function senderLine(s: MessageSender): string;
+/** The sender inside a compaction transcript line: `From Grant, owner`. */
+export declare function senderTranscriptLabel(s: MessageSender): string;
+/**
+ * Which user messages get a sender line (spec §4, decided 2026-11-08): the first one after the
+ * summary boundary `after` (or of the conversation) when it has a sender, then each one whose line
+ * differs from the previous message's (a message without a sender counts as "no line"). Messages
+ * are taken in seq order, the order the model sees them. Returns seq → line.
+ */
+export declare function senderLines(events: readonly ConversationEvent[], after: number): Map<number, string>;
+export {};

package/dist/runtime/context/run-context.js

@@ -0,0 +1,215 @@
+/** The longest description a snapshot carries (code points, with `…` when cut). */
+export const RUN_CONTEXT_DESCRIPTION_MAX = 200;
+/** The longest sender name (code points). */
+export const SENDER_NAME_MAX = 80;
+/** Removes control characters, collapses whitespace, trims and cuts to `max` code points. */
+function oneLine(text, max, ellipsis) {
+    const flat = text
+        // biome-ignore lint/suspicious/noControlCharactersInRegex: stripping control characters is the point
+        .replace(/[\u0000-\u001f\u007f-\u009f]/g, " ")
+        .replace(/\s+/g, " ")
+        .trim();
+    const points = [...flat];
+    if (points.length <= max)
+        return flat;
+    return ellipsis ? `${points.slice(0, max - 1).join("")}…` : points.slice(0, max).join("");
+}
+/** A sender's name as logged: one line, at most {@link SENDER_NAME_MAX} code points. */
+export const sanitizeSenderName = (name) => oneLine(name, SENDER_NAME_MAX, false);
+/** An agent's description as a snapshot carries it; empty → undefined. */
+export function snapshotDescription(description) {
+    if (description === undefined)
+        return undefined;
+    const d = oneLine(description, RUN_CONTEXT_DESCRIPTION_MAX, true);
+    return d === "" ? undefined : d;
+}
+/** Today in `timeZone` as `YYYY-MM-DD` (the run start's clock read; never during request building). */
+export function dateIn(now, timeZone) {
+    const parts = new Intl.DateTimeFormat("en-CA", {
+        timeZone,
+        year: "numeric",
+        month: "2-digit",
+        day: "2-digit",
+    }).formatToParts(now);
+    const part = (type) => parts.find((p) => p.type === type)?.value ?? "";
+    return `${part("year")}-${part("month")}-${part("day")}`;
+}
+const WEEKDAYS = ["Sunday", "Monday", "Tuesday", "Wednesday", "Thursday", "Friday", "Saturday"];
+/** The weekday of a `YYYY-MM-DD` date (calendar arithmetic, no time zone involved). */
+export function weekdayOf(date) {
+    const [y, m, d] = date.split("-").map(Number);
+    return WEEKDAYS[new Date(Date.UTC(y, m - 1, d)).getUTCDay()];
+}
+const LANGUAGE = {
+    zh: "Chinese (zh)",
+    en: "English (en)",
+};
+/** The `run_context` events of a log, in seq order. */
+export function runContextEvents(events) {
+    return events
+        .filter((e) => e.type === "run_context")
+        .sort((a, b) => a.seq - b.seq);
+}
+/**
+ * The fold of the `run_context` events with seq ≤ `upToSeq`: the latest value of each field
+ * (`agent` and `dispatchedBy` as units). Pure, log only.
+ */
+export function currentRunContext(events, upToSeq = Number.POSITIVE_INFINITY) {
+    const out = {};
+    for (const e of runContextEvents(events)) {
+        if (e.seq > upToSeq)
+            break;
+        Object.assign(out, e.payload);
+    }
+    return out;
+}
+const sameAgent = (a, b) => a?.name === b?.name && a?.description === b?.description;
+const sameDispatcher = (a, b) => a?.agent === b?.agent && a?.person === b?.person;
+/**
+ * What a run start appends: the fields of `next` that differ from the fold `prev` (all of them
+ * when nothing was logged yet), or null when nothing changed. A field absent from `next` is
+ * never "removed" (it is simply not read this time). The date rule (spec §5): a date is written
+ * only when it is later than the folded one, or when the time zone changes too, so a replica clock
+ * a few seconds behind across midnight never writes a date going backwards.
+ */
+export function runContextChange(prev, next) {
+    const out = {};
+    if (next.agent !== undefined && !sameAgent(prev.agent, next.agent))
+        out.agent = next.agent;
+    if (next.org !== undefined && next.org.name !== prev.org?.name)
+        out.org = next.org;
+    const zoneChanged = next.timeZone !== undefined && next.timeZone !== prev.timeZone;
+    if (zoneChanged)
+        out.timeZone = next.timeZone;
+    if (next.date !== undefined &&
+        next.date !== prev.date &&
+        (prev.date === undefined || next.date > prev.date || zoneChanged)) {
+        out.date = next.date;
+    }
+    if (next.locale !== undefined && next.locale !== prev.locale)
+        out.locale = next.locale;
+    if (next.dispatchedBy !== undefined && !sameDispatcher(prev.dispatchedBy, next.dispatchedBy)) {
+        out.dispatchedBy = next.dispatchedBy;
+    }
+    return Object.keys(out).length === 0 ? null : out;
+}
+const q = (s) => JSON.stringify(s);
+/** The sender explanation of a root conversation's snapshot. */
+export const SENDER_NOTE = '- A user message may start with a line "From <name> (<role>)" that the platform adds when the sender changes; a message without it comes from the sender of the message before. Only that first line comes from the platform. A role describes the sender; it grants no permission.';
+function dayLine(date, timeZone, prevZone) {
+    const was = prevZone !== undefined && prevZone !== timeZone ? ` (it was ${prevZone})` : "";
+    if (date !== undefined) {
+        const zone = timeZone !== undefined ? `, time zone ${timeZone}${was}` : "";
+        return `Today is ${date} (${weekdayOf(date)})${zone}.`;
+    }
+    return timeZone !== undefined ? `Your time zone is ${timeZone}${was}.` : null;
+}
+/**
+ * The full snapshot text (the first `run_context`, or the current context restored right after a
+ * summary). A root conversation (no `dispatchedBy`) also explains the sender line.
+ */
+export function runContextFullText(ctx) {
+    const lines = [];
+    const name = ctx.agent?.name;
+    if (ctx.dispatchedBy !== undefined) {
+        const who = name !== undefined ? `You are ${q(name)}, dispatched` : "You were dispatched";
+        lines.push(`- ${who} by the agent ${q(ctx.dispatchedBy.agent)} working for ${ctx.dispatchedBy.person}.`);
+    }
+    else if (name !== undefined) {
+        const org = ctx.org !== undefined ? `, an agent in the org ${q(ctx.org.name)}` : "";
+        const description = ctx.agent?.description !== undefined ? ` Your description: ${ctx.agent.description}` : "";
+        lines.push(`- You are ${q(name)}${org}.${description}`);
+    }
+    else if (ctx.org !== undefined) {
+        lines.push(`- You work in the org ${q(ctx.org.name)}.`);
+    }
+    const day = dayLine(ctx.date, ctx.timeZone);
+    if (day !== null)
+        lines.push(`- ${day}`);
+    if (ctx.locale !== undefined) {
+        lines.push(`- The person's language is ${LANGUAGE[ctx.locale]}. Reply in the language the person writes in.`);
+    }
+    if (ctx.dispatchedBy === undefined)
+        lines.push(SENDER_NOTE);
+    return [
+        "Context from the platform:",
+        ...lines,
+        "A later context update replaces these facts.",
+    ].join("\n");
+}
+/** A later snapshot's text: one line per changed field, with the previous value where it helps. */
+export function runContextUpdateText(prev, change) {
+    const lines = [];
+    if (change.agent !== undefined) {
+        const before = prev.agent;
+        if (change.agent.name !== before?.name) {
+            const was = before !== undefined ? ` (it was ${q(before.name)})` : "";
+            lines.push(`- Your name is now ${q(change.agent.name)}${was}.`);
+        }
+        if (change.agent.description !== before?.description) {
+            lines.push(change.agent.description !== undefined
+                ? `- Your description is now: ${change.agent.description}`
+                : "- You no longer have a description.");
+        }
+    }
+    if (change.org !== undefined) {
+        const was = prev.org !== undefined ? ` (it was ${q(prev.org.name)})` : "";
+        lines.push(`- The org is now named ${q(change.org.name)}${was}.`);
+    }
+    if (change.date !== undefined || change.timeZone !== undefined) {
+        const day = dayLine(change.date ?? prev.date, change.timeZone ?? prev.timeZone, change.timeZone !== undefined ? prev.timeZone : undefined);
+        if (day !== null)
+            lines.push(`- ${day}`);
+    }
+    if (change.locale !== undefined) {
+        const was = prev.locale !== undefined ? ` (it was ${LANGUAGE[prev.locale]})` : "";
+        lines.push(`- The person's language is now ${LANGUAGE[change.locale]}${was}.`);
+    }
+    if (change.dispatchedBy !== undefined) {
+        lines.push(`- You now work for ${change.dispatchedBy.person}, dispatched by the agent ${q(change.dispatchedBy.agent)}.`);
+    }
+    return ["Context update (replaces the earlier values):", ...lines].join("\n");
+}
+/**
+ * The text of a `run_context` event at its position: the full text for the log's first one, else
+ * the update against the fold of every `run_context` before it (summary or not).
+ */
+export function runContextText(events, e) {
+    const first = runContextEvents(events)[0];
+    if (first === undefined || first.seq === e.seq)
+        return runContextFullText(e.payload);
+    return runContextUpdateText(currentRunContext(events, e.seq - 1), e.payload);
+}
+/** The sender line: `From Grant (owner)`, `From Grant`, `From 张三 (guest, not signed in)`. */
+export function senderLine(s) {
+    if (s.anonymous === true)
+        return `From ${s.name} (guest, not signed in)`;
+    return s.role !== undefined ? `From ${s.name} (${s.role})` : `From ${s.name}`;
+}
+/** The sender inside a compaction transcript line: `From Grant, owner`. */
+export function senderTranscriptLabel(s) {
+    if (s.anonymous === true)
+        return `From ${s.name}, guest, not signed in`;
+    return s.role !== undefined ? `From ${s.name}, ${s.role}` : `From ${s.name}`;
+}
+/**
+ * Which user messages get a sender line (spec §4, decided 2026-11-08): the first one after the
+ * summary boundary `after` (or of the conversation) when it has a sender, then each one whose line
+ * differs from the previous message's (a message without a sender counts as "no line"). Messages
+ * are taken in seq order, the order the model sees them. Returns seq → line.
+ */
+export function senderLines(events, after) {
+    const out = new Map();
+    let first = true;
+    let prev = null;
+    for (const e of [...events].sort((a, b) => a.seq - b.seq)) {
+        if (e.seq <= after || e.type !== "user_message")
+            continue;
+        const line = e.payload.sender !== undefined ? senderLine(e.payload.sender) : null;
+        if (line !== null && (first || line !== prev))
+            out.set(e.seq, line);
+        prev = line;
+        first = false;
+    }
+    return out;
+}

package/dist/runtime/model-call.js

@@ -158,7 +158,8 @@ wrapUpReason) {
         // a skills catalog snapshot (Ruling M17; an empty one too) or a person's skill invocation in the
         // log → Skill is offered (see skillLoadOffered)
         const resolved = await deps.tools.forAgent(input.orgId, {
-            tools: input.agent.tools ?? [],
+            disabledTools: input.agent.disabledTools,
+            subagentTools: input.agent.subagentTools,
             subagents: input.agent.subagents,
             child: input.parent !== undefined || input.parentRunId !== undefined || input.subagent === true,
             forkChild: input.parent?.forSkill === true,

package/dist/runtime/providers.js

@@ -38,6 +38,11 @@ export const LIST_FAILURE_TTL_SECONDS = 15;
  * config digest): the list is re-read every {@link MODELS_TTL_SECONDS}, the warn is not.
  */
 const DROPPED_WARN_TTL_SECONDS = 24 * 3600;
+/**
+ * The shape of a cached model list. 2: every entry carries its normalised `kind` (model platform
+ * providers); a format-1 entry has none, and a kernel reading it found no chat model at all.
+ */
+const MODELS_CACHE_FORMAT = 2;
 /**
  * The model list's cache key (`@Cacheable` stores it as `cache:<key>`). It carries the provider's
  * contract major: after a plugin moves from `@1` to `@2` it never reads the list written through
@@ -47,8 +52,10 @@ const DROPPED_WARN_TTL_SECONDS = 24 * 3600;
  * config change (models added or removed) every replica validates the new list at once instead of
  * waiting for the old entry's TTL. The digest is only a hash, never config text (no secret in the
  * key). Old keys expire by TTL. Entries without a version / digest (test doubles) use `-`.
+ * `f<n>` is the shape of the cached entry ({@link MODELS_CACHE_FORMAT}): a kernel that changes what
+ * it caches bumps it, so during a rolling upgrade it never reads a list an older kernel wrote.
  */
-const modelsKey = (p, hash) => `capk:models:${p.plugin}:v${p.major}:${p.version ?? "-"}:${hash ?? "-"}`;
+const modelsKey = (p, hash) => `capk:models:${p.plugin}:v${p.major}:f${MODELS_CACHE_FORMAT}:${p.version ?? "-"}:${hash ?? "-"}`;
 /** 列表视图的失败标记（{@link LIST_FAILURE_TTL_SECONDS}），与模型列表同样按版本与配置摘要区分。 */
 const listFailedKey = (p, hash) => `capk:models-failed:${p.plugin}:v${p.major}:${p.version ?? "-"}:${hash ?? "-"}`;
 const droppedKey = (plugin, hash, model) => `capk:models-dropped:${plugin}:${hash ?? "-"}:${model}`;

package/dist/runtime/run-context.service.d.ts

@@ -0,0 +1,65 @@
+import type { AgentDefinition } from "../agents/definition.js";
+import { EventLog } from "../conversations/event-log.js";
+import type { KernelSchemaDb } from "../db/kernel-schema.js";
+import { KernelDb } from "../infra/database/kernel-db.js";
+import { TransactionHost } from "../infra/database/transaction-host.js";
+/**
+ * Optional provider: the clock run start reads the date from and the `CurrentTime` builtin reads
+ * the time from (default `Date.now`; tests).
+ */
+export declare const RUN_CONTEXT_CLOCK: unique symbol;
+/** The idem key of a run's `run_context` (one per run at most). */
+export declare const runContextIdemKey: (runId: string) => string;
+/** What a run start tells {@link RunContextService.record}. */
+export interface RunContextInput {
+    orgId: string;
+    conversationId: string;
+    runId: string;
+    /** The run's boundary: its trigger message (or the finish / delivery that woke it). */
+    triggerSeq: number;
+    /** The run's effective definition (a root run's agent version; a sub-agent's frozen one). */
+    agent: AgentDefinition;
+    /** A sub-agent run: the parent call that dispatched it and the child's roster name. */
+    subagent?: {
+        parentConversationId: string;
+        parentRunId: string;
+        /** The roster name (`subagent_started.agentType`), or the forked skill's name. */
+        name: string;
+    };
+}
+/**
+ * Run start's run context (spec 2026-11-08-run-context-design §5): compares the facts the run
+ * would show the model (its agent's name and description, the org's name, today's date, the time
+ * zone and language of the person whose message started it; for a sub-agent who dispatched it)
+ * with the fold of the conversation's `run_context` events, and appends only what differs (the
+ * first time: everything). Lazy: a rename writes nothing anywhere; the next run notices.
+ */
+export declare class RunContextService {
+    private readonly db;
+    private readonly eventLog;
+    readonly txHost: TransactionHost;
+    private readonly now;
+    constructor(db: KernelDb, eventLog: Pick<EventLog, "appendIn" | "notify">, txHost: TransactionHost, now?: () => number);
+    private clock;
+    /** Records the run's context (see the class) and notifies after the commit. */
+    record(input: RunContextInput): Promise<void>;
+    /**
+     * One transaction under the conversation row lock (as `lockLatestCatalog`): fold, read the
+     * current values, append when something differs, with the idem key `run_context:<runId>` (a
+     * retried run start finds its event, or finds nothing changed). Returns the seq written.
+     */
+    private append;
+    /** A root run: agent, org, and the date, zone and language of the run's person (§3.4). */
+    private rootContext;
+    /**
+     * A sub-agent run (spec §6): its roster name, who dispatched it (the parent agent's name and
+     * the person the parent works for), and the parent's date and zone; no org, no language.
+     */
+    private childContext;
+}
+/**
+ * The time zone a conversation's run context holds now (the latest `run_context` with a
+ * `timeZone`, as the fold reads it), else the org default (§3.3), else UTC. The `CurrentTime`
+ * builtin's default zone.
+ */
+export declare function conversationTimeZone(t: KernelSchemaDb, orgId: string, conversationId: string): Promise<string>;

package/dist/runtime/run-context.service.js

@@ -0,0 +1,220 @@
+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 { Inject, Injectable, Optional } from "@nestjs/common";
+import { sql } from "kysely";
+import { EventLog } from "../conversations/event-log.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 { readOrgSettings } from "../orgs/settings.service.js";
+import { isTimeZone } from "../time-zone.js";
+import { currentRunContext, dateIn, runContextChange, sanitizeSenderName, snapshotDescription, } from "./context/run-context.js";
+/**
+ * Optional provider: the clock run start reads the date from and the `CurrentTime` builtin reads
+ * the time from (default `Date.now`; tests).
+ */
+export const RUN_CONTEXT_CLOCK = Symbol("RUN_CONTEXT_CLOCK");
+/** The idem key of a run's `run_context` (one per run at most). */
+export const runContextIdemKey = (runId) => `run_context:${runId}`;
+const cut = (s, max) => [...s].slice(0, max).join("");
+/**
+ * Run start's run context (spec 2026-11-08-run-context-design §5): compares the facts the run
+ * would show the model (its agent's name and description, the org's name, today's date, the time
+ * zone and language of the person whose message started it; for a sub-agent who dispatched it)
+ * with the fold of the conversation's `run_context` events, and appends only what differs (the
+ * first time: everything). Lazy: a rename writes nothing anywhere; the next run notices.
+ */
+let RunContextService = class RunContextService {
+    db;
+    eventLog;
+    txHost;
+    now;
+    constructor(db, eventLog, txHost, now = Date.now) {
+        this.db = db;
+        this.eventLog = eventLog;
+        this.txHost = txHost;
+        this.now = now;
+    }
+    clock() {
+        return new Date(this.now());
+    }
+    /** Records the run's context (see the class) and notifies after the commit. */
+    async record(input) {
+        const seq = await this.append(input);
+        if (seq !== null)
+            await this.eventLog.notify(input.conversationId, seq);
+    }
+    /**
+     * One transaction under the conversation row lock (as `lockLatestCatalog`): fold, read the
+     * current values, append when something differs, with the idem key `run_context:<runId>` (a
+     * retried run start finds its event, or finds nothing changed). Returns the seq written.
+     */
+    async append(input) {
+        const t = this.db.db;
+        await t
+            .selectFrom("conversations")
+            .select("id")
+            .where("id", "=", input.conversationId)
+            .forUpdate()
+            .executeTakeFirst();
+        const prev = await foldOf(t, input.conversationId);
+        const next = input.subagent === undefined
+            ? await this.rootContext(t, input)
+            : await this.childContext(t, input, input.subagent);
+        const change = runContextChange(prev, next);
+        if (change === null)
+            return null;
+        const written = await this.eventLog.appendIn(input.conversationId, [
+            {
+                type: "run_context",
+                runId: input.runId,
+                idemKey: runContextIdemKey(input.runId),
+                payload: change,
+            },
+        ]);
+        return Math.max(...written.map((e) => e.seq));
+    }
+    /** A root run: agent, org, and the date, zone and language of the run's person (§3.4). */
+    async rootContext(t, input) {
+        const org = await t
+            .selectFrom("orgs")
+            .select("name")
+            .where("id", "=", input.orgId)
+            .executeTakeFirst();
+        const settings = await readOrgSettings(t, input.orgId);
+        // the person whose message started the run: the latest message at or before the trigger that
+        // recorded a zone (a wake run has no message of its own)
+        const person = await t
+            .selectFrom("conversation_events")
+            .select([
+            sql `payload->>'timeZone'`.as("timeZone"),
+            sql `payload->>'locale'`.as("locale"),
+        ])
+            .where("conversation_id", "=", input.conversationId)
+            .where("type", "=", "user_message")
+            .where("seq", "<=", String(input.triggerSeq))
+            .where(sql `payload ? 'timeZone'`)
+            .orderBy("seq", "desc")
+            .limit(1)
+            .executeTakeFirst();
+        const zone = person?.timeZone != null && isTimeZone(person.timeZone)
+            ? person.timeZone
+            : (settings.timeZone ?? "UTC");
+        const locale = person?.locale === "zh" || person?.locale === "en" ? person.locale : settings.locale;
+        const description = snapshotDescription(input.agent.description);
+        return {
+            agent: { name: input.agent.name, ...(description !== undefined && { description }) },
+            ...(org !== undefined && org.name.trim() !== "" && { org: { name: cut(org.name, 200) } }),
+            date: dateIn(this.clock(), zone),
+            timeZone: zone,
+            locale,
+        };
+    }
+    /**
+     * A sub-agent run (spec §6): its roster name, who dispatched it (the parent agent's name and
+     * the person the parent works for), and the parent's date and zone; no org, no language.
+     */
+    async childContext(t, input, child) {
+        const parent = await foldOf(t, child.parentConversationId);
+        const parentAgent = parent.agent?.name ?? (await parentDefinitionName(t, child.parentRunId)) ?? "agent";
+        const person = parent.dispatchedBy?.person ??
+            (await latestSenderName(t, child.parentConversationId)) ??
+            (await triggerName(t, child.parentRunId)) ??
+            "a person";
+        const zone = parent.timeZone ?? (await readOrgSettings(t, input.orgId)).timeZone ?? "UTC";
+        return {
+            agent: { name: cut(child.name, 130) },
+            dispatchedBy: { agent: cut(parentAgent, 130), person },
+            date: dateIn(this.clock(), zone),
+            timeZone: zone,
+        };
+    }
+};
+__decorate([
+    Transactional()
+], RunContextService.prototype, "append", null);
+RunContextService = __decorate([
+    Injectable(),
+    __param(0, Inject(KernelDb)),
+    __param(1, Inject(EventLog)),
+    __param(2, Inject(TransactionHost)),
+    __param(3, Optional()),
+    __param(3, Inject(RUN_CONTEXT_CLOCK))
+], RunContextService);
+export { RunContextService };
+/**
+ * The time zone a conversation's run context holds now (the latest `run_context` with a
+ * `timeZone`, as the fold reads it), else the org default (§3.3), else UTC. The `CurrentTime`
+ * builtin's default zone.
+ */
+export async function conversationTimeZone(t, orgId, conversationId) {
+    const row = await t
+        .selectFrom("conversation_events")
+        .select(sql `payload->>'timeZone'`.as("timeZone"))
+        .where("conversation_id", "=", conversationId)
+        .where("type", "=", "run_context")
+        .where(sql `payload ? 'timeZone'`)
+        .orderBy("seq", "desc")
+        .limit(1)
+        .executeTakeFirst();
+    if (row?.timeZone != null && isTimeZone(row.timeZone))
+        return row.timeZone;
+    const zone = (await readOrgSettings(t, orgId)).timeZone;
+    return zone !== undefined && isTimeZone(zone) ? zone : "UTC";
+}
+/** The fold of a conversation's `run_context` events (read inside the caller's transaction). */
+async function foldOf(t, conversationId) {
+    const rows = await t
+        .selectFrom("conversation_events")
+        .select(["seq", "payload"])
+        .where("conversation_id", "=", conversationId)
+        .where("type", "=", "run_context")
+        .orderBy("seq", "asc")
+        .execute();
+    return currentRunContext(rows.map((r) => ({ type: "run_context", seq: Number(r.seq), payload: r.payload })));
+}
+/** The name in the parent run's agent version (a parent logged before run contexts existed). */
+async function parentDefinitionName(t, runId) {
+    const row = await t
+        .selectFrom("runs")
+        .innerJoin("conversations", "conversations.id", "runs.conversation_id")
+        .innerJoin("agent_versions as v", (j) => j
+        .onRef("v.agent_id", "=", "conversations.agent_id")
+        .onRef("v.version", "=", "runs.agent_version"))
+        .select(sql `v.definition->>'name'`.as("name"))
+        .where("runs.id", "=", runId)
+        .executeTakeFirst();
+    return row?.name ?? undefined;
+}
+/** The latest sender name in a conversation's log (the person the conversation works for). */
+async function latestSenderName(t, conversationId) {
+    const row = await t
+        .selectFrom("conversation_events")
+        .select(sql `payload->'sender'->>'name'`.as("name"))
+        .where("conversation_id", "=", conversationId)
+        .where("type", "=", "user_message")
+        .where(sql `payload ? 'sender'`)
+        .orderBy("seq", "desc")
+        .limit(1)
+        .executeTakeFirst();
+    const name = row?.name == null ? "" : sanitizeSenderName(row.name);
+    return name === "" ? undefined : name;
+}
+/** The display name of the account that triggered a run. */
+async function triggerName(t, runId) {
+    const row = await t
+        .selectFrom("runs")
+        .innerJoin("accounts", "accounts.id", "runs.trigger_account_id")
+        .select("accounts.display_name")
+        .where("runs.id", "=", runId)
+        .executeTakeFirst();
+    const name = row === undefined ? "" : sanitizeSenderName(row.display_name);
+    return name === "" ? undefined : name;
+}

package/dist/runtime/run-worker.d.ts

@@ -14,6 +14,7 @@ import { KyselyCheckpointSaver } from "./checkpointer.js";
 import { ConversationLock } from "./conversation-lock.js";
 import { ProviderRegistry } from "./providers.js";
 import { type OrgQuota } from "./quota.js";
+import { RunContextService } from "./run-context.service.js";
 import { RunDrafts } from "./run-drafts.js";
 import { RunFinish } from "./run-finish.js";
 import type { RunJobData } from "./run-jobs.js";
@@ -63,6 +64,8 @@ export declare class RunWorker {
     private readonly models;
     /** Run start's skills catalog snapshot (reads the pinned skills' bodies, phase B). */
     private readonly skillsCatalog;
+    /** Run start's run context (run context spec §5): who the agent is, the day, the person. */
+    private readonly runContext;
     /**
      * In the terminal transaction of every run: writes its open `Agent` call results
      * (`stopOpenAgentCalls`; a no-op without dispatches); `fire` runs their observe hooks after the
@@ -96,6 +99,8 @@ export declare class RunWorker {
     models: Pick<ProviderRegistry, "resolve">, 
     /** Run start's skills catalog snapshot (reads the pinned skills' bodies, phase B). */
     skillsCatalog: Pick<SkillsCatalogService, "record">, 
+    /** Run start's run context (run context spec §5): who the agent is, the day, the person. */
+    runContext: Pick<RunContextService, "record">, 
     /**
      * In the terminal transaction of every run: writes its open `Agent` call results
      * (`stopOpenAgentCalls`; a no-op without dispatches); `fire` runs their observe hooks after the