agentgraph-server 0.6.0__tar.gz → 0.6.1__tar.gz

{agentgraph_server-0.6.0/.agents/skills/AgentGraph → agentgraph_server-0.6.1/.agents/skills/agentgraph}/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: AgentGraph
+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_server-0.6.0/.agents/skills/AgentGraph → agentgraph_server-0.6.1/.agents/skills/agentgraph}/references/data-model.md

@@ -11,8 +11,10 @@
 | `Message` | Chat messages. Chat images and uploads are stored in `metadata.attachments`. |
 | `Person` | Source identities and confirmed cross-source identity merges. |
 | `Spreadsheet` | Google Sheets and other spreadsheet resources. |
+| `Task` | Tracked work items such as Jira issues. Issue key, status, and assignee live in `metadata`. |
+| `Video` | Recorded videos such as Looms. The transcript is indexed as content and `metadata.web_url` links to the video. |
 
-The valid core model does not currently include `Task` or `Project`.
+The valid core model does not currently include `Project`.
 
 ## Relationships
 

{agentgraph_server-0.6.0/.agents/skills/AgentGraph → agentgraph_server-0.6.1/.agents/skills/agentgraph}/references/operations.md

@@ -3,16 +3,16 @@
 ## Availability and authentication
 
 ```bash
-agentgraph connectors [--verify] [--json]
+agentgraph list-connectors [--verify] [--json]
 agentgraph auth [--verify] [--json] status
 agentgraph auth <provider> [--add] [--account <account-id>]
 agentgraph auth remove <provider> [--account <account-id>] [--json]
 ```
 
-Use `agentgraph connectors --json` to discover installed connector source names,
+Use `agentgraph list-connectors --json` to discover installed connector source names,
 valid platform values, URL ownership, polling delegation, and sync state. Do not rely
 on a hardcoded platform list. Use `--verify` only when a live provider check is
-needed.
+needed. Without `--json`, the CLI renders the same status as an operator-facing table.
 
 MCP equivalents are `list_connectors_tool`, `list_auth_providers_tool`,
 `authenticate_provider_tool`, and `remove_auth_provider_tool`.
@@ -45,6 +45,22 @@ agentgraph connector gmail ingest [--account <account-id>] [--json]
 The MCP form is `run_connector_command_tool("gmail", ["ingest", ...])`. There is no
 top-level `agentgraph ingest` command or `ingest_connector_tool`.
 
+For an oversized HTML page, request a one-off web fetch that removes style, script,
+noscript, and comment blocks before applying the response-size limit:
+
+```bash
+agentgraph connector web fetch <url> --compact [--json]
+```
+
+The MCP form is `run_connector_command_tool("web", ["fetch", "<url>", "--compact"])`.
+Compaction applies only to that command; ordinary fetches, bookmarks, observations, and
+RSS article hydration retain their default behavior.
+
+Configure browser observation rules with `agentgraph connector web observe <url-or-prefix>`
+and remove them with `agentgraph connector web observe <url-or-prefix> --remove`. The MCP
+forms are `run_connector_command_tool("web", ["observe", "<url-or-prefix>"])` and
+`run_connector_command_tool("web", ["observe", "<url-or-prefix>", "--remove"])`.
+
 ## Files and retained context
 
 ```bash
@@ -71,7 +87,12 @@ commands, request permission to contact the configured localhost server and retr
 ```bash
 agentgraph mcp-config
 agentgraph mcp-serve
-agentgraph install-skill [AgentGraph] [--target user|project] [--no-claude] [--force] [--json]
+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.
+
 The skill installer is available only through the `agentgraph install-skill` CLI command.

{agentgraph_server-0.6.0 → agentgraph_server-0.6.1}/.agents/skills/slack-auth/SKILL.md

@@ -28,8 +28,10 @@ permission in the target workspace.
 Admins create AgentGraph at `https://api.slack.com/apps` with **Create New App →
 From an app manifest**, select the target workspace, paste the manifest printed by
 AgentGraph into Slack's **JSON** tab, approve it, and enter its Client ID. The
