neoctl 0.1.2 → 0.1.4

package/README.md

@@ -1,151 +1,151 @@
-# Agent Scaffold Source
-
-This directory is a TypeScript implementation scaffold for the parent README. Chapters 01, 02, 03, 04, 05-core, and 07 now have runnable paths; later chapters still expose stable module boundaries and placeholders.
-
-## Shape
-
-- `src/repl`: the UI layer. It owns terminal input, slash commands, system init events, and rendering streamed events.
-- `src/core`: the multi-turn query loop, loop state, message pipeline, `QueryEngine`, and child-agent runner entry points.
-- `src/model`: provider-neutral model gateway/config/factory, provider adapters, OpenAI Responses/Chat mappers, HTTP transport, SSE decoder, retry, and normalized errors.
-- `src/tools`: lifecycle tool contracts, registry, schema validation, execution pipeline, batch orchestration, streaming executor, and built-in tools.
-- `src/context`: system prompt sections, runtime user/system context, deterministic compaction helpers, and model-driven compaction.
-- `src/session`: JSONL session transcripts, tool-result persistence, latest/specific session resume, and session listing.
-- `src/agents`: agent definitions, `AgentTool`, prompt rules, fork constraints, local task lifecycle, and agent smoke coverage.
-- `src/tasks`: background task store, task-control tools, named-agent message routing, and persisted task output files.
-- `src/skills`: inline workflow-as-tool injection and fork-skill boundary.
-- `src/safety`: optional permission, sandbox, and audit ports.
-- `src/app`: app-state ports used by tools and runtime code.
-- `vendor/ripgrep`: per-platform bundled `rg` binaries installed by `npm run vendor:rg` or optional `postinstall`.
-
-## Commands
-
-```bash
-npm install
-npm run vendor:rg
-npm run typecheck
-npm run build
-npm run smoke:core
-npm run smoke:tools
-npm run smoke:context
-npm run smoke:agents
-npm run smoke:skills
-npm run smoke:openai -- "Say pong"
-npm run dev
-```
-
-## Core Loop
-
-`src/core/query.ts` implements the Chapter 01 main path as a streaming state machine:
-
-- prepares each turn from a single `QueryState`
-- applies compact-boundary filtering and tool-result budgeting before model calls
-- builds system/user context into the model request
-- streams assistant deltas and messages to the UI
-- collects `tool_use` events, executes tools, and feeds `tool_result` messages into the next model turn
-- tracks `previousResponseId` for Responses API tool-result continuation
-- emits terminal reasons such as `completed`, `max_turns`, `model_error`, and abort states
-- keeps max-output-token recovery and reactive compact continuation points explicit
-
-`npm run smoke:core` verifies the tool-call follow-up loop with a fake model and the built-in `echo` tool.
-
-## Tool System
-
-`src/tools` implements the Chapter 02 tool system contract:
-
-- tools are lifecycle objects with identity, aliases, schemas, metadata, validators, execution, result mapping, progress rendering, and optional context modifiers
-- `ToolRegistry` keeps built-in tools as a stable prompt-cache prefix, supports aliases, filters deferred tools, and merges external tools deterministically
-- `runToolUse()` performs schema validation, custom validation, permission decision, progress emission, abort handling, result mapping, max-result truncation, new messages, and context modifier propagation
-- `runTools()` partitions tool calls into concurrency-safe batches and serial batches, applying context modifiers in tool-use order
-- `StreamingToolExecutor` can start tools as tool calls arrive and can synthesize discarded results on fallback/abort
-- `grepTool` calls the bundled ripgrep binary through `ripgrep-binary.ts`, supports smart/sensitive/insensitive case modes, glob filters, hidden-file opt-in, bounded context lines, and bounded total results
-- `searchTool` performs web search through a pluggable `SearchProvider`; the initial backend is Exa MCP, with provider factory seams for future Bing/Tavily/custom implementations
-- `scripts/install-ripgrep.cjs` resolves the current OS/CPU, downloads the matching official ripgrep release asset, extracts `rg`, and writes a manifest beside the binary; runtime lookup does not depend on PATH
-
-`npm run smoke:tools` verifies aliases, schema/custom validation, unknown-tool errors, max result truncation, bundled-rg grep, pluggable web search, and concurrent batch execution.
-
-## Context And Prompts
-
-`src/context` implements the Chapter 03 and Chapter 05 prompt/context path:
-
-- `prompts.ts` builds system prompt sections with `__SYSTEM_PROMPT_DYNAMIC_BOUNDARY__`, replacement priority, proactive agent append mode, and prefix splitting for cache-aware providers
-- `DefaultContextManager` memoizes user context (`currentDate`, project memory files) and system context (`cwd`, platform, git branch/status/recent commit)
-- `message-pipeline.ts` prepends user context as a user message, appends system context to the system prompt, respects compact boundaries, and budgets oversized tool results
-- `ModelDrivenCompactor` uses the configured model gateway for autocompact and reactive compact summaries
-- deterministic snip, microcompact, and summary fallback remain available when model summarization fails or when tests need predictable output
-- `query.ts` persists compact-boundary messages into the event stream and retries once after provider `context_length` errors
-
-`npm run smoke:context` verifies prompt boundary splitting, context injection, tool result budgeting, deterministic compaction, model-driven autocompact, and prompt-too-long recovery.
-
-## Session Resume
-
-The REPL writes JSONL transcripts under `.agent/sessions` by default. After each user message, a background title subagent check is scheduled after 5s: it creates one initial title, then performs one later refinement with the conversation and previous title if the prior title agent has finished. `/sessions` opens an interactive browser (default 10 per page): use ↑/↓ to select a session, ←/→ to switch pages when more than one page exists, Enter to resume the selected session, and Esc to close.
-
-Startup resume is available with environment variables:
-
-```bash
-set AGENT_SESSION_RESUME=1
-npm run dev
-
-set AGENT_SESSION_ID=<session_id>
-set AGENT_SESSION_RESUME=1
-npm run dev
-```
-
-Set `AGENT_SESSION_TRANSCRIPT=0` to disable transcript persistence, or `AGENT_SESSION_DIR=<absolute-or-relative-dir>` to store transcripts elsewhere. `/reset` clears the active history and records a reset marker so future resumes start after the reset.
-
-`npm run smoke:session` verifies transcript recording, latest-session lookup, specific-session resume, tool-result output persistence, and reset markers.
-
-## Subagents And Tasks
-
-`src/agents` and `src/tasks` implement the Chapter 04 core path:
-
-- `AgentTool` is a normal tool with `prompt`, `description`, `subagent_type`, `model`, `run_in_background`, `name`, `team_name`, `mode`, `isolation`, and `cwd` inputs
-- `AgentTool` now exports prompt rules covering fresh/fork/background/parallel/prompt-quality behavior
-- `runAgent()` creates isolated child messages/context/tool pools and reuses the same `query()` loop
-- `AgentDefinition` supports tool allow/deny lists, model, effort, permission mode, background, max turns, memory, isolation, and custom system prompts
-- sync agents return a completed structured result; background/fork agents register `LocalAgentTask` and return `async_launched`
-- `TaskOutput`, `TaskList`, `TaskGet`, `TaskStop`, and `SendMessage` provide the minimum control surface for background agents
-- completed background tasks write `.agent-tasks/<task_id>.txt`; the directory is gitignored
-- fork children get explicit anti-recursion and scope boilerplate; teammate/team inputs are represented as named background agents for now
-
-`npm run smoke:agents` verifies sync delegation, async launch, task output, output-file persistence, task listing, and named-agent message routing.
-
-## Skills
-
-`src/skills` implements the low-risk part of Chapter 05 SkillTool:
-
-- `SkillTool` validates skill existence and model invocation eligibility
-- inline skills inject a meta user message into the next model turn through `newMessages`
-- inline skills can update main loop model and effort through `contextModifier`
-- fork skills are recognized and return a structured `fork_required` result instead of silently pretending to run
-
-`npm run smoke:skills` verifies inline injection, context modification, fork-skill rejection, and unknown-skill validation.
-
-## Model Providers
-
-The REPL loads environment files, reads `MODEL_*` settings into a small discriminated provider config, and constructs a provider through `provider-factory.ts`. It loads the current directory `.env` first, then overrides it with the user-level config at `%APPDATA%\\neo\\.env` on Windows or `~/.config/neo/.env` on other platforms. If the user-level config file is missing, `neo` creates a commented template there and prints a startup notice telling the user to fill `MODEL_API_KEY`. Set `NEO_ENV_FILE` to point at a custom env file; that file has the highest priority. Provider-specific switches stay inside provider-owned config (`OpenAIProviderConfig.openai.endpoint` today), while `OPENAI_*` variables remain supported as compatibility aliases.
-
-```bash
-mkdir "%APPDATA%\\neo"
-notepad "%APPDATA%\\neo\\.env"
-
-# In the env file:
-MODEL_PROVIDER=openai
-MODEL_API_KEY=your-api-key
-MODEL_BASE_URL=https://api.openai.com
-MODEL_ID=gpt-5.5
-MODEL_REASONING_EFFORT=high
-MODEL_ENDPOINT=auto
-
-npm run smoke:openai -- "Say pong"
-npm run dev
-```
-
-The OpenAI adapter is split into a small provider facade plus mappers:
-
-- `openai-adapter.ts`: endpoint selection, auth, transport, retry, and Responses-to-Chat fallback
-- `openai-responses-mapper.ts`: `/v1/responses` request and event mapping
-- `openai-chat-mapper.ts`: OpenAI-compatible `/v1/chat/completions` fallback mapping
-- `openai-mappers.ts`: shared tool/message/usage helpers
-
-`MODEL_ENDPOINT=auto` tries `/v1/responses` first and falls back to `/v1/chat/completions` for OpenAI-compatible gateways that do not expose Responses API.
+# Agent Scaffold Source
+
+This directory is a TypeScript implementation scaffold for the parent README. Chapters 01, 02, 03, 04, 05-core, and 07 now have runnable paths; later chapters still expose stable module boundaries and placeholders.
+
+## Shape
+
+- `src/repl`: the UI layer. It owns terminal input, slash commands, system init events, and rendering streamed events.
+- `src/core`: the multi-turn query loop, loop state, message pipeline, `QueryEngine`, and child-agent runner entry points.
+- `src/model`: provider-neutral model gateway/config/factory, provider adapters, OpenAI Responses/Chat mappers, HTTP transport, SSE decoder, retry, and normalized errors.
+- `src/tools`: lifecycle tool contracts, registry, schema validation, execution pipeline, batch orchestration, streaming executor, and built-in tools.
+- `src/context`: system prompt sections, runtime user/system context, deterministic compaction helpers, and model-driven compaction.
+- `src/session`: JSONL session transcripts, tool-result persistence, latest/specific session resume, and session listing.
+- `src/agents`: agent definitions, `AgentTool`, prompt rules, fork constraints, local task lifecycle, and agent smoke coverage.
+- `src/tasks`: background task store, task-control tools, named-agent message routing, and persisted task output files.
+- `src/skills`: inline workflow-as-tool injection and fork-skill boundary.
+- `src/safety`: optional permission, sandbox, and audit ports.
+- `src/app`: app-state ports used by tools and runtime code.
+- `vendor/ripgrep`: per-platform bundled `rg` binaries installed by `npm run vendor:rg` or optional `postinstall`.
+
+## Commands
+
+```bash
+npm install
+npm run vendor:rg
+npm run typecheck
+npm run build
+npm run smoke:core
+npm run smoke:tools
+npm run smoke:context
+npm run smoke:agents
+npm run smoke:skills
+npm run smoke:openai -- "Say pong"
+npm run dev
+```
+
+## Core Loop
+
+`src/core/query.ts` implements the Chapter 01 main path as a streaming state machine:
+
+- prepares each turn from a single `QueryState`
+- applies compact-boundary filtering and tool-result budgeting before model calls
+- builds system/user context into the model request
+- streams assistant deltas and messages to the UI
+- collects `tool_use` events, executes tools, and feeds `tool_result` messages into the next model turn
+- tracks `previousResponseId` for Responses API tool-result continuation
+- emits terminal reasons such as `completed`, `max_turns`, `model_error`, and abort states
+- keeps max-output-token recovery and reactive compact continuation points explicit
+
+`npm run smoke:core` verifies the tool-call follow-up loop with a fake model and the built-in `echo` tool.
+
+## Tool System
+
+`src/tools` implements the Chapter 02 tool system contract:
+
+- tools are lifecycle objects with identity, aliases, schemas, metadata, validators, execution, result mapping, progress rendering, and optional context modifiers
+- `ToolRegistry` keeps built-in tools as a stable prompt-cache prefix, supports aliases, filters deferred tools, and merges external tools deterministically
+- `runToolUse()` performs schema validation, custom validation, permission decision, progress emission, abort handling, result mapping, max-result truncation, new messages, and context modifier propagation
+- `runTools()` partitions tool calls into concurrency-safe batches and serial batches, applying context modifiers in tool-use order
+- `StreamingToolExecutor` can start tools as tool calls arrive and can synthesize discarded results on fallback/abort
+- `grepTool` calls the bundled ripgrep binary through `ripgrep-binary.ts`, supports smart/sensitive/insensitive case modes, glob filters, hidden-file opt-in, bounded context lines, and bounded total results
+- `searchTool` performs web search through a pluggable `SearchProvider`; the initial backend is Exa MCP, with provider factory seams for future Bing/Tavily/custom implementations
+- `scripts/install-ripgrep.cjs` resolves the current OS/CPU, downloads the matching official ripgrep release asset, extracts `rg`, and writes a manifest beside the binary; runtime lookup does not depend on PATH
+
+`npm run smoke:tools` verifies aliases, schema/custom validation, unknown-tool errors, max result truncation, bundled-rg grep, pluggable web search, and concurrent batch execution.
+
+## Context And Prompts
+
+`src/context` implements the Chapter 03 and Chapter 05 prompt/context path:
+
+- `prompts.ts` builds system prompt sections with `__SYSTEM_PROMPT_DYNAMIC_BOUNDARY__`, replacement priority, proactive agent append mode, and prefix splitting for cache-aware providers
+- `DefaultContextManager` memoizes user context (`currentDate`, project memory files) and system context (`cwd`, platform, git branch/status/recent commit)
+- `message-pipeline.ts` prepends user context as a user message, appends system context to the system prompt, respects compact boundaries, and budgets oversized tool results
+- `ModelDrivenCompactor` uses the configured model gateway for autocompact and reactive compact summaries
+- deterministic snip, microcompact, and summary fallback remain available when model summarization fails or when tests need predictable output
+- `query.ts` persists compact-boundary messages into the event stream and retries once after provider `context_length` errors
+
+`npm run smoke:context` verifies prompt boundary splitting, context injection, tool result budgeting, deterministic compaction, model-driven autocompact, and prompt-too-long recovery.
+
+## Session Resume
+
+The REPL writes JSONL transcripts under `.agent/sessions` by default. After each user message, a background title subagent check is scheduled after 5s: it creates one initial title, then performs one later refinement with the conversation and previous title if the prior title agent has finished. `/sessions` opens an interactive browser (default 10 per page): use ↑/↓ to select a session, ←/→ to switch pages when more than one page exists, Enter to resume the selected session, and Esc to close.
+
+Startup resume is available with environment variables:
+
+```bash
+set AGENT_SESSION_RESUME=1
+npm run dev
+
+set AGENT_SESSION_ID=<session_id>
+set AGENT_SESSION_RESUME=1
+npm run dev
+```
+
+Set `AGENT_SESSION_TRANSCRIPT=0` to disable transcript persistence, or `AGENT_SESSION_DIR=<absolute-or-relative-dir>` to store transcripts elsewhere. `/reset` clears the active history and records a reset marker so future resumes start after the reset.
+
+`npm run smoke:session` verifies transcript recording, latest-session lookup, specific-session resume, tool-result output persistence, and reset markers.
+
+## Subagents And Tasks
+
+`src/agents` and `src/tasks` implement the Chapter 04 core path:
+
+- `AgentTool` is a normal tool with `prompt`, `description`, `subagent_type`, `model`, `run_in_background`, `name`, `team_name`, `mode`, `isolation`, and `cwd` inputs
+- `AgentTool` now exports prompt rules covering fresh/fork/background/parallel/prompt-quality behavior
+- `runAgent()` creates isolated child messages/context/tool pools and reuses the same `query()` loop
+- `AgentDefinition` supports tool allow/deny lists, model, effort, permission mode, background, max turns, memory, isolation, and custom system prompts
+- sync agents return a completed structured result; background/fork agents register `LocalAgentTask` and return `async_launched`
+- `TaskOutput`, `TaskList`, `TaskGet`, `TaskStop`, and `SendMessage` provide the minimum control surface for background agents
+- completed background tasks write `.agent-tasks/<task_id>.txt`; the directory is gitignored
+- fork children get explicit anti-recursion and scope boilerplate; teammate/team inputs are represented as named background agents for now
+
+`npm run smoke:agents` verifies sync delegation, async launch, task output, output-file persistence, task listing, and named-agent message routing.
+
+## Skills
+
+`src/skills` implements the low-risk part of Chapter 05 SkillTool:
+
+- `SkillTool` validates skill existence and model invocation eligibility
+- inline skills inject a meta user message into the next model turn through `newMessages`
+- inline skills can update main loop model and effort through `contextModifier`
+- fork skills are recognized and return a structured `fork_required` result instead of silently pretending to run
+
+`npm run smoke:skills` verifies inline injection, context modification, fork-skill rejection, and unknown-skill validation.
+
+## Model Providers
+
+The REPL loads environment files, reads `MODEL_*` settings into a small discriminated provider config, and constructs a provider through `provider-factory.ts`. It loads the current directory `.env` first, then overrides it with the user-level config at `%APPDATA%\\neo\\.env` on Windows or `~/.config/neo/.env` on other platforms. If the user-level config file is missing, `neo` creates a commented template there and prints a startup notice telling the user to fill `MODEL_API_KEY`. Set `NEO_ENV_FILE` to point at a custom env file; that file has the highest priority. Provider-specific switches stay inside provider-owned config (`OpenAIProviderConfig.openai.endpoint` today), while `OPENAI_*` variables remain supported as compatibility aliases.
+
+```bash
+mkdir "%APPDATA%\\neo"
+notepad "%APPDATA%\\neo\\.env"
+
+# In the env file:
+MODEL_PROVIDER=openai
+MODEL_API_KEY=your-api-key
+MODEL_BASE_URL=https://api.openai.com
+MODEL_ID=gpt-5.5
+MODEL_REASONING_EFFORT=high
+MODEL_ENDPOINT=auto
+
+npm run smoke:openai -- "Say pong"
+npm run dev
+```
+
+The OpenAI adapter is split into a small provider facade plus mappers:
+
+- `openai-adapter.ts`: endpoint selection, auth, transport, retry, and Responses-to-Chat fallback
+- `openai-responses-mapper.ts`: `/v1/responses` request and event mapping
+- `openai-chat-mapper.ts`: OpenAI-compatible `/v1/chat/completions` fallback mapping
+- `openai-mappers.ts`: shared tool/message/usage helpers
+
+`MODEL_ENDPOINT=auto` tries `/v1/responses` first and falls back to `/v1/chat/completions` for OpenAI-compatible gateways that do not expose Responses API.

