@tinchu0/knitt 0.1.0-beta.4 → 0.1.0-beta.5

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (40) hide show
  1. package/README.md +26 -15
  2. package/dist/apps/server/src/conversation-server.js +203 -0
  3. package/dist/apps/server/src/http-gateway.js +1 -1
  4. package/dist/apps/server/src/main.js +6 -2
  5. package/dist/apps/server/src/server.js +292 -81
  6. package/dist/memory-schema.json +1 -0
  7. package/dist/packages/adapters/src/cli.js +193 -45
  8. package/dist/packages/adapters/src/command.js +149 -18
  9. package/dist/packages/adapters/src/discovery.js +128 -0
  10. package/dist/packages/adapters/src/handoff.js +13 -8
  11. package/dist/packages/adapters/src/histories.js +222 -0
  12. package/dist/packages/adapters/src/history-time.js +10 -0
  13. package/dist/packages/adapters/src/hooks.js +123 -44
  14. package/dist/packages/adapters/src/launch.js +10 -3
  15. package/dist/packages/adapters/src/picker.js +2 -1
  16. package/dist/packages/adapters/src/providers/jsonl.js +105 -0
  17. package/dist/packages/adapters/src/question-ui.js +37 -0
  18. package/dist/packages/adapters/src/repository.js +32 -5
  19. package/dist/packages/adapters/src/scope.js +9 -3
  20. package/dist/packages/adapters/src/server-name.js +6 -0
  21. package/dist/packages/adapters/src/status.js +81 -0
  22. package/dist/packages/adapters/src/transcript.js +72 -15
  23. package/dist/packages/contracts/src/conversations.js +30 -0
  24. package/dist/packages/installer/src/antigravity.js +90 -0
  25. package/dist/packages/installer/src/cli.js +210 -48
  26. package/dist/packages/installer/src/connections.js +193 -38
  27. package/dist/packages/installer/src/runtime.js +73 -11
  28. package/dist/packages/memory/src/checkpoints.js +68 -0
  29. package/dist/packages/memory/src/context.js +91 -0
  30. package/dist/packages/memory/src/conversations.js +148 -0
  31. package/dist/packages/memory/src/migrations.js +55 -0
  32. package/dist/packages/memory/src/store.js +201 -23
  33. package/dist/skills/continue-chat/SKILL.md +15 -0
  34. package/dist/skills/knit/SKILL.md +11 -5
  35. package/docs/clients/connector-setup.md +1 -1
  36. package/docs/clients/local-agent-memory.md +50 -0
  37. package/docs/clients/npm-installation.md +23 -11
  38. package/docs/clients/support-matrix.md +12 -0
  39. package/docs/usage.md +19 -29
  40. package/package.json +5 -4
@@ -1,6 +1,14 @@
1
1
  # npm installation and runtime lifecycle
2
2
 
3
- ## Try the unpublished release candidate
3
+ ## Install the beta
4
+
5
+ ```bash
6
+ npx --yes @tinchu0/knitt@next setup --workspace /path/to/project --client antigravity
7
+ ```
8
+
9
+ Setup registers Antigravity’s global MCP server and verifies its memory tools automatically. Restart Antigravity and use `/knit` in a fresh chat. Choose a conversation inside the same coding interface. Antigravity uses its selectable question UI; clients with native MCP forms can use those.
10
+
11
+ ## Test a local build
4
12
 
5
13
  Build and pack from the repository:
6
14
 
@@ -14,12 +22,12 @@ npm pack
14
22
  Then use the tarball (absolute paths work from any directory):
15
23
 
16
24
  ```bash
17
- npx --yes --package ./tinchu0-knitt-0.1.0-beta.1.tgz knitt setup \
25
+ npx --yes --package ./tinchu0-knitt-0.1.0-beta.5.tgz knitt setup \
18
26
  --workspace /path/to/project --client codex --client claude-code \
19
- --package /absolute/path/to/tinchu0-knitt-0.1.0-beta.1.tgz
27
+ --package /absolute/path/to/tinchu0-knitt-0.1.0-beta.5.tgz
20
28
  ```
