@qvac/core 0.1.6 → 0.2.1
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.
- package/.claude/skills/compaction/SKILL.md +1 -1
- package/.claude/skills/gh-stack/SKILL.md +24 -24
- package/.claude/skills/gh-stack/references/commands.md +2 -2
- package/.claude/skills/js-house-style/SKILL.md +1 -1
- package/.claude/skills/pr-create/SKILL.md +46 -3
- package/.claude/skills/pr-review/SKILL.md +76 -7
- package/CLAUDE.md +3 -0
- package/README.md +10 -5
- package/dist-lib/lib/api/agents.js +3 -3
- package/dist-lib/lib/api/chat-groups.d.ts +1 -1
- package/dist-lib/lib/api/chat-groups.js +5 -3
- package/dist-lib/lib/api/chat.js +2 -2
- package/dist-lib/lib/api/current-mesh.d.ts +3 -2
- package/dist-lib/lib/api/current-mesh.js +4 -3
- package/dist-lib/lib/api/devices.js +1 -0
- package/dist-lib/lib/api/index.js +2 -0
- package/dist-lib/lib/api/members.d.ts +3 -0
- package/dist-lib/lib/api/members.js +23 -0
- package/dist-lib/lib/api/mesh.d.ts +14 -3
- package/dist-lib/lib/api/mesh.js +20 -3
- package/dist-lib/lib/api/watchable.d.ts +1 -1
- package/dist-lib/lib/api/watchable.js +1 -1
- package/dist-lib/lib/core/agent.d.ts +1 -0
- package/dist-lib/lib/core/agent.js +29 -1
- package/dist-lib/lib/core/chat-group.d.ts +4 -0
- package/dist-lib/lib/core/chat-group.js +43 -1
- package/dist-lib/lib/core/chat.d.ts +10 -0
- package/dist-lib/lib/core/chat.js +75 -9
- package/dist-lib/lib/core/contract/index.js +2 -0
- package/dist-lib/lib/core/contract/joined-meshes.d.ts +2 -0
- package/dist-lib/lib/core/contract/joined-meshes.js +41 -0
- package/dist-lib/lib/core/contract/members.js +68 -2
- package/dist-lib/lib/core/contract/writers.js +19 -3
- package/dist-lib/lib/core/departures.d.ts +3 -1
- package/dist-lib/lib/core/departures.js +6 -4
- package/dist-lib/lib/core/device-attestation.d.ts +8 -0
- package/dist-lib/lib/core/device-attestation.js +25 -0
- package/dist-lib/lib/core/device-invites.d.ts +9 -0
- package/dist-lib/lib/core/device-invites.js +40 -0
- package/dist-lib/lib/core/files/index.d.ts +2 -1
- package/dist-lib/lib/core/files/index.js +1 -1
- package/dist-lib/lib/core/files/store/index.d.ts +1 -0
- package/dist-lib/lib/core/files/store/server.d.ts +5 -4
- package/dist-lib/lib/core/files/store/server.js +10 -6
- package/dist-lib/lib/core/helpers/index.d.ts +1 -1
- package/dist-lib/lib/core/hosted-agents.d.ts +3 -1
- package/dist-lib/lib/core/hosted-agents.js +9 -3
- package/dist-lib/lib/core/identity.d.ts +10 -0
- package/dist-lib/lib/core/identity.js +45 -0
- package/dist-lib/lib/core/invite.d.ts +3 -0
- package/dist-lib/lib/core/invite.js +8 -2
- package/dist-lib/lib/core/local/index.d.ts +22 -7
- package/dist-lib/lib/core/local/index.js +202 -66
- package/dist-lib/lib/core/membership.d.ts +8 -2
- package/dist-lib/lib/core/membership.js +33 -9
- package/dist-lib/lib/core/mesh-seed-handoff.d.ts +17 -0
- package/dist-lib/lib/core/mesh-seed-handoff.js +34 -0
- package/dist-lib/lib/core/mesh.d.ts +12 -1
- package/dist-lib/lib/core/mesh.js +36 -7
- package/dist-lib/lib/core/migrations/index.d.ts +3 -1
- package/dist-lib/lib/core/migrations/index.js +2 -2
- package/dist-lib/lib/core/migrations/membership.js +27 -15
- package/dist-lib/lib/core/rank.d.ts +14 -0
- package/dist-lib/lib/core/rank.js +23 -0
- package/dist-lib/lib/core/sync/index.js +6 -0
- package/dist-lib/lib/core.d.ts +91 -13
- package/dist-lib/lib/core.js +1051 -207
- package/dist-lib/schema/build.js +3 -2
- package/dist-lib/schema/engine.js +153 -9
- package/dist-lib/schema/field-order.js +4 -1
- package/dist-lib/schema/local.js +32 -0
- package/dist-lib/schema/qvac.js +45 -6
- package/dist-lib/spec/bind.js +35 -0
- package/dist-lib/spec/calls.js +37 -27
- package/dist-lib/spec/capabilities.d.ts +30 -10
- package/dist-lib/spec/hrpc/hrpc.json +135 -5
- package/dist-lib/spec/hrpc/index.js +130 -9
- package/dist-lib/spec/hrpc/messages.js +408 -14
- package/dist-lib/spec/hyperschema/index.js +408 -14
- package/dist-lib/spec/hyperschema/schema.json +309 -1
- package/dist-lib/spec/hyperschema/types.d.ts +90 -1
- package/dist-lib/spec/local/hyperdb/db.json +46 -1
- package/dist-lib/spec/local/hyperdb/index.js +209 -2
- package/dist-lib/spec/local/hyperdb/messages.js +557 -90
- package/dist-lib/spec/local/hyperschema/index.js +240 -2
- package/dist-lib/spec/local/hyperschema/schema.json +120 -1
- package/dist-lib/spec/local/hyperschema/types.d.ts +33 -1
- package/dist-lib/spec/mesh/hyperdb/db.json +16 -1
- package/dist-lib/spec/mesh/hyperdb/index.js +71 -2
- package/dist-lib/spec/mesh/hyperdb/messages.js +571 -192
- package/dist-lib/spec/mesh/hyperdispatch/dispatch.json +13 -1
- package/dist-lib/spec/mesh/hyperdispatch/index.js +35 -1
- package/dist-lib/spec/mesh/hyperdispatch/messages.js +283 -20
- package/dist-lib/spec/mesh/hyperschema/index.js +283 -20
- package/dist-lib/spec/mesh/hyperschema/schema.json +179 -1
- package/dist-lib/spec/mesh/hyperschema/types.d.ts +45 -1
- package/package.json +4 -4
- package/tui/app.mjs +416 -50
- package/tui/boot.mjs +1 -1
- package/tui/lib/sidebar.mjs +3 -2
|
@@ -9,7 +9,7 @@ This repo owns the **prompt**: what history a run is given, when that history is
|
|
|
9
9
|
folded, and when a chat's cache key has to be thrown away. The **cache itself** —
|
|
10
10
|
the `kvCache` key, the context window, the overflow ladder, `ContextOverflowError`
|
|
11
11
|
— belongs to `@qvac/harness`; read its **kvcache** skill and
|
|
12
|
-
|
|
12
|
+
`@qvac/harness → docs/kvcache-reference.md` before changing anything on this side.
|
|
13
13
|
|
|
14
14
|
## The rule that governs everything here
|
|
15
15
|
|
|
@@ -7,7 +7,7 @@ description: >
|
|
|
7
7
|
branch layers, dependent PRs, or gh stack; or when a stack is checked out.
|
|
8
8
|
metadata:
|
|
9
9
|
author: github
|
|
10
|
-
version:
|
|
10
|
+
version: '0.1.0'
|
|
11
11
|
---
|
|
12
12
|
|
|
13
13
|
# gh-stack
|
|
@@ -45,16 +45,16 @@ Agent harnesses differ, so always pass the flags below instead of relying on tha
|
|
|
45
45
|
`--remote <name>` unless `remote.pushDefault` is configured. `checkout` and `trunk` have no
|
|
46
46
|
`--remote` flag and require the config.
|
|
47
47
|
|
|
48
|
-
| Always run
|
|
49
|
-
|
|
50
|
-
| `gh stack view --json`
|
|
51
|
-
| `gh stack submit --auto`
|
|
52
|
-
| `gh stack merge <target> --yes`
|
|
53
|
-
| `gh stack init <branch>...`
|
|
54
|
-
| `gh stack add <branch>`
|
|
55
|
-
| `gh stack checkout <target>`
|
|
56
|
-
| `gh stack up` / `down` / `top` / `bottom` | `gh stack switch`
|
|
57
|
-
| —
|
|
48
|
+
| Always run | Never run bare | Why |
|
|
49
|
+
| ----------------------------------------- | ------------------- | --------------------------------------------- |
|
|
50
|
+
| `gh stack view --json` | `gh stack view` | opens a TUI under a PTY |
|
|
51
|
+
| `gh stack submit --auto` | `gh stack submit` | prompts for a title per new PR |
|
|
52
|
+
| `gh stack merge <target> --yes` | `gh pr merge` | `gh pr merge` cannot merge a stack |
|
|
53
|
+
| `gh stack init <branch>...` | `gh stack init` | prompts for branch names |
|
|
54
|
+
| `gh stack add <branch>` | `gh stack add` | prompts for a name, and fails even when piped |
|
|
55
|
+
| `gh stack checkout <target>` | `gh stack checkout` | opens a selection menu |
|
|
56
|
+
| `gh stack up` / `down` / `top` / `bottom` | `gh stack switch` | `switch` is menu-only |
|
|
57
|
+
| — | `gh stack modify` | TUI-only, no non-interactive path |
|
|
58
58
|
|
|
59
59
|
- `view --short` is safe in both modes, but it is formatted for humans. Use `--json` to parse.
|
|
60
60
|
- **`checkout <pr>` when a different local stack already covers those branches** cannot be forced.
|
|
@@ -138,19 +138,19 @@ an ancestor of the branch.
|
|
|
138
138
|
|
|
139
139
|
## Exit codes
|
|
140
140
|
|
|
141
|
-
| Code | Meaning
|
|
142
|
-
|
|
143
|
-
| 0
|
|
144
|
-
| 1
|
|
145
|
-
| 2
|
|
146
|
-
| 3
|
|
147
|
-
| 4
|
|
148
|
-
| 5
|
|
149
|
-
| 6
|
|
150
|
-
| 7
|
|
151
|
-
| 8
|
|
152
|
-
| 9
|
|
153
|
-
| 10
|
|
141
|
+
| Code | Meaning | Recovery |
|
|
142
|
+
| ---- | -------------------------- | ---------------------------------------------------------- |
|
|
143
|
+
| 0 | Success | — |
|
|
144
|
+
| 1 | Generic error | Read stderr |
|
|
145
|
+
| 2 | Not in a stack | `gh stack init`, or `gh stack checkout <target>` |
|
|
146
|
+
| 3 | Rebase conflict | Follow the Exit 3 recovery below |
|
|
147
|
+
| 4 | GitHub API failure | Check `gh auth status`, retry |
|
|
148
|
+
| 5 | Invalid arguments | Fix the invocation; see `<command> --help` |
|
|
149
|
+
| 6 | Disambiguation required | Branch is in several stacks; check out a non-shared branch |
|
|
150
|
+
| 7 | Rebase already in progress | `gh stack rebase --continue` or `--abort` |
|
|
151
|
+
| 8 | Stack file locked | Another `gh stack` process is writing; retry after ~5s |
|
|
152
|
+
| 9 | Stacked PRs unavailable | Not enabled on the repository; tell the user |
|
|
153
|
+
| 10 | Modify recovery required | `gh stack modify --abort` |
|
|
154
154
|
|
|
155
155
|
**Exit 3 recovery:**
|
|
156
156
|
|
|
@@ -67,7 +67,7 @@ first non-merged ancestor, then links them into a Stack on GitHub.
|
|
|
67
67
|
the title and its body as the PR body. A branch with multiple commits humanizes the branch name
|
|
68
68
|
(hyphens and underscores become spaces). There is no flag for a custom title or body; use
|
|
69
69
|
`gh pr edit` afterwards.
|
|
70
|
-
- `--open` marks new
|
|
70
|
+
- `--open` marks new _and existing_ PRs ready for review; without it new PRs are drafts.
|
|
71
71
|
- Requires stacked PRs to be enabled on the repository. If not, `submit` exits **9** when
|
|
72
72
|
non-interactive (under a TTY it offers to create ordinary unstacked PRs instead).
|
|
73
73
|
|
|
@@ -172,6 +172,6 @@ Removes the stack **grouping** only. It never deletes pull requests or branches.
|
|
|
172
172
|
|
|
173
173
|
`up`, `down`, `top`, `bottom`, and `trunk` are always non-interactive. `up` and `down` accept a
|
|
174
174
|
count (`gh stack up 3`). Movement clamps at the stack bounds, and merged branches are skipped when
|
|
175
|
-
navigating from an active branch, so `bottom` lands on the lowest
|
|
175
|
+
navigating from an active branch, so `bottom` lands on the lowest _unmerged_ branch.
|
|
176
176
|
|
|
177
177
|
`gh stack switch` is a selection menu with no non-interactive path. Use the commands above instead.
|
|
@@ -667,4 +667,4 @@ This skill governs the shape of the code. The others cover surfaces and workflow
|
|
|
667
667
|
- Prompt folding and KV-cache invalidation → **compaction**.
|
|
668
668
|
- Reproducing a bug on a real phone against a real mesh → **device-mesh-debug**.
|
|
669
669
|
|
|
670
|
-
Commit
|
|
670
|
+
Commit and branch rules live in [`CLAUDE.md`](../../../CLAUDE.md); how a PR itself is shaped and delivered is **pr-create**.
|
|
@@ -61,6 +61,45 @@ Optional, and taken from what the diff actually touches — `lib`, `tui`, `schem
|
|
|
61
61
|
A scope that restates the type (`fix(fix)`) or names the whole repo adds
|
|
62
62
|
nothing; leave it off.
|
|
63
63
|
|
|
64
|
+
## Decision records
|
|
65
|
+
|
|
66
|
+
`docs/decisions/` holds the durable, non-obvious choices — why a boundary is
|
|
67
|
+
where it is, why an approach was rejected. They are reference for a future
|
|
68
|
+
reader, **not rules, and not to be loaded by default**.
|
|
69
|
+
|
|
70
|
+
Add one when this PR settles something a later reader would otherwise have to
|
|
71
|
+
reverse-engineer from the diff: a runtime or storage boundary, a wire-format or
|
|
72
|
+
schema choice, a build or publish constraint, a rejected alternative that will
|
|
73
|
+
look obvious later. Do not add one for a bug fix, a rename, or anything the code
|
|
74
|
+
already says plainly.
|
|
75
|
+
|
|
76
|
+
Copy `docs/decisions/TEMPLATE.md`, give it a `status`, list it once in
|
|
77
|
+
`INDEX.md`, and name it in the PR's Decisions section. `node
|
|
78
|
+
scripts/docs-audit.cjs` checks all of that, and CI runs it.
|
|
79
|
+
|
|
80
|
+
An **active** record may cite only paths that exist here; a path in another
|
|
81
|
+
repository is written `@qvac/harness → lib/x.ts` so the audit treats it as
|
|
82
|
+
context rather than a local file. A superseded record is exempt — it describes
|
|
83
|
+
how things used to be.
|
|
84
|
+
|
|
85
|
+
### One PR, one type
|
|
86
|
+
|
|
87
|
+
The commits carry conventional-commit types, so the mix of types _is_ the scope
|
|
88
|
+
statement. `feat:`, `fix:` and `chore:` on one branch is not a well-rounded
|
|
89
|
+
change, it is three changes sharing a branch, and a reviewer has to hold all
|
|
90
|
+
three while judging any one of them.
|
|
91
|
+
|
|
92
|
+
List them before writing the body:
|
|
93
|
+
|
|
94
|
+
```bash
|
|
95
|
+
git log --format='%s' main..HEAD | grep -oE '^[a-z]+' | sort -u
|
|
96
|
+
```
|
|
97
|
+
|
|
98
|
+
- **One type** is the PR's type.
|
|
99
|
+
- **A dominant type plus its own tests or docs** (`feat` + `test`, `fix` +
|
|
100
|
+
`docs`) is fine; the dominant one wins.
|
|
101
|
+
- **Unrelated types** means split the PR, or stack it.
|
|
102
|
+
|
|
64
103
|
## Small PRs, stacked
|
|
65
104
|
|
|
66
105
|
A PR is read by a human, so it has to fit in one head. Default to one concern.
|
|
@@ -79,8 +118,10 @@ insensitive). Use a neutral name before committing or pushing.
|
|
|
79
118
|
|
|
80
119
|
## Body
|
|
81
120
|
|
|
82
|
-
|
|
83
|
-
|
|
121
|
+
`.github/pull_request_template.md` pre-fills the headings. Keep its shape, fill
|
|
122
|
+
what applies, and delete the sections that would be empty — an absent section
|
|
123
|
+
says more than one saying "n/a". The template's own order is Why, What, Testing,
|
|
124
|
+
Decisions; the expanded form below is what each should contain.
|
|
84
125
|
|
|
85
126
|
```markdown
|
|
86
127
|
## What
|
|
@@ -111,7 +152,9 @@ this is the only warning they get.
|
|
|
111
152
|
|
|
112
153
|
1. Check the branch is not `main` and the name is neutral.
|
|
113
154
|
2. `git log --oneline main..HEAD` — every commit is a conventional commit, and
|
|
114
|
-
each one is a change you would defend on its own.
|
|
155
|
+
each one is a change you would defend on its own. A trail of `wip`,
|
|
156
|
+
`fixup` or `address review` commits is not history; reshape it before
|
|
157
|
+
opening.
|
|
115
158
|
3. `bun run lint` and ``bun run test` (node, bare and addon lanes)` pass locally. CI runs the same lanes; a
|
|
116
159
|
red PR wastes a reviewer's round trip.
|
|
117
160
|
4. Rebase on `main` rather than merging it in. A merge commit in the branch
|
|
@@ -15,6 +15,26 @@ Reviews changes in `@qvac/core`. Two modes.
|
|
|
15
15
|
- **Local mode** (`local`, or "review my changes") — the overview in chat only.
|
|
16
16
|
Posts nothing, anywhere.
|
|
17
17
|
|
|
18
|
+
## Reviewing is read-only
|
|
19
|
+
|
|
20
|
+
This skill never writes to the working tree. Against the user's repo these are
|
|
21
|
+
forbidden, whatever the reason:
|
|
22
|
+
|
|
23
|
+
- `git switch`, `git checkout`, `git reset`, `git restore`, `git clean`
|
|
24
|
+
- `git stash`, in any form
|
|
25
|
+
- `git pull`, `git merge`, `git rebase`, `git cherry-pick`
|
|
26
|
+
- `gh pr checkout`
|
|
27
|
+
- any edit to a file
|
|
28
|
+
|
|
29
|
+
Local mode reads the diff with `git diff`, `git status` and `git ls-files`, and
|
|
30
|
+
nothing else. If the tree is dirty in a way that makes the diff hard to read, say
|
|
31
|
+
so and let the user decide; never tidy it yourself. A review that loses
|
|
32
|
+
uncommitted work is worse than no review.
|
|
33
|
+
|
|
34
|
+
PR mode needs no checkout at all: `gh pr diff` gives the patch, and
|
|
35
|
+
`gh api repos/{owner}/{repo}/contents/{path}?ref={sha}` gives any file at the PR
|
|
36
|
+
head.
|
|
37
|
+
|
|
18
38
|
## Gather
|
|
19
39
|
|
|
20
40
|
PR mode:
|
|
@@ -104,6 +124,32 @@ avoid `codex` / `cursor` / `claude`?
|
|
|
104
124
|
**6. Scope.** Does the PR do one thing? A behaviour change mixed with an
|
|
105
125
|
unrelated rename is two PRs — say so, and say which commit to split out.
|
|
106
126
|
|
|
127
|
+
**7. Decision records.** Does the change contradict something in
|
|
128
|
+
`docs/decisions/`? If it does, the record is updated or superseded in the same
|
|
129
|
+
PR, not left to rot. Does it settle something non-obvious with no record at all?
|
|
130
|
+
Say which, and what the record would have to state.
|
|
131
|
+
|
|
132
|
+
### Do not over-engineer the review
|
|
133
|
+
|
|
134
|
+
The most damaging thing a review can do is talk a good PR into a worse one. AI
|
|
135
|
+
review skews defensive: a guard here, an abstraction there, a layer to absorb a
|
|
136
|
+
hypothetical, each one permanent debt bolted to a problem that never happened.
|
|
137
|
+
That runs directly against the house style, which does not program defensively.
|
|
138
|
+
|
|
139
|
+
It compounds. Successive reviews each add a layer against a different
|
|
140
|
+
speculative case, one review's fix undoes another's, and the code ends up in a
|
|
141
|
+
corner nobody chose.
|
|
142
|
+
|
|
143
|
+
- **Only raise what is wrong now**, or has a concrete path to being wrong.
|
|
144
|
+
"Someone could later..." is not a finding.
|
|
145
|
+
- **Never propose a guard, wrapper, fallback or abstraction** whose only job is
|
|
146
|
+
to make a hypothetical safe. Let caller bugs crash; that is the contract.
|
|
147
|
+
- **Prefer the fix that deletes code.** If your suggestion makes the diff
|
|
148
|
+
bigger, be sure it earns it.
|
|
149
|
+
- **Simplification is a valid finding; speculative hardening is not.**
|
|
150
|
+
- When you cannot tell whether something is real, ask instead of requesting a
|
|
151
|
+
change, and be willing to land zero findings.
|
|
152
|
+
|
|
107
153
|
## Write the findings
|
|
108
154
|
|
|
109
155
|
Each finding: the file and line, what breaks, and the concrete scenario that
|
|
@@ -111,18 +157,41 @@ breaks it. No finding without a failure mode you can state.
|
|
|
111
157
|
|
|
112
158
|
Drop anything you cannot defend as changing the code, the reviewer's decision,
|
|
113
159
|
or a consumer's experience. Style opinions the house style does not back are
|
|
114
|
-
noise. Say so plainly when the diff is clean
|
|
115
|
-
complete review.
|
|
160
|
+
noise. Say so plainly when the diff is clean: "no `[P1]` or `[P2]`
|
|
161
|
+
findings" is a complete review.
|
|
162
|
+
|
|
163
|
+
Lead with the findings, ordered by severity.
|
|
164
|
+
|
|
165
|
+
### Severity tags
|
|
166
|
+
|
|
167
|
+
Tag every finding `[P1]`, `[P2]` or `[P3]`. Use the tag, not a word, so two
|
|
168
|
+
reviews of the same repo rank things the same way.
|
|
169
|
+
|
|
170
|
+
- `[P1]` — almost-certain bug, data corruption, security issue, CI breaker, or a
|
|
171
|
+
break of behaviour a consumer relies on. In the overview, and **proposed inline
|
|
172
|
+
by default**.
|
|
173
|
+
- `[P2]` — likely bug, non-obvious caveat, contract or API mismatch, subtle
|
|
174
|
+
behaviour change, missing test on a risky path. In the overview, and **proposed
|
|
175
|
+
inline by default**.
|
|
176
|
+
- `[P3]` — minor: a stale comment or doc, an ergonomic improvement, an optional
|
|
177
|
+
cleanup. In the overview when material, and **not proposed inline** unless the
|
|
178
|
+
user asks for them.
|
|
179
|
+
|
|
180
|
+
**Never silently put a `[P3]` in the inline payload.** A review that posts ten
|
|
181
|
+
nits inline teaches the author to skim the next one.
|
|
116
182
|
|
|
117
|
-
|
|
183
|
+
**Severity is what the code does today, not what it might do.** A finding whose
|
|
184
|
+
only support is a scenario nobody has hit is not a `[P2]`: either find the path
|
|
185
|
+
that reaches it, or drop it. Zero findings is a legitimate result.
|
|
118
186
|
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
- **Question** — you could not tell from the diff, and the author can.
|
|
187
|
+
If the user says this is a re-review, say explicitly which earlier concerns are
|
|
188
|
+
resolved and which still stand.
|
|
122
189
|
|
|
123
190
|
## Posting (PR mode only)
|
|
124
191
|
|
|
125
|
-
1. Print every proposed comment in chat first: file, line, body.
|
|
192
|
+
1. Print every proposed comment in chat first: file, line, severity, body.
|
|
193
|
+
The default set is the `[P1]` and `[P2]` findings; name any `[P3]` you are
|
|
194
|
+
holding back so the user can pull it in.
|
|
126
195
|
2. Ask the user to confirm the exact set. Wait for a clear yes.
|
|
127
196
|
3. Create the review as **PENDING**, with no event:
|
|
128
197
|
|
package/CLAUDE.md
CHANGED
|
@@ -37,6 +37,9 @@ directly and is Bare-only.
|
|
|
37
37
|
never more. Most code needs none — do not narrate it.
|
|
38
38
|
- **Commits read as if a human wrote them.** No `Co-Authored-By` trailer and no
|
|
39
39
|
AI or agent attribution, in a commit message or a PR.
|
|
40
|
+
- **Durable decisions are in `docs/decisions/`.** Read `INDEX.md` when touching an
|
|
41
|
+
area it lists, and open a record only on a path or keyword match — they are
|
|
42
|
+
reference, not rules. Add one when a change makes a non-obvious lasting choice.
|
|
40
43
|
- **Branch from `main`, and open the PR against `main`.** The one exception is a
|
|
41
44
|
stacked PR, which branches from the PR below it and targets that branch.
|
|
42
45
|
- **Branch names never contain `codex`, `cursor` or `claude`**, in any case.
|
package/README.md
CHANGED
|
@@ -245,11 +245,16 @@ The engine exposes a snapshot chat catalog:
|
|
|
245
245
|
const { chats } = await engine.listChats()
|
|
246
246
|
```
|
|
247
247
|
|
|
248
|
-
It returns complete, active mesh chat rows
|
|
249
|
-
|
|
250
|
-
|
|
251
|
-
|
|
252
|
-
|
|
248
|
+
It returns complete, active mesh chat rows in sidebar order, bottom first
|
|
249
|
+
(clients reverse to render): a chat sits where the user last dragged it
|
|
250
|
+
(`moveChat`) until a chunk lands in it, then most-recently-active wins; `id`
|
|
251
|
+
breaks ties. Groups ride the same frame, top first (`moveChatGroup` orders
|
|
252
|
+
them). Recency is derived from the chunk counter and costs no write, but it is
|
|
253
|
+
part of the row, so `chatsWatch` re-emits on any change to the rendered list:
|
|
254
|
+
create, rename, delete, flag, placement, or a chunk landing. The existing
|
|
255
|
+
replicated chat encoding uses zero as the default for an absent optional
|
|
256
|
+
`deletedAt`, so `deletedAt: 0` is not a representable tombstone and is treated
|
|
257
|
+
as active. Positive tombstone timestamps are excluded.
|
|
253
258
|
`listChats()` itself is a snapshot query. Chat create, update, delete, and watch
|
|
254
259
|
capabilities are available through the typed chat API.
|
|
255
260
|
|
|
@@ -17,10 +17,10 @@ export function createAgentsApi(current, deviceId) {
|
|
|
17
17
|
};
|
|
18
18
|
return {
|
|
19
19
|
createAgent: async (input) => {
|
|
20
|
-
const mesh = await requireMesh(current);
|
|
20
|
+
const mesh = await requireMesh(current, input.meshId);
|
|
21
21
|
return withOrphaned(mesh, await createAgent(mesh, input));
|
|
22
22
|
},
|
|
23
|
-
listAgents: async () => list(await requireMesh(current)),
|
|
23
|
+
listAgents: async (request) => list(await requireMesh(current, request?.meshId)),
|
|
24
24
|
getAgent: async ({ id }) => {
|
|
25
25
|
const mesh = await requireMesh(current);
|
|
26
26
|
return withOrphaned(mesh, await mustGetActiveAgent(mesh, id));
|
|
@@ -33,6 +33,6 @@ export function createAgentsApi(current, deviceId) {
|
|
|
33
33
|
const mesh = await requireMesh(current);
|
|
34
34
|
return withOrphaned(mesh, await deleteAgent(mesh, deviceId, id));
|
|
35
35
|
},
|
|
36
|
-
agentsWatch: watchable('agentsWatch', () => requireMesh(current), (_request, mesh) => list(mesh))
|
|
36
|
+
agentsWatch: watchable('agentsWatch', (request) => requireMesh(current, request?.meshId), (_request, mesh) => list(mesh))
|
|
37
37
|
};
|
|
38
38
|
}
|
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
import type { CapabilityHandlers } from '../../spec/capabilities.d.ts';
|
|
2
2
|
import { type CurrentMesh } from './current-mesh.ts';
|
|
3
|
-
type ChatGroupCapabilities = Pick<CapabilityHandlers, 'createChatGroup' | 'listChatGroups' | 'renameChatGroup' | 'deleteChatGroup' | 'setChatGroup'>;
|
|
3
|
+
type ChatGroupCapabilities = Pick<CapabilityHandlers, 'createChatGroup' | 'listChatGroups' | 'renameChatGroup' | 'deleteChatGroup' | 'setChatGroup' | 'moveChat' | 'moveChatGroup'>;
|
|
4
4
|
export declare function createChatGroupsApi(current: CurrentMesh): ChatGroupCapabilities;
|
|
5
5
|
export {};
|
|
@@ -1,5 +1,5 @@
|
|
|
1
|
-
import { createChatGroup, deleteChatGroup, listChatGroups, renameChatGroup } from "../core/chat-group.js";
|
|
2
|
-
import { setChatGroup } from "../core/chat.js";
|
|
1
|
+
import { createChatGroup, deleteChatGroup, listChatGroups, moveChatGroup, renameChatGroup } from "../core/chat-group.js";
|
|
2
|
+
import { moveChat, setChatGroup } from "../core/chat.js";
|
|
3
3
|
import { requireMesh } from "./current-mesh.js";
|
|
4
4
|
export function createChatGroupsApi(current) {
|
|
5
5
|
return {
|
|
@@ -7,6 +7,8 @@ export function createChatGroupsApi(current) {
|
|
|
7
7
|
listChatGroups: async () => listChatGroups(await requireMesh(current)).then((groups) => ({ groups })),
|
|
8
8
|
renameChatGroup: async ({ id, name }) => renameChatGroup(await requireMesh(current), id, name),
|
|
9
9
|
deleteChatGroup: async ({ id }) => deleteChatGroup(await requireMesh(current), id),
|
|
10
|
-
setChatGroup: async ({ id, groupId }) => setChatGroup(await requireMesh(current), id, groupId)
|
|
10
|
+
setChatGroup: async ({ id, groupId }) => setChatGroup(await requireMesh(current), id, groupId),
|
|
11
|
+
moveChat: async ({ id, groupId, afterId }) => moveChat(await requireMesh(current), id, { groupId, afterId }),
|
|
12
|
+
moveChatGroup: async ({ id, afterId }) => moveChatGroup(await requireMesh(current), id, { afterId })
|
|
11
13
|
};
|
|
12
14
|
}
|
package/dist-lib/lib/api/chat.js
CHANGED
|
@@ -11,13 +11,13 @@ export function createChatApi(current, deviceId) {
|
|
|
11
11
|
const chatActivity = (mesh, chatIds) => listChatActivity(mesh, chatIds ?? undefined).then((activities) => ({ activities }));
|
|
12
12
|
return {
|
|
13
13
|
createChat: async (input) => createChat(await requireMesh(current), input),
|
|
14
|
-
listChats: async () => chatList(await requireMesh(current)),
|
|
14
|
+
listChats: async (request) => chatList(await requireMesh(current, request?.meshId)),
|
|
15
15
|
getChat: async ({ id }) => mustGetActiveChatListing(await requireMesh(current), id),
|
|
16
16
|
renameChat: async ({ id, title }) => renameChat(await requireMesh(current), id, title),
|
|
17
17
|
setChatRagEnabled: async ({ id, enabled }) => setChatRagEnabled(await requireMesh(current), id, enabled ?? false),
|
|
18
18
|
setChatWebSearchEnabled: async ({ id, enabled }) => setChatWebSearchEnabled(await requireMesh(current), id, enabled ?? false),
|
|
19
19
|
deleteChat: async ({ id }) => deleteChat(await requireMesh(current), deviceId, id),
|
|
20
|
-
chatsWatch: watchable('chatsWatch', () => requireMesh(current), (_request, store) => chatList(store)),
|
|
20
|
+
chatsWatch: watchable('chatsWatch', (request) => requireMesh(current, request?.meshId), (_request, store) => chatList(store)),
|
|
21
21
|
listChatActivity: async (input) => chatActivity(await requireMesh(current), input?.chatIds),
|
|
22
22
|
chatActivityWatch: watchable('chatActivityWatch', () => requireMesh(current), (request, store) => chatActivity(store, request?.chatIds)),
|
|
23
23
|
searchChats: async (input) => {
|
|
@@ -1,5 +1,6 @@
|
|
|
1
1
|
import type { Mesh } from '../core/mesh.ts';
|
|
2
|
-
export type CurrentMesh = () => Mesh | null | Promise<Mesh | null>;
|
|
2
|
+
export type CurrentMesh = (meshId?: string | null) => Mesh | null | Promise<Mesh | null>;
|
|
3
3
|
export declare const NO_ACTIVE_MESH = "no active mesh";
|
|
4
|
-
export declare
|
|
4
|
+
export declare const NO_SUCH_MESH = "no such mesh";
|
|
5
|
+
export declare function requireMesh(current: CurrentMesh, meshId?: string | null): Promise<Mesh>;
|
|
5
6
|
export declare function isMeshTransition(err: unknown): boolean;
|
|
@@ -1,8 +1,9 @@
|
|
|
1
1
|
export const NO_ACTIVE_MESH = 'no active mesh';
|
|
2
|
-
export
|
|
3
|
-
|
|
2
|
+
export const NO_SUCH_MESH = 'no such mesh';
|
|
3
|
+
export async function requireMesh(current, meshId) {
|
|
4
|
+
const mesh = await current(meshId);
|
|
4
5
|
if (!mesh)
|
|
5
|
-
throw new Error(NO_ACTIVE_MESH);
|
|
6
|
+
throw new Error(meshId ? `${NO_SUCH_MESH}: ${meshId}` : NO_ACTIVE_MESH);
|
|
6
7
|
if (!mesh.opened)
|
|
7
8
|
await mesh.ready();
|
|
8
9
|
return mesh;
|
|
@@ -17,6 +17,7 @@ import { createFilesApi } from "./files.js";
|
|
|
17
17
|
import { createLogsApi } from "./logs.js";
|
|
18
18
|
import { instrument } from "./instrument.js";
|
|
19
19
|
import { watchable } from "./watchable.js";
|
|
20
|
+
import { createMembersApi } from "./members.js";
|
|
20
21
|
import { createMeshApi } from "./mesh.js";
|
|
21
22
|
import { createNetworkApi } from "./network.js";
|
|
22
23
|
import { createNotificationsApi } from "./notifications.js";
|
|
@@ -64,6 +65,7 @@ export function createApi(deps = {}) {
|
|
|
64
65
|
})
|
|
65
66
|
: null),
|
|
66
67
|
...(deps.meshStatus ? createMeshApi(deps.meshStatus) : null),
|
|
68
|
+
...(mesh ? createMembersApi(mesh) : null),
|
|
67
69
|
...(deps.network ? createNetworkApi(deps.network) : null),
|
|
68
70
|
...(deps.diagnostics ? createDiagnosticsApi(deps.diagnostics) : null),
|
|
69
71
|
...(deps.logs ? createLogsApi(deps.logs) : null),
|
|
@@ -0,0 +1,23 @@
|
|
|
1
|
+
import { requireMesh } from "./current-mesh.js";
|
|
2
|
+
const MEMBERS = '@qvac/members';
|
|
3
|
+
export function createMembersApi(current) {
|
|
4
|
+
return {
|
|
5
|
+
listMembers: async () => {
|
|
6
|
+
const mesh = await requireMesh(current);
|
|
7
|
+
const snap = mesh.view.snapshot();
|
|
8
|
+
try {
|
|
9
|
+
const members = await snap.find(MEMBERS).toArray();
|
|
10
|
+
return {
|
|
11
|
+
members: members.map((member) => ({
|
|
12
|
+
id: member.id,
|
|
13
|
+
name: member.name,
|
|
14
|
+
joinedAt: member.joinedAt
|
|
15
|
+
}))
|
|
16
|
+
};
|
|
17
|
+
}
|
|
18
|
+
finally {
|
|
19
|
+
await snap.close();
|
|
20
|
+
}
|
|
21
|
+
}
|
|
22
|
+
};
|
|
23
|
+
}
|
|
@@ -1,5 +1,10 @@
|
|
|
1
|
-
import type { AssistantMeshStatus } from '../../spec/hyperschema/types.d.ts';
|
|
1
|
+
import type { AssistantMeshList, AssistantMeshStatus } from '../../spec/hyperschema/types.d.ts';
|
|
2
2
|
import type { CapabilityHandlers } from '../../spec/capabilities.d.ts';
|
|
3
|
+
export interface MeshInviteResult {
|
|
4
|
+
readonly invite?: string;
|
|
5
|
+
readonly meshId?: string;
|
|
6
|
+
readonly notice?: string;
|
|
7
|
+
}
|
|
3
8
|
export interface MeshStatusSource {
|
|
4
9
|
watch(listener: () => void): void;
|
|
5
10
|
unwatch(listener: () => void): void;
|
|
@@ -8,6 +13,12 @@ export interface MeshStatusSource {
|
|
|
8
13
|
acknowledgeKicked(): void;
|
|
9
14
|
join(invite: string): Promise<void>;
|
|
10
15
|
cancelJoin(): void;
|
|
11
|
-
invite(): Promise<
|
|
16
|
+
invite(member?: boolean, meshId?: string): Promise<MeshInviteResult>;
|
|
17
|
+
list(): Promise<AssistantMeshList>;
|
|
18
|
+
open(meshId: string): Promise<void>;
|
|
19
|
+
select(meshId: string): Promise<void>;
|
|
20
|
+
close(meshId: string): Promise<void>;
|
|
21
|
+
label(meshId: string, label: string): Promise<void>;
|
|
22
|
+
createRoom(): Promise<string>;
|
|
12
23
|
}
|
|
13
|
-
export declare function createMeshApi(status: MeshStatusSource): Pick<CapabilityHandlers, 'meshStatusWatch' | 'leaveMesh' | 'acknowledgeKicked' | 'joinMesh' | 'cancelMeshJoin' | 'meshInvite'>;
|
|
24
|
+
export declare function createMeshApi(status: MeshStatusSource): Pick<CapabilityHandlers, 'meshStatusWatch' | 'listMeshes' | 'meshesWatch' | 'openMesh' | 'selectMesh' | 'closeMesh' | 'leaveMesh' | 'acknowledgeKicked' | 'joinMesh' | 'cancelMeshJoin' | 'meshInvite' | 'setMeshLabel' | 'createRoom'>;
|
package/dist-lib/lib/api/mesh.js
CHANGED
|
@@ -2,6 +2,20 @@ import { watchable } from "./watchable.js";
|
|
|
2
2
|
export function createMeshApi(status) {
|
|
3
3
|
return {
|
|
4
4
|
meshStatusWatch: watchable('meshStatusWatch', () => status, async () => status.snapshot()),
|
|
5
|
+
listMeshes: () => status.list(),
|
|
6
|
+
meshesWatch: watchable('meshesWatch', () => status, () => status.list()),
|
|
7
|
+
openMesh: async ({ meshId }) => {
|
|
8
|
+
await status.open(meshId);
|
|
9
|
+
return { ok: true };
|
|
10
|
+
},
|
|
11
|
+
selectMesh: async ({ meshId }) => {
|
|
12
|
+
await status.select(meshId);
|
|
13
|
+
return { ok: true };
|
|
14
|
+
},
|
|
15
|
+
closeMesh: async ({ meshId }) => {
|
|
16
|
+
await status.close(meshId);
|
|
17
|
+
return { ok: true };
|
|
18
|
+
},
|
|
5
19
|
leaveMesh: async () => {
|
|
6
20
|
await status.leave();
|
|
7
21
|
return { ok: true };
|
|
@@ -18,8 +32,11 @@ export function createMeshApi(status) {
|
|
|
18
32
|
status.cancelJoin();
|
|
19
33
|
return { ok: true };
|
|
20
34
|
},
|
|
21
|
-
meshInvite: async () => (
|
|
22
|
-
|
|
23
|
-
|
|
35
|
+
meshInvite: async ({ member, meshId }) => status.invite(member ?? false, meshId ?? undefined),
|
|
36
|
+
setMeshLabel: async ({ meshId, label }) => {
|
|
37
|
+
await status.label(meshId, label ?? '');
|
|
38
|
+
return { ok: true };
|
|
39
|
+
},
|
|
40
|
+
createRoom: async () => ({ meshId: await status.createRoom() })
|
|
24
41
|
};
|
|
25
42
|
}
|
|
@@ -8,5 +8,5 @@ interface WatchableStore {
|
|
|
8
8
|
closing?: unknown;
|
|
9
9
|
closed?: boolean;
|
|
10
10
|
}
|
|
11
|
-
export declare function watchable<TRequest, TResult, TStore extends WatchableStore = WatchableStore>(name: string, storeOf: () => TStore | null | Promise<TStore | null>, query: (request: TRequest, store: TStore) => Promise<TResult>): (request: TRequest) => Readable & AsyncIterable<TResult>;
|
|
11
|
+
export declare function watchable<TRequest, TResult, TStore extends WatchableStore = WatchableStore>(name: string, storeOf: (request: TRequest) => TStore | null | Promise<TStore | null>, query: (request: TRequest, store: TStore) => Promise<TResult>): (request: TRequest) => Readable & AsyncIterable<TResult>;
|
|
12
12
|
export {};
|
|
@@ -26,7 +26,7 @@ function isRecord(value) {
|
|
|
26
26
|
}
|
|
27
27
|
export function watchable(name, storeOf, query) {
|
|
28
28
|
return (request) => {
|
|
29
|
-
const resolved = storeOf();
|
|
29
|
+
const resolved = storeOf(request);
|
|
30
30
|
const pending = resolved instanceof Promise ? resolved.catch(noop) : null;
|
|
31
31
|
let store = resolved instanceof Promise ? null : resolved;
|
|
32
32
|
let dirty = true;
|
|
@@ -10,6 +10,7 @@ export declare function liveProviderIds(store: Mesh): Promise<Set<string>>;
|
|
|
10
10
|
export declare function mustGetAgent(store: Mesh, id: string): Promise<QvacAgent>;
|
|
11
11
|
export declare function mustGetActiveAgent(store: Mesh, id: string): Promise<QvacAgent>;
|
|
12
12
|
export declare function createAgent(store: Mesh, input: CreateAgentInput): Promise<QvacAgent>;
|
|
13
|
+
export declare function ownDefaultAgents(store: Mesh): Promise<QvacAgent[]>;
|
|
13
14
|
export declare function updateAgent(store: Mesh, input: UpdateAgentInput): Promise<QvacAgent>;
|
|
14
15
|
export declare function deleteAgent(store: Mesh, deviceId: Buffer | null, id: string): Promise<QvacAgent>;
|
|
15
16
|
export {};
|
|
@@ -82,7 +82,7 @@ export async function createAgent(store, input) {
|
|
|
82
82
|
enabledSkills,
|
|
83
83
|
enabledTools,
|
|
84
84
|
installedSkills: mergeSkills(installedBase, enabledSkills),
|
|
85
|
-
isDefault: false,
|
|
85
|
+
isDefault: input.isDefault ?? false,
|
|
86
86
|
createdAt: now,
|
|
87
87
|
updatedAt: now,
|
|
88
88
|
deletedAt: undefined,
|
|
@@ -102,8 +102,35 @@ export async function createAgent(store, input) {
|
|
|
102
102
|
await store.dispatch('put-agent', { agent });
|
|
103
103
|
return agent;
|
|
104
104
|
}
|
|
105
|
+
export async function ownDefaultAgents(store) {
|
|
106
|
+
const self = store.ourDeviceId;
|
|
107
|
+
const ours = store.ourMemberId;
|
|
108
|
+
const own = [];
|
|
109
|
+
const snap = store.view.snapshot();
|
|
110
|
+
try {
|
|
111
|
+
for await (const agent of snap.find(AGENTS)) {
|
|
112
|
+
if (agent.deletedAt || !agent.isDefault || !agent.providerDeviceId)
|
|
113
|
+
continue;
|
|
114
|
+
const host = await snap.get(DEVICES, { id: agent.providerDeviceId });
|
|
115
|
+
if (!host || host.revoked)
|
|
116
|
+
continue;
|
|
117
|
+
if (self?.equals(host.id) || (ours && host.memberId?.equals(ours)))
|
|
118
|
+
own.push(agent);
|
|
119
|
+
}
|
|
120
|
+
return own;
|
|
121
|
+
}
|
|
122
|
+
finally {
|
|
123
|
+
await snap.close();
|
|
124
|
+
}
|
|
125
|
+
}
|
|
105
126
|
export async function updateAgent(store, input) {
|
|
106
127
|
const current = await mustGetActiveAgent(store, input.id);
|
|
128
|
+
if (input.clearIsDefault && current.isDefault) {
|
|
129
|
+
const own = await ownDefaultAgents(store);
|
|
130
|
+
if (own.length === 1 && own[0].id === current.id) {
|
|
131
|
+
throw new Error('cannot clear the last default agent of this member');
|
|
132
|
+
}
|
|
133
|
+
}
|
|
107
134
|
const enabledSkills = patch(input.enabledSkills, current.enabledSkills);
|
|
108
135
|
const installedBase = patch(input.installedSkills, current.installedSkills);
|
|
109
136
|
const imageBase = input.clearImageSettings
|
|
@@ -119,6 +146,7 @@ export async function updateAgent(store, input) {
|
|
|
119
146
|
enabledSkills,
|
|
120
147
|
enabledTools: patch(input.enabledTools, current.enabledTools),
|
|
121
148
|
installedSkills: mergeSkills(installedBase, enabledSkills),
|
|
149
|
+
isDefault: input.clearIsDefault ? false : input.isDefault || current.isDefault,
|
|
122
150
|
imageModelChoice: patch(input.imageModelChoice, imageBase.imageModelChoice),
|
|
123
151
|
kvCacheK: patch(input.kvCacheK, current.kvCacheK),
|
|
124
152
|
kvCacheV: patch(input.kvCacheV, current.kvCacheV),
|
|
@@ -1,6 +1,7 @@
|
|
|
1
1
|
import type HyperDB from 'hyperdb';
|
|
2
2
|
import type { QvacChatGroup } from '../../spec/mesh/hyperschema/types.d.ts';
|
|
3
3
|
import type { Mesh } from './mesh.ts';
|
|
4
|
+
export declare function groupSortKey(group: QvacChatGroup): number;
|
|
4
5
|
export declare function byGroupOrder(a: QvacChatGroup, b: QvacChatGroup): number;
|
|
5
6
|
export declare function listChatGroupsIn(snap: HyperDB): Promise<QvacChatGroup[]>;
|
|
6
7
|
export declare function listChatGroups(store: Mesh): Promise<QvacChatGroup[]>;
|
|
@@ -11,4 +12,7 @@ export declare function createChatGroup(store: Mesh, input: {
|
|
|
11
12
|
name: string;
|
|
12
13
|
}): Promise<QvacChatGroup>;
|
|
13
14
|
export declare function renameChatGroup(store: Mesh, id: string, name: string): Promise<QvacChatGroup>;
|
|
15
|
+
export declare function moveChatGroup(store: Mesh, id: string, { afterId }: {
|
|
16
|
+
afterId?: string | null;
|
|
17
|
+
}): Promise<QvacChatGroup>;
|
|
14
18
|
export declare function deleteChatGroup(store: Mesh, id: string): Promise<QvacChatGroup>;
|