@aexol/spectral 0.9.220 → 0.9.222

package/dist/agent/index.d.ts

@@ -22,13 +22,17 @@
  *   - Tool filtering (only the tools specified in agent config)
  *   - Model selection (session model preferred, agent-configured as fallback)
  *   - Signal propagation (abort passthrough)
- *   - Access to observational memory via the recall tool
+ *   - Access to observational memory via the `recall` and
+ *     `write_project_observation` tools, which run against a parent-session
+ *     point-in-time snapshot (branch + session id); other observation tools
+ *     (`share_project_observation`, `receive_agent_observations`,
+ *     `compact_context`, `subagent`) remain excluded
  */
 import type { AgentTool } from "../sdk/agent-core/index.js";
 import { type ExtensionAPI, type ExtensionContext } from "../sdk/coding-agent/index.js";
 import { type AgentConfig } from "./agents.js";
 import type { ServerEvent } from "../server/wire.ts";
-import type { ExtensionContext as RichExtensionContext } from "../sdk/coding-agent/core/extensions/types.js";
+import type { ReadonlySessionManager } from "../sdk/coding-agent/core/session-manager.js";
 /**
  * Build the system prompt for a subagent session.
  *
@@ -44,7 +48,7 @@ export declare function buildSubagentSystemPrompt(baseSystemPrompt: string | und
  * Give subagents a point-in-time branch view without exposing the live parent
  * SessionManager. Each getBranch call returns fresh clones of the snapshot.
  */