21
29
 
22
- The outer `--package` tells npx which CLI to run. The `--package` after `setup` tells setup which exact artifact to install persistently. Before registry publication this second argument is required for applying setup; preview can run without it. The release candidate is configured for registry publication; until it is published, pass the explicit tarball to setup/update. After publication, omitting the internal package argument installs the CLI's exact published version. `update` follows the `next` registry tag for prerelease CLIs and `latest` for stable CLIs.
30
+ The outer `--package` tells npx which CLI to run. The `--package` after `setup` tells setup which exact artifact to install persistently. For a local build, pass this second argument to setup/update so the persistent runtime uses your local artifact. For a published CLI, omitting it installs the CLI's exact published version. `update` follows the `next` registry tag for prerelease CLIs and `latest` for stable CLIs.
23
31
 
24
32
  Use `--preview` to inspect changes without creating installation/configuration files. Interactive setup asks before applying; automation must pass `--yes`. Repeat `--client` for several agents. Setup requires Git repository metadata to derive a stable repository identity.
25
33
 
@@ -27,19 +35,19 @@ Use `--preview` to inspect changes without creating installation/configuration f
27
35
 
28
36
  Install Node.js 24+ (including npm) and Git, and ensure both are on PATH. Use the same package on all platforms. Windows hooks use built-in Windows PowerShell 5.1 (`powershell.exe` on PATH); no WSL or Python is needed for npm setup. macOS and Linux hooks use their existing POSIX shell.
29
37
 
30
- Until publication, build the tarball as above, then run from its directory. Windows PowerShell example (one line, with quoted paths):
38
+ For a local build, pack the tarball as above, then run from its directory. Windows PowerShell example (one line, with quoted paths):
31
39
 
32
40
  ```powershell
33
- npx --yes --package .\tinchu0-knitt-0.1.0-beta.1.tgz knitt setup --workspace "C:\Users\you\My Project" --client codex --client claude-code --package "C:\Downloads\tinchu0-knitt-0.1.0-beta.1.tgz"
41
+ npx --yes --package .\tinchu0-knitt-0.1.0-beta.5.tgz knitt setup --workspace "C:\Users\you\My Project" --client codex --client claude-code --package "C:\Downloads\tinchu0-knitt-0.1.0-beta.5.tgz"
34
42
  ```
35
43
 
36
44
  macOS example:
37
45
 
38
46
  ```sh
39
- npx --yes --package ./tinchu0-knitt-0.1.0-beta.1.tgz knitt setup --workspace "$HOME/Projects/My Project" --client codex --client claude-code --package "$HOME/Downloads/tinchu0-knitt-0.1.0-beta.1.tgz"
47
+ npx --yes --package ./tinchu0-knitt-0.1.0-beta.5.tgz knitt setup --workspace "$HOME/Projects/My Project" --client codex --client claude-code --package "$HOME/Downloads/tinchu0-knitt-0.1.0-beta.5.tgz"
40
48
  ```
41
49
 
42
- Replace the artifact path with its actual location. The existing lifecycle commands below work on each platform. Restart clients and approve their normal hook/MCP trust prompts. For Claude Desktop, merge the generated fragment into Desktop settings manually.
50
+ Replace the artifact path with its actual location. The existing lifecycle commands below work on each platform. Restart clients and approve their normal hook/MCP trust prompts. For Claude Desktop, merge the generated fragment into Desktop settings manually. For Antigravity, setup registers a separate server for each project in `~/.gemini/config/mcp_config.json`, preserving existing servers, and verifies its tool connection. Project `.agents/mcp_config.json` alone does not activate it. Override the global config location with `--antigravity-config PATH` during setup; the installer remembers it for later commands. `KNITT_ANTIGRAVITY_CONFIG` is an alternative override for isolated environments.
43
51
 
44
52
  ## Durable installation
45
53
 
@@ -57,7 +65,7 @@ The project-local `.memory/npm-connection.json` records original and generated s
57
65
 
