maqam 0.1.4 → 0.1.6
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.
- package/README.md +24 -2
- package/app/index.html +42 -3
- package/app/styles.css +46 -10
- package/bin/maqam.js +1 -1
- package/docs/usage.md +45 -4
- package/package.json +2 -2
- package/src/framework/research-workflow.js +1 -1
- package/src/maqam/server.js +1 -1
package/README.md
CHANGED
|
@@ -2,9 +2,9 @@
|
|
|
2
2
|
|
|
3
3
|
|
|
4
4
|
|
|
5
|
-
Maqam is an MIT-licensed
|
|
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
|
|
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
|
|
|
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
|
|
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">
|
|
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
|
|
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:
|
|
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(
|
|
121
|
-
line-height:
|
|
119
|
+
font-size: clamp(2.7rem, 5.4vw, 5rem);
|
|
120
|
+
line-height: 1;
|
|
122
121
|
letter-spacing: 0;
|
|
123
|
-
margin-bottom:
|
|
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.
|
|
135
|
-
line-height: 1.
|
|
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
|
-
|
|
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/bin/maqam.js
CHANGED
package/docs/usage.md
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# Maqam Usage Guide
|
|
2
2
|
|
|
3
|
-
Maqam is an MIT-licensed
|
|
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
|
|
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
|
|
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": "
|
|
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
|
-
"description": "Maqam is an MIT-licensed
|
|
3
|
+
"version": "0.1.6",
|
|
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",
|
|
@@ -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
|
|
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: "
|
|
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));
|