@psnext/slingcli 3.0.20260820-2 → 3.0.20260827-1

package/node_modules/@earendil-works/pi-coding-agent/dist/package-manager-cli.js

@@ -1,6 +1,8 @@
-import { join } from "node:path";
+import { existsSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, renameSync, rmSync, writeFileSync, } from "node:fs";
+import { join, resolve } from "node:path";
 import { Markdown } from "@earendil-works/pi-tui";
 import chalk from "chalk";
+import lockfile from "proper-lockfile";
 import { selectConfig } from "./cli/config-selector.js";
 import { createProjectTrustContext } from "./cli/project-trust.js";
 import { APP_NAME, CONFIG_DIR_NAME, detectInstallMethod, getAgentDir, getPackageDir, getSelfUpdateCommand, getSelfUpdateUnavailableInstruction, PACKAGE_NAME, VERSION, } from "./config.js";
@@ -10,9 +12,168 @@ import { resolveProjectTrusted } from "./core/project-trust.js";
 import { DefaultResourceLoader } from "./core/resource-loader.js";
 import { SettingsManager } from "./core/settings-manager.js";
 import { hasTrustRequiringProjectResources, ProjectTrustStore } from "./core/trust-manager.js";
-import { spawnProcess } from "./utils/child-process.js";
+import { spawnProcess, spawnProcessSync, waitForChildProcess } from "./utils/child-process.js";
+import { canonicalizePath, getCwdRelativePath } from "./utils/paths.js";
+import { getPiUserAgent } from "./utils/pi-user-agent.js";
 import { formatVersionCheckError, getLatestPiRelease, isNewerPackageVersion } from "./utils/version-check.js";
 import { cleanupWindowsSelfUpdateQuarantine, quarantineWindowsNativeDependencies, } from "./utils/windows-self-update.js";
