@aexol/spectral 0.3.5 → 0.3.7

package/dist/relay/dispatcher.js

@@ -41,7 +41,7 @@
 import { BadRequestError, NotFoundError } from "../server/handlers/errors.js";
 import { handlePathAutocomplete } from "../server/handlers/paths-autocomplete.js";
 import { handleCreateProject, handleDeleteProject, handleListProjects, handleListSessionsByProject, handleUpdateProject, } from "../server/handlers/projects.js";
-import { handleCreateSession, handleDeleteSession, handleGetSessionDetail, handleUpdateSession, } from "../server/handlers/sessions.js";
+import { handleCreateSession, handleDeleteSession, handleForkSession, handleGetSessionDetail, handleUpdateSession, } from "../server/handlers/sessions.js";
 import { shutdownState } from "../server/shutdown.js";
 /**
  * Inline path matcher. Returns `null` for any path/method combination we
@@ -103,6 +103,14 @@ export function matchRoute(method, path) {
             return { route: "delete_session", id };
         return null;
     }
+    // /api/sessions/:id/fork
+    const forkMatch = /^\/api\/sessions\/([^/]+)\/fork$/.exec(cleanPath);
+    if (forkMatch) {
+        const id = decodeURIComponent(forkMatch[1]);
+        if (method === "POST")
+            return { route: "fork_session", id };
+        return null;
+    }
     return null;
 }
 /**
@@ -275,6 +283,15 @@ function dispatchRoute(match, body, deps) {
             }
             return { ok: true };
         }
+        case "fork_session": {
+            const session = handleForkSession(store, id, asObject(body));
+            safePublish(publishMetaEvent, logger, {
+                type: "session_created",
+                projectId: session.projectId,
+                sessionId: session.id,
+            });
+            return session;
+        }
         case "list_path_autocomplete": {
             const prefix = match.query?.get("prefix") ?? "";
             return handlePathAutocomplete(prefix);
@@ -471,6 +488,7 @@ export function handleClientMessage(frame, deps) {
                 sessionId,
                 history: attachResult.history,
                 currentTurn: attachResult.currentTurn,
+                forkCompactPending: attachResult.forkCompactPending || undefined,
             },
         });
         // Surface bridge-start failures as `error` events; otherwise the
@@ -542,6 +560,7 @@ export function handleSubscribe(frame, deps) {
             sessionId,
             history: attachResult.history,
             currentTurn: attachResult.currentTurn,
+            forkCompactPending: attachResult.forkCompactPending || undefined,
         },
     });
     if (isNewSubscriber) {

package/dist/server/handlers/sessions.js

@@ -40,3 +40,15 @@ export function handleDeleteSession(store, id) {
     if (!deleted)
         throw new NotFoundError("Session not found");
 }
+/**
+ * Fork a session: create a new session copying all messages from the
+ * source, with the `fork_compact_source_id` flag set so the
+ * SessionStreamManager compacts after the first assistant turn.
+ */
+export function handleForkSession(store, id, body) {
+    const source = store.getSession(id);
+    if (!source)
+        throw new NotFoundError("Session not found");
+    const title = typeof body.title === "string" ? body.title : undefined;
+    return store.forkSession(id, { title });
+}

package/dist/server/pi-bridge.js

@@ -740,6 +740,20 @@ export class PiBridge {
             this.opts.emit({ type: "error", message: e.message });
         }
     }
+    /**
+     * Manually compact the session context via pi's built-in compaction.
+     * Pi generates a summary of older conversation history, preserving the
+     * most recent ~20K tokens verbatim. Compaction events are forwarded to
+     * the wire through `handleEvent()`.
+     *
+     * `customInstructions` can inject guidance into the compaction prompt
+     * so the summary captures information relevant to the current task.
+     */
+    async compact(customInstructions) {
+        if (!this.session)
+            throw new Error("PiBridge.start() not called");
+        await this.session.compact(customInstructions);
+    }
     dispose() {
         if (this.disposed)
             return;
@@ -975,11 +989,30 @@ export class PiBridge {
                 this.opts.emit({ type: "agent_end" });
                 return;
             }
+            case "compaction_start": {
+                // Forward compaction lifecycle events to the wire so the browser
+                // can surface a "Compacting…" indicator and track compaction
+                // activity.
+                this.opts.emit({
+                    type: "compaction_start",
+                    reason: ev.reason,
+                });
+                return;
+            }
+            case "compaction_end": {
+                this.opts.emit({
+                    type: "compaction_end",
+                    summary: ev.result?.summary ?? "",
+                    tokensBefore: ev.result?.tokensBefore ?? 0,
+                    aborted: ev.aborted,
+                });
+                return;
+            }
             default:
-                // Other pi-internal events (turn_start, queue_update, compaction_*,
-                // auto_retry_*, tool_execution_update) are intentionally not on the
-                // wire surface for MVP and are NOT persisted — the wire format is
-                // the source of truth for replay.
+                // Other pi-internal events (turn_start, queue_update,
+                // auto_retry_*, tool_execution_update) are intentionally not on
+                // the wire surface for MVP and are NOT persisted — the wire format
+                // is the source of truth for replay.
                 return;
         }
     }

