grokbot-kit 0.1.0__tar.gz

grokbot_kit-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Rodrigo Pasini
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

grokbot_kit-0.1.0/PKG-INFO

@@ -0,0 +1,88 @@
+Metadata-Version: 2.4
+Name: grokbot-kit
+Version: 0.1.0
+Summary: Grok Bot integration kit: delegate tasks to headless coding agents (opencode, Claude Code, Codex) and wake the right Grok Bot routine when they finish or need input.
+Author: Rodrigo Pasini
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Environment :: Console
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.11
+Project-URL: Repository, https://github.com/rodrigo-pasini/grokbot-kit
+Description-Content-Type: text/markdown
+
+# grokbot-kit
+
+Grok Bot integration kit: delegate tasks to headless coding agents (opencode, Claude Code, Codex) and wake the right
+Grok Bot routine when they finish or need input.
+
+> Leia em português: [docs/pt-BR/README.md](docs/pt-BR/README.md)
+
+**Status:** pre-release. The repository scaffold is in place; the commands below are being built and are not usable
+yet.
+
+## What it is
+
+A Grok Bot that delegates a long task to a headless coding agent hibernates while the agent runs, and nothing wakes
+it up. The exit code alone does not tell whether the task was done, failed, or stopped at a permission prompt.
+
+`grokbot-kit` wraps the agent run (`grokbot-kit run`), listens to each agent's native hooks, and sends exactly one
+terminal event (`completed`, `error` or `timeout`) — plus a `needs_input` event when the agent hits a permission — to
+the webhook trigger of the routine of the bot that delegated the task. Other bots are not woken up.
+
+## Install
+
+```sh
+uv tool install --managed-python grokbot-kit
+```
+
+`pipx install grokbot-kit` also works. Before the first release, install from the repository:
+
+```sh
+uv tool install git+https://github.com/rodrigo-pasini/grokbot-kit
+```
+
+Requires Linux and Python 3.11 or newer (`uv` manages the interpreter). The package has no runtime dependencies.
+
+## Quick start
+
+```sh
+grokbot-kit setup cli add opencode
+grokbot-kit setup default opencode
+grokbot-kit secret set mybot-url
+grokbot-kit secret set mybot-key
+grokbot-kit route add mybot --url-secret mybot-url --key-secret mybot-key
+grokbot-kit route test mybot
+grokbot-kit run --target mybot --label rename-vars -- "Rename the variables in x.py"
+```
+
+## Grok Bot skill
+
+`skills/grokbot-kit/` is a skill for any Grok Bot. Copy the folder into the bot's workflows directory and the bot can
+install the kit, install and log in to the CLIs you choose, create the route to its own routine, and delegate tasks
+choosing CLI and model.
+
+## Configuration
+
+The configuration lives in `~/.config/grokbot-kit/config.toml`: installed CLIs and the default one, model tiers
+(`trivial`, `standard`, `complex`) per CLI, timeouts per tier, and one route per target bot. Each task keeps its
+output, logs and events in `~/.grokbot-kit/tasks/<task_id>/` until `grokbot-kit gc` removes it.
+
+## Security
+
+- Secrets (routine URL and key, API keys) are written with `grokbot-kit secret set` to `~/.secrets/grokbot-kit/`
+  with mode `0600`, never to the config file and never pasted into a chat.
+- `grokbot-kit` never writes a secret to logs, stdout, stderr or events.
+- `~/.claude/settings.json` and `~/.codex/` are never modified; Codex runs in its own `CODEX_HOME`.
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md).
+
+## License
+
+[MIT](LICENSE). Third-party material in this repository is listed in [NOTICE](NOTICE).

grokbot_kit-0.1.0/README.md

