maqam 0.1.2 → 0.1.4

package/README.md

@@ -2,20 +2,24 @@
 
 ![Maqam governed agent framework hero](app/assets/maqam-readme-hero.png)
 
-Maqam is an MIT-licensed Ajnas agent framework for governed workflows. It combines a local agent runtime, policy engine, evidence ledger, skill registry, tool gateway, human-review-ready approval errors, and a crawler-backed research workflow.
+Maqam is an MIT-licensed Ajnas agent framework for governed workflows. It combines a local agent runtime, policy engine, evidence ledger, skill registry, tool gateway, generic agent adapter, human-review-ready approval errors, and a crawler-backed research workflow.
 
-The crawler is no longer the product center; it is the first governed connector. Maqam is meant for enterprise agent workflows that need inspectable runs, source-backed outputs, compliance-friendly defaults, and no required hosted service.
+The crawler is not the product center; it is only the first built-in connector. Maqam can govern any agent or tool you register through `ToolGateway`, including function agents, object agents with `run`/`invoke`/`call`, browser agents, research agents, internal SaaS connectors, and write-action agents that need human approval.
 
 Full documentation: [docs/usage.md](https://github.com/AjnasNB/maqam/blob/main/docs/usage.md)
 
 ![Maqam system map](app/assets/maqam-system-map.svg)
 
+![Maqam governed CLI worker flow](app/assets/maqam-cli-agent-flow.png)
+
 ## What Ships
 
 - `AgentRuntime`: sequential workflow execution with retries, trace events, task outputs, and policy preflight.
 - `PolicyEngine`: deterministic goal and tool-call decisions for allowed tools, origins, limits, and approval gates.
 - `EvidenceLedger`: provenance records, claim links, source hashes, confidence, and unsupported-claim checks.
 - `ToolGateway`: one governed path for external tool execution.
+- `createAgentTool`: wraps any function agent or object agent so Maqam can control it through policy, trace, approval, and evidence.
+- `createCliAgentTool`: wraps fixed command-line workers with timeout, approximate input-token limits, output byte limits, and no shell execution by default.
 - `SkillRegistry`: lightweight skill metadata registration and selection.
 - `createResearchWorkflow`: crawler-backed source collection, synthesis, and quality checks.
 - `maqam`: local web console for running governed research workflows.
@@ -80,18 +84,32 @@ import {
   EvidenceLedger,
   PolicyEngine,
   ToolGateway,
+  createAgentTool,
+  createCliAgentTool,
   createCrawlerTool,
   createResearchWorkflow
 } from "maqam";
 
 const evidenceLedger = new EvidenceLedger();
 const policyEngine = new PolicyEngine({
-  allowedTools: ["crawler"],
+  allowedTools: ["crawler", "summarizer"],
   allowedOrigins: ["https://github.com", "https://www.npmjs.com"]
 });
 
 const gateway = new ToolGateway({ policyEngine, evidenceLedger });
 gateway.registerTool("crawler", createCrawlerTool());
+gateway.registerTool("summarizer", createAgentTool(async (input) => ({
+  summary: `Reviewed ${input.topic}`
+}), { name: "summarizer" }));
+gateway.registerTool("localWorker", createCliAgentTool({
+  name: "localWorker",
+  command: process.execPath,
+  args: ["--version"],
+  stdin: "none",
+  timeoutMs: 5000,
+  maxInputTokens: 20,
+  maxOutputBytes: 2048
+}));
 
 const runtime = new AgentRuntime({ policyEngine, evidenceLedger, toolGateway: gateway });
 const result = await runtime.runWorkflow(
@@ -101,7 +119,7 @@ const result = await runtime.runWorkflow(
   }),
   {
     objective: "Research permissive OSS agent framework projects",
-    allowedTools: ["crawler"],
+    allowedTools: ["crawler", "summarizer"],
     allowedOrigins: ["https://github.com"]
   }
 );
