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

package/lib/types/preset-tool-host.js

@@ -0,0 +1,210 @@
+/**
+ * Preset tool host: lets an external CLI member use the plugin tools of a
+ * host agent preset (a mode), through its member bridge, ON THE MEMBER'S OWN
+ * SESSION. The tool registry keys scoped tools by an agent identity, and
+ * plugin tools read only `agent.id` and `agent.session` from it — so the
+ * member gets a model-less stand-in: `{ id, session }` over its own child
+ * session, given a scope (`createScope`) with the preset mounted. Calls run
+ * through the registry's normal pipeline (policies, approvals, timeouts) as
+ * that stand-in, so plugin state (a video project) belongs to the member's
+ * session and the mode's panels show there; the session also records the mode
+ * (`agent-preset/selected`), so per-session plugin visibility follows it.
+ * Only PLUGIN tools are offered (`Symbol.for('dsh.tool.origin')` channel
+ * `plugin`; the CLI brings its own shell, files and todo).
+ *
+ * Everything host-side is probed, never injected: without `sessions`,
+ * `agentPresets` or `tools` the member simply gets no extra tools.
+ * @module @khorsheed/dsh-local-agent/preset-tool-host
+ */
+import { randomUUID } from 'node:crypto';
+import { appendFileSync } from 'node:fs';
+import { createScope } from '@deepseek-ai/dsh-scope';
+import { SessionId } from '@deepseek-ai/dsh-session';
+/** Owners whose tools the bridge already serves itself (room), or that delegate from dsh (the local-agent family). */
+const skippedOwner = (owner) => owner === '@khorsheed/dsh-room' || owner.startsWith('@khorsheed/dsh-local-agent');
+/** How long a freshly mounted preset may take to finish registering its tools, and how often to look. */
+const SETTLE_MS = 3_000;
+const SETTLE_STEP_MS = 150;
+const ORIGIN = Symbol.for('dsh.tool.origin');
+/** The mode a session records: its header, overridden by the latest selection. */
+function sessionPreset(session) {
+    let preset = session.header.agentPreset ?? undefined;
+    for (const event of session.snapshotEvents()) {
+        if (event.type === 'agent-preset/selected')
+            preset = event.data?.agentPreset ?? preset;
+    }
+    return preset;
+}
+/** Whether a definition is a plugin tool the bridge may forward. */
+function isPluginTool(definition) {
+    const origin = definition?.[ORIGIN];
+    return origin?.channel === 'plugin' && !skippedOwner(String(origin.owner));
+}
+/** Map registry content blocks to MCP content (text and images; anything else as text). */
+function mcpContent(blocks) {
+    return blocks.map((block) => {
+        if (block.type === 'text')
+            return { type: 'text', text: block.text ?? '' };
+        if (block.type === 'image' && typeof block.data === 'string')
+            return { type: 'image', data: block.data, mimeType: block.mediaType ?? block.mimeType ?? 'image/png' };
+        return { type: 'text', text: JSON.stringify(block) };
+    });
+}
+/** The per-member preset agents and the list/call operations the bridge forwards. */
+export class PresetToolHost {
+    ctx;
+    diagnostics;
+    hosts = new Map();
+    /** Stand-in → the member's child session, for routing approvals its calls raise. */
+    standIns = new WeakMap();
+    /** The member a stand-in agent acts for, if it is one of ours. */
+    memberOf(agent) {
+        return typeof agent === 'object' && agent !== null ? this.standIns.get(agent) : undefined;
+    }
+    /**
+     * @param ctx - the local-agent plugin context.
+     * @param diagnostics - optional JSONL file each listing appends a summary to
+     *   (what the preset agent's scope saw and which tools passed the filter).
+     */
+    constructor(ctx, diagnostics) {
+        this.ctx = ctx;
+        this.diagnostics = diagnostics;
+    }
+    /** Append one diagnostics line (best-effort). */
+    note(entry) {
+        if (this.diagnostics === undefined)
+            return;
+        try {
+            appendFileSync(this.diagnostics, `${JSON.stringify({ time: new Date().toISOString(), ...entry })}\n`);
+        }
+        catch { /* diagnostics never fail a call */ }
+    }
+    probe(name) {
+        return this.ctx.get.call(this.ctx, name);
+    }
+    /** The member's stand-in, scoped with its preset on first use (and re-scoped when the preset changed). */
+    async agentFor(childSessionId, preset, _cwd) {
+        const sessions = this.probe('sessions');
+        const presets = this.probe('agentPresets');
+        const session = sessions?.get(SessionId(childSessionId));
+        if (presets?.mount === undefined || session === undefined)
+            return undefined;
+        const current = this.hosts.get(childSessionId);
+        if (current !== undefined && current.preset === preset && (await current.agent).agent.session === session)
+            return (await current.agent).agent;
+        if (current !== undefined) {
+            this.hosts.delete(childSessionId);
+            void current.agent.then(handle => handle.dispose()).catch(() => { });
+        }
+        const agent = (async () => {
+            const resolved = await presets.resolve(preset);
+            const member = { id: childSessionId, session };
+            this.standIns.set(member, childSessionId);
+            const scope = createScope(this.ctx, member);
+            member.ctx = scope.ctx;
+            try {
+                await presets.mount(scope.ctx, resolved.id);
+            }
+            catch (error) {
+                await scope.dispose();
+                throw error;
+            }
+            // The member's session runs this mode now: the host's per-session
+            // plugin visibility reads it from here.
+            if (sessionPreset(session) !== resolved.id)
+                session.append('agent-preset/selected', { agentPreset: resolved.id });
+            return { agent: member, dispose: () => scope.dispose() };
+        })();
+        this.hosts.set(childSessionId, { preset, agent });
+        try {
+            return (await agent).agent;
+        }
+        catch (error) {
+            this.hosts.delete(childSessionId);
+            throw error;
+        }
+    }
+    /**
+     * The preset's plugin tools, for a member's `tools/list`.
+     * @param childSessionId - the member's child session.
+     * @param preset - the member's mode.
+     * @param cwd - the member's working directory.
+     * @returns the tools, empty when the host lacks the capabilities.
+     */
+    async list(childSessionId, preset, cwd) {
+        const tools = this.probe('tools');
+        const fresh = this.hosts.get(childSessionId)?.preset !== preset;
+        const agent = await this.agentFor(childSessionId, preset, cwd);
+        if (tools === undefined || agent === undefined) {
+            this.note({ childSessionId, preset, tools: tools !== undefined, agent: agent !== undefined });
+            return [];
+        }
+        // A preset mounted for the first time registers some rows' tools a
+        // moment later (deferred injects): wait until the scope stops growing.
+        let schemas = tools.schemas(agent);
+        if (fresh) {
+            for (let waited = 0; waited < SETTLE_MS; waited += SETTLE_STEP_MS) {
+                await new Promise(resolve => setTimeout(resolve, SETTLE_STEP_MS));
+                const next = tools.schemas(agent);
+                if (next.length === schemas.length && waited >= SETTLE_STEP_MS * 3)
+                    break;
+                schemas = next;
+            }
+        }
+        const listed = schemas.filter(schema => isPluginTool(tools.get(schema.name, agent)));
+        this.note({ childSessionId, preset, agent: agent.id, scope: schemas.map(schema => {
+                const origin = tools.get(schema.name, agent)?.[ORIGIN];
+                return origin === undefined ? schema.name : `${schema.name}<${String(origin.channel)}:${String(origin.owner)}>`;
+            }), listed: listed.map(schema => schema.name) });
+        return listed
+            .map(schema => ({
+            name: schema.name,
+            description: schema.description ?? '',
+            inputSchema: (schema.parameters ?? { type: 'object', properties: {} }),
+        }));
+    }
+    /**
+     * Run one plugin tool for a member through the registry's execution
+     * pipeline (policies, approvals, timeouts), as the member's preset agent.
+     * @param childSessionId - the member's child session.
+     * @param preset - the member's mode.
+     * @param name - the tool name.
+     * @param args - the tool arguments.
+     * @param signal - cancellation.
+     * @param cwd - the member's working directory.
+     * @returns the MCP result.
+     */
+    async call(childSessionId, preset, name, args, signal, cwd) {
+        const tools = this.probe('tools');
+        const agent = await this.agentFor(childSessionId, preset, cwd);
+        if (tools === undefined || agent === undefined)
+            return { content: [{ type: 'text', text: 'Mode tools are unavailable on this host' }], isError: true };
+        if (!isPluginTool(tools.get(name, agent)))
+            return { content: [{ type: 'text', text: `Unknown tool ${name} in mode ${preset}` }], isError: true };
+        const result = await tools.execute({ callId: `bridge-${randomUUID()}`, name, arguments: args, agent, signal });
+        return { content: mcpContent(result.content), isError: result.isError };
+    }
+    /**
+     * The skills the member's mode contributes: visible in its scope, absent
+     * from the global view (installed skills every CLI already sees stay out).
+     * @param childSessionId - the member's child session.
+     * @param preset - the member's mode.
+     * @returns the mode's skills with their content; empty without a skill registry.
+     */
+    async skills(childSessionId, preset) {
+        const registry = this.probe('skills');
+        const agent = await this.agentFor(childSessionId, preset, undefined);
+        if (registry?.list === undefined || agent === undefined)
+            return [];
+        const global = new Set((await registry.list()).map(skill => skill.name));
+        const own = (await registry.list({ scope: agent })).filter(skill => !global.has(skill.name));
+        const loaded = await Promise.all(own.map(skill => registry.get(skill.name, { scope: agent })));
+        return loaded.flatMap(skill => skill === undefined ? [] : [{ name: skill.name, description: skill.description, content: skill.content }]);
+    }
+    /** Dispose every preset agent. */
+    async dispose() {
+        const hosts = [...this.hosts.values()];
+        this.hosts.clear();
+        await Promise.all(hosts.map(host => host.agent.then(handle => handle.dispose()).catch(() => { })));
+    }
+}

