@jstn-sdk/ma 0.1.12 → 0.14.0

package/mcp/local/code-intel.js

@@ -1,39 +1,181 @@
+import { execFile } from "node:child_process";
 import fs from "node:fs/promises";
 import path from "node:path";
+import { promisify } from "node:util";
 import { getRepoRoot } from "../../src/paths.js";
 
-const ignoredDirs = new Set([".git", ".ma", ".omx", "node_modules"]);
+const execFileAsync = promisify(execFile);
+const MAX_SCAN_BYTES = 1024 * 1024;
+const ignoredDirs = new Set([
+  ".git",
+  ".ma",
+  ".omx",
+  ".next",
+  ".turbo",
+  ".vercel",
+  "build",
+  "coverage",
+  "dist",
+  "node_modules",
+]);
+const artifactExtensions = new Set([
+  ".7z",
+  ".bin",
+  ".bmp",
+  ".class",
+  ".dll",
+  ".dylib",
+  ".gif",
+  ".gz",
+  ".ico",
+  ".jar",
+  ".jpeg",
+  ".jpg",
+  ".lockb",
+  ".mp3",
+  ".mp4",
+  ".o",
+  ".pdf",
+  ".png",
+  ".so",
+  ".svg",
+  ".tar",
+  ".tgz",
+  ".wasm",
+  ".webp",
+  ".woff",
+  ".woff2",
+  ".zip",
+  ".zst",
+]);
+const ignoredFiles = new Set([".active"]);
 const codeIntelTools = [
   "code_intel.list_files",
   "code_intel.search_text",
   "code_intel.read_excerpt",
 ];
 
