@jini-ai/cms 0.5.4 → 0.5.5

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

@@ -1,10 +0,0 @@
-import type { AgentToolDefinition } from "@jini-ai/core";
-/**
- * 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.
- * @overallScore 100
- */
-export declare function getSettingsAgentToolCatalog(): AgentToolDefinition[];
-//# sourceMappingURL=agent-tools.d.ts.map

package/dist/settings/agent-tools.js

@@ -1,204 +0,0 @@
-/**
- * @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.
- *
- * 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.
- *
- * 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.
- *
- * 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
- * `settings.user.read` check), and cannot surface a secret value even in principle —
- * `settings.ts`'s `validateDefinitionInput` unconditionally refuses `secret:true` at registration
- * 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
- * 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";
-/**
-   * 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",
-    additionalProperties: false,
-    required: [],
-    properties: {},
-};
-/** Shared by `settings_get_effective`/`settings_get_raw`: naming a DIFFERENT principal than the
- * caller requires `settings.user.read` (checked by the handler, not expressed in this schema). */
-const PRINCIPAL_ID_PROPERTY = {
-    type: "string",
-    description: "Read another principal's user-layer value instead of the caller's own. Requires the settings.user.read permission when it names a principal other than the caller. Omit to read the caller's own user layer.",
-};
-const GET_EFFECTIVE_SCHEMA = {
-    type: "object",
-    additionalProperties: false,
-    required: ["namespace"],
-    properties: {
-        namespace: { type: "string", minLength: 1, description: "The settings namespace to enumerate, e.g. 'core.presentation'." },
-        principalId: PRINCIPAL_ID_PROPERTY,
-    },
-};
-const GET_RAW_SCHEMA = {
-    type: "object",
-    additionalProperties: false,
-    required: ["namespace", "key"],
-    properties: {
-        namespace: { type: "string", minLength: 1, description: "The settings namespace the key belongs to, e.g. 'core.presentation'." },
-        key: { type: "string", minLength: 1, description: "The setting key within the namespace." },
-        principalId: PRINCIPAL_ID_PROPERTY,
-    },
-};
-/**
- * Input schema for `settings_set_ui_preference`.
- *
- * The `enum` on `setting` is the load-bearing part and the reason this tool is wireable at all —
- * it is what makes "which key" a schema-constrained choice rather than free text. Built from
- * {@link AGENT_WRITABLE_PREFERENCE_IDS} rather than listed here, so the published schema and the
- * handler's own allowlist check cannot disagree.
- *
- * `value` is typed only as "present". Constraining it here would mean restating seven different
- * per-key schemas that the ledger already holds and already enforces inside the write chokepoint
- * (`write-service.ts`'s `set()`), and a second copy that drifts is worse than no copy: it would
- * reject values the ledger accepts, or — far worse — describe as acceptable a shape the ledger
- * will refuse. The per-key hints below tell the model what to send; the ledger decides.
- */
-const SET_UI_PREFERENCE_SCHEMA = {
-    type: "object",
-    additionalProperties: false,
-    required: ["setting", "value"],
-    properties: {
-        setting: {
-            type: "string",
-            enum: AGENT_WRITABLE_PREFERENCE_IDS,
-            description: `The preference to set. Legal values and what each expects: ${AGENT_WRITABLE_PREFERENCES.map((p) => `${p.id} — ${p.valueHint}`).join(" | ")}`,
-        },
-        value: {
-            description: "The new value, matching the shape described for the chosen setting. Validated against that setting's registered schema; a mismatch is rejected and nothing is written.",
-        },
-    },
-};
-/** 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 — 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.
- * @overallScore 100
- */
-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, 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,
-        },
-        {
-            name: "settings_get_effective",
-            description: "Returns the effective (precedence-resolved: user, then workspace, then global, then default) value of every active setting registered in a namespace.",
-            sideEffects: "none",
-            authorization: { permission: "settings.read" },
-            inputSchema: GET_EFFECTIVE_SCHEMA,
-        },
-        {
-            name: "settings_get_raw",
-            description: "Returns the per-layer raw values (global, workspace, user, default) of one setting key, unresolved by precedence.",
-            sideEffects: "none",
-            authorization: { permission: "settings.read.raw" },
-            inputSchema: GET_RAW_SCHEMA,
-        },
-        {
-            name: "settings_set_ui_preference",
-            description: "Sets one of the operator's own admin-UI preferences (interface language, theme, accent color, or notification sounds) and returns the stored value. Writes only to the calling operator's own user layer — it cannot target another operator, another scope, or any setting outside its fixed list. Use settings_get_effective to read current values first.",
-            sideEffects: "mutates-durable-state",
-            // The narrowest write grant in the system, and it is what this tool derives BECAUSE it never
-            // names a target principal (`write-service.ts`'s `deriveRequiredPermission`). Declared here
-            // to match; the handler does not pass this string, it lets the chokepoint derive it, so the
-            // two cannot drift into a state where this file advertises a check that is not the one run.
-            authorization: { permission: "settings.user.self.write" },
-            inputSchema: SET_UI_PREFERENCE_SCHEMA,
-        },
-        {
-            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,
-        },
-        {
-            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 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.",
-            sideEffects: "mutates-durable-state",
-            authorization: { permission: "settings.reset.workspace" },
-        },
-        {
-            // EXCLUDED BY DESIGN, never wired: see this file's header. Schema-level, not value-level —
-            // can rename/retype/deprecate/tombstone the definition a key resolves through, changing how
-            // every existing stored value for that key is interpreted platform-wide.
-            name: "settings_register_definitions",
-            description: "Registers, renames, retypes, deprecates, or tombstones setting definitions. NEVER agent-callable — see file header.",
-            sideEffects: "mutates-durable-state",
-            authorization: { permission: "settings.definitions.manage" },
-        },
-    ];
-}
-//# sourceMappingURL=agent-tools.js.map

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