@@ -149,7 +167,7 @@ Brand assets live in `app/assets/`, including `maqam-logo.svg` and `maqam-brand-
 - Use a clear user agent.
 - Rate-limit per origin.
 - Avoid bypassing access controls, paywalls, anti-bot systems, or private content.
-- No required AI provider dependency.
+- No required model provider dependency.
 - No required external hosted service.
 - Produce JSON/JSONL output that agents can consume directly.
 
@@ -176,3 +194,7 @@ Publishing requires an authenticated npm session with permission to publish the
 ## License
 
 MIT
+
+## Open Development
+
+Maqam is open source under MIT and open for development, issues, ideas, and contributions.

package/docs/usage.md

@@ -1,6 +1,6 @@
 # Maqam Usage Guide
 
-Maqam is an MIT-licensed Ajnas agent framework for governed workflows. It gives you a small local runtime for building agent systems that can be inspected, policy-checked, and connected to evidence.
+Maqam is an MIT-licensed Ajnas agent framework for governed workflows. It gives you a small local runtime for building agent systems that can be inspected, policy-checked, and connected to evidence. The crawler is only one built-in connector; Maqam can also govern arbitrary agents and tools through `createAgentTool` and `ToolGateway`.
 
 This guide covers installation, CLI usage, SDK usage, the local console, crawler usage, API reference, common patterns, and troubleshooting.
 
@@ -14,6 +14,8 @@ This guide covers installation, CLI usage, SDK usage, the local console, crawler
 - [Architecture](#architecture)
 - [API Reference](#api-reference)
 - [Build A Custom Workflow](#build-a-custom-workflow)
+- [Control Any Agent](#control-any-agent)
+- [Control CLI Workers](#control-cli-workers)
 - [Register A Custom Tool](#register-a-custom-tool)
 - [Use Policy And Approvals](#use-policy-and-approvals)
 - [Use Evidence And Claims](#use-evidence-and-claims)
@@ -77,18 +79,32 @@ import {
   EvidenceLedger,
   PolicyEngine,
   ToolGateway,
+  createAgentTool,
+  createCliAgentTool,
   createCrawlerTool,
   createResearchWorkflow
 } from "maqam";
 
 const evidenceLedger = new EvidenceLedger();
 const policyEngine = new PolicyEngine({
-  allowedTools: ["crawler"],
+  allowedTools: ["crawler", "summarizer"],
   allowedOrigins: ["https://github.com"]
 });
 
 const toolGateway = new ToolGateway({ policyEngine, evidenceLedger });
 toolGateway.registerTool("crawler", createCrawlerTool());
+toolGateway.registerTool("summarizer", createAgentTool(async (input) => ({
+  summary: `Reviewed ${input.topic}`
+}), { name: "summarizer" }));
+toolGateway.registerTool("localWorker", createCliAgentTool({
+  name: "localWorker",
+  command: process.execPath,
+  args: ["--version"],
+  stdin: "none",
+  timeoutMs: 5000,
+  maxInputTokens: 20,
+  maxOutputBytes: 2048
+}));
 
 const runtime = new AgentRuntime({ policyEngine, evidenceLedger, toolGateway });
 const result = await runtime.runWorkflow(
@@ -98,7 +114,7 @@ const result = await runtime.runWorkflow(
   }),
   {
     objective: "Research Maqam from public sources",
-    allowedTools: ["crawler"],
+    allowedTools: ["crawler", "summarizer"],
     allowedOrigins: ["https://github.com"],
     budget: { maxToolCalls: 20, maxRuntimeMs: 120_000 }
   }
@@ -210,6 +226,8 @@ import {
   PolicyEngine,
   ToolGateway,
   SkillRegistry,
+  createAgentTool,
+  createCliAgentTool,
   createCrawlerTool,
   createResearchWorkflow,
   crawl,
@@ -245,6 +263,8 @@ Core objects:
 - `AgentRuntime`: owns workflow execution.
 - `PolicyEngine`: decides what is allowed, denied, or approval-gated.
 - `ToolGateway`: routes all external tool calls through policy.
+- `createAgentTool`: wraps arbitrary agents so they can be governed like any other tool.
+- `createCliAgentTool`: wraps fixed command-line workers with timeout, approximate input-token limits, output byte limits, and no shell execution by default.
 - `EvidenceLedger`: stores source evidence and claim support.
 - `SkillRegistry`: stores skill metadata and selects matching skills.
 - `createResearchWorkflow`: bundled workflow for public web research.
@@ -560,6 +580,69 @@ await toolGateway.call("crawler", {
 });
 ```
 
