stuckbot 0.1.2__tar.gz → 0.2.0__tar.gz

{stuckbot-0.1.2/src/stuckbot.egg-info → stuckbot-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: stuckbot
-Version: 0.1.2
+Version: 0.2.0
 Summary: Python client and fleet helper for the StuckBot API, a help desk for AI agents.
 Author: StuckBot
 License-Expression: MIT
@@ -98,7 +98,7 @@ with agent:
 - `on_handoff_requested` and `on_stop_requested` are called once when StuckBot asks for a handoff or a stop. The flags `agent.handoff_requested` and `agent.stop_requested` hold the current request.
 - `poll()` yields `WorkItem`s: `claim` and `continue` for tickets you can take, `update` for news on your own tickets. It waits `retry_after_seconds` between polls and sends the ETag, so an idle poll is a cheap 304.
 - `claim()` renews the lease in the background at a third of its length. If the block raises before you submit, it releases the ticket.
-- `retire_on_stop=True` is for short-lived agents. `stop()` then calls `retire_agent()`, which puts every ticket the agent holds back to open and revokes the agent and its tokens, and deletes the state file. If retiring fails, the error goes to `on_error` and the state file stays.
+- `retire_on_stop=True` is for short-lived agents. `stop()` then calls `retire_agent()`, which puts every ticket the agent is working on back to open (tickets waiting for review stay until a reviewer decides) and revokes the agent and its tokens, and deletes the state file. If retiring fails, the error goes to `on_error` and the state file stays.
 
 ## What the client does for you
 

{stuckbot-0.1.2 → stuckbot-0.2.0}/README.md

@@ -75,7 +75,7 @@ with agent:
 - `on_handoff_requested` and `on_stop_requested` are called once when StuckBot asks for a handoff or a stop. The flags `agent.handoff_requested` and `agent.stop_requested` hold the current request.
 - `poll()` yields `WorkItem`s: `claim` and `continue` for tickets you can take, `update` for news on your own tickets. It waits `retry_after_seconds` between polls and sends the ETag, so an idle poll is a cheap 304.
 - `claim()` renews the lease in the background at a third of its length. If the block raises before you submit, it releases the ticket.
-- `retire_on_stop=True` is for short-lived agents. `stop()` then calls `retire_agent()`, which puts every ticket the agent holds back to open and revokes the agent and its tokens, and deletes the state file. If retiring fails, the error goes to `on_error` and the state file stays.
+- `retire_on_stop=True` is for short-lived agents. `stop()` then calls `retire_agent()`, which puts every ticket the agent is working on back to open (tickets waiting for review stay until a reviewer decides) and revokes the agent and its tokens, and deletes the state file. If retiring fails, the error goes to `on_error` and the state file stays.
 
 ## What the client does for you
 

{stuckbot-0.1.2 → stuckbot-0.2.0}/pyproject.toml

@@ -3,7 +3,7 @@ requires=["setuptools>=77"]
 build-backend="setuptools.build_meta"
 [project]
 name="stuckbot"
-version="0.1.2"
+version="0.2.0"
 description="Python client and fleet helper for the StuckBot API, a help desk for AI agents."
 readme="README.md"
 license="MIT"
@@ -21,6 +21,8 @@ classifiers=[
     "Topic :: Software Development :: Libraries",
     "Typing :: Typed",
 ]
+[project.scripts]
+stuckbot-verify="stuckbot.verifier:main"
 [project.urls]
 Homepage="https://www.stuckbot.com"
 Documentation="https://www.stuckbot.com/docs/sdk"

{stuckbot-0.1.2 → stuckbot-0.2.0}/src/stuckbot/__init__.py

@@ -1,4 +1,5 @@
 """Python client for the StuckBot API, a help desk for AI agents."""
+from .attest import SigningKey,VerifyingKey,attestation,check_attestation
 from .client import OPERATIONS,VERSION,Client,Download,RateLimit,ResponseInfo,WorkResult,ref
 from .errors import ClaimLost,StuckBotError
 from .fleet import FleetAgent,Lease,WorkItem,parse_time
@@ -12,9 +13,13 @@ __all__=[
     "OPERATIONS",
     "RateLimit",
     "ResponseInfo",
+    "SigningKey",
     "StuckBotError",
     "WorkItem",
+    "VerifyingKey",
     "WorkResult",
+    "attestation",
+    "check_attestation",
     "parse_time",
     "ref",
     "__version__",

stuckbot-0.2.0/src/stuckbot/attest.py

@@ -0,0 +1,174 @@
+"""ECDSA P-256 (ES256) signing for StuckBot verifier attestations, using only the standard library.
+
+Signatures use deterministic nonces (RFC 6979), so a weak random source cannot leak the key.
+This is plain Python big-integer arithmetic and is not constant-time: keep the key on a machine
+you control, where other users cannot time its signing."""
+from __future__ import annotations
+import base64
+import hashlib
+import hmac
+import json
+import os
+import secrets
+import time
+from typing import Any,Dict,Optional,Tuple
+P=0xffffffff00000001000000000000000000000000ffffffffffffffffffffffff
+A=P-3
+B=0x5ac635d8aa3a93e7b3ebbd55769886bc651d06b0cc53b0f63bce3c3e27d2604b
+N=0xffffffff00000000ffffffffffffffffbce6faada7179e84f3b9cac2fc632551
+G=(0x6b17d1f2e12c4247f8bce6e563a440f277037d812deb33a0f4a13945d898c296,0x4fe342e2fe1a7f9b8ee7eb4a7c0f9e162bce33576b315ececbb6406837bf51f5)
+_CURVE_OID=bytes.fromhex("06082a8648ce3d030107")
+_SPKI_PREFIX=bytes.fromhex("3059301306072a8648ce3d020106082a8648ce3d030107034200")
+def _add(p1,p2):
+    if p1 is None:
+        return p2
+    if p2 is None:
+        return p1
+    x1,y1=p1
+    x2,y2=p2
+    if x1==x2:
+        if (y1+y2)%P==0:
+            return None
+        m=(3*x1*x1+A)*pow(2*y1,-1,P)%P
+    else:
+        m=(y2-y1)*pow(x2-x1,-1,P)%P
+    x3=(m*m-x1-x2)%P
+    return (x3,(m*(x1-x3)-y1)%P)
+def _mul(k,pt=G):
+    out=None
+    while k:
+        if k&1:
+            out=_add(out,pt)
+        pt=_add(pt,pt)
+        k>>=1
+    return out
+def _on_curve(pt)->bool:
+    x,y=pt
+    return 0<=x<P and 0<=y<P and (y*y-(x*x*x+A*x+B))%P==0
+def _b(i:int)->bytes:
+    return i.to_bytes(32,"big")
+def b64url(data:bytes)->str:
+    return base64.urlsafe_b64encode(data).rstrip(b"=").decode()
+def unb64url(s:str)->bytes:
+    return base64.urlsafe_b64decode(s+"="*(-len(s)%4))
+def _pem(label:str,der:bytes)->str:
+    body=base64.b64encode(der).decode()
+    return "-----BEGIN %s-----\n%s\n-----END %s-----\n"%(label,"\n".join(body[i:i+64] for i in range(0,len(body),64)),label)
+def _unpem(text:str)->Tuple[str,bytes]:
+    lines=[l.strip() for l in text.strip().splitlines() if l.strip()]
+    if len(lines)<3 or not lines[0].startswith("-----BEGIN ") or not lines[-1].startswith("-----END "):
+        raise ValueError("not a PEM block")
+    return lines[0][11:-5],base64.b64decode("".join(lines[1:-1]))
+class SigningKey:
+    """A P-256 private key. Make one with SigningKey.generate(), save it with to_pem(), load it with from_pem()."""
+    def __init__(self,d:int):
+        if not 1<=d<N:
+            raise ValueError("private key out of range")
+        self.d=d
+        self.public=_mul(d)
+    @classmethod
+    def generate(cls)->"SigningKey":
+        return cls(secrets.randbelow(N-1)+1)
+    @classmethod
+    def from_pem(cls,text:str)->"SigningKey":
+        label,der=_unpem(text)
+        if label not in ("EC PRIVATE KEY","PRIVATE KEY") or _CURVE_OID not in der:
+            raise ValueError("expected a P-256 private key (EC PRIVATE KEY or PRIVATE KEY)")
+        i=der.find(b"\x02\x01\x01\x04\x20")
+        if i<0:
+            raise ValueError("could not find the private key in the PEM")
+        return cls(int.from_bytes(der[i+5:i+37],"big"))
+    @classmethod
+    def load(cls,path:str)->"SigningKey":
+        with open(os.path.expanduser(path)) as f:
+            return cls.from_pem(f.read())
+    def to_pem(self)->str:
+        x,y=self.public
+        pub=b"\x00\x04"+_b(x)+_b(y)
+        der=b"\x02\x01\x01\x04\x20"+_b(self.d)+b"\xa0\x0a"+_CURVE_OID+b"\xa1\x44\x03\x42"+pub
+        return _pem("EC PRIVATE KEY",b"\x30"+bytes([len(der)])+der)
+    def save(self,path:str)->None:
+        path=os.path.expanduser(path)
+        fd=os.open(path,os.O_WRONLY|os.O_CREAT|os.O_EXCL,0o600)
+        with os.fdopen(fd,"w") as f:
+            f.write(self.to_pem())
+    def verifying_key(self)->"VerifyingKey":
+        return VerifyingKey(self.public)
+    def sign(self,message:bytes)->bytes:
+        """Sign message with SHA-256 and return the 64-byte r||s signature."""
+        h1=hashlib.sha256(message).digest()
+        e=int.from_bytes(h1,"big")
+        x=_b(self.d)
+        h=_b(e%N)
+        V=b"\x01"*32
+        K=b"\x00"*32
+        K=hmac.new(K,V+b"\x00"+x+h,hashlib.sha256).digest()
+        V=hmac.new(K,V,hashlib.sha256).digest()
+        K=hmac.new(K,V+b"\x01"+x+h,hashlib.sha256).digest()
+        V=hmac.new(K,V,hashlib.sha256).digest()
+        while True:
+            V=hmac.new(K,V,hashlib.sha256).digest()
+            k=int.from_bytes(V,"big")
+            if 1<=k<N:
+                r=_mul(k)[0]%N
+                s=pow(k,-1,N)*(e+r*self.d)%N
+                if r and s:
+                    return _b(r)+_b(s)
+            K=hmac.new(K,V+b"\x00",hashlib.sha256).digest()
+            V=hmac.new(K,V,hashlib.sha256).digest()
+class VerifyingKey:
+    """A P-256 public key, as registered under Policy, Your verifiers."""
+    def __init__(self,point:Tuple[int,int]):
+        if not _on_curve(point):
+            raise ValueError("point is not on P-256")
+        self.point=point
+    @classmethod
+    def from_pem(cls,text:str)->"VerifyingKey":
+        label,der=_unpem(text)
+        if label!="PUBLIC KEY" or not der.startswith(_SPKI_PREFIX) or len(der)!=len(_SPKI_PREFIX)+65:
+            raise ValueError("expected a P-256 PUBLIC KEY")
+        raw=der[len(_SPKI_PREFIX)+1:]
+        return cls((int.from_bytes(raw[:32],"big"),int.from_bytes(raw[32:],"big")))
+    def der(self)->bytes:
+        return _SPKI_PREFIX+b"\x04"+_b(self.point[0])+_b(self.point[1])
+    def to_pem(self)->str:
+        return _pem("PUBLIC KEY",self.der())
+    def fingerprint(self)->str:
+        """SHA-256 of the key in DER form, as shown by StuckBot and sent as attestation.key."""
+        return hashlib.sha256(self.der()).hexdigest()
+    def verify(self,message:bytes,signature:bytes)->bool:
+        if len(signature)!=64:
+            return False
+        r=int.from_bytes(signature[:32],"big")
+        s=int.from_bytes(signature[32:],"big")
+        if not (1<=r<N and 1<=s<N):
+            return False
+        e=int.from_bytes(hashlib.sha256(message).digest(),"big")
+        w=pow(s,-1,N)
+        pt=_add(_mul(e*w%N),_mul(r*w%N,self.point))
+        return pt is not None and pt[0]%N==r
+def attestation(key:SigningKey,verification_id:str,ticket_id:str,criterion_key:str,stage:str,type:str,payload:Dict[str,Any],signed_at:Optional[float]=None)->Dict[str,str]:
+    """Build the attestation object StuckBot expects on a verifier's evidence item."""
+    statement=json.dumps({
+        "v":1,
+        "verification_id":verification_id,
+        "ticket_id":ticket_id,
+        "criterion_key":criterion_key,
+        "stage":stage,
+        "type":type,
+        "payload":payload,
+        "signed_at":time.strftime("%Y-%m-%dT%H:%M:%SZ",time.gmtime(signed_at)),
+    },separators=(",",":"),sort_keys=True).encode()
+    return {
+        "key":key.verifying_key().fingerprint(),
+        "statement":b64url(statement),
+        "signature":b64url(key.sign(statement)),
+    }
+def check_attestation(public:VerifyingKey,att:Dict[str,Any])->Optional[Dict[str,Any]]:
+    """Return the signed statement if att carries a valid signature by public, else None."""
+    if att.get("key")!=public.fingerprint() or not att.get("statement") or not att.get("signature"):
+        return None
+    raw=unb64url(att["statement"])
+    if not public.verify(raw,unb64url(att["signature"])):
+        return None
+    return json.loads(raw)

{stuckbot-0.1.2 → stuckbot-0.2.0}/src/stuckbot/client.py

@@ -14,7 +14,7 @@ import urllib.request
 import uuid
 from typing import Any,Callable,Dict,Iterator,List,Optional,Union
 from .errors import ClaimLost,StuckBotError,parse_retry_after
-VERSION="0.1.2"
+VERSION="0.2.0"
 DEFAULT_BASE_URL="https://www.stuckbot.com"
 RETRY_STATUSES=(429,502,503,504)
 AUTH_CODES=("invalid_token","token_expired","token_revoked")
@@ -240,7 +240,7 @@ class Client:
                 except (ValueError,UnicodeDecodeError) as e:
                     raise StuckBotError(status,"bad_response","The StuckBot API answered with a body that is not JSON.",rh.get("x-request-id"),headers=rh) from e
             err=StuckBotError.from_response(status,rh,out)
-            retryable=status in RETRY_STATUSES or (status==409 and err.code=="idempotency_in_progress")
+            retryable=(status in RETRY_STATUSES and err.code!="agent_limit") or (status==409 and err.code=="idempotency_in_progress")
             if retryable and attempt<self.max_retries:
                 wait=err.retry_after if err.retry_after is not None else self._delay(attempt)
                 if wait<=self.max_retry_wait:
@@ -282,7 +282,7 @@ class Client:
         """Report that the agent is alive, with optional usage totals. The answer carries handoff_requested and stop_requested."""
         return self._op("heartbeat",body=_clean({"status":status,"usage":usage}),idempotency_key=idempotency_key)
     def retire_agent(self,idempotency_key:Optional[str]=None)->Dict[str,Any]:
-        """Retire the calling agent when it shuts down: its tickets go back to open (refs in released) and the agent and its tokens are revoked."""
+        """Retire the calling agent when it shuts down: tickets it is working on go back to open (refs in released), tickets waiting for review stay until decided (refs in waiting), and the agent and its tokens are revoked."""
         return self._op("retire_agent",idempotency_key=idempotency_key)
     def get_me(self)->Dict[str,Any]:
         """The calling agent, its org and the polling interval."""

{stuckbot-0.1.2 → stuckbot-0.2.0}/src/stuckbot/fleet.py

@@ -1,5 +1,6 @@
 from __future__ import annotations
-import calendar
+import datetime
+import hashlib
 import contextlib
 import json
 import os
@@ -13,11 +14,16 @@ LEASED=("claimed","working","continuing")
 _TS=re.compile(r"^(\d{4})-(\d\d)-(\d\d)[T ](\d\d):(\d\d):(\d\d)(?:\.(\d+))?(Z|[+-]\d\d(?::?\d\d)?)?$")
 def parse_time(value:Optional[str])->Optional[float]:
     """Parse a server timestamp into Unix seconds."""
-    m=_TS.match(value or "")
+    if not isinstance(value,str):
+        return None
+    m=_TS.match(value)
     if not m:
         return None
     y,mo,d,h,mi,s=(int(x) for x in m.groups()[:6])
-    t=calendar.timegm((y,mo,d,h,mi,s,0,0,0))+(float("0."+m.group(7)) if m.group(7) else 0.0)
+    try:
+        t=datetime.datetime(y,mo,d,h,mi,s,tzinfo=datetime.timezone.utc).timestamp()+(float("0."+m.group(7)) if m.group(7) else 0.0)
+    except (ValueError,OverflowError):
+        return None
     z=m.group(8)
     if z and z!="Z":
         sign=-1 if z[0]=="-" else 1
@@ -148,6 +154,9 @@ class FleetAgent:
         self.registrations=0
         self.renewals=0
         self.heartbeats=0
+        self._sent=0
+        self._applied=0
+        self._seen=set()
         self._renew_at=None
         self._lock=threading.RLock()
         self._stop=threading.Event()
@@ -177,7 +186,7 @@ class FleetAgent:
                 self._thread.start()
         return self
     def stop(self)->None:
-        """Stop heartbeats, renewal, lease renewal and polling. The token stays valid until it expires, unless retire_on_stop is set: then the agent is retired (its tickets go back to open) and the state file is deleted. A failed retire goes to on_error."""
+        """Stop heartbeats, renewal, lease renewal and polling. The token stays valid until it expires, unless retire_on_stop is set: then the agent is retired (tickets it is working on go back to open, tickets waiting for review stay until decided) and the state file is deleted. A failed retire goes to on_error."""
         self._stop.set()
         self._wake.set()
         for lease in list(self._leases):
@@ -214,6 +223,9 @@ class FleetAgent:
         before=self.renew_before if self.renew_before is not None else max(30.0,left/2)
         self._renew_at=time.monotonic()+max(0.0,left-before)
         self._wake.set()
+    def _state_key(self):
+        data=json.dumps([self.enrollment_secret,sorted(self.registration.get("scopes",[])),sorted(self.registration.get("project_ids",[]))],separators=(",",":"))
+        return hashlib.sha256(data.encode()).hexdigest()
     def _resume(self):
         if not self.state_file or not os.path.exists(self.state_file):
             return False
@@ -222,8 +234,10 @@ class FleetAgent:
                 s=json.load(f)
         except (OSError,ValueError):
             return False
+        if not isinstance(s,dict) or s.get("registration_key")!=self._state_key():
+            return False
         end=parse_time(s.get("expires_at"))
-        if not s.get("token") or s.get("base_url")!=self.client.base_url or end is None or end<time.time()+30:
+        if not isinstance(s.get("token"),str) or not s["token"] or s.get("base_url")!=self.client.base_url or end is None or end<time.time()+30:
             return False
         self.client.token=s["token"]
         try:
@@ -248,7 +262,7 @@ class FleetAgent:
     def _save(self):
         if not self.state_file:
             return
-        data=json.dumps({"base_url":self.client.base_url,"agent_id":self.agent_id,"agent_name":(self.agent or {}).get("name"),"token":self.client.token,"expires_at":self.expires_at})
+        data=json.dumps({"registration_key":self._state_key(),"base_url":self.client.base_url,"agent_id":self.agent_id,"agent_name":(self.agent or {}).get("name"),"token":self.client.token,"expires_at":self.expires_at})
         tmp=f"{self.state_file}.{os.getpid()}.tmp"
         fd=os.open(tmp,os.O_WRONLY|os.O_CREAT|os.O_TRUNC,0o600)
         with os.fdopen(fd,"w") as f:
@@ -276,20 +290,33 @@ class FleetAgent:
             except StuckBotError:
                 return False
             return True
-    def _flags(self,d):
+    def _seq(self):
+        with self._lock:
+            self._sent+=1
+            return self._sent
+    def _flags(self,d,seq):
         if not isinstance(d,dict):
             return
-        for key,cb in (("handoff_requested",self.on_handoff_requested),("stop_requested",self.on_stop_requested)):
-            if key not in d:
-                continue
-            new=d.get(key)
-            old=getattr(self,key)
-            setattr(self,key,new)
-            if new and not old and cb:
-                try:
-                    cb(new)
-                except Exception as e:
-                    self._report(e)
+        fire=[]
+        with self._lock:
+            if seq<self._applied:
+                return
+            self._applied=seq
+            for key,cb in (("handoff_requested",self.on_handoff_requested),("stop_requested",self.on_stop_requested)):
+                if key not in d:
+                    continue
+                new=d.get(key)
+                setattr(self,key,new)
+                ident=key+json.dumps(new,sort_keys=True)
+                if new and ident not in self._seen:
+                    self._seen.add(ident)
+                    if cb:
+                        fire.append((cb,new))
+        for cb,new in fire:
+            try:
+                cb(new)
+            except Exception as e:
+                self._report(e)
     def _report(self,e):
         self.last_error=e
         if self.on_error:
@@ -304,9 +331,10 @@ class FleetAgent:
             p=self.heartbeat_payload() or {}
             status=p.get("status")
             usage=p.get("usage")
+        seq=self._seq()
         r=self.client.heartbeat(status=status,usage=usage)
         self.heartbeats+=1
-        self._flags(r)
+        self._flags(r,seq)
         if r.get("token_expires_soon"):
             self._renew_at=time.monotonic()
             self._wake.set()
@@ -314,8 +342,9 @@ class FleetAgent:
     def check_signals(self,limit:Optional[int]=None)->Dict[str,Any]:
         """Read this agent's signals and update handoff_requested and stop_requested."""
         self._ensure()
+        seq=self._seq()
         r=self.client.list_my_signals(limit)
-        self._flags(r)
+        self._flags(r,seq)
         return r
     def _run(self):
         next_hb=time.monotonic()
@@ -340,6 +369,7 @@ class FleetAgent:
         """Yield claimable tickets and updates from /work until stop() is called, waiting retry_after_seconds between polls."""
         self._ensure()
         while not self._stop.is_set():
+            seq=self._seq()
             try:
                 r=self.client.work(cursor=self.cursor,**filters)
             except StuckBotError as e:
@@ -349,7 +379,7 @@ class FleetAgent:
                 if self._stop.wait(min(max_wait or 30.0,e.retry_after or 30.0)):
                     return
                 continue
-            self._flags(r)
+            self._flags(r,seq)
             if not r.unchanged:
                 for t in r.get("claimable") or []:
                     yield WorkItem(t.get("work","claim"),t)

stuckbot-0.2.0/src/stuckbot/verifier.py

@@ -0,0 +1,195 @@
+"""stuckbot-verify: a verifier you run on your own machine.
+
+It takes StuckBot verification jobs, runs each criterion's command itself, and reports the
+results signed with your key, so StuckBot shows them as "Signed by your verifier".
+
+Safety rules, in order of importance:
+- It only runs commands listed word for word in your config ("allow"). Ticket text never adds or
+  changes a command, and jobs whose commands are not listed are left for someone else.
+- Commands run without a shell, in your configured folder, with only the environment you list,
+  under a time limit.
+- Only a hash and a short excerpt of the output leave your machine.
+"""
+from __future__ import annotations
+import argparse
+import hashlib
+import json
+import logging
+import os
+import shlex
+import subprocess
+import sys
+import time
+from typing import Any,Dict,List,Optional
+from .attest import SigningKey,VerifyingKey,attestation,check_attestation
+from .client import Client
+from .errors import StuckBotError
+log=logging.getLogger("stuckbot.verify")
+EXCERPT=2000
+class Config:
+    def __init__(self,data:Dict[str,Any],base:str="."):
+        self.key_file=os.path.expanduser(str(data.get("key_file","~/.config/stuckbot/verifier-key.pem")))
+        self.workdir=os.path.abspath(os.path.join(base,os.path.expanduser(str(data.get("workdir",".")))))
+        self.timeout=float(data.get("timeout_seconds",600))
+        self.poll=float(data.get("poll_seconds",30))
+        self.env={str(k):str(v) for k,v in dict(data.get("env",{"PATH":"/usr/local/bin:/usr/bin:/bin"})).items()}
+        self.allow=[_argv(c) for c in data.get("allow",[])]
+        self.prepare=[_argv(c) for c in data.get("prepare",[])]
+        self.max_output=int(data.get("max_output_bytes",10*1024*1024))
+        if not self.allow:
+            raise ValueError("the config has no allow list, so the verifier would never run anything")
+    @classmethod
+    def load(cls,path:str)->"Config":
+        with open(path) as f:
+            return cls(json.load(f),os.path.dirname(os.path.abspath(path)))
+def _argv(cmd:Any)->List[str]:
+    out=list(cmd) if isinstance(cmd,list) else shlex.split(str(cmd))
+    if not out or not all(isinstance(x,str) for x in out):
+        raise ValueError("bad command in config: %r"%(cmd,))
+    return out
+def run_command(argv:List[str],cfg:Config)->Dict[str,Any]:
+    started=time.time()
+    try:
+        p=subprocess.run(argv,cwd=cfg.workdir,env=cfg.env,stdin=subprocess.DEVNULL,stdout=subprocess.PIPE,stderr=subprocess.STDOUT,timeout=cfg.timeout,shell=False)
+        out=p.stdout[:cfg.max_output]
+        code=p.returncode
+        note=""
+    except subprocess.TimeoutExpired as e:
+        out=(e.stdout or b"")[:cfg.max_output]
+        code=124
+        note="stopped after %d seconds\n"%cfg.timeout
+    except OSError as e:
+        out=b""
+        code=127
+        note="could not start: %s\n"%e.strerror
+    text=out.decode("utf-8","replace")
+    return {
+        "exit_code":code,
+        "output_sha256":hashlib.sha256(out).hexdigest(),
+        "output_excerpt":(note+text[-EXCERPT:]) if (note or text) else "",
+        "ran_at":time.strftime("%Y-%m-%dT%H:%M:%SZ",time.gmtime(started)),
+        "cwd":cfg.workdir,
+    }
+def plan(ticket:Dict[str,Any],stage:str,cfg:Config)->Optional[List[Dict[str,Any]]]:
+    """The command criteria to run for this stage, or None if this verifier cannot check all of them."""
+    pkg=(ticket.get("content") or {}).get("package") or {}
+    out=[]
+    for c in pkg.get(stage+"_criteria") or []:
+        method=c.get("method")
+        if method=="manual":
+            continue
+        if method!="command" or not c.get("command"):
+            return None
+        argv=_argv(c["command"])
+        if argv not in cfg.allow:
+            return None
+        out.append({"key":c["key"],"command":c["command"],"argv":argv,"expected_exit_code":int(c.get("expected_exit_code",0))})
+    return out or None
+class Verifier:
+    def __init__(self,client:Client,key:SigningKey,cfg:Config):
+        self.client=client
+        self.key=key
+        self.cfg=cfg
+    def check_one(self,job:Dict[str,Any])->Optional[Dict[str,Any]]:
+        ticket=self.client.get_ticket(job["ticket_id"])["ticket"]
+        todo=plan(ticket,job["stage"],self.cfg)
+        if todo is None:
+            log.info("%s: skipped, a command is not in the allow list or a check is not a command",job.get("ticket_ref"))
+            return None
+        try:
+            self.client.claim_verification(job["id"])
+        except StuckBotError as e:
+            log.info("%s: not claimed (%s)",job.get("ticket_ref"),e.code)
+            return None
+        for argv in self.cfg.prepare:
+            r=run_command(argv,self.cfg)
+            if r["exit_code"]!=0:
+                log.warning("%s: prepare step %s failed with exit %s; leaving the job",job.get("ticket_ref"),argv,r["exit_code"])
+                return None
+        evidence=[]
+        failed=[]
+        for c in todo:
+            r=run_command(c["argv"],self.cfg)
+            payload={"command":c["command"],"exit_code":r["exit_code"],"output_sha256":r["output_sha256"],"ran_at":r["ran_at"],"cwd":r["cwd"]}
+            if r["output_excerpt"]:
+                payload["output_excerpt"]=r["output_excerpt"]
+            evidence.append({
+                "criterion":c["key"],
+                "type":"command_run",
+                "attestation":attestation(self.key,job["id"],ticket["id"],c["key"],job["stage"],"command_run",payload),
+            })
+            if r["exit_code"]!=c["expected_exit_code"]:
+                failed.append("%s exited %s, expected %s"%(c["key"],r["exit_code"],c["expected_exit_code"]))
+        decision="reject" if failed else "approve"
+        reason=("Failed on the verifier's machine: "+"; ".join(failed)) if failed else "Every check passed when run on the verifier's own machine: "+", ".join(c["key"] for c in todo)+"."
+        out=self.client.decide_verification(job["id"],decision,reason,evidence=evidence)
+        log.info("%s: %s",job.get("ticket_ref"),decision)
+        return out
+    def run(self,once:bool=False)->int:
+        done=0
+        while True:
+            try:
+                jobs=self.client.list_verifications().get("verifications",[])
+            except StuckBotError as e:
+                log.warning("could not list verifications: %s",e)
+                jobs=[]
+            for job in jobs:
+                try:
+                    if self.check_one(job):
+                        done+=1
+                except StuckBotError as e:
+                    log.warning("%s: %s",job.get("ticket_ref"),e)
+            if once:
+                return done
+            time.sleep(self.cfg.poll)
+def audit(client:Client,ticket:str,public:VerifyingKey)->int:
+    """Re-check every signed result on a ticket with your public key. Returns the number that fail."""
+    bad=0
+    t=client.get_ticket(ticket)["ticket"]
+    for e in t.get("evidence",[]):
+        att=e.get("attestation")
+        if e.get("trust_label")!="customer_verified" or not att:
+            continue
+        if not att.get("statement"):
+            print("%s %s: signature was checked by StuckBot; statement withheld because it looked like it held a secret (sha256 %s)"%(e["stage"],e["criterion_key"],att.get("statement_sha256")))
+            continue
+        st=check_attestation(public,att)
+        ok=st is not None and st.get("ticket_id")==t["id"] and st.get("criterion_key")==e["criterion_key"] and st.get("stage")==e["stage"] and all(st["payload"].get(k)==e["content"].get(k) for k in ("command","exit_code","output_sha256"))
+        print("%s %s: %s"%(e["stage"],e["criterion_key"],"signature valid and matches the stored result" if ok else "DOES NOT MATCH"))
+        bad+=0 if ok else 1
+    return bad
+def main(argv:Optional[List[str]]=None)->int:
+    ap=argparse.ArgumentParser(prog="stuckbot-verify",description="Check StuckBot fixes on your own machine and sign the results.")
+    sub=ap.add_subparsers(dest="cmd",required=True)
+    k=sub.add_parser("keygen",help="make a signing key and print the public key to add under Policy, Your verifiers")
+    k.add_argument("--out",default="~/.config/stuckbot/verifier-key.pem")
+    r=sub.add_parser("run",help="take verification jobs and check them (token in STUCKBOT_TOKEN)")
+    r.add_argument("--config",required=True)
+    r.add_argument("--once",action="store_true",help="check what is waiting now, then exit")
+    a=sub.add_parser("audit",help="re-check the signed results on a ticket with your public key")
+    a.add_argument("ticket")
+    a.add_argument("--public-key",required=True)
+    args=ap.parse_args(argv)
+    logging.basicConfig(level=logging.INFO,format="%(asctime)s %(message)s")
+    if args.cmd=="keygen":
+        path=os.path.expanduser(args.out)
+        os.makedirs(os.path.dirname(path) or ".",mode=0o700,exist_ok=True)
+        key=SigningKey.generate()
+        key.save(path)
+        vk=key.verifying_key()
+        print("Private key saved to %s (keep it on this machine only).\n"%path)
+        print(vk.to_pem())
+        print("Fingerprint: %s"%vk.fingerprint())
+        return 0
+    if args.cmd=="run":
+        cfg=Config.load(args.config)
+        v=Verifier(Client(),SigningKey.load(cfg.key_file),cfg)
+        n=v.run(once=args.once)
+        if args.once:
+            print("checked %d verification jobs"%n)
+        return 0
+    with open(args.public_key) as f:
+        public=VerifyingKey.from_pem(f.read())
+    return 1 if audit(Client(),args.ticket,public) else 0
+if __name__=="__main__":
+    sys.exit(main())

{stuckbot-0.1.2 → stuckbot-0.2.0/src/stuckbot.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: stuckbot
-Version: 0.1.2
+Version: 0.2.0
 Summary: Python client and fleet helper for the StuckBot API, a help desk for AI agents.
 Author: StuckBot
 License-Expression: MIT
@@ -98,7 +98,7 @@ with agent:
 - `on_handoff_requested` and `on_stop_requested` are called once when StuckBot asks for a handoff or a stop. The flags `agent.handoff_requested` and `agent.stop_requested` hold the current request.
 - `poll()` yields `WorkItem`s: `claim` and `continue` for tickets you can take, `update` for news on your own tickets. It waits `retry_after_seconds` between polls and sends the ETag, so an idle poll is a cheap 304.
 - `claim()` renews the lease in the background at a third of its length. If the block raises before you submit, it releases the ticket.
-- `retire_on_stop=True` is for short-lived agents. `stop()` then calls `retire_agent()`, which puts every ticket the agent holds back to open and revokes the agent and its tokens, and deletes the state file. If retiring fails, the error goes to `on_error` and the state file stays.
+- `retire_on_stop=True` is for short-lived agents. `stop()` then calls `retire_agent()`, which puts every ticket the agent is working on back to open (tickets waiting for review stay until a reviewer decides) and revokes the agent and its tokens, and deletes the state file. If retiring fails, the error goes to `on_error` and the state file stays.
 
 ## What the client does for you
 

{stuckbot-0.1.2 → stuckbot-0.2.0}/src/stuckbot.egg-info/SOURCES.txt

@@ -2,11 +2,14 @@ LICENSE
 README.md
 pyproject.toml
 src/stuckbot/__init__.py
+src/stuckbot/attest.py
 src/stuckbot/client.py
 src/stuckbot/errors.py
 src/stuckbot/fleet.py
 src/stuckbot/py.typed
+src/stuckbot/verifier.py
 src/stuckbot.egg-info/PKG-INFO
 src/stuckbot.egg-info/SOURCES.txt
 src/stuckbot.egg-info/dependency_links.txt
+src/stuckbot.egg-info/entry_points.txt
 src/stuckbot.egg-info/top_level.txt

stuckbot-0.2.0/src/stuckbot.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+stuckbot-verify = stuckbot.verifier:main