@hachej/boring-execution

中文文档
0.5.1发布于 2026/11/17MITTypeScriptES Module零依赖构建来源已验证近 30 天下载 2.4万

Native Pi working-environment types and independently composable workspace leases.

原始使用文档
文档目录7 节
  1. Disposable virtual workspace
  2. Python (opt-in, Node only)
  3. Optional local Git
  4. Borrowed remote Shell
  5. Borrowed remote FileSystem
  6. Virtual repository saved in SQLite
  7. AWS Code Interpreter environment

@hachej/boring-execution

Optional working environments use Pi's public FileSystem, Shell and ExecutionEnv contracts. /native re-exports those contracts. /contracts adds acquisition and lease identity without requiring recovery, a shell or a Boring resource reference.

Disposable virtual workspace

/virtual provides createVirtualWorkspace. Install the exact optional peer [email protected] alongside the declared native peers. Seed absolute paths, acquire a native environment with an absolute cwd, or create a public upstream Bash instance.

import { createVirtualWorkspace } from '@hachej/boring-execution/virtual';
import { BACKGROUND_CONTEXT } from '@earendil-works/chord/context';

const workspace = createVirtualWorkspace({
  providerId: 'scratch',
  files: { '/repo/note.txt': 'hello\n' },
});
const lease = await workspace.acquire({
  operationId: 'open-scratch', input: { cwd: '/repo' },
}, BACKGROUND_CONTEXT);
console.log(await workspace.createBash({ cwd: '/repo' }).exec('cat note.txt'));
await lease.release(BACKGROUND_CONTEXT);
workspace.dispose();

One upstream InMemoryFs stores all bytes. Public mutation adapters resolve aliases consistently for native access, Bash and Git. Leases share namespace identity and have independent cwd and cleanup. Releasing a lease closes only its native facade. Disposing the workspace prevents new acquisitions/Bash instances and closes native facades. Already returned raw filesystem and Bash handles remain trusted host-owned handles; disposal does not revoke them or terminate their commands.

Native read/write/append, directory access, symlinks and exclusive temporary files are exercised by public tests. Native rename, truncate and durable flush return not_supported. The backing refuses move and recursive directory copy. These refusals precede mutation. Hard links refuse with ENOTSUP. Virtual Bash refuses hard-link arguments before stock ln -f can remove an existing destination; symbolic links retain the stock command context. Concurrent structural changes to paths remain unqualified; this disposable adapter is not an authoritative publication provider or a POSIX filesystem qualification.

The native shell runs Pi's stock bash tool with buffered output: onOutput receives the combined stdout and stderr once when the command ends (never as a live stream), spill thresholds are accepted but nothing is spilled to a file, and timeout (seconds) aborts the command and returns timeout. Use public Bash exec for separate buffered stdout/stderr. Host Bash options select upstream limits and explicit network/custom commands. No native executable fallback or network transport is added. Host callbacks are trusted code.

Errors are bounded in one place (boundedMessage in src/bounded-error.ts, also used by the AWS Code Interpreter environment below): every error the native environment, the git command or a fs backing passes on toward a tool result is its message only, with stack-frame lines dropped even when a backing put them in the message, and at most MAX_ERROR_CHARS (2,000, exported from /virtual) characters. The whole error stays on cause for host logs. Command output itself is bounded by Pi's bash tool (its tail, 50 KB or 2,000 lines).

Python (opt-in, Node only)

