@qvac/core 0.0.0 → 0.1.1

package/dist-lib/lib/core/migrations/agent-catalog.d.ts

@@ -0,0 +1,6 @@
+import { type HealthAssistantHost } from '../health-assistant.ts';
+import type { Mesh } from '../mesh.ts';
+export interface AgentCatalogMigrationContext {
+    readonly device: HealthAssistantHost;
+}
+export declare function migrateAgentCatalog(mesh: Mesh, { device }: AgentCatalogMigrationContext): Promise<boolean>;

package/dist-lib/lib/core/migrations/agent-catalog.js

@@ -0,0 +1,17 @@
+import { buildHealthAssistant, HEALTH_ASSISTANT_ID } from "../health-assistant.js";
+const AGENTS = '@qvac/agents';
+const MIGRATION_BASELINE_AT = 0;
+export async function migrateAgentCatalog(mesh, { device }) {
+    const snap = mesh.view.snapshot();
+    try {
+        if (await snap.get(AGENTS, { id: HEALTH_ASSISTANT_ID }))
+            return false;
+    }
+    finally {
+        await snap.close();
+    }
+    await mesh.dispatch('migrate-agent-catalog', {
+        agent: buildHealthAssistant(device, { at: MIGRATION_BASELINE_AT })
+    });
+    return true;
+}

package/dist-lib/lib/core/migrations/index.d.ts

@@ -0,0 +1,5 @@
+import type { Mesh } from '../mesh.ts';
+import { type AgentCatalogMigrationContext } from './agent-catalog.ts';
+import { type MembershipMigrationContext } from './membership.ts';
+export type MigrationContext = MembershipMigrationContext & AgentCatalogMigrationContext;
+export declare function runMigrations(mesh: Mesh, context: MigrationContext): Promise<boolean>;

package/dist-lib/lib/core/migrations/index.js

@@ -0,0 +1,7 @@
+import { migrateAgentCatalog } from "./agent-catalog.js";
+import { migrateMembership } from "./membership.js";
+export async function runMigrations(mesh, context) {
+    const membership = await migrateMembership(mesh, context);
+    const agents = await migrateAgentCatalog(mesh, context);
+    return membership || agents;
+}

package/dist-lib/lib/core/migrations/membership.d.ts

@@ -0,0 +1,11 @@
+import { type MembershipContext } from '../membership.ts';
+import type { Mesh } from '../mesh.ts';
+export interface MintedRoot {
+    readonly publicKey: Buffer;
+    readonly proof: Buffer;
+}
+export interface MembershipMigrationContext extends MembershipContext {
+    readonly deviceName: string;
+    readonly mintRoot: (deviceId: Buffer, at: number) => Promise<MintedRoot>;
+}
+export declare function migrateMembership(mesh: Mesh, { deviceKeyPair, deviceName, mintRoot, log }: MembershipMigrationContext): Promise<boolean>;

package/dist-lib/lib/core/migrations/membership.js

@@ -0,0 +1,26 @@
+import { attestDeviceProof } from "../identity.js";
+import { membershipView } from "../membership.js";
+export async function migrateMembership(mesh, { deviceKeyPair, deviceName, mintRoot, log }) {
+    const { members, own, unattested } = await membershipView(mesh, deviceKeyPair.publicKey);
+    if (members > 0 || !own || own.memberId)
+        return false;
+    const now = Date.now();
+    const root = await mintRoot(own.id, now);
+    const batch = mesh.batch();
+    batch.dispatch('mint-member', {
+        member: { id: root.publicKey, name: deviceName, joinedAt: now, updatedAt: now },
+        proof: root.proof
+    });
+    for (const id of unattested) {
+        batch.dispatch('attest-member-device', {
+            deviceId: id,
+            memberId: root.publicKey,
+            proof: await attestDeviceProof(id, deviceKeyPair, root.proof),
+            attestedAt: now
+        });
+    }
+    await batch.flush();
+    await mesh.refreshOurMember();
+    log?.info(['p2p', 'mesh'], 'migrated: minted the member this mesh predates, every device we hold is attested to our member', { attested: unattested.length });
+    return true;
+}

