dsh-agent-plugins-market 0.9.0 → 0.9.2

package/lib/packages/market-runtime/src/runtime/agents/teammate-role-runtime.js

@@ -0,0 +1,241 @@
+/** Role composition over public Team creation and awaited Agent initialization. */
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { installModelSelection } from '@deepseek-ai/dsh-agent';
+import { createUserMessage } from '@deepseek-ai/dsh-llm';
+import { foldSubagentDescriptor } from '@deepseek-ai/dsh-subagent';
+import { z } from 'zod';
+const PROVIDER = 'market-role-team';
+export const TEAM_ROLE_SOURCE = 'teammate-role-binding';
+const routeSchema = z.object({ provider: z.string().min(1), model: z.string().min(1), reasoningEffort: z.string().min(1).optional() }).strict();
+const snapshotSchema = z.object({ roleId: z.string().min(1), persona: z.string(), route: routeSchema }).strict();
+const bindingSchema = snapshotSchema.extend({ version: z.literal(1), childId: z.string().min(1) }).strict();
+/** The teammate's own orientation, mirroring the host's native teammate wrapper. */
+function memberIdentity(member, role) {
+    return [
+        '<system-reminder>',
+        '',
+        `You are teammate ${JSON.stringify(member)}.`,
+        'Your Team Lead is addressed as "lead".',
+        'Use list_agents({}) to find your teammates and their names.',
+        'To message your Team Lead, use send_message({ target: "lead", message: "..." }).',
+        'To message another teammate, use send_message({ target: "<teammate name>", message: "..." }).',
+        ...(role === '' ? [] : [`Your role is ${role}. The role instructions are applied to your system prompt.`]),
+        '',
+        '</system-reminder>'
+    ].join('\n');
+}
+/**
+ * Record the role route on the member's own `AgentOptions`.
+ *
+ * The host Team creation request carries no per-member route, so the child
+ * Agent starts with the Lead's route. Host surfaces read this object rather
+ * than the model selection: the Team roster shows it, the image-input gate
+ * checks it, and the member's own delegation inherits it. A host that freezes
+ * the object is reported and keeps the model selection, which still routes
+ * every request.
+ * @param agent - the member's live Agent.
+ * @param route - the validated route from the creation snapshot.
+ * @param diagnose - diagnostic sink for a host that refuses the write.
+ * @returns the disposer that restores the inherited values.
+ */
+function applyRoleRoute(agent, route, diagnose) {
+    const options = agent.options;
+    const inherited = { provider: options.provider, model: options.model, reasoningEffort: options.reasoningEffort };
+    const write = (next) => {
+        try {
+            options.provider = next.provider;
+            options.model = next.model;
+            if (next.reasoningEffort === undefined)
+                delete options.reasoningEffort;
+            else
+                options.reasoningEffort = next.reasoningEffort;
+            return true;
+        }
+        catch {
+            return false;
+        }
+    };
+    if (!write(route)) {
+        diagnose(`role teammate ${agent.id}: AgentOptions is not writable, so the host reports the inherited route`);
+        return () => { };
+    }
+    return () => {
+        write(inherited);
+    };
+}
+/** Creation and replay keep role data out of task text and never mutate the Lead's route. */
+export class TeammateRoleRuntime {
+    ctx;
+    teams;
+    subagents;
+    pending = new AsyncLocalStorage();
+    stop = new AbortController();
+    registrations = [];
+    compositions = new Map();
+    creations = new Set();
+    initializing = new Map();
+    disposal;
+    constructor(ctx) {
+        this.ctx = ctx;
+        this.teams = ctx.get('agentTeams');
+        this.subagents = ctx.get('subagents');
+        this.registrations.push(this.subagents.registerProvider({
+            name: PROVIDER,
+            inheritsParentContext: false,
+            capabilities: { agentOptions: false, outputSchema: false, depthLimit: false, toolFilter: false, persona: false },
+            start: () => Promise.reject(new Error('role teammates require Team continuation')),
+            prepareContinuable: request => {
+                const pending = this.pending.getStore();
+                if (this.stop.signal.aborted || !pending || pending.parent !== request.parent || pending.childId !== undefined)
+                    throw new Error('role teammate creation has no matching role binding');
+                pending.childId = request.sessionId;
+                return Promise.resolve({});
+            }
+        }));
+        this.registrations.push(ctx.on('agent/created', async ({ agent, signal }) => {
+            await this.initialize(agent, signal);
+        }));
+        this.registrations.push(ctx.on('agent/disposed', ({ agent }) => {
+            this.compositions.get(agent)?.();
+            this.compositions.delete(agent);
+        }));
+    }
+    /** Reattach immutable role snapshots after a plugin reload, before exposing its creation tool. */
+    async restore() {
+        for (const agent of this.ctx.agents.list())
+            await this.initialize(agent, this.stop.signal);
+    }
+    /** Resolve after native Team admission; use the returned target with native Team management tools. */
+    spawn(parent, request, snapshot, signal) {
+        this.stop.signal.throwIfAborted();
+        signal.throwIfAborted();
+        if (!request.prompt.trim())
+            return Promise.reject(new Error('spawn_teammate_role requires a non-empty prompt'));
+        const membership = this.teams.membership(parent);
+        if (membership.role !== 'lead')
+            return Promise.reject(new Error('only the Team Lead can create role teammates'));
+        const pending = {
+            parent,
+            name: request.name,
+            role: request.agent?.trim() ?? '',
+            snapshot: snapshotSchema.parse(snapshot),
+            initialized: false
+        };
+        const operation = this.pending.run(pending, async () => {
+            const result = await this.teams.spawnTeammate(parent, {
+                name: request.name,
+                description: request.description,
+                prompt: [{ type: 'text', text: request.prompt }],
+                context: 'fresh',
+                provider: PROVIDER,
+                signal: AbortSignal.any([signal, this.stop.signal])
+            });
+            if (!pending.initialized || result.member.id !== pending.childId)
+                throw new Error('role teammate was not initialized before Team admission');
+            return { target: result.member.name, roleId: pending.snapshot.roleId, ...pending.snapshot.route };
+        });
+        this.creations.add(operation);
+        void operation.finally(() => this.creations.delete(operation)).catch(() => { });
+        return operation;
+    }
+    initialize(agent, signal) {
+        const existing = this.initializing.get(agent);
+        if (existing)
+            return existing;
+        const operation = this.initializeOnce(agent, signal);
+        this.initializing.set(agent, operation);
+        void operation.finally(() => this.initializing.delete(agent)).catch(() => { });
+        return operation;
+    }
+    async initializeOnce(agent, signal) {
+        if (this.compositions.has(agent))
+            return;
+        const query = this.ctx.get('sessionQuery');
+        const observation = await query.observeSession(agent.id, { projectionMode: 'none', ...(signal === undefined ? {} : { signal }) });
+        let events;
+        try {
+            events = observation.events.filter(event => event.seq >= observation.inheritedEventCount);
+        }
+        finally {
+            observation[Symbol.dispose]();
+        }
+        const descriptor = foldSubagentDescriptor(events);
+        if (descriptor?.provider !== PROVIDER)
+            return;
+        this.stop.signal.throwIfAborted();
+        signal?.throwIfAborted();
+        const messages = events.flatMap(event => (event.type === 'user/message' ? [event.data] : event.type === 'agent/inbox/spliced' ? event.data.inserted : []));
+        const sources = new Map(messages.filter(message => message.source.kind === TEAM_ROLE_SOURCE).map(message => [message.id, message.source]));
+        const records = [...sources.values()].map(source => (source.kind === TEAM_ROLE_SOURCE ? source.binding : undefined));
+        if (records.length > 1)
+            throw new Error('role teammate has multiple role bindings');
+        let binding;
+        if (records.length === 1) {
+            binding = bindingSchema.parse(records[0]);
+            if (binding.childId !== agent.id)
+                throw new Error('role binding belongs to another teammate');
+        }
+        else {
+            const pending = this.pending.getStore();
+            const membership = this.teams.tryMembership(agent);
+            if (!pending || pending.initialized || pending.childId !== agent.id || membership?.root !== pending.parent || membership.name !== pending.name) {
+                throw new Error('role teammate has no durable or in-flight role binding');
+            }
+            binding = { version: 1, childId: agent.id, ...pending.snapshot };
+            agent.inject(createUserMessage({
+                source: { kind: TEAM_ROLE_SOURCE, form: 'context', binding },
+                content: [{ type: 'text', text: memberIdentity(membership.name, pending.role) }]
+            }));
+            if (!(await this.ctx.sessions.flush(agent.session)))
+                throw new Error('role teammate requires session persistence');
+            pending.initialized = true;
+        }
+        signal?.throwIfAborted();
+        this.stop.signal.throwIfAborted();
+        const prompt = agent.ctx.get('systemPrompt');
+        const offPersona = prompt.section({ name: 'deployment:persona-prefix', order: prompt.getSectionOrder('DEPLOYMENT_PERSONA_PREFIX'), text: binding.persona, interpolate: false });
+        const offRoute = applyRoleRoute(agent, binding.route, message => this.ctx.logger?.warn(message));
+        let offModel;
+        try {
+            offModel = installModelSelection(agent.ctx, { current: binding.route, assembled: undefined });
+        }
+        catch (error) {
+            offRoute();
+            offPersona();
+            throw error;
+        }
+        this.compositions.set(agent, () => {
+            offModel?.();
+            offPersona();
+            offRoute();
+        });
+    }
+    /** Stop owned role work before removing its scoped configuration; native Team records stay authoritative. */
+    dispose() {
+        return (this.disposal ??= this.finishDisposal());
+    }
+    async finishDisposal() {
+        this.stop.abort('role teammate plugin disposed');
+        // Keep initialization guards installed while draining, so concurrent cold
+        // resumes cannot start without the role composition during teardown.
+        await Promise.allSettled([...this.creations, ...this.initializing.values()]);
+        const byParent = new Map();
+        for (const agent of this.compositions.keys()) {
+            const parentId = agent.session.header.parentSession;
+            const parent = parentId === undefined ? undefined : this.ctx.agents.get(parentId);
+            if (parent !== undefined)
+                byParent.set(parent, [...(byParent.get(parent) ?? []), agent.id]);
+        }
+        try {
+            await Promise.all([...byParent].map(([parent, ids]) => this.subagents.drainContinuableChildren(parent, ids)));
+        }
+        finally {
+            for (const off of this.registrations.splice(0).reverse())
+                off();
+            for (const off of this.compositions.values())
+                off();
+            this.compositions.clear();
+            this.pending.disable();
+        }
+    }
+}

