instar 0.6.12 → 0.6.13

package/.vercel/README.txt

@@ -0,0 +1,11 @@
+> Why do I have a folder named ".vercel" in my project?
+The ".vercel" folder is created when you link a directory to a Vercel project.
+
+> What does the "project.json" file contain?
+The "project.json" file contains:
+- The ID of the Vercel project that you linked ("projectId")
+- The ID of the user or team your Vercel project is owned by ("orgId")
+
+> Should I commit the ".vercel" folder?
+No, you should not share the ".vercel" folder with anyone.
+Upon creation, it will be automatically added to your ".gitignore" file.

package/.vercel/project.json

@@ -0,0 +1 @@
+{"projectId":"prj_evM5LcItYL3IAmw8zNvEPGrHeaya","orgId":"team_dHctwIDcV3X9ydapQlCPHFGI","projectName":"claude-agent-kit"}

package/dist/cli.js

@@ -21,7 +21,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { Command } from 'commander';
 import { initProject } from './commands/init.js';
-import { runSetup } from './commands/setup.js';
+// setup.ts is imported dynamically — it depends on @inquirer/prompts which requires Node 20.12+
 import { startServer, stopServer } from './commands/server.js';
 import { showStatus } from './commands/status.js';
 import { addUser, listUsers } from './commands/user.js';
@@ -257,13 +257,33 @@ program
     .description('Persistent autonomy infrastructure for AI agents')
     .version(getInstarVersion())
     .option('--classic', 'Use the classic inquirer-based setup wizard instead of Claude')
-    .action((opts) => runSetup(opts)); // Default: run interactive setup when no subcommand given
+    .action(async (opts) => {
+    const [major, minor] = process.versions.node.split('.').map(Number);
+    if (major < 20 || (major === 20 && minor < 12)) {
+        console.error(`\n  Instar setup requires Node.js 20.12 or later.`);
+        console.error(`  You're running Node.js ${process.versions.node}.`);
+        console.error(`\n  Upgrade: https://nodejs.org/en/download\n`);
+        process.exit(1);
+    }
+    const { runSetup } = await import('./commands/setup.js');
+    return runSetup(opts);
+}); // Default: run interactive setup when no subcommand given
 // ── Setup (explicit alias) ────────────────────────────────────────
 program
     .command('setup')
     .description('Interactive setup wizard (same as running `instar` with no args)')
     .option('--classic', 'Use the classic inquirer-based setup wizard instead of Claude')
-    .action((opts) => runSetup(opts));
+    .action(async (opts) => {
+    const [major, minor] = process.versions.node.split('.').map(Number);
+    if (major < 20 || (major === 20 && minor < 12)) {
+        console.error(`\n  Instar setup requires Node.js 20.12 or later.`);
+        console.error(`  You're running Node.js ${process.versions.node}.`);
+        console.error(`\n  Upgrade: https://nodejs.org/en/download\n`);
+        process.exit(1);
+    }
+    const { runSetup } = await import('./commands/setup.js');
+    return runSetup(opts);
+});
 // ── Init ─────────────────────────────────────────────────────────
 program
     .command('init [project-name]')

package/dist/commands/init.js

@@ -1336,6 +1336,15 @@ fi
 # For startup/resume/clear — output a compact orientation
 echo "=== SESSION START ==="
 
+# Telegram-spawned session awareness
+# When auto-created for a Telegram topic, prime the agent to respond immediately
+if [ -n "\$INSTAR_TELEGRAM_TOPIC" ]; then
+  echo ""
+  echo "This session was auto-spawned for Telegram topic \$INSTAR_TELEGRAM_TOPIC."
+  echo "A message from your user triggered this session and will arrive momentarily."
+  echo "IMMEDIATELY acknowledge it via your Telegram relay — they are waiting."
+fi
+
 # Identity summary (first 20 lines of AGENT.md — enough for name + role)
 if [ -f "$INSTAR_DIR/AGENT.md" ]; then
   echo ""

package/dist/commands/server.js

@@ -18,6 +18,8 @@ import { JobScheduler } from '../scheduler/JobScheduler.js';
 import { AgentServer } from '../server/AgentServer.js';
 import { TelegramAdapter } from '../messaging/TelegramAdapter.js';
 import { RelationshipManager } from '../core/RelationshipManager.js';
