comisai 1.0.4

package/node_modules/@comis/agent/dist/bootstrap/system-prompt-assembler.d.ts

@@ -0,0 +1,108 @@
+/**
+ * System prompt assembler with 3 verbosity modes.
+ *
+ * Composes 20 static section builders into a single system prompt string.
+ * Dynamic sections (date/time, inbound metadata) relocated to user-message
+ * preamble in prompt-assembly.ts for cache stability.
+ * Supports "full" (all sections), "minimal" (7 sections), and "none"
+ * (identity line only, no file I/O).
+ */
+import type { BootstrapContextFile, InboundMetadata, PromptMode, RuntimeInfo } from "./types.js";
+import type { SubagentRoleParams } from "./sections/index.js";
+export type { SubagentRoleParams } from "./sections/index.js";
+export type { InboundMetadata } from "./types.js";
+/** Section separator used between all sections and between the two blocks. */
+export declare const SECTION_SEPARATOR = "\n\n---\n\n";
+/** Multi-block system prompt for independent cache_control placement. */
+export interface SystemPromptBlocks {
+    /** Static prefix: identity + persona. Never changes per session. */
+    staticPrefix: string;
+    /** Attribution: safety + language. Changes per-user (language preference). */
+    attribution: string;
+    /** Semi-stable body: tooling, workspace, messaging, etc. Changes on MCP reconnect. */
+    semiStableBody: string;
+}
+export interface AssemblerParams {
+    agentName?: string;
+    promptMode?: PromptMode;
+    toolNames?: string[];
+    skillsPrompt?: string;
+    hasMemoryTools?: boolean;
+    workspaceDir?: string;
+    heartbeatPrompt?: string;
+    reasoningEnabled?: boolean;
+    runtimeInfo?: RuntimeInfo;
+    /** Per-message metadata injected as trusted system-role context. */
+    inboundMeta?: InboundMetadata;
+    bootstrapFiles?: BootstrapContextFile[];
+    extraSystemPrompt?: string;
+    /** Backward-compatible additional sections (RAG memory, etc.) */
+    additionalSections?: string[];
+    /** Pre-rendered <available_skills> XML from formatAvailableSkillsXml(). */
+    promptSkillsXml?: string;
+    /** Pre-rendered active skill content from expandSkillForInvocation(). */
+    activePromptSkillContent?: string;
+    /** Current channel context for background task announcement routing. */
+    channelContext?: {
+        channelType: string;
+        channelId: string;
+    };
+    /** Optional tool summaries for MCP/external tools (merged with TOOL_SUMMARIES defaults). */
+    toolSummaries?: Record<string, string>;
+    /** Structured subagent role params. When provided, replaces extraSystemPrompt for subagent prompts. */
+    subagentRole?: SubagentRoleParams;
+    /** User's preferred language (BCP-47 code or display name, e.g., "Hebrew", "ar"). Used as default when ambiguous. */
+    userLanguage?: string;
+    /** Reaction frequency mode for emoji reactions. undefined = section omitted. */
+    reactionLevel?: "minimal" | "extensive";
+    /** When true, enforces <think>/<final> tag format for non-Anthropic models. */
+    reasoningTagHint?: boolean;
+    /** AGENTS.md section names for post-compaction recovery. */
+    postCompactionSections?: string[];
+    /** When true, include MEDIA: directive instructions in the prompt. */
+    outboundMediaEnabled?: boolean;
+    /** When true, agent prompt includes guidance about persisted media files in workspace. */
+    mediaPersistenceEnabled?: boolean;
+    /** When true, agent prompt includes guidance about processing attachment hints with on-demand tools. */
+    autonomousMediaEnabled?: boolean;
+    /** Tool names available to sub-agents, for delegation awareness in system prompt. */
+    subAgentToolNames?: string[];
+    /** Whether sub-agents inherit MCP tools from parent (default: false). */
+    mcpToolsInherited?: boolean;
+    /** Pre-resolved sender trust entries for display. */
+    senderTrustEntries?: import("./sections/index.js").SenderTrustEntry[];
+    /** Sender trust display mode for anti-injection warning. */
+    senderTrustDisplayMode?: import("./sections/index.js").TrustDisplayMode;
+    /** Documentation config for help links section. */
+    documentationConfig?: import("@comis/core").DocumentationConfig;
+    /** When true, exclude BOOTSTRAP.md from Project Context section. */
+    excludeBootstrapFromContext?: boolean;
+    /** Workspace profile controlling platform instruction verbosity ('full' or 'specialist'). */
+    workspaceProfile?: "full" | "specialist";
+    /** Whether Silent Execution Planner (SEP) is enabled for this agent. */
+    sepEnabled?: boolean;
+}
+/**
+ * Assemble a rich multi-section system prompt.
+ *
+ * @param params - All optional parameters for section inclusion
+ * @returns Assembled system prompt string
+ */
+export declare function assembleRichSystemPrompt(params: AssemblerParams): string;
+/**
+ * Assemble a multi-block system prompt split into a static prefix, attribution, and semi-stable body.
+ *
+ * The static prefix (sections 1-1b: identity, persona) never changes per session.
+ * The attribution (sections 2-2b: safety, language) changes per-user (language preference).
+ * The semi-stable body (sections 3-22 + additionalSections) can change when MCP tools
+ * reconnect or tool schemas evolve. Splitting enables independent Anthropic `cache_control`
+ * placement so that per-user attribution changes do not invalidate the static identity prefix
+ * cache entry.
+ *
+ * **Identity invariant:** For modes "full" and "minimal":
+ * `blocks.staticPrefix + SECTION_SEPARATOR + blocks.attribution + SECTION_SEPARATOR + blocks.semiStableBody === assembleRichSystemPrompt(sameParams)`
+ *
+ * @param params - All optional parameters for section inclusion (same as assembleRichSystemPrompt)
+ * @returns SystemPromptBlocks with staticPrefix, attribution, and semiStableBody
+ */
+export declare function assembleRichSystemPromptBlocks(params: AssemblerParams): SystemPromptBlocks;

