@nkmc/agent-fs 0.1.0

package/dist/index.cjs

@@ -0,0 +1,1278 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  AgentFs: () => AgentFs,
+  HttpBackend: () => HttpBackend,
+  JsonRpcTransport: () => JsonRpcTransport,
+  MountResolver: () => MountResolver,
+  RpcBackend: () => RpcBackend,
+  RpcError: () => RpcError,
+  VERSION: () => VERSION,
+  createAgentFsServer: () => createAgentFsServer,
+  parseCommand: () => parseCommand
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/parser.ts
+var VALID_OPS = /* @__PURE__ */ new Set(["ls", "cat", "write", "rm", "grep"]);
+function parseCommand(input) {
+  const trimmed = input.trim();
+  const normalized = trimmed.startsWith("nk ") ? trimmed.slice(3).trim() : trimmed;
+  const spaceIdx = normalized.indexOf(" ");
+  if (spaceIdx === -1) {
+    return {
+      ok: false,
+      error: {
+        code: "PARSE_ERROR",
+        message: `Missing path: "${input}"`
+      }
+    };
+  }
+  const op = normalized.slice(0, spaceIdx);
+  if (!VALID_OPS.has(op)) {
+    return {
+      ok: false,
+      error: {
+        code: "PARSE_ERROR",
+        message: `Unknown operation: "${op}". Valid: ls, cat, write, rm, grep`
+      }
+    };
+  }
+  const rest = normalized.slice(spaceIdx + 1).trim();
+  if (op === "grep") {
+    return parseGrep(rest, input);
+  }
+  if (op === "write") {
+    return parseWrite(rest, input);
+  }
+  const path = normalizePath(rest);
+  if (!path) {
+    return {
+      ok: false,
+      error: { code: "PARSE_ERROR", message: `Invalid path: "${rest}"` }
+    };
+  }
+  return { ok: true, data: { op, path } };
+}
+function parseGrep(rest, raw) {
+  let pattern;
+  let pathPart;
+  if (rest.startsWith('"') || rest.startsWith("'")) {
+    const quote = rest[0];
+    const endQuote = rest.indexOf(quote, 1);
+    if (endQuote === -1) {
+      return {
+        ok: false,
+        error: { code: "PARSE_ERROR", message: `Unterminated quote in: "${raw}"` }
+      };
+    }
+    pattern = rest.slice(1, endQuote);
+    pathPart = rest.slice(endQuote + 1).trim();
+  } else {
+    const spaceIdx = rest.indexOf(" ");
+    if (spaceIdx === -1) {
+      return {
+        ok: false,
+        error: { code: "PARSE_ERROR", message: `grep requires pattern and path: "${raw}"` }
+      };
+    }
+    pattern = rest.slice(0, spaceIdx);
+    pathPart = rest.slice(spaceIdx + 1).trim();
+  }
+  const path = normalizePath(pathPart);
+  if (!path) {
+    return {
+      ok: false,
+      error: { code: "PARSE_ERROR", message: `Invalid path: "${pathPart}"` }
+    };
+  }
+  return { ok: true, data: { op: "grep", path, pattern } };
+}
+function parseWrite(rest, raw) {
+  const pathMatch = rest.match(/^(\/\S+)\s+(.+)$/s);
+  if (!pathMatch) {
+    return {
+      ok: false,
+      error: { code: "PARSE_ERROR", message: `write requires path and data: "${raw}"` }
+    };
+  }
+  const path = normalizePath(pathMatch[1]);
+  if (!path) {
+    return {
+      ok: false,
+      error: { code: "PARSE_ERROR", message: `Invalid path: "${pathMatch[1]}"` }
+    };
+  }
+  let dataStr = pathMatch[2].trim();
+  if (dataStr.startsWith("'") && dataStr.endsWith("'") || dataStr.startsWith('"') && dataStr.endsWith('"')) {
+    dataStr = dataStr.slice(1, -1);
+  }
+  let data;
+  try {
+    data = JSON.parse(dataStr);
+  } catch {
+    return {
+      ok: false,
+      error: { code: "PARSE_ERROR", message: `Invalid JSON data: ${dataStr}` }
+    };
+  }
+  return { ok: true, data: { op: "write", path, data } };
+}
+function normalizePath(raw) {
+  if (!raw.startsWith("/")) return null;
+  if (raw.includes("..")) return null;
+  const cleaned = raw.replace(/\/+/g, "/");
+  return cleaned;
+}
+
+// src/mount.ts
+var MountResolver = class {
+  mounts = [];
+  /** Optional async callback invoked when resolve() finds no matching mount.
+   *  Should return true if a new mount was added. */
+  onMiss;
+  /** Register a mount point */
+  add(mount) {
+    const normalized = mount.path.replace(/\/+$/, "") || "/";
+    this.mounts.push({ ...mount, path: normalized });
+    this.mounts.sort((a, b) => b.path.length - a.path.length);
+  }
+  /** Resolve a virtual path to a mount and its relative path */
+  resolve(virtualPath) {
+    for (const mount of this.mounts) {
+      if (virtualPath === mount.path || virtualPath.startsWith(mount.path + "/")) {
+        const relativePath = virtualPath.slice(mount.path.length) || "/";
+        return { mount, relativePath };
+      }
+    }
+    return null;
+  }
+  /** Async resolve: tries sync resolve first, then calls onMiss if set. */
+  async resolveAsync(virtualPath, agent) {
+    const result = this.resolve(virtualPath);
+    if (result) return result;
+    if (this.onMiss) {
+      const added = await this.onMiss(virtualPath, agent);
+      if (added) {
+        return this.resolve(virtualPath);
+      }
+    }
+    return null;
+  }
+  /** Check if a role has permission for an operation on a mount */
+  checkPermission(mount, op, roles) {
+    const allowed = mount.permissions?.[op];
+    if (!allowed) return null;
+    const hasRole = roles.some((r) => allowed.includes(r));
+    if (!hasRole) {
+      return {
+        code: "PERMISSION_DENIED",
+        message: `Requires one of [${allowed.join(", ")}] for ${op} on ${mount.path}`
+      };
+    }
+    return null;
+  }
+  /** List all registered mount paths (used by "ls /") */
+  listMounts() {
+    return this.mounts.map((m) => m.path);
+  }
+  /** Get the backend for a mount path */
+  getBackend(mountPath) {
+    const mount = this.mounts.find((m) => m.path === mountPath);
+    return mount?.backend;
+  }
+};
+
+// src/backends/memory.ts
+var NotFoundError = class extends Error {
+  constructor(path) {
+    super(`Not found: ${path}`);
+    this.name = "NotFoundError";
+  }
+};
+
+// src/agent-fs.ts
+var AgentFs = class {
+  resolver;
+  _listDomains;
+  _searchDomains;
+  _searchEndpoints;
+  constructor(options) {
+    this.resolver = new MountResolver();
+    for (const mount of options.mounts) {
+      this.resolver.add(mount);
+    }
+    if (options.onMiss) {
+      const addMount = (mount) => this.resolver.add(mount);
+      this.resolver.onMiss = (path, agent) => options.onMiss(path, addMount, agent);
+    }
+    this._listDomains = options.listDomains;
+    this._searchDomains = options.searchDomains;
+    this._searchEndpoints = options.searchEndpoints;
+  }
+  /** Execute a raw command string like "ls /db/users/" */
+  async execute(input, roles = ["agent"], agent) {
+    const parsed = parseCommand(input);
+    if (!parsed.ok) return parsed;
+    const cmd = parsed.data;
+    return this.executeCommand(cmd, roles, agent);
+  }
+  /** Execute a pre-parsed FsCommand */
+  async executeCommand(cmd, roles = ["agent"], agent) {
+    if (cmd.path === "/" && cmd.op === "ls") {
+      const staticEntries = this.resolver.listMounts().map((p) => p.slice(1) + "/");
+      if (this._listDomains) {
+        const dynamicDomains = await this._listDomains();
+        const dynamicEntries = dynamicDomains.map((d) => d + "/");
+        const merged = [.../* @__PURE__ */ new Set([...staticEntries, ...dynamicEntries])];
+        return { ok: true, data: merged };
+      }
+      return { ok: true, data: staticEntries };
+    }
+    if (cmd.path === "/" && cmd.op === "grep" && this._searchDomains) {
+      const results = await this._searchDomains(cmd.pattern);
+      return { ok: true, data: results };
+    }
+    if (cmd.op === "grep" && this._searchEndpoints) {
+      const segments = cmd.path.split("/").filter(Boolean);
+      if (segments.length === 1) {
+        const domain = segments[0];
+        const results = await this._searchEndpoints(domain, cmd.pattern);
+        return { ok: true, data: results };
+      }
+    }
+    const resolved = await this.resolver.resolveAsync(cmd.path, agent);
+    if (!resolved) {
+      return {
+        ok: false,
+        error: { code: "NO_MOUNT", message: `No mount for path: ${cmd.path}` }
+      };
+    }
+    const permType = cmd.op === "write" || cmd.op === "rm" ? "write" : "read";
+    const permError = this.resolver.checkPermission(
+      resolved.mount,
+      permType,
+      roles
+    );
+    if (permError) {
+      return { ok: false, error: permError };
+    }
+    const backend = resolved.mount.backend;
+    const relPath = resolved.relativePath;
+    try {
+      switch (cmd.op) {
+        case "ls": {
+          const entries = await backend.list(relPath);
+          return { ok: true, data: entries };
+        }
+        case "cat": {
+          const data = await backend.read(relPath);
+          return { ok: true, data };
+        }
+        case "write": {
+          const result = await backend.write(relPath, cmd.data);
+          return { ok: true, data: result };
+        }
+        case "rm": {
+          await backend.remove(relPath);
+          return { ok: true, data: { deleted: cmd.path } };
+        }
+        case "grep": {
+          const results = await backend.search(relPath, cmd.pattern);
+          return { ok: true, data: results };
+        }
+      }
+    } catch (err) {
+      if (err instanceof NotFoundError) {
+        return {
+          ok: false,
+          error: { code: "NOT_FOUND", message: err.message }
+        };
+      }
+      return {
+        ok: false,
+        error: {
+          code: "BACKEND_ERROR",
+          message: err instanceof Error ? err.message : String(err)
+        }
+      };
+    }
+  }
+};
+
+// src/server.ts
+var import_node_http = require("http");
+function createAgentFsServer(options) {
+  const { agentFs, port = 3071 } = options;
+  const server = (0, import_node_http.createServer)(async (req, res) => {
+    try {
+      res.setHeader("Access-Control-Allow-Origin", "*");
+      res.setHeader("Access-Control-Allow-Methods", "GET, POST, PUT, DELETE, OPTIONS");
+      res.setHeader("Access-Control-Allow-Headers", "Content-Type, Authorization");
+      if (req.method === "OPTIONS") {
+        res.writeHead(204);
+        res.end();
+        return;
+      }
+      const url = new URL(req.url ?? "/", `http://${req.headers.host ?? "localhost"}`);
+      if (url.pathname === "/execute" && req.method === "POST") {
+        const body = await readBody(req);
+        const { command, roles } = body;
+        if (!command || typeof command !== "string") {
+          sendJson(res, 400, { error: "Missing 'command' field" });
+          return;
+        }
+        const result = await agentFs.execute(command, roles);
+        const status = result.ok ? 200 : errorToStatus(result.error.code);
+        sendJson(res, status, result);
+        return;
+      }
+      if (url.pathname.startsWith("/fs")) {
+        const virtualPath = url.pathname.slice(3) || "/";
+        const query = url.searchParams.get("q");
+        let op;
+        let data;
+        let pattern;
+        switch (req.method) {
+          case "GET":
+            if (query) {
+              op = "grep";
+              pattern = query;
+            } else if (virtualPath.endsWith("/")) {
+              op = "ls";
+            } else {
+              op = "cat";
+            }
+            break;
+          case "POST":
+          case "PUT":
+            op = "write";
+            data = await readBody(req);
+            break;
+          case "DELETE":
+            op = "rm";
+            break;
+          default:
+            sendJson(res, 405, { error: "Method not allowed" });
+            return;
+        }
+        const result = await agentFs.executeCommand(
+          { op, path: virtualPath, data, pattern }
+        );
+        const status = result.ok ? 200 : errorToStatus(result.error.code);
+        sendJson(res, status, result);
+        return;
+      }
+      sendJson(res, 404, { error: "Not found. Use /fs/* or /execute" });
+    } catch (err) {
+      sendJson(res, 500, {
+        error: err instanceof Error ? err.message : "Internal server error"
+      });
+    }
+  });
+  return {
+    server,
+    listen: () => new Promise((resolve) => {
+      server.listen(port, () => resolve());
+    }),
+    close: () => new Promise((resolve, reject) => {
+      server.close((err) => err ? reject(err) : resolve());
+    }),
+    port
+  };
+}
+async function readBody(req) {
+  return new Promise((resolve, reject) => {
+    const chunks = [];
+    req.on("data", (chunk) => chunks.push(chunk));
+    req.on("end", () => {
+      const raw = Buffer.concat(chunks).toString("utf-8");
+      if (!raw) {
+        resolve({});
+        return;
+      }
+      try {
+        resolve(JSON.parse(raw));
+      } catch {
+        reject(new Error("Invalid JSON body"));
+      }
+    });
+    req.on("error", reject);
+  });
+}
+function sendJson(res, status, data) {
+  res.writeHead(status, { "Content-Type": "application/json" });
+  res.end(JSON.stringify(data));
+}
+function errorToStatus(code) {
+  switch (code) {
+    case "PARSE_ERROR":
+    case "INVALID_PATH":
+      return 400;
+    case "PERMISSION_DENIED":
+      return 403;
+    case "NOT_FOUND":
+    case "NO_MOUNT":
+      return 404;
+    default:
+      return 500;
+  }
+}
+
+// src/backends/http.ts
+var HttpBackend = class {
+  baseUrl;
+  auth;
+  resourceList;
+  endpoints;
+  params;
+  _fetch;
+  bodyEncoding;
+  pagination;
+  retryConfig;
+  /** Cached OAuth2 access token */
+  _oauth2Token;
+  constructor(config) {
+    this.baseUrl = config.baseUrl.replace(/\/+$/, "");
+    this.auth = config.auth;
+    this.resourceList = config.resources ?? [];
+    this.endpoints = new Map(
+      (config.endpoints ?? []).map((e) => [e.name, e])
+    );
+    this.params = config.params ?? {};
+    this._fetch = config.fetch ?? globalThis.fetch.bind(globalThis);
+    this.bodyEncoding = config.bodyEncoding ?? "json";
+    this.retryConfig = {
+      maxRetries: config.retry?.maxRetries ?? 3,
+      baseDelayMs: config.retry?.baseDelayMs ?? 1e3
+    };
+    if (config.pagination) {
+      this.pagination = {
+        ...config.pagination,
+        maxPages: config.pagination.maxPages ?? 10
+      };
+    }
+  }
+  async list(path) {
+    const parsed = this.parsePath(path);
+    if (parsed.type === "root") {
+      const entries = [];
+      for (const r of this.resourceList) {
+        entries.push(r.name + "/");
+      }
+      if (this.endpoints.size > 0) {
+        entries.push("_api/");
+      }
+      return entries;
+    }
+    if (parsed.type === "api-list") {
+      return Array.from(this.endpoints.values()).map(
+        (e) => `${e.name} [${e.method}]`
+      );
+    }
+    if (parsed.type === "resource-list") {
+      const { resource, resolvedApiPath } = parsed;
+      const items = await this.fetchAllItems(resource, resolvedApiPath);
+      if (!Array.isArray(items)) return [];
+      return this.formatListItems(resource, items);
+    }
+    if (parsed.type === "passthrough") {
+      const resp = await this.request("GET", parsed.apiPath);
+      if (!resp.ok) return [];
+      const data = await safeJson(resp);
+      if (data === null) return [];
+      if (Array.isArray(data)) return data.map((item) => String(item.id ?? item.name ?? JSON.stringify(item)));
+      return Object.keys(data);
+    }
+    if (parsed.type === "resource-item") {
+      const { resource, resolvedApiPath, id } = parsed;
+      if (resource.pathMode === "tree") {
+        const resp = await this.request("GET", `${resolvedApiPath}/${id}`);
+        if (!resp.ok) return [];
+        const data = await safeJson(resp);
+        if (data === null) return [];
+        if (Array.isArray(data)) {
+          return this.formatListItems(resource, data);
+        }
+        return [];
+      }
+      if (resource.children && resource.children.length > 0) {
+        return resource.children.map((c) => c.name + "/");
+      }
+      return [];
+    }
+    return [];
+  }
+  async read(path) {
+    const parsed = this.parsePath(path);
+    if (parsed.type === "resource-item") {
+      const { resource, resolvedApiPath, id } = parsed;
+      if (id === "_schema") {
+        return {
+          resource: resource.name,
+          fields: resource.fields ?? []
+        };
+      }
+      if (id === "_count") {
+        const resp2 = await this.request("GET", resolvedApiPath);
+        const data = await safeJson(resp2) ?? {};
+        const items = extractList(data, resource.listKey);
+        return { count: Array.isArray(items) ? items.length : 0 };
+      }
+      const resp = await this.request("GET", `${resolvedApiPath}/${id}`);
+      if (!resp.ok) throw new NotFoundError(path);
+      let result = await safeJson(resp);
+      if (resource.transform?.read) result = resource.transform.read(result);
+      return result;
+    }
+    if (parsed.type === "resource-list") {
+      const { resource, resolvedApiPath } = parsed;
+      const resp = await this.request("GET", resolvedApiPath);
+      const data = await safeJson(resp);
+      return data === null ? [] : extractList(data, resource.listKey) ?? data;
+    }
+    if (parsed.type === "api-call") {
+      const endpoint = this.getEndpoint(parsed.endpoint);
+      const resp = await this.request(endpoint.method, endpoint.apiPath);
+      return safeJson(resp);
+    }
+    if (parsed.type === "passthrough") {
+      const resp = await this.request("GET", parsed.apiPath);
+      if (!resp.ok) throw new NotFoundError(path);
+      return safeJson(resp);
+    }
+    throw new NotFoundError(path);
+  }
+  async write(path, data) {
+    const parsed = this.parsePath(path);
+    if (parsed.type === "root" && this.resourceList.length === 0 && this.endpoints.size === 0) {
+      const resp = await this.request("POST", "/", data);
+      const result = await safeJson(resp) ?? {};
+      return { id: String(result.id ?? "ok") };
+    }
+    if (parsed.type === "resource-item" && parsed.id) {
+      const { resource, resolvedApiPath, id } = parsed;
+      let writeData = data;
+      if (resource.readBeforeWrite) {
+        try {
+          const readResp = await this.request(
+            "GET",
+            `${resolvedApiPath}/${id}`
+          );
+          if (readResp.ok) {
+            const readResult = await safeJson(readResp);
+            if (readResult) writeData = resource.readBeforeWrite.inject(readResult, writeData);
+          }
+        } catch {
+        }
+      }
+      if (resource.transform?.write) writeData = resource.transform.write(writeData);
+      const method = resource.updateMethod ?? "PUT";
+      const resp = await this.request(
+        method,
+        `${resolvedApiPath}/${id}`,
+        writeData
+      );
+      if (!resp.ok) throw new NotFoundError(path);
+      const result = await safeJson(resp) ?? {};
+      const idField = resource.idField ?? "id";
+      return { id: String(result[idField] ?? id) };
+    }
+    if (parsed.type === "resource-list") {
+      const { resource, resolvedApiPath } = parsed;
+      let writeData = data;
+      if (resource.transform?.write) writeData = resource.transform.write(writeData);
+      const resp = await this.request("POST", resolvedApiPath, writeData);
+      const result = await safeJson(resp) ?? {};
+      const idField = resource.idField ?? "id";
+      return { id: String(result[idField] ?? "unknown") };
+    }
+    if (parsed.type === "api-call") {
+      const endpoint = this.getEndpoint(parsed.endpoint);
+      const resp = await this.request(endpoint.method, endpoint.apiPath, data);
+      const result = await safeJson(resp) ?? {};
+      return { id: result.id ?? "ok" };
+    }
+    if (parsed.type === "passthrough") {
+      const method = parsed.apiPath === "/" ? "POST" : "PUT";
+      const resp = await this.request(method, parsed.apiPath, data);
+      const result = await safeJson(resp) ?? {};
+      return { id: String(result.id ?? "ok") };
+    }
+    throw new Error(`Cannot write to path: ${path}`);
+  }
+  async remove(path) {
+    const parsed = this.parsePath(path);
+    if (parsed.type === "resource-item" && parsed.id) {
+      const { resource, resolvedApiPath, id } = parsed;
+      let deleteBody;
+      if (resource.readBeforeWrite) {
+        const readResp = await this.request(
+          "GET",
+          `${resolvedApiPath}/${id}`
+        );
+        if (!readResp.ok) throw new NotFoundError(path);
+        const readResult = await safeJson(readResp);
+        if (resource.transform?.remove) {
+          deleteBody = resource.transform.remove(readResult);
+        }
+      } else if (resource.transform?.remove) {
+        deleteBody = resource.transform.remove(null);
+      }
+      const resp = await this.request(
+        "DELETE",
+        `${resolvedApiPath}/${id}`,
+        deleteBody
+      );
+      if (!resp.ok) throw new NotFoundError(path);
+      return;
+    }
+    if (parsed.type === "passthrough") {
+      const resp = await this.request("DELETE", parsed.apiPath);
+      if (!resp.ok) throw new NotFoundError(path);
+      return;
+    }
+    throw new Error(`Cannot remove path: ${path}`);
+  }
+  async search(path, pattern) {
+    const parsed = this.parsePath(path);
+    if (parsed.type === "resource-list" || parsed.type === "resource-item") {
+      const { resource, resolvedApiPath } = parsed;
+      const resp = await this.request(
+        "GET",
+        `${resolvedApiPath}?q=${encodeURIComponent(pattern)}`
+      );
+      const data = await safeJson(resp) ?? {};
+      const items = extractList(data, resource.listKey);
+      if (Array.isArray(items)) return items;
+      const allResp = await this.request("GET", resolvedApiPath);
+      const allData = await safeJson(allResp) ?? {};
+      const allItems = extractList(allData, resource.listKey);
+      if (!Array.isArray(allItems)) return [];
+      return allItems.filter(
+        (item) => JSON.stringify(item).includes(pattern)
+      );
+    }
+    if (parsed.type === "passthrough") {
+      const resp = await this.request("GET", `${parsed.apiPath}?q=${encodeURIComponent(pattern)}`);
+      const data = await safeJson(resp);
+      return Array.isArray(data) ? data : [];
+    }
+    return [];
+  }
+  // --- Internal helpers ---
+  async request(method, apiPath, body, absoluteUrl) {
+    const url = absoluteUrl ? apiPath : `${this.baseUrl}${apiPath}`;
+    const useForm = this.bodyEncoding === "form";
+    const headers = {
+      "Content-Type": useForm ? "application/x-www-form-urlencoded" : "application/json",
+      Accept: "application/json",
+      "User-Agent": "nkmc-gateway/1.0"
+    };
+    if (this.auth) {
+      switch (this.auth.type) {
+        case "bearer": {
+          const prefix = this.auth.prefix ?? "Bearer";
+          headers["Authorization"] = `${prefix} ${this.auth.token}`;
+          break;
+        }
+        case "api-key":
+          headers[this.auth.header] = this.auth.key;
+          break;
+        case "basic":
+          headers["Authorization"] = `Basic ${btoa(`${this.auth.username}:${this.auth.password}`)}`;
+          break;
+        case "oauth2": {
+          const token = await this.getOAuth2Token();
+          headers["Authorization"] = `Bearer ${token}`;
+          break;
+        }
+      }
+    }
+    let encodedBody;
+    if (body !== void 0) {
+      encodedBody = useForm ? encodeFormBody(body) : JSON.stringify(body);
+    }
+    let lastResp;
+    for (let attempt = 0; attempt <= this.retryConfig.maxRetries; attempt++) {
+      lastResp = await this._fetch(url, {
+        method,
+        headers,
+        body: encodedBody
+      });
+      if (lastResp.ok || lastResp.status >= 400 && lastResp.status < 500 && lastResp.status !== 429) {
+        return lastResp;
+      }
+      if (attempt === this.retryConfig.maxRetries) break;
+      let delayMs;
+      const retryAfter = lastResp.headers.get("retry-after");
+      if (retryAfter) {
+        const seconds = Number(retryAfter);
+        delayMs = isNaN(seconds) ? this.retryConfig.baseDelayMs : seconds * 1e3;
+      } else {
+        delayMs = this.retryConfig.baseDelayMs * Math.pow(2, attempt) * (0.5 + Math.random() * 0.5);
+      }
+      await sleep(delayMs);
+    }
+    return lastResp;
+  }
+  /** Obtain (or refresh) OAuth2 access token via client_credentials grant */
+  async getOAuth2Token() {
+    if (this.auth?.type !== "oauth2") throw new Error("Not OAuth2 auth");
+    if (this._oauth2Token && Date.now() < this._oauth2Token.expiresAt - 3e4) {
+      return this._oauth2Token.token;
+    }
+    const { tokenUrl, clientId, clientSecret, scope } = this.auth;
+    const params = new URLSearchParams({ grant_type: "client_credentials" });
+    if (scope) params.set("scope", scope);
+    const resp = await this._fetch(tokenUrl, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/x-www-form-urlencoded",
+        Authorization: `Basic ${btoa(`${clientId}:${clientSecret}`)}`
+      },
+      body: params.toString()
+    });
+    if (!resp.ok) {
+      throw new Error(`OAuth2 token request failed: ${resp.status} ${resp.statusText}`);
+    }
+    const data = await resp.json();
+    const expiresIn = data.expires_in ?? 3600;
+    this._oauth2Token = {
+      token: data.access_token,
+      expiresAt: Date.now() + expiresIn * 1e3
+    };
+    return this._oauth2Token.token;
+  }
+  /** Parse Link header to extract rel="next" URL */
+  getNextPageUrl(resp) {
+    const link = resp.headers.get("link");
+    if (!link) return null;
+    const match = link.match(/<([^>]+)>;\s*rel="next"/);
+    return match ? match[1] : null;
+  }
+  /** Fetch all items with optional pagination */
+  async fetchAllItems(resource, apiPath) {
+    const resp = await this.request("GET", apiPath);
+    const data = await safeJson(resp);
+    if (data === null) return [];
+    let items = extractList(data, resource.listKey);
+    if (!Array.isArray(items)) return [];
+    if (this.pagination) {
+      const maxPages = this.pagination.maxPages;
+      let pages = 1;
+      if (this.pagination.type === "link-header") {
+        let nextUrl = this.getNextPageUrl(resp);
+        while (nextUrl && pages < maxPages) {
+          const nextResp = await this.request("GET", nextUrl, void 0, true);
+          const nextData = await safeJson(nextResp);
+          if (!nextData) break;
+          const nextItems = extractList(nextData, resource.listKey);
+          if (!Array.isArray(nextItems) || nextItems.length === 0) break;
+          items = items.concat(nextItems);
+          nextUrl = this.getNextPageUrl(nextResp);
+          pages++;
+        }
+      } else if (this.pagination.type === "cursor") {
+        const { cursorParam, cursorPath } = this.pagination;
+        let cursor = getNestedValue(data, cursorPath);
+        while (cursor && pages < maxPages) {
+          const sep = apiPath.includes("?") ? "&" : "?";
+          const nextResp = await this.request("GET", `${apiPath}${sep}${cursorParam}=${encodeURIComponent(String(cursor))}`);
+          const nextData = await safeJson(nextResp);
+          if (!nextData) break;
+          const nextItems = extractList(nextData, resource.listKey);
+          if (!Array.isArray(nextItems) || nextItems.length === 0) break;
+          items = items.concat(nextItems);
+          cursor = getNestedValue(nextData, cursorPath);
+          pages++;
+        }
+      } else if (this.pagination.type === "offset") {
+        const { offsetParam = "offset", limitParam = "limit", pageSize = 100 } = this.pagination;
+        let offset = items.length;
+        while (pages < maxPages) {
+          const sep = apiPath.includes("?") ? "&" : "?";
+          const nextResp = await this.request("GET", `${apiPath}${sep}${offsetParam}=${offset}&${limitParam}=${pageSize}`);
+          const nextData = await safeJson(nextResp);
+          if (!nextData) break;
+          const nextItems = extractList(nextData, resource.listKey);
+          if (!Array.isArray(nextItems) || nextItems.length === 0) break;
+          items = items.concat(nextItems);
+          offset += nextItems.length;
+          pages++;
+        }
+      } else if (this.pagination.type === "page") {
+        const { pageParam = "page" } = this.pagination;
+        let page = 2;
+        while (pages < maxPages) {
+          const sep = apiPath.includes("?") ? "&" : "?";
+          const nextResp = await this.request("GET", `${apiPath}${sep}${pageParam}=${page}`);
+          const nextData = await safeJson(nextResp);
+          if (!nextData) break;
+          const nextItems = extractList(nextData, resource.listKey);
+          if (!Array.isArray(nextItems) || nextItems.length === 0) break;
+          items = items.concat(nextItems);
+          page++;
+          pages++;
+        }
+      }
+    }
+    return items;
+  }
+  /** Format list items using transform.list or default idField + ".json" */
+  formatListItems(resource, items) {
+    if (resource.transform?.list) {
+      return items.map((item) => resource.transform.list(item));
+    }
+    const idField = resource.idField ?? "id";
+    return items.map(
+      (item) => String(item[idField]) + ".json"
+    );
+  }
+  getEndpoint(name) {
+    const endpoint = this.endpoints.get(name);
+    if (!endpoint) throw new NotFoundError(`Endpoint not found: ${name}`);
+    return endpoint;
+  }
+  /** Replace :param and {param} placeholders in API paths with values from config.params */
+  resolveTemplate(path) {
+    return path.replace(/:(\w+)/g, (_, key) => {
+      const value = this.params[key];
+      if (value === void 0) throw new Error(`Missing param: ${key}`);
+      return value;
+    }).replace(/\{(\w+)\}/g, (_, key) => {
+      const value = this.params[key];
+      if (value === void 0) throw new Error(`Missing param: ${key}`);
+      return value;
+    });
+  }
+  /** Recursively resolve a filesystem path against the resource tree */
+  resolveResourcePath(parts, pos, resources, parentApiPath) {
+    if (pos >= parts.length) return null;
+    const resourceName = parts[pos];
+    const resource = resources.find((r) => r.name === resourceName);
+    if (!resource) return null;
+    const rawSegment = resource.apiPath ?? `/${resource.name}`;
+    const resolvedSegment = this.resolveTemplate(rawSegment);
+    const baseApiPath = parentApiPath + resolvedSegment;
+    const remaining = parts.length - pos - 1;
+    if (resource.pathMode === "tree") {
+      if (remaining === 0) {
+        return { type: "resource-list", resource, resolvedApiPath: baseApiPath };
+      }
+      const id2 = parts.slice(pos + 1).join("/");
+      return { type: "resource-item", resource, resolvedApiPath: baseApiPath, id: id2 };
+    }
+    if (remaining === 0) {
+      return { type: "resource-list", resource, resolvedApiPath: baseApiPath };
+    }
+    const rawId = parts[pos + 1];
+    if (remaining >= 2) {
+      if (resource.children) {
+        const childResult = this.resolveResourcePath(
+          parts,
+          pos + 2,
+          resource.children,
+          baseApiPath + "/" + rawId
+        );
+        if (childResult) return childResult;
+      }
+      return null;
+    }
+    let id = rawId;
+    if (id.endsWith(".json")) id = id.slice(0, -5);
+    return { type: "resource-item", resource, resolvedApiPath: baseApiPath, id };
+  }
+  parsePath(path) {
+    const cleaned = path.replace(/^\/+/, "").replace(/\/+$/, "");
+    if (!cleaned) return { type: "root" };
+    const parts = cleaned.split("/");
+    if (parts[0] === "_api") {
+      if (parts.length === 1) return { type: "api-list" };
+      return { type: "api-call", endpoint: parts[1] };
+    }
+    const result = this.resolveResourcePath(
+      parts,
+      0,
+      this.resourceList,
+      ""
+    );
+    if (!result) {
+      return { type: "passthrough", apiPath: "/" + cleaned };
+    }
+    return result;
+  }
+};
+async function safeJson(resp) {
+  if (resp.status === 204) return null;
+  const text = await resp.text();
+  if (!text || !text.trim()) return null;
+  try {
+    return JSON.parse(text);
+  } catch {
+    return null;
+  }
+}
+function extractList(data, listKey) {
+  if (Array.isArray(data)) return data;
+  if (typeof data !== "object" || data === null) return data;
+  if (listKey) return data[listKey];
+  let firstEmpty = null;
+  for (const value of Object.values(data)) {
+    if (Array.isArray(value)) {
+      if (value.length > 0) return value;
+      if (!firstEmpty) firstEmpty = value;
+    }
+  }
+  if (firstEmpty) return firstEmpty;
+  return data;
+}
+function getNestedValue(obj, path) {
+  let current = obj;
+  for (const key of path.split(".")) {
+    if (current === null || current === void 0 || typeof current !== "object") return void 0;
+    current = current[key];
+  }
+  return current;
+}
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function encodeFormBody(data, prefix) {
+  if (data === null || data === void 0) return "";
+  if (typeof data !== "object") {
+    return prefix ? `${encodeURIComponent(prefix)}=${encodeURIComponent(String(data))}` : "";
+  }
+  const parts = [];
+  const obj = data;
+  for (const [key, value] of Object.entries(obj)) {
+    const fullKey = prefix ? `${prefix}[${key}]` : key;
+    if (Array.isArray(value)) {
+      for (const item of value) {
+        parts.push(`${encodeURIComponent(`${fullKey}[]`)}=${encodeURIComponent(String(item))}`);
+      }
+    } else if (value !== null && typeof value === "object") {
+      const nested = encodeFormBody(value, fullKey);
+      if (nested) parts.push(nested);
+    } else if (value !== void 0) {
+      parts.push(`${encodeURIComponent(fullKey)}=${encodeURIComponent(String(value))}`);
+    }
+  }
+  return parts.join("&");
+}
+
+// src/backends/rpc.ts
+var RpcError = class extends Error {
+  code;
+  data;
+  constructor(code, message, data) {
+    super(message);
+    this.name = "RpcError";
+    this.code = code;
+    this.data = data;
+  }
+};
+function sleep2(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+async function safeRpcJson(resp) {
+  const text = await resp.text();
+  if (!text || !text.trim()) {
+    throw new RpcError(-32700, "Parse error: empty response body");
+  }
+  try {
+    return JSON.parse(text);
+  } catch {
+    throw new RpcError(-32700, `Parse error: invalid JSON response`);
+  }
+}
+var NON_RETRYABLE_RPC_CODES = /* @__PURE__ */ new Set([-32700, -32600, -32601, -32602]);
+function isRetryableRpcError(code) {
+  if (NON_RETRYABLE_RPC_CODES.has(code)) return false;
+  return code === -32603 || code >= -32099 && code <= -32e3;
+}
+function isRetryableHttpStatus(status) {
+  return status === 429 || status >= 500;
+}
+var JsonRpcTransport = class {
+  url;
+  headers;
+  _fetch;
+  nextId = 1;
+  retryConfig;
+  constructor(config) {
+    this.url = config.url;
+    this.headers = config.headers ?? {};
+    this._fetch = config.fetch ?? globalThis.fetch.bind(globalThis);
+    this.retryConfig = {
+      maxRetries: config.retry?.maxRetries ?? 3,
+      baseDelayMs: config.retry?.baseDelayMs ?? 1e3
+    };
+  }
+  async call(method, params) {
+    const id = this.nextId++;
+    const body = JSON.stringify({ jsonrpc: "2.0", id, method, params });
+    const headers = { "Content-Type": "application/json", ...this.headers };
+    let lastError;
+    for (let attempt = 0; attempt <= this.retryConfig.maxRetries; attempt++) {
+      let resp;
+      try {
+        resp = await this._fetch(this.url, { method: "POST", headers, body });
+      } catch (err) {
+        lastError = err instanceof Error ? err : new Error(String(err));
+        if (attempt < this.retryConfig.maxRetries) {
+          await this.backoff(attempt);
+          continue;
+        }
+        throw lastError;
+      }
+      if (isRetryableHttpStatus(resp.status)) {
+        lastError = new RpcError(-32e3, `HTTP ${resp.status}`);
+        if (attempt < this.retryConfig.maxRetries) {
+          await this.backoff(attempt, resp);
+          continue;
+        }
+        throw lastError;
+      }
+      const result = await safeRpcJson(resp);
+      if (result.error) {
+        const { code, message, data } = result.error;
+        if (isRetryableRpcError(code) && attempt < this.retryConfig.maxRetries) {
+          lastError = new RpcError(code, message, data);
+          await this.backoff(attempt);
+          continue;
+        }
+        throw new RpcError(code, message, data);
+      }
+      return result.result;
+    }
+    throw lastError ?? new RpcError(-32e3, "Max retries exhausted");
+  }
+  async batch(calls) {
+    const requests = calls.map((c) => ({
+      jsonrpc: "2.0",
+      id: this.nextId++,
+      method: c.method,
+      params: c.params
+    }));
+    const body = JSON.stringify(requests);
+    const headers = { "Content-Type": "application/json", ...this.headers };
+    let lastError;
+    for (let attempt = 0; attempt <= this.retryConfig.maxRetries; attempt++) {
+      let resp;
+      try {
+        resp = await this._fetch(this.url, { method: "POST", headers, body });
+      } catch (err) {
+        lastError = err instanceof Error ? err : new Error(String(err));
+        if (attempt < this.retryConfig.maxRetries) {
+          await this.backoff(attempt);
+          continue;
+        }
+        throw lastError;
+      }
+      if (isRetryableHttpStatus(resp.status)) {
+        lastError = new RpcError(-32e3, `HTTP ${resp.status}`);
+        if (attempt < this.retryConfig.maxRetries) {
+          await this.backoff(attempt, resp);
+          continue;
+        }
+        throw lastError;
+      }
+      const results = await safeRpcJson(resp);
+      const sorted = results.sort((a, b) => a.id - b.id);
+      const hasRetryableError = sorted.some(
+        (r) => r.error && isRetryableRpcError(r.error.code)
+      );
+      if (hasRetryableError && attempt < this.retryConfig.maxRetries) {
+        const firstErr = sorted.find((r) => r.error).error;
+        lastError = new RpcError(firstErr.code, firstErr.message, firstErr.data);
+        await this.backoff(attempt);
+        continue;
+      }
+      return sorted.map((r) => {
+        if (r.error) {
+          throw new RpcError(r.error.code, r.error.message, r.error.data);
+        }
+        return r.result;
+      });
+    }
+    throw lastError ?? new RpcError(-32e3, "Max retries exhausted");
+  }
+  /** Exponential backoff with jitter + Retry-After header support */
+  async backoff(attempt, resp) {
+    let delayMs;
+    const retryAfter = resp?.headers.get("retry-after");
+    if (retryAfter) {
+      const seconds = Number(retryAfter);
+      delayMs = isNaN(seconds) ? this.retryConfig.baseDelayMs : seconds * 1e3;
+    } else {
+      delayMs = this.retryConfig.baseDelayMs * Math.pow(2, attempt) * (0.5 + Math.random() * 0.5);
+    }
+    await sleep2(delayMs);
+  }
+};
+var RpcBackend = class {
+  transport;
+  resources;
+  constructor(config) {
+    this.transport = config.transport;
+    this.resources = config.resources;
+  }
+  async list(path) {
+    const parsed = this.parsePath(path);
+    if (parsed.type === "root") {
+      return this.resources.filter((r) => r.methods.list || r.methods.read).map((r) => r.name + "/");
+    }
+    if (parsed.type === "resource-list") {
+      const { resource } = parsed;
+      if (!resource.methods.list) return [];
+      const { method, params } = resource.methods.list;
+      const result = await this.transport.call(method, params({}));
+      if (resource.transform?.list) {
+        const transformed = resource.transform.list(result);
+        return Array.isArray(transformed) ? transformed : [transformed];
+      }
+      if (Array.isArray(result)) {
+        const idField = resource.idField ?? "id";
+        return result.map(
+          (item) => String(item[idField]) + ".json"
+        );
+      }
+      return [];
+    }
+    return [];
+  }
+  async read(path) {
+    const parsed = this.parsePath(path);
+    if (parsed.type === "resource-item") {
+      const { resource, id } = parsed;
+      if (!resource.methods.read) {
+        throw new NotFoundError(path);
+      }
+      const { method, params } = resource.methods.read;
+      const result = await this.transport.call(method, params({ id }));
+      if (result === null || result === void 0) {
+        throw new NotFoundError(path);
+      }
+      return resource.transform?.read ? resource.transform.read(result) : result;
+    }
+    if (parsed.type === "resource-list") {
+      const { resource } = parsed;
+      if (!resource.methods.list) {
+        throw new NotFoundError(path);
+      }
+      const { method, params } = resource.methods.list;
+      return this.transport.call(method, params({}));
+    }
+    throw new NotFoundError(path);
+  }
+  async write(path, data) {
+    const parsed = this.parsePath(path);
+    if (parsed.type === "resource-item") {
+      const { resource, id } = parsed;
+      const rpcMethod = resource.methods.write ?? resource.methods.create;
+      if (!rpcMethod) throw new Error(`Cannot write to path: ${path}`);
+      const writeData = resource.transform?.write ? resource.transform.write(data) : data;
+      const { method, params } = rpcMethod;
+      const result = await this.transport.call(method, params({ id, data: writeData }));
+      return { id: String(result ?? id) };
+    }
+    if (parsed.type === "resource-list") {
+      const { resource } = parsed;
+      const rpcMethod = resource.methods.create ?? resource.methods.write;
+      if (!rpcMethod) throw new Error(`Cannot write to path: ${path}`);
+      const writeData = resource.transform?.write ? resource.transform.write(data) : data;
+      const { method, params } = rpcMethod;
+      const result = await this.transport.call(method, params({ data: writeData }));
+      return { id: String(result ?? "unknown") };
+    }
+    throw new Error(`Cannot write to path: ${path}`);
+  }
+  async remove(path) {
+    const parsed = this.parsePath(path);
+    if (parsed.type === "resource-item") {
+      const { resource, id } = parsed;
+      if (!resource.methods.remove) {
+        throw new Error(`Cannot remove path: ${path}`);
+      }
+      const { method, params } = resource.methods.remove;
+      await this.transport.call(method, params({ id }));
+      return;
+    }
+    throw new Error(`Cannot remove path: ${path}`);
+  }
+  async search(path, pattern) {
+    const parsed = this.parsePath(path);
+    if (parsed.type === "resource-list" || parsed.type === "resource-item") {
+      const { resource } = parsed;
+      if (resource.methods.search) {
+        const { method, params } = resource.methods.search;
+        const result = await this.transport.call(method, params({ pattern }));
+        if (Array.isArray(result)) return result;
+        return [result];
+      }
+      if (resource.methods.list) {
+        const { method, params } = resource.methods.list;
+        const result = await this.transport.call(method, params({}));
+        if (Array.isArray(result)) {
+          return result.filter(
+            (item) => JSON.stringify(item).includes(pattern)
+          );
+        }
+        if (JSON.stringify(result).includes(pattern)) {
+          return [result];
+        }
+      }
+    }
+    return [];
+  }
+  // --- Internal ---
+  parsePath(path) {
+    const cleaned = path.replace(/^\/+/, "").replace(/\/+$/, "");
+    if (!cleaned) return { type: "root" };
+    const parts = cleaned.split("/");
+    const resourceName = parts[0];
+    const resource = this.resources.find((r) => r.name === resourceName);
+    if (!resource) throw new NotFoundError(`Invalid path: ${path}`);
+    if (parts.length === 1) {
+      return { type: "resource-list", resource };
+    }
+    let id = parts.slice(1).join("/");
+    if (id.endsWith(".json")) id = id.slice(0, -5);
+    return { type: "resource-item", resource, id };
+  }
+};
+
+// src/index.ts
+var VERSION = "0.1.0";
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  AgentFs,
+  HttpBackend,
+  JsonRpcTransport,
+  MountResolver,
+  RpcBackend,
+  RpcError,
+  VERSION,
+  createAgentFsServer,
+  parseCommand
+});