gru-bot 0.1.0__py3-none-any.whl

gru_associate.py

@@ -0,0 +1,325 @@
+# /// script
+# requires-python = ">=3.11"
+# dependencies = ["qrcode[pil]==8.2"]
+# ///
+"""Bounded WeChat association. No message sending, model, service or auto-refresh."""
+import argparse
+import base64
+from contextlib import contextmanager
+import fcntl
+import json
+import os
+from pathlib import Path
+import re
+import secrets
+import socket
+import shlex
+import stat
+import tempfile
+import time
+from urllib.parse import urlencode, urlsplit
+from urllib.request import build_opener, Request
+from gru_weixin import Binding, BoundaryError, NoRedirect
+
+BASE = 'https://ilinkai.weixin.qq.com'
+FIELDS = {'GRU_ILINK_ACCOUNT_ID': 'ilink_bot_id', 'GRU_ILINK_USER_ID': 'ilink_user_id',
+          'GRU_ILINK_BASE_URL': 'baseurl', 'GRU_ILINK_TOKEN': 'bot_token'}
+STATES = {'wait','scaned','confirmed','expired','scaned_but_redirect','need_verifycode',
+          'verify_code_blocked','binded_redirect'}
+
+
+def private_path(path, directory=False):
+    if path.is_symlink():
+        raise BoundaryError('symlink state is not accepted')
+    s = path.stat()
+    if s.st_uid != os.getuid() or stat.S_IMODE(s.st_mode) & 0o077:
+        raise BoundaryError('state must be owner-only')
+    if directory != stat.S_ISDIR(s.st_mode):
+        raise BoundaryError('unexpected state path type')
+
+
+def atomic(path, data):
+    if path.exists() or path.is_symlink():
+        private_path(path)
+    fd, name = tempfile.mkstemp(prefix='.association-', dir=path.parent)
+    try:
+        with os.fdopen(fd, 'wb') as h:
+            h.write(data); h.flush(); os.fsync(h.fileno())
+        os.replace(name, path)
+        d = os.open(path.parent, os.O_RDONLY)
+        try: os.fsync(d)
+        finally: os.close(d)
+    finally:
+        if os.path.exists(name): os.unlink(name)
+
+
+def official_base(value):
+    p = urlsplit(value)
+    if (p.scheme != 'https' or p.username or p.password or p.port or p.query or p.fragment
+            or p.path not in ('', '/') or not p.hostname
+            or not (p.hostname == 'weixin.qq.com' or p.hostname.endswith('.weixin.qq.com'))):
+        raise BoundaryError('unrecognized official association host; preserve for review')
+    return 'https://' + p.hostname
+
+
+def binding_values(data):
+    if not isinstance(data, dict) or any(not isinstance(data.get(v),str) or not data[v]
+                                        or any(c in data[v] for c in '\r\n\x00') for v in FIELDS.values()):
+        raise BoundaryError('association fields missing or malformed')
+    official_base(data['baseurl'])
+    Binding(data['ilink_bot_id'], data['ilink_user_id'], data['baseurl'])
+    return {k:data[v] for k,v in FIELDS.items()}
+
+
+def environment_binding():
+    values = {k:os.environ.get(k, '') for k in FIELDS}
+    if not any(values.values()): return None
+    if not all(values.values()): raise BoundaryError('partial existing binding; no new association')
+    binding_values({FIELDS[k]:v for k,v in values.items()})
+    return values
+
+
+@contextmanager
+def profile_fence(profile):
+    if profile.is_symlink() or not profile.is_file():
+        raise BoundaryError('existing regular shell profile required')
+    if profile.stat().st_uid!=os.getuid(): raise BoundaryError('profile owner differs')
+    normalized=profile.resolve(strict=True)
+    lock=Path(str(normalized)+'.gru-association.fence')
+    try: fd=os.open(lock,os.O_CREAT|os.O_EXCL|os.O_WRONLY,0o600)
+    except FileExistsError:
+        raise BoundaryError('profile installation is occupied; preserve the lock for review') from None
+    nonce=secrets.token_hex(16)
+    try:
+        os.write(fd,nonce.encode());os.fsync(fd)
+        yield normalized
+    finally:
+        os.close(fd)
+        if not lock.is_symlink() and lock.is_file() and lock.read_text()==nonce: lock.unlink()
+
+
+class Association:
+    def __init__(self, root, request=None, now=time.time, renderer=None):
+        if not root.is_absolute(): raise BoundaryError('absolute state directory required')
+        if not root.exists(): root.mkdir(mode=0o700, parents=True)
+        private_path(root, True)
+        self.root, self.now = root, now
+        self.request = request or self.http
+        self.renderer = renderer or self.render
+
+    @contextmanager
+    def locked(self):
+        p=self.root/'association.lock'
+        fd=os.open(p,os.O_CREAT|os.O_RDWR|os.O_NOFOLLOW,0o600)
+        try:
+            private_path(p)
+            fcntl.flock(fd,fcntl.LOCK_EX|fcntl.LOCK_NB)
+            with self.fenced():
+                yield
+        finally: os.close(fd)
+
+    @contextmanager
+    def fenced(self):
+        # Shared with the Node CLI; preserve the legacy flock for Python clients.
+        gate=self.root/'association.fence.acquire'
+        lock=self.root/'association.fence'
+        gate_fd=os.open(gate,os.O_CREAT|os.O_EXCL|os.O_WRONLY,0o600)
+        nonce=secrets.token_hex(16)
+        try:
+            if lock.exists():
+                private_path(lock)
+                owner=json.loads(lock.read_text())
+                if (owner.get('host')!=socket.gethostname() or type(owner.get('pid')) is not int
+                        or owner['pid']<1 or not isinstance(owner.get('nonce'),str)):
+                    raise BoundaryError('unrecognized association lock; preserve for review')
+                try: os.kill(owner['pid'],0)
+                except ProcessLookupError: lock.unlink()
+                else: raise BoundaryError('association is occupied')
+            fd=os.open(lock,os.O_CREAT|os.O_EXCL|os.O_WRONLY,0o600)
+            with os.fdopen(fd,'w') as h:
+                json.dump({'pid':os.getpid(),'host':socket.gethostname(),'nonce':nonce},h)
+                h.flush();os.fsync(h.fileno())
+        finally:
+            os.close(gate_fd);gate.unlink()
+        try: yield
+        finally:
+            private_path(lock)
+            owner=json.loads(lock.read_text())
+            if owner.get('nonce')==nonce: lock.unlink()
+
+    def load(self):
+        p=self.root/'session.json'
+        if not p.exists(): return None
+        private_path(p)
+        s=json.loads(p.read_text())
+        if (not isinstance(s,dict) or s.get('schema')!=1
+                or s.get('status') not in STATES|{'request_unknown'}):
+            raise BoundaryError('unknown association state')
+        official_base(s['base_url'])
+        return s
+
+    def save(self,s): atomic(self.root/'session.json',json.dumps(s).encode())
+
+    def http(self,method,base,endpoint,body=None):
+        base=official_base(base)
+        headers={'iLink-App-Id':'bot','iLink-App-ClientVersion':str((2<<16)|(4<<8)|9)}
+        if method=='POST':
+            headers.update({'Content-Type':'application/json','AuthorizationType':'ilink_bot_token',
+                'X-WECHAT-UIN':base64.b64encode(str(secrets.randbits(32)).encode()).decode()})
+        r=Request(base+'/'+endpoint, None if body is None else json.dumps(body).encode(),headers,method=method)
+        with build_opener(NoRedirect).open(r,timeout=36 if method=='GET' else 20) as response:
+            data=json.loads(response.read())
+        if not isinstance(data,dict): raise BoundaryError('invalid association response')
+        return data
+
+    def render(self,text):
+        import io,qrcode
+        h=io.BytesIO();qrcode.make(text).save(h,format='PNG')
+        atomic(self.root/'qr.png',h.getvalue())
+
+    def inspect(self,s=None):
+        s=self.load() if s is None else s
+        if not s: return {'state':'not_started','message_sent':False}
+        status=s['status']
+        if status=='confirmed':
+            binding_values(s['binding'])
+            return {'state':'confirmed','binding_complete':True,'message_sent':False}
+        if status in ('wait','scaned','need_verifycode','scaned_but_redirect') and self.now()>=s['local_expires_at']:
+            status='local_expired'
+        result={'state':status,'message_sent':False}
+        if status in ('wait','scaned','need_verifycode','scaned_but_redirect'):
+            result.update(qr_image=str(self.root/'qr.png'),local_expires_at=s['local_expires_at'])
+        return result
+
+    def start(self,refresh=False):
+        env=environment_binding()
+        if env: return {'state':'existing_environment_binding','binding_complete':True,'message_sent':False}
+        s=self.load()
+        if s:
+            state=self.inspect(s)['state']
+            if state=='confirmed': return self.inspect(s)
+            if state not in ('expired','local_expired'): return self.inspect(s)
+            if not refresh: return self.inspect(s)
+            # Keep prior session bytes; refreshing requires an observed expiry.
+            backup=self.root/('expired-'+secrets.token_hex(8)+'.json')
+            atomic(backup,json.dumps(s).encode())
+        s={'schema':1,'status':'request_unknown','base_url':BASE,'created_at':self.now()}
+        self.save(s)  # unknown request is not automatically repeated after interruption
+        d=self.request('POST',BASE,'ilink/bot/get_bot_qrcode?bot_type=3',{'local_token_list':[]})
+        if any(not isinstance(d.get(k),str) or not d[k] for k in ('qrcode','qrcode_img_content')):
+            raise BoundaryError('missing QR fields; request remains unknown')
+        s.update(status='wait',qrcode=d['qrcode'],qr_content=d['qrcode_img_content'],local_expires_at=self.now()+300)
+        self.save(s)
+        self.renderer(s['qr_content'])
+        return self.inspect(s)
+
+    def poll(self,code=None):
+        s=self.load()
+        state=self.inspect(s)['state']
+        if state in ('not_started','confirmed','expired','local_expired','request_unknown',
+                     'verify_code_blocked','binded_redirect'): return self.inspect(s)
+        if code is not None and (state!='need_verifycode' or not re.fullmatch('[0-9]{1,16}',code)):
+            raise BoundaryError('pairing code only accepted at need_verifycode')
+        params={'qrcode':s['qrcode']}
+        if code: params['verify_code']=code
+        d=self.request('GET',s['base_url'],'ilink/bot/get_qrcode_status?'+urlencode(params))
+        status=d.get('status')
+        if status not in STATES: raise BoundaryError('unrecognized association status')
+        if status=='scaned_but_redirect':
+            host=d.get('redirect_host')
+            if not isinstance(host,str): raise BoundaryError('missing redirect host')
+            s['base_url']=official_base('https://'+host)
+        if status=='confirmed':
+            binding_values(d)
+            s['binding']={v:d[v] for v in FIELDS.values()}
+        s['status']=status;self.save(s)
+        return self.inspect(s)
+
+    def render_existing(self):
+        s=self.load()
+        if self.inspect(s)['state'] not in ('wait','scaned','need_verifycode','scaned_but_redirect'):
+            raise BoundaryError('no live QR to render')
+        self.renderer(s['qr_content']);return self.inspect(s)
+
+    def install(self,profile):
+        with profile_fence(profile) as normalized:
+            return self.install_fenced(normalized)
+
+    def install_fenced(self,profile):
+        s=self.load()
+        if self.inspect(s)['state']!='confirmed': raise BoundaryError('confirmed association required')
+        wanted=binding_values(s['binding'])
+        if profile.is_symlink() or not profile.is_file(): raise BoundaryError('existing regular shell profile required')
+        with profile.open('r+') as h:
+            if os.fstat(h.fileno()).st_uid!=os.getuid(): raise BoundaryError('profile owner differs')
+            fcntl.flock(h.fileno(),fcntl.LOCK_EX|fcntl.LOCK_NB)
+            raw=h.read()
+            # Never overwrite an existing declaration (including dynamic configuration).
+            # A general shell profile can construct names. Only literal profiles
+            # are appendable; unknown syntax never means absence of a binding.
+            declared={}
+            for line in raw.splitlines():
+                if not line.strip() or line.lstrip().startswith('#'): continue
+                if any(c in line for c in ('$','`','\\')):
+                    raise BoundaryError('nonliteral profile requires its configuration owner; unchanged')
+                lexer=shlex.shlex(line,posix=True,punctuation_chars='();<>|&')
+                lexer.whitespace_split=True
+                words=list(lexer)
+                words=words[1:] if words and words[0]=='export' else words
+                if not words or any(not re.fullmatch(r'[A-Za-z_][A-Za-z0-9_]*=.*',w) for w in words):
+                    raise BoundaryError('unsupported shell profile; unchanged')
+                for word in words:
+                    k,v=word.split('=',1)
+                    if k in FIELDS:
+                        if k in declared:
+                            raise BoundaryError('duplicate profile binding; unchanged')
+                        declared[k]=v
+            if declared:
+                if declared==wanted and environment_binding()==wanted:
+                    return {'state':'existing_matching_profile','profile_changed':False,'message_sent':False}
+                raise BoundaryError('existing profile binding must be reconciled; unchanged')
+            if environment_binding() not in (None,wanted): raise BoundaryError('environment binding differs')
+            h.seek(0,os.SEEK_END)
+            h.write('\n# Gru WeChat association\n'+''.join('export '+k+'='+shlex.quote(v)+'\n' for k,v in wanted.items()))
+            h.flush();os.fsync(h.fileno())
+        return {'state':'profile_appended','profile_changed':True,'message_sent':False}
+
+
+def main():
+    p=argparse.ArgumentParser(description=__doc__)
+    p.add_argument('--state-dir',type=Path,required=True)
+    c=p.add_subparsers(dest='command',required=True)
+    c.add_parser('inspect',help='local state only; no network')
+    start=c.add_parser('start',help='reuse binding/live QR, otherwise request once');start.add_argument('--refresh',action='store_true')
+    poll=c.add_parser('poll',help='one bounded official status request');poll.add_argument('--code-file',type=Path)
+    c.add_parser('render',help='render existing live QR without requesting another')
+    ins=c.add_parser('install',help='append to literal profiles only; refuse general shell or conflicting bindings')
+    ins.add_argument('--profile',type=Path,default=Path.home()/'.zprofile')
+    a=p.parse_args()
+    try:
+        x=Association(a.state_dir)
+        with x.locked():
+            if a.command=='start': r=x.start(a.refresh)
+            elif a.command=='inspect': r=x.inspect()
+            elif a.command=='render': r=x.render_existing()
+            elif a.command=='install': r=x.install(a.profile)
+            else:
+                code=None
+                if a.code_file:
+                    private_path(a.code_file);code=a.code_file.read_text().strip()
+                r=x.poll(code)
+        print(json.dumps(r))
+        return 2 if r['state'] in ('request_unknown','not_started','verify_code_blocked','binded_redirect') else 0
+    except Exception as e:
+        # URL, QR nonce, pairing digits, server body and credentials never enter stdout/stderr.
+        result={'state':'failed','error_type':type(e).__name__,'message_sent':False}
+        if isinstance(e,BoundaryError):
+            if str(e)=='profile installation is occupied; preserve the lock for review':
+                result['reason']='profile_install_occupied'
+            elif str(e) in ('existing profile binding must be reconciled; unchanged',
+                            'duplicate profile binding; unchanged','environment binding differs'):
+                result['reason']='profile_binding_conflict'
+        print(json.dumps(result))
+        return 2
+
+if __name__=='__main__': raise SystemExit(main())

