@schlenkr/ragents 0.1.5 → 0.1.6

package/packages/agent/dist/core/messages.d.ts

@@ -0,0 +1,37 @@
+/** Custom message types of the agent runtime and their conversion to LLM messages. */
+import type { AgentMessage } from "../loop/index.ts";
+import type { Message, UserContent } from "@ragents/ai";
+export declare const COMPACTION_SUMMARY_PREFIX = "The conversation history before this point was compacted into the following summary:\n\n<summary>\n";
+export declare const COMPACTION_SUMMARY_SUFFIX = "\n</summary>";
+/** Message that an extension injects into the context of a model call. */
+export interface CustomMessage<T = unknown> {
+    role: "custom";
+    customType: string;
+    content: string | UserContent[];
+    display: boolean;
+    details?: T;
+    timestamp: number;
+}
+export interface CompactionSummaryMessage {
+    role: "compactionSummary";
+    summary: string;
+    tokensBefore: number;
+    timestamp: number;
+}
+declare module "../loop/types.ts" {
+    interface CustomAgentMessages {
+        custom: CustomMessage;
+        compactionSummary: CompactionSummaryMessage;
+    }
+}
+export declare function createCompactionSummaryMessage(summary: string, tokensBefore: number, timestamp: string): CompactionSummaryMessage;
+/**
+ * Transform AgentMessages (including custom types) to LLM-compatible Messages.
+ *
+ * This is used by:
+ * - Agent's transormToLlm option (for prompt calls and queued messages)
+ * - Compaction's generateSummary (for summarization)
+ * - Custom extensions and tools
+ */
+export declare function convertToLlm(messages: AgentMessage[]): Message[];
+//# sourceMappingURL=messages.d.ts.map

package/packages/agent/dist/core/model-runtime.d.ts

@@ -0,0 +1,32 @@
+import { type Api, type AssistantMessage, type AssistantMessageEventStream, type AuthCheck, type AuthResult, type Context, type Model, type SimpleStreamOptions } from "@ragents/ai";
+import { type ProviderConfigInput } from "./provider-composer.ts";
+/** A name under which a model of another provider is offered; only the alias is visible to callers. */
+export interface ModelAlias {
+    readonly alias: string;
+    readonly upstream: string;
+    readonly model: string;
+}
+/** The metadata of the target under the alias as id and name, with the alias provider as provider. */
+export declare function aliasedModel(providerId: string, alias: string, target: Model<Api>): Model<Api>;
+/** The built-in providers plus the ones registered at runtime; a key comes from the registration or the environment. */
+export declare class ModelRuntime {
+    private readonly models;
+    private readonly builtins;
+    private readonly registrations;
+    private aliasRegistration;
+    private constructor();
+    static create(): ModelRuntime;
+    getModels(providerId?: string): readonly Model<Api>[];
+    getModel(providerId: string, modelId: string): Model<Api> | undefined;
+    checkAuth(providerId: string): Promise<AuthCheck | undefined>;
+    getAuth(model: Model<Api>): Promise<AuthResult | undefined>;
+    streamSimple(model: Model<Api>, context: Context, options?: SimpleStreamOptions): AssistantMessageEventStream;
+    completeSimple(model: Model<Api>, context: Context, options?: SimpleStreamOptions): Promise<AssistantMessage>;
+    /** A repeated registration keeps the earlier values it does not set; an invalid one throws and changes nothing. */
+    registerProvider(providerId: string, config: ProviderConfigInput): void;
+    /** Offers models of registered providers under alias names; requests go to the target, answers carry the alias. */
+    registerAliases(providerId: string, aliases: readonly ModelAlias[]): void;
+    private aliasModels;
+    private targetOf;
+}
+//# sourceMappingURL=model-runtime.d.ts.map

package/packages/agent/dist/core/provider-composer.d.ts

