@capybara-hq/kernel 0.0.0-stage → 0.1.0-rc.1

package/dist/runtime/subagents/definition.js

@@ -0,0 +1,392 @@
+import { 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"];
+/**
+ * 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
+ * unknown type.
+ */
+export class SubagentTypeGoneError extends Error {
+    type;
+    constructor(type) {
+        super(`agent template ${type} not found`);
+        this.type = type;
+        this.name = "SubagentTypeGoneError";
+    }
+}
+const RANK = { ask: 1, deny: 2 };
+const isPolicy = (p) => p === "ask" || p === "deny";
+/**
+ * `base` with `over` applied on top, the stricter value winning per key (`deny` > `ask`). Values
+ * other than `ask` / `deny` (stored template data is not re-validated) are skipped on both sides.
+ */
+export function stricterPolicies(base, over) {
+    const out = {};
+    for (const [key, p] of Object.entries(base))
+        if (isPolicy(p))
+            out[key] = p;
+    for (const [key, p] of Object.entries(over)) {
+        if (!isPolicy(p))
+            continue;
+        const prev = out[key];
+        if (prev === undefined || RANK[p] > RANK[prev])
+            out[key] = p;
+    }
+    return out;
+}
+async function loadConnectors(db, orgId, refs) {
+    const ids = [...new Set(refs.flatMap((r) => (r.kind === "connector" ? [r.connectorId] : [])))];
+    const out = new Map();
+    if (ids.length === 0)
+        return out;
+    const rows = await db
+        .selectFrom("connectors")
+        .select(["id", "slug"])
+        .where("org_id", "=", orgId)
+        .where("deleted_at", "is", null)
+        .where("id", "in", ids)
+        .execute();
+    const tools = rows.length === 0
+        ? []
+        : await db
+            .selectFrom("connector_tools")
+            .select(["connector_id", "name"])
+            .where("connector_id", "in", rows.map((r) => r.id))
+            .orderBy("name")
+            .execute();
+    for (const r of rows) {
+        out.set(r.id, {
+            slug: r.slug,
+            tools: tools.filter((t) => t.connector_id === r.id).map((t) => t.name),
+        });
+    }
+    return out;
+}
+/**
+ * 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
+ * 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.
+ */
+function narrowTools(refs, connectors, allow, deny) {
+    const removed = new Set(CHILD_REMOVED_TOOLS);
+    const keep = (key) => !removed.has(key) && !deny.has(key) && (allow === null || allow.has(key));
+    const out = [];
+    for (const ref of refs) {
+        if (ref.kind === "builtin") {
+            if (keep(ref.name))
+                out.push(ref);
+        }
+        else if (ref.kind === "plugin") {
+            if (keep(toolKey(ref.plugin, ref.name)))
+                out.push(ref);
+        }
+        else {
+            const c = connectors.get(ref.connectorId);
+            if (!c) {
+                if (allow === null)
+                    out.push(ref);
+                continue;
+            }
+            const prefix = toolKey(c.slug, "");
+            if (ref.tools === "all" && allow === null && ![...deny].some((k) => k.startsWith(prefix))) {
+                out.push(ref);
+                continue;
+            }
+            const names = ref.tools === "all" ? c.tools : ref.tools;
+            const kept = names.filter((name) => keep(toolKey(c.slug, name)));
+            if (kept.length > 0)
+                out.push({ ...ref, tools: kept });
+        }
+    }
+    return out;
+}
+/**
+ * The template's skills the parent selects (its `orgSkills` or the parent agent's own skills),
+ * within the pinned limits (spec §5.3): inline templates name skill ids, plugin templates skill
+ * names (`<name>` or `<plugin>:<name>`). A name that matches more than one selected skill picks, in
+ * this order, the skill from the template's own plugin, the agent's own skill, the org skill (ties
+ * by id), with a warning. Dropped ones get a warning.
+ */
+async function pinnedFor(db, a, refs, byName) {
+    if (refs.length === 0)
+        return { pinned: [], warnings: [] };
+    const orgSkills = a.parent.skills?.orgSkills ?? [];
+    const rows = (await db
+        .selectFrom("skills as s")
+        .innerJoin("skill_versions as v", (j) => j.onRef("v.skill_id", "=", "s.id").onRef("v.version", "=", "s.current_version"))
+        .leftJoin("catalog_items as c", "c.id", "s.catalog_item_id")
+        .select(["s.id", "s.name", "s.scope", "v.manifest", "c.name as plugin"])
+        .where("s.org_id", "=", a.orgId)
+        .where("s.deleted_at", "is", null)
+        .where((eb) => {
+        const own = eb.and([eb("s.scope", "=", "agent"), eb("s.agent_id", "=", a.parentAgentId)]);
+        return orgSkills.length === 0
+            ? own
+            : eb.or([own, eb.and([eb("s.scope", "=", "org"), eb("s.id", "in", orgSkills)])]);
+    })
+        .orderBy("s.id")
+        .execute()).map((r) => ({
+        id: r.id,
+        name: r.name,
+        scope: r.scope,
+        plugin: r.plugin,
+        bytes: r.manifest.files.find((f) => f.path === SKILL_ENTRY_FILE)?.size ?? 0,
+    }));
+    const pinned = [];
+    const warnings = [];
+    const own = byName?.plugin;
+    const rank = (r) => own !== undefined && r.plugin === own ? 0 : r.scope === "agent" ? 1 : 2;
+    const match = (ref) => {
+        if (byName === null)
+            return rows.find((r) => r.id === ref);
+        const i = ref.indexOf(":");
+        const found = i < 0
+            ? rows.filter((r) => r.name === ref)
+            : rows.filter((r) => r.name === ref.slice(i + 1) && r.plugin === ref.slice(0, i));
+        // rows are ordered by id, and the sort is stable: ties keep that order
+        const [first, ...rest] = found.sort((x, y) => rank(x) - rank(y));
+        if (first && rest.length > 0) {
+            const which = [`the one from the plugin ${own}`, "the agent's own skill", "the org skill"][rank(first)];
+            warnings.push(`The skill name "${ref}" matches more than one selected skill; ${which} was pinned.`);
+        }
+        return first;
+    };
+    let total = 0;
+    for (const ref of refs) {
+        const r = match(ref);
+        if (!r) {
+            warnings.push(`The skill "${ref}" was not pinned: the agent does not select it.`);
+            continue;
+        }
+        if (pinned.includes(r.id))
+            continue;
+        if (pinned.length >= PINNED_SKILLS_LIMITS.count) {
+            warnings.push(`The skill "${r.name}" was not pinned: at most 3 skills can be pinned.`);
+            continue;
+        }
+        if (total + r.bytes > PINNED_SKILLS_LIMITS.totalBytes) {
+            warnings.push(`The skill "${r.name}" was not pinned: pinned skills are limited to 32 KB in total.`);
+            continue;
+        }
+        total += r.bytes;
+        pinned.push(r.id);
+    }
+    return { pinned, warnings };
+}
+/** The `effort` declaration of `model`, or null (or when the model cannot be resolved). */
+async function effortDecl(registry, model) {
+    try {
+        const { info } = await registry.resolve(model);
+        return info.parameters.find((p) => p.standard === "effort") ?? null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Model, params and fallback of a sub-agent (spec §5.4). */
+async function resolveTier(d, orgId, parent, tier) {
+    const inherit = {
+        model: parent.model,
+        modelParams: parent.modelParams,
+        fallback: parent.fallback,
+        fallbackParams: parent.fallbackParams,
+    };
+    if (tier === "inherit")
+        return { ...inherit, tierFallback: false };
+    try {
+        const target = await d.purposes.resolve(orgId, `subagent_${tier}`);
+        return {
+            model: target.model,
+            modelParams: target.params,
+            fallback: null,
+            fallbackParams: {},
+            tierFallback: false,
+        };
+    }
+    catch (e) {
+        if (e instanceof ApiError && e.code === "model.unconfigured") {
+            return { ...inherit, tierFallback: true };
+        }
+        throw e;
+    }
+}
+/** `"{parent name} › {agent type}"`, within the 80-character name limit. */
+const childName = (parent, type) => `${parent} › ${type}`.slice(0, 80);
+function orgAgentDefinition(d, a) {
+    // the version the gates checked (checkOrgAgent), never read again here: a version saved in
+    // between could be one the gates never saw (batch 3 review M1)
+    if (a.orgAgent === undefined) {
+        throw new Error(`org agent ${a.entry.type} dispatched without its checked version`);
+    }
+    const agentId = a.entry.agentId ?? "";
+    const own = a.orgAgent.definition;
+    const { subagents: _subagents, skills, ...rest } = own;
+    const definition = {
+        ...rest,
+        // its own tools, not intersected with the parent's; only the child-removed ones go
+        tools: narrowTools(own.tools, new Map(), null, new Set()),
+        // its policies, then the parent's on top, stricter wins (keys outside its tools are inert)
+        toolPolicies: stricterPolicies(own.toolPolicies ?? {}, a.parent.toolPolicies ?? {}),
+        ...(skills !== undefined && {
+            skills: {
+                orgSkills: skills.orgSkills,
+                ...(skills.pinned !== undefined && { pinned: skills.pinned }),
+            },
+        }),
+    };
+    return {
+        definition,
+        template: { source: "agent", id: agentId, version: a.orgAgent.version },
+        maxSteps: d.config().runtime.maxSteps,
+        warnings: [],
+        model: own.model,
+        tierFallback: false,
+    };
+}
+/**
+ * The effective definition of a sub-agent at its first dispatch (spec §5.3–§5.5):
+ * - `general` / `inline` / `plugin`: the parent's definition narrowed by the template (tools by
+ *   resolved key, `disallowedTools`, {@link CHILD_REMOVED_TOOLS}; policies stricter-wins), the
+ *   template's instructions, pinned = the template's skills the parent selects (general pins
+ *   nothing), `maxSteps = min(template ?? runtime.maxSteps, runtime.maxSteps)`, and the model tier
+ *   `tier` (the call's) → the template's → `inherit`; an unmapped tier runs on the parent's model
+ *   (`tierFallback`); a template `effort` is set when the resolved model declares it;
+ * - `agent`: the org agent's version that passed the gates (`orgAgent`, from {@link checkOrgAgent}),
+ *   its own tools minus the child-removed ones, its policies with the parent's on top (stricter
+ *   wins), its skills and model; `tier` ignored.
+ * The `subagents` block is never part of a child's definition (depth 1).
+ */
+export async function effectiveDefinition(d, a) {
+    if (a.entry.source === "agent")
+        return orgAgentDefinition(d, a);
+    const runtimeMax = d.config().runtime.maxSteps;
+    const { parent, entry } = a;
+    let template = null;
+    let ref = { source: entry.source };
+    if (entry.source === "inline") {
+        template = parent.subagents?.inline?.find((t) => t.name === entry.type) ?? null;
+        if (!template)
+            throw new SubagentTypeGoneError(entry.type);
+    }
+    else if (entry.source === "plugin") {
+        const row = (await loadTemplates(d.db, a.orgId, [entry.templateId ?? ""])).get(entry.templateId ?? "");
+        if (!row)
+            throw new SubagentTypeGoneError(entry.type);
+        template = row.template;
+        ref = { source: "plugin", id: row.id, version: row.version, plugin: row.plugin };
+    }
+    const connectors = await loadConnectors(d.db, a.orgId, parent.tools);
+    const tools = narrowTools(parent.tools, connectors, template?.tools !== undefined ? new Set(template.tools) : null, new Set(template?.disallowedTools ?? []));
+    const toolPolicies = stricterPolicies(parent.toolPolicies ?? {}, template?.toolPolicies ?? {});
+    const { pinned, warnings } = await pinnedFor(d.db, a, template?.skills ?? [], entry.source === "plugin" ? { plugin: entry.plugin } : null);
+    const tier = a.tier ?? template?.model ?? "inherit";
+    const m = await resolveTier(d, a.orgId, parent, tier);
+    let modelParams = m.modelParams;
+    if (template?.effort !== undefined) {
+        const decl = await effortDecl(d.registry, m.model);
+        if (decl) {
+            const v = sanitizeParams([decl], { [decl.key]: template.effort }).value[decl.key];
+            if (v !== undefined)
+                modelParams = { ...modelParams, [decl.key]: v };
+        }
+    }
+    const parentSkills = parent.skills;
+    const definition = {
+        name: childName(parent.name, entry.type),
+        avatarUrl: parent.avatarUrl,
+        instructions: template?.instructions ?? parent.instructions,
+        model: m.model,
+        fallback: m.fallback,
+        modelParams,
+        fallbackParams: m.fallbackParams,
+        tools,
+        toolPolicies,
+        ...((parentSkills !== undefined || pinned.length > 0) && {
+            skills: {
+                orgSkills: parentSkills?.orgSkills ?? [],
+                ...(pinned.length > 0 && { pinned }),
+            },
+        }),
+    };
+    return {
+        definition,
+        template: ref,
+        maxSteps: Math.min(template?.maxSteps ?? runtimeMax, runtimeMax),
+        warnings,
+        model: m.model,
+        tierFallback: m.tierFallback,
+    };
+}
+/**
+ * The refs of `frozen` that `current` still has: a builtin or plugin tool by name, a connector by
+ * id; a connector's `all` meets the other side's names (`all` on both stays `all`), and a
+ * connector left with no names is dropped. Pure: a connector `current` lists is not looked up.
+ */
+export function intersectTools(frozen, current) {
+    const out = [];
+    for (const ref of frozen) {
+        if (ref.kind === "builtin") {
+            if (current.some((c) => c.kind === "builtin" && c.name === ref.name))
+                out.push(ref);
+        }
+        else if (ref.kind === "plugin") {
+            if (current.some((c) => c.kind === "plugin" && c.plugin === ref.plugin && c.name === ref.name)) {
+                out.push(ref);
+            }
+        }
+        else {
+            const c = current.find((x) => x.kind === "connector" && x.connectorId === ref.connectorId);
+            if (!c)
+                continue;
+            if (c.tools === "all") {
+                out.push(ref);
+                continue;
+            }
+            const names = ref.tools === "all" ? c.tools : ref.tools.filter((n) => c.tools.includes(n));
+            if (names.length > 0)
+                out.push({ ...ref, tools: names });
+        }
+    }
+    return out;
+}
+/**
+ * The narrowing of a follow-up (final review I1): `frozen` (the child's `subagent_started`
+ * definition) against `current`, the definition a fresh dispatch would read now: the dispatching
+ * parent run's version for `general` / inline / plugin children, the dispatched org agent's
+ * current version for an org agent child (whose tools are its own at dispatch too, §5.5). Its
+ * `orgSkills` keep only those `current` still selects; a pinned id that was one of the frozen org
+ * skills goes with it (the agent's own skills stay).
+ */
+export function narrowFollowUp(frozen, current) {
+    const tools = intersectTools(frozen.tools, current.tools);
+    if (frozen.skills === undefined)
+        return { tools };
+    const frozenOrg = new Set(frozen.skills.orgSkills);
+    const now = new Set(current.skills?.orgSkills ?? []);
+    const orgSkills = frozen.skills.orgSkills.filter((id) => now.has(id));
+    const pinned = frozen.skills.pinned?.filter((id) => !frozenOrg.has(id) || now.has(id));
+    return { tools, skills: { orgSkills, ...(pinned !== undefined && { pinned }) } };
+}
+/** The definition a child run uses: the frozen one with its trigger's follow-up narrowing. */
+export function childRunDefinition(frozen, narrowed) {
+    if (narrowed === undefined)
+        return frozen;
+    const { skills, ...rest } = frozen;
+    const kept = skills === undefined || narrowed.skills === undefined
+        ? skills
+        : {
+            ...skills,
+            orgSkills: narrowed.skills.orgSkills,
+            ...(narrowed.skills.pinned !== undefined && { pinned: narrowed.skills.pinned }),
+        };
+    return { ...rest, tools: narrowed.tools, ...(kept !== undefined && { skills: kept }) };
+}

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

@@ -0,0 +1,69 @@
+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 { 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";
+export interface DispatchDeps {
+    db: KernelDb;
+    eventLog: EventLog;
+    purposes: Pick<ModelPurposesService, "resolve">;
+    registry: Pick<ProviderRegistry, "resolve">;
+    config: () => KernelConfig;
+    /** 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">;
+}
+export type DispatchOutcome = {
+    kind: "dispatched";
+    childRunId: string;
+} | {
+    kind: "refused";
+    content: string;
+};
+/**
+ * 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
+ * `subagents.general` do not gate it), an unknown type falls back to it with a warning, and the
+ * child records the invoked skill.
+ */
+export interface SkillForkDispatch {
+    /** The invocation message's seq. */
+    seq: number;
+    /** The invocation record (`user_message.skill`), also put on the child's task message. */
+    skill: NonNullable<EventPayload<"user_message">["skill"]>;
+    /** Warnings decided when rendering the task (`SkillInvoker.renderTask`). */
+    warnings: string[];
+    /** The task for the sub-agent's effective definition (replaces `input.prompt`). */
+    task: (child: AgentDefinition) => string;
+}
+/** Idempotency key of the parent's `subagent_dispatched` event. */
+export declare const dispatchedIdemKey: (runId: string, callId: string) => string;
+/**
+ * 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,
+ * inserts the child run (`queued`) and the `subagent_dispatches` row, appends `subagent_dispatched`
+ * to the parent and audits `subagent.dispatched`. A `resume` appends the follow-up message and
+ * starts the child's next run the same way. After commit the child run is enqueued; a failed
+ * enqueue only logs (the dispatch is durable, the wait sweep re-enqueues it).
+ *
+ * Refusals (§4.5) start nothing: a call from a sub-agent, an unknown type, an org agent that fails
+ * one of its gates ({@link orgAgentGates}, at every dispatch and follow-up; audited
+ * `subagent.refused`), `resume` with `subagent_type` / `model`, a `resume` id that is not a
+ * sub-agent of this conversation (whatever it is otherwise: no detail about other conversations),
+ * or one whose run is still active.
+ */
+export declare function dispatchSubagent(d: DispatchDeps, a: {
+    ctx: ToolStepContext;
+    callId: string;
+    input: AgentToolInputT;
+    /** Phase D: a person's fork invocation (see {@link SkillForkDispatch}). */
+    forSkill?: SkillForkDispatch;
+}): Promise<DispatchOutcome>;