@mcoda/agents 0.1.7 → 0.1.9

package/CHANGELOG.md

@@ -3,5 +3,8 @@
 ## Unreleased
 - Initial public packaging for @mcoda/agents.
 
-## 0.1.7
+## 0.1.9
+- Release v0.1.9.
+
+## 0.1.8
 - Initial release.

package/README.md

@@ -1,9 +1,36 @@
 # @mcoda/agents
 
-Agent registry and capability definitions for mcoda.
+Agent registry, adapter wiring, and invocation helpers for mcoda.
 
-## Usage
-This package is primarily an internal dependency of `mcoda`.
+## Install
+- Requires Node.js >= 20.
+- Install: `npm i @mcoda/agents`
+
+## What it provides
+- AgentService for resolving agents, prompts, capabilities, and secrets.
+- Adapter interfaces (AgentAdapter, InvocationRequest/InvocationResult).
+- Built-in adapters for OpenAI, Codex, Gemini, Ollama, Zhipu, local models, and QA.
+
+## Example
+```ts
+import { AgentService } from "@mcoda/agents";
+
+const service = await AgentService.create();
+const agent = await service.resolveAgent("codex");
+const adapter = await service.getAdapter(agent);
+const result = await adapter.invoke?.({ input: "Summarize this repo." });
+
+if (result) {
+  console.log(result.output);
+}
+
+await service.close();
+```
+
+## Notes
+- Primarily used by the mcoda CLI; APIs may evolve.
+- Set `MCODA_STREAM_IO=1` to emit adapter I/O lines to stderr.
+- If `~/.docdex/agents.md` exists, AgentService prepends it to every agent invocation.
 
 ## License
 MIT - see `LICENSE`.

package/dist/AgentService/AgentService.d.ts

@@ -18,5 +18,6 @@ export declare class AgentService {
     invoke(agentId: string, request: InvocationRequest): Promise<InvocationResult>;
     invokeStream(agentId: string, request: InvocationRequest): Promise<AsyncGenerator<InvocationResult>>;
     private applyGatewayHandoff;
+    private applyDocdexGuidance;
 }
 //# sourceMappingURL=AgentService.d.ts.map

package/dist/AgentService/AgentService.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"AgentService.d.ts","sourceRoot":"","sources":["../../src/AgentService/AgentService.ts"],"names":[],"mappings":"AACA,OAAO,EAAgB,KAAK,EAAE,iBAAiB,EAAE,WAAW,EAAE,mBAAmB,EAAE,MAAM,eAAe,CAAC;AACzG,OAAO,EAAE,gBAAgB,EAAE,MAAM,WAAW,CAAC;AAU7C,OAAO,EAAE,YAAY,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,MAAM,6BAA6B,CAAC;AAoFhG,qBAAa,YAAY;IACX,OAAO,CAAC,IAAI;gBAAJ,IAAI,EAAE,gBAAgB;WAE7B,MAAM,IAAI,OAAO,CAAC,YAAY,CAAC;IAKtC,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAItB,YAAY,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,KAAK,CAAC;IAUhD,UAAU,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,mBAAmB,GAAG,SAAS,CAAC;IAIrE,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IAInD,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,CAAC;YAIpD,kBAAkB;YAMlB,kBAAkB;IA6BhC,OAAO,CAAC,kBAAkB;IA+BpB,UAAU,CAAC,KAAK,EAAE,KAAK,GAAG,OAAO,CAAC,YAAY,CAAC;IAsC/C,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC;IAmBlD,MAAM,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,iBAAiB,GAAG,OAAO,CAAC,gBAAgB,CAAC;IAmB9E,YAAY,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,iBAAiB,GAAG,OAAO,CAAC,cAAc,CAAC,gBAAgB,CAAC,CAAC;YA0B5F,mBAAmB;CASlC"}
+{"version":3,"file":"AgentService.d.ts","sourceRoot":"","sources":["../../src/AgentService/AgentService.ts"],"names":[],"mappings":"AAGA,OAAO,EAAgB,KAAK,EAAE,iBAAiB,EAAE,WAAW,EAAE,mBAAmB,EAAE,MAAM,eAAe,CAAC;AACzG,OAAO,EAAE,gBAAgB,EAAE,MAAM,WAAW,CAAC;AAU7C,OAAO,EAAE,YAAY,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,MAAM,6BAA6B,CAAC;AAuGhG,qBAAa,YAAY;IACX,OAAO,CAAC,IAAI;gBAAJ,IAAI,EAAE,gBAAgB;WAE7B,MAAM,IAAI,OAAO,CAAC,YAAY,CAAC;IAKtC,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAItB,YAAY,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,KAAK,CAAC;IAUhD,UAAU,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,mBAAmB,GAAG,SAAS,CAAC;IAIrE,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IAInD,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,CAAC;YAIpD,kBAAkB;YAMlB,kBAAkB;IA6BhC,OAAO,CAAC,kBAAkB;IA+BpB,UAAU,CAAC,KAAK,EAAE,KAAK,GAAG,OAAO,CAAC,YAAY,CAAC;IAsC/C,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC;IAmBlD,MAAM,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,iBAAiB,GAAG,OAAO,CAAC,gBAAgB,CAAC;IAoB9E,YAAY,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,iBAAiB,GAAG,OAAO,CAAC,cAAc,CAAC,gBAAgB,CAAC,CAAC;YA2B5F,mBAAmB;YAUnB,mBAAmB;CAMlC"}

