maqam 0.1.3 → 0.1.5

package/README.md

@@ -2,14 +2,38 @@
 
 ![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, generic agent adapter, human-review-ready approval errors, and a crawler-backed research workflow.
+Maqam is an MIT-licensed agent framework for governed workflows. It combines a local agent runtime, policy engine, evidence ledger, skill registry, tool gateway, generic agent adapter, CLI worker adapter, human-review-ready approval errors, and a crawler-backed research workflow.
 
-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.
+The crawler is not the product center; it is only one built-in connector. Maqam can govern any agent or tool you register through `ToolGateway`, including function agents, object agents with `run`/`invoke`/`call`, command-line workers, 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)
+
+## Universal Agent Control
+
+Maqam controls agents by putting every worker behind the same gateway:
+
+```mermaid
+flowchart LR
+  Goal["Goal"] --> Policy["PolicyEngine"]
+  Policy --> Runtime["AgentRuntime"]
+  Runtime --> Gateway["ToolGateway"]
+  Gateway --> FunctionAgent["Function agent"]
+  Gateway --> ObjectAgent["run / invoke / call agent"]
+  Gateway --> CliWorker["CLI worker"]
+  Gateway --> Connector["Crawler or SaaS connector"]
+  FunctionAgent --> Evidence["EvidenceLedger"]
+  ObjectAgent --> Evidence
+  CliWorker --> Evidence
+  Connector --> Evidence
+  Evidence --> Review["Trace, claims, approval path"]
+```
+
+That means Maqam is not limited to crawling. If an agent can be called as a function, object method, HTTP/SDK connector, or fixed command-line worker, Maqam can route it through policy, limits, trace capture, evidence, and human approval gates.
+
 ## What Ships
 
 - `AgentRuntime`: sequential workflow execution with retries, trace events, task outputs, and policy preflight.