@@ -0,0 +1,71 @@
+# grokbot-kit
+
+Grok Bot integration kit: delegate tasks to headless coding agents (opencode, Claude Code, Codex) and wake the right
+Grok Bot routine when they finish or need input.
+
+> Leia em português: [docs/pt-BR/README.md](docs/pt-BR/README.md)
+
+**Status:** pre-release. The repository scaffold is in place; the commands below are being built and are not usable
+yet.
+
+## What it is
+
+A Grok Bot that delegates a long task to a headless coding agent hibernates while the agent runs, and nothing wakes
+it up. The exit code alone does not tell whether the task was done, failed, or stopped at a permission prompt.
+
+`grokbot-kit` wraps the agent run (`grokbot-kit run`), listens to each agent's native hooks, and sends exactly one
+terminal event (`completed`, `error` or `timeout`) — plus a `needs_input` event when the agent hits a permission — to
+the webhook trigger of the routine of the bot that delegated the task. Other bots are not woken up.
+
+## Install
+
+```sh
+uv tool install --managed-python grokbot-kit
+```
+
+`pipx install grokbot-kit` also works. Before the first release, install from the repository:
+
+```sh
+uv tool install git+https://github.com/rodrigo-pasini/grokbot-kit
+```
+
+Requires Linux and Python 3.11 or newer (`uv` manages the interpreter). The package has no runtime dependencies.
+
+## Quick start
+
+```sh
+grokbot-kit setup cli add opencode
+grokbot-kit setup default opencode
+grokbot-kit secret set mybot-url
+grokbot-kit secret set mybot-key
+grokbot-kit route add mybot --url-secret mybot-url --key-secret mybot-key
+grokbot-kit route test mybot
+grokbot-kit run --target mybot --label rename-vars -- "Rename the variables in x.py"
+```
+
+## Grok Bot skill
+
+`skills/grokbot-kit/` is a skill for any Grok Bot. Copy the folder into the bot's workflows directory and the bot can
+install the kit, install and log in to the CLIs you choose, create the route to its own routine, and delegate tasks
+choosing CLI and model.
+
+## Configuration
+
+The configuration lives in `~/.config/grokbot-kit/config.toml`: installed CLIs and the default one, model tiers
+(`trivial`, `standard`, `complex`) per CLI, timeouts per tier, and one route per target bot. Each task keeps its
+output, logs and events in `~/.grokbot-kit/tasks/<task_id>/` until `grokbot-kit gc` removes it.
+
+## Security
+
+- Secrets (routine URL and key, API keys) are written with `grokbot-kit secret set` to `~/.secrets/grokbot-kit/`
+  with mode `0600`, never to the config file and never pasted into a chat.
+- `grokbot-kit` never writes a secret to logs, stdout, stderr or events.
+- `~/.claude/settings.json` and `~/.codex/` are never modified; Codex runs in its own `CODEX_HOME`.
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md).
+
+## License
+
+[MIT](LICENSE). Third-party material in this repository is listed in [NOTICE](NOTICE).

grokbot_kit-0.1.0/pyproject.toml

@@ -0,0 +1,58 @@
+[project]
+name = "grokbot-kit"
+version = "0.1.0"
+description = "Grok Bot integration kit: delegate tasks to headless coding agents (opencode, Claude Code, Codex) and wake the right Grok Bot routine when they finish or need input."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.11"
+dependencies = []
+classifiers = [
+    "Environment :: Console",
+    "Operating System :: POSIX :: Linux",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+]
+
+[[project.authors]]
+name = "Rodrigo Pasini"
+
+[project.urls]
+Repository = "https://github.com/rodrigo-pasini/grokbot-kit"
+
+[project.scripts]
+grokbot-kit = "grokbot_kit.cli:main"
+
+[build-system]
+requires = ["uv_build>=0.9.26,<0.14.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "jsonschema>=4.26.0",
+    "mypy>=2.4.0",
+    "pre-commit>=4.7.0",
+    "pytest>=9.1.1",
+    "pyyaml>=6.0.3",
+    "ruff>=0.17.1",
+]
+
+[tool.ruff]
+target-version = "py311"
+line-length = 120
+extend-exclude = [
+    ".claude",
+    ".agents",
+]
+force-exclude = true
+
+[tool.mypy]
+strict = true
+files = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-m 'not integration'"
+markers = ["integration: roda só no box, com as CLIs reais ou o GitHub"]

grokbot_kit-0.1.0/pyproject.toml.orig

