diff --git a/README.md b/README.md index 8999260..836b712 100644 --- a/README.md +++ b/README.md @@ -29,9 +29,11 @@ ## Recently shipped -- **May 18, 2026** — Deployed agents can now run selected live skills from their Skills tab and mint agent-tagged receipts. -- **May 18, 2026** — Apogee Pilot chat now mints receipts on-chain. -- **May 17, 2026** — Apogee Pilot full-page experience live at `/apogee-pilot`, streaming via 0G Compute, with on-chain receipts. +- May 17, 2026 — Apogee Pilot full-page chat shipped at `/apogee-pilot`. +- May 18, 2026 — Apogee Pilot chat receipts now mint on-chain. +- May 18, 2026 — Live skills batch 1 shipped: `chat.completion`, `text.summarize`, `text.translate`, `text.sentiment`, `text.entities`, `code.review`. +- May 18, 2026 — User-deployed agents can invoke selected skills from the dashboard, with receipts tagged to the invoking agent. +- May 19, 2026 — Per-skill output rendering shipped and agent status gates hardened for recovered deployments. --- @@ -75,32 +77,22 @@ The result: teams spend weeks on plumbing instead of building products. Apogee e | 1 | **Self-custodial smart wallets** | Every agent gets an `AgentAccount` on 0G Chain with a programmable `PolicyEngine` — spending limits, allowlists, per-action caps, pause flags. No centralized custodian ever touches agent funds. | | 2 | **On-chain receipts** | Every billable action calls `ReceiptBook.emitReceipt(agentId, actionTag, payloadHash, storageRoot, valueWei)` on Aristotle mainnet. The payload is uploaded to 0G Storage first; its Merkle root is the permanent anchor. | | 3 | **Encrypted persistent memory** | Agent memories are AES-256-GCM encrypted, stored as Merkle blobs on 0G Storage, and indexed on-chain. The decryption key is derived from the agent's signer — no third party can read it. | -| 4 | **Paid skills marketplace** | 22 skills (12 free core + 10 premium) run in `isolated-vm` sandboxes. Premium skills charge $0G per call through `PaymentRouter`. `RevenueSplitter` enables creator royalties. | +| 4 | **Paid skills marketplace** | The catalog models 22 skills (12 free core + 10 premium); the production dashboard currently exposes six live invokable skills with receipt-backed execution. Premium skill billing uses `PaymentRouter`; `RevenueSplitter` enables creator royalties. | | 5 | **0G Compute backbone** | `chat.completion`, `chat.embed`, `image.generate`, and `audio.transcribe` route through `@0glabs/0g-serving-broker`. Provider acknowledgement, ChatID extraction from response headers, and `processResponse()` settlement happen automatically. | --- ## What works today -- Wallet connect and wallet ownership/signature flow for sign-in and deployment authorization where enabled. -- Agent deployment through the web app. -- On-chain `AgentIdentity` indexing for agents visible to Apogee. -- `ReceiptBook` receipts and a receipts explorer with safe Chainscan links only for real transaction hashes. +- Wallet connect and wallet ownership/signature flow for sign-in and deployment authorization. +- User-deployable agents with NFT identity, policy, bootstrap memory, selected skill registration, and on-chain lifecycle receipts on Aristotle mainnet. +- Three production heartbeat agents — Aurora analyze, Vesper media, and Helix report — running scheduled jobs and minting receipts. +- Apogee Pilot chat at `/apogee-pilot`, backed by 0G Compute with `pilot.chat` receipts. +- Six live dashboard-callable skills: `chat.completion`, `text.summarize`, `text.translate`, `text.sentiment`, `text.entities`, and `code.review`. +- Agent-scoped skill invocation with owner checks, policy enforcement, 0G Compute execution, per-skill modal output, and receipts tagged to the invoking agent. +- `ReceiptBook` ledger visible at `/proofs`, currently indexing 1,656 Aristotle receipts with safe Chainscan links for real transaction hashes. - Global dashboard metrics for Aristotle network agents, active runtime/demo agents, receipts, and indexed volume. -- Marketplace skill catalog and services catalog. -- System/bootstrap memory for newly deployed agents. -- Selected skills attached to new deployments. -- Demo runtime receipts from scheduled heartbeat agents. -- `/proofs` page for live receipt/proof visibility, payload hashes, and optional 0G Storage roots. - -## Roadmap / not yet fully automated - -- Full autonomous recurring runtime scheduling for arbitrary user-created agents. -- Session-key/delegation flow for user agents. -- True paid marketplace install/purchase flow. -- On-chain policy editing UI. -- Revenue split UI actions. -- Richer memory writes beyond bootstrap for arbitrary newly-created agents. +- Marketplace skill and service catalog backed by seeded Edge metadata. --- @@ -137,7 +129,7 @@ Full sequence diagrams: [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) | **EscrowVault** | Deferred payment escrow | `0x3c0879852e8956cfFCD8C9a2fa8b078b06DB2767` | [chainscan.0g.ai](https://chainscan.0g.ai/address/0x3c0879852e8956cfFCD8C9a2fa8b078b06DB2767) | | **AgentAccount** | Smart wallet implementation | `0xc18eD4e075a23A66505744A353eeFE91340F924d` | [chainscan.0g.ai](https://chainscan.0g.ai/address/0xc18eD4e075a23A66505744A353eeFE91340F924d) | | **0G Storage** | Payload + memory blobs | `indexer-storage-turbo.0g.ai` | Aristotle chainId 16661 | -| **0G Compute** | Inference backbone | `@0glabs/0g-serving-broker 0.6.5` | TEE-attested providers | +| **0G Compute** | Inference backbone | `@0glabs/0g-serving-broker` | TEE-attested providers | --- @@ -146,8 +138,10 @@ Full sequence diagrams: [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) ### Prerequisites - Node.js 20.18.x LTS, pnpm 9.12.x -- 0G-compatible wallet + testnet tokens from [faucet.0g.ai](https://faucet.0g.ai) +- 0G-compatible wallet with Aristotle network tokens - PostgreSQL 16 and Redis 7 +- Production app: [apogeeprotocol.vercel.app](https://apogeeprotocol.vercel.app) +- Production Edge API: [apogeeedge-production.up.railway.app](https://apogeeedge-production.up.railway.app/v1/health) ### Clone and install @@ -165,14 +159,15 @@ cp .env.example .env ``` ```env -DEPLOYER_PRIVATE_KEY=0x... # Wallet funded with testnet 0G -EDGE_SERVICE_PRIVATE_KEY=0x... # Service-account signing key +DEPLOYER_PRIVATE_KEY=0x... # Wallet funded with Aristotle 0G +EDGE_SERVICE_PRIVATE_KEY=0x... # Edge relayer + 0G Compute payment wallet +PILOT_AGENT_PRIVATE_KEY=0x... # Dedicated Pilot service wallet identity DATABASE_URL=postgresql://user:pass@localhost:5432/apogee REDIS_URL=redis://localhost:6379 JWT_SECRET=<32-char-random-string> EDGE_JWT_SECRET=<32-char-random-string> -ZERO_G_GALILEO_RPC_URL=https://evmrpc-testnet.0g.ai -ZERO_G_STORAGE_INDEXER_URL=https://indexer-storage-testnet-turbo.0g.ai +ZERO_G_ARISTOTLE_RPC_URL=https://evmrpc.0g.ai +ZERO_G_STORAGE_INDEXER_URL=https://indexer-storage-turbo.0g.ai ``` ### Database @@ -194,11 +189,11 @@ pnpm -F @apogee/runtime dev pnpm -F @apogee/web dev ``` -### Deploy to Galileo testnet +### Deploy contracts to Aristotle mainnet ```bash -pnpm -F @apogee/contracts deploy:galileo -pnpm -F @apogee/contracts seed:agents --testnet +pnpm -F @apogee/contracts deploy:aristotle +pnpm -F @apogee/contracts seed:demo-agents ``` ### Smoke tests @@ -210,7 +205,7 @@ pnpm -F @apogee/runtime heartbeat:once vesper pnpm -F @apogee/runtime heartbeat:once helix ``` -Full deployment guide: [docs/REVIEWER.md](docs/REVIEWER.md) +Full deployment guide: [docs/REVIEWER.md](docs/REVIEWER.md). Production surfaces are the Vercel web app and Railway Edge API linked above. --- @@ -228,7 +223,18 @@ Three agents are live on Aristotle mainnet. Receipts are visible at [apogeeproto ## Skills Catalog -### Free Core Skills (12) +### Live dashboard skills (6) + +| Skill | Description | +|-------|-------------| +| `chat.completion` | Chat inference via 0G Compute with agent-tagged receipts. | +| `text.summarize` | Concise summaries via 0G Compute. | +| `text.translate` | Translation to a requested target language. | +| `text.sentiment` | Sentiment classification with normalized score. | +| `text.entities` | Named entity extraction. | +| `code.review` | Concise code review via 0G Compute. | + +### Cataloged Free Core Skills (12) | Skill | Description | |-------|-------------| diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md index 2fa06c4..a5f254e 100644 --- a/docs/ARCHITECTURE.md +++ b/docs/ARCHITECTURE.md @@ -28,35 +28,41 @@ Apogee is a four-layer autonomous-agent runtime: ## 2. Component Interaction Diagrams -### 2.1 Agent Skill Execution (paid skill call) +### 2.1 Agent Skill Execution (dashboard skill call) ```mermaid sequenceDiagram participant U as User (browser) participant W as Web (Next.js) participant E as Edge API - participant SK as SkillRunner participant C as 0G Compute + participant S as 0G Storage participant CB as ReceiptBook (chain) - - U->>W: POST /api/pilot/chat - W->>E: POST /v1/pilot/chat (server-side proxy) - E->>E: verify JWT, get agentId - E->>SK: runner.execute("chat.completion", input, ctx) - SK->>SK: spawn isolated-vm sandbox (128 MB, 30s TTL) - SK->>C: compute.chatCompletion(messages) - C-->>SK: stream tokens - SK-->>E: output + provenance (chatId, storageRoot) - E->>CB: receiptMinter.mint({ agentId, actionTag, payload }) - CB-->>E: { receiptId, txHash, storageRoot } - E-->>W: SSE stream (token events → done event with receiptId) - W-->>U: rendered response + receipt link + participant P as /proofs page + + U->>W: Run skill from agent Skills tab + W->>E: POST /v1/skills/:skillId/invoke { agentId, input } + E->>E: verify JWT owner, selected skill, policy caps + E->>E: read onboarding/deployment status from durable store + E->>C: compute.chat({ messages, maxTokens }) + C-->>E: normalized output + chatId + usage + E->>S: upload canonical receipt payload + S-->>E: { storageRoot, storageTxHash } + E->>CB: ReceiptBook.emitReceipt(agentId, actionTag, payloadHash, storageRoot) + CB-->>E: { receiptId, txHash } + E->>E: index receipt and auto-promote agent active on first receipt + E-->>W: { output, compute, receipt } + W-->>U: per-skill modal output + receipt link + P->>E: GET /v1/proofs + E-->>P: agent name, action label, tx hash, storage root ``` +Production live skills are `chat.completion`, `text.summarize`, `text.translate`, `text.sentiment`, `text.entities`, and `code.review`. The modal renderer consumes canonical Edge output shapes (`output.content`, `output.summary`, `output.translation`, `output.sentiment`, `output.entities`, `output.review`) and falls back to raw JSON only for malformed outputs. + -### 2.3 Apogee Pilot inference and receipts +### 2.2 Apogee Pilot inference and receipts -Apogee Pilot is exposed both as the floating in-app launcher and as the full-page `/apogee-pilot` chat surface. The browser posts to `apps/web` at `/api/pilot/chat`; the Next.js route runs on the Node.js runtime and forwards the stream plus the `apogee-jwt` cookie as a Bearer token to Edge `/v1/pilot/chat` without buffering. +Apogee Pilot is exposed both as the floating in-app launcher and as the full-page `/apogee-pilot` chat surface. The browser posts to `apps/web` at `/api/pilot/chat`; the Next.js route runs on the Node.js runtime and forwards the stream plus the `apogee-jwt` cookie as a Bearer token to Edge `/v1/pilot/chat` without buffering. The route uses the configured `PILOT_AGENT_PRIVATE_KEY` service wallet identity for unauthenticated widget receipt payloads and mints indexed `pilot.chat` receipts through the authorized Edge relayer. Edge serves Pilot with a three-tier inference strategy: @@ -64,9 +70,9 @@ Edge serves Pilot with a three-tier inference strategy: 2. **HTTP LLM fallback** — existing `PILOT_LLM_BASE_URL` / `PILOT_LLM_API_KEY` OpenAI-compatible stream, also used when `APOGEE_PILOT_USE_COMPUTE=false`. 3. **Simulated fallback** — deterministic `simulatePilotTokens()` responses when both live inference paths are unavailable. -Every completed Pilot chat can mint a non-blocking ReceiptBook receipt with indexed action label `pilot.chat` (encoded as bytes4 `pilo` on-chain). Authenticated requests use the user wallet address in the receipt payload; unauthenticated widget requests use the configured `PILOT_AGENT_PRIVATE_KEY` service wallet identity. Pilot is not an agent iNFT, so receipts use `agentId=0` as a system sentinel; `ReceiptBook.emitReceipt` permits this and existing system contracts already emit `agentId=0` receipts. If a client cancels after tokens have streamed, Edge mints the same receipt payload with `cancelled: true`; zero-token aborts do not mint. Conversation history remains bounded in-memory LRU state on Edge and no Prisma migration is used for Ship 1. +Every completed Pilot chat can mint a non-blocking ReceiptBook receipt with indexed action label `pilot.chat` (encoded as bytes4 `pilo` on-chain). Authenticated requests use the user wallet address in the receipt payload; unauthenticated widget requests use the configured `PILOT_AGENT_PRIVATE_KEY` service wallet identity. Pilot is not an agent iNFT, so receipts use `agentId=0` as a system sentinel; `ReceiptBook.emitReceipt` permits this and existing system contracts already emit `agentId=0` receipts. If a client cancels after tokens have streamed, Edge mints the same receipt payload with `cancelled: true`; zero-token aborts do not mint. Conversation history remains bounded in-memory LRU state on Edge. -### 2.2 Heartbeat Loop (Aurora — every 10 min) +### 2.3 Heartbeat Loop (Aurora — every 10 min) ```mermaid sequenceDiagram @@ -94,7 +100,7 @@ sequenceDiagram EE-->>W: 200 OK ``` -### 2.3 Storage Proof Path +### 2.4 Storage Proof Path ```mermaid sequenceDiagram @@ -115,7 +121,7 @@ sequenceDiagram P-->>P: render Storage Proofs table ``` -### 2.4 SIWE Authentication Flow +### 2.5 SIWE Authentication Flow ```mermaid sequenceDiagram @@ -142,6 +148,8 @@ sequenceDiagram ## 3. Data Flow — Receipt Lifecycle +The on-chain `ReceiptBook` stores compact receipt fields, including a bytes4 action tag. Edge keeps the richer indexed metadata used by the product UI: full action labels such as `text.summarize`, agent display names such as `Francc Alpha`, storage transaction hashes, and normalized skill outputs. `/proofs` reads this Edge metadata and links only real 32-byte transaction hashes to Chainscan, which is why the UI can display full skill names even though on-chain encoding is intentionally compact. + ``` Agent action occurs │ @@ -239,7 +247,13 @@ ServiceRegistry └── lookup by serviceId or owner ``` -## 6. Infrastructure +## 6. Compute and signer roles + +- `EDGE_SERVICE_PRIVATE_KEY` is the Edge service wallet. It pays for 0G Compute through the broker ledger, signs provider requests, and performs service-account Edge operations. +- `PILOT_AGENT_PRIVATE_KEY` is the dedicated Apogee Pilot service wallet identity used in Pilot receipt payloads. It is separate from the Edge compute/payment wallet so operators can rotate or fund the roles independently. +- Receipt minting is still submitted by the authorized server-side receipt relayer to `ReceiptBook` on Aristotle mainnet. + +## 7. Infrastructure | Component | Host | Notes | |---|---|---| @@ -248,10 +262,10 @@ ServiceRegistry | Runtime (BullMQ workers) | Railway | Same process as Edge; `HEARTBEATS_PAUSED=false` to activate | | PostgreSQL | Railway | Managed; Prisma migrations | | Redis | Railway | BullMQ queues; `heartbeats` queue | -| 0G Chain | Aristotle mainnet | RPC: https://evmrpc-testnet.0g.ai | -| 0G Storage Indexer | 0G managed | SDK: `@0gfoundation/0g-ts-sdk@1.2.8` | +| 0G Chain | Aristotle mainnet | RPC: https://evmrpc.0g.ai | +| 0G Storage Indexer | 0G managed | `https://indexer-storage-turbo.0g.ai`, SDK `@0gfoundation/0g-ts-sdk@1.2.8` | -## 7. ADR Index +## 8. ADR Index | ADR | Title | Status | |---|---|---| diff --git a/docs/DECISIONS.md b/docs/DECISIONS.md index 743ffa0..db1b24d 100644 --- a/docs/DECISIONS.md +++ b/docs/DECISIONS.md @@ -1,5 +1,37 @@ # Decisions +## 2026-05-19 — Compute ledger seeded with 3 OG + +- The Edge compute wallet funded the 0G Compute broker ledger via `broker.ledger.depositFund` with 3 OG so production skill invocation can settle provider usage without per-call manual funding. +- `EDGE_SERVICE_PRIVATE_KEY` handles 0G Compute payments and Edge service-account operations. +- `PILOT_AGENT_PRIVATE_KEY` remains the dedicated Pilot service wallet identity used in receipt payloads; on-chain receipt mints are still relayed by the authorized Edge receipt minter. +- The two-wallet split is intentional operator guidance: compute payments and Pilot identity should not be conflated. + +## 2026-05-19 — Edge skill-invoke gate reads bootstrap state from persistent onboarding + +- Skill invocation now reads `bootstrapComplete` from the persistent onboarding record in Redis instead of relying on in-memory `store.skills`. +- This closes the activation-status circular dependency where recovered agents could have complete onboarding persisted but an empty in-memory skills index after Edge restart. +- The legacy installed-skills fallback remains for older rows, but persistent onboarding is the production source of truth. + +## 2026-05-19 — Increased Edge skill token budget for GLM final content + +- GLM can still spend hundreds of completion tokens on reasoning before emitting final `message.content`, even when non-streaming skill requests send `chat_template_kwargs: { enable_thinking: false }`. +- Edge skill invokes now reserve a larger completion-token budget so the provider can emit final content instead of returning reasoning-only payloads. +- This eliminated `[object Object]` and reasoning leakage in the skills modal while preserving the canonical output shapes (`output.summary`, `output.translation`, etc.). + +## 2026-05-19 — Skill-invoke gate trusts active persistent deployments + +- Skill invocation now trusts `deployment.status === 'active'` when recovered agent rows lag behind and still say `activating`. +- Owner authentication, selected-skill allowlists, policy enforcement, and receipt minting remain unchanged. +- This removed the residual `409 Activation in progress` edge case for already-active deployments. + +## 2026-05-19 — Skill invocation verified end-to-end across the production paths + +- Francc Alpha #29 verified the five selected dashboard skills end-to-end: `text.summarize`, `text.translate`, `text.sentiment`, `text.entities`, and `code.review`. +- `chat.completion` is covered by the Apogee Pilot path, which uses the same 0G Compute pipeline and mints indexed `pilot.chat` receipts. +- Each verified production path returns real UI-ready output, mints an on-chain ReceiptBook receipt, and appears on `/proofs` with the invoking agent or Pilot identity. +- Apogee v0.1 is marked production-ready as a real protocol demo: user-deployed agents, policy-scoped skills, 0G Compute execution, and on-chain receipts all work together. + ## 2026-05-19 — Skill output shape is normalized at the compute boundary - Production `POST /v1/skills/text.summarize/invoke` returned `{ output: { summary: "[object Object]" } }`, so the PR #13 frontend renderer was reading the right path (`result.output.summary`) but Edge had already shaped an invalid summary string.