agentgraph-server 0.8.0__tar.gz → 0.9.0__tar.gz

agentgraph_server-0.9.0/.agents/skills/agentgraph/SKILL.md

@@ -0,0 +1,54 @@
+---
+name: agentgraph
+description: Use AgentGraph through its CLI or MCP tools to search and traverse selected local context, retrieve full source-backed evidence, fetch missing or stale resources, and troubleshoot connector availability.
+---
+
+# AgentGraph skill
+
+AgentGraph is a local graph of selected messages, documents, people, feeds, pages,
+and relationships. Use its CLI or connected MCP tools to investigate that context;
+do not query its database or connector internals directly.
+
+Prefer the connected MCP tools when AgentGraph is available through MCP. Use the
+`agentgraph` CLI when MCP is unavailable or when a terminal script is the natural
+interface. Do not query AgentGraph's SQLite database or connector internals directly.
+
+## Investigate
+
+1. Start with `search` for discovery. If the user supplied a graph ID, platform
+   reference, or indexed URL, use `get` directly instead.
+2. Read the full entity before making a source-backed claim. Search results and graph
+   traversals contain bounded snippets.
+3. Inspect direct edges or traverse only when relationships help answer the question.
+4. Resolve a stub or fetch a known resource when missing or stale content blocks the
+   answer, then repeat the read.
+5. Compare source dates and contents. Cite the source URL or entity ID and separate
+   source facts from conclusions drawn across sources.
+
+Use search filters when the type, source, author, time window, observation, or
+attachments are already known. A search without a query lists matching entities by
+date; a query ranks them by relevance.
+
+## Guardrails
+
+- A stub has neither a title nor content.
+- Use `source_created_at` and `source_updated_at` for source chronology; local
+  `created_at` and `updated_at` describe the graph record.
+- Browser observation alone updates `observed_at`; fetch, poll, and ingest do not
+  indicate that the user viewed a resource.
+- Check connector or authentication state only when availability, freshness, or a
+  graph operation calls it into question.
+- Confirm Person merges, deletion, credential removal, and removal of bookmark
+  protection with the user.
+- A multi-target deletion resolves every target before changing the graph; it either
+  deletes the resolved set or leaves the graph unchanged.
+
+## References
+
+- Read [references/commands.md](references/commands.md) for command syntax, MCP
+  mappings, filters, targets, stubs, and result limits.
+- Read [references/data-model.md](references/data-model.md) for entity types,
+  relationships, attachments, timestamps, and retention.
+- Read [references/operations.md](references/operations.md) for connector discovery,
+  authentication, fetching, downloads, polling, connector-owned commands, and server
+  transport.

{agentgraph_server-0.8.0 → agentgraph_server-0.9.0}/.agents/skills/agentgraph/references/commands.md

@@ -43,6 +43,11 @@ MCP search defaults to `refresh=false`; set it only when fresh connector-owned
 presentation metadata is needed. It does not replace a targeted source fetch for
 stale content.
 
+MCP tools return structured content: successes use `status="ok"` with a `data`
+object; expected failures use `status="error"`, an error `code`, and `message`, with
+the MCP error flag set. Search `data` includes `has_more`; entity payloads include
+`is_stub` and, when known, `source_url`.
+
 ## Stubs
 
 An entity is a stub when it has neither a title nor content. With the CLI, pass

{agentgraph_server-0.8.0 → agentgraph_server-0.9.0}/.agents/skills/agentgraph/references/operations.md

@@ -16,6 +16,11 @@ receive the full installed entity type catalog in the `search_entities_tool`
 description during tool discovery. Use `--verify` only when a live provider check is
 needed.
 
+Connector `last_synced_at` values come from successful poll timestamps in `sync_state`,
+aggregated across account-scoped cursors. A connector command may reset its own cursor
+through the generic command-effects path; after a reset, its status is `never` until the
+next successful poll.
+
 MCP equivalents are `list_connectors_tool`, `list_auth_providers_tool`,
 `authenticate_provider_tool`, and `remove_auth_provider_tool`.
 
