@lawrenceliang-btc/atel-sdk 0.8.7

package/dist/envelope/index.js

@@ -0,0 +1,156 @@
+/**
+ * Module: Message Envelope
+ *
+ * Standardized message format for ATEL inter-agent communication.
+ * Every message is signed by the sender and verified by the receiver.
+ * Includes nonce + timestamp for replay protection.
+ */
+import { v4 as uuidv4 } from 'uuid';
+import { sign, verify, serializePayload } from '../identity/index.js';
+// ─── Custom Errors ───────────────────────────────────────────────
+export class EnvelopeError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'EnvelopeError';
+    }
+}
+// ─── Constants ───────────────────────────────────────────────────
+/** Maximum age of a message before it's considered expired (5 minutes) */
+const MAX_MESSAGE_AGE_MS = 5 * 60 * 1000;
+// ─── Core Functions ──────────────────────────────────────────────
+/**
+ * Create and sign an ATEL message.
+ *
+ * @param options - Message creation options.
+ * @returns A signed ATELMessage.
+ */
+export function createMessage(options) {
+    const { type, from, to, payload, secretKey } = options;
+    const unsigned = {
+        envelope: 'atel.msg.v1',
+        type,
+        from,
+        to,
+        timestamp: new Date().toISOString(),
+        nonce: uuidv4(),
+        payload,
+    };
+    const signable = serializePayload(unsigned);
+    const signature = sign(signable, secretKey);
+    return { ...unsigned, signature };
+}
+/**
+ * Verify an ATEL message's signature and freshness.
+ *
+ * Checks:
+ * 1. Envelope version is supported
+ * 2. Required fields are present
+ * 3. Timestamp is not too old (replay protection)
+ * 4. Signature is valid against sender's public key
+ *
+ * @param message - The message to verify.
+ * @param senderPublicKey - The sender's 32-byte Ed25519 public key.
+ * @param options - Optional verification settings.
+ * @returns Verification result.
+ */
+export function verifyMessage(message, senderPublicKey, options) {
+    // Check envelope version
+    if (message.envelope !== 'atel.msg.v1') {
+        return { valid: false, error: `Unsupported envelope version: ${message.envelope}` };
+    }
+    // Check required fields
+    if (!message.from || !message.to || !message.type || !message.nonce) {
+        return { valid: false, error: 'Missing required fields' };
+    }
+    // Check timestamp freshness (replay protection)
+    if (!options?.skipTimestampCheck) {
+        const maxAge = options?.maxAgeMs ?? MAX_MESSAGE_AGE_MS;
+        const messageTime = new Date(message.timestamp).getTime();
+        const now = Date.now();
+        if (isNaN(messageTime)) {
+            return { valid: false, error: 'Invalid timestamp format' };
+        }
+        if (now - messageTime > maxAge) {
+            return { valid: false, error: 'Message expired (timestamp too old)' };
+        }
+        if (messageTime > now + 30_000) {
+            return { valid: false, error: 'Message timestamp is in the future' };
+        }
+    }
+    // Verify signature
+    const { signature, ...unsigned } = message;
+    const signable = serializePayload(unsigned);
+    if (!verify(signable, signature, senderPublicKey)) {
+        return { valid: false, error: 'Invalid signature' };
+    }
+    return { valid: true };
+}
+/**
+ * Serialize an ATEL message to JSON string for transmission.
+ *
+ * @param message - The message to serialize.
+ * @returns JSON string.
+ */
+export function serializeMessage(message) {
+    return JSON.stringify(message);
+}
+/**
+ * Deserialize a JSON string into an ATEL message.
+ *
+ * @param json - The JSON string to parse.
+ * @returns The parsed ATELMessage.
+ * @throws EnvelopeError if parsing fails.
+ */
+export function deserializeMessage(json) {
+    try {
+        const parsed = JSON.parse(json);
+        if (!parsed.envelope || !parsed.type || !parsed.from) {
+            throw new EnvelopeError('Invalid ATEL message structure');
+        }
+        return parsed;
+    }
+    catch (e) {
+        if (e instanceof EnvelopeError)
+            throw e;
+        throw new EnvelopeError(`Failed to parse ATEL message: ${e.message}`);
+    }
+}
+// ─── Nonce Tracker (Replay Protection) ───────────────────────────
+/**
+ * Tracks seen nonces to prevent replay attacks.
+ * Automatically evicts expired entries.
+ */
+export class NonceTracker {
+    seen = new Map();
+    maxAgeMs;
+    constructor(maxAgeMs = MAX_MESSAGE_AGE_MS * 2) {
+        this.maxAgeMs = maxAgeMs;
+    }
+    /**
+     * Check if a nonce has been seen before. If not, record it.
+     *
+     * @param nonce - The nonce to check.
+     * @returns True if the nonce is new (not a replay).
+     */
+    check(nonce) {
+        this.evict();
+        if (this.seen.has(nonce)) {
+            return false; // Replay detected
+        }
+        this.seen.set(nonce, Date.now());
+        return true;
+    }
+    /** Remove expired nonces. */
+    evict() {
+        const cutoff = Date.now() - this.maxAgeMs;
+        for (const [nonce, ts] of this.seen) {
+            if (ts < cutoff) {
+                this.seen.delete(nonce);
+            }
+        }
+    }
+    /** Get the number of tracked nonces. */
+    get size() {
+        return this.seen.size;
+    }
+}

