@zq-silk/yui 2.0.0 → 2.2.0

package/dist/nativeAgent/toolManager/executor.js

@@ -0,0 +1,290 @@
+// Match the existing model/tool wire budgets; all sizes are UTF-8 JSON bytes.
+const messageBytes = 512 * 1024;
+const argumentBytes = 64 * 1024;
+const callsPerBatch = 8;
+const object = (value) => value !== null && typeof value === 'object' && !Array.isArray(value)
+    && Object.getPrototypeOf(value) === Object.prototype;
+const nonempty = (value) => typeof value === 'string' && value.trim().length > 0;
+const identifier = (value) => nonempty(value) && Buffer.byteLength(value, 'utf8') <= 1024;
+const bytes = (value) => Buffer.byteLength(JSON.stringify(value), 'utf8');
+function json(value, depth = 0) {
+    if (depth > 32)
+        return false;
+    if (value === null || typeof value === 'string' || typeof value === 'boolean')
+        return true;
+    if (typeof value === 'number')
+        return Number.isFinite(value);
+    if (Array.isArray(value))
+        return Array.from(value).every(v => json(v, depth + 1));
+    return object(value) && Object.values(value).every(v => json(v, depth + 1));
+}
+function freeze(value) {
+    if (value && typeof value === 'object') {
+        for (const child of Object.values(value))
+            freeze(child);
+        Object.freeze(value);
+    }
+    return value;
+}
+function snapshot(value, limit) {
+    const copy = structuredClone(value);
+    if (!json(copy) || bytes(copy) > limit)
+        throw new Error('Invalid or oversized JSON');
+    return freeze(copy);
+}
+function failure(code, message, effect = 'none') {
+    return { ok: false, error: { code, message, effect } };
+}
+function outcome(raw, identity, beforeStart = false) {
+    try {
+        const value = snapshot(raw, messageBytes);
+        if (!object(value))
+            throw new Error();
+        let normalized;
+        if (!beforeStart && value.ok === true && typeof value.content === 'string') {
+            normalized = { ok: true, content: value.content };
+        }
+        else if (value.ok === false && object(value.error) && nonempty(value.error.code)
+            && typeof value.error.message === 'string'
+            && (value.error.effect === 'none' || (!beforeStart && value.error.effect === 'unknown'))) {
+            normalized = { ok: false, error: {
+                    code: value.error.code, message: value.error.message, effect: value.error.effect,
+                } };
+        }
+        else
+            throw new Error();
+        // Guarantee the consumer can append the paired message without truncation.
+        if (bytes({ role: 'tool', toolCallId: identity.toolCallId, name: identity.name, outcome: normalized }) > messageBytes) {
+            throw new Error();
+        }
+        return normalized;
+    }
+    catch {
+        return failure('tool_protocol', 'Invalid or oversized tool result', beforeStart ? 'none' : 'unknown');
+    }
+}
+function status(started, value) {
+    if (!started)
+        return 'not_executed';
+    if (value.ok)
+        return 'succeeded';
+    if (value.error.effect === 'unknown')
+        return 'unknown';
+    return value.error.code === 'cancelled' ? 'cancelled' : 'failed';
+}
+export function buildExecutor(options) {
+    if (!options?.environment || typeof options.environment.acquire !== 'function') {
+        throw new Error('Tool environment.acquire capability is required');
+    }
+    if (!options.permission || typeof options.permission.check !== 'function') {
+        throw new Error('Tool permission.check capability is required');
+    }
+    if (!Array.isArray(options.tools))
+        throw new Error('Tool collection is required');
+    const acquire = options.environment.acquire.bind(options.environment);
+    const check = options.permission.check.bind(options.permission);
+    const registry = new Map();
+    for (const tool of options.tools) {
+        let definition;
+        try {
+            definition = snapshot(tool.definition, messageBytes);
+            if (!identifier(definition.name) || typeof definition.description !== 'string'
+                || !object(definition.inputSchema) || typeof tool.validate !== 'function'
+                || typeof tool.execute !== 'function')
+                throw new Error();
+        }
+        catch {
+            throw new Error('Invalid tool declaration or implementation');
+        }
+        if (registry.has(definition.name))
+            throw new Error('Tool names must be unique');
+        registry.set(definition.name, {
+            definition, validate: tool.validate.bind(tool), execute: tool.execute.bind(tool),
+        });
+    }
+    const definitions = snapshot([...registry.values()].map(t => t.definition), messageBytes);
+    return Object.freeze({
+        definitions,
+        async executeBatch(request) {
+            // Admit the whole immutable batch before acquiring any resource.
+            let scope, calls;
+            try {
+                scope = snapshot(request.scope, 4096);
+                calls = snapshot(request.calls, messageBytes);
+                if (!identifier(scope.sessionId) || !identifier(scope.turnId) || !Number.isSafeInteger(scope.step)
+                    || scope.step < 1 || !Array.isArray(calls) || !calls.length || calls.length > callsPerBatch
+                    || calls.some(c => !object(c) || !identifier(c.id) || !identifier(c.name)
+                        || !json(c.arguments) || bytes(c.arguments) > argumentBytes)
+                    || new Set(calls.map(c => c.id)).size !== calls.length)
+                    throw new Error();
+            }
+            catch {
+                throw new Error('Invalid tool batch: bounded JSON, scope and unique call identities required');
+            }
+            // Missing recording/cancellation capabilities cannot silently become no-ops.
+            const signal = request.signal;
+            const beforeExecute = request.beforeExecute;
+            const afterExecute = request.afterExecute;
+            if (!signal || typeof signal.aborted !== 'boolean' || typeof signal.addEventListener !== 'function'
+                || typeof beforeExecute !== 'function' || typeof afterExecute !== 'function') {
+                throw new Error('Tool batch signal, beforeExecute and afterExecute capabilities are required');
+            }
+            const results = [];
+            let stopped = null;
+            let recordingError;
+            for (const call of calls) {
+                const identity = freeze({ ...scope, toolCallId: call.id, name: call.name });
+                let started = false;
+                let cleanup = { status: 'not_acquired' };
+                let value = failure('not_started', 'Tool was not started');
+                const cancelled = () => {
+                    if (!signal.aborted)
+                        return false;
+                    stopped ??= 'cancelled';
+                    value = failure('cancelled_before_start', 'Cancelled before tool execution');
+                    return true;
+                };
+                const attempt = async () => {
+                    if (cancelled())
+                        return;
+                    const tool = registry.get(call.name);
+                    if (!tool) {
+                        value = failure('unknown_tool', 'Unknown tool');
+                        return;
+                    }
+                    try {
+                        const invalid = tool.validate(call.arguments);
+                        if (invalid !== null) {
+                            value = outcome({ ok: false, error: invalid }, identity, true);
+                            if (!value.ok && value.error.code === 'tool_protocol')
+                                stopped = 'capability_failed';
+                            return;
+                        }
+                    }
+                    catch {
+                        value = failure('tool_validation', 'Tool validation capability failed');
+                        stopped = 'capability_failed';
+                        return;
+                    }
+                    if (cancelled())
+                        return;
+                    const invocation = freeze({ identity, call, definition: tool.definition });
+                    let lease;
+                    try {
+                        lease = await acquire(invocation, signal);
+                    }
+                    catch {
+                        value = failure('environment_failed', 'Environment acquisition failed');
+                        cleanup = { status: 'acquire_failed', error: {
+                                code: 'acquire_failed', message: 'Environment provider owns partial-resource cleanup; no lease was returned',
+                            } };
+                        stopped = 'capability_failed';
+                        return;
+                    }
+                    // A malformed lease cannot prove acquired resources were released.
+                    let release;
+                    try {
+                        if (!lease || typeof lease.release !== 'function')
+                            throw new Error();
+                        release = lease.release.bind(lease);
+                    }
+                    catch {
+                        value = failure('environment_protocol', 'Environment returned an invalid resource lease');
+                        cleanup = { status: 'failed', error: {
+                                code: 'invalid_lease', message: 'No release capability; resource effects unknown',
+                            } };
+                        stopped = 'cleanup_failed';
+                        return;
+                    }
+                    try {
+                        // Use the same environment for authorization and execution, even if
+                        // the lease implementation exposes its value through an accessor.
+                        let environment;
+                        try {
+                            environment = lease.value;
+                        }
+                        catch {
+                            value = failure('environment_failed', 'Environment value is unavailable');
+                            stopped = 'capability_failed';
+                            return;
+                        }
+                        if (cancelled())
+                            return;
+                        try {
+                            await beforeExecute(identity);
+                        }
+                        catch {
+                            value = failure('record_failed', 'Required execution-intent recording failed');
+                            stopped = 'capability_failed';
+                            return;
+                        }
+                        if (cancelled())
+                            return;
+                        // Permission is the last awaited boundary before tool invocation.
+                        let decision;
+                        try {
+                            decision = snapshot(await check(invocation, environment, signal), 4096);
+                            if (!object(decision) || !(decision.allowed === true
+                                || (decision.allowed === false && typeof decision.reason === 'string')))
+                                throw new Error();
+                        }
+                        catch {
+                            value = failure('permission_failed', 'Permission capability failed or returned an invalid decision');
+                            stopped = 'capability_failed';
+                            return;
+                        }
+                        if (cancelled())
+                            return;
+                        if (!decision.allowed) {
+                            value = failure('permission_denied', decision.reason);
+                            return;
+                        }
+                        started = true;
+                        try {
+                            value = outcome(await tool.execute(call.arguments, identity, signal, environment), identity);
+                        }
+                        catch {
+                            value = failure('tool_exception', 'Tool threw; actual effects are unknown', 'unknown');
+                        }
+                    }
+                    finally {
+                        try {
+                            await release();
+                            cleanup = { status: 'released' };
+                        }
+                        catch {
+                            cleanup = { status: 'failed', error: { code: 'release_failed', message: 'Resource release failed; inspect this invocation' } };
+                            stopped = 'cleanup_failed';
+                        }
+                    }
+                };
+                if (!stopped)
+                    await attempt();
+                else if (stopped === 'cancelled')
+                    cancelled();
+                if (!value.ok && value.error.effect === 'unknown')
+                    stopped = 'unknown_effect';
+                if (signal.aborted)
+                    stopped ??= 'cancelled';
+                const settlement = freeze({
+                    identity, started, status: status(started, value), outcome: value,
+                    cancellationRequested: signal.aborted, cleanup,
+                });
+                results.push(settlement);
+                if (!recordingError) {
+                    try {
+                        await afterExecute(settlement);
+                    }
+                    catch {
+                        recordingError = {
+                            identity, code: 'result_record_failed',
+                            message: 'Result recording failed; write effect unknown. Reconcile using in-memory receipts',
+                        };
+                        stopped ??= 'capability_failed';
+                    }
+                }
+            }
+            return freeze({ results, stopped, ...(recordingError ? { recordingError } : {}) });
+        },
+    });
+}

