tinker-agent 1.0.65 → 1.1.0

package/README.md

@@ -16,6 +16,9 @@ Built with [Bun](https://bun.sh) + TypeScript ESM, powered by [Ink](https://gith
   - `WebSearch` — Search the web via Exa API
   - `WebFetch` — Fetch and refine web page content (local, browser, or Exa backend)
   - `Recall` — Search or retrieve model-visible history from the current session
+- **Agent Skills**: Discover compatible `SKILL.md` packages at project and user
+  scope, disclose their catalog progressively, and keep activated instructions
+  durable across context compaction and session resume.
 - **MCP integration**: Connect external [Model Context Protocol](https://modelcontextprotocol.io) servers — their tools are dynamically registered as `mcp__<server>__<tool>`.
 - **Session persistence**: Sessions are persisted via SQLite, supporting session resume, history recall, and a catalog to browse and switch between sessions.
 - **Observation system**: Tool execution results are formatted into structured text that the model sees, with separate raw results for event logs and TUI display.
@@ -27,30 +30,58 @@ Built with [Bun](https://bun.sh) + TypeScript ESM, powered by [Ink](https://gith
 ## Quick Start
 
 ```bash
-# Clone and install
-git clone <repo>
-cd tinker
-bun install
+# Bun 1.3 or later is required: https://bun.sh
+npm install --global tinker-agent
 
 # Start the interactive TUI
-bun run tinker
+tinker
 
 # Run a one-shot prompt
-bun run tinker run "explain the project structure"
+tinker run "explain the project structure"
 ```
 
+To run Tinker from a source checkout instead, 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.
-- `/compact` — Deterministically compact eligible historical tool output while the session is idle.
+- `/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
+
+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
+`SKILL.md`; an invalid discovered skill stops activation with a clear error. A
+project skill wins when both scopes define the same name.
+
+Only skill names and descriptions are initially exposed to the model. When the
+model selects a matching skill through the conditional `Skill` tool, Tinker sends
+the complete snapshotted `SKILL.md` and a bounded listing of its standard resource
+directories. Relative resource paths are resolved from that skill's directory and
+are read or executed only through Tinker's existing tools. Activated instructions
+remain in the current system surface across later turns and compaction; resume
+rebinds them to the current validated files.
+
+Skill content is not local-only after activation: it is sent to the configured
+model provider and persisted in the private session SQLite database, event log,
+and observation log, just like other model-visible file content. `/skills` is
+read-only and does not rescan, install, activate, or remove skills.
+
 ## Configuration
 
 Tinker is configured via environment variables:
@@ -117,6 +148,33 @@ 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.
 
+### Project Custom Slash Commands
+
+The TUI loads optional project-scoped prompt aliases from `.tinker.json` in the
+workspace root:
+
+```json
+{
+  "version": 1,
+  "slashCommands": [
+    {
+      "name": "git-commit-and-push",
+      "description": "Commit and push workspace changes",
+      "prompt": "Please inspect the workspace changes, create an appropriate commit, and push it."
+    }
+  ]
+}
+```
+
+Enter `/git-commit-and-push` to submit its configured prompt as an ordinary user
+turn. Built-in slash commands appear first in suggestions, followed by project
+commands in configuration order. Custom commands accept no arguments and cannot
+override built-ins. The optional configuration is loaded once at TUI startup,
+must be valid when present, and has a 1 MiB size limit. It is not loaded by the
+one-shot `tinker run` command. See
+[`docs/project-custom-slash-commands-design.md`](docs/project-custom-slash-commands-design.md)
+for the full contract.
+
 `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
@@ -146,6 +204,7 @@ tinker/
 │   ├── model/         # Model clients (OpenAI-compatible, fake), chat mapping, preflight
 │   ├── mcp/           # MCP server management, tool executor adapter
 │   ├── observation/   # Tool result → model-visible text
+│   ├── skills/        # Agent Skills discovery, catalog, activation, and context
 │   ├── session/       # SQLite session store, catalog, history reader, resume
 │   ├── events/        # Event sinks, JSONL log, stdout printer
 │   ├── tui/           # Ink/React UI components, projection store, session controller

package/node_modules/ansi-regex/index.d.ts

@@ -0,0 +1,33 @@
+export type Options = {
+	/**
+	Match only the first ANSI escape.
+
+	@default false
+	*/
+	readonly onlyFirst: boolean;
+};
+
+/**
+Regular expression for matching ANSI escape codes.
+
+@example
+```
+import ansiRegex from 'ansi-regex';
+
+ansiRegex().test('\u001B[4mcake\u001B[0m');
+//=> true
+
+ansiRegex().test('cake');
+//=> false
+
+'\u001B[4mcake\u001B[0m'.match(ansiRegex());
+//=> ['\u001B[4m', '\u001B[0m']
+
+'\u001B[4mcake\u001B[0m'.match(ansiRegex({onlyFirst: true}));
+//=> ['\u001B[4m']
+
+'\u001B]8;;https://github.com\u0007click\u001B]8;;\u0007'.match(ansiRegex());
+//=> ['\u001B]8;;https://github.com\u0007', '\u001B]8;;\u0007']
+```
+*/
+export default function ansiRegex(options?: Options): RegExp;

package/node_modules/ansi-regex/index.js

@@ -0,0 +1,14 @@
+export default function ansiRegex({onlyFirst = false} = {}) {
+	// Valid string terminator sequences are BEL, ESC\, and 0x9c
+	const ST = '(?:\\u0007|\\u001B\\u005C|\\u009C)';
+
+	// OSC sequences only: ESC ] ... ST (non-greedy until the first ST)
+	const osc = `(?:\\u001B\\][\\s\\S]*?${ST})`;
+
+	// CSI and related: ESC/C1, optional intermediates, optional params (supports ; and :) then final byte
+	const csi = '[\\u001B\\u009B][[\\]()#;?]*(?:\\d{1,4}(?:[;:]\\d{0,4})*)?[\\dA-PR-TZcf-nq-uy=><~]';
+
+	const pattern = `${osc}|${csi}`;
+
+	return new RegExp(pattern, onlyFirst ? undefined : 'g');
+}

package/node_modules/ansi-regex/license

@@ -0,0 +1,9 @@
+MIT License
+
+Copyright (c) Sindre Sorhus <sindresorhus@gmail.com> (https://sindresorhus.com)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/node_modules/ansi-regex/package.json

@@ -0,0 +1,61 @@
+{
+	"name": "ansi-regex",
+	"version": "6.2.2",
+	"description": "Regular expression for matching ANSI escape codes",
+	"license": "MIT",
+	"repository": "chalk/ansi-regex",
+	"funding": "https://github.com/chalk/ansi-regex?sponsor=1",
+	"author": {
+		"name": "Sindre Sorhus",
+		"email": "sindresorhus@gmail.com",
+		"url": "https://sindresorhus.com"
+	},
+	"type": "module",
+	"exports": "./index.js",
+	"types": "./index.d.ts",
+	"sideEffects": false,
+	"engines": {
+		"node": ">=12"
+	},
+	"scripts": {
+		"test": "xo && ava && tsd",
+		"view-supported": "node fixtures/view-codes.js"
+	},
+	"files": [
+		"index.js",
+		"index.d.ts"
+	],
+	"keywords": [
+		"ansi",
+		"styles",
+		"color",
+		"colour",
+		"colors",
+		"terminal",
+		"console",
+		"cli",
+		"string",
+		"tty",
+		"escape",
+		"formatting",
+		"rgb",
+		"256",
+		"shell",
+		"xterm",
+		"command-line",
+		"text",
+		"regex",
+		"regexp",
+		"re",
+		"match",
+		"test",
+		"find",
+		"pattern"
+	],
+	"devDependencies": {
+		"ansi-escapes": "^5.0.0",
+		"ava": "^3.15.0",
+		"tsd": "^0.21.0",
+		"xo": "^0.54.2"
+	}
+}

package/node_modules/ansi-regex/readme.md

@@ -0,0 +1,66 @@
+# ansi-regex
+
+> Regular expression for matching [ANSI escape codes](https://en.wikipedia.org/wiki/ANSI_escape_code)
+
+## Install
+
+```sh
+npm install ansi-regex
+```
+
+## Usage
+
+```js
+import ansiRegex from 'ansi-regex';
+
+ansiRegex().test('\u001B[4mcake\u001B[0m');
+//=> true
+
+ansiRegex().test('cake');
+//=> false
+
+'\u001B[4mcake\u001B[0m'.match(ansiRegex());
+//=> ['\u001B[4m', '\u001B[0m']
+
+'\u001B[4mcake\u001B[0m'.match(ansiRegex({onlyFirst: true}));
+//=> ['\u001B[4m']
+
+'\u001B]8;;https://github.com\u0007click\u001B]8;;\u0007'.match(ansiRegex());
+//=> ['\u001B]8;;https://github.com\u0007', '\u001B]8;;\u0007']
+```
+
+## API
+
+### ansiRegex(options?)
+
+Returns a regex for matching ANSI escape codes.
+
+#### options
+
+Type: `object`
+
+##### onlyFirst
+
+Type: `boolean`\
+Default: `false` *(Matches any ANSI escape codes in a string)*
+
+Match only the first ANSI escape.
+
+## Important
+
+If you run the regex against untrusted user input in a server context, you should [give it a timeout](https://github.com/sindresorhus/super-regex).
+
+**I do not consider [ReDoS](https://blog.yossarian.net/2022/12/28/ReDoS-vulnerabilities-and-misaligned-incentives) a valid vulnerability for this package.**
+
+## FAQ
+
+### Why do you test for codes not in the ECMA 48 standard?
+
+Some of the codes we run as a test are codes that we acquired finding various lists of non-standard or manufacturer specific codes. We test for both standard and non-standard codes, as most of them follow the same or similar format and can be safely matched in strings without the risk of removing actual string content. There are a few non-standard control codes that do not follow the traditional format (i.e. they end in numbers) thus forcing us to exclude them from the test because we cannot reliably match them.
+
+On the historical side, those ECMA standards were established in the early 90's whereas the VT100, for example, was designed in the mid/late 70's. At that point in time, control codes were still pretty ungoverned and engineers used them for a multitude of things, namely to activate hardware ports that may have been proprietary. Somewhere else you see a similar 'anarchy' of codes is in the x86 architecture for processors; there are a ton of "interrupts" that can mean different things on certain brands of processors, most of which have been phased out.
+
+## Maintainers
+
+- [Sindre Sorhus](https://github.com/sindresorhus)
+- [Josh Junon](https://github.com/qix-)

package/node_modules/ansi-styles/index.d.ts

@@ -0,0 +1,236 @@
+export type CSPair = { // eslint-disable-line @typescript-eslint/naming-convention
+	/**
+	The ANSI terminal control sequence for starting this style.
+	*/
+	readonly open: string;
+
+	/**
+	The ANSI terminal control sequence for ending this style.
+	*/
+	readonly close: string;
+};
+
+export type ColorBase = {
+	/**
+	The ANSI terminal control sequence for ending this color.
+	*/
+	readonly close: string;
+
+	ansi(code: number): string;
+
+	ansi256(code: number): string;
+
+	ansi16m(red: number, green: number, blue: number): string;
+};
+
+export type Modifier = {
+	/**
+	Resets the current color chain.
+	*/
+	readonly reset: CSPair;
+
+	/**
+	Make text bold.
+	*/
+	readonly bold: CSPair;
+
+	/**
+	Emitting only a small amount of light.
+	*/
+	readonly dim: CSPair;
+
+	/**
+	Make text italic. (Not widely supported)
+	*/
+	readonly italic: CSPair;
+
+	/**
+	Make text underline. (Not widely supported)
+	*/
+	readonly underline: CSPair;
+
+	/**
+	Make text overline.
+
+	Supported on VTE-based terminals, the GNOME terminal, mintty, and Git Bash.
+	*/
+	readonly overline: CSPair;
+
+	/**
+	Inverse background and foreground colors.
+	*/
+	readonly inverse: CSPair;
+
+	/**
+	Prints the text, but makes it invisible.
+	*/
+	readonly hidden: CSPair;
+
+	/**
+	Puts a horizontal line through the center of the text. (Not widely supported)
+	*/
+	readonly strikethrough: CSPair;
+};
+
+export type ForegroundColor = {
+	readonly black: CSPair;
+	readonly red: CSPair;
+	readonly green: CSPair;
+	readonly yellow: CSPair;
+	readonly blue: CSPair;
+	readonly cyan: CSPair;
+	readonly magenta: CSPair;
+	readonly white: CSPair;
+
+	/**
+	Alias for `blackBright`.
+	*/
+	readonly gray: CSPair;
+
+	/**
+	Alias for `blackBright`.
+	*/
+	readonly grey: CSPair;
+
+	readonly blackBright: CSPair;
+	readonly redBright: CSPair;
+	readonly greenBright: CSPair;
+	readonly yellowBright: CSPair;
+	readonly blueBright: CSPair;
+	readonly cyanBright: CSPair;
+	readonly magentaBright: CSPair;
+	readonly whiteBright: CSPair;
+};
+
+export type BackgroundColor = {
+	readonly bgBlack: CSPair;
+	readonly bgRed: CSPair;
+	readonly bgGreen: CSPair;
+	readonly bgYellow: CSPair;
+	readonly bgBlue: CSPair;
+	readonly bgCyan: CSPair;
+	readonly bgMagenta: CSPair;
+	readonly bgWhite: CSPair;
+
+	/**
+	Alias for `bgBlackBright`.
+	*/
+	readonly bgGray: CSPair;
+
+	/**
+	Alias for `bgBlackBright`.
+	*/
+	readonly bgGrey: CSPair;
+
+	readonly bgBlackBright: CSPair;
+	readonly bgRedBright: CSPair;
+	readonly bgGreenBright: CSPair;
+	readonly bgYellowBright: CSPair;
+	readonly bgBlueBright: CSPair;
+	readonly bgCyanBright: CSPair;
+	readonly bgMagentaBright: CSPair;
+	readonly bgWhiteBright: CSPair;
+};
+
+export type ConvertColor = {
+	/**
+	Convert from the RGB color space to the ANSI 256 color space.
+
+	@param red - (`0...255`)
+	@param green - (`0...255`)
+	@param blue - (`0...255`)
+	*/
+	rgbToAnsi256(red: number, green: number, blue: number): number;
+
+	/**
+	Convert from the RGB HEX color space to the RGB color space.
+
+	@param hex - A hexadecimal string containing RGB data.
+	*/
+	hexToRgb(hex: string): [red: number, green: number, blue: number];
+
+	/**
+	Convert from the RGB HEX color space to the ANSI 256 color space.
+
+	@param hex - A hexadecimal string containing RGB data.
+	*/
+	hexToAnsi256(hex: string): number;
+
+	/**
+	Convert from the ANSI 256 color space to the ANSI 16 color space.
+
+	@param code - A number representing the ANSI 256 color.
+	*/
+	ansi256ToAnsi(code: number): number;
+
+	/**
+	Convert from the RGB color space to the ANSI 16 color space.
+
+	@param red - (`0...255`)
+	@param green - (`0...255`)
+	@param blue - (`0...255`)
+	*/
+	rgbToAnsi(red: number, green: number, blue: number): number;
+
+	/**
+	Convert from the RGB HEX color space to the ANSI 16 color space.
+
+	@param hex - A hexadecimal string containing RGB data.
+	*/
+	hexToAnsi(hex: string): number;
+};
+
+/**
+Basic modifier names.
+*/
+export type ModifierName = keyof Modifier;
+
+/**
+Basic foreground color names.
+
+[More colors here.](https://github.com/chalk/chalk/blob/main/readme.md#256-and-truecolor-color-support)
+*/
+export type ForegroundColorName = keyof ForegroundColor;
+
+/**
+Basic background color names.
+
+[More colors here.](https://github.com/chalk/chalk/blob/main/readme.md#256-and-truecolor-color-support)
+*/
+export type BackgroundColorName = keyof BackgroundColor;
+
+/**
+Basic color names. The combination of foreground and background color names.
+
+[More colors here.](https://github.com/chalk/chalk/blob/main/readme.md#256-and-truecolor-color-support)
+*/
+export type ColorName = ForegroundColorName | BackgroundColorName;
+
+/**
+Basic modifier names.
+*/
+export const modifierNames: readonly ModifierName[];
+
+/**
+Basic foreground color names.
+*/
+export const foregroundColorNames: readonly ForegroundColorName[];
+
+/**
+Basic background color names.
+*/
+export const backgroundColorNames: readonly BackgroundColorName[];
+
+/*
+Basic color names. The combination of foreground and background color names.
+*/
+export const colorNames: readonly ColorName[];
+
+declare const ansiStyles: {
+	readonly modifier: Modifier;
+	readonly color: ColorBase & ForegroundColor;
+	readonly bgColor: ColorBase & BackgroundColor;
+	readonly codes: ReadonlyMap<number, number>;
+} & ForegroundColor & BackgroundColor & Modifier & ConvertColor;
+
+export default ansiStyles;