@capybara-hq/kernel 0.1.0-rc.1 → 0.1.0-rc.10

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

@@ -0,0 +1,39 @@
+import { AttachmentsService } from "../conversations/attachments.service.js";
+import { EventLog } from "../conversations/event-log.js";
+import { ExtensionHost } from "../extensions/host.js";
+import { KernelConfigService } from "../infra/config/kernel-config.service.js";
+import { KernelDb } from "../infra/database/kernel-db.js";
+import type { KernelLogger } from "../log.js";
+import { ToolPipeline } from "../tools/pipeline.js";
+import { ToolRegistry } from "../tools/registry.js";
+import { KyselyCheckpointSaver } from "./checkpointer.js";
+import { type LoopDeps } from "./langgraph-loop.js";
+import type { AgentLoop } from "./loop.js";
+import { ProviderRegistry } from "./providers.js";
+import { StepLog } from "./step-log.js";
+import { SubagentsService } from "./subagents/subagents.service.js";
+import { UsageReporter } from "./usage-report.js";
+/**
+ * Builds the agent loop a run executes (default {@link LangGraphLoop}: its checkpoints live in the
+ * kernel's {@link KyselyCheckpointSaver}, so another replica resumes a crashed worker's run).
+ * Tests override it with a provider for {@link AGENT_LOOP_FACTORY}.
+ */
+export type AgentLoopFactory = (deps: LoopDeps, checkpoints: KyselyCheckpointSaver) => AgentLoop;
+/** Optional provider: the {@link AgentLoopFactory} runs use instead of the default (tests). */
+export declare const AGENT_LOOP_FACTORY: unique symbol;
+/** The agent loops of chat runs and of eval full-run replays (one factory, one checkpoint store). */
+export declare class AgentLoops {
+    private readonly checkpoints;
+    private readonly factory?;
+    constructor(checkpoints: KyselyCheckpointSaver, factory?: AgentLoopFactory | undefined);
+    create(deps: LoopDeps): AgentLoop;
+}
+/**
+ * What a run's steps use (`LoopDeps`: one model step plus the tool pipeline), over the injected
+ * services. `deps` is a plain object (eval replays copy it without the hooks, the progress and the
+ * fork dispatch).
+ */
+export declare class RunSteps {
+    readonly deps: LoopDeps;
+    constructor(kdb: KernelDb, eventLog: EventLog, stepLog: StepLog, registry: ProviderRegistry, usageReport: UsageReporter, tools: ToolRegistry, config: KernelConfigService, log: KernelLogger, toolPipeline: ToolPipeline, host: ExtensionHost, subagents: SubagentsService, attachments: AttachmentsService);
+}

package/dist/runtime/run-steps.js

@@ -0,0 +1,96 @@
+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 { AttachmentsService } from "../conversations/attachments.service.js";
+import { EventLog } from "../conversations/event-log.js";
+import { ExtensionHost } from "../extensions/host.js";
+import { KernelConfigService } from "../infra/config/kernel-config.service.js";
+import { KernelDb } from "../infra/database/kernel-db.js";
+import { KERNEL_LOGGER } from "../infra/tokens.js";
+import { ToolPipeline } from "../tools/pipeline.js";
+import { ToolRegistry } from "../tools/registry.js";
+import { KyselyCheckpointSaver } from "./checkpointer.js";
+import { LangGraphLoop } from "./langgraph-loop.js";
+import { ProviderRegistry } from "./providers.js";
+import { StepLog } from "./step-log.js";
+import { SubagentsService } from "./subagents/subagents.service.js";
+import { UsageReporter } from "./usage-report.js";
+/** Optional provider: the {@link AgentLoopFactory} runs use instead of the default (tests). */
+export const AGENT_LOOP_FACTORY = Symbol("AGENT_LOOP_FACTORY");
+/** The agent loops of chat runs and of eval full-run replays (one factory, one checkpoint store). */
+let AgentLoops = class AgentLoops {
+    checkpoints;
+    factory;
+    constructor(checkpoints, factory) {
+        this.checkpoints = checkpoints;
+        this.factory = factory;
+    }
+    create(deps) {
+        return this.factory
+            ? this.factory(deps, this.checkpoints)
+            : new LangGraphLoop(this.checkpoints, deps);
+    }
+};
+AgentLoops = __decorate([
+    Injectable(),
+    __param(0, Inject(KyselyCheckpointSaver)),
+    __param(1, Optional()),
+    __param(1, Inject(AGENT_LOOP_FACTORY))
+], AgentLoops);
+export { AgentLoops };
+/**
+ * What a run's steps use (`LoopDeps`: one model step plus the tool pipeline), over the injected
+ * services. `deps` is a plain object (eval replays copy it without the hooks, the progress and the
+ * fork dispatch).
+ */
+let RunSteps = class RunSteps {
+    deps;
+    constructor(kdb, eventLog, stepLog, registry, usageReport, tools, config, log, toolPipeline, host, subagents, attachments) {
+        this.deps = {
+            get db() {
+                return kdb.db;
+            },
+            eventLog,
+            stepLog,
+            registry,
+            usageReport,
+            tools,
+            config,
+            log,
+            toolPipeline,
+            // plugin hooks for chat runs; the full-run replay drops them (P-18)
+            hooks: host.hooks,
+            // a sub-agent's steps on its parent's stream (sub-agents spec §14.2)
+            subagentProgress: (s) => subagents.progress(s),
+            // phase D: a person's fork invocation dispatches its sub-agent in the run's first prepare
+            skillForks: subagents.skillForks,
+            media: {
+                info: (orgId, conversationId, ids) => attachments.mediaInfo(orgId, conversationId, ids),
+                fetch: (orgId, conversationId, ids, caps) => attachments.fetchMedia(orgId, conversationId, ids, caps),
+            },
+        };
+    }
+};
+RunSteps = __decorate([
+    Injectable(),
+    __param(0, Inject(KernelDb)),
+    __param(1, Inject(EventLog)),
+    __param(2, Inject(StepLog)),
+    __param(3, Inject(ProviderRegistry)),
+    __param(4, Inject(UsageReporter)),
+    __param(5, Inject(ToolRegistry)),
+    __param(6, Inject(KernelConfigService)),
+    __param(7, Inject(KERNEL_LOGGER)),
+    __param(8, Inject(ToolPipeline)),
+    __param(9, Inject(ExtensionHost)),
+    __param(10, Inject(SubagentsService)),
+    __param(11, Inject(AttachmentsService))
+], RunSteps);
+export { RunSteps };

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

