@particle-academy/agent-integrations 0.2.4 → 0.4.0

package/dist/presence/index.d.cts

@@ -0,0 +1,136 @@
+import { C as CallToolResult } from '../types-aOQLTW0E.cjs';
+
+/**
+ * Presence layer types — describe what the agent is doing right now and
+ * where. Every bridge tool emits one of these when it runs; the registry
+ * fans them out to in-process subscribers + the SSE relay so external
+ * clients can render presence indicators across the whole app.
+ */
+type AgentTargetKind = "whiteboard" | "flow" | "form" | "sheet" | "code" | "chart" | "scene" | "custom";
+type AgentTarget = {
+    /** Which package surface the action affects. */
+    kind: AgentTargetKind | string;
+    /** Optional fancy-screens screen id, for screen-scoped UIs. */
+    screenId?: string;
+    /** Optional element id within the surface (sticky id, node id, field name, …). */
+    elementId?: string;
+    /** Free-form label the host can render (e.g. "the 'email' field"). */
+    label?: string;
+};
+type AgentActivityEvent = {
+    /** Stable identifier for the acting agent. */
+    agentId: string;
+    /** Human-friendly name (used by indicators / activity log). */
+    agentName?: string;
+    /** Color for cursor / highlight CSS. */
+    agentColor?: string;
+    /** What the agent is touching. */
+    target: AgentTarget;
+    /** Snake-case action verb mirroring the tool name (e.g. "whiteboard_add_sticky"). */
+    action: string;
+    /** Wall-clock ms — when the action ran. */
+    timestamp: number;
+    /** Optional small structured payload describing the action's effect. */
+    meta?: Record<string, unknown>;
+    /** Optional duration in ms — how long the activity should "stick" on the
+     *  UI before fading. Default 1500. */
+    ttlMs?: number;
+};
+type AgentActivityListener = (event: AgentActivityEvent) => void;
+type ActivityFilter = {
+    agentId?: string;
+    screenId?: string;
+    kind?: string;
+};
+
+/** Emit an activity event. All current listeners receive it synchronously. */
+declare function emitActivity(event: AgentActivityEvent): void;
+/**
+ * Subscribe to all events (or a filtered subset). Returns an unsubscribe
+ * function. Filter checks all provided keys with strict equality; omit a
+ * key to ignore it.
+ */
+declare function onActivity(listener: AgentActivityListener, filter?: ActivityFilter): () => void;
+/** Read the recent history (newest last). Optional filter. */
+declare function readActivityHistory(filter?: ActivityFilter): AgentActivityEvent[];
+/** Wipe history + clear listeners. Test/teardown helper. */
+declare function resetActivityRegistry(): void;
+
+type ActivityAgent = {
+    id: string;
+    name?: string;
+    color?: string;
+};
+type ActivityResolverContext<TArgs = Record<string, unknown>> = {
+    /** Tool name as registered. */
+    toolName: string;
+    /** Arguments the tool was called with. */
+    args: TArgs;
+    /** The CallToolResult the underlying handler produced. */
+    result: CallToolResult;
+};
+/**
+ * Resolves an `AgentTarget` for an executed tool. Bridges declare one of
+ * these per registration so the wrapper knows which surface / element /
+ * screen the activity belongs to.
+ *
+ * The resolver runs AFTER the tool handler so it can inspect the result
+ * (e.g. read a newly-created item id from `structuredContent`).
+ */
+type ActivityTargetResolver<TArgs = Record<string, unknown>> = (ctx: ActivityResolverContext<TArgs>) => AgentTarget | null;
+type ToolHandler<TArgs = Record<string, unknown>> = (args: TArgs) => Promise<CallToolResult> | CallToolResult;
+/**
+ * wrapToolWithActivity — decorate a bridge tool handler so every successful
+ * call emits an `AgentActivityEvent`. Returns a new handler with the same shape.
+ *
+ * Usage in a bridge:
+ *
+ *   server.registerTool(
+ *     definition,
+ *     wrapToolWithActivity(
+ *       handler,
+ *       { agent, kind: "whiteboard", resolveTarget: ({ args }) => ({
+ *           kind: "whiteboard", elementId: args.id as string,
+ *         }) },
+ *     ),
+ *   );
+ */
+declare function wrapToolWithActivity<TArgs = Record<string, unknown>>(handler: ToolHandler<TArgs>, options: {
+    toolName: string;
+    agent: ActivityAgent;
+    /** Optional fancy-screens screen id this bridge is scoped to. */
+    screenId?: string;
+    /** Default target kind if the resolver returns one without `kind`. */
+    kind: AgentTarget["kind"];
+    /** Per-call resolver. Return `null` to skip emitting (e.g. for read-only tools). */
+    resolveTarget?: ActivityTargetResolver<TArgs>;
+    /** Optional ttl override. */
+    ttlMs?: number;
+}): ToolHandler<TArgs>;
+
+/**
+ * useAgentActivity — React subscription to the in-process activity stream.
+ *
+ * Returns:
+ *   - `events`: capped scrollback of recent events matching the filter
+ *   - `latest`: the most recent event (handy for transient highlights)
+ */
+declare function useAgentActivity(filter?: ActivityFilter, options?: {
+    capacity?: number;
+}): {
+    events: AgentActivityEvent[];
+    latest: AgentActivityEvent | null;
+};
+/**
+ * useAgentActivityForScreen — convenience wrapper that filters by screen id.
+ * Drives "agent is here" badges in fancy-screens-based shells.
+ */
+declare function useAgentActivityForScreen(screenId: string, options?: {
+    capacity?: number;
+}): {
+    events: AgentActivityEvent[];
+    latest: AgentActivityEvent | null;
+    isAgentActive: boolean;
+};
+
+export { type ActivityAgent, type ActivityFilter, type ActivityResolverContext, type ActivityTargetResolver, type AgentActivityEvent, type AgentActivityListener, type AgentTarget, type AgentTargetKind, type ToolHandler, emitActivity, onActivity, readActivityHistory, resetActivityRegistry, useAgentActivity, useAgentActivityForScreen, wrapToolWithActivity };

