vgxness 1.20.4 → 1.20.6

package/dist/application/agents/agent-selector-resolver.js

@@ -0,0 +1,28 @@
+import { agentLookupContexts } from './agent-lookup-contexts.js';
+export const agentSelectorNameFallbackCode = 'AGENT_SELECTOR_NAME_FALLBACK';
+export function resolveAgentSelector(input, lookup) {
+    const byId = lookup.getById(input.selector);
+    if (byId.ok)
+        return ok({ agent: byId.value });
+    for (const context of agentLookupContexts(input.project, input.scope)) {
+        const byName = lookup.getByName(context.project, context.scope, input.selector);
+        if (byName.ok) {
+            return ok({
+                agent: byName.value,
+                warning: `${agentSelectorNameFallbackCode}: selector "${input.selector}" matched agent name in ${context.project}/${context.scope}; using canonical agent id "${byName.value.id}" name "${byName.value.name}".`,
+            });
+        }
+        if (byName.error.code !== 'not_found')
+            return byName;
+    }
+    return {
+        ok: false,
+        error: {
+            code: 'not_found',
+            message: `Agent selector not found: "${input.selector}". Looked up registry id first, then agent name across project, personal, and VGXNESS global contexts for project "${input.project}" and scope "${input.scope}". Accepted forms: canonical agent id or visible agent name.`,
+        },
+    };
+}
+function ok(value) {
+    return { ok: true, value };
+}

package/dist/application/agents/boot-upgrade.js

@@ -0,0 +1,59 @@
+import { canonicalAgentManifest } from '../../domain/agents/canonical-agent-manifest.js';
+import { AgentSeedHistoryRepository } from '../../storage/agents/repositories/agent-seed-history.js';
+import { AgentRepository } from '../../storage/agents/repositories/agents.js';
+import { AgentSeedUpgradeService } from './agent-seed-upgrade-service.js';
+const skipEnvVar = 'VGXNESS_SKIP_AGENT_SEED_AUTO_UPGRADE';
+export function runBootAgentSeedUpgrade(database, env = process.env, project = canonicalAgentManifest.project, scope = canonicalAgentManifest.scope) {
+    if (isOptOut(env)) {
+        return { ok: true, skipped: true, created: 0, upgraded: 0, overwritten: 0, noop: 0, errors: 0 };
+    }
+    try {
+        const service = new AgentSeedUpgradeService({
+            agents: new AgentRepository(database),
+            history: new AgentSeedHistoryRepository(database),
+            database,
+        });
+        const result = service.upgrade({ project, scope, source: 'boot-upgrade' });
+        if (!result.ok) {
+            const message = `boot-upgrade failed: ${result.error.message} (code=${result.error.code})`;
+            process.stderr.write(`[vgxness] ${message}\n`);
+            return { ok: false, skipped: false, created: 0, upgraded: 0, overwritten: 0, noop: 0, errors: 1, message };
+        }
+        const value = result.value;
+        const touched = value.created.length + value.upgraded.length + value.overwritten.length + value.errors.length;
+        if (touched > 0) {
+            const parts = [];
+            if (value.created.length > 0)
+                parts.push(`created ${value.created.length}`);
+            if (value.upgraded.length > 0)
+                parts.push(`upgraded ${value.upgraded.length}`);
+            if (value.overwritten.length > 0)
+                parts.push(`overwrote ${value.overwritten.length}`);
+            if (value.errors.length > 0)
+                parts.push(`errors ${value.errors.length}`);
+            process.stderr.write(`[vgxness] boot-upgrade: ${parts.join(', ')}\n`);
+            for (const error of value.errors) {
+                process.stderr.write(`[vgxness] boot-upgrade: ${error.agentName} ${error.outcome}: ${error.reason}\n`);
+            }
+        }
+        return {
+            ok: true,
+            skipped: false,
+            created: value.created.length,
+            upgraded: value.upgraded.length,
+            overwritten: value.overwritten.length,
+            noop: value.noop.length,
+            errors: value.errors.length,
+        };
+    }
+    catch (cause) {
+        const detail = cause instanceof Error ? `${cause.name}: ${cause.message}` : String(cause);
+        const message = `boot-upgrade threw: ${detail}`;
+        process.stderr.write(`[vgxness] ${message}\n`);
+        return { ok: false, skipped: false, created: 0, upgraded: 0, overwritten: 0, noop: 0, errors: 1, message };
+    }
+}
+function isOptOut(env) {
+    const value = env[skipEnvVar];
+    return value === '1' || value === 'true';
+}