@@ -0,0 +1,25 @@
+import { type Api, type InputModality, type Model, type Provider } from "@ragents/ai";
+/** A provider registered at runtime: its models and a literal API key, over the built-in provider of the same id. */
+export interface ProviderConfigInput {
+    name?: string;
+    baseUrl?: string;
+    /** The key itself; it is sent as given, never read from the environment or a command. */
+    apiKey?: string;
+    api?: Api;
+    models?: Array<{
+        id: string;
+        name: string;
+        api?: Api;
+        baseUrl?: string;
+        reasoning: boolean;
+        thinkingLevelMap?: Model<Api>["thinkingLevelMap"];
+        input: InputModality[];
+        cost: Model<Api>["cost"];
+        contextWindow: number;
+        maxTokens: number;
+        compat?: Model<Api>["compat"];
+    }>;
+}
+/** Composes the built-in provider of the same id, if any, with a runtime registration. */
+export declare function composeModelProvider(providerId: string, base: Provider | undefined, config: ProviderConfigInput): Provider;
+//# sourceMappingURL=provider-composer.d.ts.map

package/packages/agent/dist/core/resource-loader.d.ts

@@ -0,0 +1,39 @@
+import type { ExtensionFactorySettlementObserver, InlineExtension, LoadExtensionsResult } from "./extensions/types.ts";
+import type { Skill } from "./skills.ts";
+export interface ResourceLoaderReloadOptions {
+    signal?: AbortSignal;
+}
+export interface ResourceLoader {
+    getExtensions(): LoadExtensionsResult;
+    getSkills(): readonly Skill[];
+    getSystemPrompt(): string | undefined;
+    setSystemPrompt(value: string): void;
+    reload(options?: ResourceLoaderReloadOptions): Promise<void>;
+    waitForSettlement?(): Promise<void> | undefined;
+}
+export interface DefaultResourceLoaderOptions {
+    skills?: readonly Skill[];
+    extensionFactories?: InlineExtension[];
+    systemPrompt?: string;
+    onExtensionFactorySettlement?: ExtensionFactorySettlementObserver;
+}
+/** Extensions come only as inline factories and skills as given by the caller; nothing is discovered or installed. */
+export declare class DefaultResourceLoader implements ResourceLoader {
+    private readonly skills;
+    private readonly extensionFactories;
+    private readonly onExtensionFactorySettlement?;
+    private readonly extensionFactorySettlements;
+    private extensionsResult;
+    private systemPrompt?;
+    constructor(options: DefaultResourceLoaderOptions);
+    getExtensions(): LoadExtensionsResult;
+    waitForSettlement(): Promise<void> | undefined;
+    private readonly trackExtensionFactorySettlement;
+    getSkills(): readonly Skill[];
+    getSystemPrompt(): string | undefined;
+    setSystemPrompt(value: string): void;
+    reload(options?: ResourceLoaderReloadOptions): Promise<void>;
+    private loadExtensionFactories;
+    private detectToolConflicts;
+}
+//# sourceMappingURL=resource-loader.d.ts.map

package/packages/agent/dist/core/sdk.d.ts

@@ -0,0 +1,38 @@
+import { type ThinkingLevel } from "../loop/index.ts";
+import { type Model } from "@ragents/ai";
+import { AgentSession } from "./agent-session.ts";
+import type { LoadExtensionsResult, ToolDefinition } from "./extensions/index.ts";
+import type { ModelRuntime } from "./model-runtime.ts";
+import type { ResourceLoader } from "./resource-loader.ts";
+import type { SessionManager } from "./session-manager.ts";
+import { type AgentSettingsInput } from "./agent-settings.ts";
+export interface CreateAgentSessionOptions {
+    /** Working directory of the session. Default: the working directory of the session manager */
+    cwd?: string;
+    modelRuntime: ModelRuntime;
+    /** The model of the session; a session without one is an error. */
+    model: Model<any>;
+    /** Thinking level. Default: from the session, else settings, else 'medium' (clamped to model capabilities) */
+    thinkingLevel?: ThinkingLevel;
+    /** Optional allowlist of tool names; without it every registered tool is enabled. */
+    tools?: string[];
+    /** Custom tools to register besides the tools of extensions. */
+    customTools?: ToolDefinition[];
+    /** Loaded resources: extensions, skills and the system prompt. */
+    resourceLoader: ResourceLoader;
+    sessionManager: SessionManager;
+    settings?: AgentSettingsInput;
+}
+/** Result from createAgentSession */
+export interface CreateAgentSessionResult {
+    /** The created session */
+    session: AgentSession;
+    /** Extensions of the session, with the errors of their factories */
+    extensionsResult: LoadExtensionsResult;
+}
+export * from "./agent-session-runtime.ts";
+export type { ExtensionAPI, ExtensionContext, ExtensionFactory, InlineExtension, ToolDefinition } from "./extensions/index.ts";
+export type { Skill } from "./skills.ts";
+/** Create an AgentSession for the given model. */
+export declare function createAgentSession(options: CreateAgentSessionOptions): Promise<CreateAgentSessionResult>;
+//# sourceMappingURL=sdk.d.ts.map

