mop-agent 0.1.0

package/packages/flow-connector/src/tools.ts

@@ -0,0 +1,198 @@
+/**
+ * Tool request handler (AGENT -> FLOW).
+ *
+ * THE capability guard. FLOW is the source of truth for permissions — even if the
+ * AGENT claims a write was "approved", FLOW re-checks the capability (and, for
+ * writes, a valid session) before doing anything. Defense in depth.
+ */
+import { readFile, writeFile, mkdir, appendFile, readdir, stat } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import {
+  DEFAULT_EXECUTION_POLICY,
+  isReadTool,
+  TOOL_CAPABILITY,
+  type Capabilities,
+  type ExecutionPolicy,
+  type McpToolName,
+} from "@mop/link-protocol";
+import { runShell } from "./exec.js";
+
+export type ToolContext = {
+  projectRoot: string;
+  capabilities: Capabilities;
+  /** Hook into the real .MOP session check (v1.2.0). Returns true if actor holds a valid session. */
+  hasValidSession?: (actor?: string) => Promise<boolean> | boolean;
+  /** Required for run_shell / edit_code; defaults to host backend. */
+  execution?: ExecutionPolicy;
+};
+
+export class CapabilityError extends Error {}
+
+export async function handleToolRequest(
+  tool: McpToolName,
+  args: Record<string, unknown>,
+  ctx: ToolContext,
+): Promise<unknown> {
+  // 1) Guard
+  if (!isReadTool(tool)) {
+    const cap = TOOL_CAPABILITY[tool as keyof typeof TOOL_CAPABILITY];
+    if (!cap || !ctx.capabilities[cap]) {
+      throw new CapabilityError(`capability_denied:${cap ?? tool}`);
+    }
+    const ok = ctx.hasValidSession ? await ctx.hasValidSession(args.actor as string | undefined) : true;
+    if (!ok) throw new CapabilityError("no_valid_session");
+  }
+
+  // 2) Dispatch
+  switch (tool) {
+    case "get_project_state":
+      return readJson(join(ctx.projectRoot, ".MOP", "STATE.json"));
+    case "list_memory":
+      return listMemory(ctx.projectRoot, Number(args.limit ?? 50));
+    case "read_artifact":
+      return readText(join(ctx.projectRoot, ".MOP", "artifacts", String(args.path)));
+    case "list_artifacts":
+      return listArtifacts(ctx.projectRoot);
+    case "workflow_status":
+      return workflowStatus(ctx.projectRoot);
+    case "search_project_context":
+      return searchContext(ctx.projectRoot, String(args.query ?? ""));
+    case "append_memory":
+      return appendMemory(ctx.projectRoot, args);
+    case "write_artifact":
+      return writeArtifact(ctx.projectRoot, String(args.path), String(args.content));
+    case "workflow_next":
+      return { note: "TODO: advance workflow via mop-core" };
+    case "run_shell": {
+      // Reaches here only if capabilities.runShell is granted (see §9.1).
+      const policy = ctx.execution ?? DEFAULT_EXECUTION_POLICY;
+      return runShell(String(args.command ?? ""), ctx.projectRoot, policy);
+    }
+    case "edit_code":
+      // Reaches here only if capabilities.editCode is granted.
+      return editCode(ctx.projectRoot, String(args.path), String(args.content));
+    default:
+      throw new CapabilityError(`unknown_tool:${tool}`);
+  }
+}
+
+// --- helpers -------------------------------------------------------------
+
+async function readJson(p: string): Promise<unknown> {
+  if (!existsSync(p)) return {};
+  return JSON.parse(await readFile(p, "utf8"));
+}
+
+async function readText(p: string): Promise<string> {
+  return readFile(p, "utf8");
+}
+
+async function listMemory(projectRoot: string, limit: number): Promise<unknown[]> {
+  const dir = join(projectRoot, ".MOP", "memory");
+  if (!existsSync(dir)) return [];
+  const { readdir } = await import("node:fs/promises");
+  const files = (await readdir(dir)).filter((f) => f.endsWith(".jsonl")).sort().reverse();
+  const out: unknown[] = [];
+  for (const f of files) {
+    const raw = await readFile(join(dir, f), "utf8");
+    for (const line of raw.split("\n").reverse()) {
+      const t = line.trim();
+      if (!t) continue;
+      try {
+        out.push(JSON.parse(t));
+      } catch {
+        /* skip */
+      }
+      if (out.length >= limit) return out;
+    }
+  }
+  return out;
+}
+
+async function appendMemory(projectRoot: string, args: Record<string, unknown>): Promise<{ ok: true; id: string }> {
+  const now = new Date();
+  const id = `mem-${now.getTime().toString(36)}-${Math.random().toString(16).slice(2, 6)}`;
+  const entry = {
+    id,
+    at: now.getTime(),
+    actor: args.actor ?? "agent",
+    kind: args.kind ?? "conversation",
+    summary: String(args.summary ?? ""),
+    body: args.body,
+  };
+  const file = join(
+    projectRoot,
+    ".MOP",
+    "memory",
+    `${now.getUTCFullYear()}-${String(now.getUTCMonth() + 1).padStart(2, "0")}.jsonl`,
+  );
+  await mkdir(dirname(file), { recursive: true });
+  await appendFile(file, JSON.stringify(entry) + "\n", "utf8");
+  return { ok: true, id };
+}
+
+async function writeArtifact(projectRoot: string, relPath: string, content: string): Promise<{ ok: true; path: string }> {
+  const p = join(projectRoot, ".MOP", "artifacts", relPath);
+  await mkdir(dirname(p), { recursive: true });
+  await writeFile(p, content, "utf8");
+  return { ok: true, path: relPath };
+}
+
+async function listArtifacts(projectRoot: string): Promise<Array<{ path: string; updatedAt: number; size: number }>> {
+  const dir = join(projectRoot, ".MOP", "artifacts");
+  if (!existsSync(dir)) return [];
+  const out: Array<{ path: string; updatedAt: number; size: number }> = [];
+  const walk = async (d: string, base: string): Promise<void> => {
+    for (const name of await readdir(d)) {
+      const full = join(d, name);
+      const s = await stat(full);
+      if (s.isDirectory()) await walk(full, join(base, name));
+      else out.push({ path: join(base, name), updatedAt: s.mtimeMs, size: s.size });
+    }
+  };
+  await walk(dir, "");
+  return out;
+}
+
+async function workflowStatus(projectRoot: string): Promise<unknown> {
+  const p = join(projectRoot, ".MOP", "STATE.json");
+  if (!existsSync(p)) return { workflow: null };
+  const state = JSON.parse(await readFile(p, "utf8")) as { workflow?: unknown };
+  return { workflow: state.workflow ?? null };
+}
+
+async function searchContext(projectRoot: string, query: string): Promise<Array<{ id: string; summary: string; score: number }>> {
+  const terms = query.toLowerCase().split(/\W+/).filter((t) => t.length >= 2);
+  if (!terms.length) return [];
+  const dir = join(projectRoot, ".MOP", "memory");
+  if (!existsSync(dir)) return [];
+  const hits: Array<{ id: string; summary: string; score: number }> = [];
+  for (const f of (await readdir(dir)).filter((f) => f.endsWith(".jsonl"))) {
+    for (const line of (await readFile(join(dir, f), "utf8")).split("\n")) {
+      const t = line.trim();
+      if (!t) continue;
+      try {
+        const m = JSON.parse(t) as { id: string; summary?: string; body?: string };
+        const hay = `${m.summary ?? ""} ${m.body ?? ""}`.toLowerCase();
+        const score = terms.reduce((s, term) => s + (hay.includes(term) ? 1 : 0), 0);
+        if (score > 0) hits.push({ id: m.id, summary: m.summary ?? "", score });
+      } catch {
+        /* skip */
+      }
+    }
+  }
+  return hits.sort((a, b) => b.score - a.score).slice(0, 20);
+}
+
+/** edit_code: write a project source file, refusing paths that escape the project root. */
+async function editCode(projectRoot: string, relPath: string, content: string): Promise<{ ok: true; path: string }> {
+  const root = resolve(projectRoot);
+  const target = resolve(root, relPath);
+  if (target !== root && !target.startsWith(root + (process.platform === "win32" ? "\\" : "/"))) {
+    throw new CapabilityError("path_escapes_project_root");
+  }
+  await mkdir(dirname(target), { recursive: true });
+  await writeFile(target, content, "utf8");
+  return { ok: true, path: relPath };
+}

