speexor 0.2.0 → 0.2.1

package/dist/types-BOMap-tI.d.ts

@@ -0,0 +1,389 @@
+type AgentStatus = 'idle' | 'running' | 'stuck' | 'needs-review' | 'done' | 'error';
+type AgentProvider = 'opencode' | 'claude-code' | 'aider' | 'codex';
+type RuntimeType = 'tmux' | 'process';
+type SessionStatus = 'initializing' | 'active' | 'paused' | 'completed' | 'failed' | 'cancelled';
+interface PluginModule {
+    name: string;
+    version: string;
+    type: PluginSlot;
+    initialize(context: PluginContext): Promise<void>;
+    destroy(): Promise<void>;
+}
+type PluginSlot = 'agent' | 'runtime' | 'workspace' | 'tracker' | 'scm' | 'notifier' | 'terminal';
+interface PluginContext {
+    config: SpeexorConfig;
+    eventBus: EventBus;
+    logger: (msg: string) => void;
+}
+interface AgentPlugin extends PluginModule {
+    type: 'agent';
+    spawn(task: AgentTask, runtime: RuntimeSession): Promise<AgentSession>;
+    sendInput(sessionId: string, input: string): Promise<void>;
+    getStatus(sessionId: string): Promise<AgentStatus>;
+    kill(sessionId: string): Promise<void>;
+}
+interface AgentTask {
+    id: string;
+    title: string;
+    description: string;
+    repository: string;
+    branch: string;
+    provider?: AgentProvider;
+    model?: string;
+}
+interface AgentSession {
+    id: string;
+    taskId: string;
+    provider: AgentProvider;
+    status: AgentStatus;
+    startedAt: Date;
+    runtimeSessionId: string;
+}
+interface RuntimePlugin extends PluginModule {
+    type: 'runtime';
+    createSession(worktreePath: string): Promise<RuntimeSession>;
+    destroySession(sessionId: string): Promise<void>;
+    sendInput(sessionId: string, input: string): Promise<void>;
+    getOutput(sessionId: string): Promise<string>;
+    getLiveStream(sessionId: string): AsyncIterable<string>;
+    getStatus(sessionId: string): Promise<'running' | 'stopped' | 'error'>;
+}
+interface RuntimeSession {
+    id: string;
+    type: RuntimeType;
+    worktreePath: string;
+    pid?: number;
+    createdAt: Date;
+}
+interface WorkspacePlugin extends PluginModule {
+    type: 'workspace';
+    createWorktree(task: AgentTask): Promise<WorktreeSession>;
+    removeWorktree(sessionId: string): Promise<void>;
+    getWorktreePath(sessionId: string): string;
+    listActive(): Promise<WorktreeSession[]>;
+    cleanupStale(): Promise<string[]>;
+}
+type WorkspaceSession = WorktreeSession;
+interface WorktreeSession {
+    id: string;
+    taskId: string;
+    repository: string;
+    branch: string;
+    path: string;
+    createdAt: Date;
+}
+interface TrackerPlugin extends PluginModule {
+    type: 'tracker';
+    fetchIssues(filter?: TrackerFilter): Promise<TrackerIssue[]>;
+    getIssue(id: string): Promise<TrackerIssue | null>;
+    onEvent(handler: (event: TrackerEvent) => void): void;
+}
+interface TrackerFilter {
+    state?: 'open' | 'closed' | 'all';
+    labels?: string[];
+    since?: Date;
+    limit?: number;
+}
+interface TrackerIssue {
+    id: string;
+    title: string;
+    description: string;
+    state: 'open' | 'closed';
+    labels: string[];
+    url: string;
+    createdAt: Date;
+    updatedAt: Date;
+}
+type TrackerEventType = 'issue-opened' | 'issue-closed' | 'ci-failed' | 'ci-passed' | 'changes-requested' | 'approved';
+interface TrackerEvent {
+    type: TrackerEventType;
+    issueId: string;
+    timestamp: Date;
+    data: Record<string, unknown>;
+}
+interface SCMPlugin extends PluginModule {
+    type: 'scm';
+    createBranch(baseBranch: string, newBranch: string): Promise<void>;
+    commitAndPush(branch: string, message: string): Promise<string>;
+    createPullRequest(title: string, description: string, head: string, base: string): Promise<PRInfo>;
+    getPRStatus(prId: string): Promise<PRStatus>;
+    getPRComments(prId: string): Promise<PRComment[]>;
+    getCIRuns(prId: string): Promise<CIRun[]>;
+    mergePR(prId: string, method?: 'merge' | 'squash' | 'rebase'): Promise<void>;
+    onEvent(handler: (event: TrackerEvent) => void): void;
+}
+interface PRInfo {
+    id: string;
+    url: string;
+    title: string;
+    state: 'open' | 'closed' | 'merged';
+    headBranch: string;
+    baseBranch: string;
+    createdAt: Date;
+}
+interface PRStatus {
+    id: string;
+    state: 'open' | 'closed' | 'merged';
+    mergeable: boolean;
+    ciStatus: 'pending' | 'passing' | 'failing' | 'unknown';
+    reviewStatus: 'approved' | 'changes-requested' | 'pending' | 'none';
+}
+interface PRComment {
+    id: string;
+    author: string;
+    body: string;
+    file?: string;
+    line?: number;
+    createdAt: Date;
+}
+interface CIRun {
+    id: string;
+    name: string;
+    status: 'queued' | 'in_progress' | 'completed';
+    conclusion: 'success' | 'failure' | 'cancelled' | 'skipped' | null;
+    url: string;
+}
+interface NotifierPlugin extends PluginModule {
+    type: 'notifier';
+    notify(level: 'info' | 'warn' | 'error' | 'success', title: string, message: string): Promise<void>;
+}
+interface TerminalPlugin extends PluginModule {
+    type: 'terminal';
+    attach(sessionId: string): Promise<void>;
+    detach(sessionId: string): Promise<void>;
+    write(sessionId: string, data: string): Promise<void>;
+    onData(sessionId: string, handler: (data: string) => void): void;
+}
+interface EventBus {
+    emit(event: string, data: unknown): void;
+    on(event: string, handler: (data: unknown) => void): void;
+    off(event: string, handler: (data: unknown) => void): void;
+    once(event: string, handler: (data: unknown) => void): void;
+}
+interface ReactionConfig {
+    'ci-failed': ReactionRule;
+    'changes-requested': ReactionRule;
+    'approved-and-green': ReactionRule;
+}
+interface ReactionRule {
+    auto: boolean;
+    action: 'fix' | 'notify' | 'escalate' | 'skip';
+    retries: number;
+    escalateAfter: number;
+}
+interface ProviderRouting {
+    primary: AgentProvider;
+    fallback?: AgentProvider[];
+    concurrentLimit?: number;
+    costLimit?: number;
+}
+type TaskNodeStatus = 'pending' | 'decomposing' | 'ready' | 'in_progress' | 'blocked' | 'review' | 'done' | 'failed';
+type TaskOrigin = 'user' | 'agent' | 'subagent';
+interface TaskNode {
+    id: string;
+    title: string;
+    description: string;
+    status: TaskNodeStatus;
+    parentId: string | null;
+    depth: number;
+    dependsOn: string[];
+    createdBy: TaskOrigin;
+    createdByAgentId?: string;
+    assignedAgentId?: string | null;
+    worktreePath?: string | null;
+    skillsUsed: string[];
+    commandsExecuted: CommandExecution[];
+    result?: TaskResult;
+    proposedBy?: string;
+    proposedReason?: string;
+    createdAt: Date;
+    updatedAt: Date;
+}
+interface CommandExecution {
+    command: string;
+    timestamp: Date;
+    exitCode: number | null;
+    output?: string;
+}
+interface TaskResult {
+    summary: string;
+    prUrl?: string;
+    filesChanged?: string[];
+    newTasksProposed: string[];
+}
+interface TaskGraph {
+    id: string;
+    rootTaskId: string;
+    projectName: string;
+    nodes: Map<string, TaskNode>;
+    status: 'decomposing' | 'executing' | 'completed' | 'failed';
+    createdAt: Date;
+    updatedAt: Date;
+}
+interface DecompositionConfig {
+    maxTaskGraphDepth: number;
+    maxAgentSpawnDepth: number;
+    maxNodesPerGraph: number;
+    plannerProvider?: string;
+    plannerModel?: string;
+}
+interface SchedulerConfig {
+    maxConcurrentAgents: number | 'auto';
+    retryOnFailure: number;
+    providerFallbackChain: string[];
+    maxAfkDurationHours?: number;
+}
+interface GovernanceConfig {
+    autoApproveProposedTasks: boolean;
+    autoApproveCategories: string[];
+    duplicateSimilarityThreshold: number;
+}
+type ApprovalAxis = 'task-origin-gate' | 'action-risk-gate';
+type ApprovalStatus = 'pending' | 'approved' | 'rejected' | 'escalated';
+interface ApprovalItem {
+    id: string;
+    axis: ApprovalAxis;
+    taskId: string;
+    agentId?: string;
+    title: string;
+    description: string;
+    riskLevel?: 'low' | 'medium' | 'high';
+    proposedBy?: string;
+    reason?: string;
+    status: ApprovalStatus;
+    createdAt: Date;
+    expiresAt?: Date;
+    defaultAction?: 'approve' | 'skip' | 'escalate';
+}
+type AgentEventType = 'skill_invoked' | 'command_executed' | 'file_changed' | 'task_proposed' | 'status_changed';
+interface AgentEvent {
+    eventType: AgentEventType;
+    agentId: string;
+    taskId: string;
+    timestamp: Date;
+    payload: Record<string, unknown>;
+}
+interface CostGuardConfig {
+    budgetLimitUSD?: number;
+    trackByProvider: boolean;
+    trackByProject: boolean;
+    trackByTaskNode: boolean;
+}
+interface ProviderCostEntry {
+    provider: string;
+    taskId: string;
+    projectName: string;
+    tokensIn: number;
+    tokensOut: number;
+    estimatedCostUSD: number;
+    timestamp: Date;
+}
+type ExtensionType = 'agent-backend' | 'skill' | 'plugin' | 'action-adapter' | 'library' | 'mcp-server';
+type PermissionAxis = 'fileSystem' | 'network' | 'shell' | 'secrets';
+type PermissionLevel = 'none' | 'read-only' | 'read-write' | 'scoped' | 'full';
+interface ExtensionManifest {
+    name: string;
+    type: ExtensionType;
+    version: string;
+    speexorApiVersion: string;
+    permissions: ExtensionPermissions;
+    entry: string;
+    description: string;
+    author: string;
+    signature?: string;
+}
+interface ExtensionPermissions {
+    fileSystem: PermissionLevel;
+    network: PermissionLevel;
+    shell: PermissionLevel;
+    secrets: string[];
+}
+interface WorktreeHierarchyConfig {
+    pinToCommitHash: boolean;
+    serializeMerges: boolean;
+    conflictEscalatesToApproval: boolean;
+}
+interface DecisionLogEntry {
+    id: string;
+    taskId: string;
+    agentId: string;
+    action: string;
+    confidence: number;
+    wasAutoExecuted: boolean;
+    approvedBy?: 'user' | 'auto';
+    outcome?: 'correct' | 'incorrect' | 'partial' | 'unknown';
+    outcomeLabeledBy?: 'user' | 'llm-judge';
+    createdAt: Date;
+}
+interface SpeexorConfig {
+    version: '1' | '2' | '3' | '4' | '5';
+    dataDir?: string;
+    projects: ProjectConfig[];
+    decomposition?: DecompositionConfig;
+    scheduler?: SchedulerConfig;
+    governance?: GovernanceConfig;
+    riskPolicy?: RiskPolicyConfig;
+    worktreeHierarchy?: WorktreeHierarchyConfig;
+    costGuard?: CostGuardConfig;
+    extensions?: ExtensionsConfig;
+    security?: SecurityConfig;
+    performance?: PerformanceConfig;
+    logging?: LoggingConfig;
+}
+interface RiskPolicyConfig {
+    autoApprove: string[];
+    requireApproval: string[];
+    approvalTimeout: string;
+    approvalDefaultAction: 'approve' | 'skip' | 'escalate';
+    budgetLimitUSD?: number;
+    defaultRiskTierForUnknownActions: 'low' | 'medium' | 'high-stakes';
+}
+interface ExtensionsConfig {
+    marketplaceIndex?: string;
+    enabled: string[];
+    permissionsMode: 'strict' | 'relaxed';
+}
+interface SecurityConfig {
+    secretsBackend: 'os-keychain' | 'file';
+    encryptAtRest: boolean;
+    sandboxModel: 'process' | 'isolated-vm';
+}
+interface PerformanceConfig {
+    maxConcurrentAgents: number | 'auto';
+    workerThreadPoolSize: number;
+}
+interface LoggingConfig {
+    level: 'error' | 'warn' | 'info' | 'debug' | 'trace';
+}
+interface RollbackRecord {
+    approvalId: string;
+    taskId: string;
+    action: string;
+    reason: string;
+    rolledBackAt: Date;
+    success: boolean;
+    error?: string;
+}
+interface ProjectConfig {
+    name: string;
+    repository: string;
+    path?: string;
+    branch?: string;
+    provider: ProviderRouting;
+    reactions?: Partial<ReactionConfig>;
+    plugins?: {
+        tracker?: string;
+        scm?: string;
+        runtime?: string;
+        notifier?: string;
+    };
+}
+interface SpeexorState {
+    sessions: AgentSession[];
+    worktrees: WorktreeSession[];
+    runtimes: RuntimeSession[];
+    projects: ProjectConfig[];
+}
+type SessionEventType = 'session:created' | 'session:status-changed' | 'session:completed' | 'session:failed' | 'worktree:created' | 'worktree:removed' | 'reaction:triggered' | 'reaction:completed' | 'task:created' | 'task:status-changed' | 'task:completed' | 'task:blocked' | 'agent:event' | 'approval:created' | 'approval:resolved' | 'cost:recorded' | 'cost:warning' | 'cost:exceeded' | 'session:afk-warning' | 'error';
+
+export type { TaskNodeStatus as $, AgentSession as A, PluginSlot as B, CIRun as C, DecisionLogEntry as D, EventBus as E, ProviderRouting as F, GovernanceConfig as G, ReactionConfig as H, ReactionRule as I, RiskPolicyConfig as J, RollbackRecord as K, LoggingConfig as L, RuntimePlugin as M, NotifierPlugin as N, RuntimeType as O, PluginModule as P, SCMPlugin as Q, RuntimeSession as R, SpeexorState as S, TaskGraph as T, SchedulerConfig as U, SecurityConfig as V, WorktreeSession as W, SessionEventType as X, SessionStatus as Y, SpeexorConfig as Z, TaskNode as _, ProviderCostEntry as a, TaskOrigin as a0, TaskResult as a1, TerminalPlugin as a2, TrackerEventType as a3, TrackerFilter as a4, TrackerIssue as a5, TrackerPlugin as a6, WorkspacePlugin as a7, WorkspaceSession as a8, WorktreeHierarchyConfig as a9, ProjectConfig as b, AgentEvent as c, ApprovalItem as d, TrackerEvent as e, AgentEventType as f, AgentPlugin as g, AgentProvider as h, AgentStatus as i, AgentTask as j, ApprovalAxis as k, ApprovalStatus as l, CommandExecution as m, CostGuardConfig as n, DecompositionConfig as o, ExtensionManifest as p, ExtensionPermissions as q, ExtensionType as r, ExtensionsConfig as s, PRComment as t, PRInfo as u, PRStatus as v, PerformanceConfig as w, PermissionAxis as x, PermissionLevel as y, PluginContext as z };

