@sema-agent/client-core 0.110.0 → 0.112.0

package/dist/localConfig/modelPoolWords.d.ts

@@ -0,0 +1,13 @@
+export declare const MODEL_POOL_EDIT_KINDS: readonly ["add", "update", "remove", "setDefault", "importEnvModels", "importChannel", "bindTier", "switchTierGroup", "addTierGroup", "removeTierGroup", "migrateTierGroups", "sweepOrphanKeySlots"];
+export type ModelPoolEditKind = (typeof MODEL_POOL_EDIT_KINDS)[number];
+export declare const MODEL_POOL_CHANNEL_SOURCES: readonly ["cc-switch", "claude-settings", "openclaw", "hermes"];
+export type ModelPoolChannelSource = (typeof MODEL_POOL_CHANNEL_SOURCES)[number];
+export declare const MODEL_POOL_CREDENTIAL_KINDS: readonly ["key", "none"];
+export type ModelPoolCredentialKind = (typeof MODEL_POOL_CREDENTIAL_KINDS)[number];
+export declare const MODEL_POOL_MAX_BATCH = 64;
+export declare const MODEL_POOL_PROBE_STATES: readonly ["verified", "unverified", "unprobed"];
+export type ModelPoolProbeState = (typeof MODEL_POOL_PROBE_STATES)[number];
+export declare const MODEL_POOL_DEFAULT_KEEP_REASONS: readonly ["has_default", "existing_unknown", "declined", "nothing_added", "none_verified"];
+export type ModelPoolDefaultKeepReason = (typeof MODEL_POOL_DEFAULT_KEEP_REASONS)[number];
+export declare const MODEL_POOL_COMPLETENESS: readonly ["complete", "catalog_incomplete"];
+export type ModelPoolCompleteness = (typeof MODEL_POOL_COMPLETENESS)[number];

package/dist/localConfig/modelPoolWords.js

@@ -0,0 +1,20 @@
+export const MODEL_POOL_EDIT_KINDS = Object.freeze([
+    'add',
+    'update',
+    'remove',
+    'setDefault',
+    'importEnvModels',
+    'importChannel',
+    'bindTier',
+    'switchTierGroup',
+    'addTierGroup',
+    'removeTierGroup',
+    'migrateTierGroups',
+    'sweepOrphanKeySlots',
+]);
+export const MODEL_POOL_CHANNEL_SOURCES = Object.freeze(['cc-switch', 'claude-settings', 'openclaw', 'hermes']);
+export const MODEL_POOL_CREDENTIAL_KINDS = Object.freeze(['key', 'none']);
+export const MODEL_POOL_MAX_BATCH = 64;
+export const MODEL_POOL_PROBE_STATES = Object.freeze(['verified', 'unverified', 'unprobed']);
+export const MODEL_POOL_DEFAULT_KEEP_REASONS = Object.freeze(['has_default', 'existing_unknown', 'declined', 'nothing_added', 'none_verified']);
+export const MODEL_POOL_COMPLETENESS = Object.freeze(['complete', 'catalog_incomplete']);

package/dist/localConfig/receiptShape.d.ts

@@ -0,0 +1,7 @@
+export type LocalConfigShapeVerdict = true | {
+    readonly reason: string;
+    readonly field?: string;
+};
+export declare function localConfigReceiptShapeOf(v: {} | null | undefined, at?: string): LocalConfigShapeVerdict;
+export declare function localConfigUnavailableShapeOf(v: {} | null | undefined, at?: string): LocalConfigShapeVerdict;
+export declare function localConfigDisclosureShapeOf(v: {} | null | undefined, at?: string): LocalConfigShapeVerdict;

package/dist/localConfig/receiptShape.js