package/dist/application/agents/canonical-agent-projection.js

@@ -0,0 +1,236 @@
+import { canonicalAgentManifest, canonicalDefaultAgentName, canonicalOpenCodeManagerPrompt, canonicalOpenCodeManagerReasoningEffort, canonicalPromptContractVersion, canonicalSddSubagentNames, createCanonicalOpenCodeSddSubagentPrompt, createCanonicalOpenCodeSddTaskPermissions, validateCanonicalAgentManifest, } from '../../domain/agents/canonical-agent-manifest.js';
+import { composeManagerInstructions } from './manager-profile-overlay-service.js';
+export function canonicalManifestValidationErrors(manifest = canonicalAgentManifest) {
+    const validation = validateCanonicalAgentManifest(manifest);
+    return validation.ok ? [] : validation.errors;
+}
+export function projectCanonicalAgentManifestToSeed(manifest = canonicalAgentManifest) {
+    assertValidCanonicalManifest(manifest);
+    const agents = manifest.agents.filter((agent) => agent.mode === 'agent').map(toSeedAgent);
+    const subagents = manifest.agents.filter((agent) => agent.mode === 'subagent').map(toSeedSubagent);
+    return { version: 1, project: manifest.project, scope: manifest.scope, agents, subagents };
+}
+export function projectCanonicalAgentManifestToOpenCode(manifest = canonicalAgentManifest) {
+    assertValidCanonicalManifest(manifest);
+    const manager = manifest.agents.find((agent) => agent.name === manifest.defaultAgentName && agent.mode === 'agent');
+    if (manager === undefined)
+        throw new Error(`Canonical OpenCode projection missing manager agent: ${manifest.defaultAgentName}`);
+    const agents = {
+        [canonicalDefaultAgentName]: {
+            description: 'VGXNESS SDD Manager - coordinates MCP state and SDD sub-agents, avoids inline execution when delegation is safer',
+            mode: 'primary',
+            ...(manager.adapters?.opencode?.model !== undefined ? { model: manager.adapters.opencode.model } : {}),
+            options: { reasoningEffort: canonicalOpenCodeManagerReasoningEffort, vgxnessPromptContractVersion: canonicalPromptContractVersion },
+            permission: openCodeManagerPermissionsFor(manager),
+            prompt: canonicalOpenCodeManagerPrompt,
+            reasoningEffort: canonicalOpenCodeManagerReasoningEffort,
+            tools: openCodeManagerTools(),
+            variant: '',
+        },
+    };
+    for (const name of canonicalSddSubagentNames) {
+        const subagent = manifest.agents.find((agent) => agent.name === name && agent.mode === 'subagent');
+        if (subagent === undefined)
+            throw new Error(`Canonical OpenCode projection missing subagent: ${name}`);
+        agents[name] = {
+            description: openCodeSubagentDescriptions[name],
+            hidden: true,
+            mode: 'subagent',
+            ...(subagent.adapters?.opencode?.model !== undefined ? { model: subagent.adapters.opencode.model } : {}),
+            options: { vgxnessPromptContractVersion: canonicalPromptContractVersion },
+            prompt: createCanonicalOpenCodeSddSubagentPrompt(name),
+            permission: openCodePermissionsFor(subagent),
+            tools: { bash: true, edit: true, read: true, write: true },
+        };
+    }
+    return { defaultAgent: canonicalDefaultAgentName, agents };
+}
+export function withEffectiveOpenCodeManagerInstructions(projection, instructions) {
+    const trimmed = instructions?.trim() ?? '';
+    if (trimmed === '')
+        return projection;
+    const manager = projection.agents[projection.defaultAgent];
+    if (manager === undefined)
+        return projection;
+    return {
+        defaultAgent: projection.defaultAgent,
+        agents: {
+            ...projection.agents,
+            [projection.defaultAgent]: { ...manager, prompt: composeManagerInstructions(manager.prompt, trimmed) },
+        },
+    };
+}
+export function projectCanonicalAgentManifestToClaudeCode(manifest = canonicalAgentManifest) {
+    assertValidCanonicalManifest(manifest);
+    const manager = manifest.agents.find((agent) => agent.name === manifest.defaultAgentName && agent.mode === 'agent');
+    if (manager === undefined)
+        throw new Error(`Canonical Claude projection missing manager agent: ${manifest.defaultAgentName}`);
+    const agents = [
+        {
+            name: canonicalDefaultAgentName,
+            canonicalName: canonicalDefaultAgentName,
+            description: manager.description,
+            fileName: `${canonicalDefaultAgentName}.md`,
+            instructions: canonicalOpenCodeManagerPrompt,
+            promptContractVersion: canonicalPromptContractVersion,
+        },
+    ];
+    for (const mapping of claudeSddNameMappings) {
+        const subagent = manifest.agents.find((agent) => agent.name === mapping.canonical && agent.mode === 'subagent');
+        if (subagent === undefined)
+            throw new Error(`Canonical Claude projection missing subagent: ${mapping.canonical}`);
+        agents.push({
+            name: mapping.claude,
+            canonicalName: mapping.canonical,
+            description: claudeSubagentDescriptions[mapping.claude],
+            fileName: `${mapping.claude}.md`,
+            instructions: createCanonicalOpenCodeSddSubagentPrompt(mapping.canonical),
+            promptContractVersion: canonicalPromptContractVersion,
+        });
+    }
+    return { defaultAgent: canonicalDefaultAgentName, agents };
+}
+export function withEffectiveManagerInstructions(projection, instructions) {
+    const trimmed = instructions?.trim() ?? '';
+    if (trimmed === '')
+        return projection;
+    const agents = projection.agents.map((agent) => agent.canonicalName === projection.defaultAgent ? { ...agent, instructions: composeManagerInstructions(agent.instructions, trimmed) } : agent);
+    return { defaultAgent: projection.defaultAgent, agents };
+}
+export function projectCanonicalAgentManifestToClaudeProjectMemory(manifest = canonicalAgentManifest) {
+    assertValidCanonicalManifest(manifest);
+    return {
+        defaultAgent: canonicalDefaultAgentName,
+        promptContractVersion: canonicalPromptContractVersion,
+        repositoryInstructions: 'AGENTS.md',
+        guidance: [
+            `Use \`${canonicalDefaultAgentName}\` as the VGXNESS project manager/personality for this project.`,
+            'Follow project-root `AGENTS.md` when present.',
+            'Use VGXNESS MCP as durable state for SDD artifacts, runs, memory, agents, permissions, and provider diagnostics.',
+            'SDD artifact acceptance is human-only; never infer acceptance from generated output or file presence.',
+            'Before phase advancement, check VGXNESS SDD readiness/status.',
+            'Preserve confirmation and preflight requirements for risky side effects.',
+            'Do not tell users to run terminal SDD phase commands for normal daily SDD flow.',
+            'Be concise, evidence-grounded, user-controlled, practical, and willing to challenge unsafe assumptions.',
+        ],
+    };
+}
+export function canonicalProviderProjection(provider, manifest = canonicalAgentManifest) {
+    assertValidCanonicalManifest(manifest);
+    const normalized = provider.trim().toLowerCase();
+    if (normalized === 'opencode')
+        return { provider: normalized, level: 'managed', manifest, projection: projectCanonicalAgentManifestToOpenCode(manifest) };
+    if (normalized === 'claude')
+        return { provider: normalized, level: 'managed', manifest, projection: projectCanonicalAgentManifestToClaudeCode(manifest) };
+    return { provider: normalized, level: 'unsupported', manifest, reason: `Unsupported provider projection: ${provider}` };
+}
+function assertValidCanonicalManifest(manifest) {
+    const errors = canonicalManifestValidationErrors(manifest);
+    if (errors.length > 0)
+        throw new Error(`Invalid canonical agent manifest: ${errors.join('; ')}`);
+}
+function openCodePermissionsFor(agent, additional = {}) {
+    const adapterPermission = asRecord(agent.adapters?.opencode?.config?.permission);
+    return { ...adapterPermission, ...additional, ...mapCanonicalPermissionsToOpenCode(agent.permissions) };
+}
+function openCodeManagerPermissionsFor(agent) {
+    return {
+        ...openCodePermissionsFor(agent, { task: createCanonicalOpenCodeSddTaskPermissions() }),
+        bash: 'deny',
+        edit: 'deny',
+        read: 'allow',
+        write: 'deny',
+    };
+}
+function openCodeManagerTools() {
+    return {
+        bash: false,
+        delegate: true,
+        delegation_list: true,
+        delegation_read: true,
+        edit: false,
+        glob: true,
+        grep: true,
+        read: true,
+        write: false,
+    };
+}
+function mapCanonicalPermissionsToOpenCode(permissions) {
+    const mapped = {};
+    if (permissions === undefined)
+        return mapped;
+    for (const [canonical, openCode] of openCodePermissionMappings) {
+        const decision = permissions[canonical];
+        if (decision !== undefined)
+            mapped[openCode] = decision;
+    }
+    return mapped;
+}
+function asRecord(value) {
+    if (value === null || typeof value !== 'object' || Array.isArray(value))
+        return {};
+    return value;
+}
+const openCodePermissionMappings = [
+    ['read', 'read'],
+    ['edit', 'edit'],
+    ['shell', 'bash'],
+    ['external-directory', 'external_directory'],
+];
+function toSeedAgent(agent) {
+    const seed = {
+        name: agent.name,
+        description: agent.description,
+        instructions: agent.instructions,
+    };
+    if (agent.capabilities !== undefined)
+        seed.capabilities = agent.capabilities;
+    if (agent.permissions !== undefined)
+        seed.permissions = agent.permissions;
+    if (agent.memory !== undefined)
+        seed.memory = agent.memory;
+    if (agent.workflows !== undefined)
+        seed.workflows = agent.workflows;
+    if (agent.skills !== undefined)
+        seed.skills = agent.skills;
+    if (agent.adapters !== undefined)
+        seed.adapters = agent.adapters;
+    return seed;
+}
+function toSeedSubagent(agent) {
+    if (agent.parentAgentName === undefined)
+        throw new Error(`Canonical subagent ${agent.name} is missing parentAgentName`);
+    return { ...toSeedAgent(agent), parentAgentName: agent.parentAgentName };
+}
+const openCodeSubagentDescriptions = {
+    'vgxness-sdd-explore': 'Investigate codebase and think through ideas',
+    'vgxness-sdd-propose': 'Create change proposals from explorations',
+    'vgxness-sdd-spec': 'Write detailed specifications from proposals',
+    'vgxness-sdd-design': 'Create technical design from proposals',
+    'vgxness-sdd-tasks': 'Break down specs and designs into implementation tasks',
+    'vgxness-sdd-apply': 'Implement code changes from task definitions',
+    'vgxness-sdd-verify': 'Validate implementation against specs',
+    'vgxness-sdd-archive': 'Archive completed change artifacts',
+    'vgxness-sdd-init': 'Bootstrap SDD context and project configuration',
+    'vgxness-sdd-onboard': 'Guide user through a complete SDD cycle using their real codebase',
+};
+const claudeSddNameMappings = [
+    { canonical: 'vgxness-sdd-explore', claude: 'vgxness-sdd-explore' },
+    { canonical: 'vgxness-sdd-propose', claude: 'vgxness-sdd-proposal' },
+    { canonical: 'vgxness-sdd-spec', claude: 'vgxness-sdd-spec' },
+    { canonical: 'vgxness-sdd-design', claude: 'vgxness-sdd-design' },
+    { canonical: 'vgxness-sdd-tasks', claude: 'vgxness-sdd-tasks' },
+    { canonical: 'vgxness-sdd-apply', claude: 'vgxness-sdd-apply-progress' },
+    { canonical: 'vgxness-sdd-verify', claude: 'vgxness-sdd-verify' },
+    { canonical: 'vgxness-sdd-archive', claude: 'vgxness-sdd-archive' },
+];
+const claudeSubagentDescriptions = {
+    'vgxness-sdd-explore': 'Investigate codebase context and risks for VGXNESS SDD changes.',
+    'vgxness-sdd-proposal': 'Create focused proposals for VGXNESS SDD changes.',
+    'vgxness-sdd-spec': 'Write detailed specifications for VGXNESS SDD changes.',
+    'vgxness-sdd-design': 'Create technical designs for VGXNESS SDD changes.',
+    'vgxness-sdd-tasks': 'Break accepted designs into implementation tasks.',
+    'vgxness-sdd-apply-progress': 'Implement accepted VGXNESS SDD tasks and report apply progress.',
+    'vgxness-sdd-verify': 'Verify VGXNESS SDD implementation evidence and risks.',
+    'vgxness-sdd-archive': 'Archive completed VGXNESS SDD outcomes and follow-ups.',
+};

