@chantier/core 0.3.0 → 0.6.0

package/dist/index.d.mts

@@ -1,4 +1,42 @@
-import { ApprovalDetail, ApprovalSink, PermissionEngine } from "@chantier/permissions";
+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,9 +393,82 @@ 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
-/** Builds the system prompt: identity + tool rules + every AGENTS.md from cwd up to the git root. */
-export declare function buildSystemPrompt(cwd: string, tools: ToolDefinition[]): Promise<string>;
+/**
+ * Per-model-family prompt profile. Only the identity section is
+ * profile-specific; every other section is shared, fixed-order text.
+ */
+interface ModelProfile {
+  /** Family name, for diagnostics and tests. */
+  name: string;
+  /** Replaces the default identity paragraph when present. */
+  identity?: string;
+}
+/**
+ * Profile registry: family prefix match on the model id — `glm-` and `claude-`
+ * resolve their profiles, anything else the default. Prefixes match the leading
+ * id so suffixed tags (e.g. `glm-5.3-flash:cloud`) still resolve to the family.
+ */
+export declare function resolveModelProfile(model: string): ModelProfile;
+/**
+ * Builds the system prompt from fixed, blank-line-joined sections: environment,
+ * 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, skills?: readonly Skill[]): Promise<string>;
 //#endregion
 //#region src/session.d.ts
 export declare const DEFAULT_SESSIONS_ROOT: string;
@@ -350,4 +544,49 @@ export declare function compactSession(opts: CompactSessionOptions): Promise<Com
 /** `--continue`: newest session file (by mtime) in this cwd's session dir. */
 export declare function loadNewestSessionId(cwd: string, sessionsRoot?: string): Promise<string | null>;
 //#endregion
-export type { AgentEvent, AssistantMessage, CompactConversationOptions, CompactSessionOptions, CompactionEntry, CompactionOptions, CompactionOutcome, CompactionResult, CreateSessionOptions, Message, ModelAdapter, ModelEvent, ResumeSessionOptions, RunAgentOptions, SessionEntry, SessionHeader, SessionStore, StopReason, SystemMessage, TextBlock, ToolCallBlock, ToolContext, ToolDefinition, ToolResultMessage, Usage, UserMessage };
+//#region src/subagent.d.ts
+interface SubagentDeps {
+  /** The parent's model adapter; the child runs on the same provider/model seam. */
+  adapter: ModelAdapter;
+  /** The parent's settings rules, verbatim: deny rules bind the child, allow rules pre-approve. */
+  rules: PermissionRules;
+  /** The parent's approval sink: a child ask surfaces in the parent's approval UI. */
+  sink: ApprovalSink;
+  /** Provider label recorded in the child session header. */
+  provider: string;
+  model: string;
+  /** Child turn cap; defaults to 25. */
+  maxTurns?: number;
+  /**
+   * Declared model context window; opts the child into compaction (same
+   * contract as runAgent). Undefined keeps compaction off for the child.
+   */
+  contextWindow?: number;
+  /**
+   * The child's toolset. Phase A depth cap: the child toolset is the builtin
+   * set, which does not contain `task`, so a child cannot recurse by
+   * construction.
+   */
+  tools: ToolDefinition[];
+}
+interface SubagentResult {
+  /** The child's final summary text (50 KiB cap, see spawnSubagent). */
+  text: string;
+  /** The child's own session id, so the parent can reference/inspect the transcript. */
+  sessionId: string;
+  truncated: boolean;
+}
+/**
+ * Runs one child agent loop for a single `task` call and returns its final
+ * summary. Isolation is structural: a fresh permission engine per spawn (the
+ * parent's remembered grants never inherit; deny rules still win first), a
+ * fresh session store (the child transcript is its own JSONL file), and a
+ * task-free toolset. Child asks surface through the parent's sink, each one a
+ * fresh decision. `ctx.signal` propagates: on abort the child loop stops and
+ * the error surfaces as the parent's tool result.
+ */
+export declare function spawnSubagent(input: {
+  prompt: string;
+}, deps: SubagentDeps, ctx: ToolContext): Promise<SubagentResult>;
+//#endregion
+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

@@ -2,6 +2,7 @@ import { createHash, randomBytes } from "node:crypto";
 import { appendFile, mkdir, readFile, readdir, stat } from "node:fs/promises";
 import { homedir } from "node:os";
 import path from "node:path";
