@theokit/sdk-tools 0.19.0 → 0.20.1

package/dist/index.d.cts

@@ -6,17 +6,27 @@ import { InteractiveProvider } from '@theokit/sdk/interactive';
 /**
  * `apply_patch` — built-in tool for coding agents.
  *
- * Parses a unified diff string and applies it to the project files.
- * Creates `.bak` backups before modifying each file.
+ * Codex's V4A patch grammar (`*** Begin Patch` … `*** End Patch`): `*** Add/Update/Delete File:`, an
+ * optional `*** Move to:`, and `@@`-anchored `+`/`-`/context hunks matched with a context-tolerant ladder
+ * (exact → rstrip → trim → unicode). See `internal/v4a-patch.ts` for the parser + matcher.
  *
- * Return shape (always a JSON string):
+ * Applied STRICTLY atomically: the whole patch is planned (every file read + new content computed + path
+ * security-checked) before ANY write. A parse error, context mismatch, or path violation anywhere ⇒ typed
+ * error and ZERO writes (stronger than Codex, which writes file-by-file and can leave partial writes).
+ *
+ * Return shape (always a JSON string — never throws on a bad patch):
  *   - `{ ok: true, files_patched: string[] }`
- *   - `{ ok: false, error: 'parse_error' | 'path_traversal' |
- *        'forbidden_path' | 'patch_failed' }`
+ *   - `{ ok: false, error: 'parse_error' | 'path_traversal' | 'forbidden_path' | 'not_found' |
+ *        'patch_failed' | 'duplicate_target' | 'file_exists' | 'io_error' }`
+ *
+ * Security/robustness (M18 review): forbidden secrets (`.env`/`.git`/`node_modules`/`.theo`) are blocked
+ * at ANY path depth and against absolute-path spelling; a file touched by two hunks is rejected
+ * (`duplicate_target`); Add over an existing file is rejected (`file_exists`); Delete of a missing file
+ * is `not_found`; any unexpected fs error maps to `io_error` (the handler never throws).
  */
 
 interface CreateApplyPatchToolOptions {
-    /** Absolute path to the project root. */
+    /** Absolute path to the project root. Every hunk path is gated against this boundary. */
     projectRoot: string;
 }
 declare function createApplyPatchTool(opts: CreateApplyPatchToolOptions): CustomTool;

package/dist/index.d.ts

@@ -6,17 +6,27 @@ import { InteractiveProvider } from '@theokit/sdk/interactive';
 /**
  * `apply_patch` — built-in tool for coding agents.
  *
- * Parses a unified diff string and applies it to the project files.
- * Creates `.bak` backups before modifying each file.
+ * Codex's V4A patch grammar (`*** Begin Patch` … `*** End Patch`): `*** Add/Update/Delete File:`, an
+ * optional `*** Move to:`, and `@@`-anchored `+`/`-`/context hunks matched with a context-tolerant ladder
+ * (exact → rstrip → trim → unicode). See `internal/v4a-patch.ts` for the parser + matcher.
  *
- * Return shape (always a JSON string):
+ * Applied STRICTLY atomically: the whole patch is planned (every file read + new content computed + path
+ * security-checked) before ANY write. A parse error, context mismatch, or path violation anywhere ⇒ typed
+ * error and ZERO writes (stronger than Codex, which writes file-by-file and can leave partial writes).
+ *
+ * Return shape (always a JSON string — never throws on a bad patch):
  *   - `{ ok: true, files_patched: string[] }`
- *   - `{ ok: false, error: 'parse_error' | 'path_traversal' |
- *        'forbidden_path' | 'patch_failed' }`
+ *   - `{ ok: false, error: 'parse_error' | 'path_traversal' | 'forbidden_path' | 'not_found' |
+ *        'patch_failed' | 'duplicate_target' | 'file_exists' | 'io_error' }`
+ *
+ * Security/robustness (M18 review): forbidden secrets (`.env`/`.git`/`node_modules`/`.theo`) are blocked
+ * at ANY path depth and against absolute-path spelling; a file touched by two hunks is rejected
+ * (`duplicate_target`); Add over an existing file is rejected (`file_exists`); Delete of a missing file
+ * is `not_found`; any unexpected fs error maps to `io_error` (the handler never throws).
  */
 
 interface CreateApplyPatchToolOptions {
-    /** Absolute path to the project root. */
+    /** Absolute path to the project root. Every hunk path is gated against this boundary. */
     projectRoot: string;
 }
 declare function createApplyPatchTool(opts: CreateApplyPatchToolOptions): CustomTool;