@octo-cyber/ai 0.5.5 → 0.5.6

package/dist/src/agent/computer-use-tools.js

@@ -0,0 +1,256 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SYSTEM_PROMPT_COMPUTER_USE = exports.IMAGE_RESULT_PREFIX = void 0;
+exports.createComputerUseTools = createComputerUseTools;
+// ============================================================
+// Sentinel prefix used to signal an image tool result.
+// OctoAgentClient.run() detects this and wraps it in an
+// Anthropic ImageBlockParam so Claude can see the screenshot.
+// ============================================================
+exports.IMAGE_RESULT_PREFIX = '[IMAGE:png]';
+exports.SYSTEM_PROMPT_COMPUTER_USE = `You are an AI agent that can control the desktop computer.
+You have access to these tools:
+- screenshot: take a screenshot to see the current state of the screen
+- left_click: click at a specific (x, y) coordinate
+- type: type text into the focused element
+- scroll: scroll up or down at a screen position
+- key: press a key or key combination (e.g. "enter", "ctrl+c")
+
+To complete a task:
+1. Start by taking a screenshot to understand the current state of the screen.
+2. Identify what needs to be done based on the screenshot.
+3. Use the appropriate tools to interact with the UI.
+4. Take follow-up screenshots to verify your actions had the intended effect.
+5. Repeat until the task is complete, then summarize what you did.
+
+Important:
+- Always verify actions with a screenshot after significant interactions.
+- Use the "key" tool for keyboard shortcuts (e.g. "enter" to confirm, "escape" to cancel).
+- Coordinate (0, 0) is the top-left corner of the screen.
+- Be precise with coordinates — click the center of buttons and input fields.`;
+// ============================================================
+// Tool factory
+// ============================================================
+/**
+ * Creates the computer-use tool set for agent loops.
+ *
+ * Screenshot results use the `[IMAGE:png]<base64>` sentinel so
+ * OctoAgentClient can pass them as Anthropic ImageBlockParam,
+ * enabling Claude to see and reason about the screen content.
+ *
+ * macOS: grant Accessibility + Screen Recording to Terminal/Node.
+ * Windows/Linux: no extra permissions required.
+ */
+function createComputerUseTools() {
+    return [
+        screenshotTool(),
+        leftClickTool(),
+        typeTool(),
+        scrollTool(),
+        keyTool(),
+    ];
+}
+// ── screenshot ────────────────────────────────────────────────
+function screenshotTool() {
+    return {
+        name: 'screenshot',
+        description: 'Take a screenshot of the current screen and return it as an image. ' +
+            'Use this to observe the current state of the desktop or any application.',
+        parameters: {
+            type: 'object',
+            properties: {},
+            required: [],
+        },
+        async execute(_args) {
+            try {
+                // eslint-disable-next-line @typescript-eslint/no-require-imports
+                const { Monitor } = require('node-screenshots');
+                const monitors = Monitor.all();
+                if (monitors.length === 0)
+                    return 'Error: no monitors found';
+                const monitor = monitors[0];
+                const image = await monitor.captureImage();
+                const pngBuffer = await image.toPng();
+                const base64 = pngBuffer.toString('base64');
+                return `${exports.IMAGE_RESULT_PREFIX}${base64}`;
+            }
+            catch (err) {
+                return `Error taking screenshot: ${err instanceof Error ? err.message : String(err)}`;
+            }
+        },
+    };
+}
+// ── left_click ────────────────────────────────────────────────
+function leftClickTool() {
+    return {
+        name: 'left_click',
+        description: 'Move the mouse cursor to screen coordinates (x, y) and perform a left click.',
+        parameters: {
+            type: 'object',
+            properties: {
+                x: { type: 'number', description: 'Horizontal pixel coordinate (from left edge of screen).' },
+                y: { type: 'number', description: 'Vertical pixel coordinate (from top edge of screen).' },
+            },
+            required: ['x', 'y'],
+        },
+        async execute(args) {
+            const { x, y } = args;
+            try {
+                // eslint-disable-next-line @typescript-eslint/no-require-imports, @typescript-eslint/no-explicit-any
+                const { mouse } = require('@nut-tree/nut-js');
+                await mouse.setPosition({ x, y });
+                await mouse.leftClick();
+                return `Clicked at (${x}, ${y})`;
+            }
+            catch (err) {
+                return `Error clicking at (${x}, ${y}): ${err instanceof Error ? err.message : String(err)}`;
+            }
+        },
+    };
+}
+// ── type ──────────────────────────────────────────────────────
+function typeTool() {
+    return {
+        name: 'type',
+        description: 'Type text into the currently focused input field or application. ' +
+            'Simulates keyboard keystrokes character by character.',
+        parameters: {
+            type: 'object',
+            properties: {
+                text: { type: 'string', description: 'Text to type. Supports printable ASCII characters.' },
+            },
+            required: ['text'],
+        },
+        async execute(args) {
+            const { text } = args;
+            try {
+                // eslint-disable-next-line @typescript-eslint/no-require-imports, @typescript-eslint/no-explicit-any
+                const { keyboard } = require('@nut-tree/nut-js');
+                await keyboard.type(text);
+                return `Typed: ${text.slice(0, 50)}${text.length > 50 ? '...' : ''}`;
+            }
+            catch (err) {
+                return `Error typing text: ${err instanceof Error ? err.message : String(err)}`;
+            }
+        },
+    };
+}
+// ── scroll ────────────────────────────────────────────────────
+function scrollTool() {
+    return {
+        name: 'scroll',
+        description: 'Scroll the mouse wheel at the given screen position. ' +
+            'Positive dy scrolls up; negative dy scrolls down.',
+        parameters: {
+            type: 'object',
+            properties: {
+                x: { type: 'number', description: 'Horizontal coordinate to scroll at.' },
+                y: { type: 'number', description: 'Vertical coordinate to scroll at.' },
+                dy: { type: 'number', description: 'Scroll amount: positive = up, negative = down (e.g. 3 or -3).' },
+            },
+            required: ['x', 'y', 'dy'],
+        },
+        async execute(args) {
+            const { x, y, dy } = args;
+            try {
+                // eslint-disable-next-line @typescript-eslint/no-require-imports, @typescript-eslint/no-explicit-any
+                const { mouse } = require('@nut-tree/nut-js');
+                await mouse.setPosition({ x, y });
+                const amount = Math.abs(Math.round(dy));
+                if (dy > 0) {
+                    await mouse.scrollUp(amount);
+                }
+                else {
+                    await mouse.scrollDown(amount);
+                }
+                return `Scrolled ${dy > 0 ? 'up' : 'down'} ${amount} at (${x}, ${y})`;
+            }
+            catch (err) {
+                return `Error scrolling: ${err instanceof Error ? err.message : String(err)}`;
+            }
+        },
+    };
+}
+// ── key ───────────────────────────────────────────────────────
+function keyTool() {
+    return {
+        name: 'key',
+        description: 'Press a keyboard key or key combination. ' +
+            'Examples: "enter", "escape", "ctrl+c", "cmd+tab", "ctrl+shift+t".',
+        parameters: {
+            type: 'object',
+            properties: {
+                keys: {
+                    type: 'string',
+                    description: 'Key or key combination to press. ' +
+                        'Single key: "enter", "escape", "tab", "space", "backspace". ' +
+                        'Combination: "ctrl+c", "cmd+v", "alt+f4", "ctrl+shift+t".',
+                },
+            },
+            required: ['keys'],
+        },
+        async execute(args) {
+            const { keys } = args;
+            try {
+                // eslint-disable-next-line @typescript-eslint/no-require-imports, @typescript-eslint/no-explicit-any
+                const { keyboard, Key } = require('@nut-tree/nut-js');
+                const resolved = parseKeys(keys, Key);
+                if (resolved.length === 0)
+                    return `Unknown key: ${keys}`;
+                await keyboard.pressKey(...resolved);
+                await keyboard.releaseKey(...resolved);
+                return `Pressed: ${keys}`;
+            }
+            catch (err) {
+                return `Error pressing key "${keys}": ${err instanceof Error ? err.message : String(err)}`;
+            }
+        },
+    };
+}
+function parseKeys(input, Key) {
+    const parts = input.toLowerCase().split('+').map((s) => s.trim());
+    return parts.map((p) => resolveKey(p, Key)).filter((k) => k !== undefined);
+}
+function resolveKey(name, Key) {
+    const map = {
+        enter: Key.Enter,
+        return: Key.Return,
+        escape: Key.Escape,
+        esc: Key.Escape,
+        tab: Key.Tab,
+        space: Key.Space,
+        backspace: Key.Backspace,
+        delete: Key.Delete,
+        del: Key.Delete,
+        home: Key.Home,
+        end: Key.End,
+        pageup: Key.PageUp,
+        pagedown: Key.PageDown,
+        up: Key.Up,
+        down: Key.Down,
+        left: Key.Left,
+        right: Key.Right,
+        ctrl: Key.LeftControl,
+        control: Key.LeftControl,
+        shift: Key.LeftShift,
+        alt: Key.LeftAlt,
+        option: Key.LeftAlt,
+        cmd: Key.LeftCmd,
+        command: Key.LeftCmd,
+        win: Key.LeftWin,
+        super: Key.LeftWin,
+        a: Key.A, b: Key.B, c: Key.C, d: Key.D, e: Key.E, f: Key.F,
+        g: Key.G, h: Key.H, i: Key.I, j: Key.J, k: Key.K, l: Key.L,
+        m: Key.M, n: Key.N, o: Key.O, p: Key.P, q: Key.Q, r: Key.R,
+        s: Key.S, t: Key.T, u: Key.U, v: Key.V, w: Key.W, x: Key.X,
+        y: Key.Y, z: Key.Z,
+        '0': Key.Num0, '1': Key.Num1, '2': Key.Num2, '3': Key.Num3,
+        '4': Key.Num4, '5': Key.Num5, '6': Key.Num6, '7': Key.Num7,
+        '8': Key.Num8, '9': Key.Num9,
+        f1: Key.F1, f2: Key.F2, f3: Key.F3, f4: Key.F4, f5: Key.F5,
+        f6: Key.F6, f7: Key.F7, f8: Key.F8, f9: Key.F9, f10: Key.F10,
+        f11: Key.F11, f12: Key.F12,
+    };
+    return map[name];
+}
+//# sourceMappingURL=computer-use-tools.js.map