package/packages/agent/dist/core/session-manager.d.ts

@@ -0,0 +1,189 @@
+import { type AgentMessage } from "../loop/index.ts";
+import type { Message } from "@ragents/ai";
+import { type CustomMessage } from "./messages.ts";
+export declare const CURRENT_SESSION_VERSION = 3;
+export interface SessionHeader {
+    type: "session";
+    version?: number;
+    id: string;
+    timestamp: string;
+    cwd: string;
+    parentSession?: string;
+}
+export interface NewSessionOptions {
+    id?: string;
+    parentSession?: string;
+}
+export interface SessionEntryBase {
+    type: string;
+    id: string;
+    parentId: string | null;
+    timestamp: string;
+}
+export interface SessionMessageEntry extends SessionEntryBase {
+    type: "message";
+    message: AgentMessage;
+}
+export interface ThinkingLevelChangeEntry extends SessionEntryBase {
+    type: "thinking_level_change";
+    thinkingLevel: string;
+}
+export interface ModelChangeEntry extends SessionEntryBase {
+    type: "model_change";
+    provider: string;
+    modelId: string;
+}
+export interface CompactionEntry<T = unknown> extends SessionEntryBase {
+    type: "compaction";
+    summary: string;
+    firstKeptEntryId: string;
+    tokensBefore: number;
+    /** Extension-specific data (e.g., ArtifactIndex, version markers for structured compaction) */
+    details?: T;
+    /** True if generated by an extension, undefined/false if agent-generated (backward compatible) */
+    fromHook?: boolean;
+}
+/**
+ * Custom entry for extensions to store extension-specific data in the session.
+ * Use customType to identify your extension's entries.
+ *
+ * Purpose: Persist extension state across session reloads. On reload, extensions can
+ * scan entries for their customType and reconstruct internal state.
+ *
+ * Does NOT participate in LLM context (ignored by buildSessionContext).
+ * For injecting content into context, see CustomMessageEntry.
+ */
+export interface CustomEntry<T = unknown> extends SessionEntryBase {
+    type: "custom";
+    customType: string;
+    data?: T;
+}
+/** Session entry - has id/parentId for tree structure (returned by "read" methods in SessionManager) */
+export type SessionEntry = SessionMessageEntry | ThinkingLevelChangeEntry | ModelChangeEntry | CompactionEntry | CustomEntry;
+/** Raw file entry (includes header) */
+export type FileEntry = SessionHeader | SessionEntry;
+export interface SessionContext {
+    messages: AgentMessage[];
+    thinkingLevel: string;
+    model: {
+        provider: string;
+        modelId: string;
+    } | null;
+}
+export type ReadonlySessionManager = Pick<SessionManager, "getBranch">;
+export declare function assertValidSessionId(id: string): void;
+export declare function getLatestCompactionEntry(entries: SessionEntry[]): CompactionEntry | null;
+/**
+ * Project one selected session entry into LLM/runtime messages.
+ * Plain custom entries are display/state entries and do not participate in context.
+ */
+export declare function sessionEntryToContextMessages(entry: SessionEntry): AgentMessage[];
+/**
+ * Build the active, compaction-aware session entry list.
+ *
+ * This follows the current leaf path. If the path contains compaction entries,
+ * the latest compaction is represented by the compaction entry itself, followed
+ * by the kept entries starting at firstKeptEntryId and all entries after the
+ * compaction entry. Older summarized entries are omitted.
+ */
+export declare function buildContextEntries(entries: SessionEntry[], leafId?: string | null, byId?: Map<string, SessionEntry>): SessionEntry[];
+/**
+ * Build the session context from entries using tree traversal.
+ * If leafId is provided, walks from that entry to root.
+ * Handles compaction and branch summaries along the path.
+ */
+export declare function buildSessionContext(entries: SessionEntry[], leafId?: string | null, byId?: Map<string, SessionEntry>): SessionContext;
+/** Exported for testing */
+export declare function loadEntriesFromFile(filePath: string): FileEntry[];
+/**
+ * Manages conversation sessions as append-only trees stored in JSONL files.
+ *
+ * Each session entry has an id and parentId forming a tree structure. The "leaf"
+ * pointer tracks the current position. Appending creates a child of the current leaf.
+ * Branching moves the leaf to an earlier entry, allowing new branches without
+ * modifying history.
+ *
+ * Use buildSessionContext() to get the resolved message list for the LLM, which
+ * handles compaction summaries and follows the path from root to current leaf.
+ */
+export declare class SessionManager {
+    private sessionId;
+    private sessionFile;
+    private sessionDir;
+    private cwd;
+    private persist;
+    private flushed;
+    private fileEntries;
+    private byId;
+    private leafId;
+    private constructor();
+    /** Switch to a different session file (used for resume and branching) */
+    setSessionFile(sessionFile: string): void;
+    newSession(options?: NewSessionOptions): string | undefined;
+    private _buildIndex;
+    private _rewriteFile;
+    isPersisted(): boolean;
+    getCwd(): string;
+    getSessionDir(): string;
+    getSessionId(): string;
+    getSessionFile(): string | undefined;
+    _persist(entry: SessionEntry): void;
+    private _appendEntry;
+    /** Append a message as child of current leaf, then advance leaf. Returns entry id.
+     * Compaction summaries are top-level entries appended via appendCompaction(), not message entries.
+     */
+    appendMessage(message: Message | CustomMessage): string;
+    /** Append a thinking level change as child of current leaf, then advance leaf. Returns entry id. */
+    appendThinkingLevelChange(thinkingLevel: string): string;
+    /** Append a model change as child of current leaf, then advance leaf. Returns entry id. */
+    appendModelChange(provider: string, modelId: string): string;
+    /** Append a compaction summary as child of current leaf, then advance leaf. Returns entry id. */
+    appendCompaction<T = unknown>(summary: string, firstKeptEntryId: string, tokensBefore: number, details?: T, fromHook?: boolean): string;
+    /** Append a custom entry (for extensions) as child of current leaf, then advance leaf. Returns entry id. */
+    appendCustomEntry(customType: string, data?: unknown): string;
+    getLeafId(): string | null;
+    getLeafEntry(): SessionEntry | undefined;
+    getEntry(id: string): SessionEntry | undefined;
+    /**
+     * Walk from entry to root, returning all entries in path order.
+     * Includes all entry types (messages, compaction, model changes, etc.).
+     * Use buildSessionContext() to get the resolved messages for the LLM.
+     */
+    getBranch(fromId?: string): SessionEntry[];
+    /**
+     * Build the active, compaction-aware entry list for context/rendering.
+     * Uses tree traversal from current leaf.
+     */
+    buildContextEntries(): SessionEntry[];
+    /**
+     * Build the session context (what gets sent to the LLM).
+     * Uses tree traversal from current leaf.
+     */
+    buildSessionContext(): SessionContext;
+    /**
+     * Get session header.
+     */
+    getHeader(): SessionHeader | null;
+    /**
+     * Get all session entries (excludes header). Returns a shallow copy.
+     * The session is append-only: use appendXXX() to add entries, branch() to
+     * change the leaf pointer. Entries cannot be modified or deleted.
+     */
+    getEntries(): SessionEntry[];
+    /**
+     * Create a new session.
+     * @param cwd Working directory (stored in session header)
+     * @param sessionDir Session directory
+     */
+    static create(cwd: string, sessionDir: string, options?: NewSessionOptions): SessionManager;
+    /**
+     * Open a specific session file.
+     * @param path Path to session file
+     * @param sessionDir Optional session directory for /new or /branch. If omitted, derives from file's parent.
+     * @param cwdOverride Optional cwd override instead of the session header cwd.
+     */
+    static open(path: string, sessionDir?: string, cwdOverride?: string): SessionManager;
+    /** Create an in-memory session (no file persistence) */
+    static inMemory(cwd?: string, options?: NewSessionOptions): SessionManager;
+}
+//# sourceMappingURL=session-manager.d.ts.map

