@xingular/harness 0.1.7 → 1.1.1

package/dist/sdk/history/trajectory.js

@@ -0,0 +1,216 @@
+import { invalid, notFound } from "../core/errors.js";
+import { listProjects } from "../core/projects.js";
+import { compareText } from "../core/text.js";
+import { scrub } from "../accounts/store.js";
+import { scrubSensitive } from "../mcp/connections.js";
+import { isActiveStatus, runStatusSchema } from "../sessions/contracts.js";
+import { readAllRuns } from "../sessions/runIndex.js";
+import { findRun, snapshot } from "../sessions/runStore.js";
+const SEARCH_DEFAULT = 10;
+const SEARCH_MAX = 30;
+const READ_DEFAULT = 8;
+const READ_MAX = 10;
+const EVENT_MAX_CHARS = 18_000;
+const PAGE_MAX_CHARS = 48_000;
+function textParam(params, key) {
+    const value = params?.[key];
+    return typeof value === 'string' ? value.trim() : '';
+}
+function boundedInteger(params, key, fallback, minimum, maximum) {
+    const value = params?.[key];
+    if (value === undefined)
+        return fallback;
+    if (typeof value !== 'number' || !Number.isInteger(value) || value < minimum || value > maximum) {
+        throw invalid(`${key} must be an integer from ${minimum} to ${maximum}.`);
+    }
+    return value;
+}
+function dateValue(params, key) {
+    const value = textParam(params, key);
+    if (!value)
+        return null;
+    if (!/^\d{4}-\d{2}-\d{2}(?:T.*)?$/.test(value))
+        throw invalid(`${key} must be a YYYY-MM-DD date or ISO timestamp.`);
+    const timestamp = Date.parse(/^\d{4}-\d{2}-\d{2}$/.test(value) ? `${value}${key === 'until' ? 'T23:59:59.999Z' : 'T00:00:00.000Z'}` : value);
+    if (!Number.isFinite(timestamp))
+        throw invalid(`${key} must be a valid date or ISO timestamp.`);
+    return { text: value, timestamp };
+}
+function decodeCursor(value) {
+    if (!value)
+        return null;
+    try {
+        const parsed = JSON.parse(Buffer.from(value, 'base64url').toString('utf8'));
+        if (typeof parsed.startedAt !== 'string' || !parsed.startedAt || typeof parsed.id !== 'string' || !parsed.id)
+            throw new Error('invalid cursor');
+        return { startedAt: parsed.startedAt, id: parsed.id };
+    }
+    catch {
+        throw invalid('The trajectory cursor is invalid. Start a new search without it.');
+    }
+}
+function encodeCursor(run) {
+    return Buffer.from(JSON.stringify({ startedAt: run.startedAt, id: run.id })).toString('base64url');
+}
+function hidden(env, context, run) {
+    const excluded = context.recallExcludeAgents ?? [];
+    if (!excluded.length)
+        return false;
+    return excluded.includes(run.agentId ?? '') || excluded.includes(run.sessionId) || excluded.includes(env.directory.sessionAgent(run.sessionId) ?? '');
+}
+function afterCursor(run, cursor) {
+    return run.startedAt < cursor.startedAt || (run.startedAt === cursor.startedAt && run.id < cursor.id);
+}
+function summary(env, run, projects) {
+    const project = projects.find((entry) => entry.id === run.projectId);
+    const goal = run.goal?.trim() ?? '';
+    return {
+        id: run.id,
+        agentId: run.agentId,
+        agentName: run.agentId ? env.directory.agentName(run.agentId) : null,
+        project: project ? { id: project.id, name: project.name, slug: project.slug } : null,
+        mode: run.mode,
+        status: run.status,
+        goal: goal.length > 500 ? `${goal.slice(0, 497)}…` : goal || null,
+        startedAt: run.startedAt,
+        endedAt: run.endedAt,
+        parentRunId: run.parentRunId,
+        relation: run.relation
+    };
+}
+/** `trajectory.search`: structured list/search over the current Harness data root. */
+export function searchTool(env, context, params) {
+    const agent = textParam(params, 'agent');
+    const projectKey = textParam(params, 'project');
+    const mode = textParam(params, 'mode');
+    const status = textParam(params, 'status');
+    const since = dateValue(params, 'since');
+    const until = dateValue(params, 'until');
+    const limit = boundedInteger(params, 'limit', SEARCH_DEFAULT, 1, SEARCH_MAX);
+    const cursor = decodeCursor(textParam(params, 'cursor'));
+    if (status && !runStatusSchema.safeParse(status).success)
+        throw invalid(`Unknown run status ${status}.`);
+    const projects = listProjects(env.root);
+    const project = projectKey ? projects.find((entry) => entry.id === projectKey || entry.slug === projectKey || entry.name.toLowerCase() === projectKey.toLowerCase()) : null;
+    if (projectKey && !project)
+        throw invalid(`There is no project called ${projectKey}.`);
+    const matching = readAllRuns(env.root)
+        .filter((run) => !hidden(env, context, run))
+        .filter((run) => !agent || run.agentId === agent || (run.agentId !== null && env.directory.agentName(run.agentId)?.toLowerCase() === agent.toLowerCase()))
+        .filter((run) => !projectKey || run.projectId === project?.id)
+        .filter((run) => !mode || run.mode === mode)
+        .filter((run) => !status || run.status === status)
+        .filter((run) => !since || Date.parse(run.startedAt) >= since.timestamp)
+        .filter((run) => !until || Date.parse(run.startedAt) <= until.timestamp)
+        .filter((run) => !cursor || afterCursor(run, cursor))
+        .sort((left, right) => compareText(right.startedAt, left.startedAt) || compareText(right.id, left.id));
+    const page = matching.slice(0, limit);
+    const hasMore = matching.length > page.length;
+    return JSON.stringify({
+        runs: page.map((run) => summary(env, run, projects)),
+        hasMore,
+        nextCursor: hasMore && page.length ? encodeCursor(page[page.length - 1]) : null
+    });
+}
+function boundedValue(value, path, truncated, stringLimit, arrayLimit, depth = 0) {
+    if (typeof value === 'string') {
+        const fieldLimit = path.endsWith('.systemPrompt') || path.endsWith('.contextUpdate') ? Math.min(12_000, stringLimit) :
+            path.endsWith('.input') || path.endsWith('.output') || path.endsWith('.summary') ? Math.min(10_000, stringLimit) : stringLimit;
+        if (value.length <= fieldLimit)
+            return value;
+        truncated.push(path);
+        return `${value.slice(0, Math.max(0, fieldLimit - 16))}… [truncated]`;
+    }
+    if (Array.isArray(value)) {
+        const kept = value.slice(0, arrayLimit).map((item, index) => boundedValue(item, `${path}[${index}]`, truncated, stringLimit, arrayLimit, depth + 1));
+        if (value.length > arrayLimit)
+            truncated.push(path);
+        return kept;
+    }
+    if (!value || typeof value !== 'object' || depth >= 8)
+        return value;
+    const entries = Object.entries(value);
+    const kept = entries.slice(0, 40).map(([key, item]) => [key, boundedValue(item, `${path}.${key}`, truncated, stringLimit, arrayLimit, depth + 1)]);
+    if (entries.length > 40)
+        truncated.push(path);
+    return Object.fromEntries(kept);
+}
+function publicEvent(event) {
+    let stringLimit = 12_000;
+    let arrayLimit = 20;
+    while (true) {
+        const truncated = [];
+        const omitted = [];
+        let payload = scrubSensitive(event.payload);
+        if (event.type === 'account.status' && payload && typeof payload === 'object' && !Array.isArray(payload)) {
+            const account = payload;
+            if (Object.hasOwn(account, 'accountId')) {
+                delete account.accountId;
+                omitted.push('payload.accountId');
+            }
+            if (typeof account.message === 'string')
+                account.message = scrub(account.message);
+        }
+        if (event.type === 'usage.updated' && payload && typeof payload === 'object' && !Array.isArray(payload)) {
+            const request = payload.request;
+            if (request && typeof request === 'object' && !Array.isArray(request) && Object.hasOwn(request, 'reasoningSummary')) {
+                delete request.reasoningSummary;
+                omitted.push('payload.request.reasoningSummary');
+            }
+        }
+        const value = {
+            id: event.id,
+            sequence: event.sequence,
+            timestamp: event.timestamp,
+            type: event.type,
+            payload: boundedValue(payload, 'payload', truncated, stringLimit, arrayLimit)
+        };
+        if (event.coalescedFrom !== undefined)
+            value.coalescedFrom = event.coalescedFrom;
+        if (truncated.length)
+            value.truncatedFields = truncated.slice(0, 40);
+        if (omitted.length)
+            value.omittedFields = omitted;
+        if (JSON.stringify(value).length <= EVENT_MAX_CHARS || (stringLimit <= 500 && arrayLimit <= 1))
+            return value;
+        stringLimit = Math.max(500, Math.floor(stringLimit / 2));
+        arrayLimit = Math.max(1, Math.floor(arrayLimit / 2));
+    }
+}
+/** `trajectory.read`: a bounded page of the events that affected a run. */
+export function readTool(env, context, params) {
+    const requested = textParam(params, 'run');
+    if (!requested)
+        throw invalid('Give a run id or "current".');
+    const runId = requested === 'current' ? context.runId ?? '' : requested;
+    if (!runId)
+        throw invalid('This caller has no current run.');
+    const run = findRun(env.root, runId);
+    if (!run || hidden(env, context, run))
+        throw notFound('Run');
+    const afterSequence = boundedInteger(params, 'afterSequence', -1, -1, Number.MAX_SAFE_INTEGER);
+    const limit = boundedInteger(params, 'limit', READ_DEFAULT, 1, READ_MAX);
+    const captured = snapshot(env.root, run.id);
+    const candidates = captured.events.filter((event) => event.sequence > afterSequence);
+    const events = [];
+    let eventChars = 0;
+    for (const event of candidates.slice(0, limit)) {
+        const bounded = publicEvent(event);
+        const size = JSON.stringify(bounded).length;
+        if (events.length && eventChars + size > PAGE_MAX_CHARS)
+            break;
+        events.push(bounded);
+        eventChars += size;
+    }
+    const lastSequence = events.length ? Number(events[events.length - 1].sequence) : afterSequence;
+    const hasMore = candidates.some((event) => event.sequence > lastSequence);
+    const projects = listProjects(env.root);
+    const result = {
+        run: summary(env, captured.run, projects),
+        active: isActiveStatus(captured.run.status),
+        events,
+        hasMore,
+        nextAfterSequence: lastSequence
+    };
+    return JSON.stringify(result);
+}

