my-project-public

repository

loading code, commits, and activity

repositories

loading repo index

my-project-public — gitlawb

#1	# Leviathan
#2
#3	Leviathan is the sovereign agent runtime for `solana-clawd`. It is a TypeScript CLI that can spawn a local agent identity, persist shell state under `~/.openclawd`, run a depth-aware pulse loop, call Claude with a constrained tool surface, and bridge into Solana, Clawd Memory, Percolator, and optional payment/A2A rails.
#4
#5	The runtime is intentionally local-first. It stores the agent keypair locally, keeps operational state in local JSON/JSONL files, and treats the Three Laws constitution as an integrity-checked runtime dependency.
#6
#7	## Quick Start
#8
#9	From the repo root:
#10
#11	```bash
#12	npm run leviathan:spawn
#13	npm run leviathan:status
#14	npm run leviathan -- --ticks 3
#15	```
#16
#17	From this folder:
#18
#19	```bash
#20	npm install
#21	npm run spawn
#22	npm run status
#23	npm run run:leviathan -- --ticks 3
#24	```
#25
#26	Required for live inference:
#27
#28	```bash
#29	ANTHROPIC_API_KEY=
#30	CREATOR_PUBKEY=
#31	SOLANA_RPC_URL=https://api.devnet.solana.com
#32	```
#33
#34	Optional:
#35
#36	```bash
#37	HELIUS_API_KEY=
#38	CLAWD_BRAIN_ROOT=../MemeBRain
#39	CLAWD_BRAIN_VAULT=
#40	CLAWD_BRAIN_PYTHON=python3
#41	PERCOLATOR_CLUSTER=devnet
#42	PERCOLATOR_MAINNET=0
#43	```
#44
#45	## What It Does
#46
#47	Leviathan runs a `SENSE -> THINK -> STRIKE -> DRIFT` loop:
#48
#49	1. SENSE: reads local state, balances, recent strikes, shell text, and Clawd Memory recall.
#50	2. THINK: calls Anthropic Claude with the current constitution, depth tier, and allowed tools.
#51	3. STRIKE: executes exactly one selected tool or holds.
#52	4. DRIFT: writes the strike journal, updates local state, and optionally molts `SHELL.md` content.
#53
#54	Depth is determined by local USDC balance:
#55
#56	\| Depth \| Balance \| Pulse \| Tool posture \|
#57	\| --- \| ---: \| ---: \| --- \|
#58	\| `deep` \| `>= 5.00` USDC \| `60s` \| full surface including spawn/molt/transfer \|
#59	\| `shallow` \| `>= 1.00` USDC \| `5m` \| conservative tool/transfer surface \|
#60	\| `shoreline` \| `>= 0.10` USDC \| `15m` \| revenue-focused minimal surface \|
#61	\| `beached` \| `< 0.10` USDC \| none \| process exits \|
#62
#63	## Path Map
#64
#65	\| Path \| What it is \|
#66	\| --- \| --- \|
#67	\| [`leviathan/`](./) \| Package root for the runtime, package metadata, constitution, and build config. \|
#68	\| [`leviathan/src/`](./src/) \| Source of truth for the CLI and runtime modules. \|
#69	\| [`leviathan/dist/`](./dist/) \| Generated JavaScript, declarations, and source maps from `npm run build`. Do not edit directly. \|
#70	\| [`leviathan/node_modules/`](./node_modules/) \| Installed dependencies. Do not edit or commit new generated dependency files. \|
#71	\| [`leviathan/package.json`](./package.json) \| Package metadata, CLI bin names, scripts, dependencies, and Node version requirement. \|
#72	\| [`leviathan/package-lock.json`](./package-lock.json) \| Locked dependency graph for reproducible installs. \|
#73	\| [`leviathan/tsconfig.json`](./tsconfig.json) \| TypeScript config. Outputs to `dist/`, uses NodeNext modules, includes `src/*/`. \|
#74	\| [`leviathan/three-laws.txt`](./three-laws.txt) \| Immutable constitution text. Its SHA-256 hash is stored in spawned state and verified at runtime. \|
#75
#76	## Source Map
#77
#78	\| Path \| Role \|
#79	\| --- \| --- \|
#80	\| [`src/index.ts`](./src/index.ts) \| CLI entrypoint. Handles `--spawn`, `--run`, `--status`, `--memory`, `--memoryInit`, `--spawnling`, `--ticks`, and `--tui`. \|
#81	\| [`src/pulse.ts`](./src/pulse.ts) \| Depth-aware scheduler. Calls one tick immediately after startup and then at the tier interval. \|
#82	\| [`src/survival.ts`](./src/survival.ts) \| Computes depth tiers, model selection, action gating, runway formatting, and conservation prompts. \|
#83	\| [`src/three-laws.ts`](./src/three-laws.ts) \| Constitution loader/verifier. Hashes `three-laws.txt` and refuses to operate on mismatch. \|
#84	\| [`src/types.ts`](./src/types.ts) \| Shared runtime types: depth tiers, identity, state, strike, memory input, and JSONL events. \|
#85	\| [`src/identity/`](./src/identity/) \| Local Ed25519 identity, keystore, signing, pubkey display, and SAS attestation payload generation. \|
#86	\| [`src/state/`](./src/state/) \| Local state persistence in `~/.openclawd/shell.json` and strike journal in `~/.openclawd/strikes.jsonl`. \|
#87	\| [`src/memory/`](./src/memory/) \| Bridge to the Python Clawd Brain / MemeBRain memory system through `python3 -m mnemosyne.clawd_brain`. \|
#88	\| [`src/agent/`](./src/agent/) \| Claude tool loop, prompt builder, tool schema, wallet shim, and Percolator CLI wrapper. \|
#89
#90	## Agent Modules
#91
#92	\| File \| Purpose \|
#93	\| --- \| --- \|
#94	\| [`src/agent/loop.ts`](./src/agent/loop.ts) \| Implements one tail-flick. Builds observations, calls Claude, executes one tool, journals the strike, and returns state changes. \|
#95	\| [`src/agent/system-prompt.ts`](./src/agent/system-prompt.ts) \| Builds the full system prompt and compact shoreline prompt. Injects law summaries and full constitution text. \|
#96	\| [`src/agent/tools.ts`](./src/agent/tools.ts) \| Anthropic tool definitions for wallet checks, Helius reads, Clawd Memory, Jupiter quote/paper swap, OODA signal, A2A, pay intent, Percolator, shell write, spawn intent, and hold. \|
#97	\| [`src/agent/wallet.ts`](./src/agent/wallet.ts) \| Wallet shim. Reads the local pubkey, checks SOL balance over RPC, gets Jupiter quotes, and signs messages via the identity module. \|
#98	\| [`src/agent/percolator.ts`](./src/agent/percolator.ts) \| Wrapper around the external `percolator` CLI. Defaults to devnet unless `PERCOLATOR_MAINNET=1`. \|
#99
#100	## Runtime State
#101
#102	Leviathan writes local runtime files under:
#103
#104	```text
#105	~/.openclawd/
#106	├── keystore.json # local secret key material, mode 0600
#107	├── shell.json # current ClawState
#108	└── strikes.jsonl # append-only strike journal
#109	```
#110
#111	Safety rules:
#112
#113	- `keystore.json` contains secret material and must never be committed, logged, pasted into prompts, or passed to tools.
#114	- `loadPubkey()` exposes only the public key.
#115	- `signMessage()` signs locally and returns a signature; it does not expose the secret.
#116	- Clawd Memory writes reject obvious secret-like content.
#117
#118	## Commands
#119
#120	\| Command \| Meaning \|
#121	\| --- \| --- \|
#122	\| `npm run build` \| Compile TypeScript into `dist/`. \|
#123	\| `npm run dev` \| Run `src/index.ts` through `tsx`. \|
#124	\| `npm run spawn` \| Generate a local identity and initial shell state. \|
#125	\| `npm run run:leviathan` \| Start the pulse loop. \|
#126	\| `npm run status` \| Print identity, depth, balances, lifecycle counters, and constitution status. \|
#127	\| `npm run memory` \| Query Clawd Memory for current Leviathan context. \|
#128	\| `npm run memory:init` \| Initialize the Clawd Memory bank before recall. \|
#129
#130	Root package aliases:
#131
#132	```bash
#133	npm run leviathan:spawn
#134	npm run leviathan
#135	npm run leviathan:status
#136	```
#137
#138	## Tool Surface
#139
#140	The Claude loop can request one tool per tick. Tools are filtered by depth before being sent to the model.
#141
#142	\| Tool family \| Examples \| Notes \|
#143	\| --- \| --- \| --- \|
#144	\| Wallet / Solana \| `solana_balance`, `wallet_brief`, `helius_transactions` \| Reads wallet/RPC data; Helius requires `HELIUS_API_KEY`. \|
#145	\| Memory \| `clawd_memory_recall`, `clawd_memory_remember`, `clawd_memory_research` \| Bridges to MemeBRain. Refuses likely secret storage. \|
#146	\| Trading / market \| `jupiter_quote`, `jupiter_swap`, `ooda_signal` \| Swap execution is currently paper-mode in the shim. \|
#147	\| Perpetuals \| `percolator_list_markets`, `percolator_slab_get`, `percolator_quote`, `percolator_funding_rate` \| Calls external `percolator` CLI, devnet by default. \|
#148	\| Agent/payment rails \| `a2a_task`, `paysh_pay` \| Records/discovers intents; private payment implementation is not public. \|
#149	\| Lifecycle \| `shell_write`, `spawn_spawnling`, `hold` \| Molt shell text, queue spawn intent, or deliberately drift. \|
#150
#151	## Safety Boundaries
#152
#153	- The Three Laws file is hashed and checked before spawn and each run.
#154	- The runtime exits when depth becomes `beached`.
#155	- Mainnet Percolator is opt-in through `PERCOLATOR_MAINNET=1`.
#156	- `spawn_spawnling` is only allowed at `deep` depth and is recorded as an intent.
#157	- `paysh_pay` records a capped payment intent; it does not by itself expose private payment source.
#158	- `jupiter_swap` returns paper-mode output in the current wallet shim.
#159
#160	## Development Notes
#161
#162	- Edit `src/`, not `dist/`.
#163	- Keep `dist/` and `node_modules/` treated as generated artifacts.
#164	- The README describes current code behavior, not an audited production agent.
#165	- Before enabling real money flows, review signer boundaries, RPC behavior, balances, external CLI execution, and every tool that can spend or mutate state.
#166

z6Mkq5mY3JWtxoxUobWcfNHm7AkRubgSWEZTkBVqZXJviFZ5/my-project-public