package/dist/application/agents/manager-profile-overlay-service.js

@@ -0,0 +1,68 @@
+import { ManagerProfileOverlayRepository } from '../../storage/agents/repositories/manager-profile-overlays.js';
+import { AgentRegistryService } from './agent-registry-service.js';
+export class ManagerProfileOverlayService {
+    dependencies;
+    constructor(dependencies) {
+        this.dependencies = dependencies;
+    }
+    save(input) {
+        return this.dependencies.overlays.save(input);
+    }
+    get(project, scope, managerName) {
+        return this.dependencies.overlays.get(project, scope, managerName);
+    }
+    resolveEffectiveManager(input) {
+        const manager = this.dependencies.agents.getAgentByName(input.project, input.scope, input.managerName);
+        if (!manager.ok)
+            return manager;
+        if (manager.value.mode !== 'agent')
+            return validationFailure('Effective manager requires a top-level agent');
+        const overlay = this.dependencies.overlays.get(input.project, input.scope, input.managerName);
+        if (!overlay.ok) {
+            if (overlay.error.code === 'not_found')
+                return ok({ manager: manager.value });
+            return overlay;
+        }
+        return ok({
+            manager: {
+                ...manager.value,
+                instructions: { kind: 'inline', value: composeManagerInstructions(manager.value.instructions.value, overlay.value.instructions) },
+            },
+            overlay: overlay.value,
+        });
+    }
+}
+const managerProfileOverlayMarker = '## Manager profile overlay';
+export function composeManagerInstructions(baseline, overlay) {
+    const baselineInstructions = baseline.trim();
+    const overlayInstructions = normalizeManagerOverlayInstructions(overlay);
+    if (baselineInstructions === '')
+        return overlayInstructions;
+    if (overlayInstructions === '')
+        return baselineInstructions;
+    if (overlayInstructions.includes(baselineInstructions))
+        return overlayInstructions;
+    return `${baselineInstructions}\n\n${managerProfileOverlayMarker}\n${overlayInstructions}`;
+}
+function normalizeManagerOverlayInstructions(overlay) {
+    const overlayInstructions = overlay.trim();
+    const markerIndex = overlayInstructions.lastIndexOf(managerProfileOverlayMarker);
+    if (markerIndex === -1)
+        return overlayInstructions;
+    return overlayInstructions.slice(markerIndex + managerProfileOverlayMarker.length).trim();
+}
+function ok(value) {
+    return { ok: true, value };
+}
+function validationFailure(message) {
+    return { ok: false, error: { code: 'validation_failed', message } };
+}
+export function computeEffectiveManagerInstructions(database, project = 'vgxness', scope = 'project', managerName = 'vgxness-manager') {
+    const registry = new AgentRegistryService(database);
+    const overlays = new ManagerProfileOverlayRepository(database);
+    const service = new ManagerProfileOverlayService({ agents: registry, overlays });
+    const resolved = service.resolveEffectiveManager({ project, scope, managerName });
+    if (!resolved.ok || resolved.value.overlay === undefined)
+        return undefined;
+    return resolved.value.manager.instructions.value.trim() || undefined;
+}