createVirtualWorkspace({ providerId, python: true }) adds python3 and python to every shell of the workspace (the native exec's included): just-bash's CPython 3.13 compiled to WebAssembly, with the standard library, reading and writing the same files as the shell. It is off by default and is the only way to turn it on (shell options cannot). Limits: Node only, so it throws a clear TypeError in a browser or its workers; the runtime (about 10 MB, shipped inside just-bash) loads on the first call (about a second here; later calls about half a second); its memory is not contained by the shell's execution limits, so a script can grow the host process; there is no pip, package installation or network. A Python traceback is the script's own output and passes through unchanged.

Optional local Git

/virtual-git requires [email protected] and @hachej/boring-files/git. createVirtualGitFs(workspace.filesystem) supplies its public promise filesystem. The host creates one createGitRepository({ fs, directory, author, authorize }), then calls installVirtualGitCommand({ bash, repository }). Installation verifies the actual public bash.fs identity. Each command requires the selected root cwd. Native tools receive the same repository instance.

The command supports local init, matrix status, single-path add, index-only rm --cached, commit -m, bounded log, branch, checkout, and binary-content JSON diff or diff --cached. Other argument forms return exit 126. The files guide owns authorization, serialization and diff semantics. No remote transport, durable recovery or publication transaction is claimed. Raw .git writes remain subject to the selected filesystem's host policy.

Run node fixtures/virtual-workspace.mjs after building for a fictional shared native/Bash/Git example. test/packages/execution.test.mjs exercises public output and actual native ToolTasks. npm run test:virtual-consumer installs the tarball and exact registry dependency closure outside the repository, checks declarations and repeats those tests. Set npm_config_cache to a writable cache containing the pinned archives.

Borrowed remote Shell

/remote-shell exports paired createRemoteShellHandler and createRemoteShellLease Fetch adapters over native Pi Shell. This subpath needs only the pinned native peers. It does not load virtual Bash, Git, Boring files or an agent implementation. The host authenticates each POST, enforces origin/CSRF policy, selects an already acquired workspace, and provides its native Shell, Context, exact identity, revocation signal and command authorization callback. Authorization must return true and runs before execution and terminal disclosure. Abort the revocation signal when access or workspace identity changes, including during silent commands.

The client takes that expected identity, a fixed HTTP(S) endpoint and an explicit authenticated Fetch function. The transport must honor redirect: 'error' and must not retry command requests. Both ends bind provider, instance, incarnation and selected view. The server checks identity before effects. The client checks identity before delivering output, validates ordered request-bound frames and requires exactly one terminal result followed by EOF. A lost or malformed acknowledgement returns native ExecutionError('unknown'); the client never replays the command. A request identifier correlates frames, not a durable idempotency or recovery record.

Command strings, cwd, environment and native exit/error results pass through (protocol version 2). Output callbacks receive live combined text and the caller's Context. Pi's window option is forwarded to the worker's native Shell, and skipped counts on its output chunks are relayed in the output frames (validated, never invented), The handler also applies the window itself (remote-shell-window.ts): it keeps the retained tail, flushes no faster than minIntervalMs, and reports what it dropped as merged skipped counts, so a worker that ignores the window (Pi's Node environment) still transfers only the tail. Counts a windowing worker already reports are merged, not recomputed. Without window, every chunk is delivered. Exit-only calls do not request output frames. Positive fractional timeout values use native seconds, with the provider responsible for its additional limits. Hosts explicitly qualify timeout and spill support; unsupported requested features refuse before execution. Spill paths remain in the remote workspace and need a separately authorized file capability to retrieve them. No dummy filesystem is supplied.

Transport defaults are 64 KiB per request, 1 MiB per frame and 4 MiB of queued server frames. Oversized output or an overfull queue interrupts observation rather than reporting truncated success. These bounds do not cap native output production or Fetch/provider peak memory. Host native execution limits remain necessary. Local cancellation, callback failure or lease release requests remote cancellation and reports unconfirmed termination; prior effects can remain. Each borrowed lease owns only its active transports, and never calls the shared provider's cleanup.

Run node fixtures/remote-shell.mjs for an actual native command through in-process Request/Response streaming. npm run test:remote-shell-consumer installs only the execution tarball and pinned native registry closure, checks strict declarations and repeats public native tests without the virtual/Git/Boring UI/agent peers. The handler reads request bodies through @hachej/boring-files/request-guard, so install @hachej/boring-files (an optional peer) with this subpath; the consumer installs its archive. This establishes the paired Fetch protocol and selected native behavior. Socket deployment, vendor provisioning/reattachment, durable command admission/recovery, independent file grants, protected builds and process-tree termination remain separate qualifications.

Borrowed remote FileSystem

/remote-files exports createRemoteFileSystemHandler and createRemoteFileSystemLease over native Pi FileSystem. Install the exact optional peer [email protected] with the declared native peers. This entry does not require a shell, virtual Bash, Git, Boring files, UI or an agent implementation.

The host authenticates each POST and selects an already acquired workspace. Its bindFileSystem(cwd, context) returns a WorkspaceLease<FileSystem> over that namespace with the requested cwd. The adapter checks the actual lease identity, native filesystem ID and cwd before execution and disclosure. Bind distinct facades for concurrent incompatible cwd values. Binding must not provision or silently recreate a workspace. The handler releases each bound lease after its operation, or after closing its native line reader. It never invokes shared provider cleanup.