package/dist/context/compaction.d.ts

@@ -15,20 +15,25 @@ export interface ContextBudgetOptions {
     compactModel?: string;
     compactMaxOutputTokens?: number;
 }
+export type CompactionReason = "none" | "snip" | "microcompact" | "autocompact" | "reactive_compact" | "manualcompact" | "purecompact";
 export interface CompactionResult {
     messages: Message[];
     summary?: string;
     changed: boolean;
-    reason?: "none" | "snip" | "microcompact" | "autocompact" | "reactive_compact";
+    reason?: CompactionReason;
     tokensFreed?: number;
 }
 export interface Compactor {
     compact(messages: readonly Message[], options?: ContextBudgetOptions): Promise<CompactionResult>;
+    manualCompact?(messages: readonly Message[], options?: ContextBudgetOptions): Promise<CompactionResult>;
+    pureCompact?(messages: readonly Message[], options?: ContextBudgetOptions): Promise<CompactionResult>;
     reactiveCompact?(messages: readonly Message[], error: Error, options?: ContextBudgetOptions): Promise<CompactionResult>;
 }
 export declare const CLEARED_TOOL_RESULT_CONTENT = "[Old tool result content cleared]";
 export declare class DeterministicCompactor implements Compactor {
     compact(messages: readonly Message[], options?: ContextBudgetOptions): Promise<CompactionResult>;
+    manualCompact(messages: readonly Message[], options?: ContextBudgetOptions): Promise<CompactionResult>;
+    pureCompact(messages: readonly Message[], options?: ContextBudgetOptions): Promise<CompactionResult>;
     reactiveCompact(messages: readonly Message[], error: Error, options?: ContextBudgetOptions): Promise<CompactionResult>;
 }
 export declare class ModelDrivenCompactor implements Compactor {
@@ -36,12 +41,16 @@ export declare class ModelDrivenCompactor implements Compactor {
     private readonly fallback;
     constructor(modelGateway: ModelGateway);
     compact(messages: readonly Message[], options?: ContextBudgetOptions): Promise<CompactionResult>;
+    manualCompact(messages: readonly Message[], options?: ContextBudgetOptions): Promise<CompactionResult>;
+    pureCompact(messages: readonly Message[], options?: ContextBudgetOptions): Promise<CompactionResult>;
     reactiveCompact(messages: readonly Message[], error: Error, options?: ContextBudgetOptions): Promise<CompactionResult>;
     private modelAutoCompactIfNeeded;
     private summarizeWithModel;
 }
 export declare class NoopCompactor implements Compactor {
     compact(messages: readonly Message[]): Promise<CompactionResult>;
+    manualCompact(messages: readonly Message[]): Promise<CompactionResult>;
+    pureCompact(messages: readonly Message[]): Promise<CompactionResult>;
 }
 export declare function estimateMessagesChars(messages: readonly Message[]): number;
 export declare function snipCompactIfNeeded(messages: readonly Message[], options?: ContextBudgetOptions): CompactionResult;

package/dist/context/compaction.js

@@ -13,6 +13,12 @@ export class DeterministicCompactor {
             return micro;
         return { messages: [...messages], changed: false, reason: "none" };
     }
+    async manualCompact(messages, options = {}) {
+        return manualCompactWithSummary(messages, options);
+    }
+    async pureCompact(messages, options = {}) {
+        return pureCompactWithSanitizedSummary(messages, options);
+    }
     async reactiveCompact(messages, error, options = {}) {
         const micro = microCompactIfNeeded(messages, options);
         const reactive = reactiveCompactWithSummary(micro.messages, `Reactive compact after model context error: ${error.message}`, options);
@@ -37,6 +43,23 @@ export class ModelDrivenCompactor {
             return micro;
         return { messages: [...messages], changed: false, reason: "none" };
     }
+    async manualCompact(messages, options = {}) {
+        const keepRecentMessages = options.keepRecentMessages ?? 8;
+        const recent = messages.slice(-keepRecentMessages);
+        const older = messages.slice(0, Math.max(0, messages.length - keepRecentMessages));
+        if (older.length === 0)
+            return { messages: [...messages], changed: false, reason: "none" };
+        try {
+            const summary = await this.summarizeWithModel(older, MANUAL_COMPACT_INSTRUCTIONS, options);
+            return buildCompactionResult(messages, recent, summary, "manualcompact", true);
+        }
+        catch {
+            return this.fallback.manualCompact?.(messages, options) ?? manualCompactWithSummary(messages, options);
+        }
+    }
+    async pureCompact(messages, options = {}) {
+        return pureCompactWithSanitizedSummary(messages, options);
+    }
     async reactiveCompact(messages, error, options = {}) {
         const micro = microCompactIfNeeded(messages, options);
         const keepRecentMessages = options.keepRecentMessages ?? 8;
@@ -104,6 +127,12 @@ export class NoopCompactor {
     async compact(messages) {
         return { messages: [...messages], changed: false, reason: "none" };
     }
+    async manualCompact(messages) {
+        return { messages: [...messages], changed: false, reason: "none" };
+    }
+    async pureCompact(messages) {
+        return { messages: [...messages], changed: false, reason: "none" };
+    }
 }
 export function estimateMessagesChars(messages) {
     return messages.reduce((total, message) => total + serializeMessage(message).length, 0);
@@ -192,6 +221,15 @@ function shouldCompactForBudget(messages, options, fallbackMaxChars, triggerRati
     }
     return estimateMessagesChars(messages) > fallbackMaxChars;
 }
+function manualCompactWithSummary(messages, options) {
+    const keepRecentMessages = options.keepRecentMessages ?? 8;
+    const recent = messages.slice(-keepRecentMessages);
+    const older = messages.slice(0, Math.max(0, messages.length - keepRecentMessages));
+    if (older.length === 0)
+        return { messages: [...messages], changed: false, reason: "none" };
+    const summary = buildHistorySummary(older, options.summaryMaxChars ?? 6000);
+    return buildCompactionResult(messages, recent, summary || "No older messages were available to summarize.", "manualcompact", false);
+}
 function reactiveCompactWithSummary(messages, heading, options) {
     const keepRecentMessages = options.keepRecentMessages ?? 8;
     const recent = messages.slice(-keepRecentMessages);
@@ -199,8 +237,25 @@ function reactiveCompactWithSummary(messages, heading, options) {
     const summary = buildHistorySummary(older, options.summaryMaxChars ?? 6000);
     return buildCompactionResult(messages, recent, `${heading}\n\n${summary || "No older messages were available to summarize."}`, "reactive_compact", false);
 }
+function pureCompactWithSanitizedSummary(messages, options) {
+    if (messages.length === 0)
+        return { messages: [], changed: false, reason: "none" };
+    const summary = buildPureSummary(messages, options.summaryMaxChars ?? 4000);
+    const boundary = createCompactionBoundaryMessage(`Pure compacted conversation after a transport/WAF risk block.\n\n${summary}`, "purecompact", false);
+    return {
+        messages: [boundary],
+        summary,
+        changed: true,
+        reason: "purecompact",
+        tokensFreed: Math.max(0, estimateMessagesChars(messages) - estimateMessagesChars([boundary])),
+    };
+}
 function buildCompactionResult(originalMessages, recentMessages, summary, reason, modelDriven) {
-    const label = reason === "autocompact" ? "Auto compacted earlier conversation." : "Reactive compacted earlier conversation.";
+    const label = reason === "autocompact"
+        ? "Auto compacted earlier conversation."
+        : reason === "manualcompact"
+            ? "Manually compacted earlier conversation."
+            : "Reactive compacted earlier conversation.";
     const boundary = createCompactionBoundaryMessage(`${label}\n\n${summary}`, reason, modelDriven);
     const compacted = [boundary, ...recentMessages];
     return {
@@ -255,6 +310,104 @@ function buildHistorySummary(messages, maxChars) {
     const joined = lines.join("\n");
     return joined.length > maxChars ? `${joined.slice(0, maxChars)}\n- ...summary truncated...` : joined;
 }
+function buildPureSummary(messages, maxChars) {
+    const userLines = [];
+    const assistantLines = [];
+    const toolLines = [];
+    const stateLines = [];
+    for (const message of messages) {
+        const text = sanitizeForPureState(serializeMessageForPure(message));
+        if (!text)
+            continue;
+        const line = `- ${text}`;
+        if (message.metadata?.compactBoundary === true)
+            stateLines.push(line);
+        else if (message.role === "user")
+            userLines.push(line);
+        else if (message.role === "assistant")
+            assistantLines.push(line);
+        else if (message.role === "tool_result")
+            toolLines.push(line);
+        else if (message.role !== "system" && message.role !== "progress" && message.role !== "tombstone")
+            stateLines.push(`- ${message.role}: ${text}`);
+    }
+    const sections = [
+        "Purpose: sanitized continuation state produced by /pure after a risk/WAF block; raw commands, logs, code snippets, and bulky tool output were intentionally omitted.",
+        formatPureSection("Recent user goals/constraints", lastItems(userLines, 10)),
+        formatPureSection("Recent assistant progress/decisions", lastItems(assistantLines, 8)),
+        formatPureSection("Tool activity summary", lastItems(toolLines, 8)),
+        formatPureSection("Prior compact/state facts", lastItems(stateLines, 8)),
+        "Pending work: continue from the latest user request using the sanitized facts above; ask for clarification only if a required detail was removed by sanitization.",
+    ].filter(Boolean).join("\n");
+    return sections.length > maxChars ? `${sections.slice(0, maxChars)}\n- ...pure summary truncated...` : sections;
+}
+function formatPureSection(title, lines) {
+    return lines.length > 0 ? `${title}:\n${dedupeLines(lines).join("\n")}` : `${title}: none retained.`;
+}
+function lastItems(items, limit) {
+    return items.slice(Math.max(0, items.length - limit));
+}
+function dedupeLines(lines) {
+    const seen = new Set();
+    const deduped = [];
+    for (const line of lines) {
+        if (seen.has(line))
+            continue;
+        seen.add(line);
+        deduped.push(line);
+    }
+    return deduped;
+}
+function serializeMessageForPure(message) {
+    return message.blocks
+        .map((block) => {
+        if (block.type === "text")
+            return block.text;
+        if (block.type === "image")
+            return block.label ?? `[image ${block.mimeType}]`;
+        if (block.type === "thinking")
+            return "[assistant thinking omitted]";
+        if (block.type === "tool_use")
+            return `tool_use ${block.name}: ${sanitizeToolPayload(block.input)}`;
+        if (block.type === "tool_result")
+            return `tool_result ${block.name}: ${block.ok ? "ok" : "error"}`;
+        return "";
+    })
+        .filter(Boolean)
+        .join("\n");
+}
+function sanitizeToolPayload(input) {
+    const serialized = typeof input === "string" ? input : JSON.stringify(input);
+    if (!serialized)
+        return "no input";
+    return sanitizeForPureState(serialized).slice(0, 180) || "details omitted";
+}
+function sanitizeForPureState(text) {
+    const normalized = text.replace(/```[\s\S]*?```/g, "[code block omitted]");
+    const lines = normalized
+        .split(/\r?\n/)
+        .map((line) => sanitizePureLine(line))
+        .filter(Boolean);
+    return dedupeLines(lines).join("; ").replace(/\s+/g, " ").trim().slice(0, 700);
+}
+function sanitizePureLine(line) {
+    let safe = line.trim();
+    if (!safe)
+        return "";
+    if (/\b(python\s+-c|node\s+-e|bash\s+-c|sh\s+-c|powershell|cmd\.exe|set-location|copy-item|invoke-webrequest|curl|read_text|write_text)\b/i.test(safe)) {
+        return "[omitted raw command/log detail]";
+    }
+    safe = safe.replace(/[A-Za-z]:[\\/][^\s"'`<>]+/g, (match) => summarizePathForPureState(match));
+    safe = safe.replace(/[\\]+/g, "/");
+    safe = safe.replace(/[{}<>`]/g, " ");
+    safe = safe.replace(/\s+/g, " ").trim();
+    return safe.length > 240 ? `${safe.slice(0, 240)}...` : safe;
+}
+function summarizePathForPureState(value) {
+    const parts = value.split(/[\\/]+/).filter(Boolean);
+    const tail = parts.slice(Math.max(0, parts.length - 3)).join("/");
+    return tail ? `[path:${tail}]` : "[path]";
+}
 function serializeTranscriptForSummary(messages, maxChars) {
     const lines = messages.map((message) => {
         const metadata = [
@@ -324,6 +477,13 @@ function extractText(message) {
 function buildReactiveCompactInstruction(error) {
     return `${AUTO_COMPACT_INSTRUCTIONS}\n\nThe previous model request failed because the prompt was too long. Preserve enough task state to continue after this error. Error: ${error.message}`;
 }
+const MANUAL_COMPACT_INSTRUCTIONS = [
+    "Summarize the earlier agent conversation for continuation after a user-requested context compaction.",
+    "Preserve: user goals and constraints, decisions made, files or commands mentioned, completed work, pending work, task ids, important tool results, and any errors or blockers.",
+    "Drop: repetitive logs, transient progress chatter, and irrelevant wording.",
+    "Return concise plain text labels, not Markdown headings. Use labels like Goal:, Constraints:, Work completed:, Important facts:, Pending work:, Open risks:.",
+    "Do not include final-answer prose; this summary is an internal continuation state only.",
+].join("\n");
 const AUTO_COMPACT_INSTRUCTIONS = [
     "Summarize the earlier agent conversation for continuation after context compaction.",
     "Preserve: user goals and constraints, decisions made, files or commands mentioned, completed work, pending work, task ids, important tool results, and any errors or blockers.",