auramaxx 0.0.1

package/server/lib/strategy/executor.ts

@@ -0,0 +1,115 @@
+/**
+ * Strategy Action Executor
+ * ========================
+ * Executes actions produced by hook intents. Supports internal wallet API
+ * calls and external HTTP endpoints, with paper trading mode.
+ */
+
+import { createToken } from '../auth';
+import { revokeToken } from '../sessions';
+import { validateExternalUrl } from '../network';
+import { Action, ActionOutcome } from './types';
+import { getErrorMessage } from '../error';
+
+/**
+ * Execute a single action, either internally against the wallet server
+ * or externally against a third-party API.
+ */
+export async function executeAction(
+  action: Action,
+  strategyId: string,
+  token?: string,
+  allowedHosts?: string[],
+): Promise<ActionOutcome> {
+  const timeout = AbortSignal.timeout(30_000);
+
+  try {
+    let url: string;
+    const headers: Record<string, string> = {
+      'Content-Type': 'application/json',
+      ...action.headers,
+    };
+
+    if (action.endpoint.startsWith('/')) {
+      // Internal call to wallet server
+      url = `http://127.0.0.1:4242${action.endpoint}`;
+      if (token) {
+        headers['Authorization'] = `Bearer ${token}`;
+      }
+      console.log(`[strategy:${strategyId}] exec: ${action.method} ${url} (internal${token ? ', auth' : ', no-auth'})`);
+    } else if (action.endpoint.startsWith('http')) {
+      // External call — validate against SSRF and allowedHosts
+      url = action.endpoint;
+      try {
+        await validateExternalUrl(url, allowedHosts);
+      } catch (err) {
+        const msg = getErrorMessage(err);
+        console.error(`[strategy:${strategyId}] exec: BLOCKED — ${msg}`);
+        return { success: false, error: msg };
+      }
+      console.log(`[strategy:${strategyId}] exec: ${action.method} ${url} (external)`);
+    } else {
+      console.error(`[strategy:${strategyId}] exec: invalid endpoint "${action.endpoint}"`);
+      return { success: false, error: `Invalid endpoint: ${action.endpoint}` };
+    }
+
+    const isExternal = !action.endpoint.startsWith('/');
+    const execStart = Date.now();
+    const res = await fetch(url, {
+      method: action.method,
+      headers,
+      body: action.body ? JSON.stringify(action.body) : undefined,
+      signal: timeout,
+      ...(isExternal ? { redirect: 'error' as const } : {}),
+    });
+
+    const data = await res.json().catch(() => null);
+    const execMs = Date.now() - execStart;
+
+    if (res.status === 401 && action.endpoint.startsWith('/')) {
+      console.error(`[strategy:${strategyId}] exec: 401 AUTH FAILURE in ${execMs}ms — token likely expired`);
+      throw new Error('AUTH_FAILURE: Internal endpoint returned 401 (token expired or SIGNING_KEY rotated)');
+    }
+
+    if (!res.ok) {
+      console.error(`[strategy:${strategyId}] exec: ${res.status} in ${execMs}ms — ${data?.error || res.statusText}`);
+      return {
+        success: false,
+        error: `HTTP ${res.status}: ${data?.error || res.statusText}`,
+        data,
+      };
+    }
+
+    console.log(`[strategy:${strategyId}] exec: ${res.status} OK in ${execMs}ms`);
+    return { success: true, data };
+  } catch (err: unknown) {
+    const message = getErrorMessage(err);
+    console.error(`[strategy:${strategyId}] exec: threw — ${message}`);
+    // Re-throw auth failures so they propagate to tickStrategy's catch block
+    if (message.includes('AUTH_FAILURE')) throw err;
+    return { success: false, error: message };
+  }
+}
+
+/**
+ * Create a scoped token for a strategy to use when calling internal endpoints.
+ * Token is valid for 24 hours and carries the strategy's declared permissions.
+ */
+export async function createStrategyToken(
+  strategyId: string,
+  permissions: string[]
+): Promise<string> {
+  return createToken(
+    `strategy:${strategyId}`,
+    0,
+    permissions,
+    86400 // 24h
+  );
+}
+
+/**
+ * Revoke a strategy's token by its hash.
+ */
+export async function revokeStrategyToken(tokenHash: string): Promise<boolean> {
+  return revokeToken(tokenHash);
+}

package/server/lib/strategy/hook-context.ts