package/dist-lib/lib/core/min-version.d.ts

@@ -0,0 +1,6 @@
+export interface VersionFloor {
+    readonly range: string | null | undefined;
+    readonly appVersion: string | null | undefined;
+}
+export declare function releaseVersion(version: string): string;
+export declare function updateRequired({ range, appVersion }: VersionFloor): boolean;

package/dist-lib/lib/core/min-version.js

@@ -0,0 +1,31 @@
+import { Range, Version, satisfies } from 'bare-semver';
+export function releaseVersion(version) {
+    const match = version
+        .trim()
+        .replace(/^[vV]/, '')
+        .match(/^\d+\.\d+\.\d+/);
+    if (!match)
+        throw new Error(`unparseable version: ${version}`);
+    return match[0];
+}
+export function updateRequired({ range, appVersion }) {
+    if (!range || !appVersion)
+        return false;
+    const floor = parseRange(range);
+    if (!floor)
+        return false;
+    try {
+        return !satisfies(Version.parse(releaseVersion(appVersion)), floor);
+    }
+    catch {
+        return false;
+    }
+}
+function parseRange(range) {
+    try {
+        return Range.parse(range);
+    }
+    catch {
+        return null;
+    }
+}

package/dist-lib/lib/core/next-frame.d.ts

@@ -0,0 +1,6 @@
+import type { AbortSignal } from 'bare-abort-controller';
+export declare const UPLOAD_INACTIVITY_MS = 30000;
+export declare function nextFrame<T>(iterator: AsyncIterator<T>, { signal, inactivityMs }?: {
+    signal?: AbortSignal;
+    inactivityMs?: number;
+}): Promise<IteratorResult<T>>;

package/dist-lib/lib/core/next-frame.js

@@ -0,0 +1,27 @@
+import { AbortedError } from '@qvac/harness/race-abort';
+import { unref } from "../unref.js";
+export const UPLOAD_INACTIVITY_MS = 30_000;
+export function nextFrame(iterator, { signal, inactivityMs = UPLOAD_INACTIVITY_MS } = {}) {
+    if (signal?.aborted)
+        return Promise.reject(new AbortedError());
+    return new Promise((resolve, reject) => {
+        const timer = setTimeout(() => finish(new Error('upload source timed out')), inactivityMs);
+        unref(timer);
+        const abort = () => finish(new AbortedError());
+        const finish = (error, result) => {
+            clearTimeout(timer);
+            signal?.removeEventListener('abort', abort);
+            if (error)
+                reject(error);
+            else if (result)
+                resolve(result);
+        };
+        signal?.addEventListener('abort', abort, { once: true });
+        try {
+            iterator.next().then((result) => finish(undefined, result), finish);
+        }
+        catch (error) {
+            finish(error);
+        }
+    });
+}

package/dist-lib/lib/core/notification.d.ts

@@ -0,0 +1,6 @@
+import type { AssistantNotificationList } from '../../spec/hyperschema/types.d.ts';
+import type { openLocalStore } from './local/index.ts';
+import type { Mesh } from './mesh.ts';
+type LocalStore = Awaited<ReturnType<typeof openLocalStore>>;
+export declare function deriveNotifications(mesh: Mesh, local: LocalStore, requestedLimit?: number, deviceId?: Buffer | null): Promise<AssistantNotificationList>;
+export {};

package/dist-lib/lib/core/notification.js