-manifest includes the only
-supported callback, `http://localhost:8766/slack/oauth/callback`.
+manifest includes the callback, which defaults to `http://localhost:8766/slack/oauth/callback`; set
+`AGENTGRAPH_SLACK_OAUTH_CALLBACK_PORT` before setup to use another local port. The
+manifest printed by AgentGraph uses that port, which must match the Slack app's
+registered redirect URL.
 
 Non-admins choose either **Enter a Client ID provided by a Slack admin** or **Set up
 the AgentGraph Slack App**. The setup path checks whether the target workspace

{agentgraph_server-0.6.0 → agentgraph_server-0.6.1}/PKG-INFO

@@ -1,12 +1,12 @@
 Metadata-Version: 2.4
 Name: agentgraph-server
-Version: 0.6.0
+Version: 0.6.1
 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.6,>=0.5.0
+Requires-Dist: agentgraph-connector-web<0.7,>=0.5.4
 Requires-Dist: apscheduler>=3.11.2
 Requires-Dist: click<8.4
 Requires-Dist: fastapi>=0.135.2
@@ -16,26 +16,27 @@ Requires-Dist: mcp>=1.26.0
 Requires-Dist: numpy>=2.4.6
 Requires-Dist: pydantic>=2.12.5
 Requires-Dist: pydantic-settings>=2.13.1
+Requires-Dist: questionary>=2.1.1
 Requires-Dist: rich>=14.3.3
 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.6,>=0.5.0; extra == "google"
+Requires-Dist: agentgraph-connector-google<0.7,>=0.5.4; extra == "google"
 Provides-Extra: slack
-Requires-Dist: agentgraph-connector-slack<0.6,>=0.5.0; extra == "slack"
+Requires-Dist: agentgraph-connector-slack<0.7,>=0.5.4; extra == "slack"
 Provides-Extra: discord
-Requires-Dist: agentgraph-connector-discord<0.6,>=0.5.0; extra == "discord"
+Requires-Dist: agentgraph-connector-discord<0.7,>=0.5.4; extra == "discord"
 Provides-Extra: rss
-Requires-Dist: agentgraph-connector-rss<0.6,>=0.5.0; extra == "rss"
+Requires-Dist: agentgraph-connector-rss<0.7,>=0.5.4; extra == "rss"
 Provides-Extra: web
-Requires-Dist: agentgraph-connector-web<0.6,>=0.5.0; extra == "web"
+Requires-Dist: agentgraph-connector-web<0.7,>=0.5.4; extra == "web"
 Provides-Extra: all
-Requires-Dist: agentgraph-connector-web<0.6,>=0.5.0; extra == "all"
-Requires-Dist: agentgraph-connector-google<0.6,>=0.5.0; extra == "all"
-Requires-Dist: agentgraph-connector-slack<0.6,>=0.5.0; extra == "all"
-Requires-Dist: agentgraph-connector-discord<0.6,>=0.5.0; extra == "all"
-Requires-Dist: agentgraph-connector-rss<0.6,>=0.5.0; extra == "all"
+Requires-Dist: agentgraph-connector-web<0.7,>=0.5.4; extra == "all"
+Requires-Dist: agentgraph-connector-google<0.7,>=0.5.4; extra == "all"
+Requires-Dist: agentgraph-connector-slack<0.7,>=0.5.4; extra == "all"
+Requires-Dist: agentgraph-connector-discord<0.7,>=0.5.4; extra == "all"
+Requires-Dist: agentgraph-connector-rss<0.7,>=0.5.4; extra == "all"
 Dynamic: license-file
 
 # AgentGraph
@@ -46,7 +47,7 @@ AgentGraph is a local-first, self-hosted CLI and MCP server that turns the sourc
 
 > **AgentGraph stores context; your agent reasons over it.** It is not an agent, chatbot, hosted graph service, or replacement for the tools you already use.
 
