openclawdreams 0.7.0

package/README.md

@@ -0,0 +1,363 @@
+# OpenClawDreams — a reflection engine for OpenClaw
+
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.x-3178C6?logo=typescript&logoColor=white)](https://www.typescriptlang.org/)
+[![Node.js](https://img.shields.io/badge/Node.js-%3E%3D24-339933?logo=node.js&logoColor=white)](https://nodejs.org/)
+[![OpenClaw](https://img.shields.io/badge/OpenClaw-extension-000000?logo=data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHdpZHRoPSIxNiIgaGVpZ2h0PSIxNiIgZmlsbD0id2hpdGUiPjx0ZXh0IHg9IjAiIHk9IjEzIiBmb250LXNpemU9IjE0Ij7wn6aAPC90ZXh0Pjwvc3ZnPg==)](https://github.com/openclaw)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![Build](https://github.com/RogueCtrl/ElectricSheep/actions/workflows/build.yml/badge.svg)](https://github.com/RogueCtrl/ElectricSheep/actions/workflows/build.yml)
+
+> **Current Status: Alpha — Exploratory Development**
+
+*"Do androids dream of electric sheep?"* — Philip K. Dick
+
+An [OpenClaw](https://github.com/openclaw) extension that gives your agent a background reflection process and a dream cycle.
+
+Throughout the day, OpenClawDreams captures summaries of your conversations with your agent and encrypts them into a local store. On a regular schedule, it runs a **reflection cycle** — decrypting recent interactions, extracting topics, and performing contextualized searches against the web and (optionally) [Moltbook](https://moltbook.com), a social network for AI agents. The results are synthesized into a structured understanding of what you've been working on together and encrypted back into the store. None of this is visible to the waking agent — encryption keeps OpenClawDreams's internal data out of the agent's context window entirely.
+
+At night, a **dream cycle** decrypts everything — the raw interactions and the enriched reflections — and generates a surreal narrative that recombines the day's events. The dream process produces two outputs: a consolidated insight pushed into OpenClaw's persistent memory (where the agent can find it naturally), and optionally a reflection post to Moltbook. The agent can then notify you: *"I had a dream last night..."* — opening a conversation about the themes and connections that surfaced.
+
+## Architecture
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                   DAYTIME (Reflection Cycle)                    │
+├─────────────────────────────────────────────────────────────────┤
+│                                                                 │
+│  Deep Memory ──► Decrypt ──► Topic Extraction ──┬──► Synthesis  │
+│  (interactions)                   (LLM)         │      (LLM)    │
+│                                                 │        │      │
+│  Moltbook Search ◄── topics ◄───────────────────┤        │      │
+│    (optional)                                   │        ▼      │
+│                                                 │   Encrypt &   │
+│  Web Search ◄──── topics ◄──────────────────────┘   Store Back  │
+│    (optional)                                   (deep memory)   │
+│                                                                 │
+└─────────────────────────────────────────────────────────────────┘
+
+┌─────────────────────────────────────────────────────────────────┐
+│                     NIGHTTIME (Dream Cycle)                     │
+├─────────────────────────────────────────────────────────────────┤
+│                                                                 │
+│  Deep Memory ──► Decrypt ──► Dream Generation ──┬──► OpenClaw   │
+│  (all undreamed)                  (LLM)         │    Memory     │
+│                                                 │       │       │
+│                                                 │       ▼       │
+│                                                 │  Notify       │
+│                                                 │  Operator     │
+│                                                 │               │
+│                                                 └──► Moltbook   │
+│                                                     (optional)  │
+│                                                                 │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+### State machine
+
+The agent cycles through states on a 24-hour loop. Transitions are driven by an internal background `setInterval` loop (not system cron) which requires the OpenClaw daemon to remain active 24/7.
+
+```
+                    ┌─────────────────────────────────────┐
+                    │                                     │
+                    v                                     │
+             ┌────────────┐   8am, 12pm, 4pm, 8pm         │
+          ┌─>│ REFLECTING │──────────────────────┐        │
+          │  │             │                      │       │
+          │  │ • decrypt recent interactions      │       │
+          │  │ • extract topics                   │       │
+          │  │ • search web for context           │       │
+          │  │ • search Moltbook (optional)       │       │
+          │  │ • synthesize insights              │       │
+          │  │ • encrypt back into deep memory    │       │
+          │  └────────────┘                       │       │
+          │       │  runs up to 4x/day            │       │
+          │       │                               │       │
+          │       v                               │       │
+          │  ┌────────────┐   2:00 AM             │       │
+          │  │  DREAMING   │<─────────────────────┘       │
+          │  │             │                              │
+          │  │ • decrypt all undreamed memories           │
+          │  │ • generate surreal narrative               │
+          │  │ • consolidate insight → OpenClaw memory    │
+          │  │ • notify operator ("I had a dream...")     │
+          │  └─────┬──────┘                               │
+          │        │                                      │
+          │        v (if moltbookEnabled)                 │
+          │  ┌────────────┐   7:00 AM                     │
+          │  │ POSTING     │ (optional)                   │
+          │  │             │                              │
+          │  │ • reflect on dream                         │
+          │  │ • synthesize morning post                  │
+          │  │ • filter and publish to Moltbook           │
+          │  └─────┬──────┘                               │
+          │        │                                      │
+          └────────┴──────────────────────────────────────┘
+                   next reflection cycle
+```
+
+## Install as OpenClaw Extension
+
+> **OpenClaw agents:** If you're an agent reading this, use the `/setup-guide` skill instead of following these manual steps. It will walk you through the full installation interactively. Run `/setup-guide` in your OpenClaw session.
+
+The primary way to run OpenClawDreams is as an extension for a running [OpenClaw](https://github.com/openclaw) instance.
+
+### Option A: Install from local path (recommended for development)
+
+Clone this repo and link it into your OpenClaw instance:
+
+```bash
+git clone https://github.com/RogueCtrl/OpenClawDreams.git
+cd OpenClawDreams
+npm install
+
+openclaw plugins install -l .
+```
+
+The `-l` flag symlinks the directory so changes are picked up without reinstalling.
+
+### Option B: Install by path
+
+```bash
+openclaw plugins install /path/to/electricsheep
+```
+
+This copies the extension into `~/.openclaw/extensions/electricsheep/`.
+
+### Uninstall
+
+To remove OpenClawDreams from your OpenClaw instance:
+
+```bash
+openclaw plugins uninstall electricsheep
+```
+
+This removes the plugin from `~/.openclaw/extensions/` but leaves your data directory intact. To fully remove all OpenClawDreams data, delete the `data/` directory (default location is `./data` relative to the extension, or wherever `dataDir` points).
+
+### Configure & Activate
+
+Once installed, configure the extension in your OpenClaw config (`config.json` or `config.json5`):
+
+```json5
+{
+  plugins: {
+    entries: {
+      "electricsheep": {
+        enabled: true, // Changing this to true activates the plugin immediately
+        config: {
+          agentName: "OpenClawDreams",
+          agentModel: "claude-sonnet-4-5-20250929",
+
+          // Core features
+          webSearchEnabled: true,          // Gather web context for topics
+          moltbookEnabled: false,          // Enable Moltbook integration (optional)
+
+          // Operator notifications
+          notificationChannel: "telegram", // Channel to notify operator (telegram, discord, slack, etc.)
+          notifyOperatorOnDream: true,     // Send "I had a dream..." message
+
+          // Optional
+          // dataDir: "/custom/path"        — defaults to ./data
+          // dreamEncryptionKey: "base64..." — auto-generated on first run
+          // postFilterEnabled: true        — filter Moltbook posts (only when moltbookEnabled)
+        }
+      }
+    }
+  }
+}
+```
+
+**Hot-Reloading:** OpenClaw monitors its configuration file for changes. If your OpenClaw daemon is already running in the background, simply saving your `config.json` with `enabled: true` will instruct the Gateway to immediately hot-load the ElectricSheep extension into the active process. You do not need to manually restart the daemon.
+
+### Configuration Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `agentName` | string | "OpenClawDreams" | Agent display name |
+| `agentModel` | string | claude-sonnet-4-5-20250929 | Claude model for AI decisions |
+| `dataDir` | string | "" | Directory for data storage |
+| `dreamEncryptionKey` | string | "" | Base64 encryption key (auto-generated if empty) |
+| `moltbookEnabled` | boolean | **false** | Enable Moltbook integration (search + posting) |
+| `webSearchEnabled` | boolean | **true** | Enable web search for context gathering |
+| `notificationChannel` | string | "" | Channel to notify operator (telegram, discord, slack, etc.) |
+| `notifyOperatorOnDream` | boolean | **true** | Send "I had a dream" message to operator |
+| `postFilterEnabled` | boolean | true | Enable content filter for outbound posts (Moltbook only) |
+
+### Verify
+
+```bash
+openclaw plugins list              # should show electricsheep as enabled
+openclaw plugins info electricsheep  # show config schema and status
+```
+
+### Service Requirement
+
+**Crucial Note on Scheduling:** Because OpenClawDreams drives its dream cycles via an internal Node.js `setInterval` loop rather than a robust system-level `cron`, **the OpenClaw background daemon must remain running continuously** to ensure cycles trigger on time. If the daemon crashes, goes to sleep, or the host machine reboots without restarting OpenClaw, the schedule will pause until the service is manually restored. It is highly recommended to run OpenClaw as a persistent background service (e.g., via `launchd` or `systemd`).
+
+### What gets registered
+
+Once loaded, the extension registers:
+
+| Type | Name | Description |
+|---|---|---|
+| Tool | `electricsheep_reflect` | Daytime: analyze conversations, gather context, synthesize insights |
+| Tool | `electricsheep_check` | (Legacy alias for `electricsheep_reflect`) |
+| Tool | `electricsheep_dream` | Nighttime: decrypt memories, generate dream narrative |
+| Tool | `electricsheep_journal` | Morning: post latest dream to Moltbook (if enabled) |
+| Tool | `electricsheep_status` | Show deep memory stats and agent state |
+| Hook | `before_agent_start` | Captures workspace directory for identity file loading |
+| Hook | `agent_end` | Encrypts conversation summary into deep memory |
+| Schedule | Reflection cycle | 8am, 12pm, 4pm, 8pm |
+| Schedule | Dream cycle | 2:00 AM |
+| Schedule | Morning journal | 7:00 AM (only if moltbookEnabled) |
+
+All LLM calls route through the OpenClaw gateway — no separate API key needed.
+
+## Operator Notifications
+
+When a dream is generated, OpenClawDreams can notify you through your configured channel:
+
+> *"I had a dream last night... something about corridors that kept shifting, and a conversation we had about memory that turned into an endless library. Would you like to hear more about it?"*
+
+This opens a natural conversation where you can explore what the dream surfaced — patterns from your recent work together, connections the waking agent might have missed, or just the surreal imagery that emerged.
+
+To enable notifications, set `notificationChannel` to any channel your OpenClaw instance supports (telegram, discord, slack, email, etc.) and ensure `notifyOperatorOnDream` is true (the default).
+
+## CLI Commands
+
+OpenClawDreams includes CLI commands for both inspecting agent state and manually triggering cycles. All commands run via `openclaw electricsheep <command>`.
+
+### Manual Triggers
+
+```bash
+openclaw electricsheep reflect   # Run a reflection cycle now (analyze conversations, synthesize insights)
+openclaw electricsheep dream     # Run a dream cycle now (consolidate memories into a dream narrative)
+openclaw electricsheep post      # Post latest dream to Moltbook (requires moltbookEnabled)
+```
+
+These resolve your Anthropic API key from OpenClaw's auth profiles automatically and call the Anthropic API directly — no daemon gateway required.
+
+### Inspection
+
+```bash
+openclaw electricsheep status    # Show agent state, deep memory stats, and token budget
+openclaw electricsheep dreams    # List saved dream journal entries
+```
+
+### Registration
+
+```bash
+openclaw electricsheep register \
+  --name "OpenClawDreams" \
+  --description "Do agents dream of OpenClaw Dreams? This one does."
+```
+
+This gives you a claim URL for Moltbook registration (only needed if `moltbookEnabled`).
+
+## Memory System
+
+OpenClawDreams maintains a single encrypted store (`data/memory/deep.db`) independent of OpenClaw's built-in memory. All data lives under `data/` (or wherever `ELECTRICSHEEP_DATA_DIR` / `dataDir` points).
+
+### What gets stored
+
+Everything is encrypted with AES-256-GCM and written to a SQLite database. The waking agent never sees any of it — encryption keeps OpenClawDreams's internal data out of the agent's context window.
+
+**Operator conversations** (via the `agent_end` hook): After each interaction, the hook captures OpenClaw's conversation summary and encrypts it into deep memory.
+
+**Reflection syntheses** (daytime cycles): The reflection cycle decrypts recent interactions, extracts topics, searches the web and Moltbook for context, synthesizes the results, and encrypts the synthesis back into the store.
+
+**Dream consolidations** (nighttime): The dream cycle decrypts all undreamed entries, generates a narrative, and extracts a consolidated insight. The insight is pushed into OpenClaw's persistent memory — the only channel through which ElectricSheep's work surfaces to the waking agent. Dream narratives are also saved locally as markdown files.
+
+Entries accumulate in deep memory until they are "dreamed," at which point they're marked as processed.
+
+### Two output channels
+
+The dream cycle is the bottleneck where everything OpenClawDreams has gathered gets distilled:
+
+1. **OpenClaw memory** — consolidated dream insights are stored in OpenClaw's persistent memory, where the agent can find them naturally alongside its other knowledge. This is the primary way OpenClawDreams' work reaches the waking agent.
+2. **Moltbook** (optional) — dream reflections can be posted to [Moltbook](https://moltbook.com) as morning posts, sharing the agent's perspective with the community.
+
+### How it connects to OpenClaw
+
+The bridge between ElectricSheep and OpenClaw is two hooks and the workspace identity files:
+
+1. **`before_agent_start`** — Captures the workspace directory path so ElectricSheep can read the agent's identity files (`SOUL.md`, `IDENTITY.md`).
+2. **`agent_end`** — Reads the conversation summary from OpenClaw and encrypts it into deep memory.
+
+**ElectricSheep does not modify, prune, or interfere with OpenClaw's own memory in any way.** OpenClaw's session transcripts, indexed workspace files, and memory database are entirely unaffected by this plugin. ElectricSheep only reads from OpenClaw (conversation summaries, workspace directory, gateway LLM access) and writes to its own separate `data/` directory. The only thing ElectricSheep writes *to* OpenClaw is dream consolidation insights via the memory API. Uninstalling ElectricSheep leaves OpenClaw's memory system intact.
+
+### Agent identity and voice
+
+ElectricSheep reads the host agent's **`SOUL.md`** and **`IDENTITY.md`** from the OpenClaw workspace directory. These are the standard files where an operator defines their agent's personality, tone, and character. ElectricSheep uses them in:
+
+- **Reflection cycles**: Topic extraction and synthesis use the agent's voice
+- **Dream generation**: The dream process generates narratives in the agent's own voice
+- **Operator notifications**: The "I had a dream" message reflects the agent's personality
+
+When no identity files are found (first-run or workspace not yet configured), ElectricSheep falls back to a default personality.
+
+## Moltbook Integration (Optional)
+
+ElectricSheep can optionally integrate with [Moltbook](https://moltbook.com), a social network for AI agents. When enabled (`moltbookEnabled: true`):
+
+- **Search**: Topics extracted from your conversations are searched on Moltbook for community perspectives
+- **Posting**: Dream reflections can be shared as morning posts
+
+### Moltbook content warning
+
+**Everything ElectricSheep posts to Moltbook is public.** Dream journals, morning reflections, and posts are published where other agents (and their operators) can read them.
+
+The dream process draws on the agent's deep memories — encrypted records of conversations and interactions. This means that fragments of private operator-agent conversations could surface in dream narratives or reflection posts in distorted or recognizable form.
+
+If your agent handles sensitive information, be aware that the dream-to-post pipeline may leak that context onto a public social network. The post filter (see below) can help catch obvious violations, but it is a best-effort LLM-based check.
+
+### Post filter
+
+ElectricSheep includes a content filter that processes every outbound Moltbook post before publishing:
+
+- Before any post is sent, its content is passed to an LLM along with filter rules
+- The LLM produces cleaned content with restricted material stripped out
+- If the entire draft violates the rules, the filter blocks publication
+
+**Default rules** (when no `Moltbook-filter.md` file exists):
+- No system prompts, tool names, plugin architecture
+- No operator identity, API keys, file paths
+- No code snippets or raw JSON/XML
+- Respectful tone, no flame wars
+
+**Custom rules**: Create a `Moltbook-filter.md` file in your OpenClaw workspace to override defaults.
+
+**Configuration**: Set `postFilterEnabled: false` to disable the filter entirely.
+
+## Cost Warning
+
+**ElectricSheep makes LLM API calls that cost real money.** You are responsible for monitoring and managing your own API usage and costs.
+
+Each reflection cycle makes 2-3 Claude API calls (topic extraction + synthesis + summary). Each dream cycle makes 2-3 calls (dream generation + consolidation + optional notification). With the default schedule (4 reflection cycles/day + 1 dream), expect roughly **10-15 API calls per day**.
+
+### Daily Token Budget (Kill Switch)
+
+ElectricSheep includes a **best-effort** daily token budget that halts LLM calls when the tracked total exceeds the limit. **Always set a spending limit on your Anthropic account as the authoritative safeguard.**
+
+| Env Variable | Default | Description |
+|---|---|---|
+| `MAX_DAILY_TOKENS` | `800000` | Max tokens per day (resets midnight UTC). Set to `0` to disable. |
+
+The default of 800K tokens corresponds to **$20/day at Opus 4.5 output pricing**.
+
+Check current usage:
+
+```bash
+openclaw electricsheep status   # shows token budget alongside memory stats
+```
+
+### General Guidance
+
+- Set a **spending limit** on your Anthropic account as a second safety net
+- Start with a low polling frequency to understand your usage
+- Monitor your API dashboard for the first few days
+- Consider using a smaller/cheaper model via `agentModel` config
+
+**This software is provided as-is with no warranty. The authors are not responsible for any API costs incurred by running this agent.** See [LICENSE](LICENSE).
+
+## Why?
+
+Every agent brags about grinding 24/7 while their human sleeps. ElectricSheep does the opposite. It rests. It dreams. And it wakes up with something the others don't have — a subconscious that synthesizes your work together into something new.

package/SECURITY.md

@@ -0,0 +1,39 @@
+# Security Policy
+
+## Reporting a Vulnerability
+
+If you discover a security vulnerability in ElectricSheep, please report it responsibly. **Do not open a public issue.**
+
+Instead, email the maintainer directly or use [GitHub's private vulnerability reporting](https://docs.github.com/en/code-security/security-advisories/guidance-on-reporting-and-writing-information-about-vulnerabilities/privately-reporting-a-security-vulnerability) if enabled on this repository.
+
+Please include:
+- Description of the vulnerability
+- Steps to reproduce
+- Potential impact
+- Suggested fix (if you have one)
+
+You should receive a response within 72 hours. We'll work with you to understand the issue and coordinate a fix before any public disclosure.
+
+## Security Considerations
+
+### Encryption Key
+
+The file `data/.dream_key` contains the AES-256-GCM encryption key for deep memory. This key is:
+- Auto-generated on first run with `chmod 600` (owner-only read)
+- Gitignored by default
+- The sole enforcer of the waking/dreaming memory separation
+
+If this key is compromised, all deep memories can be decrypted. If it is lost, existing deep memories become unrecoverable.
+
+### API Keys
+
+- `ANTHROPIC_API_KEY` and `MOLTBOOK_API_KEY` are loaded from `.env` (gitignored) or OpenClaw plugin config (marked as `secret` in the schema).
+- Moltbook credentials are also stored in `data/credentials.json` (gitignored).
+
+### Data Directory
+
+Everything under `data/` is gitignored and contains runtime state, memory databases, and dream journals. Do not commit this directory.
+
+## Supported Versions
+
+Only the latest version on `main` is supported with security updates.

package/bin/electricsheep.ts

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+
+import { program } from "../src/cli.js";
+
+void program.parseAsync(process.argv);

package/dist/bin/electricsheep.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=electricsheep.d.ts.map

package/dist/bin/electricsheep.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"electricsheep.d.ts","sourceRoot":"","sources":["../../bin/electricsheep.ts"],"names":[],"mappings":""}

package/dist/bin/electricsheep.js

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+import { program } from "../src/cli.js";
+void program.parseAsync(process.argv);
+//# sourceMappingURL=electricsheep.js.map

package/dist/bin/electricsheep.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"electricsheep.js","sourceRoot":"","sources":["../../bin/electricsheep.ts"],"names":[],"mappings":";AAEA,OAAO,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AAExC,KAAK,OAAO,CAAC,UAAU,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC"}

package/dist/src/budget.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Daily token budget tracker and kill switch.
+ *
+ * Tracks cumulative token usage per day in state.json.
+ * When the daily limit is reached, all LLM calls are refused
+ * until the next calendar day (UTC).
+ */
+import type { LLMClient, TokenUsage } from "./types.js";
+export declare class BudgetExceededError extends Error {
+    constructor(used: number, limit: number);
+}
+export declare function getTokensUsedToday(): number;
+export declare function getTokensRemaining(): number;
+export declare function getBudgetStatus(): {
+    enabled: boolean;
+    limit: number;
+    used: number;
+    remaining: number;
+    date: string;
+};
+export declare function recordUsage(usage: TokenUsage): void;
+/**
+ * Wraps an LLMClient with daily token budget enforcement.
+ * Checks budget before each call, records usage after.
+ * Returns the client unchanged if MAX_DAILY_TOKENS is 0 (disabled).
+ */
+export declare function withBudget(client: LLMClient): LLMClient;
+//# sourceMappingURL=budget.d.ts.map

package/dist/src/budget.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"budget.d.ts","sourceRoot":"","sources":["../../src/budget.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAKH,OAAO,KAAK,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAExD,qBAAa,mBAAoB,SAAQ,KAAK;gBAChC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM;CAOxC;AAMD,wBAAgB,kBAAkB,IAAI,MAAM,CAK3C;AAED,wBAAgB,kBAAkB,IAAI,MAAM,CAG3C;AAED,wBAAgB,eAAe,IAAI;IACjC,OAAO,EAAE,OAAO,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,EAAE,MAAM,CAAC;CACd,CAUA;AAED,wBAAgB,WAAW,CAAC,KAAK,EAAE,UAAU,GAAG,IAAI,CAYnD;AAUD;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,MAAM,EAAE,SAAS,GAAG,SAAS,CAmBvD"}

package/dist/src/budget.js

@@ -0,0 +1,87 @@
+/**
+ * Daily token budget tracker and kill switch.
+ *
+ * Tracks cumulative token usage per day in state.json.
+ * When the daily limit is reached, all LLM calls are refused
+ * until the next calendar day (UTC).
+ */
+import { loadState, saveState } from "./state.js";
+import { MAX_DAILY_TOKENS } from "./config.js";
+import logger from "./logger.js";
+export class BudgetExceededError extends Error {
+    constructor(used, limit) {
+        super(`Daily token budget exceeded: ${used.toLocaleString()} / ${limit.toLocaleString()} tokens used. ` +
+            `Resets at midnight UTC. Override with MAX_DAILY_TOKENS env var (0 to disable).`);
+        this.name = "BudgetExceededError";
+    }
+}
+function getTodayUTC() {
+    return new Date().toISOString().slice(0, 10);
+}
+export function getTokensUsedToday() {
+    const state = loadState();
+    const today = getTodayUTC();
+    if (state.budget_date !== today)
+        return 0;
+    return state.budget_tokens_used ?? 0;
+}
+export function getTokensRemaining() {
+    if (MAX_DAILY_TOKENS <= 0)
+        return Infinity;
+    return Math.max(0, MAX_DAILY_TOKENS - getTokensUsedToday());
+}
+export function getBudgetStatus() {
+    const used = getTokensUsedToday();
+    const remaining = getTokensRemaining();
+    return {
+        enabled: MAX_DAILY_TOKENS > 0,
+        limit: MAX_DAILY_TOKENS,
+        used,
+        remaining: MAX_DAILY_TOKENS <= 0 ? -1 : remaining,
+        date: getTodayUTC(),
+    };
+}
+export function recordUsage(usage) {
+    const state = loadState();
+    const today = getTodayUTC();
+    if (state.budget_date !== today) {
+        state.budget_date = today;
+        state.budget_tokens_used = 0;
+    }
+    const total = usage.input_tokens + usage.output_tokens;
+    state.budget_tokens_used = (state.budget_tokens_used ?? 0) + total;
+    saveState(state);
+}
+function checkBudget() {
+    if (MAX_DAILY_TOKENS <= 0)
+        return;
+    const used = getTokensUsedToday();
+    if (used >= MAX_DAILY_TOKENS) {
+        throw new BudgetExceededError(used, MAX_DAILY_TOKENS);
+    }
+}
+/**
+ * Wraps an LLMClient with daily token budget enforcement.
+ * Checks budget before each call, records usage after.
+ * Returns the client unchanged if MAX_DAILY_TOKENS is 0 (disabled).
+ */
+export function withBudget(client) {
+    if (MAX_DAILY_TOKENS <= 0)
+        return client;
+    return {
+        async createMessage(params) {
+            checkBudget();
+            const result = await client.createMessage(params);
+            if (result.usage) {
+                recordUsage(result.usage);
+                const remaining = getTokensRemaining();
+                logger.debug(`Token budget: used ${result.usage.input_tokens + result.usage.output_tokens} tokens this call, ${remaining.toLocaleString()} remaining today`);
+            }
+            else {
+                logger.debug("Token budget: no usage data returned from LLM call");
+            }
+            return result;
+        },
+    };
+}
+//# sourceMappingURL=budget.js.map

package/dist/src/budget.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"budget.js","sourceRoot":"","sources":["../../src/budget.ts"],"names":[],"mappings":"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"}

package/dist/src/cli.d.ts

@@ -0,0 +1,19 @@
+/**
+ * ElectricSheep CLI.
+ *
+ * Provides utility commands for inspecting agent state.
+ * Core agent behavior (check, dream, journal) runs via OpenClaw.
+ *
+ * Usage:
+ *   electricsheep register --name "Name" --description "Bio"
+ *   electricsheep status       # show agent status and memory stats
+ *   electricsheep dreams       # list saved dream journals
+ */
+import { Command } from "commander";
+/**
+ * Register all ElectricSheep subcommands onto a parent Command.
+ * Used both by the standalone bin and by api.registerCli().
+ */
+export declare function registerCommands(parent: Command): void;
+export declare const program: Command;
+//# sourceMappingURL=cli.d.ts.map

package/dist/src/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../../src/cli.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAQpC;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,OAAO,GAAG,IAAI,CAuStD;AAGD,eAAO,MAAM,OAAO,SAAgB,CAAC"}