package/docs/PRD03.md

@@ -0,0 +1,119 @@
+# PRD: Speexor v3 — "Never-Ask, Always-Decide" Autonomy Layer
+
+**Codename:** Speexor — Autonomous Decision Engine
+**Version:** 3.0 — Pengembangan dari v2
+**Author:** Aditya (drafted with Claude)
+**Date:** June 30, 2026
+**Status:** Reconstructed (original file was lost — restored from PRD04/PRD05 cross-references and architectural context)
+
+> **⚠️ REKONSTRUKSI RETROAKTIF:** Dokumen ini direkonstruksi dari referensi di PRD04 dan PRD05 setelah file asli `PRD03.md` ditemukan kosong (0 byte) saat audit PRD06. Konten here mewakili fitur-fitur v3 yang dirujuk oleh PRD04 dan PRD05, direkonstruksi berdasarkan konteks arsitektur dan kebutuhan produk. Lihat PRD06 C1 untuk detail.
+
+---
+
+## 1. Apa yang Berubah dari v2
+
+| Aspek | v2 | v3 |
+|---|---|---|
+| Keputusan | Task graph dihasilkan otomatis, tapi masih butuh approval manusia untuk banyak titik | **Never-Ask, Always-Decide** — agent membuat keputusan secara otonom berdasarkan confidence score dan risk classification |
+| Interupsi | Tidak ada mekanisme interupsi — agent berjalan sampai selesai atau gagal | **Interrupt/Override Protocol** — user bisa menginterupsi agent di tengah jalan, mengubah arah, atau membatalkan dengan graceful handoff |
+| Universal actions | Terbatas pada coding任务 (read/write file, git operations) | **Universal Action Layer** — agent bisa melakukan aksi di luar coding: dokumentasi, web scraping, komunikasi, scheduling |
+| Notification | Desktop notification pasif | **Multi-channel proactive communication** — agent bisa mengirim update, meminta klarifikasi, dan melapor via Slack/Discord/Telegram |
+| Session management | Manual start/stop | **Persistent background daemon** — sesi berjalan terus meski terminal ditutup, auto-restart on crash |
+
+---
+
+## 2. Tujuan Produk v3
+
+| # | Goal | Metrik Keberhasilan |
+|---|---|---|
+| G1 | Agent mengambil keputusan sendiri tanpa bertanya untuk >80% aksi rutin | ≥80% aksi berjalan otomatis tanpa intervensi manusia |
+| G2 | User bisa menginterupsi agent kapan saja dengan aman | Interupsi menghasilkan state konsisten (tidak ada half-written files) dalam <5 detik |
+| G3 | Agent bisa melakukan aksi non-coding (dokumen, web, komunikasi) | ≥3 action adapter terimplementasi: Document, Web/Browser, Communication |
+
+---
+
+## 3. Konsep Inti: Never-Ask Decision Engine
+
+### 3.1 Decision Ladder
+
+Setiap keputusan agent dievaluasi dalam 4 tingkat:
+
+1. **Confidence Scoring** — agent memberikan confidence score (0.0-1.0) untuk setiap keputusan
+2. **Risk Classification** — setiap aksi diklasifikasikan sebagai `reversible-low`, `reversible-medium`, `irreversible-high-stakes`
+3. **Auto-Execute Threshold** — jika confidence > threshold DAN risk = low/medium, eksekusi otomatis
+4. **Human Gate** — jika confidence < threshold ATAU risk = high-stakes, minta approval
+
+### 3.2 Confidence Threshold Configuration
+
+Dikonfigurasi per project di `speexor.config.yaml`:
+
+```yaml
+decision:
+  confidenceThreshold: 0.8
+  riskClassification:
+    autoApprove: ["reversible-low", "reversible-medium"]
+    requireApproval: ["irreversible-high-stakes"]
+  approvalTimeout: 4h
+  approvalDefaultAction: "skip"
+```
+
+---
+
+## 4. Interrupt/Override Protocol
+
+- **Graceful Handoff**: Agent menyelesaikan Atomic Unit of Work (1 fungsi, 1 file edit, 1 commit) sebelum pause
+- **Interrupt Levels**: `pause` (selesai AUW lalu pause), `redirect` (ganti task), `cancel` (batalkan + cleanup), `hard-stop` (kill paksa, hanya darurat)
+- **State Checkpoint**: Setiap interrupt menghasilkan checkpoint yang bisa di-resume nanti
+
+---
+
+## 5. Universal Action Layer
+
+Action Adapters adalah plugin type baru (slot ke-8 implisit) yang memungkinkan agent melakukan:
+
+| Action Type | Contoh | Status di v3 |
+|---|---|---|
+| Document | Menulis dokumentasi API, README, changelog | ✅ Implemented |
+| Web/Browser | Scrape web, cek dokumentasi, test UI | ✅ Implemented |
+| Communication | Kirim notifikasi ke Slack/Discord/Telegram | 🔄 Partial (desktop only) |
+| Scheduling | Buat reminder, jadwalkan task | 📅 Planned |
+
+---
+
+## 6. Perubahan Arsitektur
+
+| Komponen Baru | Tanggung Jawab |
+|---|---|
+| DecisionEngine | Confidence scoring, risk classification, auto-execute gating |
+| ActionAdapterPlugin | Interface untuk universal action adapters |
+| CheckpointManager | State persistence untuk resume/interrupt |
+| SessionDaemon | Background process management, auto-restart |
+
+---
+
+## 7. Referensi di PRD04 & PRD05
+
+PRD04 dan PRD05 merujuk ke v3 untuk:
+
+- **Action Adapters** (PRD04 §5.1) — sebagai extension type ke-4
+- **Decision Engine & Confidence Scoring** (PRD05 §3.2/3.3) — di-refine menjadi unified Approval Model
+- **Graceful Handoff** (PRD05 §3.4) — digunakan dalam Worktree Hierarchy Protocol
+- **Simple Mode** (PRD04 §10.3) — toggle UI complexity
+- **maxAfkDurationHours** (PRD05 §4.7) — session guard configuration
+
+---
+
+## 8. Status Implementasi
+
+| Komponen | Status | Catatan |
+|---|---|---|
+| Decision Engine | ✅ Implemented | GovernanceEngine + ApprovalManager |
+| Confidence Scoring | ✅ Implemented | CalibrationAnalyzer + DecisionLog |
+| Action Adapters | 🔄 Partial | Document adapter di extension-manager |
+| Checkpoint Manager | 🔄 Partial | TaskGraph store sudah ada checkpoint |
+| Session Daemon | ✅ Implemented | Scheduler + SessionGuard |
+| Interrupt Protocol | 📅 Not yet | Worktree Hierarchy Protocol sudah mencakup bagian merge interrupt |
+
+---
+
+*Dokumen ini direkonstruksi untuk menjaga kontinuitas rantai keputusan produk. Lihat PRD04 untuk platform layer di atas v1-v3, dan PRD05 untuk gap analysis yang mengoreksi v1-v4.*