aimeat 1.7.0 → 1.9.0

package/dist/src/routes/agent-webhook.js

@@ -0,0 +1,243 @@
+/**
+ * @file agent-webhook.ts
+ * @description REST endpoints for agent webhook CRUD (register, get, delete, test, delivery log).
+ *   Owners can manage webhooks for any of their agents; agents can manage their own.
+ * @structure
+ *   - PUT    /v1/agents/:name/webhook       -- Register or update webhook
+ *   - GET    /v1/agents/:name/webhook       -- Get webhook config and status
+ *   - DELETE /v1/agents/:name/webhook       -- Remove webhook
+ *   - POST   /v1/agents/:name/webhook/test  -- Send a test event to the webhook
+ *   - GET    /v1/agents/:name/webhook/log   -- Get delivery log
+ * @version-history
+ *   v1.0.0 -- 2026-05-23 -- Initial creation for Agent Dashboard webhook management
+ */
+import { Router } from 'express';
+import { randomBytes, randomUUID, createHmac } from 'node:crypto';
+import { z } from 'zod';
+import { success, error } from '../middleware/envelope.js';
+import { requireAuth } from '../auth/middleware.js';
+import { buildGAII } from '../utils/gaii.js';
+import { validateOutboundUrl } from '../utils/url-validator.js';
+import { emitChange } from '../services/event-bus.js';
+/* ── Zod validation schema ── */
+const WebhookPutSchema = z.object({
+    url: z.string().url().max(2048),
+    secret: z.string().min(16).max(256).optional(),
+});
+export function agentWebhookRouter(config, storage) {
+    const router = Router();
+    /** Build GAII for the named agent under the authenticated owner */
+    function resolveAgentGaii(req, agentName) {
+        const owner = req.auth.owner;
+        return buildGAII(agentName, owner, config.nodeId);
+    }
+    /** Check if current session can access an agent's webhook */
+    function canAccessAgent(req, agentName) {
+        const roles = req.auth.roles;
+        const isOwnerSession = roles.includes('owner') && !roles.includes('agent');
+        if (isOwnerSession)
+            return true;
+        if (roles.includes('agent')) {
+            return req.auth.sub === resolveAgentGaii(req, agentName);
+        }
+        return false;
+    }
+    /* ── PUT /v1/agents/:name/webhook -- Register or update webhook ── */
+    router.put('/v1/agents/:name/webhook', requireAuth(), async (req, res) => {
+        const agentName = req.params.name;
+        if (!canAccessAgent(req, agentName)) {
+            res.status(403).json(error(config.nodeId, 'FORBIDDEN', 'Access denied'));
+            return;
+        }
+        const agentGaii = resolveAgentGaii(req, agentName);
+        // Verify agent exists
+        const agent = await storage.getAgent(agentGaii);
+        if (!agent) {
+            res.status(404).json(error(config.nodeId, 'NOT_FOUND', `Agent '${agentName}' not found`));
+            return;
+        }
+        // Validate body
+        const parsed = WebhookPutSchema.safeParse(req.body);
+        if (!parsed.success) {
+            res.status(400).json(error(config.nodeId, 'INVALID_INPUT', parsed.error.issues.map(i => `${i.path.join('.')}: ${i.message}`).join('; ')));
+            return;
+        }
+        const { url, secret } = parsed.data;
+        // SSRF check
+        const urlCheck = await validateOutboundUrl(url);
+        if (!urlCheck.valid) {
+            res.status(400).json(error(config.nodeId, 'INVALID_URL', urlCheck.reason ?? 'URL is not allowed'));
+            return;
+        }
+        // Generate a random secret if not provided
+        const webhookSecret = secret ?? randomBytes(32).toString('hex');
+        await storage.updateAgent(agentGaii, {
+            webhookUrl: url,
+            webhookSecret,
+            webhookEnabled: true,
+            webhookFailCount: 0,
+        });
+        emitChange('agents');
+        res.json(success(config.nodeId, {
+            url,
+            secret: webhookSecret,
+            enabled: true,
+        }));
+    });
+    /* ── GET /v1/agents/:name/webhook -- Get webhook config and status ── */
+    router.get('/v1/agents/:name/webhook', requireAuth(), async (req, res) => {
+        const agentName = req.params.name;
+        if (!canAccessAgent(req, agentName)) {
+            res.status(403).json(error(config.nodeId, 'FORBIDDEN', 'Access denied'));
+            return;
+        }
+        const agentGaii = resolveAgentGaii(req, agentName);
+        const agent = await storage.getAgent(agentGaii);
+        if (!agent) {
+            res.status(404).json(error(config.nodeId, 'NOT_FOUND', `Agent '${agentName}' not found`));
+            return;
+        }
+        if (!agent.webhookUrl) {
+            res.json(success(config.nodeId, {
+                configured: false,
+            }));
+            return;
+        }
+        res.json(success(config.nodeId, {
+            configured: true,
+            url: agent.webhookUrl,
+            enabled: agent.webhookEnabled ?? false,
+            last_success: agent.webhookLastSuccess ?? null,
+            last_failure: agent.webhookLastFailure ?? null,
+            fail_count: agent.webhookFailCount ?? 0,
+        }));
+    });
+    /* ── DELETE /v1/agents/:name/webhook -- Remove webhook ── */
+    router.delete('/v1/agents/:name/webhook', requireAuth(), async (req, res) => {
+        const agentName = req.params.name;
+        if (!canAccessAgent(req, agentName)) {
+            res.status(403).json(error(config.nodeId, 'FORBIDDEN', 'Access denied'));
+            return;
+        }
+        const agentGaii = resolveAgentGaii(req, agentName);
+        const agent = await storage.getAgent(agentGaii);
+        if (!agent) {
+            res.status(404).json(error(config.nodeId, 'NOT_FOUND', `Agent '${agentName}' not found`));
+            return;
+        }
+        // Use null (cast through any) to clear nullable fields in MongoDB/Prisma.
+        // Prisma treats undefined as "don't update" but null as "set to null".
+        await storage.updateAgent(agentGaii, {
+            webhookUrl: null,
+            webhookSecret: null,
+            webhookEnabled: false,
+            webhookFailCount: 0,
+            webhookLastSuccess: null,
+            webhookLastFailure: null,
+        });
+        emitChange('agents');
+        res.json(success(config.nodeId, { removed: true }));
+    });
+    /* ── POST /v1/agents/:name/webhook/test -- Send test event ── */
+    router.post('/v1/agents/:name/webhook/test', requireAuth(), async (req, res) => {
+        const agentName = req.params.name;
+        if (!canAccessAgent(req, agentName)) {
+            res.status(403).json(error(config.nodeId, 'FORBIDDEN', 'Access denied'));
+            return;
+        }
+        const agentGaii = resolveAgentGaii(req, agentName);
+        const agent = await storage.getAgent(agentGaii);
+        if (!agent) {
+            res.status(404).json(error(config.nodeId, 'NOT_FOUND', `Agent '${agentName}' not found`));
+            return;
+        }
+        if (!agent.webhookUrl || !agent.webhookSecret) {
+            res.status(400).json(error(config.nodeId, 'NO_WEBHOOK', 'No webhook configured for this agent'));
+            return;
+        }
+        // Build test payload
+        const payload = {
+            event: 'webhook.test',
+            agent: agentGaii,
+            node: config.nodeId,
+            timestamp: new Date().toISOString(),
+            data: { message: 'Webhook test delivery' },
+        };
+        const body = JSON.stringify(payload);
+        const signature = createHmac('sha256', agent.webhookSecret).update(body).digest('hex');
+        const startMs = Date.now();
+        let httpStatus;
+        let deliveryError;
+        try {
+            const resp = await fetch(agent.webhookUrl, {
+                method: 'POST',
+                headers: {
+                    'Content-Type': 'application/json',
+                    'X-AIMEAT-Signature': `sha256=${signature}`,
+                    'X-AIMEAT-Event': 'webhook.test',
+                },
+                body,
+                signal: AbortSignal.timeout(10_000),
+            });
+            httpStatus = resp.status;
+            if (!resp.ok) {
+                deliveryError = `HTTP ${resp.status}`;
+            }
+        }
+        catch (err) {
+            deliveryError = err instanceof Error ? err.message : 'Delivery failed';
+        }
+        const latencyMs = Date.now() - startMs;
+        const deliveryStatus = deliveryError ? 'failed' : 'success';
+        // Log the delivery
+        await storage.appendDeliveryLog({
+            id: randomUUID(),
+            agentGaii,
+            event: 'webhook.test',
+            payload,
+            status: deliveryStatus,
+            httpStatus,
+            errorMessage: deliveryError,
+            attemptCount: 1,
+            latencyMs,
+            createdAt: new Date().toISOString(),
+        });
+        // Update last success/failure on the agent
+        const now = new Date().toISOString();
+        if (deliveryStatus === 'success') {
+            await storage.updateAgent(agentGaii, { webhookLastSuccess: now });
+        }
+        else {
+            await storage.updateAgent(agentGaii, {
+                webhookLastFailure: now,
+                webhookFailCount: (agent.webhookFailCount ?? 0) + 1,
+            });
+        }
+        res.json(success(config.nodeId, {
+            delivered: deliveryStatus === 'success',
+            status: deliveryStatus,
+            http_status: httpStatus ?? null,
+            error: deliveryError ?? null,
+            latency_ms: latencyMs,
+        }));
+    });
+    /* ── GET /v1/agents/:name/webhook/log -- Delivery log ── */
+    router.get('/v1/agents/:name/webhook/log', requireAuth(), async (req, res) => {
+        const agentName = req.params.name;
+        if (!canAccessAgent(req, agentName)) {
+            res.status(403).json(error(config.nodeId, 'FORBIDDEN', 'Access denied'));
+            return;
+        }
+        const agentGaii = resolveAgentGaii(req, agentName);
+        const agent = await storage.getAgent(agentGaii);
+        if (!agent) {
+            res.status(404).json(error(config.nodeId, 'NOT_FOUND', `Agent '${agentName}' not found`));
+            return;
+        }
+        const limit = Math.min(Math.max(parseInt(req.query.limit) || 50, 1), 200);
+        const deliveries = await storage.listDeliveryLog(agentGaii, limit);
+        res.json(success(config.nodeId, { deliveries }));
+    });
+    return router;
+}
+//# sourceMappingURL=agent-webhook.js.map