@@ -0,0 +1,135 @@
+import { isPlainRecord as isJsonPlainRecord } from '../jsonFaithful.js';
+import { ownDataField, ownSendableField } from '../ownKey.js';
+import { LOCAL_CONFIG_APPLIES_ON, LOCAL_CONFIG_DISCLOSURE_KINDS, LOCAL_CONFIG_REFUSALS, LOCAL_CONFIG_RESIDUES, LOCAL_CONFIG_UNAVAILABLE_CAUSES, LOCAL_CONFIG_UNKNOWN_CAUSES, } from './kernel.js';
+import { isWritableLocalConfigDocument, localConfigDocumentOf } from './documents.js';
+const req = (judge) => ({ opt: false, judge });
+const opt = (judge) => ({ opt: true, judge });
+const fail = (reason, at) => (at === '' ? { reason } : { reason, field: at });
+const pathAt = (at, key) => (at === '' ? key : `${at}.${key}`);
+const NOT_PLAIN = 'not plain';
+const UNREADABLE = 'unreadable';
+function slotOf(v, key) {
+    try {
+        return { ok: true, value: ownSendableField(v, key) };
+    }
+    catch {
+        return { ok: false };
+    }
+}
+const isRecord = (v) => typeof v === 'object' && v !== null && !Array.isArray(v) && isJsonPlainRecord(v);
+const badValue = (label, at) => fail(`bad value (${label})`, at);
+const valueOf = (label, test) => (v, at) => (test(v) ? true : badValue(label, at));
+const oneOf = (label, words) => valueOf(label, (v) => typeof v === 'string' && words.includes(v));
+const NONEMPTY = valueOf('non-empty string', (v) => typeof v === 'string' && v.length > 0);
+const BOOL = valueOf('boolean', (v) => typeof v === 'boolean');
+const isSlotKey = (k, n) => k === 'length' || (/^(0|[1-9][0-9]*)$/.test(k) && Number(k) < n);
+function listOf(label, item, nonEmpty) {
+    return (v, at) => {
+        if (!Array.isArray(v))
+            return badValue(label, at);
+        const n = ownDataField(v, 'length');
+        const len = typeof n === 'number' ? n : 0;
+        for (const k of Reflect.ownKeys(v))
+            if (typeof k === 'string' && !isSlotKey(k, len))
+                return fail('unknown key', pathAt(at, k));
+        if (nonEmpty && len === 0)
+            return badValue(label, at);
+        for (let i = 0; i < len; i += 1) {
+            const s = slotOf(v, String(i));
+            if (!s.ok)
+                return fail(NOT_PLAIN, `${at}[${i}]`);
+            const r = item(s.value, `${at}[${i}]`);
+            if (r !== true)
+                return r;
+        }
+        return true;
+    };
+}
+function fieldsVerdict(fields, v, at, disc) {
+    if (!isRecord(v))
+        return fail('not object', at);
+    for (const k of Reflect.ownKeys(v)) {
+        if (typeof k !== 'string')
+            continue;
+        if (!slotOf(v, k).ok)
+            return fail(NOT_PLAIN, pathAt(at, k));
+        if (k !== disc && !Object.hasOwn(fields, k))
+            return fail('unknown key', pathAt(at, k));
+    }
+    for (const k of Object.keys(fields)) {
+        const f = fields[k];
+        const s = slotOf(v, k);
+        if (!s.ok)
+            return fail(NOT_PLAIN, pathAt(at, k));
+        if (s.value === undefined) {
+            if (!f.opt)
+                return fail('missing key', pathAt(at, k));
+            continue;
+        }
+        const r = f.judge(s.value, pathAt(at, k));
+        if (r !== true)
+            return r;
+    }
+    return true;
+}
+const DISCLOSURE_KIND = req(oneOf('disclosure kind', LOCAL_CONFIG_DISCLOSURE_KINDS));
+const LAYER = opt(valueOf('document', (v) => localConfigDocumentOf(v) !== undefined));
+const DETAIL = opt(NONEMPTY);
+function disclosureFields() {
+    return { kind: DISCLOSURE_KIND, layer: LAYER, detail: DETAIL };
+}
+const disclosureJudge = (v, at) => fieldsVerdict(disclosureFields(), v, at);
+const RESIDUES = opt(listOf('residue', oneOf('residue', LOCAL_CONFIG_RESIDUES), true));
+const DISCLOSURES = opt(listOf('disclosure', disclosureJudge, true));
+const APPLIES_ON = req(oneOf('applies on', LOCAL_CONFIG_APPLIES_ON));
+const WRITES = req(listOf('writes', valueOf('writable document', (v) => isWritableLocalConfigDocument(v)), false));
+const CHANGED = req(BOOL);
+const REASON = req(oneOf('refusal', LOCAL_CONFIG_REFUSALS));
+const UNAVAILABLE_CAUSE = req(oneOf('unavailable cause', LOCAL_CONFIG_UNAVAILABLE_CAUSES));
+const UNKNOWN_CAUSE = req(oneOf('unknown cause', LOCAL_CONFIG_UNKNOWN_CAUSES));
+function receiptArms() {
+    return {
+        applied: { appliesOn: APPLIES_ON, changed: CHANGED, residue: RESIDUES, disclosures: DISCLOSURES },
+        refused: { reason: REASON, detail: DETAIL, residue: RESIDUES },
+        unavailable: { cause: UNAVAILABLE_CAUSE },
+        unknown: { cause: UNKNOWN_CAUSE, residue: RESIDUES },
+        preview: { appliesOn: APPLIES_ON, changed: CHANGED, writes: WRITES, disclosures: DISCLOSURES },
+    };
+}
+function armVerdict(v, at, only) {
+    try {
+        if (!isRecord(v))
+            return fail('not object', at);
+        const d = slotOf(v, 'kind');
+        if (!d.ok)
+            return fail(NOT_PLAIN, pathAt(at, 'kind'));
+        const arms = receiptArms();
+        const kind = typeof d.value === 'string' && Object.hasOwn(arms, d.value) && (only === undefined || d.value === only) ? d.value : undefined;
+        if (kind === undefined)
+            return fail('unknown arm', pathAt(at, 'kind'));
+        const r = fieldsVerdict(arms[kind], v, at, 'kind');
+        if (r !== true || kind !== 'preview')
+            return r;
+        const writes = slotOf(v, 'writes');
+        const changed = slotOf(v, 'changed');
+        const n = writes.ok && Array.isArray(writes.value) ? ownDataField(writes.value, 'length') : undefined;
+        return changed.ok && changed.value === (typeof n === 'number' && n > 0) ? true : badValue('changed', pathAt(at, 'changed'));
+    }
+    catch {
+        return fail(UNREADABLE, at);
+    }
+}
+export function localConfigReceiptShapeOf(v, at = '') {
+    return armVerdict(v, at);
+}
+export function localConfigUnavailableShapeOf(v, at = '') {
+    return armVerdict(v, at, 'unavailable');
+}
+export function localConfigDisclosureShapeOf(v, at = '') {
+    try {
+        return disclosureJudge(v, at);
+    }
+    catch {
+        return fail(UNREADABLE, at);
+    }
+}

