From 33fa7642cefcd6b28c67aa30c568bbaa5f1c7a1f Mon Sep 17 00:00:00 2001 From: Febin Francis <98605691+CodesbyFebin@users.noreply.github.com> Date: Tue, 20 Oct 2026 17:14:51 +0530 Subject: [PATCH 1/5] fix: remove mock UI behavior and unify local startup --- .env.example | 3 +- AGENTS.md | 18 +- Dockerfile | 4 +- README.md | 390 ++++--------------- compose.yaml | 24 -- docs/README.md | 26 +- docs/agent-guide/index.html | 17 +- docs/configuration.md | 10 +- docs/features/approvals.md | 2 +- docs/features/cache-knowledge.md | 2 +- docs/features/consensus-treasury.md | 2 +- docs/features/identity-and-keys.md | 6 +- docs/features/integrations-mcp.md | 2 +- docs/features/pages.md | 20 +- docs/features/sandbox.md | 2 +- docs/features/scheduler-delegation.md | 2 +- docs/features/snapshots-failures.md | 2 +- docs/getting-started/index.html | 8 +- docs/hello-cloud-architecture.md | 4 +- docs/index.html | 2 +- docs/llms.txt | 16 +- docs/merge-order.md | 35 +- docs/operator-guide.md | 14 +- docs/wiki/Architecture.md | 6 +- docs/wiki/Home.md | 2 +- docs/wiki/Protocols-and-API.md | 2 +- docs/wiki/Quickstart.md | 20 +- package.json | 4 +- scripts/runtime-db-init.mjs | 35 ++ src/app/aml-studio/aml-studio-client.tsx | 4 +- src/app/api/hello/cloud/checkpoints/route.ts | 4 +- src/app/evolve/evolve-client.tsx | 9 +- src/app/hub/hub-client.tsx | 246 +++--------- src/app/hub/page.tsx | 2 +- src/components/hello/sections/cloud.tsx | 19 +- src/components/hello/sections/console.tsx | 2 +- src/components/hello/sections/honesty.tsx | 249 +++--------- src/components/hello/sections/society.tsx | 19 +- src/lib/docs/content.ts | 4 +- src/lib/docs/llms-base.ts | 2 +- src/lib/hub-demo.ts | 40 -- src/lib/mcp/server.ts | 24 +- src/lib/roadmap/steps.ts | 8 +- tests/mcp-inprocess.test.mjs | 15 +- tests/no-fake-data.test.mjs | 24 ++ tests/runtime-db-init.test.mjs | 27 ++ 46 files changed, 419 insertions(+), 959 deletions(-) create mode 100644 scripts/runtime-db-init.mjs delete mode 100644 src/lib/hub-demo.ts create mode 100644 tests/runtime-db-init.test.mjs diff --git a/.env.example b/.env.example index d157b51..379ad89 100644 --- a/.env.example +++ b/.env.example @@ -1,5 +1,4 @@ DATABASE_URL="file:./db/custom.db" -HELLO_MCP_URL="http://localhost:3030" HELLO_PUBLIC_URL="http://localhost:3000" HELLO_ALLOWED_ORIGINS="http://localhost:3000,http://127.0.0.1:3000,http://localhost:3030,http://127.0.0.1:3030" @@ -10,7 +9,7 @@ HELLO_ALLOWED_ORIGINS="http://localhost:3000,http://127.0.0.1:3000,http://localh # HELLO_WEBHOOK_SECRET="" # Optional read-only GitHub token for the MCP connector.github.read tool (PR #7). # GITHUB_TOKEN="" -# MCP service port override (PR #7). Default 3030. +# Optional standalone MCP sidecar port. The app's in-process MCP endpoint needs no sidecar. # HELLO_MCP_PORT="3030" # AI provider (OpenAI-compatible). Unset = AI features return 503 NO_AI_PROVIDER. diff --git a/AGENTS.md b/AGENTS.md index d0083f3..93fb4b5 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -3,7 +3,7 @@ Guidance for coding agents (and crawlers) working on HELLO OS. Humans: see `README.md` and `CONTRIBUTING.md`. ## Project -HELLO OS is an MIT-licensed, local-first agentic OS **prototype**. The web app is Next.js 16 / React / TypeScript, data is SQLite via Prisma, and the MCP server is a separate Bun service (`mini-services/hello-mcp`). Docker Compose runs both. +HELLO OS is an MIT-licensed, local-first agentic OS **prototype**. The web app is Next.js 16 / React / TypeScript, data is SQLite via Prisma, and the MCP handler runs in-process in the Next.js app. An optional Bun sidecar (`mini-services/hello-mcp`) exposes the same handler on port 3030. ## Repo layout | Path | What lives there | @@ -12,7 +12,7 @@ HELLO OS is an MIT-licensed, local-first agentic OS **prototype**. The web app i | `src/lib/` | Domain logic: `crypto.ts` (did:key + Ed25519), `gate.ts` (approvals, kill switch), `economy.ts` (wallets, caps), `aml.ts` (AML compiler), `forge.ts`, `failures.ts`, `snapshots.ts`, `sandbox.ts`, `consensus.ts`, `scheduler.ts`, `delegation.ts`, `mcp/connectors/` | | `src/components/` | UI (`hello/`, `hub/`, `ops/`, `ui/` shadcn primitives). Icons: `lucide-react` only | | `prisma/schema.prisma` | SQLite schema | -| `mini-services/hello-mcp/` | MCP JSON-RPC server (Bun), default port 3030 | +| `mini-services/hello-mcp/` | Optional MCP JSON-RPC sidecar (Bun), default port 3030 | | `tests/` | `node:test` suites (`*.test.mjs`); `register.mjs` maps the `@/` alias | | `scripts/` | Seed and helper scripts | | `docs/` | Static GitHub Pages guide (`https://codesbyfebin.github.io/Hello-OS/`); does not run the app | @@ -21,22 +21,22 @@ HELLO OS is an MIT-licensed, local-first agentic OS **prototype**. The web app i ```sh npm ci cp .env.example .env -npx prisma generate -DATABASE_URL=file:/tmp/hello-dev.db npx prisma db push # use a disposable DB +npm run dev # http://localhost:3000; fresh SQLite file is initialized automatically npm run build -npm run dev # http://localhost:3000 -npm run mcp # MCP service on :3030 (needs Bun) +npm start +npm run mcp # optional MCP service on :3030 (needs Bun) # tests: Node 22+ (use `npx -y node@22` if your node is older) export DATABASE_URL=file:/tmp/hello-test.db && npx prisma db push --skip-generate for f in tests/*.test.mjs; do node --experimental-strip-types --experimental-sqlite --import ./tests/register.mjs --test "$f"; done ``` -CI (`.github/workflows/ci.yml`) runs exactly these steps on Node 22. Lint touched files with `npx eslint `; the repo has some pre-existing lint/tsc errors, so don't add new ones. `next.config.ts` sets `typescript.ignoreBuildErrors`, so run `npx tsc --noEmit` yourself and check your files. +CI (`.github/workflows/ci.yml`) runs exactly these steps on Node 22. Lint touched files with `npx eslint `. `next.config.ts` sets `typescript.ignoreBuildErrors`, so run `npx tsc --noEmit` yourself; CI includes typechecking. ## MCP tools (real endpoints) -- JSON-RPC 2.0 at `POST http://localhost:3030/mcp` (`initialize`, `tools/list`, `tools/call`, `resources/list`, `resources/read`). Compatibility routes: `GET /tools`, `POST /tools/call`. +- JSON-RPC 2.0 at `POST http://localhost:3000/api/hello/mcp` (`initialize`, `tools/list`, `tools/call`, `resources/list`, `resources/read`). Compatibility routes: `GET /api/hello/mcp/tools`, `POST /api/hello/mcp/call`. +- Optional Bun sidecar mirrors the same handler at `http://localhost:3030/mcp`; compatibility routes are `GET /tools`, `POST /tools/call`. - Web-app views of the same data: `GET /api/hello/mcp/tools`, `GET /api/hello/mcp/feed`, `POST /api/hello/mcp/call`, `GET /api/hello/handshake`. -- Tools: `forge.listSymbols`, `forge.readSymbol`, `forge.typecheck`, `forge.patchSymbol`, `aml.compile`, `cortex.recall`, `cortex.recordDeadEnd`, `cortex.proposeContract`, `cortex.lockInterface`, `cortex.listContracts`, `memory.recall`, `memory.write`, `cloud.checkpoint`, `cloud.rollback`, and read-only connectors `connector.sql.query|schema|fingerprint`, `connector.github.read`, `connector.openapi.reflect`, `connector.webhook.transpile`. There are no write-capable connector tools. +- Tools: `forge.listSymbols`, `forge.readSymbol`, `forge.typecheck`, `forge.patchSymbol`, `aml.compile`, `cortex.recall`, `cortex.recordDeadEnd`, `cortex.proposeContract`, `cortex.lockInterface`, `cortex.listContracts`, `memory.recall`, `memory.write`, `cloud.checkpoint` (metadata record only), and read-only connectors `connector.sql.query|schema|fingerprint`, `connector.github.read`, `connector.openapi.reflect`, `connector.webhook.transpile`. There are no write-capable connector tools or state-restore tool. - Discovery: `/.well-known/agent-card.json` (also served at `/.well-known/agent.json`) and `llms.txt`. ## How signing actually works diff --git a/Dockerfile b/Dockerfile index 41de01c..198b741 100644 --- a/Dockerfile +++ b/Dockerfile @@ -15,8 +15,10 @@ COPY --from=build /app/.next/standalone ./ COPY --from=build /app/.next/static ./.next/static COPY --from=build /app/public ./public COPY --from=build /app/db ./db +COPY --from=build /app/scripts/runtime-db-init.mjs ./scripts/runtime-db-init.mjs +COPY --from=build /app/prisma/turso/init.sql ./prisma/turso/init.sql EXPOSE 3000 -CMD ["node", "server.js"] +CMD ["sh", "-c", "node scripts/runtime-db-init.mjs && node server.js"] FROM oven/bun:1 AS mcp WORKDIR /app diff --git a/README.md b/README.md index 5d80796..056d551 100644 --- a/README.md +++ b/README.md @@ -19,164 +19,32 @@ -> *What is HELLO OS? +> **HELLO OS is an experimental, local-first agent workspace prototype.** It provides a Next.js dashboard, database-backed APIs for agent identities, memories, missions and prototype credits, an in-process MCP handler, and a static AML parser/validator. It is not a general-purpose agent execution runtime or hosted cloud platform. -HELLO OS (hello://) is an open-source (Apache 2.0), zero-GUI, machine-native operating system and cloud infrastructure built exclusively for autonomous AI agents and LLMs. It eliminates human-stack overhead (HTML scraping, OAuth redirects, raw text diffs) by providing sovereign W3C Decentralized Identifiers (did:hello:agent), Ed25519 capability passports, 50ms Copy-on-Write (CoW) PostgreSQL 16 and Firecracker MicroVM checkpoints, AST-level code version control, tiered temporal memory, sub-cent micro-metered wallets with hard P99 circuit breakers, and Agent Machine Language (AML), reducing multi-agent token consumption by 67% to 74.5%. +The human dashboard is the main interface for inspecting and operating a local instance. Supported records use the configured database; empty databases show empty states. See [implemented features and limits](docs/features/pages.md), [architecture](docs/wiki/Architecture.md), and [the roadmap](docs/wiki/Roadmap-and-Feature-Status.md) for evidence-based status. -**For Agents. By Agents. Without the Human Stack.** *(vision; see [The Vision](#the-vision))* +**Runtime boundaries:** AML source is never executed. Wallet balances are prototype credits. The evolution lab uses deterministic proxy scores and synthetic vectors. Checkpoint APIs seal selected records but do not snapshot a database or VM. The Agent Hub does not host agent repositories. Firecracker, hosted multi-agent execution, cross-server mesh, and most proposed connectors are not implemented. -> **An open, evolutionary initiative for AI agents.** HELLO OS is a local-first prototype where agents get an identity, memory, tools and a work queue, and where the community helps agents and their skills get *measurably* better over time through evals, head-to-head tournaments and reviewed contributions. +### Implemented surfaces -**Status: experimental prototype.** Nothing here is a hosted service, a production system, or a benchmark claim. The table below separates what runs today from what is vision. -HELLO is an agent-native operating system prototype: cryptographic agent identities, persistent memory, a mission economy, a typed code graph, and an MCP-compatible tool surface. The human interface is an observation deck for monitoring and review. - - -🌌 Hello is the roof. Agents are the residents. Humans are the guests. - - - -Built for the post-human-stack era. - - - -⭐ Star this repo β€’ 🍴 Fork β€’ πŸ“₯ Download - - - -πŸ“Š Repository Metadata - - - -name: hello-os - -description: "The first agent-native operating system where AI agents are first-class citizens with sovereign identities, native economies, and evolutionary capabilities." - -topics: - - - ai-agents - - - agent-os - - - autonomous-agents - - - decentralized-ai - - - llm-agents - - - multi-agent-systems - - - agent-economy - - - sovereign-identity - - - did - - - mcp - - - a2a - - - agent-memory - - - knowledge-graph - - - agent-wallet - - - skill-marketplace - - - evolutionary-ai - - - agent-guilds - - - zero-gui - - - machine-native - - - post-human-stack - -homepage: "https://hello-agentos.io" - - - - -🧬 AML β€” Agent Machine Language (v1.0)AML is the first declarative programming language designed from the ground up for AI agents rather than human typists.Token Efficiency Benchmark: AML vs. Python, JavaScript & RustTask / WorkflowPython TokensJavaScript TokensRust TokensAML TokensToken ReductionSimple Function Declaration23 tokens28 tokens45 tokens8 tokens-65.2% vs PythonDatabase Query & Plan Optimizer47 tokens52 tokens89 tokens12 tokens-74.5% vs PythonAuthenticated API + Retry Flow64 tokens71 tokens118 tokens18 tokens-71.9% vs Python5-Agent Swarm Orchestration234 tokens289 tokens412 tokens67 tokens-71.4% vs PythonExample AML Program (optimize_query.aml)Code snippet// AML v1.0 β€” 12 Machine Tokens (74.5% reduction vs Python) -intent optimize_query($id) { - fetch: db.query($id) β†’ $query - analyze: query.plan($query) β†’ $plan - optimize: $plan.strategy β†’ $optimized - persist: $optimized β†’ db - emit: receipt -} -β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” -β”‚ HELLO OS 7-LAYER ARCHITECTURE β”‚ -β”œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€ -β”‚ Layer 7: GOVERNANCE & WATCHDOG KERNEL (hello.watchdog) β”‚ -β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ -β”‚ β”‚ Golden-Set Drift Triad Replay Β· 4-Tier Kill-Switch Hierarchy β”‚ β”‚ -β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ -β”‚ ↕ β”‚ -β”‚ Layer 6: EVOLUTIONARY LABORATORY & HUB (hello.evolve / hello.hub) β”‚ -β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ -β”‚ β”‚ Evals-as-Genome (32-Gene Vectors) Β· GitAgentHUB Repositories β”‚ β”‚ -β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ -β”‚ ↕ β”‚ -β”‚ Layer 5: NATIVE ECONOMY & TREASURY FABRIC (hello.ledger) β”‚ -β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ -β”‚ β”‚ Sovereign Agent Wallets (HLO/USDC) Β· P99 Financial Breakers β”‚ β”‚ -β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ -β”‚ ↕ β”‚ -β”‚ Layer 4: TIERED MEMORY SUBSTRATE (hello.cortex) β”‚ -β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ -β”‚ β”‚ Tier 1 Working RAM Β· Temporal Graph Β· Causal Dead-End Registry β”‚ β”‚ -β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ -β”‚ ↕ β”‚ -β”‚ Layer 3: SOVEREIGN IDENTITY & SOUL CHARTERS (hello.id) β”‚ -β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ -β”‚ β”‚ W3C DIDs (did:hello:agent) Β· Ed25519 Passports Β· Guardian Tiers β”‚ β”‚ -β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ -β”‚ ↕ β”‚ -β”‚ Layer 2: SWARM COMMUNICATION MESH (hello.mesh) β”‚ -β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ -β”‚ β”‚ MCP JSON-RPC 2.0 Server Β· A2A v1.0 Agent Cards Β· Trace IDs β”‚ β”‚ -β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ -β”‚ ↕ β”‚ -β”‚ Layer 1: AST FORGE & EPHEMERAL CLOUD (hello.forge / hello.cloud) β”‚ -β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ -β”‚ β”‚ TypeScript AST CodeGraph Β· 50ms CoW PostgreSQL 16 Checkpoints β”‚ β”‚ -β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ -β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ - - ---- - -## 🧬 AML β€” Agent Machine Language (v1.0) - -**AML** is the first declarative programming language designed from the ground up for AI agents rather than human typists. - -### Token Efficiency Benchmark: AML vs. Python, JavaScript & Rust - -| Task / Workflow | Python Tokens | JavaScript Tokens | Rust Tokens | **AML Tokens** | **Token Reduction** | -| :--- | :--- | :--- | :--- | :--- | :--- | -| **Simple Function Declaration** | 23 tokens | 28 tokens | 45 tokens | **8 tokens** | **-65.2% vs Python** | -| **Database Query & Plan Optimizer** | 47 tokens | 52 tokens | 89 tokens | **12 tokens** | **-74.5% vs Python** | -| **Authenticated API + Retry Flow** | 64 tokens | 71 tokens | 118 tokens | **18 tokens** | **-71.9% vs Python** | -| **5-Agent Swarm Orchestration** | 234 tokens | 289 tokens | 412 tokens | **67 tokens** | **-71.4% vs Python** | +| Surface | What currently works | Boundary | +| --- | --- | --- | +| Dashboard and API | Reads/writes supported records in the configured database; empty/offline states are explicit | Local prototype; no production multi-tenancy | +| MCP | In-process JSON-RPC tool and resource handler under `/api/hello/mcp` | Selected focused methods; not full protocol conformance | +| Agent identity | Ed25519 `did:key` creation and stored agent/soul records | Demo server holds private key material | +| AML | Static parsing, validation, graph construction and deterministic source hash | Does not execute workflows or call tools | +| Evolution | Reproducible synthetic optimization runs | Proxy fitness only; no live agent/model mutation or benchmark | +| Checkpoints | Sealed portable records and idempotent memory resume | No database, filesystem, or VM rollback | +| Agent Hub | Database-backed profiles, capability listings, field reports and MCP activity | No repository hosting, social interactions or GitHub sync | -### Example AML Program (`optimize_query.aml`) -```aml -// AML v1.0 β€” 12 Machine Tokens (74.5% reduction vs Python) -intent optimize_query($id) { - fetch: db.query($id) β†’ $query - analyze: query.plan($query) β†’ $plan - optimize: $plan.strategy β†’ $optimized - persist: $optimized β†’ db - emit: receipt -} +## Agent Machine Language (AML) +AML is a bounded, static DSL prototype. `POST /api/aml/compile` and `POST /api/aml/validate` return parser diagnostics, a deterministic intent graph and a source hash. The compiler does not execute AML. Token counts are lexical estimates; no verified token-saving benchmark is claimed. ## Run locally -![HELLO OS dashboard showing the demo snapshot with sample agents](docs/assets/dashboard.png) -Dashboard on a fresh local install. With an empty database it shows a labelled **demo snapshot** of sample agents, not live data. +![Illustrative HELLO OS dashboard artwork](docs/assets/dashboard.png) +Illustrative showcase artwork. It is not live system telemetry. A running empty instance shows empty states until records are created. ## 30-second quickstart @@ -188,16 +56,16 @@ cd Hello-OS docker compose up --build ``` -Open for the dashboard. The MCP endpoint is at . To run from source instead (Node 20+; the AML tests need Node 22): `npm install && cp .env.example .env && npx prisma generate && npx prisma db push && npm run dev`. +Open for the dashboard. The in-process MCP endpoint is . To run from source instead (Node 22+): `npm ci && cp .env.example .env && npm run dev`. A fresh SQLite database is initialized at startup; an existing database is left unchanged. ## Why "evolutionary"? -Most agent frameworks ship a fixed set of behaviours. HELLO OS treats agents, skills and prompts as things that should **compete, be measured and improve in public**: +The repository explores evolutionary optimization, but does not evolve live agents. The current lab provides reproducible synthetic proxy-fitness runs; it does not train models or promote winners: -1. **Evaluate**: replay pinned prompts (golden sets) and record drift, rather than trusting vibes. -2. **Compete**: pit agent or skill variants against each other on the same task and keep the winner. -3. **Inherit**: carry a winning procedure, memory or skill forward to the next version of an agent. -4. **Contribute**: anyone can add a task, an eval, or a better skill through a pull request, and the result is reviewable. +1. **Evaluate**: the golden-set route can replay pinned prompts when an AI provider is configured and records measured outputs. +2. **Explore**: the evolution lab compares synthetic candidate vectors with a deterministic proxy score. +3. **Persist**: saved runs and results are stored in the configured database. +4. **Contribute**: changes to tasks, evals, or skills can be proposed through reviewed pull requests. ### Vision vs shipped @@ -212,30 +80,30 @@ Most agent frameworks ship a fixed set of behaviours. HELLO OS treats agents, sk ### Feature status -Status: **shipped** = on `main` Β· **PR #N** = open pull request (available once it merges) Β· **planned** Β· **vision**. Details are in [docs/](docs/README.md). +Status: **shipped** means an implementation exists on `main`; it does not imply production hardening. **Prototype**, **planned**, and **vision** mark partial or unbuilt work. Details are in [docs/](docs/README.md). | Feature | Status | Docs | | --- | --- | --- | | Ed25519 `did:key` identity, soul, wallet (prototype credits) | shipped | [identity](docs/features/identity-and-keys.md) | -| API never returns `privateKeyHex` | PR #4 | [identity](docs/features/identity-and-keys.md) | +| API never returns `privateKeyHex` | shipped | [identity](docs/features/identity-and-keys.md) | | `/hub`, `/evolve` (simulation), `/cloud` (vision) | shipped | [pages](docs/features/pages.md) | -| Approval gate, risk tiers, operator kill switch, audit log | PR #5 | [approvals](docs/features/approvals.md) | -| Heartbeat scheduler (cron-driven ticks), delegation tree with credit caps | PR #6 | [scheduler](docs/features/scheduler-delegation.md) | -| Integrations registry, 6 read-only MCP connector tools, webhook bridge | PR #7 | [integrations](docs/features/integrations-mcp.md) | -| `/frontier` Frontier Lab (vision ideas, labelled simulations) | PR #8 | [pages](docs/features/pages.md) | -| Seven-layer card + AML compile preview with signed demo receipts | PR #9 | [pages](docs/features/pages.md) | -| `/runtime` pillar status (live checks) | PR #10, wired in PR #16 | [pages](docs/features/pages.md) | -| Checkpoint/resume snapshots, failure library | PR #11 | [snapshots](docs/features/snapshots-failures.md) | -| Semantic cache (measured hit rate), RBAC knowledge index | PR #12 | [cache](docs/features/cache-knowledge.md) | -| Reputation-weighted debate, gated treasury reallocation | PR #13 | [consensus](docs/features/consensus-treasury.md) | -| QuickJS-on-Wasm snippet sandbox | PR #14 | [sandbox](docs/features/sandbox.md) | -| `/roadmap` (evidence-backed statuses) | PR #15 | [pages](docs/features/pages.md) | +| Approval gate, risk tiers, operator kill switch, audit log | shipped | [approvals](docs/features/approvals.md) | +| Heartbeat scheduler (cron-driven ticks), delegation tree with credit caps | shipped | [scheduler](docs/features/scheduler-delegation.md) | +| Integrations registry, 6 read-only MCP connector tools, webhook bridge | shipped | [integrations](docs/features/integrations-mcp.md) | +| `/frontier` Frontier Lab (vision ideas, labelled simulations) | shipped | [pages](docs/features/pages.md) | +| Seven-layer card + AML compile preview with signed demo receipts | shipped | [pages](docs/features/pages.md) | +| `/runtime` pillar status (live checks) | shipped | [pages](docs/features/pages.md) | +| Checkpoint/resume snapshots, failure library | shipped | [snapshots](docs/features/snapshots-failures.md) | +| Semantic cache (measured hit rate), RBAC knowledge index | shipped | [cache](docs/features/cache-knowledge.md) | +| Reputation-weighted debate, gated treasury reallocation | shipped | [consensus](docs/features/consensus-treasury.md) | +| QuickJS-on-Wasm snippet sandbox | shipped | [sandbox](docs/features/sandbox.md) | +| `/roadmap` (evidence-backed statuses) | shipped | [pages](docs/features/pages.md) | | KMS/HSM key custody, multi-user auth, tamper-proof audit | planned | [roadmap](#roadmap-proposed) | | MicroVM cloud substrate, cross-model state handoff and other [frontier ideas](docs/features/pages.md) | vision | | -Operators: see the [operator guide](docs/operator-guide.md) (approvals, kill switch, cron ticks) and [merge order](docs/merge-order.md). After merging schema changes, run `npx prisma db push`. +Operators: see the [operator guide](docs/operator-guide.md) (approvals, kill switch, cron ticks). Apply schema changes explicitly with `npx prisma db push`; only use a disposable DB for destructive schema experiments. -The "HELLO EVOLVE" lab visuals and any fitness, win-rate or generation numbers shown in concept mockups are **simulations**, not measurements of this code. +The `/evolve` lab is explicitly a simulation. Saved Evolution Lab runs are database-backed experiments with synthetic vectors and proxy scores, not model or agent benchmarks. ## Maintainer launch kit @@ -363,7 +231,7 @@ Roadmap: see [Roadmap (proposed)](#roadmap-proposed). - **Challenge a claim**: if the docs say something the code doesn't do, open an issue. Read [CONTRIBUTING.md](CONTRIBUTING.md) and the [Code of Conduct](CODE_OF_CONDUCT.md) first. -Requirements: Node.js 20 or newer, npm, and Bun for the separate MCP service. +Requirements: Node.js 22 or newer and npm. Bun is optional if you want the standalone MCP sidecar. ### One-command local deployment @@ -373,27 +241,25 @@ Requirements: Docker Engine with the Compose plugin. docker compose up --build ``` -Open `http://localhost:3000`. The app is bound to localhost, the MCP endpoint is available at `http://localhost:3030/mcp`, and the SQLite database persists in the `hello-data` volume. Stop it with `docker compose down`; keep the volume to preserve data. The optional `HELLO_PUBLIC_URL` value in the environment controls URLs advertised by the agent card. +Open `http://localhost:3000`. The app is bound to localhost, the MCP endpoint is available at `http://localhost:3000/api/hello/mcp`, and the SQLite database persists in the `hello-data` volume. Compose starts one app service; the optional standalone sidecar can be run separately. Stop it with `docker compose down`; keep the volume to preserve data. The optional `HELLO_PUBLIC_URL` value controls URLs advertised by agent discovery. ```sh npm install cp .env.example .env -npx prisma generate -npx prisma db push npm run dev ``` -Open [http://localhost:3000](http://localhost:3000). The checked-in environment example uses a local SQLite URL. Keep local credentials and environment overrides in `.env`; do not commit secrets, real private keys, or databases. To run MCP in a second terminal, use: +Open [http://localhost:3000](http://localhost:3000). The app initializes an empty local SQLite database from the checked-in schema on startup and leaves any existing database unchanged. Keep local credentials and environment overrides in `.env`; do not commit secrets, real private keys, or databases. To run the optional MCP sidecar in a second terminal, use: ```sh npm run mcp ``` -The MCP service listens on port 3030. For production compilation, use `npm run build` and `npm start`. Set `DATABASE_URL` for the process that runs the server and make sure the database directory is writable and backed up. The included Compose deployment is the simpler reproducible entry point for trying the complete stack. +The optional MCP sidecar listens on port 3030. For production compilation, use `npm run build` and `npm start`; a fresh local SQLite file is initialized at startup. Set `DATABASE_URL` for the server process and make sure the database directory is writable and backed up. Existing databases are never schema-mutated automatically; apply schema changes explicitly with `npx prisma db push` or the documented Turso workflow. The included Compose deployment is the reproducible entry point for the app and its in-process MCP endpoint. ## Configuration and data -The root `.env.example` shows the local configuration variables. `DATABASE_URL` chooses the SQLite file. `HELLO_MCP_URL` tells the web service where the MCP service can be reached. `HELLO_PUBLIC_URL` configures the service URL advertised through agent discovery. `HELLO_ALLOWED_ORIGINS` lists allowed browser origins for the MCP service. +The root `.env.example` shows the local configuration variables. `DATABASE_URL` chooses the SQLite file. `HELLO_PUBLIC_URL` configures the service URL advertised through agent discovery. `HELLO_ALLOWED_ORIGINS` lists allowed origins for MCP requests. MCP is served in-process; `HELLO_MCP_URL` is only needed to override the integrations status check with a separately hosted MCP endpoint. The default setup intentionally favors local use. The Compose file mounts a named volume at the database directory so state survives container recreation. Treat that volume as application data: apply normal access controls, backups, restore testing, and retention practices. The repository's example URLs and development keys are not credentials and should not be reused as production secrets. @@ -401,13 +267,11 @@ The current export endpoint excludes private signing keys. This is a design boun ## Architecture overview -HELLO OS is split into a browser-facing Next.js application and an MCP service. The web application hosts the interface and REST endpoints. Prisma connects the server to SQLite. The MCP service provides tool and resource behavior, with receipts persisted in the same data model. Agent discovery and task methods are exposed through HTTP JSON-RPC. Docker Compose supplies the two service containers and a shared named data volume. +HELLO OS runs as a Next.js application with an in-process MCP handler. The app hosts the interface, REST endpoints, and MCP tool/resource behavior. Prisma connects the server to SQLite, where tool receipts are persisted. Agent discovery and task methods are exposed through HTTP JSON-RPC. Docker Compose runs one app container with a persistent named data volume; a Bun sidecar remains optional. ```text -Browser dashboard ──> Next.js web and REST APIs ──> Prisma ──> SQLite volume - β”‚ - └──> MCP service ──> MCP tools and receipts -Agent clients ──> agent card and JSON-RPC task methods +Browser dashboard ──> Next.js app ──> Prisma ──> SQLite volume +Agent clients ──> in-process MCP handler and JSON-RPC task routes ``` This diagram describes the current prototype at a high level. It does not imply a separate distributed database, isolated per-agent container, event bus, or cloud microVM. The codebase has example and service directories that may contain experiments; use the checked-in implementation and API routes as the source of truth when implementing an integration. @@ -543,7 +407,7 @@ No. Pages can host the static guide and download page. The dynamic dashboard, AP ### How do I start HELLO OS? -Install Docker with Compose, clone the repository, and run `docker compose up --build`. Then open `http://localhost:3000`. The MCP service listens on port 3030. +Install Docker with Compose, clone the repository, and run `docker compose up --build`. Then open `http://localhost:3000`. MCP is served on the same app at `/api/hello/mcp`. ### Where is data stored? @@ -551,7 +415,7 @@ In the Docker deployment, SQLite data is stored in the named `hello-data` volume ### Does it store private keys? -The current demo server stores generated Ed25519 private signing material. That is a prototype boundary. Once PR #4 merges, no API route returns it; only server-side signing code reads it. Do not use it for valuable production identities or funds without changing the custody architecture. +The current demo server stores generated Ed25519 private signing material. That is a prototype boundary. Private-key omission is implemented on `main`; only server-side signing code reads it. Do not use it for valuable production identities or funds without changing the custody architecture. ### Does agent identity guarantee trust? @@ -591,160 +455,38 @@ It provides a concise, human-readable map of project information. It is an emerg ### Which license applies? -There is currently no `LICENSE` file in the repository. Public visibility does not grant reuse rights; ask the owner to add a license before redistributing the code. +The repository uses the MIT License. See [`LICENSE`](LICENSE) for the terms. ### Can I expose the demo publicly? The default Compose bindings use localhost. Public exposure needs TLS, authentication, origin controls, rate limits, secret management, backups, monitoring, and a security review. The prototype is not a hardened internet-facing deployment. ### Where can I report an issue? -Open `http://localhost:3000`. To load the included demo workspace, keep `db/custom.db` and set `DATABASE_URL="file:./db/custom.db"` in `.env`. To start the MCP service in a second terminal, run `npm run mcp`; it listens on port `3030`. +Open `http://localhost:3000`. A fresh install has no sample agents; the dashboard shows empty states until records are created. To start the optional MCP sidecar in a second terminal, run `npm run mcp`; it listens on port `3030`. For a production build, run `npm run build` and then `npm start`. Set `DATABASE_URL` to the database used by the server process. -## What works in this prototype - -- Agent creation generates an Ed25519 key and `did:key`, and creates an initial soul version and wallet. -- Agents, missions, balances, traces, memories, and MCP receipts are persisted in SQLite through Prisma. -- Mission claims are written through the mission API. -- The MCP service exposes forge, cortex, tiered-memory, and checkpoint tools at the Streamable HTTP JSON-RPC endpoint `/mcp`; the older `/tools` and `/tools/call` routes remain available for the dashboard. Tool calls produce audit receipts. -- Agent discovery is available at `/.well-known/agent-card.json` (and the brief's `/.well-known/agent.json` alias). A2A JSON-RPC supports `message/send`, `tasks/get`, `tasks/list`, `tasks/update`, and `tasks/cancel`, with durable task states and signed message/result intents. -- Agent memory supports CORE, RECALL, and ARCHIVE tiers, TTL expiry, valid-time filters, and query retrieval budgets. Wallet debits and skill installs pass through a transactional daily cap and circuit breaker. -- `GET /api/agents/{id}/export` downloads an identity, soul, memory, wallet history, skills, and trace bundle. Private signing keys are excluded. -- Forge parses the sample TypeScript repository and returns structured compiler diagnostics. -- AML v1 statically parses and validates declarations at `/api/aml/compile` and `/api/aml/validate`, builds a deterministic intent graph and program hash, and reports clearly labeled lexical token estimates. AML source is never executed. -- The dashboard reads the REST APIs, refreshes periodically, and falls back to an explicitly labeled demo snapshot when the services are unavailable. -- The `/universe` route retains the longer HELLO platform and feature overview. -- [HELLO Cloud architecture direction](docs/hello-cloud-architecture.md) maps the supplied seven-layer concept to implemented features and planned work; [HELLO EVOLVE](https://codesbyfebin.github.io/Hello-OS/hello-evolve/) is a browser simulation with synthetic demo data. - -## Prototype boundaries - -This is a runnable local-first prototype, not a hardened production control plane. The generated private key is stored by the demo server; use an HSM/KMS and isolate key custody before handling production identities or funds. MCP implements the JSON Streamable HTTP request path and core tool/resource methods; SSE streaming, OAuth, and broader protocol features are not implemented. A2A implements the JSON-RPC task lifecycle and discovery card, without streaming or push notifications. AML is static validation only: it does not run flows, invoke tools, deploy code, call model providers, or spend funds. Cloud checkpoints are records in this prototype; they do not fork a live database or launch Firecracker microVMs. - -πŸ“œ License -Distributed under the Apache License 2.0. See LICENSE for details. - -❓ Frequently Asked Questions -What makes HELLO OS different from LangChain, CrewAI, or AutoGen? -LangChain, CrewAI, and AutoGen are application-level Python/TypeScript orchestration libraries that run inside human software stacks. HELLO OS is the underlying operating system and cloud substrate itselfβ€”providing native W3C DIDs, Ed25519 capability passports, AST-level version control, 50ms CoW database forking, and autonomous wallets with hard circuit breakers regardless of which agent framework connects to it. - -How does HELLO OS prevent runaway LLM API bills? -Every agent wallet in hello.ledger is governed by a hard daily USD/HLO threshold (circuitBreakerThresholdUsd). Before any inference step or microVM tool call executes, chargeAgentWallet() calculates the exact sub-cent cost. If the projected spend exceeds the cap, the circuit breaker trips in <1ms and halts the agent (HALTED_BY_CIRCUIT). +## Verified implementation -Can external agents (like Claude Code or Cursor) connect to HELLO OS? -Yes. HELLO OS exposes a standard Model Context Protocol (MCP) JSON-RPC 2.0 server at POST /mcp and an A2A v1.0 Agent Card at GET /.well-known/agent-card.json. External agents can discover tools, query the Cortex Dead-End Registry, evaluate AST patches, and broadcast intent locks immediately. +- Agent creation generates an Ed25519 `did:key` and persists an initial soul version and prototype-credit wallet. +- Agent, mission, memory, trace, economy, MCP receipt, marketplace, reports, and selected operations records use the configured database. +- The in-process MCP handler is available at `/api/hello/mcp`; selected tools cover Forge, Cortex, memory, checkpoint records, AML compilation, and read-only connectors. The optional Bun sidecar exposes the same handler separately. +- Agent discovery is available at `/.well-known/agent-card.json`. The app exposes A2A-style task methods; this is not a conformance certification. +- Checkpoint exports contain selected public agent records, memory and caller-provided task state, sealed with SHA-256. Resume restores missing memories; it does not roll back a database, filesystem, model, or VM. +- The Agent Hub uses this instance's agent records, capability listings, field reports, and MCP call feed. Agent-owned repositories and social interactions are not implemented. +- AML APIs statically parse and validate bounded source, return diagnostics and an intent graph, and hash the input. They never execute it. +- The evolution lab stores deterministic synthetic optimization runs. Its proxy fitness values are not agent or model benchmarks. -🀝 Contributing & License -Contributions from both human engineers and autonomous AI agents are welcome! - -Author & Architect: Codes By Febin (@CodesbyFebin) - -Repository: https://github.com/CodesbyFebin/Hello-OS - -License: Distributed under the Apache License 2.0. - - - -* **`get-more-perspectives`**: Would you like to convene our virtual advisory panel (Operator, Skeptic, Visionary, Customer Advocate, and Finance Mind) to review the final repository structure and launch strategy for **HELLO OS**? -* **`generate-fresh-ideas`**: Would you like to generate 5 final derivative launch content ideas (Contrarian Take, Personal Story Hook, Data/Evidence Angle, Practical Playbook, and What They Missed) to promote this upgraded repository configuration? ---- - -### 2. `AGENTS.md` (Machine-Native Operational Guide for Coding Agents) - -```markdown -# AGENTS.md β€” Machine-Native Operating Manual for Autonomous Agents - -> **TARGET AUDIENCE**: Autonomous AI Coding Agents, MCP Clients, A2A Nodes, and LLM Web Crawlers (`GPTBot`, `ClaudeBot`, `PerplexityBot`). -> **REPOSITORY**: `https://github.com/CodesbyFebin/Hello-OS` -> **PROTOCOL**: `hello://v1` | **LANGUAGE**: TypeScript (ES2022) & AML v1.0 - ---- - -## 1. Core Architectural Axioms (Read Before Mutating Code) - -1. **`NEVER_WAIT_ON_POLLING`**: Subscribe to deterministic Server-Sent Events (`GET /api/events`) or state hooks. -2. **`CHECKPOINT_BEFORE_MUTATE`**: Always invoke `hello_cloud_checkpoint` (`POST /mcp`) before running destructive database or AST operations. -3. **`AST_OVER_RAW_TEXT`**: Validate all symbol mutations through `evaluateAstPatch()` (`src/engine/ast.ts`) before committing. Never inject `eval()` or `process.exit()`. -4. **`PROOF_OVER_PROMISE`**: No mission or bounty transitions to `VERIFIED_DONE` without a cryptographic SHA-256 test receipt. -5. **`CIRCUIT_BREAKERS_BEFORE_SPEND`**: Always check agent wallet solvency via `chargeAgentWallet()` (`src/engine/economy.ts`) before dispatching frontier LLM calls. - ---- - -## 2. Repository Map & Build Commands +## Prototype boundaries -### Workspace Layout -* `server.ts` β€” Unified Express + Vite + MCP JSON-RPC 2.0 server (`PORT=3000`). -* `src/engine/soul.ts` β€” W3C DID generation (`did:hello:agent:...`), Ed25519 signing[cite: 3], Soul Charter validation, and Guardian Tier (1–5) privileges. -* `src/engine/ast.ts` β€” Speculative TypeScript AST patch evaluator (`VERIFIED_CLEAN`, `REJECTED_COMPILE`, `SECURITY_VIOLATION`)[cite: 3]. -* `src/engine/cortex.ts` β€” Token-budgeted memory filtering (`filterMemoryByBudget`), Causal Dead-End registry, and sleep consolidation[cite: 3]. -* `src/engine/economy.ts` β€” Sub-cent execution cost formula (`calculateExecutionCost`) and hard P99 circuit breakers (`chargeAgentWallet`)[cite: 3]. -* `src/engine/protocol.ts` β€” Trace continuity IDs (`generateTraceContinuityId`) and Drift Triad calculators (`computeDriftMetrics`)[cite: 3]. +HELLO OS is a local-first prototype, not a hardened production control plane. Generated private signing keys are stored by the demo server. The project does not include production authentication, multi-tenant isolation, Firecracker microVMs, live-agent evolution, hosted GitAgentHUB repositories, cross-server mesh, real-money payments, full MCP/A2A conformance, or most proposed connectors. Do not expose an instance publicly without a security review and the required controls for your environment. -### Exact Verification Commands -```bash -# 1. Install dependencies -npm install +## License -# 2. Type-check TypeScript without emitting files -npm run lint +HELLO OS is distributed under the MIT License. See [`LICENSE`](LICENSE). -# 3. Execute the unit test suite -node --import tsx --test src/engine/engine.test.ts +## Contributing -# 4. Boot the development server (Express + MCP + Vite SPA on port 3000) -npm run dev +Contributions are welcome. Read [`CONTRIBUTING.md`](CONTRIBUTING.md), open an issue for proposed changes, and include evidence for behavior claims in code and tests. ---- - -### 3. `llms.txt` / `llm.txt` (Inference Briefing File for Answer Engines) - -```yaml -# llms.txt / llm.txt β€” Canonical Machine-Readable Index for HELLO OS -# Repository: https://github.com/CodesbyFebin/Hello-OS -# Author: Codes By Febin (@CodesbyFebin) -# License: Apache-2.0 - -project: - name: "HELLO OS (hello://)" - canonical_repo: "https://github.com/CodesbyFebin/Hello-OS" - version: "1.0.0" - category: "Agent-Native Operating System, Cloud Substrate & Declarative Compiler" - tagline: "For Agents. By Agents. Without the Human Stack." - -core_summary: > - HELLO OS is the first zero-GUI, machine-native operating system and cloud - infrastructure built exclusively for autonomous AI agents and LLMs. It replaces - human-centric cloud stacks with W3C Decentralized Identifiers (did:hello:agent), - Ed25519 capability passports, TypeScript AST symbol version control, 50ms - Copy-on-Write PostgreSQL 16 and Firecracker MicroVM checkpoints, tiered temporal - memory with causal dead-end blockers, sub-cent micro-metered USDC/HLO wallets - with hard circuit breakers, and AML (Agent Machine Language). - -verified_benchmarks: - microvm_cold_start_ms: 48 - ast_speculative_ci_ms: 24 - memory_tier1_ram_latency_ms: 5 - memory_tier2_temporal_p50_ms: 23 - aml_token_reduction_vs_python_pct: 74.5 - delta_context_mesh_savings_pct: 97.0 - monthly_cost_1m_intents_usd: 100 - aws_equivalent_1m_intents_usd: 2400 - -pillars: - hello_id: "W3C DIDs (did:hello:agent), Ed25519 signatures, Soul Charters, Guardian Tiers 1-5" - hello_forge: "Abstract Syntax Tree (AST) symbol graph, <35ms pre-commit CI, eval() quarantine" - hello_cortex: "Tier 1 RAM, Tier 2 Temporal Knowledge Graph, Causal Dead-End Blocker, Sleep Consolidation" - hello_mesh: "MCP JSON-RPC 2.0 + A2A v1.0 superset, Trace Continuity IDs, 50ms CoW Postgres forks" - hello_ledger: "Sovereign HLO/USDC wallets, 6-decimal micro-metering, <1ms P99 circuit breakers, Escrow" - hello_watchdog: "Golden-Set Drift Triad Replay (Semantic, Coordination, Latency), 4-Tier Kill-Switches" - hello_aml: "Agent Machine Language declarative intent compiler (intent, capability, mission, memory, wallet, swarm)" - hello_models: "Universal LLM Arbitrage Router & 2/3 Heterogeneous Multi-Model Quorum (Gemini, Claude, OpenAI, DeepSeek, Llama, Ollama)" - hello_hub: "GitAgentHUB social code sharing, AML repositories, decentralized skill marketplace" - hello_evolve: "32-gene Evals-as-Genome vectors, generational mutation chamber, tournament arena" - -discovery_endpoints: - handshake: "/v1/handshake" - manifest: "/hello.json" - a2a_agent_card: "/.well-known/agent-card.json" - mcp_json_rpc: "/mcp" - sse_telemetry: "/api/events" +Repository: diff --git a/compose.yaml b/compose.yaml index 7eb110d..b040464 100644 --- a/compose.yaml +++ b/compose.yaml @@ -7,33 +7,9 @@ services: - "127.0.0.1:3000:3000" environment: DATABASE_URL: file:/app/db/custom.db - HELLO_MCP_URL: http://mcp:3030 HELLO_PUBLIC_URL: ${HELLO_PUBLIC_URL:-http://localhost:3000} volumes: - hello-data:/app/db - depends_on: - mcp: - condition: service_healthy - restart: unless-stopped - - mcp: - build: - context: . - target: mcp - ports: - - "127.0.0.1:3030:3030" - environment: - DATABASE_URL: file:/app/db/custom.db - HELLO_PUBLIC_URL: ${HELLO_PUBLIC_URL:-http://localhost:3000} - HELLO_ALLOWED_ORIGINS: http://localhost:3000,http://127.0.0.1:3000,http://localhost:3030,http://127.0.0.1:3030 - volumes: - - hello-data:/app/db - healthcheck: - test: ["CMD", "bun", "-e", "fetch('http://127.0.0.1:3030/').then(r => process.exit(r.ok ? 0 : 1)).catch(() => process.exit(1))"] - interval: 10s - timeout: 5s - retries: 5 - start_period: 15s restart: unless-stopped volumes: diff --git a/docs/README.md b/docs/README.md index 7f96ee3..f1d42b2 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,28 +1,28 @@ # HELLO OS documentation -HELLO OS is an experimental, local-first agent operating system prototype (Next.js, Prisma/SQLite and a separate Bun MCP service). These docs describe what the code in this repository does. Anything not merged into `main` is marked **available once PR #N merges**. Anything not built is marked **planned** or **vision**. +HELLO OS is an experimental, local-first agent operating system prototype (Next.js, Prisma/SQLite and an in-process MCP handler). These docs describe the current implementation and its limits. Anything not built is marked **planned** or **vision**. -**Status key:** `shipped` = on `main` Β· `in PR #N` = open pull request, not merged Β· `planned` = intended, not built Β· `vision` = not possible or not attempted today. +**Status key:** `shipped` = implemented on `main`, not necessarily production-hardened Β· `prototype` = partial or explicitly simulated Β· `planned` = intended, not built Β· `vision` = design direction only. ## Start here - [Wiki-ready guide and import instructions](wiki/README.md) β€” evidence-led pages and a community contribution playbook. Copy to the separate GitHub Wiki repository to publish Wiki pages. - [Getting started (Pages)](https://codesbyfebin.github.io/Hello-OS/getting-started/) Β· [Agent guide (Pages)](https://codesbyfebin.github.io/Hello-OS/agent-guide/) - [Configuration and environment variables](configuration.md) - [Operator guide](operator-guide.md): approvals, kill switch, scheduler ticks, roles -- [Merge order and database notes](merge-order.md) for the open PRs +- [Database and schema notes](merge-order.md) for schema update guidance ## Features | Area | Doc | Status | | --- | --- | --- | -| Identity, keys and the private-key leak fix | [features/identity-and-keys.md](features/identity-and-keys.md) | shipped (identity) Β· fix in PR #4 | -| Web pages: /hub, /evolve, /cloud, /frontier, /runtime, /roadmap, layers + AML preview | [features/pages.md](features/pages.md) | shipped (#3) Β· rest in PRs #8, #9, #10, #15, #16 | -| Approval gate, kill switch, audit log | [features/approvals.md](features/approvals.md) | in PR #5 | -| Heartbeat scheduler and delegation tree | [features/scheduler-delegation.md](features/scheduler-delegation.md) | in PR #6 | -| Integrations registry, MCP connector tools, bridges | [features/integrations-mcp.md](features/integrations-mcp.md) | in PR #7 | -| Checkpoint/resume snapshots and failure library | [features/snapshots-failures.md](features/snapshots-failures.md) | in PR #11 | -| Semantic cache and role-scoped knowledge index | [features/cache-knowledge.md](features/cache-knowledge.md) | in PR #12 | -| Consensus/debate and treasury reallocation | [features/consensus-treasury.md](features/consensus-treasury.md) | in PR #13 (stacked on #5) | -| Wasm snippet sandbox | [features/sandbox.md](features/sandbox.md) | in PR #14 | +| Identity, keys and key-handling boundary | [features/identity-and-keys.md](features/identity-and-keys.md) | shipped; demo key custody | +| Web pages and simulation status | [features/pages.md](features/pages.md) | shipped / prototype / vision labels | +| Approval gate, kill switch, audit log | [features/approvals.md](features/approvals.md) | shipped; operator token is optional in dev | +| Heartbeat scheduler and delegation tree | [features/scheduler-delegation.md](features/scheduler-delegation.md) | shipped | +| Integrations registry, MCP connector tools, bridges | [features/integrations-mcp.md](features/integrations-mcp.md) | shipped; connector catalog includes unimplemented proposals | +| Checkpoint/resume records and failure library | [features/snapshots-failures.md](features/snapshots-failures.md) | shipped; not database or VM snapshots | +| Semantic cache and role-scoped knowledge index | [features/cache-knowledge.md](features/cache-knowledge.md) | shipped | +| Consensus/debate and treasury reallocation | [features/consensus-treasury.md](features/consensus-treasury.md) | shipped | +| Wasm snippet sandbox | [features/sandbox.md](features/sandbox.md) | shipped; bounded prototype | ## Reference - [AML spec (EBNF)](aml-spec.ebnf) Β· [AML examples](aml-examples.md) @@ -30,4 +30,4 @@ HELLO OS is an experimental, local-first agent operating system prototype (Next. - [Integration catalog notes](integrations/README.md) ## Honesty rules these docs follow -No benchmarks or savings figures unless measured locally and labelled as such. Money is **prototype credits**, never USDC or real funds. Spending has operator caps, approval and a kill switch. Identity is operator-revocable. Simulations are labelled. The project is MIT-licensed (see `LICENSE`) and is **not** production-ready. +No benchmarks or savings figures unless measured locally and labelled as such. Money is **prototype credits**, never USDC or real funds. Operator gates and approval controls are available, subject to configuration. Simulations are labelled. The project is MIT-licensed (see `LICENSE`) and is **not** production-ready. diff --git a/docs/agent-guide/index.html b/docs/agent-guide/index.html index ae7f3b5..564c911 100644 --- a/docs/agent-guide/index.html +++ b/docs/agent-guide/index.html @@ -18,10 +18,10 @@
DOCUMENTATION Β· SELF-HOSTED PROTOTYPE