+import { createPermissionEngine, createRememberingEngine } from "@chantier/permissions";
 //#region src/compaction.ts
 /**
 * Rough token estimate: ~4 characters per token for English/code text. Used
@@ -195,8 +196,11 @@ function sessionsDirFor(sessionsRoot, cwd) {
 	const hash = createHash("sha256").update(cwd).digest("hex").slice(0, 12);
 	return path.join(sessionsRoot, hash);
 }
+let sequence = 0;
 function newSessionId() {
-	return `${(/* @__PURE__ */ new Date()).toISOString().replace(/[:.]/g, "-")}-${randomBytes(4).toString("hex")}`;
+	sequence = (sequence + 1) % 1679616;
+	const seq = sequence.toString(36).padStart(4, "0");
+	return `${(/* @__PURE__ */ new Date()).toISOString().replace(/[:.]/g, "-")}-${seq}${randomBytes(2).toString("hex")}`;
 }
 function buildStore(file, dir, id, selfId) {
 	const readEntries = async (loadId) => {
@@ -665,10 +669,44 @@ 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. */
-const TOOL_RULES = `
-# Tool usage rules
+/**
+* Tool-usage rules the model needs to drive the harness correctly.
+*/
+const TOOL_RULES = `# Tool usage rules
 
 - Paths are relative to the project cwd unless you pass an absolute path deliberately.
 - Protected paths (.env, .env.*, *.pem, id_rsa*, ~/.ssh) are refused by the harness; do not retry them.
@@ -680,17 +718,131 @@ const TOOL_RULES = `
 const IDENTITY = `You are chantier, a terminal coding agent. You work inside the user's project directory:
 read before you write, make surgical edits, and explain what you did in one short paragraph at the end
 of a task. When a mutation is denied, state it plainly and continue with what is allowed.`;
