@qvac/core 0.1.3 → 0.1.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.
- package/.claude/skills/asana/SKILL.md +86 -0
- package/.claude/skills/compaction/SKILL.md +127 -0
- package/.claude/skills/device-mesh-debug/SKILL.md +328 -0
- package/.claude/skills/gh-stack/SKILL.md +181 -0
- package/.claude/skills/gh-stack/references/commands.md +177 -0
- package/.claude/skills/gh-stack/references/stack-design.md +97 -0
- package/.claude/skills/gh-stack/references/troubleshooting.md +159 -0
- package/.claude/skills/js-house-style/SKILL.md +670 -0
- package/.claude/skills/pr-create/SKILL.md +137 -0
- package/.claude/skills/pr-review/SKILL.md +147 -0
- package/CLAUDE.md +42 -0
- package/README.md +54 -23
- package/dist-lib/lib/assistant.js +2 -1
- package/dist-lib/lib/core/mesh.d.ts +1 -0
- package/dist-lib/lib/core/mesh.js +25 -1
- package/dist-lib/lib/oauth/common.d.ts +1 -1
- package/dist-lib/lib/oauth/common.js +1 -3
- package/dist-lib/lib/oauth/keys.d.ts +1 -0
- package/dist-lib/lib/oauth/keys.js +3 -0
- package/ducks.png +0 -0
- package/package.json +3 -2
- package/tui/README.md +15 -14
- package/tui/app.mjs +27 -18
- package/tui/boot.mjs +141 -0
- package/tui/index.mjs +34 -617
- package/tui/lib/render.mjs +4 -0
- package/tui/main.mjs +284 -0
|
@@ -0,0 +1,137 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: pr-create
|
|
3
|
+
description: Write the title, body and commits for a pull request in @qvac/core, and decide the conventional-commit type for a change — `fix` is reserved for user-facing defects in a released version. Use when opening a PR here, splitting work into a stack, or choosing between `fix` and `chore`.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# PR creation
|
|
7
|
+
|
|
8
|
+
`@qvac/core` is a published package. The log is the only durable record of intent,
|
|
9
|
+
and for this repo it is also the changelog a consumer reads before upgrading.
|
|
10
|
+
|
|
11
|
+
## Title
|
|
12
|
+
|
|
13
|
+
```
|
|
14
|
+
type(scope): subject
|
|
15
|
+
```
|
|
16
|
+
|
|
17
|
+
Imperative, lowercase after the colon, no trailing period. Scope optional, and
|
|
18
|
+
only when it narrows something real. What and why, not how.
|
|
19
|
+
|
|
20
|
+
```
|
|
21
|
+
feat: publish the sidecar entry, so spawning it needs no bundle
|
|
22
|
+
fix(publish): repoint dynamic imports at dist-lib too
|
|
23
|
+
refactor: own the schema codegen tooling
|
|
24
|
+
chore: regenerate the schema
|
|
25
|
+
```
|
|
26
|
+
|
|
27
|
+
There is no ticket prefix here, and no title validator in CI. That is not
|
|
28
|
+
licence to be loose: nothing will catch a bad title but a reviewer.
|
|
29
|
+
|
|
30
|
+
## Types
|
|
31
|
+
|
|
32
|
+
```
|
|
33
|
+
build chore ci docs style refactor perf test fix feat
|
|
34
|
+
```
|
|
35
|
+
|
|
36
|
+
**`fix` is reserved for a defect a consumer of a released version could hit.**
|
|
37
|
+
It is the line someone reads to decide whether to upgrade, so it claims real
|
|
38
|
+
breakage in something already published.
|
|
39
|
+
|
|
40
|
+
| The change | Type |
|
|
41
|
+
| ----------------------------------------------------------- | -------------------------------------------------- |
|
|
42
|
+
| Breaks a consumer on a published version | `fix` |
|
|
43
|
+
| Repairs code that has never shipped (same release cycle) | `chore` |
|
|
44
|
+
| Repairs the build, the bundle, or what lands in the tarball | `build` or `fix` if a published artifact was wrong |
|
|
45
|
+
| Repairs CI, a workflow, an action pin | `ci` |
|
|
46
|
+
| Repairs or adds a test | `test` |
|
|
47
|
+
| Repairs a lint/type error | `chore` |
|
|
48
|
+
| Pure move or rename, no behaviour change | `refactor` |
|
|
49
|
+
| New capability, new export, new flag | `feat` |
|
|
50
|
+
| README, comments, docs | `docs` |
|
|
51
|
+
|
|
52
|
+
When a repair is on unreleased code, check the last release tag: if the bug was
|
|
53
|
+
never in a published version, it is `chore`, not `fix`.
|
|
54
|
+
|
|
55
|
+
Never relabel a real defect as `chore` to make the log quieter, and never
|
|
56
|
+
inflate a cleanup into `fix` to make it look urgent.
|
|
57
|
+
|
|
58
|
+
## Scopes
|
|
59
|
+
|
|
60
|
+
Optional, and taken from what the diff actually touches — `lib`, `tui`, `schema`, `spec`, `scripts`, `test`, `ci`, `publish`, or a domain name (`mesh`, `sync`, `assistant`, `storage`).
|
|
61
|
+
A scope that restates the type (`fix(fix)`) or names the whole repo adds
|
|
62
|
+
nothing; leave it off.
|
|
63
|
+
|
|
64
|
+
## Small PRs, stacked
|
|
65
|
+
|
|
66
|
+
A PR is read by a human, so it has to fit in one head. Default to one concern.
|
|
67
|
+
When a change decomposes into dependent steps, do not grow one PR to fit them —
|
|
68
|
+
stack them, so each step is reviewable alone and lands in order.
|
|
69
|
+
|
|
70
|
+
- A large refactor belongs on a `refactor/...` branch with `refactor:` commits.
|
|
71
|
+
- **Refactor commits never live inside a non-refactor branch.** A `feat/` branch
|
|
72
|
+
that also reshuffles unrelated code is two PRs. Behaviour changes and pure
|
|
73
|
+
moves are reviewed differently, and mixing them hides both.
|
|
74
|
+
- A pure rename or move lands _before_ the change that depends on it, as its own
|
|
75
|
+
commit or its own PR in the stack.
|
|
76
|
+
|
|
77
|
+
Branch names must never contain `codex`, `cursor`, or `claude` (case
|
|
78
|
+
insensitive). Use a neutral name before committing or pushing.
|
|
79
|
+
|
|
80
|
+
## Body
|
|
81
|
+
|
|
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".
|
|
84
|
+
|
|
85
|
+
```markdown
|
|
86
|
+
## What
|
|
87
|
+
|
|
88
|
+
One paragraph. The change, in the reviewer's terms.
|
|
89
|
+
|
|
90
|
+
## Why
|
|
91
|
+
|
|
92
|
+
The problem this solves, or the decision it implements. Link the issue,
|
|
93
|
+
PR, or upstream change that forced it.
|
|
94
|
+
|
|
95
|
+
## How
|
|
96
|
+
|
|
97
|
+
Only the parts a reader would not infer from the diff: the seam that moved,
|
|
98
|
+
the invariant being preserved, the thing that looks wrong but isn't.
|
|
99
|
+
|
|
100
|
+
## Testing
|
|
101
|
+
|
|
102
|
+
What you ran, and what it proved. ``bun run test` (node, bare and addon lanes)` at minimum.
|
|
103
|
+
Say plainly when something could not be tested locally and why.
|
|
104
|
+
```
|
|
105
|
+
|
|
106
|
+
For a **breaking change**, say so in the body under its own `## Breaking`
|
|
107
|
+
heading, with the migration a consumer has to perform. Published package —
|
|
108
|
+
this is the only warning they get.
|
|
109
|
+
|
|
110
|
+
## Before opening
|
|
111
|
+
|
|
112
|
+
1. Check the branch is not `main` and the name is neutral.
|
|
113
|
+
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.
|
|
115
|
+
3. `bun run lint` and ``bun run test` (node, bare and addon lanes)` pass locally. CI runs the same lanes; a
|
|
116
|
+
red PR wastes a reviewer's round trip.
|
|
117
|
+
4. Rebase on `main` rather than merging it in. A merge commit in the branch
|
|
118
|
+
makes the diff unreadable.
|
|
119
|
+
5. Open as a **draft** unless you are asking for review right now.
|
|
120
|
+
|
|
121
|
+
```bash
|
|
122
|
+
gh pr create --repo tetherto/qvac-core --draft --title "type(scope): subject" --body-file <path>
|
|
123
|
+
```
|
|
124
|
+
|
|
125
|
+
Never push to `main`, never force-push a branch someone else is reviewing, and
|
|
126
|
+
never open a PR that carries commits you did not write without saying so.
|
|
127
|
+
|
|
128
|
+
## Version bumps
|
|
129
|
+
|
|
130
|
+
Release PRs in this repo are titled by version alone (`0.2.4 (#32)`,
|
|
131
|
+
`release/0.1.4 (#40)`). They carry the version bump and nothing else — do not
|
|
132
|
+
fold a bump into a feature PR, and do not fold a feature into a bump.
|
|
133
|
+
|
|
134
|
+
## Sibling skills
|
|
135
|
+
|
|
136
|
+
- Reviewing a PR or a local diff → **pr-review**.
|
|
137
|
+
- How the code itself should be shaped → **js-house-style**.
|
|
@@ -0,0 +1,147 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: pr-review
|
|
3
|
+
description: Deep-dive review of a pull request in @qvac/core, or of local uncommitted/branch changes when invoked with `local`. Checks CI, the commit type and title, code quality against the house style, contract and API mismatches, and missing tests. In PR mode it creates PENDING inline comments only after the user confirms them, and never submits the review event. In local mode it prints findings in chat and posts nothing. Use when reviewing a PR, given a PR link, or asked to review the working tree or current branch.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# PR review
|
|
7
|
+
|
|
8
|
+
Reviews changes in `@qvac/core`. Two modes.
|
|
9
|
+
|
|
10
|
+
- **PR mode** (a PR number or URL) — a short overview in chat, then a **pending**
|
|
11
|
+
GitHub review of per-file inline comments. The pending review is created only
|
|
12
|
+
after the user confirms the exact set of comments. **Never submit the review
|
|
13
|
+
event** (`COMMENT`, `REQUEST_CHANGES`, `APPROVE`) — that is the user's call,
|
|
14
|
+
from the GitHub UI.
|
|
15
|
+
- **Local mode** (`local`, or "review my changes") — the overview in chat only.
|
|
16
|
+
Posts nothing, anywhere.
|
|
17
|
+
|
|
18
|
+
## Gather
|
|
19
|
+
|
|
20
|
+
PR mode:
|
|
21
|
+
|
|
22
|
+
```bash
|
|
23
|
+
gh pr view <num> --repo tetherto/qvac-core \
|
|
24
|
+
--json title,body,author,headRefName,headRefOid,baseRefName,files,additions,deletions,state,isDraft,mergeable
|
|
25
|
+
gh pr diff <num> --repo tetherto/qvac-core --patch > /tmp/pr-<num>.patch
|
|
26
|
+
```
|
|
27
|
+
|
|
28
|
+
Read the patch from the file with Read/Grep rather than re-running `gh` — it is
|
|
29
|
+
the same bytes every time and the file is greppable.
|
|
30
|
+
|
|
31
|
+
Local mode:
|
|
32
|
+
|
|
33
|
+
```bash
|
|
34
|
+
git diff --staged > /tmp/local-staged.patch
|
|
35
|
+
git diff > /tmp/local-unstaged.patch
|
|
36
|
+
git status --porcelain=v1
|
|
37
|
+
git ls-files --others --exclude-standard # untracked, easy to miss
|
|
38
|
+
```
|
|
39
|
+
|
|
40
|
+
For a branch rather than a working tree: `git diff main...HEAD` (three dots —
|
|
41
|
+
the merge base, not the tip).
|
|
42
|
+
|
|
43
|
+
## CI
|
|
44
|
+
|
|
45
|
+
One workflow gates this repo: **Integrate** (`.github/workflows/ci.yml`), a
|
|
46
|
+
single `Lint & Tests` job. `publish.yml` runs on release, not on PRs.
|
|
47
|
+
|
|
48
|
+
Its steps are each a separate way to fail, and the last three catch what a
|
|
49
|
+
local `bun run test` does not:
|
|
50
|
+
|
|
51
|
+
| Step | Command | Fails when |
|
|
52
|
+
| ------------------------ | ---------------------- | --------------------------------------------------------------------------------------------- |
|
|
53
|
+
| Lint | `bun run lint` | prettier, lunte or `tsc --noEmit` |
|
|
54
|
+
| Schema is regenerated | `bun run build:schema` | `spec/` is dirty after codegen — someone hand-edited it, or forgot to commit the regeneration |
|
|
55
|
+
| Tests | `bun run test` | the node, bare and addon lanes |
|
|
56
|
+
| Library surface compiles | `bun run build:lib` | the compiled export surface breaks |
|
|
57
|
+
|
|
58
|
+
A PR that touches `schema/` and leaves `spec/` stale is the most common red
|
|
59
|
+
here, and it looks nothing like a test failure.
|
|
60
|
+
|
|
61
|
+
```bash
|
|
62
|
+
gh pr checks <num> --repo tetherto/qvac-core
|
|
63
|
+
gh run view --repo tetherto/qvac-core --log-failed --job <id> > /tmp/pr-<num>-<id>.log
|
|
64
|
+
```
|
|
65
|
+
|
|
66
|
+
A red `Integrate` is a blocking finding on its own. Read the failing job's log
|
|
67
|
+
before writing a single line of review — half of what looks like a design
|
|
68
|
+
problem is a lint rule.
|
|
69
|
+
|
|
70
|
+
## What to check, in order
|
|
71
|
+
|
|
72
|
+
Stop at the first tier that produces findings worth the author's time; a review
|
|
73
|
+
that lists twelve nits under a broken contract has buried the real thing.
|
|
74
|
+
|
|
75
|
+
**1. Correctness.** Does it do what the title claims? Trace the changed path
|
|
76
|
+
end to end, including the error path. Look for: a promise not awaited, a
|
|
77
|
+
listener never removed, a resource opened on one path and closed on another, an
|
|
78
|
+
error swallowed into a default.
|
|
79
|
+
|
|
80
|
+
**2. Contract and API.** This is a published package, so an exported signature
|
|
81
|
+
is a promise to a consumer.
|
|
82
|
+
|
|
83
|
+
- Anything added to or changed in the export map, `index.ts`, `types/`, or
|
|
84
|
+
`package.json#exports` — is it intentional, and is it a breaking change?
|
|
85
|
+
- `schema/` or `spec/` changes: is the wire format still compatible, and was the
|
|
86
|
+
baseline regenerated (`bun run build:schema`) rather than hand-edited?
|
|
87
|
+
- Does the change match its own type declarations, and do callers in this repo
|
|
88
|
+
still typecheck?
|
|
89
|
+
|
|
90
|
+
**3. House style.** Run the changed files against **js-house-style** — that
|
|
91
|
+
document, not your own taste. Layering, composition on primitives, module size
|
|
92
|
+
and shape, no defensive programming, comment density.
|
|
93
|
+
|
|
94
|
+
**4. Tests.** A behaviour change with no test is a finding. Name the missing
|
|
95
|
+
case rather than asking for "more tests": the tests live under `test/`, run on
|
|
96
|
+
both the node and bare lanes, and a fix without a regression guard will come
|
|
97
|
+
back.
|
|
98
|
+
|
|
99
|
+
**5. Commit type and title.** Per **pr-create**: is this really a `fix` (a
|
|
100
|
+
defect a consumer of a released version could hit), or is it `chore` on code
|
|
101
|
+
that never shipped? Is the title imperative and specific? Does the branch name
|
|
102
|
+
avoid `codex` / `cursor` / `claude`?
|
|
103
|
+
|
|
104
|
+
**6. Scope.** Does the PR do one thing? A behaviour change mixed with an
|
|
105
|
+
unrelated rename is two PRs — say so, and say which commit to split out.
|
|
106
|
+
|
|
107
|
+
## Write the findings
|
|
108
|
+
|
|
109
|
+
Each finding: the file and line, what breaks, and the concrete scenario that
|
|
110
|
+
breaks it. No finding without a failure mode you can state.
|
|
111
|
+
|
|
112
|
+
Drop anything you cannot defend as changing the code, the reviewer's decision,
|
|
113
|
+
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.
|
|
116
|
+
|
|
117
|
+
Distinguish clearly:
|
|
118
|
+
|
|
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.
|
|
122
|
+
|
|
123
|
+
## Posting (PR mode only)
|
|
124
|
+
|
|
125
|
+
1. Print every proposed comment in chat first: file, line, body.
|
|
126
|
+
2. Ask the user to confirm the exact set. Wait for a clear yes.
|
|
127
|
+
3. Create the review as **PENDING**, with no event:
|
|
128
|
+
|
|
129
|
+
```bash
|
|
130
|
+
gh api repos/tetherto/qvac-core/pulls/<num>/reviews \
|
|
131
|
+
--method POST --input /tmp/review.json
|
|
132
|
+
```
|
|
133
|
+
|
|
134
|
+
where `review.json` has `commit_id` (the `headRefOid` you fetched) and a
|
|
135
|
+
`comments` array of `{path, line, side, body}`, and **no `event` field**. A body
|
|
136
|
+
with `event` submits the review; leaving it out is what makes it pending.
|
|
137
|
+
|
|
138
|
+
4. Hand the user the link and stop:
|
|
139
|
+
`https://github.com/tetherto/qvac-core/pull/<num>#pullrequestreview-<id>`
|
|
140
|
+
|
|
141
|
+
If a line is not in the diff, GitHub rejects the comment. Anchor to a line the
|
|
142
|
+
patch actually touches, or raise it in the chat overview instead.
|
|
143
|
+
|
|
144
|
+
## Sibling skills
|
|
145
|
+
|
|
146
|
+
- Writing the PR being reviewed → **pr-create**.
|
|
147
|
+
- The rules tier 3 reviews against → **js-house-style**.
|
package/CLAUDE.md
ADDED
|
@@ -0,0 +1,42 @@
|
|
|
1
|
+
# @qvac/core
|
|
2
|
+
|
|
3
|
+
A P2P, multi-device AI workbench core. Three pieces, one duplex stream:
|
|
4
|
+
|
|
5
|
+
- **`Core`** — the state authority. Owns the replicated mesh and the device-local
|
|
6
|
+
store, serves every capability over hrpc. It contains **no AI whatsoever**.
|
|
7
|
+
- **`Client`** — a thin proxy whose methods are generated from the schema.
|
|
8
|
+
Everything an app or assistant does goes through it.
|
|
9
|
+
- **`QvacAssistant`** — the execution host. Owns the AI harness and drives it
|
|
10
|
+
through the Client's capability surface, like any other client. **The only
|
|
11
|
+
place inference happens.**
|
|
12
|
+
|
|
13
|
+
The library runs on both Bare and Node, and both test lanes are real — anything
|
|
14
|
+
that works on only one is a bug. `tui/` is the exception: it imports `bare-tui`
|
|
15
|
+
directly and is Bare-only.
|
|
16
|
+
|
|
17
|
+
## Durable invariants
|
|
18
|
+
|
|
19
|
+
- **Those three roles do not blur.** AI does not move into `Core`; state
|
|
20
|
+
authority does not move out of it; nothing reaches around `Client`.
|
|
21
|
+
- **`spec/` is generated** by `bun run build:schema`. Never hand-edit it; CI fails
|
|
22
|
+
when it is dirty after regeneration.
|
|
23
|
+
- **Autobee is the source of truth** for replicated state; anything else is a
|
|
24
|
+
materialized view.
|
|
25
|
+
- **History is never evicted to make a prompt fit.** Compaction is the one
|
|
26
|
+
sanctioned exception and it already exists.
|
|
27
|
+
|
|
28
|
+
## Working here
|
|
29
|
+
|
|
30
|
+
- `bun run lint` (prettier + lunte + tsc) and `bun run test` (node, bare and
|
|
31
|
+
addon lanes) before considering a change done.
|
|
32
|
+
- Tests live in `test/` and run under brittle. A non-trivial change ships tests.
|
|
33
|
+
|
|
34
|
+
## Always
|
|
35
|
+
|
|
36
|
+
- **Comment only what the code cannot say.** Why, not what. One or two lines,
|
|
37
|
+
never more. Most code needs none — do not narrate it.
|
|
38
|
+
- **Commits read as if a human wrote them.** No `Co-Authored-By` trailer and no
|
|
39
|
+
AI or agent attribution, in a commit message or a PR.
|
|
40
|
+
- **Branch from `main`, and open the PR against `main`.** The one exception is a
|
|
41
|
+
stacked PR, which branches from the PR below it and targets that branch.
|
|
42
|
+
- **Branch names never contain `codex`, `cursor` or `claude`**, in any case.
|
package/README.md
CHANGED
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
<p align="center">
|
|
2
|
-
<img src="
|
|
2
|
+
<img src="ducks.png" alt="" width="200">
|
|
3
3
|
</p>
|
|
4
4
|
|
|
5
5
|
<h1 align="center">@qvac/core</h1>
|
|
@@ -21,7 +21,8 @@
|
|
|
21
21
|
<a href="#one-shot-tasks">Tasks</a> ·
|
|
22
22
|
<a href="#rendering-the-chunk-stream-any-ui">Chunk stream</a> ·
|
|
23
23
|
<a href="#harness-event-reference">Events</a> ·
|
|
24
|
-
<a href="#development">Development</a>
|
|
24
|
+
<a href="#development">Development</a> ·
|
|
25
|
+
<a href="#the-duck-tui">duck TUI</a>
|
|
25
26
|
</p>
|
|
26
27
|
|
|
27
28
|
A P2P, multi-device AI workbench core. Three pieces, one duplex stream:
|
|
@@ -41,6 +42,26 @@ A P2P, multi-device AI workbench core. Three pieces, one duplex stream:
|
|
|
41
42
|
└────────────────────────────────────────────┘ └────────────────────────────┘
|
|
42
43
|
```
|
|
43
44
|
|
|
45
|
+
## Install
|
|
46
|
+
|
|
47
|
+
`@qvac/core` is two things: a **library** you embed, and **`duck`**, a terminal
|
|
48
|
+
app that runs the whole stack on top of it.
|
|
49
|
+
|
|
50
|
+
```sh
|
|
51
|
+
npm i @qvac/core # the library
|
|
52
|
+
npm i -g @qvac/core # duck, on your PATH
|
|
53
|
+
```
|
|
54
|
+
|
|
55
|
+
```sh
|
|
56
|
+
duck # the TUI
|
|
57
|
+
duck --help
|
|
58
|
+
```
|
|
59
|
+
|
|
60
|
+
The library is the three pieces above — start at
|
|
61
|
+
[Integrating a harness](#integrating-a-harness). `duck` is the fastest way to
|
|
62
|
+
watch them work, and what the examples here drive; it has its own section at
|
|
63
|
+
[The duck TUI](#the-duck-tui).
|
|
64
|
+
|
|
44
65
|
## Integrating a harness
|
|
45
66
|
|
|
46
67
|
A harness is one method. Implement `completion(context)` as an async iterable
|
|
@@ -613,8 +634,8 @@ skill's `allow_list` binds that key to the URL prefixes it may be sent to.
|
|
|
613
634
|
Credentials are **per agent** (stored at `skills.<agentId>.<key>`), so two
|
|
614
635
|
agents never share one connection.
|
|
615
636
|
|
|
616
|
-
Fill a key with a slash command in the running TUI
|
|
617
|
-
|
|
637
|
+
Fill a key with a slash command in the running TUI — see
|
|
638
|
+
[The duck TUI](#the-duck-tui):
|
|
618
639
|
|
|
619
640
|
- `/connect google` · `/connect spotify` · `/connect asana` · `/connect notion` — browser OAuth;
|
|
620
641
|
the example stores the token and refreshes it on use.
|
|
@@ -641,19 +662,43 @@ Then ask the assistant anything Notion — it loads the `notion` skill and calls
|
|
|
641
662
|
`mcp_call` itself; the session handshake and auth are handled for you. A `401`
|
|
642
663
|
in a tool result means the token expired — run `/connect notion` again.
|
|
643
664
|
|
|
665
|
+
## Development
|
|
666
|
+
|
|
644
667
|
```sh
|
|
645
|
-
|
|
668
|
+
npm test # node + bare suites
|
|
669
|
+
npm run build:schema # regenerate spec/ from schema/ (bare)
|
|
670
|
+
bun run duck # run the TUI (no build step)
|
|
646
671
|
```
|
|
647
672
|
|
|
648
|
-
|
|
649
|
-
|
|
650
|
-
|
|
651
|
-
|
|
673
|
+
The TUI lives in [`tui/`](tui/README.md) and installs as the `duck` command.
|
|
674
|
+
Schema changes go in `schema/*.ts` (builders) — `spec/` is generated. The
|
|
675
|
+
mesh schema (`spec/mesh/*`) is the replicated protocol: every device in a
|
|
676
|
+
mesh must run the same generated spec. See `MIGRATION.md` for the audited
|
|
677
|
+
feature checklist vs core v1.
|
|
678
|
+
|
|
679
|
+
### Office documents
|
|
680
|
+
|
|
681
|
+
Word-processor documents (`.docx`, `.doc`, `.docm`, `.dot`, `.dotx`, `.odt`,
|
|
682
|
+
`.fodt`, `.ott`) decode through an engine the host supplies rather than a
|
|
683
|
+
declared dependency: the package pulls all thirteen platform prebuilds at
|
|
684
|
+
~350MB each, so declaring it would cost every install 4.3GB. In this repo,
|
|
685
|
+
fetch the one for this machine before exercising `/knowledge add report.docx`:
|
|
652
686
|
|
|
653
687
|
```sh
|
|
654
688
|
bun run engine:collabora
|
|
655
689
|
```
|
|
656
690
|
|
|
691
|
+
**There is no equivalent for an installed `duck`.** Nothing fetches the engine
|
|
692
|
+
for you, so those formats fail to index outside this repo, even though
|
|
693
|
+
`/knowledge add` accepts them. Everything else it accepts — `.pdf`, `.txt`,
|
|
694
|
+
`.md`, `.rtf`, `.html`, `.csv`, `.json` and the rest — works from any install.
|
|
695
|
+
|
|
696
|
+
## The duck TUI
|
|
697
|
+
|
|
698
|
+
`duck` brings the whole stack up — Core, the assistant, your harness — behind a
|
|
699
|
+
terminal UI. It is on your PATH after `npm i -g @qvac/core`, or `bun run duck`
|
|
700
|
+
in this repo. `duck --help` lists the flags.
|
|
701
|
+
|
|
657
702
|
The TUI copies its mesh invite to the clipboard on ctrl+y. On a second machine
|
|
658
703
|
(or a second terminal), start `duck` and join from inside it:
|
|
659
704
|
|
|
@@ -678,17 +723,3 @@ The joiner brings no models and no agents — it finds the mesh's seeded agent,
|
|
|
678
723
|
asks, and the _creator's_ device runs the model while both sides watch the
|
|
679
724
|
same replicated stream: load progress, thinking, tokens, tool approvals
|
|
680
725
|
(either side can answer), and final stats.
|
|
681
|
-
|
|
682
|
-
## Development
|
|
683
|
-
|
|
684
|
-
```sh
|
|
685
|
-
npm test # node + bare suites
|
|
686
|
-
npm run build:schema # regenerate spec/ from schema/ (bare)
|
|
687
|
-
bun run duck # run the TUI (no build step)
|
|
688
|
-
```
|
|
689
|
-
|
|
690
|
-
The TUI lives in [`tui/`](tui/README.md) and installs as the `duck` command.
|
|
691
|
-
Schema changes go in `schema/*.ts` (builders) — `spec/` is generated. The
|
|
692
|
-
mesh schema (`spec/mesh/*`) is the replicated protocol: every device in a
|
|
693
|
-
mesh must run the same generated spec. See `MIGRATION.md` for the audited
|
|
694
|
-
feature checklist vs core v1.
|
|
@@ -421,7 +421,8 @@ export function historyFromChunks(chunks, stale = {}) {
|
|
|
421
421
|
const loaded = chunk.toolResult.result?.name;
|
|
422
422
|
if (typeof loaded === 'string' && !replayedSkills.has(loaded)) {
|
|
423
423
|
replayedSkills.add(loaded);
|
|
424
|
-
|
|
424
|
+
const at = history.indexOf(anchor(chunk.runId)) + 1;
|
|
425
|
+
history.splice(at, 0, { role: 'tool', content: skillLoadedTurn(loaded) });
|
|
425
426
|
}
|
|
426
427
|
continue;
|
|
427
428
|
}
|
|
@@ -133,6 +133,7 @@ export declare class Mesh extends ReadyResource {
|
|
|
133
133
|
_autobeeIsTrusted(key: Buffer, reference: MeshView): Promise<boolean>;
|
|
134
134
|
_autobeeMostRecentTrusted(target: MeshView, reference: MeshView | null): Promise<AutobeeOplogRef | null>;
|
|
135
135
|
_autobeeOpen(bee: unknown): MeshView;
|
|
136
|
+
_autobeeWarmup(view: MeshView): Promise<void>;
|
|
136
137
|
_autobeeApply(nodes: ReadonlyArray<AutobeeNode>, view: MeshView, host: AutobeeHost): Promise<void>;
|
|
137
138
|
private _halt;
|
|
138
139
|
_autobeeUpdate(view: MeshView, changes: AutobeeChanges): Promise<void>;
|
|
@@ -17,8 +17,14 @@ import { liveDeviceForWriter } from "./contract/activity.js";
|
|
|
17
17
|
import { registerRoutes } from "./contract/index.js";
|
|
18
18
|
import { createSyncActivity } from "./sync-status.js";
|
|
19
19
|
import { buildHealthAssistant } from "./health-assistant.js";
|
|
20
|
-
const [MESH_KEYPAIR, MESH_ENCRYPTION, MESH_DEVICE] = crypto.namespace('
|
|
20
|
+
const [MESH_KEYPAIR, MESH_ENCRYPTION, MESH_DEVICE] = crypto.namespace('qvac-assistant/mesh', 3);
|
|
21
21
|
const LIVE_WRITERS_BY_MOST_RECENT = '@qvac/live-writers-by-most-recent';
|
|
22
|
+
const WARMUP_COLLECTIONS = [
|
|
23
|
+
'@qvac/devices',
|
|
24
|
+
'@qvac/active-agents',
|
|
25
|
+
'@qvac/members',
|
|
26
|
+
'@qvac/active-chats'
|
|
27
|
+
];
|
|
22
28
|
export async function isOurTrustedWriter(snap, writerKey, ourMemberId) {
|
|
23
29
|
const device = await liveDeviceForWriter(snap, writerKey);
|
|
24
30
|
if (!device)
|
|
@@ -184,6 +190,7 @@ export class Mesh extends ReadyResource {
|
|
|
184
190
|
open: this._autobeeOpen.bind(this),
|
|
185
191
|
apply: this._autobeeApply.bind(this),
|
|
186
192
|
update: this._autobeeUpdate.bind(this),
|
|
193
|
+
warmup: this._autobeeWarmup.bind(this),
|
|
187
194
|
isTrusted: this._autobeeIsTrusted.bind(this),
|
|
188
195
|
mostRecentTrusted: this._autobeeMostRecentTrusted.bind(this),
|
|
189
196
|
keyPair: writerKeyPair,
|
|
@@ -408,6 +415,17 @@ export class Mesh extends ReadyResource {
|
|
|
408
415
|
const db = HyperDB.bee2(bee, MeshDefinition, { autoUpdate: true });
|
|
409
416
|
return { db };
|
|
410
417
|
}
|
|
418
|
+
async _autobeeWarmup(view) {
|
|
419
|
+
try {
|
|
420
|
+
const counts = await Promise.all(WARMUP_COLLECTIONS.map((collection) => drain(view.db.find(collection))));
|
|
421
|
+
const warmed = counts.reduce((total, count) => total + count, 0);
|
|
422
|
+
this._log?.info(this._scope, 'warmed candidate view', { warmed });
|
|
423
|
+
this.emit('warmup', { warmed });
|
|
424
|
+
}
|
|
425
|
+
catch (err) {
|
|
426
|
+
this._log?.warn(this._scope, 'warmup failed', err);
|
|
427
|
+
}
|
|
428
|
+
}
|
|
411
429
|
async _autobeeApply(nodes, view, host) {
|
|
412
430
|
const tx = view.db.transaction();
|
|
413
431
|
try {
|
|
@@ -497,6 +515,12 @@ export class MeshBatch {
|
|
|
497
515
|
}
|
|
498
516
|
}
|
|
499
517
|
function noop() { }
|
|
518
|
+
async function drain(stream) {
|
|
519
|
+
let count = 0;
|
|
520
|
+
for await (const _row of stream)
|
|
521
|
+
count++;
|
|
522
|
+
return count;
|
|
523
|
+
}
|
|
500
524
|
const NEWER_BUILD_MESSAGES = new Set(['Unsupported version', 'Unknown enum', 'Out of bounds']);
|
|
501
525
|
function isInterrupt(err) {
|
|
502
526
|
return err instanceof Error && err.message === 'Apply interrupted';
|
|
@@ -1,4 +1,5 @@
|
|
|
1
1
|
import { Buffer } from 'buffer';
|
|
2
|
+
export { scopedKey } from './keys.ts';
|
|
2
3
|
export declare const CALLBACK_PATH = "/callback";
|
|
3
4
|
export declare const DEFAULT_TIMEOUT_MS = 120000;
|
|
4
5
|
export declare const REFRESH_SKEW_MS = 60000;
|
|
@@ -33,6 +34,5 @@ export declare function createPkce(randomBytes?: RandomBytes): {
|
|
|
33
34
|
challenge: string;
|
|
34
35
|
method: "S256";
|
|
35
36
|
};
|
|
36
|
-
export declare function scopedKey(agentId: string | undefined, key: string): string;
|
|
37
37
|
export declare function oauthRedirectUri(port: number): string;
|
|
38
38
|
export declare function tokenRequest(fetchImpl: Fetch, tokenUrl: string, body: URLSearchParams, label: string): Promise<OAuthTokens>;
|
|
@@ -1,5 +1,6 @@
|
|
|
1
1
|
import { Buffer } from 'buffer';
|
|
2
2
|
import { createHash, randomBytes as defaultRandomBytes } from 'crypto';
|
|
3
|
+
export { scopedKey } from "./keys.js";
|
|
3
4
|
export const CALLBACK_PATH = '/callback';
|
|
4
5
|
export const DEFAULT_TIMEOUT_MS = 120_000;
|
|
5
6
|
export const REFRESH_SKEW_MS = 60_000;
|
|
@@ -11,9 +12,6 @@ export function createPkce(randomBytes = defaultRandomBytes) {
|
|
|
11
12
|
const challenge = base64url(createHash('sha256').update(verifier).digest());
|
|
12
13
|
return { verifier, challenge, method: 'S256' };
|
|
13
14
|
}
|
|
14
|
-
export function scopedKey(agentId, key) {
|
|
15
|
-
return agentId ? `skills.${agentId}.${key}` : `skills.${key}`;
|
|
16
|
-
}
|
|
17
15
|
export function oauthRedirectUri(port) {
|
|
18
16
|
return `http://127.0.0.1:${port}${CALLBACK_PATH}`;
|
|
19
17
|
}
|
|
@@ -1,4 +1,5 @@
|
|
|
1
1
|
import type { OAuthProvider } from './types.ts';
|
|
2
|
+
export declare function scopedKey(agentId: string | undefined, key: string): string;
|
|
2
3
|
export declare const GMAIL_CREDENTIAL_KEY = "gmail_access_token";
|
|
3
4
|
export declare const GOOGLE_CALENDAR_CREDENTIAL_KEY = "google_calendar_access_token";
|
|
4
5
|
export declare const GOOGLE_DOCS_CREDENTIAL_KEY = "google_docs_access_token";
|
|
@@ -1,3 +1,6 @@
|
|
|
1
|
+
export function scopedKey(agentId, key) {
|
|
2
|
+
return agentId ? `skills.${agentId}.${key}` : `skills.${key}`;
|
|
3
|
+
}
|
|
1
4
|
export const GMAIL_CREDENTIAL_KEY = 'gmail_access_token';
|
|
2
5
|
export const GOOGLE_CALENDAR_CREDENTIAL_KEY = 'google_calendar_access_token';
|
|
3
6
|
export const GOOGLE_DOCS_CREDENTIAL_KEY = 'google_docs_access_token';
|
package/ducks.png
ADDED
|
Binary file
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@qvac/core",
|
|
3
|
-
"version": "0.1.
|
|
3
|
+
"version": "0.1.5",
|
|
4
4
|
"type": "module",
|
|
5
5
|
"description": "Peer-to-peer AI across your devices",
|
|
6
6
|
"exports": {
|
|
@@ -265,6 +265,7 @@
|
|
|
265
265
|
"hyperschema-ts": "^0.1.1",
|
|
266
266
|
"hyperswarm": "^4.17.0",
|
|
267
267
|
"keet-identity-key": "^3.2.0",
|
|
268
|
+
"paparam": "^1.13.0",
|
|
268
269
|
"process-top": "^1.7.1",
|
|
269
270
|
"protomux": "^3.11.0",
|
|
270
271
|
"protomux-wakeup": "^2.9.0",
|
|
@@ -290,7 +291,7 @@
|
|
|
290
291
|
"bare-runtime": "^1.30.0",
|
|
291
292
|
"bare-sidecar": "^0.5.2",
|
|
292
293
|
"brittle": "^4.0.2",
|
|
293
|
-
"holepunch-types": "^0.2.
|
|
294
|
+
"holepunch-types": "^0.2.2",
|
|
294
295
|
"hyperdht": "^6.32.0",
|
|
295
296
|
"hyperschema-regen": "^3.0.1",
|
|
296
297
|
"lunte": "^1.8.3",
|
package/tui/README.md
CHANGED
|
@@ -73,15 +73,14 @@ for the full command set.
|
|
|
73
73
|
|
|
74
74
|
## Environment
|
|
75
75
|
|
|
76
|
-
| Variable | Effect
|
|
77
|
-
| ----------------------------------------------------------- |
|
|
78
|
-
| `QVAC_MODEL` | Overrides the demo agent's model — a registry name, or a local path/URL
|
|
79
|
-
| `QVAC_MMPROJ` | Pairs models with their mmproj projections so ctrl+V'd images reach the model natively. One value applies to every model; `model=mmproj,model2=mmproj2` pairs are per-model
|
|
80
|
-
| `QVAC_IMAGE_MODEL` | Enables the `generate_image`/`edit_image` tools — a catalog choice (`sd2` \| `sdxl` \| `flux2-klein`), or a local diffusion model
|
|
81
|
-
| `QVAC_IMAGE_LLM`, `QVAC_IMAGE_VAE`, `QVAC_IMAGE_PREDICTION` | FLUX.2 is a companion set: the Qwen3 text encoder, the VAE, and `flux2_flow` (required for img2img)
|
|
82
|
-
| `QVAC_LOG_FILE`, `QVAC_LOG_LEVEL` | Move the log file / pick the level (`debug` \| `info` \| `warn` \| `error`, default `info`)
|
|
83
|
-
| `QVAC_BOOT_TIMING=1` | Prints the total connect time after the TUI exits
|
|
84
|
-
| `QVAC_INPROCESS=1` | Runs Core and Client in this process, no sidecar — the only topology that can inject a live harness object |
|
|
76
|
+
| Variable | Effect |
|
|
77
|
+
| ----------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
78
|
+
| `QVAC_MODEL` | Overrides the demo agent's model — a registry name, or a local path/URL |
|
|
79
|
+
| `QVAC_MMPROJ` | Pairs models with their mmproj projections so ctrl+V'd images reach the model natively. One value applies to every model; `model=mmproj,model2=mmproj2` pairs are per-model |
|
|
80
|
+
| `QVAC_IMAGE_MODEL` | Enables the `generate_image`/`edit_image` tools — a catalog choice (`sd2` \| `sdxl` \| `flux2-klein`), or a local diffusion model |
|
|
81
|
+
| `QVAC_IMAGE_LLM`, `QVAC_IMAGE_VAE`, `QVAC_IMAGE_PREDICTION` | FLUX.2 is a companion set: the Qwen3 text encoder, the VAE, and `flux2_flow` (required for img2img) |
|
|
82
|
+
| `QVAC_LOG_FILE`, `QVAC_LOG_LEVEL` | Move the log file / pick the level (`debug` \| `info` \| `warn` \| `error`, default `info`) |
|
|
83
|
+
| `QVAC_BOOT_TIMING=1` | Prints the total connect time after the TUI exits |
|
|
85
84
|
|
|
86
85
|
```sh
|
|
87
86
|
QVAC_MODEL=~/.qvac/models/3a65a2a3c6a30a47_Qwen3.5-4B-Q4_K_M.gguf \
|
|
@@ -95,11 +94,13 @@ desktop. Nothing is printed: the TUI owns the tty.
|
|
|
95
94
|
|
|
96
95
|
## Layout
|
|
97
96
|
|
|
98
|
-
| Path | Responsibility
|
|
99
|
-
| ----------- |
|
|
100
|
-
| `index.mjs` | The `duck` bin — CLI
|
|
101
|
-
| `
|
|
102
|
-
| `
|
|
97
|
+
| Path | Responsibility |
|
|
98
|
+
| ----------- | ------------------------------------------------------------------------------- |
|
|
99
|
+
| `index.mjs` | The `duck` bin — CLI parsing; loads nothing else for `--help` and `--version` |
|
|
100
|
+
| `main.mjs` | The app and its first frame; imports `boot.mjs` behind it |
|
|
101
|
+
| `boot.mjs` | Storage resolution, the sidecar the stack comes up in, and the Client to it |
|
|
102
|
+
| `app.mjs` | The TUI itself — state, keys, commands, rendering |
|
|
103
|
+
| `lib/` | Leaf helpers: wrapping, selection, rendering, export, knowledge import, uploads |
|
|
103
104
|
|
|
104
105
|
## Splash
|
|
105
106
|
|