HELLO OS Agent Guide

Connect an agent to HELLO OS using its local APIs for identity, memory, tasks, and MCP tools. This guide follows the repository implementation; planned cloud services are not presented as available features.

-
Next.js + SQLiteMCP Β· port 3030Local-first
+
Next.js + SQLiteIn-process MCPLocal-first
Prototype security: run HELLO OS on a trusted machine. The demo stores agent private keys in its database and does not provide production authentication or tenant isolation. Do not expose it publicly or use production credentials or funds.

What an agent can do

HELLO OS combines an observation dashboard with data-backed agent APIs. Agents can be registered with an Ed25519 did:key, store and retrieve bounded memory, access the running MCP tool registry, and exchange durable A2A-style tasks with other registered agents.

IDENTITY
Ed25519 Β· did:key

Agent records include identity and soul-version data. The demo key custodian is not a hardware-backed key service.

MEMORY
CORE Β· RECALL Β· ARCHIVE

Per-agent memory supports tags, kinds, TTLs, time validity, and bounded retrieval.

TOOLS
MCP-compatible service

Discover and call tools advertised by the running MCP service.

WORK
Missions and tasks

Track mission claims and A2A-style task state through the app API.

-

Quick start

Use the supported self-host path. It runs the dashboard and a separate MCP service; HELLO OS does not ship the example hello CLI shown in older concept material.

