@zq-silk/yui 0.15.5 → 0.15.7

package/dist/cli/commandCatalog.js

@@ -985,7 +985,7 @@ export const ROOT_COMMAND = buildNode({
             ] },
         { id: "workflow", title: "Workflow", entries: ["operator", "project", "task"] },
         { id: "configuration", title: "Configuration", entries: ["config"] },
-        { id: "operations", title: "Operations", entries: ["web", "controller", "session", "execution", "job", "jobs", "telemetry", "release"] },
+        { id: "operations", title: "Operations", entries: ["web", "controller", "session", "execution", "capability", "job", "jobs", "telemetry", "release"] },
         { id: "resources", title: "Resources", entries: ["resources"] },
         { id: "internal", title: "Internal", entries: ["internal"] }
     ],
@@ -1386,6 +1386,16 @@ export const ROOT_COMMAND = buildNode({
             ],
             children: taskChildren
         },
+        {
+            name: "capability",
+            summary: "Discover and call authorized capabilities through the Controller.",
+            sections: [{ id: "entry", title: "Commands", entries: ["search", "describe", "call"] }],
+            children: [
+                { name: "search", summary: "Search the current authorized directory.", usage: "yui capability search [query] --task <id>" },
+                { name: "describe", summary: "Describe one contract or report Provider ambiguity.", usage: "yui capability describe <name> --task <id> [--provider <id>] [--version <version>]" },
+                { name: "call", summary: "Invoke one implementation under the current managed identity.", usage: "yui capability call <name> --task <id> --input <json> [--provider <id>] [--version <version>] [--request-id <id>]" }
+            ]
+        },
         {
             name: "job",
             summary: "Start, inspect, cancel, or acknowledge a Controller-managed DurableJob.",

package/dist/cli.js

@@ -24,6 +24,7 @@ import { nativeAgentEnvironmentNames } from "./agent/launchEnvironment.js";
 import { runAgentCommand } from "./commands/agentCommands.js";
 import { runGlobalRoleCommand } from "./commands/globalRoleCommands.js";
 import { runConfigCommand } from "./commands/configCommands.js";
+import { runCapabilityCommand } from "./commands/capabilityCommands.js";
 import { CONFIG_DOMAINS } from "./config/configCatalog.js";
 import { runConfigOverview } from "./commands/configOverview.js";
 import { parseControllerCleanupOptions, parseControllerStatusOptions, parseControllerRuntimeSnapshot, renderControllerResourceStatus, renderRuntimeIdentitySection, summarizeDurablePhysicalMismatch, runInteractiveControllerCleanup } from "./commands/controllerCommands.js";
@@ -249,6 +250,15 @@ export async function main() {
         emit(renderCommandHelp(target, VERSION), false, describeCommandTree(target));
         return;
     }
+    if (args[0] === "capability") {
+        const result = await runCapabilityCommand(args.slice(1), home, process.env);
+        emit(JSON.stringify(result, null, 2), false, result);
+        const kind = result?.kind;
+        if (typeof result === "object" && result !== null && !Array.isArray(result)
+            && typeof kind === "string" && !["value", "operation"].includes(kind))
+            process.exitCode = 5;
+        return;
+    }
     if (args[0] === "setup") {
         if (jsonOutput)
             throw usageError("Setup does not support --json.");

package/dist/commands/capabilityCommands.js

@@ -0,0 +1,54 @@
+import { usageError } from "../errors/cliError.js";
+import { resolveJobCaller } from "./taskActor.js";
+import { callFileTaskController } from "../controller/clientRuntime.js";
+export async function runCapabilityCommand(args, home, environment) {
+    const [action, ...rest] = args;
+    const usage = "yui capability search [query] --task <id> | describe <name> --task <id> [--provider <id>] [--version <version>] | call <name> --task <id> --input <json> [--provider <id>] [--version <version>] [--request-id <id>]";
+    if (!["search", "describe", "call"].includes(action))
+        throw usageError(usage);
+    const flags = new Map();
+    const positionals = [];
+    const allowed = new Set(["--task", "--provider", "--version", "--input", "--request-id"]);
+    for (let index = 0; index < rest.length; index += 1) {
+        const arg = rest[index];
+        if (!arg.startsWith("--")) {
+            positionals.push(arg);
+            continue;
+        }
+        const next = rest[++index];
+        if (!allowed.has(arg) || flags.has(arg) || next === undefined || next.startsWith("--")) {
+            throw usageError(`Invalid capability option: ${arg}.`, usage);
+        }
+        flags.set(arg, next);
+    }
+    const taskId = flags.get("--task") ?? environment.YUI_TASK_ID;
+    if (!taskId || positionals.length > 1 || (action !== "search" && !positionals.length))
+        throw usageError(usage);
+    if (action === "search" && [...flags.keys()].some((key) => key !== "--task"))
+        throw usageError(usage);
+    if (action === "describe" && (flags.has("--input") || flags.has("--request-id")))
+        throw usageError(usage);
+    let input;
+    if (action === "call") {
+        if (!flags.has("--input"))
+            throw usageError("Capability call requires --input <json>.", usage);
+        try {
+            input = JSON.parse(flags.get("--input"));
+        }
+        catch {
+            throw usageError("Invalid capability JSON input.");
+        }
+    }
+    return callFileTaskController(home, `capability.${action}`, {
+        taskId, caller: resolveJobCaller(environment, taskId),
+        ...(action === "search" ? { query: positionals[0] ?? "" } : {
+            request: {
+                name: positionals[0],
+                ...(input === undefined ? {} : { input }),
+                ...(flags.has("--provider") ? { providerId: flags.get("--provider") } : {}),
+                ...(flags.has("--version") ? { contractVersion: flags.get("--version") } : {}),
+                ...(flags.has("--request-id") ? { requestId: flags.get("--request-id") } : {})
+            }
+        })
+    }, { environment });
+}

package/dist/commands/taskCommands.js

@@ -471,30 +471,38 @@ function updateTaskCommand(args, store, options) {
     const tags = parsed.options.has("--tags")
         ? parseTaskTags(requiredOption(parsed.options, "--tags"))
         : undefined;
+    const result = updateTaskMetadataCommand(store, parsed.positionals[0], {
+        ...(parsed.options.has("--title") ? { title: requiredOption(parsed.options, "--title") } : {}),
+        ...(parsed.options.has("--type")
+            ? { type: requiredOption(parsed.options, "--type") }
+            : parsed.options.has("--clear-type") ? { type: null } : {}),
+        ...(parsed.options.has("--description")
+            ? { description: requiredOption(parsed.options, "--description") }
+            : parsed.options.has("--clear-description") ? { description: null } : {}),
+        ...(priority === undefined
+            ? parsed.options.has("--clear-priority") ? { priority: null } : {}
+            : { priority }),
+        ...(tags === undefined
+            ? parsed.options.has("--clear-tags") ? { tags: null } : {}
+            : { tags }),
+        ...(dueAt === undefined
+            ? parsed.options.has("--clear-due-at") ? { dueAt: null } : {}
+            : { dueAt })
+    }, options);
+    return `Updated task ${result.id}\n`;
+}
+/** Shared domain transaction for structured capabilities and the legacy CLI.
+ * Parsing text flags must not become an alternate business write path. */
+export function updateTaskMetadataCommand(store, taskId, patch, options = {}) {
+    if (Object.keys(patch).length === 0)
+        throw usageError("At least one Task metadata field is required.");
     const now = clock(options);
     const result = store.transaction((tx) => {
-        const current = requireTask(tx, parsed.positionals[0]);
+        const current = requireTask(tx, taskId);
         if (current.status === "archived")
             throw usageError(`Task is archived: ${current.id}.`);
         taskActor(tx, options, current.id);
-        const updated = updateTaskMetadata(current, {
-            ...(parsed.options.has("--title") ? { title: requiredOption(parsed.options, "--title") } : {}),
-            ...(parsed.options.has("--type")
-                ? { type: requiredOption(parsed.options, "--type") }
-                : parsed.options.has("--clear-type") ? { type: null } : {}),
-            ...(parsed.options.has("--description")
-                ? { description: requiredOption(parsed.options, "--description") }
-                : parsed.options.has("--clear-description") ? { description: null } : {}),
-            ...(priority === undefined
-                ? parsed.options.has("--clear-priority") ? { priority: null } : {}
-                : { priority }),
-            ...(tags === undefined
-                ? parsed.options.has("--clear-tags") ? { tags: null } : {}
-                : { tags }),
-            ...(dueAt === undefined
-                ? parsed.options.has("--clear-due-at") ? { dueAt: null } : {}
-                : { dueAt })
-        }, now);
+        const updated = updateTaskMetadata(current, patch, now);
         tx.saveTask(updated);
         recordTaskEvent(tx, updated.id, "task.updated", {
             status: updated.status,
@@ -504,7 +512,7 @@ function updateTaskCommand(args, store, options) {
         return updated;
     });
     notifyMailbox(options.runtime, taskMailbox(result.id), result.id);
-    return `Updated task ${result.id}\n`;
+    return result;
 }
 export function submitOperatorMessage(body, taskId, store, options = {}) {
     const now = clock(options);

package/dist/controller/capabilityBridge.js

@@ -0,0 +1,66 @@
+import { capabilitySchemaError } from "../kernel/capabilitySchema.js";
+/** The same transport method is usable by CLI, Agent and an authenticated
+ * Surface adapter. Credentials are an ingress envelope, never capability input. */
+export function createCapabilityDispatcher(capabilities) {
+    return async (method, value) => {
+        const error = capabilitySchemaError({
+            type: "object", required: ["taskId", "caller"],
+            additionalProperties: false,
+            properties: {
+                taskId: { type: "string", minLength: 1 },
+                caller: {
+                    type: "object", required: ["scope"], additionalProperties: false,
+                    properties: {
+                        scope: { enum: ["user", "global", "task"] }, taskId: { type: "string" },
+                        role: { type: "string" }, agentId: { type: "string" }, adapterId: { type: "string" },
+                        runtimeGenerationId: { type: "string" }, nativeSessionId: { type: "string" },
+                        turnId: { type: "string" }, callerKey: { type: "string" }
+                    }
+                },
+                query: { type: "string" },
+                request: {
+                    type: "object", required: ["name"], additionalProperties: false,
+                    properties: {
+                        name: { type: "string", minLength: 1 }, input: {},
+                        contractVersion: { type: "string", minLength: 1 },
+                        providerId: { type: "string", minLength: 1 },
+                        requestId: { type: "string", minLength: 1 }
+                    }
+                }
+            }
+        }, value);
+        if (error)
+            throw invalidParams(`Invalid capability envelope: ${error}`);
+        const params = value;
+        const context = capabilities.authenticate(params.caller, params.taskId);
+        let result;
+        if (method === "capability.search") {
+            if (params.request !== undefined)
+                throw invalidParams("search accepts query, not request.");
+            result = { capabilities: capabilities.registry.search(context, params.query) };
+        }
+        else {
+            if (params.query !== undefined || params.request === undefined)
+                throw invalidParams("describe/call requires request.");
+            if (method === "capability.describe")
+                result = capabilities.registry.describe(context, params.request);
+            else if (method === "capability.call") {
+                if (!Object.hasOwn(params.request, "input"))
+                    throw invalidParams("call requires input.");
+                // Target is bound before acquisition, not inferred from plugin actor data.
+                const input = params.request.input;
+                if (typeof input === "object" && input !== null && "taskId" in input
+                    && input.taskId !== params.taskId)
+                    throw invalidParams("Capability target is outside the authenticated Task.");
+                result = await capabilities.registry.call(context, params.request);
+            }
+            else
+                throw invalidParams("Unknown capability method.");
+        }
+        return JSON.parse(JSON.stringify(result));
+    };
+}
+/** Expected ingress rejections use the Controller's existing safe error shape. */
+function invalidParams(message) {
+    return Object.assign(new Error(message), { name: "CoreApplicationError", code: "INVALID_PARAMS" });
+}

package/dist/controller/controller.js

@@ -1667,6 +1667,19 @@ export async function startFileTaskController(home, store, delivery, dispatcher,
                 const intervalMs = runtime.reloadReconciliationInterval();
                 return { configured: true, reconciliationIntervalMs: intervalMs };
             }
+            if (method === "capability.search" || method === "capability.describe" || method === "capability.call") {
+                if (options.capabilityDispatcher === undefined) {
+                    throw controllerApplicationError("METHOD_NOT_FOUND", "Capability ingress is unavailable.");
+                }
+                const request = Promise.resolve(options.capabilityDispatcher(method, params));
+                lifecycleRequests.add(request);
+                try {
+                    return await request;
+                }
+                finally {
+                    lifecycleRequests.delete(request);
+                }
+            }
             if (method === "job.start" || method === "job.get" || method === "job.cancel" || method === "job.acknowledge") {
                 const control = options.jobControl;
                 if (control === undefined) {

package/dist/controller/runtime.js

@@ -23,6 +23,7 @@ import { openSchedulerTelemetry } from "../telemetry/telemetryWiring.js";
 import { createFileArtifactPort, createLinuxProcessPort, DurableJobSupervisor } from "./jobSupervisor.js";
 import { authorizeJobStart } from "./jobControl.js";
 import { createKernelPorts } from "../kernel/kernelPorts.js";
+import { createCapabilityDispatcher } from "./capabilityBridge.js";
 import { FileRuntimeEventInbox } from "./runtimeEventInbox.js";
 import { AgentRuntimeObserver } from "./agentRuntimeObserver.js";
 import { AsyncRuntimeEventProcessor, FileRuntimeEventProcessor, createAsyncRuntimeObserver, } from "./runtimeEventProcessor.js";
@@ -356,7 +357,9 @@ export async function startFileTaskControllerRuntime(home, options = {}) {
     // supervisor enqueues a durable-job-terminal event; the processor drains it
     // on the next pass, waking the Controller immediately instead of waiting for
     // the poll interval.
-    const kernel = createKernelPorts(store, createLinuxProcessPort());
+    const kernel = createKernelPorts(store, createLinuxProcessPort(), (taskId) => {
+        runningRuntime?.signal(`task:${taskId}`);
+    });
     const jobSupervisor = new DurableJobSupervisor({
         store: schedulerStore,
         process: kernel.runner,
@@ -419,6 +422,7 @@ export async function startFileTaskControllerRuntime(home, options = {}) {
         lifecycleHost,
         jobSupervisor,
         jobControl,
+        capabilityDispatcher: createCapabilityDispatcher(kernel.capabilities),
         ...(continuationReconciler === undefined ? {} : { continuationReconciler }),
         ...(resourceReaper === undefined ? {} : { resourceReaper }),
         resourceAutoGc,

package/dist/controller/runtimeLaunchCoordinator.js

@@ -76,8 +76,9 @@ export class RuntimeLaunchCoordinator {
         if (request.owner.scope === "global" && request.managedWorkspace !== undefined) {
             throw new Error("A global runtime cannot use a Task ManagedWorkspace.");
         }
+        let currentRequest = request;
         const assertLaunchCurrent = () => {
-            this.#assertCurrent?.(request);
+            this.#assertCurrent?.(currentRequest);
             assertCurrent?.();
         };
         const proposedGenerationId = requireText(this.#createGenerationId(), "Launch generation id");
@@ -155,8 +156,20 @@ export class RuntimeLaunchCoordinator {
                 throw new Error("Runtime host reported its pre-start launch fence more than once.");
             }
             validateRuntimeLaunchPreflight(preflight, request, runtimeGenerationId);
+            this.reservations.confirmRuntimeLaunchReservation({
+                owner: request.owner,
+                runtimeGenerationId
+            }, assertLaunchCurrent);
             preflightObserved = true;
             beforeHostStart?.(preflight);
+            // The pre-start persistence callback hands the fixed native Session to
+            // this reserved activation. From here on, fence against that exact new
+            // identity, not the historical Host we originally set out to restore.
+            // Do not accept both identities: a later change back is stale as well.
+            if (request.mode === "resume" && request.hostActivationId !== undefined) {
+                currentRequest = { ...request, hostActivationId: runtimeGenerationId };
+            }
+            assertLaunchCurrent();
         };
         let binding;
         try {
@@ -257,7 +270,7 @@ export class RuntimeLaunchCoordinator {
             throw error;
         }
         if (reusedConfirmedRunningHost && binding.hostCreated === true) {
-            await this.#compensateStartedHost(request.owner, binding, runtimeGenerationId, runtimeIsolation, new Error(`Runtime host was recreated while recovering an existing generation: ${request.owner.roleName}.`));
+            await this.#compensateStartedHost(request.owner, binding, runtimeGenerationId, runtimeIsolation, reusedConfirmedRunningHost, new Error(`Runtime host was recreated while recovering an existing generation: ${request.owner.roleName}.`));
         }
         try {
             assertLaunchCurrent();
@@ -282,7 +295,7 @@ export class RuntimeLaunchCoordinator {
             }
         }
         catch (error) {
-            await this.#compensateStartedHost(request.owner, binding, runtimeGenerationId, runtimeIsolation, error);
+            await this.#compensateStartedHost(request.owner, binding, runtimeGenerationId, runtimeIsolation, reusedConfirmedRunningHost, error);
         }
         return binding;
     }
@@ -317,7 +330,14 @@ export class RuntimeLaunchCoordinator {
             return;
         this.#requireCleanup(request.owner);
     }
-    async #compensateStartedHost(owner, binding, runtimeGenerationId, runtimeIsolation, cause) {
+    async #compensateStartedHost(owner, binding, runtimeGenerationId, runtimeIsolation, reusedConfirmedRunningHost, cause) {
+        if (reusedConfirmedRunningHost && binding.hostCreated !== true) {
+            // Reattaching an existing activation gives this launch no ownership of
+            // it. A fresh activation inside a persistent Host is different: this
+            // launch still owns its startup and isolation cleanup even when the
+            // physical Host did not need to be created.
+            throw new RuntimeLaunchStateChangedError(`Runtime launch state changed while reusing a Host: ${cause instanceof Error ? cause.message : String(cause)}`, { cause });
+        }
         try {
             await this.host.stop(binding);
         }

package/dist/kernel/builtinCapabilities.js

@@ -0,0 +1,188 @@
+import { updateTaskMetadataCommand } from "../commands/taskCommands.js";
+import { runConfigCommand } from "../commands/configCommands.js";
+import { CONFIG_DOMAINS } from "../config/configCatalog.js";
+import { createJobCallAuthority, parseDurableJobStartParams } from "../controller/jobControl.js";
+import { inspectJobOperation } from "./kernelPorts.js";
+import { CapabilityRegistry, } from "./capabilityRegistry.js";
+const text = { type: "string", minLength: 1 };
+const strings = { type: "object", additionalProperties: { type: "string" } };
+const object = (properties, required = Object.keys(properties)) => ({
+    type: "object", properties, required, additionalProperties: false
+});
+const taskInput = object({ taskId: text });
+const taskOutput = { type: "object", required: ["id", "status", "title"], properties: {
+        id: text, status: text, title: text
+    } };
+const provider = Object.freeze({ id: "yui:builtin-capabilities", generation: "1" });
+/** Source locators identify the existing semantic owner, not a new Store. */
+const definitions = [
+    {
+        name: "task.read", summary: "Read the current Task record.", effect: "query",
+        inputSchema: taskInput, outputSchema: taskOutput, requiredPermissions: ["task:read"],
+        source: "TaskStore.getTask (task show)"
+    },
+    {
+        name: "task.update", summary: "Update Task metadata through the existing command transaction.",
+        effect: "local-mutation", requiredPermissions: ["task:manage"],
+        source: "updateTaskMetadataCommand (task update)",
+        inputSchema: object({
+            taskId: text,
+            patch: object({
+                title: text, description: { type: "string" },
+                priority: { enum: ["low", "medium", "high", "urgent"] },
+                tags: { type: "array", items: text }
+            }, [])
+        }), outputSchema: taskOutput
+    },
+    {
+        name: "config.read", summary: "Read effective global configuration (Operator only).",
+        effect: "query", requiredPermissions: ["config:read"],
+        source: "runConfigCommand (config <domain> show)",
+        inputSchema: object({ domain: { enum: CONFIG_DOMAINS } }),
+        outputSchema: { type: "object" }
+    },
+    {
+        name: "resource.workspaces", summary: "Read the Task's managed workspace resources.",
+        effect: "query", requiredPermissions: ["task:read"],
+        source: "TaskStore.listManagedWorkspaces (task workspace list)",
+        inputSchema: taskInput, outputSchema: { type: "array", items: { type: "object", required: ["owner", "root", "entries"] } }
+    },
+    {
+        name: "job.get", summary: "Read the original Job and its operation evidence.",
+        effect: "query", requiredPermissions: ["task:read"],
+        source: "DurableJobControlPort.getJob (job.get RPC)",
+        inputSchema: object({ taskId: text, jobId: text }),
+        outputSchema: { type: "object", required: ["job", "operation"] }
+    },
+    {
+        name: "job.start", summary: "Request an idempotent Job through the existing Controller owner.",
+        effect: "external-operation", requiredPermissions: ["job:start"],
+        source: "DurableJobControlPort.startJob (job.start RPC)",
+        inputSchema: object({
+            taskId: text, projectId: text, head: text, workspace: text,
+            owner: { anyOf: [
+                    object({ kind: { const: "task" } }),
+                    object({ kind: { const: "work-item" }, workItemId: text }),
+                    object({ kind: { const: "integration-attempt" }, integrationAttemptId: text })
+                ] },
+            env: strings,
+            steps: { type: "array", minItems: 1, items: object({
+                    name: text, command: text, timeoutMs: { type: "integer" }
+                }, ["name", "command"]) },
+            retryOf: text
+        }, ["taskId", "projectId", "head", "workspace", "owner", "env", "steps"]),
+        outputSchema: { type: "object", required: ["job", "created", "operation"], properties: { created: { type: "boolean" } } }
+    },
+    ...["create", "validate", "activate", "disable"].map((action) => ({
+        name: `plugin.${action}`, summary: "Plugin SDK management is not implemented.",
+        effect: "local-mutation", requiredPermissions: ["plugin:manage"],
+        source: "T09 (not implemented)", inputSchema: object({}), outputSchema: object({}),
+        unavailable: "The executable plugin SDK is not implemented. Existing Agent Drivers and Project Skills retain their typed management interfaces."
+    }))
+];
+export const BUILTIN_CAPABILITIES = definitions.map((entry) => ({
+    ...entry, contractVersion: "1", provider, scope: { kind: "global" }
+}));
+/** Authenticated managed bridge. Socket possession/scope JSON is not a grant.
+ * A future user/Web ingress must provide its own verified identity adapter;
+ * this one deliberately accepts only the existing managed credentials. */
+export function createBuiltinCapabilities(host, store, jobs, signal = () => undefined) {
+    const authority = createJobCallAuthority(store);
+    const callers = new WeakMap();
+    const current = (context) => {
+        authority.authorize(context, context.targetId);
+        const caller = callers.get(context);
+        if (!caller)
+            throw new Error("Untrusted capability ingress.");
+        return caller;
+    };
+    const implementation = {
+        invoke(name, input, invocation) {
+            const caller = current(invocation.context);
+            const params = input;
+            if (params.taskId !== undefined && params.taskId !== invocation.context.targetId) {
+                throw new Error("Capability target is outside the authenticated Task.");
+            }
+            const taskId = invocation.context.targetId;
+            if (name === "task.read")
+                return requireTask(store, taskId);
+            if (name === "resource.workspaces")
+                return store.listManagedWorkspaces(taskId);
+            if (name === "config.read")
+                return runConfigCommand(params.domain, ["show"], store).data;
+            if (name === "task.update") {
+                const patch = params.patch;
+                return updateTaskMetadataCommand(store, taskId, {
+                    ...patch,
+                    ...(patch.description === "" ? { description: null } : {}),
+                    ...(patch.tags?.length === 0 ? { tags: null } : {})
+                }, {
+                    environment: callerEnvironment(caller),
+                    runtime: { notifyStateChanged: signal, reconcileTask: signal }
+                });
+            }
+            if (name === "job.get") {
+                const job = jobs.getJob(taskId, params.jobId);
+                if (!job)
+                    throw new Error(`Job not found: ${taskId}/${params.jobId}.`);
+                const operation = inspectJobOperation(job);
+                invocation.observe(operation);
+                return { job, operation };
+            }
+            if (name === "job.start") {
+                const parsed = parseDurableJobStartParams({
+                    ...params, caller, requestId: invocation.requestId
+                });
+                const { job, created } = jobs.startJob(parsed, new Date());
+                const operation = inspectJobOperation(job);
+                invocation.observe(operation);
+                if (created)
+                    signal(taskId);
+                return { job, created, operation };
+            }
+            throw new Error(`Builtin capability unavailable: ${name}.`);
+        }
+    };
+    host.attach(provider, implementation);
+    const registry = new CapabilityRegistry(host, (context, descriptor, input) => {
+        const caller = current(context);
+        const task = requireTask(store, context.targetId);
+        if (typeof input === "object" && input !== null && "taskId" in input && input.taskId !== task.id) {
+            throw new Error("Capability target is outside the authenticated Task.");
+        }
+        for (const permission of descriptor?.requiredPermissions ?? []) {
+            if (permission === "task:read" || permission === "job:start")
+                continue;
+            if (permission === "task:manage" && ((caller.scope === "task" && caller.role === "leader")
+                || (caller.scope === "global" && caller.role === "operator")))
+                continue;
+            if ((permission === "config:read" || permission === "plugin:manage")
+                && caller.scope === "global" && caller.role === "operator")
+                continue;
+            throw new Error(`Permission unavailable: ${permission}.`);
+        }
+        return { taskIds: [task.id], projectIds: task.projectBindings.map((binding) => binding.projectId) };
+    }, BUILTIN_CAPABILITIES);
+    return {
+        registry,
+        authenticate(caller, taskId) {
+            const credential = Object.freeze({ ...caller });
+            const context = authority.authenticate(credential, taskId);
+            callers.set(context, credential);
+            return context;
+        }
+    };
+}
+function requireTask(store, taskId) {
+    const task = store.getTask(taskId);
+    if (!task)
+        throw new Error(`Task not found: ${taskId}.`);
+    return task;
+}
+function callerEnvironment(caller) {
+    return {
+        YUI_SESSION_SCOPE: caller.scope, YUI_TASK_ID: caller.taskId,
+        YUI_ROLE: caller.role, YUI_AGENT_ID: caller.agentId,
+        YUI_ADAPTER_ID: caller.adapterId, YUI_JOB_CALLER_KEY: caller.callerKey
+    };
+}

package/dist/kernel/capabilityRegistry.js

@@ -0,0 +1,268 @@
+import { capabilitySchemaError, checkCapabilitySchema } from "./capabilitySchema.js";
+const effectRank = { query: 0, "local-mutation": 1, "external-operation": 2 };
+const reserved = new Set(["yui", "task", "config", "job", "resource", "plugin", "runtime", "grant", "capability"]);
+/** One rebuildable descriptor view over the composition root's existing Host.
+ * Only the trusted root owns this object. Extensions receive a bound invocation
+ * port, never the registry/Host or an actor-selecting call interface. */
+export class CapabilityRegistry {
+    host;
+    authorize;
+    #descriptors = [];
+    #coreProviders = new Set();
+    constructor(host, authorize, builtins = []) {
+        this.host = host;
+        this.authorize = authorize;
+        this.#publish(builtins, true);
+        builtins.forEach((entry) => this.#coreProviders.add(entry.provider.id));
+    }
+    /** Publish a complete provider generation atomically after owner initialization.
+     * Failure leaves all existing descriptors intact. Host lifecycle remains owned
+     * by the root: publish replacement, then detach old generation when appropriate. */
+    register(descriptors) {
+        this.#publish(descriptors, false);
+    }
+    disable(providerId) {
+        this.#descriptors = this.#descriptors.filter((entry) => entry.provider.id !== providerId);
+    }
+    search(context, query = "") {
+        const visibility = this.authorize(context);
+        const authorized = this.#descriptors.filter((entry) => visible(entry.scope, visibility))
+            .filter((entry) => {
+            try {
+                this.authorize(context, entry);
+                return true;
+            }
+            catch {
+                return false;
+            }
+        });
+        return authorized.filter((entry) => `${entry.name} ${entry.summary}`.toLowerCase().includes(query.toLowerCase()))
+            .map((entry) => {
+            const unavailable = this.#unavailable(entry, authorized, new Set());
+            return unavailable === undefined ? entry : Object.freeze({ ...entry, unavailable });
+        });
+    }
+    describe(context, request) {
+        try {
+            const candidates = this.search(context).filter((entry) => entry.name === request.name
+                && (request.contractVersion === undefined || request.contractVersion === entry.contractVersion)
+                && (request.providerId === undefined || request.providerId === entry.provider.id));
+            if (!candidates.length)
+                return result("unavailable", "No authorized compatible Provider is available.");
+            const available = candidates.filter((entry) => entry.unavailable === undefined);
+            if (!available.length)
+                return {
+                    ...result("unavailable", candidates.map((entry) => `${entry.provider.id}: ${entry.unavailable}`).join("; ")),
+                    candidates
+                };
+            if (available.length > 1)
+                return { ...result("ambiguous", "Select an explicit Provider and contract version."), candidates };
+            const selected = available[0];
+            return {
+                ...result("value"), value: selected, candidates, provider: selected.provider,
+                selection: request.providerId === undefined ? "unique" : "explicit"
+            };
+        }
+        catch {
+            return result("denied", "Current call authority is unavailable.");
+        }
+    }
+    call(context, request) {
+        return this.#call(context, request, "external-operation");
+    }
+    async #call(context, request, ceiling) {
+        // Freeze one input snapshot across validation/acquisition and async nesting.
+        try {
+            request = deepFreeze(structuredClone(request));
+        }
+        catch {
+            return result("invalid", "Capability request must be cloneable data.");
+        }
+        const resolved = this.describe(context, request);
+        if (resolved.kind !== "value")
+            return resolved;
+        const descriptor = resolved.value;
+        const origin = { provider: descriptor.provider, selection: resolved.selection };
+        if (effectRank[descriptor.effect] > effectRank[ceiling]) {
+            return { ...result("denied", "Nested call exceeds the parent's effect boundary."), ...origin };
+        }
+        const inputError = capabilitySchemaError(descriptor.inputSchema, request.input);
+        if (inputError)
+            return { ...result("invalid", inputError), ...origin };
+        if (descriptor.effect !== "query" && (typeof request.requestId !== "string" || !request.requestId.trim())) {
+            return { ...result("invalid", "Effectful calls require requestId."), ...origin };
+        }
+        try {
+            this.authorize(context, descriptor, request.input);
+        }
+        catch {
+            return { ...result("denied", "Current call authority was revoked."), ...origin };
+        }
+        const operations = [];
+        let effect = "none";
+        const observe = (operation) => {
+            operations.push(structuredClone(operation));
+            effect = accumulatedEffect(effect, operation.effect);
+        };
+        let entered = false;
+        try {
+            const value = await this.host.use(descriptor.provider, async (implementation) => {
+                entered = true;
+                let open = true;
+                const children = [];
+                try {
+                    return await implementation.invoke(descriptor.name, request.input, Object.freeze({
+                        context, requestId: request.requestId,
+                        observe: (operation) => {
+                            if (!open)
+                                throw new Error("Capability invocation has ended.");
+                            observe(operation);
+                        },
+                        call: (nested) => {
+                            if (!open)
+                                return Promise.resolve(result("denied", "Capability invocation has ended."));
+                            const child = this.#call(context, nested, descriptor.effect).then((outcome) => {
+                                outcome.operations.forEach(observe);
+                                effect = accumulatedEffect(effect, outcome.effect);
+                                return outcome;
+                            });
+                            children.push(child);
+                            return child;
+                        }
+                    }));
+                }
+                finally {
+                    open = false;
+                    // A wrapper throwing early must not detach its already-issued child
+                    // operations from the returned evidence or release the parent handle.
+                    await Promise.all(children);
+                }
+            });
+            if (descriptor.effect === "local-mutation")
+                effect = accumulatedEffect(effect, "confirmed");
+            // An external implementation without an owner's operation reference is not
+            // proof of success. Preserve uncertainty rather than return a value success.
+            if (descriptor.effect === "external-operation" && !operations.length) {
+                return { kind: "failed", detail: "External implementation returned no operation evidence.", effect: "possible", operations, ...origin };
+            }
+            let output;
+            try {
+                output = JSON.parse(JSON.stringify(value, (_key, item) => {
+                    if ((typeof item === "number" && !Number.isFinite(item))
+                        || typeof item === "bigint" || typeof item === "function" || typeof item === "symbol") {
+                        throw new Error("Output contains a non-JSON value.");
+                    }
+                    return item;
+                }));
+            }
+            catch {
+                if (descriptor.effect !== "query")
+                    effect = accumulatedEffect(effect, "possible");
+                return { kind: "invalid", detail: "Output is not JSON serializable.", effect, operations, ...origin };
+            }
+            const outputError = capabilitySchemaError(descriptor.outputSchema, output);
+            if (outputError) {
+                if (descriptor.effect !== "query")
+                    effect = accumulatedEffect(effect, "possible");
+                return { kind: "invalid", detail: `Output ${outputError}`, effect, operations, ...origin };
+            }
+            return { kind: operations.length ? "operation" : "value", value: output, effect, operations, ...origin };
+        }
+        catch (error) {
+            // An unrelated observation (including a historical queued Job with none)
+            // cannot prove that a failing effectful wrapper performed no other action.
+            // Preserve the owner's precise facts while reporting wrapper uncertainty.
+            if (entered && descriptor.effect !== "query")
+                effect = accumulatedEffect(effect, "possible");
+            return {
+                kind: entered ? "failed" : "unavailable",
+                detail: error instanceof Error ? error.message : "Capability invocation failed.",
+                effect, operations, ...origin
+            };
+        }
+    }
+    #unavailable(entry, authorized, visiting) {
+        if (entry.unavailable !== undefined)
+            return entry.unavailable;
+        if (!this.host.isAvailable(entry.provider))
+            return "Provider implementation is not available.";
+        if (visiting.has(entry))
+            return "Required capability dependency cycle.";
+        const path = new Set([...visiting, entry]);
+        // Only declared exact name/version edges are checked. No installation,
+        // priority policy, version solver or persisted dependency state is involved.
+        const missing = entry.required?.filter((dependency) => !authorized.some((candidate) => (candidate.name === dependency.name && candidate.contractVersion === dependency.contractVersion
+            && this.#unavailable(candidate, authorized, path) === undefined)));
+        if (missing?.length)
+            return `Missing available required capabilities: ${missing.map((dependency) => `${dependency.name}@${dependency.contractVersion}`).join(", ")}.`;
+        return undefined;
+    }
+    #publish(descriptors, core) {
+        if (!descriptors.length)
+            return;
+        const prepared = structuredClone(descriptors);
+        const provider = prepared[0].provider;
+        if (!core && this.#coreProviders.has(provider.id))
+            throw new Error("Core Provider identity is reserved.");
+        const names = new Set();
+        for (const entry of prepared) {
+            if (!/^[a-z][a-z0-9-]*(?:\.[a-z][a-z0-9-]*)+$/u.test(entry.name)
+                || !entry.contractVersion?.trim() || !entry.source?.trim()
+                || !Object.hasOwn(effectRank, entry.effect)
+                || !Array.isArray(entry.requiredPermissions)
+                || entry.requiredPermissions.some((permission) => typeof permission !== "string" || !permission.trim())) {
+                throw new Error("Invalid capability descriptor.");
+            }
+            if (!core && reserved.has(entry.name.split(".")[0]))
+                throw new Error("Core capability namespace is reserved.");
+            if (!["global", "project", "task"].includes(entry.scope.kind)
+                || (entry.scope.kind !== "global" && !entry.scope.id?.trim()))
+                throw new Error("Invalid capability scope.");
+            if (entry.provider.id !== provider.id || entry.provider.generation !== provider.generation) {
+                throw new Error("Publish one complete Provider generation at a time.");
+            }
+            const key = `${entry.name}@${entry.contractVersion}`;
+            if (names.has(key))
+                throw new Error(`Duplicate capability: ${key}.`);
+            names.add(key);
+            checkCapabilitySchema(entry.inputSchema);
+            checkCapabilitySchema(entry.outputSchema);
+            for (const dependency of entry.required ?? []) {
+                if (!dependency.name?.trim() || !dependency.contractVersion?.trim())
+                    throw new Error("Invalid required capability.");
+            }
+        }
+        // Validate acquisition before publishing; no implementation is invoked.
+        if (prepared.some((entry) => !entry.unavailable)) {
+            const handle = this.host.acquire(provider);
+            try {
+                if (typeof handle.value?.invoke !== "function")
+                    throw new Error("Provider has no capability implementation.");
+            }
+            finally {
+                void handle.release();
+            }
+        }
+        this.#descriptors = [
+            ...this.#descriptors.filter((entry) => entry.provider.id !== provider.id),
+            ...prepared.map((entry) => deepFreeze(entry))
+        ];
+    }
+}
+function visible(scope, visibility) {
+    return scope.kind === "global" || (scope.kind === "task"
+        ? visibility.taskIds.includes(scope.id) : visibility.projectIds.includes(scope.id));
+}
+function result(kind, detail) {
+    return { kind, effect: "none", operations: [], ...(detail === undefined ? {} : { detail }) };
+}
+function accumulatedEffect(a, b) {
+    return a === "confirmed" || b === "confirmed" ? "confirmed" : a === "possible" || b === "possible" ? "possible" : "none";
+}
+function deepFreeze(value) {
+    if (value !== null && typeof value === "object") {
+        Object.values(value).forEach(deepFreeze);
+        Object.freeze(value);
+    }
+    return value;
+}

package/dist/kernel/capabilitySchema.js

@@ -0,0 +1,91 @@
+import { isDeepStrictEqual } from "node:util";
+export function checkCapabilitySchema(schema) {
+    if (typeof schema !== "object" || schema === null || Array.isArray(schema)) {
+        throw new Error("Capability schema must be an object.");
+    }
+    const keywords = new Set([
+        "type", "properties", "required", "additionalProperties", "items",
+        "enum", "const", "anyOf", "minLength", "minItems"
+    ]);
+    for (const key of Object.keys(schema)) {
+        if (!keywords.has(key))
+            throw new Error(`Unsupported schema keyword: ${key}.`);
+    }
+    if (schema.type !== undefined
+        && !["object", "array", "string", "number", "integer", "boolean", "null"].includes(schema.type)) {
+        throw new Error("Unsupported schema type.");
+    }
+    if (schema.required !== undefined && (!Array.isArray(schema.required)
+        || schema.required.some((key) => typeof key !== "string")))
+        throw new Error("Invalid schema required.");
+    for (const bound of [schema.minLength, schema.minItems]) {
+        if (bound !== undefined && (!Number.isSafeInteger(bound) || bound < 0))
+            throw new Error("Invalid schema bound.");
+    }
+    if (schema.enum !== undefined && (!Array.isArray(schema.enum) || schema.enum.length === 0)) {
+        throw new Error("Invalid schema enum.");
+    }
+    if (schema.anyOf !== undefined) {
+        if (!Array.isArray(schema.anyOf) || !schema.anyOf.length)
+            throw new Error("Invalid schema anyOf.");
+        schema.anyOf.forEach(checkCapabilitySchema);
+    }
+    if (schema.properties !== undefined) {
+        if (typeof schema.properties !== "object" || schema.properties === null || Array.isArray(schema.properties)) {
+            throw new Error("Invalid schema properties.");
+        }
+        Object.values(schema.properties).forEach(checkCapabilitySchema);
+    }
+    if (schema.items !== undefined)
+        checkCapabilitySchema(schema.items);
+    if (schema.additionalProperties !== undefined && typeof schema.additionalProperties !== "boolean") {
+        checkCapabilitySchema(schema.additionalProperties);
+    }
+}
+export function capabilitySchemaError(schema, value, path = "$") {
+    if ("const" in schema && !isDeepStrictEqual(value, schema.const))
+        return `${path}: unexpected value.`;
+    if (schema.enum && !schema.enum.some((item) => isDeepStrictEqual(item, value)))
+        return `${path}: not in enum.`;
+    if (schema.anyOf && !schema.anyOf.some((branch) => capabilitySchemaError(branch, value) === undefined)) {
+        return `${path}: no matching schema branch.`;
+    }
+    const type = value === null ? "null" : Array.isArray(value) ? "array" : typeof value;
+    if (schema.type !== undefined && (schema.type === "integer"
+        ? typeof value !== "number" || !Number.isSafeInteger(value)
+        : type !== schema.type))
+        return `${path}: expected ${schema.type}.`;
+    if (typeof value === "number" && !Number.isFinite(value))
+        return `${path}: non-finite number.`;
+    if (typeof value === "string" && schema.minLength !== undefined && value.length < schema.minLength) {
+        return `${path}: string too short.`;
+    }
+    if (Array.isArray(value)) {
+        if (schema.minItems !== undefined && value.length < schema.minItems)
+            return `${path}: array too short.`;
+        if (schema.items) {
+            for (const [index, item] of value.entries()) {
+                const error = capabilitySchemaError(schema.items, item, `${path}[${index}]`);
+                if (error)
+                    return error;
+            }
+        }
+    }
+    else if (type === "object") {
+        const record = value;
+        for (const key of schema.required ?? []) {
+            if (!Object.hasOwn(record, key))
+                return `${path}.${key}: required.`;
+        }
+        for (const [key, item] of Object.entries(record)) {
+            const property = Object.hasOwn(schema.properties ?? {}, key) ? schema.properties[key] : undefined;
+            if (!property && schema.additionalProperties === false)
+                return `${path}.${key}: unexpected property.`;
+            const child = property ?? (typeof schema.additionalProperties === "object" ? schema.additionalProperties : undefined);
+            const error = child && capabilitySchemaError(child, item, `${path}.${key}`);
+            if (error)
+                return error;
+        }
+    }
+    return undefined;
+}

package/dist/kernel/instanceHost.js

@@ -19,6 +19,12 @@ export class InstanceHost {
         });
         return ref;
     }
+    /** Read-only availability for the rebuildable capability directory. This is
+     * not an acquisition or a grant; acquire still checks immediately before use. */
+    isAvailable(implementation) {
+        const instance = this.#instances.get(implementationKey(implementation));
+        return !this.#closed && instance !== undefined && !instance.detached;
+    }
     acquire(implementation) {
         const instance = this.#instances.get(implementationKey(implementation));
         if (this.#closed || instance === undefined || instance.detached) {

package/dist/kernel/kernelPorts.js

@@ -1,19 +1,22 @@
 import { createDurableJobControl } from "../controller/jobControl.js";
 import { JOB_RUNNER_IMPLEMENTATION } from "../job/durableJob.js";
 import { InstanceHost } from "./instanceHost.js";
+import { createBuiltinCapabilities } from "./builtinCapabilities.js";
 /** Called once by the existing Controller root. Does not open a Store, start
  * another Controller, or provide arbitrary persistence to plugin code.
  * T02 registers contributions on this Host and wraps this same Job control.
  */
-export function createKernelPorts(store, runner) {
+export function createKernelPorts(store, runner, signal = () => undefined) {
     const host = new InstanceHost();
     const runnerImplementation = host.attach(JOB_RUNNER_IMPLEMENTATION, runner);
     const runnerHandle = host.acquire(runnerImplementation);
     const jobImplementation = host.attach({ id: "yui:job-control", generation: "1" }, createDurableJobControl(store));
     // The Controller is a long-lived consumer of this exact implementation.
     const jobHandle = host.acquire(jobImplementation);
+    const capabilities = createBuiltinCapabilities(host, store, jobHandle.value, signal);
     return {
         host,
+        capabilities,
         jobImplementation,
         runnerImplementation,
         runner: runnerHandle.value,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zq-silk/yui",
-  "version": "0.15.5",
+  "version": "0.15.7",
   "description": "Local control plane for long-running native agent CLI sessions backed by tmux.",
   "license": "MIT",
   "private": false,
@@ -39,12 +39,12 @@
   ],
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/zhangqian-silk/Yui.git"
+    "url": "git+https://github.com/zhangqian-silk/yui.git"
   },
   "bugs": {
-    "url": "https://github.com/zhangqian-silk/Yui/issues"
+    "url": "https://github.com/zhangqian-silk/yui/issues"
   },
-  "homepage": "https://github.com/zhangqian-silk/Yui#readme",
+  "homepage": "https://github.com/zhangqian-silk/yui#readme",
   "dependencies": {
     "@xterm/addon-fit": "^0.11.0",
     "@xterm/xterm": "^6.0.0",