@jini-ai/cms 0.3.11 → 0.4.1

package/dist/navigation/tool-registrations.js

@@ -1,3 +1,4 @@
+import { adaptLegacyAuthorize } from "../core/tools/index.js";
 /**
  * @file Navigation's (Menus') half of the agent-tool authorization wiring: maps `agent-tools.ts`'s five
  * catalog entries onto `menu-service.ts`'s read/create/update/assign operations, as
@@ -10,10 +11,11 @@
  * single evaluation for these tools, located where the real route locates it.
  */
 import { ToolInputError } from "@jini-ai/core";
-import { buildDomainRegistrations, indexCatalogById, requireInputRecord, requireNumber, requireString, requireToolPermission, withSchemaOnRejection, } from "../core/tools/registration-kit.js";
+import { buildDomainRegistrations, indexCatalogById, requireInputRecord, requireNumber, requireString, withSchemaOnRejection } from "@jini-ai/core";
+import { requireToolPermission } from "../core/tools/index.js";
 import { menusAgentToolCatalog } from "./agent-tools.js";
 import { assignLocation, createMenu, MenuNotFoundError, MenuValidationError, updateMenuTree } from "./menu-service.js";
-const CATALOG_BY_ID = indexCatalogById(menusAgentToolCatalog);
+const CATALOG_BY_ID = indexCatalogById({ catalog: menusAgentToolCatalog });
 /**
  * This wiring layer's OWN risk classification, authored from what each handler below actually
  * calls. See `DerivedRiskByToolId` in the kit for why it is independent of the catalog's own
@@ -62,65 +64,65 @@ function menusDeps(routeDeps) {
 export function buildMenusRegistrations(routeDeps) {
     const handlers = {
         menus_list_menus: async (ctx) => {
-            await requireToolPermission(routeDeps, { principalId: ctx.principal.id, permission: "admin.menus.read", entityType: "menu" });
+            await requireToolPermission({ authorize: adaptLegacyAuthorize({ authorize: routeDeps.authorize }), workspaceId: routeDeps.workspaceId, principalId: ctx.principal.id, permission: "admin.menus.read" }, { entityType: "menu" });
             const menus = await routeDeps.menuRepo.list({ workspaceId: routeDeps.workspaceId });
             return { menus: menus.map(toMenuToolView) };
         },
         menus_get_menu: async (ctx) => {
-            const menuId = requireString(requireInputRecord(ctx.input), "menuId");
-            await requireToolPermission(routeDeps, { principalId: ctx.principal.id, permission: "admin.menus.read", entityType: "menu", entityId: menuId });
+            const menuId = requireString({ input: requireInputRecord({ input: ctx.input }), key: "menuId" });
+            await requireToolPermission({ authorize: adaptLegacyAuthorize({ authorize: routeDeps.authorize }), workspaceId: routeDeps.workspaceId, principalId: ctx.principal.id, permission: "admin.menus.read" }, { entityType: "menu", entityId: menuId });
             const menu = await routeDeps.menuRepo.findById({ workspaceId: routeDeps.workspaceId, id: menuId });
             if (!menu)
-                throw new MenuNotFoundError(`menu '${menuId}' was not found`);
+                throw new MenuNotFoundError({ message: `menu '${menuId}' was not found` });
             return { menu: toMenuToolView(menu) };
         },
         menus_create_menu: async (ctx) => {
-            const input = requireInputRecord(ctx.input);
-            await requireToolPermission(routeDeps, { principalId: ctx.principal.id, permission: "admin.menus.create", entityType: "menu" });
+            const input = requireInputRecord({ input: ctx.input });
+            await requireToolPermission({ authorize: adaptLegacyAuthorize({ authorize: routeDeps.authorize }), workspaceId: routeDeps.workspaceId, principalId: ctx.principal.id, permission: "admin.menus.create" }, { entityType: "menu" });
             if (input.items !== undefined && !Array.isArray(input.items)) {
-                throw new ToolInputError("'items' must be an array of nav items");
+                throw new ToolInputError({ message: "'items' must be an array of nav items" });
             }
-            return withSchemaOnRejection({ toolId: "menus_create_menu", catalog: CATALOG_BY_ID, isShapeRejection: isMenusShapeRejection }, async () => {
-                const { menu } = await createMenu({
-                    deps: menusDeps(routeDeps),
-                    input: {
-                        workspaceId: routeDeps.workspaceId,
-                        title: requireString(input, "title"),
-                        slug: requireString(input, "slug"),
-                        items: Array.isArray(input.items) ? input.items : undefined,
-                    },
-                });
-                return { menu: toMenuToolView(menu) };
-            });
+            return withSchemaOnRejection({ toolId: "menus_create_menu", catalog: CATALOG_BY_ID, isShapeRejection: ({ error }) => isMenusShapeRejection(error), fn: async () => {
+                    const { menu } = await createMenu({
+                        deps: menusDeps(routeDeps),
+                        input: {
+                            workspaceId: routeDeps.workspaceId,
+                            title: requireString({ input: input, key: "title" }),
+                            slug: requireString({ input: input, key: "slug" }),
+                            items: Array.isArray(input.items) ? input.items : undefined,
+                        },
+                    });
+                    return { menu: toMenuToolView(menu) };
+                } });
         },
         menus_update_menu_tree: async (ctx) => {
-            const input = requireInputRecord(ctx.input);
-            const menuId = requireString(input, "menuId");
-            await requireToolPermission(routeDeps, { principalId: ctx.principal.id, permission: "admin.menus.update", entityType: "menu", entityId: menuId });
+            const input = requireInputRecord({ input: ctx.input });
+            const menuId = requireString({ input: input, key: "menuId" });
+            await requireToolPermission({ authorize: adaptLegacyAuthorize({ authorize: routeDeps.authorize }), workspaceId: routeDeps.workspaceId, principalId: ctx.principal.id, permission: "admin.menus.update" }, { entityType: "menu", entityId: menuId });
             if (!Array.isArray(input.items))
                 throw new Error("'items' (array) is required");
-            return withSchemaOnRejection({ toolId: "menus_update_menu_tree", catalog: CATALOG_BY_ID, isShapeRejection: isMenusShapeRejection }, async () => {
-                const { menu } = await updateMenuTree({
-                    deps: menusDeps(routeDeps),
-                    input: {
-                        workspaceId: routeDeps.workspaceId,
-                        id: menuId,
-                        expectedVersion: requireNumber(input, "expectedVersion"),
-                        title: typeof input.title === "string" ? input.title : undefined,
-                        slug: typeof input.slug === "string" ? input.slug : undefined,
-                        items: input.items,
-                    },
-                });
-                return { menu: toMenuToolView(menu) };
-            });
+            return withSchemaOnRejection({ toolId: "menus_update_menu_tree", catalog: CATALOG_BY_ID, isShapeRejection: ({ error }) => isMenusShapeRejection(error), fn: async () => {
+                    const { menu } = await updateMenuTree({
+                        deps: menusDeps(routeDeps),
+                        input: {
+                            workspaceId: routeDeps.workspaceId,
+                            id: menuId,
+                            expectedVersion: requireNumber({ input: input, key: "expectedVersion" }),
+                            title: typeof input.title === "string" ? input.title : undefined,
+                            slug: typeof input.slug === "string" ? input.slug : undefined,
+                            items: input.items,
+                        },
+                    });
+                    return { menu: toMenuToolView(menu) };
+                } });
         },
         menus_assign_location: async (ctx) => {
-            const input = requireInputRecord(ctx.input);
-            const menuId = requireString(input, "menuId");
-            await requireToolPermission(routeDeps, { principalId: ctx.principal.id, permission: "admin.menus.assign", entityType: "menu", entityId: menuId });
+            const input = requireInputRecord({ input: ctx.input });
+            const menuId = requireString({ input: input, key: "menuId" });
+            await requireToolPermission({ authorize: adaptLegacyAuthorize({ authorize: routeDeps.authorize }), workspaceId: routeDeps.workspaceId, principalId: ctx.principal.id, permission: "admin.menus.assign" }, { entityType: "menu", entityId: menuId });
             const { menu, binding, displacedMenu } = await assignLocation({
                 deps: { ...menusDeps(routeDeps), bindingRepo: routeDeps.navLocationBindingRepo },
-                input: { workspaceId: routeDeps.workspaceId, menuId, locationKey: requireString(input, "locationKey") },
+                input: { workspaceId: routeDeps.workspaceId, menuId, locationKey: requireString({ input: input, key: "locationKey" }) },
             });
             return {
                 menu: toMenuToolView(menu),

package/dist/navigation/types.d.ts

@@ -22,7 +22,7 @@
  * this library introduces; the entries repo, revisions, `entry_refs`, and the command
  * gateway are reused unchanged from the generic entries model.
  */
