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

package/dist/codex/skill-policy.js

@@ -0,0 +1,69 @@
+import path from "node:path";
+import { fail } from "../diagnostics.js";
+import { isRecord } from "../validation.js";
+function restrictedSkills(views) {
+    return views.flatMap((view) => view.skills.filter((skill) => skill.userInvocable === false));
+}
+function normalized(file) {
+    const resolved = path.resolve(file);
+    return process.platform === "win32" ? resolved.toLowerCase() : resolved;
+}
+function explicitMention(text, name) {
+    const literal = name.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    // Match native $skill syntax, preserving escaped dollars and longer names.
+    return new RegExp(String.raw `(?<![\\\p{L}\p{N}_$])\$${literal}(?![\p{L}\p{N}_:-])`, "u").test(text);
+}
+export function assertUserSkillInvocation(request, views) {
+    if (request.method !== "turn/start" && request.method !== "turn/steer")
+        return;
+    const restricted = restrictedSkills(views);
+    if (!restricted.length)
+        return;
+    if (!isRecord(request.params) || !Array.isArray(request.params.input))
+        fail("CODEX_PROTOCOL_INVALID", "codex", "The frontend sent invalid turn input.", {}, 6);
+    for (const input of request.params.input) {
+        if (!isRecord(input))
+            continue;
+        for (const skill of restricted) {
+            const names = [
+                skill.name,
+                ...(skill.sourceName ? [skill.sourceName] : []),
+            ];
+            const paths = [
+                skill.path,
+                ...(skill.sourcePath ? [skill.sourcePath] : []),
+            ];
+            const selected = input.type === "skill" &&
+                ((typeof input.name === "string" && names.includes(input.name)) ||
+                    (typeof input.path === "string" &&
+                        paths.some((file) => normalized(file) === normalized(input.path))));
+            const mentioned = input.type === "text" &&
+                typeof input.text === "string" &&
+                names.some((name) => explicitMention(input.text, name));
+            if (selected || mentioned)
+                fail("SKILL_USER_INVOCATION_DISABLED", "compatibility", "Agency marks this skill as user-invocable: false. It remains registered for native implicit use and cannot be invoked explicitly by the frontend.", { component: skill.name, field: "user-invocable" });
+        }
+    }
+}
+export function filterUserSkillCatalogue(value, views) {
+    const hidden = new Set(restrictedSkills(views).map((skill) => skill.name));
+    if (!hidden.size ||
+        !isRecord(value) ||
+        !isRecord(value.result) ||
+        !Array.isArray(value.result.data))
+        return value;
+    let changed = false;
+    const data = value.result.data.map((entry) => {
+        if (!isRecord(entry) || !Array.isArray(entry.skills))
+            return entry;
+        const skills = entry.skills.filter((skill) => !(isRecord(skill) &&
+            typeof skill.name === "string" &&
+            hidden.has(skill.name)));
+        if (skills.length === entry.skills.length)
+            return entry;
+        changed = true;
+        return { ...entry, skills };
+    });
+    return changed ? { ...value, result: { ...value.result, data } } : value;
+}
+//# sourceMappingURL=skill-policy.js.map

package/dist/codex/skill-views.js