@@ -1,22 +0,0 @@
-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

package/dist/settings/agent-value-write-tools.js

@@ -1,154 +0,0 @@
-import { adaptLegacyAuthorize } from "../core/tools/index.js";
-import { ToolInputError } from "@jini-ai/core";
-import { ForbiddenError as PermissionDeniedError } from "../core/commands/command.js";
-import { requireToolPermission } from "../core/tools/index.js";
-import { AGENT_WRITE_CONFIRMATION_SETTINGS, AGENT_WRITE_DENIED_SETTINGS, findAgentWriteRule } from "./agent-write-denylist.js";
-import { DefinitionNotFoundError, DefinitionTombstonedError, ForbiddenError, ScopeNotAllowedError, ValueValidationFailedError } from "./errors.js";
-import { getEffective, resolveDefinitionRaw, validateValueAgainstSchema } from "./settings.js";
-import { SCOPE_BIT } from "./types.js";
-import { clear, deriveRequiredPermission, set } from "./write-service.js";
-/** Strict boundary, including direct handler calls. JSON is cloned before the first await
- * so a held-open card cannot consent to a value later changed by the caller. O(input size). */
-function parseTarget(toolId, raw) {
-    if (!raw || typeof raw !== "object" || Array.isArray(raw))
-        throw new ToolInputError({ message: `${toolId}: input must be an object containing namespace and key.` });
-    const input = raw;
-    const fields = toolId === "settings_set_value" ? ["namespace", "key", "value", "scope"] : ["namespace", "key", "scope"];
-    const extra = Object.keys(input).find((key) => !fields.includes(key));
-    if (extra)
-        throw new ToolInputError({ message: `${toolId}: unexpected input '${extra}'. Only ${fields.join(", ")} are accepted; the caller's own user layer is the only user target.` });
-    for (const field of ["namespace", "key"]) {
-        if (typeof input[field] !== "string" || !input[field].trim())
-            throw new ToolInputError({ message: `${toolId}: '${field}' must be a non-empty string. Call settings_list_definitions to see valid keys.` });
-    }
-    const namespace = input.namespace;
-    const key = input.key;
-    const scope = input.scope === undefined ? "workspace" : input.scope;
-    if (scope !== "workspace" && scope !== "user")
-        throw new ToolInputError({ message: `${toolId}: scope must be 'workspace' or 'user'; global settings are not writable by this tool.` });
-    if (toolId === "settings_clear_value")
-        return { namespace, key, scope };
-    if (!("value" in input))
-        throw new ToolInputError({ message: `${toolId}: a JSON 'value' is required.` });
-    // The executor validates JSON input too. The round trip protects direct callers and isolates
-    // the snapshot; values JSON would silently change (NaN, undefined, functions) are rejected.
-    let serialized;
-    try {
-        serialized = JSON.stringify(input.value, (_key, value) => {
-            if (value === undefined || typeof value === "function" || typeof value === "symbol" || (typeof value === "number" && !Number.isFinite(value)))
-                throw new Error("not JSON");
-            return value;
-        });
-    }
-    catch {
-        throw new ToolInputError({ message: `${toolId}: value must be valid JSON.` });
-    }
-    if (serialized === undefined)
-        throw new ToolInputError({ message: `${toolId}: value must be valid JSON.` });
-    return { namespace, key, scope, value: JSON.parse(serialized) };
-}
-/** Definition/scope/value preflight for readable refusal before any card. O(1) repository
- * lookups plus alias resolution and schema validation, with no writes. */
-async function resolveTarget(deps, target, isSet) {
-    const definition = await resolveDefinitionRaw({ repo: deps.settingsRepo }, { namespace: target.namespace, key: target.key, workspaceId: deps.workspaceId });
-    const name = `${target.namespace}.${target.key}`;
-    if (!definition)
-        throw new DefinitionNotFoundError(`setting '${name}' was not found`);
-    if (definition.status === "tombstone")
-        throw new DefinitionTombstonedError(`setting '${name}' has been tombstoned`);
-    if ((definition.scopes & SCOPE_BIT[target.scope]) === 0)
-        throw new ScopeNotAllowedError(name);
-    if (isSet && !validateValueAgainstSchema(definition.schema, target.value))
-        throw new ValueValidationFailedError(`value for '${name}' does not match the definition schema`);
-    return definition;
-}
-/** Reads exactly the override being changed, never an effective value or another principal.
- * One repository read, O(1) outside adapter cost. */
-function readLayer(deps, target, settingId, principalId) {
-    const base = { workspaceId: deps.workspaceId, settingId };
-    return target.scope === "user" ? deps.settingsRepo.getUserValue({ ...base, principalId }) : deps.settingsRepo.getWorkspaceValue(base);
-}
-/** Fail closed on host-denied keys, including a protected target reached through an alias.
- * Returns a confirmation rule if either coordinate needs one; O(r) in fixed policy rules. */
-function writePolicy(deps, toolId, target, definition) {
-    const targets = definition ? [target, definition] : [target];
-    const denied = [...AGENT_WRITE_DENIED_SETTINGS, ...(deps.extraDeniedSettings ?? [])];
-    for (const coordinate of targets) {
-        const rule = findAgentWriteRule(denied, coordinate);
-        if (rule)
-            throw new ToolInputError({ message: `${toolId}: '${coordinate.namespace}.${coordinate.key}' can't be changed by the assistant: ${rule.reason}. The owner can change it in Settings.` });
-    }
-    const confirmation = [...AGENT_WRITE_CONFIRMATION_SETTINGS, ...(deps.extraConfirmationSettings ?? [])];
-    for (const coordinate of targets) {
-        const rule = findAgentWriteRule(confirmation, coordinate);
-        if (rule)
-            return { ...rule, namespace: coordinate.namespace, key: coordinate.key };
-    }
-    return undefined;
-}
-/** Maps expected caller-fixable errors; infrastructure failures remain untouched. O(1). */
-function rethrowWriteError(error, toolId, target, permission) {
-    if (error instanceof DefinitionNotFoundError || error instanceof DefinitionTombstonedError)
-        throw new ToolInputError({ message: `${toolId}: ${error.message}. Call settings_list_definitions to see valid keys.` });
-    if (error instanceof ScopeNotAllowedError)
-        throw new ToolInputError({ message: `${toolId}: '${target.namespace}.${target.key}' can't be set ${target.scope === "user" ? "per-user" : "at workspace scope"}. Call settings_list_definitions to see allowed scopes.` });
-    if (error instanceof ValueValidationFailedError)
-        throw new ToolInputError({ message: `${toolId}: ${error.message}. Call settings_list_definitions and use a value matching the setting's schema.` });
-    if (error instanceof ForbiddenError || error instanceof PermissionDeniedError)
-        throw new ToolInputError({ message: `${toolId}: permission '${permission}' is required. Ask the owner to grant it before retrying.` });
-    throw error;
-}
-/** 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 function buildSettingsValueWriteHandler(deps, toolId) {
-    return async (ctx, options) => {
-        const target = parseTarget(toolId, ctx.input);
-        const permission = deriveRequiredPermission({ scope: target.scope, callerPrincipalId: ctx.principal.id });
-        const isSet = toolId === "settings_set_value";
-        try {
-            if (ctx.signal.aborted)
-                throw new ToolInputError({ message: `${toolId}: the run ended before the change could be applied. Nothing was changed.` });
-            writePolicy(deps, toolId, target);
-            await Promise.all([deps.settingsReady, deps.settingsUiTabsReady]);
-            await requireToolPermission({ authorize: adaptLegacyAuthorize({ authorize: deps.authorize }), workspaceId: deps.workspaceId, principalId: ctx.principal.id, permission }, { entityType: "setting-value" });
-            const definition = await resolveTarget(deps, target, isSet);
-            const rule = writePolicy(deps, toolId, target, definition);
-            const layer = await readLayer(deps, target, definition.settingId, ctx.principal.id);
-            const previous = layer?.state === "set" ? structuredClone(layer.valueJson) : null;
-            // Cancellation may have arrived during readiness, authorization or the raw read.
-            // Check before opening a card so a finished run cannot leave a new exchange waiting.
-            if (ctx.signal.aborted)
-                throw new ToolInputError({ message: `${toolId}: the run ended before the change could be applied. Nothing was changed.` });
-            if (rule) {
-                if (!deps.confirmWrite)
-                    throw new ToolInputError({ message: `${toolId}: '${rule.namespace}.${rule.key}' requires a human confirmation card: ${rule.reason}. The owner can change it in Settings.` });
-                const confirmed = await deps.confirmWrite({ ctx, toolId, namespace: rule.namespace, key: rule.key, scope: target.scope, previous: structuredClone(previous), ...(isSet ? { value: structuredClone(target.value) } : {}), reason: rule.reason }, options);
-                if (confirmed !== true)
-                    throw new ToolInputError({ message: `${toolId}: the human did not confirm the change. Nothing was changed.` });
-                const current = await resolveTarget(deps, target, isSet);
-                const currentLayer = await readLayer(deps, target, current.settingId, ctx.principal.id);
-                if (current.settingId !== definition.settingId || current.version !== definition.version || currentLayer?.seq !== layer?.seq)
-                    throw new ToolInputError({ message: `${toolId}: this setting changed while the confirmation card was open. Read it again and request a new confirmation. Nothing was changed by this call.` });
-            }
-            if (ctx.signal.aborted)
-                throw new ToolInputError({ message: `${toolId}: the run ended before the change could be applied. Nothing was changed.` });
-            const writeDeps = { repo: deps.settingsRepo, clock: deps.clock, ids: deps.idGen, authorize: deps.authorize, principals: deps.principalRepo };
-            // Resolved coordinates preserve host validators even when the request named an alias.
-            const input = { namespace: definition.namespace, key: definition.key, scope: target.scope, workspaceId: deps.workspaceId, callerPrincipalId: ctx.principal.id, authWorkspaceId: deps.workspaceId };
-            const key = `${target.namespace}.${target.key}`;
-            if (isSet) {
-                const result = await (deps.setValue ?? set)({ deps: writeDeps, input: { ...input, value: target.value } });
-                return { key, scope: target.scope, previous, value: result.value, revisionSeq: result.revisionSeq };
-            }
-            await clear({ deps: writeDeps, input });
-            const effective = await getEffective({ repo: deps.settingsRepo }, { namespace: definition.namespace, key: definition.key, scopeContext: { workspaceId: deps.workspaceId, principalId: ctx.principal.id } });
-            return { key, scope: target.scope, previous, effective: effective?.value ?? null };
-        }
-        catch (error) {
-            rethrowWriteError(error, toolId, target, permission);
-        }
-    };
-}
-//# sourceMappingURL=agent-value-write-tools.js.map

package/dist/settings/agent-writable-preferences.d.ts

@@ -1,67 +0,0 @@
-/**
- * One agent-writable preference.
- *
- * `namespace`/`key` are the ledger coordinates; `id` is the dotted form published to the model.
- * They are kept as separate fields rather than split from `id` at call time because a key may
- * itself contain dots (`telemetry.metrics` in the withheld privacy set proves the split is not
- * unambiguous), so deriving one from the other would be a latent bug the moment the allowlist grows.
- */
-export interface AgentWritablePreference {
-    /** The dotted `namespace.key`, published in the tool's `setting` enum. */
-    readonly id: string;
-    readonly namespace: string;
-    readonly key: string;
-    /**
-     * Human-readable hint published alongside the enum, so a model knows what a legal value looks
-     * like without a round trip. NOT a validator — the ledger's registered definition schema is the
-     * only thing that accepts or rejects a value, and it is checked inside the write chokepoint.
-     */
-    readonly valueHint: string;
-}
-/**
- * The scope every write through this surface uses.
- *
- * `user`, always, and never operator-selectable. All seven keys register `user | workspace`
- * (`ui-tab-definitions.ts`'s `PER_OPERATOR_SCOPES` / `NOTIFICATIONS_SCOPES`), so `workspace` is
- * reachable in principle — and deliberately not offered. A workspace-scoped write changes the
- * inherited default for every operator who has no user-scoped row of their own, which is a write
- * whose blast radius the caller cannot see. The user layer affects exactly one person, and
- * `write-service.ts`'s `deriveRequiredPermission` gates it behind `settings.user.self.write`, the
- * narrowest write grant in the system, only because the target principal is left unnamed.
- */
-export declare const AGENT_PREFERENCE_WRITE_SCOPE: "user";
-/**
- * Asserted by `__tests__/agent-writable-preferences.test.ts` against `ui-tab-definitions.ts`:
- * every id below must correspond to a definition that is actually registered AND whose scope mask
- * includes {@link SCOPE_BIT.user}. That test is the real guard on this file — an entry naming an
- * unregistered key would otherwise fail only at call time, as a runtime `DefinitionNotFoundError`
- * from inside the write chokepoint, on a tool the model had already been told it could call.
- */
-export declare const AGENT_WRITABLE_PREFERENCES: readonly AgentWritablePreference[];
-/**
- * The `setting` enum published in the tool's input schema.
- *
- * Derived from {@link AGENT_WRITABLE_PREFERENCES} rather than written out a second time: a
- * hand-maintained copy is how an id ends up callable after being removed from the allowlist.
- *
- * @complexity O(n) once at module load.
- */
-export declare const AGENT_WRITABLE_PREFERENCE_IDS: readonly string[];
-/**
- * Resolves a model-supplied `setting` id to its ledger coordinates.
- *
- * Returns `undefined` for anything not on the allowlist — including ids the enum should already
- * have rejected. The redundancy is the point: the enum lives in a schema a caller validates
- * against, and this is the check that holds if that validation is ever bypassed, misconfigured, or
- * outrun by a stale published descriptor. A curated allowlist that is enforced in only one place
- * is enforced nowhere in particular.
- *
- * @param settingId - The dotted `namespace.key` from the tool input.
- * @returns The matching preference, or `undefined` if it is not agent-writable.
- * @complexity O(1).
- * @overallScore 100
- */
-export declare function resolveAgentWritablePreference(settingId: string): AgentWritablePreference | undefined;
-/** Re-exported so the drift test can assert the scope mask without reaching into `types.ts` itself. */
-export declare const AGENT_PREFERENCE_REQUIRED_SCOPE_BIT: 4;
-//# sourceMappingURL=agent-writable-preferences.d.ts.map