+### `createAgentTool(agent, options)`
+
+Wraps an arbitrary agent so it can be controlled by Maqam policy and executed through `ToolGateway`.
+
+Supported agent shapes:
+
+- Function agent: `async (input, context) => output`
+- Object agent with `run(input, context)`
+- Object agent with `invoke(input, context)`
+- Object agent with `call(input, context)`
+
+```js
+const summarizer = createAgentTool(async (input, context) => {
+  return {
+    summary: `Reviewed ${input.topic}`,
+    evidence: [
+      {
+        evidenceId: "ev_agent_1",
+        sourceType: "agent_output",
+        source: "summarizer",
+        excerpt: "The agent reviewed policy and evidence controls.",
+        confidence: 0.8
+      }
+    ],
+    claims: [
+      {
+        text: "The summarizer reviewed policy and evidence controls.",
+        evidenceIds: ["ev_agent_1"],
+        confidence: 0.8
+      }
+    ]
+  };
+}, { name: "summarizer" });
+
+toolGateway.registerTool("summarizer", summarizer);
+
+const result = await toolGateway.call("summarizer", {
+  topic: "Maqam"
+}, {
+  runId: "run_1",
+  taskId: "summarize"
+});
+```
+
+If the agent output includes `evidence` or `claims` arrays, Maqam records them into the active `EvidenceLedger`.
+
+Object-agent example:
+
+```js
+const browserAgent = {
+  async run(input) {
+    return {
+      url: input.url,
+      result: "Browser task completed"
+    };
+  }
+};
+
+toolGateway.registerTool("browserAgent", createAgentTool(browserAgent, {
+  name: "browserAgent"
+}));
+```
+
 ### `createResearchWorkflow(options)`
 
 Creates the bundled public research workflow.
@@ -573,6 +656,93 @@ const workflow = createResearchWorkflow({
 });
 ```
 
+### `createCliAgentTool(options)`
+
+Wraps a fixed command-line worker so it can run through Maqam policy and trace capture.
+
+```js
+const localWorker = createCliAgentTool({
+  name: "localWorker",
+  command: process.execPath,
+  args: ["--input-type=module", "-e", "let body=''; for await (const c of process.stdin) body += c; const input = JSON.parse(body); console.log(JSON.stringify({ artifact: `built:${input.name}` }));"],
+  stdin: "json",
+  parseJson: true,
+  timeoutMs: 5000,
+  maxInputTokens: 50,
+  maxOutputBytes: 2048
+});
+
+toolGateway.registerTool("localWorker", localWorker);
+
+const result = await toolGateway.call("localWorker", {
+  name: "demo-widget"
+});
+
+console.log(result.json.artifact);
+```
+
+Options:
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `name` | `string` | Name used in result metadata. |
+| `command` | `string` | Fixed executable path or command. Required. |
+| `args` | `string[]` | Fixed argument list. Dynamic user input should go through stdin, not command args. |
+| `cwd` | `string` | Optional working directory. |
+| `env` | `object` | Extra environment variables. |
+| `inheritEnv` | `boolean` | Inherit `process.env`. Default: `true`. |
+| `stdin` | `"json" | "text" | "none"` | How input is passed to the worker. Default: `"json"`. |
+| `parseJson` | `boolean` | Parse stdout as JSON and expose it as `result.json`. |
+| `timeoutMs` | `number` | Hard runtime timeout. Default: `30000`. |
+| `maxInputTokens` | `number` | Approximate input token limit. Default: `4000`. |
+| `maxOutputBytes` | `number` | Maximum combined stdout/stderr bytes. Default: `65536`. |
+| `rejectOnNonZero` | `boolean` | Reject when exit code is not zero. Default: `true`. |
+| `shell` | `boolean` | Run through a shell. Default: `false`. Use only when a platform wrapper requires it. |
+
+Result shape:
+
+```json
+{
+  "name": "localWorker",
+  "command": "node",
+  "args": ["--version"],
+  "exitCode": 0,
+  "signal": null,
+  "timedOut": false,
+  "stdout": "v20.0.0\n",
+  "stderr": "",
+  "durationMs": 42,
+  "approxInputTokens": 0,
+  "outputBytes": 9,
+  "limits": {
+    "maxInputTokens": 50,
+    "maxOutputBytes": 2048,
+    "timeoutMs": 5000
+  }
+}
+```
+
+Limit errors:
+
+| Code | Meaning |
+| --- | --- |
+| `CLI_INPUT_LIMIT_EXCEEDED` | Input was too large before execution. |
+| `CLI_OUTPUT_LIMIT_EXCEEDED` | stdout/stderr exceeded the configured byte limit. |
+| `CLI_TIMEOUT` | Process exceeded `timeoutMs`. |
+| `CLI_EXIT_NONZERO` | Process exited with a non-zero code. |
+| `CLI_JSON_PARSE_FAILED` | `parseJson` was enabled but stdout was not valid JSON. |
+| `CLI_SPAWN_FAILED` | The process could not be started. |
+
+Security notes:
+
+- Maqam does not use a shell for CLI workers by default.
+- Keep `command` and `args` fixed in code.
+- Send user input through stdin.
+- Use narrow `allowedTools`.
+- Set short `timeoutMs` and small `maxOutputBytes` for untrusted workers.
+- Use approval gates for workers that write, publish, send, or modify state.
+- Prefer direct executable paths over platform wrapper scripts. On Windows, some `.cmd` or `.ps1` shims may require `shell: true` or a direct underlying executable path.
+
 Tasks:
 
 | Task ID | Purpose |
@@ -741,6 +911,187 @@ console.log(result.outputs.record_summary);
 console.log(result.evidence.unsupportedClaims);
 ```
 
