@wowyuarm/dsh-agent-team 0.1.6 → 0.1.7

package/packages/agent-team/lib/member-runtime.js

@@ -0,0 +1,229 @@
+/**
+ * Per-Member runtime state extracted from the Agent Team Host service: the
+ * cohesive per-Member maps and methods that must dispose together across
+ * activation, edit, suspend, and removal — the tool-policy restriction seam,
+ * the private skill selection/provider mounts, capability warnings, and
+ * private-memory provisioning.
+ *
+ * This class is Host-side by design: its turn-boundary wait subscribes to
+ * Host-level agent events, and every traceable-service registration goes
+ * through contexts the Host already owns. The service keeps orchestration
+ * (ledger, handles, notifications, recovery); this module owns per-Member
+ * runtime invariants.
+ *
+ * @module @wowyuarm/dsh-agent-team/member-runtime
+ */
+import { mkdir, rm, writeFile } from 'node:fs/promises';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { scopeOf } from '@deepseek-ai/dsh-scope';
+import * as memberSkills from "./member-skills.js";
+/**
+ * Read-only core skills shipped beside the preset (the meta skill first:
+ * its description routes any skill-management work to itself). Resolved
+ * from this module's emitted location so it follows the installed plugin,
+ * like the preset roster's own root.
+ */
+const BUNDLED_SKILLS_DIRECTORY = resolve(dirname(fileURLToPath(import.meta.url)), '../core-skills');
+/** Model-facing capabilities every Team-enabled preset must publish. */
+export const AGENT_TEAM_TOOL_NAMES = Object.freeze([
+    'team_inbox',
+    'team_thread',
+    'team_message',
+    'team_claim',
+    'team_view',
+]);
+/** Copy a Remote-supplied capability overlay into owned frozen storage. */
+export function deepCopyCapabilities(capabilities) {
+    const copyAllow = (allow) => allow === undefined ? {} : { allow: [...allow] };
+    return {
+        ...(capabilities.tools === undefined ? {} : { tools: copyAllow(capabilities.tools.allow) }),
+        ...(capabilities.skills === undefined ? {} : { skills: copyAllow(capabilities.skills.allow) }),
+    };
+}
+/** Per-Member runtime state; the four maps dispose together with each Member. */
+export class MemberRuntime {
+    deps;
+    /**
+     * Live per-Member tool restriction disposers, mirroring modelSelections:
+     * activation registers, disposal paths release, edits swap at a turn
+     * boundary. Deliberate interface reservation: the restriction seam is the
+     * primitive future Runtime Revision manifests orchestrate — do not remove
+     * during cleanup.
+     */
+    memberRestrictions = new Map();
+    /**
+     * Runtime-derived capability warnings, recomputed at every activation (like
+     * memberFailures, keyed by Member and never persisted): persisted warnings
+     * would lie after a Host restart or a Harness upgrade renames tools.
+     */
+    capabilityWarnings = new Map();
+    /** Live skill selection refs let capability edits re-filter the catalog without disposing the Session. */
+    skillSelections = new Map();
+    /** Per-Member private skill provider disposers; released with the Member's agent scope. */
+    skillProviderDisposals = new Map();
+    constructor(deps) {
+        this.deps = deps;
+    }
+    /** One Member's live capability warnings, if any; runtime-derived, never persisted. */
+    capabilityWarningsFor(memberId) {
+        return this.capabilityWarnings.get(memberId);
+    }
+    /**
+     * Apply one Member's persisted tool allow-list as a scoped restriction on
+     * the freshly composed preset surface, and derive activation-time warnings
+     * for entries the current tool surface no longer knows. Runs inside setup
+     * BEFORE validateMemberPreset so the validation observes the restricted
+     * view (the Host always unions the five Team tools over the configured
+     * list). Deliberate interface reservation: this restriction seam is the
+     * primitive future Runtime Revision manifests orchestrate — do not remove
+     * during cleanup.
+     */
+    applyMemberToolPolicy(agentCtx, member) {
+        const configured = member.capabilities?.tools?.allow;
+        if (configured === undefined) {
+            this.capabilityWarnings.delete(member.memberId);
+            return;
+        }
+        // Drop names the current surface does not know rather than failing the
+        // activation: a Harness upgrade renaming a tool must not make the Member
+        // unavailable. The warning carries the known-name digest so a distant
+        // future reader can diagnose the drift.
+        const known = this.deps.ctx.tools.schemas(scopeOf(agentCtx)).map(tool => tool.name);
+        const knownSet = new Set(known);
+        const dropped = configured.filter(name => !knownSet.has(name));
+        this.setCapabilityWarnings(member.memberId, dropped.map(name => ({ name, knownNames: known })));
+        const allow = [...new Set([...configured.filter(name => knownSet.has(name)), ...AGENT_TEAM_TOOL_NAMES])];
+        if (allow.length === 0)
+            return;
+        // tools.restrict() requires a scoped context and rejects names outside
+        // the inherited surface; both errors surface as this Member's activation
+        // failure without touching any other Member.
+        const dispose = agentCtx.tools.restrict({ allow });
+        this.memberRestrictions.set(member.memberId, dispose);
+    }
+    /** Swap a live Member's tool policy at a turn boundary: dispose the old restriction, apply the new. */
+    reapplyMemberToolPolicy(member) {
+        this.releaseMemberToolPolicy(member.memberId);
+        this.applyMemberToolPolicy(this.deps.liveMemberContext(member.memberId), member);
+    }
+    /** Release one Member's restriction disposer and warning state; safe to call twice. */
+    releaseMemberToolPolicy(memberId) {
+        const dispose = this.memberRestrictions.get(memberId);
+        if (dispose !== undefined) {
+            this.memberRestrictions.delete(memberId);
+            dispose();
+        }
+        this.capabilityWarnings.delete(memberId);
+    }
+    setCapabilityWarnings(memberId, warnings) {
+        if (warnings.length === 0)
+            this.capabilityWarnings.delete(memberId);
+        else
+            this.capabilityWarnings.set(memberId, Object.freeze([...warnings]));
+    }
+    /**
+     * Wait until one live Member's current turn ends or its Session is
+     * disposed. While the Agent runs, the current turn keeps its schemas and
+     * catalog; the swap happens once idle, so the next step recomputes schemas
+     * from the new restriction and the durable replacement skill catalog from
+     * the new selection, with the same Session and history surviving.
+     * Suspend/remove during the wait resolves it — the disposed handle released
+     * the old restriction already and no disposer leaks. Returns whether any
+     * wait happened, so the caller can re-check the handle afterwards.
+     */
+    async awaitTurnBoundary(active) {
+        if (!this.deps.runningAgents.has(active.agent.id))
+            return false;
+        await new Promise(resolve => {
+            const disposers = [];
+            const settle = () => {
+                for (const dispose of disposers.splice(0))
+                    dispose();
+                resolve();
+            };
+            disposers.push(this.deps.ctx.on('agent/status', (payload) => {
+                if (payload.agent !== active.agent)
+                    return;
+                // A turn that ends — clean idle or error — is the boundary; the
+                // next step recomputes schemas from the new restriction.
+                if (payload.status !== 'running')
+                    settle();
+            }), 
+            // Disposal (suspend/remove/reactivation) resolves the wait: the old
+            // restriction went with the disposed scope, so only the ledger
+            // intent remains to apply at the next activation.
+            this.deps.ctx.on('session/disposed', (session) => {
+                if (session.id === active.agent.session.id)
+                    settle();
+            }));
+        });
+        return true;
+    }
+    /**
+     * Register the Member-private skill provider on the created agent's exact
+     * scope layer (the traceable-service seam, like the tool restriction):
+     * bundled read-only core skills plus this Member's own private directory,
+     * with the live selection ref that later capability edits swap in place.
+     */
+    mountMemberSkillProvider(member, agentCtx, selection) {
+        this.skillProviderDisposals.set(member.memberId, memberSkills.mountMemberSkillProvider(agentCtx, {
+            skillsDirectory: join(member.privateMemoryPath, 'skills'),
+            bundledSkillsDirectory: BUNDLED_SKILLS_DIRECTORY,
+            selection,
+        }));
+        this.skillSelections.set(member.memberId, selection);
+    }
+    /** Live-apply a capability edit to a registered selection; a no-op when none exists. */
+    swapSkillSelection(memberId, allow) {
+        this.skillSelections.get(memberId)?.swap(allow);
+    }
+    /**
+     * Provision one Member's private memory namespace: notes/, skills/, and a
+     * first-run memory.md scaffold. The Member-private skills directory starts
+     * empty; the per-Member provider scans exactly this root (default roots
+     * excluded).
+     */
+    async initializePrivateMemory(path) {
+        await mkdir(join(path, 'notes'), { recursive: true });
+        await mkdir(join(path, 'skills'), { recursive: true });
+        try {
+            await writeFile(join(path, 'memory.md'), '# Member memory\n\n## Stable facts\n- Add only verified, durable facts that help future work.\n\n## Notes index\n- Add focused `notes/*.md` entries here when a reusable detail needs on-demand reading.\n', { flag: 'wx' });
+        }
+        catch (error) {
+            if (error.code !== 'EEXIST')
+                throw error;
+        }
+    }
+    /** Irreversibly remove one Member: archive its Session and delete its private namespace. */
+    async cleanupRemovedMember(member) {
+        const results = await Promise.allSettled([
+            this.deps.ctx.workspaceRegistry.archiveSession(member.sessionId),
+            rm(member.privateMemoryPath, { recursive: true, force: true }),
+        ]);
+        const failures = results.flatMap(result => result.status === 'rejected' ? [result.reason] : []);
+        if (failures.length > 0)
+            throw new AggregateError(failures, `failed to clean up removed Member '${member.memberId}'`);
+    }
+    /** Drop one Member's transient selection/disposer state after its handle is gone; safe to call twice. */
+    forgetMember(memberId) {
+        this.skillSelections.delete(memberId);
+        const providerDispose = this.skillProviderDisposals.get(memberId);
+        if (providerDispose !== undefined) {
+            this.skillProviderDisposals.delete(memberId);
+            providerDispose();
+        }
+        this.releaseMemberToolPolicy(memberId);
+    }
+    /** Dispose every registered per-Member seam; service shutdown only. */
+    disposeAll() {
+        this.skillSelections.clear();
+        for (const dispose of this.skillProviderDisposals.values())
+            dispose();
+        this.skillProviderDisposals.clear();
+        for (const dispose of this.memberRestrictions.values())
+            dispose();
+        this.memberRestrictions.clear();
+        this.capabilityWarnings.clear();
+    }
+}

