@wowyuarm/dsh-agent-team 0.1.7 → 0.1.9

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

@@ -13,7 +13,7 @@
  *
  * @module @wowyuarm/dsh-agent-team/member-runtime
  */
-import { mkdir, rm, writeFile } from 'node:fs/promises';
+import { mkdir, readdir, rename, rm, stat, writeFile } from 'node:fs/promises';
 import { dirname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { scopeOf } from '@deepseek-ai/dsh-scope';
@@ -32,6 +32,9 @@ export const AGENT_TEAM_TOOL_NAMES = Object.freeze([
     'team_message',
     'team_claim',
     'team_view',
+    'context_rollover',
+    'context_checkpoint',
+    'context_timeline',
 ]);
 /** Copy a Remote-supplied capability overlay into owned frozen storage. */
 export function deepCopyCapabilities(capabilities) {
@@ -41,6 +44,31 @@ export function deepCopyCapabilities(capabilities) {
         ...(capabilities.skills === undefined ? {} : { skills: copyAllow(capabilities.skills.allow) }),
     };
 }
+/**
+ * Filesystem directory segment for one Member's private memory namespace.
+ * The `member:<uuid>` ref is a durable ledger identity and must never appear
+ * in a path: Windows rejects `:` in a path segment (NTFS parses it as an
+ * Alternate Data Stream separator), which made Member activation fail at its
+ * first `mkdir` on Windows (issue #7).
+ */
+export function memberMemoryDirectoryName(memberId) {
+    return memberId.replaceAll(':', '-');
+}
+/** The sanitized absolute private-memory path for one Member, regardless of what the ledger recorded. */
+export function memberMemoryDirectoryPath(member) {
+    // Sanitize per segment: only a segment that actually contains the ledger's
+    // member identity colon needs rewriting, and the recorded final segment is
+    // the only place it can appear. The drive-letter colon of a Windows
+    // absolute prefix is not a member identity and must survive untouched, so
+    // a colon-free final segment keeps the recorded path verbatim even when
+    // earlier segments carry colons.
+    const separator = Math.max(member.privateMemoryPath.lastIndexOf('/'), member.privateMemoryPath.lastIndexOf('\\'));
+    const finalSegment = separator === -1 ? member.privateMemoryPath : member.privateMemoryPath.slice(separator + 1);
+    if (!finalSegment.includes(':'))
+        return member.privateMemoryPath;
+    const prefix = separator === -1 ? '' : member.privateMemoryPath.slice(0, separator + 1);
+    return prefix + memberMemoryDirectoryName(member.memberId);
+}
 /** Per-Member runtime state; the four maps dispose together with each Member. */
 export class MemberRuntime {
     deps;
@@ -165,10 +193,12 @@ export class MemberRuntime {
      * 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.
+     * The sanitized directory is authoritative: activateMember migrated any
+     * legacy colon directory onto it before the provider mounted.
      */
     mountMemberSkillProvider(member, agentCtx, selection) {
         this.skillProviderDisposals.set(member.memberId, memberSkills.mountMemberSkillProvider(agentCtx, {
-            skillsDirectory: join(member.privateMemoryPath, 'skills'),
+            skillsDirectory: join(memberMemoryDirectoryPath(member), 'skills'),
             bundledSkillsDirectory: BUNDLED_SKILLS_DIRECTORY,
             selection,
         }));
@@ -183,8 +213,29 @@ export class MemberRuntime {
      * first-run memory.md scaffold. The Member-private skills directory starts
      * empty; the per-Member provider scans exactly this root (default roots
      * excluded).
+     *
+     * Existing installs recorded the pre-fix colon directory in the ledger, and
+     * `privateMemoryPath` is a durable Member fact the renewal path cannot
+     * rewrite: when the legacy directory exists it is renamed onto the sanitized
+     * path once (same-parent rename, atomic), so existing private memory
+     * survives instead of being silently orphaned.
+     *
+     * A colon-form twin directory is also merged when it exists: a Member may
+     * have written files under the ledger identity spelling (the branded
+     * `member:<uuid>` ref is what every Team tool result shows, so a
+     * hand-assembled path carries the colon). Linux accepts the segment
+     * silently — two directories for one Member — while Windows would have
+     * failed the write outright. The twin is never a durable-Member-Fact
+     * candidate: only the files the Member actually wrote there are worth
+     * keeping, and `memory.md` cannot merge, so the sanitized copy always wins
+     * and twin-only notes/skills are moved in without overwriting.
      */
-    async initializePrivateMemory(path) {
+    async initializePrivateMemory(path, legacyPath) {
+        if (legacyPath !== undefined && legacyPath !== path)
+            await migrateLegacyMemoryDirectory(legacyPath, path);
+        const twinPath = twinMemoryDirectoryPath(path);
+        if (twinPath !== undefined)
+            await mergeTwinMemoryDirectory(twinPath, path);
         await mkdir(join(path, 'notes'), { recursive: true });
         await mkdir(join(path, 'skills'), { recursive: true });
         try {
@@ -197,9 +248,14 @@ export class MemberRuntime {
     }
     /** Irreversibly remove one Member: archive its Session and delete its private namespace. */
     async cleanupRemovedMember(member) {
+        // The ledger path may still name the legacy colon directory (never
+        // activated after the fix): remove both spellings; rm is force-tolerant
+        // of the one that does not exist.
+        const sanitized = memberMemoryDirectoryPath(member);
         const results = await Promise.allSettled([
             this.deps.ctx.workspaceRegistry.archiveSession(member.sessionId),
-            rm(member.privateMemoryPath, { recursive: true, force: true }),
+            rm(sanitized, { recursive: true, force: true }),
+            ...(sanitized === member.privateMemoryPath ? [] : [rm(member.privateMemoryPath, { recursive: true, force: true })]),
         ]);
         const failures = results.flatMap(result => result.status === 'rejected' ? [result.reason] : []);
         if (failures.length > 0)
@@ -227,3 +283,102 @@ export class MemberRuntime {
         this.capabilityWarnings.clear();
     }
 }
+/**
+ * One-time in-place migration of a pre-fix colon-named private memory
+ * directory onto its sanitized path. A sanitized target that already exists
+ * wins (idempotent across restarts and partially migrated installs); a legacy
+ * source that never existed is simply the fresh-install case.
+ */
+async function migrateLegacyMemoryDirectory(legacyPath, path) {
+    let legacy;
+    try {
+        legacy = await stat(legacyPath);
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return;
+        throw error;
+    }
+    if (!legacy.isDirectory())
+        throw new Error(`legacy Member memory path '${legacyPath}' exists but is not a directory`);
+    try {
+        await stat(path);
+        return; // Sanitized directory already present: migration already done or a new install.
+    }
+    catch (error) {
+        if (error.code !== 'ENOENT')
+            throw error;
+    }
+    await rename(legacyPath, path);
+}
+/** The colon-form twin path of one sanitized Member memory directory, when the segment form admits one. */
+function twinMemoryDirectoryPath(sanitizedPath) {
+    const separator = Math.max(sanitizedPath.lastIndexOf('/'), sanitizedPath.lastIndexOf('\\'));
+    const prefix = separator === -1 ? '' : sanitizedPath.slice(0, separator + 1);
+    const finalSegment = separator === -1 ? sanitizedPath : sanitizedPath.slice(separator + 1);
+    // Only the exact sanitized identity segment (`member-<uuid>`) has a colon
+    // twin (`member:<uuid>`); any other segment shape has no identity mapping.
+    if (!/^member-[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/.test(finalSegment))
+        return undefined;
+    return `${prefix}member:${finalSegment.slice('member-'.length)}`;
+}
+/** The colon-twin trace name for one conflicting file: `note.md` → `note.colon-twin.md`. */
+function colonTwinTraceName(name) {
+    const dot = name.lastIndexOf('.');
+    return dot <= 0 ? `${name}.colon-twin` : `${name.slice(0, dot)}.colon-twin${name.slice(dot)}`;
+}
+/**
+ * Merge a hand-created colon-form twin directory into the sanitized Member
+ * memory directory. Unlike the ledger legacy migration this is a merge, not a
+ * rename: the sanitized directory is the Member's live root (the injected
+ * paths and the skill provider point at it), so on a same-path conflict the
+ * live root's copy wins and the twin's losing copy is preserved beside it
+ * under a `.colon-twin` name instead of being silently discarded. Twin-only
+ * files move in under their own names; the emptied twin directory is then
+ * removed so the drift cannot silently recur.
+ */
+async function mergeTwinMemoryDirectory(twinPath, path) {
+    let twin;
+    try {
+        twin = await stat(twinPath);
+    }
+    catch (error) {
+        if (error.code !== 'ENOENT')
+            throw error;
+        return;
+    }
+    if (!twin.isDirectory())
+        return;
+    await mergeDirectoryContents(twinPath, path);
+    await rm(twinPath, { recursive: true, force: true });
+}
+/** Recursively move every twin file into the live root; an existing live file wins, its twin copy traced beside it. */
+async function mergeDirectoryContents(source, target) {
+    await mkdir(target, { recursive: true });
+    for (const entry of await readdir(source, { withFileTypes: true })) {
+        const sourcePath = join(source, entry.name);
+        const targetPath = join(target, entry.name);
+        if (entry.isDirectory()) {
+            await mergeDirectoryContents(sourcePath, targetPath);
+        }
+        else if (entry.isFile()) {
+            // rename(2) silently REPLACES an existing target on POSIX (the EEXIST
+            // error only exists on Windows, where the colon twin cannot exist at
+            // all), so a collision must be detected, not caught: probe the target
+            // first. Activation is the single serialized writer, so the
+            // probe-to-rename window has no concurrent writer to race.
+            let liveFilePresent = true;
+            try {
+                await stat(targetPath);
+            }
+            catch (error) {
+                if (error.code !== 'ENOENT')
+                    throw error;
+                liveFilePresent = false;
+            }
+            // The live root stays authoritative; the twin's losing copy stays
+            // traceable beside it instead of being silently discarded.
+            await rename(sourcePath, liveFilePresent ? join(target, colonTwinTraceName(entry.name)) : targetPath);
+        }
+    }
+}

package/packages/agent-team/lib/pressure-policy.js

@@ -0,0 +1,200 @@
+/**
+ * Team-owned context pressure policy.
+ *
+ * The Team preset mounts `compaction-basic` with `auto: false`; this
+ * coordinator owns both policy entry points instead — the proactive handoff
+ * notice near the effective handoff budget and the forced CompactionEngine
+ * reduction before any request at or above the effective hard limit — while
+ * reusing the public CompactionEngine implementation. The hard-limit
+ * translation lives in exactly one method; no caller re-derives it.
+ *
+ * Fail-closed rule: at the hard limit, a compaction that no-ops, throws, is
+ * cancelled, or does not advance the durable surface must block the model
+ * request (reject the step) rather than knowingly submit over the Team limit.
+ * A blocked Member keeps its log and reports a recoverable error.
+ * @module @wowyuarm/dsh-agent-team/pressure-policy
+ */
+import { CONTEXT_WINDOW_EXCEEDED_CODE } from '@deepseek-ai/dsh-llm';
+import { createUserMessage } from '@deepseek-ai/dsh-llm';
+import { CONTEXT_PRESSURE_NOTICE_SUMMARY } from "./context-management.js";
+/** Plugin identity of the Agent Team Host, for the notice source. */
+const AGENT_TEAM_PLUGIN_ID = '@wowyuarm/dsh-agent-team';
+/** One pressure-notice text; concise, structured, and inside the reserve. */
+export function contextPressureNoticeText(input) {
+    const claims = input.activeClaims.length === 0 ? 'none' : input.activeClaims.join(', ');
+    const jobs = input.runningJobs.length === 0 ? 'none' : `${input.runningJobs.length} running (collect or stop them before switching)`;
+    return [
+        `Context pressure: ${input.usageTokens} tokens measured; the handoff budget is ${input.handoffAt} and the hard limit is ${input.hardLimit}.`,
+        `Active Claims: ${claims}. Owner jobs: ${jobs}.`,
+        'Finish the current atomic action, then call context_rollover with a handoff covering your objective, verified facts, and external side effects — a fresh context is the default path. Record anything durable in your private memory/notes first.',
+    ].join(' ');
+}
+/** Whether one user message is this policy's one-shot pressure notice. */
+function isPressureNotice(message) {
+    const source = message.source;
+    return source?.plugin === AGENT_TEAM_PLUGIN_ID
+        && source?.summary === CONTEXT_PRESSURE_NOTICE_SUMMARY;
+}
+export class PressurePolicyCoordinator {
+    options;
+    /**
+     * Retry budget per agent for the current provider-overflow sequence.
+     * Process-only by design: a restart re-earns one sequence per chain.
+     */
+    overflowRetries = new Map();
+    disposed = false;
+    constructor(options) {
+        this.options = options;
+    }
+    /**
+     * The one-shot pressure notice is durable Session evidence, not process
+     * state: a `CONTEXT_PRESSURE_NOTICE_SUMMARY` notice already surfaced as a
+     * `user/message`, or still queued in a durable `agent/inbox/spliced`
+     * insert (a steered notice surfaces only at the next step boundary, and a
+     * Host restart replays the splice before surfacing), marks the current
+     * generation as already notified. A resume or restart stays quiet; a
+     * rollover starts a fresh Session whose own event span has no notice yet,
+     * which is exactly the documented re-arm.
+     */
+    noticeDelivered(agent) {
+        for (const event of agent.session.ownEvents()) {
+            if (event.type === 'user/message' && isPressureNotice(event.data))
+                return true;
+            if (event.type === 'agent/inbox/spliced' && event.data.inserted.some(isPressureNotice))
+                return true;
+        }
+        return false;
+    }
+    dispose() {
+        this.disposed = true;
+        this.overflowRetries.clear();
+    }
+    /** A successful assistant response ends any open overflow-recovery sequence. */
+    onAssistantMessage(agent) {
+        this.overflowRetries.delete(agent);
+    }
+    /**
+     * Pre-step policy for one Member agent: below the handoff budget nothing
+     * happens; at the handoff budget one structured notice per generation is
+     * steered into the running turn; at the hard limit the request is forced
+     * through compaction first and fails closed when that cannot be proven.
+     * Returns the decision for the step: `continue` forwards, `reject` blocks.
+     */
+    async onPreStep(agent, signal) {
+        if (this.disposed || signal.aborted)
+            return { kind: 'continue' };
+        const member = this.options.memberForAgent(agent);
+        if (member === undefined)
+            return { kind: 'continue' };
+        const limits = await this.options.limitsForAgent(agent);
+        if (limits === undefined) {
+            // A missing route capacity must be explicit, never an accidental
+            // unlimited policy: reject the step with a recoverable diagnostic.
+            const diagnostic = 'context pressure policy: the routed model capacity is unknown; refusing to forward a request without a bounded context budget';
+            this.options.failed(member.memberId, member.sessionId, diagnostic);
+            return { kind: 'reject' };
+        }
+        const { usageTokens, hardLimit, handoffAt } = limits;
+        if (usageTokens >= hardLimit) {
+            const outcome = await this.enforceHardLimit(agent, member.memberId, member.sessionId, signal);
+            return outcome ? { kind: 'continue' } : { kind: 'reject' };
+        }
+        if (usageTokens >= handoffAt && !this.noticeDelivered(agent)) {
+            const notice = createUserMessage({
+                content: [{ type: 'text', text: contextPressureNoticeText({
+                            usageTokens, handoffAt, hardLimit,
+                            activeClaims: this.options.activeClaimLabels(member.memberId),
+                            runningJobs: this.options.runningJobLabels(member.memberId),
+                        }) }],
+                source: { kind: 'plugin', plugin: AGENT_TEAM_PLUGIN_ID, form: 'notice', summary: CONTEXT_PRESSURE_NOTICE_SUMMARY },
+            });
+            try {
+                agent.steer(notice);
+            }
+            catch (error) {
+                this.options.log(`context pressure notice failed: ${error instanceof Error ? error.message : String(error)} (member ${member.memberId})`);
+            }
+            return { kind: 'notice' };
+        }
+        return { kind: 'continue' };
+    }
+    /**
+     * Provider-overflow recovery: one bounded compact-and-retry sequence per
+     * open failure chain. Returns whether the request may retry once.
+     */
+    async onRequestError(agent, failure, signal) {
+        if (this.disposed || signal.aborted)
+            return false;
+        if (failure.code !== CONTEXT_WINDOW_EXCEEDED_CODE)
+            return false;
+        const member = this.options.memberForAgent(agent);
+        if (member === undefined)
+            return false;
+        const retries = this.overflowRetries.get(agent) ?? 0;
+        if (retries >= 1)
+            return false;
+        const engine = this.options.compactionForAgent(agent);
+        if (engine === undefined)
+            return false;
+        const generation = agent.session.surface.replaceGeneration;
+        try {
+            await engine.compactIfNeeded(agent, 'context-overflow', signal);
+        }
+        catch (error) {
+            // Durable prune progress before a later summary failure justifies the
+            // single retry; cancellation never does.
+            if (!signal.aborted && agent.session.surface.replaceGeneration > generation) {
+                this.overflowRetries.set(agent, retries + 1);
+                return true;
+            }
+            this.options.log(`context-overflow recovery failed: ${error instanceof Error ? error.message : String(error)} (member ${member.memberId})`);
+            return false;
+        }
+        if (signal.aborted || agent.session.surface.replaceGeneration <= generation)
+            return false;
+        this.overflowRetries.set(agent, retries + 1);
+        return true;
+    }
+    /**
+     * The one Team hard-limit translation: force a CompactionEngine reduction
+     * in the current Agent/Session and prove it advanced the durable surface
+     * (or measurably reduced pressure) before continuing. Background jobs are
+     * untouched — compaction never cancels or discards them.
+     * @returns whether the request may proceed.
+     */
+    async enforceHardLimit(agent, memberId, sessionId, signal) {
+        const engine = this.options.compactionForAgent(agent);
+        if (engine === undefined) {
+            const diagnostic = 'context hard limit reached and compaction is unavailable in the Member scope; the request was blocked';
+            this.options.failed(memberId, sessionId, diagnostic);
+            return false;
+        }
+        const meter = agent.ctx.get('tokenMeter');
+        const before = meter?.measure(agent.session)?.totalTokens ?? Number.POSITIVE_INFINITY;
+        const generation = agent.session.surface.replaceGeneration;
+        let result;
+        try {
+            result = await engine.compactIfNeeded(agent, 'context-overflow', signal);
+        }
+        catch (error) {
+            const diagnostic = `context hard limit compaction failed: ${error instanceof Error ? error.message : String(error)}; the request was blocked`;
+            this.options.failed(memberId, sessionId, diagnostic);
+            return false;
+        }
+        if (signal.aborted)
+            return false;
+        const after = meter?.measure(agent.session)?.totalTokens ?? Number.POSITIVE_INFINITY;
+        const surfaceAdvanced = agent.session.surface.replaceGeneration > generation;
+        const pressureReduced = meter === undefined ? false : after < before;
+        if (!surfaceAdvanced && !pressureReduced) {
+            // No-op or unchanged replacement generation: fail closed rather than
+            // knowingly submit over the Team limit.
+            const diagnostic = result === null
+                ? 'context hard limit reached and no compactable range exists; the request was blocked'
+                : 'context hard limit compaction produced no measurable reduction; the request was blocked';
+            this.options.failed(memberId, sessionId, diagnostic);
+            return false;
+        }
+        return true;
+    }
+}