@@ -0,0 +1,162 @@
+import { diagramRepairLinks, isDiagramRepairPrompt } from '@qvac/harness/lib/diagram-repair.ts';
+import { findChunksOfType } from "./chunk.js";
+const ACTIVE_CHATS = '@qvac/active-chats';
+const AGENTS = '@qvac/agents';
+const CHUNK_COUNTERS = '@qvac/chunk-counters';
+const DEFAULT_LIMIT = 200;
+const PREVIEW_LIMIT = 280;
+export async function deriveNotifications(mesh, local, requestedLimit, deviceId) {
+    const limit = requestedLimit || DEFAULT_LIMIT;
+    const snap = mesh.view.snapshot();
+    try {
+        const chats = await snap.find(ACTIVE_CHATS).toArray();
+        const candidates = [];
+        const own = deviceId ? await snap.get('@qvac/devices', { id: deviceId }) : null;
+        for (const chat of chats) {
+            const counter = await snap.get(CHUNK_COUNTERS, { chatId: chat.id });
+            const ackedThrough = (await local.getChatNotify(chat.id))?.ackedThrough ?? 0;
+            const [statuses, approvals, messages] = await Promise.all([
+                (counter?.count ?? 0) <= ackedThrough
+                    ? []
+                    : findChunksOfType(snap, chat.id, 'run-status', { fromSeq: ackedThrough }),
+                findChunksOfType(snap, chat.id, 'approval-request'),
+                (counter?.count ?? 0) <= ackedThrough
+                    ? []
+                    : findChunksOfType(snap, chat.id, 'user-message', { fromSeq: ackedThrough })
+            ]);
+            const terminalStatuses = statuses.filter((chunk) => {
+                const state = chunk.runStatus?.state;
+                return state === 'completed' || state === 'failed';
+            });
+            for (const chunk of messages) {
+                if (deviceId?.equals(chunk.originDeviceId))
+                    continue;
+                const text = chunk.userMessage?.text ?? '';
+                if (isDiagramRepairPrompt(text))
+                    continue;
+                const sender = await snap.get('@qvac/devices', { id: chunk.originDeviceId });
+                if (own?.memberId && sender?.memberId?.equals(own.memberId))
+                    continue;
+                const member = sender?.memberId
+                    ? await snap.get('@qvac/members', { id: sender.memberId })
+                    : null;
+                candidates.push({
+                    chatId: chat.id,
+                    agentId: chat.agentId,
+                    chunkId: chunk.id,
+                    kind: 'user-message',
+                    seq: chunk.seq,
+                    createdAt: chunk.createdAt,
+                    senderDeviceId: chunk.originDeviceId,
+                    senderMemberId: sender?.memberId,
+                    senderName: member?.name ?? sender?.name,
+                    chatTitle: chat.title,
+                    preview: Array.from(text).slice(0, PREVIEW_LIMIT).join('') || undefined
+                });
+            }
+            for (const chunk of terminalStatuses) {
+                candidates.push({
+                    chatId: chat.id,
+                    agentId: chat.agentId,
+                    chunkId: chunk.id,
+                    kind: chunk.runStatus?.state === 'completed' ? 'assistant-reply' : 'run-failed',
+                    seq: chunk.seq,
+                    createdAt: chunk.createdAt,
+                    runId: chunk.runId ?? undefined
+                });
+            }
+            for (const chunk of approvals) {
+                if (chunk.approvalRequest?.status !== 'pending')
+                    continue;
+                candidates.push({
+                    chatId: chat.id,
+                    agentId: chat.agentId,
+                    chunkId: chunk.id,
+                    kind: 'approval-required',
+                    seq: chunk.seq,
+                    createdAt: chunk.createdAt,
+                    runId: chunk.runId ?? undefined
+                });
+            }
+        }
+        candidates.sort((left, right) => right.createdAt - left.createdAt || right.seq - left.seq);
+        const maxSeqByChat = new Map();
+        for (const candidate of candidates) {
+            maxSeqByChat.set(candidate.chatId, Math.max(maxSeqByChat.get(candidate.chatId) ?? 0, candidate.seq));
+        }
+        const repairRunIdsByChat = new Map();
+        const selected = [];
+        let truncated = false;
+        for (const candidate of candidates) {
+            let repairRunIds = repairRunIdsByChat.get(candidate.chatId);
+            if (!repairRunIds) {
+                const maxSeq = maxSeqByChat.get(candidate.chatId);
+                repairRunIds = await diagramRepairRunIds(snap, candidate.chatId, maxSeq);
+                repairRunIdsByChat.set(candidate.chatId, repairRunIds);
+            }
+            if (candidate.runId && repairRunIds.has(candidate.runId))
+                continue;
+            if (selected.length >= limit) {
+                truncated = true;
+                break;
+            }
+            selected.push(candidate);
+        }
+        const terminalSeqByChat = new Map();
+        for (const candidate of selected) {
+            if (candidate.kind === 'approval-required' || !candidate.runId)
+                continue;
+            terminalSeqByChat.set(candidate.chatId, Math.max(terminalSeqByChat.get(candidate.chatId) ?? 0, candidate.seq));
+        }
+        const contentByChat = new Map();
+        for (const [chatId, terminalSeq] of terminalSeqByChat) {
+            contentByChat.set(chatId, await findChunksOfType(snap, chatId, 'content', { toSeq: terminalSeq }));
+        }
+        const agentNameById = new Map();
+        for (const agentId of new Set(selected.map((candidate) => candidate.agentId))) {
+            agentNameById.set(agentId, (await snap.get(AGENTS, { id: agentId }))?.name);
+        }
+        const notifications = selected.map((candidate) => {
+            const content = candidate.kind === 'approval-required' ? undefined : contentByChat.get(candidate.chatId);
+            const preview = candidate.runId && content ? runPreview(content, candidate.runId, candidate.seq) : undefined;
+            const { runId, ...event } = candidate;
+            return {
+                ...event,
+                agentName: agentNameById.get(candidate.agentId),
+                preview: candidate.preview ?? preview
+            };
+        });
+        return {
+            notifications,
+            truncated: truncated || undefined
+        };
+    }
+    finally {
+        await snap.close();
+    }
+}
+async function diagramRepairRunIds(snap, chatId, toSeq) {
+    const [users, requests] = await Promise.all([
+        findChunksOfType(snap, chatId, 'user-message', { toSeq }),
+        findChunksOfType(snap, chatId, 'run-request', { toSeq })
+    ]);
+    const records = [...users, ...requests];
+    const repairs = diagramRepairLinks(records, (chunk) => chunk.userMessage?.text ?? null);
+    const runIds = new Set();
+    for (const chunk of records) {
+        if (chunk.runId && isDiagramRepairPrompt(chunk.userMessage?.text ?? '')) {
+            runIds.add(chunk.runId);
+        }
+    }
+    for (const repair of repairs)
+        runIds.add(repair.runId);
+    return runIds;
+}
+function runPreview(content, runId, terminalSeq) {
+    const text = content
+        .filter((chunk) => chunk.seq <= terminalSeq && chunk.runId === runId)
+        .map((chunk) => chunk.content?.text ?? '')
+        .join('')
+        .slice(0, PREVIEW_LIMIT);
+    return text || undefined;
+}

