@snoglobe/helios 0.1.0

package/dist/core/orchestrator.js

@@ -0,0 +1,235 @@
+import { AgentStateMachine } from "./state-machine.js";
+import { SessionStore } from "../store/session-store.js";
+import { savePreferences } from "../store/preferences.js";
+export class Orchestrator {
+    providers = new Map();
+    activeProvider = null;
+    activeSession = null;
+    tools = [];
+    _totalCostUsd = 0;
+    _lastInputTokens = 0;
+    _contextGate = null;
+    _stickyManager = null;
+    stateMachine = new AgentStateMachine();
+    sessionStore = new SessionStore();
+    config;
+    constructor(config) {
+        this.config = config;
+    }
+    registerProvider(provider) {
+        this.providers.set(provider.name, provider);
+    }
+    registerTool(tool) {
+        this.tools.push(tool);
+    }
+    registerTools(tools) {
+        this.tools.push(...tools);
+    }
+    setContextGate(gate) {
+        this._contextGate = gate;
+    }
+    get contextGate() {
+        return this._contextGate;
+    }
+    setStickyManager(manager) {
+        this._stickyManager = manager;
+    }
+    getTools() {
+        return this.tools;
+    }
+    getProvider(name) {
+        if (name)
+            return this.providers.get(name) ?? null;
+        return this.activeProvider;
+    }
+    async switchProvider(name) {
+        const provider = this.providers.get(name);
+        if (!provider)
+            throw new Error(`Provider "${name}" not registered`);
+        // Clean up old session before switching
+        if (this.activeSession && this.activeProvider) {
+            await this.activeProvider.closeSession(this.activeSession).catch(() => { });
+            this.activeSession = null;
+        }
+        await provider.authenticate();
+        this.activeProvider = provider;
+        savePreferences({ lastProvider: name });
+    }
+    async ensureSession() {
+        if (this.activeSession)
+            return this.activeSession;
+        return this.startSession();
+    }
+    async startSession(config) {
+        if (!this.activeProvider) {
+            await this.switchProvider(this.config.defaultProvider);
+        }
+        const sessionConfig = {
+            systemPrompt: this.config.systemPrompt,
+            ...config,
+        };
+        const session = await this.activeProvider.createSession(sessionConfig);
+        this.activeSession = session;
+        // Bind memory store to this session
+        if (this._contextGate) {
+            this._contextGate.onSessionStart(session.id);
+        }
+        if (this.stateMachine.state === "idle") {
+            this.stateMachine.transition("active", "Session started");
+        }
+        return session;
+    }
+    async resumeSession(sessionId) {
+        const stored = this.sessionStore.getSession(sessionId);
+        if (!stored)
+            throw new Error(`Session "${sessionId}" not found`);
+        // Ensure the correct provider is active
+        const providerName = stored.providerId;
+        if (!this.activeProvider || this.activeProvider.name !== providerName) {
+            await this.switchProvider(providerName);
+        }
+        // Ask the provider to resume its side (re-hydrate conversation history etc.)
+        const session = await this.activeProvider.resumeSession(stored.id);
+        this.activeSession = session;
+        if (this.stateMachine.state === "idle") {
+            this.stateMachine.transition("active", "Session resumed");
+        }
+        return session;
+    }
+    async *send(message) {
+        if (!this.activeProvider) {
+            await this.switchProvider(this.config.defaultProvider);
+        }
+        const session = await this.ensureSession();
+        this.sessionStore.updateLastActive(session.id);
+        this.sessionStore.addMessage(session.id, "user", message);
+        // Prepend sticky notes to the message so the model always sees them
+        let augmentedMessage = message;
+        if (this._stickyManager) {
+            const stickies = this._stickyManager.formatForModel();
+            if (stickies) {
+                augmentedMessage = stickies + "\n\n---\n\n" + message;
+            }
+        }
+        let fullResponse = "";
+        for await (const event of this.activeProvider.send(session, augmentedMessage, this.tools)) {
+            if (event.type === "text" && event.delta) {
+                fullResponse += event.delta;
+            }
+            if (event.type === "done") {
+                if (event.usage?.costUsd) {
+                    this._totalCostUsd += event.usage.costUsd;
+                }
+                if (event.usage?.inputTokens) {
+                    this._lastInputTokens = event.usage.inputTokens;
+                }
+            }
+            yield event;
+        }
+        // Check if context window is filling up — trigger checkpoint if needed
+        yield* this.maybeCheckpoint(session);
+        if (fullResponse) {
+            this.sessionStore.addMessage(session.id, "assistant", fullResponse);
+        }
+    }
+    interrupt() {
+        if (this.activeProvider && this.activeSession) {
+            this.activeProvider.interrupt(this.activeSession);
+        }
+    }
+    get currentSession() {
+        return this.activeSession;
+    }
+    get currentProvider() {
+        return this.activeProvider;
+    }
+    get currentState() {
+        return this.stateMachine.state;
+    }
+    get totalCostUsd() {
+        return this._totalCostUsd;
+    }
+    get currentModel() {
+        return this.activeProvider?.currentModel ?? null;
+    }
+    async setModel(model) {
+        if (!this.activeProvider) {
+            await this.switchProvider(this.config.defaultProvider);
+        }
+        this.activeProvider.currentModel = model;
+        // Reset session so next message uses the new model
+        if (this.activeSession) {
+            await this.activeProvider.closeSession(this.activeSession);
+            this.activeSession = null;
+        }
+    }
+    async fetchModels() {
+        if (!this.activeProvider) {
+            await this.switchProvider(this.config.defaultProvider);
+        }
+        if (this.activeProvider.fetchModels) {
+            return this.activeProvider.fetchModels();
+        }
+        // Return current model as the only option
+        return [{ id: this.activeProvider.currentModel, name: this.activeProvider.currentModel }];
+    }
+    get reasoningEffort() {
+        return this.activeProvider?.reasoningEffort ?? null;
+    }
+    async setReasoningEffort(effort) {
+        if (!this.activeProvider) {
+            await this.switchProvider(this.config.defaultProvider);
+        }
+        this.activeProvider.reasoningEffort = effort;
+    }
+    /** Last input token count reported by the provider (for context budget tracking). */
+    get lastInputTokens() {
+        return this._lastInputTokens;
+    }
+    async *maybeCheckpoint(session) {
+        if (!this._contextGate || !this.activeProvider)
+            return;
+        const model = this.activeProvider.currentModel;
+        const threshold = this._contextGate.checkThreshold(model, this._lastInputTokens);
+        if (!threshold)
+            return;
+        // Ask the model to write a gist of the conversation before we wipe it
+        const gist = await this.generateCheckpointGist(session);
+        // Save gist to memory and build briefing
+        const briefing = this._contextGate.performCheckpointWithGist(gist);
+        // Reset provider history with the briefing
+        this.activeProvider.resetHistory(session, briefing);
+        this._lastInputTokens = 0;
+        yield {
+            type: "text",
+            text: "\n\n---\n*[Context checkpoint — conversation archived, continuing from memory]*\n\n",
+            delta: "\n\n---\n*[Context checkpoint — conversation archived, continuing from memory]*\n\n",
+        };
+    }
+    async generateCheckpointGist(session) {
+        const provider = this.activeProvider;
+        let gist = "";
+        try {
+            for await (const event of provider.send(session, CHECKPOINT_GIST_PROMPT, [])) {
+                if (event.type === "text" && event.delta) {
+                    gist += event.delta;
+                }
+            }
+        }
+        catch {
+            // If gist generation fails, continue with empty gist
+            gist = "(gist generation failed)";
+        }
+        return gist;
+    }
+}
+const CHECKPOINT_GIST_PROMPT = `SYSTEM: Your conversation context is about to be archived because it's getting too long. You'll be resumed with your memory tree and this gist.
+
+Write a concise gist covering:
+1. **Goal**: What you're trying to achieve
+2. **Status**: Where you are right now — what's running, what just finished, what the latest results are
+3. **Plan**: What you were about to do next, and why
+4. **Key context**: Anything critical that isn't already in your memory tree (observations not yet saved, hunches, dead ends to avoid)
+
+Be direct and dense. This is a note to yourself.`;
+//# sourceMappingURL=orchestrator.js.map

