Skip to content

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

Python

DeepSeek: loaded tools ride a user message, tools stays frozen

justrachccffb9c2833b
diff --git a/docs/adr/0221-chatgpt-new-sign-in.md b/docs/adr/0221-chatgpt-new-sign-in.md
index 317eb1ef..08fc3a9d 100644
--- a/docs/adr/0221-chatgpt-new-sign-in.md
+++ b/docs/adr/0221-chatgpt-new-sign-in.md
@@ -154,6 +154,21 @@ process rather than restarting anything.
tools and returns an announced tool's values as strings (`"5"`,
`"[\"a\"]"`); `tool_call_repair.retypeArgs` restores their schema types.
Other chat providers keep the tail until each is checked the same way.
+- **DeepSeek announces loaded tools in a user message.** DeepSeek renders
+ `tools` after the system prompt and before the messages, so a load
+ re-billed the whole conversation. Its cache only hits up to a point an
+ earlier request ended or split, so the first request after a load often
+ kept little beyond the system prompt. A system announcement would be
+ worse. V4 Pro's template moves every system message up into the system
+ prompt, so an appended one re-billed the tools as well. A user message
+ renders where it was appended and kept the full cache on V4 Pro and V4
+ Flash. The model called an announced tool with typed arguments on every
+ try, as it does a declared one. So DeepSeek's announcement is a user
+ message. Its tag makes it a notice (`session_wake.isNotice`), so `/edit`,
+ ACP replay and prompt lookups never take it for a prompt, and the TUI
+ transcript leaves it out. A wire change drops it (`history_translate`).
+ Hot-context updates still ride a system message on chat wires, so on
+ DeepSeek each project-instructions change costs one miss.
- **The first request carries every MCP server that is ready.** `-p` starts
MCP in the background and never waits out a handshake (ADR 0035). A server
restored from cache was ready before the first request, but that request
diff --git a/src/additional_tools.zig b/src/additional_tools.zig
index af421fa3..c8ba9920 100644
--- a/src/additional_tools.zig
+++ b/src/additional_tools.zig
@@ -17,6 +17,14 @@
//! only for declared tools, so tool_call_repair.retypeArgs restores the
//! announced tools' argument types.
//!
+//! DeepSeek renders `tools` right after the system prompt, so a load re-bills
+//! every message. A system announcement would not help there: V4 Pro's template
+//! moves every system message up into the system prompt, which also re-bills
+//! the tools. A user message stays where it was appended, so on DeepSeek the
+//! announcement is user-role. Its tag makes it a notice, never a prompt
+//! (session_wake.isNotice). The model calls announced tools with typed
+//! arguments, as it does declared ones.
+//!
//! So on these routes the tail never reaches `tools`, and before each request
//! `sync` announces every loaded tool that no announcement in the history
//! carries yet: once per tool, and again only if compaction pruned it.
@@ -41,11 +49,18 @@ pub fn active(p: Provider) bool {
if (!mcp_schema_gate.g_stable_catalog) return false;
return switch (p.kind) {
.responses => std.mem.eql(u8, p.id, "chatgpt-new"),
- .openai => @import("effort_route.zig").mimoRoute(p.id, p.model),
+ .openai => @import("effort_route.zig").mimoRoute(p.id, p.model) or deepseekRoute(p),
.anthropic, .interactions => false,
};
}
+/// DeepSeek models, direct or through Codegraff.
+fn deepseekRoute(p: Provider) bool {
+ const name = if (std.mem.lastIndexOfScalar(u8, p.model, '/')) |slash| p.model[slash + 1 ..] else p.model;
+ return (std.mem.eql(u8, p.id, "deepseek") or std.mem.eql(u8, p.id, "codegraff")) and
+ std.ascii.startsWithIgnoreCase(name, "deepseek-");
+}
+
/// The loaded tail as tool entries for the agent's wire: exactly what the
/// stable catalog would append to `tools`.
fn tailEntries(self: *Agent, arena: Allocator) ![]const Value {
@@ -109,15 +124,16 @@ pub fn sync(self: *Agent) void {
var fresh = std.json.Array.init(arena);
for (tail) |t| if (!announced(arena, self.messages.items, toolName(t))) fresh.append(t) catch return;
if (fresh.items.len == 0) return;
- const item = announcement(arena, self.provider.kind, fresh) catch return;
+ const item = announcement(arena, self.provider, fresh) catch return;
self.messages.append(item) catch {};
}
/// A developer-role `additional_tools` item on Responses. The chat wire has no
-/// such item, so there it is a system message with one definition per line.
-fn announcement(arena: Allocator, kind: Provider.Kind, tools: std.json.Array) !Value {
+/// such item, so there it is a message with one definition per line: system
+/// on MiMo, user on DeepSeek.
+fn announcement(arena: Allocator, p: Provider, tools: std.json.Array) !Value {
var item: std.json.ObjectMap = .empty;
- if (kind == .responses) {
+ if (p.kind == .responses) {
try item.put(arena, "type", .{ .string = item_type });
try item.put(arena, "role", .{ .string = "developer" });
try item.put(arena, "tools", .{ .array = tools });
@@ -127,7 +143,7 @@ fn announcement(arena: Allocator, kind: Provider.Kind, tools: std.json.Array) !V
try aw.writer.writeAll(chat_header);
for (tools.items) |t| try aw.writer.print("{s}\n", .{try std.json.Stringify.valueAlloc(arena, t, .{})});
try aw.writer.writeAll("</tools>");
- try item.put(arena, "role", .{ .string = "system" });
+ try item.put(arena, "role", .{ .string = if (deepseekRoute(p)) "user" else "system" });
try item.put(arena, "content", .{ .string = aw.writer.buffered() });
try item.put(arena, origin_key, .{ .string = item_type });
return .{ .object = item };
diff --git a/src/additional_tools_tests.zig b/src/additional_tools_tests.zig
index a3a0e9ef..3ee70cad 100644
--- a/src/additional_tools_tests.zig
+++ b/src/additional_tools_tests.zig
@@ -1,6 +1,6 @@
//! Tests for additional_tools.zig (ADR 0221): a load on the ChatGPT plan
-//! route or MiMo's chat wire must leave `tools` byte-identical and announce
-//! the tool in the conversation instead.
+//! route or on MiMo's or DeepSeek's chat wire must leave `tools`
+//! byte-identical and announce the tool in the conversation instead.
const std = @import("std");
const additional_tools = @import("additional_tools.zig");
@@ -167,7 +167,58 @@ test "MiMo chat: a tool load leaves tools byte-identical and adds one system ann
_ = agent.messages.pop();
additional_tools.sync(&agent);
try std.testing.expectEqual(@as(usize, 1), items(agent.messages.items));
- agent.provider.model = "deepseek-v4-pro";
+ agent.provider.model = "glm-5.3";
additional_tools.sync(&agent);
try std.testing.expectEqual(@as(usize, 0), items(agent.messages.items));
}
+
+test "DeepSeek chat: a tool load leaves tools byte-identical and adds one user announcement that is not a prompt" {
+ var arena_state = std.heap.ArenaAllocator.init(std.testing.allocator);
+ defer arena_state.deinit();
+ const a = arena_state.allocator();
+ const saved_fold = native_fold.enabled;
+ const saved_stable = mcp_schema_gate.g_stable_catalog;
+ defer {
+ native_fold.enabled = saved_fold;
+ mcp_schema_gate.g_stable_catalog = saved_stable;
+ native_fold.clearLoadedSession();
+ }
+ native_fold.enabled = true;
+ mcp_schema_gate.g_stable_catalog = true;
+
+ // DeepSeek's own API and the gateway, Pro and Flash.
+ for ([_][2][]const u8{ .{ "deepseek", "deepseek-v4-pro" }, .{ "codegraff", "deepseek-v4-flash" } }) |route| {
+ native_fold.clearLoadedSession();
+ var agent = try testAgentFor(a, route[0], .openai, route[1]);
+ try std.testing.expect(additional_tools.active(agent.provider));
+ agent.invalidateRootTools();
+ try agent.ensureRootTools(.openai);
+ const before = try agent.buildBody(agent.tools_openai, false, true, true);
+ defer std.testing.allocator.free(before);
+
+ native_fold.markLoaded("workflow");
+ agent.invalidateRootTools();
+ try agent.ensureRootTools(.openai);
+ additional_tools.sync(&agent);
+ try std.testing.expectEqual(@as(usize, 1), items(agent.messages.items));
+ const note = agent.messages.items[agent.messages.items.len - 1];
+ // User-role: DeepSeek moves system messages up into the system prompt.
+ try std.testing.expectEqualStrings("user", note.object.get("role").?.string);
+ try std.testing.expect(std.mem.indexOf(u8, note.object.get("content").?.string, "\"name\":\"workflow\"") != null);
+ // Harness text, not something the human typed.
+ try std.testing.expect(@import("messages.zig").userPromptText(note) == null);
+ try std.testing.expect(@import("session_wake.zig").isNotice(note));
+ const after = try agent.buildBody(agent.tools_openai, false, true, true);
+ defer std.testing.allocator.free(after);
+
+ try std.testing.expect(chatToolsOf(before).len > 2);
+ try std.testing.expectEqualStrings(chatToolsOf(before), chatToolsOf(after));
+ try std.testing.expect(std.mem.indexOf(u8, after, "_graff_origin") == null);
+
+ // A switch to another wire drops the announcement rather than carrying it as text.
+ var msgs = agent.messages;
+ @import("history_translate.zig").translateHistory(a, &msgs, .anthropic);
+ try std.testing.expectEqual(@as(usize, 0), items(msgs.items));
+ for (msgs.items) |m| try std.testing.expect(std.mem.indexOf(u8, try std.json.Stringify.valueAlloc(a, m, .{}), "workflow") == null);
+ }
+}
diff --git a/src/agent_request_body.zig b/src/agent_request_body.zig
index 467dd29b..f4079083 100644
--- a/src/agent_request_body.zig
+++ b/src/agent_request_body.zig
@@ -147,7 +147,7 @@ pub fn buildBody(self: *Agent, tools_in: ?[]const u8, force_tool: bool, stream:
}
}
if (tools) |t| {
- // ADR 0221: on MiMo the loaded tail rides a system message instead (additional_tools.zig).
+ // ADR 0221: on MiMo and DeepSeek the loaded tail rides a message instead (additional_tools.zig).
const at = @import("additional_tools.zig");
try s.objectField("tools");
// #261 follow-up: the rest need the root-schema repair too.
diff --git a/src/history_translate.zig b/src/history_translate.zig
index e78766cb..283dd8e3 100644
--- a/src/history_translate.zig
+++ b/src/history_translate.zig
@@ -20,6 +20,8 @@ pub fn translateHistory(arena: Allocator, msgs: *std.json.Array, to_kind: Provid
var out = std.json.Array.init(arena);
for (msgs.items) |m| {
if (m != .object) continue;
+ // The new route announces loaded tools its own way, or not at all (ADR 0221).
+ if (@import("additional_tools.zig").isItem(m)) continue;
if (hot_context.isHotContext(m)) {
out.append(hot_context.retyped(arena, to_kind, extractText(arena, m)) catch continue) catch {};
continue;
diff --git a/src/mcp_schema_gate_tests.zig b/src/mcp_schema_gate_tests.zig
index 927264a2..ec80d1a2 100644
--- a/src/mcp_schema_gate_tests.zig
+++ b/src/mcp_schema_gate_tests.zig
@@ -419,8 +419,8 @@ test "mixed native MCP loads preserve earlier emitted tool entries" {
const loaded = try gate.loadInto(a, fat, load);
try testing.expectEqual(@as(usize, 1), loaded.loaded);
const routes = [_]struct { id: []const u8, kind: @import("provider.zig").Provider.Kind, model: []const u8 }{
- // MiMo sends the loaded tail as a system message instead (additional_tools_tests.zig).
- .{ .id = "deepseek", .kind = .openai, .model = "deepseek-v4-pro" },
+ // MiMo and DeepSeek send the loaded tail as a message instead (additional_tools_tests.zig).
+ .{ .id = "zai", .kind = .openai, .model = "glm-5.3" },
.{ .id = "xai", .kind = .responses, .model = "grok-4.6" },
.{ .id = "codex", .kind = .responses, .model = "gpt-6-sol" },
};
diff --git a/src/session_wake.zig b/src/session_wake.zig
index 36964405..fef87443 100644
--- a/src/session_wake.zig
+++ b/src/session_wake.zig
@@ -19,8 +19,10 @@ 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;
- // #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"));
+ // #1333: hot-context updates are notices too, with their own origin. So are
+ // loaded-tool announcements, which DeepSeek gets user-role (ADR 0221).
+ return v == .string and (std.mem.eql(u8, v.string, "notification") or std.mem.eql(u8, v.string, "hot_context") or
+ std.mem.eql(u8, v.string, @import("additional_tools.zig").item_type));
}
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/tui_session.zig b/src/tui_session.zig
index 132f1129..36708f97 100644
--- a/src/tui_session.zig
+++ b/src/tui_session.zig
@@ -23,6 +23,7 @@ pub fn syncRoot(convo: *repl_glue.Conversation, root: *agent_mod.Agent) !void {
pub fn visibleTurns(arena: Allocator, messages: std.json.Array) ![]tui.Turn {
var turns: std.ArrayList(tui.Turn) = .empty;
for (messages.items) |message| {
+ if (@import("additional_tools.zig").isItem(message)) continue; // tool definitions for the model, not a turn
const role = visibleRole(message) orelse continue;
const text = try visibleText(arena, message);
if (text.len == 0) continue;