@almanak/mcp-server 0.2.4 → 0.2.6

package/dist/tools.js

@@ -48,8 +48,10 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.PlatformToolHandler = void 0;
 const node_fs_1 = require("node:fs");
 const path = __importStar(require("node:path"));
+const client_1 = require("./client");
 const runner_1 = require("./testing/runner");
 const workspace_git_1 = require("./workspace-git");
+const backtest_v3_1 = require("./backtest-v3");
 const EXPORT_COMMIT_MESSAGE = 'feat: initial strategy export from Almanak';
 const ROOT_DIR_ALLOWED_RE = /^[a-zA-Z0-9._/-]+$/;
 const WORKSPACE_ABSOLUTE_PATH_RE = /^\/(?:tmp\/)?workspaces\/[^/]+\/(.+)$/;
@@ -58,6 +60,9 @@ const COMMIT_SHA_PREFIX_RE = /^[0-9a-fA-F]{7,40}$/;
 const FULL_COMMIT_SHA_RE = /^[0-9a-fA-F]{40}$/;
 const PRICE_TIMEFRAMES = ['auto', '1m', '5m', '15m', '1h', '4h', '1d'];
 const PRICE_TIMEFRAME_SET = new Set(PRICE_TIMEFRAMES);
+// strategies_spec field units. The frontend SpecPanel (SpecFieldUnit in
+// packages/frontend/src/stores/almanak-code-store.ts) renders each one; keep both in step.
+const SPEC_FIELD_UNITS = ['pct', 'pct_of_balance', 'usd', 'bps', 'raw'];
 // Decision grid options, in seconds (1m, 5m, 15m, 1h, 4h, 1d): the SDK's canonical cadences, mirrored by the
 // platform API validation. The default is one hour.
 const DECISION_INTERVALS_SECONDS = [60, 300, 900, 3600, 14400, 86400];
@@ -105,9 +110,9 @@ function parseSdkVersion(value) {
         phaseNumber: phaseNumber ? Number(phaseNumber) : 0,
     };
 }