package/dist/nativeAgent/toolManager/index.js

@@ -0,0 +1,4 @@
+import { buildExecutor } from './executor.js';
+export function createToolExecutor(options) {
+    return buildExecutor(options);
+}

package/dist/nativeAgent/validation.js

@@ -0,0 +1,95 @@
+// JSON escaping can expand a 64 KiB text result to almost 384 KiB.
+export const limits = { messageBytes: 512 * 1024, argumentBytes: 64 * 1024, historyBytes: 1024 * 1024, callsPerStep: 8 };
+export class AgentFault extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+    }
+}
+export function snapshot(value) {
+    const copy = structuredClone(value);
+    const freeze = (item) => {
+        if (item && typeof item === 'object') {
+            for (const child of Object.values(item))
+                freeze(child);
+            Object.freeze(item);
+        }
+    };
+    freeze(copy);
+    return copy;
+}
+function object(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+function text(value) { return typeof value === 'string'; }
+function id(value) { return text(value) && value.trim().length > 0; }
+function json(value, depth = 0) {
+    if (depth > 32)
+        return false;
+    if (value === null || text(value) || typeof value === 'boolean')
+        return true;
+    if (typeof value === 'number')
+        return Number.isFinite(value);
+    if (Array.isArray(value))
+        return Array.from(value).every(v => json(v, depth + 1));
+    return object(value) && Object.getPrototypeOf(value) === Object.prototype
+        && Object.values(value).every(v => json(v, depth + 1));
+}
+export function size(value) { return Buffer.byteLength(JSON.stringify(value), 'utf8'); }
+function bounded(value) { return json(value) && size(value) <= limits.messageBytes; }
+function calls(value) {
+    return Array.isArray(value) && value.length <= limits.callsPerStep
+        && value.every(c => object(c) && id(c.id) && id(c.name) && bounded(c.arguments)
+            && size(c.arguments) <= limits.argumentBytes)
+        && new Set(value.map(c => c.id)).size === value.length;
+}
+export function validOutcome(value) {
+    return object(value) && bounded(value) && (value.ok === true ? text(value.content)
+        : value.ok === false && object(value.error) && id(value.error.code) && text(value.error.message)
+            && (value.error.effect === 'none' || value.error.effect === 'unknown'));
+}
+export function response(value, usedIds) {
+    if (!object(value) || !bounded(value) || !text(value.content)
+        || !(value.kind === 'final' || (value.kind === 'tool_calls' && calls(value.calls)
+            && value.calls.length > 0 && value.calls.every(c => !usedIds.has(c.id))))) {
+        throw new AgentFault('provider_protocol', 'Invalid, oversized or duplicate model response');
+    }
+    return snapshot(value);
+}
+export function history(value, maxBytes = limits.historyBytes) {
+    const pending = new Map();
+    const used = new Set();
+    if (!Array.isArray(value) || !json(value) || size(value) > maxBytes) {
+        throw new AgentFault('invalid_history', 'History must be bounded JSON messages');
+    }
+    for (const m of value) {
+        if (!object(m) || !bounded(m))
+            throw new AgentFault('invalid_history', 'Invalid history message');
+        if (m.role === 'tool') {
+            if (!id(m.toolCallId) || !id(m.name) || !validOutcome(m.outcome)
+                || pending.get(m.toolCallId) !== m.name || !pending.has(m.toolCallId)) {
+                throw new AgentFault('invalid_history', 'Tool results must match exactly one pending call');
+            }
+            pending.delete(m.toolCallId);
+        }
+        else {
+            if (pending.size || !text(m.content))
+                throw new AgentFault('invalid_history', 'Unsettled calls or invalid content');
+            if (m.role === 'assistant' && calls(m.toolCalls)) {
+                for (const c of m.toolCalls) {
+                    if (used.has(c.id))
+                        throw new AgentFault('invalid_history', 'Duplicate tool call identity');
+                    used.add(c.id);
+                    pending.set(c.id, c.name);
+                }
+            }
+            else if (m.role !== 'system' && m.role !== 'user') {
+                throw new AgentFault('invalid_history', 'Invalid message role or assistant calls');
+            }
+        }
+    }
+    if (pending.size)
+        throw new AgentFault('invalid_history', 'History contains unsettled calls');
+    return snapshot([...value]);
+}

package/dist/plugins/pluginService.js

@@ -98,24 +98,39 @@ export function createPluginService(store, host, registry) {
         source: `plugin:${pkg.manifest.id}@${pkg.digest}`, required: pkg.manifest.required
     }));
     const refFor = (taskId, pkg) => ({ id: keyFor(taskId, pkg.manifest.id), generation: randomUUID() });
