@chantier/core 0.5.0 → 0.6.0

package/dist/index.d.mts

@@ -1,4 +1,42 @@
 import { ApprovalDetail, ApprovalSink, PermissionEngine, PermissionRules } from "@chantier/permissions";
+//#region src/todo.d.ts
+/**
+ * Frozen v0.6.0 contract (spec /home/debian/portfolio/chantier/v06-spec.md
+ * §Frozen contract): the todo-checklist step shape shared by the core tool,
+ * the store, and the TUI. Types only — Worker CoreExt implements the tool;
+ * the TUI worker implements the store fields and rendering.
+ */
+/** One checklist row. Whole-list replace per call; at most one in_progress. */
+interface TodoStep {
+  readonly content: string;
+  readonly status: "pending" | "in_progress" | "completed";
+}
+/**
+ * The todo tool factory. The tool replaces the whole checklist per call and
+ * enforces the exactly-one-in_progress invariant (normalizing extras to
+ * pending). `onTodo` receives every accepted list; the CLI loop forwards it
+ * to the TUI store.
+ */
+type CreateTodoTool = (deps: {
+  onTodo: (steps: readonly TodoStep[]) => void;
+}) => ToolDefinition;
+/**
+ * The `todo` tool: whole-list checklist replace with the
+ * exactly-one-in_progress invariant (extras normalize to pending, first
+ * keeps the slot). readOnly: the checklist mutates nothing on disk.
+ */
+export declare function createTodoTool(deps: {
+  onTodo: (steps: readonly TodoStep[]) => void;
+}): ToolDefinition;
+/**
+ * Lenient row normalization: drops non-object/blank rows, coerces unknown
+ * statuses to pending, and enforces exactly one in_progress (the first keeps
+ * the slot; extras become pending).
+ */
+export declare function normalizeTodoSteps(raw: readonly unknown[]): readonly TodoStep[];
+/** One-line summary the model sees: counts per status in fixed order. */
+export declare function summarizeTodoSteps(steps: readonly TodoStep[]): string;
+//#endregion
 //#region src/types.d.ts
 interface TextBlock {
   type: "text";
@@ -78,6 +116,12 @@ interface ToolContext {
   session: SessionStore;
   permission: PermissionEngine;
   signal: AbortSignal;
+  /**
+   * v0.6: live todo-trail hook. The todo tool forwards each accepted
+   * checklist to it; the interactive loop binds it to the TUI store.
+   * Undefined = the checklist is accepted without a live consumer.
+   */
+  onTodo?: (steps: readonly TodoStep[]) => void;
 }
 interface ToolDefinition {
   name: string;
@@ -203,6 +247,83 @@ interface RunAgentOptions {
  */
 export declare function runAgent(opts: RunAgentOptions): AsyncGenerator<AgentEvent>;
 //#endregion
+//#region src/commands.d.ts
+/**
+ * Frozen v0.6.0 contract (spec /home/debian/portfolio/chantier/v06-spec.md
+ * §Theme 3): the slash-command registry. Types only — Worker CoreExt
+ * implements the registry and dispatch; the TUI consumes `list()` for the
+ * palette. `/compact` semantics are preserved exactly (trimmed exact match
+ * dispatches; a slash-word that is not a registered command goes to the
+ * agent as a normal task).
+ */
+/** A registered slash command. `name` excludes the leading slash. */
+interface CommandSpec {
+  /** `[a-z0-9-]+` — the palette matches this string after `/`. */
+  readonly name: string;
+  /** One-line description shown in the palette and /help. */
+  readonly description: string;
+  /**
+   * "action" performs work itself (e.g. /compact); "expand" rewrites the
+   * task text (e.g. a skill fills the editor / injects its body).
+   */
+  readonly kind: "action" | "expand";
+}
+/** Registry surface the TUI palette relies on (implementation in core). */
+interface CommandRegistry {
+  register(spec: CommandSpec): void;
+  /** Stable order: registration order, built-ins first. */
+  list(): readonly CommandSpec[];
+}
+/**
+ * Core-agnostic IO surface actions render through. The TUI store satisfies
+ * it structurally (its pushItem accepts every TuiItem, including these).
+ */
+interface CommandIo {
+  /** Abort signal for the current prompt interaction (e.g. manual compaction). */
+  readonly signal: AbortSignal;
+  /** Appends one transcript line. */
+  pushItem(item: {
+    readonly kind: "info" | "divider" | "error";
+    readonly text: string;
+  }): void;
+}
+/** A registered action command: `run` performs the work itself. */
+interface ActionSpec extends CommandSpec {
+  readonly kind: "action";
+  /** Only exact `/name` dispatches (the /compact rule); args go to the agent verbatim. */
+  readonly run?: (io: CommandIo) => void | Promise<void>;
+}
+/** A registered expand command (e.g. a skill): rewrites the task text. */
+interface ExpandSpec extends CommandSpec {
+  readonly kind: "expand";
+  /**
+   * Receives the text after the command name ("" when none) and returns the
+   * replacement task. Async bodies (skill files) are awaited by dispatch.
+   */
+  readonly expand: (args: string) => string | Promise<string>;
+}
+type RegistrableCommand = ActionSpec | ExpandSpec;
+type DispatchResult = {
+  readonly kind: "handled";
+} | {
+  readonly kind: "expanded";
+  readonly task: string;
+} | {
+  readonly kind: "not-command";
+};
+interface CommandRegistryV6 extends CommandRegistry {
+  register(spec: RegistrableCommand): void;
+  /**
+   * Slash-command seam for the interactive loop. A trimmed task starting
+   * with `/` whose first word exactly matches a registered command
+   * dispatches; anything else is `not-command` (the task goes to the agent
+   * verbatim). Actions dispatch only on the exact `/name` form; expand
+   * commands receive the remaining text as args.
+   */
+  dispatch(task: string, io: CommandIo): Promise<DispatchResult>;
+}
+export declare function createCommandRegistry(): CommandRegistryV6;
+//#endregion
 //#region src/compaction.d.ts
 /**
  * Rough token estimate: ~4 characters per token for English/code text. Used
@@ -272,6 +393,54 @@ export declare function compactConversation(opts: CompactConversationOptions): P
 /** Builds the regular user message that carries the summary after compaction. */
 export declare function compactedSummaryMessage(summary: string): UserMessage;
 //#endregion
+//#region src/skills.d.ts
+/**
+ * Frozen v0.6.0 contract (spec /home/debian/portfolio/chantier/v06-spec.md
+ * §Theme 1): agentskills.io SKILL.md types. Types only — Worker CoreExt
+ * implements the loader (frontmatter parse, discovery, precedence, trust).
+ */
+/** Validated SKILL.md frontmatter (agentskills.io/specification subset). */
+interface SkillFrontmatter {
+  /** 1–64 chars, [a-z0-9-], no lead/trail/consecutive `-`. */
+  readonly name: string;
+  /** 1–1024 chars, what + when. */
+  readonly description: string;
+  readonly license?: string;
+  /** ≤500 chars. */
+  readonly compatibility?: string;
+  readonly metadata?: Readonly<Record<string, string>>;
+}
+/** A discovered skill; the body is NOT loaded (progressive disclosure). */
+interface Skill {
+  readonly name: string;
+  readonly description: string;
+  /** Absolute directory holding SKILL.md (body + bundled files resolve here). */
+  readonly dir: string;
+  readonly frontmatter: SkillFrontmatter;
+}
+/**
+ * Scan the given roots (each root = a directory of `<name>/SKILL.md`
+ * subdirectories). First occurrence per name wins (caller passes roots in
+ * precedence order); invalid skills are skipped with a one-line notice.
+ */
+type LoadSkills = (roots: readonly string[]) => Promise<readonly Skill[]>;
+/** Tier-2 load: the full markdown body below the frontmatter. */
+type LoadSkillBody = (skill: Skill) => Promise<string>;
+interface LoadSkillsOptions {
+  /** Called once per skipped-but-diagnosable skill with a one-line reason. */
+  onNotice?: (notice: string) => void;
+}
+/**
+ * Scans each root one level deep for `<name>/SKILL.md`. Roots are in
+ * precedence order (project before user; the caller decides) and the first
+ * occurrence of a name wins. Nonexistent or unreadable roots contribute
+ * nothing; unreadable directories are skipped silently; a skill whose
+ * frontmatter parses but fails validation is skipped with a one-line notice.
+ */
+export declare function loadSkills(roots: readonly string[], options?: LoadSkillsOptions): Promise<readonly Skill[]>;
+/** Tier-2 load: the full markdown body below the frontmatter delimiter. */
+export declare function loadSkillBody(skill: Skill): Promise<string>;
+//#endregion
 //#region src/context.d.ts
 /**
  * Per-model-family prompt profile. Only the identity section is
@@ -291,14 +460,15 @@ interface ModelProfile {
 export declare function resolveModelProfile(model: string): ModelProfile;
 /**
  * Builds the system prompt from fixed, blank-line-joined sections: environment,
- * identity (profile-adjustable), doing-tasks rules, denial rule, delegation
- * (only when a `task` tool is offered), tool catalog, tool rules, and every
- * AGENTS.md from cwd up to the git root last.
+ * identity (profile-adjustable), doing-tasks rules, todo usage (when the tool
+ * is offered), the tier-1 skill catalog (when skills are passed), denial rule,
+ * delegation (only when a `task` tool is offered), tool catalog, tool rules,
+ * and every AGENTS.md from cwd up to the git root last.
  *
  * `profile` omitted means the default profile: identity and tool rules keep
  * today's semantics, new sections are purely additive.
  */
-export declare function buildSystemPrompt(cwd: string, tools: ToolDefinition[], profile?: ModelProfile): Promise<string>;
+export declare function buildSystemPrompt(cwd: string, tools: ToolDefinition[], profile?: ModelProfile, skills?: readonly Skill[]): Promise<string>;
 //#endregion
 //#region src/session.d.ts
 export declare const DEFAULT_SESSIONS_ROOT: string;
@@ -419,4 +589,4 @@ export declare function spawnSubagent(input: {
   prompt: string;
 }, deps: SubagentDeps, ctx: ToolContext): Promise<SubagentResult>;
 //#endregion
-export type { AgentEvent, AssistantMessage, CompactConversationOptions, CompactSessionOptions, CompactionEntry, CompactionOptions, CompactionOutcome, CompactionResult, CreateSessionOptions, Message, ModelAdapter, ModelEvent, ModelProfile, ResumeSessionOptions, RunAgentOptions, SessionEntry, SessionHeader, SessionStore, StopReason, SubagentDeps, SubagentResult, SystemMessage, TextBlock, ToolCallBlock, ToolContext, ToolDefinition, ToolResultMessage, Usage, UserMessage };
+export type { ActionSpec, AgentEvent, AssistantMessage, CommandIo, CommandRegistryV6, CompactConversationOptions, CompactSessionOptions, CompactionEntry, CompactionOptions, CompactionOutcome, CompactionResult, CreateSessionOptions, CreateTodoTool, DispatchResult, ExpandSpec, LoadSkillBody, LoadSkills, LoadSkillsOptions, Message, ModelAdapter, ModelEvent, ModelProfile, RegistrableCommand, ResumeSessionOptions, RunAgentOptions, SessionEntry, SessionHeader, SessionStore, Skill, SkillFrontmatter, StopReason, SubagentDeps, SubagentResult, SystemMessage, TextBlock, TodoStep, ToolCallBlock, ToolContext, ToolDefinition, ToolResultMessage, Usage, UserMessage };

package/dist/index.mjs

@@ -669,6 +669,39 @@ async function executeCall(call, opts, byName) {
 	}
 }
 //#endregion
+//#region src/commands.ts
+const COMMAND_NAME_PATTERN = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+const COMMAND_NAME_MAX = 64;
+function createCommandRegistry() {
+	const commands = /* @__PURE__ */ new Map();
+	return {
+		register(spec) {
+			if (spec.name.length === 0 || spec.name.length > COMMAND_NAME_MAX || !COMMAND_NAME_PATTERN.test(spec.name)) throw new Error(`Invalid command name "${spec.name}" (1-${COMMAND_NAME_MAX} chars, [a-z0-9-], no lead/trail/double -).`);
+			if (commands.has(spec.name)) throw new Error(`Command "${spec.name}" is already registered.`);
+			if (spec.kind === "expand" && typeof spec.expand !== "function") throw new Error(`Expand command "${spec.name}" requires an expand function.`);
+			commands.set(spec.name, spec);
+		},
+		list: () => [...commands.values()],
+		async dispatch(task, io) {
+			const trimmed = task.trim();
+			if (!trimmed.startsWith("/")) return { kind: "not-command" };
+			const word = trimmed.slice(1).split(/\s+/, 1)[0] ?? "";
+			const spec = commands.get(word);
+			if (spec === void 0) return { kind: "not-command" };
+			if (spec.kind === "action") {
+				if (trimmed !== `/${spec.name}`) return { kind: "not-command" };
+				await spec.run?.(io);
+				return { kind: "handled" };
+			}
+			const args = trimmed.slice(1 + spec.name.length).trim();
+			return {
+				kind: "expanded",
+				task: await spec.expand(args)
+			};
+		}
+	};
+}
+//#endregion
 //#region src/context.ts
 /**
 * Tool-usage rules the model needs to drive the harness correctly.
@@ -694,6 +727,12 @@ const DOING_TASKS = `# Doing tasks
 - Comments explain WHY, not WHAT; skip them where the code already says it.
 - Verify behavioral changes by running the changed path, not by re-reading the edit.
 - State uncertainty plainly rather than guessing.`;
+/** Present in the prompt only when a tool named "todo" is offered. */
+const TODO_USAGE = `# Todo checklist
+
+For any task with more than a couple of steps, lay out the plan with the todo tool FIRST
+(one step in_progress, the rest pending), then keep the checklist current as you work:
+each update replaces the whole list, so re-send every row with its new status.`;
 const DENIALS = `# Permission denials
 
 A denied tool call is final for that exact invocation: never retry the identical
@@ -736,27 +775,52 @@ function resolveModelProfile(model) {
 }
 /**
 * Builds the system prompt from fixed, blank-line-joined sections: environment,
-* identity (profile-adjustable), doing-tasks rules, denial rule, delegation
-* (only when a `task` tool is offered), tool catalog, tool rules, and every
-* AGENTS.md from cwd up to the git root last.
+* identity (profile-adjustable), doing-tasks rules, todo usage (when the tool
+* is offered), the tier-1 skill catalog (when skills are passed), denial rule,
+* delegation (only when a `task` tool is offered), tool catalog, tool rules,
+* and every AGENTS.md from cwd up to the git root last.
 *
 * `profile` omitted means the default profile: identity and tool rules keep
 * today's semantics, new sections are purely additive.
 */
-async function buildSystemPrompt(cwd, tools, profile = DEFAULT_PROFILE) {
+async function buildSystemPrompt(cwd, tools, profile = DEFAULT_PROFILE, skills = []) {
 	const toolCatalog = tools.map((tool) => `- ${tool.name}${tool.readOnly ? " (read-only)" : ""}: ${tool.description.split(".")[0]}.`).join("\n");
 	const sections = [
 		await environmentSection(cwd),
 		profile.identity ?? IDENTITY,
-		DOING_TASKS,
-		DENIALS
+		DOING_TASKS
 	];
+	if (tools.some((tool) => tool.name === "todo")) sections.push(TODO_USAGE);
+	if (skills.length > 0) sections.push(skillsSection(skills));
+	sections.push(DENIALS);
 	if (tools.some((tool) => tool.name === "task")) sections.push(DELEGATION);
 	sections.push(`# Available tools\n\n${toolCatalog}`, TOOL_RULES);
 	const agentsDocs = await collectAgentsMd(cwd);
 	if (agentsDocs.length > 0) sections.push(`# Project instructions (AGENTS.md)\n\n${agentsDocs.join("\n\n")}`);
 	return sections.join("\n\n");
 }
+/** Tier-1 skill catalog: `name — description` rows, 200-char descriptions, ~2000-char cap. */
+const SKILL_DESCRIPTION_SHOWN = 200;
+const SKILL_CATALOG_CAP = 2e3;
+const SKILLS_INTRO = "# Skills\n\nSlash commands available (/name [args]) — invoking one injects the skill's full body into the task:";
+function skillsSection(skills) {
+	const kept = [];
+	let dropped = 0;
+	const render = () => {
+		const parts = [...kept];
+		if (dropped > 0) parts.push(`(+${dropped} more)`);
+		return [SKILLS_INTRO, ...parts].join("\n");
+	};
+	for (const skill of skills) {
+		const description = skill.description;
+		kept.push(`- ${skill.name} — ${description.length > SKILL_DESCRIPTION_SHOWN ? `${description.slice(0, SKILL_DESCRIPTION_SHOWN)}...` : description}`);
+		while (kept.length > 1 && render().length > SKILL_CATALOG_CAP) {
+			kept.shift();
+			dropped += 1;
+		}
+	}
+	return render();
+}
 /** Environment facts first; the branch line is omitted rather than fabricated. */
 async function environmentSection(cwd) {
 	const branch = await resolveBranch(await findGitRoot(path.resolve(cwd)));
@@ -814,6 +878,173 @@ async function findGitRoot(dir) {
 	}
 }
 //#endregion
+//#region src/skills.ts
+/** agentskills.io name rules: 1–64 chars, [a-z0-9-], no lead/trail/consecutive `-`. */
+const NAME_PATTERN = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+const NAME_MAX = 64;
+const DESCRIPTION_MAX = 1024;
+const COMPATIBILITY_MAX = 500;
+/**
+* Scans each root one level deep for `<name>/SKILL.md`. Roots are in
+* precedence order (project before user; the caller decides) and the first
+* occurrence of a name wins. Nonexistent or unreadable roots contribute
+* nothing; unreadable directories are skipped silently; a skill whose
+* frontmatter parses but fails validation is skipped with a one-line notice.
+*/
+async function loadSkills(roots, options = {}) {
+	const onNotice = options.onNotice;
+	const byName = /* @__PURE__ */ new Map();
+	for (const root of roots) {
+		let entries;
+		try {
+			entries = await readdir(root, { withFileTypes: true });
+		} catch {
+			continue;
+		}
+		for (const entry of entries) {
+			if (!entry.isDirectory()) continue;
+			const dir = path.join(root, entry.name);
+			let read;
+			try {
+				read = await readSkill(dir, entry.name, onNotice);
+			} catch {
+				continue;
+			}
+			if ("reason" in read) {
+				onNotice?.(`skill '${entry.name}' skipped: ${read.reason}`);
+				continue;
+			}
+			if (byName.has(read.skill.name)) {
+				onNotice?.(`skill '${read.skill.name}' from ${dir} skipped: duplicate name (first in precedence wins)`);
+				continue;
+			}
+			byName.set(read.skill.name, read.skill);
+		}
+	}
+	return [...byName.values()];
+}
+/** Tier-2 load: the full markdown body below the frontmatter delimiter. */
+async function loadSkillBody(skill) {
+	const doc = parseFrontmatter((await readFile(path.join(skill.dir, "SKILL.md"), "utf8")).replaceAll("\r\n", "\n"));
+	if (doc === void 0) return "";
+	return doc.body.trim();
+}
+/** Reads and validates one `<dir>/SKILL.md`; a validation failure skips it. */
+async function readSkill(dir, dirName, onNotice) {
+	let text;
+	try {
+		text = (await readFile(path.join(dir, "SKILL.md"), "utf8")).replaceAll("\r\n", "\n");
+	} catch {
+		return { reason: "no readable SKILL.md" };
+	}
+	const doc = parseFrontmatter(text);
+	if (doc === void 0) return { reason: "missing or malformed frontmatter (expects --- delimited YAML)" };
+	const name = doc.fields.name;
+	if (name === void 0 || name.length === 0) return { reason: "missing name" };
+	if (name.length > NAME_MAX || !NAME_PATTERN.test(name)) return { reason: `invalid name "${name}" (1-${NAME_MAX} chars, [a-z0-9-], no lead/trail/double -)` };
+	const description = doc.fields.description;
+	if (description === void 0 || description.length === 0) return { reason: "missing description" };
+	if (description.length > DESCRIPTION_MAX) return { reason: `description exceeds ${DESCRIPTION_MAX} chars (${description.length})` };
+	const compatibility = doc.fields.compatibility;
+	if (compatibility !== void 0 && compatibility.length > COMPATIBILITY_MAX) return { reason: `compatibility exceeds ${COMPATIBILITY_MAX} chars (${compatibility.length})` };
+	if (name !== dirName) onNotice?.(`skill '${dirName}': frontmatter name '${name}' ignored (name ≠ dir)`);
+	return { skill: {
+		name: dirName,
+		description,
+		dir,
+		frontmatter: {
+			name,
+			description,
+			...doc.fields.license === void 0 ? {} : { license: doc.fields.license },
+			...compatibility === void 0 ? {} : { compatibility },
+			...Object.keys(doc.metadata).length === 0 ? {} : { metadata: doc.metadata }
+		}
+	} };
+}
+/**
+* Line-based YAML frontmatter for the SKILL.md subset: `key: value` pairs
+* split on the FIRST colon per line, so unquoted colons inside values parse
+* (the gemini-cli bug); surrounding single/double quotes are stripped. Only
+* one nesting level is supported, under `metadata:`. Returns undefined when
+* the delimiters are missing or a line is not a plain `key: value` pair.
+*/
+function parseFrontmatter(text) {
+	const lines = text.split("\n");
+	if ((lines[0] ?? "").trimEnd() !== "---") return void 0;
+	const fields = {};
+	const metadata = {};
+	let inMetadata = false;
+	let bodyStart = -1;
+	let current;
+	const flush = () => {
+		if (current === void 0) return;
+		const folded = current.mode === void 0 ? current.value : current.mode === "fold" ? current.value.split("\n").map((line) => line.trim()).filter((line) => line.length > 0).join(" ") : current.value.replace(/^\n+/, "");
+		current.map[current.key] = folded.trim();
+		current = void 0;
+	};
+	for (let i = 1; i < lines.length; i += 1) {
+		const line = lines[i] ?? "";
+		if (line.trimEnd() === "---") {
+			flush();
+			bodyStart = i + 1;
+			break;
+		}
+		if (line.trim().length === 0) {
+			if (current !== void 0 && current.mode !== void 0) current.value += "\n";
+			continue;
+		}
+		if (/^\s/.test(line)) {
+			if (current !== void 0 && current.mode !== void 0) {
+				current.value += `\n${line.trim()}`;
+				continue;
+			}
+			if (inMetadata) {
+				const entry = splitKeyValue(line.trim());
+				if (entry === void 0) return void 0;
+				metadata[entry[0]] = entry[1];
+				continue;
+			}
+			return;
+		}
+		flush();
+		const pair = splitKeyValue(line);
+		if (pair === void 0) return void 0;
+		const indicator = /^[|>][+-]?\d*$/.exec(pair[1]);
+		if (indicator === null) {
+			inMetadata = pair[0] === "metadata" && pair[1].length === 0;
+			if (!inMetadata) fields[pair[0]] = pair[1];
+			continue;
+		}
+		inMetadata = false;
+		current = {
+			map: fields,
+			key: pair[0],
+			mode: indicator[0].startsWith("|") ? "keep" : "fold",
+			value: ""
+		};
+	}
+	if (bodyStart === -1) return void 0;
+	return {
+		fields,
+		metadata,
+		body: lines.slice(bodyStart).join("\n")
+	};
+}
+/**
+* Splits on the FIRST colon (values may contain colons), trims both sides,
+* and strips one pair of surrounding single/double quotes. Undefined for a
+* missing colon or an empty key.
+*/
+function splitKeyValue(line) {
+	const colon = line.indexOf(":");
+	if (colon <= 0) return void 0;
+	const key = line.slice(0, colon).trim();
+	if (key.length === 0) return void 0;
+	let value = line.slice(colon + 1).trim();
+	if (value.length >= 2 && (value.startsWith("\"") && value.endsWith("\"") || value.startsWith("'") && value.endsWith("'"))) value = value.slice(1, -1);
+	return [key, value];
+}
+//#endregion
 //#region src/subagent.ts
 /** The returned summary is capped at 50 KiB; the full transcript stays in the child session. */
 const SUMMARY_CAP_CHARS = 51200;
@@ -880,4 +1111,92 @@ async function spawnSubagent(input, deps, ctx) {
 	};
 }
 //#endregion