package/dist/src/agent/computer-use-tools.js.map

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

package/dist/src/agent/external-agent.controller.d.ts

@@ -0,0 +1,41 @@
+import type { Request, Response } from '@octo-cyber/core';
+/**
+ * ExternalAgentController — HTTP API for external agent self-management.
+ *
+ * Endpoints:
+ *   POST /api/v1/agents/external/register    — Register or update an external agent
+ *   POST /api/v1/agents/external/heartbeat   — Send a heartbeat to stay online
+ *   POST /api/v1/agents/external/unregister  — Mark the agent as offline
+ *   GET  /api/v1/agents/external             — List all external agents
+ */
+export declare class ExternalAgentController {
+    private get service();
+    /**
+     * Register or update an external agent (upsert by agentId).
+     *
+     * Body:
+     *   agentId      {string}    — Caller-chosen unique identifier
+     *   name         {string}    — Human-readable agent name
+     *   description  {string?}   — Optional description
+     *   endpoint     {string}    — HTTP URL that accepts POST task payloads
+     *   capabilities {string[]?} — Optional list of capability tags
+     */
+    registerAgent(req: Request, res: Response): Promise<void>;
+    /**
+     * Send a heartbeat for the given agentId.
+     *
+     * Body:
+     *   agentId {string}
+     */
+    heartbeat(req: Request, res: Response): Promise<void>;
+    /**
+     * Unregister (mark offline) the given external agent.
+     *
+     * Body:
+     *   agentId {string}
+     */
+    unregisterAgent(req: Request, res: Response): Promise<void>;
+    /** List all external agents (newest first). */
+    listAgents(_req: Request, res: Response): Promise<void>;
+}
+//# sourceMappingURL=external-agent.controller.d.ts.map