@@ -1,19 +1,30 @@
-import type { Logger } from "@capybara-hq/plugin-sdk";
-import { type Transaction } from "kysely";
-import type { KernelConfig } from "../config/schema.js";
-import type { EventLog } from "../conversations/event-log.js";
-import type { KernelDatabase, KernelDb } from "../db/kernel-schema.js";
-import type { SettingsService } from "../identity/settings.js";
-import type { StorageService } from "../storage/storage.service.js";
-import type { RunAbort } from "./abort.js";
-import type { KyselyCheckpointSaver } from "./checkpointer.js";
-import type { ConversationLock } from "./conversation-lock.js";
-import type { AgentLoop } from "./loop.js";
-import { type StreamSink } from "./model-call.js";
-import { type ProviderRegistry } from "./providers.js";
+import type { ExtensionContext, Logger } from "@capybara-hq/plugin-sdk";
+import { type Job, type Worker } from "bullmq";
+import { EventLog } from "../conversations/event-log.js";
+import { TitleQueue } from "../conversations/titles.js";
+import { SettingsService } from "../identity/settings.js";
+import { KernelConfigService } from "../infra/config/kernel-config.service.js";
+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 { ToolPipeline } from "../tools/pipeline.js";
+import { RunAbort } from "./abort.js";
+import { KyselyCheckpointSaver } from "./checkpointer.js";
+import { ConversationLock } from "./conversation-lock.js";
+import { ProviderRegistry } from "./providers.js";
 import { type OrgQuota } from "./quota.js";