@@ -17,6 +41,7 @@ Full documentation: [docs/usage.md](https://github.com/AjnasNB/maqam/blob/main/d
 - `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.
@@ -82,6 +107,7 @@ import {
   PolicyEngine,
   ToolGateway,
   createAgentTool,
+  createCliAgentTool,
   createCrawlerTool,
   createResearchWorkflow
 } from "maqam";
@@ -97,6 +123,15 @@ 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(
@@ -154,7 +189,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.
 
@@ -181,3 +216,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/app/index.html

@@ -3,7 +3,7 @@
   <head>
     <meta charset="utf-8">
     <meta name="viewport" content="width=device-width, initial-scale=1">
-    <meta name="description" content="Maqam is an enterprise agent framework console for governed research workflows.">
+    <meta name="description" content="Maqam is an agent framework console for governed workflows, CLI workers, connectors, and evidence-backed runs.">
     <title>Maqam | Compose governed agents</title>
     <link rel="icon" href="/assets/maqam-logo.svg" type="image/svg+xml">
     <link rel="stylesheet" href="/styles.css">
@@ -28,9 +28,9 @@
       <main>
         <section class="hero" aria-labelledby="hero-title">
           <div class="hero-copy">
-            <p class="kicker">Enterprise agent framework</p>
+            <p class="kicker">Agent framework</p>
             <h1 id="hero-title">Build agent workflows that can be inspected, governed, and trusted.</h1>
-            <p class="lede">Maqam composes skills, tools, policy, evidence, and runtime traces into one controlled workflow surface.</p>
+            <p class="lede">Maqam composes agents, CLI workers, connectors, policy, evidence, and runtime traces into one controlled workflow surface.</p>
           </div>
           <div class="run-panel" id="run">
             <div class="panel-header">
@@ -78,6 +78,45 @@
           </article>
         </section>
 
+        <section class="control-map" aria-labelledby="control-map-title">
+          <div class="section-heading">
+            <h2 id="control-map-title">Agent control map</h2>
+            <p>Every worker enters through the same governed path before it can read, write, crawl, call, or publish.</p>
+          </div>
+          <div class="control-grid">
+            <article>
+              <span>01</span>
+              <strong>Function agents</strong>
+              <p>Wrap local functions with `createAgentTool` and record their evidence and claims.</p>
+            </article>
+            <article>
+              <span>02</span>
+              <strong>Object agents</strong>
+              <p>Control existing workers that expose `run`, `invoke`, or `call` methods.</p>
+            </article>
+            <article>
+              <span>03</span>
+              <strong>CLI workers</strong>
+              <p>Run fixed commands with timeout, input-token, output-byte, and exit-code controls.</p>
+            </article>
+            <article>
+              <span>04</span>
+              <strong>Connectors</strong>
+              <p>Route crawlers, browser tools, SaaS APIs, and internal services through `ToolGateway`.</p>
+            </article>
+            <article>
+              <span>05</span>
+              <strong>Approvals</strong>
+              <p>Fail closed when a workflow reaches a write, publish, send, or modify action.</p>
+            </article>
+            <article>
+              <span>06</span>
+              <strong>Evidence</strong>
+              <p>Attach source records to claims so each run can be reviewed and audited.</p>
+            </article>
+          </div>
+        </section>
+
         <section class="workspace">
           <div class="column">
             <div class="section-heading">

package/app/styles.css

@@ -95,12 +95,11 @@ a {
 }
 
 .hero {
-  min-height: calc(100dvh - 76px);
   display: grid;
   grid-template-columns: minmax(0, 1.08fr) minmax(340px, .72fr);
   align-items: center;
   gap: 52px;
-  padding: 52px 0;
+  padding: 44px 0 34px;
 }
 
 .kicker {
@@ -117,10 +116,10 @@ p {
 
 h1 {
   max-width: 820px;
-  font-size: clamp(3rem, 8vw, 7.6rem);
-  line-height: .96;
+  font-size: clamp(2.7rem, 5.4vw, 5rem);
+  line-height: 1;
   letter-spacing: 0;
-  margin-bottom: 28px;
+  margin-bottom: 22px;
 }
 
 h2 {
@@ -131,12 +130,13 @@ h2 {
 .lede {
   max-width: 680px;
   color: var(--muted);
-  font-size: 1.2rem;
-  line-height: 1.65;
+  font-size: 1.08rem;
+  line-height: 1.55;
 }
 
 .run-panel,
 .metrics article,
+.control-grid article,
 .stack > article,
 .policy-band {
   border: 1px solid var(--line);
@@ -246,6 +246,41 @@ button:disabled {
   font-size: 1.25rem;
 }
 
+.control-map {
+  padding: 34px 0 12px;
+}
+
+.control-grid {
+  display: grid;
+  grid-template-columns: repeat(3, minmax(0, 1fr));
+  gap: 14px;
+}
+
+.control-grid article {
+  min-height: 172px;
+  padding: 18px;
+  display: grid;
+  align-content: start;
+  gap: 10px;
+}
+
+.control-grid span {
+  color: var(--blue);
+  font-size: .78rem;
+  font-weight: 800;
+  letter-spacing: .08em;
+}
+
+.control-grid strong {
+  font-size: 1.05rem;
+}
+
+.control-grid p {
+  color: var(--muted);
+  line-height: 1.5;
+  margin-bottom: 0;
+}
+
 .workspace {
   display: grid;
   grid-template-columns: 1fr 1fr;
@@ -352,8 +387,7 @@ button:disabled {
   }
 
   .hero {
-    min-height: auto;
-    padding: 38px 0;
+    padding: 32px 0;
     gap: 30px;
   }
 
@@ -366,7 +400,8 @@ button:disabled {
     line-height: 1.02;
   }
 
-  .metrics {
+  .metrics,
+  .control-grid {
     grid-template-columns: 1fr 1fr;
   }
 }
@@ -377,6 +412,7 @@ button:disabled {
   }
 
   .metrics,
+  .control-grid,
   .form-grid {
     grid-template-columns: 1fr;
   }

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. The crawler is only one built-in connector; Maqam can also govern arbitrary agents and tools through `createAgentTool` and `ToolGateway`.
+Maqam is an MIT-licensed 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`, `createCliAgentTool`, and `ToolGateway`.
 
 This guide covers installation, CLI usage, SDK usage, the local console, crawler usage, API reference, common patterns, and troubleshooting.
 
@@ -14,7 +14,9 @@ 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)
+- [Universal Agent Control](#universal-agent-control)
 - [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)
@@ -79,6 +81,7 @@ import {
   PolicyEngine,
   ToolGateway,
   createAgentTool,
+  createCliAgentTool,
   createCrawlerTool,
   createResearchWorkflow
 } from "maqam";
@@ -94,6 +97,15 @@ 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(
@@ -216,6 +228,7 @@ import {
   ToolGateway,
   SkillRegistry,
   createAgentTool,
+  createCliAgentTool,
   createCrawlerTool,
   createResearchWorkflow,
   crawl,
@@ -252,6 +265,7 @@ Core objects:
 - `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.
@@ -643,6 +657,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 |
@@ -658,7 +759,7 @@ Candidate shape:
   "name": "Maqam",
   "url": "https://github.com/AjnasNB/maqam",
   "whatItDoes": "Summary excerpt...",
-  "whyUseful": "Potential source or reference for enterprise agent framework capabilities.",
+  "whyUseful": "Potential source or reference for governed agent framework capabilities.",
   "risks": ["Requires license and maintenance review before reuse."],
   "recommendation": "inspiration_first",
   "evidenceIds": ["ev_1"]
@@ -811,6 +912,46 @@ console.log(result.outputs.record_summary);
 console.log(result.evidence.unsupportedClaims);
 ```
 
+## Universal Agent Control
+
+Maqam is designed to control workers through stable adapter boundaries, not through one specific agent implementation.
+
+```mermaid
+flowchart LR
+  Goal["Goal"] --> Policy["PolicyEngine"]
+  Policy --> Runtime["AgentRuntime"]
+  Runtime --> Gateway["ToolGateway"]
+  Gateway --> FunctionAgent["Function agent"]
+  Gateway --> ObjectAgent["Object agent: run / invoke / call"]
+  Gateway --> CliWorker["Fixed CLI worker"]
+  Gateway --> Connector["Crawler, browser, SaaS, or internal connector"]
+  FunctionAgent --> Evidence["EvidenceLedger"]
+  ObjectAgent --> Evidence
+  CliWorker --> Evidence
+  Connector --> Evidence
+  Evidence --> Trace["Trace, claims, approval, review"]
+```
+
+Adapter matrix:
+
+| Worker shape | Maqam adapter | Best for |
+| --- | --- | --- |
+| Function agent | `createAgentTool(fn)` | Small local agents, scoring functions, synthesis, transforms. |
+| Object agent with `run`, `invoke`, or `call` | `createAgentTool(objectAgent)` | Existing agent frameworks and SDK objects. |
+| Command-line worker | `createCliAgentTool(options)` | Local CLIs, sandboxed scripts, code tools, packaged executables. |
+| HTTP or SDK connector | Custom `ToolGateway` tool function | SaaS tools, internal APIs, browser services, queues, storage. |
+| Crawler-backed public research | `createCrawlerTool()` and `createResearchWorkflow()` | Source collection, discovery, evidence-backed research. |
+
+Control path:
+
+1. `PolicyEngine` checks whether the goal, tool, origin, and budget are allowed.
+2. `AgentRuntime` executes workflow tasks in order and records task traces.
+3. `ToolGateway` is the only path to external work.
+4. Agent outputs can add evidence and claims to `EvidenceLedger`.
+5. Risky tools can be configured as approval-required and fail closed until a human approves.
+
+What this proves in practice: Maqam does not need the worker to be written for Maqam. The worker only needs a stable callable boundary. That boundary can be a JavaScript function, an object method, a CLI command, or a connector function.
+
 ## Control Any Agent
 
 Yes, Maqam can control agents beyond crawling. The pattern is:
@@ -895,7 +1036,7 @@ What Maqam can control:
 
 - Function agents.
 - LangChain/LangGraph-style agents if exposed through `invoke` or wrapped in a function.
-- OpenAI Agents SDK-style functions if wrapped in a function.
+- External SDK-style functions if wrapped in a function.
 - Browser agents.
 - Research agents.
 - GitHub/npm/internal API agents.
@@ -907,6 +1048,91 @@ What Maqam cannot do automatically:
 - 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.
@@ -982,7 +1208,7 @@ Use evidence for source facts:
 const evidence = evidenceLedger.addEvidence({
   sourceType: "url",
   source: "https://github.com/AjnasNB/maqam",
-  excerpt: "Maqam is an MIT-licensed Ajnas agent framework...",
+  excerpt: "Maqam is an MIT-licensed agent framework...",
   tool: "crawler",
   confidence: 0.85
 });
@@ -1053,7 +1279,7 @@ Response:
   "product": {
     "name": "Maqam",
     "tagline": "Compose governed agents",
-    "description": "Enterprise agent framework console for policy-bound research, evidence capture, and auditable workflow runs."
+    "description": "Agent framework console for policy-bound workflows, evidence capture, CLI workers, connectors, and auditable runs."
   },
   "status": "ok"
 }
@@ -1258,3 +1484,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,7 +1,7 @@
 {
   "name": "maqam",
-  "version": "0.1.3",
-  "description": "Maqam is an MIT-licensed Ajnas agent framework for governed workflows, policy, evidence, skills, and crawler-backed research.",
+  "version": "0.1.5",
+  "description": "Maqam is an MIT-licensed agent framework for governed workflows, policy, evidence, skills, CLI workers, and crawler-backed research.",
   "license": "MIT",
   "author": {
     "name": "Ajnas",
@@ -43,6 +43,8 @@
     "skills",
     "tool-orchestration",
     "human-approval",
+    "cli-agent",
+    "command-runner",
     "crawler",
     "agent",
     "web-crawler",

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/framework/research-workflow.js

@@ -58,7 +58,7 @@ export function createResearchWorkflow(options = {}) {
               name,
               url: page.url,
               whatItDoes: page.description || page.text?.slice(0, 240) || page.title || "",
-              whyUseful: "Potential source or reference for enterprise agent framework capabilities.",
+              whyUseful: "Potential source or reference for governed agent framework capabilities.",
               risks: ["Requires license and maintenance review before reuse."],
               recommendation: "inspiration_first",
               evidenceIds: [evidenceId]

package/src/index.js

@@ -340,6 +340,7 @@ 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 = {}) {

package/src/maqam/server.js

@@ -14,7 +14,7 @@ import {
 const PRODUCT = {
   name: "Maqam",
   tagline: "Compose governed agents",
-  description: "Enterprise agent framework console for policy-bound research, evidence capture, and auditable workflow runs."
+  description: "Agent framework console for policy-bound workflows, evidence capture, CLI workers, connectors, and auditable runs."
 };
 
 const DEFAULT_PUBLIC_DIR = fileURLToPath(new URL("../../app/", import.meta.url));