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

package/dist/runtime/subagents/child.js

@@ -1,7 +1,5 @@
 import { usageTokens } from "../../evals/budget.js";
 import { agentResultText } from "../../tools/builtins/agent.js";
-import { TERMINAL_STATUSES } from "../run-finish.js";
-import { ACTIVE_RUN_STATUSES } from "../run-queue.js";
 /** Idempotency key of the parent's `subagent_finished` event. */
 export const finishedIdemKey = (childRunId) => `subagent_finished:${childRunId}`;
 const DISPATCH_COLUMNS = [
@@ -146,80 +144,3 @@ export const finishedEvent = (row, finished) => ({
     idemKey: finishedIdemKey(row.childRunId),
     payload: finished,
 });
-/**
- * After a child run's terminal state committed (spec §7.3): appends `subagent_finished` to the
- * parent log (idempotent; allowed while the parent waits, it is not model-visible) and tries
- * `Waits.resume(parentRunId, childRunId)`. Every finishing child tries; the conditional resume lets
- * exactly one succeed, the last to see all its siblings terminal. A run that is not a dispatched
- * child, or not terminal yet, is left alone. A crash in between is repaired by the wait sweep and
- * by the parent's tools node, which writes a missing `subagent_finished` itself.
- */
-export async function onChildFinished(d, childRunId) {
-    const row = await dispatchOfChildRun(d.db, childRunId);
-    if (!row)
-        return;
-    const run = await d.db
-        .selectFrom("runs")
-        .select("status")
-        .where("id", "=", childRunId)
-        .executeTakeFirst();
-    if (!run || !TERMINAL_STATUSES.has(run.status))
-        return;
-    const r = await childResult(d.eventLog, row);
-    if (!r) {
-        d.log.warn("sub-agent run is terminal without a terminal event", { childRunId });
-        return;
-    }
-    await d.eventLog.append(row.parentConversationId, [finishedEvent(row, r.finished)]);
-    await d.waits.resume(row.parentRunId, childRunId);
-}
-/**
- * Stops the active children of a parent run (sub-agents spec §12), or only those dispatched in
- * `opts.step`: a `waiting` child through its own `abortWaiting`, a `queued` / `running` one that
- * no worker holds directly (`abortIfOrphaned`), any other through `RunAbort.request` (the
- * cross-replica broadcast plus the marker key, so a child that starts later still sees it), after
- * which a child found `waiting` is stopped through `abortWaiting` too. A child stopped here is
- * reported to the parent at once (by `abortWaiting` itself, or {@link onChildFinished} after
- * `abortIfOrphaned`); one stopped by its worker is reported by that worker. Returns the number of
- * children asked to stop.
- *
- * `byAccountId` is the person whose action stops them, or null when the kernel stops them on the
- * parent's behalf; a child stopped with null reports the §4.4 "parent's stop" text.
- */
-export async function stopChildren(d, parentRunId, byAccountId, opts = {}) {
-    let q = d.db
-        .selectFrom("subagent_dispatches as sd")
-        .innerJoin("runs as cr", "cr.id", "sd.child_run_id")
-        .select(["sd.child_conversation_id", "sd.child_run_id", "cr.status"])
-        .where("sd.parent_run_id", "=", parentRunId)
-        .where("cr.status", "in", ACTIVE_RUN_STATUSES);
-    if (opts.step !== undefined)
-        q = q.where("sd.step", "=", opts.step);
-    const children = await q.execute();
-    for (const c of children) {
-        const conv = c.child_conversation_id;
-        const runId = c.child_run_id;
-        // abortWaiting reports the stopped child to the parent itself (Waits.subagents.finished)
-        if (c.status === "waiting" &&
-            (await d.waits.abortWaiting(conv, runId, byAccountId, opts.detail))) {
-            continue;
-        }
-        if (await d.runQueue.abortIfOrphaned(conv, runId, byAccountId, opts.detail)) {
-            await onChildFinished(d, runId);
-            continue;
-        }
-        await d.abort.request(runId, byAccountId, opts.detail);
-        // the suspend handshake (see Waits.suspend): a child that became `waiting` after the read
-        // above may have checked the marker before it was set, so check `waiting` again after setting
-        // it (review M1)
-        const now = await d.db
-            .selectFrom("runs")
-            .select("status")
-            .where("id", "=", runId)
-            .executeTakeFirst();
-        if (now?.status === "waiting") {
-            await d.waits.abortWaiting(conv, runId, byAccountId, opts.detail);
-        }
-    }
-    return children.length;
-}

package/dist/runtime/subagents/definition.d.ts

@@ -1,16 +1,12 @@
 import { type AgentTemplateTier } from "@capybara-hq/plugin-sdk";
 import type { AgentDefinition, AgentToolRef, ModelRef } from "../../agents/definition.js";
-import type { KernelConfig } from "../../config/schema.js";
 import type { EventPayload } from "../../conversations/events.js";
-import type { KernelDb } from "../../db/kernel-schema.js";
+import type { KernelSchemaDb } from "../../db/kernel-schema.js";
+import type { KernelConfigService } from "../../infra/config/kernel-config.service.js";
 import type { ModelPurposesService } from "../../models/purposes.js";
 import type { ProviderRegistry } from "../providers.js";
 import type { RosterEntry } from "./roster.js";
-/**
- * Tools a sub-agent never gets (spec §5.3, §5.5): `agent` (depth 1), `ask_user` (the person does not
- * see the child), `sandbox_deliver` (delivering files is the parent's job) and `skill_write`.
- */
-export declare const CHILD_REMOVED_TOOLS: readonly ["agent", "ask_user", "sandbox_deliver", "skill_write"];
+export { CHILD_REMOVED_TOOLS } from "../../tools/builtin-names.js";
 /**
  * The roster entry's template is gone (an inline template edited away, a plugin template
  * uninstalled) between resolving the roster and reading it. The dispatch refuses the call as an
@@ -29,11 +25,11 @@ export interface EffectiveDefinition {
     warnings: string[];
 }
 export interface EffectiveDefinitionDeps {
-    db: KernelDb;
+    db: KernelSchemaDb;
     purposes: Pick<ModelPurposesService, "resolve">;
     /** Reads the resolved model's parameter declarations (a template `effort`). */
     registry: Pick<ProviderRegistry, "resolve">;
-    config: () => KernelConfig;
+    config: Pick<KernelConfigService, "get">;
 }
 type Policy = "ask" | "deny";
 /**
@@ -100,4 +96,3 @@ export declare function intersectTools(frozen: readonly AgentToolRef[], current:
 export declare function narrowFollowUp(frozen: Pick<AgentDefinition, "tools" | "skills">, current: Pick<AgentDefinition, "tools" | "skills">): FollowUpNarrowing;
 /** The definition a child run uses: the frozen one with its trigger's follow-up narrowing. */
 export declare function childRunDefinition(frozen: AgentDefinition, narrowed: FollowUpNarrowing | undefined): AgentDefinition;