@@ -0,0 +1,53 @@
+[project]
+name = "grokbot-kit"
+version = "0.1.0"
+description = "Grok Bot integration kit: delegate tasks to headless coding agents (opencode, Claude Code, Codex) and wake the right Grok Bot routine when they finish or need input."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Rodrigo Pasini" }]
+requires-python = ">=3.11"
+dependencies = []
+classifiers = [
+    "Environment :: Console",
+    "Operating System :: POSIX :: Linux",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+]
+
+[project.urls]
+Repository = "https://github.com/rodrigo-pasini/grokbot-kit"
+
+[project.scripts]
+grokbot-kit = "grokbot_kit.cli:main"
+
+[build-system]
+requires = ["uv_build>=0.9.26,<0.14.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "jsonschema>=4.26.0",
+    "mypy>=2.4.0",
+    "pre-commit>=4.7.0",
+    "pytest>=9.1.1",
+    "pyyaml>=6.0.3",
+    "ruff>=0.17.1",
+]
+
+[tool.ruff]
+target-version = "py311"
+line-length = 120
+extend-exclude = [".claude", ".agents"]
+force-exclude = true
+
+[tool.mypy]
+strict = true
+files = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-m 'not integration'"
+markers = ["integration: roda só no box, com as CLIs reais ou o GitHub"]

grokbot_kit-0.1.0/src/grokbot_kit/__init__.py

@@ -0,0 +1,5 @@
+"""grokbot-kit: delega tarefas a agentes de código headless e acorda a routine do Grok Bot certo."""
+
+from importlib.metadata import version
+
+__version__ = version("grokbot-kit")

grokbot_kit-0.1.0/src/grokbot_kit/assets/event.v1.json

@@ -0,0 +1,311 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/rodrigo-pasini/grokbot-kit/blob/main/src/grokbot_kit/assets/event.v1.json",
+  "title": "grokbot-kit.event/v1",
+  "description": "Evento enviado pelo grokbot-kit aos sinks de um target (door 2). Os campos de task só são null em event: test.",
+  "type": "object",
+  "properties": {
+    "schema": {
+      "const": "grokbot-kit.event/v1"
+    },
+    "event": {
+      "enum": [
+        "completed",
+        "error",
+        "timeout",
+        "needs_input",
+        "test"
+      ]
+    },
+    "status": {
+      "enum": [
+        "ok",
+        "denied",
+        "failed",
+        "interrupted",
+        "timeout",
+        "permission",
+        "question",
+        "test"
+      ]
+    },
+    "task_id": {
+      "type": [
+        "string",
+        "null"
+      ]
+    },
+    "task_label": {
+      "type": [
+        "string",
+        "null"
+      ]
+    },
+    "target": {
+      "type": "string"
+    },
+    "tool": {
+      "enum": [
+        "opencode",
+        "claude",
+        "codex",
+        null
+      ]
+    },
+    "model": {
+      "type": [
+        "string",
+        "null"
+      ]
+    },
+    "model_source": {
+      "enum": [
+        "user",
+        "tier",
+        "default",
+        null
+      ]
+    },
+    "tier": {
+      "enum": [
+        "trivial",
+        "standard",
+        "complex",
+        null
+      ]
+    },
+    "session_id": {
+      "type": [
+        "string",
+        "null"
+      ]
+    },
+    "cwd": {
+      "type": "string"
+    },
+    "repo": {
+      "oneOf": [
+        {
+          "type": "null"
+        },
+        {
+          "type": "object",
+          "properties": {
+            "root": {
+              "type": "string"
+            },
+            "branch": {
+              "type": [
+                "string",
+                "null"
+              ]
+            },
+            "head": {
+              "type": "string"
+            }
+          },
+          "required": [
+            "root",
+            "branch",
+            "head"
+          ],
+          "additionalProperties": false
+        }
+      ]
+    },
+    "exit_code": {
+      "type": [
+        "integer",
+        "null"
+      ]
+    },
+    "exit_reason": {
+      "enum": [
+        "success",
+        "permission_denied",
+        "agent_error",
+        "nonzero_exit",
+        "timeout",
+        "interrupted",
+        "needs_input",
+        null
+      ]
+    },
+    "summary": {
+      "type": "string"
+    },
+    "needs_input": {
+      "oneOf": [
+        {
+          "type": "null"
+        },
+        {
+          "type": "object",
+          "properties": {
+            "kind": {
+              "type": "string"
+            },
+            "tool_name": {
+              "type": [
+                "string",
+                "null"
+              ]
+            },
+            "detail": {
+              "type": [
+                "string",
+                "null"
+              ]
+            }
+          },
+          "required": [
+            "kind",
+            "tool_name",
+            "detail"
+          ],
+          "additionalProperties": false
+        }
+      ]
+    },
+    "resume_hint": {
+      "type": [
+        "string",
+        "null"
+      ]
+    },
+    "output_file": {
+      "type": [
+        "string",
+        "null"
+      ]
+    },
+    "transcript_path": {
+      "type": [
+        "string",
+        "null"
+      ]
+    },
+    "log_file": {
+      "type": [
+        "string",
+        "null"
+      ]
+    },
+    "started_at": {
+      "type": [
+        "string",
+        "null"
+      ],
+      "format": "date-time"
+    },
+    "timestamp": {
+      "type": "string",
+      "format": "date-time"
+    }
+  },
+  "required": [
+    "schema",
+    "event",
+    "status",
+    "task_id",
+    "task_label",
+    "target",
+    "tool",
+    "model",
+    "model_source",
+    "tier",
+    "session_id",
+    "cwd",
+    "repo",
+    "exit_code",
+    "exit_reason",
+    "summary",
+    "needs_input",
+    "resume_hint",
+    "output_file",
+    "transcript_path",
+    "log_file",
+    "started_at",
+    "timestamp"
+  ],
+  "additionalProperties": false,
+  "if": {
+    "properties": {
+      "event": {
+        "const": "test"
+      }
+    }
+  },
+  "then": {
+    "properties": {
+      "task_id": {
+        "type": "null"
+      },
+      "task_label": {
+        "type": "null"
+      },
+      "tool": {
+        "type": "null"
+      },
+      "model": {
+        "type": "null"
+      },
+      "model_source": {
+        "type": "null"
+      },
+      "output_file": {
+        "type": "null"
+      },
+      "log_file": {
+        "type": "null"
+      },
+      "started_at": {
+        "type": "null"
+      }
+    }
+  },
+  "else": {
+    "properties": {
+      "task_id": {
+        "not": {
+          "type": "null"
+        }
+      },
+      "task_label": {
+        "not": {
+          "type": "null"
+        }
+      },
+      "tool": {
+        "not": {
+          "type": "null"
+        }
+      },
+      "model": {
+        "not": {
+          "type": "null"
+        }
+      },
+      "model_source": {
+        "not": {
+          "type": "null"
+        }
+      },
+      "output_file": {
+        "not": {
+          "type": "null"
+        }
+      },
+      "log_file": {
+        "not": {
+          "type": "null"
+        }
+      },
+      "started_at": {
+        "not": {
+          "type": "null"
+        }
+      }
+    }
+  }
+}

