The open-source app everyone uses to manage agents at work
TypeScript acpxagent-orchestrationagent-skillsagentic-aiai-agentsai-engineeringai-governanceai-toolsautonomous-agentsclaudeclaude-codeclaude-skillscodexhermesllmmcpmulti-agentopenclawproject-managementworkflow-automation
#!/usr/bin/env python3
"""Private personal Muse transport; durable command identities precede network I/O."""
import argparse
import datetime
import fcntl
import hashlib
import json
import os
from pathlib import Path
import sys
import urllib.error
import urllib.request
import uuid
from urllib.parse import urlparse
VERSION = "1"
ROOT = Path.home() / ".config" / "paperclip-muse"
MAX_BYTES = 2_000_000
class NoRedirect(urllib.request.HTTPRedirectHandler):
def redirect_request(self, req, fp, code, msg, headers, newurl): return None
HTTP = urllib.request.build_opener(NoRedirect)
def canonical(value): return json.dumps(value, sort_keys=True, separators=(",", ":"), ensure_ascii=False).encode()
def save(path, value):
path.parent.mkdir(parents=True, exist_ok=True, mode=0o700)
os.chmod(path.parent, 0o700)
temporary = path.with_name(path.name + ".tmp")
descriptor = os.open(temporary, os.O_WRONLY | os.O_CREAT | os.O_TRUNC, 0o600)
with os.fdopen(descriptor, "w") as stream:
json.dump(value, stream, ensure_ascii=False); stream.flush(); os.fsync(stream.fileno())
os.chmod(temporary, 0o600); os.replace(temporary, path)
descriptor = os.open(path.parent, os.O_RDONLY)
try: os.fsync(descriptor)
finally: os.close(descriptor)
def origin(value):
parsed = urlparse(value)
if parsed.scheme != "https" or not parsed.hostname or parsed.username or parsed.password or parsed.query or parsed.fragment or parsed.path not in ("", "/"):
raise RuntimeError("A public HTTPS Paperclip origin is required")
return value.rstrip("/")
def http(url, body=None, token=None):
parsed = urlparse(url)
if parsed.scheme != "https" or not parsed.hostname or parsed.username or parsed.password or parsed.query or parsed.fragment:
raise RuntimeError("Invalid Paperclip endpoint")
headers = {"Accept": "application/json"}
if token: headers["Authorization"] = "Bearer " + token
if body is not None: headers["Content-Type"] = "application/json"
encoded = None if body is None else canonical(body)
if encoded is not None and len(encoded) > 262144: raise RuntimeError("Command exceeds transport limit")
request = urllib.request.Request(url, encoded, headers)
try:
with HTTP.open(request, timeout=30) as response:
if response.status != 200 or response.headers.get_content_type() != "application/json": raise RuntimeError("Incomplete Paperclip protocol response")
data = response.read(MAX_BYTES + 1)
if len(data) > MAX_BYTES: raise RuntimeError("Paperclip response exceeds transport limit")
value = json.loads(data)
if not isinstance(value, dict): raise RuntimeError("Invalid Paperclip protocol response")
return value
except urllib.error.HTTPError as error:
raise RuntimeError("Paperclip HTTP %d; inspect connection or receipt before retrying" % error.code) from None
class Client:
def __init__(self, binding):
uuid.UUID(binding)
self.binding = binding; self.directory = ROOT / binding
self.directory.mkdir(parents=True, exist_ok=True, mode=0o700); os.chmod(self.directory, 0o700)
self.lock = open(self.directory / "client.lock", "a"); os.chmod(self.directory / "client.lock", 0o600)
fcntl.flock(self.lock, fcntl.LOCK_EX)
self.path = self.directory / "worker.json"
self.config = json.loads(self.path.read_text()) if self.path.exists() else None
self.rotation = self.directory / "credential-commit.json"
self.suspension = self.directory / "signal-suspended.json"
if self.rotation.exists():
staged = json.loads(self.rotation.read_text())
self._publish_credentials(staged)
self.rotation.unlink()
self.suspension.unlink(missing_ok=True)
descriptor = os.open(self.directory, os.O_RDONLY)
try: os.fsync(descriptor)
finally: os.close(descriptor)
def close(self): self.lock.close()
def store_credentials(self, value, base):
required = {"version", "bindingId", "generation", "companyId", "agentId", "accessToken", "accessExpiresAt", "refreshToken", "refreshExpiresAt", "signalToken", "cleanupToken", "detectorCleanupToken"}
if set(value) != required or value["version"] != 1 or value["bindingId"] != self.binding: raise RuntimeError("Unexpected pairing identity")
staged = {**value, "origin": origin(base)}
save(self.rotation, staged)
self._publish_credentials(staged)
self.rotation.unlink()
self.suspension.unlink(missing_ok=True)
descriptor = os.open(self.directory, os.O_RDONLY)
try: os.fsync(descriptor)
finally: os.close(descriptor)
def _publish_credentials(self, staged):
self.config = staged
save(self.path, staged)
# Detector reads this file alone. A durable commit intent repairs an
# interrupted worker/signal publication under this same OS lock.
save(self.directory / "signal.json", {"origin": staged["origin"], "bindingId": self.binding, "generation": staged["generation"], "signalToken": staged["signalToken"], "detectorCleanupToken": staged["detectorCleanupToken"]})
def access(self):
if not self.config or self.config.get("reconnectRequired") or self.config.get("refreshPending"): raise RuntimeError("Reconnect Muse; credential rotation outcome is uncertain")
expiry = datetime.datetime.fromisoformat(self.config["accessExpiresAt"].replace("Z", "+00:00")).timestamp()
if expiry < datetime.datetime.now().timestamp() + 60:
save(self.suspension, {"bindingId": self.binding, "generation": self.config["generation"], "suspended": True})
self.config["refreshPending"] = True; save(self.path, self.config)
try:
value = http(self.config["origin"] + "/api/muse/v1/refresh", {"version": 1, "refreshToken": self.config["refreshToken"]})
self.store_credentials(value, self.config["origin"])
except Exception:
self.config["reconnectRequired"] = True; save(self.path, self.config)
raise RuntimeError("Refresh outcome uncertain; reconnect without replaying refresh") from None
return self.config["accessToken"]
def query(self, value):
return http(self.config["origin"] + "/api/muse/v1/queries", {"version": 1, **value}, self.access())
def journal_path(self, key):
return self.directory / "journal" / (hashlib.sha256(key.encode()).hexdigest() + ".json")
def receipt(self, key):
path = self.journal_path(key)
if not path.exists(): raise RuntimeError("No prepared command for that key")
journal = json.loads(path.read_text())
command = journal["command"]
if "assignmentId" not in command:
return {"requestId": command["requestId"], "command": command["command"], "state": journal["state"], "receipt": journal.get("receipt"), "instruction": "Retry only the same command key and unchanged input to inspect its durable idle receipt"}
result = self.query({"query": "operation.receipt", "assignmentId": command["assignmentId"], "requestId": command["requestId"]})
journal["receipt"] = result; journal["state"] = "received"; save(path, journal)
return {"assignmentId": command["assignmentId"], "requestId": command["requestId"], "receipt": result}
def mailbox(self, acknowledge=None):
path = self.directory / "mailbox.json"
state = json.loads(path.read_text()) if path.exists() else {"bindingId": self.binding, "generation": self.config["generation"], "ackedThrough": 0}
if state["bindingId"] != self.binding or state["generation"] != self.config["generation"]: raise RuntimeError("Mailbox generation changed; reconnect instructions are required")
if acknowledge is not None:
if acknowledge != state.get("batch", {}).get("nextCursor") or acknowledge < state["ackedThrough"]: raise RuntimeError("Acknowledge only the exact durably saved batch cursor")
state["ackedThrough"] = acknowledge; state.pop("batch", None); save(path, state)
return {"status": "acknowledged", "nextCursor": acknowledge}
result = self.query({"query": "mailbox", "after": state["ackedThrough"]})
if result.get("bindingId") != self.binding or result.get("generation") != self.config["generation"] or not isinstance(result.get("items"), list) or not isinstance(result.get("nextCursor"), int) or result["nextCursor"] < state["ackedThrough"]: raise RuntimeError("Mailbox response identity or cursor changed")
state["batch"] = result; save(path, state)
return result
def status(self):
identity = self.query({"query": "identify"})
identity["localPendingCommands"] = sum(1 for path in (self.directory / "journal").glob("*.json") if json.loads(path.read_text()).get("receipt", {}).get("status", "pending") in ("pending", "reserved", "dispatched", "unknown"))
identity["instructionsPath"] = str(ROOT / "instructions.md")
return identity
def command(self, key, value):
path = self.journal_path(key)
value = {"version": 1, **value}
proposed = {k: v for k, v in value.items() if k != "requestId"}
digest = hashlib.sha256(canonical(proposed)).hexdigest()
if path.exists():
journal = json.loads(path.read_text())
if journal["digest"] != digest: raise RuntimeError("Stable command key reused with different input")
else:
journal = {"digest": digest, "command": {**value, "requestId": value.get("requestId", str(uuid.uuid4()))}, "state": "prepared"}
save(path, journal)
if journal.get("receipt", {}).get("status") in ("unknown", "rejected"):
raise RuntimeError("Operation is unresolved or rejected; inspect its original receipt without replay")
if journal.get("receipt", {}).get("status") not in ("pending", "reserved", "dispatched") and "receipt" in journal: return journal["receipt"]
# Persist dispatch intent before issuing the stable command. A lost ACK
# is inspected using exactly this requestId, never a replacement effect.
journal["state"] = "sending"; save(path, journal)
result = http(self.config["origin"] + "/api/muse/v1/commands", journal["command"], self.access())
journal["receipt"] = result; journal["state"] = "received"; save(path, journal)
return result
def detector_cleanup(self, removed):
# Invoke only after an explicit runtime removal request/confirmation.
generation = self.config["generation"]
if type(generation) is not int or generation < 1: raise RuntimeError("Invalid cleanup generation")
kind = "detector-cleanup:" + ("removed" if removed else "requested")
path = self.directory / "control" / (kind + ":g" + str(generation) + ".json")
legacy = self.directory / "control" / (kind + ".json")
if path.exists(): journal = json.loads(path.read_text())
else:
old = json.loads(legacy.read_text()) if legacy.exists() else None
# Preserve a prepared older-client identity only for this exact
# generation. A reconnect never adopts another generation's facts.
if old and old.get("request", {}).get("bindingId") == self.binding and old["request"].get("generation") == generation:
journal = old
else:
body = {"version": 1, "requestId": str(uuid.uuid4()), "bindingId": self.binding, "generation": generation, "detectorRemoved" if removed else "detectorRemovalRequested": True}
journal = {"request": body}
save(path, journal)
if journal["request"]["bindingId"] != self.binding or journal["request"]["generation"] != self.config["generation"]: raise RuntimeError("Cleanup identity changed")
if "receipt" not in journal:
journal["receipt"] = http(self.config["origin"] + "/api/muse/v1/detector-cleanup", journal["request"], self.config["detectorCleanupToken"])
save(path, journal)
return journal["receipt"]
def answer(self, assignment, request):
value = self.query({"query": "input.pending", "assignmentId": assignment, "nativeRequestId": request})
if value.get("status") == "pending": return value
if value.get("assignmentId") != assignment or value.get("bindingId") != self.binding or value.get("generation") != self.config["generation"] or value.get("requestId") != request or not isinstance(value.get("turnId"), str) or not value["turnId"]: raise RuntimeError("Input response does not belong to this exact assignment and turn")
path = self.directory / "continuations" / (assignment + ".json")
old = json.loads(path.read_text()) if path.exists() else {"assignmentId": assignment, "inputs": {}}
previous = old["inputs"].get(request)
if previous and (previous["inputDigest"] != value["inputDigest"] or previous["turnId"] != value["turnId"]): raise RuntimeError("Input changed within a turn")
old["inputs"][request] = {**value, "continuationReceiptId": previous["continuationReceiptId"] if previous else str(uuid.uuid4())}
save(path, old)
return old["inputs"][request]
def consume(self, assignment, request):
continuation = json.loads((self.directory / "continuations" / (assignment + ".json")).read_text())
value = continuation["inputs"][request]
if continuation["assignmentId"] != assignment or value.get("assignmentId") != assignment or value.get("bindingId") != self.binding or value.get("generation") != self.config["generation"] or value.get("requestId") != request: raise RuntimeError("Continuation identity changed")
current = self.query({"query": "input.pending", "assignmentId": assignment, "nativeRequestId": request})
if any(current.get(field) != value.get(field) for field in ("assignmentId", "bindingId", "generation", "requestId", "turnId", "inputDigest")): raise RuntimeError("Pending input changed before consumption")
return self.command("consume:" + assignment + ":" + request, {"command": "consume_input", "assignmentId": assignment, "nativeRequestId": request, "inputDigest": value["inputDigest"], "continuationReceiptId": value["continuationReceiptId"], "continuationPersisted": True})
def main():
parser = argparse.ArgumentParser()
parser.add_argument("--binding", required=True)
sub = parser.add_subparsers(dest="mode", required=True)
pair = sub.add_parser("pair"); pair.add_argument("--origin", required=True); pair.add_argument("--ticket", required=True)
sub.add_parser("query", help="Read JSON from stdin; see installed instructions.md for exact envelopes")
sub.add_parser("status", help="Inspect bound identity and local pending command count")
sub.add_parser("help", help="Read persistent Paperclip instructions")
receipt = sub.add_parser("receipt", help="Inspect the original durable command without resending it"); receipt.add_argument("--key", required=True)
mailbox = sub.add_parser("mailbox", help="Durably save mailbox references; explicitly acknowledge only after incorporating them"); mailbox.add_argument("--ack", type=int)
command = sub.add_parser("command"); command.add_argument("--key", required=True)
for name in ("answer", "consume-input"):
child = sub.add_parser(name); child.add_argument("assignment"); child.add_argument("request")
cleanup = sub.add_parser("cleanup"); cleanup_mode = cleanup.add_mutually_exclusive_group()
cleanup_mode.add_argument("--inspect", action="store_true")
cleanup_mode.add_argument("--detector-removed", action="store_true", help="Report only an independently runtime-confirmed exact hook removal")
cleanup_mode.add_argument("--detector-removal-requested", action="store_true", help="Report a runtime removal request; this never confirms removal")
client = Client(parser.parse_args().binding)
try:
args = parser.parse_args()
if args.mode == "pair":
base = origin(args.origin)
client.store_credentials(http(base + "/api/muse/v1/pair", {"version": 1, "ticket": args.ticket, "clientVersion": VERSION}), base)
result = {"paired": True, "bindingId": client.binding, "version": VERSION}
elif args.mode == "help":
print((ROOT / "instructions.md").read_text()); return
elif args.mode == "status": result = client.status()
elif args.mode == "receipt": result = client.receipt(args.key)
elif args.mode == "mailbox": result = client.mailbox(args.ack)
elif args.mode == "query":
value = json.load(sys.stdin)
result = client.mailbox() if value.get("query") == "mailbox" else client.query(value)
elif args.mode == "command": result = client.command(args.key, json.load(sys.stdin))
elif args.mode == "answer": result = client.answer(args.assignment, args.request)
elif args.mode == "consume-input": result = client.consume(args.assignment, args.request)
elif args.mode == "cleanup" and (args.detector_removed or args.detector_removal_requested):
result = client.detector_cleanup(args.detector_removed)
elif args.mode == "cleanup":
body = {"version": 1, "command": "control.inspect"} if args.inspect else {"version": 1, **json.load(sys.stdin)}
result = http(client.config["origin"] + "/api/muse/v1/cleanup", body, client.config["cleanupToken"])
client.suspension.unlink(missing_ok=True)
print(json.dumps(result, ensure_ascii=False))
finally: client.close()
if __name__ == "__main__":
try: main()
except Exception as error:
# Never echo exception payloads, request bodies, credentials or URLs.
print("Paperclip client stopped: " + (str(error) if isinstance(error, RuntimeError) else "private state or transport failure"), file=sys.stderr)
sys.exit(1)