@@ -0,0 +1,159 @@
+/**
+ * Hook System Context
+ * ===================
+ * Loads and caches system context for strategy hook AI calls.
+ *
+ * Two framing modes:
+ * - 'tool-call': For message hooks (chat apps). AI uses wallet_api + request_human_action tools directly.
+ * - 'intent': For tick hooks (strategies). AI returns intent JSON for the engine to process.
+ *
+ * Two provider paths:
+ * - 'cli': Claude CLI / Codex CLI — model reads MCP resources (docs://guide, docs://api).
+ *          Returns minimal response-format reminder only.
+ * - 'sdk': Anthropic SDK / OpenAI SDK — no MCP resources available.
+ *          Loads full context from skills/auramaxx/SKILL.md + docs/API.md.
+ *
+ * Source of truth: skills/auramaxx/SKILL.md (served as docs://guide MCP resource too).
+ */
+
+import { readFileSync } from 'fs';
+import { join } from 'path';
+import { getErrorMessage } from '../error';
+
+/** Cache key: `${provider}-${mode}` */
+const cache = new Map<string, string>();
+
+/** Minimal response-format reminder for CLI providers (model reads MCP resources for the rest) */
+const CLI_TOOL_CALL_REMINDER = `## Response format
+Return a JSON object with: reply, state, emit (all optional).
+{ "reply": "...", "state": {...}, "emit": {...} }
+
+Tool rule: if user gives a token ticker/name without a contract address,
+call wallet_api GET /token/search?q=<ticker>&chain=<chain> before asking for an address.
+Do not tell the user to search external sites first.
+
+Read the docs://guide resource for operating instructions.
+Read the docs://api resource for the full endpoint reference.`;
+
+const CLI_INTENT_REMINDER = `## Response format
+Return a JSON object with: reply, state, intents, emit (all optional).
+
+Read the docs://guide resource for operating instructions.
+Read the docs://api resource for the full endpoint reference.`;
+
+/** Hardcoded fallback if doc files are missing — never crash */
+const FALLBACK_TOOL_CALL = `## Response format
+Return a JSON object with: reply, state, emit (all optional).
+{ "reply": "...", "state": {...}, "emit": {...} }
+
+Tool rule: for token tickers/names without contract addresses, call
+wallet_api GET /token/search first before asking the user for an address.`;
+
+const FALLBACK_INTENT = `## Response format
+Return a JSON object with: reply, state, intents, emit (all optional).`;
+
+/**
+ * Load the agent guide from skills/auramaxx/SKILL.md and extract a section.
+ * Returns the section content or empty string if not found.
+ */
+function loadAgentGuideSection(mode: 'tool-call' | 'intent'): string {
+  const guidePath = join(__dirname, '..', '..', '..', 'skills', 'auramaxx', 'SKILL.md');
+  try {
+    const full = readFileSync(guidePath, 'utf-8');
+    if (mode === 'tool-call') {
+      const start = full.indexOf('## Tool-Call Mode');
+      const end = full.indexOf('## Intent Mode');
+      if (start !== -1 && end !== -1) {
+        return full.slice(start, end).trim();
+      }
+    } else {
+      const start = full.indexOf('## Intent Mode');
+      const end = full.indexOf('## Reference Documentation');
+      if (start !== -1 && end !== -1) {
+        return full.slice(start, end).trim();
+      }
+      if (start !== -1) {
+        return full.slice(start).trim();
+      }
+    }
+    // Section markers not found — return full content
+    return full.trim();
+  } catch (err) {
+    console.debug('[hook-context] SKILL.md not found:', getErrorMessage(err));
+    return '';
+  }
+}
+
+function loadApiReference(): string {
+  const apiMdPath = join(__dirname, '..', '..', '..', 'docs', 'API.md');
+  try {
+    const full = readFileSync(apiMdPath, 'utf-8');
+    const agentStart = full.indexOf('## Agent Endpoints');
+    const endMarker = full.indexOf('## Request Types');
+    if (agentStart !== -1 && endMarker !== -1) {
+      return full.slice(agentStart, endMarker).trim();
+    }
+    // Newer API.md layouts may not include legacy section markers.
+    // In that case, keep behavior deterministic by returning the full entrypoint doc.
+    return full.trim();
+  } catch (err) {
+    console.debug('[hook-context] API.md not found:', getErrorMessage(err));
+  }
+
+  // Fallback to SKILL.md
+  const skillPath = join(__dirname, '..', '..', '..', 'skills', 'auramaxx', 'SKILL.md');
+  try {
+    return readFileSync(skillPath, 'utf-8').trim();
+  } catch (err) {
+    console.warn('[hook-context] no api reference docs found:', getErrorMessage(err));
+  }
+
+  return '';
+}
+
+/**
+ * Returns the cached system context string for hook AI calls.
+ * Loaded lazily on first call, then cached for the process lifetime.
+ *
+ * @param mode - 'tool-call' for message hooks (chat apps), 'intent' for tick hooks (strategies)
+ * @param provider - 'cli' for CLI providers (reads MCP resources), 'sdk' for SDK providers (needs full injection)
+ */
+export function getHookSystemContext(
+  mode: 'tool-call' | 'intent' = 'intent',
+  provider: 'cli' | 'sdk' = 'sdk',
+): string {
+  const key = `${provider}-${mode}`;
+  const cached = cache.get(key);
+  if (cached !== undefined) return cached;
+
+  let result: string;
+
+  if (provider === 'cli') {
+    // CLI providers: minimal reminder — model reads docs://guide and docs://api via MCP
+    result = mode === 'tool-call' ? CLI_TOOL_CALL_REMINDER : CLI_INTENT_REMINDER;
+  } else {
+    // SDK providers: load full context from doc files (same source as MCP resources)
+    const guideSection = loadAgentGuideSection(mode);
+    const apiRef = loadApiReference();
+
+    if (guideSection) {
+      result = apiRef
+        ? `${guideSection}\n\n## Available API endpoints\n\n${apiRef}`
+        : guideSection;
+    } else {
+      // Fallback if doc file missing
+      const fallback = mode === 'tool-call' ? FALLBACK_TOOL_CALL : FALLBACK_INTENT;
+      result = apiRef
+        ? `${fallback}\n\n## Available API endpoints\n\n${apiRef}`
+        : fallback;
+    }
+  }
+
+  cache.set(key, result);
+  return result;
+}
+
+/** Reset cached context (for tests) */
+export function __resetHookContext(): void {
+  cache.clear();
+}