@slopus/rig 0.0.4 → 0.0.6

package/README.md

@@ -25,9 +25,16 @@ rig stays close to pi and to upstream vendor behavior, but adds a curated defaul
 - Simplified system prompts that are easier to reason about and reuse.
 - Per-model and per-vendor prompt/tool optimizations, so different inference providers can work well without forcing users into one stack.
 - Bundled subagents for common coding workflows.
-- Background workers for longer-running or asynchronous tasks.
+- Provider-aligned task planning with Codex `update_plan` and Claude's persistent task tools.
+- Structured user questions with provider-aligned tools and terminal or web answer controls.
+- MCP tool servers over stdio or streamable HTTP, with Codex- and Claude-compatible configuration.
+- Background subagents with completion notifications and follow-up turns.
+- Managed shell sessions for long-running commands and interactive input.
 - Workflow presets for repeated engineering operations.
 - Auto mode for hands-off execution when a project allows it.
+- Persistent goals that continue across agent turns until they are completed, paused, or blocked.
+- Findings-first local code review with `/review` for current workspace changes.
+- Automatic conversation compaction for long sessions, plus `/compact` when you want to free context space immediately.
 - Sandboxing defaults that make local execution practical while keeping controls visible.
 - Per-project enable/disable behavior, so teams can use rig where it helps and leave other repos untouched.
 
@@ -35,12 +42,23 @@ rig stays close to pi and to upstream vendor behavior, but adds a curated defaul
 
 rig is intentionally opinionated, but not locked down:
 
+- Best of both worlds. Combine the strongest ideas from Codex and Claude Code into one coherent experience instead of cloning either product wholesale.
 - Good defaults first. A fresh install should already feel usable.
+- Simplicity and polish. Prefer clear, pleasant workflows over obscure features, exhaustive parity, or unnecessary configuration.
 - Provider flexibility. The harness should work across proprietary and open source models.
 - Project-local control. Repos should be able to enable, disable, or override behavior without changing global machine state.
 - Close to upstream. Tool definitions and model expectations should track vendor semantics closely.
 - Less ceremony. Common agent features should not require a custom setup ritual on every machine.
 
+## Deliberate non-goals
+
+rig aims for the best mainstream coding-agent experience, not a union of every
+feature exposed by Codex and Claude Code. It intentionally does not implement:
+
+- A dedicated Plan mode. Planning remains part of the normal agent workflow instead of a separate permission mode or interaction state.
+- Vim or other modal terminal editing modes. The terminal input experience stays simple and conventional.
+- Niche parity features whose main value is matching a rarely used upstream flag, command, protocol, or edge case. New parity work should solve a common user need and fit rig's simpler product model.
+
 ## Intended experience
 
 Install rig once, open a project, and get a capable coding harness with prompts, tools, subagents, workflows, workers, automation, and sandboxing already wired together.
@@ -51,6 +69,11 @@ When a project needs different behavior, configure it locally. When a machine ch
 
 This is a single-package TypeScript project. Source files live in `sources/`, with `sources/main.ts` as the CLI entry point.
 
+Reference implementations for coding agents live in
+`~/Developer/coding-assistant-sources`, including the Codex and Claude Code
+source trees. Use them when implementing or comparing provider-aligned behavior,
+then adapt the useful parts to rig's simpler, curated experience.
+
 ```sh
 pnpm install
 pnpm run check
@@ -108,6 +131,126 @@ pnpm dev:web
 Open the Vite URL printed by `pnpm dev:web`, usually `http://127.0.0.1:5173`.
 The Vite dev server proxies `/api/*` to the local daemon socket.
 
