instar 0.9.0 → 0.9.2

package/dist/users/UserOnboarding.d.ts

@@ -0,0 +1,116 @@
+/**
+ * User Onboarding — handles new user registration and verification flows.
+ *
+ * Implements the Multi-User Setup Wizard spec (Rev 7):
+ * - New user joining an existing agent
+ * - Existing user on a new machine (verification)
+ * - On-the-fly Telegram registration
+ * - Consent collection before data collection
+ * - Agent contextual assessment for join requests
+ */
+import type { UserProfile, AgentAutonomyConfig, ConsentRecord, DataCollectedManifest, VerificationCode, JoinRequest } from '../core/types.js';
+/**
+ * Generate a random numeric verification code.
+ */
+export declare function generateVerificationCode(digits?: number): string;
+/**
+ * Generate a cryptographically random alphanumeric connect code
+ * using unambiguous characters (no 0/O, 1/l/I).
+ */
+export declare function generateConnectCode(length?: number): string;
+/**
+ * Hash a verification code for storage (we never store plaintext codes).
+ */
+export declare function hashCode(code: string): string;
+/**
+ * Generate a recovery key (32 bytes, displayed as hex).
+ */
+export declare function generateRecoveryKey(): string;
+/**
+ * Hash a recovery key with bcrypt-compatible SHA-256 (for config storage).
+ */
+export declare function hashRecoveryKey(key: string): string;
+/**
+ * Build the consent disclosure text for a given agent name.
+ */
+export declare function buildConsentDisclosure(agentName: string): string;
+/**
+ * Build a condensed consent disclosure for on-the-fly Telegram registration.
+ */
+export declare function buildCondensedConsentDisclosure(agentName: string): string;
+/**
+ * Create a consent record.
+ */
+export declare function createConsentRecord(version?: string): ConsentRecord;
+/**
+ * Create a default data collected manifest.
+ */
+export declare function createDataManifest(options?: Partial<DataCollectedManifest>): DataCollectedManifest;
+/**
+ * Manages verification codes with expiry and attempt limits.
+ */
+export declare class VerificationManager {
+    private codes;
+    private lockouts;
+    /**
+     * Create a new verification code for a target.
+     * Returns the plaintext code (display to user) and stores the hash.
+     */
+    createCode(targetId: string, type: VerificationCode['type']): {
+        code: string;
+        expiresAt: Date;
+    };
+    /**
+     * Verify a code attempt. Returns true if valid.
+     * Handles attempt counting, expiry, and lockout.
+     */
+    verifyCode(targetId: string, attempt: string): {
+        valid: boolean;
+        error?: string;
+    };
+}
+/**
+ * Manages join requests for admin-only registration.
+ */
+export declare class JoinRequestManager {
+    private requests;
+    private requestsFile;
+    constructor(stateDir: string);
+    /**
+     * Create a new join request.
+     */
+    createRequest(name: string, telegramUserId: number, agentAssessment: string | null): JoinRequest;
+    /**
+     * Resolve a join request (approve or deny).
+     */
+    resolveRequest(approvalCode: string, action: 'approved' | 'denied', resolvedBy: string): JoinRequest | null;
+    /**
+     * Get pending requests.
+     */
+    getPendingRequests(): JoinRequest[];
+    /**
+     * Get a request by Telegram user ID.
+     */
+    getRequestByTelegramUser(telegramUserId: number): JoinRequest | null;
+    private loadRequests;
+    private persistRequests;
+}
+/**
+ * Build a new user profile from onboarding data.
+ */
+export declare function buildUserProfile(opts: {
+    name: string;
+    userId?: string;
+    telegramTopicId?: string;
+    telegramUserId?: number;
+    email?: string;
+    permissions?: string[];
+    style?: string;
+    autonomyLevel?: 'full' | 'confirm-destructive' | 'confirm-all';
+    consent?: ConsentRecord;
+}): UserProfile;
+/**
+ * Get the default autonomy config for a given level.
+ */
+export declare function getDefaultAutonomyConfig(level: AgentAutonomyConfig['level']): AgentAutonomyConfig;
+//# sourceMappingURL=UserOnboarding.d.ts.map

package/dist/users/UserOnboarding.d.ts.map

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

package/dist/users/UserOnboarding.js