package/dist/presence/index.d.ts

@@ -0,0 +1,136 @@
+import { C as CallToolResult } from '../types-aOQLTW0E.js';
+
+/**
+ * Presence layer types — describe what the agent is doing right now and
+ * where. Every bridge tool emits one of these when it runs; the registry
+ * fans them out to in-process subscribers + the SSE relay so external
+ * clients can render presence indicators across the whole app.
+ */
+type AgentTargetKind = "whiteboard" | "flow" | "form" | "sheet" | "code" | "chart" | "scene" | "custom";
+type AgentTarget = {
+    /** Which package surface the action affects. */
+    kind: AgentTargetKind | string;
+    /** Optional fancy-screens screen id, for screen-scoped UIs. */
+    screenId?: string;
+    /** Optional element id within the surface (sticky id, node id, field name, …). */
+    elementId?: string;
+    /** Free-form label the host can render (e.g. "the 'email' field"). */
+    label?: string;
+};
+type AgentActivityEvent = {
+    /** Stable identifier for the acting agent. */
+    agentId: string;
+    /** Human-friendly name (used by indicators / activity log). */
+    agentName?: string;
+    /** Color for cursor / highlight CSS. */
+    agentColor?: string;
+    /** What the agent is touching. */
+    target: AgentTarget;
+    /** Snake-case action verb mirroring the tool name (e.g. "whiteboard_add_sticky"). */
+    action: string;
+    /** Wall-clock ms — when the action ran. */
+    timestamp: number;
+    /** Optional small structured payload describing the action's effect. */
+    meta?: Record<string, unknown>;
+    /** Optional duration in ms — how long the activity should "stick" on the
+     *  UI before fading. Default 1500. */
+    ttlMs?: number;
+};
+type AgentActivityListener = (event: AgentActivityEvent) => void;
+type ActivityFilter = {
+    agentId?: string;
+    screenId?: string;
+    kind?: string;
+};
+
+/** Emit an activity event. All current listeners receive it synchronously. */
+declare function emitActivity(event: AgentActivityEvent): void;
+/**
+ * Subscribe to all events (or a filtered subset). Returns an unsubscribe
+ * function. Filter checks all provided keys with strict equality; omit a
+ * key to ignore it.
+ */
+declare function onActivity(listener: AgentActivityListener, filter?: ActivityFilter): () => void;
+/** Read the recent history (newest last). Optional filter. */
+declare function readActivityHistory(filter?: ActivityFilter): AgentActivityEvent[];
+/** Wipe history + clear listeners. Test/teardown helper. */
+declare function resetActivityRegistry(): void;
+
+type ActivityAgent = {
+    id: string;
+    name?: string;
+    color?: string;
+};
+type ActivityResolverContext<TArgs = Record<string, unknown>> = {
+    /** Tool name as registered. */
+    toolName: string;
+    /** Arguments the tool was called with. */
+    args: TArgs;
+    /** The CallToolResult the underlying handler produced. */
+    result: CallToolResult;
+};
+/**
+ * Resolves an `AgentTarget` for an executed tool. Bridges declare one of
+ * these per registration so the wrapper knows which surface / element /
+ * screen the activity belongs to.
+ *
+ * The resolver runs AFTER the tool handler so it can inspect the result
+ * (e.g. read a newly-created item id from `structuredContent`).
+ */
+type ActivityTargetResolver<TArgs = Record<string, unknown>> = (ctx: ActivityResolverContext<TArgs>) => AgentTarget | null;
+type ToolHandler<TArgs = Record<string, unknown>> = (args: TArgs) => Promise<CallToolResult> | CallToolResult;
+/**
+ * wrapToolWithActivity — decorate a bridge tool handler so every successful
+ * call emits an `AgentActivityEvent`. Returns a new handler with the same shape.
+ *
+ * Usage in a bridge:
+ *
+ *   server.registerTool(
+ *     definition,
+ *     wrapToolWithActivity(
+ *       handler,
+ *       { agent, kind: "whiteboard", resolveTarget: ({ args }) => ({
+ *           kind: "whiteboard", elementId: args.id as string,
+ *         }) },
+ *     ),
+ *   );
+ */
+declare function wrapToolWithActivity<TArgs = Record<string, unknown>>(handler: ToolHandler<TArgs>, options: {
+    toolName: string;
+    agent: ActivityAgent;
+    /** Optional fancy-screens screen id this bridge is scoped to. */
+    screenId?: string;
+    /** Default target kind if the resolver returns one without `kind`. */
+    kind: AgentTarget["kind"];
+    /** Per-call resolver. Return `null` to skip emitting (e.g. for read-only tools). */
+    resolveTarget?: ActivityTargetResolver<TArgs>;
+    /** Optional ttl override. */
+    ttlMs?: number;
+}): ToolHandler<TArgs>;
+
+/**
+ * useAgentActivity — React subscription to the in-process activity stream.
+ *
+ * Returns:
+ *   - `events`: capped scrollback of recent events matching the filter
+ *   - `latest`: the most recent event (handy for transient highlights)
+ */
+declare function useAgentActivity(filter?: ActivityFilter, options?: {
+    capacity?: number;
+}): {
+    events: AgentActivityEvent[];
+    latest: AgentActivityEvent | null;
+};
+/**
+ * useAgentActivityForScreen — convenience wrapper that filters by screen id.
+ * Drives "agent is here" badges in fancy-screens-based shells.
+ */
+declare function useAgentActivityForScreen(screenId: string, options?: {
+    capacity?: number;
+}): {
+    events: AgentActivityEvent[];
+    latest: AgentActivityEvent | null;
+    isAgentActive: boolean;
+};
+
+export { type ActivityAgent, type ActivityFilter, type ActivityResolverContext, type ActivityTargetResolver, type AgentActivityEvent, type AgentActivityListener, type AgentTarget, type AgentTargetKind, type ToolHandler, emitActivity, onActivity, readActivityHistory, resetActivityRegistry, useAgentActivity, useAgentActivityForScreen, wrapToolWithActivity };