+### Permission modes
+
+New sessions start in **Workspace write** mode. File tools can edit the working
+directory, while shell writes outside it and shell network access are blocked.
+Git metadata and temporary files remain writable so normal development commands
+continue to work.
+
+Use `/permissions` in the terminal or the Permissions control in the web
+inspector to switch the current session and its subagents between:
+
+- **Auto** — run routine workspace work immediately and review risky actions automatically, asking only when needed.
+- **Workspace write** — write in the working directory with shell network access blocked.
+- **Read only** — keep project files read only; shell commands may write temporary files.
+- **Full access** — allow unrestricted filesystem, shell, and network access.
+
+In Auto mode, shell commands remain workspace-sandboxed by default. Codex
+`exec_command` can request `sandbox_permissions = "require_escalated"`, and
+Claude `Bash` can request `dangerouslyDisableSandbox = true`; both requests are
+reviewed before receiving one-call full access.
+
+Set the terminal default in global or project-local `rig.toml`:
+
+```toml
+[defaults]
+permission_mode = "workspace_write"
+```
+
+`RIG_PERMISSION_MODE` overrides the configured default for a newly created
+terminal session. Accepted values are `workspace_write`, `read_only`, and
+`full_access`, and `auto`.
+
+### Persistent goals
+
+Use `/goal` followed by an objective to start long-running work that may need
+more than one agent turn. Rig keeps the objective on the session and
+automatically continues while the goal remains active. Use `/goal` by itself to
+check its status, `/goal pause` to stop automatic continuation, `/goal resume`
+to continue, and `/goal clear` to remove it.
+
+Models receive `get_goal`, `create_goal`, and `update_goal` tools. A model can
+mark the goal complete after verifying the full objective, or blocked when it
+cannot make meaningful progress without user input or an external change.
+Goals survive daemon restarts and are available from both the terminal and web
+session inspector.
+
+### Code review
+
+Use `/review` to inspect current staged, unstaged, and untracked changes without
+modifying them. Add a focus after the command when useful, such as
+`/review focus on concurrency`. Reviews lead with actionable findings ordered
+by severity and include file references, concrete impact, and remaining test
+gaps. The command works in terminal and web-backed sessions.
+
+### Task tracking
+
+Claude sessions use the current `TaskCreate`, `TaskGet`, `TaskUpdate`, and
+`TaskList` tools. Tasks, dependencies, and progress survive daemon restarts and
+are shared with the session's subagents. Use `/tasks` in the terminal or the
+Tasks section in the web inspector to see the current list.
+
+### Background subagents
+
+Claude sessions can set `run_in_background` on the `Agent` tool and use
+`SendMessage` for follow-up work. Codex sessions use `spawn_agent`,
+`followup_task`, `wait_agent`, `list_agents`, and
+`interrupt_agent`. Each child keeps its own persisted conversation, reports a
+completion notification to its parent, and can receive more work without losing
+context. Use `/agents` in the terminal or Delegated work in the web inspector to
+see current status and open a child transcript.
+
+Team/swarm coordination, remote agents, and automatic worktree isolation are
+intentionally outside this core workflow.
+
+### Long-running commands
+
+Codex `exec_command` now yields a live session when a command outlasts its wait
+window; `write_stdin` can poll it, send input, or interrupt it. Claude `Bash`
+honors `run_in_background`, with `TaskOutput` for later results and `TaskStop`
+for cancellation. These commands retain the session's permission and sandbox
+mode instead of escaping into an unmanaged process.
+
+### MCP tool servers
+
+Rig discovers tools from MCP servers when a workspace first runs. Codex-style
+servers can be configured globally in `~/.config/rig/config.toml` or locally in
+`rig.toml`:
+
+```toml
+[mcp_servers.docs]
+command = "docs-mcp-server"
+args = ["--stdio"]
+tool_timeout_sec = 30
+
+[mcp_servers.issues]
+url = "https://example.com/mcp"
+bearer_token_env_var = "ISSUES_MCP_TOKEN"
+```
+
+Claude-style project configuration is also supported in `.mcp.json`:
+
+```json
+{
+    "mcpServers": {
+        "docs": {
+            "type": "stdio",
+            "command": "docs-mcp-server",
+            "args": ["--stdio"]
+        }
+    }
+}
+```
+
+Use `/mcp` in the terminal or the MCP servers section in the web inspector to
+check connection failures and discovered tool counts. Restart the daemon after
+changing MCP configuration. OAuth, legacy SSE transports, MCP prompts, and MCP
+resources are not yet supported.
+
+Only configure servers you trust. Stdio servers are local processes that receive
+the daemon environment and are not restricted by the session filesystem sandbox.
+
 ## Publishing
 
 Authenticate with npm once using `pnpm login`, then publish from a clean, up-to-date

package/dist/agent/Agent.d.ts

