Skip to content

implementation.md

Latest commit

 

History

History
106 lines (87 loc) · 5.63 KB

implementation.md

File metadata and controls

106 lines (87 loc) · 5.63 KB
Raw

Implementation Notes

中文 | Back to README

This document records implementation details that are useful for maintainers and reviewers but are not required for installing or evaluating DSH Smarter Edit.

Codex alignment

The grammar is byte-identical to OpenAI Codex commit 8e6a44b428e31f91b21edc97904fcdf4f0931ade. The parser state machine, ordered replacement computation, four-pass sequence matching, context-line handling, and PreserveLineEndings reconstruction are TypeScript ports of that revision.

Tests run the complete 25-scenario official portable corpus. Twenty-four scenarios match the upstream final state exactly. Scenario 015 asserts the one intentional difference: upstream keeps earlier writes when a later operation fails, while this plugin preflights all operations and rolls back published targets.

The project uses the MIT License. Codex-derived grammar, fixtures, and ported implementation retain their Apache-2.0 license and NOTICE attribution under third_party/codex/; see THIRD_PARTY_NOTICES.md.

Safety and atomicity

  • Parses and validates the complete patch before mutating a target.
  • Locates update hunks with Codex-compatible exact, trailing-whitespace, full-whitespace, and Unicode-punctuation matching passes.
  • Uses Codex's PreserveLineEndings mode. Context lines keep their endings, inserted lines use the first existing ending, and updates retain Codex's historical trailing-newline behavior.
  • Resolves relative paths from the Session working directory, accepts absolute paths, and follows symbolic links. DSH's active sandbox remains the permission boundary.
  • Stages every new file body before commit, avoids clobbering a concurrently created path, captures and validates backups, verifies final contents, and rolls published targets back in reverse order after a detected failure.
  • Returns a canonical unified diff and operation summary.

The transaction is failure-atomic, not crash-atomic. A handled parse, preflight, stage, commit, or verification failure leaves no partial target changes when rollback succeeds. Process termination, kernel failure, power loss, or rollback I/O failure can still leave recovery files.

Failure atomicity does not bound retry cost. Any failed operation rejects the whole patch, and a retry must submit the full patch again. The plugin imposes no fixed patch-size limit, so this cost grows with the size of the patch.

Freeform transport

DSH 0.1.x and 0.2.1 expose JSON-schema tool definitions and strip custom-tool metadata before the provider adapter. This plugin installs a narrow, reference-counted bridge at PiAiAdapter.current(), the request-frozen model snapshot boundary, and enriches only the exact apply_patch schema with the bundled OpenAI Lark grammar. It handles both request-level tools and pi-ai 1.x toolsAdded declarations in system messages, preserving tool removals and unrelated history.

On pi-ai OpenAI Responses routes, the provider request contains an OpenAI type: "custom" tool with raw input. Grammar-capable OpenAI Chat Completions routes also receive type: "custom", with custom.format carrying the Lark grammar; they do not receive a JSON Schema function definition for apply_patch. Provider protocols without custom grammar tools retain their ordinary JSON tool transport.

Some OpenAI-compatible completion routes return that input through temporary JSON fallback envelopes. The bridge accepts pi-ai's patch and input properties. DeepSeek V4 routes can intermittently answer the custom request through a function-shaped arguments fallback, whose string value can itself contain a JSON-encoded known fallback envelope; the bridge unwraps those layers only when they restore raw patch text. An envelope with multiple known properties is accepted only when every property independently restores the same patch bytes. Duplicate names, unknown properties, non-string values, conflicting payloads, and arbitrary prefixed text remain rejected. The normalized streamed input must also match the completed ToolCallBlock exactly.

An invalid envelope, a streamed/final mismatch, or an incomplete tool call is converted into a fixed rejected apply_patch call. DSH's ToolRuntime materializes it as an isError: true result with a raw-input retry instruction, so the Agent can continue to its next model step. The rejected candidate is never parsed or applied, and its ambiguous provider envelope is not persisted as executable input. The bridge preserves the call identity from pi-ai's start event, supplies a non-empty ID if the provider omitted one, and converts ID, name, or block-type changes into exactly one rejected call. A provider transport failure that aborts the source stream before it can form a tool call remains an LLM transport failure.

DSH's public llm/stream middleware removes these temporary envelopes before DSH assembles, executes, or persists a completed call. A replay bridge restores pi-ai's envelope only inside the adapter when a later model step replays raw Session history. Live arguments, Session logs, and the Trajectory parameter view therefore contain raw patch text.

Package entry points and presentation

The pure engine is available from @anionex/dsh-smarter-edit/engine. The DSH adapter lives in src/host.ts and src/index.ts.

Each successful call returns an operation summary, a canonical unified diff, and per-hunk presentation metadata. The bundled Web client registers through DSH's official keyed toolview slot and renders the native DiffBlock. Historical calls without presentation metadata fall back to plain output instead of reconstructing a diff from untrusted text.