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

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

@@ -1,4 +1,6 @@
+import type { Logger } from "@capybara-hq/plugin-sdk";
 import type { AgentDefinition } from "../../agents/definition.js";
+import { templateTypeOf } from "../../agents/templates.js";
 import type { KernelSchemaDb } from "../../db/kernel-schema.js";
 /**
  * The sub-agent roster of an agent version (phase C, spec §4.3, §5.1): the agent types its `agent`
@@ -10,8 +12,18 @@ export interface RosterEntry {
     source: "general" | "inline" | "plugin" | "agent";
     /** When to use it (shown in the tool description), cut to {@link ROSTER_DESCRIPTION_MAX}. */
     description: string;
-    /** Plugin templates: the `agent_templates` id. */
+    /**
+     * Plugin templates: the selected id (an org template's, a linked copy's own, or a platform
+     * template's; `subagent_started.template.id`).
+     */
     templateId?: string;
+    /**
+     * Plugin templates: other selected ids this entry stands for: ids resolving to the same platform
+     * template under this type (an org copy linked since the save), or a selected platform id an org
+     * row of the same component shadows (the entry is that row); a follow-up recorded under one of
+     * them finds this entry.
+     */
+    aliasTemplateIds?: string[];
     /** Org agents: the allowlisted agent id. */
     agentId?: string;
     /** Org agents: the agent's current name, when it is still a live agent of the org. */
