loopx 0.4.8__py3-none-any.whl

loopx/capabilities/value_connectors/cli.py

@@ -0,0 +1,401 @@
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from collections.abc import Callable
+from pathlib import Path
+
+from ..issue_fix.github_public import (
+    build_github_public_channel_probe_packet,
+    build_github_public_reply_monitor_packet,
+    render_github_public_channel_probe_markdown,
+    render_github_public_reply_monitor_markdown,
+)
+from .install_check import (
+    build_value_connector_install_check_packet,
+    render_value_connector_install_check_markdown,
+)
+from .finance_extension_migration import (
+    LEGACY_FINANCE_CONNECTOR_ID,
+    build_finance_extension_migration_contract,
+    render_finance_extension_migration_markdown,
+)
+from .planner import (
+    ALLOWED_CONNECTOR_KINDS,
+    ALLOWED_STAGES,
+    ALLOWED_VALUE_AXES,
+    build_single_value_connector_plan,
+    build_value_connector_plan_fixture,
+    build_value_connector_plan_packet,
+    render_value_connector_plan_markdown,
+)
+from .source_map import (
+    SOURCE_PROFILE_IDS,
+    build_value_connector_source_map_packet,
+    render_value_connector_source_map_markdown,
+)
+
+
+PrintPayload = Callable[
+    [dict[str, object], str, Callable[[dict[str, object]], str]],
+    None,
+]
+FormatSelector = Callable[..., str]
+AddFormat = Callable[[argparse.ArgumentParser], None]
+
+
+def _load_json_object_or_array(path_text: str) -> dict[str, object] | list[object]:
+    if path_text == "-":
+        payload = json.loads(sys.stdin.read())
+    else:
+        payload = json.loads(Path(path_text).expanduser().read_text(encoding="utf-8"))
+    if not isinstance(payload, (dict, list)):
+        raise ValueError(f"{path_text} must contain a JSON object or array")
+    return payload
+
+
+def register_value_connector_commands(
+    subparsers: argparse._SubParsersAction,
+    add_subcommand_format: AddFormat,
+) -> None:
+    parser = subparsers.add_parser(
+        "value-connectors",
+        help="Plan reusable external-value connector calls before execution.",
+    )
+    sub = parser.add_subparsers(dest="value_connectors_command", required=True)
+    install_parser = sub.add_parser(
+        "install-check",
+        help="Show connector install/use steps and local dependency status.",
+    )
+    add_subcommand_format(install_parser)
+    install_parser.add_argument(
+        "--connector",
+        choices=[
+            "all",
+            "agent_reach_ops_source_map",
+            "finance_market_snapshot",
+            "github_public_channel",
+            "botmail_identity",
+            "community_channel",
+            "social_browser_x",
+        ],
+        default="all",
+        help="Connector profile to check.",
+    )
+    source_map_parser = sub.add_parser(
+        "source-map",
+        help=(
+            "Render a read-first source-map packet so agents can use proven "
+            "connectors without opening internal docs."
+        ),
+    )
+    add_subcommand_format(source_map_parser)
+    source_map_parser.add_argument(
+        "--connector",
+        choices=sorted(SOURCE_PROFILE_IDS),
+        default="all",
+        help="Connector source profile to render.",
+    )
+    plan_parser = sub.add_parser(
+        "plan",
+        help="Render a public-safe connector call plan with gates and value metrics.",
+    )
+    add_subcommand_format(plan_parser)
+    plan_parser.add_argument(
+        "--generated-at",
+        default="2026-06-25T00:00:00Z",
+        help="Public-safe generated_at timestamp for the plan.",
+    )
+    plan_parser.add_argument(
+        "--scenario",
+        default="external_value_channel_queue",
+        help="Fixture scenario label when --connector-id is omitted.",
+    )
+    plan_parser.add_argument(
+        "--connector-id", help="Build a single-call plan for this connector id."
+    )
+    plan_parser.add_argument(
+        "--connector-kind",
+        choices=sorted(ALLOWED_CONNECTOR_KINDS),
+        default="custom_connector",
+        help="Connector kind for --connector-id single-call plans.",
+    )
+    plan_parser.add_argument("--channel", help="Channel label for a single-call plan.")
+    plan_parser.add_argument(
+        "--stage",
+        choices=sorted(ALLOWED_STAGES),
+        default="observe",
+        help="Connector stage for a single-call plan.",
+    )
+    plan_parser.add_argument(
+        "--target-ref", help="Public-safe target label for a single-call plan."
+    )
+    plan_parser.add_argument(
+        "--target-url",
+        help="Optional public https target URL without query or fragment.",
+    )
+    plan_parser.add_argument(
+        "--value-axis",
+        choices=sorted(ALLOWED_VALUE_AXES),
+        default="revenue",
+        help="Primary value axis for a single-call plan.",
+    )
+    plan_parser.add_argument(
+        "--money-metric",
+        help="Required money/cost/demand proxy for a single-call plan.",
+    )
+    plan_parser.add_argument(
+        "--success-metric", help="Required success metric for a single-call plan."
+    )
+    plan_parser.add_argument(
+        "--kill-condition", help="Required stop condition for a single-call plan."
+    )
+    plan_parser.add_argument(
+        "--audience",
+        default="external operators running long-lived agent workflows",
+        help="Public-safe target audience label.",
+    )
+    plan_parser.add_argument(
+        "--sender-identity",
+        default="LoopX operator",
+        help="Public-safe sender identity label for the plan.",
+    )
+    plan_parser.add_argument(
+        "--external-read",
+        action="store_true",
+        help="Declare that the future connector call would need a bounded external metadata read.",
+    )
+    plan_parser.add_argument(
+        "--external-write-requested",
+        action="store_true",
+        help="Declare that the future connector call requests an external write gate.",
+    )
+    github_parser = sub.add_parser(
+        "github-public-probe",
+        help="Probe public GitHub issue/PR/discussion metadata without external writes.",
+    )
+    add_subcommand_format(github_parser)
+    github_parser.add_argument(
+        "--url",
+        required=True,
+        help=(
+            "Public GitHub issue, PR, or discussion URL. Query strings, fragments, "
+            "auth material, and non-github.com hosts are rejected."
+        ),
+    )
+    github_parser.add_argument(
+        "--fetch-metadata",
+        action="store_true",
+        help=(
+            "Perform the bounded metadata read. Issue/PR uses GitHub REST; "
+            "discussion uses gh GraphQL when available."
+        ),
+    )
+    github_parser.add_argument(
+        "--timeout-seconds",
+        type=float,
+        default=10.0,
+        help="Network/tool timeout for --fetch-metadata.",
+    )
+    reply_monitor_parser = sub.add_parser(
+        "github-reply-monitor",
+        help=(
+            "Detect new public maintainer replies after a LoopX issue comment "
+            "without capturing comment bodies."
+        ),
+    )
+    add_subcommand_format(reply_monitor_parser)
+    reply_monitor_parser.add_argument(
+        "--issue-url",
+        required=True,
+        help="Public GitHub issue or PR URL being monitored.",
+    )
+    reply_monitor_parser.add_argument(
+        "--after-comment-url",
+        required=True,
+        help=(
+            "Public GitHub issue comment URL that anchors the monitor window, "
+            "for example https://github.com/owner/repo/issues/1#issuecomment-123."
+        ),
+    )
+    reply_monitor_parser.add_argument(
+        "--metadata-json",
+        default=None,
+        help=(
+            "Path to mocked provider comment metadata JSON, or '-' for stdin. "
+            "Body/raw fields stay gated and are not copied."
+        ),
+    )
+    reply_monitor_parser.add_argument(
+        "--fetch-metadata",
+        action="store_true",
+        help=(
+            "Use gh api to fetch public issue-comment metadata only: author, "
+            "association, timestamps, and URL. Comment bodies are not output."
+        ),
+    )
+    reply_monitor_parser.add_argument(
+        "--timeout-seconds",
+        type=float,
+        default=10.0,
+        help="Network/tool timeout for --fetch-metadata.",
+    )
+
+
+def handle_value_connector_command(
+    args: argparse.Namespace,
+    *,
+    output_format: FormatSelector,
+    print_payload: PrintPayload,
+) -> int | None:
+    if args.command != "value-connectors":
+        return None
+    try:
+        if args.value_connectors_command == "install-check":
+            payload = build_value_connector_install_check_packet(
+                connector=args.connector,
+            )
+            print_payload(
+                payload,
+                output_format(args),
+                render_value_connector_install_check_markdown,
+            )
+            return 0
+        if args.value_connectors_command == "source-map":
+            payload = build_value_connector_source_map_packet(
+                connector=args.connector,
+            )
+            print_payload(
+                payload,
+                output_format(args),
+                render_value_connector_source_map_markdown,
+            )
+            return 0
+        if args.value_connectors_command == "github-public-probe":
+            payload = build_github_public_channel_probe_packet(
+                url=args.url,
+                fetch_metadata=args.fetch_metadata,
+                timeout_seconds=args.timeout_seconds,
+            )
+            print_payload(
+                payload,
+                output_format(args),
+                render_github_public_channel_probe_markdown,
+            )
+            return 0 if payload.get("ok") else 1
+        if args.value_connectors_command == "github-reply-monitor":
+            if args.fetch_metadata and args.metadata_json:
+                raise ValueError(
+                    "--fetch-metadata cannot be combined with --metadata-json"
+                )
+            payload = build_github_public_reply_monitor_packet(
+                issue_url=args.issue_url,
+                after_comment_url=args.after_comment_url,
+                provider_payload=_load_json_object_or_array(args.metadata_json)
+                if args.metadata_json
+                else None,
+                fetch_metadata=args.fetch_metadata,
+                timeout_seconds=args.timeout_seconds,
+            )
+            print_payload(
+                payload,
+                output_format(args),
+                render_github_public_reply_monitor_markdown,
+            )
+            return 0 if payload.get("ok") else 1
+        if args.value_connectors_command != "plan":
+            raise ValueError(
+                "value-connectors requires `install-check`, `plan`, "
+                "`source-map`, `github-public-probe`, or `github-reply-monitor`"
+            )
+        if args.connector_id == LEGACY_FINANCE_CONNECTOR_ID:
+            payload = build_finance_extension_migration_contract()
+            print_payload(
+                payload,
+                output_format(args),
+                render_finance_extension_migration_markdown,
+            )
+            return 0
+        if args.connector_id:
+            missing = [
+                name
+                for name in (
+                    "channel",
+                    "target_ref",
+                    "money_metric",
+                    "success_metric",
+                    "kill_condition",
+                )
+                if not getattr(args, name)
+            ]
+            if missing:
+                raise ValueError(
+                    "single-call plan requires "
+                    + ", ".join(f"--{name.replace('_', '-')}" for name in missing)
+                )
+            plan = build_single_value_connector_plan(
+                connector_id=args.connector_id,
+                connector_kind=args.connector_kind,
+                channel=args.channel,
+                stage=args.stage,
+                target_ref=args.target_ref,
+                target_url=args.target_url,
+                audience=args.audience,
+                sender_identity=args.sender_identity,
+                value_axis=args.value_axis,
+                money_metric=args.money_metric,
+                success_metric=args.success_metric,
+                kill_condition=args.kill_condition,
+                generated_at=args.generated_at,
+                external_reads_allowed=args.external_read,
+                external_write_requested=args.external_write_requested,
+            )
+        else:
+            plan = build_value_connector_plan_fixture(
+                generated_at=args.generated_at,
+                scenario=args.scenario,
+            )
+        payload = build_value_connector_plan_packet(plan)
+    except Exception as exc:
+        if getattr(args, "value_connectors_command", None) == "github-public-probe":
+            payload = {
+                "ok": False,
+                "schema_version": "github_public_channel_probe_error_v0",
+                "mode": "github-public-channel-probe",
+                "error": str(exc),
+                "external_reads_performed": False,
+                "external_writes_performed": False,
+            }
+            print_payload(
+                payload,
+                output_format(args),
+                render_github_public_channel_probe_markdown,
+            )
+            return 1
+        if getattr(args, "value_connectors_command", None) == "github-reply-monitor":
+            payload = {
+                "ok": False,
+                "schema_version": "github_public_reply_monitor_error_v0",
+                "mode": "github-public-reply-monitor",
+                "error": str(exc),
+                "external_reads_performed": False,
+                "external_writes_performed": False,
+            }
+            print_payload(
+                payload,
+                output_format(args),
+                render_github_public_reply_monitor_markdown,
+            )
+            return 1
+        payload = {
+            "ok": False,
+            "schema_version": "value_connector_plan_error_v0",
+            "error": str(exc),
+        }
+        print_payload(
+            payload, output_format(args), render_value_connector_plan_markdown
+        )
+        return 1
+    print_payload(payload, output_format(args), render_value_connector_plan_markdown)
+    return 0

