vgxness 0.1.0

package/dist/harness/tools/agents.js

@@ -0,0 +1,245 @@
+import { permissionCategories, permissionDecisions } from '../../permissions/policy-evaluator.js';
+export function createAgentRegistryToolHandlers(dependencies) {
+    const { service } = dependencies;
+    return {
+        registerAgent: (input) => {
+            const mapped = mapRegisterAgentInput(input, false);
+            return mapped.ok ? service.registerAgent(mapped.value) : mapped;
+        },
+        registerSubagent: (input) => {
+            const mapped = mapRegisterAgentInput(input, true);
+            return mapped.ok ? service.registerSubagent(mapped.value) : mapped;
+        },
+        getAgent: (input) => {
+            const mappedInput = requireRecord(input, 'input');
+            if (!mappedInput.ok)
+                return mappedInput;
+            const payload = mappedInput.value;
+            const id = requireString(payload.id, 'id');
+            return id.ok ? service.getAgent(id.value) : id;
+        },
+        getAgentByName: (input) => {
+            const mapped = mapNaturalKey(input);
+            return mapped.ok ? service.getAgentByName(mapped.value.project, mapped.value.scope, mapped.value.name) : mapped;
+        },
+        listAgents: (input) => {
+            const mapped = mapListFilters(input ?? {});
+            return mapped.ok ? service.listAgents(mapped.value) : mapped;
+        },
+        listSubagents: (input) => {
+            const mappedInput = requireRecord(input, 'input');
+            if (!mappedInput.ok)
+                return mappedInput;
+            const payload = mappedInput.value;
+            const parentAgentId = requireString(payload.parentAgentId, 'parentAgentId');
+            return parentAgentId.ok ? service.listSubagents(parentAgentId.value) : parentAgentId;
+        },
+    };
+}
+function mapRegisterAgentInput(input, subagent) {
+    const mappedInput = requireRecord(input, 'input');
+    if (!mappedInput.ok)
+        return mappedInput;
+    const payload = mappedInput.value;
+    const project = requireString(payload.project, 'project');
+    if (!project.ok)
+        return project;
+    const scope = requireScope(payload.scope, 'scope');
+    if (!scope.ok)
+        return scope;
+    const name = requireString(payload.name, 'name');
+    if (!name.ok)
+        return name;
+    const description = requireString(payload.description, 'description');
+    if (!description.ok)
+        return description;
+    const instructions = requireInstructions(payload.instructions);
+    if (!instructions.ok)
+        return instructions;
+    const capabilities = optionalStringArray(payload.capabilities, 'capabilities');
+    if (!capabilities.ok)
+        return capabilities;
+    const permissions = optionalPermissions(payload.permissions);
+    if (!permissions.ok)
+        return permissions;
+    const memory = optionalMemory(payload.memory);
+    if (!memory.ok)
+        return memory;
+    const workflows = optionalStringArray(payload.workflows, 'workflows');
+    if (!workflows.ok)
+        return workflows;
+    const skills = optionalStringArray(payload.skills, 'skills');
+    if (!skills.ok)
+        return skills;
+    const adapters = optionalAdapters(payload.adapters);
+    if (!adapters.ok)
+        return adapters;
+    const value = {
+        project: project.value,
+        scope: scope.value,
+        mode: subagent ? 'subagent' : 'agent',
+        name: name.value,
+        description: description.value,
+        instructions: instructions.value,
+    };
+    if (capabilities.value !== undefined)
+        value.capabilities = capabilities.value;
+    if (permissions.value !== undefined)
+        value.permissions = permissions.value;
+    if (memory.value !== undefined)
+        value.memory = memory.value;
+    if (workflows.value !== undefined)
+        value.workflows = workflows.value;
+    if (skills.value !== undefined)
+        value.skills = skills.value;
+    if (adapters.value !== undefined)
+        value.adapters = adapters.value;
+    if (subagent) {
+        const parentAgentId = requireString(payload.parentAgentId, 'parentAgentId');
+        if (!parentAgentId.ok)
+            return parentAgentId;
+        value.parentAgentId = parentAgentId.value;
+    }
+    return ok(value);
+}
+function mapNaturalKey(input) {
+    const mappedInput = requireRecord(input, 'input');
+    if (!mappedInput.ok)
+        return mappedInput;
+    const payload = mappedInput.value;
+    const project = requireString(payload.project, 'project');
+    if (!project.ok)
+        return project;
+    const scope = requireScope(payload.scope, 'scope');
+    if (!scope.ok)
+        return scope;
+    const name = requireString(payload.name, 'name');
+    if (!name.ok)
+        return name;
+    return ok({ project: project.value, scope: scope.value, name: name.value });
+}
+function mapListFilters(input) {
+    const mappedInput = requireRecord(input, 'input');
+    if (!mappedInput.ok)
+        return mappedInput;
+    const payload = mappedInput.value;
+    const filters = {};
+    if (payload.project !== undefined) {
+        const project = requireString(payload.project, 'project');
+        if (!project.ok)
+            return project;
+        filters.project = project.value;
+    }
+    if (payload.scope !== undefined) {
+        const scope = requireScope(payload.scope, 'scope');
+        if (!scope.ok)
+            return scope;
+        filters.scope = scope.value;
+    }
+    if (payload.mode !== undefined) {
+        if (payload.mode !== 'agent' && payload.mode !== 'subagent')
+            return validationFailure('mode must be agent or subagent');
+        filters.mode = payload.mode;
+    }
+    if (payload.parentAgentId !== undefined) {
+        const parentAgentId = requireString(payload.parentAgentId, 'parentAgentId');
+        if (!parentAgentId.ok)
+            return parentAgentId;
+        filters.parentAgentId = parentAgentId.value;
+    }
+    return ok(filters);
+}
+function requireString(value, field) {
+    return typeof value === 'string' && value.trim() ? ok(value) : validationFailure(`${field} must be a non-empty string`);
+}
+function requireScope(value, field) {
+    return value === 'project' || value === 'personal' ? ok(value) : validationFailure(`${field} must be project or personal`);
+}
+function requireRecord(value, field) {
+    return isRecord(value) ? ok(value) : validationFailure(`${field} must be an object`);
+}
+function requireInstructions(value) {
+    if (!isRecord(value))
+        return validationFailure('instructions must be an object');
+    if (value.kind !== 'inline' && value.kind !== 'path')
+        return validationFailure('instructions.kind must be inline or path');
+    const instructionValue = requireString(value.value, 'instructions.value');
+    return instructionValue.ok ? ok({ kind: value.kind, value: instructionValue.value }) : instructionValue;
+}
+function optionalStringArray(value, field) {
+    if (value === undefined)
+        return ok(undefined);
+    if (!Array.isArray(value) || value.some((item) => typeof item !== 'string'))
+        return validationFailure(`${field} must be an array of strings`);
+    return ok(value);
+}
+function optionalPermissions(value) {
+    if (value === undefined)
+        return ok(undefined);
+    if (!isRecord(value))
+        return validationFailure('permissions must be an object');
+    const permissions = {};
+    for (const [key, decision] of Object.entries(value)) {
+        if (!permissionCategories.includes(key))
+            return validationFailure(`Unknown permission category: ${key}`);
+        if (!permissionDecisions.includes(decision))
+            return validationFailure(`Invalid permission decision for ${key}`);
+        permissions[key] = decision;
+    }
+    return ok(permissions);
+}
+function optionalMemory(value) {
+    if (value === undefined)
+        return ok(undefined);
+    if (!isRecord(value) || !Array.isArray(value.scopes))
+        return validationFailure('memory.scopes must be an array');
+    const scopes = [];
+    for (const scope of value.scopes) {
+        const mapped = requireScope(scope, 'memory.scopes[]');
+        if (!mapped.ok)
+            return mapped;
+        scopes.push(mapped.value);
+    }
+    return ok({ scopes });
+}
+function optionalAdapters(value) {
+    if (value === undefined)
+        return ok(undefined);
+    if (!isRecord(value))
+        return validationFailure('adapters must be an object');
+    const adapters = {};
+    for (const [name, adapter] of Object.entries(value)) {
+        if (!isRecord(adapter))
+            return validationFailure(`adapters.${name} must be an object`);
+        const config = {};
+        if (adapter.model !== undefined) {
+            if (typeof adapter.model !== 'string')
+                return validationFailure(`adapters.${name}.model must be a string`);
+            config.model = adapter.model;
+        }
+        if (adapter.config !== undefined) {
+            if (!isRecord(adapter.config) || !isJsonValue(adapter.config))
+                return validationFailure(`adapters.${name}.config must be JSON-compatible`);
+            config.config = adapter.config;
+        }
+        adapters[name] = config;
+    }
+    return ok(adapters);
+}
+function isJsonValue(value) {
+    if (value === null || typeof value === 'string' || typeof value === 'boolean')
+        return true;
+    if (typeof value === 'number')
+        return Number.isFinite(value);
+    if (Array.isArray(value))
+        return value.every(isJsonValue);
+    return isRecord(value) && Object.values(value).every(isJsonValue);
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function ok(value) { return { ok: true, value }; }
+function validationFailure(message) {
+    const error = { code: 'validation_failed', message };
+    return { ok: false, error };
+}

package/dist/harness/tools/memory.js

@@ -0,0 +1,29 @@
+export function createMemoryToolHandlers(dependencies) {
+    const { service, config, fallback } = dependencies;
+    return {
+        saveObservation: (input, context) => localOrFallback(config, fallback?.saveObservation, context, () => service.saveObservation(input, context), input),
+        getObservation: (input, context) => localOrFallback(config, fallback?.getObservation, context, () => service.getObservation(input.id, context), input.id),
+        updateObservation: (input, context) => localOrFallback(config, fallback?.updateObservation, context, () => service.updateObservation(input, context), input),
+        searchObservations: (input, context) => localOrFallback(config, fallback?.searchObservations, context, () => service.searchObservations(input, context), input),
+        listObservationRevisions: (input, context) => localOrFallback(config, fallback?.listObservationRevisions, context, () => service.listObservationRevisions(input.id, context), input),
+        saveSession: (input, context) => localOrFallback(config, fallback?.saveSession, context, () => service.saveSession(input, context), input),
+        appendActivity: (input, context) => localOrFallback(config, fallback?.appendActivity, context, () => service.appendActivity(input, context), input),
+        closeSession: (input, context) => localOrFallback(config, fallback?.closeSession, context, () => service.closeSession(input, context), input),
+        restoreSession: (input, context) => localOrFallback(config, fallback?.restoreSession, context, () => service.restoreSession(input), input),
+        saveArtifact: (input, context) => localOrFallback(config, fallback?.saveArtifact, context, () => service.saveArtifact(input, context), input),
+        getArtifact: (input, context) => localOrFallback(config, fallback?.getArtifact, context, () => service.getArtifact(input.project, input.topicKey, context), input),
+    };
+}
+function localOrFallback(config, fallback, context, local, input) {
+    if (config.localMemoryEnabled)
+        return local();
+    if (fallback)
+        return fallback(input, context);
+    return { ok: false, error: disabledFailure() };
+}
+function disabledFailure() {
+    return {
+        code: 'validation_failed',
+        message: 'Local memory tool is disabled and no Engram fallback is configured',
+    };
+}

package/dist/mcp/client-install-opencode-contract.js

@@ -0,0 +1,227 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { createOpenCodeDefaultAgentConfig, createOpenCodeDefaultAgentInstallPlan } from './opencode-default-agent-config.js';
+const opencodeConfigSchema = 'https://opencode.ai/config.json';
+const supportedConfigTargets = [
+    '.opencode/opencode.json',
+    'opencode.json',
+    '.opencode/opencode.jsonc',
+    'opencode.jsonc',
+];
+export function resolveOpenCodeMcpInstallTarget(input) {
+    const scope = input.scope ?? 'project';
+    if (scope === 'project')
+        return { ok: true, scope, path: join(input.cwd, '.opencode', 'opencode.json') };
+    const home = input.env?.HOME;
+    if (typeof home !== 'string' || home.trim().length === 0) {
+        return { ok: false, scope, reason: 'missing_home', message: 'Unable to resolve OpenCode user config because HOME is not set.' };
+    }
+    return { ok: true, scope, path: join(home, '.config', 'opencode', 'opencode.json') };
+}
+export function planOpenCodeMcpInstall(input) {
+    const databasePathSource = input.databasePathSource ?? 'flag';
+    const server = createOpenCodeLocalMcpServerConfig(input.databasePath, databasePathSource);
+    const scope = input.scope ?? 'project';
+    const agentPlan = createOpenCodeDefaultAgentInstallPlan({ mcpOnly: input.mcpOnly });
+    if (scope === 'user') {
+        return planUserOpenCodeMcpInstall(input, databasePathSource, server, agentPlan);
+    }
+    const existingTargets = supportedConfigTargets
+        .map((relativePath) => ({ relativePath, absolutePath: join(input.cwd, relativePath) }))
+        .filter((target) => existsSync(target.absolutePath));
+    if (existingTargets.length > 1) {
+        return refusal('ambiguous_target', `Multiple OpenCode project config targets exist: ${existingTargets.map((target) => target.relativePath).join(', ')}. Remove ambiguity before installing.`, input.databasePath, databasePathSource, scope, undefined, [{ kind: 'manual-check', message: 'Remove ambiguity by keeping exactly one OpenCode project config target before installing.' }], agentPlan);
+    }
+    if (existingTargets.length === 0) {
+        return {
+            ...baseContract(input.databasePath, databasePathSource, scope, join(input.cwd, '.opencode', 'opencode.json'), false, 'create', agentPlan),
+            status: 'would_install',
+            action: 'create',
+            targetPath: join(input.cwd, '.opencode', 'opencode.json'),
+            backupRequired: false,
+            server,
+            preservedTopLevelKeys: agentPlan.installsAgents ? ['$schema', 'default_agent', 'agent', 'mcp'] : ['$schema', 'mcp'],
+            existingSchema: null,
+        };
+    }
+    const [target] = existingTargets;
+    if (target === undefined)
+        return refusal('ambiguous_target', 'Unable to resolve OpenCode project config target.', input.databasePath, databasePathSource, scope);
+    if (target.relativePath.endsWith('.jsonc')) {
+        return refusal('unsupported_jsonc', `OpenCode JSONC config ${target.relativePath} is not supported yet; use JSON or remove comments first.`, input.databasePath, databasePathSource, scope, target.absolutePath, [], agentPlan);
+    }
+    const parsed = parseConfig(target.absolutePath);
+    if (!parsed.ok)
+        return refusal(parsed.reason, parsed.message, input.databasePath, databasePathSource, scope, target.absolutePath, [], agentPlan);
+    const config = parsed.value;
+    if (config.mcp !== undefined && !isRecord(config.mcp)) {
+        return refusal('invalid_mcp_shape', 'Existing top-level mcp must be a JSON object before vgxness can be merged.', input.databasePath, databasePathSource, scope, target.absolutePath, [], agentPlan);
+    }
+    if (isRecord(config.mcp) && Object.hasOwn(config.mcp, 'vgxness')) {
+        return refusal('existing_vgxness_mcp', 'Existing OpenCode config already contains mcp.vgxness; overwrite is refused by default.', input.databasePath, databasePathSource, scope, target.absolutePath, [], agentPlan);
+    }
+    const agentConflict = findConflictingVgxnessAgents(config, agentPlan);
+    if (agentConflict.length > 0) {
+        return refusal('existing_vgxness_agent', `Existing OpenCode config contains custom VGXNESS agent entries that would be overwritten: ${agentConflict.join(', ')}. Remove, rename, or manually reconcile them before installing.`, input.databasePath, databasePathSource, scope, target.absolutePath, [{ kind: 'manual-check', message: `Manually reconcile conflicting VGXNESS agent entries: ${agentConflict.join(', ')}.` }], agentPlan);
+    }
+    return {
+        ...baseContract(input.databasePath, databasePathSource, scope, target.absolutePath, true, 'merge-preserve-existing', agentPlan),
+        status: 'would_install',
+        action: 'merge',
+        targetPath: target.absolutePath,
+        backupRequired: true,
+        server,
+        preservedTopLevelKeys: Object.keys(config),
+        existingSchema: typeof config.$schema === 'string' ? config.$schema : opencodeConfigSchema,
+    };
+}
+function planUserOpenCodeMcpInstall(input, databasePathSource, server, agentPlan) {
+    const target = resolveOpenCodeMcpInstallTarget({ cwd: input.cwd, scope: 'user', env: input.env });
+    if (!target.ok) {
+        return refusal('unsupported_config_shape', target.message, input.databasePath, databasePathSource, 'user');
+    }
+    const jsoncPath = `${target.path}c`;
+    if (existsSync(jsoncPath)) {
+        return refusal('unsupported_jsonc', 'OpenCode user JSONC config opencode.jsonc is not supported yet; use JSON or remove comments first.', input.databasePath, databasePathSource, 'user', jsoncPath, [], agentPlan);
+    }
+    if (!existsSync(target.path)) {
+        return {
+            ...baseContract(input.databasePath, databasePathSource, 'user', target.path, false, 'create', agentPlan),
+            status: 'would_install',
+            action: 'create',
+            targetPath: target.path,
+            backupRequired: false,
+            server,
+            preservedTopLevelKeys: agentPlan.installsAgents ? ['$schema', 'default_agent', 'agent', 'mcp'] : ['$schema', 'mcp'],
+            existingSchema: null,
+        };
+    }
+    const parsed = parseConfig(target.path);
+    if (!parsed.ok)
+        return refusal(parsed.reason, parsed.message, input.databasePath, databasePathSource, 'user', target.path, [], agentPlan);
+    const config = parsed.value;
+    if (config.mcp !== undefined && !isRecord(config.mcp)) {
+        return refusal('invalid_mcp_shape', 'Existing top-level mcp must be a JSON object before vgxness can be merged.', input.databasePath, databasePathSource, 'user', target.path, [], agentPlan);
+    }
+    if (isRecord(config.mcp) && Object.hasOwn(config.mcp, 'vgxness')) {
+        return refusal('existing_vgxness_mcp', 'Existing OpenCode config already contains mcp.vgxness; overwrite is refused by default.', input.databasePath, databasePathSource, 'user', target.path, [], agentPlan);
+    }
+    const agentConflict = findConflictingVgxnessAgents(config, agentPlan);
+    if (agentConflict.length > 0) {
+        return refusal('existing_vgxness_agent', `Existing OpenCode config contains custom VGXNESS agent entries that would be overwritten: ${agentConflict.join(', ')}. Remove, rename, or manually reconcile them before installing.`, input.databasePath, databasePathSource, 'user', target.path, [{ kind: 'manual-check', message: `Manually reconcile conflicting VGXNESS agent entries: ${agentConflict.join(', ')}.` }], agentPlan);
+    }
+    return {
+        ...baseContract(input.databasePath, databasePathSource, 'user', target.path, true, 'merge-preserve-existing', agentPlan),
+        status: 'would_install',
+        action: 'merge',
+        targetPath: target.path,
+        backupRequired: true,
+        server,
+        preservedTopLevelKeys: Object.keys(config),
+        existingSchema: typeof config.$schema === 'string' ? config.$schema : opencodeConfigSchema,
+    };
+}
+function createOpenCodeLocalMcpServerConfig(databasePath, source) {
+    return { type: 'local', command: createVgxnessMcpServerCommand(databasePath, source), enabled: true };
+}
+function createVgxnessMcpServerCommand(databasePath, source) {
+    return source === 'global-default' ? ['vgxness', 'mcp', 'start'] : ['vgxness', 'mcp', 'start', '--db', databasePath];
+}
+function createVgxnessMcpDoctorCommand(databasePath, source) {
+    return source === 'global-default' ? ['vgxness', 'mcp', 'doctor'] : ['vgxness', 'mcp', 'doctor', '--db', databasePath];
+}
+function parseConfig(path) {
+    try {
+        const parsed = JSON.parse(readFileSync(path, 'utf8'));
+        return isRecord(parsed)
+            ? { ok: true, value: parsed }
+            : { ok: false, reason: 'unsupported_config_shape', message: 'OpenCode config must be a JSON object.' };
+    }
+    catch {
+        return { ok: false, reason: 'malformed_json', message: 'OpenCode config must be valid JSON; malformed JSON and JSONC comments are refused.' };
+    }
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+export function findConflictingVgxnessAgents(config, agentPlan) {
+    if (!agentPlan.installsAgents || !isRecord(config.agent))
+        return [];
+    const defaults = createOpenCodeDefaultAgentConfig().agents;
+    return agentPlan.agentNames.filter((name) => Object.hasOwn(config.agent, name) && !deepEqual(config.agent[name], defaults[name]));
+}
+function deepEqual(left, right) {
+    if (Object.is(left, right))
+        return true;
+    if (Array.isArray(left) || Array.isArray(right)) {
+        return Array.isArray(left) && Array.isArray(right) && left.length === right.length && left.every((value, index) => deepEqual(value, right[index]));
+    }
+    if (!isRecord(left) || !isRecord(right))
+        return false;
+    const leftKeys = Object.keys(left).sort();
+    const rightKeys = Object.keys(right).sort();
+    return leftKeys.length === rightKeys.length && leftKeys.every((key, index) => key === rightKeys[index] && deepEqual(left[key], right[key]));
+}
+function baseContract(databasePath, source, scope, targetPath, backupRequired, mergePolicy, agentPlan = createOpenCodeDefaultAgentInstallPlan({ mcpOnly: true })) {
+    return {
+        version: 1,
+        kind: 'mcp-client-install-opencode',
+        installable: true,
+        mutating: false,
+        safety: {
+            operation: 'plan',
+            mutating: false,
+            writesProviderConfig: false,
+            ...(targetPath !== undefined ? { targetPath } : {}),
+            backupRequired,
+            mergePolicy,
+        },
+        scope,
+        warnings: warningsForScope(scope),
+        verificationHints: verificationHints(databasePath, source),
+        manualTest: manualTestForScope(scope, databasePath, source),
+        installsAgents: agentPlan.installsAgents,
+        agentNames: agentPlan.agentNames,
+        ...(agentPlan.defaultAgent !== undefined ? { defaultAgent: agentPlan.defaultAgent } : {}),
+    };
+}
+function refusal(reason, message, databasePath, source, scope, targetPath, extraVerificationHints = [], agentPlan = createOpenCodeDefaultAgentInstallPlan({ mcpOnly: true })) {
+    const contract = baseContract(databasePath, source, scope, targetPath, false, 'refuse-no-clobber', agentPlan);
+    return {
+        ...contract,
+        verificationHints: [...extraVerificationHints, ...contract.verificationHints],
+        status: 'refused',
+        reason,
+        message,
+        ...(targetPath !== undefined ? { targetPath } : {}),
+    };
+}
+function warningsForScope(scope) {
+    if (scope === 'project')
+        return ['Restart OpenCode after installation so it reloads the project MCP config.'];
+    return [
+        'Restart OpenCode after installation so it reloads the user MCP config.',
+        'OpenCode project config may override user config for a workspace; check project-level config if vgxness is not visible.',
+    ];
+}
+function manualTestForScope(scope, databasePath, source) {
+    if (scope === 'project') {
+        return {
+            restart: 'Restart OpenCode after the config is installed.',
+            verify: 'Open the project in OpenCode and verify the vgxness MCP server is available.',
+            doctorCommand: createVgxnessMcpDoctorCommand(databasePath, source),
+        };
+    }
+    return {
+        restart: 'Restart OpenCode after the user config is installed.',
+        verify: 'Open OpenCode and verify the vgxness MCP server is available from the user OpenCode config; project config may override it.',
+        doctorCommand: createVgxnessMcpDoctorCommand(databasePath, source),
+    };
+}
+function verificationHints(databasePath, source) {
+    return [
+        { kind: 'restart-client', message: 'Restart OpenCode after the config is installed.' },
+        { kind: 'manual-check', message: 'Open the project in OpenCode and verify the vgxness MCP server is available.' },
+        { kind: 'command', message: 'Run the MCP doctor command after installation.', command: createVgxnessMcpDoctorCommand(databasePath, source) },
+    ];
+}