authorize(call, cwd) receives a discriminated native method/argument tuple and must return literal true. The handler checks authorization before and after each operation and stream read. Abort the host revocation signal when authorization or workspace identity changes, including while a reader is idle. Authentication, origin/CSRF policy, path and symlink confinement, deadlines and provider limits remain host responsibilities. Native temporary-file operations retain provider semantics, which can place files outside cwd. A cwd check alone is not a path grant.

The client captures cwd and arguments for each invocation. Native path, binary, metadata, text and mutation results pass through validated request-bound envelopes. Native errors retain their code, message and optional path. A lost, malformed or post-dispatch cancelled acknowledgement returns FileError('unknown') and can follow prior effects. There is no automatic retry, rollback or durable deduplication. The request ID correlates the response only. Authoritative published resources use their separate conditional publication contract.

openTextLineReader retains one streamed native reader. Frames preserve strict LF splitting and each line's terminated flag. A cancelled readLine wait leaves its pending frame available for the next call. Cancelling the original open context after successful opening does not close the reader. Concurrent reads refuse. Explicit close or lease release cancels local observation; server cleanup closes the reader before releasing its facade. Client close does not wait for a remote cleanup acknowledgement or prove remote termination.

Pi's openBinaryReader and openDirReader keep a handle open, which a stateless request cannot. The client therefore turns each reader call into one request-bound call (binaryInfo, readRange, scanLines, readDirPage) that opens the worker's own native reader, answers a bounded range, line scan or directory page, and closes it. scanLines runs on the worker, so locating lines in a large file does not move the file; read is split into responses that fit the response limit, and a range above the worker's limit is refused. The client records the opened file's size and mtimeMs and sends them with every call; the worker checks them before and after the read and fails with FileError('invalid') when the file changed (Pi's FileInfo has no inode, so a same-size, same-mtime replacement cannot be told apart). Directory pages continue by entry offset over the native reader and are checked against the directory's mtimeMs; a directory that changed between pages fails instead of skipping or repeating entries. Native open errors (not_found, is_directory, not_directory, invalid for noFollow links) keep their codes. These calls pass through authorize like every other method. Only environments without positional reads (the in-memory virtual file system) use snapshotReaders in fs-readers.ts.

Known deviations from Pi's reader contract: a reader holds no handle, so renaming or replacing the file after openBinaryReader makes later calls fail (not_found or invalid) instead of reading the originally opened file; the path is resolved to an absolute path once at open, so a later cwd change does not affect an open reader; concurrent next() calls on one directory reader are refused with invalid; an empty not-done directory page is refused (unknown) rather than looped on; directory paging costs O(offset) per page on the worker.

watch is one streamed request: the worker's native watch feeds a bounded queue (a full queue, or a frame over the limit, becomes Pi's overflow), each change is authorized again before disclosure, and mode comes from the native watcher. A terminal error is kept apart from the bounded event queue (a full queue collapses events to overflow, never the error) and an oversized error has its text bounded; a stream that ends without an error change is reported to the listener as an error change. An error change ends the stream; revocation, a lost stream or lease release deliver one error change; close (or aborting the stream) closes the native watcher, and no change is delivered after close resolves. Establishing the watch fails with the worker's native error, so an environment without native watching reports its own not_supported.

Defaults are 1 MiB per request, 4 MiB per normal JSON response and 1 MiB per stream frame. Binary values travel as canonical base64 text (protocol version 3; older peers are refused, so upgrade both ends together). Server backpressure queues at most one frame and reads on demand, with a read possibly in flight. These limits bound accepted transport data, not native reader allocation, JSON expansion, Fetch allocation or provider production. Oversized data refuses instead of reporting truncated success.

Run node fixtures/remote-files.mjs after building to write and stream a fictional native file without a shell capability. npm run test:remote-files-consumer installs the execution and files tarballs (this subpath reads bodies through @hachej/boring-files/request-guard) and pinned registry dependencies, checks strict declarations and exercises actual native files, a native ToolTask and reader lifetime races. Its pinned buffer fixture dependency keeps undici's bare type import inside the isolated installation when the temporary directory has a parent workspace. In-process Fetch evidence does not qualify deployed sockets, vendor lifecycle, acquisition recovery, protected builds or complete exposure policy.

