diff options
| author | t <t@tjp.lol> | 2026-06-13 12:22:18 -0600 |
|---|---|---|
| committer | t <t@tjp.lol> | 2026-06-15 15:08:32 -0600 |
| commit | eb19fd812e15de5a6930daf2fcd0b2b0757687c7 (patch) | |
| tree | ace85c641e48836fe45b289141213fe8984ccb52 /libpanto/src/openai_responses_json.zig | |
| parent | 9f983c5d0ecc1c12f15eadf1add123e24995b660 (diff) | |
auth: openai_responses provider for Codex subscription (Tier 2)
Add the OpenAI Responses API wire dialect (openai_responses APIStyle +
OpenAIResponsesConfig), a request serializer (instructions/input items,
flat function tools, reasoning, store:false, include encrypted reasoning),
and a streaming state machine over the typed response.* SSE events mapping
to the shared block model. Wire dispatch, buildProviderConfig, the C-ABI
free switch, and the reasoning selectors. Ship a commented Codex example in
the default config.
Implemented from the Responses API docs + the open-source Codex client and
covered by fixture tests; live verification against a ChatGPT plan is still
required (documented).
Diffstat (limited to 'libpanto/src/openai_responses_json.zig')
| -rw-r--r-- | libpanto/src/openai_responses_json.zig | 582 |
1 files changed, 582 insertions, 0 deletions
diff --git a/libpanto/src/openai_responses_json.zig b/libpanto/src/openai_responses_json.zig new file mode 100644 index 0000000..8ff7712 --- /dev/null +++ b/libpanto/src/openai_responses_json.zig @@ -0,0 +1,582 @@ +//! OpenAI Responses API JSON serialization and streaming-event parsing. +//! +//! The Responses API (`POST /responses`) backs the ChatGPT-subscription Codex +//! provider. Its wire shape differs from Chat Completions: +//! +//! - The system prompt rides in a top-level `instructions` string. +//! - History is an `input` array of items: `{role, content:[{type, text}]}` +//! messages, `{type:"function_call", call_id, name, arguments}` for +//! assistant tool calls, and `{type:"function_call_output", call_id, +//! output}` for tool results. +//! - Tools are flat: `{type:"function", name, description, parameters}`. +//! - Reasoning is requested via `{reasoning:{effort, summary}}` and +//! `include:["reasoning.encrypted_content"]`; `store:false` keeps the +//! exchange stateless. +//! - Streaming uses typed SSE events (`response.output_text.delta`, +//! `response.function_call_arguments.delta`, `response.completed`, …) +//! rather than Chat Completions' `choices[].delta`. +//! +//! References: OpenAI Responses API streaming docs and the open-source Codex +//! client's request transformer. + +const std = @import("std"); +const Allocator = std.mem.Allocator; +const Writer = std.Io.Writer; +const conversation = @import("conversation.zig"); +const config_mod = @import("config.zig"); +const tool_registry_mod = @import("tool_registry.zig"); + +// =========================================================================== +// Request serialization +// =========================================================================== + +/// Serialize a Conversation into a `/responses` request body. Caller owns the +/// returned slice. +pub fn serializeRequest( + allocator: Allocator, + cfg: *const config_mod.OpenAIResponsesConfig, + conv: *const conversation.Conversation, + tools: *const tool_registry_mod.ToolRegistry, +) ![]u8 { + var aw: Writer.Allocating = .init(allocator); + errdefer aw.deinit(); + var s: std.json.Stringify = .{ .writer = &aw.writer }; + + try s.beginObject(); + + try s.objectField("model"); + try s.write(cfg.model); + + try s.objectField("stream"); + try s.write(true); + + // Stateless: we replay full history each turn (no server-side state). + try s.objectField("store"); + try s.write(false); + + try s.objectField("max_output_tokens"); + try s.write(cfg.max_tokens); + + // Carry encrypted reasoning so multi-turn reasoning can continue without + // server-side storage. + try s.objectField("include"); + try s.beginArray(); + try s.write("reasoning.encrypted_content"); + try s.endArray(); + + switch (cfg.reasoning) { + .default => {}, + // The Codex backend does not accept "none"; the lowest real effort is + // "low". `.off`/`.minimal` map to "low". + .off, .minimal, .low => try writeReasoning(&s, "low"), + .medium => try writeReasoning(&s, "medium"), + .high => try writeReasoning(&s, "high"), + } + + // System prompt → `instructions` (joined with blank lines). + var sys_blocks = try conversation.effectiveSystemBlocks(allocator, conv.messages.items); + defer sys_blocks.deinit(allocator); + if (sys_blocks.items.len > 0) { + var instr: std.ArrayList(u8) = .empty; + defer instr.deinit(allocator); + for (sys_blocks.items, 0..) |text, i| { + if (i != 0) try instr.appendSlice(allocator, "\n\n"); + try instr.appendSlice(allocator, text); + } + try s.objectField("instructions"); + try s.write(instr.items); + } + + if (tools.count() > 0) { + try s.objectField("tools"); + try s.beginArray(); + var it = tools.toolsForLLM(); + while (it.next()) |t| { + try s.beginObject(); + try s.objectField("type"); + try s.write("function"); + try s.objectField("name"); + try s.write(t.decl.name); // already wire-encoded + try s.objectField("description"); + try s.write(t.decl.description); + try s.objectField("parameters"); + try writeRawJson(&s, t.decl.schema_json); + try s.endObject(); + } + try s.endArray(); + } + + try s.objectField("input"); + try s.beginArray(); + for (conversation.activeMessageWindow(conv.messages.items)) |msg| { + if (msg.role == .system) continue; + try writeInputForMessage(&s, msg, allocator); + } + try s.endArray(); + + try s.endObject(); + return try aw.toOwnedSlice(); +} + +fn writeReasoning(s: *std.json.Stringify, effort: []const u8) !void { + try s.objectField("reasoning"); + try s.beginObject(); + try s.objectField("effort"); + try s.write(effort); + try s.objectField("summary"); + try s.write("auto"); + try s.endObject(); +} + +/// Emit the `input` item(s) for one conversation message. +fn writeInputForMessage(s: *std.json.Stringify, msg: conversation.Message, allocator: Allocator) !void { + switch (msg.role) { + .system => {}, + .user => { + // Tool results fan out into `function_call_output` items; any + // plain text becomes a `user` message. + var has_tool_result = false; + for (msg.content.items) |b| { + if (b == .ToolResult) has_tool_result = true; + } + if (has_tool_result) { + for (msg.content.items) |block| { + if (block != .ToolResult) continue; + const tr = block.ToolResult; + try s.beginObject(); + try s.objectField("type"); + try s.write("function_call_output"); + try s.objectField("call_id"); + try s.write(tr.tool_use_id); + try s.objectField("output"); + var tbuf: std.ArrayList(u8) = .empty; + defer tbuf.deinit(allocator); + try tr.appendTextInto(allocator, &tbuf); + try s.write(tbuf.items); + try s.endObject(); + } + } + // Plain user text (skip if the message was purely tool results). + var text_buf: std.ArrayList(u8) = .empty; + defer text_buf.deinit(allocator); + try concatTextBlocks(msg.content.items, &text_buf, allocator); + if (text_buf.items.len > 0) { + try writeRoleMessage(s, "user", "input_text", text_buf.items); + } + }, + .assistant => { + // Assistant text first (as an output_text message), then each + // tool call as a `function_call` item. + var text_buf: std.ArrayList(u8) = .empty; + defer text_buf.deinit(allocator); + try concatTextBlocks(msg.content.items, &text_buf, allocator); + if (text_buf.items.len > 0) { + try writeRoleMessage(s, "assistant", "output_text", text_buf.items); + } + for (msg.content.items) |block| { + if (block != .ToolUse) continue; + const tu = block.ToolUse; + try s.beginObject(); + try s.objectField("type"); + try s.write("function_call"); + try s.objectField("call_id"); + try s.write(tu.id); + try s.objectField("name"); + var name_buf: [tool_registry_mod.max_wire_name_len]u8 = undefined; + try s.write(tool_registry_mod.encodeName(&name_buf, tu.name)); + try s.objectField("arguments"); + try s.write(tu.input.items); + try s.endObject(); + } + }, + } +} + +fn writeRoleMessage(s: *std.json.Stringify, role: []const u8, content_type: []const u8, text: []const u8) !void { + try s.beginObject(); + try s.objectField("role"); + try s.write(role); + try s.objectField("content"); + try s.beginArray(); + try s.beginObject(); + try s.objectField("type"); + try s.write(content_type); + try s.objectField("text"); + try s.write(text); + try s.endObject(); + try s.endArray(); + try s.endObject(); +} + +fn concatTextBlocks( + blocks: []const conversation.ContentBlock, + out: *std.ArrayList(u8), + allocator: Allocator, +) !void { + for (blocks) |block| { + switch (block) { + .Text => |tb| try out.appendSlice(allocator, tb.items), + .CompactionSummary => |cs| try out.appendSlice(allocator, cs.text.items), + else => {}, + } + } +} + +fn writeRawJson(s: *std.json.Stringify, raw: []const u8) !void { + var arena = std.heap.ArenaAllocator.init(std.heap.page_allocator); + defer arena.deinit(); + const parsed = std.json.parseFromSlice(std.json.Value, arena.allocator(), raw, .{}) catch { + try s.beginObject(); + try s.endObject(); + return; + }; + try s.write(parsed.value); +} + +// =========================================================================== +// Streaming event parsing +// =========================================================================== + +/// The kinds of streaming event this provider acts on. Everything else is +/// ignored (`.other`). +pub const EventKind = enum { + output_item_added, + output_text_delta, + reasoning_summary_delta, + function_call_arguments_delta, + output_item_done, + completed, + failed, + err, + other, +}; + +/// A parsed Responses streaming event. Slices borrow from `parsed`. +pub const StreamEvent = struct { + parsed: std.json.Parsed(std.json.Value), + kind: EventKind, + /// `output_text`/`reasoning_summary` delta, or function-call argument + /// fragment. + delta: ?[]const u8 = null, + /// Item id (`response.output_item.added/done`, function-call argument + /// deltas reference `item_id`). + item_id: ?[]const u8 = null, + /// Item type on add/done: "message" | "function_call" | "reasoning". + item_type: ?[]const u8 = null, + /// Function-call identity (on `output_item.added`/`done`). + call_id: ?[]const u8 = null, + name: ?[]const u8 = null, + /// Full arguments string on `output_item.done` for a function_call. + arguments: ?[]const u8 = null, + /// Error/failure message (`error`, `response.failed`). + error_message: ?[]const u8 = null, + /// Usage on `response.completed`. + usage: ?Usage = null, + + pub const Usage = struct { + input_tokens: u64 = 0, + output_tokens: u64 = 0, + cached_tokens: u64 = 0, + reasoning_tokens: u64 = 0, + }; + + pub fn deinit(self: *StreamEvent) void { + self.parsed.deinit(); + } +}; + +/// Parse one SSE event payload (the JSON after `data: `). The caller must keep +/// the returned value alive while reading its slices, then `deinit` it. +pub fn parseStreamEvent(allocator: Allocator, payload: []const u8) !StreamEvent { + var parsed = try std.json.parseFromSlice(std.json.Value, allocator, payload, .{}); + errdefer parsed.deinit(); + + var ev: StreamEvent = .{ .parsed = parsed, .kind = .other }; + const root = parsed.value; + if (root != .object) return ev; + const obj = root.object; + + const type_str = strField(obj, "type") orelse { + ev.parsed = parsed; + return ev; + }; + + if (std.mem.eql(u8, type_str, "response.output_text.delta")) { + ev.kind = .output_text_delta; + ev.delta = strField(obj, "delta"); + ev.item_id = strField(obj, "item_id"); + } else if (std.mem.eql(u8, type_str, "response.reasoning_summary_text.delta")) { + ev.kind = .reasoning_summary_delta; + ev.delta = strField(obj, "delta"); + ev.item_id = strField(obj, "item_id"); + } else if (std.mem.eql(u8, type_str, "response.function_call_arguments.delta")) { + ev.kind = .function_call_arguments_delta; + ev.delta = strField(obj, "delta"); + ev.item_id = strField(obj, "item_id"); + } else if (std.mem.eql(u8, type_str, "response.output_item.added")) { + ev.kind = .output_item_added; + readItem(obj, &ev); + } else if (std.mem.eql(u8, type_str, "response.output_item.done")) { + ev.kind = .output_item_done; + readItem(obj, &ev); + } else if (std.mem.eql(u8, type_str, "response.completed")) { + ev.kind = .completed; + readUsage(obj, &ev); + } else if (std.mem.eql(u8, type_str, "response.failed") or std.mem.eql(u8, type_str, "response.incomplete")) { + ev.kind = .failed; + ev.error_message = readResponseError(obj); + } else if (std.mem.eql(u8, type_str, "error")) { + ev.kind = .err; + ev.error_message = strField(obj, "message") orelse "stream error"; + } + + ev.parsed = parsed; + return ev; +} + +fn readItem(obj: std.json.ObjectMap, ev: *StreamEvent) void { + const item = obj.get("item") orelse return; + if (item != .object) return; + const io = item.object; + ev.item_id = strField(io, "id"); + ev.item_type = strField(io, "type"); + ev.call_id = strField(io, "call_id"); + ev.name = strField(io, "name"); + ev.arguments = strField(io, "arguments"); +} + +fn readUsage(obj: std.json.ObjectMap, ev: *StreamEvent) void { + const resp = obj.get("response") orelse return; + if (resp != .object) return; + const u = resp.object.get("usage") orelse return; + if (u != .object) return; + var usage: StreamEvent.Usage = .{}; + usage.input_tokens = u64Field(u.object, "input_tokens"); + usage.output_tokens = u64Field(u.object, "output_tokens"); + usage.reasoning_tokens = blk: { + const otd = u.object.get("output_tokens_details") orelse break :blk 0; + if (otd != .object) break :blk 0; + break :blk u64Field(otd.object, "reasoning_tokens"); + }; + usage.cached_tokens = blk: { + const itd = u.object.get("input_tokens_details") orelse break :blk 0; + if (itd != .object) break :blk 0; + break :blk u64Field(itd.object, "cached_tokens"); + }; + ev.usage = usage; +} + +fn readResponseError(obj: std.json.ObjectMap) ?[]const u8 { + const resp = obj.get("response") orelse return null; + if (resp != .object) return null; + if (resp.object.get("error")) |e| { + if (e == .object) return strField(e.object, "message"); + } + if (resp.object.get("incomplete_details")) |d| { + if (d == .object) return strField(d.object, "reason"); + } + return null; +} + +fn strField(obj: std.json.ObjectMap, name: []const u8) ?[]const u8 { + const v = obj.get(name) orelse return null; + return if (v == .string) v.string else null; +} + +fn u64Field(obj: std.json.ObjectMap, name: []const u8) u64 { + const v = obj.get(name) orelse return 0; + if (v != .integer or v.integer < 0) return 0; + return @intCast(v.integer); +} + +// =========================================================================== +// Tests +// =========================================================================== + +const testing = std.testing; + +fn testConfig(model: []const u8) config_mod.OpenAIResponsesConfig { + return .{ .api_key = "k", .base_url = "u", .model = model }; +} + +fn emptyTools() tool_registry_mod.ToolRegistry { + return tool_registry_mod.ToolRegistry.init(testing.allocator); +} + +fn addUserText(conv: *conversation.Conversation, text: []const u8) !void { + const tb = try conversation.textualBlockFromSlice(conv.allocator, text); + var block: conversation.ContentBlock = .{ .Text = tb }; + errdefer block.deinit(conv.allocator); + try conv.addUserMessage(&.{block}); +} + +test "responses serializeRequest - instructions, input, store/include" { + const allocator = testing.allocator; + var conv = conversation.Conversation.init(allocator); + defer conv.deinit(); + try conv.addSystemMessage("You are Codex."); + try addUserText(&conv, "Hello!"); + + var cfg = testConfig("gpt-5.1-codex"); + cfg.reasoning = .high; + var tools = emptyTools(); + defer tools.deinit(); + const body = try serializeRequest(allocator, &cfg, &conv, &tools); + defer allocator.free(body); + + var parsed = try std.json.parseFromSlice(std.json.Value, allocator, body, .{}); + defer parsed.deinit(); + const root = parsed.value.object; + + try testing.expectEqualStrings("gpt-5.1-codex", root.get("model").?.string); + try testing.expect(root.get("stream").?.bool); + try testing.expect(!root.get("store").?.bool); + try testing.expectEqualStrings("You are Codex.", root.get("instructions").?.string); + try testing.expectEqualStrings("reasoning.encrypted_content", root.get("include").?.array.items[0].string); + try testing.expectEqualStrings("high", root.get("reasoning").?.object.get("effort").?.string); + + const input = root.get("input").?.array.items; + try testing.expectEqual(@as(usize, 1), input.len); + try testing.expectEqualStrings("user", input[0].object.get("role").?.string); + const part = input[0].object.get("content").?.array.items[0].object; + try testing.expectEqualStrings("input_text", part.get("type").?.string); + try testing.expectEqualStrings("Hello!", part.get("text").?.string); +} + +test "responses serializeRequest - tools are flat function items" { + const allocator = testing.allocator; + var conv = conversation.Conversation.init(allocator); + defer conv.deinit(); + try addUserText(&conv, "go"); + + var tools = emptyTools(); + defer tools.deinit(); + try tools.register(.{ + .decl = .{ .name = "echo", .description = "Echo.", .schema_json = "{\"type\":\"object\"}" }, + .ctx = undefined, + .vtable = &NoopToolVT.v, + }); + + const cfg = testConfig("gpt-5.1-codex"); + const body = try serializeRequest(allocator, &cfg, &conv, &tools); + defer allocator.free(body); + var parsed = try std.json.parseFromSlice(std.json.Value, allocator, body, .{}); + defer parsed.deinit(); + + const tool0 = parsed.value.object.get("tools").?.array.items[0].object; + // Flat shape: name/description/parameters directly on the tool object. + try testing.expectEqualStrings("function", tool0.get("type").?.string); + try testing.expectEqualStrings("echo", tool0.get("name").?.string); + try testing.expectEqualStrings("Echo.", tool0.get("description").?.string); + try testing.expect(tool0.get("parameters").? == .object); +} + +test "responses serializeRequest - assistant tool_use + tool result round-trip" { + const allocator = testing.allocator; + var conv = conversation.Conversation.init(allocator); + defer conv.deinit(); + + const id = try allocator.dupe(u8, "call_1"); + const name = try allocator.dupe(u8, "echo"); + var args: conversation.TextualBlock = .empty; + try args.appendSlice(allocator, "{\"m\":\"hi\"}"); + try conv.addAssistantMessage(&.{ + .{ .Text = try conversation.textualBlockFromSlice(allocator, "calling") }, + .{ .ToolUse = .{ .id = id, .name = name, .input = args } }, + }, null); + + const rid = try allocator.dupe(u8, "call_1"); + var parts: std.ArrayList(conversation.ResultPartStored) = .empty; + try parts.append(allocator, .{ .text = try conversation.textualBlockFromSlice(allocator, "42") }); + var content: std.ArrayList(conversation.ContentBlock) = .empty; + try content.append(allocator, .{ .ToolResult = .{ .tool_use_id = rid, .parts = parts } }); + try conv.messages.append(allocator, .{ .role = .user, .content = content }); + + var tools = emptyTools(); + defer tools.deinit(); + const cfg = testConfig("gpt-5.1-codex"); + const body = try serializeRequest(allocator, &cfg, &conv, &tools); + defer allocator.free(body); + var parsed = try std.json.parseFromSlice(std.json.Value, allocator, body, .{}); + defer parsed.deinit(); + + const input = parsed.value.object.get("input").?.array.items; + // assistant message (text) + function_call + function_call_output = 3. + try testing.expectEqual(@as(usize, 3), input.len); + try testing.expectEqualStrings("assistant", input[0].object.get("role").?.string); + try testing.expectEqualStrings("function_call", input[1].object.get("type").?.string); + try testing.expectEqualStrings("call_1", input[1].object.get("call_id").?.string); + try testing.expectEqualStrings("echo", input[1].object.get("name").?.string); + try testing.expectEqualStrings("function_call_output", input[2].object.get("type").?.string); + try testing.expectEqualStrings("call_1", input[2].object.get("call_id").?.string); + try testing.expectEqualStrings("42", input[2].object.get("output").?.string); +} + +test "responses parseStreamEvent - output_text delta" { + const allocator = testing.allocator; + var ev = try parseStreamEvent(allocator, + \\{"type":"response.output_text.delta","item_id":"msg_1","delta":"Hi"} + ); + defer ev.deinit(); + try testing.expectEqual(EventKind.output_text_delta, ev.kind); + try testing.expectEqualStrings("Hi", ev.delta.?); +} + +test "responses parseStreamEvent - function_call item added/done + args delta" { + const allocator = testing.allocator; + var added = try parseStreamEvent(allocator, + \\{"type":"response.output_item.added","item":{"type":"function_call","id":"fc_1","call_id":"call_9","name":"echo"}} + ); + defer added.deinit(); + try testing.expectEqual(EventKind.output_item_added, added.kind); + try testing.expectEqualStrings("function_call", added.item_type.?); + try testing.expectEqualStrings("call_9", added.call_id.?); + try testing.expectEqualStrings("echo", added.name.?); + + var d = try parseStreamEvent(allocator, + \\{"type":"response.function_call_arguments.delta","item_id":"fc_1","delta":"{\"x\":1}"} + ); + defer d.deinit(); + try testing.expectEqual(EventKind.function_call_arguments_delta, d.kind); + try testing.expectEqualStrings("fc_1", d.item_id.?); + try testing.expectEqualStrings("{\"x\":1}", d.delta.?); +} + +test "responses parseStreamEvent - completed usage" { + const allocator = testing.allocator; + var ev = try parseStreamEvent(allocator, + \\{"type":"response.completed","response":{"usage":{"input_tokens":100,"output_tokens":20,"input_tokens_details":{"cached_tokens":80},"output_tokens_details":{"reasoning_tokens":8}}}} + ); + defer ev.deinit(); + try testing.expectEqual(EventKind.completed, ev.kind); + try testing.expectEqual(@as(u64, 100), ev.usage.?.input_tokens); + try testing.expectEqual(@as(u64, 20), ev.usage.?.output_tokens); + try testing.expectEqual(@as(u64, 80), ev.usage.?.cached_tokens); + try testing.expectEqual(@as(u64, 8), ev.usage.?.reasoning_tokens); +} + +test "responses parseStreamEvent - error + failed" { + const allocator = testing.allocator; + var e = try parseStreamEvent(allocator, + \\{"type":"error","message":"boom"} + ); + defer e.deinit(); + try testing.expectEqual(EventKind.err, e.kind); + try testing.expectEqualStrings("boom", e.error_message.?); + + var f = try parseStreamEvent(allocator, + \\{"type":"response.failed","response":{"error":{"message":"bad"}}} + ); + defer f.deinit(); + try testing.expectEqual(EventKind.failed, f.kind); + try testing.expectEqualStrings("bad", f.error_message.?); +} + +const tool_mod = @import("tool.zig"); +const NoopToolVT = struct { + fn invoke(_: *anyopaque, _: []const u8, _: Allocator) anyerror!tool_mod.ResultParts { + return error.NotImplementedInTest; + } + fn deinit_(_: *anyopaque, _: Allocator) void {} + const v: tool_mod.Tool.VTable = .{ .invoke = invoke, .deinit = deinit_ }; +}; |