package/dist-lib/lib/core/ota-config.d.ts

@@ -0,0 +1,19 @@
+import Hyperconf from 'hyperconf';
+import type Corestore from 'corestore';
+import type { Hypercore } from 'corestore';
+import { type ReleaseLane } from './app-build.ts';
+import { type ConfConfig } from '../../spec/config/hyperconf/index.js';
+export type ConfigChannel = ReleaseLane;
+export interface ConfigCore {
+    readonly key: string;
+    readonly minLength: number;
+}
+export declare function resolveConfigChannel(channel?: string | null): ConfigChannel | null;
+export declare function configCoreFor(channel: ConfigChannel): ConfigCore;
+export declare function vendoredMinSupportedVersion(): string;
+export declare class OtaConfigReader extends Hyperconf<ConfConfig> {
+    constructor(store: Corestore, { key, minLength }: ConfigCore);
+    get minSupportedVersion(): string | null;
+}
+export declare function readOtaConfig(core: Hypercore): Promise<ConfConfig | null>;
+export declare function publishOtaConfig(core: Hypercore, config: ConfConfig): Promise<number>;

package/dist-lib/lib/core/ota-config.js

@@ -0,0 +1,44 @@
+import b4a from 'b4a';
+import { Range } from 'bare-semver';
+import c from 'compact-encoding';
+import Hyperconf from 'hyperconf';
+import HypercoreId from 'hypercore-id-encoding';
+import { RELEASE_LANES } from "./app-build.js";
+import spec, {} from '../../spec/config/hyperconf/index.js';
+const CONFIG_CORES = {
+    dev: { key: 'e5g337qdk4qachns5nsnu63wjp96twyc34ainucherhq1zodanmy', minLength: 1 },
+    staging: { key: '89mz9t33g1c8e4nsjuzafjcbsdht74akzouw3ptfzewnuathpkcy', minLength: 1 },
+    prod: { key: 'enuaa7ybdsp3ons73yrazrno9gwrejx4tum3kdws6rps1p1bekgo', minLength: 1 }
+};
+export function resolveConfigChannel(channel) {
+    return RELEASE_LANES.find((lane) => lane === channel) ?? null;
+}
+export function configCoreFor(channel) {
+    return CONFIG_CORES[channel];
+}
+export function vendoredMinSupportedVersion() {
+    return spec.production.minSupportedVersion;
+}
+export class OtaConfigReader extends Hyperconf {
+    constructor(store, { key, minLength }) {
+        super(spec, store.get(HypercoreId.decode(key)), { minLength, production: true });
+    }
+    get minSupportedVersion() {
+        const range = this.current?.minSupportedVersion;
+        return typeof range === 'string' && range.length > 0 ? range : null;
+    }
+}
+export async function readOtaConfig(core) {
+    await core.ready();
+    if (!core.length)
+        return null;
+    const block = await core.get(core.length - 1);
+    return block ? c.decode(spec.productionEncoding, block) : null;
+}
+export async function publishOtaConfig(core, config) {
+    Range.parse(config.minSupportedVersion);
+    await core.ready();
+    await core.append(c.encode(spec.productionEncoding, config));
+    await core.setUserData('hyperconf', b4a.from(String(core.length)));
+    return core.length;
+}

