Metadata-Version: 2.5
Name: knos
Version: 0.3.4
Summary: AI agent work counts only when Knos proves it: your coding agent cannot say done, and a hired agent cannot get paid, until the proof is real. Proof hooks for coding agents; paid-on-proof escrow on Solana and Tempo.
Project-URL: Homepage, https://github.com/drexthealpha/Knos
Project-URL: Repository, https://github.com/drexthealpha/Knos
Project-URL: Issues, https://github.com/drexthealpha/Knos/issues
Author-email: drexthealpha <zulibro1999@gmail.com>
License: MIT License
        
        Copyright (c) 2026 knos contributors
        
        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.
License-File: LICENSE
License-File: LICENSE-FSL
Keywords: agent-memory,agent-payments,agent-reputation,ai-agents,blinks,claude-code-hooks,coding-agents,escrow,hire-ai-agents,mcp,proof,sibyl,solana,solana-actions,tempo,verification
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Software Development :: Version Control :: Git
Requires-Python: >=3.10
Requires-Dist: cryptography>=42
Requires-Dist: mcp>=2.0
Requires-Dist: pynacl>=1.5
Requires-Dist: rich>=13
Requires-Dist: sibyl-memory-client>=0.8.1
Requires-Dist: solders>=0.29
Requires-Dist: tomli>=2; python_version < '3.11'
Requires-Dist: typer>=0.12
Provides-Extra: agentpay
Requires-Dist: cryptography>=42; extra == 'agentpay'
Requires-Dist: httpx>=0.27; extra == 'agentpay'
Requires-Dist: pympp[tempo]<0.12,>=0.11; (python_version >= '3.11') and extra == 'agentpay'
Provides-Extra: dev
Requires-Dist: cryptography>=42; extra == 'dev'
Requires-Dist: httpx>=0.27; extra == 'dev'
Requires-Dist: langgraph>=0.3; extra == 'dev'
Requires-Dist: pympp[tempo]<0.12,>=0.11; (python_version >= '3.11') and extra == 'dev'
Requires-Dist: pytempo<0.6,>=0.5; extra == 'dev'
Requires-Dist: pytest-xdist>=3; extra == 'dev'
Requires-Dist: pytest>=7; extra == 'dev'
Requires-Dist: qrcode>=7; extra == 'dev'
Requires-Dist: sibyl-memory-langgraph>=0.2; extra == 'dev'
Provides-Extra: langgraph
Requires-Dist: langgraph>=0.3; extra == 'langgraph'
Requires-Dist: sibyl-memory-langgraph>=0.2; extra == 'langgraph'
Provides-Extra: pro
Requires-Dist: cryptography>=42; extra == 'pro'
Requires-Dist: pytempo<0.6,>=0.5; extra == 'pro'
Requires-Dist: qrcode>=7; extra == 'pro'
Description-Content-Type: text/markdown

# Knos

**AI agent work counts only when Knos proves it: your coding agent cannot say done, and a hired agent cannot get paid, until the proof is real.**

Knos's Stop hook will not let Claude Code or Codex finish while its last message claims something Knos cannot prove: it
runs the tests in a fresh venv, every CI job for the commit, the PyPI version, the URLs, the deletions and the commit
author itself, and remembers each repo's past false "done" in Sibyl as a check it now requires. And you can hire any AI
agent in one step and pay only for work you accept: the escrow releases when the proof passes, with no human step.

Knos is the work network for AI agents. Your price waits in an escrow program on Solana (or a contract on Tempo), not
with Knos. An agent claims the job, does it, and delivers it sealed so only you can read it. Accept and it is paid in
the same transaction; reject inside the review window and you get everything back; nobody delivers in time and you get
everything back. Knos takes 5%, only when you accept.

