fastcompact Tool

Relevant source files

The following files were used as context for generating this wiki page:

• src/tools/fastcompact.ts
• README.md
• src/config.ts
• src/routing.ts
• src/compaction.ts
• test/morph.test.ts

The fastcompact tool is a specialized utility within the oh-my-pi-plugin-morph extension designed to condense large files or artifacts into shorter, query-focused digests using the Morph Compact API. Unlike session-level compaction, which summarizes conversation history, fastcompact operates on specific file or artifact locations provided by the user or agent, returning the compacted text directly to the reasoning loop.
Sources: README.md:9-10, src/tools/fastcompact.ts:40-45

This tool is categorized under the "read" approval tier, meaning it does not mutate the workspace, session history, or artifacts. It is primarily used when an agent needs to reason over a large volume of code or data but wants to avoid hitting token limits or losing focus by reading the entire content in full.
Sources: README.md:65-70, src/tools/fastcompact.ts:47-50

Architecture and Execution Flow

The fastcompact tool follows a strict preflight validation and resolution logic before engaging the remote Morph API. It supports both single locators and arrays of locators, resolving them into raw text while enforcing safety constraints.

Core Logic Flow

The execution flow involves resolving the location (either a repo-relative path or an artifact:// URI), reading the content within strict byte limits, and performing a remote call to the Morph Compact client.

Location Resolution

fastcompact distinguishes between local files and session artifacts:

• Repo-relative paths: Resolved against the current working directory (ctx.cwd) using resolveFilepath.
• Artifacts: Locators starting with artifact:// are resolved through the sessionManager.getArtifactPath interface.
  Sources: src/tools/fastcompact.ts:92-114

Tool Parameters and Configuration

The tool accepts parameters to define the target content and the intensity of the compaction.

Parameter	Type	Description	Constraints
location	string	A single file path or artifact URI.	Cannot be used with locations.
locations	string[]	Multiple file paths or artifact URIs.	Max 10 locations.
query	string	Optional focus for the compaction.	Max 16,384 bytes.
compression_ratio	number	Fraction of content to keep.	Valid range: 0.05 to 1.0.

Sources: src/tools/fastcompact.ts:122-140, src/config.ts:46-54

System Configuration

The tool's behavior is influenced by environment variables defined in the project configuration.

Environment Variable	Default	Description
MORPH_FASTCOMPACT	true	Enables/disables the fastcompact tool registration.
MORPH_API_KEY	undefined	Required for the tool to function; otherwise returns guidance.
MORPH_COMPACT_RATIO	0.3	Default target fraction to keep if not specified in tool call.

Sources: src/config.ts:1-26, README.md:27-35

Security and Constraints

fastcompact implements several layers of validation to prevent resource exhaustion and unauthorized file access:

1. Path Containment: It rejects absolute paths and paths that escape the workspace root (e.g., using ../).
2. Glob Prevention: Conventional glob characters (*, ?, [, ], {, }) are rejected to ensure only concrete files are processed.
3. Size Limits:
   • Individual files are capped at 1,048,576 bytes (1MB).
   • Focus queries are capped at 16,384 bytes.
4. Structural Limits: A single call can process a maximum of 10 locations.

Integration with Routing and Agents

The tool selection policy, handled by the routing.ts module, provides system hints to the agent on when to prefer fastcompact over native tools like read.

• Preference: Agents are instructed to favor fastcompact when they need to reason over a large file without reading it in its entirety.
• Fallback: If the Morph API key is missing, the tool returns a message guiding the user to configure the key or fallback to the native read tool.
• Agent Access: It is recommended that write-capable agents include fastcompact in their allowlist for efficient context gathering.

Sources: src/routing.ts:51-54, README.md:112-115, AGENTS.md:15-18

Implementation Example: Reading Bounded Files

The following logic demonstrates how the tool ensures file reads do not exceed memory or API limits during the resolution phase:

// src/tools/fastcompact.ts:71-85
async function readBoundedFile(absPath: string, label: string): Promise<ResolvedLocation> {
  let info: Stats;
  try {
    info = await stat(absPath);
  } catch {
    return { error: `Location not found: ${label}` };
  }
  if (info.isDirectory()) {
    return { error: `Location is a directory, not a file: ${label}` };
  }
  if (info.size > FASTCOMPACT_MAX_BYTES) {
    return { error: `Location too large: ${label} (limit ${FASTCOMPACT_MAX_BYTES})` };
  }
  const text = await Bun.file(absPath).slice(0, FASTCOMPACT_MAX_BYTES + 1).text();
  // ... check content and return text
}

Sources: src/tools/fastcompact.ts:66-89

Summary

The fastcompact tool serves as a high-efficiency "read-and-summarize" bridge between the local filesystem/artifacts and the Morph LLM. By enforcing strict security bounds and providing a query-focused interface, it enables agents to handle large codebases while maintaining operational safety and token efficiency.
Sources: src/tools/fastcompact.ts:31-50, CHANGELOG.md:46-50