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

package/dist/runtime/subagents/subagents.service.js

@@ -0,0 +1,101 @@
+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, Module } from "@nestjs/common";
+import { EventLog, EventLogModule } from "../../conversations/event-log.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 { Transactional } from "../../infra/database/transactional.decorator.js";
+import { KERNEL_BUS, KERNEL_LOGGER } from "../../infra/tokens.js";
+import { ModelsModule } from "../../models/models.module.js";
+import { ModelPurposesService } from "../../models/purposes.js";
+import { SkillInvoker } from "../../skills/invoke.js";
+import { SkillsModule } from "../../skills/skills.module.js";
+import { ProviderRegistry, ProvidersModule } from "../providers.js";
+import { RunJobs, RunJobsModule } from "../run-jobs.js";
+import { commitDispatchIn, dispatchSubagent, } from "./dispatch.js";
+import { publishSubagentProgress } from "./progress.js";
+import { liveSkillForks } from "./skill-fork.js";
+/**
+ * Sub-agents (phase C, spec §7) and forked skills (phase D): the `Agent` tool's dispatch (the
+ * tool pipeline calls {@link dispatch}), a run's fork invocation ({@link skillForks}, the loop's
+ * `prepare`) and a child step's progress on the parent's stream ({@link progress}). Child runs go
+ * to the sub-agent run queue through {@link RunJobs}. The child lifecycle after dispatch (a
+ * finished child resumes its parent, a stopped parent stops its children) is the waits'
+ * (`Waits.childFinished` / `stopChildren`).
+ */
+let SubagentsService = class SubagentsService {
+    bus;
+    log;
+    txHost;
+    /** The dispatch's dependencies (`dispatch.ts`, `skill-fork.ts`). */
+    deps;
+    /** The live fork handler of the loop (`LoopDeps.skillForks`). */
+    skillForks;
+    constructor(kdb, eventLog, purposes, registry, config, jobs, invoker, bus, log, txHost) {
+        this.bus = bus;
+        this.log = log;
+        this.txHost = txHost;
+        this.deps = {
+            get db() {
+                return kdb.db;
+            },
+            eventLog,
+            purposes,
+            registry,
+            config,
+            enqueue: (data, jobId, kind) => jobs.enqueue(data, jobId, kind),
+            log,
+            invoker,
+            commitDispatch: (a, plan, child) => this.commitDispatch(a, plan, child),
+        };
+        this.skillForks = liveSkillForks(this.deps);
+    }
+    /** Dispatches the sub-agent of one `Agent` call (`dispatchSubagent`). */
+    dispatch(a) {
+        return dispatchSubagent(this.deps, a);
+    }
+    /** The dispatch's writes in a transaction of their own (see `commitDispatchIn`). */
+    commitDispatch(a, plan, child) {
+        return commitDispatchIn(this.deps, a, plan, child);
+    }
+    /** A sub-agent's finished step on its parent's stream (sub-agents spec §14.2). Never throws. */
+    progress(s) {
+        return publishSubagentProgress({ db: this.deps.db, bus: this.bus, log: this.log }, s);
+    }
+};
+__decorate([
+    Transactional({ propagation: "requires_new" })
+], SubagentsService.prototype, "commitDispatch", null);
+SubagentsService = __decorate([
+    Injectable(),
+    __param(0, Inject(KernelDb)),
+    __param(1, Inject(EventLog)),
+    __param(2, Inject(ModelPurposesService)),
+    __param(3, Inject(ProviderRegistry)),
+    __param(4, Inject(KernelConfigService)),
+    __param(5, Inject(RunJobs)),
+    __param(6, Inject(SkillInvoker)),
+    __param(7, Inject(KERNEL_BUS)),
+    __param(8, Inject(KERNEL_LOGGER)),
+    __param(9, Inject(TransactionHost))
+], SubagentsService);
+export { SubagentsService };
+/** Sub-agent dispatch (the tools domain's `Agent` tool and the run loop use it). */
+let SubagentsModule = class SubagentsModule {
+};
+SubagentsModule = __decorate([
+    Module({
+        imports: [EventLogModule, ModelsModule, ProvidersModule, RunJobsModule, SkillsModule],
+        providers: [SubagentsService],
+        exports: [SubagentsService],
+    })
+], SubagentsModule);
+export { SubagentsModule };

package/dist/runtime/usage-report.d.ts

@@ -1,7 +1,11 @@
 import type { Logger } from "@capybara-hq/plugin-sdk";
-import type { KernelConfig } from "../config/schema.js";
-import type { KernelDb } from "../db/kernel-schema.js";
-import { type HookRegistry } from "../extensions/hooks.js";
+import { Job, type Queue, type Worker } from "bullmq";
+import type { KernelSchemaDb } from "../db/kernel-schema.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 { LockService } from "../infra/lock/lock.service.js";
+import type { KernelLogger } from "../log.js";
 /** Queue of `usage.report` deliveries (no `:` in the name). */
 export declare const USAGE_REPORT_QUEUE = "cap-kernel-usage-report";
 /** One job per `usage` event (no `:`: conversation ids are UUIDs, seq is a number). */