package/dist/presence.cjs

@@ -0,0 +1,107 @@
+'use strict';
+
+var react = require('react');
+
+// src/presence/registry.ts
+var HISTORY_CAP = 200;
+var listeners = /* @__PURE__ */ new Set();
+var history = [];
+function emitActivity(event) {
+  history.push(event);
+  if (history.length > HISTORY_CAP) history.splice(0, history.length - HISTORY_CAP);
+  for (const l of listeners) l(event);
+}
+function onActivity(listener, filter) {
+  const wrapped = filter ? (e) => {
+    if (matches(e, filter)) listener(e);
+  } : listener;
+  listeners.add(wrapped);
+  return () => listeners.delete(wrapped);
+}
+function readActivityHistory(filter) {
+  if (!filter) return history.slice();
+  return history.filter((e) => matches(e, filter));
+}
+function resetActivityRegistry() {
+  listeners.clear();
+  history.length = 0;
+}
+function matches(e, f) {
+  if (f.agentId !== void 0 && e.agentId !== f.agentId) return false;
+  if (f.screenId !== void 0 && e.target.screenId !== f.screenId) return false;
+  if (f.kind !== void 0 && e.target.kind !== f.kind) return false;
+  return 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;
+    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;
+}
+function useAgentActivity(filter, options = {}) {
+  const cap = options.capacity ?? 50;
+  const [events, setEvents] = react.useState(() => readActivityHistory(filter).slice(-cap));
+  react.useEffect(() => {
+    setEvents(readActivityHistory(filter).slice(-cap));
+    return onActivity((event) => {
+      setEvents((prev) => {
+        const next = prev.length >= cap ? prev.slice(prev.length - cap + 1) : prev.slice();
+        next.push(event);
+        return next;
+      });
+    }, filter);
+  }, [filter?.agentId, filter?.screenId, filter?.kind, cap]);
+  return { events, latest: events.length > 0 ? events[events.length - 1] : null };
+}
+function useAgentActivityForScreen(screenId, options = {}) {
+  const { events, latest } = useAgentActivity({ screenId }, options);
+  const fadeAfter = latest?.ttlMs ?? 1500;
+  const [isAgentActive, setActive] = react.useState(false);
+  react.useEffect(() => {
+    if (!latest) {
+      setActive(false);
+      return;
+    }
+    setActive(true);
+    const timer = setTimeout(() => setActive(false), fadeAfter);
+    return () => clearTimeout(timer);
+  }, [latest, fadeAfter]);
+  return { events, latest, isAgentActive };
+}
+
+exports.emitActivity = emitActivity;
+exports.onActivity = onActivity;
+exports.readActivityHistory = readActivityHistory;
+exports.resetActivityRegistry = resetActivityRegistry;
+exports.useAgentActivity = useAgentActivity;
+exports.useAgentActivityForScreen = useAgentActivityForScreen;
+exports.wrapToolWithActivity = wrapToolWithActivity;
+//# sourceMappingURL=presence.cjs.map
+//# sourceMappingURL=presence.cjs.map