package/node_modules/@comis/agent/dist/bootstrap/system-prompt-assembler.js

@@ -0,0 +1,199 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * System prompt assembler with 3 verbosity modes.
+ *
+ * Composes 20 static section builders into a single system prompt string.
+ * Dynamic sections (date/time, inbound metadata) relocated to user-message
+ * preamble in prompt-assembly.ts for cache stability.
+ * Supports "full" (all sections), "minimal" (7 sections), and "none"
+ * (identity line only, no file I/O).
+ */
+import { buildIdentitySection, buildSafetySection, buildLanguageSection, buildToolingSection, buildToolCallStyleSection, buildSelfUpdateGatingSection, buildConfigSecretIntegritySection, buildPrivilegedToolsSection, buildTaskDelegationSection, buildCodingFallbackSection, buildCompactedOutputRecoverySection, buildPostCompactionRecoverySection, buildPersonaSection, buildSkillsSection, buildMemoryRecallSection, buildWorkspaceSection, buildMessagingSection, buildBackgroundTaskSection, buildSilentRepliesSection, buildHeartbeatsSection, buildReactionGuidanceSection, buildReasoningSection, buildRuntimeMetadataSection, buildProjectContextSection, buildSubagentContextSection, buildSubagentRoleSection, buildMediaFilesSection, buildAutonomousMediaSection, buildSenderTrustSection, buildDocumentationSection, buildTaskPlanningSection, } from "./sections/index.js";
+// ---------------------------------------------------------------------------
+// Public constants
+// ---------------------------------------------------------------------------
+/** Section separator used between all sections and between the two blocks. */
+export const SECTION_SEPARATOR = "\n\n---\n\n";
+// ---------------------------------------------------------------------------
+// Media Sharing section builder
+// ---------------------------------------------------------------------------
+/**
+ * Build the Media Sharing section for outbound MEDIA: directives.
+ *
+ * Only included when outboundMediaEnabled is true and mode is not minimal.
+ */
+function buildMediaSharingSection(outboundMediaEnabled, isMinimal) {
+    if (isMinimal || !outboundMediaEnabled)
+        return [];
+    return [
+        "## Media Sharing",
+        "",
+        "When you want to share an image or file with the user, include a line in your response with the format:",
+        "",
+        "MEDIA: <url>",
+        "",
+        "Where <url> is the direct link to the image or file. The system will automatically download the media and deliver it to the user. Guidelines:",
+        "- Use one MEDIA: line per image/file, each on its own line.",
+        "- The URL must be a direct link to the media (not a webpage containing media).",
+        "- Supported: images (JPEG, PNG, GIF, WebP), documents, audio, video.",
+        "- You can include text before or after MEDIA: lines for context/captions.",
+        "- Multiple MEDIA: lines are supported in a single response.",
+        "- MEDIA: lines will be removed from the text shown to the user.",
+        "- MEDIA: directives are for web URLs only. To send local workspace files, use the `message` tool with action=attach.",
+    ];
+}
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+/** Join non-empty section arrays into a single string with SECTION_SEPARATOR between them. */
+function joinSections(sections) {
+    const nonEmpty = sections.filter((lines) => lines.length > 0);
+    return nonEmpty.map((lines) => lines.join("\n")).join(SECTION_SEPARATOR);
+}
+/**
+ * Build all section arrays in the canonical order (1-22).
+ *
+ * Shared by both `assembleRichSystemPrompt` and `assembleRichSystemPromptBlocks`
+ * to guarantee identity by construction between both assembly functions.
+ *
+ * @returns Array of section line arrays in fixed order
+ */
+function buildAllSections(params, isMinimal) {
+    const agentName = params.agentName ?? "Comis";
+    const modelTier = isMinimal ? "small" : "large";
+    return [
+        // --- Static prefix sections (indices 0-1) ---
+        buildIdentitySection(agentName), // 1
+        buildPersonaSection(params.bootstrapFiles ?? []), // 1b: Persona (SOUL.md) before Safety
+        // --- Attribution sections (indices 2-3) ---
+        buildSafetySection(isMinimal), // 2
+        buildLanguageSection(params.userLanguage), // 2b
+        // --- Semi-stable body sections (indices 4+) ---
+        buildToolingSection(params.toolNames ?? [], modelTier, params.toolSummaries), // 3
+        buildToolCallStyleSection(isMinimal, params.toolNames ?? []), // 4
+        buildSelfUpdateGatingSection(params.toolNames ?? [], isMinimal, true), // 5: deferred to tool result
+        buildConfigSecretIntegritySection(params.toolNames ?? [], isMinimal), // 5a: always-present
+        buildPrivilegedToolsSection(params.toolNames ?? [], isMinimal, true), // 5b: deferred to tool result
+        buildCompactedOutputRecoverySection(isMinimal), // 6
+        buildPostCompactionRecoverySection(// 6a
+        params.bootstrapFiles ?? [], isMinimal, params.postCompactionSections),
+        buildCodingFallbackSection(params.toolNames ?? [], isMinimal, true), // 6b: deferred to tool result
+        buildTaskDelegationSection(params.toolNames ?? [], isMinimal, params.subAgentToolNames, params.mcpToolsInherited, true), // 6c: deferred to tool result
+        buildSkillsSection(params.skillsPrompt, isMinimal, params.promptSkillsXml, params.activePromptSkillContent), // 7: Merged filesystem + prompt skills
+        buildMemoryRecallSection(params.hasMemoryTools ?? false, isMinimal), // 8
+        buildWorkspaceSection(params.workspaceDir, isMinimal), // 9
+        params.documentationConfig
+            ? buildDocumentationSection(params.documentationConfig, params.toolNames ?? [], isMinimal)
+            : [], // 9b: Documentation
+        buildMessagingSection(params.toolNames ?? [], isMinimal, params.channelContext), // 10
+        buildBackgroundTaskSection(params.toolNames ?? [], isMinimal, params.channelContext), // 11
+        buildSilentRepliesSection(isMinimal), // 14
+        buildHeartbeatsSection(params.heartbeatPrompt, isMinimal), // 15
+        buildReactionGuidanceSection(params.reactionLevel, params.channelContext?.channelType, isMinimal), // 16
+        buildMediaSharingSection(params.outboundMediaEnabled, isMinimal), // 16b
+        buildMediaFilesSection(// 16c
+        params.hasMemoryTools ?? false, (params.toolNames ?? []).includes("message"), params.workspaceDir, params.mediaPersistenceEnabled ?? false, isMinimal),
+        buildAutonomousMediaSection(params.autonomousMediaEnabled ?? false, isMinimal), // 16d
+        buildReasoningSection(params.reasoningEnabled ?? false, isMinimal, params.reasoningTagHint ?? false), // 17
+        buildTaskPlanningSection(params.sepEnabled ?? false, isMinimal), // 17b: SEP task planning (static, cache-stable)
+        // buildDateTimeSection() removed from system prompt (relocated to user-message preamble in prompt-assembly.ts)
+        buildRuntimeMetadataSection(params.runtimeInfo ?? {}, isMinimal), // 19
+        // buildInboundMetadataSection() removed from system prompt (relocated to user-message preamble in prompt-assembly.ts)
+        buildSenderTrustSection(params.senderTrustEntries ?? [], params.senderTrustDisplayMode ?? "raw", isMinimal), // 20b
+        buildProjectContextSection(// 21
+        params.bootstrapFiles ?? [], isMinimal, params.excludeBootstrapFromContext ? new Set(["BOOTSTRAP.md"]) : undefined, params.workspaceProfile),
+        // Subagent: prefer structured params, fall back to raw extraSystemPrompt
+        ...(params.subagentRole
+            ? [buildSubagentRoleSection(params.subagentRole)]
+            : [buildSubagentContextSection(params.extraSystemPrompt)]), // 22
+    ];
+}
+/**
+ * Append additional sections (backward compat for RAG memory etc.) to a joined string.
+ *
+ * @param joined - Already-joined section string
+ * @param additionalSections - Extra sections to append
+ * @returns Final string with extras appended via SECTION_SEPARATOR
+ */
+function appendAdditionalSections(joined, additionalSections) {
+    let result = joined;
+    if (additionalSections && additionalSections.length > 0) {
+        const extras = additionalSections.filter(Boolean);
+        if (extras.length > 0) {
+            result = result + SECTION_SEPARATOR + extras.join(SECTION_SEPARATOR);
+        }
+    }
+    return result;
+}
+// ---------------------------------------------------------------------------
+// Assembler
+// ---------------------------------------------------------------------------
+/**
+ * Assemble a rich multi-section system prompt.
+ *
+ * @param params - All optional parameters for section inclusion
+ * @returns Assembled system prompt string
+ */
+export function assembleRichSystemPrompt(params) {
+    const agentName = params.agentName ?? "Comis";
+    const mode = params.promptMode ?? "full";
+    // "none" mode: identity line only, no other sections
+    if (mode === "none") {
+        return buildIdentitySection(agentName).join("\n");
+    }
+    const isMinimal = mode === "minimal";
+    const allSections = buildAllSections(params, isMinimal);
+    // Filter out empty arrays, join each section's lines, then join sections
+    const joined = joinSections(allSections);
+    // Append additional sections (backward compat for RAG memory etc.)
+    const result = appendAdditionalSections(joined, params.additionalSections);
+    // Canary token relocated to dynamic preamble in prompt-assembly.ts.
+    // OutputGuard scans response text against deps.canaryToken (passed separately),
+    // so the canary protects against leakage regardless of prompt placement.
+    return result;
+}
+// ---------------------------------------------------------------------------
+// Block assembler
+// ---------------------------------------------------------------------------
+/** Number of leading sections that form the static prefix (identity, persona). */
+const STATIC_PREFIX_SECTION_COUNT = 2;
+/** Number of attribution sections after static prefix (safety, language). */
+const ATTRIBUTION_SECTION_COUNT = 2;
+/**
+ * Assemble a multi-block system prompt split into a static prefix, attribution, and semi-stable body.
+ *
+ * The static prefix (sections 1-1b: identity, persona) never changes per session.
+ * The attribution (sections 2-2b: safety, language) changes per-user (language preference).
+ * The semi-stable body (sections 3-22 + additionalSections) can change when MCP tools
+ * reconnect or tool schemas evolve. Splitting enables independent Anthropic `cache_control`
+ * placement so that per-user attribution changes do not invalidate the static identity prefix
+ * cache entry.
+ *
+ * **Identity invariant:** For modes "full" and "minimal":
+ * `blocks.staticPrefix + SECTION_SEPARATOR + blocks.attribution + SECTION_SEPARATOR + blocks.semiStableBody === assembleRichSystemPrompt(sameParams)`
+ *
+ * @param params - All optional parameters for section inclusion (same as assembleRichSystemPrompt)
+ * @returns SystemPromptBlocks with staticPrefix, attribution, and semiStableBody
+ */
+export function assembleRichSystemPromptBlocks(params) {
+    const agentName = params.agentName ?? "Comis";
+    const mode = params.promptMode ?? "full";
+    // "none" mode: identity line only in prefix, empty attribution and body
+    if (mode === "none") {
+        return {
+            staticPrefix: buildIdentitySection(agentName).join("\n"),
+            attribution: "",
+            semiStableBody: "",
+        };
+    }
+    const isMinimal = mode === "minimal";
+    const allSections = buildAllSections(params, isMinimal);
+    // Split at boundaries: identity+persona | safety+language | tooling+workspace+...
+    const staticSections = allSections.slice(0, STATIC_PREFIX_SECTION_COUNT);
+    const attributionSections = allSections.slice(STATIC_PREFIX_SECTION_COUNT, STATIC_PREFIX_SECTION_COUNT + ATTRIBUTION_SECTION_COUNT);
+    const bodySections = allSections.slice(STATIC_PREFIX_SECTION_COUNT + ATTRIBUTION_SECTION_COUNT);
+    const staticPrefix = joinSections(staticSections);
+    const attribution = joinSections(attributionSections);
+    const semiStableBody = appendAdditionalSections(joinSections(bodySections), params.additionalSections);
+    return { staticPrefix, attribution, semiStableBody };
+}

