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

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

@@ -15,10 +15,12 @@
  * 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. */
 export const AGENT_TEAM_PLUGIN_ID = '@wowyuarm/dsh-agent-team';
 /**
@@ -50,47 +52,6 @@ export function isAgentTeamSourceKind(kind) {
 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.
@@ -200,32 +161,3 @@ 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,157 @@
+import { readFileSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import z from '@deepseek-ai/schemastery';
+import { parse } from 'yaml';
+/**
+ * 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 are the Team Host row's own Config, so they live in the
+ *   active profile's patch document as that row's `config` and the settings
+ *   service derives their form from this schema. rc.1 derives every form from
+ *   a plugin's Config, so the retired `installSection` namespace — a section of
+ *   its own — has no counterpart; the row id below is the settings namespace.
+ * - avatar bytes live under a persistent directory below; the profile holds
+ *   only the reference, never a data URL. The composer attachment cache is
+ *   TTL-bound and must not hold avatar bytes.
+ */
+/**
+ * Settings namespace of the Human profile: the Team Host row's id in
+ * `cordis.patch.yml`, which is what the settings service addresses a form and a
+ * write by AND the id the profile-document write patches. It is addressed by
+ * this constant, never by the running Host's `ctx.fiber.entry`: a Remote call
+ * runs under its caller's context, so that lookup names the RPC gateway's row.
+ * `shipping.spec.ts` pins the constant to the row the composition declares.
+ */
+export const HUMAN_PROFILE_SETTINGS_NAMESPACE = 'wowyuarm-agent-team-host';
+/** 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, and the current side of the
+ * update check: the version of the package THIS Host runs from — read from the
+ * installed manifest, so a `link:` checkout under the development profile and a
+ * registry tarball under stable each state their own truth. It is not a
+ * hand-maintained string: the 0.1.14 bundle shipped with `0.1.13` written in
+ * it, which made the footnote name the previous release and the update check
+ * offer the release the user already had.
+ *
+ * Resolved once at load, three levels above this module — `packages/agent-team/{src,lib}`
+ * sits that deep in both layouts, the same relative positioning
+ * `member-runtime.ts` uses to find `core-skills`. An unreadable or malformed
+ * manifest degrades to `'unknown'`: the Remote's `version: string` contract
+ * holds and the update comparison simply compares nothing. The footnote is
+ * informational only and never gates behavior.
+ */
+export const HUMAN_PROFILE_VERSION = readInstalledBundleVersion();
+/** Version of the manifest this package installed from, or `'unknown'`. */
+function readInstalledBundleVersion() {
+    try {
+        const manifestPath = resolve(dirname(fileURLToPath(import.meta.url)), '../../../package.json');
+        const manifest = JSON.parse(readFileSync(manifestPath, 'utf8'));
+        if (typeof manifest.version === 'string' && manifest.version !== '')
+            return manifest.version;
+    }
+    catch {
+        // Reading our own manifest must never fail the Host boot: a host that
+        // cannot find its own package.json is a broken install, and the footnote
+        // reporting 'unknown' says so more honestly than a stale number.
+    }
+    return 'unknown';
+}
+/**
+ * Schemastery schema of the Human profile: the Team Host row's Config. Both
+ * fields are volatile, which is what lets an edit reach the running Host
+ * without remounting it — and what makes the settings service derive a form
+ * from this schema at all.
+ */
+export const HUMAN_PROFILE_SETTINGS_SCHEMA = z.object({
+    name: z.string().default(HUMAN_PROFILE_DEFAULT_NAME).volatile(),
+    // Schemastery fields are optional unless `.required()`: a missing avatarRef
+    // simply resolves absent, which the profile reads as "no custom avatar".
+    avatarRef: z.string().volatile(),
+});
+/** 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;
+}
+/**
+ * The retired settings section this profile's facts lived in before rc.1.
+ * rc.1 derives every settings form from a plugin's Config, and its legacy
+ * `settings.yaml` importer maps a section to a composition entry id through a
+ * closed built-in list — this third-party section matches nothing there, so
+ * the import rejects it and the values survive only in the renamed document.
+ * This Host owns the section, so adopting what is left belongs here.
+ */
+export const LEGACY_HUMAN_PROFILE_SECTION = 'agent-team-human';
+/**
+ * Read the legacy section out of one legacy settings document. An
+ * unparsable document or a missing section means "nothing to adopt" rather
+ * than an error — the file is retired input, not an authority — and each
+ * field is validated independently so one bad field never costs the other.
+ */
+export function parseLegacyHumanProfile(yamlText) {
+    let document;
+    try {
+        document = parse(yamlText);
+    }
+    catch {
+        return undefined;
+    }
+    if (typeof document !== 'object' || document === null)
+        return undefined;
+    const section = document[LEGACY_HUMAN_PROFILE_SECTION];
+    if (typeof section !== 'object' || section === null)
+        return undefined;
+    const fields = section;
+    let name;
+    if (typeof fields.name === 'string') {
+        try {
+            name = assertValidHumanName(fields.name);
+        }
+        catch {
+            name = undefined;
+        }
+    }
+    const avatarRef = typeof fields.avatarRef === 'string' && fields.avatarRef.trim() !== ''
+        ? fields.avatarRef.trim()
+        : undefined;
+    if (name === undefined && avatarRef === undefined)
+        return undefined;
+    return { ...(name === undefined ? {} : { name }), ...(avatarRef === undefined ? {} : { avatarRef }) };
+}
+/**
+ * Decide what adoption may write: nothing unless the stored profile is still
+ * the pristine default, so a value the Human re-entered after the upgrade
+ * always wins, and never the legacy default name itself. The current profile
+ * carries explicit `undefined` on `avatarRef` — the Host getter spreads a
+ * settings read — and so is not `HumanProfile` under
+ * exactOptionalPropertyTypes; taking that shape directly keeps the Host call
+ * cast-free. The returned fields are exactly the ops the profile page would
+ * have written; byte existence for `avatarRef` is the caller's I/O and must
+ * already hold.
+ */
+export function planLegacyAdoption(current, legacy) {
+    if (current.name !== HUMAN_PROFILE_DEFAULT_NAME || current.avatarRef !== undefined)
+        return undefined;
+    const name = legacy.name !== undefined && legacy.name !== HUMAN_PROFILE_DEFAULT_NAME ? legacy.name : undefined;
+    const avatarRef = legacy.avatarRef;
+    if (name === undefined && avatarRef === undefined)
+        return undefined;
+    return { ...(name === undefined ? {} : { name }), ...(avatarRef === undefined ? {} : { avatarRef }) };
+}

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 };
+        },
+    };
+}