@capybara-hq/kernel 0.1.0-rc.1 → 0.1.0-rc.10

package/dist/orgs/settings.service.js

@@ -1,18 +1,38 @@
+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 { validateAllowHost } from "@capybara-hq/plugin-sdk";
+import { Inject, Injectable } from "@nestjs/common";
 import { z } from "zod";
 import { ApiError } from "../errors.js";
 import { audit } from "../identity/audit.js";
 import { readSandboxLimitOverride } from "../identity/settings.js";
-import { lockOrgAndAuthorize } from "./org-lock.js";
+import { KernelConfigService } from "../infra/config/kernel-config.service.js";
+import { KernelDb } from "../infra/database/kernel-db.js";
+import { TransactionHost } from "../infra/database/transaction-host.js";
+import { Transactional } from "../infra/database/transactional.decorator.js";
+import { IanaTimeZone } from "../time-zone.js";
+import { OrgLock } from "./org-lock.js";
 /**
  * 组织设置（`capybara.orgs.settings` jsonb）。读取宽松：缺失或非法的字段按默认值，未知键保留不动
  * （更新时与存量合并），新版本加字段不需要迁移。
- * - `toolSearch`：工具超过阈值时是否改用目录 + `tool_search`（D11，默认 on）。
+ * - `toolSearch`：工具超过阈值时是否改用目录 + `ToolSearch`（D11，默认 on）。
  * - `locale`：组织默认语言（`zh` / `en`，默认 en），机器人在 IM 里说的固定话术按它选择。
  * - `sandboxToolPolicy`：沙箱工具的默认策略（M5 T8，默认 allow）。为 `ask` 时除只读的
- *   `sandbox_read` / `sandbox_glob` / `sandbox_grep` 外都需要审批（执行时实时读取）。
+ *   `Read` / `Glob` / `Grep` 外都需要审批（执行时实时读取）。
+ * - `wakeOnBackgroundTask`：组织对 `runtime.wakeOnBackgroundTask` 的覆盖（缺省跟随部署），见 {@link effectiveWakeOnBackgroundTask}。
  * - `sandboxEgress`：组织的沙箱出站（Ruling M19 / D6），缺省跟随部署的 `sandbox.limits.egress` + `allowHosts`。
  *   见 {@link effectiveSandboxEgress}。存量值非法时按 `none` 读（宁可断网，不悄悄放宽到部署默认）。
+ * - `platformTool`: the `Platform` builtin for the whole org (Platform tool spec §3): `on`,
+ *   `read-only` (writes listed as unavailable) or `off` (default `on`).
+ * - `timeZone`: the org's default time zone (IANA; absent = UTC) for senders without one of their
+ *   own (run context spec §3.3); an invalid stored value reads as absent.
  */
 /** 组织沙箱出站白名单的主机数上限。 */
 export const ORG_SANDBOX_ALLOW_HOSTS_MAX = 200;
@@ -43,7 +63,12 @@ export const OrgSettingsSchema = z.object({
     toolSearch: z.enum(["on", "off"]).default("on").catch("on"),
     locale: z.enum(["zh", "en"]).default("en").catch("en"),
     sandboxToolPolicy: z.enum(["allow", "ask"]).default("allow").catch("allow"),
+    platformTool: z.enum(["on", "read-only", "off"]).default("on").catch("on"),
     sandboxEgress: SandboxEgressSettingSchema.optional().catch({ mode: "none" }),
+    /** Overrides `runtime.wakeOnBackgroundTask`; absent follows the deployment. */
+    wakeOnBackgroundTask: z.boolean().optional().catch(undefined),
+    /** The org's default time zone (run context spec §3.3); absent = UTC. */
+    timeZone: IanaTimeZone.optional().catch(undefined),
 });
 /** PATCH 体：只改给出的字段；未知字段 → 400。 */
 export const OrgSettingsPatchSchema = z
@@ -51,8 +76,13 @@ export const OrgSettingsPatchSchema = z
     toolSearch: z.enum(["on", "off"]).optional(),
     locale: z.enum(["zh", "en"]).optional(),
     sandboxToolPolicy: z.enum(["allow", "ask"]).optional(),