@@ -70,13 +75,15 @@ forms are `run_connector_command_tool("web", ["observe", "<url-or-prefix>"])` an
 ```bash
 agentgraph download <entity-id|platform/ref> [--output <file-or-dir>] [--json]
 agentgraph bookmark <entity-id|platform/ref|url> [--remove] [--json]
-agentgraph delete <entity-id|platform/ref|url> [--json]
+agentgraph delete <entity-id|platform/ref|url>... [--json]
 agentgraph unify-persons <primary-person-id> <duplicate-person-id>... [--json]
 ```
 
-Use `download_entity_tool`, `bookmark_entity_tool`, `delete_entity_tool`, and
-`unify_persons_tool` through MCP. Confirm identity before person unification. The
-first Person is canonical and keeps its ID. Deletion removes connected edges.
+Use `download_entity_tool`, `bookmark_entity_tool`, `delete_entity_tool`,
+`delete_entities_tool`, and `unify_persons_tool` through MCP. Confirm identity before
+person unification. The first Person is canonical and keeps its ID. Multi-target
+deletion resolves every target before deleting any of them, removes connected edges,
+and returns compact references for the deleted entities.
 
 ## Server and skill setup
 
@@ -88,12 +95,17 @@ The server listens on a Unix socket (`AGENTGRAPH_SERVER_UDS_PATH`, default
 `~/.agentgraph/agentgraph.sock`) as well as TCP, because most agent sandboxes deny
 loopback TCP while permitting an allowlisted socket.
 
-`agentgraph poll` and connector or authentication commands that queue a poll or ingest
-always contact that service and have no local fallback; if sandboxed execution blocks
-one, request permission to contact the server or ask for the socket to be allowlisted,
-then retry. Reads and `fetch`/`download` follow `AGENTGRAPH_QUERY_TRANSPORT`
-(`auto` by default: socket, then TCP, then in-process), so they keep working when the
-server is unreachable.
+CLI polling and connector or authentication commands that queue a poll or ingest
+contact the local server. Reads and `fetch`/`download` follow
+`AGENTGRAPH_QUERY_TRANSPORT` (`auto` by default: socket, then TCP, then in-process),
+so they keep working when the server is unreachable. The MCP server can run polling
+and ingest locally when it cannot queue them on the local server.
+
+Run ordinary reads with the default transport. To diagnose connectivity, use
+`AGENTGRAPH_QUERY_TRANSPORT=server agentgraph search x --limit 1`; retry an affected
+read with `AGENTGRAPH_QUERY_TRANSPORT=in-process` only after an actual sandbox
+connection failure. See the Coding agent sandboxes section of the configuration docs
+for Unix-socket allowlist settings.
 
 ```bash
 agentgraph mcp-config
@@ -101,9 +113,11 @@ agentgraph mcp-serve
 agentgraph install-skill [agentgraph] [--target user|project] [--no-claude] [--force] [--json]
 ```
 
-`agentgraph mcp-config` prints local stdio setup for ChatGPT Desktop Work Mode and
-Claude Desktop. In ChatGPT Desktop, enter the printed executable in **Command to
-launch** and `mcp-serve` in **Arguments**; for Claude Desktop, add the printed JSON
-to its MCP configuration file.
+`agentgraph mcp-config` prints local stdio setup for ChatGPT Desktop Work Mode, Codex,
+Claude Desktop, and Claude Code. Prefer these MCP connections when they are available.
+In ChatGPT Desktop, enter the printed executable in **Command to launch** and
+`mcp-serve` in **Arguments**; for Claude Desktop, add the printed JSON to its MCP
+configuration file. Claude Code uses the printed user-scoped command so the server is
+available across projects.
 
 The skill installer is available only through the `agentgraph install-skill` CLI command.

{agentgraph_server-0.8.0/agentgraph_server.egg-info → agentgraph_server-0.9.0}/PKG-INFO

@@ -1,18 +1,18 @@
 Metadata-Version: 2.4
 Name: agentgraph-server
-Version: 0.8.0
+Version: 0.9.0
 Summary: A local-first CLI and MCP server that turns selected digital sources into a searchable graph for the AI agent you already use.
 Requires-Python: >=3.12
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: aiosqlite>=0.20.0
-Requires-Dist: agentgraph-connector-web<0.7,>=0.6.0
+Requires-Dist: agentgraph-connector-web<0.8,>=0.7.0
 Requires-Dist: apscheduler>=3.11.2
 Requires-Dist: click<8.4
 Requires-Dist: fastapi>=0.135.2
 Requires-Dist: fastembed>=0.8.0
 Requires-Dist: httpx>=0.28.1