+import { ClaudeCliIntelligenceProvider } from '../core/ClaudeCliIntelligenceProvider.js';
+import { AnthropicIntelligenceProvider } from '../core/AnthropicIntelligenceProvider.js';
 import { FeedbackManager } from '../core/FeedbackManager.js';
 import { DispatchManager } from '../core/DispatchManager.js';
 import { UpdateChecker } from '../core/UpdateChecker.js';
@@ -25,6 +27,7 @@ import { registerPort, unregisterPort, startHeartbeat } from '../core/PortRegist
 import { TelegraphService } from '../publishing/TelegraphService.js';
 import { PrivateViewer } from '../publishing/PrivateViewer.js';
 import { TunnelManager } from '../tunnel/TunnelManager.js';
+import { EvolutionManager } from '../core/EvolutionManager.js';
 /**
  * Respawn a session for a topic, including thread history in the bootstrap.
  * This prevents "thread drift" where respawned sessions lose context.
@@ -218,9 +221,9 @@ function wireTelegramRouting(telegram, sessionManager) {
             const ctxPath = path.join(tmpDir, `ctx-${topicId}-${Date.now()}.txt`);
             fs.writeFileSync(ctxPath, contextLines.join('\n'));
             const bootstrapMessage = `[telegram:${topicId}] ${text} (IMPORTANT: Read ${ctxPath} for Telegram relay instructions — you MUST relay your response back.)`;
-            sessionManager.spawnInteractiveSession(bootstrapMessage, storedName).then((newSessionName) => {
+            sessionManager.spawnInteractiveSession(bootstrapMessage, storedName, { telegramTopicId: topicId }).then((newSessionName) => {
                 telegram.registerTopicSession(topicId, newSessionName);
-                telegram.sendToTopic(topicId, `Session created.`).catch(() => { });
+                telegram.sendToTopic(topicId, `Session starting up — reading your message now. One moment.`).catch(() => { });
                 console.log(`[telegram→session] Auto-spawned "${newSessionName}" for topic ${topicId}`);
             }).catch((err) => {
                 console.error(`[telegram→session] Auto-spawn failed:`, err);
@@ -351,8 +354,32 @@ export async function startServer(options) {
         const sessionManager = new SessionManager(config.sessions, state);
         let relationships;
         if (config.relationships) {
+            // Wire LLM intelligence for identity resolution.
+            // Priority: Claude CLI (subscription, zero extra cost) > Anthropic API (explicit opt-in only)
+            const claudePath = config.sessions.claudePath;
+            let intelligenceMode = 'heuristic-only';
+            // Check if user explicitly opted into API-based intelligence
+            // (intelligenceProvider is a config-file-only field, not in the TypeScript type)
+            const explicitProvider = config.relationships.intelligenceProvider;
+            if (explicitProvider === 'anthropic-api') {
+                // User explicitly chose API — respect their decision
+                const apiProvider = AnthropicIntelligenceProvider.fromEnv();
+                if (apiProvider) {
+                    config.relationships.intelligence = apiProvider;
+                    intelligenceMode = 'LLM-supervised (Anthropic API — user choice)';
+                }
+                else {
+                    console.log(pc.yellow('  intelligenceProvider: "anthropic-api" set but ANTHROPIC_API_KEY not found'));
+                }
+            }
+            else if (claudePath) {
+                // Default: use Claude CLI via subscription (zero extra cost)
+                config.relationships.intelligence = new ClaudeCliIntelligenceProvider(claudePath);
+                intelligenceMode = 'LLM-supervised (Claude CLI subscription)';
+            }
             relationships = new RelationshipManager(config.relationships);
-            console.log(pc.green(`  Relationships loaded: ${relationships.getAll().length} tracked`));
+            const count = relationships.getAll().length;
+            console.log(pc.green(`  Relationships loaded: ${count} tracked (${intelligenceMode})`));
         }
         let scheduler;
         if (config.scheduler.enabled) {
@@ -454,7 +481,13 @@ export async function startServer(options) {
                 stateDir: config.stateDir,
             });
         }
-        const server = new AgentServer({ config, sessionManager, state, scheduler, telegram, relationships, feedback, dispatches, updateChecker, publisher, viewer, tunnel });
+        // Set up evolution system (always enabled — the feedback loop infrastructure)
+        const evolution = new EvolutionManager({
+            stateDir: config.stateDir,
+            ...(config.evolution || {}),
+        });
+        console.log(pc.green('  Evolution system enabled'));
+        const server = new AgentServer({ config, sessionManager, state, scheduler, telegram, relationships, feedback, dispatches, updateChecker, publisher, viewer, tunnel, evolution });
         await server.start();
         // Start tunnel AFTER server is listening
         if (tunnel) {

package/dist/core/AnthropicIntelligenceProvider.d.ts

@@ -0,0 +1,24 @@
+/**
+ * AnthropicIntelligenceProvider — OPTIONAL IntelligenceProvider using the Anthropic Messages API.
+ *
+ * ⚠️  This provider uses API tokens (extra cost). For most Instar agents, the
+ * ClaudeCliIntelligenceProvider (which uses the Claude subscription) is the
+ * correct default. Only use this provider when:
+ *   - The user explicitly sets intelligenceProvider: "anthropic-api" in config
+ *   - The Claude CLI is not available
+ *   - The user has a specific reason to prefer direct API access
+ *
+ * No SDK dependency — direct fetch calls, following the TelegramAdapter pattern.
+ */
+import type { IntelligenceProvider, IntelligenceOptions } from './types.js';
+export declare class AnthropicIntelligenceProvider implements IntelligenceProvider {
+    private apiKey;
+    constructor(apiKey: string);
+    /**
+     * Create a provider from environment variables, or null if no key available.
+     * Follows the same graceful degradation pattern as TelegramAdapter's voice providers.
+     */
+    static fromEnv(): AnthropicIntelligenceProvider | null;
+    evaluate(prompt: string, options?: IntelligenceOptions): Promise<string>;
+}
+//# sourceMappingURL=AnthropicIntelligenceProvider.d.ts.map

