maqam 0.1.0

package/src/framework/policy.js

@@ -0,0 +1,119 @@
+const DEFAULT_LIMITS = {
+  maxToolCalls: 100,
+  maxRuntimeMs: 600_000
+};
+
+function asSet(values = []) {
+  return new Set(values.filter(Boolean));
+}
+
+function isHttpUrl(value) {
+  try {
+    const url = new URL(value);
+    return url.protocol === "http:" || url.protocol === "https:";
+  } catch {
+    return false;
+  }
+}
+
+function collectUrls(value, urls = []) {
+  if (!value) return urls;
+  if (typeof value === "string") {
+    if (isHttpUrl(value)) urls.push(value);
+    return urls;
+  }
+  if (Array.isArray(value)) {
+    for (const item of value) collectUrls(item, urls);
+    return urls;
+  }
+  if (typeof value === "object") {
+    for (const item of Object.values(value)) collectUrls(item, urls);
+  }
+  return urls;
+}
+
+function toOrigin(value) {
+  try {
+    return new URL(value).origin;
+  } catch {
+    return value;
+  }
+}
+
+export class PolicyEngine {
+  constructor(config = {}) {
+    this.allowedTools = asSet(config.allowedTools);
+    this.deniedTools = asSet(config.deniedTools);
+    this.allowedOrigins = asSet((config.allowedOrigins || []).map(toOrigin));
+    this.deniedOrigins = asSet((config.deniedOrigins || []).map(toOrigin));
+    this.approvalRequiredTools = asSet(config.approvalRequiredTools);
+    this.defaultLimits = {
+      ...DEFAULT_LIMITS,
+      ...(config.defaultLimits || {}),
+      ...(config.maxToolCalls ? { maxToolCalls: config.maxToolCalls } : {})
+    };
+  }
+
+  evaluateGoal(goal = {}) {
+    for (const tool of goal.allowedTools || []) {
+      if (!this.isToolAllowed(tool)) {
+        return this.decision("deny", `Tool '${tool}' is not allowed for this tenant.`);
+      }
+    }
+
+    for (const origin of goal.allowedOrigins || []) {
+      if (!this.isOriginAllowed(toOrigin(origin))) {
+        return this.decision("deny", `Origin '${origin}' is not allowed for this tenant.`);
+      }
+    }
+
+    return this.decision("allow", "Goal is allowed by policy.", {
+      limits: {
+        ...this.defaultLimits,
+        ...(goal.budget || {})
+      }
+    });
+  }
+
+  authorizeToolCall({ toolName, input = {} } = {}) {
+    if (!this.isToolAllowed(toolName)) {
+      return this.decision("deny", `Tool '${toolName}' is not allowed.`);
+    }
+
+    if (this.approvalRequiredTools.has(toolName)) {
+      return this.decision("needs_approval", `Tool '${toolName}' requires approval.`, {
+        requiredApprovals: [`tool:${toolName}`]
+      });
+    }
+
+    const origins = [...new Set(collectUrls(input).map(toOrigin))];
+    for (const origin of origins) {
+      if (!this.isOriginAllowed(origin)) {
+        return this.decision("deny", `URL origin '${origin}' is not allowed.`);
+      }
+    }
+
+    return this.decision("allow", "Tool call is allowed.");
+  }
+
+  isToolAllowed(toolName) {
+    if (!toolName || this.deniedTools.has(toolName)) return false;
+    return this.allowedTools.size === 0 || this.allowedTools.has(toolName);
+  }
+
+  isOriginAllowed(origin) {
+    if (!origin || this.deniedOrigins.has(origin)) return false;
+    return this.allowedOrigins.size === 0 || this.allowedOrigins.has(origin);
+  }
+
+  decision(status, reason, extra = {}) {
+    return {
+      status,
+      reason,
+      limits: extra.limits || { ...this.defaultLimits },
+      requiredApprovals: extra.requiredApprovals || []
+    };
+  }
+}
+
+export { collectUrls };

package/src/framework/research-workflow.js

