tinker-agent 1.7.0 → 1.8.0

package/CHANGELOG.md

@@ -5,6 +5,18 @@ All notable user-facing changes to Tinker are documented here. The project follo
 
 ## [Unreleased]
 
+## [1.8.0] - 2026-08-02
+
+### Added
+
+- Add `tinker update` for manually upgrading a direct npm global installation to
+  the latest stable release from the official npm registry.
+
+### Fixed
+
+- Wait for completed background-task output to finish flushing before returning
+  it through `TaskOutput`.
+
 ## [1.7.0] - 2026-08-01
 
 ### Added
@@ -149,7 +161,8 @@ All notable user-facing changes to Tinker are documented here. The project follo
 - First formal npm release under the `tinker-agent` package name with the `tinker`
   executable.
 
-[Unreleased]: https://github.com/ishowshao/tinker/compare/v1.7.0...HEAD
+[Unreleased]: https://github.com/ishowshao/tinker/compare/v1.8.0...HEAD
+[1.8.0]: https://github.com/ishowshao/tinker/releases/tag/v1.8.0
 [1.7.0]: https://github.com/ishowshao/tinker/releases/tag/v1.7.0
 [1.6.0]: https://github.com/ishowshao/tinker/releases/tag/v1.6.0
 [1.5.1]: https://github.com/ishowshao/tinker/releases/tag/v1.5.1

package/README.md

@@ -80,11 +80,17 @@ The installed package exposes this public CLI:
 | `tinker run [--profile <profile-name>] [--yolo] <prompt>` | Submit one shell-quoted prompt argument. |
 | `tinker run [--profile <profile-name>] [--yolo] --stdin` | Read the prompt from standard input until EOF. |
 | `tinker run [--profile <profile-name>] [--yolo] --file <path>` | Read the prompt from a UTF-8 text file. |
+| `tinker update` | Update the global npm installation from the official npm registry. |
 | `tinker --help` | Show top-level CLI help. |
 | `tinker help run` | Show one-shot command help. |
+| `tinker help update` | Show update command help. |
 | `tinker --version` | Print the installed package version. |
 <!-- END GENERATED: PUBLIC CLI COMMANDS -->
 
