maqam 0.1.0

package/app/styles.css

@@ -0,0 +1,397 @@
+:root {
+  color-scheme: dark;
+  --bg: #080d0c;
+  --panel: #111816;
+  --panel-2: #18211f;
+  --line: #2d3935;
+  --text: #f4f7f3;
+  --muted: #a9b7b0;
+  --blue: #48c7ff;
+  --green: #84e07f;
+  --danger: #ff7a73;
+  --radius: 14px;
+  font-family: "Aptos", "Segoe UI", sans-serif;
+}
+
+* {
+  box-sizing: border-box;
+}
+
+body {
+  margin: 0;
+  background:
+    linear-gradient(135deg, rgb(72 199 255 / .08), transparent 35%),
+    linear-gradient(315deg, rgb(132 224 127 / .08), transparent 42%),
+    var(--bg);
+  color: var(--text);
+  min-width: 320px;
+}
+
+a {
+  color: inherit;
+  text-decoration: none;
+}
+
+.shell {
+  width: min(1180px, calc(100% - 32px));
+  margin: 0 auto;
+}
+
+.topbar {
+  min-height: 76px;
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 24px;
+  border-bottom: 1px solid var(--line);
+}
+
+.brand {
+  display: inline-flex;
+  align-items: center;
+  gap: 12px;
+}
+
+.brand img {
+  border-radius: 12px;
+}
+
+.brand span {
+  display: grid;
+  gap: 2px;
+}
+
+.brand strong {
+  font-size: 1rem;
+}
+
+.brand small,
+.hint,
+.section-heading p,
+.policy-band p,
+.metrics span {
+  color: var(--muted);
+}
+
+.nav {
+  display: flex;
+  gap: 6px;
+  padding: 6px;
+  border: 1px solid var(--line);
+  border-radius: 999px;
+  background: rgb(17 24 22 / .8);
+}
+
+.nav a {
+  color: var(--muted);
+  padding: 8px 12px;
+  border-radius: 999px;
+  font-size: .92rem;
+}
+
+.nav a:hover {
+  color: var(--text);
+  background: rgb(244 247 243 / .08);
+}
+
+.hero {
+  min-height: calc(100dvh - 76px);
+  display: grid;
+  grid-template-columns: minmax(0, 1.08fr) minmax(340px, .72fr);
+  align-items: center;
+  gap: 52px;
+  padding: 52px 0;
+}
+
+.kicker {
+  color: var(--green);
+  font-weight: 700;
+  margin: 0 0 20px;
+}
+
+h1,
+h2,
+p {
+  margin-top: 0;
+}
+
+h1 {
+  max-width: 820px;
+  font-size: clamp(3rem, 8vw, 7.6rem);
+  line-height: .96;
+  letter-spacing: 0;
+  margin-bottom: 28px;
+}
+
+h2 {
+  font-size: 1.35rem;
+  letter-spacing: 0;
+}
+
+.lede {
+  max-width: 680px;
+  color: var(--muted);
+  font-size: 1.2rem;
+  line-height: 1.65;
+}
+
+.run-panel,
+.metrics article,
+.stack > article,
+.policy-band {
+  border: 1px solid var(--line);
+  border-radius: var(--radius);
+  background: linear-gradient(180deg, rgb(244 247 243 / .06), rgb(244 247 243 / .025));
+}
+
+.run-panel {
+  padding: 22px;
+  box-shadow: 0 24px 80px rgb(0 0 0 / .22);
+}
+
+.panel-header {
+  display: flex;
+  justify-content: space-between;
+  gap: 16px;
+  margin-bottom: 24px;
+  color: var(--muted);
+}
+
+.panel-header strong {
+  color: var(--green);
+}
+
+form {
+  display: grid;
+  gap: 16px;
+}
+
+label {
+  display: grid;
+  gap: 8px;
+  color: var(--muted);
+  font-size: .94rem;
+}
+
+input,
+select {
+  width: 100%;
+  min-height: 46px;
+  border: 1px solid var(--line);
+  border-radius: 10px;
+  background: var(--panel);
+  color: var(--text);
+  padding: 0 12px;
+  font: inherit;
+}
+
+input:focus,
+select:focus,
+button:focus-visible,
+a:focus-visible {
+  outline: 3px solid rgb(72 199 255 / .45);
+  outline-offset: 2px;
+}
+
+.form-grid {
+  display: grid;
+  grid-template-columns: 1fr 1fr;
+  gap: 12px;
+}
+
+button {
+  min-height: 48px;
+  border: 0;
+  border-radius: 999px;
+  background: var(--text);
+  color: #0c1110;
+  font: inherit;
+  font-weight: 800;
+  cursor: pointer;
+}
+
+button:hover {
+  background: var(--green);
+}
+
+button:active {
+  transform: translateY(1px);
+}
+
+button:disabled {
+  cursor: wait;
+  opacity: .7;
+}
+
+.hint {
+  margin: 0;
+  font-size: .9rem;
+  line-height: 1.5;
+}
+
+.metrics {
+  display: grid;
+  grid-template-columns: repeat(4, minmax(0, 1fr));
+  gap: 14px;
+  margin-bottom: 26px;
+}
+
+.metrics article {
+  padding: 18px;
+  display: grid;
+  gap: 8px;
+}
+
+.metrics strong {
+  font-size: 1.25rem;
+}
+
+.workspace {
+  display: grid;
+  grid-template-columns: 1fr 1fr;
+  gap: 26px;
+  padding: 38px 0;
+}
+
+.section-heading {
+  border-bottom: 1px solid var(--line);
+  margin-bottom: 16px;
+  padding-bottom: 14px;
+}
+
+.section-heading p {
+  margin-bottom: 0;
+}
+
+.stack {
+  display: grid;
+  gap: 12px;
+}
+
+.empty {
+  min-height: 150px;
+  align-content: center;
+  padding: 20px;
+  border: 1px dashed var(--line);
+  border-radius: var(--radius);
+  color: var(--muted);
+}
+
+.stack > article {
+  padding: 16px;
+}
+
+.stack h3 {
+  margin: 0 0 8px;
+  font-size: 1rem;
+}
+
+.stack p {
+  color: var(--muted);
+  line-height: 1.55;
+  margin-bottom: 12px;
+}
+
+.tag-row {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 8px;
+}
+
+.tag {
+  display: inline-flex;
+  align-items: center;
+  min-height: 28px;
+  padding: 0 10px;
+  border-radius: 999px;
+  border: 1px solid var(--line);
+  color: var(--green);
+  background: rgb(132 224 127 / .08);
+  font-size: .82rem;
+}
+
+.policy-band {
+  display: grid;
+  grid-template-columns: .9fr 1.1fr;
+  gap: 24px;
+  padding: 24px;
+  margin: 20px 0 54px;
+}
+
+.policy-band ol {
+  margin: 0;
+  display: grid;
+  gap: 10px;
+}
+
+.policy-band li {
+  color: var(--muted);
+}
+
+.error {
+  color: var(--danger);
+}
+
+@media (max-width: 860px) {
+  .topbar,
+  .hero,
+  .workspace,
+  .policy-band {
+    grid-template-columns: 1fr;
+  }
+
+  .topbar {
+    align-items: flex-start;
+    flex-direction: column;
+    padding: 16px 0;
+  }
+
+  .nav {
+    width: 100%;
+    justify-content: space-between;
+  }
+
+  .hero {
+    min-height: auto;
+    padding: 38px 0;
+    gap: 30px;
+  }
+
+  .run-panel {
+    order: -1;
+  }
+
+  h1 {
+    font-size: clamp(2.35rem, 11vw, 3.6rem);
+    line-height: 1.02;
+  }
+
+  .metrics {
+    grid-template-columns: 1fr 1fr;
+  }
+}
+
+@media (max-width: 560px) {
+  .shell {
+    width: min(100% - 24px, 1180px);
+  }
+
+  .metrics,
+  .form-grid {
+    grid-template-columns: 1fr;
+  }
+
+  .nav a {
+    padding-inline: 9px;
+  }
+}
+
+@media (prefers-reduced-motion: reduce) {
+  *,
+  *::before,
+  *::after {
+    scroll-behavior: auto !important;
+    transition: none !important;
+    animation: none !important;
+  }
+}