-import { type RunQueue } from "./run-queue.js";
-import type { Waits } from "./waits.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";
+import { RunQueue } from "./run-queue.js";
+import { AgentLoops, RunSteps } from "./run-steps.js";
+import { Waits } from "./waits.js";
+/** BullMQ stalled 检测允许的最大次数（超过则任务失败）。 */
+export declare const MAX_STALLED_COUNT = 3;
+/** Optional provider: the run worker's {@link RunHooks} (tests). */
+export declare const RUN_HOOKS: unique symbol;
 /** 测试钩子与参数。 */
 export interface RunHooks {
     /** 终态事件已写入、释放配额与会话锁之前调用（用于构造「运行结束瞬间到达的消息」）。 */
@@ -23,78 +34,116 @@ export interface RunHooks {
     /** 任务结束后的每次 ensureRun 尝试之前调用（attempt 从 0 起）；抛错即模拟该次尝试失败。 */
     beforeEnsureRun?(conversationId: string, attempt: number): Promise<void>;
 }
-export interface RunWorkerDeps {
-    db: KernelDb;
-    eventLog: EventLog;
-    lock: ConversationLock;
-    quota: OrgQuota;
-    abort: RunAbort;
-    queue: Pick<RunQueue, "ensureRun">;
-    settings: Pick<SettingsService, "get">;
-    loop: AgentLoop;
-    config: () => KernelConfig;
-    log: Logger;
-    redisUrl: string;
-    /** 按会话取流式增量出口；默认丢弃。 */
-    sinkFor?: (conversationId: string) => StreamSink;
+/** 处理函数的返回值：`ensure` 表示任务完成后再调用一次 ensureRun。 */
+export type ProcessResult = "ensure" | undefined;
+/**
+ * 运行 worker（只在含 `worker` 角色的进程消费）：领取 `cap-kernel-runs` 与 `cap-kernel-subagent-runs` 的任务
+ * （两个 `@Processor`，见 run-processors.ts），取会话锁与组织配额，调用 AgentLoop，按结果写终态事件并推进
+ * `consumed_seq`；结束后再调用一次 `ensureRun` 处理运行期间到达但没被吸收的消息（Review Focus 2）。
+ */
+export declare class RunWorker {
+    private readonly kdb;
+    private readonly eventLog;
+    private readonly lock;
+    private readonly quota;
+    private readonly abort;
+    private readonly queue;
+    private readonly settings;
+    private readonly config;
+    private readonly log;
+    private readonly bus;
     /** 运行到达终态后删除该运行（thread_id = runId）的 checkpoint thread（只用于续跑，结束后无用）。 */
-    checkpoints?: Pick<KyselyCheckpointSaver, "deleteThread">;
-    /** loop 返回 `suspended` 后把运行置为 waiting（释放会话锁与配额之后）。 */
-    waits: Pick<Waits, "suspend">;
-    /** 取得会话锁与配额、开始执行运行时调用（同步、不等待；渠道出站投递用它排投递任务）。 */
-    onRunStart?: (conversationId: string) => void;
-    /**
-     * A run reached `completed` (`run_finished`, any reason): called after the terminal event is
-     * written (sync, not awaited). The kernel enqueues the conversation's title job with it.
-     */
-    onRunCompleted?: (conversationId: string) => void;
-    hooks?: RunHooks;
+    private readonly checkpoints;
+    /** loop 返回 `suspended` 后把运行置为 waiting（释放会话锁与配额之后）; the child lifecycle. */
+    private readonly waits;
+    /** `run.started` (the channel outbound enqueues the conversation's IM delivery). */
+    private readonly events;
+    /** A completed run enqueues the conversation's title job. */
+    private readonly titles;
     /** Resolves a switched-to model at run start (fallback when it is gone; UI refresh B). */
-    models?: Pick<ProviderRegistry, "resolve">;
-    /** Object storage: run start reads the pinned skills' bodies from it (phase B). */
-    storage?: StorageService;
-    /**
-     * After a sub-agent run's terminal state committed (sub-agents spec §7.3; `onChildFinished`):
-     * reports it to the parent. Called with any run id whose conversation may be a child; it ignores
-     * runs that were not dispatched. Errors are logged (the wait sweep repairs a missed call).
-     */
-    onChildFinished?: (runId: string) => Promise<void>;
-    /**
-     * After any terminal commit of a run that is not a sub-agent's (sub-agents spec §12): stops its
-     * active children on its behalf (`stopChildren` with no account). The wait sweep is the backstop.
-     */
-    stopChildren?: (runId: string) => Promise<number>;
+    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
-     * (`ToolPipeline.stopOpenAgentCalls`; a no-op without dispatches); `fire` runs their observe
-     * hooks after the commit (sub-agents spec §12, review m1: a failed or stalled parent too).
+     * 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
+     * commit (sub-agents spec §12, review m1: a failed or stalled parent too).
      */
-    stopOpenCalls?: (t: Transaction<KernelDatabase>, runId: string) => Promise<{
-        fire: () => void;
-    }>;
-}
-/**
- * 运行 worker（只在含 `worker` 角色的进程启动）：领取 `cap-kernel-runs` 的任务，取会话锁与组织配额，
- * 调用 AgentLoop，按结果写终态事件并推进 `consumed_seq`；结束后再调用一次 `ensureRun` 处理
- * 运行期间到达但没被吸收的消息（Review Focus 2）。
- */
-export declare class RunWorker {
-    private readonly d;
-    /** One BullMQ worker per run queue: conversation runs and sub-agent runs (spec §7.4). */
+    private readonly pipeline;
+    private readonly finisher;
+    readonly txHost: TransactionHost;
+    /** The steps' live drafts this process writes for the runs it executes. */
+    private readonly drafts;
+    private readonly hooks?;
+    /** The two run queues' BullMQ workers (spec §7.4), once {@link start}ed on the worker role. */
     private workers;
-    /** 传给 Worker 的连接：BullMQ 不关闭调用方传入的连接，close() 时自己关。 */
-    private conn;
     private readonly active;
     /** 进行中的「任务结束后」处理（完成后的 ensureRun、失败标记）：停机时等它们做完再关闭队列。 */
     private readonly followUps;
     private closing;
     /** close() 开始时触发：ensureRun 重试不再等待退避间隔。 */
     private readonly closingSignal;
-    constructor(d: RunWorkerDeps);
-    start(): void;
-    /** Stops the active children of a finished run (see {@link RunWorkerDeps.stopChildren}). */
+    private readonly loop;
+    constructor(kdb: KernelDb, eventLog: EventLog, lock: ConversationLock, quota: OrgQuota, abort: RunAbort, queue: Pick<RunQueue, "ensureRun">, settings: Pick<SettingsService, "get">, loops: AgentLoops, steps: RunSteps, config: KernelConfigService, log: Logger, bus: ExtensionContext["bus"], 
+    /** 运行到达终态后删除该运行（thread_id = runId）的 checkpoint thread（只用于续跑，结束后无用）。 */
+    checkpoints: Pick<KyselyCheckpointSaver, "deleteThread">, 
+    /** loop 返回 `suspended` 后把运行置为 waiting（释放会话锁与配额之后）; the child lifecycle. */
+    waits: Pick<Waits, "suspend" | "childFinished" | "stopChildren" | "stopDescendantsOfStopped">, 
+    /** `run.started` (the channel outbound enqueues the conversation's IM delivery). */
+    events: KernelEvents, 
+    /** A completed run enqueues the conversation's title job. */
+    titles: Pick<TitleQueue, "maybeEnqueue">, 
+    /** Resolves a switched-to model at run start (fallback when it is gone; UI refresh B). */
+    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
+     * commit (sub-agents spec §12, review m1: a failed or stalled parent too).
+     */
+    pipeline: Pick<ToolPipeline, "stopOpenAgentCalls">, 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();
+    /**
+     * Starts consuming (worker role only): `workers` are the `@Processor` workers of both run queues
+     * (built with `runtime.workerConcurrency`, `jobLockMs`, `stalledIntervalMs`; never autorun).
+     */
+    start(workers: Worker<RunJobData, ProcessResult>[]): void;
+    /** A worker's `error` event. */
+    onError(err: Error, queue: string): void;
+    /**
+     * A job completed (the worker's `completed` event). ensureRun after a run goes after its job
+     * completed and left the queue: when the latest unconsumed message is this run's own trigger
+     * (e.g. a run ended by its deadline without absorbing it, R34), the new job has this job's id
+     * and would be dropped as a duplicate while this one is still active. Relies on BullMQ moving
+     * the job to completed (deleted by removeOnComplete) before emitting "completed" (pinned by the
+     * R34 test).
+     */
+    onCompleted(job: Job<RunJobData>, result: ProcessResult): void;
+    /** A job failed (the worker's `failed` event). */
+    onFailed(job: Job<RunJobData> | undefined, err: Error): void;
+    /**
+     * The run's stream sink: deltas on the conversation's topic (any replica's subscribers get them)
+     * and the steps' live drafts in Redis ({@link streamSink}, spec 2026-11-07 §3.2).
+     */
+    private sinkFor;
+    /**
+     * After any terminal commit of a run that is not a sub-agent's (sub-agents spec §12): stops its
+     * active fork invocation child on its behalf (no account); background `Agent` children keep
+     * running (agent map spec §5.4). The wait sweep is the backstop.
+     */
     private stopChildren;
-    /** Reports a finished sub-agent run to its parent (see {@link RunWorkerDeps.onChildFinished}). */
+    /**
+     * After a sub-agent run's terminal state committed (sub-agents spec §7.3): reports it to the
+     * parent. Called with any run id whose conversation may be a child; runs that were not
+     * dispatched are ignored. Errors are logged (the wait sweep repairs a missed call).
+     */
     private childFinished;
     /**
      * 任务结束后的 ensureRun，失败按 {@link ENSURE_RETRY_DELAYS_MS} 退避重试；停机开始后不再等待间隔
@@ -117,7 +166,8 @@ export declare class RunWorker {
      * worker，不再续任务锁），由 BullMQ 的 stalled 机制交给其他 worker 续跑。
      */
     close(budgetMs: number): Promise<void>;
-    private process;
+    /** One run job (the `@Processor`s of both run queues call it). */
+    process(job: Job<RunJobData>, token: string | undefined): Promise<ProcessResult>;
     private execute;
     private completed;
     /**
@@ -125,9 +175,16 @@ 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;
+    /**
+     * `run_started` under the conversation row lock, with the model / effort switch in effect then
+     * (a chat run's `saved` version under the conversation's selection): what the run uses.
+     */
+    private appendRunStarted;
+    /** {@link fallBackIfUnavailable}'s write: null when the person switched again meanwhile. */
+    private fallBackIn;
     /** 删除已结束运行的 checkpoint thread（失败只记日志）。 */
     private dropCheckpoints;
     /**