package/dist/core/AnthropicIntelligenceProvider.js

@@ -0,0 +1,68 @@
+/**
+ * AnthropicIntelligenceProvider — OPTIONAL IntelligenceProvider using the Anthropic Messages API.
+ *
+ * ⚠️  This provider uses API tokens (extra cost). For most Instar agents, the
+ * ClaudeCliIntelligenceProvider (which uses the Claude subscription) is the
+ * correct default. Only use this provider when:
+ *   - The user explicitly sets intelligenceProvider: "anthropic-api" in config
+ *   - The Claude CLI is not available
+ *   - The user has a specific reason to prefer direct API access
+ *
+ * No SDK dependency — direct fetch calls, following the TelegramAdapter pattern.
+ */
+const ANTHROPIC_API_URL = 'https://api.anthropic.com/v1/messages';
+const ANTHROPIC_API_VERSION = '2023-06-01';
+/** Model mapping: abstract tiers → concrete Anthropic model IDs */
+const MODEL_MAP = {
+    fast: 'claude-haiku-4-5-20251001',
+    balanced: 'claude-sonnet-4-5-20250514',
+    capable: 'claude-opus-4-0-20250514',
+};
+const DEFAULT_MODEL = 'fast';
+export class AnthropicIntelligenceProvider {
+    apiKey;
+    constructor(apiKey) {
+        this.apiKey = apiKey;
+    }
+    /**
+     * Create a provider from environment variables, or null if no key available.
+     * Follows the same graceful degradation pattern as TelegramAdapter's voice providers.
+     */
+    static fromEnv() {
+        const apiKey = process.env['ANTHROPIC_API_KEY'];
+        if (!apiKey) {
+            return null;
+        }
+        return new AnthropicIntelligenceProvider(apiKey);
+    }
+    async evaluate(prompt, options) {
+        const model = MODEL_MAP[options?.model ?? DEFAULT_MODEL] ?? MODEL_MAP[DEFAULT_MODEL];
+        const maxTokens = options?.maxTokens ?? 100;
+        const temperature = options?.temperature ?? 0;
+        const response = await fetch(ANTHROPIC_API_URL, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                'x-api-key': this.apiKey,
+                'anthropic-version': ANTHROPIC_API_VERSION,
+            },
+            body: JSON.stringify({
+                model,
+                max_tokens: maxTokens,
+                temperature,
+                messages: [
+                    { role: 'user', content: prompt },
+                ],
+            }),
+        });
+        if (!response.ok) {
+            const errorText = await response.text().catch(() => 'unknown error');
+            throw new Error(`Anthropic API error ${response.status}: ${errorText}`);
+        }
+        const data = await response.json();
+        // Extract text from the response
+        const textBlock = data.content?.find((block) => block.type === 'text');
+        return textBlock?.text ?? '';
+    }
+}
+//# sourceMappingURL=AnthropicIntelligenceProvider.js.map

