Skip to content

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

Python

Deliver mid-session instruction and date changes as hot context (#1333)

justrache26e6086655b
diff --git a/docs/adr/0208-hot-context-keyed-updates-keep-the-prefix.md b/docs/adr/0208-hot-context-keyed-updates-keep-the-prefix.md
new file mode 100644
index 00000000..ec2ecda3
--- /dev/null
+++ b/docs/adr/0208-hot-context-keyed-updates-keep-the-prefix.md
@@ -0,0 +1,63 @@
+# 0208. Hot context: keyed updates ride the tail, compaction folds them in
+
+Status: accepted 2026-09-27
+
+## Context
+
+The root system prompt is composed once at startup, and the provider caches
+it as a prefix (ADR 0011). Two things in it can go stale during a live
+session: the project instructions file (`AGENTS.md` / `HARNESS.md` /
+`CLAUDE.md`) and the calendar date. Rewriting the system prompt when either
+changes discards the cached prefix on every edit. Leaving them frozen means
+the model keeps following rules the user has already changed (#1333).
+
+A first cut sent updates as user-role messages. On the Responses wire, the
+model kept following the old system-prompt rule, because a user message
+ranks below system/developer instructions in that wire's instruction
+hierarchy.
+
+## Decision
+
+- Ambient values are keyed sources in `src/hot_context.zig`:
+ `core/instructions` and `core/date`. Before each root model request,
+ `turn_inbox.deliver` diffs them against what the model last saw (a stat
+ probe first, then a content hash) and sends only the changed keys.
+- Each changed key becomes one `<context key="...">` message, inserted just
+ before the pending user prompt. It is tagged `_graff_origin:
+ "hot_context"`, so it is treated as a notice and never as a human turn.
+ Everything already sent keeps its bytes, so the prefix still reads from
+ the cache.
+- The role depends on the wire, so that the update outranks the stale
+ prompt:
+
+ | Wire | Role |
+ |------|------|
+ | Responses | `developer` |
+ | Chat Completions | `system` |
+ | Anthropic Messages | `user` (no mid-thread system role) |
+ | Interactions | `user` (no mid-thread system role) |
+
+ A `/model` switch across wires retypes the update instead of dropping it
+ (`history_translate.zig`).
+- Compaction already loses the cached prefix. After a client summary, an
+ emergency trim, or a provider-side compaction, `afterCompact` does two
+ things. It removes the update messages. Then, if the file differs from
+ what the prompt holds (or the date has moved), it folds the latest section
+ and date into the system base through `prompts.setSystemPrompts`.
+ `afterCompact` compares hashes instead of looking for surviving update
+ messages, because the summary's working set usually drops them already.
+- `/cache` shows `hot ctx N updates last: <key> (appended; prefix kept)`.
+ An update is not counted as a bust.
+- Only the root session gets updates. Subagents get their brief when they
+ are spawned.
+
+## Consequences
+
+An instruction edit now costs one small message at the end of the history
+per change, not a full prefix miss. The file is read from the process cwd.
+An ACP session that enters another tree (or runs `workspace use`)
+therefore receives that tree's instructions as an update.
+
+Revisit this if a Chat Completions provider rejects a mid-thread `system`
+message. The fallback is to send `user` for that provider id only, not for
+the whole wire.
diff --git a/docs/adr/README.md b/docs/adr/README.md
index 33243a3b..3cb826f8 100644
--- a/docs/adr/README.md
+++ b/docs/adr/README.md
@@ -233,6 +233,7 @@ record only when you need the evidence or the edge cases.
| [0204](0204-kimi-platform-is-graff.md) | Kimi requests send `X-Msh-Platform: graff` and `graff/<version>` everywhere (OAuth and inference), never `kimi_code_cli`; a Kimi Code console key bills as plan quota. Supersedes 0027. |
| [0205](0205-subagent-progress-is-standard-tool-content.md) | By default a subagent streams its work onto the parent tool call as content-only `tool_call_update` rows (rolling log + `_meta["graff/subagent"]`); the draft child-session stream only when both sides opt in; `GRAFF_ACP_SUBAGENT_PROGRESS=0` turns it off. |
| [0206](0206-acp-v2-preview-behind-a-gate.md) | ACP v2 draft shapes behind `GRAFF_ACP_V2=1` plus a client `protocolVersion` >= 2; v1 stays the default and unchanged. Prompt is acknowledged with `messageId` on insertion, the outcome travels as `state_update`. |
+| [0208](0208-hot-context-keyed-updates-keep-the-prefix.md) | A mid-session instruction-file edit or date rollover is appended before the next prompt as a keyed `<context>` message (developer role on Responses, system on Chat Completions, user elsewhere), and the system prompt is left as is. Compaction drops those messages and folds the latest values into the new system prompt. |
## When to write one
diff --git a/docs/architecture.md b/docs/architecture.md
index 8f68f7ef..556c5e56 100644
--- a/docs/architecture.md
+++ b/docs/architecture.md
@@ -353,7 +353,10 @@ cwd and builds two arena-owned strings — `sys_normal` (= `main_system_prompt`
+ the file) and `sys_strict` (+ `strict_note`) — stored on the root `Agent`.
`systemPrompt()` returns `sys_strict`/`sys_normal` for the root and the lean
`sub_system_prompt` for subagents. Built once at startup, so there's no
-per-request cost and the prompt stays byte-stable for the KV cache.
+per-request cost and the prompt stays byte-stable for the KV cache. A
+mid-session edit to the file (or a date rollover) is appended as a keyed
+`<context>` update rather than rewriting that prefix; compaction folds the
+latest version back in (ADR 0208).
## ultracode codeword
diff --git a/src/agent_compact.zig b/src/agent_compact.zig
index 8b4bc3c2..84080bbf 100644
--- a/src/agent_compact.zig
+++ b/src/agent_compact.zig
@@ -243,6 +243,7 @@ pub fn compact(self: *Agent) anyerror!usize {
// prefix, so mutating the system prompt here costs nothing extra. Root-only
// and once per session — prompts.noteSessionCompacted owns both rules.
prompts.noteSessionCompacted(self, self.arena);
+ @import("hot_context.zig").afterCompact(self); // #1333: fold latest keys into the new prefix
// A/B control arm doing work (#compact-ab): a client-side summary on the
// Responses wire. Manual /compact on codex lands here too — correctly
// labeled, since it IS a client compaction.
@@ -580,6 +581,7 @@ pub fn compactOrRecover(self: *Agent, trim_on_fail: bool) void {
// call site rather than inside emergencyTrim() because the direct
// emergencyTrim callers drive partially-initialized test agents.
prompts.noteSessionCompacted(self, self.arena);
+ @import("hot_context.zig").afterCompact(self);
if (main_mod.json_mode)
self.emit(.{ .type = "compact", .ok = true, .trimmed = dropped })
else
diff --git a/src/agent_server_compact.zig b/src/agent_server_compact.zig
index 69835102..3f604b0e 100644
--- a/src/agent_server_compact.zig
+++ b/src/agent_server_compact.zig
@@ -168,6 +168,7 @@ fn installItems(self: *Agent, items: []const std.json.Value) !void {
self.goal_note_fp = 0;
self.history_rewrites +%= 1;
session_prunes +|= 1; // manual compaction is not an A/B treatment exposure
+ @import("hot_context.zig").afterCompact(self); // #1333: the opaque item replaced history; fold latest keys
}
pub fn installCompactedOutput(self: *Agent, response: std.json.Value) !usize {
diff --git a/src/history_translate.zig b/src/history_translate.zig
new file mode 100644
index 00000000..e78766cb
--- /dev/null
+++ b/src/history_translate.zig
@@ -0,0 +1,71 @@
+//! History translation across a /model switch that changes wire format.
+//! Split out of providers.zig.
+
+const std = @import("std");
+const Allocator = std.mem.Allocator;
+const Value = std.json.Value;
+const Provider = @import("provider.zig").Provider;
+const extractText = @import("providers.zig").extractText;
+const textMessage = @import("messages.zig").textMessage;
+const hot_context = @import("hot_context.zig");
+
+/// Rebuild the history as text-only user/assistant turns in `to_kind`'s format
+/// — used to carry the conversation across a wire-format switch. Tool-call
+/// structure is dropped (the dialogue is what matters for continuity).
+/// textMessage's {role,content:string} shape is valid in all 3 formats.
+/// Hot-context updates may be developer/system-role, so they are retyped for
+/// the new wire rather than dropped; otherwise the model would fall back to
+/// the stale instructions in the system prompt.
+pub fn translateHistory(arena: Allocator, msgs: *std.json.Array, to_kind: Provider.Kind) void {
+ var out = std.json.Array.init(arena);
+ for (msgs.items) |m| {
+ if (m != .object) continue;
+ if (hot_context.isHotContext(m)) {
+ out.append(hot_context.retyped(arena, to_kind, extractText(arena, m)) catch continue) catch {};
+ continue;
+ }
+ const role = if (m.object.get("role")) |r| (if (r == .string) r.string else "") else "";
+ if (!std.mem.eql(u8, role, "user") and !std.mem.eql(u8, role, "assistant")) continue;
+ const text = std.mem.trim(u8, extractText(arena, m), " \t\r\n");
+ if (text.len == 0) continue;
+ out.append(@import("session_wake.zig").copyOrigin(arena, m, textMessage(arena, role, text) catch continue) catch continue) catch {};
+ }
+ msgs.* = out;
+}
+
+fn parse(a: Allocator, s: []const u8) Value {
+ return std.json.parseFromSliceLeaky(Value, a, s, .{}) catch unreachable;
+}
+
+test "translateHistory: flattens to {role,content:string}, keeps user/assistant, drops the rest" {
+ var arena_state = std.heap.ArenaAllocator.init(std.testing.allocator);
+ defer arena_state.deinit();
+ const a = arena_state.allocator();
+ var msgs = std.json.Array.init(a);
+ try msgs.append(parse(a, "{\"role\":\"system\",\"content\":\"sys\"}")); // dropped
+ try msgs.append(parse(a, "{\"role\":\"user\",\"content\":\"hello\"}")); // kept
+ try msgs.append(parse(a, "{\"role\":\"assistant\",\"content\":[{\"type\":\"text\",\"text\":\"hi\"}]}")); // flattened
+ try msgs.append(parse(a, "{\"role\":\"tool\",\"content\":\"result\"}")); // dropped
+ try msgs.append(parse(a, "{\"role\":\"user\",\"content\":\" \"}")); // whitespace-only -> dropped
+ translateHistory(a, &msgs, .anthropic);
+ try std.testing.expectEqual(@as(usize, 2), msgs.items.len);
+ try std.testing.expectEqualStrings("user", msgs.items[0].object.get("role").?.string);
+ try std.testing.expectEqualStrings("hello", msgs.items[0].object.get("content").?.string);
+ try std.testing.expectEqualStrings("assistant", msgs.items[1].object.get("role").?.string);
+ try std.testing.expectEqualStrings("hi", msgs.items[1].object.get("content").?.string);
+}
+
+test "translateHistory retypes a hot-context update for the new wire" {
+ var arena_state = std.heap.ArenaAllocator.init(std.testing.allocator);
+ defer arena_state.deinit();
+ const a = arena_state.allocator();
+ var msgs = std.json.Array.init(a);
+ try msgs.append(parse(a, "{\"role\":\"user\",\"content\":\"hi\"}"));
+ try msgs.append(try hot_context.retyped(a, .responses, "<context key=\"core/date\">x</context>"));
+ try std.testing.expectEqualStrings("developer", msgs.items[1].object.get("role").?.string);
+ translateHistory(a, &msgs, .anthropic);
+ try std.testing.expectEqual(@as(usize, 2), msgs.items.len);
+ try std.testing.expect(hot_context.isHotContext(msgs.items[1]));
+ try std.testing.expectEqualStrings("user", msgs.items[1].object.get("role").?.string);
+ try std.testing.expectEqualStrings("<context key=\"core/date\">x</context>", msgs.items[1].object.get("content").?.string);
+}
diff --git a/src/hot_context.zig b/src/hot_context.zig
new file mode 100644
index 00000000..818432f7
--- /dev/null
+++ b/src/hot_context.zig
@@ -0,0 +1,318 @@
+//! Hot context (#1333): ambient values that change during a live session
+//! reach the model without rewriting the cached system prefix.
+//!
+//! The root system prompt is composed once at startup (startup.zig) and the
+//! provider caches it as a prefix. Rewriting it when an instruction file
+//! changes, or the date rolls over, would throw that cache away. Instead each
+//! ambient value is a keyed source. Before a model request, a changed key is
+//! delivered as one `<context key="...">` message (a notice, not a human turn)
+//! placed just before the pending user prompt, so everything already sent
+//! stays byte-identical. Compaction already discards the cached prefix, so
+//! there the synthetic messages are dropped and the latest values are folded
+//! into a fresh system prompt.
+//!
+//! Keys:
+//! - `core/instructions`: the first of AGENTS.md / HARNESS.md / CLAUDE.md in
+//! the working directory, capped like the startup copy.
+//! - `core/date`: the UTC date. Not in the startup prompt; announced only when
+//! it changes during the session.
+
+const std = @import("std");
+const Io = std.Io;
+const Value = std.json.Value;
+const Allocator = std.mem.Allocator;
+
+pub const instruction_names = [_][]const u8{ "AGENTS.md", "HARNESS.md", "CLAUDE.md" };
+pub const origin = "hot_context";
+
+pub const Key = enum {
+ instructions,
+ date,
+ pub fn label(k: Key) []const u8 {
+ return switch (k) {
+ .instructions => "core/instructions",
+ .date => "core/date",
+ };
+ }
+};
+
+const State = struct {
+ armed: bool = false,
+ /// The exact section startup put in the system prompt (header + body),
+ /// so a later fold can replace it. Empty when no file was found.
+ baked_section: []const u8 = "",
+ /// What the model currently believes: hash of the latest delivered body.
+ believed_hash: u64 = 0,
+ /// Hash of the body inside the system prompt (0 = none baked).
+ baked_hash: u64 = 0,
+ stat_size: u64 = 0,
+ stat_mtime: i128 = 0,
+ stat_name: []const u8 = "",
+ date: [10]u8 = undefined,
+ date_len: u8 = 0,
+ /// The date the model believes, when it differs from the session start.
+ date_announced: bool = false,
+};
+
+var g: State = .{};
+var g_gpa: Allocator = std.heap.page_allocator;
+
+pub fn resetForTest() void {
+ g = .{};
+}
+
+fn section(a: Allocator, name: []const u8, body: []const u8) ![]const u8 {
+ return std.fmt.allocPrint(a, "# Project instructions (from {s})\n{s}", .{ name, body });
+}
+
+/// startup.buildSystemPrompt: the instructions it baked into the prefix.
+pub fn noteBaked(name: []const u8, body: []const u8) void {
+ g.baked_section = section(g_gpa, name, body) catch "";
+ g.believed_hash = std.hash.Wyhash.hash(0, body);
+ g.baked_hash = g.believed_hash;
+ g.armed = true;
+}
+
+/// The current instruction body (capped), or null when no file exists.
+fn currentInstructions(io: Io, a: Allocator) ?struct { name: []const u8, body: []const u8 } {
+ for (instruction_names) |name| {
+ const raw = Io.Dir.cwd().readFileAlloc(io, name, a, .limited(64 * 1024)) catch continue;
+ const trimmed = std.mem.trim(u8, raw, " \t\r\n");
+ if (trimmed.len == 0) continue;
+ const limits = @import("context_limits.zig");
+ return .{ .name = name, .body = limits.applyAlloc(a, trimmed, limits.agents_md_bytes) };
+ }
+ return null;
+}
+
+/// Cheap change probe: size + mtime of whichever instruction file exists.
+fn instructionsTouched(io: Io) bool {
+ for (instruction_names) |name| {
+ const st = Io.Dir.cwd().statFile(io, name, .{}) catch continue;
+ const mtime: i128 = st.mtime.nanoseconds;
+ const touched = st.size != g.stat_size or mtime != g.stat_mtime or !std.mem.eql(u8, name, g.stat_name);
+ g.stat_size = st.size;
+ g.stat_mtime = mtime;
+ g.stat_name = name;
+ return touched;
+ }
+ const had = g.stat_name.len > 0;
+ g.stat_name = "";
+ g.stat_size = 0;
+ return had;
+}
+
+pub fn utcDate(buf: *[10]u8, unix_ms: i64) []const u8 {
+ const es: std.time.epoch.EpochSeconds = .{ .secs = @intCast(@max(0, @divFloor(unix_ms, 1000))) };
+ const yd = es.getEpochDay().calculateYearDay();
+ const md = yd.calculateMonthDay();
+ return std.fmt.bufPrint(buf, "{d:0>4}-{d:0>2}-{d:0>2}", .{ yd.year, md.month.numeric(), md.day_index + 1 }) catch buf[0..0];
+}
+
+pub const Update = struct { key: Key, text: []const u8 };
+
+/// Changed keys since the model last saw them, as ready-to-send text.
+/// `now_ms` is injected so tests can roll the date.
+pub fn collect(io: Io, a: Allocator, now_ms: i64, out: *std.ArrayList(Update)) !void {
+ var buf: [10]u8 = undefined;
+ const today = utcDate(&buf, now_ms);
+ if (g.date_len == 0) {
+ @memcpy(g.date[0..today.len], today);
+ g.date_len = @intCast(today.len);
+ } else if (!std.mem.eql(u8, g.date[0..g.date_len], today)) {
+ @memcpy(g.date[0..today.len], today);
+ g.date_len = @intCast(today.len);
+ g.date_announced = true;
+ try out.append(a, .{ .key = .date, .text = try std.fmt.allocPrint(a, "<context key=\"core/date\">\nThe date is now {s} (UTC).\n</context>", .{today}) });
+ }
+ if (!g.armed) {
+ // Startup found no instruction file (or ran without the funnel):
+ // track from here so a file created later is still delivered.
+ g.armed = true;
+ _ = instructionsTouched(io);
+ if (currentInstructions(io, a)) |cur| g.believed_hash = std.hash.Wyhash.hash(0, cur.body);
+ g.baked_hash = g.believed_hash;
+ return;
+ }
+ if (!instructionsTouched(io)) return;
+ const cur = currentInstructions(io, a);
+ const hash: u64 = if (cur) |c| std.hash.Wyhash.hash(0, c.body) else 0;
+ if (hash == g.believed_hash) return;
+ g.believed_hash = hash;
+ const text = if (cur) |c|
+ try std.fmt.allocPrint(a, "<context key=\"core/instructions\" source=\"{s}\">\nThe project instructions changed during this session. This version replaces the one in the system prompt.\n\n{s}\n</context>", .{ c.name, c.body })
+ else
+ try a.dupe(u8, "<context key=\"core/instructions\">\nThe project instructions file was removed during this session. The version in the system prompt no longer applies.\n</context>");
+ try out.append(a, .{ .key = .instructions, .text = text });
+}
+
+pub fn isHotContext(m: Value) bool {
+ if (m != .object) return false;
+ const v = m.object.get(@import("session_wake.zig").origin_key) orelse return false;
+ return v == .string and std.mem.eql(u8, v.string, origin);
+}
+
+fn isHumanPrompt(m: Value) bool {
+ if (m != .object) return false;
+ if (@import("session_wake.zig").isNotice(m)) return false;
+ return @import("messages.zig").userPromptText(m) != null;
+}
+
+/// The role an update needs to be obeyed over the startup system prompt.
+/// A user-role message ranks below system/developer instructions (a live
+/// gpt-6-sol run kept following the old AGENTS.md rule), so wires that
+/// accept a mid-conversation instruction message get one: Responses takes
+/// `developer`, Chat Completions `system`. Anthropic and Interactions have
+/// no mid-thread system role; the update rides as user text there.
+pub fn roleFor(kind: @import("provider.zig").Provider.Kind) []const u8 {
+ return switch (kind) {
+ .responses => "developer",
+ .openai => "system",
+ .anthropic, .interactions => "user",
+ };
+}
+
+fn typedUpdate(a: Allocator, kind: @import("provider.zig").Provider.Kind, text: []const u8) !Value {
+ if (kind == .interactions) return @import("session_wake.zig").typedMessage(a, kind, text);
+ return @import("messages.zig").textMessage(a, roleFor(kind), text);
+}
+
+/// An update message for `kind`, tagged as hot context. Also used when a
+/// /model switch changes wire format (providers.translateHistory).
+pub fn retyped(a: Allocator, kind: @import("provider.zig").Provider.Kind, text: []const u8) !Value {
+ var msg = try typedUpdate(a, kind, text);
+ try msg.object.put(a, @import("session_wake.zig").origin_key, .{ .string = origin });
+ return msg;
+}
+
+/// Before a model request (turn_inbox.deliver): send changed keys. Root only.
+pub fn deliver(self: anytype) void {
+ if (self.sub) return;
+ var updates: std.ArrayList(Update) = .empty;
+ collect(self.io, self.arena, @import("util.zig").unixMs(self.io), &updates) catch return;
+ for (updates.items) |u| {
+ const msg = retyped(self.arena, self.provider.kind, u.text) catch continue;
+ // Just before the pending human prompt, so it reads as current;
+ // everything already sent keeps its bytes either way.
+ const items = self.messages.items;
+ if (items.len > 0 and isHumanPrompt(items[items.len - 1]))
+ self.messages.insert(items.len - 1, msg) catch continue
+ else
+ self.messages.append(msg) catch continue;
+ @import("prompt_cache_hud.zig").noteHot(u.key.label());
+ @import("engine_sink.zig").forAgent(self).emit(self.io, .{ .session_notice = .{ .text = u.key.label(), .tone = .dim } });
+ }
+}
+
+/// The system base with the latest keyed values folded in.
+pub fn foldedBase(a: Allocator, base: []const u8, latest: ?[]const u8, date: ?[]const u8) ![]const u8 {
+ var out = base;
+ if (latest) |section_now| {
+ if (g.baked_section.len > 0 and std.mem.indexOf(u8, out, g.baked_section) != null)
+ out = try std.mem.replaceOwned(u8, a, out, g.baked_section, section_now)
+ else if (section_now.len > 0)
+ out = try std.fmt.allocPrint(a, "{s}\n\n{s}", .{ out, section_now });
+ } else if (g.baked_section.len > 0) {
+ out = try std.mem.replaceOwned(u8, a, out, g.baked_section, "");
+ }
+ if (date) |d| {
+ const marker = "\n\n# Current date (UTC)\n";
+ if (std.mem.indexOf(u8, out, marker)) |at| {
+ out = try std.fmt.allocPrint(a, "{s}{s}{s}", .{ out[0..at], marker, d });
+ } else out = try std.fmt.allocPrint(a, "{s}{s}{s}", .{ out, marker, d });
+ }
+ return out;
+}
+
+/// After compaction: the cached prefix is gone, so drop the synthetic
+/// messages and bake the latest values into the system prompt.
+/// The update messages are not a reliable signal: the summary's working set
+/// usually drops them already, so the fold compares the file against what
+/// the prompt holds.
+pub fn afterCompact(self: anytype) void {
+ if (self.sub) return;
+ var i: usize = 0;
+ while (i < self.messages.items.len) {
+ if (isHotContext(self.messages.items[i])) _ = self.messages.orderedRemove(i) else i += 1;
+ }
+ if (self.sys_base.len == 0) return; // never went through the prompt funnel
+ const cur = currentInstructions(self.io, self.arena);
+ const hash: u64 = if (cur) |c| std.hash.Wyhash.hash(0, c.body) else 0;
+ if (hash == g.baked_hash and !g.date_announced) return;
+ const section_now: ?[]const u8 = if (cur) |c| section(self.arena, c.name, c.body) catch return else null;
+ const date: ?[]const u8 = if (g.date_announced) g.date[0..g.date_len] else null;
+ const base = foldedBase(self.arena, self.sys_base, section_now, date) catch return;
+ @import("prompts.zig").setSystemPrompts(self, base, self.arena) catch return;
+ g.baked_section = if (section_now) |s| g_gpa.dupe(u8, s) catch "" else "";
+ g.baked_hash = hash;
+ g.believed_hash = hash;
+ // Rehydrate the stat probe so the fold is not re-announced next turn.
+ _ = instructionsTouched(self.io);
+}
+
+const testing = std.testing;
+
+test "utcDate formats the UTC calendar day" {
+ var buf: [10]u8 = undefined;
+ try testing.expectEqualStrings("1970-01-01", utcDate(&buf, 0));
+ try testing.expectEqualStrings("2026-09-27", utcDate(&buf, 1_790_500_000_000));
+}
+
+fn dateUpdates(list: []const Update) usize {
+ var n: usize = 0;
+ for (list) |u| if (u.key == .date) {
+ n += 1;
+ };
+ return n;
+}
+
+test "collect announces a date rollover once and nothing on the first day" {
+ resetForTest();
+ defer resetForTest();
+ g.armed = true;
+ var arena = std.heap.ArenaAllocator.init(testing.allocator);
+ defer arena.deinit();
+ const a = arena.allocator();
+ var out: std.ArrayList(Update) = .empty;
+ const day: i64 = 86_400_000;
+ try collect(testing.io, a, 20_000 * day, &out);
+ try testing.expectEqual(@as(usize, 0), dateUpdates(out.items));
+ try collect(testing.io, a, 20_000 * day + 5000, &out);
+ try testing.expectEqual(@as(usize, 0), dateUpdates(out.items));
+ try collect(testing.io, a, 20_001 * day, &out);
+ try testing.expectEqual(@as(usize, 1), dateUpdates(out.items));
+ for (out.items) |u| if (u.key == .date) try testing.expect(std.mem.indexOf(u8, u.text, "key=\"core/date\"") != null);
+ try collect(testing.io, a, 20_001 * day + 1, &out);
+ try testing.expectEqual(@as(usize, 1), dateUpdates(out.items));
+}
+
+test "foldedBase replaces the baked instructions and adds the date" {
+ resetForTest();
+ defer resetForTest();
+ var arena = std.heap.ArenaAllocator.init(testing.allocator);
+ defer arena.deinit();
+ const a = arena.allocator();
+ g_gpa = a;
+ defer g_gpa = std.heap.page_allocator;
+ noteBaked("AGENTS.md", "use tabs");
+ const base = "You are graff.\n\n# Project instructions (from AGENTS.md)\nuse tabs\n\nskills";
+ const folded = try foldedBase(a, base, "# Project instructions (from AGENTS.md)\nuse spaces", "2026-09-28");
+ try testing.expect(std.mem.indexOf(u8, folded, "use spaces") != null);
+ try testing.expect(std.mem.indexOf(u8, folded, "use tabs") == null);
+ try testing.expect(std.mem.endsWith(u8, folded, "\n\n# Current date (UTC)\n2026-09-28"));
+ try testing.expect(std.mem.indexOf(u8, folded, "skills") != null);
+ const again = try foldedBase(a, folded, null, "2026-09-29");
+ try testing.expect(std.mem.endsWith(u8, again, "# Current date (UTC)\n2026-09-29"));
+ try testing.expectEqual(@as(usize, 1), std.mem.count(u8, again, "# Current date"));
+}
+
+test "a hot context message is a notice with its own origin" {
+ var arena = std.heap.ArenaAllocator.init(testing.allocator);
+ defer arena.deinit();
+ const a = arena.allocator();
+ var msg = try @import("session_wake.zig").typedMessage(a, .openai, "<context key=\"core/date\">x</context>");
+ try msg.object.put(a, @import("session_wake.zig").origin_key, .{ .string = origin });
+ try testing.expect(isHotContext(msg));
+ try testing.expect(@import("session_wake.zig").isNotice(msg));
+ try testing.expect(!isHumanPrompt(msg));
+}
diff --git a/src/main.zig b/src/main.zig
index 448a6f04..3de98e9f 100644
--- a/src/main.zig
+++ b/src/main.zig
@@ -579,7 +579,7 @@ test { // ── Unit tests (`zig build test`): pull in tests from imported modu
_ = .{ @import("http2_pool.zig"), @import("agent_stream_h2.zig"), @import("agent_stream_h2_transport_test.zig") }; // h2 stream path, and graff's request/response contract over the pinned http-zig
_ = @import("tui_acp_updates.zig");
_ = @import("acp_preauth.zig"); // credential-free ACP loop must stay in the test root
- _ = .{ @import("acp_protocol.zig"), @import("acp_v2.zig"), @import("acp_v2_prompt.zig"), @import("acp_elicit.zig"), @import("ask_user_args.zig"), @import("acp_engine_test.zig"), @import("subagent_mimo_tests.zig"), @import("mimo_effort_tests.zig"), @import("gateway_picker_catalog.zig") };
+ _ = .{ @import("acp_protocol.zig"), @import("acp_v2.zig"), @import("acp_v2_prompt.zig"), @import("acp_elicit.zig"), @import("hot_context.zig"), @import("history_translate.zig"), @import("ask_user_args.zig"), @import("acp_engine_test.zig"), @import("subagent_mimo_tests.zig"), @import("mimo_effort_tests.zig"), @import("gateway_picker_catalog.zig") };
_ = @import("task_outcome.zig"); // goal-outcome telemetry events
_ = @import("learn_delete.zig"); // #303: its tests were dead until listed here
_ = .{ @import("additional_tests.zig"), @import("req_stats.zig"), @import("exact_reply.zig"), @import("rlm_order_tests.zig"), @import("async_tool_policy.zig"), @import("agent_async_tools.zig"), @import("request_usage_attempts.zig"), @import("learn_formal.zig") };
diff --git a/src/prompt_cache_hud.zig b/src/prompt_cache_hud.zig
index 13f70330..20bc931f 100644
--- a/src/prompt_cache_hud.zig
+++ b/src/prompt_cache_hud.zig
@@ -36,8 +36,19 @@ pub const Snap = struct {
last_bust: Bust = .none,
last_read: u64 = 0,
last_write: u64 = 0,
+ /// #1333: keyed context updates delivered without touching the prefix.
+ hot_updates: u32 = 0,
+ last_hot: []const u8 = "",
};
+/// A hot-context key update (static label). Not a bust: the prefix is kept.
+pub fn noteHot(key: []const u8) void {
+ acquire();
+ defer release();
+ snap.hot_updates += 1;
+ snap.last_hot = key;
+}
+
var lock: std.atomic.Value(bool) = .init(false);
var snap: Snap = .{};
var pending: Bust = .none;
@@ -200,6 +211,7 @@ pub fn render(w: *Io.Writer) !void {
}
try w.writeByte('\n');
try w.print(" busts {d} last: {s}\n", .{ s.busts, bustLabel(s.last_bust) });
+ if (s.hot_updates > 0) try w.print(" hot ctx {d} update{s} last: {s} (appended; prefix {s})\n", .{ s.hot_updates, if (s.hot_updates == 1) "" else "s", s.last_hot, if (s.same) "kept" else "changed" });
}
try w.print(" catalog {s}\n", .{if (mcp_schema_gate.g_stable_catalog) "stable (loads append tail only)" else "mutating (a load rewrites tools JSON)"});
if (g_xai and g_aff_len > 0) {
@@ -314,6 +326,20 @@ test "render stays content-free and names remaining levers" {
try std.testing.expect(!contains(text, "bash"));
}
+test "hot context updates show in render with the prefix kept" {
+ reset();
+ defer reset();
+ noteRequest(std.testing.io, "system", "[]");
+ noteHot("core/instructions");
+ noteRequest(std.testing.io, "system", "[]");
+ var buf: [2048]u8 = undefined;
+ var w: Io.Writer = .fixed(&buf);
+ try render(&w);
+ const text = w.buffered();
+ try std.testing.expect(contains(text, "hot ctx 1 update last: core/instructions (appended; prefix kept)"));
+ try std.testing.expectEqual(@as(u32, 0), snapshot().busts);
+}
+
test "render shows xAI affinity without prompt text" {
reset();
defer reset();
diff --git a/src/providers.zig b/src/providers.zig
index 0775b7a5..bf836b97 100644
--- a/src/providers.zig
+++ b/src/providers.zig
@@ -19,7 +19,6 @@ const router_catalog = @import("router_catalog.zig");
const serde = @import("serde.zig");
const saveModel = serde.saveModel;
const messages_mod = @import("messages.zig");
-const textMessage = messages_mod.textMessage;
const engine_sink = @import("engine_sink.zig"); // #429: the failover notice is a typed event, not a print
const fallback_config = @import("fallback_config.zig");
const util = @import("util.zig");
@@ -55,23 +54,6 @@ pub fn extractText(arena: Allocator, m: Value) []const u8 {
return b.items;
}
-/// Rebuild the history as text-only user/assistant turns in `to_kind`'s format
-/// — used to carry the conversation across a wire-format switch. Tool-call
-/// structure is dropped (the dialogue is what matters for continuity).
-fn translateHistory(arena: Allocator, msgs: *std.json.Array, to_kind: Provider.Kind) void {
- _ = to_kind; // textMessage's {role,content:string} shape is valid in all 3 formats
- var out = std.json.Array.init(arena);
- for (msgs.items) |m| {
- if (m != .object) continue;
- const role = if (m.object.get("role")) |r| (if (r == .string) r.string else "") else "";
- if (!std.mem.eql(u8, role, "user") and !std.mem.eql(u8, role, "assistant")) continue;
- const text = std.mem.trim(u8, extractText(arena, m), " \t\r\n");
- if (text.len == 0) continue;
- out.append(@import("session_wake.zig").copyOrigin(arena, m, textMessage(arena, role, text) catch continue) catch continue) catch {};
- }
- msgs.* = out;
-}
-
pub fn applyProviderInner(root: *Agent, arena: Allocator, p: Provider, persist: bool) ![]const u8 {
const same_format = root.provider.kind == p.kind;
const same_selection = same_format and
@@ -82,7 +64,7 @@ pub fn applyProviderInner(root: *Agent, arena: Allocator, p: Provider, persist:
var note: []const u8 = "context kept";
if (!same_format) {
if (root.keep_context) {
- translateHistory(arena, &root.messages, p.kind);
+ @import("history_translate.zig").translateHistory(arena, &root.messages, p.kind);
note = "context translated & kept";
} else {
root.messages = std.json.Array.init(arena);
@@ -464,29 +446,6 @@ test "nextFallbackProvider: rotates after the failed provider and skips missing
try std.testing.expectEqualStrings("codegraff", nextFallbackProvider(sparse, "codex", &tried_codex, &allow_codegraff).?.id);
}
-test "translateHistory: flattens to {role,content:string}, keeps user/assistant, drops the rest" {
- var arena_state = std.heap.ArenaAllocator.init(std.testing.allocator);
- defer arena_state.deinit();
- const a = arena_state.allocator();
- const mk = struct {
- fn p(al: Allocator, s: []const u8) Value {
- return std.json.parseFromSliceLeaky(Value, al, s, .{}) catch unreachable;
- }
- }.p;
- var msgs = std.json.Array.init(a);
- try msgs.append(mk(a, "{\"role\":\"system\",\"content\":\"sys\"}")); // dropped
- try msgs.append(mk(a, "{\"role\":\"user\",\"content\":\"hello\"}")); // kept
- try msgs.append(mk(a, "{\"role\":\"assistant\",\"content\":[{\"type\":\"text\",\"text\":\"hi\"}]}")); // flattened
- try msgs.append(mk(a, "{\"role\":\"tool\",\"content\":\"result\"}")); // dropped
- try msgs.append(mk(a, "{\"role\":\"user\",\"content\":\" \"}")); // whitespace-only -> dropped
- translateHistory(a, &msgs, .anthropic);
- try std.testing.expectEqual(@as(usize, 2), msgs.items.len);
- try std.testing.expectEqualStrings("user", msgs.items[0].object.get("role").?.string);
- try std.testing.expectEqualStrings("hello", msgs.items[0].object.get("content").?.string);
- try std.testing.expectEqualStrings("assistant", msgs.items[1].object.get("role").?.string);
- try std.testing.expectEqualStrings("hi", msgs.items[1].object.get("content").?.string);
-}
-
test "applyProviderInner preserves the server meter on an exact model re-selection" {
var arena_state = std.heap.ArenaAllocator.init(std.testing.allocator);
defer arena_state.deinit();
diff --git a/src/session_wake.zig b/src/session_wake.zig
index d5e2e7e4..22c4fcb2 100644
--- a/src/session_wake.zig
+++ b/src/session_wake.zig
@@ -19,7 +19,8 @@ pub const origin_key = "_graff_origin";
pub fn isNotice(m: std.json.Value) bool {
if (m != .object) return false;
const v = m.object.get(origin_key) orelse return false;
- return v == .string and std.mem.eql(u8, v.string, "notification");
+ // #1333: hot-context updates are notices too, with their own origin.
+ return v == .string and (std.mem.eql(u8, v.string, "notification") or std.mem.eql(u8, v.string, "hot_context"));
}
pub fn message(a: std.mem.Allocator, text: []const u8) !std.json.Value {
return mark(a, try @import("messages.zig").textMessage(a, "user", text));
diff --git a/src/startup.zig b/src/startup.zig
index f04a0499..ecff8cc5 100644
--- a/src/startup.zig
+++ b/src/startup.zig
@@ -109,6 +109,7 @@ pub fn buildSystemPrompt(
if (trimmed.len == 0) continue;
const capped = @import("context_limits.zig").applyAlloc(arena, trimmed, @import("context_limits.zig").agents_md_bytes);
sys_normal = try std.fmt.allocPrint(arena, "{s}\n\n# Project instructions (from {s})\n{s}", .{ base_prompt, fname, capped });
+ @import("hot_context.zig").noteBaked(fname, capped); // #1333: later edits arrive as keyed updates
if (!quiet) {
try out.print("loaded project instructions from {s} ({d} bytes)\n", .{ fname, trimmed.len });
try out.flush();
diff --git a/src/turn_inbox.zig b/src/turn_inbox.zig
index b983a877..fe60d97d 100644
--- a/src/turn_inbox.zig
+++ b/src/turn_inbox.zig
@@ -16,6 +16,7 @@ pub fn deliver(self: *Agent) !void {
@import("job_notify.zig").deliver(self);
@import("schedule.zig").deliver(self);
@import("channel_worker.zig").deliver(self);
+ @import("hot_context.zig").deliver(self); // #1333: changed ambient keys, before the prompt
deliverSteer(self);
}