@aexol/spectral 0.7.0 → 0.7.3

package/dist/pi/coding-agent/core/extensions/types.js

@@ -0,0 +1,44 @@
+/**
+ * Extension system types.
+ *
+ * Extensions are TypeScript modules that can:
+ * - Subscribe to agent lifecycle events
+ * - Register LLM-callable tools
+ * - Register commands, keyboard shortcuts, and CLI flags
+ * - Interact with the user via UI primitives
+ */
+/**
+ * Preserve parameter inference for standalone tool definitions.
+ *
+ * Use this when assigning a tool to a variable or passing it through arrays such
+ * as `customTools`, where contextual typing would otherwise widen params to
+ * `unknown`.
+ */
+export function defineTool(tool) {
+    return tool;
+}
+// Type guards for ToolResultEvent
+export function isBashToolResult(e) {
+    return e.toolName === "bash";
+}
+export function isReadToolResult(e) {
+    return e.toolName === "read";
+}
+export function isEditToolResult(e) {
+    return e.toolName === "edit";
+}
+export function isWriteToolResult(e) {
+    return e.toolName === "write";
+}
+export function isGrepToolResult(e) {
+    return e.toolName === "grep";
+}
+export function isFindToolResult(e) {
+    return e.toolName === "find";
+}
+export function isLsToolResult(e) {
+    return e.toolName === "ls";
+}
+export function isToolCallEventType(toolName, event) {
+    return event.toolName === toolName;
+}

package/dist/pi/coding-agent/core/extensions/wrapper.js

@@ -0,0 +1,21 @@
+/**
+ * Tool wrappers for extension-registered tools.
+ *
+ * These wrappers only adapt tool execution so extension tools receive the runner context.
+ * Tool call and tool result interception is handled by AgentSession via agent hooks.
+ */
+import { wrapToolDefinition, wrapToolDefinitions } from "../tools/tool-definition-wrapper.js";
+/**
+ * Wrap a RegisteredTool into an AgentTool.
+ * Uses the runner's createContext() for consistent context across tools and event handlers.
+ */
+export function wrapRegisteredTool(registeredTool, runner) {
+    return wrapToolDefinition(registeredTool.definition, () => runner.createContext());
+}
+/**
+ * Wrap all registered tools into AgentTools.
+ * Uses the runner's createContext() for consistent context across tools and event handlers.
+ */
+export function wrapRegisteredTools(registeredTools, runner) {
+    return wrapToolDefinitions(registeredTools.map((registeredTool) => registeredTool.definition), () => runner.createContext());
+}

package/dist/pi/coding-agent/core/footer-data-provider.js