@@ -0,0 +1,80 @@
+function candidateNameFromPage(page) {
+  if (page.title) return page.title.replace(/\s*[-|].*$/, "").trim();
+  const url = new URL(page.url);
+  const parts = url.pathname.split("/").filter(Boolean);
+  return parts.at(-1) || url.hostname;
+}
+
+export function createResearchWorkflow(options = {}) {
+  const seeds = options.seeds || [];
+  const maxPages = options.maxPages || 10;
+
+  return {
+    name: "enterprise_research",
+    tasks: [
+      {
+        id: "collect_sources",
+        retries: 1,
+        run: async (context) => {
+          const pages = await context.tools.call("crawler", {
+            seeds,
+            maxPages,
+            sameOrigin: options.sameOrigin ?? true,
+            includeSitemaps: options.includeSitemaps ?? false
+          }, context);
+
+          const evidenceIds = pages.map((page) => {
+            const evidence = context.evidence.addEvidence({
+              runId: context.runId,
+              taskId: "collect_sources",
+              sourceType: "url",
+              source: page.url,
+              excerpt: page.text || page.markdown || page.title || "",
+              tool: "crawler",
+              confidence: page.status === 200 ? 0.85 : 0.5
+            });
+            return evidence.evidenceId;
+          });
+
+          return { pages, evidenceIds };
+        }
+      },
+      {
+        id: "synthesize_report",
+        run: async (context) => {
+          const collected = context.outputs.collect_sources || { pages: [], evidenceIds: [] };
+          const candidates = collected.pages.map((page, index) => {
+            const evidenceId = collected.evidenceIds[index];
+            const name = candidateNameFromPage(page);
+            context.evidence.addClaim({
+              runId: context.runId,
+              taskId: "synthesize_report",
+              text: `${name} was inspected from ${page.url}.`,
+              evidenceIds: [evidenceId],
+              confidence: 0.8
+            });
+
+            return {
+              name,
+              url: page.url,
+              whatItDoes: page.description || page.text?.slice(0, 240) || page.title || "",
+              whyUseful: "Potential source or reference for enterprise agent framework capabilities.",
+              risks: ["Requires license and maintenance review before reuse."],
+              recommendation: "inspiration_first",
+              evidenceIds: [evidenceId]
+            };
+          });
+
+          return { candidates };
+        }
+      },
+      {
+        id: "quality_checks",
+        run: async (context) => ({
+          unsupportedClaims: context.evidence.unsupportedClaims(),
+          evidenceCount: context.evidence.listEvidence().length
+        })
+      }
+    ]
+  };
+}

package/src/framework/runtime.js

@@ -0,0 +1,101 @@
+import { toErrorRecord } from "./errors.js";
+
+function withTimeout(promise, timeoutMs, taskId) {
+  if (!timeoutMs) return promise;
+  let timer;
+  const timeout = new Promise((_, reject) => {
+    timer = setTimeout(() => reject(new Error(`Task '${taskId}' timed out after ${timeoutMs}ms.`)), timeoutMs);
+  });
+  return Promise.race([promise, timeout]).finally(() => clearTimeout(timer));
+}
+
+export class AgentRuntime {
+  constructor(options = {}) {
+    this.policyEngine = options.policyEngine || null;
+    this.evidenceLedger = options.evidenceLedger || null;
+    this.toolGateway = options.toolGateway || null;
+    this.clock = options.clock || (() => new Date());
+  }
+
+  async runWorkflow(workflow, goal = {}) {
+    const runId = goal.runId || `run_${this.clock().getTime()}`;
+    const preflight = this.policyEngine?.evaluateGoal(goal) || {
+      status: "allow",
+      reason: "No policy engine configured.",
+      limits: {}
+    };
+
+    if (preflight.status !== "allow") {
+      return {
+        runId,
+        status: preflight.status,
+        reason: preflight.reason,
+        trace: [],
+        outputs: {}
+      };
+    }
+
+    const context = {
+      runId,
+      goal,
+      outputs: {},
+      evidence: this.evidenceLedger,
+      tools: this.toolGateway,
+      trace: []
+    };
+
+    for (const task of workflow.tasks || []) {
+      const maxAttempts = 1 + (task.retries || 0);
+      let lastError = null;
+
+      for (let attempt = 1; attempt <= maxAttempts; attempt += 1) {
+        const startedAt = this.clock().toISOString();
+        try {
+          const output = await withTimeout(
+            Promise.resolve(task.run(context)),
+            task.timeoutMs,
+            task.id
+          );
+          context.outputs[task.id] = output;
+          context.trace.push({
+            taskId: task.id,
+            status: "completed",
+            attempt,
+            startedAt,
+            finishedAt: this.clock().toISOString()
+          });
+          lastError = null;
+          break;
+        } catch (error) {
+          lastError = error;
+          context.trace.push({
+            taskId: task.id,
+            status: "failed",
+            attempt,
+            startedAt,
+            finishedAt: this.clock().toISOString(),
+            error: toErrorRecord(error)
+          });
+        }
+      }
+
+      if (lastError) {
+        return {
+          runId,
+          status: "failed",
+          error: toErrorRecord(lastError),
+          trace: context.trace,
+          outputs: context.outputs
+        };
+      }
+    }
+
+    return {
+      runId,
+      status: "completed",
+      trace: context.trace,
+      outputs: context.outputs,
+      evidence: this.evidenceLedger?.toJSON?.() || null
+    };
+  }
+}