package/node_modules/@comis/agent/dist/bootstrap/types.d.ts

@@ -0,0 +1,96 @@
+/**
+ * Bootstrap types for workspace file loading and system prompt assembly.
+ *
+ * These types support the workspace loader (loading all 7 workspace files
+ * with truncation and missing-file markers) and the system prompt assembler
+ * (composing rich multi-section prompts with verbosity modes).
+ */
+import type { WorkspaceFileName } from "../workspace/templates.js";
+/**
+ * A workspace file loaded (or attempted) from the agent workspace directory.
+ *
+ * - `missing: false` means the file was read successfully and `content` is set.
+ * - `missing: true` means the file was not found; `content` is undefined.
+ */
+export interface BootstrapFile {
+    /** Workspace file name (e.g. "SOUL.md", "AGENTS.md") */
+    readonly name: WorkspaceFileName;
+    /** Resolved absolute path on disk */
+    readonly path: string;
+    /** File content (present only when file exists) */
+    readonly content?: string;
+    /** Whether the file was missing from the workspace */
+    readonly missing: boolean;
+}
+/**
+ * Result of truncating a file's content to fit within maxChars.
+ */
+export interface TruncationResult {
+    /** The (possibly truncated) content */
+    readonly content: string;
+    /** Whether truncation was applied */
+    readonly truncated: boolean;
+    /** Original content length before truncation */
+    readonly originalLength: number;
+}
+/**
+ * System prompt verbosity mode.
+ *
+ * - `"full"`: All workspace sections included (primary agents)
+ * - `"minimal"`: Only AGENTS.md + TOOLS.md (sub-agents)
+ * - `"none"`: Identity-only prompt (lightweight contexts)
+ */
+export type PromptMode = "full" | "minimal" | "none";
+/**
+ * Runtime metadata injected into the system prompt header.
+ */
+export interface RuntimeInfo {
+    readonly agentId?: string;
+    readonly host?: string;
+    readonly os?: string;
+    readonly arch?: string;
+    readonly model?: string;
+    readonly thinkingLevel?: string;
+    /** Node.js version (e.g., "20.11.0") */
+    readonly nodeVersion?: string;
+    /** User's default shell (e.g., "/bin/zsh") */
+    readonly shell?: string;
+    /** Configured default model string */
+    readonly defaultModel?: string;
+    /** Current channel type (e.g., "telegram") */
+    readonly channel?: string;
+    /** Comma-separated capability summary (e.g., "reactions, threads, fetch") */
+    readonly channelCapabilities?: string;
+}
+/**
+ * Per-message metadata injected as trusted system-role context.
+ * Changes on every message turn (unlike RuntimeInfo which is static per session).
+ */
+export interface InboundMetadata {
+    readonly messageId: string;
+    readonly senderId: string;
+    readonly senderTrust?: string;
+    readonly chatId: string;
+    readonly channel: string;
+    readonly chatType: string;
+    readonly flags: Record<string, boolean>;
+}
+/**
+ * Output format for assembled bootstrap context files.
+ * Used by the system prompt assembler to compose sections.
+ */
+export interface BootstrapContextFile {
+    /** Display path (typically the workspace file name) */
+    readonly path: string;
+    /** File content (possibly truncated or a [MISSING] marker) */
+    readonly content: string;
+}
+/**
+ * Workspace file names allowed in sub-agent bootstrap context.
+ * Sub-agents only receive AGENTS.md (instructions) and TOOLS.md (tool notes).
+ */
+export declare const SUBAGENT_BOOTSTRAP_ALLOWLIST: Set<"AGENTS.md" | "SOUL.md" | "IDENTITY.md" | "USER.md" | "ROLE.md" | "TOOLS.md" | "HEARTBEAT.md" | "BOOTSTRAP.md" | "BOOT.md">;
+/** Head portion ratio for truncation (first 70% of maxChars) */
+export declare const BOOTSTRAP_HEAD_RATIO = 0.7;
+/** Tail portion ratio for truncation (last 20% of maxChars) */
+export declare const BOOTSTRAP_TAIL_RATIO = 0.2;

