Metadata-Version: 2.4
Name: saki-io
Version: 0.1.0
Summary: Saki AI — Live2D avatar app with Copilot/Cursor CLI relay (ACP)
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: agent-client-protocol>=0.8.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"

# saki.io

Saki AI — Live2D avatar app with Copilot/Cursor CLI relay. Planning and goals live in MySpace; this repo is implementation only.

## Install

```bash
uv sync
```

## Run

```bash
uv run saki.io
```

Then open **http://localhost:8000** in your browser. The app uses the [Copilot CLI](https://docs.github.com/en/copilot/how-tos/copilot-cli/set-up-copilot-cli) (e.g. `brew install copilot-cli`) and `agent-client-protocol` for context across messages. If ACP isn't available, the server falls back to one-shot `copilot --prompt "..."`.

## Commands for developers

All commands use [UV](https://docs.astral.sh/uv/):

| Command | Description |
|---------|-------------|
| `uv run saki.io` | Run Saki (default). |
| `uv run saki.io --allow-tools` | Allow Copilot to run commands, read/write files, and use tools (e.g. `gh`). |
| `uv run saki.io -v` | Enable verbose output (session, HTTP, ACP logs). |

Flags can be combined, e.g. `uv run saki.io --allow-tools -v`.

## Structure

- `saki/io/` — Python package
  - `server.py` — HTTP server + setup APIs + `/api/send` → agent backend
  - `app/` — static web app (HTML, CSS, JS) shipped as package data
  - `backend/` — agent backend abstraction (Copilot now; Cursor later)
  - `acp_client.py` — Copilot ACP client (used by CopilotBackend)
  - `bootstrap.py` — .saki.io folder bootstrap
- `tests/` — pytest

## Stack

Plain HTML + JavaScript, no build. Python deps in `pyproject.toml`. Relay uses one `copilot --acp --stdio` session when `agent-client-protocol` is installed.

## Tests

```bash
uv sync --extra dev
uv run pytest tests/ -v
```

Integration test (Copilot + gh): `RUN_ACP_INTEGRATION=1 uv run pytest tests/test_acp_gh_integration.py -v`

## Debugging ACP

If you see "Using one-shot --prompt" and want the single-session (context) mode:

1. Install the ACP client: `uv sync`
2. Ensure Copilot supports ACP: `copilot --acp --stdio` (then Ctrl+C)
3. Run with verbose logs: `uv run saki.io -v` — startup and ACP errors are printed to stderr.
4. To inspect the raw ACP protocol: `SAKI_ACP_LOG=1 uv run saki.io -v` — every JSON-RPC message to/from Copilot is printed.

**"Failed to list models"** — Copilot ACP can't list models (auth/network). Start the server from a **terminal** where `copilot --prompt "hi"` works (same env = same credentials).

## Tool use

By default, Saki rejects all tool use (terminal, file read/write). To allow Copilot to run commands and use tools:

```bash
uv run saki.io --allow-tools
```

### Why does Saki say "tool rejected" when gh/copilot work in tests?

Tests run commands **directly** in the server process. In chat, Copilot uses the **ACP** flow: it asks for permission (we say "allowed"), then it **calls back** into our client. If that follow-up uses a method or param shape we don't support, we return "method not found". With `SAKI_ACP_LOG=1 uv run saki.io -v` you can see the exact ACP messages and adjust `acp_client.py` or backend.
