@qvac/core 0.1.5 → 0.2.0

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 (100) hide show
  1. package/.claude/skills/compaction/SKILL.md +1 -1
  2. package/.claude/skills/gh-stack/SKILL.md +24 -24
  3. package/.claude/skills/gh-stack/references/commands.md +2 -2
  4. package/.claude/skills/js-house-style/SKILL.md +1 -1
  5. package/.claude/skills/pr-create/SKILL.md +46 -3
  6. package/.claude/skills/pr-review/SKILL.md +76 -7
  7. package/CLAUDE.md +3 -0
  8. package/README.md +10 -5
  9. package/dist-lib/lib/api/agents.js +3 -3
  10. package/dist-lib/lib/api/chat-groups.d.ts +1 -1
  11. package/dist-lib/lib/api/chat-groups.js +5 -3
  12. package/dist-lib/lib/api/chat.js +2 -2
  13. package/dist-lib/lib/api/current-mesh.d.ts +3 -2
  14. package/dist-lib/lib/api/current-mesh.js +4 -3
  15. package/dist-lib/lib/api/devices.js +1 -0
  16. package/dist-lib/lib/api/index.js +2 -0
  17. package/dist-lib/lib/api/members.d.ts +3 -0
  18. package/dist-lib/lib/api/members.js +23 -0
  19. package/dist-lib/lib/api/mesh.d.ts +14 -3
  20. package/dist-lib/lib/api/mesh.js +20 -3
  21. package/dist-lib/lib/api/watchable.d.ts +1 -1
  22. package/dist-lib/lib/api/watchable.js +1 -1
  23. package/dist-lib/lib/core/agent.d.ts +1 -0
  24. package/dist-lib/lib/core/agent.js +29 -1
  25. package/dist-lib/lib/core/chat-group.d.ts +4 -0
  26. package/dist-lib/lib/core/chat-group.js +43 -1
  27. package/dist-lib/lib/core/chat.d.ts +10 -0
  28. package/dist-lib/lib/core/chat.js +75 -9
  29. package/dist-lib/lib/core/contract/index.js +2 -0
  30. package/dist-lib/lib/core/contract/joined-meshes.d.ts +2 -0
  31. package/dist-lib/lib/core/contract/joined-meshes.js +41 -0
  32. package/dist-lib/lib/core/contract/members.js +68 -2
  33. package/dist-lib/lib/core/contract/writers.js +19 -3
  34. package/dist-lib/lib/core/departures.d.ts +3 -1
  35. package/dist-lib/lib/core/departures.js +6 -4
  36. package/dist-lib/lib/core/device-attestation.d.ts +8 -0
  37. package/dist-lib/lib/core/device-attestation.js +25 -0
  38. package/dist-lib/lib/core/device-invites.d.ts +9 -0
  39. package/dist-lib/lib/core/device-invites.js +40 -0
  40. package/dist-lib/lib/core/files/index.d.ts +2 -1
  41. package/dist-lib/lib/core/files/index.js +1 -1
  42. package/dist-lib/lib/core/files/store/index.d.ts +1 -0
  43. package/dist-lib/lib/core/files/store/server.d.ts +5 -4
  44. package/dist-lib/lib/core/files/store/server.js +10 -6
  45. package/dist-lib/lib/core/helpers/index.d.ts +1 -1
  46. package/dist-lib/lib/core/hosted-agents.d.ts +3 -1
  47. package/dist-lib/lib/core/hosted-agents.js +9 -3
  48. package/dist-lib/lib/core/identity.d.ts +10 -0
  49. package/dist-lib/lib/core/identity.js +45 -0
  50. package/dist-lib/lib/core/invite.d.ts +3 -0
  51. package/dist-lib/lib/core/invite.js +8 -2
  52. package/dist-lib/lib/core/local/index.d.ts +22 -7
  53. package/dist-lib/lib/core/local/index.js +202 -66
  54. package/dist-lib/lib/core/membership.d.ts +8 -2
  55. package/dist-lib/lib/core/membership.js +33 -9
  56. package/dist-lib/lib/core/mesh-seed-handoff.d.ts +17 -0
  57. package/dist-lib/lib/core/mesh-seed-handoff.js +34 -0
  58. package/dist-lib/lib/core/mesh.d.ts +12 -1
  59. package/dist-lib/lib/core/mesh.js +36 -7
  60. package/dist-lib/lib/core/migrations/index.d.ts +3 -1
  61. package/dist-lib/lib/core/migrations/index.js +2 -2
  62. package/dist-lib/lib/core/migrations/membership.js +27 -15
  63. package/dist-lib/lib/core/rank.d.ts +14 -0
  64. package/dist-lib/lib/core/rank.js +23 -0
  65. package/dist-lib/lib/core/sync/index.js +6 -0
  66. package/dist-lib/lib/core.d.ts +91 -13
  67. package/dist-lib/lib/core.js +1051 -207
  68. package/dist-lib/schema/build.js +3 -2
  69. package/dist-lib/schema/engine.js +153 -9
  70. package/dist-lib/schema/field-order.js +4 -1
  71. package/dist-lib/schema/local.js +32 -0
  72. package/dist-lib/schema/qvac.js +45 -6
  73. package/dist-lib/spec/bind.js +35 -0
  74. package/dist-lib/spec/calls.js +37 -27
  75. package/dist-lib/spec/capabilities.d.ts +30 -10
  76. package/dist-lib/spec/hrpc/hrpc.json +135 -5
  77. package/dist-lib/spec/hrpc/index.js +130 -9
  78. package/dist-lib/spec/hrpc/messages.js +408 -14
  79. package/dist-lib/spec/hyperschema/index.js +408 -14
  80. package/dist-lib/spec/hyperschema/schema.json +309 -1
  81. package/dist-lib/spec/hyperschema/types.d.ts +90 -1
  82. package/dist-lib/spec/local/hyperdb/db.json +46 -1
  83. package/dist-lib/spec/local/hyperdb/index.js +209 -2
  84. package/dist-lib/spec/local/hyperdb/messages.js +557 -90
  85. package/dist-lib/spec/local/hyperschema/index.js +240 -2
  86. package/dist-lib/spec/local/hyperschema/schema.json +120 -1
  87. package/dist-lib/spec/local/hyperschema/types.d.ts +33 -1
  88. package/dist-lib/spec/mesh/hyperdb/db.json +16 -1
  89. package/dist-lib/spec/mesh/hyperdb/index.js +71 -2
  90. package/dist-lib/spec/mesh/hyperdb/messages.js +571 -192
  91. package/dist-lib/spec/mesh/hyperdispatch/dispatch.json +13 -1
  92. package/dist-lib/spec/mesh/hyperdispatch/index.js +35 -1
  93. package/dist-lib/spec/mesh/hyperdispatch/messages.js +283 -20
  94. package/dist-lib/spec/mesh/hyperschema/index.js +283 -20
  95. package/dist-lib/spec/mesh/hyperschema/schema.json +179 -1
  96. package/dist-lib/spec/mesh/hyperschema/types.d.ts +45 -1
  97. package/package.json +5 -5
  98. package/tui/app.mjs +416 -50
  99. package/tui/boot.mjs +1 -1
  100. 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
