Skip to content

graff — a fast agentic coding harness in Zig: multi-provider, MCP, workflows, DGM evolution loop, TS/Python SDKs

Python

compaction: choose where automatic compaction starts, as a percent

justrache4e5421a744b
diff --git a/sdk/generate.py b/sdk/generate.py
index 00057cf9..0fd386ed 100644
--- a/sdk/generate.py
+++ b/sdk/generate.py
@@ -114,6 +114,8 @@ export interface HarnessOptions {{
maxModelCalls?: number;
/** Reject duplicate root tool name+normalized-input calls per turn. */
dedupeToolCalls?: boolean;
+ /** Start automatic compaction at this percent of the context window (10-95; default 80). */
+ compactAt?: number;
/** Extra raw flags. `--json` is always added. */
args?: string[];
}}
@@ -188,6 +190,7 @@ function spawnArgs(o: HarnessOptions): string[] {{
if (o.maxToolCalls !== undefined) a.push("--max-tool-calls", String(o.maxToolCalls));
if (o.maxModelCalls !== undefined) a.push("--max-model-calls", String(o.maxModelCalls));
if (o.dedupeToolCalls) a.push("--dedupe-tool-calls");
+ if (o.compactAt !== undefined) a.push("--compact-at", String(o.compactAt));
if (o.systemPrompt) a.push("--system-prompt", o.systemPrompt);
if (o.appendSystemPrompt) a.push("--append-system-prompt", o.appendSystemPrompt);
if (o.args) a.push(...o.args);
@@ -1482,7 +1485,8 @@ class Harness:
append_system_prompt: Optional[str] = None,
max_tool_calls: Optional[int] = None,
dedupe_tool_calls: bool = False,
- max_model_calls: Optional[int] = None):
+ max_model_calls: Optional[int] = None,
+ compact_at: Optional[int] = None):
binary = binary or _default_binary()
argv = [binary, "--json"]
if yolo:
@@ -1495,6 +1499,8 @@ class Harness:
argv += ["--max-model-calls", str(max_model_calls)]
if dedupe_tool_calls:
argv.append("--dedupe-tool-calls")
+ if compact_at is not None:
+ argv += ["--compact-at", str(compact_at)]
if system_prompt:
argv += ["--system-prompt", system_prompt]
if append_system_prompt:
diff --git a/sdk/py/harness_sdk.py b/sdk/py/harness_sdk.py
index 26ab2fce..e5800698 100644
--- a/sdk/py/harness_sdk.py
+++ b/sdk/py/harness_sdk.py
@@ -224,7 +224,8 @@ class Harness:
append_system_prompt: Optional[str] = None,
max_tool_calls: Optional[int] = None,
dedupe_tool_calls: bool = False,
- max_model_calls: Optional[int] = None):
+ max_model_calls: Optional[int] = None,
+ compact_at: Optional[int] = None):
binary = binary or _default_binary()
argv = [binary, "--json"]
if yolo:
@@ -237,6 +238,8 @@ class Harness:
argv += ["--max-model-calls", str(max_model_calls)]
if dedupe_tool_calls:
argv.append("--dedupe-tool-calls")
+ if compact_at is not None:
+ argv += ["--compact-at", str(compact_at)]
if system_prompt:
argv += ["--system-prompt", system_prompt]
if append_system_prompt:
diff --git a/sdk/ts/harness.ts b/sdk/ts/harness.ts
index d15cfd5a..e2fe186f 100644
--- a/sdk/ts/harness.ts
+++ b/sdk/ts/harness.ts
@@ -77,6 +77,8 @@ export interface HarnessOptions {
maxModelCalls?: number;
/** Reject duplicate root tool name+normalized-input calls per turn. */
dedupeToolCalls?: boolean;
+ /** Start automatic compaction at this percent of the context window (10-95; default 80). */
+ compactAt?: number;
/** Extra raw flags. `--json` is always added. */
args?: string[];
}
@@ -151,6 +153,7 @@ function spawnArgs(o: HarnessOptions): string[] {
if (o.maxToolCalls !== undefined) a.push("--max-tool-calls", String(o.maxToolCalls));
if (o.maxModelCalls !== undefined) a.push("--max-model-calls", String(o.maxModelCalls));
if (o.dedupeToolCalls) a.push("--dedupe-tool-calls");
+ if (o.compactAt !== undefined) a.push("--compact-at", String(o.compactAt));
if (o.systemPrompt) a.push("--system-prompt", o.systemPrompt);
if (o.appendSystemPrompt) a.push("--append-system-prompt", o.appendSystemPrompt);
if (o.args) a.push(...o.args);
diff --git a/src/additional_tests.zig b/src/additional_tests.zig
index 77bb5645..7d1b359a 100644
--- a/src/additional_tests.zig
+++ b/src/additional_tests.zig
@@ -9,6 +9,7 @@ test {
_ = @import("agent_server_compact_tests.zig");
_ = @import("agent_server_compact_route_tests.zig");
_ = @import("compaction_quiet_delivery_tests.zig");
+ _ = @import("compact_at.zig");
_ = @import("provider_codegraff_tests.zig");
_ = @import("agent_responses.zig");
_ = @import("session_branch.zig");
diff --git a/src/args.zig b/src/args.zig
index d4f0b440..0ba8650c 100644
--- a/src/args.zig
+++ b/src/args.zig
@@ -168,6 +168,9 @@ pub fn parse(init: std.process.Init) !Flags {
} else if (std.mem.eql(u8, arg, "--max-tool-calls")) {
const mv = it.next() orelse std.process.fatal("--max-tool-calls needs a non-negative integer — harness --help", .{});
main_mod.max_tool_calls = std.fmt.parseInt(u64, mv, 10) catch std.process.fatal("--max-tool-calls needs a non-negative integer, got '{s}'", .{mv});
+ } else if (std.mem.eql(u8, arg, "--compact-at")) {
+ const mv = it.next() orelse std.process.fatal("--compact-at needs a percent of the context window (10-95)", .{});
+ @import("compact_at.zig").g_cli = @import("compact_at.zig").parse(mv) orelse std.process.fatal("--compact-at needs a percent of the context window (10-95), got '{s}'", .{mv});
} else if (std.mem.eql(u8, arg, "--max-run-tool-calls")) {
const mv = it.next() orelse std.process.fatal("--max-run-tool-calls needs a non-negative integer", .{});
@import("run_budget.zig").cli_max_tool_calls = std.fmt.parseInt(u64, mv, 10) catch std.process.fatal("--max-run-tool-calls needs a non-negative integer", .{});
diff --git a/src/cli.zig b/src/cli.zig
index c3a0d860..7a8f24f7 100644
--- a/src/cli.zig
+++ b/src/cli.zig
@@ -233,6 +233,7 @@ pub const usage_text =
\\ --json structured stdio protocol (JSON in, JSONL events out)
\\ --max-run-tool-calls N aggregate root/descendant tool ceiling for this invocation
\\ --max-tool-calls N reject root tool calls after N per turn (JSON-safe budget)
+ \\ --compact-at PCT start automatic compaction at PCT% of the context window (10-95, default 80)
\\ --max-model-calls N total provider calls allowed across this run (default 0 = unlimited; includes children/title/judges)
\\ --dedupe-tool-calls reject duplicate root tool name+input calls per turn
\\ --no-telemetry disable anonymous usage telemetry for this run
diff --git a/src/command_catalog.zig b/src/command_catalog.zig
index 1e56eec1..8e4be7fb 100644
--- a/src/command_catalog.zig
+++ b/src/command_catalog.zig
@@ -83,6 +83,7 @@ pub const commands = [_]Item{
.{ .name = "/keepcontext", .desc = "toggle keeping the conversation when /model switches wire format (default on)" },
.{ .name = "/effort", .desc = "reasoning depth: low|medium|high|... (codex, deepseek, codegraff; persists)" },
.{ .name = "/reasoning", .desc = "alias for /effort" },
+ .{ .name = "/compact-at", .usage = "/compact-at [10-95|default]", .desc = "where automatic compaction starts, as % of the context window (default 80; persists)" },
.{ .name = "/fast", .desc = "codex only: priority service tier for lower latency (toggle, persists)" },
.{ .name = "/thinking", .desc = "stream reasoning live vs spinner only (toggle, persists)" },
.{ .name = "/title", .desc = "name the tab from your first prompt (AI session title; toggle, persists)" },
diff --git a/src/commands_model.zig b/src/commands_model.zig
index 902c57f7..ea94e820 100644
--- a/src/commands_model.zig
+++ b/src/commands_model.zig
@@ -284,6 +284,7 @@ pub fn tryHandle(root: *Agent, keys: *Keys, arena: Allocator, line: []const u8,
return true;
}
if (try @import("commands_effort.zig").handle(root, arena, line, out)) return true;
+ if (try @import("compact_at.zig").handle(root, line, out)) return true;
if (std.mem.startsWith(u8, line, "/keepcontext")) {
const arg = std.mem.trim(u8, line["/keepcontext".len..], " \t");
if (std.mem.eql(u8, arg, "on")) {
diff --git a/src/compact_at.zig b/src/compact_at.zig
new file mode 100644
index 00000000..33c51da9
--- /dev/null
+++ b/src/compact_at.zig
@@ -0,0 +1,155 @@
+//! Where automatic compaction starts, as a percent of the model's context
+//! window (default 80; `Provider.compactAt`). The first one set wins:
+//!
+//! 1. `--compact-at N` on the command line (the SDK's `compactAt` option)
+//! 2. `GRAFF_COMPACT_PCT=N` (how Harness passes its setting)
+//! 3. `compact_pct` in `.harness/settings.json`, written by `/compact-at`
+//!
+//! `/compact-at N` also applies to the running session at once: compactAt
+//! reads the override on every check, including the server-side directive.
+const std = @import("std");
+const Io = std.Io;
+const Allocator = std.mem.Allocator;
+const Value = std.json.Value;
+const provider_mod = @import("provider.zig");
+const policy = @import("harness_policy.zig");
+const Agent = @import("agent.zig").Agent;
+
+pub const default_pct: u8 = 80;
+/// Below 10% a session compacts on its own standing prompt; at 95% the
+/// emergency trim (`Provider.nearContextLimit`) would fire first.
+pub const min_pct: u8 = 10;
+pub const max_pct: u8 = 95;
+
+/// Set by `--compact-at`; applied over every other source at startup.
+pub var g_cli: ?u8 = null;
+
+/// "70" or "70%", within min_pct..max_pct.
+pub fn parse(text: []const u8) ?u8 {
+ const trimmed = std.mem.trimEnd(u8, std.mem.trim(u8, text, " \t"), "%");
+ const pct = std.fmt.parseInt(u8, std.mem.trim(u8, trimmed, " \t"), 10) catch return null;
+ return if (pct >= min_pct and pct <= max_pct) pct else null;
+}
+
+/// Startup, after the env knobs: the flag beats the env, which beats the
+/// saved setting.
+pub fn applyStartup(io: Io, arena: Allocator) void {
+ if (g_cli) |pct| {
+ provider_mod.g_compact_pct_override = pct;
+ return;
+ }
+ if (provider_mod.g_compact_pct_override != null) return;
+ if (loadSaved(io, arena)) |pct| provider_mod.g_compact_pct_override = pct;
+}
+
+fn loadSaved(io: Io, arena: Allocator) ?u8 {
+ const data = Io.Dir.cwd().readFileAlloc(io, policy.settings_path, arena, .limited(1 << 20)) catch return null;
+ const v = std.json.parseFromSliceLeaky(Value, arena, data, .{ .allocate = .alloc_always }) catch return null;
+ if (v != .object) return null;
+ const saved = v.object.get("compact_pct") orelse return null;
+ if (saved != .integer or saved.integer < min_pct or saved.integer > max_pct) return null;
+ return @intCast(saved.integer);
+}
+
+/// Write `compact_pct` (null removes it), keeping every other key.
+fn save(io: Io, gpa: Allocator, pct: ?u8) bool {
+ Io.Dir.cwd().createDir(io, policy.settings_dir, .default_dir) catch {};
+ var arena_state = std.heap.ArenaAllocator.init(gpa);
+ defer arena_state.deinit();
+ const a = arena_state.allocator();
+ var root_obj: std.json.ObjectMap = .empty;
+ if (Io.Dir.cwd().readFileAlloc(io, policy.settings_path, a, .limited(1 << 20))) |data| {
+ if (std.json.parseFromSliceLeaky(Value, a, data, .{ .allocate = .alloc_always })) |v| {
+ if (v == .object) root_obj = v.object;
+ } else |_| {}
+ } else |_| {}
+ if (pct) |p| {
+ root_obj.put(a, "compact_pct", .{ .integer = p }) catch return false;
+ } else _ = root_obj.orderedRemove("compact_pct");
+ var aw: Io.Writer.Allocating = .init(gpa);
+ defer aw.deinit();
+ var s: std.json.Stringify = .{ .writer = &aw.writer, .options = .{ .whitespace = .indent_2 } };
+ s.write(Value{ .object = root_obj }) catch return false;
+ const f = Io.Dir.cwd().createFile(io, policy.settings_path, .{}) catch return false;
+ defer f.close(io);
+ var wbuf: [4096]u8 = undefined;
+ var fw = f.writer(io, &wbuf);
+ fw.interface.writeAll(aw.writer.buffered()) catch return false;
+ fw.interface.writeAll("\n") catch return false;
+ fw.interface.flush() catch return false;
+ return true;
+}
+
+pub fn current() u8 {
+ return if (provider_mod.g_compact_pct_override) |p| @min(p, 100) else default_pct;
+}
+
+/// `/compact-at` shows the point, `/compact-at N` sets it (and persists it
+/// for this workspace), `/compact-at default` goes back to 80%.
+pub fn handle(root: *Agent, line: []const u8, out: *Io.Writer) !bool {
+ const name = "/compact-at";
+ if (!std.mem.startsWith(u8, line, name)) return false;
+ if (line.len > name.len and line[name.len] != ' ' and line[name.len] != '\t') return false;
+ const arg = std.mem.trim(u8, line[name.len..], " \t");
+ if (arg.len == 0) {
+ try out.print("compaction starts at {d}% of the context window ({d}k of {d}k tokens){s}\n", .{
+ current(),
+ root.provider.compactAt() / 1000,
+ root.provider.context / 1000,
+ if (provider_mod.g_compact_pct_override == null) " · default" else "",
+ });
+ } else if (std.ascii.eqlIgnoreCase(arg, "default") or std.ascii.eqlIgnoreCase(arg, "reset")) {
+ provider_mod.g_compact_pct_override = null;
+ const saved = save(root.io, root.gpa, null);
+ try out.print("compaction starts at the default {d}% of the context window{s}\n", .{ default_pct, if (saved) "" else " (not persisted)" });
+ } else if (parse(arg)) |pct| {
+ provider_mod.g_compact_pct_override = pct;
+ const saved = save(root.io, root.gpa, pct);
+ try out.print("compaction starts at {d}% of the context window ({d}k of {d}k tokens){s}\n", .{
+ pct,
+ root.provider.compactAt() / 1000,
+ root.provider.context / 1000,
+ if (saved) "" else " (not persisted)",
+ });
+ } else {
+ try out.print("usage: /compact-at <{d}-{d}>[%] | default\n", .{ min_pct, max_pct });
+ }
+ try out.flush();
+ return true;
+}
+
+test "parse accepts a bare or percent-suffixed value inside the safe range" {
+ try std.testing.expectEqual(@as(?u8, 70), parse("70"));
+ try std.testing.expectEqual(@as(?u8, 70), parse(" 70% "));
+ try std.testing.expectEqual(@as(?u8, 10), parse("10"));
+ try std.testing.expectEqual(@as(?u8, 95), parse("95%"));
+ for ([_][]const u8{ "9", "96", "100", "0", "-5", "seventy", "", "%", "70.5" }) |bad|
+ try std.testing.expectEqual(@as(?u8, null), parse(bad));
+}
+
+test "the flag beats the env, and the env beats nothing" {
+ const saved_override = provider_mod.g_compact_pct_override;
+ const saved_cli = g_cli;
+ defer provider_mod.g_compact_pct_override = saved_override;
+ defer g_cli = saved_cli;
+ provider_mod.g_compact_pct_override = 55; // GRAFF_COMPACT_PCT
+ g_cli = 70;
+ applyStartup(std.testing.io, std.testing.allocator);
+ try std.testing.expectEqual(@as(?u8, 70), provider_mod.g_compact_pct_override);
+ g_cli = null;
+ provider_mod.g_compact_pct_override = 55;
+ applyStartup(std.testing.io, std.testing.allocator);
+ try std.testing.expectEqual(@as(?u8, 55), provider_mod.g_compact_pct_override);
+}
+
+test "the threshold follows the setting in both directions" {
+ const saved_override = provider_mod.g_compact_pct_override;
+ defer provider_mod.g_compact_pct_override = saved_override;
+ const p: provider_mod.Provider = .{ .id = "t", .kind = .responses, .auth = .bearer, .url = "", .api_key = "", .model = "t", .context = 200_000 };
+ provider_mod.g_compact_pct_override = null;
+ try std.testing.expectEqual(@as(u64, 160_000), p.compactAt());
+ provider_mod.g_compact_pct_override = parse("60%");
+ try std.testing.expectEqual(@as(u64, 120_000), p.compactAt());
+ provider_mod.g_compact_pct_override = parse("90");
+ try std.testing.expectEqual(@as(u64, 180_000), p.compactAt());
+}
diff --git a/src/help.zig b/src/help.zig
index abcf23f9..5017362e 100644
--- a/src/help.zig
+++ b/src/help.zig
@@ -33,7 +33,7 @@ pub const sections = [_]Section{
.{ .title = "working autonomously", .names = &.{ "/goal", "/goals", "/schedule", "/review", "/issue", "/plan", "/todo", "/jobs", "/ultracode", "/strict", "/yolo", "/never" } },
.{ .title = "talking to other graffs", .names = &.{ "/tell", "/daddy", "/peek", "/adapter" }, .blurb = peers_blurb },
.{ .title = "your setup", .names = &.{ "/login", "/key", "/cost", "/usage", "/version", "/update", "/privacy", "/mcp", "/import-claude", "/skills", "/plugins", "/agents", "/hooks", "/tools", "/fleet" } },
- .{ .title = "context & history", .names = &.{ "/compact", "/btw", "/doctor", "/debug", "/cache", "/trace", "/trajectory" } },
+ .{ .title = "context & history", .names = &.{ "/compact", "/compact-at", "/btw", "/doctor", "/debug", "/cache", "/trace", "/trajectory" } },
.{ .title = "shell & images", .names = &.{ "/bash", "/image", "/images", "/paste" } },
.{ .title = "look & feel", .names = &.{ "/theme", "/animation", "/title" } },
.{ .title = "this list", .names = &.{"/help"} },
diff --git a/src/session_settings.zig b/src/session_settings.zig
index 485963b6..a4af6397 100644
--- a/src/session_settings.zig
+++ b/src/session_settings.zig
@@ -297,6 +297,7 @@ fn codegraffLoginKey(io: Io, arena: Allocator, environ_map: anytype) ?[]const u8
pub fn setupSkillsAndTheme(io: Io, arena: Allocator, environ_map: anytype, out: *Io.Writer, flags: args.Flags, use_color: bool, json_mode: bool, cwd_display: []const u8) !ThemeSetup {
try applyEnvKnobs(arena, environ_map);
+ @import("compact_at.zig").applyStartup(io, arena); // --compact-at > GRAFF_COMPACT_PCT > saved /compact-at
@import("python_version.zig").detect(io, environ_map.get("PATH")); // ADR 0242: before any catalog renders
_ = jev_tool.setCodegraffLoginKey(io, codegraffLoginKey(io, arena, environ_map));
skills.loadSkillSettings(io, arena); // per-skill opt-outs, also gates the auto-connect