@aexol/spectral 0.9.221 → 0.9.222

package/dist/extensions/logic-trace-backend-draft.js

@@ -0,0 +1,171 @@
+/**
+ * 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 { LOGIC_TRACE_LEAK_RULES } from "./logic-trace.js";
+const LOGIC_TRACE_DEBUG_ENV = "PI_LOGIC_TRACE_DEBUG";
+/** Default cadence between `remote_get_from_task` polls. */
+export const DEFAULT_DRAFT_BACKEND_POLL_INTERVAL_MS = 2_000;
+/** Default total wait for a refine task to reach a terminal status. */
+export const DEFAULT_DRAFT_BACKEND_POLL_TIMEOUT_MS = 120_000;
+function debugEnabled() {
+    const v = process.env[LOGIC_TRACE_DEBUG_ENV]?.trim().toLowerCase();
+    return v === "1" || v === "true" || v === "yes" || v === "on";
+}
+function debug(line, extra) {
+    if (!debugEnabled())
+        return;
+    process.stderr.write(`[logic-trace-backend-draft] ${line}${extra !== undefined ? ` ${JSON.stringify(extra)}` : ""}\n`);
+}
+function firstJson(content) {
+    const first = content[0];
+    return first && typeof first.json === "object" && first.json !== null
+        ? first.json
+        : undefined;
+}
+const defaultSleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+const MERGE_INSTRUCTIONS = `Update the ONE logic.aexol file given below: it is the project's single business-logic spec (domain types, enums, roles, workflows, agents). Return the COMPLETE updated file as aexolCode — a full-spec rewrite, never a diff, patch or changelog.
+- "Merge, never append-only": extend or reorganize the existing types/enums/roles/workflows/agents with the new facts; do not duplicate definitions that already exist.
+- The returned aexolCode MUST parse with the Aexol parser; keep the file compact and grammar-valid.
+- Keep existing correct definitions; remove one only when it is clearly superseded by the new information.
+- Do not invent facts beyond the recent activity below.`;
+function buildRefinementPrompt(delta, promptRules) {
+    return [
+        MERGE_INSTRUCTIONS,
+        // Shared leak rules — the same bullet list LOGIC_TRACE_SYSTEM carries,
+        // defined once in logic-trace.ts. Read lazily (function scope): the
+        // logic-trace ↔ backend-draft import cycle makes top-level access a TDZ
+        // hazard.
+        LOGIC_TRACE_LEAK_RULES,
+        promptRules ? `\n${promptRules}` : "",
+        `\nRECENT AGENT ACTIVITY:\n${delta}`,
+    ].join("\n");
+}
+/**
+ * Build a `LogicTraceDraftRunner` that delegates the .aexol draft step to the
+ * backend from/refine pipeline. See the module doc for the outcome contract.
+ */
+export function createBackendRefineDraftRunner(options) {
+    const pollIntervalMs = options.pollIntervalMs ?? DEFAULT_DRAFT_BACKEND_POLL_INTERVAL_MS;
+    const pollTimeoutMs = options.pollTimeoutMs ?? DEFAULT_DRAFT_BACKEND_POLL_TIMEOUT_MS;
+    const sleep = options.sleep ?? defaultSleep;
+    return async (input) => {
+        try {
+            const currentContent = input.currentContent;
+            // Without current remote content there is nothing to refine — the
+            // local runner owns authoring a starting spec (starter template).
+            if (typeof currentContent !== "string" || !currentContent.trim()) {
+                debug("no current remote content → fallback signal");
+                return {};
+            }
+            if (input.signal?.aborted) {
+                debug("aborted before refine call");
+                return {};
+            }
+            const refinementPrompt = buildRefinementPrompt(input.delta, options.promptRules);
+            const teamArg = options.teamId ? { teamId: options.teamId } : {};
+            const started = await options.client.callTool("remote_refine_aexol_content", {
+                aexolContent: currentContent,
+                refinementPrompt,
+                projectId: options.projectId,
+                ...teamArg,
+                ...(options.guidance !== undefined ? { guidance: options.guidance } : {}),
+                ...(options.maxRetries !== undefined ? { maxRetries: options.maxRetries } : {}),
+            });
+            if (started.isError) {
+                debug("remote_refine_aexol_content reported an error → fallback signal");
+                return {};
+            }
+            const json = firstJson(started.content);
+            // Real wire shape: { ok, task: { id, status } }. `?? json` tolerates a
+            // legacy flat { id, status } payload — the same both-shapes unwrap as
+            // extractCreatedFileId in logic-trace.ts (json.id ?? json.file.id).
+            // A missing/undefined task collapses to {} → no id → the fallback
+            // signal below.
+            const task = (json?.task ?? json ?? {});
+            const taskId = typeof task.id === "string" ? task.id : undefined;
+            if (!taskId) {
+                debug("refine returned no task id → fallback signal", { task });
+                return {};
+            }
+            // Poll locally to a terminal status (remote_wait_task's internal wait
+            // would exceed the client's 30s fetch abort — do not use it).
+            const deadline = Date.now() + pollTimeoutMs;
+            for (;;) {
+                let res;
+                try {
+                    res = await options.client.callTool("remote_get_from_task", { taskId });
+                }
+                catch (err) {
+                    debug("remote_get_from_task threw → fallback signal", {
+                        errorMessage: err instanceof Error ? err.message : String(err),
+                    });
+                    return {};
+                }
+                if (res.isError) {
+                    debug("remote_get_from_task reported an error (task failed?) → fallback signal");
+                    return {};
+                }
+                const pollJson = firstJson(res.content);
+                // Same nested unwrap as the refine response: the real backend
+                // answers { ok, task: { id, status, aexolCode, … } }.
+                const poll = (pollJson?.task ?? pollJson ?? {});
+                const status = typeof poll.status === "string" ? poll.status.toUpperCase() : "";
+                if (status === "COMPLETED") {
+                    const code = typeof poll.aexolCode === "string" ? poll.aexolCode : undefined;
+                    if (!code || !code.trim()) {
+                        debug("task COMPLETED without aexolCode → fallback signal");
+                        return {};
+                    }
+                    const changed = code !== currentContent;
+                    debug("backend refine task completed", { taskId, changed });
+                    return { submitted: { content: code, changed } };
+                }
+                if (status === "FAILED" || status === "CANCELLED") {
+                    debug("backend refine task terminal failure → fallback signal", { status });
+                    return {};
+                }
+                if (Date.now() >= deadline) {
+                    debug("backend refine poll timeout → fallback signal", { pollTimeoutMs });
+                    return {};
+                }
+                await sleep(pollIntervalMs);
+                if (input.signal?.aborted) {
+                    debug("aborted while polling → fallback signal");
+                    return {};
+                }
+            }
+        }
+        catch (err) {
+            // Never throw past the draftRunner seam: any unexpected error is the
+            // empty outcome, which attemptLogicTraceSync turns into the local
+            // draft fallback.
+            debug("backend draft failed → fallback signal", {
+                errorMessage: err instanceof Error ? err.message : String(err),
+            });
+            return {};
+        }
+    };
+}