+const DEFAULT_INSTALLER_API_BASE = "https://pi.dev/api/installer/releases";
+const MANAGED_INSTALL_MARKER = "managed-install.json";
+const MANAGED_RELEASE_VERSION_RE = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/;
+function getActiveManagedInstallRoot() {
+    const configuredRoot = process.env.PI_MANAGED_INSTALL_ROOT?.trim();
+    if (!configuredRoot)
+        return undefined;
+    const managedRoot = resolve(configuredRoot);
+    const releasesDir = canonicalizePath(join(managedRoot, "releases"));
+    // The launcher environment is inherited by child processes. Do not classify a
+    // source checkout or another Pi installation launched from managed Pi as managed.
+    if (getCwdRelativePath(canonicalizePath(getPackageDir()), releasesDir) === undefined)
+        return undefined;
+    const markerPath = join(managedRoot, MANAGED_INSTALL_MARKER);
+    try {
+        const marker = JSON.parse(readFileSync(markerPath, "utf8"));
+        if (marker.kind !== "pi-managed-install" || marker.schemaVersion !== 1 || marker.layout !== "releases-v1") {
+            throw new Error();
+        }
+    }
+    catch {
+        throw new Error(`Managed install marker is missing or invalid: ${markerPath}`);
+    }
+    return managedRoot;
+}
+async function fetchInstallerArtifact(url, label) {
+    const response = await fetch(url, { headers: { "User-Agent": getPiUserAgent(VERSION) } });
+    if (!response.ok) {
+        throw new Error(`Could not download managed installer ${label} from ${url}: HTTP ${response.status}`);
+    }
+    return await response.text();
+}
+async function runManagedNpmCi(stageDir) {
+    const args = [
+        "ci",
+        "--ignore-scripts",
+        "--min-release-age=0",
+        "--omit=dev",
+        "--include=optional",
+        "--no-fund",
+        "--no-audit",
+        "--loglevel=error",
+        "--progress=false",
+    ];
+    const code = await waitForChildProcess(spawnProcess("npm", args, { cwd: stageDir, stdio: "inherit" }));
+    if (code !== 0)
+        throw new Error(`npm ${args.join(" ")} exited with code ${code ?? "unknown"}`);
+}
+function verifyManagedRelease(releaseDir, expectedVersion) {
+    const binPath = join(releaseDir, "node_modules", ".bin", process.platform === "win32" ? `${APP_NAME}.cmd` : APP_NAME);
+    const result = spawnProcessSync(binPath, ["--version"], {
+        encoding: "utf8",
+        stdio: ["ignore", "pipe", "pipe"],
+    });
+    if (result.error || result.status !== 0) {
+        const reason = result.error?.message || result.stderr.trim() || `exit code ${result.status ?? "unknown"}`;
+        throw new Error(`Could not verify managed Pi ${expectedVersion}: ${reason}`);
+    }
+    const installedVersion = result.stdout.trim();
+    if (installedVersion !== expectedVersion) {
+        throw new Error(`Managed Pi smoke test returned version ${installedVersion}; expected ${expectedVersion}.`);
+    }
+}
+function activateManagedRelease(managedRoot, version) {
+    const currentPath = join(managedRoot, "current-version");
+    const temporaryPath = join(managedRoot, `current-version.tmp.${process.pid}-${Date.now()}`);
+    try {
+        writeFileSync(temporaryPath, `${version}\n`);
+        renameSync(temporaryPath, currentPath);
+    }
+    finally {
+        rmSync(temporaryPath, { force: true });
+    }
+}
+function cleanupManagedStaging(managedRoot) {
+    const stagingRoot = join(managedRoot, "staging");
+    try {
+        for (const entry of readdirSync(stagingRoot)) {
+            if (entry.startsWith("update-")) {
+                rmSync(join(stagingRoot, entry), { force: true, recursive: true });
+            }
+        }
+    }
+    catch {
+        // The staging directory does not exist yet or is not writable.
+    }
+}
+export function cleanupManagedInstall() {
+    let managedRoot;
+    try {
+        managedRoot = getActiveManagedInstallRoot();
+    }
+    catch {
+        return;
+    }
+    if (!managedRoot)
+        return;
+    try {
+        const releaseLock = lockfile.lockSync(join(managedRoot, "update"), { realpath: false });
+        try {
+            cleanupManagedStaging(managedRoot);
+        }
+        finally {
+            releaseLock();
+        }
+    }
+    catch {
+        // A live update owns the staging directory, or cleanup is unavailable.
+    }
+}
+async function runManagedSelfUpdate(managedRoot, version) {
+    if (!MANAGED_RELEASE_VERSION_RE.test(version)) {
+        throw new Error(`Invalid managed release version: ${version}`);
+    }
+    let releaseLock;
+    try {
+        releaseLock = await lockfile.lock(join(managedRoot, "update"), { realpath: false });
+    }
+    catch (error) {
+        if (error instanceof Error && "code" in error && error.code === "ELOCKED") {
+            throw new Error("Another managed Sling update is already running.");
+        }
+        throw error;
+    }
+    let stageDir;
+    try {
+        cleanupManagedStaging(managedRoot);
+        const installerApiBase = (process.env.PI_INSTALLER_API_BASE?.trim() || DEFAULT_INSTALLER_API_BASE).replace(/\/+$/, "");
+        const releaseUrl = `${installerApiBase}/${encodeURIComponent(version)}`;
+        const stagingRoot = join(managedRoot, "staging");
+        const releasesRoot = join(managedRoot, "releases");
+        mkdirSync(releasesRoot, { recursive: true });
+        const releaseDir = join(releasesRoot, version);
+        if (existsSync(releaseDir)) {
+            verifyManagedRelease(releaseDir, version);
+            activateManagedRelease(managedRoot, version);
+            return;
+        }
+        mkdirSync(stagingRoot, { recursive: true });
+        stageDir = mkdtempSync(join(stagingRoot, "update-"));
+        const [packageJsonContent, packageLockContent] = await Promise.all([
+            fetchInstallerArtifact(`${releaseUrl}/package.json`, "package.json"),
+            fetchInstallerArtifact(`${releaseUrl}/package-lock.json`, "package-lock.json"),
+        ]);
+        writeFileSync(join(stageDir, "package.json"), packageJsonContent);
+        writeFileSync(join(stageDir, "package-lock.json"), packageLockContent);
+        await runManagedNpmCi(stageDir);
+        verifyManagedRelease(stageDir, version);
+        renameSync(stageDir, releaseDir);
+        activateManagedRelease(managedRoot, version);
+    }
+    finally {
+        if (stageDir)
+            rmSync(stageDir, { force: true, recursive: true });
+        await releaseLock();
+    }
+}
 const SELF_UPDATE_NOTE_MARKDOWN_THEME = {
     heading: (text) => chalk.bold(chalk.yellow(text)),
     link: (text) => chalk.cyan(text),
@@ -381,7 +542,7 @@ function printSelfUpdateUnavailable(npmCommand, updatePackageTarget = PACKAGE_NA
     const entrypoint = process.argv[1];
     if (entrypoint) {
         console.error("");
-        console.error(`Location of pi executable: ${entrypoint}`);
+        console.error(`Location of ${APP_NAME} executable: ${entrypoint}`);
     }
 }
 function printSelfUpdateFallback(command) {
@@ -721,10 +882,33 @@ export async function handlePackageCommand(args, runtimeOptions = {}) {
                     }
                 }
                 if (updateTargetIncludesSelf(target)) {
+                    const managedInstallRoot = getActiveManagedInstallRoot();
+                    if (managedInstallRoot && options.force) {
+                        console.error(chalk.red(`Managed ${APP_NAME} installations do not support --force; rerun the installer to repair this installation.`));
+                        process.exitCode = 1;
+                        return true;
+                    }
                     const selfUpdatePlan = await getSelfUpdatePlan(options.force);
                     if (!selfUpdatePlan.shouldRun) {
                         return true;
                     }
+                    if (managedInstallRoot) {
+                        if (selfUpdatePlan.note) {
+                            printSelfUpdateNote(selfUpdatePlan.note);
+                        }
+                        try {
+                            console.log(chalk.dim(`Updating managed ${APP_NAME} installation...`));
+                            await runManagedSelfUpdate(managedInstallRoot, selfUpdatePlan.version);
+                        }
+                        catch (error) {
+                            const message = error instanceof Error ? error.message : "Unknown managed update error";
+                            console.error(chalk.red(`Error: ${message}`));
+                            process.exitCode = 1;
+                            return true;
+                        }
+                        console.log(chalk.green(`Updated ${APP_NAME} from ${VERSION} to ${selfUpdatePlan.version}`));
+                        return true;
+                    }
                     const installMethod = detectInstallMethod();
                     if (process.platform === "win32" && installMethod !== "npm" && installMethod !== "pnpm") {
                         console.error(chalk.red(`${APP_NAME} self-update on Windows is only supported for npm and pnpm installs.`));

package/node_modules/@earendil-works/pi-coding-agent/dist/server/create-harness.js

@@ -1,4 +1,5 @@
 import { AgentHarness, createBashTool, createEditTool, createReadTool, createWriteTool, } from "@earendil-works/pi-agent-core";
+import { getExperimentalToolSampling } from "../core/experimental.js";
 import { buildSystemPrompt } from "../core/system-prompt.js";
 import { bashToolSystemPromptContribution } from "../core/tools/bash.js";
 import { editToolSystemPromptContribution } from "../core/tools/edit.js";
@@ -8,6 +9,7 @@ function createCodingAgentHarnessTool(tool, context, prompt) {
     return {
         ...tool,
         ...prompt,
+        constrainedSampling: getExperimentalToolSampling(),
         execute: (toolCallId, params, signal, onUpdate) => tool.execute(toolCallId, params, signal, onUpdate, context),
     };
 }

package/node_modules/@earendil-works/pi-coding-agent/dist/utils/frontmatter.js

@@ -1,7 +1,8 @@
 import { parse } from "yaml";
+import { stripBom } from "./text.js";
 const normalizeNewlines = (value) => value.replace(/\r\n/g, "\n").replace(/\r/g, "\n");
 const extractFrontmatter = (content) => {
-    const normalized = normalizeNewlines(content);
+    const normalized = normalizeNewlines(stripBom(content));
     if (!normalized.startsWith("---")) {
         return { yamlString: null, body: normalized };
     }

package/node_modules/@earendil-works/pi-coding-agent/dist/utils/management-http.js

@@ -7,23 +7,23 @@ const RETRYABLE_STATUS_CODES = new Set([408, 425, 429, 500, 502, 503, 504]);
  * agent/model operations: those can fail after the HTTP request starts and are
  * retried by their semantic caller instead.
  *
- * Caller cancellation is terminal. When timeoutMs is supplied, it is the
- * overall time budget shared by all attempts.
+ * Caller cancellation and timeoutMs are terminal. attemptTimeoutMs aborts
+ * only the current attempt so a hung connection can be retried.
  */
 export async function fetchWithRetry(input, init = undefined, options = {}) {
     const maxRetries = options.maxRetries === undefined || !Number.isFinite(options.maxRetries)
         ? 2
         : Math.max(0, Math.floor(options.maxRetries));
     const retryOnStatus = options.retryOnStatus ?? true;
-    const parentSignal = init?.signal;
+    const parentSignal = init?.signal ?? undefined;
     const timeoutSignal = options.timeoutMs !== undefined && options.timeoutMs > 0 ? AbortSignal.timeout(options.timeoutMs) : undefined;
-    const signal = timeoutSignal
-        ? parentSignal
-            ? AbortSignal.any([parentSignal, timeoutSignal])
-            : timeoutSignal
-        : parentSignal;
+    const attemptTimeoutMs = options.attemptTimeoutMs !== undefined && options.attemptTimeoutMs > 0 ? options.attemptTimeoutMs : undefined;
     for (let attempt = 0;; attempt++) {
-        signal?.throwIfAborted();
+        parentSignal?.throwIfAborted();
+        timeoutSignal?.throwIfAborted();
+        const attemptTimeoutSignal = attemptTimeoutMs ? AbortSignal.timeout(attemptTimeoutMs) : undefined;
+        const signals = [parentSignal, timeoutSignal, attemptTimeoutSignal].filter((signal) => signal !== undefined);
+        const signal = signals.length > 1 ? AbortSignal.any(signals) : signals[0];
         try {
             const response = await fetch(input, signal ? { ...init, signal } : init);
             const shouldRetry = retryOnStatus && RETRYABLE_STATUS_CODES.has(response.status) && attempt < maxRetries;
@@ -38,9 +38,13 @@ export async function fetchWithRetry(input, init = undefined, options = {}) {
             }
         }
         catch (error) {
+            const attemptTimedOut = attemptTimeoutSignal?.aborted === true && !parentSignal?.aborted && !timeoutSignal?.aborted;
             if (parentSignal?.aborted ||
                 timeoutSignal?.aborted ||
-                (error instanceof Error && error.name === "AbortError" && timeoutSignal === undefined) ||
+                (error instanceof Error &&
+                    error.name === "AbortError" &&
+                    !attemptTimedOut &&
+                    timeoutSignal === undefined) ||
                 attempt >= maxRetries) {
                 throw error;
             }

package/node_modules/@earendil-works/pi-coding-agent/dist/utils/shell.js

@@ -1,5 +1,5 @@
 import { existsSync } from "node:fs";
-import { delimiter } from "node:path";
+import { delimiter, join } from "node:path";
 import { spawn, spawnSync } from "child_process";
 import { getBinDir } from "../config.js";
 /**
@@ -12,11 +12,11 @@ function isLegacyWslBashPath(path) {
 function getBashShellConfig(shell) {
     return isLegacyWslBashPath(shell) ? { shell, args: ["-s"], commandTransport: "stdin" } : { shell, args: ["-c"] };
 }
-function findBashOnPath() {
+function findExecutableOnPath(executable) {
     if (process.platform === "win32") {
         // Windows: Use 'where' and verify file exists (where can return non-existent paths)
         try {
-            const result = spawnSync("where", ["bash.exe"], {
+            const result = spawnSync("where", [executable], {
                 encoding: "utf-8",
                 timeout: 5000,
                 windowsHide: true,
@@ -35,7 +35,7 @@ function findBashOnPath() {
     }
     // Unix: Use 'which' and trust its output (handles Termux and special filesystems)
     try {
-        const result = spawnSync("which", ["bash"], { encoding: "utf-8", timeout: 5000 });
+        const result = spawnSync("which", [executable], { encoding: "utf-8", timeout: 5000 });
         if (result.status === 0 && result.stdout) {
             const firstMatch = result.stdout.trim().split(/\r?\n/)[0];
             if (firstMatch) {
@@ -80,7 +80,7 @@ export function getShellConfig(customShellPath) {
             }
         }
         // 3. Fallback: search bash.exe on PATH (Cygwin, MSYS2, WSL, etc.)
-        const bashOnPath = findBashOnPath();
+        const bashOnPath = findExecutableOnPath("bash.exe");
         if (bashOnPath) {
             return getBashShellConfig(bashOnPath);
         }
@@ -94,12 +94,24 @@ export function getShellConfig(customShellPath) {
     if (existsSync("/bin/bash")) {
         return getBashShellConfig("/bin/bash");
     }
-    const bashOnPath = findBashOnPath();
+    const bashOnPath = findExecutableOnPath("bash");
     if (bashOnPath) {
         return getBashShellConfig(bashOnPath);
     }
     return { shell: "sh", args: ["-c"] };
 }
+export const POWERSHELL_ARGS = ["-NoProfile", "-NonInteractive", "-ExecutionPolicy", "Bypass", "-Command"];
+/** Resolve PowerShell on Windows, preferring PowerShell 7 when available. */
+export function getPowerShellConfig() {
+    if (process.platform !== "win32") {
+        throw new Error("The powershell tool is only available on Windows.");
+    }
+    const shell = findExecutableOnPath("pwsh.exe") ?? findExecutableOnPath("powershell.exe");
+    if (!shell) {
+        throw new Error("No PowerShell executable found. Install PowerShell or add powershell.exe/pwsh.exe to PATH.");
+    }
+    return { shell, args: [...POWERSHELL_ARGS] };
+}
 export function getShellEnv() {
     const binDir = getBinDir();
     const pathKey = Object.keys(process.env).find((key) => key.toLowerCase() === "path") ?? "PATH";
@@ -171,16 +183,18 @@ export function killTrackedDetachedChildren() {
  */
 export function killProcessTree(pid) {
     if (process.platform === "win32") {
-        // Use taskkill on Windows to kill process tree
+        // Use the trusted System32 executable so cleanup does not depend on PATH.
         try {
-            spawn("taskkill", ["/F", "/T", "/PID", String(pid)], {
+            const child = spawn(join(process.env.SystemRoot ?? "C:\\Windows", "System32", "taskkill.exe"), ["/F", "/T", "/PID", String(pid)], {
                 stdio: "ignore",
                 detached: true,
                 windowsHide: true,
             });
+            // A failed spawn emits "error" asynchronously; consume it to avoid crashing Node.
+            child.once("error", () => { });
         }
         catch {
-            // Ignore errors if taskkill fails
+            // Ignore errors if taskkill fails.
         }
     }
     else {

package/node_modules/@earendil-works/pi-coding-agent/dist/utils/syntax-highlight.js

@@ -1,5 +1,64 @@
-import hljs from "highlight.js/lib/index.js";
+import hljs from "highlight.js/lib/core.js";
+import bash from "highlight.js/lib/languages/bash.js";
+import c from "highlight.js/lib/languages/c.js";
+import cpp from "highlight.js/lib/languages/cpp.js";
+import csharp from "highlight.js/lib/languages/csharp.js";
+import dart from "highlight.js/lib/languages/dart.js";
+import go from "highlight.js/lib/languages/go.js";
+import groovy from "highlight.js/lib/languages/groovy.js";
+import java from "highlight.js/lib/languages/java.js";
+import javascript from "highlight.js/lib/languages/javascript.js";
+import kotlin from "highlight.js/lib/languages/kotlin.js";
+import lua from "highlight.js/lib/languages/lua.js";
+import nix from "highlight.js/lib/languages/nix.js";
+import perl from "highlight.js/lib/languages/perl.js";
+import php from "highlight.js/lib/languages/php.js";
+import python from "highlight.js/lib/languages/python.js";
+import ruby from "highlight.js/lib/languages/ruby.js";
+import rust from "highlight.js/lib/languages/rust.js";
+import scala from "highlight.js/lib/languages/scala.js";
+import swift from "highlight.js/lib/languages/swift.js";
+import typescript from "highlight.js/lib/languages/typescript.js";
 import { decodeHtmlEntityAt } from "./html.js";
+const eagerLanguages = {
+    python,
+    java,
+    go,
+    javascript,
+    cpp,
+    typescript,
+    php,
+    ruby,
+    c,
+    csharp,
+    nix,
+    bash,
+    rust,
+    scala,
+    kotlin,
+    swift,
+    dart,
+    groovy,
+    perl,
+    lua,
+};
+for (const [name, language] of Object.entries(eagerLanguages)) {
+    hljs.registerLanguage(name, language);
+}
+let allLanguagesPromise;
+export function loadAllHighlightLanguages() {
+    if (!allLanguagesPromise) {
+        allLanguagesPromise = new Promise((resolve) => {
+            setImmediate(() => {
+                void import("highlight.js/lib/index.js").then(() => resolve(), () => {
+                    // Eager languages and plaintext fallback remain available.
+                    resolve();
+                });
+            });
+        });
+    }
+    return allLanguagesPromise;
+}
 const SPAN_CLOSE = "</span>";
 const HIGHLIGHT_CLASS_PREFIX = "hljs-";
 function getScopeFromSpanTag(tag) {

package/node_modules/@earendil-works/pi-coding-agent/dist/utils/text.js

@@ -0,0 +1,9 @@
+/** Split a leading UTF-8 byte order mark from decoded text. */
+export function splitBom(content) {
+    return content.startsWith("\uFEFF") ? { bom: "\uFEFF", text: content.slice(1) } : { bom: "", text: content };
+}
+/** Remove a leading UTF-8 byte order mark from decoded text. */
+export function stripBom(content) {
+    return splitBom(content).text;
+}
+//# sourceMappingURL=text.js.map

package/node_modules/@earendil-works/pi-coding-agent/dist/utils/tools-manager.js

@@ -1,4 +1,3 @@
-import chalk from "chalk";
 import { spawnSync } from "child_process";
 import { chmodSync, createWriteStream, existsSync, mkdirSync, readdirSync, renameSync, rmSync } from "fs";
 import { arch, platform } from "os";
@@ -280,9 +279,12 @@ const TERMUX_PACKAGES = {
     fd: "fd",
     rg: "ripgrep",
 };
-// Ensure a tool is available, downloading if necessary
-// Returns the path to the tool, or null if unavailable
-export async function ensureTool(tool, silent = false) {
+/**
+ * Ensure a tool is available, downloading if necessary.
+ * Reports progress through `onStatus`; status messages are otherwise silent.
+ * Returns the tool path, or undefined if unavailable.
+ */
+export async function ensureTool(tool, onStatus) {
     const existingPath = getToolPath(tool);
     if (existingPath) {
         return existingPath;
@@ -291,35 +293,28 @@ export async function ensureTool(tool, silent = false) {
     if (!config)
         return undefined;
     if (isOfflineModeEnabled()) {
-        if (!silent) {
-            console.log(chalk.yellow(`${config.name} not found. Offline mode enabled, skipping download.`));
-        }
+        onStatus?.({ type: "warning", message: `${config.name} not found. Offline mode enabled, skipping download.` });
         return undefined;
     }
     // On Android/Termux, Linux binaries don't work due to Bionic libc incompatibility.
     // Users must install via pkg.
     if (platform() === "android") {
         const pkgName = TERMUX_PACKAGES[tool] ?? tool;
-        if (!silent) {
-            console.log(chalk.yellow(`${config.name} not found. Install with: pkg install ${pkgName}`));
-        }
+        onStatus?.({ type: "warning", message: `${config.name} not found. Install with: pkg install ${pkgName}` });
         return undefined;
     }
     // Tool not found - download it
-    if (!silent) {
-        console.log(chalk.dim(`${config.name} not found. Downloading...`));
-    }
+    onStatus?.({ type: "info", message: `${config.name} not found. Downloading...` });
     try {
         const path = await downloadTool(tool);
-        if (!silent) {
-            console.log(chalk.dim(`${config.name} installed to ${path}`));
-        }
+        onStatus?.({ type: "info", message: `${config.name} installed to ${path}` });
         return path;
     }
     catch (e) {
-        if (!silent) {
-            console.log(chalk.yellow(`Failed to download ${config.name}: ${e instanceof Error ? e.message : e}`));
-        }
+        onStatus?.({
+            type: "warning",
+            message: `Failed to download ${config.name}: ${e instanceof Error ? e.message : e}`,
+        });
         return undefined;
     }
 }

package/node_modules/@earendil-works/pi-coding-agent/docs/designs/2026-08-24-smart-model-attribution-design.md

@@ -0,0 +1,149 @@
+# Smart Model Attribution Design
+
+**Jira:** [AGPM-6619](https://publicisbodhi.atlassian.net/browse/AGPM-6619)  
+**Branch:** `feature/AGPM-6619-smart-model-attribution`
+
+## Goal
+
+Show the concrete model that handles a query through a Slingshot smart model.
+
+The terminal shows one dim line after the completed assistant response:
+
+```text
+Model used: gpt-5-nano-2025-08-07
+```
+
+The feature does not change the existing footer.
+
+## Scope
+
+All implementation changes stay in `slingshot/`.
+
+The change does not modify these areas:
+
+- `packages/*`
+- `protocol/`
+- The core assistant-message renderer
+- The core model type
+- The OpenAI-compatible response parser
+
+The parser already stores the concrete response model in `AssistantMessage.responseModel`.
+
+## Model Family Data
+
+The models API identifies smart models with `metadata.family = "smart"`.
+
+Slingshot defines a local model type that adds an optional `family` string to the shared model shape. This is a Slingshot-only type.
+
+`transformApiModels()` validates `metadata.family`. It copies the value only when the value is a non-empty string.
+
+The Slingshot model cache stores the local model type. JSON serialization preserves the optional property.
+
+Provider registration uses object spreads. These spreads preserve the property at runtime without a core type change.
+
+Slingshot rebuilds a set of smart model IDs each time it loads or refreshes the model catalog.
+
+## Smart Model Request Compatibility
+
+Smart models use the OpenAI Chat Completions API. This path already records the routed chunk model in `AssistantMessage.responseModel`.
+
+Slingshot disables client reasoning parameters for smart models. The backend can route a query to a concrete model that does not accept `reasoning_effort`.
+
+Slingshot limits smart-model output to 16,384 tokens. The router can select a concrete model with that output limit, and the gateway does not clamp larger client values.
+
+These overrides apply only to models with `family = "smart"`.
+
+## Event Flow
+
+Slingshot registers hooks for the agent lifecycle.
+
+1. The `agent_start` hook clears the pending routed-model value.
+2. The `message_end` hook examines each completed assistant message.
+3. The hook ignores messages from other providers.
+4. The hook checks the requested model ID against the current smart-model set.
+5. The hook stores a non-empty `responseModel` from the last qualifying assistant message.
+6. The `agent_end` hook appends one custom transcript entry when a value exists.
+7. The hook clears the pending value after it appends the entry.
+
+The final qualifying completion supplies the model attribution for a tool-assisted turn. This creates one attribution line for each user query.
+
+The design uses `agent_end` because the assistant component is complete at that time. A custom entry added during `message_end` appears above the streaming assistant component.
+
+## Transcript Rendering
+
+Slingshot registers a renderer for a provider-specific custom entry type.
+
+The renderer validates the stored data before it reads the model name. It uses `theme.fg("dim", ...)` for the complete line.
+
+The custom entry has these properties:
+
+- It appears directly after the completed response.
+- It persists in the session transcript.
+- It appears again after a session reload.
+- It does not enter the LLM context.
+
+The entry text is `Model used: <responseModel>`.
+
+## Fallback Behavior
+
+Slingshot does not add an attribution entry in these cases:
+
+- The selected provider is not Slingshot.
+- The requested model is not in the smart-model set.
+- The family value is missing, empty, or not a string.
+- The assistant message has no non-empty `responseModel`.
+- The turn ends without a qualifying assistant completion.
+
+The feature does not show a placeholder. It does not change the footer or the assistant response.
+
+A model refresh replaces the smart-model set. This prevents stale family data after a catalog change.
+
+## Tests
+
+All new and changed tests stay in `slingshot/`.
+
+### Model transformation and cache
+
+Tests cover these cases:
+
+- A valid family value survives model transformation.
+- A malformed or empty family value is not stored.
+- The model cache preserves the family value.
+- A smart model uses Chat Completions without client reasoning parameters.
+- A smart model has a 16,384-token output limit.
+
+### Attribution lifecycle
+
+Tests cover these cases:
+
+- A smart Slingshot model records a non-empty `responseModel`.
+- A non-smart Slingshot model does not create an entry.
+- A message from another provider does not create an entry.
+- A missing `responseModel` does not create an entry.
+- A tool-assisted turn uses the last qualifying completion.
+- A new turn clears the prior pending value.
+- A model refresh replaces stale smart-model IDs.
+
+### Renderer
+
+Tests cover these cases:
+
+- Valid entry data renders `Model used: <model>` with the dim theme color.
+- Invalid persisted data renders no component and does not throw an error.
+
+## Documentation
+
+The repository has no `slingshot/CHANGELOG.md`. This change will not create one only for this feature.
+
+No package changelog changes are in scope because the user restricted implementation changes to `slingshot/`.
+
+## Success Criteria
+
+The design is successful when all these statements are true:
+
+- A smart Slingshot query shows the concrete response model after the completed response.
+- A normal model query shows no attribution line.
+- The existing footer is unchanged.
+- The attribution survives session reload.
+- The attribution does not enter LLM context.
+- No file outside `slingshot/` changes during implementation.