@wowyuarm/dsh-agent-team 0.1.9 → 0.1.11

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

@@ -61,16 +61,20 @@ export function renderMemberIdentity(member) {
         ? `Team identity: you are @${member.handle}.`
         : `Team identity: you are @${member.handle} — ${member.description}`;
 }
+/** The four private-memory paths plus the out-of-cwd warning; callers append their own sentence. */
+function memoryPathsBlock(privateMemoryPath) {
+    return `Private memory directory: ${privateMemoryPath}\nMemory index: ${privateMemoryPath}/memory.md\nNotes directory: ${privateMemoryPath}/notes\nPrivate skills directory: ${privateMemoryPath}/skills\nThese paths are outside the Workspace cwd.`;
+}
 export function renderMemberMemory(raw, privateMemoryPath = '<private-memory-path>') {
     const overBudget = raw.byteLength > MAX_MEMORY_BYTES;
     const body = overBudget ? '' : raw.toString('utf8');
     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\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. Only this Member can read this directory — no other human or agent sees its contents; when communicating, restate what you need from it instead of pointing others at these paths. 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\n${memoryPathsBlock(privateMemoryPath)} Relative filesystem paths resolve from cwd, so use the absolute paths above when reading or editing this Member's memory. Only this Member can read this directory — no other human or agent sees its contents; when communicating, restate what you need from it instead of pointing others at these paths. 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\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}`;
+    return `${BEGIN}\nThis is the complete replacement for this Team Member's private memory index; all earlier private-memory context is obsolete. ${reason}\n\n${memoryPathsBlock(privateMemoryPath)} 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-time-context.js

@@ -0,0 +1,141 @@
+/**
+ * Team Member turn-level clock context.
+ *
+ * The first model step of every eligible Team Member turn appends one
+ * durable, source-attributed clock snapshot: the current instant in the
+ * fixed Team coordination zone (UTC+8), the elapsed time since the
+ * preceding model-visible event, and the ordering authority note. Later
+ * steps of the same turn stay quiet unless the turn runs longer than the
+ * refresh interval, in which case one snapshot lands per elapsed interval —
+ * a tool-dense turn of quick steps produces exactly one line, while a turn
+ * that outlives the interval still shows its real span. The snapshot is an
+ * observation, never ledger authority: sequence and revision, not
+ * wall-clock time, order Team facts.
+ *
+ * This plugin deliberately does not mount the shipped
+ * `@deepseek-ai/dsh-time-context`: its browser-zone policy asks the model to
+ * confirm dates with the user whenever a request carries no unique browser
+ * zone, which is the normal case for background Member wakes (Inbox, DM,
+ * recovery, continuation). The Team coordination zone is fixed instead. If
+ * the harness grows a public non-browser/canonical-zone policy, retire this
+ * row in favor of configuring that plugin.
+ *
+ * State is folded from the Member Session's own events — the same
+ * manual-fold pattern the Host's context projection uses — so restart,
+ * request reconstruction, and compaction all derive identical baselines
+ * without a second durable store.
+ * @module @wowyuarm/dsh-agent-team/member-time-context
+ */
+import { createUserMessage } from '@deepseek-ai/dsh-llm';
+import { formatTeamDuration, formatTeamTimestamp } from "./time-format.js";
+import { advanceOwnedSessionEventCursor } from "./session-event-cursor.js";
+export const name = 'wowyuarm-agent-team-member-time-context';
+/** Default minimum spacing between two snapshots within one turn, in ms. */
+export const CLOCK_REFRESH_INTERVAL_MS = 1_800_000;
+function emptyBaseline() {
+    return { lastMessageTime: null, lastInjectionTime: null, lastTurnInjectionTime: null, openTurn: -1 };
+}
+/**
+ * Fold one session event into the clock baseline. Uninterested events return
+ * the same state reference.
+ * @internal exported for tests.
+ */
+export function applyClockEvent(state, event) {
+    switch (event.type) {
+        case 'turn/start':
+            return event.data.turn === state.openTurn ? state
+                : { ...state, lastTurnInjectionTime: null, openTurn: event.data.turn };
+        case 'turn/end':
+            return state.openTurn === -1 ? state : { ...state, lastTurnInjectionTime: null, openTurn: -1 };
+        case 'user/message': {
+            const source = event.data.source;
+            const injected = source.kind === 'plugin' && source.plugin === name;
+            const withMessage = state.lastMessageTime === event.time ? state : { ...state, lastMessageTime: event.time };
+            if (!injected)
+                return withMessage;
+            return { ...withMessage, lastInjectionTime: event.time, lastTurnInjectionTime: event.time };
+        }
+        case 'assistant/message':
+        case 'tool/result':
+            return state.lastMessageTime === event.time ? state : { ...state, lastMessageTime: event.time };
+        default:
+            return state;
+    }
+}
+/** Fold a whole event log into the clock baseline. @internal exported for tests. */
+export function foldClockBaseline(events) {
+    let state = emptyBaseline();
+    for (const event of events)
+        state = applyClockEvent(state, event);
+    return state;
+}
+/**
+ * Whether this step should append a clock snapshot: the first step of a turn
+ * always does (every wake starts with a fresh instant), and a later step
+ * does only when the turn has run longer than the refresh interval since
+ * the last landed snapshot. Skipped steps produce nothing and never
+ * backfill — their span folds into the next snapshot's elapsed.
+ * @internal exported for tests.
+ */
+export function shouldSampleClock(step, now, baseline, refreshIntervalMs) {
+    if (step === 1)
+        return true;
+    return baseline.lastTurnInjectionTime === null || now - baseline.lastTurnInjectionTime >= refreshIntervalMs;
+}
+/** Render one durable clock snapshot text. @internal exported for tests. */
+export function renderClockSnapshot(input) {
+    // A wall-clock rollback clamps elapsed to 0s without rewriting history.
+    const elapsed = input.previous === undefined ? 'unavailable' : formatTeamDuration(input.now - input.previous);
+    const baseline = input.step === 1 ? 'model-visible event' : 'step context';
+    return `Team clock sampled while preparing turn ${input.turn}, step ${input.step}: ${formatTeamTimestamp(new Date(input.now).toISOString())}\n`
+        + `Elapsed since the preceding ${baseline}: ${elapsed}.\n`
+        + 'Team collaboration timestamps use UTC+8. Sequence and revision, not wall-clock time, determine ordering and concurrency.';
+}
+/**
+ * The clock baseline folded incrementally over one Session's own events. A
+ * rollover starts a fresh Session log, and the cache below is keyed by Session
+ * id, so the fold never guesses elapsed across generations: a missing prior
+ * event renders `unavailable`, not a fabricated baseline.
+ */
+const CLOCK_FOLD = {
+    start: emptyBaseline(),
+    step: (state, event) => applyClockEvent(state, event),
+};
+export function apply(ctx, config = {}) {
+    const refreshIntervalMs = config.refreshIntervalMs ?? CLOCK_REFRESH_INTERVAL_MS;
+    // Per-step fold state, reused for this plugin lifecycle: one entry per
+    // Member, replaced when that Member's Session changes, so a rollover neither
+    // resumes across generations nor retains every generation it leaves behind.
+    const cursors = new Map();
+    ctx.on('agent/pre-step', async ({ agent, turn, step, signal }, next) => {
+        const decision = await next();
+        if (decision.kind === 'reject' || signal.aborted)
+            return decision;
+        // The Host service is resolved at step time, never through plugin inject
+        // (same reason as member-context: the row mounts while the Host itself
+        // is still restoring Members).
+        const host = ctx.get('agentTeam');
+        if (host === undefined)
+            return decision;
+        const member = host.memberForAgent(agent);
+        if (member === undefined)
+            return decision;
+        const now = Date.now();
+        const owned = advanceOwnedSessionEventCursor(cursors.get(member.memberId), agent.session.id, CLOCK_FOLD, agent.session.ownEvents(), agent.session.inheritedEventCount);
+        cursors.set(member.memberId, owned);
+        const baseline = owned.cursor.value;
+        // Turn-first-step always samples; later steps sample only at the refresh
+        // interval, so a quick tool-dense turn stays at one line.
+        if (!shouldSampleClock(step, now, baseline, refreshIntervalMs))
+            return decision;
+        const previous = step === 1
+            ? baseline.lastMessageTime ?? undefined
+            : baseline.lastTurnInjectionTime ?? undefined;
+        const text = renderClockSnapshot({ now, turn, step, previous });
+        const message = createUserMessage({
+            content: [{ type: 'text', text }],
+            source: { kind: 'plugin', plugin: name, form: 'snapshot', sections: [{ name, text }] },
+        });
+        return { kind: 'enter', messages: [...decision.messages, message] };
+    }, { prepend: true });
+}

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

@@ -17,8 +17,27 @@
 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';
+import { AGENT_TEAM_PLUGIN_ID } from "./context-source.js";
+import { advanceOwnedSessionEventCursor } from "./session-event-cursor.js";
+/**
+ * Whether this Session's own span already carries the pressure notice: either
+ * surfaced as a `user/message` or still queued in a durable
+ * `agent/inbox/spliced` insert. Expressed as a fold rather than a scan because
+ * the answer is monotone — once delivered it stays delivered for the
+ * generation — so the cursor only ever has to read events it has not seen.
+ */
+export const PRESSURE_NOTICE_FOLD = {
+    start: false,
+    step: (delivered, event) => {
+        if (delivered)
+            return true;
+        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;
+    },
+};
 /** One pressure-notice text; concise, structured, and inside the reserve. */
 export function contextPressureNoticeText(input) {
     const claims = input.activeClaims.length === 0 ? 'none' : input.activeClaims.join(', ');
@@ -42,6 +61,14 @@ export class PressurePolicyCoordinator {
      * Process-only by design: a restart re-earns one sequence per chain.
      */
     overflowRetries = new Map();
+    /**
+     * Whether the one-shot notice was already delivered, folded incrementally per
+     * Member. The scan below is a monotone "has this ever happened" fold over the
+     * Session's own events, so a cursor can replace re-scanning the whole log on
+     * every step; identity guarding falls back to a cold fold when the Member's
+     * Session changed under the entry.
+     */
+    noticeSeen = new Map();
     disposed = false;
     constructor(options) {
         this.options = options;
@@ -56,14 +83,10 @@ export class PressurePolicyCoordinator {
      * 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;
+    noticeDelivered(agent, memberId) {
+        const owned = advanceOwnedSessionEventCursor(this.noticeSeen.get(memberId), agent.session.id, PRESSURE_NOTICE_FOLD, agent.session.ownEvents(), agent.session.inheritedEventCount);
+        this.noticeSeen.set(memberId, owned);
+        return owned.cursor.value;
     }
     dispose() {
         this.disposed = true;
@@ -99,7 +122,7 @@ export class PressurePolicyCoordinator {
             const outcome = await this.enforceHardLimit(agent, member.memberId, member.sessionId, signal);
             return outcome ? { kind: 'continue' } : { kind: 'reject' };
         }
-        if (usageTokens >= handoffAt && !this.noticeDelivered(agent)) {
+        if (usageTokens >= handoffAt && !this.noticeDelivered(agent, member.memberId)) {
             const notice = createUserMessage({
                 content: [{ type: 'text', text: contextPressureNoticeText({
                             usageTokens, handoffAt, hardLimit,

package/packages/agent-team/lib/progress-nudge.js

@@ -22,7 +22,7 @@
  * @module @wowyuarm/dsh-agent-team/progress-nudge
  */
 import { createUserMessage } from '@deepseek-ai/dsh-llm';
-const PROGRESS_NUDGE_PLUGIN_ID = '@wowyuarm/dsh-agent-team';
+import { AGENT_TEAM_PLUGIN_ID, isCheckpointContinuationMessage } from "./context-source.js";
 /** Notice summary for every nudge this Coordinator injects. */
 export const PROGRESS_NUDGE_NOTICE_SUMMARY = 'Progress visibility reminder';
 export const PROGRESS_NUDGE_TOOL_CALLS_START = 20;
@@ -39,7 +39,7 @@ export function isPublicCommunicationOperationKind(kind) {
 /** Whether one message is a nudge notice this module injected. */
 export function isProgressNudgeNotice(message) {
     const source = message.source;
-    return source.kind === 'plugin' && source.plugin === PROGRESS_NUDGE_PLUGIN_ID
+    return source.kind === 'plugin' && source.plugin === AGENT_TEAM_PLUGIN_ID
         && source.form === 'notice' && source.summary === PROGRESS_NUDGE_NOTICE_SUMMARY;
 }
 /**
@@ -218,7 +218,7 @@ export class ProgressNudgeCoordinator {
         const claimTargets = claimDue ? freshClaimTargets : [];
         const notice = createUserMessage({
             content: [{ type: 'text', text: nudgeNoticeText(state.silentToolCalls, progressTargets, claimTargets) }],
-            source: { kind: 'plugin', plugin: PROGRESS_NUDGE_PLUGIN_ID, form: 'notice', summary: PROGRESS_NUDGE_NOTICE_SUMMARY },
+            source: { kind: 'plugin', plugin: AGENT_TEAM_PLUGIN_ID, form: 'notice', summary: PROGRESS_NUDGE_NOTICE_SUMMARY },
         });
         const pending = {
             messageId: notice.id,
@@ -268,7 +268,15 @@ export class ProgressNudgeCoordinator {
     hasBlockingNotice(agent) {
         for (const message of [...agent.inbox.nextStep, ...agent.inbox.nextTurn]) {
             const source = message.source;
-            if (source.kind !== 'plugin' || source.plugin !== PROGRESS_NUDGE_PLUGIN_ID || source.form !== 'notice')
+            if (source.kind !== 'plugin' || source.plugin !== AGENT_TEAM_PLUGIN_ID)
+                continue;
+            // A queued checkpoint continuation is a pending wake that outranks a
+            // nudge exactly as the notice families above do. It rides the snapshot
+            // form (it must carry its checkpoint ref in a section), so it cannot be
+            // recognized by the notice summary check below.
+            if (isCheckpointContinuationMessage(message))
+                return true;
+            if (source.form !== 'notice')
                 continue;
             if (source.summary !== PROGRESS_NUDGE_NOTICE_SUMMARY)
                 return true;

package/packages/agent-team/lib/session-event-cursor.js

@@ -0,0 +1,116 @@
+/**
+ * Incremental Session-log fold with an identity guard.
+ *
+ * Several Host projections are pure left folds over one Member Session's own
+ * events: context intent, the clock baseline, and the one-shot pressure
+ * notice. Folding the whole log on every event makes each of them cost
+ * O(session length) per step, so a long Session gets steadily slower. This
+ * module keeps the fold value together with how far it has consumed the log,
+ * so a step folds only the tail that arrived since — the same idiom the
+ * Harness Session itself uses for its own derived folds.
+ *
+ * The module is deliberately Session-agnostic: it takes a plain event array
+ * plus the log offset that array starts at, so a caller (including a
+ * measurement harness) can drive it without constructing a Session.
+ *
+ * Correctness rests on the log being append-only, which it is: Session logs
+ * have no truncation API, `seq` is the log index, and `seq === log.length` is
+ * a documented contiguity contract. A Session adopts a different log only by
+ * being constructed from another seed, which replaces the whole slice rather
+ * than editing one position.
+ *
+ * The guard covers the observable ways that contract can break: a changed
+ * `logFrom`, a shorter log, a different event type at the anchor. Each
+ * re-folds from `logFrom`, so a fork, resume, or rollover degrades to the cost
+ * of a cold fold and never to a wrong picture.
+ *
+ * Named residual: the guard anchors on `(seq, type)`, so an event replaced in
+ * place by another of the SAME type at the SAME seq is not detected, and the
+ * cursor would keep its old value and fold only the tail. Reaching that state
+ * requires a caller to violate the append-only contract above — reading one
+ * Session's cursor against a log someone rewrote in place. A content-sensitive
+ * anchor would not close it either: only the anchor position is re-read, so a
+ * swap at any earlier folded position passes a boundary digest just as
+ * silently, while costing a payload digest on every advance. Closing it
+ * properly means fingerprinting every folded event, which is the full refold
+ * this module exists to avoid; if the contract ever changes, that is the fix.
+ * @module @wowyuarm/dsh-agent-team/session-event-cursor
+ */
+/**
+ * Open a cursor for a log slice that starts at `logFrom` (a Session's
+ * `inheritedEventCount` for its own events, or 0 for a full log). Nothing is
+ * consumed yet, so the first {@link advanceSessionEventCursor} folds the whole
+ * slice.
+ */
+export function initSessionEventCursor(fold, logFrom = 0) {
+    return { value: fold.start, foldedThrough: logFrom, logFrom, anchor: null };
+}
+/**
+ * Fold the log tail that arrived since the cursor stopped and return the
+ * advanced cursor; the same reference comes back when there is nothing new.
+ *
+ * `events` is the slice starting at `logFrom`, and `logEnd` is the EXCLUSIVE
+ * end offset of that slice in the owning log — the same coordinate space as
+ * `logFrom`, not `events.length`. An inherited Session's own events start at
+ * its `inheritedEventCount`, so for a 14-event log with 10 inherited events
+ * the slice is `events[0..4]` spanning `logFrom = 10` to `logEnd = 14`. This
+ * mirrors the Session's own `snapshotEvents(fromSeq, toSeqExclusive)`.
+ *
+ * Both offsets are passed explicitly rather than read from the cursor so the
+ * caller states the log it is folding, which is also what makes the fallback
+ * below decidable.
+ */
+export function advanceSessionEventCursor(cursor, events, logFrom, logEnd, fold) {
+    if (logEnd !== logFrom + events.length) {
+        // The slice and the log it claims to describe disagree, so the tail it is
+        // missing is indistinguishable from events that were never there. Refuse
+        // rather than fold a shape the caller did not state.
+        throw new RangeError(`session event cursor: ${events.length} events cannot span [${logFrom}, ${logEnd})`);
+    }
+    // Resume only from a position the log can still justify. Every other case
+    // re-folds from `logFrom`: one path handles truncation, a changed fork
+    // prefix, and a rebuilt log alike, so no caller has to classify them.
+    const resumable = cursor.logFrom === logFrom
+        && cursor.foldedThrough >= logFrom
+        && cursor.foldedThrough <= logEnd
+        && (cursor.foldedThrough === logFrom || anchorMatches(cursor, events));
+    const from = resumable ? cursor.foldedThrough : logFrom;
+    if (from === logEnd)
+        return cursor;
+    let value = resumable ? cursor.value : fold.start;
+    for (let index = from; index < logEnd; index += 1)
+        value = fold.step(value, events[index - logFrom]);
+    return { value, foldedThrough: logEnd, logFrom, anchor: anchorOf(events[logEnd - 1 - logFrom]) };
+}
+/**
+ * Whether the event the cursor stopped on still occupies that position with
+ * the type it had. The position is checked as well as the type because `seq`
+ * is a log index: an event that moved is a different event.
+ */
+function anchorMatches(cursor, events) {
+    const anchor = cursor.anchor;
+    if (anchor === null)
+        return false;
+    const seen = events[anchor.seq - cursor.logFrom];
+    return seen !== undefined && seen.seq === anchor.seq && seen.type === anchor.type;
+}
+/** The identity a cursor anchors on when it stops at the last consumed event. */
+function anchorOf(event) {
+    if (event === undefined)
+        return null;
+    return { seq: event.seq, type: event.type };
+}
+/**
+ * Advance one owner's fold and answer with the entry to store back, so every
+ * caller keeps the same one-entry-per-owner invariant.
+ *
+ * `events` is that Session's whole own-events slice starting at `logFrom` (its
+ * `inheritedEventCount`), so the slice's end is the log's end. The cursor is
+ * resumed only while `owned` still belongs to `sessionId`; every other case
+ * starts cold at `logFrom`, which is the same degradation the cursor's own
+ * guard performs for a rewritten log.
+ */
+export function advanceOwnedSessionEventCursor(owned, sessionId, fold, events, logFrom) {
+    const cursor = owned !== undefined && owned.sessionId === sessionId ? owned.cursor : initSessionEventCursor(fold, logFrom);
+    return { sessionId, cursor: advanceSessionEventCursor(cursor, events, logFrom, logFrom + events.length, fold) };
+}