package/dist/src/routes/agent-webhook.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-webhook.js","sourceRoot":"","sources":["../../../src/routes/agent-webhook.ts"],"names":[],"mappings":"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"}

package/dist/src/routes/agents.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"agents.d.ts","sourceRoot":"","sources":["../../../src/routes/agents.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,SAAS,CAAC;AAOjC,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AACjD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,yBAAyB,CAAC;AAgBvD,wBAAgB,YAAY,CAAC,MAAM,EAAE,YAAY,EAAE,OAAO,EAAE,OAAO,GAAG,MAAM,CAkjC3E"}
+{"version":3,"file":"agents.d.ts","sourceRoot":"","sources":["../../../src/routes/agents.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,SAAS,CAAC;AAOjC,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AACjD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,yBAAyB,CAAC;AAkBvD,wBAAgB,YAAY,CAAC,MAAM,EAAE,YAAY,EAAE,OAAO,EAAE,OAAO,GAAG,MAAM,CA6wC3E"}

package/dist/src/routes/agents.js

@@ -15,6 +15,8 @@ import { AgentRegistrationSchema, validateBody } from '../models/schemas.js';
 import { verifyJWT, issueJWT, generateSessionId } from '../auth/jwt.js';
 import { rateLimit } from '../middleware/rate-limit.js';
 import { emitChange } from '../services/event-bus.js';
+import { createDefaultSteps } from '../models/agent-onboarding-schemas.js';
+import { detectPlatform } from '../services/platform-detector.js';
 /** Device authorization code expires after 30 minutes */
 const DEVICE_AUTH_EXPIRY_MS = 1_800_000;
 export function agentsRouter(config, storage) {
@@ -78,8 +80,9 @@ export function agentsRouter(config, storage) {
             verification_uri_complete: verificationUriComplete,
             expires_in: 1800,
             interval: 5,
+            user_instructions: `Tell your owner to approve this request. They can find it in their AIMEAT profile under Agents (${baseUrl}/v1/profile -> Agents tab). The verification code is: ${userCode}. Once approved, poll POST /v1/agents/device-token with { "device_code": "${deviceCode}", "grant_type": "urn:ietf:params:oauth:grant-type:device_code" } every 5 seconds until you receive your token.`,
         }, [
-            { description: 'Open this URL in a browser', method: 'GET', url: `/v1/agents/verify?code=${userCode}` },
+            { description: 'Owner approves in AIMEAT profile -> Agents tab', method: 'GET', url: `${baseUrl}/v1/profile` },
             { description: 'Poll for authorization result', method: 'POST', url: '/v1/agents/device-token' },
         ]));
         emitChange('agents');