package/src/framework/skill-registry.js

@@ -0,0 +1,52 @@
+function normalizeSkill(input) {
+  if (!input?.id || !input?.name || !input?.version) {
+    throw new TypeError("Skill requires id, name, and version.");
+  }
+  return {
+    id: input.id,
+    name: input.name,
+    version: input.version,
+    triggers: input.triggers || [],
+    capabilities: input.capabilities || [],
+    trustLevel: input.trustLevel || "community",
+    evalScore: Number.isFinite(Number(input.evalScore)) ? Number(input.evalScore) : 0,
+    metadata: input.metadata || {}
+  };
+}
+
+function containsAny(text, values) {
+  const haystack = text.toLowerCase();
+  return values.some((value) => haystack.includes(String(value).toLowerCase()));
+}
+
+export class SkillRegistry {
+  constructor() {
+    this.skills = new Map();
+  }
+
+  register(input) {
+    const skill = normalizeSkill(input);
+    this.skills.set(skill.id, skill);
+    return skill;
+  }
+
+  get(id) {
+    return this.skills.get(id) || null;
+  }
+
+  list() {
+    return [...this.skills.values()];
+  }
+
+  find(query = {}) {
+    const text = query.text || "";
+    const requiredCapabilities = query.capabilities || [];
+    return this.list()
+      .filter((skill) => {
+        const triggerMatch = !text || containsAny(text, skill.triggers);
+        const capabilityMatch = requiredCapabilities.every((capability) => skill.capabilities.includes(capability));
+        return triggerMatch && capabilityMatch;
+      })
+      .sort((a, b) => b.evalScore - a.evalScore || a.id.localeCompare(b.id));
+  }
+}

package/src/framework/tool-gateway.js

@@ -0,0 +1,65 @@
+import { ApprovalRequiredError, PolicyDeniedError } from "./errors.js";
+
+export class ToolGateway {
+  constructor(options = {}) {
+    this.policyEngine = options.policyEngine || null;
+    this.evidenceLedger = options.evidenceLedger || null;
+    this.goal = options.goal || null;
+    this.tools = new Map();
+    this.trace = [];
+  }
+
+  registerTool(name, handler, metadata = {}) {
+    if (!name || typeof handler !== "function") {
+      throw new TypeError("ToolGateway.registerTool requires a name and handler.");
+    }
+    this.tools.set(name, { name, handler, metadata });
+    return this;
+  }
+
+  async call(toolName, input = {}, context = {}) {
+    const tool = this.tools.get(toolName);
+    if (!tool) {
+      throw new PolicyDeniedError(`Tool '${toolName}' is not registered.`, {
+        details: { toolName }
+      });
+    }
+
+    const decision = this.policyEngine?.authorizeToolCall({
+      goal: this.goal,
+      toolName,
+      input,
+      context
+    }) || { status: "allow", reason: "No policy engine configured.", requiredApprovals: [] };
+
+    if (decision.status === "deny") {
+      throw new PolicyDeniedError(decision.reason, {
+        details: { toolName, decision }
+      });
+    }
+
+    if (decision.status === "needs_approval") {
+      throw new ApprovalRequiredError(decision.reason, {
+        details: { toolName, requiredApprovals: decision.requiredApprovals, decision }
+      });
+    }
+
+    const startedAt = new Date().toISOString();
+    const result = await tool.handler(input, {
+      ...context,
+      toolName,
+      evidenceLedger: this.evidenceLedger
+    });
+    const finishedAt = new Date().toISOString();
+
+    this.trace.push({
+      toolName,
+      input,
+      startedAt,
+      finishedAt,
+      decision
+    });
+
+    return result;
+  }
+}