package/dist-lib/lib/core/prompt-history.d.ts

@@ -0,0 +1,12 @@
+import { type DiagramRepairLink } from '@qvac/harness/lib/diagram-repair.ts';
+import type { AssistantChunk } from '../../spec/hyperschema/types.d.ts';
+export interface HistoryBranches {
+    readonly repairs: ReadonlyArray<DiagramRepairLink>;
+    readonly repairByRunId: ReadonlyMap<string, DiagramRepairLink>;
+    readonly hiddenChunkIds: ReadonlySet<string>;
+    readonly rejectedRunIds: ReadonlySet<string>;
+    readonly deadRanges: ReadonlyArray<readonly [number, number]>;
+}
+export declare function historyBranches(all: ReadonlyArray<AssistantChunk>, currentRunId?: string): HistoryBranches;
+export declare function isPromptChunk(chunk: AssistantChunk, branches: HistoryBranches): boolean;
+export declare function acceptedRepairCount(branches: HistoryBranches, currentRunId?: string): number;

package/dist-lib/lib/core/prompt-history.js

@@ -0,0 +1,40 @@
+import { diagramRepairAccepted, diagramRepairLinks, isDiagramRepairPrompt } from '@qvac/harness/lib/diagram-repair.ts';
+export function historyBranches(all, currentRunId) {
+    const seqById = new Map(all.map((chunk) => [chunk.id, chunk.seq]));
+    const repairs = diagramRepairLinks(all.filter((chunk) => chunk.type === 'user-message' || chunk.type === 'run-request'), (chunk) => chunk.userMessage?.text ?? null);
+    const repairByRunId = new Map(repairs.map((repair) => [repair.runId, repair]));
+    const hiddenChunkIds = new Set(all
+        .filter((chunk) => isDiagramRepairPrompt(chunk.userMessage?.text ?? ''))
+        .map((chunk) => chunk.id));
+    const replyText = (target) => all
+        .filter((chunk) => chunk.runId === target && chunk.content)
+        .map((chunk) => chunk.content?.text ?? '')
+        .join('');
+    const completed = (target) => all.some((chunk) => chunk.type === 'run-status' &&
+        chunk.runId === target &&
+        chunk.runStatus?.state === 'completed');
+    const rejectedRunIds = new Set(repairs
+        .filter((repair) => repair.runId !== currentRunId &&
+        !(completed(repair.runId) && diagramRepairAccepted(replyText(repair.runId))))
+        .map((repair) => repair.runId));
+    const deadRanges = [];
+    for (const chunk of all) {
+        const repair = chunk.runId ? repairByRunId.get(chunk.runId) : undefined;
+        if (repair && (repair.runId === currentRunId || rejectedRunIds.has(repair.runId)))
+            continue;
+        const start = chunk.parentId ? seqById.get(chunk.parentId) : undefined;
+        if (start !== undefined)
+            deadRanges.push([start, chunk.seq]);
+    }
+    return { repairs, repairByRunId, hiddenChunkIds, rejectedRunIds, deadRanges };
+}
+export function isPromptChunk(chunk, branches) {
+    if (chunk.compaction)
+        return true;
+    return (!branches.hiddenChunkIds.has(chunk.id) &&
+        !(chunk.runId && branches.rejectedRunIds.has(chunk.runId)) &&
+        !branches.deadRanges.some(([start, end]) => chunk.seq >= start && chunk.seq < end));
+}
+export function acceptedRepairCount(branches, currentRunId) {
+    return branches.repairs.filter((repair) => repair.runId !== currentRunId && !branches.rejectedRunIds.has(repair.runId)).length;
+}