gru_bot-0.1.0.dist-info/METADATA

@@ -0,0 +1,84 @@
+Metadata-Version: 2.4
+Name: gru-bot
+Version: 0.1.0
+Summary: Gru CLI with built-in WeChat Bot connection and automatic Skill synchronization
+License-Expression: MIT
+Project-URL: Homepage, https://gru.bot
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+License-File: NOTICE-TENCENT
+Requires-Dist: gru-bot-skills==0.1.0
+Requires-Dist: qrcode[pil]==8.2
+Dynamic: license-file
+
+# Gru CLI
+
+`@gru-bot/cli` and `gru-bot` provide one-shot WeChat iLink text transport and a durable local SQLite inbox. It can pull inbound messages, show the earliest message without a reply intent, report inbox and send-intent state, and reply once to a specific inbound message.
+
+This release is the text transport component of [Gru](https://gru.bot). It does not run an Agent, schedule background work, read personal WeChat history, or process media. The npm CLI runs on Node.js 24+ and requires no Python or native addon compilation. The PyPI CLI runs on Python 3.11+ without Node.js. Both include WeChat Bot QR association and the Gru Skill.
+
+## Install
+
+Choose either npm name; they provide the same `gru` command and functionality:
+
+```bash
+npm install -g @gru-bot/cli
+# Alternative name:
+npm install -g gru-bot
+```
+
+Use one global installation at a time because both provide `gru`. The Gru Skill is bundled and installed automatically for detected Agent hosts; installation failures are reported. A host that appears later is handled on the next CLI invocation. `gru skills status` reports the actual state, including deferred installation when no supported host is found. `gru skills disable` and `gru skills remove` stop automatic restoration.
+
+For Python, choose `pip install gru-bot-cli` or the equivalent `pip install gru-bot`. Both provide `gru`; install one alternative at a time. pip has no postinstall hook, so the first CLI invocation syncs the bundled Skill. The Python QR renderer uses the declared `qrcode[pil]==8.2` dependency. The standalone Skill packages are `@gru-bot/skills` on npm and `gru-bot-skills` on PyPI. Personal WeChat history reading is provided separately by `@gru-bot/wx` or `gru-bot-wx`, using an explicitly configured existing local reader.
+
+## WeChat Bot association
+
+Both CLI distributions include the default Bot connection. Use an explicit private directory and follow bounded steps:
+
+```bash
+gru bot --state-dir /absolute/private/association inspect
+gru bot --state-dir /absolute/private/association start
+gru bot --state-dir /absolute/private/association poll
+gru bot --state-dir /absolute/private/association install
+```
+
+`start` reuses a complete binding or live QR. When it returns a new private `qr_image` file, open that image and scan it in the authorized account's WeChat. `poll` makes one status request. Expired QR codes stop; `start --refresh` requests a replacement only after expiry. For `need_verifycode`, put the phone's pairing digits in an owner-only file and use `poll --code-file /absolute/private/code.txt`. `render` recreates the same live QR after interruption.
+
+`install` is an explicit configuration command: it appends confirmed exports to an existing literal `.zprofile`, or the file selected with `--profile`, and refuses conflicting or dynamic shell configuration. Open a fresh login shell afterwards. Package installation and ordinary CLI startup do not pair accounts, send messages or write credentials.
+
+Association state and profile installation currently require POSIX owner permissions (macOS/Linux). Unsupported ownership checks fail explicitly. Updated Python and Node association commands share a fence; an older Python association command does not participate, so use one association implementation at a time when continuing older trials. A lock left during acquisition remains explicit for manual reconciliation.
+
+## Configuration
+
+Use an existing authorized WeChat Bot association. Supply the exact server-returned account ID, user ID, HTTPS base URL, and credential through your shell environment:
+
+- `GRU_ILINK_ACCOUNT_ID`: `ilink_bot_id`.
+- `GRU_ILINK_USER_ID`: `ilink_user_id`.
+- `GRU_ILINK_BASE_URL`: HTTPS `baseurl`.
+- `GRU_ILINK_TOKEN`: Bot credential; needed for `pull` and `reply`.
+- `GRU_ILINK_ROUTE_TAG`: optional confirmed server route tag.
+
+Keep credentials and the database private. The Bot API URL comes from the confirmed association response; `gru.bot` is the product homepage, not the API endpoint. QR pairing is built in; personal WeChat history reading is a separate capability.
+
+## Commands
+
+Choose an explicit private database path. `status` and `next` use local state; they require the account, user and base URL, but do not require a token or contact the server. An empty new database is created with owner-only permissions.
+
+```bash
+gru --help
+gru --db /absolute/private/inbox.sqlite status
+gru --db /absolute/private/inbox.sqlite next
+gru --db /absolute/private/inbox.sqlite pull
+gru --db /absolute/private/inbox.sqlite reply 123 'approved reply text'
+```
+
+`pull` makes one network poll and persists raw receipts, inbox messages and the cursor. `reply` makes a real send to the exact associated sender of that inbound message. Run these only for an authorized account and approved content. Missing binding or credentials stop the command with exit code 2.
+
+`next` returns a limited JSON projection without reply/media credentials. It does not claim a message for a worker; use one consumer. Unsupported media remains marked as unprocessed.
+
+Each reply stores an intent before sending. Accepted, rejected and unknown intents all prevent automatic resend for that inbound ID. `status` lists unresolved intents. An accepted server receipt does not prove recipient-side display. Unknown sends need manual reconciliation, not automatic retries. Do not delete or replace your existing inbox to retry a send.
+
+## License and source
+
+MIT. Protocol, headers and text payloads are adapted from Tencent's [openclaw-weixin](https://github.com/Tencent/openclaw-weixin) at commit `24de5c9eb0dd5e595d7e2d090ed8a3f82870d42c`; its copyright and MIT notice are included. The local SQLite persistence and one-shot CLI share the same SQLite schema and message/send-intent rules across the Node npm and Python PyPI distributions.

gru_bot-0.1.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+gru_associate.py,sha256=OEXObM4Cm-c1aeeH_pKGTeu1SEPokDWw-bREjI7Obbg,15532
+gru_bot_cli.py,sha256=Z29cBPPjV-hCbxpkY8bpO_ugucn4X6QUHILN4MQv33A,2061
+gru_weixin.py,sha256=Tnig1OipVUhWS9i9HrU3coNDvL7Uu3n6KuAcIjW72Xs,17222
+gru_bot-0.1.0.dist-info/licenses/LICENSE,sha256=NmyNkf8pkfTQguVPpkcUPVQ0b9qxa2tmZBjTm_f2tso,1035
+gru_bot-0.1.0.dist-info/licenses/NOTICE-TENCENT,sha256=fx6M8JnPA958d14z6X48lQw6Vqlha7TeaxTTyRG8VXM,1301
+gru_bot-0.1.0.dist-info/METADATA,sha256=EIoUoJXg1Y7HGzhT31cTP73-zCO_YzsBXl5m3k-FuiA,6231
+gru_bot-0.1.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+gru_bot-0.1.0.dist-info/entry_points.txt,sha256=Zim-9nPIqNvPHNoMa5Snq1KeXgQM8k1GvVL3M9fUh5o,41
+gru_bot-0.1.0.dist-info/top_level.txt,sha256=nmBFELlJAgdwy4ARriqx8dnw_pUVRRCzMDd3o_pD1Lw,37
+gru_bot-0.1.0.dist-info/RECORD,,

gru_bot-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

gru_bot-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+gru = gru_bot_cli:main

gru_bot-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,20 @@
+MIT License
+
+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.

gru_bot-0.1.0.dist-info/licenses/NOTICE-TENCENT

@@ -0,0 +1,27 @@
+Tencent is pleased to support the open source community by making openclaw-weixin available. 
+
+Copyright (C) 2026 Tencent.  All rights reserved. 
+
+openclaw-weixin is licensed under the MIT.
+
+
+Terms of the MIT:
+--------------------------------------------------------------------
+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.

gru_bot-0.1.0.dist-info/top_level.txt

@@ -0,0 +1,3 @@
+gru_associate
+gru_bot_cli
+gru_weixin

gru_bot_cli.py

@@ -0,0 +1,57 @@
+"""Gru CLI facade over the canonical Bot transport and association modules."""
+import json
+import sys
+
+HELP = """Gru CLI — built-in WeChat Bot text transport
+Usage: gru --db PATH {status|next|pull|reply MESSAGE_ID TEXT}
+  --db PATH   explicit private SQLite inbox
+  status      show local counts and unresolved send intents
+  next        read earliest inbound without a reply intent; does not claim it
+  pull        one server poll; persist inbox and cursor atomically
+  reply       send once to the named inbound's exact associated sender
+  bot         built-in QR association: gru bot --help
+  skills      install/status/disable/remove the Gru Skill
+  --help      show this help
+"""
+
+
+def main(args=None):
+    args = list(sys.argv[1:] if args is None else args)
+    import gru_bot_skills
+    if args and args[0] == "skills":
+        if args[1:] in (["--help"], ["-h"]):
+            print("Usage: gru skills [install|sync|status|remove|disable|enable]")
+            return 0
+        try:
+            print(json.dumps(gru_bot_skills.main(args[1:])))
+            return 0
+        except (OSError, ValueError, RuntimeError) as error:
+            print(f"[gru skills] {error}", file=sys.stderr)
+            return 2
+    try:
+        gru_bot_skills.startup_sync()
+    except (OSError, ValueError, RuntimeError) as error:
+        print(f"[gru skills] {error}", file=sys.stderr)
+        return 2
+    if not args or args in (["--help"], ["-h"]):
+        print(HELP)
+        return 0
+    previous = sys.argv
+    try:
+        if args[0] == "bot":
+            sys.argv = [previous[0] + " bot", *args[1:]]
+            try:
+                import gru_associate
+            except ImportError:
+                print(json.dumps({"state": "failed", "error_type": "UnsupportedPlatform", "message_sent": False}))
+                return 2
+            return gru_associate.main()
+        sys.argv = [previous[0], *args]
+        import gru_weixin
+        return gru_weixin.main()
+    finally:
+        sys.argv = previous
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

gru_weixin.py

@@ -0,0 +1,337 @@
+# /// script
+# requires-python = ">=3.11"
+# dependencies = []
+# ///
+"""One-shot iLink transport. No login, model invocation, scheduler or notification."""
+from __future__ import annotations
+
+import argparse
+import base64
+from dataclasses import dataclass
+import json
+import os
+from pathlib import Path
+import secrets
+import sqlite3
+from typing import Callable
+from urllib.error import HTTPError, URLError
+from urllib.parse import urlsplit
+from urllib.request import HTTPRedirectHandler, Request, build_opener
+import uuid
+
+
+class BoundaryError(ValueError):
+    """Missing or conflicting binding; no network request should be made."""
+
+
+def json_text(value):
+    return json.dumps(value, ensure_ascii=False, separators=(",", ":"))
+
+
+def wire_id(value):
+    # Python's JSON integers are arbitrary precision; floats are never accepted.
+    if isinstance(value, bool) or not isinstance(value, (str, int)):
+        raise BoundaryError("message_id must be a uint64 string or integer")
+    value = str(value)
+    if not value.isascii() or not value.isdecimal() or not 0 <= int(value) < 2**64:
+        raise BoundaryError("message_id must be uint64")
+    return str(int(value))
+
+
+@dataclass(frozen=True)
+class Binding:
+    account: str  # exact ilink_bot_id returned by the authorized association
+    user: str     # exact ilink_user_id returned by that association
+    base_url: str
+
+    def __post_init__(self):
+        parts = urlsplit(self.base_url)
+        if (not self.account or not self.user or parts.scheme != "https" or not parts.netloc
+                or parts.username or parts.password or parts.query or parts.fragment):
+            raise BoundaryError("require exact server account/user IDs and an HTTPS base URL")
+
+    @classmethod
+    def from_env(cls):
+        keys = ("GRU_ILINK_ACCOUNT_ID", "GRU_ILINK_USER_ID", "GRU_ILINK_BASE_URL")
+        values = [os.environ.get(key, "") for key in keys]
+        if not all(values):
+            raise BoundaryError("missing binding environment: " + ", ".join(keys))
+        return cls(values[0], values[1], values[2].rstrip("/") + "/")
+
+
+class NoRedirect(HTTPRedirectHandler):
+    def redirect_request(self, req, fp, code, msg, headers, newurl):
+        return None  # never forward the bearer credential to a redirected target
+
+
+class Transport:
+    def __init__(self, binding: Binding, token: str, open_request: Callable | None = None):
+        if not token.strip():
+            raise BoundaryError("missing GRU_ILINK_TOKEN")
+        self.binding, self.token = binding, token.strip()
+        self.open_request = open_request or build_opener(NoRedirect).open
+
+    def post(self, endpoint: str, body: dict, timeout: int):
+        # Header and message shapes adapted from the pinned Tencent implementation.
+        body = dict(body, base_info={"channel_version": "2.4.9", "bot_agent": "GruPrototype/0.1"})
+        headers = {
+            "Content-Type": "application/json", "AuthorizationType": "ilink_bot_token",
+            "Authorization": "Bearer " + self.token,
+            "X-WECHAT-UIN": base64.b64encode(str(secrets.randbits(32)).encode()).decode(),
+            "iLink-App-Id": "bot", "iLink-App-ClientVersion": str((2 << 16) | (4 << 8) | 9),
+        }
+        route = os.environ.get("GRU_ILINK_ROUTE_TAG")
+        if route:
+            headers["SKRouteTag"] = route
+        req = Request(self.binding.base_url.rstrip("/") + "/" + endpoint,
+                      json_text(body).encode(), headers, method="POST")
+        with self.open_request(req, timeout=timeout) as response:
+            data = json.loads(response.read().decode())
+        if not isinstance(data, dict):
+            raise BoundaryError("response must be an object")
+        return data
+
+
+def response_state(response):
+    if not isinstance(response, dict):
+        return "unknown"
+    for key in ("ret", "errcode"):
+        value = response.get(key)
+        if isinstance(value, int) and not isinstance(value, bool) and value != 0:
+            return "rejected"
+    if type(response.get("ret")) is int and response["ret"] == 0:
+        if "errcode" not in response or type(response["errcode"]) is int and response["errcode"] == 0:
+            return "accepted"
+    return "unknown"
+
+
+class Inbox:
+    def __init__(self, path: Path, binding: Binding):
+        self.binding = binding
+        missing = []
+        directory = path.parent
+        while not directory.exists():
+            missing.append(directory)
+            directory = directory.parent
+        for directory in reversed(missing):
+            directory.mkdir(mode=0o700, exist_ok=True)
+        try:
+            fd = os.open(path, os.O_CREAT | os.O_EXCL | os.O_WRONLY, 0o600)
+        except FileExistsError:
+            pass  # preserve permissions of existing user-selected state
+        else:
+            os.close(fd)
+        self.db = sqlite3.connect(path, timeout=10)
+        self.db.row_factory = sqlite3.Row
+        self.db.execute("PRAGMA journal_mode=WAL")
+        self.db.execute("PRAGMA synchronous=FULL")
+        self.db.executescript("""
+        CREATE TABLE IF NOT EXISTS accounts (
+          account TEXT PRIMARY KEY, user TEXT NOT NULL, base_url TEXT NOT NULL, cursor TEXT NOT NULL);
+        CREATE TABLE IF NOT EXISTS inbox (
+          account TEXT NOT NULL, message_id TEXT NOT NULL, sender TEXT NOT NULL,
+          context_token TEXT, raw TEXT NOT NULL, ordinal INTEGER PRIMARY KEY AUTOINCREMENT,
+          UNIQUE(account, message_id));
+        CREATE TABLE IF NOT EXISTS replies (
+          account TEXT NOT NULL, message_id TEXT NOT NULL, client_id TEXT NOT NULL,
+          request TEXT NOT NULL, state TEXT NOT NULL, response TEXT,
+          PRIMARY KEY(account, message_id));
+        CREATE TABLE IF NOT EXISTS pull_receipts (
+          receipt_id TEXT PRIMARY KEY, account TEXT NOT NULL,
+          expected_cursor TEXT NOT NULL, raw TEXT NOT NULL, applied INTEGER NOT NULL);
+        """)
+        with self.db:
+            self.db.execute("INSERT OR IGNORE INTO accounts VALUES (?, ?, ?, '')",
+                            (binding.account, binding.user, binding.base_url))
+            row = self.db.execute("SELECT * FROM accounts WHERE account=?", (binding.account,)).fetchone()
+            if row["user"] != binding.user or row["base_url"] != binding.base_url:
+                raise BoundaryError("account binding conflicts with persisted server identity")
+
+    def close(self):
+        self.db.close()
+
+    def cursor(self):
+        return self.db.execute("SELECT cursor FROM accounts WHERE account=?",
+                               (self.binding.account,)).fetchone()[0]
+
+    def ingest(self, response, expected_cursor):
+        # Retain the actual server receipt even when subsequent validation fails.
+        # A new empty cursor is not proof the server will replay an earlier response.
+        receipt_id = uuid.uuid4().hex
+        with self.db:
+            self.db.execute("INSERT INTO pull_receipts VALUES(?,?,?,?,0)",
+                            (receipt_id, self.binding.account, expected_cursor, json_text(response)))
+        state = response_state(response)
+        # Official GetUpdates omits zero-valued status fields. Require positive
+        # payload evidence; absent/malformed status alone is never success.
+        if (state == "unknown" and isinstance(response, dict)
+                and "ret" not in response and "errcode" not in response
+                and isinstance(response.get("msgs"), list)
+                and isinstance(response.get("get_updates_buf"), str)
+                and response["get_updates_buf"]):
+            state = "accepted"
+        if state != "accepted":
+            raise BoundaryError("pull rejected or unconfirmed; cursor unchanged")
+        msgs, returned_cursor = response.get("msgs", []), response.get("get_updates_buf")
+        if not isinstance(msgs, list) or returned_cursor is not None and not isinstance(returned_cursor, str):
+            raise BoundaryError("pull requires a message list and opaque string cursor")
+        # Upstream monitor retains its previous cursor for omitted/empty buffers.
+        new_cursor = returned_cursor or expected_cursor
+        # BEGIN IMMEDIATE plus compare prevents concurrent pulls overwriting newer cursors.
+        try:
+            self.db.execute("BEGIN IMMEDIATE")
+            if self.cursor() != expected_cursor:
+                raise BoundaryError("cursor changed during pull; discard stale response")
+            added = 0
+            for msg in msgs:
+                if not isinstance(msg, dict):
+                    raise BoundaryError("invalid message object")
+                mid = wire_id(msg.get("message_id"))
+                if (msg.get("from_user_id") != self.binding.user
+                        or msg.get("to_user_id") != self.binding.account
+                        or msg.get("message_type") != 1 or msg.get("group_id")):
+                    raise BoundaryError("inbound is not the exact associated account/user direct message")
+                token = msg.get("context_token")
+                if token is not None and not isinstance(token, str):
+                    raise BoundaryError("invalid context_token")
+                raw = json_text(msg)
+                old = self.db.execute("SELECT raw FROM inbox WHERE account=? AND message_id=?",
+                                      (self.binding.account, mid)).fetchone()
+                if old and old[0] != raw:
+                    raise BoundaryError("same message ID has changed payload; manual reconciliation required")
+                if not old:
+                    self.db.execute("INSERT INTO inbox(account,message_id,sender,context_token,raw) VALUES(?,?,?,?,?)",
+                                    (self.binding.account, mid, msg["from_user_id"], token, raw))
+                    added += 1
+            self.db.execute("UPDATE accounts SET cursor=? WHERE account=?", (new_cursor, self.binding.account))
+            self.db.execute("UPDATE pull_receipts SET applied=1 WHERE receipt_id=?", (receipt_id,))
+            self.db.commit()
+            return {"state": "stored", "inserted": added}
+        except BaseException:
+            self.db.rollback()
+            raise
+
+    def next(self):
+        row = self.db.execute("""SELECT i.* FROM inbox i LEFT JOIN replies r
+          ON i.account=r.account AND i.message_id=r.message_id
+          WHERE i.account=? AND r.message_id IS NULL ORDER BY i.ordinal LIMIT 1""",
+                              (self.binding.account,)).fetchone()
+        if not row:
+            return None
+        raw = json.loads(row["raw"])
+        items = raw.get("item_list", [])
+        texts = [item["text_item"]["text"] for item in items if isinstance(item, dict)
+                 and item.get("type") == 1 and isinstance(item.get("text_item"), dict)
+                 and isinstance(item["text_item"].get("text"), str)] if isinstance(items, list) else []
+        names = {0: "none", 1: "text", 2: "image", 3: "voice", 4: "file", 5: "video",
+                 11: "tool_call_start", 12: "tool_call_result"}
+        types = [names.get(item.get("type"), "unknown")
+                 if isinstance(item, dict) and type(item.get("type")) is int else "unknown"
+                 for item in items] if isinstance(items, list) else ["unknown"]
+        # Consumption projection is a whitelist; raw reply/media credentials stay in SQLite.
+        return {"account": row["account"], "message_id": row["message_id"], "sender": row["sender"],
+                "text": "\n".join(texts), "item_types": types, "media_processed": False}
+
+    def reply(self, transport: Transport, message_id: str, text: str):
+        if transport.binding != self.binding:
+            raise BoundaryError("transport and inbox binding differ")
+        mid = wire_id(message_id)
+        if not text or not text.strip():
+            raise BoundaryError("reply text must be nonempty")
+        try:
+            self.db.execute("BEGIN IMMEDIATE")
+            existing = self.db.execute("SELECT state FROM replies WHERE account=? AND message_id=?",
+                                       (self.binding.account, mid)).fetchone()
+            if existing:
+                self.db.rollback()
+                return {"state": existing[0], "attempted": False, "message_id": mid}
+            inbound = self.db.execute("SELECT * FROM inbox WHERE account=? AND message_id=?",
+                                      (self.binding.account, mid)).fetchone()
+            if not inbound or inbound["sender"] != self.binding.user or not inbound["context_token"]:
+                raise BoundaryError("no bound inbound message with a usable context_token")
+            body = {"msg": {"from_user_id": "", "to_user_id": inbound["sender"],
+                    "client_id": "gru-" + uuid.uuid4().hex, "message_type": 2, "message_state": 2,
+                    "item_list": [{"type": 1, "text_item": {"text": text}}],
+                    "context_token": inbound["context_token"]}}
+            self.db.execute("INSERT INTO replies VALUES(?,?,?,?,?,?)",
+                            (self.binding.account, mid, body["msg"]["client_id"], json_text(body),
+                             "unknown", None))
+            self.db.commit()  # durable intent precedes any network side effect
+        except BaseException:
+            self.db.rollback()
+            raise
+        state, result = "unknown", {"reason": "transport_failure_or_unconfirmed_receipt"}
+        try:
+            response = transport.post("ilink/bot/sendmessage", body, timeout=15)
+            state = response_state(response)
+            result = {"ret": response.get("ret"), "errcode": response.get("errcode")}
+            if "message_id" in response:
+                result["message_id"] = wire_id(response["message_id"])
+        except HTTPError as err:
+            state = "rejected" if err.code in (400, 401, 403, 404, 405, 422) else "unknown"
+            result = {"http_status": err.code}
+        except (URLError, TimeoutError, OSError, ValueError):
+            state = "unknown"  # malformed or precision-unsafe receipt is not success
+        try:
+            with self.db:
+                self.db.execute("UPDATE replies SET state=?,response=? WHERE account=? AND message_id=?",
+                                (state, json_text(result), self.binding.account, mid))
+        except sqlite3.Error:
+            state = "unknown"  # durable pre-send intent remains; never automatically resend
+        return {"state": state, "attempted": True, "message_id": mid}
+
+    def status(self):
+        counts = dict(self.db.execute("SELECT state,count(*) FROM replies WHERE account=? GROUP BY state",
+                                     (self.binding.account,)).fetchall())
+        intents = [dict(row) for row in self.db.execute(
+            "SELECT message_id,client_id,state FROM replies WHERE account=? AND state!=?",
+            (self.binding.account, "accepted"))]
+        return {"account": self.binding.account, "cursor_present": bool(self.cursor()),
+                "inbox": self.db.execute("SELECT count(*) FROM inbox WHERE account=?",
+                                         (self.binding.account,)).fetchone()[0], "replies": counts,
+                "unresolved_intents": intents}
+
+
+def main():
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--db", type=Path, required=True, help="explicit prototype SQLite file")
+    commands = parser.add_subparsers(dest="command", required=True)
+    commands.add_parser("pull", help="one long-poll; preserve inbox and cursor atomically")
+    commands.add_parser("next", help="read earliest inbound without a reply intent; does not claim it")
+    commands.add_parser("status", help="show local counts, including unknown send intents")
+    reply = commands.add_parser("reply", help="send once, using the named inbound's exact sender/token")
+    reply.add_argument("message_id")
+    reply.add_argument("text")
+    args = parser.parse_args()
+    inbox = None
+    try:
+        binding = Binding.from_env()
+        transport = None
+        if args.command in ("pull", "reply"):
+            transport = Transport(binding, os.environ.get("GRU_ILINK_TOKEN", ""))
+        inbox = Inbox(args.db, binding)
+        if args.command == "pull":
+            cursor = inbox.cursor()
+            result = inbox.ingest(transport.post("ilink/bot/getupdates", {"get_updates_buf": cursor}, 35), cursor)
+        elif args.command == "next":
+            result = inbox.next()
+        elif args.command == "reply":
+            result = inbox.reply(transport, args.message_id, args.text)
+        else:
+            result = inbox.status()
+        print(json_text(result))
+        return 2 if isinstance(result, dict) and result.get("state") in ("unknown", "rejected") else 0
+    except (ValueError, URLError, TimeoutError, OSError, sqlite3.Error) as err:
+        # Do not print exceptions that may embed credential-bearing URLs/responses.
+        result = {"state": "failed", "error_type": type(err).__name__}
+        if isinstance(err, BoundaryError):
+            result["reason"] = str(err)
+        print(json_text(result))
+        return 2
+    finally:
+        if inbox:
+            inbox.close()
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())