@@ -0,0 +1,104 @@
+import { chmod, cp, mkdir, mkdtemp, readFile, realpath, writeFile, } from "node:fs/promises";
+import path from "node:path";
+import { fail } from "../diagnostics.js";
+import { packageFingerprint } from "../adapters/plugins.js";
+import { markdownDocument } from "../adapters/instructions.js";
+import { parseDocument } from "yaml";
+export async function createSkillView(spec, sessionRoot, options = {}) {
+    if ((!spec.skills.length &&
+        !spec.agents?.length &&
+        !spec.hooks.some((hook) => hook.count > 0)) ||
+        (spec.hooks.some((hook) => hook.count > 0) && !options.allowHooks) ||
+        spec.primaryAgentPath !== undefined)
+        fail("PLUGIN_NOT_READY", "compatibility", "A cold mixed-component plugin needs the native whole-plugin preparation and trust path.", { component: spec.name });
+    await packageFingerprint(spec.root);
+    const root = await mkdtemp(path.join(sessionRoot, "plugin-view-"));
+    await chmod(root, 0o700);
+    const packageRoot = path.join(root, "package");
+    const fileKey = (file) => process.platform === "win32"
+        ? path.resolve(file).toLowerCase()
+        : path.resolve(file);
+    const mcpFiles = new Set(spec.mcpFiles.map(fileKey));
+    await cp(spec.root, packageRoot, {
+        recursive: true,
+        filter: (source) => path.basename(source) !== ".git" && !mcpFiles.has(fileKey(source)),
+    });
+    // Agency already resolved these MCPs, including authentication and tool
+    // filters. Suppress every original declaration in the session view so it
+    // cannot create a duplicate connection or copy literal credentials.
+    for (const original of spec.mcpFiles) {
+        const target = path.join(packageRoot, path.relative(spec.root, original));
+        await mkdir(path.dirname(target), { recursive: true });
+        await writeFile(target, '{"mcpServers":{}}\n', { mode: 0o600 });
+    }
+    const view = {
+        pluginName: spec.name,
+        root,
+        extraRoots: [],
+        skills: [],
+    };
+    for (const original of spec.skills) {
+        const target = path.join(packageRoot, path.relative(spec.root, original));
+        const text = await readFile(target, "utf8");
+        const parsed = markdownDocument(text, original);
+        const name = `${spec.name}:${String(parsed.metadata.name)}`;
+        // The native skill loader reads the retained plugin manifest and adds its
+        // namespace itself. Keep every source file, including frontmatter, intact.
+        if (spec.manualInvocationSkills.includes(original)) {
+            const metadataFile = path.join(path.dirname(target), "agents", "openai.yaml");
+            const existing = await readFile(metadataFile, "utf8").catch(() => "");
+            const document = parseDocument(existing || "{}\n");
+            document.setIn(["policy", "allow_implicit_invocation"], false);
+            await mkdir(path.dirname(metadataFile), { recursive: true, mode: 0o700 });
+            const eol = existing.includes("\r\n") ? "\r\n" : "\n";
+            await writeFile(metadataFile, document.toString().replace(/\r?\n/g, eol), { mode: 0o600 });
+        }
+        view.skills.push({
+            name,
+            path: target,
+            sourceName: String(parsed.metadata.name),
+            sourcePath: original,
+            userInvocable: parsed.metadata["user-invocable"] !== false,
+        });
+        view.extraRoots.push(path.dirname(path.dirname(target)));
+    }
+    view.extraRoots = [...new Set(view.extraRoots)];
+    return view;
+}
+async function canonical(file) {
+    const resolved = await realpath(file).catch(() => path.resolve(file));
+    return process.platform === "win32" ? resolved.toLowerCase() : resolved;
+}
+export async function registerSkillViews(client, views) {
+    if (!views.length)
+        return;
+    await client.request("skills/extraRoots/set", {
+        extraRoots: [...new Set(views.flatMap((view) => view.extraRoots))],
+    });
+}
+export async function verifySkillViews(views, loaded) {
+    const expected = new Set();
+    for (const view of views) {
+        for (const skill of view.skills) {
+            const target = await canonical(skill.path);
+            expected.add(target);
+            const matches = loaded.filter((candidate) => candidate.name === skill.name && candidate.enabled);
+            if (matches.length !== 1 ||
+                (await canonical(matches[0].path)) !== target)
+                fail("SKILL_VIEW_NOT_READY", "compatibility", "A required skill is missing, disabled, or conflicts with another native skill.", { component: skill.name });
+        }
+    }
+    for (const skill of loaded) {
+        const target = await canonical(skill.path);
+        for (const view of views) {
+            const root = await canonical(view.root);
+            const relative = path.relative(root, target);
+            if (!relative.startsWith(`..${path.sep}`) &&
+                relative !== ".." &&
+                !path.isAbsolute(relative) &&
+                !expected.has(target))
+                fail("SKILL_SOURCE_SCOPE_UNVERIFIED", "compatibility", "Native discovery found an extra execution skill outside the validated package selection.", { component: view.pluginName });
+        }
+    }
+}
+//# sourceMappingURL=skill-views.js.map

package/dist/codex/toml.js