package/dist-lib/lib/core/search-fold.d.ts

@@ -0,0 +1 @@
+export declare function foldSearchText(text: string): string;

package/dist-lib/lib/core/search-fold.js

@@ -0,0 +1,4 @@
+import { fold } from 'asenion';
+export function foldSearchText(text) {
+    return fold(text, { preserveLength: true });
+}

package/dist-lib/lib/core/secret-handoff.d.ts

@@ -0,0 +1,17 @@
+import { ACK_TIMEOUT_MS, HOST_SILENT, HOST_UNREACHABLE, type HandoffStream } from './handoff-channel.ts';
+import type { AssistantPushSkillSecretRequest, AssistantSkillSecretValue } from '../../spec/hyperschema/types.d.ts';
+export { ACK_TIMEOUT_MS, HOST_SILENT, HOST_UNREACHABLE, type HandoffStream };
+export type SecretValue = AssistantSkillSecretValue;
+export type SecretRequest = AssistantPushSkillSecretRequest;
+export type SecretRequestHandler = (request: SecretRequest, fromDeviceId: Uint8Array) => Promise<void>;
+export interface SecretHandoffOptions {
+    readonly onrequest: SecretRequestHandler;
+    readonly ackTimeoutMs?: number;
+}
+export declare class SecretHandoff {
+    private readonly _channel;
+    constructor(opts: SecretHandoffOptions);
+    addStream(stream: HandoffStream): void;
+    send(hostDeviceId: Uint8Array, request: SecretRequest): Promise<void>;
+    destroy(): void;
+}

package/dist-lib/lib/core/secret-handoff.js

