opc-agent 3.0.0 → 4.0.0

package/dist/core/audio.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Audio Processor - v1.0.0
+ * Audio transcription/synthesis wrappers with format detection, duration, split.
+ */
+export type AudioFormat = 'wav' | 'mp3' | 'ogg' | 'flac' | 'webm' | 'aac' | 'unknown';
+export interface TranscribeOptions {
+    language?: string;
+    model?: string;
+    provider?: string;
+}
+export interface SynthesizeOptions {
+    voice?: string;
+    speed?: number;
+    format?: AudioFormat;
+    provider?: string;
+}
+export interface TranscribeResult {
+    text: string;
+    language?: string;
+    duration?: number;
+    segments?: {
+        start: number;
+        end: number;
+        text: string;
+    }[];
+}
+export interface SynthesizeResult {
+    audio: Buffer;
+    format: AudioFormat;
+    duration?: number;
+}
+export type TranscribeFunction = (audio: Buffer, options?: TranscribeOptions) => Promise<TranscribeResult>;
+export type SynthesizeFunction = (text: string, options?: SynthesizeOptions) => Promise<SynthesizeResult>;
+export declare class AudioProcessor {
+    private transcribeFn?;
+    private synthesizeFn?;
+    constructor(options?: {
+        transcribe?: TranscribeFunction;
+        synthesize?: SynthesizeFunction;
+    });
+    /** Detect audio format from buffer header */
+    static detectFormat(audio: Buffer): AudioFormat;
+    /** Estimate duration in seconds for WAV files (for others returns undefined) */
+    static estimateDuration(audio: Buffer): number | undefined;
+    /** Split audio buffer into chunks of roughly `chunkBytes` size */
+    static split(audio: Buffer, chunkBytes: number): Buffer[];
+    transcribe(audio: Buffer, options?: TranscribeOptions): Promise<TranscribeResult>;
+    synthesize(text: string, options?: SynthesizeOptions): Promise<SynthesizeResult>;
+}
+//# sourceMappingURL=audio.d.ts.map

package/dist/core/audio.js

@@ -0,0 +1,68 @@
+"use strict";
+/**
+ * Audio Processor - v1.0.0
+ * Audio transcription/synthesis wrappers with format detection, duration, split.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AudioProcessor = void 0;
+const FORMAT_SIGNATURES = [
+    [Buffer.from('RIFF'), 'wav'],
+    [Buffer.from([0xff, 0xfb]), 'mp3'],
+    [Buffer.from([0xff, 0xf3]), 'mp3'],
+    [Buffer.from([0xff, 0xf2]), 'mp3'],
+    [Buffer.from([0x49, 0x44, 0x33]), 'mp3'], // ID3
+    [Buffer.from('OggS'), 'ogg'],
+    [Buffer.from('fLaC'), 'flac'],
+    [Buffer.from([0x1a, 0x45, 0xdf, 0xa3]), 'webm'],
+];
+class AudioProcessor {
+    transcribeFn;
+    synthesizeFn;
+    constructor(options) {
+        this.transcribeFn = options?.transcribe;
+        this.synthesizeFn = options?.synthesize;
+    }
+    /** Detect audio format from buffer header */
+    static detectFormat(audio) {
+        for (const [sig, fmt] of FORMAT_SIGNATURES) {
+            if (audio.length >= sig.length && audio.subarray(0, sig.length).equals(sig))
+                return fmt;
+        }
+        return 'unknown';
+    }
+    /** Estimate duration in seconds for WAV files (for others returns undefined) */
+    static estimateDuration(audio) {
+        const fmt = AudioProcessor.detectFormat(audio);
+        if (fmt === 'wav' && audio.length >= 44) {
+            const sampleRate = audio.readUInt32LE(24);
+            const byteRate = audio.readUInt32LE(28);
+            if (byteRate > 0) {
+                const dataSize = audio.length - 44;
+                return dataSize / byteRate;
+            }
+        }
+        return undefined;
+    }
+    /** Split audio buffer into chunks of roughly `chunkBytes` size */
+    static split(audio, chunkBytes) {
+        if (chunkBytes <= 0)
+            throw new Error('chunkBytes must be positive');
+        const chunks = [];
+        for (let i = 0; i < audio.length; i += chunkBytes) {
+            chunks.push(audio.subarray(i, Math.min(i + chunkBytes, audio.length)));
+        }
+        return chunks;
+    }
+    async transcribe(audio, options) {
+        if (!this.transcribeFn)
+            throw new Error('No transcribe provider configured');
+        return this.transcribeFn(audio, options);
+    }
+    async synthesize(text, options) {
+        if (!this.synthesizeFn)
+            throw new Error('No synthesize provider configured');
+        return this.synthesizeFn(text, options);
+    }
+}
+exports.AudioProcessor = AudioProcessor;
+//# sourceMappingURL=audio.js.map