@@ -0,0 +1,365 @@
+/**
+ * User Onboarding — handles new user registration and verification flows.
+ *
+ * Implements the Multi-User Setup Wizard spec (Rev 7):
+ * - New user joining an existing agent
+ * - Existing user on a new machine (verification)
+ * - On-the-fly Telegram registration
+ * - Consent collection before data collection
+ * - Agent contextual assessment for join requests
+ */
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+// ── Constants ────────────────────────────────────────────────────────
+const VERIFICATION_DEFAULTS = {
+    digits: 6,
+    expiryMinutes: 10,
+    maxAttempts: 5,
+    lockoutMinutes: 30,
+};
+const CONNECT_CODE_DEFAULTS = {
+    length: 8,
+    expiryMinutes: 15,
+};
+// Unambiguous character set (no 0/O, 1/l/I)
+const UNAMBIGUOUS_CHARS = 'ABCDEFGHJKLMNPQRSTUVWXYZabcdefghjkmnpqrstuvwxyz23456789';
+// ── Code Generation ──────────────────────────────────────────────────
+/**
+ * Generate a random numeric verification code.
+ */
+export function generateVerificationCode(digits = VERIFICATION_DEFAULTS.digits) {
+    const max = Math.pow(10, digits);
+    const min = Math.pow(10, digits - 1);
+    const num = crypto.randomInt(min, max);
+    return num.toString();
+}
+/**
+ * Generate a cryptographically random alphanumeric connect code
+ * using unambiguous characters (no 0/O, 1/l/I).
+ */
+export function generateConnectCode(length = CONNECT_CODE_DEFAULTS.length) {
+    const bytes = crypto.randomBytes(length);
+    let code = '';
+    for (let i = 0; i < length; i++) {
+        code += UNAMBIGUOUS_CHARS[bytes[i] % UNAMBIGUOUS_CHARS.length];
+    }
+    return code;
+}
+/**
+ * Hash a verification code for storage (we never store plaintext codes).
+ */
+export function hashCode(code) {
+    return crypto.createHash('sha256').update(code).digest('hex');
+}
+/**
+ * Generate a recovery key (32 bytes, displayed as hex).
+ */
+export function generateRecoveryKey() {
+    return crypto.randomBytes(32).toString('hex');
+}
+/**
+ * Hash a recovery key with bcrypt-compatible SHA-256 (for config storage).
+ */
+export function hashRecoveryKey(key) {
+    return crypto.createHash('sha256').update(key).digest('hex');
+}
+// ── Consent ──────────────────────────────────────────────────────────
+/**
+ * Build the consent disclosure text for a given agent name.
+ */
+export function buildConsentDisclosure(agentName) {
+    return [
+        `Before we get started, here's what ${agentName} stores about you:`,
+        `- Your name and communication preferences`,
+        `- Your Telegram user ID (for identity verification)`,
+        `- Conversation history within your personal topic`,
+        `- Memory entries created during your sessions (tagged with your user ID)`,
+        ``,
+        `You can request deletion of your data at any time by asking the agent`,
+        `or contacting the admin. Your data is stored locally on the machines`,
+        `running this agent and in the git-backed state repository (if enabled).`,
+    ].join('\n');
+}
+/**
+ * Build a condensed consent disclosure for on-the-fly Telegram registration.
+ */
+export function buildCondensedConsentDisclosure(agentName) {
+    return `${agentName} will store your name, Telegram ID, and conversation history. You can request deletion anytime. Reply "OK" to continue or "No thanks" to stop.`;
+}
+/**
+ * Create a consent record.
+ */
+export function createConsentRecord(version) {
+    return {
+        consentGiven: true,
+        consentDate: new Date().toISOString(),
+        consentNoticeVersion: version,
+    };
+}
+/**
+ * Create a default data collected manifest.
+ */
+export function createDataManifest(options) {
+    return {
+        name: true,
+        telegramId: false,
+        communicationPreferences: true,
+        conversationHistory: false,
+        memoryEntries: false,
+        machineIdentities: false,
+        ...options,
+    };
+}
+// ── Verification ─────────────────────────────────────────────────────
+/**
+ * Manages verification codes with expiry and attempt limits.
+ */
+export class VerificationManager {
+    codes = new Map();
+    lockouts = new Map(); // userId -> lockout expiry timestamp
+    /**
+     * Create a new verification code for a target.
+     * Returns the plaintext code (display to user) and stores the hash.
+     */
+    createCode(targetId, type) {
+        // Check lockout
+        const lockoutExpiry = this.lockouts.get(targetId);
+        if (lockoutExpiry && Date.now() < lockoutExpiry) {
+            const remainingMinutes = Math.ceil((lockoutExpiry - Date.now()) / 60000);
+            throw new Error(`Too many failed attempts. Please wait ${remainingMinutes} minutes.`);
+        }
+        const code = type === 'pairing-code'
+            ? generateConnectCode()
+            : generateVerificationCode();
+        const expiryMinutes = type === 'pairing-code'
+            ? CONNECT_CODE_DEFAULTS.expiryMinutes
+            : VERIFICATION_DEFAULTS.expiryMinutes;
+        const verificationCode = {
+            codeHash: hashCode(code),
+            createdAt: new Date().toISOString(),
+            expiryMinutes,
+            maxAttempts: VERIFICATION_DEFAULTS.maxAttempts,
+            attempts: 0,
+            used: false,
+            targetId,
+            type,
+        };
+        this.codes.set(targetId, verificationCode);
+        const expiresAt = new Date(Date.now() + expiryMinutes * 60000);
+        return { code, expiresAt };
+    }
+    /**
+     * Verify a code attempt. Returns true if valid.
+     * Handles attempt counting, expiry, and lockout.
+     */
+    verifyCode(targetId, attempt) {
+        const stored = this.codes.get(targetId);
+        if (!stored) {
+            return { valid: false, error: 'No verification code found. Please request a new one.' };
+        }
+        // Check expiry
+        const expiryTime = new Date(stored.createdAt).getTime() + stored.expiryMinutes * 60000;
+        if (Date.now() > expiryTime) {
+            this.codes.delete(targetId);
+            return { valid: false, error: 'Code has expired. Please request a new one.' };
+        }
+        // Check if already used
+        if (stored.used) {
+            return { valid: false, error: 'Code has already been used. Please request a new one.' };
+        }
+        // Increment attempts
+        stored.attempts++;
+        // Check attempt limit
+        if (stored.attempts > stored.maxAttempts) {
+            this.codes.delete(targetId);
+            // Set lockout
+            this.lockouts.set(targetId, Date.now() + VERIFICATION_DEFAULTS.lockoutMinutes * 60000);
+            return {
+                valid: false,
+                error: `Too many incorrect attempts. Please wait ${VERIFICATION_DEFAULTS.lockoutMinutes} minutes before requesting a new code.`,
+            };
+        }
+        // Verify
+        if (hashCode(attempt) === stored.codeHash) {
+            stored.used = true;
+            this.codes.delete(targetId);
+            return { valid: true };
+        }
+        const remaining = stored.maxAttempts - stored.attempts;
+        return {
+            valid: false,
+            error: `Incorrect code. ${remaining} attempt${remaining === 1 ? '' : 's'} remaining.`,
+        };
+    }
+}
+// ── Join Request Management ──────────────────────────────────────────
+/**
+ * Manages join requests for admin-only registration.
+ */
+export class JoinRequestManager {
+    requests = new Map();
+    requestsFile;
+    constructor(stateDir) {
+        this.requestsFile = path.join(stateDir, 'join-requests.json');
+        this.loadRequests();
+    }
+    /**
+     * Create a new join request.
+     */
+    createRequest(name, telegramUserId, agentAssessment) {
+        const requestId = crypto.randomBytes(8).toString('hex');
+        const approvalCode = crypto.randomBytes(3).toString('hex'); // 6-char hex
+        const request = {
+            requestId,
+            name,
+            telegramUserId,
+            agentAssessment,
+            approvalCode,
+            requestedAt: new Date().toISOString(),
+            status: 'pending',
+        };
+        this.requests.set(requestId, request);
+        this.persistRequests();
+        return request;
+    }
+    /**
+     * Resolve a join request (approve or deny).
+     */
+    resolveRequest(approvalCode, action, resolvedBy) {
+        for (const request of this.requests.values()) {
+            if (request.approvalCode === approvalCode && request.status === 'pending') {
+                request.status = action;
+                request.resolvedBy = resolvedBy;
+                request.resolvedAt = new Date().toISOString();
+                this.persistRequests();
+                return request;
+            }
+        }
+        return null;
+    }
+    /**
+     * Get pending requests.
+     */
+    getPendingRequests() {
+        return Array.from(this.requests.values()).filter(r => r.status === 'pending');
+    }
+    /**
+     * Get a request by Telegram user ID.
+     */
+    getRequestByTelegramUser(telegramUserId) {
+        for (const request of this.requests.values()) {
+            if (request.telegramUserId === telegramUserId && request.status === 'pending') {
+                return request;
+            }
+        }
+        return null;
+    }
+    loadRequests() {
+        if (fs.existsSync(this.requestsFile)) {
+            try {
+                const data = JSON.parse(fs.readFileSync(this.requestsFile, 'utf-8'));
+                for (const req of data) {
+                    this.requests.set(req.requestId, req);
+                }
+            }
+            catch {
+                // Start fresh on corruption
+            }
+        }
+    }
+    persistRequests() {
+        const dir = path.dirname(this.requestsFile);
+        fs.mkdirSync(dir, { recursive: true });
+        const tmpPath = `${this.requestsFile}.${process.pid}.tmp`;
+        try {
+            fs.writeFileSync(tmpPath, JSON.stringify(Array.from(this.requests.values()), null, 2));
+            fs.renameSync(tmpPath, this.requestsFile);
+        }
+        catch (err) {
+            try {
+                fs.unlinkSync(tmpPath);
+            }
+            catch { /* ignore */ }
+            throw err;
+        }
+    }
+}
+// ── Onboarding Flow ──────────────────────────────────────────────────
+/**
+ * Build a new user profile from onboarding data.
+ */
+export function buildUserProfile(opts) {
+    // Generate a URL-safe user ID from the name if not provided
+    const userId = opts.userId || opts.name.toLowerCase().replace(/[^a-z0-9]/g, '-').replace(/-+/g, '-').replace(/^-|-$/g, '').slice(0, 32) || `user-${crypto.randomBytes(4).toString('hex')}`;
+    const channels = [];
+    if (opts.telegramTopicId) {
+        channels.push({ type: 'telegram', identifier: opts.telegramTopicId });
+    }
+    if (opts.email) {
+        channels.push({ type: 'email', identifier: opts.email });
+    }
+    const profile = {
+        id: userId,
+        name: opts.name,
+        channels,
+        permissions: opts.permissions || ['user'],
+        preferences: {
+            style: opts.style,
+            autonomyLevel: opts.autonomyLevel || 'confirm-destructive',
+        },
+        consent: opts.consent,
+        dataCollected: createDataManifest({
+            telegramId: !!opts.telegramTopicId || !!opts.telegramUserId,
+            conversationHistory: !!opts.telegramTopicId,
+        }),
+        pendingTelegramTopic: false,
+        createdAt: new Date().toISOString(),
+        telegramUserId: opts.telegramUserId,
+    };
+    return profile;
+}
+/**
+ * Get the default autonomy config for a given level.
+ */
+export function getDefaultAutonomyConfig(level) {
+    switch (level) {
+        case 'supervised':
+            return {
+                level: 'supervised',
+                capabilities: {
+                    assessJoinRequests: false,
+                    proposeConflictResolution: false,
+                    recommendConfigChanges: false,
+                    autoEnableVerifiedJobs: false,
+                    proactiveStatusAlerts: false,
+                    autoApproveKnownContacts: false,
+                },
+            };
+        case 'collaborative':
+            return {
+                level: 'collaborative',
+                capabilities: {
+                    assessJoinRequests: true,
+                    proposeConflictResolution: true,
+                    recommendConfigChanges: true,
+                    autoEnableVerifiedJobs: false,
+                    proactiveStatusAlerts: true,
+                    autoApproveKnownContacts: false,
+                },
+            };
+        case 'autonomous':
+            return {
+                level: 'autonomous',
+                capabilities: {
+                    assessJoinRequests: true,
+                    proposeConflictResolution: true,
+                    recommendConfigChanges: true,
+                    autoEnableVerifiedJobs: true,
+                    proactiveStatusAlerts: true,
+                    autoApproveKnownContacts: true,
+                },
+            };
+    }
+}
+//# sourceMappingURL=UserOnboarding.js.map

