@capybara-hq/kernel 0.1.0-rc.24 → 0.1.0-rc.26

package/dist/evals/run-replay.js

@@ -18,6 +18,7 @@ import { ApiError } from "../errors.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 { pluginContextIdemKey } from "../runtime/context/plugin-context.js";
 import { estimateTokens } from "../runtime/context/tokens.js";
 import { runDeadline, tightestLimit } from "../runtime/limits.js";
 import { RunError } from "../runtime/model-call.js";
@@ -36,7 +37,7 @@ export class ReplayClaimLost extends Error {
 /**
  * The seed of a full-run replay (C6): the `kind = 'eval'` conversation with the events before the
  * original run at their original seqs, the run row and its `run_started` (and the original
- * `skills_catalog`), in one transaction of its own.
+ * `skills_catalog`, `run_context` and `plugin_context` events), in one transaction of its own.
  */
 let EvalReplaySeeder = class EvalReplaySeeder {
     db;
@@ -74,6 +75,7 @@ let EvalReplaySeeder = class EvalReplaySeeder {
             consumed_seq: p.consumed,
             kind: "eval",
             eval_run_id: evalRunId,
+            source: p.source,
         })
             .execute();
         for (let i = 0; i < p.seeds.length; i += SEED_BATCH) {
@@ -133,6 +135,12 @@ let EvalReplaySeeder = class EvalReplaySeeder {
                     },
                 ]
                 : []),
+            ...p.pluginContexts.map((c) => ({
+                type: "plugin_context",
+                runId,
+                idemKey: pluginContextIdemKey(runId, c.payload.plugin),
+                payload: c.payload,
+            })),
         ]);
         if (onSeeded && !(await onSeeded(conversationId)))
             throw new ReplayClaimLost();
