@octo-cyber/ai 0.5.5 → 0.5.7

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"}

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

@@ -0,0 +1,143 @@
+"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;
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ExternalAgentService = void 0;
+const core_1 = require("@octo-cyber/core");
+const agent_registry_service_js_1 = require("./agent-registry.service.js");
+const DEFAULT_HEARTBEAT_MAX_AGE_MS = 30_000;
+/**
+ * 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.
+ */
+let ExternalAgentService = class ExternalAgentService {
+    logger = core_1.Container.get(core_1.LoggerService).child('ExternalAgentService');
+    repo = null;
+    setRepository(repo) {
+        this.repo = repo;
+    }
+    getRepo() {
+        if (!this.repo)
+            throw new Error('ExternalAgentService: repository not initialized');
+        return this.repo;
+    }
+    /**
+     * Register or update an external agent (upsert by agentId).
+     * Sets status='online' and updates lastHeartbeatAt.
+     */
+    async register(dto) {
+        const repo = this.getRepo();
+        const now = new Date();
+        let agent = await repo.findOne({ where: { agentId: dto.agentId } });
+        if (agent) {
+            agent.name = dto.name;
+            agent.description = dto.description ?? null;
+            agent.endpoint = dto.endpoint;
+            agent.status = 'online';
+            agent.lastHeartbeatAt = now;
+            agent.capabilities = dto.capabilities ? JSON.stringify(dto.capabilities) : null;
+        }
+        else {
+            agent = repo.create({
+                agentId: dto.agentId,
+                name: dto.name,
+                description: dto.description ?? null,
+                endpoint: dto.endpoint,
+                status: 'online',
+                lastHeartbeatAt: now,
+                capabilities: dto.capabilities ? JSON.stringify(dto.capabilities) : null,
+            });
+        }
+        const saved = await repo.save(agent);
+        this.syncToRegistry(saved);
+        this.logger.info(`[ExternalAgentService] registered agent: ${dto.agentId}`);
+        return saved;
+    }
+    /**
+     * Update lastHeartbeatAt and set status='online'.
+     * Returns false if the agent is not found.
+     */
+    async heartbeat(agentId) {
+        const repo = this.getRepo();
+        const agent = await repo.findOne({ where: { agentId } });
+        if (!agent)
+            return false;
+        await repo.update(agent.id, { status: 'online', lastHeartbeatAt: new Date() });
+        return true;
+    }
+    /**
+     * Set the agent's status to 'offline'.
+     * Returns false if the agent is not found.
+     */
+    async unregister(agentId) {
+        const repo = this.getRepo();
+        const agent = await repo.findOne({ where: { agentId } });
+        if (!agent)
+            return false;
+        await repo.update(agent.id, { status: 'offline' });
+        this.logger.info(`[ExternalAgentService] unregistered agent: ${agentId}`);
+        return true;
+    }
+    /** List all external agents, newest first. */
+    async list() {
+        return this.getRepo().find({ order: { createdAt: 'DESC' } });
+    }
+    async getById(id) {
+        return this.getRepo().findOne({ where: { id } });
+    }
+    async getByAgentId(agentId) {
+        return this.getRepo().findOne({ where: { agentId } });
+    }
+    /**
+     * Mark agents whose lastHeartbeatAt is older than maxAgeMs as 'offline'.
+     * Returns the number of agents updated.
+     */
+    async markStaleOffline(maxAgeMs = DEFAULT_HEARTBEAT_MAX_AGE_MS) {
+        const repo = this.getRepo();
+        const cutoff = new Date(Date.now() - maxAgeMs);
+        const stale = await repo.find({ where: { status: 'online' } });
+        const toUpdate = stale.filter((a) => a.lastHeartbeatAt !== null && a.lastHeartbeatAt < cutoff);
+        if (toUpdate.length === 0)
+            return 0;
+        const ids = toUpdate.map((a) => a.id);
+        await Promise.all(ids.map((id) => repo.update(id, { status: 'offline' })));
+        this.logger.info(`[ExternalAgentService] marked ${ids.length} stale agent(s) offline`);
+        return ids.length;
+    }
+    toDto(agent) {
+        return {
+            id: agent.id,
+            agentId: agent.agentId,
+            name: agent.name,
+            description: agent.description,
+            endpoint: agent.endpoint,
+            status: agent.status,
+            lastHeartbeatAt: agent.lastHeartbeatAt?.toISOString() ?? null,
+            capabilities: agent.capabilities ? JSON.parse(agent.capabilities) : [],
+            createdAt: agent.createdAt.toISOString(),
+        };
+    }
+    // ─── Private helpers ──────────────────────────────────────────────────
+    syncToRegistry(agent) {
+        const registry = core_1.Container.get(agent_registry_service_js_1.AgentRegistryService);
+        registry.register({
+            type: `remote:${agent.agentId}`,
+            name: agent.name,
+            description: agent.description ?? '',
+            isAvailable: agent.status === 'online',
+            metadata: { agentId: agent.agentId, endpoint: agent.endpoint },
+        });
+    }
+};
+exports.ExternalAgentService = ExternalAgentService;
+exports.ExternalAgentService = ExternalAgentService = __decorate([
+    (0, core_1.Service)()
+], ExternalAgentService);
+//# sourceMappingURL=external-agent.service.js.map

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

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

package/dist/src/ai.module.d.ts

@@ -0,0 +1,22 @@
+import type { IModule, IModuleContext, Express } from '@octo-cyber/core';
+import { OctoSkill } from './skill/entities/octo-skill.entity.js';
+import './skill/services/skill-generator.service.js';
+import { AgentRun } from './agent/agent-run.entity.js';
+import { AgentSession } from './agent/agent-session.entity.js';
+import { AgentApproval } from './agent/agent-approval.entity.js';
+import { ExternalAgent } from './agent/external-agent.entity.js';
+import { OrchestratorPlan } from './orchestrator/orchestrator-plan.entity.js';
+import { WorkflowFeedback } from './orchestrator/workflow-feedback.entity.js';
+/**
+ * AI module — CLI tool management (Claude/Gemini/Codex) + Skill system.
+ */
+export declare class AiModule implements IModule {
+    readonly name = "ai";
+    readonly version = "0.5.5";
+    readonly entities: (typeof OctoSkill | typeof AgentRun | typeof AgentSession | typeof AgentApproval | typeof ExternalAgent | typeof OrchestratorPlan | typeof WorkflowFeedback)[];
+    initialize(ctx: IModuleContext): Promise<void>;
+    private registerAiQueryHandler;
+    registerRoutes(app: Express, _ctx: IModuleContext): void;
+    destroy(): Promise<void>;
+}
+//# sourceMappingURL=ai.module.d.ts.map

package/dist/src/ai.module.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ai.module.d.ts","sourceRoot":"","sources":["../../src/ai.module.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,OAAO,EAAE,cAAc,EAAE,OAAO,EAAE,MAAM,kBAAkB,CAAC;AAgBzE,OAAO,EAAE,SAAS,EAAE,MAAM,uCAAuC,CAAC;AAOlE,OAAO,6CAA6C,CAAC;AAGrD,OAAO,EAAE,QAAQ,EAAE,MAAM,6BAA6B,CAAC;AAUvD,OAAO,EAAE,YAAY,EAAE,MAAM,iCAAiC,CAAC;AAG/D,OAAO,EAAE,aAAa,EAAE,MAAM,kCAAkC,CAAC;AAKjE,OAAO,EAAE,aAAa,EAAE,MAAM,kCAAkC,CAAC;AAKjE,OAAO,EAAE,gBAAgB,EAAE,MAAM,4CAA4C,CAAC;AAC9E,OAAO,EAAE,gBAAgB,EAAE,MAAM,4CAA4C,CAAC;AAK9E;;GAEG;AACH,qBAAa,QAAS,YAAW,OAAO;IACtC,QAAQ,CAAC,IAAI,QAAQ;IACrB,QAAQ,CAAC,OAAO,WAAW;IAC3B,QAAQ,CAAC,QAAQ,iKAQf;IAEI,UAAU,CAAC,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC;IA0DpD,OAAO,CAAC,sBAAsB;IA+B9B,cAAc,CAAC,GAAG,EAAE,OAAO,EAAE,IAAI,EAAE,cAAc,GAAG,IAAI;IAqClD,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;CAG/B"}