arkclaw-webchat-cli 0.1.0__tar.gz → 0.3.0__tar.gz

arkclaw_webchat_cli-0.3.0/PKG-INFO

@@ -0,0 +1,197 @@
+Metadata-Version: 2.4
+Name: arkclaw-webchat-cli
+Version: 0.3.0
+Summary: CLI to chat with an ArkClaw EE space's Claw over enterprise SSO — zero permanent AK/SK.
+Author: ArkClaw Team
+Keywords: arkclaw,cli,ee,openclaw,sso,sts
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: MacOS
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.10
+Requires-Dist: keyring>=24.0
+Requires-Dist: typer>=0.12.0
+Requires-Dist: websockets>=12.0
+Provides-Extra: dev
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pytest>=7.4; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# arkclaw
+
+**Chat with your ArkClaw claws (agents) from the terminal — log in with your
+own SSO identity, no passwords, no permanent keys.** Works the same for a human
+at a prompt and for another agent/script (`--json` + exit codes).
+
+```bash
+arkclaw init        # one-time interactive setup (asks only what it can't auto-detect)
+arkclaw login       # browser SSO
+arkclaw agents      # list the claws you can chat
+arkclaw chat ci-xxxxxxxx
+```
+
+---
+
+## What it can do
+
+- **Log in as you** — browser SSO (PKCE), short-lived token, auto-refresh. No AK/SK, no client secret, nothing permanent on disk but a token in your OS keychain.
+- **List your agents** — `arkclaw agents` shows the claws you can chat with.
+- **Chat** — interactive REPL or one-shot `-m`, streaming token-by-token, with a live "what's it doing" spinner and tool-event trace.
+- **Talk to a specific claw** — by id (`chat ci-...`) or by name (`chat 答疑助手`).
+- **Manage a claw's files** — read/write its managed workspace files (`AGENTS.md`, `SOUL.md`, `MEMORY.md`, …) with `ls` / `pull` / `push`.
+- **Fan out** — send one message to many claws in parallel.
+- **Be scripted** — every command takes `--json` (one clean `{ok,data,error}` envelope on stdout) and returns a typed exit code.
+
+Two transports, picked at login: **openclaw** (your claws, the default) and **a2a** (an agent endpoint).
+
+---
+
+## Install
+
+```bash
+pip install arkclaw-webchat-cli          # provides the `arkclaw` command
+```
+
+From source:
+
+```bash
+git clone <repo> && cd ee-claw
+uv venv && uv pip install -e .
+```
+
+---
+
+## Quick start
+
+```bash
+# 0. one-time setup — interactive. Asks for your space address and (only if the
+#    space doesn't already publish them) the CLI client + STS role. Saved to
+#    ~/.arkclaw/defaults.json so you never type them again.
+arkclaw init
+
+# 1. log in (a browser opens; sign in with SSO)
+arkclaw login
+
+# 2. see which claws you can talk to
+arkclaw agents
+
+# 3. chat — interactive…
+arkclaw chat ci-xxxxxxxx
+#    …or one-shot:
+arkclaw chat ci-xxxxxxxx -m "用一句话介绍你自己"
+```
+
+`arkclaw init` resolves everything it can from the address (identity pool,
+region) and only prompts for what's missing. Once your space publishes
+auto-discovery, `init` asks for nothing but the address — and you can even skip
+straight to `arkclaw login https://your-space...`. See **[Configuration](#configuration)**.
+
+---
+
+## Commands
+
+| Command | What it does |
+|---|---|
+| `arkclaw init [address]` | One-time interactive setup. Saves the address + (only what isn't auto-discovered) the CLI client and STS role to `~/.arkclaw/defaults.json`, so later commands need no env/flags. |
+| `arkclaw login [space-url]` | Browser SSO login. Uses `init` defaults if you omit the URL. `--transport a2a --endpoint <url>` for an agent endpoint. `--clawid ci-...` sets a default claw. Bare `arkclaw login` re-logs into the previous space. |
+| `arkclaw agents` | List the claws/agents you can chat with. |
+| `arkclaw chat [TARGET] [MSG]` | Chat. `TARGET` = a claw id (`ci-...`), an agent name (from `agents`), or a profile. With `MSG` → one-shot; without → interactive REPL. `-f` attach files, `-o` write the reply, `--session NAME` name the conversation, `--approve-all` auto-approve tool runs. |
+| `arkclaw <name>` | Shortcut: `arkclaw 答疑助手` ≡ `arkclaw chat 答疑助手`. |
+| `arkclaw ls` | List the claw's managed workspace files. |
+| `arkclaw pull <name> [local]` | Download a managed file to local disk. |
+| `arkclaw push <local> [name]` | Write a local text file into a managed file. |
+| `arkclaw fanout "<msg>" --clawid ci-a --clawid ci-b` | Same message to many claws in parallel. |
+| `arkclaw sessions` | Recent chat sessions on this machine. |
+| `arkclaw profile save/use/list` | Named snapshots of the session config (multi-space / multi-claw). |
+| `arkclaw doctor` | Self-check: login freshness, keychain, pool/STS/endpoint reachability. |
+| `arkclaw schema --json` | Machine-readable command surface (for agents/tooling). |
+| `arkclaw claw list/describe/create/delete` | Fleet management on the control plane. |
+
+All commands accept `--clawid ci-...` (where relevant) to target a specific claw, and `--json` for machine output.
+
+---
+
+## Chatting
+
+```bash
+arkclaw chat ci-xxxx                       # REPL with that claw (Ctrl-C: interrupt turn; twice: exit)
+arkclaw chat ci-xxxx -m "你好"             # one-shot
+arkclaw chat 答疑助手 -m "怎么部署"         # by name (names come from `arkclaw agents`)
+echo "$DATA" | arkclaw chat ci-xxxx --json -m "总结" | jq -r .data.reply   # piped, machine
+arkclaw chat ci-xxxx -f notes.md -m "review" -o out.md   # attach context, save reply
+```
+
+- **Streaming** on both transports; until the first token a spinner shows elapsed time + the running tool.
+- **Sessions are server-side** — `--session NAME` keeps a named conversation that survives CLI restarts.
+- **Tool approvals**: in a terminal you're prompted; headless it fails closed (deny) unless `--approve-all`; a `~/.arkclaw/cmdpolicy.json` deny-list always wins.
+
+---
+
+## Files
+
+`ls` / `pull` / `push` operate on a claw's **managed workspace files** — its
+"brain": `AGENTS.md`, `SOUL.md`, `MEMORY.md`, `TOOLS.md`, `IDENTITY.md`,
+`USER.md`, `HEARTBEAT.md`. (This is not a general file store — arbitrary
+filenames are rejected.)
+
+```bash
+arkclaw ls                          # list them (defaults to your default claw)
+arkclaw pull SOUL.md                # download SOUL.md here
+arkclaw pull AGENTS.md ./agents.md  # download to a path
+arkclaw push ./agents.md AGENTS.md  # write a managed file
+arkclaw ls --clawid ci-other        # a different claw
+```
+
+---
+
+## For agents / automation
+
+- `--json` → stdout is exactly one `{ok, data, error}` document; progress/streaming goes to stderr. Pipe to `jq`.
+- Exit codes: `0` ok · `1` api · `2` validation · `3` auth · `4` network · `5` internal.
+- Headless never blocks: `--json` / piped stdin refuse the interactive REPL; tool approvals fail closed.
+- `arkclaw schema --json` describes every command + option for programmatic discovery.
+
+---
+
+## Identity & security
+
+- **Identity-through, zero permanent secrets.** Browser PKCE (S256, public client, loopback) → a short-lived `id_token` that *is your user identity* (same as the web app), auto-refreshed. The claw sees you, not a shared key.
+- **openclaw** path exchanges that token (via a least-privilege STS role that can do exactly `GetClawInstanceChatToken`) for a one-time ChatToken, then connects over wss. **a2a** presents the token directly to the agent's gateway.
+- Tokens live in the **OS keychain** (0600 file fallback). The config file holds only non-secret routing. Every upstream error is **redacted** (tokens / AK-SK) before display.
+
+---
+
+## Configuration
+
+`login` resolves config in this order: **explicit flag → `ARKCLAW_*` env →
+the space's published discovery → `arkclaw init` defaults → derived from the
+address**. You normally only type the address.
+
+**The easy way — `arkclaw init`** asks once (interactively) for whatever the
+space doesn't yet auto-publish, and saves it. After that, just `arkclaw login`.
+
+**The env way** (scripts/CI, or instead of `init`) — supply the same non-secret
+values via env:
+
+| Env | Purpose |
+|---|---|
+| `ARKCLAW_CLIENT_ID` | The CLI's public OAuth client id for the pool. |
+| `ARKCLAW_ROLE_TRN` | STS role that mints the ChatToken (openclaw). |
+| `ARKCLAW_REGION` / `ARKCLAW_SPACE_ID` | Override region / space (usually auto). |
+
+Other config: `~/.arkclaw/defaults.json` (`init` answers, 0600), `~/.arkclaw/session.json` (routing, 0600), `~/.arkclaw/cmdpolicy.json` (tool-approval allow/deny), OS keychain (tokens).
+
+> **Escape hatch (admin/test):** `arkclaw login <url> --transport openclaw --static-creds` uses `VOLCENGINE_ACCESS_KEY`/`SECRET_KEY` from the env instead of SSO — convenient for CI, but it's account-level keys, not identity-through.
+
+---
+
+## Notes
+
+- `ls`/`pull`/`push` and a bare `chat` use your **default claw** (set at login, or the last one you opened in the browser); override with `--clawid` (or `chat ci-...`).
+- File commands cover the claw's **managed** files only; arbitrary file drop isn't exposed by the API.
+- Nothing is hardcoded per space — the CLI reads what the space serves.

arkclaw_webchat_cli-0.3.0/README.md

@@ -0,0 +1,173 @@
+# arkclaw
+
+**Chat with your ArkClaw claws (agents) from the terminal — log in with your
+own SSO identity, no passwords, no permanent keys.** Works the same for a human
+at a prompt and for another agent/script (`--json` + exit codes).
+
+```bash
+arkclaw init        # one-time interactive setup (asks only what it can't auto-detect)
+arkclaw login       # browser SSO
+arkclaw agents      # list the claws you can chat
+arkclaw chat ci-xxxxxxxx
+```
+
+---
+
+## What it can do
+
+- **Log in as you** — browser SSO (PKCE), short-lived token, auto-refresh. No AK/SK, no client secret, nothing permanent on disk but a token in your OS keychain.
+- **List your agents** — `arkclaw agents` shows the claws you can chat with.
+- **Chat** — interactive REPL or one-shot `-m`, streaming token-by-token, with a live "what's it doing" spinner and tool-event trace.
+- **Talk to a specific claw** — by id (`chat ci-...`) or by name (`chat 答疑助手`).
+- **Manage a claw's files** — read/write its managed workspace files (`AGENTS.md`, `SOUL.md`, `MEMORY.md`, …) with `ls` / `pull` / `push`.
+- **Fan out** — send one message to many claws in parallel.
+- **Be scripted** — every command takes `--json` (one clean `{ok,data,error}` envelope on stdout) and returns a typed exit code.
+
+Two transports, picked at login: **openclaw** (your claws, the default) and **a2a** (an agent endpoint).
+
+---
+
+## Install
+
+```bash
+pip install arkclaw-webchat-cli          # provides the `arkclaw` command
+```
+
+From source:
+
+```bash
+git clone <repo> && cd ee-claw
+uv venv && uv pip install -e .
+```
+
+---
+
+## Quick start
+
+```bash
+# 0. one-time setup — interactive. Asks for your space address and (only if the
+#    space doesn't already publish them) the CLI client + STS role. Saved to
+#    ~/.arkclaw/defaults.json so you never type them again.
+arkclaw init
+
+# 1. log in (a browser opens; sign in with SSO)
+arkclaw login
+
+# 2. see which claws you can talk to
+arkclaw agents
+
+# 3. chat — interactive…
+arkclaw chat ci-xxxxxxxx
+#    …or one-shot:
+arkclaw chat ci-xxxxxxxx -m "用一句话介绍你自己"
+```
+
+`arkclaw init` resolves everything it can from the address (identity pool,
+region) and only prompts for what's missing. Once your space publishes
+auto-discovery, `init` asks for nothing but the address — and you can even skip
+straight to `arkclaw login https://your-space...`. See **[Configuration](#configuration)**.
+
+---
+
+## Commands
+
+| Command | What it does |
+|---|---|
+| `arkclaw init [address]` | One-time interactive setup. Saves the address + (only what isn't auto-discovered) the CLI client and STS role to `~/.arkclaw/defaults.json`, so later commands need no env/flags. |
+| `arkclaw login [space-url]` | Browser SSO login. Uses `init` defaults if you omit the URL. `--transport a2a --endpoint <url>` for an agent endpoint. `--clawid ci-...` sets a default claw. Bare `arkclaw login` re-logs into the previous space. |
+| `arkclaw agents` | List the claws/agents you can chat with. |
+| `arkclaw chat [TARGET] [MSG]` | Chat. `TARGET` = a claw id (`ci-...`), an agent name (from `agents`), or a profile. With `MSG` → one-shot; without → interactive REPL. `-f` attach files, `-o` write the reply, `--session NAME` name the conversation, `--approve-all` auto-approve tool runs. |
+| `arkclaw <name>` | Shortcut: `arkclaw 答疑助手` ≡ `arkclaw chat 答疑助手`. |
+| `arkclaw ls` | List the claw's managed workspace files. |
+| `arkclaw pull <name> [local]` | Download a managed file to local disk. |
+| `arkclaw push <local> [name]` | Write a local text file into a managed file. |
+| `arkclaw fanout "<msg>" --clawid ci-a --clawid ci-b` | Same message to many claws in parallel. |
+| `arkclaw sessions` | Recent chat sessions on this machine. |
+| `arkclaw profile save/use/list` | Named snapshots of the session config (multi-space / multi-claw). |
+| `arkclaw doctor` | Self-check: login freshness, keychain, pool/STS/endpoint reachability. |
+| `arkclaw schema --json` | Machine-readable command surface (for agents/tooling). |
+| `arkclaw claw list/describe/create/delete` | Fleet management on the control plane. |
+
+All commands accept `--clawid ci-...` (where relevant) to target a specific claw, and `--json` for machine output.
+
+---
+
+## Chatting
+
+```bash
+arkclaw chat ci-xxxx                       # REPL with that claw (Ctrl-C: interrupt turn; twice: exit)
+arkclaw chat ci-xxxx -m "你好"             # one-shot
+arkclaw chat 答疑助手 -m "怎么部署"         # by name (names come from `arkclaw agents`)
+echo "$DATA" | arkclaw chat ci-xxxx --json -m "总结" | jq -r .data.reply   # piped, machine
+arkclaw chat ci-xxxx -f notes.md -m "review" -o out.md   # attach context, save reply
+```
+
+- **Streaming** on both transports; until the first token a spinner shows elapsed time + the running tool.
+- **Sessions are server-side** — `--session NAME` keeps a named conversation that survives CLI restarts.
+- **Tool approvals**: in a terminal you're prompted; headless it fails closed (deny) unless `--approve-all`; a `~/.arkclaw/cmdpolicy.json` deny-list always wins.
+
+---
+
+## Files
+
+`ls` / `pull` / `push` operate on a claw's **managed workspace files** — its
+"brain": `AGENTS.md`, `SOUL.md`, `MEMORY.md`, `TOOLS.md`, `IDENTITY.md`,
+`USER.md`, `HEARTBEAT.md`. (This is not a general file store — arbitrary
+filenames are rejected.)
+
+```bash
+arkclaw ls                          # list them (defaults to your default claw)
+arkclaw pull SOUL.md                # download SOUL.md here
+arkclaw pull AGENTS.md ./agents.md  # download to a path
+arkclaw push ./agents.md AGENTS.md  # write a managed file
+arkclaw ls --clawid ci-other        # a different claw
+```
+
+---
+
+## For agents / automation
+
+- `--json` → stdout is exactly one `{ok, data, error}` document; progress/streaming goes to stderr. Pipe to `jq`.
+- Exit codes: `0` ok · `1` api · `2` validation · `3` auth · `4` network · `5` internal.
+- Headless never blocks: `--json` / piped stdin refuse the interactive REPL; tool approvals fail closed.
+- `arkclaw schema --json` describes every command + option for programmatic discovery.
+
+---
+
+## Identity & security
+
+- **Identity-through, zero permanent secrets.** Browser PKCE (S256, public client, loopback) → a short-lived `id_token` that *is your user identity* (same as the web app), auto-refreshed. The claw sees you, not a shared key.
+- **openclaw** path exchanges that token (via a least-privilege STS role that can do exactly `GetClawInstanceChatToken`) for a one-time ChatToken, then connects over wss. **a2a** presents the token directly to the agent's gateway.
+- Tokens live in the **OS keychain** (0600 file fallback). The config file holds only non-secret routing. Every upstream error is **redacted** (tokens / AK-SK) before display.
+
+---
+
+## Configuration
+
+`login` resolves config in this order: **explicit flag → `ARKCLAW_*` env →
+the space's published discovery → `arkclaw init` defaults → derived from the
+address**. You normally only type the address.
+
+**The easy way — `arkclaw init`** asks once (interactively) for whatever the
+space doesn't yet auto-publish, and saves it. After that, just `arkclaw login`.
+
+**The env way** (scripts/CI, or instead of `init`) — supply the same non-secret
+values via env:
+
+| Env | Purpose |
+|---|---|
+| `ARKCLAW_CLIENT_ID` | The CLI's public OAuth client id for the pool. |
+| `ARKCLAW_ROLE_TRN` | STS role that mints the ChatToken (openclaw). |
+| `ARKCLAW_REGION` / `ARKCLAW_SPACE_ID` | Override region / space (usually auto). |
+
+Other config: `~/.arkclaw/defaults.json` (`init` answers, 0600), `~/.arkclaw/session.json` (routing, 0600), `~/.arkclaw/cmdpolicy.json` (tool-approval allow/deny), OS keychain (tokens).
+
+> **Escape hatch (admin/test):** `arkclaw login <url> --transport openclaw --static-creds` uses `VOLCENGINE_ACCESS_KEY`/`SECRET_KEY` from the env instead of SSO — convenient for CI, but it's account-level keys, not identity-through.
+
+---
+
+## Notes
+
+- `ls`/`pull`/`push` and a bare `chat` use your **default claw** (set at login, or the last one you opened in the browser); override with `--clawid` (or `chat ci-...`).
+- File commands cover the claw's **managed** files only; arbitrary file drop isn't exposed by the API.
+- Nothing is hardcoded per space — the CLI reads what the space serves.

{arkclaw_webchat_cli-0.1.0 → arkclaw_webchat_cli-0.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "arkclaw-webchat-cli"
-version = "0.1.0"
+version = "0.3.0"
 description = "CLI to chat with an ArkClaw EE space's Claw over enterprise SSO — zero permanent AK/SK."
 readme = "README.md"
 requires-python = ">=3.10"
@@ -23,20 +23,28 @@ classifiers = [
 dependencies = [
     "typer>=0.12.0",
     "websockets>=12.0",
+    "keyring>=24.0",
 ]
 
 [project.optional-dependencies]
 dev = [
     "pytest>=7.4",
     "ruff>=0.6",
+    "mypy>=1.10",
 ]
 
 [project.scripts]
-arkclaw-webchat = "ee_claw.cli:main"
+arkclaw = "ee_claw.cli:main"
+arkclaw-webchat = "ee_claw.cli:main"  # legacy alias
 
 [tool.hatch.build.targets.wheel]
 packages = ["src/ee_claw"]
 
+[tool.hatch.build.targets.sdist]
+# Ship ONLY the package (+ auto: pyproject, README). Never publish the internal
+# docs/ (SRE asks, well-known sample) — they carry real deployment identifiers.
+only-include = ["src/ee_claw"]
+
 [tool.ruff]
 line-length = 100
 target-version = "py310"
@@ -45,3 +53,12 @@ src = ["src", "tests"]
 [tool.ruff.lint]
 select = ["E", "W", "F", "I", "UP", "B"]
 ignore = ["E501"]
+
+[tool.ruff.lint.per-file-ignores]
+# typer's API *is* function calls in argument defaults.
+"src/ee_claw/cli.py" = ["B008"]
+
+[tool.mypy]
+python_version = "3.10"
+ignore_missing_imports = true
+check_untyped_defs = true

arkclaw_webchat_cli-0.3.0/src/ee_claw/attachments.py

@@ -0,0 +1,81 @@
+"""Composable input: collect stdin / files / directories into Attachments.
+
+Caps are explicit and every drop is reported (no silent truncation — a "we
+covered everything" that didn't is worse than a visible limit)."""
+
+from __future__ import annotations
+
+import mimetypes
+import pathlib
+
+from ee_claw.errors import ValidationError
+from ee_claw.transport.base import Attachment
+
+MAX_FILE_BYTES = 64 * 1024
+MAX_TOTAL_BYTES = 256 * 1024
+MAX_FILES = 32
+
+
+def collect_files(paths: list[str]) -> tuple[list[Attachment], list[str]]:
+    """Read files (and directories, shallow-recursively) into attachments.
+    Returns ``(attachments, notices)`` — notices describe everything that was
+    truncated or skipped, for the human stream."""
+    notices: list[str] = []
+    candidates: list[pathlib.Path] = []
+    for raw in paths:
+        p = pathlib.Path(raw).expanduser()
+        if not p.exists():
+            raise ValidationError(f"文件不存在: {raw}")
+        if p.is_dir():
+            # Exclude any path with a hidden COMPONENT below the requested dir
+            # (not just hidden leaves): rglob descends into .git/ and .ssh/,
+            # whose contents are exactly the secrets that must never ride
+            # along. relative_to(p) keeps a user-supplied hidden base
+            # (e.g. -f ~/.config/proj) workable.
+            inner = sorted(
+                f
+                for f in p.rglob("*")
+                if f.is_file()
+                and not any(part.startswith(".") for part in f.relative_to(p).parts)
+            )
+            candidates.extend(inner)
+        else:
+            candidates.append(p)
+
+    if len(candidates) > MAX_FILES:
+        notices.append(f"超出 {MAX_FILES} 个文件上限,丢弃了 {len(candidates) - MAX_FILES} 个")
+        candidates = candidates[:MAX_FILES]
+
+    attachments: list[Attachment] = []
+    total = 0
+    for f in candidates:
+        try:
+            content = f.read_bytes()
+        except OSError as e:
+            notices.append(f"读不了 {f}: {e.__class__.__name__}")
+            continue
+        if len(content) > MAX_FILE_BYTES:
+            notices.append(f"{f.name} 截断到 {MAX_FILE_BYTES // 1024}KB(原 {len(content)} 字节)")
+            content = content[:MAX_FILE_BYTES]
+        if total + len(content) > MAX_TOTAL_BYTES:
+            notices.append(f"总量超出 {MAX_TOTAL_BYTES // 1024}KB,从 {f.name} 起丢弃")
+            break
+        total += len(content)
+        mime = mimetypes.guess_type(f.name)[0] or "application/octet-stream"
+        attachments.append(Attachment(name=f.name, content=content, mime=mime))
+    return attachments, notices
+
+
+def inline_attachments(message: str, files: tuple[Attachment, ...] | list[Attachment]) -> tuple[str, list[str]]:
+    """Render text attachments as context blocks appended to the message (for
+    transports without native file parts). Returns ``(message, skipped_names)``
+    — binary attachments can't be inlined and are reported, not dropped silently."""
+    blocks = [message]
+    skipped: list[str] = []
+    for att in files:
+        text = att.text
+        if text is None:
+            skipped.append(att.name)
+            continue
+        blocks.append(f"\n\n--- 文件: {att.name} ---\n{text}")
+    return "".join(blocks), skipped