-async function walk(rootDir, currentDir = rootDir, files = [], limit = Number.POSITIVE_INFINITY) {
-  if (files.length >= limit) {
-    return files;
+function normalizeRelative(relativePath) {
+  const normalized = path.posix.normalize(relativePath.replaceAll(path.sep, "/"));
+  if (
+    normalized === "." ||
+    normalized === ".." ||
+    normalized.startsWith("../") ||
+    normalized.includes("\0")
+  ) {
+    throw new Error("code_intel path must stay inside the repository");
   }
+  return normalized;
+}
 
-  const entries = await fs.readdir(currentDir, { withFileTypes: true });
-  for (const entry of entries) {
-    if (files.length >= limit) {
-      break;
-    }
+function isArtifactPath(relativePath) {
+  const segments = relativePath.split("/");
+  return (
+    ignoredFiles.has(segments.at(-1)) ||
+    segments.some((segment) => ignoredDirs.has(segment)) ||
+    artifactExtensions.has(path.extname(relativePath).toLowerCase())
+  );
+}
+
+async function isReadableTextFile(absolutePath) {
+  const stat = await fs.lstat(absolutePath);
+  if (stat.isSymbolicLink()) return false;
+  if (!stat.isFile() || stat.size > MAX_SCAN_BYTES) return false;
+  const sample = await fs.readFile(absolutePath, { encoding: null, flag: "r" });
+  return !sample.subarray(0, Math.min(sample.length, 8192)).includes(0);
+}
+
+async function assertSafeRepoPath(rootDir, relativePath) {
+  let current = rootDir;
+  for (const component of relativePath.split("/")) {
+    current = path.join(current, component);
+    const stat = await fs.lstat(current).catch((error) => {
+      if (error?.code === "ENOENT") return null;
+      throw error;
+    });
+    if (stat?.isSymbolicLink()) throw new Error("code_intel cannot follow symlinks");
+  }
+  return path.join(rootDir, relativePath);
+}
+
+async function listGitFiles(rootDir) {
+  try {
+    const { stdout } = await execFileAsync(
+      "git",
+      ["ls-files", "--cached", "--others", "--exclude-standard", "-z"],
+      { cwd: rootDir, encoding: "buffer", maxBuffer: 4 * 1024 * 1024 },
+    );
+    return stdout
+      .toString("utf8")
+      .split("\0")
+      .filter(Boolean)
+      .map((file) => file.replaceAll("\\", "/"));
+  } catch {
+    return null;
+  }
+}
+
+async function loadFallbackIgnorePatterns(rootDir) {
+  const content = await fs.readFile(path.join(rootDir, ".gitignore"), "utf8").catch(() => "");
+  return content
+    .split("\n")
+    .map((line) => line.trim())
+    .filter((line) => line && !line.startsWith("#") && !line.startsWith("!"));
+}
+
+function isFallbackIgnored(relativePath, patterns) {
+  const normalized = relativePath.split(path.sep).join("/");
+  return patterns.some((pattern) => {
+    const directoryPattern = pattern.endsWith("/") ? pattern.slice(0, -1) : pattern;
+    const escaped = directoryPattern.replace(/[.+^${}()|[\]\\]/g, "\\$&");
+    const expression = escaped
+      .replaceAll("**", ".*")
+      .replaceAll("*", "[^/]*")
+      .replaceAll("?", "[^/]");
+    const matcher = new RegExp(`(?:^|/)${expression}(?:/|$)`);
+    return (
+      matcher.test(normalized) ||
+      (!pattern.includes("/") && new RegExp(`(^|/)${expression}$`).test(normalized))
+    );
+  });
+}
 
+async function walkFallback(rootDir, currentDir = rootDir, files = [], limit = 200, patterns = []) {
+  if (files.length >= limit) return files;
+  const entries = await fs.readdir(currentDir, { withFileTypes: true }).catch(() => []);
+  for (const entry of entries) {
+    if (files.length >= limit) break;
+    const absolutePath = path.join(currentDir, entry.name);
+    const relativePath = path.relative(rootDir, absolutePath);
+    if (isFallbackIgnored(relativePath, patterns)) continue;
     if (entry.isDirectory()) {
-      if (ignoredDirs.has(entry.name)) {
-        continue;
+      if (!ignoredDirs.has(entry.name)) {
+        await walkFallback(rootDir, absolutePath, files, limit, patterns);
       }
-      await walk(rootDir, path.join(currentDir, entry.name), files, limit);
-      continue;
+    } else if (entry.isFile() && !isArtifactPath(relativePath)) {
+      files.push(relativePath.split(path.sep).join("/"));
     }
+  }
+  return files;
+}
 
-    if (!entry.isFile()) {
-      continue;
+async function listSafeFiles(rootDir, limit = 200) {
+  const gitFiles = await listGitFiles(rootDir);
+  const candidates =
+    gitFiles ??
+    (await walkFallback(rootDir, rootDir, [], limit, await loadFallbackIgnorePatterns(rootDir)));
+  const files = [];
+  for (const relativePath of candidates) {
+    if (files.length >= limit) break;
+    const normalized = normalizeRelative(relativePath);
+    if (isArtifactPath(normalized)) continue;
+    try {
+      const absolute = await assertSafeRepoPath(rootDir, normalized);
+      if (await isReadableTextFile(absolute)) files.push(normalized);
+    } catch {
+      // Ignore files that disappear or cannot be inspected.
     }
-    files.push(path.relative(rootDir, path.join(currentDir, entry.name)));
   }
-
   return files;
 }
 
@@ -42,52 +184,49 @@ export function listCodeIntelTools() {
 }
 
 export async function listRepoFiles(limit = 200) {
-  const repoRoot = getRepoRoot();
-  return walk(repoRoot, repoRoot, [], limit);
+  return listSafeFiles(getRepoRoot(), Math.max(1, Math.min(Number(limit) || 200, 2000)));
 }
 
 export async function searchRepoText(query, limit = 20) {
   const repoRoot = getRepoRoot();
   const files = await listRepoFiles(500);
   const matches = [];
-
+  const boundedLimit = Math.max(1, Math.min(Number(limit) || 20, 100));
   for (const relativePath of files) {
-    if (matches.length >= limit) {
-      break;
-    }
-
+    if (matches.length >= boundedLimit) break;
     try {
       const content = await fs.readFile(path.join(repoRoot, relativePath), "utf8");
-      const lines = content.split("\n");
-      lines.forEach((line, index) => {
-        if (matches.length < limit && line.includes(query)) {
+      content.split("\n").forEach((line, index) => {
+        if (matches.length < boundedLimit && line.includes(query)) {
           matches.push({ file: relativePath, line: index + 1, text: line.trim() });
         }
       });
     } catch {
-      // Skip non-text files.
+      // Skip files that disappear or fail the text boundary.
     }
   }
-
   return matches;
 }
 
 export async function readRepoExcerpt(relativePath, line = 1, context = 2) {
   const repoRoot = getRepoRoot();
-  const content = await fs.readFile(path.join(repoRoot, relativePath), "utf8");
+  const normalized = normalizeRelative(relativePath);
+  if (isArtifactPath(normalized))
+    throw new Error("code_intel cannot read generated or binary artifacts");
+  const absolutePath = await assertSafeRepoPath(repoRoot, normalized);
+  if (!(await isReadableTextFile(absolutePath)))
+    throw new Error("code_intel can only read bounded text files");
+  const content = await fs.readFile(absolutePath, "utf8");
+  const safeLine = Math.max(1, Number(line) || 1);
+  const safeContext = Math.max(0, Math.min(Number(context) || 2, 20));
   const lines = content.split("\n");
-  const start = Math.max(0, line - context - 1);
-  const end = Math.min(lines.length, line + context);
-  return lines.slice(start, end).map((text, index) => ({
-    line: start + index + 1,
-    text,
-  }));
+  const start = Math.max(0, safeLine - safeContext - 1);
+  const end = Math.min(lines.length, safeLine + safeContext);
+  return lines.slice(start, end).map((text, index) => ({ line: start + index + 1, text }));
 }
 
 export async function callCodeIntelTool(name, args = {}) {
-  if (name === "code_intel.list_files") {
-    return listRepoFiles(args.limit);
-  }
+  if (name === "code_intel.list_files") return listRepoFiles(args.limit);
   if (name === "code_intel.search_text") {
     if (typeof args.query !== "string" || args.query.trim() === "") {
       throw new Error("code_intel.search_text requires a non-empty query");
@@ -100,7 +239,6 @@ export async function callCodeIntelTool(name, args = {}) {
     }
     return readRepoExcerpt(args.file, args.line, args.context);
   }
-
   throw new Error(`Unknown code_intel tool: ${name}`);
 }
 
@@ -108,6 +246,6 @@ export async function checkCodeIntelCapability() {
   const files = await listRepoFiles(10);
   return {
     ready: files.length > 0,
-    detail: `code intel indexed ${files.length} repo file(s) in the readiness sample`,
+    detail: `code intel indexed ${files.length} bounded text file(s) with Git-ignore and artifact filtering`,
   };
 }

package/mcp/local/context.js

@@ -0,0 +1,180 @@
+import path from "node:path";
+import { loadLearningLoopCore, loadLearningRecords } from "../../src/runtime/learning-loop-core.js";
+import {
+  loadObsidianVaultIndex,
+  loadObsidianVaultOperations,
+} from "../../src/runtime/obsidian-integration-core.js";
+import { resolvePreferences } from "../../src/runtime/preferences.js";
+import { loadProjectIndex } from "../../src/runtime/project-context.js";
+import {
+  loadRuntimeHookReceipts,
+  loadRuntimeHooksAuditLog,
+  loadRuntimeHooksConfig,
+} from "../../src/runtime/signal-hooks.js";
+
+const contextResources = [
+  "context://project-index",
+  "context://learning",
+  "context://obsidian",
+  "context://hooks",
+  "context://freshness",
+  "context://commands",
+  "context://agent-brief",
+  "context://architecture",
+  "context://preferences",
+];
+
+export function listContextResources() {
+  return [...contextResources];
+}
+
+async function readOptional(loader, fallback) {
+  try {
+    return { available: true, data: await loader() };
+  } catch (error) {
+    if (error?.code === "ENOENT") return { available: false, data: fallback };
+    throw error;
+  }
+}
+
+function envelope(resource, result, extra = {}) {
+  const freshness = extra.freshness ?? result.data?.freshness ?? null;
+  return {
+    record_type: `mcp_context:${resource}`,
+    authority: "source_truth",
+    source: "meta-architect-runtime",
+    resource,
+    ...extra,
+    ...result,
+    context: {
+      authority: extra.authority ?? "generated_context",
+      source: "meta-architect-runtime",
+      freshness,
+      provenance: result.data?.sourceFiles?.map((file) => file.path) ?? [],
+    },
+    quality: result.data?.quality ?? extra.quality ?? null,
+  };
+}
+
+export async function readContextResource(uri) {
+  if (uri === "context://project-index") {
+    const result = await readOptional(loadProjectIndex, null);
+    return envelope("project-index", result, {
+      authority: result.available ? "source_truth" : "missing_source_truth",
+      fact_ids: result.data?.facts?.map((fact) => fact.id) ?? [],
+      provenance:
+        result.data?.facts?.map((fact) => ({ id: fact.id, provenance: fact.provenance })) ?? [],
+    });
+  }
+
+  if (uri === "context://learning") {
+    const [core, records] = await Promise.all([
+      readOptional(loadLearningLoopCore, null),
+      readOptional(loadLearningRecords, []),
+    ]);
+    return envelope(
+      "learning",
+      {
+        available: core.available || records.available,
+        data: {
+          core: core.data,
+          records: records.data,
+          failure_records: records.data.filter((record) => Boolean(record.failure_state)),
+        },
+      },
+      {
+        authority: "generated_context",
+        fact_ids: records.data.flatMap((record) => record.fact_ids ?? []),
+      },
+    );
+  }
+
+  if (uri === "context://obsidian") {
+    const [index, operations] = await Promise.all([
+      readOptional(loadObsidianVaultIndex, null),
+      readOptional(loadObsidianVaultOperations, null),
+    ]);
+    return envelope(
+      "obsidian",
+      {
+        available: index.available || operations.available,
+        data: { index: index.data, operations: operations.data },
+      },
+      { authority: "vault_note" },
+    );
+  }
+
+  if (uri === "context://hooks") {
+    const [config, audit, receipts] = await Promise.all([
+      readOptional(loadRuntimeHooksConfig, null),
+      readOptional(loadRuntimeHooksAuditLog, ""),
+      readOptional(loadRuntimeHookReceipts, []),
+    ]);
+    return envelope(
+      "hooks",
+      {
+        available: config.available || audit.available,
+        data: { config: config.data, audit: audit.data, receipts: receipts.data },
+      },
+      { authority: "hook_evidence" },
+    );
+  }
+
+  if (
+    uri === "context://commands" ||
+    uri === "context://agent-brief" ||
+    uri === "context://architecture"
+  ) {
+    const relative = uri.slice("context://".length);
+    const loader = async () => {
+      if (relative === "commands") return readOptional(() => readJsonFile("commands.json"), null);
+      return readOptional(() => readTextFile(`${relative}.md`), "");
+    };
+    const result = await loader();
+    const project = await readOptional(loadProjectIndex, null);
+    return envelope(relative, result, {
+      authority: "generated_context",
+      freshness: { status: "derived", stale: false, source: "project-index" },
+      quality: project.data?.quality ?? null,
+    });
+  }
+
+  if (uri === "context://freshness") {
+    const result = await readOptional(loadProjectIndex, null);
+    return envelope(
+      "freshness",
+      { available: result.available, data: result.data?.freshness ?? null },
+      { authority: "source_truth" },
+    );
+  }
+
+  if (uri === "context://preferences") {
+    const result = await readOptional(resolvePreferences, {});
+    return envelope("preferences", result, { authority: "learning_memory" });
+  }
+
+  throw new Error(`Unknown context resource: ${uri}`);
+}
+
+async function readJsonFile(name) {
+  const { readJson } = await import("../../src/fs-utils.js");
+  return readJson(path.join(process.env.MA_ROOT || process.cwd(), ".ma", "context", name));
+}
+
+async function readTextFile(name) {
+  const fs = await import("node:fs/promises");
+  return fs.readFile(
+    path.join(process.env.MA_ROOT || process.cwd(), ".ma", "context", name),
+    "utf8",
+  );
+}
+
+export async function checkContextCapability() {
+  const project = await readContextResource("context://project-index");
+  return {
+    ready: true,
+    detail: project.available
+      ? `project context loaded with ${project.data.sourceFiles?.length ?? 0} source file(s)`
+      : "project context has not been generated; run ma setup",
+  };
+}

package/mcp/local/memory.js

@@ -1,11 +1,13 @@
+import { loadContinuityGraph, queryContinuityGraph } from "../../src/runtime/continuity-graph.js";
 import {
   loadContinuityIndex,
   loadContinuityNotes,
   storeContinuityNote,
 } from "../../src/runtime/continuity-notes.js";
+import { withMcpWriteGate } from "../../src/runtime/mcp-authority.js";
 
-const memoryResources = ["memory://notes", "memory://index"];
-const memoryTools = ["memory.store_note"];
+const memoryResources = ["memory://notes", "memory://index", "memory://graph"];
+const memoryTools = ["memory.store_note", "memory.query_graph"];
 
 export function listMemoryResources() {
   return [...memoryResources];
@@ -22,19 +24,28 @@ export async function readMemoryResource(uri) {
   if (uri === "memory://index") {
     return loadContinuityIndex();
   }
+  if (uri === "memory://graph") {
+    return loadContinuityGraph();
+  }
 
   throw new Error(`Unknown memory resource: ${uri}`);
 }
 
 export async function callMemoryTool(name, args = {}, options = {}) {
+  if (name === "memory.query_graph") {
+    return queryMemoryGraph(args);
+  }
   if (name !== "memory.store_note") {
     throw new Error(`Unknown memory tool: ${name}`);
   }
 
-  return storeContinuityNote(args.content ?? "", {
-    ...options,
-    actor: "local-capability:memory",
-  });
+  return withMcpWriteGate({ tool: name, options, payload: args }, (metadata) =>
+    storeContinuityNote(args.content ?? "", { ...options, ...metadata }),
+  );
+}
+
+export async function queryMemoryGraph(args = {}) {
+  return queryContinuityGraph(await loadContinuityGraph(), args);
 }
 
 export async function checkMemoryCapability() {

package/mcp/local/quality.js

@@ -0,0 +1,39 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { getRepoRoot } from "../../src/paths.js";
+
+const qualityRoot = () => path.join(getRepoRoot(), ".ma", "quality");
+
+export const qualityResources = ["quality://violations", "quality://kpis"];
+
+export async function readQualityResource(uri) {
+  const file =
+    uri === "quality://violations"
+      ? "violations.json"
+      : uri === "quality://kpis"
+        ? "kpis.json"
+        : null;
+  if (!file) throw new Error(`Unknown quality resource: ${uri}`);
+  try {
+    return JSON.parse(await fs.readFile(path.join(qualityRoot(), file), "utf8"));
+  } catch (error) {
+    if (error.code === "ENOENT") return [];
+    throw error;
+  }
+}
+
+export async function queryQualityStatus() {
+  const [violations, kpis] = await Promise.all([
+    readQualityResource("quality://violations"),
+    readQualityResource("quality://kpis"),
+  ]);
+  return {
+    violations,
+    kpis,
+    passed:
+      violations.length > 0 &&
+      kpis.length > 0 &&
+      violations.every((record) => record.violations?.length === 0) &&
+      kpis.every((record) => record.kpis?.qualityScore >= 60),
+  };
+}

package/mcp/local/state.js

@@ -1,5 +1,6 @@
 import { appendDecision } from "../../src/decision-log.js";
 import { loadManagerRunRegistryOrDefault } from "../../src/runtime/maestro-manager.js";
+import { withMcpWriteGate } from "../../src/runtime/mcp-authority.js";
 import { createRuntimeSummary, loadRuntimeSnapshot } from "../../src/runtime/runtime-state.js";
 import { loadCombinedState, syncStatusUpdates } from "../../src/state-sync.js";
 
@@ -45,15 +46,18 @@ export async function readStateResource(uri) {
 }
 
 export async function callStateTool(name, args = {}, options = {}) {
-  const localOptions = { ...options, actor: "local-capability:_state" };
   if (name === "state.sync_release_status") {
     const statusUpdates = args.statusUpdates ?? args;
-    return syncStatusUpdates(statusUpdates, localOptions);
+    return withMcpWriteGate({ tool: name, options, payload: statusUpdates }, (metadata) =>
+      syncStatusUpdates(statusUpdates, metadata),
+    );
   }
 
   if (name === "state.append_decision") {
     const entry = args.entry ?? args;
-    return appendDecision(entry, localOptions);
+    return withMcpWriteGate({ tool: name, options, payload: entry }, (metadata) =>
+      appendDecision(entry, metadata),
+    );
   }
 
   throw new Error(`Unknown _state tool: ${name}`);

package/mcp/local/team-run.js

@@ -1,4 +1,5 @@
 import fs from "node:fs/promises";
+import { withMcpWriteGate } from "../../src/runtime/mcp-authority.js";
 import {
   controlTask,
   getTask,
@@ -15,7 +16,14 @@ const teamRunResources = [
   "team-run://registry",
   "team-run://mailbox",
 ];
-const teamRunTools = ["team_run.submit_task", "team_run.get_status", "team_run.control_task"];
+const teamRunTools = [
+  "team_run.submit_task",
+  "team_run.get_status",
+  "team_run.list_tasks",
+  "team_run.wait_task",
+  "team_run.control_task",
+];
+const terminalTaskStatuses = new Set(["done", "blocked", "cancelled"]);
 
 export function listTeamRunResources() {
   return [...teamRunResources];
@@ -43,20 +51,64 @@ export async function readTeamRunResource(uri) {
 }
 
 export async function callTeamRunTool(name, args = {}, options = {}) {
-  const localOptions = { ...options, actor: "local-capability:team_run" };
   if (name === "team_run.submit_task") {
-    return submitTask(args.task ?? args, localOptions);
+    const task = args.task ?? args;
+    return withMcpWriteGate({ tool: name, options, payload: task }, (metadata) =>
+      submitTask(task, metadata),
+    );
   }
   if (name === "team_run.get_status") {
     return getTask(args.taskId);
   }
+  if (name === "team_run.list_tasks") {
+    return args.managerOwner === "$maestro" ? listMaestroTasks() : listTasks();
+  }
+  if (name === "team_run.wait_task") {
+    return waitForTask(args.taskId, args);
+  }
   if (name === "team_run.control_task") {
-    return controlTask(args.taskId, args.action, localOptions);
+    return withMcpWriteGate({ tool: name, options, payload: args }, (metadata) =>
+      controlTask(args.taskId, args.action, metadata),
+    );
   }
 
   throw new Error(`Unknown team_run tool: ${name}`);
 }
 
+export async function waitForTask(taskId, { timeoutMs = 1_000, pollMs = 50 } = {}) {
+  if (typeof taskId !== "string" || taskId.trim() === "") {
+    throw new Error("team_run.wait_task requires a taskId");
+  }
+
+  const boundedTimeoutMs = Math.max(0, Math.min(Number(timeoutMs) || 0, 30_000));
+  const boundedPollMs = Math.max(10, Math.min(Number(pollMs) || 50, 1_000));
+  const startedAt = Date.now();
+
+  while (Date.now() - startedAt <= boundedTimeoutMs) {
+    const task = await getTask(taskId);
+    if (terminalTaskStatuses.has(task.status)) {
+      return {
+        record_type: "team_run_wait_result",
+        terminal: true,
+        timed_out: false,
+        task,
+      };
+    }
+
+    if (boundedTimeoutMs === 0) {
+      break;
+    }
+    await new Promise((resolve) => setTimeout(resolve, boundedPollMs));
+  }
+
+  return {
+    record_type: "team_run_wait_result",
+    terminal: false,
+    timed_out: true,
+    task: await getTask(taskId),
+  };
+}
+
 export async function checkTeamRunCapability() {
   const registry = await readTeamRunResource("team-run://registry");
   return {

package/mcp/local-capabilities.json

@@ -51,6 +51,15 @@
       "module": "./local/playbooks.js",
       "readinessCheck": "checkPlaybooksCapability",
       "seededByBootstrap": true
+    },
+    {
+      "kind": "local-capability",
+      "capability": "context",
+      "transport": "inproc",
+      "module": "./local/context.js",
+      "readinessCheck": "checkContextCapability",
+      "seededByBootstrap": true,
+      "authorityMode": "read-only-evidence"
     }
   ]
 }