package/dist/localConfig/settingsWrite.d.ts

@@ -0,0 +1,127 @@
+import type { SettingsDocument } from '../host.js';
+import type { WorkspaceTrustState } from '../hostSettingsSource.js';
+import type { LocalConfigWritableDocumentName } from './documents.js';
+import type { LocalConfigRefusal, LocalConfigResidue, LocalConfigStep, LocalConfigStepRole } from './kernel.js';
+export declare const LOCAL_CONFIG_WRITE_INTENTS: readonly [Readonly<{
+    readonly intent: "skillOverride";
+    readonly key: readonly ["skillOverrides"];
+    readonly member: "name";
+    readonly targets: readonly ["localSettings", "userSettings"];
+    readonly unit: null;
+    readonly values: readonly ["on", "name-only", "user-invocable-only", "off"];
+}>, Readonly<{
+    readonly intent: "modelKeySlot";
+    readonly key: readonly ["env"];
+    readonly member: "keySlot";
+    readonly targets: readonly ["userSettings"];
+    readonly unit: "env";
+    readonly values: null;
+}>, Readonly<{
+    readonly intent: "additionalDirectories";
+    readonly key: readonly ["permissions", "additionalDirectories"];
+    readonly member: null;
+    readonly targets: readonly ["userSettings", "projectSettings", "localSettings"];
+    readonly unit: "additionalDirectories";
+    readonly values: null;
+}>, Readonly<{
+    readonly intent: "modelCatalog";
+    readonly key: readonly ["models"];
+    readonly member: null;
+    readonly targets: readonly ["models"];
+    readonly unit: null;
+    readonly values: null;
+}>, Readonly<{
+    readonly intent: "defaultModel";
+    readonly key: readonly ["roles", "default"];
+    readonly member: null;
+    readonly targets: readonly ["models"];
+    readonly unit: null;
+    readonly values: null;
+}>, Readonly<{
+    readonly intent: "tierGroups";
+    readonly key: readonly ["tierGroups"];
+    readonly member: null;
+    readonly targets: readonly ["models"];
+    readonly unit: null;
+    readonly values: null;
+}>, Readonly<{
+    readonly intent: "activeTierGroup";
+    readonly key: readonly ["activeTierGroup"];
+    readonly member: null;
+    readonly targets: readonly ["models"];
+    readonly unit: null;
+    readonly values: null;
+}>, Readonly<{
+    readonly intent: "mcpJsonEnabled";
+    readonly key: readonly ["enabledMcpjsonServers"];
+    readonly member: "listItem";
+    readonly targets: readonly ["localSettings"];
+    readonly unit: null;
+    readonly values: null;
+    readonly admitVia: "mcpServers";
+}>, Readonly<{
+    readonly intent: "mcpJsonDisabled";
+    readonly key: readonly ["disabledMcpjsonServers"];
+    readonly member: "listItem";
+    readonly targets: readonly ["localSettings"];
+    readonly unit: null;
+    readonly values: null;
+}>, Readonly<{
+    readonly intent: "legacyTierGroups";
+    readonly key: readonly ["semaTierGroups"];
+    readonly member: null;
+    readonly targets: readonly ["userSettings"];
+    readonly unit: null;
+    readonly values: null;
+}>, Readonly<{
+    readonly intent: "legacyRosters";
+    readonly key: readonly ["semaRosters"];
+    readonly member: null;
+    readonly targets: readonly ["userSettings"];
+    readonly unit: null;
+    readonly values: null;
+}>];
+export type LocalConfigWriteIntentRow = (typeof LOCAL_CONFIG_WRITE_INTENTS)[number];
+export type LocalConfigWriteIntent = LocalConfigWriteIntentRow['intent'];
+declare const SETTINGS_LAYER_DOCUMENTS: readonly ["userSettings", "projectSettings", "localSettings"];
+type SettingsLayerDocument = (typeof SETTINGS_LAYER_DOCUMENTS)[number];
+type SettingsIntentRow = Extract<LocalConfigWriteIntentRow, {
+    readonly targets: readonly SettingsLayerDocument[];
+}>;
+export type SettingsWriteIntent = SettingsIntentRow['intent'];
+export declare const SETTINGS_WRITE_KEYS: readonly string[];
+export type SettingsWriteEdit = {
+    readonly intent: SettingsWriteIntent;
+    readonly member?: string;
+    readonly op: 'set';
+    readonly value: string | readonly string[];
+} | {
+    readonly intent: SettingsWriteIntent;
+    readonly member?: string;
+    readonly op: 'delete';
+};
+export interface SettingsWritePlanInput {
+    readonly doc: LocalConfigWritableDocumentName;
+    readonly current: SettingsDocument | null;
+    readonly trust: WorkspaceTrustState | 'unreadable';
+    readonly edits: readonly SettingsWriteEdit[];
+}
+export type SettingsWritePlan = {
+    readonly ok: true;
+    readonly next: SettingsDocument;
+    readonly changed: boolean;
+} | {
+    readonly ok: false;
+    readonly reason: LocalConfigRefusal;
+    readonly detail?: string;
+};
+export declare function settingsWritePlan(input: SettingsWritePlanInput): SettingsWritePlan;
+export interface SettingsWriteStepInput {
+    readonly doc: LocalConfigWritableDocumentName;
+    readonly trust: WorkspaceTrustState | 'unreadable';
+    readonly edits: readonly SettingsWriteEdit[];
+    readonly role?: LocalConfigStepRole;
+    readonly residue?: LocalConfigResidue;
+}
+export declare function settingsWriteStep(input: SettingsWriteStepInput): LocalConfigStep;
+export {};