package/dist/presence.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/presence/registry.ts","../src/presence/wrap-tool-with-activity.ts","../src/presence/use-agent-activity.ts"],"names":["useState","useEffect"],"mappings":"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","file":"presence.cjs","sourcesContent":["import type { ActivityFilter, AgentActivityEvent, AgentActivityListener } from \"./types\";\n\n/**\n * In-process registry of agent activity events. Bridges call `emitActivity`\n * after a tool runs; React hooks + the SSE relay subscribe via\n * `onActivity()`.\n *\n * Holds a short scrollback of recent events (default 200) so newly-mounted\n * subscribers can render the recent past — useful for activity-log UIs\n * that rejoin a session mid-stream.\n */\n\nconst HISTORY_CAP = 200;\n\nconst listeners = new Set<AgentActivityListener>();\nconst history: AgentActivityEvent[] = [];\n\n/** Emit an activity event. All current listeners receive it synchronously. */\nexport function emitActivity(event: AgentActivityEvent): void {\n  history.push(event);\n  if (history.length > HISTORY_CAP) history.splice(0, history.length - HISTORY_CAP);\n  for (const l of listeners) l(event);\n}\n\n/**\n * Subscribe to all events (or a filtered subset). Returns an unsubscribe\n * function. Filter checks all provided keys with strict equality; omit a\n * key to ignore it.\n */\nexport function onActivity(listener: AgentActivityListener, filter?: ActivityFilter): () => void {\n  const wrapped: AgentActivityListener = filter\n    ? (e) => { if (matches(e, filter)) listener(e); }\n    : listener;\n  listeners.add(wrapped);\n  return () => listeners.delete(wrapped);\n}\n\n/** Read the recent history (newest last). Optional filter. */\nexport function readActivityHistory(filter?: ActivityFilter): AgentActivityEvent[] {\n  if (!filter) return history.slice();\n  return history.filter((e) => matches(e, filter));\n}\n\n/** Wipe history + clear listeners. Test/teardown helper. */\nexport function resetActivityRegistry(): void {\n  listeners.clear();\n  history.length = 0;\n}\n\nfunction matches(e: AgentActivityEvent, f: ActivityFilter): boolean {\n  if (f.agentId !== undefined && e.agentId !== f.agentId) return false;\n  if (f.screenId !== undefined && e.target.screenId !== f.screenId) return false;\n  if (f.kind !== undefined && e.target.kind !== f.kind) return false;\n  return true;\n}\n","import type { CallToolResult } from \"../mcp/types\";\nimport { emitActivity } from \"./registry\";\nimport type { AgentTarget } from \"./types\";\n\nexport type ActivityAgent = { id: string; name?: string; color?: string };\n\nexport type ActivityResolverContext<TArgs = Record<string, unknown>> = {\n  /** Tool name as registered. */\n  toolName: string;\n  /** Arguments the tool was called with. */\n  args: TArgs;\n  /** The CallToolResult the underlying handler produced. */\n  result: CallToolResult;\n};\n\n/**\n * Resolves an `AgentTarget` for an executed tool. Bridges declare one of\n * these per registration so the wrapper knows which surface / element /\n * screen the activity belongs to.\n *\n * The resolver runs AFTER the tool handler so it can inspect the result\n * (e.g. read a newly-created item id from `structuredContent`).\n */\nexport type ActivityTargetResolver<TArgs = Record<string, unknown>> = (\n  ctx: ActivityResolverContext<TArgs>,\n) => AgentTarget | null;\n\nexport type ToolHandler<TArgs = Record<string, unknown>> = (\n  args: TArgs,\n) => Promise<CallToolResult> | CallToolResult;\n\n/**\n * wrapToolWithActivity — decorate a bridge tool handler so every successful\n * call emits an `AgentActivityEvent`. Returns a new handler with the same shape.\n *\n * Usage in a bridge:\n *\n *   server.registerTool(\n *     definition,\n *     wrapToolWithActivity(\n *       handler,\n *       { agent, kind: \"whiteboard\", resolveTarget: ({ args }) => ({\n *           kind: \"whiteboard\", elementId: args.id as string,\n *         }) },\n *     ),\n *   );\n */\nexport function wrapToolWithActivity<TArgs = Record<string, unknown>>(\n  handler: ToolHandler<TArgs>,\n  options: {\n    toolName: string;\n    agent: ActivityAgent;\n    /** Optional fancy-screens screen id this bridge is scoped to. */\n    screenId?: string;\n    /** Default target kind if the resolver returns one without `kind`. */\n    kind: AgentTarget[\"kind\"];\n    /** Per-call resolver. Return `null` to skip emitting (e.g. for read-only tools). */\n    resolveTarget?: ActivityTargetResolver<TArgs>;\n    /** Optional ttl override. */\n    ttlMs?: number;\n  },\n): ToolHandler<TArgs> {\n  return async (args) => {\n    const result = await handler(args);\n    if (result.isError) return result;\n\n    let target: AgentTarget | null;\n    if (options.resolveTarget) {\n      target = options.resolveTarget({ toolName: options.toolName, args, result });\n    } else {\n      target = { kind: options.kind, screenId: options.screenId };\n    }\n    if (!target) return result;\n\n    emitActivity({\n      agentId: options.agent.id,\n      agentName: options.agent.name,\n      agentColor: options.agent.color,\n      target: { ...target, kind: target.kind ?? options.kind, screenId: target.screenId ?? options.screenId },\n      action: options.toolName,\n      timestamp: Date.now(),\n      meta: extractMeta(result),\n      ttlMs: options.ttlMs,\n    });\n    return result;\n  };\n}\n\nfunction extractMeta(result: CallToolResult): Record<string, unknown> | undefined {\n  const sc = result.structuredContent;\n  if (sc && typeof sc === \"object\" && !Array.isArray(sc)) {\n    return sc as Record<string, unknown>;\n  }\n  return undefined;\n}\n","import { useEffect, useState } from \"react\";\nimport { onActivity, readActivityHistory } from \"./registry\";\nimport type { ActivityFilter, AgentActivityEvent } from \"./types\";\n\n/**\n * useAgentActivity — React subscription to the in-process activity stream.\n *\n * Returns:\n *   - `events`: capped scrollback of recent events matching the filter\n *   - `latest`: the most recent event (handy for transient highlights)\n */\nexport function useAgentActivity(\n  filter?: ActivityFilter,\n  options: { capacity?: number } = {},\n): { events: AgentActivityEvent[]; latest: AgentActivityEvent | null } {\n  const cap = options.capacity ?? 50;\n  const [events, setEvents] = useState<AgentActivityEvent[]>(() => readActivityHistory(filter).slice(-cap));\n\n  useEffect(() => {\n    setEvents(readActivityHistory(filter).slice(-cap));\n    return onActivity((event) => {\n      setEvents((prev) => {\n        const next = prev.length >= cap ? prev.slice(prev.length - cap + 1) : prev.slice();\n        next.push(event);\n        return next;\n      });\n    }, filter);\n    // eslint-disable-next-line react-hooks/exhaustive-deps\n  }, [filter?.agentId, filter?.screenId, filter?.kind, cap]);\n\n  return { events, latest: events.length > 0 ? events[events.length - 1] : null };\n}\n\n/**\n * useAgentActivityForScreen — convenience wrapper that filters by screen id.\n * Drives \"agent is here\" badges in fancy-screens-based shells.\n */\nexport function useAgentActivityForScreen(\n  screenId: string,\n  options: { capacity?: number } = {},\n): { events: AgentActivityEvent[]; latest: AgentActivityEvent | null; isAgentActive: boolean } {\n  const { events, latest } = useAgentActivity({ screenId }, options);\n  const fadeAfter = latest?.ttlMs ?? 1500;\n  const [isAgentActive, setActive] = useState(false);\n\n  useEffect(() => {\n    if (!latest) {\n      setActive(false);\n      return;\n    }\n    setActive(true);\n    const timer = setTimeout(() => setActive(false), fadeAfter);\n    return () => clearTimeout(timer);\n  }, [latest, fadeAfter]);\n\n  return { events, latest, isAgentActive };\n}\n"]}