-export {};

package/dist/runtime/subagents/definition.js

@@ -1,13 +1,9 @@
-import { SKILL_ENTRY_FILE, sanitizeParams, } from "@capybara-hq/plugin-sdk";
+import { connectorToolKey, extensionToolKey, parseToolKey, SKILL_ENTRY_FILE, sanitizeParams, } from "@capybara-hq/plugin-sdk";
 import { loadTemplates } from "../../agents/templates.js";
 import { ApiError } from "../../errors.js";
 import { PINNED_SKILLS_LIMITS } from "../../skills/catalog.js";
-import { toolKey } from "../../tools/naming.js";
-/**
- * Tools a sub-agent never gets (spec §5.3, §5.5): `agent` (depth 1), `ask_user` (the person does not
- * see the child), `sandbox_deliver` (delivering files is the parent's job) and `skill_write`.
- */
-export const CHILD_REMOVED_TOOLS = ["agent", "ask_user", "sandbox_deliver", "skill_write"];
+import { CHILD_REMOVED_TOOLS } from "../../tools/builtin-names.js";
+export { CHILD_REMOVED_TOOLS } from "../../tools/builtin-names.js";
 /**
  * The roster entry's template is gone (an inline template edited away, a plugin template
  * uninstalled) between resolving the roster and reading it. The dispatch refuses the call as an
@@ -72,7 +68,7 @@ async function loadConnectors(db, orgId, refs) {
 /**
  * Narrows tool refs by resolved key (spec §5.3): keeps a key when `allow` (if given) lists it and
  * neither `deny` nor {@link CHILD_REMOVED_TOOLS} does. A connector ref with `tools: "all"` stays
- * live only when nothing can narrow it (no allowlist and no deny key under `<slug>__`), so a tool
+ * live only when nothing can narrow it (no allowlist and no deny key under `mcp__<slug>__`), so a tool
  * the connector gains later never slips past the template; otherwise it becomes the kept names, or
  * is dropped. A connector that no longer exists keeps its ref only without an allowlist.
  */
