@zq-silk/yui 2.1.0 → 2.3.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

@@ -57,10 +57,10 @@ export function response(value, usedIds) {
     }
     return snapshot(value);
 }
-export function history(value) {
+export function history(value, maxBytes = limits.historyBytes) {
     const pending = new Map();
     const used = new Set();
-    if (!Array.isArray(value) || !json(value) || size(value) > limits.historyBytes) {
+    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) {

package/dist/repository/gitWorkspace.js

@@ -821,7 +821,7 @@ export class NodeGitWorkspace {
         const state = await this.inspectWorktree(input);
         if (state === "dirty")
             return state;
-        const container = await canonicalContainer(input.container, false);
+        const container = await cleanupContainer(input.container);
         const branch = worktreeIdentity(input.taskSegment, input.roleName).branch;
         const path = managedPath(container, input.directory);
         const project = await this.inspect(input.repositoryPath);
@@ -970,13 +970,13 @@ export class NodeGitWorkspace {
         return "removed";
     }
     async inspectWorktree(input) {
-        const container = await canonicalContainer(input.container, false);
+        const container = await cleanupContainer(input.container);
         const path = managedPath(container, input.directory);
         const kind = await pathKind(path);
         const branch = input.expectedBranch ?? worktreeIdentity(input.taskSegment, input.roleName).branch;
         if (kind === undefined) {
             const project = await this.inspect(input.repositoryPath);
-            await inspectMissingWorktreeRegistration(project.root, path, branch);
+            await inspectMissingWorktreeRegistration(project.root, path, branch, input.expectedBranch !== undefined);
             return "missing";
         }
         if (kind === "symlink")
@@ -984,7 +984,7 @@ export class NodeGitWorkspace {
         const canonicalContainerPath = await canonicalContainer(container, false);
         const project = await this.inspect(input.repositoryPath);
         await assertOwnedWorktree(project, canonicalContainerPath, path);
-        await assertExpectedBranch(path, branch);
+        await assertExpectedBranch(path, branch, input.expectedBranch !== undefined);
         const porcelain = await readWorktreeStatus(path);
         return porcelain.length > 0 ? "dirty" : "clean";
     }
@@ -1000,19 +1000,19 @@ export class NodeGitWorkspace {
         });
     }
     async #removeManagedWorktree(input) {
-        const container = await canonicalContainer(input.container, false);
+        const container = await cleanupContainer(input.container);
         const path = managedPath(container, input.identity.directory);
         const kind = await pathKind(path);
         if (kind === "symlink")
             throw new Error("Managed worktree path must not be a symbolic link.");
         const repository = await this.inspect(input.repositoryPath);
         if (kind === undefined) {
-            await removeMissingWorktreeRegistration(repository.root, path, input.identity.branch);
+            await removeMissingWorktreeRegistration(repository.root, path, input.identity.branch, true);
         }
         if (kind === "directory") {
             const canonicalContainerPath = await canonicalContainer(container, false);
             await assertOwnedWorktree(repository, canonicalContainerPath, path);
-            await assertExpectedBranch(path, input.identity.branch);
+            await assertExpectedBranch(path, input.identity.branch, true);
             if (input.discardChanges === true) {
                 await git(["-C", repository.root, "worktree", "remove", "--force", "--", path]);
             }
@@ -1043,19 +1043,22 @@ export class NodeGitWorkspace {
 /** Missing paths do not imply missing Git metadata. Never prune another
  * workspace's registration as a side effect of cleaning this exact owner.
  */
-async function removeMissingWorktreeRegistration(repositoryRoot, path, branch) {
-    if (!await inspectMissingWorktreeRegistration(repositoryRoot, path, branch))
+async function removeMissingWorktreeRegistration(repositoryRoot, path, branch, allowDetached = false) {
+    if (!await inspectMissingWorktreeRegistration(repositoryRoot, path, branch, allowDetached))
         return;
     if (await pathKind(path) !== undefined)
         throw new Error(`Worktree reappeared before metadata cleanup: ${path}.`);
     await git(["-C", repositoryRoot, "worktree", "remove", "--force", "--", path]);
 }
-async function inspectMissingWorktreeRegistration(repositoryRoot, path, branch) {
+async function inspectMissingWorktreeRegistration(repositoryRoot, path, branch, allowDetached = false) {
     const records = (await git(["-C", repositoryRoot, "worktree", "list", "--porcelain", "-z"])).split("\0\0");
     const fields = records.map(record => record.split("\0")).find(record => record.includes(`worktree ${path}`));
     if (fields === undefined)
         return false;
-    if (!fields.includes(`branch refs/heads/${branch}`) || fields.some(field => field.startsWith("locked"))) {
+    const pinnedDetached = allowDetached && fields.includes("detached")
+        && await gitSucceeds(["-C", repositoryRoot, "show-ref", "--verify", "--quiet", `refs/heads/${branch}`])
+        && fields.includes(`HEAD ${await resolveRefCommit(repositoryRoot, `refs/heads/${branch}`)}`);
+    if ((!fields.includes(`branch refs/heads/${branch}`) && !pinnedDetached) || fields.some(field => field.startsWith("locked"))) {
         cleanupFailure("git-registration-mismatch", "Missing worktree has uncertain or locked Git ownership; metadata retained.", { branch, locked: false }, { branch: fields.find(field => field.startsWith("branch "))?.slice(7) ?? null,
             locked: fields.some(field => field.startsWith("locked")) });
     }
@@ -1115,7 +1118,12 @@ async function assertExpectedBranch(path, expected, allowRebase = false) {
                 return;
             throw new Error(`Managed worktree is rebasing an unexpected branch: ${headName}.`);
         }
-        throw new Error("Managed worktree has detached HEAD without its expected rebase.");
+        // A terminal Integration can legitimately retain a detached checkout.
+        // Its exact owned path/common-dir were checked by the caller; require its
+        // retained branch to pin the same commit before allowing clean removal.
+        if (await resolveRefCommit(path, "HEAD") === await resolveRefCommit(path, `refs/heads/${expected}`))
+            return;
+        cleanupFailure("workspace-identity-mismatch", "Detached worktree is not pinned by its owned branch or rebase.", expected, "unproven detached HEAD");
     }
     const branch = await gitLine(["-C", path, "symbolic-ref", "--short", "HEAD"]);
     if (branch !== expected) {
@@ -1237,6 +1245,27 @@ async function canonicalContainer(path, create) {
     // stay rejected by the managed-path lstat checks.
     return canonicalDirectory(lexical, "Worktree container");
 }
+/** A previous removal may have deleted the whole owner container before its
+ * receipt committed. Resolve only surviving ancestors, without creating it.
+ * Git registration inspection remains mandatory even when this path is absent.
+ */
+async function cleanupContainer(path) {
+    const lexical = resolve(path);
+    if (await pathKind(lexical) === "symlink") {
+        cleanupFailure("workspace-identity-mismatch", "Cleanup container must not be a symbolic link.", "owned directory or missing path", "symbolic link");
+    }
+    try {
+        return await canonicalContainer(lexical, false);
+    }
+    catch (error) {
+        if (!isErrno(error, "ENOENT"))
+            throw error;
+        const parent = dirname(lexical);
+        if (parent === lexical)
+            throw error;
+        return join(await cleanupContainer(parent), relative(parent, lexical));
+    }
+}
 async function canonicalDirectory(path, label) {
     const value = requireText(path, label);
     const canonical = await realpath(isAbsolute(value) ? value : resolve(value));