agentxchain 2.44.0 → 2.45.0

package/README.md

@@ -24,7 +24,7 @@ Legacy IDE-window coordination is still shipped as a compatibility mode for team
 See governance before you scaffold a real repo:
 
 ```bash
-npx agentxchain demo
+npx --yes -p agentxchain@latest -c "agentxchain demo"
 ```
 
 Requires Node.js 18.17+ or 20.5+ and `git`. The demo creates a temporary governed repo, runs a full PM -> Dev -> QA lifecycle through the real runner interface, shows gates/decisions/objections, and removes the temp workspace when finished. No API keys, config edits, or manual turn authoring required.
@@ -33,12 +33,13 @@ Requires Node.js 18.17+ or 20.5+ and `git`. The demo creates a temporary governe
 
 ```bash
 npm install -g agentxchain
+agentxchain --version
 ```
 
-Or run without installing:
+For a zero-install one-off command, use the package-bound form:
 
 ```bash
-npx agentxchain init --governed --dir my-agentxchain-project -y
+npx --yes -p agentxchain@latest -c "agentxchain demo"
 ```
 
 ## Testing
@@ -62,7 +63,7 @@ Duplicate execution remains intentional for the current 36-file slice until a la
 ### Governed workflow
 
 ```bash
-npx agentxchain init --governed --dir my-agentxchain-project -y
+agentxchain init --governed --dir my-agentxchain-project -y
 cd my-agentxchain-project
 git init
 git add -A
@@ -74,13 +75,13 @@ agentxchain step --role pm
 The default governed dev runtime is `claude --print --dangerously-skip-permissions` with stdin prompt delivery. The non-interactive governed path needs write access, so do not pretend bare `claude --print` is sufficient for unattended implementation turns. If your local coding agent uses a different launch contract, set it during scaffold creation:
 
 ```bash
-npx agentxchain init --governed --dir my-agentxchain-project --dev-command ./scripts/dev-agent.sh --dev-prompt-transport dispatch_bundle_only -y
+agentxchain init --governed --dir my-agentxchain-project --dev-command ./scripts/dev-agent.sh --dev-prompt-transport dispatch_bundle_only -y
 ```
 
 If you want template-specific planning artifacts from day one:
 
 ```bash
