clementine-agent 1.0.0

package/dist/gateway/heartbeat.d.ts

@@ -0,0 +1,3 @@
+export { HeartbeatScheduler } from './heartbeat-scheduler.js';
+export { CronScheduler, CronRunLog, parseCronJobs, parseAgentCronJobs, validateCronYaml, classifyError, logToDailyNote } from './cron-scheduler.js';
+//# sourceMappingURL=heartbeat.d.ts.map

package/dist/gateway/heartbeat.js

@@ -0,0 +1,3 @@
+export { HeartbeatScheduler } from './heartbeat-scheduler.js';
+export { CronScheduler, CronRunLog, parseCronJobs, parseAgentCronJobs, validateCronYaml, classifyError, logToDailyNote } from './cron-scheduler.js';
+//# sourceMappingURL=heartbeat.js.map

package/dist/gateway/lanes.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Clementine TypeScript — Lane-based concurrency control.
+ *
+ * Separates work into independent concurrency pools so cron jobs
+ * can't starve chat responses and vice versa.
+ */
+export type Lane = 'chat' | 'cron' | 'heartbeat' | 'self-improve' | 'team';
+declare class LaneController {
+    private limits;
+    private active;
+    private waiters;
+    /** Acquire a slot in a lane. Resolves when a slot is available. */
+    acquire(lane: Lane): Promise<() => void>;
+    /** Get current lane utilization for monitoring. */
+    status(): Record<Lane, {
+        active: number;
+        limit: number;
+        queued: number;
+    }>;
+    private createRelease;
+}
+export declare const lanes: LaneController;
+export {};
+//# sourceMappingURL=lanes.d.ts.map

package/dist/gateway/lanes.js

@@ -0,0 +1,76 @@
+/**
+ * Clementine TypeScript — Lane-based concurrency control.
+ *
+ * Separates work into independent concurrency pools so cron jobs
+ * can't starve chat responses and vice versa.
+ */
+import pino from 'pino';
+const logger = pino({ name: 'clementine.lanes' });
+class LaneController {
+    limits = {
+        chat: 3, // Up to 3 concurrent chat sessions
+        cron: 2, // Up to 2 concurrent cron jobs
+        heartbeat: 1, // Only 1 heartbeat at a time
+        'self-improve': 1, // Only 1 self-improvement cycle at a time
+        team: 2, // Up to 2 concurrent inter-agent messages
+    };
+    active = {
+        chat: 0,
+        cron: 0,
+        heartbeat: 0,
+        'self-improve': 0,
+        team: 0,
+    };
+    waiters = {
+        chat: [],
+        cron: [],
+        heartbeat: [],
+        'self-improve': [],
+        team: [],
+    };
+    /** Acquire a slot in a lane. Resolves when a slot is available. */
+    async acquire(lane) {
+        if (this.active[lane] < this.limits[lane]) {
+            this.active[lane]++;
+            logger.debug({ lane, active: this.active[lane], limit: this.limits[lane] }, 'Lane slot acquired');
+            return this.createRelease(lane);
+        }
+        // Lane is full — queue a waiter
+        logger.info({ lane, active: this.active[lane], limit: this.limits[lane], queued: this.waiters[lane].length }, 'Lane full — queuing');
+        await new Promise((resolve) => {
+            this.waiters[lane].push(resolve);
+        });
+        // Slot was handed to us by a release — already incremented
+        return this.createRelease(lane);
+    }
+    /** Get current lane utilization for monitoring. */
+    status() {
+        return {
+            chat: { active: this.active.chat, limit: this.limits.chat, queued: this.waiters.chat.length },
+            cron: { active: this.active.cron, limit: this.limits.cron, queued: this.waiters.cron.length },
+            heartbeat: { active: this.active.heartbeat, limit: this.limits.heartbeat, queued: this.waiters.heartbeat.length },
+            'self-improve': { active: this.active['self-improve'], limit: this.limits['self-improve'], queued: this.waiters['self-improve'].length },
+            team: { active: this.active.team, limit: this.limits.team, queued: this.waiters.team.length },
+        };
+    }
+    createRelease(lane) {
+        let released = false;
+        return () => {
+            if (released)
+                return; // guard against double-release
+            released = true;
+            const next = this.waiters[lane].shift();
+            if (next) {
+                // Hand the slot directly to the next waiter (active count stays the same)
+                logger.debug({ lane, queued: this.waiters[lane].length }, 'Lane slot handed to next waiter');
+                next();
+            }
+            else {
+                this.active[lane]--;
+                logger.debug({ lane, active: this.active[lane] }, 'Lane slot released');
+            }
+        };
+    }
+}
+export const lanes = new LaneController();
+//# sourceMappingURL=lanes.js.map