-[See the demo](docs-src/demo.md) · [Install](docs-src/install.md) · [Documentation](https://simonexmachina.github.io/agent-graph/) · [Chrome extension](https://chromewebstore.google.com/detail/agentgraph-extension/iilkfclglabllelhjacijldknapbhidi)
+[See the demo](docs-src/demo.md) · [Install](docs-src/install.md) · [Documentation](https://agentgraph.simonwa.de/) · [Chrome extension](https://chromewebstore.google.com/detail/agentgraph-extension/iilkfclglabllelhjacijldknapbhidi)
 
 <picture>
   <source media="(prefers-color-scheme: dark)" srcset="docs-src/assets/diagrams/architecture-overview-dark.svg">
@@ -110,7 +111,7 @@ agentgraph serve
 Install the [AgentGraph Chrome extension](https://chromewebstore.google.com/detail/agentgraph-extension/iilkfclglabllelhjacijldknapbhidi), browse a supported resource, then verify that context landed:
 
 ```bash
-agentgraph connectors
+agentgraph list-connectors
 agentgraph search "project kickoff notes"
 agentgraph traverse <entity-id> --depth 2
 ```
@@ -121,7 +122,7 @@ Connect the agent you already use:
 agentgraph mcp-config
 ```
 
-Use the printed stdio configuration with Claude Desktop, Claude Code, Codex, or another compatible MCP client. ChatGPT developer mode uses the streamable HTTP `/mcp` endpoint through HTTPS. See [Install](docs-src/install.md) for the complete setup path.
+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.
 
 ## What AgentGraph is and is not
 

{agentgraph_server-0.6.0 → agentgraph_server-0.6.1}/README.md

@@ -6,7 +6,7 @@ AgentGraph is a local-first, self-hosted CLI and MCP server that turns the sourc
 
 > **AgentGraph stores context; your agent reasons over it.** It is not an agent, chatbot, hosted graph service, or replacement for the tools you already use.
 
-[See the demo](docs-src/demo.md) · [Install](docs-src/install.md) · [Documentation](https://simonexmachina.github.io/agent-graph/) · [Chrome extension](https://chromewebstore.google.com/detail/agentgraph-extension/iilkfclglabllelhjacijldknapbhidi)
+[See the demo](docs-src/demo.md) · [Install](docs-src/install.md) · [Documentation](https://agentgraph.simonwa.de/) · [Chrome extension](https://chromewebstore.google.com/detail/agentgraph-extension/iilkfclglabllelhjacijldknapbhidi)
 
 <picture>
   <source media="(prefers-color-scheme: dark)" srcset="docs-src/assets/diagrams/architecture-overview-dark.svg">
@@ -70,7 +70,7 @@ agentgraph serve
 Install the [AgentGraph Chrome extension](https://chromewebstore.google.com/detail/agentgraph-extension/iilkfclglabllelhjacijldknapbhidi), browse a supported resource, then verify that context landed:
 
 ```bash
-agentgraph connectors
+agentgraph list-connectors
 agentgraph search "project kickoff notes"
 agentgraph traverse <entity-id> --depth 2
 ```
@@ -81,7 +81,7 @@ Connect the agent you already use:
 agentgraph mcp-config
 ```
 
-Use the printed stdio configuration with Claude Desktop, Claude Code, Codex, or another compatible MCP client. ChatGPT developer mode uses the streamable HTTP `/mcp` endpoint through HTTPS. See [Install](docs-src/install.md) for the complete setup path.
+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.
 
 ## What AgentGraph is and is not
 

{agentgraph_server-0.6.0 → agentgraph_server-0.6.1}/agentgraph/backends/sqlite/backend.py

@@ -64,7 +64,7 @@ _LIST_PAGE_ORDER_BY = {
 _COLUMN_FILTERS = {"platform", "platform_entity_id", "entity_type"}
 _FTS_DELETE_CHUNK_SIZE = 500
 _BUSY_TIMEOUT_MS = 5_000
-_SCHEMA_VERSION = 3
+_SCHEMA_VERSION = 4
 
 
 def _now() -> str:
@@ -291,6 +291,10 @@ class SQLiteBackend(StorageBackend):
         await conn.execute(
             "CREATE INDEX IF NOT EXISTS idx_entities_platform_type_observed_at ON entities(platform, entity_type, observed_at DESC)"
         )
+        await conn.execute(
+            "CREATE INDEX IF NOT EXISTS idx_entities_platform_type_feed_updated "
+            "ON entities(platform, entity_type, json_extract(metadata, '$.feed_url'), updated_at DESC)"
+        )
 
     async def _retention_policy_needs_migration(self) -> bool:
         """Return whether the entity policy constraint lacks persistent support."""
@@ -348,7 +352,8 @@ class SQLiteBackend(StorageBackend):
         observed = "NULL"
         if "observed_at" in columns and "cumulative_observation_duration_ms" in columns:
             observed = (
-                "CASE WHEN entity_type IN ('Channel', 'Document', 'Email', 'Folder', 'Spreadsheet') "
+                "CASE WHEN entity_type IN "
+                "('Channel', 'Document', 'Email', 'Folder', 'Spreadsheet', 'Task', 'Video') "
                 "AND cumulative_observation_duration_ms > 0 THEN observed_at ELSE NULL END"
             )
         observed = (
@@ -1454,6 +1459,59 @@ class SQLiteBackend(StorageBackend):
             )
         return [_row_to_entity(row) for row in rows]
 
+    async def list_recent_metadata_by_group(
+        self,
+        entity_type: str,
+        filters: dict[str, str],
+        group_metadata_key: str,
+        group_values: list[str],
+        per_group_limit: int,
+        order_by: str,
+    ) -> list[dict[str, Any]]:
+        if not group_values or per_group_limit <= 0:
+            return []
+        if order_by not in _VALID_ORDER_BY:
+            order_by = "updated_at"
+
+        params: list[Any] = [entity_type]
+        clauses: list[str] = []
+        for key, value in filters.items():
+            if key in _COLUMN_FILTERS:
+                clauses.append(f"e.{key} = ?")
+            else:
+                clauses.append(f"json_extract(e.metadata, '$.{key}') = ?")
+            params.append(value)
+
+        group_path = f"$.{group_metadata_key}"
+        value_placeholders = ", ".join("?" for _ in group_values)
+        clauses.append(f"json_extract(e.metadata, ?) IN ({value_placeholders})")
+        where_extra = " AND ".join(clauses)
+
+        with timed(
+            "sqlite.list_recent_metadata_by_group",
+            entity_type=entity_type,
+            per_group_limit=per_group_limit,
+            group_count=len(group_values),
+        ):
+            rows = await self._fetchall(
+                f"""
+                SELECT metadata FROM (
+                    SELECT e.metadata,
+                           json_extract(e.metadata, ?) AS group_value,
+                           ROW_NUMBER() OVER (
+                               PARTITION BY json_extract(e.metadata, ?)
+                               ORDER BY e.{order_by} DESC
+                           ) AS group_rank
+                    FROM entities e
+                    WHERE e.entity_type = ? AND {where_extra}
+                )
+                WHERE group_rank <= ?
+                ORDER BY group_value, group_rank
+                """,
+                [group_path, group_path, *params, group_path, *group_values, per_group_limit],
+            )
+        return [json.loads(row["metadata"]) if row["metadata"] else {} for row in rows]
+
     # --- Read: edges ---
 
     async def get_edges(

{agentgraph_server-0.6.0 → agentgraph_server-0.6.1}/agentgraph/backends/sqlite/schema.sql

@@ -68,6 +68,8 @@ CREATE INDEX IF NOT EXISTS idx_entities_type_created_at ON entities(entity_type,
 CREATE INDEX IF NOT EXISTS idx_entities_type_updated_at ON entities(entity_type, updated_at DESC);
 CREATE INDEX IF NOT EXISTS idx_entities_platform_observed_at_id ON entities(platform, observed_at DESC, id ASC);
 CREATE INDEX IF NOT EXISTS idx_entities_platform_type_observed_at ON entities(platform, entity_type, observed_at DESC);
+CREATE INDEX IF NOT EXISTS idx_entities_platform_type_feed_updated
+    ON entities(platform, entity_type, json_extract(metadata, '$.feed_url'), updated_at DESC);
 
 -- Edge indexes
 CREATE INDEX IF NOT EXISTS idx_edges_source  ON edges(source_entity_id);

{agentgraph_server-0.6.0 → agentgraph_server-0.6.1}/agentgraph/cli.py

@@ -12,7 +12,10 @@ from importlib.metadata import PackageNotFoundError
 from importlib.metadata import version as package_version
 from typing import TYPE_CHECKING, cast
 
+import questionary  # type: ignore[import-untyped]
 import typer
+from rich.console import Console
+from rich.table import Table
 
 if TYPE_CHECKING:
     from agentgraph.connectors.base import BaseConnector
@@ -22,6 +25,7 @@ app = typer.Typer(
     help="Local knowledge graph for AI agents.",
     no_args_is_help=True,
 )
+console = Console()
 
 
 def _version_callback(value: bool) -> None:
@@ -81,6 +85,20 @@ def _status_label(status: str) -> str:
     )
 
 
+def _connector_auth_label(item: dict[str, object]) -> str:
+    """Build the authentication cell for a connector status row."""
+    status = item["auth_status"]
+    if status is None:
+        return ""
+
+    status_label = str(status)
+    auth = _status_label(status_label)
+    detail = item["auth_detail"]
+    if detail:
+        auth = f"{auth} ({detail})" if status_label != "ok" else f"{auth} as {detail}"
+    return f"{auth} via {item['auth_provider']}"
+
+
 def _server_is_running() -> bool:
     """Return whether the configured AgentGraph server responds to health checks."""
     from agentgraph.config import get_settings
@@ -367,7 +385,7 @@ def connector_command(
     help: bool = typer.Option(False, "--help", help="Show this message and exit."),
 ) -> None:
     """Run a connector-owned command."""
-    from agentgraph.connectors.registry import bootstrap, get_connector
+    from agentgraph.connectors.registry import bootstrap, get_connector, get_connector_load_error
 
     if source is None:
         from typer.rich_utils import rich_format_help
@@ -378,6 +396,10 @@ def connector_command(
     bootstrap()
     connector = get_connector(source)
     if connector is None:
+        if error := get_connector_load_error(source):
+            typer.echo(f"Failed to load connector '{source}': {error}", err=True)
+            typer.echo("Reinstall AgentGraph and its connector dependencies, then retry.", err=True)
+            raise typer.Exit(code=1)
         typer.echo(f"Unknown connector '{source}'", err=True)
         raise typer.Exit(code=1)
 
@@ -394,6 +416,17 @@ def connector_command(
             from agentgraph.connectors.command_effects import execute_deletions
 
             result["deleted_entities"] = run_graph_operation(lambda: execute_deletions(effects))
+        if effects.fetch_references:
+            from agentgraph.cli_query import run_graph_operation
+            from agentgraph.connectors.command_effects import (
+                execute_fetches,
+                fetch_effect_error_hint,
+            )
+
+            result["fetched"] = run_graph_operation(
+                lambda: execute_fetches(effects),
+                error_hint=lambda error: fetch_effect_error_hint(effects, error, "cli"),
+            )
         if effects.poll:
             from agentgraph.cli_sync import queue_connector_poll
 
@@ -418,8 +451,8 @@ def connector_command(
     typer.echo(type(connector).format_cli_result(result))
 
 
-@app.command()
-def connectors(
+@app.command(name="list-connectors")
+def list_connectors(
     json: bool = typer.Option(False, "--json", help="Output as JSON"),
     verify: bool = typer.Option(
         False, "--verify", help="Live-check connector credentials with provider APIs"
@@ -443,23 +476,22 @@ def connectors(
         typer.echo(_json.dumps(items, indent=2))
         return
 
+    table = Table(title="Connectors", show_lines=True)
+    table.add_column("Connector", style="bold", no_wrap=True)
+    table.add_column("Description", ratio=1)
+    table.add_column("Auth")
+    table.add_column("Sync")
+    table.add_column("Last sync", no_wrap=True)
     for item in items:
-        sync = str(item["sync"])
-        last_sync = str(item["last_sync"])
         desc = item["description"] or item["source"]
-        typer.echo(f"  {item['source']:<12}  {desc}")
-        status = item["auth_status"]
-        if status is None:
-            typer.echo(f"  {'':<12}  sync: {sync}  |  last sync: {last_sync}")
-            continue
-        status_label = str(status)
-        detail = item["auth_detail"]
-        auth = _status_label(status_label)
-        if detail:
-            auth = f"{auth} ({detail})" if status_label != "ok" else f"{auth} as {detail}"
-        typer.echo(
-            f"  {'':<12}  auth: {auth} via {item['auth_provider']}  |  sync: {sync}  |  last sync: {last_sync}"
+        table.add_row(
+            str(item["source"]),
+            str(desc),
+            _connector_auth_label(item),
+            str(item["sync"]),
+            str(item["last_sync"]),
         )
+    console.print(table)
 
 
 @app.command()
@@ -657,7 +689,7 @@ def onboard() -> None:
         prompt: str = getattr(connector, "onboard_prompt", None) or f"Set up {label}?"
         description: str = getattr(connector, "auth_description", None) or label.title()
         typer.echo(f"Step {i}/{total}: {description}")
-        if typer.confirm(f"  {prompt}", default=True):
+        if questionary.confirm(f"  {prompt}", default=True).ask():
             type(connector).run_auth_flow()
         else:
             typer.echo("  Skipped.")
@@ -689,30 +721,22 @@ def mcp_config() -> None:
         }
     }
 
-    typer.echo("\nFor stdio MCP clients, add this to your MCP client config:\n")
-    typer.echo("  Claude Desktop:  ~/Library/Application Support/Claude/claude_desktop_config.json")
-    typer.echo("  Claude Code:     ~/.claude/mcp.json  (or .claude/mcp.json in your project)\n")
-    typer.echo(json.dumps(config, indent=2))
-    typer.echo()
-    typer.echo("For ChatGPT developer mode, do not use the stdio JSON above.")
-    typer.echo("Run a streamable HTTP MCP server:")
-    typer.echo(f"  {binary} mcp-serve --transport streamable-http --port 8808")
-    typer.echo("Local endpoint:")
-    typer.echo("  http://127.0.0.1:8808/mcp")
-    typer.echo("ChatGPT requires a reachable HTTPS URL. Use Secure MCP Tunnel, ngrok,")
-    typer.echo("or Cloudflare Tunnel, then create an app/connector in ChatGPT Developer mode")
-    typer.echo("with the public URL ending in /mcp, for example:")
-    typer.echo("  https://your-tunnel.example/mcp")
+    typer.echo("\nChatGPT Desktop Work Mode:")
+    typer.echo("  Add a local MCP server in the MCP configuration screen.")
+    typer.echo("  Command to launch:")
+    typer.echo(f"  {binary}")
+    typer.echo("  Arguments:")
+    typer.echo("  mcp-serve")
     typer.echo()
-    typer.echo("SSE is also supported by the server if your MCP client needs it:")
-    typer.echo(f"  {binary} mcp-serve --transport sse --port 8808")
-    typer.echo("  http://127.0.0.1:8808/sse")
+    typer.echo("Claude Desktop:")
+    typer.echo("  Add this to ~/Library/Application Support/Claude/claude_desktop_config.json:\n")
+    typer.echo(json.dumps(config, indent=2))
     typer.echo()
 
 
 @app.command()
 def install_skill(
-    skill: str = typer.Argument("AgentGraph", help="Bundled skill to install"),
+    skill: str = typer.Argument("agentgraph", help="Bundled skill to install"),
     target: str = typer.Option(
         "user",
         "--target",

{agentgraph_server-0.6.0 → agentgraph_server-0.6.1}/agentgraph/cli_query.py

@@ -24,19 +24,28 @@ async def _with_backend[T](operation: Callable[[], Awaitable[T]]) -> T:
         return await operation()
 
 
-def _run[T](operation: Callable[[], Awaitable[T]]) -> T:
+def _run[T](
+    operation: Callable[[], Awaitable[T]],
+    error_hint: Callable[[Exception], str | None] | None = None,
+) -> T:
     """Run one graph operation with a configured backend and concise CLI errors."""
     try:
         return asyncio.run(_with_backend(operation))
     except Exception as exc:
         console.print("[red]AgentGraph command failed:[/red] ", end="")
         console.print(str(exc), markup=False, highlight=False)
+        hint = error_hint(exc) if error_hint is not None else None
+        if hint:
+            console.print(hint, markup=False, highlight=False)
         raise SystemExit(1) from exc
 
 
-def run_graph_operation[T](operation: Callable[[], Awaitable[T]]) -> T:
+def run_graph_operation[T](
+    operation: Callable[[], Awaitable[T]],
+    error_hint: Callable[[Exception], str | None] | None = None,
+) -> T:
     """Run a graph operation from another CLI command."""
-    return _run(operation)
+    return _run(operation, error_hint=error_hint)
 
 
 def cmd_search(
@@ -224,7 +233,13 @@ def cmd_fetch(platform: str, resource_id: str, as_json: bool) -> None:
 
         return await fetch_entity(platform, resource_id)
 
-    result = _run(operation)
+    def error_hint(error: Exception) -> str | None:
+        from agentgraph.connectors.registry import get_connector
+
+        connector = get_connector(platform)
+        return connector.fetch_error_hint(resource_id, error, "cli") if connector is not None else None
+
+    result = _run(operation, error_hint=error_hint)
     if as_json:
         console.print_json(json.dumps(result, default=str))
         return

{agentgraph_server-0.6.0 → agentgraph_server-0.6.1}/agentgraph/connectors/base.py

@@ -15,7 +15,17 @@ from pydantic import BaseModel, Field
 
 # All resource_type values understood by the connector layer.
 # Each value maps to a distinct fetch strategy within a connector.
-ResourceType = Literal["channel", "dm", "document", "folder", "message", "spreadsheet", "thread"]
+ResourceType = Literal[
+    "channel",
+    "dm",
+    "document",
+    "folder",
+    "message",
+    "spreadsheet",
+    "thread",
+    "video",
+    "work-item",
+]
 RetentionPolicy = Literal["observed", "owned", "connected", "persistent"]
 
 # All valid entity_type values stored in the DB.
@@ -27,6 +37,8 @@ ENTITY_TYPES: tuple[str, ...] = (
     "Person",
     "Spreadsheet",
     "Email",
+    "Task",
+    "Video",
 )
 
 # Broad URL extractor — classify_url does fine-grained matching
@@ -41,6 +53,8 @@ RESOURCE_TYPE_TO_ENTITY_TYPE: dict[str, str] = {
     "message": "Message",
     "spreadsheet": "Spreadsheet",
     "thread": "Email",
+    "video": "Video",
+    "work-item": "Task",
 }
 
 
@@ -68,6 +82,7 @@ class ConnectorCommandEffects:
     ingest: bool = False
     ingest_account_id: str | None = None
     delete_entities: tuple[EntityReference, ...] = ()
+    fetch_references: tuple[SourceReference, ...] = ()
 
 
 class PersonRecord(BaseModel):
@@ -225,6 +240,10 @@ class FetchPolicy:
         return self.FRESH
 
 
+class ResourceUnavailableError(RuntimeError):
+    """A connector cannot retrieve a resource because it is unavailable to the account."""
+
+
 class BaseConnector(ABC):
     source: ClassVar[str]  # platform name, e.g. "slack" — must be set by subclass
     fetch_policy: ClassVar[FetchPolicy]  # staleness policy — must be set by subclass
@@ -360,6 +379,8 @@ class BaseConnector(ABC):
             "Channel": "channel",
             "Message": "message",
             "Email": "thread",
+            "Task": "work-item",
+            "Video": "video",
         }
         return resource_id, resource_type_map.get(entity_type, "document")  # type: ignore[return-value]
 
@@ -425,6 +446,16 @@ class BaseConnector(ABC):
         """
         ...
 
+    def fetch_error_hint(
+        self,
+        resource_id: str,
+        error: Exception,
+        audience: Literal["cli", "mcp"],
+    ) -> str | None:
+        """Return connector-owned recovery guidance for a failed fetch, if available."""
+        _ = (resource_id, error, audience)
+        return None
+
     async def ingest(self, account_id: str | None = None) -> EntityBatch:
         """Run a one-shot bulk ingest of all available historical data for this connector.