agencyx-cli 0.0.0-stage → 0.1.0-dev.4

package/dist/adapters/agent.js

@@ -0,0 +1,73 @@
+import { readTextFile } from "../agency/prepared-input.js";
+import { fail } from "../diagnostics.js";
+import { assertKnownFields, isRecord, nonEmptyString, stringArray, } from "../validation.js";
+import { markdownDocument } from "./instructions.js";
+export async function adaptPrimaryAgent(file, effectiveConfig, toolsPolicy = "strict") {
+    const { metadata, body } = markdownDocument(await readTextFile(file), file);
+    assertKnownFields(metadata, [
+        "name",
+        "description",
+        "model",
+        "tools",
+        "mcp-servers",
+        "mcpServers",
+        "agency",
+    ], "primary agent");
+    if (metadata.tools !== undefined) {
+        const tools = typeof metadata.tools === "string"
+            ? metadata.tools.split(",").map((item) => item.trim())
+            : stringArray(metadata.tools, "agent.tools");
+        if (toolsPolicy !== "inherit" && !(tools.length === 1 && tools[0] === "*"))
+            fail("AGENT_TOOLS_UNSUPPORTED", "compatibility", "A restricted Copilot built-in/tool allow-list cannot be enforced by instructions. This agent requires a verified native tool policy.", { path: file, field: "tools" });
+        // Strict mode keeps explicit empty lists from widening access.
+    }
+    if (metadata.model !== undefined && metadata.model !== effectiveConfig.model)
+        fail("AGENT_MODEL_UNSUPPORTED", "compatibility", "The agent model requirement does not match the effective Codex model. No model-name substitution is performed.", { path: file, field: "model" });
+    for (const field of ["mcp-servers", "mcpServers"]) {
+        if (metadata[field] !== undefined &&
+            (!isRecord(metadata[field]) || Object.keys(metadata[field]).length))
+            fail("AGENT_MCP_UNVERIFIED", "compatibility", "The rendered agent still declares MCP behavior that was not proven to be in the Agency final configuration.", { path: file, field });
+    }
+    if (metadata.agency !== undefined) {
+        if (!isRecord(metadata.agency))
+            fail("AGENT_METADATA_INVALID", "configuration", "Agency agent metadata must be an object.", { path: file }, 5);
+        assertKnownFields(metadata.agency, ["inputs", "extra_args", "env", "description", "engine", "agent_type"], "agent.agency");
+        for (const field of ["extra_args", "env"]) {
+            const value = metadata.agency[field];
+            if (value !== undefined &&
+                value !== null &&
+                !(Array.isArray(value) && value.length === 0) &&
+                !(isRecord(value) && Object.keys(value).length === 0))
+                fail("AGENT_CONTRACT_UNVERIFIED", "compatibility", "The rendered agent contains execution metadata without a verified equivalent.", { path: file, field: `agency.${field}` });
+        }
+        if (metadata.agency.engine !== undefined &&
+            metadata.agency.engine !== "codex")
+            fail("AGENT_ENGINE_UNSUPPORTED", "compatibility", "The agent declares a different required execution engine.", { path: file, field: "agency.engine" });
+    }
+    if (!body.trim())
+        fail("AGENT_INSTRUCTIONS_EMPTY", "configuration", "The selected rendered agent has no instructions.", { path: file }, 5);
+    return body;
+}
+export async function readPluginAgent(file) {
+    const { metadata, body } = markdownDocument(await readTextFile(file), file);
+    assertKnownFields(metadata, ["name", "description", "model", "tools"], "plugin agent", file);
+    if (!body.trim())
+        fail("AGENT_INSTRUCTIONS_EMPTY", "configuration", "The plugin agent has no instructions.", { path: file }, 5);
+    const definition = {
+        name: nonEmptyString(metadata.name, "plugin agent name"),
+        description: nonEmptyString(metadata.description, "plugin agent description"),
+        instructions: body,
+        sourcePath: file,
+    };
+    if (!/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(definition.name))
+        fail("AGENT_NAME_UNSUPPORTED", "compatibility", "The plugin agent name contains unsupported characters.", { path: file, field: "name" });
+    if (metadata.tools !== undefined)
+        definition.declaredTools =
+            typeof metadata.tools === "string"
+                ? metadata.tools.split(",").map((tool) => tool.trim())
+                : stringArray(metadata.tools, "plugin agent tools");
+    if (metadata.model !== undefined)
+        definition.model = nonEmptyString(metadata.model, "plugin agent model");
+    return definition;
+}
+//# sourceMappingURL=agent.js.map