package/dist/gateway/notifications.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Clementine TypeScript — Notification dispatcher.
+ *
+ * Decouples heartbeat/cron DM sending from any specific channel.
+ * Each channel adapter registers a sender function on startup;
+ * the dispatcher fans out notifications to all registered channels.
+ */
+import type { NotificationSender, NotificationContext } from '../types.js';
+export interface SendResult {
+    delivered: boolean;
+    channelErrors: Record<string, string>;
+}
+export declare class NotificationDispatcher {
+    private senders;
+    private _retryQueue;
+    constructor();
+    register(channelName: string, senderFn: NotificationSender): void;
+    unregister(channelName: string): void;
+    get hasChannels(): boolean;
+    /** Get the retry queue size (for dashboard status). */
+    get pendingRetries(): number;
+    /** Send a notification; automatically queues for retry on total failure. */
+    send(text: string, context?: NotificationContext): Promise<SendResult>;
+    /** Direct send without retry queueing (used by retry queue itself). */
+    private sendDirect;
+    /** Stop the retry queue timer (for graceful shutdown). */
+    shutdown(): void;
+}
+//# sourceMappingURL=notifications.d.ts.map

package/dist/gateway/notifications.js

@@ -0,0 +1,75 @@
+/**
+ * Clementine TypeScript — Notification dispatcher.
+ *
+ * Decouples heartbeat/cron DM sending from any specific channel.
+ * Each channel adapter registers a sender function on startup;
+ * the dispatcher fans out notifications to all registered channels.
+ */
+import pino from 'pino';
+import { DeliveryQueue } from './delivery-queue.js';
+const logger = pino({ name: 'clementine.notifications' });
+/** Safety cap — prevent runaway messages, but each channel handles its own chunking/limits. */
+const MAX_MESSAGE_LENGTH = 8000;
+export class NotificationDispatcher {
+    senders = new Map();
+    _retryQueue;
+    constructor() {
+        this._retryQueue = new DeliveryQueue();
+        this._retryQueue.setSender((text, ctx) => this.sendDirect(text, ctx));
+        this._retryQueue.start();
+    }
+    register(channelName, senderFn) {
+        this.senders.set(channelName, senderFn);
+        logger.info(`Notification sender registered: ${channelName}`);
+    }
+    unregister(channelName) {
+        this.senders.delete(channelName);
+        logger.info(`Notification sender unregistered: ${channelName}`);
+    }
+    get hasChannels() {
+        return this.senders.size > 0;
+    }
+    /** Get the retry queue size (for dashboard status). */
+    get pendingRetries() {
+        return this._retryQueue.size;
+    }
+    /** Send a notification; automatically queues for retry on total failure. */
+    async send(text, context) {
+        const result = await this.sendDirect(text, context);
+        // If delivery failed and there were actual senders (not "no channels"), queue for retry
+        if (!result.delivered && this.senders.size > 0) {
+            this._retryQueue.enqueue(text, context);
+        }
+        return result;
+    }
+    /** Direct send without retry queueing (used by retry queue itself). */
+    async sendDirect(text, context) {
+        if (this.senders.size === 0) {
+            logger.warn('No notification senders registered — message dropped');
+            return { delivered: false, channelErrors: { _: 'no channels registered' } };
+        }
+        // Sanity cap only — each channel sender handles its own chunking/truncation
+        const capped = text.length > MAX_MESSAGE_LENGTH
+            ? text.slice(0, MAX_MESSAGE_LENGTH - 20) + '\n\n_(truncated)_'
+            : text;
+        const channelErrors = {};
+        let anySuccess = false;
+        for (const [name, sender] of this.senders) {
+            try {
+                await sender(capped, context);
+                anySuccess = true;
+            }
+            catch (err) {
+                const errMsg = String(err).slice(0, 200);
+                channelErrors[name] = errMsg;
+                logger.error({ err, channel: name }, `Failed to send notification via ${name}`);
+            }
+        }
+        return { delivered: anySuccess, channelErrors };
+    }
+    /** Stop the retry queue timer (for graceful shutdown). */
+    shutdown() {
+        this._retryQueue.stop();
+    }
+}
+//# sourceMappingURL=notifications.js.map

