vgxness 1.20.5 → 1.20.7

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

@@ -0,0 +1,287 @@
+import { normalizeSddPhaseInput } from '../../sdd/schema.js';
+import { agentLookupContexts } from './agent-lookup-contexts.js';
+export class AgentResolver {
+    loadAgents;
+    constructor(loadAgents) {
+        this.loadAgents = loadAgents;
+    }
+    resolve(input) {
+        const agents = this.loadAgents();
+        if (!agents.ok)
+            return agents;
+        const normalized = normalizeInput(input);
+        const candidates = [];
+        const skipped = [];
+        for (const agent of agents.value) {
+            const skipReasons = hardSkipReasons(agent, normalized);
+            if (skipReasons.length > 0) {
+                skipped.push(toSkipped(agent, skipReasons));
+                continue;
+            }
+            const scored = scoreAgent(agent, normalized);
+            if (scored.score <= 0) {
+                skipped.push(toSkipped(agent, ['no matching resolution signals']));
+                continue;
+            }
+            candidates.push(scored);
+        }
+        candidates.sort(compareCandidates);
+        skipped.sort(compareSkipped);
+        return ok({
+            context: {
+                ...(normalized.project !== undefined ? { project: normalized.project } : {}),
+                ...(normalized.scope !== undefined ? { scope: normalized.scope } : {}),
+                ...(normalized.taskDescription !== undefined ? { taskDescription: normalized.taskDescription } : {}),
+                ...(normalized.intent !== undefined ? { intent: normalized.intent } : {}),
+                desiredCapabilities: normalized.desiredCapabilities,
+                ...(normalized.workflow !== undefined ? { workflow: normalized.workflow } : {}),
+                ...(normalized.phase !== undefined ? { phase: normalized.phase } : {}),
+                ...(normalized.providerAdapter !== undefined ? { providerAdapter: normalized.providerAdapter } : {}),
+                ...(normalized.mode !== undefined ? { mode: normalized.mode } : {}),
+            },
+            candidates,
+            skipped,
+        });
+    }
+}
+const SDD_PHASE_SEMANTICS = [
+    {
+        name: 'sdd-planning',
+        phases: ['proposal', 'design', 'tasks'],
+        terms: ['plan', 'planning', 'proposal', 'propose', 'design', 'task', 'tasks', 'breakdown', 'slice', 'slicing'],
+    },
+    {
+        name: 'sdd-verification',
+        phases: ['verify'],
+        terms: ['verify', 'verification', 'test', 'testing', 'review', 'risk', 'evidence'],
+    },
+];
+function normalizeInput(input) {
+    const desiredCapabilities = normalizeList(input.desiredCapabilities ?? []);
+    const taskDescription = normalizeText(input.taskDescription);
+    const intent = normalizeText(input.intent);
+    const metaWorkflow = isMetaWorkflow(input.workflow);
+    const workflow = normalizeMetaWorkflow(input.workflow);
+    const phase = metaWorkflow || input.phase === undefined ? undefined : isSddWorkflow(workflow) ? (normalizeSddPhaseInput(input.phase) ?? input.phase) : input.phase;
+    const { workflow: _workflow, phase: _phase, ...rest } = input;
+    return {
+        ...rest,
+        ...(workflow !== undefined ? { workflow } : {}),
+        ...(phase !== undefined ? { phase } : {}),
+        ...(taskDescription !== undefined ? { taskDescription } : {}),
+        ...(intent !== undefined ? { intent } : {}),
+        desiredCapabilities,
+        terms: tokenize([taskDescription, intent].filter((value) => value !== undefined).join(' ')),
+    };
+}
+function normalizeMetaWorkflow(workflow) {
+    if (isMetaWorkflow(workflow))
+        return undefined;
+    return workflow;
+}
+function isMetaWorkflow(workflow) {
+    return workflow?.trim().toLowerCase() === 'workflow-selection';
+}
+function hardSkipReasons(agent, input) {
+    const reasons = [];
+    if (input.project !== undefined && !agentMatchesRequestedContext(agent, input))
+        reasons.push(`context mismatch: ${agent.project}/${agent.scope}`);
+    else if (input.project === undefined && input.scope !== undefined && agent.scope !== input.scope)
+        reasons.push(`scope mismatch: ${agent.scope}`);
+    if (input.mode !== undefined && agent.mode !== input.mode)
+        reasons.push(`mode mismatch: ${agent.mode}`);
+    if (input.providerAdapter !== undefined && Object.keys(agent.adapters).length > 0 && agent.adapters[input.providerAdapter] === undefined)
+        reasons.push(`provider adapter mismatch: ${input.providerAdapter}`);
+    if ((input.workflow !== undefined || input.phase !== undefined) && agent.workflows.length > 0 && workflowMatches(agent, input).length === 0)
+        reasons.push('workflow mismatch');
+    if (input.desiredCapabilities.length > 0 && matchingValues(agent.capabilities, input.desiredCapabilities).length === 0)
+        reasons.push('capability mismatch');
+    return reasons;
+}
+function agentMatchesRequestedContext(agent, input) {
+    if (input.project === undefined)
+        return true;
+    const contexts = agentLookupContexts(input.project, input.scope ?? 'project');
+    return contexts.some((context) => agent.project === context.project && agent.scope === context.scope);
+}
+function scoreAgent(agent, input) {
+    const reasons = [];
+    let score = 0;
+    const capabilityMatches = matchingValues(agent.capabilities, input.desiredCapabilities);
+    if (capabilityMatches.length > 0) {
+        score += capabilityMatches.length * 30;
+        reasons.push(`capabilities matched: ${capabilityMatches.join(', ')}`);
+    }
+    const workflowMatchesValue = workflowSignalMatches(agent, input);
+    if (workflowMatchesValue.exactPhase.length > 0) {
+        score += workflowMatchesValue.exactPhase.length * 25;
+        reasons.push(`workflow phase matched: ${workflowMatchesValue.exactPhase.join(', ')}`);
+    }
+    if (workflowMatchesValue.phaseOnly.length > 0) {
+        score += workflowMatchesValue.phaseOnly.length * 22;
+        reasons.push(`workflow phase-only matched: ${workflowMatchesValue.phaseOnly.join(', ')}`);
+    }
+    if (workflowMatchesValue.broad.length > 0) {
+        score += workflowMatchesValue.broad.length * 20;
+        reasons.push(`workflow matched: ${workflowMatchesValue.broad.join(', ')}`);
+    }
+    if (input.providerAdapter !== undefined) {
+        if (agent.adapters[input.providerAdapter] !== undefined) {
+            score += 20;
+            reasons.push(`provider adapter matched: ${input.providerAdapter}`);
+        }
+        else if (Object.keys(agent.adapters).length === 0) {
+            score += 5;
+            reasons.push(`provider neutral: no adapter restrictions for ${input.providerAdapter}`);
+        }
+    }
+    const skillMatches = matchingValues(agent.skills, [...input.desiredCapabilities, ...input.terms]);
+    if (skillMatches.length > 0) {
+        score += skillMatches.length * 10;
+        reasons.push(`skills matched: ${skillMatches.join(', ')}`);
+    }
+    const textMatches = textSignalMatches(agent, input.terms);
+    if (textMatches.length > 0) {
+        score += Math.min(textMatches.length, 5) * 4;
+        reasons.push(`task text matched: ${textMatches.join(', ')}`);
+    }
+    const phaseSemanticMatches = phaseSemanticMatchesFor(agent, input);
+    for (const match of phaseSemanticMatches) {
+        score += 8;
+        reasons.push(`phase semantics matched: ${match}`);
+    }
+    if (input.mode !== undefined) {
+        score += 3;
+        reasons.push(`mode matched: ${agent.mode}`);
+    }
+    if (agent.mode === 'subagent') {
+        score += 2;
+        reasons.push(`parent constraint satisfied: ${agent.parentAgentId}`);
+    }
+    return { agent, score, reasons };
+}
+function workflowMatches(agent, input) {
+    const matches = workflowSignalMatches(agent, input);
+    return [...matches.broad, ...matches.phaseOnly, ...matches.exactPhase];
+}
+function workflowSignalMatches(agent, input) {
+    const requested = workflowRequestedSignals(input)
+        .filter((value) => value !== undefined)
+        .map(normalizeKey);
+    if (requested.length === 0)
+        return { broad: [], phaseOnly: [], exactPhase: [] };
+    const workflow = input.workflow !== undefined ? normalizeKey(input.workflow) : undefined;
+    const phase = input.phase !== undefined ? normalizeKey(input.phase) : undefined;
+    const exact = workflow !== undefined && phase !== undefined ? `${workflow}:${phase}` : undefined;
+    const matches = { broad: [], phaseOnly: [], exactPhase: [] };
+    for (const agentWorkflow of agent.workflows) {
+        const normalizedWorkflow = normalizeKey(agentWorkflow);
+        const comparableWorkflow = canonicalSddWorkflowTargetKey(agentWorkflow);
+        if (!requested.includes(normalizedWorkflow) && !requested.includes(comparableWorkflow) && !sddApplyAliasMatches(agentWorkflow, input))
+            continue;
+        if (exact !== undefined && (normalizedWorkflow === exact || comparableWorkflow === exact))
+            matches.exactPhase.push(agentWorkflow);
+        else if (phase !== undefined && normalizedWorkflow === phase)
+            matches.phaseOnly.push(agentWorkflow);
+        else if (sddApplyAliasMatches(agentWorkflow, input))
+            matches.exactPhase.push(agentWorkflow);
+        else
+            matches.broad.push(agentWorkflow);
+    }
+    return matches;
+}
+function canonicalSddWorkflowTargetKey(workflow) {
+    const normalized = normalizeKey(workflow);
+    const separator = normalized.indexOf(':');
+    if (separator <= 0)
+        return normalized;
+    const workflowName = normalized.slice(0, separator);
+    const phase = normalized.slice(separator + 1);
+    if (workflowName !== 'sdd')
+        return normalized;
+    return `${workflowName}:${normalizeSddPhaseInput(phase) ?? phase}`;
+}
+function workflowRequestedSignals(input) {
+    return [input.workflow, input.phase, input.workflow !== undefined && input.phase !== undefined ? `${input.workflow}:${input.phase}` : undefined];
+}
+function sddApplyAliasMatches(agentWorkflow, input) {
+    if (input.phase === undefined || normalizeKey(input.phase) !== 'apply')
+        return false;
+    if (input.workflow !== undefined && !isSddWorkflow(input.workflow))
+        return false;
+    return normalizeKey(agentWorkflow) === 'sdd:apply-progress';
+}
+function phaseSemanticMatchesFor(agent, input) {
+    const workflow = input.workflow !== undefined ? normalizeKey(input.workflow) : undefined;
+    if (workflow !== undefined && workflow !== 'sdd')
+        return [];
+    const inputPhase = input.phase !== undefined ? normalizeKey(input.phase) : undefined;
+    const agentTerms = tokenize([agent.name, agent.description, ...agent.capabilities, ...agent.skills, ...agent.workflows].join(' '));
+    const requestTerms = new Set(input.terms);
+    const matches = [];
+    for (const semantic of SDD_PHASE_SEMANTICS) {
+        const phaseMatches = inputPhase !== undefined && semantic.phases.includes(inputPhase);
+        const termMatches = semantic.terms.some((term) => requestTerms.has(term));
+        const agentMatches = semantic.terms.some((term) => agentTerms.includes(term));
+        if ((phaseMatches || termMatches) && agentMatches)
+            matches.push(semantic.name);
+    }
+    return matches;
+}
+function textSignalMatches(agent, terms) {
+    if (terms.length === 0)
+        return [];
+    const searchable = tokenize([agent.name, agent.description, ...agent.capabilities, ...agent.skills, ...agent.workflows].join(' '));
+    return terms.filter((term) => searchable.includes(term));
+}
+function matchingValues(values, requested) {
+    const normalizedValues = new Map(values.map((value) => [normalizeKey(value), value]));
+    const matches = [];
+    for (const requestedValue of requested) {
+        const match = normalizedValues.get(normalizeKey(requestedValue));
+        if (match !== undefined && !matches.includes(match))
+            matches.push(match);
+    }
+    return matches;
+}
+function compareCandidates(a, b) {
+    return (b.score - a.score || modeRank(a.agent.mode) - modeRank(b.agent.mode) || a.agent.name.localeCompare(b.agent.name) || a.agent.id.localeCompare(b.agent.id));
+}
+function compareSkipped(a, b) {
+    return a.agent.name.localeCompare(b.agent.name) || a.agent.id.localeCompare(b.agent.id);
+}
+function modeRank(mode) {
+    return mode === 'agent' ? 0 : 1;
+}
+function toSkipped(agent, reasons) {
+    return { agent: { id: agent.id, name: agent.name, mode: agent.mode, project: agent.project, scope: agent.scope }, reasons };
+}
+function normalizeList(values) {
+    return values.map(normalizeText).filter((value) => value !== undefined);
+}
+function normalizeText(value) {
+    const normalized = value?.trim();
+    return normalized ? normalized : undefined;
+}
+function normalizeKey(value) {
+    return value.trim().toLowerCase();
+}
+function isSddWorkflow(workflow) {
+    return workflow?.trim().toLowerCase() === 'sdd';
+}
+function tokenize(value) {
+    const seen = new Set();
+    return value
+        .toLowerCase()
+        .split(/[^a-z0-9-]+/)
+        .filter(Boolean)
+        .filter((term) => {
+        if (term.length < 3 || seen.has(term))
+            return false;
+        seen.add(term);
+        return true;
+    });
+}
+function ok(value) {
+    return { ok: true, value };
+}

