maqam 0.1.2 → 0.1.3

package/README.md

@@ -2,9 +2,9 @@
 
 ![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)
 
@@ -16,6 +16,7 @@ Full documentation: [docs/usage.md](https://github.com/AjnasNB/maqam/blob/main/d
 - `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.
 - `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 +81,22 @@ import {
   EvidenceLedger,
   PolicyEngine,
   ToolGateway,
+  createAgentTool,
   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" }));
 
 const runtime = new AgentRuntime({ policyEngine, evidenceLedger, toolGateway: gateway });
 const result = await runtime.runWorkflow(
@@ -101,7 +106,7 @@ const result = await runtime.runWorkflow(
   }),
   {
     objective: "Research permissive OSS agent framework projects",
-    allowedTools: ["crawler"],
+    allowedTools: ["crawler", "summarizer"],
     allowedOrigins: ["https://github.com"]
   }
 );

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,7 @@ 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)
 - [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 +78,22 @@ import {
   EvidenceLedger,
   PolicyEngine,
   ToolGateway,
+  createAgentTool,
   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" }));
 
 const runtime = new AgentRuntime({ policyEngine, evidenceLedger, toolGateway });
 const result = await runtime.runWorkflow(
@@ -98,7 +103,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 +215,7 @@ import {
   PolicyEngine,
   ToolGateway,
   SkillRegistry,
+  createAgentTool,
   createCrawlerTool,
   createResearchWorkflow,
   crawl,
@@ -245,6 +251,7 @@ 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.
 - `EvidenceLedger`: stores source evidence and claim support.
 - `SkillRegistry`: stores skill metadata and selects matching skills.
 - `createResearchWorkflow`: bundled workflow for public web research.
@@ -560,6 +567,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.
@@ -741,6 +811,102 @@ 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.
+- OpenAI Agents 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.
+
 ## Register A Custom Tool
 
 Tools should be small and explicit. The gateway handles policy and trace capture.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "maqam",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "description": "Maqam is an MIT-licensed Ajnas agent framework for governed workflows, policy, evidence, skills, and crawler-backed research.",
   "license": "MIT",
   "author": {

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/index.js

@@ -339,6 +339,7 @@ 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 { createResearchWorkflow } from "./framework/research-workflow.js";
 
 export function createCrawlerTool(defaultOptions = {}) {