package/dist/localConfig/settingsWrite.js

@@ -0,0 +1,237 @@
+import { SETTINGS_UNIT_PLACES, SETTINGS_WORKSPACE_TRUST_STATES } from '../generated/settingsSchemaTables.js';
+import { SETTINGS_IS_RESERVED_MEMBER_NAME } from '../generated/settingsSchemaFns.js';
+import { layerAdmissionWord } from '../settingsLayerAdmission.js';
+import { KEY_SLOT_PREFIX } from '../model/onboardJudgement.js';
+import { ownSnapshotRecord, readOwnDataValue } from '../ownKey.js';
+import { SKILL_OVERRIDE_STATES } from '../skillOverrideChain.js';
+const unitKey = (unit) => SETTINGS_UNIT_PLACES[unit].path;
+const SKILL_OVERRIDE_WORDS = SKILL_OVERRIDE_STATES;
+export const LOCAL_CONFIG_WRITE_INTENTS = Object.freeze([
+    Object.freeze({ intent: 'skillOverride', key: Object.freeze(['skillOverrides']), member: 'name', targets: Object.freeze(['localSettings', 'userSettings']), unit: null, values: SKILL_OVERRIDE_WORDS }),
+    Object.freeze({ intent: 'modelKeySlot', key: unitKey('env'), member: 'keySlot', targets: Object.freeze(['userSettings']), unit: 'env', values: null }),
+    Object.freeze({ intent: 'additionalDirectories', key: unitKey('additionalDirectories'), member: null, targets: Object.freeze(['userSettings', 'projectSettings', 'localSettings']), unit: 'additionalDirectories', values: null }),
+    Object.freeze({ intent: 'modelCatalog', key: Object.freeze(['models']), member: null, targets: Object.freeze(['models']), unit: null, values: null }),
+    Object.freeze({ intent: 'defaultModel', key: Object.freeze(['roles', 'default']), member: null, targets: Object.freeze(['models']), unit: null, values: null }),
+    Object.freeze({ intent: 'tierGroups', key: Object.freeze(['tierGroups']), member: null, targets: Object.freeze(['models']), unit: null, values: null }),
+    Object.freeze({ intent: 'activeTierGroup', key: Object.freeze(['activeTierGroup']), member: null, targets: Object.freeze(['models']), unit: null, values: null }),
+    Object.freeze({ intent: 'mcpJsonEnabled', key: Object.freeze(['enabledMcpjsonServers']), member: 'listItem', targets: Object.freeze(['localSettings']), unit: null, values: null, admitVia: 'mcpServers' }),
+    Object.freeze({ intent: 'mcpJsonDisabled', key: Object.freeze(['disabledMcpjsonServers']), member: 'listItem', targets: Object.freeze(['localSettings']), unit: null, values: null }),
+    Object.freeze({ intent: 'legacyTierGroups', key: Object.freeze(['semaTierGroups']), member: null, targets: Object.freeze(['userSettings']), unit: null, values: null }),
+    Object.freeze({ intent: 'legacyRosters', key: Object.freeze(['semaRosters']), member: null, targets: Object.freeze(['userSettings']), unit: null, values: null }),
+]);
+const SETTINGS_LAYER_DOCUMENTS = Object.freeze(['userSettings', 'projectSettings', 'localSettings']);
+const isSettingsLayerDocument = (v) => SETTINGS_LAYER_DOCUMENTS.some((d) => d === v);
+const settingsRows = () => LOCAL_CONFIG_WRITE_INTENTS.filter((r) => r.targets.every((t) => isSettingsLayerDocument(t)));
+const memberShape = (member) => member === 'name' ? '.<name>' : member === 'keySlot' ? `.${KEY_SLOT_PREFIX}<entry>` : member === 'listItem' ? '[<name>]' : '';
+export const SETTINGS_WRITE_KEYS = Object.freeze(settingsRows().map((r) => `${r.key.join('.')}${memberShape(r.member)}`));
+const MAX_EDITS = 64;
+const KEY_SLOT_RE = new RegExp(`^${KEY_SLOT_PREFIX}[A-Z0-9_]+$`);
+function own(v, key) {
+    try {
+        return readOwnDataValue(v, key);
+    }
+    catch {
+        return undefined;
+    }
+}
+const isPlainRecord = (v) => typeof v === 'object' && v !== null && !Array.isArray(v);
+const refuse = (reason, detail) => Object.freeze({ ok: false, reason, ...(detail === undefined ? {} : { detail }) });
+function admissionRefusal(doc, trust, unit) {
+    return categoryAdmissionRefusal(doc, trust, SETTINGS_UNIT_PLACES[unit].category);
+}
+function categoryAdmissionRefusal(doc, trust, category) {
+    let word;
+    try {
+        word = layerAdmissionWord(doc, trust, category);
+    }
+    catch {
+        return 'invalid_request';
+    }
+    if (word === 'admitted')
+        return undefined;
+    if (word === 'trust_withheld')
+        return 'untrusted_folder';
+    return 'scope_unwritable';
+}
+function stringListOf(v) {
+    if (!Array.isArray(v) || v.length > 4096)
+        return undefined;
+    const out = [];
+    for (let i = 0; i < v.length; i++) {
+        const s = own(v, String(i));
+        if (typeof s !== 'string' || s === '')
+            return undefined;
+        out.push(s);
+    }
+    return out;
+}
+function valueFor(row, raw) {
+    const values = row.values;
+    if (Array.isArray(values))
+        return typeof raw === 'string' && values.some((w) => w === raw) ? raw : undefined;
+    if (values !== null)
+        return undefined;
+    if (row.unit === null)
+        return undefined;
+    const reading = 'reading' in SETTINGS_UNIT_PLACES[row.unit] ? SETTINGS_UNIT_PLACES[row.unit].reading : undefined;
+    if (reading === 'stringList' && row.member === null)
+        return stringListOf(raw);
+    if (reading === 'envMap' && row.member !== null)
+        return typeof raw === 'string' ? raw : undefined;
+    return undefined;
+}
+function memberFits(row, member) {
+    if (typeof member !== 'string' || member === '' || member.length > 512 || SETTINGS_IS_RESERVED_MEMBER_NAME(member))
+        return false;
+    return row.member === 'keySlot' ? KEY_SLOT_RE.test(member) : true;
+}
+function listWith(current, name, present) {
+    const list = current === undefined ? [] : stringListOf(current);
+    if (list === undefined)
+        return undefined;
+    if (!present)
+        return list.filter((x) => x !== name);
+    return list.includes(name) ? list : [...list, name];
+}
+function sameJson(a, b) {
+    if (a === b)
+        return true;
+    if (typeof a !== 'object' || typeof b !== 'object' || a === null || b === null)
+        return false;
+    if (Array.isArray(a) !== Array.isArray(b))
+        return false;
+    if (Array.isArray(a) && Array.isArray(b))
+        return a.length === b.length && a.every((x, i) => sameJson(x, b[i]));
+    const ka = Object.keys(a);
+    const kb = Object.keys(b);
+    return ka.length === kb.length && ka.every((k) => Object.hasOwn(b, k) && sameJson(a[k], b[k]));
+}
+export function settingsWritePlan(input) {
+    try {
+        if (!isPlainRecord(input))
+            return refuse('invalid_request');
+        const doc = own(input, 'doc');
+        if (!isSettingsLayerDocument(doc))
+            return refuse('invalid_request');
+        const currentRaw = own(input, 'current');
+        if (currentRaw !== null && !isPlainRecord(currentRaw))
+            return refuse('invalid_request');
+        const snap = currentRaw === null ? {} : ownSnapshotRecord(currentRaw);
+        if (snap === undefined)
+            return refuse('invalid_request');
+        const before = JSON.parse(JSON.stringify(snap));
+        const next = JSON.parse(JSON.stringify(snap));
+        const trustRaw = own(input, 'trust');
+        const trust = SETTINGS_WORKSPACE_TRUST_STATES.find((w) => w === trustRaw) ?? 'unreadable';
+        const edits = own(input, 'edits');
+        if (!Array.isArray(edits) || edits.length === 0 || edits.length > MAX_EDITS)
+            return refuse('invalid_request');
+        const rows = settingsRows();
+        for (let i = 0; i < edits.length; i++) {
+            const edit = own(edits, String(i));
+            if (!isPlainRecord(edit))
+                return refuse('invalid_request');
+            const row = rows.find((r) => r.intent === own(edit, 'intent'));
+            if (row === undefined)
+                return refuse('invalid_request');
+            const op = own(edit, 'op');
+            if (op !== 'set' && op !== 'delete')
+                return refuse('invalid_request');
+            const memberRaw = own(edit, 'member');
+            if (row.member === null ? memberRaw !== undefined : !memberFits(row, memberRaw))
+                return refuse('invalid_request');
+            if (!row.targets.some((t) => t === doc))
+                return refuse('scope_unwritable');
+            if (row.member === 'listItem') {
+                const name = memberRaw;
+                if (op === 'set') {
+                    if (own(edit, 'value') !== name)
+                        return refuse('invalid_request');
+                    if ('admitVia' in row) {
+                        const why = categoryAdmissionRefusal(doc, trust, row.admitVia);
+                        if (why !== undefined)
+                            return refuse(why);
+                    }
+                }
+                let box = next;
+                for (let k = 0; k < row.key.length - 1; k++) {
+                    const seg = row.key[k];
+                    const child = Object.hasOwn(box, seg) ? box[seg] : undefined;
+                    if (child === undefined) {
+                        const made = {};
+                        Object.defineProperty(box, seg, { value: made, writable: true, enumerable: true, configurable: true });
+                        box = made;
+                    }
+                    else if (isPlainRecord(child))
+                        box = child;
+                    else
+                        return refuse('scope_unreadable', row.key.slice(0, k + 1).join('.'));
+                }
+                const last = row.key[row.key.length - 1];
+                const had = Object.hasOwn(box, last);
+                const list = listWith(had ? box[last] : undefined, name, op === 'set');
+                if (list === undefined)
+                    return refuse('scope_unreadable', row.key.join('.'));
+                if (had || list.length > 0)
+                    Object.defineProperty(box, last, { value: list, writable: true, enumerable: true, configurable: true });
+                continue;
+            }
+            const path = [...row.key, ...(row.member === null ? [] : [memberRaw])];
+            let value;
+            if (op === 'set') {
+                value = valueFor(row, own(edit, 'value'));
+                if (value === undefined)
+                    return refuse('invalid_request');
+                if (row.unit !== null) {
+                    const why = admissionRefusal(doc, trust, row.unit);
+                    if (why !== undefined)
+                        return refuse(why);
+                }
+            }
+            let box = next;
+            for (let k = 0; k < path.length - 1; k++) {
+                const seg = path[k];
+                const child = Object.hasOwn(box, seg) ? box[seg] : undefined;
+                if (child === undefined) {
+                    if (op === 'delete') {
+                        box = {};
+                        break;
+                    }
+                    const made = {};
+                    Object.defineProperty(box, seg, { value: made, writable: true, enumerable: true, configurable: true });
+                    box = made;
+                }
+                else if (isPlainRecord(child))
+                    box = child;
+                else
+                    return refuse('scope_unreadable', path.slice(0, k + 1).join('.'));
+            }
+            const last = path[path.length - 1];
+            if (op === 'delete')
+                delete box[last];
+            else
+                Object.defineProperty(box, last, { value, writable: true, enumerable: true, configurable: true });
+        }
+        const frozen = ownSnapshotRecord(next);
+        if (frozen === undefined)
+            return refuse('invalid_request');
+        return Object.freeze({ ok: true, next: frozen, changed: !sameJson(before, next) });
+    }
+    catch {
+        return refuse('invalid_request');
+    }
+}
+export function settingsWriteStep(input) {
+    const doc = input.doc;
+    const trust = input.trust;
+    const edits = input.edits;
+    const plan = ({ fresh }) => {
+        const reading = fresh[doc];
+        const current = reading !== undefined && reading.status === 'loaded' ? reading.doc : null;
+        const r = settingsWritePlan({ doc, current, trust, edits });
+        if (!r.ok)
+            return { kind: 'refuse', reason: r.reason, ...(r.detail === undefined ? {} : { detail: r.detail }) };
+        return r.changed ? { kind: 'write', next: r.next } : { kind: 'unchanged' };
+    };
+    return Object.freeze({ doc, role: input.role ?? 'effect', ...(input.residue === undefined ? {} : { residue: input.residue }), plan });
+}