@@ -333,6 +341,9 @@ export async function replayRun(d, s, candidate, evalRunId, signal) {
     const trigger = replayTrigger(start.payload, seeds, consumed);
     const catalog = s.events.find((e) => e.runId === s.runId && e.type === "skills_catalog" && e.seq > R);
     const runContext = s.events.find((e) => e.runId === s.runId && e.type === "run_context" && e.seq > R);
+    const pluginContexts = s.events
+        .filter((e) => e.runId === s.runId && e.type === "plugin_context" && e.seq > R)
+        .map((e) => ({ payload: e.payload }));
     // a sub-agent's case (spec §15.3) runs the effective definition frozen in its subagent_started
     // (the request renders that event's preamble and instructions; its tools come from it too), with
     // only the candidate's model and params, and the logged step limit
@@ -348,12 +359,16 @@ export async function replayRun(d, s, candidate, evalRunId, signal) {
     const forkRun = triggerEvent?.type === "user_message" &&
         triggerEvent.payload.skill !== undefined &&
         triggerEvent.payload.dispatch !== undefined;
+    // the original conversation's source (recorded in the case); a case taken before it was
+    // recorded replays as its run did by default: a web conversation, or a sub-agent's for a child
+    const source = s.source ?? (subagent === undefined ? "web" : "subagent");
     const conversationId = randomUUID();
     const runId = randomUUID();
     await d.seeder.seed({
         evalRunId,
         orgId: s.orgId,
         agentId: s.agentId,
+        source,
         accountId,
         conversationId,
         runId,
@@ -365,6 +380,7 @@ export async function replayRun(d, s, candidate, evalRunId, signal) {
         model: agent.model,
         catalog,
         runContext,
+        pluginContexts,
     }, d.onSeeded);
     await d.hooks?.afterRunSeeded?.(evalRunId, conversationId);
     // 停止：取消 / 越限 / 熔断 / 失去认领 / 截止时间 → 中止 loop（进行中的请求立即停下，loop 以 aborted 返回）
@@ -542,6 +558,13 @@ export async function replayRun(d, s, candidate, evalRunId, signal) {
     // a fork invocation's report is the recorded one: a replay never dispatches a sub-agent (A5)
     const skillForks = recordedSkillForks(eventLog, s.events.filter((e) => e.runId === s.runId));
     const loop = d.loop({ toolPipeline: pipeline, registry, skillForks, ...(media && { media }) });
+    // a replay never executes a tool, so the role only completes the context
+    const membership = await db
+        .selectFrom("memberships")
+        .select("role")
+        .where("org_id", "=", s.orgId)
+        .where("account_id", "=", accountId)
+        .executeTakeFirst();
     let outcome;
     try {
         outcome = await loop.run({
@@ -550,6 +573,10 @@ export async function replayRun(d, s, candidate, evalRunId, signal) {
             runId,
             agentId: s.agentId,
             triggerAccountId: accountId,
+            // the seeded conversation's source (the original's): its tools are the original's
+            source,
+            ownerAccountId: accountId,
+            role: membership?.role ?? "guest",
             agent,
             agentVersion: candidate.agentVersion,
             signal: loopSignal,

package/dist/evals/runs.service.d.ts

@@ -145,7 +145,7 @@ export declare const RESULTS_ASOF_OVERLAP_MS = 15000;
 export declare class EvalRunsService {
     readonly txHost: TransactionHost;
     private readonly d;
-    constructor(kdb: KernelDb, orgLock: OrgLock, locks: LockService, config: KernelConfigService, registry: ProviderRegistry, prices: PricesService, settings: SettingsService, queue: EvalJobs, budget: EvalBudget, purposes: ModelPurposesService, txHost: TransactionHost);
+    constructor(kdb: KernelDb, orgLock: OrgLock, locks: LockService, config: KernelConfigService, registry: ProviderRegistry, prices: PricesService, settings: SettingsService, jobs: EvalJobs, budget: EvalBudget, purposes: ModelPurposesService, txHost: TransactionHost);
     private liveSet;
     /**
      * 解析模型；不存在 / 不可用 → `eval.candidate_invalid`（供应商列表暂时失败照常抛出）。
@@ -187,8 +187,9 @@ export declare class EvalRunsService {
     private tokenCaps;
     /**
      * 启动：校验 token 上限（[1, `evals.maxTokenCap`]，缺省 `evals.defaultTokenCap`）、候选、评委用途；
-     * 没有可回放的 → `eval.nothing_to_replay`。事务内建运行行、预建 pending 结果，提交后每个用例入队一个任务；
-     * 入队失败 → 运行标 failed、结果 skipped，错误照常抛出。
+     * 没有可回放的 → `eval.nothing_to_replay`。One transaction writes the run row and its pending
+     * results and owes one case job per valid case (transactional outbox spec §3): the outbox adds
+     * them after the commit, so a run never waits for a job that was never added.
      */
     start(orgId: string, actor: string, setId: string, input: {
         mode: "step" | "run";
@@ -196,10 +197,8 @@ export declare class EvalRunsService {
         judge: boolean;
         tokenCap?: number;
     }, actorTokenId?: string, auditDetail?: Record<string, unknown>): Promise<EvalRunView>;
-    /** The run row and its pending results, in a transaction of their own (enqueued after the commit). */
+    /** The run row, its pending results and its owed case jobs, in a transaction of their own. */
     private startIn;
-    /** The enqueue failed: the run is `failed`, its pending results `skipped`. */
-    private failStartIn;
     /** 各运行的汇总（只算已结束的）。 */
     private summaries;
     private static toView;

package/dist/evals/runs.service.js

@@ -154,7 +154,7 @@ const resultsViewedKey = (runId, accountId) => `capk:eval-results-viewed:${runId
 let EvalRunsService = EvalRunsService_1 = class EvalRunsService {
     txHost;
     d;
-    constructor(kdb, orgLock, locks, config, registry, prices, settings, queue, budget, purposes, txHost) {
+    constructor(kdb, orgLock, locks, config, registry, prices, settings, jobs, budget, purposes, txHost) {
         this.txHost = txHost;
         this.d = {
             orgLock,
@@ -166,7 +166,7 @@ let EvalRunsService = EvalRunsService_1 = class EvalRunsService {
             registry,
             prices,
             settings,
-            queue,
+            jobs,
             budget,
             purposes,
         };
@@ -415,8 +415,9 @@ let EvalRunsService = EvalRunsService_1 = class EvalRunsService {
     }
     /**
      * 启动：校验 token 上限（[1, `evals.maxTokenCap`]，缺省 `evals.defaultTokenCap`）、候选、评委用途；
-     * 没有可回放的 → `eval.nothing_to_replay`。事务内建运行行、预建 pending 结果，提交后每个用例入队一个任务；
-     * 入队失败 → 运行标 failed、结果 skipped，错误照常抛出。
+     * 没有可回放的 → `eval.nothing_to_replay`。One transaction writes the run row and its pending
+     * results and owes one case job per valid case (transactional outbox spec §3): the outbox adds
+     * them after the commit, so a run never waits for a job that was never added.
      */
     async start(orgId, actor, setId, input, actorTokenId, auditDetail) {
         const set = await this.liveSet(orgId, setId);
@@ -435,17 +436,10 @@ let EvalRunsService = EvalRunsService_1 = class EvalRunsService {
         if (firstProblem) {
             throw candidateInvalid(firstProblem.message, firstProblem.details ?? []);
         }
-        const { runId, plans } = await this.startIn(orgId, actor, setId, set.agent_id, input, tokenCap, planned, judge, actorTokenId, auditDetail);
-        try {
-            await this.d.queue.enqueue(plans.map((p) => ({ runId, caseId: p.caseId, orgId })));
-        }
-        catch (e) {
-            await this.failStartIn(runId);
-            throw e;
-        }
+        const { runId } = await this.startIn(orgId, actor, setId, set.agent_id, input, tokenCap, planned, judge, actorTokenId, auditDetail);
         return this.get(orgId, runId);
     }
-    /** The run row and its pending results, in a transaction of their own (enqueued after the commit). */
+    /** The run row, its pending results and its owed case jobs, in a transaction of their own. */
     async startIn(orgId, actor, setId, agentId, input, tokenCap, planned, judge, actorTokenId, auditDetail) {
         const db = this.d.db;
         await this.d.orgLock.lockAndAuthorize(orgId, actor, "evals.manage");
@@ -521,23 +515,10 @@ let EvalRunsService = EvalRunsService_1 = class EvalRunsService {
             },
         });
         await this.d.budget.recountCases(run.id);
-        return { runId: run.id, plans: plans.filter((p) => p.problem === null) };
-    }
-    /** The enqueue failed: the run is `failed`, its pending results `skipped`. */
-    async failStartIn(runId) {
-        const db = this.d.db;
-        await db
-            .updateTable("eval_runs")
-            .set({ status: "failed", finished_at: sql `now()` })
-            .where("id", "=", runId)
-            .execute();
-        await db
-            .updateTable("eval_results")
-            .set({ status: "skipped", updated_at: sql `now()` })
-            .where("run_id", "=", runId)
-            .where("status", "=", "pending")
-            .execute();
-        await this.d.budget.recountCases(runId);
+        await this.d.jobs.owe(plans
+            .filter((p) => p.problem === null)
+            .map((p) => ({ runId: run.id, caseId: p.caseId, orgId })));
+        return { runId: run.id };
     }
     /** 各运行的汇总（只算已结束的）。 */
     async summaries(rows) {
@@ -836,9 +817,6 @@ let EvalRunsService = EvalRunsService_1 = class EvalRunsService {
 __decorate([
     Transactional({ propagation: "requires_new" })
 ], EvalRunsService.prototype, "startIn", null);
-__decorate([
-    Transactional({ propagation: "requires_new" })
-], EvalRunsService.prototype, "failStartIn", null);
 __decorate([
     Transactional({ propagation: "requires_new" })
 ], EvalRunsService.prototype, "cancelIn", null);

package/dist/evals/snapshot.d.ts

@@ -1,4 +1,4 @@
-import type { ToolSpec } from "@capybara-hq/plugin-sdk";
+import type { ConversationSource, ToolSpec } from "@capybara-hq/plugin-sdk";
 import { type AgentDefinition } from "../agents/definition.js";
 import type { ConversationEvent, ConversationEventType } from "../conversations/events.js";
 import type { KernelSchemaDb } from "../db/kernel-schema.js";
@@ -21,6 +21,12 @@ export interface CaseSnapshot {
     runId: string;
     agentId: string;
     agentVersion: number;
+    /**
+     * The original conversation's source (memory plugin spec §6.2): a full-run replay offers the
+     * tools of this source. Cases taken before it was recorded have none (replayed as `web`, or as
+     * `subagent` for a child case).
+     */
+    source?: ConversationSource;
     /** seq ≤ 该运行终态事件的 seq，按 seq 升序。 */
     events: SnapshotEvent[];
     /** 事件里各次运行（`run_started`）与本运行引用的 agent 版本 → 定义。 */

package/dist/evals/snapshot.js

@@ -17,7 +17,7 @@ const PAGE = 1000;
 export async function takeSnapshot(db, orgId, conversationId, runId, maxBytes) {
     const conv = await db
         .selectFrom("conversations")
-        .select(["agent_id", "kind"])
+        .select(["agent_id", "kind", "source"])
         .where("id", "=", conversationId)
         .where("org_id", "=", orgId)
         .executeTakeFirst();
@@ -126,6 +126,7 @@ export async function takeSnapshot(db, orgId, conversationId, runId, maxBytes) {
         runId,
         agentId: conv.agent_id,
         agentVersion: run.agent_version,
+        source: conv.source,
         events,
         definitions,
         toolSpecs,

package/dist/extensions/hooks.d.ts

@@ -1,4 +1,4 @@
-import { type AvailableHook, type HookHandler, type HookOptions, type HookPayloads, type Logger, type PolicyHook } from "@capybara-hq/plugin-sdk";
+import { type AvailableHook, type HookHandler, type HookOptions, type HookPayloads, type LIFECYCLE_HOOKS, type Logger, type PolicyHook } from "@capybara-hq/plugin-sdk";
 import type { KernelConfig } from "../config/schema.js";
 import type { LockService } from "../infra/lock/lock.service.js";
 import { type EffectiveConfig } from "./effective-config.js";
@@ -63,7 +63,16 @@ export interface HookSource {
     readonly name: string;
     readonly hooks: readonly RegisteredHook[];
     readonly inflight: InflightTracker;
+    /** The instance's platform deployment config (what lifecycle hooks are called with). */
+    readonly config?: unknown;
 }
+/** A lifecycle mount: an observe-only notice that a member, an agent or an org was removed. */
+export type LifecycleHook = (typeof LIFECYCLE_HOOKS)[number];
+/**
+ * Mounts delivered by a queue (at least once, by plugin) instead of {@link HookRegistry.run}:
+ * `usage.report` and the lifecycle mounts.
+ */
+export type QueuedHook = "usage.report" | LifecycleHook;
 /** Error text that never throws itself (a hostile `message` getter or `toString`). */
 export declare function errMsg(e: unknown): string;
 /**
@@ -166,8 +175,18 @@ export declare class HookRegistry {
         plugin: string;
         handler: HookHandler<"usage.report">;
     }[];
-    /** Runs the hooks of a mount point (see the class comment). */
-    run<K extends Exclude<AvailableHook, "usage.report">>(mount: K, payload: HookPayloads[K], signal: AbortSignal): Promise<HookOutcome>;
+    /**
+     * Lifecycle handlers by plugin name (delivered by the lifecycle queue, `lifecycle-hooks.ts`, not
+     * by {@link run}). Each call runs through the instance's `inflight.run` with the plugin's platform
+     * deployment config, never an org's copy: cleanup goes out whether or not the org's effective
+     * config is valid (or the org still exists).
+     */
+    lifecycleHandlers<K extends LifecycleHook>(mount: K): {
+        plugin: string;
+        handler: HookHandler<K>;
+    }[];
+    /** Runs the hooks of a mount point (see the class comment); queue-delivered mounts excluded. */
+    run<K extends Exclude<AvailableHook, QueuedHook>>(mount: K, payload: HookPayloads[K], signal: AbortSignal): Promise<HookOutcome>;
     /**
      * The M-1 denial: `missing` (sorted) are enabled policy plugins that are not loaded on this replica.
      * The model-visible reason is generic; the detail and a throttled warning name the plugin for the

package/dist/extensions/hooks.js

@@ -189,7 +189,21 @@ export class HookRegistry {
             }),
         }));
     }
-    /** Runs the hooks of a mount point (see the class comment). */
+    /**
+     * Lifecycle handlers by plugin name (delivered by the lifecycle queue, `lifecycle-hooks.ts`, not
+     * by {@link run}). Each call runs through the instance's `inflight.run` with the plugin's platform
+     * deployment config, never an org's copy: cleanup goes out whether or not the org's effective
+     * config is valid (or the org still exists).
+     */
+    lifecycleHandlers(mount) {
+        return this.entries(mount).map(({ src, hook }) => ({
+            plugin: src.name,
+            handler: (payload, signal) => src.inflight.run(signal, async (s) => {
+                await hook.handler(payload, s, { config: src.config });
+            }),
+        }));
+    }
+    /** Runs the hooks of a mount point (see the class comment); queue-delivered mounts excluded. */
     async run(mount, payload, signal) {
         if (signal.aborted)
             throw signal.reason;

package/dist/extensions/lifecycle-hooks.d.ts

@@ -0,0 +1,99 @@
+import type { HookPayloads } from "@capybara-hq/plugin-sdk";
+import { WorkerHost } from "@nestjs/bullmq";
+import type { Job, Worker } from "bullmq";
+import type { KernelSchemaDb } from "../db/kernel-schema.js";
+import { KernelDb } from "../infra/database/kernel-db.js";
+import { TransactionHost } from "../infra/database/transaction-host.js";
+import { OutboxService } from "../infra/outbox/outbox.service.js";
+import type { KernelLogger } from "../log.js";
+import { type LifecycleHook } from "./hooks.js";
+import { ExtensionHost } from "./host.js";
+/** Queue of lifecycle hook deliveries (no `:` in the name). */
+export declare const LIFECYCLE_QUEUE = "cap-kernel-lifecycle";
+/** The job name of every delivery (registered in `infra/outbox/registry.ts`). */
+export declare const LIFECYCLE_JOB = "lifecycle";
+/** One handler call's time limit. */
+export declare const LIFECYCLE_HOOK_TIMEOUT_MS = 5000;
+/** Job data: one mount's payload for one subscribing plugin. */
+export interface LifecycleJob<K extends LifecycleHook = LifecycleHook> {
+    mount: K;
+    plugin: string;
+    payload: HookPayloads[K];
+}
+/**
+ * The deterministic job id of one delivery: the mount, the plugin and the payload's ids (no `:`;
+ * kernel ids and plugin names carry none). Removing the same member, agent or org again while the
+ * first delivery is still owed is the same job.
+ */
+export declare function lifecycleJobId<K extends LifecycleHook>(mount: K, plugin: string, payload: HookPayloads[K]): string;
+/**
+ * Plugins that subscribe to a lifecycle mount according to deployment state: the approved
+ * permission snapshot declares the mount in `permissions.hooks`, and that approved version is the
+ * one the deployment runs: an enabled install of that version, or a replica status row (not
+ * `unloaded`) that loaded or still serves it (an upgrade pending approval keeps serving the
+ * approved version; a config-declared plugin has only replica rows). A snapshot approved for
+ * another version than the one installed or served does not count. Org enablement does not count
+ * either: cleanup concerns data the plugin already holds (memory plugin spec §6.3). Sorted by name.
+ */
+export declare function queryLifecycleSubscribers(db: KernelSchemaDb, mount: LifecycleHook): Promise<string[]>;
+/**
+ * Durable delivery of the lifecycle hooks `org.member_removed`, `agent.deleted` and `org.deleted`
+ * (memory plugin spec §6.3), so extensions reliably learn to delete the data they hold:
+ * - **Owe** ({@link recordIn}): in the transaction that removes the member, the agent or the org,
+ *   one outbox job per subscribing plugin ({@link queryLifecycleSubscribers}) on
+ *   {@link LIFECYCLE_QUEUE}, under {@link lifecycleJobId}, with no `org_id` (it is the deletion's
+ *   own cleanup work, transactional outbox spec §9); a rollback owes nothing. The outbox delivers
+ *   it to BullMQ after the commit (registry: attempts and backoff).
+ * - **Deliver** ({@link process}, worker role): the plugin's handlers loaded on this replica are
+ *   called in turn (5 s each). Not loaded on this replica -> the job fails and is retried (another
+ *   replica or a later attempt). Loaded without a handler -> dropped with a warning. Handlers get
+ *   the plugin's platform deployment config (`call.config`), never an org's copy, so an org whose
+ *   effective config is not valid still gets its cleanup. The last failed attempt logs an error.
+ * Handlers must be idempotent (a delivery may repeat when a replica dies after the call).
+ */
+export declare class LifecycleHooks {
+    private readonly kdb;
+    readonly txHost: TransactionHost;
+    private readonly outbox;
+    /** The loaded plugins' handlers (`hooks.handlers`) and whether a plugin is active here. */
+    private readonly host;
+    private readonly log;
+    constructor(kdb: KernelDb, txHost: TransactionHost, outbox: Pick<OutboxService, "add">, 
+    /** The loaded plugins' handlers (`hooks.handlers`) and whether a plugin is active here. */
+    host: Pick<ExtensionHost, "hooks" | "current">, log: KernelLogger);
+    /**
+     * Owes one delivery per subscribing plugin in the caller's transaction (`mandatory`); returns
+     * the plugins.
+     */
+    recordIn<K extends LifecycleHook>(mount: K, payload: HookPayloads[K]): Promise<string[]>;
+    /** One delivery job (the consumer {@link LifecycleHooksProcessor} calls it). */
+    process(data: LifecycleJob, stop: AbortSignal): Promise<void>;
+    /** One handler call, aborted after {@link LIFECYCLE_HOOK_TIMEOUT_MS} or when the replica stops. */
+    private call;
+    /** A job failed (the worker's `failed` event): a retry warns, the last attempt logs an error. */
+    onFailed(j: Job<LifecycleJob> | undefined, err: Error): void;
+}
+/**
+ * The consumer of {@link LIFECYCLE_QUEUE}: {@link LifecycleHooks.process}. Worker role only
+ * (`LifecycleHookWorkersModule`); built with `autorun: false`, started by the worker role after the
+ * extensions loaded.
+ */
+export declare class LifecycleHooksProcessor extends WorkerHost<Worker<LifecycleJob>> {
+    private readonly hooks;
+    private readonly log;
+    private readonly stopping;
+    constructor(hooks: LifecycleHooks, log: Pick<KernelLogger, "error">);
+    process(job: Job<LifecycleJob>): Promise<void>;
+    /** Starts consuming (worker role, after the extensions loaded). */
+    start(): void;
+    /** Aborts the calls in flight and closes the worker. */
+    close(): Promise<void>;
+    failed(job: Job<LifecycleJob> | undefined, err: Error): void;
+    error(err: Error): void;
+}
+/** Lifecycle hook delivery: owing the jobs, and the queue the outbox adds them to, on every role. */
+export declare class LifecycleHooksModule {
+}
+/** The lifecycle queue's consumer; imported only by the worker role (`WorkerModule`). */
+export declare class LifecycleHookWorkersModule {
+}