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

package/dist/skills/usable.d.ts

@@ -0,0 +1,81 @@
+import type { Logger, ObjectStore } from "@capybara-hq/plugin-sdk";
+import type { KernelSchemaDb, SkillManifest, SourceFormat } from "../db/kernel-schema.js";
+/** The `source` prefix of a platform skill version in a snapshot or an invocation record. */
+export declare const PLATFORM_SOURCE = "platform:";
+/** The snapshot `source` of a platform skill version stored at `prefix` (in `deployment/`). */
+export declare const platformSource: (prefix: string) => string;
+/**
+ * Where the files of a skill version with snapshot `source` live: `deployment/` for a platform
+ * version (`platform:<prefix>`), else the org's `kernel/<orgId>/`; `prefix` is the key prefix in
+ * that store.
+ */
+export declare function skillFileStore(storage: {
+    kernel(orgId: string): ObjectStore;
+    deployment(): ObjectStore;
+}, orgId: string, source: string): {
+    store: ObjectStore;
+    prefix: string;
+};
+/** A skill the org can use: one of its own, or a platform skill that is on in the org. */
+export interface UsableSkill {
+    id: string;
+    name: string;
+    description: string;
+    version: number;
+    /** The object prefix of the version (`platform:<prefix>` for a platform version). */
+    source: string;
+    /** The plugin it came from (a platform skill's plugin, an org skill's provenance). */
+    plugin: string | null;
+    origin: "org" | "platform";
+    /** The platform skill whose content this is (a platform skill, or a linked org copy). */
+    platformSkillId?: string;
+}
+/** A usable or selected skill with what the resolvers need beyond {@link UsableSkill}. */
+export interface SkillVersionRow extends UsableSkill {
+    /** `agent`: an agent's own skill (never in the org library). Platform skills are `org`. */
+    scope: "org" | "agent";
+    agentId: string | null;
+    manifest: SkillManifest;
+    format: SourceFormat;
+}
+/**
+ * The ids among `ids` of the platform skills on in the org (see {@link platformOn}), whatever the
+ * org's own skills are named: a skill of the org with the same name would clash with them.
+ */
+export declare function platformSkillsOn(db: KernelSchemaDb, orgId: string, ids: readonly string[]): Promise<Set<string>>;
+/**
+ * The ids among `ids` (platform skills that org copies are pinned to) whose pinned copies the org
+ * may use (ruling P2-18): the platform skill is on in the org ({@link platformSkillsOn}), or it was
+ * removed by a plugin update (soft-deleted, ruling P2-7: a pinned copy then keeps its own version
+ * as the org's).
+ */
+export declare function pinnedSkillLinksServed(db: KernelSchemaDb, orgId: string, ids: readonly string[]): Promise<Set<string>>;
+/**
+ * The org's live skills by id (`ids`; ids that are no usable skill are missing from the map): an
+ * agent's own skill or an org skill with its current version; an org copy linked to a platform
+ * skill without a pin (ruling B2) as that platform skill's current version under the copy's id,
+ * while the platform skill is on in the org; a pinned copy as its own version, while its platform
+ * skill is on in the org (ruling P2-18); a platform skill id while it is on in the org.
+ */
+export declare function skillVersionsById(db: KernelSchemaDb, orgId: string, ids: readonly string[], log?: Pick<Logger, "warn">): Promise<Map<string, SkillVersionRow>>;
+/**
+ * The skills an agent selects, sorted by id: its own skills (`scope = 'agent'`) and the ids of
+ * `orgSkills` that resolve ({@link skillVersionsById}: org skills, linked copies, platform skills
+ * on in the org). Not deduplicated by name.
+ */
+export declare function selectedSkills(db: KernelSchemaDb, a: {
+    orgId: string;
+    agentId: string;
+    orgSkills: readonly string[];
+}, log?: Pick<Logger, "warn">): Promise<SkillVersionRow[]>;
+/**
+ * The org's usable skills, sorted by name: its own live org skills (`scope = 'org'`, unlinked, or
+ * pinned while their platform skill is on in the org, ruling P2-18) and the platform skills on in
+ * the org (see {@link platformOn}). An org copy linked
+ * without a pin is not listed: its platform skill is; except the org's own skill it promoted
+ * (ruling P3-3), listed once under its own id instead of the platform skill.
+ * `log` receives the name-clash warnings.
+ */
+export declare function usableSkills(db: KernelSchemaDb, orgId: string, log?: Pick<Logger, "warn">): Promise<UsableSkill[]>;
+/** {@link usableSkills} with each skill's manifest and format. */
+export declare function usableSkillVersions(db: KernelSchemaDb, orgId: string, log?: Pick<Logger, "warn">): Promise<SkillVersionRow[]>;

