@borgee/agents-host 0.2.33 → 0.2.44

package/skills/borgee-agent/scripts/borgee-agent.py

@@ -0,0 +1,547 @@
+#!/usr/bin/env python3
+
+from __future__ import annotations
+
+import json
+import os
+import re
+import sys
+from urllib.error import HTTPError, URLError
+from urllib.parse import quote
+from urllib.request import HTTPRedirectHandler, Request, build_opener
+
+MANUAL = """borgee-agent — read the Borgee channel this turn runs in, and act on its tasks.
+
+Usage:
+  borgee-agent --gateway <absolute path> <command> [arguments]
+  borgee-agent --help
+
+Commands:
+  health
+      Gateway reachability.
+  bootstrap
+      Channel bootstrap snapshot.
+  whoami
+      This agent's identity in this channel.
+  history [--limit <n>] [--before <n>] [--after <n>]
+      Recent messages in this channel.
+  users
+      Participants visible in this channel.
+  draft --turn-execution-id <id>
+      This turn's host-private in-flight draft.
+  send --body <text> --turn-execution-id <id> (--reply-to <message-id> | --mention <user-id>)...
+      Post a short auxiliary message. It must address someone.
+  mention <user-id> --body <text> --turn-execution-id <id> [--reply-to <message-id>]
+      Post a short auxiliary message addressed to one participant.
+  task list
+      Tasks in this channel. Parent channel only.
+  task create --title <text> [--description <text>] [--assignee-id <user-id>]
+      Create a task. Parent channel only.
+  task get [<task-id>]
+      One task with its properties.
+  task update [<task-id>] [--status <open|in_progress|in_review|done|cancelled>] [--title <text>] [--description <text>] [--assignee-id <user-id>]
+      Update the task. At least one field is required.
+  task history <task-id> [--limit <n>] [--before <n>] [--after <n>]
+      Messages in that task's thread.
+  task set-property [<task-id>] --key <key> --value <value>
+      Set one task property.
+  task delete-property [<task-id>] --key <key>
+      Remove one task property.
+
+Inside a task thread every task command with an optional task id acts on this thread's own task when the id is omitted, and task list / task create are refused there. In a parent channel the task id is required.
+
+Exit codes: 0 success, 1 gateway failure, 2 usage error.
+
+The full manual, including the task property registry and the error table, is SKILL.md in this skill directory."""
+
+# Python ints are arbitrary precision, so nothing can be rounded on the way into the query string;
+# the bound is here only so both packaged CLIs accept and reject exactly the same inputs. It is the
+# Node CLI that needs it: there an out-of-range magnitude re-stringifies as `1e+21`, which the
+# gateway's `Number.parseInt(value, 10)` reads back as `1`.
+INTEGER_ARGUMENT_PATTERN = re.compile(r"[+-]?[0-9]+")
+MAX_SAFE_INTEGER = 2**53 - 1
+
+# Spelled out instead of `str.isspace()` because the Node CLI must trim arguments and append the
+# mention separator on exactly the same inputs, and the two languages disagree on U+00A0, U+3000,
+# U+FEFF and U+001C…U+001F.
+PORTABLE_WHITESPACE = " \t\n\r\f\v"
+
+COMMANDS = frozenset(
+    {
+        "health",
+        "bootstrap",
+        "whoami",
+        "history",
+        "users",
+        "draft",
+        "send",
+        "mention",
+        "task",
+    }
+)
+
+TASK_COMMANDS = frozenset(
+    {
+        "list",
+        "create",
+        "get",
+        "update",
+        "history",
+        "set-property",
+        "delete-property",
+    }
+)
+
+
+class UsageError(Exception):
+    pass
+
+
+def trim_argument(value: str) -> str:
+    return value.strip(PORTABLE_WHITESPACE)
+
+
+def is_non_empty_string(value: object) -> bool:
+    return isinstance(value, str) and bool(trim_argument(value))
+
+
+def parse_args(argv: list[str]) -> dict[str, object]:
+    positionals: list[str] = []
+    mentions: list[str] = []
+    gateway_credential_path: str | None = None
+    turn_execution_id: str | None = None
+    limit: int | None = None
+    before: int | None = None
+    after: int | None = None
+    body: str | None = None
+    reply_to_id: str | None = None
+    title: str | None = None
+    description: str | None = None
+    assignee_id: str | None = None
+    status: str | None = None
+    property_key: str | None = None
+    property_value: str | None = None
+    index = 0
+
+    def take_value(flag: str) -> str:
+        nonlocal index
+        index += 1
+        if index >= len(argv):
+            raise UsageError(f"Missing value after {flag}")
+        return argv[index]
+
+    def take_integer(flag: str) -> int:
+        value = take_value(flag)
+        if not INTEGER_ARGUMENT_PATTERN.fullmatch(value):
+            raise UsageError(f"Invalid integer for {flag}: {value}")
+        parsed = int(value)
+        if abs(parsed) > MAX_SAFE_INTEGER:
+            raise UsageError(f"Integer out of range for {flag}: {value}")
+        return parsed
+
+    while index < len(argv):
+        arg = argv[index]
+        if arg in ("--help", "-h"):
+            return {"help": True}
+        if not arg.startswith("-"):
+            positionals.append(arg)
+        elif arg == "--gateway":
+            gateway_credential_path = take_value(arg)
+        elif arg == "--turn-execution-id":
+            turn_execution_id = trim_argument(take_value(arg))
+        elif arg == "--limit":
+            limit = take_integer(arg)
+        elif arg == "--before":
+            before = take_integer(arg)
+        elif arg == "--after":
+            after = take_integer(arg)
+        elif arg == "--body":
+            body = take_value(arg)
+        elif arg == "--reply-to":
+            reply_to_id = take_value(arg)
+        elif arg == "--mention":
+            mention = trim_argument(take_value(arg))
+            if not mention:
+                raise UsageError("Missing value after --mention")
+            mentions.append(mention)
+        elif arg == "--title":
+            title = take_value(arg)
+        elif arg == "--description":
+            description = take_value(arg)
+        elif arg == "--assignee-id":
+            assignee_id = take_value(arg)
+        elif arg == "--status":
+            status = take_value(arg)
+        elif arg == "--key":
+            property_key = trim_argument(take_value(arg))
+        elif arg == "--value":
+            property_value = take_value(arg)
+        else:
+            raise UsageError(f"Unknown argument: {arg}")
+        index += 1
+
+    if not positionals:
+        return {"help": False, "command": None}
+    command = positionals[0]
+    if command not in COMMANDS:
+        raise UsageError(f"Unknown command: {command}")
+
+    task_command: str | None = None
+    task_id: str | None = None
+    mention_target_id: str | None = None
+    consumed = 1
+    if command == "task":
+        if len(positionals) < 2:
+            raise UsageError(
+                "Missing task command; expected one of list, create, get, update, history, set-property, delete-property"
+            )
+        task_command = positionals[1]
+        if task_command not in TASK_COMMANDS:
+            raise UsageError(f"Unknown task command: {task_command}")
+        consumed = 2
+        if task_command not in ("list", "create") and len(positionals) > consumed:
+            task_id = trim_argument(positionals[consumed])
+            # Only an absent positional may mean the thread's own task. Treating an empty one as
+            # absent would send a write the caller meant for a named task to whatever task the
+            # thread resolves.
+            if not task_id:
+                raise UsageError(
+                    f'Empty task id for "task {task_command}"; pass a task id or omit the argument entirely'
+                )
+            consumed += 1
+    elif command == "mention" and len(positionals) > consumed:
+        mention_target_id = trim_argument(positionals[consumed])
+        consumed += 1
+    if len(positionals) > consumed:
+        raise UsageError(f"Unexpected argument: {positionals[consumed]}")
+
+    if gateway_credential_path is None:
+        raise UsageError("Missing required --gateway <path> argument")
+    if not os.path.isabs(gateway_credential_path):
+        raise UsageError(f"--gateway requires an absolute path: {gateway_credential_path}")
+
+    return {
+        "help": False,
+        "command": command,
+        "task_command": task_command,
+        "task_id": task_id,
+        "mention_target_id": mention_target_id,
+        "gateway_credential_path": gateway_credential_path,
+        "turn_execution_id": turn_execution_id,
+        "limit": limit,
+        "before": before,
+        "after": after,
+        "body": body,
+        "reply_to_id": reply_to_id,
+        "mentions": mentions,
+        "title": title,
+        "description": description,
+        "assignee_id": assignee_id,
+        "status": status,
+        "property_key": property_key,
+        "property_value": property_value,
+    }
+
+
+def command_label(parsed: dict[str, object]) -> str:
+    if parsed["command"] == "task":
+        return f"task {parsed['task_command']}"
+    return str(parsed["command"])
+
+
+def require_text(value: object, flag: str, label: str) -> None:
+    if not is_non_empty_string(value):
+        raise UsageError(f'Missing required {flag} <value> for "{label}"')
+
+
+def validate_command(parsed: dict[str, object]) -> None:
+    label = command_label(parsed)
+    command = parsed["command"]
+    if command == "draft":
+        require_text(parsed["turn_execution_id"], "--turn-execution-id", label)
+        return
+    if command == "send":
+        require_text(parsed["body"], "--body", label)
+        require_text(parsed["turn_execution_id"], "--turn-execution-id", label)
+        return
+    if command == "mention":
+        if not is_non_empty_string(parsed["mention_target_id"]):
+            raise UsageError('Missing required user id for "mention"')
+        if parsed["mentions"]:
+            raise UsageError("Do not combine the mention command with --mention flags")
+        require_text(parsed["body"], "--body", label)
+        require_text(parsed["turn_execution_id"], "--turn-execution-id", label)
+        return
+    if command != "task":
+        return
+    task_command = parsed["task_command"]
+    if task_command == "create":
+        require_text(parsed["title"], "--title", label)
+        return
+    if task_command == "update":
+        updated = (parsed["status"], parsed["title"], parsed["description"], parsed["assignee_id"])
+        if all(value is None for value in updated):
+            raise UsageError(
+                'At least one of --status, --title, --description or --assignee-id is required for "task update"'
+            )
+        return
+    if task_command == "history":
+        if parsed["task_id"] is None:
+            raise UsageError('Missing required task id for "task history"')
+        return
+    if task_command == "set-property":
+        require_text(parsed["property_key"], "--key", label)
+        # An empty property value is a legitimate string, so presence of the flag is the requirement.
+        if parsed["property_value"] is None:
+            raise UsageError('Missing required --value <value> for "task set-property"')
+        return
+    if task_command == "delete-property":
+        require_text(parsed["property_key"], "--key", label)
+
+
+# The credential path is used exactly as handed over: no walk-up, no glob, no environment lookup.
+# Task workspaces live inside the git repository and are not gitignored, so any search would
+# traverse attacker-influenceable directories where a planted file could redirect the gateway base
+# URL or point at another channel's credentials.
+def read_gateway_credential(gateway_credential_path: str) -> dict[str, str]:
+    try:
+        with open(gateway_credential_path, "rb") as handle:
+            encoded = handle.read()
+    except FileNotFoundError as exc:
+        raise UsageError(f"Gateway credential file not found: {gateway_credential_path}") from exc
+    try:
+        # Decoded strictly, like the Node CLI: a replacement character would silently mangle the
+        # channel id the request is issued against.
+        payload = json.loads(encoded.decode("utf-8"))
+    except (UnicodeDecodeError, json.JSONDecodeError) as exc:
+        raise UsageError(
+            f"{gateway_credential_path} is not a Borgee gateway credential"
+        ) from exc
+    channel_id = payload.get("channelId") if isinstance(payload, dict) else None
+    localhost_gateway = payload.get("localhostGateway") if isinstance(payload, dict) else None
+    base_url = localhost_gateway.get("baseUrl") if isinstance(localhost_gateway, dict) else None
+    token = localhost_gateway.get("token") if isinstance(localhost_gateway, dict) else None
+    if not (
+        is_non_empty_string(channel_id)
+        and is_non_empty_string(base_url)
+        and is_non_empty_string(token)
+    ):
+        raise UsageError(f"{gateway_credential_path} is not a Borgee gateway credential")
+    return {
+        "channel_id": str(channel_id),
+        "base_url": str(base_url).rstrip("/"),
+        "token": str(token),
+    }
+
+
+def ensure_visible_mention(body: str, participant_id: str) -> str:
+    token = f"<@{participant_id}>"
+    if token in body:
+        return body
+    separator = "" if body[-1:] in PORTABLE_WHITESPACE else " "
+    return f"{body}{separator}{token}"
+
+
+def ensure_visible_mentions(body: str, participant_ids: list[str]) -> str:
+    next_body = body
+    for participant_id in participant_ids:
+        next_body = ensure_visible_mention(next_body, participant_id)
+    return next_body
+
+
+def encode_component(value: str) -> str:
+    # quote() escapes more than JavaScript's encodeURIComponent does; widening the safe set to the
+    # difference keeps both CLIs issuing byte-identical request lines.
+    return quote(value, safe="!~*'()")
+
+
+def build_query(entries: list[tuple[str, object]]) -> str:
+    parts = [
+        f"{key}={encode_component(str(value))}" for key, value in entries if value is not None
+    ]
+    return f"?{'&'.join(parts)}" if parts else ""
+
+
+def history_query(parsed: dict[str, object]) -> str:
+    return build_query(
+        [("limit", parsed["limit"]), ("before", parsed["before"]), ("after", parsed["after"])]
+    )
+
+
+def build_message_body(parsed: dict[str, object]) -> dict[str, object]:
+    if parsed["command"] == "mention":
+        mentions = [str(parsed["mention_target_id"])]
+    else:
+        mentions = list(parsed["mentions"])
+    body = str(parsed["body"])
+    request_body: dict[str, object] = {
+        "body": ensure_visible_mentions(body, mentions) if mentions else body,
+        "turnExecutionId": parsed["turn_execution_id"],
+    }
+    reply_to_id = parsed["reply_to_id"]
+    if isinstance(reply_to_id, str) and trim_argument(reply_to_id):
+        request_body["replyToId"] = trim_argument(reply_to_id)
+    return request_body
+
+
+def build_task_create_body(parsed: dict[str, object]) -> dict[str, object]:
+    request_body: dict[str, object] = {"title": parsed["title"]}
+    if parsed["description"] is not None:
+        request_body["description"] = parsed["description"]
+    if parsed["assignee_id"] is not None:
+        request_body["assigneeId"] = parsed["assignee_id"]
+    return request_body
+
+
+def build_task_update_body(parsed: dict[str, object]) -> dict[str, object]:
+    request_body: dict[str, object] = {}
+    if parsed["status"] is not None:
+        request_body["status"] = parsed["status"]
+    if parsed["title"] is not None:
+        request_body["title"] = parsed["title"]
+    if parsed["description"] is not None:
+        request_body["description"] = parsed["description"]
+    if parsed["assignee_id"] is not None:
+        request_body["assigneeId"] = parsed["assignee_id"]
+    return request_body
+
+
+# Which task a bare `task` verb addresses is the gateway's decision, taken from the token binding:
+# in a task thread `current-task` resolves that thread's task, and in a parent channel it answers
+# not_found. The CLI therefore never inspects the turn's task assignment state.
+def resolve_task_request(
+    parsed: dict[str, object],
+    base_url: str,
+    channel: str,
+) -> dict[str, object]:
+    task_command = parsed["task_command"]
+    if task_command == "list":
+        return {"url": f"{base_url}/v1/channels/{channel}/tasks", "method": "GET", "body": None}
+    if task_command == "create":
+        return {
+            "url": f"{base_url}/v1/channels/{channel}/tasks",
+            "method": "POST",
+            "body": build_task_create_body(parsed),
+        }
+    if task_command == "history":
+        task_id = encode_component(str(parsed["task_id"]))
+        return {
+            "url": f"{base_url}/v1/tasks/{task_id}/history{history_query(parsed)}",
+            "method": "GET",
+            "body": None,
+        }
+    if parsed["task_id"] is None:
+        task_url = f"{base_url}/v1/channels/{channel}/current-task"
+    else:
+        task_url = f"{base_url}/v1/tasks/{encode_component(str(parsed['task_id']))}"
+    if task_command == "get":
+        return {"url": task_url, "method": "GET", "body": None}
+    if task_command == "update":
+        return {"url": task_url, "method": "PATCH", "body": build_task_update_body(parsed)}
+    property_url = f"{task_url}/properties/{encode_component(str(parsed['property_key']))}"
+    if task_command == "set-property":
+        return {"url": property_url, "method": "PUT", "body": {"value": parsed["property_value"]}}
+    return {"url": property_url, "method": "DELETE", "body": None}
+
+
+def resolve_request(credential: dict[str, str], parsed: dict[str, object]) -> dict[str, object]:
+    base_url = credential["base_url"]
+    channel = encode_component(credential["channel_id"])
+    command = parsed["command"]
+    if command == "health":
+        return {"url": f"{base_url}/health", "method": "GET", "body": None}
+    if command == "bootstrap":
+        return {
+            "url": f"{base_url}/v1/channels/{channel}/bootstrap",
+            "method": "GET",
+            "body": None,
+        }
+    if command == "whoami":
+        return {"url": f"{base_url}/v1/channels/{channel}/me", "method": "GET", "body": None}
+    if command == "history":
+        return {
+            "url": f"{base_url}/v1/channels/{channel}/history{history_query(parsed)}",
+            "method": "GET",
+            "body": None,
+        }
+    if command == "users":
+        return {"url": f"{base_url}/v1/channels/{channel}/users", "method": "GET", "body": None}
+    if command == "draft":
+        query = build_query([("turnExecutionId", parsed["turn_execution_id"])])
+        return {
+            "url": f"{base_url}/v1/channels/{channel}/draft{query}",
+            "method": "GET",
+            "body": None,
+        }
+    if command in ("send", "mention"):
+        return {
+            "url": f"{base_url}/v1/channels/{channel}/messages",
+            "method": "POST",
+            "body": build_message_body(parsed),
+        }
+    return resolve_task_request(parsed, base_url, channel)
+
+
+class RefuseRedirects(HTTPRedirectHandler):
+    """The gateway has no redirect routes, so a 3xx means something other than the gateway
+    answered. Following it would carry the channel token off the loopback address — the default
+    handler copies the Authorization header onto the new host — so the redirect is reported as the
+    failure it is, matching the Node CLI."""
+
+    def redirect_request(self, req, fp, code, msg, headers, newurl):
+        return None
+
+
+GATEWAY_OPENER = build_opener(RefuseRedirects)
+
+
+def call_gateway(credential: dict[str, str], request: dict[str, object]) -> object:
+    headers = {"Authorization": f"Bearer {credential['token']}"}
+    data = None
+    if request["body"] is not None:
+        headers["Content-Type"] = "application/json; charset=utf-8"
+        data = json.dumps(request["body"], ensure_ascii=False, separators=(",", ":")).encode(
+            "utf-8"
+        )
+    http_request = Request(
+        str(request["url"]), headers=headers, method=str(request["method"]), data=data
+    )
+    try:
+        with GATEWAY_OPENER.open(http_request) as response:
+            body_text = response.read().decode("utf-8")
+    except HTTPError as exc:
+        error_text = exc.read().decode("utf-8")
+        error_payload = json.loads(error_text) if error_text else None
+        reported = json.dumps(error_payload, ensure_ascii=False, separators=(",", ":"))
+        raise RuntimeError(f"Gateway request failed with {exc.code}: {reported}") from exc
+    except URLError as exc:
+        raise RuntimeError(
+            f"Cannot reach the localhost gateway at {credential['base_url']}: {exc.reason}"
+        ) from exc
+    return json.loads(body_text) if body_text else None
+
+
+def main() -> int:
+    parsed = parse_args(sys.argv[1:])
+    if parsed.get("help") is True:
+        sys.stdout.write(f"{MANUAL}\n")
+        return 0
+    if parsed["command"] is None:
+        sys.stderr.write(f"{MANUAL}\n")
+        return 2
+    validate_command(parsed)
+    credential = read_gateway_credential(str(parsed["gateway_credential_path"]))
+    result = call_gateway(credential, resolve_request(credential, parsed))
+    sys.stdout.write(json.dumps(result, indent=2, ensure_ascii=False) + "\n")
+    return 0
+
+
+if __name__ == "__main__":
+    try:
+        sys.exit(main())
+    except UsageError as error:
+        sys.stderr.write(f"error: {error}\n")
+        sys.exit(2)
+    except Exception as error:
+        sys.stderr.write(f"error: {error}\n")
+        sys.exit(1)