@zq-silk/yui 1.1.2 → 2.1.0

package/dist/kernel/capabilityRegistry.js

@@ -17,11 +17,13 @@ const reserved = new Set(["yui", "task", "context", "config", "job", "resource",
 export class CapabilityRegistry {
     host;
     authorize;
+    assess;
     #descriptors = [];
     #coreProviders = new Set();
-    constructor(host, authorize, builtins = []) {
+    constructor(host, authorize, builtins = [], assess) {
         this.host = host;
         this.authorize = authorize;
+        this.assess = assess;
         this.#publish(builtins, true);
         builtins.forEach((entry) => this.#coreProviders.add(entry.provider.id));
     }
@@ -38,7 +40,7 @@ export class CapabilityRegistry {
         if (!prepared.length)
             throw new Error("Plugin must contribute capabilities.");
         const available = [
-            ...this.search(context).filter((entry) => entry.provider.id !== prepared[0].provider.id),
+            ...this.#authorized(context).filter((entry) => entry.provider.id !== prepared[0].provider.id),
             ...prepared
         ];
         const check = (entry, path) => {
@@ -47,7 +49,8 @@ export class CapabilityRegistry {
                 throw new Error("Required capability dependency cycle.");
             for (const dependency of entry.required ?? []) {
                 const matches = available.filter((candidate) => candidate.name === dependency.name
-                    && candidate.contractVersion === dependency.contractVersion && candidate.unavailable === undefined);
+                    && candidate.contractVersion === dependency.contractVersion && candidate.unavailable === undefined
+                    && (prepared.includes(candidate) || this.host.isAvailable(candidate.provider)));
                 if (matches.length !== 1)
                     throw new Error(`Required capability is missing or ambiguous: ${dependency.name}.`);
                 check(matches[0], new Set([...path, entry]));
@@ -58,9 +61,9 @@ export class CapabilityRegistry {
     disable(providerId) {
         this.#descriptors = this.#descriptors.filter((entry) => entry.provider.id !== providerId);
     }
-    search(context, query = "") {
+    #authorized(context) {
         const visibility = this.authorize(context);
-        const authorized = this.#descriptors.filter((entry) => visible(entry.scope, visibility))
+        return this.#descriptors.filter((entry) => visible(entry.scope, visibility))
             .filter((entry) => {
             try {
                 this.authorize(context, entry);
@@ -70,25 +73,28 @@ export class CapabilityRegistry {
                 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) {
+    search(context, query = "") {
+        // Descriptor discovery must not acquire or inspect runtime Providers. These
+        // are templates: without input, no exact-target authorization is asserted.
+        return this.#authorized(context).filter((entry) => `${entry.name} ${entry.summary}`.toLowerCase().includes(query.toLowerCase()))
+            .map(entry => {
+            const access = this.assess?.(context, entry, undefined);
+            return access ? { ...entry, access } : entry;
+        }).filter(entry => !("access" in entry) || entry.access?.state !== "hidden");
+    }
+    #select(context, request, execution) {
         try {
-            const candidates = this.search(context).filter((entry) => entry.name === request.name
+            const authorized = this.#authorized(context);
+            const candidates = authorized.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
-                };
+            const available = execution ? candidates.filter(entry => this.#unavailable(entry, authorized, new Set()) === undefined) : candidates;
+            if (!available.length) {
+                return { ...result("unavailable", candidates.map(entry => `${entry.provider.id}: ${this.#unavailable(entry, authorized, new Set())}`).join("; ")), candidates };
+            }
             if (available.length > 1)
                 return { ...result("ambiguous", "Select an explicit Provider and contract version."), candidates };
             const selected = available[0];
@@ -101,6 +107,32 @@ export class CapabilityRegistry {
             return result("denied", "Current call authority is unavailable.");
         }
     }
+    describe(context, request) {
+        const selected = this.#select(context, request, false);
+        if (selected.kind !== "value")
+            return selected;
+        const descriptor = selected.value;
+        if (Object.hasOwn(request, "input")) {
+            const error = capabilitySchemaError(descriptor.inputSchema, request.input);
+            if (error)
+                return result("invalid", error);
+            try {
+                this.authorize(context, descriptor, request.input);
+            }
+            catch {
+                return result("denied", "Current call authority is unavailable.");
+            }
+        }
+        try {
+            const access = this.assess?.(context, descriptor, request.input);
+            if (access?.state === "hidden")
+                return result("unavailable", "No authorized compatible Provider is available.");
+            return access ? { ...selected, value: { ...descriptor, access } } : selected;
+        }
+        catch (error) {
+            return result("failed", error instanceof Error ? error.message : "Authorization assessment failed.");
+        }
+    }
     call(context, request) {
         return this.#call(context, request, "external-operation");
     }
@@ -112,7 +144,11 @@ export class CapabilityRegistry {
         catch {
             return result("invalid", "Capability request must be cloneable data.");
         }
-        const resolved = this.describe(context, request);
+        // Execution selects independently of discovery assessment and rechecks the
+        // exact input below. A requestable descriptor never grants admission.
+        const resolved = this.#select(context, {
+            name: request.name, contractVersion: request.contractVersion, providerId: request.providerId
+        }, true);
         if (resolved.kind !== "value")
             return resolved;
         const descriptor = resolved.value;
@@ -135,6 +171,15 @@ export class CapabilityRegistry {
         catch {
             return { ...result("denied", "Current call authority was revoked."), ...origin };
         }
+        try {
+            const access = this.assess?.(context, descriptor, request.input);
+            if (access && access.state !== "authorized") {
+                return { ...result("denied", "Exact target authorization is required."), ...origin };
+            }
+        }
+        catch (error) {
+            return { ...result("failed", error instanceof Error ? error.message : "Authorization assessment failed."), ...origin };
+        }
         const operations = [];
         let effect = "none";
         const observe = (operation) => {

package/dist/kernel/kernelPorts.js

@@ -6,14 +6,14 @@ import { InstanceHost } from "./instanceHost.js";
  * 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, signal = () => undefined, contextProviders = []) {
+export function createKernelPorts(store, runner, signal = () => undefined, contextProviders = [], archiveTask) {
     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, contextProviders);
+    const capabilities = createBuiltinCapabilities(host, store, jobHandle.value, signal, contextProviders, archiveTask);
     return {
         host,
         capabilities,

package/dist/nativeAgent/agent.js

@@ -0,0 +1,173 @@
+import { AgentFault, history, limits, response, size, snapshot, validOutcome } from './validation.js';
+const failed = (code, message, effect = 'none') => ({ ok: false, error: { code, message, effect } });
+export function createAgent(options) {
+    const tools = new Map(options.tools.map(t => [t.definition.name, t]));
+    if (tools.size !== options.tools.length || [...tools.keys()].some(name => !name.trim())) {
+        throw new Error('Tool names must be unique and nonempty');
+    }
+    const definitions = snapshot(options.tools.map(t => t.definition));
+    return {
+        async runTurn(input) {
+            const scope = { sessionId: input.sessionId, turnId: input.turnId };
+            const signal = input.signal ?? new AbortController().signal;
+            const messages = [];
+            const events = [];
+            let steps = 0;
+            let reason = 'error';
+            let error;
+            let sinkFailed = false;
+            const emit = async (data) => {
+                const event = snapshot({ ...scope, seq: events.length + 1, data });
+                events.push(event);
+                if (options.onEvent && !sinkFailed) {
+                    try {
+                        await options.onEvent(event);
+                    }
+                    catch {
+                        sinkFailed = true;
+                        error = { code: 'event_sink_failed', message: 'Event sink rejected a fact; inspect in-memory evidence' };
+                    }
+                }
+            };
+            const append = async (message, step) => {
+                const saved = snapshot(message);
+                messages.push(saved);
+                await emit({ type: 'message_appended', step, message: saved });
+            };
+            await emit({ type: 'turn_started' });
+            try {
+                if (!scope.sessionId?.trim() || !scope.turnId?.trim()
+                    || !Number.isSafeInteger(input.maxSteps) || input.maxSteps < 1 || typeof input.input !== 'string'
+                    || size({ role: 'user', content: input.input }) > limits.messageBytes) {
+                    throw new AgentFault('invalid_input', 'Nonempty identities, bounded input and positive integer maxSteps required');
+                }
+                const prior = history(input.history ?? []);
+                const usedIds = new Set(prior.flatMap(m => m.role === 'assistant' ? m.toolCalls.map(c => c.id) : []));
+                await append({ role: 'user', content: input.input });
+                while (!sinkFailed) {
+                    if (signal.aborted) {
+                        reason = 'cancelled';
+                        break;
+                    }
+                    if (steps >= input.maxSteps) {
+                        reason = 'budget_exhausted';
+                        break;
+                    }
+                    const all = [...prior, ...messages];
+                    if (size(all) > limits.historyBytes)
+                        throw new AgentFault('context_limit', 'History exceeds context byte limit');
+                    steps++;
+                    await emit({ type: 'step_started', step: steps });
+                    try {
+                        if (sinkFailed)
+                            break;
+                        if (signal.aborted) {
+                            reason = 'cancelled';
+                            break;
+                        }
+                        const request = snapshot({ ...scope, step: steps, messages: all, tools: definitions });
+                        let raw;
+                        try {
+                            raw = await options.provider.complete(request, signal);
+                        }
+                        catch (cause) {
+                            if (signal.aborted) {
+                                reason = 'cancelled';
+                                break;
+                            }
+                            throw new AgentFault('provider_error', cause instanceof Error ? cause.message : String(cause));
+                        }
+                        if (signal.aborted) {
+                            reason = 'cancelled';
+                            break;
+                        }
+                        const model = response(raw, usedIds);
+                        if (model.kind === 'final') {
+                            await append({ role: 'assistant', content: model.content, toolCalls: [] }, steps);
+                            reason = signal.aborted ? 'cancelled' : 'completed';
+                            break;
+                        }
+                        await append({ role: 'assistant', content: model.content, toolCalls: model.calls }, steps);
+                        let uncertain = false;
+                        for (const call of model.calls) {
+                            usedIds.add(call.id);
+                            let outcome;
+                            if (sinkFailed || uncertain || signal.aborted) {
+                                outcome = failed(signal.aborted ? 'cancelled_before_start' : 'not_started', 'Tool was not started');
+                            }
+                            else {
+                                const tool = tools.get(call.name);
+                                if (!tool)
+                                    outcome = failed('unknown_tool', `Unknown tool: ${call.name}`);
+                                else {
+                                    // Validation has no effects. Unexpected execution failures conservatively
+                                    // preserve uncertainty and stop the batch; never retry a write.
+                                    try {
+                                        const invalid = tool.validate(call.arguments);
+                                        if (invalid) {
+                                            outcome = { ok: false, error: invalid };
+                                            if (!validOutcome(outcome))
+                                                outcome = failed('tool_protocol', 'Invalid tool validation result');
+                                        }
+                                        else {
+                                            await emit({ type: 'tool_started', step: steps, toolCallId: call.id, name: call.name });
+                                            if (sinkFailed || signal.aborted)
+                                                outcome = failed('not_started', 'Tool was not started');
+                                            else {
+                                                try {
+                                                    outcome = await tool.execute(call.arguments, { ...scope, step: steps, toolCallId: call.id }, signal);
+                                                    if (!validOutcome(outcome))
+                                                        outcome = failed('tool_protocol', 'Invalid tool result', 'unknown');
+                                                }
+                                                catch (cause) {
+                                                    outcome = failed('tool_exception', cause instanceof Error ? cause.message : String(cause), 'unknown');
+                                                }
+                                            }
+                                        }
+                                    }
+                                    catch {
+                                        outcome = failed('tool_validation', 'Tool validation failed');
+                                    }
+                                }
+                            }
+                            if (!validOutcome(outcome))
+                                outcome = failed('tool_protocol', 'Invalid tool failure result', 'unknown');
+                            if (!outcome.ok && outcome.error.effect === 'unknown') {
+                                uncertain = true;
+                                error ??= { code: outcome.error.code, message: outcome.error.message };
+                            }
+                            await append({ role: 'tool', toolCallId: call.id, name: call.name, outcome }, steps);
+                        }
+                        if (uncertain || sinkFailed) {
+                            reason = 'error';
+                            break;
+                        }
+                        if (signal.aborted) {
+                            reason = 'cancelled';
+                            break;
+                        }
+                    }
+                    finally {
+                        await emit({ type: 'step_ended', step: steps });
+                    }
+                }
+            }
+            catch (cause) {
+                error ??= { code: cause instanceof AgentFault ? cause.code : 'internal_error',
+                    message: cause instanceof Error ? cause.message : String(cause) };
+                reason = 'error';
+            }
+            if (sinkFailed)
+                reason = 'error';
+            // If the sink rejects the terminal itself, replace that one in-memory
+            // terminal with the truthful failure. Never recursively retry the sink.
+            await emit({ type: 'turn_ended', reason, ...(error ? { errorCode: error.code } : {}) });
+            if (sinkFailed) {
+                reason = 'error';
+                const last = events[events.length - 1];
+                events[events.length - 1] = snapshot({ ...last, data: { type: 'turn_ended', reason, errorCode: error.code } });
+            }
+            return snapshot({ ...scope, reason, messages, events, steps, ...(error ? { error } : {}) });
+        },
+    };
+}

package/dist/nativeAgent/contracts.js

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

package/dist/nativeAgent/demo.js

@@ -0,0 +1,29 @@
+import assert from 'node:assert/strict';
+import { mkdtemp, readFile, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+import { createAgent, createMockProvider, createTextTools } from './index.js';
+const root = await mkdtemp(path.join(tmpdir(), 'independent-agent-demo-'));
+try {
+    const text = 'An independent Agent copied this text through tool results.\n';
+    await writeFile(path.join(root, 'input.txt'), text);
+    const samples = [0.1, 0.2, 0.9];
+    const agent = createAgent({
+        tools: createTextTools({ root }),
+        provider: createMockProvider({ toolCallProbability: 0.5, random: () => {
+                const sample = samples.shift();
+                if (sample === undefined)
+                    throw new Error('Demo random sequence exhausted');
+                return sample;
+            } }),
+    });
+    const result = await agent.runTurn({
+        sessionId: 'demo-session', turnId: 'demo-turn', input: 'Copy input.txt to output.txt', maxSteps: 3,
+    });
+    assert.equal(result.reason, 'completed');
+    assert.equal(await readFile(path.join(root, 'output.txt'), 'utf8'), text);
+    console.log(JSON.stringify({ ...result, fileVerified: true }, null, 2));
+}
+finally {
+    await rm(root, { recursive: true, force: true });
+}

package/dist/nativeAgent/index.js

@@ -0,0 +1,3 @@
+export { createAgent } from './agent.js';
+export { createMockProvider } from './mockProvider.js';
+export { createTextTools } from './textTools.js';

package/dist/nativeAgent/mockProvider.js

@@ -0,0 +1,43 @@
+/** A deliberately small read/write mock, not a semantic planner. */
+export function createMockProvider(options) {
+    const { toolCallProbability: p, random = Math.random, readPath = 'input.txt', writePath = 'output.txt' } = options;
+    if (!Number.isFinite(p) || p < 0 || p > 1)
+        throw new Error('toolCallProbability must be in [0, 1]');
+    const latestRead = (request) => {
+        for (const m of [...request.messages].reverse()) {
+            if (m.role === 'tool' && m.name === 'read' && m.outcome.ok) {
+                try {
+                    const data = JSON.parse(m.outcome.content);
+                    if (data && typeof data === 'object' && 'text' in data && typeof data.text === 'string')
+                        return data.text;
+                }
+                catch { /* Other read implementations need not use the text-tools payload. */ }
+            }
+        }
+        return undefined;
+    };
+    return {
+        async complete(request, signal) {
+            signal.throwIfAborted();
+            const u = random();
+            if (!Number.isFinite(u) || u < 0 || u >= 1)
+                throw new Error('random must return a number in [0, 1)');
+            if (u >= p) {
+                const outcomes = request.messages.filter(m => m.role === 'tool');
+                const success = outcomes.filter(m => m.role === 'tool' && m.outcome.ok).length;
+                return { kind: 'final', content: `Observed ${success} successful and ${outcomes.length - success} failed tool results.` };
+            }
+            const content = latestRead(request);
+            const write = request.step % 2 === 0 && content !== undefined;
+            const used = new Set(request.messages.flatMap(m => m.role === 'assistant' ? m.toolCalls.map(c => c.id) : []));
+            let suffix = 1;
+            while (used.has(`mock-${suffix}`))
+                suffix++;
+            const call = { id: `mock-${suffix}`, name: write ? 'write' : 'read',
+                arguments: write ? { path: writePath, content } : { path: readPath } };
+            if (!request.tools.some(t => t.name === call.name))
+                throw new Error(`Mock requires the ${call.name} tool`);
+            return { kind: 'tool_calls', content: '', calls: [call] };
+        },
+    };
+}

package/dist/nativeAgent/textTools.js

@@ -0,0 +1,156 @@
+import { constants, realpathSync, statSync } from 'node:fs';
+import { lstat, open, rename, unlink } from 'node:fs/promises';
+import path from 'node:path';
+import { randomUUID } from 'node:crypto';
+class FileFault extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+    }
+}
+const fail = (code, message) => ({ code, message, effect: 'none' });
+/** Controlled local directories only. Path checks are NOT an adversarial sandbox. */
+export function createTextTools({ root, maxBytes = 64 * 1024 }) {
+    if (!path.isAbsolute(root))
+        throw new Error('An explicit absolute workspace root is required');
+    const workspace = realpathSync(root);
+    if (!statSync(workspace).isDirectory())
+        throw new Error('Workspace must be a directory');
+    if (!Number.isSafeInteger(maxBytes) || maxBytes < 1 || maxBytes > 64 * 1024) {
+        throw new Error('maxBytes must be an integer in [1, 65536]');
+    }
+    const validate = (args, write) => {
+        if (!args || typeof args !== 'object' || Array.isArray(args)
+            || typeof args.path !== 'string' || !args.path.trim()
+            || Object.keys(args).some(k => k !== 'path' && !(write && k === 'content'))
+            || (write && typeof args.content !== 'string'))
+            return fail('invalid_arguments', 'Expected path and, for write, content');
+        if (args.path.includes('\0') || path.isAbsolute(args.path) || args.path.split(/[\\/]/).includes('..')) {
+            return fail('path_out_of_scope', 'Expected a relative path without parent traversal');
+        }
+        if (write && Buffer.byteLength(args.content) > maxBytes)
+            return fail('too_large', 'Text exceeds byte limit');
+        return null;
+    };
+    const check = async (relative, allowMissing) => {
+        const target = path.resolve(workspace, relative);
+        const rel = path.relative(workspace, target);
+        if (!rel || rel === '..' || rel.startsWith(`..${path.sep}`) || path.isAbsolute(rel)) {
+            throw new FileFault('path_out_of_scope', 'Path is outside the file workspace');
+        }
+        const parts = rel.split(path.sep);
+        let current = workspace;
+        for (let i = 0; i < parts.length; i++) {
+            current = path.join(current, parts[i]);
+            const final = i === parts.length - 1;
+            let stat;
+            try {
+                stat = await lstat(current);
+            }
+            catch (error) {
+                if (error.code === 'ENOENT' && final && allowMissing)
+                    return target;
+                throw error;
+            }
+            if (stat.isSymbolicLink())
+                throw new FileFault('symlink_denied', 'Symlinks are not allowed');
+            if (final ? !stat.isFile() || stat.nlink > 1 : !stat.isDirectory()) {
+                throw new FileFault('not_regular_file', 'Expected ordinary directories and a single-link regular file');
+            }
+        }
+        return target;
+    };
+    return ['read', 'write'].map(name => {
+        const writing = name === 'write';
+        return {
+            definition: {
+                name,
+                description: writing ? 'Replace a workspace UTF-8 text file' : 'Read a bounded workspace UTF-8 text file',
+                inputSchema: { type: 'object', properties: { path: { type: 'string' },
+                        ...(writing ? { content: { type: 'string' } } : {}) },
+                    required: writing ? ['path', 'content'] : ['path'], additionalProperties: false },
+            },
+            validate: (args) => validate(args, writing),
+            async execute(args, _scope, signal) {
+                const invalid = validate(args, writing);
+                if (invalid)
+                    return { ok: false, error: invalid };
+                const { path: relative, content } = args;
+                let temporary;
+                let committed = false;
+                let result;
+                try {
+                    signal.throwIfAborted();
+                    const target = await check(relative, writing);
+                    if (!writing) {
+                        const file = await open(target, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+                        try {
+                            const stat = await file.stat();
+                            if (!stat.isFile() || stat.nlink > 1)
+                                throw new FileFault('not_regular_file', 'Expected single-link regular file');
+                            if (stat.size > maxBytes)
+                                throw new FileFault('too_large', 'File exceeds byte limit');
+                            const buffer = Buffer.alloc(maxBytes + 1);
+                            let bytes = 0;
+                            while (bytes < buffer.length) {
+                                signal.throwIfAborted();
+                                const read = await file.read(buffer, bytes, buffer.length - bytes, bytes);
+                                if (!read.bytesRead)
+                                    break;
+                                bytes += read.bytesRead;
+                            }
+                            if (bytes > maxBytes)
+                                throw new FileFault('too_large', 'File exceeds byte limit');
+                            let text;
+                            try {
+                                text = new TextDecoder('utf-8', { fatal: true, ignoreBOM: true }).decode(buffer.subarray(0, bytes));
+                            }
+                            catch {
+                                throw new FileFault('invalid_utf8', 'File is not valid UTF-8');
+                            }
+                            result = { ok: true, content: JSON.stringify({ path: relative, text, bytes }) };
+                        }
+                        finally {
+                            await file.close();
+                        }
+                    }
+                    else {
+                        const candidate = path.join(path.dirname(target), `.agent-${randomUUID()}.tmp`);
+                        const file = await open(candidate, 'wx', 0o600);
+                        temporary = candidate;
+                        try {
+                            await file.writeFile(content, { encoding: 'utf8', signal });
+                        }
+                        finally {
+                            await file.close();
+                        }
+                        await check(relative, true);
+                        signal.throwIfAborted();
+                        await rename(temporary, target);
+                        committed = true;
+                        temporary = undefined;
+                        result = { ok: true, content: JSON.stringify({ path: relative, bytes: Buffer.byteLength(content) }) };
+                    }
+                }
+                catch (error) {
+                    const code = error instanceof FileFault ? error.code
+                        : signal.aborted ? 'cancelled_before_commit'
+                            : error.code === 'ENOENT' ? 'not_found' : 'io_error';
+                    result = { ok: false, error: fail(code, error instanceof FileFault ? error.message : `File operation failed (${code})`) };
+                }
+                if (temporary) {
+                    try {
+                        await unlink(temporary);
+                    }
+                    catch {
+                        return { ok: false, error: { code: 'cleanup_failed',
+                                message: `Owned temporary file remains: ${path.relative(workspace, temporary)}; targetCommitted=${committed}`,
+                                effect: 'unknown' } };
+                    }
+                }
+                return result;
+            },
+        };
+    });
+}