@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.
@@ -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="https://raw.githubusercontent.com/tetherto/qvac-core/main/ducks.png" alt="" width="200">
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> &middot;
22
22
  <a href="#rendering-the-chunk-stream-any-ui">Chunk stream</a> &middot;
23
23
  <a href="#harness-event-reference">Events</a> &middot;
24
- <a href="#development">Development</a>
24
+ <a href="#development">Development</a> &middot;
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 (`duck` drives the
617
- command set):
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
- duck
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
- Office documents (`docx`, `doc`, `odt`) decode through an engine the host supplies rather
649
- than a declared dependency: the package pulls all thirteen platform prebuilds at ~350MB
650
- each, so declaring it would cost every install 4.3GB. Fetch the one for this machine before
651
- exercising `/knowledge add report.docx`:
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
- history.push({ role: 'tool', content: skillLoadedTurn(loaded) });
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('@qvac/core/mesh', 3);
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",
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.1",
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. `QVAC_INPROCESS=1` only |
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. Per-stage stamps exist only under `QVAC_INPROCESS=1` — the shared assistant sidecar carries no boot timer |
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, storage resolution, and the two topologies (sidecar, in-process) |
101
- | `app.mjs` | The TUI itself — state, keys, commands, rendering |
102
- | `lib/` | Leaf helpers: wrapping, selection, rendering, export, knowledge import, uploads, prebuilds |
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