dsh-gitbash-shell 0.39.4 → 0.40.0

package/src/native-output.js

@@ -0,0 +1,347 @@
+// Private, operation-local adapter over the public subprocess raw-pipe seam.
+// No peer imports: the host must inject its exported ./output OutputCollector.
+import fs from 'node:fs';
+import path from 'node:path';
+import { randomUUID } from 'node:crypto';
+
+const ENCODINGS = Object.freeze({ utf8: 'utf-8', 'utf-8': 'utf-8', gbk: 'gbk', cp936: 'gbk', utf16le: 'utf-16le', 'utf-16le': 'utf-16le', raw: 'raw' });
+const freeze = value => Object.freeze(value);
+const failure = (error, code) => freeze({ code: String(error?.code ?? code), message: String(error?.message ?? error).slice(0, 400) });
+function integer(value, fallback, name, min = 0) {
+  const result = value ?? fallback;
+  if (!Number.isSafeInteger(result) || result < min) throw new TypeError(`${name} must be a safe integer >= ${min}`);
+  return result;
+}
+function encoding(value = 'utf8') {
+  const label = ENCODINGS[value];
+  if (!label) throw new TypeError(`Unsupported native output encoding: ${value}`);
+  if (label !== 'raw') {
+    // Probe both replacement and fatal support in the actual host, before spawn.
+    new TextDecoder(label, { fatal: false, ignoreBOM: true });
+    new TextDecoder(label, { fatal: true, ignoreBOM: true });
+  }
+  return label;
+}
+function isCollect(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value)
+    && Number.isSafeInteger(value.maxBytes) && value.maxBytes >= 0
+    && Object.keys(value).every(key => key === 'maxBytes' || key === 'spill')
+    && (value.spill === undefined || (value.spill !== null && typeof value.spill === 'object'
+      && Number.isSafeInteger(value.spill.maxBytes) && value.spill.maxBytes >= 0
+      && Object.keys(value.spill).every(key => key === 'maxBytes')));
+}
+function alignedStart(bytes, start) {
+  while (start < bytes.length && (bytes[start] & 0xc0) === 0x80) start++;
+  return start;
+}
+function alignedEnd(bytes, end) {
+  if (end === bytes.length) return end;
+  while (end > 0 && (bytes[end] & 0xc0) === 0x80) end--;
+  return end;
+}
+
+/**
+ * Construct one immutable operation's provider facade. Create another facade for
+ * a different encoding/configuration; no ambient per-agent or global settings.
+ *
+ * Only known {maxBytes, spill?} stdout/stderr modes opt in. Pipe, inherit and
+ * future/unknown modes are delegated unchanged. The real provider still owns
+ * execution, abort, termination, range observation, stdin and control.
+ *
+ * artifactDirectory must ALREADY exist and be owned/authorized by the caller.
+ * artifactPolicyValidated is only a misuse guard, NOT a sandbox grant: the
+ * native executor must enforce its actual resolved danger-only policy first.
+ * This adapter never creates directories, chmods, removes files or grants access.
+ * The caller owns artifact retention/removal after all readers have finished.
+ *
+ * maxTotalBytes bounds adapter-owned byte payload reservations + artifact bytes,
+ * not provider/Node pipe buffers, JS object overhead or copies retained by callers.
+ * Memory reservation includes tail backing buffers, snapshot/string copies and
+ * bounded decode scratch (conservative multipliers). No raw in-memory history.
+ * Artifact quotas are SHARED by both streams and by raw + normalized UTF8 files.
+ * Readers use normalized UTF8 byte offsets, never raw/source-byte offsets.
+ */
+export function createNativeOutputAdapter(provider, options = {}) {
+  if (!provider || typeof provider.spawn !== 'function') throw new TypeError('A real subprocess provider is required');
+  if (typeof options.OutputCollector !== 'function') throw new TypeError('Inject the host OutputCollector from its public ./output export');
+  const config = freeze({
+    OutputCollector: options.OutputCollector,
+    stdoutEncoding: encoding(options.stdoutEncoding),
+    stderrEncoding: encoding(options.stderrEncoding),
+    errors: options.errors ?? 'replace',
+    maxSpillBytes: integer(options.maxSpillBytes, 8 * 1024 * 1024, 'maxSpillBytes'),
+    maxTotalBytes: integer(options.maxTotalBytes, 16 * 1024 * 1024, 'maxTotalBytes', 1024),
+    drainTimeoutMs: integer(options.drainTimeoutMs, 250, 'drainTimeoutMs', 1),
+    artifactDirectory: options.artifactDirectory,
+  });
+  if (!['replace', 'strict'].includes(config.errors)) throw new TypeError('errors must be replace or strict');
+  if (config.drainTimeoutMs > 2_147_483_647) throw new TypeError('drainTimeoutMs exceeds Node timer range');
+  if (config.artifactDirectory !== undefined) {
+    if (options.artifactPolicyValidated !== true) throw new Error('Native output artifacts require caller policy validation');
+    if (typeof config.artifactDirectory !== 'string' || !path.isAbsolute(config.artifactDirectory)) throw new TypeError('artifactDirectory must be absolute');
+    if (!fs.statSync(config.artifactDirectory).isDirectory()) throw new TypeError('artifactDirectory must already be a directory');
+  }
+
+  function spawn(spec) {
+    const names = ['stdout', 'stderr'].filter(name => isCollect(spec.stdio?.[name]));
+    if (!names.length) return provider.spawn(spec);
+    // Capture mutable caller dispositions before invoking the real provider.
+    const modes = Object.fromEntries(names.map(name => [name, freeze({ maxBytes: spec.stdio[name].maxBytes, spillMax: spec.stdio[name].spill?.maxBytes })]));
+    const scratchBytes = Math.max(1, Math.min(1024, Math.floor(config.maxTotalBytes / 256)));
+    const baseReservation = scratchBytes * 64 + 256 * names.length;
+    const tailShare = Math.max(0, Math.floor((config.maxTotalBytes - baseReservation) / (16 * names.length)));
+    const caps = Object.fromEntries(names.map(name => [name, Math.min(modes[name].maxBytes, tailShare)]));
+    const reservedMemoryBytes = baseReservation + names.reduce((sum, name) => sum + caps[name] * 16, 0);
+    const budget = { artifactBytes: 0, limit: Math.min(config.maxSpillBytes, config.maxTotalBytes - reservedMemoryBytes) };
+    const owners = names.map(name => makeOwner(name, modes[name], caps[name], config, budget, scratchBytes));
+    const stdio = { ...spec.stdio };
+    for (const name of names) stdio[name] = 'pipe';
+    let real;
+    try { real = provider.spawn({ ...spec, stdio }); }
+    catch (error) { for (const owner of owners) owner.finish('spawn-error'); throw error; }
+    for (const owner of owners) owner.attach(real[owner.name]);
+    let timer;
+    let processSettled = false;
+    const armDrain = reason => {
+      if (timer || owners.every(owner => owner.isSettled())) return;
+      timer = setTimeout(() => { for (const owner of owners) owner.finish(reason); }, config.drainTimeoutMs);
+    };
+    const onAbort = () => {
+      for (const owner of owners) owner.markAborted();
+      armDrain('abort-drain-timeout');
+    };
+    const signal = spec.signal;
+    signal?.addEventListener('abort', onAbort, { once: true });
+    if (signal?.aborted) onAbort();
+    const outputSettled = Promise.all(owners.map(owner => owner.settled)).then(() => {
+      clearTimeout(timer);
+    });
+    // Observe success AND rejection immediately. Decoding/storage NEVER changes
+    // process outcome or converts a successful side-effecting process into a
+    // provider failure that might invite an unsafe retry.
+    const done = Promise.resolve(real.done).then(async outcome => {
+      processSettled = true;
+      armDrain('exit-drain-timeout');
+      await outputSettled;
+      signal?.removeEventListener('abort', onAbort);
+      return outcome;
+    }, async error => {
+      processSettled = true;
+      armDrain('provider-error-drain-timeout');
+      await outputSettled;
+      signal?.removeEventListener('abort', onAbort);
+      throw error;
+    });
+    const collected = { ...real.collected };
+    for (const owner of owners) collected[owner.name] = owner.reader;
+    const additions = {
+      done, outputSettled, collected: freeze(collected),
+      terminate(...args) {
+        // Direct kill/dispose need not abort spec.signal. Record interruption
+        // before delegating, but never retroactively spoil a completed result
+        // merely because an owner invokes idempotent cleanup after settlement.
+        if (!processSettled || !owners.every(owner => owner.isSettled())) {
+          for (const owner of owners) owner.markAborted();
+          armDrain('terminate-drain-timeout');
+        }
+        return real.terminate(...args);
+      },
+      outputFacts: () => freeze({
+        ...Object.fromEntries(owners.map(owner => [owner.name, owner.facts()])),
+        budget: freeze({ maxTotalBytes: config.maxTotalBytes, reservedMemoryBytes, artifactBytes: budget.artifactBytes, maxArtifactBytes: budget.limit }),
+      }),
+      ...Object.fromEntries(names.map(name => [name, undefined])),
+    };
+    return delegate(real, additions);
+  }
+  return delegate(provider, { spawn, provider, outputConfig: config });
+}
+
+// Bind unknown methods to their REAL receiver (including private-field methods).
+// Do not mutate provider/handle identity or their service registration.
+function delegate(real, additions) {
+  return new Proxy(Object.create(null), {
+    get(_target, key) {
+      if (Object.hasOwn(additions, key)) return additions[key];
+      const value = Reflect.get(real, key, real);
+      return typeof value === 'function' ? value.bind(real) : value;
+    },
+    has: (_target, key) => Object.hasOwn(additions, key) || key in real,
+    set() { return false; },
+  });
+}
+
+function makeOwner(name, mode, cap, config, budget, scratchBytes) {
+  const label = config[`${name}Encoding`];
+  const collector = new config.OutputCollector(cap, `native-${name}`); // no host-private spill fields
+  const decoder = label === 'raw' ? undefined : new TextDecoder(label, { fatal: config.errors === 'strict', ignoreBOM: true });
+  // A fatal validator distinguishes actual invalid bytes from a legitimate U+FFFD.
+  let validator = label === 'raw' || config.errors === 'strict' ? undefined : new TextDecoder(label, { fatal: true, ignoreBOM: true });
+  let rawBytes = 0, decodedUtf8Bytes = 0, decodeError, storageError, streamError;
+  let settled = false, naturalEOF = false, aborted = false, termination, stream, stopText = false;
+  let resolveSettled;
+  const settledPromise = new Promise(resolve => { resolveSettled = resolve; });
+  const artifacts = {};
+  function recordStorage(error) { storageError ??= failure(error, 'NATIVE_OUTPUT_STORAGE'); }
+  function artifact(kind) {
+    if (!config.artifactDirectory) return undefined;
+    return artifacts[kind] ??= { kind, encoding: kind === 'raw' ? label : 'utf-8', bytes: 0, capReached: false, error: undefined, path: undefined, fd: undefined, sealed: false };
+  }
+  function writeArtifact(kind, bytes) {
+    const target = artifact(kind);
+    if (!target || !bytes.length || target.error || target.capReached) return;
+    const streamLimit = kind === 'decoded' ? Math.min(mode.spillMax ?? config.maxSpillBytes, config.maxSpillBytes) : config.maxSpillBytes;
+    let length = Math.min(bytes.length, Math.max(0, budget.limit - budget.artifactBytes), Math.max(0, streamLimit - target.bytes));
+    if (kind === 'decoded') length = alignedEnd(bytes, length);
+    if (length < bytes.length) target.capReached = true;
+    if (!length) return;
+    try {
+      if (target.fd === undefined) {
+        const filename = path.join(config.artifactDirectory, `native-${randomUUID()}-${name}-${kind}.${kind === 'raw' ? 'bin' : 'utf8.log'}`);
+        target.fd = fs.openSync(filename, 'wx', 0o600);
+        target.path = filename;
+      }
+      let offset = 0;
+      while (offset < length) {
+        const written = fs.writeSync(target.fd, bytes, offset, length - offset);
+        if (!Number.isSafeInteger(written) || written <= 0) throw new Error('Native artifact write made no progress');
+        offset += written;
+        target.bytes += written;
+        budget.artifactBytes += written;
+      }
+    } catch (error) { target.error = failure(error, 'NATIVE_OUTPUT_SPILL'); recordStorage(error); }
+  }
+  function publish(text) {
+    if (!text) return;
+    const bytes = Buffer.from(text, 'utf8');
+    decodedUtf8Bytes += bytes.length;
+    writeArtifact('decoded', bytes);
+    if (stopText) return;
+    try {
+      // Bound backing allocations, too: OutputCollector may retain subarray tails.
+      // Every push owns a small copy, never a view of the provider's giant chunk.
+      const step = Math.max(1, Math.min(scratchBytes, cap || 1));
+      for (let offset = 0; offset < bytes.length; offset += step) {
+        const slice = bytes.subarray(offset, offset + step);
+        // Unpooled storage prevents a one-byte retained tail pinning an 8KiB slab.
+        const owned = Buffer.allocUnsafeSlow(slice.length);
+        owned.set(slice);
+        collector.push(owned);
+      }
+    } catch (error) { recordStorage(error); stopText = true; }
+  }
+  function ingest(chunk) {
+    if (settled) return;
+    if (!(chunk instanceof Uint8Array)) {
+      streamError ??= failure(new Error('Raw pipe emitted non-byte data (setEncoding must not be used)'), 'NATIVE_OUTPUT_NOT_BYTES');
+      finish('stream-error');
+      return;
+    }
+    rawBytes += chunk.byteLength;
+    // Never decode a giant incoming chunk in one allocation. Borrow raw slices;
+    // output/string scratch is bounded even after an error or artifact cap.
+    for (let offset = 0; offset < chunk.byteLength; offset += scratchBytes) {
+      const bytes = chunk.subarray(offset, offset + scratchBytes);
+      writeArtifact('raw', bytes);
+      if (!decoder || (decodeError && config.errors === 'strict')) continue;
+      if (validator) {
+        try { validator.decode(bytes, { stream: true }); }
+        catch (error) { decodeError ??= failure(error, 'NATIVE_OUTPUT_DECODE'); validator = undefined; }
+      }
+      try { publish(decoder.decode(bytes, { stream: true })); }
+      catch (error) { decodeError ??= failure(error, 'NATIVE_OUTPUT_DECODE'); }
+    }
+  }
+  function finish(reason) {
+    if (settled) return;
+    settled = true;
+    termination = reason;
+    naturalEOF = reason === 'end';
+    if (validator) {
+      try { validator.decode(); }
+      catch (error) { decodeError ??= failure(error, 'NATIVE_OUTPUT_DECODE'); }
+    }
+    if (decoder && !(decodeError && config.errors === 'strict')) {
+      try { publish(decoder.decode()); }
+      catch (error) { decodeError ??= failure(error, 'NATIVE_OUTPUT_DECODE'); }
+    }
+    try { collector.seal(); } catch (error) { recordStorage(error); }
+    for (const target of Object.values(artifacts)) {
+      if (target.fd !== undefined) {
+        try { fs.closeSync(target.fd); }
+        catch (error) { target.error ??= failure(error, 'NATIVE_OUTPUT_SPILL_CLOSE'); recordStorage(error); }
+        target.fd = undefined;
+      }
+      target.sealed = true;
+    }
+    if (stream) {
+      stream.removeListener('data', ingest);
+      stream.removeListener('end', onEnd);
+      stream.removeListener('close', onClose);
+      // Keep a harmless error sink until close: destroy can schedule a late
+      // error, which must not become an uncaught exception after settlement.
+      if (stream.closed) stream.removeListener('error', onError);
+      else stream.once('close', () => stream.removeListener('error', onError));
+      if (!naturalEOF && !stream.destroyed) stream.destroy();
+    }
+    resolveSettled();
+  }
+  const onEnd = () => finish('end');
+  const onClose = () => finish('close-before-end');
+  const onError = error => { if (!settled) { streamError ??= failure(error, 'NATIVE_OUTPUT_STREAM'); finish('stream-error'); } };
+  function artifactFacts() {
+    return freeze(Object.fromEntries(Object.entries(artifacts).map(([kind, target]) => [kind, freeze({
+      kind, encoding: target.encoding, path: target.path, bytes: target.bytes,
+      complete: target.sealed && naturalEOF && !aborted && !target.error && !target.capReached && (kind === 'raw' || !decodeError),
+      capReached: target.capReached, error: target.error,
+    })])));
+  }
+  const reader = freeze({ readFrom(fromByte) {
+    if (!Number.isSafeInteger(fromByte) || fromByte < 0 || fromByte > decodedUtf8Bytes) throw new RangeError('Expected a normalized UTF8 cursor between zero and decodedUtf8Bytes');
+    let snapshot;
+    try { snapshot = collector.snapshot(); }
+    catch (error) { recordStorage(error); return { text: '', nextOffset: decodedUtf8Bytes, lossy: true }; }
+    const start = snapshot.totalBytes - snapshot.bytes.length;
+    const requested = Math.max(0, fromByte - start);
+    const aligned = alignedStart(snapshot.bytes, requested);
+    const spill = artifactFacts().decoded;
+    return {
+      text: snapshot.bytes.subarray(aligned).toString('utf8'),
+      nextOffset: decodedUtf8Bytes,
+      lossy: label === 'raw' || !!decodeError || !!storageError || fromByte < start || aligned !== requested,
+      // Only finalized COMPLETE normalized text can be called a full-output path.
+      ...(spill?.complete && spill.path ? { spillPath: spill.path } : {}),
+    };
+  } });
+  return {
+    name, reader, settled: settledPromise, finish, isSettled: () => settled,
+    markAborted() { aborted = true; },
+    attach(value) {
+      stream = value;
+      if (!stream || typeof stream.on !== 'function') {
+        stream = undefined;
+        streamError = failure(new Error('Provider did not expose requested raw pipe'), 'NATIVE_OUTPUT_PIPE_MISSING');
+        finish('missing-pipe');
+        return;
+      }
+      stream.on('error', onError);
+      stream.once('end', onEnd);
+      stream.once('close', onClose);
+      stream.on('data', ingest);
+      if (stream.readableEnded) finish('end');
+      else if (stream.destroyed || stream.closed) finish('close-before-end');
+    },
+    facts() {
+      const artifact = artifactFacts();
+      const lossy = reader.readFrom(0).lossy;
+      return freeze({
+        encoding: label, errors: config.errors, rawBytes, decodedUtf8Bytes,
+        rawCursor: rawBytes, decodedCursor: decodedUtf8Bytes,
+        reliableText: label !== 'raw' && !decodeError && !streamError && !storageError,
+        lossy, complete: naturalEOF && !aborted && !streamError && !decodeError && !storageError && (label !== 'raw' || artifact.raw?.complete === true),
+        sourceComplete: naturalEOF, aborted, settled, termination, decodeError, streamError, storageError, artifact,
+        retainedMaxBytes: cap,
+      });
+    },
+  };
+}