-/** Builds the system prompt: identity + tool rules + every AGENTS.md from cwd up to the git root. */
-async function buildSystemPrompt(cwd, tools) {
-	const toolCatalog = tools.map((tool) => `- ${tool.name}${tool.readOnly ? " (read-only)" : ""}: ${tool.description.split(".")[0]}.`).join("\n");
-	const agentsDocs = await collectAgentsMd(cwd);
-	const agentsSection = agentsDocs.length > 0 ? `\n# Project instructions (AGENTS.md)\n\n${agentsDocs.join("\n\n")}` : "";
-	return `${IDENTITY}
+/** Doing-tasks discipline shared by every model family. */
+const DOING_TASKS = `# Doing tasks
+
+- Prefer editing existing files over creating new ones.
+- Do exactly what was asked: no scope creep — no extra retries, telemetry, or
+  abstraction "while you're at it"; the real ask only.
+- 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
 
-# Available tools
+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
 
-${toolCatalog}
-${TOOL_RULES}${agentsSection}`;
+A denied tool call is final for that exact invocation: never retry the identical
+denied call. Adjust the arguments or switch the approach, or continue with what
+is allowed, and state plainly that the action was not permitted.`;
+/** Present in the prompt only when a tool named "task" is offered. */
+const DELEGATION = `# Delegating subtasks
+
+- Delegate self-contained subtasks with the full context the child needs in the
+  prompt (paths, constraints, acceptance); the child returns a final summary.
+- Scale the prompt effort to the subtask: brief for mechanical work, detailed
+  for design work.
+- Do not delegate single sequential edits you can do directly.`;
+/** Default semantics: today's identity, unchanged. */
+const DEFAULT_PROFILE = { name: "default" };
+const GLM_PROFILE = {
+	name: "glm",
+	identity: `You are chantier, a terminal coding agent working directly in the user's project directory.
+Style for this model family: keep prose terse; tool arguments are strict JSON
+objects with no trailing commentary inside tool calls; finish each task with one
+short final paragraph and nothing more. When a tool call is denied or fails,
+adjust the arguments or change the approach — never loop identical retries.`
+};
+const CLAUDE_PROFILE = {
+	name: "claude",
+	identity: `You are chantier, a terminal coding agent working directly in the user's project directory.
+Read before you write; strongly prefer editing existing files over creating new
+ones; do exactly the task asked with no scope creep; when something is unclear,
+say so plainly instead of guessing.`
+};
+/**
+* Profile registry: family prefix match on the model id — `glm-` and `claude-`
+* resolve their profiles, anything else the default. Prefixes match the leading
+* id so suffixed tags (e.g. `glm-5.3-flash:cloud`) still resolve to the family.
+*/
+function resolveModelProfile(model) {
+	if (model.startsWith("glm-")) return GLM_PROFILE;
+	if (model.startsWith("claude-")) return CLAUDE_PROFILE;
+	return DEFAULT_PROFILE;
+}
+/**
+* Builds the system prompt from fixed, blank-line-joined sections: environment,
+* 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, 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
+	];
+	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)));
+	const lines = [
+		"# Environment",
+		"",
+		`- cwd: ${cwd}`,
+		`- date: ${(/* @__PURE__ */ new Date()).toISOString().slice(0, 10)} (UTC)`
+	];
+	if (branch !== null) lines.push(`- branch: ${branch}`);
+	return lines.join("\n");
+}
+/**
+* Branch read from the filesystem, no git process spawned: `.git/HEAD` with
+* `ref: refs/heads/<name>` yields the name; a raw sha means detached. Missing
+* or unreadable HEAD → null → the caller omits the branch line.
+*/
+async function resolveBranch(gitRoot) {
+	if (gitRoot === null) return null;
+	const head = await readFile(path.join(gitRoot, ".git", "HEAD"), "utf8").catch(() => null);
+	if (head === null) return null;
+	return /^ref: refs\/heads\/(.+)$/.exec(head.trim())?.[1] ?? "(detached)";
 }
 /**
 * AGENTS.md discovery: walk from cwd to the git root. Files from ancestor
@@ -726,4 +878,325 @@ async function findGitRoot(dir) {
 	}
 }
 //#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, resumeSessionStore, runAgent, serializeConversation, sessionView, sessionsDirFor, shouldCompact };
+//#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;
+/** Children get their own (smaller) turn budget; the parent's cap says nothing about subtasks. */
+const DEFAULT_SUBAGENT_TURNS = 25;
+/**
+* Plain-string appendix for the child system prompt. Kept out of the composer
+* on purpose: the subagent role is a property of delegation, not of the
+* project's base prompt.
+*/
+const SUBAGENT_ROLE_APPENDIX = "\n\n# Subagent role\n\nYou are a subagent spawned by the parent agent to complete one self-contained task. Work within the prompt you were given, use the allowed tools, and end with a single short summary paragraph of what you did and found. Do not ask the user questions; decide and act.";
+/**
+* Runs one child agent loop for a single `task` call and returns its final
+* summary. Isolation is structural: a fresh permission engine per spawn (the
+* parent's remembered grants never inherit; deny rules still win first), a
+* fresh session store (the child transcript is its own JSONL file), and a
+* task-free toolset. Child asks surface through the parent's sink, each one a
+* fresh decision. `ctx.signal` propagates: on abort the child loop stops and
+* the error surfaces as the parent's tool result.
+*/
+async function spawnSubagent(input, deps, ctx) {
+	const childPermission = createRememberingEngine(createPermissionEngine(deps.rules));
+	const childSession = await createSessionStore({
+		cwd: ctx.cwd,
+		provider: deps.provider,
+		model: deps.model
+	});
+	const system = `${await buildSystemPrompt(ctx.cwd, deps.tools)}${SUBAGENT_ROLE_APPENDIX}`;
+	const userMessage = {
+		role: "user",
+		content: [{
+			type: "text",
+			text: input.prompt
+		}]
+	};
+	await childSession.append({
+		type: "message",
+		message: userMessage
+	});
+	let text = "";
+	for await (const event of runAgent({
+		adapter: deps.adapter,
+		tools: deps.tools,
+		permission: childPermission,
+		sink: deps.sink,
+		session: childSession,
+		cwd: ctx.cwd,
+		system,
+		messages: [userMessage],
+		maxTurns: deps.maxTurns ?? DEFAULT_SUBAGENT_TURNS,
+		contextWindow: deps.contextWindow,
+		compaction: deps.contextWindow === void 0 ? void 0 : { enabled: true },
+		signal: ctx.signal
+	})) if (event.type === "result") text = event.text;
+	if (text.length <= SUMMARY_CAP_CHARS) return {
+		text,
+		sessionId: childSession.id,
+		truncated: false
+	};
+	return {
+		text: `${text.slice(0, SUMMARY_CAP_CHARS)}\n[truncated: subagent summary exceeded 50 KiB cap; full transcript session id: ${childSession.id}]`,
+		sessionId: childSession.id,
+		truncated: true
+	};
+}
+//#endregion
+//#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.3.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.3.0"
+    "@chantier/permissions": "^0.6.0"
   },
   "devDependencies": {
     "tsdown": "0.23.0"