58
66
  ## Commands
59
67
 
60
- Run commands through the tarball CLI above (or the eventual published package):
68
+ Run commands through `npx --yes @tinchu0/knitt@next` or the local tarball CLI above:
61
69
 
62
70
  ```text
63
71
  knitt setup --workspace PATH --client codex --preview
@@ -72,10 +80,14 @@ Use the same `--home` for every lifecycle command if you customized it. `doctor`
72
80
 
73
81
  Update installs another runtime before changing project connections. Failed dependency installation leaves the active installation metadata and bindings untouched. Rollback switches managed projects to the previous runtime, preserving memory. Old runtime directories remain available; garbage collection is not implemented.
74
82
 
75
- Uninstall restores unchanged managed values and preserves independent additions or user edits. It removes one project's bindings and registry entry while retaining the runtime and all memory. It does not recursively delete the application directory or memory. Claude Desktop fragments must still be removed manually from Desktop's actual configuration if previously merged there.
83
+ Uninstall restores unchanged managed values and preserves independent additions or user edits. It removes one project's bindings and registry entry while retaining the runtime and all memory. It does not recursively delete the application directory or memory. Antigravity’s unchanged global entries are removed automatically; user-edited entries remain. The `.knitt-*.json` ownership file beside its MCP config is retained until the last managed entry is removed. Claude Desktop fragments must be removed manually from Desktop settings if previously merged there. Older manually merged Antigravity entries are not adopted or removed automatically.
76
84
 
77
85
  ## Release gates
78
86
 
79
- The selected package is `@tinchu0/knitt`, owned by the intended npm account `tinchu0`. A registry lookup returned no public package on 2026-11-13; Terminal login as `tinchu0` is verified. Version `0.1.0-beta.1` is prepared with public access and the `next` tag; actual publication is still pending. Knitt is licensed under Apache-2.0; the LICENSE file ships in the npm package. Native Windows setup now generates Windows PowerShell hooks and launches npm through its JavaScript entry point without interpolating package arguments through a shell. Linux tarball lifecycle checks passed locally. CI is configured for Linux, macOS and Windows; native macOS/Windows runs and live client behavior remain unverified until those checks are observed.
87
+ The npm package is `@tinchu0/knitt`; prereleases use the `next` tag. Knitt is licensed under Apache-2.0; LICENSE ships in the archive. Linux tarball lifecycle checks cover automatic Antigravity registration, native session IDs, MCP tool discovery, updates, rollback after failed server verification and uninstall. CI is configured for Linux, macOS and Windows; native macOS/Windows runs and live client behavior remain unverified until observed.
80
88
 
81
89
  ChatGPT, Claude web and teammate machines require a separately reachable authenticated service. Packaging a CLI does not supply hosting, authentication accounts or background synchronization.
90
+
91
+ ### Optional local conversation mode
92
+
93
+ Add `--capture-new-sessions` to setup to opt a connected project into independent session capture and explicit continuation links. The preference survives subsequent setup/update operations. Existing connections keep their previous semantics until opted in. This mode upgrades the database using consistent SQLite backups; the updated installer blocks incompatible runtime downgrade rather than restoring data automatically. Use `doctor` for content-free capture status. See [setup and recovery](local-agent-memory.md).
@@ -35,3 +35,15 @@ Live local result: fresh Codex sessions verified automatic Stop capture and star
35
35
  | Windows | Native PowerShell hooks; shell-free npm JS entry point; LOCALAPPDATA storage | Windows command generation/npm discovery checked on Linux; CI configured on windows-latest. Native execution and live client handoff not yet observed. |
36
36
 
37
37
  The matrix workflow runs Node.js 24 and Python 3.12. Python is used only by legacy source-installer tests, not the npm runtime. All runners execute type checking, the full suite and the tarball lifecycle smoke test. Configured CI is not evidence that a remote run has passed.
38
+
39
+
40
+ ## Antigravity npm registration and picker · 2026-11-14
41
+
42
+ Npm setup now registers a separate MCP entry per project in Antigravity’s global config and verifies its five tools before runtime activation. Project hooks name that entry and supply the native chat ID. Antigravity shows conversation options inside the same chat because a recorded native-form request returned `selected: false` without an accepted choice. Other coding clients use native forms where supported and in-chat options otherwise. Tests exercise explicit selection, cancellation, session isolation, single-use choice IDs, preservation of unrelated settings and rollback on failed server verification. Automated process evidence does not establish that a human completed this flow inside each client. Browser pickers remain a remote HTTP connector feature.
43
+
44
+
45
+ ## Cross-agent history discovery · 2026-11-14
46
+
47
+ Coding connections identify their host with MEMORY_CLIENT. The picker excludes that source before searching/limiting, merges local Claude Code project JSONL, Codex indexed/session-file history and Antigravity indexed history, labels the source and orders by timestamp newest first. Tests cover every host/source pair, same-ID collisions across agents, indexed and session-file Codex discovery, incomplete-index fallback, source/branch attribution, redaction, worktrees, unrelated projects and subagent exclusion. Local scans confirmed Claude and Codex discovery for Weave; actual rigved connections returned 16 Codex histories for Antigravity and seven Antigravity histories for Codex, without importing a choice. No local Claude history was found for rigved.
48
+
49
+ 72 tests and the packaged install/update/rollback/uninstall smoke passed after the correction. Native visual behavior still depends on the host client; the test validates protocol behavior and source selection, not a human completing every client UI.
package/docs/usage.md CHANGED
@@ -16,26 +16,15 @@ git --version
16
16
 
17
17
  The installer includes native Linux, macOS and Windows paths. Windows hooks require built-in Windows PowerShell; macOS and Linux use POSIX hooks. Linux checks passed locally; native Windows/macOS runs still need confirmation. Client configuration support does not guarantee that every client has passed a live handoff test. See the [client support evidence](clients/support-matrix.md).
18
18
 
19
- ## 2. Build the installation package
19
+ ## 2. Run the package
20
20
 
21
- The repository currently documents Knitt as an unpublished release candidate. Use a locally built tarball for this guide; registry installation is not assumed.
22
-
23
- From the Knitt source checkout:
21
+ Use the published beta through npm’s `next` channel:
24
22
 
25
23
  ```bash