package/dist/gateway/router.d.ts

@@ -0,0 +1,210 @@
+/**
+ * Clementine TypeScript — Gateway router and session management.
+ *
+ * Routes messages between channel adapters and the agent layer.
+ * Manages per-user/channel sessions for conversation continuity.
+ */
+import { PersonalAssistant, type ProjectMeta } from '../agent/assistant.js';
+import type { OnTextCallback, OnToolActivityCallback, PlanProgressUpdate, PlanStep, SelfImproveConfig, SelfImproveExperiment, SessionProvenance, TeamMessage, VerboseLevel, WorkflowDefinition } from '../types.js';
+import { AgentManager } from '../agent/agent-manager.js';
+import { TeamRouter } from '../agent/team-router.js';
+import { TeamBus } from '../agent/team-bus.js';
+import type { NotificationDispatcher } from './notifications.js';
+export type ChatErrorKind = 'rate_limit' | 'context_overflow' | 'auth' | 'transient' | 'unknown';
+export declare function classifyChatError(err: unknown): ChatErrorKind;
+/** Detect auth-like errors in response text that the SDK returned as "successful" results. */
+export declare function looksLikeAuthError(text: string): boolean;
+export declare class Gateway {
+    readonly assistant: PersonalAssistant;
+    /** Resolvers for pending approvals. `true` = approved, `false` = denied, `string` = revision feedback. */
+    private approvalResolvers;
+    private approvalCounter;
+    private sessions;
+    private auditLog;
+    private draining;
+    /** Persisted set of channel keys the owner has approved. Loaded lazily. */
+    private seenChannels;
+    private _authFailCount;
+    private _authFailSince;
+    private _authLastProbe;
+    private static readonly AUTH_FAIL_THRESHOLD;
+    private static readonly AUTH_PROBE_INTERVAL;
+    /** Returns true if the auth circuit is open (too many consecutive auth failures). */
+    get authCircuitOpen(): boolean;
+    /** Record an auth failure. On first crossing the threshold, notify the owner proactively. */
+    recordAuthFailure(): void;
+    /** Clear the auth circuit after a successful request. */
+    clearAuthFailure(): void;
+    /** Check if enough time has passed to allow an auth probe (one message let through). */
+    shouldProbeAuth(): boolean;
+    private _dispatcher?;
+    /** Register the notification dispatcher so deep mode / auto-escalation results can be pushed to channels. */
+    setDispatcher(d: NotificationDispatcher): void;
+    /** Derive a stable "channel key" from a session key (strips the per-user suffix). */
+    static channelKey(sessionKey: string): string | null;
+    private _loadSeenChannels;
+    private _saveSeenChannels;
+    /** Mark a channel as seen (owner approved or explicitly always-allowed). */
+    markChannelSeen(channelKey: string): void;
+    /**
+     * Deliver a deep-mode result back to the user.
+     * Routes through the agent's session so it responds conversationally,
+     * then pushes the agent's reply via the dispatcher so it actually reaches the channel.
+     * Falls back to pushing rawResult directly if the agent call fails.
+     */
+    private _deliverDeepResult;
+    private _agentManager?;
+    private _teamRouter?;
+    private _teamBus?;
+    private _botManager?;
+    private _slackBotManager?;
+    constructor(assistant: PersonalAssistant);
+    /** Get or create a session state entry. */
+    private getSession;
+    getAgentManager(): AgentManager;
+    getTeamRouter(): TeamRouter;
+    getTeamBus(): TeamBus;
+    /** Register the BotManager so TeamBus can resolve agent bot channels for delivery. */
+    setBotManager(botManager: import('../channels/discord-bot-manager.js').BotManager): void;
+    /** Register the SlackBotManager so TeamBus can resolve Slack agent channels for delivery. */
+    setSlackBotManager(slackBotManager: import('../channels/slack-bot-manager.js').SlackBotManager): void;
+    /** Route an inter-agent message through the team bus. */
+    handleTeamMessage(fromSlug: string, toSlug: string, content: string, depth?: number): Promise<TeamMessage>;
+    /**
+     * Register provenance for a session. Write-once: once set, spawnedBy,
+     * spawnDepth, role, and controlScope are immutable (prevents re-parenting
+     * or privilege escalation).
+     */
+    setProvenance(sessionKey: string, provenance: SessionProvenance): void;
+    getProvenance(sessionKey: string): SessionProvenance | undefined;
+    /**
+     * Create provenance from a session key using naming conventions.
+     * Called automatically on first message if no provenance exists.
+     */
+    private ensureProvenance;
+    /**
+     * Verify that a session is allowed to control (kill/steer) a target session.
+     * A session can only control sessions it directly spawned.
+     */
+    canControl(controllerKey: string, targetKey: string): boolean;
+    /** Derive provenance from session key naming conventions. */
+    static inferProvenance(sessionKey: string): SessionProvenance;
+    /**
+     * Create provenance for a spawned sub-session (e.g., !plan worker).
+     * Enforces depth limits and inherits source from parent.
+     */
+    spawnChildProvenance(parentKey: string, childKey: string, role?: 'orchestrator' | 'worker', maxDepth?: number): SessionProvenance | null;
+    setDraining(value: boolean): void;
+    isDraining(): boolean;
+    setUnleashedCompleteCallback(cb: (jobName: string, result: string) => void): void;
+    setPhaseCompleteCallback(cb: (jobName: string, phase: number, totalPhases: number, output: string) => void): void;
+    setPhaseProgressCallback(cb: (jobName: string, phase: number, summary: string) => void): void;
+    /** Wire the skill-proposed notification — called once at startup so new skills surface to owner. */
+    initSkillNotifications(): void;
+    handleSkill(action: string, args?: {
+        name?: string;
+    }): Promise<string>;
+    setSessionVerboseLevel(sessionKey: string, level: VerboseLevel): void;
+    getSessionVerboseLevel(sessionKey: string): VerboseLevel | undefined;
+    setSessionModel(sessionKey: string, modelId: string): void;
+    getSessionModel(sessionKey: string): string | undefined;
+    setSessionProject(sessionKey: string, project: ProjectMeta): void;
+    getSessionProject(sessionKey: string): ProjectMeta | undefined;
+    clearSessionProject(sessionKey: string): void;
+    setSessionProfile(sessionKey: string, slug: string): void;
+    getSessionProfile(sessionKey: string): string | undefined;
+    clearSessionProfile(sessionKey: string): void;
+    isSessionBusy(sessionKey: string): boolean;
+    /**
+     * Abort an in-progress chat query for a session.
+     * Returns true if there was an active query to abort.
+     */
+    stopSession(sessionKey: string): boolean;
+    /**
+     * Serialize access to a session. Returns a function to call when done,
+     * or waits for the current holder to finish first.
+     */
+    private acquireSessionLock;
+    handleMessage(sessionKey: string, text: string, onText?: OnTextCallback, model?: string, maxTurns?: number, onToolActivity?: OnToolActivityCallback): Promise<string>;
+    handleHeartbeat(standingInstructions: string, changesSummary?: string, timeContext?: string, dedupContext?: string, profile?: import('../types.js').AgentProfile | null): Promise<string>;
+    handleCronJob(jobName: string, jobPrompt: string, tier?: number, maxTurns?: number, model?: string, workDir?: string, mode?: 'standard' | 'unleashed', maxHours?: number, timeoutMs?: number, successCriteria?: string[]): Promise<string>;
+    /**
+     * Process a team message as an autonomous task — same multi-phase execution
+     * as cron unleashed jobs, so agents can work until done instead of being
+     * killed by the 5-minute interactive chat timeout.
+     */
+    handleTeamTask(fromName: string, fromSlug: string, content: string, profile: import('../types.js').AgentProfile, onText?: (token: string) => void): Promise<string>;
+    handlePlan(sessionKey: string, taskDescription: string, onProgress?: (updates: PlanProgressUpdate[]) => Promise<void>, onApproval?: (planSummary: string, steps: PlanStep[]) => Promise<boolean | string>): Promise<string>;
+    handleWorkflow(workflow: WorkflowDefinition, inputs?: Record<string, string>): Promise<string>;
+    /**
+     * Inject a command/response exchange into a session so follow-up
+     * conversation has context (e.g. cron output shown in DM).
+     */
+    injectContext(sessionKey: string, userText: string, assistantText: string): void;
+    /**
+     * Get recent transcript activity across all sessions.
+     * Used by heartbeat to know what happened since the last check.
+     */
+    getRecentActivity(sinceIso: string): Array<{
+        sessionKey: string;
+        role: string;
+        content: string;
+        createdAt: string;
+    }>;
+    /**
+     * Search memory (FTS5) for context relevant to a query.
+     * Used by heartbeat to enrich goal summaries with recent memory.
+     */
+    searchMemory(query: string, limit?: number): Array<{
+        sourceFile: string;
+        section: string;
+        content: string;
+        score: number;
+    }>;
+    /**
+     * Get the memory store instance for direct operations (consolidation, etc.).
+     * Returns null if the store hasn't been initialized yet.
+     */
+    getMemoryStore(): any;
+    /**
+     * Get and consume the terminal reason from the last SDK query.
+     * Used by the cron scheduler for precise error classification.
+     */
+    consumeLastTerminalReason(): string | undefined;
+    requestApproval(descriptionOrId: string, explicitId?: string): Promise<boolean | string>;
+    resolveApproval(requestId: string, result: boolean | string): void;
+    getPendingApprovals(): string[];
+    addAuditEntry(entry: string): void;
+    getAuditEntries(): string[];
+    getLaneStatus(): Record<import("./lanes.js").Lane, {
+        active: number;
+        limit: number;
+        queued: number;
+    }>;
+    getMcpStatus(): {
+        servers: Array<{
+            name: string;
+            status: string;
+        }>;
+        updatedAt: string;
+    };
+    getPresenceInfo(sessionKey: string): {
+        model: string;
+        project: string | null;
+        exchanges: number;
+        maxExchanges: number;
+        memoryCount: number;
+    };
+    clearSession(sessionKey: string): void;
+    /** Evict stale session entries (no activity in 48h, no active lock). */
+    evictStaleSessions(): number;
+    /** Get all active session provenance entries (for dashboard/monitoring). */
+    getAllProvenance(): Map<string, SessionProvenance>;
+    handleSelfImprove(action: string, args?: {
+        experimentId?: string;
+        config?: Partial<SelfImproveConfig>;
+    }, onProposal?: (experiment: SelfImproveExperiment) => Promise<void>): Promise<string>;
+    /** Extract a procedural skill from a successful cron execution (fire-and-forget). */
+    extractCronSkill(jobName: string, prompt: string, output: string, durationMs: number, agentSlug?: string): Promise<void>;
+}
+//# sourceMappingURL=router.d.ts.map