musonda 1.0.0

package/IMPLEMENTATION.md

@@ -0,0 +1,432 @@
+# Musonda Implementation Guide 🛠️
+
+This is the technical reference for Musonda contributors, integrators, and
+operators. For a friendly introduction and quick start, see the
+[README](README.md).
+
+Musonda is a personal AI assistant and autonomous agent harness built with
+TypeScript. It runs continuously inside an extensible gateway service connecting
+the terminal, Discord, Slack, and HTTP clients.
+
+Musonda uses the OpenAI Responses API and includes persistent memory, dynamic
+persona synthesis, autonomous scheduling, and an extensible tool suite.
+
+---
+
+## 🌟 Key Features
+
+- **Autonomous Gateway Architecture**:
+  - Central gateway daemon managing connections to communication platforms.
+  - **CLI Channel**: Interactive terminal REPL session (`npm run cli` or `npm start -- --cli`) for real-time conversational agent interaction directly in your terminal, with live thinking indicators, built-in slash commands (`/help`, `/status`, `/profile`, `/clear`, `/exit`), and proactive scheduled reminder delivery.
+  - **Discord Channel**: Full `discord.js` adapter with mention stripping, typing indicators, auto-chunking (2000-character Discord limit), and security whitelists.
+  - **Slack Channel**: Native `@slack/bolt` adapter with **Socket Mode** (no public IP/tunnel needed!), app mentions (`@Musonda`), DMs, thread replies, and visual reaction feedback.
+  - **HTTP REST Gateway** (port 4141): Exposes `/health`, `/status`, `/api/profile`, `/api/memories`, `/api/schedules`, and `/api/chat`.
+  - Per-session message concurrency queues preventing race conditions.
+
+- **⏰ Autonomous Schedules & Cron Jobs Engine**:
+  - Built-in persistent scheduler using `croner` running inside the Gateway daemon.
+  - **Recurring Cron Tasks**: Standard 5-part cron syntax (e.g. `0 8 * * 1-5` for weekdays at 8:00 AM) evaluated in your configured timezone.
+  - **Relative Timers**: Convenient relative delays like `+30m`, `+2h`, `+1d` for one-time reminders.
+  - **Dynamic Autonomous Execution**: Scheduled jobs can run autonomous instruction prompts through Musonda's full reasoning harness (with memory & web search) or send direct reminder notes to your Discord/Slack channel.
+  - **Conversational Management**: Say *"Remind me in 45 minutes to check tests"* or *"Every weekday at 9am send a standup summary"* directly in Discord or Slack.
+
+- **Initial Onboarding Wizard**:
+  - Interactive CLI setup wizard (`npm run onboard`) that runs before first boot.
+  - Allows you to give a **custom name** to your assistant (or keep default *Musonda*).
+  - Collects your name, background/bio, timezone, and communication style.
+  - Configures OpenAI credentials (`gpt-5.6-luna`), Discord bot token, and Slack tokens.
+  - Automatically seeds your assistant's persistent memory with your preferences.
+
+- **OpenAI Responses API (`gpt-5.6-luna`)**:
+  - Built specifically for the OpenAI `/v1/responses` API.
+  - Native support for system `instructions`, stateful conversation items, function tool calling (`type: 'function'`), and `function_call_output` returns.
+  - Optimized compatibility with `gpt-5.6-luna` parameter expectations.
+
+- **Multi-Tiered Memory System**:
+  - **User Profile**: Structured identity, bio, timezone, and tone settings stored in `data/memory/profile.json`.
+  - **Long-Term Memory**: Persistent store for facts, preferences, project details, and goals with keyword and semantic relevance scoring.
+  - **Short-Term Session History**: Sliding conversation context buffer per channel and user saved in `data/sessions/`.
+  - **Automatic Recall**: Musonda automatically retrieves relevant past memories matching your query and injects them into the reasoning prompt.
+
+- **Extensible Tool Registry (Hermes / OpenClaw Pattern)**:
+  - `schedule_create`: Schedule a one-off timer or recurring cron job.
+  - `schedule_list`: List active cron jobs and timers.
+  - `schedule_cancel`: Cancel an active schedule by ID or title.
+  - `memory_store`: Store facts, user preferences, or project updates directly into long-term memory.
+  - `memory_recall`: Search and retrieve past memories matching keywords or queries.
+  - `update_user_profile`: Dynamically update your profile (bio, name, tone, notes).
+  - `current_time`: Timezone-aware date, time, and day information.
+  - `calculate`: Safe mathematical expression evaluation.
+  - `web_fetch`: Fetch webpage content and extract clean text.
+  - `web_search`: Query real-time search information.
+  - `note_save`, `note_read`, `note_list`: Manage personal markdown notes and documents.
+  - `plugin_install`: Install and activate portable Agent Plugins from Git repositories or local folders.
+  - `plugin_remove`: Safely uninstall and unload plugins from runtime and disk.
+  - `plugin_find`: Search and discover plugins locally and across ecosystem catalogs.
+  - `plugin_info`: Deeply inspect plugin manifests, skills, and MCP configuration.
+  - `plugin_create`: Scaffold and dynamically author new Agent Plugins on the fly.
+  - `plugin_reload`: Refresh plugins from disk without restarting the Gateway daemon.
+  - `plugin_list`: Inspect all loaded plugins, active MCP tools, and skills in runtime.
+  - `skill_list`, `skill_read`, `skill_run_script`: Progressive disclosure and execution of Agent Skills.
+
+
+---
+
+## 📁 Project Structure
+
+```
+musonda/
+├── package.json               # Scripts, ESM configuration, dependencies
+├── tsconfig.json              # TypeScript configuration
+├── .env.example               # Example environment variables
+├── README.md                  # Documentation
+├── src/
+│   ├── index.ts               # Gateway daemon entry point (checks onboarding)
+│   ├── config/
+│   │   ├── types.ts           # Zod schemas & TypeScript config types
+│   │   └── loader.ts          # Reads/writes musonda.config.json & .env
+│   ├── wizard/
+│   │   └── onboarding.ts      # Interactive initial onboarding wizard (Discord & Slack)
+│   ├── scheduler/
+│   │   ├── types.ts           # ScheduleJob, ScheduleTarget, and action interfaces
+│   │   └── scheduler.ts       # MusondaScheduler (Croner engine, persistence, triggers)
+│   ├── memory/
+│   │   ├── types.ts           # Memory & session data models
+│   │   ├── storage.ts         # Atomic JSON file storage engine
+│   │   └── memoryManager.ts   # Profile, long-term memory, auto-recall & sessions
+│   ├── tools/
+│   │   ├── types.ts           # Tool interfaces & OpenAI function schemas
+│   │   ├── registry.ts        # Tool registry and execution dispatcher
+│   │   └── builtin/
+│   │       ├── scheduleTools.ts # schedule_create, schedule_list, schedule_cancel
+│   │       ├── memoryTools.ts # memory_store, memory_recall, update_user_profile
+│   │       ├── timeTools.ts   # current_time
+│   │       ├── calcTools.ts   # calculate
+│   │       ├── webTools.ts    # web_fetch, web_search
+│   │       └── noteTools.ts   # note_save, note_read, note_list
+│   ├── agent/
+│   │   ├── types.ts           # Agent message and run types
+│   │   ├── systemPrompt.ts    # Dynamic system prompt & persona builder
+│   │   ├── openaiResponsesClient.ts # OpenAI Responses API client (gpt-5.6-luna)
+│   │   └── harness.ts         # Multi-turn reasoning & tool calling loop
+│   ├── gateway/
+│   │   ├── types.ts           # Inbound/outbound message & adapter interfaces
+│   │   ├── server.ts          # MusondaGateway central daemon
+│   │   ├── http.ts            # HTTP REST server (health, chat, schedules API)
+│   │   └── channels/
+│   │       ├── cli.ts         # Interactive CLI terminal channel adapter
+│   │       ├── discord.ts     # Discord.js bot channel adapter
+│   │       ├── slack.ts       # Slack Bolt channel adapter (Socket Mode)
+│   │       └── webhook.ts     # Webhook / API direct channel adapter
+│   └── utils/
+│       └── logger.ts          # Structured, colored logging
+└── test/
+    ├── harness.test.ts        # Unit tests for config, memory, tools & prompt
+    ├── gateway.test.ts        # Integration test for Gateway HTTP & lifecycle
+    └── scheduler.test.ts      # Unit tests for Scheduler, Cron jobs & timers
+```
+
+---
+
+## ⏰ Schedules & Cron Jobs
+
+Musonda runs scheduled tasks autonomously in the background.
+
+### Natural Language Examples (In Slack or Discord):
+- **Relative Timers**:
+  > *"Remind me in 30 minutes to drink water"*
+  > *"Remind me in 2 hours to check our deployment logs"*
+- **Recurring Cron Jobs**:
+  > *"Every weekday at 8:30 AM, send me a brief news summary on Slack"*
+  > *"Every Sunday at 6 PM, check my notes and send me a weekly review"*
+- **Inspecting & Cancelling**:
+  > *"What schedules do I have active?"*
+  > *"Cancel my water reminder schedule"*
+
+### Cron Pattern Reference:
+- `0 9 * * 1-5`: Monday through Friday at 9:00 AM (in your configured timezone)
+- `0 8 * * *`: Every day at 8:00 AM
+- `*/30 * * * *`: Every 30 minutes
+- `+45m`: 45 minutes from now (one-time)
+- `+2h`: 2 hours from now (one-time)
+
+---
+
+## 💻 Musonda Interactive CLI (`musonda`)
+
+Musonda comes with an all-in-one interactive Command Line Interface. Users install `musonda` (globally via `npm install -g musonda` or clone & `npm link`), and `musonda` manages the entire agent lifecycle—including launching the gateway, live terminal chat, plugin management, system diagnostics, and autonomous updates.
+
+### Quick Command Reference:
+
+| Command | Description |
+|---|---|
+| `musonda` | Open the **Interactive Terminal Dashboard & Menu** |
+| `musonda start gateway` | Start the Musonda Gateway server (foreground mode) |
+| `musonda start gateway --daemon` | Start the Gateway in the background as a daemon process |
+| `musonda stop gateway` | Gracefully stop the running Gateway daemon |
+| `musonda restart gateway` | Restart the Gateway daemon |
+| `musonda cli` | Open interactive AI chat with real-time streaming tokens |
+| `musonda help` | View comprehensive CLI help & documentation |
+| `musonda add plugin <name\|repo\|path>` | Install and activate an Agent Plugin (local, git, or curated) |
+| `musonda remove plugin <name>` | Uninstall and remove an installed Agent Plugin |
+| `musonda list plugins` | List all installed plugins, skills, and MCP tools |
+| `musonda find plugins [query]` | Search plugins across local catalog and remote ecosystem |
+| `musonda update` | Check and apply updates to both the core agent and installed plugins |
+| `musonda update agent` | Update core Musonda assistant package (npm or git) |
+| `musonda update plugins` | Update all installed Agent Plugins from git remotes |
+| `musonda status` | Display live gateway health, AI model, persona, channels, and uptime |
+| `musonda doctor` | Run system diagnostics (Node.js, configs, keys, storage, ports, plugins) |
+| `musonda setup` | Run interactive onboarding wizard to configure persona & keys |
+| `musonda version` | Display Musonda version and environment info |
+
+### Interactive Dashboard:
+Running `musonda` without arguments in an interactive terminal opens the interactive terminal dashboard:
+
+```text
+███╗   ███╗██╗   ██╗███████╗ ██████╗ ███╗   ██╗██████╗  █████╗ 
+████╗ ████║██║   ██║██╔════╝██╔═══██╗████╗  ██║██╔══██╗██╔══██╗
+██╔████╔██║██║   ██║███████╗██║   ██║██╔██╗ ██║██║  ██║███████║
+██║╚██╔╝██║██║   ██║╚════██║██║   ██║██║╚██╗██║██║  ██║██╔══██║
+██║ ╚═╝ ██║╚██████╔╝███████║╚██████╔╝██║ ╚████║██████╔╝██║  ██║
+╚═╝     ╚═╝ ╚═════╝ ╚══════╝ ╚═════╝ ╚═╝  ╚═══╝╚═════╝ ╚═╝  ╚═╝
+=== Musonda Personal AI Assistant & Autonomous Agent Harness ===
+
+  Assistant: Musonda | Model: gpt-5.6-luna | Gateway: ● Online (http://127.0.0.1:4141)
+
+  [1]  💬  Start Chat CLI (Talk directly to Musonda)
+  [2]  🚀  Start Gateway Daemon (Run server in background)
+  [3]  ✖  Stop Gateway Daemon
+  [4]  🧩  Manage Plugins (Add, list, search, remove Agent Plugins)
+  [5]  🔄  Update Musonda & Plugins (Check & apply updates)
+  [6]  📊  System Status & Health
+  [7]  🩺  Run Musonda Doctor (Environment diagnostics)
+  [8]  ⚙️  Setup & Onboarding Wizard
+  [9]  💻  Interactive Command Shell (musonda>)
+  [10] 📖  Help & Command Reference
+  [0]  🚪  Exit
+```
+
+### Adding & Managing Plugins:
+Musonda supports the universal [Agent Plugins 1.0.0 Specification](https://agent-plugins.org/):
+
+```bash
+# Add a curated ecosystem plugin
+musonda add plugin example-calc
+
+# Add a plugin from GitHub
+musonda add plugin agentplugins/agent-plugins-example
+
+# Add a plugin from a local directory
+musonda add plugin ./my-custom-plugin
+
+# List installed plugins
+musonda list plugins
+
+# Search ecosystem for plugins
+musonda find plugins math
+
+# Remove an installed plugin
+musonda remove plugin example-calc
+```
+
+### Managing Agent Updates:
+```bash
+# Check and apply updates to both agent and plugins
+musonda update
+
+# Dry-run check without applying
+musonda update --check-only
+
+# Update only the core Musonda agent
+musonda update agent
+
+# Update installed plugins from git
+musonda update plugins
+```
+
+---
+
+## 🚀 Getting Started
+
+### 1. Installation
+
+Install globally to use the `musonda` CLI anywhere:
+
+```bash
+npm install -g musonda
+```
+
+Or clone and link locally:
+
+```bash
+git clone https://github.com/musonda/musonda.git
+cd musonda
+npm install
+npm run build
+npm link
+```
+
+### 2. Run Diagnostics & Setup
+
+```bash
+# Check environment and prerequisites
+musonda doctor
+
+# Run interactive setup wizard
+musonda setup
+```
+
+### 3. Start the Gateway & Chat
+
+```bash
+# Start Gateway daemon in background
+musonda start gateway --daemon
+
+# Open conversational chat session with real-time streaming
+musonda cli
+
+# Check live status
+musonda status
+```
+
+---
+
+## 🌐 Gateway HTTP Endpoints
+
+The Gateway exposes an HTTP server (default: `http://127.0.0.1:4141` or `0.0.0.0:4141` in container mode):
+
+| Method | Endpoint | Description |
+|---|---|---|
+| `GET` | `/health` or `/status` | Liveness and, when authenticated, gateway diagnostics |
+| `GET` | `/ready` or `/readyz` | Readiness probe (in production, verifies gateway auth, storage, AI credentials, and model access) |
+| `GET` | `/api/profile` | Inspect active user profile and assistant persona (Auth required) |
+| `GET` | `/api/memories` | Inspect all persistent memories (Auth required) |
+| `GET` | `/api/plugins` | Inspect all loaded Agent Plugins, active MCP tools, and skills (Auth required) |
+| `POST` | `/api/plugins/install` | Dynamically install and activate a plugin in live runtime (Auth required, restricted to plugin dir) |
+| `POST` | `/api/plugins/remove` | Dynamically remove and unload a plugin from runtime and disk (Auth required) |
+| `GET` | `/api/plugins/find` | Discover plugins across local directories and remote ecosystem (Auth required) |
+| `GET` | `/api/plugins/info` | Inspect detailed manifest, skills, and MCP tools of a plugin (Auth required) |
+| `GET` | `/api/schedules` | Inspect all scheduled cron jobs and timers (Auth required) |
+| `POST` | `/api/schedules` | Create a schedule via JSON API (Auth required) |
+| `POST` | `/api/schedules/cancel` | Cancel an active schedule by `{ "id": "..." }` (Auth required) |
+| `POST` | `/api/chat` | Send a JSON payload `{"message": "Hello!"}` (supports SSE streaming, Auth required) |
+| `POST` | `/api/gateway/stop` | Gracefully shut down the Gateway daemon (Auth required) |
+
+---
+
+## 🐳 Production & Container Deployment
+
+### 1. Docker Compose Deployment (Recommended)
+Musonda includes a production-ready `Dockerfile` and `docker-compose.yml` with:
+- **Non-root execution**: Runs under unprivileged `node` user (UID 1000) with permissions configured on `/app/data`.
+- **Zero-host-lock networking**: Sets `HOST=0.0.0.0` and `GATEWAY_HOST=0.0.0.0` inside container.
+- **Mandatory Production Authentication**: Protected `/api/*` endpoints fail closed when `NODE_ENV=production` unless a valid `GATEWAY_API_KEY` is provided.
+- **Health & Readiness Probes**: `/health` is a lightweight liveness endpoint; the container `HEALTHCHECK` uses `/ready` and verifies storage, authentication configuration, and live AI model access.
+- **Persistent Plugins**: Runtime plugin installation targets `/app/data/plugins`, which is covered by the Compose volume. Bundled plugins remain available from `/app/plugins`.
+- **Private Host Binding**: Compose publishes the gateway on `127.0.0.1:4141`; use a TLS-terminating reverse proxy for public access.
+
+```bash
+# 1. Copy and configure production secrets
+cp .env.example .env
+# Set GATEWAY_API_KEY, OPENAI_API_KEY, etc. in .env
+
+# 2. Start container service with persistent volume
+docker compose up -d
+
+# 3. View live logs
+docker compose logs -f
+```
+
+### 2. Security Hardening & Guardrails
+- **Authentication**: All `/api/*` endpoints require `Authorization: Bearer <key>` or `X-API-Key: <key>`. Comparisons use timing-safe equality to prevent side-channel timing attacks.
+- **Proxy Trust**: `X-Forwarded-For` is ignored by default. Set `GATEWAY_TRUST_PROXY=true` only when direct gateway access is blocked and your reverse proxy overwrites that header.
+- **Plugin Sandbox Lockdown**: Plugin installation only permits installing into managed plugin directories; path traversal and arbitrary directory deletions are strictly blocked. Dependency installations run with `--ignore-scripts` to block untrusted postinstall scripts.
+- **Child Process Secret Isolation**: MCP servers and skill scripts inherit only safe system environment variables; critical secrets (`OPENAI_API_KEY`, channel tokens, gateway key) are filtered out.
+- **SSRF Hardening**: Outbound web requests validate hostnames and DNS records against loopback, link-local, carrier-grade NAT, and RFC 1918 private subnets, then pin the connection to the validated address to prevent DNS rebinding. Redirects are manually revalidated and response bodies have a strict 2 MB limit.
+- **Persistence & Snapshots**: `JsonStorage` implements file-based concurrency locking, automatic pre-write `.bak` snapshots, and timestamped backup rotation.
+
+---
+
+
+## 🧩 Agent Plugins Subsystem (v1.0.0 Specification - https://agent-plugins.org/)
+
+Musonda natively implements the vendor-neutral **Agent Plugins Specification 1.0.0** ([https://agent-plugins.org/](https://agent-plugins.org/)). This allows you and Musonda to discover, install, author, use, and remove portable agent packages on the fly.
+
+### Package Architecture:
+```text
+plugins/<plugin-name>/
+├── plugin.json                 # Required manifest ($schema: https://agent-plugins.org/schemas/1.0.0/plugin.schema.json)
+├── mcp.json                    # Optional MCP server definitions ($schema: https://agent-plugins.org/schemas/1.0.0/mcp.schema.json)
+└── skills/                     # Optional Agent Skills directory
+    └── <skill-name>/
+        ├── SKILL.md            # Skill instructions with YAML frontmatter
+        ├── scripts/            # Bundled executable automation scripts
+        └── references/         # Knowledge base & reference files
+```
+
+### Conversational Plugin Management:
+You can manage plugins naturally via Discord, Slack, or terminal CLI:
+- **Find Plugins**:
+  > *"Musonda, find plugins for PostgreSQL database management"*
+  > *"What plugins are available for GitHub integration?"*
+- **Install Plugins**:
+  > *"Install the plugin from https://github.com/agentplugins/agent-plugins-example.git"*
+  > *"Add plugin from ./plugins/my-custom-tools"*
+- **Use Skills & Tools**:
+  > *"What skills do you have installed?"* (`skill_list`)
+  > *"Read instructions for the code-review skill"* (`skill_read`)
+  > Directly invoke any connected MCP tools (`mcp_<plugin>_<server>_<tool>`)
+- **Remove Plugins**:
+  > *"Remove the weather plugin"* (`plugin_remove`)
+- **Inspect Status**:
+  > *"List loaded plugins and their MCP servers"* (`plugin_list` or `plugin_info`)
+
+
+---
+
+## 🧪 Testing
+
+Run the full automated test suite:
+
+```bash
+npm test
+```
+
+Runs:
+1. `harness.test.ts`: Config, Memory, Built-in Tools, Dynamic Prompt Builder, Webhook.
+2. `gateway.test.ts`: Gateway lifecycle, Channel statuses, REST endpoints.
+3. `scheduler.test.ts`: Cron jobs, Relative timers, Auto-triggers, Persistence, Schedule tools.
+
+---
+
+## 📦 Releasing to npm
+
+Publish the version currently declared in `package.json`:
+
+```bash
+npm run release
+```
+
+For later releases, bump the version and publish in one command:
+
+```bash
+npm run release:patch
+npm run release:minor
+npm run release:major
+```
+
+Every publish runs the build, full test suite, and package dry run first. npm will
+prompt for two-factor authentication when required. If a bumped release fails,
+the original `package.json` and `package-lock.json` versions are restored.
+
+Run only the release checks with:
+
+```bash
+npm run release:check
+```
+
+---
+
+## 📄 License
+
+MIT License.

package/README.md

@@ -0,0 +1,119 @@
+# Musonda 
+
+**A personal AI companion that remembers, helps, and stays available.**
+
+Musonda is an AI assistant you can run and make your own. It gets to know how
+you like to work, remembers the things that matter to you, and helps you carry
+ideas and tasks from one conversation to the next.
+
+Talk to Musonda from your terminal, Discord, or Slack. Ask a question, save a
+note, set a reminder, look something up, or give it new abilities with plugins.
+
+## Meet Musonda
+
+Most AI conversations disappear when the chat ends. Musonda is designed to be
+part of your day: available when you need it and able to remember useful context
+over time.
+
+You decide its name, personality, communication style, and where you want to
+talk to it. Musonda can be a quiet helper in your terminal, a teammate in Slack,
+or a companion you message on Discord.
+
+## What can Musonda do?
+
+- **Remember what matters** — preferences, goals, project details, and useful
+  facts can carry into future conversations.
+- **Keep you on track** — create one-time reminders or recurring routines using
+  everyday language.
+- **Take and find notes** — save ideas, lists, and personal notes, then ask for
+  them later.
+- **Help with everyday questions** — search the web, read pages, calculate, and
+  work through a problem with you.
+- **Meet you where you work** — chat in the terminal, Discord, Slack, or through
+  another app connected to Musonda.
+- **Learn new abilities** — install plugins and skills when you want Musonda to
+  do more.
+
+## Things you can say
+
+> “Remember that I prefer short progress updates.”
+
+> “Remind me in 45 minutes to check the deployment.”
+
+> “Every weekday morning, help me prepare for stand-up.”
+
+> “Save this idea in my notes.”
+
+> “What do you remember about my current project?”
+
+> “Find a plugin that can help me work with GitHub.”
+
+## Getting started
+
+You need [Node.js](https://nodejs.org/) 20 or newer and an OpenAI API key.
+Discord and Slack are optional—you can start entirely in your terminal.
+
+Install Musonda:
+
+```bash
+npm install -g musonda
+```
+
+Run the guided setup:
+
+```bash
+musonda setup
+```
+
+Then open Musonda:
+
+```bash
+musonda
+```
+
+The setup guide helps you choose how Musonda should address you, how it should
+communicate, and which channels you want to connect.
+
+To go straight to a terminal conversation:
+
+```bash
+musonda start gateway --daemon
+musonda cli
+```
+
+## Make it yours
+
+Musonda starts with useful everyday abilities, but it does not have to stay the
+same. You can shape its personality, connect the channels you enjoy using, and
+add plugins for the kind of work you do.
+
+```bash
+# Discover available plugins
+musonda find plugins
+
+# Add a plugin
+musonda add plugin example-calc
+
+# See what is installed
+musonda list plugins
+```
+
+You can also ask Musonda to find, install, explain, or remove plugins during a
+conversation.
+
+## Everyday commands
+
+| Command | What it does |
+|---|---|
+| `musonda` | Opens the main menu |
+| `musonda setup` | Personalizes and connects Musonda |
+| `musonda cli` | Starts a terminal conversation |
+| `musonda start gateway --daemon` | Keeps Musonda running in the background |
+| `musonda stop gateway` | Stops the background assistant |
+| `musonda status` | Shows whether Musonda is running |
+| `musonda doctor` | Checks your setup and suggests fixes |
+| `musonda help` | Shows all available commands |
+
+## License
+
+MIT License.

package/dist/agent/harness.d.ts

@@ -0,0 +1,25 @@
+import { MusondaConfig } from '../config/types.js';
+import { MemoryManager } from '../memory/memoryManager.js';
+import { ToolRegistry } from '../tools/registry.js';
+import { OpenAIResponsesClient } from './openaiResponsesClient.js';
+import { AgentRunInput, AgentRunResult } from './types.js';
+export declare class AgentHarness {
+    private config;
+    private memory;
+    private tools;
+    private client;
+    private maxToolIterations;
+    private scheduler?;
+    private pluginManager?;
+    constructor(config: MusondaConfig, memory: MemoryManager, tools: ToolRegistry, client: OpenAIResponsesClient, scheduler?: any, pluginManager?: any);
+    setScheduler(scheduler: any): void;
+    getScheduler(): any;
+    setPluginManager(pluginManager: any): void;
+    getPluginManager(): any;
+    getMemoryManager(): MemoryManager;
+    getToolRegistry(): ToolRegistry;
+    getClient(): OpenAIResponsesClient;
+    private formatToolStatus;
+    private formatToolReviewStatus;
+    processMessage(input: AgentRunInput): Promise<AgentRunResult>;
+}