@demicodes/coding-agent 0.1.0

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,15 @@
+# @demicodes/coding-agent
+
+A ready-made coding-agent harness for Demi: the system prompt, registered commands
+(an `editor` for file edits, plus shell control), and reference resolution, wired
+to a `Host`. Drop it into an `AgentServer`.
+
+```ts
+import { createCodingAgentHarness } from '@demicodes/coding-agent'
+import { LocalHost } from '@demicodes/host-local'
+
+const harness = createCodingAgentHarness({ host: new LocalHost(process.cwd()) })
+```
+
+See the [Quickstart](../../README.md#quickstart). Part of [Demi](../../README.md).
+Apache-2.0.

package/dist/index.d.mts

@@ -0,0 +1,28 @@
+import { CommandRegistry, CommandSpec, Host } from "@demicodes/shell";
+import { AgentHarness, AgentReferenceResolveContext } from "@demicodes/agent";
+import { UserContentBlock } from "@demicodes/core";
+
+//#region src/coding-harness.d.ts
+type CodingState = Record<string, never>;
+interface CodingAgentHarnessOptions {
+  host: Host;
+  referenceHost?: Host;
+  commands?: CommandSpec[];
+}
+interface CodingCommandRegistryOptions {
+  editorHost?: Host;
+  commands?: CommandSpec[];
+}
+declare function createCodingCommandRegistry(options?: CodingCommandRegistryOptions): CommandRegistry;
+declare function createCodingAgentHarness(options: CodingAgentHarnessOptions): AgentHarness<CodingState>;
+//#endregion
+//#region src/editor-command.d.ts
+declare function createEditorCommand(host: Host): CommandSpec;
+//#endregion
+//#region src/reference-resolver.d.ts
+declare function createFileReferenceResolver<State>(host: Host): (ctx: AgentReferenceResolveContext<State>, content: UserContentBlock[]) => Promise<UserContentBlock[]>;
+//#endregion
+//#region src/todo-command.d.ts
+declare function createTodoCommand(): CommandSpec;
+//#endregion
+export { CodingAgentHarnessOptions, CodingCommandRegistryOptions, CodingState, createCodingAgentHarness, createCodingCommandRegistry, createEditorCommand, createFileReferenceResolver, createTodoCommand };

package/dist/index.mjs

@@ -0,0 +1,803 @@
+import { CommandRegistry } from "@demicodes/shell";
+import { asError, decodeUtf8, dirnamePath, encodeUtf8, errorMessage } from "@demicodes/utils";
+import { z } from "zod";
+//#region src/editor-command.ts
+function createEditorCommand(host) {
+	return {
+		name: "editor",
+		summary: "Create, edit, and patch files.",
+		subcommands: [
+			{
+				name: "create",
+				summary: "Create a new file. Fails if the file exists.",
+				effects: "modifies files by creating a new file; does not modify command storage",
+				successOutput: "writes \"Created <path>\" to stdout",
+				failureOutput: "writes the reason to stderr and exits non-zero without overwriting existing files",
+				input: {
+					path: z.string().describe("Target file path"),
+					content: z.string().describe("File content, passed via stdin/heredoc")
+				},
+				positionals: ["path"],
+				stdinField: "content",
+				examples: ["editor create src/foo.ts <<'EOF'\nexport const foo = 1\nEOF", "editor create README.md <<'EOF'\n# Project\nEOF"],
+				run: async ({ parsed, cwd, io }) => {
+					const path = String(parsed.values.path);
+					const content = String(parsed.values.content);
+					const pathError = pathValidationError$1(path);
+					if (pathError) {
+						await io.stderr(`${pathError}\n`);
+						return { exitCode: 1 };
+					}
+					if (await exists(host, cwd, path)) {
+						await io.stderr(`File already exists: ${path}\n`);
+						return { exitCode: 1 };
+					}
+					const parent = dirnamePath(path);
+					if (parent !== ".") {
+						const made = await mkdirPath(host, cwd, parent);
+						if (made.exitCode !== 0) {
+							await io.stderr(made.stderr);
+							return { exitCode: made.exitCode };
+						}
+					}
+					const write = await writeFile(host, cwd, path, content);
+					if (write.exitCode !== 0) {
+						await io.stderr(write.stderr);
+						return { exitCode: write.exitCode };
+					}
+					await io.stdout(`Created ${path}\n`);
+					return {
+						exitCode: 0,
+						metadata: editorDiffMetadata([fileDiffMetadata("create", null, path, "", content)])
+					};
+				}
+			},
+			{
+				name: "edit",
+				summary: "Replace exact text in an existing file.",
+				effects: "modifies one existing file; does not modify command storage",
+				successOutput: "writes \"Edited <path>\" to stdout",
+				failureOutput: "writes no-match, ambiguous-match, or write errors to stderr and exits non-zero without partial writes",
+				input: {
+					path: z.string().describe("Target file path"),
+					old: z.string().describe("Exact text to replace"),
+					new: z.string().describe("Replacement text"),
+					occurrence: z.number().int().positive().optional().describe("1-based occurrence to replace"),
+					context: z.number().int().positive().optional().describe("Line number used to choose nearest occurrence")
+				},
+				positionals: ["path"],
+				examples: ["editor edit src/foo.ts --old foo --new bar", "editor edit src/foo.ts --old \"old text\" --new \"new text\" --occurrence 2"],
+				run: async ({ parsed, cwd, io }) => {
+					const path = String(parsed.values.path);
+					const read = await readFile(host, cwd, path);
+					if (read.exitCode !== 0) {
+						await io.stderr(read.stderr);
+						return { exitCode: read.exitCode };
+					}
+					const oldText = String(parsed.values.old);
+					const newText = String(parsed.values.new);
+					if (oldText.length === 0) {
+						await io.stderr("Old text must not be empty\n");
+						return { exitCode: 1 };
+					}
+					const matches = findMatches(read.stdout, oldText);
+					if (matches.length === 0) {
+						await io.stderr(`No match found in ${path}\n`);
+						return { exitCode: 1 };
+					}
+					const selection = chooseMatch(matches, parsed.values.occurrence, parsed.values.context);
+					if (!selection.match) {
+						await io.stderr(`${selection.reason} in ${path}: ${formatMatches(matches)}\n`);
+						return { exitCode: 1 };
+					}
+					const match = selection.match;
+					const content = `${read.stdout.slice(0, match.index)}${newText}${read.stdout.slice(match.index + oldText.length)}`;
+					const write = await writeFile(host, cwd, path, content);
+					if (write.exitCode !== 0) {
+						await io.stderr(write.stderr);
+						return { exitCode: write.exitCode };
+					}
+					await io.stdout(`Edited ${path}\n`);
+					return {
+						exitCode: 0,
+						metadata: editorDiffMetadata([fileDiffMetadata("edit", path, path, read.stdout, content)])
+					};
+				}
+			},
+			{
+				name: "patch",
+				summary: "Apply a unified diff patch to one or more files.",
+				effects: "modifies files described by the patch; validates all patch operations before writing",
+				successOutput: "writes \"Patched <n> file(s)\" to stdout",
+				failureOutput: "writes parse, validation, or write errors to stderr and exits non-zero after rolling back partial writes when possible",
+				input: { patch: z.string().describe("Unified diff content, passed via stdin/heredoc") },
+				stdinField: "patch",
+				examples: ["editor patch <<'PATCH'\n--- a/src/foo.ts\n+++ b/src/foo.ts\n@@ -1 +1 @@\n-old\n+new\nPATCH", "editor patch <<'PATCH'\n--- /dev/null\n+++ b/src/new.ts\n@@ -0,0 +1 @@\n+export const created = true\nPATCH"],
+				run: async ({ parsed, cwd, io }) => {
+					let patches;
+					let operations;
+					try {
+						patches = parseUnifiedDiff(String(parsed.values.patch));
+						operations = await planPatchOperations(host, cwd, patches);
+					} catch (error) {
+						await io.stderr(`${asError(error).message}\n`);
+						return { exitCode: 1 };
+					}
+					const applied = await applyPatchOperations(host, cwd, operations);
+					if (applied.exitCode !== 0) {
+						await io.stderr(applied.stderr);
+						return { exitCode: applied.exitCode };
+					}
+					await io.stdout(`Patched ${patches.length} file(s)\n`);
+					return {
+						exitCode: 0,
+						metadata: editorDiffMetadata(operations.map(operationDiffMetadata))
+					};
+				}
+			}
+		]
+	};
+}
+async function exists(host, cwd, path) {
+	if (pathValidationError$1(path)) return false;
+	return host.fs.exists(path, { cwd });
+}
+async function readFile(host, cwd, path) {
+	const pathError = pathValidationError$1(path);
+	if (pathError) return {
+		stdout: "",
+		stderr: `${pathError}\n`,
+		exitCode: 1
+	};
+	try {
+		return {
+			stdout: decodeUtf8(await host.fs.readFile(path, { cwd })),
+			stderr: "",
+			exitCode: 0
+		};
+	} catch (error) {
+		return {
+			stdout: "",
+			stderr: `${errorMessage(error)}\n`,
+			exitCode: 1
+		};
+	}
+}
+async function writeFile(host, cwd, path, content) {
+	const pathError = pathValidationError$1(path);
+	if (pathError) return {
+		stdout: "",
+		stderr: `${pathError}\n`,
+		exitCode: 1
+	};
+	try {
+		await host.fs.writeFile(path, encodeUtf8(content), { cwd });
+		return {
+			stdout: "",
+			stderr: "",
+			exitCode: 0
+		};
+	} catch (error) {
+		return {
+			stdout: "",
+			stderr: `${errorMessage(error)}\n`,
+			exitCode: 1
+		};
+	}
+}
+async function deleteFile(host, cwd, path) {
+	const pathError = pathValidationError$1(path);
+	if (pathError) return {
+		stdout: "",
+		stderr: `${pathError}\n`,
+		exitCode: 1
+	};
+	try {
+		await host.fs.rm(path, {
+			cwd,
+			force: true
+		});
+		return {
+			stdout: "",
+			stderr: "",
+			exitCode: 0
+		};
+	} catch (error) {
+		return {
+			stdout: "",
+			stderr: `${errorMessage(error)}\n`,
+			exitCode: 1
+		};
+	}
+}
+async function mkdirPath(host, cwd, path) {
+	const pathError = pathValidationError$1(path);
+	if (pathError) return {
+		stdout: "",
+		stderr: `${pathError}\n`,
+		exitCode: 1
+	};
+	try {
+		await host.fs.mkdir(path, {
+			cwd,
+			recursive: true
+		});
+		return {
+			stdout: "",
+			stderr: "",
+			exitCode: 0
+		};
+	} catch (error) {
+		return {
+			stdout: "",
+			stderr: `${errorMessage(error)}\n`,
+			exitCode: 1
+		};
+	}
+}
+function findMatches(content, search) {
+	const matches = [];
+	let index = content.indexOf(search);
+	while (index !== -1) {
+		matches.push({
+			index,
+			line: content.slice(0, index).split("\n").length
+		});
+		index = content.indexOf(search, index + search.length);
+	}
+	return matches;
+}
+function chooseMatch(matches, occurrence, context) {
+	if (typeof occurrence === "number") {
+		const match = matches[occurrence - 1] ?? null;
+		return {
+			match,
+			reason: match ? "" : `Occurrence ${occurrence} is out of range`
+		};
+	}
+	if (typeof context === "number") {
+		const ranked = matches.map((match) => ({
+			match,
+			distance: Math.abs(match.line - context)
+		})).sort((a, b) => a.distance - b.distance);
+		const nearest = ranked[0];
+		if (!nearest) return {
+			match: null,
+			reason: "No match found"
+		};
+		return ranked.filter((entry) => entry.distance === nearest.distance).length === 1 ? {
+			match: nearest.match,
+			reason: ""
+		} : {
+			match: null,
+			reason: `Context line ${context} is ambiguous`
+		};
+	}
+	return matches.length === 1 ? {
+		match: matches[0],
+		reason: ""
+	} : {
+		match: null,
+		reason: "Multiple matches"
+	};
+}
+function formatMatches(matches) {
+	return matches.map((match, index) => `occurrence ${index + 1} at line ${match.line}`).join(", ");
+}
+async function applyPatchOperations(host, cwd, operations) {
+	const rollback = [];
+	const fail = async (failure) => {
+		const rollbackFailures = [];
+		for (let index = rollback.length - 1; index >= 0; index -= 1) {
+			const result = await runRollbackAction(host, cwd, rollback[index]);
+			if (result.exitCode !== 0) rollbackFailures.push(result);
+		}
+		return appendRollbackFailures(failure, rollbackFailures);
+	};
+	for (const operation of operations) {
+		if (operation.type === "delete") {
+			rollback.push({
+				type: "write",
+				path: operation.path,
+				content: operation.original
+			});
+			const deleted = await deleteFile(host, cwd, operation.path);
+			if (deleted.exitCode !== 0) return fail(deleted);
+			continue;
+		}
+		const parent = dirnamePath(operation.path);
+		if (parent !== ".") {
+			const made = await mkdirPath(host, cwd, parent);
+			if (made.exitCode !== 0) return fail(made);
+		}
+		rollback.push(rollbackForWrite(operation));
+		const write = await writeFile(host, cwd, operation.path, operation.content);
+		if (write.exitCode !== 0) return fail(write);
+		if (operation.deletePath) {
+			rollback.push({
+				type: "write",
+				path: operation.deletePath,
+				content: operation.original
+			});
+			const deleted = await deleteFile(host, cwd, operation.deletePath);
+			if (deleted.exitCode !== 0) return fail(deleted);
+		}
+	}
+	return {
+		stdout: "",
+		stderr: "",
+		exitCode: 0
+	};
+}
+function rollbackForWrite(operation) {
+	if (operation.oldPath === operation.path) return {
+		type: "write",
+		path: operation.path,
+		content: operation.original
+	};
+	return {
+		type: "delete",
+		path: operation.path
+	};
+}
+async function runRollbackAction(host, cwd, action) {
+	if (action.type === "delete") return deleteFile(host, cwd, action.path);
+	const parent = dirnamePath(action.path);
+	if (parent !== ".") {
+		const made = await mkdirPath(host, cwd, parent);
+		if (made.exitCode !== 0) return made;
+	}
+	return writeFile(host, cwd, action.path, action.content);
+}
+function appendRollbackFailures(failure, rollbackFailures) {
+	if (rollbackFailures.length === 0) return failure;
+	const rollbackStderr = rollbackFailures.map((result) => result.stderr.trim() || `rollback command exited ${result.exitCode}`).join("\n");
+	const separator = failure.stderr.length === 0 || failure.stderr.endsWith("\n") ? "" : "\n";
+	return {
+		...failure,
+		stderr: `${failure.stderr}${separator}Rollback failed:\n${rollbackStderr}\n`
+	};
+}
+function parseUnifiedDiff(diff) {
+	const lines = diff.split("\n");
+	const patches = [];
+	let current = null;
+	let hunk = null;
+	let pendingOldPath;
+	for (const line of lines) {
+		if (line.startsWith("--- ")) {
+			pendingOldPath = parseDiffPath(line.slice(4));
+			hunk = null;
+			continue;
+		}
+		if (line.startsWith("+++ ")) {
+			if (pendingOldPath === void 0) throw new Error("Invalid patch: new file header before old file header");
+			current = {
+				oldPath: pendingOldPath,
+				newPath: parseDiffPath(line.slice(4)),
+				hunks: []
+			};
+			patches.push(current);
+			pendingOldPath = void 0;
+			continue;
+		}
+		if (line.startsWith("@@ ")) {
+			if (!current) throw new Error("Invalid patch: hunk before file header");
+			const match = /^@@ -(\d+)(?:,\d+)? \+\d+(?:,\d+)? @@/.exec(line);
+			if (!match) throw new Error(`Invalid patch hunk header: ${line}`);
+			hunk = {
+				oldStart: Number(match[1]),
+				lines: []
+			};
+			current.hunks.push(hunk);
+			continue;
+		}
+		if (!hunk) continue;
+		if (line.startsWith(" ")) hunk.lines.push({
+			kind: "context",
+			text: line.slice(1)
+		});
+		else if (line.startsWith("-")) hunk.lines.push({
+			kind: "remove",
+			text: line.slice(1)
+		});
+		else if (line.startsWith("+")) hunk.lines.push({
+			kind: "add",
+			text: line.slice(1)
+		});
+		else if (line === "\") {
+			const previous = hunk.lines[hunk.lines.length - 1];
+			if (previous) previous.noNewline = true;
+		} else if (line !== "") throw new Error(`Invalid patch line: ${line}`);
+	}
+	if (patches.length === 0) throw new Error("Invalid patch: no files");
+	for (const patch of patches) {
+		if (!patch.oldPath && !patch.newPath) throw new Error("Invalid patch: both file paths are /dev/null");
+		if (patch.hunks.length === 0) throw new Error(`Invalid patch: ${patchDisplayPath(patch)} has no hunks`);
+	}
+	return patches;
+}
+async function planPatchOperations(host, cwd, patches) {
+	const operations = [];
+	for (const patch of patches) {
+		const targetPath = patch.newPath ?? patch.oldPath;
+		if (!targetPath) throw new Error("Invalid patch: missing target path");
+		assertValidPath(targetPath);
+		const isCreate = patch.oldPath === null;
+		const isDelete = patch.newPath === null;
+		let original = "";
+		if (isCreate) {
+			if (await exists(host, cwd, targetPath)) throw new Error(`File already exists: ${targetPath}`);
+		} else {
+			const oldPath = patch.oldPath;
+			if (oldPath === null) throw new Error("Invalid patch: missing old path");
+			assertValidPath(oldPath);
+			const read = await readFile(host, cwd, oldPath);
+			if (read.exitCode !== 0) throw new Error(read.stderr.trim() || `Failed to read ${oldPath}`);
+			original = read.stdout;
+		}
+		if (patch.newPath) assertValidPath(patch.newPath);
+		if (patch.oldPath && patch.newPath && patch.oldPath !== patch.newPath && await exists(host, cwd, patch.newPath)) throw new Error(`File already exists: ${patch.newPath}`);
+		const applied = applyFilePatch(original, patch);
+		if (isDelete) {
+			if (applied !== "") throw new Error(`Delete patch leaves content in ${targetPath}`);
+			operations.push({
+				type: "delete",
+				path: targetPath,
+				original,
+				oldPath: targetPath,
+				newPath: null
+			});
+		} else {
+			const deletePath = patch.oldPath && patch.newPath && patch.oldPath !== patch.newPath ? patch.oldPath : void 0;
+			operations.push({
+				type: "write",
+				path: targetPath,
+				content: applied,
+				original,
+				oldPath: patch.oldPath,
+				newPath: targetPath,
+				deletePath
+			});
+		}
+	}
+	return operations;
+}
+function applyFilePatch(content, patch) {
+	const file = splitTextFile(content);
+	const lines = file.lines;
+	let finalNewline = file.finalNewline;
+	let offset = 0;
+	for (const hunk of patch.hunks) {
+		const index = hunk.oldStart === 0 ? 0 : hunk.oldStart - 1 + offset;
+		const oldLines = hunk.lines.filter((line) => line.kind !== "add").map((line) => line.text);
+		const newLines = hunk.lines.filter((line) => line.kind !== "remove").map((line) => line.text);
+		if (!arraysEqual(lines.slice(index, index + oldLines.length), oldLines)) throw new Error(`Patch does not apply to ${patchDisplayPath(patch)} at line ${hunk.oldStart}`);
+		const touchesEof = index + oldLines.length === lines.length;
+		lines.splice(index, oldLines.length, ...newLines);
+		offset += newLines.length - oldLines.length;
+		if (touchesEof) {
+			const lastNewLine = [...hunk.lines].reverse().find((line) => line.kind !== "remove");
+			if (lastNewLine) finalNewline = !lastNewLine.noNewline;
+			else if (lines.length === 0) finalNewline = false;
+		}
+	}
+	return joinTextFile(lines, finalNewline);
+}
+function parseDiffPath(rawPath) {
+	const path = stripDiffPathMetadata(rawPath);
+	if (path === "/dev/null") return null;
+	if (path.startsWith("a/") || path.startsWith("b/")) return path.slice(2);
+	return path;
+}
+function assertValidPath(path) {
+	const error = pathValidationError$1(path);
+	if (error) throw new Error(error);
+}
+function pathValidationError$1(path) {
+	if (path.includes("\0")) return `Path contains NUL byte: ${path}`;
+	return null;
+}
+function stripDiffPathMetadata(rawPath) {
+	const trimmed = rawPath.trim();
+	const tabIndex = trimmed.indexOf("	");
+	if (tabIndex !== -1) return trimmed.slice(0, tabIndex);
+	return trimmed.replace(/\s+\d{4}-\d{2}-\d{2}(?:[ T]\d{2}:\d{2}:\d{2}(?:\.\d+)?(?:\s+[+-]\d{4})?)?$/, "");
+}
+function patchDisplayPath(patch) {
+	return patch.newPath ?? patch.oldPath ?? "<unknown>";
+}
+function splitTextFile(content) {
+	if (content === "") return {
+		lines: [],
+		finalNewline: false
+	};
+	const finalNewline = content.endsWith("\n");
+	const body = finalNewline ? content.slice(0, -1) : content;
+	return {
+		lines: body === "" ? [] : body.split("\n"),
+		finalNewline
+	};
+}
+function joinTextFile(lines, finalNewline) {
+	if (lines.length === 0) return "";
+	return `${lines.join("\n")}${finalNewline ? "\n" : ""}`;
+}
+function arraysEqual(left, right) {
+	return left.length === right.length && left.every((value, index) => value === right[index]);
+}
+function editorDiffMetadata(diffs) {
+	return {
+		type: "editor_file_diffs",
+		diffs
+	};
+}
+function operationDiffMetadata(operation) {
+	if (operation.type === "delete") return fileDiffMetadata("delete", operation.oldPath, null, operation.original, "");
+	return fileDiffMetadata("patch", operation.oldPath, operation.newPath, operation.original, operation.content);
+}
+function fileDiffMetadata(action, oldPath, newPath, oldText, newText) {
+	const path = newPath ?? oldPath;
+	if (!path) throw new Error("Missing diff path");
+	return {
+		type: "file_diff",
+		action,
+		path,
+		oldPath,
+		newPath,
+		oldText,
+		newText,
+		unifiedDiff: unifiedDiff(oldPath, newPath, oldText, newText)
+	};
+}
+function unifiedDiff(oldPath, newPath, oldText, newText) {
+	const oldLines = diffLines(oldText);
+	const newLines = diffLines(newText);
+	return `${[
+		`--- ${oldPath === null ? "/dev/null" : `a/${oldPath}`}`,
+		`+++ ${newPath === null ? "/dev/null" : `b/${newPath}`}`,
+		`@@ -${diffRange(oldLines.length)} +${diffRange(newLines.length)} @@`,
+		...oldLines.map((line) => `-${line}`),
+		...newLines.map((line) => `+${line}`)
+	].join("\n")}\n`;
+}
+function diffLines(text) {
+	if (text === "") return [];
+	const body = text.endsWith("\n") ? text.slice(0, -1) : text;
+	return body === "" ? [] : body.split("\n");
+}
+function diffRange(lineCount) {
+	return lineCount === 0 ? "0,0" : `1,${lineCount}`;
+}
+//#endregion
+//#region src/reference-resolver.ts
+function createFileReferenceResolver(host) {
+	return async (ctx, content) => {
+		const resolved = [];
+		for (const block of content) {
+			if (block.type !== "reference") {
+				resolved.push(block);
+				continue;
+			}
+			resolved.push(await resolveFileReference(host, ctx.cwd, block.reference));
+		}
+		return resolved;
+	};
+}
+async function resolveFileReference(host, cwd, reference) {
+	const path = parseFileReference(reference);
+	const pathError = pathValidationError(path);
+	if (pathError) throw new Error(pathError);
+	let stdout;
+	try {
+		stdout = decodeUtf8(await host.fs.readFile(path, { cwd }));
+	} catch (error) {
+		throw new Error(`Failed to resolve file reference "${reference}": ${errorMessage(error)}`);
+	}
+	return {
+		type: "text",
+		text: `<file path="${path}">\n${stdout}\n</file>`
+	};
+}
+function parseFileReference(reference) {
+	const trimmed = reference.trim();
+	if (!trimmed) throw new Error("Empty file reference");
+	if (trimmed.startsWith("file://") || trimmed.startsWith("file:/")) return decodeFileReferencePath(new URL(trimmed).pathname);
+	if (trimmed.startsWith("file:")) return decodeFileReferencePath(trimmed.slice(5));
+	return trimmed;
+}
+function decodeFileReferencePath(path) {
+	try {
+		return decodeURIComponent(path);
+	} catch {
+		throw new Error(`Invalid file reference URL encoding: ${path}`);
+	}
+}
+function pathValidationError(path) {
+	if (path.includes("\0")) return `File reference contains NUL byte: ${path}`;
+	return null;
+}
+//#endregion
+//#region src/todo-command.ts
+const TODO_STORAGE_KEY = "todos.json";
+const TodoStatus = z.enum([
+	"pending",
+	"in_progress",
+	"done"
+]);
+const TodoItemSchema = z.object({
+	id: z.string(),
+	text: z.string(),
+	status: TodoStatus
+});
+const TodoListSchema = z.array(TodoItemSchema);
+function createTodoCommand() {
+	return {
+		name: "todo",
+		summary: "Manage an agent-session-scoped task list for coding work.",
+		subcommands: [
+			{
+				name: "list",
+				summary: "List todos for the current agent session.",
+				effects: "read-only; does not modify files or command storage",
+				successOutput: "writes the session todo list as raw text, or JSON matching { todos } when --json is passed",
+				failureOutput: "writes storage or validation errors to stderr and exits non-zero",
+				output: { json: z.object({ todos: TodoListSchema }) },
+				examples: ["todo list", "todo list --json"],
+				run: async ({ parsed, io, storage }) => {
+					const todos = await readTodos(storage);
+					if (parsed.json) await io.stdout(JSON.stringify({ todos }));
+					else if (todos.length === 0) await io.stdout("No todos.\n");
+					else await io.stdout(`${todos.map(formatTodo).join("\n")}\n`);
+					return { exitCode: 0 };
+				}
+			},
+			{
+				name: "add",
+				summary: "Add a new todo.",
+				effects: "modifies agent-session-scoped command storage; does not modify files",
+				successOutput: "writes the created todo as raw text, or JSON matching { todo } when --json is passed",
+				failureOutput: "writes validation or storage errors to stderr and exits non-zero",
+				input: { text: z.string().describe("Todo text") },
+				positionals: ["text"],
+				output: { json: z.object({ todo: TodoItemSchema }) },
+				examples: ["todo add \"Run tests\"", "todo add \"Run tests\" --json"],
+				run: async ({ parsed, io, storage }) => {
+					const todos = await readTodos(storage);
+					const todo = {
+						id: nextTodoId(todos),
+						text: String(parsed.values.text),
+						status: "pending"
+					};
+					todos.push(todo);
+					await writeTodos(storage, todos);
+					if (parsed.json) await io.stdout(JSON.stringify({ todo }));
+					else await io.stdout(`${formatTodo(todo)}\n`);
+					return { exitCode: 0 };
+				}
+			},
+			{
+				name: "update",
+				summary: "Update todo text or status.",
+				effects: "modifies agent-session-scoped command storage; does not modify files",
+				successOutput: "writes the updated todo as raw text, or JSON matching { todo } when --json is passed",
+				failureOutput: "writes \"Todo not found\" or validation/storage errors to stderr and exits non-zero",
+				input: {
+					id: z.string().describe("Todo id"),
+					text: z.string().optional().describe("Replacement text"),
+					status: TodoStatus.optional().describe("Replacement status")
+				},
+				positionals: ["id"],
+				output: { json: z.object({ todo: TodoItemSchema }) },
+				examples: ["todo update T1 --text \"Run full test suite\"", "todo update T1 --status in_progress --json"],
+				run: async ({ parsed, io, storage }) => {
+					const todos = await readTodos(storage);
+					const todo = findTodo(todos, String(parsed.values.id));
+					if (!todo) {
+						await io.stderr(`Todo not found: ${parsed.values.id}\n`);
+						return { exitCode: 1 };
+					}
+					if (parsed.values.text !== void 0) todo.text = String(parsed.values.text);
+					if (parsed.values.status !== void 0) todo.status = parsed.values.status;
+					await writeTodos(storage, todos);
+					if (parsed.json) await io.stdout(JSON.stringify({ todo }));
+					else await io.stdout(`${formatTodo(todo)}\n`);
+					return { exitCode: 0 };
+				}
+			},
+			{
+				name: "done",
+				summary: "Mark a todo as done.",
+				effects: "modifies agent-session-scoped command storage; does not modify files",
+				successOutput: "writes the completed todo as raw text, or JSON matching { todo } when --json is passed",
+				failureOutput: "writes \"Todo not found\" or validation/storage errors to stderr and exits non-zero",
+				input: { id: z.string().describe("Todo id") },
+				positionals: ["id"],
+				output: { json: z.object({ todo: TodoItemSchema }) },
+				examples: ["todo done T1", "todo done T1 --json"],
+				run: async ({ parsed, io, storage }) => {
+					const todos = await readTodos(storage);
+					const todo = findTodo(todos, String(parsed.values.id));
+					if (!todo) {
+						await io.stderr(`Todo not found: ${parsed.values.id}\n`);
+						return { exitCode: 1 };
+					}
+					todo.status = "done";
+					await writeTodos(storage, todos);
+					if (parsed.json) await io.stdout(JSON.stringify({ todo }));
+					else await io.stdout(`${formatTodo(todo)}\n`);
+					return { exitCode: 0 };
+				}
+			}
+		]
+	};
+}
+async function readTodos(storage) {
+	return TodoListSchema.parse(await storage.readJson(TODO_STORAGE_KEY) ?? []);
+}
+async function writeTodos(storage, todos) {
+	await storage.writeJson(TODO_STORAGE_KEY, todos);
+}
+function findTodo(todos, id) {
+	return todos.find((todo) => todo.id === id) ?? null;
+}
+function nextTodoId(todos) {
+	let max = 0;
+	for (const todo of todos) {
+		const match = /^T(\d+)$/.exec(todo.id);
+		if (match) max = Math.max(max, Number(match[1]));
+	}
+	return `T${max + 1}`;
+}
+function formatTodo(todo) {
+	return `[${todo.status === "done" ? "x" : todo.status === "in_progress" ? "-" : " "}] ${todo.id} ${todo.text}`;
+}
+//#endregion
+//#region src/coding-harness.ts
+function createCodingCommandRegistry(options = {}) {
+	const registry = new CommandRegistry();
+	const commands = options.commands ?? [...options.editorHost ? [createEditorCommand(options.editorHost)] : [], createTodoCommand()];
+	for (const command of commands) registry.register(command);
+	return registry;
+}
+function createCodingAgentHarness(options) {
+	const commands = options.commands ?? defaultCodingCommands(options.host);
+	return {
+		name: "coding",
+		initialState: () => ({}),
+		host: () => options.host,
+		commands: () => [...commands],
+		systemPrompt: (ctx) => {
+			const sections = [
+				"You are a coding agent. Use shell session tools to inspect, edit, test, and verify the workspace.",
+				"Treat cwd as the task workspace. Create, edit, and verify task files there by default; do not create a separate project directory under /tmp or another absolute path unless the user asks for it or the workspace is unusable.",
+				"Prefer registered commands for agent-specific state and audited workflows. Use normal system commands for ordinary shell work.",
+				[
+					"Shell session rules:",
+					"- Use shell_exec for commands. timeoutMs is required and is only an observation window, not a kill deadline; at timeoutMs the command keeps running and a commandId is returned while the turn continues.",
+					"- Tool description: concise title for the concrete user-visible state/result to make visible or confirm. Do not describe waiting, pausing, tool mechanics, generic actions, object labels, steps, tool names, ids, internals, or reasons.",
+					"- shell_exec returns shellId, commandId, stdout/stderr deltas, and status. Track commandId for all follow-up control.",
+					"- If status is running, the command keeps running and the turn continues. Either call shell_status again to check, or call yield to end this turn and be woken later to check with commandId. shell_exec and shell_status never end the turn or schedule a wakeup on their own; only yield does.",
+					"- Use shell_status for polling. It is non-blocking and reads new stdout/stderr since the last snapshot unless offsets are provided.",
+					"- For dev servers, watch commands, previews, and other long-running processes that you need to observe and stop, run them in the foreground with a short timeoutMs, use shell_status to observe (and yield to wait between checks), and shell_abort by commandId to stop. Avoid starting them with \"&\" and avoid pkill/killall by process name.",
+					"- After a long-running process has been verified and stopped, summarize the observed evidence instead of restarting it to demonstrate the same behavior again.",
+					"- If a foreground process is running and you need a separate one-off command, such as curl against a dev server, call shell_exec without shellId; keep using the original commandId to status, write to, or abort the long-running process.",
+					"- Prefer non-interactive CLI flags for scaffolds and package tools when available.",
+					"- For underspecified scaffold requests, choose a reasonable non-interactive default and proceed unless the choice is destructive or impossible.",
+					"- Send non-empty stdin with shell_write only when the running command is known to be waiting for specific input; include a newline such as \"Alice\\n\" for line-oriented prompts.",
+					"- For interactive stdin, keep the reader inside one foreground system process such as sh -c, node, or python; do not rely on the session script builtin read across turns.",
+					"- Use shell_abort only when intentionally stopping a foreground command, and pass commandId."
+				].join("\n"),
+				"File references attached by the client are expanded before provider calls."
+			];
+			if (ctx.commandsPrompt.trim()) sections.push(`Registered commands:\n\n${ctx.commandsPrompt}`);
+			return sections.join("\n\n");
+		},
+		resolveReferences: createFileReferenceResolver(options.referenceHost ?? options.host)
+	};
+}
+function defaultCodingCommands(editorHost) {
+	return [createEditorCommand(editorHost), createTodoCommand()];
+}
+//#endregion
+export { createCodingAgentHarness, createCodingCommandRegistry, createEditorCommand, createFileReferenceResolver, createTodoCommand };

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@demicodes/coding-agent",
+  "description": "Coding-agent harness, commands, and reference resolution for Demi.",
+  "version": "0.1.0",
+  "private": false,
+  "type": "module",
+  "exports": {
+    ".": {
+      "development": "./src/index.ts",
+      "types": "./dist/index.d.mts",
+      "import": "./dist/index.mjs"
+    }
+  },
+  "dependencies": {
+    "@demicodes/agent": "workspace:*",
+    "@demicodes/core": "workspace:*",
+    "@demicodes/shell": "workspace:*",
+    "@demicodes/utils": "workspace:*",
+    "zod": "^4.0.0"
+  },
+  "devDependencies": {
+    "@demicodes/provider": "workspace:*"
+  },
+  "license": "Apache-2.0",
+  "main": "./dist/index.mjs",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.mts",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsdown"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/wspl/demi.git",
+    "directory": "packages/coding-agent"
+  },
+  "homepage": "https://github.com/wspl/demi/tree/main/packages/coding-agent#readme",
+  "bugs": "https://github.com/wspl/demi/issues"
+}