@@ -0,0 +1,29 @@
+import { getStruct } from '../../spec/hyperschema/index.js';
+import { ACK_TIMEOUT_MS, HandoffChannel, HOST_SILENT, HOST_UNREACHABLE } from "./handoff-channel.js";
+const PROTOCOL = 'qvac/secret-handoff';
+export { ACK_TIMEOUT_MS, HOST_SILENT, HOST_UNREACHABLE };
+const handoff = getStruct('@assistant/skill-secret-handoff');
+const handoffAck = getStruct('@assistant/skill-secret-handoff-ack');
+export class SecretHandoff {
+    _channel;
+    constructor(opts) {
+        this._channel = new HandoffChannel({
+            protocol: PROTOCOL,
+            requestEncoding: handoff,
+            ackEncoding: handoffAck,
+            onrequest: opts.onrequest,
+            buildAck: (id, error) => ({ id, error }),
+            readAck: (ack) => ({ error: ack.error ?? '', result: undefined }),
+            ackTimeoutMs: opts.ackTimeoutMs
+        });
+    }
+    addStream(stream) {
+        this._channel.addStream(stream);
+    }
+    send(hostDeviceId, request) {
+        return this._channel.send(hostDeviceId, request);
+    }
+    destroy() {
+        this._channel.destroy();
+    }
+}

package/dist-lib/lib/core/send.d.ts

@@ -0,0 +1,18 @@
+import type { QvacChat } from '../../spec/mesh/hyperschema/types.d.ts';
+import type { Mesh } from './mesh.ts';
+export type SendMessageInput = {
+    text: string;
+    originDeviceId: Buffer;
+    chatId?: string;
+    agentId?: string;
+    title?: string;
+    parentRunId?: string;
+};
+export type SendMessageResult = {
+    chatId: string;
+    chunkId: string;
+    runId: string;
+    chat?: QvacChat;
+};
+export declare function sendMessage(mesh: Mesh, input: SendMessageInput): Promise<SendMessageResult>;
+export declare function parentRequestId(mesh: Mesh, chatId: string, parentRunId: string): Promise<string>;

package/dist-lib/lib/core/send.js

@@ -0,0 +1,46 @@
+import { buildChat, enrichChat, mustGetActiveChat } from "./chat.js";
+import { appendChunk, listChunks } from "./chunk.js";
+import { randomId } from "./id.js";
+export async function sendMessage(mesh, input) {
+    const existing = input.chatId ? await mustGetActiveChat(mesh, input.chatId) : null;
+    const agentId = input.agentId ?? existing?.agentId;
+    if (!agentId)
+        throw new Error('send-message: agentId is required to mint a chat');
+    const chat = existing ?? buildChat({ agentId, title: input.title ?? '' });
+    const chatId = chat.id;
+    const parentId = input.parentRunId
+        ? await parentRequestId(mesh, chatId, input.parentRunId)
+        : undefined;
+    const runId = randomId();
+    const batch = mesh.batch();
+    if (!existing)
+        batch.dispatch('put-chat', { chat });
+    const { id: chunkId } = await appendChunk(mesh, {
+        chatId,
+        type: 'user-message',
+        userMessage: { text: input.text },
+        originDeviceId: input.originDeviceId
+    }, batch);
+    await appendChunk(mesh, {
+        chatId,
+        runId,
+        type: 'run-request',
+        runRequest: { agentId },
+        parentId,
+        originDeviceId: input.originDeviceId
+    }, batch);
+    await batch.flush();
+    return {
+        chatId,
+        chunkId,
+        runId,
+        chat: existing ? undefined : await enrichChat(mesh, chat)
+    };
+}
+export async function parentRequestId(mesh, chatId, parentRunId) {
+    const requests = await listChunks(mesh, { chatId, type: 'run-request' });
+    const parent = requests.find((chunk) => chunk.runId === parentRunId);
+    if (!parent)
+        throw new Error(`run not found: ${parentRunId}`);
+    return parent.id;
+}

package/dist-lib/lib/core/skill-overlay-handoff.d.ts