package/packages/agent-team/lib/preset-roster.js

@@ -9,6 +9,7 @@ export function apply(ctx) {
     ctx.plugin(AgentPresets, {
         default: 'team-member',
         roots: [{ path: root, trust: 'system' }],
+        includeShippedRoot: false,
         includeUserRoot: false,
     });
 }

package/packages/agent-team/lib/spec.js

@@ -57,7 +57,7 @@ const memberSchema = z.object({
     // Ledgers written before member capabilities existed omit the field.
     capabilities: memberCapabilitiesSchema.optional(),
     privateMemoryPath: z.string().min(1),
-    state: z.union([z.literal('enabled'), z.literal('suspended'), z.literal('inactive')]),
+    state: z.union([z.literal('enabled'), z.literal('suspended'), z.literal('inactive'), z.literal('archived')]),
 }).strict();
 const channelSchema = z.object({
     channelRef: channelRefSchema,
@@ -65,6 +65,8 @@ const channelSchema = z.object({
     name: z.string().min(1),
     description: z.string(),
     createdAtSequence: z.number().int().positive(),
+    // Ledgers written before Channel archival existed omit the field.
+    state: z.enum(['active', 'archived']).default('active'),
 }).strict();
 // Ledgers written before message occurredAt or attachments existed store bare
 // messages; the union schema below stamps occurredAt on load and leaves absent
@@ -246,6 +248,19 @@ const storedAgentTeamOperationSchema = z.discriminatedUnion('kind', [
         kind: z.literal('team/member-resumed'),
         data: z.object({ member: memberSchema }).strict(),
     }).strict(),
+    z.object({
+        ...operationBase,
+        previousOperationId: operationIdSchema.nullable(),
+        kind: z.literal('team/member-archived'),
+        data: z.object({
+            member: memberSchema,
+            claims: z.array(claimSchema),
+            activities: z.array(claimsReleasedActivitySchema),
+            tasks: z.array(taskSchema),
+            threads: z.array(threadSchema),
+            inbox: inboxDeltaSchema,
+        }).strict(),
+    }).strict(),
     z.object({
         ...operationBase,
         previousOperationId: operationIdSchema.nullable(),
@@ -297,6 +312,20 @@ const storedAgentTeamOperationSchema = z.discriminatedUnion('kind', [
             inbox: inboxDeltaSchema,
         }).strict(),
     }).strict(),
+    z.object({
+        ...operationBase,
+        previousOperationId: operationIdSchema.nullable(),
+        kind: z.literal('team/channel-archived'),
+        data: z.object({
+            workspaceId: workspaceIdSchema,
+            channel: channelSchema,
+            claims: z.array(claimSchema),
+            activities: z.array(claimsReleasedActivitySchema),
+            tasks: z.array(taskSchema),
+            threads: z.array(threadSchema),
+            inbox: inboxDeltaSchema,
+        }).strict(),
+    }).strict(),
     z.object({
         ...operationBase,
         previousOperationId: operationIdSchema.nullable(),