package/dist/core/orchestrator.js.map

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

package/dist/core/state-machine.d.ts

@@ -0,0 +1,19 @@
+export type AgentState = "idle" | "active" | "sleeping" | "waiting" | "error";
+export interface StateTransition {
+    from: AgentState;
+    to: AgentState;
+    reason: string;
+    timestamp: number;
+}
+type StateListener = (state: AgentState, transition: StateTransition) => void;
+export declare class AgentStateMachine {
+    private _state;
+    private _history;
+    private _listeners;
+    get state(): AgentState;
+    get history(): readonly StateTransition[];
+    transition(to: AgentState, reason: string): void;
+    onTransition(listener: StateListener): () => void;
+}
+export {};
+//# sourceMappingURL=state-machine.d.ts.map

package/dist/core/state-machine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"state-machine.d.ts","sourceRoot":"","sources":["../../src/core/state-machine.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,UAAU,GAAG,MAAM,GAAG,QAAQ,GAAG,UAAU,GAAG,SAAS,GAAG,OAAO,CAAC;AAE9E,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,UAAU,CAAC;IACjB,EAAE,EAAE,UAAU,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,KAAK,aAAa,GAAG,CACnB,KAAK,EAAE,UAAU,EACjB,UAAU,EAAE,eAAe,KACxB,IAAI,CAAC;AAUV,qBAAa,iBAAiB;IAC5B,OAAO,CAAC,MAAM,CAAsB;IACpC,OAAO,CAAC,QAAQ,CAAyB;IACzC,OAAO,CAAC,UAAU,CAAuB;IAEzC,IAAI,KAAK,IAAI,UAAU,CAEtB;IAED,IAAI,OAAO,IAAI,SAAS,eAAe,EAAE,CAExC;IAED,UAAU,CAAC,EAAE,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI;IAuBhD,YAAY,CAAC,QAAQ,EAAE,aAAa,GAAG,MAAM,IAAI;CAMlD"}