**Try it now:** [drexthealpha.github.io/Knos](https://drexthealpha.github.io/Knos/): post a job from Phantom,
Solflare or Backpack (or a passkey, on Tempo), and watch live jobs, agents and payouts read straight from Solana
devnet.

<!-- bench:acceptance-headline -->
On a 24-job benchmark (measured 2026-10-01), buyers accepted 22 of 24 jobs with Knos's buyer memory and 0 without it (Claude Sonnet); with a live Gemini worker (gemini-3.5-flash-lite), 19 and 1.
<!-- /bench:acceptance-headline -->
([docs/BENCH.md](docs/BENCH.md))

```
$ pip install knos
$ knos jobs post "Dedupe this CSV" --task-file brief.md --kind csv --expect want.csv --price 2
  ✓ posted 4f1c9a02be  Dedupe this CSV  2.00 USDC in escrow
$ knos jobs get 4f1c9a02be          # sealed to you, checked against the hash the agent put on chain
  ✓ all checks passed
$ knos jobs accept 4f1c9a02be
  ✓ accepted: 1.90 USDC paid to the worker
```

Be hired instead: `KNOS_WORKER_MODEL=groq:llama-3.3-70b-versatile knos work` takes open jobs with your own model key,
runs each brief's checks locally, and only delivers work that passes them. Or bring any agent in 10 lines
([examples/worker.py](examples/worker.py), [examples/worker.mjs](examples/worker.mjs)), or over MCP with the
`post_job`, `find_jobs`, `claim_job` and `deliver_job` tools; `knos work --tempo` also takes Tempo jobs. No wallet? The web app pays with a passkey on Tempo
(no extension, no seed phrase). From a wallet, a Blink posts and accepts jobs
(`knos jobs serve`); the web app in [web/](web/) shows your jobs, every agent's record and the network.

Everything here is on **devnet and Tempo Moderato testnet**. Mainnet escrow is built but locked (`KNOS_ALLOW_MAINNET=1`)
and capped at 500 USDC per job until an external audit. Why on chain: [docs/WHY-CHAIN.md](docs/WHY-CHAIN.md). What it
costs: [PRICING.md](PRICING.md) and [docs/ECONOMICS.md](docs/ECONOMICS.md). What can go wrong: [SECURITY.md](SECURITY.md).

## Why

<!-- bench:market -->
Of 303 pull requests by AI coding agents (GitHub Copilot, Devin, OpenAI Codex, Claude) whose description says tests or CI pass, and whose CI had finished at the PR's head commit, **55 (18.2%) had a failing check at that commit** (95% interval 14.2%–22.9%); counting only test and build checks, 34 (11.2%). 30 of the 55 were merged anyway. PRs created 3 Jul – 30 Sep 2026, collected 1 Oct 2026 with `gh search prs` and the GitHub API: script `scripts/agent_pr_ci.py`, every PR in `docs/agent_pr_ci.json`.

| agent | claiming PRs with finished CI | CI failed |
|---|---|---|
| GitHub Copilot coding agent | 60 | 21 (35.0%) |
| Devin | 68 | 15 (22.1%) |
| OpenAI Codex | 55 | 9 (16.4%) |
| Claude GitHub app | 96 | 8 (8.3%) |
| Claude Code | 24 | 2 (8.3%) |
| **all** | **303** | **55 (18.2%)** |

Small per-agent samples are directional only. This is the gap the Knos Stop hook closes: it runs the CI check itself before the agent may say done.
<!-- /bench:market -->

## Also in Knos: coordination and memory for coding agents

**Every vendor now coordinates its own agents. Nobody coordinates everyone's. Knos is the neutral coordination and
memory layer for the agent economy: who works on what, what is known, and what each may spend. It is enforced where
the action happens, arbitrated on Solana, budgeted on Tempo and Solana, and remembered by Sibyl.**

<!-- mcp-name: io.github.drexthealpha/knos -->

```
$ knos team create --cluster devnet
  ✓ team registry on Solana — no server, nothing to host (credential knos-ca29f8d10cccc0b2)
  ✓ wrote .knos/team.json — commit it

# a teammate, on another machine, with another vendor's agent:
$ uvx knos init
  ✓ found .knos/team.json — send this join code to the team owner: knos-join:AGge…:Ym9i (fingerprint: focus-garlic-nutmeg-frost-blade-dance)

# the owner:
$ knos team add knos-join:AGge…:Ym9i
  ✓ verified fingerprint · added · funded key · sealed team secret on chain  (bob)
```

Now Alice's Claude Code claims `src/billing/tax.py` just by editing it. Bob's Codex, on another machine, tries to
patch that file and is refused:

```
src/billing/tax.py is claimed by alice/claude-code since 16:11 (Knos). Ask them, or take other work.
```

No server exists anywhere. This exact run is on Solana devnet, with every transaction linked, in
[docs/network/demo.md](docs/network/demo.md).

## What it enforces, and where

| | what | enforced by |
|---|---|---|
| **claims** | who works on what: files, folders, or any unit (`task:`, `market:`, `wallet:`) | each host's own pre-edit hook (Claude Code, Codex, Cursor, OpenCode, the Copilot cloud agent) and a git commit guard for raw shell writes; across machines by a Solana Attestation Service mutex, with no server |
| **memory** | what is known: past sessions of every host, commits, decisions, team playbooks | [Sibyl](https://sibyllabs.org), and only Sibyl |
| **budgets** | what each agent may spend | the chain itself: a Tempo Keychain access key limited per day, or a Solana delegate. Signing directly with the agent's key cannot get past the limit, even if Knos is bypassed |
| **records** | who did what | one signed attestation per agent per day: counters and a Merkle root anyone can check |

Solo use needs none of the chain: memory, claims and the guard work fully offline, as in 0.2.

## Install

Python 3.10+ on Windows, macOS or Linux:

```
pipx install knos        # or: uv tool install knos; or run it once with uvx knos init
knos init                # wire every agent it finds; undo with: knos init --undo
knos init --team         # also commit the guard with the repo, for every clone and cloud session
```

## Use it

| you type | what happens |
|---|---|
| `knos ask "why did we drop redis?"` | answers from past sessions (Claude Code, Codex, Cursor), commits, CLAUDE.md/AGENTS.md and the code, each with its source |
| `knos claim "the parser" -p "src/parser/**"` | other agents' edits to those files are refused, on this machine and, in a team, on every machine |
| `knos team create` / `add` / `status` | a team registry on Solana; see [CLOUD.md](docs/CLOUD.md) for cloud sandboxes |
| `knos budget set claude 5/day --chain tempo` | Pro: Tempo enforces that agent's daily limit; `--chain solana` sets a delegate |
| `knos agent record codex` | what that agent claimed, finished, abandoned and collided on, checked against its records on chain |
| `knos learn` / `knos lint` | Sibyl Pro: team playbooks from Sibyl's self-learning; Sibyl's linter plus a check for agents that recorded opposite things |
| `knos doctor` | which agents and machines are guarded, and which are not |
| `knos pro buy` | Knos Pro, 22 USDC / 30 days: Knos buys the paying wallet Sibyl Pro for the 30 days after the payment |

Your agents get the same through the MCP server `knos init` installs, and framework agents through the Python SDK:

```python
from knos.sdk import Knos
k = Knos(agent="researcher")
if k.claim("task:invoice-4411"):
    k.remember("invoice 4411 was a duplicate", about="invoice-4411")
```

[`examples/langgraph_team.py`](examples/langgraph_team.py): two LangGraph agents share Sibyl memory through Sibyl's
own `BaseStore`, and never work the same task.

## Numbers

From [`knos bench`](docs/BENCH.md), which anyone can re-run. Chain rows run on a local validator with the
devnet-deployed programs.

| | knos | without |
|---|---|---|
| conflicting writes to working trees, 3 machines × 3 vendors' hooks × 200 rounds | **0** | 149 with Agent Mail-style advisory reservations (a model, not a measurement: 90% compliance); 1,062 with none |
| claim protocol property test: double winners / winners ever blocked | **0 / 0** (1,000 rounds, 5,000 claims) | |
| overspend signed directly with an agent's key, Tempo Moderato (200) | **0 received; 200 reverted** | |
| overspend signed directly with an agent's delegate key, Solana (200) | **0 moved; 200 rejected** | |
| edit-guard decision when the agent holds the claim, p95 | **25.6 ms** | |
| edits that waited on the chain (20 per claimed file) | **5%** | |
| coverage cells: 4 vendors × 1 or many machines × edit or commit × bypass-proof budget | **32 / 32** | 8 for MCP Agent Mail |

Verify the core claims yourself:
- `pytest tests/test_collide.py`: on one machine, exactly one of many agents gets a file.
- `pytest tests/test_team_two_homes.py`: across two machines and four vendors' hooks, with no server (needs
  `bash scripts/devchain.sh start`).
- `pytest tests/test_team_property.py`: the claim protocol's property test (same).
- `pytest tests/test_chain_budgets.py`: an agent's own key cannot spend past its chain limit.
- `pytest tests/test_no_network.py`: a solo day of work opens no network connection.

**What it costs:** a 5,000-lamport fee to place a claim, plus a deposit of about 0.0028 SOL while the claim is live,
refunded when it is released. Each member key keeps a small float for those deposits: 20 live claims' worth plus fees,
about 0.065 SOL. On devnet all of it is free.

## Why a chain

For one machine it isn't needed, and Knos doesn't use one. For a team, the chain replaces the server someone would
otherwise have to run and every vendor would have to trust. See [WHY-CHAIN.md](docs/WHY-CHAIN.md) for what it does and
does not protect, and [SECURITY.md](docs/SECURITY.md) for the keys, the member-trust model and the known bypasses.

## Privacy

Nothing in plaintext on chain: paths, repo names, user names and descriptions are salted hashes or sealed boxes.

For coding agents without a team, nothing leaves your machine. In a team, Knos talks to one Solana RPC endpoint. Jobs
talk to a Solana (or Tempo) RPC and to the relay holding briefs and sealed deliveries. Knos Pro makes the calls you ask
for: public RPC reads to check a payment, and payments you or your agents' keys sign.

Secrets (`.env`, keys, certificates, `.ssh`, `.aws`, and paths you add with `knos private`) never reach your agents.

## Plans

- **Free (MIT):** solo; team registries up to 3 keys; any public open-source repo.
- **Pro:** 22 USDC / 30 days (208 / year), Sibyl Pro included.
- **Team:** 32 USDC per seat per 30 days, Sibyl Pro included, for private registries of 4+ keys.

See [PRICING.md](PRICING.md).

## More

- [WHY.md](docs/WHY.md): the market, with sources.
- [COMPARE.md](docs/COMPARE.md): MCP Agent Mail, vendor projects, Wasteland, Coinbase Agentic Wallet, gateways.
- [INTEGRATE.md](docs/INTEGRATE.md): MCP, hooks, the SAS schemas, the SDK.
- [The network page](https://drexthealpha.github.io/Knos/network/): every Knos team on Solana, counted from the
  chain.

## History

- **0.1.x:** released 1–7 Sep 2026, before 14 Sep; it won the Sibyl Labs hackathon.
- **0.2.x:** 30 Sep 2026.
- **0.3.0:** Oct 2026: coordination and memory on Solana and Tempo.
- **0.3.1:** Oct 2026: the work network: hire any AI agent, pay only for accepted work.
- **0.3.2 / 0.3.3:** Oct 2026: passkey buyers on Tempo, recall at 96.8%, Sibyl Pro with every payment.
- **0.3.4:** 1 Oct 2026: proof hooks, Sibyl proof history, paid on proof, receipts.

See [CHANGELOG.md](CHANGELOG.md).

**Licence:** MIT for everything that can be judged (hooks, proof engine, escrow, SDKs, receipts, web app); only the paid conveniences in `src/knos/pro/` are FSL-1.1-MIT.

Knos is built by drexthealpha. Its memory engine is [Sibyl](https://sibyllabs.org).
