trickle-cli 0.1.213 → 0.1.215

package/dist/commands/hints.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Output source code with inline type hints (like VSCode inlay hints).
+ *
+ * Reads .trickle/variables.jsonl and renders the source with type
+ * annotations inserted inline — suitable for AI agents that need
+ * to understand runtime types without running the code.
+ *
+ * Usage:
+ *   trickle hints src/app.py              # all hints for a file
+ *   trickle hints src/app.py --values     # include sample values
+ *   trickle hints                         # all observed files
+ */
+export interface HintsOptions {
+    values?: boolean;
+}
+export declare function hintsCommand(targetFile: string | undefined, opts: HintsOptions): Promise<void>;

package/dist/commands/hints.js

@@ -0,0 +1,334 @@
+"use strict";
+/**
+ * Output source code with inline type hints (like VSCode inlay hints).
+ *
+ * Reads .trickle/variables.jsonl and renders the source with type
+ * annotations inserted inline — suitable for AI agents that need
+ * to understand runtime types without running the code.
+ *
+ * Usage:
+ *   trickle hints src/app.py              # all hints for a file
+ *   trickle hints src/app.py --values     # include sample values
+ *   trickle hints                         # all observed files
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.hintsCommand = hintsCommand;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+function typeToString(node) {
+    if (!node)
+        return "unknown";
+    switch (node.kind) {
+        case "primitive": return node.name || "unknown";
+        case "object": {
+            if (!node.properties)
+                return node.class_name || "object";
+            if (node.class_name === "Tensor" || node.class_name === "ndarray") {
+                const shape = node.properties["shape"]?.name;
+                const dtype = node.properties["dtype"]?.name;
+                const parts = [];
+                if (shape)
+                    parts.push(`shape=${shape}`);
+                if (dtype)
+                    parts.push(`dtype=${dtype}`);
+                return `${node.class_name}(${parts.join(", ")})`;
+            }
+            if (node.class_name === "DataFrame") {
+                const rows = node.properties["rows"]?.name;
+                const cols = node.properties["cols"]?.name;
+                const parts = [];
+                if (rows && cols)
+                    parts.push(`${rows}x${cols}`);
+                return `DataFrame(${parts.join(", ")})`;
+            }
+            if (node.class_name) {
+                const keys = Object.keys(node.properties).slice(0, 4);
+                const extra = Object.keys(node.properties).length > 4 ? `, +${Object.keys(node.properties).length - 4}` : "";
+                return `${node.class_name}(${keys.join(", ")}${extra})`;
+            }
+            const props = Object.entries(node.properties).slice(0, 5)
+                .map(([k, v]) => `${k}: ${typeToString(v)}`);
+            const extra = Object.keys(node.properties).length > 5 ? `, +${Object.keys(node.properties).length - 5}` : "";
+            return `{${props.join(", ")}${extra}}`;
+        }
+        case "array": {
+            const elem = node.element;
+            if (elem?.kind === "union") {
+                const members = elem.elements || elem.members;
+                if (members && members.length > 0) {
+                    const names = new Set(members.map(m => m.class_name).filter(Boolean));
+                    if (names.size === 1)
+                        return `${names.values().next().value}[]`;
+                }
+            }
+            return `${typeToString(elem || { kind: "primitive", name: "unknown" })}[]`;
+        }
+        case "tuple": return `[${(node.elements || []).map(typeToString).join(", ")}]`;
+        case "union": {
+            const members = node.elements || node.members;
+            if (!members)
+                return "unknown";
+            const names = new Set(members.map(m => m.class_name).filter(Boolean));
+            if (names.size === 1)
+                return names.values().next().value;
+            return members.map(typeToString).join(" | ");
+        }
+        case "function": return "Function";
+        default: return node.kind;
+    }
+}
+function formatSample(sample) {
+    if (sample === null || sample === undefined)
+        return "";
+    if (typeof sample === "string") {
+        if (sample.length > 40)
+            return `"${sample.substring(0, 37)}..."`;
+        return `"${sample}"`;
+    }
+    if (typeof sample === "number") {
+        return Number.isInteger(sample) ? String(sample) : sample.toFixed(4);
+    }
+    if (typeof sample === "boolean")
+        return String(sample);
+    if (Array.isArray(sample))
+        return `[...${sample.length} items]`;
+    const s = String(sample);
+    return s.length > 40 ? s.substring(0, 37) + "..." : s;
+}
+async function hintsCommand(targetFile, opts) {
+    const localDir = process.env.TRICKLE_LOCAL_DIR || path.join(process.cwd(), ".trickle");
+    const varsFile = path.join(localDir, "variables.jsonl");
+    if (!fs.existsSync(varsFile)) {
+        console.error("No trickle data found. Run your app with trickle first:");
+        console.error("  trickle run python app.py");
+        console.error("  trickle run node app.js");
+        process.exit(1);
+    }
+    // Load and deduplicate variable observations (last wins per file:line:varName)
+    const obsMap = new Map();
+    for (const line of fs.readFileSync(varsFile, "utf-8").split("\n").filter(Boolean)) {
+        try {
+            const v = JSON.parse(line);
+            if (v.kind !== "variable")
+                continue;
+            const key = `${v.file}:${v.line}:${v.varName}`;
+            obsMap.set(key, v);
+        }
+        catch { }
+    }
+    const vars = [...obsMap.values()];
+    // Filter by target file
+    let filtered = vars;
+    if (targetFile) {
+        const normalized = targetFile.replace(/^\.\//, "");
+        filtered = vars.filter(v => {
+            const relPath = path.relative(process.cwd(), v.file);
+            return relPath.includes(normalized) || v.file.includes(normalized);
+        });
+    }
+    if (filtered.length === 0) {
+        console.error(targetFile ? `No observations found for "${targetFile}".` : "No observations found.");
+        process.exit(1);
+    }
+    // Group by file
+    const byFile = new Map();
+    for (const v of filtered) {
+        if (!byFile.has(v.file))
+            byFile.set(v.file, []);
+        byFile.get(v.file).push(v);
+    }
+    for (const [absFile, fileVars] of byFile) {
+        let sourceLines = [];
+        let relPath = "";
+        // Handle notebook cell paths: __notebook__cell_N.py
+        const cellMatch = absFile.match(/__notebook__cell_(\d+)\.py$/);
+        if (cellMatch) {
+            // Try to find the notebook .ipynb in the same directory
+            const dir = path.dirname(absFile);
+            const cellIdx = parseInt(cellMatch[1]);
+            const ipynbFiles = fs.existsSync(dir)
+                ? fs.readdirSync(dir).filter(f => f.endsWith(".ipynb"))
+                : [];
+            let foundCell = false;
+            for (const nbFile of ipynbFiles) {
+                const nbPath = path.join(dir, nbFile);
+                try {
+                    const nb = JSON.parse(fs.readFileSync(nbPath, "utf-8"));
+                    const cells = nb.cells || [];
+                    // trickle's cellIdx is the Nth code cell execution (1-based).
+                    // Try direct index first, then count code cells.
+                    let cellSource;
+                    // Try: cellIdx maps to 0-based index in all cells
+                    if (cells[cellIdx - 1]?.cell_type === "code") {
+                        cellSource = cells[cellIdx - 1].source;
+                    }
+                    // Fallback: count code cells
+                    if (!cellSource) {
+                        let codeCount = 0;
+                        for (const c of cells) {
+                            if (c.cell_type === "code") {
+                                codeCount++;
+                                if (codeCount === cellIdx) {
+                                    cellSource = c.source;
+                                    break;
+                                }
+                            }
+                        }
+                    }
+                    if (!cellSource)
+                        continue;
+                    sourceLines = (Array.isArray(cellSource) ? cellSource.join("") : String(cellSource)).split("\n");
+                    relPath = `${path.relative(process.cwd(), nbPath)} [cell ${cellIdx}]`;
+                    foundCell = true;
+                    break;
+                }
+                catch {
+                    continue;
+                }
+            }
+            if (!foundCell) {
+                // Can't find source — output just the observations in a summary format
+                relPath = absFile.replace(/.*__notebook__/, "notebook ").replace(/\.py$/, "");
+                const maxLine = Math.max(...fileVars.map(v => v.line));
+                sourceLines = Array.from({ length: maxLine }, (_, i) => `# line ${i + 1}`);
+                // Place observations as standalone lines
+                const lineObs = new Map();
+                for (const v of fileVars) {
+                    if (!lineObs.has(v.line))
+                        lineObs.set(v.line, new Map());
+                    lineObs.get(v.line).set(v.varName, v);
+                }
+                console.log(`# ${relPath}`);
+                console.log("```python");
+                for (const [lineNo, obs] of [...lineObs.entries()].sort((a, b) => a[0] - b[0])) {
+                    for (const v of obs.values()) {
+                        const typeStr = typeToString(v.type);
+                        const scope = v.funcName ? ` (in ${v.funcName})` : "";
+                        if (opts.values && v.sample !== undefined) {
+                            console.log(`${v.varName}: ${typeStr} = ${formatSample(v.sample)}${scope}`);
+                        }
+                        else {
+                            console.log(`${v.varName}: ${typeStr}${scope}`);
+                        }
+                    }
+                }
+                console.log("```");
+                console.log("");
+                continue;
+            }
+        }
+        else {
+            if (!fs.existsSync(absFile))
+                continue;
+            sourceLines = fs.readFileSync(absFile, "utf-8").split("\n");
+            relPath = path.relative(process.cwd(), absFile);
+        }
+        // Build line → varName → observation map
+        const lineObs = new Map();
+        for (const v of fileVars) {
+            if (!lineObs.has(v.line))
+                lineObs.set(v.line, new Map());
+            lineObs.get(v.line).set(v.varName, v);
+        }
+        console.log(`# ${relPath}`);
+        console.log("```python");
+        for (let i = 0; i < sourceLines.length; i++) {
+            const lineNo = i + 1;
+            const src = sourceLines[i];
+            const obs = lineObs.get(lineNo);
+            if (!obs || obs.size === 0) {
+                console.log(src);
+                continue;
+            }
+            // Insert type hints inline after variable names
+            let annotated = src;
+            // Sort by position in line (rightmost first so indices don't shift)
+            const entries = [...obs.values()].sort((a, b) => {
+                const aIdx = src.indexOf(a.varName);
+                const bIdx = src.indexOf(b.varName);
+                return bIdx - aIdx; // rightmost first
+            });
+            for (const v of entries) {
+                const typeStr = typeToString(v.type);
+                // Skip if the type is just "unknown" or not useful
+                if (typeStr === "unknown")
+                    continue;
+                // Find variable in the line
+                const isAttr = v.varName.includes(".");
+                const pattern = isAttr
+                    ? new RegExp(v.varName.replace(/\./g, "\\."))
+                    : new RegExp(`\\b${v.varName.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}\\b`);
+                const match = pattern.exec(annotated);
+                if (!match)
+                    continue;
+                const varEnd = match.index + v.varName.length;
+                const afterVar = annotated.substring(varEnd).trimStart();
+                // Check this is an assignment/declaration context
+                const beforeVar = annotated.substring(0, match.index);
+                const isPython = absFile.endsWith(".py");
+                if (isPython) {
+                    const isAssignment = afterVar.startsWith("=") && !afterVar.startsWith("==");
+                    const isAnnotated = afterVar.startsWith(":");
+                    const isForVar = /\bfor\s+$/.test(beforeVar) || /\bfor\s+.*,\s*$/.test(beforeVar);
+                    const isWithAs = /\bas\s+$/.test(beforeVar);
+                    const isFuncParam = /\b(?:async\s+)?def\s+\w+\s*\(/.test(beforeVar) &&
+                        (afterVar.startsWith(",") || afterVar.startsWith(")") || afterVar.startsWith("=") || afterVar.startsWith(":"));
+                    const isBareAssign = /^\s*$/.test(beforeVar) || /,\s*$/.test(beforeVar);
+                    if (!isForVar && !isWithAs && !isFuncParam && !((isBareAssign) && (isAssignment || isAnnotated)))
+                        continue;
+                    if (isAnnotated && !isFuncParam)
+                        continue;
+                    if (isFuncParam && afterVar.startsWith(":"))
+                        continue;
+                }
+                // Build the hint string
+                let hint;
+                if (opts.values && v.sample !== undefined && v.sample !== null) {
+                    const sampleStr = formatSample(v.sample);
+                    hint = sampleStr ? `: ${typeStr} = ${sampleStr}` : `: ${typeStr}`;
+                }
+                else {
+                    hint = `: ${typeStr}`;
+                }
+                // Insert after variable name
+                annotated = annotated.substring(0, varEnd) + hint + annotated.substring(varEnd);
+            }
+            console.log(annotated);
+        }
+        console.log("```");
+        console.log("");
+    }
+}

package/dist/commands/run.js

@@ -409,8 +409,8 @@ async function executeSingleRun(instrumentedCommand, env, opts, singleFile, loca
     const localDir = env.TRICKLE_LOCAL_DIR || process.env.TRICKLE_LOCAL_DIR || path.join(process.cwd(), ".trickle");
     const jsonlPath = path.join(localDir, "observations.jsonl");
     const { generateLocalStubs, generateFromJsonl, readObservations } = await Promise.resolve().then(() => __importStar(require("../local-codegen")));
-    // Check if stub generation is enabled (TRICKLE_STUBS=0 disables .pyi/.d.ts files)
-    const stubsEnabled = (env.TRICKLE_STUBS || process.env.TRICKLE_STUBS || "1").toLowerCase() !== "0";
+    // Check if stub generation is enabled (opt-in: TRICKLE_STUBS=1 enables .pyi/.d.ts files)
+    const stubsEnabled = (env.TRICKLE_STUBS || process.env.TRICKLE_STUBS || "0").toLowerCase() !== "0";
     // Start live type generation — types update while the process runs
     let liveTypesStop = null;
     if (singleFile && stubsEnabled) {

package/dist/index.js

@@ -81,6 +81,7 @@ const mcp_server_1 = require("./commands/mcp-server");
 const rn_1 = require("./commands/rn");
 const next_1 = require("./commands/next");
 const python_1 = require("./commands/python");
+const hints_1 = require("./commands/hints");
 const program = new commander_1.Command();
 program
     .name("trickle")
@@ -533,6 +534,14 @@ program
     .action(async (opts) => {
     await (0, vars_1.varsCommand)(opts);
 });
+// trickle hints
+program
+    .command("hints [file]")
+    .description("Output source code with inline type hints from runtime observations (for AI agents)")
+    .option("--values", "Include sample values alongside types")
+    .action(async (file, opts) => {
+    await (0, hints_1.hintsCommand)(file, opts);
+});
 // trickle layers
 program
     .command("layers")

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "trickle-cli",
-  "version": "0.1.213",
+  "version": "0.1.215",
   "description": "Zero-code runtime observability for JS/Python + AI agent debugging. Traces LangChain, CrewAI, OpenAI, Anthropic, Gemini. Eval, security, compliance, cost tracking. Free, local-first.",
   "keywords": [
     "observability",

package/src/commands/hints.ts

@@ -0,0 +1,324 @@
+/**
+ * Output source code with inline type hints (like VSCode inlay hints).
+ *
+ * Reads .trickle/variables.jsonl and renders the source with type
+ * annotations inserted inline — suitable for AI agents that need
+ * to understand runtime types without running the code.
+ *
+ * Usage:
+ *   trickle hints src/app.py              # all hints for a file
+ *   trickle hints src/app.py --values     # include sample values
+ *   trickle hints                         # all observed files
+ */
+
+import * as fs from "fs";
+import * as path from "path";
+
+export interface HintsOptions {
+  values?: boolean;
+}
+
+interface TypeNode {
+  kind: string;
+  name?: string;
+  elements?: TypeNode[];
+  members?: TypeNode[];
+  element?: TypeNode;
+  properties?: Record<string, TypeNode>;
+  class_name?: string;
+}
+
+interface VarObservation {
+  kind: string;
+  varName: string;
+  line: number;
+  file: string;
+  module?: string;
+  cellIndex?: number;
+  type: TypeNode;
+  sample?: unknown;
+  funcName?: string;
+}
+
+function typeToString(node: TypeNode): string {
+  if (!node) return "unknown";
+  switch (node.kind) {
+    case "primitive": return node.name || "unknown";
+    case "object": {
+      if (!node.properties) return node.class_name || "object";
+      if (node.class_name === "Tensor" || node.class_name === "ndarray") {
+        const shape = node.properties["shape"]?.name;
+        const dtype = node.properties["dtype"]?.name;
+        const parts: string[] = [];
+        if (shape) parts.push(`shape=${shape}`);
+        if (dtype) parts.push(`dtype=${dtype}`);
+        return `${node.class_name}(${parts.join(", ")})`;
+      }
+      if (node.class_name === "DataFrame") {
+        const rows = node.properties["rows"]?.name;
+        const cols = node.properties["cols"]?.name;
+        const parts: string[] = [];
+        if (rows && cols) parts.push(`${rows}x${cols}`);
+        return `DataFrame(${parts.join(", ")})`;
+      }
+      if (node.class_name) {
+        const keys = Object.keys(node.properties).slice(0, 4);
+        const extra = Object.keys(node.properties).length > 4 ? `, +${Object.keys(node.properties).length - 4}` : "";
+        return `${node.class_name}(${keys.join(", ")}${extra})`;
+      }
+      const props = Object.entries(node.properties).slice(0, 5)
+        .map(([k, v]) => `${k}: ${typeToString(v)}`);
+      const extra = Object.keys(node.properties).length > 5 ? `, +${Object.keys(node.properties).length - 5}` : "";
+      return `{${props.join(", ")}${extra}}`;
+    }
+    case "array": {
+      const elem = node.element;
+      if (elem?.kind === "union") {
+        const members = elem.elements || elem.members;
+        if (members && members.length > 0) {
+          const names = new Set(members.map(m => m.class_name).filter(Boolean));
+          if (names.size === 1) return `${names.values().next().value}[]`;
+        }
+      }
+      return `${typeToString(elem || { kind: "primitive", name: "unknown" })}[]`;
+    }
+    case "tuple": return `[${(node.elements || []).map(typeToString).join(", ")}]`;
+    case "union": {
+      const members = node.elements || node.members;
+      if (!members) return "unknown";
+      const names = new Set(members.map(m => m.class_name).filter(Boolean));
+      if (names.size === 1) return names.values().next().value!;
+      return members.map(typeToString).join(" | ");
+    }
+    case "function": return "Function";
+    default: return node.kind;
+  }
+}
+
+function formatSample(sample: unknown): string {
+  if (sample === null || sample === undefined) return "";
+  if (typeof sample === "string") {
+    if (sample.length > 40) return `"${sample.substring(0, 37)}..."`;
+    return `"${sample}"`;
+  }
+  if (typeof sample === "number") {
+    return Number.isInteger(sample) ? String(sample) : sample.toFixed(4);
+  }
+  if (typeof sample === "boolean") return String(sample);
+  if (Array.isArray(sample)) return `[...${sample.length} items]`;
+  const s = String(sample);
+  return s.length > 40 ? s.substring(0, 37) + "..." : s;
+}
+
+export async function hintsCommand(
+  targetFile: string | undefined,
+  opts: HintsOptions,
+): Promise<void> {
+  const localDir = process.env.TRICKLE_LOCAL_DIR || path.join(process.cwd(), ".trickle");
+  const varsFile = path.join(localDir, "variables.jsonl");
+
+  if (!fs.existsSync(varsFile)) {
+    console.error("No trickle data found. Run your app with trickle first:");
+    console.error("  trickle run python app.py");
+    console.error("  trickle run node app.js");
+    process.exit(1);
+  }
+
+  // Load and deduplicate variable observations (last wins per file:line:varName)
+  const obsMap = new Map<string, VarObservation>();
+  for (const line of fs.readFileSync(varsFile, "utf-8").split("\n").filter(Boolean)) {
+    try {
+      const v = JSON.parse(line) as VarObservation;
+      if (v.kind !== "variable") continue;
+      const key = `${v.file}:${v.line}:${v.varName}`;
+      obsMap.set(key, v);
+    } catch {}
+  }
+  const vars = [...obsMap.values()];
+
+  // Filter by target file
+  let filtered = vars;
+  if (targetFile) {
+    const normalized = targetFile.replace(/^\.\//, "");
+    filtered = vars.filter(v => {
+      const relPath = path.relative(process.cwd(), v.file);
+      return relPath.includes(normalized) || v.file.includes(normalized);
+    });
+  }
+
+  if (filtered.length === 0) {
+    console.error(targetFile ? `No observations found for "${targetFile}".` : "No observations found.");
+    process.exit(1);
+  }
+
+  // Group by file
+  const byFile = new Map<string, VarObservation[]>();
+  for (const v of filtered) {
+    if (!byFile.has(v.file)) byFile.set(v.file, []);
+    byFile.get(v.file)!.push(v);
+  }
+
+  for (const [absFile, fileVars] of byFile) {
+    let sourceLines: string[] = [];
+    let relPath: string = "";
+
+    // Handle notebook cell paths: __notebook__cell_N.py
+    const cellMatch = absFile.match(/__notebook__cell_(\d+)\.py$/);
+    if (cellMatch) {
+      // Try to find the notebook .ipynb in the same directory
+      const dir = path.dirname(absFile);
+      const cellIdx = parseInt(cellMatch[1]);
+      const ipynbFiles = fs.existsSync(dir)
+        ? fs.readdirSync(dir).filter(f => f.endsWith(".ipynb"))
+        : [];
+      let foundCell = false;
+      for (const nbFile of ipynbFiles) {
+        const nbPath = path.join(dir, nbFile);
+        try {
+          const nb = JSON.parse(fs.readFileSync(nbPath, "utf-8"));
+          const cells = nb.cells || [];
+          // trickle's cellIdx is the Nth code cell execution (1-based).
+          // Try direct index first, then count code cells.
+          let cellSource: string[] | undefined;
+          // Try: cellIdx maps to 0-based index in all cells
+          if (cells[cellIdx - 1]?.cell_type === "code") {
+            cellSource = cells[cellIdx - 1].source;
+          }
+          // Fallback: count code cells
+          if (!cellSource) {
+            let codeCount = 0;
+            for (const c of cells) {
+              if (c.cell_type === "code") {
+                codeCount++;
+                if (codeCount === cellIdx) {
+                  cellSource = c.source;
+                  break;
+                }
+              }
+            }
+          }
+          if (!cellSource) continue;
+          sourceLines = (Array.isArray(cellSource) ? cellSource.join("") : String(cellSource)).split("\n");
+          relPath = `${path.relative(process.cwd(), nbPath)} [cell ${cellIdx}]`;
+          foundCell = true;
+          break;
+        } catch {
+          continue;
+        }
+      }
+      if (!foundCell) {
+        // Can't find source — output just the observations in a summary format
+        relPath = absFile.replace(/.*__notebook__/, "notebook ").replace(/\.py$/, "");
+        const maxLine = Math.max(...fileVars.map(v => v.line));
+        sourceLines = Array.from({ length: maxLine }, (_, i) => `# line ${i + 1}`);
+        // Place observations as standalone lines
+        const lineObs = new Map<number, Map<string, VarObservation>>();
+        for (const v of fileVars) {
+          if (!lineObs.has(v.line)) lineObs.set(v.line, new Map());
+          lineObs.get(v.line)!.set(v.varName, v);
+        }
+        console.log(`# ${relPath}`);
+        console.log("```python");
+        for (const [lineNo, obs] of [...lineObs.entries()].sort((a, b) => a[0] - b[0])) {
+          for (const v of obs.values()) {
+            const typeStr = typeToString(v.type);
+            const scope = v.funcName ? ` (in ${v.funcName})` : "";
+            if (opts.values && v.sample !== undefined) {
+              console.log(`${v.varName}: ${typeStr} = ${formatSample(v.sample)}${scope}`);
+            } else {
+              console.log(`${v.varName}: ${typeStr}${scope}`);
+            }
+          }
+        }
+        console.log("```");
+        console.log("");
+        continue;
+      }
+    } else {
+      if (!fs.existsSync(absFile)) continue;
+      sourceLines = fs.readFileSync(absFile, "utf-8").split("\n");
+      relPath = path.relative(process.cwd(), absFile);
+    }
+
+    // Build line → varName → observation map
+    const lineObs = new Map<number, Map<string, VarObservation>>();
+    for (const v of fileVars) {
+      if (!lineObs.has(v.line)) lineObs.set(v.line, new Map());
+      lineObs.get(v.line)!.set(v.varName, v);
+    }
+
+    console.log(`# ${relPath}`);
+    console.log("```python");
+
+    for (let i = 0; i < sourceLines.length; i++) {
+      const lineNo = i + 1;
+      const src = sourceLines[i];
+      const obs = lineObs.get(lineNo);
+
+      if (!obs || obs.size === 0) {
+        console.log(src);
+        continue;
+      }
+
+      // Insert type hints inline after variable names
+      let annotated = src;
+      // Sort by position in line (rightmost first so indices don't shift)
+      const entries = [...obs.values()].sort((a, b) => {
+        const aIdx = src.indexOf(a.varName);
+        const bIdx = src.indexOf(b.varName);
+        return bIdx - aIdx; // rightmost first
+      });
+
+      for (const v of entries) {
+        const typeStr = typeToString(v.type);
+        // Skip if the type is just "unknown" or not useful
+        if (typeStr === "unknown") continue;
+
+        // Find variable in the line
+        const isAttr = v.varName.includes(".");
+        const pattern = isAttr
+          ? new RegExp(v.varName.replace(/\./g, "\\."))
+          : new RegExp(`\\b${v.varName.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}\\b`);
+        const match = pattern.exec(annotated);
+        if (!match) continue;
+
+        const varEnd = match.index + v.varName.length;
+        const afterVar = annotated.substring(varEnd).trimStart();
+
+        // Check this is an assignment/declaration context
+        const beforeVar = annotated.substring(0, match.index);
+        const isPython = absFile.endsWith(".py");
+        if (isPython) {
+          const isAssignment = afterVar.startsWith("=") && !afterVar.startsWith("==");
+          const isAnnotated = afterVar.startsWith(":");
+          const isForVar = /\bfor\s+$/.test(beforeVar) || /\bfor\s+.*,\s*$/.test(beforeVar);
+          const isWithAs = /\bas\s+$/.test(beforeVar);
+          const isFuncParam = /\b(?:async\s+)?def\s+\w+\s*\(/.test(beforeVar) &&
+            (afterVar.startsWith(",") || afterVar.startsWith(")") || afterVar.startsWith("=") || afterVar.startsWith(":"));
+          const isBareAssign = /^\s*$/.test(beforeVar) || /,\s*$/.test(beforeVar);
+
+          if (!isForVar && !isWithAs && !isFuncParam && !((isBareAssign) && (isAssignment || isAnnotated))) continue;
+          if (isAnnotated && !isFuncParam) continue;
+          if (isFuncParam && afterVar.startsWith(":")) continue;
+        }
+
+        // Build the hint string
+        let hint: string;
+        if (opts.values && v.sample !== undefined && v.sample !== null) {
+          const sampleStr = formatSample(v.sample);
+          hint = sampleStr ? `: ${typeStr} = ${sampleStr}` : `: ${typeStr}`;
+        } else {
+          hint = `: ${typeStr}`;
+        }
+
+        // Insert after variable name
+        annotated = annotated.substring(0, varEnd) + hint + annotated.substring(varEnd);
+      }
+
+      console.log(annotated);
+    }
+
+    console.log("```");
+    console.log("");
+  }
+}

package/src/commands/run.ts

@@ -459,8 +459,8 @@ async function executeSingleRun(
 
   const { generateLocalStubs, generateFromJsonl, readObservations } = await import("../local-codegen");
 
-  // Check if stub generation is enabled (TRICKLE_STUBS=0 disables .pyi/.d.ts files)
-  const stubsEnabled = (env.TRICKLE_STUBS || process.env.TRICKLE_STUBS || "1").toLowerCase() !== "0";
+  // Check if stub generation is enabled (opt-in: TRICKLE_STUBS=1 enables .pyi/.d.ts files)
+  const stubsEnabled = (env.TRICKLE_STUBS || process.env.TRICKLE_STUBS || "0").toLowerCase() !== "0";
 
   // Start live type generation — types update while the process runs
   let liveTypesStop: (() => void) | null = null;

package/src/index.ts

@@ -44,6 +44,7 @@ import { mcpServerCommand } from "./commands/mcp-server";
 import { rnCommand } from "./commands/rn";
 import { nextCommand } from "./commands/next";
 import { pythonCommand } from "./commands/python";
+import { hintsCommand } from "./commands/hints";
 
 const program = new Command();
 
@@ -534,6 +535,15 @@ program
     await varsCommand(opts);
   });
 
+// trickle hints
+program
+  .command("hints [file]")
+  .description("Output source code with inline type hints from runtime observations (for AI agents)")
+  .option("--values", "Include sample values alongside types")
+  .action(async (file: string | undefined, opts: { values?: boolean }) => {
+    await hintsCommand(file, opts);
+  });
+
 // trickle layers
 program
   .command("layers")