induscode 0.1.0__py3-none-any.whl

induscode/console/slash_commands/integrations.py

@@ -0,0 +1,949 @@
+"""Integration slash commands — auth launchers, the external bridges, and the
+clipboard / export / share I/O verbs.
+
+Port of TS ``src/console/slash/commands/integrations.ts``. This group is the
+console's seam onto everything that lives *outside* a single turn: signing in
+and out of a provider, wiring the MCP and memory surfaces, connecting an
+external SaaS bridge, and moving the transcript out of the terminal
+(clipboard, HTML export, a share link). The handlers do real work where a
+backing capability exists — they render the live transcript to HTML through
+the :func:`~induscode.transcript_export.publish_transcript` publisher, drive
+an ``MCPClientPool`` over the workspace MCP config, reflect the
+working-memory card from the capability deck, and reach the Composio catalog
+through the SaaS gateway — and fall back to an *informative* status (never a
+dead placeholder) when a backend is unreachable in the current environment.
+
+The two family commands (``/memory``, ``/composio``) are built from
+:class:`~induscode.console_slash.SubCommand` tables via
+:func:`~induscode.console_slash.family_runner`, so their verb dispatch is a
+lookup, not an ``if``-ladder. Overlay surfaces (``mcp``, ``memory``,
+``composio``) carry the *gathered* text into the plugin modal payload
+(``{"surface": …, "title": …, "text": …}``), so the dialog renders the real
+state the command collected rather than a fixed line.
+
+Port deltas, all locked by the plan's cross-cutting rules:
+
+- **Uniform async** (rule 3): every ``run`` is ``async def`` and the
+  dispatcher awaits it. The TS ``void promise.then(...)`` chains on the
+  Composio verbs become *tracked* ``asyncio`` tasks on the per-console
+  holder's task set — never bare tasks; each settle coroutine swallows its
+  own failure into the overlay text exactly as the TS ``.catch`` did.
+- **No module-level singletons** (rule 4): the TS module globals
+  (``mcpPool``/``mcpServers``, ``composioGateway``/``composioResolved``,
+  ``memoryEnabled``) become fields on one per-console
+  :class:`IntegrationsRuntime` holder with a ``reset()`` for tests. The
+  command rows are minted by :func:`build_integration_commands` against one
+  holder, so each console owns its own bridge state.
+- **Framework surface mapping** (analysis 03 §5): ``indusagi.mcp`` keeps the
+  camelCase pool surface (``loadMCPConfig`` / ``connectAll`` /
+  ``listAllTools`` / ``isConnected`` / ``disconnectAll``); the SaaS gateway
+  moved to ``indusagi.connectors`` with a snake_case factory
+  (``create_composio_gateway(api_key=…)``) and snake_case report fields
+  (``enabled_tools`` / ``auth_url`` / ``account_id`` for the TS
+  ``enabledTools`` / ``authUrl`` / ``accountId``).
+"""
+
+from __future__ import annotations
+
+import asyncio
+import os
+import re
+import shutil
+import subprocess
+from collections.abc import Mapping, Sequence
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any, Final
+
+from indusagi.connectors import SaasGateway, create_composio_gateway
+from indusagi.mcp import (
+    MCPClientPool,
+    MCPClientPoolOptions,
+    MCPConnectionOptions,
+    MCPToolDefinition,
+    loadMCPConfig,
+)
+from indusagi.react_ink import StatusMessage
+
+from induscode.capability_deck import APP_NOVEL_CARDS, memory_card
+from induscode.console_slash import (
+    FAMILY,
+    HANDLED,
+    SlashCommand,
+    SlashContext,
+    SlashOutcome,
+    SubCommand,
+    family_runner,
+    info,
+    warn,
+)
+from induscode.transcript_export import (
+    PublishEntry,
+    PublishMessage,
+    PublishOptions,
+    PublishRole,
+    publish_transcript,
+)
+
+__all__ = [
+    "COMPOSIO_ENV_KEY",
+    "COMPOSIO_NO_KEY",
+    "IntegrationsRuntime",
+    "build_integration_commands",
+]
+
+
+# ---------------------------------------------------------------------------
+# The per-console runtime holder (plan cross-cutting rule 4)
+# ---------------------------------------------------------------------------
+
+
+@dataclass
+class IntegrationsRuntime:
+    """The mutable bridge state one console's integration commands share.
+
+    The TS build kept this state in module globals so a ``/mcp connect``
+    followed by a later ``/mcp status`` acted on the same live pool; the
+    Python port threads one holder through the command closures instead, so
+    every console owns its own connections and tests get isolation via a
+    fresh holder (or :meth:`reset`).
+    """
+
+    # The console's MCP client pool, lazily built from the workspace config.
+    mcp_pool: MCPClientPool | None = None
+    # The server configs the live pool was built from, for `status`.
+    mcp_servers: list[MCPConnectionOptions] = field(default_factory=list)
+    # The Composio gateway, built once from the env key (None = no key).
+    composio_gateway: SaasGateway | None = None
+    # Whether a gateway build has already been attempted (caches the miss).
+    composio_resolved: bool = False
+    # parity: /memory on|off flips this *reporting* flag only — it does not
+    # remove the memory tool from the live deck. TS quirk kept verbatim
+    # (plan rule 10); a real detach needs an explicit waiver first.
+    memory_enabled: bool = True
+    # Strong refs to in-flight settle tasks (rule 3: tracked, never bare).
+    tasks: set[asyncio.Task[None]] = field(default_factory=set)
+
+    def reset(self) -> None:
+        """Drop every cached bridge handle and restore the defaults (tests)."""
+        self.mcp_pool = None
+        self.mcp_servers = []
+        self.composio_gateway = None
+        self.composio_resolved = False
+        self.memory_enabled = True
+        for task in self.tasks:
+            task.cancel()
+        self.tasks.clear()
+
+
+def _spawn(runtime: IntegrationsRuntime, ctx: SlashContext, coro: Any) -> None:
+    """Run a settle coroutine as a tracked background task.
+
+    The coroutine is expected to handle its own failures (each Composio
+    settle path catches and reports through the overlay); a leak past that is
+    swallowed into a status warn rather than crashing the console — never a
+    bare task, never an unobserved exception (plan rule 3).
+    """
+    task = asyncio.get_running_loop().create_task(coro)
+    runtime.tasks.add(task)
+
+    def _settled(done: asyncio.Task[None]) -> None:
+        runtime.tasks.discard(done)
+        if done.cancelled():
+            return
+        fault = done.exception()
+        if fault is not None:
+            ctx.set_status(warn(f"Background integration task failed: {fault}"))
+
+    task.add_done_callback(_settled)
+
+
+# ---------------------------------------------------------------------------
+# Duck reads over framework messages
+# ---------------------------------------------------------------------------
+
+
+def _read(message: object, key: str) -> object | None:
+    """Read one structural field off a framework message — attribute access
+    for the framework dataclasses, key access for plain-dict stand-ins."""
+    if isinstance(message, Mapping):
+        return message.get(key)
+    return getattr(message, key, None)
+
+
+# ---------------------------------------------------------------------------
+# Clipboard plumbing
+# ---------------------------------------------------------------------------
+
+
+@dataclass(frozen=True, slots=True)
+class _ClipboardWriter:
+    """One platform clipboard writer candidate."""
+
+    bin: str
+    args: tuple[str, ...]
+
+
+#: The platform clipboard writers, tried in order until one accepts the text
+#: on stdin. The first entry whose binary exists and exits cleanly wins:
+#:   - ``pbcopy``  — macOS.
+#:   - ``clip``    — Windows.
+#:   - ``xclip``   — X11 (selection set to the system clipboard).
+#:   - ``wl-copy`` — Wayland.
+CLIPBOARD_WRITERS: Final[tuple[_ClipboardWriter, ...]] = (
+    _ClipboardWriter(bin="pbcopy", args=()),
+    _ClipboardWriter(bin="clip", args=()),
+    _ClipboardWriter(bin="xclip", args=("-selection", "clipboard")),
+    _ClipboardWriter(bin="wl-copy", args=()),
+)
+
+
+def _write_clipboard(text: str) -> bool:
+    """Best-effort write of ``text`` to the OS clipboard.
+
+    Walks :data:`CLIPBOARD_WRITERS`, feeding the text on stdin to each
+    candidate; returns ``True`` on the first writer that is present and exits
+    with status 0. A missing binary is skipped via :func:`shutil.which` (the
+    Python rendering of the TS swallowed ``ENOENT``); returns ``False`` when
+    no writer succeeds.
+
+    :param text: the string to place on the clipboard
+    """
+    for writer in CLIPBOARD_WRITERS:
+        if shutil.which(writer.bin) is None:
+            continue
+        try:
+            result = subprocess.run(
+                [writer.bin, *writer.args],
+                input=text,
+                capture_output=True,
+                encoding="utf-8",
+            )
+        except OSError:
+            # Writer is unavailable on this platform; fall through to the next.
+            continue
+        if result.returncode == 0:
+            return True
+    return False
+
+
+# ---------------------------------------------------------------------------
+# Transcript text extraction
+# ---------------------------------------------------------------------------
+
+
+def _block_text(block: object) -> str | None:
+    """The text of a ``text``-typed content block, or ``None`` otherwise."""
+    block_type = _read(block, "type")
+    text = _read(block, "text")
+    if block_type == "text" and isinstance(text, str):
+        return text
+    return None
+
+
+def _last_assistant_text(messages: Sequence[object]) -> str:
+    """Pull the plain text out of the most recent assistant turn.
+
+    Scans newest-first for a message in the assistant role and concatenates
+    the text of its text blocks (reasoning and tool-call blocks are skipped,
+    since the clipboard wants the prose). Returns an empty string when there
+    is no assistant turn yet or it carried no text — the caller decides how
+    to surface that.
+
+    :param messages: the live transcript messages, oldest first
+    """
+    for message in reversed(messages):
+        if _read(message, "role") != "assistant":
+            continue
+        content = _read(message, "content")
+        if isinstance(content, str) or not isinstance(content, Sequence):
+            continue
+        parts = [text for block in content if (text := _block_text(block)) is not None]
+        return "".join(parts).strip()
+    return ""
+
+
+# ---------------------------------------------------------------------------
+# Transcript HTML export
+# ---------------------------------------------------------------------------
+
+#: The transcript roles the publisher knows how to attribute.
+PUBLISH_ROLES: Final[frozenset[str]] = frozenset(
+    {"user", "assistant", "tool", "system", "condense", "note"}
+)
+
+
+def _to_publish_role(role: str) -> PublishRole:
+    """Map a framework message role to a publisher role, folding any
+    unrecognised role into ``note`` so an exotic message still renders."""
+    if role in PUBLISH_ROLES:
+        return role  # type: ignore[return-value]  # narrowed by the set check
+    return "note"
+
+
+def _to_publish_entries(messages: Sequence[object]) -> list[PublishEntry]:
+    """Project the live transcript onto the :class:`PublishEntry` list the
+    :func:`publish_transcript` publisher consumes. The framework message is
+    read structurally — only ``role``, ``content``, and the tool-result
+    linkage — so the publisher's own narrow ``PublishMessage`` view is
+    satisfied without redeclaring the framework union."""
+    entries: list[PublishEntry] = []
+    for message in messages:
+        role = _read(message, "role")
+        role_text = role if isinstance(role, str) else ""
+        content = _read(message, "content")
+        if isinstance(content, str) or isinstance(content, Sequence):
+            published: Any = content
+        else:
+            published = ""
+        tool_call_id = _read(message, "toolCallId")
+        tool_name = _read(message, "toolName")
+        entries.append(
+            PublishEntry(
+                role=_to_publish_role(role_text),
+                message=PublishMessage(
+                    role=role_text,
+                    content=published,
+                    toolCallId=tool_call_id if isinstance(tool_call_id, str) else None,
+                    toolName=tool_name if isinstance(tool_name, str) else None,
+                ),
+            )
+        )
+    return entries
+
+
+def _default_export_path() -> str:
+    """Build the default ``transcript-<timestamp>.html`` path under the
+    workspace (the TS ISO stamp with ``[:.]`` folded to ``-``, ``T`` to
+    ``_``, and the trailing ``Z`` dropped)."""
+    now = datetime.now(timezone.utc)
+    iso = now.strftime("%Y-%m-%dT%H:%M:%S.") + f"{now.microsecond // 1000:03d}Z"
+    stamp = re.sub(r"[:.]", "-", iso).replace("T", "_")
+    stamp = re.sub(r"Z$", "", stamp)
+    return os.path.abspath(os.path.join(os.getcwd(), f"transcript-{stamp}.html"))
+
+
+@dataclass(frozen=True, slots=True)
+class _ExportReport:
+    """The outcome of one HTML export — the absolute path written on
+    success, or a typed failure carrying a human message."""
+
+    ok: bool
+    path: str = ""
+    reason: str = ""
+
+
+def _export_transcript_html(ctx: SlashContext, target: str) -> _ExportReport:
+    """Render the live transcript to a standalone HTML document and write it
+    to disk.
+
+    The transcript is read from the conductor at call time and published
+    through the transcript-export subsystem; the only I/O here is the single
+    file write.
+
+    :param ctx:    the slash context (the conductor is read for live messages)
+    :param target: an optional output path; a timestamped default otherwise
+    """
+    messages = ctx.conductor.messages()
+    if len(messages) == 0:
+        return _ExportReport(
+            ok=False, reason="Nothing to export yet — the transcript is empty."
+        )
+    path = (
+        os.path.abspath(os.path.join(os.getcwd(), target))
+        if len(target) > 0
+        else _default_export_path()
+    )
+    try:
+        html = publish_transcript(
+            _to_publish_entries(messages), PublishOptions(title="Session Transcript")
+        )
+        Path(path).write_text(html, encoding="utf-8")
+        return _ExportReport(ok=True, path=path)
+    except Exception as cause:
+        return _ExportReport(
+            ok=False, reason=f"Could not write the HTML export: {cause}"
+        )
+
+
+# ---------------------------------------------------------------------------
+# MCP pool
+# ---------------------------------------------------------------------------
+
+
+def _load_mcp_pool(runtime: IntegrationsRuntime) -> MCPClientPool:
+    """(Re)load the workspace MCP config and rebuild the pool from it."""
+    runtime.mcp_servers = loadMCPConfig(os.getcwd())
+    runtime.mcp_pool = MCPClientPool(MCPClientPoolOptions(servers=runtime.mcp_servers))
+    return runtime.mcp_pool
+
+
+def _ensure_mcp_pool(runtime: IntegrationsRuntime) -> MCPClientPool:
+    """The live pool, building one from config on first use."""
+    if runtime.mcp_pool is not None:
+        return runtime.mcp_pool
+    return _load_mcp_pool(runtime)
+
+
+async def _gather_mcp_status(runtime: IntegrationsRuntime) -> str:
+    """Gather a human-readable status block describing the configured MCP
+    servers, their live connection state, and the tool names each currently
+    exposes."""
+    if len(runtime.mcp_servers) == 0 and runtime.mcp_pool is None:
+        runtime.mcp_servers = loadMCPConfig(os.getcwd())
+    if len(runtime.mcp_servers) == 0:
+        return (
+            "No MCP servers are configured.\n"
+            "Add one to .indusvx/mcp.json, then run /mcp connect."
+        )
+
+    pool = runtime.mcp_pool
+    lines: list[str] = [f"Configured MCP servers ({len(runtime.mcp_servers)}):"]
+
+    tools_by_server: dict[str, list[MCPToolDefinition]] = {}
+    if pool is not None:
+        try:
+            tools_by_server = await pool.listAllTools()
+        except Exception:
+            tools_by_server = {}
+
+    for server in runtime.mcp_servers:
+        connected = pool.isConnected(server.name) if pool is not None else False
+        state = "connected" if connected else "not connected"
+        lines.append(f"  • {server.name} — {state}")
+        tools = tools_by_server.get(server.name, [])
+        if len(tools) > 0:
+            lines.append(f"      tools: {', '.join(t.name for t in tools)}")
+    return "\n".join(lines)
+
+
+# ---------------------------------------------------------------------------
+# MCP command
+# ---------------------------------------------------------------------------
+
+
+def _open_mcp_overlay(ctx: SlashContext, text: str) -> None:
+    """Open the MCP plugin overlay populated with the gathered status text."""
+    ctx.open_modal("plugin", {"surface": "mcp", "title": "MCP servers", "text": text})
+
+
+async def _run_mcp(ctx: SlashContext, runtime: IntegrationsRuntime) -> SlashOutcome:
+    """Run the ``/mcp`` verb against the workspace MCP pool."""
+    verb = ctx.args.strip().lower() or "status"
+
+    try:
+        if verb in ("connect", "reconnect"):
+            pool = (
+                _load_mcp_pool(runtime)
+                if verb == "reconnect"
+                else _ensure_mcp_pool(runtime)
+            )
+            await pool.connectAll()
+            text = await _gather_mcp_status(runtime)
+            ctx.set_status(info(f"MCP {verb}ed."))
+            _open_mcp_overlay(ctx, text)
+            return HANDLED
+        if verb == "disconnect":
+            if runtime.mcp_pool is None:
+                ctx.set_status(info("No MCP connections are open."))
+                return HANDLED
+            await runtime.mcp_pool.disconnectAll()
+            ctx.set_status(info("Disconnected from all MCP servers."))
+            _open_mcp_overlay(ctx, await _gather_mcp_status(runtime))
+            return HANDLED
+        if verb == "tools":
+            pool = _ensure_mcp_pool(runtime)
+            tools_by_server: dict[str, list[MCPToolDefinition]] = {}
+            try:
+                tools_by_server = await pool.listAllTools()
+            except Exception:
+                tools_by_server = {}
+            names = [t.name for tools in tools_by_server.values() for t in tools]
+            text = (
+                "No MCP tools are loaded. Run /mcp connect first."
+                if len(names) == 0
+                else f"Loaded MCP tools ({len(names)}):\n  " + "\n  ".join(names)
+            )
+            _open_mcp_overlay(ctx, text)
+            return HANDLED
+        if verb in ("status", ""):
+            _open_mcp_overlay(ctx, await _gather_mcp_status(runtime))
+            return HANDLED
+        ctx.set_status(
+            warn("/mcp expects: connect, reconnect, disconnect, tools, or status.")
+        )
+        return HANDLED
+    except Exception as cause:
+        ctx.set_status(warn(f"MCP {verb} failed: {cause}"))
+        return HANDLED
+
+
+# ---------------------------------------------------------------------------
+# Memory family
+# ---------------------------------------------------------------------------
+
+
+def _memory_tool_names() -> list[str]:
+    """The model-facing tool name(s) the memory card contributes.
+
+    The card builds a single capability the model calls as ``memory``; the
+    card id is the deck-side handle for the same capability.
+    """
+    return list(dict.fromkeys([str(memory_card.id), "memory"]))
+
+
+def _memory_present() -> bool:
+    """Whether the working-memory card is part of the app's novel set."""
+    return any(card.id == memory_card.id for card in APP_NOVEL_CARDS)
+
+
+def _gather_memory_status(runtime: IntegrationsRuntime) -> str:
+    """Build the gathered memory status text for the overlay / status line."""
+    if not _memory_present():
+        return "The working-memory capability is not registered in this build."
+    lines = [
+        f"Working memory: {'active' if runtime.memory_enabled else 'inactive'}.",
+        f"Tool: {', '.join(_memory_tool_names())}.",
+        memory_card.summary,
+    ]
+    return "\n".join(lines)
+
+
+def _open_memory_overlay(ctx: SlashContext, text: str) -> None:
+    """Open the memory plugin overlay populated with the gathered text."""
+    ctx.open_modal(
+        "plugin", {"surface": "memory", "title": "Working memory", "text": text}
+    )
+
+
+def _memory_subs(runtime: IntegrationsRuntime) -> tuple[SubCommand, ...]:
+    """The ``/memory`` sub-command table over one console's holder. Every
+    verb reflects (or best-effort toggles) the real working-memory card from
+    the capability deck — no dead placeholder."""
+
+    async def status(ctx: SlashContext, rest: str) -> SlashOutcome:
+        _open_memory_overlay(ctx, _gather_memory_status(runtime))
+        return HANDLED
+
+    async def on(ctx: SlashContext, rest: str) -> SlashOutcome:
+        if not _memory_present():
+            ctx.set_status(warn("No working-memory capability to enable in this build."))
+            return HANDLED
+        runtime.memory_enabled = True
+        ctx.set_status(info("Working memory marked active."))
+        _open_memory_overlay(ctx, _gather_memory_status(runtime))
+        return HANDLED
+
+    async def off(ctx: SlashContext, rest: str) -> SlashOutcome:
+        if not _memory_present():
+            ctx.set_status(warn("No working-memory capability to disable in this build."))
+            return HANDLED
+        runtime.memory_enabled = False
+        ctx.set_status(info("Working memory marked inactive."))
+        _open_memory_overlay(ctx, _gather_memory_status(runtime))
+        return HANDLED
+
+    async def tools(ctx: SlashContext, rest: str) -> SlashOutcome:
+        text = (
+            "Working-memory tools:\n  " + "\n  ".join(_memory_tool_names())
+            if _memory_present()
+            else "No working-memory capability is registered in this build."
+        )
+        _open_memory_overlay(ctx, text)
+        return HANDLED
+
+    return (
+        SubCommand(verb="status", describe="show memory state + tool", run=status),
+        SubCommand(verb="on", describe="mark memory active", run=on),
+        SubCommand(verb="off", describe="mark memory inactive", run=off),
+        SubCommand(verb="tools", describe="list memory tool names", run=tools),
+    )
+
+
+# ---------------------------------------------------------------------------
+# Composio family
+# ---------------------------------------------------------------------------
+
+#: The conventional environment variable carrying a Composio API key.
+COMPOSIO_ENV_KEY: Final = "COMPOSIO_API_KEY"
+
+#: The status line shown when no Composio key is configured.
+COMPOSIO_NO_KEY: Final = (
+    f"Composio is not configured. Export {COMPOSIO_ENV_KEY} with a Composio API key, "
+    "then re-run /composio connect."
+)
+
+
+def _ensure_composio_gateway(runtime: IntegrationsRuntime) -> SaasGateway | None:
+    """Resolve the Composio gateway, building it from the env key on first
+    use (and caching the miss so repeated verbs do not re-probe the env)."""
+    if runtime.composio_resolved:
+        return runtime.composio_gateway
+    runtime.composio_resolved = True
+    api_key = (os.environ.get(COMPOSIO_ENV_KEY) or "").strip()
+    if len(api_key) == 0:
+        runtime.composio_gateway = None
+        return None
+    try:
+        runtime.composio_gateway = create_composio_gateway(api_key=api_key)
+    except Exception:
+        runtime.composio_gateway = None
+    return runtime.composio_gateway
+
+
+def _open_composio_overlay(ctx: SlashContext, text: str) -> None:
+    """Open the Composio plugin overlay populated with gathered text."""
+    ctx.open_modal("plugin", {"surface": "composio", "title": "Composio", "text": text})
+
+
+async def _gather_composio_status(gateway: SaasGateway) -> str:
+    """Gather a status block of connected accounts + in-scope tool names."""
+    report = await gateway.status()
+    lines: list[str] = []
+    if len(report.accounts) == 0:
+        lines.append("No connected accounts.")
+    else:
+        lines.append(f"Connected accounts ({len(report.accounts)}):")
+        for account in report.accounts:
+            lines.append(f"  • {account.toolkit} — {account.status} ({account.id})")
+    lines.append(
+        "No remote tools enabled yet. Run /composio enable <toolkit>."
+        if len(report.enabled_tools) == 0
+        else f"Enabled tools ({len(report.enabled_tools)}): "
+        + ", ".join(report.enabled_tools)
+    )
+    return "\n".join(lines)
+
+
+def _composio_subs(runtime: IntegrationsRuntime) -> tuple[SubCommand, ...]:
+    """The ``/composio`` sub-command table over one console's holder. Each
+    verb reaches the real Composio catalog through the SaaS gateway when a
+    key is configured, and reports the missing-key state specifically
+    otherwise. The connect/enable flows settle in tracked background tasks
+    that open the overlay on completion (the TS fire-and-forget promises)."""
+
+    async def status(ctx: SlashContext, rest: str) -> SlashOutcome:
+        gateway = _ensure_composio_gateway(runtime)
+        if gateway is None:
+            ctx.set_status(warn("Composio is not configured."))
+            _open_composio_overlay(ctx, COMPOSIO_NO_KEY)
+            return HANDLED
+
+        async def settle() -> None:
+            try:
+                text = await _gather_composio_status(gateway)
+            except Exception as cause:
+                _open_composio_overlay(ctx, f"Could not read Composio status: {cause}")
+                return
+            _open_composio_overlay(ctx, text)
+
+        _spawn(runtime, ctx, settle())
+        return HANDLED
+
+    async def accounts(ctx: SlashContext, rest: str) -> SlashOutcome:
+        gateway = _ensure_composio_gateway(runtime)
+        if gateway is None:
+            _open_composio_overlay(ctx, COMPOSIO_NO_KEY)
+            return HANDLED
+
+        async def settle() -> None:
+            try:
+                report = await gateway.status()
+            except Exception as cause:
+                _open_composio_overlay(ctx, f"Could not list accounts: {cause}")
+                return
+            text = (
+                "No connected Composio accounts."
+                if len(report.accounts) == 0
+                else f"Connected accounts ({len(report.accounts)}):\n"
+                + "\n".join(
+                    f"  • {a.toolkit} — {a.status} ({a.id})" for a in report.accounts
+                )
+            )
+            _open_composio_overlay(ctx, text)
+
+        _spawn(runtime, ctx, settle())
+        return HANDLED
+
+    async def tools(ctx: SlashContext, rest: str) -> SlashOutcome:
+        gateway = _ensure_composio_gateway(runtime)
+        if gateway is None:
+            _open_composio_overlay(ctx, COMPOSIO_NO_KEY)
+            return HANDLED
+
+        async def settle() -> None:
+            try:
+                report = await gateway.status()
+            except Exception as cause:
+                _open_composio_overlay(ctx, f"Could not list tools: {cause}")
+                return
+            text = (
+                "No Composio tools enabled. Run /composio enable <toolkit>."
+                if len(report.enabled_tools) == 0
+                else f"Enabled Composio tools ({len(report.enabled_tools)}):\n  "
+                + "\n  ".join(report.enabled_tools)
+            )
+            _open_composio_overlay(ctx, text)
+
+        _spawn(runtime, ctx, settle())
+        return HANDLED
+
+    async def connect(ctx: SlashContext, rest: str) -> SlashOutcome:
+        toolkit = rest.strip()
+        if len(toolkit) == 0:
+            ctx.set_status(warn("/composio connect expects: <toolkit> to link."))
+            return HANDLED
+        gateway = _ensure_composio_gateway(runtime)
+        if gateway is None:
+            _open_composio_overlay(ctx, COMPOSIO_NO_KEY)
+            return HANDLED
+        ctx.set_status(info(f"Starting Composio connect for {toolkit}..."))
+
+        async def settle() -> None:
+            try:
+                report = await gateway.connect(toolkit)
+            except Exception as cause:
+                _open_composio_overlay(ctx, f"Composio connect failed: {cause}")
+                return
+            lines = [f"Connect {toolkit}: {report.action}."]
+            if report.auth_url:
+                lines.append(f"Authorize at: {report.auth_url}")
+            if report.account_id:
+                lines.append(f"Account: {report.account_id}")
+            if report.reason:
+                lines.append(f"Reason: {report.reason}")
+            _open_composio_overlay(ctx, "\n".join(lines))
+
+        _spawn(runtime, ctx, settle())
+        return HANDLED
+
+    async def enable(ctx: SlashContext, rest: str) -> SlashOutcome:
+        toolkit = rest.strip()
+        if len(toolkit) == 0:
+            ctx.set_status(warn("/composio enable expects: <toolkit> to hydrate."))
+            return HANDLED
+        gateway = _ensure_composio_gateway(runtime)
+        if gateway is None:
+            _open_composio_overlay(ctx, COMPOSIO_NO_KEY)
+            return HANDLED
+        ctx.set_status(info(f"Enabling Composio toolkit {toolkit}..."))
+
+        async def settle() -> None:
+            try:
+                report = await gateway.enable(toolkit)
+            except Exception as cause:
+                _open_composio_overlay(ctx, f"Composio enable failed: {cause}")
+                return
+            text = (
+                f"Toolkit {toolkit} exposed no tools."
+                if len(report.hydrated) == 0
+                else f"Enabled {report.toolkit} ({len(report.hydrated)} tools"
+                + (", cached" if report.cached else "")
+                + "):\n  "
+                + "\n  ".join(report.hydrated)
+            )
+            _open_composio_overlay(ctx, text)
+
+        _spawn(runtime, ctx, settle())
+        return HANDLED
+
+    return (
+        SubCommand(verb="status", describe="show accounts + tools", run=status),
+        SubCommand(verb="accounts", describe="list connected accounts", run=accounts),
+        SubCommand(verb="tools", describe="list enabled tool names", run=tools),
+        SubCommand(verb="connect", describe="link a toolkit", run=connect),
+        SubCommand(verb="enable", describe="hydrate a toolkit's tools", run=enable),
+    )
+
+
+# ---------------------------------------------------------------------------
+# Direct-action handlers
+# ---------------------------------------------------------------------------
+
+
+async def _run_copy(ctx: SlashContext) -> SlashOutcome:
+    """``/copy`` — place the last assistant turn's text on the OS clipboard.
+
+    Reads the live transcript through the conductor, extracts the newest
+    assistant prose, and writes it through the best-effort clipboard walk.
+    Warns when there is nothing to copy, and again when no platform writer
+    accepted the text; otherwise confirms with an info toast.
+    """
+    text = _last_assistant_text(ctx.conductor.messages())
+    if len(text) == 0:
+        ctx.set_status(warn("Nothing to copy yet — no assistant reply on screen."))
+        return HANDLED
+    if not _write_clipboard(text):
+        ctx.set_status(warn("Could not reach a clipboard tool on this system."))
+        return HANDLED
+    ctx.set_status(info("Copied the last reply to your clipboard."))
+    return HANDLED
+
+
+async def _run_export(ctx: SlashContext) -> SlashOutcome:
+    """``/export [path]`` — render the live transcript to a standalone HTML
+    document and write it to disk, reporting the absolute path written."""
+    result = _export_transcript_html(ctx, ctx.args.strip())
+    if not result.ok:
+        ctx.set_status(warn(result.reason))
+        return HANDLED
+    ctx.set_status(
+        StatusMessage(kind="success", text=f"Exported transcript to {result.path}")
+    )
+    return HANDLED
+
+
+#: The pattern over ``gh`` stderr that suggests an authentication problem.
+_GH_AUTH_HINT: Final = re.compile(r"auth|logged in|gh auth login", re.IGNORECASE)
+
+
+async def _run_share(ctx: SlashContext) -> SlashOutcome:
+    """``/share`` — export the transcript to HTML, then publish it as a
+    secret GitHub gist via the ``gh`` CLI. On success the gist URL is
+    reported; when ``gh`` is missing or unauthenticated, that is reported
+    specifically with the local HTML path as a fallback the user can open or
+    upload manually."""
+    exported = _export_transcript_html(ctx, "")
+    if not exported.ok:
+        ctx.set_status(warn(exported.reason))
+        return HANDLED
+
+    try:
+        result = subprocess.run(
+            ["gh", "gist", "create", exported.path, "--public=false"],
+            capture_output=True,
+            encoding="utf-8",
+        )
+    except (FileNotFoundError, OSError):
+        ctx.set_status(
+            warn(
+                f"GitHub CLI (gh) is not installed. Saved HTML locally at {exported.path}"
+            )
+        )
+        return HANDLED
+
+    if result.returncode != 0:
+        stderr = (result.stderr or "").strip()
+        auth_hint = (
+            "Run `gh auth login` to authenticate, then retry."
+            if _GH_AUTH_HINT.search(stderr)
+            else stderr or "gh gist create failed."
+        )
+        ctx.set_status(
+            warn(f"Share failed: {auth_hint} Saved HTML locally at {exported.path}")
+        )
+        return HANDLED
+
+    pieces = (result.stdout or "").strip().split()
+    url = pieces[0] if pieces else ""
+    ctx.set_status(
+        StatusMessage(
+            kind="success",
+            text=f"Shared as secret gist: {url}"
+            if len(url) > 0
+            else f"Shared. Local HTML: {exported.path}",
+        )
+    )
+    return HANDLED
+
+
+# ---------------------------------------------------------------------------
+# Login routing
+# ---------------------------------------------------------------------------
+
+
+async def _run_login(ctx: SlashContext) -> SlashOutcome:
+    """``/login [provider]`` — open the sign-in surface. When a provider name
+    is supplied it is threaded into the sign-in payload so the overlay routes
+    straight to that provider's entry flow instead of the generic picker."""
+    provider = ctx.args.strip().lower()
+    if len(provider) > 0:
+        ctx.open_modal("signIn", {"providerId": provider})
+    else:
+        ctx.open_modal("signIn")
+    return HANDLED
+
+
+async def _run_logout(ctx: SlashContext) -> SlashOutcome:
+    """``/logout`` — open the sign-out confirmation."""
+    ctx.open_modal("signOut")
+    return HANDLED
+
+
+# ---------------------------------------------------------------------------
+# The exported group
+# ---------------------------------------------------------------------------
+
+
+def build_integration_commands(
+    runtime: IntegrationsRuntime | None = None,
+) -> tuple[SlashCommand, ...]:
+    """Mint the integration command group over one console's runtime holder.
+
+    The integration command group: auth launchers, the MCP/memory/composio
+    bridges, and the clipboard / export / share I/O verbs. Appended to the
+    slash catalog by the assembler (``builtins.build_catalog``) alongside the
+    other groups. Each call binds the rows to the given (or a fresh)
+    :class:`IntegrationsRuntime`, replacing the TS module-global state with
+    per-console state (plan cross-cutting rule 4).
+
+    :param runtime: the holder the bridge verbs share; fresh when omitted
+    """
+    holder = runtime if runtime is not None else IntegrationsRuntime()
+
+    run_memory = family_runner(FAMILY.memory, _memory_subs(holder))
+    run_composio = family_runner(FAMILY.composio, _composio_subs(holder))
+
+    async def run_mcp(ctx: SlashContext) -> SlashOutcome:
+        return await _run_mcp(ctx, holder)
+
+    return (
+        SlashCommand(
+            name="login",
+            summary="Sign in to a model provider.",
+            run=_run_login,
+            takes_args=True,
+        ),
+        SlashCommand(
+            name="logout",
+            summary="Sign out of a model provider.",
+            run=_run_logout,
+        ),
+        SlashCommand(
+            name="mcp",
+            summary="Manage MCP servers and their tools.",
+            run=run_mcp,
+            takes_args=True,
+        ),
+        SlashCommand(
+            name="memory",
+            summary="Inspect and toggle the working-memory capability.",
+            run=run_memory,
+            family=FAMILY.memory,
+            takes_args=True,
+        ),
+        SlashCommand(
+            name="composio",
+            summary="Connect and inspect Composio app bridges.",
+            run=run_composio,
+            family=FAMILY.composio,
+            takes_args=True,
+        ),
+        SlashCommand(
+            name="copy",
+            summary="Copy the last reply to the clipboard.",
+            run=_run_copy,
+        ),
+        SlashCommand(
+            name="export",
+            summary="Export the transcript to an HTML file.",
+            run=_run_export,
+            takes_args=True,
+        ),
+        SlashCommand(
+            name="share",
+            summary="Share the session as a secret GitHub gist.",
+            run=_run_share,
+        ),
+    )