@@ -0,0 +1,309 @@
+import { execFile, spawnSync } from "child_process";
+import { existsSync, readFileSync, statSync, unwatchFile, watchFile } from "fs";
+import { dirname, join, resolve } from "path";
+import { closeWatcher, FS_WATCH_RETRY_DELAY_MS, watchWithErrorHandler } from "../utils/fs-watch.js";
+/**
+ * Find git metadata paths by walking up from cwd.
+ * Handles both regular git repos (.git is a directory) and worktrees (.git is a file).
+ */
+function findGitPaths(cwd) {
+    let dir = cwd;
+    while (true) {
+        const gitPath = join(dir, ".git");
+        if (existsSync(gitPath)) {
+            try {
+                const stat = statSync(gitPath);
+                if (stat.isFile()) {
+                    const content = readFileSync(gitPath, "utf8").trim();
+                    if (content.startsWith("gitdir: ")) {
+                        const gitDir = resolve(dir, content.slice(8).trim());
+                        const headPath = join(gitDir, "HEAD");
+                        if (!existsSync(headPath))
+                            return null;
+                        const commonDirPath = join(gitDir, "commondir");
+                        const commonGitDir = existsSync(commonDirPath)
+                            ? resolve(gitDir, readFileSync(commonDirPath, "utf8").trim())
+                            : gitDir;
+                        return { repoDir: dir, commonGitDir, headPath };
+                    }
+                }
+                else if (stat.isDirectory()) {
+                    const headPath = join(gitPath, "HEAD");
+                    if (!existsSync(headPath))
+                        return null;
+                    return { repoDir: dir, commonGitDir: gitPath, headPath };
+                }
+            }
+            catch {
+                return null;
+            }
+        }
+        const parent = dirname(dir);
+        if (parent === dir)
+            return null;
+        dir = parent;
+    }
+}
+/** Ask git for the current branch. Returns null on detached HEAD or if git is unavailable. */
+function resolveBranchWithGitSync(repoDir) {
+    const result = spawnSync("git", ["--no-optional-locks", "symbolic-ref", "--quiet", "--short", "HEAD"], {
+        cwd: repoDir,
+        encoding: "utf8",
+        stdio: ["ignore", "pipe", "ignore"],
+    });
+    const branch = result.status === 0 ? result.stdout.trim() : "";
+    return branch || null;
+}
+/** Ask git for the current branch asynchronously. Returns null on detached HEAD or if git is unavailable. */
+function resolveBranchWithGitAsync(repoDir) {
+    return new Promise((resolvePromise) => {
+        execFile("git", ["--no-optional-locks", "symbolic-ref", "--quiet", "--short", "HEAD"], {
+            cwd: repoDir,
+            encoding: "utf8",
+        }, (error, stdout) => {
+            if (error) {
+                resolvePromise(null);
+                return;
+            }
+            const branch = stdout.trim();
+            resolvePromise(branch || null);
+        });
+    });
+}
+/**
+ * Provides git branch and extension statuses - data not otherwise accessible to extensions.
+ * Token stats, model info available via ctx.sessionManager and ctx.model.
+ */
+export class FooterDataProvider {
+    cwd;
+    static WATCH_DEBOUNCE_MS = 500;
+    extensionStatuses = new Map();
+    cachedBranch = undefined;
+    gitPaths = undefined;
+    headWatcher = null;
+    reftableWatcher = null;
+    reftableTablesListWatcher = null;
+    reftableTablesListPath = null;
+    branchChangeCallbacks = new Set();
+    availableProviderCount = 0;
+    refreshTimer = null;
+    gitWatcherRetryTimer = null;
+    refreshInFlight = false;
+    refreshPending = false;
+    disposed = false;
+    constructor(cwd) {
+        this.cwd = cwd;
+        this.gitPaths = findGitPaths(cwd);
+        this.setupGitWatcher();
+    }
+    /** Current git branch, null if not in repo, "detached" if detached HEAD */
+    getGitBranch() {
+        if (this.cachedBranch === undefined) {
+            this.cachedBranch = this.resolveGitBranchSync();
+        }
+        return this.cachedBranch;
+    }
+    /** Extension status texts set via ctx.ui.setStatus() */
+    getExtensionStatuses() {
+        return this.extensionStatuses;
+    }
+    /** Subscribe to git branch changes. Returns unsubscribe function. */
+    onBranchChange(callback) {
+        this.branchChangeCallbacks.add(callback);
+        return () => this.branchChangeCallbacks.delete(callback);
+    }
+    /** Internal: set extension status */
+    setExtensionStatus(key, text) {
+        if (text === undefined) {
+            this.extensionStatuses.delete(key);
+        }
+        else {
+            this.extensionStatuses.set(key, text);
+        }
+    }
+    /** Internal: clear extension statuses */
+    clearExtensionStatuses() {
+        this.extensionStatuses.clear();
+    }
+    /** Number of unique providers with available models (for footer display) */
+    getAvailableProviderCount() {
+        return this.availableProviderCount;
+    }
+    /** Internal: update available provider count */
+    setAvailableProviderCount(count) {
+        this.availableProviderCount = count;
+    }
+    setCwd(cwd) {
+        if (this.cwd === cwd) {
+            return;
+        }
+        this.cwd = cwd;
+        if (this.refreshTimer) {
+            clearTimeout(this.refreshTimer);
+            this.refreshTimer = null;
+        }
+        this.clearGitWatchers();
+        this.cachedBranch = undefined;
+        this.gitPaths = findGitPaths(cwd);
+        this.setupGitWatcher();
+        this.notifyBranchChange();
+    }
+    /** Internal: cleanup */
+    dispose() {
+        this.disposed = true;
+        if (this.refreshTimer) {
+            clearTimeout(this.refreshTimer);
+            this.refreshTimer = null;
+        }
+        this.clearGitWatchers();
+        this.branchChangeCallbacks.clear();
+    }
+    notifyBranchChange() {
+        for (const cb of this.branchChangeCallbacks)
+            cb();
+    }
+    scheduleRefresh() {
+        if (this.disposed || this.refreshTimer)
+            return;
+        if (this.refreshInFlight) {
+            this.refreshPending = true;
+            return;
+        }
+        this.refreshTimer = setTimeout(() => {
+            this.refreshTimer = null;
+            void this.refreshGitBranchAsync();
+        }, FooterDataProvider.WATCH_DEBOUNCE_MS);
+    }
+    async refreshGitBranchAsync() {
+        if (this.disposed)
+            return;
+        if (this.refreshInFlight) {
+            this.refreshPending = true;
+            return;
+        }
+        this.refreshInFlight = true;
+        try {
+            const nextBranch = await this.resolveGitBranchAsync();
+            if (this.disposed)
+                return;
+            if (this.cachedBranch !== undefined && this.cachedBranch !== nextBranch) {
+                this.cachedBranch = nextBranch;
+                this.notifyBranchChange();
+                return;
+            }
+            this.cachedBranch = nextBranch;
+        }
+        finally {
+            this.refreshInFlight = false;
+            if (this.refreshPending && !this.disposed) {
+                this.refreshPending = false;
+                this.scheduleRefresh();
+            }
+        }
+    }
+    resolveGitBranchSync() {
+        try {
+            if (!this.gitPaths)
+                return null;
+            const content = readFileSync(this.gitPaths.headPath, "utf8").trim();
+            if (content.startsWith("ref: refs/heads/")) {
+                const branch = content.slice(16);
+                return branch === ".invalid" ? (resolveBranchWithGitSync(this.gitPaths.repoDir) ?? "detached") : branch;
+            }
+            return "detached";
+        }
+        catch {
+            return null;
+        }
+    }
+    async resolveGitBranchAsync() {
+        try {
+            if (!this.gitPaths)
+                return null;
+            const content = readFileSync(this.gitPaths.headPath, "utf8").trim();
+            if (content.startsWith("ref: refs/heads/")) {
+                const branch = content.slice(16);
+                return branch === ".invalid"
+                    ? ((await resolveBranchWithGitAsync(this.gitPaths.repoDir)) ?? "detached")
+                    : branch;
+            }
+            return "detached";
+        }
+        catch {
+            return null;
+        }
+    }
+    clearGitWatchers() {
+        closeWatcher(this.headWatcher);
+        this.headWatcher = null;
+        closeWatcher(this.reftableWatcher);
+        this.reftableWatcher = null;
+        closeWatcher(this.reftableTablesListWatcher);
+        this.reftableTablesListWatcher = null;
+        if (this.reftableTablesListPath) {
+            unwatchFile(this.reftableTablesListPath);
+            this.reftableTablesListPath = null;
+        }
+        if (this.gitWatcherRetryTimer) {
+            clearTimeout(this.gitWatcherRetryTimer);
+            this.gitWatcherRetryTimer = null;
+        }
+    }
+    scheduleGitWatcherRetry() {
+        if (this.disposed || this.gitWatcherRetryTimer) {
+            return;
+        }
+        this.gitWatcherRetryTimer = setTimeout(() => {
+            this.gitWatcherRetryTimer = null;
+            this.setupGitWatcher();
+        }, FS_WATCH_RETRY_DELAY_MS);
+    }
+    handleGitWatcherError() {
+        this.clearGitWatchers();
+        this.scheduleGitWatcherRetry();
+    }
+    setupGitWatcher() {
+        this.clearGitWatchers();
+        if (!this.gitPaths)
+            return;
+        // Watch the directory containing HEAD, not HEAD itself.
+        // Git uses atomic writes (write temp, rename over HEAD), which changes the inode.
+        // fs.watch on a file stops working after the inode changes.
+        this.headWatcher = watchWithErrorHandler(dirname(this.gitPaths.headPath), (_eventType, filename) => {
+            if (!filename || filename === "HEAD") {
+                this.scheduleRefresh();
+            }
+        }, () => this.handleGitWatcherError());
+        if (!this.headWatcher) {
+            return;
+        }
+        // In reftable repos, branch switches update files in the reftable directory
+        // instead of HEAD. Watch it separately so the footer picks up those changes.
+        const reftableDir = join(this.gitPaths.commonGitDir, "reftable");
+        if (existsSync(reftableDir)) {
+            this.reftableWatcher = watchWithErrorHandler(reftableDir, () => {
+                this.scheduleRefresh();
+            }, () => this.handleGitWatcherError());
+            if (!this.reftableWatcher) {
+                return;
+            }
+            const tablesListPath = join(reftableDir, "tables.list");
+            if (existsSync(tablesListPath)) {
+                this.reftableTablesListPath = tablesListPath;
+                this.reftableTablesListWatcher = watchWithErrorHandler(tablesListPath, () => {
+                    this.scheduleRefresh();
+                }, () => this.handleGitWatcherError());
+                if (!this.reftableTablesListWatcher) {
+                    return;
+                }
+                watchFile(tablesListPath, { interval: 250 }, (current, previous) => {
+                    if (current.mtimeMs !== previous.mtimeMs ||
+                        current.ctimeMs !== previous.ctimeMs ||
+                        current.size !== previous.size) {
+                        this.scheduleRefresh();
+                    }
+                });
+            }
+        }
+    }
+}