26
- npm ci
27
- npm run check
28
- npm run build
29
- npm pack
24
+ npx --yes @tinchu0/knitt@next --version
30
25
  ```
31
26
 
32
- For version `0.1.0-beta.1`, this produces `tinchu0-knitt-0.1.0-beta.1.tgz`. Set its absolute path so the following commands work from any folder:
33
-
34
- ```bash
35
- KNITT_TARBALL="/absolute/path/to/knitt/tinchu0-knitt-0.1.0-beta.1.tgz"
36
- ```
37
-
38
- Replace the example path with the location printed by `npm pack`. If the package version changes, use the new filename. Keep the tarball available for later management commands.
27
+ No source checkout is needed. To test a source build instead, see [local tarball installation](clients/npm-installation.md).
39
28
 
40
29
  ## 3. Connect your project
41
30
 
@@ -44,7 +33,7 @@ Replace `/absolute/path/to/your-project` below with the Git repository whose con
44
33
  First preview the configuration:
45
34
 
46
35
  ```bash
47
- npx --yes --package "$KNITT_TARBALL" knitt setup \
36
+ npx --yes @tinchu0/knitt@next setup \
48
37
  --workspace /absolute/path/to/your-project \
49
38
  --client codex --client antigravity \
50
39
  --preview
@@ -53,17 +42,16 @@ npx --yes --package "$KNITT_TARBALL" knitt setup \
53
42
  Then install:
54
43
 
55
44
  ```bash
56
- npx --yes --package "$KNITT_TARBALL" knitt setup \
45
+ npx --yes @tinchu0/knitt@next setup \
57
46
  --workspace /absolute/path/to/your-project \
58
- --client codex --client antigravity \
59
- --package "$KNITT_TARBALL"
47
+ --client codex --client antigravity
60
48
  ```
