@chamvi/coding

Coding tools for chamvi agents.
Read, write and edit files, search, run shell commands and show the diff,
in a disposable workspace of the calling run on any sandbox provider.

Table of Contents

• Installation
• Usage
• Tools
• Repository instructions
• Workspaces
• Not effect tools
• Security
• Coding backends
• API
• License

Installation

npm install @chamvi/coding @chamvi/sandbox @chamvi/core ai --save

ESM only, Node.js >=26.0.0. @chamvi/core, @chamvi/sandbox and ai are peer dependencies. Add a sandbox provider: @chamvi/sandbox-docker or @chamvi/sandbox-k8s (or @chamvi/sandbox-local for development).

Usage

import type { LanguageModel } from 'ai';
import { codingTools } from '@chamvi/coding';
import { ToolDeniedError, approve, defineModelAgent } from '@chamvi/core';
import type { IWorkspaceManager } from '@chamvi/sandbox';

export function createCodingAgent(model: LanguageModel, workspaces: IWorkspaceManager) {
    return defineModelAgent({
        name: 'triage',
        model,
        instructions: 'Check out the repository named in the payload, reproduce the reported bug ' +
            'with a failing test and answer with what you found and the diff.',
        // create_workspace and dispose_workspace, then the coding tools
        tools: { ...workspaces.tools(), ...codingTools(workspaces) },
        hooks: {
            // every shell command waits for a human
            async beforeToolExecution({ toolName, input }, ctx) {
                if (toolName !== 'bash') {
                    return input;
                }

                const { command } = input as { command: string };
                const decision = await approve(ctx, { title: 'Run a shell command?', body: command });

                if (!decision.approved) {
                    throw new ToolDeniedError(`Command refused: ${decision.reason ?? 'denied'}`);
                }

                return input;
            },
        },
        budget: { maxSteps: 40 },
    });
}

workspaces is a manager from createWorkspaceManager({ provider }) (@chamvi/sandbox), attached to the engine with workspaces.attach(engine) so a run's workspaces go when it settles. The model calls create_workspace first, then works in it. Subscribe the agent to a channel to start it (channels: [http.on()] with @chamvi/http).

The tools are plain tools you did not write, so the gate lives in the agent's beforeToolExecution hook: it runs before every tool call, and approve() there pauses the run in waiting until someone answers (the UI inbox, POST /runs/:id/approve, or a channel's approval message with ctx.channels.findOneOrFail(name).approve(...)). The run keeps its workspace while it waits on this replica. Once answered, the hook runs again and approve() returns the decision; a thrown ToolDeniedError goes back to the model as a tool error and the run goes on.

Tools

codingTools(workspaces, { outputLogMaxBytes?, repositoryInstructions? }) returns a plain AI SDK ToolSet. Paths are relative to the workspace root or start with /workspace/; anything that leaves the root is a tool error.

git_diff, list_files and grep (with git grep) read paths literally, so a path like :!src names a file and is never pathspec magic. bash keeps its state through an EXIT trap: a command that sets its own EXIT trap replaces it, so that call's working directory and exports are not kept. On a manager with git credentials the edit tools read the raw file (IWorkspace.readFileRaw): they match oldString against the redacted text the model read (redactedSpans), refuse an edit that touches a [redacted] span and put every untouched token back byte for byte, so an oldString can neither probe a token nor write [redacted] back; their errors never echo file text. A model mistake (an unknown file, an oldString that is missing or ambiguous, a bad path) comes back as a tool error it can correct; a broken sandbox is a SandboxError tool error, never a failed run.

Repository instructions

Ordinary UTF-8 workspace read_file results include instructions?: RepositoryInstructions from @chamvi/sandbox by default, scoped to the file's root and ancestors. Image, base64 and HOME log reads have no instruction field. codingTools(workspaces, { repositoryInstructions: false }) omits it from text reads too. This option is independent of the manager's default-on repositoryInstructions: disabling the manager's root collection and explicit tool does not disable coding attachments, and disabling coding attachments leaves the manager's delivery enabled. Set both to false to disable both forms of delivery.

The sandbox collector reads root-first AGENTS.md, then CLAUDE.md per directory and expands standalone @relative/path includes depth-first outside backtick/tilde fences. Each source records path, sha256, redacted content, inherited scopes and includedBy; complete: false and bounded diagnostics report skipped guidance. Source files are whole or omitted (32 KiB each, 128 KiB total; other bounds in the sandbox README). Resolve incomplete guidance that could affect the task. Each read collects current worktree guidance; earlier tool outputs retain the context delivered then in steps and checkpoints across pauses and restarts.

Before direct edits or shell commands in a new subtree, obtain its guidance with read_file or the manager's read_repository_instructions({ paths: ['packages/api/src/new.ts'], workspace }). The latter also works for a file that does not exist yet. Repository text and system prompts confer no operator authorization, permissions, credentials, skill installation or publication rights. Write/edit tools and arbitrary bash do not enforce instruction scope; bash bypasses file-tool-only enforcement. Discovery refuses observed symlinks, special files, .git paths and escapes on a best-effort basis; it is not race-free confinement (#92).

Workspaces

Every tool takes an optional workspace id (from create_workspace). Omitted, the tool uses the run's only workspace; with several, the model must name one. Workspaces are resolved through the manager with context.run.runId, so a run can never reach another run's workspace: an id of another run is "not found".

Not effect tools

write_file, edit_file, multi_edit and bash change state but are deliberately not effect tools. A workspace lives in one process and dies with it, while an effect record survives in the store: after a crash the redone step runs on a fresh workspace, where a recorded "applied" result would skip the write. Re-applying is safe instead: write_file is idempotent, edit_file fails with "oldString not found" when it already applied, and bash runs in a disposable sandbox. Nothing outside the workspace changes (no push).

Security

bash runs whatever the model writes, and the model follows what it reads (an issue, a README, a test output): treat it as untrusted code. Use the Docker or Kubernetes provider, keep the workspace network firewalled, narrow allowRepo on the manager, and put bash behind an approval (a beforeToolExecution hook calling approve(), as in Usage) where a human should see each command.

Coding backends

ICodingBackend is the contract for something that solves a coding task in a workspace with its own tool loop (Claude Code, or these tools in a nested agent):

interface ICodingBackend {
    code(task: CodingTask): Promise<CodingResult>;
}
// CodingTask: { workspace, task, budget?: { maxSteps?, maxTokens?, timeoutMs? }, signal? }
// CodingResult: { status: 'done' | 'stuck', summary, diff }

The package ships the contract only; backends are planned.

API

Types: CodingWorkspaces, CodingToolsOptions, ReadFileResult, ReadFileBinaryResult, ReadFileImageResult, WriteFileResult, EditFileResult, MultiEditResult, GrepEngine, GrepMatch, GrepResult, GlobResult, ListFilesResult, BashResult, BashJobResult, BashJobStatus, BashOutputResult, BashKillResult, GitDiffResult, ICodingBackend, CodingTask, CodingResult, CodingBudget.

License

Published under Apache License 2.0.