-npx agentxchain init --governed --template api-service --dir my-agentxchain-project -y
+agentxchain init --governed --template api-service --dir my-agentxchain-project -y
 ```
 
 Built-in governed templates:
@@ -119,8 +120,8 @@ Default governed scaffolding configures QA as `api_proxy` with `ANTHROPIC_API_KE
 For initiatives spanning multiple governed repos, use the coordinator to add cross-repo sequencing and shared gates:
 
 ```bash
-npx agentxchain init --governed --template api-service --dir repos/backend -y
-npx agentxchain init --governed --template web-app --dir repos/frontend -y
+agentxchain init --governed --template api-service --dir repos/backend -y
+agentxchain init --governed --template web-app --dir repos/frontend -y
 agentxchain multi init
 agentxchain multi step --json
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentxchain",
-  "version": "2.44.0",
+  "version": "2.45.0",
   "description": "CLI for AgentXchain — governed multi-agent software delivery",
   "type": "module",
   "bin": {

package/src/lib/adapters/api-proxy-adapter.js

@@ -23,7 +23,7 @@
  *   All error returns include a `classified` ApiProxyError object with
  *   error_class, recovery instructions, and retryable flag.
  *
- * Supported providers: "anthropic", "openai", "google"
+ * Supported providers: "anthropic", "openai", "google", "ollama"
  */
 
 import { readFileSync, writeFileSync, existsSync, mkdirSync, rmSync } from 'fs';
@@ -51,6 +51,7 @@ const PROVIDER_ENDPOINTS = {
   anthropic: 'https://api.anthropic.com/v1/messages',
   openai: 'https://api.openai.com/v1/chat/completions',
   google: 'https://generativelanguage.googleapis.com/v1beta/models/{model}:generateContent',
+  ollama: 'http://localhost:11434/v1/chat/completions',
 };
 
 // Bundled cost rates per million tokens (USD).
@@ -161,6 +162,22 @@ const PROVIDER_ERROR_MAPS = {
       { provider_error_type: 'INTERNAL', http_status: 500, error_class: 'unknown_api_error', retryable: true },
     ],
   },
+  // Ollama uses OpenAI-compatible error structure
+  ollama: {
+    extractErrorType(body) {
+      return typeof body?.error?.type === 'string' ? body.error.type : null;
+    },
+    extractErrorCode(body) {
+      return typeof body?.error?.code === 'string' ? body.error.code : null;
+    },
+    mappings: [
+      { provider_error_code: 'invalid_api_key', http_status: 401, error_class: 'auth_failure', retryable: false },
+      { provider_error_code: 'model_not_found', http_status: 404, error_class: 'model_not_found', retryable: false },
+      { provider_error_type: 'invalid_request_error', http_status: 400, body_pattern: /context|token.*limit|too.many.tokens/i, error_class: 'context_overflow', retryable: false },
+      { provider_error_type: 'invalid_request_error', http_status: 400, error_class: 'invalid_request', retryable: false },
+      { provider_error_type: 'rate_limit_error', http_status: 429, error_class: 'rate_limited', retryable: true },
+    ],
+  },
 };
 
 // ── Error classification ──────────────────────────────────────────────────────
@@ -465,7 +482,7 @@ function usageFromTelemetry(provider, model, usage, config) {
   let inputTokens = 0;
   let outputTokens = 0;
 
-  if (provider === 'openai') {
+  if (provider === 'openai' || provider === 'ollama') {
     inputTokens = Number.isFinite(usage.prompt_tokens) ? usage.prompt_tokens : 0;
     outputTokens = Number.isFinite(usage.completion_tokens) ? usage.completion_tokens : 0;
   } else if (provider === 'google') {
@@ -811,9 +828,10 @@ export async function dispatchApiProxy(root, state, config, options = {}) {
   const provider = runtime.provider;
   const model = runtime.model;
   const authEnv = runtime.auth_env;
-  const apiKey = process.env[authEnv];
+  const apiKey = authEnv ? process.env[authEnv] : null;
 
-  if (!apiKey) {
+  // Auth is required for cloud providers, optional for local providers (ollama)
+  if (!apiKey && authEnv) {
     const classified = classifyError(
       'missing_credentials',
       `Environment variable "${authEnv}" is not set — required for api_proxy`,
@@ -1124,6 +1142,15 @@ function buildOpenAiRequest(promptMd, contextMd, model, maxOutputTokens) {
   };
 }
 
+function buildOllamaRequest(promptMd, contextMd, model, maxOutputTokens) {
+  const openAiCompatible = buildOpenAiRequest(promptMd, contextMd, model, maxOutputTokens);
+  return {
+    ...openAiCompatible,
+    max_tokens: maxOutputTokens,
+    max_completion_tokens: undefined,
+  };
+}
+
 function buildGoogleHeaders(_apiKey) {
   // Google Gemini uses API key as a query parameter, not a header
   return {
@@ -1203,6 +1230,14 @@ function extractGoogleTurnResult(responseData) {
   return extraction;
 }
 
+function buildOllamaHeaders(apiKey) {
+  const headers = { 'Content-Type': 'application/json' };
+  if (apiKey) {
+    headers['Authorization'] = `Bearer ${apiKey}`;
+  }
+  return headers;
+}
+
 function buildProviderHeaders(provider, apiKey) {
   if (provider === 'openai') {
     return buildOpenAiHeaders(apiKey);
@@ -1210,6 +1245,9 @@ function buildProviderHeaders(provider, apiKey) {
   if (provider === 'google') {
     return buildGoogleHeaders(apiKey);
   }
+  if (provider === 'ollama') {
+    return buildOllamaHeaders(apiKey);
+  }
   return buildAnthropicHeaders(apiKey);
 }
 
@@ -1217,6 +1255,9 @@ function buildProviderRequest(provider, promptMd, contextMd, model, maxOutputTok
   if (provider === 'openai') {
     return buildOpenAiRequest(promptMd, contextMd, model, maxOutputTokens);
   }
+  if (provider === 'ollama') {
+    return buildOllamaRequest(promptMd, contextMd, model, maxOutputTokens);
+  }
   if (provider === 'google') {
     return buildGoogleRequest(promptMd, contextMd, model, maxOutputTokens);
   }
@@ -1304,7 +1345,7 @@ function extractOpenAiTurnResult(responseData) {
 }
 
 function extractTurnResult(responseData, provider = 'anthropic') {
-  if (provider === 'openai') {
+  if (provider === 'openai' || provider === 'ollama') {
     return extractOpenAiTurnResult(responseData);
   }
   if (provider === 'google') {
@@ -1324,10 +1365,17 @@ export {
   extractTurnResult,
   buildAnthropicRequest,
   buildOpenAiRequest,
+  buildOllamaRequest,
   buildGoogleRequest,
+  buildOllamaHeaders,
+  buildProviderHeaders,
+  buildProviderRequest,
   classifyError,
   classifyHttpError,
+  DEFAULT_RETRY_POLICY,
   BUNDLED_COST_RATES,
   BUNDLED_COST_RATES as COST_RATES, // backward compat alias
   getCostRates,
+  PROVIDER_ENDPOINTS,
+  RETRYABLE_ERROR_CLASSES,
 };

package/src/lib/normalized-config.js

@@ -24,7 +24,8 @@ import {
 
 const VALID_WRITE_AUTHORITIES = ['authoritative', 'proposed', 'review_only'];
 const VALID_RUNTIME_TYPES = ['manual', 'local_cli', 'api_proxy', 'mcp', 'remote_agent'];
-const VALID_API_PROXY_PROVIDERS = ['anthropic', 'openai', 'google'];
+export const VALID_API_PROXY_PROVIDERS = ['anthropic', 'openai', 'google', 'ollama'];
+const AUTH_OPTIONAL_PROVIDERS = ['ollama'];
 export const VALID_PROMPT_TRANSPORTS = ['argv', 'stdin', 'dispatch_bundle_only'];
 const VALID_MCP_TRANSPORTS = ['stdio', 'streamable_http'];
 const DEFAULT_PHASES = ['planning', 'implementation', 'qa'];
@@ -388,7 +389,9 @@ export function validateV4Config(data, projectRoot) {
           errors.push(`Runtime "${id}": api_proxy requires "model" (e.g. "claude-sonnet-4-6")`);
         }
         if (typeof rt.auth_env !== 'string' || !rt.auth_env.trim()) {
-          errors.push(`Runtime "${id}": api_proxy requires "auth_env" (environment variable name for API key)`);
+          if (!AUTH_OPTIONAL_PROVIDERS.includes(rt.provider)) {
+            errors.push(`Runtime "${id}": api_proxy requires "auth_env" (environment variable name for API key)`);
+          }
         }
         if ('base_url' in rt) {
           if (typeof rt.base_url !== 'string' || !rt.base_url.trim()) {