package/dist/extensions/logic-trace-validate.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Parser-backed validity gate for the ONE cloud `logic.aexol` file.
+ *
+ * The logic-trace extension (see `logic-trace.ts`) maintains a remote
+ * `logic.aexol` mirror of the project's business logic. Every path that can
+ * write that file — the draft LLM's `submit_logic_trace` tool, the automatic
+ * sync engine, and the manual `remote_logic_trace_write` tool — funnels
+ * through this gate, so the remote file can never hold content the Aexol
+ * parser rejects.
+ *
+ * The parser itself lives in `src/generated/parser/` (vendored verbatim from
+ * `packages/parser/` by `scripts/vendor-parser.mjs`) so this module stays a
+ * static, dependency-free import that works in packaged checkouts too.
+ */
+export interface SpecParseDiagnostics {
+    /** true only when the spec parses AND the validator reports zero errors. */
+    ok: boolean;
+    /** Readable "line N: message" strings for every blocking problem. */
+    errors: string[];
+    /** Readable strings for non-blocking / best-practice advisories. */
+    warnings: string[];
+}
+/**
+ * Parse `content` and run the semantic validator. Never throws — parser
+ * failures become `errors` entries and `ok: false` diagnostics.
+ */
+export declare function validateLogicTraceSpec(content: string): SpecParseDiagnostics;
+/**
+ * Render diagnostics as one newline-joined block (empty string when nothing
+ * to report) ready to be appended to a tool-result error message.
+ */
+export declare function formatSpecErrors(result: SpecParseDiagnostics): string;
+//# sourceMappingURL=logic-trace-validate.d.ts.map