package/dist/application/agents/agent-seed-service.js

@@ -0,0 +1,157 @@
+import { AgentRepository } from '../../storage/agents/repositories/agents.js';
+import { projectCanonicalAgentManifestToSeed } from './canonical-agent-projection.js';
+const requiredManagerName = 'vgxness-manager';
+export class AgentSeedService {
+    database;
+    agents;
+    constructor(database) {
+        this.database = database;
+        this.agents = new AgentRepository(database);
+    }
+    loadBuiltInDefaults() {
+        try {
+            return this.loadManifest(projectCanonicalAgentManifestToSeed());
+        }
+        catch (cause) {
+            const message = cause instanceof Error ? cause.message : String(cause);
+            return { ok: false, error: { code: 'validation_failed', message } };
+        }
+    }
+    loadManifest(manifest) {
+        const validation = this.validateManifest(manifest);
+        if (!validation.ok)
+            return validation;
+        const existingNames = new Map();
+        for (const definition of [...manifest.agents, ...manifest.subagents]) {
+            const existing = this.agents.getByName(manifest.project, manifest.scope, definition.name);
+            if (existing.ok)
+                existingNames.set(definition.name, true);
+            else
+                existingNames.set(definition.name, false);
+        }
+        const transaction = this.database.transaction(() => {
+            const agents = [];
+            const subagents = [];
+            const nameToId = new Map();
+            const created = [];
+            const updated = [];
+            for (const definition of manifest.agents) {
+                const registered = this.agents.register(toRegisterInput(manifest, definition, 'agent'));
+                if (!registered.ok)
+                    throw new SeedLoadError(registered.error);
+                agents.push(registered.value);
+                nameToId.set(registered.value.name, registered.value.id);
+                (existingNames.get(definition.name) ? updated : created).push(definition.name);
+            }
+            for (const definition of manifest.subagents) {
+                const parentAgentId = nameToId.get(definition.parentAgentName) ?? this.resolveExistingParentId(manifest, definition.parentAgentName);
+                if (parentAgentId === undefined) {
+                    throw new SeedLoadError({ code: 'validation_failed', message: `Unresolved parentAgentName: ${definition.parentAgentName}` });
+                }
+                const registered = this.agents.register(toRegisterInput(manifest, definition, 'subagent', parentAgentId));
+                if (!registered.ok)
+                    throw new SeedLoadError(registered.error);
+                subagents.push(registered.value);
+                (existingNames.get(definition.name) ? updated : created).push(definition.name);
+            }
+            return { created, updated, agents, subagents, warnings: [] };
+        });
+        if (!transaction.ok) {
+            if (transaction.error.cause instanceof SeedLoadError)
+                return { ok: false, error: transaction.error.cause.failure };
+            return transaction;
+        }
+        return transaction;
+    }
+    validateManifest(manifest) {
+        if (manifest.version !== 1)
+            return validationFailure('Agent seed manifest version must be 1');
+        if (!manifest.project?.trim())
+            return validationFailure('Agent seed manifest project is required');
+        if (manifest.scope !== 'project' && manifest.scope !== 'personal')
+            return validationFailure('Agent seed manifest scope must be project or personal');
+        if (!Array.isArray(manifest.agents))
+            return validationFailure('Agent seed manifest agents must be an array');
+        if (!Array.isArray(manifest.subagents))
+            return validationFailure('Agent seed manifest subagents must be an array');
+        const managerCount = manifest.agents.filter((agent) => agent.name === requiredManagerName).length;
+        if (managerCount !== 1)
+            return validationFailure(`Agent seed manifest must declare exactly one ${requiredManagerName} agent`);
+        const seenNames = new Set();
+        for (const definition of manifest.agents) {
+            const validation = validateDefinition(definition, 'agent');
+            if (!validation.ok)
+                return validation;
+            if (seenNames.has(definition.name))
+                return validationFailure(`Duplicate seed agent name: ${definition.name}`);
+            seenNames.add(definition.name);
+        }
+        for (const definition of manifest.subagents) {
+            const validation = validateDefinition(definition, 'subagent');
+            if (!validation.ok)
+                return validation;
+            if (seenNames.has(definition.name))
+                return validationFailure(`Duplicate seed agent name: ${definition.name}`);
+            seenNames.add(definition.name);
+            if (!definition.parentAgentName.trim())
+                return validationFailure(`Subagent ${definition.name} parentAgentName is required`);
+            if (!manifest.agents.some((agent) => agent.name === definition.parentAgentName) &&
+                this.resolveExistingParentId(manifest, definition.parentAgentName) === undefined) {
+                return validationFailure(`Unresolved parentAgentName: ${definition.parentAgentName}`);
+            }
+        }
+        return { ok: true, value: undefined };
+    }
+    resolveExistingParentId(manifest, parentAgentName) {
+        const parent = this.agents.getByName(manifest.project, manifest.scope, parentAgentName);
+        if (!parent.ok || parent.value.mode !== 'agent')
+            return undefined;
+        return parent.value.id;
+    }
+}
+function validateDefinition(definition, mode) {
+    if (!definition.name?.trim())
+        return validationFailure(`Seed ${mode} name is required`);
+    if (!definition.description?.trim())
+        return validationFailure(`Seed ${mode} ${definition.name} description is required`);
+    if (definition.instructions?.kind !== 'inline' && definition.instructions?.kind !== 'path')
+        return validationFailure(`Seed ${mode} ${definition.name} instructions kind is invalid`);
+    if (!definition.instructions.value.trim())
+        return validationFailure(`Seed ${mode} ${definition.name} instructions are required`);
+    return { ok: true, value: undefined };
+}
+function toRegisterInput(manifest, definition, mode, parentAgentId) {
+    const input = {
+        project: manifest.project,
+        scope: manifest.scope,
+        mode,
+        name: definition.name,
+        description: definition.description,
+        instructions: definition.instructions,
+    };
+    if (definition.capabilities !== undefined)
+        input.capabilities = definition.capabilities;
+    if (definition.permissions !== undefined)
+        input.permissions = definition.permissions;
+    if (definition.memory !== undefined)
+        input.memory = definition.memory;
+    if (definition.workflows !== undefined)
+        input.workflows = definition.workflows;
+    if (definition.skills !== undefined)
+        input.skills = definition.skills;
+    if (definition.adapters !== undefined)
+        input.adapters = definition.adapters;
+    if (parentAgentId !== undefined)
+        input.parentAgentId = parentAgentId;
+    return input;
+}
+function validationFailure(message) {
+    return { ok: false, error: { code: 'validation_failed', message } };
+}
+class SeedLoadError extends Error {
+    failure;
+    constructor(failure) {
+        super(failure.message);
+        this.failure = failure;
+    }
+}