-import type { ISODateTime, JsonObject, UUID } from "../core/ports.js";
+import type { ISODateTime, JsonObject, UUID } from "@jini-ai/core/primitives";
 /**
  * `menu` ships as a **seeded content-type registry row**, like
  * `post`/`page`/`media`. Core may special-case it in admin UI/rendering, never

package/dist/presentation/presentation.d.ts

@@ -1,4 +1,4 @@
-import type { ClockPort, UUID } from "../core/ports.js";
+import type { Clock, UUID } from "@jini-ai/core/primitives";
 /**
  * @file Presentation settings — the active-theme identity of a workspace.
  *
@@ -22,7 +22,9 @@ export interface PresentationSettingsRecord {
     updatedAt: string;
 }
 export interface PresentationSettingsRepoPort {
-    findByWorkspaceId(workspaceId: UUID): Promise<PresentationSettingsRecord | null>;
+    findByWorkspaceId({ workspaceId }: {
+        workspaceId: UUID;
+    }): Promise<PresentationSettingsRecord | null>;
     save(record: PresentationSettingsRecord): Promise<void>;
     /**
      * Every row across every workspace, for the one-time
@@ -43,7 +45,7 @@ export interface GetPresentationSettingsRequired {
     };
 }
 export interface SetActiveThemeDeps {
-    clock: ClockPort;
+    clock: Clock;
     repo: PresentationSettingsRepoPort;
     /** Discovered valid theme ids; falls back to ALLOWED_THEME_IDS when absent. */
     availableThemeIds?: readonly string[] | undefined;