package/dist/sdk/hub/catalog.json

@@ -0,0 +1,123 @@
+{
+    "schemaVersion": 1,
+    "entries": [
+        {
+            "id": "xingular/evidence-first",
+            "title": "Evidence first",
+            "description": "Keep observations, inferences, and unknowns distinct.",
+            "publisher": "Xingular",
+            "license": "MIT",
+            "version": "1.0.0",
+            "category": "rule",
+            "channel": "official",
+            "tags": [
+                "rule"
+            ],
+            "requires": {
+                "harness": "0.1.6"
+            },
+            "sourceUrl": "https://github.com/tanntnny/xingular-hub/tree/main/entries/xingular/evidence-first/1.0.0",
+            "delivery": {
+                "kind": "registry",
+                "registryKind": "rules",
+                "url": "https://raw.githubusercontent.com/tanntnny/xingular-hub/main/entries/xingular/evidence-first/1.0.0/payload.json",
+                "sha256": "0f77661ea41e27bcb51aad982d15d493b893c5c1ba1eb6046a21315ddac07c5b",
+                "bundled": "{\n  \"items\": [\n    {\n      \"name\": \"hub-evidence-first\",\n      \"files\": [\n        {\n          \"path\": \"CONTENT.md\",\n          \"encoding\": \"utf8\",\n          \"content\": \"---\\nname: Evidence first\\ndescription: Distinguish observations, inferences, and unknowns.\\n---\\n\\nSupport factual claims with inspectable evidence. Label inferences and uncertainties. Correct a claim when better evidence changes it.\\n\"\n        }\n      ]\n    }\n  ]\n}\n"
+            }
+        },
+        {
+            "id": "xingular/github-connector",
+            "title": "GitHub connector",
+            "description": "A setup recipe for the GitHub MCP server; provide your own credentials.",
+            "publisher": "Xingular",
+            "license": "MIT",
+            "version": "1.0.0",
+            "category": "connector",
+            "channel": "official",
+            "tags": [
+                "connector"
+            ],
+            "requires": {
+                "harness": "0.1.6"
+            },
+            "sourceUrl": "https://github.com/tanntnny/xingular-hub/tree/main/entries/xingular/github-connector/1.0.0",
+            "delivery": {
+                "kind": "document",
+                "url": "https://raw.githubusercontent.com/tanntnny/xingular-hub/main/entries/xingular/github-connector/1.0.0/payload.json",
+                "sha256": "ec5bd9675e2977b9d880cf81732d84ac72b04af271048499415eaa6288896223",
+                "bundled": "{\n  \"id\": \"github-hub\",\n  \"name\": \"GitHub\",\n  \"description\": \"Repositories, issues, and pull requests\",\n  \"kind\": \"remote\",\n  \"docsUrl\": \"https://github.com/github/github-mcp-server\",\n  \"url\": \"https://api.githubcopilot.com/mcp/\",\n  \"auth\": \"headers\",\n  \"oauth\": null,\n  \"fields\": [\n    {\n      \"header\": \"Authorization\",\n      \"label\": \"Personal access token\",\n      \"prefix\": \"Bearer \",\n      \"help\": \"Provide a token for only the repositories and permissions you need.\"\n    }\n  ],\n  \"setup\": [\n    \"Create a personal access token in GitHub with the access you want to grant.\",\n    \"Review the connection before enabling it.\"\n  ],\n  \"notice\": null,\n  \"provenance\": null,\n  \"suggestedReadTools\": []\n}\n"
+            }
+        },
+        {
+            "id": "xingular/research-starter",
+            "title": "Research starter",
+            "description": "A starting agent for comparing sources and writing supported answers.",
+            "publisher": "Xingular",
+            "license": "MIT",
+            "version": "1.0.0",
+            "category": "agent-template",
+            "channel": "official",
+            "tags": [
+                "agent-template"
+            ],
+            "requires": {
+                "harness": "0.1.6"
+            },
+            "sourceUrl": "https://github.com/tanntnny/xingular-hub/tree/main/entries/xingular/research-starter/1.0.0",
+            "delivery": {
+                "kind": "document",
+                "url": "https://raw.githubusercontent.com/tanntnny/xingular-hub/main/entries/xingular/research-starter/1.0.0/payload.json",
+                "sha256": "a2f672583df6f4049cc153ba1e173192301220e5f8817f9ad5a4fe87af25f52b",
+                "bundled": "{\n  \"schemaVersion\": 1,\n  \"id\": \"research-starter\",\n  \"title\": \"Research starter\",\n  \"description\": \"Compare sources and explain the evidence behind an answer.\",\n  \"version\": \"1.0.0\",\n  \"author\": \"Xingular\",\n  \"license\": \"MIT\",\n  \"agent\": {\n    \"name\": \"Research starter\",\n    \"icon\": {\n      \"kind\": \"mascot\",\n      \"shape\": \"prism\",\n      \"color\": \"violet\",\n      \"material\": \"glass\"\n    },\n    \"description\": \"Investigates questions with sources.\",\n    \"instructions\": \"Help the user investigate a question. Start with reliable sources, explain what the evidence supports, cite the sources, and state unresolved questions. Ask the user when their goal is unclear.\",\n    \"model\": null,\n    \"effort\": \"high\",\n    \"tools\": [\n      \"read\",\n      \"grep\",\n      \"find\",\n      \"ls\",\n      \"web_search\",\n      \"web_fetch\"\n    ]\n  },\n  \"skills\": [],\n  \"connections\": []\n}\n"
+            }
+        },
+        {
+            "id": "xingular/source-review",
+            "title": "Review a source",
+            "description": "Check who wrote a source, what it supports, and what remains uncertain.",
+            "publisher": "Xingular",
+            "license": "MIT",
+            "version": "1.0.0",
+            "category": "skill",
+            "channel": "official",
+            "tags": [
+                "skill"
+            ],
+            "requires": {
+                "harness": "0.1.6"
+            },
+            "sourceUrl": "https://github.com/tanntnny/xingular-hub/tree/main/entries/xingular/source-review/1.0.0",
+            "delivery": {
+                "kind": "registry",
+                "registryKind": "skills",
+                "url": "https://raw.githubusercontent.com/tanntnny/xingular-hub/main/entries/xingular/source-review/1.0.0/payload.json",
+                "sha256": "bb0617889ee1ca39611a10952bec3086fa3986e9ce10a809c473c57acf47bc07",
+                "bundled": "{\n  \"items\": [\n    {\n      \"name\": \"hub-source-review\",\n      \"files\": [\n        {\n          \"path\": \"SKILL.md\",\n          \"encoding\": \"utf8\",\n          \"content\": \"---\\nname: hub-source-review\\ndescription: Review the evidence behind a source before using its claims.\\n---\\n\\n# Review a source\\n\\nRecord its author and date. Identify the original evidence. Write what the source supports and which uncertainties remain. Cite the source so the reader can inspect it.\\n\"\n        }\n      ]\n    }\n  ]\n}\n"
+            }
+        },
+        {
+            "id": "xingular/summarize-source",
+            "title": "Summarize a source",
+            "description": "Summarize a provided source and explain its limitations.",
+            "publisher": "Xingular",
+            "license": "MIT",
+            "version": "1.0.0",
+            "category": "prompt",
+            "channel": "official",
+            "tags": [
+                "prompt"
+            ],
+            "requires": {
+                "harness": "0.1.6"
+            },
+            "sourceUrl": "https://github.com/tanntnny/xingular-hub/tree/main/entries/xingular/summarize-source/1.0.0",
+            "delivery": {
+                "kind": "registry",
+                "registryKind": "prompts",
+                "url": "https://raw.githubusercontent.com/tanntnny/xingular-hub/main/entries/xingular/summarize-source/1.0.0/payload.json",
+                "sha256": "12a646d474fe3cd822970869c972d1d9400c7f6350388dc735dce5c31a22680a",
+                "bundled": "{\n  \"items\": [\n    {\n      \"name\": \"hub-summarize-source\",\n      \"files\": [\n        {\n          \"path\": \"CONTENT.md\",\n          \"encoding\": \"utf8\",\n          \"content\": \"---\\nname: summarize-source\\ndescription: Summarize the supplied source and its limits.\\n---\\n\\nSummarize the source below. Include its main claims, supporting evidence, limitations, and questions it leaves unanswered.\\n\\n$@\\n\"\n        }\n      ]\n    }\n  ]\n}\n"
+            }
+        }
+    ]
+}