package/dist/application/agents/agent-seed-upgrade-service.js

@@ -0,0 +1,231 @@
+import { canonicalAgentManifest, canonicalPromptContractVersion, canonicalSddSubagentNames } from '../../domain/agents/canonical-agent-manifest.js';
+import { projectCanonicalAgentManifestToSeed } from './canonical-agent-projection.js';
+export class AgentSeedUpgradeService {
+    agents;
+    history;
+    database;
+    constructor(dependencies) {
+        this.agents = dependencies.agents;
+        this.history = dependencies.history;
+        this.database = dependencies.database;
+    }
+    upgrade(input) {
+        if (!input.project.trim())
+            return validationFailure('Agent seed upgrade project is required');
+        if (input.scope !== 'project' && input.scope !== 'personal')
+            return validationFailure('Agent seed upgrade scope is invalid');
+        const seed = projectCanonicalAgentManifestToSeed();
+        const canonicalByName = new Map();
+        for (const agent of seed.agents)
+            canonicalByName.set(agent.name, agent);
+        for (const subagent of seed.subagents)
+            canonicalByName.set(subagent.name, subagent);
+        const source = input.source ?? 'boot-upgrade';
+        const summary = {
+            created: [],
+            upgraded: [],
+            noop: [],
+            overwritten: [],
+            errors: [],
+            skipped: false,
+        };
+        const expected = canonicalPromptContractVersion;
+        const transaction = this.database.transaction(() => {
+            for (const [name, definition] of canonicalByName) {
+                const outcome = this.upgradeOne(input.project, input.scope, name, definition, source, expected);
+                if (outcome.ok) {
+                    switch (outcome.value.outcome) {
+                        case 'created':
+                            summary.created.push(name);
+                            break;
+                        case 'upgraded':
+                            summary.upgraded.push(name);
+                            break;
+                        case 'overwrote-custom-instructions':
+                            summary.overwritten.push(name);
+                            break;
+                        case 'noop':
+                            summary.noop.push(name);
+                            break;
+                    }
+                }
+                else {
+                    const failureOutcome = outcome.error.code === 'validation_failed' ? 'validation_failed' : 'db_error';
+                    summary.errors.push({ agentName: name, outcome: failureOutcome, reason: outcome.error.message });
+                }
+            }
+            return summary;
+        });
+        if (!transaction.ok) {
+            return { ok: false, error: transaction.error };
+        }
+        return transaction;
+    }
+    hasDrift(input) {
+        const expected = input.expectedVersion ?? canonicalPromptContractVersion;
+        try {
+            const canonicalNames = [canonicalAgentManifest.defaultAgentName, ...canonicalSddSubagentNames];
+            const placeholders = canonicalNames.map(() => '?').join(', ');
+            const row = this.database.connection
+                .prepare(`
+        SELECT COUNT(*) AS stale_count
+        FROM agents
+        WHERE project = ? AND scope = ? AND name IN (${placeholders})
+          AND json_extract(adapters_json, '$.opencode.config.options.vgxnessPromptContractVersion') <> ?
+      `)
+                .get(input.project, input.scope, ...canonicalNames, expected);
+            return ok((row?.stale_count ?? 0) > 0);
+        }
+        catch (cause) {
+            return fail('Failed to detect agent seed drift', cause);
+        }
+    }
+    upgradeOne(project, scope, name, definition, source, expected) {
+        const existing = this.agents.getByName(project, scope, name);
+        const fromVersion = existing.ok ? readPromptContractVersion(existing.value) : null;
+        if (existing.ok && fromVersion === expected && isByteEqualToCanonical(existing.value, definition)) {
+            return ok({ outcome: 'noop', fromVersion: expected });
+        }
+        const parentAgentId = 'parentAgentName' in definition ? this.resolveParentId(project, scope, definition.parentAgentName) : undefined;
+        if ('parentAgentName' in definition && parentAgentId === undefined) {
+            return validationFailure(`Unresolved parentAgentName: ${definition.parentAgentName}`);
+        }
+        const registerInput = toRegisterInput(project, scope, definition, parentAgentId);
+        const registered = this.agents.register(registerInput);
+        if (!registered.ok) {
+            this.appendHistory({
+                project,
+                scope,
+                agentName: name,
+                fromVersion,
+                toVersion: expected,
+                outcome: registered.error.code === 'validation_failed' ? 'validation_failed' : 'db_error',
+                reason: registered.error.message,
+                source,
+            });
+            return registered;
+        }
+        let outcome;
+        if (!existing.ok) {
+            outcome = 'created';
+        }
+        else if (fromVersion !== null && fromVersion !== expected) {
+            outcome = 'upgraded';
+        }
+        else {
+            outcome = 'overwrote-custom-instructions';
+        }
+        this.appendHistory({
+            project,
+            scope,
+            agentName: name,
+            fromVersion,
+            toVersion: expected,
+            outcome,
+            reason: outcomeReason(outcome, fromVersion, expected, existing.ok),
+            source,
+        });
+        return ok({ outcome, fromVersion });
+    }
+    resolveParentId(project, scope, parentAgentName) {
+        const parent = this.agents.getByName(project, scope, parentAgentName);
+        if (!parent.ok || parent.value.mode !== 'agent')
+            return undefined;
+        return parent.value.id;
+    }
+    appendHistory(input) {
+        this.history.append({
+            project: input.project,
+            scope: input.scope,
+            agentName: input.agentName,
+            fromVersion: input.fromVersion,
+            toVersion: input.toVersion,
+            outcome: input.outcome,
+            reason: input.reason,
+            source: input.source,
+        });
+    }
+}
+function toRegisterInput(project, scope, definition, parentAgentId) {
+    const input = {
+        project,
+        scope,
+        mode: 'parentAgentName' in definition ? 'subagent' : 'agent',
+        name: definition.name,
+        description: definition.description,
+        instructions: definition.instructions,
+    };
+    if (definition.capabilities !== undefined)
+        input.capabilities = definition.capabilities;
+    if (definition.permissions !== undefined)
+        input.permissions = definition.permissions;
+    if (definition.memory !== undefined)
+        input.memory = definition.memory;
+    if (definition.workflows !== undefined)
+        input.workflows = definition.workflows;
+    if (definition.skills !== undefined)
+        input.skills = definition.skills;
+    if (definition.adapters !== undefined)
+        input.adapters = definition.adapters;
+    if (parentAgentId !== undefined)
+        input.parentAgentId = parentAgentId;
+    return input;
+}
+function isByteEqualToCanonical(existing, definition) {
+    if (existing.description !== definition.description)
+        return false;
+    if (existing.instructions.value !== definition.instructions.value)
+        return false;
+    if (!adaptersEqual(existing.adapters, definition.adapters ?? {}))
+        return false;
+    if (!arraysEqual(existing.capabilities, definition.capabilities ?? []))
+        return false;
+    if (!arraysEqual(existing.workflows, definition.workflows ?? []))
+        return false;
+    if (!arraysEqual(existing.skills, definition.skills ?? []))
+        return false;
+    return true;
+}
+function adaptersEqual(a, b) {
+    return JSON.stringify(a ?? {}) === JSON.stringify(b ?? {});
+}
+function arraysEqual(a, b) {
+    if (a.length !== b.length)
+        return false;
+    for (let i = 0; i < a.length; i += 1) {
+        if (a[i] !== b[i])
+            return false;
+    }
+    return true;
+}
+function readPromptContractVersion(agent) {
+    const opencode = agent.adapters?.opencode;
+    if (opencode === undefined)
+        return null;
+    const options = opencode.config?.options;
+    const value = options?.vgxnessPromptContractVersion;
+    if (typeof value !== 'number' || !Number.isInteger(value))
+        return null;
+    return value;
+}
+function outcomeReason(outcome, fromVersion, toVersion, existed) {
+    if (outcome === 'created')
+        return `created canonical row at v${toVersion}`;
+    if (outcome === 'upgraded')
+        return `upgraded v${fromVersion ?? 'unknown'} -> v${toVersion}`;
+    if (outcome === 'overwrote-custom-instructions')
+        return `overwrote customized row (was v${fromVersion ?? 'unknown'}) with v${toVersion} canonical`;
+    return existed ? `noop at v${toVersion}` : `noop at v${toVersion}`;
+}
+function ok(value) {
+    return { ok: true, value };
+}
+function validationFailure(message) {
+    return { ok: false, error: { code: 'validation_failed', message } };
+}
+function fail(message, cause) {
+    const error = { code: 'validation_failed', message };
+    if (cause !== undefined)
+        error.cause = cause;
+    return { ok: false, error };
+}