package/lib/types/types.d.ts

@@ -653,6 +653,14 @@ export interface LocalAgentMemberMessage {
     parentSessionId: string;
     /** The sender's delegation view, recorded as the delivery's provenance. */
     provenance: Record<string, string>;
+    /** `task` (default): a claiming room reports the reply back; `notify`: FYI only. */
+    kind?: 'task' | 'notify';
+    /** The message id this one answers (e.g. `m12`). */
+    inReplyTo?: string;
+    /** What the sender waits for before acting on the result (a claiming room's report gate reads it). */
+    note?: string;
+    /** `new` or a task number (a claiming room files the message under it). */
+    task?: string;
 }
 /**
  * The room gate's answer to a member notification, passed back to the sender
@@ -661,7 +669,7 @@ export interface LocalAgentMemberMessage {
  * DECLINE is not a value: the gate throws (the parent session is not a room
  * this instance manages) and the family direct-sends.
  */
-export type RoomMemberMessageReceipt = 'sent' | 'pending-confirm' | 'busy';
+export type RoomMemberMessageReceipt = 'sent' | 'pending-confirm' | 'busy' | `sent ${string}` | `pending-confirm ${string}`;
 /**
  * Duck-typed shape of the room service's member-message gate, probed via
  * `ctx.get('room')` — deliberately NO import of any room package, so the
@@ -669,7 +677,7 @@ export type RoomMemberMessageReceipt = 'sent' | 'pending-confirm' | 'busy';
  * independence-checker sanction: room absent or declining is invisible to the
  * family path. Room implements this shape to own the dispatch gate.
  */
