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

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
@@ -170,7 +175,7 @@ export declare class RunWorker {
      * model removed), writes `model_switched { model: null, effort: null, reason: "unavailable" }`
      * for this run (idempotent) and clears the cached selection: the run and the next ones use the
      * agent's model. A provider that only failed to list its models is not "gone" (the run's ladder
-     * handles it).
+     * handles it). Resolved for the conversation's org (its effective provider config).
      */
     private fallBackIfUnavailable;
     /**

package/dist/runtime/run-worker.js

@@ -32,6 +32,7 @@ import { ConversationLock } from "./conversation-lock.js";
 import { RunError } from "./model-call.js";
 import { ProviderListError, ProviderRegistry } from "./providers.js";
 import { ORG_QUOTA_LEASE_MS, orgRunLimit, RUN_QUOTA } from "./quota.js";
+import { RunContextService } from "./run-context.service.js";
 import { RunDrafts, streamSink } from "./run-drafts.js";
 import { RunFinish, TERMINAL_STATUSES } from "./run-finish.js";
 import { RunQueue } from "./run-queue.js";
@@ -84,6 +85,7 @@ let RunWorker = class RunWorker {
     titles;
     models;
     skillsCatalog;
+    runContext;
     pipeline;
     finisher;
     txHost;
@@ -111,6 +113,8 @@ let RunWorker = class RunWorker {
     models, 
     /** Run start's skills catalog snapshot (reads the pinned skills' bodies, phase B). */
     skillsCatalog, 