package/dist/src/agent/external-agent.controller.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"external-agent.controller.d.ts","sourceRoot":"","sources":["../../../src/agent/external-agent.controller.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAI1D;;;;;;;;GAQG;AACH,qBACa,uBAAuB;IAClC,OAAO,KAAK,OAAO,GAElB;IAED;;;;;;;;;OASG;IAEG,aAAa,CAAC,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC;IAiC/D;;;;;OAKG;IAEG,SAAS,CAAC,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC;IAe3D;;;;;OAKG;IAEG,eAAe,CAAC,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC;IAejE,+CAA+C;IAEzC,UAAU,CAAC,IAAI,EAAE,OAAO,EAAE,GAAG,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC;CAI9D"}

package/dist/src/agent/external-agent.controller.js

@@ -0,0 +1,129 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ExternalAgentController = void 0;
+const core_1 = require("@octo-cyber/core");
+const external_agent_service_js_1 = require("./external-agent.service.js");
+/**
+ * ExternalAgentController — HTTP API for external agent self-management.
+ *
+ * Endpoints:
+ *   POST /api/v1/agents/external/register    — Register or update an external agent
+ *   POST /api/v1/agents/external/heartbeat   — Send a heartbeat to stay online
+ *   POST /api/v1/agents/external/unregister  — Mark the agent as offline
+ *   GET  /api/v1/agents/external             — List all external agents
+ */
+let ExternalAgentController = class ExternalAgentController {
+    get service() {
+        return core_1.Container.get(external_agent_service_js_1.ExternalAgentService);
+    }
+    /**
+     * Register or update an external agent (upsert by agentId).
+     *
+     * Body:
+     *   agentId      {string}    — Caller-chosen unique identifier
+     *   name         {string}    — Human-readable agent name
+     *   description  {string?}   — Optional description
+     *   endpoint     {string}    — HTTP URL that accepts POST task payloads
+     *   capabilities {string[]?} — Optional list of capability tags
+     */
+    async registerAgent(req, res) {
+        const { agentId, name, description, endpoint, capabilities } = req.body;
+        if (!agentId || typeof agentId !== 'string' || agentId.trim().length === 0) {
+            throw core_1.AppError.badRequest('Missing or invalid agentId');
+        }
+        if (!name || typeof name !== 'string' || name.trim().length === 0) {
+            throw core_1.AppError.badRequest('Missing or invalid name');
+        }
+        if (!endpoint || typeof endpoint !== 'string' || endpoint.trim().length === 0) {
+            throw core_1.AppError.badRequest('Missing or invalid endpoint');
+        }
+        const dto = {
+            agentId: agentId.trim(),
+            name: name.trim(),
+            description: typeof description === 'string' ? description.trim() : undefined,
+            endpoint: endpoint.trim(),
+            capabilities: Array.isArray(capabilities)
+                ? capabilities.filter((c) => typeof c === 'string')
+                : undefined,
+        };
+        const agent = await this.service.register(dto);
+        res.json(core_1.ApiResponse.ok(this.service.toDto(agent)));
+    }
+    /**
+     * Send a heartbeat for the given agentId.
+     *
+     * Body:
+     *   agentId {string}
+     */
+    async heartbeat(req, res) {
+        const { agentId } = req.body;
+        if (!agentId || typeof agentId !== 'string' || agentId.trim().length === 0) {
+            throw core_1.AppError.badRequest('Missing or invalid agentId');
+        }
+        const found = await this.service.heartbeat(agentId.trim());
+        if (!found) {
+            throw core_1.AppError.notFound(`External agent not found: ${agentId}`);
+        }
+        res.json(core_1.ApiResponse.ok({ ok: true }));
+    }
+    /**
+     * Unregister (mark offline) the given external agent.
+     *
+     * Body:
+     *   agentId {string}
+     */
+    async unregisterAgent(req, res) {
+        const { agentId } = req.body;
+        if (!agentId || typeof agentId !== 'string' || agentId.trim().length === 0) {
+            throw core_1.AppError.badRequest('Missing or invalid agentId');
+        }
+        const found = await this.service.unregister(agentId.trim());
+        if (!found) {
+            throw core_1.AppError.notFound(`External agent not found: ${agentId}`);
+        }
+        res.json(core_1.ApiResponse.ok({ unregistered: true }));
+    }
+    /** List all external agents (newest first). */
+    async listAgents(_req, res) {
+        const agents = await this.service.list();
+        res.json(core_1.ApiResponse.ok(agents.map((a) => this.service.toDto(a))));
+    }
+};
+exports.ExternalAgentController = ExternalAgentController;
+__decorate([
+    (0, core_1.Post)('/register'),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [Object, Object]),
+    __metadata("design:returntype", Promise)
+], ExternalAgentController.prototype, "registerAgent", null);
+__decorate([
+    (0, core_1.Post)('/heartbeat'),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [Object, Object]),
+    __metadata("design:returntype", Promise)
+], ExternalAgentController.prototype, "heartbeat", null);
+__decorate([
+    (0, core_1.Post)('/unregister'),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [Object, Object]),
+    __metadata("design:returntype", Promise)
+], ExternalAgentController.prototype, "unregisterAgent", null);
+__decorate([
+    (0, core_1.Get)('/'),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [Object, Object]),
+    __metadata("design:returntype", Promise)
+], ExternalAgentController.prototype, "listAgents", null);
+exports.ExternalAgentController = ExternalAgentController = __decorate([
+    (0, core_1.Controller)('/api/v1/agents/external')
+], ExternalAgentController);
+//# sourceMappingURL=external-agent.controller.js.map

