@zq-silk/yui 0.15.6 → 0.15.8

package/dist/observability/orchestrationMetrics.js

@@ -1,5 +1,5 @@
 import { isDeepStrictEqual } from "node:util";
-import { isCompletedReviewExecutionFromTurns } from "../review/reviewAcceptance.js";
+import { isCompletedReviewExecutionFromRuns } from "../review/reviewAcceptance.js";
 import { projectFirstProgressAdvisory } from "../runtime/firstProgressAdvisory.js";
 /** One Task's orchestration cost and advisory projection, with no writes. */
 export function projectTaskOrchestration(facts) {
@@ -48,10 +48,10 @@ export function projectTaskOrchestration(facts) {
         timeToFirstProjectCommitMs: firstCommitAt === undefined
             ? null
             : Math.max(0, Date.parse(firstCommitAt) - Date.parse(facts.task.createdAt)),
-        turns: {
-            total: facts.turns.length,
-            byStatus: counts(facts.turns.map(({ status }) => status)),
-            byRole: counts(facts.turns.map(({ roleName }) => roleName))
+        runs: {
+            total: facts.runs.length,
+            byStatus: counts(facts.runs.map(({ status }) => status)),
+            byRole: counts(facts.runs.map(({ roleName }) => roleName))
         },
         workItems: facts.workItems.length,
         reviews: {
@@ -65,7 +65,7 @@ export function projectTaskOrchestration(facts) {
             repeatedIdentities,
             evidenceReuses: facts.integrations.filter((attempt) => ((attempt.checks ?? []).some(({ details }) => details?.startsWith("Reused successful check evidence from ")))).length
         },
-        providerGenerationsBeforeFirstProgress: firstProgress.generationsBeforeFirstProgress,
+        providerSessionsBeforeFirstProgress: firstProgress.sessionsBeforeFirstProgress,
         publicationToCompletionMs: publicationAt === undefined || facts.task.completedAt === undefined
             ? null
             : Math.max(0, Date.parse(facts.task.completedAt) - Date.parse(publicationAt)),
@@ -91,7 +91,7 @@ function projectAdvisories(facts, fullRounds, repeatedIdentities, firstProgressA
                 .map(({ id }) => `durable-job:${id}`)
         });
     }
-    const completedFull = fullRounds.filter((round) => (isCompletedReviewExecutionFromTurns(round, facts.turns)))
+    const completedFull = fullRounds.filter((round) => (isCompletedReviewExecutionFromRuns(round, facts.runs)))
         .sort((left, right) => left.createdAt.localeCompare(right.createdAt));
     const recent = completedFull.slice(-3);
     const sameCandidate = recent.length === 3
@@ -108,7 +108,7 @@ function projectAdvisories(facts, fullRounds, repeatedIdentities, firstProgressA
     if (firstProgressAttention) {
         result.push({
             code: "provider-first-progress-advisory",
-            reason: "Two fresh Leader generations produced no first durable progress; consider Operator attention before another generation.",
+            reason: "Two fresh Leader Sessions produced no first durable progress; consider Operator attention before another Session.",
             refs: [facts.task.id]
         });
     }

package/dist/operator/operatorSessionHistory.js

@@ -1,3 +1,4 @@
+import { agentAdapterLabel as adapterLabel } from "../agent/adapterCatalog.js";
 import { normalizeRoleAgentSessionText, roleAgentSessionRef, validateRoleSessionSet } from "../executor/agentExecutor.js";
 /** Separates the one selected writer authority from retained conversations. */
 export function projectOperatorStatus(sessions, activeAgentId, activeAdapterId) {
@@ -141,13 +142,6 @@ function optionalDisplayText(value) {
     const normalized = normalizeRoleAgentSessionText(value);
     return normalized.length === 0 ? undefined : normalized;
 }
-function adapterLabel(adapterId) {
-    return adapterId === "codex"
-        ? "Codex"
-        : adapterId === "claude"
-            ? "Claude"
-            : adapterId;
-}
 function requireText(value, label) {
     if (typeof value !== "string" || value.includes("\0") || value.trim().length === 0) {
         throw new Error(`${label} is required.`);

package/dist/output/agentConfigurationPresentation.js

@@ -1,4 +1,5 @@
 import { renderAgentConfigurationResolutionNotice } from "../cli/agentConfigurationPicker.js";
+import { agentHandshakeLine } from "./agentRunConfigurationPresentation.js";
 import { defaultTableWidth, renderTable } from "./table.js";
 export function renderAgentConfigurationCatalog(resolved) {
     const { catalog } = resolved;
@@ -11,13 +12,17 @@ export function renderAgentConfigurationCatalog(resolved) {
         model.serviceTiers?.map((tier) => tier.value).join(", ") || "none reported"
     ]);
     const fieldRows = catalog.fields
-        .filter((field) => field.key !== "model" && field.key !== "effort")
+        .filter((field) => modelRows.length === 0 || (field.key !== "model" && field.key !== "effort"))
         .map((field) => [
         field.key,
         field.choices.map((choice) => choice.value).join(", ") || "none reported",
+        // An available field can still carry a reason, and for ACP it always does:
+        // the values are enumerated per Session, so the probe deliberately lists
+        // none. Dropping that sentence left "none reported" looking like a failed
+        // query rather than a deliberate boundary, so it is shown either way.
         field.available === false
             ? `unavailable${field.reason === undefined ? "" : `: ${field.reason}`}`
-            : "available",
+            : field.reason === undefined ? "available" : `available: ${field.reason}`,
         field.allowCustom ? "yes" : "no"
     ]);
     const sections = [
@@ -39,5 +44,5 @@ export function renderAgentConfigurationCatalog(resolved) {
                     { header: "Custom", minWidth: 6, maxWidth: 8 }
                 ], fieldRows, defaultTableWidth())])
     ];
-    return `${sections.join("\n\n")}\n${renderAgentConfigurationResolutionNotice(resolved)}`;
+    return `${sections.join("\n\n")}\n${agentHandshakeLine(catalog.handshake)}\n${renderAgentConfigurationResolutionNotice(resolved)}`;
 }

package/dist/output/agentRunConfigurationPresentation.js

@@ -0,0 +1,128 @@
+/**
+ * Rendering what a live Agent reports about its own run configuration.
+ *
+ * The whole point of this display is to keep two things visibly apart that a
+ * reader would otherwise merge: what the launch asked for, and what the Agent
+ * says it is doing. So the confirmation strength is printed for every requested
+ * value rather than summarized into a checkmark, and a value Yui could not
+ * verify is labelled as such in the same column where a verified one would
+ * appear. There is no state in which this renders a requested value as though
+ * the Agent had agreed to it.
+ */
+import { renderTable, defaultTableWidth } from "./table.js";
+/**
+ * The one handshake line, shared by every surface that has one to show.
+ *
+ * Both the capability catalog and a Session inspect display this same fact, and
+ * a reader comparing them is entitled to assume the wording means the same thing
+ * in both. One function is what guarantees that, in the same way one projection
+ * function guarantees the two produce the same observation to begin with.
+ *
+ * `undefined` is the catalog's third state — no connection was attempted — and
+ * is distinct from a plan that negotiates nothing.
+ */
+export function agentHandshakeLine(handshake) {
+    if (handshake === undefined) {
+        return "Agent handshake: not attempted (these values did not come from a live connection)";
+    }
+    if (handshake.status === "unsupported") {
+        return `Agent handshake: unsupported (${handshake.reason})`;
+    }
+    return [
+        `Agent handshake: protocol v${handshake.protocolVersion};`,
+        ` reported as ${handshake.agentName} ${handshake.agentVersion};`,
+        ` capabilities ${handshake.capabilities.join(", ") || "none"};`,
+        // Method ids only. Which methods an Agent offers is a capability; any
+        // credential or token that satisfies one is not Yui's to display.
+        ` auth methods ${handshake.authMethods.join(", ") || "none"}`
+    ].join("");
+}
+/**
+ * The one-line form, for a status display that has a line to spare.
+ *
+ * Deliberately says which of the three "no value" answers applies instead of
+ * printing a blank: a reader who sees nothing cannot tell whether Yui failed to
+ * ask, the Agent has nothing to report, or the Agent reported a problem.
+ */
+export function agentRunConfigurationLabel(observation) {
+    if (observation === undefined)
+        return "not queried";
+    if (observation.status === "unknown")
+        return `unknown (${observation.reason})`;
+    if (observation.status === "unsupported")
+        return `unsupported (${observation.reason})`;
+    const summary = observation.requested.length === 0
+        ? "no configuration requested; the Agent's own defaults stand"
+        : observation.requested
+            .map((request) => `${request.field}=${requestValueLabel(request)}`)
+            .join(", ");
+    return `${summary}; read at ${observation.observedAt}`;
+}
+/**
+ * The full form: one table for what was asked and one for what the Agent offers.
+ *
+ * Returns an empty string when there is nothing an Agent reported, so a caller
+ * can append it unconditionally without producing an empty heading.
+ */
+export function renderAgentRunConfiguration(observation) {
+    if (observation === undefined || observation.status !== "observed")
+        return "";
+    const sections = [];
+    if (observation.requested.length > 0) {
+        sections.push(renderTable("Requested run configuration (launch-time confirmation)", [
+            { header: "Field", minWidth: 10, maxWidth: 12 },
+            { header: "Requested", minWidth: 12, maxWidth: 30 },
+            { header: "Evidence", minWidth: 12, maxWidth: 14 },
+            { header: "Agent reports now", minWidth: 16, maxWidth: 46 }
+        ], observation.requested.map((request) => [
+            request.field,
+            request.value,
+            confirmationLabel(request.confirmation),
+            currentValueLabel(request.current, request.value)
+        ]), defaultTableWidth()));
+    }
+    if (observation.axes.length > 0) {
+        sections.push(renderTable("Agent-reported configuration options (Yui-supported axes)", [
+            { header: "Option", minWidth: 10, maxWidth: 22 },
+            { header: "Axis", minWidth: 8, maxWidth: 14 },
+            { header: "Current", minWidth: 12, maxWidth: 40 },
+            { header: "Offered", minWidth: 18, maxWidth: 44 }
+        ], observation.axes.map((axis) => [
+            axis.key,
+            axis.category ?? "unnamed",
+            axis.current.status === "observed"
+                ? axis.current.value
+                : `unobserved: ${axis.current.reason}`,
+            axis.offered.join(", ") || "none reported"
+        ]), defaultTableWidth()));
+    }
+    sections.push(agentHandshakeLine(observation.handshake));
+    sections.push(`Read from the live Session at ${observation.observedAt}. `
+        + "Requests describe this connection's launch, not subsequent Role edits; "
+        + "current values are the latest peer reports, not independent execution verification.");
+    return sections.join("\n\n");
+}
+/** Spell out what each confirmation actually proves, in the table cell. */
+function confirmationLabel(confirmation) {
+    if (confirmation === "already")
+        return "already set";
+    if (confirmation === "observed")
+        return "observed";
+    return "ack only";
+}
+function requestValueLabel(request) {
+    if (request.current.status === "unobserved")
+        return `${request.value} (unverified)`;
+    return request.current.value === request.value
+        ? request.value
+        // Drift is the case this whole path exists to make visible, so it is stated
+        // rather than resolved in favour of either value.
+        : `${request.current.value} (requested ${request.value})`;
+}
+function currentValueLabel(current, requested) {
+    if (current.status === "unobserved")
+        return `unobserved: ${current.reason}`;
+    return current.value === requested
+        ? current.value
+        : `${current.value} — differs from the requested ${requested}`;
+}

package/dist/output/rolePresentation.js

@@ -1,5 +1,29 @@
 import { activeRoleAgentSession } from "../executor/agentExecutor.js";
+import { effectiveRoleForLaunch } from "../executor/effectiveLaunch.js";
 import { defaultTableWidth, renderTable } from "./table.js";
+/** Desired configuration and the fixed Session request are not Provider evidence. */
+export function renderRoleLaunchComparison(role, effective) {
+    const pinned = effectiveRoleForLaunch(role, effective);
+    return renderTable("Configuration intent (not observed Provider state)", [
+        { header: "Source", minWidth: 14, maxWidth: 20 },
+        { header: "Agent / component", minWidth: 18, maxWidth: 32 },
+        { header: "Model", minWidth: 10, maxWidth: 20 },
+        { header: "Effort", minWidth: 8, maxWidth: 14 },
+        { header: "Permission", minWidth: 12, maxWidth: 34 },
+        { header: "Profile intent", minWidth: 14, maxWidth: 14 }
+    ], [[`Role desired r${role.launchRevision}`, role],
+        [`Session pinned r${effective.sourceDesiredRevision}`, pinned]].map(([source, current]) => {
+        const binding = current.agentBindings[current.activeAgentId];
+        return [
+            source,
+            `${binding.agentId}/${binding.component}`,
+            binding.config.model ?? "Agent default",
+            binding.config.effort ?? "Agent default",
+            permission(binding),
+            current.defaultAccess
+        ];
+    }), defaultTableWidth());
+}
 export function activeRoleSummary(role) {
     const binding = role.agentBindings[role.activeAgentId];
     return {
@@ -24,10 +48,20 @@ export function renderRoleDetails(title, role, input) {
         `  Kind             ${input.kind}`,
         `  Active Agent     ${role.activeAgentId}`,
         `  Workspace        ${role.workspace}`,
+        ...("taskId" in role ? [
+            `  Desired environment ${role.executionEnvironment === undefined
+                ? "managed workspace"
+                : `${role.executionEnvironment.environmentRef}; ${role.executionEnvironment.directory.path}; ${role.executionEnvironment.access}`}`,
+            `  Session environment ${effective === undefined ? "not started"
+                : effective.executionEnvironment === undefined ? "managed workspace"
+                    : `${effective.executionEnvironment.environmentRef}; ${effective.executionEnvironment.directory.path}; ${effective.executionEnvironment.access}`}`
+        ] : []),
         `  Desired launch   r${role.launchRevision}; Profile intent=${role.defaultAccess}`,
+        // The component is what the Session is pinned to; its plan follows from it.
+        // Naming the plan alone would show two different ACP products identically.
         `  Effective launch ${effective === undefined
             ? "not started"
-            : `${effective.agentId}/${effective.adapterId}; r${effective.sourceDesiredRevision}; Profile intent=${effective.profileAccess}; permission=${effective.permission.strategy}`}`,
+            : `${effective.agentId}/${effective.component}; r${effective.sourceDesiredRevision}; Profile intent=${effective.profileAccess}; permission=${effective.permission.strategy}`}`,
         `  Desired drift    ${effective === undefined
             ? "-"
             : effective.sourceDesiredRevision === role.launchRevision
@@ -46,7 +80,10 @@ export function renderRoleDetails(title, role, input) {
         renderTable("Agent settings", [
             { header: "Agent", minWidth: 5, maxWidth: 20 },
             { header: "Active", minWidth: 6, maxWidth: 6 },
-            { header: "Adapter", minWidth: 7, maxWidth: 10 },
+            // Wide enough to hold the longest component id whole: it is an
+            // identifier, so splitting it mid-token reads worse than letting the
+            // prose in Permission wrap, which it does naturally.
+            { header: "Component", minWidth: 17, maxWidth: 18 },
             { header: "Model", minWidth: 8, maxWidth: 24 },
             { header: "Effort", minWidth: 8, maxWidth: 16 },
             { header: "Permission", minWidth: 10, maxWidth: 34 },
@@ -59,7 +96,7 @@ function bindingRow(binding, role, sessions) {
     return [
         binding.agentId,
         binding.agentId === role.activeAgentId ? "yes" : "",
-        binding.adapterId,
+        binding.component,
         binding.config.model ?? "CLI default",
         binding.config.effort ?? "CLI default",
         permission(binding),
@@ -81,6 +118,20 @@ function permission(binding) {
             permission.approval === undefined ? undefined : `approval=${permission.approval}`
         ].filter((value) => value !== undefined).join("; ");
     }
+    // ACP's strategy decides the Session mode Yui requests over the protocol. It
+    // is stated separately from how Yui answers `session/request_permission`,
+    // which is always a decline on this transport: those are two different
+    // questions, and collapsing them would make a configured Session mode read as
+    // interactive consent Yui does not hold.
+    if (binding.config.adapterId === "acp") {
+        const permission = binding.config.permission;
+        const requests = "requests declined";
+        if (permission.strategy === "default")
+            return `Agent default; ${requests}`;
+        if (permission.strategy === "bypass")
+            return `bypass; ${requests}`;
+        return `mode=${permission.mode}; ${requests}`;
+    }
     const permission = binding.config.permission;
     if (permission.strategy === "default")
         return "CLI default";

package/dist/plugins/pluginChild.js

@@ -0,0 +1,104 @@
+/** Dedicated trusted-local process. Module linking fixes the dependency closure
+ * to captured package bytes; node:vm is NOT a security boundary. The explicit
+ * trusted-local execution grant, not this loader, authorizes author code. */
+import { createContext, SourceTextModule } from "node:vm";
+import { posix } from "node:path";
+const send = (message) => process.send?.(message);
+const pending = new Map();
+let nextCall = 0;
+let instance;
+let selfTest;
+const context = createContext(Object.create(null), { codeGeneration: { strings: false, wasm: false } });
+process.on("message", (raw) => {
+    if (raw.type === "nested-result") {
+        const entry = pending.get(raw.id);
+        if (!entry)
+            return;
+        pending.delete(raw.id);
+        if (raw.error)
+            entry.reject(new Error(String(raw.error)));
+        else
+            entry.resolve(raw.value);
+        return;
+    }
+    void execute(raw).then((value) => send({ type: "result", id: raw.id, value }), (error) => send({ type: "result", id: raw.id, error: error instanceof Error ? error.message : String(error) }));
+});
+async function execute(message) {
+    if (message.type === "load") {
+        const files = message.files;
+        const modules = new Map();
+        const load = (name) => {
+            const previous = modules.get(name);
+            if (previous)
+                return previous;
+            if (!Object.hasOwn(files, name))
+                throw new Error(`Package module missing: ${name}`);
+            const module = new SourceTextModule(files[name], {
+                context, identifier: name,
+                importModuleDynamically: async () => { throw new Error("Dynamic imports are not supported; bundle package dependencies."); }
+            });
+            modules.set(name, module);
+            return module;
+        };
+        const root = load(message.entry);
+        await root.link((specifier, parent) => {
+            if (!specifier.startsWith("./") && !specifier.startsWith("../"))
+                throw new Error("Only package-relative module imports are supported.");
+            const path = posix.normalize(posix.join(posix.dirname(parent.identifier), specifier));
+            if (path.startsWith("../") || path.startsWith("/"))
+                throw new Error("Module import escapes the captured package.");
+            return load(path);
+        });
+        await root.evaluate();
+        const exports = root.namespace;
+        if (typeof exports.initialize !== "function")
+            throw new Error("Executable entry must export initialize().");
+        // No host invocation/identity/resource port exists during initialization.
+        instance = await exports.initialize();
+        if (!instance || typeof instance.handlers !== "object" || !instance.handlers
+            || Object.values(instance.handlers).some((handler) => typeof handler !== "function")
+            || (instance.dispose !== undefined && typeof instance.dispose !== "function")) {
+            throw new Error("initialize() must return handlers and an optional dispose function.");
+        }
+        selfTest = exports.selfTest;
+        return Object.keys(instance.handlers).sort();
+    }
+    if (message.type === "test") {
+        if (typeof selfTest !== "function")
+            throw new Error("Executable validation requires exported selfTest().");
+        if (await selfTest() !== true)
+            throw new Error("selfTest() must return true.");
+        return true;
+    }
+    if (message.type === "dispose") {
+        await instance?.dispose?.();
+        return null;
+    }
+    if (message.type !== "invoke")
+        throw new Error("Unknown child request.");
+    let open = true;
+    try {
+        const value = await instance.handlers[message.name](message.input, Object.freeze({
+            context: Object.freeze(message.context), requestId: message.requestId,
+            call: (request) => {
+                if (!open)
+                    return Promise.reject(new Error("Plugin invocation ended."));
+                const id = `nested-${++nextCall}`;
+                return new Promise((resolve, reject) => {
+                    pending.set(id, { resolve, reject });
+                    send({ type: "nested", id, parentId: message.id, request });
+                });
+            }
+        }));
+        // IPC's JSON projection must not hide bad output from the parent registry.
+        return JSON.parse(JSON.stringify(value, (_key, item) => {
+            if (typeof item === "bigint" || typeof item === "function" || typeof item === "symbol"
+                || (typeof item === "number" && !Number.isFinite(item)))
+                throw new Error("Plugin output is not JSON data.");
+            return item;
+        }));
+    }
+    finally {
+        open = false;
+    }
+}

package/dist/plugins/pluginIntent.js

@@ -0,0 +1,26 @@
+import { requireIdentity, requireText, requireTimestamp } from "../domain/validation.js";
+export function validatePluginId(id) {
+    if (typeof id !== "string" || !/^[a-z][a-z0-9-]*$/u.test(id))
+        throw new Error("Invalid plugin id.");
+    return id;
+}
+export function validatePluginIntentFailure(failure) {
+    requireText(failure.message, "Plugin failure");
+    requireTimestamp(failure.occurredAt, "Plugin failure time");
+    return failure;
+}
+export function validatePluginIntent(intent) {
+    if (intent.schemaVersion !== 1 || typeof intent.enabled !== "boolean"
+        || !Number.isSafeInteger(intent.revision) || intent.revision < 1)
+        throw new Error("Invalid plugin intent.");
+    requireIdentity(intent.taskId, "Plugin intent Task");
+    validatePluginId(intent.pluginId);
+    requireTimestamp(intent.updatedAt, "Plugin intent time");
+    if (intent.validationId !== undefined)
+        requireIdentity(intent.validationId, "Plugin validation reference");
+    if (intent.enabled && intent.validationId === undefined)
+        throw new Error("Enabled intent requires a fixed validation reference.");
+    if (intent.lastFailure !== undefined)
+        validatePluginIntentFailure(intent.lastFailure);
+    return intent;
+}

package/dist/plugins/pluginInterpreter.js

@@ -0,0 +1,43 @@
+import { capabilitySchemaError } from "../kernel/capabilitySchema.js";
+/** Bounded data interpreter, not JavaScript evaluation or a workflow engine. */
+export function interpretPlugin(pkg) {
+    const handlers = JSON.parse(pkg.files[pkg.manifest.entry]);
+    const text = { type: "string", minLength: 1 };
+    const handlerSchema = {
+        anyOf: [
+            { type: "object", properties: { type: { const: "echo" } }, required: ["type"], additionalProperties: false },
+            { type: "object", properties: { type: { const: "constant" }, value: {} }, required: ["type", "value"], additionalProperties: false },
+            { type: "object", properties: { type: { const: "call" }, name: text, contractVersion: text, providerId: text },
+                required: ["type", "name", "contractVersion"], additionalProperties: false }
+        ]
+    };
+    const error = capabilitySchemaError({
+        type: "object", required: pkg.manifest.capabilities.map((capability) => capability.name),
+        properties: Object.fromEntries(pkg.manifest.capabilities.map((capability) => [capability.name, handlerSchema])),
+        additionalProperties: false
+    }, handlers);
+    if (error)
+        throw new Error(`Declarative entry: ${error}`);
+    const entries = handlers;
+    for (const handler of Object.values(entries)) {
+        if (handler.type === "call" && !pkg.manifest.required.some((dependency) => dependency.name === handler.name && dependency.contractVersion === handler.contractVersion)) {
+            throw new Error("Declarative call must name a required dependency.");
+        }
+    }
+    return {
+        async invoke(name, input, invocation) {
+            const handler = entries[name];
+            if (handler.type === "echo")
+                return input;
+            if (handler.type === "constant")
+                return structuredClone(handler.value);
+            const result = await invocation.call({
+                name: handler.name, input, contractVersion: handler.contractVersion,
+                providerId: handler.providerId, requestId: invocation.requestId
+            });
+            if (!["value", "operation"].includes(result.kind))
+                throw new Error(result.detail ?? result.kind);
+            return result.value;
+        }
+    };
+}

package/dist/plugins/pluginPackage.js

@@ -0,0 +1,101 @@
+import { createHash } from "node:crypto";
+import { lstatSync, readFileSync, readdirSync, realpathSync } from "node:fs";
+import { join, posix } from "node:path";
+import { capabilitySchemaError, checkCapabilitySchema } from "../kernel/capabilitySchema.js";
+const text = { type: "string", minLength: 1 };
+const texts = { type: "array", items: text };
+const object = (properties, required = Object.keys(properties)) => ({ type: "object", properties, required, additionalProperties: false });
+const manifestSchema = object({
+    id: text, version: text, apiVersion: { const: "1" }, entry: text,
+    kind: { enum: ["declarative", "trusted-local"] }, reloadMode: { const: "manual" },
+    permissions: texts,
+    required: { type: "array", items: object({ name: text, contractVersion: text }) },
+    capabilities: { type: "array", minItems: 1, items: object({
+            name: text, contractVersion: text, summary: text,
+            inputSchema: { type: "object" }, outputSchema: { type: "object" },
+            effect: { enum: ["query", "local-mutation", "external-operation"] }, requiredPermissions: texts
+        }) },
+    build: { type: "array", minItems: 1, items: text }
+}, ["id", "version", "apiVersion", "entry", "kind", "reloadMode", "permissions", "required", "capabilities"]);
+export function parsePluginManifest(value) {
+    const error = capabilitySchemaError(manifestSchema, value);
+    if (error)
+        throw new Error(`Plugin manifest: ${error}`);
+    const manifest = value;
+    if (!/^[a-z][a-z0-9-]*$/u.test(manifest.id))
+        throw new Error("Plugin id must be a lowercase unqualified name.");
+    packagePath(manifest.entry);
+    if (manifest.kind === "declarative" && manifest.build !== undefined)
+        throw new Error("Declarative packages do not execute builds.");
+    if (new Set(manifest.permissions).size !== manifest.permissions.length)
+        throw new Error("Duplicate plugin permissions.");
+    if (manifest.permissions.includes("plugin:manage"))
+        throw new Error("Task-local plugins cannot manage their own Host or other plugins.");
+    for (const capability of manifest.capabilities) {
+        checkCapabilitySchema(capability.inputSchema);
+        checkCapabilitySchema(capability.outputSchema);
+        if (capability.requiredPermissions.some((permission) => !manifest.permissions.includes(permission))) {
+            throw new Error("Capability permission exceeds the manifest permission set.");
+        }
+    }
+    return manifest;
+}
+export function packagePath(value) {
+    if (!value || value.startsWith("/") || value.includes("\\") || value.includes("\0")
+        || value.split("/").some((part) => !part || part === "." || part === "..")
+        || posix.normalize(value) !== value)
+        throw new Error("Package paths must be normalized relative paths.");
+    return value;
+}
+/** Data-only scan. Symlinks, special files and non-UTF8 dependencies are not a
+ * supported package. Capture every byte, including build inputs and dependencies. */
+export function readPluginPackage(directory, requireEntry = true) {
+    if (realpathSync(directory) !== directory)
+        throw new Error("Plugin directory must be canonical.");
+    const files = Object.create(null);
+    let bytes = 0;
+    const walk = (prefix) => {
+        for (const name of readdirSync(join(directory, prefix)).sort()) {
+            const path = prefix ? `${prefix}/${name}` : name;
+            packagePath(path);
+            const stat = lstatSync(join(directory, path));
+            if (stat.isDirectory())
+                walk(path);
+            else {
+                if (!stat.isFile() || stat.isSymbolicLink())
+                    throw new Error("Plugin package contains a non-regular file.");
+                bytes += stat.size;
+                if (bytes > 4 * 1024 * 1024 || Object.keys(files).length >= 256)
+                    throw new Error("Plugin package exceeds 4 MiB/256 files.");
+                const buffer = readFileSync(join(directory, path));
+                const content = buffer.toString("utf8");
+                if (!Buffer.from(content).equals(buffer))
+                    throw new Error("Plugin package files must be UTF-8.");
+                files[path] = content;
+            }
+        }
+    };
+    walk("");
+    const manifest = parsePluginManifest(JSON.parse(files["plugin.json"] ?? "null"));
+    if (requireEntry && !Object.hasOwn(files, manifest.entry))
+        throw new Error("Plugin entry is missing.");
+    return { manifest, files, digest: packageDigest(files) };
+}
+export function packageDigest(files) {
+    return createHash("sha256").update(JSON.stringify(Object.entries(files).sort(([a], [b]) => a.localeCompare(b)))).digest("hex");
+}
+export function validatePluginValidation(record) {
+    if (record.schemaVersion !== 1 || !record.id?.startsWith("validation-") || !record.taskId || !record.directory || !record.preparationId
+        || !record.environment?.path || record.environment.isolation !== "trusted-local"
+        || !record.environment.node || !record.environment.device || !record.environment.inode
+        || !/^[0-9a-f]{64}$/u.test(record.sourceDigest) || !Number.isFinite(Date.parse(record.createdAt))
+        || !Array.isArray(record.checks) || !record.checks.every((value) => typeof value === "string")) {
+        throw new Error("Invalid plugin validation record.");
+    }
+    const manifest = parsePluginManifest(JSON.parse(record.package.files["plugin.json"]));
+    if (JSON.stringify(manifest) !== JSON.stringify(record.package.manifest)
+        || packageDigest(record.package.files) !== record.package.digest
+        || !Object.hasOwn(record.package.files, manifest.entry))
+        throw new Error("Plugin validation content mismatch.");
+    return record;
+}