package/dist/application/agents/profile-model-routing.js

@@ -0,0 +1,30 @@
+export function resolveAgentProfileModel(input) {
+    const providerAdapter = input.providerAdapter?.trim() || 'opencode';
+    const adapters = input.agent.adapters;
+    const adapterNames = Object.keys(adapters);
+    const adapter = adapters[providerAdapter];
+    if (adapterNames.length > 0 && adapter === undefined) {
+        return validationFailure(`Agent ${input.agent.name} does not declare provider adapter: ${providerAdapter}`);
+    }
+    const model = adapter?.model?.trim();
+    if (model !== undefined && model.length > 0) {
+        const profile = profileFromAdapter(adapter?.config);
+        return ok({ providerAdapter, model, ...(profile === undefined ? {} : { profile }), source: 'agent-adapter-model', warnings: [] });
+    }
+    const previewModel = `${providerAdapter}-preview`;
+    const warnings = adapter === undefined
+        ? [`Agent does not declare adapters; using provider-neutral preview model ${previewModel}.`]
+        : [`Adapter ${providerAdapter} does not declare a model; using ${previewModel}.`];
+    const profile = profileFromAdapter(adapter?.config);
+    return ok({ providerAdapter, model: previewModel, ...(profile === undefined ? {} : { profile }), source: 'provider-preview-default', warnings });
+}
+function profileFromAdapter(config) {
+    const profile = config?.profile;
+    return typeof profile === 'string' && profile.trim().length > 0 ? profile.trim() : undefined;
+}
+function ok(value) {
+    return { ok: true, value };
+}
+function validationFailure(message) {
+    return { ok: false, error: { code: 'validation_failed', message } };
+}

