@chantier/core 0.3.0

package/CHANGELOG.md

@@ -0,0 +1,13 @@
+# Changelog
+
+All notable changes are documented in the root
+[CHANGELOG.md](../../CHANGELOG.md).
+
+## 0.3.0 — 2026-09-16
+
+- Compaction is a derived view over the append-only session log; callers drive
+  `compactSession`, with `/compact`, an automatic trigger near the context
+  window, and a reactive fallback.
+- `includeUsage` is requested from providers so token accounting stays exact.
+
+See the root changelog for the full list.

package/LICENSE

@@ -0,0 +1,190 @@
+                                 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
+
+      4. (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
+
+   Copyright 2026 DASHLEA × MLC
+
+   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,12 @@
+# @chantier/core
+
+Agent loop, session store, and the `ModelAdapter` seam for the
+[chantier](https://github.com/mlcassociation/chantier) coding agent. Sessions
+are plain JSONL under `~/.chantier/sessions/`; compaction is a derived view
+over that append-only log, never a rewrite of it.
+
+```ts
+import { runAgent, createSessionStore } from "@chantier/core";
+```
+
+License: Apache-2.0.

package/dist/index.d.mts

@@ -0,0 +1,353 @@
+import { ApprovalDetail, ApprovalSink, PermissionEngine } from "@chantier/permissions";
+//#region src/types.d.ts
+interface TextBlock {
+  type: "text";
+  text: string;
+}
+interface ToolCallBlock {
+  type: "tool-call";
+  id: string;
+  name: string;
+  args: Record<string, unknown>;
+}
+interface Usage {
+  inputTokens: number;
+  outputTokens: number;
+}
+interface SystemMessage {
+  role: "system";
+  content: string;
+}
+interface UserMessage {
+  role: "user";
+  content: Array<TextBlock>;
+}
+interface AssistantMessage {
+  role: "assistant";
+  content: Array<TextBlock | ToolCallBlock>;
+  usage?: Usage;
+}
+interface ToolResultMessage {
+  role: "tool-result";
+  toolCallId: string;
+  toolName: string;
+  content: string;
+}
+type Message = SystemMessage | UserMessage | AssistantMessage | ToolResultMessage;
+/**
+ * Marker appended to the JSONL when a compaction replaces the older part of the
+ * conversation with a summary. The log stays append-only: nothing is rewritten
+ * or deleted, `load()` always returns everything (TUI/rewind keep working), and
+ * `view()` folds compaction entries into the model-facing context.
+ *
+ * `firstKeptMessageIndex` is the 0-based ordinal of the first `message` entry
+ * that is kept verbatim after this compaction (the session header and
+ * compaction entries themselves are not counted). Ordinals are stable because
+ * the log is append-only — entries are never reordered, rewritten, or removed —
+ * so no entry ids are needed, and `--continue`/fork of an old file stays safe.
+ *
+ * Convention: the compaction entry is immediately followed by a regular `user`
+ * message entry carrying the summary text prefixed with COMPACTED_MARKER. The
+ * summary message is a real log entry (its ordinal is always >=
+ * firstKeptMessageIndex), so `view()` returns it naturally and resume flows
+ * stay plain `Message[]` with no synthetic messages.
+ */
+interface CompactionEntry {
+  type: "compaction";
+  summary: string;
+  firstKeptMessageIndex: number;
+  tokensBefore: number;
+  createdAt: string;
+}
+type StopReason = "end_turn" | "max_turns" | "error";
+type ModelEvent = {
+  type: "text-delta";
+  text: string;
+} | {
+  type: "tool-call";
+  id: string;
+  name: string;
+  args: Record<string, unknown>;
+} | {
+  type: "finish";
+  stopReason: StopReason;
+  usage?: Usage;
+};
+interface ToolContext {
+  cwd: string;
+  session: SessionStore;
+  permission: PermissionEngine;
+  signal: AbortSignal;
+}
+interface ToolDefinition {
+  name: string;
+  description: string;
+  inputSchema: {
+    type: "object";
+    properties: Record<string, unknown>;
+    required?: string[];
+  };
+  readOnly: boolean;
+  handler: (input: Record<string, unknown>, ctx: ToolContext) => Promise<string>;
+  /** How to extract the permission specifier (e.g. path, command) from input. */
+  specifier?: (input: Record<string, unknown>) => string | undefined;
+  /**
+   * Optional approval-UI metadata (e.g. a unified diff preview of the pending
+   * mutation), passed to the sink via ApprovalRequest.detail. Shape: ApprovalDetail
+   * from @chantier/permissions. Called with the same input the handler will
+   * receive; a returned undefined simply omits the metadata. May be async
+   * (e.g. reading the file to build a diff). Sinks that ignore detail are unaffected.
+   */
+  askDetail?: (input: Record<string, unknown>, ctx: ToolContext) => ApprovalDetail | undefined | Promise<ApprovalDetail | undefined>;
+}
+type SessionHeader = {
+  type: "session";
+  id: string;
+  cwd: string;
+  provider: string;
+  model: string;
+  createdAt: string;
+};
+type SessionEntry = SessionHeader | {
+  type: "message";
+  message: Message;
+} | CompactionEntry;
+/**
+ * `view` folds the append-only log into the model-facing context: the summary
+ * message convention replaces everything before the last compaction's
+ * `firstKeptMessageIndex`. Optional so lightweight fakes (tests) remain valid;
+ * real stores from this module always implement it, and
+ * `sessionView(store.load(id))` is the equivalent free-function form.
+ */
+interface SessionStore {
+  id: string;
+  dir: string;
+  append(entry: SessionEntry): Promise<void>;
+  load(id: string): Promise<SessionEntry[]>;
+  view?(id: string): Promise<Message[]>;
+}
+//#endregion
+//#region src/model-adapter.d.ts
+/**
+ * The provider seam. Core never imports a provider SDK; implementations live in
+ * `@chantier/providers` and translate into these events.
+ */
+interface ModelAdapter {
+  /** `messages` always starts with a SystemMessage (see core context assembly). */
+  stream(messages: Message[], tools: ToolDefinition[], signal: AbortSignal): AsyncIterable<ModelEvent>;
+}
+//#endregion
+//#region src/agent.d.ts
+type AgentEvent = {
+  type: "text-delta";
+  text: string;
+} | {
+  type: "tool-result";
+  toolCallId: string;
+  toolName: string;
+  args: Record<string, unknown>;
+  content: string;
+} | {
+  type: "compaction";
+  tokensBefore: number;
+  tokensAfter: number;
+  summaryChars: number;
+} | {
+  type: "result";
+  text: string;
+  usage?: Usage;
+  turns: number;
+  stopReason: "end_turn" | "max_turns";
+};
+interface CompactionOptions {
+  /** Compaction on/off; defaults to true when `contextWindow` is set. */
+  enabled?: boolean;
+  /** Headroom kept for the model's answer; see `shouldCompact`. */
+  reserve?: number;
+  /** Verbatim tail kept after compaction, in estimated tokens. */
+  keepRecent?: number;
+}
+interface RunAgentOptions {
+  adapter: ModelAdapter;
+  tools: ToolDefinition[];
+  permission: PermissionEngine;
+  sink: ApprovalSink;
+  session: SessionStore;
+  /** Project cwd; every tool handler resolves paths against it. */
+  cwd: string;
+  system: string;
+  /** Prior conversation (e.g. replayed on --continue); the system prompt is prepended once. */
+  messages?: Message[];
+  maxTurns?: number;
+  signal: AbortSignal;
+  /**
+   * Model context window in tokens. Undefined = compaction disabled; callers
+   * opt in by declaring the window they are targeting.
+   */
+  contextWindow?: number;
+  compaction?: CompactionOptions;
+}
+/**
+ * The boring loop: stream → accumulate → execute tools (denials feed back as
+ * results, never as error branching) → repeat until a turn has zero tool calls.
+ * Consecutive readOnly tool calls run concurrently, in the order the model
+ * emitted them; mutating calls run sequentially.
+ *
+ * Context management: when `contextWindow` is set, compaction is checked
+ * between turns (after tool results are appended, before the next stream) and
+ * once as a reactive fallback when a stream fails with a context-overflow
+ * error. Compaction replaces the in-memory context with summary + kept tail,
+ * appends one `compaction` entry plus the summary as a regular user message to
+ * the session log (the log stays append-only; `load()` is untouched), and
+ * preserves assistant tool-call / tool-result pairing.
+ */
+export declare function runAgent(opts: RunAgentOptions): AsyncGenerator<AgentEvent>;
+//#endregion
+//#region src/compaction.d.ts
+/**
+ * Rough token estimate: ~4 characters per token for English/code text. Used
+ * when a provider does not report usage; deliberately cheap and deterministic
+ * rather than accurate — the reserve/keepRecent margins absorb the error.
+ */
+export declare function estimateTokens(text: string): number;
+/** Compaction trigger margins, per the design dossier (§9.1). */
+export declare const DEFAULT_COMPACTION_RESERVE = 16000;
+export declare const DEFAULT_COMPACTION_KEEP_RECENT = 20000;
+/**
+ * Marker prefixing the summary message injected after a compaction. The same
+ * text is logged as a regular `user` message and re-built in memory, so the
+ * agent's live context and `view()` agree byte-for-byte.
+ */
+export declare const COMPACTED_MARKER = "[context compacted — earlier conversation summarized]\n\n";
+/** Fires when the next call would leave less than reserve + keepRecent of headroom. */
+export declare function shouldCompact(opts: {
+  tokensUsed: number;
+  window: number;
+  reserve?: number;
+  keepRecent?: number;
+}): boolean;
+/** Best-effort context-overflow detection: provider error texts vary widely. */
+export declare function looksLikeContextOverflow(error: unknown): boolean;
+/** Sums `estimateTokens` over messages; the chars/4 fallback for missing usage. */
+export declare function estimateMessageTokens(messages: readonly Message[]): number;
+/**
+ * Compact textual rendering of a conversation for the summarizer model.
+ * Deterministic and role-tagged; tool-call args are inlined as JSON.
+ */
+export declare function serializeConversation(messages: readonly Message[]): string;
+export declare const COMPACT_PROMPT = "You are summarizing a coding-agent conversation so the work can continue in a fresh context window. Write the summary as plain text with exactly these sections:\n\nACTIVE TASK\n- The user's current request and intent, in the user's own terms. Quote the latest instruction's original wording when it is precise.\n\nDECISIONS AND CONSTRAINTS\n- Key decisions made (with the why), invariants, preferences, and constraints that must not be violated.\n\nFILES AND CODE\n- Files read or modified, one line each: path, what was done or learned, and why it matters.\n\nUNRESOLVED THREADS\n- Open questions, pending next steps, and anything attempted that did not work (with the error).\n\nTO REMEMBER\n- Anything the user explicitly asked to remember, verbatim.\n\nRules: preserve exact identifiers, paths, commands, and error messages; do not invent facts; output nothing before or after the sections; be concise but complete — this summary replaces the conversation it summarizes.";
+interface CompactionResult {
+  /** Summarizer output for everything before the kept span. Empty = nothing to summarize. */
+  summary: string;
+  /** Tail of the input conversation that stays verbatim; never contains a SystemMessage. */
+  keptMessages: Message[];
+  /**
+   * Index into the `messages` input of the first kept message, so callers can
+   * align their own per-message metadata (keptMessages === messages.slice(keptStart)).
+   */
+  keptStart: number;
+  tokensBefore: number;
+  /** Estimated context size after re-injection (summary message + kept messages). */
+  estimatedAfter: number;
+}
+interface CompactConversationOptions {
+  adapter: ModelAdapter;
+  /**
+   * Full conversation, starting with the SystemMessage (the caller rebuilds it
+   * from the system prompt). The system message is never summarized and never
+   * returned in keptMessages.
+   */
+  messages: Message[];
+  keepRecent: number;
+  window: number;
+  reserve: number;
+  signal?: AbortSignal;
+}
+/**
+ * Summarizes everything except the most recent `keepRecent` tokens-worth of
+ * messages and returns the pieces for re-injection. Pure with respect to the
+ * session: it never mutates any store; callers decide what to append.
+ */
+export declare function compactConversation(opts: CompactConversationOptions): Promise<CompactionResult>;
+/** Builds the regular user message that carries the summary after compaction. */
+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>;
+//#endregion
+//#region src/session.d.ts
+export declare const DEFAULT_SESSIONS_ROOT: string;
+export declare function sessionsDirFor(sessionsRoot: string, cwd: string): string;
+interface CreateSessionOptions {
+  cwd: string;
+  provider: string;
+  model: string;
+  sessionsRoot?: string;
+  id?: string;
+}
+interface ResumeSessionOptions {
+  cwd: string;
+  sessionsRoot?: string;
+  id: string;
+}
+/** Creates a new session file and writes the header line immediately. */
+export declare function createSessionStore(opts: CreateSessionOptions): Promise<SessionStore>;
+/** Reattaches to an existing session file (--continue); no new header line. */
+export declare function resumeSessionStore(opts: ResumeSessionOptions): Promise<SessionStore>;
+/**
+ * Folds the append-only log into the model-facing context: everything with a
+ * message ordinal below the last compaction's `firstKeptMessageIndex` is
+ * replaced by that compaction's summary message (a regular logged `user`
+ * message — see `CompactionEntry`). Logs without compaction entries view as
+ * the plain message sequence, so old sessions and `--continue` stay safe.
+ *
+ * Two subtleties make this more than a filter:
+ * - The boundary is applied to the WHOLE log, not just entries after the
+ *   compaction marker: in the append order the kept tail is logged before the
+ *   compaction entry, so a forward pass alone would leak pre-boundary
+ *   messages into the view.
+ * - The summary message is hoisted to the front of the kept span. It is logged
+ *   after the boundary messages (append-only), but the model-facing context is
+ *   system + summary + kept tail — the live agent list and `view()` must
+ *   agree, and hoisting restores that order without touching the log.
+ */
+export declare function sessionView(entries: readonly SessionEntry[]): Message[];
+/**
+ * True log ordinals for `given` messages when they form a suffix of the log's
+ * view — the shape every flow this harness builds produces (`sessionView()`
+ * output plus messages appended after the last load, which land at the end).
+ * Returns null when the suffix match fails (e.g. a full replay of a compacted
+ * log, whose pre-boundary messages are absent from the view); callers fall
+ * back to the naive suffix-offset heuristic in that case. System messages are
+ * never logged; their slots stay null.
+ */
+export declare function alignedMessageOrdinals(entries: readonly SessionEntry[], given: readonly Message[]): Array<number | null> | null;
+interface CompactionOutcome {
+  tokensBefore: number;
+  tokensAfter: number;
+  summaryChars: number;
+}
+interface CompactSessionOptions {
+  store: SessionStore;
+  adapter: ModelAdapter;
+  /** The system prompt; never summarized, stays first in the next context. */
+  system: string;
+  contextWindow: number;
+  reserve?: number;
+  keepRecent?: number;
+  signal?: AbortSignal;
+}
+/**
+ * Caller-driven compaction between agent runs: estimates the current view and,
+ * when `shouldCompact` fires, summarizes everything but the recent tail and
+ * appends one compaction entry plus the summary message through the same
+ * append-only `SessionStore.append` seam the agent uses. Returns null when the
+ * estimate is under the threshold or the summarizer produced nothing (nothing
+ * to do); the caller re-derives the context with `sessionView(store.load())`.
+ */
+export declare function compactSession(opts: CompactSessionOptions): Promise<CompactionOutcome | null>;
+/** `--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 };

package/dist/index.mjs

@@ -0,0 +1,729 @@
+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";
+//#region src/compaction.ts
+/**
+* Rough token estimate: ~4 characters per token for English/code text. Used
+* when a provider does not report usage; deliberately cheap and deterministic
+* rather than accurate — the reserve/keepRecent margins absorb the error.
+*/
+function estimateTokens(text) {
+	return Math.ceil(text.length / 4);
+}
+/** Compaction trigger margins, per the design dossier (§9.1). */
+const DEFAULT_COMPACTION_RESERVE = 16e3;
+const DEFAULT_COMPACTION_KEEP_RECENT = 2e4;
+/**
+* Marker prefixing the summary message injected after a compaction. The same
+* text is logged as a regular `user` message and re-built in memory, so the
+* agent's live context and `view()` agree byte-for-byte.
+*/
+const COMPACTED_MARKER = "[context compacted — earlier conversation summarized]\n\n";
+/** Fires when the next call would leave less than reserve + keepRecent of headroom. */
+function shouldCompact(opts) {
+	const reserve = opts.reserve ?? 16e3;
+	const keepRecent = opts.keepRecent ?? 2e4;
+	return opts.tokensUsed >= opts.window - reserve - keepRecent;
+}
+/** Best-effort context-overflow detection: provider error texts vary widely. */
+function looksLikeContextOverflow(error) {
+	const text = error instanceof Error ? error.message : String(error);
+	return /context (?:length|window)|maximum context length|prompt is too long|input length exceeds|too many tokens|token limit|reduce the (?:length|number of tokens)/i.test(text);
+}
+/** Flat text rendering of a message for the estimator fallback. */
+function messageText(message) {
+	if (message.role === "system") return message.content;
+	if (message.role === "user") return message.content.map((block) => block.text).join("");
+	if (message.role === "assistant") return message.content.map((block) => {
+		if (block.type === "text") return block.text;
+		return `${block.name}${block.id}${JSON.stringify(block.args)}`;
+	}).join("");
+	return message.content;
+}
+/** Sums `estimateTokens` over messages; the chars/4 fallback for missing usage. */
+function estimateMessageTokens(messages) {
+	let tokens = 0;
+	for (const message of messages) tokens += estimateTokens(messageText(message));
+	return tokens;
+}
+/**
+* Compact textual rendering of a conversation for the summarizer model.
+* Deterministic and role-tagged; tool-call args are inlined as JSON.
+*/
+function serializeConversation(messages) {
+	const parts = [];
+	for (const message of messages) if (message.role === "system") parts.push(`[system]\n${message.content}`);
+	else if (message.role === "user") parts.push(`[user]\n${message.content.map((block) => block.text).join("\n")}`);
+	else if (message.role === "assistant") {
+		const blocks = message.content.map((block) => block.type === "text" ? block.text : `tool-call ${block.name} id=${block.id}: ${JSON.stringify(block.args)}`);
+		parts.push(`[assistant]\n${blocks.join("\n")}`);
+	} else parts.push(`[tool-result ${message.toolCallId} (${message.toolName})]\n${message.content}`);
+	return parts.join("\n\n");
+}
+const COMPACT_PROMPT = `You are summarizing a coding-agent conversation so the work can continue in a fresh context window. Write the summary as plain text with exactly these sections:
+
+ACTIVE TASK
+- The user's current request and intent, in the user's own terms. Quote the latest instruction's original wording when it is precise.
+
+DECISIONS AND CONSTRAINTS
+- Key decisions made (with the why), invariants, preferences, and constraints that must not be violated.
+
+FILES AND CODE
+- Files read or modified, one line each: path, what was done or learned, and why it matters.
+
+UNRESOLVED THREADS
+- Open questions, pending next steps, and anything attempted that did not work (with the error).
+
+TO REMEMBER
+- Anything the user explicitly asked to remember, verbatim.
+
+Rules: preserve exact identifiers, paths, commands, and error messages; do not invent facts; output nothing before or after the sections; be concise but complete — this summary replaces the conversation it summarizes.`;
+/** Old tool results are the biggest context sinks; prune them for summarization. */
+const TOOL_RESULT_PRUNE_CHARS = 800;
+function pruneToolResult(result) {
+	if (result.content.length <= TOOL_RESULT_PRUNE_CHARS) return result;
+	return {
+		...result,
+		content: `${result.content.slice(0, TOOL_RESULT_PRUNE_CHARS)}\n[...tool result truncated, ${result.content.length} chars total]`
+	};
+}
+/** Prunes oversized tool-result payloads from the span that gets summarized. */
+function pruneOldToolResults(messages) {
+	return messages.map((message) => message.role === "tool-result" ? pruneToolResult(message) : message);
+}
+function findAssistantWithCall(messages, from, toolCallId) {
+	for (let i = from; i >= 1; i -= 1) {
+		const message = messages[i];
+		if (message?.role === "assistant" && message.content.some((block) => block.type === "tool-call" && block.id === toolCallId)) return i;
+	}
+	return -1;
+}
+/**
+* Walks the boundary back until every kept tool-result has its assistant
+* tool-call inside the kept span (and therefore every kept call has its
+* result). Splitting a pair would 400 on strict APIs.
+*/
+function safeBoundary(messages, start) {
+	let boundary = start;
+	for (;;) {
+		const seen = /* @__PURE__ */ new Set();
+		let moved = false;
+		for (let i = boundary; i < messages.length; i += 1) {
+			const message = messages[i];
+			if (message === void 0) break;
+			if (message.role === "assistant") {
+				for (const block of message.content) if (block.type === "tool-call") seen.add(block.id);
+			} else if (message.role === "tool-result" && !seen.has(message.toolCallId)) {
+				const assistantIndex = findAssistantWithCall(messages, i - 1, message.toolCallId);
+				if (assistantIndex < 1) return 1;
+				boundary = assistantIndex;
+				moved = true;
+				break;
+			}
+		}
+		if (!moved) return boundary;
+	}
+}
+/**
+* Summarizes everything except the most recent `keepRecent` tokens-worth of
+* messages and returns the pieces for re-injection. Pure with respect to the
+* session: it never mutates any store; callers decide what to append.
+*/
+async function compactConversation(opts) {
+	const { adapter, messages, keepRecent, window, reserve } = opts;
+	if (messages[0]?.role !== "system") throw new Error("compactConversation: messages must start with the SystemMessage");
+	if (window - reserve - keepRecent <= 0) throw new RangeError(`compaction cannot fit: window ${window} must exceed reserve ${reserve} + keepRecent ${keepRecent}`);
+	let acc = 0;
+	let boundary = messages.length;
+	while (boundary > 1 && acc < keepRecent) {
+		boundary -= 1;
+		const message = messages[boundary];
+		if (message !== void 0) acc += estimateTokens(messageText(message));
+	}
+	const keptStart = safeBoundary(messages, boundary);
+	const summarizedSpan = messages.slice(1, keptStart);
+	const keptMessages = messages.slice(keptStart);
+	const tokensBefore = estimateMessageTokens(messages);
+	const keptTokens = estimateMessageTokens(keptMessages);
+	if (summarizedSpan.length === 0) return {
+		summary: "",
+		keptMessages,
+		keptStart,
+		tokensBefore,
+		estimatedAfter: keptTokens
+	};
+	const summary = await summarizeWithAdapter(adapter, serializeConversation(pruneOldToolResults(summarizedSpan)), opts.signal);
+	return {
+		summary,
+		keptMessages,
+		keptStart,
+		tokensBefore,
+		estimatedAfter: estimateTokens(COMPACTED_MARKER + summary) + keptTokens
+	};
+}
+const EMPTY_SIGNAL = new AbortController().signal;
+async function summarizeWithAdapter(adapter, conversationText, signal) {
+	const messages = [{
+		role: "system",
+		content: "You summarize coding-agent conversations. Output only the requested summary sections as plain text."
+	}, {
+		role: "user",
+		content: [{
+			type: "text",
+			text: `${COMPACT_PROMPT}\n\n<conversation>\n${conversationText}\n</conversation>`
+		}]
+	}];
+	let text = "";
+	for await (const event of adapter.stream(messages, [], signal ?? EMPTY_SIGNAL)) if (event.type === "text-delta") text += event.text;
+	return text.trim();
+}
+/** Builds the regular user message that carries the summary after compaction. */
+function compactedSummaryMessage(summary) {
+	return {
+		role: "user",
+		content: [{
+			type: "text",
+			text: `${COMPACTED_MARKER}${summary}`
+		}]
+	};
+}
+//#endregion
+//#region src/session.ts
+const DEFAULT_SESSIONS_ROOT = path.join(homedir(), ".chantier", "sessions");
+function sessionsDirFor(sessionsRoot, cwd) {
+	const hash = createHash("sha256").update(cwd).digest("hex").slice(0, 12);
+	return path.join(sessionsRoot, hash);
+}
+function newSessionId() {
+	return `${(/* @__PURE__ */ new Date()).toISOString().replace(/[:.]/g, "-")}-${randomBytes(4).toString("hex")}`;
+}
+function buildStore(file, dir, id, selfId) {
+	const readEntries = async (loadId) => {
+		const target = loadId === selfId ? file : path.join(dir, `${loadId}.jsonl`);
+		return (await readFile(target, "utf8")).split("\n").filter((line) => line.length > 0).map((line) => JSON.parse(line));
+	};
+	return {
+		id,
+		dir,
+		async append(entry) {
+			await appendFile(file, `${JSON.stringify(entry)}\n`);
+		},
+		load: readEntries,
+		async view(viewId) {
+			return sessionView(await readEntries(viewId));
+		}
+	};
+}
+/** Creates a new session file and writes the header line immediately. */
+async function createSessionStore(opts) {
+	const dir = sessionsDirFor(opts.sessionsRoot ?? DEFAULT_SESSIONS_ROOT, opts.cwd);
+	await mkdir(dir, { recursive: true });
+	const id = opts.id ?? newSessionId();
+	const file = path.join(dir, `${id}.jsonl`);
+	const header = {
+		type: "session",
+		id,
+		cwd: opts.cwd,
+		provider: opts.provider,
+		model: opts.model,
+		createdAt: (/* @__PURE__ */ new Date()).toISOString()
+	};
+	await appendFile(file, `${JSON.stringify(header)}\n`);
+	return buildStore(file, dir, id, id);
+}
+/** Reattaches to an existing session file (--continue); no new header line. */
+async function resumeSessionStore(opts) {
+	const dir = sessionsDirFor(opts.sessionsRoot ?? DEFAULT_SESSIONS_ROOT, opts.cwd);
+	return buildStore(path.join(dir, `${opts.id}.jsonl`), dir, opts.id, opts.id);
+}
+/**
+* Folds the append-only log into the model-facing context: everything with a
+* message ordinal below the last compaction's `firstKeptMessageIndex` is
+* replaced by that compaction's summary message (a regular logged `user`
+* message — see `CompactionEntry`). Logs without compaction entries view as
+* the plain message sequence, so old sessions and `--continue` stay safe.
+*
+* Two subtleties make this more than a filter:
+* - The boundary is applied to the WHOLE log, not just entries after the
+*   compaction marker: in the append order the kept tail is logged before the
+*   compaction entry, so a forward pass alone would leak pre-boundary
+*   messages into the view.
+* - The summary message is hoisted to the front of the kept span. It is logged
+*   after the boundary messages (append-only), but the model-facing context is
+*   system + summary + kept tail — the live agent list and `view()` must
+*   agree, and hoisting restores that order without touching the log.
+*/
+function sessionView(entries) {
+	return viewWithOrdinals(entries).map((viewed) => viewed.message);
+}
+/** `sessionView` with ordinals, shared by the alignment and compaction helpers. */
+function viewWithOrdinals(entries) {
+	let keptFrom = 0;
+	for (const entry of entries) if (entry.type === "compaction") keptFrom = Math.max(keptFrom, entry.firstKeptMessageIndex);
+	let hoisted;
+	let hoistedOrdinal = -1;
+	let lastCompaction = -1;
+	for (let i = 0; i < entries.length; i += 1) if (entries[i]?.type === "compaction") lastCompaction = i;
+	if (lastCompaction >= 0) {
+		const next = entries[lastCompaction + 1];
+		if (next?.type === "message" && next.message.role === "user" && next.message.content[0]?.type === "text" && next.message.content[0].text.startsWith("[context compacted — earlier conversation summarized]\n\n")) hoisted = next.message;
+	}
+	const view = [];
+	let ordinal = 0;
+	for (const entry of entries) {
+		if (entry.type !== "message") continue;
+		if (entry.message === hoisted) hoistedOrdinal = ordinal;
+		else if (ordinal >= keptFrom) view.push({
+			message: entry.message,
+			ordinal
+		});
+		ordinal += 1;
+	}
+	if (hoisted !== void 0) view.unshift({
+		message: hoisted,
+		ordinal: hoistedOrdinal
+	});
+	return view;
+}
+/**
+* True log ordinals for `given` messages when they form a suffix of the log's
+* view — the shape every flow this harness builds produces (`sessionView()`
+* output plus messages appended after the last load, which land at the end).
+* Returns null when the suffix match fails (e.g. a full replay of a compacted
+* log, whose pre-boundary messages are absent from the view); callers fall
+* back to the naive suffix-offset heuristic in that case. System messages are
+* never logged; their slots stay null.
+*/
+function alignedMessageOrdinals(entries, given) {
+	const view = viewWithOrdinals(entries);
+	const result = new Array(given.length).fill(null);
+	let cursor = view.length - 1;
+	for (let i = given.length - 1; i >= 0; i -= 1) {
+		const message = given[i];
+		if (message === void 0) return null;
+		if (message.role === "system") continue;
+		let viewed = view[cursor];
+		while (cursor >= 0 && viewed !== void 0 && JSON.stringify(viewed.message) !== JSON.stringify(message)) {
+			cursor -= 1;
+			viewed = view[cursor];
+		}
+		if (viewed === void 0) return null;
+		result[i] = viewed.ordinal;
+		cursor -= 1;
+	}
+	return result;
+}
+/**
+* Caller-driven compaction between agent runs: estimates the current view and,
+* when `shouldCompact` fires, summarizes everything but the recent tail and
+* appends one compaction entry plus the summary message through the same
+* append-only `SessionStore.append` seam the agent uses. Returns null when the
+* estimate is under the threshold or the summarizer produced nothing (nothing
+* to do); the caller re-derives the context with `sessionView(store.load())`.
+*/
+async function compactSession(opts) {
+	const reserve = opts.reserve ?? 16e3;
+	const keepRecent = opts.keepRecent ?? 2e4;
+	const entries = await opts.store.load(opts.store.id);
+	const view = viewWithOrdinals(entries);
+	const messages = [{
+		role: "system",
+		content: opts.system
+	}, ...view.map((viewed) => viewed.message)];
+	if (!shouldCompact({
+		tokensUsed: estimateMessageTokens(messages),
+		window: opts.contextWindow,
+		reserve,
+		keepRecent
+	})) return null;
+	const kept = await compactConversation({
+		adapter: opts.adapter,
+		messages,
+		keepRecent,
+		window: opts.contextWindow,
+		reserve,
+		signal: opts.signal
+	});
+	if (kept.summary.length === 0) return null;
+	const loggedCount = entries.reduce((count, entry) => entry.type === "message" ? count + 1 : count, 0);
+	const firstKept = view[kept.keptStart - 1];
+	const entry = {
+		type: "compaction",
+		summary: kept.summary,
+		firstKeptMessageIndex: firstKept?.ordinal ?? loggedCount,
+		tokensBefore: kept.tokensBefore,
+		createdAt: (/* @__PURE__ */ new Date()).toISOString()
+	};
+	await opts.store.append(entry);
+	await opts.store.append({
+		type: "message",
+		message: compactedSummaryMessage(kept.summary)
+	});
+	return {
+		tokensBefore: kept.tokensBefore,
+		tokensAfter: kept.estimatedAfter,
+		summaryChars: kept.summary.length
+	};
+}
+/** `--continue`: newest session file (by mtime) in this cwd's session dir. */
+async function loadNewestSessionId(cwd, sessionsRoot = DEFAULT_SESSIONS_ROOT) {
+	const dir = sessionsDirFor(sessionsRoot, cwd);
+	let files;
+	try {
+		files = await readdir(dir);
+	} catch {
+		return null;
+	}
+	const jsonl = files.filter((name) => name.endsWith(".jsonl"));
+	if (jsonl.length === 0) return null;
+	let newest = null;
+	for (const name of jsonl) {
+		const info = await stat(path.join(dir, name));
+		if (newest === null || info.mtimeMs > newest.mtimeMs || info.mtimeMs === newest.mtimeMs && name > newest.name) newest = {
+			name,
+			mtimeMs: info.mtimeMs
+		};
+	}
+	return newest ? newest.name.replace(/\.jsonl$/, "") : null;
+}
+//#endregion
+//#region src/agent.ts
+const HEADLESS_HINT = "rerun with --yolo or add an allow rule to .chantier/settings.json";
+/**
+* The boring loop: stream → accumulate → execute tools (denials feed back as
+* results, never as error branching) → repeat until a turn has zero tool calls.
+* Consecutive readOnly tool calls run concurrently, in the order the model
+* emitted them; mutating calls run sequentially.
+*
+* Context management: when `contextWindow` is set, compaction is checked
+* between turns (after tool results are appended, before the next stream) and
+* once as a reactive fallback when a stream fails with a context-overflow
+* error. Compaction replaces the in-memory context with summary + kept tail,
+* appends one `compaction` entry plus the summary as a regular user message to
+* the session log (the log stays append-only; `load()` is untouched), and
+* preserves assistant tool-call / tool-result pairing.
+*/
+async function* runAgent(opts) {
+	const maxTurns = opts.maxTurns ?? 50;
+	const byName = new Map(opts.tools.map((tool) => [tool.name, tool]));
+	const system = {
+		role: "system",
+		content: opts.system
+	};
+	const messages = [system, ...opts.messages ?? []];
+	const available = opts.tools.filter((tool) => !opts.permission.isRemoved(tool.name));
+	const contextWindow = opts.contextWindow;
+	const compactionEnabled = contextWindow !== void 0 && (opts.compaction?.enabled ?? true);
+	const reserve = opts.compaction?.reserve ?? 16e3;
+	const keepRecent = opts.compaction?.keepRecent ?? 2e4;
+	/**
+	* Ordinal of each message within the session log's message-entry sequence
+	* (the header and compaction entries are not counted; null = never logged,
+	* i.e. the system message). Maintained even when compaction is off — it is
+	* then garbage but never read.
+	*/
+	const ordinals = [null];
+	let nextOrdinal = 0;
+	if (compactionEnabled) {
+		const priorEntries = await opts.session.load(opts.session.id);
+		const logged = priorEntries.reduce((count, entry) => entry.type === "message" ? count + 1 : count, 0);
+		const given = opts.messages ?? [];
+		const aligned = alignedMessageOrdinals(priorEntries, given);
+		if (aligned !== null) ordinals.push(...aligned);
+		else {
+			const offset = Math.max(0, logged - given.filter((message) => message.role !== "system").length);
+			let seen = 0;
+			for (const message of given) {
+				if (message.role === "system") {
+					ordinals.push(null);
+					continue;
+				}
+				ordinals.push(offset + seen);
+				seen += 1;
+			}
+		}
+		nextOrdinal = logged;
+	} else ordinals.push(...(opts.messages ?? []).map(() => null));
+	let usage;
+	let turns = 0;
+	let lastText = "";
+	const appendMessage = async (message) => {
+		messages.push(message);
+		ordinals.push(nextOrdinal);
+		await opts.session.append({
+			type: "message",
+			message
+		});
+	};
+	/**
+	* Runs one compaction against the current context and rewires the live
+	* message list (system + summary message + kept tail). Never throws: a
+	* failed compaction keeps the run going uncompacted. Appends the compaction
+	* entry (which carries the summary) and the summary message to the log.
+	*/
+	const runCompaction = async () => {
+		if (!compactionEnabled || contextWindow === void 0) return null;
+		let kept;
+		try {
+			kept = await compactConversation({
+				adapter: opts.adapter,
+				messages,
+				keepRecent,
+				window: contextWindow,
+				reserve,
+				signal: opts.signal
+			});
+		} catch {
+			return null;
+		}
+		if (kept.summary.length === 0) return null;
+		const keptOrdinals = ordinals.slice(kept.keptStart);
+		const entry = {
+			type: "compaction",
+			summary: kept.summary,
+			firstKeptMessageIndex: keptOrdinals[0] ?? nextOrdinal,
+			tokensBefore: kept.tokensBefore,
+			createdAt: (/* @__PURE__ */ new Date()).toISOString()
+		};
+		await opts.session.append(entry);
+		const summaryMessage = compactedSummaryMessage(kept.summary);
+		await opts.session.append({
+			type: "message",
+			message: summaryMessage
+		});
+		messages.splice(0, messages.length, system, summaryMessage, ...kept.keptMessages);
+		ordinals.splice(0, ordinals.length, null, nextOrdinal, ...keptOrdinals);
+		nextOrdinal += 1;
+		return {
+			tokensBefore: kept.tokensBefore,
+			tokensAfter: kept.estimatedAfter,
+			summaryChars: kept.summary.length
+		};
+	};
+	while (turns < maxTurns) {
+		turns += 1;
+		let turnText = "";
+		const toolCalls = [];
+		let turnStart = messages.length;
+		let overflowError;
+		for (;;) {
+			turnText = "";
+			toolCalls.length = 0;
+			try {
+				for await (const event of opts.adapter.stream(messages, available, opts.signal)) if (event.type === "text-delta") {
+					turnText += event.text;
+					yield event;
+				} else if (event.type === "tool-call") toolCalls.push({
+					type: "tool-call",
+					id: event.id,
+					name: event.name,
+					args: event.args
+				});
+				else usage = event.usage;
+				break;
+			} catch (error) {
+				if (!looksLikeContextOverflow(error)) throw error;
+				if (overflowError !== void 0) throw overflowError;
+				overflowError = error;
+				const outcome = await runCompaction();
+				if (outcome === null) throw error;
+				turnStart = messages.length;
+				yield {
+					type: "compaction",
+					...outcome
+				};
+			}
+		}
+		await appendMessage({
+			role: "assistant",
+			content: [...turnText.length > 0 ? [{
+				type: "text",
+				text: turnText
+			}] : [], ...toolCalls]
+		});
+		if (toolCalls.length === 0) {
+			yield {
+				type: "result",
+				text: turnText,
+				usage,
+				turns,
+				stopReason: "end_turn"
+			};
+			return;
+		}
+		lastText = turnText;
+		for (const group of consecutiveReadOnlyGroups(toolCalls, byName)) {
+			const results = await Promise.all(group.map((call) => executeCall(call, opts, byName)));
+			for (const [index, result] of results.entries()) {
+				await appendMessage(result);
+				yield {
+					type: "tool-result",
+					toolCallId: result.toolCallId,
+					toolName: result.toolName,
+					args: group[index]?.args ?? {},
+					content: result.content
+				};
+			}
+		}
+		if (compactionEnabled && contextWindow !== void 0) {
+			const turnDelta = messages.slice(turnStart);
+			if (shouldCompact({
+				tokensUsed: usage ? usage.inputTokens + usage.outputTokens + estimateMessageTokens(turnDelta) : estimateMessageTokens(messages),
+				window: contextWindow,
+				reserve,
+				keepRecent
+			})) {
+				const outcome = await runCompaction();
+				if (outcome !== null) yield {
+					type: "compaction",
+					...outcome
+				};
+			}
+		}
+	}
+	yield {
+		type: "result",
+		text: lastText,
+		usage,
+		turns: maxTurns,
+		stopReason: "max_turns"
+	};
+}
+/** Groups consecutive readOnly calls; the first mutating call breaks the run. */
+function* consecutiveReadOnlyGroups(calls, byName) {
+	let group = [];
+	for (const call of calls) {
+		if (byName.get(call.name)?.readOnly === true) {
+			group.push(call);
+			continue;
+		}
+		if (group.length > 0) {
+			yield group;
+			group = [];
+		}
+		yield [call];
+	}
+	if (group.length > 0) yield group;
+}
+async function executeCall(call, opts, byName) {
+	const base = {
+		role: "tool-result",
+		toolCallId: call.id,
+		toolName: call.name
+	};
+	const tool = byName.get(call.name);
+	if (tool === void 0) return {
+		...base,
+		content: `Permission denied: tool "${call.name}" is not available. It was removed by a deny rule or does not exist. Use one of the listed tools.`
+	};
+	const ctx = {
+		cwd: opts.cwd,
+		session: opts.session,
+		permission: opts.permission,
+		signal: opts.signal
+	};
+	const specifier = tool.specifier?.(call.args);
+	const decision = opts.permission.evaluate(call.name, specifier, tool.readOnly);
+	if (decision === "deny") return {
+		...base,
+		content: `Permission denied: ${call.name}(${specifier ?? ""}) is denied by permission rules. This decision is final; do not retry this call.`
+	};
+	if (decision === "ask") {
+		let detail;
+		try {
+			detail = await tool.askDetail?.(call.args, ctx);
+		} catch {
+			detail = void 0;
+		}
+		const approval = await opts.sink.ask({
+			tool: call.name,
+			input: call.args,
+			reason: specifier === void 0 ? call.name : `${call.name} ${specifier}`,
+			detail
+		});
+		if (!approval.approved) {
+			const reason = approval.reason ?? `the request was not approved (${HEADLESS_HINT})`;
+			return {
+				...base,
+				content: `Permission denied: ${call.name}(${specifier ?? ""}) was not approved. ${reason}`
+			};
+		}
+	}
+	try {
+		const content = await tool.handler(call.args, ctx);
+		return {
+			...base,
+			content
+		};
+	} catch (error) {
+		const description = error instanceof Error ? error.message : String(error);
+		return {
+			...base,
+			content: `Error: tool ${call.name} failed: ${description}. Adjust the arguments and retry if useful.`
+		};
+	}
+}
+//#endregion
+//#region src/context.ts
+/** 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.
+- read returns numbered lines; use offset/limit to window big files instead of re-reading everything.
+- edit requires an exact unique oldString; include surrounding context when text is not unique.
+- write refuses to overwrite a multi-line file without overwrite: true; prefer edit for targeted changes.
+- Tool output is truncated at a character cap; note the [truncated] marker and read narrower ranges.
+`;
+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}
+
+# Available tools
+
+${toolCatalog}
+${TOOL_RULES}${agentsSection}`;
+}
+/**
+* AGENTS.md discovery: walk from cwd to the git root. Files from ancestor
+* directories come first, the nearest file last (nearer = later in context).
+* No @import expansion in v0.1 (planned for v0.2).
+*/
+async function collectAgentsMd(cwd) {
+	const docs = [];
+	const dir = path.resolve(cwd);
+	const stop = await findGitRoot(dir);
+	stop ?? path.parse(dir).root;
+	const chain = [];
+	for (let current = dir;; current = path.dirname(current)) {
+		chain.push(current);
+		if (current === stop || current === path.parse(current).root) break;
+	}
+	for (const candidate of chain.reverse()) {
+		const file = path.join(candidate, "AGENTS.md");
+		if ((await stat(file).catch(() => null))?.isFile() === true) {
+			const content = await readFile(file, "utf8");
+			if (content.trim().length > 0) docs.push(`--- ${file} ---\n${content.trim()}`);
+		}
+	}
+	return docs;
+}
+async function findGitRoot(dir) {
+	let current = path.resolve(dir);
+	for (;;) {
+		if (await stat(path.join(current, ".git")).catch(() => null) !== null) return current;
+		const parent = path.dirname(current);
+		if (parent === current) return null;
+		current = parent;
+	}
+}
+//#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 };

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@chantier/core",
+  "version": "0.3.0",
+  "type": "module",
+  "license": "Apache-2.0",
+  "description": "Agent loop, session store, and model-adapter seam for the chantier coding agent",
+  "exports": {
+    ".": {
+      "development": "./src/index.ts",
+      "types": "./dist/index.d.mts",
+      "import": "./dist/index.mjs"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mlcassociation/chantier.git"
+  },
+  "homepage": "https://github.com/mlcassociation/chantier#readme",
+  "bugs": {
+    "url": "https://github.com/mlcassociation/chantier/issues"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "scripts": {
+    "build": "tsdown src/index.ts --format esm --dts --clean --out-dir dist",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "@chantier/permissions": "^0.3.0"
+  },
+  "devDependencies": {
+    "tsdown": "0.23.0"
+  }
+}