package/dist/src/agent/external-agent.controller.js.map

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

package/dist/src/agent/external-agent.entity.d.ts

@@ -0,0 +1,22 @@
+/**
+ * ExternalAgent — persists remote agents that have registered their capabilities
+ * with Octo via the external agent registration API.
+ *
+ * External agents run on remote machines and expose an HTTP endpoint.
+ * Octo routes tasks to them by POSTing to that endpoint.
+ */
+export declare class ExternalAgent {
+    id: string;
+    name: string;
+    /** Caller-chosen unique identifier for this agent. Used for heartbeat and unregister. */
+    agentId: string;
+    description: string | null;
+    /** HTTP endpoint that accepts POST requests with task payloads. */
+    endpoint: string;
+    status: 'online' | 'offline';
+    lastHeartbeatAt: Date | null;
+    /** JSON-serialised array of capability strings (e.g. ["code-review", "summarise"]). */
+    capabilities: string | null;
+    createdAt: Date;
+}
+//# sourceMappingURL=external-agent.entity.d.ts.map

package/dist/src/agent/external-agent.entity.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"external-agent.entity.d.ts","sourceRoot":"","sources":["../../../src/agent/external-agent.entity.ts"],"names":[],"mappings":"AAOA;;;;;;GAMG;AACH,qBACa,aAAa;IAExB,EAAE,EAAG,MAAM,CAAC;IAGZ,IAAI,EAAG,MAAM,CAAC;IAEd,yFAAyF;IAEzF,OAAO,EAAG,MAAM,CAAC;IAGjB,WAAW,EAAG,MAAM,GAAG,IAAI,CAAC;IAE5B,mEAAmE;IAEnE,QAAQ,EAAG,MAAM,CAAC;IAGlB,MAAM,EAAG,QAAQ,GAAG,SAAS,CAAC;IAG9B,eAAe,EAAG,IAAI,GAAG,IAAI,CAAC;IAE9B,uFAAuF;IAEvF,YAAY,EAAG,MAAM,GAAG,IAAI,CAAC;IAG7B,SAAS,EAAG,IAAI,CAAC;CAClB"}