package/dist/AgentService/AgentService.js

@@ -1,4 +1,6 @@
 import { promises as fs } from "node:fs";
+import os from "node:os";
+import path from "node:path";
 import { CryptoHelper } from "@mcoda/shared";
 import { GlobalRepository } from "@mcoda/db";
 import { CodexAdapter } from "../adapters/codex/CodexAdapter.js";
@@ -32,6 +34,11 @@ const MAX_HANDOFF_CHARS = 8000;
 const IO_ENV = "MCODA_STREAM_IO";
 const IO_PROMPT_ENV = "MCODA_STREAM_IO_PROMPT";
 const IO_PREFIX = "[agent-io]";
+const DOCDEX_GUIDANCE_HEADER = "[Docdex guidance]";
+const DOCDEX_GUIDANCE_MAX_CHARS = 12000;
+const DOCDEX_GUIDANCE_PATH = path.join(os.homedir(), ".docdex", "agents.md");
+let docdexGuidanceCache;
+let docdexGuidanceLoaded = false;
 const isIoEnabled = () => {
     const raw = process.env[IO_ENV];
     if (!raw)
@@ -87,6 +94,22 @@ const readGatewayHandoff = async () => {
         return undefined;
     }
 };
+const readDocdexGuidance = async () => {
+    if (docdexGuidanceLoaded)
+        return docdexGuidanceCache;
+    docdexGuidanceLoaded = true;
+    try {
+        const content = await fs.readFile(DOCDEX_GUIDANCE_PATH, "utf8");
+        const trimmed = content.trim();
+        if (!trimmed)
+            return undefined;
+        docdexGuidanceCache = trimmed.slice(0, DOCDEX_GUIDANCE_MAX_CHARS);
+        return docdexGuidanceCache;
+    }
+    catch {
+        return undefined;
+    }
+};
 export class AgentService {
     constructor(repo) {
         this.repo = repo;
@@ -241,7 +264,8 @@ export class AgentService {
         if (!adapter.invoke) {
             throw new Error("Adapter does not support invoke");
         }
-        const enriched = await this.applyGatewayHandoff(request);
+        const withDocdex = await this.applyDocdexGuidance(request);
+        const enriched = await this.applyGatewayHandoff(withDocdex);
         const ioEnabled = isIoEnabled();
         if (ioEnabled) {
             renderIoHeader(agent, enriched, "invoke");
@@ -259,7 +283,8 @@ export class AgentService {
         if (!adapter.invokeStream) {
             throw new Error("Adapter does not support streaming");
         }
-        const enriched = await this.applyGatewayHandoff(request);
+        const withDocdex = await this.applyDocdexGuidance(request);
+        const enriched = await this.applyGatewayHandoff(withDocdex);
         const ioEnabled = isIoEnabled();
         const generator = await adapter.invokeStream(enriched);
         async function* wrap() {
@@ -288,4 +313,11 @@ export class AgentService {
         const suffix = `\n\n${HANDOFF_HEADER}\n${handoff}`;
         return { ...request, input: `${request.input ?? ""}${suffix}` };
     }
+    async applyDocdexGuidance(request) {
+        const guidance = await readDocdexGuidance();
+        if (!guidance)
+            return request;
+        const prefix = `${DOCDEX_GUIDANCE_HEADER}\n${guidance}\n\n`;
+        return { ...request, input: `${prefix}${request.input ?? ""}` };
+    }
 }

package/dist/adapters/codex/CodexCliRunner.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"CodexCliRunner.d.ts","sourceRoot":"","sources":["../../../src/adapters/codex/CodexCliRunner.ts"],"names":[],"mappings":"AAIA,eAAO,MAAM,UAAU,GAAI,sBAAoB,KAAG;IAAE,EAAE,EAAE,OAAO,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CA2BjG,CAAC;AAEF,eAAO,MAAM,YAAY,GAAI,QAAQ,MAAM,EAAE,QAAQ,MAAM,KAAG;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAyC1F,CAAC;AAEF,wBAAuB,kBAAkB,CACvC,MAAM,EAAE,MAAM,EACd,KAAK,CAAC,EAAE,MAAM,GACb,cAAc,CAAC;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,EAAE,IAAI,EAAE,OAAO,CAAC,CA0EhE"}
+{"version":3,"file":"CodexCliRunner.d.ts","sourceRoot":"","sources":["../../../src/adapters/codex/CodexCliRunner.ts"],"names":[],"mappings":"AA0BA,eAAO,MAAM,UAAU,GAAI,sBAAoB,KAAG;IAAE,EAAE,EAAE,OAAO,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CA2BjG,CAAC;AAEF,eAAO,MAAM,YAAY,GAAI,QAAQ,MAAM,EAAE,QAAQ,MAAM,KAAG;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CA8C1F,CAAC;AAEF,wBAAuB,kBAAkB,CACvC,MAAM,EAAE,MAAM,EACd,KAAK,CAAC,EAAE,MAAM,GACb,cAAc,CAAC;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,EAAE,IAAI,EAAE,OAAO,CAAC,CA+EhE"}

package/dist/adapters/codex/CodexCliRunner.js

@@ -1,5 +1,30 @@
 import { spawn, spawnSync } from "node:child_process";
 const CODEX_MAX_BUFFER_BYTES = 10 * 1024 * 1024;
+const CODEX_REASONING_ENV = "MCODA_CODEX_REASONING_EFFORT";
+const CODEX_REASONING_ENV_FALLBACK = "CODEX_REASONING_EFFORT";
+const normalizeReasoningEffort = (raw) => {
+    if (!raw)
+        return undefined;
+    const normalized = raw.trim().toLowerCase();
+    if (!normalized)
+        return undefined;
+    if (!["low", "medium", "high", "xhigh"].includes(normalized))
+        return undefined;
+    return normalized;
+};
+const resolveReasoningEffort = (model) => {
+    const configured = normalizeReasoningEffort(process.env[CODEX_REASONING_ENV] ?? process.env[CODEX_REASONING_ENV_FALLBACK]);
+    const normalizedModel = (model ?? "").toLowerCase();
+    const isGpt51 = normalizedModel.includes("gpt-5.1");
+    if (configured) {
+        if (configured === "xhigh" && isGpt51)
+            return "high";
+        return configured;
+    }
+    if (isGpt51)
+        return "high";
+    return undefined;
+};
 export const cliHealthy = (throwOnError = false) => {
     if (process.env.MCODA_CLI_STUB === "1") {
         return { ok: true, details: { stub: true } };
@@ -35,7 +60,12 @@ export const runCodexExec = (prompt, model) => {
         return { output, raw };
     }
     const health = cliHealthy(true);
-    const args = ["exec", "--model", model ?? "gpt-5.1-codex-max", "--full-auto", "--json"];
+    const resolvedModel = model ?? "gpt-5.1-codex-max";
+    const args = ["exec", "--model", resolvedModel, "--full-auto", "--json"];
+    const reasoningEffort = resolveReasoningEffort(resolvedModel);
+    if (reasoningEffort) {
+        args.push("-c", `model_reasoning_effort=${reasoningEffort}`);
+    }
     const result = spawnSync("codex", args, {
         input: prompt,
         encoding: "utf8",
@@ -78,7 +108,12 @@ export async function* runCodexExecStream(prompt, model) {
         return;
     }
     cliHealthy(true);
-    const args = ["exec", "--model", model ?? "gpt-5.1-codex-max", "--full-auto", "--json"];
+    const resolvedModel = model ?? "gpt-5.1-codex-max";
+    const args = ["exec", "--model", resolvedModel, "--full-auto", "--json"];
+    const reasoningEffort = resolveReasoningEffort(resolvedModel);
+    if (reasoningEffort) {
+        args.push("-c", `model_reasoning_effort=${reasoningEffort}`);
+    }
     const child = spawn("codex", args, { stdio: ["pipe", "pipe", "pipe"] });
     child.stdin.write(prompt);
     child.stdin.end();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mcoda/agents",
-  "version": "0.1.7",
+  "version": "0.1.9",
   "description": "Agent registry and capabilities for mcoda.",
   "type": "module",
   "main": "dist/index.js",
@@ -30,8 +30,8 @@
     "access": "public"
   },
   "dependencies": {
-    "@mcoda/shared": "0.1.7",
-    "@mcoda/db": "0.1.7"
+    "@mcoda/shared": "0.1.9",
+    "@mcoda/db": "0.1.9"
   },
   "scripts": {
     "build": "tsc -p tsconfig.json",