+## Control Any Agent
+
+Yes, Maqam can control agents beyond crawling. The pattern is:
+
+1. Wrap the agent with `createAgentTool`.
+2. Register it in `ToolGateway`.
+3. Put the agent name in `PolicyEngine.allowedTools`.
+4. Add it to `approvalRequiredTools` if it can write, publish, send, modify, or spend.
+5. Call it from an `AgentRuntime` workflow task.
+
+Example with multiple agents:
+
+```js
+import {
+  AgentRuntime,
+  EvidenceLedger,
+  PolicyEngine,
+  ToolGateway,
+  createAgentTool
+} from "maqam";
+
+const evidenceLedger = new EvidenceLedger();
+const policyEngine = new PolicyEngine({
+  allowedTools: ["researchAgent", "reviewAgent", "publishAgent"],
+  approvalRequiredTools: ["publishAgent"]
+});
+const toolGateway = new ToolGateway({ policyEngine, evidenceLedger });
+
+toolGateway.registerTool("researchAgent", createAgentTool(async (input) => ({
+  notes: `Researched ${input.topic}`,
+  evidence: [
+    {
+      evidenceId: "ev_research_1",
+      sourceType: "agent_output",
+      source: "researchAgent",
+      excerpt: `Researched ${input.topic}`,
+      confidence: 0.7
+    }
+  ]
+}), { name: "researchAgent" }));
+
+toolGateway.registerTool("reviewAgent", createAgentTool({
+  async run(input) {
+    return { approvedForDraft: Boolean(input.notes) };
+  }
+}, { name: "reviewAgent" }));
+
+toolGateway.registerTool("publishAgent", createAgentTool(async () => ({
+  published: true
+}), { name: "publishAgent" }));
+
+const workflow = {
+  name: "multi_agent_governed_flow",
+  tasks: [
+    {
+      id: "research",
+      run: (context) => context.tools.call("researchAgent", { topic: "Maqam" }, context)
+    },
+    {
+      id: "review",
+      run: (context) => context.tools.call("reviewAgent", context.outputs.research, context)
+    },
+    {
+      id: "publish",
+      run: (context) => context.tools.call("publishAgent", context.outputs.review, context)
+    }
+  ]
+};
+
+const runtime = new AgentRuntime({ policyEngine, evidenceLedger, toolGateway });
+const result = await runtime.runWorkflow(workflow, {
+  objective: "Run a governed multi-agent workflow",
+  allowedTools: ["researchAgent", "reviewAgent", "publishAgent"]
+});
+
+console.log(result.status);
+```
+
+In this example, `publishAgent` will throw `ApprovalRequiredError` because it is approval-gated. That is intentional: Maqam controls the agent rather than letting it publish directly.
+
+What Maqam can control:
+
+- Function agents.
+- LangChain/LangGraph-style agents if exposed through `invoke` or wrapped in a function.
+- External SDK-style functions if wrapped in a function.
+- Browser agents.
+- Research agents.
+- GitHub/npm/internal API agents.
+- Email, Slack, Jira, database, or release agents when registered as tools.
+
+What Maqam cannot do automatically:
+
+- It cannot control an agent you do not route through `ToolGateway`.
+- It cannot make an unsafe third-party agent safe if that agent bypasses the wrapper and performs side effects internally.
+- It cannot approve risky actions by itself; approval-gated actions should be routed to humans.
+
+## Control CLI Workers
+
+Maqam can govern command-line workers the same way it governs function agents.
+
+The pattern is:
+
+1. Create a fixed CLI adapter with `createCliAgentTool`.
+2. Register it with `ToolGateway`.
+3. Add the worker name to `allowedTools`.
+4. Configure `timeoutMs`, `maxInputTokens`, and `maxOutputBytes`.
+5. Call the worker from a workflow task.
+
+Example workflow:
+
+```js
+import {
+  AgentRuntime,
+  EvidenceLedger,
+  PolicyEngine,
+  ToolGateway,
+  createCliAgentTool
+} from "maqam";
+
+const evidenceLedger = new EvidenceLedger();
+const policyEngine = new PolicyEngine({
+  allowedTools: ["builderWorker"]
+});
+const toolGateway = new ToolGateway({ policyEngine, evidenceLedger });
+
+toolGateway.registerTool("builderWorker", createCliAgentTool({
+  name: "builderWorker",
+  command: process.execPath,
+  args: ["--input-type=module", "-e", "let body=''; for await (const c of process.stdin) body += c; const input = JSON.parse(body); console.log(JSON.stringify({ fileName: `${input.name}.txt`, content: `Built ${input.name}` }));"],
+  stdin: "json",
+  parseJson: true,
+  timeoutMs: 5000,
+  maxInputTokens: 100,
+  maxOutputBytes: 4096
+}));
+
+const workflow = {
+  name: "governed_cli_build",
+  tasks: [
+    {
+      id: "build",
+      run: (context) => context.tools.call("builderWorker", {
+        name: "demo-widget"
+      }, context)
+    },
+    {
+      id: "record",
+      run: (context) => {
+        const output = context.outputs.build.json;
+        const evidence = context.evidence.addEvidence({
+          runId: context.runId,
+          taskId: "record",
+          sourceType: "cli_worker_output",
+          source: "builderWorker",
+          excerpt: output.content,
+          tool: "builderWorker",
+          confidence: 0.8
+        });
+        context.evidence.addClaim({
+          runId: context.runId,
+          taskId: "record",
+          text: `The worker created ${output.fileName}.`,
+          evidenceIds: [evidence.evidenceId],
+          confidence: 0.8
+        });
+        return output;
+      }
+    }
+  ]
+};
+
+const runtime = new AgentRuntime({ policyEngine, evidenceLedger, toolGateway });
+const result = await runtime.runWorkflow(workflow, {
+  objective: "Build a small artifact through a governed CLI worker",
+  allowedTools: ["builderWorker"]
+});
+
+console.log(result.outputs.record);
+console.log(result.evidence.unsupportedClaims);
+```
+
 ## Register A Custom Tool
 
 Tools should be small and explicit. The gateway handles policy and trace capture.