package/dist/src/agent/external-agent.entity.js

@@ -0,0 +1,75 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ExternalAgent = void 0;
+const core_1 = require("@octo-cyber/core");
+/**
+ * ExternalAgent — persists remote agents that have registered their capabilities
+ * with Octo via the external agent registration API.
+ *
+ * External agents run on remote machines and expose an HTTP endpoint.
+ * Octo routes tasks to them by POSTing to that endpoint.
+ */
+let ExternalAgent = class ExternalAgent {
+    id;
+    name;
+    /** Caller-chosen unique identifier for this agent. Used for heartbeat and unregister. */
+    agentId;
+    description;
+    /** HTTP endpoint that accepts POST requests with task payloads. */
+    endpoint;
+    status;
+    lastHeartbeatAt;
+    /** JSON-serialised array of capability strings (e.g. ["code-review", "summarise"]). */
+    capabilities;
+    createdAt;
+};
+exports.ExternalAgent = ExternalAgent;
+__decorate([
+    (0, core_1.PrimaryGeneratedColumn)('uuid'),
+    __metadata("design:type", String)
+], ExternalAgent.prototype, "id", void 0);
+__decorate([
+    (0, core_1.Column)({ type: 'varchar', length: 128 }),
+    __metadata("design:type", String)
+], ExternalAgent.prototype, "name", void 0);
+__decorate([
+    (0, core_1.Column)({ type: 'varchar', length: 64, unique: true }),
+    __metadata("design:type", String)
+], ExternalAgent.prototype, "agentId", void 0);
+__decorate([
+    (0, core_1.Column)({ type: 'text', nullable: true }),
+    __metadata("design:type", Object)
+], ExternalAgent.prototype, "description", void 0);
+__decorate([
+    (0, core_1.Column)({ type: 'varchar', length: 512 }),
+    __metadata("design:type", String)
+], ExternalAgent.prototype, "endpoint", void 0);
+__decorate([
+    (0, core_1.Column)({ type: 'varchar', length: 32, default: 'online' }),
+    __metadata("design:type", String)
+], ExternalAgent.prototype, "status", void 0);
+__decorate([
+    (0, core_1.Column)({ type: 'datetime', nullable: true, name: 'last_heartbeat_at' }),
+    __metadata("design:type", Object)
+], ExternalAgent.prototype, "lastHeartbeatAt", void 0);
+__decorate([
+    (0, core_1.Column)({ type: 'text', nullable: true }),
+    __metadata("design:type", Object)
+], ExternalAgent.prototype, "capabilities", void 0);
+__decorate([
+    (0, core_1.CreateDateColumn)({ name: 'created_at' }),
+    __metadata("design:type", Date)
+], ExternalAgent.prototype, "createdAt", void 0);
+exports.ExternalAgent = ExternalAgent = __decorate([
+    (0, core_1.Entity)('external_agent')
+], ExternalAgent);
+//# sourceMappingURL=external-agent.entity.js.map