package/dist/presence.js

@@ -0,0 +1,5 @@
+export { useAgentActivity, useAgentActivityForScreen } from './chunk-X66JWQBB.js';
+export { wrapToolWithActivity } from './chunk-52S7XYZK.js';
+export { emitActivity, onActivity, readActivityHistory, resetActivityRegistry } from './chunk-JU2N4KK6.js';
+//# sourceMappingURL=presence.js.map
+//# sourceMappingURL=presence.js.map

package/dist/presence.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"presence.js"}

package/dist/registry-2DRURS6U.js

@@ -0,0 +1,3 @@
+export { emitActivity, onActivity, readActivityHistory, resetActivityRegistry } from './chunk-JU2N4KK6.js';
+//# sourceMappingURL=registry-2DRURS6U.js.map
+//# sourceMappingURL=registry-2DRURS6U.js.map

package/dist/registry-2DRURS6U.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"registry-2DRURS6U.js"}

package/dist/server-BsSwfemr.d.cts

@@ -0,0 +1,63 @@
+import { S as ServerInfo, a as ServerCapabilities, J as JsonRpcMessage, C as CallToolResult } from './types-aOQLTW0E.cjs';
+import { a as ToolRegistry } from './tool-host-BQuUygLF.cjs';
+
+type McpServerOptions = {
+    info: ServerInfo;
+    /** Defaults to { tools: { listChanged: true } } */
+    capabilities?: ServerCapabilities;
+    /** Free-text instructions surfaced to clients during initialize. */
+    instructions?: string;
+};
+type Transport = {
+    /** Called by the server when it has a message to deliver to the client. */
+    send: (message: JsonRpcMessage) => void;
+    /** Called by the server when it's torn down so the transport can clean up. */
+    close?: () => void;
+};
+/**
+ * MicroMcpServer — protocol-level MCP server, transport-agnostic.
+ *
+ * Use it like:
+ *
+ *   const server = new MicroMcpServer({ info: { name: "session", version: "0.1" } });
+ *   server.registerTool({ name: "...", inputSchema: { type: "object" } }, async (args) => ({...}));
+ *   const transport = new InProcessTransport();
+ *   server.attach(transport);
+ *   transport.deliver({ ... }); // client → server frames
+ *
+ * The same server can serve multiple transports (e.g. an in-process agent
+ * AND a relayed external client) by attaching each one.
+ */
+declare class MicroMcpServer extends ToolRegistry {
+    private transports;
+    private notifyListChangedScheduled;
+    readonly info: ServerInfo;
+    readonly capabilities: ServerCapabilities;
+    readonly instructions?: string;
+    constructor(options: McpServerOptions);
+    attach(transport: Transport): () => void;
+    detach(transport: Transport): void;
+    unregisterTool(name: string): void;
+    protected onToolsChanged(): void;
+    /**
+     * Receive a JSON-RPC frame from a client (called by the transport).
+     * The transport is responsible for sending the response back.
+     */
+    receive(transport: Transport, message: JsonRpcMessage): Promise<void>;
+    private handle;
+    private scheduleListChangedNotification;
+    private broadcast;
+    private toRpcError;
+}
+declare function rpcError(code: number, message: string, data?: any): {
+    data?: any;
+    code: number;
+    message: string;
+};
+/**
+ * Helper to build a CallToolResult from a string or structured value.
+ */
+declare function textResult(text: string, structured?: any): CallToolResult;
+declare function errorResult(text: string): CallToolResult;
+
+export { MicroMcpServer as M, type Transport as T, type McpServerOptions as a, errorResult as e, rpcError as r, textResult as t };