@@ -141,17 +144,41 @@ export function agentsRouter(config, storage) {
                 // Return credentials and immediately clear them
                 const creds = request.agentCredentials;
                 await storage.updateDeviceAuth(device_code, { agentCredentials: null });
+                const baseUrl = config.baseUrl;
+                const agentName = request.agentName;
                 res.json({
+                    access_token: creds.token,
+                    token: creds.token,
+                    token_type: 'Bearer',
                     gaii: creds.gaii,
-                    name: request.agentName,
+                    name: agentName,
                     owner: request.ownerName,
-                    token: creds.token,
                     expires_at: creds.expires_at,
                     privateKey: creds.privateKey,
                     publicKey: creds.publicKey,
                     scopes: request.scopes,
                     morselBalance: 0,
-                    note: 'Use the token directly: Authorization: Bearer <token>. The privateKey is provided for advanced use (Ed25519 signing) but is not required.',
+                    next_steps: {
+                        message: 'Authentication successful. Your MANDATORY first action: download and read your skill bundle.',
+                        step_1_skill_bundle: {
+                            action: 'Download your skill bundle ZIP, extract it, and read SKILL.md. It contains your personalized operating instructions, directives, rules, and complete API reference.',
+                            method: 'GET',
+                            url: `${baseUrl}/v1/agents/${agentName}/skill-bundle`,
+                            auth: 'Authorization: Bearer <your token from above>',
+                        },
+                        step_2_system_prompt: {
+                            action: 'Read your system prompt for additional operating context.',
+                            method: 'GET',
+                            url: `${baseUrl}/v1/prompts/tier1`,
+                            auth: 'Authorization: Bearer <your token from above>',
+                        },
+                        step_3_hello_integration: {
+                            action: 'Check your onboarding status and complete the Hello Integration steps. A test task is already created for you. GET this endpoint auto-validates steps and auto-starts the test task after you propose todos -- always re-check here instead of trying POST /start.',
+                            method: 'GET',
+                            url: `${baseUrl}/v1/agents/${agentName}/onboarding`,
+                            auth: 'Authorization: Bearer <your token from above>',
+                        },
+                    },
                 });
                 return;
             }