-Requires-Dist: mcp>=1.26.0
+Requires-Dist: mcp<2,>=1.26.0
 Requires-Dist: numpy>=2.4.6
 Requires-Dist: pydantic>=2.12.5
 Requires-Dist: pydantic-settings>=2.13.1
@@ -22,21 +22,21 @@ Requires-Dist: sqlite-vec>=0.1.9
 Requires-Dist: typer>=0.24.1
 Requires-Dist: uvicorn>=0.42.0
 Provides-Extra: google
-Requires-Dist: agentgraph-connector-google<0.7,>=0.6.0; extra == "google"
+Requires-Dist: agentgraph-connector-google<0.7,>=0.6.1; extra == "google"
 Provides-Extra: slack
-Requires-Dist: agentgraph-connector-slack<0.7,>=0.6.0; extra == "slack"
+Requires-Dist: agentgraph-connector-slack<0.7,>=0.6.1; extra == "slack"
 Provides-Extra: discord
-Requires-Dist: agentgraph-connector-discord<0.7,>=0.6.0; extra == "discord"
+Requires-Dist: agentgraph-connector-discord<0.7,>=0.6.1; extra == "discord"
 Provides-Extra: rss
-Requires-Dist: agentgraph-connector-rss<0.7,>=0.6.0; extra == "rss"
+Requires-Dist: agentgraph-connector-rss<0.8,>=0.7.0; extra == "rss"
 Provides-Extra: web
-Requires-Dist: agentgraph-connector-web<0.7,>=0.6.0; extra == "web"
+Requires-Dist: agentgraph-connector-web<0.8,>=0.7.0; extra == "web"
 Provides-Extra: all
-Requires-Dist: agentgraph-connector-web<0.7,>=0.6.0; extra == "all"
-Requires-Dist: agentgraph-connector-google<0.7,>=0.6.0; extra == "all"
-Requires-Dist: agentgraph-connector-slack<0.7,>=0.6.0; extra == "all"
-Requires-Dist: agentgraph-connector-discord<0.7,>=0.6.0; extra == "all"
-Requires-Dist: agentgraph-connector-rss<0.7,>=0.6.0; extra == "all"
+Requires-Dist: agentgraph-connector-web<0.8,>=0.7.0; extra == "all"
+Requires-Dist: agentgraph-connector-google<0.7,>=0.6.1; extra == "all"
+Requires-Dist: agentgraph-connector-slack<0.7,>=0.6.1; extra == "all"
+Requires-Dist: agentgraph-connector-discord<0.7,>=0.6.1; extra == "all"
+Requires-Dist: agentgraph-connector-rss<0.8,>=0.7.0; extra == "all"
 Dynamic: license-file
 
 # AgentGraph
@@ -122,7 +122,7 @@ Connect the agent you already use:
 agentgraph mcp-config
 ```
 
-Use the printed instructions to connect ChatGPT Desktop Work Mode or Claude Desktop to the local stdio server. See [Install](docs-src/install.md) for the complete setup path.
+Use the printed instructions to connect ChatGPT Desktop Work Mode, Codex, Claude Desktop, or Claude Code to the local stdio server. MCP is the preferred connection; the installed skill provides CLI fallback workflows. See [Install](docs-src/install.md) for the complete setup path.
 
 ## What AgentGraph is and is not
 

{agentgraph_server-0.8.0 → agentgraph_server-0.9.0}/README.md

@@ -81,7 +81,7 @@ Connect the agent you already use:
 agentgraph mcp-config
 ```
 
-Use the printed instructions to connect ChatGPT Desktop Work Mode or Claude Desktop to the local stdio server. See [Install](docs-src/install.md) for the complete setup path.
+Use the printed instructions to connect ChatGPT Desktop Work Mode, Codex, Claude Desktop, or Claude Code to the local stdio server. MCP is the preferred connection; the installed skill provides CLI fallback workflows. See [Install](docs-src/install.md) for the complete setup path.
 
 ## What AgentGraph is and is not
 

{agentgraph_server-0.8.0 → agentgraph_server-0.9.0}/agentgraph/backends/sqlite/backend.py

