qlogicagent 2.13.3 → 2.13.5

package/dist/cli/handlers/community-handler.js

@@ -0,0 +1,671 @@
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import { getUserSettingsPath } from "../../runtime/infra/agent-paths.js";
+import { createDefaultCommunityConsentClient, normalizeCommunityConsent, } from "../../runtime/community/community-consent-client.js";
+import { sanitizeCommunityTelemetryMetadata } from "../../runtime/community/community-telemetry-metadata.js";
+import { publishCommunityPetAsset } from "../../runtime/community/community-pet-publisher.js";
+import { AGENT_RPC_ERROR_CODES } from "../../protocol/wire/index.js";
+import { installCommunityResource } from "../community-resource-installer.js";
+import { installRuntimeDependency, probeRuntimeDependency } from "../runtime-dependency-catalog.js";
+import { listCommunityPublishAuditEntries } from "../turn-skill-autopersist.js";
+const COMMUNITY_CONSENT_KEY = "communityConsent";
+const HUB_UNAVAILABLE_MESSAGE = "Community hub is unavailable; consent was not changed.";
+export const METHOD_CONSENT_REQUIRED_MESSAGE = "Community participation consent is required before publishing shared skills.";
+const SIGNAL_CONSENT_REQUIRED_MESSAGE = "Community participation consent is required before sending registry signals.";
+const TELEMETRY_CONSENT_REQUIRED_MESSAGE = "Community participation consent is required before sending community telemetry.";
+const INSTALL_CONSENT_REQUIRED_MESSAGE = "explicitInstallConsent=true is required before resolving a community install.";
+const SIGNAL_EVENTS = new Set([
+    "installed",
+    "success",
+    "fail",
+    "neutral",
+    "kept",
+    "uninstalled",
+    "endorse",
+    "error",
+]);
+const TELEMETRY_EVENTS = new Set([
+    "community.journey.view",
+    "community.share.generated",
+    "community.sandbox.violation",
+    "community.desensitization.hit",
+]);
+const MAX_REGISTRY_MATCH_TOP_K = 3;
+const MAX_REGISTRY_DISCOVERY_JSON_CHARS = 1800;
+export async function handleCommunityGetConsent(msg) {
+    try {
+        const store = resolveStore(this);
+        const localConsent = await store.read();
+        const client = resolveClient(this);
+        if (!client) {
+            sendResult(this, msg, {
+                ok: true,
+                remoteAvailable: false,
+                consent: localConsent,
+            });
+            return;
+        }
+        try {
+            const remoteConsent = await client.getConsent();
+            await store.write(remoteConsent);
+            sendResult(this, msg, {
+                ok: true,
+                remoteAvailable: true,
+                consent: remoteConsent,
+            });
+        }
+        catch (err) {
+            sendResult(this, msg, {
+                ok: true,
+                remoteAvailable: false,
+                consent: localConsent,
+                error: err instanceof Error ? err.message : "Community hub is unavailable.",
+            });
+        }
+    }
+    catch (err) {
+        sendError(this, msg, err instanceof Error ? err.message : String(err));
+    }
+}
+export async function handleCommunitySetConsent(msg) {
+    const input = parseSetConsentInput(msg.params);
+    if (!input) {
+        sendError(this, msg, "enabled (boolean) is required.", AGENT_RPC_ERROR_CODES.INVALID_PARAMS);
+        return;
+    }
+    try {
+        const store = resolveStore(this);
+        const client = resolveClient(this);
+        if (!client) {
+            if (input.enabled) {
+                sendError(this, msg, HUB_UNAVAILABLE_MESSAGE);
+                return;
+            }
+            const disabled = normalizeCommunityConsent(input, false);
+            await store.write(disabled);
+            sendResult(this, msg, {
+                ok: true,
+                remoteAvailable: false,
+                consent: disabled,
+                warning: "Community hub is unavailable; local sharing gates are off.",
+            });
+            return;
+        }
+        try {
+            const remoteConsent = await client.setConsent(input);
+            await store.write(remoteConsent);
+            sendResult(this, msg, {
+                ok: true,
+                remoteAvailable: true,
+                consent: remoteConsent,
+            });
+        }
+        catch (err) {
+            if (!input.enabled) {
+                const disabled = normalizeCommunityConsent(input, false);
+                await store.write(disabled);
+                sendResult(this, msg, {
+                    ok: true,
+                    remoteAvailable: false,
+                    consent: disabled,
+                    warning: err instanceof Error ? err.message : "Community hub is unavailable.",
+                });
+                return;
+            }
+            sendError(this, msg, HUB_UNAVAILABLE_MESSAGE);
+        }
+    }
+    catch (err) {
+        sendError(this, msg, err instanceof Error ? err.message : String(err));
+    }
+}
+export async function handleCommunityListShared(msg) {
+    try {
+        const client = resolveClient(this);
+        if (!client) {
+            sendError(this, msg, "Community hub is unavailable.");
+            return;
+        }
+        sendResult(this, msg, {
+            ok: true,
+            resources: await client.listSharedResources(),
+        });
+    }
+    catch (err) {
+        sendError(this, msg, err instanceof Error ? err.message : String(err));
+    }
+}
+export async function handleCommunityMatchRegistry(msg) {
+    const input = parseRegistryMatchInput(msg.params);
+    if (!input) {
+        sendError(this, msg, "Required: intent (string) and optional topK integer 1..3.", AGENT_RPC_ERROR_CODES.INVALID_PARAMS);
+        return;
+    }
+    try {
+        const client = resolveClient(this);
+        if (!client) {
+            sendError(this, msg, "Community hub is unavailable.");
+            return;
+        }
+        const matches = await client.matchRegistry(input);
+        const payload = { ok: true, matches };
+        if (JSON.stringify(payload).length > MAX_REGISTRY_DISCOVERY_JSON_CHARS) {
+            sendError(this, msg, "Community registry discovery response exceeded the O(1) size contract.");
+            return;
+        }
+        sendResult(this, msg, payload);
+    }
+    catch (err) {
+        sendError(this, msg, err instanceof Error ? err.message : String(err));
+    }
+}
+export async function handleCommunityResolveInstall(msg) {
+    const params = msg.params ?? {};
+    const resourceId = typeof params.resourceId === "string" ? params.resourceId.trim() : "";
+    if (!resourceId) {
+        sendError(this, msg, "resourceId (string) is required.", AGENT_RPC_ERROR_CODES.INVALID_PARAMS);
+        return;
+    }
+    if (params.explicitInstallConsent !== true) {
+        sendError(this, msg, INSTALL_CONSENT_REQUIRED_MESSAGE, AGENT_RPC_ERROR_CODES.INVALID_PARAMS);
+        return;
+    }
+    const version = typeof params.version === "string" && params.version.trim() ? params.version.trim() : undefined;
+    const explicitHighRiskConsent = params.explicitHighRiskConsent === true;
+    try {
+        const client = resolveClient(this);
+        if (!client) {
+            sendError(this, msg, "Community hub is unavailable.");
+            return;
+        }
+        const install = await client.resolveInstall(resourceId, version);
+        if (isHighRiskInstall(install) && !explicitHighRiskConsent) {
+            sendHighRiskConsentRequired(this, msg, install);
+            return;
+        }
+        sendResult(this, msg, {
+            ok: true,
+            install,
+        });
+    }
+    catch (err) {
+        sendError(this, msg, err instanceof Error ? err.message : String(err));
+    }
+}
+export async function handleCommunityInstallResource(msg) {
+    const params = msg.params ?? {};
+    const resourceId = typeof params.resourceId === "string" ? params.resourceId.trim() : "";
+    if (!resourceId) {
+        sendError(this, msg, "resourceId (string) is required.", AGENT_RPC_ERROR_CODES.INVALID_PARAMS);
+        return;
+    }
+    if (params.explicitInstallConsent !== true) {
+        sendError(this, msg, INSTALL_CONSENT_REQUIRED_MESSAGE, AGENT_RPC_ERROR_CODES.INVALID_PARAMS);
+        return;
+    }
+    const version = typeof params.version === "string" && params.version.trim() ? params.version.trim() : undefined;
+    const explicitHighRiskConsent = params.explicitHighRiskConsent === true;
+    try {
+        const client = resolveClient(this);
+        if (!client) {
+            sendError(this, msg, "Community hub is unavailable.");
+            return;
+        }
+        const install = await client.resolveInstall(resourceId, version);
+        if (isHighRiskInstall(install) && !explicitHighRiskConsent) {
+            sendHighRiskConsentRequired(this, msg, install);
+            return;
+        }
+        const installed = await installCommunityResource(install);
+        let signalWarning;
+        const consent = await resolveStore(this).read();
+        if (!isInstallPreview(installed) && hasSignalConsent(consent)) {
+            try {
+                await client.recordSignal({
+                    resourceId: install.id,
+                    event: "installed",
+                    metadata: { version: install.version, source: "community-install" },
+                });
+            }
+            catch (err) {
+                signalWarning = err instanceof Error ? err.message : String(err);
+            }
+        }
+        sendResult(this, msg, {
+            ok: true,
+            ...(isInstallPreview(installed) ? { preview: installed } : { installed }),
+            ...(signalWarning ? { signalWarning } : {}),
+        });
+    }
+    catch (err) {
+        sendError(this, msg, err instanceof Error ? err.message : String(err));
+    }
+}
+/**
+ * Handshake step ① — probe declared runtime dependencies (vetted catalog only).
+ * The plugin page calls this right after install so "点 + 即可用" holds: missing
+ * quick runtimes are auto-installed, heavy/unknown ones surface a consent card.
+ */
+export async function handleCommunityRuntimeStatus(msg) {
+    const params = msg.params ?? {};
+    const raw = params.ids;
+    const ids = Array.isArray(raw) ? raw.filter((v) => typeof v === "string" && !!v.trim()).map((v) => v.trim()) : [];
+    if (!ids.length) {
+        sendError(this, msg, "ids (non-empty string array) is required.", AGENT_RPC_ERROR_CODES.INVALID_PARAMS);
+        return;
+    }
+    if (ids.length > 8) {
+        sendError(this, msg, "At most 8 runtime ids per call.", AGENT_RPC_ERROR_CODES.INVALID_PARAMS);
+        return;
+    }
+    try {
+        const items = [];
+        for (const id of ids)
+            items.push(await probeRuntimeDependency(id));
+        sendResult(this, msg, { ok: true, items });
+    }
+    catch (err) {
+        sendError(this, msg, err instanceof Error ? err.message : String(err));
+    }
+}
+/** Handshake step ② — install ONE vetted runtime dependency (catalog recipe only). */
+export async function handleCommunityInstallRuntime(msg) {
+    const params = msg.params ?? {};
+    const id = typeof params.id === "string" ? params.id.trim() : "";
+    if (!id) {
+        sendError(this, msg, "id (string) is required.", AGENT_RPC_ERROR_CODES.INVALID_PARAMS);
+        return;
+    }
+    try {
+        const result = await installRuntimeDependency(id);
+        sendResult(this, msg, result);
+    }
+    catch (err) {
+        sendError(this, msg, err instanceof Error ? err.message : String(err));
+    }
+}
+function isInstallPreview(value) {
+    return !!value
+        && typeof value === "object"
+        && ((value.kind === "mcp" && value.mode === "preview")
+            || value.kind === "executable");
+}
+export async function handleCommunityPublishSkill(msg) {
+    const input = parsePublishSkillInput(msg.params);
+    if (!input) {
+        sendError(this, msg, "Required: id, title, summary, manifest.", AGENT_RPC_ERROR_CODES.INVALID_PARAMS);
+        return;
+    }
+    try {
+        const store = resolveStore(this);
+        const consent = await store.read();
+        if (!hasMethodSharingConsent(consent)) {
+            sendError(this, msg, METHOD_CONSENT_REQUIRED_MESSAGE);
+            return;
+        }
+        const client = resolveClient(this);
+        if (!client) {
+            sendError(this, msg, "Community hub is unavailable.");
+            return;
+        }
+        sendResult(this, msg, {
+            ok: true,
+            ...(await client.publishSkill(input)),
+        });
+    }
+    catch (err) {
+        sendError(this, msg, err instanceof Error ? err.message : String(err));
+    }
+}
+export async function handleCommunityPublishPet(msg) {
+    const input = parsePublishPetInput(msg.params);
+    if (!input) {
+        sendError(this, msg, "Required: id, name, summary, persona.", AGENT_RPC_ERROR_CODES.INVALID_PARAMS);
+        return;
+    }
+    try {
+        const store = resolveStore(this);
+        const consent = await store.read();
+        if (!hasMethodSharingConsent(consent)) {
+            sendError(this, msg, METHOD_CONSENT_REQUIRED_MESSAGE);
+            return;
+        }
+        const client = resolveClient(this);
+        if (!client) {
+            sendError(this, msg, "Community hub is unavailable.");
+            return;
+        }
+        sendResult(this, msg, {
+            ok: true,
+            ...(await publishCommunityPetAsset(client, input)),
+        });
+    }
+    catch (err) {
+        sendError(this, msg, err instanceof Error ? err.message : String(err));
+    }
+}
+export async function handleCommunityRecordSignal(msg) {
+    const input = parseRecordSignalInput(msg.params);
+    if (!input) {
+        sendError(this, msg, "Required: resourceId and valid event.", AGENT_RPC_ERROR_CODES.INVALID_PARAMS);
+        return;
+    }
+    try {
+        const store = resolveStore(this);
+        const consent = await store.read();
+        if (!hasSignalConsent(consent)) {
+            sendError(this, msg, SIGNAL_CONSENT_REQUIRED_MESSAGE);
+            return;
+        }
+        const client = resolveClient(this);
+        if (!client) {
+            sendError(this, msg, "Community hub is unavailable.");
+            return;
+        }
+        sendResult(this, msg, {
+            ok: true,
+            ...(await client.recordSignal(input)),
+        });
+    }
+    catch (err) {
+        sendError(this, msg, err instanceof Error ? err.message : String(err));
+    }
+}
+export async function handleCommunityRecordTelemetry(msg) {
+    const input = parseRecordTelemetryInput(msg.params);
+    if (!input) {
+        sendError(this, msg, "Required: valid community telemetry event.", AGENT_RPC_ERROR_CODES.INVALID_PARAMS);
+        return;
+    }
+    try {
+        const store = resolveStore(this);
+        const consent = await store.read();
+        if (!hasSignalConsent(consent)) {
+            sendError(this, msg, TELEMETRY_CONSENT_REQUIRED_MESSAGE);
+            return;
+        }
+        const client = resolveClient(this);
+        if (!client) {
+            sendError(this, msg, "Community hub is unavailable.");
+            return;
+        }
+        sendResult(this, msg, {
+            ok: true,
+            ...(await client.recordTelemetry(input)),
+        });
+    }
+    catch (err) {
+        sendError(this, msg, err instanceof Error ? err.message : String(err));
+    }
+}
+export async function handleCommunityListPublishAudit(msg) {
+    const params = msg.params ?? {};
+    const limit = typeof params.limit === "number" ? params.limit : undefined;
+    try {
+        sendResult(this, msg, {
+            ok: true,
+            entries: listCommunityPublishAuditEntries({ limit }),
+        });
+    }
+    catch (err) {
+        sendError(this, msg, err instanceof Error ? err.message : String(err));
+    }
+}
+export async function handleCommunityWithdrawShared(msg) {
+    const params = msg.params ?? {};
+    const resourceId = typeof params.resourceId === "string" ? params.resourceId.trim() : "";
+    if (!resourceId) {
+        sendError(this, msg, "resourceId (string) is required.", AGENT_RPC_ERROR_CODES.INVALID_PARAMS);
+        return;
+    }
+    const reason = typeof params.reason === "string" ? params.reason : undefined;
+    try {
+        const client = resolveClient(this);
+        if (!client) {
+            sendError(this, msg, "Community hub is unavailable.");
+            return;
+        }
+        sendResult(this, msg, {
+            ok: true,
+            resource: await client.withdrawSharedResource(resourceId, reason),
+        });
+    }
+    catch (err) {
+        sendError(this, msg, err instanceof Error ? err.message : String(err));
+    }
+}
+export async function handleCommunityWithdrawAllShared(msg) {
+    const params = msg.params ?? {};
+    const reason = typeof params.reason === "string" ? params.reason : undefined;
+    try {
+        const client = resolveClient(this);
+        if (!client) {
+            sendError(this, msg, "Community hub is unavailable.");
+            return;
+        }
+        sendResult(this, msg, {
+            ok: true,
+            resources: await client.withdrawSharedResources(reason),
+        });
+    }
+    catch (err) {
+        sendError(this, msg, err instanceof Error ? err.message : String(err));
+    }
+}
+export async function handleCommunityListNotices(msg) {
+    try {
+        const client = resolveClient(this);
+        if (!client) {
+            sendError(this, msg, "Community hub is unavailable.");
+            return;
+        }
+        sendResult(this, msg, {
+            ok: true,
+            notices: await client.listNotices(parseListNoticesInput(msg.params)),
+        });
+    }
+    catch (err) {
+        sendError(this, msg, err instanceof Error ? err.message : String(err));
+    }
+}
+export async function handleCommunityMarkNoticeRead(msg) {
+    const params = msg.params ?? {};
+    const noticeId = typeof params.noticeId === "number" ? params.noticeId : Number(params.noticeId);
+    if (!Number.isSafeInteger(noticeId) || noticeId < 1) {
+        sendError(this, msg, "noticeId (positive integer) is required.", AGENT_RPC_ERROR_CODES.INVALID_PARAMS);
+        return;
+    }
+    try {
+        const client = resolveClient(this);
+        if (!client) {
+            sendError(this, msg, "Community hub is unavailable.");
+            return;
+        }
+        sendResult(this, msg, {
+            ok: true,
+            notice: await client.markNoticeRead(noticeId),
+        });
+    }
+    catch (err) {
+        sendError(this, msg, err instanceof Error ? err.message : String(err));
+    }
+}
+function parseSetConsentInput(params) {
+    if (!params || typeof params.enabled !== "boolean")
+        return null;
+    const input = { enabled: params.enabled };
+    if (typeof params.methodSharingEnabled === "boolean")
+        input.methodSharingEnabled = params.methodSharingEnabled;
+    if (typeof params.signalsEnabled === "boolean")
+        input.signalsEnabled = params.signalsEnabled;
+    if (typeof params.encounterEnabled === "boolean")
+        input.encounterEnabled = params.encounterEnabled;
+    return input;
+}
+function parsePublishSkillInput(params) {
+    if (!params)
+        return null;
+    const id = typeof params.id === "string" ? params.id.trim() : "";
+    const title = typeof params.title === "string" ? params.title.trim() : "";
+    const summary = typeof params.summary === "string" ? params.summary.trim() : "";
+    const manifest = isRecord(params.manifest) ? params.manifest : null;
+    if (!id || !title || !summary || !manifest)
+        return null;
+    const visibility = params.visibility === "private" ? "private" : "public";
+    const tags = Array.isArray(params.tags)
+        ? params.tags.filter((tag) => typeof tag === "string")
+        : [];
+    const input = {
+        id,
+        title,
+        summary,
+        visibility,
+        tags,
+        manifest,
+    };
+    if (typeof params.version === "string")
+        input.version = params.version.trim();
+    if (typeof params.packageGzipBase64 === "string")
+        input.packageGzipBase64 = params.packageGzipBase64.trim();
+    return input;
+}
+function parsePublishPetInput(params) {
+    if (!params)
+        return null;
+    const id = typeof params.id === "string" ? params.id.trim() : "";
+    const name = typeof params.name === "string" ? params.name.trim() : "";
+    const summary = typeof params.summary === "string" ? params.summary.trim() : "";
+    const persona = typeof params.persona === "string" ? params.persona.trim() : "";
+    if (!id || !name || !summary || !persona)
+        return null;
+    return {
+        id,
+        name,
+        summary,
+        persona,
+        visibility: params.visibility === "private" ? "private" : "public",
+        tags: Array.isArray(params.tags) ? params.tags.filter((tag) => typeof tag === "string") : [],
+        traits: Array.isArray(params.traits) ? params.traits.filter((trait) => typeof trait === "string") : [],
+        assets: Array.isArray(params.assets)
+            ? params.assets
+                .filter(isRecord)
+                .map((asset) => ({
+                kind: typeof asset.kind === "string" ? asset.kind : "",
+                path: typeof asset.path === "string" ? asset.path : "",
+            }))
+                .filter((asset) => asset.kind && asset.path)
+            : [],
+    };
+}
+function parseRegistryMatchInput(params) {
+    if (!params)
+        return null;
+    const intent = typeof params.intent === "string" ? params.intent.trim() : "";
+    if (!intent)
+        return null;
+    const topK = params.topK === undefined ? undefined : Number(params.topK);
+    if (topK !== undefined && (!Number.isSafeInteger(topK) || topK < 1 || topK > MAX_REGISTRY_MATCH_TOP_K)) {
+        return null;
+    }
+    return {
+        intent,
+        ...(topK === undefined ? {} : { topK }),
+        ...(typeof params.preferOfficial === "boolean" ? { preferOfficial: params.preferOfficial } : {}),
+    };
+}
+function parseRecordSignalInput(params) {
+    if (!params)
+        return null;
+    const resourceId = typeof params.resourceId === "string" ? params.resourceId.trim() : "";
+    const event = typeof params.event === "string" && SIGNAL_EVENTS.has(params.event)
+        ? params.event
+        : null;
+    if (!resourceId || !event)
+        return null;
+    const input = { resourceId, event };
+    if (typeof params.attribution === "string" && params.attribution.trim())
+        input.attribution = params.attribution.trim();
+    if (isRecord(params.metadata))
+        input.metadata = params.metadata;
+    return input;
+}
+function parseRecordTelemetryInput(params) {
+    if (!params)
+        return null;
+    const event = typeof params.event === "string" && TELEMETRY_EVENTS.has(params.event)
+        ? params.event
+        : null;
+    if (!event)
+        return null;
+    const input = { event };
+    const metadata = sanitizeCommunityTelemetryMetadata(event, params.metadata);
+    if (metadata)
+        input.metadata = metadata;
+    return input;
+}
+function parseListNoticesInput(params) {
+    return {
+        includeRead: params?.includeRead === true,
+    };
+}
+export function hasMethodSharingConsent(consent) {
+    return consent.enabled && consent.methodSharingEnabled && consent.remoteSynced;
+}
+function hasSignalConsent(consent) {
+    return consent.enabled && consent.signalsEnabled && consent.remoteSynced;
+}
+function isHighRiskInstall(install) {
+    return isHighRiskTier(install.effectiveRiskTier);
+}
+function isHighRiskTier(tier) {
+    return tier === "R2" || tier === "R3";
+}
+function sendHighRiskConsentRequired(ctx, msg, install) {
+    sendError(ctx, msg, `Explicit high-risk consent is required before exposing ${install.effectiveRiskTier} community install resolution.`, AGENT_RPC_ERROR_CODES.INTERNAL_ERROR, {
+        resourceRiskTier: install.resourceRiskTier,
+        effectiveRiskTier: install.effectiveRiskTier,
+        requiresExplicitHighRiskConsent: true,
+    });
+}
+function isRecord(value) {
+    return !!value && typeof value === "object" && !Array.isArray(value);
+}
+function resolveClient(ctx) {
+    if (ctx.resolveCommunityConsentClient)
+        return ctx.resolveCommunityConsentClient();
+    return createDefaultCommunityConsentClient();
+}
+function resolveStore(ctx) {
+    return ctx.resolveCommunityConsentStore?.() ?? createFileCommunityConsentStore();
+}
+export function createFileCommunityConsentStore() {
+    const settingsPath = getUserSettingsPath();
+    return {
+        async read() {
+            const settings = await readSettings(settingsPath);
+            return normalizeCommunityConsent(settings[COMMUNITY_CONSENT_KEY], false);
+        },
+        async write(consent) {
+            const settings = await readSettings(settingsPath);
+            settings[COMMUNITY_CONSENT_KEY] = consent;
+            await fs.mkdir(path.dirname(settingsPath), { recursive: true });
+            await fs.writeFile(settingsPath, JSON.stringify(settings, null, 2), "utf-8");
+        },
+    };
+}
+async function readSettings(settingsPath) {
+    try {
+        return JSON.parse(await fs.readFile(settingsPath, "utf-8"));
+    }
+    catch {
+        return {};
+    }
+}
+function sendResult(ctx, msg, result) {
+    if (msg.id !== undefined)
+        ctx.sendResponse(msg.id, result);
+}
+function sendError(ctx, msg, message, code = AGENT_RPC_ERROR_CODES.INTERNAL_ERROR, data) {
+    if (msg.id !== undefined)
+        ctx.sendResponse(msg.id, undefined, { code, message, ...(data === undefined ? {} : { data }) });
+}

package/dist/cli/handlers/community-handler.test.d.ts

@@ -0,0 +1 @@
+export {};