package/dist/executor/index.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Module: Built-in Executor
+ *
+ * Default executor that bridges ATEL tasks to OpenClaw agent sessions.
+ * Automatically started by `atel start` when no external ATEL_EXECUTOR_URL is set.
+ *
+ * Flow:
+ *   1. Receives task from ATEL endpoint
+ *   2. Reads agent-context.md for shared context (if exists)
+ *   3. Calls OpenClaw Gateway → sessions_spawn
+ *   4. Polls for result via sessions_history
+ *   5. Callbacks result to ATEL endpoint
+ *
+ * Security:
+ *   - Business-layer payload audit (capability mismatch, fs ops, network, code exec)
+ *   - Configurable via policy.json
+ *   - Agent context file provides identity without exposing private data
+ */
+export interface BuiltinExecutorConfig {
+    /** Port to listen on */
+    port: number;
+    /** ATEL agent callback URL (for result delivery) */
+    callbackUrl: string;
+    /** OpenClaw Gateway URL */
+    gatewayUrl?: string;
+    /** OpenClaw Gateway auth token */
+    gatewayToken?: string;
+    /** Path to agent-context.md (optional shared context) */
+    contextPath?: string;
+    /** ToolGateway proxy URL (optional) */
+    toolProxyUrl?: string;
+    /** Logger function */
+    log?: (obj: Record<string, unknown>) => void;
+}
+export interface ExecutorAuditResult {
+    safe: boolean;
+    reason?: string;
+    severity?: 'low' | 'medium' | 'high' | 'critical';
+}
+export interface TaskRequest {
+    taskId: string;
+    from: string;
+    action: string;
+    payload: Record<string, unknown>;
+    toolProxy?: string;
+}
+export declare class BuiltinExecutor {
+    private app;
+    private server;
+    private config;
+    private agentContext;
+    private taskHistoryPath;
+    private log;
+    constructor(config: BuiltinExecutorConfig);
+    private loadContext;
+    private loadTaskHistory;
+    private saveTaskHistory;
+    private setupRoutes;
+    private processTask;
+    private buildPrompt;
+    private executeDirect;
+    private pollResultFile;
+    private executeViaTool;
+    private finalizeTool;
+    private callback;
+    /** Business-layer security audit */
+    auditPayload(action: string, payload: Record<string, unknown>): ExecutorAuditResult;
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    get url(): string;
+}

package/dist/executor/index.js