@@ -0,0 +1,25 @@
+import { ACK_TIMEOUT_MS, HOST_SILENT, HOST_UNREACHABLE, type HandoffStream } from './handoff-channel.ts';
+import type { AssistantManagedSkill, AssistantSkillOverlayOp } from '../../spec/hyperschema/types.d.ts';
+export { ACK_TIMEOUT_MS, HOST_SILENT, HOST_UNREACHABLE, type HandoffStream };
+export type SkillOverlayOp = AssistantSkillOverlayOp;
+export interface SkillOverlayResult {
+    readonly skills?: ReadonlyArray<AssistantManagedSkill>;
+    readonly found?: boolean;
+    readonly content?: string | null;
+    readonly origin?: string | null;
+    readonly ok?: boolean;
+    readonly copied?: boolean;
+    readonly removed?: boolean;
+}
+export type SkillOverlayHandler = (op: SkillOverlayOp, fromDeviceId: Uint8Array) => Promise<SkillOverlayResult>;
+export interface SkillOverlayHandoffOptions {
+    readonly onrequest: SkillOverlayHandler;
+    readonly ackTimeoutMs?: number;
+}
+export declare class SkillOverlayHandoff {
+    private readonly _channel;
+    constructor(opts: SkillOverlayHandoffOptions);
+    addStream(stream: HandoffStream): void;
+    send(hostDeviceId: Uint8Array, op: SkillOverlayOp): Promise<SkillOverlayResult>;
+    destroy(): void;
+}

package/dist-lib/lib/core/skill-overlay-handoff.js

@@ -0,0 +1,50 @@
+import { getStruct } from '../../spec/hyperschema/index.js';
+import { ACK_TIMEOUT_MS, HandoffChannel, HOST_SILENT, HOST_UNREACHABLE } from "./handoff-channel.js";
+const PROTOCOL = 'qvac/skill-overlay-handoff';
+export { ACK_TIMEOUT_MS, HOST_SILENT, HOST_UNREACHABLE };
+const handoff = getStruct('@assistant/skill-overlay-handoff');
+const handoffAck = getStruct('@assistant/skill-overlay-handoff-ack');
+export class SkillOverlayHandoff {
+    _channel;
+    constructor(opts) {
+        this._channel = new HandoffChannel({
+            protocol: PROTOCOL,
+            requestEncoding: handoff,
+            ackEncoding: handoffAck,
+            onrequest: opts.onrequest,
+            buildAck: (id, error, result) => ({
+                id,
+                error,
+                skills: result?.skills ? [...result.skills] : undefined,
+                found: result?.found,
+                content: result?.content ?? undefined,
+                origin: result?.origin ?? undefined,
+                ok: result?.ok,
+                copied: result?.copied,
+                removed: result?.removed
+            }),
+            readAck: (ack) => ({
+                error: ack.error ?? '',
+                result: {
+                    skills: ack.skills ?? undefined,
+                    found: ack.found,
+                    content: ack.content ?? undefined,
+                    origin: ack.origin ?? undefined,
+                    ok: ack.ok,
+                    copied: ack.copied,
+                    removed: ack.removed
+                }
+            }),
+            ackTimeoutMs: opts.ackTimeoutMs
+        });
+    }
+    addStream(stream) {
+        this._channel.addStream(stream);
+    }
+    send(hostDeviceId, op) {
+        return this._channel.send(hostDeviceId, op);
+    }
+    destroy() {
+        this._channel.destroy();
+    }
+}

package/dist-lib/lib/core/skill-overlay-receiver.d.ts

@@ -0,0 +1,8 @@
+import type { Mesh } from './mesh.ts';
+import type { SkillOverlayHandler, SkillOverlayOp, SkillOverlayResult } from './skill-overlay-handoff.ts';
+export interface SkillOverlayReceiverOptions {
+    readonly mesh: Mesh;
+    readonly deviceId: Uint8Array;
+    readonly runLocal: (op: SkillOverlayOp) => Promise<SkillOverlayResult>;
+}
+export declare function createSkillOverlayReceiver(opts: SkillOverlayReceiverOptions): SkillOverlayHandler;