package/bin/ajnas-crawl.js

@@ -0,0 +1,119 @@
+#!/usr/bin/env node
+import { createWriteStream } from "node:fs";
+import { crawl } from "../src/index.js";
+
+function usage() {
+  console.log(`
+Maqam Crawler
+
+Usage:
+  maqam-crawl <url> [more urls...] [options]
+
+Options:
+  --max-pages <n>       Maximum pages to return. Default: 50
+  --concurrency <n>     Concurrent workers. Default: 4
+  --delay <ms>          Minimum delay per origin. Default: 250
+  --timeout <ms>        Request timeout. Default: 15000
+  --sitemaps            Discover URLs from robots.txt sitemaps and /sitemap.xml
+  --all-origins         Allow crawling across origins discovered from links
+  --jsonl               Output JSON Lines instead of a JSON array
+  --output <file>       Write output to a file
+  --user-agent <ua>     Custom user agent
+  --help                Show this help
+
+This crawler is Maqam's first governed connector. It respects robots.txt by default and does not bypass access controls.
+`);
+}
+
+function readArgs(argv) {
+  const urls = [];
+  const options = {
+    maxPages: 50,
+    concurrency: 4,
+    delayMs: 250,
+    timeoutMs: 15_000,
+    includeSitemaps: false,
+    sameOrigin: true,
+    jsonl: false,
+    output: null,
+    userAgent: undefined
+  };
+
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (arg === "--help" || arg === "-h") {
+      options.help = true;
+    } else if (arg === "--max-pages") {
+      options.maxPages = Number(argv[++i]);
+    } else if (arg === "--concurrency") {
+      options.concurrency = Number(argv[++i]);
+    } else if (arg === "--delay") {
+      options.delayMs = Number(argv[++i]);
+    } else if (arg === "--timeout") {
+      options.timeoutMs = Number(argv[++i]);
+    } else if (arg === "--sitemaps") {
+      options.includeSitemaps = true;
+    } else if (arg === "--all-origins") {
+      options.sameOrigin = false;
+    } else if (arg === "--jsonl") {
+      options.jsonl = true;
+    } else if (arg === "--output" || arg === "-o") {
+      options.output = argv[++i];
+    } else if (arg === "--user-agent") {
+      options.userAgent = argv[++i];
+    } else if (arg.startsWith("-")) {
+      throw new Error(`Unknown option: ${arg}`);
+    } else {
+      urls.push(arg);
+    }
+  }
+
+  return { urls, options };
+}
+
+function writeOutput(pages, options) {
+  const body = options.jsonl
+    ? pages.map((page) => JSON.stringify(page)).join("\n") + "\n"
+    : JSON.stringify(pages, null, 2) + "\n";
+
+  if (!options.output) {
+    process.stdout.write(body);
+    return;
+  }
+  const stream = createWriteStream(options.output, { encoding: "utf8" });
+  stream.end(body);
+}
+
+async function main() {
+  const { urls, options } = readArgs(process.argv.slice(2));
+  if (options.help) {
+    usage();
+    return;
+  }
+  if (!urls.length) {
+    usage();
+    process.exitCode = 1;
+    return;
+  }
+
+  const pages = await crawl({
+    seeds: urls,
+    maxPages: options.maxPages,
+    concurrency: options.concurrency,
+    delayMs: options.delayMs,
+    timeoutMs: options.timeoutMs,
+    includeSitemaps: options.includeSitemaps,
+    sameOrigin: options.sameOrigin,
+    userAgent: options.userAgent,
+    onError: (failure) => {
+      process.stderr.write(`crawl warning: ${failure.url}: ${failure.error}\n`);
+    }
+  });
+
+  writeOutput(pages, options);
+}
+
+main().catch((error) => {
+  process.stderr.write(`${error.stack || error.message || String(error)}\n`);
+  process.exitCode = 1;
+});