+    platformTool: z.enum(["on", "read-only", "off"]).optional(),
+    /** null clears (follow the deployment again). */
+    wakeOnBackgroundTask: z.boolean().nullable().optional(),
     /** null 清除（恢复跟随部署默认）。 */
     sandboxEgress: SandboxEgressSettingSchema.nullable().optional(),
+    /** The org's default time zone (IANA); null clears it (UTC). */
+    timeZone: IanaTimeZone.nullable().optional(),
 })
     .strict();
 /**
@@ -66,8 +96,12 @@ export function effectiveSandboxEgress(deployment, org) {
         return { egress: "none", allowHosts: [] };
     return { egress: "allowlist", allowHosts: [...(org.allowHosts ?? deployment.allowHosts)] };
 }
+/** Whether a finished background task wakes an idle conversation: the org's setting, else the deployment's. */
+export function effectiveWakeOnBackgroundTask(deployment, org) {
+    return org ?? deployment;
+}
 /**
- * 组织实际生效的沙箱限额（C19 / Ruling M16）：企业管理员的覆盖（部署设置 `sandboxLimitOverrides[orgId]`）
+ * 组织实际生效的沙箱限额（C19 / Ruling M16）：超级管理员的覆盖（部署设置 `sandboxLimitOverrides[orgId]`）
  * 给出的 cpu / memoryMb 替换部署默认，未给的项、disk 与出站沿用 `deployment`。只在创建沙箱时读取。
  */
 export function effectiveSandboxLimits(deployment, override) {
@@ -96,30 +130,33 @@ export async function readOrgSettings(db, orgId) {
     return parseOrgSettings(row?.settings);
 }
 /** 组织设置服务：读取与修改（修改需 `org.update`，锁内实时复核角色，写审计）。 */
-export class OrgSettingsService {
+let OrgSettingsService = class OrgSettingsService {
     db;
+    txHost;
+    orgLock;
     config;
-    constructor(db, 
-    /** 部署配置（校验 `sandboxEgress` 不超出部署）；省略视为部署出站 `allowlist` + 空白名单。 */
+    constructor(db, txHost, orgLock, 
+    /** The deployment config (`sandboxEgress` may not exceed the deployment's). */
     config) {
         this.db = db;
+        this.txHost = txHost;
+        this.orgLock = orgLock;
         this.config = config;
     }
     /** 部署默认值（设置页展示「跟随部署」时的实际取值）。 */
     deployment() {
-        const lim = this.config?.().sandbox.limits;
+        const lim = this.config.get().sandbox.limits;
         return {
-            sandboxEgress: { mode: lim?.egress ?? "allowlist", allowHosts: [...(lim?.allowHosts ?? [])] },
+            sandboxEgress: { mode: lim.egress, allowHosts: [...lim.allowHosts] },
         };
     }
-    /** 组织实际生效的沙箱 cpu / 内存（只读；由企业管理员在部署设置里覆盖）。 */
+    /** 组织实际生效的沙箱 cpu / 内存（只读；由超级管理员在部署设置里覆盖）。 */
     async sandboxLimits(orgId) {
-        const lim = this.config?.().sandbox.limits;
-        const override = await readSandboxLimitOverride(this.db, orgId);
+        const lim = this.config.get().sandbox.limits;
+        const override = await readSandboxLimitOverride(this.db.db, orgId);
         return {
-            // 没有部署配置（测试构造）时用 schema 默认值 1 核 / 2048 MiB
-            cpu: override?.cpu ?? lim?.cpu ?? 1,
-            memoryMb: override?.memoryMb ?? lim?.memoryMb ?? 2048,
+            cpu: override?.cpu ?? lim.cpu,
+            memoryMb: override?.memoryMb ?? lim.memoryMb,
             source: override === undefined ? "deployment" : "override",
         };
     }
@@ -134,45 +171,67 @@ export class OrgSettingsService {
             throw new ApiError("org.not_found", "Organization not found");
         return parseOrgSettings(row.settings);
     }
-    async update(orgId, patch, actorAccountId, actorTokenId) {
+    /** The refusals of {@link update} that need no read of the org (the Platform tool's precheck). */
+    check(patch) {
         if (patch.sandboxEgress?.mode === "allowlist" &&
             this.deployment().sandboxEgress.mode === "none") {
             throw new ApiError("org.sandbox_egress_not_allowed", "This deployment disables sandbox network access (sandbox.limits.egress is none); an organization can only set sandboxEgress to none");
         }
-        return this.db.transaction().execute(async (trx) => {
-            await lockOrgAndAuthorize(trx, orgId, actorAccountId, "org.update");
-            const row = await trx
-                .selectFrom("orgs")
-                .select("settings")
-                .where("id", "=", orgId)
-                .executeTakeFirstOrThrow();
-            const stored = asObject(row.settings);
-            const before = parseOrgSettings(stored);
-            const changes = Object.fromEntries(Object.entries(patch)
-                .filter(([, v]) => v !== undefined)
-                // null 清除 sandboxEgress：恢复跟随部署默认
-                .map(([k, v]) => [k, v === null ? undefined : v]));
-            const after = { ...before, ...changes };
-            if (after.sandboxEgress === undefined)
-                delete after.sandboxEgress;
-            if (sameSettings(before, after))
-                return before;
-            // 与存量合并：保留本版本不认识的键（清除的 sandboxEgress 不留在存量里）
-            const { sandboxEgress: _old, ...rest } = stored;
-            await trx
-                .updateTable("orgs")
-                .set({ settings: JSON.stringify({ ...rest, ...after }) })
-                .where("id", "=", orgId)
-                .execute();
-            await audit(trx, {
-                actorAccountId,
-                ...(actorTokenId !== undefined && { actorTokenId }),
-                orgId,
-                action: "org.settings_updated",
-                target: orgId,
-                detail: { before, after },
-            });
-            return after;
+    }
+    async update(orgId, patch, actorAccountId, actorTokenId, 
+    /** Merged into the audit detail (the Platform tool's `via: "agent"`). */
+    auditDetail) {
+        this.check(patch);
+        return this.updateIn(orgId, patch, actorAccountId, actorTokenId, auditDetail);
+    }
+    async updateIn(orgId, patch, actorAccountId, actorTokenId, auditDetail) {
+        await this.orgLock.lockAndAuthorize(orgId, actorAccountId, "org.update");
+        const row = await this.db
+            .selectFrom("orgs")
+            .select("settings")
+            .where("id", "=", orgId)
+            .executeTakeFirstOrThrow();
+        const stored = asObject(row.settings);
+        const before = parseOrgSettings(stored);
+        const changes = Object.fromEntries(Object.entries(patch)
+            .filter(([, v]) => v !== undefined)
+            // null clears sandboxEgress / wakeOnBackgroundTask: follow the deployment default again
+            .map(([k, v]) => [k, v === null ? undefined : v]));
+        const after = { ...before, ...changes };
+        if (after.sandboxEgress === undefined)
+            delete after.sandboxEgress;
+        if (after.wakeOnBackgroundTask === undefined)
+            delete after.wakeOnBackgroundTask;
+        if (after.timeZone === undefined)
+            delete after.timeZone;
+        if (sameSettings(before, after))
+            return before;
+        // 与存量合并：保留本版本不认识的键（清除的 sandboxEgress 不留在存量里）
+        const { sandboxEgress: _old, wakeOnBackgroundTask: _oldWake, timeZone: _oldZone, ...rest } = stored;
+        await this.db
+            .updateTable("orgs")
+            .set({ settings: JSON.stringify({ ...rest, ...after }) })
+            .where("id", "=", orgId)
+            .execute();
+        await audit(this.db.db, {
+            actorAccountId,
+            ...(actorTokenId !== undefined && { actorTokenId }),
+            orgId,
+            action: "org.settings_updated",
+            target: orgId,
+            detail: { before, after, ...auditDetail },
         });
+        return after;
     }
-}
+};
+__decorate([
+    Transactional()
+], OrgSettingsService.prototype, "updateIn", null);
+OrgSettingsService = __decorate([
+    Injectable(),
+    __param(0, Inject(KernelDb)),
+    __param(1, Inject(TransactionHost)),
+    __param(2, Inject(OrgLock)),
+    __param(3, Inject(KernelConfigService))
+], OrgSettingsService);
+export { OrgSettingsService };

package/dist/overrides.d.ts

@@ -0,0 +1,63 @@
+import type { NestInterceptor } from "@nestjs/common";
+import { APP_INTERCEPTOR } from "@nestjs/core";
+import { CHANNEL_WEBHOOK_TIMINGS, type ChannelWebhookTimings } from "./channels/webhook.js";
+import type { EvalReplayHooks } from "./evals/run-replay.js";
+import { EVAL_REPLAY_HOOKS } from "./evals/worker.js";
+import { BOOTSTRAP_LOCK_TTL } from "./extensions/bootstrap.js";
+import { FILE_PREVIEW_TIMEOUT } from "./files/previewers.js";
+import { LIST_MODELS_TIMEOUT } from "./runtime/providers.js";
+import { RUN_CONTEXT_CLOCK } from "./runtime/run-context.service.js";
+import { AGENT_LOOP_FACTORY, type AgentLoopFactory } from "./runtime/run-steps.js";
+import { RUN_HOOKS, type RunHooks } from "./runtime/run-worker.js";
+import { SUBAGENT_MESSAGES_HOOKS, type SubagentMessagesHooks } from "./runtime/subagents/messages.js";
+import { USAGE_REPORT_RETRY, type UsageReportRetry } from "./runtime/usage-report.js";
+import { SANDBOX_LEASE_TIMINGS, type SandboxLeaseTimings } from "./sandbox/leases.js";
+import { TOOL_PIPELINE_HOOKS, type ToolPipelineHooks } from "./tools/pipeline.js";
+import { EMBED_TOKEN_CLOCK } from "./ui/embed-token.js";
+/**
+ * The value each seam token takes. Every token is an optional provider the kernel itself never
+ * provides (its consumer falls back to the production default):
+ *
+ * - `AGENT_LOOP_FACTORY`: the agent loop runs execute (default the LangGraph loop);
+ * - `RUN_HOOKS`: the run worker's hooks;
+ * - `EVAL_REPLAY_HOOKS`: the hooks of the eval full-run replay and the judge;
+ * - `TOOL_PIPELINE_HOOKS`: the tool pipeline's hooks and policy decision;
+ * - `SUBAGENT_MESSAGES_HOOKS`: the sub-agent message tools' hooks (a send raced by a run's end);
+ * - `BOOTSTRAP_LOCK_TTL`, `FILE_PREVIEW_TIMEOUT`, `LIST_MODELS_TIMEOUT`, `USAGE_REPORT_RETRY`,
+ *   `SANDBOX_LEASE_TIMINGS`, `CHANNEL_WEBHOOK_TIMINGS`: shorter timings;
+ * - `EMBED_TOKEN_CLOCK`: the clock embed tokens are issued and checked with;
+ * - `RUN_CONTEXT_CLOCK`: the clock run start reads the run context's date from, and the
+ *   `CurrentTime` builtin the time;
+ * - `APP_INTERCEPTOR`: one more global interceptor (a probe of the matched routes).
+ */
+interface KernelSeams {
+    [AGENT_LOOP_FACTORY]: AgentLoopFactory;
+    [RUN_HOOKS]: RunHooks;
+    [EVAL_REPLAY_HOOKS]: EvalReplayHooks;
+    [TOOL_PIPELINE_HOOKS]: ToolPipelineHooks;
+    [SUBAGENT_MESSAGES_HOOKS]: SubagentMessagesHooks;
+    [BOOTSTRAP_LOCK_TTL]: number;
+    [FILE_PREVIEW_TIMEOUT]: number;
+    [LIST_MODELS_TIMEOUT]: number;
+    [USAGE_REPORT_RETRY]: UsageReportRetry;
+    [SANDBOX_LEASE_TIMINGS]: Partial<SandboxLeaseTimings>;
+    [CHANNEL_WEBHOOK_TIMINGS]: Partial<ChannelWebhookTimings>;
+    [EMBED_TOKEN_CLOCK]: () => number;
+    [RUN_CONTEXT_CLOCK]: () => number;
+    [APP_INTERCEPTOR]: NestInterceptor;
+}
+/**
+ * A seam of the kernel's own tests (`KernelAppOptions.overrides`): a value for one of the named
+ * seam tokens of {@link KernelSeams}. Domain classes cannot be replaced this way. The tokens are
+ * not exported from the package, and `@capybara-hq/testing`'s `startTestKernel` takes no
+ * overrides (decision R22 of the Nest kernel spec).
+ */
+export type KernelOverride = {
+    [K in keyof KernelSeams]: {
+        provide: K;
+        useValue: KernelSeams[K];
+    };
+}[keyof KernelSeams];
+/** The tokens {@link KernelOverride} may name; any other token is refused when the application is built. */
+export declare const KERNEL_OVERRIDE_TOKENS: ReadonlySet<unknown>;
+export {};

package/dist/overrides.js

@@ -0,0 +1,34 @@
+import { APP_INTERCEPTOR } from "@nestjs/core";
+import { CHANNEL_WEBHOOK_TIMINGS } from "./channels/webhook.js";
+import { EVAL_REPLAY_HOOKS } from "./evals/worker.js";
+import { BOOTSTRAP_LOCK_TTL } from "./extensions/bootstrap.js";
+import { FILE_PREVIEW_TIMEOUT } from "./files/previewers.js";
+import { LIST_MODELS_TIMEOUT } from "./runtime/providers.js";
+import { RUN_CONTEXT_CLOCK } from "./runtime/run-context.service.js";
+import { AGENT_LOOP_FACTORY } from "./runtime/run-steps.js";
+import { RUN_HOOKS } from "./runtime/run-worker.js";
+import { SUBAGENT_MESSAGES_HOOKS, } from "./runtime/subagents/messages.js";
+import { USAGE_REPORT_RETRY } from "./runtime/usage-report.js";
+import { SANDBOX_LEASE_TIMINGS } from "./sandbox/leases.js";
+import { TOOL_PIPELINE_HOOKS } from "./tools/pipeline.js";
+import { EMBED_TOKEN_CLOCK } from "./ui/embed-token.js";
+const SEAM_TOKENS = [
+    AGENT_LOOP_FACTORY,
+    RUN_HOOKS,
+    EVAL_REPLAY_HOOKS,
+    TOOL_PIPELINE_HOOKS,
+    SUBAGENT_MESSAGES_HOOKS,
+    BOOTSTRAP_LOCK_TTL,
+    FILE_PREVIEW_TIMEOUT,
+    LIST_MODELS_TIMEOUT,
+    USAGE_REPORT_RETRY,
+    SANDBOX_LEASE_TIMINGS,
+    CHANNEL_WEBHOOK_TIMINGS,
+    EMBED_TOKEN_CLOCK,
+    RUN_CONTEXT_CLOCK,
+    APP_INTERCEPTOR,
+];
+const allSeamsListed = true;
+void allSeamsListed;
+/** The tokens {@link KernelOverride} may name; any other token is refused when the application is built. */
+export const KERNEL_OVERRIDE_TOKENS = new Set(SEAM_TOKENS);

package/dist/platform/actor.d.ts

@@ -0,0 +1,48 @@
+import { KernelDb } from "../infra/database/kernel-db.js";
+import type { OrgRole } from "../orgs/roles.js";
+import { type OrgSettings } from "../orgs/settings.service.js";
+/** What `availability()` (./availability.ts) decides on, read live for each call (spec §6.1). */
+export interface ActorFacts {
+    /**
+     * The actor's role in the org; null: not a member any more, or the account is disabled (the HTTP
+     * auth refuses a disabled account on every request).
+     */
+    role: OrgRole | null;
+    isSuperAdmin: boolean;
+    /** A person who can see and answer a confirmation is behind this run. */
+    personPresent: boolean;
+    /** The root conversation's agent is `private` and its owner is the actor. */
+    agentPrivateToActor: boolean;
+    /** The org setting `platformTool`. */
+    setting: OrgSettings["platformTool"];
+}
+/**
+ * Reads the facts about the actor of a `Platform` call: the run's trigger account (spec §6.1),
+ * re-read on every call, as the HTTP guards would.
+ *
+ * A person is present when all of these hold:
+ * - there is a run, it belongs to the conversation and its trigger account is the actor;
+ * - the root conversation of the tree (a sub-agent's is followed up through its parents) is a
+ *   `chat` (an `eval` conversation replays, nobody watches it);
+ * - the actor is an active member of the org, and not the org's anonymous guest account (a channel
+ *   message from an unlinked user under the `anonymous` policy runs as that account).
+ *
+ * The agent is private to the actor when the root conversation's agent is `private` and owned by
+ * the actor (a sub-agent's own agent does not count; Platform tool spec §6.1).
+ *
+ * Service tokens cannot start runs (posting a message requires a user principal), so no run is
+ * token-started; a wake run (`budget_run_id` set) runs as the person whose run it continues and
+ * counts as present. No new run column is needed to tell the origins apart.
+ */
+export declare class PlatformActor {
+    private readonly db;
+    constructor(db: KernelDb);
+    facts(ctx: {
+        orgId: string;
+        accountId: string;
+        /** The calling agent (from the runtime, never from the model's input). */
+        agentId: string;
+        conversationId: string;
+        runId?: string | null;
+    }): Promise<ActorFacts>;
+}

package/dist/platform/actor.js

@@ -0,0 +1,100 @@
+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 { KernelDb } from "../infra/database/kernel-db.js";
+import { readOrgSettings } from "../orgs/settings.service.js";
+import { rootConversationOf } from "../runtime/subagents/child.js";
+/**
+ * Reads the facts about the actor of a `Platform` call: the run's trigger account (spec §6.1),
+ * re-read on every call, as the HTTP guards would.
+ *
+ * A person is present when all of these hold:
+ * - there is a run, it belongs to the conversation and its trigger account is the actor;
+ * - the root conversation of the tree (a sub-agent's is followed up through its parents) is a
+ *   `chat` (an `eval` conversation replays, nobody watches it);
+ * - the actor is an active member of the org, and not the org's anonymous guest account (a channel
+ *   message from an unlinked user under the `anonymous` policy runs as that account).
+ *
+ * The agent is private to the actor when the root conversation's agent is `private` and owned by
+ * the actor (a sub-agent's own agent does not count; Platform tool spec §6.1).
+ *
+ * Service tokens cannot start runs (posting a message requires a user principal), so no run is
+ * token-started; a wake run (`budget_run_id` set) runs as the person whose run it continues and
+ * counts as present. No new run column is needed to tell the origins apart.
+ */
+let PlatformActor = class PlatformActor {
+    db;
+    constructor(db) {
+        this.db = db;
+    }
+    async facts(ctx) {
+        const rootId = await rootConversationOf(this.db.db, ctx.conversationId);
+        const [account, settings, root, anonymous, run] = await Promise.all([
+            this.db
+                .selectFrom("accounts")
+                .leftJoin("memberships", (j) => j
+                .onRef("memberships.account_id", "=", "accounts.id")
+                .on("memberships.org_id", "=", ctx.orgId))
+                .select(["accounts.is_super_admin", "accounts.status", "memberships.role"])
+                .where("accounts.id", "=", ctx.accountId)
+                .executeTakeFirst(),
+            readOrgSettings(this.db.db, ctx.orgId),
+            this.db
+                .selectFrom("conversations")
+                .select(["kind", "agent_id"])
+                .where("id", "=", rootId)
+                .where("org_id", "=", ctx.orgId)
+                .executeTakeFirst(),
+            this.db
+                .selectFrom("org_anonymous_accounts")
+                .select("account_id")
+                .where("org_id", "=", ctx.orgId)
+                .where("account_id", "=", ctx.accountId)
+                .executeTakeFirst(),
+            ctx.runId == null
+                ? undefined
+                : this.db
+                    .selectFrom("runs")
+                    .select("trigger_account_id")
+                    .where("id", "=", ctx.runId)
+                    .where("conversation_id", "=", ctx.conversationId)
+                    .executeTakeFirst(),
+        ]);
+        // the super admin's "own private agent" is the tree's root agent: a sub-agent (a template or
+        // general-purpose child) of a shared agent's conversation never counts as private
+        const agentId = rootId === ctx.conversationId ? ctx.agentId : root?.agent_id;
+        const agent = agentId == null
+            ? undefined
+            : await this.db
+                .selectFrom("agents")
+                .select(["owner_account_id", "visibility"])
+                .where("id", "=", agentId)
+                .where("org_id", "=", ctx.orgId)
+                .where("deleted_at", "is", null)
+                .executeTakeFirst();
+        const activeMember = account?.role != null && account.status === "active";
+        return {
+            role: activeMember ? (account?.role ?? null) : null,
+            isSuperAdmin: account?.is_super_admin === true && account.status === "active",
+            // the run is the actor's, in this conversation, and its tree's root is a `chat`
+            personPresent: activeMember &&
+                anonymous === undefined &&
+                run?.trigger_account_id === ctx.accountId &&
+                root?.kind === "chat",
+            agentPrivateToActor: agent?.visibility === "private" && agent.owner_account_id === ctx.accountId,
+            setting: settings.platformTool,
+        };
+    }
+};
+PlatformActor = __decorate([
+    Injectable(),
+    __param(0, Inject(KernelDb))
+], PlatformActor);
+export { PlatformActor };

package/dist/platform/agent-docs.d.ts

@@ -0,0 +1,18 @@
+export interface AgentDocTopic {
+    id: string;
+    title: string;
+}
+/**
+ * The documentation topics the `Platform` tool's `read` action serves (Platform tool spec §8):
+ * the Markdown files of the SDK's `agent-docs` directory, versioned with the contracts they
+ * describe. The files are immutable within a version, so one read per process is a cache of
+ * package files, not shared state.
+ */
+export declare class AgentDocs {
+    private cache;
+    private load;
+    /** Topic ids (path without `.md`, e.g. `extension-points/channel`) with their titles. */
+    topics(): AgentDocTopic[];
+    /** The Markdown of a topic, or null when there is none. */
+    read(id: string): string | null;
+}

package/dist/platform/agent-docs.js

@@ -0,0 +1,59 @@
+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;
+};
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { createRequire } from "node:module";
+import { dirname, join } from "node:path";
+import { Injectable } from "@nestjs/common";
+/** The SDK's `agent-docs` directory, found from the installed `@capybara-hq/plugin-sdk` package. */
+function agentDocsDir() {
+    const pkg = createRequire(import.meta.url).resolve("@capybara-hq/plugin-sdk/package.json");
+    return join(dirname(pkg), "agent-docs");
+}
+function listTopics(dir, prefix = "") {
+    const topics = new Map();
+    if (!existsSync(dir))
+        return topics;
+    for (const e of readdirSync(dir, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))) {
+        if (e.isDirectory()) {
+            for (const [id, text] of listTopics(join(dir, e.name), `${prefix}${e.name}/`)) {
+                topics.set(id, text);
+            }
+        }
+        else if (e.name.endsWith(".md")) {
+            topics.set(`${prefix}${e.name.slice(0, -3)}`, readFileSync(join(dir, e.name), "utf8"));
+        }
+    }
+    return topics;
+}
+/**
+ * The documentation topics the `Platform` tool's `read` action serves (Platform tool spec §8):
+ * the Markdown files of the SDK's `agent-docs` directory, versioned with the contracts they
+ * describe. The files are immutable within a version, so one read per process is a cache of
+ * package files, not shared state.
+ */
+let AgentDocs = class AgentDocs {
+    cache;
+    load() {
+        this.cache ??= listTopics(agentDocsDir());
+        return this.cache;
+    }
+    /** Topic ids (path without `.md`, e.g. `extension-points/channel`) with their titles. */
+    topics() {
+        return [...this.load()].map(([id, text]) => ({
+            id,
+            title: /^#\s+(.+)$/m.exec(text)?.[1]?.trim() ?? id,
+        }));
+    }
+    /** The Markdown of a topic, or null when there is none. */
+    read(id) {
+        return this.load().get(id) ?? null;
+    }
+};
+AgentDocs = __decorate([
+    Injectable()
+], AgentDocs);
+export { AgentDocs };

package/dist/platform/availability.d.ts

@@ -0,0 +1,14 @@
+import type { ActorFacts } from "./actor.js";
+import type { PlatformOperation } from "./operation.js";
+export type Availability = {
+    ok: true;
+} | {
+    ok: false;
+    reason: string;
+};
+/**
+ * Whether the actor may call `op` now (spec §6), decided on facts read at call time. The reason
+ * is model-visible English: it says who can do it or why not, so the agent can offer the next
+ * step (a request operation, the web page, an admin) instead of retrying.
+ */
+export declare function availability(op: PlatformOperation, f: ActorFacts): Availability;

package/dist/platform/availability.js

@@ -0,0 +1,43 @@
+import { ACTION_MIN_ROLE, can } from "../orgs/roles.js";
+/** Who holds a role, as a reason names them. */
+const HOLDER = {
+    guest: "any org member",
+    member: "an org member (not a guest)",
+    admin: "an org admin",
+    owner: "an org owner",
+};
+const refuse = (reason) => ({ ok: false, reason });
+/**
+ * Whether the actor may call `op` now (spec §6), decided on facts read at call time. The reason
+ * is model-visible English: it says who can do it or why not, so the agent can offer the next
+ * step (a request operation, the web page, an admin) instead of retrying.
+ */
+export function availability(op, f) {
+    if (f.role === null) {
+        return refuse("You are not a member of this org any more, or your account is disabled, so no Platform operation is available; ask an org admin to add you back or the super admin to enable your account.");
+    }
+    if (f.setting === "off") {
+        return refuse("The org turned the Platform tool off; an org admin can switch it on in the organization settings.");
+    }
+    if ("superAdmin" in op.authz) {
+        if (!f.isSuperAdmin) {
+            return refuse("Only the super admin can do this; ask them, or use a request operation where one exists.");
+        }
+        if (!f.agentPrivateToActor) {
+            return refuse("Platform-scope operations run only through your own private agent; open a conversation with a private agent you own and do it there.");
+        }
+    }
+    else if (!can(f.role, op.authz.orgAction)) {
+        const min = ACTION_MIN_ROLE[op.authz.orgAction];
+        return refuse(`This needs the ${min} role in the org (you are ${f.role}); ${HOLDER[min]} can do it, or use a request operation where one exists.`);
+    }
+    if (op.confirm !== "read") {
+        if (f.setting === "read-only") {
+            return refuse("The org set the Platform tool to read-only, so writes are unavailable; do it on the web, or ask an org admin to change the setting.");
+        }
+        if (!f.personPresent) {
+            return refuse("This write needs a person to confirm it, and no person is present in this run (a scheduled, evaluation or anonymous run); only read operations are available.");
+        }
+    }
+    return { ok: true };
+}

package/dist/platform/errors.d.ts

@@ -0,0 +1,28 @@
+import { ToolError } from "@capybara-hq/plugin-sdk";
+import type { ActorFacts } from "./actor.js";
+import type { OperationError, OperationErrorNext } from "./operation.js";
+/** What the model is told to do after an operation refused its input (Platform tool spec §5.2). */
+export declare const OPERATION_ERROR_NEXT = "Check the input with describe and call again, or ask the person.";
+/** The role an error's next step is written for (spec §14.5 item 7). */
+export type ErrorRole = "superAdmin" | "orgAdmin" | "member";
+/** The actor's role for next steps: the super admin first, then an org admin (admin or owner). */
+export declare function errorRoleOf(facts: Pick<ActorFacts, "role" | "isSuperAdmin">): ErrorRole;
+/** The next step an operation declares for `code`, for this role; undefined when it has none. */
+export declare function nextStepFor(errors: readonly OperationError[] | undefined, code: string, role: ErrorRole): string | undefined;
+/** One next step resolved for this role (the fallbacks of {@link nextStepFor}). */
+export declare function resolveNext(next: OperationErrorNext | undefined, role: ErrorRole): string | undefined;
+/** `errors[]` as `describe` shows them to this actor: each `next` resolved for the role. */
+export declare function errorsFor(errors: readonly OperationError[], role: ErrorRole): {
+    code: string;
+    next: string;
+}[];
+/**
+ * An error an operation threw, as the `Platform` tool's error for the model (spec §5.2: errors say
+ * what to do next). A `ToolError` passes as is; an `ApiError` (what the same HTTP route would
+ * answer) keeps its code, message and details, then gives the next step: `nextOf(code)` (the
+ * operation's entry for the actor's role), else the generic one. Anything else is a kernel fault,
+ * not the model's: it is rethrown, so the pipeline logs it and reports the generic failure.
+ */
+export declare function toToolError(e: unknown, nextOf?: (code: string) => string | undefined): ToolError;
+/** A text ending with a full stop (`.` added unless it ends with `.`, `!` or `?`). */
+export declare const sentence: (s: string) => string;