@albalink/agent 1.0.0

package/dist/session/SessionManager.d.ts

@@ -0,0 +1,64 @@
+/**
+ * SessionManager — manages conversation history, compaction, and persistence.
+ *
+ * Compaction is done in atomic turn pairs so tool_call_id references are
+ * never orphaned (which causes 400 errors from every provider).
+ *
+ * Three compaction tiers:
+ *   Tier 1 (>70%): trim long tool results to 1-line summaries
+ *   Tier 2 (>85%): drop oldest complete turns (atomic pairs only)
+ *   Tier 3 (>95%): hard reset keeping only last KEEP_TURNS turns
+ */
+import type { Message } from "../runner/ModelClient.js";
+/** Context pressure levels for UI display and swarm gating */
+export interface ContextPressure {
+    chars: number;
+    pct: number;
+    level: "green" | "yellow" | "red" | "critical";
+    turboReady: boolean;
+}
+export declare class SessionManager {
+    private history;
+    private systemPrompt;
+    setSystemPrompt(prompt: string): void;
+    getSystemPrompt(): string;
+    addMessage(msg: Message): void;
+    addMessages(msgs: Message[]): void;
+    /** Returns messages ready to send to the model — system prompt prepended */
+    getMessages(): Message[];
+    /** Full raw history (no system prompt) */
+    getHistory(): Message[];
+    clear(): void;
+    charCount(): number;
+    getContextPressure(): ContextPressure;
+    private buildSystemContent;
+    /**
+     * Split history into atomic turns.
+     * A turn = [user_msg, assistant_msg, ...tool_result_msgs]
+     * Keeping turns atomic prevents orphaned tool_call_id errors.
+     */
+    private splitIntoTurns;
+    /**
+     * Tier 1: Trim long tool results in-place. No messages dropped.
+     * Replaces content >TOOL_RESULT_CAP chars with a 1-line summary.
+     */
+    private trimToolResults;
+    /**
+     * Tier 2: Drop oldest turns, but ANCHOR high-value messages (prices, signals,
+     * decisions) so they survive compaction. (#36 semantic anchor compaction)
+     */
+    private dropOldTurns;
+    /** #36: Score a message's semantic importance (0-10) */
+    private messageWeight;
+    maybeCompact(): void;
+    /** Force compaction */
+    forceCompact(): void;
+    /**
+     * #32: Tier-2 summarization via a cheap model.
+     * Compresses the oldest 40% of turns into a single summary message.
+     * Call this when pct is between 70-90 to reclaim space gracefully.
+     * @param summarizeCallback — provided by AgentRunner which has model access
+     */
+    summarizeOldTurns(summarizeCallback: (messages: Message[]) => Promise<string>): Promise<void>;
+}
+//# sourceMappingURL=SessionManager.d.ts.map

package/dist/session/SessionManager.js

