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

package/dist/environments/legacy-cleanup.job.js

@@ -0,0 +1,141 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+import { Inject, Injectable } from "@nestjs/common";
+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 { LockedInterval } from "../infra/schedule/locked-interval.js";
+import { KERNEL_LOGGER } from "../infra/tokens.js";
+import { SandboxProviders } from "../sandbox/providers.js";
+/** The job's name (`@LockedInterval`, run lock `cron:environments-legacy-cleanup`). */
+export const LEGACY_CLEANUP_JOB = "environments-legacy-cleanup";
+/** Every 5 minutes, once per tick across replicas. */
+const PERIOD_MS = 5 * 60_000;
+/** Rows handled per tick. */
+const BATCH = 50;
+/** The time limit of one provider call. */
+const CALL_TIMEOUT_MS = 120_000;
+/**
+ * The cleanup of the per-conversation sandboxes of before environments (spec
+ * 2026-11-07-environments-design §4.2 item 9): for up to {@link BATCH} rows of the legacy
+ * `sandboxes` table per tick, the row's provider destroys the instance and the file system named
+ * `cap-<conversationId>` (`destroyByName`, `destroyFileSystemByName`; also the instance of the
+ * provider it replaced, `prev_provider`, when that one is loaded), then the row is deleted. No
+ * lease is taken: nothing holds a legacy row after the upgrade. A row whose provider is not loaded
+ * is kept (warned once per hour: on the tick in the first {@link PERIOD_MS} of each hour); a row
+ * whose destruction failed is retried at a later tick, after the others (`sweep_failed_at`). With
+ * no rows left a tick is one `SELECT … LIMIT 1`. The table is dropped by a later migration.
+ */
+let LegacySandboxCleanupJob = class LegacySandboxCleanupJob {
+    db;
+    providers;
+    config;
+    lockService;
+    log;
+    constructor(db, providers, config, lockService, log) {
+        this.db = db;
+        this.providers = providers;
+        this.config = config;
+        this.lockService = lockService;
+        this.log = log;
+    }
+    async tick(signal) {
+        const res = await this.runOnce(new Date(), signal);
+        if (res.destroyed > 0)
+            this.log.info("legacy sandboxes destroyed", { ...res });
+    }
+    /** One run (see the class); `signal` (the stop, or a lost run lock) is read between rows. */
+    async runOnce(now = new Date(), signal) {
+        const any = await this.db
+            .selectFrom("sandboxes")
+            .select("conversation_id")
+            .limit(1)
+            .executeTakeFirst();
+        if (any === undefined)
+            return { destroyed: 0, kept: 0 };
+        const byProvider = await this.db
+            .selectFrom("sandboxes")
+            .select(["provider", (eb) => eb.fn.countAll().as("n")])
+            .groupBy("provider")
+            .execute();
+        const loaded = byProvider.filter((p) => this.providers.lookup(p.provider) !== undefined);
+        const unloaded = byProvider.filter((p) => this.providers.lookup(p.provider) === undefined);
+        const kept = unloaded.reduce((sum, p) => sum + Number(p.n), 0);
+        if (unloaded.length > 0 && now.getTime() % 3_600_000 < PERIOD_MS) {
+            this.log.warn("legacy sandboxes kept: their provider is not loaded", {
+                providers: unloaded.map((p) => p.provider),
+                count: kept,
+            });
+        }
+        if (loaded.length === 0)
+            return { destroyed: 0, kept };
+        const rows = await this.db
+            .selectFrom("sandboxes")
+            .select(["conversation_id", "provider", "prev_provider"])
+            .where("provider", "in", loaded.map((p) => p.provider))
+            .orderBy("sweep_failed_at", (o) => o.asc().nullsFirst())
+            .orderBy("conversation_id")
+            .limit(BATCH)
+            .execute();
+        let destroyed = 0;
+        for (const row of rows) {
+            if (signal?.aborted)
+                break;
+            const name = `cap-${row.conversation_id}`;
+            const impl = this.providers.lookup(row.provider);
+            if (impl === undefined)
+                continue; // unloaded since the query: kept for a later tick
+            const callSignal = () => signal
+                ? AbortSignal.any([signal, AbortSignal.timeout(CALL_TIMEOUT_MS)])
+                : AbortSignal.timeout(CALL_TIMEOUT_MS);
+            try {
+                await impl.destroyByName(name, callSignal());
+                await impl.destroyFileSystemByName(name, callSignal());
+                if (row.prev_provider !== null && row.prev_provider !== row.provider) {
+                    const prev = this.providers.lookup(row.prev_provider);
+                    if (prev !== undefined)
+                        await prev.destroyByName(name, callSignal());
+                    else {
+                        this.log.warn("legacy sandbox of a replaced provider left: provider not loaded", {
+                            name,
+                            provider: row.prev_provider,
+                        });
+                    }
+                }
+                await this.db
+                    .deleteFrom("sandboxes")
+                    .where("conversation_id", "=", row.conversation_id)
+                    .execute();
+                destroyed++;
+            }
+            catch (err) {
+                this.log.warn("cannot destroy legacy sandbox; will retry", { name, err });
+                await this.db
+                    .updateTable("sandboxes")
+                    .set({ sweep_failed_at: now })
+                    .where("conversation_id", "=", row.conversation_id)
+                    .execute();
+            }
+        }
+        return { destroyed, kept };
+    }
+};
+__decorate([
+    LockedInterval(LEGACY_CLEANUP_JOB, () => PERIOD_MS, { ttl: CALL_TIMEOUT_MS })
+], LegacySandboxCleanupJob.prototype, "tick", null);
+LegacySandboxCleanupJob = __decorate([
+    Injectable(),
+    __param(0, Inject(KernelDb)),
+    __param(1, Inject(SandboxProviders)),
+    __param(2, Inject(KernelConfigService)),
+    __param(3, Inject(LockService)),
+    __param(4, Inject(KERNEL_LOGGER))
+], LegacySandboxCleanupJob);
+export { LegacySandboxCleanupJob };

