clementine-agent 1.0.0

package/dist/types.d.ts

@@ -0,0 +1,716 @@
+/**
+ * Clementine TypeScript — Shared types.
+ */
+export interface SearchResult {
+    sourceFile: string;
+    section: string;
+    content: string;
+    score: float;
+    chunkType: string;
+    matchType: 'fts' | 'recency' | 'timeline' | 'vector';
+    lastUpdated: string;
+    chunkId: number;
+    salience: number;
+    agentSlug?: string | null;
+    category?: string | null;
+    topic?: string | null;
+}
+export type ChunkCategory = 'facts' | 'events' | 'discoveries' | 'preferences' | 'advice';
+export interface Chunk {
+    sourceFile: string;
+    section: string;
+    content: string;
+    chunkType: 'frontmatter' | 'heading' | 'preamble' | 'episodic';
+    frontmatterJson: string;
+    contentHash: string;
+    category?: ChunkCategory | null;
+    topic?: string | null;
+}
+export interface SyncStats {
+    filesScanned: number;
+    filesUpdated: number;
+    filesDeleted: number;
+    chunksTotal: number;
+}
+export interface SessionData {
+    sessionId: string;
+    exchanges: number;
+    timestamp: string;
+    exchangeHistory: Array<{
+        user: string;
+        assistant: string;
+    }>;
+    pendingContext?: Array<{
+        user: string;
+        assistant: string;
+    }>;
+}
+/** Origin context for a session — who/what created it and with what authority. */
+export interface SessionProvenance {
+    /** Channel that originated this session (e.g., 'discord', 'slack', 'cron', 'heartbeat', 'dashboard'). */
+    channel: string;
+    /** User ID within the channel (e.g., Discord user ID), or 'system' for autonomous. */
+    userId: string;
+    /** Interaction source determines trust level. */
+    source: 'owner-dm' | 'owner-channel' | 'member-channel' | 'autonomous';
+    /** Parent session key if spawned by another session (e.g., !plan sub-tasks). */
+    spawnedBy?: string;
+    /** Depth in the spawn hierarchy: 0 = top-level, 1 = sub-task, etc. */
+    spawnDepth: number;
+    /** Role assigned at spawn time — immutable once set. */
+    role: 'primary' | 'orchestrator' | 'worker';
+    /** What this session can control: 'children' = own spawns only, 'none' = no control. */
+    controlScope: 'children' | 'none';
+    /** ISO timestamp of session creation. */
+    createdAt: string;
+}
+export interface ChannelMessage {
+    sessionKey: string;
+    text: string;
+    channel: string;
+    userId: string;
+    attachments?: Attachment[];
+}
+export interface Attachment {
+    name: string;
+    url: string;
+    mimeType: string;
+    localPath?: string;
+}
+/** Declares what a channel can do, enabling graceful degradation. */
+export interface ChannelCapabilities {
+    /** Channel supports threaded conversations. */
+    threads: boolean;
+    /** Channel supports rich text (markdown, formatting). */
+    richText: boolean;
+    /** Channel supports file/image attachments. */
+    attachments: boolean;
+    /** Channel supports interactive buttons/actions. */
+    buttons: boolean;
+    /** Channel supports emoji reactions. */
+    reactions: boolean;
+    /** Channel supports typing indicators. */
+    typingIndicators: boolean;
+    /** Channel supports editing previously sent messages. */
+    editMessages: boolean;
+    /** Channel supports inline images in responses. */
+    inlineImages: boolean;
+    /** Maximum message length (0 = unlimited). */
+    maxMessageLength: number;
+}
+/** Default capabilities for channels that don't declare their own. */
+export declare const DEFAULT_CHANNEL_CAPABILITIES: ChannelCapabilities;
+export type OnTextCallback = (text: string) => Promise<void>;
+export type OnToolActivityCallback = (toolName: string, toolInput: Record<string, unknown>) => Promise<void>;
+export interface NotificationContext {
+    agentSlug?: string;
+}
+export type NotificationSender = (text: string, context?: NotificationContext) => Promise<void>;
+/** Policy governing autonomous outbound email sending for an agent. */
+export interface SendPolicy {
+    /** Maximum emails this agent can send per calendar day. */
+    maxDailyEmails: number;
+    /** Glob patterns for allowed email templates (e.g., ['intro-*', 'followup-*']). Omit to allow any. */
+    allowedTemplates?: string[];
+    /** When human approval is required: 'none' = fully autonomous, 'first-in-sequence' = approve first email per lead, 'all' = approve every send. */
+    requiresApproval: 'none' | 'first-in-sequence' | 'all';
+    /** If true, restrict sends to 8am–6pm in the system timezone. */
+    businessHoursOnly?: boolean;
+}
+export interface TeamAgentConfig {
+    channelName: string | string[];
+    channels: string[];
+    canMessage: string[];
+    allowedTools?: string[];
+    allowedUsers?: string[];
+    teamChat?: boolean;
+    respondToAll?: boolean;
+}
+export interface TeamMessage {
+    id: string;
+    fromAgent: string;
+    toAgent: string;
+    content: string;
+    timestamp: string;
+    delivered: boolean;
+    depth: number;
+    response?: string;
+    protocol?: 'fire-and-forget' | 'request' | 'response' | 'broadcast';
+    requestId?: string;
+    replyTo?: string;
+    expectedBy?: string;
+}
+export interface PendingRequest {
+    requestId: string;
+    fromAgent: string;
+    toAgent: string;
+    content: string;
+    timestamp: string;
+    expectedBy?: string;
+    status: 'pending' | 'responded' | 'expired';
+    responseMessageId?: string;
+}
+export interface AgentProfile {
+    slug: string;
+    name: string;
+    tier: number;
+    description: string;
+    systemPromptBody: string;
+    model?: string;
+    avatar?: string;
+    team?: TeamAgentConfig;
+    project?: string;
+    projects?: string[];
+    agentDir?: string;
+    discordToken?: string;
+    discordChannelId?: string;
+    slackBotToken?: string;
+    slackAppToken?: string;
+    slackChannelId?: string;
+    sendPolicy?: SendPolicy;
+    allowedMcpServers?: string[];
+    status?: AgentStatus;
+    budgetMonthlyCents?: number;
+    spentMonthlyCents?: number;
+    strictMemoryIsolation?: boolean;
+}
+export type AgentStatus = 'active' | 'paused' | 'error' | 'terminated';
+export interface HeartbeatReportedTopic {
+    topic: string;
+    summary: string;
+    reportedAt: string;
+    agentSlug?: string;
+}
+export interface HeartbeatState {
+    fingerprint: string;
+    details: Record<string, number | string>;
+    timestamp: string;
+    reportedTopics?: HeartbeatReportedTopic[];
+    consecutiveSilentBeats?: number;
+    lastDiscordMessageAt?: string;
+    /** Persisted scheduling dates — survive process restarts */
+    lastSelfImproveDate?: string;
+    lastConsolidationDate?: string;
+    lastAgentSiRuns?: Record<string, string>;
+    /** Proactive insight engine state */
+    insightState?: {
+        sentToday: string[];
+        lastSentAt?: string;
+        unackedCount: number;
+        cooldownMultiplier: number;
+        currentDate?: string;
+    };
+}
+export interface HeartbeatWorkItem {
+    id: string;
+    description: string;
+    prompt: string;
+    source: string;
+    priority: 'high' | 'normal';
+    queuedAt: string;
+    maxTurns: number;
+    tier: number;
+    status: 'pending' | 'running' | 'completed' | 'failed';
+    completedAt?: string;
+    result?: string;
+    error?: string;
+    agentSlug?: string;
+}
+export interface CronJobDefinition {
+    name: string;
+    schedule: string;
+    prompt: string;
+    enabled: boolean;
+    tier: number;
+    maxTurns?: number;
+    model?: string;
+    workDir?: string;
+    mode?: 'standard' | 'unleashed';
+    maxHours?: number;
+    maxRetries?: number;
+    after?: string;
+    agentSlug?: string;
+    successCriteria?: string[];
+    alwaysDeliver?: boolean;
+    context?: string;
+    preCheck?: string;
+    attachments?: string[];
+    requiresConfirmation?: boolean;
+    confirmationTimeoutMin?: number;
+}
+export type TerminalReason = 'blocking_limit' | 'rapid_refill_breaker' | 'prompt_too_long' | 'image_error' | 'model_error' | 'aborted_streaming' | 'aborted_tools' | 'stop_hook_prevented' | 'hook_stopped' | 'tool_deferred' | 'max_turns' | 'completed';
+export interface CronRunEntry {
+    jobName: string;
+    startedAt: string;
+    finishedAt: string;
+    status: 'ok' | 'error' | 'retried' | 'skipped';
+    durationMs: number;
+    error?: string;
+    errorType?: 'transient' | 'permanent';
+    terminalReason?: TerminalReason;
+    attempt: number;
+    outputPreview?: string;
+    deliveryFailed?: boolean;
+    deliveryError?: string;
+    advisorApplied?: {
+        adjustedMaxTurns?: number;
+        adjustedModel?: string;
+        adjustedTimeoutMs?: number;
+        enriched?: boolean;
+        escalated?: boolean;
+    };
+}
+export interface Models {
+    haiku: string;
+    sonnet: string;
+    opus: string;
+}
+export interface TranscriptTurn {
+    sessionKey: string;
+    role: string;
+    content: string;
+    model: string;
+    createdAt: string;
+}
+export interface SessionSummary {
+    sessionKey: string;
+    summary: string;
+    exchangeCount: number;
+    createdAt: string;
+}
+export interface WikilinkConnection {
+    direction: 'incoming' | 'outgoing';
+    file: string;
+    context: string;
+}
+export interface MemoryExtraction {
+    id?: number;
+    sessionKey: string;
+    userMessage: string;
+    toolName: string;
+    toolInput: string;
+    extractedAt: string;
+    status: 'active' | 'corrected' | 'dismissed' | 'dedup_skipped';
+    correction?: string;
+    agentSlug?: string;
+}
+export interface Feedback {
+    id?: number;
+    sessionKey?: string;
+    channel: string;
+    messageSnippet?: string;
+    responseSnippet?: string;
+    rating: 'positive' | 'negative' | 'mixed';
+    comment?: string;
+    createdAt?: string;
+}
+export interface BehavioralCorrection {
+    correction: string;
+    category: 'verbosity' | 'tone' | 'workflow' | 'format' | 'accuracy' | 'proactivity' | 'scope';
+    strength: 'explicit' | 'implicit';
+}
+export interface PreferenceLearned {
+    preference: string;
+    confidence: 'high' | 'medium' | 'low';
+}
+export interface SessionReflection {
+    id?: number;
+    sessionKey: string;
+    exchangeCount: number;
+    frictionSignals: string[];
+    qualityScore: number;
+    behavioralCorrections: BehavioralCorrection[];
+    preferencesLearned: PreferenceLearned[];
+    agentSlug?: string;
+    createdAt?: string;
+}
+export interface ManagedMcpServer {
+    name: string;
+    type: 'stdio' | 'http' | 'sse';
+    command?: string;
+    args?: string[];
+    url?: string;
+    headers?: Record<string, string>;
+    env?: Record<string, string>;
+    description: string;
+    enabled: boolean;
+    source: 'auto-detected' | 'user';
+}
+export interface UserModelUpdate {
+    field: string;
+    value: string;
+    evidence: string;
+    confidence: 'high' | 'medium' | 'low';
+}
+export interface SkillDocument {
+    name: string;
+    title: string;
+    description: string;
+    triggers: string[];
+    source: 'unleashed' | 'cron' | 'chat' | 'manual';
+    sourceJob?: string;
+    agentSlug?: string;
+    steps: string;
+    toolsUsed: string[];
+    useCount: number;
+    lastUsed?: string;
+    createdAt: string;
+    updatedAt: string;
+}
+export interface PlanStep {
+    id: string;
+    description: string;
+    prompt: string;
+    dependsOn: string[];
+    maxTurns: number;
+    tier: number;
+    model?: string;
+    delegateTo?: string;
+}
+export interface ExecutionPlan {
+    goal: string;
+    steps: PlanStep[];
+    synthesisPrompt: string;
+}
+export interface PlanProgressUpdate {
+    stepId: string;
+    status: 'waiting' | 'running' | 'done' | 'failed';
+    description: string;
+    durationMs?: number;
+    resultPreview?: string;
+}
+export interface WorkflowInput {
+    type: 'string' | 'number';
+    default?: string;
+    description?: string;
+}
+export interface WorkflowStep {
+    id: string;
+    prompt: string;
+    dependsOn: string[];
+    model?: string;
+    tier: number;
+    maxTurns: number;
+    workDir?: string;
+}
+export interface WorkflowDefinition {
+    name: string;
+    description: string;
+    enabled: boolean;
+    trigger: {
+        schedule?: string;
+        manual?: boolean;
+    };
+    inputs: Record<string, WorkflowInput>;
+    steps: WorkflowStep[];
+    synthesis?: {
+        prompt: string;
+    };
+    sourceFile: string;
+    agentSlug?: string;
+}
+export interface WorkflowRunEntry {
+    workflowName: string;
+    runId: string;
+    startedAt: string;
+    finishedAt: string;
+    status: 'ok' | 'error' | 'partial';
+    durationMs: number;
+    inputs: Record<string, string>;
+    stepResults: Array<{
+        stepId: string;
+        status: 'done' | 'failed' | 'skipped';
+        durationMs: number;
+        outputPreview?: string;
+    }>;
+    outputPreview?: string;
+    error?: string;
+}
+export interface SelfImproveExperiment {
+    id: string;
+    iteration: number;
+    startedAt: string;
+    finishedAt: string;
+    durationMs: number;
+    area: 'soul' | 'cron' | 'workflow' | 'memory' | 'agent' | 'source' | 'communication' | 'goal';
+    target: string;
+    hypothesis: string;
+    proposedChange: string;
+    baselineScore: number;
+    score: number;
+    accepted: boolean;
+    approvalStatus: 'pending' | 'approved' | 'denied' | 'expired';
+    reason: string;
+    error?: string;
+}
+/** Tracks a versioned evolution change for rollback chains. */
+export interface EvolutionVersion {
+    experimentId: string;
+    area: string;
+    target: string;
+    appliedAt: string;
+    parentVersion?: string;
+    rationale: string;
+    beforeSnapshot: string;
+    rolledBack?: boolean;
+    rolledBackAt?: string;
+}
+export interface SelfImproveState {
+    status: 'idle' | 'running' | 'completed' | 'failed';
+    lastRunAt: string;
+    currentIteration: number;
+    totalExperiments: number;
+    baselineMetrics: {
+        feedbackPositiveRatio: number;
+        cronSuccessRate: number;
+        avgResponseQuality: number;
+    };
+    pendingApprovals: number;
+    /** Version lineage for applied changes — enables rollback chains. */
+    evolutionVersions?: EvolutionVersion[];
+    /** Set when the loop aborted due to a persistent infrastructure error. */
+    infraError?: {
+        category: string;
+        diagnostic: string;
+    };
+}
+export interface SelfImproveConfig {
+    maxIterations: number;
+    iterationBudgetMs: number;
+    maxDurationMs: number;
+    acceptThreshold: number;
+    plateauLimit: number;
+    areas: ('soul' | 'cron' | 'workflow' | 'memory' | 'agent' | 'source' | 'communication' | 'goal')[];
+    /** Enable tiered auto-apply: low-risk changes apply without approval. Default: false. */
+    autoApply?: boolean;
+    /** Target a specific agent slug (for per-agent improvement cycles). */
+    agentSlug?: string;
+    /** How to handle source code proposals. 'skip' = drop silently, 'propose-only' = save for human review. Default: 'propose-only'. */
+    sourceMode?: 'skip' | 'propose-only';
+}
+export interface RestartSentinel {
+    previousPid: number;
+    restartedAt: string;
+    reason: 'source-edit' | 'update' | 'manual';
+    sourceChangeId?: string;
+    sessionKey?: string;
+    changedFiles?: string[];
+    updateDetails?: {
+        commitHash?: string;
+        commitDate?: string;
+        commitsBehind?: number;
+        summary?: string;
+        modsReapplied?: number;
+        modsSuperseded?: number;
+        modsNeedReconciliation?: number;
+        modsFailed?: number;
+    };
+}
+export interface EntityNode {
+    label: string;
+    id: string;
+    properties: Record<string, any>;
+}
+export interface EntityRef {
+    label: string;
+    id: string;
+}
+export interface RelationshipTriplet {
+    from: EntityRef;
+    rel: string;
+    to: EntityRef;
+    context?: string;
+    validFrom?: string | null;
+    validTo?: string | null;
+}
+export interface TraversalResult {
+    entity: EntityNode;
+    depth: number;
+    path: string[];
+}
+export interface PathResult {
+    nodes: EntityNode[];
+    relationships: string[];
+    length: number;
+}
+export interface GraphSyncStats {
+    nodesCreated: number;
+    relationshipsCreated: number;
+    duration: number;
+}
+export interface PersistentGoal {
+    id: string;
+    title: string;
+    description: string;
+    status: 'active' | 'paused' | 'completed' | 'blocked';
+    owner: string;
+    priority: 'high' | 'medium' | 'low';
+    createdAt: string;
+    updatedAt: string;
+    targetDate?: string;
+    progressNotes: string[];
+    nextActions: string[];
+    blockers?: string[];
+    reviewFrequency: 'daily' | 'weekly' | 'on-demand';
+    linkedCronJobs?: string[];
+    autoSchedule?: boolean;
+}
+export interface GoalProgressEntry {
+    timestamp: string;
+    goalId: string;
+    focus: string;
+    source: string;
+    madeProgress: boolean;
+    newProgressNotes: number;
+    resultSnippet: string;
+    status: 'progress' | 'no-change' | 'error';
+}
+export interface CronProgress {
+    jobName: string;
+    lastRunAt: string;
+    runCount: number;
+    state: Record<string, unknown>;
+    completedItems: string[];
+    pendingItems: string[];
+    notes: string;
+}
+export interface DelegatedTask {
+    id: string;
+    fromAgent: string;
+    toAgent: string;
+    task: string;
+    expectedOutput: string;
+    status: 'pending' | 'in_progress' | 'completed';
+    createdAt: string;
+    updatedAt: string;
+    result?: string;
+    goalId?: string;
+}
+export type VerboseLevel = 'quiet' | 'normal' | 'detailed';
+export interface ExecutionAdvice {
+    adjustedMaxTurns: number | null;
+    adjustedModel: string | null;
+    adjustedTimeoutMs: number | null;
+    promptEnrichment: string;
+    shouldEscalate: boolean;
+    escalationReason?: string;
+    shouldSkip: boolean;
+    skipReason?: string;
+}
+export interface AdvisorDecision {
+    jobName: string;
+    timestamp: string;
+    advice: ExecutionAdvice;
+    originalModel?: string;
+    originalMaxTurns?: number;
+    runOutcome?: 'ok' | 'error' | 'skipped';
+    runDurationMs?: number;
+}
+export interface DailyPlanPriority {
+    type: 'goal' | 'task' | 'cron-fix' | 'inbox';
+    id: string;
+    action: string;
+    urgency: number;
+}
+export interface DailyPlan {
+    date: string;
+    createdAt: string;
+    priorities: DailyPlanPriority[];
+    suggestedCronChanges: Array<{
+        job: string;
+        change: string;
+        reason: string;
+    }>;
+    newWork: Array<{
+        description: string;
+        goalId?: string;
+        suggestedSchedule?: string;
+    }>;
+    summary: string;
+}
+export interface RemoteAccessConfig {
+    enabled: boolean;
+    authToken: string;
+    tunnelUrl?: string;
+    autoPost: boolean;
+    lastStarted?: string;
+}
+export interface ConfigRevision {
+    id?: number;
+    agentSlug: string;
+    fileName: string;
+    content: string;
+    changedBy?: string;
+    createdAt?: string;
+}
+export interface Lead {
+    id?: number;
+    agentSlug: string;
+    email: string;
+    name: string;
+    company?: string;
+    title?: string;
+    status: 'new' | 'contacted' | 'replied' | 'qualified' | 'meeting_booked' | 'won' | 'lost' | 'opted_out';
+    source?: string;
+    sfId?: string;
+    metadata?: Record<string, unknown>;
+    createdAt?: string;
+    updatedAt?: string;
+}
+export interface SequenceEnrollment {
+    id?: number;
+    leadId: number;
+    sequenceName: string;
+    currentStep: number;
+    status: 'active' | 'paused' | 'replied' | 'completed' | 'opted_out';
+    nextStepDueAt?: string;
+    startedAt?: string;
+    updatedAt?: string;
+}
+export interface Activity {
+    id?: number;
+    leadId?: number;
+    agentSlug: string;
+    type: 'email_sent' | 'email_received' | 'meeting_booked' | 'call' | 'note' | 'status_change';
+    subject?: string;
+    detail?: string;
+    templateUsed?: string;
+    performedAt?: string;
+}
+export interface SuppressionEntry {
+    id?: number;
+    email: string;
+    reason: 'unsubscribe' | 'bounce' | 'manual' | 'complaint';
+    addedAt?: string;
+    addedBy?: string;
+}
+export interface ApprovalRequest {
+    id?: number;
+    agentSlug: string;
+    actionType: 'email_send' | 'sequence_start' | 'escalation';
+    summary: string;
+    detail?: Record<string, unknown>;
+    status: 'pending' | 'approved' | 'rejected';
+    requestedAt?: string;
+    resolvedAt?: string;
+    resolvedBy?: string;
+}
+export interface SfSyncRecord {
+    id?: number;
+    localTable: 'leads' | 'activities';
+    localId: number;
+    sfObjectType: 'Lead' | 'Contact' | 'Opportunity' | 'Task' | 'Event';
+    sfId: string;
+    syncDirection: 'push' | 'pull';
+    syncedAt?: string;
+    syncStatus: 'success' | 'error' | 'conflict';
+    errorMessage?: string;
+}
+export interface SfFieldMapping {
+    localField: string;
+    sfField: string;
+    direction: 'bidirectional' | 'push-only' | 'pull-only';
+}
+type float = number;
+export {};
+//# sourceMappingURL=types.d.ts.map