package/dist/settings/agent-writable-preferences.js

@@ -1,132 +0,0 @@
-/**
- * @file The curated list of setting keys an agent may write — the precondition
- * `agent-tools.ts`'s header names.
- *
- * ## The curated surface and the generic value tools
- *
- * This enum still bounds WHICH display preference settings_set_ui_preference may change.
- * Value schemas alone do not bound target keys: the original concern remains valid.
- * The owner reversed the generic setter's permanent exclusion on 2026-10-01. See agent-tools.ts
- * and agent-write-denylist.ts: generic value tools require a human card for privacy consent and
- * standing instructions, while ordinary settings run directly. The curated display tool stays
- * caller-only and has no confirmation bypass for protected keys.
- *
- * ## What is deliberately NOT here
- *
- * `ui-tab-definitions.ts` registers 12 keys. Five are withheld:
- *
- * - **`core.privacy.telemetry.metrics` / `telemetry.content` / `decisionAt` / `installationId`** —
- *   a telemetry consent record whose entire purpose is to attest that a HUMAN decided. An agent
- *   writing it would not be recording a decision, it would be manufacturing one, and `decisionAt`
- *   is specifically the field the tab reads to know whether to stop asking. Withheld because the
- *   value means something different depending on who wrote it — the one property a curated
- *   allowlist cannot express.
- * - **`core.instructions.custom`** — the custom instructions prepended to every admin-assistant
- *   conversation. An agent writing this edits its own standing prompt for all future runs. That
- *   is self-modification, not a display preference: the generic tool now requires a human card.
- *
- * Every key that IS here is a per-operator display preference: reversible in one call, scoped to
- * the caller's own user layer, and visible in the admin UI the moment it changes — which is what
- * makes the whole surface auditable by looking at it.
- *
- * ## Architectural role
- *
- * `settings` domain data. No I/O, no enforcement — `tool-registrations.ts` performs the
- * `authorize()` call and the write. Kept as data rather than inlined into the catalog so the tool
- * schema, the handler's dispatch, and the drift test all read the same source.
- */
-import { SCOPE_BIT } from "./types.js";
-import { APPEARANCE_NAMESPACE, LANGUAGE_NAMESPACE, NOTIFICATIONS_NAMESPACE, } from "./ui-tab-definitions.js";
-/**
- * The scope every write through this surface uses.
- *
- * `user`, always, and never operator-selectable. All seven keys register `user | workspace`
- * (`ui-tab-definitions.ts`'s `PER_OPERATOR_SCOPES` / `NOTIFICATIONS_SCOPES`), so `workspace` is
- * reachable in principle — and deliberately not offered. A workspace-scoped write changes the
- * inherited default for every operator who has no user-scoped row of their own, which is a write
- * whose blast radius the caller cannot see. The user layer affects exactly one person, and
- * `write-service.ts`'s `deriveRequiredPermission` gates it behind `settings.user.self.write`, the
- * narrowest write grant in the system, only because the target principal is left unnamed.
- */
-export const AGENT_PREFERENCE_WRITE_SCOPE = "user";
-/**
- * Asserted by `__tests__/agent-writable-preferences.test.ts` against `ui-tab-definitions.ts`:
- * every id below must correspond to a definition that is actually registered AND whose scope mask
- * includes {@link SCOPE_BIT.user}. That test is the real guard on this file — an entry naming an
- * unregistered key would otherwise fail only at call time, as a runtime `DefinitionNotFoundError`
- * from inside the write chokepoint, on a tool the model had already been told it could call.
- */
-export const AGENT_WRITABLE_PREFERENCES = [
-    {
-        id: "core.language.locale",
-        namespace: LANGUAGE_NAMESPACE,
-        key: "locale",
-        valueHint: "A BCP-47 language code the admin UI ships a translation for, e.g. 'en' or 'es'. An unrecognized code is stored but selects no option in the UI.",
-    },
-    {
-        id: "core.appearance.theme",
-        namespace: APPEARANCE_NAMESPACE,
-        key: "theme",
-        valueHint: "One of 'system', 'light', or 'dark'.",
-    },
-    {
-        id: "core.appearance.accentColor",
-        namespace: APPEARANCE_NAMESPACE,
-        key: "accentColor",
-        valueHint: "A hex color, e.g. '#2563eb'. Malformed values are rejected at render time.",
-    },
-    {
-        id: "core.notifications.soundEnabled",
-        namespace: NOTIFICATIONS_NAMESPACE,
-        key: "soundEnabled",
-        valueHint: "Boolean — whether a sound plays when an assistant run finishes.",
-    },
-    {
-        id: "core.notifications.successSoundId",
-        namespace: NOTIFICATIONS_NAMESPACE,
-        key: "successSoundId",
-        valueHint: "Sound id for a successful run, e.g. 'ding'. An unknown id falls back to the default.",
-    },
-    {
-        id: "core.notifications.failureSoundId",
-        namespace: NOTIFICATIONS_NAMESPACE,
-        key: "failureSoundId",
-        valueHint: "Sound id for a failed run, e.g. 'buzz'. An unknown id falls back to the default.",
-    },
-    {
-        id: "core.notifications.desktopEnabled",
-        namespace: NOTIFICATIONS_NAMESPACE,
-        key: "desktopEnabled",
-        valueHint: "Boolean — the operator's INTENT to receive desktop notifications. The browser's own Notification permission is separate and not settable from here.",
-    },
-];
-const BY_ID = new Map(AGENT_WRITABLE_PREFERENCES.map((pref) => [pref.id, pref]));
-/**
- * The `setting` enum published in the tool's input schema.
- *
- * Derived from {@link AGENT_WRITABLE_PREFERENCES} rather than written out a second time: a
- * hand-maintained copy is how an id ends up callable after being removed from the allowlist.
- *
- * @complexity O(n) once at module load.
- */
-export const AGENT_WRITABLE_PREFERENCE_IDS = AGENT_WRITABLE_PREFERENCES.map((p) => p.id);
-/**
- * Resolves a model-supplied `setting` id to its ledger coordinates.
- *
- * Returns `undefined` for anything not on the allowlist — including ids the enum should already
- * have rejected. The redundancy is the point: the enum lives in a schema a caller validates
- * against, and this is the check that holds if that validation is ever bypassed, misconfigured, or
- * outrun by a stale published descriptor. A curated allowlist that is enforced in only one place
- * is enforced nowhere in particular.
- *
- * @param settingId - The dotted `namespace.key` from the tool input.
- * @returns The matching preference, or `undefined` if it is not agent-writable.
- * @complexity O(1).
- * @overallScore 100
- */
-export function resolveAgentWritablePreference(settingId) {
-    return BY_ID.get(settingId);
-}
-/** Re-exported so the drift test can assert the scope mask without reaching into `types.ts` itself. */
-export const AGENT_PREFERENCE_REQUIRED_SCOPE_BIT = SCOPE_BIT.user;
-//# sourceMappingURL=agent-writable-preferences.js.map

