@wowyuarm/dsh-agent-team 0.1.14-alpha.2 → 0.1.14

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

@@ -1,10 +1,14 @@
 /**
- * Producer-attributed message sources for Agent Team context management.
+ * Plugin-attributed message sources for Agent Team context management.
  *
- * Both sources ride ordinary `UserMessage`s under this plugin's own
- * producer kind with the `snapshot` context form — Session format V4 admits
- * exactly that shape and refuses the retired `{ kind: 'plugin', plugin: … }`
- * wrapper at write time. See `docs/dsh-release-compatibility.md`
+ * Both sources ride ordinary `UserMessage`s under the shipped `plugin` kind
+ * with the `snapshot` context form — the same shape the Harness's own
+ * system-prompt producer writes. This module declares no `MessageSourceMap`
+ * member of its own, and carries no bespoke source members: Session format
+ * migration validates a `plugin` source against a closed member list
+ * (`kind`, `plugin`, `form`, `sections`, `summary`), and refuses every logged
+ * Session that carries anything else. A plugin-declared kind is type-legal yet
+ * refused the same way. See `docs/dsh-release-compatibility.md`
  * § "Session message sources".
  *
  * Everything the Host needs to read back therefore rides the admitted payload
@@ -15,82 +19,18 @@
  * snapshot-aware surface.
  *
  * The validators below are the single place that recognizes these messages, so
- * callers never match on localized body text.
+ * callers never match on localized body text. Writing them belongs to the
+ * context-continuity engine's codec, which Team constructs with its own plugin
+ * identity and prose (`context-continuity-host.ts`): one writer, so the
+ * envelope Team reads back can never drift from the one it wrote.
  * @module @wowyuarm/dsh-agent-team/context-source
  */
-import { createUserMessage } from '@deepseek-ai/dsh-llm';
-/** The producer kind attributing every Agent Team message source. */
+/** Plugin identity attributing every Agent Team message source. */
 export const AGENT_TEAM_PLUGIN_ID = '@wowyuarm/dsh-agent-team';
-/**
- * The kind the Harness's V4 read-time conversion renames this plugin's
- * released V3 `plugin` sources into: `plugin:` + the producer id, with the
- * `plugin` key dropped and every payload field (`form`, `sections`,
- * `summary`) preserved. History read through the new line carries exactly
- * this shape, so the read side recognizes both identities below.
- */
-export const AGENT_TEAM_V3_RENAMED_KIND = `plugin:${AGENT_TEAM_PLUGIN_ID}`;
-/** The kind the read-time conversion renames one producer's released V3 sources into. */
-export const v3RenamedSourceKind = (producer) => `plugin:${producer}`;
-/**
- * Whether one message source carries this plugin's own attribution. Both
- * identities are matched by exact kind equality — never by a `plugin:`
- * prefix test, which would claim third-party producers' rows as Team facts.
- */
-export function isAgentTeamSource(source) {
-    return source.kind === AGENT_TEAM_PLUGIN_ID || source.kind === AGENT_TEAM_V3_RENAMED_KIND;
-}
-/**
- * Whether one source kind carries this plugin's attribution, for call sites
- * whose sources arrive untyped. Exact identities only, never a prefix test.
- */
-export function isAgentTeamSourceKind(kind) {
-    return kind === AGENT_TEAM_PLUGIN_ID || kind === AGENT_TEAM_V3_RENAMED_KIND;
-}
 /** Handoff snapshot section name carrying the model-authored prose. */
 export const HANDOFF_SECTION_NAME = 'HANDOFF';
 /** Stable section name marking a checkpoint continuation and carrying its ref. */
 export const CHECKPOINT_SECTION_NAME = 'Checkpoint';