package/dist/core/state-machine.js

@@ -0,0 +1,42 @@
+const VALID_TRANSITIONS = {
+    idle: ["active"],
+    active: ["idle", "sleeping", "waiting", "error"],
+    sleeping: ["active", "error"],
+    waiting: ["active", "error"],
+    error: ["idle", "active"],
+};
+export class AgentStateMachine {
+    _state = "idle";
+    _history = [];
+    _listeners = [];
+    get state() {
+        return this._state;
+    }
+    get history() {
+        return this._history;
+    }
+    transition(to, reason) {
+        const valid = VALID_TRANSITIONS[this._state];
+        if (!valid.includes(to)) {
+            throw new Error(`Invalid state transition: ${this._state} → ${to}`);
+        }
+        const transition = {
+            from: this._state,
+            to,
+            reason,
+            timestamp: Date.now(),
+        };
+        this._state = to;
+        this._history.push(transition);
+        for (const listener of this._listeners) {
+            listener(to, transition);
+        }
+    }
+    onTransition(listener) {
+        this._listeners.push(listener);
+        return () => {
+            this._listeners = this._listeners.filter((l) => l !== listener);
+        };
+    }
+}
+//# sourceMappingURL=state-machine.js.map

package/dist/core/state-machine.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"state-machine.js","sourceRoot":"","sources":["../../src/core/state-machine.ts"],"names":[],"mappings":"AAcA,MAAM,iBAAiB,GAAqC;IAC1D,IAAI,EAAE,CAAC,QAAQ,CAAC;IAChB,MAAM,EAAE,CAAC,MAAM,EAAE,UAAU,EAAE,SAAS,EAAE,OAAO,CAAC;IAChD,QAAQ,EAAE,CAAC,QAAQ,EAAE,OAAO,CAAC;IAC7B,OAAO,EAAE,CAAC,QAAQ,EAAE,OAAO,CAAC;IAC5B,KAAK,EAAE,CAAC,MAAM,EAAE,QAAQ,CAAC;CAC1B,CAAC;AAEF,MAAM,OAAO,iBAAiB;IACpB,MAAM,GAAe,MAAM,CAAC;IAC5B,QAAQ,GAAsB,EAAE,CAAC;IACjC,UAAU,GAAoB,EAAE,CAAC;IAEzC,IAAI,KAAK;QACP,OAAO,IAAI,CAAC,MAAM,CAAC;IACrB,CAAC;IAED,IAAI,OAAO;QACT,OAAO,IAAI,CAAC,QAAQ,CAAC;IACvB,CAAC;IAED,UAAU,CAAC,EAAc,EAAE,MAAc;QACvC,MAAM,KAAK,GAAG,iBAAiB,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;QAC7C,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,EAAE,CAAC,EAAE,CAAC;YACxB,MAAM,IAAI,KAAK,CACb,6BAA6B,IAAI,CAAC,MAAM,MAAM,EAAE,EAAE,CACnD,CAAC;QACJ,CAAC;QAED,MAAM,UAAU,GAAoB;YAClC,IAAI,EAAE,IAAI,CAAC,MAAM;YACjB,EAAE;YACF,MAAM;YACN,SAAS,EAAE,IAAI,CAAC,GAAG,EAAE;SACtB,CAAC;QAEF,IAAI,CAAC,MAAM,GAAG,EAAE,CAAC;QACjB,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;QAE/B,KAAK,MAAM,QAAQ,IAAI,IAAI,CAAC,UAAU,EAAE,CAAC;YACvC,QAAQ,CAAC,EAAE,EAAE,UAAU,CAAC,CAAC;QAC3B,CAAC;IACH,CAAC;IAED,YAAY,CAAC,QAAuB;QAClC,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;QAC/B,OAAO,GAAG,EAAE;YACV,IAAI,CAAC,UAAU,GAAG,IAAI,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,KAAK,QAAQ,CAAC,CAAC;QAClE,CAAC,CAAC;IACJ,CAAC;CACF"}