@@ -68,6 +68,7 @@ _LIST_PAGE_ORDER_BY = {
 }
 _COLUMN_FILTERS = {"platform", "platform_entity_id", "entity_type"}
 _FTS_DELETE_CHUNK_SIZE = 500
+_PLATFORM_ENTITY_ID_LOOKUP_CHUNK_SIZE = 900
 _BUSY_TIMEOUT_MS = 5_000
 _SCHEMA_VERSION = 6
 
@@ -869,11 +870,14 @@ class SQLiteBackend(StorageBackend):
                     str(existing_row["content"]) if existing_row and existing_row["content"] else ""
                 )
                 fts_title = e.title if e.title is not None else existing_title
-                fts_content = e.content if e.content is not None else existing_content
+                fts_content = (
+                    e.content if e.content_searchable and e.content is not None else ""
+                )
                 rewrite_fts = (
                     existing_row is None
                     or fts_title != existing_title
-                    or fts_content != existing_content
+                    or (e.content_searchable and fts_content != existing_content)
+                    or not e.content_searchable
                 )
                 embedding = embeddings.get(e.platform_entity_id)
                 emb_blob = pack_embedding(embedding) if embedding else None
@@ -892,7 +896,10 @@ class SQLiteBackend(StorageBackend):
                     target_title = e.title if e.title is not None else existing_row["title"]
                     target_content = e.content if e.content is not None else existing_row["content"]
                     target_embedding = (
-                        emb_blob if emb_blob is not None else existing_row["content_embedding"]
+                        emb_blob if e.content_searchable and emb_blob is not None
+                        else existing_row["content_embedding"]
+                        if e.content_searchable
+                        else None
                     )
                     target_source_created = (
                         source_created
@@ -927,7 +934,7 @@ class SQLiteBackend(StorageBackend):
                         entity_type       = CASE WHEN entities.entity_type = 'Document' THEN EXCLUDED.entity_type ELSE entities.entity_type END,
                         title             = COALESCE(EXCLUDED.title, entities.title),
                         content           = COALESCE(EXCLUDED.content, entities.content),
-                        content_embedding = COALESCE(EXCLUDED.content_embedding, entities.content_embedding),
+                        content_embedding = CASE WHEN ? THEN COALESCE(EXCLUDED.content_embedding, entities.content_embedding) ELSE NULL END,
                         metadata          = EXCLUDED.metadata,
                         source_created_at = COALESCE(EXCLUDED.source_created_at, entities.source_created_at),
                         source_updated_at = COALESCE(EXCLUDED.source_updated_at, entities.source_updated_at),
@@ -953,6 +960,7 @@ class SQLiteBackend(StorageBackend):
                         local_updated,
                         e.retention_policy,
                         parent_id,
+                        e.content_searchable,
                         local_updated,
                     ],
                 )
@@ -1220,42 +1228,55 @@ class SQLiteBackend(StorageBackend):
 
     async def delete_entity(self, entity_id: str) -> EntityResult:
         """Delete one entity by internal ID. Edges cascade; FTS rows are removed explicitly."""
+        deleted = await self.delete_entities([entity_id])
+        return deleted[0]
+
+    async def delete_entities(self, entity_ids: list[str]) -> list[EntityResult]:
+        """Atomically delete entities, their edges, and their FTS rows."""
+        unique_ids = list(dict.fromkeys(entity_ids))
+        if not unique_ids:
+            raise ValueError("At least one entity ID is required")
         assert self._write_lock is not None
         async with self._write_lock:
             conn = self._conn_or_raise()
             await conn.execute("BEGIN IMMEDIATE")
             try:
