@khorsheed/dsh-local-agent 0.2.0-rc.1 → 0.2.0

package/lib/types/member-bridge.js

@@ -10,7 +10,9 @@
  * it bare: `node <this file>`, with the socket path and token in its
  * environment (written into the CLI's scoped MCP config by the provider).
  * Covers the MCP handshake subset a client needs: `initialize`,
- * `notifications/initialized`, `ping`, `tools/list`, `tools/call`.
+ * `notifications/initialized`, `ping`, `tools/list`, `tools/call`. A member
+ * with a mode also gets that preset's plugin tools: `tools/list` asks the
+ * host for them and any other tool name is forwarded as a mode-tool call.
  * @module @khorsheed/dsh-local-agent/member-bridge
  */
 import { createInterface } from 'node:readline';
@@ -21,15 +23,24 @@ import { MEMBER_BRIDGE_SOCKET_ENV, MEMBER_BRIDGE_TOKEN_ENV } from './types.js';
 /** The one tool this server exposes. */
 export const MEMBER_MESSAGE_TOOL = 'member_message';
 const TOOL_DESCRIPTION = [
-    'Notify another CLI member of this room/session group (member-to-member message).',
-    '`to` is the target member\'s dsh child session id (or a member name when a room manages the group).',
-    'The delivery receipt is returned verbatim: sent / pending-confirm / busy / an error reason.',
+    'Send a message to another member of this room/session group.',
+    '`to` is the member name (or its dsh child session id).',
+    'kind "task" (default) hands it work: in a room, its final reply is reported back to you automatically, citing the message id — do not poll.',
+    'kind "notify" is an FYI and is never reported back. Pass inReplyTo (e.g. m12) when answering a message.',
+    'Never sleep or poll for the result (room_read included): end your turn, the report arrives on its own.',
+    'Writing "@name" in a reply reaches nobody; only this tool does.',
+    'Optional note: what you will wait for before acting on the result; optional task: "new" or a task number from room_read.',
+    'The receipt is returned verbatim: sent #m<id> … / pending-confirm … / busy / an error reason.',
 ].join(' ');
 const TOOL_SCHEMA = {
     type: 'object',
     properties: {
         to: { type: 'string', description: 'The target member\'s child session id (or room-roster name).' },
-        text: { type: 'string', description: 'The notification text, delivered with your provenance.' },
+        text: { type: 'string', description: 'The message text, delivered with your provenance.' },
+        kind: { type: 'string', enum: ['task', 'notify'], description: 'task (default): the reply is reported back to you; notify: FYI only.' },
+        inReplyTo: { type: 'string', description: 'Optional id of the message this answers, e.g. m12.' },
+        note: { type: 'string', description: 'Optional: what you will wait for before acting on the result (the room uses it to decide when to hand you the report).' },
+        task: { type: 'string', description: 'Optional: "new" or a task number from room_read; omit to stay in the task you are working on.' },
     },
     required: ['to', 'text'],
     additionalProperties: false,
@@ -37,15 +48,38 @@ const TOOL_SCHEMA = {
 const ROOM_TOOLS = [
     { name: 'room_plan', description: 'Manage a formal goal with stages, dependent tasks and evidence review. Read room_read for plan state and the command contract. Ordinary small work uses room_message. Workers may submit only their own current attempt.',
         inputSchema: { type: 'object', properties: { command: { type: 'string', description: 'JSON command with action, requestId and expectedRevision; see room_read planCommands.' } }, required: ['command'], additionalProperties: false } },
-    { name: 'room_read', description: 'Read your room roster, coordinator, deliveries, recent outcomes and available harness providers. Identity comes from the host.',
+    { name: 'room_read', description: 'Read your room: roster with roles, coordinator, tasks with their numbers, deliveries, recent outcomes and available harness providers. Identity comes from the host. Use it to look around, not to wait for a result.',
         inputSchema: { type: 'object', properties: {}, additionalProperties: false } },
     { name: 'room_invite', description: 'Coordinator only: invite a member. An optional firstTask starts in the background and returns its result to you automatically.',
         inputSchema: { type: 'object', properties: {
-                provider: { type: 'string' }, name: { type: 'string' }, instructions: { type: 'string' },
+                provider: { type: 'string' }, name: { type: 'string' }, note: { type: 'string', description: 'What you will wait for before acting on the first task result.' }, role: { type: 'string', description: 'Short public role (≤30 chars) the other members see, e.g. 代码审查.' }, instructions: { type: 'string', description: 'Private instructions only this member reads.' },
                 cwd: { type: 'string' }, model: { type: 'string' }, firstTask: { type: 'string' },
+                mode: { type: 'string', description: 'The member\'s dsh mode (a host preset id, e.g. dsh-gamedev). Omit to keep this room\'s own mode; "none" for only its own CLI tools.' },
             }, required: ['provider', 'name'], additionalProperties: false } },
-    { name: 'room_message', description: 'Coordinator only: dispatch background work to a room member by name. Returns acceptance immediately; completion arrives as a correlated report. Do not poll.',
-        inputSchema: { type: 'object', properties: { member: { type: 'string' }, text: { type: 'string' } }, required: ['member', 'text'], additionalProperties: false } },
+    { name: 'ask_user_question', description: 'Ask the human questions they answer by picking options (or typing), instead of writing the questions into your reply. '
+            + 'Use it whenever you need the human to decide or fill in something before you go on: give each question 2-4 short options with a one-line description each. '
+            + 'The call waits for the answer and returns {answers:[{id, selected:[labels], custom?}]}; if nobody answers it fails — then go on with your best judgement and say what you assumed.',
+        inputSchema: { type: 'object', properties: {
+                questions: { type: 'array', description: 'At most 4 questions.', items: { type: 'object', properties: {
+                            id: { type: 'string', description: 'Short unique id, echoed in the answer.' },
+                            question: { type: 'string', description: 'The full question.' },
+                            header: { type: 'string', description: 'Optional 2-6 word topic chip.' },
+                            options: { type: 'array', items: { type: 'object', properties: { label: { type: 'string' }, description: { type: 'string' } }, required: ['label'] } },
+                            multi_select: { type: 'boolean', description: 'True when several options may be picked.' },
+                        }, required: ['id', 'question'] } },
+            }, required: ['questions'], additionalProperties: false } },
+    { name: 'room_message', description: 'Send a room member a message by name (same as member_message). kind "task" (default): its reply comes back to you as a report citing the message id; kind "notify": FYI only. Do not poll.',
+        inputSchema: { type: 'object', properties: { member: { type: 'string' }, text: { type: 'string' }, kind: { type: 'string', enum: ['task', 'notify'] }, inReplyTo: { type: 'string' }, note: { type: 'string', description: 'What you will wait for before acting on the result.' }, task: { type: 'string', description: '"new" or a task number; omit to stay in your current task.' } }, required: ['member', 'text'], additionalProperties: false } },
+    { name: 'room_help', description: 'Ask another session outside this room for help — typically the one that built what you are stuck on. It works in its own session (a busy one queues you); '
+            + 'its final answer plus a short handoff comes back to you on its own, so end your turn after asking and do not poll. Name the session by title, id or the @ mention the human wrote; '
+            + 'a session that is another room goes to its coordinator, or to the member you name. The first ask of a session the human did not @ in the room waits for their approval. '
+            + 'To answer its question or ask more, call again with the help id and no session.',
+        inputSchema: { type: 'object', properties: {
+                session: { type: 'string', description: 'The session to ask (title, id, or @ mention). Omit when continuing a thread.' },
+                member: { type: 'string', description: 'When the session is another room: the member to ask. Omit to let its coordinator decide.' },
+                help: { type: 'string', description: 'The help id of an existing thread.' },
+                text: { type: 'string', description: 'What you need, self-contained: the helper does not see this room.' },
+            }, required: ['text'], additionalProperties: false } },
 ];
 export async function callRoomCommand(env, name, args) {
     if (env.socket === undefined || env.token === undefined)
@@ -60,6 +94,30 @@ export async function callRoomCommand(env, name, args) {
         return toolText(`Room command unavailable: ${String(error)}`, true);
     }
 }
+/** The member's mode tools (the preset's plugin tools), empty when it has none or the host is unreachable. */
+export async function listModeTools(env) {
+    if (env.socket === undefined || env.token === undefined)
+        return [];
+    try {
+        const outcome = await callHost(env.socket, { token: env.token, modeTools: { list: true } });
+        return outcome.ok && Array.isArray(outcome.tools) ? outcome.tools : [];
+    }
+    catch {
+        return [];
+    }
+}
+/** Run one mode tool on the host; the host's MCP result passes through. */
+export async function callModeTool(env, name, args) {
+    if (env.socket === undefined || env.token === undefined)
+        return toolText('member channel is not configured for this run', true);
+    try {
+        const outcome = await callHost(env.socket, { token: env.token, modeTools: { call: { name, arguments: args } } });
+        return outcome.ok && outcome.result !== undefined ? outcome.result : toolText(outcome.error ?? `Tool ${name} failed`, true);
+    }
+    catch (error) {
+        return toolText(`Mode tool unavailable: ${String(error)}`, true);
+    }
+}
 /** One socket round trip: send the request line, read the one-line response. */
 function callHost(socket, payload) {
     return new Promise((resolve, reject) => {
@@ -108,6 +166,10 @@ export async function callMemberMessage(env, args) {
             token: env.token,
             to: args.to,
             text: args.text,
+            ...args.kind === 'task' || args.kind === 'notify' ? { kind: args.kind } : {},
+            ...typeof args.inReplyTo === 'string' ? { inReplyTo: args.inReplyTo } : {},
+            ...typeof args.note === 'string' ? { note: args.note } : {},
+            ...typeof args.task === 'string' ? { task: args.task } : {},
         });
         if (outcome.ok)
             return toolText(outcome.receipt ?? 'sent');
@@ -161,7 +223,8 @@ export function serveMemberBridge(env, input, output) {
                 write({ jsonrpc: '2.0', id: id ?? null, result: {} });
                 return;
             case 'tools/list':
-                write({
+                // The member's mode tools (its preset's plugin tools) join the room set.
+                void listModeTools(env).then(modeTools => write({
                     jsonrpc: '2.0',
                     id: id ?? null,
                     result: {
@@ -169,9 +232,9 @@ export function serveMemberBridge(env, input, output) {
                                 name: MEMBER_MESSAGE_TOOL,
                                 description: TOOL_DESCRIPTION,
                                 inputSchema: TOOL_SCHEMA,
-                            }, ...ROOM_TOOLS],
+                            }, ...ROOM_TOOLS, ...modeTools.filter(tool => tool['name'] !== MEMBER_MESSAGE_TOOL && !ROOM_TOOLS.some(room => room.name === tool['name']))],
                     },
-                });
+                }));
                 return;
             case 'tools/call': {
                 const params = request.params;
@@ -180,7 +243,12 @@ export function serveMemberBridge(env, input, output) {
                     return;
                 }
                 if (params?.name !== MEMBER_MESSAGE_TOOL) {
-                    write({ jsonrpc: '2.0', id: id ?? null, error: { code: -32602, message: `unknown tool ${String(params?.name)}` } });
+                    if (typeof params?.name !== 'string') {
+                        write({ jsonrpc: '2.0', id: id ?? null, error: { code: -32602, message: 'tools/call requires a tool name' } });
+                        return;
+                    }
+                    // Anything else is a mode tool; the host rejects names its mode lacks.
+                    void callModeTool(env, params.name, params.arguments ?? {}).then(result => write({ jsonrpc: '2.0', id: id ?? null, result }));
                     return;
                 }
                 void callMemberMessage(env, params.arguments ?? {}).then((result) => {

package/lib/types/member-channel.d.ts

@@ -27,6 +27,7 @@
  */
 import type { Context } from '@deepseek-ai/cordis';
 import type { LocalAgentRegistry } from './index.ts';
+import type { BridgedTool, BridgedToolResult, PresetToolHost } from './preset-tool-host.ts';
 import type { MemberRoomCommand, MemberMessageOutcome } from './types.ts';
 /** One bridge callback on the wire. */
 export interface MemberBridgeRequest {
@@ -36,11 +37,42 @@ export interface MemberBridgeRequest {
     to: string;
     /** The notification text. */
     text: string;
+    /** `task` (default) or `notify`; passed to a claiming room. */
+    kind?: 'task' | 'notify';
+    /** The message id this one answers (e.g. `m12`); passed to a claiming room. */
+    inReplyTo?: string;
+    /** What the sender waits for before acting on the result; passed to a claiming room. */
+    note?: string;
+    /** `new` or a task number; passed to a claiming room. */
+    task?: string;
 }
 export interface MemberCommandBridgeRequest {
     token: string;
     command: MemberRoomCommand;
 }
+/** The bridge asking for (`list`) or calling (`call`) the member's mode tools. */
+export interface MemberModeToolsBridgeRequest {
+    token: string;
+    modeTools: {
+        readonly list: true;
+    } | {
+        readonly call: {
+            readonly name: string;
+            readonly arguments?: unknown;
+        };
+    };
+}
+/** A mode-tools answer: the list, or one call's MCP result. */
+export type MemberModeToolsOutcome = {
+    readonly ok: true;
+    readonly tools: readonly BridgedTool[];
+} | {
+    readonly ok: true;
+    readonly result: BridgedToolResult;
+} | {
+    readonly ok: false;
+    readonly error: string;
+};
 /**
  * The member-channel host: owns the loopback unix-socket listener and the
  * delivery chain. Mounted by the plugin's `apply` and disposed with its fiber.
@@ -49,8 +81,9 @@ export declare class MemberChannel {
     private readonly ctx;
     private readonly registry;
     private readonly socketPath;
+    private readonly modeTools?;
     private server;
-    constructor(ctx: Context, registry: LocalAgentRegistry, socketPath: string);
+    constructor(ctx: Context, registry: LocalAgentRegistry, socketPath: string, modeTools?: PresetToolHost | undefined);
     /**
      * Start listening. A listener failure (e.g. a socket path beyond the
      * platform limit) degrades the whole member channel to absent — the run
@@ -71,6 +104,16 @@ export declare class MemberChannel {
      * @returns the delivery outcome.
      */
     handle(request: MemberBridgeRequest | MemberCommandBridgeRequest): Promise<MemberMessageOutcome>;
+    /**
+     * The member's mode tools: the room says which mode the member has; the
+     * preset tool host lists or runs that mode's plugin tools. No room, no mode
+     * or no host = an empty list.
+     * @param request - the bridge callback.
+     * @returns the list or the call result.
+     */
+    handleModeTools(request: MemberModeToolsBridgeRequest): Promise<MemberModeToolsOutcome>;
+    /** Install the mode's skills into the member's harness skill directory (best-effort). */
+    private installSkills;
     /** Probe the optional room gate without importing any room package. */
     private probeRoom;
     /**

package/lib/types/member-channel.js

@@ -28,6 +28,9 @@
 import { createServer } from 'node:net';
 import { mkdirSync, rmSync } from 'node:fs';
 import { dirname } from 'node:path';
+import { harnessSkillsDir, installModeSkills } from './mode-skills.js';
+/** How long one bridged mode-tool call may run before it is cancelled. */
+const MODE_TOOL_TIMEOUT_MS = 30 * 60_000;
 /**
  * The member-channel host: owns the loopback unix-socket listener and the
  * delivery chain. Mounted by the plugin's `apply` and disposed with its fiber.
@@ -36,11 +39,13 @@ export class MemberChannel {
     ctx;
     registry;
     socketPath;
+    modeTools;
     server;
-    constructor(ctx, registry, socketPath) {
+    constructor(ctx, registry, socketPath, modeTools) {
         this.ctx = ctx;
         this.registry = registry;
         this.socketPath = socketPath;
+        this.modeTools = modeTools;
     }
     /**
      * Start listening. A listener failure (e.g. a socket path beyond the
@@ -98,7 +103,10 @@ export class MemberChannel {
     async answer(socket, line) {
         let outcome;
         try {
-            outcome = await this.handle(JSON.parse(line));
+            const request = JSON.parse(line);
+            outcome = request !== null && typeof request === 'object' && 'modeTools' in request
+                ? await this.handleModeTools(request)
+                : await this.handle(request);
         }
         catch (error) {
             outcome = { ok: false, error: error instanceof Error ? error.message : String(error) };
@@ -181,6 +189,57 @@ export class MemberChannel {
         }
         return { ok: true, receipt: 'sent' };
     }
+    /**
+     * The member's mode tools: the room says which mode the member has; the
+     * preset tool host lists or runs that mode's plugin tools. No room, no mode
+     * or no host = an empty list.
+     * @param request - the bridge callback.
+     * @returns the list or the call result.
+     */
+    async handleModeTools(request) {
+        const run = typeof request.token === 'string' ? this.registry.resolveMemberRun(request.token) : undefined;
+        if (run === undefined)
+            return { ok: false, error: 'localAgent: unknown or expired member token' };
+        const mode = this.modeTools === undefined ? undefined : await this.probeRoom()?.memberMode?.(run);
+        if ('list' in request.modeTools) {
+            if (mode === undefined) {
+                // Visible in the diagnostics: a member whose room gave it no mode.
+                this.modeTools?.note({ childSessionId: run.childSessionId, provider: run.provider, mode: false });
+                return { ok: true, tools: [] };
+            }
+            try {
+                const tools = await this.modeTools.list(run.childSessionId, mode.preset, mode.cwd);
+                await this.installSkills(run, mode.preset);
+                return { ok: true, tools };
+            }
+            catch (error) {
+                this.ctx.logger.warn(`localAgent: mode tools for ${run.childSessionId} unavailable: ${String(error)}`);
+                return { ok: true, tools: [] };
+            }
+        }
+        if (mode === undefined)
+            return { ok: false, error: 'This member has no mode tools' };
+        const { name, arguments: args } = request.modeTools.call;
+        try {
+            return { ok: true, result: await this.modeTools.call(run.childSessionId, mode.preset, name, args ?? {}, AbortSignal.timeout(MODE_TOOL_TIMEOUT_MS), mode.cwd) };
+        }
+        catch (error) {
+            return { ok: false, error: String(error) };
+        }
+    }
+    /** Install the mode's skills into the member's harness skill directory (best-effort). */
+    async installSkills(run, preset) {
+        try {
+            const harness = this.registry.list().map(name => this.registry.get(name)).find(candidate => candidate?.delegationProvider === run.provider);
+            const dir = harness === undefined ? undefined : harnessSkillsDir(harness.name, this.registry.homeDir(harness.name));
+            if (dir === undefined)
+                return;
+            installModeSkills(dir, preset, await this.modeTools.skills(run.childSessionId, preset));
+        }
+        catch (error) {
+            this.ctx.logger.warn(`localAgent: mode skills for ${run.childSessionId} not installed: ${String(error)}`);
+        }
+    }
     /** Probe the optional room gate without importing any room package. */
     probeRoom() {
         const room = this.ctx.get.call(this.ctx, 'room');
@@ -203,6 +262,10 @@ export class MemberChannel {
             to: request.to,
             content: request.text,
             parentSessionId: from.parentSessionId,
+            ...request.kind === 'task' || request.kind === 'notify' ? { kind: request.kind } : {},
+            ...typeof request.inReplyTo === 'string' ? { inReplyTo: request.inReplyTo } : {},
+            ...typeof request.note === 'string' ? { note: request.note } : {},
+            ...typeof request.task === 'string' ? { task: request.task } : {},
             provenance: {
                 childSessionId: from.childSessionId,
                 provider: from.provider,

package/lib/types/member-controls.d.ts

@@ -8,6 +8,14 @@ export declare class MemberControls {
     private readonly adapter;
     private readonly onError;
     private readonly admitted;
+    /**
+     * Latest admitted configuration per child session id. Host 0.2.1 note: the
+     * activation manager wraps the provider's run, so a facade/tool caller never
+     * holds the exact object {@link admitted} keys — its run adapter names the
+     * child session id instead. Rounds of one child serialize through this
+     * class's queue, so the latest entry at read time is the reader's own round.
+     */
+    private readonly admittedByChild;
     configurationOf(run: object): LocalAgentAppliedConfiguration | undefined;
     private readonly members;
     constructor(storage: MemberControlStorage, adapter: (binding: LocalAgentMemberBinding) => MemberConfigurationAdapter, onError: (error: unknown) => void);

package/lib/types/member-controls.js

@@ -6,9 +6,21 @@ export class MemberControls {
     adapter;
     onError;
     admitted = new WeakMap();
+    /**
+     * Latest admitted configuration per child session id. Host 0.2.1 note: the
+     * activation manager wraps the provider's run, so a facade/tool caller never
+     * holds the exact object {@link admitted} keys — its run adapter names the
+     * child session id instead. Rounds of one child serialize through this
+     * class's queue, so the latest entry at read time is the reader's own round.
+     */
+    admittedByChild = new Map();
     configurationOf(run) {
-        const configuration = this.admitted.get(run);
-        return configuration === undefined ? undefined : structuredClone(configuration);
+        const exact = this.admitted.get(run);
+        if (exact !== undefined)
+            return structuredClone(exact);
+        const id = run.id;
+        const byChild = typeof id === 'string' ? this.admittedByChild.get(id) : undefined;
+        return byChild === undefined ? undefined : structuredClone(byChild);
     }
     members = new Map();
     constructor(storage, adapter, onError) {
@@ -113,6 +125,7 @@ export class MemberControls {
             nativeStarted = true;
             const run = await start(lease.configuration);
             this.admitted.set(run, lease.configuration);
+            this.admittedByChild.set(binding.childSessionId, lease.configuration);
             const release = () => { try {
                 lease.release();
             }

package/lib/types/mode-skills.d.ts

@@ -0,0 +1,18 @@
+import type { ModeSkill } from './preset-tool-host.ts';
+/** The skill directory of a harness home, or undefined when its CLI has none we know. */
+export declare function harnessSkillsDir(harness: string, home: string): string | undefined;
+/** The SKILL.md a mode skill installs as. */
+export declare function modeSkillFile(skill: ModeSkill, mode: string): {
+    readonly name: string;
+    readonly text: string;
+};
+/**
+ * Write the mode's skills into the harness's skill directory, skipping files
+ * already up to date.
+ * @param dir - the harness skill directory.
+ * @param mode - the member's mode id.
+ * @param skills - the mode's skills.
+ * @returns the installed skill names.
+ */
+export declare function installModeSkills(dir: string, mode: string, skills: readonly ModeSkill[]): string[];
+//# sourceMappingURL=mode-skills.d.ts.map

package/lib/types/mode-skills.js

@@ -0,0 +1,56 @@
+/**
+ * Mode skills, installed the CLI's own way: a member with a mode gets the
+ * skills that mode contributes (e.g. the 剪辑 mode's `video-studio`) written
+ * into its harness home's skill directory — `skills/<name>/SKILL.md`, the
+ * layout Codex (`$CODEX_HOME`), Claude Code (`$CLAUDE_CONFIG_DIR`) and Kimi
+ * (`$KIMI_CODE_HOME`, its auto-discovered user skill directory) load. The home is shared by every member of that harness, so each skill is
+ * named `dsh-<name>` and says it applies only alongside the mode's tools.
+ * Harnesses without a known skill directory get none. Best-effort:
+ * a failed write never fails the member's tool listing.
+ * @module @khorsheed/dsh-local-agent/mode-skills
+ */
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+/** Harnesses whose CLI loads `<home>/skills/<name>/SKILL.md`. */
+const SKILL_HOMES = new Set(['codex', 'claude-code', 'kimi']);
+/** The skill directory of a harness home, or undefined when its CLI has none we know. */
+export function harnessSkillsDir(harness, home) {
+    return SKILL_HOMES.has(harness) ? join(home, 'skills') : undefined;
+}
+/** The SKILL.md a mode skill installs as. */
+export function modeSkillFile(skill, mode) {
+    const name = `dsh-${skill.name}`;
+    const description = `${skill.description} (dsh mode "${mode}": use only when your tools include this mode's tools.)`.replace(/\s+/g, ' ');
+    return {
+        name,
+        text: `---\nname: ${name}\ndescription: ${JSON.stringify(description)}\n---\n\n${skill.content.trim()}\n`,
+    };
+}
+/**
+ * Write the mode's skills into the harness's skill directory, skipping files
+ * already up to date.
+ * @param dir - the harness skill directory.
+ * @param mode - the member's mode id.
+ * @param skills - the mode's skills.
+ * @returns the installed skill names.
+ */
+export function installModeSkills(dir, mode, skills) {
+    const installed = [];
+    for (const skill of skills) {
+        const file = modeSkillFile(skill, mode);
+        const target = join(dir, file.name, 'SKILL.md');
+        let current;
+        try {
+            current = readFileSync(target, 'utf8');
+        }
+        catch {
+            current = undefined;
+        }
+        if (current !== file.text) {
+            mkdirSync(join(dir, file.name), { recursive: true });
+            writeFileSync(target, file.text);
+        }
+        installed.push(file.name);
+    }
+    return installed;
+}

package/lib/types/model-list.d.ts

@@ -0,0 +1,55 @@
+/**
+ * A harness's curated model list: `<scopedHome>/models.json` holds an
+ * ORDERED array of model identifiers the user picked from the endpoint's
+ * served catalog. The list's FIRST entry is the harness's default model —
+ * it answers wherever the plugin-config `model` key answered before (round
+ * resolution, the broker's settings layer, the eval snapshot's model
+ * field), ahead of that key; an absent or empty list leaves the
+ * pre-existing chain untouched (settings key → the scoped config file →
+ * the CLI's own default). One store shape serves every harness in the
+ * family (claude-code, codex, kimi): the file is keyed by the scoped home
+ * alone, so a scope carries its own list exactly like its own endpoint
+ * credential.
+ *
+ * Why a file and not the settings channel: the credential form's
+ * endpoint-auth.json proved the pattern — the harness owns the store, the
+ * volatile row-config channel rejects writes a deployment cannot explain,
+ * and the file keeps every scope free to carry its own list. The settings
+ * card edits the default scope's file through the gateway's
+ * `modelList`/`configureModelList` Remotes; nothing here is secret (0600 is
+ * for uniformity with the credential file, not necessity).
+ * @module @khorsheed/dsh-local-agent/model-list
+ */
+/** The scoped-home model list file. */
+export declare const MODEL_LIST_FILE = "models.json";
+/** Normalize one list: trimmed, blank-dropped, deduplicated keeping first occurrence. */
+export declare function normalizeModelList(models: readonly unknown[]): string[];
+/**
+ * Read the scope's model list. Absent, unreadable, or malformed content all
+ * read as an empty list — the fallback chain then decides, exactly as
+ * before the file existed.
+ * @param homeDir - the harness's scoped home.
+ * @returns the ordered model identifiers.
+ */
+export declare function readModelList(homeDir: string): Promise<readonly string[]>;
+/**
+ * The sync twin of {@link readModelList} for the per-round model resolver —
+ * one small file read per resolution, no caching, so a card write always
+ * reaches the very next round.
+ * @param homeDir - the scope's scoped home.
+ * @returns the ordered model identifiers.
+ */
+export declare function readModelListSync(homeDir: string): readonly string[];
+/** The list's default model: its first entry, or undefined when empty. */
+export declare function firstModelOf(models: readonly string[]): string | undefined;
+/**
+ * Persist the scope's model list (normalized; an empty list DELETES the
+ * file rather than shadowing the fallback chain with nothing). Answers the
+ * normalized list as written, so the writer can flip its surface without a
+ * re-read.
+ * @param homeDir - the scope's scoped home.
+ * @param models - the new ordered list.
+ * @returns the normalized list.
+ */
+export declare function writeModelList(homeDir: string, models: readonly string[]): Promise<readonly string[]>;
+//# sourceMappingURL=model-list.d.ts.map

package/lib/types/model-list.js

@@ -0,0 +1,101 @@
+/**
+ * A harness's curated model list: `<scopedHome>/models.json` holds an
+ * ORDERED array of model identifiers the user picked from the endpoint's
+ * served catalog. The list's FIRST entry is the harness's default model —
+ * it answers wherever the plugin-config `model` key answered before (round
+ * resolution, the broker's settings layer, the eval snapshot's model
+ * field), ahead of that key; an absent or empty list leaves the
+ * pre-existing chain untouched (settings key → the scoped config file →
+ * the CLI's own default). One store shape serves every harness in the
+ * family (claude-code, codex, kimi): the file is keyed by the scoped home
+ * alone, so a scope carries its own list exactly like its own endpoint
+ * credential.
+ *
+ * Why a file and not the settings channel: the credential form's
+ * endpoint-auth.json proved the pattern — the harness owns the store, the
+ * volatile row-config channel rejects writes a deployment cannot explain,
+ * and the file keeps every scope free to carry its own list. The settings
+ * card edits the default scope's file through the gateway's
+ * `modelList`/`configureModelList` Remotes; nothing here is secret (0600 is
+ * for uniformity with the credential file, not necessity).
+ * @module @khorsheed/dsh-local-agent/model-list
+ */
+import { readFileSync } from 'node:fs';
+import { mkdir, readFile, rm, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+/** The scoped-home model list file. */
+export const MODEL_LIST_FILE = 'models.json';
+/** Normalize one list: trimmed, blank-dropped, deduplicated keeping first occurrence. */
+export function normalizeModelList(models) {
+    const out = [];
+    for (const candidate of models) {
+        if (typeof candidate !== 'string')
+            continue;
+        const trimmed = candidate.trim();
+        if (trimmed !== '' && !out.includes(trimmed))
+            out.push(trimmed);
+    }
+    return out;
+}
+/** Fold a parsed file payload into a list; any other shape reads as empty. */
+function fold(parsed) {
+    if (Array.isArray(parsed))
+        return normalizeModelList(parsed);
+    if (typeof parsed === 'object' && parsed !== null && Array.isArray(parsed.models)) {
+        return normalizeModelList(parsed.models);
+    }
+    return [];
+}
+/**
+ * Read the scope's model list. Absent, unreadable, or malformed content all
+ * read as an empty list — the fallback chain then decides, exactly as
+ * before the file existed.
+ * @param homeDir - the harness's scoped home.
+ * @returns the ordered model identifiers.
+ */
+export async function readModelList(homeDir) {
+    try {
+        return fold(JSON.parse(await readFile(join(homeDir, MODEL_LIST_FILE), 'utf8')));
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * The sync twin of {@link readModelList} for the per-round model resolver —
+ * one small file read per resolution, no caching, so a card write always
+ * reaches the very next round.
+ * @param homeDir - the scope's scoped home.
+ * @returns the ordered model identifiers.
+ */
+export function readModelListSync(homeDir) {
+    try {
+        return fold(JSON.parse(readFileSync(join(homeDir, MODEL_LIST_FILE), 'utf8')));
+    }
+    catch {
+        return [];
+    }
+}
+/** The list's default model: its first entry, or undefined when empty. */
+export function firstModelOf(models) {
+    return models.length === 0 ? undefined : models[0];
+}
+/**
+ * Persist the scope's model list (normalized; an empty list DELETES the
+ * file rather than shadowing the fallback chain with nothing). Answers the
+ * normalized list as written, so the writer can flip its surface without a
+ * re-read.
+ * @param homeDir - the scope's scoped home.
+ * @param models - the new ordered list.
+ * @returns the normalized list.
+ */
+export async function writeModelList(homeDir, models) {
+    const normalized = normalizeModelList(models);
+    if (normalized.length === 0) {
+        await rm(join(homeDir, MODEL_LIST_FILE), { force: true });
+        return [];
+    }
+    await mkdir(homeDir, { recursive: true });
+    await writeFile(join(homeDir, MODEL_LIST_FILE), JSON.stringify({ models: normalized }, undefined, 2) + '\n', { mode: 0o600 });
+    return normalized;
+}