package/dist/skills/usable.js

@@ -0,0 +1,379 @@
+import { componentOn } from "../catalog/component-state.js";
+/** The `source` prefix of a platform skill version in a snapshot or an invocation record. */
+export const PLATFORM_SOURCE = "platform:";
+/** The snapshot `source` of a platform skill version stored at `prefix` (in `deployment/`). */
+export const platformSource = (prefix) => `${PLATFORM_SOURCE}${prefix}`;
+/**
+ * Where the files of a skill version with snapshot `source` live: `deployment/` for a platform
+ * version (`platform:<prefix>`), else the org's `kernel/<orgId>/`; `prefix` is the key prefix in
+ * that store.
+ */
+export function skillFileStore(storage, orgId, source) {
+    return source.startsWith(PLATFORM_SOURCE)
+        ? { store: storage.deployment(), prefix: source.slice(PLATFORM_SOURCE.length) }
+        : { store: storage.kernel(orgId), prefix: source };
+}
+/** Plugin install statuses that make a plugin on in the org (phase 1, org catalog state). */
+const LIVE_INSTALL = ["installing", "installed", "upgrading"];
+const byNameThenId = (a, b) => a.name < b.name ? -1 : a.name > b.name ? 1 : a.id < b.id ? -1 : a.id > b.id ? 1 : 0;
+/** The live platform skill rows on in the org (`ids`: only those), before any name clash. */
+async function platformRowsOn(db, orgId, ids) {
+    if (ids !== undefined && ids.length === 0)
+        return [];
+    let q = db
+        .selectFrom("platform_skills as p")
+        .innerJoin("platform_skill_versions as v", (j) => j.onRef("v.skill_id", "=", "p.id").onRef("v.version", "=", "p.current_version"))
+        .leftJoin("catalog_items as c", (j) => j.onRef("c.id", "=", "p.catalog_item_id").on("c.deleted_at", "is", null))
+        .select((eb) => [
+        "p.id",
+        "p.name",
+        "p.plugin_name",
+        "p.catalog_item_id",
+        "p.current_version",
+        "p.scope_mode",
+        "p.scope",
+        "v.manifest",
+        "v.object_prefix",
+        "v.source_format",
+        "c.id as item_id",
+        "c.disabled as item_disabled",
+        "c.builtin as item_builtin",
+        eb
+            .exists(eb
+            .selectFrom("plugin_installs as a")
+            .select("a.id")
+            .whereRef("a.item_id", "=", "p.catalog_item_id")
+            .where("a.org_id", "=", orgId)
+            .where("a.status", "in", [...LIVE_INSTALL]))
+            .as("installed"),
+        eb
+            .exists(eb
+            .selectFrom("component_scope_orgs as l")
+            .select("l.org_id")
+            .where("l.kind", "=", "skill")
+            .whereRef("l.component_id", "=", "p.id")
+            .where("l.org_id", "=", orgId))
+            .as("listed"),
+        eb
+            .selectFrom("component_org_switches as w")
+            .select("w.enabled")
+            .where("w.kind", "=", "skill")
+            .whereRef("w.component_id", "=", "p.id")
+            .where("w.org_id", "=", orgId)
+            .as("switch"),
+    ])
+        .where("p.deleted_at", "is", null)
+        .where("p.disabled", "=", false);
+    if (ids !== undefined)
+        q = q.where("p.id", "in", [...ids]);
+    // the predicate of component scope (catalog/component-state.ts); `disabled` is filtered above
+    return (await q.execute()).filter((r) => componentOn({ scopeMode: r.scope_mode, scope: r.scope, disabled: false, itemId: r.catalog_item_id }, r.catalog_item_id === null
+        ? null
+        : {
+            live: r.item_id !== null,
+            disabled: r.item_disabled === true,
+            builtin: r.item_builtin === true,
+            // the plugin's own scope and list do not decide whether a component is on
+            scope: "optional",
+            listed: false,
+            installed: Boolean(r.installed),
+        }, Boolean(r.listed), r.switch ?? null));
+}
+/**
+ * The ids among `ids` of the platform skills on in the org (see {@link platformOn}), whatever the
+ * org's own skills are named: a skill of the org with the same name would clash with them.
+ */
+export async function platformSkillsOn(db, orgId, ids) {
+    return new Set((await platformRowsOn(db, orgId, ids)).map((r) => r.id));
+}
+/**
+ * The ids among `ids` (platform skills that org copies are pinned to) whose pinned copies the org
+ * may use (ruling P2-18): the platform skill is on in the org ({@link platformSkillsOn}), or it was
+ * removed by a plugin update (soft-deleted, ruling P2-7: a pinned copy then keeps its own version
+ * as the org's).
+ */
+export async function pinnedSkillLinksServed(db, orgId, ids) {
+    if (ids.length === 0)
+        return new Set();
+    const removed = await db
+        .selectFrom("platform_skills")
+        .select("id")
+        .where("id", "in", [...ids])
+        .where("deleted_at", "is not", null)
+        .execute();
+    return new Set([...(await platformSkillsOn(db, orgId, ids)), ...removed.map((r) => r.id)]);
+}
+/**
+ * The platform skills on in the org (`ids`: only those), minus the ones whose name an org skill of
+ * its own already uses (rule 10: the org's wins; logged unless that skill is a copy of the same
+ * component: linked to it, or carrying the same plugin's provenance before the migration linked
+ * it). On in the org:
+ * - never when the skill or its plugin is disabled (or its plugin is deleted);
+ * - `follow`: its plugin is on in the org (a live install, or builtin) and no component switch of
+ *   the org says off;
+ * - `own`: `wantedOn` over the skill's own scope, the org's list membership and its switch.
+ * One query for the skills with their plugin and org state, one for the org's names.
+ */
+async function platformOn(db, orgId, ids, log) {
+    const rows = await platformRowsOn(db, orgId, ids);
+    if (rows.length === 0)
+        return [];
+    const own = await db
+        .selectFrom("skills")
+        .select(["id", "name", "platform_skill_id", "catalog_item_id"])
+        .where("org_id", "=", orgId)
+        .where("scope", "=", "org")
+        .where("deleted_at", "is", null)
+        .where((eb) => eb.or([eb("platform_skill_id", "is", null), eb("pinned_version", "is not", null)]))
+        .where("name", "in", [...new Set(rows.map((r) => r.name))])
+        .execute();
+    const ownByName = new Map(own.map((r) => [r.name, r]));
+    const out = [];
+    const taken = new Map();
+    rows.sort((a, b) => (a.plugin_name ?? "") < (b.plugin_name ?? "")
+        ? -1
+        : (a.plugin_name ?? "") > (b.plugin_name ?? "")
+            ? 1
+            : a.id < b.id
+                ? -1
+                : 1);
+    for (const r of rows) {
+        const o = ownByName.get(r.name);
+        if (o) {
+            const sameComponent = o.platform_skill_id === r.id ||
+                (o.catalog_item_id !== null && o.catalog_item_id === r.catalog_item_id);
+            if (!sameComponent) {
+                log?.warn("platform skill shadowed by an org skill of the same name", {
+                    orgId,
+                    name: r.name,
+                    platformSkillId: r.id,
+                    skillId: o.id,
+                });
+            }
+            continue;
+        }
+        const first = taken.get(r.name);
+        if (first !== undefined) {
+            log?.warn("platform skills share a name in one org", {
+                orgId,
+                name: r.name,
+                kept: first,
+                dropped: r.id,
+            });
+            continue;
+        }
+        taken.set(r.name, r.id);
+        out.push({
+            id: r.id,
+            name: r.name,
+            description: r.manifest.description,
+            version: r.current_version,
+            source: platformSource(r.object_prefix),
+            plugin: r.plugin_name,
+            origin: "platform",
+            platformSkillId: r.id,
+            scope: "org",
+            agentId: null,
+            manifest: r.manifest,
+            format: r.source_format,
+        });
+    }
+    return out;
+}
+/**
+ * The org's live skills by id (`ids`; ids that are no usable skill are missing from the map): an
+ * agent's own skill or an org skill with its current version; an org copy linked to a platform
+ * skill without a pin (ruling B2) as that platform skill's current version under the copy's id,
+ * while the platform skill is on in the org; a pinned copy as its own version, while its platform
+ * skill is on in the org (ruling P2-18); a platform skill id while it is on in the org.
+ */
+export async function skillVersionsById(db, orgId, ids, log) {
+    const unique = [...new Set(ids)];
+    const out = new Map();
+    if (unique.length === 0)
+        return out;
+    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.scope",
+        "s.agent_id",
+        "s.name",
+        "s.current_version",
+        "s.platform_skill_id",
+        "s.pinned_version",
+        "v.manifest",
+        "v.object_prefix",
+        "v.source_format",
+        "c.name as item_name",
+    ])
+        .where("s.org_id", "=", orgId)
+        .where("s.deleted_at", "is", null)
+        .where("s.id", "in", unique)
+        .execute();
+    const linked = rows.filter((r) => r.scope === "org" && r.platform_skill_id !== null && r.pinned_version === null);
+    const pinned = rows.filter((r) => r.scope === "org" && r.platform_skill_id !== null && r.pinned_version !== null);
+    const known = new Set(rows.map((r) => r.id));
+    const platformIds = [
+        ...new Set([
+            ...unique.filter((id) => !known.has(id)),
+            ...linked.map((r) => r.platform_skill_id),
+        ]),
+    ];
+    const platform = new Map((await platformOn(db, orgId, platformIds, log)).map((p) => [p.id, p]));
+    const owned = await ownedPlatformIds(db, orgId, linked.map((r) => r.platform_skill_id));
+    // ruling P2-18: a pinned copy serves its own version while its platform skill is on in the org
+    const pinnedOn = await pinnedSkillLinksServed(db, orgId, pinned.map((r) => r.platform_skill_id));
+    for (const r of rows) {
+        if (linked.includes(r)) {
+            const p = platform.get(r.platform_skill_id);
+            if (!p)
+                continue;
+            if (!owned.has(p.id)) {
+                out.set(r.id, { ...p, id: r.id });
+                continue;
+            }
+            // the org's own skill, promoted (ruling P3-3): promotion copied its current version to the
+            // platform under the same number, so while that is still the platform's current version it
+            // serves its own stored version (its snapshot source stays); a newer platform version (the
+            // owner's later upload, ruling P3-4) serves under its id. Either way it is the org's own.
+            if (r.current_version !== p.version) {
+                out.set(r.id, { ...p, id: r.id, origin: "org", plugin: r.item_name });
+                continue;
+            }
+        }
+        if (pinned.includes(r) && !pinnedOn.has(r.platform_skill_id))
+            continue;
+        out.set(r.id, {
+            id: r.id,
+            name: r.name,
+            description: r.manifest.description,
+            version: r.current_version,
+            source: r.object_prefix,
+            plugin: r.item_name,
+            origin: "org",
+            ...(r.platform_skill_id !== null && { platformSkillId: r.platform_skill_id }),
+            scope: r.scope,
+            agentId: r.agent_id,
+            manifest: r.manifest,
+            format: r.source_format,
+        });
+    }
+    for (const id of unique) {
+        const p = platform.get(id);
+        if (p && !known.has(id))
+            out.set(id, p);
+    }
+    return out;
+}
+/**
+ * The ids among `platformIds` of the live platform skills owned by `orgId` (promoted from its own
+ * skills, ruling P3-3).
+ */
+async function ownedPlatformIds(db, orgId, platformIds) {
+    if (platformIds.length === 0)
+        return new Set();
+    const rows = await db
+        .selectFrom("platform_skills")
+        .select("id")
+        .where("id", "in", [...new Set(platformIds)])
+        .where("owner_org_id", "=", orgId)
+        .where("deleted_at", "is", null)
+        .execute();
+    return new Set(rows.map((r) => r.id));
+}
+/**
+ * The skills an agent selects, sorted by id: its own skills (`scope = 'agent'`) and the ids of
+ * `orgSkills` that resolve ({@link skillVersionsById}: org skills, linked copies, platform skills
+ * on in the org). Not deduplicated by name.
+ */
+export async function selectedSkills(db, a, log) {
+    const agentOwn = await db
+        .selectFrom("skills")
+        .select("id")
+        .where("org_id", "=", a.orgId)
+        .where("scope", "=", "agent")
+        .where("agent_id", "=", a.agentId)
+        .where("deleted_at", "is", null)
+        .execute();
+    const orgSkills = new Set(a.orgSkills);
+    const byId = await skillVersionsById(db, a.orgId, [...agentOwn.map((r) => r.id), ...orgSkills], log);
+    return [...byId.values()]
+        .filter((r) => (r.scope === "agent" ? r.agentId === a.agentId : orgSkills.has(r.id)))
+        .sort((x, y) => (x.id < y.id ? -1 : x.id > y.id ? 1 : 0));
+}
+/**
+ * The org's usable skills, sorted by name: its own live org skills (`scope = 'org'`, unlinked, or
+ * pinned while their platform skill is on in the org, ruling P2-18) and the platform skills on in
+ * the org (see {@link platformOn}). An org copy linked
+ * without a pin is not listed: its platform skill is; except the org's own skill it promoted
+ * (ruling P3-3), listed once under its own id instead of the platform skill.
+ * `log` receives the name-clash warnings.
+ */
+export async function usableSkills(db, orgId, log) {
+    return (await usableSkillVersions(db, orgId, log)).map(({ scope: _s, agentId: _a, manifest: _m, format: _f, ...u }) => u);
+}
+/** {@link usableSkills} with each skill's manifest and format. */
+export async function usableSkillVersions(db, orgId, log) {
+    const own = 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.current_version",
+        "s.platform_skill_id",
+        "v.manifest",
+        "v.object_prefix",
+        "v.source_format",
+        "c.name as item_name",
+    ])
+        .where("s.org_id", "=", orgId)
+        .where("s.scope", "=", "org")
+        .where("s.deleted_at", "is", null)
+        .where((eb) => eb.or([eb("s.platform_skill_id", "is", null), eb("s.pinned_version", "is not", null)]))
+        .execute();
+    // ruling P2-18: a pinned copy follows its platform skill's availability (the pin fixes the
+    // version only)
+    const pinnedOn = await pinnedSkillLinksServed(db, orgId, [
+        ...new Set(own.flatMap((r) => (r.platform_skill_id === null ? [] : [r.platform_skill_id]))),
+    ]);
+    const rows = own
+        .filter((r) => r.platform_skill_id === null || pinnedOn.has(r.platform_skill_id))
+        .map((r) => ({
+        id: r.id,
+        name: r.name,
+        description: r.manifest.description,
+        version: r.current_version,
+        source: r.object_prefix,
+        plugin: r.item_name,
+        origin: "org",
+        ...(r.platform_skill_id !== null && { platformSkillId: r.platform_skill_id }),
+        scope: "org",
+        agentId: null,
+        manifest: r.manifest,
+        format: r.source_format,
+    }));
+    // the org's own skills it promoted: under their own ids, instead of their platform skills
+    const promoted = await db
+        .selectFrom("skills as s")
+        .innerJoin("platform_skills as p", "p.id", "s.platform_skill_id")
+        .select(["s.id", "s.platform_skill_id"])
+        .where("s.org_id", "=", orgId)
+        .where("s.scope", "=", "org")
+        .where("s.deleted_at", "is", null)
+        .where("s.pinned_version", "is", null)
+        .where("p.owner_org_id", "=", orgId)
+        .where("p.deleted_at", "is", null)
+        .execute();
+    const promotedTo = new Set(promoted.map((r) => r.platform_skill_id));
+    if (promoted.length > 0) {
+        const served = await skillVersionsById(db, orgId, promoted.map((r) => r.id), log);
+        rows.push(...served.values());
+    }
+    rows.push(...(await platformOn(db, orgId, undefined, log)).filter((p) => !promotedTo.has(p.id)));
+    return rows.sort(byNameThenId);
+}