@@ -0,0 +1,193 @@
+/**
+ * SessionManager — manages conversation history, compaction, and persistence.
+ *
+ * Compaction is done in atomic turn pairs so tool_call_id references are
+ * never orphaned (which causes 400 errors from every provider).
+ *
+ * Three compaction tiers:
+ *   Tier 1 (>70%): trim long tool results to 1-line summaries
+ *   Tier 2 (>85%): drop oldest complete turns (atomic pairs only)
+ *   Tier 3 (>95%): hard reset keeping only last KEEP_TURNS turns
+ */
+const MAX_HISTORY_CHARS = 80_000; // ~20k tokens rough estimate
+const KEEP_TURNS = 8; // complete turns to keep on hard reset
+const TOOL_RESULT_CAP = 500; // trim tool results longer than this
+export class SessionManager {
+    history = [];
+    systemPrompt = "";
+    setSystemPrompt(prompt) {
+        this.systemPrompt = prompt;
+    }
+    getSystemPrompt() {
+        return this.systemPrompt;
+    }
+    addMessage(msg) {
+        this.history.push(msg);
+        this.maybeCompact();
+    }
+    addMessages(msgs) {
+        for (const m of msgs)
+            this.history.push(m);
+        this.maybeCompact();
+    }
+    /** Returns messages ready to send to the model — system prompt prepended */
+    getMessages() {
+        const sys = { role: "system", content: this.buildSystemContent() };
+        return [sys, ...this.history];
+    }
+    /** Full raw history (no system prompt) */
+    getHistory() {
+        return [...this.history];
+    }
+    clear() {
+        this.history = [];
+    }
+    charCount() {
+        return this.history.reduce((n, m) => n + (typeof m.content === "string" ? m.content.length : 0), 0);
+    }
+    getContextPressure() {
+        const chars = this.charCount();
+        const pct = Math.min(100, Math.round(chars / MAX_HISTORY_CHARS * 100));
+        return {
+            chars,
+            pct,
+            level: pct < 50 ? "green" : pct < 70 ? "yellow" : pct < 90 ? "red" : "critical",
+            turboReady: pct < 70, // keep 30% free for swarm sub-agent outputs
+        };
+    }
+    buildSystemContent() {
+        return this.systemPrompt || "You are ALBA, an AI trading agent.";
+    }
+    /**
+     * Split history into atomic turns.
+     * A turn = [user_msg, assistant_msg, ...tool_result_msgs]
+     * Keeping turns atomic prevents orphaned tool_call_id errors.
+     */
+    splitIntoTurns() {
+        const turns = [];
+        let current = [];
+        for (const msg of this.history) {
+            // New user message starts a new turn (unless history starts with assistant)
+            if (msg.role === "user" && current.length > 0) {
+                turns.push(current);
+                current = [];
+            }
+            current.push(msg);
+        }
+        if (current.length > 0)
+            turns.push(current);
+        return turns;
+    }
+    /**
+     * Tier 1: Trim long tool results in-place. No messages dropped.
+     * Replaces content >TOOL_RESULT_CAP chars with a 1-line summary.
+     */
+    trimToolResults() {
+        for (const msg of this.history) {
+            if (msg.role === "tool" && typeof msg.content === "string" &&
+                msg.content.length > TOOL_RESULT_CAP) {
+                const firstLine = msg.content.split("\n")[0] ?? msg.content.slice(0, 120);
+                msg.content = `${firstLine} … [trimmed, ${msg.content.length} chars]`;
+            }
+        }
+    }
+    /**
+     * Tier 2: Drop oldest turns, but ANCHOR high-value messages (prices, signals,
+     * decisions) so they survive compaction. (#36 semantic anchor compaction)
+     */
+    dropOldTurns() {
+        const turns = this.splitIntoTurns();
+        if (turns.length <= KEEP_TURNS)
+            return;
+        const recentTurns = turns.slice(-KEEP_TURNS);
+        const olderTurns = turns.slice(0, -KEEP_TURNS);
+        // #36: From older turns, extract high-weight messages as anchors
+        const anchors = [];
+        for (const turn of olderTurns) {
+            for (const msg of turn) {
+                if (this.messageWeight(msg) >= 7)
+                    anchors.push(msg);
+            }
+        }
+        // Prepend anchors (deduped) before the recent window
+        const anchorIds = new Set(anchors.map(m => `${m.role}:${String(m.content).slice(0, 50)}`));
+        const recentFlat = recentTurns.flat();
+        // Remove any anchors already in recent window
+        const recentIds = new Set(recentFlat.map(m => `${m.role}:${String(m.content).slice(0, 50)}`));
+        const dedupedAnchors = anchors.filter(m => !recentIds.has(`${m.role}:${String(m.content).slice(0, 50)}`));
+        this.history = [...dedupedAnchors, ...recentFlat];
+        void anchorIds; // suppress unused warning
+    }
+    /** #36: Score a message's semantic importance (0-10) */
+    messageWeight(msg) {
+        if (msg.role === "system")
+            return 10;
+        const content = typeof msg.content === "string" ? msg.content.toLowerCase() : "";
+        if (msg.role === "tool") {
+            // High value: price data, signals, positions, goals
+            if (/\$[\d,]+|\d+%|signal|buy|sell|position|goal|rsi|macd/.test(content))
+                return 8;
+            if (/news|sentiment|bullish|bearish|tvl|funding/.test(content))
+                return 6;
+            return 2; // generic tool result — expendable
+        }
+        if (msg.role === "user")
+            return 3;
+        if (msg.role === "assistant") {
+            // Keep assistant messages with decisions/recommendations
+            if (/recommend|suggest|should|will|plan|strategy|target|stop/.test(content))
+                return 7;
+            return 4;
+        }
+        return 1;
+    }
+    maybeCompact() {
+        const pct = this.getContextPressure().pct;
+        if (pct < 70)
+            return;
+        if (pct < 85) {
+            this.trimToolResults();
+            return;
+        } // Tier 1: trim verbose tool results
+        if (pct < 95) {
+            this.trimToolResults();
+            this.dropOldTurns();
+            return;
+        } // Tier 2: drop turns
+        // Tier 3: hard reset — emergency
+        this.trimToolResults();
+        this.dropOldTurns();
+        if (this.getContextPressure().pct >= 95) {
+            const turns = this.splitIntoTurns();
+            this.history = turns.slice(-4).flat();
+        }
+    }
+    /** Force compaction */
+    forceCompact() {
+        this.trimToolResults();
+        this.dropOldTurns();
+    }
+    /**
+     * #32: Tier-2 summarization via a cheap model.
+     * Compresses the oldest 40% of turns into a single summary message.
+     * Call this when pct is between 70-90 to reclaim space gracefully.
+     * @param summarizeCallback — provided by AgentRunner which has model access
+     */
+    async summarizeOldTurns(summarizeCallback) {
+        const turns = this.splitIntoTurns();
+        if (turns.length < 4)
+            return; // not enough history to summarize
+        const splitAt = Math.floor(turns.length * 0.4);
+        const toSummarize = turns.slice(0, splitAt).flat();
+        const toKeep = turns.slice(splitAt).flat();
+        const summary = await summarizeCallback(toSummarize);
+        this.history = [
+            {
+                role: "system",
+                content: `[CONVERSATION SUMMARY — ${toSummarize.length} earlier messages compressed]\n${summary}`,
+            },
+            ...toKeep,
+        ];
+    }
+}
+//# sourceMappingURL=SessionManager.js.map