package/dist/core/context-discovery.d.ts

@@ -0,0 +1,16 @@
+export interface ContextFile {
+    path: string;
+    type: 'agents' | 'soul' | 'user' | 'memory' | 'tools' | 'identity' | 'heartbeat' | 'bootstrap' | 'custom';
+    content: string;
+}
+export declare class ContextDiscovery {
+    static STANDARD_FILES: string[];
+    private customFiles;
+    private watchers;
+    discover(workDir?: string): ContextFile[];
+    load(files: ContextFile[]): string;
+    watch(workDir: string, onChange: Function): void;
+    stopWatching(): void;
+    addCustomFile(filePath: string): void;
+}
+//# sourceMappingURL=context-discovery.d.ts.map

package/dist/core/context-discovery.js

@@ -0,0 +1,107 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ContextDiscovery = void 0;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const FILE_TYPE_MAP = {
+    'AGENTS.md': 'agents',
+    'SOUL.md': 'soul',
+    'USER.md': 'user',
+    'MEMORY.md': 'memory',
+    'TOOLS.md': 'tools',
+    'IDENTITY.md': 'identity',
+    'HEARTBEAT.md': 'heartbeat',
+    'BOOTSTRAP.md': 'bootstrap',
+    '.opc.md': 'custom',
+    '.opc/config.md': 'custom',
+};
+class ContextDiscovery {
+    static STANDARD_FILES = [
+        'AGENTS.md', 'SOUL.md', 'USER.md', 'MEMORY.md', 'TOOLS.md',
+        'IDENTITY.md', 'HEARTBEAT.md', 'BOOTSTRAP.md',
+        '.opc.md', '.opc/config.md',
+    ];
+    customFiles = [];
+    watchers = [];
+    discover(workDir) {
+        const dir = workDir || process.cwd();
+        const found = [];
+        for (const file of ContextDiscovery.STANDARD_FILES) {
+            const fullPath = path.join(dir, file);
+            if (fs.existsSync(fullPath)) {
+                found.push({
+                    path: fullPath,
+                    type: FILE_TYPE_MAP[file] || 'custom',
+                    content: fs.readFileSync(fullPath, 'utf-8'),
+                });
+            }
+        }
+        for (const file of this.customFiles) {
+            const fullPath = path.isAbsolute(file) ? file : path.join(dir, file);
+            if (fs.existsSync(fullPath)) {
+                found.push({
+                    path: fullPath,
+                    type: 'custom',
+                    content: fs.readFileSync(fullPath, 'utf-8'),
+                });
+            }
+        }
+        return found;
+    }
+    load(files) {
+        return files.map(f => `# ${f.type.toUpperCase()}\n${f.content}`).join('\n\n');
+    }
+    watch(workDir, onChange) {
+        const watcher = fs.watch(workDir, { recursive: false }, (event, filename) => {
+            if (filename && ContextDiscovery.STANDARD_FILES.includes(filename)) {
+                onChange(filename, event);
+            }
+        });
+        this.watchers.push(watcher);
+    }
+    stopWatching() {
+        for (const w of this.watchers)
+            w.close();
+        this.watchers = [];
+    }
+    addCustomFile(filePath) {
+        if (!this.customFiles.includes(filePath)) {
+            this.customFiles.push(filePath);
+        }
+    }
+}
+exports.ContextDiscovery = ContextDiscovery;
+//# sourceMappingURL=context-discovery.js.map

package/dist/core/context-refs.d.ts

@@ -0,0 +1,29 @@
+export type RefType = 'file' | 'folder' | 'url' | 'git-diff' | 'git-log';
+export interface ContextRef {
+    type: RefType;
+    path: string;
+    content?: string;
+}
+export interface Message {
+    role: string;
+    content: string;
+    [key: string]: unknown;
+}
+export declare class ContextRefResolver {
+    /**
+     * Parse @-references from text without resolving content.
+     */
+    parseRefs(text: string): ContextRef[];
+    /**
+     * Resolve content for each ref. Returns new array with content filled in.
+     */
+    resolveRefs(refs: ContextRef[]): Promise<ContextRef[]>;
+    private resolveOne;
+    private listDir;
+    private fetchUrl;
+    /**
+     * Inject resolved refs as system messages before the user's last message.
+     */
+    injectRefs(messages: Message[], refs: ContextRef[]): Message[];
+}
+//# sourceMappingURL=context-refs.d.ts.map

package/dist/core/context-refs.js

@@ -0,0 +1,162 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ContextRefResolver = void 0;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const child_process_1 = require("child_process");
+const MAX_CONTENT_LENGTH = 5000;
+function truncate(text, max = MAX_CONTENT_LENGTH) {
+    if (text.length <= max)
+        return text;
+    return text.slice(0, max) + `\n...[truncated, ${text.length - max} chars omitted]`;
+}
+class ContextRefResolver {
+    /**
+     * Parse @-references from text without resolving content.
+     */
+    parseRefs(text) {
+        const refs = [];
+        const patterns = [
+            [/@file:(\S+)/g, 'file', (m) => m[1]],
+            [/@folder:(\S+)/g, 'folder', (m) => m[1]],
+            [/@url:(https?:\/\/\S+)/g, 'url', (m) => m[1]],
+            [/@git-diff\b/g, 'git-diff', () => 'git-diff'],
+            [/@git-log:(\d+)/g, 'git-log', (m) => m[1]],
+            [/@git-log\b(?!:)/g, 'git-log', () => '10'],
+        ];
+        for (const [regex, type, extract] of patterns) {
+            let match;
+            while ((match = regex.exec(text)) !== null) {
+                refs.push({ type, path: extract(match) });
+            }
+        }
+        return refs;
+    }
+    /**
+     * Resolve content for each ref. Returns new array with content filled in.
+     */
+    async resolveRefs(refs) {
+        return Promise.all(refs.map(async (ref) => {
+            try {
+                const content = await this.resolveOne(ref);
+                return { ...ref, content: truncate(content) };
+            }
+            catch (err) {
+                const msg = err instanceof Error ? err.message : String(err);
+                return { ...ref, content: `[Error resolving @${ref.type}:${ref.path}]: ${msg}` };
+            }
+        }));
+    }
+    async resolveOne(ref) {
+        switch (ref.type) {
+            case 'file':
+                return fs.readFileSync(ref.path, 'utf-8');
+            case 'folder':
+                return this.listDir(ref.path);
+            case 'url':
+                return await this.fetchUrl(ref.path);
+            case 'git-diff':
+                return (0, child_process_1.execSync)('git diff', { encoding: 'utf-8', timeout: 10000 });
+            case 'git-log': {
+                const n = parseInt(ref.path) || 10;
+                return (0, child_process_1.execSync)(`git log --oneline -${n}`, { encoding: 'utf-8', timeout: 10000 });
+            }
+            default:
+                return `[Unknown ref type: ${ref.type}]`;
+        }
+    }
+    listDir(dirPath, prefix = '', depth = 0) {
+        if (depth > 5)
+            return prefix + '...(max depth)\n';
+        if (!fs.existsSync(dirPath))
+            throw new Error(`Directory not found: ${dirPath}`);
+        const entries = fs.readdirSync(dirPath, { withFileTypes: true });
+        let result = '';
+        for (const entry of entries) {
+            if (entry.name.startsWith('.') || entry.name === 'node_modules')
+                continue;
+            result += `${prefix}${entry.isDirectory() ? '📁 ' : '📄 '}${entry.name}\n`;
+            if (entry.isDirectory()) {
+                result += this.listDir(path.join(dirPath, entry.name), prefix + '  ', depth + 1);
+            }
+        }
+        return result;
+    }
+    async fetchUrl(url) {
+        const controller = new AbortController();
+        const timeout = setTimeout(() => controller.abort(), 10000);
+        try {
+            const res = await fetch(url, { signal: controller.signal });
+            const text = await res.text();
+            return text;
+        }
+        finally {
+            clearTimeout(timeout);
+        }
+    }
+    /**
+     * Inject resolved refs as system messages before the user's last message.
+     */
+    injectRefs(messages, refs) {
+        if (refs.length === 0)
+            return messages;
+        const resolvedRefs = refs.filter(r => r.content);
+        if (resolvedRefs.length === 0)
+            return messages;
+        const contextMessages = resolvedRefs.map(ref => ({
+            role: 'system',
+            content: `[Context from @${ref.type}:${ref.path}]\n\`\`\`\n${ref.content}\n\`\`\``,
+        }));
+        // Insert before the last user message
+        const result = [...messages];
+        let lastUserIdx = -1;
+        for (let i = result.length - 1; i >= 0; i--) {
+            if (result[i].role === 'user') {
+                lastUserIdx = i;
+                break;
+            }
+        }
+        if (lastUserIdx >= 0) {
+            result.splice(lastUserIdx, 0, ...contextMessages);
+        }
+        else {
+            result.push(...contextMessages);
+        }
+        return result;
+    }
+}
+exports.ContextRefResolver = ContextRefResolver;
+//# sourceMappingURL=context-refs.js.map

package/dist/core/gateway.d.ts

@@ -0,0 +1,53 @@
+import { EventEmitter } from 'events';
+export interface AgentConfig {
+    id: string;
+    name: string;
+    model?: string;
+    skills?: string[];
+}
+export interface ChannelConfig {
+    id: string;
+    type: string;
+    config?: Record<string, unknown>;
+}
+export interface GatewayConfig {
+    port: number;
+    agents: AgentConfig[];
+    channels: ChannelConfig[];
+}
+interface GatewayMessage {
+    id: string;
+    content: string;
+    channel: string;
+    timestamp: number;
+}
+export declare class Gateway extends EventEmitter {
+    private config;
+    private agents;
+    private channels;
+    private running;
+    private startTime;
+    private messagesProcessed;
+    private latencies;
+    private errors;
+    constructor(config: GatewayConfig);
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    routeMessage(message: GatewayMessage, channel: string): Promise<string>;
+    addAgent(config: AgentConfig): void;
+    removeAgent(id: string): void;
+    addChannel(config: ChannelConfig): void;
+    getStatus(): {
+        uptime: number;
+        agents: number;
+        channels: number;
+        messagesProcessed: number;
+    };
+    getMetrics(): {
+        messagesPerMinute: number;
+        avgLatency: number;
+        errorRate: number;
+    };
+}
+export {};
+//# sourceMappingURL=gateway.d.ts.map

package/dist/core/gateway.js

@@ -0,0 +1,80 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Gateway = void 0;
+const events_1 = require("events");
+class Gateway extends events_1.EventEmitter {
+    config;
+    agents = new Map();
+    channels = new Map();
+    running = false;
+    startTime = 0;
+    messagesProcessed = 0;
+    latencies = [];
+    errors = 0;
+    constructor(config) {
+        super();
+        this.config = config;
+        for (const a of config.agents)
+            this.agents.set(a.id, a);
+        for (const c of config.channels)
+            this.channels.set(c.id, c);
+    }
+    async start() {
+        if (this.running)
+            throw new Error('Gateway already running');
+        this.running = true;
+        this.startTime = Date.now();
+        this.emit('started');
+    }
+    async stop() {
+        if (!this.running)
+            throw new Error('Gateway not running');
+        this.running = false;
+        this.emit('stopped');
+    }
+    async routeMessage(message, channel) {
+        if (!this.running)
+            throw new Error('Gateway not running');
+        const start = Date.now();
+        this.messagesProcessed++;
+        // Simple round-robin routing
+        const agentIds = Array.from(this.agents.keys());
+        if (agentIds.length === 0) {
+            this.errors++;
+            throw new Error('No agents available');
+        }
+        const agentId = agentIds[this.messagesProcessed % agentIds.length];
+        this.latencies.push(Date.now() - start);
+        return agentId;
+    }
+    addAgent(config) {
+        this.agents.set(config.id, config);
+    }
+    removeAgent(id) {
+        if (!this.agents.has(id))
+            throw new Error(`Agent ${id} not found`);
+        this.agents.delete(id);
+    }
+    addChannel(config) {
+        this.channels.set(config.id, config);
+    }
+    getStatus() {
+        return {
+            uptime: this.running ? Date.now() - this.startTime : 0,
+            agents: this.agents.size,
+            channels: this.channels.size,
+            messagesProcessed: this.messagesProcessed,
+        };
+    }
+    getMetrics() {
+        const upMinutes = this.running ? (Date.now() - this.startTime) / 60000 : 1;
+        const avgLatency = this.latencies.length ? this.latencies.reduce((a, b) => a + b, 0) / this.latencies.length : 0;
+        return {
+            messagesPerMinute: this.messagesProcessed / Math.max(upMinutes, 0.001),
+            avgLatency,
+            errorRate: this.messagesProcessed ? this.errors / this.messagesProcessed : 0,
+        };
+    }
+}
+exports.Gateway = Gateway;
+//# sourceMappingURL=gateway.js.map

