@particle-academy/agent-integrations 0.21.1 → 0.22.0

package/dist/bridges/map.d.cts

@@ -0,0 +1,62 @@
+import { T as ToolHost } from '../tool-host-BQuUygLF.cjs';
+import { B as Bridge } from '../types-CCSBGW9T.cjs';
+import '../types-aOQLTW0E.cjs';
+
+type LatLng = {
+    lat: number;
+    lng: number;
+};
+type MapView = {
+    center: LatLng;
+    zoom: number;
+    bearing?: number;
+    pitch?: number;
+};
+type MapMarker = {
+    id: string;
+    position: LatLng;
+    label?: string;
+    color?: string;
+    icon?: string;
+    draggable?: boolean;
+    data?: Record<string, unknown>;
+};
+
+/**
+ * Adapter the host provides — getters/setters over the SAME controlled state it
+ * passes to fancy-map's `<Map>` (view, markers, selection), plus optional
+ * `fitBounds` (from the map's onReady handle) and `setFollow` (drives the map's
+ * `follow` prop so an agent can make the camera track a moving marker).
+ */
+type MapBridgeAdapter = {
+    getView: () => MapView;
+    setView: (next: MapView) => void;
+    getMarkers: () => MapMarker[];
+    setMarkers: (next: MapMarker[] | ((prev: MapMarker[]) => MapMarker[])) => void;
+    getSelected: () => string | null;
+    setSelected: (id: string | null) => void;
+    /** Fit the camera to points (wire to the `MapHandle.fitBounds` from `<Map onReady>`). */
+    fitBounds?: (points: LatLng[], padding?: number) => void;
+    /** Make the camera follow a marker as it moves (drives the map's `follow` prop). */
+    setFollow?: (id: string | null) => void;
+};
+type MapBridgeOptions = {
+    adapter: MapBridgeAdapter;
+    /** Identity tagged onto agent-authored markers. */
+    agent?: {
+        id: string;
+        name?: string;
+        color?: string;
+    };
+};
+/**
+ * registerMapBridge — an MCP tool set over a fancy-map `<Map>`'s controlled
+ * state, so a human and an agent cohabit one map. The agent moves the camera,
+ * drops/updates/removes markers, selects, fits bounds, and follows a live
+ * track; every mutation broadcasts AgentActivity (for presence) and pushes an
+ * undo entry (so the human can step the agent back). Mirrors the whiteboard /
+ * flow bridges in shape.
+ */
+declare function registerMapBridge(host: ToolHost, options: MapBridgeOptions): Bridge;
+
+export { type MapBridgeAdapter, type MapBridgeOptions, registerMapBridge };

package/dist/bridges/map.d.ts

@@ -0,0 +1,62 @@
+import { T as ToolHost } from '../tool-host-C8JMMGYq.js';
+import { B as Bridge } from '../types-DIVNcIQO.js';
+import '../types-aOQLTW0E.js';
+
+type LatLng = {
+    lat: number;
+    lng: number;
+};
+type MapView = {
+    center: LatLng;
+    zoom: number;
+    bearing?: number;
+    pitch?: number;
+};
+type MapMarker = {
+    id: string;
+    position: LatLng;
+    label?: string;
+    color?: string;
+    icon?: string;
+    draggable?: boolean;
+    data?: Record<string, unknown>;
+};
+
+/**
+ * Adapter the host provides — getters/setters over the SAME controlled state it
+ * passes to fancy-map's `<Map>` (view, markers, selection), plus optional
+ * `fitBounds` (from the map's onReady handle) and `setFollow` (drives the map's
+ * `follow` prop so an agent can make the camera track a moving marker).
+ */
+type MapBridgeAdapter = {
+    getView: () => MapView;
+    setView: (next: MapView) => void;
+    getMarkers: () => MapMarker[];
+    setMarkers: (next: MapMarker[] | ((prev: MapMarker[]) => MapMarker[])) => void;
+    getSelected: () => string | null;
+    setSelected: (id: string | null) => void;
+    /** Fit the camera to points (wire to the `MapHandle.fitBounds` from `<Map onReady>`). */
+    fitBounds?: (points: LatLng[], padding?: number) => void;
+    /** Make the camera follow a marker as it moves (drives the map's `follow` prop). */
+    setFollow?: (id: string | null) => void;
+};
+type MapBridgeOptions = {
+    adapter: MapBridgeAdapter;
+    /** Identity tagged onto agent-authored markers. */
+    agent?: {
+        id: string;
+        name?: string;
+        color?: string;
+    };
+};
+/**
+ * registerMapBridge — an MCP tool set over a fancy-map `<Map>`'s controlled
+ * state, so a human and an agent cohabit one map. The agent moves the camera,
+ * drops/updates/removes markers, selects, fits bounds, and follows a live
+ * track; every mutation broadcasts AgentActivity (for presence) and pushes an
+ * undo entry (so the human can step the agent back). Mirrors the whiteboard /
+ * flow bridges in shape.
+ */
+declare function registerMapBridge(host: ToolHost, options: MapBridgeOptions): Bridge;
+
+export { type MapBridgeAdapter, type MapBridgeOptions, registerMapBridge };