package/src/native-tool.js

@@ -0,0 +1,195 @@
+import { registerExperimentalTool } from './experimental-tools.js'
+import { createNativeExecutor } from './native-executor.js'
+import { processJob, processSources, ringDelta } from './bash-render.js'
+
+const typedPath = () => ({ type: 'object', additionalProperties: false, properties: {
+  kind: { type: 'string', const: 'path', required: true }, value: { type: 'string', required: true },
+} })
+
+/** defineTool's AUTHOR property-map, not a raw object-root JSON schema. */
+export function nativeParameters({ background = false, promote = false } = {}) {
+  return {
+    description: { type: 'string', required: true, description: 'Short description of the intended native operation.' },
+    executable: { ...typedPath(), required: true, description: 'Absolute native .exe path. MSYS paths translate only in kind:path values. Bare commands, scripts, .cmd and .bat are unsupported.' },
+    argv: { type: 'array', required: true, items: { type: 'object', additionalProperties: false, properties: {
+      kind: { type: 'string', enum: ['literal', 'path'], required: true }, value: { type: 'string', required: true },
+    } }, description: 'Each literal is passed unchanged (including /all, /c, quotes and empty strings); each path must be absolute and is explicitly translated to native Windows spelling. No shell expansion.' },
+    cwd: { ...typedPath(), description: 'Absolute typed working directory; omitted means the agent workspace.' },
+    entrypoint: { type: 'string', enum: ['native', 'interpreter'], description: 'Default native. Known interpreters require explicit interpreter. Their own command language/quoting is not made safe by direct argv; no automatic script wrapper.' },
+    timeoutMs: { type: 'number', description: promote ? 'Foreground wait deadline, default 120000ms, capped at 600000ms; expiry promotes the managed process to a job. Not accepted with run_in_background.' : 'Kill deadline, default 120000ms, capped at 600000ms. Not accepted with run_in_background.' },
+    ...(background ? { run_in_background: { type: 'boolean', description: 'Use existing managed Jobs; collect with job_output, stop with job_kill. No tool deadline. Requires an attached job controller.' } } : {}),
+    stdoutEncoding: { type: 'string', enum: ['utf8', 'gbk', 'utf16le', 'raw'], description: 'Known producer stdout encoding, default utf8. raw preserves unknown/mixed bytes without claiming reliable text. No auto detection.' },
+    stderrEncoding: { type: 'string', enum: ['utf8', 'gbk', 'utf16le', 'raw'], description: 'Known producer stderr encoding, independently selected; default utf8.' },
+    errors: { type: 'string', enum: ['replace', 'strict'], description: 'Default replace; strict records decoding failures separately from actual command exit. Never rerun a side-effecting command merely because output decoding failed.' },
+  }
+}
+
+const streamSchema = { type: 'object', additionalProperties: false, properties: {
+  text: { type: 'string', required: true }, truncated: { type: 'boolean', required: true }, spillPath: { type: 'string' },
+} }
+// Core's author DSL supports integer, not numeric minimum keywords; the
+// adapter owns non-negative counters and budget validation before execution.
+const byteCount = () => ({ type: 'integer', required: true })
+const factBoolean = () => ({ type: 'boolean', required: true })
+const outputErrorSchema = { type: 'object', additionalProperties: false, properties: {
+  code: { type: 'string', required: true }, message: { type: 'string', required: true },
+} }
+const normalizedEncoding = ['utf-8', 'gbk', 'utf-16le', 'raw']
+const artifactSchema = kind => ({ type: 'object', additionalProperties: false, properties: {
+  kind: { type: 'string', const: kind, required: true },
+  encoding: { type: 'string', ...(kind === 'decoded' ? { const: 'utf-8' } : { enum: normalizedEncoding }), required: true },
+  path: { type: 'string' }, bytes: byteCount(), complete: factBoolean(), capReached: factBoolean(), error: outputErrorSchema,
+} })
+const streamFactsSchema = { type: 'object', additionalProperties: false, properties: {
+  encoding: { type: 'string', enum: normalizedEncoding, required: true },
+  errors: { type: 'string', enum: ['replace', 'strict'], required: true },
+  rawBytes: byteCount(), decodedUtf8Bytes: byteCount(), rawCursor: byteCount(), decodedCursor: byteCount(),
+  reliableText: factBoolean(), lossy: factBoolean(), complete: factBoolean(), sourceComplete: factBoolean(),
+  aborted: factBoolean(), settled: factBoolean(),
+  termination: { type: 'string', enum: ['end', 'close-before-end', 'stream-error', 'missing-pipe', 'spawn-error', 'abort-drain-timeout', 'terminate-drain-timeout', 'exit-drain-timeout', 'provider-error-drain-timeout'] },
+  decodeError: outputErrorSchema, streamError: outputErrorSchema, storageError: outputErrorSchema,
+  artifact: { type: 'object', additionalProperties: false, required: true, properties: {
+    raw: artifactSchema('raw'), decoded: artifactSchema('decoded'),
+  } },
+  retainedMaxBytes: byteCount(),
+} }
+// Explicit current adapter DTO, including the two executor-owned degradation
+// branches. Optional undefined projection never admits arbitrary output fields.
+export const NATIVE_OUTPUT_FACTS_SCHEMA = { oneOf: [
+  { type: 'object', additionalProperties: false, properties: {
+    stdout: { ...streamFactsSchema, required: true }, stderr: { ...streamFactsSchema, required: true },
+    budget: { type: 'object', additionalProperties: false, required: true, properties: {
+      maxTotalBytes: byteCount(), reservedMemoryBytes: byteCount(), artifactBytes: byteCount(), maxArtifactBytes: byteCount(),
+    } },
+  } },
+  { type: 'object', additionalProperties: false, properties: { unavailable: { type: 'boolean', const: true, required: true } } },
+  { type: 'object', additionalProperties: false, properties: {
+    projectionError: { type: 'string', required: true }, reliableText: { type: 'boolean', const: false, required: true },
+  } },
+] }
+const sandboxSchema = { type: 'object', additionalProperties: false, properties: {
+  mode: { type: 'string', const: 'danger-full-access', required: true }, denied: { type: 'boolean', const: false, required: true },
+} }
+const encodingSchema = { type: 'object', additionalProperties: false, properties: {
+  stdoutEncoding: { type: 'string', enum: ['utf8', 'gbk', 'utf16le', 'raw'], required: true },
+  stderrEncoding: { type: 'string', enum: ['utf8', 'gbk', 'utf16le', 'raw'], required: true },
+  errors: { type: 'string', enum: ['replace', 'strict'], required: true },
+} }
+export const NATIVE_OUTPUT_SCHEMA = {
+  oneOf: [
+    { type: 'object', additionalProperties: false, properties: {
+      kind: { type: 'string', const: 'foreground', required: true }, cwd: { type: 'string', required: true },
+      status: { type: 'string', enum: ['running', 'completed', 'killed'], required: true }, exitCode: { required: true, oneOf: [{ type: 'integer' }, { type: 'null' }] },
+      signal: { required: true, oneOf: [{ type: 'string' }, { type: 'null' }] },
+      timedOut: { type: 'boolean', required: true }, aborted: { type: 'boolean', required: true }, timeoutMs: { type: 'number', required: true },
+      stdout: { ...streamSchema, required: true }, stderr: { ...streamSchema, required: true },
+      sandbox: { ...sandboxSchema, required: true }, outputFacts: { ...NATIVE_OUTPUT_FACTS_SCHEMA, required: true },
+    } },
+    { type: 'object', additionalProperties: false, properties: {
+      kind: { type: 'string', enum: ['background', 'promoted'], required: true }, cwd: { type: 'string', required: true },
+      jobId: { type: 'string', required: true }, timeoutMs: { type: 'number' }, output: { type: 'string' },
+      encoding: { ...encodingSchema, required: true },
+    } },
+  ],
+}
+
+export function renderNativeResult(value) {
+  if (value.kind !== 'foreground') return `Native command ${value.kind === 'promoted' ? 'continues after the wait deadline' : 'admitted to managed Jobs'}; job id: ${value.jobId}. Collect with job_output, stop with job_kill.\n${value.output ?? ''}\n[requested encoding: ${JSON.stringify(value.encoding)}; final producer/output facts arrive in job output]`
+  const text = value.stdout.text + (value.stderr.text ? `\n[stderr]\n${value.stderr.text}` : '')
+  return `${text}\n[exit code: ${value.exitCode ?? 'unknown'}; status: ${value.status}; signal: ${value.signal ?? 'none'}; timedOut: ${value.timedOut}; aborted: ${value.aborted}]\n[native output facts: ${JSON.stringify(value.outputFacts)}]\nOutput decoding/storage problems do not mean the command did not execute; inspect producer exit facts before considering any retry.`
+}
+
+/** One per-agent module. Host packages and the shared path translator are injected. */
+export function createNativeToolModule(deps) {
+  if (typeof deps.toolsModule?.defineTool !== 'function') throw new Error('gitbash_native: host defineTool capability unavailable')
+  return {
+    inject: ['tools', 'subprocess', 'shellEnv'],
+    apply(ctx, config = {}) {
+      const executor = createNativeExecutor(ctx, deps)
+      const enabled = config.enableRunInBackground !== false
+      const promoteOnTimeout = config.promoteOnTimeout !== false && enabled
+      const definition = jobs => {
+        const background = enabled && jobs !== undefined
+        const promote = background && promoteOnTimeout
+        const startJob = (request, exec) => {
+          let proc
+          let finalFacts = ''
+          const sources = processSources(() => proc)
+          sources.push({ channel: 'stderr', read(fromByte) {
+            const bytes = Buffer.from(finalFacts, 'utf8')
+            return { text: bytes.subarray(fromByte).toString('utf8'), nextOffset: bytes.length, lossy: false }
+          } })
+          const id = jobs.start({ kind: 'gitbash-native', label: request.description,
+            ...(exec.agent ? { owner: exec.agent.id } : {}), output: sources,
+            run: () => processJob(async signal => {
+              proc = await executor.execute(request, exec, { signal, onExpiry: 'none' })
+              return proc
+            }, async started => {
+              // done has already sealed decoding and released this operation's scope.
+              const result = await started.result()
+              finalFacts = `\n[native producer: exitCode=${result.exitCode}, signal=${result.signal}, status=${result.status}, aborted=${result.aborted}]\n[native output facts: ${JSON.stringify(result.outputFacts)}]\nOutput failure is not command non-execution; do not blindly retry.\n`
+              return { status: result.status === 'killed' ? 'killed' : 'completed', detail: `exit code: ${result.exitCode ?? 'unknown'}; output facts retained in job output` }
+            }),
+          })
+          return { id, process: () => proc }
+        }
+        const execute = async (args, exec) => {
+          // prepare resolves policy BEFORE ensure/path/env/artifact work.
+          const request = await executor.prepare(args, exec)
+          exec.signal?.throwIfAborted()
+          if (request.run_in_background && !background) throw new Error('run_in_background is unavailable or disabled; this request was not executed')
+          if (request.run_in_background) {
+            const attached = startJob(request, exec)
+            return { kind: 'background', jobId: attached.id, cwd: request.cwd, encoding: request.output }
+          }
+          if (promote) {
+            // No retry/fallback around admission: a host throwing after starting a
+            // producer must not cause a second execution of a side-effecting call.
+            const attached = startJob(request, exec)
+            const owner = exec.agent?.id
+            let view
+            try { view = await jobs.wait(attached.id, executor.waitBudget(request), owner, exec.signal) }
+            catch (error) {
+              jobs.kill(attached.id, owner, 'tool call aborted')
+              await jobs.wait(attached.id, 10000, owner)
+              throw error
+            }
+            if (view.status === 'running' || view.status === 'stopping') {
+              if (!attached.process()) {
+                jobs.kill(attached.id, owner, 'timed out during native preparation')
+                await jobs.wait(attached.id, 10000, owner)
+                throw new Error(`native preparation timed out; job ${attached.id} was cancelled, inspect job_output before retrying`)
+              }
+              const read = jobs.read(attached.id, owner)
+              return { kind: 'promoted', jobId: attached.id, cwd: request.cwd, timeoutMs: request.timeoutMs,
+                output: ringDelta(read.chunks), encoding: request.output }
+            }
+            jobs.remove(attached.id, owner)
+            if (!attached.process()) throw new Error(view.detail ?? 'native preparation failed before a process handle was available')
+            return { kind: 'foreground', ...await attached.process().result() }
+          }
+          const proc = await executor.execute(request, exec)
+          return { kind: 'foreground', ...await proc.result() }
+        }
+        return deps.toolsModule.defineTool({ name: 'gitbash_native',
+          description: 'Choose this tool BEFORE execution for a Windows-native .exe that needs exact literal argv (for example /all or /c without MSYS conversion) or explicitly known independent stdout/stderr encodings. Use an offered shell tool instead for pipelines, redirection, globbing, shell expansion or POSIX scripts; this is direct typed argv through the host managed executor, not shell source. Supply an absolute executable, mark literal arguments unchanged and path arguments explicitly; do not put a whole shell command into argv. Prefer a producer UTF-8 option; declare gbk/utf16le only when known, raw for unknown or mixed bytes. In PTC call this offered SDK binding from inside run_code, not as a direct model tool call. Only actual danger-full-access standing policy is supported; missing/restricted policy is rejected before execution. A policy/access denial is a stop condition, never permission for another-tool retry. Decoding/storage failure preserves producer exit: never blindly repeat side effects. No user env, implicit scripts, .cmd/.bat wrappers, path guessing or encoding auto-detection. Known interpreters require explicit entrypoint:interpreter; common CRT/Node argv is supported, arbitrary interpreter quoting is not guaranteed.',
+          parameters: nativeParameters({ background, promote }),
+          output: { schema: NATIVE_OUTPUT_SCHEMA, render: (_args, value) => [{ type: 'text', text: renderNativeResult(value) }], presentationMeta: (_args, value) => ({ cwd: value.cwd }) },
+          execute,
+          presentCall: args => ({ card: 'generic', title: args.description, kind: 'execute', content: [{ type: 'text', text: args.executable.value }] }),
+        })
+      }
+      let currentJobs
+      const refresh = registerExperimentalTool(ctx, () => definition(currentJobs), deps.experimentalEnabled, { scope: deps.scope, log: deps.log })
+      if (!enabled) return
+      ctx.inject(['jobs'], jobCtx => {
+        currentJobs = jobCtx.jobs
+        refresh()
+        jobCtx.effect(() => () => {
+          currentJobs = undefined
+          if (ctx.fiber?.state === 2) refresh()
+        })
+      })
+    },
+  }
+}