+    const executionParams = (taskId, preparationId, pkg, phase) => ({
+        pluginId: pkg.manifest.id, digest: pkg.digest,
+        environmentRef: `${taskId}/${preparationId}`, trust: "trusted-local", phase
+    });
+    const executionGrant = (taskId, params, path, plannedUses = new Map()) => store.listCapabilityGrants(taskId).find(candidate => Object.entries(params).every(([key, value]) => candidate.parameterBounds[key]?.includes(value))
+        && (candidate.scope.taskId === undefined || candidate.scope.taskId === taskId)
+        && candidate.scope.projectIds === undefined && candidate.scope.repositories === undefined
+        && candidate.scope.packages === undefined
+        && (candidate.scope.homePath === undefined || candidate.scope.homePath === path)
+        && checkGrant({ ...candidate, usesUsed: candidate.usesUsed + (plannedUses.get(candidate.id) ?? 0) }, { action: "plugin.execute", params, irreversibility: "irreversible" }, new Date()).allowed);
+    const environmentAccess = (taskId, preparationId, via) => {
+        const prepared = store.getEnvironmentPreparation(taskId, preparationId);
+        if (!prepared)
+            throw new Error("Plugin environment preparation is missing.");
+        for (const resourceId of prepared.resourceRefs) {
+            const access = resources.assessLocalAccess(taskId, resourceId, prepared.access, via, prepared.id, true);
+            if (access.state !== "authorized")
+                return access;
+        }
+        return { state: "authorized" };
+    };
     /** Each execution consumes one use. A live call's bound closure carries its
      * admission; it is never resumed from a durable reservation or sent to code.
      * Subsequent actions still check current authority, not cached permission. */
     const execution = (taskId, preparationId, pkg, phase) => {
-        const params = { pluginId: pkg.manifest.id, digest: pkg.digest,
-            environmentRef: `${taskId}/${preparationId}`, trust: "trusted-local", phase };
+        const params = executionParams(taskId, preparationId, pkg, phase);
         // This grants the capability to run code without OS effect confinement;
         // it does not claim that every invocation actually has irreversible effects.
         const request = { action: "plugin.execute", params, irreversibility: "irreversible" };
         const reservation = phase === "call" ? undefined : `plugin/${randomUUID()}`;
         const grantId = store.transaction((tx) => {
             const env = environment(taskId, preparationId);
-            const grant = tx.listCapabilityGrants(taskId).find((candidate) => Object.entries(params).every(([key, value]) => candidate.parameterBounds[key]?.includes(value))
-                && (candidate.scope.taskId === undefined || candidate.scope.taskId === taskId)
-                && candidate.scope.projectIds === undefined && candidate.scope.repositories === undefined
-                && candidate.scope.packages === undefined
-                && (candidate.scope.homePath === undefined || candidate.scope.homePath === env.directory.path)
-                && checkGrant(candidate, request, new Date()).allowed);
+            const grant = executionGrant(taskId, params, env.directory.path);
             if (!grant)
                 throw new Error(`Explicit trusted-local execution grant unavailable (${phase}); pluginId=${params.pluginId}, digest=${params.digest}, environmentRef=${params.environmentRef}.`);
             tx.saveCapabilityGrant(taskId, recordGrantUse(grant, new Date(), reservation));
@@ -173,6 +188,81 @@ export function createPluginService(store, host, registry) {
         }
     };
     return {
+        assess(taskId, descriptor, input, via) {
+            let validationId;
+            let phase;
+            let pkg;
+            let preparationId;
+            let path;
+            if (descriptor.name === "plugin.validate") {
+                if (input === undefined)
+                    return undefined;
+                const params = input;
+                const prepared = store.getEnvironmentPreparation(taskId, params.preparationId);
+                if (!prepared?.directory)
+                    throw new Error("Plugin validation needs an existing directory preparation.");
+                const access = environmentAccess(taskId, prepared.id, via);
+                if (access.state !== "authorized")
+                    return access;
+                const directory = resolve(prepared.directory.path, params.directory);
+                packagePath(relative(prepared.directory.path, directory));
+                // Capture data only. Never run a build, prepare an environment or
+                // initialize a Provider just to assess the source's exact grant.
+                pkg = readPluginPackage(directory, false);
+                preparationId = prepared.id;
+                path = prepared.directory.path;
+                phase = "validate";
+            }
+            else if (descriptor.name === "plugin.activate") {
+                if (input === undefined)
+                    return undefined;
+                validationId = input.validationId;
+                phase = "activate";
+            }
+            else {
+                const selected = active.get(descriptor.provider.id);
+                if (!selected || selected.ref.generation !== descriptor.provider.generation)
+                    return undefined;
+                validationId = selected.validationId;
+                phase = "call";
+            }
+            // Inspect captured authorization parameters, not Host availability,
+            // filesystem readiness or author code. Execution owns those checks.
+            if (validationId !== undefined) {
+                const report = store.getPluginValidation(taskId, validationId);
+                if (!report)
+                    throw new Error("Plugin validation not found in this Task.");
+                pkg = report.package;
+                preparationId = report.preparationId;
+                path = report.environment.path;
+            }
+            if (phase !== "validate") {
+                const access = environmentAccess(taskId, preparationId, via);
+                if (access.state !== "authorized")
+                    return access;
+            }
+            if (pkg.manifest.kind === "declarative")
+                return { state: "authorized" };
+            const params = executionParams(taskId, preparationId, pkg, phase);
+            const phases = phase === "validate" && pkg.manifest.build ? ["build", "validate"] : [phase];
+            // Simulate the same ordered selection as execution, without persisting
+            // uses. A broad Grant may fund multiple phases only if it has capacity.
+            const plannedUses = new Map();
+            const missing = phases.filter(value => {
+                const grant = executionGrant(taskId, { ...params, phase: value }, path, plannedUses);
+                if (!grant)
+                    return true;
+                plannedUses.set(grant.id, (plannedUses.get(grant.id) ?? 0) + 1);
+                return false;
+            });
+            if (!missing.length)
+                return { state: "authorized" };
+            return { state: "requestable", request: {
+                    action: "plugin.execute", taskId,
+                    bounds: { ...Object.fromEntries(Object.entries(params).map(([key, value]) => [key, [value]])), phase: missing },
+                    via, explanation: "Trusted-local author code needs an exact, irreversible execution Grant. Use the existing authorization source and Grant path; discovery consumes no uses."
+                } };
+        },
         current: inspect,
         list(taskId) {
             return store.transaction(() => store.listPluginIntents(taskId)

package/dist/resources/projectResourceService.js

@@ -42,7 +42,7 @@ export function createProjectResources(store, now = () => new Date()) {
             throw new Error(`Local resource not found: ${resourceId}.`);
         return value;
     };
-    const grantFor = (taskId, resourceId, access, reservation, reservedOnly = false) => {
+    const findGrant = (taskId, resourceId, access, reservation, reservedOnly = false) => {
         const target = resource(resourceId);
         const grant = store.listCapabilityGrants(taskId).find((candidate) => {
             // A Project scope is visibility, not an exhaustive Resource grant. A
@@ -57,6 +57,10 @@ export function createProjectResources(store, now = () => new Date()) {
                 return false;
             return checkGrant(candidate, { action: `resource.local.${access}`, params: { resourceId } }, now(), { skipUsesCheck: reservation !== undefined && candidate.useReservations.includes(reservation) }).allowed;
         });
+        return grant;
+    };
+    const grantFor = (taskId, resourceId, access, reservation, reservedOnly = false) => {
+        const grant = findGrant(taskId, resourceId, access, reservation, reservedOnly);
         if (!grant)
             throw new Error(`Resource grant unavailable: ${resourceId}/${access}.`);
         return grant;
@@ -109,6 +113,24 @@ export function createProjectResources(store, now = () => new Date()) {
         });
     };
     return {
+        assessLocalAccess(taskId, resourceId, access, via, reservation, reservedOnly = false) {
+            const current = task(taskId);
+            // Only already-discoverable references may receive request guidance.
+            // Do not resolve an arbitrary global ID merely to confirm its existence.
+            const known = current.projectBindings.some(({ projectId }) => store.getProject(projectId)?.resourceRefs?.includes(resourceId))
+                || store.listCapabilityGrants(taskId).some(grant => grant.parameterBounds.resourceId?.includes(resourceId))
+                || store.listEnvironmentPreparations(taskId).some(value => value.resourceRefs.includes(resourceId))
+                || store.listEvents(taskId).some(event => event.type === "resource.local.registered" && event.payload.resourceId === resourceId);
+            if (!known)
+                return { state: "hidden" };
+            if (findGrant(taskId, resourceId, access, reservation, reservedOnly))
+                return { state: "authorized" };
+            return { state: "requestable", request: {
+                    action: `resource.local.${access}`, taskId, bounds: { resourceId: [resourceId] }, via,
+                    explanation: "Request this exact resource and access through existing Message/InputRequest and Grant authority. A response alone is not a Grant."
+                        + (reservedOnly ? " This environment's adoption reservation is no longer valid; inspect preparation/adoption before reusing it." : "")
+                } };
+        },
         resolveExecutionEnvironment,
         bindEnvironment(taskId, roleName, preparationId, source = { source: "environment.bind" }) {
             return store.transaction((tx) => {

package/dist/runtime/managedIdentity.js

@@ -0,0 +1,6 @@
+/** Presence is not authentication. Even partial transport identity must not
+ * silently acquire the authority of an unbound public caller. */
+export function hasManagedIdentity(environment) {
+    return ["YUI_SESSION_SCOPE", "YUI_ROLE", "YUI_AGENT_ID", "YUI_NATIVE_SESSION_ID",
+        "YUI_TASK_ID", "YUI_SESSION_MANIFEST"].some(key => environment[key] !== undefined);
+}

package/dist/surface/surfaceContributions.js

@@ -10,11 +10,14 @@ export class SurfaceContributions {
         return this.registry.search(context).map((entry) => ({
             ...reference(entry), name: entry.surfaces?.cli?.name ?? entry.name,
             help: entry.surfaces?.cli?.help ?? entry.summary, effect: entry.effect,
+            ...(entry.access === undefined ? {} : { access: entry.access }),
             ...(entry.unavailable === undefined ? {} : { unavailable: entry.unavailable })
         }));
     }
     listPanels(context) {
         return this.registry.search(context).flatMap((entry) => {
+            if (entry.access?.state === "requestable")
+                return [];
             const panel = entry.surfaces?.panel
                 ?? (entry.effect === "query" ? { kind: "data", title: entry.summary, renderer: "json" } : undefined);
             return panel ? [{