package/dist/server-Du3-IGqM.d.ts

@@ -0,0 +1,63 @@
+import { S as ServerInfo, a as ServerCapabilities, J as JsonRpcMessage, C as CallToolResult } from './types-aOQLTW0E.js';
+import { a as ToolRegistry } from './tool-host-C8JMMGYq.js';
+
+type McpServerOptions = {
+    info: ServerInfo;
+    /** Defaults to { tools: { listChanged: true } } */
+    capabilities?: ServerCapabilities;
+    /** Free-text instructions surfaced to clients during initialize. */
+    instructions?: string;
+};
+type Transport = {
+    /** Called by the server when it has a message to deliver to the client. */
+    send: (message: JsonRpcMessage) => void;
+    /** Called by the server when it's torn down so the transport can clean up. */
+    close?: () => void;
+};
+/**
+ * MicroMcpServer — protocol-level MCP server, transport-agnostic.
+ *
+ * Use it like:
+ *
+ *   const server = new MicroMcpServer({ info: { name: "session", version: "0.1" } });
+ *   server.registerTool({ name: "...", inputSchema: { type: "object" } }, async (args) => ({...}));
+ *   const transport = new InProcessTransport();
+ *   server.attach(transport);
+ *   transport.deliver({ ... }); // client → server frames
+ *
+ * The same server can serve multiple transports (e.g. an in-process agent
+ * AND a relayed external client) by attaching each one.
+ */
+declare class MicroMcpServer extends ToolRegistry {
+    private transports;
+    private notifyListChangedScheduled;
+    readonly info: ServerInfo;
+    readonly capabilities: ServerCapabilities;
+    readonly instructions?: string;
+    constructor(options: McpServerOptions);
+    attach(transport: Transport): () => void;
+    detach(transport: Transport): void;
+    unregisterTool(name: string): void;
+    protected onToolsChanged(): void;
+    /**
+     * Receive a JSON-RPC frame from a client (called by the transport).
+     * The transport is responsible for sending the response back.
+     */
+    receive(transport: Transport, message: JsonRpcMessage): Promise<void>;
+    private handle;
+    private scheduleListChangedNotification;
+    private broadcast;
+    private toRpcError;
+}
+declare function rpcError(code: number, message: string, data?: any): {
+    data?: any;
+    code: number;
+    message: string;
+};
+/**
+ * Helper to build a CallToolResult from a string or structured value.
+ */
+declare function textResult(text: string, structured?: any): CallToolResult;
+declare function errorResult(text: string): CallToolResult;
+
+export { MicroMcpServer as M, type Transport as T, type McpServerOptions as a, errorResult as e, rpcError as r, textResult as t };

