notion-agent-cli 0.1.1__tar.gz

notion_agent_cli-0.1.1/.claude/skills/notion-agent/SKILL.md

@@ -0,0 +1,132 @@
+---
+name: notion-agent
+description: Ask Notion's ✦ AI / Custom Agent (e.g. Jarvis) via the local `notion-agent` CLI. Use when the user wants a workspace-aware answer from their bound Notion agent, wants to pipe a draft through Notion AI, list their agents / threads, or continue a prior thread. Trigger phrases include "ask Jarvis", "Notion AI", "via the chat panel", "notion-agent", "Custom Agent".
+---
+
+## When to use
+
+- The user wants an answer that depends on **their Notion workspace**
+  (their notes, their Custom Agent's instructions / skill pages) and a
+  public Claude can't see that context.
+- The user mentions a Custom Agent by name ("Jarvis", "the chat panel
+  one", "my Notion agent") — that's a workspace-bound persona, not a
+  general assistant.
+- The user wants to dump a draft into Notion's ✦ AI for them to react
+  to inside Notion (the conversation surfaces in the chat panel under
+  the bound persona).
+
+Skip this skill for general programming / world-knowledge questions —
+answer those directly. Notion's chat costs the user API quota.
+
+## Quick start
+
+```bash
+# One-shot chat — prints the assistant reply to stdout
+notion-agent chat "summarize my last week of project notes"
+
+# Streaming output for long replies
+notion-agent chat --stream "draft a status update from this week's notes"
+
+# Structured JSON (text + usage + thread_id) for piping into other tools
+notion-agent chat --json "what tickets did I close in May?"
+```
+
+Check `notion-agent --help` for the full subcommand list. Six
+subcommands: `init`, `chat`, `doctor`, `models refresh`, `agents list`,
+`threads list`.
+
+## Pre-flight
+
+Before the first call, the user needs an account file at
+`~/.notionagents/notion_account.json`. If chat errors with
+`[account_missing]`:
+
+```bash
+# Paste the full document.cookie string from a logged-in Notion tab
+notion-agent init --cookie "token_v2=...; notion_user_id=...; ..."
+```
+
+`init` auto-extracts `token_v2` / `notion_user_id` / `notion_browser_id`
+from the pasted cookie string. Add `--agent-name "Jarvis"
+--agent-page-id <uuid>` to bind to a Custom Agent so threads surface in
+the chat panel.
+
+If chat errors with `[auth_invalid]`, the `token_v2` cookie expired —
+re-run `init` with a fresh one.
+
+## Multi-turn continuation
+
+```bash
+# Turn 1 — get the thread_id from --json output
+THREAD=$(notion-agent chat --json "start a brainstorm on X" | jq -r .thread_id)
+
+# Turn 2+ — pass --thread-id to continue
+notion-agent chat --thread-id "$THREAD" "now narrow down to 3 ideas"
+notion-agent chat --thread-id "$THREAD" "expand idea 1"
+```
+
+State is stored under `~/.notionagents/threads/<thread-id>.json`.
+The thread's original model is locked — `--model` is ignored on
+continuation. If state is missing the error is `[thread_state_missing]`
+and the user should drop `--thread-id` to start fresh.
+
+## Looking up agent / thread ids
+
+```bash
+notion-agent agents  list --limit 10     # 19-ish agents, page_id + activity
+notion-agent threads list --limit 10     # recent threads, newest first
+notion-agent threads list --agent <id>   # threads under one agent
+```
+
+JSON variants (`--json`) for both. Use `agents list` when the user asks
+to bind a new Custom Agent during `init` — the page_id column is what
+goes into `--agent-page-id`.
+
+## Troubleshooting
+
+```bash
+notion-agent doctor          # human-readable 6-step report
+notion-agent doctor --json   # structured, for cron / automation
+```
+
+`doctor` checks: account file readable, required fields, Custom Agent
+binding (informational), `/loadUserContent` ping, bound space_id still
+in workspace list, user model map present. Each line tagged
+`[ok] / [FAIL] / [..]`.
+
+If Notion rotates internal model ids (the `apricot-sorbet-high` style):
+
+```bash
+notion-agent models refresh   # writes ~/.notionagents/models.json
+```
+
+## Don't
+
+- **Don't paste real `token_v2` values into prompts** — `init` already
+  bound it, and the CLI handles auth transparently. The token is
+  long-lived (~months); only re-run `init` when `doctor` says
+  `[auth_invalid]`.
+- **Don't loop more than ~3 chats per user task** — each call is a real
+  Notion API hit consuming the operator's quota. If a batch run is
+  unavoidable, ask the user first.
+- **Don't write to `~/.notionagents/`** directly — the CLI owns it.
+  Account file, models map, and thread state are all CLI-managed.
+- **Don't switch `--model` mid-thread** — the flag is silently ignored
+  on `--thread-id` continuations because Notion locks the model to
+  turn 1. If the user wants a different model, start a new thread.
+
+## ErrorCode reference (for `--json` consumers)
+
+| Code | Meaning | Action |
+|---|---|---|
+| `account_missing`     | No file at `~/.notionagents/notion_account.json` | Run `init` |
+| `account_invalid`     | File present but missing required fields | Re-run `init` |
+| `auth_invalid`        | 401/403 — `token_v2` expired or rejected | Re-run `init` with fresh cookie |
+| `thread_state_missing`| `--thread-id` used but no saved state | Drop `--thread-id` to start fresh |
+| `premium_required`    | Notion premium feature gated | Tell the user their plan blocks this |
+| `empty_text`          | 200 but empty stream | Likely transient — retry once |
+| `http_error`          | Non-200 from Notion | Likely transient — retry once |
+| `transport`           | Network failure | Check connectivity |
+
+`NotionAgentError.code` is a `StrEnum` — branching on the literal
+string is fine.

notion_agent_cli-0.1.1/.github/workflows/release.yml

@@ -0,0 +1,46 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - 'v*'
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+      - name: Install build tooling
+        run: python -m pip install --upgrade pip build twine
+      - name: Build sdist + wheel
+        run: python -m build
+      - name: Verify metadata + README rendering
+        run: twine check --strict dist/*
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    # Must match the Pending Publisher environment configured on PyPI.
+    # Configure required reviewers on this environment in GitHub repo
+    # settings to gate the upload step.
+    environment:
+      name: pypi
+      url: https://pypi.org/project/notion-agent-cli/
+    permissions:
+      id-token: write   # OIDC token for Trusted Publishing
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1

notion_agent_cli-0.1.1/.github/workflows/test.yml

@@ -0,0 +1,30 @@
+name: Test
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ['3.11', '3.12']
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: pip
+      - name: Install (with dev extra)
+        run: python -m pip install -e ".[dev]"
+      - name: Lint
+        run: ruff check src tests
+      - name: Test
+        run: pytest -q

notion_agent_cli-0.1.1/.gitignore

@@ -0,0 +1,35 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+*.egg-info/
+.eggs/
+build/
+dist/
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.coverage
+htmlcov/
+
+# Virtualenvs
+.venv/
+venv/
+env/
+
+# IDE
+.vscode/
+.idea/
+*.swp
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Notion CLI artifacts (real credentials — never commit)
+notion_account.json
+.notion-agent/
+
+# Local session state (oh-my-claudecode, etc.)
+.omc/

notion_agent_cli-0.1.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 chenyqthu
+
+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.

notion_agent_cli-0.1.1/PKG-INFO

@@ -0,0 +1,245 @@
+Metadata-Version: 2.4
+Name: notion-agent-cli
+Version: 0.1.1
+Summary: Call Notion's reverse-engineered ✦ AI / Custom Agent endpoint from the command line
+Project-URL: Homepage, https://github.com/chenyqthu/notion-agent-cli
+Project-URL: Source, https://github.com/chenyqthu/notion-agent-cli
+Project-URL: Issues, https://github.com/chenyqthu/notion-agent-cli/issues
+Project-URL: Changelog, https://github.com/chenyqthu/notion-agent-cli/releases
+Author: chenyqthu
+License: MIT
+License-File: LICENSE
+Keywords: ai,cli,custom-agent,jarvis,notion
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Communications :: Chat
+Classifier: Topic :: Office/Business
+Requires-Python: >=3.11
+Requires-Dist: brotli>=1.1
+Requires-Dist: httpx>=0.27
+Provides-Extra: dev
+Requires-Dist: fastapi>=0.110; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest-timeout>=2.3; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Requires-Dist: uvicorn[standard]>=0.27; extra == 'dev'
+Provides-Extra: serve
+Requires-Dist: fastapi>=0.110; extra == 'serve'
+Requires-Dist: uvicorn[standard]>=0.27; extra == 'serve'
+Description-Content-Type: text/markdown
+
+# notion-agent-cli
+
+> 把你的 Notion ✦ AI / Custom Agent 变成一条 shell 命令。
+
+A small Python CLI + library that talks **directly** to Notion's internal
+`POST /api/v3/runInferenceTranscript` endpoint using a `token_v2` cookie
+copied from a logged-in browser session. No `notion_manager` Go proxy, no
+account pool — just your own session.
+
+The conversations show up in Notion's ✦ AI chat panel under whichever
+Custom Agent persona you bind (e.g. Jarvis), so you can switch between
+talking to your agent from Notion's UI and from the shell.
+
+## Status
+
+**v0.1.0 — first tagged release.** The library is live-validated against
+Notion's real endpoint and adopted by at least one downstream project
+([NotionAgents](https://github.com/chenyqthu/NotionAgents) uses
+`NotionAgentClient` as its inference backend). See
+[`docs/STATUS.md`](docs/STATUS.md) for the full live-test ledger and
+[`docs/ROADMAP.md`](docs/ROADMAP.md) for what's still planned.
+
+## Install
+
+```bash
+pipx install notion-agent-cli      # recommended — isolated venv, one-line upgrade
+# or
+pip install notion-agent-cli       # if you don't use pipx
+```
+
+For the optional FastAPI HTTP wrapper (`notion-agent serve`):
+
+```bash
+pipx install 'notion-agent-cli[serve]'
+```
+
+For local development from a clone, `pip install -e ".[dev]"`. The
+release flow is in [`docs/RELEASING.md`](docs/RELEASING.md).
+
+## Quickstart
+
+```bash
+# One-shot setup: paste the full `document.cookie` string copied from
+# a logged-in Notion tab (DevTools → Application → Cookies → notion.so,
+# right-click any row → "Copy all as ..."). The CLI extracts token_v2 /
+# notion_user_id / notion_browser_id, calls /api/v3/loadUserContent to
+# fetch workspace metadata, and picks the (only) workspace for you.
+notion-agent init --cookie "notion_browser_id=...; notion_user_id=...; token_v2=v03%3A..."
+
+# Want to keep the cookie out of shell history? Read it from stdin:
+pbpaste | notion-agent init --cookie -
+
+# Chat (returns the full reply after streaming completes).
+notion-agent chat "用一句话确认你在线。"
+```
+
+For Jarvis-style custom agent binding (so threads surface in the ✦ AI
+chat panel under your agent name), grab the agent's instructions page id
+from its URL and pass it to `init`:
+
+```bash
+notion-agent init --cookie "..." \
+                  --agent-name Jarvis \
+                  --agent-page-id 2e115375-830d-8184-bf4d-f427d847c6bc
+```
+
+## CLI surface
+
+```text
+notion-agent init     Bootstrap notion_account.json from a token_v2 cookie.
+notion-agent chat     Send one prompt, print the reply (text / --json / --stream / --ndjson).
+notion-agent doctor   Validate the account file and ping /loadUserContent.
+notion-agent models   refresh — pull the current alias→Notion-id map.
+notion-agent agents   list    — custom agents in the bound workspace.
+notion-agent threads  list    — recent chat threads (filter by --agent).
+notion-agent profile  list / current / use <name> / migrate <name>
+notion-agent serve    Local FastAPI server (optional [serve] extra).
+```
+
+Run `notion-agent <sub> --help` for flag details. Every subcommand
+accepts `--account PATH` to point at a non-default credential file.
+
+## Continuation (multi-turn chats)
+
+`chat` saves per-thread continuation state under
+`~/.notionagents/threads/<thread-id>.json` after every successful turn,
+so the next turn can be a follow-up in the same chat-panel thread:
+
+```bash
+# Turn 1 — capture the thread id.
+THREAD=$(notion-agent chat --json "summarize my day so far" | jq -r .thread_id)
+
+# Turn 2 — reuse it.
+notion-agent chat --thread-id "$THREAD" "now translate it to chinese"
+```
+
+The thread's model is locked to whatever turn 1 chose — passing
+`--model` on a `--thread-id` continuation is silently ignored, since
+mid-thread model switches occasionally make Notion reject the partial
+transcript.
+
+## Multi-workspace profiles
+
+Run `notion-agent init` once per workspace into a named profile file,
+then swap between them with `profile use`:
+
+```bash
+notion-agent init --cookie "..." --account ~/.notionagents/tplink.json
+notion-agent init --cookie "..." --account ~/.notionagents/personal.json
+notion-agent profile use tplink   # symlinks notion_account.json → tplink.json
+notion-agent profile current      # prints "tplink"
+notion-agent profile list         # both, * marks active
+```
+
+If you started before profiles existed, `profile migrate <name>` renames
+your existing `notion_account.json` into a named profile and replaces
+the original with a symlink — non-destructive, no re-init required.
+
+## Local HTTP server
+
+`notion-agent serve` wraps the CLI in a small FastAPI app for
+orchestrators (n8n, Make, internal Go services) that prefer HTTP over
+shell-out. Install with the `[serve]` extra:
+
+```bash
+pip install -e ".[serve]"
+notion-agent serve --host 127.0.0.1 --port 8000
+
+# In another shell:
+curl -sN -X POST localhost:8000/chat \
+     -H 'content-type: application/json' \
+     -d '{"prompt":"hi","stream":true}'   # SSE; data: {"text":"..."} per chunk
+curl -s localhost:8000/healthz
+curl -s localhost:8000/agents
+```
+
+Endpoints: `POST /chat` (blocking JSON or SSE), `GET /healthz` (doctor's
+checks, 200 / 503), `GET /agents`, `GET /threads`. Error codes match
+the library's [`ErrorCode`](src/notion_agent_cli/exceptions.py) taxonomy
+so callers branch on `code` without parsing messages.
+
+## Calling this from an AI agent
+
+Two paths, pick the one that matches your runtime:
+
+- **Claude Code** — the repo ships a skill at
+  [`.claude/skills/notion-agent/`](.claude/skills/notion-agent/). Open
+  this repo (or a downstream project that depends on the CLI) and the
+  skill auto-loads via its frontmatter trigger phrases ("ask Jarvis",
+  "Notion AI", "via the chat panel").
+- **Anything else** (Codex, Gemini, openclaw, your own orchestrator) —
+  read [`docs/AGENTS.md`](docs/AGENTS.md). It has a paste-ready
+  system-prompt snippet at the bottom covering the CLI contract,
+  preflight, error codes, and safety rules in ~40 lines.
+
+Both paths shell out to the same `notion-agent` binary — make sure it
+is on `$PATH` for whatever runtime you use.
+
+## Why this exists
+
+Notion's Custom Agents went paid in May 2026 ($10 / 1k credits,
+30–60 credits per run, Business+ only). Their built-in ✦ AI chat is
+free for any Plus seat but only addressable from the UI — not from a
+cron job, a webhook, or a shell pipe. This CLI bridges that gap by
+mirroring exactly what the SPA sends, so you get the same
+free-quota model from `bash` / `python` / wherever.
+
+Reverse-engineering notes + the captured chat-panel traffic that this
+implementation is built against live in
+[`docs/01-notion-chat-protocol.md`](docs/01-notion-chat-protocol.md).
+
+## Library use
+
+```python
+import asyncio
+from notion_agent_cli import NotionAgentClient
+
+async def main():
+    client = NotionAgentClient("~/.notionagents/notion_account.json")
+    try:
+        resp = await client.complete(prompt="今天周几？")
+        print(resp.text)
+        print(f"usage: in={resp.usage.input_tokens} out={resp.usage.output_tokens}")
+
+        # Reuse the thread for a follow-up:
+        followup = await client.complete(
+            prompt="and yesterday?", thread_id=resp.thread_id,
+        )
+        print(followup.text)
+    finally:
+        await client.aclose()
+
+asyncio.run(main())
+```
+
+Async streaming consumers can pass `on_text_delta=` (sync) or
+`on_text_delta_async=` (coroutine, awaited per chunk — used by the
+FastAPI SSE branch). For raw NDJSON passthrough use
+`client.stream_lines(...)`.
+
+The public surface kept stable across v0.1: `NotionAgentClient`,
+`NotionAgentError`, `ChatResponse`, `TokenUsage`, `ErrorCode`. Sub-modules
+(`transcript`, `ndjson`, `account`, `models`, `profile`, `serve`) are
+importable but their internals can shift between minor releases.
+
+## License
+
+MIT. See [`LICENSE`](LICENSE).