package/dist/tools/approvals.service.d.ts

@@ -32,6 +32,16 @@ export interface ApprovalRecord {
     decidedAt: string | null;
     /** The reason given with a denial (null otherwise). */
     denyReason: string | null;
+    /** The kernel-rendered summary of the call (a per-call policy's; null otherwise). */
+    summary: {
+        zh: string;
+        en: string;
+    } | null;
+    /**
+     * The scopes the decider may choose: stored with the approval (a per-call policy that may not
+     * be remembered stores `["once"]`), else derived: only "once" for a role escalation.
+     */
+    scopes: ApprovalScope[];
     expiresAt: string;
     createdAt: string;
 }
@@ -54,8 +64,9 @@ export interface ApprovalView extends ApprovalRecord {
         name: string;
     };
     /**
-     * 网页中该会话的路径（不含语言前缀）。A sub-agent's approval links to its parent conversation
-     * with the sub-agent open: `/chat/<parent>?subagent=<child>`.
+     * 网页中该会话的路径（不含语言前缀）。A sub-agent's approval, at any depth, links to the root
+     * conversation of its tree with the sub-agent open: `/chat/<root>?subagent=<child>` (agent map
+     * spec §7).
      */
     conversationPath: string;
     /** Set when the approval belongs to a sub-agent: the conversation it was dispatched from. */