@@ -22,16 +34,21 @@ export interface RosterEntry {
 export declare const ROSTER_DESCRIPTION_MAX = 1024;
 /** The description of `general-purpose` in the roster (spec §4.3, model-visible). */
 export declare const GENERAL_PURPOSE_DESCRIPTION = "a copy of you with your tools and skills, for multi-step work.";
-/** Plugin template type: `<plugin>:<name>`. */
-export declare const templateType: (plugin: string, name: string) => string;
+/** Plugin template type: `<plugin>:<name>`; the bare `<name>` for a template without a plugin. */
+export declare const templateType: typeof templateTypeOf;
 /**
  * Resolves the roster of `parent` (spec §4.3): `general-purpose` first unless
  * `subagents.general === false`, then the plugin templates, inline templates and allowlisted org
- * agents, each in the owner's order, at most {@link SUBAGENT_ROSTER_MAX} entries. Templates deleted
- * since the save are skipped; allowlisted org agents stay listed (the dispatch checks their gates
- * and refuses with the §4.5 text), with `agentName` only while the agent is live.
+ * agents, each in the owner's order, at most {@link SUBAGENT_ROSTER_MAX} entries. Templates are
+ * the org's and the platform's ({@link loadTemplates}); ones deleted or off since the save are
+ * skipped. A template whose type is taken (`general-purpose`, an earlier template, an inline
+ * template's name; only a bare `<name>` can clash with the last two kinds, and the save refuses
+ * every clash) is skipped with a warning; when it resolves to the same platform template as the
+ * entry kept, its id becomes that entry's alias. Allowlisted org agents stay listed (the dispatch
+ * checks their gates and refuses with the §4.5 text), with `agentName` only while the agent is
+ * live.
  */
-export declare function resolveRoster(db: KernelSchemaDb, orgId: string, parent: Pick<AgentDefinition, "subagents">): Promise<RosterEntry[]>;
+export declare function resolveRoster(db: KernelSchemaDb, orgId: string, parent: Pick<AgentDefinition, "subagents">, log?: Pick<Logger, "warn">): Promise<RosterEntry[]>;
 /**
  * The roster entry for a requested `subagent_type`: an exact type first; else a bare `<name>`
  * matches the plugin template `<plugin>:<name>` when exactly one has it (as Claude Code accepts

package/dist/runtime/subagents/roster.js

@@ -1,19 +1,24 @@
 import { SUBAGENT_ROSTER_MAX } from "../../agents/definition.js";
-import { loadTemplates } from "../../agents/templates.js";
+import { loadTemplates, templateTypeOf } from "../../agents/templates.js";
 export const ROSTER_DESCRIPTION_MAX = 1024;
 /** The description of `general-purpose` in the roster (spec §4.3, model-visible). */
 export const GENERAL_PURPOSE_DESCRIPTION = "a copy of you with your tools and skills, for multi-step work.";
 const cut = (s) => s.slice(0, ROSTER_DESCRIPTION_MAX);
-/** Plugin template type: `<plugin>:<name>`. */
-export const templateType = (plugin, name) => `${plugin}:${name}`;
+/** Plugin template type: `<plugin>:<name>`; the bare `<name>` for a template without a plugin. */
+export const templateType = templateTypeOf;
 /**
  * Resolves the roster of `parent` (spec §4.3): `general-purpose` first unless
  * `subagents.general === false`, then the plugin templates, inline templates and allowlisted org
- * agents, each in the owner's order, at most {@link SUBAGENT_ROSTER_MAX} entries. Templates deleted
- * since the save are skipped; allowlisted org agents stay listed (the dispatch checks their gates
- * and refuses with the §4.5 text), with `agentName` only while the agent is live.
+ * agents, each in the owner's order, at most {@link SUBAGENT_ROSTER_MAX} entries. Templates are
+ * the org's and the platform's ({@link loadTemplates}); ones deleted or off since the save are
+ * skipped. A template whose type is taken (`general-purpose`, an earlier template, an inline
+ * template's name; only a bare `<name>` can clash with the last two kinds, and the save refuses
+ * every clash) is skipped with a warning; when it resolves to the same platform template as the
+ * entry kept, its id becomes that entry's alias. Allowlisted org agents stay listed (the dispatch
+ * checks their gates and refuses with the §4.5 text), with `agentName` only while the agent is
+ * live.
  */
-export async function resolveRoster(db, orgId, parent) {
+export async function resolveRoster(db, orgId, parent, log) {
     const sub = parent.subagents;
     const out = [];
     if (sub?.general !== false) {
@@ -24,19 +29,50 @@ export async function resolveRoster(db, orgId, parent) {
         });
     }
     const templateIds = sub?.templates ?? [];
-    const templates = await loadTemplates(db, orgId, templateIds);
+    const templates = await loadTemplates(db, orgId, templateIds, log);
+    const inlineNames = new Set((sub?.inline ?? []).map((t) => t.name));
+    const kept = new Map();
+    const alias = (e, id) => {
+        if (e.templateId !== id && !e.aliasTemplateIds?.includes(id)) {
+            e.aliasTemplateIds = [...(e.aliasTemplateIds ?? []), id];
+        }
+    };
     for (const id of templateIds) {
         const r = templates.get(id);
         if (!r)
             continue;
+        const type = templateType(r.plugin, r.name);
+        const first = kept.get(type);
+        if (first !== undefined || type === "general-purpose" || inlineNames.has(type)) {
+            if (first !== undefined &&
+                (first.entry.templateId === r.id ||
+                    (r.platformTemplateId !== undefined && first.platformTemplateId === r.platformTemplateId))) {
+                alias(first.entry, id);
+                continue;
+            }
+            log?.warn("agent template skipped in the roster: its type is taken", {
+                orgId,
+                type,
+                templateId: r.id,
+            });
+            continue;
+        }
         const description = r.template.description;
-        out.push({
-            type: templateType(r.plugin, r.name),
+        const entry = {
+            type,
             source: "plugin",
             description: cut(typeof description === "string" ? description : ""),
             templateId: r.id,
-            plugin: r.plugin,
+            ...(r.plugin ? { plugin: r.plugin } : {}),
+        };
+        // a selected platform id that an org row of the same component shadows resolves to that row
+        if (r.id !== id)
+            alias(entry, id);
+        kept.set(type, {
+            entry,
+            ...(r.platformTemplateId !== undefined && { platformTemplateId: r.platformTemplateId }),
         });
+        out.push(entry);
     }
     for (const t of sub?.inline ?? []) {
         out.push({ type: t.name, source: "inline", description: cut(t.description) });

package/dist/runtime/subagents/skill-fork.d.ts

@@ -8,8 +8,9 @@ import { type DispatchDeps } from "./dispatch.js";
 /**
  * Forked skills (phase D spec §6): a person's invocation of a `context: fork` skill starts its own
  * run (the run boundary, {@link forkBoundary}), whose `prepare` node dispatches the sub-agent
- * through phase C's `dispatchSubagent` before any model call and waits on it like an `Agent` call
- * (`subagents` wait `sa-<runId>-0`). When the child has ended, `prepare` appends the model-visible
+ * through phase C's `dispatchSubagent` before any model call and waits on it (`subagents` wait
+ * `sa-<runId>-0`; the dispatch row has `for_skill`, agent map spec §5.4: a fork stays in the
+ * foreground while `Agent` calls run in the background). When the child has ended, `prepare` appends the model-visible
  * `skill_fork_result` and the parent's model answers. Every terminal path of the run (and the wait
  * sweep) pairs a fork invocation without a report ({@link pairStoppedForks}), so the log never holds
  * a fork lead whose report is missing before the next model call.

package/dist/runtime/subagents/skill-fork.js

@@ -7,8 +7,9 @@ import { dispatchSubagent } from "./dispatch.js";
 /**
  * Forked skills (phase D spec §6): a person's invocation of a `context: fork` skill starts its own
  * run (the run boundary, {@link forkBoundary}), whose `prepare` node dispatches the sub-agent
- * through phase C's `dispatchSubagent` before any model call and waits on it like an `Agent` call
- * (`subagents` wait `sa-<runId>-0`). When the child has ended, `prepare` appends the model-visible
+ * through phase C's `dispatchSubagent` before any model call and waits on it (`subagents` wait
+ * `sa-<runId>-0`; the dispatch row has `for_skill`, agent map spec §5.4: a fork stays in the
+ * foreground while `Agent` calls run in the background). When the child has ended, `prepare` appends the model-visible
  * `skill_fork_result` and the parent's model answers. Every terminal path of the run (and the wait
  * sweep) pairs a fork invocation without a report ({@link pairStoppedForks}), so the log never holds
  * a fork lead whose report is missing before the next model call.
@@ -92,7 +93,7 @@ export async function advanceSkillForks(d, a) {
     const callId = skillCallId(seq);
     const row = await dispatchOfCall(d.db, ctx.runId, callId);
     if (row) {
-        const r = await childResult(d.eventLog, row, { forSkill: true });
+        const r = await childResult(d.eventLog, row);
         if (!r)
             return ctx.signal.aborted ? { kind: "aborted" } : suspend(d, ctx);
         await report(r.content, row, [finishedEvent(row, r.finished)]);
@@ -236,6 +237,7 @@ t, eventLog, runId) {
         "parent_conversation_id",
         "child_conversation_id",
         "child_run_id",
+        "budget_run_id",
     ])
         .where("parent_run_id", "=", runId)
         .where("parent_call_id", "=", callId)
@@ -251,6 +253,8 @@ t, eventLog, runId) {
             parentConversationId: d.parent_conversation_id,
             childConversationId: d.child_conversation_id,
             childRunId: d.child_run_id,
+            budgetRunId: d.budget_run_id,
+            forSkill: true,
         };
         const child = await t
             .selectFrom("runs")
@@ -259,7 +263,7 @@ t, eventLog, runId) {
             .executeTakeFirst();
         // a child that already ended keeps its own result (its log is committed)
         const ended = child !== undefined && TERMINAL_STATUSES.has(child.status)
-            ? await childResult(eventLog, row, { forSkill: true })
+            ? await childResult(eventLog, row)
             : null;
         if (ended)
             events.push(finishedEvent(row, ended.finished));

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

@@ -0,0 +1,14 @@
+import type { EventPayload } from "../../conversations/events.js";
+/** How a sub-agent's run ended (`subagent_finished.status`, a finished `subagent_delivery`). */
+export type SubagentStatus = EventPayload<"subagent_finished">["status"];
+/** Who stopped an aborted sub-agent: a person, or the kernel on its parent run's behalf. */
+export type SubagentAbortedBy = "user" | "parent";
+/**
+ * How a sub-agent's run ended, as the model reads it: the status of `agentResultText`'s bracket
+ * line (a fork invocation's report) and of a finished `subagent_delivery`
+ * (`renderSubagentDelivery`).
+ */
+export declare function subagentStatusText(status: SubagentStatus, opts?: {
+    errorCode?: string | undefined;
+    abortedBy?: SubagentAbortedBy | undefined;
+}): string;

package/dist/runtime/subagents/status.js

@@ -0,0 +1,23 @@
+/**
+ * How a sub-agent's run ended, as the model reads it: the status of `agentResultText`'s bracket
+ * line (a fork invocation's report) and of a finished `subagent_delivery`
+ * (`renderSubagentDelivery`).
+ */
+export function subagentStatusText(status, opts = {}) {
+    switch (status) {
+        case "completed":
+            return "completed";
+        case "max_steps":
+            return "stopped at the step limit; the reply may be partial";
+        case "max_duration":
+            return "stopped at the time limit; the reply may be partial";
+        case "budget":
+            return "stopped: token budget used up";
+        case "aborted":
+            return opts.abortedBy === "parent" ? "stopped with this run" : "stopped by the user";
+        case "timed_out":
+            return "timed out";
+        case "failed":
+            return opts.errorCode === undefined ? "failed" : `failed (${opts.errorCode})`;
+    }
+}

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

@@ -15,9 +15,9 @@ import { type SkillForkDeps, type SkillForks } 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`).
+ * to the sub-agent run queue through {@link RunJobs}. The child lifecycle after dispatch is the
+ * waits' (`Waits.childFinished`): a background child's finish is delivered to its parent
+ * ({@link SubagentDeliveries}), a fork invocation's child resumes its waiting parent run.
  */
 export declare class SubagentsService {
     private readonly bus;
@@ -35,6 +35,9 @@ export declare class SubagentsService {
     /** A sub-agent's finished step on its parent's stream (sub-agents spec §14.2). Never throws. */
     progress(s: SubagentStep): Promise<void>;
 }
-/** Sub-agent dispatch (the tools domain's `Agent` tool and the run loop use it). */
+/**
+ * Sub-agent dispatch, deliveries and messages (the tools domain's `Agent`, `SendMessage` and
+ * `SubagentHandback`, the run loop, the waits).
+ */
 export declare class SubagentsModule {
 }

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

@@ -20,16 +20,18 @@ 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 { SubagentDeliveries } from "./deliveries.js";
 import { commitDispatchIn, dispatchSubagent, } from "./dispatch.js";
+import { SubagentMessages } from "./messages.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`).
+ * to the sub-agent run queue through {@link RunJobs}. The child lifecycle after dispatch is the
+ * waits' (`Waits.childFinished`): a background child's finish is delivered to its parent
+ * ({@link SubagentDeliveries}), a fork invocation's child resumes its waiting parent run.
  */
 let SubagentsService = class SubagentsService {
     bus;
@@ -88,14 +90,17 @@ SubagentsService = __decorate([
     __param(9, Inject(TransactionHost))
 ], SubagentsService);
 export { SubagentsService };
-/** Sub-agent dispatch (the tools domain's `Agent` tool and the run loop use it). */
+/**
+ * Sub-agent dispatch, deliveries and messages (the tools domain's `Agent`, `SendMessage` and
+ * `SubagentHandback`, the run loop, the waits).
+ */
 let SubagentsModule = class SubagentsModule {
 };
 SubagentsModule = __decorate([
     Module({
         imports: [EventLogModule, ModelsModule, ProvidersModule, RunJobsModule, SkillsModule],
-        providers: [SubagentsService],
-        exports: [SubagentsService],
+        providers: [SubagentsService, SubagentDeliveries, SubagentMessages],
+        exports: [SubagentsService, SubagentDeliveries, SubagentMessages],
     })
 ], SubagentsModule);
 export { SubagentsModule };

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

@@ -93,7 +93,8 @@ export declare function narrowPending(stored: readonly string[] | undefined, fai
  *   using up an attempt.
  * Handlers must be idempotent by `eventId` (`<conversationId>/<seq>`). Nothing is written to the event
  * log (never model-visible). Compaction calls log usage too (`purpose: "compaction"`) and are reported,
- * as are conversation title calls (`purpose: "title"`, no run: `runId` is "").
+ * as are conversation title calls (`purpose: "title"`, no run: `runId` is "") and `WebFetch`
+ * extraction calls (`purpose: "web_fetch"`).
  * Single-step eval replays and judge requests log no usage: not reported (M7).
  */
 export declare class UsageReporter {

package/dist/runtime/usage-report.js

@@ -13,7 +13,7 @@ import { DelayedError, Job, UnrecoverableError, } from "bullmq";
 import { sql } from "kysely";
 import { enabledExtensionsQuery } from "../extensions/enabled.js";
 import { ExtensionsModule } from "../extensions/extensions.module.js";
-import { deepFreeze, errMsg } from "../extensions/hooks.js";
+import { deepFreeze, errMsg, HookNeedsConfigError, } from "../extensions/hooks.js";
 import { ExtensionHost } from "../extensions/host.js";
 import { STALE_RECONCILE_PERIODS } from "../extensions/lifecycle-topics.js";
 import { KernelConfigService } from "../infra/config/kernel-config.service.js";
@@ -22,6 +22,7 @@ import { LockService } from "../infra/lock/lock.service.js";
 import { QueueModule } from "../infra/queue/queue.module.js";
 import { LockedCron } from "../infra/schedule/locked-cron.decorator.js";
 import { KERNEL_LOGGER } from "../infra/tokens.js";
+import { deliveryRowOfChildRun } from "./subagents/child.js";
 /** Queue of `usage.report` deliveries (no `:` in the name). */
 export const USAGE_REPORT_QUEUE = "cap-kernel-usage-report";
 /** One job per `usage` event (no `:`: conversation ids are UUIDs, seq is a number). */
@@ -160,7 +161,8 @@ export function narrowPending(stored, failed) {
  *   using up an attempt.
  * Handlers must be idempotent by `eventId` (`<conversationId>/<seq>`). Nothing is written to the event
  * log (never model-visible). Compaction calls log usage too (`purpose: "compaction"`) and are reported,
- * as are conversation title calls (`purpose: "title"`, no run: `runId` is "").
+ * as are conversation title calls (`purpose: "title"`, no run: `runId` is "") and `WebFetch`
+ * extraction calls (`purpose: "web_fetch"`).
  * Single-step eval replays and judge requests log no usage: not reported (M7).
  */
 let UsageReporter = class UsageReporter {
@@ -370,8 +372,6 @@ let UsageReporter = class UsageReporter {
             .selectFrom("conversation_events as e")
             .innerJoin("conversations as c", "c.id", "e.conversation_id")
             .leftJoin("runs as r", "r.id", "e.run_id")
-            // a sub-agent's run: its dispatch says where it was dispatched from (spec §11)
-            .leftJoin("subagent_dispatches as sd", "sd.child_run_id", "e.run_id")
             .select([
             "e.payload",
             "e.run_id",
@@ -382,9 +382,6 @@ let UsageReporter = class UsageReporter {
             "c.account_id",
             "c.kind",
             "r.trigger_account_id",
-            "sd.parent_conversation_id",
-            "sd.parent_run_id",
-            "sd.parent_call_id",
         ])
             .where("e.conversation_id", "=", conversationId)
             .where("e.seq", "=", String(seq))
@@ -392,6 +389,11 @@ let UsageReporter = class UsageReporter {
         if (row?.type !== "usage")
             return null;
         const p = row.payload;
+        // a sub-agent's run: where it was dispatched from (spec §11), its own dispatch, else (a wake
+        // run nobody dispatched, agent map spec §5.3) its conversation's latest one
+        const parent = row.kind === "subagent" && row.run_id !== null
+            ? await deliveryRowOfChildRun(this.db, row.run_id)
+            : null;
         return {
             eventId: `${conversationId}/${seq}`,
             purpose: p.purpose ?? "step",
@@ -402,13 +404,11 @@ let UsageReporter = class UsageReporter {
             // a sub-agent's calls report "chat" (spec §11: the SDK union is not widened)
             conversationKind: row.kind === "eval" ? "eval" : "chat",
             runId: row.run_id ?? "",
-            ...(row.parent_conversation_id !== null &&
-                row.parent_run_id !== null &&
-                row.parent_call_id !== null && {
+            ...(parent !== null && {
                 parent: {
-                    conversationId: row.parent_conversation_id,
-                    runId: row.parent_run_id,
-                    callId: row.parent_call_id,
+                    conversationId: parent.parentConversationId,
+                    runId: parent.parentRunId,
+                    callId: parent.parentCallId,
                 },
             }),
             provider: p.provider,
@@ -492,6 +492,12 @@ let UsageReporter = class UsageReporter {
                     notHere.push(plugin);
                 return;
             }
+            // layering spec A §6: the extension's effective config is not valid in this organization, so
+            // it is not called there (an observe hook skipped); dropped, not retried
+            if (r.reason instanceof HookNeedsConfigError) {
+                dropped.set(plugin, "needs configuration in this organization");
+                return;
+            }
             failed.push(plugin);
             if (!this.stopping.signal.aborted) {
                 this.log.warn("usage.report delivery to a plugin failed", {