package/dist/core/ClaudeCliIntelligenceProvider.d.ts

@@ -0,0 +1,21 @@
+/**
+ * ClaudeCliIntelligenceProvider — Default IntelligenceProvider using the Claude CLI.
+ *
+ * Uses `claude -p` (print mode) to make judgment calls via the user's existing
+ * Claude subscription. Zero extra cost — the subscription is already paid for.
+ *
+ * This is the DEFAULT provider for Instar agents. The Anthropic API provider
+ * (AnthropicIntelligenceProvider) is an explicit opt-in alternative for users
+ * who intentionally choose direct API access.
+ *
+ * Preference hierarchy:
+ *   1. Claude CLI (subscription) — default, always available
+ *   2. Anthropic API — explicit user choice only
+ */
+import type { IntelligenceProvider, IntelligenceOptions } from './types.js';
+export declare class ClaudeCliIntelligenceProvider implements IntelligenceProvider {
+    private claudePath;
+    constructor(claudePath: string);
+    evaluate(prompt: string, options?: IntelligenceOptions): Promise<string>;
+}
+//# sourceMappingURL=ClaudeCliIntelligenceProvider.d.ts.map

package/dist/core/ClaudeCliIntelligenceProvider.js

@@ -0,0 +1,59 @@
+/**
+ * ClaudeCliIntelligenceProvider — Default IntelligenceProvider using the Claude CLI.
+ *
+ * Uses `claude -p` (print mode) to make judgment calls via the user's existing
+ * Claude subscription. Zero extra cost — the subscription is already paid for.
+ *
+ * This is the DEFAULT provider for Instar agents. The Anthropic API provider
+ * (AnthropicIntelligenceProvider) is an explicit opt-in alternative for users
+ * who intentionally choose direct API access.
+ *
+ * Preference hierarchy:
+ *   1. Claude CLI (subscription) — default, always available
+ *   2. Anthropic API — explicit user choice only
+ */
+import { execFile } from 'node:child_process';
+/** Model mapping: abstract tiers → Claude CLI model flags */
+const MODEL_MAP = {
+    fast: 'haiku',
+    balanced: 'sonnet',
+    capable: 'opus',
+};
+const DEFAULT_MODEL = 'fast';
+const DEFAULT_TIMEOUT_MS = 30_000;
+export class ClaudeCliIntelligenceProvider {
+    claudePath;
+    constructor(claudePath) {
+        this.claudePath = claudePath;
+    }
+    async evaluate(prompt, options) {
+        const model = MODEL_MAP[options?.model ?? DEFAULT_MODEL] ?? MODEL_MAP[DEFAULT_MODEL];
+        const maxTokens = options?.maxTokens ?? 100;
+        return new Promise((resolve, reject) => {
+            const args = [
+                '-p', prompt,
+                '--model', model,
+                '--max-turns', '1',
+                '--output-format', 'text',
+            ];
+            if (maxTokens) {
+                args.push('--max-tokens', String(maxTokens));
+            }
+            const child = execFile(this.claudePath, args, {
+                timeout: DEFAULT_TIMEOUT_MS,
+                maxBuffer: 1024 * 1024, // 1MB
+                env: { ...process.env },
+            }, (error, stdout, stderr) => {
+                if (error) {
+                    // Timeout or other error — return empty so caller can fall back
+                    reject(new Error(`Claude CLI error: ${error.message}${stderr ? ` — ${stderr.slice(0, 200)}` : ''}`));
+                    return;
+                }
+                resolve(stdout.trim());
+            });
+            // Write prompt via stdin for very long prompts (belt and suspenders)
+            child.stdin?.end();
+        });
+    }
+}
+//# sourceMappingURL=ClaudeCliIntelligenceProvider.js.map

package/dist/core/EvolutionManager.d.ts

