tinker-agent 1.3.0 → 1.5.0

package/CHANGELOG.md

@@ -5,6 +5,42 @@ All notable user-facing changes to Tinker are documented here. The project follo
 
 ## [Unreleased]
 
+## [1.5.0] - 2026-07-27
+
+### Added
+
+- Add optional global Memory for the interactive TUI. When configured, Tinker
+  extracts durable facts from completed turns, stores them locally, and exposes
+  relevant memories to the agent through `MemorySearch`.
+- Add a read-only `/memory` browser for reviewing the memories stored in the
+  current global Memory database.
+- Show live elapsed time in the TUI footer while a turn is running.
+
+### Changed
+
+- Compact and retire context toward 30% input utilization instead of 60%, leaving
+  more headroom for continued work after automatic or manual maintenance.
+
+### Fixed
+
+- Let the Tinker Chrome MCP server exit promptly when its client closes stdin,
+  avoiding the shutdown timeout during ordinary CLI exit.
+
+## [1.4.0] - 2026-07-24
+
+### Added
+
+- Add stable `tinker --help`, `tinker --version`, and `tinker help run` command
+  surfaces with explicit usage errors and exit codes.
+- Let one-shot runs read an exact Prompt from explicit stdin or a UTF-8 text file,
+  with bounded input and strict encoding validation.
+
+### Changed
+
+- Require `tinker run` to receive exactly one shell-quoted Prompt argument,
+  `--stdin`, or `--file <path>`. The former unquoted variadic form is no longer
+  joined automatically; quote a short Prompt or use stdin/file input instead.
+
 ## [1.3.0] - 2026-07-22
 
 ### Added
@@ -48,7 +84,9 @@ 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.3.0...HEAD
+[Unreleased]: https://github.com/ishowshao/tinker/compare/v1.5.0...HEAD
+[1.5.0]: https://github.com/ishowshao/tinker/releases/tag/v1.5.0
+[1.4.0]: https://github.com/ishowshao/tinker/releases/tag/v1.4.0
 [1.3.0]: https://github.com/ishowshao/tinker/releases/tag/v1.3.0
 [1.2.1]: https://github.com/ishowshao/tinker/releases/tag/v1.2.1
 [1.2.0]: https://github.com/ishowshao/tinker/releases/tag/v1.2.0

package/README.md

