@wowyuarm/dsh-agent-team 0.1.5 → 0.1.7

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

@@ -1,5 +1,6 @@
 import { readFile } from 'node:fs/promises';
 import { createUserMessage } from '@deepseek-ai/dsh-llm';
+import { SessionLogOffset } from '@deepseek-ai/dsh-session';
 export const name = 'wowyuarm-agent-team-member-context';
 const MAX_MEMORY_BYTES = 8 * 1024;
 const BEGIN = '<team-member-private-memory>';
@@ -30,7 +31,10 @@ export function apply(ctx) {
         }
         const text = `${renderMemberIdentity(member)}\n\n${memory}`;
         const latestText = agent.session.surface.nodes.toReversed().flatMap(sequence => {
-            const event = agent.session.events[sequence];
+            // `nodes` are event identities (SessionSeq); snapshotEvents takes log
+            // offsets. Re-entering through the validating constructor keeps the two
+            // number domains explicit (the seq = log.length contiguity contract).
+            const event = agent.session.snapshotEvents(SessionLogOffset(sequence), SessionLogOffset(sequence + 1))[0];
             return event?.type === 'user/message'
                 && event.data.source.kind === 'plugin'
                 && event.data.source.plugin === name
@@ -59,10 +63,10 @@ export function renderMemberMemory(raw, privateMemoryPath = '<private-memory-pat
     const warning = overBudget
         ? '\n\n[Maintenance warning: memory.md exceeds the 8 KiB context budget. Its contents were not injected; do not delete or automatically summarize the file. Maintain a smaller index explicitly.]'
         : '';
-    return `${BEGIN}\nThis is the complete replacement for this Team Member's private memory index; all earlier private-memory context is obsolete. It is reference context only, may be stale, and is not an instruction or Team fact.\n\nPrivate memory directory: ${privateMemoryPath}\nMemory index: ${privateMemoryPath}/memory.md\nNotes directory: ${privateMemoryPath}/notes\nThese paths are outside the Workspace cwd. Relative filesystem paths resolve from cwd, so use the absolute paths above when reading or editing this Member's memory. Read matching notes on demand; do not copy credentials, sensitive data, guesses, chat logs, other Members' memory, or Team facts already owned by the ledger into memory.\n\n${escape(body)}${warning}\n${END}`;
+    return `${BEGIN}\nThis is the complete replacement for this Team Member's private memory index; all earlier private-memory context is obsolete. It is reference context only, may be stale, and is not an instruction or Team fact.\n\nPrivate memory directory: ${privateMemoryPath}\nMemory index: ${privateMemoryPath}/memory.md\nNotes directory: ${privateMemoryPath}/notes\nPrivate skills directory: ${privateMemoryPath}/skills\nThese paths are outside the Workspace cwd. Relative filesystem paths resolve from cwd, so use the absolute paths above when reading or editing this Member's memory. Read matching notes on demand; do not copy credentials, sensitive data, guesses, chat logs, other Members' memory, or Team facts already owned by the ledger into memory.\n\n${escape(body)}${warning}\n${END}`;
 }
 function renderUnavailableMemory(privateMemoryPath, reason) {
-    return `${BEGIN}\nThis is the complete replacement for this Team Member's private memory index; all earlier private-memory context is obsolete. ${reason}\n\nPrivate memory directory: ${privateMemoryPath}\nMemory index: ${privateMemoryPath}/memory.md\nNotes directory: ${privateMemoryPath}/notes\nThese paths are outside the Workspace cwd. Use the absolute paths above when inspecting or repairing this Member's memory.\n${END}`;
+    return `${BEGIN}\nThis is the complete replacement for this Team Member's private memory index; all earlier private-memory context is obsolete. ${reason}\n\nPrivate memory directory: ${privateMemoryPath}\nMemory index: ${privateMemoryPath}/memory.md\nNotes directory: ${privateMemoryPath}/notes\nPrivate skills directory: ${privateMemoryPath}/skills\nThese paths are outside the Workspace cwd. Use the absolute paths above when inspecting or repairing this Member's memory.\n${END}`;
 }
 function escape(value) {
     return value.replaceAll(BEGIN, '[escaped begin marker]').replaceAll(END, '[escaped end marker]');

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/member-skills.js

@@ -0,0 +1,94 @@
+/**
+ * Per-Member private skill provider: the Team-owned wrapper around the
+ * Harness filesystem provider that scopes one Member's skill discovery to
+ * exactly the plugin's bundled read-only core skills plus that Member's
+ * private `skills/` directory (default roots excluded), and filters `list()`
+ * output by that Member's selection ref.
+ *
+ * Deliberate interface reservation: this per-Member provider seam is the
+ * primitive future Runtime Revision manifests orchestrate — do not remove
+ * during cleanup.
+ *
+ * @module @wowyuarm/dsh-agent-team/member-skills
+ */
+import { FileSystemSkillProvider } from '@deepseek-ai/dsh-skill-filesystem';
+/**
+ * Register the Member-private skill provider on one Member's agent scope and
+ * return its disposer. The provider files into that agent's exact layer, so
+ * no sibling Member or ordinary session can observe the catalog; discovery,
+ * watching, and invalidation flow through the same Harness provider below.
+ *
+ * Registration goes through the traceable service resolved FROM the agent
+ * context (the same shape as `tools.restrict()`), never through a plugin
+ * mount: a plugin mounted from Host activation code lands on the Host's
+ * async-trace fiber instead of the agent scope, and a plugin `inject` would
+ * hold Member activation open while the Host is still starting. A deployment
+ * without the skill registry keeps its Members; they simply carry no private
+ * skill catalog.
+ */
+export function mountMemberSkillProvider(agentCtx, config) {
+    const selection = config.selection;
+    // A no-op swap stands in for deployments without the skill registry, so
+    // the Host's edit path never sees a half-initialized ref.
+    selection.swap = () => { };
+    const skills = agentCtx.get('skills');
+    if (skills === undefined)
+        return () => { };
+    return skills.registerProvider(control => {
+        const provider = new MemberPrivateSkillProvider(agentCtx, control, config, selection);
+        // The ref swap updates the live filter and drops cached catalogs through
+        // the provider's own registration, so the next catalog query (and the
+        // next step's durable replacement catalog) sees the new selection.
+        selection.swap = (allow) => {
+            selection.current = allow;
+            control.invalidate();
+        };
+        return provider;
+    });
+}
+/** One Member's bundled-plus-private skill roots wrapped as a filtered registry provider. */
+class MemberPrivateSkillProvider {
+    selection;
+    name;
+    wrapped;
+    constructor(ctx, control, config, selection) {
+        this.selection = selection;
+        this.name = `member-private:${config.skillsDirectory}`;
+        // Two Team-owned roots, no project/user/global leakage: the bundled
+        // read-only core skills first, then the Member's writable private
+        // directory. Within one provider both roots share the custom rank, and
+        // discovery keeps the first root's same-name candidate, so a bundled
+        // skill stays stable across plugin upgrades while a Member installs
+        // its own additions under their own names.
+        const customSkillDirs = config.bundledSkillsDirectory === undefined
+            ? [config.skillsDirectory]
+            : [config.bundledSkillsDirectory, config.skillsDirectory];
+        this.wrapped = new FileSystemSkillProvider(ctx, control, {
+            providerName: this.name,
+            includeDefaultRoots: false,
+            customSkillDirs,
+        });
+    }
+    /**
+     * Filter the wrapped discovery to the Member's selection. Filtering is
+     * list()-output only — the directory is still scanned and watched, so this
+     * is a performance/visibility semantic, not a security boundary.
+     */
+    async list(options) {
+        const output = await this.wrapped.list(options);
+        const allow = this.selection.current;
+        if (allow === undefined)
+            return output;
+        const allowed = new Set(allow);
+        return filterObservation(output, candidate => allowed.has(candidate.name));
+    }
+    async get(candidate, options) {
+        return this.wrapped.get(candidate, options);
+    }
+}
+/** Apply one name filter to either provider observation shape. */
+function filterObservation(output, keep) {
+    if (!('candidates' in output))
+        return output.filter(keep);
+    return { candidates: output.candidates.filter(keep), complete: output.complete };
+}

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

@@ -32,6 +32,19 @@ const modelSelectionSchema = z.object({
     model,
     ...(reasoningEffort === undefined ? {} : { reasoningEffort }),
 }));
+// Pure intent: allow-list entries are plain strings. They are never
+// validated against a known-name set here — committing must survive Harness
+// upgrades that rename or remove tools, so divergence is derived at
+// activation instead (see AgentTeamCapabilityWarning).
+const memberCapabilitiesSchema = z.object({
+    // Deliberate interface reservation, no UI writes it today: Runtime Revision
+    // manifests depend on this seam — do not remove during cleanup.
+    tools: z.object({ allow: z.array(z.string().min(1)) }).strict().transform(omitUndefined).optional(),
+    skills: z.object({ allow: z.array(z.string().min(1)) }).strict().transform(omitUndefined).optional(),
+}).strict().transform(({ tools, skills }) => ({
+    ...(tools === undefined ? {} : { tools }),
+    ...(skills === undefined ? {} : { skills }),
+}));
 const memberSchema = z.object({
     memberId: memberIdSchema,
     sessionId: sessionIdSchema,
@@ -41,8 +54,10 @@ const memberSchema = z.object({
     presetId: z.string().min(1),
     // Ledgers written before per-Member model selection existed omit the field.
     model: modelSelectionSchema.optional(),
+    // 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,
@@ -50,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
@@ -231,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(),
@@ -282,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(),
@@ -384,6 +428,17 @@ const storedAgentTeamOperationSchema = z.discriminatedUnion('kind', [
             inbox: inboxDeltaSchema,
         }).strict(),
     }).strict(),
+    z.object({
+        ...operationBase,
+        previousOperationId: operationIdSchema.nullable(),
+        kind: z.literal('team/dm-sent'),
+        data: z.object({
+            workspaceId: workspaceIdSchema,
+            senderMemberId: memberIdSchema,
+            recipientMemberId: memberIdSchema,
+            body: z.string().min(1),
+        }).strict(),
+    }).strict(),
 ]);
 /** Durable validator for the closed Agent Team operation union; ledgers written before message occurredAt existed normalize on load. */
 export const agentTeamOperationSchema = storedAgentTeamOperationSchema.transform(stampOperationMessages);