package/dist/adapters/ambient.js

@@ -0,0 +1,35 @@
+import { readdir, stat } from "node:fs/promises";
+import path from "node:path";
+import { fail } from "../diagnostics.js";
+async function exists(file) {
+    try {
+        await stat(file);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export async function validateAmbientCopilotContracts(prepared) {
+    for (const root of new Set([
+        prepared.repositoryRoot ?? prepared.cwd,
+        prepared.cwd,
+    ])) {
+        const hooks = path.join(root, ".github", "hooks");
+        if (await exists(hooks)) {
+            const entries = await readdir(hooks, { withFileTypes: true });
+            if (entries.some((entry) => entry.isFile() && entry.name.toLowerCase().endsWith(".json")))
+                fail("REPOSITORY_HOOKS_UNSUPPORTED", "compatibility", "The repository declares Copilot hooks whose execution and blocking semantics have not been adapted. They cannot be omitted from this launch.", { path: hooks });
+        }
+        if (prepared.extraInstructionRoots.some((directory) => path.resolve(directory) === path.resolve(root)))
+            continue;
+        const global = path.join(root, ".github", "copilot-instructions.md");
+        const instructions = path.join(root, ".github", "instructions");
+        if ((await exists(global)) ||
+            ((await exists(instructions)) &&
+                (await readdir(instructions)).some((name) => name.endsWith(".instructions.md")))) {
+            fail("REPOSITORY_INSTRUCTIONS_UNVERIFIED", "compatibility", "Copilot repository instructions require an explicit Agency instruction source and a verified scope/trust mapping. They are not silently omitted or elevated into developer instructions.", { path: root });
+        }
+    }
+}
+//# sourceMappingURL=ambient.js.map

package/dist/adapters/instructions.js

@@ -0,0 +1,102 @@
+import { readdir, stat } from "node:fs/promises";
+import path from "node:path";
+import { parseDocument } from "yaml";
+import { readTextFile } from "../agency/prepared-input.js";
+import { fail } from "../diagnostics.js";
+import { assertKnownFields, isRecord } from "../validation.js";
+export function markdownDocument(text, file) {
+    if (!/^---\r?\n/.test(text))
+        return { metadata: {}, body: text };
+    const match = /^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)([\s\S]*)$/.exec(text);
+    if (!match)
+        fail("FRONTMATTER_INVALID", "configuration", "Markdown frontmatter is not terminated.", { path: file }, 5);
+    const document = parseDocument(match[1], { uniqueKeys: true });
+    if (document.errors.length)
+        fail("FRONTMATTER_INVALID", "configuration", "Markdown frontmatter must contain valid YAML with unique keys.", { path: file }, 5);
+    let metadata;
+    try {
+        metadata = document.toJS({ maxAliasCount: 20 });
+    }
+    catch {
+        fail("FRONTMATTER_INVALID", "configuration", "Markdown frontmatter contains excessive YAML aliases.", { path: file }, 5);
+    }
+    if (metadata !== null && !isRecord(metadata))
+        fail("FRONTMATTER_INVALID", "configuration", "Markdown frontmatter must be an object.", { path: file }, 5);
+    return { metadata: metadata ?? {}, body: match[2] };
+}
+export async function collectInstructions(roots) {
+    const collected = [];
+    const seen = new Set();
+    for (const root of roots) {
+        let metadata;
+        try {
+            metadata = await stat(root);
+        }
+        catch {
+            fail("INSTRUCTIONS_UNREADABLE", "configuration", "An Agency instruction root cannot be read.", { path: root }, 5);
+        }
+        if (!metadata.isDirectory())
+            fail("INSTRUCTIONS_UNREADABLE", "configuration", "An Agency instruction root must be a directory.", { path: root }, 5);
+        const files = [];
+        const global = path.join(root, ".github", "copilot-instructions.md");
+        try {
+            if ((await stat(global)).isFile())
+                files.push(global);
+        }
+        catch {
+            /* Optional global instruction file. */
+        }
+        await collectInstructionFiles(path.join(root, ".github", "instructions"), files);
+        for (const file of files.sort()) {
+            if (seen.has(file))
+                continue;
+            seen.add(file);
+            const { metadata, body } = markdownDocument(await readTextFile(file), file);
+            assertKnownFields(metadata, ["applyTo", "description", "name"], "Agency instructions");
+            if (metadata.applyTo !== undefined &&
+                metadata.applyTo !== "**" &&
+                metadata.applyTo !== "**/*")
+                fail("INSTRUCTION_SCOPE_UNSUPPORTED", "compatibility", "Scoped Copilot instructions cannot be made unconditional Codex developer instructions.", { path: file, field: "applyTo" });
+            if (body.trim())
+                collected.push(body);
+        }
+    }
+    return collected;
+}
+async function collectInstructionFiles(directory, result, depth = 0) {
+    if (depth > 10 || result.length > 1_000)
+        fail("INSTRUCTIONS_LIMIT", "configuration", "Instruction discovery exceeded its supported limit.", { path: directory }, 5);
+    let entries;
+    try {
+        entries = await readdir(directory, { withFileTypes: true });
+    }
+    catch (error) {
+        if (isRecord(error) && error.code === "ENOENT")
+            return;
+        throw error;
+    }
+    for (const entry of entries) {
+        const file = path.join(directory, entry.name);
+        if (entry.isSymbolicLink())
+            fail("INSTRUCTION_PATH_UNSUPPORTED", "compatibility", "Symbolic instruction entries require an explicit verified source path.", { path: file });
+        if (entry.isDirectory())
+            await collectInstructionFiles(file, result, depth + 1);
+        else if (entry.isFile() && entry.name.endsWith(".instructions.md"))
+            result.push(file);
+    }
+}
+export function combineInstructions(original, additions, aliases) {
+    if (original !== undefined &&
+        original !== null &&
+        typeof original !== "string")
+        fail("CODEX_CONFIG_INVALID", "configuration", "Codex developer_instructions must be a string.", {}, 5);
+    const sections = [
+        typeof original === "string" ? original : "",
+        ...additions,
+    ].filter((part) => part.trim());
+    const names = Object.entries(aliases);
+    if (names.length)
+        sections.push(`Agency MCP server aliases for this session:\n${names.map(([from, to]) => `- ${JSON.stringify(from)} is exposed as ${JSON.stringify(to)}.`).join("\n")}\nUse the actual Codex tool catalog for tool names.`);
+    return sections.length ? sections.join("\n\n") : undefined;
+}
+//# sourceMappingURL=instructions.js.map

package/dist/adapters/mcp.js

@@ -0,0 +1,237 @@
+import path from "node:path";
+import { fail } from "../diagnostics.js";
+import { assertKnownFields, isRecord, nonEmptyString, record, stringArray, } from "../validation.js";
+const FIELDS = [
+    "type",
+    "command",
+    "args",
+    "cwd",
+    "url",
+    "headers",
+    "env",
+    "description",
+    "tools",
+    "timeout",
+    "oauthClientId",
+    "oauthPublicClient",
+    "oauthGrantType",
+    "enabled_tools",
+    "disabled_tools",
+    "enabled",
+    "env_vars",
+    "startup_timeout_sec",
+    "tool_timeout_sec",
+];
+export function parseMcpDocument(value) {
+    const document = record(value, "MCP configuration");
+    assertKnownFields(document, ["mcpServers"], "MCP configuration");
+    return record(document.mcpServers, "mcpServers");
+}
+export function convertMcpServer(name, value, cwd) {
+    nonEmptyString(name, "MCP server name");
+    const source = record(value, name);
+    assertKnownFields(source, FIELDS, name);
+    for (const field of [
+        "oauthClientId",
+        "oauthPublicClient",
+        "oauthGrantType",
+    ]) {
+        if (source[field] !== undefined && source[field] !== null)
+            fail("MCP_AUTH_UNSUPPORTED", "compatibility", "Copilot-specific OAuth settings must be handled by an Agency proxy.", { component: name, field });
+    }
+    for (const field of ["headers", "env"]) {
+        if (source[field] !== undefined &&
+            Object.keys(record(source[field], `${name}.${field}`)).length > 0) {
+            fail("MCP_AUTH_UNSUPPORTED", "compatibility", "Literal headers and environment values are not copied into generated command-line configuration. Use an Agency-managed proxy or existing environment references.", { component: name, field });
+        }
+    }
+    const result = {};
+    if (source.command !== undefined && source.url !== undefined)
+        fail("MCP_TRANSPORT_INVALID", "configuration", "A server cannot declare both command and URL transports.", { component: name }, 5);
+    const transport = source.type ?? (source.url !== undefined ? "http" : "stdio");
+    if (transport === "stdio" || transport === "local") {
+        result.command = nonEmptyString(source.command, `${name}.command`);
+        result.args =
+            source.args === undefined ? [] : stringArray(source.args, `${name}.args`);
+        if (result.args.some((arg) => /(?:^|[-_])(?:token|secret|password|authorization|credential)(?:=|$)/i.test(arg))) {
+            fail("MCP_AUTH_UNSUPPORTED", "compatibility", "Authentication arguments must remain inside an Agency-managed proxy.", { component: name, field: "args" });
+        }
+        result.cwd =
+            source.cwd === undefined
+                ? cwd
+                : path.resolve(cwd, nonEmptyString(source.cwd, `${name}.cwd`));
+        if (source.env_vars !== undefined)
+            result.env_vars = stringArray(source.env_vars, `${name}.env_vars`);
+    }
+    else if (transport === "http") {
+        let url;
+        try {
+            url = new URL(nonEmptyString(source.url, `${name}.url`));
+        }
+        catch {
+            fail("MCP_TRANSPORT_INVALID", "configuration", "Expected an absolute HTTP or HTTPS URL.", { component: name, field: "url" }, 5);
+        }
+        if (!["http:", "https:"].includes(url.protocol))
+            fail("MCP_TRANSPORT_UNSUPPORTED", "compatibility", "Only Streamable HTTP and stdio transports are supported.", { component: name });
+        if (url.username || url.password || url.search || url.hash)
+            fail("MCP_AUTH_UNSUPPORTED", "compatibility", "Credential-bearing or query-bearing URLs are not copied into generated command lines. Use an Agency-managed proxy.", { component: name, field: "url" });
+        if (source.args !== undefined ||
+            source.cwd !== undefined ||
+            source.env_vars !== undefined)
+            fail("MCP_TRANSPORT_INVALID", "configuration", "An HTTP server cannot declare stdio-only settings.", { component: name }, 5);
+        result.url = source.url;
+    }
+    else
+        fail("MCP_TRANSPORT_UNSUPPORTED", "compatibility", "The requested transport has no verified Codex mapping. SSE is not relabeled as Streamable HTTP.", { component: name, field: "type" });
+    if (source.tools !== undefined && source.enabled_tools !== undefined)
+        fail("MCP_TOOLS_INVALID", "configuration", "Use one tool allow-list representation.", { component: name }, 5);
+    if (source.tools !== undefined) {
+        const tools = stringArray(source.tools, `${name}.tools`);
+        if (!(tools.length === 1 && tools[0] === "*")) {
+            if (tools.some((tool) => /[*?]/.test(tool)))
+                fail("MCP_TOOLS_UNSUPPORTED", "compatibility", "Only a single all-tools wildcard or exact tool names have a verified mapping.", { component: name, field: "tools" });
+            result.enabled_tools = [...new Set(tools)];
+        }
+    }
+    for (const field of ["enabled_tools", "disabled_tools"]) {
+        if (source[field] !== undefined) {
+            const tools = stringArray(source[field], `${name}.${field}`);
+            if (tools.some((tool) => /[*?]/.test(tool)))
+                fail("MCP_TOOLS_UNSUPPORTED", "compatibility", "Native tool filters require exact tool names.", { component: name, field });
+            result[field] = [...new Set(tools)];
+        }
+    }
+    if (source.timeout !== undefined && source.tool_timeout_sec !== undefined)
+        fail("MCP_TIMEOUT_INVALID", "configuration", "The timeout cannot be specified in two units.", { component: name }, 5);
+    for (const field of ["timeout", "startup_timeout_sec", "tool_timeout_sec"]) {
+        const number = source[field];
+        if (number === undefined)
+            continue;
+        if (typeof number !== "number" || !Number.isFinite(number) || number <= 0)
+            fail("MCP_TIMEOUT_INVALID", "configuration", "Timeouts must be positive finite numbers.", { component: name, field }, 5);
+        result[field === "timeout" ? "tool_timeout_sec" : field] =
+            field === "timeout" ? number / 1_000 : number;
+    }
+    if (source.enabled !== undefined) {
+        if (typeof source.enabled !== "boolean")
+            fail("CONFIG_INVALID", "configuration", "enabled must be a boolean.", { component: name }, 5);
+        result.enabled = source.enabled;
+    }
+    return result;
+}
+function sorted(value) {
+    if (Array.isArray(value))
+        return value.map(sorted);
+    if (isRecord(value))
+        return Object.fromEntries(Object.keys(value)
+            .sort()
+            .filter((key) => value[key] !== null && value[key] !== undefined)
+            .map((key) => [key, sorted(value[key])]));
+    return value;
+}
+export function equivalentMcp(left, right, cwd) {
+    const normalize = (source) => {
+        const result = { ...source };
+        for (const [key, value] of Object.entries(result))
+            if (value === null || value === undefined)
+                delete result[key];
+        const defaults = {
+            enabled: true,
+            required: false,
+            env: {},
+            env_vars: [],
+            disabled_tools: [],
+            startup_timeout_sec: 10,
+            tool_timeout_sec: 60,
+            environment_id: "local",
+        };
+        if (result.command !== undefined) {
+            defaults.args = [];
+            defaults.cwd = cwd;
+        }
+        for (const [key, defaultValue] of Object.entries(defaults))
+            if (JSON.stringify(sorted(result[key])) ===
+                JSON.stringify(sorted(defaultValue)))
+                delete result[key];
+        if (Array.isArray(result.enabled_tools))
+            result.enabled_tools = [...result.enabled_tools].sort();
+        return sorted(result);
+    };
+    return JSON.stringify(normalize(left)) === JSON.stringify(normalize(right));
+}
+export function planMcps(incoming, existing, profileMode, policy, cwd) {
+    if (profileMode === "unknown")
+        fail("PROFILE_ISOLATION_UNKNOWN", "compatibility", "The effective Agency profile mode could not be established. Select --profile or --profile-only explicitly.");
+    const entries = Object.create(null);
+    const plan = {
+        overrides: { mcp_servers: entries },
+        names: [],
+        reused: [],
+        disabled: [],
+        aliases: Object.create(null),
+        findings: [],
+        expected: Object.create(null),
+    };
+    const occupied = new Set([
+        ...Object.keys(existing),
+        ...Object.keys(incoming),
+    ]);
+    for (const [name, raw] of Object.entries(incoming)) {
+        const converted = convertMcpServer(name, raw, cwd);
+        if (converted.enabled !== false)
+            converted.required = true;
+        const previous = Object.hasOwn(existing, name) ? existing[name] : undefined;
+        if (previous !== undefined) {
+            const previousDefinition = record(previous, name);
+            const comparison = converted.required === true
+                ? { ...previousDefinition, required: true }
+                : previousDefinition;
+            if (equivalentMcp(comparison, converted, cwd)) {
+                if (converted.required === true && previousDefinition.required !== true)
+                    entries[name] = { required: true };
+                plan.reused.push(name);
+                plan.names.push(name);
+                plan.expected[name] = converted;
+                continue;
+            }
+            if (policy !== "prefer-agency")
+                fail("MCP_CONFLICT", "compatibility", "An existing Codex server differs from the Agency definition. Use --mcp-conflict=prefer-agency to replace it for this session.", { component: name });
+            // A new name avoids Codex deep-merging transport or auth fields from the old entry.
+            let alias = `agencyx_${name}`;
+            let suffix = 2;
+            while (occupied.has(alias))
+                alias = `agencyx_${name}_${suffix++}`;
+            occupied.add(alias);
+            entries[name] = { enabled: false };
+            entries[alias] = converted;
+            plan.aliases[name] = alias;
+            plan.disabled.push(name);
+            plan.names.push(alias);
+            plan.expected[alias] = converted;
+        }
+        else {
+            entries[name] = converted;
+            plan.names.push(name);
+            plan.expected[name] = converted;
+        }
+    }
+    if (profileMode === "profile-only") {
+        for (const [name, value] of Object.entries(existing)) {
+            if (!Object.hasOwn(incoming, name) &&
+                record(value, name).enabled !== false) {
+                entries[name] = { enabled: false };
+                plan.disabled.push(name);
+            }
+        }
+    }
+    for (const name of plan.names)
+        plan.findings.push({
+            component: `mcp:${name}`,
+            state: plan.reused.includes(name) ? "native" : "adapted",
+            reason: plan.reused.includes(name)
+                ? "The complete effective definition is equivalent and will be reused."
+                : "Agency prepared the connection; Codex performs native MCP discovery and execution.",
+        });
+    return plan;
+}
+//# sourceMappingURL=mcp.js.map

package/dist/adapters/permissions.js

@@ -0,0 +1,42 @@
+import path from "node:path";
+import { fail } from "../diagnostics.js";
+import { isRecord } from "../validation.js";
+export function validateReadGrants(directories, config, requirements) {
+    if (!directories.length)
+        return [];
+    const profile = config.default_permissions;
+    const knownProfile = profile === undefined ||
+        profile === null ||
+        [
+            ":read-only",
+            ":workspace",
+            ":workspace-write",
+            ":danger-full-access",
+            ":unrestricted",
+        ].includes(String(profile));
+    const knownSandbox = config.sandbox_mode === undefined ||
+        config.sandbox_mode === null ||
+        ["read-only", "workspace-write", "danger-full-access"].includes(String(config.sandbox_mode));
+    if (!knownProfile ||
+        !knownSandbox ||
+        config.sandbox_permissions !== undefined ||
+        (requirements &&
+            (requirements.permissions !== undefined ||
+                requirements.filesystem !== undefined))) {
+        fail("READ_PERMISSION_UNVERIFIED", "compatibility", "Agency supplied read-directory grants, but the effective Codex filesystem policy cannot be proven to provide the same access. No writable directories were added.");
+    }
+    if (isRecord(config.permissions) &&
+        Object.keys(config.permissions).length &&
+        profile &&
+        !String(profile).startsWith(":"))
+        fail("READ_PERMISSION_UNVERIFIED", "compatibility", "A custom permissions profile requires a verified filesystem mapping.");
+    return [
+        ...new Set(directories.map((directory) => path.resolve(directory))),
+    ].map((directory) => ({
+        component: "read-directory",
+        state: "adapted",
+        path: directory,
+        reason: "The native Codex policy already permits reads. No write permission is granted by the wrapper.",
+    }));
+}
+//# sourceMappingURL=permissions.js.map