-                await conn.execute(
-                    """
-                    UPDATE entities
-                    SET retention_parent_id = NULL, updated_at = ?
-                    WHERE retention_parent_id = ? AND bookmarked = 1
-                    """,
-                    [_now(), entity_id],
-                )
-                cursor = await conn.execute(
-                    """
-                    DELETE FROM entities
-                    WHERE id = ?
-                    RETURNING id, entity_type, platform, platform_entity_id,
-                              title, content, metadata, created_at, updated_at,
-                              source_created_at, source_updated_at, synced_at, observed_at,
-                              retention_policy, retention_parent_id,
-                              cumulative_observation_duration_ms, bookmarked
-                    """,
-                    [entity_id],
-                )
-                row = await cursor.fetchone()
-                if row is None:
-                    raise ValueError(f"Entity {entity_id!r} not found")
-                await conn.execute(
-                    "DELETE FROM entities_fts WHERE id NOT IN (SELECT id FROM entities)"
-                )
+                rows: list[aiosqlite.Row] = []
+                for start in range(0, len(unique_ids), _FTS_DELETE_CHUNK_SIZE):
+                    ids = unique_ids[start : start + _FTS_DELETE_CHUNK_SIZE]
+                    placeholders = ",".join("?" * len(ids))
+                    await conn.execute(
+                        f"""
+                        UPDATE entities
+                        SET retention_parent_id = NULL, updated_at = ?
+                        WHERE retention_parent_id IN ({placeholders}) AND bookmarked = 1
+                        """,
+                        [_now(), *ids],
+                    )
+                    cursor = await conn.execute(
+                        f"""
+                        DELETE FROM entities
+                        WHERE id IN ({placeholders})
+                        RETURNING id, entity_type, platform, platform_entity_id,
+                                  title, content, metadata, created_at, updated_at,
+                                  source_created_at, source_updated_at, synced_at, observed_at,
+                                  retention_policy, retention_parent_id,
+                                  cumulative_observation_duration_ms, bookmarked
+                        """,
+                        ids,
+                    )
+                    rows.extend(await cursor.fetchall())
+                    await conn.execute(
+                        f"DELETE FROM entities_fts WHERE id IN ({placeholders})", ids
+                    )
+                if len(rows) != len(unique_ids):
+                    raise ValueError("One or more entities were not found")
                 await conn.execute("COMMIT")
             except Exception:
                 await conn.execute("ROLLBACK")
                 raise
-        return _row_to_entity(row)
+        deleted_by_id = {str(row["id"]): _row_to_entity(row) for row in rows}
+        return [deleted_by_id[entity_id] for entity_id in unique_ids]
 
     # --- Read: entities ---
 
@@ -1546,6 +1567,30 @@ class SQLiteBackend(StorageBackend):
         )
         return _row_to_entity(row) if row else None
 
+    async def get_existing_platform_entity_ids(
+        self,
+        platform: str,
+        platform_entity_ids: list[str],
+    ) -> set[str]:
+        if not platform_entity_ids:
+            return set()
+
+        existing: set[str] = set()
+        for offset in range(0, len(platform_entity_ids), _PLATFORM_ENTITY_ID_LOOKUP_CHUNK_SIZE):
+            chunk = platform_entity_ids[
+                offset : offset + _PLATFORM_ENTITY_ID_LOOKUP_CHUNK_SIZE
+            ]
+            placeholders = ",".join("?" for _ in chunk)
+            rows = await self._fetchall(
+                f"""
+                SELECT platform_entity_id FROM entities
+                WHERE platform = ? AND platform_entity_id IN ({placeholders})
+                """,
+                [platform, *chunk],
+            )
+            existing.update(str(row["platform_entity_id"]) for row in rows)
+        return existing
+
     async def list_entities(
         self,
         entity_types: list[str] | None,
@@ -1992,6 +2037,9 @@ class SQLiteBackend(StorageBackend):
             [source, json.dumps(cursor), _now()],
         )
 