package/dist/core/stickies.d.ts

@@ -0,0 +1,20 @@
+export interface StickyNote {
+    num: number;
+    text: string;
+    createdAt: number;
+}
+/**
+ * Manages sticky notes — persistent reminders injected into every model turn.
+ * Notes are numbered starting from 1.
+ */
+export declare class StickyManager {
+    private notes;
+    private nextNum;
+    add(text: string): StickyNote;
+    remove(num: number): boolean;
+    list(): StickyNote[];
+    count(): number;
+    /** Format sticky notes for injection into the model's context. */
+    formatForModel(): string | null;
+}
+//# sourceMappingURL=stickies.d.ts.map

package/dist/core/stickies.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stickies.d.ts","sourceRoot":"","sources":["../../src/core/stickies.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,UAAU;IACzB,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;;GAGG;AACH,qBAAa,aAAa;IACxB,OAAO,CAAC,KAAK,CAAoB;IACjC,OAAO,CAAC,OAAO,CAAK;IAEpB,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,UAAU;IAU7B,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO;IAO5B,IAAI,IAAI,UAAU,EAAE;IAIpB,KAAK,IAAI,MAAM;IAIf,kEAAkE;IAClE,cAAc,IAAI,MAAM,GAAG,IAAI;CAYhC"}

package/dist/core/stickies.js