package/dist/application/agents/renderers/claude-renderer.js

@@ -0,0 +1 @@
+export * from '../../../adapters/claude/agent-renderer.js';

package/dist/application/agents/renderers/index.js

@@ -0,0 +1,14 @@
+import { ClaudeAgentRenderer } from '../../../adapters/claude/agent-renderer.js';
+import { JsonAgentRenderer } from '../../../adapters/json/agent-renderer.js';
+import { OpenCodeAgentRenderer } from '../../../adapters/opencode/agent-renderer.js';
+import { ok, validationFailure } from '../../../adapters/provider-renderer.js';
+const renderers = {
+    json: new JsonAgentRenderer(),
+    opencode: new OpenCodeAgentRenderer(),
+    claude: new ClaudeAgentRenderer(),
+};
+export function getProviderRenderer(provider) {
+    const normalized = provider.trim().toLowerCase();
+    const renderer = renderers[normalized];
+    return renderer === undefined ? validationFailure(`Unknown provider renderer: ${provider}`) : ok(renderer);
+}

package/dist/application/agents/renderers/json-renderer.js

@@ -0,0 +1 @@
+export * from '../../../adapters/json/agent-renderer.js';

package/dist/application/agents/renderers/opencode-renderer.js

@@ -0,0 +1 @@
+export * from '../../../adapters/opencode/agent-renderer.js';

