Skip to content
AgentsKit

@agentskit/cross-platform β€” for agents

One place for OS and runtime portability. Spawn, paths, line endings and filesystem that behave the same on Windows, macOS and Linux under Node, Bun and Deno.

#Install

npm install @agentskit/cross-platform

#Why

Windows contributors kept fixing the same bugs in every repository: .cmd shims (npx, pnpm, claude) failing without a shell, prompts truncated at the first newline by cmd.exe, \ vs / in path comparisons, CRLF breaking hashes and frontmatter, EBUSY on rename, and child processes left running after a timeout. This package owns those fixes and the libraries behind them (cross-spawn, tree-kill, pathe, std-env, graceful-fs, which). See ADR-0036.

#Primary exports

#Processes

  • spawnProcess(command, args?, options?) β€” returns a ChildHandle with web-stream stdin/stdout/stderr, an exited promise and a tree-wide kill(). Never throws for a failed start: exited rejects with CrossPlatformError.
  • runCommand(command, args?, options?) β€” runs to completion; resolves { code, signal, stdout, stderr, timedOut, truncated, durationMs }. A non-zero exit is a result, not an error.
  • spawnShell(commandLine, options?) / runShell(commandLine, options?) β€” same handle/result, but through the platform shell (sh -c on POSIX, %ComSpec% /d /s /c on Windows). Only for command lines a user wrote (hooks, scripts). shellCommand(line, env) returns that invocation.
  • spawnNodeChild(command, args?, options?) β€” child_process.spawn with the same resolution (.cmd shims, cmd.exe escaping, child PATH), for code that needs Node streams and events (JSON-RPC over stdio, long-lived servers). A missing command emits the usual 'error' (ENOENT); pair it with killProcessTree.
  • selectAdapter(runtime?) β€” the native adapter: node:child_process, Bun.spawn or Deno.Command.
  • resolveCommand(command, args, { cwd, env }) β€” Windows command resolution and cmd.exe escaping (cross-spawn's parser).
  • killProcessTree(pid, signal?, fallback?) β€” taskkill /T /F on Windows; on POSIX a tree walk plus the process group pid leads (children spawned with detached: true), so descendants whose parent already exited are reached too.
  • findExecutable(command) / commandExists(command) β€” PATH lookup honouring PATHEXT.
  • safeEnv({ inherit?, extra?, source? }) β€” minimal child env with SYSTEM_ENV_KEYS (PATH, PATHEXT, SystemRoot, COMSPEC…). getEnv(name) is case-insensitive on Windows. homeDir(), tempDir().

Options: cwd, env, input (written to stdin, then closed), stdin/stdout/stderr (pipe | inherit | ignore), timeoutMs, killGraceMs, signal (AbortSignal), windowsHide (default true), and for runCommand/runShell maxOutputBytes (per stream).

#Paths and file URLs

  • toPosix, normalizePosix, joinPosix, resolvePosix, relativePosix, basename, dirname, extname β€” / output on every OS (pathe).
  • samePath(a, b), isPathInside(parent, child) β€” separator-, trailing-slash- and (on Windows) case-insensitive.
  • isAbsolutePath, isWindowsStylePath.
  • fileUrlToPath, pathToFileUrl, moduleDir(import.meta.url), isMainModule(import.meta.url) β€” never use new URL(...).pathname.

#Text

  • normalizeEol, stripBom, splitLines, splitFrontmatter (CRLF/BOM tolerant), hashText (SHA-256 after EOL normalisation; Web Crypto).

#Filesystem

  • removePath (rm -rf with retries), renamePath (graceful-fs retries on Windows locks), writeFileAtomic (temp file on the same volume, then rename), createSymlink (junction/copy fallback without Windows symlink privilege), copyPath, setFileMode (no-op on Windows; returns false).

#Testing helpers

Import createFetchStub, jsonResponse, and withTempDir from @agentskit/cross-platform/testing. They have no test-runner dependency; withTempDir uses this package's OS temp-directory and retrying cleanup helpers.

#Runtime and errors

  • getRuntimeInfo() β†’ { runtime, os, platform, isServer }; isWindows, isMacOS, isLinux, isBun, isDeno (std-env).
  • CrossPlatformError, CrossPlatformErrorCodes (AK_PLATFORM_PERMISSION_DENIED, AK_PLATFORM_COMMAND_NOT_FOUND, AK_PLATFORM_SPAWN_FAILED, AK_PLATFORM_INVALID_INPUT, AK_PLATFORM_UNSUPPORTED_RUNTIME), isPermissionError, isNotFoundError, mapRuntimeError, permissionDenied.

#Guardrail

  • PORTABILITY_RULES, scanText, scanRepository, countFindings, compareToBaseline, tightenBaseline, runCli β€” back the agentskit-cross-platform check bin (ratchet baseline in .cross-platform-baseline.json; runCli accepts optional { rules, filter } for custom ratchets; cross-platform-ignore: <reason> skips every rule on the line, and <rule-id>-ignore: <reason> skips only that rule).

#Source layout

  • packages/cross-platform/src/process/ β€” spawn, run, kill, command resolution and the Node, Bun and Deno adapters behind spawnProcess, runCommand and killProcessTree.
  • packages/cross-platform/src/lint/ β€” the guardrail: rules.ts, scan.ts, baseline.ts and the cli.ts behind agentskit-cross-platform check.

#Usage

import { runCommand, spawnProcess } from '@agentskit/cross-platform'

const result = await runCommand('claude', ['-p', '--output-format', 'json'], {
  input: longMultiLinePrompt,
  timeoutMs: 120_000,
})

const child = spawnProcess('npx', ['-y', '@modelcontextprotocol/server-filesystem', '.'])
for await (const chunk of child.stdout!) process.stdout.write(chunk)

#Notes

  • @agentskit/cross-platform/pure exposes paths, text and runtime detection without node: imports (browsers, edge workers).
  • Deno: missing --allow-run/--allow-read/--allow-write/--allow-env raises AK_PLATFORM_PERMISSION_DENIED naming the flag. It never prompts.
  • Supported: Node β‰₯ 20.19, Bun β‰₯ 1.2, Deno β‰₯ 2.0 on Windows, macOS and Linux (CI matrix).

Explore nearby