npm - @clawpump/claw-agent - Versions diffs - 0.1.5 → 0.1.6 - Mend

@clawpump/claw-agent 0.1.5 → 0.1.6

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (1212) hide show

package/agent/skills/productivity/linear/scripts/linear_api.py DELETED Viewed

@@ -1,445 +0,0 @@
-#!/usr/bin/env python3
-"""Linear GraphQL API CLI — zero dependencies, stdlib only.
-Usage:
-  linear_api.py <command> [args...]
-Commands:
-  whoami                                  Show authenticated user
-  list-teams                              List all teams
-  list-projects [--team KEY]              List projects (optionally filter by team)
-  list-states [--team KEY]                List workflow states
-  list-issues [filters]                   List issues
-    --team KEY                            Filter by team key (e.g. ENG)
-    --status NAME                         Filter by workflow state name
-    --assignee NAME                       Filter by assignee name (exact)
-    --label NAME                          Filter by label name
-    --limit N                             Max results (default: 25)
-  get-issue <IDENTIFIER>                  Full issue details (e.g. ENG-42)
-  search-issues <query>                   Full-text search across issues
-  create-issue [options]                  Create a new issue
-    --title TITLE                         Required
-    --team KEY                            Required
-    --description DESC
-    --priority 0-4                        0=none, 1=urgent, 4=low
-    --label NAME
-    --assignee NAME
-    --parent IDENTIFIER                   Parent issue ID for sub-issues
-  update-issue <IDENTIFIER> [options]     Update existing issue (same options as create)
-  update-status <IDENTIFIER> <STATE>      Move issue to workflow state (by state name)
-  add-comment <IDENTIFIER> <body>         Add comment to issue
-  list-documents [--limit N]              List documents (docs, not issues)
-  get-document <SLUG_OR_ID>               Fetch a document by slugId (from URL) or UUID
-  search-documents <query>                Search documents by title
-  raw <graphql_query> [variables_json]    Run an arbitrary GraphQL query
-                                          Use --vars '{"key":"value"}' for variables
-Auth:
-  Set LINEAR_API_KEY environment variable (from Linear Settings -> API).
-  Uses the personal API key header format: `Authorization: <KEY>` (no Bearer prefix).
-Output:
-  JSON to stdout. Errors to stderr with non-zero exit code.
-"""
-from __future__ import annotations
-import argparse
-import json
-import os
-import sys
-import urllib.error
-import urllib.request
-from typing import Any
-API_URL = "https://api.linear.app/graphql"
-def _get_key() -> str:
-    key = os.environ.get("LINEAR_API_KEY", "").strip()
-    if not key:
-        sys.stderr.write(
-            "ERROR: LINEAR_API_KEY not set.\n"
-            "Create one at https://linear.app/settings/api and export it,\n"
-            "or add `LINEAR_API_KEY=lin_api_...` to ~/.hermes/.env\n"
-        )
-        sys.exit(2)
-    return key
-def gql(query: str, variables: dict[str, Any] | None = None) -> dict[str, Any]:
-    """Execute a GraphQL query against Linear. Raises on HTTP error or GraphQL errors."""
-    key = _get_key()
-    payload = {"query": query}
-    if variables:
-        payload["variables"] = variables
-    data = json.dumps(payload).encode("utf-8")
-    req = urllib.request.Request(
-        API_URL,
-        data=data,
-        headers={
-            "Content-Type": "application/json",
-            "Authorization": key,  # Personal API key — NO `Bearer` prefix
-            "User-Agent": "hermes-agent-linear-skill/1.0",
-        },
-        method="POST",
-    )
-    try:
-        with urllib.request.urlopen(req, timeout=30) as resp:
-            body = resp.read().decode("utf-8")
-    except urllib.error.HTTPError as e:
-        sys.stderr.write(f"HTTP {e.code}: {e.read().decode('utf-8', 'replace')}\n")
-        sys.exit(1)
-    except urllib.error.URLError as e:
-        sys.stderr.write(f"Network error: {e}\n")
-        sys.exit(1)
-    result = json.loads(body)
-    if "errors" in result and result["errors"]:
-        sys.stderr.write(f"GraphQL errors: {json.dumps(result['errors'], indent=2)}\n")
-        # Still return data if partial success; let caller decide
-        if not result.get("data"):
-            sys.exit(1)
-    return result.get("data", {}) or {}
-def emit(obj: Any) -> None:
-    print(json.dumps(obj, indent=2, default=str))
-# ---------- Commands ----------
-def cmd_whoami(_args: argparse.Namespace) -> None:
-    q = "query { viewer { id name email displayName } }"
-    emit(gql(q).get("viewer"))
-def cmd_list_teams(_args: argparse.Namespace) -> None:
-    q = "query { teams(first: 100) { nodes { id key name description } } }"
-    emit(gql(q).get("teams", {}).get("nodes", []))
-def _resolve_team_id(key_or_name: str) -> str | None:
-    """Map a team key (ENG) or name to UUID."""
-    q = "query { teams(first: 100) { nodes { id key name } } }"
-    teams = gql(q).get("teams", {}).get("nodes", [])
-    kl = key_or_name.lower()
-    for t in teams:
-        if t["key"].lower() == kl or t["name"].lower() == kl:
-            return t["id"]
-    return None
-def cmd_list_projects(args: argparse.Namespace) -> None:
-    if args.team:
-        tid = _resolve_team_id(args.team)
-        if not tid:
-            sys.stderr.write(f"Team not found: {args.team}\n")
-            sys.exit(1)
-        q = """query($id: String!) {
-          team(id: $id) { projects(first: 100) { nodes { id name description state } } }
-        }"""
-        data = gql(q, {"id": tid})
-        emit(data.get("team", {}).get("projects", {}).get("nodes", []))
-    else:
-        q = "query { projects(first: 100) { nodes { id name description state } } }"
-        emit(gql(q).get("projects", {}).get("nodes", []))
-def cmd_list_states(args: argparse.Namespace) -> None:
-    if args.team:
-        tid = _resolve_team_id(args.team)
-        if not tid:
-            sys.stderr.write(f"Team not found: {args.team}\n")
-            sys.exit(1)
-        q = """query($id: String!) {
-          team(id: $id) { states(first: 100) { nodes { id name type color } } }
-        }"""
-        emit(gql(q, {"id": tid}).get("team", {}).get("states", {}).get("nodes", []))
-    else:
-        q = "query { workflowStates(first: 200) { nodes { id name type team { key } } } }"
-        emit(gql(q).get("workflowStates", {}).get("nodes", []))
-def cmd_list_issues(args: argparse.Namespace) -> None:
-    filt: dict[str, Any] = {}
-    if args.team:
-        filt["team"] = {"key": {"eq": args.team}}
-    if args.status:
-        filt["state"] = {"name": {"eq": args.status}}
-    if args.assignee:
-        filt["assignee"] = {"name": {"eq": args.assignee}}
-    if args.label:
-        filt["labels"] = {"name": {"eq": args.label}}
-    q = """query($filter: IssueFilter, $first: Int!) {
-      issues(filter: $filter, first: $first, orderBy: updatedAt) {
-        nodes {
-          id identifier title
-          state { name } priority
-          assignee { name }
-          team { key }
-          updatedAt url
-        }
-      }
-    }"""
-    data = gql(q, {"filter": filt or None, "first": args.limit})
-    emit(data.get("issues", {}).get("nodes", []))
-def cmd_get_issue(args: argparse.Namespace) -> None:
-    q = """query($id: String!) {
-      issue(id: $id) {
-        id identifier title description
-        state { name type }
-        priority priorityLabel
-        assignee { name email }
-        creator { name }
-        team { key name }
-        project { name }
-        labels { nodes { name } }
-        parent { identifier title }
-        children { nodes { identifier title state { name } } }
-        comments { nodes { user { name } body createdAt } }
-        createdAt updatedAt url
-      }
-    }"""
-    emit(gql(q, {"id": args.identifier}).get("issue"))
-def cmd_search_issues(args: argparse.Namespace) -> None:
-    q = """query($term: String!, $first: Int!) {
-      searchIssues(term: $term, first: $first) {
-        nodes { id identifier title state { name } url }
-      }
-    }"""
-    emit(gql(q, {"term": args.query, "first": args.limit}).get("searchIssues", {}).get("nodes", []))
-def cmd_create_issue(args: argparse.Namespace) -> None:
-    tid = _resolve_team_id(args.team)
-    if not tid:
-        sys.stderr.write(f"Team not found: {args.team}\n")
-        sys.exit(1)
-    inp: dict[str, Any] = {"title": args.title, "teamId": tid}
-    if args.description:
-        inp["description"] = args.description
-    if args.priority is not None:
-        inp["priority"] = args.priority
-    if args.parent:
-        inp["parentId"] = args.parent
-    # TODO: label + assignee name->id lookup (omitted for v1 brevity)
-    q = """mutation($input: IssueCreateInput!) {
-      issueCreate(input: $input) {
-        success issue { id identifier title url }
-      }
-    }"""
-    emit(gql(q, {"input": inp}).get("issueCreate"))
-def cmd_update_issue(args: argparse.Namespace) -> None:
-    inp: dict[str, Any] = {}
-    if args.title:
-        inp["title"] = args.title
-    if args.description:
-        inp["description"] = args.description
-    if args.priority is not None:
-        inp["priority"] = args.priority
-    if not inp:
-        sys.stderr.write("No update fields provided.\n")
-        sys.exit(1)
-    q = """mutation($id: String!, $input: IssueUpdateInput!) {
-      issueUpdate(id: $id, input: $input) {
-        success issue { identifier title url }
-      }
-    }"""
-    emit(gql(q, {"id": args.identifier, "input": inp}).get("issueUpdate"))
-def cmd_update_status(args: argparse.Namespace) -> None:
-    # Resolve state name -> id within the issue's team
-    get_q = """query($id: String!) {
-      issue(id: $id) { team { id states(first: 100) { nodes { id name } } } }
-    }"""
-    issue = gql(get_q, {"id": args.identifier}).get("issue")
-    if not issue:
-        sys.stderr.write(f"Issue not found: {args.identifier}\n")
-        sys.exit(1)
-    sl = args.state.lower()
-    match = next((s for s in issue["team"]["states"]["nodes"] if s["name"].lower() == sl), None)
-    if not match:
-        sys.stderr.write(
-            f"State '{args.state}' not found. Available: "
-            f"{[s['name'] for s in issue['team']['states']['nodes']]}\n"
-        )
-        sys.exit(1)
-    q = """mutation($id: String!, $stateId: String!) {
-      issueUpdate(id: $id, input: { stateId: $stateId }) {
-        success issue { identifier state { name } url }
-      }
-    }"""
-    emit(gql(q, {"id": args.identifier, "stateId": match["id"]}).get("issueUpdate"))
-def cmd_add_comment(args: argparse.Namespace) -> None:
-    q = """mutation($input: CommentCreateInput!) {
-      commentCreate(input: $input) {
-        success comment { id body createdAt }
-      }
-    }"""
-    emit(gql(q, {"input": {"issueId": args.identifier, "body": args.body}}).get("commentCreate"))
-# ---- Documents ----
-def cmd_list_documents(args: argparse.Namespace) -> None:
-    q = """query($first: Int!) {
-      documents(first: $first, orderBy: updatedAt) {
-        nodes { id title slugId updatedAt url project { name } creator { name } }
-      }
-    }"""
-    emit(gql(q, {"first": args.limit}).get("documents", {}).get("nodes", []))
-def cmd_get_document(args: argparse.Namespace) -> None:
-    """Fetch a document by slugId (from URL) OR full UUID.
-    Linear document URLs look like:
-      https://linear.app/<workspace>/document/<slug>-<shortid>
-    The part we want is the final hex segment (the slugId).
-    """
-    ref = args.ref
-    # If it looks like a UUID, query by id. Otherwise, assume slugId.
-    is_uuid = len(ref) == 36 and ref.count("-") == 4
-    if is_uuid:
-        q = """query($id: String!) {
-          document(id: $id) {
-            id title content contentState slugId
-            createdAt updatedAt url
-            creator { name } project { name }
-          }
-        }"""
-        emit(gql(q, {"id": ref}).get("document"))
-    else:
-        # Query the collection and filter by slugId — the doc() query only accepts UUIDs.
-        q = """query($slug: String!) {
-          documents(filter: { slugId: { eq: $slug } }, first: 1) {
-            nodes {
-              id title content contentState slugId
-              createdAt updatedAt url
-              creator { name } project { name }
-            }
-          }
-        }"""
-        nodes = gql(q, {"slug": ref}).get("documents", {}).get("nodes", [])
-        emit(nodes[0] if nodes else None)
-def cmd_search_documents(args: argparse.Namespace) -> None:
-    # Linear doesn't have a first-class searchDocuments — use title filter as a fallback.
-    q = """query($term: String!, $first: Int!) {
-      documents(filter: { title: { containsIgnoreCase: $term } }, first: $first) {
-        nodes { id title slugId url updatedAt }
-      }
-    }"""
-    emit(gql(q, {"term": args.query, "first": args.limit}).get("documents", {}).get("nodes", []))
-def cmd_raw(args: argparse.Namespace) -> None:
-    variables = json.loads(args.vars) if args.vars else None
-    emit(gql(args.query, variables))
-# ---------- Arg parsing ----------
-def build_parser() -> argparse.ArgumentParser:
-    p = argparse.ArgumentParser(prog="linear_api.py", description="Linear GraphQL CLI")
-    sub = p.add_subparsers(dest="cmd", required=True)
-    sub.add_parser("whoami").set_defaults(func=cmd_whoami)
-    sub.add_parser("list-teams").set_defaults(func=cmd_list_teams)
-    lp = sub.add_parser("list-projects")
-    lp.add_argument("--team")
-    lp.set_defaults(func=cmd_list_projects)
-    ls = sub.add_parser("list-states")
-    ls.add_argument("--team")
-    ls.set_defaults(func=cmd_list_states)
-    li = sub.add_parser("list-issues")
-    li.add_argument("--team")
-    li.add_argument("--status")
-    li.add_argument("--assignee")
-    li.add_argument("--label")
-    li.add_argument("--limit", type=int, default=25)
-    li.set_defaults(func=cmd_list_issues)
-    gi = sub.add_parser("get-issue")
-    gi.add_argument("identifier")
-    gi.set_defaults(func=cmd_get_issue)
-    si = sub.add_parser("search-issues")
-    si.add_argument("query")
-    si.add_argument("--limit", type=int, default=25)
-    si.set_defaults(func=cmd_search_issues)
-    ci = sub.add_parser("create-issue")
-    ci.add_argument("--title", required=True)
-    ci.add_argument("--team", required=True)
-    ci.add_argument("--description")
-    ci.add_argument("--priority", type=int, choices=[0, 1, 2, 3, 4])
-    ci.add_argument("--label")
-    ci.add_argument("--assignee")
-    ci.add_argument("--parent")
-    ci.set_defaults(func=cmd_create_issue)
-    ui = sub.add_parser("update-issue")
-    ui.add_argument("identifier")
-    ui.add_argument("--title")
-    ui.add_argument("--description")
-    ui.add_argument("--priority", type=int, choices=[0, 1, 2, 3, 4])
-    ui.set_defaults(func=cmd_update_issue)
-    us = sub.add_parser("update-status")
-    us.add_argument("identifier")
-    us.add_argument("state")
-    us.set_defaults(func=cmd_update_status)
-    ac = sub.add_parser("add-comment")
-    ac.add_argument("identifier")
-    ac.add_argument("body")
-    ac.set_defaults(func=cmd_add_comment)
-    ld = sub.add_parser("list-documents")
-    ld.add_argument("--limit", type=int, default=50)
-    ld.set_defaults(func=cmd_list_documents)
-    gd = sub.add_parser("get-document")
-    gd.add_argument("ref", help="slugId (hex suffix from URL) or full UUID")
-    gd.set_defaults(func=cmd_get_document)
-    sd = sub.add_parser("search-documents")
-    sd.add_argument("query")
-    sd.add_argument("--limit", type=int, default=25)
-    sd.set_defaults(func=cmd_search_documents)
-    r = sub.add_parser("raw")
-    r.add_argument("query")
-    r.add_argument("--vars", help="JSON string of variables")
-    r.set_defaults(func=cmd_raw)
-    return p
-def main(argv: list[str] | None = None) -> None:
-    parser = build_parser()
-    args = parser.parse_args(argv)
-    args.func(args)
-if __name__ == "__main__":
-    main()