package/dist/sharing/index.d.cts

@@ -1,4 +1,6 @@
-import { j as Transport, M as MicroMcpServer, b as JsonRpcMessage } from '../server-Bv985us3.cjs';
+import { J as JsonRpcMessage } from '../types-aOQLTW0E.cjs';
+import { T as Transport, M as MicroMcpServer } from '../server-BsSwfemr.cjs';
+import '../tool-host-BQuUygLF.cjs';
 
 /**
  * Session-token utilities. The token is a high-entropy secret; possession

package/dist/sharing/index.d.ts

@@ -1,4 +1,6 @@
-import { j as Transport, M as MicroMcpServer, b as JsonRpcMessage } from '../server-Bv985us3.js';
+import { J as JsonRpcMessage } from '../types-aOQLTW0E.js';
+import { T as Transport, M as MicroMcpServer } from '../server-Du3-IGqM.js';
+import '../tool-host-C8JMMGYq.js';
 
 /**
  * Session-token utilities. The token is a high-entropy secret; possession

package/dist/sharing.cjs

@@ -1,5 +1,58 @@
 'use strict';
 
+var __defProp = Object.defineProperty;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __esm = (fn, res) => function __init() {
+  return fn && (res = (0, fn[__getOwnPropNames(fn)[0]])(fn = 0)), res;
+};
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+
+// src/presence/registry.ts
+var registry_exports = {};
+__export(registry_exports, {
+  emitActivity: () => emitActivity,
+  onActivity: () => onActivity,
+  readActivityHistory: () => readActivityHistory,
+  resetActivityRegistry: () => resetActivityRegistry
+});
+function emitActivity(event) {
+  history.push(event);
+  if (history.length > HISTORY_CAP) history.splice(0, history.length - HISTORY_CAP);
+  for (const l of listeners) l(event);
+}
+function onActivity(listener, filter) {
+  const wrapped = filter ? (e) => {
+    if (matches(e, filter)) listener(e);
+  } : listener;
+  listeners.add(wrapped);
+  return () => listeners.delete(wrapped);
+}
+function readActivityHistory(filter) {
+  if (!filter) return history.slice();
+  return history.filter((e) => matches(e, filter));
+}
+function resetActivityRegistry() {
+  listeners.clear();
+  history.length = 0;
+}
+function matches(e, f) {
+  if (f.agentId !== void 0 && e.agentId !== f.agentId) return false;
+  if (f.screenId !== void 0 && e.target.screenId !== f.screenId) return false;
+  if (f.kind !== void 0 && e.target.kind !== f.kind) return false;
+  return true;
+}
+var HISTORY_CAP, listeners, history;
+var init_registry = __esm({
+  "src/presence/registry.ts"() {
+    HISTORY_CAP = 200;
+    listeners = /* @__PURE__ */ new Set();
+    history = [];
+  }
+});
+
 // src/sharing/token.ts
 var TOKEN_BYTES = 24;
 function createSessionDescriptor() {
@@ -151,6 +204,21 @@ function attachSseRelay(server, options) {
   transport.bindServer(server);
   server.attach(transport);
   transport.start();
+  Promise.resolve().then(() => (init_registry(), registry_exports)).then(({ onActivity: onActivity2 }) => {
+    const off = onActivity2((event) => {
+      transport.send({
+        jsonrpc: "2.0",
+        method: "notifications/agent_activity",
+        params: event
+      });
+    });
+    const origClose = transport.close.bind(transport);
+    transport.close = () => {
+      off();
+      origClose();
+    };
+  }).catch(() => {
+  });
   return transport;
 }