package/dist/sdk/hub/cli.d.ts

@@ -0,0 +1,7 @@
+import { Harness, type HarnessOptions } from "../harness.js";
+export declare const HUB_USAGE = "Usage: xagent hub <list | show | install> [id@version] [options]\n\n  list [--refresh]             Browse the curated catalog and locally installed versions\n  show <id@version>            Show publisher, license, source, and delivery details\n  install <id@version>         Install the exact reviewed version, disabled and untrusted\n\n  --data <dir>                 Target data library (default: ~/.xingular-harness/data)\n  --state <dir>                Target device state (default: ~/.xingular-harness/state)\n  --refresh                    Refresh the public catalog; cached items remain usable offline\n";
+export declare function runHubCli(argv: string[], dependencies?: {
+    home?: string;
+    write?: (text: string) => void;
+    createHarness?: (options: HarnessOptions) => Harness;
+}): Promise<number>;

package/dist/sdk/hub/cli.js

@@ -0,0 +1,81 @@
+import { homedir } from 'node:os';
+import { join, resolve } from 'node:path';
+import { Harness } from "../harness.js";
+export const HUB_USAGE = `Usage: xagent hub <list | show | install> [id@version] [options]
+
+  list [--refresh]             Browse the curated catalog and locally installed versions
+  show <id@version>            Show publisher, license, source, and delivery details
+  install <id@version>         Install the exact reviewed version, disabled and untrusted
+
+  --data <dir>                 Target data library (default: ~/.xingular-harness/data)
+  --state <dir>                Target device state (default: ~/.xingular-harness/state)
+  --refresh                    Refresh the public catalog; cached items remain usable offline
+`;
+export async function runHubCli(argv, dependencies = {}) {
+    const write = dependencies.write ?? ((text) => void process.stdout.write(text));
+    const args = [];
+    const values = {};
+    let refresh = false;
+    for (let index = 0; index < argv.length; index += 1) {
+        const arg = argv[index];
+        if (arg === '--refresh')
+            refresh = true;
+        else if (arg === '--data' || arg === '--state') {
+            const value = argv[++index];
+            if (!value || value.startsWith('--')) {
+                write(`${arg} needs a directory.\n`);
+                return 2;
+            }
+            values[arg.slice(2)] = resolve(value);
+        }
+        else if (arg.startsWith('--')) {
+            write(`Unknown option ${arg}.\n`);
+            return 2;
+        }
+        else
+            args.push(arg);
+    }
+    const [command, target] = args;
+    if (!command || command === 'help') {
+        write(HUB_USAGE);
+        return 0;
+    }
+    if (!['list', 'show', 'install'].includes(command)) {
+        write(HUB_USAGE);
+        return 2;
+    }
+    const root = join(dependencies.home ?? homedir(), '.xingular-harness');
+    const options = { dataRoot: values.data ?? join(root, 'data'), stateDir: values.state ?? join(root, 'state') };
+    const harness = dependencies.createHarness?.(options) ?? new Harness(options);
+    try {
+        const overview = await harness.hub.list(refresh);
+        if (overview.error)
+            write(`Catalog refresh failed: ${overview.error} Using ${overview.origin} content.\n`);
+        if (command === 'list') {
+            write(`Library: ${options.dataRoot}\n${overview.entries.map((entry) => `${entry.id}@${entry.version}  ${entry.category}  ${entry.title}${overview.installed.some((receipt) => receipt.entry.id === entry.id && receipt.entry.version === entry.version) ? ' · installed' : ''}`).join('\n')}\n`);
+            return 0;
+        }
+        const split = target?.lastIndexOf('@') ?? -1;
+        if (!target || split < 1)
+            throw new Error('Name an exact item as publisher/name@version. Run hub list to see versions.');
+        const id = target.slice(0, split);
+        const version = target.slice(split + 1);
+        const entry = await harness.hub.get(id, version);
+        if (command === 'show') {
+            const { bundled: _bundled, ...delivery } = entry.delivery.kind === 'pi-package' ? { ...entry.delivery, bundled: undefined } : entry.delivery;
+            write(`${entry.title} (${target})\n${entry.description}\nPublisher: ${entry.publisher}\nLicense: ${entry.license}\nSource: ${entry.sourceUrl}\nDelivery: ${JSON.stringify(delivery)}\n`);
+        }
+        else {
+            const receipt = await harness.hub.install(id, version);
+            write(receipt.document ? `Saved ${target} in ${options.dataRoot}/hub/documents/${receipt.document}. Open this library in a compatible application to apply it.\n` : `Installed ${target}, switched off. Attach it separately${entry.delivery.kind === 'pi-package' ? ' and review/trust any code' : ''} before using it.\n`);
+        }
+        return 0;
+    }
+    catch (error) {
+        write(`${error instanceof Error ? error.message : String(error)}\n`);
+        return 1;
+    }
+    finally {
+        await harness.close();
+    }
+}