@@ -0,0 +1,46 @@
+import { parse } from "smol-toml";
+import { fail } from "../diagnostics.js";
+import { isRecord } from "../validation.js";
+export function tomlValue(value) {
+    if (typeof value === "string") {
+        if (!value.isWellFormed())
+            fail("CONFIG_ENCODING_INVALID", "configuration", "Configuration strings must contain valid Unicode.", {}, 5);
+        return JSON.stringify(value).replace(/[\u007f]/g, "\\u007f");
+    }
+    if (typeof value === "boolean" ||
+        (typeof value === "number" && Number.isFinite(value)))
+        return String(value);
+    if (Array.isArray(value))
+        return `[${value.map(tomlValue).join(",")}]`;
+    if (isRecord(value))
+        return `{${Object.entries(value)
+            .map(([key, item]) => `${tomlValue(key)}=${tomlValue(item)}`)
+            .join(",")}}`;
+    fail("CONFIG_ENCODING_INVALID", "configuration", "Only strings, finite numbers, booleans, arrays, and tables can be encoded as overrides.", {}, 5);
+}
+export function configArguments(overrides) {
+    // Encode the whole top-level table so names containing dots never become paths.
+    return Object.entries(overrides).flatMap(([key, value]) => [
+        "-c",
+        `${key}=${tomlValue(value)}`,
+    ]);
+}
+export function parseOverride(value) {
+    try {
+        const equals = value.indexOf("=");
+        if (equals <= 0 || value.includes("\0"))
+            throw new Error("Invalid override.");
+        // Codex treats an unquoted value that is not valid TOML as a literal string.
+        parse(`${value.slice(0, equals)}=true`);
+        try {
+            return parse(value);
+        }
+        catch {
+            return parse(`${value.slice(0, equals)}=${tomlValue(value.slice(equals + 1))}`);
+        }
+    }
+    catch {
+        fail("CODEX_ARGUMENT_INVALID", "arguments", "Configuration overrides must use valid TOML key=value syntax.", { field: "--config" }, 2);
+    }
+}
+//# sourceMappingURL=toml.js.map

package/dist/commands/codex.js