package/packages/agent/dist/core/skills.d.ts

@@ -0,0 +1,20 @@
+/** A skill the host has read and checked; the agent runtime reads no skill files itself. */
+export interface Skill {
+    name: string;
+    description: string;
+    /** Where the host reads the SKILL.md. */
+    filePath: string;
+    baseDir: string;
+    /** How the model's tools reach the SKILL.md; its folder holds the skill's other files. */
+    location: string;
+    disableModelInvocation: boolean;
+}
+/**
+ * Format skills for inclusion in a system prompt.
+ * Uses XML format per Agent Skills standard.
+ * See: https://agentskills.io/integrate-skills
+ *
+ * Skills with disableModelInvocation=true are excluded from the prompt.
+ */
+export declare function formatSkillsForPrompt(skills: readonly Skill[]): string;
+//# sourceMappingURL=skills.d.ts.map

package/packages/agent/dist/core/source-info.d.ts

@@ -0,0 +1,16 @@
+export type SourceScope = "user" | "project" | "temporary";
+export type SourceOrigin = "package" | "top-level";
+export interface SourceInfo {
+    path: string;
+    source: string;
+    scope: SourceScope;
+    origin: SourceOrigin;
+    baseDir?: string;
+}
+export declare function createSyntheticSourceInfo(path: string, options: {
+    source: string;
+    scope?: SourceScope;
+    origin?: SourceOrigin;
+    baseDir?: string;
+}): SourceInfo;
+//# sourceMappingURL=source-info.d.ts.map