@@ -0,0 +1,157 @@
+/**
+ * Evolution Manager — the feedback loop that turns running into evolving.
+ *
+ * Four subsystems, one principle: every interaction is an opportunity
+ * to improve. Not during batch reflection hours later, but at the
+ * moment the insight is freshest.
+ *
+ * Subsystems:
+ * 1. Evolution Queue — staged self-improvement proposals
+ * 2. Learning Registry — structured, searchable insights
+ * 3. Capability Gap Tracker — "what am I missing?"
+ * 4. Action Queue — commitment tracking with stale detection
+ *
+ * Born from Portal's engagement pipeline (Steps 8-11) and proven
+ * across 100+ evolution proposals and 10 platform engagement skills.
+ */
+import type { EvolutionProposal, EvolutionType, EvolutionStatus, LearningEntry, LearningSource, CapabilityGap, GapCategory, ActionItem, EvolutionManagerConfig } from './types.js';
+interface EvolutionState {
+    proposals: EvolutionProposal[];
+    stats: {
+        totalProposals: number;
+        byStatus: Record<string, number>;
+        byType: Record<string, number>;
+        lastUpdated: string;
+    };
+}
+interface LearningState {
+    learnings: LearningEntry[];
+    stats: {
+        totalLearnings: number;
+        applied: number;
+        pending: number;
+        byCategory: Record<string, number>;
+        lastUpdated: string;
+    };
+}
+interface GapState {
+    gaps: CapabilityGap[];
+    stats: {
+        totalGaps: number;
+        bySeverity: Record<string, number>;
+        byCategory: Record<string, number>;
+        addressed: number;
+        lastUpdated: string;
+    };
+}
+interface ActionState {
+    actions: ActionItem[];
+    stats: {
+        totalActions: number;
+        pending: number;
+        completed: number;
+        overdue: number;
+        lastUpdated: string;
+    };
+}
+export declare class EvolutionManager {
+    private stateDir;
+    private config;
+    constructor(config: EvolutionManagerConfig);
+    private filePath;
+    private readFile;
+    private writeFile;
+    private now;
+    private loadEvolution;
+    private saveEvolution;
+    private nextProposalId;
+    addProposal(opts: {
+        title: string;
+        source: string;
+        description: string;
+        type: EvolutionType;
+        impact?: 'high' | 'medium' | 'low';
+        effort?: 'high' | 'medium' | 'low';
+        proposedBy?: string;
+        tags?: string[];
+    }): EvolutionProposal;
+    updateProposalStatus(id: string, status: EvolutionStatus, resolution?: string): boolean;
+    listProposals(filter?: {
+        status?: EvolutionStatus;
+        type?: EvolutionType;
+    }): EvolutionProposal[];
+    getEvolutionStats(): EvolutionState['stats'];
+    private loadLearnings;
+    private saveLearnings;
+    private nextLearningId;
+    addLearning(opts: {
+        title: string;
+        category: string;
+        description: string;
+        source: LearningSource;
+        tags?: string[];
+        evolutionRelevance?: string;
+    }): LearningEntry;
+    markLearningApplied(id: string, appliedTo: string): boolean;
+    listLearnings(filter?: {
+        category?: string;
+        applied?: boolean;
+    }): LearningEntry[];
+    getLearningStats(): LearningState['stats'];
+    private loadGaps;
+    private saveGaps;
+    private nextGapId;
+    addGap(opts: {
+        title: string;
+        category: GapCategory;
+        severity: 'critical' | 'high' | 'medium' | 'low';
+        description: string;
+        context: string;
+        platform?: string;
+        session?: string;
+        currentState?: string;
+        proposedSolution?: string;
+    }): CapabilityGap;
+    addressGap(id: string, resolution: string): boolean;
+    listGaps(filter?: {
+        severity?: string;
+        category?: GapCategory;
+        status?: string;
+    }): CapabilityGap[];
+    getGapStats(): GapState['stats'];
+    private loadActions;
+    private saveActions;
+    private nextActionId;
+    addAction(opts: {
+        title: string;
+        description: string;
+        priority?: 'critical' | 'high' | 'medium' | 'low';
+        commitTo?: string;
+        dueBy?: string;
+        source?: ActionItem['source'];
+        tags?: string[];
+    }): ActionItem;
+    updateAction(id: string, updates: {
+        status?: ActionItem['status'];
+        resolution?: string;
+    }): boolean;
+    listActions(filter?: {
+        status?: ActionItem['status'];
+        priority?: string;
+    }): ActionItem[];
+    getOverdueActions(): ActionItem[];
+    getActionStats(): ActionState['stats'];
+    /**
+     * Get a full dashboard of evolution health.
+     * Useful for session-start orientation and status reporting.
+     */
+    getDashboard(): {
+        evolution: EvolutionState['stats'];
+        learnings: LearningState['stats'];
+        gaps: GapState['stats'];
+        actions: ActionState['stats'];
+        highlights: string[];
+    };
+}
+export {};
+//# sourceMappingURL=EvolutionManager.d.ts.map