package/dist/errors.d.ts

@@ -14,7 +14,7 @@ export declare const ERROR_CODES: {
     readonly rate_limited: 429;
     readonly "account.login_taken": 409;
     readonly "account.not_found": 404;
-    readonly "account.last_enterprise_admin": 409;
+    readonly "account.last_super_admin": 409;
     readonly "auth.account_disabled": 403;
     readonly "auth.required": 401;
     readonly "auth.token_expired": 401;
@@ -39,10 +39,15 @@ export declare const ERROR_CODES: {
     readonly "invitation.expired": 410;
     readonly "invitation.used": 409;
     readonly "extension.not_found": 404;
+    /** The extension registers no tool of that name (org tool switches, layering spec A §7). */
+    readonly "extension.tool_not_found": 404;
     readonly "extension.unavailable": 503;
     readonly "extension.no_org_config": 400;
     readonly "extension.config_invalid": 400;
     readonly "extension.config_readonly": 409;
+    readonly "extension.field_not_overridable": 400;
+    readonly "extension.no_org_override": 404;
+    readonly "extension.needs_config": 409;
     readonly "extension.dependency_missing": 409;
     readonly "extension.has_dependents": 409;
     readonly "extension.not_enabled": 409;
@@ -72,12 +77,44 @@ export declare const ERROR_CODES: {
     readonly "catalog.dependency_cycle": 409;
     readonly "catalog.version_exists": 409;
     readonly "catalog.item_not_found": 404;
+    /** An org-owned item its owner has not made shareable cannot be shown or associated (P3-16). */
+    readonly "catalog.not_shareable": 409;
+    /** The owner org cannot be removed from its own item's list (P3-17). */
+    readonly "catalog.owner_required": 409;
+    /**
+     * Only the org's own rows can be made shareable: not an agent's skill, not a copy linked to a
+     * platform item another owner has (P3-6).
+     */
+    readonly "catalog.not_owned": 409;
+    /** The item (or the version asked for) waits for the super admin's confirmation (P3-9). */
+    readonly "catalog.item_pending": 409;
+    /** A super admin confirmation raced the item's removal (P3-21). */
+    readonly "catalog.item_removed": 409;
+    /** What deleting an org's own plugin does changed since its preview (P3-19). */
+    readonly "catalog.preview_stale": 409;
     readonly "catalog.name_conflict": 409;
     readonly "directory.not_configured": 409;
     readonly "catalog.item_disabled": 403;
+    readonly "plugin.disabled": 409;
+    readonly "plugin.scope_locked": 409;
+    readonly "plugin.switch_stale": 409;
+    readonly "plugin.builtin": 409;
+    readonly "plugin.scope_stale": 409;
+    readonly "component.not_found": 404;
+    readonly "component.version_stale": 409;
+    /** A platform component offered to the org but off there (one more connector from a template). */
+    readonly "component.off": 409;
     readonly "catalog.approval_required": 403;
     readonly "catalog.request_not_found": 404;
+    /** No open org notice with that id for an admin of the org (inbox). */
+    readonly "inbox.notice_not_found": 404;
     readonly "catalog.request_decided": 409;
+    /** A pending request of the same kind for the same item or entry exists (spec §5.1 rule 5). */
+    readonly "catalog.request_pending": 409;
+    /** The item is not in the state the request kind asks to change (already offered, on, ...). */
+    readonly "catalog.request_invalid": 409;
+    /** The deployment setting `orgMarketplaceBrowse` is off: no marketplace requests. */
+    readonly "catalog.marketplace_browse_disabled": 409;
     readonly "catalog.custom_disabled": 403;
     readonly "catalog.not_deployed": 409;
     readonly "catalog.icon_not_found": 404;
@@ -89,6 +126,7 @@ export declare const ERROR_CODES: {
     readonly "marketplace.private_address": 422;
     readonly "marketplace.redirect": 422;
     readonly "marketplace.incompatible": 409;
+    readonly "marketplace.entry_deprecated": 409;
     readonly "marketplace.package_mismatch": 409;
     readonly "marketplace.builtin": 409;
     readonly "marketplace.git_failed": 502;
@@ -97,6 +135,10 @@ export declare const ERROR_CODES: {
     readonly "marketplace.host_not_allowed": 403;
     readonly "marketplace.path_unsupported": 422;
     readonly "plugin.review_stale": 409;
+    readonly "plugin.name_taken": 409;
+    readonly "plugin.name_reserved": 409;
+    readonly "plugin.dependency_unavailable": 409;
+    readonly "plugin.extension_upload_pending": 501;
     readonly "plugin.staging_not_found": 404;
     readonly "plugin.install_failed": 502;
     readonly "plugin.install_not_found": 404;
@@ -122,6 +164,27 @@ export declare const ERROR_CODES: {
     readonly "agent.pinned_invalid": 400;
     /** `subagents` of an agent definition is refused (details: `{ reason, path, value? }`). */
     readonly "agent.subagents_invalid": 400;
+    /** Creating from a template with a visibility other than `private` without `agents.manage`. */
+    readonly "agent.visibility_forbidden": 403;
+    /** Creating from a template: the template or the org changed since the preview (P4-3). */
+    readonly "agent.template_preview_stale": 409;
+    /** The agent has no pending connector with that key (ruling P4-6). */
+    readonly "agent.pending_connector_not_found": 404;
+    /**
+     * The connector does not fit the pending entry (ruling P4-T6-1; details `[{ reason }]`:
+     * `template` another or no connector template, `protocol` another kind, `tools` none of the
+     * entry's tools, `not_synced` no tool snapshot yet: an OAuth connector to authorize first).
+     */
+    readonly "agent.pending_connector_mismatch": 400;
+    /** Requesting connector setup for an agent with no pending connectors (ruling P4-T6-7). */
+    readonly "agent.no_pending_connectors": 409;
+    /**
+     * An org template's bare name is a type the org can already use (spec §5 rule 10, ruling
+     * P4-9; details `[{ owner, templateId }]`, `owner` as `plugin.name_taken`'s).
+     */
+    readonly "agent_template.name_taken": 409;
+    /** An org template was saved since the editor read it (`expectedVersion` is stale, P4-12). */
+    readonly "agent_template.version_conflict": 409;
     readonly "conversation.not_found": 404;
     readonly "conversation.output_not_found": 404;
     readonly "conversation.artifact_not_found": 404;
@@ -134,18 +197,22 @@ export declare const ERROR_CODES: {
     /** A sub-agent's conversation takes no messages from people (sub-agents spec §6.1). */
     readonly "conversation.read_only": 409;
     readonly "run.not_active": 409;
+    /** A run that is not one of the conversation's (the live draft route, spec 2026-11-07 §3.2). */
+    readonly "run.not_found": 404;
     /** A background task that is not in this conversation (or its sub-agents), or does not exist. */
     readonly "background_task.not_found": 404;
     /** The task's output cannot be read now (its sandbox is not running and no finish recorded it). */
     readonly "background_task.output_unavailable": 409;
     readonly "connector.not_found": 404;
     readonly "connector.slug_taken": 409;
+    readonly "connector.kind_unavailable": 409;
     readonly "connector.connect_failed": 502;
     readonly "connector.tool_not_found": 404;
     readonly "connector.tool_not_pending": 409;
     readonly "connector.resources_disabled": 409;
     readonly "approval.not_found": 404;
     readonly "approval.already_decided": 409;
+    readonly "approval.scope_not_allowed": 409;
     readonly "question.not_found": 404;
     readonly "question.already_answered": 409;
     readonly "tool_output.not_found": 404;
@@ -172,7 +239,18 @@ export declare const ERROR_CODES: {
     readonly "attachment.too_many_pending": 429;
     readonly "sandbox.unavailable": 503;
     readonly "sandbox.busy": 409;
-    readonly "sandbox.not_found": 404;
+    /** The environment is missing, deleted, or not the caller's (never 403, so ids cannot be probed). */
+    readonly "environment.not_found": 404;
+    /** The environment's file system is gone at the provider; reset its files to start empty. */
+    readonly "environment.files_lost": 409;
+    /** The caller may see the environment but not use it (project environments, later phases). */
+    readonly "environment.forbidden": 403;
+    /** The environment's provider is not the deployment's current one, or there is none. */
+    readonly "environment.unavailable": 503;
+    /** The person already has a live environment with this name (case-insensitive). */
+    readonly "environment.name_taken": 409;
+    /** The person already has `environments.maxPersonal` live personal environments. */
+    readonly "environment.limit_reached": 409;
     readonly "skill.not_found": 404;
     /** Also a skill neither the model nor a person could use (phase D: both invocation flags off). */
     readonly "skill.invalid_package": 400;
@@ -181,6 +259,8 @@ export declare const ERROR_CODES: {
      * (`details: [{ reason: "not_found" }]`) or is hidden from the menu (`not_user_invocable`).
      */
     readonly "skill.not_invocable": 400;
+    /** Creating a skill from text (P3-24, F18): an org-level skill with this name already exists in the org. */
+    readonly "skill.name_exists": 409;
     readonly "skill_change.not_found": 404;
     readonly "skill_change.not_owner": 403;
     readonly "skill_change.already_decided": 409;

package/dist/errors.js

@@ -14,7 +14,7 @@ export const ERROR_CODES = {
     rate_limited: 429,
     "account.login_taken": 409,
     "account.not_found": 404,
-    "account.last_enterprise_admin": 409,
+    "account.last_super_admin": 409,
     "auth.account_disabled": 403,
     "auth.required": 401,
     "auth.token_expired": 401,
@@ -39,10 +39,15 @@ export const ERROR_CODES = {
     "invitation.expired": 410,
     "invitation.used": 409,
     "extension.not_found": 404,
+    /** The extension registers no tool of that name (org tool switches, layering spec A §7). */
+    "extension.tool_not_found": 404,
     "extension.unavailable": 503,
     "extension.no_org_config": 400,
     "extension.config_invalid": 400,
     "extension.config_readonly": 409,
+    "extension.field_not_overridable": 400,
+    "extension.no_org_override": 404,
+    "extension.needs_config": 409,
     "extension.dependency_missing": 409,
     "extension.has_dependents": 409,
     "extension.not_enabled": 409,
@@ -72,12 +77,44 @@ export const ERROR_CODES = {
     "catalog.dependency_cycle": 409,
     "catalog.version_exists": 409,
     "catalog.item_not_found": 404,
+    /** An org-owned item its owner has not made shareable cannot be shown or associated (P3-16). */
+    "catalog.not_shareable": 409,
+    /** The owner org cannot be removed from its own item's list (P3-17). */
+    "catalog.owner_required": 409,
+    /**
+     * Only the org's own rows can be made shareable: not an agent's skill, not a copy linked to a
+     * platform item another owner has (P3-6).
+     */
+    "catalog.not_owned": 409,
+    /** The item (or the version asked for) waits for the super admin's confirmation (P3-9). */
+    "catalog.item_pending": 409,
+    /** A super admin confirmation raced the item's removal (P3-21). */
+    "catalog.item_removed": 409,
+    /** What deleting an org's own plugin does changed since its preview (P3-19). */
+    "catalog.preview_stale": 409,
     "catalog.name_conflict": 409,
     "directory.not_configured": 409,
     "catalog.item_disabled": 403,
+    "plugin.disabled": 409,
+    "plugin.scope_locked": 409,
+    "plugin.switch_stale": 409,
+    "plugin.builtin": 409,
+    "plugin.scope_stale": 409,
+    "component.not_found": 404,
+    "component.version_stale": 409,
+    /** A platform component offered to the org but off there (one more connector from a template). */
+    "component.off": 409,
     "catalog.approval_required": 403,
     "catalog.request_not_found": 404,
+    /** No open org notice with that id for an admin of the org (inbox). */
+    "inbox.notice_not_found": 404,
     "catalog.request_decided": 409,
+    /** A pending request of the same kind for the same item or entry exists (spec §5.1 rule 5). */
+    "catalog.request_pending": 409,
+    /** The item is not in the state the request kind asks to change (already offered, on, ...). */
+    "catalog.request_invalid": 409,
+    /** The deployment setting `orgMarketplaceBrowse` is off: no marketplace requests. */
+    "catalog.marketplace_browse_disabled": 409,
     "catalog.custom_disabled": 403,
     "catalog.not_deployed": 409,
     "catalog.icon_not_found": 404,
@@ -89,6 +126,7 @@ export const ERROR_CODES = {
     "marketplace.private_address": 422,
     "marketplace.redirect": 422,
     "marketplace.incompatible": 409,
+    "marketplace.entry_deprecated": 409,
     "marketplace.package_mismatch": 409,
     "marketplace.builtin": 409,
     "marketplace.git_failed": 502,
@@ -97,6 +135,10 @@ export const ERROR_CODES = {
     "marketplace.host_not_allowed": 403,
     "marketplace.path_unsupported": 422,
     "plugin.review_stale": 409,
+    "plugin.name_taken": 409,
+    "plugin.name_reserved": 409,
+    "plugin.dependency_unavailable": 409,
+    "plugin.extension_upload_pending": 501,
     "plugin.staging_not_found": 404,
     "plugin.install_failed": 502,
     "plugin.install_not_found": 404,
@@ -122,6 +164,27 @@ export const ERROR_CODES = {
     "agent.pinned_invalid": 400,
     /** `subagents` of an agent definition is refused (details: `{ reason, path, value? }`). */
     "agent.subagents_invalid": 400,
+    /** Creating from a template with a visibility other than `private` without `agents.manage`. */
+    "agent.visibility_forbidden": 403,
+    /** Creating from a template: the template or the org changed since the preview (P4-3). */
+    "agent.template_preview_stale": 409,
+    /** The agent has no pending connector with that key (ruling P4-6). */
+    "agent.pending_connector_not_found": 404,
+    /**
+     * The connector does not fit the pending entry (ruling P4-T6-1; details `[{ reason }]`:
+     * `template` another or no connector template, `protocol` another kind, `tools` none of the
+     * entry's tools, `not_synced` no tool snapshot yet: an OAuth connector to authorize first).
+     */
+    "agent.pending_connector_mismatch": 400,
+    /** Requesting connector setup for an agent with no pending connectors (ruling P4-T6-7). */
+    "agent.no_pending_connectors": 409,
+    /**
+     * An org template's bare name is a type the org can already use (spec §5 rule 10, ruling
+     * P4-9; details `[{ owner, templateId }]`, `owner` as `plugin.name_taken`'s).
+     */
+    "agent_template.name_taken": 409,
+    /** An org template was saved since the editor read it (`expectedVersion` is stale, P4-12). */
+    "agent_template.version_conflict": 409,
     "conversation.not_found": 404,
     "conversation.output_not_found": 404,
     "conversation.artifact_not_found": 404,
@@ -134,18 +197,22 @@ export const ERROR_CODES = {
     /** A sub-agent's conversation takes no messages from people (sub-agents spec §6.1). */
     "conversation.read_only": 409,
     "run.not_active": 409,
+    /** A run that is not one of the conversation's (the live draft route, spec 2026-11-07 §3.2). */
+    "run.not_found": 404,
     /** A background task that is not in this conversation (or its sub-agents), or does not exist. */
     "background_task.not_found": 404,
     /** The task's output cannot be read now (its sandbox is not running and no finish recorded it). */
     "background_task.output_unavailable": 409,
     "connector.not_found": 404,
     "connector.slug_taken": 409,
+    "connector.kind_unavailable": 409,
     "connector.connect_failed": 502,
     "connector.tool_not_found": 404,
     "connector.tool_not_pending": 409,
     "connector.resources_disabled": 409,
     "approval.not_found": 404,
     "approval.already_decided": 409,
+    "approval.scope_not_allowed": 409,
     "question.not_found": 404,
     "question.already_answered": 409,
     "tool_output.not_found": 404,
@@ -172,7 +239,18 @@ export const ERROR_CODES = {
     "attachment.too_many_pending": 429,
     "sandbox.unavailable": 503,
     "sandbox.busy": 409,
-    "sandbox.not_found": 404,
+    /** The environment is missing, deleted, or not the caller's (never 403, so ids cannot be probed). */
+    "environment.not_found": 404,
+    /** The environment's file system is gone at the provider; reset its files to start empty. */
+    "environment.files_lost": 409,
+    /** The caller may see the environment but not use it (project environments, later phases). */
+    "environment.forbidden": 403,
+    /** The environment's provider is not the deployment's current one, or there is none. */
+    "environment.unavailable": 503,
+    /** The person already has a live environment with this name (case-insensitive). */
+    "environment.name_taken": 409,
+    /** The person already has `environments.maxPersonal` live personal environments. */
+    "environment.limit_reached": 409,
     "skill.not_found": 404,
     /** Also a skill neither the model nor a person could use (phase D: both invocation flags off). */
     "skill.invalid_package": 400,
@@ -181,6 +259,8 @@ export const ERROR_CODES = {
      * (`details: [{ reason: "not_found" }]`) or is hidden from the menu (`not_user_invocable`).
      */
     "skill.not_invocable": 400,
+    /** Creating a skill from text (P3-24, F18): an org-level skill with this name already exists in the org. */
+    "skill.name_exists": 409,
     "skill_change.not_found": 404,
     "skill_change.not_owner": 403,
     "skill_change.already_decided": 409,

package/dist/evals/reconstruct.d.ts

@@ -63,10 +63,7 @@ export interface ReconstructOptions {
      * eval worker reads the current one). Another version than the logged one is a candidate change
      * (`subagent_changed`).
      */
-    subagentTemplate?: {
-        id: string;
-        version: number;
-    };
+    subagentTemplate?: SubagentTemplateRef;
     /**
      * A child case under another agent version (`agentVersion` differs): that version's own
      * definition, compared with the logged sub-agent for `subagent_changed` (the candidate
@@ -87,6 +84,16 @@ export declare function reconstructRequest(s: CaseSnapshot, modelCallSeq: number
 type SubagentStarted = EventPayload<"subagent_started">;
 /** The `subagent_started` of a sub-agent's (child) log, or undefined for any other conversation. */
 export declare function subagentStartedOf(events: readonly ConversationEvent[]): SubagentStarted | undefined;
+/**
+ * A plugin template child's template as a new dispatch would use it: the selected id, the version
+ * and the platform template whose content it is (absent: the org's own template; plugin scope
+ * phase 2, a linked copy shares its id with both sources, whose version numbers may collide).
+ */
+export interface SubagentTemplateRef {
+    id: string;
+    version: number;
+    platformTemplateId?: string;
+}
 /**
  * Does a candidate change what a sub-agent (child) case would run (`subagent_changed`, spec
  * §15.1)? Pure, from the snapshot alone, comparing the model-visible parts of the effective
@@ -101,7 +108,12 @@ export declare function subagentStartedOf(events: readonly ConversationEvent[]):
  *   parent version (its own version is {@link ReconstructOptions.subagentTemplate}). Template
  *   narrowing that needs the database (inline and plugin tool allowlists, skill names) is not
  *   recomputed: those compare instructions only.
- * Models and params are not part of it: they are candidate axes of their own.
+ * Models and params are not part of it: they are candidate axes of their own. Neither is the
+ * candidate's `subagents` block as the child's own roster (allowlist, templates, limits; only a
+ * template child's entry in its parent's roster counts, `parentSide`) nor whether it offers `Agent`:
+ * whether a child has `Agent` follows its depth (`keepAgent` comes only from the logged child), and
+ * what a nesting child dispatches is recorded as its `Agent` results, which replay reuses (agent
+ * map spec §4.1, §8). A roster-only candidate therefore reports no `subagent_changed`.
  */
 export declare function subagentChanged(started: SubagentStarted, logged: AgentDefinition, candidate: AgentDefinition, sameVersion: boolean, 
 /** The parent's definition at the case's version (the snapshot's), for template children. */
@@ -115,10 +127,7 @@ export declare function subagentCaseChanged(s: CaseSnapshot, c: {
     changed: boolean;
     definition: AgentDefinition;
     agentVersion: number;
-    subagentTemplate?: {
-        id: string;
-        version: number;
-    };
+    subagentTemplate?: SubagentTemplateRef;
     subagentVersion?: AgentDefinition;
 }): boolean;
 /** 还原该请求要查的附件 id（该模型用得到的引用，去重、按出现顺序；见 `mediaRefs`）。 */

package/dist/evals/reconstruct.js

@@ -6,6 +6,7 @@ import { mediaRefs, planMedia, } from "../runtime/context/build.js";
 import { assembleModelRequest } from "../runtime/model-call.js";
 import { CHILD_REMOVED_TOOLS } from "../runtime/subagents/definition.js";
 import { PINNED_SKILLS_LIMITS } from "../skills/catalog.js";
+import { AGENT_TOOL } from "../tools/builtin-names.js";
 import { canonicalJson } from "./recorded-tools.js";
 import { toEvents } from "./snapshot.js";
 const DRIFT_ORDER = [
@@ -210,10 +211,21 @@ export function subagentStartedOf(events) {
     const e = events.find((x) => x.type === "subagent_started");
     return e?.type === "subagent_started" ? e.payload : undefined;
 }
-const sameTemplate = (logged, t) => logged.source !== "plugin" || (logged.id === t.id && logged.version === t.version);
+const sameTemplate = (logged, t) => logged.source !== "plugin" ||
+    (logged.id === t.id &&
+        logged.version === t.version &&
+        (logged.platformTemplateId ?? null) === (t.platformTemplateId ?? null));
 const pinsOf = (d) => [...new Set(d.skills?.pinned ?? [])].slice(0, PINNED_SKILLS_LIMITS.count);
-/** Tool refs as a sub-agent gets them without template narrowing (general and org agents). */
-const childToolsOf = (d) => canonicalJson(d.tools.filter((t) => t.kind !== "builtin" || !CHILD_REMOVED_TOOLS.includes(t.name)));
+/**
+ * Tool refs as a sub-agent gets them without template narrowing (general and org agents).
+ * `Agent` depends on the child's depth, not on the definition (agent map spec §4.1): it is kept
+ * only when the logged child had it, so a child logged without it (at the depth limit, or before
+ * nesting) compares equal to a candidate that offers it.
+ */
+const childToolsOf = (d, keepAgent) => canonicalJson(d.tools.filter((t) => t.kind !== "builtin" ||
+    (!CHILD_REMOVED_TOOLS.includes(t.name) &&
+        (keepAgent || t.name !== AGENT_TOOL))));
+const hasAgent = (d) => d.tools.some((t) => t.kind === "builtin" && t.name === AGENT_TOOL);
 /** The parent's selection a template child depends on: its tools, org skills and roster entry. */
 const parentSide = (d, started) => canonicalJson({
     tools: d.tools,
@@ -236,22 +248,29 @@ const parentSide = (d, started) => canonicalJson({
  *   parent version (its own version is {@link ReconstructOptions.subagentTemplate}). Template
  *   narrowing that needs the database (inline and plugin tool allowlists, skill names) is not
  *   recomputed: those compare instructions only.
- * Models and params are not part of it: they are candidate axes of their own.
+ * Models and params are not part of it: they are candidate axes of their own. Neither is the
+ * candidate's `subagents` block as the child's own roster (allowlist, templates, limits; only a
+ * template child's entry in its parent's roster counts, `parentSide`) nor whether it offers `Agent`:
+ * whether a child has `Agent` follows its depth (`keepAgent` comes only from the logged child), and
+ * what a nesting child dispatches is recorded as its `Agent` results, which replay reuses (agent
+ * map spec §4.1, §8). A roster-only candidate therefore reports no `subagent_changed`.
  */
 export function subagentChanged(started, logged, candidate, sameVersion, 
 /** The parent's definition at the case's version (the snapshot's), for template children. */
 original) {
+    const keepAgent = hasAgent(logged);
+    const childTools = (d) => childToolsOf(d, keepAgent);
     const differs = (instructions, pinned, tools) => instructions !== logged.instructions ||
         (pinned !== null && canonicalJson(pinned) !== canonicalJson(pinsOf(logged))) ||
-        (tools !== null && tools !== childToolsOf(logged));
+        (tools !== null && tools !== childTools(logged));
     if (sameVersion) {
         return differs(candidate.instructions, pinsOf(candidate), canonicalJson(candidate.tools));
     }
     switch (started.template.source) {
         case "agent":
-            return differs(candidate.instructions, pinsOf(candidate), childToolsOf(candidate));
+            return differs(candidate.instructions, pinsOf(candidate), childTools(candidate));
         case "general":
-            return (differs(candidate.instructions, [], childToolsOf(candidate)) ||
+            return (differs(candidate.instructions, [], childTools(candidate)) ||
                 (original !== undefined && parentSide(original, started) !== parentSide(candidate, started)));
         case "inline": {
             const t = candidate.subagents?.inline?.find((x) => x.name === started.agentType);

package/dist/evals/run-replay.d.ts

@@ -21,8 +21,10 @@ import type { ResolvedCandidate } from "./step-replay.js";
  *   原运行开始时的 `skills_catalog` 照抄；然后写 `runs` 行与 `run_started`，`agent` 用候选定义。
  * - 插话：原运行中途吸收的可吸收事件（user_message, and finished background tasks: background Bash
  *   spec §4.4），在「原吸收步骤 ≤ 当前步骤」时追加进评测对话并交给 loop（a recorded finish is
- *   appended as recorded: no task starts, polls or stops）。
- * - A wake run (its boundary a finished background task, not a message) is seeded from that event.
+ *   appended as recorded: no task starts, polls or stops; likewise a sub-agent's delivery, agent map
+ *   spec §8: no child is dispatched, sent to or woken）。
+ * - A wake run (its boundary a finished background task or a sub-agent's delivery, not a message)
+ *   is seeded from that event.
  * - 计费（C7，与单步回放同一套）：每次模型请求（含压缩、重试、兜底）发出前查运行仍在执行、仍持有认领；
  *   收完按真实用量、没收完按估算 `consumeTokens`（越限即 `capped`，下一次请求前停下）。
  * - 附件按快照自己的组织与原对话取（C3）。