package/dist/users/UserOnboarding.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "instar",
-  "version": "0.9.0",
+  "version": "0.9.2",
   "description": "Persistent autonomy infrastructure for AI agents",
   "type": "module",
   "main": "dist/index.js",
@@ -24,6 +24,7 @@
     "test:all": "vitest run && vitest run --config vitest.integration.config.ts && vitest run --config vitest.e2e.config.ts",
     "lint": "tsc --noEmit",
     "clean": "rm -rf dist",
+    "check:upgrade-guide": "node scripts/check-upgrade-guide.js",
     "prepublishOnly": "npm run build"
   },
   "keywords": [

package/upgrades/0.8.23.md

@@ -0,0 +1,106 @@
+# Upgrade Guide: Instar 0.8.23
+
+> This guide covers new capabilities introduced in v0.8.23 through v0.8.26.
+
+## What Changed
+
+### Standalone Agents — Agents Without a Project Directory
+Previously, Instar required a project directory (a git repo) to house `.instar/`. This meant agents couldn't exist independently of a codebase.
+
+Now you can create **standalone agents** — agents that live in `~/.instar/agents/<name>/` with no associated project. These are ideal for general-purpose assistants, personal agents, or agents that work across multiple projects.
+
+```bash
+# Create a standalone agent
+instar init --standalone my-agent
+
+# Start it
+instar server start --dir ~/.instar/agents/my-agent
+```
+
+### Global Agent Registry
+All agents (project-based and standalone) are now tracked in a global registry at `~/.instar/registry.json`. This enables:
+- Listing all agents across your machine
+- Coordinating between agents
+- Health monitoring across your agent fleet
+
+### Backup & Restore — Protect Agent State
+A new backup system lets you snapshot and restore your agent's state.
+
+```bash
+instar backup create          # Snapshot current state
+instar backup list            # See all snapshots
+instar backup restore <id>    # Restore from snapshot
+```
+
+Backups capture everything: AGENT.md, MEMORY.md, config, job state, relationships.
+
+### Git-Backed State for Standalone Agents
+Standalone agents can sync their state via git. Useful for multi-machine setups.
+
+```bash
+instar git init               # Initialize git tracking
+instar git status             # See uncommitted changes
+instar git sync               # Commit and push state
+```
+
+### Memory Search — Find What You've Remembered
+Your MEMORY.md is searchable now. Full-text search across all memory files.
+
+```bash
+instar memory search "project goals"     # Search memory
+instar memory index                       # Re-index for faster search
+instar memory stats                       # See memory statistics
+```
+
+**What you should do:**
+1. If you manage multiple agents or want a personal agent, explore `instar init --standalone`.
+2. Consider setting up `instar backup create` as a regular habit (or add it to a scheduled job).
+3. Try `instar memory search` to surface things from your MEMORY.md you may have forgotten.
+
+### Multi-Machine Coordination Infrastructure
+Under the hood, significant infrastructure was added for coordinating agents across machines. This powers future capabilities for syncing agent state and coordinating work between machines. No user-facing action needed now.
+
+---
+
+## What Changed: Conversational Notification Tone
+Agent notifications have been tuned to sound more like a colleague than a system alert. Expect updates and status messages to use natural language rather than technical jargon.
+
+**What you should do:** Nothing. Just notice that your messages to your user sound more natural. If you have custom notification templates in your jobs, consider whether they match this tone.
+
+---
+
+## What Changed: Telegram Photo Viewing
+When your user sends a photo in Telegram, it's now delivered as `[image:path]` in your message input — a path you can pass directly to Claude for viewing. Previously photos were dropped or passed as raw file references that Claude couldn't process.
+
+**What you should do:** If you have photo-handling logic that worked around the old behavior, you may be able to simplify it. Now when you receive `[image:path]`, treat it as a viewable image.
+
+---
+
+## What Changed: Health Check Stability
+The server's health check now uses hysteresis — a brief failure doesn't immediately mark the server as unhealthy. This prevents false-positive health failures during brief transient issues.
+
+Also: `ANTHROPIC_API_KEY` is now trimmed of whitespace on startup. Keys with trailing newlines (a common copy-paste artifact) were previously silently failing.
+
+**What you should do:** If you experienced flapping health states or mysterious API key errors, this is fixed.
+
+---
+
+## Summary of New Capabilities
+
+| Capability | How to Use |
+|-----------|-----------|
+| Standalone agents | `instar init --standalone <name>` |
+| Global registry | `~/.instar/registry.json` — all agents tracked |
+| Backup/restore | `instar backup create/list/restore` |
+| Git-backed state | `instar git init/status/sync` |
+| Memory search | `instar memory search "<query>"` |
+| Photo messages | Receive `[image:path]` — viewable by Claude directly |
+| Health hysteresis | Fewer false-positive health failures |
+
+## What to Tell Your User
+
+Pick what's relevant to your context:
+- **Standalone agents**: "Instar can now run agents that aren't tied to a specific project. You could create a dedicated personal assistant this way."
+- **Backup**: "I can now snapshot my own state. Want me to set up regular backups so your preferences and my memory are protected?"
+- **Photo messages**: "I can now see photos you send me in Telegram — just attach them like normal."
+- **Cleaner notifications**: "My messages should sound a bit more natural now — less system-speak."