package/packages/agent/dist/core/system-prompt.d.ts

@@ -0,0 +1,21 @@
+/**
+ * System prompt construction and project context loading
+ */
+import { type Skill } from "./skills.ts";
+export interface BuildSystemPromptOptions {
+    /** Custom system prompt (replaces default). */
+    customPrompt?: string;
+    /** Tools to include in prompt. Default: [read, bash, edit, write] */
+    selectedTools?: string[];
+    /** Optional one-line tool snippets keyed by tool name. */
+    toolSnippets?: Record<string, string>;
+    /** Additional guideline bullets appended to the default system prompt guidelines. */
+    promptGuidelines?: string[];
+    /** Working directory; only the default prompt names it, a custom prompt stays as the caller wrote it. */
+    cwd: string;
+    /** Pre-loaded skills. */
+    skills?: readonly Skill[];
+}
+/** Build the system prompt with tools, guidelines, and context */
+export declare function buildSystemPrompt(options: BuildSystemPromptOptions): string;
+//# sourceMappingURL=system-prompt.d.ts.map

package/packages/agent/dist/core/tools/bash.d.ts

@@ -0,0 +1,63 @@
+import { Type } from "typebox";
+import type { ToolDefinition } from "../extensions/types.ts";
+import { type TruncationResult } from "./truncate.ts";
+export declare const BASH_MAX_BYTES: number;
+export declare const BASH_MAX_LINE_CHARS = 1000;
+declare const bashSchema: Type.TObject<{
+    command: Type.TString;
+    timeout: Type.TOptional<Type.TNumber>;
+    cwd: Type.TOptional<Type.TString>;
+}>;
+export interface BashToolDetails {
+    truncation?: TruncationResult;
+    fullOutputPath?: string;
+}
+/**
+ * Pluggable operations for the bash tool.
+ * Override these to delegate command execution to remote systems (for example SSH).
+ */
+export interface BashOperations {
+    /**
+     * Execute a command and stream output.
+     * @param command The command to execute
+     * @param cwd Working directory
+     * @param options Execution options
+     * @returns Promise resolving to exit code (null if killed)
+     */
+    exec: (command: string, cwd: string, options: {
+        onData: (data: Buffer) => void;
+        signal?: AbortSignal;
+        timeout?: number;
+        env?: NodeJS.ProcessEnv;
+    }) => Promise<{
+        exitCode: number | null;
+    }>;
+}
+/**
+ * Create bash operations using the built-in local shell execution backend.
+ *
+ * This is useful for extensions that intercept user_bash and still want the
+ * standard local shell behavior while wrapping or rewriting commands.
+ */
+export declare function createLocalBashOperations(options?: {
+    shellPath?: string;
+}): BashOperations;
+export interface BashSpawnContext {
+    command: string;
+    cwd: string;
+    env: NodeJS.ProcessEnv;
+}
+export type BashSpawnHook = (context: BashSpawnContext) => BashSpawnContext;
+export interface BashToolOptions {
+    /** Custom operations for command execution. Default: local shell */
+    operations?: BashOperations;
+    /** Command prefix prepended to every command (for example shell setup commands) */
+    commandPrefix?: string;
+    /** Optional explicit shell path from settings */
+    shellPath?: string;
+    /** Hook to adjust command, cwd, or env before execution */
+    spawnHook?: BashSpawnHook;
+}
+export declare function createBashToolDefinition(cwd: string, options?: BashToolOptions): ToolDefinition<typeof bashSchema, BashToolDetails | undefined>;
+export {};
+//# sourceMappingURL=bash.d.ts.map