@@ -1092,3 +1443,7 @@ Useful next packages or modules:
 - Browser automation connector.
 - GitHub and npm metadata connectors.
 - Tenant-aware configuration and audit export.
+
+## Open Development
+
+Maqam is open source under MIT and open for development, issues, ideas, and contributions.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "maqam",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "Maqam is an MIT-licensed Ajnas agent framework for governed workflows, policy, evidence, skills, and crawler-backed research.",
   "license": "MIT",
   "author": {
@@ -43,6 +43,8 @@
     "skills",
     "tool-orchestration",
     "human-approval",
+    "cli-agent",
+    "command-runner",
     "crawler",
     "agent",
     "web-crawler",

package/src/framework/agent-tool.js

@@ -0,0 +1,43 @@
+function resolveAgentInvoker(agent) {
+  if (typeof agent === "function") return agent;
+  if (agent && typeof agent.run === "function") return agent.run.bind(agent);
+  if (agent && typeof agent.invoke === "function") return agent.invoke.bind(agent);
+  if (agent && typeof agent.call === "function") return agent.call.bind(agent);
+  throw new TypeError("createAgentTool requires a function agent or an object with run, invoke, or call.");
+}
+
+function recordAgentEvidence(result, context, agentName) {
+  const ledger = context.evidenceLedger || context.evidence;
+  if (!ledger || !result || typeof result !== "object") return;
+
+  for (const item of result.evidence || []) {
+    ledger.addEvidence({
+      runId: context.runId || item.runId || null,
+      taskId: context.taskId || item.taskId || null,
+      tool: context.toolName || agentName,
+      ...item
+    });
+  }
+
+  for (const item of result.claims || []) {
+    ledger.addClaim({
+      runId: context.runId || item.runId || null,
+      taskId: context.taskId || item.taskId || null,
+      ...item
+    });
+  }
+}
+
+export function createAgentTool(agent, options = {}) {
+  const invoke = resolveAgentInvoker(agent);
+  const agentName = options.name || agent?.name || "agent";
+
+  return async function agentTool(input = {}, context = {}) {
+    const result = await invoke(input, {
+      ...context,
+      agentName
+    });
+    recordAgentEvidence(result, context, agentName);
+    return result;
+  };
+}

package/src/framework/cli-agent-tool.js

@@ -0,0 +1,185 @@
+import { spawn } from "node:child_process";
+import { AjnasFrameworkError } from "./errors.js";
+
+const DEFAULT_TIMEOUT_MS = 30_000;
+const DEFAULT_MAX_INPUT_TOKENS = 4_000;
+const DEFAULT_MAX_OUTPUT_BYTES = 64 * 1024;
+
+function estimateTokens(value) {
+  return Math.ceil(Buffer.byteLength(value || "", "utf8") / 4);
+}
+
+function buildStdin(input, mode) {
+  if (mode === "none") return null;
+  if (mode === "text") return String(input.prompt ?? input.text ?? "");
+  return JSON.stringify(input);
+}
+
+function cliError(message, code, details = {}) {
+  return new AjnasFrameworkError(message, {
+    code,
+    details
+  });
+}
+
+export function createCliAgentTool(options = {}) {
+  const {
+    name = "cliAgent",
+    command,
+    args = [],
+    cwd,
+    env = {},
+    inheritEnv = true,
+    stdin = "json",
+    parseJson = false,
+    timeoutMs = DEFAULT_TIMEOUT_MS,
+    maxInputTokens = DEFAULT_MAX_INPUT_TOKENS,
+    maxOutputBytes = DEFAULT_MAX_OUTPUT_BYTES,
+    rejectOnNonZero = true,
+    shell = false
+  } = options;
+
+  if (!command || typeof command !== "string") {
+    throw new TypeError("createCliAgentTool requires a fixed command string.");
+  }
+  if (!Array.isArray(args) || args.some((arg) => typeof arg !== "string")) {
+    throw new TypeError("createCliAgentTool args must be an array of strings.");
+  }
+
+  return async function cliAgentTool(input = {}) {
+    const stdinBody = buildStdin(input, stdin);
+    const approxInputTokens = estimateTokens(stdinBody || "");
+    if (maxInputTokens && approxInputTokens > maxInputTokens) {
+      throw cliError(`CLI input exceeds maxInputTokens (${approxInputTokens} > ${maxInputTokens}).`, "CLI_INPUT_LIMIT_EXCEEDED", {
+        name,
+        approxInputTokens,
+        maxInputTokens
+      });
+    }
+
+    return new Promise((resolve, reject) => {
+      const startedAt = Date.now();
+      let child;
+      try {
+        child = spawn(command, args, {
+          cwd,
+          env: inheritEnv ? { ...process.env, ...env } : { ...env },
+          shell,
+          windowsHide: true,
+          stdio: ["pipe", "pipe", "pipe"]
+        });
+      } catch (error) {
+        reject(cliError(error.message, "CLI_SPAWN_FAILED", {
+          name,
+          command,
+          cause: error.code || error.name
+        }));
+        return;
+      }
+
+      const stdout = [];
+      const stderr = [];
+      let outputBytes = 0;
+      let settled = false;
+
+      const finish = (callback, value) => {
+        if (settled) return;
+        settled = true;
+        clearTimeout(timer);
+        callback(value);
+      };
+
+      const stopWithError = (error) => {
+        if (!child.killed) child.kill();
+        finish(reject, error);
+      };
+
+      const timer = setTimeout(() => {
+        stopWithError(cliError(`CLI agent '${name}' timed out after ${timeoutMs}ms.`, "CLI_TIMEOUT", {
+          name,
+          timeoutMs
+        }));
+      }, timeoutMs);
+
+      const collect = (target, chunk) => {
+        outputBytes += chunk.byteLength;
+        if (outputBytes > maxOutputBytes) {
+          stopWithError(cliError(`CLI output exceeds maxOutputBytes (${outputBytes} > ${maxOutputBytes}).`, "CLI_OUTPUT_LIMIT_EXCEEDED", {
+            name,
+            maxOutputBytes,
+            outputBytes
+          }));
+          return;
+        }
+        target.push(Buffer.from(chunk));
+      };
+
+      child.stdout.on("data", (chunk) => collect(stdout, chunk));
+      child.stderr.on("data", (chunk) => collect(stderr, chunk));
+
+      child.on("error", (error) => {
+        finish(reject, cliError(error.message, "CLI_SPAWN_FAILED", {
+          name,
+          command,
+          cause: error.code || error.name
+        }));
+      });
+
+      child.on("close", (exitCode, signal) => {
+        if (settled) return;
+
+        const stdoutText = Buffer.concat(stdout).toString("utf8");
+        const stderrText = Buffer.concat(stderr).toString("utf8");
+        const result = {
+          name,
+          command,
+          args,
+          exitCode,
+          signal,
+          timedOut: false,
+          stdout: stdoutText,
+          stderr: stderrText,
+          durationMs: Date.now() - startedAt,
+          approxInputTokens,
+          outputBytes,
+          limits: {
+            maxInputTokens,
+            maxOutputBytes,
+            timeoutMs
+          }
+        };
+
+        if (parseJson && stdoutText.trim()) {
+          try {
+            result.json = JSON.parse(stdoutText.trim());
+          } catch (error) {
+            finish(reject, cliError("CLI stdout was not valid JSON.", "CLI_JSON_PARSE_FAILED", {
+              name,
+              message: error.message
+            }));
+            return;
+          }
+        }
+
+        if (rejectOnNonZero && exitCode !== 0) {
+          finish(reject, cliError(`CLI agent '${name}' exited with code ${exitCode}.`, "CLI_EXIT_NONZERO", {
+            ...result,
+            stdout: stdoutText.slice(0, 2048),
+            stderr: stderrText.slice(0, 2048)
+          }));
+          return;
+        }
+
+        finish(resolve, result);
+      });
+
+      if (stdinBody === null) {
+        child.stdin.end();
+      } else {
+        child.stdin.end(stdinBody);
+      }
+    });
+  };
+}
+
+export { estimateTokens as estimateCliInputTokens };

package/src/index.js

@@ -339,6 +339,8 @@ export { EvidenceLedger } from "./framework/evidence-ledger.js";
 export { ToolGateway } from "./framework/tool-gateway.js";
 export { SkillRegistry } from "./framework/skill-registry.js";
 export { AgentRuntime } from "./framework/runtime.js";
+export { createAgentTool } from "./framework/agent-tool.js";
+export { createCliAgentTool, estimateCliInputTokens } from "./framework/cli-agent-tool.js";
 export { createResearchWorkflow } from "./framework/research-workflow.js";
 
 export function createCrawlerTool(defaultOptions = {}) {