-function isSdkVersionBacktestable(version) {
+function isSdkVersionBacktestable(version, minimum = MIN_BACKTEST_SDK_VERSION) {
     const left = parseSdkVersion(version);
-    const right = parseSdkVersion(MIN_BACKTEST_SDK_VERSION);
+    const right = parseSdkVersion(minimum);
     if (!left || !right)
         return false;
     for (const key of ['major', 'minor', 'patch']) {
@@ -118,6 +123,67 @@ function isSdkVersionBacktestable(version) {
         return SDK_PHASE_RANK[left.phase] > SDK_PHASE_RANK[right.phase];
     return left.phaseNumber >= right.phaseNumber;
 }
+/**
+ * `backtests_run` as SDK v3 sessions see it. A v3 run executes a backtest YAML committed and pushed in the linked
+ * repository with that commit's config.yaml; the window, inventory, cadence and costs live in that file, so none of
+ * the v2 window inputs apply.
+ */
+const BACKTESTS_RUN_V3_DEFINITION = {
+    name: 'backtests_run',
+    description: 'Run a hosted backtest of a linked SDK v3 strategy (SDK v3 backtests are a staging preview). The run executes a ' +
+        'backtest YAML committed in the strategy repository together with config.yaml and strategy.py at the same commit. ' +
+        'The mode, window, inventory, execution, costs and data policy all come from that file (schema: ' +
+        '`almanak support --schema backtest`); this tool takes no window or capital inputs. Only committed, pushed files ' +
+        'run: local or unpushed edits are never used, so commit and push the backtest YAML (and any strategy change) first, ' +
+        'then call this with commit_sha set to the pushed commit (git rev-parse HEAD after the push). ' +
+        'backtest_config_path names the file; omitted, the only committed backtest.yaml or backtest-economic.yaml at the ' +
+        'repository root is used. Economic mode (`mode: economic`) refuses banded liquidity allocations: a config.yaml with ' +
+        'a `band` allocation is refused before submission (V3_BACKTEST_BAND_UNSUPPORTED). ' +
+        'The call submits the run, renders a live backtest widget in the chat and PAUSES until the run finishes; it then ' +
+        'resumes you with the outcome as _widgetResponse. A v3 summary carries no v2 metrics: call backtests_results with ' +
+        'the backtest_id for the report (return, drawdown, positions, decision interval) or the runner failure (stage, code, ' +
+        'message). Do not re-submit while a run is in progress and do not claim results before they arrive. If the user ' +
+        'chooses "Continue in background", you are resumed early with status RUNNING; read it later with backtests_results. ' +
+        'Errors carry errorCode: COMMIT_UNRESOLVED (the commit is not in the repository: push it), REPO_ACCESS or ' +
+        'GITHUB_UNAVAILABLE (repository access, not a push problem), BACKTEST_CONFIG_NOT_FOUND (file not in that commit), ' +
+        'BACKTEST_CONFIG_UNREADABLE, BACKTEST_CONFIG_AMBIGUOUS (several files, pass backtest_config_path), ' +
+        'V3_BACKTEST_INPUT_INVALID, V3_BACKTEST_BAND_UNSUPPORTED, SDK_GENERATION_MISMATCH (the strategy link is not stored as ' +
+        'SDK v3; do not add v2 inputs). Users can have at most 10 active backtests; a 429 BACKTEST_CONCURRENCY_LIMIT error ' +
+        'means do not retry until one finishes or is cancelled.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            strategy_link_id: {
+                type: 'string',
+                description: 'The strategy link ID (from strategies_list or the strategies_export_workspace result).',
+            },
+            backtest_config_path: {
+                type: 'string',
+                description: 'Repository-relative path of the committed backtest YAML to run, for example "backtest-economic.yaml". ' +
+                    'Optional when exactly one of backtest.yaml or backtest-economic.yaml is committed at the repository root.',
+            },
+            commit_sha: {
+                type: 'string',
+                description: 'Optional 7-40 character hexadecimal commit SHA or unique prefix of a pushed commit; it is resolved to a full SHA ' +
+                    'in the linked repository. Pass the commit you just pushed. Omitted, the head of branch (or the default branch) runs.',
+            },
+            branch: {
+                type: 'string',
+                description: 'Optional branch whose head runs when commit_sha is omitted. Defaults to the repository default branch.',
+            },
+            show_widget: {
+                const: true,
+                description: 'Must be true. Renders the live backtest widget and pauses this call until the run completes.',
+            },
+        },
+        required: ['strategy_link_id', 'show_widget'],
+    },
+};
+/** Appended to the backtests_results description in SDK v3 sessions only; other sessions keep the v2 text. */
+const BACKTESTS_RESULTS_V3_NOTE = ' For an SDK v3 run (sdk_generation "v3") it returns the committed backtest_config_path, progress while running, ' +
+    'failure (stage preflight/run/infra, code, message) for a FAILED run, and for a COMPLETED run report_summary (mode, ' +
+    'window, decision interval, evaluations, metrics, net_quote_return, positions and equity counts) with the full ' +
+    'result.json written to .logs/.';
 /** One-line human summary of a spec's `content.exit` for the injected teardown-disclosure field. */
 function summarizeSpecExit(exit) {
     if (exit === undefined || exit === null || (typeof exit === 'object' && Object.keys(exit).length === 0)) {
@@ -984,7 +1050,7 @@ class PlatformToolHandler {
         });
         this.register('strategies', {
             name: 'strategies_spec',
-            description: "Show the user an editable Strategy Spec panel to review and approve the strategy's risk posture BEFORE building. Call early — after confirming protocol support, before scaffolding. Pass plainSummary (one-line plain-language money-at-risk), fields (the few user-facing posture choices, each {key,label,description,value,unit}), the full content (the SPEC.json values), optional presets (conservative/balanced/aggressive content variants), and show_widget=true. content must include an `exit` object stating what stop/teardown does (close actions, asset policy), and fields must include an `exit.*` entry so the user sees it. If user constraints conflict with a clean exit, surface the resolution here rather than deciding silently. Execution pauses; the user reviews/edits, then the reply is a fenced ```json``` block `{action, content}` — use the returned `content` as the approved build contract (the full SPEC values with the user's edits applied). Surface only genuine posture choices the strategy actually consults — keep safety internals in config.json.",
+            description: "Show the user an editable Strategy Spec panel to review and approve the strategy's risk posture BEFORE building. Call early — after confirming protocol support, before scaffolding. Pass plainSummary (one-line plain-language money-at-risk), fields (the few user-facing posture choices, each {key,label,description,value,unit}), the full content (the SPEC.json values), optional presets (conservative/balanced/aggressive content variants), and show_widget=true. content must include an `exit` object stating what stop/teardown does (close actions, asset policy), and fields must include an `exit.*` entry so the user sees it. If user constraints conflict with a clean exit, surface the resolution here rather than deciding silently. Give each field the unit that matches its meaning (see fields[].unit): a plain percentage such as an LP range width is `pct`, never `pct_of_balance`. Execution pauses; the user reviews/edits, then the reply is a fenced ```json``` block `{action, content}` — use the returned `content` as the approved build contract (the full SPEC values with the user's edits applied). Surface only genuine posture choices the strategy actually consults — keep safety internals in config.json.",
             inputSchema: {
                 type: 'object',
                 properties: {
@@ -1003,8 +1069,14 @@ class PlatformToolHandler {
                                 value: { type: ['string', 'number', 'boolean'], description: 'Current value (number | string | boolean).' },
                                 unit: {
                                     type: 'string',
-                                    enum: ['pct_of_balance', 'usd', 'bps', 'raw'],
-                                    description: 'pct_of_balance | usd | bps | raw — drives display + funding scaling.',
+                                    enum: SPEC_FIELD_UNITS,
+                                    description: 'Unit badge for the value exactly as stored in content; the panel never rescales it. ' +
+                                        'pct = a plain percentage in percent points (8 means 8%): LP range width, recenter/rebalance ' +
+                                        'thresholds, slippage, stop-loss, drawdown, target LTV. pct_of_balance = ONLY position sizing: the ' +
+                                        "share of the strategy's funded balance one trade or position uses (percent points). usd = a US " +
+                                        'dollar amount. bps = basis points (50 means 0.5%). raw = anything else (counts, durations, token ' +
+                                        'amounts, ticks, ratios, text); no badge. If content stores a percentage as a fraction (0.08 for ' +
+                                        '8%), use raw and state the scale in the label.',
                                 },
                                 editable: { type: 'boolean' },
                                 min: { type: 'number' },
@@ -1208,7 +1280,10 @@ class PlatformToolHandler {
                 required: ['strategy_link_id'],
             },
         }, (args) => this.linkWorkspace(args));
-        this.register('strategies', {
+        // The session generation picks the schema the model sees: v2 sessions keep the v2 window inputs unchanged, v3
+        // sessions see the committed-backtest-file inputs. The handler dispatches on the strategy's stored
+        // framework_version either way, which is authoritative.
+        const backtestsRunDefinition = this.options.sdkGeneration === 'v3' ? BACKTESTS_RUN_V3_DEFINITION : {
             name: 'backtests_run',
             description: 'Run a backtest of a linked strategy against historical market data. Use this after the strategy is in its ' +
                 'repository (strategies_export_workspace, or git push on a linked chat) and before deploying — backtests run against a ' +
@@ -1272,7 +1347,8 @@ class PlatformToolHandler {
                 },
                 required: ['strategy_link_id', 'start_time', 'end_time', 'show_widget'],
             },
-        }, (args) => this.runBacktest(args));
+        };
+        this.register('strategies', backtestsRunDefinition, (args) => this.runBacktest(args));
         this.register('strategies', {
             name: 'backtests_results',
             description: "Fetch a backtest run's status and results for diagnosis — including WHY a run traded or held. Returns " +
@@ -1285,7 +1361,8 @@ class PlatformToolHandler {
                 'returning its absolute path — use Grep/Read on it for the equity curve, trades, and price series (not ' +
                 'returned inline). Works for any backtest of your linked strategies, including runs started from the ' +
                 'platform UI and runs from earlier sessions. Use it BEFORE editing strategy code in response to a bad ' +
-                'backtest, to attribute the cause first.',
+                'backtest, to attribute the cause first.' +
+                (this.options.sdkGeneration === 'v3' ? BACKTESTS_RESULTS_V3_NOTE : ''),
             inputSchema: {
                 type: 'object',
                 properties: {
@@ -1602,7 +1679,7 @@ class PlatformToolHandler {
      * turn into a widget (the error card auto-resolves the gate immediately).
      */
     async runBacktest(args) {
-        var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l, _m, _o, _p, _q, _r, _s, _t, _u, _v, _w, _x, _y;
+        var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l, _m, _o, _p, _q, _r, _s, _t, _u, _v, _w, _x, _y, _z, _0, _1;
         const strategyLinkId = String((_a = args.strategy_link_id) !== null && _a !== void 0 ? _a : '').trim();
         const startTime = String((_b = args.start_time) !== null && _b !== void 0 ? _b : '').trim();
         // required[] only checks presence — an empty/whitespace id would call
@@ -1650,6 +1727,28 @@ class PlatformToolHandler {
                 return fail((_e = strategyRes === null || strategyRes === void 0 ? void 0 : strategyRes.statusCode) !== null && _e !== void 0 ? _e : 404, (_g = (_f = strategyRes === null || strategyRes === void 0 ? void 0 : strategyRes.message) !== null && _f !== void 0 ? _f : strategyRes === null || strategyRes === void 0 ? void 0 : strategyRes.error) !== null && _g !== void 0 ? _g : 'Strategy not found');
             }
             const strategy = strategyRes.data;
+            // The stored framework_version is authoritative for which runner family serves the strategy.
+            const sessionIsV3 = this.options.sdkGeneration === 'v3';
+            if (strategy.framework_version === 'V3') {
+                if (!sessionIsV3) {
+                    // The v2 schema requires the window inputs a v3 run refuses; retrying with other inputs cannot succeed here.
+                    return fail(400, 'This strategy is stored as SDK v3, but this chat session is not on the SDK v3 lane, so its backtests_run takes ' +
+                        'the SDK v2 window inputs that SDK v3 backtests refuse. Do not retry with other inputs: start the run from the ' +
+                        "strategy's Backtest page on the platform, or from an SDK v3 chat session attached to this strategy.", { errorCode: 'SDK_GENERATION_MISMATCH' });
+                }
+                return await this.runV3Backtest(args, strategyLinkId, strategy);
+            }
+            if (sessionIsV3) {
+                return fail(400, `The strategy link is stored as SDK ${String((_h = strategy.framework_version) !== null && _h !== void 0 ? _h : 'v2').toLowerCase()}, but this chat session ` +
+                    'runs the SDK v3 lane. The stored generation decides which backtest runs, and the two disagree, so nothing was ' +
+                    'submitted. Do not add SDK v2 window inputs; tell the user the strategy link is not recognised as SDK v3 ' +
+                    '(its repository must resolve almanak 3.x and carry strategy.py and config.yaml at the root).', { errorCode: 'SDK_GENERATION_MISMATCH' });
+            }
+            const v3Inputs = backtest_v3_1.V3_ONLY_BACKTEST_ARGS.filter((key) => args[key] !== undefined);
+            if (v3Inputs.length > 0) {
+                return fail(400, `${v3Inputs.join(', ')} ${v3Inputs.length > 1 ? 'are SDK v3 inputs' : 'is an SDK v3 input'}, and this strategy is ` +
+                    'stored as SDK v2: its backtest takes start_time and end_time (YYYY-MM-DD).', { errorCode: 'SDK_GENERATION_MISMATCH' });
+            }
             const strategyName = (typeof strategy.display_name === 'string' && strategy.display_name) ||
                 (typeof strategy.github_repo_name === 'string' && strategy.github_repo_name) ||
                 null;
@@ -1675,19 +1774,19 @@ class PlatformToolHandler {
             const refType = explicitSha ? 'commit' : 'branch';
             const refConfigRes = await this.client.getStrategyRefConfig(strategyLinkId, ref, refType);
             if ((refConfigRes === null || refConfigRes === void 0 ? void 0 : refConfigRes.valid) === false || !(refConfigRes === null || refConfigRes === void 0 ? void 0 : refConfigRes.data)) {
-                const baseError = (_j = (_h = refConfigRes === null || refConfigRes === void 0 ? void 0 : refConfigRes.message) !== null && _h !== void 0 ? _h : refConfigRes === null || refConfigRes === void 0 ? void 0 : refConfigRes.error) !== null && _j !== void 0 ? _j : `Could not resolve ref "${ref}" for the linked strategy repository.`;
+                const baseError = (_k = (_j = refConfigRes === null || refConfigRes === void 0 ? void 0 : refConfigRes.message) !== null && _j !== void 0 ? _j : refConfigRes === null || refConfigRes === void 0 ? void 0 : refConfigRes.error) !== null && _k !== void 0 ? _k : `Could not resolve ref "${ref}" for the linked strategy repository.`;
                 const recoveryGuidance = explicitSha
                     ? ` Omit commit_sha only if the user explicitly approves running the latest commit on ${defaultBranch}; ` +
                         'do not retry with different code automatically.'
                     : '';
-                return fail((_k = refConfigRes === null || refConfigRes === void 0 ? void 0 : refConfigRes.statusCode) !== null && _k !== void 0 ? _k : 400, `${baseError}${recoveryGuidance}`, {
-                    errorCode: (_l = refConfigRes === null || refConfigRes === void 0 ? void 0 : refConfigRes.errorCode) !== null && _l !== void 0 ? _l : 'INTERNAL_ERROR',
+                return fail((_l = refConfigRes === null || refConfigRes === void 0 ? void 0 : refConfigRes.statusCode) !== null && _l !== void 0 ? _l : 400, `${baseError}${recoveryGuidance}`, {
+                    errorCode: (_m = refConfigRes === null || refConfigRes === void 0 ? void 0 : refConfigRes.errorCode) !== null && _m !== void 0 ? _m : 'INTERNAL_ERROR',
                     retryable: (refConfigRes === null || refConfigRes === void 0 ? void 0 : refConfigRes.retryable) === true,
                     ...recoveryContext,
                 });
             }
             const refConfig = refConfigRes.data;
-            const commitSha = (_m = refConfig.github_commit_sha) !== null && _m !== void 0 ? _m : '';
+            const commitSha = (_o = refConfig.github_commit_sha) !== null && _o !== void 0 ? _o : '';
             if (!FULL_COMMIT_SHA_RE.test(commitSha)) {
                 return fail(400, `Could not resolve "${ref}" to a full commit SHA — has the strategy been pushed to its repository?`, {
                     errorCode: 'COMMIT_UNRESOLVED',
@@ -1698,17 +1797,22 @@ class PlatformToolHandler {
             // /ref-config — pin it to the resolved commit so it matches the config.
             const refMetaRes = await this.client.getStrategyRefMetadata(strategyLinkId, commitSha);
             if ((refMetaRes === null || refMetaRes === void 0 ? void 0 : refMetaRes.valid) === false || !(refMetaRes === null || refMetaRes === void 0 ? void 0 : refMetaRes.data)) {
-                return fail((_o = refMetaRes === null || refMetaRes === void 0 ? void 0 : refMetaRes.statusCode) !== null && _o !== void 0 ? _o : 400, (_q = (_p = refMetaRes === null || refMetaRes === void 0 ? void 0 : refMetaRes.message) !== null && _p !== void 0 ? _p : refMetaRes === null || refMetaRes === void 0 ? void 0 : refMetaRes.error) !== null && _q !== void 0 ? _q : 'Could not load strategy ref metadata');
+                return fail((_p = refMetaRes === null || refMetaRes === void 0 ? void 0 : refMetaRes.statusCode) !== null && _p !== void 0 ? _p : 400, (_r = (_q = refMetaRes === null || refMetaRes === void 0 ? void 0 : refMetaRes.message) !== null && _q !== void 0 ? _q : refMetaRes === null || refMetaRes === void 0 ? void 0 : refMetaRes.error) !== null && _r !== void 0 ? _r : 'Could not load strategy ref metadata');
             }
-            const sdkVersion = (_r = refMetaRes.data.almanak_sdk_version) !== null && _r !== void 0 ? _r : null;
+            const sdkVersion = (_s = refMetaRes.data.almanak_sdk_version) !== null && _s !== void 0 ? _s : null;
             if (!sdkVersion) {
                 return fail(400, 'Could not detect the Almanak SDK version from pyproject.toml at the selected commit.');
             }
+            if (((_u = (_t = parseSdkVersion(sdkVersion)) === null || _t === void 0 ? void 0 : _t.major) !== null && _u !== void 0 ? _u : 0) >= 3) {
+                // The backend refuses a v3 SDK against a V2 record; say why instead of submitting the v2 shape.
+                return fail(400, `Commit ${commitSha.slice(0, 7)} resolves almanak ${sdkVersion} (SDK v3), but the strategy link is stored as SDK v2. ` +
+                    'The generations disagree, so nothing was submitted; SDK v2 window inputs cannot backtest an SDK v3 repository.', { errorCode: 'SDK_GENERATION_MISMATCH', commit_sha: commitSha, sdk_version: sdkVersion });
+            }
             if (!isSdkVersionBacktestable(sdkVersion)) {
                 return fail(400, `Backtesting requires Almanak SDK >= ${MIN_BACKTEST_SDK_VERSION}; the repo pins ${sdkVersion}. ` +
                     'Upgrade the almanak dependency in pyproject.toml, push, and re-run.');
             }
-            const strategyConfig = (_s = args.strategy_config) !== null && _s !== void 0 ? _s : refConfig.effective_config_json;
+            const strategyConfig = (_v = args.strategy_config) !== null && _v !== void 0 ? _v : refConfig.effective_config_json;
             const submit = await this.client.submitBacktest({
                 github_strategy_link_id: strategyLinkId,
                 commit_sha: commitSha,
@@ -1717,7 +1821,7 @@ class PlatformToolHandler {
                 backtest_config: backtestConfig,
             });
             if ((submit === null || submit === void 0 ? void 0 : submit.valid) === false || typeof (submit === null || submit === void 0 ? void 0 : submit.id) !== 'string') {
-                return fail((_t = submit === null || submit === void 0 ? void 0 : submit.statusCode) !== null && _t !== void 0 ? _t : 400, (_v = (_u = submit === null || submit === void 0 ? void 0 : submit.error) !== null && _u !== void 0 ? _u : submit === null || submit === void 0 ? void 0 : submit.message) !== null && _v !== void 0 ? _v : 'Backtest submission failed', {
+                return fail((_w = submit === null || submit === void 0 ? void 0 : submit.statusCode) !== null && _w !== void 0 ? _w : 400, (_y = (_x = submit === null || submit === void 0 ? void 0 : submit.error) !== null && _x !== void 0 ? _x : submit === null || submit === void 0 ? void 0 : submit.message) !== null && _y !== void 0 ? _y : 'Backtest submission failed', {
                     commit_sha: commitSha,
                     sdk_version: sdkVersion,
                     ...(typeof (submit === null || submit === void 0 ? void 0 : submit.errorCode) === 'string' ? { errorCode: submit.errorCode } : {}),
@@ -1729,8 +1833,8 @@ class PlatformToolHandler {
             }
             return {
                 backtest_id: submit.id,
-                status: (_w = submit.status) !== null && _w !== void 0 ? _w : 'PENDING',
-                created_at: (_x = submit.created_at) !== null && _x !== void 0 ? _x : null,
+                status: (_z = submit.status) !== null && _z !== void 0 ? _z : 'PENDING',
+                created_at: (_0 = submit.created_at) !== null && _0 !== void 0 ? _0 : null,
                 strategy_link_id: strategyLinkId,
                 strategy_name: strategyName,
                 commit_sha: commitSha,
@@ -1739,6 +1843,175 @@ class PlatformToolHandler {
                 show_widget: true,
             };
         }
+        catch (err) {
+            return fail(502, `Backtest submission failed: ${(_1 = err === null || err === void 0 ? void 0 : err.message) !== null && _1 !== void 0 ? _1 : String(err)}`);
+        }
+    }
+    /**
+     * Submit an SDK v3 run: resolve the pushed commit, pick the committed backtest YAML the same way the strategy's
+     * Backtest page does, and send `backtest_config_path` (never the v2 `backtest_config`). Like runBacktest it never
+     * throws and every path returns a widget-renderable shape.
+     */
+    async runV3Backtest(args, strategyLinkId, strategy) {
+        var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l, _m, _o, _p, _q, _r, _s, _t, _u, _v, _w, _x, _y;
+        const strategyName = (typeof strategy.display_name === 'string' && strategy.display_name) ||
+            (typeof strategy.github_repo_name === 'string' && strategy.github_repo_name) ||
+            null;
+        const repoOwner = typeof strategy.github_repo_owner === 'string' ? strategy.github_repo_owner : '';
+        const repoName = typeof strategy.github_repo_name === 'string' ? strategy.github_repo_name : '';
+        const linkedRepo = repoOwner && repoName ? `${repoOwner}/${repoName}` : null;
+        const defaultBranch = (typeof strategy.github_default_branch === 'string' && strategy.github_default_branch.trim()) || 'main';
+        const context = { strategy_link_id: strategyLinkId, strategy_name: strategyName, sdk_generation: 'v3' };
+        const fail = (statusCode, error, extra) => ({ statusCode, error, ...context, ...extra });
+        const v2Inputs = backtest_v3_1.V2_ONLY_BACKTEST_ARGS.filter((key) => args[key] !== undefined);
+        if (v2Inputs.length > 0) {
+            return fail(400, `${v2Inputs.join(', ')} ${v2Inputs.length > 1 ? 'are SDK v2 inputs' : 'is an SDK v2 input'}. An SDK v3 backtest takes its ` +
+                'window, inventory, cadence and costs from the committed backtest YAML: set them in that file, commit and push it, ' +
+                'and call again with backtest_config_path and without the v2 inputs.', { errorCode: 'V3_BACKTEST_INPUT_INVALID' });
+        }
+        let requestedPath = null;
+        if (args.backtest_config_path !== undefined) {
+            const normalized = (0, backtest_v3_1.normalizeBacktestConfigPath)(args.backtest_config_path);
+            if ('error' in normalized) {
+                return fail(400, normalized.error, { errorCode: 'V3_BACKTEST_INPUT_INVALID' });
+            }
+            requestedPath = normalized.path;
+            context.backtest_config_path = requestedPath;
+        }
+        const explicitSha = typeof args.commit_sha === 'string' ? args.commit_sha.trim() : '';
+        const branch = typeof args.branch === 'string' ? args.branch.trim() : '';
+        if (explicitSha && branch) {
+            return fail(400, 'Pass commit_sha or branch, not both: commit_sha already names the exact code to run.', {
+                errorCode: 'V3_BACKTEST_INPUT_INVALID',
+            });
+        }
+        if (explicitSha && !COMMIT_SHA_PREFIX_RE.test(explicitSha)) {
+            return fail(400, `commit_sha must contain 7 to 40 hexadecimal characters, got "${explicitSha}".`, {
+                errorCode: 'INVALID_COMMIT_FORMAT',
+                requestedCommit: explicitSha,
+                linkedRepo,
+                defaultBranch,
+            });
+        }
+        if (args.branch !== undefined && !(0, backtest_v3_1.isValidBranchName)(branch)) {
+            return fail(400, `branch must be a git branch name, got "${branch}".`, { errorCode: 'V3_BACKTEST_INPUT_INVALID' });
+        }
+        const ref = explicitSha ? explicitSha.toLowerCase() : branch || defaultBranch;
+        const refType = explicitSha ? 'commit' : 'branch';
+        const recoveryContext = { requestedCommit: explicitSha || null, linkedRepo, defaultBranch };
+        try {
+            const refConfigRes = await this.client.getStrategyRefConfig(strategyLinkId, ref, refType);
+            const commitSha = (refConfigRes === null || refConfigRes === void 0 ? void 0 : refConfigRes.valid) === false ? '' : String((_b = (_a = refConfigRes === null || refConfigRes === void 0 ? void 0 : refConfigRes.data) === null || _a === void 0 ? void 0 : _a.github_commit_sha) !== null && _b !== void 0 ? _b : '');
+            if (!FULL_COMMIT_SHA_RE.test(commitSha)) {
+                const baseError = (_d = (_c = refConfigRes === null || refConfigRes === void 0 ? void 0 : refConfigRes.message) !== null && _c !== void 0 ? _c : refConfigRes === null || refConfigRes === void 0 ? void 0 : refConfigRes.error) !== null && _d !== void 0 ? _d : `Could not resolve ${refType} "${ref}" in the linked strategy repository.`;
+                // Push advice fits only a ref the repository does not have; access and availability errors keep their own text.
+                const errorCode = (refConfigRes === null || refConfigRes === void 0 ? void 0 : refConfigRes.valid) === false ? ((_e = refConfigRes === null || refConfigRes === void 0 ? void 0 : refConfigRes.errorCode) !== null && _e !== void 0 ? _e : 'INTERNAL_ERROR') : 'COMMIT_UNRESOLVED';
+                const guidance = errorCode !== 'COMMIT_UNRESOLVED'
+                    ? ''
+                    : explicitSha
+                        ? ` Only pushed commits can be backtested: make sure the commit is pushed to ${linkedRepo !== null && linkedRepo !== void 0 ? linkedRepo : 'the linked repository'} ` +
+                            '(git push, then git rev-parse HEAD) and call again with that SHA. Do not switch to a different commit without the user.'
+                        : ` Push the branch to ${linkedRepo !== null && linkedRepo !== void 0 ? linkedRepo : 'the linked repository'} first.`;
+                return fail((_f = refConfigRes === null || refConfigRes === void 0 ? void 0 : refConfigRes.statusCode) !== null && _f !== void 0 ? _f : 400, `${baseError}${guidance}`, {
+                    errorCode,
+                    retryable: (refConfigRes === null || refConfigRes === void 0 ? void 0 : refConfigRes.retryable) === true,
+                    ...recoveryContext,
+                });
+            }
+            context.commit_sha = commitSha;
+            const refMetaRes = await this.client.getStrategyRefMetadata(strategyLinkId, commitSha);
+            if ((refMetaRes === null || refMetaRes === void 0 ? void 0 : refMetaRes.valid) === false || !(refMetaRes === null || refMetaRes === void 0 ? void 0 : refMetaRes.data)) {
+                return fail((_g = refMetaRes === null || refMetaRes === void 0 ? void 0 : refMetaRes.statusCode) !== null && _g !== void 0 ? _g : 400, (_j = (_h = refMetaRes === null || refMetaRes === void 0 ? void 0 : refMetaRes.message) !== null && _h !== void 0 ? _h : refMetaRes === null || refMetaRes === void 0 ? void 0 : refMetaRes.error) !== null && _j !== void 0 ? _j : 'Could not load strategy ref metadata');
+            }
+            const meta = refMetaRes.data;
+            const sdkVersion = typeof meta.almanak_sdk_version === 'string' ? meta.almanak_sdk_version : '';
+            if (!sdkVersion) {
+                return fail(400, 'Could not detect the almanak SDK version (uv.lock or pyproject.toml) at the selected commit.', {
+                    errorCode: 'V3_BACKTEST_INPUT_INVALID',
+                });
+            }
+            context.sdk_version = sdkVersion;
+            if (((_l = (_k = parseSdkVersion(sdkVersion)) === null || _k === void 0 ? void 0 : _k.major) !== null && _l !== void 0 ? _l : 0) < 3 || !isSdkVersionBacktestable(sdkVersion, backtest_v3_1.MIN_BACKTEST_SDK_VERSION_V3)) {
+                return fail(400, `Hosted SDK v3 backtests need almanak ${backtest_v3_1.MIN_BACKTEST_SDK_VERSION_V3} or newer; commit ${commitSha.slice(0, 7)} resolves ` +
+                    `${sdkVersion}. Update the almanak pin (uv.lock / pyproject.toml), commit, push and re-run.`, { errorCode: 'V3_BACKTEST_INPUT_INVALID' });
+            }
+            const committed = {};
+            const configs = meta.backtest_configs && typeof meta.backtest_configs === 'object' ? meta.backtest_configs : {};
+            for (const [name, text] of Object.entries(configs)) {
+                if (typeof text === 'string')
+                    committed[name] = text;
+            }
+            const discovered = Array.isArray(meta.backtest_config_paths)
+                ? meta.backtest_config_paths.filter((name) => typeof name === 'string')
+                : Object.keys(committed);
+            const shortSha = commitSha.slice(0, 7);
+            let backtestPath = requestedPath;
+            if (!backtestPath) {
+                if (discovered.length === 1) {
+                    backtestPath = discovered[0];
+                }
+                else if (discovered.length === 0) {
+                    return fail(404, `Commit ${shortSha} has no backtest.yaml or backtest-economic.yaml at the repository root. Write the backtest YAML ` +
+                        '(schema: almanak support --schema backtest), commit and push it, then call again with backtest_config_path.', { errorCode: 'BACKTEST_CONFIG_NOT_FOUND' });
+                }
+                else {
+                    return fail(400, `Commit ${shortSha} has several backtest files (${discovered.join(', ')}); pass backtest_config_path to choose one.`, { errorCode: 'BACKTEST_CONFIG_AMBIGUOUS', backtest_config_paths: discovered });
+                }
+            }
+            context.backtest_config_path = backtestPath;
+            let backtestYaml = (_m = committed[backtestPath]) !== null && _m !== void 0 ? _m : null;
+            if (backtestYaml === null) {
+                const fileRes = await this.client.getStrategyFileContent(strategyLinkId, backtestPath, commitSha);
+                const file = (fileRes === null || fileRes === void 0 ? void 0 : fileRes.valid) === false ? null : (_o = fileRes === null || fileRes === void 0 ? void 0 : fileRes.data) === null || _o === void 0 ? void 0 : _o.file;
+                const lookupError = (fileRes === null || fileRes === void 0 ? void 0 : fileRes.valid) === false ? String((_q = (_p = fileRes === null || fileRes === void 0 ? void 0 : fileRes.message) !== null && _p !== void 0 ? _p : fileRes === null || fileRes === void 0 ? void 0 : fileRes.error) !== null && _q !== void 0 ? _q : '') : '';
+                if (typeof (file === null || file === void 0 ? void 0 : file.content) === 'string') {
+                    backtestYaml = file.content;
+                }
+                else if (file) {
+                    // The preview refuses some present files (build/dist/venv paths, directories, oversized files) with a reason.
+                    return fail(400, `Could not read ${backtestPath} at ${shortSha}: ${(_r = file.message) !== null && _r !== void 0 ? _r : 'the file is not readable as text'}. Keep the backtest ` +
+                        'YAML a small text file outside build output directories, commit and push it, then call again.', { errorCode: 'BACKTEST_CONFIG_UNREADABLE' });
+                }
+                else if (lookupError !== 'File not found') {
+                    return fail((_s = fileRes === null || fileRes === void 0 ? void 0 : fileRes.statusCode) !== null && _s !== void 0 ? _s : 502, `Could not read ${backtestPath} at ${shortSha}: ${lookupError || 'lookup failed'}`, {
+                        errorCode: 'BACKTEST_CONFIG_UNREADABLE',
+                    });
+                }
+                else {
+                    return fail(404, `${backtestPath} is not in commit ${shortSha}. Only committed, pushed files run: commit and push it, then call ` +
+                        'again with the pushed commit_sha.' +
+                        (discovered.length > 0 ? ` Committed backtest files at that commit: ${discovered.join(', ')}.` : ''), { errorCode: 'BACKTEST_CONFIG_NOT_FOUND', ...(discovered.length > 0 ? { backtest_config_paths: discovered } : {}) });
+                }
+            }
+            const configYaml = typeof meta.config_yaml === 'string' ? meta.config_yaml : '';
+            if ((0, backtest_v3_1.backtestMode)(backtestYaml) === 'economic' && (0, backtest_v3_1.declaresBandAllocation)(configYaml)) {
+                return fail(400, `${backtestPath} selects the economic model, and config.yaml at ${shortSha} declares a banded liquidity allocation ` +
+                    `(band). The SDK refuses that combination ("${backtest_v3_1.SDK_BAND_ECONOMIC_REFUSAL}"), so the run was not submitted. ` +
+                    'Tell the user; backtesting this strategy needs a fixed range allocation instead of a band.', { errorCode: 'V3_BACKTEST_BAND_UNSUPPORTED' });
+            }
+            const submit = await this.client.submitBacktest({
+                github_strategy_link_id: strategyLinkId,
+                commit_sha: commitSha,
+                sdk_version: sdkVersion,
+                sdk_generation: 'v3',
+                backtest_config_path: backtestPath,
+            });
+            if ((submit === null || submit === void 0 ? void 0 : submit.valid) === false || typeof (submit === null || submit === void 0 ? void 0 : submit.id) !== 'string') {
+                return fail((_t = submit === null || submit === void 0 ? void 0 : submit.statusCode) !== null && _t !== void 0 ? _t : 400, (_v = (_u = submit === null || submit === void 0 ? void 0 : submit.error) !== null && _u !== void 0 ? _u : submit === null || submit === void 0 ? void 0 : submit.message) !== null && _v !== void 0 ? _v : 'Backtest submission failed', {
+                    ...(typeof (submit === null || submit === void 0 ? void 0 : submit.errorCode) === 'string' ? { errorCode: submit.errorCode } : {}),
+                    ...(typeof (submit === null || submit === void 0 ? void 0 : submit.activeBacktests) === 'number' ? { activeBacktests: submit.activeBacktests } : {}),
+                    ...(typeof (submit === null || submit === void 0 ? void 0 : submit.maxActiveBacktests) === 'number' ? { maxActiveBacktests: submit.maxActiveBacktests } : {}),
+                    ...((submit === null || submit === void 0 ? void 0 : submit.errorCode) === 'BACKTEST_CONCURRENCY_LIMIT' ? { retryable: false } : {}),
+                });
+            }
+            return {
+                backtest_id: submit.id,
+                status: (_w = submit.status) !== null && _w !== void 0 ? _w : 'PENDING',
+                created_at: (_x = submit.created_at) !== null && _x !== void 0 ? _x : null,
+                ...context,
+                show_widget: true,
+            };
+        }
         catch (err) {
             return fail(502, `Backtest submission failed: ${(_y = err === null || err === void 0 ? void 0 : err.message) !== null && _y !== void 0 ? _y : String(err)}`);
         }
@@ -1752,7 +2025,7 @@ class PlatformToolHandler {
      * path returned — equity curves and per-trade detail are read on demand.
      */
     async getBacktestResults(args) {
-        var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l, _m, _o, _p, _q, _r, _s, _t, _u, _v, _w;
+        var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l, _m, _o, _p, _q, _r, _s, _t, _u, _v;
         const backtestId = typeof args.backtest_id === 'string' ? args.backtest_id.trim() : '';
         if (!backtestId) {
             return {
@@ -1774,6 +2047,9 @@ class PlatformToolHandler {
                 backtest_id: backtestId,
             };
         }
+        if ((0, backtest_v3_1.isV3BacktestRun)(run)) {
+            return this.getV3BacktestResults(backtestId, run);
+        }
         const summaryVerdict = summarizeRunValidity((_d = run.result_summary) === null || _d === void 0 ? void 0 : _d.run_validity);
         const base = {
             backtest_id: (_e = run.id) !== null && _e !== void 0 ? _e : backtestId,
@@ -1844,34 +2120,117 @@ class PlatformToolHandler {
                     'environment/data plane, not strategy logic.'
                 : 'This run predates decision telemetry (older SDK), so per-tick hold reasons are unavailable — attribute ' +
                     'zero-trade results by reproducing the decision path rather than assuming a strategy bug.');
-        // Same path-hardening rules as fetchAgentLogsToFile: the id is a UUID in
-        // normal usage, but strip anything that isn't hex/dash before using it in
-        // a filename.
+        const written = await this.writeBacktestResultArtifact(backtestId, doc);
+        if ('refused' in written) {
+            return { error: written.refused, statusCode: 500 };
+        }
+        if ('error' in written) {
+            return { ...inline, result_write_error: written.error, hint: telemetryHint };
+        }
+        const fpath = written.path;
+        return {
+            ...inline,
+            result_path: fpath,
+            hint: 'Full result.json written to result_path — Grep/Read it for equity_curve, trades, price_series, and ' +
+                'data_manifest entries (content is not returned inline). ' +
+                telemetryHint,
+        };
+    }
+    /**
+     * Persist a backtest result document to `.logs/` for Grep/Read and return its path. Compact on purpose: the artifact
+     * can be MBs and is a Grep/jq target. The id is a UUID in normal usage, but anything other than letters, digits and
+     * dashes is stripped before it reaches a filename (the same hardening as fetchAgentLogsToFile), and a document above
+     * the fetch cap is not written.
+     */
+    async writeBacktestResultArtifact(backtestId, doc) {
+        var _a;
         const safeId = backtestId.replace(/[^a-zA-Z0-9-]/g, '').slice(0, 8);
         const logsDir = path.resolve(process.cwd(), '.logs');
         const fpath = path.join(logsDir, `backtest_${safeId}_result_${Date.now()}.json`);
         if (!fpath.startsWith(logsDir + path.sep)) {
-            return { error: 'refused to write outside .logs/', statusCode: 500 };
+            return { refused: 'refused to write outside .logs/' };
         }
         try {
+            const text = JSON.stringify(doc);
+            const bytes = Buffer.byteLength(text, 'utf8');
+            if (bytes > client_1.BACKTEST_RESULT_MAX_BYTES) {
+                return { error: `result.json is ${bytes} bytes, above the ${client_1.BACKTEST_RESULT_MAX_BYTES}-byte cap; it was not written to .logs/` };
+            }
             await node_fs_1.promises.mkdir(logsDir, { recursive: true });
-            // Compact on purpose: the artifact can be MBs and this is a Grep/jq
-            // target, so don't double its size (and the in-memory copy) with pretty-printing.
-            await node_fs_1.promises.writeFile(fpath, JSON.stringify(doc), 'utf8');
+            await node_fs_1.promises.writeFile(fpath, text, 'utf8');
         }
         catch (err) {
+            return { error: `Could not persist result.json to .logs/: ${(_a = err === null || err === void 0 ? void 0 : err.message) !== null && _a !== void 0 ? _a : String(err)}` };
+        }
+        return { path: fpath };
+    }
+    /**
+     * backtests_results for an SDK v3 run. The runner's summary carries run facts (or a failure block with stage, code
+     * and message) instead of v2 metrics, and the result document embeds the SDK report under `report`; the v2 trade,
+     * decision-telemetry and manifest fields do not exist, so they are not reported as empty.
+     */
+    async getV3BacktestResults(backtestId, run) {
+        var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k;
+        const failure = (0, backtest_v3_1.v3BacktestFailure)(run);
+        const base = {
+            backtest_id: (_a = run.id) !== null && _a !== void 0 ? _a : backtestId,
+            status: run.status,
+            sdk_generation: 'v3',
+            created_at: (_b = run.created_at) !== null && _b !== void 0 ? _b : null,
+            completed_at: (_c = run.completed_at) !== null && _c !== void 0 ? _c : null,
+            strategy_link_id: (_d = run.github_strategy_link_id) !== null && _d !== void 0 ? _d : null,
+            commit_sha: (_e = run.commit_sha) !== null && _e !== void 0 ? _e : null,
+            sdk_version: (_f = run.sdk_version) !== null && _f !== void 0 ? _f : null,
+            ...(0, backtest_v3_1.v3BacktestSource)(run),
+            result_summary: (_g = run.result_summary) !== null && _g !== void 0 ? _g : null,
+            error_message: (_h = run.error_message) !== null && _h !== void 0 ? _h : null,
+        };
+        if (run.status !== 'COMPLETED') {
+            if (run.status === 'FAILED') {
+                return { ...base, failure, hint: (0, backtest_v3_1.v3FailureHint)(failure, typeof run.error_message === 'string' ? run.error_message : null) };
+            }
+            if (run.status === 'CANCELLED') {
+                return { ...base, hint: 'The run was cancelled by the user; no results exist and none will. Do not re-run unless asked.' };
+            }
             return {
-                ...inline,
-                result_write_error: `Could not persist result.json to .logs/: ${(_w = err === null || err === void 0 ? void 0 : err.message) !== null && _w !== void 0 ? _w : String(err)}`,
-                hint: telemetryHint,
+                ...base,
+                progress: (0, backtest_v3_1.backtestProgress)(run),
+                hint: 'The run has not finished. progress (when present) is the runner snapshot: phase, completed_ticks of total_ticks ' +
+                    'and simulation_elapsed_ms. Call again later; do not re-submit.',
             };
         }
+        let doc;
+        try {
+            doc = await this.client.getBacktestResult(backtestId);
+        }
+        catch (err) {
+            return { ...base, result_fetch_error: `Result fetch failed: ${(_j = err === null || err === void 0 ? void 0 : err.message) !== null && _j !== void 0 ? _j : String(err)}` };
+        }
+        if (!doc || doc.valid === false) {
+            return { ...base, result_fetch_error: (_k = doc === null || doc === void 0 ? void 0 : doc.error) !== null && _k !== void 0 ? _k : 'Backtest result not found' };
+        }
+        const inline = {
+            ...base,
+            report_summary: (0, backtest_v3_1.summarizeV3Report)(doc),
+            artifacts: doc.artifacts && typeof doc.artifacts === 'object' ? Object.keys(doc.artifacts) : [],
+        };
+        const reportHint = 'report_summary compacts the SDK report: metrics and net_quote_return are in the quote currency, and absent fields ' +
+            'mean the run did not measure them (for example no price bindings), never zero. incomplete_equity_points counts marks ' +
+            'where a held asset had no valid price.';
+        const written = await this.writeBacktestResultArtifact(backtestId, doc);
+        if ('refused' in written) {
+            return { error: written.refused, statusCode: 500 };
+        }
+        if ('error' in written) {
+            return { ...inline, result_write_error: written.error, hint: reportHint };
+        }
+        const fpath = written.path;
         return {
             ...inline,
             result_path: fpath,
-            hint: 'Full result.json written to result_path — Grep/Read it for equity_curve, trades, price_series, and ' +
-                'data_manifest entries (content is not returned inline). ' +
-                telemetryHint,
+            hint: 'Full result.json written to result_path; the SDK report is under `report` (equity_curve, price_series, positions, ' +
+                'wallets, assumptions). Grep/Read it for detail. ' +
+                reportHint,
         };
     }
     /**