@@ -0,0 +1,118 @@
+import { fileURLToPath } from "node:url";
+import { resolveCommand } from "../runtime/resolve-command.js";
+import { createLauncher, createSession } from "../runtime/session.js";
+import { SessionServer } from "../runtime/ipc.js";
+import { exitCode, observeSignals, startProcess } from "../runtime/process.js";
+import { agencyArguments, agencyEnvironment, resolveProfileMode, validateAgencyOptions, } from "../agency/invocation.js";
+import { AgencyxError, fail, formatDiagnostic } from "../diagnostics.js";
+import { isRecord } from "../validation.js";
+import { parseCodexOptions } from "../codex/options.js";
+import { formatPlan } from "../diagnostics/plan.js";
+export async function runCodex(options, env = process.env, cwd = process.cwd()) {
+    validateAgencyOptions(options.agencyArgs);
+    parseCodexOptions(options.codexArgs, cwd);
+    const [agencyPath, codexPath] = await Promise.all([
+        resolveCommand("agency", env.AGENCYX_AGENCY_PATH, cwd, env),
+        resolveCommand("codex", env.AGENCYX_CODEX_PATH, cwd, env),
+    ]);
+    const agencyEnv = agencyEnvironment(env);
+    const profileMode = await resolveProfileMode(agencyPath, options.agencyArgs, cwd, agencyEnv);
+    if (profileMode === "unknown")
+        fail("PROFILE_ISOLATION_UNKNOWN", "compatibility", "The effective Agency profile mode could not be established. Select --profile or --profile-only explicitly.");
+    const session = await createSession();
+    let server;
+    let removeSignals;
+    try {
+        const context = {
+            sessionId: session.id,
+            sessionRoot: session.root,
+            cwd,
+            codexPath,
+            agencyPath,
+            profileMode,
+            options,
+        };
+        server = await SessionServer.listen(session, context);
+        const launcher = await createLauncher(session, fileURLToPath(new URL("../cli.js", import.meta.url)), process.execPath, cwd);
+        const running = startProcess(agencyPath, agencyArguments(launcher.path, options.agencyArgs), {
+            cwd,
+            env: { ...agencyEnv, ...launcher.env },
+            stdio: options.dryRun ? ["inherit", "ignore", "inherit"] : "inherit",
+        });
+        const channel = server;
+        channel.on("execution-lost", () => {
+            void running.stop();
+        });
+        removeSignals = observeSignals((signal) => {
+            if (channel.executionConnected)
+                channel.abort(signal);
+            else
+                void running.stop(signal);
+        }, Boolean(process.stdin.isTTY), () => !channel.engineStarted);
+        const agencyResult = await running.completion;
+        if (options.dryRun && isRecord(channel.plan)) {
+            const report = channel.plan;
+            let code = channel.result
+                ? exitCode(channel.result)
+                : (channel.failureExitCode ?? exitCode(agencyResult));
+            if (code === 0 && exitCode(agencyResult) !== 0) {
+                const diagnostic = {
+                    code: "AGENCY_CLEANUP_FAILED",
+                    stage: "cleanup",
+                    reason: "The plan was prepared, but Agency reported a cleanup failure.",
+                };
+                report.errors = [
+                    ...(Array.isArray(report.errors) ? report.errors : []),
+                    diagnostic,
+                ];
+                report.ready = false;
+                code = 1;
+            }
+            process.stdout.write(`${options.json ? JSON.stringify(report, null, 2) : formatPlan(report)}\n`);
+            return code;
+        }
+        if (channel.result && exitCode(channel.result) !== 0)
+            return exitCode(channel.result);
+        if (channel.failure)
+            throw new AgencyxError(channel.failure, channel.failureExitCode ?? 4);
+        if (!channel.result) {
+            if (exitCode(agencyResult) !== 0) {
+                if (options.dryRun)
+                    fail("AGENCY_PREPARATION_FAILED", "agency", "Agency failed before a launch plan could be produced.", {}, exitCode(agencyResult));
+                return exitCode(agencyResult);
+            }
+            fail("HANDOFF_NOT_EXECUTED", "handoff", "Agency did not invoke the session bridge. The hidden engine-path override may no longer be compatible.", {}, 6);
+        }
+        if (exitCode(agencyResult) !== 0)
+            fail("AGENCY_CLEANUP_FAILED", "cleanup", "Codex succeeded, but Agency reported a preparation or cleanup failure.", {}, 1);
+        return 0;
+    }
+    finally {
+        removeSignals?.();
+        let cleanupFailed = false;
+        try {
+            await server?.close();
+        }
+        catch {
+            cleanupFailed = true;
+        }
+        try {
+            await session.dispose();
+        }
+        catch {
+            cleanupFailed = true;
+        }
+        if (cleanupFailed) {
+            const diagnostic = {
+                code: "SESSION_CLEANUP_FAILED",
+                stage: "cleanup",
+                reason: "The owned session resources could not be fully removed.",
+            };
+            if (server?.result && exitCode(server.result) !== 0)
+                process.stderr.write(`${formatDiagnostic(diagnostic)}\n`);
+            else
+                throw new AgencyxError(diagnostic, 1);
+        }
+    }
+}
+//# sourceMappingURL=codex.js.map

package/dist/commands/doctor.js