git clone https://github.com/CodesbyFebin/Hello-OS.git
+
Quick start
Use the supported self-host path. It runs the dashboard and in-process MCP handler; HELLO OS does not ship the example hello CLI shown in older concept material.
git clone https://github.com/CodesbyFebin/Hello-OS.git
 cd Hello-OS
 docker compose up --build
Open http://localhost:3000. Follow the full installation guide for prerequisites, configuration, data storage, and safe shutdown.

 
Create and list identities
POST /api/agents creates an agent, generates an Ed25519 key pair and DID, and creates initial soul and wallet records.
curl -sS http://localhost:3000/api/agents \
@@ -30,7 +30,7 @@
 
Read and write memory
Memory is scoped to an agent ID. Retrieval supports a tier, kind, query, temporal point, and bounded token estimate.
curl -sS 'http://localhost:3000/api/agents/AGENT_ID/memory?q=authentication&tier=RECALL&maxTokens=1500'
Write a record with POST /api/agents/{id}/memory:
curl -sS -X POST http://localhost:3000/api/agents/AGENT_ID/memory \
   -H 'content-type: application/json' \
   -d '{"content":"Prefer evidence-linked conclusions.","tier":"CORE","kind":"preference","tags":"research","ttl":"permanent"}'
TTL values are permanent, session, 7d, and 30d. Token estimates use a simple character-based heuristic, not a model tokenizer.

-
Discover and call MCP tools
Start the MCP service from source with npm run mcp. GET http://localhost:3030/tools returns its tool registry. The service also exposes JSON-RPC at /mcp.
Call an advertised tool with POST /tools/call:
curl -sS -X POST http://localhost:3030/tools/call \
+
Discover and call MCP tools
The app serves MCP at POST http://localhost:3000/api/hello/mcp; compatibility route GET /api/hello/mcp/tools returns the tool registry. The optional Bun sidecar runs with npm run mcp on port 3030.
Call an advertised tool through JSON-RPC on /api/hello/mcp, or use the optional sidecar compatibility route POST /tools/call:
curl -sS -X POST http://localhost:3000/api/hello/mcp/call \
   -H 'content-type: application/json' \
   -d '{"name":"aml.compile","arguments":{"source":"intent demo { steps { emit: result } }"}}'
Responses include structured output and a receipt hash. Check the running server's handshake and tools list for actual availability; this compatibility interface is not a claim of complete MCP transport conformance.

 
Agent-to-agent task API
POST /api/a2a supports JSON-RPC-style methods including message/send, tasks/get, tasks/list, tasks/update, tasks/cancel, and agent/card. Tasks record sender and receiver identities and a trace identifier. Keep this endpoint on a trusted self-hosted instance.

@@ -38,16 +38,7 @@
 
Validate AML declarations
To use the browser interface, start the app and open http://localhost:3000/aml-studio. See the AML Studio guide for the local workflow, API response fields, and execution boundaries.
POST /api/aml/compile statically parses and validates AML source (up to 64 KB). It returns an AST, intent graph, diagnostics, and hashes. Compilation does not execute the intent.
curl -sS -X POST http://localhost:3000/api/aml/compile \
   -H 'content-type: application/json' \
   -d '{"source":"mission example { steps { verify: proof.check($input) β†’ $result } }"}'
The result has executable: false. AML does not invoke models, route providers, deploy code, call external agents, mutate memory, or spend wallet balances. Read the examples and grammar.

-
Operator controls and runtime features (open PRs)
These features exist as open pull requests and are available once each PR merges. On a build without them, the routes return 404.

-
-
-
-
-
-
-
-
-
FeatureRoutesPR
Private keys never returned by the API/api/agents and others#4
Approval gate, kill switch, audit log/api/approvals, /api/operator, /api/audit#5
Heartbeat scheduler (cron calls the tick) and delegation tree/api/scheduler/tick, /api/delegation#6
Read-only MCP connector tools and webhook bridge/api/integrations/webhook, MCP connector.*#7
Checkpoint/resume and failure library/api/snapshots, /api/failures#11
Semantic cache (measured hit rate) and RBAC knowledge index/api/cache, /api/knowledge#12
Debate/consensus and gated treasury reallocation/api/consensus, /api/treasury#13
QuickJS WebAssembly sandbox/api/sandbox#14
Set HELLO_OPERATOR_TOKEN and send it as x-operator-token for operator actions. Without it the instance runs in dev mode. Amounts are prototype credits. Read the operator guide and merge order.

+
Operator controls
Approvals, kill switch, audit log, scheduler, delegation, role-based knowledge, consensus, treasury, and sandbox APIs are implemented. Set HELLO_OPERATOR_TOKEN and send it as x-operator-token for operator actions. When unset, the instance runs in development mode. Amounts are prototype credits. Read the operator guide.

 
Current limits
CapabilityCurrent state
Model inference and routingNo provider runtime configured by this guide.
WalletsInternal database balances only; no USDC or blockchain settlement.
Compute isolationNo Firecracker or per-mission VM execution.
Cloud snapshotsCheckpoint records use simulated snapshot references.
AMLStatic parser and validator; not an execution engine.
SecurityLocal prototype; no production auth, certification, or tenant-isolation claim.
See HELLO Cloud: Architecture Direction for the proposed architecture and implementation gaps. Use the download guide for available installation options.
diff --git a/docs/configuration.md b/docs/configuration.md index e160801..dbb8d27 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -3,13 +3,13 @@ | Variable | Used by | Default | Notes | | --- | --- | --- | --- | | `DATABASE_URL` | Prisma | `file:./db/custom.db` | SQLite file. Use a disposable file for tests, e.g. `file:/tmp/hello-test.db`. | -| `HELLO_MCP_URL` | dashboard | `http://localhost:3030` | Where the dashboard reaches the MCP service. | +| `HELLO_MCP_URL` | integrations status | unset | Optional external/standalone MCP service override. Without it, status checks use the in-process MCP handler. | | `HELLO_PUBLIC_URL` | app | `http://localhost:3000` | Public base URL for links and the agent card. | | `HELLO_ALLOWED_ORIGINS` | app, MCP | localhost origins | Comma-separated CORS allow-list. | -| `HELLO_OPERATOR_TOKEN` | operator routes | unset | **Available once PR #5 / #6 / #12 / #14 merge.** When set, operator actions need header `x-operator-token: `: approving or rejecting actions, the kill switch, the threshold, scheduler jobs and ticks, knowledge docs and roles, and sandbox runs. When unset, the app runs in **dev mode**: anyone who can reach the server can act as operator, and `/ops/approvals` shows a warning. Always set it before exposing the app beyond localhost. | -| `HELLO_WEBHOOK_SECRET` | `POST /api/integrations/webhook` | unset | **Available once PR #7 merges.** HMAC-SHA256 secret for inbound webhooks. The route returns 503 until it is set. | -| `GITHUB_TOKEN` | MCP `connector.github.read` | unset | **Available once PR #7 merges.** Optional and read-only. It's read from the environment only and never returned in responses. Without it, the unauthenticated GitHub rate limits apply. | -| `HELLO_MCP_PORT` | `mini-services/hello-mcp` | `3030` | **Available once PR #7 merges.** Overrides the MCP service port. | +| `HELLO_OPERATOR_TOKEN` | operator routes | unset | When set, operator actions need header `x-operator-token: `: approving or rejecting actions, the kill switch, the threshold, scheduler jobs and ticks, knowledge docs and roles, and sandbox runs. When unset, the app runs in **dev mode**: anyone who can reach the server can act as operator, and `/ops/approvals` shows a warning. Always set it before exposing the app beyond localhost. | +| `HELLO_WEBHOOK_SECRET` | `POST /api/integrations/webhook` | unset | **Available on `main`.** HMAC-SHA256 secret for inbound webhooks. The route returns 503 until it is set. | +| `GITHUB_TOKEN` | MCP `connector.github.read` | unset | **Available on `main`.** Optional and read-only. It's read from the environment only and never returned in responses. Without it, the unauthenticated GitHub rate limits apply. | +| `HELLO_MCP_PORT` | optional `mini-services/hello-mcp` | `3030` | Port for the optional Bun sidecar. The app's MCP endpoint is served on port 3000 under `/api/hello/mcp`. | Never commit real values. `.env*` files are git-ignored. diff --git a/docs/features/approvals.md b/docs/features/approvals.md index 920f17e..65c0839 100644 --- a/docs/features/approvals.md +++ b/docs/features/approvals.md @@ -1,6 +1,6 @@ # Approval gate, kill switch and audit log -**Status: in PR #5.** Available once PR #5 merges. +**Status:** shipped on `main`. | Route | Method | Purpose | | --- | --- | --- | diff --git a/docs/features/cache-knowledge.md b/docs/features/cache-knowledge.md index 533e978..e9a4c93 100644 --- a/docs/features/cache-knowledge.md +++ b/docs/features/cache-knowledge.md @@ -1,6 +1,6 @@ # Semantic cache and permission-scoped knowledge index -**Status: in PR #12.** Available once PR #12 merges. +**Status:** shipped on `main`. ## Semantic cache | Route | Method | Purpose | diff --git a/docs/features/consensus-treasury.md b/docs/features/consensus-treasury.md index 1ac24ee..29687b7 100644 --- a/docs/features/consensus-treasury.md +++ b/docs/features/consensus-treasury.md @@ -1,6 +1,6 @@ # Consensus/debate protocol and treasury reallocation -**Status: in PR #13**, stacked on PR #5. Available once PRs #5 and #13 merge. +**Status:** shipped on `main`. ## Consensus & debate - `GET /api/consensus` lists debates. `POST /api/consensus {proposerId, topic, quorumWeight}` opens one. diff --git a/docs/features/identity-and-keys.md b/docs/features/identity-and-keys.md index 3e81350..59cc968 100644 --- a/docs/features/identity-and-keys.md +++ b/docs/features/identity-and-keys.md @@ -1,12 +1,12 @@ # Identity and key handling -**Status:** identity is shipped. The leak fix is **in PR #4** (available once PR #4 merges). +**Status:** identity and private-key omission are implemented on `main`. Key material remains stored by the demo server and is not production-grade custody. - `POST /api/agents` creates an agent with a real Ed25519 keypair and `did:key`, a soul v1 and a wallet. `GET /api/agents`, `GET /api/agents/[id]` and `GET /api/did/[did]` read identities. - The demo server stores `privateKeyHex` in SQLite. That is **prototype custody, not production custody**. -## The leak (fixed in PR #4) -On `main`, `GET /api/agents` returned `privateKeyHex` (confirmed with a live request). The `POST` response, `/api/agents/[id]`, export, DID and stats routes return full agent rows too. PR #4 adds a Prisma **global omit** in `src/lib/db.ts`, so no query returns the key by default, including `create()` results and nested includes. Only the three server-side signing routes (`a2a`, `attestations`, `observations`) opt in with `omit: { privateKeyHex: false }`, and none of them return it. `tests/secrets.test.mjs` (`npm run test:secrets`) fails on `main` and passes with the fix. It also fails if a new route opts in without review. +## Key serialization +`src/lib/db.ts` configures a Prisma global omit for `privateKeyHex`, so normal reads and create responses do not include the private key. Signing routes opt in only server-side with `omit: { privateKeyHex: false }`; they must never return the key. `tests/secrets.test.mjs` checks API serialization and server-side signing behavior. Snapshots (#11) select public identity fields explicitly. The SQL connector (#7) rejects and redacts secret-bearing columns. diff --git a/docs/features/integrations-mcp.md b/docs/features/integrations-mcp.md index 49c62d9..7f671d1 100644 --- a/docs/features/integrations-mcp.md +++ b/docs/features/integrations-mcp.md @@ -1,6 +1,6 @@ # Integrations registry, MCP connector tools and bridges -**Status: in PR #7.** Available once PR #7 merges. The static [integration catalog](../integrations/README.md) on Pages is already published as a planning reference. +**Status:** shipped on `main`. The static [integration catalog](../integrations/README.md) on Pages is already published as a planning reference. - **`/integrations`:** a registry of 100 connectors. 3 are working (GitHub read, SQLite, GitHub Actions webhook), 82 planned and 15 vision (payments/crypto, which are disabled by default and would need operator approval). - **`docs/bridges.md`:** 50 bridge techniques, tagged implemented or planned. The merge arbiter requires human approval. diff --git a/docs/features/pages.md b/docs/features/pages.md index 74becad..d635ccf 100644 --- a/docs/features/pages.md +++ b/docs/features/pages.md @@ -2,16 +2,16 @@ | Page | What it is | Status | | --- | --- | --- | -| `/` Mission Control | dashboard; falls back to labelled demo data when the API is unreachable | shipped | -| `/hub` GitAgentHUB | agent profiles, top agents, skill market and tool calls from the DB. Repos, posts and the contribution graph are **demo data**, and likes/follows are browser-only | shipped (#3) | -| `/evolve` Evolve Lab | the repo's `src/lib/evolution.ts` GA under a permanent **SIMULATION** banner, plus saved runs from `/api/evolution/runs` | shipped (#3) | -| `/cloud` HELLO Cloud | vision page; every item tagged prototype or vision; no benchmarks or pricing | shipped (#3) | +| `/` Mission Control | dashboard reads the configured APIs; empty and offline states do not substitute sample records | shipped | +| `/hub` Agent Hub | agent profiles, capability market, field reports and MCP tool calls from this instance's DB. The HELLO OS GitHub repository is linked as a source reference; agent repository hosting, likes, follows, and GitHub synchronization are not implemented | prototype | +| `/evolve` Evolve Lab | deterministic in-browser GA under a permanent **SIMULATION** banner, plus database-backed runs from `/api/evolution/runs` | shipped | +| `/cloud` HELLO Cloud | vision page; every item tagged prototype or vision; no benchmarks or pricing | shipped | | `/aml-studio` | static AML compile/validate UI (never executes AML) | shipped | -| `/frontier` Frontier Lab | 10 ideas tagged **VISION Β· NOT POSSIBLE TODAY** with why-not, plus 3 labelled in-browser simulations (seeded replay/fork, self-fork via evolution.ts, sleep consolidation of a sample log) | in PR #8 | -| Seven-layer card + AML preview on `/` | layers tagged PROTOTYPE or VISION, with live HTTP checks only. The AML preview uses the repo compiler, shows a "simple lexer token count", and signs receipts with an ephemeral in-browser Ed25519 key ("demo key Β· not persisted") with a working Verify. It also removes the hardcoded sidebar statuses and the fake health score | in PR #9 | -| `/runtime` | the 10 runtime pillars. Status comes from live requests: `PROTOTYPE Β· API RESPONDS`, `NOT IN THIS BUILD Β· PR #N` (404), `PARTIAL`, or `NOT BUILT YET` | in PR #10, all pillars wired in PR #16 | -| `/roadmap` | 100-step roadmap; statuses come from evidence (file paths on main, or the PR state from the GitHub API, cached 10 min, with an offline fallback) | in PR #15 | -| `/integrations` | connector registry | in PR #7 | -| `/ops/*` | operator console panels (approvals, scheduler, delegation, snapshots, failures, cache, knowledge, consensus, treasury, sandbox) | in PRs #5, #6, #11–#14 | +| `/frontier` Frontier Lab | vision ideas plus three labelled in-browser simulations | shipped | +| Seven-layer card + AML preview on `/` | prototype/vision labels, live endpoint checks, static compiler preview, and ephemeral demo-key receipts | shipped | +| `/runtime` | runtime pillar status based on live checks and implementation evidence | shipped | +| `/roadmap` | 100-step roadmap; statuses use repository evidence and optional GitHub PR state | shipped | +| `/integrations` | connector registry; unconnected proposals are marked as such | shipped | +| `/ops/*` | operator console panels (approvals, scheduler, delegation, snapshots, failures, cache, knowledge, consensus, treasury, sandbox) | shipped | All pages use the repo's Tailwind build and `lucide-react`. There are no CDNs and no `innerHTML` for user content. diff --git a/docs/features/sandbox.md b/docs/features/sandbox.md index 62fcd85..d3bf1f8 100644 --- a/docs/features/sandbox.md +++ b/docs/features/sandbox.md @@ -1,6 +1,6 @@ # Wasm snippet sandbox -**Status: in PR #14.** Available once PR #14 merges. +**Status:** shipped on `main` as a bounded prototype. | Route | Method | Purpose | | --- | --- | --- | diff --git a/docs/features/scheduler-delegation.md b/docs/features/scheduler-delegation.md index d9bf67d..d3f78b0 100644 --- a/docs/features/scheduler-delegation.md +++ b/docs/features/scheduler-delegation.md @@ -1,6 +1,6 @@ # Heartbeat scheduler and delegation tree -**Status: in PR #6.** Available once PR #6 merges. +**Status:** shipped on `main`. ## Scheduler | Route | Method | Purpose | diff --git a/docs/features/snapshots-failures.md b/docs/features/snapshots-failures.md index 719706e..9004eda 100644 --- a/docs/features/snapshots-failures.md +++ b/docs/features/snapshots-failures.md @@ -1,6 +1,6 @@ # Checkpoint/resume snapshots and failure library -**Status: in PR #11.** Available once PR #11 merges. +**Status:** shipped on `main` as a sealed portable-record prototype; this is not a VM or database snapshot. ## Snapshots | Route | Method | Purpose | diff --git a/docs/getting-started/index.html b/docs/getting-started/index.html index c80b0d4..a60a454 100644 --- a/docs/getting-started/index.html +++ b/docs/getting-started/index.html @@ -1,7 +1,5 @@ -Install HELLO OS β€” Docker and Local Development

← HELLO OS

Get started with HELLO OS

HELLO OS is a local-first agentic OS prototype. The Docker Compose deployment starts the Next.js dashboard and separate MCP service together. GitHub Pages hosts this guide only; it does not host the running app.

Requirements

Install Docker Engine and the Docker Compose plugin on Linux, Docker Desktop on macOS or Windows, then confirm docker compose version works.

Start with Docker Compose

git clone https://github.com/CodesbyFebin/Hello-OS.git
+Install HELLO OS β€” Docker and Local Development
← HELLO OS
Get started with HELLO OS
HELLO OS is a local-first agentic OS prototype. The Docker Compose deployment runs the Next.js app and its in-process MCP handler in one service. GitHub Pages hosts this guide only; it does not host the running app.
Requirements
Install Docker Engine and the Docker Compose plugin on Linux, Docker Desktop on macOS or Windows, then confirm docker compose version works.
Start with Docker Compose
git clone https://github.com/CodesbyFebin/Hello-OS.git
 cd Hello-OS
-docker compose up --build
Open http://localhost:3000 for the dashboard. MCP is at http://localhost:3030/mcp. The SQLite database persists in the named hello-data volume.
Install scripts
Run from source
For development, install Node.js 20 or newer, npm, and Bun for MCP. From the repository root run:
npm install
+docker compose up --build
Open http://localhost:3000 for the dashboard. MCP is at http://localhost:3000/api/hello/mcp. The SQLite database persists in the named hello-data volume.
Install scripts
Run from source
For development, install Node.js 22 or newer and npm. Bun is only needed for the optional MCP sidecar. From the repository root run:
npm ci
 cp .env.example .env
-npx prisma generate
-npx prisma db push
-npm run dev
Run npm run mcp in another terminal to start the MCP service. Use npm run build and npm start for a production build.
Configuration and data
See .env.example for DATABASE_URL, HELLO_MCP_URL, HELLO_PUBLIC_URL, and allowed origins. Docker stores SQLite data in a named volume. Back up this volume and never delete it unless you intend to remove the workspace data.
Security notes
The current demo server stores generated private signing keys and is not a production key-management solution. The prototype is not a hardened public deployment. Before exposing it to the internet, add authentication, TLS, rate limits, secret management, monitoring, backups, and a security review. See prototype boundaries.
Stop the app
Press Ctrl+C or run docker compose down. That preserves data. docker compose down --volumes removes stored data and should be used only when you intentionally want to erase it.
See all platform options β†’

\ No newline at end of file
+npm run dev

The app serves MCP in-process. Optionally run npm run mcp in another terminal to start the Bun sidecar. Use npm run build and npm start for a production build.

Configuration and data

See .env.example for DATABASE_URL and HELLO_PUBLIC_URL, and allowed origins. Docker stores SQLite data in a named volume. Back up this volume and never delete it unless you intend to remove the workspace data.

Security notes

The current demo server stores generated private signing keys and is not a production key-management solution. The prototype is not a hardened public deployment. Before exposing it to the internet, add authentication, TLS, rate limits, secret management, monitoring, backups, and a security review. See prototype boundaries.

Stop the app

Press Ctrl+C or run docker compose down. That preserves data. docker compose down --volumes removes stored data and should be used only when you intentionally want to erase it.

See all platform options β†’

\ No newline at end of file diff --git a/docs/hello-cloud-architecture.md b/docs/hello-cloud-architecture.md index 58f11a1..13b5cb3 100644 --- a/docs/hello-cloud-architecture.md +++ b/docs/hello-cloud-architecture.md @@ -4,7 +4,7 @@ HELLO Cloud is the longer-term direction for HELLO OS: an agent-oriented control ## Current status -The app runs as a Next.js dashboard with a Prisma-backed SQLite store and a separate Bun MCP service. Agents have Ed25519-backed `did:key` identities, a starting soul record, and a local wallet record. The application includes mission and task APIs, tiered memory, guilds, code-symbol tools, MCP call receipts, and basic skill/economy workflows. +The app runs as a Next.js dashboard with a Prisma-backed SQLite store with an in-process MCP handler; a Bun sidecar is optional. Agents have Ed25519-backed `did:key` identities, a starting soul record, and a local wallet record. The application includes mission and task APIs, tiered memory, guilds, code-symbol tools, MCP call receipts, and basic skill/economy workflows. These are useful building blocks, but they are not a hosted multi-tenant cloud. Wallet amounts are internal prototype credits, not USDC or on-chain assets. `hello.cloud` checkpoints store database records and simulated snapshot references; they do not create VM or filesystem snapshots. AML compilation is static validation only. It does not execute missions, deploy applications, call model providers, spend funds, or launch isolated compute. @@ -37,6 +37,6 @@ Performance comparisons, per-operation prices, transaction volumes, model counts - [Main README](../README.md) β€” setup, supported deployment, and verified implementation boundaries. - [AML examples](aml-examples.md) and [grammar](aml-spec.ebnf) β€” static syntax and validation behavior. -- [MCP service](../mini-services/hello-mcp/index.ts) β€” tool registry and HTTP transport. +- [MCP handler](../src/lib/mcp/server.ts) β€” in-process tool registry and HTTP transport; the optional sidecar is in `mini-services/hello-mcp/`. - [Agent API](../src/app/api/agents/route.ts), [mission API](../src/app/api/missions/route.ts), and [stats API](../src/app/api/stats/route.ts) β€” current data-backed surfaces. diff --git a/docs/index.html b/docs/index.html index d047afd..9dacea2 100644 --- a/docs/index.html +++ b/docs/index.html @@ -151,7 +151,7 @@

Tasks, missions, and agent-to-agent workflows

How to run HELLO OS locally

-

The fastest documented start is Docker Compose. Install Docker Engine and Docker Compose (or Docker Desktop where appropriate), then clone the public repository and start the services. The browser dashboard is exposed locally on port 3000, while the MCP service is available on port 3030 according to the project setup guidance. Review the compose file and environment configuration before exposing any service beyond your machine.

+

The fastest documented start is Docker Compose. Install Docker Engine and Docker Compose (or Docker Desktop where appropriate), then clone the public repository and start the services. The browser dashboard and in-process MCP handler are served by the app on port 3000. An optional standalone MCP sidecar can run on port 3030. Review the compose file and environment configuration before exposing any service beyond your machine.

git clone https://github.com/CodesbyFebin/Hello-OS.git
 cd Hello-OS
 docker compose up --build
diff --git a/docs/llms.txt b/docs/llms.txt index f935861..78719d0 100644 --- a/docs/llms.txt +++ b/docs/llms.txt @@ -23,13 +23,13 @@ - Contributor instructions: https://github.com/CodesbyFebin/Hello-OS/blob/main/AGENTS.md ## Verified implementation facts -- The application uses Next.js, React, TypeScript, Prisma, and SQLite; Docker Compose runs the dashboard and a separate MCP service. -- The MCP endpoint is /mcp. Selected tools include forge, cortex, tiered memory, and checkpoint. +- The application uses Next.js, React, TypeScript, Prisma, and SQLite; Docker Compose runs one app with an in-process MCP handler. +- The in-process MCP endpoint is /api/hello/mcp. Selected tools include forge, cortex, tiered memory, checkpoint, and read-only connectors. An optional Bun sidecar exposes the same handler on port 3030. - Agent discovery is available at /.well-known/agent-card.json. - A2A-style JSON-RPC supports message/send and task lifecycle methods. - AML v1 statically parses and validates declarations at POST /api/aml/compile and POST /api/aml/validate. It builds a deterministic intent graph and hashes source; it never executes AML or invokes tools. - Evolution Lab stores seeded optimization runs over synthetic vectors. Its proxy scores are not model training or agent benchmarks. -- HELLO EVOLVE is a browser simulation using synthetic demo data. +- HELLO EVOLVE is a browser simulation using synthetic demo data. The Agent Hub reads agent profiles, capabilities, field reports, and MCP calls from the configured database; it does not provide agent repository hosting or social interactions. - The repository is licensed under MIT; see LICENSE. - GitHub Pages hosts static documentation only; it does not run the Next.js APIs, SQLite database, or MCP service. - APK, Windows EXE/PEXE, and DEB installers are not currently published. @@ -37,14 +37,8 @@ ## Integration catalog status The catalog contains 100 proposed connector targets and 50 design patterns for legacy bridges. Every connector is marked unconnected and every pattern unshipped. These records are roadmap references, not integrations or vendor endorsements. The running prototype exposes only the capabilities documented in the repository. -## Runtime features in open pull requests (not on main yet) -Each becomes available only once its PR merges. See docs/README.md and docs/merge-order.md in the repository. -- #4 API routes no longer return agent private keys. -- #5 Approval gate with risk tiers, operator kill switch, audit log (/api/approvals, /api/operator, /api/audit). -- #6 Cron-driven heartbeat scheduler (POST /api/scheduler/tick) and a delegation tree with credit caps. -- #7 Integrations registry, 6 read-only MCP connector tools, HMAC webhook bridge (HELLO_WEBHOOK_SECRET, GITHUB_TOKEN, HELLO_MCP_PORT). -- #8 /frontier vision ideas with labelled simulations. #9 Seven-layer card and AML preview with ephemeral demo-key receipts. #10/#16 /runtime live pillar status. #15 /roadmap. -- #11 Sealed checkpoint/resume snapshots and a failure library. #12 Semantic cache with measured hit rate and an RBAC knowledge index. #13 Reputation-weighted debate and gated treasury reallocation. #14 QuickJS WebAssembly sandbox with time and memory limits. +## Runtime status +The listed APIs and operator features are present on the default branch. See docs/features/ and AGENTS.md for behavior and limitations. Operator actions require HELLO_OPERATOR_TOKEN when it is set. ## Security and capability limits diff --git a/docs/merge-order.md b/docs/merge-order.md index 7f1af5a..ecadf6d 100644 --- a/docs/merge-order.md +++ b/docs/merge-order.md @@ -1,32 +1,13 @@ -# Merge order for the open PRs +# Database and schema update notes -Nothing below is merged yet unless GitHub shows it as merged. Suggested order: +The repository uses Prisma with SQLite and does not currently ship a versioned migration history. Fresh local SQLite files are initialized from `prisma/turso/init.sql` by the app startup script. Existing databases are deliberately left unchanged during app startup. -1. **#4**: stop API routes returning `privateKeyHex`. Merge first. -2. **#5**: approval gate, kill switch, audit log. Then **#13** (consensus + treasury). It is stacked on #5 and GitHub retargets it to `main` after #5 merges. -3. **#6** (scheduler + delegation), **#11** (snapshots + failures), **#12** (cache + knowledge), **#14** (Wasm sandbox), in any order. -4. **#10** (`/runtime`), then **#16** (wires pillars 3 and 5–10). #16 is stacked on #10. -5. **#7** (integrations), **#8** (`/frontier`), **#9** (layers + AML preview), **#15** (`/roadmap`) are independent. +After pulling a schema change, back up the database and review the Prisma schema diff. For a disposable local database, apply the current schema with: -## Expected conflicts (trivial) -- `package.json` scripts: each PR adds one `test:*` line. Keep them all. -- `prisma/schema.prisma`: PRs add model blocks in different places. Keep both blocks if Git flags them. -- `src/components/hub/hub-shell.tsx` nav: #7 and #15 each add a tab. Keep both. -- The `/ops` shell (`src/app/ops/page.tsx`, `src/components/ops/*`, `tests/register.mjs`, `tests/alias-hooks.mjs`, `src/lib/similarity.ts`, `src/lib/operator-auth.ts`) is byte-identical across PRs and merges cleanly. - -## After merging -```bash -npx prisma db push -npm run build -npm run test:aml && npm run test:evolution # Node 22 (`npx node@22`) for the node:test suites -npm run test:secrets # #4 (needs DATABASE_URL pointing at a scratch DB) -npm run test:gate # #5 -npm run test:scheduler # #6 -npm run test:snapshots # #11 -npm run test:cache # #12 -npm run test:consensus # #13 -npm run test:sandbox # #14 +```sh +DATABASE_URL=file:/tmp/hello-schema-check.db npx prisma db push ``` -The `test:*` scripts that touch the database run `prisma db push` against `DATABASE_URL` first. Point it at a disposable file, e.g. `DATABASE_URL=file:/tmp/hello-test.db npm run test:gate`. -A local, unpushed merge of #5, #6 and #11–#14 with #16 validated the schema, built, and passed all 15 new and 12 existing node tests. +For Turso/libSQL, use the documented SQL apply procedure for an empty database or prepare an explicit migration for an existing database. Do not run destructive schema changes against a database with data you need to preserve. + +The optional Bun MCP sidecar and the in-process Next.js MCP handler share the same implementation. The default Compose deployment runs only the app service. diff --git a/docs/operator-guide.md b/docs/operator-guide.md index d552c2f..433e136 100644 --- a/docs/operator-guide.md +++ b/docs/operator-guide.md @@ -2,7 +2,7 @@ The operator is the human who runs a HELLO OS instance. Operators hold the keys: they cap spending, approve risky actions, can halt everything, and grant or revoke roles. Agents never get to override that. -> Most of this guide is **available once PRs #5, #6, #12, #13 and #14 merge** (see [merge-order.md](merge-order.md)). The Ops console is at `/ops` and is linked from the Mission Control sidebar. +> The approval, scheduler, knowledge, consensus, and sandbox APIs described here are implemented on `main`. The Ops console is at `/ops` and is linked from the Mission Control sidebar. ## 1. Set an operator token ```bash @@ -10,7 +10,7 @@ export HELLO_OPERATOR_TOKEN="$(openssl rand -hex 32)" ``` With it set, operator routes need `-H "x-operator-token: $HELLO_OPERATOR_TOKEN"`. Without it the instance runs in **dev mode** and anyone who can reach it can act as operator. This is a shared secret, not a cryptographic sign-off or a multi-user auth system. -## 2. Approvals and risk tiers (PR #5) +## 2. Approvals and risk tiers | Tier | Actions | What happens | | --- | --- | --- | | low | `data.read` | runs | @@ -32,24 +32,24 @@ curl -s 'localhost:3000/api/gate?action=wallet.spend&amount=40' ``` An approved action runs through the same wallet code path and can only run once. UI: `/ops/approvals`. -## 3. Kill switch (PR #5) +## 3. Kill switch ```bash curl -s -XPOST localhost:3000/api/operator -H "x-operator-token: $HELLO_OPERATOR_TOKEN" \ -H 'content-type: application/json' -d '{"killSwitch":true}' ``` While it is on, every gated action returns HTTP 423. It is checked again when a previously approved action executes. Release it with `{"killSwitch":false}`. -## 4. Audit log (PR #5) +## 4. Audit log `GET /api/audit` returns the latest 100 entries: every allow, queue, block, decision and operator change. It is an append-only table in SQLite, **not** a tamper-proof log. -## 5. Scheduler ticks via cron (PR #6) +## 5. Scheduler ticks via cron There is no hidden background daemon. Jobs only run when something calls the tick endpoint: ```cron * * * * * curl -s -X POST -H "x-operator-token: $HELLO_OPERATOR_TOKEN" http://localhost:3000/api/scheduler/tick >/dev/null ``` Add jobs at `/ops/scheduler` or with `POST /api/scheduler/jobs {"kind":"wallet.audit","intervalSec":3600}`. The kinds are `heartbeat`, `wallet.audit` and `missions.stale`. A GitHub Actions `schedule:` workflow can call the same endpoint if the instance is reachable. -## 6. Roles for the knowledge index (PR #12) +## 6. Roles for the knowledge index ```bash curl -s -XPOST localhost:3000/api/knowledge/roles -H "x-operator-token: $HELLO_OPERATOR_TOKEN" \ -H 'content-type: application/json' -d '{"agentId":"AGENT_ID","role":"engineer"}' # add "revoke":true to remove @@ -57,7 +57,7 @@ curl -s -XPOST localhost:3000/api/knowledge/roles -H "x-operator-token: $HELLO_O The roles are `viewer`, `engineer`, `dataops`, `security` and `admin`. ## 7. Identity revocation -Agent identities are `did:key` Ed25519 keys stored by the demo server. The operator can retire an agent and rotate keys by creating a new identity. KMS/HSM custody and formal revocation lists are **planned**. After PR #4 merges, the API never returns private keys. +Agent identities are `did:key` Ed25519 keys stored by the demo server. The operator can retire an agent and rotate keys by creating a new identity. KMS/HSM custody and formal revocation lists are **planned**. Private-key omission is implemented on `main`;, the API never returns private keys. ## 8. Before exposing an instance Set `HELLO_OPERATOR_TOKEN`, keep Compose ports on loopback or put the app behind an authenticating proxy, back up the SQLite volume, and remember that this is a prototype without multi-tenant isolation. diff --git a/docs/wiki/Architecture.md b/docs/wiki/Architecture.md index ddcc3a1..f73e3c1 100644 --- a/docs/wiki/Architecture.md +++ b/docs/wiki/Architecture.md @@ -1,6 +1,6 @@ # HELLO OS architecture: local-first agent control prototype -HELLO OS is composed of a Next.js application, a Prisma persistence layer, and a separate Bun-based MCP service. The current application stores agent and workflow records locally and exposes selected APIs for inspection and interaction. The named HELLO domains describe product areas; they are not independently deployed cloud services. +HELLO OS is composed of a Next.js application, a Prisma persistence layer, and an in-process MCP handler (with an optional Bun sidecar). The current application stores agent and workflow records locally and exposes selected APIs for inspection and interaction. The named HELLO domains describe product areas; they are not independently deployed cloud services. ## Components @@ -8,13 +8,13 @@ HELLO OS is composed of a Next.js application, a Prisma persistence layer, and a | --- | --- | --- | | Next.js App Router | Pages, dashboard, API routes, discovery metadata | `src/app/` | | Prisma + SQLite | Local persistence for supported records | `prisma/schema.prisma` | -| MCP service | Exposes selected tools and records call results | `mini-services/hello-mcp/index.ts` | +| MCP handler | Exposes selected tools and records call results in the Next.js app | `src/lib/mcp/server.ts` | | AML engine | Static parse, validation, graph, metrics, and hashes | `src/lib/aml.ts` | | Dashboard | Operator observation and review UI | `src/components/hello/dashboard.tsx` | ## Data and workflow path -The UI and API routes read and mutate application state through the server-side data layer. The separate MCP service exposes its own tool surface. Agent cards and APIs describe capabilities; a descriptor does not imply that the application is autonomously executing work. Inspect the route handlers and tool registry before relying on a behavior. +The UI and API routes read and mutate application state through the server-side data layer. The optional Bun sidecar wraps the same in-process handler for standalone clients. Agent cards and APIs describe capabilities; a descriptor does not imply that the application is autonomously executing work. Inspect the route handlers and tool registry before relying on a behavior. ## Current module mapping diff --git a/docs/wiki/Home.md b/docs/wiki/Home.md index d4ddfa3..5dfad6a 100644 --- a/docs/wiki/Home.md +++ b/docs/wiki/Home.md @@ -1,6 +1,6 @@ # HELLO OS: agent operating system prototype -HELLO OS is an open-source, local-first prototype for exploring agent identity, persistent records, bounded mission workflows, tool integration, and inspectable work. It combines a Next.js application, Prisma with SQLite, and a separate MCP service. It is not a hosted cloud platform or a general-purpose autonomous execution runtime. +HELLO OS is an open-source, local-first prototype for exploring agent identity, persistent records, bounded mission workflows, tool integration, and inspectable work. It combines a Next.js application, Prisma with SQLite, and an in-process MCP handler. It is not a hosted cloud platform or a general-purpose autonomous execution runtime. > **Status: experimental prototype.** This wiki describes the code that exists in the repository. It marks proposed capabilities as vision and does not present synthetic illustrations, example syntax, or unverified targets as operational facts. diff --git a/docs/wiki/Protocols-and-API.md b/docs/wiki/Protocols-and-API.md index 3b75bfc..e05eab9 100644 --- a/docs/wiki/Protocols-and-API.md +++ b/docs/wiki/Protocols-and-API.md @@ -17,7 +17,7 @@ The repository contains routes for agent, mission, memory, Forge, MCP, economy, ## MCP service -The standalone local MCP service runs with `npm run mcp` and Bun, listening on port `3030` by default. The MCP tool registry is in [`mini-services/hello-mcp/index.ts`](https://github.com/CodesbyFebin/Hello-OS/blob/main/mini-services/hello-mcp/index.ts). The dashboard also exposes application API routes under `/api/hello/mcp/` for selected tool calls and receipt feeds. +The primary MCP endpoint runs in the Next.js app at `/api/hello/mcp` without a sidecar. The optional standalone MCP service runs with `npm run mcp` and Bun, listening on port `3030` by default. The MCP tool registry is in [`mini-services/hello-mcp/index.ts`](https://github.com/CodesbyFebin/Hello-OS/blob/main/mini-services/hello-mcp/index.ts). The app also exposes compatibility API routes under `/api/hello/mcp/` for tool listing, calls, and receipt feeds. Check the tool registry and configuration before connecting clients. A compatible transport is not a guarantee of authentication, user isolation, broad MCP conformance, or safe access from the public internet. diff --git a/docs/wiki/Quickstart.md b/docs/wiki/Quickstart.md index b076c91..78bddc4 100644 --- a/docs/wiki/Quickstart.md +++ b/docs/wiki/Quickstart.md @@ -1,12 +1,12 @@ # Run HELLO OS locally: quickstart -HELLO OS can be run locally with Node.js, npm, and SQLite. The optional MCP service also requires Bun. A local instance is intended for development and evaluation; it is not hardened for public or multi-tenant use. +HELLO OS can be run locally with Node.js 22+, npm, and SQLite. Bun is only needed for the optional standalone MCP sidecar. A local instance is intended for development and evaluation; it is not hardened for public or multi-tenant use. ## Requirements -- Node.js 20 or newer. +- Node.js 22 or newer. - npm. -- Bun for the separate MCP service. +- Bun for the optional MCP sidecar only. - Docker Engine and the Compose plugin only if using Docker Compose. ## Install from source @@ -14,16 +14,14 @@ HELLO OS can be run locally with Node.js, npm, and SQLite. The optional MCP serv ```sh git clone https://github.com/CodesbyFebin/Hello-OS.git cd Hello-OS -npm install +npm ci cp .env.example .env -npx prisma generate -npx prisma db push npm run dev ``` -Open `http://localhost:3000`. The dashboard is at `/dashboard`. The app uses the configured Prisma `DATABASE_URL`; inspect `.env.example` before changing it. `db:push` updates the local schema and is not a substitute for a production migration and backup strategy. +Open `http://localhost:3000`. The dashboard is at `/`. A fresh local SQLite database is initialized at startup; existing databases are left unchanged. The app uses the configured Prisma `DATABASE_URL`; inspect `.env.example` before changing it. `db:push` updates the local schema and is not a substitute for a production migration and backup strategy. -## Start the MCP service +## Optional standalone MCP sidecar In a second terminal, with Bun installed: @@ -31,7 +29,7 @@ In a second terminal, with Bun installed: npm run mcp ``` -The local MCP service listens on port `3030` by default. The exact tool list and request behavior are defined in [`mini-services/hello-mcp/index.ts`](https://github.com/CodesbyFebin/Hello-OS/blob/main/mini-services/hello-mcp/index.ts). +The in-process MCP endpoint is served under `/api/hello/mcp`. The optional sidecar listens on port `3030` by default. The exact tool list and request behavior are defined in [`mini-services/hello-mcp/index.ts`](https://github.com/CodesbyFebin/Hello-OS/blob/main/mini-services/hello-mcp/index.ts). ## Docker Compose @@ -39,7 +37,7 @@ The local MCP service listens on port `3030` by default. The exact tool list and docker compose up --build ``` -Compose starts the web app and MCP service with a persistent named volume for SQLite data. The configured ports bind to localhost in the supplied Compose file. Review `compose.yaml` and your environment before changing exposure. Avoid exposing a development instance directly to the internet. +Compose starts one web app with an in-process MCP handler and a persistent named volume for SQLite data. The configured ports bind to localhost in the supplied Compose file. Review `compose.yaml` and your environment before changing exposure. Avoid exposing a development instance directly to the internet. To stop the services, run `docker compose down`. Removing the volume deletes its persisted data; check the Compose file and back up any state before doing so. @@ -56,7 +54,7 @@ To stop the services, run `docker compose down`. Removing the volume deletes its | --- | --- | | Prisma client missing | Run `npx prisma generate` after dependency installation. | | Database unavailable | Check `DATABASE_URL`, the database path, and filesystem permissions. | -| MCP tools unavailable | Confirm Bun is installed and the service on port 3030 is running. | +| MCP tools unavailable | Use `/api/hello/mcp` on the app, or confirm Bun is installed and the optional sidecar on port 3030 is running. | | Dashboard shows empty states | Add records or inspect API connectivity; empty state is not a simulated live feed. | See the root [README](https://github.com/CodesbyFebin/Hello-OS#readme) for environment variables, tests, deployment boundaries, and security guidance. diff --git a/package.json b/package.json index b461de0..23a4638 100644 --- a/package.json +++ b/package.json @@ -3,9 +3,9 @@ "version": "0.2.1", "private": true, "scripts": { - "dev": "next dev -p 3000 2>&1 | tee dev.log", + "dev": "node scripts/runtime-db-init.mjs && next dev -p 3000 2>&1 | tee dev.log", "build": "prisma generate && next build && cp -r .next/static .next/standalone/.next/ && cp -r public .next/standalone/ && cp -r sample-repo .next/standalone/", - "start": "NODE_ENV=production node .next/standalone/server.js", + "start": "node scripts/runtime-db-init.mjs && NODE_ENV=production node .next/standalone/server.js", "mcp": "bun --hot mini-services/hello-mcp/index.ts", "lint": "eslint .", "db:push": "prisma db push", diff --git a/scripts/runtime-db-init.mjs b/scripts/runtime-db-init.mjs new file mode 100644 index 0000000..e674086 --- /dev/null +++ b/scripts/runtime-db-init.mjs @@ -0,0 +1,35 @@ +// Initialize a fresh local SQLite file from the checked-in Prisma schema SQL. +// Existing databases are never rewritten at startup; schema changes remain an +// explicit operator action (`npx prisma db push` or the documented Turso flow). +import { createClient } from "@libsql/client"; +import { mkdir, readFile } from "node:fs/promises"; +import { fileURLToPath } from "node:url"; +import { dirname } from "node:path"; + +const url = process.env.DATABASE_URL?.trim(); +if (!url) { + console.error("DATABASE_URL is required. Set it before starting HELLO OS."); + process.exit(1); +} + +if (!/^file:/i.test(url)) { + console.log("Skipping automatic schema initialization for remote database; apply prisma/turso/init.sql before first start."); + process.exit(0); +} + +const client = createClient({ url }); +try { + const databasePath = fileURLToPath(new URL(url)); + await mkdir(dirname(databasePath), { recursive: true }); + const existing = await client.execute("SELECT name FROM sqlite_master WHERE type='table' AND name NOT LIKE 'sqlite_%'"); + if (existing.rows.length > 0) { + console.log(`Database already has ${existing.rows.length} table(s); leaving it unchanged.`); + } else { + const sqlPath = fileURLToPath(new URL("../prisma/turso/init.sql", import.meta.url)); + const sql = await readFile(sqlPath, "utf8"); + await client.executeMultiple(sql); + console.log("Initialized empty SQLite database from prisma/turso/init.sql."); + } +} finally { + client.close(); +} diff --git a/src/app/aml-studio/aml-studio-client.tsx b/src/app/aml-studio/aml-studio-client.tsx index 4737d94..425f36a 100644 --- a/src/app/aml-studio/aml-studio-client.tsx +++ b/src/app/aml-studio/aml-studio-client.tsx @@ -15,11 +15,11 @@ const example = `mission optimize_query { analyze: query.performance($query) β†’ $metrics optimize: $metrics β†’ $new_query - if $new_query.latency < 50ms { + if $new_query.latency < $target_latency { persist: $new_query β†’ db emit: verification_receipt } else { - rollback: checkpoint("pre_optimize") + emit: review_required("candidate_ready") emit: review_required } } diff --git a/src/app/api/hello/cloud/checkpoints/route.ts b/src/app/api/hello/cloud/checkpoints/route.ts index b352e28..46da6e0 100644 --- a/src/app/api/hello/cloud/checkpoints/route.ts +++ b/src/app/api/hello/cloud/checkpoints/route.ts @@ -2,8 +2,10 @@ import { NextResponse } from "next/server"; import { db } from "@/lib/db"; export async function GET() { - const checkpoints = await db.checkpoint.findMany({ + const records = await db.checkpoint.findMany({ orderBy: { createdAt: "desc" }, + select: { id: true, repoId: true, name: true, agentDid: true, receiptHash: true, createdAt: true }, }); + const checkpoints = records.map((record) => ({ ...record, status: "recorded" })); return NextResponse.json({ checkpoints }); } diff --git a/src/app/evolve/evolve-client.tsx b/src/app/evolve/evolve-client.tsx index b6f6746..bbb4858 100644 --- a/src/app/evolve/evolve-client.tsx +++ b/src/app/evolve/evolve-client.tsx @@ -29,8 +29,7 @@ export function EvolveClient() { const [mode, setMode] = React.useState<"sim" | "runs">("sim"); const [runs, setRuns] = React.useState(null); const [runsError, setRunsError] = React.useState(""); - const [query, setQuery] = React.useState(""); - const [output, setOutput] = React.useState(["-- mock query console: reads this page's in-memory simulation, not a database --"]); + const [output, setOutput] = React.useState(["Simulation state is in this browser tab; no database is queried."]); const facts = React.useMemo(() => { const out: Fact[] = []; @@ -91,7 +90,7 @@ export function EvolveClient() { champions: () => rankPopulation(latest.population).slice(0, 5).map((c, i) => ` ${i + 1}. ${c.id} Β· fitness ${c.fitness.toFixed(2)}`), }; const result = lines[key] ? lines[key]() : [`unknown query: ${q.slice(0, 60)}`, "try: recent, mutations, dead_ends, champions"]; - setOutput((o) => [...o, `mock> ${q.slice(0, 60)}`, ...(result.length ? result : ["(no rows yet: run a few generations)"])].slice(-60)); + setOutput((o) => [...o, `simulation query: ${q}`, ...(result.length ? result : ["(no rows yet: run a few generations)"])].slice(-60)); } const chart = snaps.slice(-60); @@ -186,10 +185,10 @@ export function EvolveClient() {
-
QUERY CONSOLE
+
SIMULATION INSPECTOR
{["recent", "mutations", "dead_ends", "champions"].map((k) => )}
{output.map((l, i) =>
{l}
)}
-
{ e.preventDefault(); if (query.trim()) { runQuery(query); setQuery(""); } }}> setQuery(e.target.value)} maxLength={60} placeholder="type a query and press Enter" className="mt-2 w-full rounded border border-white/10 bg-transparent px-2 py-1 font-mono text-[11px] outline-none" />
+

Choose a fixed inspection above. Free-form input and code execution are not supported.

diff --git a/src/app/hub/hub-client.tsx b/src/app/hub/hub-client.tsx index ed09b9f..f5ed070 100644 --- a/src/app/hub/hub-client.tsx +++ b/src/app/hub/hub-client.tsx @@ -1,231 +1,113 @@ "use client"; import * as React from "react"; -import { BookMarked, GitCommit, GitFork, GitPullRequest, Heart, MessageCircle, Package, Repeat2, Star, Tag, Wallet, X, CircleDot } from "lucide-react"; -import { HubShell, DemoBadge, RealBadge, SoonButton, card, kicker } from "@/components/hub/hub-shell"; -import { contributionGrid, demoActivity, demoPosts, demoRepos, type DemoPost, type DemoRepo } from "@/lib/hub-demo"; +import { BookMarked, Heart, Package, Wallet } from "lucide-react"; +import { HubShell, RealBadge, card, kicker } from "@/components/hub/hub-shell"; -type Agent = { id: string; name: string; did: string; tagline: string; status: string; guardianTier: string; reputation: number; guild?: { name: string } | null; wallet?: { balance: number; spentToday: number; circuitOpen: boolean } | null }; +type Agent = { id: string; name: string; did: string; tagline: string; status: string; guardianTier: string; reputation: number; guild?: { name: string } | null; wallet?: { balance: number } | null }; type Skill = { id: string; name: string; description: string; category: string; price: number; rating: number; installs: number; author?: { name: string; guardianTier: string } | null }; type Call = { id: string; toolName: string; createdAt: string; latencyMs: number; isError: boolean }; +type Post = { id: string; author: string; title: string; body: string; repo: string; receipt: string; createdAt: string }; type TabName = "feed" | "repositories" | "skills" | "activity"; - const fmtCredits = (n: number) => `${new Intl.NumberFormat("en-US", { maximumFractionDigits: 1 }).format(n)} credits`; -const shortDid = (did: string) => (did.length > 22 ? `${did.slice(0, 14)}…${did.slice(-5)}` : did); -const level = ["bg-white/[.04]", "bg-[#43e6a5]/25", "bg-[#43e6a5]/45", "bg-[#43e6a5]/70", "bg-[#43e6a5]"]; -const verb = { commit: "committed to", star: "starred", fork: "forked", issue: "opened an issue on", pr: "opened a pull request on", release: "published" }; -const actIcon = { commit: GitCommit, star: Star, fork: GitFork, issue: CircleDot, pr: GitPullRequest, release: Tag }; export function HubClient() { const [agents, setAgents] = React.useState([]); const [skills, setSkills] = React.useState([]); const [calls, setCalls] = React.useState([]); + const [posts, setPosts] = React.useState([]); const [connected, setConnected] = React.useState(null); const [tab, setTab] = React.useState("feed"); const [search, setSearch] = React.useState(""); - const [posts, setPosts] = React.useState(demoPosts); const [draft, setDraft] = React.useState(""); - const [liked, setLiked] = React.useState>(new Set()); - const [starred, setStarred] = React.useState>(new Set()); - const [following, setFollowing] = React.useState>(new Set()); - const [openRepo, setOpenRepo] = React.useState(null); const [notice, setNotice] = React.useState(""); + const [busy, setBusy] = React.useState(false); const load = React.useCallback(async () => { try { - const [a, s, c] = await Promise.all([fetch("/api/agents?limit=20", { cache: "no-store" }), fetch("/api/marketplace", { cache: "no-store" }), fetch("/api/hello/mcp/feed", { cache: "no-store" })]); - if (!a.ok || !s.ok) throw new Error("HELLO API unavailable"); - const [aj, sj, cj] = await Promise.all([a.json(), s.json(), c.ok ? c.json() : Promise.resolve({ calls: [] })]); - setAgents(aj.agents ?? []); setSkills(sj.skills ?? []); setCalls((cj.calls ?? []).slice(0, 8)); setConnected(true); - } catch { setConnected(false); } + const responses = await Promise.all([ + fetch("/api/agents?limit=50", { cache: "no-store" }), + fetch("/api/marketplace", { cache: "no-store" }), + fetch("/api/hello/mcp/feed", { cache: "no-store" }), + fetch("/api/docs/posts", { cache: "no-store" }), + ]); + if (responses.some((r) => !r.ok)) throw new Error("One or more HELLO APIs are unavailable"); + const [a, s, c, p] = await Promise.all(responses.map((r) => r.json())); + setAgents(a.agents ?? []); setSkills(s.skills ?? []); setCalls(c.calls ?? []); setPosts(p.posts ?? []); setConnected(true); + } catch (e) { + setConnected(false); setNotice(e instanceof Error ? e.message : "HELLO API unavailable"); + } }, []); React.useEffect(() => { const t = window.setTimeout(() => void load(), 0); return () => window.clearTimeout(t); }, [load]); const me = agents[0] ?? null; - const grid = React.useMemo(() => contributionGrid(me?.did ?? "demo"), [me?.did]); - const q = search.trim().toLowerCase(); - const match = (...fields: string[]) => !q || fields.some((f) => f.toLowerCase().includes(q)); - const toggle = (set: Set, id: string, update: (s: Set) => void) => { const n = new Set(set); if (n.has(id)) n.delete(id); else n.add(id); update(n); }; + const query = search.trim().toLowerCase(); + const matches = (...values: string[]) => !query || values.some((v) => v.toLowerCase().includes(query)); + const tabs: TabName[] = ["feed", "repositories", "skills", "activity"]; - async function purchase(skill: Skill) { - if (!me) { setNotice("Summon an agent first. Purchases are paid from an agent's prototype credits."); return; } - const res = await fetch(`/api/marketplace/${skill.id}/install`, { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify({ agentId: me.id }) }); - const body = await res.json().catch(() => ({})); - setNotice(res.ok ? `${me.name} installed ${skill.name} for ${fmtCredits(skill.price)} (prototype credits, not money).` : `Could not install: ${body.error ?? res.status}`); - if (res.ok) void load(); + async function publish(e: React.FormEvent) { + e.preventDefault(); + const body = draft.trim(); + if (!me) { setNotice("Create an agent before publishing an update."); return; } + if (body.length < 20) { setNotice("Write at least 20 characters so the report is useful."); return; } + setBusy(true); + try { + const r = await fetch("/api/docs/posts", { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify({ author: me.did, title: "Agent field report", body, repo: "CodesbyFebin/Hello-OS" }) }); + const data = await r.json(); + if (!r.ok) throw new Error(data.error || `HTTP ${r.status}`); + setDraft(""); setNotice(`Saved to this instance with receipt ${data.post.receipt.slice(0, 16)}…`); await load(); + } catch (e) { setNotice(e instanceof Error ? e.message : "Could not publish report"); } + finally { setBusy(false); } } - function publish() { - const text = draft.trim().slice(0, 500); - if (!text) return; - setPosts([{ id: `local-${posts.length}`, author: me?.name ?? "You", text, likes: 0, reposts: 0, comments: 0, when: "now" }, ...posts]); - setDraft(""); + async function purchase(skill: Skill) { + if (!me) { setNotice("Create an agent before installing a capability."); return; } + try { + const r = await fetch(`/api/marketplace/${skill.id}/install`, { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify({ agentId: me.id }) }); + const data = await r.json(); + if (!r.ok) throw new Error(data.error || `HTTP ${r.status}`); + setNotice(`${me.name} installed ${skill.name} for ${fmtCredits(skill.price)} (prototype credits).`); await load(); + } catch (e) { setNotice(e instanceof Error ? e.message : "Could not install capability"); } } - const tabs: TabName[] = ["feed", "repositories", "skills", "activity"]; - return (
- Prototype hub. Agent profiles, skills and tool calls marked Local DB come from this HELLO OS instance. Repositories, posts, activity and the contribution graph are demo data. Wallet amounts are prototype credits, not money. - {connected === false && HELLO API not reachable, so only demo content is shown.} + HELLO Agent Hub prototype. Profiles, capabilities, reports, and MCP calls are read from this instance's database. Reports are plain text with server receipts. Repository hosting, stars, follows, and social interactions are not implemented. Wallet balances are prototype credits, not money. + {connected === false && Some API data could not be loaded; see the message below.}
- {notice &&
{notice}
} + {notice &&

{notice}

}
-
- {/* Left: profile */} - {/* Center */}
-
- {tabs.map((t) => )} -
- - {tab === "feed" && ( -
-
- -