handmux 0.23.0 → 0.25.0

package/dist/src/agent-runtime/resources.js

@@ -0,0 +1,245 @@
+import { constants } from 'node:fs';
+import { open, realpath } from 'node:fs/promises';
+import { basename, isAbsolute, relative, sep } from 'node:path';
+import { randomUUID } from 'node:crypto';
+const DEFAULT_TTL_MS = 60 * 60 * 1000;
+const DEFAULT_MAX_RESOURCE_BYTES = 16 * 1024 * 1024;
+const DEFAULT_MAX_BYTE_STORAGE = 64 * 1024 * 1024;
+const DEFAULT_MAX_RESOURCES = 1024;
+const DEFAULT_MAX_SESSION_RESOURCES = 128;
+const RESOURCE_ID_RE = /^[a-zA-Z0-9_-]{16,256}$/;
+const MEDIA_TYPE_RE = /^[a-zA-Z0-9][a-zA-Z0-9!#$&^_.+-]{0,126}\/[a-zA-Z0-9][a-zA-Z0-9!#$&^_.+-]{0,126}$/;
+export class AgentResourceError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = 'AgentResourceError';
+    }
+}
+function validText(value, max) {
+    return typeof value === 'string' && value.length > 0 && Buffer.byteLength(value) <= max;
+}
+function validSession(value) {
+    return value !== null && typeof value === 'object'
+        && validText(value.agentId, 64)
+        && validText(value.sessionId, 1024);
+}
+function validName(value) {
+    return value === undefined || (validText(value, 1024) && !/[\\/\0-\x1f\x7f]/.test(value));
+}
+function validMediaType(value) {
+    return typeof value === 'string' && MEDIA_TYPE_RE.test(value);
+}
+function within(root, target) {
+    const child = relative(root, target);
+    return child === '' || (!child.startsWith(`..${sep}`) && child !== '..' && !isAbsolute(child));
+}
+function positiveLimit(value, fallback) {
+    return value === undefined ? fallback : Math.max(1, Math.floor(value));
+}
+export class AgentResourceService {
+    #allowedFileRoots;
+    #now;
+    #newResourceId;
+    #ttlMs;
+    #maxResourceBytes;
+    #maxByteStorage;
+    #maxResources;
+    #maxSessionResources;
+    #records = new Map();
+    #byteStorage = 0;
+    constructor({ allowedFileRoots = {}, now = Date.now, newResourceId = randomUUID, ttlMs = DEFAULT_TTL_MS, maxResourceBytes = DEFAULT_MAX_RESOURCE_BYTES, maxByteStorage = DEFAULT_MAX_BYTE_STORAGE, maxResources = DEFAULT_MAX_RESOURCES, maxSessionResources = DEFAULT_MAX_SESSION_RESOURCES, } = {}) {
+        this.#allowedFileRoots = allowedFileRoots;
+        this.#now = now;
+        this.#newResourceId = newResourceId;
+        this.#ttlMs = positiveLimit(ttlMs, DEFAULT_TTL_MS);
+        this.#maxResourceBytes = positiveLimit(maxResourceBytes, DEFAULT_MAX_RESOURCE_BYTES);
+        this.#maxByteStorage = positiveLimit(maxByteStorage, DEFAULT_MAX_BYTE_STORAGE);
+        this.#maxResources = positiveLimit(maxResources, DEFAULT_MAX_RESOURCES);
+        this.#maxSessionResources = positiveLimit(maxSessionResources, DEFAULT_MAX_SESSION_RESOURCES);
+    }
+    forAdapter(agentId) {
+        if (!validText(agentId, 64))
+            throw new TypeError('Agent resource registry requires an adapter id');
+        return Object.freeze({
+            register: (session, source) => (this.#register(agentId, session, source)),
+            revoke: (resourceId) => this.#revoke(agentId, resourceId),
+        });
+    }
+    async read(session, resourceId) {
+        if (!validSession(session) || !RESOURCE_ID_RE.test(resourceId))
+            return null;
+        this.clearExpired();
+        const record = this.#records.get(resourceId);
+        if (!record || record.agentId !== session.agentId || record.sessionId !== session.sessionId)
+            return null;
+        let data;
+        if (record.kind === 'bytes') {
+            data = new Uint8Array(record.data);
+        }
+        else {
+            try {
+                const resolved = await realpath(record.path);
+                if (resolved !== record.path || !record.roots.some((root) => within(root, resolved))) {
+                    this.#delete(record);
+                    throw new AgentResourceError('resource-changed', 'Agent resource path changed after registration');
+                }
+                const handle = await open(resolved, constants.O_RDONLY | constants.O_NOFOLLOW);
+                try {
+                    const stat = await handle.stat();
+                    if (!stat.isFile() || stat.size !== record.size || stat.size > this.#maxResourceBytes
+                        || stat.dev !== record.dev || stat.ino !== record.ino || stat.mtimeMs !== record.mtimeMs) {
+                        this.#delete(record);
+                        throw new AgentResourceError('resource-changed', 'Agent resource changed after registration');
+                    }
+                    data = new Uint8Array(await handle.readFile());
+                }
+                finally {
+                    await handle.close();
+                }
+            }
+            catch (error) {
+                if (error instanceof AgentResourceError)
+                    throw error;
+                this.#delete(record);
+                throw new AgentResourceError('resource-changed', 'Agent resource is no longer readable');
+            }
+        }
+        return {
+            resourceId,
+            session: { agentId: record.agentId, sessionId: record.sessionId },
+            data,
+            size: record.size,
+            ...(record.name === undefined ? {} : { name: record.name }),
+            mediaType: record.mediaType,
+            expiresAt: record.expiresAt,
+        };
+    }
+    clearExpired() {
+        const now = this.#now();
+        let removed = 0;
+        for (const record of this.#records.values()) {
+            if (record.expiresAt > now)
+                continue;
+            this.#delete(record);
+            removed += 1;
+        }
+        return removed;
+    }
+    revokeAdapter(agentId) {
+        for (const record of this.#records.values()) {
+            if (record.agentId === agentId)
+                this.#delete(record);
+        }
+    }
+    async #register(agentId, session, source) {
+        if (!validSession(session) || session.agentId !== agentId || !source || typeof source !== 'object'
+            || !validName(source.name)) {
+            throw new AgentResourceError('invalid-source', 'Invalid Agent resource owner or metadata');
+        }
+        this.clearExpired();
+        const sessionCount = [...this.#records.values()].filter((record) => (record.agentId === agentId && record.sessionId === session.sessionId)).length;
+        if (this.#records.size >= this.#maxResources || sessionCount >= this.#maxSessionResources) {
+            throw new AgentResourceError('capacity-exceeded', 'Agent resource capacity is exhausted');
+        }
+        const common = {
+            resourceId: this.#allocateId(),
+            agentId,
+            sessionId: session.sessionId,
+            expiresAt: this.#now() + this.#ttlMs,
+        };
+        let record;
+        if (source.kind === 'bytes') {
+            if (!(source.data instanceof Uint8Array) || !validMediaType(source.mediaType)) {
+                throw new AgentResourceError('invalid-source', 'Invalid Agent byte resource');
+            }
+            const data = new Uint8Array(source.data);
+            if (data.byteLength > this.#maxResourceBytes) {
+                throw new AgentResourceError('resource-too-large', 'Agent resource exceeds the size limit');
+            }
+            if (this.#byteStorage + data.byteLength > this.#maxByteStorage) {
+                throw new AgentResourceError('capacity-exceeded', 'Agent byte resource storage is exhausted');
+            }
+            record = {
+                ...common,
+                kind: 'bytes',
+                data,
+                size: data.byteLength,
+                ...(source.name === undefined ? {} : { name: source.name }),
+                mediaType: source.mediaType,
+            };
+        }
+        else if (source.kind === 'file') {
+            if (!validText(source.path, 16 * 1024) || !isAbsolute(source.path)
+                || (source.mediaType !== undefined && !validMediaType(source.mediaType))) {
+                throw new AgentResourceError('invalid-source', 'Invalid Agent file resource');
+            }
+            const roots = await Promise.all((this.#allowedFileRoots[agentId] ?? []).map((root) => realpath(root)));
+            let resolved;
+            try {
+                resolved = await realpath(source.path);
+            }
+            catch {
+                throw new AgentResourceError('path-denied', 'Agent resource file is unavailable');
+            }
+            if (!roots.some((root) => within(root, resolved))) {
+                throw new AgentResourceError('path-denied', 'Agent resource file is outside allowed roots');
+            }
+            const handle = await open(resolved, constants.O_RDONLY | constants.O_NOFOLLOW);
+            let stat;
+            try {
+                stat = await handle.stat();
+            }
+            finally {
+                await handle.close();
+            }
+            if (!stat.isFile())
+                throw new AgentResourceError('invalid-source', 'Agent resource must be a regular file');
+            if (stat.size > this.#maxResourceBytes) {
+                throw new AgentResourceError('resource-too-large', 'Agent resource exceeds the size limit');
+            }
+            const basenameValue = basename(resolved).replace(/[\0-\x1f\x7f]/g, '_');
+            record = {
+                ...common,
+                kind: 'file',
+                path: resolved,
+                roots,
+                dev: stat.dev,
+                ino: stat.ino,
+                mtimeMs: stat.mtimeMs,
+                size: stat.size,
+                name: source.name ?? basenameValue,
+                mediaType: source.mediaType ?? 'application/octet-stream',
+            };
+        }
+        else {
+            throw new AgentResourceError('invalid-source', 'Unknown Agent resource source');
+        }
+        this.#records.set(record.resourceId, record);
+        if (record.kind === 'bytes')
+            this.#byteStorage += record.size;
+        return { resourceId: record.resourceId, expiresAt: record.expiresAt };
+    }
+    async #revoke(agentId, resourceId) {
+        if (!RESOURCE_ID_RE.test(resourceId))
+            return;
+        const record = this.#records.get(resourceId);
+        if (record?.agentId === agentId)
+            this.#delete(record);
+    }
+    #allocateId() {
+        for (let attempt = 0; attempt < 8; attempt += 1) {
+            const candidate = this.#newResourceId();
+            if (RESOURCE_ID_RE.test(candidate) && !this.#records.has(candidate))
+                return candidate;
+        }
+        throw new AgentResourceError('capacity-exceeded', 'Unable to allocate an Agent resource id');
+    }
+    #delete(record) {
+        if (!this.#records.delete(record.resourceId))
+            return;
+        if (record.kind === 'bytes')
+            this.#byteStorage -= record.size;
+    }
+}

package/dist/src/agent-runtime/run.js

@@ -0,0 +1,328 @@
+import { randomUUID } from 'node:crypto';
+export class AgentRunError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = 'AgentRunError';
+    }
+}
+function attachmentKey(agentId, attachmentId) {
+    return `${agentId}\0${attachmentId}`;
+}
+function validText(value, max) {
+    return typeof value === 'string' && value.length > 0 && value.length <= max;
+}
+function validateCandidate(candidate) {
+    if (!candidate || !validText(candidate.paneId, 256) || !validText(candidate.attachmentId, 512)) {
+        throw new AgentRunError('invalid-candidate', 'Attachment requires a valid paneId and attachmentId');
+    }
+    if (candidate.sessionId !== undefined && !validText(candidate.sessionId, 1024)) {
+        throw new AgentRunError('invalid-candidate', 'Attachment sessionId must be a non-empty bounded string');
+    }
+    if (candidate.implementationVersion !== undefined
+        && (!Number.isSafeInteger(candidate.implementationVersion)
+            || candidate.implementationVersion <= 0)) {
+        throw new AgentRunError('invalid-candidate', 'Attachment implementationVersion must be a positive integer');
+    }
+    if (!candidate.process || !Number.isSafeInteger(candidate.process.pid) || candidate.process.pid <= 0) {
+        throw new AgentRunError('invalid-candidate', 'Attachment process requires a positive integer pid');
+    }
+    if (candidate.process.startedAt !== undefined
+        && (!Number.isFinite(candidate.process.startedAt) || candidate.process.startedAt < 0)) {
+        throw new AgentRunError('invalid-candidate', 'Attachment process startedAt must be a finite timestamp');
+    }
+    if (candidate.process.tty !== undefined && !validText(candidate.process.tty, 1024)) {
+        throw new AgentRunError('invalid-candidate', 'Attachment process tty must be a non-empty bounded string');
+    }
+}
+function sameProcess(first, second) {
+    return first.pid === second.pid
+        && first.startedAt === second.startedAt
+        && first.tty === second.tty;
+}
+function refFor(agentId, paneId, runId, sessionId, implementationVersion) {
+    return Object.freeze({
+        agentId,
+        paneId,
+        runId,
+        ...(sessionId === undefined ? {} : { sessionId }),
+        ...(implementationVersion === undefined ? {} : { implementationVersion }),
+    });
+}
+// Owns logical run generations only. Bridge connection nonces and transport reconnects never enter here.
+export class AgentRunRuntime {
+    #byRunId = new Map();
+    #knownRunRefs = new Map();
+    #byPane = new Map();
+    #byAttachment = new Map();
+    #records = new WeakMap();
+    #paneQueues = new Map();
+    #disabledAdapters = new Set();
+    #newRunId;
+    #verifyTimeoutMs;
+    #shuttingDown = false;
+    constructor({ newRunId = randomUUID, verifyTimeoutMs = 1000, } = {}) {
+        this.#newRunId = newRunId;
+        this.#verifyTimeoutMs = Math.max(1, verifyTimeoutMs);
+    }
+    resolve(ref) {
+        if (!ref || typeof ref.runId !== 'string')
+            return null;
+        const record = this.#byRunId.get(ref.runId);
+        if (!record || record.abort.signal.aborted)
+            return null;
+        if (record.ref.agentId !== ref.agentId || record.ref.paneId !== ref.paneId)
+            return null;
+        if (ref.sessionId !== undefined && record.ref.sessionId !== ref.sessionId)
+            return null;
+        return record.lease;
+    }
+    status(ref) {
+        if (this.resolve(ref))
+            return 'current';
+        const known = ref && typeof ref.runId === 'string' ? this.#knownRunRefs.get(ref.runId) : undefined;
+        if (!known || known.agentId !== ref.agentId || known.paneId !== ref.paneId)
+            return 'unknown';
+        if (ref.sessionId !== undefined && known.sessionId !== ref.sessionId)
+            return 'unknown';
+        return 'revoked';
+    }
+    isLive(lease) {
+        const record = this.#records.get(lease);
+        return record !== undefined && this.#byRunId.get(record.ref.runId) === record
+            && !record.abort.signal.aborted;
+    }
+    requireLive(lease) {
+        if (!this.isLive(lease))
+            throw new AgentRunError('stale-lease', 'Agent run lease is no longer live');
+        return lease.ref;
+    }
+    currentForPane(paneId) {
+        const record = this.#byPane.get(paneId);
+        return record && !record.abort.signal.aborted ? record.lease : null;
+    }
+    controller(agentId, verify) {
+        if (!validText(agentId, 64) || typeof verify !== 'function') {
+            throw new TypeError('Scoped Agent run controller requires an agentId and attachment verifier');
+        }
+        return Object.freeze({
+            attach: (candidate) => this.#attach(agentId, verify, candidate),
+            associateSession: (lease, sessionId) => (this.#associateSession(agentId, lease, sessionId)),
+            replace: (current, candidate, reason) => this.#replace(agentId, verify, current, candidate, reason),
+            revoke: (lease, reason) => this.#revoke(agentId, lease, reason),
+        });
+    }
+    async revokeAdapter(agentId, reason = 'adapter_stopped') {
+        this.#disabledAdapters.add(agentId);
+        const records = [...this.#byRunId.values()].filter((record) => record.agentId === agentId);
+        await Promise.all(records.map((record) => this.#withPane(record.paneId, async () => {
+            if (this.#byRunId.get(record.ref.runId) === record)
+                this.#remove(record, reason);
+        })));
+    }
+    // Root Runtime uses this after process identity changes. Scoped adapter controllers deliberately do not
+    // receive it, so one adapter cannot evict another adapter's run by naming its pane.
+    async revokePane(paneId, reason) {
+        await this.#withPane(paneId, async () => {
+            const record = this.#byPane.get(paneId);
+            if (record)
+                this.#remove(record, reason);
+        });
+    }
+    async shutdown() {
+        if (this.#shuttingDown)
+            return;
+        this.#shuttingDown = true;
+        const records = [...this.#byRunId.values()];
+        await Promise.all(records.map((record) => this.#withPane(record.paneId, async () => {
+            if (this.#byRunId.get(record.ref.runId) === record)
+                this.#remove(record, 'runtime_shutdown');
+        })));
+    }
+    async #withPane(paneId, operation) {
+        const previous = this.#paneQueues.get(paneId) ?? Promise.resolve();
+        let release;
+        const current = new Promise((resolve) => { release = resolve; });
+        const queued = previous.catch(() => { }).then(() => current);
+        this.#paneQueues.set(paneId, queued);
+        await previous.catch(() => { });
+        try {
+            return await operation();
+        }
+        finally {
+            release();
+            if (this.#paneQueues.get(paneId) === queued)
+                this.#paneQueues.delete(paneId);
+        }
+    }
+    async #verify(verify, candidate) {
+        let accepted = false;
+        let timer;
+        try {
+            accepted = await Promise.race([
+                Promise.resolve(verify(candidate)).then(Boolean, () => false),
+                new Promise((resolve) => {
+                    timer = setTimeout(() => resolve(false), this.#verifyTimeoutMs);
+                }),
+            ]);
+        }
+        catch { /* adapter probe failure is a rejection */ }
+        finally {
+            if (timer)
+                clearTimeout(timer);
+        }
+        if (!accepted) {
+            throw new AgentRunError('attachment-unverified', 'Agent attachment no longer matches the live process');
+        }
+    }
+    #recordFor(agentId, lease) {
+        const record = this.#records.get(lease);
+        if (!record || record.agentId !== agentId) {
+            throw new AgentRunError('foreign-lease', 'Agent run lease does not belong to this scoped controller');
+        }
+        return record;
+    }
+    #create(agentId, candidate) {
+        const abort = new AbortController();
+        const record = {};
+        record.agentId = agentId;
+        record.paneId = candidate.paneId;
+        record.attachmentId = candidate.attachmentId;
+        record.process = Object.freeze({ ...candidate.process });
+        let runId = '';
+        for (let attempt = 0; attempt < 8; attempt += 1) {
+            const proposed = this.#newRunId();
+            if (validText(proposed, 256) && !this.#byRunId.has(proposed)) {
+                runId = proposed;
+                break;
+            }
+        }
+        if (!runId)
+            throw new Error('Unable to allocate a unique Agent runId');
+        record.ref = refFor(agentId, candidate.paneId, runId, candidate.sessionId, candidate.implementationVersion);
+        this.#knownRunRefs.set(runId, record.ref);
+        record.abort = abort;
+        record.lease = Object.freeze({
+            get ref() { return record.ref; },
+            signal: abort.signal,
+        });
+        this.#records.set(record.lease, record);
+        return record;
+    }
+    #install(record) {
+        this.#byRunId.set(record.ref.runId, record);
+        this.#byPane.set(record.paneId, record);
+        this.#byAttachment.set(attachmentKey(record.agentId, record.attachmentId), record);
+    }
+    #remove(record, reason) {
+        if (this.#byRunId.get(record.ref.runId) !== record)
+            return;
+        this.#byRunId.delete(record.ref.runId);
+        if (this.#byPane.get(record.paneId) === record)
+            this.#byPane.delete(record.paneId);
+        const key = attachmentKey(record.agentId, record.attachmentId);
+        if (this.#byAttachment.get(key) === record)
+            this.#byAttachment.delete(key);
+        record.abort.abort(reason);
+    }
+    #replaceInstalled(current, next, reason) {
+        this.#byRunId.delete(current.ref.runId);
+        if (this.#byPane.get(current.paneId) === current)
+            this.#byPane.delete(current.paneId);
+        const currentKey = attachmentKey(current.agentId, current.attachmentId);
+        if (this.#byAttachment.get(currentKey) === current)
+            this.#byAttachment.delete(currentKey);
+        this.#install(next);
+        current.abort.abort(reason);
+        return next.lease;
+    }
+    async #attach(agentId, verify, candidate) {
+        validateCandidate(candidate);
+        return this.#withPane(candidate.paneId, async () => {
+            if (this.#shuttingDown || this.#disabledAdapters.has(agentId)) {
+                throw new AgentRunError('runtime-unavailable', 'Agent runtime or adapter is stopped');
+            }
+            await this.#verify(verify, candidate);
+            const paneOwner = this.#byPane.get(candidate.paneId);
+            if (paneOwner && paneOwner.agentId !== agentId) {
+                throw new AgentRunError('pane-owned-by-another-adapter', `Pane ${candidate.paneId} is owned by another Agent adapter`);
+            }
+            const attached = this.#byAttachment.get(attachmentKey(agentId, candidate.attachmentId));
+            if (attached && attached.paneId !== candidate.paneId) {
+                throw new AgentRunError('attachment-already-attached', 'Agent attachment is already live on another pane');
+            }
+            if (!paneOwner) {
+                const created = this.#create(agentId, candidate);
+                this.#install(created);
+                return created.lease;
+            }
+            if (paneOwner.attachmentId === candidate.attachmentId
+                && sameProcess(paneOwner.process, candidate.process)) {
+                const currentSession = paneOwner.ref.sessionId;
+                if (currentSession !== undefined && candidate.sessionId !== undefined
+                    && currentSession !== candidate.sessionId) {
+                    throw new AgentRunError('session-replacement-required', 'A different session requires replace(), even when process and pane are unchanged');
+                }
+                if (currentSession === undefined && candidate.sessionId !== undefined) {
+                    paneOwner.ref = refFor(agentId, candidate.paneId, paneOwner.ref.runId, candidate.sessionId);
+                    this.#knownRunRefs.set(paneOwner.ref.runId, paneOwner.ref);
+                }
+                return paneOwner.lease;
+            }
+            const created = this.#create(agentId, candidate);
+            return this.#replaceInstalled(paneOwner, created, 'process_exit');
+        });
+    }
+    async #associateSession(agentId, lease, sessionId) {
+        if (!validText(sessionId, 1024)) {
+            throw new AgentRunError('invalid-candidate', 'sessionId must be a non-empty bounded string');
+        }
+        const known = this.#recordFor(agentId, lease);
+        return this.#withPane(known.paneId, async () => {
+            const record = this.#recordFor(agentId, lease);
+            if (this.#byRunId.get(record.ref.runId) !== record || record.abort.signal.aborted) {
+                throw new AgentRunError('stale-lease', 'Cannot associate a session with a stale Agent run');
+            }
+            if (record.ref.sessionId === sessionId)
+                return record.ref;
+            if (record.ref.sessionId !== undefined) {
+                throw new AgentRunError('session-replacement-required', 'An associated session is immutable; use replace() for a new session');
+            }
+            record.ref = refFor(agentId, record.paneId, record.ref.runId, sessionId);
+            this.#knownRunRefs.set(record.ref.runId, record.ref);
+            return record.ref;
+        });
+    }
+    async #replace(agentId, verify, current, candidate, reason) {
+        validateCandidate(candidate);
+        const known = this.#recordFor(agentId, current);
+        if (candidate.paneId !== known.paneId) {
+            throw new AgentRunError('pane-change-requires-attach', 'replace() cannot move an Agent attachment to another pane');
+        }
+        return this.#withPane(known.paneId, async () => {
+            const record = this.#recordFor(agentId, current);
+            if (this.#byRunId.get(record.ref.runId) !== record || record.abort.signal.aborted) {
+                throw new AgentRunError('stale-lease', 'Cannot replace a stale Agent run');
+            }
+            if (this.#shuttingDown || this.#disabledAdapters.has(agentId)) {
+                throw new AgentRunError('runtime-unavailable', 'Agent runtime or adapter is stopped');
+            }
+            await this.#verify(verify, candidate);
+            const attached = this.#byAttachment.get(attachmentKey(agentId, candidate.attachmentId));
+            if (attached && attached !== record) {
+                throw new AgentRunError('attachment-already-attached', 'Replacement attachment is already live');
+            }
+            const created = this.#create(agentId, candidate);
+            return this.#replaceInstalled(record, created, reason);
+        });
+    }
+    async #revoke(agentId, lease, reason) {
+        const known = this.#recordFor(agentId, lease);
+        await this.#withPane(known.paneId, async () => {
+            const record = this.#recordFor(agentId, lease);
+            if (this.#byRunId.get(record.ref.runId) === record)
+                this.#remove(record, reason);
+        });
+    }
+}