package/lib/packages/market-runtime/src/runtime/agents/teammate-role-tool.js

@@ -0,0 +1,130 @@
+import { resolveChildAgentOptions } from '@deepseek-ai/dsh-subagent';
+import { defineTool } from '@deepseek-ai/dsh-tools';
+import { agentRoleCatalog, requireCurrentRole, resolveAgentOptions, resolveRolePolicy, roleSnapshot, sessionCwd } from './agent-role-router.js';
+import { mountSubagentCatalog } from './subagent-catalog.js';
+import { TeammateRoleRuntime } from './teammate-role-runtime.js';
+export const TEAMMATE_ROLE_TOOL_NAME = 'spawn_teammate_role';
+/** Install the enhanced tool after its replay listener is ready; teardown drains owned role creations. */
+export async function mountTeammateRoleTool(ctx, listRoles) {
+    const runtime = new TeammateRoleRuntime(ctx);
+    const entries = async (parent) => roleSnapshot(await listRoles(parent)).entries;
+    const cleanups = [];
+    try {
+        await runtime.restore();
+        const tool = defineTool({
+            name: TEAMMATE_ROLE_TOOL_NAME,
+            description: 'Create a named Team member from a role in the current "subagent-catalog" message. Use only when the user explicitly requests Agent Teams or teammates; only the Team Lead can create members. The member starts fresh, without this conversation, with the role instructions applied to its system prompt. Returns the Team target immediately and the member runs asynchronously, so keep working instead of waiting on the call. Use the native Team tools to message, interrupt, list and assign tasks to it. Without a matching role, use spawn_teammate.',
+            parameters: {
+                agent: { type: 'string', required: true, description: 'Exact role name listed in the current "subagent-catalog" message.' },
+                name: { type: 'string', required: true, description: 'Unique lower-kebab-case Team member name, distinct from the reusable role name.' },
+                description: { type: 'string', required: true, description: 'Short description of this member responsibility.' },
+                prompt: {
+                    type: 'string',
+                    required: true,
+                    description: 'Complete standalone task, context, expected result and write boundaries. The member does not inherit this conversation.'
+                },
+                provider: { type: 'string', description: 'LLM provider, paired with model to override the role route. This is not the Team transport provider.' },
+                model: { type: 'string', description: 'Exact model id, paired with provider. Omit both to use the role route or inherit the Lead route.' },
+                reasoning_effort: { type: 'string', description: 'Optional adapter-owned reasoning effort. An explicit call route without effort uses that model default.' }
+            },
+            output: {
+                schema: {
+                    type: 'object',
+                    additionalProperties: false,
+                    properties: {
+                        target: { type: 'string', required: true },
+                        roleId: { type: 'string', required: true },
+                        provider: { type: 'string', required: true },
+                        model: { type: 'string', required: true },
+                        reasoningEffort: { type: 'string' }
+                    }
+                },
+                render: (_args, value) => [{ type: 'text', text: `created role teammate ${value.target} on ${value.provider}/${value.model}` }]
+            },
+            isConcurrencySafe: () => true,
+            async execute(args, exec) {
+                const parent = exec.agent;
+                if (!parent)
+                    throw new Error('spawn_teammate_role requires a calling agent');
+                exec.signal.throwIfAborted();
+                if (ctx.agentTeams.membership(parent).role !== 'lead')
+                    throw new Error('only the Team Lead can create role teammates');
+                const { entry, policy } = await resolveRolePolicy(entries, args.agent, parent);
+                const options = await resolveAgentOptions(policy, {
+                    ...(args.provider === undefined ? {} : { provider: args.provider }),
+                    ...(args.model === undefined ? {} : { model: args.model }),
+                    ...(args.reasoning_effort === undefined ? {} : { reasoningEffort: args.reasoning_effort })
+                }, parent, ctx.llm, exec.signal, args.agent, message => ctx.logger.warn(message));
+                // The role resolver validates effort with the live adapter; brand it only at this host boundary.
+                const effective = resolveChildAgentOptions(parent, options, parent.session.header.delegationDepth ?? 0);
+                if (!effective.provider || !effective.model)
+                    throw new Error('role teammate requires an effective provider and model');
+                // The route lookup awaited the live LLM runtime; a role revoked during
+                // it must not become a Team member.
+                await requireCurrentRole(entries, entry, parent);
+                exec.signal.throwIfAborted();
+                return runtime.spawn(parent, args, {
+                    roleId: entry.name,
+                    persona: policy.content,
+                    route: {
+                        provider: effective.provider,
+                        model: effective.model,
+                        ...(effective.reasoningEffort === undefined ? {} : { reasoningEffort: effective.reasoningEffort })
+                    }
+                }, exec.signal);
+            }
+        });
+        cleanups.push(ctx.tools.register(tool));
+        // Lead-only in the model schema: registration stays global, and each non-Lead scope
+        // denies the name in its own layer, which also covers that agent's descendants.
+        const denied = new Map();
+        const denyFor = (agent) => {
+            if (denied.has(agent) || ctx.agentTeams.tryMembership(agent)?.role === 'lead')
+                return;
+            denied.set(agent, agent.ctx.tools.restrict({ deny: [TEAMMATE_ROLE_TOOL_NAME] }));
+        };
+        // Registered before the sweep and the listeners: an early throw must still unwind
+        // what the sweep installed, and the listeners are dropped before the restrictions.
+        cleanups.push(() => {
+            for (const off of denied.values())
+                off();
+            denied.clear();
+        });
+        const offCreated = ctx.on('agent/created', ({ agent }) => {
+            denyFor(agent);
+            return undefined;
+        });
+        cleanups.push(() => {
+            offCreated();
+        });
+        const offDisposed = ctx.on('agent/disposed', ({ agent }) => {
+            denied.get(agent)?.();
+            denied.delete(agent);
+        });
+        cleanups.push(() => {
+            offDisposed();
+        });
+        for (const agent of ctx.agents.list())
+            denyFor(agent);
+        cleanups.push(mountSubagentCatalog(ctx, tool, async (agent, signal) => {
+            if (ctx.agentTeams.tryMembership(agent)?.role !== 'lead')
+                return { entries: [], complete: true };
+            const observation = roleSnapshot(await listRoles(agent));
+            return {
+                entries: await agentRoleCatalog(observation.entries, signal, message => ctx.logger.warn(message), sessionCwd(agent)),
+                complete: observation.complete
+            };
+        }, 'spawn_teammate_role'));
+        return async () => {
+            for (const off of cleanups.splice(0).reverse())
+                off();
+            await runtime.dispose();
+        };
+    }
+    catch (error) {
+        for (const off of cleanups.reverse())
+            off();
+        await runtime.dispose();
+        throw error;
+    }
+}

package/lib/{runtime → packages/market-runtime/src/runtime}/core/reconcile-scheduler.js

@@ -52,10 +52,10 @@ export class ReconcileScheduler {
     }
     async reconcileOnce() {
         try {
-            const suites = await this.host.enabledSuites();
+            const [suites, declarations] = await Promise.all([this.host.enabledSuites(), this.host.declarations?.()]);
             if (this.disposed)
                 return;
-            const diagnostics = await this.runtime.reconcile(suites);
+            const diagnostics = declarations === undefined ? await this.runtime.reconcile(suites) : await this.runtime.refreshCatalog(declarations, suites);
             this.host.publishMcpDiagnostics(diagnostics.mcp);
             for (const diagnostic of diagnostics.mcp) {
                 this.ctx.logger?.warn(`[dsh-agent-plugins-market] suite "${diagnostic.suiteId}" mcp server "${diagnostic.serverKey}": ${diagnostic.reason}`);