loopx/capabilities/value_connectors/finance_extension_migration.py

@@ -0,0 +1,108 @@
+from __future__ import annotations
+
+from collections.abc import Mapping
+from typing import Any
+
+
+FINANCE_EXTENSION_ID = "loopx-finance-value-discovery"
+LEGACY_FINANCE_CONNECTOR_ID = "finance_market_snapshot"
+FINANCE_EXTENSION_MIGRATION_SCHEMA_VERSION = "value_connector_extension_migration_v0"
+
+
+def build_finance_extension_migration_contract() -> dict[str, Any]:
+    """Describe the bounded route from the retired connector to the extension."""
+
+    return {
+        "ok": True,
+        "schema_version": FINANCE_EXTENSION_MIGRATION_SCHEMA_VERSION,
+        "mode": "finance-extension-migration",
+        "status": "migrated_to_extension",
+        "legacy_connector_id": LEGACY_FINANCE_CONNECTOR_ID,
+        "replacement_extension_id": FINANCE_EXTENSION_ID,
+        "replacement_capability_id": None,
+        "provider_distribution": "co_located_source_package",
+        "automatic_provider_install_supported": False,
+        "packaged_loopx_only_start_supported": False,
+        "agent_start_mode": "guided_when_provider_source_is_available",
+        "recommended_action": "inspect_then_install_register_run",
+        "source_checkout_required": True,
+        "source_checkout_paths": {
+            "package": "packages/loopx-finance-value-discovery",
+            "manifest": "packages/loopx-finance-value-discovery/extension.toml",
+            "example_input": (
+                "packages/loopx-finance-value-discovery/examples/"
+                "paypal-debeta-discovery.json"
+            ),
+        },
+        "agent_start_sequence": [
+            {
+                "step": "inspect_installed_extensions",
+                "command": "loopx extension list --format json",
+                "local_environment_write": False,
+            },
+            {
+                "step": "install_provider_from_source_checkout",
+                "command": (
+                    "python3 -m pip install ./packages/loopx-finance-value-discovery"
+                ),
+                "local_environment_write": True,
+                "condition": "provider entrypoint is absent and source checkout exists",
+            },
+            {
+                "step": "register_extension",
+                "command": (
+                    "loopx extension install --manifest "
+                    "packages/loopx-finance-value-discovery/extension.toml "
+                    "--execute --format json"
+                ),
+                "local_environment_write": True,
+                "condition": "provider entrypoint is installed but extension is absent",
+            },
+            {
+                "step": "run_extension",
+                "command": (
+                    "loopx extension run loopx-finance-value-discovery "
+                    "--input-json "
+                    "packages/loopx-finance-value-discovery/examples/"
+                    "paypal-debeta-discovery.json --execute --format json"
+                ),
+                "local_environment_write": False,
+                "condition": "extension is installed, enabled, and doctor-ready",
+            },
+        ],
+        "blocked_when": [
+            "the separately distributed provider source or package is unavailable",
+            "local environment writes are not authorized",
+            "extension doctor does not pass",
+        ],
+        "truth_contract": {
+            "legacy_connector_executes_finance": False,
+            "finance_capability_registered": False,
+            "provider_install_is_implicit": False,
+            "external_reads_performed": False,
+            "external_writes_performed": False,
+        },
+    }
+
+
+def render_finance_extension_migration_markdown(payload: Mapping[str, Any]) -> str:
+    """Render the retired Finance connector's extension migration contract."""
+
+    lines = [
+        "# Finance Connector Migration",
+        "",
+        f"- status: `{payload.get('status')}`",
+        f"- legacy_connector_id: `{payload.get('legacy_connector_id')}`",
+        f"- replacement_extension_id: `{payload.get('replacement_extension_id')}`",
+        "- replacement_capability_id: `none`",
+        "- automatic_provider_install_supported: "
+        f"`{payload.get('automatic_provider_install_supported')}`",
+        "",
+        "## Agent Start Sequence",
+    ]
+    for step in payload.get("agent_start_sequence") or []:
+        if isinstance(step, Mapping):
+            lines.append(f"- `{step.get('step')}`: `{step.get('command')}`")
+    lines.extend(["", "## Stop When"])
+    lines.extend(f"- {item}" for item in payload.get("blocked_when") or [])
+    return "\n".join(lines)