package/dist/sdk/hub/hub.d.ts

@@ -0,0 +1,74 @@
+import type { Harness } from "../harness.js";
+import { type HubCatalog, type HubEntry, type HubOverview, type HubReceipt } from "./schema.js";
+export interface HubOptions {
+    catalogUrl?: string;
+    catalog?: HubCatalog;
+    fetch?: typeof globalThis.fetch;
+}
+/** Catalog data never loads extensions or changes attachment, trust, or connector scopes. */
+export declare class Hub {
+    private readonly harness;
+    private readonly fallback;
+    private readonly fetcher;
+    private readonly catalogUrl;
+    private watcher;
+    private refresh;
+    private installing;
+    private cachedPayload;
+    get busy(): boolean;
+    constructor(harness: Harness, options?: HubOptions);
+    private receipts;
+    private snapshot;
+    private receiptState;
+    private present;
+    list(refresh?: boolean): Promise<HubOverview>;
+    private bytes;
+    private refreshCatalog;
+    private decode;
+    private find;
+    get(id: string, version: string, preview?: boolean): Promise<HubEntry>;
+    private verifiedPayload;
+    preview(id: string, version: string, offset?: number): Promise<{
+        entry: {
+            id: string;
+            title: string;
+            description: string;
+            publisher: string;
+            license: string;
+            version: string;
+            category: string;
+            channel: "official" | "community";
+            tags: string[];
+            requires: Record<string, string>;
+            sourceUrl: string;
+            delivery: {
+                url: string;
+                sha256: string;
+                kind: "registry";
+                registryKind: "skills" | "prompts" | "rules";
+                bundled?: string | undefined;
+            } | {
+                url: string;
+                sha256: string;
+                kind: "document";
+                bundled?: string | undefined;
+            } | {
+                kind: "pi-package";
+                source: string;
+            };
+        };
+        content: string;
+        offset: number;
+        nextOffset: number;
+        totalBytes: number;
+        done: boolean;
+    }>;
+    install(id: string, version: string): Promise<HubReceipt>;
+    uninstall(id: string, version: string): Promise<HubReceipt>;
+    readDocument(id: string, version: string): {
+        entry: HubEntry;
+        content: string;
+    };
+    watch(root: string): void;
+    close(): void;
+}