package/dist/server/session-stream.js

@@ -105,6 +105,7 @@ export class SessionStreamManager {
             history: detail.messages,
             currentTurn: stream.currentTurn ? snapshotTurn(stream.currentTurn) : null,
             ready: stream.ready,
+            forkCompactPending: stream.forkCompactSourceId != null,
         };
     }
     /**
@@ -170,6 +171,16 @@ export class SessionStreamManager {
         let stream = this.streams.get(sessionId);
         if (!stream)
             throw new Error(`No active stream for session: ${sessionId}`);
+        // Guard: block new prompts while compaction is running. Compaction
+        // takes ~1 LLM call (<5 s) and the bridge emits a clear error message
+        // so the user knows to wait a moment.
+        if (stream.compacting) {
+            this.broadcast(stream, {
+                type: "error",
+                message: "Session is being compacted. Please wait a moment and try again.",
+            });
+            return;
+        }
         // If the bridge was disposed (e.g. by cancelTurn), recreate it before
         // proceeding. We rebuild only the bridge inside the existing stream so
         // subscribers, cwd, and other metadata are preserved.
@@ -457,6 +468,60 @@ export class SessionStreamManager {
                 stream.loopIterationCount = 0;
         }
     }
+    /**
+     * Fork & Compact: trigger compaction after the first assistant turn of a
+     * forked session. Uses pi's built-in `compact()` which generates a summary
+     * of older context, retaining the most recent ~20K tokens (including the
+     * user's new message + the assistant's response).
+     *
+     * Custom instructions reference the most recent user message so the LLM
+     * summary prioritizes information relevant to the current task.
+     */
+    triggerForkCompact(stream) {
+        if (!stream.bridge.compact) {
+            console.warn(`[spectral] warn: bridge does not support compact ("Fork & Compact" skipped for ${stream.sessionId})`);
+            return;
+        }
+        stream.compacting = true;
+        // Read the most recent user message to use as guidance for the
+        // compaction summary.
+        const detail = this.store.getSession(stream.sessionId);
+        const lastUserMsg = detail?.messages
+            .filter((m) => m.role === "user")
+            .pop();
+        const guidanceMessage = lastUserMsg?.content?.trim() || "";
+        const customInstructions = guidanceMessage
+            ? `Focus the context summary on information relevant to: "${guidanceMessage}"`
+            : undefined;
+        void stream.bridge
+            .compact(customInstructions)
+            .then(() => {
+            stream.compacting = false;
+            try {
+                this.store.clearForkCompactSource(stream.sessionId);
+            }
+            catch {
+                // best-effort
+            }
+            console.log(`[spectral] fork-compact completed for ${stream.sessionId}`);
+        })
+            .catch((err) => {
+            stream.compacting = false;
+            const msg = err instanceof Error ? err.message : String(err);
+            console.error(`[spectral] fork-compact failed for ${stream.sessionId}: ${msg}`);
+            this.broadcast(stream, {
+                type: "error",
+                message: `Context compaction failed: ${msg}`,
+            });
+            // Clear the flag even on failure so it doesn't block forever.
+            try {
+                this.store.clearForkCompactSource(stream.sessionId);
+            }
+            catch {
+                // best-effort
+            }
+        });
+    }
     // --- internals ----------------------------------------------------------
     createStream(sessionId, history) {
         // Resolve cwd from the owning project. Sessions without a project
@@ -472,6 +537,7 @@ export class SessionStreamManager {
         }
         // Forward declaration so the bridge factory's emit callback can refer to
         // the stream object that's still being assembled.
+        const forkSourceId = this.store.getForkCompactSource(sessionId);
         const stream = {
             sessionId,
             cwd,
@@ -485,6 +551,8 @@ export class SessionStreamManager {
             loopActive: false,
             loopIterationCount: 0,
             loopOriginalPrompt: null,
+            forkCompactSourceId: forkSourceId ?? null,
+            compacting: false,
         };
         const bridgeOpts = {
             cwd,
@@ -637,6 +705,14 @@ export class SessionStreamManager {
                     });
                 }
             }