@@ -86,7 +82,7 @@ function narrowTools(refs, connectors, allow, deny) {
                 out.push(ref);
         }
         else if (ref.kind === "plugin") {
-            if (keep(toolKey(ref.plugin, ref.name)))
+            if (keep(extensionToolKey(ref.plugin, ref.name)))
                 out.push(ref);
         }
         else {
@@ -96,13 +92,16 @@ function narrowTools(refs, connectors, allow, deny) {
                     out.push(ref);
                 continue;
             }
-            const prefix = toolKey(c.slug, "");
-            if (ref.tools === "all" && allow === null && ![...deny].some((k) => k.startsWith(prefix))) {
+            const ownsKey = (k) => {
+                const parsed = parseToolKey(k);
+                return parsed?.kind === "connector" && parsed.slug === c.slug;
+            };
+            if (ref.tools === "all" && allow === null && ![...deny].some(ownsKey)) {
                 out.push(ref);
                 continue;
             }
             const names = ref.tools === "all" ? c.tools : ref.tools;
-            const kept = names.filter((name) => keep(toolKey(c.slug, name)));
+            const kept = names.filter((name) => keep(connectorToolKey(c.slug, name)));
             if (kept.length > 0)
                 out.push({ ...ref, tools: kept });
         }
@@ -246,7 +245,7 @@ function orgAgentDefinition(d, a) {
     return {
         definition,
         template: { source: "agent", id: agentId, version: a.orgAgent.version },
-        maxSteps: d.config().runtime.maxSteps,
+        maxSteps: d.config.get().runtime.maxSteps,
         warnings: [],
         model: own.model,
         tierFallback: false,
@@ -268,7 +267,7 @@ function orgAgentDefinition(d, a) {
 export async function effectiveDefinition(d, a) {
     if (a.entry.source === "agent")
         return orgAgentDefinition(d, a);
-    const runtimeMax = d.config().runtime.maxSteps;
+    const runtimeMax = d.config.get().runtime.maxSteps;
     const { parent, entry } = a;
     let template = null;
     let ref = { source: entry.source };

package/dist/runtime/subagents/dispatch.d.ts

@@ -1,24 +1,44 @@
 import type { Logger } from "@capybara-hq/plugin-sdk";
 import { type AgentDefinition } from "../../agents/definition.js";
-import type { KernelConfig } from "../../config/schema.js";
 import type { EventLog } from "../../conversations/event-log.js";
-import type { EventPayload } from "../../conversations/events.js";
-import type { ConversationKind, KernelDb } from "../../db/kernel-schema.js";
+import type { ConversationEvent, EventPayload } from "../../conversations/events.js";
+import type { ConversationKind, KernelSchemaDb } from "../../db/kernel-schema.js";
+import type { KernelConfigService } from "../../infra/config/kernel-config.service.js";
 import type { ModelPurposesService } from "../../models/purposes.js";
 import { type AgentToolInputT } from "../../tools/builtins/agent.js";
 import type { ToolStepContext } from "../../tools/pipeline.js";
 import type { ProviderRegistry } from "../providers.js";
-import { type RunJobData } from "../run-queue.js";
+import { type RunJobData } from "../run-jobs.js";
+import { type CheckedOrgAgent } from "./definition.js";
+import { type RosterEntry } from "./roster.js";
 export interface DispatchDeps {
-    db: KernelDb;
+    /** The context's handle: inside {@link commitDispatchIn} it is the dispatch's transaction. */
+    db: KernelSchemaDb;
     eventLog: EventLog;
     purposes: Pick<ModelPurposesService, "resolve">;
     registry: Pick<ProviderRegistry, "resolve">;
-    config: () => KernelConfig;
+    config: Pick<KernelConfigService, "get">;
     /** Enqueues a child run (on the sub-agent run queue: `kind` is always `subagent`). */
     enqueue: (data: RunJobData, jobId: string, kind: ConversationKind) => Promise<void>;
     log: Pick<Logger, "error" | "warn">;
+    /**
+     * Runs {@link commitDispatchIn} in a transaction of its own (`SubagentsService.commitDispatch`,
+     * a `@Transactional` method).
+     */
+    commitDispatch: (a: DispatchArgs, plan: DispatchPlan, child: ChildWriter) => Promise<DispatchCommit | null>;
 }
+/** One dispatch's call. */
+export interface DispatchArgs {
+    ctx: ToolStepContext;
+    callId: string;
+    input: AgentToolInputT;
+    forSkill?: SkillForkDispatch;
+}
+/**
+ * Writes the child's events in the dispatch's transaction (`db` is its handle); `checked` is the
+ * org agent version the in-lock gates passed. Null refuses.
+ */
+export type ChildWriter = (db: KernelSchemaDb, checked?: CheckedOrgAgent) => Promise<ConversationEvent | null>;
 export type DispatchOutcome = {
     kind: "dispatched";
     childRunId: string;
@@ -28,7 +48,7 @@ export type DispatchOutcome = {
 };
 /**
  * A dispatch for a person's fork invocation (phase D spec §6.2, `advanceSkillForks`), not for a
- * model's `agent` call: `general-purpose` is always available (the `agent` tool and
+ * model's `Agent` call: `general-purpose` is always available (the `Agent` tool and
  * `subagents.general` do not gate it), an unknown type falls back to it with a warning, and the
  * child records the invoked skill.
  */
@@ -44,8 +64,26 @@ export interface SkillForkDispatch {
 }
 /** Idempotency key of the parent's `subagent_dispatched` event. */
 export declare const dispatchedIdemKey: (runId: string, callId: string) => string;
+/** What one dispatch writes, decided before its transaction. */
+export interface DispatchPlan {
+    childConversationId: string;
+    agentType: string;
+    source: RosterEntry["source"];
+    /**
+     * The child conversation's agent and its run's `agent_version`: the parent's for
+     * general-purpose and templates, the dispatched agent's frozen version for an org agent (§5.5).
+     */
+    agentId: string;
+    agentVersion: number;
+    resumed: boolean;
+    model: {
+        provider: string;
+        model: string;
+    };
+    tierFallback: boolean;
+}
 /**
- * Dispatches the sub-agent of one `agent` call (spec §7.1), after the pipeline's validation,
+ * Dispatches the sub-agent of one `Agent` call (spec §7.1), after the pipeline's validation,
  * policy, approval and `tool.preExecute` stages. A new sub-agent: resolves its type and effective
  * definition, then in one transaction (holding the parent run's row lock, so the dispatches of one
  * run serialize) inserts the child conversation, appends `subagent_started` and the task message,
@@ -67,3 +105,46 @@ export declare function dispatchSubagent(d: DispatchDeps, a: {
     /** Phase D: a person's fork invocation (see {@link SkillForkDispatch}). */
     forSkill?: SkillForkDispatch;
 }): Promise<DispatchOutcome>;
+/**
+ * The dispatch transaction shared by new sub-agents and follow-ups: locks the parent conversation
+ * row, then the parent run row (the order every terminal path uses),
+ * runs `child` (writes the child conversation's first events and returns the task message, or
+ * null to refuse), then inserts the child run and the dispatch row, appends `subagent_dispatched`
+ * and the audit row. After commit: notifies both conversations and enqueues the child run.
+ * Returns null when `child` refused.
+ *
+ * Under the parent run's row lock it first re-checks what the pipeline checked without it: a call
+ * already dispatched (a second holder of the same step, e.g. after a stalled-job takeover) gets
+ * the existing child run back and writes nothing, and a parent run that is no longer `running`
+ * (stopped, orphaned) dispatches nothing. Then the run's limits (§8.2, {@link subagentLimits}),
+ * read fresh: its children's token counter at or over the cap, its dispatches (follow-ups
+ * included) at the cap, or as many active children as may run at once each refuse with the §4.5
+ * text. The lock serializes the dispatches of one run, so the counts cannot race.
+ */
+/** What the dispatch transaction did. */
+export type DispatchCommit = {
+    kind: "existing";
+    childRunId: string;
+    requeue: {
+        conversationId: string;
+        seq: number;
+    } | null;
+} | {
+    kind: "stopped";
+} | {
+    kind: "limit";
+    content: string;
+} | {
+    kind: "gate";
+    outcome: DispatchOutcome;
+} | {
+    kind: "written";
+    childRunId: string;
+    childSeq: number;
+    parentSeq: number;
+};
+/**
+ * {@link commit}'s transaction (run by `SubagentsService.commitDispatch`, `d.db` its handle).
+ * Null when `child` refused.
+ */
+export declare function commitDispatchIn(d: Pick<DispatchDeps, "db" | "eventLog" | "config">, a: DispatchArgs, plan: DispatchPlan, child: ChildWriter): Promise<DispatchCommit | null>;