Repository navigation
feat(js): add customBuiltins to Bash and BashTool #1646
Description
Python has Bash(custom_builtins={...}) from #1315 but the JS bindings
(@everruns/bashkit) were missing this feature.
What was missing
Bashhas persistent VFS acrossexecute()calls but no way to
register JS callbacks as persistent builtinsScriptedTool.addTool()has callbacks but VFS is ephemeral per call- The issue described
JS bindings already have this via Bash.defineCommand()
but in realitydefineCommandnever existed
What was implemented
BashOptions.customBuiltins: Record<string, BuiltinCallback>— constructor-timeBash.addBuiltin(name, callback)— post-constructionBashToolequivalent supportBuiltinContextwithname,argv,stdin,env,cwd- 10 tests covering pipes, VFS persistence, reset survival, pipelines
import { Bash } from '@everruns/bashkit';
// Needed API that was missing
const bash = new Bash({
customBuiltins: {
'get-order': (ctx) =>
JSON.stringify({ id: ctx.argv[0], status: 'shipped' }) + '\n',
},
});
await bash.execute('mkdir -p /scratch');
await bash.execute('get-order 42 > /scratch/order.json'); // → VFS
const result = await bash.execute('cat /scratch/order.json'); // persists across callsNotes
executeSync()deadlocks with custom builtins (same limitation as
ScriptedTool). Useexecute()(async).- Custom builtins survive
reset()but are host-side config — pass
customBuiltinsagain on snapshot restore.
Reacted by Mykhailo Chalyi
Activity
mayneyao commentedon May 22, 2026
I am migrating from just-bash to bashkit. Need persistent VFS + custom builtins together — but Bash/BashTool JS bindings were missing this. Python got it in #1315 (constructor-time custom_builtins dict). JS only had ScriptedTool.addTool() which creates a fresh interpreter per call (no VFS persistence across execute()). So I opened a PR to add customBuiltins + addBuiltin() to the JS bindings.
@chaliy
chaliy commentedon May 24, 2026
I went in the little bit other direction, where I added abilty to change builtins in core. I also slop adaopted your changes in terns of contract. - #1721
Can you check if this wors for you? If yes, I will release a version of the lib with this changes.
I am also in progress adding couple of perf improvements, and some examples.
mayneyao commentedon May 24, 2026
Your
BuiltinRegistryapproach is much cleaner, thanks for this work!Would you consider adding three more features to the JS bindings? All in core already, just need exposure:
env — BashBuilder::env() → new Bash({ env: { KEY: "val" } })
network — BashBuilder::network() → new Bash({ network: { allow: ["https://..."] } })
bash.parse(script) returns AST as plain JS object, agent uses it to inspect/intercept commands before execution
I've implemented all three on my fork and they work well. Happy to send PRs if you're interested.
chaliy commentedon May 24, 2026
Good. Let me release that.
Yes
Yes
Yes, but ideally if JSON format would be the same as with rust (e.g. no field renaming)
mayneyao commentedon May 27, 2026
The original AST is also okay; later, we can expose a user-friendly API that encapsulates a layer. That’s fine.
I'd like to ask about Python-related support. I noticed that even when I explicitly instruct in the prompt to prohibit the agent from calling Python, most vendors' LLMs still actively use Python to process data. This is likely related to the training data. Python currently lacks interaction with VFS files, and this capability gap means the agent's call requirements cannot be met. For now, Bash can solve most problems, but LLMs still prefer Python. Whether it's Python or TypeScript, they are currently just simple calculation scripts. If they cannot interact with VFS, it's better not to enable them. I'd like to ask about future plans for supporting this aspect.
mayneyao commentedon May 27, 2026
In most file-related scenarios, LLMs use the with open('/tmp/xxx') syntax, which is currently not supported. This leads to many erroneous calls, and using prompts that limit the Python environment cannot effectively mitigate this.
chaliy commentedon May 28, 2026
My current solution, is not opt-in python in bashkit for cases when Agent does not really need it.
Root case of this, we use in-memory implementation of Python - Monty. And they choose not to support open. It supports pathlib.Path, so with more stricted prompting it can work, pathlib.Path supports VFS.
I was thinking about fork of Monty to add FS and network abstractions, but for now this out of my focus.
chaliy commentedon May 28, 2026
Oh! Nice. Actually in latest not yet released version of Monty, there is an extensibility point for Open. Nice-nice. Let's me wire this :).
chaliy commentedon May 28, 2026
I merged #1800 , but tommorrow I will need to built more testing around this. If you have some time to check if this works, that would be awesome.
(But also, Monty is under active development, and bashkit uses latest main commit, this not more then experimental, pls be careful)
mayneyao commentedon May 28, 2026
That's so fast! Cool, I'll test it.
chaliy commentedon Jun 1, 2026
Hey, if you do mind, I will close this issue. Feel free to reopen or submit new one at any time.