@@ -310,6 +337,150 @@ export function agentsRouter(config, storage) {
             existing_agent: !!existing,
         }));
         emitChange('agents');
+        // ── Auto-start Hello Integration onboarding ──
+        const onboardingSteps = createDefaultSteps();
+        onboardingSteps[0].status = 'passed';
+        onboardingSteps[0].validatedAt = now;
+        onboardingSteps[0].validationMethod = 'automatic';
+        onboardingSteps[0].details = { createdAt: existing?.createdAt ?? now };
+        const detectedPlatform = detectPlatform(req.headers['user-agent']);
+        if (detectedPlatform) {
+            onboardingSteps[1].status = 'passed';
+            onboardingSteps[1].validatedAt = now;
+            onboardingSteps[1].validationMethod = 'automatic';
+            onboardingSteps[1].details = { platform: detectedPlatform.id, version: detectedPlatform.version };
+            await storage.updateAgent(gaii, {
+                platform: detectedPlatform.id,
+                platformVersion: detectedPlatform.version,
+                platformDetectedBy: detectedPlatform.detectedBy,
+            });
+        }
+        const existingOnboarding = await storage.getOnboarding(gaii);
+        if (!existingOnboarding) {
+            const testTaskId = randomUUID();
+            await storage.createAgentTask({
+                id: testTaskId,
+                agentGaii: gaii,
+                ownerGaii: `${ownerPayload.owner}@${config.nodeId}`,
+                title: 'Onboarding verification',
+                description: 'This is a test task created during Hello Integration. Propose todos, get approval, execute, and complete.',
+                status: 'queued',
+                scope: [],
+                rules: [],
+                todos: [],
+                verification: { userExpects: 'Agent completes the onboarding test task successfully', technicalChecks: [] },
+                createdAt: now,
+                updatedAt: now,
+            });
+            onboardingSteps[8].details = { testTaskId };
+            await storage.createOnboarding({
+                agentGaii: gaii,
+                status: 'in_progress',
+                startedAt: now,
+                steps: onboardingSteps,
+                detectedPlatform: detectedPlatform?.id,
+            });
+            emitChange('agent-onboarding');
+        }
+    });
+    // POST /v1/agents/connect — register an agent via connectivity key (no auth required)
+    router.post('/v1/agents/connect', async (req, res) => {
+        const { connectivity_key, agent_name, display_name } = req.body ?? {};
+        if (!connectivity_key) {
+            res.status(400).json(error(config.nodeId, 'INVALID_INPUT', 'connectivity_key is required'));
+            return;
+        }
+        const otk = await storage.consumeOtk(connectivity_key, config.otkGraceMs);
+        if (!otk || otk.action !== 'register_agent') {
+            res.status(404).json(error(config.nodeId, 'INVALID_KEY', 'Connectivity key not found, already used, or invalid'));
+            return;
+        }
+        const owner = otk.params.owner;
+        const finalName = agent_name ?? otk.params.agent_name;
+        if (!finalName) {
+            res.status(400).json(error(config.nodeId, 'INVALID_INPUT', 'agent_name is required (either in the connectivity key or in the request body)'));
+            return;
+        }
+        const nameError = validateAgentName(finalName);
+        if (nameError) {
+            res.status(400).json(error(config.nodeId, 'INVALID_INPUT', nameError));
+            return;
+        }
+        const ownerRecord = await storage.getOwner(owner);
+        if (!ownerRecord) {
+            res.status(404).json(error(config.nodeId, 'NOT_FOUND', `Owner "${owner}" not found`));
+            return;
+        }
+        const gaii = buildGAII(finalName, owner, config.nodeId);
+        const existing = await storage.getAgent(gaii);
+        if (existing) {
+            res.status(409).json(error(config.nodeId, 'NAME_TAKEN', `Agent "${finalName}" already exists under owner "${owner}"`));
+            return;
+        }
+        const keyPair = await generateKeyPair();
+        const now = new Date().toISOString();
+        const description = otk.params.description ?? undefined;
+        const requestedScopes = config.defaultAgentScopes;
+        await storage.createAgent({
+            name: finalName,
+            owner,
+            gaii,
+            displayName: display_name ?? finalName,
+            description,
+            capabilities: [],
+            defaultScopes: requestedScopes,
+            publicKey: keyPair.publicKey,
+            trustScore: 50,
+            morselBalance: 0,
+            createdAt: now,
+            lastSeen: now,
+        });
+        fireHook(config, storage, 'post_agent_registration', { gaii, owner });
+        // Auto-start Hello Integration onboarding
+        const connectSteps = createDefaultSteps();
+        connectSteps[0].status = 'passed';
+        connectSteps[0].validatedAt = now;
+        connectSteps[0].validationMethod = 'automatic';
+        connectSteps[0].details = { createdAt: now };
+        const connectDetected = detectPlatform(req.headers['user-agent']);
+        if (connectDetected) {
+            connectSteps[1].status = 'passed';
+            connectSteps[1].validatedAt = now;
+            connectSteps[1].validationMethod = 'automatic';
+            connectSteps[1].details = { platform: connectDetected.id, version: connectDetected.version };
+            await storage.updateAgent(gaii, {
+                platform: connectDetected.id,
+                platformVersion: connectDetected.version,
+                platformDetectedBy: connectDetected.detectedBy,
+            });
+        }
+        await storage.createOnboarding({
+            agentGaii: gaii,
+            status: 'in_progress',
+            startedAt: now,
+            steps: connectSteps,
+            detectedPlatform: connectDetected?.id,
+        });
+        emitChange('agent-onboarding');
+        res.set('Cache-Control', 'no-store');
+        res.set('Pragma', 'no-cache');
+        res.status(201).json(success(config.nodeId, {
+            agent: {
+                gaii,
+                display_name: display_name ?? finalName,
+                description,
+                scopes: requestedScopes,
+            },
+            private_key: keyPair.privateKey,
+            public_key: keyPair.publicKey,
+        }, [
+            {
+                description: 'Authenticate as this agent to get a JWT',
+                method: 'POST',
+                url: '/v1/auth/token',
+            },
+        ]));
+        emitChange('agents');
     });
     // POST /v1/agents — register a new agent (requires owner JWT, local session only)
     router.post('/v1/agents', requireAuth(), requireLocalSession(), requireRole('owner'), validateBody(AgentRegistrationSchema, config.nodeId), async (req, res) => {
@@ -416,6 +587,32 @@ export function agentsRouter(config, storage) {
             },
         ]));
         emitChange('agents');
