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

package/dist/models/purposes.js

@@ -29,7 +29,9 @@ import { ProviderListError, ProviderRegistry } from "../runtime/providers.js";
  * - 用途 = 内核用途 {@link KERNEL_PURPOSES}（目前只有评委 `eval`），或已加载插件 `permissions.models` 声明的；
  * - 映射 = 部署默认（`org_id` 为 null，超级管理员设）+ 组织覆盖（组织管理员设，`org.models.manage`）；
  *   生效的映射先取组织覆盖、再取部署默认，都没有 → `model.unconfigured`；
- * - 目标模型按部署范围解析（与运行时一致），参数按目标模型自己的声明严格校验；不做模型白名单；
+ * - a target's kind must equal the purpose's kind; an org's override must be enabled in the org on
+ *   save (a deployment default: not disabled on the platform), and an effective target disabled in
+ *   the org (by either layer) counts as unconfigured there (spec B §5.3)；参数按目标模型自己的声明严格校验；
  * - 每次都查 PG，不在进程内缓存（多副本下改映射立即生效）。`ctx.models` 仍预留，插件暂不能调用。
  */
 /**
@@ -189,11 +191,17 @@ let ModelPurposesService = class ModelPurposesService {
     async list(orgId) {
         return this.views(this.declared(), orgId);
     }
-    /** 校验目标：模型可解析（部署范围）、参数按它的声明严格通过。 */
-    async check(target) {
+    /**
+     * 校验目标：模型可解析且启用（an org's override for the org, a deployment default in the
+     * platform view）、its kind is the purpose's `kind`、参数按它的声明严格通过。
+     */
+    async check(orgId, target, kind) {
         let info;
         try {
-            ({ info } = await this.providers.resolve(target.model));
+            info =
+                orgId === null
+                    ? await this.providers.platformInfo(target.model, { kind: "callable" })
+                    : (await this.providers.resolve(orgId, target.model, { kind: "callable" })).info;
         }
         catch (e) {
             if (e instanceof ProviderListError)
@@ -203,20 +211,38 @@ let ModelPurposesService = class ModelPurposesService {
             }
             throw e;
         }
+        if (info.kind !== kind) {
+            throw invalid([
+                {
+                    path: "target.model",
+                    message: `this purpose needs ${kind === "embedding" ? "an" : "a"} ${kind} model, not ${info.kind}`,
+                },
+            ]);
+        }
         const issues = paramIssues("target.params", info.parameters, target.params);
         if (issues.length > 0)
             throw invalid(issues);
     }
-    async set(orgId, purpose, target, actor, actorTokenId) {
+    async set(orgId, purpose, target, actor, actorTokenId, auditDetail) {
         const decl = this.find(purpose);
         if (target)
-            await this.check(target);
-        await this.write(orgId, purpose, target, actor, actorTokenId);
+            await this.check(orgId, target, decl.kind);
+        await this.write(orgId, purpose, target, actor, actorTokenId, auditDetail);
         const [view] = await this.views([decl], orgId ?? undefined);
         return view;
     }
+    /**
+     * The checks {@link set} runs before writing, nothing written: an unknown purpose, and a target
+     * model the scope cannot use, of another kind, or with invalid params (the Platform tool's
+     * precheck, so a known failure never reaches the confirmation card).
+     */
+    async validate(orgId, purpose, target) {
+        const decl = this.find(purpose);
+        if (target)
+            await this.check(orgId, target, decl.kind);
+    }
     /** The mapping write of {@link set}, under the super admin or org lock. */
-    async write(orgId, purpose, target, actor, actorTokenId) {
+    async write(orgId, purpose, target, actor, actorTokenId, auditDetail) {
         if (orgId === null)
             await this.adminLock.lockAndAuthorize(actor);
         else
@@ -249,23 +275,48 @@ let ModelPurposesService = class ModelPurposesService {
             ...(orgId !== null && { orgId }),
             action: "model.purpose_mapped",
             target: purpose,
-            detail: { scope: orgId === null ? "deployment" : "org", target },
+            detail: { scope: orgId === null ? "deployment" : "org", target, ...auditDetail },
         });
     }
     /** 设置（或 `null` 清除）部署默认；只有超级管理员（事务内复核）。 */
-    setDefault(purpose, target, actor, actorTokenId) {
-        return this.set(null, purpose, target, actor, actorTokenId);
+    setDefault(purpose, target, actor, actorTokenId, 
+    /** Merged into the audit detail (a write made through the Platform tool). */
+    auditDetail) {
+        return this.set(null, purpose, target, actor, actorTokenId, auditDetail);
     }
     /** 设置（或 `null` 清除）组织覆盖；事务内锁组织并复核 `org.models.manage`。 */
-    setOrg(orgId, purpose, target, actor, actorTokenId) {
-        return this.set(orgId, purpose, target, actor, actorTokenId);
+    setOrg(orgId, purpose, target, actor, actorTokenId, 
+    /** Merged into the audit detail (a write made through the Platform tool). */
+    auditDetail) {
+        return this.set(orgId, purpose, target, actor, actorTokenId, auditDetail);
     }
-    /** 生效的映射：组织覆盖，否则部署默认；都没有 → `model.unconfigured`；用途未声明 → `model.purpose_unknown`。 */
+    /**
+     * 生效的映射：组织覆盖，否则部署默认；都没有 → `model.unconfigured`；用途未声明 → `model.purpose_unknown`。
+     * An effective target the org cannot use counts as unconfigured there (spec B §5.3): checked in
+     * the registry's org view, so a model the platform or the org disabled, a provider off or needing
+     * configuration in the org, a model gone from the org's list or of another kind than the purpose
+     * all give `model.unconfigured`. A provider whose list fails (`ProviderListError`) keeps the
+     * mapping: the call that follows resolves the model again and fails there, retryably, so paths
+     * that only read the mapping (sub-agent tiers, eval start, `ctx.models.describe`) do not fail on
+     * a transient list error.
+     */
     async resolve(orgId, purpose) {
-        const [view] = await this.views([this.find(purpose)], orgId);
+        const decl = this.find(purpose);
+        const [view] = await this.views([decl], orgId);
         if (!view?.effective) {
             throw new ApiError("model.unconfigured", `No model is configured for the "${purpose}" purpose`);
         }
+        try {
+            await this.providers.resolve(orgId, view.effective.model, { kind: decl.kind });
+        }
+        catch (e) {
+            if (e instanceof ProviderListError)
+                return view.effective;
+            if (e instanceof ApiError && e.code === "agent.model_unavailable") {
+                throw new ApiError("model.unconfigured", `The model configured for the "${purpose}" purpose is not available in this organization`);
+            }
+            throw e;
+        }
         return view.effective;
     }
     /** The target a {@link chat} call on `purpose` uses: the mapping, else `fallback` when unmapped. */
@@ -286,7 +337,7 @@ let ModelPurposesService = class ModelPurposesService {
      */
     async chatLimits(orgId, purpose, opts = {}) {
         const target = await this.chatTarget(orgId, purpose, opts.fallback);
-        const { info } = await this.providers.resolve(target.model);
+        const { info } = await this.providers.resolve(orgId, target.model);
         return { contextWindow: info.contextWindow, maxOutputTokens: info.maxOutputTokens };
     }
     /**
@@ -301,7 +352,7 @@ let ModelPurposesService = class ModelPurposesService {
      */
     async chat(orgId, purpose, req, signal, opts = {}) {
         const target = await this.chatTarget(orgId, purpose, opts.fallback);
-        const { provider, info } = await this.providers.resolve(target.model);
+        const { provider, info } = await this.providers.resolve(orgId, target.model);
         const request = {
             ...req,
             model: info.id,

package/dist/orgs/orgs.controller.d.ts

@@ -3,16 +3,13 @@ import { type ApiTokenRecord, ApiTokenService } from "../identity/api-tokens.js"
 import { type Principal } from "../identity/principal.js";
 import { type Member, MembersService } from "./members.service.js";
 import { type OrgContext } from "./org.guard.js";
+import { OrgUpdateBody } from "./orgs.schemas.js";
 import { type Org, OrgsService } from "./orgs.service.js";
 import { type OrgRole } from "./roles.js";
 declare const CreateSchema: z.ZodObject<{
     name: z.ZodString;
     slug: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
-declare const UpdateSchema: z.ZodObject<{
-    name: z.ZodOptional<z.ZodString>;
-    slug: z.ZodOptional<z.ZodString>;
-}, z.core.$strip>;
 declare const TransferSchema: z.ZodObject<{
     toAccountId: z.ZodString;
 }, z.core.$strip>;
@@ -52,7 +49,7 @@ export declare class OrgsController {
         org: Org;
         role: OrgRole;
     }>;
-    update(principal: Principal, org: OrgContext, body: z.infer<typeof UpdateSchema>): Promise<{
+    update(principal: Principal, org: OrgContext, body: z.infer<typeof OrgUpdateBody>): Promise<{
         org: Org;
     }>;
     remove(principal: Principal, org: OrgContext): Promise<void>;

package/dist/orgs/orgs.controller.js

@@ -16,6 +16,7 @@ import { createZodDto } from "../infra/validation/create-zod-dto.js";
 import { ZBody } from "../infra/validation/zod-params.js";
 import { MembersService } from "./members.service.js";
 import { CurrentOrg, OrgAction } from "./org.guard.js";
+import { OrgUpdateBody } from "./orgs.schemas.js";
 import { OrgsService } from "./orgs.service.js";
 import { ORG_ROLES } from "./roles.js";
 const CreateSchema = z.object({
@@ -24,11 +25,7 @@ const CreateSchema = z.object({
 });
 class OrgCreateBody extends createZodDto(CreateSchema, "OrgCreateBody") {
 }
-const UpdateSchema = z.object({
-    name: z.string().min(1).max(100).optional(),
-    slug: z.string().min(1).max(40).optional(),
-});
-class OrgUpdateBody extends createZodDto(UpdateSchema, "OrgUpdateBody") {
+class OrgUpdateBodyDto extends createZodDto(OrgUpdateBody, "OrgUpdateBody") {
 }
 const TransferSchema = z.object({ toAccountId: z.string().min(1) });
 class OrgTransferBody extends createZodDto(TransferSchema, "OrgTransferBody") {
@@ -127,7 +124,7 @@ __decorate([
     OrgAction("org.update"),
     __param(0, CurrentPrincipal()),
     __param(1, CurrentOrg()),
-    __param(2, ZBody(OrgUpdateBody))
+    __param(2, ZBody(OrgUpdateBodyDto))
 ], OrgsController.prototype, "update", null);
 __decorate([
     Delete(":orgId"),

package/dist/orgs/orgs.schemas.d.ts

@@ -0,0 +1,8 @@
+import { z } from "zod";
+import type { RouteSchemas } from "../platform/route-schemas.js";
+export declare const OrgUpdateBody: z.ZodObject<{
+    name: z.ZodOptional<z.ZodString>;
+    slug: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export declare const ORG_ROUTES: readonly RouteSchemas[];
+export declare const ORG_SETTINGS_ROUTES: readonly RouteSchemas[];

package/dist/orgs/orgs.schemas.js

@@ -0,0 +1,16 @@
+import { z } from "zod";
+import { OrgSettingsPatchSchema } from "./settings.service.js";
+export const OrgUpdateBody = z.object({
+    name: z.string().min(1).max(100).optional(),
+    slug: z.string().min(1).max(40).optional(),
+});
+export const ORG_ROUTES = [
+    { route: "GET /api/v1/orgs" },
+    { route: "GET /api/v1/orgs/:orgId" },
+    { route: "PATCH /api/v1/orgs/:orgId", body: OrgUpdateBody },
+    { route: "GET /api/v1/orgs/:orgId/members" },
+];
+export const ORG_SETTINGS_ROUTES = [
+    { route: "GET /api/v1/orgs/:orgId/settings" },
+    { route: "PATCH /api/v1/orgs/:orgId/settings", body: OrgSettingsPatchSchema },
+];

package/dist/orgs/orgs.service.d.ts

@@ -69,7 +69,9 @@ export declare class OrgsService {
     update(orgId: string, patch: {
         name?: string | undefined;
         slug?: string | undefined;
-    }, actor: Account, actorTokenId?: string): Promise<Org>;
+    }, actor: Account, actorTokenId?: string, 
+    /** Merged into the audit detail (the Platform tool's `via: "agent"`). */
+    auditDetail?: Record<string, unknown>): Promise<Org>;
     private updateIn;
     /**
      * Soft delete (needs owner, decided live under the org lock): in the same transaction revokes

package/dist/orgs/orgs.service.js

@@ -178,7 +178,9 @@ let OrgsService = class OrgsService {
         return row && toOrg(row);
     }
     /** Renames / re-slugs (needs admin, decided live under the org lock). */
-    async update(orgId, patch, actor, actorTokenId) {
+    async update(orgId, patch, actor, actorTokenId, 
+    /** Merged into the audit detail (the Platform tool's `via: "agent"`). */
+    auditDetail) {
         const values = {};
         if (patch.name !== undefined)
             values.name = checkName(patch.name);
@@ -186,9 +188,9 @@ let OrgsService = class OrgsService {
             checkSlug(patch.slug);
             values.slug = patch.slug;
         }
-        return slugGuard(this.updateIn(orgId, values, actor, actorTokenId));
+        return slugGuard(this.updateIn(orgId, values, actor, actorTokenId, auditDetail));
     }
-    async updateIn(orgId, values, actor, actorTokenId) {
+    async updateIn(orgId, values, actor, actorTokenId, auditDetail) {
         const { org: before } = await this.orgLock.lockAndAuthorize(orgId, actor.id, "org.update");
         if (Object.keys(values).length === 0) {
             const row = await this.db
@@ -210,7 +212,7 @@ let OrgsService = class OrgsService {
             orgId,
             action: "org.updated",
             target: orgId,
-            detail: { before, after: values },
+            detail: { before, after: values, ...auditDetail },
         });
         return toOrg(row);
     }

package/dist/orgs/settings.service.d.ts

@@ -17,6 +17,8 @@ import { OrgLock } from "./org-lock.js";
  *   见 {@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 declare const ORG_SANDBOX_ALLOW_HOSTS_MAX = 200;
@@ -58,6 +60,7 @@ export declare const OrgSettingsSchema: z.ZodObject<{
         allowHosts: z.ZodOptional<z.ZodArray<z.ZodString>>;
     }, z.core.$strict>>>;
     wakeOnBackgroundTask: z.ZodCatch<z.ZodOptional<z.ZodBoolean>>;
+    timeZone: z.ZodCatch<z.ZodOptional<z.ZodString>>;
 }, z.core.$strip>;
 export type OrgSettings = z.infer<typeof OrgSettingsSchema>;
 /** PATCH 体：只改给出的字段；未知字段 → 400。 */
@@ -87,6 +90,7 @@ export declare const OrgSettingsPatchSchema: z.ZodObject<{
         }>;
         allowHosts: z.ZodOptional<z.ZodArray<z.ZodString>>;
     }, z.core.$strict>>>;
+    timeZone: z.ZodOptional<z.ZodNullable<z.ZodString>>;
 }, z.core.$strict>;
 export type OrgSettingsPatch = z.infer<typeof OrgSettingsPatchSchema>;
 /** 部署的沙箱出站（`sandbox.limits.egress` + `allowHosts`）。 */
@@ -138,6 +142,10 @@ export declare class OrgSettingsService {
     /** 组织实际生效的沙箱 cpu / 内存（只读；由超级管理员在部署设置里覆盖）。 */
     sandboxLimits(orgId: string): Promise<OrgSandboxLimits>;
     get(orgId: string): Promise<OrgSettings>;
-    update(orgId: string, patch: OrgSettingsPatch, actorAccountId: string, actorTokenId?: string): Promise<OrgSettings>;
+    /** The refusals of {@link update} that need no read of the org (the Platform tool's precheck). */
+    check(patch: OrgSettingsPatch): void;
+    update(orgId: string, patch: OrgSettingsPatch, actorAccountId: string, actorTokenId?: string, 
+    /** Merged into the audit detail (the Platform tool's `via: "agent"`). */
+    auditDetail?: Record<string, unknown>): Promise<OrgSettings>;
     private updateIn;
 }

package/dist/orgs/settings.service.js

@@ -17,6 +17,7 @@ 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）。读取宽松：缺失或非法的字段按默认值，未知键保留不动
@@ -30,6 +31,8 @@ import { OrgLock } from "./org-lock.js";
  *   见 {@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;
@@ -64,6 +67,8 @@ export const OrgSettingsSchema = z.object({
     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
@@ -76,6 +81,8 @@ export const OrgSettingsPatchSchema = z
     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();
 /**
@@ -164,14 +171,20 @@ let OrgSettingsService = 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.updateIn(orgId, patch, actorAccountId, actorTokenId);
     }
-    async updateIn(orgId, patch, actorAccountId, actorTokenId) {
+    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")
@@ -189,10 +202,12 @@ let OrgSettingsService = class OrgSettingsService {
             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, ...rest } = stored;
+        const { sandboxEgress: _old, wakeOnBackgroundTask: _oldWake, timeZone: _oldZone, ...rest } = stored;
         await this.db
             .updateTable("orgs")
             .set({ settings: JSON.stringify({ ...rest, ...after }) })
@@ -204,7 +219,7 @@ let OrgSettingsService = class OrgSettingsService {
             orgId,
             action: "org.settings_updated",
             target: orgId,
-            detail: { before, after },
+            detail: { before, after, ...auditDetail },
         });
         return after;
     }

package/dist/overrides.d.ts

@@ -6,6 +6,7 @@ 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";
@@ -25,6 +26,8 @@ import { EMBED_TOKEN_CLOCK } from "./ui/embed-token.js";
  * - `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 {
@@ -40,6 +43,7 @@ interface KernelSeams {
     [SANDBOX_LEASE_TIMINGS]: Partial<SandboxLeaseTimings>;
     [CHANNEL_WEBHOOK_TIMINGS]: Partial<ChannelWebhookTimings>;
     [EMBED_TOKEN_CLOCK]: () => number;
+    [RUN_CONTEXT_CLOCK]: () => number;
     [APP_INTERCEPTOR]: NestInterceptor;
 }
 /**

package/dist/overrides.js

@@ -4,6 +4,7 @@ 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";
@@ -24,6 +25,7 @@ const SEAM_TOKENS = [
     SANDBOX_LEASE_TIMINGS,
     CHANNEL_WEBHOOK_TIMINGS,
     EMBED_TOKEN_CLOCK,
+    RUN_CONTEXT_CLOCK,
     APP_INTERCEPTOR,
 ];
 const allSeamsListed = true;

package/dist/platform/errors.d.ts

@@ -1,11 +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 says what to do next. Anything else is a
- * kernel fault, not the model's: it is rethrown, so the pipeline logs it and reports the generic
- * failure.
+ * 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): ToolError;
+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;

package/dist/platform/errors.js

@@ -4,23 +4,62 @@ import { ApiError } from "../errors.js";
 const DETAILS_MAX = 1000;
 /** What the model is told to do after an operation refused its input (Platform tool spec §5.2). */
 export const OPERATION_ERROR_NEXT = "Check the input with describe and call again, or ask the person.";
+/** The actor's role for next steps: the super admin first, then an org admin (admin or owner). */
+export function errorRoleOf(facts) {
+    if (facts.isSuperAdmin)
+        return "superAdmin";
+    return facts.role === "admin" || facts.role === "owner" ? "orgAdmin" : "member";
+}
+/**
+ * Which keyed texts a role may get, in order. The super admin's text (the admin console path) goes
+ * to the super admin only; an org admin falls back to the member's step and a member to the org
+ * admin's (both name steps inside the org).
+ */
+const FALLBACK = {
+    superAdmin: ["superAdmin", "orgAdmin", "member"],
+    orgAdmin: ["orgAdmin", "member"],
+    member: ["member", "orgAdmin"],
+};
+/** The next step an operation declares for `code`, for this role; undefined when it has none. */
+export function nextStepFor(errors, code, role) {
+    return resolveNext(errors?.find((e) => e.code === code)?.next, role);
+}
+/** One next step resolved for this role (the fallbacks of {@link nextStepFor}). */
+export function resolveNext(next, role) {
+    if (next === undefined || typeof next === "string")
+        return next;
+    for (const r of FALLBACK[role]) {
+        const text = next[r];
+        if (text !== undefined)
+            return text;
+    }
+    return undefined;
+}
+/** `errors[]` as `describe` shows them to this actor: each `next` resolved for the role. */
+export function errorsFor(errors, role) {
+    return errors.flatMap((e) => {
+        const next = nextStepFor(errors, e.code, role);
+        return next === undefined ? [] : [{ code: e.code, next }];
+    });
+}
 /**
  * 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 says what to do next. Anything else is a
- * kernel fault, not the model's: it is rethrown, so the pipeline logs it and reports the generic
- * failure.
+ * 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 function toToolError(e) {
+export function toToolError(e, nextOf) {
     if (e instanceof ToolError)
         return e;
     if (e instanceof ApiError) {
         const details = e.details !== undefined && e.details.length > 0
             ? ` Details: ${clip(JSON.stringify(e.details))}`
             : "";
-        const message = e.message.trim().replace(/[.!]?$/, ".");
-        return new ToolError(`${e.code}: ${message}${details} ${OPERATION_ERROR_NEXT}`);
+        return new ToolError(`${e.code}: ${sentence(e.message)}${details} ${nextOf?.(e.code) ?? OPERATION_ERROR_NEXT}`);
     }
     throw e;
 }
+/** A text ending with a full stop (`.` added unless it ends with `.`, `!` or `?`). */
+export const sentence = (s) => s.trim().replace(/[.!?]?$/, (m) => m || ".");
 const clip = (s) => (s.length > DETAILS_MAX ? `${s.slice(0, DETAILS_MAX)}…` : s);

package/dist/platform/exclusions.d.ts

@@ -1,12 +1,11 @@
-export type ExclusionCategory = "human-only" | "secret" | "transport" | "internal" | "later";
+export type ExclusionCategory = "human-only" | "secret" | "transport" | "internal";
 /**
  * Kernel HTTP routes the `Platform` tool does not mirror, each with a reason (spec §9);
  * `check:platform-ops` fails a route that is neither mirrored by an operation nor listed here.
- * `later` needs an `issue` URL.
+ * Every exclusion is for good: there is no "later" (rule `platform-op-later`).
  */
 export declare const PLATFORM_EXCLUSIONS: readonly {
     route: string;
     category: ExclusionCategory;
     reason: string;
-    issue?: string;
 }[];