- `docs/kvcache-reference.md` there before changing anything on this side.
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: "0.1.0"
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 | 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 |
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 | 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` |
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 *and existing* PRs ready for review; without it new PRs are drafts.
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 *unmerged* branch.
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, branch, and PR-delivery workflow lives in [`CLAUDE.md`](../../../CLAUDE.md).
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
- No template is enforced. Use these four headings and drop any that would be
83
- empty — an absent section says more than a section saying "n/a".
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 — "no blocking findings" is a
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
- Distinguish clearly:
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
- - **Blocking** — wrong behaviour, a broken contract, a missing test for a fix.
120
- - **Non-blocking** — a simplification, a naming improvement, a follow-up.
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 ordered by `createdAt`, then `id` —
249
- pure metadata, so `chatsWatch` only re-emits on create, rename, delete, or flag
250
- changes. The existing replicated chat encoding uses zero as the default for an
251
- absent optional `deletedAt`, so `deletedAt: 0` is not a representable tombstone
252
- and is treated as active. Positive tombstone timestamps are excluded.
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
  }
@@ -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 function requireMesh(current: CurrentMesh): Promise<Mesh>;
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 async function requireMesh(current) {
3
- const mesh = await current();
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;
@@ -20,6 +20,7 @@ function toEngineDevice(device, overrides = {}) {
20
20
  appBuild: device.appBuild,
21
21
  appChannel: device.appChannel,
22
22
  platform: device.platform,
23
+ memberId: device.memberId,
23
24
  ...overrides
24
25
  };
25
26
  }
@@ -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,3 @@
1
+ import { type CurrentMesh } from './current-mesh.ts';
2
+ import type { CapabilityHandlers } from '../../spec/capabilities.d.ts';
3
+ export declare function createMembersApi(current: CurrentMesh): Pick<CapabilityHandlers, 'listMembers'>;
@@ -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<string | null>;
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'>;
@@ -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
- invite: (await status.invite()) ?? undefined
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>;