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

package/dist/runtime/usage-report.js

@@ -9,9 +9,8 @@ var __param = (this && this.__param) || function (paramIndex, decorator) {
 };
 import { getQueueToken } from "@nestjs/bullmq";
 import { Inject, Injectable, Module, Optional } from "@nestjs/common";
-import { DelayedError, Job, UnrecoverableError, } from "bullmq";
+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, HookNeedsConfigError, } from "../extensions/hooks.js";
 import { ExtensionHost } from "../extensions/host.js";
@@ -19,31 +18,13 @@ import { STALE_RECONCILE_PERIODS } from "../extensions/lifecycle-topics.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 { 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). */
-export const usageReportJobId = (conversationId, seq) => `usage-${conversationId}-${seq}`;
-/** First attempt plus 5 retries (F11). */
-export const USAGE_REPORT_ATTEMPTS = 6;
-/** Retry backoff: 2 s, doubling (2, 4, 8, 16, 32 s). */
-export const USAGE_REPORT_BACKOFF_MS = 2000;
-/** Optional provider: the {@link UsageReportRetry} instead of the defaults above (tests). */
-export const USAGE_REPORT_RETRY = Symbol("USAGE_REPORT_RETRY");
-/** Failed jobs (given up) are kept for inspection, at most {@link KEEP_FAILED_MAX} of them. */
-const KEEP_FAILED_S = 7 * 86_400;
-/** Upper bound on kept failed jobs (I-2): a long outage of a billing endpoint cannot grow Redis. */
-const KEEP_FAILED_MAX = 100_000;
+import { modelUsageJobId, queryUsageSubscribers, USAGE_REPORT_ATTEMPTS, USAGE_REPORT_BACKOFF_MS, USAGE_REPORT_JOB, USAGE_REPORT_QUEUE, USAGE_REPORT_RETRY, UsageReportJobsModule, usageReportJobId, usageReportJobOpts, } from "./usage-report-jobs.js";
+export { ModelUsageJobs, modelUsageJobId, queryUsageSubscribers, USAGE_REPORT_ATTEMPTS, USAGE_REPORT_BACKOFF_MS, USAGE_REPORT_QUEUE, USAGE_REPORT_RETRY, UsageReportJobsModule, usageReportJobId, } from "./usage-report-jobs.js";
 /** Warnings about a plugin that cannot take deliveries are logged at most once per this window. */
 const WARN_WINDOW_MS = 60_000;
-/**
- * Upper bound on kept finished jobs (Redis memory). At the default retention it only bites above
- * ~1.1 usage events per second sustained for a day; dedupe needs the jobs only for the sweeper overlap.
- */
-const KEEP_COMPLETED_MAX = 100_000;
 /** The sweeper's cron job name (no `:`; every minute, once across replicas). */
 export const USAGE_SWEEP_JOB = "usage-report-sweep";
 /** The maintenance scheduler the sweep ran on before it became a `@LockedCron` (retired). */
@@ -57,38 +38,6 @@ export const USAGE_SWEEP_LAG_MS = 30_000;
  */
 export const USAGE_SWEEP_OVERLAP_MS = 10 * 60_000;
 const SWEEP_PAGE = 500;
