@vibesdotdev/external 0.0.0-stage → 1.0.0-rc.0

package/dist/client/external-client.js

@@ -0,0 +1,979 @@
+import { CloudTouchProjection } from "../ambient/cloud-touch-projection.impl.js";
+import { TouchIdentityCache } from "../storage/touch-identity.js";
+import { ExternalLifecycle } from "./lifecycle.js";
+import * as z from 'zod/v4';
+import { listRuntimePresets } from "../presets/runtime.js";
+import { ConfigManifest } from '@vibesdotdev/config/manifest/config-manifest';
+import { ExecutionResultSchema } from "../schemas/presets.js";
+import { getLogger } from '@vibesdotdev/logging';
+/**
+ * ExternalClient - Runtime Client for External Tooling
+ *
+ * The canonical client for the external/host domain. Provides typed access to:
+ * - Tool detection and management (tools.*)
+ * - MCP configuration (mcp.*)
+ * - Hook installation (hooks.*)
+ * - Skill generation (skills.*)
+ * - File access tracking (fileAccess.*)
+ * - Context summary generation (contextSummary.*)
+ * - Preset management (presets.*)
+ * - Setup wizard (setup.runWizard)
+ * - Config management (config.*)
+ *
+ * Cross-module access goes through getVibesExternalClient(runtime) - never through
+ * deep imports of storage/, mcp-config/, or detection/.
+ */
+import { CapabilityError, CaughtFailureSchema, valueFreeFailure } from '@vibesdotdev/kernel';
+import { BaseRuntimeClient, getVibesClient } from '@vibesdotdev/kernel/client';
+import { DEFAULT_RECENCY_WINDOW_MS, WhoElseTouchedInputSchema } from "../schemas/collision.js";
+import { RECENT_WINDOW_MS, mergeRosterEntries, rosterFromAnnouncements, rosterFromTouches } from "../schemas/roster.js";
+import { announceCurrentAgentSession, resolveAgentRosterProvider } from "../ambient/agent-roster-heartbeat.js";
+import { listExternalHostDescriptors, resolveExternalHostImplementation } from "../external-tool/runtime.js";
+import { externalFileSystem, listNamesIfPresent } from "../utils/runtime-fs.js";
+/** What a unified-tool action answers: a message, plus any data. */
+const ToolReceiptSchema = z.object({ message: z.string() }).passthrough();
+const ExternalToolImplementationSchema = z.custom((value) => value instanceof Object && 'execute' in value && Object(value).execute instanceof Function);
+/** Value-free failure facts as JSON details. */
+function failureDetails(failure) {
+    return { name: failure.name, code: failure.code ?? null, reason: failure.reason ?? null };
+}
+async function attemptWrite(write) {
+    try {
+        return { value: await write() };
+    }
+    catch (error) {
+        return { failed: valueFreeFailure(CaughtFailureSchema.parse(error)) };
+    }
+}
+// =============================================================================
+// FILE ACCESS STORAGE HELPER
+// =============================================================================
+class FileAccessStorage {
+    runtime;
+    recordPromise = null;
+    constructor(runtime) {
+        this.runtime = runtime;
+    }
+    async getRecord() {
+        if (!this.recordPromise) {
+            this.recordPromise = this.runtime
+                .query('storage/record')
+                .withId('external.file_accesses')
+                .resolve();
+        }
+        return this.recordPromise;
+    }
+    toDate(value) {
+        if (value instanceof Date)
+            return value;
+        return value === undefined ? new Date(0) : new Date(value);
+    }
+    normalizeFileAccess(access) {
+        return {
+            ...access,
+            timestamp: this.toDate(access.timestamp),
+            createdAt: this.toDate(access.createdAt)
+        };
+    }
+    filterAccesses(accesses, filters) {
+        if (!filters)
+            return accesses;
+        return accesses.filter((access) => {
+            if (filters.operation && access.operation !== filters.operation)
+                return false;
+            if (filters.filePath && !access.filePath.includes(filters.filePath))
+                return false;
+            if (filters.since && this.toDate(access.timestamp) < filters.since)
+                return false;
+            if (filters.until && this.toDate(access.timestamp) > filters.until)
+                return false;
+            return true;
+        });
+    }
+    buildStats(entries) {
+        const byPath = new Map();
+        for (const entry of entries) {
+            const list = byPath.get(entry.filePath) ?? [];
+            list.push(entry);
+            byPath.set(entry.filePath, list);
+        }
+        const now = Date.now();
+        const stats = [];
+        for (const [filePath, list] of byPath) {
+            const sorted = [...list].sort((a, b) => this.toDate(a.timestamp).getTime() - this.toDate(b.timestamp).getTime());
+            // A row is a bucket carrying `accessCount` touches, so sum it rather
+            // than counting rows — otherwise rollup would silently deflate every
+            // number a caller reads.
+            const weight = (e) => e.accessCount ?? 1;
+            const totalAccesses = list.reduce((sum, e) => sum + weight(e), 0);
+            const firstAccess = this.toDate(sorted[0]?.timestamp);
+            const lastAccess = this.toDate(sorted[sorted.length - 1]?.timestamp);
+            const ageDays = Math.max(0, (now - lastAccess.getTime()) / (1000 * 60 * 60 * 24));
+            const recencyScore = Math.max(0, 1 - Math.min(1, ageDays / 7));
+            const frequencyScore = Math.min(1, totalAccesses / 20);
+            const relevanceScore = recencyScore * 0.6 + frequencyScore * 0.4;
+            stats.push({
+                filePath,
+                readCount: list.reduce((n, e) => n + (e.operation === 'read' ? weight(e) : 0), 0),
+                editCount: list.reduce((n, e) => n + (e.operation === 'edit' ? weight(e) : 0), 0),
+                writeCount: list.reduce((n, e) => n + (e.operation === 'write' ? weight(e) : 0), 0),
+                deleteCount: list.reduce((n, e) => n + (e.operation === 'delete' ? weight(e) : 0), 0),
+                totalAccesses,
+                firstAccess: firstAccess.toISOString(),
+                lastAccess: lastAccess.toISOString(),
+                recencyScore,
+                frequencyScore,
+                relevanceScore
+            });
+        }
+        return stats.sort((a, b) => b.relevanceScore - a.relevanceScore);
+    }
+    /**
+     * The rollup bucket a touch belongs to: one per
+     * (session, path, operation, tool, UTC day). Derived, not random, so a
+     * repeat touch finds its bucket with a get instead of a query. Shaped as a
+     * v8 UUID because the record id is schema-constrained to a UUID.
+     */
+    async bucketId(options, day) {
+        // JSON rather than a delimiter: a file path may contain any byte, so a
+        // delimiter that can appear in the input can merge two distinct touches.
+        const key = JSON.stringify([
+            options.sessionId,
+            options.filePath,
+            options.operation,
+            options.toolName ?? '',
+            day
+        ]);
+        if (!globalThis.crypto?.subtle) {
+            throw new CapabilityError('File-access rollup requires Web Crypto (crypto.subtle).', 'UNAVAILABLE', {
+                reason: 'web-crypto-unavailable',
+                retryable: false
+            });
+        }
+        const digest = new Uint8Array(await globalThis.crypto.subtle.digest('SHA-256', new TextEncoder().encode(key)));
+        const h = Array.from(digest, (byte) => byte.toString(16).padStart(2, '0')).join('');
+        return [
+            h.slice(0, 8),
+            h.slice(8, 12),
+            `8${h.slice(13, 16)}`,
+            `${((parseInt(h[16], 16) & 0x3) | 0x8).toString(16)}${h.slice(17, 20)}`,
+            h.slice(20, 32)
+        ].join('-');
+    }
+    /**
+     * Record a touch.
+     *
+     * Touches ROLL UP: a bucket row is created once and then counted, never
+     * appended to. The ambient watcher fires on every OS change, so
+     * append-per-event grew `external.db` to 2.15 million rows and 3.4 GB in
+     * eight days while carrying nine rows of real tool activity. What callers
+     * read — who touched what, when, how often — is unchanged.
+     */
+    async track(options) {
+        const record = await this.getRecord();
+        const now = new Date();
+        const at = options.timestamp ?? now;
+        const day = this.toDate(at).toISOString().slice(0, 10);
+        const id = await this.bucketId(options, day);
+        const create = {
+            id,
+            accessCount: 1,
+            sessionId: options.sessionId,
+            filePath: options.filePath,
+            operation: options.operation,
+            lineRange: options.lineRange,
+            symbolsAccessed: options.symbolsAccessed ?? [],
+            bytesRead: options.bytesRead,
+            bytesWritten: options.bytesWritten,
+            diagnosticsCount: options.diagnosticsCount,
+            activeTodoId: options.activeTodoId,
+            toolName: options.toolName,
+            toolCallId: options.toolCallId,
+            // Ambient identity (v2). Undefined stays undefined: a touch that
+            // cannot resolve its machine or workspace still records.
+            machineId: options.machineId,
+            machineName: options.machineName,
+            participantId: options.participantId,
+            participantSlug: options.participantSlug,
+            workspaceRoot: options.workspaceRoot,
+            gitBranch: options.gitBranch,
+            headSha: options.headSha,
+            workItemId: options.workItemId,
+            workItemTitle: options.workItemTitle,
+            metadata: options.metadata ?? {},
+            timestamp: at,
+            createdAt: now
+        };
+        // This path is shared by watcher callbacks and can be entered
+        // concurrently. A plain get/update loses increments. Compare-and-set the
+        // observed count; a create collision means another caller created the
+        // bucket first, so retry against that row. Retention is deliberately not
+        // duplicated here: the descriptor-owned policy is enforced by the
+        // External plugin on activation and on its bounded interval.
+        for (let attempt = 0; attempt < 64; attempt++) {
+            const existing = await record.get(id);
+            if (!existing) {
+                const created = await attemptWrite(async () => this.normalizeFileAccess(await record.create(create)));
+                if ('value' in created)
+                    return created.value;
+                // Another caller created the bucket first: retry against that row.
+                if (await record.get(id))
+                    continue;
+                throw new CapabilityError('The file-access bucket could not be created.', 'UNAVAILABLE', {
+                    reason: 'file-access-create-failed',
+                    details: { failure: failureDetails(created.failed) }
+                });
+            }
+            const accessCount = existing.accessCount ?? 1;
+            const updated = await attemptWrite(async () => this.normalizeFileAccess(await record.update(id, {
+                accessCount: accessCount + 1,
+                timestamp: at,
+                // Fill identity omitted by an earlier lower-context tracker; keep the newest branch and task.
+                machineId: options.machineId ?? existing.machineId,
+                machineName: options.machineName ?? existing.machineName,
+                participantId: options.participantId ?? existing.participantId,
+                participantSlug: options.participantSlug ?? existing.participantSlug,
+                workspaceRoot: options.workspaceRoot ?? existing.workspaceRoot,
+                gitBranch: options.gitBranch ?? existing.gitBranch,
+                headSha: options.headSha ?? existing.headSha,
+                workItemId: options.workItemId ?? existing.workItemId,
+                workItemTitle: options.workItemTitle ?? existing.workItemTitle
+            }, { where: { accessCount } })));
+            if ('value' in updated)
+                return updated.value;
+            // A concurrent increment won: compare-and-set again against the new count.
+            if (updated.failed.name === 'OptimisticLockError')
+                continue;
+            throw new CapabilityError('The file-access bucket could not be updated.', 'UNAVAILABLE', {
+                reason: 'file-access-update-failed',
+                details: { failure: failureDetails(updated.failed) }
+            });
+        }
+        throw new CapabilityError('A file-access bucket stayed contended after 64 compare-and-set attempts.', 'CONFLICT', {
+            reason: 'file-access-contended',
+            details: { id }
+        });
+    }
+    /**
+     * Cross-session collision read: who ELSE recently touched this path.
+     *
+     * This is a new query rather than a widening of `list()`, which stays
+     * `sessionId`-scoped so no existing caller changes behaviour.
+     *
+     * Noise budget enforced here (see schemas/collision.ts):
+     *  - other sessions only,
+     *  - same workspace only when the caller knows its own workspace,
+     *  - inside the recency window,
+     *  - one entry per peer session (its most recent touch), capped.
+     */
+    async whoElseTouched(input) {
+        const parsed = WhoElseTouchedInputSchema.parse(input);
+        const now = new Date();
+        const since = parsed.since ?? new Date(now.getTime() - DEFAULT_RECENCY_WINDOW_MS);
+        const record = await this.getRecord();
+        // Indexed by idx_file_accesses_path_recent (filePath, timestamp).
+        const filters = {
+            filePath: parsed.filePath,
+            timestamp: { gte: since },
+            sessionId: { ne: parsed.excludeSessionId }
+        };
+        // Preserve legacy rows without workspace identity without fetching foreign
+        // workspaces ahead of the cap. Both reads use the same indexed path/window.
+        const pages = parsed.workspaceRoot
+            ? await Promise.all([
+                record.list({ where: { ...filters, workspaceRoot: parsed.workspaceRoot }, orderBy: { timestamp: 'desc' }, limit: 200, offset: 0 }),
+                record.list({ where: { ...filters, workspaceRoot: { isNull: true } }, orderBy: { timestamp: 'desc' }, limit: 200, offset: 0 })
+            ])
+            : [await record.list({ where: filters, orderBy: { timestamp: 'desc' }, limit: 200, offset: 0 })];
+        const items = pages.flatMap(page => page.items)
+            .sort((left, right) => this.toDate(right.timestamp).getTime() - this.toDate(left.timestamp).getTime());
+        const bySession = new Map();
+        for (const raw of items) {
+            const access = this.normalizeFileAccess(raw);
+            // Never report the caller to itself.
+            if (access.sessionId === parsed.excludeSessionId)
+                continue;
+            // Read-side expiry — no sweep job is involved.
+            const timestamp = this.toDate(access.timestamp);
+            if (timestamp < since)
+                continue;
+            // A different worktree is NOT a collision. Only excludes when the
+            // caller knows its own workspace AND the peer declared one.
+            if (parsed.workspaceRoot &&
+                access.workspaceRoot &&
+                access.workspaceRoot !== parsed.workspaceRoot) {
+                continue;
+            }
+            // Rows are timestamp-desc, so the first hit per session is newest.
+            if (bySession.has(access.sessionId))
+                continue;
+            bySession.set(access.sessionId, {
+                sessionId: access.sessionId,
+                machineId: access.machineId,
+                machineName: access.machineName,
+                participantId: access.participantId,
+                participantSlug: access.participantSlug,
+                workspaceRoot: access.workspaceRoot,
+                gitBranch: access.gitBranch,
+                workItemId: access.workItemId,
+                workItemTitle: access.workItemTitle,
+                operation: access.operation,
+                filePath: access.filePath,
+                timestamp,
+                ageMs: Math.max(0, now.getTime() - timestamp.getTime()),
+                origin: 'local'
+            });
+        }
+        return Array.from(bySession.values())
+            .sort((a, b) => a.ageMs - b.ageMs)
+            .slice(0, parsed.limit);
+    }
+    async get(id) {
+        const record = await this.getRecord();
+        const result = await record.get(id);
+        return result ? this.normalizeFileAccess(result) : null;
+    }
+    async list(options) {
+        const record = await this.getRecord();
+        const result = await record.list({
+            where: { sessionId: options.sessionId },
+            orderBy: { timestamp: 'desc' },
+            limit: options.limit ?? 100,
+            offset: options.offset ?? 0
+        });
+        const normalized = result.items.map((item) => this.normalizeFileAccess(item));
+        return this.filterAccesses(normalized, {
+            operation: options.operation,
+            filePath: options.filePath,
+            since: options.since,
+            until: options.until,
+            limit: options.limit ?? 100,
+            offset: options.offset ?? 0
+        });
+    }
+    /**
+     * Every session's recent touches, for the roster.
+     *
+     * Unlike `list()` this is NOT sessionId-scoped — presence is inherently a
+     * question about other people. Bounded by the window and a row cap so a
+     * busy machine cannot turn `vibes who` into a table scan.
+     */
+    async recentTouches(input) {
+        const record = await this.getRecord();
+        const now = new Date();
+        const result = await record.list({
+            where: { timestamp: { gte: input.since } },
+            orderBy: { timestamp: 'desc' },
+            limit: input.limit ?? 500,
+            offset: 0
+        });
+        const peers = [];
+        for (const raw of result.items) {
+            const access = this.normalizeFileAccess(raw);
+            const timestamp = this.toDate(access.timestamp);
+            // Read-side expiry: the window is the only thing that decides
+            // presence, so no sweep job is ever required.
+            if (timestamp < input.since)
+                continue;
+            peers.push({
+                sessionId: access.sessionId,
+                machineId: access.machineId,
+                machineName: access.machineName,
+                participantId: access.participantId,
+                participantSlug: access.participantSlug,
+                workspaceRoot: access.workspaceRoot,
+                gitBranch: access.gitBranch,
+                workItemId: access.workItemId,
+                workItemTitle: access.workItemTitle,
+                operation: access.operation,
+                filePath: access.filePath,
+                timestamp,
+                ageMs: Math.max(0, now.getTime() - timestamp.getTime()),
+                origin: 'local'
+            });
+        }
+        return peers;
+    }
+    async stats(sessionId, limit = 50) {
+        const accesses = await this.list({ sessionId, limit: 5000, offset: 0 });
+        return this.buildStats(accesses).slice(0, limit);
+    }
+    async summary(sessionId) {
+        const stats = await this.stats(sessionId, 5000);
+        const recentlyEdited = stats.filter((s) => s.editCount > 0 || s.writeCount > 0).slice(0, 20);
+        const recentlyRead = stats.filter((s) => s.readCount > 0).slice(0, 20);
+        const totalAccesses = stats.reduce((sum, s) => sum + s.totalAccesses, 0);
+        return {
+            sessionId,
+            generatedAt: new Date().toISOString(),
+            totalFiles: stats.length,
+            totalAccesses,
+            recentlyEdited,
+            recentlyRead,
+            hotspots: stats.slice(0, 10).map((s) => ({
+                filePath: s.filePath,
+                score: s.relevanceScore,
+                reason: `${s.totalAccesses} accesses`
+            }))
+        };
+    }
+    async delete(id) {
+        const record = await this.getRecord();
+        await record.delete(id);
+    }
+    async deleteSession(sessionId) {
+        const all = await this.list({ sessionId, limit: 5000, offset: 0 });
+        await Promise.all(all.map((entry) => this.delete(entry.id)));
+        return all.length;
+    }
+    /**
+     * Drop touch records older than `retentionDays`.
+     *
+     * THIS USED TO BE UNABLE TO DO ITS JOB. The previous implementation listed
+     * `{ limit: 10000, offset: 0 }` with NO ordering, filtered in JS, and deleted
+     * row by row. Three problems compounded:
+     *
+     *   1. No ordering means the 10k window is whatever the backend returns. If
+     *      that is newest-first, every row in the window is fresh, the filter
+     *      matches nothing, and cleanup reports success having deleted zero —
+     *      forever, no matter how large the table grows.
+     *   2. The 10k cap silently bounded a table that reached 3,182,962 rows.
+     *   3. Row-by-row deletes make the cost proportional to the backlog, which is
+     *      exactly backwards: the worse the problem, the less likely it finishes.
+     *
+     * The record layer already has `deleteMany(where)`, so this is one predicate
+     * evaluated by the store. Ordering stops mattering because nothing is being
+     * sampled — every stale row matches, regardless of what a listing would have
+     * returned first.
+     *
+     * None of that mattered while nothing CALLED this, which was the case until
+     * 2026-08-21. A cleanup routine with zero call sites is invisible: the code
+     * exists, so everyone assumes the behaviour does.
+     */
+    async cleanup(retentionDays) {
+        const cutoff = new Date(Date.now() - retentionDays * 24 * 60 * 60 * 1000);
+        const record = await this.getRecord();
+        const result = await record.deleteMany({ timestamp: { lt: cutoff } });
+        return result.count;
+    }
+}
+// =============================================================================
+// EXTERNAL CLIENT
+// =============================================================================
+/**
+ * Runtime port `VibesRuntime` (Runtime SPEC `./client`): hook calls run
+ * through the Tools invocation pipeline (`invokeTool`: `acquireInvocation`,
+ * `runInvocation`, `assets`, `resolve`), which `RuntimeRef` does not carry.
+ */
+export class ExternalClient extends BaseRuntimeClient {
+    fileAccessStorage = null;
+    backgroundWork = new ExternalLifecycle();
+    fallbackSessionId;
+    deferredAmbientDelivery = new Map();
+    deliveryPaths = new Map();
+    pendingNotices = new Map();
+    collisionDedupe = new Set();
+    touchIdentity = new TouchIdentityCache();
+    cloudProjection;
+    getCloudTouchProjection() {
+        return this.cloudProjection ??= new CloudTouchProjection(this.runtime);
+    }
+    async activateBackgroundWork() {
+        await this.backgroundWork.activate(this.runtime);
+    }
+    ambientSessionId(bound) {
+        if (bound)
+            return bound;
+        return this.fallbackSessionId ??= crypto.randomUUID();
+    }
+    queueNotice(sessionId, entry) {
+        const batches = this.pendingNotices.get(sessionId) ?? [];
+        batches.push(entry);
+        this.pendingNotices.set(sessionId, batches);
+    }
+    drainNotice(sessionId) {
+        const batches = this.drainNoticeBatches(sessionId);
+        if (!batches.length)
+            return null;
+        const notice = batches.flatMap((entry) => entry.notice ? [entry.notice] : []).join('\n');
+        const messages = batches.flatMap((entry) => entry.messages ? [entry.messages] : []).join('\n');
+        const combined = {};
+        if (notice)
+            combined.notice = notice;
+        if (messages)
+            combined.messages = messages;
+        return combined;
+    }
+    drainNoticeBatches(sessionId) {
+        const batches = this.pendingNotices.get(sessionId) ?? [];
+        this.pendingNotices.delete(sessionId);
+        return batches;
+    }
+    rememberDeliveryPaths(sessionId, paths) {
+        const pending = this.deliveryPaths.get(sessionId) ?? new Set();
+        for (const path of paths)
+            pending.add(path);
+        this.deliveryPaths.set(sessionId, pending);
+    }
+    deliveryPathsFor(sessionId) {
+        return [...(this.deliveryPaths.get(sessionId) ?? [])];
+    }
+    clearDeliveryPaths(sessionId) {
+        this.deliveryPaths.delete(sessionId);
+    }
+    /** Hook-internal tools have no independent participant-visible result. */
+    async withDeferredAmbientDelivery(sessionId, run) {
+        this.deferredAmbientDelivery.set(sessionId, (this.deferredAmbientDelivery.get(sessionId) ?? 0) + 1);
+        try {
+            return await run();
+        }
+        finally {
+            const remaining = (this.deferredAmbientDelivery.get(sessionId) ?? 1) - 1;
+            if (remaining > 0)
+                this.deferredAmbientDelivery.set(sessionId, remaining);
+            else
+                this.deferredAmbientDelivery.delete(sessionId);
+        }
+    }
+    ambientDeliveryDeferred(sessionId) {
+        return this.deferredAmbientDelivery.has(sessionId);
+    }
+    onDispose() {
+        this.backgroundWork.dispose();
+        this.cloudProjection?.dispose();
+        this.cloudProjection = undefined;
+        this.collisionDedupe.clear();
+        this.touchIdentity.reset();
+        this.pendingNotices.clear();
+        this.deliveryPaths.clear();
+        this.deferredAmbientDelivery.clear();
+        this.fallbackSessionId = undefined;
+        this.fileAccessStorage = null;
+    }
+    constructor(descriptor = { id: 'external', kind: 'runtime/client', name: 'External Client' }, context, runtime) {
+        super(descriptor, context, runtime);
+    }
+    // Lazy-init file access storage
+    getFileAccessStorage() {
+        if (!this.fileAccessStorage) {
+            this.fileAccessStorage = new FileAccessStorage(this.runtime);
+        }
+        return this.fileAccessStorage;
+    }
+    // =========================================================================
+    // TOOLS
+    // =========================================================================
+    /** The host registered under `toolId`, admitted against the host contract. */
+    host(toolId) {
+        return resolveExternalHostImplementation(this.runtime, toolId);
+    }
+    /** The host registered under `toolId`, or `null` when none is (confirmed absence); any other failure propagates. */
+    async hostIfRegistered(toolId) {
+        try {
+            return await this.host(toolId);
+        }
+        catch (error) {
+            if (CapabilityError.isAbsenceOf(CaughtFailureSchema.parse(error), 'external/host', toolId))
+                return null;
+            throw error;
+        }
+    }
+    /**
+     * Detect a single tool; `null` when no host is registered under `toolId`.
+     */
+    async detectTool(toolId, options) {
+        const externalTool = await this.hostIfRegistered(toolId);
+        if (!externalTool)
+            return null;
+        const result = await externalTool.detect(options?.projectDir);
+        return {
+            id: toolId,
+            name: externalTool.manifest.name,
+            installed: result.installation.installed,
+            version: result.installation.version,
+            installPath: result.installation.installPath,
+            configPath: result.installation.configPath,
+            mcpConfigured: result.mcpState.configured,
+            hasAuthToken: result.mcpState.hasAuthToken,
+            manifest: externalTool.manifest
+        };
+    }
+    /**
+     * Detect all available tools. One host's failed detection is that host's
+     * refusal: it propagates, never silently dropped from the list.
+     */
+    async detectAll(options) {
+        const descriptors = this.runtime.query('external/host').enabled().descriptors();
+        const results = await Promise.all(descriptors.map((d) => this.detectTool(d.id, options)));
+        return results.filter((r) => r !== null);
+    }
+    /**
+     * Get a tool manifest; `null` when no host is registered under `toolId`.
+     */
+    async getTool(toolId) {
+        return (await this.hostIfRegistered(toolId))?.manifest ?? null;
+    }
+    /**
+     * List all available tools
+     */
+    async listTools() {
+        return listExternalHostDescriptors(this.runtime).map((d) => ({ id: d.id, name: d.manifest.name, manifest: d.manifest }));
+    }
+    // =========================================================================
+    // MCP
+    // =========================================================================
+    /**
+     * Install MCP configuration for a tool
+     */
+    async installMcp(options) {
+        return (await this.host(options.tool)).installMcp({
+            global: options.global ?? true,
+            projectDir: options.projectDir,
+            vibesPath: options.vibesPath,
+            authToken: options.authToken,
+            tier: options.tier,
+            mcpClientId: options.mcpClientId,
+            dryRun: options.dryRun ?? false,
+            force: options.force ?? false
+        });
+    }
+    /**
+     * Uninstall MCP configuration for a tool
+     */
+    async uninstallMcp(tool, global, projectDir) {
+        return (await this.host(tool)).uninstallMcp(global ?? true, projectDir);
+    }
+    /**
+     * Check MCP configuration status for a tool
+     */
+    async checkMcp(tool, global, projectDir) {
+        return (await this.host(tool)).checkMcp({ global: global ?? true, projectDir });
+    }
+    /**
+     * Get MCP config path for a tool
+     */
+    async configPath(tool, global, projectDir) {
+        return (await this.host(tool)).getMcpConfigPath(global ?? true, projectDir) ?? null;
+    }
+    /**
+     * Check if MCP is configured for a tool
+     */
+    async isConfigured(tool, global, projectDir) {
+        return (await this.host(tool)).isMcpConfigured(global ?? true, projectDir);
+    }
+    /**
+     * Fix MCP configuration for a tool (reinstall)
+     */
+    async fixMcp(tool, options) {
+        return (await this.host(tool)).fixMcp({
+            global: options?.global ?? true,
+            projectDir: options?.projectDir,
+            authToken: options?.authToken,
+            dryRun: options?.dryRun ?? false
+        });
+    }
+    // =========================================================================
+    // HOOKS
+    // =========================================================================
+    /**
+     * Install hooks for a tool
+     */
+    async installHooks(options) {
+        return (await this.host(options.tool)).installHooks({
+            global: options.global ?? true,
+            projectDir: options.projectDir,
+            dryRun: options.dryRun ?? false,
+            force: options.force ?? false,
+            hooks: options.hooks,
+            vibesPath: options.vibesPath
+        });
+    }
+    /**
+     * Uninstall hooks for a tool
+     */
+    async uninstallHooks(tool, global, projectDir) {
+        return (await this.host(tool)).uninstallHooks(global ?? true, projectDir);
+    }
+    /**
+     * List installed hooks for a tool: the entries of its hooks directory, read
+     * through the runtime filesystem (`[]` when the host has none or it is absent).
+     */
+    async listHooks(tool, global, projectDir) {
+        const dir = (await this.host(tool)).getHooksDir(global ?? true, projectDir);
+        if (!dir)
+            return [];
+        return listNamesIfPresent(await externalFileSystem(this.runtime), dir);
+    }
+    /**
+     * Get hooks directory for a tool
+     */
+    async hooksDir(tool, global, projectDir) {
+        return (await this.host(tool)).getHooksDir(global ?? true, projectDir) ?? null;
+    }
+    /**
+     * Call a hook event (unified handler)
+     */
+    async callHook(event, target, caller) {
+        // Through invokeTool like every surface: validated input (`target`, not the
+        // old `toolId` the schema rejected), hook-bus events, and the caller as the
+        // invocation actor.
+        const { invokeTool } = await import('@vibesdotdev/tools/execution/invoke');
+        const input = { action: 'hook-call', event };
+        if (target)
+            input.target = target;
+        const ctx = {
+            callId: `external-hook-${crypto.randomUUID()}`,
+            logger: getLogger('external.hooks', this.runtime)
+        };
+        if (caller)
+            ctx.caller = caller;
+        const result = await invokeTool({
+            runtime: this.runtime,
+            toolId: 'external',
+            input,
+            ctx
+        });
+        return { success: true, message: ToolReceiptSchema.parse(result).message };
+    }
+    // =========================================================================
+    // SKILLS
+    // =========================================================================
+    /**
+     * Generate skills for a tool
+     */
+    async generateSkills(options) {
+        return (await this.host(options.tool)).generateSkills({
+            global: options.global ?? true,
+            projectDir: options.projectDir,
+            outputDir: options.outputDir,
+            filter: options.filter,
+            dryRun: options.dryRun ?? false,
+            includeTools: options.includeTools ?? false
+        });
+    }
+    /**
+     * Preview skill names for a tool
+     */
+    async previewSkills(_tool, filter, 
+    /** See {@link GenerateSkillsOptions.includeTools} — empty preview without it. */
+    includeTools = false) {
+        const { previewSkillNames } = await import('@vibesdotdev/tools/adapters/skill/consumer/node/generator');
+        const ids = filter?.length ? filter : undefined;
+        return previewSkillNames(this.runtime, ids ? { ids } : undefined, {
+            includeTools,
+            targetId: _tool
+        });
+    }
+    /**
+     * Get skills directory for a tool
+     */
+    async skillsDir(tool, global, projectDir) {
+        return (await this.host(tool)).getSkillsDir(global ?? true, projectDir) ?? null;
+    }
+    // =========================================================================
+    // FILE ACCESS
+    // =========================================================================
+    /**
+     * Track a file access
+     */
+    async trackFileAccess(options) {
+        return this.getFileAccessStorage().track(options);
+    }
+    /**
+     * Get file access by ID
+     */
+    async getFileAccess(id) {
+        return this.getFileAccessStorage().get(id);
+    }
+    /**
+     * Who ELSE recently touched this path — the ambient collision read.
+     *
+     * Returns at most one entry per peer session (its most recent touch),
+     * newest first, already filtered to the recency window and (when the
+     * caller supplies its own `workspaceRoot`) to the same workspace.
+     *
+     * Callers should treat this as best-effort: it exists to inform an edit,
+     * never to gate one.
+     */
+    async whoElseTouched(input) {
+        return this.getFileAccessStorage().whoElseTouched(input);
+    }
+    /**
+     * The roster — every live agent session visible to this linked account.
+     *
+     * Account provider rows are authoritative across environments. The local
+     * touch stream remains an offline/backward-compatible liveness source, but
+     * it no longer defines the product boundary by itself. Rows merge by caller
+     * seat `(session, participant-or-agent)` and expire at read time, so shared
+     * rooms remain distinct and a crashed agent becomes a ghost without a sweep.
+     */
+    async roster(input = {}) {
+        const now = input.now ?? new Date();
+        const since = new Date(now.getTime() - RECENT_WINDOW_MS);
+        const current = await announceCurrentAgentSession(this.runtime, now);
+        const provider = await resolveAgentRosterProvider(this.runtime);
+        const [touches, accountAnnouncements] = await Promise.all([
+            this.getFileAccessStorage().recentTouches({ since }),
+            provider ? provider.list() : Promise.resolve([])
+        ]);
+        return mergeRosterEntries([
+            ...rosterFromTouches(touches, {
+                now,
+                exclude: input.exclude,
+                excludeSessionId: input.excludeSessionId
+            }),
+            ...rosterFromAnnouncements(accountAnnouncements, {
+                now,
+                exclude: input.exclude,
+                excludeSessionId: input.excludeSessionId
+            }),
+            ...(current
+                ? rosterFromAnnouncements([current], {
+                    now,
+                    exclude: input.exclude,
+                    excludeSessionId: input.excludeSessionId
+                })
+                : [])
+        ], now);
+    }
+    /**
+     * List file accesses for a session
+     */
+    async listFileAccesses(options) {
+        return this.getFileAccessStorage().list(options);
+    }
+    /**
+     * Get file access statistics for a session
+     */
+    async fileAccessStats(sessionId, limit) {
+        return this.getFileAccessStorage().stats(sessionId, limit);
+    }
+    /**
+     * Get file access summary for a session
+     */
+    async fileAccessSummary(sessionId) {
+        return this.getFileAccessStorage().summary(sessionId);
+    }
+    /**
+     * Delete a file access record
+     */
+    async deleteFileAccess(id) {
+        return this.getFileAccessStorage().delete(id);
+    }
+    /**
+     * Delete all file accesses for a session
+     */
+    async deleteSessionFileAccesses(sessionId) {
+        return this.getFileAccessStorage().deleteSession(sessionId);
+    }
+    /**
+     * Cleanup old file accesses
+     */
+    async cleanupOldFileAccesses(retentionDays) {
+        return this.getFileAccessStorage().cleanup(retentionDays);
+    }
+    // =========================================================================
+    // CONTEXT SUMMARY
+    // =========================================================================
+    /**
+     * Generate a context summary for a session
+     */
+    async generateContextSummary(options) {
+        const result = await (await this.externalTool()).execute({
+            action: 'context-summary',
+            sessionId: options.sessionId,
+            format: options.format ?? 'markdown',
+            maxFiles: options.maxFiles ?? 15,
+            includeTodos: options.includeTodos ?? true,
+            includeScratchpad: options.includeScratchpad ?? true,
+            includeCodeContext: options.includeCodeContext ?? false,
+            timeWindowHours: options.timeWindowHours ?? 24,
+            customInstructions: options.customInstructions
+        });
+        return ToolReceiptSchema.parse(result);
+    }
+    /** The unified `external` tool, admitted against the shape this client calls. */
+    async externalTool() {
+        const parsed = ExternalToolImplementationSchema.safeParse(await this.runtime.query('tools/tool').withId('external').resolve());
+        if (!parsed.success) {
+            throw new CapabilityError('The external tool implementation has no execute().', 'INVALID_INPUT', {
+                reason: 'external-tool-invalid',
+                retryable: false
+            });
+        }
+        return parsed.data;
+    }
+    // =========================================================================
+    // PRESETS
+    // =========================================================================
+    /**
+     * List available presets
+     */
+    async listPresets() {
+        return listRuntimePresets(this.runtime).map(({ id, name, description }) => ({
+            id,
+            name,
+            description
+        }));
+    }
+    /**
+     * Get a preset by ID
+     */
+    async getPreset(id) {
+        return listRuntimePresets(this.runtime).find((preset) => preset.id === id) ?? null;
+    }
+    /**
+     * Apply a preset
+     */
+    async applyPreset(options) {
+        const result = await (await this.externalTool()).execute({
+            action: 'install',
+            preset: options.presetId,
+            global: options.global ?? true,
+            projectDir: options.projectDir,
+            dryRun: options.dryRun ?? false
+        });
+        return ExecutionResultSchema.parse(result);
+    }
+    /**
+     * Export a preset
+     */
+    async exportPreset(id) {
+        const preset = await this.getPreset(id);
+        if (!preset) {
+            throw new CapabilityError(`Preset not found: ${id}`, 'NOT_FOUND', { reason: 'preset-not-found', retryable: false });
+        }
+        return JSON.stringify(preset, null, 2);
+    }
+    // =========================================================================
+    // CONFIG
+    // =========================================================================
+    /**
+     * Read external config through its config manifest; schema defaults apply
+     * when nothing is stored. A runtime composing no External config manifest
+     * is refused `NOT_FOUND` `config-manifest-unregistered`.
+     */
+    async readConfig() {
+        return ConfigManifest.forRuntime(this.runtime, 'external').load();
+    }
+    /**
+     * Write external config through its config manifest.
+     */
+    async writeConfig(data) {
+        await ConfigManifest.forRuntime(this.runtime, 'external').save(data);
+    }
+}
+// =============================================================================
+// SINGLETON ACCESSOR
+// =============================================================================
+/** Resolve through the kernel on every call; the kernel owns identity and lifetime. */
+export function getVibesExternalClient(runtime) {
+    return getVibesClient('external', runtime);
+}
+/**
+ * Compatibility entrypoint. The former wrapper-cache reset never reset the
+ * kernel client, its lifecycle resources, or stored data. With no wrapper cache,
+ * there is nothing to invalidate. Dispose the owning runtime to end its lifetime.
+ */
+export function resetExternalClient(_runtime) { }
+//# sourceMappingURL=external-client.js.map