-export declare function createSubagentSessionManagerSnapshot(sessionManager: ExtensionContext["sessionManager"]): Pick<RichExtensionContext["sessionManager"], "getBranch">;
+export declare function createSubagentSessionManagerSnapshot(sessionManager: ExtensionContext["sessionManager"]): Pick<ReadonlySessionManager, "getBranch" | "getSessionId">;
 export declare function resolveSubagentTools(cwd: string, ext: ExtensionAPI, ctx: ExtensionContext): AgentTool[];
 export default function subagentExtension(ext: ExtensionAPI, opts?: {
     disabledAgents?: string[];

package/dist/agent/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/agent/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,OAAO,KAAK,EAIX,SAAS,EAET,MAAM,4BAA4B,CAAC;AAUpC,OAAO,EACN,KAAK,YAAY,EACjB,KAAK,gBAAgB,EACrB,MAAM,8BAA8B,CAAC;AAGtC,OAAO,EACN,KAAK,WAAW,EAKhB,MAAM,aAAa,CAAC;AAErB,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAQrD,OAAO,KAAK,EAAE,gBAAgB,IAAI,oBAAoB,EAAE,MAAM,8CAA8C,CAAC;AAuG7G;;;;;;;;;GASG;AACH,wBAAgB,yBAAyB,CACxC,gBAAgB,EAAE,MAAM,GAAG,SAAS,EACpC,KAAK,EAAE,IAAI,CAAC,WAAW,EAAE,MAAM,GAAG,aAAa,GAAG,cAAc,GAAG,OAAO,GAAG,QAAQ,CAAC,GACpF,MAAM,CAYR;AA0JD;;;GAGG;AACH,wBAAgB,oCAAoC,CACnD,cAAc,EAAE,gBAAgB,CAAC,gBAAgB,CAAC,GAChD,IAAI,CAAC,oBAAoB,CAAC,gBAAgB,CAAC,EAAE,WAAW,CAAC,CAK3D;AAoBD,wBAAgB,oBAAoB,CACnC,GAAG,EAAE,MAAM,EACX,GAAG,EAAE,YAAY,EACjB,GAAG,EAAE,gBAAgB,GACnB,SAAS,EAAE,CAoCb;AAycD,MAAM,CAAC,OAAO,UAAU,iBAAiB,CACxC,GAAG,EAAE,YAAY,EACjB,IAAI,CAAC,EAAE;IACN,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;IAC1B,iBAAiB,CAAC,EAAE,CAAC,KAAK,EAAE,WAAW,KAAK,IAAI,CAAC;IACjD,MAAM,CAAC,EAAE,MAAM,CAAC;CAChB,GACC,IAAI,CAgaN"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/agent/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAEH,OAAO,KAAK,EAIX,SAAS,EAET,MAAM,4BAA4B,CAAC;AAUpC,OAAO,EACN,KAAK,YAAY,EACjB,KAAK,gBAAgB,EAErB,MAAM,8BAA8B,CAAC;AAGtC,OAAO,EACN,KAAK,WAAW,EAKhB,MAAM,aAAa,CAAC;AAErB,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAQrD,OAAO,KAAK,EAAE,sBAAsB,EAAgB,MAAM,6CAA6C,CAAC;AAuGxG;;;;;;;;;GASG;AACH,wBAAgB,yBAAyB,CACxC,gBAAgB,EAAE,MAAM,GAAG,SAAS,EACpC,KAAK,EAAE,IAAI,CAAC,WAAW,EAAE,MAAM,GAAG,aAAa,GAAG,cAAc,GAAG,OAAO,GAAG,QAAQ,CAAC,GACpF,MAAM,CAYR;AA0JD;;;GAGG;AACH,wBAAgB,oCAAoC,CACnD,cAAc,EAAE,gBAAgB,CAAC,gBAAgB,CAAC,GAChD,IAAI,CAAC,sBAAsB,EAAE,WAAW,GAAG,cAAc,CAAC,CAe5D;AA6BD,wBAAgB,oBAAoB,CACnC,GAAG,EAAE,MAAM,EACX,GAAG,EAAE,YAAY,EACjB,GAAG,EAAE,gBAAgB,GACnB,SAAS,EAAE,CAwCb;AAycD,MAAM,CAAC,OAAO,UAAU,iBAAiB,CACxC,GAAG,EAAE,YAAY,EACjB,IAAI,CAAC,EAAE;IACN,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;IAC1B,iBAAiB,CAAC,EAAE,CAAC,KAAK,EAAE,WAAW,KAAK,IAAI,CAAC;IACjD,MAAM,CAAC,EAAE,MAAM,CAAC;CAChB,GACC,IAAI,CAgaN"}

package/dist/agent/index.js

@@ -22,7 +22,11 @@
  *   - Tool filtering (only the tools specified in agent config)
  *   - Model selection (session model preferred, agent-configured as fallback)
  *   - Signal propagation (abort passthrough)
- *   - Access to observational memory via the recall tool
+ *   - Access to observational memory via the `recall` and
+ *     `write_project_observation` tools, which run against a parent-session
+ *     point-in-time snapshot (branch + session id); other observation tools
+ *     (`share_project_observation`, `receive_agent_observations`,
+ *     `compact_context`, `subagent`) remain excluded
  */
 import { agentLoop } from "../sdk/agent-core/index.js";
 import { buildIsolatedRequestTimePrunedMessagesResult, COMPACT_CONTEXT_TOOL_NAME, } from "../memory/tools/compact-context.js";
@@ -40,6 +44,7 @@ import { wrapToolDefinition } from "../sdk/coding-agent/core/tools/tool-definiti
 import { RECALL_OBSERVATION_TOOL_NAME } from "../memory/tools/recall-observation.js";
 import { RECEIVE_AGENT_OBSERVATIONS_TOOL_NAME } from "../memory/tools/receive-agent-observations.js";
 import { SHARE_PROJECT_OBSERVATION_TOOL_NAME } from "../memory/tools/share-project-observation.js";
+import { WRITE_PROJECT_OBSERVATION_TOOL_NAME } from "../memory/tools/write-project-observation.js";
 import { compressSubagentToolResult } from "../memory/tool-output-compressor.js";
 // ---------------------------------------------------------------------------
 // Constants
@@ -230,8 +235,18 @@ function cloneSessionEntry(entry) {
  */
 export function createSubagentSessionManagerSnapshot(sessionManager) {
     const snapshot = sessionManager.getBranch().map(cloneSessionEntry);
+    // Optional call tolerates minimal branch-only snapshots in tests; a
+    // missing id falls through to the tools' `no_session` handling.
+    const sessionId = sessionManager.getSessionId?.();
     return {
         getBranch: () => snapshot.map(cloneSessionEntry),
+        // Captured eagerly so the session id and the branch snapshot come
+        // from the same point in time. fork/newSession mutate the live
+        // SessionManager's sessionId in place, so a lazy read could diverge
+        // from the point-in-time branch on a mid-run fork. Subagent
+        // observations must be attributed to the parent session id at
+        // snapshot creation, same branch semantics as `recall`.
+        getSessionId: () => sessionId,
     };
 }
 /**
@@ -251,14 +266,27 @@ const SUBAGENT_EXCLUDED_TOOL_NAMES = new Set([
     RECEIVE_AGENT_OBSERVATIONS_TOOL_NAME,
     SHARE_PROJECT_OBSERVATION_TOOL_NAME,
 ]);
+/**
+ * Extension tools that run with the parent session's point-in-time branch
+ * snapshot instead of the bare `{ cwd, getSystemPrompt }` isolated context.
+ */
+const SUBAGENT_SESSION_SNAPSHOT_TOOL_NAMES = new Set([
+    RECALL_OBSERVATION_TOOL_NAME,
+    WRITE_PROJECT_OBSERVATION_TOOL_NAME,
+]);
 export function resolveSubagentTools(cwd, ext, ctx) {
     // Subagents receive every tool registered on the primary agent. Built-in
     // tools are created fresh with the subagent's isolated cwd/jobs, and
-    // extension-registered tools are wrapped with an isolated context exposing
-    // only `cwd` and `getSystemPrompt` (plus a read-only branch snapshot for
-    // `recall`).
+    // extension-registered tools are wrapped with a `SubagentToolContext`:
+    // always `cwd` + `getSystemPrompt`, plus a point-in-time parent-session
+    // branch snapshot for the observation tools that need branch/session
+    // semantics. Everything else (ui, modelRegistry, live sessionManager) is
+    // absent at runtime, so handlers must guard those members.
     const tools = [];
     const jobs = new BashJobRegistry();
+    // One shared snapshot per invocation so all snapshot-routed tools observe
+    // the same parent-session epoch (branch + session id).
+    const sharedSnapshot = createSubagentSessionManagerSnapshot(ctx.sessionManager);
     for (const toolInfo of ext.getAllTools()) {
         const name = toolInfo.name;
         if (SUBAGENT_EXCLUDED_TOOL_NAMES.has(name))
@@ -278,11 +306,10 @@ export function resolveSubagentTools(cwd, ext, ctx) {
         const toolDef = ext.getToolDefinition(name);
         if (!toolDef)
             continue;
-        const isolatedContext = name === RECALL_OBSERVATION_TOOL_NAME
-            ? { cwd, sessionManager: createSubagentSessionManagerSnapshot(ctx.sessionManager), getSystemPrompt: ctx.getSystemPrompt }
+        const isolatedContext = SUBAGENT_SESSION_SNAPSHOT_TOOL_NAMES.has(name)
+            ? { cwd, sessionManager: sharedSnapshot, getSystemPrompt: ctx.getSystemPrompt }
             : { cwd, getSystemPrompt: ctx.getSystemPrompt };
-        const isolatedContextWithNoParent = isolatedContext;
-        tools.push(wrapToolDefinition(toolDef, () => isolatedContextWithNoParent));
+        tools.push(wrapToolDefinition(toolDef, () => isolatedContext));
     }
     return tools;
 }

package/dist/extensions/aexol-backend-client.d.ts

@@ -0,0 +1,85 @@
+/**
+ * Shared Aexol-backend MCP client bootstrap for native extensions.
+ *
+ * Extracted from `aexol-mcp.ts` (behavior-preserving: identical config/
+ * token resolution, identical tools/list bootstrap and OAuth re-auth flow,
+ * identical diagnostic strings) so other extensions that talk to the same
+ * JSON-RPC MCP backend can reuse one chunk of logic.
+ *
+ * Responsibilities:
+ *   1. Reads ~/.spectral/config.json (written by `spectral login`).
+ *   2. Resolves the effective API URL: SPECTRAL_MCP_URL > stored > default.
+ *   3. Resolves the auth token: teamApiKey > userJwt.
+ *   4. Instantiates AexolMcpClient and performs the initial tools/list call.
+ *   5. On 401/403 from tools/list, runs the OAuth re-auth flow once and
+ *      retries the catalog fetch with a fresh token.
+ *
+ * Failure modes are non-fatal: instead of throwing, the factory returns a
+ * discriminated outcome. Transient diagnostics are streamed through an
+ * optional `warn` sink so each caller can render them with its own log
+ * prefix; the terminal failure reason travels in the returned outcome.
+ */
+import { AexolMcpClient, type McpContentItem, type McpTool } from "../mcp-client.js";
+import { ensureAuthenticated } from "../auth-helper.js";
+/** Sink for transient bootstrap diagnostics (line without prefix/newline). */
+export type BootstrapWarn = (line: string) => void;
+export interface CreateAexolBackendClientOptions {
+    /**
+     * Receives transient diagnostics (tools/list failure, re-auth progress).
+     * Defaults to writing `[aexol-backend-client] <line>` to stderr — extension
+     * callers should pass a sink with their own prefix.
+     */
+    warn?: BootstrapWarn;
+}
+/**
+ * Successfully-bootstrapped client handle.
+ *
+ * NOTE: if the initial tools/list hit a 401/403 and re-auth succeeded, `tools`
+ * comes from a retry client while `client` is still the initially-created one.
+ * This intentionally mirrors the original aexol-mcp.ts behavior (call-time
+ * tools/call kept using the boot-time client).
+ */
+export interface AexolBackendClient {
+    /** Ready-to-use JSON-RPC MCP client for tools/call (and tools/list). */
+    client: AexolMcpClient;
+    /** Effective backend URL (SPECTRAL_MCP_URL > stored config > default). */
+    apiUrl: string;
+    /** Tool catalog returned by the initial tools/list call. */
+    tools: McpTool[];
+    /**
+     * Re-auth helper (OAuth browser flow) for later 401/403 recovery; see
+     * `../auth-helper.js` for semantics (no-op failure in non-UI sessions).
+     * The caller owns rebuilding the client from the returned fresh config.
+     */
+    ensureAuthenticated: typeof ensureAuthenticated;
+    /** Render backend tool result content into one model-readable string. */
+    renderContentToString: typeof renderContentToString;
+}
+export type AexolBackendBootstrapFailureReason = "no-config" | "no-token" | "catalog-failed";
+export interface AexolBackendBootstrapFailure {
+    ok: false;
+    reason: AexolBackendBootstrapFailureReason;
+    /** Fully-formed diagnostic, ready to be prefixed and written by the caller. */
+    message: string;
+}
+export type AexolBackendBootstrap = ({
+    ok: true;
+} & AexolBackendClient) | AexolBackendBootstrapFailure;
+/**
+ * Render a backend tool result into a single string for ext.
+ *
+ * The Aexol backend wraps results as `{ content: [{ type: "json", json: ... }] }`
+ * but may also send `{ type: "text", text: ... }`. We pick the first content
+ * item, prefer JSON when present (pretty-print so the model can read it),
+ * fall back to text, and last-resort stringify the whole content array.
+ */
+export declare function renderContentToString(content: McpContentItem[]): string;
+/**
+ * Bootstrap a connection to the Aexol backend MCP endpoint.
+ *
+ * Non-fatal by design: returns a failure outcome (never throws) when the
+ * config or token is missing, or when the initial tools/list call cannot be
+ * completed even after the OAuth re-auth attempt.
+ */
+export declare function createAexolBackendClient(options?: CreateAexolBackendClientOptions): Promise<AexolBackendBootstrap>;
+//# sourceMappingURL=aexol-backend-client.d.ts.map

package/dist/extensions/aexol-backend-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"aexol-backend-client.d.ts","sourceRoot":"","sources":["../../src/extensions/aexol-backend-client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,EACL,cAAc,EAEd,KAAK,cAAc,EACnB,KAAK,OAAO,EACb,MAAM,kBAAkB,CAAC;AAE1B,OAAO,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AAExD,8EAA8E;AAC9E,MAAM,MAAM,aAAa,GAAG,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;AAEnD,MAAM,WAAW,+BAA+B;IAC9C;;;;OAIG;IACH,IAAI,CAAC,EAAE,aAAa,CAAC;CACtB;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,kBAAkB;IACjC,wEAAwE;IACxE,MAAM,EAAE,cAAc,CAAC;IACvB,0EAA0E;IAC1E,MAAM,EAAE,MAAM,CAAC;IACf,4DAA4D;IAC5D,KAAK,EAAE,OAAO,EAAE,CAAC;IACjB;;;;OAIG;IACH,mBAAmB,EAAE,OAAO,mBAAmB,CAAC;IAChD,yEAAyE;IACzE,qBAAqB,EAAE,OAAO,qBAAqB,CAAC;CACrD;AAED,MAAM,MAAM,kCAAkC,GAC1C,WAAW,GACX,UAAU,GACV,gBAAgB,CAAC;AAErB,MAAM,WAAW,4BAA4B;IAC3C,EAAE,EAAE,KAAK,CAAC;IACV,MAAM,EAAE,kCAAkC,CAAC;IAC3C,+EAA+E;IAC/E,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,MAAM,qBAAqB,GAC7B,CAAC;IAAE,EAAE,EAAE,IAAI,CAAA;CAAE,GAAG,kBAAkB,CAAC,GACnC,4BAA4B,CAAC;AAEjC;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,cAAc,EAAE,GAAG,MAAM,CA+BvE;AAED;;;;;;GAMG;AACH,wBAAsB,wBAAwB,CAC5C,OAAO,GAAE,+BAAoC,GAC5C,OAAO,CAAC,qBAAqB,CAAC,CAmFhC"}

package/dist/extensions/aexol-backend-client.js

@@ -0,0 +1,159 @@
+/**
+ * Shared Aexol-backend MCP client bootstrap for native extensions.
+ *
+ * Extracted from `aexol-mcp.ts` (behavior-preserving: identical config/
+ * token resolution, identical tools/list bootstrap and OAuth re-auth flow,
+ * identical diagnostic strings) so other extensions that talk to the same
+ * JSON-RPC MCP backend can reuse one chunk of logic.
+ *
+ * Responsibilities:
+ *   1. Reads ~/.spectral/config.json (written by `spectral login`).
+ *   2. Resolves the effective API URL: SPECTRAL_MCP_URL > stored > default.
+ *   3. Resolves the auth token: teamApiKey > userJwt.
+ *   4. Instantiates AexolMcpClient and performs the initial tools/list call.
+ *   5. On 401/403 from tools/list, runs the OAuth re-auth flow once and
+ *      retries the catalog fetch with a fresh token.
+ *
+ * Failure modes are non-fatal: instead of throwing, the factory returns a
+ * discriminated outcome. Transient diagnostics are streamed through an
+ * optional `warn` sink so each caller can render them with its own log
+ * prefix; the terminal failure reason travels in the returned outcome.
+ */
+import { AexolMcpClient, AexolMcpError, } from "../mcp-client.js";
+import { getApiUrl, getConfigFile, readConfig } from "../config.js";
+import { ensureAuthenticated } from "../auth-helper.js";
+/**
+ * Render a backend tool result into a single string for ext.
+ *
+ * The Aexol backend wraps results as `{ content: [{ type: "json", json: ... }] }`
+ * but may also send `{ type: "text", text: ... }`. We pick the first content
+ * item, prefer JSON when present (pretty-print so the model can read it),
+ * fall back to text, and last-resort stringify the whole content array.
+ */
+export function renderContentToString(content) {
+    if (content.length === 0)
+        return "";
+    const first = content[0];
+    if (first.json !== undefined) {
+        try {
+            return JSON.stringify(first.json, null, 2);
+        }
+        catch {
+            return String(first.json);
+        }
+    }
+    if (typeof first.text === "string")
+        return first.text;
+    // For image/audio/binary content types, return a metadata placeholder
+    // instead of serializing the raw base64 data into the model context.
+    if (first.type === "image" || first.type === "audio") {
+        const mimeType = typeof first.mimeType === "string" ? first.mimeType : first.type;
+        const dataLen = typeof first.data === "string" ? first.data.length : 0;
+        return `[${first.type}: ${mimeType}${dataLen ? `, ${dataLen.toLocaleString()} bytes base64` : ""}]`;
+    }
+    try {
+        // Strip large binary fields from serialization to prevent context overflow.
+        const safe = content.map((c) => {
+            const copy = { ...c };
+            if ("data" in copy && typeof copy.data === "string" && copy.data.length > 200) {
+                copy.data = `[${copy.data.length.toLocaleString()} bytes base64 omitted]`;
+            }
+            return copy;
+        });
+        return JSON.stringify(safe, null, 2);
+    }
+    catch {
+        return String(content);
+    }
+}
+/**
+ * Bootstrap a connection to the Aexol backend MCP endpoint.
+ *
+ * Non-fatal by design: returns a failure outcome (never throws) when the
+ * config or token is missing, or when the initial tools/list call cannot be
+ * completed even after the OAuth re-auth attempt.
+ */
+export async function createAexolBackendClient(options = {}) {
+    const warn = options.warn ??
+        ((line) => process.stderr.write(`[aexol-backend-client] ${line}\n`));
+    const cfg = await readConfig();
+    if (!cfg) {
+        // Pre-flight in cli.ts should have caught this. Returning a diagnostic is
+        // enough; the caller decides how (or whether) to surface it.
+        return {
+            ok: false,
+            reason: "no-config",
+            message: `No config found at ${getConfigFile()}; Aexol tools disabled. Run \`spectral login\`.`,
+        };
+    }
+    const apiUrl = getApiUrl(cfg.apiUrl);
+    const token = cfg.teamApiKey || cfg.userJwt || "";
+    if (!token) {
+        return {
+            ok: false,
+            reason: "no-token",
+            message: `No auth token in ${getConfigFile()}; Aexol tools disabled. Run \`spectral login\`.`,
+        };
+    }
+    const client = new AexolMcpClient(apiUrl, token);
+    let tools;
+    try {
+        tools = await client.listTools();
+    }
+    catch (err) {
+        const msg = err instanceof AexolMcpError || err instanceof Error ? err.message : String(err);
+        warn(`Failed to fetch tool catalog from ${apiUrl}: ${msg}`);
+        // Attempt auto-reauth via OAuth browser flow on auth errors
+        if (err instanceof AexolMcpError && (err.status === 401 || err.status === 403)) {
+            const authResult = await ensureAuthenticated();
+            if (authResult.ok && authResult.config) {
+                const newToken = authResult.config.teamApiKey || authResult.config.userJwt || "";
+                if (newToken && newToken !== token) {
+                    warn("Re-authenticated — retrying tool catalog fetch...");
+                    const newClient = new AexolMcpClient(apiUrl, newToken);
+                    try {
+                        tools = await newClient.listTools();
+                    }
+                    catch (retryErr) {
+                        const retryMsg = retryErr instanceof Error ? retryErr.message : String(retryErr);
+                        warn(`Retry also failed: ${retryMsg}`);
+                        return {
+                            ok: false,
+                            reason: "catalog-failed",
+                            message: "Continuing without Aexol tools.",
+                        };
+                    }
+                }
+                else {
+                    return {
+                        ok: false,
+                        reason: "catalog-failed",
+                        message: "Re-authentication did not produce a new token. Continuing without Aexol tools.",
+                    };
+                }
+            }
+            else {
+                return {
+                    ok: false,
+                    reason: "catalog-failed",
+                    message: `Re-authentication failed: ${authResult.reason ?? "unknown"}. Continuing without Aexol tools.`,
+                };
+            }
+        }
+        else {
+            return {
+                ok: false,
+                reason: "catalog-failed",
+                message: "Continuing without Aexol tools.",
+            };
+        }
+    }
+    return {
+        ok: true,
+        client,
+        apiUrl,
+        tools,
+        ensureAuthenticated,
+        renderContentToString,
+    };
+}

package/dist/extensions/aexol-mcp.d.ts

@@ -2,13 +2,17 @@
  * Aexol MCP spectral extension.
  *
  * Loaded by the spectral wrapper via `--extension <abs-path>`. On startup it:
- *   1. Reads ~/.spectral/config.json (writen by `spectral login`).
- *   2. Calls tools/list against the MCP backend once.
- *   3. Reads the local Studio binding (`.aexol/aexol.jsonc`) so remote tools
- *      auto-inherit `teamId` / `projectId` without needing `remote_set_context`.
- *   4. Registers every returned remote tool through ext.registerTool() so the
+ *   1. Boots the Aexol backend MCP client via the shared
+ *      `createAexolBackendClient()` factory in ./aexol-backend-client.ts
+ *      (config load, token resolution, initial tools/list call, OAuth
+ *      re-auth on 401/403).
+ *   2. Reads the local Studio binding (`.aexol/aexol.jsonc`) so remote tools
+ *      auto-inherit `teamId` / `projectId`; the binding itself is managed from
+ *      agent via the `local_bind_project` / `local_unbind_project` tools
+ *      registered at startup (see step 4).
+ *   3. Registers every returned remote tool through ext.registerTool() so the
  *      model can call them like built-in tools.
- *   5. Registers local binding-management tools (`local_bind_project`,
+ *   4. Registers local binding-management tools (`local_bind_project`,
  *      `local_unbind_project`, `local_get_binding`) so users can bind a
  *      directory to an Aexol Studio project from within the agent.
  *

package/dist/extensions/aexol-mcp.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"aexol-mcp.d.ts","sourceRoot":"","sources":["../../src/extensions/aexol-mcp.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAoC,MAAM,8BAA8B,CAAC;AAiKnG,wBAA8B,iBAAiB,CAAC,GAAG,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC,CAsShF"}
+{"version":3,"file":"aexol-mcp.d.ts","sourceRoot":"","sources":["../../src/extensions/aexol-mcp.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAoC,MAAM,8BAA8B,CAAC;AAqHnG,wBAA8B,iBAAiB,CAAC,GAAG,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC,CA0PhF"}

package/dist/extensions/aexol-mcp.js

@@ -2,13 +2,17 @@
  * Aexol MCP spectral extension.
  *
  * Loaded by the spectral wrapper via `--extension <abs-path>`. On startup it:
- *   1. Reads ~/.spectral/config.json (writen by `spectral login`).
- *   2. Calls tools/list against the MCP backend once.
- *   3. Reads the local Studio binding (`.aexol/aexol.jsonc`) so remote tools
- *      auto-inherit `teamId` / `projectId` without needing `remote_set_context`.
- *   4. Registers every returned remote tool through ext.registerTool() so the
+ *   1. Boots the Aexol backend MCP client via the shared
+ *      `createAexolBackendClient()` factory in ./aexol-backend-client.ts
+ *      (config load, token resolution, initial tools/list call, OAuth
+ *      re-auth on 401/403).
+ *   2. Reads the local Studio binding (`.aexol/aexol.jsonc`) so remote tools
+ *      auto-inherit `teamId` / `projectId`; the binding itself is managed from
+ *      agent via the `local_bind_project` / `local_unbind_project` tools
+ *      registered at startup (see step 4).
+ *   3. Registers every returned remote tool through ext.registerTool() so the
  *      model can call them like built-in tools.
- *   5. Registers local binding-management tools (`local_bind_project`,
+ *   4. Registers local binding-management tools (`local_bind_project`,
  *      `local_unbind_project`, `local_get_binding`) so users can bind a
  *      directory to an Aexol Studio project from within the agent.
  *
@@ -20,55 +24,10 @@
  * backend is unreachable we log a warning and return, leaving spectral to start
  * without Aexol tools rather than crashing the whole agent.
  */
-import { getApiUrl, getConfigFile, readConfig } from "../config.js";
-import { AexolMcpClient, AexolMcpError } from "../mcp-client.js";
+import { createAexolBackendClient, renderContentToString } from "./aexol-backend-client.js";
 import { stat } from "node:fs/promises";
 import { join } from "node:path";
 import { readStudioBinding, writeStudioBinding, deleteStudioBinding, } from "../studio-binding.js";
-/**
- * Render a backend tool result into a single string for ext.
- *
- * The Aexol backend wraps results as `{ content: [{ type: "json", json: ... }] }`
- * but may also send `{ type: "text", text: ... }`. We pick the first content
- * item, prefer JSON when present (pretty-print so the model can read it),
- * fall back to text, and last-resort stringify the whole content array.
- */
-function renderContentToString(content) {
-    if (content.length === 0)
-        return "";
-    const first = content[0];
-    if (first.json !== undefined) {
-        try {
-            return JSON.stringify(first.json, null, 2);
-        }
-        catch {
-            return String(first.json);
-        }
-    }
-    if (typeof first.text === "string")
-        return first.text;
-    // For image/audio/binary content types, return a metadata placeholder
-    // instead of serializing the raw base64 data into the model context.
-    if (first.type === "image" || first.type === "audio") {
-        const mimeType = typeof first.mimeType === "string" ? first.mimeType : first.type;
-        const dataLen = typeof first.data === "string" ? first.data.length : 0;
-        return `[${first.type}: ${mimeType}${dataLen ? `, ${dataLen.toLocaleString()} bytes base64` : ""}]`;
-    }
-    try {
-        // Strip large binary fields from serialization to prevent context overflow.
-        const safe = content.map((c) => {
-            const copy = { ...c };
-            if ("data" in copy && typeof copy.data === "string" && copy.data.length > 200) {
-                copy.data = `[${copy.data.length.toLocaleString()} bytes base64 omitted]`;
-            }
-            return copy;
-        });
-        return JSON.stringify(safe, null, 2);
-    }
-    catch {
-        return String(content);
-    }
-}
 /** Build a one-line human label from a tool name like "remote_cloud_search". */
 function toLabel(name) {
     return name
@@ -127,8 +86,6 @@ async function refreshBindingForCwd(cwd) {
  */
 const MODEL_INJECTING_TOOLS = new Set([
     "remote_start_from",
-    "remote_start_inference",
-    "remote_refine_inference_artifact",
     "remote_refine_from_task",
     "remote_refine_aexol_content",
 ]);
@@ -163,19 +120,18 @@ function augmentParams(toolName, params, ctx, binding) {
     return { params: augmented };
 }
 export default async function aexolMcpExtension(ext) {
-    const cfg = await readConfig();
-    if (!cfg) {
-        // Pre-flight in cli.ts should have caught this. Logging is enough.
-        process.stderr.write(`[aexol-mcp] No config found at ${getConfigFile()}; Aexol tools disabled. Run \`spectral login\`.\n`);
-        return;
-    }
-    const apiUrl = getApiUrl(cfg.apiUrl);
-    const token = cfg.teamApiKey || cfg.userJwt || "";
-    if (!token) {
-        process.stderr.write(`[aexol-mcp] No auth token in ${getConfigFile()}; Aexol tools disabled. Run \`spectral login\`.\n`);
+    // Shared bootstrap (config load, token resolution, client + initial
+    // tools/list call, OAuth re-auth on 401/403) lives in
+    // ./aexol-backend-client.ts. Diagnostics stream through this sink so the
+    // extension's stderr output is unchanged.
+    const boot = await createAexolBackendClient({
+        warn: (line) => process.stderr.write(`[aexol-mcp] ${line}\n`),
+    });
+    if (!boot.ok) {
+        process.stderr.write(`[aexol-mcp] ${boot.message}\n`);
         return;
     }
-    const client = new AexolMcpClient(apiUrl, token);
+    const { client, apiUrl, tools } = boot;
     // ---- Load local Studio binding on session start --------------------------
     ext.on("session_start", async (_event, ctx) => {
         try {
@@ -193,47 +149,6 @@ export default async function aexolMcpExtension(ext) {
             // Non-fatal — remote tools still work with explicit teamId/projectId.
         }
     });
-    let tools;
-    try {
-        tools = await client.listTools();
-    }
-    catch (err) {
-        const msg = err instanceof AexolMcpError || err instanceof Error ? err.message : String(err);
-        process.stderr.write(`[aexol-mcp] Failed to fetch tool catalog from ${apiUrl}: ${msg}\n`);
-        // Attempt auto-reauth via OAuth browser flow on auth errors
-        if (err instanceof AexolMcpError && (err.status === 401 || err.status === 403)) {
-            const { ensureAuthenticated } = await import("../auth-helper.js");
-            const authResult = await ensureAuthenticated();
-            if (authResult.ok && authResult.config) {
-                const newToken = authResult.config.teamApiKey || authResult.config.userJwt || "";
-                if (newToken && newToken !== token) {
-                    process.stderr.write("[aexol-mcp] Re-authenticated — retrying tool catalog fetch...\n");
-                    const newClient = new AexolMcpClient(apiUrl, newToken);
-                    try {
-                        tools = await newClient.listTools();
-                    }
-                    catch (retryErr) {
-                        const retryMsg = retryErr instanceof Error ? retryErr.message : String(retryErr);
-                        process.stderr.write(`[aexol-mcp] Retry also failed: ${retryMsg}\n`);
-                        process.stderr.write("[aexol-mcp] Continuing without Aexol tools.\n");
-                        return;
-                    }
-                }
-                else {
-                    process.stderr.write("[aexol-mcp] Re-authentication did not produce a new token. Continuing without Aexol tools.\n");
-                    return;
-                }
-            }
-            else {
-                process.stderr.write(`[aexol-mcp] Re-authentication failed: ${authResult.reason ?? "unknown"}. Continuing without Aexol tools.\n`);
-                return;
-            }
-        }
-        else {
-            process.stderr.write("[aexol-mcp] Continuing without Aexol tools.\n");
-            return;
-        }
-    }
     let registered = 0;
     for (const tool of tools) {
         // Defensive defaults: an empty-object schema is valid JSON Schema and

package/dist/extensions/logic-trace-backend-draft.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Backend refine draft adapter for the logic-trace extension.
+ *
+ * Implements the `LogicTraceDraftRunner` seam (see logic-trace.ts) on top of
+ * the backend from/refine pipeline instead of the local LLM agent loop:
+ *   1. `remote_refine_aexol_content` — submits the CURRENT remote logic.aexol
+ *      content plus a compressed merge instruction prompt (full-spec rewrite,
+ *      "merge, never append-only", grammar + leak rules) and the serialized
+ *      recent-activity delta. Answers `{ ok, task: { id, status } }`. The
+ *      session model is intentionally NOT sent — the backend resolves the
+ *      team's default model.
+ *   2. `remote_get_from_task` — polled locally (NOT via remote_wait_task,
+ *      whose internal wait exceeds the MCP client's 30s fetch abort) until a
+ *      terminal status or the configured timeout. Answers
+ *      `{ ok, task: { id, status, aexolCode, … } }`.
+ *   3. COMPLETED with an `aexolCode` → `{ submitted: { content, changed } }`
+ *      where `changed` is a plain string comparison against the current
+ *      remote content.
+ *   4. Anything else (FAILED / CANCELLED / poll timeout / missing content /
+ *      any error) → `{}` — the empty outcome is the seam's fallback signal
+ *      and attemptLogicTraceSync retries with the local draft runner. The
+ *      adapter NEVER throws past the seam.
+ *
+ * This file only adapts the draft STEP; the downstream sanitize → parser
+ * gate → hash dedupe → push flow stays in logic-trace.ts untouched.
+ */
+import { AexolMcpClient } from "../mcp-client.js";
+import type { LogicTraceDraftRunner } from "./logic-trace.js";
+/** Default cadence between `remote_get_from_task` polls. */
+export declare const DEFAULT_DRAFT_BACKEND_POLL_INTERVAL_MS = 2000;
+/** Default total wait for a refine task to reach a terminal status. */
+export declare const DEFAULT_DRAFT_BACKEND_POLL_TIMEOUT_MS = 120000;
+export interface BackendRefineDraftRunnerOptions {
+    /** Bootstrapped Aexol backend MCP client (from the extension's bootstrap). */
+    client: AexolMcpClient;
+    /** Bound Studio project id (every remote_* call carries it). */
+    projectId: string;
+    /**
+     * Bound team id — injected on every refine/get call so team access
+     * resolves to the BOUND project's team, not the token's first membership.
+     */
+    teamId?: string;
+    /** Poll cadence for `remote_get_from_task` (default 2s). */
+    pollIntervalMs?: number;
+    /** Total wait for a terminal task status (default 120s). */
+    pollTimeoutMs?: number;
+    /** Optional retry hint forwarded to `remote_refine_aexol_content`. */
+    maxRetries?: number;
+    /** Optional guidance forwarded to `remote_refine_aexol_content`. */
+    guidance?: string;
+    /**
+     * Constraint block (grammar + leak rules) merged into the refinement
+     * prompt. Supplied by the caller so the adapter stays decoupled from the
+     * logic-trace grammar constant. Only the shared leak-rule list is imported
+     * from logic-trace.ts directly, and it is read lazily inside
+     * buildRefinementPrompt (never at module-eval time) to stay safe within
+     * the logic-trace ↔ backend-draft import cycle.
+     */
+    promptRules?: string;
+    /** Injectable sleep (tests). */
+    sleep?: (ms: number) => Promise<void>;
+}
+/**
+ * Build a `LogicTraceDraftRunner` that delegates the .aexol draft step to the
+ * backend from/refine pipeline. See the module doc for the outcome contract.
+ */
+export declare function createBackendRefineDraftRunner(options: BackendRefineDraftRunnerOptions): LogicTraceDraftRunner;
+//# sourceMappingURL=logic-trace-backend-draft.d.ts.map

package/dist/extensions/logic-trace-backend-draft.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"logic-trace-backend-draft.d.ts","sourceRoot":"","sources":["../../src/extensions/logic-trace-backend-draft.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,OAAO,EAAE,cAAc,EAAuB,MAAM,kBAAkB,CAAC;AAEvE,OAAO,KAAK,EAGX,qBAAqB,EACrB,MAAM,kBAAkB,CAAC;AAI1B,4DAA4D;AAC5D,eAAO,MAAM,sCAAsC,OAAQ,CAAC;AAC5D,uEAAuE;AACvE,eAAO,MAAM,qCAAqC,SAAU,CAAC;AAqB7D,MAAM,WAAW,+BAA+B;IAC/C,8EAA8E;IAC9E,MAAM,EAAE,cAAc,CAAC;IACvB,gEAAgE;IAChE,SAAS,EAAE,MAAM,CAAC;IAClB;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,4DAA4D;IAC5D,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,4DAA4D;IAC5D,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,sEAAsE;IACtE,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,oEAAoE;IACpE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;;;;;OAOG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,gCAAgC;IAChC,KAAK,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CACtC;AAqBD;;;GAGG;AACH,wBAAgB,8BAA8B,CAC7C,OAAO,EAAE,+BAA+B,GACtC,qBAAqB,CAoGvB"}