grokbot_kit-0.1.0/src/grokbot_kit/assets/opencode/grokbot-kit.ts

@@ -0,0 +1,7 @@
+// Plugin do opencode instalado por `grokbot-kit install opencode`.
+// Fora de uma task (sem GROKBOT_KIT_TASK_ID no ambiente) não faz nada e não chama o grokbot-kit.
+// O repasse de `permission.asked` e `question.asked` para `grokbot-kit emit --from opencode` chega no S3.
+export const GrokbotKit = async () => {
+  if (!process.env.GROKBOT_KIT_TASK_ID) return {}
+  return {}
+}

grokbot_kit-0.1.0/src/grokbot_kit/cli.py

@@ -0,0 +1,25 @@
+"""Ponto de entrada do executável `grokbot-kit`."""
+
+import argparse
+
+from grokbot_kit import __version__
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="grokbot-kit",
+        description="Delegate tasks to headless coding agents and wake the right Grok Bot routine.",
+    )
+    parser.add_argument("--version", action="version", version=f"grokbot-kit {__version__}")
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = build_parser()
+    parser.parse_args(argv)
+    parser.print_help()
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

grokbot_kit-0.1.0/src/grokbot_kit/emit.py

@@ -0,0 +1,18 @@
+"""`grokbot-kit emit`: chamado pelos hooks dos agentes dentro de uma task.
+
+Antes do gate de `GROKBOT_KIT_TASK_ID` só entram `os`, `sys` e `json` (door 6); o resto é
+carregado sob demanda. O registro e o envio de `needs_input` chegam no S3.
+"""
+
+import os
+import sys
+
+
+def main() -> int:
+    if not os.environ.get("GROKBOT_KIT_TASK_ID"):
+        return 0
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())