package/dist/pi/coding-agent/core/http-dispatcher.js

@@ -0,0 +1,47 @@
+import * as undici from "undici";
+export const DEFAULT_HTTP_IDLE_TIMEOUT_MS = 300_000;
+export const HTTP_IDLE_TIMEOUT_CHOICES = [
+    { label: "30 sec", timeoutMs: 30_000 },
+    { label: "1 min", timeoutMs: 60_000 },
+    { label: "2 min", timeoutMs: 120_000 },
+    { label: "5 min", timeoutMs: 300_000 },
+    { label: "disabled", timeoutMs: 0 },
+];
+export function parseHttpIdleTimeoutMs(value) {
+    if (typeof value === "string") {
+        const trimmed = value.trim();
+        if (trimmed.toLowerCase() === "disabled") {
+            return 0;
+        }
+        if (trimmed.length === 0) {
+            return undefined;
+        }
+        return parseHttpIdleTimeoutMs(Number(trimmed));
+    }
+    if (typeof value !== "number" || !Number.isFinite(value) || value < 0) {
+        return undefined;
+    }
+    return Math.floor(value);
+}
+export function formatHttpIdleTimeoutMs(timeoutMs) {
+    const choice = HTTP_IDLE_TIMEOUT_CHOICES.find((item) => item.timeoutMs === timeoutMs);
+    if (choice) {
+        return choice.label;
+    }
+    return `${timeoutMs / 1000} sec`;
+}
+export function configureHttpDispatcher(timeoutMs = DEFAULT_HTTP_IDLE_TIMEOUT_MS) {
+    const normalizedTimeoutMs = parseHttpIdleTimeoutMs(timeoutMs);
+    if (normalizedTimeoutMs === undefined) {
+        throw new Error(`Invalid HTTP idle timeout: ${String(timeoutMs)}`);
+    }
+    undici.setGlobalDispatcher(new undici.EnvHttpProxyAgent({
+        allowH2: false,
+        bodyTimeout: normalizedTimeoutMs,
+        headersTimeout: normalizedTimeoutMs,
+    }));
+    // Keep fetch and the dispatcher on the same undici implementation. Node 26.0's
+    // bundled fetch can otherwise consume compressed responses through npm undici's
+    // dispatcher without decompressing them, causing response.json() failures.
+    undici.install?.();
+}

package/dist/pi/coding-agent/core/index.js

@@ -0,0 +1,11 @@
+/**
+ * Core modules shared between all run modes.
+ */
+export { AgentSession, } from "./agent-session.js";
+export { AgentSessionRuntime, createAgentSessionRuntime, } from "./agent-session-runtime.js";
+export { createAgentSessionFromServices, createAgentSessionServices, } from "./agent-session-services.js";
+export { executeBashWithOperations } from "./bash-executor.js";
+export { createEventBus } from "./event-bus.js";
+// Extensions system
+export { defineTool, discoverAndLoadExtensions, ExtensionRunner, } from "./extensions/index.js";
+export { createSyntheticSourceInfo } from "./source-info.js";