package/dist/bridges-map.cjs

@@ -0,0 +1,454 @@
+'use strict';
+
+var fancyAutoCommon = require('@particle-academy/fancy-auto-common');
+
+// src/mcp/server.ts
+function textResult(text, structured) {
+  return {
+    content: [{ type: "text", text }],
+    ...structured !== void 0 ? { structuredContent: structured } : {}
+  };
+}
+function errorResult(text) {
+  return { content: [{ type: "text", text }], isError: true };
+}
+
+// src/presence/wrap-tool-with-activity.ts
+function wrapToolWithActivity(handler, options) {
+  return async (args) => {
+    const result = await handler(args);
+    if (result.isError) return result;
+    let target;
+    if (options.resolveTarget) {
+      target = options.resolveTarget({ toolName: options.toolName, args, result });
+    } else {
+      target = { kind: options.kind, screenId: options.screenId };
+    }
+    if (!target) return result;
+    fancyAutoCommon.emitActivity({
+      agentId: options.agent.id,
+      agentName: options.agent.name,
+      agentColor: options.agent.color,
+      target: { ...target, kind: target.kind ?? options.kind, screenId: target.screenId ?? options.screenId },
+      action: options.toolName,
+      timestamp: Date.now(),
+      meta: extractMeta(result),
+      ttlMs: options.ttlMs
+    });
+    return result;
+  };
+}
+function extractMeta(result) {
+  const sc = result.structuredContent;
+  if (sc && typeof sc === "object" && !Array.isArray(sc)) {
+    return sc;
+  }
+  return void 0;
+}
+
+// src/undo/undo-tools.ts
+var installedHosts = /* @__PURE__ */ new WeakSet();
+function ensureUndoToolsRegistered(host, options = {}) {
+  if (installedHosts.has(host)) return;
+  installedHosts.add(host);
+  registerUndoTools(host, options);
+}
+function registerUndoTools(host, options = {}) {
+  const defaultAgent = options.defaultAgentId ?? "agent";
+  const disposers = [];
+  const agentOf = (args) => typeof args?.agentId === "string" ? args.agentId : defaultAgent;
+  disposers.push(
+    host.registerTool(
+      {
+        name: "agent_undo",
+        description: "Undo the most recent action on the agent's stack. Optional agentId targets a specific agent.",
+        inputSchema: {
+          type: "object",
+          properties: { agentId: { type: "string" } },
+          additionalProperties: false
+        }
+      },
+      async (args) => {
+        const entry = await fancyAutoCommon.undoOne(agentOf(args));
+        if (!entry) return errorResult("Nothing to undo.");
+        return textResult(`Undid: ${entry.label}`, { entry: serialize(entry) });
+      }
+    )
+  );
+  disposers.push(
+    host.registerTool(
+      {
+        name: "agent_redo",
+        description: "Redo the most recently undone action.",
+        inputSchema: {
+          type: "object",
+          properties: { agentId: { type: "string" } },
+          additionalProperties: false
+        }
+      },
+      async (args) => {
+        const entry = await fancyAutoCommon.redoOne(agentOf(args));
+        if (!entry) return errorResult("Nothing to redo.");
+        return textResult(`Redid: ${entry.label}`, { entry: serialize(entry) });
+      }
+    )
+  );
+  disposers.push(
+    host.registerTool(
+      {
+        name: "agent_history",
+        description: "List the agent's undo stack (oldest first). Useful for understanding what's reversible.",
+        inputSchema: {
+          type: "object",
+          properties: { agentId: { type: "string" } },
+          additionalProperties: false
+        }
+      },
+      async (args) => {
+        const history = fancyAutoCommon.readHistory(agentOf(args)).map(serialize);
+        const text = history.map((e) => `${new Date(e.timestamp).toISOString()} ${e.bridgeId} ${e.action}: ${e.label}`).join("\n");
+        return textResult(text || "(empty)", history);
+      }
+    )
+  );
+  return () => disposers.forEach((d) => d());
+}
+function serialize(entry) {
+  return {
+    timestamp: entry.timestamp,
+    bridgeId: entry.bridgeId,
+    action: entry.action,
+    label: entry.label
+  };
+}
+
+// src/bridges/map.ts
+var DEFAULT_AGENT = { id: "agent", name: "Agent", color: "#7c3aed" };
+var num = (v, fallback) => typeof v === "number" && Number.isFinite(v) ? v : 0;
+var str = (v, fallback = "") => typeof v === "string" ? v : fallback;
+var newId = (prefix) => `${prefix}_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 7)}`;
+function registerMapBridge(host, options) {
+  const { adapter } = options;
+  const agent = { ...DEFAULT_AGENT, ...options.agent ?? {} };
+  const disposers = [];
+  ensureUndoToolsRegistered(host, { defaultAgentId: agent.id });
+  const mTarget = (args, result) => ({
+    kind: "map",
+    elementId: result?.structuredContent?.id ?? args?.id
+  });
+  const reg = (name, description, properties, required, handler, resolveTarget) => {
+    const wrapped = async (args) => {
+      try {
+        return await handler(args);
+      } catch (e) {
+        return errorResult(e instanceof Error ? e.message : String(e));
+      }
+    };
+    const final = resolveTarget ? wrapToolWithActivity(wrapped, {
+      toolName: name,
+      agent: { id: agent.id, name: agent.name, color: agent.color },
+      kind: "map",
+      resolveTarget: ({ args, result }) => resolveTarget(args, result)
+    }) : wrapped;
+    disposers.push(
+      host.registerTool(
+        {
+          name,
+          description,
+          inputSchema: {
+            type: "object",
+            properties,
+            required,
+            additionalProperties: false
+          }
+        },
+        final
+      )
+    );
+  };
+  reg("map_get_state", "Get the map's camera, markers, and current selection.", {}, [], () => {
+    const state = {
+      view: adapter.getView(),
+      markers: adapter.getMarkers(),
+      selectedId: adapter.getSelected()
+    };
+    return textResult(JSON.stringify(state, null, 2), state);
+  });
+  reg(
+    "map_set_view",
+    "Move the camera to an absolute position. Any omitted field is left unchanged.",
+    {
+      lat: { type: "number", description: "New center latitude." },
+      lng: { type: "number", description: "New center longitude." },
+      zoom: { type: "number", description: "New zoom level (higher = closer)." }
+    },
+    [],
+    (args) => {
+      const prev = adapter.getView();
+      const next = {
+        center: {
+          lat: args.lat !== void 0 ? num(args.lat) : prev.center.lat,
+          lng: args.lng !== void 0 ? num(args.lng) : prev.center.lng
+        },
+        zoom: args.zoom !== void 0 ? num(args.zoom) : prev.zoom
+      };
+      adapter.setView(next);
+      fancyAutoCommon.pushUndoEntry(agent.id, {
+        timestamp: Date.now(),
+        bridgeId: "map",
+        action: "map_set_view",
+        label: `Moved camera to ${next.center.lat.toFixed(4)},${next.center.lng.toFixed(4)} z${next.zoom}`,
+        undo: () => adapter.setView(prev),
+        redo: () => adapter.setView(next)
+      });
+      return textResult(`Camera \u2192 ${next.center.lat.toFixed(4)},${next.center.lng.toFixed(4)} z${next.zoom}`, next);
+    },
+    mTarget
+  );
+  reg(
+    "map_pan",
+    "Pan the camera by a relative offset in degrees (positive dLat = north, positive dLng = east).",
+    { dLat: { type: "number" }, dLng: { type: "number" } },
+    [],
+    (args) => {
+      const prev = adapter.getView();
+      const next = {
+        ...prev,
+        center: { lat: prev.center.lat + num(args.dLat), lng: prev.center.lng + num(args.dLng) }
+      };
+      adapter.setView(next);
+      fancyAutoCommon.pushUndoEntry(agent.id, {
+        timestamp: Date.now(),
+        bridgeId: "map",
+        action: "map_pan",
+        label: "Panned camera",
+        undo: () => adapter.setView(prev),
+        redo: () => adapter.setView(next)
+      });
+      return textResult(`Panned to ${next.center.lat.toFixed(4)},${next.center.lng.toFixed(4)}`, next);
+    },
+    mTarget
+  );
+  reg(
+    "map_zoom",
+    "Zoom the camera by a relative delta (e.g. +1 zooms in one level, -2 out two).",
+    { delta: { type: "number" } },
+    ["delta"],
+    (args) => {
+      const prev = adapter.getView();
+      const next = { ...prev, zoom: prev.zoom + num(args.delta) };
+      adapter.setView(next);
+      fancyAutoCommon.pushUndoEntry(agent.id, {
+        timestamp: Date.now(),
+        bridgeId: "map",
+        action: "map_zoom",
+        label: `Zoom \u2192 ${next.zoom}`,
+        undo: () => adapter.setView(prev),
+        redo: () => adapter.setView(next)
+      });
+      return textResult(`Zoom \u2192 ${next.zoom}`, next);
+    }
+  );
+  reg(
+    "map_fit_bounds",
+    "Fit the camera to enclose points. Pass `points`, or omit to fit all current markers.",
+    {
+      points: {
+        type: "array",
+        description: "Points to enclose, e.g. [{lat,lng},\u2026].",
+        items: {
+          type: "object",
+          properties: { lat: { type: "number" }, lng: { type: "number" } },
+          required: ["lat", "lng"]
+        }
+      },
+      padding: { type: "number", description: "Padding in pixels (default 40)." }
+    },
+    [],
+    (args) => {
+      if (!adapter.fitBounds) {
+        return errorResult("Host did not wire fitBounds (pass the <Map onReady> handle's fitBounds).");
+      }
+      const points = Array.isArray(args.points) ? args.points.map((p) => ({ lat: num(p?.lat), lng: num(p?.lng) })) : adapter.getMarkers().map((m) => m.position);
+      if (!points.length) {
+        return errorResult("No points to fit (map has no markers).");
+      }
+      adapter.fitBounds(points, args.padding !== void 0 ? num(args.padding) : void 0);
+      return textResult(`Fit camera to ${points.length} point(s).`);
+    }
+  );
+  reg(
+    "map_add_marker",
+    "Drop a marker. `id` is optional (auto-generated); `icon` is an emoji or 1\u20132 chars.",
+    {
+      id: { type: "string" },
+      lat: { type: "number" },
+      lng: { type: "number" },
+      label: { type: "string" },
+      color: { type: "string", description: "CSS color, e.g. #2563eb." },
+      icon: { type: "string", description: "Emoji / short text in the pin." },
+      draggable: { type: "boolean" },
+      data: { type: "object", description: "Arbitrary JSON payload carried with the marker." }
+    },
+    ["lat", "lng"],
+    (args) => {
+      const id = args.id ? str(args.id) : newId("m");
+      if (adapter.getMarkers().some((m) => m.id === id)) {
+        return errorResult(`A marker with id ${id} already exists \u2014 use map_update_marker.`);
+      }
+      const marker = {
+        id,
+        position: { lat: num(args.lat), lng: num(args.lng) },
+        ...args.label !== void 0 ? { label: str(args.label) } : {},
+        ...args.color !== void 0 ? { color: str(args.color) } : {},
+        ...args.icon !== void 0 ? { icon: str(args.icon) } : {},
+        ...args.draggable !== void 0 ? { draggable: !!args.draggable } : {},
+        ...args.data && typeof args.data === "object" ? { data: args.data } : {}
+      };
+      adapter.setMarkers((all) => [...all, marker]);
+      fancyAutoCommon.pushUndoEntry(agent.id, {
+        timestamp: Date.now(),
+        bridgeId: "map",
+        action: "map_add_marker",
+        label: `Added marker ${id}`,
+        undo: () => adapter.setMarkers((all) => all.filter((m) => m.id !== id)),
+        redo: () => adapter.setMarkers((all) => [...all, marker])
+      });
+      return textResult(`Added marker ${id} at ${marker.position.lat.toFixed(4)},${marker.position.lng.toFixed(4)}`, marker);
+    },
+    mTarget
+  );
+  reg(
+    "map_update_marker",
+    "Update a marker. Only provided fields change \u2014 update lat/lng repeatedly to drive a live track.",
+    {
+      id: { type: "string" },
+      lat: { type: "number" },
+      lng: { type: "number" },
+      label: { type: "string" },
+      color: { type: "string" },
+      icon: { type: "string" },
+      draggable: { type: "boolean" }
+    },
+    ["id"],
+    (args) => {
+      const id = str(args.id);
+      const prev = adapter.getMarkers().find((m) => m.id === id);
+      if (!prev) {
+        return errorResult(`No marker with id ${id}`);
+      }
+      const next = {
+        ...prev,
+        position: {
+          lat: args.lat !== void 0 ? num(args.lat) : prev.position.lat,
+          lng: args.lng !== void 0 ? num(args.lng) : prev.position.lng
+        },
+        ...args.label !== void 0 ? { label: str(args.label) } : {},
+        ...args.color !== void 0 ? { color: str(args.color) } : {},
+        ...args.icon !== void 0 ? { icon: str(args.icon) } : {},
+        ...args.draggable !== void 0 ? { draggable: !!args.draggable } : {}
+      };
+      adapter.setMarkers((all) => all.map((m) => m.id === id ? next : m));
+      fancyAutoCommon.pushUndoEntry(agent.id, {
+        timestamp: Date.now(),
+        bridgeId: "map",
+        action: "map_update_marker",
+        label: `Updated marker ${id}`,
+        undo: () => adapter.setMarkers((all) => all.map((m) => m.id === id ? prev : m)),
+        redo: () => adapter.setMarkers((all) => all.map((m) => m.id === id ? next : m))
+      });
+      return textResult(`Updated marker ${id}`, next);
+    },
+    mTarget
+  );
+  reg(
+    "map_remove_marker",
+    "Remove a marker by id.",
+    { id: { type: "string" } },
+    ["id"],
+    (args) => {
+      const id = str(args.id);
+      const prev = adapter.getMarkers().find((m) => m.id === id);
+      if (!prev) {
+        return errorResult(`No marker with id ${id}`);
+      }
+      adapter.setMarkers((all) => all.filter((m) => m.id !== id));
+      fancyAutoCommon.pushUndoEntry(agent.id, {
+        timestamp: Date.now(),
+        bridgeId: "map",
+        action: "map_remove_marker",
+        label: `Removed marker ${id}`,
+        undo: () => adapter.setMarkers((all) => [...all, prev]),
+        redo: () => adapter.setMarkers((all) => all.filter((m) => m.id !== id))
+      });
+      return textResult(`Removed marker ${id}`);
+    },
+    mTarget
+  );
+  reg(
+    "map_select",
+    "Select a marker (or pass no id / null to clear the selection).",
+    { id: { type: "string" } },
+    [],
+    (args) => {
+      const prev = adapter.getSelected();
+      const id = args.id === void 0 || args.id === null ? null : str(args.id);
+      if (id !== null && !adapter.getMarkers().some((m) => m.id === id)) {
+        return errorResult(`No marker with id ${id}`);
+      }
+      adapter.setSelected(id);
+      fancyAutoCommon.pushUndoEntry(agent.id, {
+        timestamp: Date.now(),
+        bridgeId: "map",
+        action: "map_select",
+        label: id ? `Selected ${id}` : "Cleared selection",
+        undo: () => adapter.setSelected(prev),
+        redo: () => adapter.setSelected(id)
+      });
+      return textResult(id ? `Selected marker ${id}` : "Cleared selection", { selectedId: id });
+    },
+    mTarget
+  );
+  reg(
+    "map_start_track",
+    "Make the camera follow a marker as its position updates (live tracking). Requires the host to wire setFollow.",
+    { id: { type: "string" } },
+    ["id"],
+    (args) => {
+      if (!adapter.setFollow) {
+        return errorResult("Host did not wire setFollow (pass the map's `follow` setter).");
+      }
+      const id = str(args.id);
+      if (!adapter.getMarkers().some((m) => m.id === id)) {
+        return errorResult(`No marker with id ${id}`);
+      }
+      adapter.setFollow(id);
+      return textResult(`Camera now following ${id}`, { follow: id });
+    },
+    mTarget
+  );
+  reg(
+    "map_stop_track",
+    "Stop following any marker (releases the camera). Requires the host to wire setFollow.",
+    {},
+    [],
+    () => {
+      if (!adapter.setFollow) {
+        return errorResult("Host did not wire setFollow.");
+      }
+      adapter.setFollow(null);
+      return textResult("Camera released (no longer following).", { follow: null });
+    }
+  );
+  return {
+    id: "map",
+    title: "Map",
+    dispose: () => {
+      for (const d of disposers) d();
+    }
+  };
+}
+
+exports.registerMapBridge = registerMapBridge;
+//# sourceMappingURL=bridges-map.cjs.map
+//# sourceMappingURL=bridges-map.cjs.map