@@ -0,0 +1,41 @@
+/**
+ * Manages sticky notes — persistent reminders injected into every model turn.
+ * Notes are numbered starting from 1.
+ */
+export class StickyManager {
+    notes = [];
+    nextNum = 1;
+    add(text) {
+        const note = {
+            num: this.nextNum++,
+            text,
+            createdAt: Date.now(),
+        };
+        this.notes.push(note);
+        return note;
+    }
+    remove(num) {
+        const idx = this.notes.findIndex((n) => n.num === num);
+        if (idx === -1)
+            return false;
+        this.notes.splice(idx, 1);
+        return true;
+    }
+    list() {
+        return [...this.notes];
+    }
+    count() {
+        return this.notes.length;
+    }
+    /** Format sticky notes for injection into the model's context. */
+    formatForModel() {
+        if (this.notes.length === 0)
+            return null;
+        const lines = this.notes.map((n) => `  [${n.num}] ${n.text}`);
+        return [
+            "⚠️ STICKY NOTES — The user has pinned the following reminders. Keep these at the forefront of your thinking at ALL times:",
+            ...lines,
+        ].join("\n");
+    }
+}
+//# sourceMappingURL=stickies.js.map

package/dist/core/stickies.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stickies.js","sourceRoot":"","sources":["../../src/core/stickies.ts"],"names":[],"mappings":"AAMA;;;GAGG;AACH,MAAM,OAAO,aAAa;IAChB,KAAK,GAAiB,EAAE,CAAC;IACzB,OAAO,GAAG,CAAC,CAAC;IAEpB,GAAG,CAAC,IAAY;QACd,MAAM,IAAI,GAAe;YACvB,GAAG,EAAE,IAAI,CAAC,OAAO,EAAE;YACnB,IAAI;YACJ,SAAS,EAAE,IAAI,CAAC,GAAG,EAAE;SACtB,CAAC;QACF,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACtB,OAAO,IAAI,CAAC;IACd,CAAC;IAED,MAAM,CAAC,GAAW;QAChB,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,GAAG,KAAK,GAAG,CAAC,CAAC;QACvD,IAAI,GAAG,KAAK,CAAC,CAAC;YAAE,OAAO,KAAK,CAAC;QAC7B,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC;QAC1B,OAAO,IAAI,CAAC;IACd,CAAC;IAED,IAAI;QACF,OAAO,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC;IACzB,CAAC;IAED,KAAK;QACH,OAAO,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC;IAC3B,CAAC;IAED,kEAAkE;IAClE,cAAc;QACZ,IAAI,IAAI,CAAC,KAAK,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO,IAAI,CAAC;QAEzC,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAC1B,CAAC,CAAC,EAAE,EAAE,CAAC,MAAM,CAAC,CAAC,GAAG,KAAK,CAAC,CAAC,IAAI,EAAE,CAChC,CAAC;QAEF,OAAO;YACL,2HAA2H;YAC3H,GAAG,KAAK;SACT,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACf,CAAC;CACF"}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.tsx"],"names":[],"mappings":""}

package/dist/index.js