package/packages/agent/dist/core/tools/edit-diff.d.ts

@@ -0,0 +1,98 @@
+/**
+ * Shared diff computation utilities for the edit and similar tools.
+ */
+export declare function detectLineEnding(content: string): "\r\n" | "\n";
+export declare function normalizeToLF(text: string): string;
+export declare function restoreLineEndings(text: string, ending: "\r\n" | "\n"): string;
+/**
+ * Normalize text for fuzzy matching. Applies progressive transformations:
+ * - Strip trailing whitespace from each line
+ * - Normalize smart quotes to ASCII equivalents
+ * - Normalize Unicode dashes/hyphens to ASCII hyphen
+ * - Normalize special Unicode spaces to regular space
+ */
+export declare function normalizeForFuzzyMatch(text: string): string;
+interface MatchedEdit {
+    editIndex: number;
+    matchIndex: number;
+    matchLength: number;
+    newText: string;
+}
+type TextReplacement = Pick<MatchedEdit, "matchIndex" | "matchLength" | "newText">;
+/**
+ * Apply replacements matched against `baseContent` to `originalContent` while
+ * preserving unchanged line blocks from the original.
+ *
+ * This is useful when `baseContent` is a normalized view of the original. Each
+ * replacement is widened to the lines it actually touches, those touched lines
+ * are rewritten from the normalized base, and all other lines are copied back
+ * from `originalContent`. The actual replacement ranges drive preservation so
+ * duplicate normalized lines cannot be aligned to the wrong occurrence.
+ */
+export declare function applyReplacementsPreservingUnchangedLines(originalContent: string, baseContent: string, replacements: TextReplacement[]): string;
+export interface FuzzyMatchResult {
+    /** Whether a match was found */
+    found: boolean;
+    /** The index where the match starts (in the content that should be used for replacement) */
+    index: number;
+    /** Length of the matched text */
+    matchLength: number;
+    /** Whether fuzzy matching was used (false = exact match) */
+    usedFuzzyMatch: boolean;
+    /**
+     * The content to use for replacement operations.
+     * When exact match: original content. When fuzzy match: normalized content.
+     */
+    contentForReplacement: string;
+}
+export interface Edit {
+    oldText: string;
+    newText: string;
+    /** 1-based index of the occurrence to replace when oldText is not unique */
+    occurrence?: number;
+    /** Line number close to the intended occurrence; the closest occurrence wins */
+    nearLine?: number;
+    /** Replace every occurrence instead of requiring a unique match */
+    replaceAll?: boolean;
+}
+export interface AppliedEditsResult {
+    baseContent: string;
+    newContent: string;
+    /** Number of replaced regions, which is larger than edits.length when replaceAll is used */
+    replacementCount: number;
+}
+/**
+ * Find oldText in content, trying exact match first, then fuzzy match.
+ * When fuzzy matching is used, the returned contentForReplacement is the
+ * fuzzy-normalized version of the content (trailing whitespace stripped,
+ * Unicode quotes/dashes normalized to ASCII).
+ */
+export declare function fuzzyFindText(content: string, oldText: string): FuzzyMatchResult;
+/** Strip UTF-8 BOM if present, return both the BOM (if any) and the text without it */
+export declare function stripBom(content: string): {
+    bom: string;
+    text: string;
+};
+/**
+ * Apply one or more exact-text replacements to LF-normalized content.
+ *
+ * All edits are matched against the same original content. An edit replaces its
+ * unique match, the match picked by occurrence or nearLine, or every match when
+ * replaceAll is set. Replacements are applied in reverse order so offsets remain
+ * stable. If any edit needs fuzzy matching, the operation runs in fuzzy-normalized
+ * content space and then overlays those line-level changes onto the original
+ * content so unchanged line blocks keep their original bytes.
+ */
+export declare function applyEditsToNormalizedContent(normalizedContent: string, edits: Edit[], path: string): AppliedEditsResult;
+/** Generate a standard unified patch. */
+export declare function generateUnifiedPatch(path: string, oldContent: string, newContent: string, contextLines?: number): string;
+/**
+ * Generate a display-oriented diff string with line numbers and context.
+ * Returns both the diff string and the first changed line number (in the new file).
+ */
+export declare function generateDiffString(oldContent: string, newContent: string, contextLines?: number): {
+    diff: string;
+    firstChangedLine: number | undefined;
+};
+export {};
+//# sourceMappingURL=edit-diff.d.ts.map