package/dist/telemetry/Tracer.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Tracer — lightweight JSONL span tracing for agent observability. (#30)
+ *
+ * Zero external dependencies. Writes structured traces to ~/.alba/traces.jsonl.
+ * Each trace covers one user turn and records all model calls, tool dispatches,
+ * and swarm sub-tasks with timing and status.
+ *
+ * View traces: cat ~/.alba/traces.jsonl | jq
+ * Last 5 traces: tail -5 ~/.alba/traces.jsonl | jq
+ * /traces command in REPL shows a formatted summary.
+ */
+export interface Span {
+    spanId: string;
+    name: string;
+    startMs: number;
+    durationMs?: number;
+    status: "ok" | "error" | "aborted";
+    attrs: Record<string, unknown>;
+}
+export interface Trace {
+    traceId: string;
+    sessionId: string;
+    prompt: string;
+    startMs: number;
+    durationMs?: number;
+    spans: Span[];
+    totalCost?: number;
+    modelUsed?: string;
+}
+export declare class Tracer {
+    /** @internal exposed for AgentRunner span lookup */
+    readonly trace: Trace;
+    constructor(sessionId: string, prompt: string);
+    /** Start a named span, returns spanId */
+    startSpan(name: string, attrs?: Record<string, unknown>): string;
+    /** End a span by ID */
+    endSpan(spanId: string, status?: "ok" | "error" | "aborted", attrs?: Record<string, unknown>): void;
+    /** Record model call details */
+    recordModel(spanId: string, model: string, promptTokens: number, completionTokens: number, costNano: number): void;
+    /** Flush trace to disk */
+    flush(status?: "ok" | "error" | "aborted"): void;
+    get traceId(): string;
+    /** Read last N traces from disk for /traces command */
+    static readRecent(limit?: number): Trace[];
+    /** Format traces for REPL display */
+    static formatSummary(traces: Trace[]): string;
+}
+//# sourceMappingURL=Tracer.d.ts.map

package/dist/telemetry/Tracer.js

@@ -0,0 +1,102 @@
+/**
+ * Tracer — lightweight JSONL span tracing for agent observability. (#30)
+ *
+ * Zero external dependencies. Writes structured traces to ~/.alba/traces.jsonl.
+ * Each trace covers one user turn and records all model calls, tool dispatches,
+ * and swarm sub-tasks with timing and status.
+ *
+ * View traces: cat ~/.alba/traces.jsonl | jq
+ * Last 5 traces: tail -5 ~/.alba/traces.jsonl | jq
+ * /traces command in REPL shows a formatted summary.
+ */
+import { appendFileSync, existsSync, readFileSync, mkdirSync } from "node:fs";
+import { join } from "node:path";
+import { homedir } from "node:os";
+import { randomUUID } from "node:crypto";
+const ALBA_HOME = process.env.ALBA_HOME ?? join(homedir(), ".alba");
+const TRACES_FILE = join(ALBA_HOME, "traces.jsonl");
+export class Tracer {
+    /** @internal exposed for AgentRunner span lookup */
+    trace;
+    constructor(sessionId, prompt) {
+        this.trace = {
+            traceId: randomUUID().slice(0, 12),
+            sessionId,
+            prompt: prompt.slice(0, 200),
+            startMs: Date.now(),
+            spans: [],
+        };
+    }
+    /** Start a named span, returns spanId */
+    startSpan(name, attrs = {}) {
+        const spanId = randomUUID().slice(0, 8);
+        this.trace.spans.push({ spanId, name, startMs: Date.now(), status: "ok", attrs });
+        return spanId;
+    }
+    /** End a span by ID */
+    endSpan(spanId, status = "ok", attrs = {}) {
+        const span = this.trace.spans.find(s => s.spanId === spanId);
+        if (!span)
+            return;
+        span.durationMs = Date.now() - span.startMs;
+        span.status = status;
+        Object.assign(span.attrs, attrs);
+    }
+    /** Record model call details */
+    recordModel(spanId, model, promptTokens, completionTokens, costNano) {
+        this.endSpan(spanId, "ok", { model, promptTokens, completionTokens, costNano });
+        this.trace.modelUsed = model;
+        this.trace.totalCost = (this.trace.totalCost ?? 0) + costNano;
+    }
+    /** Flush trace to disk */
+    flush(status = "ok") {
+        this.trace.durationMs = Date.now() - this.trace.startMs;
+        try {
+            mkdirSync(ALBA_HOME, { recursive: true });
+            appendFileSync(TRACES_FILE, JSON.stringify({ ...this.trace, status, ts: Date.now() }) + "\n", "utf-8");
+        }
+        catch { /* best effort — tracing should never crash the agent */ }
+    }
+    get traceId() { return this.trace.traceId; }
+    // ── Static helpers ────────────────────────────────────────────────────────
+    /** Read last N traces from disk for /traces command */
+    static readRecent(limit = 5) {
+        try {
+            if (!existsSync(TRACES_FILE))
+                return [];
+            const lines = readFileSync(TRACES_FILE, "utf-8")
+                .trim().split("\n").filter(Boolean);
+            return lines.slice(-limit).map(l => JSON.parse(l)).reverse();
+        }
+        catch {
+            return [];
+        }
+    }
+    /** Format traces for REPL display */
+    static formatSummary(traces) {
+        if (traces.length === 0)
+            return "No traces recorded yet.";
+        return traces.map(t => {
+            const duration = t.durationMs ? `${(t.durationMs / 1000).toFixed(1)}s` : "?s";
+            const model = t.modelUsed?.split("/").pop()?.slice(0, 20) ?? "?";
+            const spans = t.spans.length;
+            const tools = t.spans.filter(s => s.name.startsWith("tool:")).length;
+            const cost = t.totalCost ? `$${(t.totalCost / 1_000_000_000).toFixed(4)}` : "?";
+            const prompt = t.prompt.slice(0, 60);
+            const errors = t.spans.filter(s => s.status === "error").length;
+            const lines = [
+                `[${t.traceId}] ${new Date(t.startMs).toLocaleTimeString()} — ${duration} · ${model} · ${cost}`,
+                `  Prompt: "${prompt}"`,
+                `  Spans: ${spans} total, ${tools} tool calls${errors > 0 ? `, ${errors} errors` : ""}`,
+            ];
+            // Show tool spans
+            for (const span of t.spans.filter(s => s.name.startsWith("tool:"))) {
+                const icon = span.status === "ok" ? "✓" : "✗";
+                const dur = span.durationMs ? `${span.durationMs}ms` : "?";
+                lines.push(`    ${icon} ${span.name.slice(5)} (${dur})`);
+            }
+            return lines.join("\n");
+        }).join("\n\n");
+    }
+}
+//# sourceMappingURL=Tracer.js.map

package/dist/tools/MarketSentiment.d.ts

@@ -0,0 +1,166 @@
+/**
+ * MarketSentiment — free, no-key market data tools.
+ *
+ * #20: Fear & Greed Index (alternative.me)
+ * #19: BTC Mempool stats (mempool.space — free, no key)
+ * #19: ETH / EVM Gas prices (blocknative public — free)
+ * #19: Solana TPS (public RPC — no key)
+ * #19: DeFi TVL by chain (DeFiLlama — free, no key)
+ * #20: Binance perp funding rates (public endpoint — no key)
+ */
+import { type Static } from "@sinclair/typebox";
+export declare const fearGreedParams: import("@sinclair/typebox").TObject<{
+    days: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TNumber>;
+}>;
+export declare function getFearGreedTool(_id: string, params: Static<typeof fearGreedParams>): Promise<{
+    content: {
+        type: "text";
+        text: string;
+    }[];
+    details: {
+        current: number;
+        classification: string;
+        avg7: number;
+        trend: number[];
+        direction: string;
+    };
+} | {
+    content: {
+        type: "text";
+        text: string;
+    }[];
+    details: {
+        current?: undefined;
+        classification?: undefined;
+        avg7?: undefined;
+        trend?: undefined;
+        direction?: undefined;
+    };
+}>;
+export declare const fundingRatesParams: import("@sinclair/typebox").TObject<{
+    symbol: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+    limit: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TNumber>;
+}>;
+export declare function getFundingRatesTool(_id: string, params: Static<typeof fundingRatesParams>): Promise<{
+    content: {
+        type: "text";
+        text: string;
+    }[];
+    details: {
+        symbol: string;
+        currentRate: number;
+        annualizedPct: number;
+        sentiment: string;
+        history: {
+            fundingRate: string;
+            fundingTime: number;
+        }[];
+    };
+} | {
+    content: {
+        type: "text";
+        text: string;
+    }[];
+    details: {
+        symbol?: undefined;
+        currentRate?: undefined;
+        annualizedPct?: undefined;
+        sentiment?: undefined;
+        history?: undefined;
+    };
+}>;
+export declare const btcMempoolParams: import("@sinclair/typebox").TObject<{}>;
+export declare function getBtcMempoolTool(): Promise<{
+    content: {
+        type: "text";
+        text: string;
+    }[];
+    details: {
+        pendingTxs: number;
+        vsizeMB: number;
+        fees: {
+            fastestFee: number;
+            halfHourFee: number;
+            hourFee: number;
+            economyFee: number;
+        };
+    };
+} | {
+    content: {
+        type: "text";
+        text: string;
+    }[];
+    details: {
+        pendingTxs?: undefined;
+        vsizeMB?: undefined;
+        fees?: undefined;
+    };
+}>;
+export declare const defiTvlParams: import("@sinclair/typebox").TObject<{
+    chain: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+}>;
+export declare function getDefiTvlTool(_id: string, params: Static<typeof defiTvlParams>): Promise<{
+    content: {
+        type: "text";
+        text: string;
+    }[];
+    details: {
+        chain: string;
+        tvl: number;
+        change7d: string | null;
+        chains?: undefined;
+        totalTvl?: undefined;
+    };
+} | {
+    content: {
+        type: "text";
+        text: string;
+    }[];
+    details: {
+        chains: {
+            name: string;
+            tvl: number;
+        }[];
+        totalTvl: number;
+        chain?: undefined;
+        tvl?: undefined;
+        change7d?: undefined;
+    };
+} | {
+    content: {
+        type: "text";
+        text: string;
+    }[];
+    details: {
+        chain?: undefined;
+        tvl?: undefined;
+        change7d?: undefined;
+        chains?: undefined;
+        totalTvl?: undefined;
+    };
+}>;
+export declare const solanaStatsParams: import("@sinclair/typebox").TObject<{}>;
+export declare function getSolanaStatsTool(): Promise<{
+    content: {
+        type: "text";
+        text: string;
+    }[];
+    details: {
+        avgTps: number;
+        maxTps: number;
+        latestSlot: number;
+        samples: number[];
+    };
+} | {
+    content: {
+        type: "text";
+        text: string;
+    }[];
+    details: {
+        avgTps?: undefined;
+        maxTps?: undefined;
+        latestSlot?: undefined;
+        samples?: undefined;
+    };
+}>;
+//# sourceMappingURL=MarketSentiment.d.ts.map