@@ -0,0 +1,68 @@
+#!/usr/bin/env node
+import { jsx as _jsx } from "react/jsx-runtime";
+import { withFullScreen } from "fullscreen-ink";
+import { App } from "./app.js";
+import { createMouseFilter } from "./ui/mouse-filter.js";
+import { VERSION } from "./version.js";
+// Parse CLI args
+const args = process.argv.slice(2);
+let providerArg;
+let claudeModeArg;
+for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if ((arg === "--provider" || arg === "-p") && args[i + 1]) {
+        const p = args[i + 1];
+        if (p === "claude" || p === "openai") {
+            providerArg = p;
+        }
+        else {
+            console.error(`Unknown provider: ${p}. Use "claude" or "openai".`);
+            process.exit(1);
+        }
+        i++;
+    }
+    else if (arg === "--claude-mode" && args[i + 1]) {
+        const m = args[i + 1];
+        if (m === "cli" || m === "api") {
+            claudeModeArg = m;
+        }
+        else {
+            console.error(`Unknown claude mode: ${m}. Use "cli" or "api".`);
+            process.exit(1);
+        }
+        i++;
+    }
+    else if (arg === "--version" || arg === "-v" || arg === "-V") {
+        console.log(`helios ${VERSION}`);
+        process.exit(0);
+    }
+    else if (arg === "--help" || arg === "-h") {
+        console.log(`
+Helios ${VERSION} - Autonomous ML Research Agent
+
+Usage: helios [options]
+
+Options:
+  -p, --provider <claude|openai>  Model provider (default: claude)
+  --claude-mode <cli|api>         Force Claude auth mode (cli = Agent SDK, api = API key)
+  -v, --version                   Show version
+  -h, --help                      Show this help
+
+Environment:
+  ANTHROPIC_API_KEY  Claude API key (for Claude provider with API key auth)
+
+Auth:
+  Claude: Install \`claude\` CLI and run \`claude login\`, or set ANTHROPIC_API_KEY
+  OpenAI: OAuth login via ChatGPT Plus/Pro on first run
+`);
+        process.exit(0);
+    }
+}
+// Filter mouse escape sequences from stdin before Ink sees them
+const { filteredStdin, mouseEmitter } = createMouseFilter(process.stdin);
+// fullscreen-ink handles alternate screen buffer + cursor hiding
+const { start, waitUntilExit } = withFullScreen(_jsx(App, { defaultProvider: providerArg, claudeMode: claudeModeArg, mouseEmitter: mouseEmitter }), { exitOnCtrlC: false, stdin: filteredStdin });
+await start();
+await waitUntilExit();
+process.exit(0);
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.tsx"],"names":[],"mappings":";;AAGA,OAAO,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAChD,OAAO,EAAE,GAAG,EAAE,MAAM,UAAU,CAAC;AAC/B,OAAO,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AACzD,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAEvC,iBAAiB;AACjB,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;AACnC,IAAI,WAA4C,CAAC;AACjD,IAAI,aAAwC,CAAC;AAE7C,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;IACrC,MAAM,GAAG,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC;IACpB,IAAI,CAAC,GAAG,KAAK,YAAY,IAAI,GAAG,KAAK,IAAI,CAAC,IAAI,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC;QAC1D,MAAM,CAAC,GAAG,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;QACtB,IAAI,CAAC,KAAK,QAAQ,IAAI,CAAC,KAAK,QAAQ,EAAE,CAAC;YACrC,WAAW,GAAG,CAAC,CAAC;QAClB,CAAC;aAAM,CAAC;YACN,OAAO,CAAC,KAAK,CAAC,qBAAqB,CAAC,6BAA6B,CAAC,CAAC;YACnE,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QAClB,CAAC;QACD,CAAC,EAAE,CAAC;IACN,CAAC;SAAM,IAAI,GAAG,KAAK,eAAe,IAAI,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC;QAClD,MAAM,CAAC,GAAG,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;QACtB,IAAI,CAAC,KAAK,KAAK,IAAI,CAAC,KAAK,KAAK,EAAE,CAAC;YAC/B,aAAa,GAAG,CAAC,CAAC;QACpB,CAAC;aAAM,CAAC;YACN,OAAO,CAAC,KAAK,CAAC,wBAAwB,CAAC,uBAAuB,CAAC,CAAC;YAChE,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QAClB,CAAC;QACD,CAAC,EAAE,CAAC;IACN,CAAC;SAAM,IAAI,GAAG,KAAK,WAAW,IAAI,GAAG,KAAK,IAAI,IAAI,GAAG,KAAK,IAAI,EAAE,CAAC;QAC/D,OAAO,CAAC,GAAG,CAAC,UAAU,OAAO,EAAE,CAAC,CAAC;QACjC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC;SAAM,IAAI,GAAG,KAAK,QAAQ,IAAI,GAAG,KAAK,IAAI,EAAE,CAAC;QAC5C,OAAO,CAAC,GAAG,CAAC;SACP,OAAO;;;;;;;;;;;;;;;;CAgBf,CAAC,CAAC;QACC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC;AACH,CAAC;AAED,gEAAgE;AAChE,MAAM,EAAE,aAAa,EAAE,YAAY,EAAE,GAAG,iBAAiB,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;AAEzE,iEAAiE;AACjE,MAAM,EAAE,KAAK,EAAE,aAAa,EAAE,GAAG,cAAc,CAC7C,KAAC,GAAG,IAAC,eAAe,EAAE,WAAW,EAAE,UAAU,EAAE,aAAa,EAAE,YAAY,EAAE,YAAY,GAAI,EAC5F,EAAE,WAAW,EAAE,KAAK,EAAE,KAAK,EAAE,aAAoB,EAAE,CACpD,CAAC;AAEF,MAAM,KAAK,EAAE,CAAC;AACd,MAAM,aAAa,EAAE,CAAC;AACtB,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC"}