package/dist/core/heartbeat.d.ts

@@ -0,0 +1,19 @@
+export interface HeartbeatConfig {
+    interval: number;
+    checkFn: () => Promise<string>;
+}
+export declare class HeartbeatManager {
+    private config;
+    private timer;
+    private callbacks;
+    private lastBeat;
+    constructor(config: HeartbeatConfig);
+    start(): void;
+    stop(): void;
+    onBeat(callback: (status: string) => void): void;
+    getLastBeat(): {
+        timestamp: number;
+        status: string;
+    } | null;
+}
+//# sourceMappingURL=heartbeat.d.ts.map

package/dist/core/heartbeat.js

@@ -0,0 +1,50 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HeartbeatManager = void 0;
+class HeartbeatManager {
+    config;
+    timer = null;
+    callbacks = [];
+    lastBeat = null;
+    constructor(config) {
+        if (!config.interval || config.interval < 100) {
+            throw new Error('HeartbeatManager requires interval >= 100ms');
+        }
+        if (typeof config.checkFn !== 'function') {
+            throw new Error('HeartbeatManager requires checkFn');
+        }
+        this.config = config;
+    }
+    start() {
+        if (this.timer)
+            return;
+        this.timer = setInterval(async () => {
+            try {
+                const status = await this.config.checkFn();
+                this.lastBeat = { timestamp: Date.now(), status };
+                for (const cb of this.callbacks)
+                    cb(status);
+            }
+            catch (err) {
+                const status = `error: ${err.message}`;
+                this.lastBeat = { timestamp: Date.now(), status };
+                for (const cb of this.callbacks)
+                    cb(status);
+            }
+        }, this.config.interval);
+    }
+    stop() {
+        if (this.timer) {
+            clearInterval(this.timer);
+            this.timer = null;
+        }
+    }
+    onBeat(callback) {
+        this.callbacks.push(callback);
+    }
+    getLastBeat() {
+        return this.lastBeat;
+    }
+}
+exports.HeartbeatManager = HeartbeatManager;
+//# sourceMappingURL=heartbeat.js.map

package/dist/core/hooks.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Hooks Module - v1.0.0
+ * Event hook system with priority ordering and context modification.
+ */
+export type HookEvent = 'before:message' | 'after:message' | 'before:tool' | 'after:tool' | 'before:llm' | 'after:llm' | 'before:send' | 'after:send' | 'before:learn' | 'after:learn' | 'before:recall' | 'after:recall' | 'on:error' | 'on:start' | 'on:stop';
+export declare const ALL_HOOK_EVENTS: HookEvent[];
+export interface HookContext {
+    [key: string]: unknown;
+}
+export type HookHandler = (ctx: HookContext) => HookContext | void | Promise<HookContext | void>;
+export declare class HookManager {
+    private hooks;
+    register(event: HookEvent, handler: HookHandler, options?: {
+        priority?: number;
+        name?: string;
+    }): string;
+    unregister(id: string): boolean;
+    run(event: HookEvent, ctx?: HookContext): Promise<HookContext>;
+    getRegistered(event?: HookEvent): {
+        id: string;
+        event: HookEvent;
+        priority: number;
+        name?: string;
+    }[];
+    clear(event?: HookEvent): void;
+    hasHooks(event: HookEvent): boolean;
+}
+//# sourceMappingURL=hooks.d.ts.map