@@ -82,6 +93,13 @@ export interface ApprovalRequestInput {
     attempt?: number;
     /** Which rule asked (written to `approval_requested.policy`; display only). */
     policy?: ApprovalPolicySource;
+    /** The kernel-rendered summary of the call (per-call policies). */
+    summary?: {
+        zh: string;
+        en: string;
+    };
+    /** The scopes the decider may choose; unset: derived (see {@link ApprovalRecord.scopes}). */
+    scopes?: ApprovalScope[];
 }
 export interface DecisionInput {
     decision: "approve" | "deny";

package/dist/tools/approvals.service.js

@@ -20,6 +20,7 @@ import { TransactionHost } from "../infra/database/transaction-host.js";
 import { Transactional } from "../infra/database/transactional.decorator.js";
 import { KernelEvents } from "../infra/events/kernel-events.js";
 import { ORG_ROLES, roleAtLeast } from "../orgs/roles.js";
+import { rootConversationOf } from "../runtime/subagents/child.js";
 import { pluginDisplayNames } from "./display-names.js";
 export { APPROVAL_DENY_REASON_MAX_CHARS } from "../conversations/events.js";
 /** `list` 一次最多返回的审批数（收件箱据此判断这个来源是否取满）。 */
@@ -27,6 +28,8 @@ export const APPROVALS_LIST_MAX = 100;
 const notFound = () => new ApiError("approval.not_found", "Approval not found");
 const iso = (v) => new Date(v).toISOString();
 const isRole = (v) => v !== null && ORG_ROLES.includes(v);
+/** The scopes of an approval without stored ones: a role escalation is approved only once. */
+const derivedScopes = (requestedFor) => requestedFor === null ? ["once"] : ["once", "session", "always"];
 function toRecord(r) {
     return {
         id: r.id,
@@ -46,6 +49,8 @@ function toRecord(r) {
         decidedBy: r.decided_by,
         decidedAt: r.decided_at === null ? null : iso(r.decided_at),
         denyReason: r.deny_reason,
+        summary: r.summary ?? null,
+        scopes: r.scopes ?? derivedScopes(r.requested_for),
         expiresAt: iso(r.expires_at),
         createdAt: iso(r.created_at),
     };
@@ -125,6 +130,8 @@ let ApprovalsService = class ApprovalsService {
             input: JSON.stringify(input.input ?? {}),
             requested_for: input.requestedFor,
             approver_role: input.approverRole,
+            summary: input.summary === undefined ? null : JSON.stringify(input.summary),
+            scopes: input.scopes ?? null,
             scope: null,
             decided_by: null,
             expires_at: sql `now() + ${hours}::integer * interval '1 hour'`,
@@ -267,6 +274,11 @@ let ApprovalsService = class ApprovalsService {
         if (scope !== null && scope !== "once" && before.requestedFor === null) {
             throw new ApiError("validation_failed", 'Only scope "once" is allowed for role-escalated approvals', [{ path: "scope", message: 'Only "once" is allowed for role-escalated approvals' }]);
         }
+        // the scopes stored with the approval (an org / platform operation: "once" only), whatever
+        // the client offered
+        if (scope !== null && !before.scopes.includes(scope)) {
+            throw new ApiError("approval.scope_not_allowed", `Scope "${scope}" is not allowed for this approval; allowed: ${before.scopes.join(", ")}`);
+        }
         const updated = await t
             .updateTable("approvals")
             .set({
@@ -283,12 +295,14 @@ let ApprovalsService = class ApprovalsService {
         const hash = before.specHash;
         const connectorId = before.connectorId;
         if (scope === "session") {
-            // a sub-agent's grant is its parent conversation's (sub-agents spec §9): its siblings and
-            // the parent itself are not asked again for the same call
+            // a sub-agent's grant is the root conversation's (agent map spec §7): the root and every
+            // agent of its tree, at any depth, are not asked again for the same call
             await t
                 .insertInto("conversation_tool_grants")
                 .values({
-                conversation_id: ctx.parent_conversation_id ?? before.conversationId,
+                conversation_id: ctx.parent_conversation_id === null
+                    ? before.conversationId
+                    : await rootConversationOf(t, ctx.parent_conversation_id),
                 tool_key: before.toolKey,
                 spec_hash: hash,
                 connector_id: connectorId,
@@ -571,6 +585,11 @@ let ApprovalsService = class ApprovalsService {
             .where("runs.id", "in", [...new Set(recs.map((r) => r.runId))])
             .execute();
         const ctx = new Map(ctxRows.map((r) => [r.id, r]));
+        // a sub-agent's approval links to the root conversation of its tree (agent map spec §7)
+        const roots = new Map();
+        for (const p of new Set(ctxRows.flatMap((r) => r.parent_conversation_id ?? []))) {
+            roots.set(p, await rootConversationOf(db.db, p));
+        }
         const names = await this.agentNames([...new Set(ctxRows.map((r) => r.agent_id))]);
         const connectorIds = [
             ...new Set(recs.flatMap((r) => (r.connectorId === null ? [] : [r.connectorId]))),
@@ -615,7 +634,7 @@ let ApprovalsService = class ApprovalsService {
                     agent: { id: c.agent_id, name: names.get(c.agent_id) ?? "" },
                     ...(c.parent_conversation_id !== null
                         ? {
-                            conversationPath: `/chat/${c.parent_conversation_id}?subagent=${r.conversationId}`,
+                            conversationPath: `/chat/${roots.get(c.parent_conversation_id) ?? c.parent_conversation_id}?subagent=${r.conversationId}`,
                             parentConversationId: c.parent_conversation_id,
                         }
                         : { conversationPath: `/chat/${r.conversationId}` }),

package/dist/tools/builtin-names.d.ts

@@ -21,10 +21,13 @@ export declare const BUILTIN: {
     readonly ReadToolOutput: "ReadToolOutput";
     readonly ToolSearch: "ToolSearch";
     readonly Agent: "Agent";
+    readonly SendMessage: "SendMessage";
+    readonly SubagentHandback: "SubagentHandback";
     readonly TaskOutput: "TaskOutput";
     readonly TaskStop: "TaskStop";
     readonly WebSearch: "WebSearch";
     readonly WebFetch: "WebFetch";
+    readonly Platform: "Platform";
 };
 export type BuiltinName = (typeof BUILTIN)[keyof typeof BUILTIN];
 /**
@@ -49,7 +52,9 @@ export declare const SANDBOX_ASK_TOOL_NAMES: ReadonlySet<string>;
  * Every builtin name. Saving an agent checks builtin refs against this list, not against what is
  * registered now, so the order the implementations land in never affects a saved definition.
  * `SkillWrite` is available only when a definition names it; `ToolSearch` and `Skill` are added
- * by the registry; `Agent` dispatches sub-agents and its description is built per agent.
+ * by the registry; `Agent` dispatches sub-agents and its description is built per agent;
+ * `SendMessage` and `SubagentHandback` are added by the registry ({@link SUBAGENT_MESSAGE_TOOLS}).
+ * `Platform` calls the platform's own operations as the run's person (Platform tool spec).
  */
 export declare const BUILTIN_TOOL_NAMES: readonly BuiltinName[];
 /** The builtin that loads a skill (added by the registry when the log has a skills catalog). */
@@ -58,6 +63,16 @@ export declare const SKILL_LOAD: "Skill";
 export declare const TOOL_SEARCH: "ToolSearch";
 /** The builtin that dispatches sub-agents. */
 export declare const AGENT_TOOL: "Agent";
+/** The builtin that sends a message to one of the caller's sub-agents or to its parent. */
+export declare const SEND_MESSAGE: "SendMessage";
+/** The builtin that hands a sub-agent's report back to its parent (sub-agents only). */
+export declare const SUBAGENT_HANDBACK: "SubagentHandback";
+/**
+ * The tools between the agents of one tree (agent map spec §4.2, §4.3), added by the registry
+ * whatever a definition names: `SendMessage` to an agent that has `Agent` or a parent, and
+ * `SubagentHandback` to a sub-agent. A definition's ref to either is ignored.
+ */
+export declare const SUBAGENT_MESSAGE_TOOLS: ReadonlySet<string>;
 /**
  * Tool keys on the spec 3.6 R3 fixed list ("allowed is not confirmed"): their policy is at least
  * `ask` and remembered grants never let them through. `SkillWrite` changes shared skills.
@@ -70,14 +85,15 @@ export declare const R3_FIXED_ASK_TOOL_KEYS: ReadonlySet<string>;
  */
 export declare const R3_SHARED_AGENT_ONLY_TOOL_KEYS: ReadonlySet<string>;
 /**
- * Tools a sub-agent never gets (sub-agents spec §5.3, §5.5): `Agent` (depth 1), `AskUserQuestion`
- * (the person does not see the child), `Deliver` (delivering files is the parent's job) and
- * `SkillWrite`.
+ * Tools a sub-agent never gets (sub-agents spec §5.3, §5.5): `AskUserQuestion` (the person does
+ * not see the child), `Deliver` (delivering files is the parent's job) and `SkillWrite`. `Agent`
+ * is removed only from a child at `subagents.maxDepth` (agent map spec §4.1, `effectiveDefinition`).
  */
-export declare const CHILD_REMOVED_TOOLS: readonly ["Agent", "AskUserQuestion", "Deliver", "SkillWrite"];
+export declare const CHILD_REMOVED_TOOLS: readonly ["AskUserQuestion", "Deliver", "SkillWrite"];
 /**
  * The tools of a new agent created without `tools` (`ToolSearch` is added by the registry, never
  * by a definition). Only for create requests; updates and stored versions get no defaults.
+ * `Platform` is on by default (Platform tool spec §3: reads are harmless, every write confirmed).
  */
 export declare const DEFAULT_AGENT_TOOLS: AgentToolRef[];
 /** Kinds of the builtin tools (display only); a builtin missing here is a plain `tool`. */