akiiwa-games/AgentCompass / skills/dot-subagent
dot-subagent
VerifiedLeaf-only runner for the local OpenAI Dot through dot2api. Use only after agent-compass has chosen Dot. Covers the runner, packets, code written and run on Dot's own computer, and how data reaches it (public re-fetch, text packets, the private GitHub repository) and how results come back. No routing and no spawning children.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 12.5 KB |
| agents/openai.yaml | config | 290 B |
| scripts/dot-subagent.cmd | script | 72 B |
| scripts/github_return.py | script | 8.0 KB |
| scripts/github_send.py | script | 18.1 KB |
| scripts/pack_chunks.py | script | 9.7 KB |
| scripts/parallel_fetch.py | script | 1.9 KB |
| scripts/remote_root.py | script | 1.7 KB |
| scripts/run_dot_task.py | script | 21.7 KB |
| scripts/test_executable_discovery.py | script | 2.7 KB |
| scripts/test_github_return.py | script | 6.2 KB |
| scripts/test_github_send.py | script | 11.8 KB |
| scripts/test_pack_chunks.py | script | 5.0 KB |
| scripts/test_parallel_fetch.py | script | 3.6 KB |
| scripts/test_remote_root.py | script | 1.6 KB |
| scripts/test_run_dot_task.py | script | 5.2 KB |
| scripts/test_unpack_files.py | script | 3.9 KB |
| scripts/unpack_files.py | script | 4.7 KB |
scripts/run_dot_task.py
View on GitHub"""Send one text task to the local Dot and print its reply. Never print credentials."""
from __future__ import annotations
import argparse
import hashlib
import json
import os
import sys
import time
import urllib.error
import urllib.request
from datetime import datetime
from pathlib import Path
sys.path.insert(0, str(Path(__file__).resolve().parent))
import unpack_files
EXIT_OK = 0
EXIT_FAILED = 1
EXIT_USAGE = 2
EXIT_PENDING = 3
TASK_INSTRUCTIONS = (
"This task is a chat completion request. payload.messages is the conversation, oldest "
"first; each entry has a role and text content. Write the next assistant reply, honoring "
"any system messages. Complete the task with the result "
'{"content": "<your reply>"}. Reply with the answer only, without mentioning this task.'
)
FILE_RETURN_CONTRACT = """
## File Return Format (Required for Modified or Created Files)
For every file you create or modify, emit the complete file in your reply using this exact block format (compute the exact UTF-8 sha256 in Python first):
=== FILE: <relative/path> sha256=<64 lowercase hex> ===
<full file content>
=== END FILE ===
"""
def client_path() -> Path:
return Path.home() / ".dot2api" / "client.json"
def load_config() -> dict:
env_url = os.environ.get("DOT2API_BASE_URL", "").strip()
env_key = os.environ.get("DOT2API_API_KEY", "").strip()
if env_url or env_key:
if not env_url or not env_key:
raise RuntimeError("Set both DOT2API_BASE_URL and DOT2API_API_KEY, or neither.")
file_config = {}
else:
path = client_path()
if not path.is_file():
raise RuntimeError(f"Missing {path}. Deploy dot2api before dispatching.")
file_config = json.loads(path.read_text(encoding="utf-8"))
env_url = str(file_config.get("base_url", "")).rstrip("/")
env_key = str(file_config.get("api_key", ""))
if not env_url or not env_key:
raise RuntimeError("Dot client config needs base_url and api_key.")
return {
"base_url": env_url.rstrip("/"),
"api_key": env_key,
"queue": str(file_config.get("queue", "dot")),
"completion_timeout": int(file_config.get("completion_timeout", 900)),
"task_ttl": int(file_config.get("task_ttl", 7200)),
}
def request(config: dict, method: str, path: str, body: dict | None, timeout: float):
data = None if body is None else json.dumps(body).encode()
req = urllib.request.Request(
config["base_url"] + path,
data=data,
method=method,
headers={
"Authorization": f"Bearer {config['api_key']}",
"Content-Type": "application/json",
"Accept": "application/json",
},
)
try:
with urllib.request.urlopen(req, timeout=timeout) as response:
return response.status, response.read()
except urllib.error.HTTPError as exc:
return exc.code, exc.read()
def reply_text(result) -> str:
if isinstance(result, dict):
for key in ("content", "text", "output"):
if isinstance(result.get(key), str):
return result[key]
if isinstance(result, str):
return result
return json.dumps(result, ensure_ascii=False)
def parse_sse(payload: bytes) -> tuple[str, str | None, str | None]:
"""Return reply text, task id, and a terminal error message."""
text: list[str] = []
task_id = None
error = None
for raw in payload.decode("utf-8", "replace").splitlines():
line = raw.strip()
if not line.startswith("data:"):
continue
data = line[5:].strip()
if not data or data == "[DONE]":
continue
try:
event = json.loads(data)
except json.JSONDecodeError:
continue
if not isinstance(event, dict):
continue
if isinstance(event.get("id"), str):
task_id = event["id"]
err = event.get("error")
if isinstance(err, dict) and "choices" not in event:
error = str(err.get("message") or "Dot request failed")
if isinstance(err.get("task_id"), str):
task_id = err["task_id"]
continue
choices = event.get("choices")
if isinstance(choices, list) and choices:
delta = choices[0].get("delta") if isinstance(choices[0], dict) else None
if isinstance(delta, dict) and isinstance(delta.get("content"), str):
text.append(delta["content"])
return "".join(text), task_id, error
def task_view(config: dict, task_id: str) -> dict:
status, raw = request(config, "GET", f"/v1/tasks/{task_id}", None, 30)
if status != 200:
raise RuntimeError(f"Reading task failed with HTTP {status}")
body = json.loads(raw.decode())
task = body.get("task")
if not isinstance(task, dict):
raise RuntimeError("Task response has no task")
return task
def seconds(value) -> float | None:
"""Epoch seconds from a number or an ISO-8601 string; None when it is neither."""
if isinstance(value, (int, float)):
return float(value)
if isinstance(value, str):
try:
return datetime.fromisoformat(value.replace("Z", "+00:00")).timestamp()
except ValueError:
return None
return None
def describe(task: dict, now: float | None = None) -> str:
"""One line: status, attempts and ages. A running task has no heartbeat, so its age is the only hint."""
now = time.time() if now is None else now
parts = [f"status={task.get('status')}", f"attempts={task.get('attempts')}/{task.get('max_attempts')}"]
for label, key in (("age", "created_at"), ("idle", "updated_at")):
moment = seconds(task.get(key))
if moment is not None:
parts.append(f"{label}={int(now - moment)}s")
return " ".join(parts)
def pack_context_files(files: list[str] | None, base_dir: str | Path | None = None) -> str:
"""Format local files as === FILE: <rel_path> sha256=<hex> === blocks for the prompt."""
if not files:
return ""
root = Path(base_dir).resolve() if base_dir else Path.cwd().resolve()
sections = ["\n\n## Input Files\n"]
for item in files:
path = Path(item)
full = path.resolve() if path.is_absolute() else (root / path).resolve()
if not full.is_file():
raise FileNotFoundError(f"Input file not found: {item}")
try:
rel = full.relative_to(root).as_posix()
except ValueError:
rel = full.name
content = full.read_text(encoding="utf-8").replace("\r\n", "\n")
if not content.endswith("\n"):
content += "\n"
digest = hashlib.sha256(content.encode("utf-8")).hexdigest()
sections.append(f"=== FILE: {rel} sha256={digest} ===\n{content}=== END FILE ===\n")
return "\n".join(sections)
def augment_prompt_with_files(
prompt: str,
files: list[str] | None = None,
base_dir: str | Path | None = None,
expect_files: bool = False,
) -> str:
out = prompt
packed = pack_context_files(files, base_dir=base_dir)
if packed:
out = out.rstrip() + packed
if expect_files and "=== FILE:" not in prompt:
out = out.rstrip() + "\n" + FILE_RETURN_CONTRACT
return out
def handle_completed_reply(
message: str,
output: str | Path | None = None,
unpack_to: str | Path | None = None,
apply_to: str | Path | None = None,
) -> int:
if output:
out_path = Path(output)
out_path.parent.mkdir(parents=True, exist_ok=True)
out_path.write_text(message, encoding="utf-8")
if unpack_to:
results = unpack_files.unpack(message, unpack_to, keep_unverified=False, allow_existing=False)
for name, st in results:
print(f"unpacked {name}: {st}", file=sys.stderr)
if not results or not all(st == "ok" for _, st in results):
print("ERROR: failed to unpack all verified file blocks", file=sys.stderr)
return EXIT_FAILED
if apply_to:
results = unpack_files.unpack(message, apply_to, keep_unverified=True, allow_existing=True)
for name, st in results:
print(f"applied {name}: {st}", file=sys.stderr)
if not results:
print("ERROR: reply contained no === FILE: ... === blocks to apply", file=sys.stderr)
return EXIT_FAILED
return EXIT_OK
def submit_task_api(
config: dict,
messages: list[dict],
idempotency_key: str | None = None,
) -> tuple[int, str | None, bytes]:
"""Create a task directly via POST /v1/tasks so client timeout/disconnect never cancels the task."""
body: dict = {
"queue": config.get("queue", "dot"),
"instructions": TASK_INSTRUCTIONS,
"payload": {"model": "dot", "messages": messages},
"ttl_seconds": int(config.get("task_ttl", 7200)),
}
# dot2api requires idempotency_key on POST /v1/tasks (models.Submit); a fresh one per submission.
body["idempotency_key"] = idempotency_key or f"task-{os.urandom(12).hex()}"
status, raw = request(config, "POST", "/v1/tasks", body, 30)
if status in (200, 201):
try:
parsed = json.loads(raw.decode() or "{}")
except json.JSONDecodeError:
parsed = {}
task = parsed.get("task") if isinstance(parsed, dict) else None
if isinstance(task, dict) and isinstance(task.get("id"), str):
return status, task["id"], raw
return status, None, raw
def wait_task(config: dict, task_id: str, deadline: float) -> tuple[int, str]:
while True:
task = task_view(config, task_id)
status = task.get("status")
if status == "completed":
return EXIT_OK, reply_text(task.get("result"))
if status not in ("queued", "running"):
print(f"task_id={task_id}", file=sys.stderr)
print(f"FAILED {describe(task)}", file=sys.stderr)
return EXIT_FAILED, str(task.get("error") or f"Dot task {status}")
if time.monotonic() >= deadline:
print(f"task_id={task_id}", file=sys.stderr)
print(f"OPEN {describe(task)}", file=sys.stderr)
return EXIT_PENDING, "Dot has not finished; read this task id later (run --task-id, or status --task-id)."
time.sleep(2)
def doctor(config: dict) -> int:
try:
with urllib.request.urlopen(config["base_url"] + "/readyz", timeout=5) as response:
ready = response.status == 200
except (OSError, urllib.error.URLError):
print("status: failed")
print(f"base_url: {config['base_url']}")
print("ready: false")
return EXIT_FAILED
status, raw = request(config, "GET", "/v1/models", None, 15)
model = ""
if status == 200:
body = json.loads(raw.decode())
data = body.get("data")
if isinstance(data, list) and data and isinstance(data[0], dict):
model = str(data[0].get("id", ""))
print("status: ok" if ready and status == 200 else "status: failed")
print(f"base_url: {config['base_url']}")
print(f"ready: {str(ready).lower()}")
print(f"auth: {'accepted' if status == 200 else 'rejected'}")
if model:
print(f"model: {model}")
return EXIT_OK if ready and status == 200 else EXIT_FAILED
def _record_completed_dispatch(task_id: str | None) -> None:
if not task_id:
return
try:
db = Path(os.environ.get("ROUTER_DISPATCH_DB") or Path.home() / ".agent-compass/dispatch.sqlite3")
if not db.exists():
return
compass_scripts = str(Path(__file__).resolve().parents[2] / "agent-compass" / "scripts")
if compass_scripts not in sys.path:
sys.path.insert(0, compass_scripts)
import dispatch_registry
dispatch_registry.complete_external("dot", task_id, path=db)
except Exception:
pass
def status_command(
config: dict,
task_id: str,
wait: float = 0.0,
output: str | Path | None = None,
unpack_to: str | Path | None = None,
apply_to: str | Path | None = None,
) -> int:
"""Read a task (or wait up to `wait` seconds if > 0): exit 0 completed, 3 still open, 1 failed."""
if wait and wait > 0:
code, message = wait_task(config, task_id, time.monotonic() + wait)
if code == EXIT_OK:
print(message)
rc = handle_completed_reply(message, output=output, unpack_to=unpack_to, apply_to=apply_to)
if rc == EXIT_OK:
_record_completed_dispatch(task_id)
return rc
print(message, file=sys.stderr)
return code
task = task_view(config, task_id)
print(f"task_id={task_id}")
print(describe(task))
state = task.get("status")
if state == "completed":
if output or unpack_to or apply_to:
message = reply_text(task.get("result"))
rc = handle_completed_reply(message, output=output, unpack_to=unpack_to, apply_to=apply_to)
if rc == EXIT_OK:
_record_completed_dispatch(task_id)
return rc
_record_completed_dispatch(task_id)
return EXIT_OK
if state in ("queued", "running"):
print("No heartbeat: running does not prove progress. Dot's reply is the only proof.")
return EXIT_PENDING
print(str(task.get("error") or f"Dot task {state}"))
return EXIT_FAILED
def run_task(
config: dict,
prompt: str,
system: str | None,
task_id: str | None,
wait: float,
no_wait: bool = False,
idempotency_key: str | None = None,
output: str | Path | None = None,
unpack_to: str | Path | None = None,
apply_to: str | Path | None = None,
) -> int:
deadline = time.monotonic() + wait
if task_id:
code, message = wait_task(config, task_id, deadline)
if code == EXIT_OK:
print(message)
rc = handle_completed_reply(message, output=output, unpack_to=unpack_to, apply_to=apply_to)
if rc == EXIT_OK:
_record_completed_dispatch(task_id)
return rc
print(message, file=sys.stderr)
return code
messages = []
if system:
messages.append({"role": "system", "content": system})
messages.append({"role": "user", "content": prompt})
status, created_id, raw = submit_task_api(config, messages, idempotency_key=idempotency_key)
if created_id:
print(f"task_id={created_id}", file=sys.stderr)
if no_wait or wait <= 0:
print(created_id)
return EXIT_OK
code, message = wait_task(config, created_id, deadline)
if code == EXIT_OK:
print(message)
rc = handle_completed_reply(message, output=output, unpack_to=unpack_to, apply_to=apply_to)
if rc == EXIT_OK:
_record_completed_dispatch(created_id)
return rc
print(message, file=sys.stderr)
return code
if status in (404, 405):
status, raw = request(
config,
"POST",
"/v1/chat/completions",
{"model": "dot", "stream": True, "messages": messages},
max(10.0, min(wait + 15.0, float(config["completion_timeout"] + 60))),
)
if status == 200:
reply, found_id, error = parse_sse(raw)
if error:
if found_id and "not answered" in error.lower():
print(f"task_id={found_id}", file=sys.stderr)
code, message = wait_task(config, found_id, deadline)
if code == EXIT_OK:
print(message)
rc = handle_completed_reply(message, output=output, unpack_to=unpack_to, apply_to=apply_to)
if rc == EXIT_OK:
_record_completed_dispatch(found_id)
return rc
print(message, file=sys.stderr)
return code
print(error, file=sys.stderr)
return EXIT_FAILED
print(reply)
rc = handle_completed_reply(reply, output=output, unpack_to=unpack_to, apply_to=apply_to)
if rc == EXIT_OK:
_record_completed_dispatch(found_id)
return rc
try:
body = json.loads(raw.decode() or "{}")
except json.JSONDecodeError:
body = {}
err = body.get("error") if isinstance(body, dict) else None
message = err.get("message") if isinstance(err, dict) else f"HTTP {status}"
found = err.get("task_id") if isinstance(err, dict) else None
if status == 504 and isinstance(found, str):
print(f"task_id={found}", file=sys.stderr)
code, pending = wait_task(config, found, deadline)
if code == EXIT_OK:
print(pending)
rc = handle_completed_reply(pending, output=output, unpack_to=unpack_to, apply_to=apply_to)
if rc == EXIT_OK:
_record_completed_dispatch(found)
return rc
print(pending, file=sys.stderr)
return code
print(str(message), file=sys.stderr)
return EXIT_FAILED
def add_task_io_args(subparser: argparse.ArgumentParser, include_prompt: bool = True) -> None:
if include_prompt:
subparser.add_argument("--prompt", default="")
subparser.add_argument("--prompt-file")
subparser.add_argument("--system")
subparser.add_argument("--file", dest="files", action="append", default=[],
help="Pack a local file into the prompt (repeatable).")
subparser.add_argument("--base-dir", help="Base directory for relative --file paths (default: cwd).")
subparser.add_argument("--expect-files", action="store_true",
help="Append the === FILE: ... === return format contract to the prompt.")
subparser.add_argument("--idempotency-key", help="Optional idempotency key for POST /v1/tasks.")
subparser.add_argument("--output", help="Write the completed assistant reply to this file path.")
subparser.add_argument("--unpack-to", help="Unpack verified === FILE: ... === blocks into this empty directory.")
subparser.add_argument("--apply-to", help="Unpack === FILE: ... === blocks directly into this existing workspace directory.")
def main() -> int:
parser = argparse.ArgumentParser(description=__doc__)
commands = parser.add_subparsers(dest="command", required=True)
commands.add_parser("doctor")
status = commands.add_parser("status")
status.add_argument("--task-id", required=True)
status.add_argument("--wait", type=float, default=0.0,
help="Optional seconds to wait for completion before returning.")
add_task_io_args(status, include_prompt=False)
submit = commands.add_parser("submit", help="Submit a task via POST /v1/tasks, print task_id immediately, and exit 0.")
add_task_io_args(submit, include_prompt=True)
run = commands.add_parser("run")
add_task_io_args(run, include_prompt=True)
run.add_argument("--task-id")
run.add_argument("--wait", type=float)
run.add_argument("--no-wait", action="store_true",
help="Submit the task and return immediately after printing task_id.")
args = parser.parse_args()
try:
config = load_config()
except (OSError, json.JSONDecodeError, RuntimeError, ValueError) as exc:
print(f"Status: blocked\n{exc}", file=sys.stderr)
return EXIT_USAGE
if args.command == "doctor":
return doctor(config)
if args.command == "status":
try:
return status_command(
config,
args.task_id,
wait=args.wait,
output=args.output,
unpack_to=args.unpack_to,
apply_to=args.apply_to,
)
except (OSError, RuntimeError, ValueError) as exc:
print(f"FAILED reading the task: {exc}", file=sys.stderr)
return EXIT_FAILED
task_id = getattr(args, "task_id", None)
prompt = args.prompt
if args.prompt_file:
prompt = Path(args.prompt_file).read_text(encoding="utf-8")
elif not prompt and not task_id and not sys.stdin.isatty():
prompt = sys.stdin.read()
if not task_id and not prompt.strip():
print("A prompt or --task-id is required.", file=sys.stderr)
return EXIT_USAGE
if not task_id:
try:
expect_files = bool(args.expect_files or args.unpack_to or args.apply_to)
prompt = augment_prompt_with_files(
prompt,
files=args.files,
base_dir=args.base_dir or args.apply_to,
expect_files=expect_files,
)
except (OSError, ValueError) as exc:
print(f"Status: blocked\n{exc}", file=sys.stderr)
return EXIT_USAGE
if args.command == "submit":
return run_task(
config,
prompt,
args.system,
None,
0.0,
no_wait=True,
idempotency_key=args.idempotency_key,
)
wait = args.wait if args.wait is not None else float(config["task_ttl"])
return run_task(
config,
prompt,
args.system,
task_id,
wait,
no_wait=args.no_wait,
idempotency_key=args.idempotency_key,
output=args.output,
unpack_to=args.unpack_to,
apply_to=args.apply_to,
)
if __name__ == "__main__":
raise SystemExit(main())
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 471k | Updated | Claude CodeCodex | Verified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |