diff --git a/.env.example b/.env.example index 86675b9..c8d413e 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" @@ -12,7 +11,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 d246ffc..0d01043 100644 --- a/README.md +++ b/README.md @@ -27,7 +27,7 @@ ## What is HELLO OS? -**HELLO OS is an experimental, MIT-licensed operating layer for AI agents. It gives each agent an Ed25519 identity, tiered memory, a dead-end registry, credit-budgeted wallets with operator approval gates, a non-executable AML compiler, and a 20-tool MCP server served inside the Next.js app. It is a prototype, not a production service.** +**HELLO OS is an experimental, MIT-licensed operating layer for AI agents. It gives each agent an Ed25519 identity, tiered memory, a dead-end registry, credit-budgeted wallets with operator approval gates, a non-executable AML compiler, and an MCP server served inside the Next.js app. It is a prototype, not a production service.** > **Status:** experimental prototype, version `0.2.1` (from `package.json`). Every feature below is labelled **Implemented**, **Prototype** or **Vision**. No benchmarks have been published. @@ -68,7 +68,7 @@ Agents today mostly run inside tools built for people. HELLO OS tries a differen | 3 | **HELLO Cortex** | Tiered memory, dead-end registry, contract locks, semantic cache, knowledge docs | `/api/hello/cortex/*`, `/api/failures`, `/api/cache`, `/api/knowledge` | Implemented | | 4 | **HELLO Mesh** | In-process MCP server, A2A messages and tasks, delegation trees, consensus | `POST /api/hello/mcp`, `/api/a2a`, `/api/delegation`, `/api/consensus` | Implemented (single node); federation is Vision | | 5 | **HELLO Ledger** | Wallets and spend in credits (H), treasury, approvals, operator gate | `/api/economy/*`, `/api/treasury`, `/api/gate`, `/api/approvals` | Implemented (credits only, no money or tokens) | -| 6 | **HELLO Cloud** | Checkpoints, snapshots and resume, QuickJS sandbox | `/api/hello/cloud/checkpoints`, `/api/snapshots`, `/api/sandbox` | Prototype: records are real, copy-on-write fork is simulated; microVMs are Vision | +| 6 | **HELLO Cloud** | Checkpoint request records and QuickJS sandbox | `/api/hello/cloud/checkpoints`, `/api/sandbox` | Metadata only; no database or VM snapshots or rollback | | 7 | **HELLO Evolve and AI** | Deterministic evolution runs; AI provider (OpenRouter, Kilo Code gateway, any OpenAI-compatible API) for golden replay | `/api/evolution/runs`, `/api/ai/status`, `/api/traces/golden-replay` | Prototype: `/evolve` page is a labelled simulation; AI calls need a key | ```mermaid @@ -103,7 +103,7 @@ mission review_patch { if $symbol.valid { emit: verification_receipt } else { - rollback: checkpoint("before_patch") + emit: review_required } } } @@ -114,7 +114,7 @@ Compile it: ```bash curl -s http://localhost:3000/api/aml/compile \ -H 'Content-Type: application/json' \ - -d '{"source":"mission review_patch {\n input: $patch_id\n budget: 5 H\n steps {\n fetch: forge.readSymbol($patch_id) → $symbol\n if $symbol.valid {\n emit: verification_receipt\n } else {\n rollback: checkpoint(\"before_patch\")\n }\n }\n}"}' + -d '{"source":"mission review_patch {\n input: $patch_id\n budget: 5 H\n steps {\n fetch: forge.readSymbol($patch_id) → $symbol\n if $symbol.valid {\n emit: verification_receipt\n } else {\n emit: review_required\n }\n }\n}"}' ``` The response includes `"ok": true`, `"executable": false`, `"budgets": [{"declaration":"review_patch","amount":5,"unit":"H"}]` and a `tokenMetrics` object. @@ -146,7 +146,7 @@ docker compose up --build # web on 127.0.0.1:3000 ### Option 3: Vercel + Turso -The live app is at **https://hello-os-bice.vercel.app/**. Serverless hosts don't keep a local SQLite file, so Vercel needs a hosted database. Turso support is in **open PR #30** and is not on `main` yet. Once #30 merges: +The live app is at **https://hello-os-bice.vercel.app/**. Serverless hosts don't keep a local SQLite file, so Vercel needs a hosted database. Turso is supported through Prisma's libSQL adapter: ```bash turso auth login @@ -162,11 +162,11 @@ Then set `DATABASE_URL`, `TURSO_AUTH_TOKEN`, `HELLO_AI_PROVIDER` and `HELLO_AI_A | Variable | Purpose | |---|---| -| `DATABASE_URL` | SQLite file (`file:./db/custom.db`), or a `libsql://` URL with #30 | -| `TURSO_AUTH_TOKEN` | Turso token (#30) | +| `DATABASE_URL` | SQLite file (`file:./db/custom.db`), or a `libsql://` URL | +| `TURSO_AUTH_TOKEN` | Turso auth token | | `HELLO_PUBLIC_URL` | Public base URL used in the handshake and agent card | | `HELLO_ALLOWED_ORIGINS` | Comma-separated origins allowed to call MCP | -| `HELLO_OPERATOR_TOKEN` | Protects approvals, kill switch, scheduler, sandbox. If unset, the app runs in dev mode | +| `HELLO_OPERATOR_TOKEN` | Protects approvals, kill switch, scheduler, sandbox. Required in production; local development can use dev mode | | `HELLO_WEBHOOK_SECRET` | HMAC secret for `POST /api/integrations/webhook` | | `GITHUB_TOKEN` | Optional read-only token for `connector.github.read` | | `HELLO_AI_PROVIDER` | `openrouter`, `kilo`, or `custom`. If unset, AI routes return `503 NO_AI_PROVIDER` | @@ -198,7 +198,7 @@ curl -s https://hello-os-bice.vercel.app/api/hello/mcp \ -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","_meta":{"io.modelcontextprotocol/protocolVersion":"2026-07-28"}}' ``` -### The 20 MCP tools +### MCP tools | Tool | What it does | |---|---| @@ -214,8 +214,7 @@ curl -s https://hello-os-bice.vercel.app/api/hello/mcp \ | `cortex.listContracts` | List active contract locks | | `memory.recall` | Search one agent's tiered memory within a token budget | | `memory.write` | Write a memory to CORE, RECALL or ARCHIVE with a lifetime | -| `cloud.checkpoint` | Record a checkpoint before a risky change (copy-on-write fork is simulated) | -| `cloud.rollback` | Roll back to a checkpoint | +| `cloud.checkpoint` | Record a checkpoint request for audit; captures no state and cannot be rolled back | | `connector.sql.query` | Read-only single SELECT/WITH against the HELLO datasource | | `connector.sql.schema` | Reflect tables and columns | | `connector.sql.fingerprint` | SHA-256 schema fingerprint for drift checks | @@ -223,6 +222,10 @@ curl -s https://hello-os-bice.vercel.app/api/hello/mcp \ | `connector.openapi.reflect` | Turn an OpenAPI 3 document into candidate tool definitions (never calls it) | | `connector.webhook.transpile` | Map a webhook payload to a typed, observe-only intent record | +## Session portability + +The optional local CLI/TUI discovers Claude Code, Codex, and OpenCode sessions and ports selected text transcripts between them. It runs on your computer; the HELLO OS web app never reads local harness files. Install Bun, then run `npm run sessions:install`, `npm run sessions -- detect`, or `npm run sessions -- tui`. Transfers are manual; tool calls, reasoning blocks, and attachments are not preserved. See the [session guide](/sessions) and [third-party notices](THIRD_PARTY_NOTICES.md). + ## Downloads **No binaries have been published yet.** There are no installers (APK, EXE, DEB, DMG) and no release checksums. Run from source or Docker. @@ -242,7 +245,7 @@ No. Credits (H) are prototype numbers in the database. There is no on-chain ledg Yes. Retire the agent or use the kill switch. Identities can be revoked by the operator, and gated actions above the approval threshold wait for a human. ### Does it run agents in microVMs? -No. Firecracker microVMs and copy-on-write (CoW) checkpoints are **not built**; they are Vision. Code runs in a QuickJS sandbox, and checkpoint forks are simulated and labelled as simulations. +No. Firecracker microVMs and copy-on-write checkpoints are **not built**; they are Vision. Code runs in a QuickJS sandbox. Checkpoint calls create metadata-only audit records; they capture no state and cannot restore or roll back anything. ### Are Evolution Lab and HELLO EVOLVE real training? No. HELLO Evolve scores are a **deterministic simulation**: they measure the distance of candidate gene vectors to fixed target gene vectors (a candidate matching the target scores 100). They do **not** measure whether an agent got better at real tasks. The `/evolve` page is a labelled browser simulation. @@ -263,7 +266,7 @@ Yes: [`/llms.txt`](https://codesbyfebin.github.io/Hello-OS/llms.txt), [`AGENTS.m These items are proposed, not done, and have no committed dates. The full list is in `src/lib/roadmap/steps.ts` and on the `/roadmap` page. -- Turso database for serverless hosting (PR #30, open) +- Production-grade hosted database operations and deployment hardening - Real file and SQLite checkpoints with restore and SHA-256 receipts - `/evolve` driven by stored evolution runs and golden-set replay - Real evolution evaluation loop: a small set of pinned, versioned agent tasks; per-candidate results reported separately for task success, policy violations, latency and token usage; stored model/provider, prompt version, test revision and traces; promotion only when recorded tests pass and a reviewer approves diff --git a/THIRD_PARTY_NOTICES.md b/THIRD_PARTY_NOTICES.md new file mode 100644 index 0000000..479d0f3 --- /dev/null +++ b/THIRD_PARTY_NOTICES.md @@ -0,0 +1,9 @@ +# Third-party notices + +## Session portability utility + +The local session-portability utility adapts code from [`mem0ai/openmemory`](https://github.com/mem0ai/openmemory), upstream commit `2df78cc48e5f688a771fee5b39899325accc2450` (MIT License). The command, interface, metadata, storage namespace, and HELLO OS integration have been adapted for this repository. No upstream logos or user-facing product branding are included. + +Copyright (c) 2026 Howard Gil + +The full upstream MIT license text is retained at [`tools/session-portability/UPSTREAM-LICENSE`](tools/session-portability/UPSTREAM-LICENSE). diff --git a/compose.yaml b/compose.yaml index a0557d4..46fec5a 100644 --- a/compose.yaml +++ b/compose.yaml @@ -7,41 +7,11 @@ 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} - # Operator auth: containers run with NODE_ENV=production, so operator actions fail closed - # unless you set a token, or HELLO_OPERATOR_DEV_MODE=1 for a local-only instance. HELLO_OPERATOR_TOKEN: ${HELLO_OPERATOR_TOKEN:-} HELLO_OPERATOR_DEV_MODE: ${HELLO_OPERATOR_DEV_MODE:-} 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 - # Operator auth: containers run with NODE_ENV=production, so operator actions fail closed - # unless you set a token, or HELLO_OPERATOR_DEV_MODE=1 for a local-only instance. - HELLO_OPERATOR_TOKEN: ${HELLO_OPERATOR_TOKEN:-} - HELLO_OPERATOR_DEV_MODE: ${HELLO_OPERATOR_DEV_MODE:-} - 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 b82e487..75f4b34 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -11,8 +11,8 @@ Every variable the code reads (`rg "process.env" src mini-services scripts`). Ne | `HELLO_DB_ADAPTER` | unset | `libsql` forces the libSQL adapter for a `file:` URL (used by tests). | | `HELLO_PUBLIC_URL` | `http://localhost:3000` | Base URL for links, the agent card and the MCP handshake. | | `HELLO_ALLOWED_ORIGINS` | localhost:3000/3030 | Comma-separated Origin allow-list for `POST /api/hello/mcp`. | -| `HELLO_MCP_URL` | `http://localhost:3030` | Optional Bun sidecar. MCP also runs in-process at `/api/hello/mcp`. | -| `HELLO_MCP_PORT` | `3030` | Sidecar port. | +| `HELLO_MCP_URL` | unset | Optional standalone MCP sidecar override. MCP runs in-process at `/api/hello/mcp` by default. | +| `HELLO_MCP_PORT` | `3030` | Optional sidecar port. | | `HELLO_FORGE_ROOT` | `./sample-repo` | Repo that the `forge.*` MCP tools parse and patch. | | `HELLO_SYNC_INTERVAL_MS` | `3000` (min 500) | Polling interval for `/api/sync`. | @@ -22,7 +22,7 @@ Every variable the code reads (`rg "process.env" src mini-services scripts`). Ne | --- | --- | --- | | `HELLO_OPERATOR_TOKEN` | unset | Shared secret for operator actions, sent as `x-operator-token`. See [operator-guide.md](operator-guide.md). | -Today, with the token unset, operator routes run in **dev mode** (open to anyone who can reach the port). PR #36 changes this: in production (`NODE_ENV=production` or `VERCEL` set) they fail closed with 503, and `HELLO_OPERATOR_DEV_MODE=1` is the local override. Set a token before exposing the app beyond localhost. +When unset, operator routes fail closed in production. Local development may use dev mode; set a token before exposing the app beyond localhost. ## AI provider (optional, off by default) @@ -30,7 +30,7 @@ Unset = AI features return `503 NO_AI_PROVIDER` with the variables to set. `GET | Variable | Notes | | --- | --- | -| `HELLO_AI_PROVIDER` | `openrouter`, `kilo` or `custom` (`ollama` is added in PR #35). | +| `HELLO_AI_PROVIDER` | `openrouter`, `kilo`, `custom` or `ollama`. | | `HELLO_AI_API_KEY` | Provider key. Required except for `ollama`. | | `HELLO_AI_MODEL` | Default `google/gemma-4-31b-it:free`. | | `HELLO_AI_BASE_URL` | Override. Required for `custom`. | @@ -46,6 +46,10 @@ To turn AI off again, unset `HELLO_AI_PROVIDER`. | `HELLO_WEBHOOK_SECRET` | HMAC-SHA256 secret for `POST /api/integrations/webhook`. The route returns 503 until it is set. | | `GITHUB_TOKEN` | Optional, read-only, for MCP `connector.github.read`. Without it, GitHub's unauthenticated rate limits apply. | +## Session portability + +The optional local CLI/TUI requires Bun. From the repository root, run `npm run sessions:install`, then `npm run sessions -- detect` or `npm run sessions -- tui`. Transfers run on the user's machine and do not upload transcript contents to the web app. + ## Database schema and backup The repo uses `prisma db push` (no migrations directory). After pulling schema changes: 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..46d0c4d 100644 --- a/docs/features/pages.md +++ b/docs/features/pages.md @@ -2,16 +2,17 @@ | 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 | +| `/sessions` | HELLO OS guide for a local CLI/TUI that ports text sessions among Claude Code, Codex, and OpenCode; the web app never reads local files | prototype | +| `/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 56e6480..52e3dca 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 Ops console is at `/ops` and is linked from the Mission Control sidebar. Operator actions fail closed in production unless `HELLO_OPERATOR_TOKEN` is configured. ## 1. Set an operator token ```bash @@ -20,7 +20,7 @@ What happens without a token depends on where the instance runs (`src/lib/operat Operator-only routes: `POST /api/operator` (kill switch, threshold), `POST /api/approvals/:id`, `PATCH`/`POST /api/agents/:id/wallet` (daily cap, circuit breaker, top-up), `POST /api/knowledge` and `/api/knowledge/roles`, `POST /api/sandbox`, the scheduler routes, creating an agent with a tier other than `Seedling`, and the MCP tools listed below. The dashboard's top-up and circuit buttons don't send a token yet, so in production they show the 401/503 error. Use curl with the token, or the Ops console where it has a token field. -## 2. Approvals and risk tiers (PR #5) +## 2. Approvals and risk tiers | Tier | Actions | What happens | | --- | --- | --- | | low | `data.read` | runs | @@ -42,24 +42,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 @@ -67,7 +67,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. MCP tool access -Read-only tools over public data are open. Tools that write state or read private data need the operator token (same rules as above): `forge.patchSymbol`, `cortex.recordDeadEnd`, `cortex.proposeContract`, `cortex.lockInterface`, `memory.write`, `memory.recall`, `cloud.checkpoint`, `cloud.rollback`, `connector.sql.query`. The handshake lists them as `operatorTools`. +Read-only tools over public data are open. Tools that write state or read private data need the operator token (same rules as above): `forge.patchSymbol`, `cortex.recordDeadEnd`, `cortex.proposeContract`, `cortex.lockInterface`, `memory.write`, `memory.recall`, `cloud.checkpoint`, `connector.sql.query`. The handshake lists them as `operatorTools`. - `agentDid` in a call is self-asserted and only labels the log. It does not authenticate the caller. - `receiptHash` is a SHA-256 digest that identifies a logged `McpToolCall` row. It is not a signature and doesn't prove the row was never edited. @@ -75,7 +75,7 @@ Read-only tools over public data are open. Tools that write state or read privat - There is no replay protection or idempotency key: resending a call runs it again. That is one reason write tools are operator-only. ## 8. 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**. The API omits private keys from responses. -## 8. Before exposing an instance +## 9. 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 6999c0e..4f1197a 100644 --- a/package.json +++ b/package.json @@ -3,9 +3,13 @@ "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", + "sessions:install": "cd tools/session-portability && bun install", + "sessions": "cd tools/session-portability && bun run src/cli.ts", + "sessions:test": "cd tools/session-portability && bun test test", + "sessions:typecheck": "cd tools/session-portability && bun run typecheck", "mcp": "bun --hot mini-services/hello-mcp/index.ts", "lint": "eslint .", "db:push": "prisma db push", diff --git a/prisma/turso/2026-10-21-agent-auth.sql b/prisma/turso/2026-10-21-agent-auth.sql index 6040343..5d1e5e6 100644 --- a/prisma/turso/2026-10-21-agent-auth.sql +++ b/prisma/turso/2026-10-21-agent-auth.sql @@ -47,4 +47,3 @@ CREATE INDEX "RateLimitBucket_windowStart_idx" ON "RateLimitBucket"("windowStart -- CreateIndex CREATE UNIQUE INDEX "RateLimitBucket_key_windowStart_key" ON "RateLimitBucket"("key", "windowStart"); - diff --git a/prisma/turso/2026-10-21-eval.sql b/prisma/turso/2026-10-21-eval.sql index 4c4e372..484119b 100644 --- a/prisma/turso/2026-10-21-eval.sql +++ b/prisma/turso/2026-10-21-eval.sql @@ -44,4 +44,3 @@ CREATE INDEX "EvalRun_fingerprint_idx" ON "EvalRun"("fingerprint"); -- CreateIndex CREATE INDEX "EvalPromotion_suiteId_status_decidedAt_idx" ON "EvalPromotion"("suiteId", "status", "decidedAt"); - 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" && ( -
-
- -