package/dist/settings/agent-write-denylist.d.ts

@@ -1,19 +0,0 @@
-/** One key or an entire namespace governed by a host's agent-write policy. */
-export interface AgentSettingWriteRule {
-    readonly namespace: string;
-    readonly key?: string;
-    readonly reason: string;
-}
-/** Owner decision 2026-10-01: these keys are writable with a HUMAN confirmation card.
- * Schema validation bounds the value, not which key. Keep that original concern explicit:
- * telemetry must record a human decision; custom instructions modify the assistant itself. */
-export declare const AGENT_WRITE_CONFIRMATION_SETTINGS: readonly AgentSettingWriteRule[];
-/** No built-in permanent deny under the owner's updated rule. Hosts may add restrictions
- * through extraDeniedSettings; assistant self-configuration belongs in confirmation rules. */
-export declare const AGENT_WRITE_DENIED_SETTINGS: readonly AgentSettingWriteRule[];
-/** Returns the first matching namespace/key rule, or undefined; pure, O(r) in fixed rules. */
-export declare function findAgentWriteRule(rules: readonly AgentSettingWriteRule[], target: {
-    namespace: string;
-    key: string;
-}): AgentSettingWriteRule | undefined;
-//# sourceMappingURL=agent-write-denylist.d.ts.map

package/dist/settings/agent-write-denylist.js

@@ -1,15 +0,0 @@
-/** Owner decision 2026-10-01: these keys are writable with a HUMAN confirmation card.
- * Schema validation bounds the value, not which key. Keep that original concern explicit:
- * telemetry must record a human decision; custom instructions modify the assistant itself. */
-export const AGENT_WRITE_CONFIRMATION_SETTINGS = [
-    { namespace: "core.privacy", reason: "Telemetry consent must record a human decision" },
-    { namespace: "core.instructions", key: "custom", reason: "The assistant's own standing instructions are self-modification" },
-];
-/** No built-in permanent deny under the owner's updated rule. Hosts may add restrictions
- * through extraDeniedSettings; assistant self-configuration belongs in confirmation rules. */
-export const AGENT_WRITE_DENIED_SETTINGS = [];
-/** Returns the first matching namespace/key rule, or undefined; pure, O(r) in fixed rules. */
-export function findAgentWriteRule(rules, target) {
-    return rules.find((rule) => rule.namespace === target.namespace && (rule.key === undefined || rule.key === target.key));
-}
-//# sourceMappingURL=agent-write-denylist.js.map