@capybara-hq/kernel 0.1.0-rc.23 → 0.1.0-rc.25

package/dist/runtime/maintenance.d.ts

@@ -4,6 +4,7 @@ import { OwnedPluginCleanup } from "../catalog/owned-plugin-cleanup.js";
 import { ScheduledRuns } from "../infra/schedule/scheduled-runs.js";
 import type { KernelLogger } from "../log.js";
 import { DirectorySync } from "../orgs/directory-sync.js";
+import { Offboarding } from "../orgs/offboarding.js";
 import { SandboxService } from "../sandbox/sandbox.service.js";
 import { ScheduledTaskFirer } from "../schedules/fire.js";
 import { ToolDrift } from "../tools/drift.js";
@@ -16,8 +17,10 @@ export declare const MAINTENANCE_CONCURRENCY = 5;
  * The one consumer of `cap-kernel-maintenance` (decision R11 of the Nest kernel spec): dispatches
  * each one-off job by name to its domain (`wait-timeout` → {@link Waits}, `sandbox-destroy-for` and
  * `sandbox-reset-files` → {@link SandboxService}, `drift-connector` → {@link ToolDrift}, `directory-sync` →
- * {@link DirectorySync}, `bg-wake` → {@link RunQueue.ensureRun}, `owned-plugin-cleanup` →
- * {@link OwnedPluginCleanup}, `sched-fire` → {@link ScheduledTaskFirer}). The name of a periodic job (a `@LockedCron` / `@LockedInterval` job,
+ * {@link DirectorySync}, `run-stop` → {@link Offboarding.stopRun}, `bg-wake` and `ensure-run` → {@link RunQueue.ensureRun}, `stop-tree` →
+ * {@link processStopTree} and `deliver-to-parent` → {@link processDeliverToParent} (both in
+ * runtime/subagents/tree-jobs.ts, over {@link Waits}), `owned-plugin-cleanup` →
+ * {@link OwnedPluginCleanup}, `sched-fire` and `sched-settle` → {@link ScheduledTaskFirer}). The name of a periodic job (a `@LockedCron` / `@LockedInterval` job,
  * such as `sandbox-suspend-idle`) runs that job's body once ({@link ScheduledRuns.runNow}), as the
  * maintenance handlers did when those jobs were schedulers on this queue: an operator's or a
  * test's one-off run, not a second schedule (decision R23 of the Nest kernel spec). Any other