package/agent/skills/software-development/debugging-hermes-tui-commands/SKILL.md DELETED Viewed

@@ -1,152 +0,0 @@
----
-name: debugging-hermes-tui-commands
-description: "Debug Hermes TUI slash commands: Python, gateway, Ink UI."
-version: 1.0.0
-author: Hermes Agent
-license: MIT
-platforms: [linux, macos, windows]
-metadata:
-  hermes:
-    tags: [debugging, hermes-agent, tui, slash-commands, typescript, python]
-    related_skills: [python-debugpy, node-inspect-debugger, systematic-debugging]
----
-# Debugging Hermes TUI Slash Commands
-## Overview
-Hermes slash commands span three layers — Python command registry, tui_gateway JSON-RPC bridge, and the Ink/TypeScript frontend. When a command misbehaves (missing from autocomplete, works in CLI but not TUI, config persists but UI doesn't update), the bug is almost always one layer being out of sync with another.
-Use this skill when you encounter issues with slash commands in the Hermes TUI, particularly when commands aren't showing in autocomplete, aren't working properly in the TUI, or need to be added/updated.
-## When to Use
-- A slash command exists in one part of the codebase but doesn't work fully
-- A command needs to be added to both backend and frontend
-- Command autocomplete isn't working for specific commands
-- Command behavior is inconsistent between CLI and TUI
-- A command persists config but doesn't apply live in the TUI
-## Architecture Overview
-```
-Python backend (hermes_cli/commands.py)     <- canonical COMMAND_REGISTRY
-       │
-       ▼
-TUI gateway (tui_gateway/server.py)         <- slash.exec / command.dispatch
-       │
-       ▼
-TUI frontend (ui-tui/src/app/slash/)        <- local handlers + fallthrough
-```
-Command definitions must be registered consistently across Python and TypeScript to work properly. The Python `COMMAND_REGISTRY` is the source of truth for: CLI dispatch, gateway help, Telegram BotCommand menu, Slack subcommand map, and autocomplete data shipped to Ink.
-## Investigation Steps
-1. **Check if the command exists in the TUI frontend:**
-   ```bash
-   search_files --pattern "/commandname" --file_glob "*.ts" --path ui-tui/
-   search_files --pattern "/commandname" --file_glob "*.tsx" --path ui-tui/
-   ```
-2. **Examine the TUI command definition:**
-   ```bash
-   read_file ui-tui/src/app/slash/commands/core.ts
-   # If not there:
-   search_files --pattern "commandname" --path ui-tui/src/app/slash/commands --target files
-   ```
-3. **Check if the command exists in the Python backend:**
-   ```bash
-   search_files --pattern "CommandDef" --file_glob "*.py" --path hermes_cli/
-   search_files --pattern "commandname" --path hermes_cli/commands.py --context 3
-   ```
-4. **Examine the gateway implementation:**
-   ```bash
-   search_files --pattern "complete.slash|slash.exec" --path tui_gateway/
-   ```
-## Fix: Missing Command Autocomplete
-If a command exists in the TUI but doesn't show in autocomplete:
-1. Add a `CommandDef` entry to `COMMAND_REGISTRY` in `hermes_cli/commands.py`:
-   ```python
-   CommandDef("commandname", "Description of the command", "Session",
-              cli_only=True, aliases=("alias",),
-              args_hint="[arg1|arg2|arg3]",
-              subcommands=("arg1", "arg2", "arg3")),
-   ```
-2. Pick `cli_only` vs gateway availability carefully:
-   - `cli_only=True` — only in the interactive CLI/TUI
-   - `gateway_only=True` — only in messaging platforms
-   - neither — available everywhere
-   - `gateway_config_gate="display.foo"` — config-gated availability in the gateway
-3. Ensure `subcommands` matches the expected tab-completion options shown by the TUI.
-4. If the command runs server-side, add a handler in `HermesCLI.process_command()` in `cli.py`:
-   ```python
-   elif canonical == "commandname":
-       self._handle_commandname(cmd_original)
-   ```
-5. For gateway-available commands, add a handler in `gateway/run.py`:
-   ```python
-   if canonical == "commandname":
-       return await self._handle_commandname(event)
-   ```
-## Common Issues
-1. **Command shows in TUI but not in autocomplete.** The command is defined in the TUI codebase but missing from `COMMAND_REGISTRY` in `hermes_cli/commands.py`. Autocomplete data ships from Python.
-2. **Command shows in autocomplete but doesn't work.** Check the command handler in `tui_gateway/server.py` and the frontend handler in `ui-tui/src/app/createSlashHandler.ts`. If the command is local-only in Ink, it must be handled in `app.tsx` built-in branch; otherwise it falls through to `slash.exec` and must have a Python handler.
-3. **Command behavior differs between CLI and TUI.** The command might have different implementations. Check both `cli.py::process_command` and the TUI's local handler. Local TUI handlers take precedence over gateway dispatch.
-4. **Command persists config but doesn't apply live.** For TUI-local commands, updating `config.set` is not enough. Also patch the relevant nanostore state immediately (usually `patchUiState(...)`) and pass any new state through rendering components. Example: `/details collapsed` must update live detail visibility, not just save `details_mode`; in-session global `/details <mode>` may need a separate command-override flag so live commands can override built-in section defaults while startup/config sync preserves default-expanded thinking/tools behavior.
-5. **Gateway dispatch silently ignores the command.** The gateway only dispatches commands it knows about. Check `GATEWAY_KNOWN_COMMANDS` (derived from `COMMAND_REGISTRY` automatically) includes the canonical name. If the command is `cli_only` with a `gateway_config_gate`, verify the gated config value is truthy.
-## Debugging Tactics
-When surface-level inspection doesn't reveal the bug:
-- **Python side hangs or misbehaves:** use the `python-debugpy` skill to break inside `_SlashWorker.exec` or the command handler. `remote-pdb` set at the handler entry is the fastest path.
-- **Ink side not reacting:** use the `node-inspect-debugger` skill to break in `app.tsx`'s slash dispatch or the local command branch. `sb('dist/app.js', <line>)` after `npm run build`.
-- **Registry mismatch / unclear which side is wrong:** compare the canonical `COMMAND_REGISTRY` entry against the TUI's local command list side-by-side.
-## Pitfalls
-- Don't forget to set the appropriate category for the command in `CommandDef` (e.g., "Session", "Configuration", "Tools & Skills", "Info", "Exit")
-- Make sure any aliases are properly registered in the `aliases` tuple — no other file changes are needed, everything downstream (Telegram menu, Slack mapping, autocomplete, help) derives from it
-- For commands with subcommands, ensure the `subcommands` tuple in `CommandDef` matches what's in the TUI code
-- `cli_only=True` commands won't work in gateway/messaging platforms — unless you add a `gateway_config_gate` and the gate is truthy
-- After adding live UI state, search every consumer of the old prop/helper and thread the new state through all render paths, not just the active streaming path. TUI detail rendering has at least two important paths: live `StreamingAssistant`/`ToolTrail` and transcript/pending `MessageLine` rows. A `/clean` pass should explicitly check both.
-- Rebuild the TUI (`npm --prefix ui-tui run build`) before testing — tsx watch mode may lag on first launch
-## Verification
-After fixing:
-1. Rebuild the TUI:
-   ```bash
-   cd /home/bb/hermes-agent && npm --prefix ui-tui run build
-   ```
-2. Run the TUI and test the command:
-   ```bash
-   hermes --tui
-   ```
-3. Type `/` and verify the command appears in autocomplete suggestions with the expected description and args hint.
-4. Execute the command and confirm:
-   - Expected behavior fires
-   - Any persisted config updates correctly (`read_file ~/.hermes/config.yaml`)
-   - Live UI state reflects the change immediately (not just after restart)
-5. If the command is also gateway-available, test it from at least one messaging platform (or run the gateway tests: `scripts/run_tests.sh tests/gateway/`).