-/** Fixed text of the quiet checkpoint continuation delivered on the next turn. */
-export const CHECKPOINT_CONTINUATION_TEXT = 'A context checkpoint was recorded at the end of the previous turn. Continue the work you were doing.';
-/**
- * Build the first model-facing context of one rollover generation. The Host
- * owns only the verifiable envelope; the prose is the Member's own handoff.
- *
- * The envelope sections are additive structure, not the only carrier of these
- * facts: {@link handoffBody} already states them in the model-facing text, so a
- * surface that renders only the body loses nothing.
- */
-export function createHandoffMessage(input) {
-    return createUserMessage({
-        content: [{ type: 'text', text: handoffBody(input) }],
-        source: {
-            kind: AGENT_TEAM_PLUGIN_ID,
-            form: 'snapshot',
-            sections: handoffSections(input),
-        },
-    });
-}
-/**
- * Build the quiet follow-up that continues work after an explicit checkpoint
- * concluded its turn. Delivery is scheduled only after the checkpoint's
- * successful tool result is durable, so a result-render failure can never
- * leave a ghost continuation behind.
- *
- * This is a `snapshot` rather than a `notice` for one reason: the projection
- * must read the checkpoint ref back out of the durable log to record delivery,
- * and `sections` is the only admitted payload slot that carries structure. A
- * notice would have forced the ref into its human-readable one-line summary.
- */
-export function createCheckpointContinuationMessage(checkpointRef) {
-    return createUserMessage({
-        content: [{ type: 'text', text: CHECKPOINT_CONTINUATION_TEXT }],
-        source: {
-            kind: AGENT_TEAM_PLUGIN_ID,
-            form: 'snapshot',
-            sections: [{ name: CHECKPOINT_SECTION_NAME, text: checkpointRef }],
-        },
-    });
-}
 /**
  * Read one message's snapshot sections when it is this plugin's own snapshot.
  * @param message - candidate user message.
@@ -98,7 +38,7 @@ export function createCheckpointContinuationMessage(checkpointRef) {
  */
 function ownSections(message) {
     const source = message.source;
-    if (!isAgentTeamSource(source))
+    if (source.kind !== 'plugin' || source.plugin !== AGENT_TEAM_PLUGIN_ID)
         return undefined;
     if (source.form !== 'snapshot')
         return undefined;
@@ -192,40 +132,11 @@ export function isAgentTeamContextSource(message) {
     return isHandoffMessage(message) || isCheckpointContinuationMessage(message);
 }
 /** Envelope section names; stable, because they are read back from the log.
- * One shared vocabulary for writer and reader — no drift between the shape
- * published at rollover and the shape the projection folds back. */
+ * Exported for the legacy-artifact remediation, which rewrites pre-0.1.10
+ * envelopes into exactly these names — one shared vocabulary, no drift. */
 export const HANDOFF_PREVIOUS_SESSION = 'Previous session';
 export const HANDOFF_NEW_SESSION = 'New session';
 export const HANDOFF_TRIGGER = 'Trigger';
 export const HANDOFF_EVENT_SEQ = 'Handoff event seq';
 export const HANDOFF_CHECKPOINT = 'Continued from checkpoint';
 export const HANDOFF_RELATED_FILES = 'Related files';
-/** The envelope contributions of one handoff, prose first. */
-function handoffSections(input) {
-    return [
-        { name: HANDOFF_SECTION_NAME, text: input.handoff },
-        { name: HANDOFF_PREVIOUS_SESSION, text: input.previousSessionId },
-        { name: HANDOFF_NEW_SESSION, text: input.newSessionId },
-        { name: HANDOFF_TRIGGER, text: input.trigger },
-        { name: HANDOFF_EVENT_SEQ, text: String(input.handoffEventSeq) },
-        ...(input.checkpointRef === undefined ? [] : [{ name: HANDOFF_CHECKPOINT, text: input.checkpointRef }]),
-        ...(input.relatedFiles === undefined || input.relatedFiles.length === 0
-            ? []
-            : [{ name: HANDOFF_RELATED_FILES, text: JSON.stringify(input.relatedFiles.map(file => file.path)) }]),
-    ];
-}
-function handoffBody(input) {
-    const lines = [
-        'Context handoff: you are continuing as the same Team Member in a fresh private context.',
-        `Previous session: ${input.previousSessionId}`,
-        `New session: ${input.newSessionId}`,
-        `Trigger: ${input.trigger}`,
-        ...(input.checkpointRef === undefined ? [] : [`Continued from checkpoint: ${input.checkpointRef}`]),
-        ...(input.relatedFiles === undefined || input.relatedFiles.length === 0 ? [] : [`Related files: ${input.relatedFiles.map(file => file.path).join(', ')}`]),
-        '',
-        'Your handoff from the previous context follows. Verify external state before relying on it; a context change never rolls back files, processes, Team facts, or remote side effects.',
-        '',
-        input.handoff,
-    ];
-    return lines.join('\n');
-}

package/packages/agent-team/lib/human-avatar.js

@@ -0,0 +1,61 @@
+import { mkdir, readFile, readdir, rm, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { dshHomePath } from '@deepseek-ai/dsh-home-paths';
+import { ATTACHMENT_MAX_BYTES, sanitizeFileName, sanitizeMediaType } from "./attachments.js";
+/**
+ * Persistent human avatar store. Layout mirrors the composer attachment
+ * cache (`<avatarRef>/` payload plus `meta.json`) but lives under its own
+ * root with no TTL sweep: avatar bytes must survive longer than the 72h
+ * referenced / 24h orphan windows that bound message attachments.
+ */
+export function humanAvatarsRoot() {
+    return dshHomePath('agent-team', 'human', 'v1');
+}
+function avatarDir(root, avatarRef) {
+    return join(root, avatarRef);
+}
+/** Accept only image payloads; the settings page sends `image/*` exclusively. */
+export function assertAvatarMediaType(mediaType) {
+    const sanitized = sanitizeMediaType(mediaType);
+    if (!sanitized.startsWith('image/'))
+        throw new Error(`human avatar must be an image (got '${mediaType}')`);
+    return sanitized;
+}
+/** Write one avatar as an immutable entry; the caller stores the ref in settings. */
+export async function writeHumanAvatar(root, rawName, mediaType, bytes) {
+    if (bytes.byteLength === 0)
+        throw new Error('human avatar must not be empty');
+    if (bytes.byteLength > ATTACHMENT_MAX_BYTES)
+        throw new Error(`human avatar exceeds the ${ATTACHMENT_MAX_BYTES} byte limit`);
+    const storedMediaType = assertAvatarMediaType(mediaType);
+    const name = sanitizeFileName(rawName);
+    const avatarRef = randomUUID();
+    const dir = avatarDir(root, avatarRef);
+    await mkdir(dir, { recursive: true });
+    await writeFile(join(dir, name), bytes);
+    await writeFile(join(dir, 'meta.json'), JSON.stringify({ name, mediaType: storedMediaType, uploadedAt: new Date().toISOString() }), 'utf8');
+    return { avatarRef, path: join(dir, name), name, byteSize: bytes.byteLength, mediaType: storedMediaType };
+}
+/** Read one avatar back; `undefined` when removed or never written. */
+export async function readHumanAvatar(root, avatarRef) {
+    const dir = avatarDir(root, avatarRef);
+    let metaRaw;
+    try {
+        metaRaw = await readFile(join(dir, 'meta.json'));
+    }
+    catch {
+        return undefined;
+    }
+    const meta = JSON.parse(metaRaw.toString('utf8'));
+    const entries = await readdir(dir);
+    const payload = entries.filter(entry => entry !== 'meta.json')[0];
+    if (payload === undefined)
+        return undefined;
+    const bytes = await readFile(join(dir, payload));
+    return { name: meta.name, mediaType: meta.mediaType, byteSize: bytes.byteLength, uploadedAt: meta.uploadedAt, bytes };
+}
+/** Remove one avatar entry; missing entries already satisfy the removal. */
+export async function removeHumanAvatar(root, avatarRef) {
+    await rm(avatarDir(root, avatarRef), { recursive: true, force: true });
+}

package/packages/agent-team/lib/human-profile.js

@@ -0,0 +1,46 @@
+import z from '@deepseek-ai/schemastery';
+/**
+ * Human identity profile: the one configurable display name plus the avatar
+ * reference. `member:human` stays the durable identity everywhere; only the
+ * handle shown in team_view, @ matching, and UI follows this profile.
+ *
+ * Storage split (see spec.md v1):
+ * - name + avatarRef live in the Host settings namespace `agent-team-human`
+ *   (settings.yaml user layer, live through `ctx.settings`).
+ * - avatar bytes live under a persistent directory below; the settings
+ *   document holds only the reference, never a data URL. The composer
+ *   attachment cache is TTL-bound and must not hold avatar bytes.
+ */
+export const HUMAN_PROFILE_SETTINGS_NAMESPACE = 'agent-team-human';
+/** Fallback display name before any user override is stored. */
+export const HUMAN_PROFILE_DEFAULT_NAME = 'human';
+/** Repository home for the version footnote link. */
+export const HUMAN_PROFILE_REPO_URL = 'https://github.com/wowyuarm/dsh-agent-team';
+/**
+ * Bundle version shown in the settings footnote. Kept in sync with the root
+ * package.json by hand until the Host build injects it; the footnote is
+ * informational only and never gates behavior.
+ */
+export const HUMAN_PROFILE_VERSION = '0.1.13';
+/** Schemastery schema resolving the `agent-team-human` namespace value. */
+export const HUMAN_PROFILE_SETTINGS_SCHEMA = z.object({
+    name: z.string().default(HUMAN_PROFILE_DEFAULT_NAME),
+    // Schemastery fields are optional unless `.required()`: a missing avatarRef
+    // simply resolves absent, which the profile reads as "no custom avatar".
+    avatarRef: z.string(),
+});
+/** Normalize one candidate display name the way Member handles normalize. */
+export function normalizeHumanName(raw) {
+    return raw.normalize('NFKC').trim();
+}
+/**
+ * Validate one candidate display name with the same floor as Member handles:
+ * non-empty after trim. Uniqueness against live Members is checked by the
+ * Host (which owns the ledger), not here, so this stays a pure function.
+ */
+export function assertValidHumanName(raw) {
+    const name = normalizeHumanName(raw);
+    if (name === '')
+        throw new Error('human name must not be empty');
+    return name;
+}

package/packages/agent-team/lib/human-update-check.js

@@ -0,0 +1,119 @@
+/**
+ * Best-effort Host-side check for a newer published bundle release.
+ *
+ * The settings footnote needs `updateAvailable`/`latestVersion`, but the
+ * profile read path must never wait on the network: the checker serves a
+ * cached snapshot synchronously and refreshes it in the background. Every
+ * failure mode — disabled by the operator, no fetch implementation, timeout,
+ * non-OK status, malformed payload, unparsable version — settles as "no
+ * update known", so the footnote degrades to version + link exactly as before.
+ *
+ * No durable state: the cache lives only in memory. A Host restart simply
+ * starts unknown again, which is the safe default for an informational tip.
+ */
+/** Public npm metadata document for the bundle's `latest` dist-tag. */
+export const HUMAN_UPDATE_CHECK_REGISTRY_URL = 'https://registry.npmjs.org/@wowyuarm%2fdsh-agent-team/latest';
+/** How long one settled check stays authoritative before a re-check. */
+export const HUMAN_UPDATE_CHECK_TTL_MS = 12 * 60 * 60 * 1000;
+/** Upper bound for one registry round trip; the read path never waits on it. */
+export const HUMAN_UPDATE_CHECK_TIMEOUT_MS = 5000;
+/** Setting this env var to `0`/`false`/`off` disables the outbound check. */
+export const HUMAN_UPDATE_CHECK_ENV = 'DSH_AGENT_TEAM_UPDATE_CHECK';
+/** Operator kill-switch; anything but an explicit off value keeps the default on. */
+export function isUpdateCheckEnabled(env = process.env) {
+    const raw = env[HUMAN_UPDATE_CHECK_ENV]?.trim().toLowerCase();
+    return raw !== '0' && raw !== 'false' && raw !== 'off';
+}
+/**
+ * Numeric core of a `major.minor.patch…` version. Pre-release/build suffixes
+ * are ignored for ordering; anything else unparsable resolves absent so the
+ * caller treats it as "no update known" instead of guessing.
+ */
+export function parseVersionCore(value) {
+    const core = value.split('+', 1)[0]?.split('-', 1)[0];
+    if (core === undefined || core === '')
+        return undefined;
+    const parts = core.split('.');
+    const numbers = [];
+    for (const part of parts) {
+        if (part === '' || !/^[0-9]+$/.test(part))
+            return undefined;
+        numbers.push(Number(part));
+    }
+    return numbers.length === 0 ? undefined : numbers;
+}
+/** True when `latest` orders strictly after `current` on the numeric core. */
+export function isNewerVersion(current, latest) {
+    const from = parseVersionCore(current);
+    const to = parseVersionCore(latest);
+    if (from === undefined || to === undefined)
+        return false;
+    const width = Math.max(from.length, to.length);
+    for (let index = 0; index < width; index += 1) {
+        const left = from[index] ?? 0;
+        const right = to[index] ?? 0;
+        if (right !== left)
+            return right > left;
+    }
+    return false;
+}
+/**
+ * One registry round trip resolving the published `latest` version string.
+ * Never throws: anything unexpected resolves absent.
+ */
+export async function fetchLatestVersion(fetchImpl, url = HUMAN_UPDATE_CHECK_REGISTRY_URL, timeoutMs = HUMAN_UPDATE_CHECK_TIMEOUT_MS) {
+    try {
+        const response = await fetchImpl(url, { signal: AbortSignal.timeout(timeoutMs) });
+        if (!response.ok)
+            return undefined;
+        const payload = (await response.json());
+        return typeof payload?.version === 'string' ? payload.version : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Synchronous snapshot over a background-refreshed latest-version cache.
+ * `snapshot()` never blocks: a stale or empty cache serves the last known
+ * value (initially "no update") and kicks off at most one shared refresh.
+ * Concurrent and repeated calls while a refresh is in flight share it, and a
+ * refresh that settles only stamps the cache — failures simply leave the
+ * previous value standing.
+ */
+export function createHumanUpdateChecker(options) {
+    const { currentVersion, ttlMs = HUMAN_UPDATE_CHECK_TTL_MS, timeoutMs = HUMAN_UPDATE_CHECK_TIMEOUT_MS, now = Date.now, env = process.env, } = options;
+    const fetchImpl = options.fetchImpl ?? ((url, init) => globalThis.fetch(url, init));
+    let latestVersion;
+    let checkedAt = Number.NEGATIVE_INFINITY;
+    let inFlight;
+    const refresh = () => {
+        if (inFlight !== undefined)
+            return;
+        if (!isUpdateCheckEnabled(env))
+            return;
+        const settled = fetchLatestVersion(fetchImpl, HUMAN_UPDATE_CHECK_REGISTRY_URL, timeoutMs).then(version => {
+            checkedAt = now();
+            if (version !== undefined && isNewerVersion(currentVersion, version))
+                latestVersion = version;
+        });
+        const tracked = settled.finally(() => {
+            if (inFlight === tracked)
+                inFlight = undefined;
+        });
+        inFlight = tracked;
+        // Rejections are already absorbed inside fetchLatestVersion, but the
+        // finally chain still needs a settlement handler so a Host without an
+        // unhandled-rejection policy never sees one from this floating refresh.
+        void tracked.catch(() => { });
+    };
+    return {
+        snapshot: () => {
+            if (checkedAt + ttlMs <= now())
+                refresh();
+            if (latestVersion === undefined)
+                return { updateAvailable: false };
+            return { updateAvailable: true, latestVersion };
+        },
+    };
+}