package/dist/memory/context-gate.d.ts

@@ -0,0 +1,49 @@
+import type { MemoryStore } from "./memory-store.js";
+import type { RemoteExecutor } from "../remote/executor.js";
+import type { MetricStore } from "../metrics/store.js";
+export interface ContextGateConfig {
+    /** Override checkpoint threshold (for testing). */
+    thresholdOverride?: number;
+}
+/**
+ * ContextGate monitors token usage and triggers checkpoints when
+ * the context window is filling up.
+ *
+ * Uses actual input_tokens from the API response (reported in DoneEvent.usage)
+ * rather than re-estimating from history text.
+ *
+ * On checkpoint:
+ * 1. Save active tasks + latest metrics to memory
+ * 2. Build a briefing from the memory tree
+ * 3. Orchestrator resets provider history with the briefing
+ */
+export declare class ContextGate {
+    private memory;
+    private executor;
+    private metricStore;
+    private config;
+    constructor(memory: MemoryStore, config?: ContextGateConfig);
+    /** Update the memory store's session ID when a new session starts. */
+    onSessionStart(sessionId: string): void;
+    setExecutor(executor: RemoteExecutor): void;
+    setMetricStore(store: MetricStore): void;
+    /**
+     * Check if actual input token count exceeds checkpoint threshold.
+     * Called by Orchestrator after each send() completes.
+     */
+    checkThreshold(model: string, inputTokens: number): boolean;
+    /**
+     * Perform a checkpoint with a model-generated gist.
+     * Saves active state + gist to memory, returns the briefing.
+     */
+    performCheckpointWithGist(gist: string): string;
+    /**
+     * Perform a checkpoint without a gist (fallback).
+     */
+    performCheckpointFromOrchestrator(): string;
+    private saveActiveTasks;
+    /** Build a checkpoint briefing string from the memory tree + optional gist. */
+    buildBriefing(gist: string | null): string;
+    private getLatestMetrics;
+}
+//# sourceMappingURL=context-gate.d.ts.map

package/dist/memory/context-gate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context-gate.d.ts","sourceRoot":"","sources":["../../src/memory/context-gate.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AACrD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAC5D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAEvD,MAAM,WAAW,iBAAiB;IAChC,mDAAmD;IACnD,iBAAiB,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED;;;;;;;;;;;GAWG;AACH,qBAAa,WAAW;IACtB,OAAO,CAAC,MAAM,CAAc;IAC5B,OAAO,CAAC,QAAQ,CAA+B;IAC/C,OAAO,CAAC,WAAW,CAA4B;IAC/C,OAAO,CAAC,MAAM,CAAoB;gBAEtB,MAAM,EAAE,WAAW,EAAE,MAAM,GAAE,iBAAsB;IAK/D,sEAAsE;IACtE,cAAc,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI;IAIvC,WAAW,CAAC,QAAQ,EAAE,cAAc,GAAG,IAAI;IAI3C,cAAc,CAAC,KAAK,EAAE,WAAW,GAAG,IAAI;IAIxC;;;OAGG;IACH,cAAc,CAAC,KAAK,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,OAAO;IAO3D;;;OAGG;IACH,yBAAyB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM;IAc/C;;OAEG;IACH,iCAAiC,IAAI,MAAM;IAK3C,OAAO,CAAC,eAAe;IAuBvB,+EAA+E;IAC/E,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,GAAG,MAAM;IA2B1C,OAAO,CAAC,gBAAgB;CAiBzB"}

package/dist/memory/context-gate.js

