@neotx/core 0.1.0-alpha.2 → 0.1.0-alpha.4

package/dist/index.d.ts

@@ -86,14 +86,21 @@ declare const mcpServerConfigSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     args: z.ZodOptional<z.ZodArray<z.ZodString>>;
     env: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
 }, z.core.$strip>], "type">;
+declare const gitStrategySchema: z.ZodDefault<z.ZodEnum<{
+    pr: "pr";
+    branch: "branch";
+}>>;
+type GitStrategy = z.infer<typeof gitStrategySchema>;
 declare const repoConfigSchema: z.ZodObject<{
     path: z.ZodString;
     name: z.ZodOptional<z.ZodString>;
     defaultBranch: z.ZodDefault<z.ZodString>;
     branchPrefix: z.ZodDefault<z.ZodString>;
     pushRemote: z.ZodDefault<z.ZodString>;
-    autoCreatePr: z.ZodDefault<z.ZodBoolean>;
-    prBaseBranch: z.ZodOptional<z.ZodString>;
+    gitStrategy: z.ZodDefault<z.ZodEnum<{
+        pr: "pr";
+        branch: "branch";
+    }>>;
 }, z.core.$strip>;
 declare const globalConfigSchema: z.ZodObject<{
     repos: z.ZodDefault<z.ZodArray<z.ZodObject<{
@@ -102,8 +109,10 @@ declare const globalConfigSchema: z.ZodObject<{
         defaultBranch: z.ZodDefault<z.ZodString>;
         branchPrefix: z.ZodDefault<z.ZodString>;
         pushRemote: z.ZodDefault<z.ZodString>;
-        autoCreatePr: z.ZodDefault<z.ZodBoolean>;
-        prBaseBranch: z.ZodOptional<z.ZodString>;
+        gitStrategy: z.ZodDefault<z.ZodEnum<{
+            pr: "pr";
+            branch: "branch";
+        }>>;
     }, z.core.$strip>>>;
     concurrency: z.ZodDefault<z.ZodObject<{
         maxSessions: z.ZodDefault<z.ZodNumber>;
@@ -121,6 +130,7 @@ declare const globalConfigSchema: z.ZodObject<{
     sessions: z.ZodDefault<z.ZodObject<{
         initTimeoutMs: z.ZodDefault<z.ZodNumber>;
         maxDurationMs: z.ZodDefault<z.ZodNumber>;
+        dir: z.ZodDefault<z.ZodString>;
     }, z.core.$strip>>;
     webhooks: z.ZodDefault<z.ZodArray<z.ZodObject<{
         url: z.ZodString;
@@ -131,14 +141,18 @@ declare const globalConfigSchema: z.ZodObject<{
     supervisor: z.ZodDefault<z.ZodObject<{
         port: z.ZodDefault<z.ZodNumber>;
         secret: z.ZodOptional<z.ZodString>;
-        idleIntervalMs: z.ZodDefault<z.ZodNumber>;
-        idleSkipMax: z.ZodDefault<z.ZodNumber>;
         heartbeatTimeoutMs: z.ZodDefault<z.ZodNumber>;
         maxConsecutiveFailures: z.ZodDefault<z.ZodNumber>;
         maxEventsPerSec: z.ZodDefault<z.ZodNumber>;
         dailyCapUsd: z.ZodDefault<z.ZodNumber>;
+        consolidationIntervalMs: z.ZodDefault<z.ZodNumber>;
+        compactionIntervalMs: z.ZodDefault<z.ZodNumber>;
+        eventTimeoutMs: z.ZodDefault<z.ZodNumber>;
         instructions: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>>;
+    memory: z.ZodDefault<z.ZodObject<{
+        embeddings: z.ZodDefault<z.ZodBoolean>;
+    }, z.core.$strip>>;
     mcpServers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodDiscriminatedUnion<[z.ZodObject<{
         type: z.ZodLiteral<"http">;
         url: z.ZodString;
@@ -166,8 +180,10 @@ declare const neoConfigSchema: z.ZodObject<{
         defaultBranch: z.ZodDefault<z.ZodString>;
         branchPrefix: z.ZodDefault<z.ZodString>;
         pushRemote: z.ZodDefault<z.ZodString>;
-        autoCreatePr: z.ZodDefault<z.ZodBoolean>;
-        prBaseBranch: z.ZodOptional<z.ZodString>;
+        gitStrategy: z.ZodDefault<z.ZodEnum<{
+            pr: "pr";
+            branch: "branch";
+        }>>;
     }, z.core.$strip>>>;
     concurrency: z.ZodDefault<z.ZodObject<{
         maxSessions: z.ZodDefault<z.ZodNumber>;
@@ -185,6 +201,7 @@ declare const neoConfigSchema: z.ZodObject<{
     sessions: z.ZodDefault<z.ZodObject<{
         initTimeoutMs: z.ZodDefault<z.ZodNumber>;
         maxDurationMs: z.ZodDefault<z.ZodNumber>;
+        dir: z.ZodDefault<z.ZodString>;
     }, z.core.$strip>>;
     webhooks: z.ZodDefault<z.ZodArray<z.ZodObject<{
         url: z.ZodString;
@@ -195,14 +212,18 @@ declare const neoConfigSchema: z.ZodObject<{
     supervisor: z.ZodDefault<z.ZodObject<{
         port: z.ZodDefault<z.ZodNumber>;
         secret: z.ZodOptional<z.ZodString>;
-        idleIntervalMs: z.ZodDefault<z.ZodNumber>;
-        idleSkipMax: z.ZodDefault<z.ZodNumber>;
         heartbeatTimeoutMs: z.ZodDefault<z.ZodNumber>;
         maxConsecutiveFailures: z.ZodDefault<z.ZodNumber>;
         maxEventsPerSec: z.ZodDefault<z.ZodNumber>;
         dailyCapUsd: z.ZodDefault<z.ZodNumber>;
+        consolidationIntervalMs: z.ZodDefault<z.ZodNumber>;
+        compactionIntervalMs: z.ZodDefault<z.ZodNumber>;
+        eventTimeoutMs: z.ZodDefault<z.ZodNumber>;
         instructions: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>>;
+    memory: z.ZodDefault<z.ZodObject<{
+        embeddings: z.ZodDefault<z.ZodBoolean>;
+    }, z.core.$strip>>;
     mcpServers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodDiscriminatedUnion<[z.ZodObject<{
         type: z.ZodLiteral<"http">;
         url: z.ZodString;
@@ -255,6 +276,7 @@ interface AgentDefinition {
     prompt: string;
     tools: string[];
     model: string;
+    mcpServers?: string[] | undefined;
 }
 interface ResolvedAgent {
     name: string;
@@ -295,7 +317,7 @@ interface PersistedRun {
     repo: string;
     prompt: string;
     branch?: string | undefined;
-    worktreePath?: string | undefined;
+    sessionPath?: string | undefined;
     pid?: number | undefined;
     status: "running" | "paused" | "completed" | "failed";
     steps: Record<string, StepResult>;
@@ -308,6 +330,8 @@ interface StepResult {
     sessionId?: string | undefined;
     output?: unknown;
     rawOutput?: string | undefined;
+    prUrl?: string | undefined;
+    prNumber?: number | undefined;
     costUsd: number;
     durationMs: number;
     agent: string;
@@ -322,10 +346,12 @@ interface DispatchInput {
     repo: string;
     prompt: string;
     runId?: string | undefined;
+    branch?: string | undefined;
     step?: string | undefined;
     from?: string | undefined;
     retry?: string | undefined;
     priority?: Priority | undefined;
+    gitStrategy?: "pr" | "branch" | undefined;
     overrides?: {
         agents?: Record<string, string> | undefined;
         maxTurns?: number | undefined;
@@ -357,7 +383,7 @@ interface ActiveSession {
     repo: string;
     status: "running" | "queued" | "waiting_gate";
     startedAt: string;
-    worktreePath?: string | undefined;
+    sessionPath?: string | undefined;
 }
 interface OrchestratorStatus {
     paused: boolean;
@@ -611,15 +637,13 @@ declare class Semaphore {
  */
 declare class CostJournal {
     private readonly dir;
-    private dirCreated;
+    private readonly dirCache;
     private dayCache;
     constructor(options: {
         dir: string;
     });
     append(entry: CostEntry): Promise<void>;
     getDayTotal(date?: Date): Promise<number>;
-    private fileForDate;
-    private ensureDir;
 }
 
 /**
@@ -646,28 +670,31 @@ declare class NeoEventEmitter {
  */
 declare class EventJournal {
     private readonly dir;
-    private dirCreated;
+    private readonly dirCache;
     constructor(options: {
         dir: string;
     });
     append(event: NeoEvent): Promise<void>;
-    private fileForDate;
-    private ensureDir;
 }
 
 type WebhookConfig = NeoConfig["webhooks"][number];
 /**
- * Fire-and-forget webhook dispatcher for NeoEvents.
+ * Webhook dispatcher for NeoEvents.
  *
  * - Matches events against per-webhook filters (exact or wildcard like "session:*")
  * - Excludes gate:waiting events (contain non-serializable callbacks)
  * - Signs payloads with HMAC-SHA256 when a secret is configured
- * - Never throws — errors are silently swallowed (consistent with EventJournal)
+ * - Terminal events (session:complete, session:fail, budget:alert) are retried
+ *   with exponential backoff on failure
+ * - Non-terminal events remain fire-and-forget
  */
 declare class WebhookDispatcher {
     private readonly webhooks;
+    private readonly pending;
     constructor(webhooks: WebhookConfig[]);
     dispatch(event: NeoEvent): void;
+    /** Wait for all pending terminal webhook deliveries to complete. */
+    flush(): Promise<void>;
 }
 /**
  * Check if an event type matches a filter list.
@@ -676,27 +703,48 @@ declare class WebhookDispatcher {
  */
 declare function matchesFilter(eventType: string, filters?: string[]): boolean;
 
+interface SessionCloneInfo {
+    path: string;
+    branch: string;
+    repoPath: string;
+}
+/**
+ * Create an isolated git clone for an agent session.
+ * Uses `git clone --local` to hardlink objects (fast, no network).
+ * Then checks out the target branch (existing or new).
+ */
+declare function createSessionClone(options: {
+    repoPath: string;
+    branch: string;
+    baseBranch: string;
+    sessionDir: string;
+}): Promise<SessionCloneInfo>;
+/**
+ * Remove a session clone directory.
+ * Idempotent — does not throw if the directory is already gone.
+ */
+declare function removeSessionClone(sessionPath: string): Promise<void>;
+/**
+ * List all session clones under a base directory.
+ */
+declare function listSessionClones(sessionsBaseDir: string): Promise<SessionCloneInfo[]>;
+
 declare function createBranch(repoPath: string, branch: string, baseBranch: string): Promise<void>;
 declare function pushBranch(repoPath: string, branch: string, remote: string): Promise<void>;
 declare function fetchRemote(repoPath: string, remote: string): Promise<void>;
 declare function deleteBranch(repoPath: string, branch: string): Promise<void>;
 declare function getCurrentBranch(repoPath: string): Promise<string>;
 /**
- * Generate a deterministic branch name for a run.
- * Uses the repo's branchPrefix (default "feat") and the runId.
- */
-declare function getBranchName(config: RepoConfig, runId: string): string;
-
-/**
- * Per-repository in-memory mutex to serialise git operations.
- * Concurrent git commands on the same repo corrupt the index — this prevents that.
+ * Resolve the branch name for a run.
+ * If an explicit branch is provided, use it as-is.
+ * Otherwise, generate a deterministic name from the repo's branchPrefix and runId.
  */
+declare function getBranchName(config: RepoConfig, runId: string, branch?: string): string;
 /**
- * Execute `fn` while holding an exclusive lock for `repoPath`.
- * Concurrent calls for the same repo are queued and executed serially.
- * Operations on different repos run in parallel.
+ * Push a branch from a session clone to a remote. Silently succeeds if
+ * the branch has no new commits to push.
  */
-declare function withGitLock<T>(repoPath: string, fn: () => Promise<T>): Promise<T>;
+declare function pushSessionBranch(sessionPath: string, branch: string, remote: string): Promise<void>;
 
 /**
  * SDK-compatible sandbox configuration.
@@ -715,40 +763,10 @@ interface SandboxConfig {
 /**
  * Build an SDK-compatible sandbox configuration for an agent.
  *
- * - Writable agents: all their tools are allowed, write paths include the worktree
+ * - Writable agents: all their tools are allowed, write paths include the session clone
  * - Readonly agents: write tools are filtered out, no writable paths
  */
-declare function buildSandboxConfig(agent: ResolvedAgent, worktreePath?: string): SandboxConfig;
-
-interface WorktreeInfo {
-    path: string;
-    branch: string;
-    repoPath: string;
-}
-/**
- * Create a new git worktree with an associated branch.
- * Creates the branch from baseBranch, then adds the worktree at worktreeDir.
- */
-declare function createWorktree(options: {
-    repoPath: string;
-    branch: string;
-    baseBranch: string;
-    worktreeDir: string;
-}): Promise<WorktreeInfo>;
-/**
- * Remove a worktree. Does NOT delete the branch (branch stays for the PR).
- * Idempotent — does not throw if the worktree is already gone.
- */
-declare function removeWorktree(worktreePath: string): Promise<void>;
-/**
- * List all worktrees for a repository.
- */
-declare function listWorktrees(repoPath: string): Promise<WorktreeInfo[]>;
-/**
- * Clean up worktrees under worktreeBaseDir that no longer have a matching run.
- * Removes any subdirectory that is a git worktree.
- */
-declare function cleanupOrphanedWorktrees(worktreeBaseDir: string): Promise<void>;
+declare function buildSandboxConfig(agent: ResolvedAgent, sessionPath?: string): SandboxConfig;
 
 /**
  * Audit log middleware.
@@ -828,13 +846,14 @@ declare class Orchestrator extends NeoEventEmitter {
     private readonly idempotencyCache;
     private readonly abortControllers;
     private readonly repoIndex;
-    private readonly createdRunDirs;
+    private readonly runStore;
     private readonly journalDir;
     private readonly builtInWorkflowDir;
     private readonly customWorkflowDir;
     private costJournal;
     private eventJournal;
     private webhookDispatcher;
+    private memoryStore;
     private _paused;
     private _costToday;
     private _startedAt;
@@ -870,12 +889,14 @@ declare class Orchestrator extends NeoEventEmitter {
     private buildDispatchContext;
     private executeStep;
     /**
-     * Push the branch, then remove the worktree.
+     * Push the branch (writable only), then remove the session clone.
      * Runs in `finally` so it executes on both success and failure.
      */
-    private finalizeWorktree;
+    private finalizeSession;
     private runAgentSession;
     private finalizeDispatch;
+    private getMemoryStore;
+    private loadMemoryContext;
     private emitCostEvents;
     private emitSessionComplete;
     private emitSessionFail;
@@ -885,8 +906,10 @@ declare class Orchestrator extends NeoEventEmitter {
     private getFirstStep;
     private resolveStepAgent;
     private resolveRepo;
-    private buildMiddlewareContext;
     private computeBudgetRemainingPct;
+    private resolveMcpServers;
+    /** Discover running supervisor daemons and return webhook configs for their endpoints. */
+    private discoverSupervisorWebhooks;
     private persistRun;
     private recoverOrphanedRuns;
 }
@@ -930,7 +953,6 @@ declare function getSupervisorDir(name: string): string;
  * Path to a supervisor state file: ~/.neo/supervisors/<name>/state.json
  */
 declare function getSupervisorStatePath(name: string): string;
-declare function getSupervisorMemoryPath(name: string): string;
 declare function getSupervisorActivityPath(name: string): string;
 declare function getSupervisorInboxPath(name: string): string;
 declare function getSupervisorEventsPath(name: string): string;
@@ -940,9 +962,12 @@ interface ParsedOutput {
     rawOutput: string;
     output?: unknown;
     parseError?: string;
+    prUrl?: string;
+    prNumber?: number;
 }
 /**
  * Parse agent output, optionally validating against a Zod schema.
+ * Also extracts structured markers like PR_URL from the output.
  *
  * - If no schema: returns rawOutput only
  * - If schema provided: extracts JSON from output, validates with schema
@@ -954,10 +979,11 @@ interface SessionOptions {
     agent: ResolvedAgent;
     prompt: string;
     repoPath?: string;
-    worktreePath?: string;
+    sessionPath?: string;
     sandboxConfig: SandboxConfig;
     hooks?: Record<string, unknown>;
-    mcpServers?: McpServerConfig[];
+    mcpServers?: Record<string, McpServerConfig>;
+    env?: Record<string, string>;
     initTimeoutMs: number;
     maxDurationMs: number;
     resumeSessionId?: string | undefined;
@@ -1007,6 +1033,78 @@ interface RecoveryOptions extends SessionOptions {
  */
 declare function runWithRecovery(options: RecoveryOptions): Promise<SessionResult>;
 
+interface SessionExecutionInput {
+    runId: string;
+    sessionId: string;
+    agent: ResolvedAgent;
+    stepDef: WorkflowStepDef;
+    repoConfig: RepoConfig;
+    repoPath: string;
+    prompt: string;
+    branch?: string | undefined;
+    gitStrategy: GitStrategy;
+    sessionPath?: string | undefined;
+    metadata?: Record<string, unknown> | undefined;
+    startedAt: string;
+}
+interface SessionExecutionConfig {
+    initTimeoutMs: number;
+    maxDurationMs: number;
+    maxRetries: number;
+    backoffBaseMs: number;
+}
+interface SessionExecutionDeps {
+    middleware: Middleware[];
+    mcpServers?: Record<string, McpServerConfig> | undefined;
+    memoryContext?: string | undefined;
+    onAttempt?: (attempt: number, strategy: string) => void;
+}
+interface SessionExecutionResult extends StepResult {
+    parsed: ParsedOutput;
+}
+declare function loadRepoInstructions(repoPath: string): Promise<string | undefined>;
+declare function buildGitStrategyInstructions(strategy: GitStrategy, agent: ResolvedAgent, branch: string, baseBranch: string, remote: string, metadata?: Record<string, unknown>): string | null;
+declare function buildReportingInstructions(_runId: string): string;
+declare function buildFullPrompt(agentPrompt: string | undefined, repoInstructions: string | undefined, gitInstructions: string | null, taskPrompt: string, memoryContext?: string | undefined, cwdInstructions?: string | undefined, reportingInstructions?: string | undefined): string;
+/**
+ * Encapsulates session execution logic: prompt building, SDK calls, and response processing.
+ * Extracted from Orchestrator for better testability and separation of concerns.
+ */
+declare class SessionExecutor {
+    private readonly config;
+    private readonly getContextValue;
+    constructor(config: SessionExecutionConfig, getContextValue: (key: string) => unknown);
+    /**
+     * Execute an agent session with the given input and dependencies.
+     * Handles prompt building, SDK invocation via recovery wrapper, and output parsing.
+     */
+    execute(input: SessionExecutionInput, deps: SessionExecutionDeps): Promise<SessionExecutionResult>;
+}
+
+/**
+ * Checks whether a process with the given PID is currently running.
+ *
+ * Uses the POSIX signal 0 trick: `process.kill(pid, 0)` doesn't actually
+ * send a signal but checks whether the process exists and the current
+ * process has permission to signal it. If the process doesn't exist,
+ * an ESRCH error is thrown.
+ *
+ * @param pid - The process ID to check. Must be a positive integer.
+ * @returns `true` if the process is alive and accessible, `false` otherwise.
+ *
+ * @example
+ * ```ts
+ * import { isProcessAlive } from "@/shared/process";
+ *
+ * // Check if current process is alive (always true)
+ * isProcessAlive(process.pid); // => true
+ *
+ * // Check if a non-existent process is alive
+ * isProcessAlive(999999); // => false
+ * ```
+ */
+declare function isProcessAlive(pid: number): boolean;
+
 declare const supervisorDaemonStateSchema: z.ZodObject<{
     pid: z.ZodNumber;
     sessionId: z.ZodString;
@@ -1019,11 +1117,21 @@ declare const supervisorDaemonStateSchema: z.ZodObject<{
     todayCostUsd: z.ZodDefault<z.ZodNumber>;
     costResetDate: z.ZodOptional<z.ZodString>;
     idleSkipCount: z.ZodDefault<z.ZodNumber>;
+    activeWorkSkipCount: z.ZodDefault<z.ZodNumber>;
     status: z.ZodDefault<z.ZodEnum<{
         running: "running";
         draining: "draining";
         stopped: "stopped";
     }>>;
+    lastConsolidationHeartbeat: z.ZodDefault<z.ZodNumber>;
+    lastCompactionHeartbeat: z.ZodDefault<z.ZodNumber>;
+    lastConsolidationTimestamp: z.ZodOptional<z.ZodString>;
+    wakeReason: z.ZodOptional<z.ZodEnum<{
+        events: "events";
+        timer: "timer";
+        active_runs: "active_runs";
+        forced: "forced";
+    }>>;
 }, z.core.$strip>;
 type SupervisorDaemonState = z.infer<typeof supervisorDaemonStateSchema>;
 declare const webhookIncomingEventSchema: z.ZodObject<{
@@ -1038,6 +1146,7 @@ type WebhookIncomingEvent = z.infer<typeof webhookIncomingEventSchema>;
 declare const inboxMessageSchema: z.ZodObject<{
     id: z.ZodString;
     from: z.ZodEnum<{
+        agent: "agent";
         tui: "tui";
         api: "api";
         external: "external";
@@ -1053,19 +1162,47 @@ declare const activityEntrySchema: z.ZodObject<{
         error: "error";
         message: "message";
         decision: "decision";
+        tool_use: "tool_use";
         event: "event";
         heartbeat: "heartbeat";
         action: "action";
         thinking: "thinking";
         plan: "plan";
         dispatch: "dispatch";
-        tool_use: "tool_use";
     }>;
     summary: z.ZodString;
     detail: z.ZodOptional<z.ZodUnknown>;
     timestamp: z.ZodString;
 }, z.core.$strip>;
 type ActivityEntry = z.infer<typeof activityEntrySchema>;
+declare const logBufferEntrySchema: z.ZodObject<{
+    id: z.ZodString;
+    type: z.ZodEnum<{
+        decision: "decision";
+        action: "action";
+        progress: "progress";
+        blocker: "blocker";
+        milestone: "milestone";
+        discovery: "discovery";
+    }>;
+    message: z.ZodString;
+    agent: z.ZodOptional<z.ZodString>;
+    runId: z.ZodOptional<z.ZodString>;
+    repo: z.ZodOptional<z.ZodString>;
+    target: z.ZodEnum<{
+        memory: "memory";
+        knowledge: "knowledge";
+        digest: "digest";
+    }>;
+    timestamp: z.ZodString;
+    consolidatedAt: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+type LogBufferEntry = z.infer<typeof logBufferEntrySchema>;
+declare const internalEventKindSchema: z.ZodEnum<{
+    consolidation_timer: "consolidation_timer";
+    active_run_check: "active_run_check";
+}>;
+type InternalEventKind = z.infer<typeof internalEventKindSchema>;
 type QueuedEvent = {
     kind: "webhook";
     data: WebhookIncomingEvent;
@@ -1076,6 +1213,10 @@ type QueuedEvent = {
     kind: "run_complete";
     runId: string;
     timestamp: string;
+} | {
+    kind: "internal";
+    eventKind: InternalEventKind;
+    timestamp: string;
 };
 
 declare class ActivityLog {
@@ -1101,6 +1242,8 @@ declare class ActivityLog {
 interface SupervisorDaemonOptions {
     name: string;
     config: GlobalConfig;
+    /** Path to bundled default SUPERVISOR.md (e.g. from @neotx/agents) */
+    defaultInstructionsPath?: string | undefined;
 }
 /**
  * Orchestrates all supervisor components: webhook server, event queue,
@@ -1110,6 +1253,7 @@ declare class SupervisorDaemon {
     private readonly name;
     private readonly config;
     private readonly dir;
+    private readonly defaultInstructionsPath;
     private webhookServer;
     private eventQueue;
     private heartbeatLoop;
@@ -1122,7 +1266,6 @@ declare class SupervisorDaemon {
     private readState;
     private writeState;
     private readLockPid;
-    private isProcessAlive;
 }
 
 interface EventQueueOptions {
@@ -1178,7 +1321,7 @@ declare class EventQueue {
      * Start watching inbox.jsonl and events.jsonl for new entries.
      * New lines are parsed and pushed into the queue.
      */
-    startWatching(inboxPath: string, eventsPath: string): void;
+    startWatching(inboxPath: string, eventsPath: string): Promise<void>;
     stopWatching(): void;
     /**
      * Replay unprocessed events from disk on startup.
@@ -1210,15 +1353,20 @@ interface HeartbeatLoopOptions {
     sessionId: string;
     eventQueue: EventQueue;
     activityLog: ActivityLog;
+    /** Path to bundled default SUPERVISOR.md (e.g. from @neotx/agents) */
+    defaultInstructionsPath?: string | undefined;
+    memoryDbPath?: string | undefined;
 }
 /**
  * The core autonomous loop. At each iteration:
  * 1. Drain events from the queue
- * 2. Build a prompt with context + memory + events
- * 3. Call sdk.query() for Claude to reason and act
- * 4. Extract and save updated memory
- * 5. Log activity
- * 6. Wait for the next event or idle timeout
+ * 2. Read log buffer entries
+ * 3. Determine standard vs consolidation mode
+ * 4. Build the appropriate prompt
+ * 5. Call sdk.query() for Claude to reason and act
+ * 6. Mark entries consolidated and compact log buffer (consolidation only)
+ * 7. Log activity
+ * 8. Wait for the next event or idle timeout
  */
 declare class HeartbeatLoop {
     private stopping;
@@ -1231,17 +1379,48 @@ declare class HeartbeatLoop {
     private readonly eventQueue;
     private readonly activityLog;
     private customInstructions;
+    private readonly defaultInstructionsPath;
+    private memoryStore;
+    private readonly memoryDbPath;
     constructor(options: HeartbeatLoopOptions);
+    private getMemoryStore;
     start(): Promise<void>;
     stop(): void;
     private runHeartbeat;
+    /**
+     * Check if supervisor daily budget is exceeded.
+     */
+    private checkBudgetExceeded;
+    /**
+     * Handle skip logic for idle and active-work scenarios.
+     */
+    private handleSkipLogic;
+    /**
+     * Determine heartbeat mode: compaction > consolidation > standard.
+     */
+    private determineHeartbeatMode;
+    /**
+     * Build the state update object after heartbeat completion.
+     */
+    private buildStateUpdate;
+    /**
+     * Build the prompt for the current heartbeat mode.
+     */
+    private buildHeartbeatModePrompt;
+    /**
+     * Call the Claude SDK and stream results.
+     */
+    private callSdk;
     private readState;
     private updateState;
+    /** Read persisted run files and return summaries of active (running/paused) runs. */
+    private getActiveRuns;
     /**
      * Load custom instructions from SUPERVISOR.md.
      * Resolution order:
      * 1. Explicit path via `supervisor.instructions` in config
-     * 2. Default: ~/.neo/SUPERVISOR.md
+     * 2. User default: ~/.neo/SUPERVISOR.md
+     * 3. Bundled default from @neotx/agents (if path provided)
      */
     private loadInstructions;
     /** Route a single SDK stream message to the appropriate log handler. */
@@ -1256,50 +1435,115 @@ declare class HeartbeatLoop {
 }
 
 /**
- * Load the supervisor memory from disk.
- * Migrates from legacy memory.md if needed.
- */
-declare function loadMemory(dir: string): Promise<string>;
-/**
- * Save the supervisor memory to disk (full overwrite).
- * Automatically compacts if needed.
- */
-declare function saveMemory(dir: string, content: string): Promise<void>;
-/**
- * Extract memory content from Claude's response using <memory>...</memory> tags.
+ * Append a single entry to the log buffer file.
  */
-declare function extractMemoryFromResponse(response: string): string | null;
-/**
- * Check if memory content exceeds the recommended size limit.
- */
-declare function checkMemorySize(content: string): {
-    ok: boolean;
-    sizeKB: number;
-};
+declare function appendLogBuffer(dir: string, entry: LogBufferEntry): Promise<void>;
 
-interface HeartbeatPromptOptions {
-    repos: RepoConfig[];
-    memory: string;
-    knowledge: string;
-    memorySizeKB: number;
-    grouped: GroupedEvents;
-    budgetStatus: {
-        todayUsd: number;
-        capUsd: number;
-        remainingPct: number;
-    };
-    activeRuns: string[];
-    heartbeatCount: number;
-    mcpServerNames: string[];
-    customInstructions?: string | undefined;
+interface Embedder {
+    embed(texts: string[]): Promise<number[][]>;
+    readonly dimensions: number;
+}
+declare class LocalEmbedder implements Embedder {
+    readonly dimensions = 384;
+    embed(texts: string[]): Promise<number[][]>;
+}
+
+declare const memoryTypeSchema: z.ZodEnum<{
+    fact: "fact";
+    procedure: "procedure";
+    episode: "episode";
+    focus: "focus";
+    feedback: "feedback";
+    task: "task";
+}>;
+type MemoryType = z.infer<typeof memoryTypeSchema>;
+declare const memoryEntrySchema: z.ZodObject<{
+    id: z.ZodString;
+    type: z.ZodEnum<{
+        fact: "fact";
+        procedure: "procedure";
+        episode: "episode";
+        focus: "focus";
+        feedback: "feedback";
+        task: "task";
+    }>;
+    scope: z.ZodString;
+    content: z.ZodString;
+    source: z.ZodString;
+    tags: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    createdAt: z.ZodString;
+    lastAccessedAt: z.ZodString;
+    accessCount: z.ZodDefault<z.ZodNumber>;
+    expiresAt: z.ZodOptional<z.ZodString>;
+    outcome: z.ZodOptional<z.ZodString>;
+    runId: z.ZodOptional<z.ZodString>;
+    category: z.ZodOptional<z.ZodString>;
+    severity: z.ZodOptional<z.ZodString>;
+    supersedes: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+type MemoryEntry = z.infer<typeof memoryEntrySchema>;
+declare const memoryWriteInputSchema: z.ZodObject<{
+    type: z.ZodEnum<{
+        fact: "fact";
+        procedure: "procedure";
+        episode: "episode";
+        focus: "focus";
+        feedback: "feedback";
+        task: "task";
+    }>;
+    scope: z.ZodDefault<z.ZodString>;
+    content: z.ZodString;
+    source: z.ZodDefault<z.ZodString>;
+    tags: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    expiresAt: z.ZodOptional<z.ZodString>;
+    outcome: z.ZodOptional<z.ZodString>;
+    runId: z.ZodOptional<z.ZodString>;
+    category: z.ZodOptional<z.ZodString>;
+    severity: z.ZodOptional<z.ZodString>;
+    supersedes: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+type MemoryWriteInput = z.input<typeof memoryWriteInputSchema>;
+interface MemoryQuery {
+    scope?: string;
+    types?: MemoryType[];
+    since?: string;
+    limit?: number;
+    sortBy?: "relevance" | "createdAt" | "accessCount";
+    tags?: string[];
+}
+interface MemoryStats {
+    total: number;
+    byType: Record<string, number>;
+    byScope: Record<string, number>;
+}
+
+declare class MemoryStore {
+    private db;
+    private embedder;
+    private hasVec;
+    constructor(dbPath: string, embedder?: Embedder | null);
+    private initSchema;
+    /**
+     * Migrate existing tables whose CHECK constraint predates the 'task' type.
+     * SQLite doesn't allow ALTER CHECK, so we recreate the table if needed.
+     */
+    private migrateCheckConstraint;
+    write(input: MemoryWriteInput): Promise<string>;
+    update(id: string, content: string): void;
+    updateFields(id: string, fields: {
+        content?: string;
+        outcome?: string;
+        runId?: string;
+    }): void;
+    forget(id: string): void;
+    query(opts?: MemoryQuery): MemoryEntry[];
+    search(text: string, opts?: MemoryQuery): Promise<MemoryEntry[]>;
+    markAccessed(ids: string[]): void;
+    decay(maxAgeDays?: number, minAccessCount?: number): number;
+    expireEphemeral(): number;
+    stats(): MemoryStats;
+    close(): void;
 }
-/**
- * Build the prompt sent to Claude at each heartbeat.
- *
- * Includes: role definition, current memory, pending events,
- * budget status, active runs, and available integrations.
- */
-declare function buildHeartbeatPrompt(opts: HeartbeatPromptOptions): string;
 
 interface WebhookServerOptions {
     port: number;
@@ -1378,4 +1622,4 @@ declare class WorkflowRegistry {
 
 declare const VERSION = "0.1.0";
 
-export { type ActiveSession, type ActivityEntry, ActivityLog, type AgentConfig, type AgentDefinition, type AgentMessageEvent, type AgentModel, AgentRegistry, type AgentTool, type AgentToolEntry, type AgentToolUseEvent, type AuditLogMiddleware, type BudgetAlertEvent, type CostEntry, CostJournal, type CostUpdateEvent, type DispatchInput, EventJournal, EventQueue, type GateWaitingEvent, type GlobalConfig, HeartbeatLoop, type HeartbeatLoopOptions, type HeartbeatPromptOptions, type HookEvent, type InboxMessage, type LoopDetectionMiddleware, type McpServerConfig, type Middleware, type MiddlewareChain, type MiddlewareContext, type MiddlewareContextMap, type MiddlewareEvent, type MiddlewareHandler, type MiddlewareResult, type NeoConfig, type NeoEvent, NeoEventEmitter, Orchestrator, type OrchestratorOptions, type OrchestratorShutdownEvent, type OrchestratorStatus, type ParsedOutput, type PersistedRun, type Priority, type QueueDequeueEvent, type QueueEnqueueEvent, type QueuedEvent, type RecoveryOptions, type RepoConfig, type RepoConfigInput, type ResolvedAgent, type SDKHooks, type SandboxConfig, Semaphore, type SemaphoreCallbacks, type SemaphoreConfig, type SessionCompleteEvent, SessionError, type SessionEvent, type SessionFailEvent, type SessionOptions, type SessionResult, type SessionStartEvent, type StepResult, SupervisorDaemon, type SupervisorDaemonOptions, type SupervisorDaemonState, type SupervisorDaemonState as SupervisorState, type TaskResult, VERSION, WebhookDispatcher, type WebhookIncomingEvent, WebhookServer, type WorkflowContext, type WorkflowDefinition, type WorkflowGateDef, WorkflowRegistry, type WorkflowStepCompleteEvent, type WorkflowStepDef, type WorkflowStepStartEvent, type WorktreeInfo, activityEntrySchema, addRepoToGlobalConfig, agentConfigSchema, agentModelSchema, agentSandboxSchema, agentToolEntrySchema, agentToolSchema, auditLog, budgetGuard, buildHeartbeatPrompt, buildMiddlewareChain, buildSDKHooks, buildSandboxConfig, checkMemorySize, cleanupOrphanedWorktrees, createBranch, createWorktree, deleteBranch, extractMemoryFromResponse, fetchRemote, getBranchName, getCurrentBranch, getDataDir, getJournalsDir, getRepoRunsDir, getRunDispatchPath, getRunLogPath, getRunsDir, getSupervisorActivityPath, getSupervisorDir, getSupervisorEventsPath, getSupervisorInboxPath, getSupervisorLockPath, getSupervisorMemoryPath, getSupervisorStatePath, getSupervisorsDir, globalConfigSchema, inboxMessageSchema, listReposFromGlobalConfig, listWorktrees, loadAgentFile, loadConfig, loadGlobalConfig, loadMemory, loadWorkflow, loopDetection, matchesFilter, mcpServerConfigSchema, neoConfigSchema, parseOutput, pushBranch, removeRepoFromGlobalConfig, removeWorktree, repoConfigSchema, resolveAgent, runSession, runWithRecovery, saveMemory, supervisorDaemonStateSchema, supervisorDaemonStateSchema as supervisorStateSchema, toRepoSlug, webhookIncomingEventSchema, withGitLock, workflowGateDefSchema, workflowStepDefSchema };
+export { type ActiveSession, type ActivityEntry, ActivityLog, type AgentConfig, type AgentDefinition, type AgentMessageEvent, type AgentModel, AgentRegistry, type AgentTool, type AgentToolEntry, type AgentToolUseEvent, type AuditLogMiddleware, type BudgetAlertEvent, type CostEntry, CostJournal, type CostUpdateEvent, type DispatchInput, type Embedder, EventJournal, EventQueue, type GateWaitingEvent, type GitStrategy, type GlobalConfig, HeartbeatLoop, type HeartbeatLoopOptions, type HookEvent, type InboxMessage, LocalEmbedder, type LoopDetectionMiddleware, type McpServerConfig, type MemoryEntry, type MemoryQuery, type MemoryStats, MemoryStore, type MemoryType, type MemoryWriteInput, type Middleware, type MiddlewareChain, type MiddlewareContext, type MiddlewareContextMap, type MiddlewareEvent, type MiddlewareHandler, type MiddlewareResult, type NeoConfig, type NeoEvent, NeoEventEmitter, Orchestrator, type OrchestratorOptions, type OrchestratorShutdownEvent, type OrchestratorStatus, type ParsedOutput, type PersistedRun, type Priority, type QueueDequeueEvent, type QueueEnqueueEvent, type QueuedEvent, type RecoveryOptions, type RepoConfig, type RepoConfigInput, type ResolvedAgent, type SDKHooks, type SandboxConfig, Semaphore, type SemaphoreCallbacks, type SemaphoreConfig, type SessionCloneInfo, type SessionCompleteEvent, SessionError, type SessionEvent, type SessionExecutionConfig, type SessionExecutionDeps, type SessionExecutionInput, type SessionExecutionResult, SessionExecutor, type SessionFailEvent, type SessionOptions, type SessionResult, type SessionStartEvent, type StepResult, SupervisorDaemon, type SupervisorDaemonOptions, type SupervisorDaemonState, type SupervisorDaemonState as SupervisorState, type TaskResult, VERSION, WebhookDispatcher, type WebhookIncomingEvent, WebhookServer, type WorkflowContext, type WorkflowDefinition, type WorkflowGateDef, WorkflowRegistry, type WorkflowStepCompleteEvent, type WorkflowStepDef, type WorkflowStepStartEvent, activityEntrySchema, addRepoToGlobalConfig, agentConfigSchema, agentModelSchema, agentSandboxSchema, agentToolEntrySchema, agentToolSchema, appendLogBuffer, auditLog, budgetGuard, buildFullPrompt, buildGitStrategyInstructions, buildMiddlewareChain, buildReportingInstructions, buildSDKHooks, buildSandboxConfig, createBranch, createSessionClone, deleteBranch, fetchRemote, getBranchName, getCurrentBranch, getDataDir, getJournalsDir, getRepoRunsDir, getRunDispatchPath, getRunLogPath, getRunsDir, getSupervisorActivityPath, getSupervisorDir, getSupervisorEventsPath, getSupervisorInboxPath, getSupervisorLockPath, getSupervisorStatePath, getSupervisorsDir, globalConfigSchema, inboxMessageSchema, isProcessAlive, listReposFromGlobalConfig, listSessionClones, loadAgentFile, loadConfig, loadGlobalConfig, loadRepoInstructions, loadWorkflow, loopDetection, matchesFilter, mcpServerConfigSchema, neoConfigSchema, parseOutput, pushBranch, pushSessionBranch, removeRepoFromGlobalConfig, removeSessionClone, repoConfigSchema, resolveAgent, runSession, runWithRecovery, supervisorDaemonStateSchema, supervisorDaemonStateSchema as supervisorStateSchema, toRepoSlug, webhookIncomingEventSchema, workflowGateDefSchema, workflowStepDefSchema };