61
49
 
62
50
  Review the displayed changes and confirm in the terminal. For noninteractive setup, add `--yes` after `setup`; the outer `npx --yes` only approves npx's package prompt.
63
51
 
64
52
  Supported `--client` values are `codex`, `claude-code`, `antigravity`, and `claude-desktop`. Repeat the flag for each client you use. Running setup without `--workspace` and `--client` asks for them interactively.
65
53
 
66
- The two package arguments have different jobs: npx's `--package` runs the CLI, while setup's `--package` installs that exact artifact as a persistent runtime. Connected agents then use the persistent runtime independently of npx's temporary cache.
54
+ Setup installs a persistent runtime matching the CLI version. Connected agents use it independently of npx's temporary cache.
67
55
 
68
56
  Restart connected agents, open the target project, and approve their normal MCP and hook trust prompts. Claude Desktop needs an extra manual step described below.
69
57
 
@@ -79,9 +67,9 @@ If your client does not expose slash skills, ask:
79
67
 
80
68
  > Use Knitt's shared-memory connection to open the conversation picker. Let me choose a chat, then retrieve its checkpoint and summarize the last progress and next step.
81
69
 
82
- Choose the source conversation in the picker. Knitt's current picker discovers local **Antigravity conversations** belonging to the connected repository, including linked worktrees. It does not browse arbitrary Claude or ChatGPT account history.
70
+ Choose the source conversation inside your coding interface. Antigravity opens its selectable question UI; click the conversation you want. Clients supporting native forms can show those directly. No browser or separate terminal is required for a connected coding client. Knitt requires the active folder on each coding-picker call and rejects a connection for a different project. The picker shows the project folder above its choices. It discovers local **Claude Code, Codex and Antigravity histories** belonging to that repository, including linked worktrees. It excludes the agent you are using, labels each source, and offers only the four most recent matching chats, newest first. It does not browse remote Claude or ChatGPT account history.
83
71
 
84
- After selection, the agent calls `get_context` and shows the restored checkpoint. Review it, then give a concrete instruction, for example:
72
+ After selection, Knitt returns bounded context in the acceptance response and the agent shows the restored checkpoint. Older servers fall back to one `get_context` call. Review it, then give a concrete instruction, for example:
85
73
 
86
74
  > Continue the retry implementation from this checkpoint. Inspect the current branch first and run the relevant tests after making changes.
87
75
 
@@ -107,9 +95,11 @@ Checkpoints are reference material: inspect current files and branch state befor
107
95
 
108
96
  ## Claude Desktop, ChatGPT, and Claude web
109
97
 
98
+ **Antigravity:** setup automatically registers and verifies a project-specific memory server in `~/.gemini/config/mcp_config.json`, preserving existing servers. Restart Antigravity and use `/knit` in a fresh chat. Choose a conversation inside the same coding interface. Antigravity uses its selectable question UI; clients with native MCP forms can use those. Several projects can coexist; startup hooks identify the matching server. Update, rollback and uninstall manage Knitt’s unchanged entries. Use `--antigravity-config PATH` during setup if your installation uses another location; subsequent lifecycle commands remember that path.
99
+
110
100
  **Claude Desktop:** select `--client claude-desktop` during setup. Merge the generated project's `.memory/connectors/claude-desktop.json` `mcpServers` entry into Desktop's local MCP settings, then restart Desktop. Knitt generates the fragment; it does not perform this merge for you.
111
101
 
112
- In a new ordinary chat, ask the agent to call `start_session`, then `choose_conversation`, wait for your selection, and call `get_context`. Use the session ID returned for that chat. Ask for `save_memory` after substantive progress.
102
+ In a new ordinary chat, ask the agent to call `start_session`, then `choose_conversation`, wait for your selection, and summarize the returned context (or call `get_context` if using the browser fallback). Use the session ID returned for that chat. Ask for `save_memory` after substantive progress.
113
103
 