@@ -29,7 +29,9 @@ Built with [Bun](https://bun.sh) + TypeScript ESM, powered by [Ink](https://gith
   context revisions, Recall-addressable cold state, and qualified prefix retirement
   keep long-running sessions recoverable without pretending the model has infinite
   tokens. See the [technical design](docs/infinite-context-technical-design-a.md).
-- **Choice of models**: Supports any OpenAI-compatible API (defaults to DeepSeek). Configurable via environment variables.
+- **Choice of models**: Uses an OpenAI-compatible Chat Completions transport with
+  explicit model and context limits. Actual provider support must be established
+  by a qualification matrix; transport compatibility alone is not a guarantee.
 
 ## Quick Start
 
@@ -41,31 +43,65 @@ tinker
 
 # Run a one-shot prompt
 tinker run "explain the project structure"
+
+# Inspect the installed command surface
+tinker --help
+tinker --version
 ```
 
 The npm package includes its own Bun runtime. To run Tinker from a source checkout,
-install Bun 1.3 or later, then use `bun install` followed by `bun run tinker`.
-
-### Slash Commands
-
-- `/view <path>` — Open a readable UTF-8 text file in a full-window viewer. Relative
-  paths must remain inside the workspace; absolute paths may point outside it. Use
-  the keyboard or mouse wheel to scroll and press `Esc` to close the viewer.
-- `/copy` — Copy the current session's last completed assistant response to the
-  system clipboard as raw Markdown.
-- `/status` — Show session and context details.
-- `/skills` — Show available skills, their scope and active state, plus user skills
-  shadowed by a project skill.
-- `/compact` — Deterministically compact eligible historical tool output while the
-  session is idle.
-- `/compact retire` — Retire a complete cold history prefix from the active request;
-  the original history remains available through `Recall`.
-- `/model [profile-name]` — Choose a model profile for a new session.
-- `/resume [session-id]` — Choose or directly resume a stored session.
-- `/session delete <session-id> --confirm` — Delete a stored session.
-- `/quit` — Exit the TUI.
-
-### Agent Skills
+install Bun 1.3.14 or later, then use `bun install` followed by `bun run tinker`.
+
+`run` accepts exactly one Prompt source: one shell-quoted argument, explicit stdin,
+or a UTF-8 text file. Use stdin for multiline code, private patches, or Prompt text
+containing secrets so it does not become a command-line argument:
+
+```bash
+printf '%s\n' 'Review `$HOME`, *.ts, and "quotes" literally.' | tinker run --stdin
+tinker run --file prompts/review.md
+```
+
+Tinker does not reconstruct shell expansions or join multiple positional arguments.
+Use `tinker run "one quoted prompt"`; the former unquoted variadic form now fails
+with a usage error. File paths are resolved from the current directory and may point
+outside the configured workspace. You are responsible for Prompt-file permissions
+and cleanup.
+
+## Commands
+
+The installed package exposes this public CLI:
+
+<!-- BEGIN GENERATED: PUBLIC CLI COMMANDS -->
+| Command | Description |
+| --- | --- |
+| `tinker` | Start the interactive terminal interface. |
+| `tinker --profile <profile-name>` | Start the TUI with a selected model profile. |
+| `tinker run [--profile <profile-name>] <prompt>` | Submit one shell-quoted prompt argument. |
+| `tinker run [--profile <profile-name>] --stdin` | Read the prompt from standard input until EOF. |
+| `tinker run [--profile <profile-name>] --file <path>` | Read the prompt from a UTF-8 text file. |
+| `tinker --help` | Show top-level CLI help. |
+| `tinker help run` | Show one-shot command help. |
+| `tinker --version` | Print the installed package version. |
+<!-- END GENERATED: PUBLIC CLI COMMANDS -->
+
+Repository development commands are separate from the installed CLI:
+
+```bash
+bun install              # Install dependencies
+bun run tinker           # Start the interactive TUI
+bun test                 # Run test suite
+bun run typecheck        # TypeScript type checking (tsc --noEmit)
+bun run lint             # ESLint (zero warnings required)
+bun run format           # Biome code formatting
+bun run check            # Full repository quality gate
+```
+
+`bun run check` runs type checking, formatting verification, linting, the README
+contract check, the full test suite, and the benchmark smoke check. Documentation
+checking is read-only; use `bun run docs:generate` explicitly after changing a
+public declaration.
+
+## Agent Skills
 
 Tinker scans `<workspace>/.agents/skills/` and `~/.agents/skills/` once when a new
 or resumed runtime starts. Each direct child skill must contain a strictly valid
@@ -87,61 +123,186 @@ read-only and does not rescan, install, activate, or remove skills.
 
 ## Configuration
 
-Tinker is configured via environment variables:
-
-| Variable | Default | Description |
-|---|---|---|
-| `TINKER_MODEL` | — | Required model name when `TINKER_MODELS` is not set |
-| `TINKER_BASE_URL` | — | Required API base URL |
-| `TINKER_API_KEY` | — | Required API key |
-| `TINKER_MODELS` | — | Path to a multi-model profiles JSON file (see below) |
-| `TINKER_WORKSPACE` | `process.cwd()` | Workspace root |
-| `TINKER_MAX_ITERATIONS` | `512` | Max agent loop iterations per turn |
-| `EXA_API_KEY` | — | Enables WebSearch tool |
-| `TINKER_MCP_CONFIG` | — | Path to MCP server config JSON |
-| `TINKER_EVENT_LOG` | `$TINKER_DIR/events.jsonl` | Event log path |
-| `TINKER_SESSION_DIR` | `$TINKER_DIR/sessions` | Session storage directory |
-| `TINKER_INCLUDE_REASONING` | `false` | Include model reasoning in output |
-| `TINKER_TASK_STOP_GRACE_MS` | `5000` | Grace period before SIGKILL |
-| `TINKER_MCP_TIMEOUT_MS` | `30000` | MCP tool timeout |
-| `TINKER_CONTEXT_BUDGET_TOKENS` | `128000` | Context budget in tokens |
+Set `TINKER_MODELS` to use a profile file. Without it, the env-mode model fields
+are required. Boolean environment values accept case-insensitive `true/false`,
+`1/0`, `yes/no`, and `on/off`.
+
+<!-- BEGIN GENERATED: PUBLIC ENVIRONMENT VARIABLES -->
+| Variable | Area | Applies | Required | Type | Default | Secret | Description |
+| --- | --- | --- | --- | --- | --- | --- | --- |
+| `TINKER_MODELS` | Model | All modes | No | Non-empty string | — | No | Optional model profiles JSON path. Relative paths resolve from the process cwd. |
+| `TINKER_MODEL` | Model | Env mode | Env mode | Non-empty string | — | No | Model name used when model profiles are not configured. |
+| `TINKER_BASE_URL` | Model | Env mode | Env mode | Non-empty string | — | No | OpenAI-compatible Chat Completions API base URL. |
+| `TINKER_API_KEY` | Model | Env mode | Env mode | Non-empty string | — | Yes | API credential for the configured model endpoint. |
+| `TINKER_CONTEXT_WINDOW_TOKENS` | Model | Env mode | Env mode | Positive integer | — | No | Model context-window size in tokens. |
+| `TINKER_MAX_SUPPORTED_OUTPUT_TOKENS` | Model | Env mode | Env mode | Positive integer | — | No | Maximum output-token count supported by the model; must not exceed the context window. |
+| `TINKER_INCLUDE_REASONING_CONTENT` | Model | Env mode | No | Boolean | `false` | No | Include provider reasoning content in the model response mapping. |
+| `TINKER_STREAM` | Model | Env mode | No | Boolean | `true` | No | Use streaming Chat Completions transport. |
+| `TINKER_WEBFETCH_REFINE_MODEL` | Model | Env mode | No | Non-empty string | — | No | Optional WebFetch refiner model; currently must match TINKER_MODEL. |
+| `TINKER_WORKSPACE` | Workspace | All modes | No | Non-empty string | Process cwd | No | Workspace path. Relative paths resolve from the process cwd. |
+| `TINKER_MAX_ITERATIONS` | Workspace | All modes | No | Positive integer | `512` | No | Maximum agent-loop iterations per turn. |
+| `EXA_API_KEY` | Tooling | All modes | No | Non-empty string | — | Yes | Enables WebSearch and the Exa WebFetch backend when set. |
+| `TINKER_MCP_TIMEOUT_MS` | Tooling | All modes | No | Positive integer | `60000` | No | MCP tool-call timeout in milliseconds. |
+| `TINKER_MCP_MAX_OBSERVATION_CHARS` | Tooling | All modes | No | Positive integer | `40000` | No | Maximum model-visible characters in one MCP result. |
+| `TINKER_BASH_DEFAULT_TIMEOUT_MS` | Tooling | All modes | No | Positive integer | `5000` | No | Default Bash foreground timeout in milliseconds. |
+| `TINKER_BASH_MAX_TIMEOUT_MS` | Tooling | All modes | No | Positive integer | `600000` | No | Maximum Bash foreground timeout in milliseconds. |
+| `TINKER_GREP_TIMEOUT_MS` | Tooling | All modes | No | Positive integer | `20000` | No | Bundled ripgrep invocation timeout in milliseconds. |
+| `TINKER_GREP_MAX_BUFFER_BYTES` | Tooling | All modes | No | Positive integer | `20000000` | No | Maximum buffered output from one ripgrep invocation. |
+| `TINKER_WEBFETCH_REFINE_THRESHOLD` | Tooling | All modes | No | Positive integer | `2000` | No | Content-length threshold that enables WebFetch refinement. |
+| `TINKER_RIPGREP_PATH` | Tooling | All modes | No | Non-empty string | Bundled ripgrep | No | Explicit diagnostic override for the bundled ripgrep executable. |
+<!-- END GENERATED: PUBLIC ENVIRONMENT VARIABLES -->
+
+Model and estimator API keys are sent to their configured external endpoints.
+`EXA_API_KEY` is sent to Exa when WebSearch or the Exa WebFetch backend is used.
+Keep configuration files private and review each service's data-handling policy.
 
 ### Multi-Model Profiles
 
-Set `TINKER_MODELS` in `.env` to point to a JSON file with multiple named model
+Set `TINKER_MODELS` to point to a JSON file with multiple named model
 profiles. When set, the profile's `default` field selects the startup model, and
 the `/model` slash command (available in new sessions before any turns) lets you
 switch to another profile. If `TINKER_MODELS` is not set, Tinker falls back to
 the individual `TINKER_*` environment variables. A configured profiles file must
 exist and be valid; Tinker does not silently fall back when it cannot be loaded.
 
+<!-- BEGIN GENERATED: MODEL PROFILE FIELDS -->
+Profile fields:
+
+| Field | Required | Type / constraint | Default | Secret | Description |
+| --- | --- | --- | --- | --- | --- |
+| `model` | Yes | Non-empty string | — | No | Provider model name. |
+| `apiBase` | Yes | Non-empty string | — | No | OpenAI-compatible API base URL. |
+| `apiKey` | Yes | Non-empty string | — | Yes | API credential for this profile. |
+| `contextWindowTokens` | Yes | Positive integer | — | No | Model context-window size in tokens. |
+| `maxSupportedOutputTokens` | Yes | Positive integer | — | No | Maximum output-token count supported by the model; must not exceed contextWindowTokens. |
+| `includeReasoningContent` | No | JSON boolean | `false` | No | Include provider reasoning content in response mapping. |
+| `stream` | No | JSON boolean | `true` | No | Use streaming Chat Completions transport. |
+| `inputModalities` | No | Normalized modality array | `["text"]` | No | Accepted model input modalities; normalizes to ["text"] or ["text", "image"]. |
+| `tokenEstimator` | With image | Object | — | Yes | Independent token estimator required for image profiles. |
+
+`tokenEstimator` fields:
+
+| Field | Type / constraint | Secret | Description |
+| --- | --- | --- | --- |
+| `kind` | Literal `"moonshot-estimate-token-count-v1"` | No | Estimator protocol discriminator. |
+| `model` | Non-empty string | No | Estimator model name. |
+| `apiBase` | Non-empty string | No | Estimator API base URL. |
+| `apiKey` | Non-empty string | Yes | Estimator API credential. |
+| `timeoutMs` | Integer 1000–60000 | No | Estimator request timeout in milliseconds. |
+| `maxRetries` | Literal `0` | No | Estimator retry count; retries are disabled. |
+
+Text-only profile example:
+
+```json
+{
+  "default": "text",
+  "profiles": {
+    "text": {
+      "model": "example-text-model",
+      "apiBase": "https://api.example.com/v1",
+      "apiKey": "your-model-api-key",
+      "contextWindowTokens": 128000,
+      "maxSupportedOutputTokens": 8192,
+      "includeReasoningContent": false,
+      "stream": true,
+      "inputModalities": [
+        "text"
+      ]
+    }
+  }
+}
+```
+
+Image-capable profile example:
+
 ```json
 {
-  "default": "deepseek",
+  "default": "image",
   "profiles": {
-    "deepseek": {
-      "model": "deepseek-chat",
-      "apiBase": "https://api.deepseek.com/v1",
-      "apiKey": "sk-xxx",
+    "image": {
+      "model": "example-vision-model",
+      "apiBase": "https://api.example.com/v1",
+      "apiKey": "your-model-api-key",
       "contextWindowTokens": 128000,
-      "maxSupportedOutputTokens": 8192
-    },
-    "gpt-4o": {
-      "model": "gpt-4o",
-      "apiBase": "https://api.openai.com/v1",
-      "apiKey": "sk-yyy",
+      "maxSupportedOutputTokens": 8192,
+      "includeReasoningContent": false,
+      "stream": true,
+      "inputModalities": [
+        "text",
+        "image"
+      ],
+      "tokenEstimator": {
+        "kind": "moonshot-estimate-token-count-v1",
+        "model": "example-token-estimator",
+        "apiBase": "https://estimator.example.com/v1",
+        "apiKey": "your-estimator-api-key",
+        "timeoutMs": 30000,
+        "maxRetries": 0
+      }
+    }
+  }
+}
+```
+
+The top-level `memory` object is optional. When present, every field below is required. It enables completed-turn extraction and `MemorySearch` only in the TUI; one-shot runs do not load memory.
+
+| Field | Required | Type / constraint | Secret | Description |
+| --- | --- | --- | --- | --- |
+| `profile` | Yes | Non-empty string | No | Existing model profile used for completed-turn atomic-memory extraction. |
+| `embedding` | Yes | Object | Yes | Single embedding profile for the global memory database. |
+
+`memory.embedding` fields:
+
+| Field | Required | Type / constraint | Secret | Description |
+| --- | --- | --- | --- | --- |
+| `name` | Yes | Non-empty string | No | Stable identity for the embedding space. |
+| `kind` | Yes | Literal `"openai-compatible"` | No | Embedding transport kind. |
+| `model` | Yes | Non-empty string | No | Embedding provider model name. |
+| `apiBase` | Yes | Non-empty string | No | OpenAI-compatible API base URL. |
+| `apiKey` | Yes | Non-empty string | Yes | Embedding provider credential. |
+| `dimensions` | Yes | Positive integer | No | Fixed vector dimensions for the global memory database. |
+
+Enabling memory sends completed-turn text (not image bytes) to `memory.profile`, and sends extracted candidates plus search queries to the embedding endpoint. Derived memories are stored in `~/.tinker/memory/memory.sqlite`; newly inserted memory text is appended to the private development log `~/.tinker/memory/extracted-memories.log`.
+
+Atomic-memory profile example:
+
+```json
+{
+  "default": "text",
+  "profiles": {
+    "text": {
+      "model": "example-text-model",
+      "apiBase": "https://api.example.com/v1",
+      "apiKey": "your-model-api-key",
       "contextWindowTokens": 128000,
-      "maxSupportedOutputTokens": 16384,
-      "includeReasoningContent": true
+      "maxSupportedOutputTokens": 8192,
+      "includeReasoningContent": false,
+      "stream": true,
+      "inputModalities": [
+        "text"
+      ]
+    }
+  },
+  "memory": {
+    "profile": "text",
+    "embedding": {
+      "name": "example-embedding-space",
+      "kind": "openai-compatible",
+      "model": "example-embedding-model",
+      "apiBase": "https://embeddings.example.com/v1",
+      "apiKey": "your-embedding-api-key",
+      "dimensions": 1024
     }
   }
 }
 ```
+<!-- END GENERATED: MODEL PROFILE FIELDS -->
 
-You can also start TUI with a specific profile:
+You can also select profiles explicitly for the TUI or one-shot command:
 
 ```bash
-bun run tinker --profile gpt-4o
+tinker --profile text
+tinker run --profile text "explain the project structure"
 ```
 
 Switching models creates a new session. The previous session is preserved and
@@ -151,6 +312,47 @@ longer present or its runtime contract has changed. Older sessions without a
 stored profile name can resume only when their model name uniquely matches one
 configured profile.
 
+### Image Input
+
+Image attachment is enabled only for a profile whose `inputModalities` explicitly
+includes `image` and which supplies a valid `tokenEstimator`. In the interactive
+TUI, type `@` and select a file that is inside the workspace and visible to the
+workspace search rules. One-shot commands, clipboard image bytes, remote URLs, and
+files outside or ignored by the workspace search are not supported.
+
+Tinker accepts PNG (not APNG), JPEG, and static WebP. It rejects GIF, animated
+WebP, and other formats. A message and provider request may contain at most eight
+images; each image may be at most 20 MiB, 4096 pixels on either edge, and 8,847,360
+pixels in total. See the
+[`multimodal image input design`](docs/multimodal-image-input-design.md) for the
+complete fixed policy and persistence contract.
+
+### Built-in Slash Commands
+
+<!-- BEGIN GENERATED: BUILT-IN SLASH COMMANDS -->
+| Command | Description |
+| --- | --- |
+| `/status` | Show session and context details |
+| `/skills` | Show available and active Agent Skills |
+| `/mcp` | Show MCP servers and runtime tools |
+| `/memory` | Browse stored global memories |
+| `/compact [retire]` | Swap tool output or retire a cold history prefix |
+| `/clear` | Start a new session and clear conversation |
+| `/fork` | Clone the current session |
+| `/view <path>` | View a local UTF-8 text file |
+| `/copy` | Copy the last response as Markdown |
+| `/model [profile-name]` | Switch model profile (new session) |
+| `/resume [session-id]` | Choose or resume a session |
+| `/session delete <session-id> --confirm` | Manage stored sessions |
+| `/quit` | Exit the TUI |
+<!-- END GENERATED: BUILT-IN SLASH COMMANDS -->
+
+`/view` opens a readable UTF-8 text file in a full-window viewer. Relative paths
+must remain inside the workspace; absolute paths may point outside it. `/compact`
+swaps eligible historical tool output, while `/compact retire` retires a complete
+cold prefix whose original history remains available through `Recall`. `/copy`
+copies the last completed assistant response as raw Markdown.
+
 ### Project Custom Slash Commands
 
 The TUI loads optional project-scoped prompt aliases from `.tinker.json` in the
@@ -178,24 +380,20 @@ one-shot `tinker run` command. See
 [`docs/project-custom-slash-commands-design.md`](docs/project-custom-slash-commands-design.md)
 for the full contract.
 
+### Workspace-Local Runtime Data
+
+Tinker keeps private runtime state under `<workspace>/.tinker/`: each session has
+its own SQLite database, event log, and observation log, while image assets and
+Prompt history are stored at the workspace level. These locations are fixed and
+have no public path-override environment variables. MCP server configuration is
+loaded from `<workspace>/.mcp.json`; project slash commands are loaded from
+`<workspace>/.tinker.json`.
+
 `Read` has a fixed 262144-byte (256 KiB) content limit per call. A successful
 call always returns the complete requested line range. Use `offset` and `limit`
 to page through larger files; oversized requests fail instead of returning
 truncated content.
 
-## Commands
-
-```bash
-bun install              # Install dependencies
-bun run tinker           # Start the interactive TUI
-bun run tinker run "..." # Run a one-shot CLI prompt
-bun test                 # Run test suite
-bun run typecheck        # TypeScript type checking (tsc --noEmit)
-bun run lint             # ESLint (zero warnings required)
-bun run format           # Biome code formatting
-bun run check            # Full check: typecheck + format + lint + test
-```
-
 ## Project Structure
 
 ```
@@ -228,8 +426,9 @@ tinker/
 ## Requirements
 
 - Node.js 20 or later and npm for the global package installation
-- [Bun](https://bun.sh) 1.3 or later for development from source
-- A compatible LLM API (defaults to DeepSeek; any OpenAI-compatible API works)
+- [Bun](https://bun.sh) 1.3.14 or later for development from source
+- A configured OpenAI-compatible Chat Completions endpoint; transport compatibility
+  alone does not establish provider qualification
 
 ## Security
 

package/bin/tinker.js

@@ -1,39 +1,89 @@
 #!/usr/bin/env node
 
-import { spawnSync } from "node:child_process";
+import { spawn } from "node:child_process";
+import { realpathSync } from "node:fs";
 import { createRequire } from "node:module";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 
 const require = createRequire(import.meta.url);
+const START_FAILURE_MESSAGE =
+  "Tinker failed to start. Reinstall tinker-agent.\n";
 
-let bunPackageJson;
-try {
-  bunPackageJson = require.resolve("bun/package.json");
-} catch {
-  process.stderr.write(
-    "Tinker could not find its bundled Bun runtime. Reinstall tinker-agent.\n",
+export async function launchTinker(
+  input = {
+    args: process.argv.slice(2),
+    stderr: process.stderr,
+  },
+  injected = {},
+) {
+  const resolveBundledBun =
+    injected.resolveBundledBun ?? (() => require.resolve("bun/package.json"));
+  const startChild = injected.spawn ?? spawn;
+  const forwardSignal =
+    injected.forwardSignal ?? ((signal) => process.kill(process.pid, signal));
+
+  let bunPackageJson;
+  try {
+    bunPackageJson = resolveBundledBun();
+  } catch {
+    input.stderr.write(START_FAILURE_MESSAGE);
+    return 1;
+  }
+
+  const bunExecutable = join(dirname(bunPackageJson), "bin", "bun.exe");
+  const tinkerEntryPoint = fileURLToPath(
+    new URL("../src/cli/index.ts", import.meta.url),
   );
-  process.exit(1);
-}
+  let child;
+  try {
+    child = startChild(
+      bunExecutable,
+      [tinkerEntryPoint, ...input.args],
+      { stdio: "inherit" },
+    );
+  } catch {
+    input.stderr.write(START_FAILURE_MESSAGE);
+    return 1;
+  }
 
-const bunExecutable = join(dirname(bunPackageJson), "bin", "bun.exe");
-const tinkerEntryPoint = fileURLToPath(
-  new URL("../src/cli/index.ts", import.meta.url),
-);
-const result = spawnSync(
-  bunExecutable,
-  [tinkerEntryPoint, ...process.argv.slice(2)],
-  { stdio: "inherit" },
-);
-
-if (result.error !== undefined) {
-  process.stderr.write(`Tinker failed to start Bun: ${result.error.message}\n`);
-  process.exit(1);
+  return new Promise((resolve) => {
+    let settled = false;
+    child.once("error", () => {
+      if (settled) {
+        return;
+      }
+      settled = true;
+      input.stderr.write(START_FAILURE_MESSAGE);
+      resolve(1);
+    });
+    child.once("exit", (code, signal) => {
+      if (settled) {
+        return;
+      }
+      settled = true;
+      if (signal !== null) {
+        forwardSignal(signal);
+        resolve(1);
+        return;
+      }
+      resolve(code ?? 1);
+    });
+  });
 }
 
-if (result.signal !== null) {
-  process.kill(process.pid, result.signal);
+function isExecutableEntryPoint() {
+  const entryPoint = process.argv[1];
+  if (entryPoint === undefined) {
+    return false;
+  }
+  try {
+    return realpathSync(entryPoint) === realpathSync(fileURLToPath(import.meta.url));
+  } catch {
+    return false;
+  }
 }
 
-process.exit(result.status ?? 1);
+if (isExecutableEntryPoint()) {
+  process.exitCode = await launchTinker();
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tinker-agent",
-  "version": "1.3.0",
+  "version": "1.5.0",
   "description": "A personal coding agent with an interactive TUI and one-shot CLI.",
   "license": "Apache-2.0",
   "type": "module",
@@ -20,6 +20,7 @@
     "src/image",
     "src/instructions",
     "src/mcp",
+    "src/memory",
     "src/model",
     "src/observation",
     "src/session",
@@ -58,13 +59,18 @@
     "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",
+    "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",
-    "check": "bun run typecheck && bun run format:check && bun run lint && bun test && bun run bench:smoke",
+    "check": "bun run typecheck && bun run format:check && bun run lint && bun run docs:check && bun run test && bun run bench:smoke",
+    "check:fast": "bun run typecheck && bun run format:check && bun run lint && bun run test:fast",
     "format": "biome format --write .",
     "format:check": "biome format .",
     "lint": "eslint \"bin/**/*.js\" \"src/**/*.{ts,tsx}\" \"scripts/**/*.ts\" \"packages/**/*.ts\" --max-warnings=0",
     "lint:fix": "eslint \"bin/**/*.js\" \"src/**/*.{ts,tsx}\" \"scripts/**/*.ts\" \"packages/**/*.ts\" --fix",
-    "test": "bun test",
+    "test": "FORCE_COLOR=0 bun test",
+    "test:fast": "FORCE_COLOR=0 bun test --path-ignore-patterns='**/*pty*.test.ts' --path-ignore-patterns='**/native-host-integration.test.ts'",
+    "test:e2e": "FORCE_COLOR=0 bun test src/__tests__/cli-pty src/__tests__/pty-tui-harness packages/tinker-chrome/__tests__/native-host-integration",
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
@@ -76,6 +82,7 @@
     "@vscode/ripgrep": "1.18.0",
     "bun": "1.3.14",
     "clipboardy": "^5.3.1",
+    "commander": "^14.0.3",
     "diff": "^9.0.0",
     "glob": "^13.0.6",
     "ink": "^7.1.0",
@@ -96,6 +103,8 @@
     "@types/chrome": "^0.2.2",
     "@types/react": "^19.2.17",
     "@types/turndown": "^5.0.6",
+    "@xterm/addon-unicode11": "0.9.0",
+    "@xterm/headless": "6.0.0",
     "eslint": "^10.6.0",
     "eslint-plugin-react-hooks": "^7.1.1",
     "globals": "^17.7.0",