@@ -3,6 +3,7 @@ import { type AgentLoopEvent, type AgentLoopResult } from "./loop.js";
 import { type AgentConsole } from "./printAgentMessageToConsole.js";
 import type { AnyDefinedTool, ContentBlock, Message, SystemMessage, UserMessage } from "./types.js";
 import type { Model, Provider } from "../providers/types.js";
+import type { PermissionMode } from "../permissions/index.js";
 export type AgentStatus = "idle" | "running" | "aborted";
 export interface QueuedAgentMessage {
     id: string;
@@ -16,6 +17,8 @@ export interface AgentSnapshot {
     status: AgentStatus;
     instructions?: string;
     messages: readonly Message[];
+    /** Compacted model-facing history. Omitted while it matches the visible transcript. */
+    contextMessages?: readonly Message[];
     queue: readonly QueuedAgentMessage[];
     tools: readonly string[];
     lastRunId?: string;
@@ -27,6 +30,7 @@ export interface AgentOptions {
     id?: string;
     effort?: string;
     messages?: readonly Message[];
+    contextMessages?: readonly Message[];
     instructions?: string;
     tools?: readonly AnyDefinedTool[];
     idFactory?: () => string;
@@ -45,6 +49,13 @@ export interface AgentRunOptions {
 export interface AgentRunResult extends AgentLoopResult {
     runId: string;
 }
+export interface AgentCompactionResult {
+    compacted: boolean;
+    compactedMessageCount: number;
+    estimatedTokensAfter: number;
+    estimatedTokensBefore: number;
+    retainedMessageCount: number;
+}
 export declare class Agent {
     #private;
     readonly id: string;
@@ -56,17 +67,22 @@ export declare class Agent {
     get messages(): readonly Message[];
     get queue(): readonly QueuedAgentMessage[];
     get tools(): readonly AnyDefinedTool[];
+    get permissionMode(): PermissionMode;
     get canChangeModel(): boolean;
     setInstructions(instructions: string | undefined): void;
     setEffort(effort: string | undefined): void;
     setModel(modelId: string, effort: string | undefined): void;
     setTools(tools: readonly AnyDefinedTool[]): void;
+    setPermissionMode(mode: PermissionMode): void;
     reset(): void;
     addSteering(text: string): SystemMessage;
     enqueueSystemMessage(text: string): SystemMessage;
     enqueueUserMessage(text: string | readonly ContentBlock[]): UserMessage;
     enqueueMessage(message: Message): QueuedAgentMessage;
     send(text: string | readonly ContentBlock[], options?: AgentRunOptions): Promise<AgentRunResult>;
+    steer(content: string | readonly ContentBlock[]): Promise<void>;
+    steerMessage(message: UserMessage): void;
+    compact(signal?: AbortSignal): Promise<AgentCompactionResult>;
     run(options?: AgentRunOptions): Promise<AgentRunResult>;
     snapshot(): AgentSnapshot;
 }

package/dist/agent/Agent.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Agent.d.ts","sourceRoot":"","sources":["../../sources/agent/Agent.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"Agent.d.ts","sourceRoot":"","sources":["../../sources/agent/Agent.ts"],"names":[],"mappings":"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"}

package/dist/agent/Agent.js

@@ -1,4 +1,5 @@
 import { createId } from "@paralleldrive/cuid2";
+import { compactConversation } from "./compaction/compactConversation.js";
 import { runAgentLoop } from "./loop.js";
 import { printAgentMessageToConsole } from "./printAgentMessageToConsole.js";
 import { selectToolsForModel } from "./selectToolsForModel.js";
@@ -18,7 +19,9 @@ export class Agent {
     #onEvent;
     #onMessage;
     #messages = [];
+    #contextMessages;
     #queue = [];
+    #steeringQueue = [];
     #status = "idle";
     #lastRunId;
     #activeRunId;
@@ -44,6 +47,8 @@ export class Agent {
         this.#onEvent = options.onEvent;
         this.#onMessage = options.onMessage;
         this.#messages = [...(options.messages ?? [])];
+        this.#contextMessages =
+            options.contextMessages === undefined ? undefined : [...options.contextMessages];
     }
     get status() {
         return this.#status;
@@ -60,6 +65,9 @@ export class Agent {
     get tools() {
         return this.#tools;
     }
+    get permissionMode() {
+        return this.context.permissions?.mode ?? "full_access";
+    }
     get canChangeModel() {
         return (this.#messages.length === 0 &&
             this.#queue.length === 0 &&
@@ -82,12 +90,24 @@ export class Agent {
             });
         }
     }
+    #takeSteering() {
+        const steering = this.#steeringQueue;
+        this.#steeringQueue = [];
+        for (const message of steering)
+            this.#printMessage(message);
+        return steering;
+    }
     setTools(tools) {
         this.#tools = tools;
     }
+    setPermissionMode(mode) {
+        this.context.permissions?.setMode(mode);
+    }
     reset() {
         this.#messages = [];
+        this.#contextMessages = undefined;
         this.#queue = [];
+        this.#steeringQueue = [];
         this.#lastRunId = undefined;
         this.#resetVersion += 1;
         if (this.#activeRunId === undefined) {
@@ -130,6 +150,42 @@ export class Agent {
         this.enqueueUserMessage(text);
         return this.run(options);
     }
+    async steer(content) {
+        this.steerMessage({
+            role: "user",
+            id: this.#idFactory(),
+            blocks: typeof content === "string" ? [{ type: "text", text: content }] : content,
+        });
+    }
+    steerMessage(message) {
+        if (this.#activeRunId === undefined) {
+            throw new Error(`Agent '${this.id}' is not running`);
+        }
+        this.#steeringQueue.push(message);
+    }
+    async compact(signal) {
+        if (this.#activeRunId !== undefined) {
+            throw new Error("Wait for the active response to finish before compacting.");
+        }
+        const runId = this.#idFactory();
+        this.#activeRunId = runId;
+        this.#status = "running";
+        try {
+            const result = await this.#compactContext({
+                force: true,
+                preserveLatestUserMessage: false,
+                ...(signal !== undefined ? { signal } : {}),
+            });
+            this.#status = "idle";
+            return result;
+        }
+        finally {
+            if (this.#activeRunId === runId)
+                this.#activeRunId = undefined;
+            if (this.#status === "running")
+                this.#status = signal?.aborted ? "aborted" : "idle";
+        }
+    }
     async run(options = {}) {
         if (this.#activeRunId !== undefined) {
             throw new Error(`Agent '${this.id}' is already running`);
@@ -141,6 +197,20 @@ export class Agent {
         this.#status = "running";
         this.#drainQueueToTranscript();
         try {
+            try {
+                await this.#compactContext({
+                    force: false,
+                    preserveLatestUserMessage: true,
+                    ...(options.signal !== undefined ? { signal: options.signal } : {}),
+                });
+            }
+            catch (error) {
+                // The main loop still gets a chance to report an abort or the provider's
+                // context-limit error when automatic compaction is unavailable.
+                if (!options.signal?.aborted) {
+                    this.#console.error?.(`[agent:${this.id}] automatic compaction failed`, error);
+                }
+            }
             const loopOptions = {
                 provider: this.provider,
                 modelId: this.#model.id,
@@ -152,7 +222,11 @@ export class Agent {
                 context: this.context,
                 onEvent: async (event) => this.#handleEvent(event, options),
                 onMessage: async (message) => this.#handleMessage(message, options),
+                takeSteering: () => this.#takeSteering(),
             };
+            if (this.#contextMessages !== undefined) {
+                loopOptions.contextMessages = this.#contextMessages;
+            }
             if (this.#effort !== undefined)
                 loopOptions.effort = this.#effort;
             if (this.#instructions !== undefined)
@@ -163,8 +237,12 @@ export class Agent {
             if (this.#activeRunId === runId) {
                 this.#activeRunId = undefined;
             }
+            this.#steeringQueue = [];
             if (this.#resetVersion === resetVersion) {
                 this.#messages = [...result.messages];
+                if (this.#contextMessages !== undefined) {
+                    this.#contextMessages = [...result.contextMessages];
+                }
                 this.#status = result.stopReason === "aborted" ? "aborted" : "idle";
             }
             else if (this.#status === "running") {
@@ -179,6 +257,7 @@ export class Agent {
             if (this.#activeRunId === runId) {
                 this.#activeRunId = undefined;
             }
+            this.#steeringQueue = [];
             if (this.#resetVersion === resetVersion) {
                 this.#status = options.signal?.aborted ? "aborted" : "idle";
             }
@@ -198,6 +277,9 @@ export class Agent {
             queue: [...this.#queue],
             tools: this.#tools.map((tool) => tool.name),
             ...(this.#effort !== undefined ? { effort: this.#effort } : {}),
+            ...(this.#contextMessages !== undefined
+                ? { contextMessages: [...this.#contextMessages] }
+                : {}),
             ...(this.#instructions !== undefined ? { instructions: this.#instructions } : {}),
             ...(this.#lastRunId !== undefined ? { lastRunId: this.#lastRunId } : {}),
         };
@@ -217,9 +299,33 @@ export class Agent {
         this.#queue = [];
         for (const entry of queued) {
             this.#messages.push(entry.message);
+            this.#contextMessages?.push(entry.message);
             this.#printMessage(entry.message);
         }
     }
+    async #compactContext(options) {
+        const result = await compactConversation({
+            provider: this.provider,
+            model: this.#model,
+            messages: this.#contextMessages ?? this.#messages,
+            idFactory: this.#idFactory,
+            now: this.#now,
+            force: options.force,
+            preserveLatestUserMessage: options.preserveLatestUserMessage,
+            ...(this.#effort !== undefined ? { effort: this.#effort } : {}),
+            ...(options.signal !== undefined ? { signal: options.signal } : {}),
+        });
+        if (result.compacted) {
+            this.#contextMessages = [...result.contextMessages];
+        }
+        return {
+            compacted: result.compacted,
+            compactedMessageCount: result.compactedMessageCount,
+            estimatedTokensAfter: result.estimatedTokensAfter,
+            estimatedTokensBefore: result.estimatedTokensBefore,
+            retainedMessageCount: result.retainedMessageCount,
+        };
+    }
     #printMessage(message) {
         if (!this.#printToConsole) {
             return;

package/dist/agent/compaction/compactConversation.d.ts

@@ -0,0 +1,22 @@
+import type { Message } from "../types.js";
+import type { Model, Provider } from "../../providers/types.js";
+export interface CompactConversationResult {
+    compacted: boolean;
+    compactedMessageCount: number;
+    contextMessages: readonly Message[];
+    estimatedTokensAfter: number;
+    estimatedTokensBefore: number;
+    retainedMessageCount: number;
+}
+export declare function compactConversation(options: {
+    provider: Provider;
+    model: Model;
+    messages: readonly Message[];
+    idFactory: () => string;
+    now: () => number;
+    effort?: string;
+    force: boolean;
+    preserveLatestUserMessage: boolean;
+    signal?: AbortSignal;
+}): Promise<CompactConversationResult>;
+//# sourceMappingURL=compactConversation.d.ts.map

package/dist/agent/compaction/compactConversation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"compactConversation.d.ts","sourceRoot":"","sources":["../../../sources/agent/compaction/compactConversation.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,OAAO,EAAe,MAAM,aAAa,CAAC;AACxD,OAAO,KAAK,EAAE,KAAK,EAAE,QAAQ,EAAE,MAAM,0BAA0B,CAAC;AAMhE,MAAM,WAAW,yBAAyB;IACtC,SAAS,EAAE,OAAO,CAAC;IACnB,qBAAqB,EAAE,MAAM,CAAC;IAC9B,eAAe,EAAE,SAAS,OAAO,EAAE,CAAC;IACpC,oBAAoB,EAAE,MAAM,CAAC;IAC7B,qBAAqB,EAAE,MAAM,CAAC;IAC9B,oBAAoB,EAAE,MAAM,CAAC;CAChC;AAED,wBAAsB,mBAAmB,CAAC,OAAO,EAAE;IAC/C,QAAQ,EAAE,QAAQ,CAAC;IACnB,KAAK,EAAE,KAAK,CAAC;IACb,QAAQ,EAAE,SAAS,OAAO,EAAE,CAAC;IAC7B,SAAS,EAAE,MAAM,MAAM,CAAC;IACxB,GAAG,EAAE,MAAM,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,OAAO,CAAC;IACf,yBAAyB,EAAE,OAAO,CAAC;IACnC,MAAM,CAAC,EAAE,WAAW,CAAC;CACxB,GAAG,OAAO,CAAC,yBAAyB,CAAC,CAkDrC"}

package/dist/agent/compaction/compactConversation.js

@@ -0,0 +1,77 @@
+import { estimateMessagesTokens } from "./estimateMessagesTokens.js";
+import { requestCompactionSummary } from "./requestCompactionSummary.js";
+const DEFAULT_CONTEXT_WINDOW = 200_000;
+const AUTO_COMPACT_FRACTION = 0.85;
+const RETAINED_CONTEXT_FRACTION = 0.1;
+export async function compactConversation(options) {
+    const estimatedTokensBefore = estimateMessagesTokens(options.messages);
+    const contextWindow = options.model.contextWindow ?? DEFAULT_CONTEXT_WINDOW;
+    if (!options.force && estimatedTokensBefore < contextWindow * AUTO_COMPACT_FRACTION) {
+        return unchanged(options.messages, estimatedTokensBefore);
+    }
+    const systemMessages = options.messages.filter((message) => message.role === "system");
+    const conversation = options.messages.filter((message) => message.role !== "system");
+    const keepStart = options.preserveLatestUserMessage
+        ? findRetainedStart(conversation, contextWindow)
+        : conversation.length;
+    const messagesToCompact = conversation.slice(0, keepStart);
+    const retainedMessages = conversation.slice(keepStart);
+    if (messagesToCompact.length < 2 ||
+        !messagesToCompact.some((message) => message.role === "agent")) {
+        return unchanged(options.messages, estimatedTokensBefore);
+    }
+    const summary = await requestCompactionSummary({
+        provider: options.provider,
+        model: options.model,
+        messages: messagesToCompact,
+        now: options.now,
+        ...(options.effort !== undefined ? { effort: options.effort } : {}),
+        ...(options.signal !== undefined ? { signal: options.signal } : {}),
+    });
+    const summaryMessage = {
+        role: "user",
+        id: options.idFactory(),
+        blocks: [
+            {
+                type: "text",
+                text: `<conversation_summary>\n${summary}\n</conversation_summary>`,
+            },
+        ],
+    };
+    const contextMessages = [...systemMessages, summaryMessage, ...retainedMessages];
+    return {
+        compacted: true,
+        compactedMessageCount: messagesToCompact.length,
+        contextMessages,
+        estimatedTokensAfter: estimateMessagesTokens(contextMessages),
+        estimatedTokensBefore,
+        retainedMessageCount: retainedMessages.length,
+    };
+}
+function findRetainedStart(messages, contextWindow) {
+    const userIndexes = messages.flatMap((message, index) => message.role === "user" ? [index] : []);
+    const latestUserIndex = userIndexes.at(-1);
+    if (latestUserIndex === undefined)
+        return messages.length;
+    const retainedTokenTarget = Math.max(32, Math.floor(contextWindow * RETAINED_CONTEXT_FRACTION));
+    let keepStart = latestUserIndex;
+    for (let index = userIndexes.length - 2; index >= 0; index -= 1) {
+        const candidate = userIndexes[index];
+        if (candidate === undefined)
+            continue;
+        if (estimateMessagesTokens(messages.slice(candidate)) > retainedTokenTarget)
+            break;
+        keepStart = candidate;
+    }
+    return keepStart;
+}
+function unchanged(messages, estimatedTokens) {
+    return {
+        compacted: false,
+        compactedMessageCount: 0,
+        contextMessages: messages,
+        estimatedTokensAfter: estimatedTokens,
+        estimatedTokensBefore: estimatedTokens,
+        retainedMessageCount: messages.length,
+    };
+}

package/dist/agent/compaction/estimateMessagesTokens.d.ts

@@ -0,0 +1,3 @@
+import type { Message } from "../types.js";
+export declare function estimateMessagesTokens(messages: readonly Message[]): number;
+//# sourceMappingURL=estimateMessagesTokens.d.ts.map

package/dist/agent/compaction/estimateMessagesTokens.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"estimateMessagesTokens.d.ts","sourceRoot":"","sources":["../../../sources/agent/compaction/estimateMessagesTokens.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AAK3C,wBAAgB,sBAAsB,CAAC,QAAQ,EAAE,SAAS,OAAO,EAAE,GAAG,MAAM,CA8B3E"}

package/dist/agent/compaction/estimateMessagesTokens.js

@@ -0,0 +1,39 @@
+const IMAGE_TOKEN_ESTIMATE = 1_600;
+const MESSAGE_OVERHEAD_TOKENS = 8;
+export function estimateMessagesTokens(messages) {
+    let characters = 0;
+    let fixedTokens = messages.length * MESSAGE_OVERHEAD_TOKENS;
+    for (const message of messages) {
+        for (const block of message.blocks) {
+            if (block.type === "image") {
+                fixedTokens += IMAGE_TOKEN_ESTIMATE;
+            }
+            else if (block.type === "text") {
+                characters += block.text.length;
+            }
+            else if (block.type === "thinking") {
+                characters += block.thinking.length;
+            }
+            else if (block.type === "tool_call") {
+                characters += block.name.length + safeJson(block.arguments).length;
+            }
+            else {
+                characters +=
+                    block.toolName.length +
+                        block.rendered.reduce((total, content) => total +
+                            (content.type === "text"
+                                ? content.text.length
+                                : IMAGE_TOKEN_ESTIMATE * 4), 0);
+            }
+        }
+    }
+    return fixedTokens + Math.ceil(characters / 4);
+}
+function safeJson(value) {
+    try {
+        return JSON.stringify(value) ?? String(value);
+    }
+    catch {
+        return String(value);
+    }
+}

package/dist/agent/compaction/formatMessagesForCompaction.d.ts

@@ -0,0 +1,3 @@
+import type { Message } from "../types.js";
+export declare function formatMessagesForCompaction(messages: readonly Message[]): string;
+//# sourceMappingURL=formatMessagesForCompaction.d.ts.map

package/dist/agent/compaction/formatMessagesForCompaction.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"formatMessagesForCompaction.d.ts","sourceRoot":"","sources":["../../../sources/agent/compaction/formatMessagesForCompaction.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AAE3C,wBAAgB,2BAA2B,CAAC,QAAQ,EAAE,SAAS,OAAO,EAAE,GAAG,MAAM,CAqBhF"}

package/dist/agent/compaction/formatMessagesForCompaction.js

@@ -0,0 +1,30 @@
+export function formatMessagesForCompaction(messages) {
+    return messages
+        .map((message) => {
+        const blocks = message.blocks.flatMap((block) => {
+            if (block.type === "text")
+                return [block.text];
+            if (block.type === "image")
+                return ["[Image shared in the conversation]"];
+            if (block.type === "thinking")
+                return [];
+            if (block.type === "tool_call") {
+                return [`[Tool call: ${block.name} ${safeJson(block.arguments)}]`];
+            }
+            const result = block.rendered
+                .map((content) => content.type === "text" ? content.text : "[Image returned by tool]")
+                .join("\n");
+            return [`[Tool result: ${block.toolName}]\n${result}`];
+        });
+        return `<message role="${message.role}">\n${blocks.join("\n")}\n</message>`;
+    })
+        .join("\n\n");
+}
+function safeJson(value) {
+    try {
+        return JSON.stringify(value) ?? String(value);
+    }
+    catch {
+        return String(value);
+    }
+}

package/dist/agent/compaction/requestCompactionSummary.d.ts

@@ -0,0 +1,11 @@
+import type { Message } from "../types.js";
+import type { Model, Provider } from "../../providers/types.js";
+export declare function requestCompactionSummary(options: {
+    provider: Provider;
+    model: Model;
+    messages: readonly Message[];
+    effort?: string;
+    signal?: AbortSignal;
+    now: () => number;
+}): Promise<string>;
+//# sourceMappingURL=requestCompactionSummary.d.ts.map

package/dist/agent/compaction/requestCompactionSummary.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"requestCompactionSummary.d.ts","sourceRoot":"","sources":["../../../sources/agent/compaction/requestCompactionSummary.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AAC3C,OAAO,KAAK,EAAE,KAAK,EAAE,QAAQ,EAAiB,MAAM,0BAA0B,CAAC;AAM/E,wBAAsB,wBAAwB,CAAC,OAAO,EAAE;IACpD,QAAQ,EAAE,QAAQ,CAAC;IACnB,KAAK,EAAE,KAAK,CAAC;IACb,QAAQ,EAAE,SAAS,OAAO,EAAE,CAAC;IAC7B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,GAAG,EAAE,MAAM,MAAM,CAAC;CACrB,GAAG,OAAO,CAAC,MAAM,CAAC,CA4ClB"}