@chantier/core 0.3.0 → 0.5.0

package/dist/index.d.mts

@@ -1,4 +1,4 @@
-import { ApprovalDetail, ApprovalSink, PermissionEngine } from "@chantier/permissions";
+import { ApprovalDetail, ApprovalSink, PermissionEngine, PermissionRules } from "@chantier/permissions";
 //#region src/types.d.ts
 interface TextBlock {
   type: "text";
@@ -273,8 +273,32 @@ export declare function compactConversation(opts: CompactConversationOptions): P
 export declare function compactedSummaryMessage(summary: string): UserMessage;
 //#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, 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>;
 //#endregion
 //#region src/session.d.ts
 export declare const DEFAULT_SESSIONS_ROOT: string;
@@ -350,4 +374,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 { 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 };

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) => {
@@ -666,9 +670,10 @@ async function executeCall(call, opts, byName) {
 }
 //#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 +685,100 @@ 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.`;
+const DENIALS = `# Permission denials
 
-# Available tools
+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
 
-${toolCatalog}
-${TOOL_RULES}${agentsSection}`;
+- 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, 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) {
+	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
+	];
+	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");
+}
+/** 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 +814,70 @@ 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/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
+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 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chantier/core",
-  "version": "0.3.0",
+  "version": "0.5.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.5.0"
   },
   "devDependencies": {
     "tsdown": "0.23.0"