+    /** Run start's run context (run context spec §5): who the agent is, the day, the person. */
+    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
@@ -135,6 +139,7 @@ let RunWorker = class RunWorker {
         this.titles = titles;
         this.models = models;
         this.skillsCatalog = skillsCatalog;
+        this.runContext = runContext;
         this.pipeline = pipeline;
         this.finisher = finisher;
         this.txHost = txHost;
@@ -511,6 +516,8 @@ let RunWorker = class RunWorker {
         let saved;
         let maxSteps = runtime.maxSteps;
         let parent;
+        /** A sub-agent's name in its run context: the roster name, or the forked skill's. */
+        let childName;
         if (conv.kind === "subagent") {
             // a sub-agent runs its effective definition frozen at dispatch, never agent_versions
             // (spec §6.3), and works for the parent call that dispatched this run
@@ -525,6 +532,7 @@ let RunWorker = class RunWorker {
                 ? trigger.payload.dispatch?.narrowed
                 : undefined);
             maxSteps = Math.min(started.payload.maxSteps, runtime.maxSteps);
+            childName = started.payload.template.invokedSkill?.name ?? started.payload.agentType;
             const row = await dispatchOfChildRun(this.db, runId);
             const otherAgent = started.payload.template.source === "agent";
             const parentConversationId = row?.parentConversationId ?? started.payload.parent.conversationId;
@@ -581,7 +589,7 @@ let RunWorker = class RunWorker {
         if (run.status === "queued" || startedAt === null) {
             if (!existingStart) {
                 if (saved !== undefined)
-                    await this.fallBackIfUnavailable(conversationId, runId, saved);
+                    await this.fallBackIfUnavailable(conv.org_id, conversationId, runId, saved);
                 const started = await this.appendRunStarted(conversationId, run, agent, saved);
                 agent = started.agent;
                 const toSeq = started.toSeq;
@@ -620,6 +628,22 @@ let RunWorker = class RunWorker {
                 });
                 return "finished";
             }
+            // run context (spec §5): after the catalog, before the run is running, so before any
+            // compaction and model call; a retried run start finds its event or no change
+            await this.runContext.record({
+                orgId: conv.org_id,
+                conversationId,
+                runId,
+                triggerSeq: Number(run.trigger_seq),
+                agent,
+                ...(parent !== undefined && {
+                    subagent: {
+                        parentConversationId: parent.conversationId,
+                        parentRunId: parent.runId,
+                        name: childName ?? agent.name,
+                    },
+                }),
+            });
             const updated = await this.db
                 .updateTable("runs")
                 .set({ status: "running", started_at: sql `COALESCE(started_at, now())` })
@@ -789,14 +813,14 @@ let RunWorker = class RunWorker {
      * model removed), writes `model_switched { model: null, effort: null, reason: "unavailable" }`
      * for this run (idempotent) and clears the cached selection: the run and the next ones use the
      * agent's model. A provider that only failed to list its models is not "gone" (the run's ladder
-     * handles it).
+     * handles it). Resolved for the conversation's org (its effective provider config).
      */
-    async fallBackIfUnavailable(conversationId, runId, agent) {
+    async fallBackIfUnavailable(orgId, conversationId, runId, agent) {
         const sel = await readSelection(this.db, conversationId);
         if (sel.model === null || sameModel(sel.model, agent.model))
             return;
         try {
-            await this.models.resolve(sel.model);
+            await this.models.resolve(orgId, sel.model);
             return;
         }
         catch (e) {
@@ -946,11 +970,12 @@ RunWorker = __decorate([
     __param(15, Inject(TitleQueue)),
     __param(16, Inject(ProviderRegistry)),
     __param(17, Inject(SkillsCatalogService)),
-    __param(18, Inject(ToolPipeline)),
-    __param(19, Inject(RunFinish)),
-    __param(20, Inject(TransactionHost)),
-    __param(21, Inject(RunDrafts)),
-    __param(22, Optional()),
-    __param(22, Inject(RUN_HOOKS))
+    __param(18, Inject(RunContextService)),
+    __param(19, Inject(ToolPipeline)),
+    __param(20, Inject(RunFinish)),
+    __param(21, Inject(TransactionHost)),
+    __param(22, Inject(RunDrafts)),
+    __param(23, Optional()),
+    __param(23, Inject(RUN_HOOKS))
 ], RunWorker);
 export { RunWorker };

package/dist/runtime/runtime.module.js

@@ -24,6 +24,7 @@ import { ConversationLock } from "./conversation-lock.js";
 import { MAINTENANCE_QUEUE_NAME } from "./maintenance-queue.js";
 import { ProvidersModule } from "./providers.js";
 import { EVAL_QUOTA, EVAL_QUOTA_PREFIX, OrgQuota, RUN_QUOTA, RUN_QUOTA_PREFIX } from "./quota.js";
+import { RunContextService } from "./run-context.service.js";
 import { RunControl } from "./run-control.js";
 import { RunDrafts } from "./run-drafts.js";
 import { RunFinish } from "./run-finish.js";
@@ -79,6 +80,7 @@ RuntimeModule = __decorate([
             RunDrafts,
             AgentLoops,
             RunSteps,
+            RunContextService,
             RunWorker,
             // a finished background task wakes an idle conversation (background Bash spec §3)
             BackgroundWake,

package/dist/runtime/subagents/definition.d.ts

@@ -1,5 +1,5 @@
 import { type AgentTemplateTier } from "@capybara-hq/plugin-sdk";
-import type { AgentDefinition, AgentToolRef, ModelRef } from "../../agents/definition.js";
+import { type AgentDefinition, type DisabledToolRef, type ModelRef } from "../../agents/definition.js";
 import type { EventPayload } from "../../conversations/events.js";
 import type { KernelSchemaDb } from "../../db/kernel-schema.js";
 import type { KernelConfigService } from "../../infra/config/kernel-config.service.js";
@@ -77,31 +77,31 @@ export declare function effectiveDefinition(d: EffectiveDefinitionDeps, a: Child
     tierFallback: boolean;
 }>;
 /**
- * What a follow-up (`resume`) may still use (final review I1, spec §5.3): the frozen tools and
- * org skills intersected with the current version they come from. Recorded on the follow-up's
- * task message (`user_message.dispatch.narrowed`), so the run and its replay read it from the log.
+ * What a follow-up (`resume`) may still use (final review I1, spec §5.3): the frozen definition's
+ * turned-off tools together with the current version's (it can lose tools, never gain them), and
+ * the frozen org skills intersected with the current ones. Recorded on the follow-up's task message
+ * (`user_message.dispatch.narrowed`), so the run and its replay read it from the log.
  */
 export interface FollowUpNarrowing {
-    tools: AgentToolRef[];
+    /** Absent in logs from before tools were on by default (no tool narrowing then). */
+    disabledTools?: DisabledToolRef[] | undefined;
     skills?: {
         orgSkills: string[];
         pinned?: string[] | undefined;
     } | undefined;
 }
-/**
- * The refs of `frozen` that `current` still has: a builtin or plugin tool by name, a connector by
- * id; a connector's `all` meets the other side's names (`all` on both stays `all`), and a
- * connector left with no names is dropped. Pure: a connector `current` lists is not looked up.
- */
-export declare function intersectTools(frozen: readonly AgentToolRef[], current: readonly AgentToolRef[]): AgentToolRef[];
 /**
  * The narrowing of a follow-up (final review I1): `frozen` (the child's `subagent_started`
  * definition) against `current`, the definition a fresh dispatch would read now: the dispatching
  * parent run's version for `general` / inline / plugin children, the dispatched org agent's
  * current version for an org agent child (whose tools are its own at dispatch too, §5.5). Its
- * `orgSkills` keep only those `current` still selects; a pinned id that was one of the frozen org
- * skills goes with it (the agent's own skills stay).
+ * `disabledTools` are both lists together; its `orgSkills` keep only those `current` still
+ * selects; a pinned id that was one of the frozen org skills goes with it (the agent's own skills
+ * stay).
+ */
+export declare function narrowFollowUp(frozen: Pick<AgentDefinition, "disabledTools" | "skills">, current: Pick<AgentDefinition, "disabledTools" | "skills">): FollowUpNarrowing;
+/**
+ * The definition a child run uses: the frozen one with its trigger's follow-up narrowing. A
+ * narrowing logged before tools were on by default (no `disabledTools`) narrows only skills.
  */
-export declare function narrowFollowUp(frozen: Pick<AgentDefinition, "tools" | "skills">, current: Pick<AgentDefinition, "tools" | "skills">): FollowUpNarrowing;
-/** The definition a child run uses: the frozen one with its trigger's follow-up narrowing. */
 export declare function childRunDefinition(frozen: AgentDefinition, narrowed: FollowUpNarrowing | undefined): AgentDefinition;