wraithd 0.0.1__tar.gz

wraithd-0.0.1/.gitignore

@@ -0,0 +1,19 @@
+# Python
+__pycache__/
+*.py[cod]
+.venv/
+build/
+dist/
+*.egg-info/
+.pytest_cache/
+.ruff_cache/
+.coverage
+
+# The built web UI, copied in by scripts/release.sh
+src/wraithd/ui/
+
+# Claude Code worktrees (sessions working in isolation)
+.claude/worktrees/
+
+# Eval reports and run homes (python -m wraithd.evals)
+eval-results/

wraithd-0.0.1/LICENSE

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

wraithd-0.0.1/PKG-INFO

@@ -0,0 +1,161 @@
+Metadata-Version: 2.5
+Name: wraithd
+Version: 0.0.1
+Summary: A personal agent that runs on your own machine.
+Project-URL: Homepage, https://github.com/shaharishay14/wraithd
+Project-URL: Documentation, https://github.com/shaharishay14/wraithd/tree/main/docs
+Project-URL: Source, https://github.com/shaharishay14/wraithd
+Project-URL: Issues, https://github.com/shaharishay14/wraithd/issues
+Project-URL: Changelog, https://github.com/shaharishay14/wraithd/releases
+Author: Shahar Ishay
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agent,ai,assistant,daemon,llm,local-first,mcp,self-hosted,telegram
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Environment :: Web Environment
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Communications :: Chat
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Utilities
+Requires-Python: >=3.12
+Requires-Dist: croniter>=6
+Requires-Dist: httpx>=0.28.1
+Requires-Dist: keyring>=25
+Requires-Dist: openai-agents[litellm]>=0.24.0
+Requires-Dist: openpyxl>=3.1
+Requires-Dist: pypdf>=5
+Requires-Dist: pyyaml>=6
+Requires-Dist: starlette>=0.40
+Requires-Dist: tiktoken>=0.14
+Requires-Dist: uvicorn>=0.30
+Provides-Extra: browser
+Requires-Dist: playwright>=1.48; extra == 'browser'
+Provides-Extra: whisper
+Requires-Dist: faster-whisper>=1.1; extra == 'whisper'
+Description-Content-Type: text/markdown
+
+<p align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/shaharishay14/wraithd/main/docs/assets/hero-dark.webp">
+    <img alt="wraithd." src="https://raw.githubusercontent.com/shaharishay14/wraithd/main/docs/assets/hero-light.webp" width="100%">
+  </picture>
+</p>
+
+<p align="center">
+  <strong>A personal AI agent that runs on your own machine.</strong><br>
+  One package, your model, and you talk to it from the terminal, a local web page or Telegram.
+</p>
+
+<p align="center">
+  <a href="https://github.com/shaharishay14/wraithd/actions/workflows/ci.yml"><img alt="CI" src="https://github.com/shaharishay14/wraithd/actions/workflows/ci.yml/badge.svg"></a>
+  <a href="https://github.com/shaharishay14/wraithd/blob/main/LICENSE"><img alt="License: MIT" src="https://img.shields.io/badge/license-MIT-111111.svg"></a>
+  <img alt="Python 3.12+" src="https://img.shields.io/badge/python-3.12%2B-111111.svg">
+  <img alt="macOS and Linux" src="https://img.shields.io/badge/platform-macOS%20%7C%20Linux-111111.svg">
+</p>
+
+wraithd is an agent you own, the way you own your notes: one process on your Mac or Linux machine, its state as
+plain files and one SQLite file in `~/.wraithd/`, nothing sent anywhere but your model provider (or nowhere, with a
+local model through Ollama), Telegram if you pair it, and web searches. The rules that must hold (the permission
+gate, taint tracking, the egress guard, budgets) live in code, not in the prompt, and every step of every run is an
+event you can inspect.
+
+> **Status:** v0.0.1, in development. The package installs below work after the first PyPI release; until then,
+> [install from a checkout](#from-a-checkout).
+
+## Install
+
+Needs macOS or Linux. *After the first release:*
+
+```sh
+curl -LsSf https://raw.githubusercontent.com/shaharishay14/wraithd/main/scripts/install.sh | sh
+```
+
+The script ([read it first](https://github.com/shaharishay14/wraithd/blob/main/scripts/install.sh)) installs
+[uv](https://docs.astral.sh/uv/) if it's missing, then wraithd, without sudo. Or pick your tool:
+
+```sh
+uv tool install --python 3.12 wraithd     # uv (downloads Python 3.12 if needed)
+pipx install wraithd                      # pipx, with a Python 3.12+
+brew install shaharishay14/tap/wraithd    # Homebrew
+pip install wraithd                       # into a venv you manage, Python 3.12+
+```
+
+Extras: `wraithd[whisper]` transcribes voice notes locally, `wraithd[browser]` adds a real browser.
+
+### From a checkout
+
+```sh
+git clone https://github.com/shaharishay14/wraithd
+cd wraithd
+uv sync
+uv run wraithd onboard
+```
+
+## Quick start
+
+```sh
+wraithd onboard     # model and key, Telegram, the background service, the web UI link
+wraithd chat        # talk to it in the terminal
+wraithd doctor      # check everything, with a fix for anything wrong
+```
+
+`onboard` asks for a provider (OpenAI, Anthropic, Ollama or any OpenAI-compatible endpoint), stores the key in your
+OS keychain, optionally sets up your own Telegram bot and installs a background service that starts at login. Run
+it again any time: Enter keeps what's set.
+
+## What it does
+
+- **Chat where you are.** The terminal, a local web page, and a Telegram bot that answers only you: photos, voice
+  notes and files included.
+- **Memory you can read.** Markdown notes you can open and edit, and a short profile of you in every conversation.
+- **Skills.** Morning brief, inbox triage, research report, meeting prep, weekly review, loaded only when a request
+  matches, plus your own rules.
+- **Your apps as MCP servers.** Mail, calendar, notes, anything: `wraithd mcp add`. Read-only tools run; anything
+  else asks first, in the terminal, the web UI or Telegram.
+- **Schedules and reminders.** Cron or one-time, in your timezone, firing with the terminal closed.
+- **The web and files.** Searches with your model provider's own search (no extra key) and reads PDF, Word and
+  spreadsheets.
+- **Safe by construction.** Unattended runs only do writes you pre-approved; text from an email or page can't
+  redirect them; keys stay in the keychain and out of the model's sight; the API listens on 127.0.0.1 with a
+  token. `wraithd audit` checks the live setup against these rules.
+- **Every step inspectable.** `wraithd runs show <id>` prints a run's timeline: each model call, tool call,
+  approval and result.
+
+## Docs
+
+[All docs](https://github.com/shaharishay14/wraithd/blob/main/docs/README.md) ·
+[Install and run](https://github.com/shaharishay14/wraithd/blob/main/docs/install.md) ·
+[Connect your apps](https://github.com/shaharishay14/wraithd/blob/main/docs/mcp.md) ·
+[Security](https://github.com/shaharishay14/wraithd/blob/main/docs/security.md) ·
+[Evals](https://github.com/shaharishay14/wraithd/blob/main/docs/evals.md) ·
+[Releasing](https://github.com/shaharishay14/wraithd/blob/main/docs/release.md) ·
+[Roadmap](https://github.com/shaharishay14/wraithd/blob/main/PLAN.md)
+
+## Development
+
+```sh
+uv sync
+uv run pytest        # offline: no model, key, ~/.wraithd, keychain or service is touched
+uv run ruff check
+scripts/release.sh   # the web UI (frontend/) built into the wheel, in dist/
+```
+
+The web UI is in `frontend/` and the landing page in `site/` (`npm ci && npm run dev` in either). Issues and pull
+requests are welcome; please keep tests offline.
+
+The harness design follows Michael Livshits' writing on agent harnesses
+([michaellivs.com/blog](https://michaellivs.com/blog)). [MIT](https://github.com/shaharishay14/wraithd/blob/main/LICENSE) © 2026 Shahar Ishay
+
+<p align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/shaharishay14/wraithd/main/docs/assets/fog-dark.webp">
+    <img alt="" src="https://raw.githubusercontent.com/shaharishay14/wraithd/main/docs/assets/fog-light.webp" width="100%">
+  </picture>
+</p>

wraithd-0.0.1/README.md

@@ -0,0 +1,118 @@
+<p align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/shaharishay14/wraithd/main/docs/assets/hero-dark.webp">
+    <img alt="wraithd." src="https://raw.githubusercontent.com/shaharishay14/wraithd/main/docs/assets/hero-light.webp" width="100%">
+  </picture>
+</p>
+
+<p align="center">
+  <strong>A personal AI agent that runs on your own machine.</strong><br>
+  One package, your model, and you talk to it from the terminal, a local web page or Telegram.
+</p>
+
+<p align="center">
+  <a href="https://github.com/shaharishay14/wraithd/actions/workflows/ci.yml"><img alt="CI" src="https://github.com/shaharishay14/wraithd/actions/workflows/ci.yml/badge.svg"></a>
+  <a href="https://github.com/shaharishay14/wraithd/blob/main/LICENSE"><img alt="License: MIT" src="https://img.shields.io/badge/license-MIT-111111.svg"></a>
+  <img alt="Python 3.12+" src="https://img.shields.io/badge/python-3.12%2B-111111.svg">
+  <img alt="macOS and Linux" src="https://img.shields.io/badge/platform-macOS%20%7C%20Linux-111111.svg">
+</p>
+
+wraithd is an agent you own, the way you own your notes: one process on your Mac or Linux machine, its state as
+plain files and one SQLite file in `~/.wraithd/`, nothing sent anywhere but your model provider (or nowhere, with a
+local model through Ollama), Telegram if you pair it, and web searches. The rules that must hold (the permission
+gate, taint tracking, the egress guard, budgets) live in code, not in the prompt, and every step of every run is an
+event you can inspect.
+
+> **Status:** v0.0.1, in development. The package installs below work after the first PyPI release; until then,
+> [install from a checkout](#from-a-checkout).
+
+## Install
+
+Needs macOS or Linux. *After the first release:*
+
+```sh
+curl -LsSf https://raw.githubusercontent.com/shaharishay14/wraithd/main/scripts/install.sh | sh
+```
+
+The script ([read it first](https://github.com/shaharishay14/wraithd/blob/main/scripts/install.sh)) installs
+[uv](https://docs.astral.sh/uv/) if it's missing, then wraithd, without sudo. Or pick your tool:
+
+```sh
+uv tool install --python 3.12 wraithd     # uv (downloads Python 3.12 if needed)
+pipx install wraithd                      # pipx, with a Python 3.12+
+brew install shaharishay14/tap/wraithd    # Homebrew
+pip install wraithd                       # into a venv you manage, Python 3.12+
+```
+
+Extras: `wraithd[whisper]` transcribes voice notes locally, `wraithd[browser]` adds a real browser.
+
+### From a checkout
+
+```sh
+git clone https://github.com/shaharishay14/wraithd
+cd wraithd
+uv sync
+uv run wraithd onboard
+```
+
+## Quick start
+
+```sh
+wraithd onboard     # model and key, Telegram, the background service, the web UI link
+wraithd chat        # talk to it in the terminal
+wraithd doctor      # check everything, with a fix for anything wrong
+```
+
+`onboard` asks for a provider (OpenAI, Anthropic, Ollama or any OpenAI-compatible endpoint), stores the key in your
+OS keychain, optionally sets up your own Telegram bot and installs a background service that starts at login. Run
+it again any time: Enter keeps what's set.
+
+## What it does
+
+- **Chat where you are.** The terminal, a local web page, and a Telegram bot that answers only you: photos, voice
+  notes and files included.
+- **Memory you can read.** Markdown notes you can open and edit, and a short profile of you in every conversation.
+- **Skills.** Morning brief, inbox triage, research report, meeting prep, weekly review, loaded only when a request
+  matches, plus your own rules.
+- **Your apps as MCP servers.** Mail, calendar, notes, anything: `wraithd mcp add`. Read-only tools run; anything
+  else asks first, in the terminal, the web UI or Telegram.
+- **Schedules and reminders.** Cron or one-time, in your timezone, firing with the terminal closed.
+- **The web and files.** Searches with your model provider's own search (no extra key) and reads PDF, Word and
+  spreadsheets.
+- **Safe by construction.** Unattended runs only do writes you pre-approved; text from an email or page can't
+  redirect them; keys stay in the keychain and out of the model's sight; the API listens on 127.0.0.1 with a
+  token. `wraithd audit` checks the live setup against these rules.
+- **Every step inspectable.** `wraithd runs show <id>` prints a run's timeline: each model call, tool call,
+  approval and result.
+
+## Docs
+
+[All docs](https://github.com/shaharishay14/wraithd/blob/main/docs/README.md) ·
+[Install and run](https://github.com/shaharishay14/wraithd/blob/main/docs/install.md) ·
+[Connect your apps](https://github.com/shaharishay14/wraithd/blob/main/docs/mcp.md) ·
+[Security](https://github.com/shaharishay14/wraithd/blob/main/docs/security.md) ·
+[Evals](https://github.com/shaharishay14/wraithd/blob/main/docs/evals.md) ·
+[Releasing](https://github.com/shaharishay14/wraithd/blob/main/docs/release.md) ·
+[Roadmap](https://github.com/shaharishay14/wraithd/blob/main/PLAN.md)
+
+## Development
+
+```sh
+uv sync
+uv run pytest        # offline: no model, key, ~/.wraithd, keychain or service is touched
+uv run ruff check
+scripts/release.sh   # the web UI (frontend/) built into the wheel, in dist/
+```
+
+The web UI is in `frontend/` and the landing page in `site/` (`npm ci && npm run dev` in either). Issues and pull
+requests are welcome; please keep tests offline.
+
+The harness design follows Michael Livshits' writing on agent harnesses
+([michaellivs.com/blog](https://michaellivs.com/blog)). [MIT](https://github.com/shaharishay14/wraithd/blob/main/LICENSE) © 2026 Shahar Ishay
+
+<p align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/shaharishay14/wraithd/main/docs/assets/fog-dark.webp">
+    <img alt="" src="https://raw.githubusercontent.com/shaharishay14/wraithd/main/docs/assets/fog-light.webp" width="100%">
+  </picture>
+</p>

wraithd-0.0.1/docs/README.md

@@ -0,0 +1,82 @@
+# The harness
+
+The Agents SDK runs the loop: call the model, run the tools it asks for, feed the results back. Everything
+around that loop is the harness: what the model is given, what it may do, when it stops, what it remembers,
+and how we know what happened. These notes explain each part and why it's built that way.
+
+The harness is ported from agent-studio (a multi-user web app on EC2), where these notes started. Each note
+says what changed for running on one person's laptop.
+
+## One-liner
+
+> wraithd's harness logs every step of a run as an event, derives the run's state from that log, and uses
+> it to stop runaway runs, steer the model with short reminders, and enforce safety rules in code. The model
+> gets a small prompt and pulls in tools, memory and skills only when it needs them.
+
+## The picture
+
+```
+            ┌──────────────────────── Harness (src/wraithd/core/) ──────────────────────┐
+ input ───▶ │  Event log ──▶ Views ──▶ Stop rules / Reminders ──▶ what the model sees next  │ ──▶ model
+ (terminal, │      ▲                                                          │             │
+ Telegram,  │      └──────────────── tool calls and results ◀─────────────────┘             │
+ schedule)  │                                                                                │
+            │  Permission gate (hard rules)   Disclosure (app actions, memory, skills, web)  │
+            │  Secret redaction · Egress checks · Budgets                                    │
+            └────────────────────────────────────────────────────────────────────────────────┘
+                       │
+                       ▼
+               Store (src/wraithd/store/): events, conversations, schedules, approvals in one SQLite file
+```
+
+## The notes
+
+| Note | In one line |
+|---|---|
+| [First launch](first-launch.md) | Start here: on your Mac, a Google Calendar, Telegram, locked down; stop and remove it all. |
+| [Lockdown](lockdown.md) | The safest setup: a separate macOS user, one config block, two tool lists, approvals, and what's not protected. |
+| [One run](run.md) | `run()`, config and keys, providers, the terminal chat. |
+| [Keys](keys.md) | Keychain, else environment variables: an env file, systemd or a password manager such as 1Password. |
+| [Event log](event-log.md) | Every step is an event; the run's state is a query over them. |
+| [Security](security.md) | Hard rules in code: the gate, taint tracking, egress, redaction, budgets. |
+| [From EC2 to laptop](ec2-to-laptop.md) | What changed in the threat model, the mechanism and test for each, and `audit`. |
+| [Compaction](compaction.md) | The newest 10 messages word for word, older ones folded into a stored summary. |
+| [System reminders](reminders.md) | Short hints at the moment they're relevant; nudges, not rules. |
+| [Progressive disclosure](progressive-disclosure.md) | Search → View → Use, so the prompt doesn't grow with every tool. |
+| [Memory](memory.md) | Markdown files, a keyword map instead of vectors, BM25, distill, trust labels. |
+| [Skills](skills.md) | One line in the prompt, instructions on demand, the owner's rules on top, `model: strong`. |
+| [Workspace files](files.md) | List, read (PDF, Word, spreadsheets too), write, edit in one folder; real-path checks keep everything else out. |
+| [The shell](shell.md) | Off by default; every command asks y/N; never unattended. |
+| [Sandbox](sandbox.md) | Optional Docker sandbox for the shell and opted-in MCP servers: only workspace/files/, no network. |
+| [The web](web.md) | Pages through the egress guard, search through the model provider's own (no extra key), all third-party content. |
+| [Schedules](schedules.md) | Cron or one time in the owner's timezone, approved, fired at most once per slot. |
+| [MCP](mcp.md) | Your apps as MCP servers: secrets per server, discovery, read-only runs, the rest asks. |
+| [Installing and running](install.md) | The release build, `onboard`, the background service, `doctor`, `update`. |
+| [The daemon](daemon.md) | One process: the API and UI, the scheduler, Telegram, MCP, background distill. |
+| [The local API](api.md) | The contract the web UI is built on: token, Origin and Host checks, endpoints. |
+| [Telegram](telegram.md) | A paired owner chat only; strangers ignored; approvals as buttons; photos, voice notes, files. |
+| [The scheduler](scheduler.md) | Due schedules run unattended every minute; the answer goes to the owner. |
+| [One loop, not a team](one-loop.md) | Why there's one agent, and when a sub-agent would be worth it. |
+| [Proof](proof.md) | Unit tests, scripted runs through the real SDK, and replay of recorded runs. |
+| [Evals](evals.md) | Ten golden tasks in a fake world of MCP servers, graded by checks and a judge, cost-capped. |
+| [Seams](seams.md) | The extension points Phase 9 workers plug into: model per purpose, run options, marked blocks, module migrations, periodic jobs, tool-result hooks. |
+| [Review queue](review-queue.md) | Items waiting for the owner (third-party memory writes, later skills and changed MCP tools): `wraithd review`, the API, one short notice. |
+| [Memory provenance](memory-provenance.md) | Where each memory note came from, and why a tainted run's memory writes wait for review. |
+| [Token breakdown](tokens.md) | `wraithd runs tokens <id>`: where a run's input tokens go, part by part. |
+| [Prompt caching](caching.md) | A byte-identical prefix first, everything that changes after it; cache tokens in events and budgets. |
+| [Model per purpose](models.md) | `[models]`: a cheaper model for distill, compaction, heartbeat or subagents; unset means today's model. |
+| [Spilling big output](spill.md) | Big tool results go to a redacted file; the model gets today's preview plus the path. |
+| [Channels](channels.md) | The interface Telegram is built on: owner and pairing, receive, send, approvals. |
+| [WhatsApp options](whatsapp.md) | The Cloud API, a Web bridge or a bridge process: setup, ban risk, and the pick. Not built yet. |
+| [Remote access](remote-access.md) | `tailscale serve` in front of the API on an always-on box; `[remote] allowed_hosts`; the token still required. |
+| [The browser](browser.md) | Headless Chromium behind the egress guard: reads taint, clicks and submits ask, a fresh profile per run. Off by default. |
+| [Subagents](subagents.md) | `delegate`: a child run with its own context, the parent's budget and taint both ways, depth 1. Off by default. |
+| [Skill proposals](skill-proposals.md) | Skills the agent proposes wait in the review queue; tainted ones are flagged. |
+| [Heartbeat](heartbeat.md) | A periodic, read-only check that messages the owner only when something is worth it. Off by default. |
+
+## Where the ideas come from
+
+Most of the design follows Michael Livshits' writing on agent harnesses ([michaellivs.com/blog](https://michaellivs.com/blog)):
+the harness as the layer around the loop, the conversation as an event stream, Search → View → Use, skills as
+progressive disclosure, napkin's memory design, and system reminders. The "one loop" decision follows
+Anthropic's guidance on folding sub-agents into the main loop. Each note links the posts it uses.