@@ -58,8 +60,14 @@ export interface SetActiveThemeRequired {
 export interface PresentationOptional {
 }
 export declare class PresentationSettingsNotFoundError extends Error {
+    constructor({ message }: {
+        message: string;
+    }, optionalArgs?: ErrorOptions);
 }
 export declare class PresentationSettingsValidationError extends Error {
+    constructor({ message }: {
+        message: string;
+    }, optionalArgs?: ErrorOptions);
 }
 export declare function getPresentationSettings(required: GetPresentationSettingsRequired, _optional?: PresentationOptional): Promise<{
     settings: PresentationSettingsRecord;

package/dist/presentation/presentation.js

@@ -1,3 +1,4 @@
+import { nowIso as kernelNowIso } from "@jini-ai/core/primitives";
 /**
  * @file Presentation settings — the active-theme identity of a workspace.
  *
@@ -14,13 +15,19 @@
  */
 export const ALLOWED_THEME_IDS = ["paper", "atlas", "glassmorphic"];
 export class PresentationSettingsNotFoundError extends Error {
+    constructor({ message }, optionalArgs = {}) {
+        super(message, optionalArgs);
+    }
 }
 export class PresentationSettingsValidationError extends Error {
+    constructor({ message }, optionalArgs = {}) {
+        super(message, optionalArgs);
+    }
 }
 export async function getPresentationSettings(required, _optional = {}) {
-    const settings = await required.deps.repo.findByWorkspaceId(required.input.workspaceId);
+    const settings = await required.deps.repo.findByWorkspaceId({ workspaceId: required.input.workspaceId });
     if (!settings) {
-        throw new PresentationSettingsNotFoundError(`presentation settings for workspace '${required.input.workspaceId}' were not found`);
+        throw new PresentationSettingsNotFoundError({ message: `presentation settings for workspace '${required.input.workspaceId}' were not found` });
     }
     return {
         settings,
@@ -31,16 +38,16 @@ export async function setActiveTheme(required, _optional = {}) {
     const { deps, input } = required;
     const allowed = deps.availableThemeIds ?? ALLOWED_THEME_IDS;
     if (!allowed.includes(input.activeThemeId)) {
-        throw new PresentationSettingsValidationError(`theme '${input.activeThemeId}' is not supported`);
+        throw new PresentationSettingsValidationError({ message: `theme '${input.activeThemeId}' is not supported` });
     }
-    const existing = await deps.repo.findByWorkspaceId(input.workspaceId);
+    const existing = await deps.repo.findByWorkspaceId({ workspaceId: input.workspaceId });
     if (!existing) {
-        throw new PresentationSettingsNotFoundError(`presentation settings for workspace '${input.workspaceId}' were not found`);
+        throw new PresentationSettingsNotFoundError({ message: `presentation settings for workspace '${input.workspaceId}' were not found` });
     }
     const settings = {
         ...existing,
         activeThemeId: input.activeThemeId,
-        updatedAt: deps.clock.nowIso(),
+        updatedAt: kernelNowIso({ clock: deps.clock }),
     };
     await deps.repo.save(settings);
     return {

package/dist/presentation/repo.memory.d.ts

@@ -1,8 +1,12 @@
 import type { PresentationSettingsRecord, PresentationSettingsRepoPort } from "./presentation.js";
 export declare class InMemoryPresentationSettingsRepo implements PresentationSettingsRepoPort {
     private rows;
-    constructor(initialRows?: PresentationSettingsRecord[]);
-    findByWorkspaceId(workspaceId: string): Promise<PresentationSettingsRecord | null>;
+    constructor(requiredArgs: Record<string, never>, optionalArgs?: {
+        initialRows?: PresentationSettingsRecord[];
+    });
+    findByWorkspaceId({ workspaceId }: {
+        workspaceId: string;
+    }): Promise<PresentationSettingsRecord | null>;
     save(record: PresentationSettingsRecord): Promise<void>;
     listAll(): Promise<PresentationSettingsRecord[]>;
 }

package/dist/presentation/repo.memory.js

@@ -1,9 +1,10 @@
 export class InMemoryPresentationSettingsRepo {
     rows;
-    constructor(initialRows = []) {
+    constructor(requiredArgs, optionalArgs = {}) {
+        const { initialRows = [] } = optionalArgs;
         this.rows = [...initialRows];
     }
-    async findByWorkspaceId(workspaceId) {
+    async findByWorkspaceId({ workspaceId }) {
         return this.rows.find((row) => row.workspaceId === workspaceId) ?? null;
     }
     async save(record) {

package/dist/settings/agent-tools.d.ts

@@ -1,79 +1,6 @@
+import type { AgentToolDefinition } from "@jini-ai/core";
 /**
- * @file The Settings domain's agent-tool catalog, instantiating the naming/callability
- * convention every other domain catalog in this package already uses.
- *
- * Purpose:
- * A static, in-process catalog describing every agent-callable tool this domain exposes. Settings
- * is, by design, a broad key/value surface — a typical human admin screen for it is an uncurated,
- * free-text editor: the operator types ANY namespace string to load it and edits values through a
- * raw-JSON textarea, with no schema-exposing endpoint feeding a typed control. There is no fixed,
- * curated list of named settings on that surface to wire tools against.
- *
- * That disqualifies every GENERIC write in this domain from being wired here:
- * - `SETTINGS_SET`/`SETTINGS_CLEAR` let a caller write/clear the value of any registered
- *   namespace+key at any scope it can name — exactly the generic "set any setting key" tool this
- *   dispatch's brief prohibits outright, regardless of the write path's own schema validation
- *   (validation constrains VALUE shape, not WHICH key can be targeted).
- *
- * One curated write IS wired, and it is not a weaker `settings_set`: `ui-tab-definitions.ts`
- * registers a fixed, statically-declared list, because the settings-dialog tabs need named keys to
- * bind to. `SETTINGS_SET_UI_PREFERENCE` below wires a seven-key subset of that list
- * (`agent-writable-preferences.ts`):
- *
- * - Its `setting` parameter is a JSON Schema `enum`, so WHICH key is targeted is constrained by
- *   the same mechanism as everything else — the exact gap the paragraph above identifies. The
- *   ledger's registered definition schema still bounds the VALUE, so both halves are covered.
- * - It exposes no `scope` and no `principalId`. Every write is `scope: "user"` against the
- *   caller's own principal, which derives `settings.user.self.write` — the narrowest write grant
- *   in the system — and makes writing another operator's preferences unrepresentable rather than
- *   merely unauthorized.
- * - The keys are per-operator display preferences (locale, theme, accent, notification sounds),
- *   each reversible in one call and visible in the admin UI the moment it changes.
- *
- * The generic setter stays excluded, permanently and for its original reason. Nothing above is
- * evidence that the other three writes may now be wired:
- * - `SETTINGS_RESET` is broader still: a single call clears every value in an operator-named
- *   namespace at a scope — typically described in a host's own confirmation dialog as
- *   irreversible.
- * - `SETTINGS_REGISTER_DEFINITIONS` is schema-level, not value-level: it can rename/retype/
- *   deprecate/tombstone the DEFINITION a key resolves through, changing how every existing stored
- *   value for that key is interpreted platform-wide.
- *
- * Reads are a different risk class and are wired: `SETTINGS_LIST_DEFINITIONS`/
- * `SETTINGS_GET_EFFECTIVE`/`SETTINGS_GET_RAW` cannot mutate anything, are gated by the same real
- * `authorize()` permissions an admin UI's own reads use (including the cross-principal
- * `settings.user.read` check), and cannot surface a secret value even in principle —
- * `settings.ts`'s `validateDefinitionInput` unconditionally refuses `secret:true` at registration
- * time (REQ-09/INV-08), so no secret setting can exist in this library's current state to leak.
- *
- * How it relates to a host:
- * A host's tool-registration layer consumes this catalog to decide which tool names an agent
- * session may even see; `authorize()` enforces the actual permission checks at call time — this
- * module only declares the catalog shape, it performs no I/O and no enforcement itself.
- *
- * Architectural role:
- * `settings` domain logic. Depends only on its own sibling `agent-writable-preferences.ts` (for
- * the curated write's enum) — no I/O, no enforcement.
- */
-export type AgentToolSideEffect = "none" | "mutates-durable-state" | "mints-token";
-export interface AgentToolDefinition {
-    name: string;
-    description: string;
-    sideEffects: AgentToolSideEffect;
-    authorization: {
-        permission: string;
-    };
-    /**
-     * JSON Schema for this tool's `input`, published to the model via `ToolDescriptor.inputSchema`
-     * (a host's tool-registration layer refuses to wire any tool lacking one). Optional — the four
-     * write entries this file documents but never wires (see file header) carry no schema at all,
-     * since one is never published for a tool the model never sees.
-     */
-    inputSchema?: Readonly<Record<string, unknown>>;
-}
-/**
- * The Settings domain's fixed agent-tool catalog — the three reads, one curated write
- * (`settings_set_ui_preference`), and four generic writes documented but deliberately never
+ * The Settings domain's fixed agent-tool catalog — three reads, three bounded writes, and two bulk/schema writes documented but never
  * wired. See file header.
  *
  * @complexity O(1) — a fixed, statically-defined list.

package/dist/settings/agent-tools.js

@@ -9,54 +9,47 @@
  * raw-JSON textarea, with no schema-exposing endpoint feeding a typed control. There is no fixed,
  * curated list of named settings on that surface to wire tools against.
  *
- * That disqualifies every GENERIC write in this domain from being wired here:
- * - `SETTINGS_SET`/`SETTINGS_CLEAR` let a caller write/clear the value of any registered
- *   namespace+key at any scope it can name — exactly the generic "set any setting key" tool this
- *   dispatch's brief prohibits outright, regardless of the write path's own schema validation
- *   (validation constrains VALUE shape, not WHICH key can be targeted).
+ * The original generic-write exclusion correctly observed that schema validation bounds VALUE
+ * shape, not WHICH key may be targeted. The owner reversed permanent exclusion on 2026-10-01:
+ * settings_set_value/settings_clear_value now address one registered workspace or caller-owned
+ * user override. Explicit key policy bounds the target; privacy consent and the assistant's own
+ * instructions require a HUMAN confirmation port (the agent cannot self-confirm). Hosts add
+ * runtime/permission policies through the same seam. Headless protected writes fail closed.
+ * Ordinary settings apply directly and remain undoable using the returned previous override.
  *
- * One curated write IS wired, and it is not a weaker `settings_set`: `ui-tab-definitions.ts`
- * registers a fixed, statically-declared list, because the settings-dialog tabs need named keys to
- * bind to. `SETTINGS_SET_UI_PREFERENCE` below wires a seven-key subset of that list
- * (`agent-writable-preferences.ts`):
+ * settings_set_ui_preference remains the fixed seven-key, caller-only display-preference surface.
+ * It cannot reach consent or standing instructions; use the generic tools and a human card there.
  *
- * - Its `setting` parameter is a JSON Schema `enum`, so WHICH key is targeted is constrained by
- *   the same mechanism as everything else — the exact gap the paragraph above identifies. The
- *   ledger's registered definition schema still bounds the VALUE, so both halves are covered.
- * - It exposes no `scope` and no `principalId`. Every write is `scope: "user"` against the
- *   caller's own principal, which derives `settings.user.self.write` — the narrowest write grant
- *   in the system — and makes writing another operator's preferences unrepresentable rather than
- *   merely unauthorized.
- * - The keys are per-operator display preferences (locale, theme, accent, notification sounds),
- *   each reversible in one call and visible in the admin UI the moment it changes.
- *
- * The generic setter stays excluded, permanently and for its original reason. Nothing above is
- * evidence that the other three writes may now be wired:
- * - `SETTINGS_RESET` is broader still: a single call clears every value in an operator-named
- *   namespace at a scope — typically described in a host's own confirmation dialog as
- *   irreversible.
- * - `SETTINGS_REGISTER_DEFINITIONS` is schema-level, not value-level: it can rename/retype/
- *   deprecate/tombstone the DEFINITION a key resolves through, changing how every existing stored
- *   value for that key is interpreted platform-wide.
+ * The broader operations remain excluded:
+ * - SETTINGS_RESET clears every value in a namespace at once, an irreversible bulk operation.
+ * - SETTINGS_REGISTER_DEFINITIONS can retype/rename/tombstone definitions and reinterpret values
+ * platform-wide. Neither gets wired by the value-write decision.
  *
  * Reads are a different risk class and are wired: `SETTINGS_LIST_DEFINITIONS`/
  * `SETTINGS_GET_EFFECTIVE`/`SETTINGS_GET_RAW` cannot mutate anything, are gated by the same real
- * `authorize()` permissions an admin UI's own reads use (including the cross-principal
+ * `authorize` permissions an admin UI's own reads use (including the cross-principal
  * `settings.user.read` check), and cannot surface a secret value even in principle —
  * `settings.ts`'s `validateDefinitionInput` unconditionally refuses `secret:true` at registration
- * time (REQ-09/INV-08), so no secret setting can exist in this library's current state to leak.
+ * time, so no secret setting can exist in this library's current state to leak.
  *
  * How it relates to a host:
  * A host's tool-registration layer consumes this catalog to decide which tool names an agent
- * session may even see; `authorize()` enforces the actual permission checks at call time — this
+ * session may even see; `authorize` enforces the actual permission checks at call time — this
  * module only declares the catalog shape, it performs no I/O and no enforcement itself.
  *
  * Architectural role:
  * `settings` domain logic. Depends only on its own sibling `agent-writable-preferences.ts` (for
  * the curated write's enum) — no I/O, no enforcement.
+ * See docs/decisions/DR-003-settings-ledger-invariants.md.
  */
 import { AGENT_WRITABLE_PREFERENCE_IDS, AGENT_WRITABLE_PREFERENCES } from "./agent-writable-preferences.js";
-/** No arguments — `settings_list_definitions` takes none; it always enumerates the caller's own
+/**
+   * JSON Schema for this tool's `input`, published to the model via `ToolDescriptor.inputSchema`
+   * (a host's tool-registration layer refuses to wire any tool lacking one). Optional — the two bulk/schema
+   * write entries this file documents but never wires (see file header) carry no schema at all,
+   * since one is never published for a tool the model never sees.
+   *
+ * No arguments — `settings_list_definitions` takes none; it always enumerates the caller's own
  * (boot-wired) workspace's site-owned partition plus the shared platform partition. */
 const NO_INPUT_SCHEMA = {
     type: "object",
@@ -118,9 +111,24 @@ const SET_UI_PREFERENCE_SCHEMA = {
         },
     },
 };
+/** Both generic writes target only this workspace or the caller's own user layer. */
+const CLEAR_VALUE_SCHEMA = {
+    type: "object",
+    additionalProperties: false,
+    required: ["namespace", "key"],
+    properties: {
+        namespace: { type: "string", minLength: 1, description: "A registered settings namespace; call settings_list_definitions first." },
+        key: { type: "string", minLength: 1, description: "A registered key inside the namespace." },
+        scope: { type: "string", enum: ["workspace", "user"], default: "workspace", description: "Workspace override, or only the calling operator's own user override." },
+    },
+};
+const SET_VALUE_SCHEMA = {
+    ...CLEAR_VALUE_SCHEMA,
+    required: ["namespace", "key", "value"],
+    properties: { ...CLEAR_VALUE_SCHEMA.properties, value: { description: "Any JSON matching the definition schema returned by settings_list_definitions." } },
+};
 /**
- * The Settings domain's fixed agent-tool catalog — the three reads, one curated write
- * (`settings_set_ui_preference`), and four generic writes documented but deliberately never
+ * The Settings domain's fixed agent-tool catalog — three reads, three bounded writes, and two bulk/schema writes documented but never
  * wired. See file header.
  *
  * @complexity O(1) — a fixed, statically-defined list.
@@ -130,7 +138,7 @@ export function getSettingsAgentToolCatalog() {
     return [
         {
             name: "settings_list_definitions",
-            description: "Lists every active setting definition visible to this workspace (platform core/theme definitions plus this workspace's own site-owned definitions): namespace, key, owner kind, scope bitmask, status, and version. Metadata only — never a value.",
+            description: "Lists every active setting definition visible to this workspace (platform core/theme definitions plus this workspace's own site-owned definitions): namespace, key, owner kind, scope bitmask, status, version, schema, agentWritable and confirmationRequired. Use before writing a setting. Metadata only — never a value.",
             sideEffects: "none",
             authorization: { permission: "settings.read.definitions" },
             inputSchema: NO_INPUT_SCHEMA,
@@ -161,25 +169,21 @@ export function getSettingsAgentToolCatalog() {
             inputSchema: SET_UI_PREFERENCE_SCHEMA,
         },
         {
-            // EXCLUDED BY DESIGN, never wired: see this file's header. Generic "set any setting key" —
-            // a typical human admin UI for this domain is an uncurated free-text/raw-JSON editor, not a
-            // fixed named list. `settings_set_ui_preference` above is the curated alternative and does
-            // NOT make this one wireable: the whole difference is that its target key is enum-bounded.
-            name: "settings_set",
-            description: "Sets a setting's value at a scope. NEVER agent-callable — see file header.",
+            name: "settings_set_value",
+            description: "Sets one registered setting at workspace scope (default) or the caller's own user scope. Call settings_list_definitions for valid keys, schemas, scopes and confirmation policy. Returns {key, scope, previous, value, revisionSeq}; previous is the old override, or null if absent. Privacy, instructions and host-protected assistant settings need a human confirmation card; the agent cannot confirm itself. Rejects unknown/tombstoned keys, disallowed scopes, invalid values and missing permissions. Cannot write globally, target another operator, reset a namespace or change definitions.",
             sideEffects: "mutates-durable-state",
             authorization: { permission: "settings.workspace.write" },
+            inputSchema: SET_VALUE_SCHEMA,
         },
         {
-            // EXCLUDED BY DESIGN, never wired: see this file's header. Same "generic key" exclusion as
-            // settings_set.
-            name: "settings_clear",
-            description: "Clears a setting's value at a scope, reverting it to default. NEVER agent-callable — see file header.",
+            name: "settings_clear_value",
+            description: "Clears one setting override at workspace scope (default) or the caller's own user scope so the next layer/default applies. Use to put one setting back to its inherited value; not to reset a namespace or delete a definition. Returns {key, scope, previous, effective}; restore a non-null previous override with settings_set_value. Protected assistant settings require a human confirmation card. Rejects unknown/tombstoned keys, disallowed scopes and missing permissions; cannot target global or another operator's layer.",
             sideEffects: "mutates-durable-state",
             authorization: { permission: "settings.workspace.write" },
+            inputSchema: CLEAR_VALUE_SCHEMA,
         },
         {
-            // EXCLUDED BY DESIGN, never wired: see this file's header. Bulk variant of settings_clear —
+            // EXCLUDED BY DESIGN, never wired: see this file's header. Bulk variant of a single-value clear —
             // clears every value in an operator-named namespace at a scope in one call, irreversible.
             name: "settings_reset",
             description: "Resets every setting in a namespace to defaults at a scope. NEVER agent-callable — see file header.",

package/dist/settings/agent-value-write-tools.d.ts

@@ -0,0 +1,22 @@
+import { type ToolExecutionContext, type ToolHandler } from "@jini-ai/core";
+import type { JsonValue } from "@jini-ai/core/primitives";
+import type { SettingsToolDeps } from "./tool-registrations.js";
+export type SettingsValueWriteToolId = "settings_set_value" | "settings_clear_value";
+/** Host-only port. This request is never an agent input and only the host's authenticated
+ * human transport may answer it. Returning true without a human violates this contract. */
+export interface SettingsWriteConfirmation {
+    ctx: ToolExecutionContext;
+    toolId: SettingsValueWriteToolId;
+    namespace: string;
+    key: string;
+    scope: "workspace" | "user";
+    previous: JsonValue | null;
+    value?: JsonValue;
+    reason: string;
+}
+/** Builds one value-write handler. Effects: authorize -> raw read -> optional human card ->
+ * service write -> result. The service rechecks authorization and performs its normal transaction.
+ * @complexity O(value size + rule count) plus bounded repository calls and a human wait.
+ * @throws ToolInputError for invalid input, denied keys, absent/declined/stale confirmation. */
+export declare function buildSettingsValueWriteHandler(deps: SettingsToolDeps, toolId: SettingsValueWriteToolId): ToolHandler;
+//# sourceMappingURL=agent-value-write-tools.d.ts.map