Maqam 0.3.3 quickstart

Run the exact-approval proof, register a governed tool, route normalized research sources, and use the feed-aware bounded crawler.

Read the complete feature inventory

Start here: the product in plain English

Maqam

A security turnstile for actions performed by software agents. It checks policy, binds approval to the exact input that will run, permits that approved call once, and records the decision and result.

ProductLoop OS

The modular toolbox around Maqam. It adds focused packages for runtime, policy, approval workflows, provenance, skills, connector trust, evaluations, and browser-research records.

ProductLoop Workbench

The open-source local operator surface around those records. It adds durable single-operator runs, an exact approval inbox, evidence and memory views, policy explanations, and proof export.

Use Maqam alone

When a TypeScript application needs one compact execution boundary around functions, SDK calls, CLI workers, file writes, publishing, or bounded HTTP research.

Use ProductLoop too

When the application also needs the broader package family and explicit composition helpers. ProductLoop does not turn the modules into a hidden hosted control plane.

Typical uses include approving one exact npm publish, deployment, refund, CRM update, email send, filesystem write, or research crawl. The five-step mental model is: propose the call, evaluate policy, bind approval to the canonical input, dispatch once, then retain trace and evidence records.

Install Maqam 0.3.3

After checking that the live registry metadata still matches the tagged source, use the pinned command-line proof without modifying a project or pin the package in your dependency manifest.

# Verify npm, provenance, integrity, and the matching tag first
# One-off proof from the verified release
npx -y maqam@0.3.3 demo approval

# Pinned project dependency
npm install maqam@0.3.3

Run the exact-approval proof

The demo creates an isolated temporary workspace, performs one exact approved write, verifies the file, and removes the workspace.

# Run only after registry verification
npx -y maqam@0.3.3 demo approval
npx -y maqam@0.3.3 demo approval --json

Expected checkpoints:

APPROVAL_REQUIRED
APPROVAL_SCOPE_MISMATCH
executions 0
COMPLETED
executions 1 | approval consumptions 1
APPROVAL_INVALID
ev_1 -> claim_1
unsupported claims 0
PASS

Register a governed tool

This local fixture has no real publish side effect. It shows the contract you should preserve when replacing the handler.

import assert from "node:assert/strict";
import {
  ApprovalQueue,
  ApprovalRequiredError,
  PolicyEngine,
  ToolGateway
} from "maqam";

const approvals = new ApprovalQueue();
const policy = new PolicyEngine({
  allowedTools: ["publisher"],
  approvalRequiredEffects: ["publish"]
});
const gateway = new ToolGateway({
  policyEngine: policy,
  approvalQueue: approvals
});

let executions = 0;
gateway.registerTool("publisher", async (input) => {
  executions += 1;
  return { published: input.version };
}, { effects: ["publish"] });

const input = { packageName: "demo", version: "1.0.0" };
const context = { runId: "release_1" };
let request;

try {
  await gateway.call("publisher", input, context);
  assert.fail("The handler must wait for approval.");
} catch (error) {
  assert.ok(error instanceof ApprovalRequiredError);
  request = error.details.approvalRequests[0];
}

assert.equal(executions, 0);
approvals.approve(request.approvalId, {
  decidedBy: "authenticated-owner"
});

await assert.rejects(
  gateway.call("publisher", { ...input, version: "2.0.0" }, {
    ...context,
    approvalId: request.approvalId
  }),
  (error) => error.code === "APPROVAL_SCOPE_MISMATCH"
);

const result = await gateway.call("publisher", input, {
  ...context,
  approvalId: request.approvalId
});

assert.deepEqual(result, { published: "1.0.0" });
assert.equal(executions, 1);
console.log("PASS");

Connect workers

Maqam can wrap a function, an explicitly bound object method, a fixed command-line worker, Codex CLI, Claude Code, or a host-supplied SDK, HTTP, or MCP-shaped client call.

Codex read-only review

import {
  PolicyEngine,
  ToolGateway,
  createCodexAgentTool
} from "maqam";

const policy = new PolicyEngine({
  allowedTools: ["codeReview"],
  maxToolCalls: 1
});
const gateway = new ToolGateway({ policyEngine: policy });

gateway.registerTool("codeReview", createCodexAgentTool({
  cwd: process.cwd(),
  sandbox: "read-only",
  timeoutMs: 90_000,
  maxInputTokens: 1_000,
  maxOutputTokens: 16_000,
  maxTotalTokens: 50_000
}));

const result = await gateway.call("codeReview", {
  prompt: "Review the current diff. Do not modify files."
}, {
  runId: "review_1",
  limits: { maxToolCalls: 1 }
});

console.log(result.output);

The provider CLI must already be installed and authenticated. Keep provider permissions narrower than Maqam policy. Use a container, virtual machine, or restricted operating-system account when you need a hard host boundary.

Read the complete coding-agent guide on GitHub.

Route governed research sources

ResearchSourceRegistry orders static source adapters and normalizes their output into immutable ResearchDocument records. Its governed route() method requires a host-supplied ToolCaller; bind that caller to a configured Maqam gateway. The explicit routeUngoverned() alternative bypasses that gateway and reports the bypass in its result.

Use the bounded crawler

The built-in crawler is HTTP-only. It blocks special-purpose destinations by default, checks robots.txt, validates each redirect, pins connections to validated DNS results, enforces response limits, and can opt into linked RSS and Atom feeds.

import { crawlDetailed } from "maqam";

const result = await crawlDetailed({
  seeds: ["https://example.com"],
  allowedOrigins: ["https://example.com"],
  maxPages: 10,
  maxRequests: 80,
  maxDepth: 5,
  includeFeeds: true,
  maxFeedLinks: 20,
  maxFeedItems: 100
});

console.log(result.pages);
console.log(result.failures);
console.log(result.stats);

npx --yes --package=maqam@0.3.3 maqam-crawl https://example.com \
  --max-pages 25 \
  --max-requests 100 \
  --feeds \
  --delay 250 \
  --detailed \
  --stats \
  --output crawl.json

When crawling is the main workload, install the separate Cockroach Crawler package. Its Maqam integration guide shows how to keep crawler network policy inside the crawler while routing the registered tool call through Maqam policy, traces, approvals, and evidence.

Run the local console

# Verify the live registry record first
npx -y maqam@0.3.3
# Open http://127.0.0.1:8787

The console binds to loopback by default. Remote binding requires authentication, an explicit Host allowlist, trusted UI origins, and deployment-level egress controls.

0.3.0 integration APIs

Use the integration guide for tool adapters, the source guide for research backends, and the governed-browser guide for the structural browser boundary introduced in 0.3.1 and retained in 0.3.3. Production projects can pin maqam@0.3.3 after verifying its npm provenance, registry gitHead, integrity, and matching source release.

Know the boundary

Governed

Calls routed through a registered ToolGateway path with explicit policy and configured approval rules.

Not governed

Direct provider, SDK, HTTP, MCP, browser, or process calls that bypass the registered adapter.

Recorded

Workflow traces, gateway decisions, approval scope and consumption, plus evidence and claims that code explicitly adds.

Not guaranteed

Reviewer identity, source truth, durable state, provider-internal behavior, operating-system isolation, secret storage, or safe rollback.

Before connecting a real side effect, define its minimum effects, exact review payload, idempotency, recovery behavior, trusted persistence, credentials, network controls, and independent authorization.