package/dist/src/agent/external-agent.entity.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"external-agent.entity.js","sourceRoot":"","sources":["../../../src/agent/external-agent.entity.ts"],"names":[],"mappings":";;;;;;;;;;;;AAAA,2CAK0B;AAE1B;;;;;;GAMG;AAEI,IAAM,aAAa,GAAnB,MAAM,aAAa;IAExB,EAAE,CAAU;IAGZ,IAAI,CAAU;IAEd,yFAAyF;IAEzF,OAAO,CAAU;IAGjB,WAAW,CAAiB;IAE5B,mEAAmE;IAEnE,QAAQ,CAAU;IAGlB,MAAM,CAAwB;IAG9B,eAAe,CAAe;IAE9B,uFAAuF;IAEvF,YAAY,CAAiB;IAG7B,SAAS,CAAQ;CAClB,CAAA;AA9BY,sCAAa;AAExB;IADC,IAAA,6BAAsB,EAAC,MAAM,CAAC;;yCACnB;AAGZ;IADC,IAAA,aAAM,EAAC,EAAE,IAAI,EAAE,SAAS,EAAE,MAAM,EAAE,GAAG,EAAE,CAAC;;2CAC3B;AAId;IADC,IAAA,aAAM,EAAC,EAAE,IAAI,EAAE,SAAS,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC;;8CACrC;AAGjB;IADC,IAAA,aAAM,EAAC,EAAE,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC;;kDACb;AAI5B;IADC,IAAA,aAAM,EAAC,EAAE,IAAI,EAAE,SAAS,EAAE,MAAM,EAAE,GAAG,EAAE,CAAC;;+CACvB;AAGlB;IADC,IAAA,aAAM,EAAC,EAAE,IAAI,EAAE,SAAS,EAAE,MAAM,EAAE,EAAE,EAAE,OAAO,EAAE,QAAQ,EAAE,CAAC;;6CAC7B;AAG9B;IADC,IAAA,aAAM,EAAC,EAAE,IAAI,EAAE,UAAU,EAAE,QAAQ,EAAE,IAAI,EAAE,IAAI,EAAE,mBAAmB,EAAE,CAAC;;sDAC1C;AAI9B;IADC,IAAA,aAAM,EAAC,EAAE,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC;;mDACZ;AAG7B;IADC,IAAA,uBAAgB,EAAC,EAAE,IAAI,EAAE,YAAY,EAAE,CAAC;8BAC7B,IAAI;gDAAC;wBA7BN,aAAa;IADzB,IAAA,aAAM,EAAC,gBAAgB,CAAC;GACZ,aAAa,CA8BzB"}