package/node_modules/@comis/agent/dist/bootstrap/types.js

@@ -0,0 +1,21 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Bootstrap types for workspace file loading and system prompt assembly.
+ *
+ * These types support the workspace loader (loading all 7 workspace files
+ * with truncation and missing-file markers) and the system prompt assembler
+ * (composing rich multi-section prompts with verbosity modes).
+ */
+/**
+ * Workspace file names allowed in sub-agent bootstrap context.
+ * Sub-agents only receive AGENTS.md (instructions) and TOOLS.md (tool notes).
+ */
+export const SUBAGENT_BOOTSTRAP_ALLOWLIST = new Set([
+    "AGENTS.md",
+    "ROLE.md",
+    "TOOLS.md",
+]);
+/** Head portion ratio for truncation (first 70% of maxChars) */
+export const BOOTSTRAP_HEAD_RATIO = 0.7;
+/** Tail portion ratio for truncation (last 20% of maxChars) */
+export const BOOTSTRAP_TAIL_RATIO = 0.2;

package/node_modules/@comis/agent/dist/bootstrap/workspace-loader.d.ts

@@ -0,0 +1,121 @@
+/**
+ * Workspace file loader for bootstrap context injection.
+ *
+ * Loads 8 workspace files (SOUL.md, IDENTITY.md, USER.md, AGENTS.md,
+ * TOOLS.md, HEARTBEAT.md, BOOTSTRAP.md, BOOT.md) with per-file truncation
+ * and missing-file markers. BOOT.md is excluded from bootstrap loading
+ * (injected separately via prompt-assembly on first session message).
+ * Uses safePath for path traversal prevention.
+ */
+import type { BootstrapFile, BootstrapContextFile, TruncationResult } from "./types.js";
+/**
+ * Options for workspace file injection scanning.
+ */
+export interface WorkspaceScanOptions {
+    /** When true, scan workspace files for injection patterns (default: true). */
+    enabled?: boolean;
+    /** When true, replace file content with [BLOCKED] marker on critical findings (default: true). */
+    blockOnCritical?: boolean;
+    /** Callback fired when injection patterns are detected in a workspace file. */
+    onScanResult?: (info: {
+        fileName: string;
+        patterns: string[];
+        blocked: boolean;
+        invisibleCharsStripped: boolean;
+    }) => void;
+}
+/**
+ * Scan workspace file content for invisible characters and injection patterns.
+ *
+ * Combines stripInvisible() for zero-width/tag block char removal with
+ * detectSuspiciousPatterns() for the 17 base patterns and the 5
+ * workspace-specific scanner patterns.
+ *
+ * @param content - Raw file content
+ * @returns Cleaned content, detected pattern sources, and whether invisible chars were stripped
+ */
+export declare function scanWorkspaceContent(content: string): {
+    cleaned: string;
+    patterns: string[];
+    invisibleStripped: boolean;
+};
+/**
+ * Truncate file content to fit within maxChars using a head+tail strategy.
+ *
+ * Keeps the first 70% and last 20% of the allowed character budget,
+ * inserting a truncation marker in the middle that tells the agent how
+ * to read the full file.
+ *
+ * @param content - Raw file content
+ * @param fileName - File name for the truncation marker
+ * @param maxChars - Maximum allowed characters
+ * @returns Truncation result with content, truncated flag, and original length
+ */
+export declare function truncateFileContent(content: string, fileName: string, maxChars: number): TruncationResult;
+/**
+ * Load workspace bootstrap files from the agent workspace directory.
+ *
+ * Iterates over all 8 WORKSPACE_FILE_NAMES, resolving each path with
+ * safePath for traversal prevention. Missing files are included in the
+ * result with `missing: true` and no content field. BOOT.md is excluded
+ * from the returned array (injected separately via prompt-assembly).
+ *
+ * @param workspaceDir - Absolute path to the agent workspace directory
+ * @param maxChars - Per-file character limit (default 20000, used for info only here)
+ * @returns Array of BootstrapFile objects (BOOT.md excluded from bootstrap loading)
+ */
+export declare function loadWorkspaceBootstrapFiles(workspaceDir: string, _maxChars?: number): Promise<BootstrapFile[]>;
+/**
+ * Filter bootstrap files to only those allowed for sub-agents.
+ *
+ * Sub-agents receive a minimal bootstrap context containing only
+ * AGENTS.md (operating instructions) and TOOLS.md (tool notes).
+ *
+ * @param files - Full array of loaded bootstrap files
+ * @returns Filtered array containing only AGENTS.md and TOOLS.md
+ */
+export declare function filterBootstrapFilesForSubAgent(files: BootstrapFile[]): BootstrapFile[];
+/**
+ * Filter bootstrap files for lightweight heartbeat context mode.
+ *
+ * When heartbeat.lightContext is true, only HEARTBEAT.md is injected into
+ * the system prompt -- SOUL.md, IDENTITY.md, USER.md, AGENTS.md, TOOLS.md,
+ * and BOOTSTRAP.md are all stripped. This reduces token usage for routine
+ * heartbeat ticks where personality and full context are not needed.
+ *
+ * @param files - Full array of loaded bootstrap files
+ * @returns Filtered array containing only HEARTBEAT.md
+ */
+export declare function filterBootstrapFilesForLightContext(files: BootstrapFile[]): BootstrapFile[];
+/**
+ * Filter bootstrap files for group chat context.
+ *
+ * When group chat filtering is enabled, USER.md is excluded from
+ * the bootstrap context to protect user privacy in multi-user
+ * conversations.
+ *
+ * @param files - Full array of loaded bootstrap files
+ * @returns Filtered array with USER.md removed
+ */
+export declare function filterBootstrapFilesForGroupChat(files: BootstrapFile[]): BootstrapFile[];
+/**
+ * Build bootstrap context files from loaded workspace files.
+ *
+ * For each file:
+ * - Missing files produce a `[MISSING] Expected at: <path>` marker
+ * - Present files are scanned for injection patterns when `scan` is provided
+ * - Critical findings replace content with `[BLOCKED: ...]` marker
+ * - Present files are truncated to maxChars using head+tail strategy
+ * - An optional warn callback is called when truncation occurs
+ *
+ * Scanning is opt-in: omitting `scan` preserves backward-compatible behavior.
+ *
+ * @param files - Loaded bootstrap files
+ * @param opts - Options: maxChars limit, warn callback, and scan options
+ * @returns Array of context files ready for system prompt injection
+ */
+export declare function buildBootstrapContextFiles(files: BootstrapFile[], opts?: {
+    maxChars?: number;
+    warn?: (msg: string) => void;
+    scan?: WorkspaceScanOptions;
+}): BootstrapContextFile[];