v4a

README

v4a

Deprecated: use github.com/fgn/applypatch. applypatch.Apply and applypatch.ApplyBatch behave like this package, and it adds a Codex-compatible mode and the Codex *** Begin Patch format.

A strict Go applier for V4A diffs, the patch format OpenAI models emit through the apply_patch tool. It is a Go port of applyDiff from the OpenAI Agents SDK for JavaScript, changed to fail closed instead of guessing.

Install

go get github.com/fgn/v4a

Usage

input := "def greet():\n    print(\"Hi\")\n"
diff := "@@ def greet():\n-    print(\"Hi\")\n+    print(\"Hello\")"

output, err := v4a.Apply(input, diff)

ApplyBatch applies several diffs for one file against the same original input and fails as a whole if any diff fails or two diffs overlap.

Behavior

• Anchors, context, and removed lines must match byte for byte and exactly once. There is no whitespace trimming or Unicode normalization.
• An insertion without context needs an anchor, *** End of File, or an empty input.
• Only update_file diffs are supported. Creating, deleting, and moving files is left to the caller.
• LF and CRLF newlines and a missing final newline are preserved.

Development

Development tasks run through Task, which you can install from taskfile.dev/docs/installation. Run task to format, lint, and test, and task --list to see the rest.

License

MIT, see LICENSE. Based on the OpenAI Agents SDK for JavaScript, copyright (c) 2025 OpenAI, also MIT.

Documentation

Overview

Package v4a applies V4A update diffs strictly.

Deprecated: use github.com/fgn/applypatch, whose Apply and ApplyBatch behave like this package's.

V4A is the context-anchored patch format that OpenAI models emit through the apply_patch tool. This package is a Go port of applyDiff from the OpenAI Agents SDK for JavaScript (https://github.com/openai/openai-agents-js). An update diff looks like this:

@@ def greet():
-    print("Hi")
+    print("Hello")

Lines starting with a space are context, "-" lines are removed, and "+" lines are added. "@@ text" moves the search past the one input line equal to text; a bare "@@" starts a new section. "*** End of File" pins the section before it to the end of the input.

Unlike the reference implementations, this package never guesses. Anchors, context, and removed lines must match the input byte for byte and exactly once: there is no whitespace trimming or Unicode normalization, and an insertion without context needs an anchor or "*** End of File". A diff that does not apply returns an error and no partial result, so the caller can send the error back to the model and ask for a new patch.

Only update diffs are supported. The "*** Begin Patch" envelope and the Add File, Delete File, and Move to headers are rejected; the caller handles those operations.

Index

• func Apply(input, diff string) (string, error)
• func ApplyBatch(input string, diffs []string) (string, error)

Examples

• Apply
• Apply (Strict)
• ApplyBatch
• ApplyBatch (Overlap)

Functions

func Apply

func Apply(input, diff string) (string, error)

Apply applies one V4A update diff to input and returns the patched text. Creating, deleting, and moving files is left to the caller.

Example

package main

import (
	"fmt"

	"github.com/fgn/v4a"
)

func main() {
	input := "def greet():\n    print(\"Hi\")\n"
	diff := "@@ def greet():\n-    print(\"Hi\")\n+    print(\"Hello\")"
	output, err := v4a.Apply(input, diff)
	if err != nil {
		fmt.Println(err)
		return
	}
	fmt.Print(output)
}

Output:
def greet():
    print("Hello")

Example (Strict)

package main

import (
	"fmt"

	"github.com/fgn/v4a"
)

func main() {
	// Whitespace differences are not forgiven.
	_, err := v4a.Apply("  indented\n", "-indented\n+changed")
	fmt.Println(err)
}

Output:
target must match exactly once

func ApplyBatch

func ApplyBatch(input string, diffs []string) (string, error)

ApplyBatch applies several update diffs to the same input as one edit. Every diff targets the original input, not the output of the diffs before it. Overlapping edits fail the whole batch.

Example

package main

import (
	"fmt"

	"github.com/fgn/v4a"
)

func main() {
	input := "alpha\nbeta\ngamma\n"
	output, err := v4a.ApplyBatch(input, []string{"-alpha\n+ALPHA", "-gamma\n+GAMMA"})
	if err != nil {
		fmt.Println(err)
		return
	}
	fmt.Print(output)
}

Output:
ALPHA
beta
GAMMA

Example (Overlap)

package main

import (
	"fmt"

	"github.com/fgn/v4a"
)

func main() {
	// Both diffs target the original input, so they cannot edit the same line.
	_, err := v4a.ApplyBatch("alpha\n", []string{"-alpha\n+one", "-alpha\n+two"})
	fmt.Println(err)
}

Output:
overlapping edits