+            // Fork & Compact: after the first assistant turn of a forked session,
+            // compact the context. The custom instructions reference the user's
+            // new message so the summary preserves relevant context.
+            if (stream.forkCompactSourceId && !stream.compacting) {
+                const sourceId = stream.forkCompactSourceId;
+                stream.forkCompactSourceId = null; // one-shot
+                this.triggerForkCompact(stream);
+            }
         }
         else if (event.type === "error") {
             // An error event arriving outside a turn (or bubbling out of one) —

package/dist/server/storage.js

@@ -154,6 +154,9 @@ export class SessionStore {
     // Phase 3: per-session sticky model.
     stmtGetSessionModel;
     stmtSetSessionModel;
+    // Fork & Compact: flag + per-session source tracking.
+    stmtSetForkCompactSource;
+    stmtGetForkCompactSource;
     constructor(path) {
         this.path = path;
         // Make sure the parent directory exists. mkdirSync with recursive is a
@@ -208,6 +211,12 @@ export class SessionStore {
         if (!msgCols.some((c) => c.name === "images_json")) {
             this.db.exec(`ALTER TABLE messages ADD COLUMN images_json TEXT NOT NULL DEFAULT ''`);
         }
+        // Fork & Compact: fork_compact_source_id tracks which session a fork was
+        // created from. Set during forkSession(), cleared after first compaction.
+        // NULL means no fork-compact pending (normal session).
+        if (!sessionCols.some((c) => c.name === "fork_compact_source_id")) {
+            this.db.exec(`ALTER TABLE sessions ADD COLUMN fork_compact_source_id TEXT`);
+        }
         // ---- one-time cleanup -------------------------------------------------
         // Historical garbage from prior runs of the bridge that persisted every
         // intermediate `message_end` pi emitted, including pure-framing rows
@@ -277,6 +286,8 @@ export class SessionStore {
     `);
         this.stmtGetSessionModel = this.db.prepare(`SELECT model_id FROM sessions WHERE id = ?`);
         this.stmtSetSessionModel = this.db.prepare(`UPDATE sessions SET model_id = ? WHERE id = ?`);
+        this.stmtSetForkCompactSource = this.db.prepare(`UPDATE sessions SET fork_compact_source_id = ? WHERE id = ?`);
+        this.stmtGetForkCompactSource = this.db.prepare(`SELECT fork_compact_source_id FROM sessions WHERE id = ?`);
     }
     /** Smoke check: returns the names of the tables in the DB. */
     listTables() {
@@ -406,7 +417,7 @@ export class SessionStore {
         if (!row)
             return null;
         const messages = this.getMessages(id);
-        return {
+        const detail = {
             id: row.id,
             projectId: row.project_id,
             title: row.title,
@@ -414,6 +425,12 @@ export class SessionStore {
             updatedAt: row.updated_at,
             messages,
         };
+        // Expose the fork-compact flag so the UI can show a special send
+        // button for the first message of a forked session.
+        if (this.getForkCompactSource(id)) {
+            detail.forkCompactPending = true;
+        }
+        return detail;
     }
     /** Convenience for routes/managers that just need the projectId. */
     getSessionProjectId(id) {
@@ -518,6 +535,68 @@ export class SessionStore {
     setSessionModel(sessionId, modelId) {
         this.stmtSetSessionModel.run(modelId, sessionId);
     }
+    // ----------------------------------------------------------------------
+    // Fork & Compact
+    // ----------------------------------------------------------------------
+    /**
+     * Fork a session: create a new session in the same project, copy all
+     * messages from the source, and set the `fork_compact_source_id` flag
+     * so SessionStreamManager compacts the context after the first assistant
+     * turn completes.
+     */
+    forkSession(sourceId, opts) {
+        const source = this.stmtGetSession.get(sourceId);
+        if (!source)
+            throw new Error(`Unknown sessionId: ${sourceId}`);
+        // Capture project details before the transaction (needed for the touch).
+        const project = this.stmtGetProject.get(source.project_id);
+        if (!project)
+            throw new Error(`Unknown projectId: ${source.project_id}`);
+        const newId = opts?.newSessionId ?? randomUUID();
+        const title = opts?.title?.trim() || `${source.title} (fork)`;
+        const now = Date.now();
+        let messageCount = 0;
+        const tx = this.db.transaction(() => {
+            // Create the new session row.
+            this.stmtCreateSession.run(newId, source.project_id, title, now, now);
+            this.stmtSetSessionModel.run(null, newId);
+            // Copy every message, preserving created_at ordering.
+            const messages = this.stmtListMessages.all(sourceId);
+            messageCount = messages.length;
+            for (const m of messages) {
+                this.stmtAppendMessage.run(randomUUID(), newId, m.role, m.content, m.events_jsonl, m.images_json, m.created_at);
+            }
+            // Set the fork-compact flag — SessionStreamManager reads this to
+            // trigger compaction after the first assistant turn.
+            this.stmtSetForkCompactSource.run(sourceId, newId);
+            // Touch the project so the new session appears at the top.
+            this.stmtUpdateProject.run(project.name, project.path, now, project.id);
+        });
+        tx();
+        return {
+            id: newId,
+            projectId: source.project_id,
+            title,
+            createdAt: now,
+            updatedAt: now,
+            messageCount,
+        };
+    }
+    /**
+     * Read the fork-compact source id for a session, or null if the session
+     * was not forked or has already been compacted.
+     */
+    getForkCompactSource(sessionId) {
+        const row = this.stmtGetForkCompactSource.get(sessionId);
+        return row?.fork_compact_source_id ?? null;
+    }
+    /**
+     * Clear the fork-compact flag after compaction completes (or fails).
+     * Idempotent-safe.
+     */
+    clearForkCompactSource(sessionId) {
+        this.stmtSetForkCompactSource.run(null, sessionId);
+    }
     close() {
         if (this.closed)
             return;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aexol/spectral",
-  "version": "0.3.5",
+  "version": "0.3.7",
   "description": "Always-on coding agent for Aexol — branded pi wrapper with relay-based browser access.",
   "type": "module",
   "private": false,