Virtual repository saved in SQLite

createVirtualWorkspace({ providerId, fs }) keeps the files in a Pi FileSystem instead of memory, for example the SQLite workspace backend openSqliteFileSystem of @hachej/boring-files/sqlite-filesystem: the shell, isomorphic-git and the native environment then work on the very rows a workspace provider over the same fs reads and writes (one view, no copy). That backend has regular files and directories only: ln is refused, chmod changes nothing (files report 0644, directories 0755) and touch sets the modification time to now.

@hachej/boring-execution/virtual-sqlite is a git repository on such a file system: openVirtualRepository({ fs, root?, seed?, seedMessage?, author?, context, providerId? }) returns { root, env, repository, close() }. fs is the SQLite file system over openBrowserSqliteConnection (the private, unpublished @hachej/boring-browser/sqlite, monorepo-only; supply your own browser SqliteConnection otherwise) in a browser tab, or over openNodeConnection (@hachej/boring-files/sqlite) in Node. It composes the pieces above and adds no file or shell API of its own (BORING-PI-6): read, list, write and run commands through env, Pi's native ExecutionEnv, whose exec shell has the git command bound to repository (@hachej/boring-files/git) on the same files (the stock virtual environment creates a shell without it). Every write lands in SQLite as it happens; there is nothing to save, and close() only releases the workspace. When root has no .git yet it is filled from seed (paths relative to root) and committed; otherwise the files and history are the stored ones.

AWS Code Interpreter environment

@hachej/boring-execution/aws-code-interpreter needs the exact optional peer @aws-sdk/[email protected]; the host passes its own BedrockAgentCoreClient (region, credentials, retries). It makes no AWS call except the session start, the command tools and stop(), and creates no AWS resource. The recipe that uses it is examples/hosts/aws; the decisions are in HOST-RECIPE-AWS.md.

createCodeInterpreterEnv({ client, codeInterpreterIdentifier, session, id, mount, cwd?, umask?, pollIntervalMs?, renew?, rotateMarginSeconds? }) returns { env, owned, sessionId(), lost(), renew(), stop(context) }. env is one native Pi ExecutionEnv over one folder that both this host and the Code Interpreter session mount (an EFS access point): mount.path is where the session sees it (/mnt/<name>), mount.root where this host does. Tool paths are session paths, so commands and file tools name the same file.

  • Commands run through startCommandExecution, then getTask every pollIntervalMs (500 ms by default) until a terminal status. The cwd, environment (env, or env -i for inheritEnv: false) and umask (default 002) are prefixed to the command, which runs under bash -c. onOutput receives the new part of stdout, then of stderr, after each poll; spill thresholds are accepted and nothing is spilled. timeout (seconds) and an aborted context call stopTask and return timeout/aborted, termination unconfirmed. A failed status with an exit code is a normal result.
  • Files run on this host's mount through Pi's NodeExecutionEnv: no bytes cross the API. A path outside mount.path, or one whose resolution (symbolic links included, dangling ones followed by hand) leaves mount.root, returns FileError('permission_denied'); operations that do not follow a final link (fileInfo, exists, remove, renameFile) check its directory. Paths in results and errors are session paths. createTempDir/createTempFile return not_supported (a temporary file here would be invisible to the session). The check and the use are separate steps: a link changed in between by a concurrent command is not caught.
  • Session: { sessionId } borrows a running session, which stop() never ends; { start: { name?, sessionTimeoutSeconds?, filesystemConfigurations? } } starts one on the first command and stop() ends it once. env.cleanup() never stops a session. When the service reports the session gone (ResourceNotFoundException), the running and every later command return shell_unavailable and lost() is true; files stay. renew: 'auto' (default for started sessions; borrowed ones are always manual) starts a new session on the NEXT command after a loss: the failing command still returns shell_unavailable and is never replayed, since it may have had side effects. Before a command, a session older than sessionTimeoutSeconds - rotateMarginSeconds (default 60 s, at most half the time to live) is replaced for NEW commands. Rotation never stops the old session: a command stays on the session it started in (an unknown outcome after a transport failure stays unknown; nothing kills or replays it) and the old session lingers until its own sessionTimeoutSeconds, so hosts that care about idle sessions set a shorter timeout. Starts are single-flight (commands arriving during a rotation share the one new session); a failed Start leaves commands on the current session and backs off. stop() stops the current session and every session this env started and has not confirmed stopped, and waits for them; a failed stop stays tracked, rejects, and is retried by the next stop(). renew: 'manual' keeps the earlier behaviour: only renew() (started sessions only) lets the next command start a new session. Loss is ResourceNotFoundException plus the names and message patterns in the exported SESSION_ENDED_ERRORS (for example a ValidationException about a terminated session): those extra shapes are verified against the real service (owner, 2026-10-12; see HOST-RECIPE-AWS.md), and AccessDeniedException is never loss. Service and file errors map to ExecutionError/FileError with messages bounded by the same boundedMessage (no stack frames, at most MAX_ERROR_CHARS).