-const JOB = "usage-report";
-/**
- * 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 async function queryUsageSubscribers(db, orgId) {
-    let q = db
-        .selectFrom("extension_permission_snapshots as s")
-        .select("s.plugin")
-        .where(sql `s.permissions -> 'permissions' -> 'hooks' ? 'usage.report'`)
-        .where((eb) => eb.or([
-        eb.exists(eb
-            .selectFrom("extension_installs as i")
-            .select(sql `1`.as("one"))
-            .whereRef("i.name", "=", "s.plugin")
-            .where("i.desired_state", "=", "enabled")),
-        // config-declared plugins still declared (and not unloaded) on some replica; installs are
-        // covered by desired_state above (their replica rows linger as `unloaded` when disabled)
-        eb.exists(eb
-            .selectFrom("extension_replica_status as r")
-            .select(sql `1`.as("one"))
-            .whereRef("r.plugin", "=", "s.plugin")
-            .where("r.source", "=", "config")
-            .where("r.state", "<>", "unloaded")),
-    ]));
-    if (orgId !== undefined) {
-        q = q.where("s.plugin", "in", enabledExtensionsQuery(db, orgId));
-    }
-    return new Set((await q.execute()).map((r) => r.plugin));
-}
 /**
  * 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
@@ -128,6 +77,10 @@ class Undeliverable extends Error {
         this.name = "Undeliverable";
     }
 }
+/** A job's identity: its `usage` event or its `model_usage` row. */
+const keyOf = (d) => d.usageId !== undefined
+    ? { usageId: d.usageId }
+    : { conversationId: d.conversationId, seq: d.seq };
 /**
  * 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.
@@ -159,11 +112,18 @@ export function narrowPending(stored, failed) {
  *   most 100 000. Each call runs through the instance's `inflight.run`, limited by `hooks.timeoutMs`;
  *   when this replica stops, in-flight calls are aborted and the job goes back to the queue without
  *   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,
+ * Handlers must be idempotent by `eventId` (`<conversationId>/<seq>`, or a `model_usage` row id).
+ * 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 "") and `WebFetch`
  * extraction calls (`purpose: "web_fetch"`).
  * Single-step eval replays and judge requests log no usage: not reported (M7).
+ * - **Model usage outside conversations** (spec B §5.4): each `ctx.models.embed` call writes a
+ *   `model_usage` row; on its `model_usage.recorded` event `ModelUsageJobs` (`usage-report-jobs.ts`)
+ *   enqueues job `usage-model-<rowId>` (only while some plugin subscribes); the payload
+ *   (`purpose: "embedding"`, `eventId` = the row id, the calling `extension`, no conversation fields)
+ *   is read from the row when the job runs, and the row's `reported_at` is set once nothing is left
+ *   to deliver; a job that gives up after its last attempt sets `report_failed_at`. The sweep
+ *   re-enqueues recent rows that are neither (see {@link sweep}).
  */
 let UsageReporter = class UsageReporter {
     kdb;
@@ -226,17 +186,8 @@ let UsageReporter = class UsageReporter {
     subscribers(orgId) {
         return queryUsageSubscribers(this.db, orgId);
     }
-    jobOpts(conversationId, seq) {
-        return {
-            jobId: usageReportJobId(conversationId, seq),
-            attempts: this.retry.attempts,
-            backoff: { type: "exponential", delay: this.retry.backoffMs },
-            removeOnComplete: {
-                age: this.config.get().hooks.usageReportKeepHours * 3600,
-                count: KEEP_COMPLETED_MAX,
-            },
-            removeOnFail: { age: KEEP_FAILED_S, count: KEEP_FAILED_MAX },
-        };
+    jobOpts(jobId) {
+        return usageReportJobOpts(jobId, this.retry, this.config.get().hooks.usageReportKeepHours);
     }
     /**
      * Enqueues the delivery of one `usage` event. Returns without a job when no plugin subscribes.
@@ -252,7 +203,7 @@ let UsageReporter = class UsageReporter {
         try {
             if ((await this.subscribers()).size === 0)
                 return;
-            await this.queue.add(JOB, { conversationId, seq }, this.jobOpts(conversationId, seq));
+            await this.queue.add(USAGE_REPORT_JOB, { conversationId, seq }, this.jobOpts(usageReportJobId(conversationId, seq)));
         }
         catch (err) {
             this.log.warn("cannot enqueue usage report", { conversationId, seq, err });
@@ -261,7 +212,10 @@ let UsageReporter = class UsageReporter {
     /**
      * One sweep (R13): re-enqueues the `usage` events created in `[watermark - overlap, now - lag]` in
      * pages, then advances the watermark to `now - lag`. With no subscriber it only advances. The first
-     * sweep starts at `now - lag - overlap`. Returns the number of events offered to the queue.
+     * sweep starts at `now - lag - overlap`. Also re-enqueues the `model_usage` rows of the same
+     * window that are neither reported nor given up (spec B §5.4),
+     * or, with no subscriber, marks those rows reported (nobody to deliver to). Returns the number of
+     * events and rows offered to the queue.
      */
     async sweep(opts = {}) {
         // bounds and keyset as full-precision timestamp text (microseconds), computed with the DB clock
@@ -278,7 +232,8 @@ let UsageReporter = class UsageReporter {
             .executeTakeFirst();
         const watermark = row?.watermark ?? to;
         let offered = 0;
-        if ((await this.subscribers()).size > 0) {
+        const subscribed = (await this.subscribers()).size > 0;
+        if (subscribed) {
             let after;
             for (;;) {
                 let q = this.db
@@ -298,9 +253,9 @@ let UsageReporter = class UsageReporter {
                     .execute();
                 if (page.length > 0) {
                     await this.queue.addBulk(page.map((r) => ({
-                        name: JOB,
+                        name: USAGE_REPORT_JOB,
                         data: { conversationId: r.conversation_id, seq: Number(r.seq) },
-                        opts: this.jobOpts(r.conversation_id, Number(r.seq)),
+                        opts: this.jobOpts(usageReportJobId(r.conversation_id, Number(r.seq))),
                     })));
                     offered += page.length;
                 }
@@ -310,6 +265,7 @@ let UsageReporter = class UsageReporter {
                 after = { at: last.at, conv: last.conversation_id, seq: String(last.seq) };
             }
         }
+        offered += await this.sweepModelUsage(watermark, to, subscribed);
         await this.db
             .insertInto("usage_report_sweep")
             .values({ id: 1, watermark: sql `${to}::timestamptz` })
@@ -320,6 +276,51 @@ let UsageReporter = class UsageReporter {
             .execute();
         return offered;
     }
+    /**
+     * The `model_usage` half of {@link sweep}: rows neither reported nor given up that occurred in
+     * the same window as the events (`[watermark - overlap, to]`), oldest first. Bounded like the
+     * event sweep, so a row whose job failed for good is never offered again, even after its failed
+     * job left Redis (no repeated backlog, no second delivery to plugins already served).
+     */
+    async sweepModelUsage(watermark, to, subscribed) {
+        if (!subscribed) {
+            await this.db
+                .updateTable("model_usage")
+                .set({ reported_at: sql `now()` })
+                .where("reported_at", "is", null)
+                .where(sql `occurred_at <= ${to}::timestamptz`)
+                .execute();
+            return 0;
+        }
+        let offered = 0;
+        let after;
+        for (;;) {
+            let q = this.db
+                .selectFrom("model_usage")
+                .select(["id", sql `occurred_at::text`.as("at")])
+                .where("reported_at", "is", null)
+                .where("report_failed_at", "is", null)
+                .where(sql `occurred_at >= ${watermark}::timestamptz - make_interval(secs => ${USAGE_SWEEP_OVERLAP_MS / 1000})`)
+                .where(sql `occurred_at <= ${to}::timestamptz`);
+            if (after) {
+                q = q.where(sql `(occurred_at, id) > (${after.at}::timestamptz, ${after.id}::uuid)`);
+            }
+            const page = await q.orderBy("occurred_at").orderBy("id").limit(SWEEP_PAGE).execute();
+            if (page.length > 0) {
+                await this.queue.addBulk(page.map((r) => ({
+                    name: USAGE_REPORT_JOB,
+                    data: { usageId: r.id },
+                    opts: this.jobOpts(modelUsageJobId(r.id)),
+                })));
+                offered += page.length;
+            }
+            const last = page.at(-1);
+            if (!last || page.length < SWEEP_PAGE)
+                break;
+            after = { at: last.at, id: last.id };
+        }
+        return offered;
+    }
     /**
      * 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).
@@ -344,14 +345,17 @@ let UsageReporter = class UsageReporter {
         const final = j.attemptsMade >= (j.opts.attempts ?? 1);
         const fields = {
             jobId: j.id,
-            conversationId: j.data.conversationId,
-            seq: j.data.seq,
+            ...(j.data.usageId !== undefined
+                ? { usageId: j.data.usageId }
+                : { conversationId: j.data.conversationId, seq: j.data.seq }),
             pending: j.data.pending,
             attempt: j.attemptsMade,
             error: err.message,
         };
-        if (final)
+        if (final) {
             this.log.error("usage report given up after retries", fields);
+            void this.markFailed(j.data);
+        }
         else
             this.log.warn("usage report attempt failed; retrying", fields);
     }
@@ -366,6 +370,67 @@ let UsageReporter = class UsageReporter {
         this.worker = undefined;
         await w?.close().catch(() => { });
     }
+    /** The payload of a job: a `usage` event's or a `model_usage` row's; null when it is gone. */
+    payloadOfJob(data) {
+        return data.usageId !== undefined
+            ? this.payloadOfUsage(data.usageId)
+            : this.payloadOf(data.conversationId, data.seq);
+    }
+    /**
+     * The payload of one `model_usage` row (spec B §5.4): purpose `embedding`, the calling extension,
+     * no conversation fields; `eventId` is the row id. Null when the row no longer exists.
+     */
+    async payloadOfUsage(id) {
+        const row = await this.db
+            .selectFrom("model_usage")
+            .select(["id", "org_id", "extension", "provider", "model", "input_tokens", "occurred_at"])
+            .where("id", "=", id)
+            .executeTakeFirst();
+        if (!row)
+            return null;
+        return {
+            eventId: row.id,
+            purpose: "embedding",
+            orgId: row.org_id,
+            extension: row.extension,
+            provider: row.provider,
+            model: row.model,
+            usage: {
+                inputTokens: row.input_tokens,
+                outputTokens: 0,
+                cacheReadTokens: 0,
+                cacheWriteTokens: 0,
+            },
+            occurredAt: new Date(row.occurred_at).toISOString(),
+        };
+    }
+    /** A `model_usage` job is done (delivered, or nothing left to deliver to): marks the row. */
+    async markReported(data) {
+        if (data.usageId === undefined)
+            return;
+        await this.db
+            .updateTable("model_usage")
+            .set({ reported_at: sql `now()` })
+            .where("id", "=", data.usageId)
+            .where("reported_at", "is", null)
+            .execute();
+    }
+    /** A `model_usage` job gave up after its last attempt: the sweep never offers the row again. */
+    async markFailed(data) {
+        if (data.usageId === undefined)
+            return;
+        try {
+            await this.db
+                .updateTable("model_usage")
+                .set({ report_failed_at: sql `now()` })
+                .where("id", "=", data.usageId)
+                .where("reported_at", "is", null)
+                .execute();
+        }
+        catch (err) {
+            this.log.warn("cannot mark a model usage report as given up", { usageId: data.usageId, err });
+        }
+    }
     /** The payload of one usage event, read from the log; null when the event no longer exists. */
     async payloadOf(conversationId, seq) {
         const row = await this.db
@@ -435,8 +500,7 @@ let UsageReporter = class UsageReporter {
         const allowed = stored === undefined ? undefined : [...stored, ...Object.keys(storedDropped)];
         const keep = [...dropped].filter(([p]) => allowed === undefined || allowed.includes(p));
         const out = {
-            conversationId: j.data.conversationId,
-            seq: j.data.seq,
+            ...keyOf(j.data),
             pending: narrowPending(allowed, next),
             ...(keep.length > 0 && { dropped: Object.fromEntries(keep) }),
         };
@@ -445,22 +509,24 @@ let UsageReporter = class UsageReporter {
     }
     /** One delivery job (the `@Processor` of {@link USAGE_REPORT_QUEUE} calls it). */
     async process(j, token) {
-        const { conversationId, seq } = j.data;
-        const payload = await this.payloadOf(conversationId, seq);
+        const payload = await this.payloadOfJob(j.data);
+        // conversation (or org) deleted meanwhile: nothing to report
         if (payload === null)
-            return; // conversation deleted meanwhile: nothing to report
+            return;
         const subscribers = await this.subscribers(payload.orgId);
         if (j.data.pending === undefined) {
             // first attempt: the targets come from deployment state, recorded so later attempts (on any
             // replica) deliver exactly the plugins that have not succeeded yet
             const targets = [...subscribers];
-            await j.updateData({ conversationId, seq, pending: targets });
+            await j.updateData({ ...keyOf(j.data), pending: targets });
             j.data.pending = targets;
         }
         // plugins the organization disabled meanwhile are dropped (not a failure)
         const targets = (j.data.pending ?? []).filter((p) => subscribers.has(p));
-        if (targets.length === 0)
+        if (targets.length === 0) {
+            await this.markReported(j.data);
             return;
+        }
         const byPlugin = new Map();
         for (const h of this.hooks.handlers("usage.report")) {
             byPlugin.set(h.plugin, [...(byPlugin.get(h.plugin) ?? []), h.handler]);
@@ -539,6 +605,8 @@ let UsageReporter = class UsageReporter {
         // m-1: pending = the dropped plugins only, so a manual retry reaches them and never the
         // plugins already served
         await this.writePending(j, [...allDropped.keys()], allDropped);
+        // delivered to every target still servable (a definite drop is final too): the row is done
+        await this.markReported(j.data);
         const traced = new Map([...allDropped].filter(([p]) => j.data.dropped?.[p] !== undefined));
         if (traced.size === 0)
             return;
@@ -649,9 +717,9 @@ let UsageReportModule = class UsageReportModule {
 };
 UsageReportModule = __decorate([
     Module({
-        imports: [ExtensionsModule, QueueModule.registerQueue(USAGE_REPORT_QUEUE)],
+        imports: [ExtensionsModule, UsageReportJobsModule],
         providers: [UsageReporter],
-        exports: [UsageReporter],
+        exports: [UsageReporter, UsageReportJobsModule],
     })
 ], UsageReportModule);
 export { UsageReportModule };

package/dist/skills/changes.controller.js

@@ -11,6 +11,7 @@ import { Controller, Delete, Get, HttpCode, Inject, Param, Post } from "@nestjs/
 import { z } from "zod";
 import { AgentsService } from "../agents/agents.service.js";
 import { CurrentPrincipal, patTokenId, requireUser, } from "../identity/principal.js";
+import { InboxNoticeParams } from "../inbox/inbox.schemas.js";
 import { InboxService } from "../inbox/inbox.service.js";
 import { createZodDto } from "../infra/validation/create-zod-dto.js";
 import { ZBody, ZParam } from "../infra/validation/zod-params.js";
@@ -25,7 +26,7 @@ const DecideBody = z
     .strict();
 class SkillChangeDecideBody extends createZodDto(DecideBody, "SkillChangeDecideBody") {
 }
-const NoticeParamsSchema = z.object({ id: z.string().min(1).max(100) });
+const NoticeParamsSchema = InboxNoticeParams;
 class NoticeParams extends createZodDto(NoticeParamsSchema, "InboxNoticeParams") {
 }
 /**

package/dist/skills/changes.service.d.ts

@@ -130,7 +130,7 @@ export declare class SkillChangesService {
      * agent → `skill.not_found`。同名的待处理改动一并取消（发起对话追加回退快照，提交后删草稿）。审计 `skill.deleted`。
      * 各对话下一次运行开始时目录里去掉它；之后同名可再写为新技能。
      */
-    deleteAgentSkill(orgId: string, agentId: string, skillId: string, accountId: string, actorTokenId?: string): Promise<void>;
+    deleteAgentSkill(orgId: string, agentId: string, skillId: string, accountId: string, actorTokenId?: string, auditDetail?: Record<string, unknown>): Promise<void>;
     /** The transaction of {@link write}. */
     private writeIn;
     /** The transaction of {@link decide}. */

package/dist/skills/changes.service.js

@@ -146,8 +146,8 @@ let SkillChangesService = class SkillChangesService {
      * agent → `skill.not_found`。同名的待处理改动一并取消（发起对话追加回退快照，提交后删草稿）。审计 `skill.deleted`。
      * 各对话下一次运行开始时目录里去掉它；之后同名可再写为新技能。
      */
-    async deleteAgentSkill(orgId, agentId, skillId, accountId, actorTokenId) {
-        const cancelled = await this.deleteAgentSkillIn(orgId, agentId, skillId, accountId, actorTokenId);
+    async deleteAgentSkill(orgId, agentId, skillId, accountId, actorTokenId, auditDetail) {
+        const cancelled = await this.deleteAgentSkillIn(orgId, agentId, skillId, accountId, actorTokenId, auditDetail);
         await this.finishCancel(orgId, cancelled);
     }
     /** The transaction of {@link write}. */
@@ -401,7 +401,7 @@ let SkillChangesService = class SkillChangesService {
         return { updated, revertSeq };
     }
     /** The transaction of {@link deleteAgentSkill}. */
-    async deleteAgentSkillIn(orgId, agentId, skillId, accountId, actorTokenId) {
+    async deleteAgentSkillIn(orgId, agentId, skillId, accountId, actorTokenId, auditDetail) {
         await this.keyShareOrg(orgId);
         const agent = await this.db
             .selectFrom("agents")
@@ -471,7 +471,7 @@ let SkillChangesService = class SkillChangesService {
             orgId,
             action: "skill.deleted",
             target: skillId,
-            detail: { name: r.name, agentId },
+            detail: { name: r.name, agentId, ...auditDetail },
         });
         return out;
     }

package/dist/skills/invocable.controller.d.ts

@@ -1,4 +1,4 @@
-import { z } from "zod";
+import type { z } from "zod";
 import { type Principal } from "../identity/principal.js";
 import { type OrgContext } from "../orgs/org.guard.js";
 import { type InvocableSkill, SkillInvoker } from "./invoke.js";

package/dist/skills/invocable.controller.js

@@ -8,13 +8,13 @@ var __param = (this && this.__param) || function (paramIndex, decorator) {
     return function (target, key) { decorator(target, key, paramIndex); }
 };
 import { Controller, Get, Header, Inject, Param } from "@nestjs/common";
-import { z } from "zod";
 import { CurrentPrincipal, requireUser } from "../identity/principal.js";
 import { createZodDto } from "../infra/validation/create-zod-dto.js";
 import { ZQuery } from "../infra/validation/zod-params.js";
 import { CurrentOrg, OrgAction } from "../orgs/org.guard.js";
 import { SkillInvoker } from "./invoke.js";
-const ListQuery = z.object({ conversationId: z.string().min(1).max(100).optional() }).strict();
+import { InvocableSkillsQuerySchema } from "./skills.schemas.js";
+const ListQuery = InvocableSkillsQuerySchema;
 class InvocableSkillsQuery extends createZodDto(ListQuery, "InvocableSkillsQuery") {
 }
 /**

package/dist/skills/invoke.d.ts

@@ -1,5 +1,5 @@
 import { AgentLookup } from "../agents/agent-lookup.js";
-import type { AgentDefinition } from "../agents/definition.js";
+import { type AgentDefinition } from "../agents/definition.js";
 import type { EventPayload } from "../conversations/events.js";
 import type { KernelSchemaDb } from "../db/kernel-schema.js";
 import { ApiError } from "../errors.js";
@@ -128,7 +128,7 @@ export declare class SkillInvoker {
         conversationId: string;
         skill: InvocationRecord;
     }): Promise<{
-        task: (child: Pick<AgentDefinition, "tools">) => string;
+        task: (child: Pick<AgentDefinition, "disabledTools" | "subagentTools">) => string;
         warning?: string;
     }>;
     /** Reads and parses the version's SKILL.md (checked against the manifest), returns the body. */

package/dist/skills/invoke.js

@@ -10,6 +10,7 @@ var __param = (this && this.__param) || function (paramIndex, decorator) {
 import { escapeSkillInvocationTags, hasShellInjection, parseSkillMd, renderSkillBody, renderSkillInvocation, SKILL_ENTRY_FILE, SKILL_INVOCATION_LIMITS, skillDigest, } from "@capybara-hq/plugin-sdk";
 import { Inject, Injectable } from "@nestjs/common";
 import { AgentLookup } from "../agents/agent-lookup.js";
+import { builtinDisabled } from "../agents/definition.js";
 import { ApiError } from "../errors.js";
 import { KernelDb } from "../infra/database/kernel-db.js";
 import { KERNEL_LOGGER } from "../infra/tokens.js";
@@ -289,7 +290,13 @@ SkillInvoker = __decorate([
     __param(3, Inject(KERNEL_LOGGER))
 ], SkillInvoker);
 export { SkillInvoker };
-const hasBuiltin = (agent, name) => (agent.tools ?? []).some((t) => t.kind === "builtin" && t.name === name);
+/**
+ * Does the definition leave builtin `name` on (tools default-on spec §4): not turned off and not
+ * removed by a sub-agent's key filter. Whether it can run now (a sandbox) is not checked.
+ */
+const hasBuiltin = (agent, name) => !builtinDisabled(agent.disabledTools, name) &&
+    !(agent.subagentTools?.deny ?? []).includes(name) &&
+    (agent.subagentTools?.allow === undefined || agent.subagentTools.allow.includes(name));
 /** The skill's own body over the rendered limit: a 400 on `skill` naming the skill. */
 function tooLarge(name, render) {
     try {

package/dist/skills/skills.controller.d.ts

@@ -3,21 +3,12 @@ import { OwnedItems, type OwnedSkillDeletePreview } from "../catalog/owned-items
 import { type CreatedAttachment } from "../conversations/attachments.service.js";
 import { type Principal } from "../identity/principal.js";
 import { type OrgContext } from "../orgs/org.guard.js";
+import { SkillCreateBody, SkillIdParams } from "./skills.schemas.js";
 import { type SkillDetail, type SkillSummary, SkillsService, type UploadedSkill } from "./skills.service.js";
 declare const UploadBody: z.ZodObject<{
     name: z.ZodString;
     size: z.ZodNumber;
 }, z.core.$strict>;
-declare const CreateBody: z.ZodObject<{
-    uploadId: z.ZodOptional<z.ZodString>;
-    name: z.ZodOptional<z.ZodString & z.ZodType<string, string, z.core.$ZodTypeInternals<string, string>>>;
-    description: z.ZodOptional<z.ZodString>;
-    body: z.ZodOptional<z.ZodString>;
-    shareable: z.ZodOptional<z.ZodBoolean>;
-}, z.core.$strict>;
-declare const IdParams: z.ZodObject<{
-    id: z.ZodString;
-}, z.core.$strip>;
 declare const ShareableBody: z.ZodObject<{
     shareable: z.ZodBoolean;
 }, z.core.$strict>;
@@ -46,7 +37,7 @@ export declare class SkillsController {
     /** The org's own items: 可共享 and the delete of a promoted skill (rulings P3-3, P3-19). */
     owned: OwnedItems);
     createUpload(principal: Principal, org: OrgContext, body: z.infer<typeof UploadBody>): Promise<CreatedAttachment>;
-    create(principal: Principal, org: OrgContext, body: z.infer<typeof CreateBody>): Promise<UploadedSkill>;
+    create(principal: Principal, org: OrgContext, body: z.infer<typeof SkillCreateBody>): Promise<UploadedSkill>;
     list(principal: Principal, org: OrgContext): Promise<{
         skills: SkillSummary[];
     }>;
@@ -56,7 +47,7 @@ export declare class SkillsController {
      * skill of the org's own (P3-6: an agent's skill or a copy of another owner's platform skill ->
      * 409 `catalog.not_owned`); one it promoted writes its platform row too (ruling P3-2).
      */
-    setShareable(principal: Principal, org: OrgContext, params: z.infer<typeof IdParams>, body: z.infer<typeof ShareableBody>): Promise<{
+    setShareable(principal: Principal, org: OrgContext, params: z.infer<typeof SkillIdParams>, body: z.infer<typeof ShareableBody>): Promise<{
         id: string;
         shareable: boolean;
     }>;
@@ -65,7 +56,7 @@ export declare class SkillsController {
      * `transferred` when it was shared and another org uses it (`orgs`), else `removed`; `agents`
      * the org's agents that lose it.
      */
-    deletePreview(principal: Principal, org: OrgContext, params: z.infer<typeof IdParams>): Promise<OwnedSkillDeletePreview>;
+    deletePreview(principal: Principal, org: OrgContext, params: z.infer<typeof SkillIdParams>): Promise<OwnedSkillDeletePreview>;
     /**
      * Soft-deletes the skill; one the org shared that another org uses is transferred to the
      * platform first (P3-19, platform notice `ownership_transferred`). 204.

package/dist/skills/skills.controller.js

@@ -7,7 +7,7 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
 var __param = (this && this.__param) || function (paramIndex, decorator) {
     return function (target, key) { decorator(target, key, paramIndex); }
 };
-import { hasControlChars, isSkillName, MEDIA_NAME_MAX_CHARS, SKILL_LIMITS, } from "@capybara-hq/plugin-sdk";
+import { hasControlChars, MEDIA_NAME_MAX_CHARS } from "@capybara-hq/plugin-sdk";
 import { Controller, Delete, Get, HttpCode, Inject, Param, Post, Put } from "@nestjs/common";
 import { z } from "zod";
 import { OwnedItems } from "../catalog/owned-items.js";
@@ -16,7 +16,7 @@ import { CurrentPrincipal, patTokenId, requireUser, } from "../identity/principa
 import { createZodDto } from "../infra/validation/create-zod-dto.js";
 import { ZBody, ZParam } from "../infra/validation/zod-params.js";
 import { CurrentOrg, OrgAction } from "../orgs/org.guard.js";
-import { SKILL_WRITE_MAX_BYTES } from "../tools/builtins/skill-write.js";
+import { SkillCreateBody, SkillIdParams, SkillShareableSchema } from "./skills.schemas.js";
 import { SkillsService, } from "./skills.service.js";
 const UploadBody = z
     .object({
@@ -28,28 +28,12 @@ const UploadBody = z
     size: z.number().int().min(1).max(SKILL_PACKAGE_UPLOAD_MAX_BYTES),
 })
     .strict();
-const CreateBody = z
-    .object({
-    uploadId: z.string().min(1).max(100).optional(),
-    name: z
-        .string()
-        .refine(isSkillName, "name must be 1-64 lowercase letters, digits and single hyphens")
-        .optional(),
-    description: z.string().min(1).max(SKILL_LIMITS.descriptionMaxChars).optional(),
-    body: z.string().max(SKILL_WRITE_MAX_BYTES).optional(),
-    shareable: z.boolean().optional(),
-})
-    .strict()
-    .refine((v) => v.uploadId !== undefined
-    ? v.name === undefined && v.description === undefined && v.body === undefined
-    : v.name !== undefined && v.description !== undefined && v.body !== undefined, "send either { uploadId } or { name, description, body }");
 class SkillUploadBody extends createZodDto(UploadBody, "SkillUploadBody") {
 }
-class SkillCreateBody extends createZodDto(CreateBody, "SkillCreateBody") {
+class SkillCreateBodyDto extends createZodDto(SkillCreateBody, "SkillCreateBody") {
 }
-const IdParams = z.object({ id: z.string().min(1).max(100) });
-const ShareableBody = z.object({ shareable: z.boolean() }).strict();
-class SkillIdParams extends createZodDto(IdParams, "SkillIdParams") {
+const ShareableBody = SkillShareableSchema;
+class SkillIdParamsDto extends createZodDto(SkillIdParams, "SkillIdParams") {
 }
 class SkillShareableBody extends createZodDto(ShareableBody, "SkillShareableBody") {
 }
@@ -147,7 +131,7 @@ __decorate([
     OrgAction("skills.manage"),
     __param(0, CurrentPrincipal()),
     __param(1, CurrentOrg()),
-    __param(2, ZBody(SkillCreateBody))
+    __param(2, ZBody(SkillCreateBodyDto))
 ], SkillsController.prototype, "create", null);
 __decorate([
     Get(),
@@ -167,7 +151,7 @@ __decorate([
     OrgAction("skills.manage"),
     __param(0, CurrentPrincipal()),
     __param(1, CurrentOrg()),
-    __param(2, ZParam(SkillIdParams)),
+    __param(2, ZParam(SkillIdParamsDto)),
     __param(3, ZBody(SkillShareableBody))
 ], SkillsController.prototype, "setShareable", null);
 __decorate([
@@ -175,7 +159,7 @@ __decorate([
     OrgAction("skills.manage"),
     __param(0, CurrentPrincipal()),
     __param(1, CurrentOrg()),
-    __param(2, ZParam(SkillIdParams))
+    __param(2, ZParam(SkillIdParamsDto))
 ], SkillsController.prototype, "deletePreview", null);
 __decorate([
     Delete(":id"),