@@ -0,0 +1,58 @@
+import { resolveCommand } from "../runtime/resolve-command.js";
+import { captureProcess } from "../runtime/process.js";
+import { asDiagnostic, formatDiagnostic } from "../diagnostics.js";
+import { inspectCodex } from "../codex/inspection.js";
+import { parseCodexOptions } from "../codex/options.js";
+import { engineEnvironment } from "../runtime/session.js";
+export async function doctor(json, env = process.env, cwd = process.cwd()) {
+    const errors = [];
+    const dependencies = {};
+    let capabilities;
+    for (const name of ["agency", "codex"]) {
+        try {
+            const executable = await resolveCommand(name, env[name === "agency" ? "AGENCYX_AGENCY_PATH" : "AGENCYX_CODEX_PATH"], cwd, env);
+            const result = await captureProcess(executable, ["--version"], {
+                cwd,
+                env: engineEnvironment(env),
+                timeoutMs: 5_000,
+            });
+            const version = result.stdout.match(/\b\d+\.\d+\.\d+(?:\.\d+)?(?:-[\w.]+)?/)?.[0];
+            dependencies[name] = { path: executable, version: version ?? "unknown" };
+            if (result.code !== 0)
+                errors.push({
+                    code: "DEPENDENCY_PROBE_FAILED",
+                    stage: "discovery",
+                    component: name,
+                    reason: "The executable version probe failed.",
+                });
+        }
+        catch (error) {
+            errors.push(asDiagnostic(error));
+        }
+    }
+    if (dependencies.codex) {
+        try {
+            const inspection = await inspectCodex(dependencies.codex.path, parseCodexOptions([], cwd), cwd, engineEnvironment(env));
+            capabilities = inspection.capabilities;
+        }
+        catch (error) {
+            errors.push(asDiagnostic(error));
+        }
+    }
+    const report = {
+        schemaVersion: 1,
+        ready: errors.length === 0,
+        node: process.version,
+        dependencies,
+        capabilities,
+        errors,
+        notes: [
+            "No model turn, business tool call, or plugin installation was performed.",
+            "Use codex --dry-run for Agency profile-specific component readiness.",
+            "Original Agency launcher and terminal behavior require platform-specific E2E acceptance.",
+        ],
+    };
+    process.stdout.write(`${json ? JSON.stringify(report, null, 2) : [`Doctor: ${report.ready ? "ready" : "blocked"}`, `Node: ${process.version}`, ...Object.entries(dependencies).map(([name, value]) => `${name}: ${value.version} (${value.path})`), ...errors.map(formatDiagnostic), ...report.notes].join("\n")}\n`);
+    return report.ready ? 0 : 3;
+}
+//# sourceMappingURL=doctor.js.map

package/dist/commands/passthrough.js

@@ -0,0 +1,14 @@
+import { resolveCommand } from "../runtime/resolve-command.js";
+import { exitCode, observeSignals, runInteractive, } from "../runtime/process.js";
+export async function passthrough(args, env = process.env, cwd = process.cwd()) {
+    const agency = await resolveCommand("agency", env.AGENCYX_AGENCY_PATH, cwd, env);
+    const abort = new AbortController();
+    const removeSignals = observeSignals((signal) => abort.abort(signal));
+    try {
+        return exitCode(await runInteractive(agency, args, { cwd, env, signal: abort.signal }));
+    }
+    finally {
+        removeSignals();
+    }
+}
+//# sourceMappingURL=passthrough.js.map

package/dist/diagnostics/plan.js