-export { COMPACTED_MARKER, COMPACT_PROMPT, DEFAULT_COMPACTION_KEEP_RECENT, DEFAULT_COMPACTION_RESERVE, DEFAULT_SESSIONS_ROOT, alignedMessageOrdinals, buildSystemPrompt, compactConversation, compactSession, compactedSummaryMessage, createSessionStore, estimateMessageTokens, estimateTokens, loadNewestSessionId, looksLikeContextOverflow, resolveModelProfile, resumeSessionStore, runAgent, serializeConversation, sessionView, sessionsDirFor, shouldCompact, spawnSubagent };
+//#region src/todo.ts
+/** Valid TodoStep status values, in checklist order. */
+const STATUSES = [
+	"pending",
+	"in_progress",
+	"completed"
+];
+/**
+* The `todo` tool: whole-list checklist replace with the
+* exactly-one-in_progress invariant (extras normalize to pending, first
+* keeps the slot). readOnly: the checklist mutates nothing on disk.
+*/
+function createTodoTool(deps) {
+	return {
+		name: "todo",
+		description: "Track a multi-step plan: replaces the whole checklist with `items` ({content, status: pending|in_progress|completed}). Exactly one step stays in_progress (extras normalize to pending); lay out the plan first and keep it current as you work. An empty list clears the checklist.",
+		inputSchema: {
+			type: "object",
+			properties: { items: {
+				type: "array",
+				description: "The full checklist; replaces the previous list wholesale.",
+				items: {
+					type: "object",
+					properties: {
+						content: {
+							type: "string",
+							description: "One imperative checklist row."
+						},
+						status: {
+							type: "string",
+							enum: [...STATUSES]
+						}
+					},
+					required: ["content", "status"]
+				}
+			} },
+			required: ["items"]
+		},
+		readOnly: true,
+		handler: async (input) => {
+			const raw = input.items;
+			if (!Array.isArray(raw)) return "Error: todo requires an `items` array of {content, status} rows.";
+			const steps = normalizeTodoSteps(raw);
+			if (steps.length === 0) {
+				deps.onTodo([]);
+				return "todo: list cleared";
+			}
+			deps.onTodo(steps);
+			return summarizeTodoSteps(steps);
+		}
+	};
+}
+/**
+* Lenient row normalization: drops non-object/blank rows, coerces unknown
+* statuses to pending, and enforces exactly one in_progress (the first keeps
+* the slot; extras become pending).
+*/
+function normalizeTodoSteps(raw) {
+	const steps = [];
+	let inProgressSeen = false;
+	for (const row of raw) {
+		if (typeof row !== "object" || row === null) continue;
+		const record = row;
+		const content = typeof record.content === "string" ? record.content.trim() : "";
+		if (content.length === 0) continue;
+		const status = STATUSES.find((candidate) => candidate === record.status) ?? "pending";
+		if (status === "in_progress" && inProgressSeen) {
+			steps.push({
+				content,
+				status: "pending"
+			});
+			continue;
+		}
+		if (status === "in_progress") inProgressSeen = true;
+		steps.push({
+			content,
+			status
+		});
+	}
+	return steps;
+}
+/** One-line summary the model sees: counts per status in fixed order. */
+function summarizeTodoSteps(steps) {
+	const done = steps.filter((step) => step.status === "completed").length;
+	const active = steps.filter((step) => step.status === "in_progress").length;
+	return `todo: ${done} done, ${active} in progress, ${steps.length - done - active} pending`;
+}
+//#endregion
+export { COMPACTED_MARKER, COMPACT_PROMPT, DEFAULT_COMPACTION_KEEP_RECENT, DEFAULT_COMPACTION_RESERVE, DEFAULT_SESSIONS_ROOT, alignedMessageOrdinals, buildSystemPrompt, compactConversation, compactSession, compactedSummaryMessage, createCommandRegistry, createSessionStore, createTodoTool, estimateMessageTokens, estimateTokens, loadNewestSessionId, loadSkillBody, loadSkills, looksLikeContextOverflow, normalizeTodoSteps, resolveModelProfile, resumeSessionStore, runAgent, serializeConversation, sessionView, sessionsDirFor, shouldCompact, spawnSubagent, summarizeTodoSteps };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chantier/core",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "type": "module",
   "license": "Apache-2.0",
   "description": "Agent loop, session store, and model-adapter seam for the chantier coding agent",
@@ -36,7 +36,7 @@
     "prepublishOnly": "npm run build"
   },
   "dependencies": {
-    "@chantier/permissions": "^0.5.0"
+    "@chantier/permissions": "^0.6.0"
   },
   "devDependencies": {
     "tsdown": "0.23.0"