maqam 0.1.4 → 0.1.5

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (7) hide show
  1. package/README.md +24 -2
  2. package/app/index.html +42 -3
  3. package/app/styles.css +46 -10
  4. package/docs/usage.md +45 -4
  5. package/package.json +2 -2
  6. package/src/framework/research-workflow.js +1 -1
  7. package/src/maqam/server.js +1 -1
package/README.md CHANGED
@@ -2,9 +2,9 @@
2
2
 
3
3
  ![Maqam governed agent framework hero](app/assets/maqam-readme-hero.png)
4
4
 
5
- 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.
5
+ 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.
6
6
 
7
- 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.
7
+ 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.
8
8
 
9
9
  Full documentation: [docs/usage.md](https://github.com/AjnasNB/maqam/blob/main/docs/usage.md)
10
10
 
@@ -12,6 +12,28 @@ Full documentation: [docs/usage.md](https://github.com/AjnasNB/maqam/blob/main/d
12
12
 
13
13
  ![Maqam governed CLI worker flow](app/assets/maqam-cli-agent-flow.png)
14
14
 
15
+ ## Universal Agent Control
16
+
17
+ Maqam controls agents by putting every worker behind the same gateway:
18
+
19
+ ```mermaid
20
+ flowchart LR
21
+ Goal["Goal"] --> Policy["PolicyEngine"]
22
+ Policy --> Runtime["AgentRuntime"]
23
+ Runtime --> Gateway["ToolGateway"]
24
+ Gateway --> FunctionAgent["Function agent"]
25
+ Gateway --> ObjectAgent["run / invoke / call agent"]
26
+ Gateway --> CliWorker["CLI worker"]
27
+ Gateway --> Connector["Crawler or SaaS connector"]
28
+ FunctionAgent --> Evidence["EvidenceLedger"]
29
+ ObjectAgent --> Evidence
30
+ CliWorker --> Evidence
31
+ Connector --> Evidence
32
+ Evidence --> Review["Trace, claims, approval path"]
33
+ ```
34
+
35
+ 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.
36
+
15
37
  ## What Ships
16
38
 
17
39
  - `AgentRuntime`: sequential workflow execution with retries, trace events, task outputs, and policy preflight.
package/app/index.html CHANGED
@@ -3,7 +3,7 @@
3
3
  <head>
4
4
  <meta charset="utf-8">
5
5
  <meta name="viewport" content="width=device-width, initial-scale=1">
6
- <meta name="description" content="Maqam is an enterprise agent framework console for governed research workflows.">
6
+ <meta name="description" content="Maqam is an agent framework console for governed workflows, CLI workers, connectors, and evidence-backed runs.">
7
7
  <title>Maqam | Compose governed agents</title>
8
8
  <link rel="icon" href="/assets/maqam-logo.svg" type="image/svg+xml">
9
9
  <link rel="stylesheet" href="/styles.css">
@@ -28,9 +28,9 @@
28
28
  <main>
29
29
  <section class="hero" aria-labelledby="hero-title">
30
30
  <div class="hero-copy">
31
- <p class="kicker">Enterprise agent framework</p>
31
+ <p class="kicker">Agent framework</p>
32
32
  <h1 id="hero-title">Build agent workflows that can be inspected, governed, and trusted.</h1>
33
- <p class="lede">Maqam composes skills, tools, policy, evidence, and runtime traces into one controlled workflow surface.</p>
33
+ <p class="lede">Maqam composes agents, CLI workers, connectors, policy, evidence, and runtime traces into one controlled workflow surface.</p>
34
34
  </div>
35
35
  <div class="run-panel" id="run">
36
36
  <div class="panel-header">
@@ -78,6 +78,45 @@
78
78
  </article>
79
79
  </section>
80
80
 
81
+ <section class="control-map" aria-labelledby="control-map-title">
82
+ <div class="section-heading">
83
+ <h2 id="control-map-title">Agent control map</h2>
84
+ <p>Every worker enters through the same governed path before it can read, write, crawl, call, or publish.</p>
85
+ </div>
86
+ <div class="control-grid">
87
+ <article>
88
+ <span>01</span>
89
+ <strong>Function agents</strong>
90
+ <p>Wrap local functions with `createAgentTool` and record their evidence and claims.</p>
91
+ </article>
92
+ <article>
93
+ <span>02</span>
94
+ <strong>Object agents</strong>
95
+ <p>Control existing workers that expose `run`, `invoke`, or `call` methods.</p>
96
+ </article>
97
+ <article>
98
+ <span>03</span>
99
+ <strong>CLI workers</strong>
100
+ <p>Run fixed commands with timeout, input-token, output-byte, and exit-code controls.</p>
101
+ </article>
102
+ <article>
103
+ <span>04</span>
104
+ <strong>Connectors</strong>
105
+ <p>Route crawlers, browser tools, SaaS APIs, and internal services through `ToolGateway`.</p>
106
+ </article>
107
+ <article>
108
+ <span>05</span>
109
+ <strong>Approvals</strong>
110
+ <p>Fail closed when a workflow reaches a write, publish, send, or modify action.</p>
111
+ </article>
112
+ <article>
113
+ <span>06</span>
114
+ <strong>Evidence</strong>
115
+ <p>Attach source records to claims so each run can be reviewed and audited.</p>
116
+ </article>
117
+ </div>
118
+ </section>
119
+
81
120
  <section class="workspace">
82
121
  <div class="column">
83
122
  <div class="section-heading">
package/app/styles.css CHANGED
@@ -95,12 +95,11 @@ a {
95
95
  }
96
96
 
97
97
  .hero {
98
- min-height: calc(100dvh - 76px);
99
98
  display: grid;
100
99
  grid-template-columns: minmax(0, 1.08fr) minmax(340px, .72fr);
101
100
  align-items: center;
102
101
  gap: 52px;
103
- padding: 52px 0;
102
+ padding: 44px 0 34px;
104
103
  }
105
104
 
106
105
  .kicker {
@@ -117,10 +116,10 @@ p {
117
116
 
118
117
  h1 {
119
118
  max-width: 820px;
120
- font-size: clamp(3rem, 8vw, 7.6rem);
121
- line-height: .96;
119
+ font-size: clamp(2.7rem, 5.4vw, 5rem);
120
+ line-height: 1;
122
121
  letter-spacing: 0;
123
- margin-bottom: 28px;
122
+ margin-bottom: 22px;
124
123
  }
125
124
 
126
125
  h2 {
@@ -131,12 +130,13 @@ h2 {
131
130
  .lede {
132
131
  max-width: 680px;
133
132
  color: var(--muted);
134
- font-size: 1.2rem;
135
- line-height: 1.65;
133
+ font-size: 1.08rem;
134
+ line-height: 1.55;
136
135
  }
137
136
 
138
137
  .run-panel,
139
138
  .metrics article,
139
+ .control-grid article,
140
140
  .stack > article,
141
141
  .policy-band {
142
142
  border: 1px solid var(--line);
@@ -246,6 +246,41 @@ button:disabled {
246
246
  font-size: 1.25rem;
247
247
  }
248
248
 
249
+ .control-map {
250
+ padding: 34px 0 12px;
251
+ }
252
+
253
+ .control-grid {
254
+ display: grid;
255
+ grid-template-columns: repeat(3, minmax(0, 1fr));
256
+ gap: 14px;
257
+ }
258
+
259
+ .control-grid article {
260
+ min-height: 172px;
261
+ padding: 18px;
262
+ display: grid;
263
+ align-content: start;
264
+ gap: 10px;
265
+ }
266
+
267
+ .control-grid span {
268
+ color: var(--blue);
269
+ font-size: .78rem;
270
+ font-weight: 800;
271
+ letter-spacing: .08em;
272
+ }
273
+
274
+ .control-grid strong {
275
+ font-size: 1.05rem;
276
+ }
277
+
278
+ .control-grid p {
279
+ color: var(--muted);
280
+ line-height: 1.5;
281
+ margin-bottom: 0;
282
+ }
283
+
249
284
  .workspace {
250
285
  display: grid;
251
286
  grid-template-columns: 1fr 1fr;
@@ -352,8 +387,7 @@ button:disabled {
352
387
  }
353
388
 
354
389
  .hero {
355
- min-height: auto;
356
- padding: 38px 0;
390
+ padding: 32px 0;
357
391
  gap: 30px;
358
392
  }
359
393
 
@@ -366,7 +400,8 @@ button:disabled {
366
400
  line-height: 1.02;
367
401
  }
368
402
 
369
- .metrics {
403
+ .metrics,
404
+ .control-grid {
370
405
  grid-template-columns: 1fr 1fr;
371
406
  }
372
407
  }
@@ -377,6 +412,7 @@ button:disabled {
377
412
  }
378
413
 
379
414
  .metrics,
415
+ .control-grid,
380
416
  .form-grid {
381
417
  grid-template-columns: 1fr;
382
418
  }
package/docs/usage.md CHANGED
@@ -1,6 +1,6 @@
1
1
  # Maqam Usage Guide
2
2
 
3
- 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`.
3
+ 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`.
4
4
 
5
5
  This guide covers installation, CLI usage, SDK usage, the local console, crawler usage, API reference, common patterns, and troubleshooting.
6
6
 
@@ -14,6 +14,7 @@ This guide covers installation, CLI usage, SDK usage, the local console, crawler
14
14
  - [Architecture](#architecture)
15
15
  - [API Reference](#api-reference)
16
16
  - [Build A Custom Workflow](#build-a-custom-workflow)
17
+ - [Universal Agent Control](#universal-agent-control)
17
18
  - [Control Any Agent](#control-any-agent)
18
19
  - [Control CLI Workers](#control-cli-workers)
19
20
  - [Register A Custom Tool](#register-a-custom-tool)
@@ -758,7 +759,7 @@ Candidate shape:
758
759
  "name": "Maqam",
759
760
  "url": "https://github.com/AjnasNB/maqam",
760
761
  "whatItDoes": "Summary excerpt...",
761
- "whyUseful": "Potential source or reference for enterprise agent framework capabilities.",
762
+ "whyUseful": "Potential source or reference for governed agent framework capabilities.",
762
763
  "risks": ["Requires license and maintenance review before reuse."],
763
764
  "recommendation": "inspiration_first",
764
765
  "evidenceIds": ["ev_1"]
@@ -911,6 +912,46 @@ console.log(result.outputs.record_summary);
911
912
  console.log(result.evidence.unsupportedClaims);
912
913
  ```
913
914
 
915
+ ## Universal Agent Control
916
+
917
+ Maqam is designed to control workers through stable adapter boundaries, not through one specific agent implementation.
918
+
919
+ ```mermaid
920
+ flowchart LR
921
+ Goal["Goal"] --> Policy["PolicyEngine"]
922
+ Policy --> Runtime["AgentRuntime"]
923
+ Runtime --> Gateway["ToolGateway"]
924
+ Gateway --> FunctionAgent["Function agent"]
925
+ Gateway --> ObjectAgent["Object agent: run / invoke / call"]
926
+ Gateway --> CliWorker["Fixed CLI worker"]
927
+ Gateway --> Connector["Crawler, browser, SaaS, or internal connector"]
928
+ FunctionAgent --> Evidence["EvidenceLedger"]
929
+ ObjectAgent --> Evidence
930
+ CliWorker --> Evidence
931
+ Connector --> Evidence
932
+ Evidence --> Trace["Trace, claims, approval, review"]
933
+ ```
934
+
935
+ Adapter matrix:
936
+
937
+ | Worker shape | Maqam adapter | Best for |
938
+ | --- | --- | --- |
939
+ | Function agent | `createAgentTool(fn)` | Small local agents, scoring functions, synthesis, transforms. |
940
+ | Object agent with `run`, `invoke`, or `call` | `createAgentTool(objectAgent)` | Existing agent frameworks and SDK objects. |
941
+ | Command-line worker | `createCliAgentTool(options)` | Local CLIs, sandboxed scripts, code tools, packaged executables. |
942
+ | HTTP or SDK connector | Custom `ToolGateway` tool function | SaaS tools, internal APIs, browser services, queues, storage. |
943
+ | Crawler-backed public research | `createCrawlerTool()` and `createResearchWorkflow()` | Source collection, discovery, evidence-backed research. |
944
+
945
+ Control path:
946
+
947
+ 1. `PolicyEngine` checks whether the goal, tool, origin, and budget are allowed.
948
+ 2. `AgentRuntime` executes workflow tasks in order and records task traces.
949
+ 3. `ToolGateway` is the only path to external work.
950
+ 4. Agent outputs can add evidence and claims to `EvidenceLedger`.
951
+ 5. Risky tools can be configured as approval-required and fail closed until a human approves.
952
+
953
+ 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.
954
+
914
955
  ## Control Any Agent
915
956
 
916
957
  Yes, Maqam can control agents beyond crawling. The pattern is:
@@ -1167,7 +1208,7 @@ Use evidence for source facts:
1167
1208
  const evidence = evidenceLedger.addEvidence({
1168
1209
  sourceType: "url",
1169
1210
  source: "https://github.com/AjnasNB/maqam",
1170
- excerpt: "Maqam is an MIT-licensed Ajnas agent framework...",
1211
+ excerpt: "Maqam is an MIT-licensed agent framework...",
1171
1212
  tool: "crawler",
1172
1213
  confidence: 0.85
1173
1214
  });
@@ -1238,7 +1279,7 @@ Response:
1238
1279
  "product": {
1239
1280
  "name": "Maqam",
1240
1281
  "tagline": "Compose governed agents",
1241
- "description": "Enterprise agent framework console for policy-bound research, evidence capture, and auditable workflow runs."
1282
+ "description": "Agent framework console for policy-bound workflows, evidence capture, CLI workers, connectors, and auditable runs."
1242
1283
  },
1243
1284
  "status": "ok"
1244
1285
  }
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "maqam",
3
- "version": "0.1.4",
4
- "description": "Maqam is an MIT-licensed Ajnas agent framework for governed workflows, policy, evidence, skills, and crawler-backed research.",
3
+ "version": "0.1.5",
4
+ "description": "Maqam is an MIT-licensed agent framework for governed workflows, policy, evidence, skills, CLI workers, and crawler-backed research.",
5
5
  "license": "MIT",
6
6
  "author": {
7
7
  "name": "Ajnas",
package/src/framework/research-workflow.js CHANGED
@@ -58,7 +58,7 @@ export function createResearchWorkflow(options = {}) {
58
58
  name,
59
59
  url: page.url,
60
60
  whatItDoes: page.description || page.text?.slice(0, 240) || page.title || "",
61
- whyUseful: "Potential source or reference for enterprise agent framework capabilities.",
61
+ whyUseful: "Potential source or reference for governed agent framework capabilities.",
62
62
  risks: ["Requires license and maintenance review before reuse."],
63
63
  recommendation: "inspiration_first",
64
64
  evidenceIds: [evidenceId]
package/src/maqam/server.js CHANGED
@@ -14,7 +14,7 @@ import {
14
14
  const PRODUCT = {
15
15
  name: "Maqam",
16
16
  tagline: "Compose governed agents",
17
- description: "Enterprise agent framework console for policy-bound research, evidence capture, and auditable workflow runs."
17
+ description: "Agent framework console for policy-bound workflows, evidence capture, CLI workers, connectors, and auditable runs."
18
18
  };
19
19
 
20
20
  const DEFAULT_PUBLIC_DIR = fileURLToPath(new URL("../../app/", import.meta.url));