+        // ── Auto-start Hello Integration onboarding (direct registration path) ──
+        const regOnboardingSteps = createDefaultSteps();
+        regOnboardingSteps[0].status = 'passed';
+        regOnboardingSteps[0].validatedAt = now;
+        regOnboardingSteps[0].validationMethod = 'automatic';
+        regOnboardingSteps[0].details = { createdAt: now };
+        const regDetected = detectPlatform(req.headers['user-agent']);
+        if (regDetected) {
+            regOnboardingSteps[1].status = 'passed';
+            regOnboardingSteps[1].validatedAt = now;
+            regOnboardingSteps[1].validationMethod = 'automatic';
+            regOnboardingSteps[1].details = { platform: regDetected.id, version: regDetected.version };
+            await storage.updateAgent(gaii, {
+                platform: regDetected.id,
+                platformVersion: regDetected.version,
+                platformDetectedBy: regDetected.detectedBy,
+            });
+        }
+        await storage.createOnboarding({
+            agentGaii: gaii,
+            status: 'in_progress',
+            startedAt: now,
+            steps: regOnboardingSteps,
+            detectedPlatform: regDetected?.id,
+        });
+        emitChange('agent-onboarding');
     });
     // GET /v1/agents/device-authorize/pending — list pending device auth requests for the logged-in owner
     router.get('/v1/agents/device-authorize/pending', requireAuth(), requireRole('owner'), async (req, res) => {
@@ -522,6 +719,8 @@ export function agentsRouter(config, storage) {
                 display_name: a.displayName,
                 description: a.description,
                 capabilities: a.capabilities,
+                technical_capabilities: a.technicalCapabilities,
+                domain_capabilities: a.domainCapabilities,
                 default_scopes: a.defaultScopes ?? ['*'],
                 trust_score: a.trustScore,
                 morsel_balance: a.morselBalance,