package/dist/extensions/logic-trace-validate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"logic-trace-validate.d.ts","sourceRoot":"","sources":["../../src/extensions/logic-trace-validate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AASH,MAAM,WAAW,oBAAoB;IACpC,4EAA4E;IAC5E,EAAE,EAAE,OAAO,CAAC;IACZ,qEAAqE;IACrE,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,oEAAoE;IACpE,QAAQ,EAAE,MAAM,EAAE,CAAC;CACnB;AAyBD;;;GAGG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,MAAM,GAAG,oBAAoB,CAiB5E;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,oBAAoB,GAAG,MAAM,CAKrE"}

package/dist/extensions/logic-trace-validate.js

@@ -0,0 +1,73 @@
+/**
+ * Parser-backed validity gate for the ONE cloud `logic.aexol` file.
+ *
+ * The logic-trace extension (see `logic-trace.ts`) maintains a remote
+ * `logic.aexol` mirror of the project's business logic. Every path that can
+ * write that file — the draft LLM's `submit_logic_trace` tool, the automatic
+ * sync engine, and the manual `remote_logic_trace_write` tool — funnels
+ * through this gate, so the remote file can never hold content the Aexol
+ * parser rejects.
+ *
+ * The parser itself lives in `src/generated/parser/` (vendored verbatim from
+ * `packages/parser/` by `scripts/vendor-parser.mjs`) so this module stays a
+ * static, dependency-free import that works in packaged checkouts too.
+ */
+import { Validator, parseAexol, } from "../generated/parser/mod.js";
+/** Extract the "at line N[:M]" line number a SyntaxError message carries. */
+function lineOfParseFailure(err) {
+    const message = err instanceof Error ? err.message : String(err);
+    const match = message.match(/at line (\d+)/);
+    return match ? Number(match[1]) : undefined;
+}
+/**
+ * Format a thrown parse failure as "line N: <message>" when the message
+ * carries line information, otherwise as the bare message.
+ */
+function describeParseFailure(err) {
+    const message = err instanceof Error ? err.message : String(err);
+    const line = lineOfParseFailure(err);
+    if (line === undefined)
+        return message;
+    return `line ${line}: ${message}`;
+}
+/** Format a validator issue as "line N: message" (nodes always carry a line). */
+function describeValidatorIssue(issue) {
+    return `line ${issue.node.location.line}: ${issue.message}`;
+}
+/**
+ * Parse `content` and run the semantic validator. Never throws — parser
+ * failures become `errors` entries and `ok: false` diagnostics.
+ */
+export function validateLogicTraceSpec(content) {
+    if (typeof content !== "string") {
+        return { ok: false, errors: ["content is not a string: " + typeof content], warnings: [] };
+    }
+    const errors = [];
+    const warnings = [];
+    let program;
+    try {
+        program = parseAexol(content);
+    }
+    catch (err) {
+        errors.push(describeParseFailure(err));
+        return { ok: false, errors, warnings };
+    }
+    const result = new Validator(program).validate();
+    for (const issue of result.errors)
+        errors.push(describeValidatorIssue(issue));
+    for (const issue of result.warnings)
+        warnings.push(describeValidatorIssue(issue));
+    return { ok: errors.length === 0, errors, warnings };
+}
+/**
+ * Render diagnostics as one newline-joined block (empty string when nothing
+ * to report) ready to be appended to a tool-result error message.
+ */
+export function formatSpecErrors(result) {
+    const lines = [];
+    for (const error of result.errors)
+        lines.push(`- Error: ${error}`);
+    for (const warning of result.warnings)
+        lines.push(`- Warning: ${warning}`);
+    return lines.join("\n");
+}

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