@@ -28,13 +31,14 @@ export declare class MaintenanceProcessor extends WorkerHost<Worker> {
     private readonly sandbox;
     private readonly drift;
     private readonly directory;
+    private readonly offboarding;
     private readonly runs;
     private readonly ownedCleanup;
     private readonly scheduledTasks;
     private readonly scheduled;
     private readonly log;
     private readonly queue;
-    constructor(waits: Pick<Waits, "processTimeout">, sandbox: Pick<SandboxService, "destroyDevice" | "resetFileSystem">, drift: Pick<ToolDrift, "check">, directory: Pick<DirectorySync, "runSyncJob">, runs: Pick<RunQueue, "ensureRun">, ownedCleanup: Pick<OwnedPluginCleanup, "run">, scheduledTasks: Pick<ScheduledTaskFirer, "fire">, scheduled: Pick<ScheduledRuns, "runNow">, log: Pick<KernelLogger, "error" | "warn">, queue: Pick<Queue, "removeJobScheduler">);
+    constructor(waits: Pick<Waits, "processTimeout" | "childFinished" | "stopChildren" | "stopDescendantsOfStopped" | "stopTree">, sandbox: Pick<SandboxService, "destroyDevice" | "resetFileSystem">, drift: Pick<ToolDrift, "check">, directory: Pick<DirectorySync, "runSyncJob">, offboarding: Pick<Offboarding, "stopRun">, runs: Pick<RunQueue, "ensureRun">, ownedCleanup: Pick<OwnedPluginCleanup, "run">, scheduledTasks: Pick<ScheduledTaskFirer, "fire" | "settle">, scheduled: Pick<ScheduledRuns, "runNow">, log: Pick<KernelLogger, "error" | "warn">, queue: Pick<Queue, "removeJobScheduler">);
     /**
      * Removes the retired job schedulers (`RETIRED_SCHEDULER_IDS`, runtime/retired-schedulers.ts): every fixed-period
      * maintenance job is a `@LockedCron` / `@LockedInterval` now. Idempotent; called once when a

package/dist/runtime/maintenance.js

@@ -20,19 +20,21 @@ import { KernelScheduleModule } from "../infra/schedule/schedule.module.js";
 import { ScheduledRuns } from "../infra/schedule/scheduled-runs.js";
 import { KERNEL_LOGGER } from "../infra/tokens.js";
 import { DIRECTORY_SYNC_JOB, DirectorySync } from "../orgs/directory-sync.js";
+import { Offboarding, RUN_STOP_JOB } from "../orgs/offboarding.js";
 import { OrgsModule } from "../orgs/orgs.module.js";
 import { runSandboxDestroyFor, runSandboxResetFiles, SANDBOX_DESTROY_FOR_JOB, SANDBOX_RESET_FILES_JOB, } from "../sandbox/jobs.js";
 import { SandboxModule } from "../sandbox/sandbox.module.js";
 import { SandboxService } from "../sandbox/sandbox.service.js";
 import { ScheduledTaskFireModule, ScheduledTaskFirer } from "../schedules/fire.js";
-import { SCHED_FIRE_JOB } from "../schedules/job-ids.js";
+import { SCHED_FIRE_JOB, SCHED_SETTLE_JOB, } from "../schedules/job-ids.js";
 import { ToolDrift } from "../tools/drift.js";
 import { DRIFT_CONNECTOR_JOB } from "../tools/job-ids.js";
 import { ToolsModule } from "../tools/tools.module.js";
 import { MAINTENANCE_QUEUE_NAME } from "./maintenance-queue.js";
 import { RETIRED_SCHEDULER_IDS } from "./retired-schedulers.js";
-import { RunQueue } from "./run-queue.js";
+import { ENSURE_RUN_JOB, RunQueue } from "./run-queue.js";
 import { RuntimeModule } from "./runtime.module.js";
+import { DELIVER_TO_PARENT_JOB, processDeliverToParent, processStopTree, STOP_TREE_JOB, } from "./subagents/tree-jobs.js";
 import { WAIT_TIMEOUT_JOB, Waits } from "./waits.js";
 export { MAINTENANCE_QUEUE_NAME } from "./maintenance-queue.js";
 /** The maintenance worker's concurrency (as the hand-made worker had). */
@@ -41,8 +43,10 @@ export const MAINTENANCE_CONCURRENCY = 5;
  * The one consumer of `cap-kernel-maintenance` (decision R11 of the Nest kernel spec): dispatches
  * each one-off job by name to its domain (`wait-timeout` → {@link Waits}, `sandbox-destroy-for` and
  * `sandbox-reset-files` → {@link SandboxService}, `drift-connector` → {@link ToolDrift}, `directory-sync` →
- * {@link DirectorySync}, `bg-wake` → {@link RunQueue.ensureRun}, `owned-plugin-cleanup` →
- * {@link OwnedPluginCleanup}, `sched-fire` → {@link ScheduledTaskFirer}). The name of a periodic job (a `@LockedCron` / `@LockedInterval` job,
+ * {@link DirectorySync}, `run-stop` → {@link Offboarding.stopRun}, `bg-wake` and `ensure-run` → {@link RunQueue.ensureRun}, `stop-tree` →
+ * {@link processStopTree} and `deliver-to-parent` → {@link processDeliverToParent} (both in
+ * runtime/subagents/tree-jobs.ts, over {@link Waits}), `owned-plugin-cleanup` →
+ * {@link OwnedPluginCleanup}, `sched-fire` and `sched-settle` → {@link ScheduledTaskFirer}). The name of a periodic job (a `@LockedCron` / `@LockedInterval` job,
  * such as `sandbox-suspend-idle`) runs that job's body once ({@link ScheduledRuns.runNow}), as the
  * maintenance handlers did when those jobs were schedulers on this queue: an operator's or a
  * test's one-off run, not a second schedule (decision R23 of the Nest kernel spec). Any other
@@ -53,18 +57,20 @@ let MaintenanceProcessor = class MaintenanceProcessor extends WorkerHost {
     sandbox;
     drift;
     directory;
+    offboarding;
     runs;
     ownedCleanup;
     scheduledTasks;
     scheduled;
     log;
     queue;
-    constructor(waits, sandbox, drift, directory, runs, ownedCleanup, scheduledTasks, scheduled, log, queue) {
+    constructor(waits, sandbox, drift, directory, offboarding, runs, ownedCleanup, scheduledTasks, scheduled, log, queue) {
         super();
         this.waits = waits;
         this.sandbox = sandbox;
         this.drift = drift;
         this.directory = directory;
+        this.offboarding = offboarding;
         this.runs = runs;
         this.ownedCleanup = ownedCleanup;
         this.scheduledTasks = scheduledTasks;
@@ -106,6 +112,23 @@ let MaintenanceProcessor = class MaintenanceProcessor extends WorkerHost {
             case DIRECTORY_SYNC_JOB:
                 await this.directory.runSyncJob(job.data);
                 return;
+            // a departed member's run stop, owed by the offboarding (transactional outbox spec §8.1)
+            case RUN_STOP_JOB:
+                try {
+                    await this.offboarding.stopRun(job.data);
+                }
+                catch (err) {
+                    // nothing stops the run after its last attempt: say so (the failed job is kept)
+                    if (job.attemptsMade + 1 >= (job.opts.attempts ?? 1)) {
+                        this.log.error("a departed member's run could not be stopped", {
+                            jobId: job.id,
+                            runId: job.data.runId,
+                            err,
+                        });
+                    }
+                    throw err;
+                }
+                return;
             // the end of a conversation's wake window (background Bash spec §3)
             case BG_WAKE_JOB: {
                 // fired before the window ended (clock skew): it reschedules under its next retry id
@@ -113,6 +136,18 @@ let MaintenanceProcessor = class MaintenanceProcessor extends WorkerHost {
                 await this.runs.ensureRun(conversationId, { wakeRetry: (retry ?? 0) + 1 });
                 return;
             }
+            // the ensure-run backstop of a message, wake or run end (transactional outbox spec §6)
+            case ENSURE_RUN_JOB:
+                await this.runs.ensureRun(job.data.conversationId);
+                return;
+            // the stops a run's end or a root's delete owes its sub-agent tree (outbox spec §6)
+            case STOP_TREE_JOB:
+                await processStopTree(this.waits, job.data);
+                return;
+            // a finished sub-agent run's delivery to its parent (transactional outbox spec §6)
+            case DELIVER_TO_PARENT_JOB:
+                await processDeliverToParent(this.waits, job.data);
+                return;
             // a removed org-owned plugin's extension (plugin scope phase 3, P3-20)
             case OWNED_PLUGIN_CLEANUP_JOB:
                 await this.ownedCleanup.run(job.data.itemId);
@@ -121,6 +156,10 @@ let MaintenanceProcessor = class MaintenanceProcessor extends WorkerHost {
             case SCHED_FIRE_JOB:
                 await this.scheduledTasks.fire(job.data.taskRunId);
                 return;
+            // a task run's settle check, claimed or unfired (ruling R26)
+            case SCHED_SETTLE_JOB:
+                await this.scheduledTasks.settle(job.data);
+                return;
             default:
                 if (await this.scheduled.runNow(job.name))
                     return;
@@ -146,12 +185,13 @@ MaintenanceProcessor = __decorate([
     __param(1, Inject(SandboxService)),
     __param(2, Inject(ToolDrift)),
     __param(3, Inject(DirectorySync)),
-    __param(4, Inject(RunQueue)),
-    __param(5, Inject(OwnedPluginCleanup)),
-    __param(6, Inject(ScheduledTaskFirer)),
-    __param(7, Inject(ScheduledRuns)),
-    __param(8, Inject(KERNEL_LOGGER)),
-    __param(9, Inject(getQueueToken(MAINTENANCE_QUEUE_NAME)))
+    __param(4, Inject(Offboarding)),
+    __param(5, Inject(RunQueue)),
+    __param(6, Inject(OwnedPluginCleanup)),
+    __param(7, Inject(ScheduledTaskFirer)),
+    __param(8, Inject(ScheduledRuns)),
+    __param(9, Inject(KERNEL_LOGGER)),
+    __param(10, Inject(getQueueToken(MAINTENANCE_QUEUE_NAME)))
 ], MaintenanceProcessor);
 export { MaintenanceProcessor };
 /**
@@ -171,7 +211,7 @@ MaintenanceModule = __decorate([
             SandboxModule,
             ToolsModule,
             OrgsModule,
-            // the removed org plugins' cleanup and its daily sweep (worker-only through this module)
+            // the removed org plugins' cleanup job (worker-only through this module)
             OwnedPluginCleanupModule,
             // the scheduled task fire job and the scanner (worker-only through this module)
             ScheduledTaskFireModule,

package/dist/runtime/model-call.d.ts

@@ -1,4 +1,4 @@
-import { type ContentBlock, type Logger, type ModelRequest, type ModelStreamEvent, type ModelUsage, type StopReason } from "@capybara-hq/plugin-sdk";
+import { type ContentBlock, type ConversationSource, type Logger, type ModelRequest, type ModelStreamEvent, type ModelUsage, type StopReason } from "@capybara-hq/plugin-sdk";
 import type { AgentDefinition } from "../agents/definition.js";
 import type { AppendEvent, EventLog } from "../conversations/event-log.js";
 import { type ConversationEvent } from "../conversations/events.js";
@@ -11,7 +11,6 @@ import type { SubagentParent } from "./loop.js";
 import { MediaCache } from "./media-cache.js";
 import { type BoundProvider, type ProviderRegistry } from "./providers.js";
 import type { StepLog } from "./step-log.js";
-import type { UsageReporter } from "./usage-report.js";
 /** 单轮收尾的尾部提醒（模型可见，英文；spec 6 轮次额度收尾）。 */
 export declare const WRAP_UP_REMINDER = "Step limit reached. Do not call tools. Summarize what you found and what remains for the user.";
 /**
@@ -48,8 +47,11 @@ export type StreamSink = (delta: {
 export interface ModelStepDeps {
     db: KernelSchemaDb;
     eventLog: EventLog;
-    /** The step's transactional writes (a model call with its tool specs, a denial with its audit row, a sub-agent's counted usage). */
-    stepLog: Pick<StepLog, "appendCounted" | "appendAudited" | "appendWithSpecs">;
+    /**
+     * The step's transactional writes (a model call with its tool specs, a denial with its audit row,
+     * usage events with their owed `usage.report` deliveries, a sub-agent's counted usage).
+     */
+    stepLog: Pick<StepLog, "appendCounted" | "appendReported" | "appendAudited" | "appendWithSpecs">;
     registry: Pick<ProviderRegistry, "resolve">;
     /** 工具注册表：每步开始时解析 agent 引用的工具（状态可能在步骤之间变化）。 */
     tools: Pick<ToolRegistry, "forAgent">;
@@ -67,11 +69,6 @@ export interface ModelStepDeps {
      * `conversationKind: "chat"` on the step input.
      */
     hooks?: HookRunner;
-    /**
-     * `usage.report` delivery (P-17): each written `usage` event is enqueued (chat runs and full-run eval
-     * replays, which both log usage). `enqueue` never throws and returns at once without handlers.
-     */
-    usageReport?: Pick<UsageReporter, "enqueue">;
 }
 /** 构建请求用到的附件来源。 */
 export interface MediaSourceDeps {
@@ -107,6 +104,11 @@ export interface ModelStepInput {
     /** Hook payload scope: the run's agent, its trigger account and the conversation kind. */
     agentId?: string;
     accountId?: string;
+    /**
+     * The conversation's source (memory plugin spec §6.2): extension tools limited by
+     * `spec.sources` are listed by it.
+     */
+    source: ConversationSource;
     /** Hooks fire for `chat` and `subagent` (never for eval replays). */
     conversationKind?: ConversationKindForHooks;
     /** A sub-agent's run: where it was dispatched from (hook payloads carry it as `parent`). */
@@ -121,7 +123,8 @@ export interface ModelStepInput {
     parentRunId?: string;
     /**
      * The run's step limit (`LoopContext.limits.maxSteps`) for the turn-limit reminder; a child's
-     * may be below `runtime.maxSteps` (final review m4). Defaults to `runtime.maxSteps`.
+     * may be below `runtime.maxSteps` (final review m4). Absent: the run has no step limit, and no
+     * reminder is sent.
      */
     maxSteps?: number;
 }
@@ -176,15 +179,15 @@ export declare function runModelStep(deps: ModelStepDeps, input: ModelStepInput)
 export declare function runFinalWrapUp(deps: ModelStepDeps, input: ModelStepInput, reason?: WrapUpReason): Promise<ModelStepResult>;
 /**
  * Appends a model call's events (its reply or compaction outcome with its `usage`; also the usage
- * of a `WebFetch` extraction call, `tools/builtins/web/extract.ts`). For a
- * sub-agent's run (`input.parentRunId`) in one transaction that also adds the tokens of the usage
- * events it newly wrote to the budget run's `subagent_tokens_used` (sub-agents spec §8.3): a usage
- * event already in the log (an idempotent hit after a crash) adds nothing, so each call counts
- * exactly once.
+ * of a `WebFetch` extraction call, `tools/builtins/web/extract.ts`) in one transaction that also
+ * owes the `usage.report` delivery of the usage events it newly wrote (transactional outbox spec
+ * §8.1). For a sub-agent's run (`input.parentRunId`) that transaction also adds their tokens to the
+ * budget run's `subagent_tokens_used` (sub-agents spec §8.3): a usage event already in the log (an
+ * idempotent hit after a crash) adds nothing, so each call counts and is reported exactly once.
  */
 export declare function appendCounted(deps: {
-    eventLog: Pick<EventLog, "append" | "notify">;
-    stepLog: Pick<StepLog, "appendCounted">;
+    eventLog: Pick<EventLog, "notify">;
+    stepLog: Pick<StepLog, "appendCounted" | "appendReported">;
 }, input: {
     conversationId: string;
     parentRunId?: string | undefined;

package/dist/runtime/model-call.js

@@ -123,12 +123,6 @@ wrapUpReason) {
     const { conversationId, runId, step, signal, sink } = input;
     const existing = await findExisting(deps.eventLog, conversationId, runId, step);
     if (existing) {
-        // resumed after a crash between writing usage and enqueueing it: enqueue again (job id dedupes)
-        if (deps.usageReport && existing.usage !== null) {
-            const u = await deps.eventLog.findByIdem(conversationId, idem.usage(runId, step));
-            if (u)
-                void deps.usageReport.enqueue(conversationId, u.seq);
-        }
         // a crash between the assistant_message and clearing its draft leaves one behind
         sink({ kind: "step_end", runId, step });
         return existing;
@@ -165,6 +159,7 @@ wrapUpReason) {
             forkChild: input.parent?.forSkill === true,
             sandboxConversationId: input.parent?.rootConversationId ?? input.conversationId,
             replay: input.conversationKind === "eval",
+            source: input.source,
             skillLoad: skillLoadOffered(events.findLast((e) => e.type === "skills_catalog"), hasInvocation(events)),
         });
         const tools = {
@@ -230,8 +225,9 @@ wrapUpReason) {
             }
         }
         const { outcome, ref } = await ladder(deps, input, events, runtime, tools, wrapUpReason, streamed);
-        // assistant_message 与 usage 同一次 append = 同一事务。
-        const appended = await appendCounted(deps, input, [
+        // assistant_message and usage in one append = one transaction, which also owes the usage's
+        // usage.report delivery (transactional outbox spec §8.1)
+        await appendCounted(deps, input, [
             {
                 type: "assistant_message",
                 runId,
@@ -245,10 +241,6 @@ wrapUpReason) {
                 payload: { step, provider: ref.provider, model: ref.model, ...outcome.usage },
             },
         ]);
-        // usage.report metering (never awaited on the run's path; enqueue logs and swallows failures)
-        const usageEvent = appended.find((e) => e.type === "usage");
-        if (deps.usageReport && usageEvent)
-            void deps.usageReport.enqueue(conversationId, usageEvent.seq);
         sink({ kind: "step_end", runId, step });
         return {
             content: outcome.content,
@@ -277,18 +269,18 @@ wrapUpReason) {
 }
 /**
  * Appends a model call's events (its reply or compaction outcome with its `usage`; also the usage
- * of a `WebFetch` extraction call, `tools/builtins/web/extract.ts`). For a
- * sub-agent's run (`input.parentRunId`) in one transaction that also adds the tokens of the usage
- * events it newly wrote to the budget run's `subagent_tokens_used` (sub-agents spec §8.3): a usage
- * event already in the log (an idempotent hit after a crash) adds nothing, so each call counts
- * exactly once.
+ * of a `WebFetch` extraction call, `tools/builtins/web/extract.ts`) in one transaction that also
+ * owes the `usage.report` delivery of the usage events it newly wrote (transactional outbox spec
+ * §8.1). For a sub-agent's run (`input.parentRunId`) that transaction also adds their tokens to the
+ * budget run's `subagent_tokens_used` (sub-agents spec §8.3): a usage event already in the log (an
+ * idempotent hit after a crash) adds nothing, so each call counts and is reported exactly once.
  */
 export async function appendCounted(deps, input, events) {
     const { conversationId, parentRunId } = input;
-    if (parentRunId === undefined)
-        return deps.eventLog.append(conversationId, events);
     const budgetRunId = input.budgetRunId ?? input.parent?.budgetRunId;
-    const out = await deps.stepLog.appendCounted(conversationId, { parentRunId, ...(budgetRunId !== undefined && { budgetRunId }) }, events);
+    const out = parentRunId === undefined
+        ? await deps.stepLog.appendReported(conversationId, events)
+        : await deps.stepLog.appendCounted(conversationId, { parentRunId, ...(budgetRunId !== undefined && { budgetRunId }) }, events);
     if (out.toSeq !== null)
         await deps.eventLog.notify(conversationId, out.toSeq);
     return out.written;
@@ -691,9 +683,6 @@ async function maybeCompact(deps, input, events, runtime, tools) {
         });
     }
     const written = await appendCounted(deps, input, batch);
-    const usageEvent = written.find((e) => e.type === "usage");
-    if (deps.usageReport && usageEvent)
-        void deps.usageReport.enqueue(conversationId, usageEvent.seq);
     return mergeLocal(events, written);
 }
 /** Merges written events into the local list (idempotent hits already in it are not added twice). */
@@ -719,7 +708,9 @@ async function ladder(deps, input, events, runtime, tools, wrapUpReason, streame
         ? BUDGET_WRAP_UP_REMINDER
         : wrapUp
             ? WRAP_UP_REMINDER
-            : turnLimitReminder(step, input.maxSteps ?? runtime.maxSteps);
+            : input.maxSteps === undefined
+                ? null
+                : turnLimitReminder(step, input.maxSteps);
     let evs = events;
     const rungs = [
         { ref: agent.model, fallback: false },

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

@@ -0,0 +1,69 @@
+import { type ConversationSource } from "@capybara-hq/plugin-sdk";
+import { EventLog } from "../conversations/event-log.js";
+import { ExtensionPointDefaults } from "../extensions/point-defaults.js";
+import { ExtensionRegistry } from "../extensions/registry.js";
+import { KernelDb } from "../infra/database/kernel-db.js";
+import { TransactionHost } from "../infra/database/transaction-host.js";
+import type { KernelLogger } from "../log.js";
+import type { OrgRole } from "../orgs/roles.js";
+/** What a run start tells {@link PluginContextService.record}. */
+export interface PluginContextInput {
+    orgId: string;
+    conversationId: string;
+    runId: string;
+    agentId: string;
+    /** The run's agent definition name. */
+    agentName: string;
+    /** The conversation's owner (`conversations.account_id`) and display name. */
+    ownerAccountId: string;
+    ownerName: string;
+    /** The account whose message started the run. */
+    triggerAccountId: string;
+    source: ConversationSource;
+    /** The trigger account's role in the org. */
+    role: OrgRole;
+    /** The conversation's kind: only a chat run asks the providers. */
+    kind: "chat" | "eval" | "subagent";
+    /**
+     * The keys of the run's resolved tool set, by plugin (resolved with `forAgent` once, and only
+     * when some provider is asked).
+     */
+    toolKeysByPlugin: () => Promise<Map<string, string[]>>;
+    /** Aborts every provider call (with its own time limit). */
+    signal: AbortSignal;
+}
+/**
+ * Run start's plugin context (memory plugin spec §6.1): asks every `context@1` provider enabled in
+ * the org (valid config) for its text, in parallel and outside any transaction, each under the
+ * run's signal and {@link CONTEXT_LIMITS}.timeoutMs; then appends a `plugin_context` event for each
+ * plugin whose text differs from the latest one it recorded in the conversation. Fail open: a
+ * provider that throws, times out or returns too much is skipped for this run (its earlier text
+ * stays in effect) and logged. A provider loaded here that recorded text but no longer serves the
+ * org (switched off, its stored org config or its effective config invalid) gets an empty event,
+ * so its text stops following summaries; a plugin not loaded on this replica is left alone
+ * (another replica may still load it during a rollout, and blanking it here would make its text
+ * flap), and so is one whose status could not be read (a transient read error must not flip the
+ * model's context). Chat runs only: an
+ * eval replay reads the recorded events, and a sub-agent gets no plugin context (spec §5.4).
+ */
+export declare class PluginContextService {
+    private readonly db;
+    private readonly eventLog;
+    readonly txHost: TransactionHost;
+    private readonly points;
+    private readonly registry;
+    private readonly log;
+    constructor(db: KernelDb, eventLog: Pick<EventLog, "appendIn" | "notify">, txHost: TransactionHost, points: Pick<ExtensionPointDefaults, "providersFor">, registry: Pick<ExtensionRegistry, "list">, log: KernelLogger);
+    /** Asks the providers and records what changed (see the class); notifies after the commit. */
+    record(input: PluginContextInput): Promise<void>;
+    /** One provider's call, bounded by the run's signal and the time limit. */
+    private ask;
+    /**
+     * One transaction under the conversation row lock (as `RunContextService`): compares each
+     * answer's hash with the plugin's latest `plugin_context` and appends the ones that differ (a
+     * plugin with no earlier event and no text writes nothing), plus an empty event for each plugin
+     * in `off` whose latest text is not empty. Idem key per run and plugin, so a retried run
+     * start finds its events or nothing changed. Returns the last seq written.
+     */
+    private append;
+}

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

@@ -0,0 +1,208 @@
+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 { createHash } from "node:crypto";
+import { CONTEXT_LIMITS, } from "@capybara-hq/plugin-sdk";
+import { Inject, Injectable } from "@nestjs/common";
+import { EventLog } from "../conversations/event-log.js";
+import { ExtensionPointDefaults } from "../extensions/point-defaults.js";
+import { ExtensionRegistry } from "../extensions/registry.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 { KERNEL_LOGGER } from "../infra/tokens.js";
+import { latestPluginContexts, pluginContextIdemKey } from "./context/plugin-context.js";
+const sha256 = (text) => createHash("sha256").update(text).digest("hex");
+/**
+ * Run start's plugin context (memory plugin spec §6.1): asks every `context@1` provider enabled in
+ * the org (valid config) for its text, in parallel and outside any transaction, each under the
+ * run's signal and {@link CONTEXT_LIMITS}.timeoutMs; then appends a `plugin_context` event for each
+ * plugin whose text differs from the latest one it recorded in the conversation. Fail open: a
+ * provider that throws, times out or returns too much is skipped for this run (its earlier text
+ * stays in effect) and logged. A provider loaded here that recorded text but no longer serves the
+ * org (switched off, its stored org config or its effective config invalid) gets an empty event,
+ * so its text stops following summaries; a plugin not loaded on this replica is left alone
+ * (another replica may still load it during a rollout, and blanking it here would make its text
+ * flap), and so is one whose status could not be read (a transient read error must not flip the
+ * model's context). Chat runs only: an
+ * eval replay reads the recorded events, and a sub-agent gets no plugin context (spec §5.4).
+ */
+let PluginContextService = class PluginContextService {
+    db;
+    eventLog;
+    txHost;
+    points;
+    registry;
+    log;
+    constructor(db, eventLog, txHost, points, registry, log) {
+        this.db = db;
+        this.eventLog = eventLog;
+        this.txHost = txHost;
+        this.points = points;
+        this.registry = registry;
+        this.log = log;
+    }
+    /** Asks the providers and records what changed (see the class); notifies after the commit. */
+    async record(input) {
+        if (input.kind !== "chat")
+            return;
+        let found;
+        try {
+            found = await this.points.providersFor(input.orgId, "context");
+        }
+        catch (err) {
+            // fail open: without the org's providers nothing is asked and nothing is switched off
+            this.log.warn("context providers could not be listed; plugin context left as recorded", {
+                orgId: input.orgId,
+                conversationId: input.conversationId,
+                runId: input.runId,
+                err,
+            });
+            return;
+        }
+        const { providers } = found;
+        const tools = providers.length > 0 ? await input.toolKeysByPlugin() : new Map();
+        const answers = await Promise.all(providers.map(async (p) => {
+            const answer = await this.ask(p, input, tools.get(p.extension) ?? []);
+            if (!answer.ok) {
+                this.log.warn("context provider skipped for this run", {
+                    orgId: input.orgId,
+                    conversationId: input.conversationId,
+                    runId: input.runId,
+                    plugin: p.extension,
+                    reason: answer.reason,
+                });
+            }
+            return [p.extension, answer];
+        }));
+        const texts = new Map();
+        for (const [plugin, answer] of answers)
+            if (answer.ok)
+                texts.set(plugin, answer.text);
+        const serving = new Set(providers.map((p) => p.extension));
+        const off = new Set(this.registry
+            .list("context")
+            .map((e) => e.plugin)
+            // a provider whose status could not be read (a transient error) keeps its recorded text
+            .filter((plugin) => !serving.has(plugin) && !found.failed.has(plugin)));
+        // nothing answered and nothing to switch off: no transaction, no row lock
+        if (texts.size === 0 && off.size === 0)
+            return;
+        const seq = await this.append(input, texts, off);
+        if (seq !== null)
+            await this.eventLog.notify(input.conversationId, seq);
+    }
+    /** One provider's call, bounded by the run's signal and the time limit. */
+    async ask(p, input, tools) {
+        const signal = AbortSignal.any([input.signal, AbortSignal.timeout(CONTEXT_LIMITS.timeoutMs)]);
+        let result;
+        try {
+            result = await untilAborted(Promise.resolve().then(() => p.impl.provide({
+                orgId: input.orgId,
+                accountId: input.triggerAccountId,
+                agentId: input.agentId,
+                agentName: input.agentName,
+                conversationId: input.conversationId,
+                runId: input.runId,
+                source: input.source,
+                role: input.role,
+                ownerAccountId: input.ownerAccountId,
+                ownerName: input.ownerName,
+                tools,
+                config: p.config,
+                signal,
+            })), signal);
+        }
+        catch (err) {
+            if (signal.aborted) {
+                return { ok: false, reason: input.signal.aborted ? "run aborted" : "timed out" };
+            }
+            return { ok: false, reason: `threw: ${err instanceof Error ? err.message : String(err)}` };
+        }
+        if (result === null)
+            return { ok: true, text: "" };
+        const text = result?.text;
+        if (typeof text !== "string")
+            return { ok: false, reason: "returned no text" };
+        const bytes = Buffer.byteLength(text, "utf8");
+        if (bytes > CONTEXT_LIMITS.maxBytes) {
+            return { ok: false, reason: `text of ${bytes} bytes is over ${CONTEXT_LIMITS.maxBytes}` };
+        }
+        return { ok: true, text };
+    }
+    /**
+     * One transaction under the conversation row lock (as `RunContextService`): compares each
+     * answer's hash with the plugin's latest `plugin_context` and appends the ones that differ (a
+     * plugin with no earlier event and no text writes nothing), plus an empty event for each plugin
+     * in `off` whose latest text is not empty. Idem key per run and plugin, so a retried run
+     * start finds its events or nothing changed. Returns the last seq written.
+     */
+    async append(input, texts, off) {
+        const t = this.db.db;
+        await t
+            .selectFrom("conversations")
+            .select("id")
+            .where("id", "=", input.conversationId)
+            .forUpdate()
+            .executeTakeFirst();
+        const rows = await t
+            .selectFrom("conversation_events")
+            .select(["seq", "payload"])
+            .where("conversation_id", "=", input.conversationId)
+            .where("type", "=", "plugin_context")
+            .orderBy("seq", "asc")
+            .execute();
+        const latest = latestPluginContexts(rows.map((r) => ({ type: "plugin_context", seq: Number(r.seq), payload: r.payload })), Number.POSITIVE_INFINITY);
+        const next = new Map(texts);
+        for (const [plugin, prev] of latest) {
+            if (off.has(plugin) && prev.text !== "")
+                next.set(plugin, "");
+        }
+        const changed = [...next]
+            .filter(([plugin, text]) => {
+            const prev = latest.get(plugin);
+            return prev === undefined ? text !== "" : prev.hash !== sha256(text);
+        })
+            .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
+        if (changed.length === 0)
+            return null;
+        const written = await this.eventLog.appendIn(input.conversationId, changed.map(([plugin, text]) => ({
+            type: "plugin_context",
+            runId: input.runId,
+            idemKey: pluginContextIdemKey(input.runId, plugin),
+            payload: { plugin, text, hash: sha256(text) },
+        })));
+        return Math.max(...written.map((e) => e.seq));
+    }
+};
+__decorate([
+    Transactional()
+], PluginContextService.prototype, "append", null);
+PluginContextService = __decorate([
+    Injectable(),
+    __param(0, Inject(KernelDb)),
+    __param(1, Inject(EventLog)),
+    __param(2, Inject(TransactionHost)),
+    __param(3, Inject(ExtensionPointDefaults)),
+    __param(4, Inject(ExtensionRegistry)),
+    __param(5, Inject(KERNEL_LOGGER))
+], PluginContextService);
+export { PluginContextService };
+/** `p`, or a rejection once `signal` aborts (a provider that ignores its signal never holds a run). */
+function untilAborted(p, signal) {
+    return new Promise((resolve, reject) => {
+        const onAbort = () => reject(signal.reason);
+        if (signal.aborted) {
+            onAbort();
+            return;
+        }
+        signal.addEventListener("abort", onAbort, { once: true });
+        p.then(resolve, reject).finally(() => signal.removeEventListener("abort", onAbort));
+    });
+}