-export type MemberRoomCommandName = 'room_plan' | 'room_read' | 'room_invite' | 'room_message';
+export type MemberRoomCommandName = 'room_plan' | 'room_read' | 'room_invite' | 'room_message' | 'ask_user_question' | 'room_help';
 export interface MemberRoomCommand {
     name: MemberRoomCommandName;
     arguments: Record<string, unknown>;
@@ -681,6 +689,23 @@ export interface RoomMemberMessageGate {
     }): Promise<boolean>;
     receiveMemberCommand?(actor: LocalAgentMemberRun, command: MemberRoomCommand): Promise<MemberMessageOutcome>;
     receiveMemberMessage(message: LocalAgentMemberMessage): Promise<RoomMemberMessageReceipt>;
+    /**
+     * The member's mode (a host agent preset id) whose plugin tools its bridge
+     * offers, with the member's working directory; undefined = no mode tools.
+     */
+    memberMode?(member: LocalAgentMemberRun): Promise<{
+        readonly preset: string;
+        readonly cwd?: string;
+    } | undefined>;
+    /**
+     * A member's mode tool needs the human's approval: the room asks in its
+     * conversation and answers with the registry's approval outcome.
+     */
+    askMemberApproval?(member: LocalAgentMemberRun, request: {
+        readonly toolName: string;
+        readonly reason?: string;
+        readonly signal?: AbortSignal;
+    }): Promise<'allowed-once' | 'rejected' | 'cancelled' | 'unavailable'>;
 }
 /**
  * Outcome of one `member_message` delivery. Channel-level failures (unknown or

package/package.json

@@ -8,7 +8,7 @@
     "local-agent",
     "cli"
   ],
-  "version": "0.2.0-rc.3",
+  "version": "0.2.0",
   "type": "module",
   "main": "lib/index.js",
   "types": "lib/types/index.d.ts",
@@ -59,6 +59,9 @@
     "bundle": {
       "patch": "./cordis.patch.yml"
     },
+    "references": [
+      "@khorsheed/dsh-room"
+    ],
     "compat": {
       "minHost": "0.1.5-rc.1",
       "verifiedHost": "0.2.1-rc.1",
@@ -91,6 +94,7 @@
     "@deepseek-ai/dsh-client-ui-slots": "^0.1.0-rc.6 || ^0.2.0-rc.1 || ^0.2.1-rc.1",
     "@deepseek-ai/dsh-commands": "^0.1.0-rc.6 || ^0.2.0-rc.1 || ^0.2.1-rc.1",
     "@deepseek-ai/dsh-llm": "^0.1.0-rc.6 || ^0.2.0-rc.1 || ^0.2.1-rc.1",
+    "@deepseek-ai/dsh-scope": "^0.1.0-rc.6 || ^0.2.0-rc.1 || ^0.2.1-rc.1",
     "@deepseek-ai/dsh-session": "^0.1.0-rc.6 || ^0.2.0-rc.1 || ^0.2.1-rc.1",
     "@deepseek-ai/dsh-settings": "^0.1.0-rc.6 || ^0.2.0-rc.1 || ^0.2.1-rc.1",
     "@deepseek-ai/dsh-subagent": "^0.1.0-rc.6 || ^0.2.0-rc.1 || ^0.2.1-rc.1",