@@ -0,0 +1,87 @@
+import { formatDiagnostic } from "../diagnostics.js";
+import { isRecord } from "../validation.js";
+export function diagnosticPlan(plan) {
+    // Whitelist the public shape. Opaque argv, headers, env values, instructions,
+    // and RPC credentials never enter the diagnostic object.
+    return {
+        schemaVersion: 1,
+        ready: plan.errors.length === 0,
+        strategy: plan.strategy,
+        reason: plan.reason,
+        cwd: plan.cwd,
+        profileMode: plan.profileMode,
+        mcp: {
+            selected: plan.mcpNames,
+            reused: plan.reusedMcpNames,
+            disabled: plan.disabledMcpNames,
+            aliases: plan.serverAliases,
+            servers: plan.mcpNames.map((name) => {
+                const definition = plan.expectedMcps?.[name];
+                if (!isRecord(definition))
+                    return { name, state: "unresolved" };
+                const server = definition;
+                return {
+                    name,
+                    state: "planned",
+                    transport: server.command !== undefined ? "stdio" : "streamable-http",
+                    enabled: server.enabled !== false,
+                    required: server.required === true,
+                    allowedTools: server.enabled_tools ?? "all",
+                    deniedTools: server.disabled_tools ?? [],
+                    startupTimeoutSeconds: server.startup_timeout_sec ?? 10,
+                    toolTimeoutSeconds: server.tool_timeout_sec ?? 60,
+                };
+            }),
+        },
+        plugins: plan.pluginIds,
+        agentToolsPolicy: plan.agentToolsPolicy ?? "strict",
+        agents: (plan.agents ?? []).map((agent) => ({
+            name: agent.name,
+            plugin: agent.pluginName,
+            sourcePath: agent.sourcePath,
+            toolAccess: "inherited-from-codex",
+            sourceToolsApplied: false,
+            declaredTools: agent.declaredTools,
+        })),
+        sessionHooks: (plan.sessionHooks ?? []).map((hook) => ({
+            plugin: hook.pluginName,
+            sourcePath: hook.sourcePath,
+            event: "SessionStart",
+        })),
+        adaptedPlugins: (plan.skillViews ?? []).map((view) => ({
+            name: view.pluginName,
+            skills: view.skills.map((skill) => skill.name),
+            nonUserInvocableSkills: view.skills
+                .filter((skill) => skill.userInvocable === false)
+                .map((skill) => skill.name),
+        })),
+        hasAdditionalDeveloperInstructions: plan.developerInstructions !== undefined,
+        findings: plan.findings,
+        errors: plan.errors,
+        notes: [
+            "Agency preparation can read remote configuration, prepare files, or use its existing authentication.",
+            "Dry runs do not create a model turn or execute lifecycle hooks.",
+        ],
+    };
+}
+export function formatPlan(value) {
+    // This formatter consumes only our diagnosticPlan output, never raw config.
+    const plan = value;
+    return [
+        `Launch plan: ${plan.ready ? "ready" : "blocked"}`,
+        `Backend: ${plan.strategy}`,
+        `Agency profile mode: ${plan.profileMode}`,
+        `MCP servers: ${plan.mcp.selected.join(", ") || "(none)"}`,
+        `Reused MCP servers: ${plan.mcp.reused.join(", ") || "(none)"}`,
+        `Disabled MCP servers: ${plan.mcp.disabled.join(", ") || "(none)"}`,
+        `Native plugins: ${plan.plugins.join(", ") || "(none)"}`,
+        `Native agents: ${plan.agents.map((agent) => agent.name).join(", ") || "(none)"}`,
+        `Agent tool policy: ${plan.agentToolsPolicy}${plan.agentToolsPolicy === "inherit" ? " (source tools allow-lists are not applied)" : ""}`,
+        `Session hooks: ${plan.sessionHooks.length}`,
+        `Additional developer instructions: ${plan.hasAdditionalDeveloperInstructions ? "yes (body withheld)" : "no"}`,
+        ...Object.entries(plan.mcp.aliases).map(([name, alias]) => `MCP alias: ${name} -> ${alias}`),
+        ...plan.errors.map(formatDiagnostic),
+        "No model turn or lifecycle hook was started by this dry run.",
+    ].join("\n");
+}
+//# sourceMappingURL=plan.js.map

package/dist/diagnostics.js

@@ -0,0 +1,39 @@
+export class AgencyxError extends Error {
+    diagnostic;
+    exitCode;
+    constructor(diagnostic, exitCode = 4) {
+        super(diagnostic.reason);
+        this.diagnostic = diagnostic;
+        this.exitCode = exitCode;
+        this.name = "AgencyxError";
+    }
+}
+export function fail(code, stage, reason, details = {}, exitCode = 4) {
+    throw new AgencyxError({ code, stage, reason, ...details }, exitCode);
+}
+export function asDiagnostic(error) {
+    if (error instanceof AgencyxError)
+        return error.diagnostic;
+    // Raw process, parser, and transport errors can contain credentials or instructions.
+    return {
+        code: "INTERNAL_ERROR",
+        stage: "codex",
+        reason: "An unexpected error occurred. No raw process output was included in this diagnostic.",
+    };
+}
+export function errorExitCode(error) {
+    return error instanceof AgencyxError ? error.exitCode : 1;
+}
+export function formatDiagnostic(diagnostic) {
+    const details = [
+        diagnostic.component && `Component: ${diagnostic.component}`,
+        diagnostic.field && `Field: ${diagnostic.field}`,
+        diagnostic.path && `File: ${diagnostic.path}`,
+    ].filter(Boolean);
+    return [
+        `${diagnostic.code} [${diagnostic.stage}]`,
+        ...details,
+        diagnostic.reason,
+    ].join("\n");
+}
+//# sourceMappingURL=diagnostics.js.map

package/dist/model.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=model.js.map