maqam 0.1.3 → 0.1.4

package/README.md

@@ -10,6 +10,8 @@ Full documentation: [docs/usage.md](https://github.com/AjnasNB/maqam/blob/main/d
 
 ![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.
@@ -17,6 +19,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 +85,7 @@ import {
   PolicyEngine,
   ToolGateway,
   createAgentTool,
+  createCliAgentTool,
   createCrawlerTool,
   createResearchWorkflow
 } from "maqam";
@@ -97,6 +101,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 +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.
 
@@ -181,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

@@ -15,6 +15,7 @@ This guide covers installation, CLI usage, SDK usage, the local console, crawler
 - [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)
@@ -79,6 +80,7 @@ import {
   PolicyEngine,
   ToolGateway,
   createAgentTool,
+  createCliAgentTool,
   createCrawlerTool,
   createResearchWorkflow
 } from "maqam";
@@ -94,6 +96,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 +227,7 @@ import {
   ToolGateway,
   SkillRegistry,
   createAgentTool,
+  createCliAgentTool,
   createCrawlerTool,
   createResearchWorkflow,
   crawl,
@@ -252,6 +264,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 +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 |
@@ -895,7 +995,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 +1007,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.
@@ -1258,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.3",
+  "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/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

@@ -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 = {}) {