package/bin/maqam.js

@@ -0,0 +1,22 @@
+#!/usr/bin/env node
+import { startMaqamServer } from "../src/maqam/server.js";
+
+function readPort(argv) {
+  const index = argv.indexOf("--port");
+  if (index === -1) return undefined;
+  return Number(argv[index + 1]);
+}
+
+if (process.argv.includes("--help") || process.argv.includes("-h")) {
+  console.log(`
+Maqam
+
+Usage:
+  maqam [--port 8787]
+
+Starts the local Maqam enterprise agent framework console.
+`);
+  process.exit(0);
+}
+
+startMaqamServer({ port: readPort(process.argv.slice(2)) });

package/package.json

@@ -0,0 +1,74 @@
+{
+  "name": "maqam",
+  "version": "0.1.0",
+  "description": "Maqam is an MIT-licensed Ajnas agent framework for governed workflows, policy, evidence, skills, and crawler-backed research.",
+  "license": "MIT",
+  "author": {
+    "name": "Ajnas",
+    "email": "ajnasnb@gmail.com"
+  },
+  "type": "module",
+  "bin": {
+    "maqam": "bin/maqam.js",
+    "maqam-crawl": "bin/ajnas-crawl.js",
+    "ajnas-crawl": "bin/ajnas-crawl.js",
+    "ajnas-agent-crawler": "bin/ajnas-crawl.js"
+  },
+  "main": "src/index.js",
+  "exports": {
+    ".": "./src/index.js"
+  },
+  "files": [
+    "app/",
+    "bin/",
+    "src/",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "node --test",
+    "start": "node bin/maqam.js",
+    "crawl": "node bin/ajnas-crawl.js",
+    "maqam": "node bin/maqam.js"
+  },
+  "keywords": [
+    "maqam",
+    "agent-framework",
+    "agent-runtime",
+    "governance",
+    "policy-engine",
+    "evidence-ledger",
+    "provenance",
+    "skills",
+    "tool-orchestration",
+    "human-approval",
+    "crawler",
+    "agent",
+    "web-crawler",
+    "scraper",
+    "robots.txt",
+    "sitemap",
+    "markdown",
+    "jsonl",
+    "research"
+  ],
+  "dependencies": {
+    "cheerio": "^1.0.0",
+    "robots-parser": "^3.0.1",
+    "turndown": "^7.2.0"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/AjnasNB/maqam.git"
+  },
+  "bugs": {
+    "url": "https://github.com/AjnasNB/maqam/issues"
+  },
+  "homepage": "https://github.com/AjnasNB/maqam#readme",
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/framework/errors.js

@@ -0,0 +1,35 @@
+export class AjnasFrameworkError extends Error {
+  constructor(message, options = {}) {
+    super(message, options.cause ? { cause: options.cause } : undefined);
+    this.name = new.target.name;
+    this.code = options.code || "AJNAS_FRAMEWORK_ERROR";
+    this.details = options.details || {};
+  }
+}
+
+export class PolicyDeniedError extends AjnasFrameworkError {
+  constructor(message, options = {}) {
+    super(message, {
+      ...options,
+      code: options.code || "POLICY_DENIED"
+    });
+  }
+}
+
+export class ApprovalRequiredError extends AjnasFrameworkError {
+  constructor(message, options = {}) {
+    super(message, {
+      ...options,
+      code: options.code || "APPROVAL_REQUIRED"
+    });
+  }
+}
+
+export function toErrorRecord(error) {
+  return {
+    name: error?.name || "Error",
+    code: error?.code || "ERROR",
+    message: error?.message || String(error),
+    details: error?.details || {}
+  };
+}

package/src/framework/evidence-ledger.js

@@ -0,0 +1,72 @@
+import { createHash } from "node:crypto";
+
+function sha256(value) {
+  return `sha256:${createHash("sha256").update(value).digest("hex")}`;
+}
+
+function clampConfidence(value) {
+  const number = Number(value);
+  if (!Number.isFinite(number)) return 0.5;
+  return Math.max(0, Math.min(1, number));
+}
+
+export class EvidenceLedger {
+  constructor(options = {}) {
+    this.clock = options.clock || (() => new Date());
+    this.evidence = [];
+    this.claims = [];
+  }
+
+  addEvidence(input = {}) {
+    const record = {
+      evidenceId: input.evidenceId || `ev_${this.evidence.length + 1}`,
+      runId: input.runId || null,
+      taskId: input.taskId || null,
+      sourceType: input.sourceType || "unknown",
+      source: input.source || "unknown",
+      retrievedAt: input.retrievedAt || this.clock().toISOString(),
+      excerpt: input.excerpt || "",
+      hash: input.hash || sha256(`${input.source || ""}\n${input.excerpt || ""}`),
+      tool: input.tool || null,
+      confidence: clampConfidence(input.confidence)
+    };
+    this.evidence.push(record);
+    return record;
+  }
+
+  addClaim(input = {}) {
+    const claim = {
+      claimId: input.claimId || `claim_${this.claims.length + 1}`,
+      runId: input.runId || null,
+      taskId: input.taskId || null,
+      text: input.text || "",
+      evidenceIds: input.evidenceIds || [],
+      confidence: clampConfidence(input.confidence)
+    };
+    this.claims.push(claim);
+    return claim;
+  }
+
+  listEvidence() {
+    return [...this.evidence];
+  }
+
+  listClaims() {
+    return [...this.claims];
+  }
+
+  unsupportedClaims() {
+    const known = new Set(this.evidence.map((record) => record.evidenceId));
+    return this.claims.filter((claim) => {
+      return !claim.evidenceIds.length || claim.evidenceIds.some((id) => !known.has(id));
+    });
+  }
+
+  toJSON() {
+    return {
+      evidence: this.listEvidence(),
+      claims: this.listClaims(),
+      unsupportedClaims: this.unsupportedClaims()
+    };
+  }
+}