graff — a fast agentic coding harness in Zig: multi-provider, MCP, workflows, DGM evolution loop, TS/Python SDKs
Python
//! One `shell` tool (fx-style) for run / output / kill.
//!
//! Catalog advertises `shell`. Dispatch still accepts `bash`, `bash_output`,
//! and `bash_kill` so in-flight models and rlm `bash()` keep working.
//! `action=interact` is refused: jobs spawn with stdin ignored (not a PTY).
//! Typing in the composer during a live command is steer, not process stdin.
const std = @import("std");
const Allocator = std.mem.Allocator;
const Value = std.json.Value;
const tools = @import("tools.zig");
const ToolCall = tools.ToolCall;
const ToolCtx = tools.ToolCtx;
const ToolOutput = tools.ToolOutput;
const strField = tools.strField;
const intField = tools.intField;
const missingArg = tools.missingArg;
const jobs = @import("jobs.zig");
const exec_bash = @import("exec_bash.zig");
pub const tool_name = "shell";
/// ADR 0234: name the OS the commands run on. Told nothing, models write GNU
/// syntax, and `sed -i 's/a/b/' f` fails on macOS's BSD sed.
const os_clause = switch (@import("builtin").os.tag) {
.macos => " on macOS (BSD tools: `sed -i ''`, no GNU-only flags)",
.linux => " on Linux",
else => "",
};
const desc_head = "Run a shell command via /bin/sh -c";
pub const tool_desc = desc_head ++ os_clause ++ " in the current working directory, read a background job, or stop one. action=run (default when command is set) returns stdout/stderr/exit. A user-cancelled command reports cancelled (its whole local process group is killed; a remote process started over ssh may survive on the remote host). Foreground commands still running after 120s (interactive sessions and lean -p: 15s) move to the background and return a job id. For long-running commands set run_in_background true to skip the wait. You are notified on completion — do not poll. action=output wait_ms>0 blocks until exit (up to 10h) for a finite job; a persistent server snapshots immediately (wait_ms is ignored) and stays on /jobs. action=kill stops it. A background job that writes nothing and is read by nobody for 2 hours is stopped for inactivity; the user pins a long-lived server with /jobs keep. bash/bash_output/bash_kill still dispatch. Not a PTY: you cannot type into the process. Type in the composer to steer the turn.";
pub const tool_schema =
\\{"type": "object", "properties": {"action": {"type": "string", "enum": ["run", "output", "kill"], "description": "run a command, read a job, or stop a job. Default run when command is set."}, "command": {"type": "string", "description": "Shell command to execute (action=run)"}, "timeout": {"type": "integer", "description": "Unattended runs only: foreground wait in milliseconds before auto-background. A shorter value promotes earlier, not below 5000; a larger value cannot extend past the 120s (lean -p: 15s) bound. Interactive sessions always wait 15s. 0 uses the default. Ignored when run_in_background is true. A persistent server's action=output is a snapshot, not wait-until-exit."}, "run_in_background": {"type": "boolean", "description": "Start as a background job and return its id immediately instead of waiting (default false). Do not poll it."}, "id": {"type": "integer", "description": "Job id for action=output or kill"}, "wait_ms": {"type": "integer", "description": "0 = snapshot now. Finite jobs: >0 waits until exit (10h cap). Persistent servers: snapshot now; wait_ms is ignored. Do not poll."}}}
;
/// ADR 0242: a rendered catalog whose shell description names python3's
/// version, read once at startup (python_version.zig). Unchanged when unknown.
pub fn withPython(arena: std.mem.Allocator, catalog: []const u8) ![]const u8 {
const v = @import("python_version.zig").version;
if (v.len == 0) return catalog;
const clause = switch (@import("builtin").os.tag) {
.macos => try std.fmt.allocPrint(arena, " on macOS (BSD tools: `sed -i ''`, no GNU-only flags; python3 is {s}, so scripts must run on {s})", .{ v, v }),
.linux => try std.fmt.allocPrint(arena, " on Linux (python3 is {s}, so scripts must run on {s})", .{ v, v }),
else => try std.fmt.allocPrint(arena, " (python3 is {s}, so scripts must run on {s})", .{ v, v }),
};
return std.mem.replaceOwned(u8, arena, catalog, desc_head ++ os_clause, try std.mem.concat(arena, u8, &.{ desc_head, clause }));
}
pub const Action = enum { run, output, kill };
pub fn isFamily(name: []const u8) bool {
return std.mem.eql(u8, name, tool_name) or
std.mem.eql(u8, name, "bash") or
std.mem.eql(u8, name, "bash_output") or
std.mem.eql(u8, name, "bash_kill");
}
/// A call that runs a shell command: the advertised name or its legacy
/// alias. Every gate that inspects `command` must use this (#1292).
pub fn runsCommand(name: []const u8) bool {
return std.mem.eql(u8, name, tool_name) or std.mem.eql(u8, name, "bash");
}
pub fn isAlias(name: []const u8) bool {
return std.mem.eql(u8, name, "bash") or
std.mem.eql(u8, name, "bash_output") or
std.mem.eql(u8, name, "bash_kill");
}
fn aliasAction(name: []const u8) ?Action {
if (std.mem.eql(u8, name, "bash")) return .run;
if (std.mem.eql(u8, name, "bash_output")) return .output;
if (std.mem.eql(u8, name, "bash_kill")) return .kill;
return null;
}
fn parseAction(name: []const u8, input: Value) error{ Missing, Interact, Unknown }!Action {
if (aliasAction(name)) |a| return a;
const raw = strField(input, "action") orelse {
if (strField(input, "command") != null) return .run;
return error.Missing;
};
if (std.mem.eql(u8, raw, "run")) return .run;
if (std.mem.eql(u8, raw, "output") or std.mem.eql(u8, raw, "wait")) return .output;
if (std.mem.eql(u8, raw, "kill") or std.mem.eql(u8, raw, "stop")) return .kill;
if (std.mem.eql(u8, raw, "interact") or std.mem.eql(u8, raw, "write")) return error.Interact;
return error.Unknown;
}
pub fn actionOf(call: ToolCall) ?Action {
return parseAction(call.name, call.input) catch null;
}
pub fn runCommand(call: ToolCall) ?[]const u8 {
const action = actionOf(call) orelse return null;
if (action != .run) return null;
return strField(call.input, "command");
}
pub fn isBackgroundRun(call: ToolCall) bool {
if (actionOf(call) != .run) return false;
const v = call.input.object.get("run_in_background") orelse return false;
return v == .bool and v.bool;
}
pub fn isJobControl(call: ToolCall) bool {
const action = actionOf(call) orelse return false;
return action == .output or action == .kill;
}
pub fn isKill(call: ToolCall) bool {
return actionOf(call) == .kill;
}
pub fn exec(ctx: ToolCtx, call: ToolCall) !ToolOutput {
const gpa = ctx.gpa;
const action = parseAction(call.name, call.input) catch |err| switch (err) {
error.Missing => return missingArg(gpa, "action or command"),
error.Interact => return .{
.text = try gpa.dupe(u8, "shell action=interact is not available: jobs ignore stdin (not a PTY). Use action=run with a non-interactive command, or action=output/kill on a job id. Type in the composer to steer the turn — that does not type into the process."),
.is_error = true,
},
error.Unknown => return .{
.text = try gpa.dupe(u8, "shell action must be run, output, or kill"),
.is_error = true,
},
};
switch (action) {
.run => {
if (strField(call.input, "command") == null) return missingArg(gpa, "command");
return exec_bash.exec(ctx, call);
},
.output => {
const id = intField(call.input, "id") orelse return missingArg(gpa, "id");
const wait_ms = intField(call.input, "wait_ms") orelse 0;
if (id < 0 or id > @import("shell_identity.zig").last) return .{ .text = try gpa.dupe(u8, "invalid job id"), .is_error = true };
return jobs.jobOutput(gpa, ctx.io, @intCast(id), @intCast(@max(wait_ms, 0)));
},
.kill => {
const id = intField(call.input, "id") orelse return missingArg(gpa, "id");
if (id < 0 or id > @import("shell_identity.zig").last) return .{ .text = try gpa.dupe(u8, "invalid job id"), .is_error = true };
return jobs.jobKill(gpa, ctx.io, @intCast(id));
},
}
}
fn parseCall(gpa: Allocator, name: []const u8, json: []const u8) !struct { parsed: std.json.Parsed(Value), call: ToolCall } {
const parsed = try std.json.parseFromSlice(Value, gpa, json, .{});
return .{ .parsed = parsed, .call = .{ .id = "t", .name = name, .input = parsed.value } };
}
test "shell actions: run default, aliases, interact refused" {
const gpa = std.testing.allocator;
{
var c = try parseCall(gpa, "shell", "{\"command\":\"echo hi\"}");
defer c.parsed.deinit();
try std.testing.expectEqual(Action.run, actionOf(c.call).?);
try std.testing.expectEqualStrings("echo hi", runCommand(c.call).?);
try std.testing.expect(!isBackgroundRun(c.call));
try std.testing.expect(!isJobControl(c.call));
}
{
var c = try parseCall(gpa, "shell", "{\"action\":\"output\",\"id\":3}");
defer c.parsed.deinit();
try std.testing.expectEqual(Action.output, actionOf(c.call).?);
try std.testing.expect(isJobControl(c.call));
try std.testing.expect(!isKill(c.call));
}
{
var c = try parseCall(gpa, "shell", "{\"action\":\"stop\",\"id\":3}");
defer c.parsed.deinit();
try std.testing.expectEqual(Action.kill, actionOf(c.call).?);
try std.testing.expect(isKill(c.call));
}
{
var c = try parseCall(gpa, "bash", "{\"command\":\"true\"}");
defer c.parsed.deinit();
try std.testing.expectEqual(Action.run, actionOf(c.call).?);
try std.testing.expect(isFamily("bash") and isAlias("bash"));
}
{
var c = try parseCall(gpa, "bash_output", "{\"id\":1}");
defer c.parsed.deinit();
try std.testing.expectEqual(Action.output, actionOf(c.call).?);
}
{
var c = try parseCall(gpa, "shell", "{\"action\":\"interact\",\"session_id\":\"x\"}");
defer c.parsed.deinit();
try std.testing.expect(actionOf(c.call) == null);
try std.testing.expectError(error.Interact, parseAction("shell", c.call.input));
}
}
test "shell interact dispatch names the missing PTY" {
const gpa = std.testing.allocator;
var parsed = try std.json.parseFromSlice(Value, gpa, "{\"action\":\"interact\",\"chars\":\"ls\\n\"}", .{});
defer parsed.deinit();
var client: std.http.Client = undefined;
const ctx: ToolCtx = .{
.gpa = gpa,
.io = std.testing.io,
.client = &client,
.provider = undefined,
.registry = null,
.from_sub = false,
.approvals = null,
.tracer = null,
};
const out = try exec(ctx, .{ .id = "t", .name = "shell", .input = parsed.value });
defer gpa.free(out.text);
try std.testing.expect(out.is_error);
try std.testing.expect(std.mem.indexOf(u8, out.text, "not a PTY") != null);
}
test "#1270: a NUL byte in a shell command is refused with its offset, never run" {
const gpa = std.testing.allocator;
var client: std.http.Client = undefined;
const ctx: ToolCtx = .{ .gpa = gpa, .io = std.testing.io, .client = &client, .provider = undefined, .registry = null, .from_sub = false, .approvals = null, .tracer = null };
for ([_][]const u8{ "shell", "bash" }) |name| {
var c = try parseCall(gpa, name, "{\"command\":\"true\\u0000 && false\"}");
defer c.parsed.deinit();
try std.testing.expectEqual(@as(?usize, 4), std.mem.indexOfScalar(u8, runCommand(c.call).?, 0));
const out = try exec(ctx, c.call);
defer gpa.free(out.text);
try std.testing.expect(out.is_error);
try std.testing.expect(!out.pending);
try std.testing.expect(std.mem.indexOf(u8, out.text, "NUL byte at offset 4") != null);
}
}
test "ADR 0234: the shell tool names the OS its commands run on" {
switch (@import("builtin").os.tag) {
.macos => try std.testing.expect(std.mem.startsWith(u8, tool_desc, "Run a shell command via /bin/sh -c on macOS (BSD tools: `sed -i ''`, no GNU-only flags) in the current")),
.linux => try std.testing.expect(std.mem.startsWith(u8, tool_desc, "Run a shell command via /bin/sh -c on Linux in the current")),
else => try std.testing.expect(std.mem.startsWith(u8, tool_desc, "Run a shell command via /bin/sh -c in the current")),
}
}
test "ADR 0242: a known python3 version rides the shell tool's OS clause" {
var arena_state = std.heap.ArenaAllocator.init(std.testing.allocator);
defer arena_state.deinit();
const a = arena_state.allocator();
const pv = @import("python_version.zig");
const saved = pv.version;
defer pv.version = saved;
const catalog = "[{\"name\":\"shell\",\"description\":\"" ++ tool_desc ++ "\"}]";
pv.version = "";
try std.testing.expectEqualStrings(catalog, try withPython(a, catalog));
pv.version = "3.9";
const out = try withPython(a, catalog);
try std.testing.expect(std.mem.indexOf(u8, out, "python3 is 3.9, so scripts must run on 3.9") != null);
try std.testing.expect(std.mem.indexOf(u8, out, ") in the current working directory") != null or @import("builtin").os.tag != .macos);
try std.testing.expectEqual(@as(usize, 1), std.mem.count(u8, out, "python3 is 3.9"));
}
test "catalog advertises shell, not the three bash names" {
const schema = @import("schema.zig");
var saw_shell = false;
for (schema.base_specs) |t| {
try std.testing.expect(!std.mem.eql(u8, t.name, "bash"));
try std.testing.expect(!std.mem.eql(u8, t.name, "bash_output"));
try std.testing.expect(!std.mem.eql(u8, t.name, "bash_kill"));
if (std.mem.eql(u8, t.name, tool_name)) {
saw_shell = true;
try std.testing.expectEqualStrings(tool_desc, t.desc);
try std.testing.expectEqualStrings(tool_schema, t.schema);
try std.testing.expect(std.mem.indexOf(u8, t.schema, "wait_ms is ignored") != null);
try std.testing.expect(std.mem.indexOf(u8, t.desc, "snapshots immediately") != null);
}
}
try std.testing.expect(saw_shell);
}
test "shell controls preserve JS exact handles and reject out of range integers" {
const gpa = std.testing.allocator;
var client: std.http.Client = undefined;
const ctx: ToolCtx = .{ .gpa = gpa, .io = std.testing.io, .client = &client, .provider = undefined, .registry = null, .from_sub = false, .approvals = null, .tracer = null };
for ([_][]const u8{ "bash_output", "bash_kill" }) |name| {
for ([_]i64{ 4294967296, 9007199254740991, -1, 9007199254740992 }) |id| {
const input = try std.fmt.allocPrint(gpa, "{{\"id\":{d}}}", .{id});
defer gpa.free(input);
var c = try parseCall(gpa, name, input);
defer c.parsed.deinit();
const out = try exec(ctx, c.call);
defer gpa.free(out.text);
try std.testing.expect(out.is_error);
if (id < 0 or id > @import("shell_identity.zig").last) {
try std.testing.expectEqualStrings("invalid job id", out.text);
} else {
const expected = try std.fmt.allocPrint(gpa, "background job {d} has no live owner", .{id});
defer gpa.free(expected);
try std.testing.expect(std.mem.startsWith(u8, out.text, expected));
}
}
}
}