loopx/capabilities/value_connectors/install_check.py

@@ -0,0 +1,147 @@
+from __future__ import annotations
+
+import shutil
+from collections.abc import Mapping
+from typing import Any
+
+from ..content_ops.social_browser_x import build_social_browser_x_provider_packet
+from .finance_extension_migration import (
+    build_finance_extension_migration_contract,
+)
+
+
+VALUE_CONNECTOR_INSTALL_CHECK_PACKET_SCHEMA_VERSION = (
+    "value_connector_install_check_packet_v0"
+)
+
+
+def build_value_connector_install_check_packet(
+    *, connector: str = "all"
+) -> dict[str, Any]:
+    finance_migration = build_finance_extension_migration_contract()
+    checks = [
+        {
+            "connector_id": "github_public_channel",
+            "status": "ready" if shutil.which("python3") else "needs_python3",
+            "install": [
+                "python3 -m pip install -e .",
+                "loopx value-connectors github-public-probe --url https://github.com/owner/repo/issues/1 --format json",
+                "loopx value-connectors github-public-probe --url https://github.com/owner/repo/issues/1 --fetch-metadata --format json",
+                "loopx value-connectors github-reply-monitor --issue-url https://github.com/owner/repo/issues/1 --after-comment-url https://github.com/owner/repo/issues/1#issuecomment-1 --fetch-metadata --format json",
+            ],
+            "optional_tools": [
+                {
+                    "tool": "gh",
+                    "installed": shutil.which("gh") is not None,
+                    "needed_for": "discussion metadata fetch and reply-monitor metadata fetch",
+                    "install_hint": "Install GitHub CLI and run `gh auth login` if discussion metadata is needed.",
+                }
+            ],
+            "external_write_capability": False,
+        },
+        {
+            "connector_id": "agent_reach_ops_source_map",
+            "status": "ready" if shutil.which("agent-reach") else "needs_agent_reach",
+            "install": [
+                "Install Agent-Reach when available, then run `agent-reach doctor --json`.",
+                "Use `loopx value-connectors source-map --connector agent_reach_ops_source_map --format json` before drafting from external signals.",
+                "Keep Agent-Reach routes read-only; use LoopX evidence cards, maturity scores, and publish/audit gates for action.",
+            ],
+            "optional_tools": [
+                {
+                    "tool": "agent-reach",
+                    "installed": shutil.which("agent-reach") is not None,
+                    "needed_for": "source routing across public/read-only external channels",
+                    "install_hint": "Install Agent-Reach in the active agent environment and rerun `agent-reach doctor --json`.",
+                },
+                {
+                    "tool": "gh",
+                    "installed": shutil.which("gh") is not None,
+                    "needed_for": "GitHub-backed source routes and public repository search",
+                    "install_hint": "Install GitHub CLI and authenticate if GitHub source routes are needed.",
+                },
+            ],
+            "external_write_capability": False,
+        },
+        {
+            "connector_id": "finance_market_snapshot",
+            "status": "migrated_to_extension",
+            "install": [
+                step["command"] for step in finance_migration["agent_start_sequence"]
+            ],
+            "optional_tools": [],
+            "external_write_capability": False,
+            "migration": finance_migration,
+        },
+        {
+            "connector_id": "botmail_identity",
+            "status": "host_connector_required",
+            "install": [
+                "Install or enable a host email/Botmail connector.",
+                "Use LoopX only to plan the exact sender, recipient, subject, body, metric, and stop condition before sending.",
+            ],
+            "optional_tools": [],
+            "external_write_capability": True,
+            "write_gate": "exact sender/recipient/subject/body approval required before send",
+        },
+        {
+            "connector_id": "community_channel",
+            "status": "host_or_browser_connector_required",
+            "install": [
+                "Enable a browser or community connector owned by the user.",
+                "Run `loopx value-connectors plan` before signup, posting, or replies.",
+            ],
+            "optional_tools": [],
+            "external_write_capability": True,
+            "write_gate": "channel rules, account identity, exact message, and value metric required",
+        },
+        build_social_browser_x_provider_packet()["install_check"],
+    ]
+    selected = [
+        item
+        for item in checks
+        if connector == "all" or item["connector_id"] == connector
+    ]
+    if not selected:
+        raise ValueError("unknown connector install check")
+    return {
+        "ok": True,
+        "schema_version": VALUE_CONNECTOR_INSTALL_CHECK_PACKET_SCHEMA_VERSION,
+        "mode": "value-connector-install-check",
+        "connector": connector,
+        "checks": selected,
+        "truth_contract": {
+            "installation_check_only": True,
+            "external_reads_performed": False,
+            "external_writes_performed": False,
+            "restricted_material_recorded": False,
+        },
+    }
+
+
+def render_value_connector_install_check_markdown(payload: dict[str, Any]) -> str:
+    lines = ["# LoopX Value Connector Install Check", ""]
+    for item in payload.get("checks") or []:
+        if not isinstance(item, Mapping):
+            continue
+        lines.extend(
+            [
+                f"## {item.get('connector_id')}",
+                "",
+                f"- status: `{item.get('status')}`",
+                f"- external_write_capability: `{item.get('external_write_capability')}`",
+            ]
+        )
+        if item.get("write_gate"):
+            lines.append(f"- write_gate: {item.get('write_gate')}")
+        lines.extend(["", "Install / use:"])
+        for command in item.get("install") or []:
+            lines.append(f"- `{command}`")
+        for tool in item.get("optional_tools") or []:
+            if not isinstance(tool, Mapping):
+                continue
+            lines.append(
+                f"- optional `{tool.get('tool')}` installed=`{tool.get('installed')}`: {tool.get('needed_for')}"
+            )
+        lines.append("")
+    return "\n".join(lines).rstrip() + "\n"