efsUserLayout({ userId, uid, gid?, runtimeMountPath?, runtimeAccessPointRoot?, interpreterMountPath? }) is pure: for a user id ([a-z0-9][a-z0-9_-]{0,63}, never a path) and a host-allocated uid it returns the access point to create (root /boring/users/<id>, POSIX user uid:1000, setgid 2770, a boring:user tag), the session mount (/mnt/workspace), this host's folder (/mnt/efs/users/<id>), the state directory outside it (/mnt/efs/state/<id>, with journal.sqlite and harnessFile(key)), the namespace id and the filesystemConfigurations entry.

test/packages/execution.test.mjs drives the real SDK client against examples/hosts/aws/fake-code-interpreter.mjs (the wire format, without AWS): shared files, output, exit codes, cwd and environment, timeout and abort through stopTask, a lost session (auto renewal mid-turn and under concurrent commands, rotation before the time to live without stopping the old session, a stop that fails once and is retried, manual mode, borrowed sessions), borrowed versus owned stop, and two users who never see each other's folders (.., absolute paths, links and dangling links made by a command). The full deployment journey has not run against AWS (the session-ended error shapes are verified against the real service, owner 2026-10-12); see the open questions in HOST-RECIPE-AWS.md.

版本与发布记录

@hachej/boring-execution 共发布 98 个版本,首次发布于 2026/10/12;过去 12 个月发布了 98 个版本。最新版本附带 npm provenance 构建来源证明,可追溯到公开的 CI 构建记录。

版本发布日期距今
0.5.1latest2026/11/17今天
0.5.0next2026/11/133 天前
0.4.852026/11/125 天前
0.4.842026/11/125 天前
0.4.832026/11/125 天前
0.4.822026/11/116 天前

关于 @hachej/boring-execution 的常见问题

@hachej/boring-execution 是什么?

Native Pi working-environment types and independently composable workspace leases.

如何安装 @hachej/boring-execution?

在项目目录运行 npm install @hachej/boring-execution,或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖:@earendil-works/chord(~1.5.2)、@earendil-works/pi-durable(~1.5.2)。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖,Yarn 需要手动安装。

@hachej/boring-execution 支持 TypeScript 吗?

支持。包内自带 TypeScript 类型声明(package.json 声明了 types 入口),安装后即可获得类型提示,无需再安装 @types 包。

@hachej/boring-execution 支持 ESM 还是 CommonJS?

以 ES Module 形式发布,推荐使用 import 引入。在 CommonJS 项目中,Node.js 20.19+ / 22.12+ 可以直接 require() 不含顶层 await 的 ES Module,更早的版本需要改用动态 import()。

@hachej/boring-execution 需要什么版本的 Node.js?

package.json 的 engines 字段要求 Node.js >=22.19.0。版本不符时 npm 默认只给出警告,开启 engine-strict 后会拒绝安装。

@hachej/boring-execution 可以商用吗?

@hachej/boring-execution 使用 MIT 许可。宽松许可:允许商业使用、修改和再分发,通常只需在分发时保留原版权与许可声明。以上为概括,不构成法律意见,请以许可原文为准。

@hachej/boring-execution 的下载量有多少?

根据 npm 官方下载统计,@hachej/boring-execution 在 2026/10/17 – 2026/11/15 这 30 天内被下载 24,325 次,日均约 811 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入,适合横向比较热度,不能直接等同于使用人数。

@hachej/boring-execution 还在维护吗?

最新版本 0.5.1 发布于 2026/11/17(今天);至今共发布 98 个版本,其中过去 12 个月发布了 98 个;首次发布于 2026/10/12。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。