package/packages/agent/dist/core/tools/edit.d.ts

@@ -0,0 +1,41 @@
+import { type Static, Type } from "typebox";
+import type { ToolDefinition } from "../extensions/types.ts";
+declare const editSchema: Type.TObject<{
+    path: Type.TString;
+    edits: Type.TArray<Type.TObject<{
+        oldText: Type.TString;
+        newText: Type.TString;
+        occurrence: Type.TOptional<Type.TNumber>;
+        nearLine: Type.TOptional<Type.TNumber>;
+        replaceAll: Type.TOptional<Type.TBoolean>;
+    }>>;
+}>;
+export type EditToolInput = Static<typeof editSchema>;
+export interface EditToolDetails {
+    /** Display-oriented diff of the changes made */
+    diff: string;
+    /** Standard unified patch of the changes made */
+    patch: string;
+    /** Line number of the first change in the new file (for editor navigation) */
+    firstChangedLine?: number;
+    contentHash: string;
+}
+/**
+ * Pluggable operations for the edit tool.
+ * Override these to delegate file editing to remote systems (for example SSH).
+ */
+export interface EditOperations {
+    /** Read file contents as a Buffer */
+    readFile: (absolutePath: string) => Promise<Buffer>;
+    /** Write content to a file */
+    writeFile: (absolutePath: string, content: string) => Promise<void>;
+    /** Check if file is readable and writable (throw if not) */
+    access: (absolutePath: string) => Promise<void>;
+}
+export interface EditToolOptions {
+    /** Custom operations for file editing. Default: local filesystem */
+    operations?: EditOperations;
+}
+export declare function createEditToolDefinition(cwd: string, options?: EditToolOptions): ToolDefinition<typeof editSchema, EditToolDetails | undefined>;
+export {};
+//# sourceMappingURL=edit.d.ts.map

package/packages/agent/dist/core/tools/file-mutation-queue.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Serialize file mutation operations targeting the same file.
+ * Operations for different files still run in parallel.
+ */
+export declare function withFileMutationQueue<T>(filePath: string, fn: () => Promise<T>): Promise<T>;
+//# sourceMappingURL=file-mutation-queue.d.ts.map

package/packages/agent/dist/core/tools/index.d.ts

@@ -0,0 +1,5 @@
+export { type BashOperations, createBashToolDefinition } from "./bash.ts";
+export { createEditToolDefinition } from "./edit.ts";
+export { createReadToolDefinition } from "./read.ts";
+export { createWriteToolDefinition } from "./write.ts";
+//# sourceMappingURL=index.d.ts.map