@@ -0,0 +1,213 @@
+/**
+ * Logic trace extension.
+ *
+ * Maintains EXACTLY ONE cloud-hosted file, `logic.aexol`, inside the Aexol
+ * Studio project the current directory is bound to (`.aexol/aexol.jsonc`).
+ * The file mirrors the project's business logic (types / enums / roles /
+ * workflows / agents) as a valid Aexol specification.
+ *
+ * Automatic refresh works the same way observational memory refreshes
+ * observations (see `../memory/hooks/observer-trigger.ts`):
+ *   - `turn_end` hook fires the refresh attempt,
+ *   - a token threshold gates how much new material must exist before a run,
+ *   - an in-flight singleton prevents concurrent runs,
+ *   - a passive flag (`PI_LOGIC_TRACE_PASSIVE`) disables it entirely.
+ *
+ * A `session_before_compact` hook additionally forces one flush attempt with
+ * the accumulated delta before the context is compacted away (mirroring the
+ * flush-before-compact semantics of `../memory/hooks/compaction-hook.ts`).
+ *
+ * Each refresh fetches the CURRENT remote `logic.aexol` and lets the model
+ * return the FULL updated spec (merge, never append-only) through a single
+ * `submit_logic_trace` tool call. Pushes are skipped when the model reports
+ * no change or when the content hash is unchanged (hashId).
+ *
+ * This is a SEPARATE mechanism from memory/observations — it only reuses
+ * generic helpers from `../memory/` and never writes any memory state.
+ */
+import { Type } from "../sdk/ai/index.js";
+import { type AgentTool } from "../sdk/agent-core/index.js";
+import { type ExtensionAPI, type ExtensionUIContext } from "../sdk/coding-agent/index.js";
+import { type StudioBinding } from "../studio-binding.js";
+import { type AexolBackendBootstrap } from "./aexol-backend-client.js";
+import { type BackendRefineDraftRunnerOptions } from "./logic-trace-backend-draft.js";
+import { type Entry } from "../memory/branch.js";
+/** The single remote file this extension maintains. */
+export declare const LOGIC_TRACE_REMOTE_PATH = "logic.aexol";
+/** Default token amount of new material required before an automatic sync. */
+export declare const DEFAULT_THRESHOLD_TOKENS = 800;
+/** Default cadence between backend refine task polls (draftBackend path). */
+export declare const DEFAULT_DRAFT_BACKEND_POLL_INTERVAL_MS = 2000;
+/** Default total wait for a backend refine task to reach a terminal status. */
+export declare const DEFAULT_DRAFT_BACKEND_TIMEOUT_MS = 120000;
+export interface LogicTraceModelRef {
+    provider: string;
+    id: string;
+}
+export interface LogicTraceSettings {
+    passive?: boolean;
+    thresholdTokens?: number;
+    /**
+     * Opt-in: draft the .aexol spec through the backend from/refine pipeline
+     * (remote_refine_aexol_content) instead of the local LLM draftRunner.
+     * Default false — the local draft runner stays the default path and the
+     * fallback whenever the backend draft produces no submission.
+     */
+    draftBackend?: boolean;
+    draftBackendPollIntervalMs?: number;
+    draftBackendTimeoutMs?: number;
+    draftBackendMaxRetries?: number;
+    model?: LogicTraceModelRef;
+}
+export interface LogicTraceConfig {
+    passive: boolean;
+    thresholdTokens: number;
+    draftBackend: boolean;
+    draftBackendPollIntervalMs: number;
+    draftBackendTimeoutMs: number;
+    draftBackendMaxRetries?: number;
+    model?: LogicTraceModelRef;
+}
+/**
+ * Resolve settings from `~/.spectral/settings.json` and `<cwd>/.spectral/settings.json`
+ * (project wins), then apply the `PI_LOGIC_TRACE_PASSIVE` env override — the
+ * same layered scheme as `../memory/config.ts` under its own namespaced key.
+ */
+export declare function loadLogicTraceConfig(cwd: string, env?: NodeJS.ProcessEnv): LogicTraceConfig;
+/** Exported: also embedded into the backend-refine prompt (draftBackend path). */
+export declare const LOGIC_TRACE_GRAMMAR = ".aexol quick grammar (one file, top-level blocks in any order, '#' lines are comments):\n- type Name { fieldName: Type ... } \u2014 one field per line. Scalar types: string, number, boolean, datetime.\n  A capitalized identifier references another type or enum; a trailing [] marks a list (e.g. items: Task[]).\n- enum Name { values, one per line, then '}' on its own line }.\n- role Name { permission resource { actions } } \u2014 actions from: create, read, update, delete.\n- workflow Name { a single 'initial stateA' line, then one 'state X -> Y, Z' line per transition }.\n- agent Name: BaseRole { can ..., must ..., should ... } \u2014 ' : BaseRole' is optional.\n- visitor { can ... } \u2014 optional.\n- Reserved grammar words (visitor, type, enum, role, workflow, agent, permission, action, state, transition, \u2026) must NOT appear as identifiers: e.g. do not name a visitor/test step 'state' \u2014 write 'can inspect sync status', never 'can inspect sync state'.";
+/**
+ * Leak-rule bullet list shared by LOGIC_TRACE_SYSTEM (local draft) and the
+ * backend refine adapter's MERGE_INSTRUCTIONS — defined once so the two
+ * prompts cannot drift apart.
+ */
+export declare const LOGIC_TRACE_LEAK_RULES = "- NEVER include secrets: no API keys or tokens (sk-\u2026, xox\u2026, ghp_\u2026, AKIA\u2026, JWTs), no Bearer/Authorization headers, and no KEY=value environment-variable-style assignments.\n- NEVER include absolute filesystem paths (/home/\u2026, /Users/\u2026, /root/\u2026, C:\\Users\\\u2026) or localhost URLs; refer to resources by project-relative names. Redact or omit anything sensitive.";
+export declare const LOGIC_TRACE_SYSTEM = "You maintain the ONE logic.aexol file of the current Aexol Studio project: a valid, human-readable Aexol specification that mirrors the project's business logic (domain types, enums, roles, workflows, agents). It is always a FULL spec, never a changelog.\n\n.aexol quick grammar (one file, top-level blocks in any order, '#' lines are comments):\n- type Name { fieldName: Type ... } \u2014 one field per line. Scalar types: string, number, boolean, datetime.\n  A capitalized identifier references another type or enum; a trailing [] marks a list (e.g. items: Task[]).\n- enum Name { values, one per line, then '}' on its own line }.\n- role Name { permission resource { actions } } \u2014 actions from: create, read, update, delete.\n- workflow Name { a single 'initial stateA' line, then one 'state X -> Y, Z' line per transition }.\n- agent Name: BaseRole { can ..., must ..., should ... } \u2014 ' : BaseRole' is optional.\n- visitor { can ... } \u2014 optional.\n- Reserved grammar words (visitor, type, enum, role, workflow, agent, permission, action, state, transition, \u2026) must NOT appear as identifiers: e.g. do not name a visitor/test step 'state' \u2014 write 'can inspect sync status', never 'can inspect sync state'.\n\nReference template (shape only \u2014 not content you must reproduce):\n\"\"\"\n# Project Logic\n\ntype ChecklistItem {\n    id: string\n    title: string\n    done: boolean\n    createdAt: datetime\n    assignee: string\n    status: ItemState\n}\n\nenum ItemState {\n    planned\n    started\n    done\n    archived\n}\n\nworkflow ItemLifecycle {\n    initial planned\n    state planned -> started, archived\n    state started -> done, planned\n    state done -> done\n    state archived -> archived\n}\n\nrole DomainAdmin {\n    permission checklist { create, read, update, delete }\n}\n\nagent ChecklistAgent: DomainAdmin {\n    can plan items\n    must validate titles\n}\n\nvisitor {\n    can view items\n}\n\"\"\"\n\nRules:\n- Return the COMPLETE updated file every time. Merge new facts into the existing structure (\"merge, never append-only\"): extend or reorganize existing types/agents/workflows instead of duplicating them.\n- HARD CONSTRAINT: the submitted file MUST parse with the Aexol parser (types, enums, workflows, roles, agents, visitors). Invalid syntax is rejected with parser errors you must fix and resubmit.\n- Keep the existing correct definitions; remove one only when it is clearly superseded by the new information.\n- Keep the file compact and grammar-valid. Validity beats exhaustiveness; do not invent facts beyond the recent activity.\n- NEVER include secrets: no API keys or tokens (sk-\u2026, xox\u2026, ghp_\u2026, AKIA\u2026, JWTs), no Bearer/Authorization headers, and no KEY=value environment-variable-style assignments.\n- NEVER include absolute filesystem paths (/home/\u2026, /Users/\u2026, /root/\u2026, C:\\Users\\\u2026) or localhost URLs; refer to resources by project-relative names. Redact or omit anything sensitive.\n- If the recent activity does not change business logic meaningfully (docs, prose, file paths, UI cosmetics), submit changed=false.\n- Call submit_logic_trace exactly once with the full content, then reply with a short plain-text confirmation to end the run.";
+/**
+ * Strip secret/host-specific material from spec content before it is sent to
+ * remote_update_project_file / remote_create_project_file. Best-effort,
+ * format-preserving token pass: anything that looks like an API key
+ * (sk-…, xox*-, ghp…) a Bearer token, a JWT, an AWS access key, a
+ * `KEY=value` environment assignment, an absolute filesystem path, or a
+ * localhost URL is replaced in place with a redaction marker.
+ */
+export declare function sanitizeLogicTraceContent(content: string): string;
+export interface LogicTraceDraftInput {
+    model: unknown;
+    apiKey: string;
+    headers?: Record<string, string>;
+    /** Current remote logic.aexol content, or undefined when not created yet. */
+    currentContent: string | undefined;
+    /** Serialized recent conversation delta (already length-capped). */
+    delta: string;
+    signal?: AbortSignal;
+}
+export interface LogicTraceSubmission {
+    content: string;
+    changed: boolean;
+}
+export interface LogicTraceDraftOutput {
+    submitted?: LogicTraceSubmission;
+}
+export type LogicTraceDraftRunner = (input: LogicTraceDraftInput) => Promise<LogicTraceDraftOutput>;
+declare const SubmitLogicTraceSchema: Type.TObject<{
+    content: Type.TString;
+    changed: Type.TBoolean;
+}>;
+/**
+ * Build the draft-loop `submit_logic_trace` tool. Exported (like the internal
+ * `buildReadTool` / `buildWriteTool` builders, but visible to tests) so the
+ * parser-backed gate is unit-testable without an LLM: `collect` fires exactly
+ * once per VALID submission; invalid ones are rejected with parser diagnostics
+ * and never collected. Runtime wiring in `runLogicTraceDraft` is unchanged.
+ */
+export declare function buildSubmitTool(collect: (submission: LogicTraceSubmission) => void): AgentTool<typeof SubmitLogicTraceSchema>;
+/**
+ * Default draft runner: ONE agentLoop call with a single submit tool.
+ * Structurally mirrors `../memory/observer.ts` (drain events, await result,
+ * collect via the tool's execute) but accumulates exactly one submission.
+ */
+export declare function runLogicTraceDraft(input: LogicTraceDraftInput): Promise<LogicTraceDraftOutput>;
+interface RemoteState {
+    id: string | null;
+    contentHash: string | undefined;
+}
+interface LogicTraceServerState {
+    binding: StudioBinding | null;
+    bindingMtimeMs: number | null;
+    /** Last known remote {id, contentHash} per cwd — refreshed on fetch & push. */
+    remote: RemoteState | null;
+    /** rawTokensSinceLastBound value at the last sync ATTEMPT (skip-gate watermark). */
+    syncedTokens: number;
+    /** In-flight singleton. */
+    syncInFlight: boolean;
+    /** Promise of the in-flight sync (null when idle). Test/diagnostic hook. */
+    syncPromise: Promise<LogicTraceOutcome> | null;
+}
+/**
+ * Await/diagnose the in-flight sync for a cwd (null when idle). Exposed for
+ * deterministic tests and diagnostics; production hooks stay fire-and-forget.
+ */
+export declare function pendingLogicTraceSync(cwd: string): Promise<LogicTraceOutcome> | null;
+export interface LogicTraceOutcome {
+    pushed: boolean;
+    ok: boolean;
+    reason?: string;
+}
+export interface LogicTraceSyncDeps {
+    cwd: string;
+    config: LogicTraceConfig;
+    state: LogicTraceServerState;
+    /**
+     * Lazy backend bootstrap — invoked ONLY after the binding check and the
+     * token-threshold gate passed, so an unbound or sub-threshold turn never
+     * bootstraps a backend (no token work, no OAuth browser flow).
+     */
+    getBootstrap: (cwd: string) => Promise<AexolBackendBootstrap>;
+    draftRunner: LogicTraceDraftRunner;
+    /**
+     * Factory for the optional backend refine draft runner (draftBackend
+     * setting). Invoked per sync only when config.draftBackend is on; its
+     * empty outcome triggers the local `draftRunner` fallback.
+     */
+    backendDraftFactory: (options: BackendRefineDraftRunnerOptions) => LogicTraceDraftRunner;
+    signal?: AbortSignal;
+    ui: UiNotifier;
+    model: unknown;
+    modelRegistry: unknown;
+    entries: Entry[];
+    leafId: string | undefined;
+    /** Force mode (compaction flush): bypass the token-threshold gate. */
+    force?: boolean;
+}
+interface UiNotifier {
+    hasUI: boolean;
+    ui?: ExtensionUIContext;
+}
+/**
+ * Run one guarded sync attempt. The in-flight singleton guard is checked AND
+ * set synchronously so two back-to-back hook invocations can never race into
+ * a second concurrent run. The returned promise never rejects; concurrent
+ * callers while a run is in flight get `null` instead.
+ */
+export declare function runLogicTraceSync(deps: LogicTraceSyncDeps): Promise<LogicTraceOutcome> | null;
+export interface LogicTraceExtensionOptions {
+    /** Injectable draft step — tests pass a fake runner here. */
+    draftRunner?: LogicTraceDraftRunner;
+    /**
+     * Injectable backend refine draft factory — tests point this at a stub
+     * (or leave the default to exercise the real adapter against a mock MCP).
+     */
+    backendDraftFactory?: (options: BackendRefineDraftRunnerOptions) => LogicTraceDraftRunner;
+    /** Injectable backend bootstrap — tests point this at a mock MCP server. */
+    clientFactory?: (options: {
+        warn?: (line: string) => void;
+    }) => Promise<AexolBackendBootstrap>;
+}
+/**
+ * Logic trace extension entry point: automatic refresh hooks
+ * (`turn_end`, `session_before_compact`) plus the two agent tools.
+ */
+export declare function logicTraceExtension(ext: ExtensionAPI, options?: LogicTraceExtensionOptions): void;
+export default logicTraceExtension;
+//# sourceMappingURL=logic-trace.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"logic-trace.d.ts","sourceRoot":"","sources":["../../src/extensions/logic-trace.ts"],"names":[],"mappings":"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"}