@@ -23,10 +27,17 @@ export interface UsageReportJob {
 export declare const USAGE_REPORT_ATTEMPTS = 6;
 /** Retry backoff: 2 s, doubling (2, 4, 8, 16, 32 s). */
 export declare const USAGE_REPORT_BACKOFF_MS = 2000;
-/** Maintenance job of the sweeper (no `:`), its scheduler id and period. */
+/** The delivery retry policy of {@link UsageReporter}: attempts and the first exponential backoff. */
+export interface UsageReportRetry {
+    attempts: number;
+    backoffMs: number;
+}
+/** Optional provider: the {@link UsageReportRetry} instead of the defaults above (tests). */
+export declare const USAGE_REPORT_RETRY: unique symbol;
+/** The sweeper's cron job name (no `:`; every minute, once across replicas). */
 export declare const USAGE_SWEEP_JOB = "usage-report-sweep";
-export declare const USAGE_SWEEP_SCHEDULER_ID = "usage-report-sweep-every";
-export declare const USAGE_SWEEP_EVERY_MS = 60000;
+/** The maintenance scheduler the sweep ran on before it became a `@LockedCron` (retired). */
+export { USAGE_SWEEP_SCHEDULER_ID } from "./job-ids.js";
 /** The sweep leaves the newest events to the fast path (and to transactions still committing). */
 export declare const USAGE_SWEEP_LAG_MS = 30000;
 /**
@@ -35,45 +46,13 @@ export declare const USAGE_SWEEP_LAG_MS = 30000;
  * (`hooks.usageReportKeepHours` ≥ 1 h), so re-enqueued events dedupe on the kept job.
  */
 export declare const USAGE_SWEEP_OVERLAP_MS: number;
-export interface UsageReporterDeps {
-    db: KernelDb;
-    redisUrl: string;
-    /**
-     * The host's registry: handlers of the current local plugin generations (through inflight.run), and
-     * `has("usage.report")`, the in-process check that lets `enqueue` skip all I/O without handlers.
-     */
-    hooks: Pick<HookRegistry, "handlers" | "has">;
-    /**
-     * Whether the plugin's current instance is active on this replica (I-2): an active instance that
-     * registered no `usage.report` handler is not a subscriber, and its target is dropped. Absent: never.
-     */
-    isActive?(plugin: string): boolean;
-    /**
-     * Of these plugins, the ones no replica can serve right now (I-2): replicas report them (live
-     * `extension_replica_status` rows) and none has them loaded. Their targets are dropped at once instead
-     * of failing every attempt. See {@link queryUnservable}. Absent: none.
-     */
-    unservable?(plugins: readonly string[]): Promise<Set<string>>;
-    /**
-     * Plugins that subscribe to `usage.report`, from deployment state (approved manifests in PG), not from this replica's loaded handlers. With `orgId`: only those the
-     * organization enabled. See {@link queryUsageSubscribers}.
-     */
-    subscribers(orgId?: string): Promise<Set<string>>;
-    config: () => KernelConfig;
-    log: Logger;
-    /** Tests: retry policy (defaults {@link USAGE_REPORT_ATTEMPTS} / {@link USAGE_REPORT_BACKOFF_MS}). */
-    retry?: {
-        attempts: number;
-        backoffMs: number;
-    };
-}
 /**
  * Plugins that subscribe to `usage.report` according to deployment state: an approved permission
  * snapshot that declares the `usage.report` hook, for a plugin the deployment still knows: an enabled
  * install, or a config-declared plugin with a replica status row that is not `unloaded`. With `orgId`, only plugins
  * the organization enabled (org config rows and required bootstrap plugins).
  */
-export declare function queryUsageSubscribers(db: KernelDb, orgId?: string): Promise<Set<string>>;
+export declare function queryUsageSubscribers(db: KernelSchemaDb, orgId?: string): Promise<Set<string>>;
 /**
  * Of `plugins`, those that are **definitely** unservable right now (I-2, N-3): live replicas report
  * them (a `extension_replica_status` row with a heartbeat newer than `staleSeconds`), no live row is
@@ -82,7 +61,7 @@ export declare function queryUsageSubscribers(db: KernelDb, orgId?: string): Pro
  * reconcile). A plugin with no live row at all is unknown too (slow to load, or a host without a
  * status store). Unknown plugins are never listed.
  */
-export declare function queryUnservable(db: KernelDb, plugins: readonly string[], staleSeconds: number): Promise<Set<string>>;
+export declare function queryUnservable(db: KernelSchemaDb, plugins: readonly string[], staleSeconds: number): Promise<Set<string>>;
 /**
  * The next `pending` set (m-2 fence): plugins that failed now, narrowed to what the stored job data
  * still lists. A plugin another (stalled-over) execution already delivered never comes back.
@@ -118,14 +97,50 @@ export declare function narrowPending(stored: readonly string[] | undefined, fai
  * Single-step eval replays and judge requests log no usage: not reported (M7).
  */
 export declare class UsageReporter {
-    private readonly d;
-    private queue;
-    private queueConn;
+    private readonly kdb;
+    private readonly queue;
+    /**
+     * The host's hook registry: handlers of the current local plugin generations (through
+     * inflight.run), and `has("usage.report")`, the in-process check that lets `enqueue` skip all
+     * I/O without handlers; and whether a plugin's current instance is active here.
+     */
+    private readonly host;
+    private readonly config;
+    /** The warning throttle's markers (`capk:usage-warn:<plugin>:<kind>`, SET NX PX). */
+    private readonly locks;
+    private readonly log;
+    private readonly retry;
     private worker;
-    private workerConn;
     private closed;
     private readonly stopping;
-    constructor(d: UsageReporterDeps);
+    constructor(kdb: KernelDb, queue: Queue<UsageReportJob>, 
+    /**
+     * The host's hook registry: handlers of the current local plugin generations (through
+     * inflight.run), and `has("usage.report")`, the in-process check that lets `enqueue` skip all
+     * I/O without handlers; and whether a plugin's current instance is active here.
+     */
+    host: Pick<ExtensionHost, "hooks" | "current">, config: Pick<KernelConfigService, "get">, 
+    /** The warning throttle's markers (`capk:usage-warn:<plugin>:<kind>`, SET NX PX). */
+    locks: Pick<LockService, "lease">, log: Logger, retry?: UsageReportRetry);
+    private get db();
+    private get hooks();
+    /**
+     * Whether the plugin's current instance is active on this replica (I-2): an active instance that
+     * registered no `usage.report` handler is not a subscriber, and its target is dropped.
+     */
+    isActive(plugin: string): boolean;
+    /**
+     * Of these plugins, the ones no replica can serve right now (I-2): replicas report them (live
+     * `extension_replica_status` rows) and none has them loaded. Their targets are dropped at once
+     * instead of failing every attempt. See {@link queryUnservable}.
+     */
+    unservable(plugins: readonly string[]): Promise<Set<string>>;
+    /**
+     * Plugins that subscribe to `usage.report`, from deployment state (approved manifests in PG),
+     * not from this replica's loaded handlers. With `orgId`: only those the organization enabled.
+     * See {@link queryUsageSubscribers}.
+     */
+    subscribers(orgId?: string): Promise<Set<string>>;
     private jobOpts;
     /**
      * Enqueues the delivery of one `usage` event. Returns without a job when no plugin subscribes.
@@ -140,11 +155,20 @@ export declare class UsageReporter {
     sweep(opts?: {
         now?: number;
     }): Promise<number>;
-    /** Starts the worker (worker role only). Job lock and stalled detection follow the run queue. */
-    startWorker(): void;
-    /** Stops the worker (in-flight calls are aborted, their jobs requeued) and the queue. */
+    /**
+     * Starts consuming (worker role only): `worker` is the `@Processor` worker of
+     * {@link USAGE_REPORT_QUEUE} (built with the run queue's job lock and stalled detection).
+     */
+    startWorker(worker: Worker<UsageReportJob>): void;
+    /** The worker's `error` event. */
+    onError(err: Error): void;
+    /** A job failed (the worker's `failed` event): logs retries and the final failure. */
+    onFailed(j: Job<UsageReportJob> | undefined, err: Error): void;
+    /**
+     * Stops: no more enqueues, in-flight calls are aborted (their jobs requeued) and the worker
+     * closes. The queue itself closes with the application.
+     */
     stop(): Promise<void>;
-    private getQueue;
     /** The payload of one usage event, read from the log; null when the event no longer exists. */
     private payloadOf;
     /**
@@ -153,11 +177,29 @@ export declare class UsageReporter {
      * dropped can stay, so a plugin another execution delivered never comes back.
      */
     private writePending;
-    private process;
-    /** {@link UsageReporterDeps.unservable}; a lookup failure counts as "unknown" (keep retrying). */
-    private unservable;
+    /** One delivery job (the `@Processor` of {@link USAGE_REPORT_QUEUE} calls it). */
+    process(j: Job<UsageReportJob>, token: string | undefined): Promise<void>;
+    /** {@link unservable}; a lookup failure counts as "unknown" (keep retrying). */
+    private unservableOrNone;
     /** Logs a warning at most once per plugin and kind per minute (Redis key with a TTL). */
     private warnOnce;
     /** One handler call with its own signal (timeout or replica stop aborts it); rejects on either. */
     private call;
 }
+/**
+ * The usage sweeper (R13), every minute, once across replicas: {@link UsageReporter.sweep}.
+ * Replaces the maintenance scheduler `usage-report-sweep-every` (retired at worker start).
+ */
+export declare class UsageSweepJob {
+    private readonly reporter;
+    readonly lockService: LockService;
+    readonly log: KernelLogger;
+    constructor(reporter: Pick<UsageReporter, "sweep">, lockService: LockService, log: KernelLogger);
+    run(): Promise<void>;
+}
+/**
+ * `usage.report` delivery: the producer on every role; the consumer and the sweep ({@link UsageSweepJob})
+ * on the worker role (`WorkerModule`).
+ */
+export declare class UsageReportModule {
+}