package/dist/src/agent/external-agent.service.d.ts

@@ -0,0 +1,60 @@
+import type { Repository } from '@octo-cyber/core';
+import { ExternalAgent } from './external-agent.entity.js';
+export interface RegisterExternalAgentDto {
+    agentId: string;
+    name: string;
+    description?: string;
+    endpoint: string;
+    capabilities?: string[];
+}
+export interface ExternalAgentDto {
+    id: string;
+    agentId: string;
+    name: string;
+    description: string | null;
+    endpoint: string;
+    status: 'online' | 'offline';
+    lastHeartbeatAt: string | null;
+    capabilities: string[];
+    createdAt: string;
+}
+/**
+ * ExternalAgentService — manages external (remote) agent registrations.
+ *
+ * External agents self-register, periodically heartbeat, and self-unregister.
+ * On register the agent is also synced into the in-memory AgentRegistryService
+ * so it appears in the unified capability list.
+ */
+export declare class ExternalAgentService {
+    private readonly logger;
+    private repo;
+    setRepository(repo: Repository<ExternalAgent>): void;
+    private getRepo;
+    /**
+     * Register or update an external agent (upsert by agentId).
+     * Sets status='online' and updates lastHeartbeatAt.
+     */
+    register(dto: RegisterExternalAgentDto): Promise<ExternalAgent>;
+    /**
+     * Update lastHeartbeatAt and set status='online'.
+     * Returns false if the agent is not found.
+     */
+    heartbeat(agentId: string): Promise<boolean>;
+    /**
+     * Set the agent's status to 'offline'.
+     * Returns false if the agent is not found.
+     */
+    unregister(agentId: string): Promise<boolean>;
+    /** List all external agents, newest first. */
+    list(): Promise<ExternalAgent[]>;
+    getById(id: string): Promise<ExternalAgent | null>;
+    getByAgentId(agentId: string): Promise<ExternalAgent | null>;
+    /**
+     * Mark agents whose lastHeartbeatAt is older than maxAgeMs as 'offline'.
+     * Returns the number of agents updated.
+     */
+    markStaleOffline(maxAgeMs?: number): Promise<number>;
+    toDto(agent: ExternalAgent): ExternalAgentDto;
+    private syncToRegistry;
+}
+//# sourceMappingURL=external-agent.service.d.ts.map

package/dist/src/agent/external-agent.service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"external-agent.service.d.ts","sourceRoot":"","sources":["../../../src/agent/external-agent.service.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AACnD,OAAO,EAAE,aAAa,EAAE,MAAM,4BAA4B,CAAC;AAM3D,MAAM,WAAW,wBAAwB;IACvC,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;CACzB;AAED,MAAM,WAAW,gBAAgB;IAC/B,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,QAAQ,GAAG,SAAS,CAAC;IAC7B,eAAe,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;;;;;GAMG;AACH,qBACa,oBAAoB;IAC/B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA8D;IACrF,OAAO,CAAC,IAAI,CAA0C;IAEtD,aAAa,CAAC,IAAI,EAAE,UAAU,CAAC,aAAa,CAAC,GAAG,IAAI;IAIpD,OAAO,CAAC,OAAO;IAKf;;;OAGG;IACG,QAAQ,CAAC,GAAG,EAAE,wBAAwB,GAAG,OAAO,CAAC,aAAa,CAAC;IA+BrE;;;OAGG;IACG,SAAS,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IASlD;;;OAGG;IACG,UAAU,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAUnD,8CAA8C;IACxC,IAAI,IAAI,OAAO,CAAC,aAAa,EAAE,CAAC;IAIhC,OAAO,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,GAAG,IAAI,CAAC;IAIlD,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,GAAG,IAAI,CAAC;IAIlE;;;OAGG;IACG,gBAAgB,CAAC,QAAQ,SAA+B,GAAG,OAAO,CAAC,MAAM,CAAC;IAkBhF,KAAK,CAAC,KAAK,EAAE,aAAa,GAAG,gBAAgB;IAgB7C,OAAO,CAAC,cAAc;CAUvB"}