+`tinker update` is available only to direct npm global installations. It checks
+the `latest` stable version on the official npm registry, updates that same global
+prefix, and exits without loading model configuration or starting a session.
+
 Repository development commands are separate from the installed CLI:
 
 ```bash

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tinker-agent",
-  "version": "1.7.0",
+  "version": "1.8.0",
   "description": "A personal coding agent with an interactive TUI and one-shot CLI.",
   "license": "Apache-2.0",
   "type": "module",
@@ -59,6 +59,7 @@
     "chrome:diagnose": "bun packages/tinker-chrome/src/cli.ts diagnose",
     "chrome:install-host": "bun packages/tinker-chrome/src/cli.ts install-host",
     "chrome:mcp": "bun packages/tinker-chrome/src/cli.ts mcp",
+    "chrome:smoke": "bun packages/tinker-chrome/scripts/live-smoke.ts",
     "docs:generate": "bun scripts/render-public-contract-docs.ts --write",
     "docs:check": "bun scripts/render-public-contract-docs.ts --check",
     "tinker": "bun src/cli/index.ts",
@@ -93,6 +94,7 @@
     "markdansi": "0.3.2",
     "marked": "^18.0.5",
     "openai": "^7.1.0",
+    "puppeteer-core": "25.4.0",
     "react": "^19.2.7",
     "sharp": "^0.35.3",
     "shiki": "^4.3.1",

package/src/agent/runtime-session.ts

@@ -635,6 +635,7 @@ class DefaultRuntimeSession implements RuntimeSession {
       if (mcpConfig !== undefined) {
         session.mcpManager = await dependencies.createMcpManager({
           config: mcpConfig,
+          workspaceRoot: input.workspaceRoot,
           runtimeSession: session.context,
           timeoutMs: input.toolingConfig?.mcpTimeoutMs,
           maxObservationChars: input.toolingConfig?.mcpMaxObservationChars,

package/src/cli/command-line.ts

@@ -5,6 +5,7 @@ import { CliUsageError, type CliCommandScope } from "./output";
 
 export type CliCommand =
   | { readonly type: "tui"; readonly profileName?: string }
+  | { readonly type: "update" }
   | {
       readonly type: "run";
       readonly profileName?: string;
@@ -129,6 +130,17 @@ export async function parseCommandLine(
       },
     );
 
+  program
+    .command(contract.update.command)
+    .description(contract.update.description)
+    .showHelpAfterError('Run "tinker update --help" for usage.')
+    .showSuggestionAfterError(false)
+    .allowExcessArguments(false)
+    .exitOverride()
+    .action(() => {
+      selectedCommand = Object.freeze({ type: "update" });
+    });
+
   try {
     await program.parseAsync([...args], { from: "user" });
   } catch (error) {
@@ -154,6 +166,12 @@ export async function parseCommandLine(
       "run",
     );
   }
+  if (selectedCommand.type === "update" && topLevelProfile !== undefined) {
+    throw new CliUsageError(
+      "The top-level --profile option only applies to the TUI.",
+      "update",
+    );
+  }
   return Object.freeze({ type: "command", command: selectedCommand });
 }
 
@@ -173,7 +191,7 @@ function preflightArgv(args: readonly string[]): CliCommandScope {
 
     if (
       (!rootBlocked && scope === "root" && isRootTerminalOption(token)) ||
-      (scope === "run" && isRunTerminalOption(token))
+      (scope !== "root" && isSubcommandTerminalOption(token))
     ) {
       return scope;
     }
@@ -202,6 +220,10 @@ function preflightArgv(args: readonly string[]): CliCommandScope {
         scope = "run";
         continue;
       }
+      if (token === "update") {
+        scope = "update";
+        continue;
+      }
       if (token === "help") {
         return "root";
       }
@@ -290,7 +312,7 @@ function isRootTerminalOption(token: string): boolean {
   );
 }
 
-function isRunTerminalOption(token: string): boolean {
+function isSubcommandTerminalOption(token: string): boolean {
   return token === "--help" || token === "-h";
 }
 

package/src/cli/main.ts

@@ -67,6 +67,14 @@ type OneShotRunner = {
   ) => Promise<number>;
 };
 
+type UpdateRunner = {
+  readonly runUpdate: (options: {
+    readonly metadata: PackageMetadata;
+    readonly stdout: CliOutputWriter;
+    readonly env: NodeJS.ProcessEnv;
+  }) => Promise<number>;
+};
+
 export type MainDependencies = {
   readonly loadPackageMetadata: () => Promise<PackageMetadata>;
   readonly parseCommandLine: (
@@ -81,6 +89,7 @@ export type MainDependencies = {
   ) => Promise<ResolvedPrompt>;
   readonly loadTuiRunner: () => Promise<TuiRunner>;
   readonly loadOneShotRunner: () => Promise<OneShotRunner>;
+  readonly loadUpdateRunner: () => Promise<UpdateRunner>;
 };
 
 const DEFAULT_DEPENDENCIES: MainDependencies = {
@@ -91,6 +100,7 @@ const DEFAULT_DEPENDENCIES: MainDependencies = {
   resolvePromptSource,
   loadTuiRunner: () => import("./tui-runner"),
   loadOneShotRunner: () => import("./run-runner"),
+  loadUpdateRunner: () => import("./update-runner"),
 };
 
 export async function main(
@@ -133,6 +143,22 @@ export async function main(
       return finish(0);
     }
 
+    if (parsed.command.type === "update") {
+      try {
+        const runner = await dependencies.loadUpdateRunner();
+        return finish(
+          await runner.runUpdate({
+            metadata,
+            stdout: input.stdout,
+            env,
+          }),
+        );
+      } catch (error) {
+        await writeCliOutput(input.stderr, renderCliFailure("Update failed", error));
+        return finish(1);
+      }
+    }
+
     let configBoundary: ConfigBoundary;
     let publicConfig: ResolvedPublicConfig;
     let runnerConfig: RunnerConfig;

package/src/cli/output.ts

@@ -4,7 +4,7 @@ const TRUNCATION_MARKER = "...[truncated]";
 const ESCAPE = String.fromCharCode(27);
 const ANSI_CSI_PATTERN = new RegExp(`${ESCAPE}\\[[0-?]*[ -/]*[@-~]`, "g");
 
-export type CliCommandScope = "root" | "run";
+export type CliCommandScope = "root" | "run" | "update";
 
 export interface CliOutputWriter {
   write(chunk: string): boolean | void;
@@ -24,9 +24,9 @@ export class CliUsageError extends Error {
 
 export function renderUsageError(error: CliUsageError): string {
   const hint =
-    error.scope === "run"
-      ? 'Run "tinker run --help" for usage.'
-      : 'Run "tinker --help" for usage.';
+    error.scope === "root"
+      ? 'Run "tinker --help" for usage.'
+      : `Run "tinker ${error.scope} --help" for usage.`;
   return `error: ${sanitizeDiagnosticDetail(error.message)}\n${hint}\n`;
 }
 

package/src/cli/public-cli-contract.ts

@@ -68,6 +68,10 @@ export const PUBLIC_CLI_CONTRACT = Object.freeze({
     helpAfter:
       "Use exactly one prompt source. For complex or sensitive prompts, prefer --stdin or --file.",
   }),
+  update: Object.freeze({
+    command: "update",
+    description: "Update the global npm installation from the official npm registry.",
+  }),
 });
 
 export type PublicCliContract = typeof PUBLIC_CLI_CONTRACT;

package/src/cli/update-runner.ts

@@ -0,0 +1,308 @@
+import { spawn } from "node:child_process";
+import { lstat, realpath } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { loadPackageMetadata, type PackageMetadata } from "./package-metadata";
+import { writeCliOutput, type CliOutputWriter } from "./output";
+
+export const OFFICIAL_NPM_REGISTRY = "https://registry.npmjs.org/";
+
+const OFFICIAL_PACKAGE_NAME = "tinker-agent";
+const MAX_NPM_OUTPUT_CHARACTERS = 32_768;
+
+type NpmCommandResult = {
+  readonly exitCode: number | null;
+  readonly signal: NodeJS.Signals | null;
+  readonly stdout: string;
+  readonly stderr: string;
+};
+
+type NpmCommandInput = {
+  readonly args: readonly string[];
+  readonly cwd: string;
+  readonly env: NodeJS.ProcessEnv;
+};
+
+export type UpdateRunnerDependencies = {
+  readonly packageRoot: string;
+  readonly npmCwd: string;
+  readonly runNpm: (input: NpmCommandInput) => Promise<NpmCommandResult>;
+  readonly canonicalizePath: (filePath: string) => Promise<string>;
+  readonly isSymbolicLink: (filePath: string) => Promise<boolean>;
+  readonly readPackageMetadata: (packageJsonPath: string) => Promise<PackageMetadata>;
+  readonly compareVersions: (left: string, right: string) => -1 | 0 | 1;
+};
+
+type UpdateInput = {
+  readonly metadata: PackageMetadata;
+  readonly stdout: CliOutputWriter;
+  readonly env: NodeJS.ProcessEnv;
+};
+
+const DEFAULT_DEPENDENCIES: UpdateRunnerDependencies = {
+  packageRoot: path.resolve(fileURLToPath(new URL("../../", import.meta.url))),
+  npmCwd: tmpdir(),
+  runNpm,
+  canonicalizePath: realpath,
+  isSymbolicLink: async (filePath) => (await lstat(filePath)).isSymbolicLink(),
+  readPackageMetadata: (packageJsonPath) =>
+    loadPackageMetadata(pathToFileURL(packageJsonPath)),
+  compareVersions: (left, right) => Bun.semver.order(left, right),
+};
+
+export async function runUpdate(
+  input: UpdateInput,
+  injected: Partial<UpdateRunnerDependencies> = {},
+): Promise<number> {
+  const dependencies = { ...DEFAULT_DEPENDENCIES, ...injected };
+  if (input.metadata.name !== OFFICIAL_PACKAGE_NAME) {
+    throw new Error("The installed package is not tinker-agent.");
+  }
+
+  await writeCliOutput(input.stdout, `Current version: ${input.metadata.version}\n`);
+  await writeCliOutput(
+    input.stdout,
+    "Checking npm official registry for the latest version...\n",
+  );
+
+  const globalRoot = await readGlobalPath(
+    dependencies,
+    input.env,
+    ["root", "--global"],
+    "npm global package root",
+  );
+  const globalPrefix = await readGlobalPath(
+    dependencies,
+    input.env,
+    ["prefix", "--global"],
+    "npm global prefix",
+  );
+  const installedRoot = path.join(globalRoot, input.metadata.name);
+  await assertGlobalInstallation(dependencies, installedRoot);
+
+  const latestResult = await runNpmChecked(
+    dependencies,
+    {
+      args: [
+        "view",
+        `${input.metadata.name}@latest`,
+        "version",
+        "--json",
+        "--registry",
+        OFFICIAL_NPM_REGISTRY,
+        "--prefer-online",
+      ],
+      cwd: dependencies.npmCwd,
+      env: input.env,
+    },
+    "Could not query the npm official registry",
+  );
+  const latestVersion = parseLatestVersion(latestResult.stdout);
+  const order = compareVersions(dependencies, input.metadata.version, latestVersion);
+
+  if (order === 0) {
+    await writeCliOutput(
+      input.stdout,
+      `Already up to date: ${input.metadata.version}\n`,
+    );
+    return 0;
+  }
+  if (order > 0) {
+    await writeCliOutput(
+      input.stdout,
+      `Installed version ${input.metadata.version} is newer than npm latest ${latestVersion}; no changes made.\n`,
+    );
+    return 0;
+  }
+
+  await writeCliOutput(input.stdout, `Updating to ${latestVersion}...\n`);
+  await runNpmChecked(
+    dependencies,
+    {
+      args: [
+        "install",
+        "--global",
+        "--prefix",
+        globalPrefix,
+        `${input.metadata.name}@${latestVersion}`,
+        "--registry",
+        OFFICIAL_NPM_REGISTRY,
+        "--prefer-online",
+        "--no-audit",
+        "--no-fund",
+        "--loglevel",
+        "error",
+      ],
+      cwd: dependencies.npmCwd,
+      env: input.env,
+    },
+    `npm could not install ${input.metadata.name}@${latestVersion}`,
+  );
+
+  let installedMetadata: PackageMetadata;
+  try {
+    installedMetadata = await dependencies.readPackageMetadata(
+      path.join(installedRoot, "package.json"),
+    );
+  } catch {
+    throw new Error("The updated package metadata could not be verified.");
+  }
+  if (
+    installedMetadata.name !== input.metadata.name ||
+    installedMetadata.version !== latestVersion
+  ) {
+    throw new Error(
+      `npm completed, but the active global installation is not version ${latestVersion}.`,
+    );
+  }
+
+  await writeCliOutput(
+    input.stdout,
+    `Successfully updated from ${input.metadata.version} to version ${latestVersion}\n`,
+  );
+  return 0;
+}
+
+async function readGlobalPath(
+  dependencies: UpdateRunnerDependencies,
+  env: NodeJS.ProcessEnv,
+  args: readonly string[],
+  label: string,
+): Promise<string> {
+  const result = await runNpmChecked(
+    dependencies,
+    { args, cwd: dependencies.npmCwd, env },
+    `Could not resolve the ${label}`,
+  );
+  const value = result.stdout.trim();
+  if (value === "" || !path.isAbsolute(value)) {
+    throw new Error(`npm returned an invalid ${label}.`);
+  }
+  return value;
+}
+
+async function assertGlobalInstallation(
+  dependencies: UpdateRunnerDependencies,
+  installedRoot: string,
+): Promise<void> {
+  try {
+    const [packageRoot, expectedRoot, linked] = await Promise.all([
+      dependencies.canonicalizePath(dependencies.packageRoot),
+      dependencies.canonicalizePath(installedRoot),
+      dependencies.isSymbolicLink(installedRoot),
+    ]);
+    if (linked || packageRoot !== expectedRoot) {
+      throw new Error("not a direct global installation");
+    }
+  } catch {
+    throw new Error(
+      "This Tinker installation is not managed by the active npm global prefix.",
+    );
+  }
+}
+
+function parseLatestVersion(stdout: string): string {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(stdout);
+  } catch {
+    throw new Error("npm returned invalid update metadata.");
+  }
+  if (typeof parsed !== "string" || parsed.trim() === "") {
+    throw new Error("npm returned invalid update metadata.");
+  }
+  return parsed.trim();
+}
+
+function compareVersions(
+  dependencies: UpdateRunnerDependencies,
+  currentVersion: string,
+  latestVersion: string,
+): -1 | 0 | 1 {
+  try {
+    return dependencies.compareVersions(currentVersion, latestVersion);
+  } catch {
+    throw new Error("Tinker or npm returned an invalid semantic version.");
+  }
+}
+
+async function runNpmChecked(
+  dependencies: UpdateRunnerDependencies,
+  input: NpmCommandInput,
+  failureMessage: string,
+): Promise<NpmCommandResult> {
+  const result = await dependencies.runNpm(input);
+  if (result.exitCode === 0) {
+    return result;
+  }
+  const diagnostic = result.stderr.trim() || result.stdout.trim();
+  const status =
+    result.signal === null
+      ? `npm exited with code ${String(result.exitCode)}`
+      : `npm exited after ${result.signal}`;
+  throw new Error(
+    diagnostic === ""
+      ? `${failureMessage}: ${status}.`
+      : `${failureMessage}: ${diagnostic}`,
+  );
+}
+
+function runNpm(input: NpmCommandInput): Promise<NpmCommandResult> {
+  return new Promise((resolve, reject) => {
+    let child;
+    try {
+      child = spawn("npm", [...input.args], {
+        cwd: input.cwd,
+        env: {
+          ...input.env,
+          NPM_CONFIG_UPDATE_NOTIFIER: "false",
+        },
+        stdio: ["ignore", "pipe", "pipe"],
+      });
+    } catch {
+      reject(new Error("npm could not be started."));
+      return;
+    }
+
+    let stdout = "";
+    let stderr = "";
+    let settled = false;
+    child.stdout.setEncoding("utf8");
+    child.stderr.setEncoding("utf8");
+    child.stdout.on("data", (chunk: string) => {
+      stdout = appendBounded(stdout, chunk);
+    });
+    child.stderr.on("data", (chunk: string) => {
+      stderr = appendBounded(stderr, chunk);
+    });
+    child.once("error", (error) => {
+      if (settled) {
+        return;
+      }
+      settled = true;
+      const code = (error as NodeJS.ErrnoException).code;
+      reject(
+        new Error(
+          code === "ENOENT"
+            ? "npm was not found on PATH."
+            : "npm could not be started.",
+        ),
+      );
+    });
+    child.once("close", (exitCode, signal) => {
+      if (settled) {
+        return;
+      }
+      settled = true;
+      resolve({ exitCode, signal, stdout, stderr });
+    });
+  });
+}
+
+function appendBounded(current: string, chunk: string): string {
+  if (current.length >= MAX_NPM_OUTPUT_CHARACTERS) {
+    return current;
+  }
+  return (current + chunk).slice(0, MAX_NPM_OUTPUT_CHARACTERS);
+}

package/src/mcp/mcp-manager.ts

@@ -1,15 +1,24 @@
 import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import process from "node:process";
+import { pathToFileURL } from "node:url";
 import {
   StdioClientTransport,
   getDefaultEnvironment,
 } from "@modelcontextprotocol/sdk/client/stdio.js";
 import type { RuntimeSessionContext } from "../agent/runtime-session";
+import { ListRootsRequestSchema } from "@modelcontextprotocol/sdk/types.js";
 import type { ToolExecutor } from "../tools/types";
 import type { McpConfig, McpServerConfig } from "./mcp-config";
 import { createMcpToolExecutor } from "./mcp-tool-executor";
 
 const STDERR_TAIL_MAX_CHARS = 2_000;
 
+function temporaryDirectoryEnvironment(): Record<string, string> {
+  return process.platform === "win32" ? { TEMP: tmpdir() } : { TMPDIR: tmpdir() };
+}
+
 export type McpClientConnection = {
   client: Client;
   close(): Promise<void>;
@@ -18,6 +27,7 @@ export type McpClientConnection = {
 export type McpClientFactory = (
   serverName: string,
   serverConfig: McpServerConfig,
+  workspaceRoot: string,
 ) => Promise<McpClientConnection>;
 
 export type McpManager = {
@@ -37,6 +47,7 @@ export type McpServerInventory = {
 
 export type CreateMcpManagerOptions = {
   config: McpConfig;
+  workspaceRoot: string;
   runtimeSession: RuntimeSessionContext;
   clientFactory?: McpClientFactory;
   timeoutMs?: number;
@@ -70,7 +81,11 @@ export async function createMcpManager(
       let tools;
 
       try {
-        connection = await clientFactory(serverName, serverConfig);
+        connection = await clientFactory(
+          serverName,
+          serverConfig,
+          options.workspaceRoot,
+        );
       } catch (error) {
         await options.runtimeSession.append({
           type: "mcp.server.failed",
@@ -227,11 +242,16 @@ async function closeConnections(
 async function stdioClientFactory(
   serverName: string,
   serverConfig: McpServerConfig,
+  workspaceRoot: string,
 ): Promise<McpClientConnection> {
   const transport = new StdioClientTransport({
     command: serverConfig.command,
     args: serverConfig.args,
-    env: { ...getDefaultEnvironment(), ...serverConfig.env },
+    env: {
+      ...getDefaultEnvironment(),
+      ...temporaryDirectoryEnvironment(),
+      ...serverConfig.env,
+    },
     cwd: serverConfig.cwd,
     stderr: "pipe",
   });
@@ -241,7 +261,18 @@ async function stdioClientFactory(
     stderrTail = (stderrTail + chunk.toString("utf8")).slice(-STDERR_TAIL_MAX_CHARS);
   });
 
-  const client = new Client({ name: "tinker", version: "0.1.0" });
+  const client = new Client(
+    { name: "tinker", version: "0.1.0" },
+    { capabilities: { roots: { listChanged: false } } },
+  );
+  client.setRequestHandler(ListRootsRequestSchema, () => ({
+    roots: [
+      {
+        uri: pathToFileURL(workspaceRoot).href,
+        name: path.basename(workspaceRoot),
+      },
+    ],
+  }));
 
   try {
     await client.connect(transport);

package/src/tools/bash-task.ts

@@ -264,11 +264,7 @@ export class ShellTaskManager {
     }
 
     this.synchronizeTerminalState(task);
-    if (
-      task.mode === "pty" &&
-      isTerminalStatus(task.status) &&
-      task.finalScreen === undefined
-    ) {
+    if (isTerminalStatus(task.status)) {
       await task.completion;
     } else {
       await task.terminalScreen?.flush();