package/dist/localConfig/skills.d.ts

@@ -0,0 +1,124 @@
+import type { SettingsDocument } from '../host.js';
+import { type SkillOverrideEffective, type SkillOverrideLayers, type SkillOverrideLockSource, type SkillOverrideState, type SkillOverrideSubject } from '../skillOverrideChain.js';
+import type { LocalConfigIntent, LocalConfigRefusal } from './kernel.js';
+import { type SkillRootLayer, type SkillRootKind, type SkillsViewExcludedReason, type SkillsViewLayer, type SkillOverrideScope } from './skillsWords.js';
+export interface SkillRootHostFacts {
+    readonly configHome: string;
+    readonly gitRoot?: string | null;
+    readonly additionalDirectories?: readonly string[];
+    readonly managedDir?: string;
+    readonly plugins?: readonly {
+        readonly name: string;
+        readonly root: string;
+    }[];
+}
+export interface SkillRoot {
+    readonly layer: SkillRootLayer;
+    readonly kind: SkillRootKind;
+    readonly dir: string;
+    readonly base: string;
+    readonly plugin?: string;
+}
+export interface SkillRootsTable {
+    readonly skills: readonly SkillRoot[];
+    readonly commands: readonly SkillRoot[];
+    readonly agents: readonly SkillRoot[];
+}
+export declare function skillRootsOf(cwd: string, hostFacts: SkillRootHostFacts): SkillRootsTable | undefined;
+export interface SkillListing extends Omit<SkillOverrideSubject, 'disableModelInvocation'> {
+    readonly root?: SkillRoot;
+    readonly frontmatter?: SkillFrontmatter | null;
+}
+export interface SkillFrontmatter {
+    readonly description?: string;
+    readonly 'disable-model-invocation'?: boolean | 'true' | 'false';
+}
+type SourceRootsVerdictSubset = SourceRootsJudgedSubset | {
+    readonly state: 'unjudged';
+};
+interface SourceRootsJudgedSubset {
+    readonly state: 'judged';
+    readonly roots: readonly SourceRootVerdictSubset[];
+}
+interface SourceRootVerdictSubset {
+    readonly dir: string;
+    readonly trusted: boolean;
+    readonly why?: {
+        readonly kind: string;
+    };
+}
+export type SkillsViewEditable = {
+    readonly ok: true;
+} | {
+    readonly ok: false;
+    readonly lockedBy: SkillOverrideLockSource;
+};
+export interface SkillsViewEntryBase {
+    readonly name: string;
+    readonly layer: SkillsViewLayer;
+    readonly effective: SkillOverrideEffective;
+    readonly editable: SkillsViewEditable;
+}
+export interface SkillsViewAppliedEntry extends SkillsViewEntryBase {
+    readonly status: 'applied';
+    readonly description?: string;
+    readonly nameOnly?: true;
+}
+export interface SkillsViewExcludedEntry extends SkillsViewEntryBase {
+    readonly status: 'excluded';
+    readonly reason: SkillsViewExcludedReason;
+}
+export type SkillsViewEntry = SkillsViewAppliedEntry | SkillsViewExcludedEntry;
+export interface SkillsView {
+    readonly entries: readonly SkillsViewEntry[];
+    readonly withheldRoots: {
+        readonly untrusted: number;
+        readonly unconfirmed: number;
+    };
+}
+export declare function skillsViewOf(listings: readonly SkillListing[], layers: SkillOverrideLayers, trust: SourceRootsVerdictSubset | undefined): SkillsView;
+export type SkillsEdit = {
+    readonly kind: 'set_override';
+    readonly name: string;
+    readonly state: SkillOverrideState;
+    readonly scope: SkillOverrideScope;
+} | {
+    readonly kind: 'clear_override';
+    readonly name: string;
+    readonly scope: SkillOverrideScope;
+};
+export declare function skillsSetEditOf(entry: Pick<SkillsViewEntry, 'name'>, state: SkillOverrideState, scope: SkillOverrideScope): SkillsEdit;
+export declare function skillsClearEditOf(entry: Pick<SkillsViewEntry, 'name' | 'effective'> & {
+    readonly editable?: SkillsViewEditable;
+}): SkillsEdit | undefined;
+export interface SkillOverrideWriteContext {
+    readonly subjects: readonly SkillOverrideSubject[];
+    readonly flagSettings?: SettingsDocument | null;
+    readonly session?: SkillOverrideLayers['session'];
+    readonly disabledSources?: SkillOverrideLayers['disabledSources'];
+    readonly bundledSkillsDisabledByEnv?: boolean;
+}
+export type SkillOverrideWritePlan = {
+    readonly ok: true;
+    readonly intent: LocalConfigIntent;
+} | {
+    readonly ok: false;
+    readonly reason: LocalConfigRefusal;
+};
+export declare function skillOverrideWritePlan(edit: SkillsEdit, context: SkillOverrideWriteContext): SkillOverrideWritePlan;
+export interface SkillCreateIntent {
+    readonly root: SkillRoot;
+    readonly name: string;
+    readonly content: string;
+}
+export interface SkillRemoveIntent {
+    readonly root: SkillRoot;
+    readonly name: string;
+    readonly date: string;
+}
+export type SkillFileEditPlan = {
+    readonly kind: 'pending';
+};
+export declare function skillCreatePlan(_intent: SkillCreateIntent): SkillFileEditPlan;
+export declare function skillRemovePlan(_intent: SkillRemoveIntent): SkillFileEditPlan;
+export {};