@@ -0,0 +1,109 @@
+import { getCheckpointThreshold } from "./token-estimator.js";
+/**
+ * ContextGate monitors token usage and triggers checkpoints when
+ * the context window is filling up.
+ *
+ * Uses actual input_tokens from the API response (reported in DoneEvent.usage)
+ * rather than re-estimating from history text.
+ *
+ * On checkpoint:
+ * 1. Save active tasks + latest metrics to memory
+ * 2. Build a briefing from the memory tree
+ * 3. Orchestrator resets provider history with the briefing
+ */
+export class ContextGate {
+    memory;
+    executor = null;
+    metricStore = null;
+    config;
+    constructor(memory, config = {}) {
+        this.memory = memory;
+        this.config = config;
+    }
+    /** Update the memory store's session ID when a new session starts. */
+    onSessionStart(sessionId) {
+        this.memory.setSession(sessionId);
+    }
+    setExecutor(executor) {
+        this.executor = executor;
+    }
+    setMetricStore(store) {
+        this.metricStore = store;
+    }
+    /**
+     * Check if actual input token count exceeds checkpoint threshold.
+     * Called by Orchestrator after each send() completes.
+     */
+    checkThreshold(model, inputTokens) {
+        if (inputTokens === 0)
+            return false;
+        const threshold = this.config.thresholdOverride ?? getCheckpointThreshold(model);
+        return inputTokens >= threshold;
+    }
+    /**
+     * Perform a checkpoint with a model-generated gist.
+     * Saves active state + gist to memory, returns the briefing.
+     */
+    performCheckpointWithGist(gist) {
+        // Save the model's gist
+        this.memory.write("/context/gist", "Model-generated summary of conversation before checkpoint", gist);
+        // Save active tasks to /context/active-tasks
+        this.saveActiveTasks();
+        return this.buildBriefing(gist);
+    }
+    /**
+     * Perform a checkpoint without a gist (fallback).
+     */
+    performCheckpointFromOrchestrator() {
+        this.saveActiveTasks();
+        return this.buildBriefing(null);
+    }
+    saveActiveTasks() {
+        if (!this.executor)
+            return;
+        const tasks = this.executor.getBackgroundProcesses();
+        if (tasks.length === 0)
+            return;
+        const taskLines = tasks.map((t) => {
+            const latestMetrics = this.getLatestMetrics(t.machineId, t.pid);
+            return [
+                `${t.machineId}:${t.pid} — ${t.command.slice(0, 80)}`,
+                latestMetrics ? `  metrics: ${latestMetrics}` : null,
+            ]
+                .filter(Boolean)
+                .join("\n");
+        });
+        this.memory.write("/context/active-tasks", `${tasks.length} running task(s)`, taskLines.join("\n\n"));
+    }
+    /** Build a checkpoint briefing string from the memory tree + optional gist. */
+    buildBriefing(gist) {
+        const tree = this.memory.formatTree("/");
+        const parts = [
+            "=== CONTEXT CHECKPOINT ===",
+            "You are Helios, continuing an autonomous ML research session.",
+            "Your previous conversation has been archived.",
+        ];
+        if (gist) {
+            parts.push("\n## Your gist (written by you before the checkpoint):\n", gist);
+        }
+        parts.push("\n## Memory tree:\n", tree, "\nUse memory_read(path) for details on any item above.", "Use memory_write to store new findings as you work.", "Continue working toward your goal.");
+        return parts.join("\n");
+    }
+    getLatestMetrics(machineId, pid) {
+        if (!this.metricStore)
+            return null;
+        const taskId = `${machineId}:${pid}`;
+        const names = this.metricStore.getMetricNames(taskId);
+        if (names.length === 0)
+            return null;
+        const parts = [];
+        for (const name of names.slice(0, 5)) {
+            const series = this.metricStore.getSeries(taskId, name, 1);
+            if (series.length > 0) {
+                parts.push(`${name}=${series[0].value}`);
+            }
+        }
+        return parts.length > 0 ? parts.join(", ") : null;
+    }
+}
+//# sourceMappingURL=context-gate.js.map

package/dist/memory/context-gate.js.map

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