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

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));
+    });
+}

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

@@ -17,7 +17,7 @@ export declare class RunControl {
     /** Owes a deleted root's tree stop in the delete's transaction. */
     private readonly outbox;
     private readonly log;
-    constructor(queue: Pick<RunQueue, "ensureRun" | "oweEnsureRun" | "abortIfOrphaned" | "wakeHeldTree" | "oweHeldTreeIn">, waits: Pick<Waits, "abortWaiting" | "childFinished" | "stopChildren" | "stopTree">, abort: Pick<RunAbort, "request">, 
+    constructor(queue: Pick<RunQueue, "ensureRun" | "oweEnsureRun" | "abortIfOrphaned" | "abortQueued" | "wakeHeldTree" | "oweHeldTreeIn">, waits: Pick<Waits, "abortWaiting" | "childFinished" | "stopChildren" | "stopTree">, abort: Pick<RunAbort, "request">, 
     /** The resume of a waiting run in a decision's transaction (a reply's skips). */
     resumes: Pick<RunResume, "resumeIn">, 
     /** Owes a deleted root's tree stop in the delete's transaction. */
@@ -61,6 +61,11 @@ export declare class RunControl {
      * stops its children (sub-agents spec §12).
      */
     abortIfOrphaned(conversationId: string, runId: string, byAccountId: string | null): Promise<boolean>;
+    /**
+     * Ends a run still `queued` in PG ({@link RunQueue.abortQueued}; the caller wrote the stop marker
+     * first): true when it did. A stopped sub-agent then reports to its parent at once.
+     */
+    abortQueued(conversationId: string, runId: string, byAccountId: string | null): Promise<boolean>;
     /**
      * 运行在等人处理（waiting）时直接中止：取消等待、写 `run_aborted`、删除 checkpoint，返回 true；
      * 运行已不是 waiting（例如刚被续跑）→ false. The stop's transaction owes the IM delivery that

package/dist/runtime/run-control.js

@@ -110,6 +110,19 @@ let RunControl = class RunControl {
         }
         return r;
     }
+    /**
+     * Ends a run still `queued` in PG ({@link RunQueue.abortQueued}; the caller wrote the stop marker
+     * first): true when it did. A stopped sub-agent then reports to its parent at once.
+     */
+    async abortQueued(conversationId, runId, byAccountId) {
+        const r = await this.queue.abortQueued(conversationId, runId, byAccountId);
+        if (r) {
+            await this.waits
+                .childFinished(runId)
+                .catch((err) => this.log.error("cannot report finished sub-agent run to its parent", { runId, err }));
+        }
+        return r;
+    }
     /**
      * 运行在等人处理（waiting）时直接中止：取消等待、写 `run_aborted`、删除 checkpoint，返回 true；
      * 运行已不是 waiting（例如刚被续跑）→ false. The stop's transaction owes the IM delivery that

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

@@ -148,6 +148,19 @@ export declare class RunQueue {
      */
     abortIfOrphaned(conversationId: string, runId: string, byAccountId: string | null, detail?: RunAbortDetail): Promise<boolean>;
     private abortOrphanIn;
+    /**
+     * Ends a `queued` run in PG before any worker started it (an offboarded member's run, ruling
+     * R27): with the conversation lock free, under the conversation row lock, a run still `queued`
+     * is finished `aborted` with `run_aborted` (`consumed_seq` at least to its trigger), so a job
+     * that runs later finds it finished and starts nothing. True when it did; false when a worker
+     * holds the conversation or is in the middle of the run's first start (`run_started` written,
+     * `started_at` not yet set; it hears the stop), or the run is no longer queued. A run resumed
+     * from `waiting` to `queued` is ended like a new one. The caller writes the stop marker first, so a worker that takes the
+     * conversation meanwhile still stops; a worker that read the run before this commit re-checks it
+     * under the row locks before its `run_started` and never moves it back to `running`.
+     */
+    abortQueued(conversationId: string, runId: string, byAccountId: string | null): Promise<boolean>;
+    private abortQueuedIn;
     /** 会话当前未结束的运行（调用方已持有会话行锁）。 */
     private activeRun;
     /**

package/dist/runtime/run-queue.js

@@ -567,6 +567,66 @@ let RunQueue = class RunQueue {
             },
         });
     }
+    /**
+     * Ends a `queued` run in PG before any worker started it (an offboarded member's run, ruling
+     * R27): with the conversation lock free, under the conversation row lock, a run still `queued`
+     * is finished `aborted` with `run_aborted` (`consumed_seq` at least to its trigger), so a job
+     * that runs later finds it finished and starts nothing. True when it did; false when a worker
+     * holds the conversation or is in the middle of the run's first start (`run_started` written,
+     * `started_at` not yet set; it hears the stop), or the run is no longer queued. A run resumed
+     * from `waiting` to `queued` is ended like a new one. The caller writes the stop marker first, so a worker that takes the
+     * conversation meanwhile still stops; a worker that read the run before this commit re-checks it
+     * under the row locks before its `run_started` and never moves it back to `running`.
+     */
+    async abortQueued(conversationId, runId, byAccountId) {
+        if ((await this.lock.holder(conversationId)) !== null)
+            return false;
+        const toSeq = await this.abortQueuedIn(conversationId, runId, byAccountId);
+        if (toSeq === null)
+            return false;
+        await notifyFinished(this.eventLog, conversationId, toSeq, "aborted");
+        await this.dropCheckpoints(runId);
+        return true;
+    }
+    async abortQueuedIn(conversationId, runId, byAccountId) {
+        const t = this.db;
+        const conv = await t
+            .selectFrom("conversations")
+            .select("id")
+            .where("id", "=", conversationId)
+            .forUpdate()
+            .executeTakeFirst();
+        const active = await this.activeRun(t, conversationId);
+        if (!conv || !active || active.id !== runId || active.status !== "queued")
+            return null;
+        // a worker is in the middle of the run's FIRST start (its `run_started` written, `started_at`
+        // not set yet; it holds the conversation since): the stop marker ends it. A run resumed from
+        // `waiting` back to `queued` has both from its first start and is ended here like a new one:
+        // its worker skips `run_started` (it exists) and its conditional `running` update finds the run
+        // finished
+        const first = await t
+            .selectFrom("runs")
+            .select("started_at")
+            .where("id", "=", runId)
+            .executeTakeFirst();
+        if (first?.started_at === null) {
+            const started = await t
+                .selectFrom("conversation_events")
+                .select("seq")
+                .where("conversation_id", "=", conversationId)
+                .where("idem_key", "=", `run_started:${runId}`)
+                .executeTakeFirst();
+            if (started)
+                return null;
+        }
+        return this.finisher.finishIn({
+            conversationId,
+            runId,
+            status: "aborted",
+            consumed: null,
+            event: { type: "run_aborted", payload: { byAccountId, reason: "user" } },
+        });
+    }
     /** 会话当前未结束的运行（调用方已持有会话行锁）。 */
     activeRun(t, conversationId) {
         return t
@@ -604,6 +664,9 @@ __decorate([
 __decorate([
     Transactional({ propagation: "requires_new" })
 ], RunQueue.prototype, "abortOrphanIn", null);
+__decorate([
+    Transactional({ propagation: "requires_new" })
+], RunQueue.prototype, "abortQueuedIn", null);
 RunQueue = __decorate([
     Injectable(),
     __param(0, Inject(KernelDb)),

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

@@ -8,9 +8,11 @@ import { KernelDb } from "../infra/database/kernel-db.js";
 import { TransactionHost } from "../infra/database/transaction-host.js";
 import { KernelEvents } from "../infra/events/kernel-events.js";
 import { SkillsCatalogService } from "../skills/catalog.js";
+import { ToolRegistry } from "../tools/registry.js";
 import { RunAbort } from "./abort.js";
 import { KyselyCheckpointSaver } from "./checkpointer.js";
 import { ConversationLock } from "./conversation-lock.js";
+import { PluginContextService } from "./plugin-context.service.js";
 import { ProviderRegistry } from "./providers.js";
 import { type OrgQuota } from "./quota.js";
 import { RunContextService } from "./run-context.service.js";
@@ -32,6 +34,12 @@ export interface RunHooks {
     lockTtlMs?: number;
     /** 任务结束后的每次 ensureRun 尝试之前调用（attempt 从 0 起）；抛错即模拟该次尝试失败。 */
     beforeEnsureRun?(conversationId: string, attempt: number): Promise<void>;
+    /** Called after a run job read the run's status, before it takes the conversation lock. */
+    afterRunRead?(runId: string, conversationId: string): Promise<void>;
+    /** Called with the conversation lock held, before a queued run's `run_started` is written. */
+    beforeRunStarted?(runId: string, conversationId: string): Promise<void>;
+    /** Called with the conversation lock held, before a queued run's status becomes `running`. */
+    beforeRunning?(runId: string, conversationId: string): Promise<void>;
 }
 /** 处理函数的返回值：`ensure` 表示任务完成后再调用一次 ensureRun。 */
 export type ProcessResult = "ensure" | undefined;
@@ -65,6 +73,10 @@ export declare class RunWorker {
     private readonly skillsCatalog;
     /** Run start's run context (run context spec §5): who the agent is, the day, the person. */
     private readonly runContext;
+    /** Run start's plugin context (memory plugin spec §6.1): the `context@1` providers' text. */
+    private readonly pluginContext;
+    /** The run's resolved tools, for the plugin context's `tools` (chat runs with providers). */
+    private readonly tools;
     private readonly finisher;
     readonly txHost: TransactionHost;
     /** The steps' live drafts this process writes for the runs it executes. */
@@ -93,7 +105,11 @@ export declare class RunWorker {
     /** 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">, finisher: Pick<RunFinish, "finish">, txHost: TransactionHost, 
+    runContext: Pick<RunContextService, "record">, 
+    /** Run start's plugin context (memory plugin spec §6.1): the `context@1` providers' text. */
+    pluginContext: Pick<PluginContextService, "record">, 
+    /** The run's resolved tools, for the plugin context's `tools` (chat runs with providers). */
+    tools: Pick<ToolRegistry, "forAgent">, finisher: Pick<RunFinish, "finish">, txHost: TransactionHost, 
     /** The steps' live drafts this process writes for the runs it executes. */
     drafts: RunDrafts, hooks?: RunHooks | undefined);
     private get db();
@@ -159,6 +175,11 @@ export declare class RunWorker {
     process(job: Job<RunJobData>, token: string | undefined): Promise<ProcessResult>;
     private execute;
     private completed;
+    /**
+     * The run's extension tool keys by plugin, resolved as a chat run's first step lists them
+     * (disabled tools, org switches, the conversation's source): a provider's `tools`.
+     */
+    private pluginToolKeys;
     /**
      * When the conversation was switched to a model that no longer resolves (provider disabled,
      * model removed), writes `model_switched { model: null, effort: null, reason: "unavailable" }`