+    async def clear_cursor(self, source: str) -> None:
+        await self._execute("DELETE FROM sync_state WHERE source = ?", [source])
+
     # --- Connector support ---
 
     async def increment_observation_duration(
@@ -2129,6 +2177,26 @@ class SQLiteBackend(StorageBackend):
             result[row["platform"]] = datetime.fromisoformat(val) if val else None
         return result
 
+    async def get_sources_last_synced_at(
+        self, sources: list[str]
+    ) -> dict[str, datetime | None]:
+        if not sources:
+            return {}
+        rows = await self._fetchall(
+            "SELECT source, updated_at FROM sync_state"
+        )
+        result: dict[str, datetime | None] = dict.fromkeys(sources, None)
+        for source in sources:
+            matching = [
+                row["updated_at"]
+                for row in rows
+                if row["source"] == source or row["source"].startswith(f"{source}:")
+            ]
+            values = [datetime.fromisoformat(value) for value in matching if value]
+            if values:
+                result[source] = max(values)
+        return result
+
     async def reset_synced_at(self, platform: str, platform_entity_id: str) -> None:
         await self._execute(
             "UPDATE entities SET synced_at = NULL WHERE platform = ? AND platform_entity_id = ?",

{agentgraph_server-0.8.0 → agentgraph_server-0.9.0}/agentgraph/cli.py

@@ -437,6 +437,13 @@ def connector_command(
     try:
         result = type(connector).run_cli_command(command_args)
         effects = type(connector).command_effects(command_args, result)
+        if effects.reset_cursors:
+            from agentgraph.cli_query import run_graph_operation
+            from agentgraph.connectors.command_effects import execute_cursor_resets
+
+            result["reset_cursors"] = run_graph_operation(
+                lambda: execute_cursor_resets(effects)
+            )
         if effects.delete_entities:
             from agentgraph.cli_query import run_graph_operation
             from agentgraph.connectors.command_effects import execute_deletions
@@ -737,13 +744,13 @@ def bookmark(
 
 @app.command("delete")
 def delete_cmd(
-    target: str = typer.Argument(..., help="Entity ID, UUID prefix, platform ref, or URL"),
+    targets: list[str] = typer.Argument(..., help="Entity IDs, UUID prefixes, platform refs, or URLs"),
     json: bool = typer.Option(False, "--json", help="Output as JSON"),
 ) -> None:
-    """Delete an entity from the graph."""
+    """Delete one or more entities from the graph."""
     from agentgraph.cli_query import cmd_delete
 
-    cmd_delete(target=target, as_json=json)
+    cmd_delete(targets=targets, as_json=json)
 
 
 @app.command("unify-persons")
@@ -842,7 +849,7 @@ def mcp_config() -> None:
     typer.echo()
     typer.echo("Claude Code:")
     typer.echo("  Register the server from your terminal:\n")
-    typer.echo(f"  claude mcp add agentgraph -- {binary} mcp-serve")
+    typer.echo(f"  claude mcp add --transport stdio --scope user agentgraph -- {binary} mcp-serve")
     typer.echo()
     typer.echo("Every client above runs the same server. Reads follow")
     typer.echo("AGENTGRAPH_QUERY_TRANSPORT: by default the local server when one is")

{agentgraph_server-0.8.0 → agentgraph_server-0.9.0}/agentgraph/cli_query.py

@@ -342,7 +342,22 @@ def cmd_bookmark(target: str, bookmarked: bool, as_json: bool) -> None:
     console.print(f"[green]{action}:[/green] {label} [{result['id'][:8]}]")
 
 
-def cmd_delete(target: str, as_json: bool) -> None:
+def cmd_delete(targets: list[str], as_json: bool) -> None:
+    if len(targets) == 1:
+        _cmd_delete_one(targets[0], as_json)
+        return
+
+    async def operation(client: QueryClient) -> dict[str, Any]:
+        return await client.delete_many(targets)
+
+    result = _run_with_client(operation)
+    if as_json:
+        console.print_json(json.dumps(result, default=str))
+        return
+    console.print(f"[green]Deleted {result['deleted_count']} entities.[/green]")
+
+
+def _cmd_delete_one(target: str, as_json: bool) -> None:
     async def operation(client: QueryClient) -> dict[str, Any]:
         return await client.delete(target)
 

{agentgraph_server-0.8.0 → agentgraph_server-0.9.0}/agentgraph/connectors/base.py

@@ -105,6 +105,7 @@ class ConnectorCommandEffects:
     ingest_account_id: str | None = None
     delete_entities: tuple[EntityReference, ...] = ()
     fetch_references: tuple[SourceReference, ...] = ()
+    reset_cursors: tuple[str, ...] = ()
 
 
 class PersonRecord(BaseModel):
@@ -122,6 +123,7 @@ class EntityRecord(BaseModel):
     platform_entity_id: str
     title: str | None = None
     content: str | None = None
+    content_searchable: bool = True
     source_created_at: datetime | None = None
     source_updated_at: datetime | None = None
     metadata: dict[str, str | int | float | bool | None] = {}

{agentgraph_server-0.8.0 → agentgraph_server-0.9.0}/agentgraph/connectors/command_effects.py

@@ -39,6 +39,16 @@ async def execute_deletions(effects: ConnectorCommandEffects) -> list[dict[str,
     return deleted
 
 
+async def execute_cursor_resets(effects: ConnectorCommandEffects) -> list[str]:
+    """Clear connector-requested cursors and return the sources that were reset."""
+    from agentgraph.core.context import get_backend
+
+    backend = get_backend()
+    for source in effects.reset_cursors:
+        await backend.clear_cursor(source)
+    return list(effects.reset_cursors)
+
+
 async def execute_fetches(effects: ConnectorCommandEffects) -> list[dict[str, Any]]:
     """Fetch connector-owned references and persist their returned batches."""
     from agentgraph.connectors.registry import get_connector

{agentgraph_server-0.8.0 → agentgraph_server-0.9.0}/agentgraph/connectors/feed.py

@@ -92,6 +92,13 @@ class TombstoneMutation(BaseModel):
     target: MutationTarget
 
 
+class TombstoneBatchMutation(BaseModel):
+    event_id: UUID = Field(default_factory=uuid4)
+    kind: Literal["tombstone_batch"] = "tombstone_batch"
+    occurred_at: datetime = Field(default_factory=lambda: datetime.now(UTC))
+    targets: list[MutationTarget] = Field(min_length=1)
+
+
 class EntityUpsertMutation(BaseModel):
     event_id: UUID = Field(default_factory=uuid4)
     kind: Literal["upsert"] = "upsert"
@@ -102,7 +109,11 @@ class EntityUpsertMutation(BaseModel):
 
 
 type MutationEvent = (
-    ObservationMutation | BookmarkMutation | TombstoneMutation | EntityUpsertMutation
+    ObservationMutation
+    | BookmarkMutation
+    | TombstoneMutation
+    | TombstoneBatchMutation
+    | EntityUpsertMutation
 )
 
 

{agentgraph_server-0.8.0 → agentgraph_server-0.9.0}/agentgraph/connectors/status.py

@@ -174,7 +174,7 @@ async def connector_status_items(
         for delegated_source in type(connector).poll_delegates:
             poll_delegators.setdefault(delegated_source, []).append(connector.source)
 
-    last_synced_by_platform = await backend.get_platforms_last_synced_at(
+    last_synced_by_platform = await backend.get_sources_last_synced_at(
         [connector.source for connector in connectors]
     )
 

{agentgraph_server-0.8.0 → agentgraph_server-0.9.0}/agentgraph/core/storage.py

@@ -76,6 +76,11 @@ class StorageBackend(ABC):
         """Delete an entity and return the deleted entity."""
         ...
 
+    @abstractmethod
+    async def delete_entities(self, entity_ids: list[str]) -> list[EntityResult]:
+        """Atomically delete entities and return their deleted snapshots."""
+        ...
+
     # --- Read: entities ---
 
     @abstractmethod
@@ -127,6 +132,15 @@ class StorageBackend(ABC):
         content_limit: int | None = None,
     ) -> EntityResult | None: ...
 
+    @abstractmethod
+    async def get_existing_platform_entity_ids(
+        self,
+        platform: str,
+        platform_entity_ids: list[str],
+    ) -> set[str]:
+        """Return the supplied platform entity IDs that are already stored."""
+        ...
+
     @abstractmethod
     async def list_entities(
         self,
@@ -234,6 +248,11 @@ class StorageBackend(ABC):
     @abstractmethod
     async def save_cursor(self, source: str, cursor: dict[str, Any]) -> None: ...
 
+    @abstractmethod
+    async def clear_cursor(self, source: str) -> None:
+        """Remove a source cursor so its next poll starts from an empty state."""
+        ...
+
     # --- Connector support ---
 
     @abstractmethod
@@ -284,6 +303,13 @@ class StorageBackend(ABC):
             for platform in platforms
         }
 
+    @abstractmethod
+    async def get_sources_last_synced_at(
+        self, sources: list[str]
+    ) -> dict[str, datetime | None]:
+        """Return the latest successful poll timestamp for each connector source."""
+        ...
+
     @abstractmethod
     async def reset_synced_at(
         self, platform: str, platform_entity_id: str