feat(ai-agent): bootstrap MVP service from scaffold (#420)

services/ai-agent/README.md

@@ -1,21 +1,91 @@
-# AI Agent Service (Planned Scaffold)
+# AI Agent Service
 
-This directory is intentionally reserved for AI-assisted financial workflow orchestration.
+Minimal MVP service for AI-assisted financial intent drafting on the Ancore platform.
 
-## Why this exists
+## Overview
 
-- Keep product direction explicit without claiming full implementation.
-- Provide a stable location for upcoming AI workflow integration.
-- Separate AI orchestration from wallet core and settlement rails.
+The AI agent parses natural-language prompts into **draft** payment or invoice intents. It never executes any financial operation autonomously — all outputs require explicit user confirmation before any on-chain action is taken.
 
-## Planned responsibilities
+## Endpoints
 
-- Natural-language to financial action intent parsing
-- Safety checks and user confirmation flows
-- Draft invoice/payment request generation
-- Routing to off-chain analytics/risk systems before settlement
+### `GET /health`
 
-## Current status
+Returns service liveness status.
 
-- Scaffold only (service is not implemented yet)
-- Future work tracked in roadmap and issue backlog
+```json
+{ "status": "ok", "service": "ai-agent" }
+```
+
+### `POST /agent/draft-intent`
+
+Parses a prompt into a draft financial intent.
+
+**Request body:**
+
+```json
+{
+  "prompt": "Send 10 XLM to Alice",
+  "accountId": "GABC...",
+  "context": {}
+}
+```
+
+**Response:**
+
+```json
+{
+  "status": "draft",
+  "requiresConfirmation": true,
+  "summary": "Draft payment intent parsed from: \"Send 10 XLM to Alice\"",
+  "intent": {
+    "type": "payment",
+    "destination": "",
+    "amount": "0",
+    "asset": "XLM",
+    "memo": "Send 10 XLM to Alice"
+  }
+}
+```
+
+## Security Boundaries
+
+### What this service does
+
+- Parses natural-language prompts into structured draft intents
+- Returns typed, human-reviewable output for user confirmation
+- Enforces the no-autonomous-execution guardrail on every response
+
+### What this service does NOT do
+
+- **No on-chain execution** — the service never submits transactions to Stellar
+- **No key management** — no private keys are held or accessed
+- **No fund movement** — zero financial operations are performed without explicit user confirmation
+- **No persistent state** — no user data or financial state is stored
+
+### Guardrail enforcement
+
+Every response from `/agent/draft-intent` is validated by `enforceNoAutonomousExecution` before being returned. This function throws if:
+
+- `status` is anything other than `"draft"`
+- `requiresConfirmation` is not `true`
+
+This is a hard invariant: the agent is a **suggestion engine only**.
+
+## Limitations
+
+- The current intent parser is a stub (keyword-based). Replace with a real LLM/NLP integration before production use.
+- Parsed `amount` and `destination` fields are placeholders — the real parser must extract these from the prompt.
+- No authentication or rate limiting is implemented in this MVP. Add these before exposing the service externally.
+- This service is classified as **Medium Risk** per the Ancore security model (`services/**`).
+
+## Development
+
+```bash
+pnpm install
+pnpm test
+pnpm build
+```
+
+## Status
+
+MVP scaffold — not production-ready. See [issue #420](https://github.com/ancore-org/ancore/issues/420) and the [roadmap](../../README.md#roadmap) for planned work.

services/ai-agent/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@ancore/ai-agent",
+  "version": "0.1.0",
+  "description": "AI agent service for draft financial intent generation",
+  "main": "./dist/server.js",
+  "scripts": {
+    "build": "tsc --project tsconfig.json",
+    "test": "jest --coverage",
+    "lint": "eslint src/"
+  },
+  "keywords": [
+    "ancore",
+    "ai-agent",
+    "stellar"
+  ],
+  "license": "Apache-2.0",
+  "dependencies": {
+    "express": "^4.18.2",
+    "zod": "^3.22.4"
+  },
+  "devDependencies": {
+    "@types/express": "^4.17.21",
+    "@types/jest": "^29.5.0",
+    "@types/node": "^20.0.0",
+    "@types/supertest": "^6.0.2",
+    "jest": "^29.7.0",
+    "supertest": "^6.3.4",
+    "ts-jest": "^29.1.0",
+    "typescript": "^5.3.0"
+  },
+  "jest": {
+    "preset": "ts-jest",
+    "testEnvironment": "node",
+    "testMatch": [
+      "**/src/**/*.test.ts",
+      "**/tests/**/*.test.ts"
+    ],
+    "transform": {
+      "^.+\\.tsx?$": [
+        "ts-jest",
+        {
+          "tsconfig": "tsconfig.test.json"
+        }
+      ]
+    }
+  }
+}

services/ai-agent/src/guardrail.ts

@@ -0,0 +1,23 @@
+import type { DraftIntentResponse } from './types';
+
+/**
+ * GUARDRAIL: The AI agent MUST NOT execute any financial operation autonomously.
+ *
+ * All outputs are drafts that require explicit user confirmation before any
+ * on-chain or off-chain action is taken. This function enforces that invariant
+ * by asserting the response is always in "draft" status with requiresConfirmation=true.
+ *
+ * @throws {Error} if the response violates the no-autonomous-execution policy
+ */
+export function enforceNoAutonomousExecution(response: DraftIntentResponse): void {
+  if (response.status !== 'draft') {
+    throw new Error(
+      `GUARDRAIL VIOLATION: response status must be "draft", got "${response.status}"`
+    );
+  }
+  if (response.requiresConfirmation !== true) {
+    throw new Error(
+      'GUARDRAIL VIOLATION: requiresConfirmation must be true — the agent never executes autonomously'
+    );
+  }
+}