114
104
  **ChatGPT and Claude web:** require a separately hosted HTTPS MCP endpoint and a compatible OAuth provider. Local CLI setup does not deploy that service. Follow [remote connector setup](clients/connector-setup.md) for profiles, authentication requirements, and browser picker behavior. These clients are not assumed to be live-connected by completing the local quickstart.
115
105
 
@@ -117,12 +107,12 @@ Local memory lives on one machine. Connecting another machine or using an identi
117
107
 
118
108
  ## Manage your installation
119
109
 
120
- Use the same tarball CLI and, if configured, the same `--home /absolute/path` for all commands.
110
+ Use the same npm channel and, if configured, the same `--home /absolute/path` for all commands.
121
111
 
122
112
  Check the installation:
123
113
 
124
114
  ```bash
125
- npx --yes --package "$KNITT_TARBALL" knitt doctor
115
+ npx --yes @tinchu0/knitt@next doctor
126
116
  ```
127
117
 
128
118
  `configured` means local paths and managed settings passed inspection. It does not verify client login, trust approval, or a live handoff.
@@ -138,13 +128,13 @@ npx --yes --package "$KNITT_NEXT_TARBALL" knitt update \
138
128
  Return to the previous runtime, if an earlier installation exists:
139
129
 
140
130
  ```bash
141
- npx --yes --package "$KNITT_TARBALL" knitt rollback --yes
131
+ npx --yes @tinchu0/knitt@next rollback --yes
142
132
  ```
143
133
 
144
134
  Disconnect one project:
145
135
 
146
136
  ```bash
147
- npx --yes --package "$KNITT_TARBALL" knitt uninstall \
137
+ npx --yes @tinchu0/knitt@next uninstall \
148
138
  --workspace /absolute/path/to/your-project --yes
149
139
  ```
150
140
 
@@ -155,8 +145,8 @@ Uninstall restores unchanged managed settings while retaining user edits, the ru
155
145
  | Symptom | What to check |
156
146
  | --- | --- |
157
147
  | No shared-memory tools or `/knit` | Restart the client in the connected project. Check MCP and hook trust prompts, then run `doctor`. |
158
- | No conversations in the picker | Confirm the source chat is a local Antigravity conversation associated with this repository or its worktrees. Try searching its title. Other account histories are not imported. |
159
- | Client cannot show a selection form | For local Antigravity-to-Codex handoff, use the source-checkout fallback below. Remote HTTP clients may receive a browser picker link instead. |
148
+ | No conversations in the picker | Confirm another coding agent has a local history for this repository or its worktrees. The current agent’s own chats are excluded. Try searching the source title. Remote account histories are not imported. |
149
+ | Client cannot show a selection form | The agent must invoke the application’s native question tool with Knitt’s returned options. A printed list is not the picker. If the question tool is unavailable, native selection is unavailable in that session. Remote web connectors may use a browser picker. |
160
150
  | “No chat selected” | Open the picker and choose a conversation in this session before retrieving or saving context. |
161
151
  | Missing startup session ID | Reload the project's memory connection and start a fresh session. Ordinary chat clients use `start_session`; do not invent an ID. |
162
152
  | “Wrong repository” or “different conversation” | Open the intended project and choose its chat in the current session. |
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@tinchu0/knitt",
3
- "version": "0.1.0-beta.4",
3
+ "version": "0.1.0-beta.5",
4
4
  "type": "module",
5
5
  "engines": {
6
6
  "node": ">=24"
@@ -34,11 +34,12 @@
34
34
  "files": [
35
35
  "dist/",
36
36
  "README.md",
37
- "docs/usage.md",
38
- "docs/clients/support-matrix.md",
39
37
  "docs/clients/connector-setup.md",
40
38
  "docs/clients/npm-installation.md",
41
- "LICENSE"
39
+ "LICENSE",
40
+ "docs/clients/local-agent-memory.md",
41
+ "docs/usage.md",
42
+ "docs/clients/support-matrix.md"
42
43
  ],
43
44
  "repository": {
44
45
  "type": "git",