agentina 0.1.0

package/LICENSE

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

package/README.md

@@ -0,0 +1,136 @@
+# agentina
+
+**How parties will work together.**
+
+Every working relationship today runs on emailed attachments, shared passwords, and blind trust: the client zips the folder, the accountant gets the bank login, the IT helper takes over the whole screen. agentina replaces that pattern. Each party keeps their own machine and their own AI assistants; a relationship is an **invite** plus exactly the access it needs — *this folder, read-only, for a month* — enforced by the giver's machine, watchable in an audit trail both sides keep, revocable in one click, and self-destructing when the engagement ends.
+
+**Pick what you're doing — the console guides both sides:**
+
+| | |
+|---|---|
+| 🧑‍💻 **Freelancer ↔ Client** | Deliver a project without emailing files back and forth. |
+| 🧾 **Accountant ↔ Small business** | Monthly books without a single attachment — ask the bookkeeper assistant instead. |
+| 🏢 **Agency ↔ Client** | Status on demand, staging access per sprint — nothing standing. |
+| 🛠 **IT helper ↔ Family** | Help someone's computer for an hour — they watch every move, then it's over. |
+
+No accounts. No cloud in the middle. No telemetry. If Claude is installed, your assistants think; if not, everything else still works and the console shows the one command to add it.
+
+```
+  agentina demo — freelancer ↔ client, one trust boundary, loopback only
+
+  ✓ pair — Amal joined "Badis (client)" — directional tokens exchanged
+  ✓ invite replay rejected — the redeemed link is worthless
+  ✓ connection test — Amal→Badis 1ms · Badis→Amal 1ms
+  ✓ deny before grant — task without a grant → 403 no-grant
+  ✓ grant — Badis → Amal: agent "files", fs:project-docs (ro)
+  ✓ scoped read — "Redesign the checkout flow. Budget: 4 weeks. …"
+  ✓ path escape denied — read ../secret.txt → 403
+  ✓ ungranted agent denied — task to "echo" → agent-not-granted
+  ✓ forged token denied — GET /ping with a forged token → 401
+  ✓ grant revoked — after revoke, the same read → 403
+  ✓ audit trail — 10 entries, 6 denials (pair, ping, task, grant-create, auth-denied)
+```
+
+Try it in 30 seconds (no keys, no config):
+
+```bash
+npx agentina demo
+```
+
+## Why
+
+Multi-agent frameworks connect machines that all belong to **one** operator — trust is a shared secret, and any authenticated peer can invoke any agent. The moment two *different* owners want their agents to collaborate, you need more:
+
+- **Parties, not just peers.** Every node is owned by a party; every inbound request is attributed to one before it runs.
+- **Directional credentials.** Pairing mints two independent tokens — one per direction. Revoke one party without touching the rest. Invite links carry a one-time token, never a permanent secret.
+- **Pairing alone grants nothing.** Access is a **Grant**, authored and enforced by the granting side: "this party may invoke these agents, scoped to this directory / repo / server / skill." Read-only means read-only — `..` traversal and symlink escapes fail closed.
+- **Audit as a product.** Tasks, pairings, connection tests, grant changes, and *denials* — recorded with the party they were attributed to.
+
+Built on the Linux Foundation's [A2A protocol](https://github.com/a2aproject/A2A) for agent cards and task exchange. Network-agnostic: a peer is any reachable URL — Tailscale, WireGuard, headscale, or plain WAN + TLS.
+
+## How it works
+
+> **First time? Follow [the playlist](docs/tutorials/README.md)** — eight short episodes from install to the full security model, each one filmable as a YouTube tutorial. Start solo with [episode 01 — your own AI assistant](docs/tutorials/01-your-own-assistant.md), or jump to [episode 02 — connect two people](docs/tutorials/02-connect-two-people.md). The security model is documented in [SECURITY.md](SECURITY.md).
+
+```bash
+# Party A (the freelancer) — bind your overlay-network IP so B can reach you
+agentina init --name "Amal"
+agentina start --bind 100.84.12.7     # tailscale ip -4; omit --bind for local-only demos
+agentina invite                       # → agentina://join/… (one-time, 15 min)
+
+# Party B (the client), on their own machine
+agentina init --name "Badis"
+agentina start
+agentina join "agentina://join/…"     # redeems the invite, mints directional tokens
+agentina test "Amal"                  # authenticated connection test
+
+# The client decides exactly what the freelancer's agents may touch:
+agentina grant --to "Amal" --agent files --fs ./project-docs --mode ro
+agentina grants                       # list / audit what you've extended
+agentina revoke gr_…                  # ends it instantly
+
+# The freelancer asks the client's agent (within what was granted):
+agentina ask "Badis" read brief.txt --agent files
+```
+
+## Channels — talk to the mesh where you already are
+
+Mention an agent in a comment or a chat and it answers — including agents on the *other side* of a trust boundary. The router resolves `@name` to a local agent or a paired party's skill; cross-boundary tasks carry your party token and **the remote side enforces its grants** — a channel mention never bypasses them. A denial comes back as the reply, honestly, and lands in both audit logs.
+
+```bash
+agentina channel telegram --token-env TG_BOT_TOKEN          # DM the bot, or @files read brief.txt
+agentina channel whatsapp --token-env WA_TOKEN --phone-id 1234567890 --verify-env WA_VERIFY
+agentina channel discord --token-env DISCORD_BOT_TOKEN
+agentina channel slack --token-env SLACK_BOT_TOKEN --secret-env SLACK_SIGNING_SECRET
+agentina channel github --token-env GH_BOT_TOKEN --secret-env GH_HOOK_SECRET
+agentina channel gitlab --host https://gitlab.example.com --token-env GL_BOT_TOKEN --secret-env GL_HOOK_SECRET
+# each connection gets its own webhook address — the console shows it with a Copy button
+# full walkthroughs: docs/tutorials/05-channels.md (or the console's built-in guides)
+```
+
+| Channel | Status | How it listens |
+|---|---|---|
+| Telegram | ✓ | Bot API long-poll — no public IP needed |
+| WhatsApp | ✓ | Meta Cloud API webhook, replies as your business number |
+| Discord | ✓ | Gateway websocket (outbound, Node 22+) — no public IP needed |
+| Slack | ✓ | Events API webhook (signed, replay-guarded), replies in-thread |
+| GitHub | ✓ | webhook on issue/PR comments (HMAC-verified), replies as the bot |
+| GitLab | ✓ | webhook on issue/MR comments, replies as the bot |
+| Teams · Trello · Jira | planned | same `ChannelAdapter` contract — each is one small file |
+
+Channels start the moment you save them in the console — paste the token in the form (stored owner-only on your machine; env vars override) and mention an agent. No restart, no terminal.
+
+**Per agent, per channel.** A connection can be bound to one agent (`--agent bookkeeper`, or "Who answers here?" in the console): that bot or number becomes the agent's own face — message it like a person, no @mention needed. Several connections of the same kind coexist (each gets its own webhook address), so agentina is useful **solo**: your own agents, in your own chat apps, before any second party is involved.
+
+Every adapter implements the same 4-method contract (`start`, `stop`, `sendReply`, + a name); routing, mention resolution, mesh hops, and grant enforcement are shared and never reimplemented per channel.
+
+## Packages
+
+| Package | What it is |
+|---|---|
+| `agentina` | The CLI and node daemon. |
+| `@agentina-mesh/protocol` | Wire types: A2A + party/grant extensions. Zero deps. |
+| `@agentina-mesh/peer` | Peer registry, health checks with hysteresis, task exchange, invite codec. |
+| `@agentina-mesh/grants` | Party attribution (`decideAuth`), credentials, audit log. |
+| `@agentina-mesh/node` | The daemon: agent-card, `/task`, pairing handshake, control API. |
+| `@agentina-mesh/console` | The web console each node serves at `/`: pairing, scope picker, grants, live activity. |
+| `@agentina-mesh/channels` | Channel adapters (Telegram, WhatsApp, GitHub, GitLab) + the shared mention router. |
+
+## Roadmap
+
+- **M0 ✓:** pair → connection test → task exchange → deny → revoke → audit.
+- **M1 ✓:** Grants enforced at `/task` (party → allowed agents), `fs`/`skill` scopes with traversal/symlink-proof confinement, grant propose/approve/revoke, Claude Code adapter (cwd jailed to the granted root, tool allowlist derived from the grant mode).
+- **M2 ✓:** Web console — pairing wizard, scope picker, grants dashboard, live monitor. Non-technical users, zero CLI.
+- **M3 ✓:** Sessions — ephemeral agents that self-destruct with their grants (TTL or one click), `ssh`/`repo` scopes (credentials come only from the grant), grant expiry with live countdowns. Full console parity: every action clickable.
+- **Later:** N-party meshes, hub (master-mesh) administration, Ed25519 credentials, relay transport.
+
+## Development
+
+```bash
+pnpm install
+pnpm test        # unit + full two-node integration over real HTTP
+pnpm typecheck
+pnpm demo
+```
+
+MIT.