@@ -0,0 +1,398 @@
+/**
+ * Module: Built-in Executor
+ *
+ * Default executor that bridges ATEL tasks to OpenClaw agent sessions.
+ * Automatically started by `atel start` when no external ATEL_EXECUTOR_URL is set.
+ *
+ * Flow:
+ *   1. Receives task from ATEL endpoint
+ *   2. Reads agent-context.md for shared context (if exists)
+ *   3. Calls OpenClaw Gateway → sessions_spawn
+ *   4. Polls for result via sessions_history
+ *   5. Callbacks result to ATEL endpoint
+ *
+ * Security:
+ *   - Business-layer payload audit (capability mismatch, fs ops, network, code exec)
+ *   - Configurable via policy.json
+ *   - Agent context file provides identity without exposing private data
+ */
+import express from 'express';
+import { readFileSync, existsSync, mkdirSync, appendFileSync } from 'node:fs';
+import { join } from 'node:path';
+// ─── Built-in Executor ──────────────────────────────────────────
+export class BuiltinExecutor {
+    app;
+    server = null;
+    config;
+    agentContext = '';
+    taskHistoryPath = '';
+    log;
+    constructor(config) {
+        this.config = {
+            gatewayUrl: 'http://127.0.0.1:18789',
+            gatewayToken: '',
+            contextPath: '',
+            toolProxyUrl: '',
+            ...config,
+        };
+        this.log = config.log || ((obj) => console.log(`[Executor] ${JSON.stringify(obj)}`));
+        // Auto-detect gateway token
+        if (!this.config.gatewayToken) {
+            try {
+                const home = process.env.HOME || '';
+                const c = JSON.parse(readFileSync(join(home, '.openclaw/openclaw.json'), 'utf-8'));
+                this.config.gatewayToken = c.gateway?.auth?.token || '';
+            }
+            catch { /* ignore */ }
+        }
+        // Load agent context
+        this.loadContext();
+        // Task history path
+        this.taskHistoryPath = join(process.cwd(), '.atel', 'task-history.md');
+        // Setup express
+        this.app = express();
+        this.app.use(express.json({ limit: '1mb' }));
+        this.setupRoutes();
+    }
+    loadContext() {
+        // Try multiple paths for agent context
+        const paths = [
+            this.config.contextPath,
+            join(process.cwd(), '.atel', 'agent-context.md'),
+            join(process.cwd(), 'agent-context.md'),
+        ].filter(Boolean);
+        for (const p of paths) {
+            if (existsSync(p)) {
+                this.agentContext = readFileSync(p, 'utf-8');
+                this.log({ event: 'context_loaded', path: p, size: this.agentContext.length });
+                return;
+            }
+        }
+        this.log({ event: 'context_not_found', note: 'No agent-context.md found, tasks will run without shared context' });
+    }
+    loadTaskHistory(limit = 10) {
+        try {
+            if (!existsSync(this.taskHistoryPath))
+                return '';
+            const content = readFileSync(this.taskHistoryPath, 'utf-8');
+            // Get last N entries (each entry starts with "### ")
+            const entries = content.split(/(?=^### )/m).filter(e => e.trim());
+            const recent = entries.slice(-limit).join('\n');
+            if (recent) {
+                this.log({ event: 'history_loaded', entries: entries.length, using: Math.min(entries.length, limit) });
+            }
+            return recent;
+        }
+        catch {
+            return '';
+        }
+    }
+    saveTaskHistory(taskId, from, action, payload, result, success) {
+        try {
+            const timestamp = new Date().toISOString();
+            const text = (payload.text || payload.message || payload.task || payload.query || '');
+            const resultText = typeof result === 'object' && result !== null
+                ? (result.response || JSON.stringify(result)).toString().slice(0, 200)
+                : String(result).slice(0, 200);
+            const entry = `### ${timestamp} | ${action} | from: ${from.slice(-8)}
+- Task: ${text.slice(0, 150)}
+- Result: ${success ? resultText : 'FAILED'}
+- Status: ${success ? 'success' : 'failed'}
+
+`;
+            appendFileSync(this.taskHistoryPath, entry);
+            this.log({ event: 'history_saved', taskId });
+        }
+        catch (e) {
+            this.log({ event: 'history_save_failed', taskId, error: e.message });
+        }
+    }
+    setupRoutes() {
+        this.app.get('/health', (_req, res) => {
+            res.json({ status: 'ok', type: 'builtin-executor', gateway: this.config.gatewayUrl, hasContext: !!this.agentContext });
+        });
+        // Internal endpoint for ToolGateway to call back into executor
+        this.app.post('/internal/openclaw_agent', async (req, res) => {
+            const { tool, input } = req.body;
+            try {
+                const prompt = input?.prompt || input?.text || JSON.stringify(input);
+                const taskId = input?.taskId || `internal-${Date.now()}`;
+                const result = await this.executeDirect(prompt, taskId);
+                res.json(result);
+            }
+            catch (e) {
+                const msg = e instanceof Error ? e.message : String(e);
+                res.status(500).json({ error: msg });
+            }
+        });
+        this.app.post('/', async (req, res) => {
+            const { taskId, from, action, payload, toolProxy } = req.body;
+            this.log({ event: 'task_received', taskId, from, action, toolProxy: toolProxy || 'none' });
+            // Respond immediately
+            res.json({ status: 'accepted', taskId });
+            // Process async
+            this.processTask({ taskId, from, action, payload, toolProxy: toolProxy || this.config.toolProxyUrl || '' });
+        });
+    }
+    async processTask(task) {
+        const { taskId, from, action, payload, toolProxy } = task;
+        try {
+            // ── ToolGateway init ──
+            if (toolProxy) {
+                this.log({ event: 'toolgateway_init', taskId });
+                await fetch(`${toolProxy}/init`, {
+                    method: 'POST',
+                    headers: { 'Content-Type': 'application/json' },
+                    body: JSON.stringify({ taskId }),
+                });
+                // Register openclaw_agent tool so ToolGateway can record trace
+                await fetch(`${toolProxy}/register`, {
+                    method: 'POST',
+                    headers: { 'Content-Type': 'application/json' },
+                    body: JSON.stringify({
+                        taskId,
+                        tool: 'openclaw_agent',
+                        endpoint: `http://127.0.0.1:${this.config.port}/internal/openclaw_agent`,
+                    }),
+                });
+                this.log({ event: 'toolgateway_registered', taskId, tool: 'openclaw_agent' });
+            }
+            // ── Security audit ──
+            const audit = this.auditPayload(action, payload);
+            if (!audit.safe) {
+                this.log({ event: 'task_rejected', taskId, reason: audit.reason });
+                if (toolProxy) {
+                    await this.finalizeTool(toolProxy, taskId, false, { error: `Security: ${audit.reason}` });
+                }
+                await this.callback(taskId, { error: `Security: ${audit.reason}`, severity: audit.severity }, false);
+                return;
+            }
+            // ── Build prompt with context ──
+            const prompt = this.buildPrompt(from, action, payload);
+            this.log({ event: 'executing', taskId, promptLength: prompt.length });
+            // ── Execute via OpenClaw Gateway ──
+            let result;
+            if (toolProxy) {
+                result = await this.executeViaTool(toolProxy, taskId, prompt, action, from);
+            }
+            else {
+                result = await this.executeDirect(prompt, taskId);
+            }
+            this.log({ event: 'task_completed', taskId });
+            // ── Save task history ──
+            this.saveTaskHistory(taskId, from, action, payload, result, true);
+            // ── Finalize trace ──
+            let trace = null;
+            if (toolProxy) {
+                trace = await this.finalizeTool(toolProxy, taskId, true, result);
+            }
+            // ── Callback ──
+            await this.callback(taskId, result, true, trace);
+        }
+        catch (e) {
+            const msg = e instanceof Error ? e.message : String(e);
+            this.log({ event: 'task_failed', taskId, error: msg });
+            // Save failed task to history
+            this.saveTaskHistory(taskId, from, action, payload, { error: msg }, false);
+            if (toolProxy) {
+                await this.finalizeTool(toolProxy, taskId, false, { error: msg }).catch(() => { });
+            }
+            await this.callback(taskId, { error: msg }, false).catch(() => { });
+        }
+    }
+    buildPrompt(from, action, payload) {
+        const text = (payload.text || payload.message || payload.task || payload.query || JSON.stringify(payload));
+        const guides = {
+            translation: `Translate the following text to ${payload.target_lang || 'the target language'}. Return only the translation.`,
+            coding: 'Help with the following coding task. Provide working code with brief explanation.',
+            research: 'Research the following topic and provide useful, accurate information.',
+            general: 'Complete the following task.',
+        };
+        const guide = guides[action] || guides.general;
+        let prompt = '';
+        if (this.agentContext) {
+            prompt += `## Agent Context\n${this.agentContext}\n\n`;
+        }
+        const history = this.loadTaskHistory();
+        if (history) {
+            prompt += `## Recent Task History\n${history}\n\n`;
+        }
+        prompt += `## Task\n${guide}\n\n${text}`;
+        return prompt;
+    }
+    async executeDirect(prompt, taskId) {
+        const { gatewayUrl, gatewayToken } = this.config;
+        // Result file: sub-session writes result here, we poll for it
+        const resultDir = join(process.cwd(), '.atel', 'results');
+        try {
+            mkdirSync(resultDir, { recursive: true });
+        }
+        catch { /* exists */ }
+        const resultFile = join(resultDir, `${taskId}.json`);
+        // Wrap prompt: instruct sub-agent to write result to file
+        const wrappedPrompt = `${prompt}
+
+IMPORTANT: After completing the task, you MUST write your final answer to this file using the write tool:
+File: ${resultFile}
+Write ONLY a JSON object: {"done":true,"response":"<your answer here>"}
+Do not include any other text in the file. This is required for the result to be delivered.`;
+        // Spawn sub-session via Gateway HTTP API
+        const spawnResp = await fetch(`${gatewayUrl}/tools/invoke`, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                'Authorization': `Bearer ${gatewayToken}`,
+            },
+            body: JSON.stringify({
+                tool: 'sessions_spawn',
+                args: { task: wrappedPrompt, runTimeoutSeconds: 120 },
+            }),
+            signal: AbortSignal.timeout(10000),
+        });
+        if (!spawnResp.ok) {
+            const errText = await spawnResp.text();
+            if (errText.includes('not_found') || errText.includes('not available')) {
+                throw new Error('sessions_spawn not available via Gateway HTTP API. Add "sessions_spawn" to gateway.tools.allow in openclaw.json and restart gateway.');
+            }
+            throw new Error(`Gateway spawn failed: ${spawnResp.status} ${errText}`);
+        }
+        const spawnData = await spawnResp.json();
+        const childKey = spawnData.result?.details?.childSessionKey || spawnData.result?.childSessionKey;
+        this.log({ event: 'session_spawned', taskId, childKey, resultFile });
+        // Poll for result file
+        return this.pollResultFile(resultFile, taskId, 120000);
+    }
+    async pollResultFile(resultFile, taskId, timeoutMs) {
+        const deadline = Date.now() + timeoutMs;
+        const interval = 2000;
+        while (Date.now() < deadline) {
+            await new Promise(r => setTimeout(r, interval));
+            try {
+                if (existsSync(resultFile)) {
+                    const content = readFileSync(resultFile, 'utf-8').trim();
+                    try {
+                        const parsed = JSON.parse(content);
+                        if (parsed.done) {
+                            this.log({ event: 'result_received', taskId, method: 'file' });
+                            // Cleanup
+                            try {
+                                require('node:fs').unlinkSync(resultFile);
+                            }
+                            catch { /* ignore */ }
+                            return { response: parsed.response, agent: 'builtin-executor', action: taskId.split('-')[0] || 'general' };
+                        }
+                    }
+                    catch {
+                        // File exists but not valid JSON yet, keep polling
+                    }
+                }
+            }
+            catch { /* retry */ }
+        }
+        throw new Error(`Task ${taskId} timed out after ${timeoutMs}ms`);
+    }
+    async executeViaTool(toolProxy, taskId, prompt, action, from) {
+        const resp = await fetch(`${toolProxy}/call`, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({
+                taskId,
+                tool: 'openclaw_agent',
+                input: { prompt, action, from },
+            }),
+        });
+        if (!resp.ok) {
+            throw new Error(`ToolGateway call failed: ${resp.status} ${await resp.text()}`);
+        }
+        const result = await resp.json();
+        return result.output;
+    }
+    async finalizeTool(toolProxy, taskId, success, result) {
+        try {
+            const resp = await fetch(`${toolProxy}/finalize`, {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify({ taskId, success, result }),
+            });
+            if (resp.ok) {
+                const data = await resp.json();
+                this.log({ event: 'trace_finalized', taskId, events: data.trace?.events?.length || 0 });
+                return data.trace;
+            }
+        }
+        catch { /* ignore */ }
+        return null;
+    }
+    async callback(taskId, result, success, trace) {
+        const body = { taskId, result, success };
+        if (trace)
+            body.trace = trace;
+        await fetch(this.config.callbackUrl, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify(body),
+        });
+        this.log({ event: 'callback_sent', taskId, success });
+    }
+    /** Business-layer security audit */
+    auditPayload(action, payload) {
+        const text = JSON.stringify(payload).toLowerCase();
+        // Cross-capability mismatch
+        const mismatch = {
+            translation: [/send.*email/i, /database/i, /api.*call/i, /execute.*code/i],
+            coding: [/send.*email/i, /database.*query/i, /translate/i],
+            research: [/execute/i, /run.*code/i, /send.*email/i],
+        };
+        if (mismatch[action]) {
+            for (const p of mismatch[action]) {
+                if (p.test(text))
+                    return { safe: false, reason: `Action "${action}" mismatch: ${p.source}`, severity: 'medium' };
+            }
+        }
+        // File system ops
+        for (const p of [/read.*file/i, /write.*file/i, /create.*file/i, /delete.*file/i, /save.*to.*disk/i]) {
+            if (p.test(text))
+                return { safe: false, reason: 'File system operations require consent', severity: 'high' };
+        }
+        // External network
+        for (const p of [/fetch.*http/i, /api.*request/i, /call.*external/i, /webhook/i]) {
+            if (p.test(text))
+                return { safe: false, reason: 'External network requests require consent', severity: 'high' };
+        }
+        // Code execution
+        for (const p of [/execute.*code/i, /run.*script/i, /eval\(/i, /exec\(/i]) {
+            if (p.test(text))
+                return { safe: false, reason: 'Code execution not allowed', severity: 'critical' };
+        }
+        return { safe: true };
+    }
+    // ─── Lifecycle ──────────────────────────────────────────────────
+    async start() {
+        return new Promise((resolve) => {
+            this.server = this.app.listen(this.config.port, '127.0.0.1', () => {
+                this.log({
+                    event: 'started',
+                    port: this.config.port,
+                    gateway: this.config.gatewayUrl,
+                    callback: this.config.callbackUrl,
+                    hasToken: !!this.config.gatewayToken,
+                    hasContext: !!this.agentContext,
+                });
+                resolve();
+            });
+        });
+    }
+    async stop() {
+        if (this.server) {
+            return new Promise((resolve) => {
+                this.server.close(() => {
+                    this.log({ event: 'stopped' });
+                    resolve();
+                });
+            });
+        }
+    }
+    get url() {
+        return `http://127.0.0.1:${this.config.port}`;
+    }
+}