archbyte 0.6.0 → 0.7.0

package/dist/agents/observability/reader.js

@@ -0,0 +1,86 @@
+// Session Reader — reads session data from .archbyte/sessions/
+import { readFile, readdir } from "fs/promises";
+import { existsSync, readFileSync } from "fs";
+import path from "path";
+function sessionsDir(projectRoot) {
+    return path.join(projectRoot, ".archbyte", "sessions");
+}
+/** Load session index — reads index.json, or scans session dirs if missing */
+export async function loadSessionIndex(projectRoot) {
+    const dir = sessionsDir(projectRoot);
+    const indexPath = path.join(dir, "index.json");
+    // Try cached index first
+    if (existsSync(indexPath)) {
+        try {
+            const raw = readFileSync(indexPath, "utf-8");
+            return JSON.parse(raw);
+        }
+        catch {
+            // Corrupted — rebuild
+        }
+    }
+    // Scan session directories
+    return rebuildIndex(projectRoot);
+}
+/** Rebuild index by scanning all session dirs */
+async function rebuildIndex(projectRoot) {
+    const dir = sessionsDir(projectRoot);
+    if (!existsSync(dir))
+        return { sessions: [] };
+    const entries = await readdir(dir, { withFileTypes: true });
+    const sessions = [];
+    for (const entry of entries) {
+        if (!entry.isDirectory())
+            continue;
+        const sessionPath = path.join(dir, entry.name, "session.json");
+        if (!existsSync(sessionPath))
+            continue;
+        try {
+            const raw = await readFile(sessionPath, "utf-8");
+            const session = JSON.parse(raw);
+            sessions.push({
+                sessionId: session.sessionId,
+                startedAt: session.startedAt,
+                completedAt: session.completedAt,
+                status: session.status,
+                runCount: session.summary.totalRuns,
+                phases: session.summary.phases,
+                source: session.source,
+            });
+        }
+        catch {
+            // Skip corrupted session files
+        }
+    }
+    // Sort newest first
+    sessions.sort((a, b) => new Date(b.startedAt).getTime() - new Date(a.startedAt).getTime());
+    return { sessions };
+}
+/** Load a full session by ID */
+export async function loadSession(projectRoot, sessionId) {
+    const sessionPath = path.join(sessionsDir(projectRoot), sessionId, "session.json");
+    if (!existsSync(sessionPath))
+        return null;
+    try {
+        const raw = await readFile(sessionPath, "utf-8");
+        return JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+}
+/** Read recent activity log entries (newest first) */
+export async function loadRecentActivity(projectRoot, limit = 50) {
+    const logPath = path.join(sessionsDir(projectRoot), "activity.log");
+    if (!existsSync(logPath))
+        return [];
+    try {
+        const raw = await readFile(logPath, "utf-8");
+        const lines = raw.trim().split("\n").filter(Boolean);
+        // Return newest first, limited
+        return lines.slice(-limit).reverse();
+    }
+    catch {
+        return [];
+    }
+}

package/dist/agents/observability/types.d.ts

@@ -0,0 +1,125 @@
+export interface TranscriptEvent {
+    timestamp: string;
+    type: 'user' | 'assistant' | 'thinking' | 'tool_use' | 'tool_result' | 'system';
+    agentId?: string;
+    agentSlug?: string;
+    text?: string;
+    toolName?: string;
+    toolUseId?: string;
+    toolInput?: string;
+    toolResult?: string;
+    toolSuccess?: boolean;
+    model?: string;
+    usage?: {
+        inputTokens: number;
+        outputTokens: number;
+        cacheReadTokens: number;
+        cacheCreationTokens: number;
+    };
+}
+export interface CloudStats {
+    totalInputTokens: number;
+    totalOutputTokens: number;
+    totalCacheReadTokens: number;
+    totalCacheCreationTokens: number;
+    estimatedCost: {
+        input: number;
+        output: number;
+        cacheRead: number;
+        cacheCreation: number;
+        total: number;
+    };
+    models: string[];
+    apiCalls: number;
+}
+export interface PayloadFile {
+    path: string;
+    timestamp: string;
+    agentId?: string;
+}
+export interface AgentRun {
+    runId: string;
+    sessionId: string;
+    phase: string;
+    passId: string;
+    agent: string;
+    model: string;
+    iteration: number;
+    startedAt: string;
+    completedAt?: string;
+    elapsedSeconds?: number;
+    status: "running" | "success" | "error" | "skipped";
+    error?: string;
+    tokens?: {
+        input: number;
+        output: number;
+    };
+    cost?: {
+        input: number;
+        output: number;
+        total: number;
+    };
+    toolCalls?: Array<{
+        name: string;
+        durationMs: number;
+        success: boolean;
+    }>;
+    artifacts?: {
+        prompt?: string;
+        output?: string;
+        error?: string;
+    };
+    agentType?: string;
+    transcript?: TranscriptEvent[];
+}
+export interface AgentSession {
+    sessionId: string;
+    projectName?: string;
+    startedAt: string;
+    completedAt?: string;
+    status: "running" | "success" | "error" | "partial";
+    source: string;
+    projectMeta?: {
+        topic?: string;
+        mode?: string;
+        model?: string;
+        style?: string;
+    };
+    summary: {
+        totalRuns: number;
+        successfulRuns: number;
+        failedRuns: number;
+        skippedRuns: number;
+        totalElapsedSeconds: number;
+        totalTokens: {
+            input: number;
+            output: number;
+        };
+        phases: string[];
+        models: string[];
+    };
+    runs: AgentRun[];
+    transcript?: TranscriptEvent[];
+    cloudStats?: CloudStats;
+    payload?: PayloadFile[];
+}
+export interface SessionIndex {
+    sessions: Array<{
+        sessionId: string;
+        startedAt: string;
+        completedAt?: string;
+        status: AgentSession["status"];
+        runCount: number;
+        phases: string[];
+        source: string;
+        category?: string;
+        label?: string;
+        touchedDirs?: string[];
+        eventCount?: number;
+        dirMetrics?: Record<string, {
+            reads: number;
+            writes: number;
+        }>;
+        estimatedCost?: number;
+    }>;
+}

package/dist/agents/observability/types.js

@@ -0,0 +1,3 @@
+// Agent Session Observability — generic schema
+// Any agent framework (archbyte pipeline, custom) emits these types.
+export {};

package/dist/agents/observability/writer.d.ts

@@ -0,0 +1,9 @@
+import type { AgentRun, AgentSession } from "./types.js";
+export declare function createSession(projectRoot: string, sessionId: string, opts?: {
+    projectName?: string;
+    source?: string;
+}): Promise<AgentSession>;
+export declare function writeRun(projectRoot: string, sessionId: string, run: AgentRun): Promise<void>;
+export declare function completeSession(projectRoot: string, sessionId: string, runs: AgentRun[]): Promise<void>;
+export declare function updateSessionIndex(projectRoot: string): Promise<void>;
+export declare function appendActivityLog(projectRoot: string, entry: Record<string, unknown>): Promise<void>;

package/dist/agents/observability/writer.js

@@ -0,0 +1,100 @@
+// Session Writer — writes session data to .archbyte/sessions/
+import { mkdir, writeFile, appendFile } from "fs/promises";
+import path from "path";
+import { loadSessionIndex } from "./reader.js";
+function sessionsDir(projectRoot) {
+    return path.join(projectRoot, ".archbyte", "sessions");
+}
+export async function createSession(projectRoot, sessionId, opts) {
+    const dir = path.join(sessionsDir(projectRoot), sessionId);
+    await mkdir(path.join(dir, "runs"), { recursive: true });
+    const session = {
+        sessionId,
+        projectName: opts?.projectName,
+        startedAt: new Date().toISOString(),
+        status: "running",
+        source: opts?.source ?? "archbyte",
+        summary: {
+            totalRuns: 0,
+            successfulRuns: 0,
+            failedRuns: 0,
+            skippedRuns: 0,
+            totalElapsedSeconds: 0,
+            totalTokens: { input: 0, output: 0 },
+            phases: [],
+            models: [],
+        },
+        runs: [],
+    };
+    await writeFile(path.join(dir, "session.json"), JSON.stringify(session, null, 2), "utf-8");
+    return session;
+}
+export async function writeRun(projectRoot, sessionId, run) {
+    const runDir = path.join(sessionsDir(projectRoot), sessionId, "runs", run.runId);
+    await mkdir(runDir, { recursive: true });
+    await writeFile(path.join(runDir, "meta.json"), JSON.stringify(run, null, 2), "utf-8");
+    // Write optional artifacts
+    if (run.artifacts?.prompt) {
+        await writeFile(path.join(runDir, "prompt.md"), run.artifacts.prompt, "utf-8");
+    }
+    if (run.artifacts?.output) {
+        await writeFile(path.join(runDir, "output.md"), run.artifacts.output, "utf-8");
+    }
+    if (run.artifacts?.error) {
+        await writeFile(path.join(runDir, "error.txt"), run.artifacts.error, "utf-8");
+    }
+    // Append to activity log
+    await appendActivityLog(projectRoot, {
+        type: "run",
+        sessionId,
+        runId: run.runId,
+        agent: run.agent,
+        status: run.status,
+        timestamp: run.completedAt ?? run.startedAt,
+    });
+}
+export async function completeSession(projectRoot, sessionId, runs) {
+    const dir = path.join(sessionsDir(projectRoot), sessionId);
+    const successfulRuns = runs.filter((r) => r.status === "success").length;
+    const failedRuns = runs.filter((r) => r.status === "error").length;
+    const skippedRuns = runs.filter((r) => r.status === "skipped").length;
+    const totalElapsed = runs.reduce((s, r) => s + (r.elapsedSeconds ?? 0), 0);
+    const totalTokensIn = runs.reduce((s, r) => s + (r.tokens?.input ?? 0), 0);
+    const totalTokensOut = runs.reduce((s, r) => s + (r.tokens?.output ?? 0), 0);
+    const phases = [...new Set(runs.map((r) => r.phase))];
+    const models = [...new Set(runs.map((r) => r.model))];
+    const hasErrors = failedRuns > 0;
+    const allFailed = failedRuns === runs.length;
+    const session = {
+        sessionId,
+        startedAt: runs[0]?.startedAt ?? new Date().toISOString(),
+        completedAt: new Date().toISOString(),
+        status: allFailed ? "error" : hasErrors ? "partial" : "success",
+        source: "archbyte",
+        summary: {
+            totalRuns: runs.length,
+            successfulRuns,
+            failedRuns,
+            skippedRuns,
+            totalElapsedSeconds: totalElapsed,
+            totalTokens: { input: totalTokensIn, output: totalTokensOut },
+            phases,
+            models,
+        },
+        runs,
+    };
+    await writeFile(path.join(dir, "session.json"), JSON.stringify(session, null, 2), "utf-8");
+    // Rebuild index
+    await updateSessionIndex(projectRoot);
+}
+export async function updateSessionIndex(projectRoot) {
+    const index = await loadSessionIndex(projectRoot);
+    await mkdir(sessionsDir(projectRoot), { recursive: true });
+    await writeFile(path.join(sessionsDir(projectRoot), "index.json"), JSON.stringify(index, null, 2), "utf-8");
+}
+export async function appendActivityLog(projectRoot, entry) {
+    const logPath = path.join(sessionsDir(projectRoot), "activity.log");
+    await mkdir(sessionsDir(projectRoot), { recursive: true });
+    const line = JSON.stringify({ ...entry, _ts: new Date().toISOString() }) + "\n";
+    await appendFile(logPath, line, "utf-8");
+}

package/dist/agents/pipeline/index.d.ts

@@ -6,7 +6,7 @@ import type { IncrementalContext } from "./types.js";
  * Run the multi-agent pipeline: 3 parallel fast agents → 2 sequential agents.
  * Each agent gets a single chat() call with pre-collected static context.
  */
-export declare function runPipeline(ctx: StaticContext, provider: LLMProvider, config: ArchByteConfig, onProgress?: (msg: string) => void, incrementalContext?: IncrementalContext, onDebug?: (agentId: string, model: string, system: string, user: string) => void): Promise<StaticAnalysisResult & {
+export declare function runPipeline(ctx: StaticContext, provider: LLMProvider, config: ArchByteConfig, onProgress?: (msg: string) => void, incrementalContext?: IncrementalContext, onDebug?: (agentId: string, model: string, system: string, user: string) => void, projectRoot?: string): Promise<StaticAnalysisResult & {
     tokenUsage?: {
         input: number;
         output: number;

package/dist/agents/pipeline/index.js

@@ -1,5 +1,7 @@
 // Pipeline — Orchestrator
 // Runs static context collection → parallel LLM agents → sequential LLM agents
+import { writeFile, mkdir } from "fs/promises";
+import path from "path";
 import { resolveModel } from "../runtime/types.js";
 import { validateAnalysis } from "../static/validator.js";
 import { componentIdentifier } from "./agents/component-identifier.js";
@@ -92,14 +94,40 @@ function getFallbackData(agentId, inc) {
  * Run the multi-agent pipeline: 3 parallel fast agents → 2 sequential agents.
  * Each agent gets a single chat() call with pre-collected static context.
  */
-export async function runPipeline(ctx, provider, config, onProgress, incrementalContext, onDebug) {
+export async function runPipeline(ctx, provider, config, onProgress, incrementalContext, onDebug, projectRoot) {
     const agentResults = {};
     const agentMeta = [];
     const skippedAgents = [];
+    const sessionId = `archbyte-${Date.now()}`;
+    const sessionRuns = [];
     // Pass incremental context to agents via priorResults
     if (incrementalContext) {
         agentResults["__incremental__"] = incrementalContext;
     }
+    // Helper: record an agent run for session observability
+    function recordRun(agent, result, status, error) {
+        const model = resolveModel(config.provider, agent.modelTier, config.modelOverrides, config.model);
+        const run = {
+            runId: `${agent.id}-${Date.now()}`,
+            sessionId,
+            phase: agent.id === "connection-mapper" || agent.id === "validator" ? "sequential" : "parallel",
+            passId: agent.id,
+            agent: agent.name,
+            model,
+            iteration: 1,
+            startedAt: result ? new Date(Date.now() - result.duration).toISOString() : new Date().toISOString(),
+            completedAt: new Date().toISOString(),
+            elapsedSeconds: result ? result.duration / 1000 : 0,
+            status,
+            error,
+            tokens: result?.tokenUsage ? { input: result.tokenUsage.input, output: result.tokenUsage.output } : undefined,
+            artifacts: result?.prompt || result?.rawOutput ? {
+                ...(result.prompt ? { prompt: result.prompt } : {}),
+                ...(result.rawOutput ? { output: result.rawOutput } : {}),
+            } : undefined,
+        };
+        sessionRuns.push(run);
+    }
     // === Phase 1: Parallel agents ===
     onProgress?.(`Phase 1: Running ${PARALLEL_AGENTS.length} agents in parallel...`);
     // Pass agentResults to parallel agents too (contains __incremental__ if set)
@@ -123,17 +151,21 @@ export async function runPipeline(ctx, provider, config, onProgress, incremental
     let authFailed = false;
     for (let i = 0; i < parallelTasks.length; i++) {
         const { agent, skipReason } = parallelTasks[i];
-        if (skipReason)
-            continue; // Already handled
+        if (skipReason) {
+            recordRun(agent, null, "skipped");
+            continue;
+        }
         const result = parallelResults[i];
         if (result.status === "fulfilled" && result.value) {
             agentResults[agent.id] = result.value.data;
             agentMeta.push(result.value);
             onProgress?.(`  ${agent.name}: done (${(result.value.duration / 1000).toFixed(1)}s)`);
+            recordRun(agent, result.value, "success");
         }
         else {
             const reason = result.status === "rejected" ? result.reason : "null response";
             onProgress?.(`  ${agent.name}: failed (${reason})`);
+            recordRun(agent, null, "error", String(reason));
             if (result.status === "rejected" && isAuthError(result.reason)) {
                 authFailed = true;
             }
@@ -153,6 +185,7 @@ export async function runPipeline(ctx, provider, config, onProgress, incremental
             onProgress?.(`  ${agent.name}: skipped (${skipReason})`);
             const fallback = getFallbackData(agent.id, incrementalContext);
             agentResults[agent.id] = fallback;
+            recordRun(agent, null, "skipped");
             continue;
         }
         try {
@@ -161,13 +194,16 @@ export async function runPipeline(ctx, provider, config, onProgress, incremental
                 agentResults[agent.id] = result.data;
                 agentMeta.push(result);
                 onProgress?.(`  ${agent.name}: done (${(result.duration / 1000).toFixed(1)}s)`);
+                recordRun(agent, result, "success");
             }
             else {
                 onProgress?.(`  ${agent.name}: returned null`);
+                recordRun(agent, null, "error", "returned null");
             }
         }
         catch (err) {
             onProgress?.(`  ${agent.name}: failed (${err instanceof Error ? err.message : String(err)})`);
+            recordRun(agent, null, "error", err instanceof Error ? err.message : String(err));
             if (isAuthError(err)) {
                 throw new Error(`API key authentication failed. Check your API key with: archbyte config set api-key <your-key>\n` +
                     `  Current provider: ${config.provider}. Get a valid key from your provider's dashboard.`);
@@ -204,6 +240,50 @@ export async function runPipeline(ctx, provider, config, onProgress, incremental
         console.error();
         onProgress?.(`Token usage: ${totalInput} in / ${totalOutput} out${skippedAgents.length > 0 ? ` (${skippedAgents.length} skipped)` : ""}`);
     }
+    // === Write runs to .archbyte/runs/ (best-effort, fire-and-forget) ===
+    if (projectRoot) {
+        const sessionStartedAt = sessionRuns.length > 0
+            ? sessionRuns.reduce((earliest, r) => r.startedAt < earliest ? r.startedAt : earliest, sessionRuns[0].startedAt)
+            : new Date().toISOString();
+        const sessionCompletedAt = new Date().toISOString();
+        const writeRuns = async () => {
+            const runsDir = path.join(projectRoot, ".archbyte", "runs");
+            for (const run of sessionRuns) {
+                const agentDir = path.join(runsDir, run.passId);
+                await mkdir(agentDir, { recursive: true });
+                // meta.json — AgentRun fields minus artifacts
+                const { artifacts, ...meta } = run;
+                await writeFile(path.join(agentDir, "meta.json"), JSON.stringify(meta, null, 2));
+                // prompt.md and output.md from artifacts
+                if (artifacts?.prompt) {
+                    await writeFile(path.join(agentDir, "prompt.md"), artifacts.prompt);
+                }
+                if (artifacts?.output) {
+                    await writeFile(path.join(agentDir, "output.md"), artifacts.output);
+                }
+            }
+            // session.json — lightweight summary
+            const successCount = sessionRuns.filter(r => r.status === "success").length;
+            const failedCount = sessionRuns.filter(r => r.status === "error").length;
+            const session = {
+                sessionId,
+                startedAt: sessionStartedAt,
+                completedAt: sessionCompletedAt,
+                status: failedCount > 0 ? "partial" : "success",
+                source: "archbyte",
+                mode: "pipeline",
+                totalRuns: sessionRuns.length,
+                successfulRuns: successCount,
+                failedRuns: failedCount,
+                totalTokens: { input: totalInput, output: totalOutput },
+                totalElapsedSeconds: sessionRuns.reduce((s, r) => s + (r.elapsedSeconds ?? 0), 0),
+            };
+            await writeFile(path.join(projectRoot, ".archbyte", "session.json"), JSON.stringify(session, null, 2));
+        };
+        writeRuns().catch((err) => {
+            console.error("[pipeline] Failed to write runs:", err);
+        });
+    }
     return { ...merged, tokenUsage: { input: totalInput, output: totalOutput }, skippedAgents: skippedAgents.length > 0 ? skippedAgents : undefined };
 }
 // Agents that produce large structured output (lists of components/connections) need more tokens
@@ -248,5 +328,7 @@ async function runAgent(agent, ctx, provider, config, priorResults, onProgress,
         data,
         duration: Date.now() - start,
         tokenUsage: { input: response.usage.inputTokens, output: response.usage.outputTokens },
+        prompt: system + "\n\n---\n\n" + user,
+        rawOutput: text,
     };
 }

package/dist/agents/pipeline/types.d.ts

@@ -171,4 +171,6 @@ export interface PipelineAgentResult {
         input: number;
         output: number;
     };
+    prompt?: string;
+    rawOutput?: string;
 }

package/dist/cli/config.js

@@ -96,6 +96,14 @@ function showConfig() {
             console.log(`  ${chalk.bold("model")}:    ${config.model}`);
         }
     }
+    const sessionsPaths = config.sessionsPaths;
+    if (Array.isArray(sessionsPaths) && sessionsPaths.length > 0) {
+        console.log();
+        console.log(`  ${chalk.bold("sessions-path")}:`);
+        for (const p of sessionsPaths) {
+            console.log(`    ${p}`);
+        }
+    }
     console.log();
 }
 function setConfig(key, value) {
@@ -151,9 +159,15 @@ function setConfig(key, value) {
             profiles[activeProvider2].model = value;
             break;
         }
+        case "sessions-path":
+        case "sessionsPath": {
+            // External directory paths for session observability (comma-separated)
+            config.sessionsPaths = value.split(",").map((p) => p.trim()).filter(Boolean);
+            break;
+        }
         default:
             console.error(chalk.red(`Unknown config key: ${key}`));
-            console.error(chalk.gray("  Valid keys: provider, api-key, model"));
+            console.error(chalk.gray("  Valid keys: provider, api-key, model, sessions-path"));
             process.exit(1);
     }
     saveConfig(config);
@@ -182,6 +196,12 @@ function getConfig(key, raw = false) {
         case "model":
             console.log(profile?.model ?? config.model ?? "");
             break;
+        case "sessions-path":
+        case "sessionsPath": {
+            const paths = config.sessionsPaths;
+            console.log(Array.isArray(paths) ? paths.join(", ") : "");
+            break;
+        }
         default:
             console.error(chalk.red(`Unknown config key: ${key}`));
             process.exit(1);