package/packages/flow-connector/tsconfig.json

@@ -0,0 +1,10 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "rootDir": ".",
+    "noEmit": true,
+    "lib": ["ES2022"],
+    "types": ["node"]
+  },
+  "include": ["src/**/*", "bin/**/*"]
+}

package/packages/link-protocol/package.json

@@ -0,0 +1,17 @@
+{
+  "name": "@mop/link-protocol",
+  "version": "0.0.1",
+  "description": "Shared types + message schemas for the MOP-AGENT <-> MOP-FLOW link.",
+  "type": "module",
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit"
+  },
+  "devDependencies": {
+    "typescript": "^5.5.0"
+  }
+}

package/packages/link-protocol/src/index.ts

@@ -0,0 +1,245 @@
+/**
+ * @mop/link-protocol
+ *
+ * Shared types and message schemas for the MOP-AGENT <-> MOP-FLOW link.
+ * Imported by both `apps/web` (AGENT side) and `packages/flow-connector` (FLOW side)
+ * so the wire contract stays in exactly one place.
+ *
+ * Transport: FLOW dials OUT to AGENT over WSS (reverse tunnel). See PRD §3 / FLOW §4.
+ */
+
+export const LINK_PROTOCOL_VERSION = "1.0" as const;
+
+/** Default WSS path the AGENT exposes for FLOW connections. */
+export const LINK_WS_PATH = "/link" as const;
+
+// ---------------------------------------------------------------------------
+// Capabilities — what an AGENT is allowed to do against a linked project.
+// Enforced FLOW-side (defense in depth); AGENT can only request.
+// ---------------------------------------------------------------------------
+
+export type Capabilities = {
+  readMemory: boolean;
+  writeMemory: boolean;
+  readArtifacts: boolean;
+  writeArtifacts: boolean;
+  runWorkflow: boolean;
+  runShell: boolean;
+  editCode: boolean;
+};
+
+/** Where capability-gated execution (run_shell / edit_code) runs (FLOW side). */
+export type ExecutionBackend = "host" | "docker" | "ssh";
+
+export type ExecutionPolicy = {
+  backend: ExecutionBackend;
+  /** "always" = every exec needs owner approval (default); "never" is dangerous. */
+  approval?: "always" | "trusted" | "never";
+  docker?: { image: string; network?: string };
+  ssh?: { host: string; user: string; cwd?: string };
+  /** hard ceiling per command (ms) */
+  timeoutMs?: number;
+};
+
+export const DEFAULT_EXECUTION_POLICY: ExecutionPolicy = {
+  backend: "host",
+  approval: "always",
+  timeoutMs: 60_000,
+};
+
+/** Safe defaults: read freely, controlled writes, no shell/code edits. */
+export const DEFAULT_CAPABILITIES: Capabilities = {
+  readMemory: true,
+  writeMemory: true,
+  readArtifacts: true,
+  writeArtifacts: true,
+  runWorkflow: true,
+  runShell: false,
+  editCode: false,
+};
+
+// ---------------------------------------------------------------------------
+// Project manifest — sent FLOW -> AGENT at pairing time.
+// ---------------------------------------------------------------------------
+
+export type Platform = "win32" | "linux" | "darwin" | string;
+
+export type ProjectManifest = {
+  projectId: string;
+  name: string;
+  mopFlowVersion: string;
+  platform: Platform;
+  workflow?: {
+    currentPhase?: string;
+    profile?: string;
+  };
+  capabilities: Capabilities;
+};
+
+// ---------------------------------------------------------------------------
+// Brain payload types (mirrored on the AGENT side).
+// ---------------------------------------------------------------------------
+
+export type MemoryKind =
+  | "decision"
+  | "conversation"
+  | "artifact"
+  | "workflow"
+  | "problem"
+  | "fix"
+  | "preference"
+  | "skill";
+
+export type MemoryEntry = {
+  id: string;
+  kind: MemoryKind | string;
+  summary: string;
+  body?: string;
+  actor?: string;
+  /** epoch millis */
+  at: number;
+  /** episodic memory is private by default (judgment layer) */
+  private?: boolean;
+  tags?: string[];
+};
+
+export type ArtifactRef = {
+  path: string;
+  title?: string;
+  /** epoch millis */
+  updatedAt: number;
+};
+
+// ---------------------------------------------------------------------------
+// MCP tool surface FLOW exposes to AGENT (over the live link).
+// ---------------------------------------------------------------------------
+
+export type McpReadTool =
+  | "get_project_state"
+  | "list_artifacts"
+  | "read_artifact"
+  | "list_memory"
+  | "workflow_status"
+  | "search_project_context";
+
+export type McpWriteTool =
+  | "write_artifact"
+  | "append_memory"
+  | "workflow_next";
+
+/** Future, capability-gated, off by default. */
+export type McpDangerousTool = "run_shell" | "edit_code";
+
+export type McpToolName = McpReadTool | McpWriteTool | McpDangerousTool;
+
+/** Maps each write/dangerous tool to the capability it requires. */
+export const TOOL_CAPABILITY: Record<McpWriteTool | McpDangerousTool, keyof Capabilities> = {
+  write_artifact: "writeArtifacts",
+  append_memory: "writeMemory",
+  workflow_next: "runWorkflow",
+  run_shell: "runShell",
+  edit_code: "editCode",
+};
+
+export const READ_TOOLS: ReadonlySet<string> = new Set<McpReadTool>([
+  "get_project_state",
+  "list_artifacts",
+  "read_artifact",
+  "list_memory",
+  "workflow_status",
+  "search_project_context",
+]);
+
+// ---------------------------------------------------------------------------
+// Wire messages (both directions over the WSS link).
+// `t` is the discriminator.
+// ---------------------------------------------------------------------------
+
+export type HelloMessage = {
+  t: "hello";
+  capabilities: Capabilities;
+  /** epoch millis on the AGENT */
+  serverTime: number;
+  protocolVersion: typeof LINK_PROTOCOL_VERSION;
+};
+
+export type SnapshotPushMessage = {
+  t: "snapshot.push";
+  projectId: string;
+  /** redacted STATE.json (secrets stripped FLOW-side) */
+  state: unknown;
+  memory: MemoryEntry[];
+  artifacts: ArtifactRef[];
+};
+
+/** AGENT -> FLOW: request a tool call. */
+export type ReqMessage = {
+  t: "req";
+  id: string;
+  tool: McpToolName;
+  args: Record<string, unknown>;
+};
+
+/** FLOW -> AGENT: response to a `req`. */
+export type ResMessage = {
+  t: "res";
+  id: string;
+  ok: boolean;
+  data?: unknown;
+  error?: string;
+};
+
+/** FLOW -> AGENT: spontaneous events (memory changed, workflow advanced, etc.). */
+export type EventMessage = {
+  t: "event";
+  name: string;
+  payload: unknown;
+};
+
+export type PingMessage = { t: "ping" };
+export type PongMessage = { t: "pong" };
+
+export type LinkMessage =
+  | HelloMessage
+  | SnapshotPushMessage
+  | ReqMessage
+  | ResMessage
+  | EventMessage
+  | PingMessage
+  | PongMessage;
+
+// ---------------------------------------------------------------------------
+// Pairing (HTTP, before the WSS link is established).
+// ---------------------------------------------------------------------------
+
+/** FLOW -> AGENT  POST /api/link/pair */
+export type PairRequest = {
+  code: string;
+  manifest: ProjectManifest;
+};
+
+/** AGENT -> FLOW  response */
+export type PairResponse = {
+  projectId: string;
+  /** bearer token used for the WSS Authorization header; stored in .MOP/link.json */
+  linkToken: string;
+  wsUrl: string;
+};
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+/** Narrowing helper for received frames. */
+export function parseLinkMessage(raw: string): LinkMessage {
+  const msg = JSON.parse(raw) as LinkMessage;
+  if (typeof (msg as { t?: unknown }).t !== "string") {
+    throw new Error("invalid link message: missing discriminator `t`");
+  }
+  return msg;
+}
+
+/** True if a tool is a read-only tool (no capability required). */
+export function isReadTool(tool: string): boolean {
+  return READ_TOOLS.has(tool);
+}

package/packages/link-protocol/tsconfig.json

@@ -0,0 +1,10 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "dist",
+    "noEmit": true,
+    "lib": ["ES2022"]
+  },
+  "include": ["src/**/*"]
+}

package/tsconfig.base.json

@@ -0,0 +1,18 @@
+{
+  "$schema": "https://json.schemastore.org/tsconfig",
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "lib": ["ES2022", "DOM", "DOM.Iterable"],
+    "strict": true,
+    "noUncheckedIndexedAccess": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "declaration": false,
+    "sourceMap": true
+  }
+}