Function createCtxExpandTool

packages/pi-plugin/src/tools/ctx-expand.ts:81–204

(
	deps: CtxExpandToolDeps,
)

}

export function createCtxExpandTool(
	deps: CtxExpandToolDeps,
): ToolDefinition<typeof ParamsSchema> {
	return {
		name: "ctx_expand",
		label: "Magic Context: Expand",
		description: CTX_EXPAND_DESCRIPTION,
		parameters: ParamsSchema,
		async execute(
			_toolCallId,
			params: CtxExpandParams,
			_signal,
			_onUpdate,
			ctx,
		) {
			const sessionId = ctx.sessionManager.getSessionId();
			if (!sessionId) {
				return err("Error: no active Pi session.");
			}

			// All raw reads go through the shared provider-aware helpers, so
			// register Pi's source for the duration of this single call.
			// setRawMessageProvider returns an unregister fn so we don't leak the
			// binding into concurrent transform passes.
			const unregister = setRawMessageProvider(sessionId, {
				readMessages: () => readPiSessionMessages(ctx),
			});

			try {
				// By-ordinal mode: full recovery of a single message from JSONL.
				if (typeof params.message === "number" && params.message >= 1) {
					return ok(renderMessageByOrdinal(sessionId, params.message));
				}

				if (
					typeof params.start !== "number" ||
					typeof params.end !== "number" ||
					params.start < 1 ||
					params.end < params.start
				) {
					return err(
						"Error: provide either message=<ordinal>, or start and end (positive integers, start <= end).",
					);
				}

				// Clamp to the last compartment boundary (parity with OpenCode +
				// ctx_search): messages after it are the live tail already visible
				// to the agent, so re-expanding them wastes output tokens. -1 = no
				// compartments yet → nothing compacted, so don't clamp.
				const lastCompartmentEnd = getLastCompartmentEndMessage(
					deps.db,
					sessionId,
				);
				if (lastCompartmentEnd >= 0 && params.start > lastCompartmentEnd) {
					return ok(
						`Range ${params.start}-${params.end} is entirely within the live tail (after the last compacted message ${lastCompartmentEnd}); those messages are already visible in context.`,
					);
				}