mcoda 0.1.8 → 0.1.11

package/CHANGELOG.md

@@ -3,5 +3,8 @@
 ## Unreleased
 - Initial npm packaging scaffold for the mcoda CLI.
 
+## 0.1.9
+- Release v0.1.9.
+
 ## 0.1.8
 - Initial public release of the mcoda CLI.

package/README.md

@@ -13,10 +13,16 @@ mcoda set-workspace --workspace-root .
 mcoda docs pdr generate --workspace-root . --project WEB --rfp-path docs/rfp/web.md --agent codex
 ```
 
+## Docdex & QA
+- mcoda depends on the `docdex` CLI for doc search and context stitching.
+- Run `docdex setup` (or `docdexd browser install`) to install the headless Chromium browser used for web enrichment.
+- Docdex stores state under `~/.docdex`; mcoda does not create repo-local `.docdex` folders.
+- If `~/.docdex/agents.md` exists, it is prepended to every agent run.
+
 ## Workspace layout
-- `.mcoda/config.json` for defaults (docdex URL, branch metadata, telemetry preferences).
-- `.mcoda/mcoda.db` for backlog, jobs, and telemetry.
-- `.mcoda/docs/` for generated artifacts.
+- `~/.mcoda/workspaces/<fingerprint>/config.json` for defaults (docdex URL, branch metadata, telemetry preferences).
+- `~/.mcoda/workspaces/<fingerprint>/mcoda.db` for backlog, jobs, and telemetry.
+- `~/.mcoda/workspaces/<fingerprint>/docs/` for generated artifacts.
 
 ## Common commands
 - Docs: `mcoda docs pdr generate`, `mcoda docs sds generate`
@@ -25,6 +31,7 @@ mcoda docs pdr generate --workspace-root . --project WEB --rfp-path docs/rfp/web
 - Execution: `mcoda work-on-tasks`, `mcoda code-review`, `mcoda qa-tasks`
 - Backlog: `mcoda backlog`, `mcoda task`
 - Jobs/telemetry: `mcoda jobs`, `mcoda tokens`, `mcoda telemetry`
+- Agents: `mcoda test-agent`, `mcoda agent-run`
 - Updates: `mcoda update --check`
 
 ## Configuration

package/dist/bin/McodaEntrypoint.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"McodaEntrypoint.d.ts","sourceRoot":"","sources":["../../src/bin/McodaEntrypoint.ts"],"names":[],"mappings":";AAyBA,qBAAa,eAAe;WACb,GAAG,CAAC,IAAI,GAAE,MAAM,EAA0B,GAAG,OAAO,CAAC,IAAI,CAAC;CAoIxE"}
+{"version":3,"file":"McodaEntrypoint.d.ts","sourceRoot":"","sources":["../../src/bin/McodaEntrypoint.ts"],"names":[],"mappings":";AA2BA,qBAAa,eAAe;WACb,GAAG,CAAC,IAAI,GAAE,MAAM,EAA0B,GAAG,OAAO,CAAC,IAAI,CAAC;CAkLxE"}

package/dist/bin/McodaEntrypoint.js

@@ -15,23 +15,62 @@ import { OrderTasksCommand } from "../commands/backlog/OrderTasksCommand.js";
 import { EstimateCommands } from "../commands/estimate/EstimateCommands.js";
 import { TelemetryCommands } from "../commands/telemetry/TelemetryCommands.js";
 import { WorkOnTasksCommand } from "../commands/work/WorkOnTasksCommand.js";
+import { GatewayTrioCommand } from "../commands/work/GatewayTrioCommand.js";
 import { CodeReviewCommand } from "../commands/review/CodeReviewCommand.js";
 import { QaTasksCommand } from "../commands/planning/QaTasksCommand.js";
 import { MigrateTasksCommand } from "../commands/planning/MigrateTasksCommand.js";
 import { UpdateCommands } from "../commands/update/UpdateCommands.js";
 import { RoutingCommands } from "../commands/routing/RoutingCommands.js";
 import { TestAgentCommand } from "../commands/agents/TestAgentCommand.js";
+import { AgentRunCommand } from "../commands/agents/AgentRunCommand.js";
 import { SetWorkspaceCommand } from "../commands/workspace/SetWorkspaceCommand.js";
 export class McodaEntrypoint {
     static async run(argv = process.argv.slice(2)) {
-        const [command, ...rest] = argv;
+        const applyCodexNoSandboxFlag = (value) => {
+            if (value === undefined || value === "") {
+                process.env.MCODA_CODEX_NO_SANDBOX = "1";
+                return;
+            }
+            const normalized = value.trim().toLowerCase();
+            if (["0", "false", "off", "no"].includes(normalized)) {
+                process.env.MCODA_CODEX_NO_SANDBOX = "0";
+                return;
+            }
+            process.env.MCODA_CODEX_NO_SANDBOX = "1";
+        };
+        const filteredArgs = [];
+        for (let i = 0; i < argv.length; i += 1) {
+            const arg = argv[i];
+            if (arg === "--codex-no-sandbox") {
+                const next = argv[i + 1];
+                if (next && !next.startsWith("--")) {
+                    applyCodexNoSandboxFlag(next);
+                    i += 1;
+                }
+                else {
+                    applyCodexNoSandboxFlag(undefined);
+                }
+                continue;
+            }
+            if (arg.startsWith("--codex-no-sandbox=")) {
+                const [, raw] = arg.split("=", 2);
+                applyCodexNoSandboxFlag(raw);
+                continue;
+            }
+            filteredArgs.push(arg);
+        }
+        const [command, ...rest] = filteredArgs;
         const wantsJson = argv.some((arg) => arg === "--json" || arg.startsWith("--json="));
         const wantsQuiet = argv.some((arg) => arg === "--quiet" || arg.startsWith("--quiet="));
         if (wantsJson || wantsQuiet) {
             process.env.MCODA_STREAM_IO = "0";
+            process.env.MCODA_STREAM_IO_PROMPT = "0";
         }
         else if (process.env.MCODA_STREAM_IO === undefined) {
-            process.env.MCODA_STREAM_IO = "1";
+            process.env.MCODA_STREAM_IO = "0";
+            if (process.env.MCODA_STREAM_IO_PROMPT === undefined) {
+                process.env.MCODA_STREAM_IO_PROMPT = "0";
+            }
         }
         if (command === "--version" || command === "-v" || command === "version") {
             // Keep this simple so `mcoda --version` works even in thin installs.
@@ -40,7 +79,7 @@ export class McodaEntrypoint {
             return;
         }
         if (!command) {
-            throw new Error("Usage: mcoda <agent|gateway-agent|routing|docs|openapi|job|jobs|tokens|telemetry|create-tasks|migrate-tasks|refine-tasks|order-tasks|tasks|work-on-tasks|code-review|qa-tasks|backlog|task|task-detail|estimate|update|set-workspace|pdr|sds> [...args]\n" +
+            throw new Error("Usage: mcoda <agent|gateway-agent|test-agent|agent-run|routing|docs|openapi|job|jobs|tokens|telemetry|create-tasks|migrate-tasks|refine-tasks|order-tasks|tasks|work-on-tasks|gateway-trio|code-review|qa-tasks|backlog|task|task-detail|estimate|update|set-workspace|pdr|sds> [...args]\n" +
                 "Routing: use `mcoda routing defaults` to view/update workspace/global defaults, `mcoda routing preview|explain` to inspect agent selection/provenance (override → workspace_default → global_default).\n" +
                 "Aliases: `tasks order-by-deps` forwards to `order-tasks` (dependency-aware ordering), `task`/`task-detail` show a single task.\n" +
                 "Job commands (mcoda job --help for details): list|status|watch|logs|inspect|resume|cancel|tokens\n" +
@@ -58,6 +97,10 @@ export class McodaEntrypoint {
             await TestAgentCommand.run(rest);
             return;
         }
+        if (command === "agent-run") {
+            await AgentRunCommand.run(rest);
+            return;
+        }
         if (command === "routing") {
             await RoutingCommands.run(rest);
             return;
@@ -105,7 +148,7 @@ export class McodaEntrypoint {
         if (command === "qa-tasks") {
             if (rest.includes("--help") || rest.includes("-h")) {
                 // eslint-disable-next-line no-console
-                console.log("Usage: mcoda qa-tasks [--workspace-root <path>] --project <PROJECT_KEY> [--task <TASK_KEY> ... | --epic <EPIC_KEY> | --story <STORY_KEY>] [--status <STATUS_FILTER>] [--mode auto|manual] [--profile <PROFILE_NAME>] [--level unit|integration|acceptance] [--test-command \"<CMD>\"] [--agent <NAME>] [--agent-stream true|false] [--resume <JOB_ID>] [--create-followup-tasks auto|none|prompt] [--result pass|fail|blocked] [--notes \"<text>\"] [--evidence-url \"<url>\"] [--dry-run] [--json]");
+                console.log("Usage: mcoda qa-tasks [--workspace-root <path>] --project <PROJECT_KEY> [--task <TASK_KEY> ... | --epic <EPIC_KEY> | --story <STORY_KEY>] [--status <STATUS_FILTER>] [--limit N] [--mode auto|manual] [--profile <PROFILE_NAME>] [--level unit|integration|acceptance] [--test-command \"<CMD>\"] [--agent <NAME>] [--agent-stream true|false] [--resume <JOB_ID>] [--create-followup-tasks auto|none|prompt] [--result pass|fail] [--notes \"<text>\"] [--evidence-url \"<url>\"] [--dry-run] [--json]");
                 return;
             }
             await QaTasksCommand.run(rest);
@@ -126,6 +169,10 @@ export class McodaEntrypoint {
             await WorkOnTasksCommand.run(rest);
             return;
         }
+        if (command === "gateway-trio") {
+            await GatewayTrioCommand.run(rest);
+            return;
+        }
         if (command === "code-review") {
             await CodeReviewCommand.run(rest);
             return;

package/dist/commands/agents/AgentRunCommand.d.ts

@@ -0,0 +1,4 @@
+export declare class AgentRunCommand {
+    static run(argv: string[]): Promise<void>;
+}
+//# sourceMappingURL=AgentRunCommand.d.ts.map

package/dist/commands/agents/AgentRunCommand.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"AgentRunCommand.d.ts","sourceRoot":"","sources":["../../../src/commands/agents/AgentRunCommand.ts"],"names":[],"mappings":"AAyDA,qBAAa,eAAe;WACb,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;CAsFhD"}

package/dist/commands/agents/AgentRunCommand.js

@@ -0,0 +1,140 @@
+import fs from "node:fs/promises";
+import { AgentsApi } from "@mcoda/core";
+const USAGE = "Usage: mcoda agent-run <NAME> [--prompt \"<text>\"] [--prompt-file <PATH>] [--task-file <PATH>] [--stdin] [--json]";
+const parseArgs = (argv) => {
+    const flags = {};
+    const positionals = [];
+    for (let i = 0; i < argv.length; i += 1) {
+        const arg = argv[i];
+        if (arg.startsWith("--")) {
+            const key = arg.replace(/^--/, "");
+            const next = argv[i + 1];
+            if (next && !next.startsWith("--")) {
+                const existing = flags[key];
+                if (Array.isArray(existing)) {
+                    flags[key] = [...existing, next];
+                }
+                else if (typeof existing === "string") {
+                    flags[key] = [existing, next];
+                }
+                else {
+                    flags[key] = next;
+                }
+                i += 1;
+            }
+            else {
+                flags[key] = true;
+            }
+        }
+        else {
+            positionals.push(arg);
+        }
+    }
+    return { flags, positionals };
+};
+const readTaskFile = async (filePath) => {
+    const raw = await fs.readFile(filePath, "utf8");
+    return raw
+        .split(/\r?\n/)
+        .map((line) => line.trim())
+        .filter((line) => line.length > 0 && !line.startsWith("#"));
+};
+const toArray = (value) => {
+    if (!value || typeof value === "boolean")
+        return [];
+    return Array.isArray(value) ? value : [value];
+};
+const readStdinIfProvided = async () => {
+    if (process.stdin.isTTY)
+        return undefined;
+    const chunks = [];
+    for await (const chunk of process.stdin) {
+        chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+    }
+    const input = Buffer.concat(chunks).toString("utf8").trim();
+    return input.length ? input : undefined;
+};
+export class AgentRunCommand {
+    static async run(argv) {
+        const parsed = parseArgs(argv);
+        const name = parsed.positionals[0];
+        if (!name || parsed.flags.help) {
+            throw new Error(USAGE);
+        }
+        if (parsed.flags.prompt === true) {
+            throw new Error("agent-run: missing value for --prompt");
+        }
+        if (parsed.flags["prompt-file"] === true) {
+            throw new Error("agent-run: missing value for --prompt-file");
+        }
+        if (parsed.flags["task-file"] === true) {
+            throw new Error("agent-run: missing value for --task-file");
+        }
+        const prompts = [];
+        const inlinePrompts = toArray(parsed.flags.prompt);
+        for (const prompt of inlinePrompts) {
+            const trimmed = prompt.trim();
+            if (trimmed)
+                prompts.push(trimmed);
+        }
+        const promptFiles = toArray(parsed.flags["prompt-file"]);
+        for (const filePath of promptFiles) {
+            const content = await fs.readFile(String(filePath), "utf8");
+            const trimmed = content.trim();
+            if (trimmed)
+                prompts.push(trimmed);
+        }
+        const taskFiles = toArray(parsed.flags["task-file"]);
+        for (const filePath of taskFiles) {
+            const entries = await readTaskFile(String(filePath));
+            for (const entry of entries) {
+                if (entry)
+                    prompts.push(entry);
+            }
+        }
+        if (parsed.flags.stdin) {
+            const stdinPrompt = await readStdinIfProvided();
+            if (stdinPrompt)
+                prompts.push(stdinPrompt);
+        }
+        else if (prompts.length === 0) {
+            const stdinPrompt = await readStdinIfProvided();
+            if (stdinPrompt)
+                prompts.push(stdinPrompt);
+        }
+        if (prompts.length === 0) {
+            throw new Error("agent-run: at least one prompt is required via --prompt, --prompt-file, --task-file, or stdin");
+        }
+        const api = await AgentsApi.create();
+        try {
+            const result = await api.runAgent(name, prompts);
+            if (parsed.flags.json) {
+                // eslint-disable-next-line no-console
+                console.log(JSON.stringify({
+                    agent: result.agent,
+                    responses: result.responses.map((response, index) => ({
+                        prompt: result.prompts[index],
+                        output: response.output,
+                        adapter: response.adapter,
+                        model: response.model,
+                        metadata: response.metadata,
+                    })),
+                }, null, 2));
+            }
+            else {
+                // eslint-disable-next-line no-console
+                console.log(`Agent ${result.agent.slug} responded to ${result.responses.length} prompt(s).`);
+                result.responses.forEach((response, index) => {
+                    const label = `${response.adapter}${response.model ? `:${response.model}` : ""}`;
+                    // eslint-disable-next-line no-console
+                    console.log(`\n--- Prompt ${index + 1} ---\n${result.prompts[index]}`);
+                    // eslint-disable-next-line no-console
+                    console.log(`--- Response ${index + 1} (${label}) ---\n${response.output}`);
+                });
+            }
+        }
+        finally {
+            await api.close();
+        }
+    }
+}

package/dist/commands/agents/AgentsCommands.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"AgentsCommands.d.ts","sourceRoot":"","sources":["../../../src/commands/agents/AgentsCommands.ts"],"names":[],"mappings":"AAoMA,qBAAa,cAAc;WACZ,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;CAgLhD"}
+{"version":3,"file":"AgentsCommands.d.ts","sourceRoot":"","sources":["../../../src/commands/agents/AgentsCommands.ts"],"names":[],"mappings":"AA2TA,qBAAa,cAAc;WACZ,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;CAuThD"}