maka-agent 0.2.0-dev.4.20260830 → 0.2.0-dev.41.20260918

package/node_modules/@openai/agents-core/dist/sandbox/sandboxes/docker.js

@@ -40,96 +40,90 @@ const DOCKER_CONTAINER_REMOVE_TIMEOUT_MS = 30_000;
 const DOCKER_OWNERSHIP_LABEL = 'openai-agents-sandbox';
 const DOCKER_SESSION_IDENTITY_LABEL = 'openai-agents-sandbox.session-identity';
 const DOCKER_MOUNT_AUTHORITY_FINGERPRINT_LABEL = 'openai-agents-sandbox.mount-authority-fingerprint';
+const RESERVED_DOCKER_LABELS = new Set([
+    DOCKER_OWNERSHIP_LABEL,
+    DOCKER_SESSION_IDENTITY_LABEL,
+    DOCKER_MOUNT_AUTHORITY_FINGERPRINT_LABEL,
+]);
 class DockerSandboxSession extends unixLocal_1.UnixLocalSandboxSession {
     containerClosed = false;
+    closeStarted = false;
     stagedMountEnvironment;
     mountedPathGrants;
     constructor(args) {
-        super(args);
+        super({ ...args, fileIOProtection: 'off' });
         this.mountedPathGrants = args.state.manifest.extraPathGrants.map((grant) => ({ ...grant }));
     }
+    /** File APIs execute inside the container and never use the host Python backend. */
+    get fileIOBackend() {
+        return 'docker';
+    }
     async resolveFilesystemRunAs(runAs) {
         if (runAs && runAs.trim().length > 0) {
-            throw new errors_1.UserError('DockerSandboxClient does not support runAs for filesystem operations.');
+            throw new errors_1.UserError('DockerSandboxClient does not support runAs for host-side materialization. Use container file APIs or execCommand instead.');
         }
         return undefined;
     }
     createEditor(runAs) {
         this.assertSessionUsable();
-        return new DockerSandboxEditor(this, runAs, runAs ? undefined : super.createEditor());
+        return new DockerSandboxEditor(this, runAs);
     }
-    async viewImage(args) {
-        if (!args.runAs && !this.pathRequiresDockerFilesystem(args.path)) {
-            return await super.viewImage(args);
+    assertSessionUsable() {
+        super.assertSessionUsable();
+        if (this.containerClosed || this.closeStarted) {
+            throw new errors_1.UserError('Docker sandbox session is closed.');
         }
-        const bytes = await this.readDockerFileAs(this.resolveContainerFilesystemPath(args.path), args.runAs);
+    }
+    async viewImage(args) {
+        const bytes = await this.readDockerFileAs(args.path, args.runAs, {
+            maxBytes: media_1.MAX_VIEW_IMAGE_BYTES,
+            image: true,
+        });
         return (0, media_1.imageOutputFromBytes)(args.path, bytes);
     }
     async pathExists(path, runAs) {
-        if (!runAs && !this.pathRequiresDockerFilesystem(path)) {
-            return await super.pathExists(path);
-        }
-        const absolutePath = this.resolveContainerFilesystemPath(path);
+        const absolutePath = await this.validateContainerFilesystemPath(path);
         return await (0, pathProbe_1.probeSandboxPathExists)({
             path: absolutePath,
             runCommand: async (command) => await this.runDockerFilesystemCommand(command, { runAs }),
         });
     }
     async directoryExists(path, runAs) {
-        const requiresContainerProbe = Boolean(dockerVolumeMountContainingPath(this.state.manifest, path) ||
-            this.pathRequiresDockerFilesystem(path));
-        if (!runAs && !requiresContainerProbe) {
-            return await super.directoryExists(path);
-        }
-        const absolutePath = this.resolveContainerFilesystemPath(path);
+        const absolutePath = await this.validateContainerFilesystemPath(path);
         return await (0, pathProbe_1.probeSandboxDirectoryExists)({
             path: absolutePath,
             runCommand: async (command) => await this.runDockerFilesystemCommand(command, { runAs }),
         });
     }
     async readFile(args) {
-        if (!args.runAs && !this.pathRequiresDockerFilesystem(args.path)) {
-            return await super.readFile(args);
-        }
-        const bytes = await this.readDockerFileAs(this.resolveContainerFilesystemPath(args.path), args.runAs);
+        const bytes = await this.readDockerFileAs(args.path, args.runAs);
         if (typeof args.maxBytes === 'number' && bytes.byteLength > args.maxBytes) {
             return bytes.subarray(0, args.maxBytes);
         }
         return bytes;
     }
     async listDir(args) {
-        if (!args.runAs && !this.pathRequiresDockerFilesystem(args.path)) {
-            return await super.listDir(args);
-        }
-        const absolutePath = this.resolveContainerFilesystemPath(args.path);
+        const absolutePath = await this.validateContainerFilesystemPath(args.path);
         const output = await this.runReadableDockerFilesystemCommand([
-            `find ${(0, shell_1.shellQuote)(absolutePath)} -mindepth 1 -maxdepth 1 -printf '%y\\t%f\\n'`,
+            `test -d ${(0, shell_1.shellQuote)(absolutePath)} && find -H ${(0, shell_1.shellQuote)(absolutePath)} -mindepth 1 -maxdepth 1 -printf '%y\\0%f\\0'`,
         ].join(' && '), { runAs: args.runAs }, `list directory ${absolutePath}`, absolutePath);
         const resolvedPath = new workspacePaths_1.WorkspacePathPolicy({
             root: this.state.manifest.root,
             extraPathGrants: this.state.manifest.extraPathGrants,
         }).resolve(args.path);
         const logicalPath = resolvedPath.workspaceRelativePath ?? resolvedPath.path;
-        return output
-            .split(/\r?\n/u)
-            .filter((line) => line.trim().length > 0)
-            .map((line) => {
-            const separator = line.indexOf('\t');
-            const kind = separator >= 0 ? line.slice(0, separator) : '';
-            const name = separator >= 0 ? line.slice(separator + 1) : line;
-            return {
+        const fields = output.split('\0');
+        const entries = [];
+        for (let index = 0; index + 1 < fields.length; index += 2) {
+            const kind = fields[index];
+            const name = fields[index + 1];
+            entries.push({
                 name,
                 path: logicalPath ? `${logicalPath}/${name}` : name,
                 type: kind === 'd' ? 'dir' : kind === 'f' ? 'file' : 'other',
-            };
-        });
-    }
-    pathRequiresDockerFilesystem(path) {
-        return Boolean(dockerInContainerMountContainingPath(this.state.manifest, path) ||
-            dockerSplitPathGrantContainingPath(this.state.manifest, path));
-    }
-    pathUsesSplitGrant(path) {
-        return Boolean(dockerSplitPathGrantContainingPath(this.state.manifest, path));
+            });
+        }
+        return entries;
     }
     async materializeEntry(args) {
         const entry = structuredClone(args.entry);
@@ -333,11 +327,11 @@ class DockerSandboxSession extends unixLocal_1.UnixLocalSandboxSession {
     resolveSandboxPath(path, options = {}) {
         const mountPath = dockerVolumeMountContainingPath(this.state.manifest, path);
         if (mountPath) {
-            throw new errors_1.UserError(`DockerSandboxClient filesystem operations cannot access Docker volume mount path "${path ?? mountPath}". Use execCommand for container-visible paths under "${mountPath}".`);
+            throw new errors_1.UserError(`DockerSandboxClient cannot map Docker volume mount path "${path ?? mountPath}" to a host path. Use the session file APIs or execCommand for container-visible paths under "${mountPath}".`);
         }
         const inContainerMountPath = dockerInContainerMountContainingPath(this.state.manifest, path);
         if (inContainerMountPath) {
-            throw new errors_1.UserError(`DockerSandboxClient host filesystem operations cannot access in-container mount path "${path ?? inContainerMountPath}". Use execCommand for container-visible paths under "${inContainerMountPath}".`);
+            throw new errors_1.UserError(`DockerSandboxClient cannot map in-container mount path "${path ?? inContainerMountPath}" to a host path. Use the session file APIs or execCommand for container-visible paths under "${inContainerMountPath}".`);
         }
         return super.resolveSandboxPath(path, options);
     }
@@ -347,14 +341,72 @@ class DockerSandboxSession extends unixLocal_1.UnixLocalSandboxSession {
             root: this.state.manifest.root,
             extraPathGrants: this.state.manifest.extraPathGrants,
         }).resolve(path, options);
+        const selectedGrant = resolved.grant;
+        if (selectedGrant &&
+            !this.mountedPathGrants.some((grant) => grant.path === selectedGrant.path &&
+                grant.readOnly === selectedGrant.readOnly &&
+                (0, hostPath_1.sandboxPathGrantHostPath)(grant) ===
+                    (0, hostPath_1.sandboxPathGrantHostPath)(selectedGrant))) {
+            throw new errors_1.UserError(`Docker path grant "${selectedGrant.path}" is not mounted. Resume or recreate the session before using it.`);
+        }
+        if (options.forWrite) {
+            const mount = this.state.manifest
+                .mountTargets()
+                .map(({ logicalPath, entry }) => ({
+                path: resolveDockerMountPath(this.state.manifest.root, logicalPath, entry),
+                entry,
+            }))
+                .sort((left, right) => right.path.length - left.path.length)
+                .find((mount) => pathWithinDockerMount(resolved.path, mount.path));
+            if (mount && (mount.entry.readOnly ?? true)) {
+                throw new errors_1.UserError(`Docker path "${resolved.path}" is inside a read-only mount.`);
+            }
+        }
         return resolved.path;
     }
-    async readDockerFileAs(path, runAs) {
-        const output = await this.runReadableDockerFilesystemCommand(`base64 -- ${(0, shell_1.shellQuote)(path)}`, { runAs }, `read file ${path}`, path);
-        return Buffer.from(output.replace(/\s+/gu, ''), 'base64');
+    async validateContainerFilesystemPath(path, options = {}) {
+        const absolutePath = this.resolveContainerFilesystemPath(path, options);
+        const output = await resolveTrustedDockerPath(this, absolutePath, 'resolve a filesystem path');
+        const resolved = output.endsWith('\n') ? output.slice(0, -1) : output;
+        if (!resolved.startsWith('/')) {
+            throw new errors_1.UserError('Docker filesystem path resolution returned an invalid path.');
+        }
+        if (this.resolveContainerFilesystemPath(resolved, options) !== resolved) {
+            throw new errors_1.UserError('Docker filesystem path normalization changed the resolved target.');
+        }
+        // Keep leaf symlink identity for unlink and moves after checking its target.
+        return this.resolveContainerFilesystemPath(path, options);
+    }
+    async readDockerFileAs(path, runAs, limits) {
+        path = await this.validateContainerFilesystemPath(path);
+        const imageLimit = limits?.image ? limits.maxBytes : undefined;
+        const fileGuard = `if [ -e ${(0, shell_1.shellQuote)(path)} ] && [ ! -f ${(0, shell_1.shellQuote)(path)} ]; then exit 67; fi; `;
+        const imageGuard = imageLimit === undefined
+            ? ''
+            : `size=$(wc -c < ${(0, shell_1.shellQuote)(path)}) || exit 1; if [ "$size" -gt ${imageLimit} ]; then exit 68; fi; `;
+        const limit = limits?.maxBytes;
+        // GNU base64 adds one newline per 76 encoded bytes, including the last line.
+        const encodedBytes = limit === undefined ? undefined : Math.ceil(limit / 3) * 4;
+        const output = await this.runReadableDockerFilesystemCommand(`${fileGuard}${imageGuard}base64 -- ${(0, shell_1.shellQuote)(path)}`, {
+            runAs,
+            maxOutputBytes: encodedBytes === undefined
+                ? undefined
+                : encodedBytes + Math.ceil(encodedBytes / 76),
+        }, `read file ${path}`, path, imageLimit !== undefined);
+        const bytes = Buffer.from(output.replace(/\s+/gu, ''), 'base64');
+        if (limit !== undefined && bytes.byteLength > limit) {
+            throw new errors_1.UserError(`Docker file exceeds the ${limit} byte read limit: ${path}`);
+        }
+        return bytes;
     }
-    async runReadableDockerFilesystemCommand(command, options, action, path) {
+    async runReadableDockerFilesystemCommand(command, options, action, path, image = false) {
         const result = await this.runDockerFilesystemCommand(command, options);
+        if (result.status === 67)
+            throw new errors_1.UserError(`${image ? 'Image' : 'File'} path is not a file: ${path}`);
+        if (image) {
+            if (result.status === 68)
+                throw new errors_1.UserError(`Image file exceeds the 10 MB limit: ${path}`);
+        }
         if (result.status !== 0) {
             if (result.status === 1 &&
                 !result.timedOut &&
@@ -363,8 +415,11 @@ class DockerSandboxSession extends unixLocal_1.UnixLocalSandboxSession {
                 const exists = await (0, pathProbe_1.probeSandboxPathExists)({
                     path,
                     runCommand: async (command) => await this.runDockerFilesystemCommand(command, options),
+                    createError: () => new errors_1.UserError(`DockerSandboxClient failed to ${action}: ${(0, runProcess_1.formatSandboxProcessError)(result)}`),
                 });
                 if (!exists) {
+                    if (image)
+                        throw new errors_1.UserError(`Image file not found: ${path}`);
                     throw new errors_2.SandboxWorkspaceReadNotFoundError(`DockerSandboxClient path does not exist: ${path}`, { path });
                 }
             }
@@ -372,14 +427,23 @@ class DockerSandboxSession extends unixLocal_1.UnixLocalSandboxSession {
         }
         return result.stdout;
     }
-    async writeDockerTextFileAs(path, content, runAs) {
+    async writeDockerTextFileAs(path, content, runAs, exclusive = false, moveSource) {
+        path = await this.validateContainerFilesystemPath(path, { forWrite: true });
         const parent = dockerPosixDirname(path);
+        const guard = exclusive
+            ? `if [ -e ${(0, shell_1.shellQuote)(path)} ] || [ -L ${(0, shell_1.shellQuote)(path)} ]; then echo 'File already exists.' >&2; exit 1; fi; set -C; `
+            : `if [ -e ${(0, shell_1.shellQuote)(path)} ] && [ ! -f ${(0, shell_1.shellQuote)(path)} ]; then echo 'Destination is not a regular file.' >&2; exit 1; fi; `;
+        const moveGuard = moveSource
+            ? `if [ ${(0, shell_1.shellQuote)(moveSource)} -ef ${(0, shell_1.shellQuote)(path)} ]; then echo 'Cannot move a file onto itself.' >&2; exit 1; fi; `
+            : '';
+        const write = `${moveGuard}${guard}cat > ${(0, shell_1.shellQuote)(path)}`;
         await this.runCheckedDockerFilesystemCommand(parent === '/' || parent === '.'
-            ? `cat > ${(0, shell_1.shellQuote)(path)}`
-            : `mkdir -p -- ${(0, shell_1.shellQuote)(parent)} && cat > ${(0, shell_1.shellQuote)(path)}`, { runAs, input: content }, `write file ${path}`);
+            ? write
+            : `mkdir -p -- ${(0, shell_1.shellQuote)(parent)} && (${write})`, { runAs, input: content }, `write file ${path}`);
     }
     async deleteDockerPathAs(path, runAs) {
-        await this.runCheckedDockerFilesystemCommand(`rm -f -- ${(0, shell_1.shellQuote)(path)}`, { runAs }, `delete path ${path}`);
+        path = await this.validateContainerFilesystemPath(path, { forWrite: true });
+        await this.runCheckedDockerFilesystemCommand(`rm -- ${(0, shell_1.shellQuote)(path)}`, { runAs }, `delete path ${path}`);
     }
     async mkdirDockerPathAs(path, runAs) {
         await this.runCheckedDockerFilesystemCommand(`mkdir -p -- ${(0, shell_1.shellQuote)(path)}`, { runAs }, `create directory ${path}`);
@@ -390,7 +454,9 @@ class DockerSandboxSession extends unixLocal_1.UnixLocalSandboxSession {
             result = await this.runDockerFilesystemCommand(command, {
                 runAs: 'root',
                 input: options.input,
-                environment: options.environment ?? this.stagedMountEnvironment,
+                mountEnvironment: options.environment ??
+                    this.stagedMountEnvironment ??
+                    this.state.environment,
             });
         }
         catch {
@@ -417,17 +483,32 @@ class DockerSandboxSession extends unixLocal_1.UnixLocalSandboxSession {
     async runDockerFilesystemCommand(command, options = {}) {
         this.assertSessionUsable();
         const dockerArgs = ['exec', '-i', '-w', '/'];
-        for (const [key, value] of Object.entries(options.environment ?? this.state.environment)) {
-            dockerArgs.push('-e', `${key}=${value}`);
+        if (options.mountEnvironment) {
+            for (const [key, value] of Object.entries(options.mountEnvironment)) {
+                dockerArgs.push('-e', `${key}=${value}`);
+            }
+        }
+        else {
+            dockerArgs.push(...dockerFileEnvironmentArgs(this.state.environment));
         }
         const runAs = options.runAs ?? this.state.defaultUser;
         if (runAs) {
             dockerArgs.push('-u', runAs);
         }
-        dockerArgs.push(this.state.containerId, '/bin/sh', '-lc', command);
-        return await runDockerProcess(dockerArgs, options.input);
+        dockerArgs.push(this.state.containerId);
+        if (options.mountEnvironment) {
+            dockerArgs.push('/bin/sh', '-lc', command);
+        }
+        else {
+            dockerArgs.push('/usr/bin/env', '-i', 'PATH=/usr/bin:/bin', 'LC_ALL=C', '/bin/sh', '-c', command);
+        }
+        return await runDockerProcess(dockerArgs, options.input, options.maxOutputBytes);
     }
     async close() {
+        this.closeStarted = true;
+        await this.closeContainerResources();
+    }
+    async closeContainerResources() {
         let cleanupError;
         if (!this.containerClosed) {
             try {
@@ -473,17 +554,11 @@ exports.DockerSandboxSession = DockerSandboxSession;
 class DockerSandboxEditor {
     session;
     runAs;
-    hostEditor;
-    constructor(session, runAs, hostEditor) {
+    constructor(session, runAs) {
         this.session = session;
         this.runAs = runAs;
-        this.hostEditor = hostEditor;
     }
     canAccessPathForEdit(path) {
-        if (!this.shouldUseDockerFilesystem(path)) {
-            const canAccessPathForEdit = this.hostEditor?.canAccessPathForEdit;
-            return canAccessPathForEdit?.call(this.hostEditor, path) ?? false;
-        }
         try {
             this.session.resolveContainerFilesystemPath(path, { forWrite: true });
             return true;
@@ -492,29 +567,16 @@ class DockerSandboxEditor {
             return false;
         }
     }
-    async createFile(operation, context) {
-        if (!this.shouldUseDockerFilesystem(operation.path)) {
-            return (await this.hostEditor.createFile(operation, context)) ?? {};
-        }
-        const path = this.session.resolveContainerFilesystemPath(operation.path, {
+    async createFile(operation) {
+        this.session.resolveContainerFilesystemPath(operation.path, {
             forWrite: true,
         });
-        if (await this.session.pathExists(operation.path, this.runAs)) {
-            throw new errors_1.UserError(`Cannot create file because it already exists: ${path}`);
-        }
         const content = (0, applyDiff_1.applyDiff)('', operation.diff, 'create');
-        const parent = dockerPosixDirname(path);
-        if (parent !== '.' && parent !== '/') {
-            await this.session.mkdirDockerPathAs(parent, this.runAs);
-        }
-        await this.session.writeDockerTextFileAs(path, content, this.runAs);
+        await this.session.writeDockerTextFileAs(operation.path, content, this.runAs, true);
         return {};
     }
-    async updateFile(operation, context) {
-        if (!this.shouldUseDockerFilesystem(operation.path, operation.moveTo)) {
-            return (await this.hostEditor.updateFile(operation, context)) ?? {};
-        }
-        const path = this.session.resolveContainerFilesystemPath(operation.path, {
+    async updateFile(operation) {
+        const path = await this.session.validateContainerFilesystemPath(operation.path, {
             forWrite: true,
         });
         const destination = operation.moveTo
@@ -522,39 +584,44 @@ class DockerSandboxEditor {
                 forWrite: true,
             })
             : path;
-        const current = new TextDecoder().decode(await this.session.readDockerFileAs(path, this.runAs));
+        const current = new TextDecoder().decode(await this.session.readDockerFileAs(path, this.runAs, {
+            maxBytes: 10 * 1024 * 1024,
+        }));
         const next = (0, applyDiff_1.applyDiff)(current, operation.diff);
-        const parent = dockerPosixDirname(destination);
-        if (parent !== '.' && parent !== '/') {
-            await this.session.mkdirDockerPathAs(parent, this.runAs);
-        }
-        await this.session.writeDockerTextFileAs(destination, next, this.runAs);
+        await this.session.writeDockerTextFileAs(destination, next, this.runAs, false, destination !== path ? path : undefined);
         if (operation.moveTo && destination !== path) {
             await this.session.deleteDockerPathAs(path, this.runAs);
         }
         return {};
     }
-    async deleteFile(operation, context) {
-        if (!this.shouldUseDockerFilesystem(operation.path)) {
-            return (await this.hostEditor.deleteFile(operation, context)) ?? {};
-        }
-        await this.session.deleteDockerPathAs(this.session.resolveContainerFilesystemPath(operation.path, {
-            forWrite: true,
-        }), this.runAs);
+    async deleteFile(operation) {
+        await this.session.deleteDockerPathAs(operation.path, this.runAs);
         return {};
     }
-    shouldUseDockerFilesystem(...paths) {
-        return (!this.hostEditor ||
-            paths.some((path) => this.session.pathUsesSplitGrant(path)));
-    }
 }
+/**
+ * Docker file APIs run inside a running container using its default user or runAs.
+ * They require /bin/sh and standard GNU filesystem utilities, including realpath.
+ * Editor updates reject source files larger than 10 MB before applying changes.
+ * File helpers use an isolated environment; application and mount commands retain
+ * their configured environment.
+ * File operations do not use host Python or fall back to host paths. Path grants
+ * added after creation become container-visible only after resume or recreation.
+ */
 class DockerSandboxClient {
     backendId = 'docker';
     supportsDefaultOptions = true;
     options;
     failedCreateCleanupTokens = new Map();
     constructor(options = {}) {
-        this.options = options;
+        this.options = {
+            ...options,
+            ...(options.labels === undefined
+                ? {}
+                : {
+                    labels: normalizeDockerLabels(options.labels, 'DockerSandboxClient labels'),
+                }),
+        };
     }
     async create(args, manifestOptions) {
         const createArgs = (0, client_1.normalizeSandboxClientCreateArgs)(args, manifestOptions);
@@ -574,6 +641,7 @@ class DockerSandboxClient {
                 : {}),
         };
         const { configuredExposedPorts, networkMode } = resolveDockerNetworkConfiguration(this.options, createArgs.options);
+        const labels = resolveDockerLabels(this.options, createArgs.options);
         const environment = await manifest.resolveEnvironment();
         (0, mountSecurity_1.validateMountEnvironmentCredentialBoundaries)(manifest, environment);
         await ensureDockerAvailable();
@@ -602,6 +670,7 @@ class DockerSandboxClient {
             defaultUser,
             exposedPorts: configuredExposedPorts,
             networkMode,
+            labels,
         });
         const session = new DockerSandboxSession({
             state: {
@@ -618,6 +687,7 @@ class DockerSandboxClient {
                 defaultUser,
                 configuredExposedPorts,
                 networkMode,
+                labels: { ...labels },
                 dockerVolumeNames: container.volumeNames,
             },
             archiveLimits: resolvedOptions.archiveLimits,
@@ -669,6 +739,11 @@ class DockerSandboxClient {
                     exposedPorts: undefined,
                 };
             }
+            const labels = resolveDockerLabels(this.options, options.clientOptions, state);
+            resumeState = {
+                ...resumeState,
+                labels,
+            };
         }
         (0, manifestPersistence_1.assertMountCredentialsRebound)(resumeState);
         (0, manifestPersistence_1.assertHostPathGrantsRebound)(resumeState);
@@ -693,6 +768,8 @@ class DockerSandboxClient {
         resolveDockerNetworkConfiguration(this.options, options.clientOptions, input.source === 'explicit'
             ? { configuredExposedPorts, networkMode }
             : undefined);
+        const persistedLabels = normalizeDockerLabels(input.state.labels, 'Docker sandbox session state labels');
+        resolveDockerLabels(this.options, options.clientOptions, input.source === 'explicit' ? { labels: persistedLabels } : undefined);
     }
     async canReusePreservedOwnedSession(state, options = {}) {
         validateDockerNetworkConfiguration(state.networkMode, state.configuredExposedPorts);
@@ -709,6 +786,12 @@ class DockerSandboxClient {
             ...this.options,
             ...options.clientOptions,
         };
+        try {
+            resolveDockerLabels(this.options, options.clientOptions, state);
+        }
+        catch {
+            return false;
+        }
         const { configuredExposedPorts, networkMode } = resolveDockerNetworkConfiguration(this.options, options.clientOptions);
         if (state.image !== (resolvedOptions.image ?? DEFAULT_DOCKER_IMAGE) ||
             !dockerExposedPortSetsEqual(state.configuredExposedPorts ?? [], configuredExposedPorts) ||
@@ -738,6 +821,7 @@ class DockerSandboxClient {
     }
     async serializeSessionState(state, options = {}) {
         (0, mountSecurity_1.assertSandboxSessionStateUsable)(state);
+        const labels = normalizeDockerLabels(state.labels, 'Docker sandbox session state labels');
         (0, mountSecurity_1.validateMountEnvironmentCredentialBoundaries)(state.manifest, state.environment);
         const stateGeneration = (0, mountSecurity_1.captureSandboxStateGeneration)(state);
         const snapshotSpec = state.snapshotSpec ?? this.options.snapshot ?? null;
@@ -770,6 +854,7 @@ class DockerSandboxClient {
             ...(state.networkMode !== undefined
                 ? { networkMode: state.networkMode }
                 : {}),
+            labels,
             dockerVolumeNames: state.dockerVolumeNames ?? [],
             exposedPorts: state.exposedPorts ?? null,
         };
@@ -787,6 +872,7 @@ class DockerSandboxClient {
             containerId: (0, typeGuards_1.readString)(state, 'containerId'),
             defaultUser: (0, typeGuards_1.readOptionalString)(state, 'defaultUser') ?? getHostDockerUser(),
             networkMode,
+            labels: normalizeDockerLabels(state.labels, 'Serialized Docker sandbox session state labels'),
             dockerVolumeNames: (0, typeGuards_1.readStringArray)(state.dockerVolumeNames),
         };
     }
@@ -799,6 +885,7 @@ class DockerSandboxClient {
                 ...trustedConfig?.clientOptions,
             };
             const { configuredExposedPorts, networkMode } = resolveDockerNetworkConfiguration(this.options, trustedConfig?.clientOptions);
+            const labels = resolveDockerLabels(this.options, trustedConfig?.clientOptions);
             const trustedState = {
                 ...state,
                 sessionIdentity: undefined,
@@ -811,6 +898,7 @@ class DockerSandboxClient {
                 defaultUser: getHostDockerUser(),
                 configuredExposedPorts,
                 networkMode,
+                labels,
                 dockerVolumeNames: [],
                 exposedPorts: undefined,
             };
@@ -828,6 +916,10 @@ class DockerSandboxClient {
                 if (inspection.reusable) {
                     return state;
                 }
+                if (inspection.ownershipVerified &&
+                    inspection.requiredLabelsMatch === false) {
+                    throw new errors_1.UserError('Existing Docker sandbox labels do not match required labels. Start a fresh sandbox session instead.');
+                }
                 if (!inspection.ownershipVerified) {
                     throw new errors_1.UserError('Docker sandbox container identity could not be verified. Refusing to resume or replace the running container.');
                 }
@@ -844,9 +936,14 @@ class DockerSandboxClient {
                 return await this.restartContainer(restoredState, restoredState.workspaceRootPath, archiveLimits);
             }
         }
-        if (containerRunning &&
-            !dockerContainerIdentityMatches(state.sessionIdentity, await inspectDockerContainerLabels(state.containerId))) {
-            throw new errors_1.UserError('Docker sandbox container identity could not be verified. Refusing to resume or replace the running container.');
+        if (containerRunning) {
+            const labels = await inspectDockerContainerLabels(state.containerId);
+            if (!dockerContainerIdentityMatches(state.sessionIdentity, labels)) {
+                throw new errors_1.UserError('Docker sandbox container identity could not be verified. Refusing to resume or replace the running container.');
+            }
+            if (!dockerRequiredLabelsMatch(state.labels, labels)) {
+                throw new errors_1.UserError('Existing Docker sandbox labels do not match required labels. Start a fresh sandbox session instead.');
+            }
         }
         if (!(await (0, localSnapshots_1.localSnapshotIsRestorable)(state))) {
             throw new errors_1.UserError('Docker sandbox resources are unavailable and no local snapshot could be restored.');
@@ -894,6 +991,7 @@ class DockerSandboxClient {
             defaultUser: state.defaultUser,
             exposedPorts: state.configuredExposedPorts,
             networkMode: state.networkMode,
+            labels: normalizeDockerLabels(state.labels, 'Docker sandbox session state labels'),
         });
         const nextState = {
             ...state,
@@ -901,6 +999,7 @@ class DockerSandboxClient {
             materializedEntriesFingerprint: dockerMaterializedEntriesFingerprint(state.manifest),
             workspaceRootPath,
             containerId: container.containerId,
+            labels: normalizeDockerLabels(state.labels, 'Docker sandbox session state labels'),
             dockerVolumeNames: container.volumeNames,
             exposedPorts: undefined,
         };
@@ -988,6 +1087,13 @@ async function inspectRunningDockerContainerForReuse(state) {
     if (!dockerContainerIdentityMatches(sessionIdentity, labels)) {
         return { ownershipVerified: false, reusable: false };
     }
+    if (!dockerRequiredLabelsMatch(state.labels, labels)) {
+        return {
+            ownershipVerified: true,
+            reusable: false,
+            requiredLabelsMatch: false,
+        };
+    }
     const workspaceMountBeforeInspect = await resolveDockerWorkspaceMount(state.workspaceRootPath, state.manifest.root);
     const pathGrantMountsBeforeInspect = await resolveDockerPathGrantMounts(state.manifest);
     const manifestBindMountsBeforeInspect = await resolveDockerManifestBindMounts(state.manifest);
@@ -1032,6 +1138,13 @@ async function inspectLegacyDockerContainerForReuse(state, labels) {
         labels[DOCKER_MOUNT_AUTHORITY_FINGERPRINT_LABEL] !== undefined) {
         return { ownershipVerified: false, reusable: false };
     }
+    if (!dockerRequiredLabelsMatch(state.labels, labels)) {
+        return {
+            ownershipVerified: true,
+            reusable: false,
+            requiredLabelsMatch: false,
+        };
+    }
     const workspaceMountBeforeInspect = await resolveDockerWorkspaceMount(state.workspaceRootPath, state.manifest.root);
     const manifestBindMountsBeforeInspect = await resolveDockerManifestBindMounts(state.manifest);
     const actualBindMounts = await inspectDockerBindMounts(state.containerId);
@@ -1285,6 +1398,46 @@ function dockerExposedPortSetsEqual(left, right) {
     return (JSON.stringify([...left].sort((a, b) => a - b)) ===
         JSON.stringify([...right].sort((a, b) => a - b)));
 }
+function normalizeDockerLabels(value, source) {
+    if (value === undefined) {
+        return {};
+    }
+    if (!(0, typeGuards_1.isStringRecord)(value)) {
+        throw new errors_1.UserError(`${source} must be a record of string values.`);
+    }
+    const labels = { ...value };
+    for (const key of Object.keys(labels)) {
+        if (RESERVED_DOCKER_LABELS.has(key)) {
+            throw new errors_1.UserError(`${source} cannot override reserved SDK label "${key}".`);
+        }
+    }
+    return labels;
+}
+function dockerLabelRecordsEqual(left, right) {
+    const leftKeys = Object.keys(left);
+    return (leftKeys.length === Object.keys(right).length &&
+        leftKeys.every((key) => right[key] === left[key]));
+}
+function resolveDockerLabels(clientOptions, perRunOptions, explicitStateFallback) {
+    const trustedLabels = perRunOptions?.labels !== undefined
+        ? normalizeDockerLabels(perRunOptions.labels, 'DockerSandboxClient per-run labels')
+        : clientOptions.labels !== undefined
+            ? normalizeDockerLabels(clientOptions.labels, 'DockerSandboxClient labels')
+            : undefined;
+    const persistedLabels = explicitStateFallback
+        ? normalizeDockerLabels(explicitStateFallback.labels, 'Docker sandbox session state labels')
+        : undefined;
+    if (trustedLabels !== undefined &&
+        persistedLabels !== undefined &&
+        !dockerLabelRecordsEqual(trustedLabels, persistedLabels)) {
+        throw new errors_1.UserError('DockerSandboxClient labels cannot be changed when resuming explicit session state. Start a fresh sandbox session instead.');
+    }
+    return { ...(trustedLabels ?? persistedLabels ?? {}) };
+}
+function dockerRequiredLabelsMatch(requiredLabels, actualLabels) {
+    const normalizedRequiredLabels = normalizeDockerLabels(requiredLabels, 'Docker sandbox session state labels');
+    return Object.entries(normalizedRequiredLabels).every(([key, value]) => actualLabels?.[key] === value);
+}
 function validateDockerNetworkConfiguration(networkMode, exposedPorts) {
     if (networkMode !== undefined && networkMode !== 'none') {
         throw new errors_1.UserError('DockerSandboxClient networkMode must be "none" when provided.');
@@ -1433,17 +1586,37 @@ async function inspectContainerRunning(containerId) {
     }
     throw new errors_1.UserError(`Failed to inspect Docker sandbox container: unexpected running state "${running}".`);
 }
-async function runDockerProcess(args, input) {
+async function runDockerProcess(args, input, maxOutputBytes) {
     const child = (0, node_child_process_1.spawn)('docker', args, {
         stdio: 'pipe',
     });
     const stdoutChunks = [];
     const stderrChunks = [];
+    let stdinError;
+    let outputBytes = 0;
+    let outputLimitError;
+    const captureOutput = (chunks, chunk) => {
+        if (outputLimitError)
+            return;
+        outputBytes += chunk.length;
+        if (maxOutputBytes !== undefined && outputBytes > maxOutputBytes) {
+            outputLimitError = new Error('Docker filesystem command exceeded its output limit.');
+            stdoutChunks.length = 0;
+            stderrChunks.length = 0;
+            child.kill('SIGKILL');
+            return;
+        }
+        chunks.push(chunk);
+    };
+    // A rejected command can close its input before buffered editor content drains.
+    child.stdin.on('error', (error) => {
+        stdinError = error;
+    });
     child.stdout.on('data', (chunk) => {
-        stdoutChunks.push(chunk);
+        captureOutput(stdoutChunks, chunk);
     });
     child.stderr.on('data', (chunk) => {
-        stderrChunks.push(chunk);
+        captureOutput(stderrChunks, chunk);
     });
     const closed = new Promise((resolve) => {
         child.on('close', (code) => {
@@ -1451,15 +1624,30 @@ async function runDockerProcess(args, input) {
         });
         child.on('error', (error) => {
             stderrChunks.push(Buffer.from(error.message));
-            resolve(1);
         });
     });
     if (input !== undefined) {
         child.stdin.write(input);
     }
     child.stdin.end();
+    let status = await closed;
+    if (outputLimitError) {
+        return {
+            status: 1,
+            signal: null,
+            timedOut: false,
+            stdout: '',
+            stderr: outputLimitError.message,
+            error: outputLimitError,
+        };
+    }
+    // Preserve command diagnostics, but never report success for failed input.
+    if (status === 0 && stdinError) {
+        status = 1;
+        stderrChunks.push(Buffer.from(stdinError.message));
+    }
     return {
-        status: await closed,
+        status,
         signal: null,
         timedOut: false,
         stdout: Buffer.concat(stdoutChunks).toString('utf8'),
@@ -1482,6 +1670,7 @@ function isMissingDockerContainerError(result) {
     return (message.includes('no such container') || message.includes('no such object'));
 }
 async function startDockerContainer(args) {
+    const labels = normalizeDockerLabels(args.labels, 'Docker sandbox container labels');
     validateDockerNetworkConfiguration(args.networkMode, args.exposedPorts);
     const envArgs = Object.entries(args.environment).flatMap(([key, value]) => [
         '-e',
@@ -1493,6 +1682,10 @@ async function startDockerContainer(args) {
         `127.0.0.1::${port}`,
     ]);
     const networkArgs = args.networkMode ? ['--network', args.networkMode] : [];
+    const labelArgs = Object.entries(labels).flatMap(([key, value]) => [
+        '--label',
+        `${key}=${value}`,
+    ]);
     const containerName = `openai-agents-sandbox-${(0, node_crypto_1.randomUUID)().slice(0, 8)}`;
     const workspaceMount = await resolveDockerWorkspaceMount(args.workspaceRootPath, args.manifestRoot);
     const pathGrantMounts = await resolveDockerPathGrantMounts(args.manifest);
@@ -1504,6 +1697,7 @@ async function startDockerContainer(args) {
         '-d',
         '--name',
         containerName,
+        ...labelArgs,
         '--label',
         `${DOCKER_OWNERSHIP_LABEL}=true`,
         '--label',
@@ -1612,18 +1806,6 @@ function dockerVolumeMountContainingPath(manifest, path) {
 function dockerInContainerMountContainingPath(manifest, path) {
     return dockerMountContainingPath(manifest, path, isDockerInContainerMount);
 }
-function dockerSplitPathGrantContainingPath(manifest, path) {
-    const { grant } = new workspacePaths_1.WorkspacePathPolicy({
-        root: manifest.root,
-        extraPathGrants: manifest.extraPathGrants,
-    }).resolve(path);
-    return grant && sandboxPathGrantUsesDistinctHostPath(grant)
-        ? grant.path
-        : undefined;
-}
-function sandboxPathGrantUsesDistinctHostPath(grant) {
-    return grant.hostPath !== undefined && grant.hostPath !== grant.path;
-}
 function dockerMountContainingPath(manifest, path, predicate) {
     const resolved = new workspacePaths_1.WorkspacePathPolicy({
         root: manifest.root,
@@ -1767,17 +1949,25 @@ async function prepareDockerMountCredentialFiles(session, manifest, entry, mount
         environment: preparedEnvironment,
     };
 }
-async function resolveTrustedDockerPath(session, path, action) {
-    const dockerArgs = ['exec', '-i', '-w', '/'];
+function dockerFileEnvironmentArgs(environment) {
+    // Clear manifest values before starting even the trusted environment launcher.
     const clearedEnvironment = new Set([
-        ...Object.keys(session.state.environment),
+        ...Object.keys(environment),
         'LD_PRELOAD',
         'LD_LIBRARY_PATH',
         'LD_AUDIT',
     ]);
-    for (const key of clearedEnvironment) {
-        dockerArgs.push('-e', `${key}=`);
-    }
+    return [...clearedEnvironment].flatMap((key) => ['-e', `${key}=`]);
+}
+async function resolveTrustedDockerPath(session, path, action) {
+    session.resolveContainerFilesystemPath();
+    const dockerArgs = [
+        'exec',
+        '-i',
+        '-w',
+        '/',
+        ...dockerFileEnvironmentArgs(session.state.environment),
+    ];
     dockerArgs.push('-e', 'PATH=/usr/bin:/bin', '-e', 'HOME=/root', '-u', 'root', session.state.containerId, '/usr/bin/realpath', '-m', '--', path);
     let result;
     try {