package/dist/application/agents/renderers/provider-adapter.js

@@ -0,0 +1 @@
+export * from '../../../adapters/provider-renderer.js';

package/dist/application/memory/active-work-preview.js

@@ -0,0 +1,75 @@
+import { activeWorkCurrentSegments, activeWorkRecommendedMemoryTypes, activeWorkTopicRoot, parseActiveWorkTopicKey, } from '../../domain/memory/active-work-topics.js';
+const sourceLimit = 50;
+const maxItems = 8;
+const maxPreviewChars = 160;
+const currentPriority = new Map(activeWorkCurrentSegments.map((segment, index) => [segment, index]));
+export class ActiveWorkPreviewService {
+    source;
+    constructor(source) {
+        this.source = source;
+    }
+    build(input) {
+        const found = this.source.searchObservationPreviewsNoTrace({ project: input.project, topicKey: activeWorkTopicRoot, limit: sourceLimit });
+        if (!found.ok)
+            return found;
+        return { ok: true, value: formatActiveWorkPreview(found.value, input.change) };
+    }
+}
+export function formatActiveWorkPreview(records, change) {
+    const parsed = records
+        .map((record) => ({ record, parsed: parseActiveWorkTopicKey(record.topicKey) }))
+        .filter((entry) => entry.parsed !== undefined)
+        .filter((entry) => change === undefined || entry.parsed.change === change);
+    const changes = [...new Set(parsed.map((entry) => entry.parsed.change))].sort();
+    const notes = [
+        'Active-work memory is advisory only; canonical SDD status/readiness, runs, artifacts, and explicit human acceptance remain authoritative.',
+        'Previews are bounded and may omit full context; use memory_get for a selected memory when safe.',
+        'Do not store secrets, credentials, raw large logs, hidden reasoning, or sensitive user data in active-work memory.',
+    ];
+    if (change === undefined && changes.length > 1) {
+        return {
+            advisory: true,
+            items: [],
+            truncated: true,
+            notes: [...notes, `Multiple active-work changes found (${changes.join(', ')}); provide an explicit change to avoid mixing narratives.`],
+        };
+    }
+    const resolvedChange = change ?? changes[0];
+    const candidates = parsed.filter((entry) => resolvedChange === undefined || entry.parsed.change === resolvedChange).sort(compareActiveWorkEntries);
+    const items = candidates.slice(0, maxItems).map(({ record }) => toPreviewItem(record));
+    const truncated = candidates.length > items.length || records.length >= sourceLimit;
+    return {
+        advisory: true,
+        ...(resolvedChange === undefined ? {} : { change: resolvedChange }),
+        items,
+        truncated,
+        notes: items.length === 0 ? [...notes, 'No active-work memory found for this context.'] : notes,
+    };
+}
+function compareActiveWorkEntries(left, right) {
+    const leftPriority = currentPriority.get(left.parsed.segment) ?? 100;
+    const rightPriority = currentPriority.get(right.parsed.segment) ?? 100;
+    if (leftPriority !== rightPriority)
+        return leftPriority - rightPriority;
+    const expectedLeft = activeWorkRecommendedMemoryTypes[left.parsed.segment] === left.record.type ? 0 : 1;
+    const expectedRight = activeWorkRecommendedMemoryTypes[right.parsed.segment] === right.record.type ? 0 : 1;
+    if (expectedLeft !== expectedRight)
+        return expectedLeft - expectedRight;
+    return right.record.updatedAt.localeCompare(left.record.updatedAt);
+}
+function toPreviewItem(record) {
+    return {
+        id: record.id,
+        topicKey: record.topicKey ?? '',
+        title: record.title,
+        type: record.type,
+        preview: redactSensitivePreview(record.preview).slice(0, maxPreviewChars),
+        ...(record.updatedAt === undefined ? {} : { updatedAt: record.updatedAt }),
+    };
+}
+function redactSensitivePreview(value) {
+    return value
+        .replace(/\b([A-Za-z0-9._%+-]+)@([A-Za-z0-9.-]+\.[A-Za-z]{2,})\b/g, '[redacted-email]')
+        .replace(/\b(api[_-]?key|token|secret|password|credential)\s*[:=]\s*\S+/gi, '$1=[redacted]')
+        .replace(/\b(sk-[A-Za-z0-9_-]{8,}|ghp_[A-Za-z0-9_]{8,})\b/g, '[redacted-token]');
+}